# Get Started
Source: https://auth0.com/docs/get-started

Learn the basics and begin building your authentication solution.

<AuthDocsPipeline />

Welcome to Auth0, an identity platform to manage access to your applications. If you’re new to identity and access management (IAM), learn some of the basics and plan the solution that best fits your technology and needs. If you’re familiar with IAM, you can jump in and start building.

***

## Start Building

##### To get up and running swiftly, choose your application type for a step-by-step quickstart tutorial.

<Card title="Native/Mobile App" href="/docs/quickstart/native">
  Mobile or Desktop app that runs natively on a device

  e.g., iOS, Android
</Card>

<Card title="Single Page App" href="/docs/quickstart/spa">
  JavaScript web app that runs in the browser

  e.g., AngularJS + Node.js, React
</Card>

<Card title="Regular Web App" href="/docs/quickstart/webapp">
  Traditional web app that runs on the server

  e.g., Express.js, ASP.NET
</Card>

<Card title="Backend/API" href="/docs/quickstart/backend">
  An API or service protected by Auth0

  e.g., Express.js API, ASP.NET API
</Card>

<Card title="AI Agent" href="https://auth0.com/ai/docs">
  An AI agent to call external APIs on the user’s behalf and use human-in-the-loop controls

  e.g., LangChain, LlamaIndex
</Card>

***

## Learn the Basics

##### Build your knowledge of IAM technology and Auth0.

<Card title="Identity Fundamentals" href="/docs/get-started/identity-fundamentals">
  Explore topics related to the fundamentals of identity and access management.
</Card>

<Card title="Auth0 Overview" href="/docs/get-started/auth0-overview">
  Discover different use cases. Create and connect the building blocks of your IAM solution.
</Card>

***

## Configure Auth0

##### Define how Auth0 works with your applications and APIs. Control who can access your Auth0 Dashboard.

<Card title="Auth0 Teams" href="/docs/get-started/auth0-teams">
  Learn about Auth0 Teams, including how to enable Teams, view and manage tenants, and manage tenant members.
</Card>

<Card title="Dashboard Profile" href="/docs/get-started/dashboard-profile">
  Describes how to configure options in Auth0 Dashboard's profile section.
</Card>

<Card title="Tenant Settings" href="/docs/get-started/tenant-settings">
  Configure the behavior of your Auth0 tenant.
</Card>

<Card title="Applications in Auth0" href="/docs/get-started/applications">
  Control the details of how Auth0 works with your applications.
</Card>

<Card title="APIs" href="/docs/get-started/apis">
  Manage access for resource requests made to your APIs.
</Card>

<Card title="Manage Dashboard Access" href="/docs/get-started/manage-dashboard-access">
  Administer your team members’ access to your Auth0 Dashboard.
</Card>

***

## Plan and Design

##### Learn about Auth0 flows and architecture so you can make informed decisions about your Auth0 implementation.

<Card title="Authentication and Authorization Flows" href="/docs/get-started/authentication-and-authorization-flow">
  Explore the different flows of information that drive authentication and authorization.
</Card>

<Card title="Architecture Scenarios" href="/docs/get-started/architecture-scenarios">
  Read about real-world customer implementations of Auth0.
</Card>

<Card title="Professional Services" href="/docs/get-started/professional-services">
  Get personalized help deploying and maintaining solutions from Auth0 specialists.
</Card>

***

## Auth0 AI

##### Use the Auth0 AI product suite to learn about Auth0, integrate with AI agents, and improve your tenant’s security posture.

<Card title="Auth0 Guide" href="/docs/get-started/auth0-guide">
  Learn about Auth0 Guide, an AI-powered chatbot that answers your questions about Auth0.
</Card>

<Card title="Auth0 for AI Agents" href="/docs/get-started/auth0-for-ai-agents">
  Learn how to leverage Auth0 for AI Agents to secure every layer of your GenAI stack.
</Card>

<Card title="Auth0 Model Context Protocol (MCP) Server" href="/docs/get-started/auth0-mcp-server">
  Learn how to integrate Auth0 with Model Context Protocol (MCP).
</Card>

<Card title="Build with AI Tools" href="/docs/get-started/build-with-ai-tools">
  Learn how to use AI tools to search and index the Auth0 knowledge base.
</Card>


# APIs
Source: https://auth0.com/docs/get-started/apis

Explore key topics related to working with APIs.

An API is an entity that represents an external resource, capable of accepting and responding to protected resource requests made by applications. In the [OAuth2 specification](https://tools.ietf.org/html/rfc6749), an API maps to the **<Tooltip href="/docs/glossary?term=Resource+Server">Resource Server</Tooltip>**.

At some point, your custom APIs will need to allow limited access to their protected resources on behalf of users. Authorization refers to the process of verifying what a user has access to. While often used interchangeably with [authentication](/docs/authenticate), authorization represents a fundamentally different function. To learn more, read [Authentication and Authorization](/docs/get-started/identity-fundamentals/authentication-and-authorization).

In authorization, a user or application is granted access to an API after the API determines the extent of the permissions that it should assign. Usually, authorization occurs after identity is successfully validated through authentication so that the API has some idea of what sort of access it should grant.

Authorization can be determined through the use of [policies](/docs/manage-users/access-control/authorization-policies) and [rules](/docs/manage-users/access-control/rules-for-authorization-policies), which can be used with [role-based access control (RBAC)](/docs/manage-users/access-control/rbac). Regardless of whether RBAC is used, requested access is transmitted to the API via scopes and granted access is returned in issued <Tooltip href="/docs/glossary?term=Access+Tokens">Access Tokens</Tooltip>.

The application can then use the Access Token to access the API's protected resources. The same Access Token can be used to access the API's resources without having to authenticate again until it expires.

## API permissions

Since only the API can know all of the possible actions that it can handle, it should have its own internal access control system in which it defines its own permissions. To determine a calling application's effective permissions, an API should combine incoming scopes with the permissions assigned within its own internal access control system and make access control decisions accordingly.

## Configure an API

To protect an API, you must register an API using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. To learn more, see [Register APIs](/docs/get-started/auth0-overview/set-up-apis).

<Callout icon="file-lines">
  Before you register any APIs in the Auth0 Dashboard, one API will already exist: the **Auth0 Management API**. To learn more about the features of the Management API and its available endpoints, see [Management API](https://auth0.com/docs/api/management/v2).
</Callout>

## Learn more

* [API Scopes](/docs/get-started/apis/scopes/api-scopes)
* [Which OAuth 2.0 Flow Should I Use?](/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use)
* [Tokens](/docs/secure/tokens)
* [Register APIs](/docs/get-started/auth0-overview/set-up-apis)
* [API Settings](/docs/get-started/apis/api-settings)


# Add API Permissions
Source: https://auth0.com/docs/get-started/apis/add-api-permissions

Learn how to add permissions to APIs using the Auth Dashboard or the Management API.

You can add permissions to an API using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

<Warning>
  By default, any user of any application can ask for any permission defined here. You can implement access policies to limit this behavior via [rules](/docs/customize/rules).
</Warning>

## Use the Dashboard

1. Go to [Dashboard > Applications > APIs](https://manage.auth0.com/#/apis) and click the name of the API to view.

   <Frame>
     <img alt="Dashboard Applications APIs List" />
   </Frame>
2. Go to the **Permissions** tab and enter a permission name and description for the permission you want to add. Be sure not to use any reserved permission names (see Reserved names section).

   <Frame>
     <img alt="Dashboard Add API Permissions API Define Permissions Screen" />
   </Frame>
3. Click **Add**. Remember that individual Applications may need permissions and/or scopes updated to interact properly with the API.

## Use the Management API

<Callout icon="file-lines">
  Patching the permissions with an empty object removes the permissions completely.
</Callout>

Make a `PATCH` call to the [Update Resource Server endpoint](https://auth0.com/docs/api/management/v2/resource-servers/patch-resource-servers-by-id). Be sure to replace `API_ID`, `MGMT_API_ACCESS_TOKEN`, `PERMISSION_NAME`, and `PERMISSION_DESC` placeholder values with your API ID, Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, permission name(s), and permission description(s), respectively. Be sure not to use any reserved permission names (see Reserved names section).

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/resource-servers/API_ID' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "scopes": [ { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" }, { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" } ] }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/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", "{ "scopes": [ { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" }, { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" } ] }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/resource-servers/API_ID"

  	payload := strings.NewReader("{ "scopes": [ { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" }, { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" } ] }")

  	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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/resource-servers/API_ID")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "scopes": [ { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" }, { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" } ] }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/resource-servers/API_ID',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: {
      scopes: [
        {value: 'PERMISSION_NAME', description: 'PERMISSION_DESC'},
        {value: 'PERMISSION_NAME', description: 'PERMISSION_DESC'}
      ]
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"scopes": @[ @{ @"value": @"PERMISSION_NAME", @"description": @"PERMISSION_DESC" }, @{ @"value": @"PERMISSION_NAME", @"description": @"PERMISSION_DESC" } ] };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/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 => "{ "scopes": [ { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" }, { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" } ] }",
    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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "scopes": [ { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" }, { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" } ] }"

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

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

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/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 = "{ "scopes": [ { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" }, { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" } ] }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = ["scopes": [
      [
        "value": "PERMISSION_NAME",
        "description": "PERMISSION_DESC"
      ],
      [
        "value": "PERMISSION_NAME",
        "description": "PERMISSION_DESC"
      ]
    ]] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/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()
  ```
</AuthCodeGroup>

<Callout icon="file-lines">
  When adding or updating scopes, Management API requires that you pass all scopes you would to include. If any of the existing scopes are not passed, they will be removed.
</Callout>

<table>
  <thead>
    <tr>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>API\_ID</code></td>
      <td>ID of the API for which you want to delete permissions.</td>
    </tr>

    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td><a href="https://auth0.com/docs/api/management/v2/tokens">Access Token for the Management API</a> with the scope <code>update:resource\_servers</code>.</td>
    </tr>

    <tr>
      <td><code>PERMISSION\_NAME</code></td>
      <td>Name(s) of the permission(s) you want to keep for the specified API.</td>
    </tr>

    <tr>
      <td><code>PERMISSION\_DESC</code></td>
      <td>User-friendly description(s) of the permission(s) you want to keep for the specified API.</td>
    </tr>
  </tbody>
</table>

## Reserved names

The following permission names are reserved and cannot be set as custom API permissions:

* address
* created\_at
* email
* email\_verified
* family\_name
* given\_name
* identities
* name
* nickname
* offline\_access
* <Tooltip href="/docs/glossary?term=openid">openid</Tooltip>
* phone
* picture
* profile

## Learn more

* [Customize Consent Prompts](/docs/customize/login-pages/customize-consent-prompts)
* [Configure Logical API for Multiple APIs](/docs/get-started/apis/set-logical-api)
* [Role-Based Access Control](/docs/manage-users/access-control/rbac)
* [Enable Role-Based Access Control for APIs](/docs/get-started/apis/enable-role-based-access-control-for-apis)
* [Check API Calls](/docs/troubleshoot/authentication-issues/check-api-calls)


# API Access Policies for Applications
Source: https://auth0.com/docs/get-started/apis/api-access-policies-for-applications

Learn how to configure API Access Policies for Applications.

API Access Policies for Applications enables you to control how applications access your APIs registered in Auth0. These policies define how applications interact with an API, such as whether they can successfully obtain an access token to access the API’s resources.

You can configure the application API access policy for each API registered in the Auth0 Dashboard. To learn more, read [Configure API application access policy](#configure-api-application-access-policy).

## User access vs. client access

You can configure separate application API access policies for user access and client (machine-to-machine) access:

* **Client access**: used for machine-to-machine access, which corresponds to the [Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow).
* **User access**: used for all access flows that generate an access token associated with an end-user, allowing the application to access an API on the user’s behalf. User access flows do not include the Client Credentials Flow. To learn more about user access flows, read [Authentication and Authorization Flows](/docs/get-started/authentication-and-authorization-flow).

## Application API access policies

The application API access policies are:

<table>
  <thead>
    <tr>
      <th><strong>Policy</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Access Flow</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>Allow</code></td>
      <td>When configured for an API, any application in your tenant can get an access token to the API. No specific grant is required.</td>
      <td>The default for user access when you create an API. You can only configure `allow_all` for user access.</td>
    </tr>

    <tr>
      <td><code>Allow via client-grant</code></td>
      <td>When configured for an API, only applications with a client grant defined can get an access token for the API. The client grant establishes the maximum permissions an application can request from the API. To learn more about how to create and manage client grants, read <a href="/docs/get-started/applications/application-access-to-apis-client-grants">Application Access to APIs: Client Grants</a>.</td>
      <td>The default for the Client Credentials Flow when you create an API.</td>
    </tr>

    <tr>
      <td><code>Deny</code></td>
      <td>When configured for an API, no application can get an access token to the API, regardless of any other settings or grants. Access is completely restricted.</td>
      <td>You can configure <code>deny\_all</code> for both user and client access.</td>
    </tr>
  </tbody>
</table>

When configuring an API’s application access policy, Auth0 recommends using `Allow via client-grant`, which follows a least privilege principle approach. To learn more, read [Application Access to APIs: Client Grants](/docs/get-started/applications/application-access-to-apis-client-grants).

When you set the application access policy for an API to `Allow via client-grant`, you must explicitly provide the required scopes as part of the token request. This does not apply to refresh token requests, where if you omit the scopes, the authorization server assumes the application wants all the scopes it was granted in the original access token. As a result, the authorization server returns an access token with the same scopes originally granted by the resource owner.

## Configure API application access policy

You can configure an API’s application access policy using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

### Auth0 Dashboard

To configure an API’s application access policy:

1. Navigate to [Dashboard >  Applications > APIs](https://manage.auth0.com/#/apis) and select your API.
2. Select the **Application Access** tab.
3. Select the **Application Access Policy** to configure the **user** and **client** access.
   * Configure the **user access** policy to **Allow**, **Allow via client-grant**, or **Deny**.
     * **Allow**: Applications are allowed to access the API on the user’s behalf.
     * **Allow via client-grant**: Applications must have a client grant to access the API on the user’s behalf.
     * **Deny**: Applications are denied access to the API on the user’s behalf.
   * Configure the **client access** policy to **Allow via client-grant** or **Deny**.
     * **Allow via client-grant**: Machine-to-machine applications are allowed to access  this API as long as they have the corresponding client grant.
     * **Deny**: Restricts machine-to-machine access to this API.
4. Select **Save** to save the **Application Access Policy**.
5. When **Allow via client-grant** is the policy configured for the API, select **Edit** to authorize **User Access**, **Client Access**, or both for each individual Application.
   * Configure the **User Access Authorization** to **Unauthorized**, **Authorized**, or **All**.
     * **Unauthorized**: No permission allowed.
     * **Authorized**:  Select desired permissions.
     * **All**: Include all existing and future permissions.
   * Configure the **Client Credential Access Authorization** to **Unauthorized**, **Authorized**, or **All**.
     * **Unauthorized**: No permission allowed.
     * **Authorized**:  Select desired permissions.
     * **All**: Include all existing and future permissions.
6. Select **Save** to save the **Application Access** settings.

### Auth0 Management API

You can configure an API’s application access policy by updating its `subject_type_authorization` property on the `resource-servers` collection of the [Management API](/docs/api/management/v2/resource-servers/patch-resource-servers-by-id).

The `subject_type_authorization` object contains two nested objects, `user` and `client`, each with a policy attribute that you can set to one of the three access policies defined in [Application API access policies](#application-api-access-policies).

#### Existing API

To configure the application access policy for an existing API, make a `PATCH` request to the `/resource-servers/{id}` endpoint and pass a `subject_type_authorization` object that specifies the policies for both user and client access types.

The following code sample demonstrates how to set different access policies for user and client access types for an existing API:

* The user policy is set to `require_client_grant`, meaning applications must have a client grant to access the API on the user’s behalf.
* The client policy is set to `deny_all`, which restricts machine-to-machine access to this API.

<AuthCodeBlock />

#### New API

To configure the application access policy when creating a new API, make a `POST` request to the `/resource-servers` endpoint and pass a `subject_type_authorization` object that specifies the policies for both user and client access types.

The following code sample demonstrates how to set different access policies for user and client access types when creating a new API:

* The user policy is set to `require_client_grant`, meaning applications must have a client grant to access the API on the user’s behalf.
* The client policy is set to `deny_all`, which restricts machine-to-machine access to this API.

<AuthCodeBlock />

## Learn more

* [Application Access to APIs: Client Grants](/docs/get-started/applications/application-access-to-apis-client-grants)


# API Settings
Source: https://auth0.com/docs/get-started/apis/api-settings

Describes the settings related to APIs available in the Auth0 Dashboard.

Use the **Settings** tab in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> at [Dashboard > Applications > APIs](https://manage.auth0.com/#/apis) to configure registered APIs that you can consume from your authorized applications. To configure an API's settings, click **...** next to an API in the list and select **Settings** or click the API name. To learn how to create and register an API, read [Register APIs](/docs/get-started/auth0-overview/set-up-apis).

<Frame>
  <img alt="Dashboard Applications APIs List" />
</Frame>

## Settings

Use the settings on this tab to configure token expiration, role-based access control (RBAC), and other access settings. Click **Save** at the bottom of the tab to save changes.

### General Settings

These fields were set when you initially registered the API, except in the case of the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. You can only modify the **Name**.

<Frame>
  <img alt="Dashboard Applications APIs Settings Tab General Settings" />
</Frame>

* **Id**: A unique alphanumeric string generated by Auth0. This information is read-only, and you will only need it if you will be working directly with [Auth0's Management API Resource Servers endpoints](https://auth0.com/docs/api/management/v2#!/Resource_Servers/get_resource_servers_by_id).
* **Name**: A friendly name for the API. Does not affect any functionality. The following characters are not allowed: `< >`.
* **Identifier**: A unique identifier for your API. This value is set upon API creation and cannot be modified afterward. We recommend using a URL, but this doesn't have to be a publicly available URL; Auth0 will not call your API at all.

### Token Settings

<Frame>
  <img alt="Dashboard - API - Token Settings - Expiration" />
</Frame>

* **Maximum <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> Lifetime (Seconds)**: The amount of time (in seconds) before an access token expires. The default value is 86400 seconds (24 hours). The maximum value you can set is 2592000 seconds (30 days).
* **Implicit / Hybrid Flow Access Token Lifetime (Seconds)**: The amount of time (in seconds) before an access token issued using an implicit or hybrid flow expires. The default value is 86400 seconds (24 hours). The value cannot exceed the maximum access token lifetime.
* **<Tooltip href="/docs/glossary?term=JSON+Web+Token">JSON Web Token</Tooltip> (JWT) Profile**: The profile determines the format of the access tokens issued for the API. The available values are `Auth0` and `RFC 9068`. To learn more, read [Access Token Profiles](/docs/secure/tokens/access-tokens/access-token-profiles).
* **JSON Web Token (JWT) <Tooltip href="/docs/glossary?term=Signing+Algorithm">Signing Algorithm</Tooltip>**: The algorithm with which to sign the tokens. The signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn't changed along the way. The available values are [`HS256`](https://en.wikipedia.org/wiki/Symmetric-key_algorithm) and [`RS256`](https://en.wikipedia.org/wiki/Public-key_cryptography). If you select `RS256` (recommended), the token will be signed with your tenant's private key. This value is set when your API is created and cannot be modified afterward. To learn more about signing algorithms and how they work in Auth0, read [Signing Algorithms](/docs/get-started/applications/signing-algorithms).

  <Callout icon="file-lines">
    The signature is part of a JWT. If you are unfamiliar with JWT structure, please see [JSON Web Token Structure](/docs/secure/tokens/json-web-tokens/json-web-token-structure).
  </Callout>
* **JSON Web Encryption (JWE):** When enabled, issued access tokens are encrypted using JSON Web Encryption (JWE). format. To learn more, read [JSON Web Encryption](/docs/secure/tokens/access-tokens/json-web-encryption).

### RBAC Settings

<Frame>
  <img alt="Auth0 Dashboard API Settings RBAC toggle" />
</Frame>

* **Enable RBAC**: Enable this setting for RBAC policies to be enforced for the API. To learn more, read [Role-Based Access Control](/docs/manage-users/access-control/rbac) and [Enable Role-Based Access Control for APIs](/docs/get-started/apis/enable-role-based-access-control-for-apis). For troubleshooting help, review [Troubleshoot Role-Based Access Control and Authorization](/docs/troubleshoot/authentication-issues/troubleshoot-rbac-authorization).
* **Add Permissions in the Access Token**: Enable this setting to add the Permissions claim to the access token. This setting is only available if you enable RBAC. You can configure permissions on the **Permissions** tab.

### Access Settings

<Frame>
  <img alt="Dashboard Applications APIs Settings Tab Access Settings" />
</Frame>

* **Allow Skipping User Consent**: Enable this setting for the API to skip user consent for applications flagged as "first party."
* **Allow Offline Access**: Enable this setting to allow applications to ask for <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip> for the API.

## Permissions

Use the settings on the **Permissions** tab to define the permissions (scopes) that the API will use. To learn more, read [Add API Permissions](/docs/get-started/apis/add-api-permissions) and [Delete API Permissions](/docs/get-started/apis/delete-api-permissions).

<Frame>
  <img alt="Dashboard Add API Permissions API Define Permissions Screen" />
</Frame>

## Machine-to-Machine Applications

If you have machine-to-machine applications, they will appear in a list on this tab. Use the toggles to authorize applications in the list. To learn more, read [Register Machine-to-Machine Applications](/docs/get-started/auth0-overview/create-applications/machine-to-machine-apps).

<Frame>
  <img alt="Dashboard Applications API Machine-to-Machine Applications" />
</Frame>

## Test

A test application is automatically created by Auth0 to allow to tests with the API. To learn how to create more test machine-to-machine applications for Management API testing, read [Create Machine-to-Machine Applications for Testing](/docs/get-started/apis/create-m2m-app-test).

<Frame>
  <img alt="Dashboard Applications APIs Test Tab" />
</Frame>

## Management API Explorer

If you view the **Settings** for the Auth0 Management API, you will see an additional tab called **API Explorer**.

<Frame>
  <img alt="Dashboard Applications APIs Management API Explorer" />
</Frame>

For troubleshooting help, review [Check API Calls](/docs/troubleshoot/authentication-issues/check-api-calls).

## Learn more

* [Register APIs](/docs/get-started/auth0-overview/set-up-apis)
* [Tokens](/docs/secure/tokens)
* [Signing Algorithms](/docs/get-started/applications/signing-algorithms)
* [API Scopes](/docs/get-started/apis/scopes/api-scopes)
* [Configure Logical API for Multiple APIs](/docs/get-started/apis/set-logical-api)
* [Create Machine-to-Machine Applications for Testing](/docs/get-started/apis/create-m2m-app-test)


# Configure Access Token Profile
Source: https://auth0.com/docs/get-started/apis/configure-access-token-profile

Learn how to configure an access token profile for your API.

You can choose which <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> profile to use for your APIs: the Auth0 token profile or the RFC 9068 token profile. The access token profile you configure determines the format of the access tokens issued for the API.

By default, Auth0 issues access tokens using the Auth0 token profile. The Auth0 token profile issues access tokens that are formatted as [JSON Web Tokens (JWTs)](/docs/secure/tokens/json-web-tokens), which contain information about an entity in the form of claims.

Auth0 also supports the RFC 9068 token profile. The RFC 9068 token profile issues access tokens formatted as <Tooltip href="/docs/glossary?term=JWTs">JWTs</Tooltip> following the [IETF JWT Profile for OAuth 2.0 Access Tokens (RFC 9068)](https://datatracker.ietf.org/doc/html/rfc9068). To learn more about the differences between these token profiles, read [Access Token Profiles](/docs/secure/tokens/access-tokens/access-token-profiles).

When you [register an API](/docs/get-started/auth0-overview/set-up-apis), you can select the access token profile in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. After you’ve registered the API, you can configure the access token profile anytime using the [Management API](https://auth0.com/docs/api/management/v2) and the [Auth0 Dashboard](https://manage.auth0.com/).

## Configure access token profile for an API

<Tabs>
  <Tab title="Auth0 Dashboard">
    1. Go to [Dashboard > Applications > APIs](https://manage.auth0.com/#/apis) and click the name of the API to view.

    2. Scroll to **Access Token Settings** and select the access token profile under **JSON Web Token (JWT) Profile**. The selected profile determines the format and claims of access tokens issued for the API. The supported values are `Auth0` and `RFC 9068`. To read more about the difference between the two profiles, read [Access Token Profiles](/docs/secure/tokens/access-tokens/access-token-profiles).

    3. Click **Save**.
  </Tab>

  <Tab title="Management API">
    When using the Management API, we refer to access token profiles as token dialects. To configure your access token profile, set the `token_dialect` parameter for an API using the Management API.

    The following code sample makes a PATCH request to the [Update a resource server endpoint](https://auth0.com/docs/api/management/v2/resource-servers/patch-resource-servers-by-id):

    <AuthCodeBlock />

    Replace the `API_ID`, `MGMT_API_ACCESS_TOKEN`, and `TOKEN_DIALECT` with their respective values, as described in the following table:

    <table>
      <thead>
        <tr>
          <th>Parameter</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>API\_ID</code></td>
          <td>ID of the API for which you want to update the token dialect.</td>
        </tr>

        <tr>
          <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
          <td><a href="https://auth0.com/docs/api/management/v2/tokens">Access Token for the Management API</a> with the scope <code>update:resource\_servers</code>.</td>
        </tr>

        <tr>
          <td><code>TOKEN\_DIALECT</code></td>
          <td>Dialect of the access token for the specified API. To learn more, read <a href="#token-dialect-options">Token dialect options</a>.</td>
        </tr>
      </tbody>
    </table>

    #### Token dialect options

    Auth0 supports the following token dialects:

    <table>
      <thead>
        <tr>
          <th>Value</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>access\_token</code></td>
          <td>The default Auth0 token profile generates an access token formatted as a JSON Web Token (JWT). To learn more, read <a href="/docs/secure/tokens/access-tokens/access-token-profiles">Access Token Profiles</a>.</td>
        </tr>

        <tr>
          <td><code>access\_token\_authz</code></td>
          <td>The default Auth0 token profile (<code>access\_token</code>) with the <code>permissions</code> claim. To learn more about RBAC permissions, read <a href="/docs/get-started/apis/enable-role-based-access-control-for-apis">Enable Role-Based Access Control for APIs</a>.</td>
        </tr>

        <tr>
          <td><code>rfc9068\_profile</code></td>
          <td>The RFC 9068 token profile generates an access token formatted as a JWT following the <a href="https://datatracker.ietf.org/doc/html/rfc9068">IETF JWT Profile for OAuth 2.0 Access Tokens (RFC 9068)</a>. To learn more, read <a href="/docs/secure/tokens/access-tokens/access-token-profiles">Access Token Profiles</a>.</td>
        </tr>

        <tr>
          <td><code>rfc9068\_profile\_authz</code></td>
          <td>The RFC 9068 profile (<code>rfc9068\_profile</code>) with the <code>permissions</code> claim. To learn more about RBAC permissions, read <a href="/docs/get-started/apis/enable-role-based-access-control-for-apis">Enable Role-Based Access Control for APIs</a>.</td>
        </tr>
      </tbody>
    </table>
  </Tab>
</Tabs>


# Configure JSON Web Encryption (JWE)
Source: https://auth0.com/docs/get-started/apis/configure-json-web-encryption

Learn how to configure JSON Web Encryption (JWE) for an API.

<Callout icon="file-lines">
  To use Highly Regulated Identity features, you must have an Enterprise Plan with the Highly Regulated Identity add-on. Refer to [Auth0 Pricing](https://auth0.com/pricing/) for details.
</Callout>

By default, Auth0 issues <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> that are formatted as a signed [JSON Web Token (JWT)](/docs/secure/tokens/json-web-tokens), meaning that while they are integrity protected, clients and other intermediaries can still inspect them. This can lead to a loss of information privacy on data intended only to be exposed to a <Tooltip href="/docs/glossary?term=resource+server">resource server</Tooltip>.

To prevent unauthorized inspection of access tokens, Auth0 supports the use of nested <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> access tokens, where access information is signed in a JWT and then encrypted and represented with JSON Web Encryption (JWE). Resource servers are expected to both decrypt these access tokens and verify the signature of the JWT payload while the information is opaque to any other parties.

## Generate RSA key pair

Before configuring an API to use JWE, you must [generate an RSA key pair](/docs/secure/application-credentials/generate-rsa-key-pair).

The private key must be kept secret. Upload the public key to Auth0 encoded in PEM format as described in [Generate RSA Key Pair](/docs/secure/application-credentials/generate-rsa-key-pair). Only the resource server or API server can securely access the private key to decrypt the access token.

## Configure JWE for an API

<Tabs>
  <Tab title="Auth0 Dashboard">
    Use the [Auth0 Dashboard](https://manage.auth0.com/) to configure JWE for your API. To begin, enable the **JSON Web Encryption (JWE)** toggle under **Token Settings** for your API.

    <Frame>
      <img alt="" />
    </Frame>

    When prompted, add a JSON Web Encryption (JWE) key:

    * Enter a friendly name for easy identification.
    * Upload a certificate with the public key encoded in PEM format.
    * Select the encryption algorithm.
    * (Optional) Enter a key identifier.

    Click **Add** to save the JWE key, which will generate a thumbprint of the certificate.
  </Tab>

  <Tab title="Management API">
    Use the [Auth0 Management API](https://auth0.com/docs/api/management/v2) to configure JWE for a resource server or API server. You must configure JWE for each API, so each API has its own public encryption key.

    The following POST request configures a new API to receive encrypted access tokens:

    ```bash lines theme={null}
    curl -X POST --location "https://{domain}/api/v2/resource-servers" \
        -H "Authorization: Bearer {managementAccessToken}" \
        -H "Content-Type: application/json" \
        --data-raw '{
      "name": "{apiName}",
      "identifier": "{apiIdentifier}",
      "token_encryption": {
        "format": "compact-nested-jwe",
        "encryption_key":
        {
          "name": "{credentialName}",
          "pem": "{pem}",
          "alg": "{alg}",
          "kid": "{kid}"
        }
      }
    }'
    ```

    The following table explains what the different parameters mean:

    <table>
      <thead>
        <tr>
          <th><strong>Parameter</strong></th>
          <th><strong>Required?</strong></th>
          <th><strong>Description</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>apiName</code></td>
          <td>Required</td>
          <td>The name of your new API.</td>
        </tr>

        <tr>
          <td><code>apiIdentifier</code></td>
          <td>Required</td>
          <td>The unique identifier for your API. This will be used as your token audience.</td>
        </tr>

        <tr>
          <td><code>credentialName</code></td>
          <td>Optional</td>
          <td>The name for your public key.</td>
        </tr>

        <tr>
          <td><code>pem</code></td>
          <td>Required</td>
          <td>Public key encoded in PEM format.</td>
        </tr>

        <tr>
          <td><code>alg</code></td>
          <td>Required</td>
          <td>The encryption algorithm must be either <code>RSA-OAEP-256</code>, <code>RSA-OAEP-384</code>, or <code>RSA-OAEP-512</code>.</td>
        </tr>

        <tr>
          <td><code>kid</code></td>
          <td>Optional</td>
          <td>The identifier used to write to the <code>kid</code> header in your JWE token. This can be used to identify the key used for encryption during key rotation.</td>
        </tr>
      </tbody>
    </table>

    The response contains the `id` property which uniquely identifies the resource server. The response also contains a generated `thumbprint_sha256` field that can be used to identify the credential. Auth0 will not return key material after initial creation (in this case, your PEM).

    There are many ways to generate the `thumbprint_sha256`. For more information, see the [RFC 8705 OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens](https://datatracker.ietf.org/doc/html/rfc8705#name-jwt-certificate-thumbprint-).

    To ensure that you generated the correct `thumbprint_sha256`, you can use the following Node.js code sample to extract the thumbprint:

    ```javascript lines theme={null}
    const fs = require('fs');
    const crypto = require('crypto');

    const { calculateJwkThumbprint, exportJWK } = require('jose');

    const publicKeyObject = crypto.createPublicKey(fs.readFileSync('./my_cert.pem'));
    exportJWK(publicKeyObject).then((jwk) => {
      calculateJwkThumbprint(jwk, 'sha256').then((thumbprint) => {
        console.log(thumbprint);
      });
    });
    ```
  </Tab>
</Tabs>

## Learn more

* [JSON Web Encryption](/docs/secure/tokens/access-tokens/json-web-encryption)


# Configure Rich Authorization Requests (RAR)
Source: https://auth0.com/docs/get-started/apis/configure-rich-authorization-requests

Learn how to configure Rich Authorization Requests (RAR) for a resource server.

Using [Rich Authorization Requests (RAR)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-rar), clients can request and obtain <Tooltip href="/docs/glossary?term=fine-grained+authorization">fine-grained authorization</Tooltip> data from <Tooltip href="/docs/glossary?term=resource+owners">resource owners</Tooltip>, such as end users, during the [Authorization Code Flow with Pushed Authorization Requests (PAR)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-par) and [Client-Initiated Backchannel Authentication Flow](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow).

Rich Authorization Requests use the `authorization_details` parameter. This parameter accepts a JSON array of objects which may include detailed information about the authorization being requested, such as the specific resources or actions the client wants to access on behalf of the user.

You can render the requested `authorization_details` to the user using either:

* The browser, by using a [customized consent prompt](#set-customized-consent-prompt)
* A mobile application when using push notifications with the [Auth0 Guardian SDK or Auth0 Guardian app](/docs/secure/multi-factor-authentication/auth0-guardian)

To configure Rich Authorization Requests for a <Tooltip href="/docs/glossary?term=resource+server">resource server</Tooltip>, you must:

1. [Register `authorization_details` types](#register-authorization_details-types) for the resource server.
2. [Configure the API Access policies](#configure-the-api-access-policies) to allow your app to request those types.
3. [Set the customized consent prompt](#set-customized-consent-prompt) to render the `authorization_details`.
4. [Optional: Configure the consent policy for the resource server](#optional-configure-consent-policy-for-the-resource-server).

## Register `authorization_details` types

Each object in the JSON array must have a `type` field, which describes the shape of the object. An `authorization_details` array may contain multiple entries of the same `type`.

### Auth0 Guardian app

If you’re using the Auth0 Guardian app, then the `authorization_details` parameter value must have only one object in the array, and that object must conform to the following Auth0 schema:

<table>
  <thead>
    <tr>
      <th><strong>Field</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Example</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>type</code></td>
      <td>Specifies the type of authorization request:<br /><ul><li><code>urn:auth0:schemas:authorization-details</code>: The Auth0 URN indicates that the request will use the Auth0 schema.</li><li><code>v1</code>: The schema version.</li><li><code>user-profile</code>: Customer-provided value indicating that the request is for user profile information.</li></ul></td>
      <td><code>urn:auth0:schemas:authorization-details:v1:user-profile</code></td>
    </tr>

    <tr>
      <td><code>instruction</code></td>
      <td>A human-readable message to the user approving the request.</td>
      <td><code>Please approve the request.</code></td>
    </tr>

    <tr>
      <td><code>properties</code></td>
      <td>A JSON object containing the specific user attributes or claims being requested. Each key (e.g., <code>email</code>, <code>full\_name</code>) represents a particular user profile field:<br /><ul><li><code>display</code>: A boolean value that determines whether the property should be shown to the user in the consent dialog. If <code>true</code>, it will be displayed; if <code>false</code>, it's an internal-only property not meant for user view.</li><li><code>name</code>: The human-readable name for the property (e.g., "Email Address").</li><li><code>display\_order</code>: An integer that dictates the order in which properties will be shown in the consent dialog.</li><li><code>description</code>: An optional, short explanation of the property's purpose.</li><li>`value`: The actual data value for the property (e.g., "[user@example.com](mailto:user@example.com)", "John Doe"). The data type can vary (string, integer, boolean, etc.).</li></ul></td>
      <td>`"properties": { "stringPropertyForDisplay": { "display": true, "name": "A String:", "display_order": "1", "value": "Value 1"} }`</td>
    </tr>
  </tbody>
</table>

The following is an example `authorization_details` type with the Auth0 schema:

```json lines theme={null}
{
    "type": "urn:auth0:schemas:authorization-details:v1:user-profile",
    "instruction": "An instruction to the user",
    "properties": {
        "stringPropertyForDisplay": {
            "display": true,
            "name": "A String:",
            "display_order": 1,
            "value": "Value 1"
        },
        "numericPropertyForDisplay": {
            "display": true,
            "name": "A Number:",
            "display_order": 2,
            "description": "An optional description",
            "value": 100.00
        },
        "booleanPropertyForDisplay": {
            "display": true,
            "name": "A Boolean:",
            "display_order": 3,
            "value": true
        },
        "hiddenProperty": {
            "display": false,
            "value": "This value should not be displayed"
        }
    }
}
```

### Other notification channels

The `authorization_details` type does not need to use the Auth0 schema if you aren't using the Auth0 Guardian app. If you are displaying the `authorization_details` using a customized consent prompt or your own custom mobile app with the Auth0 Guardian SDK, then the following requirements apply:

* Maximum 5Kb
* Must be valid JSON
* Must be an array of objects
* Maximum of 5 entries in the array
* Every object must have a `type` property (that is pre-registered on the API)
* Maximum of 10 properties per object
* Maximum character length of property names is 255
* Maximum character length of property value is 255
* Maximum of 5 levels of nested objects
* Property names can only contain the following characters: `a-zA-Z0-9_.-`

The following is an example `authorization_details` of type `money_transfer` that does not use the Auth0 schema. It contains the following object fields:

* `instructedAmount`: The amount of money in USD to be transferred.
* `sourceAccount`: The source bank account from which the money will be transferred.
* `destinationAccount`: The destination bank account to which the money will be transferred.
* `beneficiary`: The recipient of the money transfer.
* `subject`: The subject line of the money transfer.

```json lines theme={null}
{
  "type": "money_transfer", 
  "instructedAmount": {"amount": 2500, "currency": "USD"},   
  "sourceAccount": "xxxxxxxxxxx1234", 
  "destinationAccount": "xxxxxxxxxxx9876", 
  "beneficiary": "Hanna Herwitz", 
  "subject": "A Lannister Always Pays His Debts"
}
```

You must register `authorization_details` types for a resource server, which is similar to registering allowed scopes. You can register `authorization_details` types with the [Auth0 Dashboard](https://manage.auth0.com/) or [Management API](https://auth0.com/docs/api/management/v2).

<Tabs>
  <Tab title="Auth0 Dashboard">
    To add `authorization_details` in the Auth0 Dashboard:

    1. Navigate to [Auth0 Dashboard > Applications > APIs](https://manage.auth0.com/#/apis).
    2. Select the **Permissions** tab.
    3. Under **Add an Authorization Details type**, you can add multiple `authorization_details` types for your resource server. Enter an `authorization_details` type
    4. Select the **+Add** option.

    You can see the `authorization_details` types for your resource server under **List of Authorization Details Types**:

    <Frame>
      <img alt="" />
    </Frame>
  </Tab>

  <Tab title="Management API">
    To register  `authorization_details` types with an existing resource server, make a `PATCH` request to the [Update a resource server](https://auth0.com/docs/api/management/v2/resource-servers/patch-resource-servers-by-id) endpoint.

    The following code sample adds the `payment_initiation` and `money_transfer` types under `authorization_details` for a resource server:

    ```bash lines theme={null}
    curl --location --request PATCH 'https://$tenant/api/v2/resource-servers/$resource-server-id' \
      --header 'Authorization: Bearer $management_access_token' \
      --header 'Content-Type: application/json' \
      --data-raw '{
      "authorization_details": [{"type": "payment_initiation"}, {"type": "money_transfer"}]
      }'
    ```

    To create a new resource server with a registered `authorization_details` type, make a `POST` request to the `/resource-servers` endpoint.

    The following `POST` request creates a new resource server with `authorization_details` type `payment_initiation`:

    ```bash lines theme={null}
    curl --location --request POST 'https://$tenant/api/v2/resource-servers' \
      --header 'Authorization: Bearer $management_access_token' \
      --header 'Content-Type: application/json' \
      --data-raw '{
      "name": "Payments API",
      "identifier": "https://payments.api/",
      "authorization_details": [{"type": "payment_initiation"}]
      }'
    ```
  </Tab>
</Tabs>

## Configure the API Access policies

[API Access Policies for Applications](/docs/get-started/apis/api-access-policies-for-applications) control what applications can access your APIs and what scopes or `authorization_details` types they are allowed to access.

You can check your API's current policy using the Management API. Make a `GET` request to the [Get a resource server](https://auth0.com/docs/api/management/v2/resource-servers/get-resource-servers-by-id) endpoint and check the `subject_type_authorization` property in the response:

```bash lines theme={null}
curl --location --request GET 'https://$tenant/api/v2/resource-servers/$resource-server-id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json'
```

The `subject_type_authorization` property has values for `client.policy` and `user.policy`:

* If the policy value is `allow_all`, then applications or users can request all `authorization_details` types registered for the API.
* If the policy value is `require_client_grant`, then each type of `authorization_details` must be explicitly allowed by the client grant for that application.
* If the policy value is `deny_all`, then no application or user can request any of the `authorization_details` types registered for the API.

To learn more on how to manage client grants for applications, read [Application Access to APIs: Client Grants](/docs/get-started/applications/application-access-to-apis-client-grants) .

## Set customized consent prompt

You can render the `authorization_details` of a Rich Authorization Request in the consent prompt. To do so, configure the `customized-consent` prompt with the appropriate template partials.

You can set the customized consent prompt using the Auth0 CLI or Management API.

### Auth0 CLI

To configure the customized consent partials, run the `auth0 ul customize` command with the appropriate flags in your terminal:

```bash lines theme={null}
auth0 ul customize
```

To learn more, read the [auth0 universal-login customize documentation](https://auth0.github.io/auth0-cli/auth0_universal-login_customize.html).

### Management API

To configure the customized consent partials, make a `PUT` request to the `/prompts/customized-consent/partials` endpoint:

```bash lines theme={null}
curl --location --request PUT "https://$tenant/api/v2/prompts/customized-consent/partials" \
  --header "Authorization: Bearer $management_access_token" \
  --header "Content-Type: application/json" \
  --data '{
    "customized-consent": {
      "form-content": "<div style=\"font-size: 1.3em; font-weight: bold;\">Operation Details</div><hr style=\"margin: 10px 0;\"><div style=\"margin-bottom: 20px;\"></div><div style=\"font-weight: bold;\">Transaction Type</div><div>{{ transaction.params.authorization_details[0].type }}</div><div style=\"margin-bottom: 20px;\"></div><div style=\"font-weight: bold;\">Amount</div><div>{{ transaction.params.authorization_details[0].instructedAmount.amount }} {{ transaction.params.authorization_details[0].instructedAmount.currency }}</div><div style=\"margin-bottom: 20px;\"></div><div style=\"font-weight: bold;\">Recipient</div><div>{{ transaction.params.authorization_details[0].beneficiary }}</div><div style=\"margin-bottom: 20px;\"></div><div style=\"font-weight: bold;\">Destination Account</div><div>{{ transaction.params.authorization_details[0].destinationAccount }}</div><div style=\"margin-bottom: 20px;\"></div>"
    }
  }'
```

The customized consent template renders the `authorization_details` in the following consent prompt that Auth0 shows to the end user:

<Frame>
  <img alt="" />
</Frame>

In the [email notifications with CIBA and RAR flow](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/email-notifications-with-ciba), you need to customize the consent prompt to show the approval or rejection screens to the user:

<Frame>
  <img alt="User accepts the authentication request" />
</Frame>

<Frame>
  <img alt="User accepts the authentication request" />
</Frame>

To learn more about how to customize the consent prompt, read:

* [Customize Universal Login Pages](/docs/customize/login-pages/universal-login/customize-templates)
* [Customize Universal Login with the No-Code Editor](/docs/customize/login-pages/universal-login/customize-themes)
* [Set partials for a prompt API documentation](/docs/api/management/v2/prompts/put-partials)

## Optional: Configure consent policy for the resource server

The resource server's consent policy determines whether Auth0 stores the `authorization_details` values and makes them available to mobile applications when a push notification is sent.

Review Auth0's standard consent policy behavior for a request containing `authorization_details`:

<table>
  <thead>
    <tr>
      <th><strong>Flow</strong></th>
      <th><strong>Push notification sent</strong></th>
      <th><strong>Behavior</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Any</td>
      <td>No</td>
      <td>The customized consent prompt is shown.</td>
    </tr>

    <tr>
      <td>Authorization Code Flow with PAR</td>
      <td>Yes</td>

      <td>
        <p>
          No consent prompt is shown. The consent must be shown on the mobile application that receives the push notification challenge.
        </p>

        <p>
          If the Auth0 Guardian app is used, it will automatically display the `authorization_details` to the user.
        </p>

        <p>
          If a custom mobile app is used, the `authorization_details` can be retreived using the Auth0 Guardian SDK.
        </p>
      </td>
    </tr>

    <tr>
      <td>Client-Initiated Backchannel Authentication Flow</td>
      <td>Yes</td>

      <td>
        <p>
          If the Auth0 Guardian App is being used to authorize the CIBA request, the `authorization_details` will be fetched automatically and displayed.
        </p>

        <p>
          If a custom mobile app is used to authorize the CIBA request, the `authorization_details` can be retreived using the Auth0 Guardian SDK.
        </p>

        <p>
          If the CIBA request is being authorized using a web link (e.g. from an email), then the customized consent prompt will be shown.
        </p>

        <p>
          Customers may choose to trigger a push notification as a second factor for the CIBA request when the user is approving it by a web link, in which case the behavior is the same as above. The Auth0 Guardian app automatically displays the `authorization_details` to the user again, while custom mobile apps can choose to retrieve the `authorization_details` using the Auth0 Guardian SDK.
        </p>
      </td>
    </tr>
  </tbody>
</table>

Customers can also set the `consent_policy` to `transactional-authorization-with-mfa`, which has the following behavior:

<table>
  <thead>
    <tr>
      <th><strong>Flow</strong></th>
      <th><strong>Push notification sent</strong></th>
      <th><strong>Behaviour</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Authorization Code Flow with PAR</td>
      <td>No</td>
      <td>The customized consent prompt is shown.</td>
    </tr>

    <tr>
      <td>Authorization Code Flow with PAR</td>
      <td>Yes</td>

      <td>
        <p>
          No consent prompt is shown. The customer solution must show the consent using their own user interface. Auth0 will allocate a unique ID for the request and expose it to the Post-Login Action as `event.transaction.linking_id` along with the `event.transaction.requested_authorization_details`.
        </p>

        <p>
          If the Auth0 Guardian App is used, the `authorization_details` will NOT be displayed.
        </p>

        <p>
          If a custom mobile app is used, the push notification will include the `linking_id`, allowing application builders to retrieve the `authorization_details` from their own APIs if required.
        </p>
      </td>
    </tr>

    <tr>
      <td>Client-Initiated Backchannel Authentication Flow</td>
      <td>Any</td>
      <td>CIBA flow is not supported with `transactional-authorization-with-mfa` consent policy</td>
    </tr>
  </tbody>
</table>

You can set the consent policy for a resource server with the [Auth0 Dashboard](https://manage.auth0.com/) or [Management API](https://auth0.com/docs/api/management/v2).

<Tabs>
  <Tab title="Auth0 Dashboard">
    Set the consent policy in your API settings using the Auth0 Dashboard.

    1. Navigate to [Auth0 Dashboard > Applications > APIs](https://manage.auth0.com/#/apis).
    2. Select the **Settings** tab.
    3. Under **Access Settings**, choose the **Standard** consent policy.
    4. Save your changes.

    <Frame>
      <img alt="Dashboard > Applications > APIs > Settings > Access Settings" />
    </Frame>
  </Tab>

  <Tab title="Management API">
    To set the consent policy for a resource server or API using the Management API, send a `PATCH` request to the [Update a resource server](https://auth0.com/docs/api/management/v2/resource-servers/patch-resource-servers-by-id) endpoint. In the `PATCH` request, set the `consent_policy` to `standard`:

    ```bash wrap lines theme={null}
    curl --location --request PATCH 'https://$tenant/api/v2/resource-servers/$resource-server-id' \
      --header 'Authorization: Bearer $management_access_token' \
      --header 'Content-Type: application/json' \
      --data-raw '{ "consent_policy": "standard" }'
    ```
  </Tab>
</Tabs>


# Create Machine-to-Machine Applications for Testing
Source: https://auth0.com/docs/get-started/apis/create-m2m-app-test

Learn how to register and authorize a test machine-to-machine application for calling Management API endpoints using Access Tokens.

When you create an account, a default <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> instance is created in the API section of the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. A sample machine-to-machine test application is automatically created. The following instructions allow you to create another test application to use with this Management API instance and use the generated test token before building your own Production setup.

You should note, the test token located under API Explorer is for testing access to the Management API only. To learn more about Management API tokens, review [Get Management API Access Tokens for Production](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production). If you are interested in using the test token, visit [Get Management API Access Tokens for Testing](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-testing)

1. Go to [Dashboard > Applications > APIs](https://manage.auth0.com/#/apis) and select **Auth0 Management API**.
2. Select the **API Explorer** tab.
3. Click **Create & Authorize a Test Application**. A new application has been created and is authorized to access the Management API.

<Frame>
  <img alt="Dashboard Applications APIs Auth0 Management API Explorer Tab Authorize and Test" />
</Frame>

The application created in the steps above has been granted all the Management API scopes. This means that it can access all endpoints for testing purposes. However, applications do not generally allow access to all scopes but only authorizes scopes that are required.

<Card title="How can I find out which scopes/permissions are required for the Management API?">
  Each machine-to-machine application that accesses an API must be granted a set of [Scopes](/docs/get-started/apis/scopes/api-scopes). Scopes are permissions that should be granted by the owner. Each [Auth0 Management API v2](https://auth0.com/docs/api/management/v2) endpoint requires specific scopes. To see the required scopes/permissions for each endpoint, go to the [Management API Explorer](https://auth0.com/docs/api/management/v2#!) and find the endpoint you want to call. Each endpoint has a section called **Scopes** listing all the scopes that the endpoint accepts.
</Card>

## Example: Get All Connections endpoint

The [Get All Connections](https://auth0.com/docs/api/management/v2#!/Clients/get_connections) endpoint accepts the `read:connections` scope while the [Create a Connection](https://auth0.com/docs/api/management/v2#!/Clients/post_connections) endpoint accepts the `write:connections` scope. Our machine-to-machine token should only need the `read:connections` scope in order to access data from that endpoint.

If you have multiple applications that should access the Management API, then you should create separate machine-to-machine applications for each application in Auth0 instead of just a single machine-to-machine application.

## Learn more

* [Get Management API Access Tokens for Testing](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-testing)
* [Get Management API Access Tokens for Production](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production)
* [Get Management API Access Tokens for Single-Page Applications](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-tokens-for-single-page-applications)
* [Applications in Auth0](/docs/get-started/applications)


# Delete API Permissions
Source: https://auth0.com/docs/get-started/apis/delete-api-permissions

Learn how to delete permissions from APIs using the Auth0 Dashboard or the Management API.

You can delete permissions from an API using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## Use the Dashboard

1. Go to [Dashboard > Applications > APIs](https://manage.auth0.com/#/apis) and click the name of the API to view.

   <Frame>
     <img alt="Dashboard Applications APIs List" />
   </Frame>
2. Go to the **Permissions** tab and click the trashcan icon next to the permission you want to remove and confirm.

   <Frame>
     <img alt="Dashboard Add API Permissions API Define Permissions Screen" />
   </Frame>

## Use the Management API

Make a PATCH call to the [Update Resource Server endpoint](https://auth0.com/docs/api/management/v2#!/Resource_Servers/patch_resource_servers_by_id) that includes all permissions you want to keep and excludes all permissions you want to delete. Replace `API_ID,` `MGMT_API_ACCESS_TOKEN`, `PERMISSION_NAME`, and `PERMISSION_DESC` placeholder values with your API ID, Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, permission name(s), and permission description(s), respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/resource-servers/API_ID' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "scopes": [ { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" }, { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" } ] }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/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", "{ "scopes": [ { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" }, { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" } ] }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/resource-servers/API_ID"

  	payload := strings.NewReader("{ "scopes": [ { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" }, { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" } ] }")

  	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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/resource-servers/API_ID")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "scopes": [ { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" }, { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" } ] }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/resource-servers/API_ID',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: {
      scopes: [
        {value: 'PERMISSION_NAME', description: 'PERMISSION_DESC'},
        {value: 'PERMISSION_NAME', description: 'PERMISSION_DESC'}
      ]
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"scopes": @[ @{ @"value": @"PERMISSION_NAME", @"description": @"PERMISSION_DESC" }, @{ @"value": @"PERMISSION_NAME", @"description": @"PERMISSION_DESC" } ] };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/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 => "{ "scopes": [ { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" }, { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" } ] }",
    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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "scopes": [ { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" }, { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" } ] }"

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

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

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/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 = "{ "scopes": [ { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" }, { "value": "PERMISSION_NAME", "description": "PERMISSION_DESC" } ] }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = ["scopes": [
      [
        "value": "PERMISSION_NAME",
        "description": "PERMISSION_DESC"
      ],
      [
        "value": "PERMISSION_NAME",
        "description": "PERMISSION_DESC"
      ]
    ]] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>API\_ID</code></td>
      <td>ID of the API for which you want to delete permissions.</td>
    </tr>

    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td><a href="https://auth0.com/docs/api/management/v2/tokens">Access Token for the Management API</a> with the scope <code>update:resource\_servers</code>.</td>
    </tr>

    <tr>
      <td><code>PERMISSION\_NAME</code></td>
      <td>Name(s) of the permission(s) you want to keep for the specified API.</td>
    </tr>

    <tr>
      <td><code>PERMISSION\_DESC</code></td>
      <td>User-friendly description(s) of the permission(s) you want to keep for the specified API.</td>
    </tr>
  </tbody>
</table>

## Learn more

* [Customize Consent Prompts](/docs/customize/login-pages/customize-consent-prompts)
* [Configure Logical API for Multiple APIs](/docs/get-started/apis/set-logical-api)
* [Role-Based Access Control](/docs/manage-users/access-control/rbac)
* [Enable Role-Based Access Control for APIs](/docs/get-started/apis/enable-role-based-access-control-for-apis)


# Enable Role-Based Access Control for APIs
Source: https://auth0.com/docs/get-started/apis/enable-role-based-access-control-for-apis

Learn how to enable role-based access control (RBAC) for an API using the Auth0 Dashboard or the Management API.

You can enable [role-based access control (RBAC)](/docs/manage-users/access-control/rbac) using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. This enables the API Authorization Core feature set.

When RBAC is enabled, the `scope` claim of the <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> 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, an application can request any permission defined for the API, and the `scope` claim includes all requested permissions.

<Callout icon="file-lines">
  If you configure any [Actions](/docs/customize/actions) that modify access token scopes, they will override the scopes set by RBAC.
</Callout>

## Dashboard

1. Go to [Dashboard > Applications > APIs](https://manage.auth0.com/#/apis) and click the name of the API to view.

   <Frame>
     <img alt="Dashboard Applications APIs List" />
   </Frame>
2. Scroll to **RBAC Settings** and enable the **Enable RBAC** toggle.

   <Frame>
     <img alt="Auth0 Dashboard API Settings RBAC toggle" />
   </Frame>
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.
   Once you’ve enabled the **Add Permissions in the Access Token** toggle, Auth0 also updates your token dialect based on the [access token profile](/docs/secure/tokens/access-tokens/access-token-profiles) you’ve set for the API:

   * If your token dialect is `access_token`, Auth0 updates it to `access_token_authz`, which is equivalent to the `access_token` profile with the `permissions` claim included.
   * If your token dialect is `rfc9068_profile`, Auth0 updates it to `rfc9068_profile_authz`, which is equivalent to the `rfc9068_profile` with the `permissions` claim included.

   To learn more about the available token dialects, read [Token dialect options](#token-dialect-options).

## Management API

To enable RBAC using the Management API, make a PATCH request to the [Update a resource server endpoint](https://auth0.com/docs/api/management/v2/resource-servers/patch-resource-servers-by-id). In the PATCH request, set `enforce_policies` to `true`:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/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" }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/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);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/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();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/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);
  });
  ```

  ```objc Obj-C theme={null}
  #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://{yourDomain}/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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/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;
  }
  ```

  ```python Python theme={null}
  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", "/{yourDomain}/api/v2/resource-servers/API_ID", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/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
  ```

  ```swift Swift theme={null}
  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://{yourDomain}/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()
  ```
</AuthCodeGroup>

Replace `API_ID`, `MGMT_API_ACCESS_TOKEN`, and `TOKEN_DIALECT` with their respective values, as shown in the following table:

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>API\_ID</code></td>
      <td>ID of the API for which you want to enable RBAC.</td>
    </tr>

    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td><a href="https://auth0.com/docs/api/management/v2/tokens">Access Token for the Management API</a> with the scope <code>update:resource\_servers</code>.</td>
    </tr>

    <tr>
      <td><code>TOKEN\_DIALECT</code></td>
      <td>Dialect of the access token for the specified API. To learn more, read <a href="#token-dialect-options">Token dialect options</a>.</td>
    </tr>
  </tbody>
</table>

### Token dialect options

Auth0 supports the following token dialects:

<table>
  <thead>
    <tr>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>access\_token</code></td>
      <td>The Auth0 default token profile generates an access token formatted as a <a href="/docs/secure/tokens/json-web-tokens">JSON Web Token (JWT)</a>. In the <code>scope</code> claim of the access token, includes an intersection of the requested permissions and the permissions assigned to the user. No <code>permissions</code> claim is passed. To learn more, read <a href="/docs/secure/tokens/access-tokens/access-token-profiles">Access Token Profiles</a>.</td>
    </tr>

    <tr>
      <td><code>access\_token\_authz</code></td>
      <td>The Auth0 default token profile (<code>access\_token</code>) with the <code>permissions</code> claim. In the <code>scope</code> claim of the access token, includes an intersection of the requested permissions and the permissions assigned to the user. In the <code>permissions</code> 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.</td>
    </tr>

    <tr>
      <td><code>rfc9068\_profile</code></td>
      <td>The RFC 9068 token profile generates an access token formatted as a JWT following the <a href="https://datatracker.ietf.org/doc/html/rfc9068">IETF JWT Profile for OAuth 2.0 Access Tokens (RFC 9068)</a>. In the <code>scope</code> claim of the access token, includes an intersection of the requested permissions and the permissions assigned to the user. No <code>permissions</code> claim is passed. To learn more, read <a href="/docs/secure/tokens/access-tokens/access-token-profiles">Access Token Profiles</a>.</td>
    </tr>

    <tr>
      <td><code>rfc9068\_profile\_authz</code></td>
      <td>The RFC 9068 token profile (<code>rfc9068\_profile</code>) with the <code>permissions</code> claim. In the <code>scope</code> claim of the access token, includes an intersection of the requested permissions and the permissions assigned to the user. In the <code>permissions</code> 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.</td>
    </tr>
  </tbody>
</table>

## Learn more

* [Manage Role-Based Access Control Users](/docs/manage-users/access-control/configure-core-rbac/rbac-users)
* [Manage Role-Based Access Control Permissions](/docs/manage-users/access-control/configure-core-rbac/manage-permissions)
* [Sample Use Cases: Role-Based Access Control](/docs/manage-users/access-control/sample-use-cases-role-based-access-control)
* [Troubleshoot Role-Based Access Control and Authorization](/docs/troubleshoot/authentication-issues/troubleshoot-rbac-authorization)


# Scopes
Source: https://auth0.com/docs/get-started/apis/scopes

Understand the principle of scopes and explore general examples of their use.

Different pieces of user information are often stored across a number of online resources. Users may upload and store photos with a service like Flickr, keep digital files on Dropbox, and store contacts and events in Google Calendar or on Facebook.

Often, new applications will want to make use of the information that has already been created in an online resource. To do so, the application must ask for authorization to access this information on a user's behalf. Scopes define the specific actions applications can be allowed to do on a user's behalf.

## Ways to use scopes

When an app requests permission to access a resource through an <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip>, it uses the `scope` parameter to specify what access it needs, and the authorization server uses the `scope` parameter to respond with the access that was actually granted (if the granted access was different from what was requested).

Generally, you use scopes in three ways:

* From an application, to verify the identity of a user and get basic profile information about the user, such as their email or picture. In this scenario, the scopes available to you include those implemented by the <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) protocol. To learn more, read [OpenID Connect Scopes](/docs/get-started/apis/scopes/openid-connect-scopes).
* In an [API](/docs/api), to implement access control. In this case, you need to define custom scopes for your API and then identify these scopes so that calling applications can use them. To learn more, read [API Scopes](/docs/get-started/apis/scopes/api-scopes).
* From an application, to call an API that has implemented its own custom scopes. In this case, you need to know which custom scopes are defined for the API you are calling. To see examples of calling a custom API from an application, read [Sample Use Cases: Scopes and Claims](/docs/get-started/apis/scopes/sample-use-cases-scopes-and-claims)

## Best practices

Understand your use case and choose the most restrictive scopes possible.

If you are requesting scopes, make sure you ask for enough access for your application to function, but only request what you absolutely need. Are you establishing a user's identity or asking the user to allow you to interact with their data? There's a big difference between importing a user's Facebook profile information and posting to their wall. By only requesting what you need, you are more likely to gain user consent when required since users are more likely to grant access for limited, clearly specified scopes.

Similarly, when creating custom scopes for an API, consider what levels of granular access applications may need and design accordingly.

## Requested scopes versus granted scopes

In certain cases, users get to consent to the access being requested. While usually, the scopes returned will be identical to those requested, users can edit granted scopes (both during initial consent and sometimes after, depending on the resource), thereby granting an app less access than it requested.

As an application developer, you should be aware of this possibility and handle these cases in your app. For example, your app could warn the user that they will see reduced functionality. It could also send the user back through the <Tooltip href="/docs/glossary?term=authorization+flow">authorization flow</Tooltip> to ask for additional permissions. But again, remember that when asked for consent, users can always say no.

By default, Auth0 skips user consent for first-party applications, which are applications that are registered under the same Auth0 domain as the API they are calling; however, you can configure your API in Auth0 to require user consent from first-party applications. Third-party applications, which are external applications, require user consent.

## Learn more

* [OpenID Connect Scopes](/docs/get-started/apis/scopes/openid-connect-scopes)
* [API Scopes](/docs/get-started/apis/scopes/api-scopes)
* [Sample Use Cases: Scopes and Claims](/docs/get-started/apis/scopes/sample-use-cases-scopes-and-claims)
* [Enable Role-Based Access Control for APIs](/docs/get-started/apis/enable-role-based-access-control-for-apis)


# API Scopes
Source: https://auth0.com/docs/get-started/apis/scopes/api-scopes

Understand the principle of scopes and how it is used with APIs.

As an API developer, you need to:

1. Decide which information you would like applications to be able to access on a user's behalf.
2. Define these access levels as custom scopes. (To learn what scopes are read [Scopes](/docs/get-started/apis/scopes).)
3. Identify these scopes so that calling applications can use them.

## Ways to use API scopes

You can use API scopes in different ways:

* In an API where the calling application is a third-party, or external, application. In this case, the calling application will request authorization from the user to access the requested scopes, and the user will approve or deny the request.
* In an API where the calling application is a first-party application, or application that is registered under the same Auth0 domain as the API it is calling. In this case, by default, user consent is not requested, but you may configure consent to be required.
* In an API where the calling application is a back-end service, whether third-party or first-party, and no user exists. In this case, user consent is never requested.

All of these examples use scopes to limit access through use of a token. If you so choose, your API may also use additional logic beyond the token to enforce more extensive access control.

For an example showing how to request custom API access for your application, read [Sample Use Cases: Scopes and Claims](/docs/get-started/apis/scopes/sample-use-cases-scopes-and-claims).

### Example: An API called by a third-party application

Let's say you are building an API that provides bank account information to online payment applications. At various times, apps may need to read account balances or transfer funds. To do this, you create two scopes for your API: one that authorizes read access to an account balance (`read:balance`), one that authorizes fund transfers (`transfer:funds`). Your API is registered with Auth0.

A calling application will request authorization from the user to access the requested scopes, and the user will approve or deny the request. The app may request read access to the user's balance by including the `read:balance` scope in its request, access to make fund transfers by including the `transfer:funds` scope in its request, or access to both read the user's balance and transfer funds by including both the `read:balance` and `transfer:funds` scopes in its request.

Now, when the app calls your API, it will include a token which verifies that the user has provided authorization to access their content and also indicates which scopes the user has approved. Your API should respect the approved scopes and only release information that was authorized by the user to the calling application.

### Example: An API called by a first-party application

Let's say you are building an API that provides data to an events application, which you have also written. You [implement role-based access control (RBAC)](/docs/manage-users/access-control/rbac), creating a role of `organizer` and a role of `participant`. Users with a role of `organizer` need to create and update events, whereas users with a role of `participant` need to view events and register for events. To do this, you create four scopes for your API: one that authorizes create access for events(`create:events`), one that authorizes update access for events (`update:events`), one that authorizes read-only access for events (`view:events`), and one that authorizes registration access for events (`register:events`). Both your API and event application are registered with Auth0, and the **Allow Skipping User Consent** for first-party applications option is enabled for your API. You have installed the Authorization Extension and configured an `organizer` role and created the `create:events` and `update:events` scopes for it, and assigned it to User A. You have also configured a `participant` role and created the `view:events` and `register:events` scopes for it, and assigned it to User B.

User A authenticates with the calling application, which requests the necessary scopes, but because it is a first-party application, user consent will not be requested. The app may request any combination of `create:events`, `update:events`, `view:events`, and `register:events` scopes, but User A is recognized as having the role of `organizer` and therefore is only granted the `create:events` and `update:events` scopes.

Now, when the app calls your API, it will include a token which verifies that it has authorization for only the scopes associated with the role of the authenticated user.

### Example: An API called by a back-end service

Let's say you work for a hospital and have an API that produces large amounts of imaging data whenever a patient gets an MRI. You store the imaging data locally for six months, but the hospital needs the images to be stored long-term for the purpose of regulatory compliance. Because of this, the hospital has a service that copies imaging data to an offsite cold storage solution on a nightly basis and deletes all local medical data after six months of storage.

To do this, you create two scopes for your API: one that authorizes read access to your imaging data (`read:images`) and one that authorizes delete access to your imaging data (`delete:images`). Your API and automated service are registered with Auth0, and you have authorized the automated service to request tokens for your API.

The calling automated service will request the necessary scopes, but because there is no user, consent will not be requested. The service may request read access to your imaging data by including the `read:images` scope in its request, delete access by including the `delete:images` scope in its request, or both read and delete access by including the `read:images` and `delete:images` scopes in its request.

Now, when the automated service calls your API, it will include a token which verifies that it has authorization for the requested scopes.

## Limit API scopes

An application can include any scope defined for an API in its request. Instead of allowing all available scopes to be requested, however, you can control how applications access your APIs using [API access policies for applications](/docs/get-started/apis/api-access-policies-for-applications).

## Learn more

* [Sample Use Cases: Scopes and Claims](/docs/get-started/apis/scopes/sample-use-cases-scopes-and-claims)
* [Add API Permissions](/docs/get-started/apis/add-api-permissions)
* [Customize Consent Prompts](/docs/customize/login-pages/customize-consent-prompts)
* [Configure Logical API for Multiple APIs](/docs/get-started/apis/set-logical-api)
* [Get Management API Access Tokens for Production](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production)
* [Get Management API Access Tokens for Testing](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-testing)


# OpenID Connect Scopes
Source: https://auth0.com/docs/get-started/apis/scopes/openid-connect-scopes

Understand scopes and claims used with the OpenID Connect (OIDC) protocol.

This document discusses scopes included within the <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) authentication protocol. For more info about OIDC itself, read [OpenID Connect Protocol](/docs/authenticate/protocols/openid-connect-protocol).

OpenID Connect (OIDC) scopes are used by an application during authentication to authorize access to a user's details, like name and picture. Each scope returns a set of user attributes, which are called claims. The scopes an application should request depend on which user attributes the application needs. Once the user authorizes the requested scopes, the claims are returned in an <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip> and are also available through the [`/userinfo` endpoint](https://auth0.com/docs/api/authentication#get-user-info).

For example, let's say you have built a regular web application, registered it with Auth0, and have configured it to allow a user to log in using a username and password. Once a user logs in to your app, you want to auto-generate and send a personalized welcome email, including the user's name.

1. A user clicks **Login** within your app.
2. Your app redirects the user to the Auth0 Authorization Server (`/authorize` endpoint), including the following scopes:

   * `openid` (required; to indicate that the application intends to use OIDC to verify the user's identity)
   * `profile` (so you can personalize the email with the user's name)
   * `email` (so you know where to send the welcome email)
3. Your Auth0 Authorization Server redirects the user to the login prompt.
4. The user authenticates and sees a consent page listing the scopes Auth0 will give to your app, which include access to their profile information and email address.
5. The user accepts and authorizes your app to have this level of access to their information stored by Auth0.
6. Your app now has access to the user's profile information and email address.

## Standard claims

Standard claims are intended to provide an application with user details, such as name, email, and picture, and are pre-defined for the OIDC protocol. These claims are returned in an ID Token and are also available through the [`/userinfo` endpoint](https://auth0.com/docs/api/authentication#get-user-info).

You can also create custom claims, which are claims that you define, control, and add to a token using [Auth0 Actions](/docs/customize/actions/actions-overview). To learn more, read [JSON Web Token Claims](/docs/secure/tokens/json-web-tokens/json-web-token-claims).

The basic (and required) scope for OIDC is `openid`, which indicates that an application intends to use the OIDC protocol to verify a user's identity. Beyond that, an application can ask for additional scopes by listing the requested scope names in the `scope` parameter, separated by spaces.

Standard claims included in the most commonly-used scopes are listed below, but for a full list of available standard claims, read [OIDC specification: Standard Claims on openid.net](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). For a full list of Scopes, see [OIDC specification: Requesting Claims Using Scope Values on openid.net](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims).

<table>
  <thead>
    <tr>
      <th>Scope</th>
      <th>Claims</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>openid</code></td>
      <td>(required) Returns the <code>sub</code> claim, which uniquely identifies the user. In an ID Token, <code>iss</code>, <code>aud</code>, <code>exp</code>, <code>iat</code>, and <code>at\_hash</code> claims will also be present. To learn more about the ID Token claims, read <a href="/docs/secure/tokens/id-tokens/id-token-structure">ID Token Structure</a>.</td>
    </tr>

    <tr>
      <td><code>profile</code></td>
      <td>Returns claims that represent basic profile information, including <code>name</code>, <code>family\_name</code>, <code>given\_name</code>, <code>middle\_name</code>, <code>nickname</code>, <code>picture</code>, and <code>updated\_at</code>.</td>
    </tr>

    <tr>
      <td><code>email</code></td>
      <td>Returns the <code>email</code> claim, which contains the user's email address, and <code>email\_verified</code>, which is a boolean indicating whether the email address was verified by the user.</td>
    </tr>
  </tbody>
</table>

For an example showing how to request standard claims for your application, read [Sample Use Cases: Scopes and Claims](/docs/get-started/apis/scopes/sample-use-cases-scopes-and-claims).

## Learn more

* [Sample Use Cases: Scopes and Claims](/docs/get-started/apis/scopes/sample-use-cases-scopes-and-claims)
* [Scopes](/docs/get-started/apis/scopes)
* [Create Custom Claims](/docs/secure/tokens/json-web-tokens/create-custom-claims)


# Sample Use Cases: Scopes and Claims
Source: https://auth0.com/docs/get-started/apis/scopes/sample-use-cases-scopes-and-claims

Learn how to use scopes and claims with applications and APIs.

In these examples, we use the [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow) to authenticate a user and request the necessary permissions (scopes) and tokens. For details on the request parameters or to learn how to fully implement this flow, read our tutorial: [Add Login to Regular Web Applications](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/add-login-auth-code-flow).

## Authenticate a user and request standard claims

In this example, we want to authenticate a user and get user details that will allow us to personalize our user interface. To do this, we need to get an <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> that contains the user's name, nickname, profile picture, and email information.

1. Initiate the authentication flow by sending the user to the authorization URL:

   <AuthCodeBlock />

   Notice that in this example:

   * The `response_type` parameter includes one value:

     * `code`: because we are using the regular web app flow, our initial request is for an authorization code; when we request our tokens using this code, we will receive the ID Token we need for authentication.
   * The `scope` parameter includes three values; the requested OIDC scopes:

     * `openid`: to indicate that the application intends to use OIDC to verify the user's identity.
     * `profile`: to get `name`, `nickname`, and `picture`.
     * `email`: to get `email` and `email_verified`.
2. After the user consents (if necessary) and Auth0 redirects back to your app, [request tokens](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/add-login-auth-code-flow).
3. Extract the ID token from the response and [decode it](/docs/secure/tokens/id-tokens). You should see the following claims:

   <AuthCodeBlock />

   Your app can now retrieve the user attributes and use them to personalize your UI.

## Request custom API access

In this example, we request a custom scope for a calendar API that will authorize the calling application to read appointments for the user. To do this, we want to get an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> containing the proper scope to read appointments from the API. Note that requesting an access token is not dependent on requesting an ID token.

Before using a custom API, you need to know what scopes are available for the API you are calling. If the custom API is under your control, you need to register both your application and API with Auth0 and [define the scopes for your API using the Auth0 Dashboard](/docs/get-started/apis/scopes/api-scopes). You can also use defined permissions to [customize the consent prompt](/docs/customize/login-pages/customize-consent-prompts) for your users.

1. Initiate the authorization flow by sending the user to the authorization URL:

   <AuthCodeBlock />

   Notice that in this example:

   * The `response_type` parameter still includes one value:

     * `code`: because we are using the regular web app flow, our initial request is for an authorization code; when we request our tokens using this code, we will receive the Access Token that we can use to call our API.
   * the `scope` parameter includes one value; the requested API scope:

     * `read:appointments`: to allow us to read the user's appointments from the API.
   * The `audience` parameter is new and includes one value:

     * The unique identifier of the API from which we want to read the user's appointments.
2. As in the previous example, after the user consents (if necessary) and Auth0 redirects back to your app, [request tokens](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/add-login-auth-code-flow).
3. Extract the access token from the response, and call the API using the access token as credentials.

## Authenticate a user and request standard claims and custom API access

In this example, we combine our previous two examples to authenticate a user, request standard claims, and also request a custom scope for a calendar API that will allow the calling application to read appointments for the user. To do this, get two tokens:

* ID token that contains:

  * User name
  * Nickname
  * Profile picture
  * Email information
* Access token that contains the proper scope to read appointments from the API. Note that requesting an access token is not dependent on requesting an ID token.

Before using a custom API, you need to know what scopes are available for the API you are calling. If the custom API is under your control, you need to register both your application and API with Auth0 and [define the scopes for your API using the Auth0 Dashboard](/docs/get-started/apis/scopes/api-scopes). You can also use defined permissions to [customize the consent prompt](/docs/customize/login-pages/customize-consent-prompts) for your users.

1. Initiate the authentication flow by sending the user to the authorization URL:

   <AuthCodeBlock />

   Notice that in this example:

   * The `response_type` parameter still includes one value:

     * `code`: because we are using the regular web app flow, our initial request is for an authorization code; when we request our tokens using this code, we will receive both the ID token we need for authentication and the access token that we can use to call our API.
   * The `scope` parameter is used for both OIDC scopes and API scopes, so now includes four values:

     * `openid`: to indicate that the application intends to use OIDC to verify the user's identity.
     * `profile`: to get `name`, `nickname`, and `picture`.
     * `email`: to get `email` and `email_verified`.
     * `read:appointments`: to allow us to read the user's appointments from the API.
   * the `audience` parameter includes one value:

     * The unique identifier of the API from which we want to read the user's appointments
2. As in the previous examples, after the user consents (if necessary) and Auth0 redirects back to your app, request tokens.
3. Extract the ID token from the response, decode it, and retrieve the user attributes and use them to personalize your UI.
4. Extract the access token from the response, and call the API using the access token as credentials.

## Add custom claims to a token

In this example, we add a user's favorite color and preferred contact method to the ID Token. To do this, we create an [Action](/docs/customize/actions) to customize the ID token by adding these [claims](/docs/secure/tokens/json-web-tokens/create-custom-claims). Once added, we will also be able to obtain the custom claims when calling the `/userinfo` endpoint (though the Action will run only during the authentication process).

<Callout icon="file-lines">
  Auth0 allows namespaced and non-namespaced claims, but certain restrictions apply (see [General restrictions](/docs/secure/tokens/json-web-tokens/create-custom-claims#general-restrictions)). To avoid name collisions, we recommend using namespaced claims. In case of collisions, the transaction won't fail, but your custom claim won't be added to your tokens.
</Callout>

Suppose that:

* At some point, the user selected a `preferred_contact` method of `email` and a `favorite_color` of `red`, and we saved it as part of the user's `user_metadata`.
* We've used the [Management API](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id) or the Dashboard to set application-specific information for this user.

In this case, the Auth0-stored [normalized user profile](/docs/manage-users/user-accounts/user-profiles/normalized-user-profiles) is:

```json lines theme={null}
{
  "email": "jane@example.com",
  "email_verified": true,
  "user_id": "custom|123",
  "favorite_color": "blue",
  "user_metadata": {
    "preferred_contact": "email"
  }
}
```

For this profile, Auth0 would normally return the following ID Token claims to your application:

```json lines theme={null}
{
  "email": "jane@example.com",
  "email_verified": true,
  "iss": "https://my-domain.auth0.com/",
  "sub": "custom|123",
  "aud": "my_client_id",
  "iat": 1311280970,
  "exp": 1311281970
}
```

Notice that in this example:

* The `sub` claim contains the value of the `user_id` property.
* Neither the `favorite_color` nor `user_metadata` properties are present because <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) does not define standard claims that represent `favorite_color` or `user_metadata`.

To receive the custom data, we'll need to [create a new Action](/docs/customize/actions/write-your-first-action) to customize the token with a [custom claims](/docs/secure/tokens/json-web-tokens/create-custom-claims) that represent these properties from the user profile.

1. Navigate to [Auth0 Dashboard > Actions > Library](https://manage.auth0.com/#/actions/library), and select **Build Custom**.

2. Enter a descriptive **Name** for your Action (for example, `Add user metadata to tokens`), select the `Login / Post Login` trigger because you’ll be adding the Action to the Login flow, then select **Create**.

3. Locate the Actions Code Editor, copy the following JavaScript code into it, and select **Save Draft** to save your changes:

   ```javascript lines theme={null}
   exports.onExecutePostLogin = async (event, api) => {
     const namespace = 'https://myapp.example.com';
     const { favorite_color, preferred_contact } = event.user.user_metadata;

     if (event.authorization) {
       // Set claims 
       api.idToken.setCustomClaim(`${namespace}/favorite_color`, favorite_color);
       api.idToken.setCustomClaim(`${namespace}/preferred_contact`, preferred_contact);
     }
   };
   ```

4. From the Actions Code Editor sidebar, select Test (play icon), then select **Run** to [test your code](/docs/customize/actions/test-actions).

5. When you’re ready for the Action to go live, select **Deploy**.

Finally, add the Action you created to the [Login Flow](https://manage.auth0.com/#/actions/flows/login/). To learn how to attach Actions to Flows, read the "Attach the Action to a flow" section in [Write Your First Action](/docs/customize/actions/write-your-first-action).

With this Action enabled, Auth0 will include the `favorite_color` and `preferred_contac`t custom claims in the ID Token:

```json lines theme={null}
{
  "email": "jane@example.com",
  "email_verified": true,
  "iss": "https://my-domain.auth0.com/",
  "sub": "custom|123",
  "aud": "my_client_id",
  "iat": 1311280970,
  "exp": 1311281970,
  "https://myapp.example.com/favorite_color": "red",
  "https://myapp.example.com/preferred_contact": "email"
}
```

When creating your Action, make sure to set some logic that determines when to include additional claims. Injecting custom claims into every ID Token that is issued is not ideal.

This example shows custom claims being added to an ID Token, which uses the `api.idToken.setCustomClaims` method. To add these claims to an Access Token, use the `api.accessToken.setCustomClaim` method.

To learn more about the event object for the trigger, read [Actions Triggers: post-login - Event Object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object). To learn more about tokens, read [Tokens](/docs/secure/tokens).

## Learn more

* [OpenID Connect Scopes](/docs/get-started/apis/scopes/openid-connect-scopes)
* [Create Custom Claims](/docs/secure/tokens/json-web-tokens/create-custom-claims)
* [API Scopes](/docs/get-started/apis/scopes/api-scopes)
* [Configure Logical API for Multiple APIs](/docs/get-started/apis/set-logical-api)


# Configure Logical API for Multiple APIs
Source: https://auth0.com/docs/get-started/apis/set-logical-api

Learn how to use a single logical API in Auth0 to represent and control access to multiple APIs.

If you have multiple distinct API implementations that are all logically a part of the same API, you can simplify your authorization process by representing them with a single logical API in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. Doing this allows you to implement just one <Tooltip href="/docs/glossary?term=authorization+flow">authorization flow</Tooltip>, while still controlling access to the individual APIs by assigning the appropriate scopes.

The following sections describe how to use and represent multiple APIs as a single <Tooltip href="/docs/glossary?term=Resource+Server">Resource Server</Tooltip> in Auth0. We will use the following sample application in the examples. The sample application uses a microservices architecture and contains:

* 2 Node.js APIs: `contacts` and `calendar` (you can think of them as microservices)
* 1 Resource Server representing the 2 APIs
* 2 Namespaced scopes: `read:contacts` and `read:calendar`
* The Implicit Grant flow to obtain an `access_token` that works for both APIs

We will represent the two APIs using just one Auth0 API called `Organizer Service`. We will then create two scopes to demonstrate how you can use the [Implicit Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce) to access the `calendar` and `contacts` APIs from the SPA.

You need to complete the following steps:

1. Enable a connection for your application
2. Create a test user
3. Register a logical API in Auth0
4. Configure scopes for the logical API
5. Grant access to the logical API
6. (Optional) Implement single logout (SLO) or single sign-on (SSO)

## Prerequisites

* [Register your application](/docs/get-started/auth0-overview/create-applications/single-page-web-apps).

  * Select an **Application Type** of **Single-Page App**.
  * Add **Allowed Callback URLs** of `http://localhost:3000` and `http://localhost:3000/callback.html`.
* Download the [sample application](https://github.com/auth0-samples/auth0-api-auth-implicit-sample). To learn how to set up the sample app, read the [README](https://github.com/auth0-samples/auth0-api-auth-implicit-sample#readme).

## Enable a connection for your application

You will need a source of users for your newly-registered application, so you will need to configure a [connection](/docs/authenticate/identity-providers). For the purpose of this sample, we'll create a simple [Database Connection](/docs/authenticate/database-connections) that asks only for the user's email address and a password. To learn more, read [Set Up Database Connections](/docs/get-started/applications/set-up-database-connections).

## Create a test user

Since you're working with a newly-created connection, there won't be any users associated with it. Before we can test the sample application's login process, we'll need to create and associate a user with the connection, so make sure you choose your newly-created Connection when you create your user. To learn more, read [Create Users](/docs/manage-users/user-accounts/create-users).

## Register a logical API in Auth0

Register a single logical API that you will use to represent the multiple APIs contained within the sample application. For the purpose of this sample, call your API `Organizer Service` and set its unique identifier to `organize`. By default, the <Tooltip href="/docs/glossary?term=signing+algorithm">signing algorithm</Tooltip> for the tokens obtained for this API is **RS256**, which you should leave as is. To learn more, read [Register APIs](/docs/get-started/auth0-overview/set-up-apis).

## Configure permissions for the logical API

To allow the logical API to represent the APIs included within the sample application, you will need to create the proper permissions (scopes).

Scopes allow you to define which API actions will be accessible to calling applications. One scope will represent one API/action combination. For the purpose of this sample, you want calling applications to be able to `read` from one API called `calendar` and another one called `contacts`, so you will need to create the following permissions:

* `read:calendar`
* `read:contacts`

You can think of each one as a microservice. To learn more, read [Add API Permissions](/docs/get-started/apis/add-api-permissions) and [API Scopes](/docs/get-started/apis/scopes/api-scopes).

## Grant access to the logical API

You are now ready to provide access to your APIs by allowing the logical API to obtain <Tooltip href="/docs/glossary?term=Access+Tokens">Access Tokens</Tooltip>. By including the necessary scopes, you can control an application's access to the APIs represented by the logical API. The following steps use the [Implicit Flow](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post) to reflect the sample. However, you can use whichever flow best suits your needs. For example:

* If you have a **Machine-to-Machine Application**, you can authorize it to request Access Tokens for your API by executing a [Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow).
* If you are building a **Native App**, you can implement the [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce).

To learn about Authorization flows, read [Authentication and Authorization Flows](/docs/get-started/authentication-and-authorization-flow).

1. The user clicks Login within the SPA, and the app redirects the user to the Auth0 Authorization Server (`/authorize` endpoint). To learn more about the call's parameters, see our tutorial: [Call Your API Using the Authorization Code Flow with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/call-your-api-using-the-authorization-code-flow-with-pkce).

   <AuthCodeBlock />

   <Frame>
     <img alt="Example application sign in page" />
   </Frame>
2. Your Auth0 Authorization Server redirects the user to the login page, where the user authenticates using one of the configured login options.

   <Frame>
     <img alt="Lock login page" />
   </Frame>
3. If this is the first time the user has been through this flow, they see a consent prompt listing the permissions Auth0 will give to the SPA. In this case, the user is asked to consent to the app reading their contacts and calendar.

   <Frame>
     <img alt="Example application Lock Consent screen" />
   </Frame>
4. If the user consents, Auth0 redirects the user back to the SPA with tokens in the hash fragment of the URI. The SPA can now extract the tokens from the hash fragment using JavaScript and use the Access Token to call your APIs on behalf of the user.

   ```javascript lines theme={null}
   function getParameterByName(name) {
     var match = RegExp('[#&]' + name + '=([^&]*)').exec(window.location.hash);
     return match && decodeURIComponent(match[1].replace(/\+/g, ' '));
   }

   function getAccessToken() {
     return getParameterByName('access_token');
   }
   ```

   In our sample, after you successfully log in, you will see buttons that allow you to call either of your APIs using the Access Token obtained from the logical API.

   <Frame>
     <img alt="Example application user authorized screen" />
   </Frame>

### Implement single logout (SLO) or single sign-on (SSO)

In some multi-application scenarios, where Single Logout is desired (a user logging out of one application needs to be logged out of other applications), an application can be set up to periodically poll Auth0 using `checkSession()` to see if a session exists. If the session does not exist, you can then log the user out of the application. The same polling method can be used to implement silent authentication for a <Tooltip href="/docs/glossary?term=Single+Sign-on">Single Sign-on</Tooltip> (SSO) scenario.

The poll interval between checks to `checkSession()` should be at least 15 minutes between calls to avoid any issues in the future with rate limiting of this call.

## Learn more

* [Register APIs](/docs/get-started/auth0-overview/set-up-apis)
* [Add API Permissions](/docs/get-started/apis/add-api-permissions)
* [API Scopes](/docs/get-started/apis/scopes/api-scopes)
* [Check API Calls](/docs/troubleshoot/authentication-issues/check-api-calls)


# Applications in Auth0
Source: https://auth0.com/docs/get-started/applications

Learn the basics of registering and configuring your applications in Auth0.

The term **application** or **app** in Auth0 does not imply any particular implementation characteristics. For example, it could be a native app that executes on a mobile device, a single-page application that executes on a browser, or a regular web application that executes on a server.

Auth0 categorizes apps based on these characteristics:

* **Application type**: To add authentication to your application, you must register it in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> and select from one of the following application types:

  * **Regular web application**: Traditional web apps that perform most of their application logic on the server (such as Express.js or ASP.NET). To learn how to set up a regular web application, read [Register Regular Web Applications](/docs/get-started/auth0-overview/create-applications/regular-web-apps).
  * **Single page web application (SPA)**: JavaScript apps that perform most of their user interface logic in a web browser, communicating with a web server primarily using APIs (such as AngularJS + Node.js or React). To learn how to set up a Single-page web application, read [Register Single-Page Web Applications](/docs/get-started/auth0-overview/create-applications/single-page-web-apps).
  * **Native application**: Mobile or Desktop applications that run natively on a device (such as iOS or Android). To learn how to set up a native application, read [Register Native Applications](/docs/get-started/auth0-overview/create-applications/native-apps).
  * **Machine to machine (M2M) application**: Non-interactive applications, such as command-line tools, daemons, IoT devices, or services running on your backend. Typically, you use this option if you have a service that requires access to an API. To learn how to set up a native application, read [Register Machine-to-Machine Applications](/docs/get-started/auth0-overview/create-applications/machine-to-machine-apps).
* **Credential security**: According to the [OAuth 2.0 spec](https://tools.ietf.org/html/rfc6749#section-2.1), apps can be classified as either public or confidential; confidential apps can hold credentials securely, while public apps cannot. To learn more, read [Confidential and Public Applications](/docs/get-started/applications/confidential-and-public-applications).
* **Ownership**: Whether an app is classified as first- or third-party depends on app ownership and control. First-party apps are controlled by the same organization or person that owns the Auth0 domain. Third-party apps enable external parties or partners to securely access protected resources behind your API. To learn more, read [First-Party and Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/first-party-and-third-party-applications).

## Manage applications settings

You register applications in [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications/\{yourClientId}/settings). In addition to setting up applications in the Dashboard, you can also set up applications programmatically as described in the [OpenID Connect (OIDC) Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html)  specification.

You can set up a more complex configuration that allows users to log in differently for different apps. To learn more, read [Multi-Tenant Application Best Practices](/docs/get-started/auth0-overview/create-tenants/multi-tenant-apps-best-practices) and [Create Multiple Tenants](/docs/get-started/auth0-overview/create-tenants/create-multiple-tenants).

By default, Auth0 enables all connections associated with your tenant when you create a new application. To change this, [update application connections](/docs/get-started/applications/update-application-connections) in the **Application Settings** in the Dashboard.

## Monitor applications

You can [monitor apps](/docs/deploy-monitor/monitor/monitor-applications) and perform end-to-end testing using your own tests. Auth0 stores [log data](/docs/deploy-monitor/logs) including Dashboard administrator actions, successful and failed user authentications, and password change requests. You can use log streaming in [Auth0 Marketplace](https://marketplace.auth0.com/features/log-streaming) to export your log data and use tools like Sumo Logic, Splunk, or Mixpanel to analyze and store your log data.

## Remove applications

You can [remove an application](/docs/get-started/applications/remove-applications) using the Dashboard or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## Manage client secrets

A <Tooltip href="/docs/glossary?term=client+secret">client secret</Tooltip> is a secret known only to your application and the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip>. It protects your resources by only granting [tokens](/docs/secure/tokens) to authorized requestors.

Protect your client secrets and **never** include them in mobile or browser-based apps. If your client secret is ever compromised, you should [rotate to a new one](/docs/get-started/applications/rotate-client-secret) and update all authorized apps with the new client secret.

## Grant types

Auth0 provides many different authentication and authorization grant types or flows and allows you to indicate which grant types are appropriate based on the `grant_types` property of your Auth0-registered app. To learn more, read [Application Grant Types](/docs/get-started/applications/application-grant-types).

## Learn more

* [Application Settings](/docs/get-started/applications/application-settings)
* [Confidential and Public Applications](/docs/get-started/applications/confidential-and-public-applications)
* [First-Party and Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/first-party-and-third-party-applications)
* [Application Grant Types](/docs/get-started/applications/application-grant-types)
* [Subdomain URL Placeholders](/docs/get-started/applications/wildcards-for-subdomains)
* [Dynamic Application Registration](/docs/get-started/applications/dynamic-client-registration)


# Application Access to APIs: Client Grants
Source: https://auth0.com/docs/get-started/applications/application-access-to-apis-client-grants

Learn about Client Grants

In Auth0, you can control how applications access your APIs using [application API access policies](/docs/get-started/apis/api-access-policies-for-applications) and client grants.

A client grant provides fine-grained application access to an API. It associates:

* An API identified by its `audience` or unique identifier.
* An application identified by its `client_id`.
* A list of permissions such as scopes and/or `authorization_details_types` that the application is allowed to request for the specified audience.

To learn more about the list of attributes you can define in a client grant, read [Client grant attributes](#client-grant-attributes). To learn how to define and manage client grants, read [Configure client grants](#configure-client-grants).

## Application API access policies and client grants

When you configure an API's [application access policy](/docs/get-started/apis/api-access-policies-for-applications) to `require_client_grant`, only applications with a client grant defined can get an access token for the API. The client grant establishes the maximum permissions an application can request from the API by following the least privilege principle approach. As a result, Auth0 recommends using `require_client_grant` when configuring an API’s application access policy.

### Example: Social Media API

To illustrate how client grants follow the least privilege principle approach, say you have a Social Media API with the permissions: `read:posts`, `write:posts`, `read:friends`, and `delete:posts`. You create an application and define a client grant with the permissions: `read:posts` and `write:posts`.

This client grant now serves as a hard ceiling. Even though the Social Media API has other permissions, your application can never request or be granted `read:friends` or `delete:posts`.

## User access vs. client access

In user and client access, client grants define the final set of permissions that control an application’s access to an API. The client grant’s `subject_type` attribute determines the type of application access allowed for an API.

An application can have up to two client grants for a single API:

* When you set `subject_type` to `client`, you define its machine-to-machine permissions.
* When you set `subject_type` to `user`, you define its permissions to act on the user’s behalf.

The following table explains how client grants control application access to APIs based on the access type flow:

<table>
  <thead>
    <tr>
      <th><strong>Access type</strong></th>
      <th><strong>subject\_type attribute</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Client credential access (Machine-to-machine access)</td>
      <td>Set <code>subject\_type</code> to <code>client</code>.</td>
      <td>The client grant directly authorizes the application to access the API on its own behalf instead of the end user’s behalf. The permissions you define in the client grant are the ones the application is authorized to receive in the access token.</td>
    </tr>

    <tr>
      <td>User access</td>
      <td>Set <code>subject\_type</code> to <code>user</code>.</td>
      <td>The client grant defines the maximum permissions the application can request from the API. The final permissions in the access token issued to the application on the user’s behalf are the intersection of the permissions:<br /><ul><li>Requested by the application</li><li>Allowed by the client grant</li><li>Allowed by <a href="/docs/manage-users/access-control/rbac">Role-Based Access Control policies</a> for the user</li><li><a href="/docs/get-started/applications/confidential-and-public-applications/user-consent-and-third-party-applications">Consented to by the end user</a>, if applicable.</li></ul><br />To learn more about user access flows, read <a href="/docs/get-started/authentication-and-authorization-flow">Authentication and Authorization Flows</a>. User access flows do not include the Client Credentials Flow.</td>
    </tr>
  </tbody>
</table>

<Callout icon="file-lines">
  You can modify the final scopes granted by the authorization server to the application or user using [Actions](/docs/customize/actions).
</Callout>

## Client grant attributes

A client grant has several attributes that you can define to configure application access to APIs using the Auth0 Management API:

<table>
  <thead>
    <tr>
      <th><strong>Attribute</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>id</code></td>
      <td>Unique identifier of the client grant.</td>
    </tr>

    <tr>
      <td><code>audience</code></td>
      <td>Unique identifier of the API the client grant is for.</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>The unique ID of the application that is being granted access.</td>
    </tr>

    <tr>
      <td><code>scopes</code></td>
      <td>An array of strings representing the permissions the application can request.</td>
    </tr>

    <tr>
      <td><code>authorization\_details\_types</code></td>
      <td>An array of strings representing rich authorization data types that the application can request. This attribute can only be specified for user access flows.</td>
    </tr>

    <tr>
      <td><code>subject\_type</code></td>
      <td>The type of application access the client grant allows for:<br /><ul><li><code>user</code>: used for user access, which corresponds to all flows that generate a token associated with an end user.</li><li><code>client</code>: used for machine access, which corresponds to the Client Credentials Flow.</li></ul></td>
    </tr>

    <tr>
      <td><code>allow\_all\_scopes</code></td>
      <td>Boolean. Indicates if all scopes defined on the API are allowed for the application. Future defined scopes, for the API, are automatically permitted. </td>
    </tr>

    <tr>
      <td><code>organization\_usage</code></td>
      <td>Determines how the application may use organizations when accessing the API via the Client Credentials Flow. Possible values are: <code>deny</code>, <code>allow</code>, or <code>require</code>.<br /><br />To learn more about the Organization settings, read <a href="/docs/manage-users/organizations/organizations-for-m2m-applications/configure-your-application-for-m2m-access#define-organization-behavior">Organizations for M2M Applications: Define Organization Behavior</a>.</td>
    </tr>

    <tr>
      <td><code>allow\_any\_organization</code></td>
      <td>Determines whether the application can access any organization when using the Client Credentials Flow.<br /><br />To learn more about the Organization settings, read <a href="/docs/manage-users/organizations/organizations-for-m2m-applications/configure-your-application-for-m2m-access#define-organization-behavior">Organizations for M2M Applications: Define Organization Behavior</a>.</td>
    </tr>
  </tbody>
</table>

## Configure client grants

You can configure client grants using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

### Auth0 Dashboard

To configure client grants using the Auth0 Dashboard:

1. Navigate to [Dashboard >  Applications](https://manage.auth0.com/#/applications).
2. Select the **Application** you want to configure.
3. Select the **APIs** tab.
4. Select **Edit** to authorize **User Access**, **Client Access**, or both.

<Callout icon="file-lines">
  For application-level authorization settings to take effect, you must set API Access Policy to Allow via client-grant. To learn more read, [API Access Policies for Applications](/docs/get-started/apis/api-access-policies-for-applications).
</Callout>

* Configure the **User Access Authorization** to **Unauthorized**, **Authorized**, or **All**.
  * **Unauthorized**: No permission allowed.
  * **Authorized**: Select desired permissions.
  * **All**: Include all existing and future permissions.
* Configure the **Client Credential Access Authorization** to **Unauthorized**, **Authorized**, or **All**.
  * **Unauthorized**: No permission allowed.
  * **Authorized**: Select desired permissions.
  * **All**: Include all existing and future permissions.

5. Select **Save** to save the **Application’s API** settings.

### Auth0 Management API

To configure client grants, use the `/client-grants` endpoint.

#### Create client grant

To create a new client grant, make a [`POST`](https://auth0.com/docs/api/management/v2/client-grants/post-client-grants) request to the `/client-grants` endpoint.

The following code sample creates a client grant for an application to access the `https://api.my-service.com` API. The `subject_type` is `user`, which means the client grant is for user access, and allows the application to request the `read:item` scope and the `payment` authorization details type.

<AuthCodeBlock />

#### Update client grant

To update an existing client grant, make a [`PATCH`](https://auth0.com/docs/api/management/v2/client-grants/patch-client-grants-by-id) request to `/client-grants/{id}`.

The following code sample updates an existing client grant to expand its permissions. The application can now also request the `update:item` scope and an additional `credits_transfer` authorization details type.

<AuthCodeBlock />

#### Delete client grant

To delete a client grant, make a [`DELETE`](https://auth0.com/docs/api/management/v2/client-grants/delete-client-grants-by-id) request to `/client-grants/{id}`.

The following code sample removes the client grant which revokes the application's access to the API:

<AuthCodeBlock />

#### Retrieve client grants

You can also query and paginate through the `client-grants` collections by using parameters like `client_id`, `audience`, or `subject_type`.

The following code sample retrieves all client grants that allow for user access to the `https://api.my-service.com` API.

<AuthCodeBlock />

## Learn more

* [API Access Policies for Applications](/docs/get-started/apis/api-access-policies-for-applications)
* [Application Grant Types](/docs/get-started/applications/application-grant-types)


# Application Grant Types
Source: https://auth0.com/docs/get-started/applications/application-grant-types

Describes grant types and how they relate to applications.

Application grant types (or flows) are methods through which applications can gain [Access Tokens](/docs/secure/tokens/access-tokens) and by which you grant limited access to your resources to another entity without exposing credentials. The [OAuth 2.0 protocol](/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use) supports several types of grants, which allow different types of access.

Based on the needs of your application, some grant types are more appropriate than others. Auth0 provides many different authentication and <Tooltip href="/docs/glossary?term=authorization+flows">authorization flows</Tooltip> and allows you to indicate which grant types are appropriate based on the `grant_types` property of your application.

For example, if you want to secure a mobile application, the [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce) is the most appropriate.

Alternatively, if you want to secure a client-side application, such as a single-page application (SPA), and aren't passing tokens between servers, the [Implicit Flow with Form Post](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post) is the most appropriate.

Various grant types are valid when registering applications. These can be divided into the following categories:

* **Specification-conforming grants**: Grants defined by and conforming to external specifications, such as <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC).
* **Auth0 extension grants**: Auth0-specific grants that conform to the [OAuth extension mechanism](https://tools.ietf.org/html/rfc6749#section-4.5) to support additional clients or to provide a bridge between <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> and other trust frameworks.
* **Auth0 legacy grants**: Traditional grant types supported for legacy customers only. If you are a legacy customer, we highly recommend moving to a more secure alternative.

## Available grant types

### Specification-conforming grants

<table>
  <thead>
    <tr>
      <th>Grant Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>implicit</code></td>
      <td><a href="/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post" title="Implicit Flow with Form Post">Implicit Grant</a></td>
    </tr>

    <tr>
      <td><code>authorization\_code</code></td>
      <td><a href="/docs/get-started/authentication-and-authorization-flow/authorization-code-flow" title="Authorization Code Flow">Authorization Code Grant</a></td>
    </tr>

    <tr>
      <td><code>client\_credentials</code></td>
      <td><a href="/docs/get-started/authentication-and-authorization-flow/client-credentials-flow" title="Client Credentials Flow">Client Credentials Grant</a></td>
    </tr>

    <tr>
      <td><code>password</code></td>
      <td><a href="/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow" title="Resource Owner Password Flow">Resource Owner Password Grant</a></td>
    </tr>

    <tr>
      <td><code>refresh\_token</code></td>
      <td><a href="/docs/secure/tokens/refresh-tokens/use-refresh-tokens" title="Use Refresh Tokens">Use Refresh Tokens</a></td>
    </tr>

    <tr>
      <td><code>urn:ietf:params:oauth:grant-type:device\_code</code></td>
      <td><a href="/docs/get-started/authentication-and-authorization-flow/device-authorization-flow" title="Device Authorization Flow">Device Authorization Grant</a></td>
    </tr>
  </tbody>
</table>

### Auth0 extension grants

| **Grant Type**                                            | **Description**                                                                                                            |
| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **`http://auth0.com/oauth/grant-type/password-realm`**    | Use an extension grant similar to the Resource Owner Password Grant that includes the ability to indicate a specific realm |
| **`http://auth0.com/oauth/grant-type/mfa-oob`**           | Multi-factor Authentication OOB Grant Request                                                                              |
| **`http://auth0.com/oauth/grant-type/mfa-otp`**           | Multi-factor Authentication OTP Grant Request                                                                              |
| **`http://auth0.com/oauth/grant-type/mfa-recovery-code`** | Multi-factor Authentication Recovery Grant Request                                                                         |
| **`http://auth0.com/oauth/grant-type/passwordless/otp`**  | Embedded Passwordless Login Grant Request                                                                                  |

### Auth0 legacy grants

Legacy grants include:

* `http://auth0.com/oauth/legacy/grant-type/ro`
* `http://auth0.com/oauth/legacy/grant-type/ro/jwt-bearer`
* `http://auth0.com/oauth/legacy/grant-type/delegation/refresh_token`
* `http://auth0.com/oauth/legacy/grant-type/delegation/id_token`
* `http://auth0.com/oauth/legacy/grant-type/access_token`

Legacy grant types are traditional grant types supported for legacy customers only. If you are a legacy customer, we highly recommend moving to a more secure alternative.

As of 08 June 2017, all applications were given a `grant_types` property that must be populated. To avoid changes in functionality for Auth0 customers at that time, we populated the `grant_types` property for all existing applications with all Auth0 legacy, Auth0 extension, and specification-conforming grant types.

At this time, new Auth0 customers were no longer able to add legacy grant types to their applications. Legacy grant types are only available for previous customers while they migrate to new flows, to avoid breaking changes. If you were a customer prior to 8 June 2017, you can [enable a legacy grant type](/docs/get-started/applications/update-grant-types) using either the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

If you're currently using a legacy grant type, refer to the chart below to see which of the secure alternatives you should use instead. For example, if you're implementing <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> Authentication,

use [Universal Login](/docs/authenticate/login/auth0-universal-login) instead of the `oauth/ro` endpoint.

## Grant type mapping

When registered, applications have access to different grant types based on their application type, specifically whether the application is confidential or public. Additionally, trusted first-party applications have access to additional grant types.

### Public applications

When a Native Application or Single-Page Application (SPA) is registered in the Dashboard, it's automatically flagged as a public application, which is indicated by the `token_endpoint_auth_method` flag being set to `none`. By default, Auth0 creates public applications with the following `grant_types` enabled:

* `implicit`
* `authorization_code`
* `refresh_token`

Native Apps can also use the `device_code` grant type.

Public applications cannot use the `client_credentials` grant type. To use this grant type, you must configure the application to be confidential rather than public. Use the Auth0 Management API [Update a client](https://auth0.com/docs/api/management/v2#!/Clients/patch_clients_by_id) endpoint to set the `token_endpoint_auth_method` to `client_secret_post,` `client_secret_basic`, or `private_key_jwt`. To learn more, read [Application Credentials](/docs/secure/application-credentials).

### Confidential applications

When a Regular Web Application or Machine-to-Machine (M2M) Application is registered in the Auth0 Dashboard, it's automatically flagged as a confidential application, which is indicated by the `token_endpoint_auth_method` flag being set to anything except `none`. By default, Auth0 creates confidential applications with the following `grant_types` enabled:

* `implicit`
* `authorization_code`
* `refresh_token`
* `client_credentials`

### Trusted first-party applications

Trusted first-party applications have the same `grant_types` enabled as confidential applications, along with the following:

* `password`
* `http://auth0.com/oauth/grant-type/password-realm`
* `http://auth0.com/oauth/grant-type/mfa-oob`
* `http://auth0.com/oauth/grant-type/mfa-otp`
* `http://auth0.com/oauth/grant-type/mfa-recovery-code`

If you are using the Dashboard to enable or disable these grant types, be aware that all the Password and <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> grant types are enabled when you add the `Password` or `MFA` grant type to your application. You cannot select them individually.

## Learn more

* [Confidential and Public Applications](/docs/get-started/applications/confidential-and-public-applications)
* [Enable Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/enable-third-party-applications)
* [First-Party and Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/first-party-and-third-party-applications)
* [Subdomain URL Placeholders](/docs/get-started/applications/wildcards-for-subdomains)


# Application Settings
Source: https://auth0.com/docs/get-started/applications/application-settings

Describe the settings related to applications available in the Auth0 Dashboard.

On the [Applications](https://manage.auth0.com/#/applications) page of the Dashboard, locate your application in the list, and click its name to view the available settings.

<Frame>
  <img alt="Dashboard Applications List" />
</Frame>

## Basic settings

When you edit an existing application's settings or create a new application, you enter information about the application in the **Settings** view.

### Basic Information

<Frame>
  <img alt="Dashboard Applications Application Settings Tab Basic Information" />
</Frame>

* **Name**: The name of your application. Editable, and will be seen in the portal, emails, logs, and so on.
* **Domain**: Your Auth0 tenant name. You choose this when you create a new Auth0 tenant, and it cannot be changed. If you need a different domain, you must register for a new tenant by selecting **+ Create Tenant** in the top-right menu.
* **<Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>**: The unique identifier for your application. You will use this when configuring authentication with Auth0. Generated by the system when you create a new application and cannot be modified.
* **<Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip>**: A string used to sign and validate <Tooltip href="/docs/glossary?term=ID+Tokens">ID Tokens</Tooltip> for authentication flows and to gain access to select Auth0 API endpoints. By default, the value is hidden, so check the **Reveal Client Secret** box to see it. While the Client ID is considered public information, the Client Secret **must be kept confidential**. If anyone can access your Client Secret, they can issue tokens and access resources they shouldn't be able to access.
* **Description**: A free-text description of the Application's purpose. Maximum of 140 characters.

### Application Properties

<Frame>
  <img alt="Dashboard Applications Application Settings Tab Application Properties" />
</Frame>

* **Application Logo**: The URL of a logo (recommended size: 150x150 pixels) to display for the application. Appears in several areas, including the list of applications in the Dashboard and customized consent forms. If none is set the default badge for this type of application will be shown.
* **Application Type**: The Auth0 application type determines which settings you can configure using the Dashboard. (Not editable for M2M apps. Sometimes disabled for other Auth0 application types if the selected grant types are only allowed for the currently selected application type.) Use the drop-down to select from the following types:

  * [Machine to Machine](/docs/get-started/auth0-overview/create-applications/machine-to-machine-apps): Non-interactive applications, such as command-line tools, daemons, IoT devices, or services running on your backend. Typically, you use this option if you have a service that requires access to an API.
  * [Native App](/docs/get-started/auth0-overview/create-applications/native-apps): Mobile or Desktop applications that run natively in a device (such as iOS or Android).
  * [Regular Web App](/docs/get-started/auth0-overview/create-applications/regular-web-apps): Traditional web apps that perform most of their application logic on the server (such as Express.js or ASP.NET).
  * [Single Page App](/docs/get-started/auth0-overview/create-applications/single-page-web-apps): JavaScript apps that perform most of their user interface logic in a web browser, communicating with a web server primarily using APIs (such as AngularJS + Node.js or React).

### Application URIs

<Frame>
  <img alt="Dashboard Applications Application Settings Application URIs" />
</Frame>

* **Application Login URI**: In some scenarios, Auth0 will need your application to redirect to your application's login page. This URI needs to point to a route in your application that redirects to your tenant's `/authorize` [endpoint](https://auth0.com/docs/api/authentication#authorize-application). It would usually take the form of `https://myapp.org/login`. To learn more, read [Configure Default Login Routes](/docs/authenticate/login/auth0-universal-login/configure-default-login-routes).
* **Allowed Callback URLs**: Set of URLs to which Auth0 is allowed to redirect users after they authenticate. You can specify multiple valid URLs by comma-separating them (typically, to handle different environments like QA or testing). For production environments, verify that the URLs do not point to localhost. You can use the following placeholders in this field:
  * [**Wildcards**](/docs/get-started/applications/wildcards-for-subdomains#wildcard-url-placeholders): Use `*` for subdomains (`*.google.com`) *Not recommended for production environments.*
  * [**Organization placeholders**](/docs/get-started/applications/wildcards-for-subdomains#organization-url-placeholders): Use `{organization_name}` to dynamically specify a registered organization's name (for example, `https://{organization_name}.example.com`).
  * [**Custom Domain placeholders**](/docs/get-started/applications/wildcards-for-subdomains#custom-domain-url-placeholders): Use `{custom.domain.metadata.KEY}` to dynamically populate the URL based on metadata from the custom domain used in the request (for example, `https://{custom_domain.metadata.public_app_url}/callback`).

<Callout icon="file-lines">
  The first URL listed in this field is taken as the default callback URL when the corresponding protocol flow does not explicitly specify one. This applies specifically to SAML, WS-Fed, and SAML IdP-initiated SSO flows.
</Callout>

Do not use wildcard placeholders or localhost URLs in your application callbacks or allowed origins fields. Using redirect URLs with wildcard placeholders can make your application vulnerable to attacks. To learn more, read [Unvalidated Redirects and Forwards Cheat Sheet on owasp.org](https://www.owasp.org/index.php/Unvalidated_Redirects_and_Forwards_Cheat_Sheet). Instead, URLs with the `{organization_name}` placeholder should be preferred, where relevant. To learn more, read [Subdomain URL Placeholders](/docs/get-started/applications/wildcards-for-subdomains).

* **Allowed Logout URLs**: After a user logs out from Auth0, you can redirect them with the `returnTo` query parameter. The URL that you use in `returnTo` must be listed here. You can specify multiple valid URLs by comma-separating them. For production environments, verify that the URLs do not point to localhost.
  * [**Wildcards**](/docs/get-started/applications/wildcards-for-subdomains#wildcard-url-placeholders): Use `*` for subdomains (`*.google.com`) *Not recommended for production environments.*
  * [**Custom Domain placeholders**](/docs/get-started/applications/wildcards-for-subdomains#custom-domain-url-placeholders): Use `{custom.domain.metadata.KEY}` to dynamically populate the URL based on metadata from the custom domain used in the request (for example, `https://{custom_domain.metadata.public_app_url}/callback`).
* **Allowed Web Origins**: List of URLs from where an authorization request using [Cross-Origin Authentication](/docs/authenticate/login/cross-origin-authentication), [Device Flow](/docs/get-started/authentication-and-authorization-flow/device-authorization-flow), and `web_message` as the response mode can originate from. You can specify multiple valid URLs by comma-separating them. For production environments, verify that the URLs do not point to localhost. Paths, query strings, and hash information are not taken into account when validating these URLs (and may, in fact, cause the match to fail). You can provide up to 100 URLs in the **Allowed Web Origins** field.
  * [**Wildcards**](/docs/get-started/applications/wildcards-for-subdomains#wildcard-url-placeholders): Use `*` for subdomains (`*.google.com`) *Not recommended for production environments.*
  * [**Custom Domain placeholders**](/docs/get-started/applications/wildcards-for-subdomains#custom-domain-url-placeholders): Use `{custom.domain.metadata.KEY`} to dynamically populate the URL based on metadata from the custom domain used in the request (for example, `https://{custom_domain.metadata.public_app_url}/callback`).
* **Allowed Origins (CORS)**: List of URLs that are allowed to make Cross-Origin Resource Sharing (CORS) requests to Auth0.
  * [**Custom Domain placeholders**](/docs/get-started/applications/wildcards-for-subdomains#custom-domain-url-placeholders): Use `{custom.domain.metadata.KEY}` to dynamically populate the URL based on metadata from the custom domain used in the request (for example, `https://{custom_domain.metadata.public_app_url}/callback`).

<Warning>
  If you configure your Application URLs exclusively using Custom Domain placeholders, authentication requests made via your tenant's canonical domain (for example, [https://your-tenant.us.auth0.com](https://your-tenant.us.auth0.com)) will fail.

  This occurs because the canonical domain does not have the custom metadata required to resolve the placeholder. Ensure your application uses the specific Custom Domain for authentication, or provide a static fallback URL if canonical domain usage is required.
</Warning>

### ID Token

In the **ID Token** section, enter the **ID Token Expiration** (in seconds) which is the amount of time before the Auth0 `id_token` expires. The default value is 36000 seconds which is 10 hours.

<Callout icon="file-lines">
  **Use Auth0 instead of the IdP to do Single Sign-on**: If enabled, this setting prevents Auth0 from redirecting authenticated users with valid sessions to the identity provider (such as Facebook or ADFS). **Legacy tenants only.**
</Callout>

### Refresh Token Rotation

In the **<Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip> Rotation** section, enable or disable rotation. When enabled, as a result of exchanging a refresh token, a new refresh token will be issued and the existing token will be invalidated. This allows for automatic detection of token reuse if the token is leaked. In addition, enter the **Rotation Overlap Period** (in seconds). This interval is the allowable leeway time that the same `refresh_token` can be used to request an `access_token` without triggering automatic reuse detection. To learn more, read [Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation).

<Frame>
  <img alt="Dashboard Applications Applications Settings Tab Refresh Token Rotation" />
</Frame>

### Refresh Token Expiration

In the **Refresh Token Expiration** section, enable or disable absolute and inactivity expiration and set the lifetimes (in seconds) for each. To learn more, read [Configure Refresh Token Expiration](/docs/secure/tokens/refresh-tokens/configure-refresh-token-expiration).

<Frame>
  <img alt="Dashboard Applications Applications Settings Tab Refresh Token Expiration" />
</Frame>

## Advanced settings

The **Advanced Settings** section allows you to:

* Manage or add application metadata, device, <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip>, and WS-Federation settings
* Obtain certificates and <Tooltip href="/docs/glossary?term=Token+endpoint">Token endpoint</Tooltip> information
* Set the grant type(s) for the application

### Application Metadata

Application metadata are custom string keys and values (each of which has a character maximum of 255), set on a per-application basis. Metadata is exposed in the application object as `client_metadata`, and in rules as `context.clientMetadata`. You can create up to 10 sets of metadata.

<Frame>
  <img alt="Dashboard Applications Applications Settings Tab Advanced Settings Application Metadata Tab" />
</Frame>

### Device Settings

If you're developing a mobile application, enter the necessary iOS/Android parameters.

* When developing iOS apps, you'll provide your **Team ID** and **App ID**. To learn more, read [Enable Universal Links Support in Apple Xcode](/docs/get-started/applications/enable-universal-links-support-in-apple-xcode).
* When developing Android apps, you'll provide your **App Package Name** and your **Key Hashes**. To learn more, read [Enable Android App Links Support](/docs/get-started/applications/enable-android-app-links-support).

<Frame>
  <img alt="Dashboard Applications Application Settings Tab Advanced Settings Device Settings Tab" />
</Frame>

### OAuth

<Frame>
  <img alt="Dashboard Applications Application Settings Tab Advanced Settings OAuth Tab" />
</Frame>

* By default, all apps/APIs can make a delegation request, but if you want to explicitly grant permissions to selected apps/APIs, you can do so in **Allowed Apps/APIs**.
* For customers using the Highly Regulated Identity add-on, use the **Compliance Enforcement Level** setting to set your level of compliance. For more information, review [Configure FAPI Compliance](/docs/get-started/applications/configure-fapi-compliance).
* **Non-Verifiable Callback URI End-User Confirmation**: Use this setting to control whether the user is prompted to confirm login when a Non-verifiable URI is used as callback. Auth0 recommends that you do not skip end-user confirmation in these cases. This setting takes precedence over the tenant setting with the same name. To learn more, read [Measures Against Application Impersonation](/docs/secure/security-guidance/measures-against-app-impersonation.mdx).
* Set the algorithm used ([**HS256**](https://en.wikipedia.org/wiki/Symmetric-key_algorithm) or [**RS256**](https://en.wikipedia.org/wiki/Public-key_cryptography)) for signing your <Tooltip href="/docs/glossary?term=JSON+web+tokens">JSON web tokens</Tooltip>. To learn more, read [JSON Web Token Signing Algorithms](/docs/get-started/applications/signing-algorithms). When selecting `RS256` (recommended), the token will be signed with your tenant's private key.
* Toggle the **Trust Token Endpoint IP Header** setting; if this is enabled, the `auth0-forwarded-for` is set as trusted and used as a source of end user IP information for protection against brute-force attacks on the Token endpoint. This setting is only available for Regular Web Apps and M2M Apps.
* Toggle the switch to indicate if your application is **OIDC Conformant** or not. Applications flagged as OIDC Conformant will strictly follow the OIDC specification.

For troubleshooting help, read [Troubleshoot Invalid Token Errors](/docs/troubleshoot/basic-issues/invalid-token-errors).

### Grant Types

Select grant types to enable or disable for your application. Available grant types are based on the application type.

<Frame>
  <img alt="Dashboard Applications Application Settings Tab Advanced Settings Grant Types tab" />
</Frame>

### WS-Federation

Manage or add WS-Federation settings.

<Frame>
  <img alt="Dashboard Applications Application Settings Tab Advanced WS-Federation tab" />
</Frame>

### Certificates

Manage or add the signing certificate, and its fingerprint and thumbprint.

<Frame>
  <img alt="Dashboard Applications Advanced Settings Certificates tab" />
</Frame>

### Endpoints

View endpoint information for OAuth, <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip>, and <Tooltip href="/docs/glossary?term=WS-Fed">WS-Fed</Tooltip>, such as Authorization and Metadata URLs.

## Learn more

* [Create Applications](/docs/get-started/auth0-overview/create-applications)
* [Remove Applications](/docs/get-started/applications/remove-applications)
* [Configure Applications with OIDC Discovery](/docs/get-started/applications/configure-applications-with-oidc-discovery)
* [Confidential and Public Applications](/docs/get-started/applications/confidential-and-public-applications)
* [First-Party and Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/first-party-and-third-party-applications)
* [Check Error Messages](/docs/troubleshoot/basic-issues/check-error-messages)


# Change Application Signing Algorithms
Source: https://auth0.com/docs/get-started/applications/change-application-signing-algorithms

Describes how to change an application's signing algorithm using the Auth0 Dashboard.

You can change your application's <Tooltip href="/docs/glossary?term=signing+algorithm">signing algorithm</Tooltip> using the Dashboard.

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and select the name of the application to view.

   <Frame>
     <img alt="Dashboard Applications List" />
   </Frame>
2. Scroll to the bottom of the **Settings** tab and select **Show Advanced Settings**.
3. Go to the **OAuth** tab.

   <Frame>
     <img alt="Dashboard Applications Application Settings Tab Advanced Settings OAuth Tab" />
   </Frame>
4. Locate **JsonWebToken Signature Algorithm** and select the appropriate signing algorithm for the application.
5. Click **Save Changes**.

## Learn more

* [Signing Keys](/docs/get-started/tenant-settings/signing-keys)
* [View Signing Certificates](/docs/get-started/tenant-settings/signing-keys/view-signing-certificates)
* [Rotate Signing Keys](/docs/get-started/tenant-settings/signing-keys/rotate-signing-keys)
* [Revoke Signing Keys](/docs/get-started/tenant-settings/signing-keys/revoke-signing-keys)
* [Signing Algorithms](/docs/get-started/applications/signing-algorithms)


# Confidential and Public Applications
Source: https://auth0.com/docs/get-started/applications/confidential-and-public-applications

Describes the difference between confidential and public application types.

According to the [OAuth 2.0 specification](https://tools.ietf.org/html/rfc6749#section-2.1), applications can be classified as either confidential or public. The main difference relates to whether or not the application is able to hold credentials (such as a <Tooltip href="/docs/glossary?term=client+ID">client ID</Tooltip> and secret) securely. This affects the type of authentication the applications can use.

When you create an application using the Dashboard, Auth0 will ask you what Auth0 application type you want to assign to the new application and use that information to determine whether the application is confidential or public.

To learn more, read [Check if Application is Confidential or Public](/docs/get-started/applications/confidential-and-public-applications/view-application-type).

## Confidential applications

Confidential applications can hold credentials in a secure way without exposing them to unauthorized parties. They require a trusted backend server to store the secret(s).

### Grant types

Confidential applications use a trusted backend server and can use grant types that require specifying their Client ID and <Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip> (or alternative registered credentials) for authentication when calling the Auth0 Authentication API [Get Token](https://auth0.com/docs/api/authentication#get-token) endpoint. Confidential applications can use Client Secret Post, Client Secret Basic, or [Private Key JWT](/docs/get-started/authentication-and-authorization-flow/authenticate-with-private-key-jwt) authentication methods.

These are considered confidential applications:

* A web application with a secure backend that uses the [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow), [Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow), or <Tooltip href="/docs/glossary?term=Resource+Owner">Resource Owner</Tooltip> Password Flow with realm support
* A machine-to-machine (M2M) application that uses the [Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow)

### ID tokens

Because confidential applications are capable of holding secrets, you can have <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip> issued to them that have signed in one of two ways:

* Symmetrically, using their client secret (`HS256`)
* Asymmetrically, using a private key (`RS256`)

## Public applications

Public applications **cannot** hold credentials securely.

### Grant types

Public applications can only use grant types that do not require the use of their client secret. They can't send a client secret because they can't maintain the confidentiality of the credentials required.

These are public applications:

* A native desktop or mobile application that uses the [Authorization Code Flow with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce)
* A JavaScript-based client-side web application (such as a single-page app) that uses the [Implicit Flow](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post) grant

### ID tokens

Because public applications are unable to hold secrets, [ID tokens](/docs/secure/tokens/id-tokens) issued to them must be:

* Signed asymmetrically using a private key (`RS256`)
* Verified using the public key corresponding to the private key used to sign the token

## Learn more

* [Check if Application is Confidential or Public](/docs/get-started/applications/confidential-and-public-applications/view-application-type)
* [First-Party and Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/first-party-and-third-party-applications)
* [User Consent and Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/user-consent-and-third-party-applications)


# Enable Third-Party Applications
Source: https://auth0.com/docs/get-started/applications/confidential-and-public-applications/enable-third-party-applications

Describes how to enable third-party applications for your tenant.

You can enable third-party applications for your tenant. See [First-Party and Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/first-party-and-third-party-applications) for details on the differences between the two types of applications.

1. [Update your application's ownership to third-party](/docs/get-started/applications/confidential-and-public-applications/update-application-ownership) in Auth0.

   By default, applications registered in Auth0 are first-party applications. If you want your application to be a third-party application, you must update its ownership.
2. [Promote the connections you will use with third-party applications to domain level](/docs/authenticate/identity-providers/promote-connections-to-domain-level) in Auth0.

   Third-party applications can only authenticate users from [connections](/docs/authenticate/identity-providers) flagged as domain-level connections. Domain-level connections can be enabled for selected first-party applications while also being open to all third-party application users for authentication.
3. Update your application's login page. If you use [Lock](/docs/libraries/lock) in the [Universal Login Page](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/classic-experience), you must also:

   1. Upgrade to Lock version 11 or later.
   2. Set the `__useTenantInfo: config.isThirdPartyClient` flag when instantiating Lock.
   3. For Private Cloud users only: Set the [`configurationBaseUrl` option](/docs/libraries/lock/lock-configuration#configurationbaseurl-string-) to `https://{config.auth0Domain}/` when instantiating Lock.

## Access token current\_user\_\* scopes

Neither first- nor third-party applications can use <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip> to invoke <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> endpoints. Instead, they should get <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> with the following `current_user_*` scopes required by each endpoint:

<table>
  <thead>
    <tr>
      <th>Scope</th>
      <th>Endpoint</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>read:current\_user</code></td>
      <td>List or search users</td>
    </tr>

    <tr>
      <td />

      <td>Get a user</td>
    </tr>

    <tr>
      <td />

      <td>Get user MFA enrollments</td>
    </tr>

    <tr>
      <td><code>update:current\_user\_metadata</code></td>
      <td>Update a user</td>
    </tr>

    <tr>
      <td />

      <td>Delete a user's multi-factor provider</td>
    </tr>

    <tr>
      <td><code>create:current\_user\_device\_credentials</code></td>
      <td>Create a device public key</td>
    </tr>

    <tr>
      <td><code>delete:current\_user\_device\_credentials</code></td>
      <td>Delete a device credential</td>
    </tr>

    <tr>
      <td><code>update:current\_user\_identities</code></td>
      <td>Link a user account</td>
    </tr>

    <tr>
      <td />

      <td>Unlink a user identity</td>
    </tr>
  </tbody>
</table>

## Script example

```html lines expandable theme={null}
<script src="https://cdn.auth0.com/js/lock/11.x.y/lock.min.js"></script>
...
<script>
  // Decode utf8 characters properly
  var config = JSON.parse(decodeURIComponent(escape(window.atob('@@config@@'))));

  var connection = config.connection;
  var prompt = config.prompt;
  var languageDictionary;
  var language;
  if (config.dict && config.dict.signin && config.dict.signin.title) {
    languageDictionary = { title: config.dict.signin.title };
  } else if (typeof config.dict === 'string') {
    language = config.dict;
  }

  var lock = new Auth0Lock(config.clientID, config.auth0Domain, {
    auth: {
      redirectUrl: config.callbackURL,
      responseType: config.callbackOnLocationHash ? 'token' : 'code',
      params: config.internalOptions
    },
    assetsUrl:  config.assetsUrl,
    allowedConnections: connection ? [connection] : null,
    configurationBaseUrl: 'https://' + config.auth0Domain + '/', // for PSaaS only
    rememberLastLogin: !prompt,
    language: language,
    languageDictionary: languageDictionary,
    closable: false,
    __useTenantInfo: config.isThirdPartyClient // required for all Tenants
  });

  lock.show();
</script>
```

## Learn more

* [First-Party and Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/first-party-and-third-party-applications)
* [User Consent and Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/user-consent-and-third-party-applications)
* [Promote Connections to Domain Level](/docs/authenticate/identity-providers/promote-connections-to-domain-level)


# First-Party and Third-Party Applications
Source: https://auth0.com/docs/get-started/applications/confidential-and-public-applications/first-party-and-third-party-applications

Describes the difference between confidential and public application types.

Applications can be classified as either first-party or third-party, which refers to the ownership of the application. The main difference relates to who has administrative access to your Auth0 domain.

## First-party applications

First-party applications are those controlled by the same organization or person who owns the Auth0 domain. For example, let's say you created both a Contoso API and an application that logs into `contoso.com` and consumes the Contoso API. You would register both the API and application under the same Auth0 domain, and the application would be a first-party application. By default, all applications created via the [Auth0 Dashboard](https://manage.auth0.com/#/applications) are first-party applications.

## Third-party applications

Third-party applications are controlled by someone who most likely should not have administrative access to your Auth0 domain. Third-party applications enable external parties or partners to securely access protected resources behind your API. An example of this is with Facebook, let's say you created an application to get a <Tooltip href="/docs/glossary?term=client+ID">client ID</Tooltip> and secret to integrate with your service. That application is considered third-party because it is not owned by Facebook but a third-party that wants to integrate with Facebook APIs and services.

All applications created through [Dynamic Client Registration](/docs/get-started/applications/dynamic-client-registration) will be third-party. Third-party applications cannot be created using the Dashboard, but must be created through the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> by setting `is_first_party` to `false`.

Third-party applications have the following unique characteristics:

* **User Consent**: You must require user consent when consuming APIs because anyone can create an application. Requiring the user to provide consent improves security.
* **<Tooltip href="/docs/glossary?term=ID+Tokens">ID Tokens</Tooltip>**: [ID tokens](/docs/secure/tokens/id-tokens) generated for third-party applications hold only minimum user profile information.
* **Connections**: You can only use tenant-level connections or domain connections. For more information, see [Enable Third-party Applications](/docs/get-started/applications/confidential-and-public-applications/enable-third-party-applications).

## Learn more

* [Update Application Ownership](/docs/get-started/applications/confidential-and-public-applications/update-application-ownership)
* [Check if Application is Confidential or Public](/docs/get-started/applications/confidential-and-public-applications/view-application-type)
* [User Consent and Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/user-consent-and-third-party-applications)


# Update Application Ownership
Source: https://auth0.com/docs/get-started/applications/confidential-and-public-applications/update-application-ownership

Learn how to update application ownership using the Auth0 Management API. This will let you specify whether an application is registered with Auth0 as a first-party or third-party application.

You can use Auth0's <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to update application ownership, which allows you to specify whether an application is registered with Auth0 as a first-party or third-party application.

Make a `PATCH` call to the [Update a Client endpoint](https://auth0.com/docs/api/management/v2#!/Clients/patch_clients_by_id). Be sure to replace `{YOUR_CLIENT_ID}`, `{YOUR_MANAGEMENT_API_ACCESS_TOKEN}`, and `{OWNERSHIP_BOOLEN}` placeholder values with your <Tooltip href="/docs/glossary?term=client+ID">client ID</Tooltip>, Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, and boolean representing the application's ownership, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{YOUR_DOMAIN}/api/v2/clients/{YOUR_CLIENT_ID}' \
    --header 'authorization: Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "is_first_party": "{OWNERSHIP_BOOLEN}" }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{YOUR_DOMAIN}/api/v2/clients/{YOUR_CLIENT_ID}");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("application/json", "{ "is_first_party": "{OWNERSHIP_BOOLEAN}" }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{YOUR_DOMAIN}/api/v2/clients/{YOUR_CLIENT_ID}"

  	payload := strings.NewReader("{ "is_first_party": "{OWNERSHIP_BOOLEAN}" }")

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

  	req.Header.Add("content-type", "application/json")
  	req.Header.Add("authorization", "Bearer {YOUR_MANAGEMENT_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))

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.patch("https://{YOUR_DOMAIN}/api/v2/clients/{YOUR_CLIENT_ID}")
    .header("content-type", "application/json")
    .header("authorization", "Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}")
    .header("cache-control", "no-cache")
    .body("{ "is_first_party": "{OWNERSHIP_BOOLEAN}" }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{YOUR_DOMAIN}/api/v2/clients/{YOUR_CLIENT_ID}',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}',
      'cache-control': 'no-cache'
    },
    data: {is_first_party: '{OWNERSHIP_BOOLEAN}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{YOUR_DOMAIN}/api/v2/clients/{YOUR_CLIENT_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 => "{ "is_first_party": "{OWNERSHIP_BOOLEAN}" }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {YOUR_MANAGEMENT_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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "is_first_party": "{OWNERSHIP_BOOLEAN}" }"

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

  conn.request("PATCH", "/{YOUR_DOMAIN}/api/v2/clients/{YOUR_CLIENT_ID}", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{YOUR_DOMAIN}/api/v2/clients/{YOUR_CLIENT_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 {YOUR_MANAGEMENT_API_ACCESS_TOKEN}'
  request["cache-control"] = 'no-cache'
  request.body = "{ "is_first_party": "{OWNERSHIP_BOOLEAN}" }"

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>YOUR\_CLIENT\_ID</code></td>
      <td>Τhe ID of the application to be updated.</td>
    </tr>

    <tr>
      <td><code>YOUR\_MANAGEMENT\_API\_ACCESS\_TOKEN</code></td>
      <td><a href="https://auth0.com/docs/api/management/v2/tokens">Access Tokens for the Management API</a> with the <Tooltip href="/docs/glossary?term=scope">scope</Tooltip> <code>update:clients</code>.</td>
    </tr>

    <tr>
      <td><code>OWNERSHIP\_BOOLEAN</code></td>
      <td>The ownership you would like to specify for the application. If the application is first-party, <code>is\_first\_party</code> should have a value of <code>true</code>. If the application is third-party, <code>is\_first\_party</code> should have a value of <code>false</code>.</td>
    </tr>
  </tbody>
</table>

## Learn more

* [First-Party and Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/first-party-and-third-party-applications)
* [View Application Ownership](/docs/get-started/applications/confidential-and-public-applications/view-application-ownership)
* [User Consent and Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/user-consent-and-third-party-applications)
* [Enable Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/enable-third-party-applications)


# User Consent and Third-Party Applications
Source: https://auth0.com/docs/get-started/applications/confidential-and-public-applications/user-consent-and-third-party-applications

Learn how to decouple APIs from applications that consume them and define third-party apps that you don't control or may not trust.

The [OIDC](/docs/authenticate/protocols/openid-connect-protocol)-conformant authentication pipeline supports defining <Tooltip href="/docs/glossary?term=resource+servers">resource servers</Tooltip> (such as APIs) as entities separate from applications. This lets you decouple APIs from the applications that consume them, and also lets you define [third-party applications](/docs/get-started/applications/confidential-and-public-applications/first-party-and-third-party-applications) that allow external parties to securely access protected resources behind your API.

## Consent dialog

If a user authenticates through a third-party application and the application requests authorization to access the user's information or perform some action at an API on their behalf, the user will see a consent dialog.

For example, this request:

```http lines theme={null}
GET /authorize?
client_id=some_third_party_client
&redirect_uri=https://fabrikam.com/contoso_social
&response_type=token id_token
&__scope=openid profile email read:posts write:posts__
&__audience=https://social.contoso.com__
&nonce=...
&state=...
```

Will result in this user consent dialog:

<Frame>
  <img alt="Authorization - User consent and applications - consent-dialog" />
</Frame>

If the user allows the application's request, this creates a user grant, which represents the user's consent to this combination of application, resource server, and requested scopes. The application then receives a successful authentication response from Auth0 as usual.

Once consent has been given, the user won't see the consent dialog during subsequent logins until consent is revoked explicitly.

## Scope descriptions

By default, the consent page will use the scopes' names to prompt for the user's consent. As shown below, you should define scopes using the `action:resource_name` format.

<Frame>
  <img alt="Authorization - User consent and applications - Consent scopes" />
</Frame>

The consent page groups scopes for the same resource and displays all actions for that resource in a single line. For example, the configuration above would result in **Posts: read and write your posts**.

If you would like to display the **Description** field instead, you can do so by setting the tenant's `use_scope_descriptions_for_consent` to `true`. This will affect consent prompts for all of the APIs on that tenant.

To set the `use_scope_descriptions_for_consent` flag, you will need to make the appropriate call to the API:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{YOUR_DOMAIN}/api/v2/tenants/settings' \
    --header 'authorization: Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "flags": { "use_scope_descriptions_for_consent": true } }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{YOUR_DOMAIN}/api/v2/tenants/settings");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("application/json", "{ "flags": { "use_scope_descriptions_for_consent": true } }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{YOUR_DOMAIN}/api/v2/tenants/settings"

  	payload := strings.NewReader("{ "flags": { "use_scope_descriptions_for_consent": true } }")

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

  	req.Header.Add("content-type", "application/json")
  	req.Header.Add("authorization", "Bearer {YOUR_MANAGEMENT_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))

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.patch("https://{YOUR_DOMAIN}/api/v2/tenants/settings")
    .header("content-type", "application/json")
    .header("authorization", "Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}")
    .header("cache-control", "no-cache")
    .body("{ "flags": { "use_scope_descriptions_for_consent": true } }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{YOUR_DOMAIN}/api/v2/tenants/settings',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}',
      'cache-control': 'no-cache'
    },
    data: {flags: {use_scope_descriptions_for_consent: true}}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{YOUR_DOMAIN}/api/v2/tenants/settings",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "PATCH",
    CURLOPT_POSTFIELDS => "{ "flags": { "use_scope_descriptions_for_consent": true } }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {YOUR_MANAGEMENT_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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "flags": { "use_scope_descriptions_for_consent": true } }"

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

  conn.request("PATCH", "/{YOUR_DOMAIN}/api/v2/tenants/settings", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{YOUR_DOMAIN}/api/v2/tenants/settings")

  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 {YOUR_MANAGEMENT_API_ACCESS_TOKEN}'
  request["cache-control"] = 'no-cache'
  request.body = "{ "flags": { "use_scope_descriptions_for_consent": true } }"

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

## Handle rejected permissions

If a user decides to reject consent to the application, they will be redirected to the `redirect_uri` specified in the request with an `access_denied` error:

```http lines theme={null}
HTTP/1.1 302 Found
Location: https://fabrikam.com/contoso_social#
    error=access_denied
    &state=...
```

## Skip consent for first-party applications

First-party applications can skip the consent dialog, but only if the API they are trying to access on behalf of the user has the **Allow Skipping User Consent** option enabled.

To navigate to the **Allow Skipping User Consent** toggle, select **Applications > APIs > (select the api) > Settings > Access Settings.**

<Card title="User consent and applications">
  Note that this option only allows verifiable first-party applications to skip consent at the moment. As `localhost` is never a verifiable first-party (because any malicious application may run on `localhost` for a user), Auth0 will always display the consent dialog for applications running on `localhost` regardless of whether they are marked as first-party applications. During development, you can work around this by modifying your `/etc/hosts` file to add an entry such as the following:

  `127.0.0.1 myapp.example`

  Similarly, you cannot skip consent (even for first-party applications) if `localhost` is used in the application's `redirect_uri` parameter and is present in any of the application's **Allowed Callback URLs** (found in [Dashboard > Applications > Settings](https://manage.auth0.com/#/applications)).
</Card>

Since third-party applications are assumed to be untrusted, they are not able to skip consent dialogs.

## Revoke consent

If a user has provided consent but you would like to revoke it:

1. Go to [Auth0 Dashboard > User Management > Users](https://manage.auth0.com/#/users), and click the user for whom you would like to revoke consent.
2. Click the **Authorized Applications** tab,
3. Click **Revoke** next to the appropriate application.

## Password-based flows

When using the [Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow), no consent dialog is involved because the user directly provides their password to the application, which is equivalent to granting the application full access to the user's account.

## Force users to provide consent

When redirecting to the `/authorize` endpoint, including the `prompt=consent` parameter will force users to provide consent, even if they have an existing user grant for the application and requested scopes.

## Learn more

* [First-Party and Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/first-party-and-third-party-applications)
* [View Application Ownership](/docs/get-started/applications/confidential-and-public-applications/view-application-ownership)
* [Confidential and Public Applications](/docs/get-started/applications/confidential-and-public-applications)
* [Enable Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/enable-third-party-applications)
* [Application Grant Types](/docs/get-started/applications/application-grant-types)


# View Application Ownership
Source: https://auth0.com/docs/get-started/applications/confidential-and-public-applications/view-application-ownership

Learn how to check whether an application is registered with Auth0 as a first-party or third-party app using the Auth0 Management API.

You can use Auth0's <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to check whether an application is registered with Auth0 as a first-party or third-party application.

Make a `GET` call to the [Get a Client endpoint](https://auth0.com/docs/api/management/v2#!/Clients/get_clients_by_id). Be sure to replace `{YOUR_CLIENT_ID}`
and `{YOUR_MANAGEMENT_API_ACCESS_TOKEN}` placeholder values with your <Tooltip href="/docs/glossary?term=client+ID">client ID</Tooltip> and Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{YOUR_DOMAIN}/api/v2/clients/{YOUR_CLIENT_ID}?fields=is_first_party&include_fields=true' \
    --header 'authorization: Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{YOUR_DOMAIN}/api/v2/clients/{YOUR_CLIENT_ID}?fields=is_first_party&include_fields=true");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{YOUR_DOMAIN}/api/v2/clients/{YOUR_CLIENT_ID}?fields=is_first_party&include_fields=true"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.get("https://{YOUR_DOMAIN}/api/v2/clients/{YOUR_CLIENT_ID}?fields=is_first_party&include_fields=true")
    .header("authorization", "Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{YOUR_DOMAIN}/api/v2/clients/{YOUR_CLIENT_ID}',
    params: {fields: 'is_first_party', include_fields: 'true'},
    headers: {authorization: 'Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{YOUR_DOMAIN}/api/v2/clients/{YOUR_CLIENT_ID}?fields=is_first_party&include_fields=true",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {YOUR_MANAGEMENT_API_ACCES_TOKEN}" }

  conn.request("GET", "/{YOUR_DOMAIN}/api/v2/clients/{YOUR_CLIENT_ID}?fields=is_first_party&include_fields=true", headers=headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{YOUR_DOMAIN}/api/v2/clients/{YOUR_CLIENT_ID}?fields=is_first_party&include_fields=true")

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

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}'

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>YOUR\_CLIENT\_ID</code></td>
      <td>Τhe ID of the application to be updated.</td>
    </tr>

    <tr>
      <td><code>YOUR\_MANAGEMENT\_API\_ACCESS\_TOKEN</code></td>
      <td><a href="https://auth0.com/docs/api/management/v2/tokens">Access Tokens for the Management API</a> with the <Tooltip href="/docs/glossary?term=scope">scope</Tooltip> <code>read:clients</code>.</td>
    </tr>
  </tbody>
</table>

If the application is first-party, the `is_first_party` field will have a value of `true`. If the application is third-party, the `is_first_party` field will have a value of `false`.

## Learn more

* [First-Party and Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/first-party-and-third-party-applications)
* [Update Application Ownership](/docs/get-started/applications/confidential-and-public-applications/update-application-ownership)
* [User Consent and Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/user-consent-and-third-party-applications)
* [Enable Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/enable-third-party-applications)


# Check if Application is Confidential or Public
Source: https://auth0.com/docs/get-started/applications/confidential-and-public-applications/view-application-type

Describes how to check whether an application is registered with Auth0 as a confidential or public app using the Auth0 Management Dashboard.

You can check whether an application is registered with Auth0 as a confidential or public application. To learn more, read [Confidential and Public Application](/docs/get-started/applications/confidential-and-public-applications).

Auth0 determines if an application is confidential or public based on the **Authentication Method** setting, which defines how an application authenticates against the Auth0 Authentication API [Get Token](https://auth0.com/docs/api/authentication/authorization-code-flow/get-token) endpoint.

1. In the Auth0 Dashboard, go to [Applications > Applications](https://manage.auth0.com/#/applications), and then select the name of the application to view.
2. If the **Credentials** view is not available, the application is a public application.
3. If the **Credentials** view is available, then select it and locate the **Authentication Method** field.

   <Frame>
     <img alt="Configure Private Key JWT Authentication - Auth0 Dashboard instructions" />
   </Frame>

Use the applicable method:

* **None**: Public application without a <Tooltip href="/docs/glossary?term=client+secret">client secret</Tooltip>.
* **Client Secret Post**: Application using POST request body parameters to send a client secret.
* **Client Secret Basic**: Application using the HTTP BASIC authentication scheme to send a client secret.
* **Private Key <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip>**: Application using asymmetric authentication.

These values map to confidential and public applications as follows:

<table>
  <thead>
    <tr>
      <th><strong>Application Type</strong></th>
      <th><strong>Example</strong></th>
      <th><strong>Token Endpoint Authentication Method</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Public</strong></td>
      <td>Single-page or native</td>
      <td><strong>None</strong></td>
    </tr>

    <tr>
      <td><strong>Confidential</strong></td>
      <td>Regular web or machine-to-machine</td>
      <td><strong>Basic</strong>, <strong>Post</strong>, <strong>Private Key JWT</strong>, <strong>Unspecified</strong></td>
    </tr>
  </tbody>
</table>

Public applications cannot maintain the confidentiality of the credentials required for <Tooltip href="/docs/glossary?term=Token+endpoint">Token endpoint</Tooltip> authentication methods like **Post** and **Basic**.


# Configure Application Metadata
Source: https://auth0.com/docs/get-started/applications/configure-application-metadata

Learn how to configure, update, and delete application metadata (client_metadata and clientMetadata)  in the Auth0 Dashboard Applications Advanced Settings.

Application metadata is optional and consists of customizable keys and values (max 255 characters each), that you can set for each application. Metadata is exposed in the `Client` object as `client_metadata`, and in Rules as `context.clientMetadata`. You might store, for example, the URL for the application’s home page (a field that Auth0 doesn’t provide by default in the application settings).

Client metadata is stored as part of the application (client) properties. To learn more about data types, field names, and storage limitations, read [Metadata Field Names and Data Types](/docs/manage-users/user-accounts/metadata/metadata-fields-data).

<Card title="Where to store client secrets">
  Where to store the secret depends on the scope of the secret:

  * Is it just one secret per application? Then `client_metadata` would be a good place.
  * Is it the same secret for the whole system (i.e., for all applications or many)? Then the rule’s configuration values might be a better choice
  * Is it a different secret for each user? Then storing in `app_metadata` might be better.
</Card>

<Warning>
  Claims in the ID token are not encrypted, so depending on the flow that you use, the user might be able to get the token and inspect the contents. Auth0 does **not** recommend storing a secret in that way.
</Warning>

Existing applications will have no value for this property.

You can access application metadata in [Actions](/docs/customize/actions):

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  if (event.client.metadata.SKIP_VERIFICATION === "yes"){
    return;
  }
  // ... continue this Action
}
```

... or in [Rules](/docs/customize/rules):

```javascript lines theme={null}
function applicationMetadataExample (user, context, callback){
  context.clientMetadata = context.clientMetadata || {};
  if (context.clientMetadata.SKIP_VERIFICATION === "yes"){
    return callback();
  }
  // ... continue this Rule
}
```

You can read and add to the application metadata using either the Dashboard or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. To learn how to manage client metadata with the Management API, read [Manage Metadata Using the Management API](/docs/manage-users/user-accounts/metadata/manage-metadata-api).

## Add application metadata key/value pairs

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and select the application.
2. Scroll down and click **Advanced Settings**.
3. On the **Application Metadata** tab, enter the key's name and value, then click **Add**.

   <Frame>
     <img alt="Dashboard Applications Applications Settings Tab Advanced Settings Application Metadata Tab" />
   </Frame>
4. Click **Save Changes**.

## Update application metadata value

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and select the application.
2. Scroll down and click **Advanced Settings**.
3. On the **Application Metadata** tab, enter the key's name that you want to change and enter a new value, then click **Add**.
4. Click **Save Changes**

## Delete application metadata

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and select the application.
2. Scroll down and click **Advanced Settings**.
3. On the **Application Metadata** tab locate the key/value pair you want to delete and click the trash can icon.
4. Confirm the deletion.
5. Click **Save Changes**.

## Learn more

* [Metadata Field Names and Data Types](/docs/manage-users/user-accounts/metadata/metadata-fields-data)
* [Manage Metadata Using the Management API](/docs/manage-users/user-accounts/metadata/manage-metadata-api)
* [Manage Metadata with Rules](/docs/manage-users/user-accounts/metadata/manage-metadata-rules)
* [Rotate Client Secrets](/docs/get-started/applications/rotate-client-secret)


# Configure Applications with OIDC Discovery
Source: https://auth0.com/docs/get-started/applications/configure-applications-with-oidc-discovery

Describes how to use OpenID Connect (OIDC) discovery to configure applications with Auth0 using SDKs.

[OpenID Connect (OIDC) Discovery](https://openid.net/specs/openid-connect-discovery-1_0-final.html#RFC5785) documents contain metadata about the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> (IdP). Adding discovery to your SDK to point your application to the `./wellknown` endpoint to consume information about your IdP could help configure your integration with the IdP.

Integrating OIDC discovery into your SDK provides:

* Exposed endpoints of the IdP
* Standard [OIDC supported claims and scope](/docs/get-started/apis/scopes/openid-connect-scopes) (this excludes [custom claims](/docs/secure/tokens/json-web-tokens/create-custom-claims) and scopes defined in your tenant)
* Features supported by the IdP

You can configure applications with the [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-discovery-1_0.html) discovery documents found at: `https://{yourDomain}/.well-known/openid-configuration`.

### Sample response

<AuthCodeBlock />

### Sample implementation

For example, this is how to configure OIDC middleware for Katana v3 (OWIN):

1. Install the nuget package: **Microsoft.Owin.Security.OpenIdConnect** (v3.x.x)
2. Go to `App_Start\Startup.Auth.cs` and replace your implementation with the following:

<AuthCodeBlock />

## RSA algorithm for JWTs

The OIDC middleware does not support <Tooltip href="/docs/glossary?term=JWTs">JWTs</Tooltip> signed with symmetric keys. Make sure you configure your app to use the RSA algorithm using public/private keys.

1. Go to [Dashboard > Settings](https://manage.auth0.com/#/applications/\{YOUR_AUTH0_CLIENT_ID}/settings).
2. Scroll down to **Advanced Settings**.
3. Under the **OAuth** tab, set `RS256` as **Json Web Token(JWT) Signature Algorithm** and click **Save**.

With this setting, Auth0 will issue JWTs signed with your private signing key. Your app will verify them with your public signing key.

## Configure applications with OAuth 2.0 Authorization Server Metadata

If your application or SDK references the [OAuth RFC-8414](https://www.rfc-editor.org/rfc/rfc8414) <Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip> Metadata specification, you can use the <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> alias to fetch metadata about the IdP: `/.well-known/oauth-authorization-server`. For example, the [Auth0 Model Context Protocol Server](/docs/get-started/auth0-mcp-server) recommends all OAuth applications reference the OAuth Authorization Server Metadata specification.

## Learn more

* [JSON Web Tokens](/docs/secure/tokens/json-web-tokens)
* [Create Custom Claims](/docs/secure/tokens/json-web-tokens/create-custom-claims)


# Configure Client-Initiated Backchannel Authentication
Source: https://auth0.com/docs/get-started/applications/configure-client-initiated-backchannel-authentication

Learn how to configure Client-Initiated Backchannel Authentication for your tenant.

<Callout icon="file-lines">
  To use Client-Initiated Backchannel Authentication (CIBA) features, you must have an Enterprise Plan or an appropriate add-on. Refer to [Auth0 Pricing](https://auth0.com/pricing/) for details.
</Callout>

The [Client-Initiated Backchannel Authentication (CIBA) flow](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow) is a decoupled authentication and authorization flow defined by the OpenID Foundation. You can use the CIBA flow in asynchronous workflows where the device initiating the CIBA request (the consumption device) is different from the device used by the user to authenticate (the authentication device).

To configure CIBA in Auth0, you need to:

* [Configure the CIBA grant type for your application](#configure-ciba-grant-type-for-your-application)
* [Enable notification channel(s) for your application](#enable-notification-channels-for-your-application)
* [Configure the notification channel for CIBA](#configure-notification-channel)

## Prerequisites

Before configuring CIBA for your application, make sure you set an [authentication method](/docs/secure/application-credentials#application-authentication-methods) for your application. You can use any authenticatino method, including mTLS authentication, Private Key <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip>, and <Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip> authentication, with the CIBA flow.

To set the authentication method for your application, read [Credential Settings](/docs/get-started/applications/credentials).

## Configure CIBA grant type for your application

You can configure the CIBA grant type for your application with the [Auth0 Dashboard](https://manage.auth0.com/) or [Management API](https://auth0.com/docs/api/management/v2).

There are some restrictions on the types of clients that can use the CIBA grant type. You can only use the CIBA grant type if:

* The client is a first-party client i.e. the `is_first_party` property is `true`.
* The client is confidential with an authentication mechanism, i.e. the `token_endpoint_auth_method` property must not be set to `none`.
* The client must be OIDC conformant i.e. the `oidc_conformant` must be `true`. This is the default for all new clients.

Once you enable the CIBA grant type, the configuration settings for the [notification channels](#enable-notification-channels-for-your-application) available to your application will become visible.

<Tabs>
  <Tab title="Auth0 Dashboard">
    To configure CIBA for your application with the Auth0 Dashboard:

    1. Navigate to **Applications > Applications** in the Auth0 Dashboard.
    2. Create an application and then enable **Client Initiated Backchannel Authentication (CIBA)** under the **Grant Types** tab:

    <Frame>
      <img alt="" />
    </Frame>

    3. Click **Save Changes**.
  </Tab>

  <Tab title="Management API">
    To configure CIBA for your application using the Management API, use the [Update a Client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) endpoint to add the `urn:openid:params:grant-type:ciba` grant type to the list of grant types on the client object:

    ```bash lines theme={null}
    curl --location --request PATCH 'https://{YOUR_DOMAIN}.auth0.com/api/v2/clients/{YOUR_CLIENT_ID}' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}' \
    --data '{
        "grant_types": [
            "authorization_code",
            "refresh_token",
            "urn:openid:params:grant-type:ciba"
        ]
    }'
    ```

    You can also use our Go Management API SDK library. To learn more, read [SDKs](/docs/libraries):

    ```go lines theme={null}
    myClient := &Client{
        Name:        auth0.Stringf("CIBA-enabled-client"),
        Description: auth0.String("This is a CIBA enabled client."),
        GrantTypes:  &[]string{"urn:openid:params:grant-type:ciba"},
      }

      err := api.Client.Create(context.Background(), myClient)
    ```
  </Tab>
</Tabs>

## Enable notification channels for your application

<Callout icon="file-lines">
  To use Client-Initiated Backchannel Authentication (CIBA) features, you must have an Enterprise Plan or an appropriate add-on. Refer to [Auth0 Pricing](https://auth0.com/pricing/) for details.
</Callout>

Once you have enabled the CIBA grant type for your application, you can configure which notification channels are enabled for the CIBA flow. If you have enabled multiple notification channels, CIBA uses the value of the `requested_expiry` parameter to determine which notification channel to use. The `requested_expiry` determines the maximum duration for which the CIBA session should be valid in seconds:

* [Mobile push notifications](#configure-mobile-push-notifications): If you set your `requested_expiry` to a value of 300 seconds or lower, CIBA uses the mobile push notification channel if enabled.
* [Email notifications](#configure-email-notifications): If you set your `requested_expiry` to a value between 301 and 259200 seconds (72 hours), CIBA uses the email notification channel if enabled.

<Tabs>
  <Tab title="Auth0 Dashboard">
    To configure the notification channel for your application with the Auth0 Dashboard:

    * Navigate to **Applications > Applications**.
    * In your application settings, go to the **Client Initiated Backchannel Authentication (CIBA)** section and select the notification channel(s) to enable.

    <Frame>
      <img alt="" />
    </Frame>
  </Tab>

  <Tab title="Management API">
    Make a `PATCH` request to the `/api/v2/clients` endpoint for your client application and set the notification channels for the CIBA flow.

    The following code sample enables the `guardian-push` notification channel for the CIBA flow:

    ```bash lines theme={null}
    curl -L --request PATCH 'https://{YOUR_DOMAIN}/api/v2/clients/{YOUR_CLIENT_ID}' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H "Authorization: Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}" \
    -d '{
        "async_approval_notification_channels":["guardian-push"]
    }'
    ```
  </Tab>
</Tabs>

## Configure notification channel

Once you have enabled the notification channel(s) for your client application, configure the notification channel for the CIBA flow:

* [Configure mobile push notifications](#configure-mobile-push-notifications)
* [Configure email notifications](#configure-email-notifications)

### Configure mobile push notifications

To send mobile push notifications with CIBA, you can use:

* The Auth0 Guardian app
* A custom app integrated with the Auth0 Guardian SDK

You can select which app to use when [enabling Auth0 Guardian push notifications](/docs/get-started/applications/configure-client-initiated-backchannel-authentication#enable-auth0-guardian-push-notifications). If you want to use a custom app, you need to integrate it with the [Auth0 Guardian SDK](/docs/secure/multi-factor-authentication/auth0-guardian#guardian-sdks). This allows the authorizing user to approve push notification challenges initiated by the CIBA flow in your custom app.

To configure mobile push notifications, make sure you:

* [Enable Auth0 Guardian push notifications](#enable-auth0-guardian-push-notifications)
* [Enroll the authorizing user in MFA using push notifications](#enroll-the-authorizing-user-in-mfa-using-push-notifications)

#### Enable Auth0 Guardian push notifications

Use the Auth0 Dashboard to enable the [Auth0 Guardian Push Notification](/docs/secure/multi-factor-authentication/auth0-guardian#enroll-in-push-notifications) factor for your tenant.

In the Auth0 Dashboard:

* Select **Security > Multi-factor Auth.**

* Enable **Push Notification using Auth0 Guardian**. This may require some <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> configuration settings. To learn more, read [Configure Push Notifications for MFA](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-push-notifications-for-mfa).

<Frame>
  <img alt="" />
</Frame>

* For **Push Notification App**, select your desired app.

<Frame>
  <img alt="" />
</Frame>

* Click **Save**.

#### Enroll the authorizing user in MFA using push notifications

<Callout icon="file-lines">
  If the user is not enrolled to use MFA push notifications, Auth0 falls back to using email notifications, if configured, instead of rejecting the CIBA request.
</Callout>

For both the Auth0 Guardian app and a custom app, you must [enroll the authorizing user in MFA using push notifications](/docs/secure/multi-factor-authentication/auth0-guardian#enroll-in-push-notifications).

To verify if the user is enrolled in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, navigate to **User Management > Users** and click on the user:

<Frame>
  <img alt="" />
</Frame>

If you have set <Tooltip href="/docs/glossary?term=Multi-factor+Authentication">Multi-factor Authentication</Tooltip> as always required for your tenant, users are prompted to enroll for MFA at their next login. You can also use [Actions](https://auth0.com/blog/using-actions-to-customize-your-mfa-factors/) to prompt for MFA enrollment.

### Configure email notifications

<Callout icon="file-lines">
  To use email notifications with CIBA, you need the Auth0 for AI Agents add-on with a paid plan. To learn more, read [Auth0 Pricing](https://auth0.com/pricing).
</Callout>

You can send email notifications with the CIBA flow. To configure email notifications with CIBA, make sure you:

* [Configure your email provider](#configure-your-email-provider)
* [Configure your email template](#configure-your-email-template) to use the **Asynchronous Approval** template
* [Ensure the authorizing user has a verified email address](#ensure-the-authorizing-user-has-a-verified-email-address)

#### Configure your email provider

While you can use Auth0’s built-in email provider to test email delivery in your development and test environments, you must set up your own email provider to use email notifications with CIBA in a production environment.

To learn how to set up your own email provider, read [Customize emails](/docs/customize/email).

#### Configure your email template

To configure the **Asynchronous Approval** email template:

<Tabs>
  <Tab title="Auth0 Dashboard">
    1. Navigate to **Branding > Email Templates**.
    2. For **Template**, select **Asynchronous Approval** from the dropdown menu.
    3. Fill in the rest of the template settings by following the [Configure template fields](/docs/customize/email/email-templates#configure-template-fields) instructions.
  </Tab>

  <Tab title="Management API">
    Make a `PATCH` request to the `/email-templates/async_approval` endpoint and follow the [Configure template fields](/docs/customize/email/email-templates#configure-template-fields) instructions to fill in the rest of the template settings. To learn more, read the [Patch an email template API documentation](https://auth0.com/docs/api/management/v2/email-templates/patch-email-templates-by-template-name).

    ```bash lines theme={null}
    curl -L "https://{YOUR_DOMAIN}.auth0.com/api/v2/email-templates" \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H "Authorization: Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}" \
    -d '{"template":"async_approval","body":"{{application.name}} says click on {{url}}, binding message: {{binding_message}}","subject":"Action Required","syntax":"liquid","enabled":true,"from":""}'
    ```
  </Tab>
</Tabs>

#### Ensure the authorizing user has a verified email address

<Callout icon="file-lines">
  If the user does not have a verified email address, Auth0 rejects the CIBA email request.
</Callout>

To send an email notification with CIBA, the authorizing user must have a verified email address associated with their user account.

To verify that the user has a verified email address using the Auth0 Dashboard:

1. Navigate to **User Management > Users** and click on the user.
2. Under **Email**, the user should have a verified email address listed.


# Configure FAPI Compliance
Source: https://auth0.com/docs/get-started/applications/configure-fapi-compliance

Learn how to configure FAPI compliance for an Auth0 tenant.

<Callout icon="file-lines">
  To use Highly Regulated Identity features, you must have an Enterprise Plan with the Highly Regulated Identity add-on. Refer to [Auth0 Pricing](https://auth0.com/pricing/) for details.
</Callout>

To help customers configure their Auth0 tenant to adhere to one of the Financial-grade API (FAPI) profiles, the Application model includes a `compliance_level` property that can be set to one of three values:

* `null` or undefined: No compliance level is required. This is the default.
* `fapi1_adv_mtls_par`: The customer would like this client to behave in accordance with the FAPI1 Advanced profile using [mTLS](/docs/get-started/applications/configure-mtls) and [PAR](/docs/get-started/applications/configure-par).
* `fapi1_adv_pkj_par`: The customer would like this client to behave in accordance with the FAPI1 Advanced profile using [Private Key JWT](/docs/get-started/applications/configure-private-key-jwt) and [PAR](/docs/get-started/applications/configure-par).
* `fapi2_sp_pkj_mtls`: The customer would like this client to behave in accordance with the FAPI 2.0 Security Profile using [Private Key JWT](/docs/get-started/applications/configure-private-key-jwt) and [mTLS Token Sender-Constraining](/docs/secure/sender-constraining/mtls-sender-constraining).
* `fapi2_sp_mtls_mtls`: The customer would like this client to behave in accordance with the FAPI 2.0 Security Profile using [mTLS Client Authentication](/docs/get-started/applications/configure-mtls) and [mTLS Token Sender-Constraining](/docs/secure/sender-constraining/mtls-sender-constraining).

Complying with a FAPI profile requires a number of configuration changes. Setting the `compliance_level` ensures that no authorization request can succeed unless the request and the configuration is compliant with the selected standard.

For example, both the `fapi1_adv_pkj_par` and `fapi1_adv_mtls_par` compliance levels require PAR. If either of these compliance levels are selected, PAR is required regardless of the value of the `require_pushed_authorization_requests` setting. Attempting an authorization without using PAR results in the following error response:

```json lines theme={null}
{
  “error”: “invalid_request”,
  “error_description”: “Pushed Authorization Requests are required by the configured compliance level” 
}
```

In some cases, setting a compliance level also changes Auth0’s behavior. For example, both the `fapi1_adv_pkj_par` and `fapi1_adv_mtls_par` compliance levels cause Auth0 to include a `s_hash` claim in the returned <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> containing a SHA256 hash of the state value. This allows the ID tokens to act as a detached signature.

The following tables summarize the additional validation rules and changes to Auth0’s behavior that each compliance level enables:

<table>
  <thead>
    <tr>
      <th><strong>Validation</strong></th>
      <th><code>fapi1\_adv\_pkj\_par</code></th>
      <th><code>fapi1\_adv\_mtls\_par</code></th>
      <th><code>fapi2\_sp\_pkj\_mtls</code></th>
      <th><code>fapi2\_sp\_mtls\_mtls</code></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Prevents the use of access tokens in the URL query when calling <code>/userinfo</code>. Access tokens must be placed in the Authorization header instead.</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
    </tr>

    <tr>
      <td>Requires PAR.</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
    </tr>

    <tr>
      <td>Requires PKCE with the S256 challenge method.</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
    </tr>

    <tr>
      <td>Prevents the use of wildcards in the allowed callbacks on a client.</td>
      <td>Y</td>
      <td>Y</td>
      <td>N</td>
      <td>N</td>
    </tr>

    <tr>
      <td>Enforces the use of JAR.</td>
      <td>Y</td>
      <td>Y</td>
      <td>N</td>
      <td>N</td>
    </tr>

    <tr>
      <td>Ensures the JAR payload is signed using the PS256 algorithm.</td>
      <td>Y</td>
      <td>Y</td>
      <td>N</td>
      <td>N</td>
    </tr>

    <tr>
      <td>Ensures the JAR payload contains the nbf claim and it is no longer than 60 minutes in the past.</td>
      <td>Y</td>
      <td>Y</td>
      <td>N</td>
      <td>N</td>
    </tr>

    <tr>
      <td>Ensures the JAR payload contains the exp claim and that it is no more than 60 minutes after the nbf claim.</td>
      <td>Y</td>
      <td>Y</td>
      <td>N</td>
      <td>N</td>
    </tr>

    <tr>
      <td>Ensures the client has set the <code>oidc\_conformant</code> property to true.</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
    </tr>

    <tr>
      <td>Requires the use of <code>x-fapi-\*</code> headers</td>
      <td>Y</td>
      <td>Y</td>
      <td>N</td>
      <td>N</td>
    </tr>

    <tr>
      <td>Requires the use of Private Key JWT for client authentication.</td>
      <td>Y</td>
      <td>N</td>
      <td>Y</td>
      <td>N</td>
    </tr>

    <tr>
      <td>Requires the use of mTLS for client authentication.</td>
      <td>N</td>
      <td>Y</td>
      <td>N</td>
      <td>Y</td>
    </tr>

    <tr>
      <td>Allowed response types.</td>
      <td>code <code>id\_token</code></td>
      <td>code <code>id\_token</code></td>
      <td>code</td>
      <td>code</td>
    </tr>

    <tr>
      <td>Requires <code>aud</code> claim to strictly match issuer in Private Key JWT assertion.</td>
      <td>N</td>
      <td>N/A</td>
      <td>Y</td>
      <td>N/A</td>
    </tr>

    <tr>
      <td>Requires <code>redirect\_uri</code> parameter in Pushed Authorization Requests.</td>
      <td>N</td>
      <td>N</td>
      <td>Y</td>
      <td>Y</td>
    </tr>
  </tbody>
</table>

<table>
  <thead>
    <tr>
      <th><strong>Auth0 updated behavior</strong></th>
      <th><code>fapi1\_adv\_pkj\_par</code></th>
      <th><code>fapi1\_adv\_mtls\_par</code></th>
      <th><code>fapi2\_sp\_pkj\_mtls</code></th>
      <th><code>fapi2\_sp\_mtls\_mtls</code></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Adds s\_hash claim to ID tokens.</td>
      <td>Y</td>
      <td>Y</td>
      <td>N</td>
      <td>N</td>
    </tr>

    <tr>
      <td>When the profile scope is requested, the <code>update\_at</code> claim contains an OIDC Conformant unix timestamp rather than a string.</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
    </tr>

    <tr>
      <td>Returns only OIDC conformant error codes. In some cases, Auth0 may return additional error codes, but enabling this compliance level ensures that Auth0 only uses error codes defined in the OpenID standards.</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
    </tr>

    <tr>
      <td>Returns issuer as <code>iss</code> parameter in code responses.</td>
      <td>N</td>
      <td>N</td>
      <td>Y</td>
      <td>Y</td>
    </tr>

    <tr>
      <td>Reduces maximum lifetime of authorization code to 60 seconds.</td>
      <td>N</td>
      <td>N</td>
      <td>Y</td>
      <td>Y</td>
    </tr>
  </tbody>
</table>

## Configure FAPI Compliance for a client

<Tabs>
  <Tab title="Auth0 Dashboard">
    To perform this using the Auth0 Dashboard:

    1. Navigate to **Auth0 Dashboard > Applications**.
    2. Select the application.
    3. Select the **Application Settings** tab.
    4. Open the **Advanced Settings** section.
    5. In the **OAuth tab**, select the **FAPI Compliance Enforcement Level**.

    The options to configure FAPI compliance are:

    * **None**: No compliance level is required. This is the default.
    * **FAPI 1 Advanced profile using Private Key JWT and PAR**: The customer would like this client to behave in accordance with the FAPI1 Advanced profile using [Private Key JWT](/docs/get-started/applications/configure-private-key-jwt) and [PAR](/docs/get-started/applications/configure-par).
    * **FAPI 1 Advanced profile using mTLS and PAR**: The customer would like this client to behave in accordance with the FAPI1 Advanced profile using [mTLS](/docs/get-started/applications/configure-mtls) and [PAR](/docs/get-started/applications/configure-par).
    * **FAPI 2.0 Security Profile with Private Key JWT and certificate binding**: The customer would like this client to behave in accordance with the FAPI2.0 Security Profile using [Private Key JWT Client Authentication](/docs/get-started/applications/configure-private-key-jwt) and [mTLS Token Sender-Constraining](/docs/secure/sender-constraining/mtls-sender-constraining).
    * **FAPI 2.0 Security Profile with mTLS and certificate binding**: The customer would like this client to behave in accordance with the FAPI2.0 Security Profile using [mTLS Client Authentication](/docs/get-started/applications/configure-mtls) and [mTLS Token Sender-Constraining](/docs/secure/sender-constraining/mtls-sender-constraining).
  </Tab>

  <Tab title="Management API">
    Use the [Management API](https://auth0.com/docs/api/management/v2) to set the `compliance_level` property with a `POST` or `PATCH` request:

    ```bash lines theme={null}
    curl --location --request PATCH 'https://{YOUR_DOMAIN}/api/v2/clients/$client_id' \
      --header 'Authorization: Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}' \
      --header 'Content-Type: application/json' \
      --data '{
        "compliance_level": "fapi1_adv_mtls_par"
    }'
    ```

    To return the `compliance_level` property, use a `GET` request:

    ```bash lines theme={null}
    curl --location 'https://{YOUR_DOMAIN}/api/v2/clients/{YOUR_CLIENT_ID} \
      --header 'Authorization: Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}'
    ```

    For FAPI 2.0 compliance, you can configure the expiry on pushed authorization requests to a value that is less than 600 seconds, with a default of 30 seconds. You can set the expiry value using the Management API.
  </Tab>
</Tabs>

## Learn more

* [Configure Private Key JWT Authentication](/docs/get-started/applications/configure-private-key-jwt)
* [Configure Pushed Authorization Requests (PAR)](/docs/get-started/applications/configure-par)
* [Configure mTLS Authentication](/docs/get-started/applications/configure-mtls)


# Configure Auth0 to pass OpenID FAPI Certification Tests
Source: https://auth0.com/docs/get-started/applications/configure-fapi-compliance/configure-auth0-to-pass-openid-fapi-certification-tests

Learn how to configure Auth0 to pass the OpenID FAPI Certification Tests.

This section contains some advice on how to configure your client if you would like to test your solution using the [OpenID FAPI Conformance Tests](https://openid.net/certification/certification-fapi_op_testing/).

To pass the <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> FAPI Conformance Tests, first configure the following:

* Set the `compliance_level` property to the desired profile, either `fapi1_adv_pkj_par`, `fapi1_adv_mtls_par`, `fapi2_sp_pkj_mtls`, or `fapi2_sp_mtls_mtls`
* Either [Configure mTLS](/docs/get-started/applications/configure-mtls) (including [mTLS aliases](/docs/get-started/applications/configure-mtls/configure-mtls-for-a-tenant#enable-mtls-aliases)) or [Configure Private Key JWT](/docs/get-started/applications/configure-private-key-jwt)
* [Configure mTLS Token Binding](/docs/get-started/applications/configure-mtls/configure-mtls-for-a-client#enable-token-binding)
* Configure [Pushed Authorization Requests](/docs/get-started/applications/configure-par)
* Ensure the `oidc_conformant` property is set to `true` for any clients used for the test. This is the default value for clients created with the Auth0 Dashboard.

Then, follow the instructions below to complete your OpenID FAPI Conformance Tests configuration:

* [Ensure Auth0 prompts users for consent](#ensure-auth0-prompts-users-for-consent)
* [Configure supported ACR claims for the tenant](#configure-supported-acr-claims-for-the-tenant)
* [Remove the alg property from JWKS endpoint](#remove-the-alg-property-from-jwks-endpoint)
* [Add Action to require scope and redirect\_uri](#add-action-to-require-scope-and-redirect-uri)
* [(FAPI2 profiles only) Ensure `iss` claim is returned in responses](#fapi2-profiles-only-ensure-iss-claim-is-returned-in-responses)

### Ensure Auth0 prompts users for consent

You will need to ensure that Auth0 prompts users for consent. You may skip this step if the client is configured as a first-party app, and the <Tooltip href="/docs/glossary?term=Resource+Server">Resource Server</Tooltip> or API supports skipping consent for first-party apps. To ensure Auth0 requests users for consent, set the `is_first_party` property on the client to `false`:

```bash lines theme={null}
curl --location --request PATCH 'https://{YOUR_DOMAIN}/api/v2/clients/YOUR_CLIENT_ID' \
  --header 'Authorization: Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "is_first_party": false  
}'
```

Then, promote your connection to the domain level:

```bash lines theme={null}
curl --location --request PATCH 'https://{YOUR_DOMAIN}/api/v2/connections/YOUR_CONNECTION_ID' \
  --header 'Authorization: Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "is_domain_connection": true
}'
```

#### Configure supported ACR claims for the tenant

The FAPI tests pass a required ACR value of `urn:mace:incommon:iap:silver`. To include the required ACR value in the <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip>, add `urn:mace:incommon:iap:silver` to the list of supported ACR values for the tenant:

```bash lines theme={null}
curl --location --request PATCH 'https://{YOUR_DOMAIN}/api/v2/tenants/settings' \
  --header 'Authorization: Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "acr_values_supported": ["urn:mace:incommon:iap:silver"]
}'
```

#### Remove the alg property from JWKS endpoint

To allow for keys to be used with multiple algorithms, not just RS256, remove the tenant's `alg` property from the output of the `/.well-known/jwks.json` endpoint:

```bash lines theme={null}
curl --location --request PATCH 'https://{YOUR_DOMAIN}/api/v2/tenants/settings' \
  --header 'Authorization: Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "flags": {
        "remove_alg_from_jwks": true
    }
}'
```

#### Add Action to require scope and redirect\_uri

By default, Auth0 allows requests without a scope, assuming the `openid` scope if no scope is present. Auth0 also allows requests without a `redirect_uri,` which you can set in [Actions](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/redirect-with-actions). However, the FAPI conformance tests require Auth0 to be more restrictive.

Add the following Action to enforce the necessary restrictions on scope and `redirect_uri`:

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  if (!event.request.body || !event.request.body.refresh_token) {
    // Require a scope
    if (!event.request.query.scope) {
      api.access.deny('scope must be provided in the request');
    }
    // To improve the error message if redirect_uri is not present
    if (!event.request.query.redirect_uri) {
      api.access.deny('redirect_uri must be provided in the request');
    }
  }
};
```

#### (FAPI2 profiles only) Ensure `iss` claim is returned in responses

The FAPI 2.0 Security Profile requires that the `iss` parameter is returned in authorization responses according to [RFC9207](https://www.rfc-editor.org/info/rfc9207). For compatibility reasons, Auth0 does not do this by default. To enable this behaviour, set the `authorization_response_iss_parameter_supported` property in tenant settings to `true`.

```bash lines theme={null}
curl --location --request PATCH "https://{YOUR_DOMAIN}/api/v2/tenants/settings" \
  --header "Authorization: Bearer {YOUR_MANAGEMENT_API_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "authorization_response_iss_parameter_supported": true
  }'
```

## Learn more

* [Configure Private Key JWT Authentication](/docs/get-started/applications/configure-private-key-jwt)
* [Configure mTLS Authentication](/docs/get-started/applications/configure-mtls)


# Configure JWT-secured Authorization Requests (JAR)
Source: https://auth0.com/docs/get-started/applications/configure-jar

Learn how to configure JWT-secured Authorization Requests (JAR) for an application.

<Callout icon="file-lines">
  To use Highly Regulated Identity features, you must have an Enterprise Plan with the Highly Regulated Identity add-on. Refer to [Auth0 Pricing](https://auth0.com/pricing/) for details.
</Callout>

<Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip>-Secured Authorization Requests (JAR) allow OAuth2 authorization request parameters to be packaged into a single JWT request parameter which is then signed for integrity protection.

## Prerequisites

Before configuring your application for using JAR, you must [generate an RSA key pair](/docs/secure/application-credentials/generate-rsa-key-pair).

<Warning>
  You should generate a separate key pair for each type of credential usage. For example, do not reuse the same key pairs for both JAR and Private Key JWT Authentication.
</Warning>

## Configure JAR for an application

You can configure JAR for an application with the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> and the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

<Tabs>
  <Tab title="Auth0 Dashboard">
    Use the Auth0 Dashboard to configure your application to use JAR with previously generated RSA keys.

    1. Navigate to [Auth0 Dashboard > Applications](https://manage.auth0.com/#/applications).
    2. Select the application you want to use with JAR.
    3. Select the **Application Settings** tab.
    4. In the **Authorization Requests** section, enable **Require JWT-Secured Authorization Requests**.
    5. If no credential is assigned and there are credentials available, you will be prompted to assign an existing credential.

       <Frame>
         <img alt="Dashboard > Application > Settings > Assign Existing Credentials" />
       </Frame>
    6. You will also have the option to assign a new credential.

       <Frame>
         <img alt="Auth0 Dashboard > Applications > Settings > Assign New Credentials" />
       </Frame>
    7. Add and assign a new credential by uploading a previously generated RSA key pair. When prompted, enter the following:

       * **Name**: a name to identify the credential
       * **Public Key**: public key of the X.509 certificate in PEM format
       * **Algorithm**: select the JAR signature algorithm
       * **Expiration Date**: set the expiration date of the credential
  </Tab>

  <Tab title="Management API">
    Use the [Management API](https://auth0.com/docs/api/management/v2) to configure JAR for your application using the `signed_request_object` client configuration property. This object property contains the following fields:

    * `required`: forces all authorization requests to the `/authorize` and `/oauth/par` to use JAR. To learn more, read [Authorization Code Flow with JWT-Secured Authorization Requests](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-jar).
    * `credentials`: an array of credential IDs used to verify signatures.

    <Callout icon="file-lines">
      The credentials parameter behaves similarly to the Private Key JWT parameter `client_authentication_methods.private_key_jwt.credentials` which supports credential creation when you create a new application. To learn more, read [Configure Private Key JWT](/docs/get-started/applications/configure-private-key-jwt).
    </Callout>

    You can configure JAR for a new application or for an existing application via the Management API.

    #### Configure JAR for a new application

    When you create a new application, configure JAR by sending a POST request with the `signed_request_object`. In that POST request, you can also register the corresponding client credential (i.e. the key PEM):

    ```json lines theme={null}
    POST https://{yourTenant}.auth0.com/api/v2/clients
    Authorization: Bearer <YOUR_ACCESS_TOKEN>
    Content-Type: application/json
    {
      "name": "My App using JAR",
      "signed_request_object": {
          "required": true,
    "credentials": [{
            "name": "My credential for JAR",
            "credential_type": "public_key",
            "pem": "[YOUR PEM FILE CONTENT]",
            "alg": "RS256"
    }]
      },
      "jwt_configuration": {
        "alg": "RS256"
      }
    }
    ```

    #### Configure JAR for an existing application

    When updating an existing application, you need to explicitly create a client credential first. The following POST request uses your PEM file content to create your client credentials for JAR:

    <AuthCodeBlock />

    <Callout icon="file-lines">
      Make sure newlines are properly JSON-encoded with no additional formatting.
    </Callout>

    Then, assign the client credential to the `signed_request_object` client configuration. The following PATCH request associates your client credentials with the `signed_request_object`:

    <AuthCodeBlock />
  </Tab>
</Tabs>

## Learn more

* [Authorization Code Flow with JWT-Secured Authorization Requests (JAR)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-jar)


# Configure mTLS Authentication
Source: https://auth0.com/docs/get-started/applications/configure-mtls

Learn how to configure mTLS authentication.

<Callout icon="file-lines">
  To use Highly Regulated Identity features, you must have an Enterprise Plan with the Highly Regulated Identity add-on. Refer to [Auth0 Pricing](https://auth0.com/pricing/) for details.
</Callout>

Use the [Auth0 Management API](https://auth0.com/docs/api/management/v2) or [Auth0 Dashboard](https://manage.auth0.com/) to configure mTLS authentication. To learn more about how mTLS authentication works at Auth0, read [Authenticate with mTLS](/docs/get-started/authentication-and-authorization-flow/authenticate-with-mtls).

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/get-started/applications/configure-mtls/set-up-the-customer-edge">Set up your customer edge</a></td>
      <td>How to set up your customer edge to validate your client certificate and forward requests to Auth0's edge network.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/applications/configure-mtls/configure-mtls-for-a-client">Configure mTLS for a client</a></td>
      <td>How to configure mTLS authentication for your Auth0 application.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/applications/configure-mtls/configure-mtls-for-a-tenant">Configure mTLS for a tenant</a></td>
      <td>How to configure mTLS authentication for your Auth0 tenant.</td>
    </tr>
  </tbody>
</table>


# Configure mTLS Authentication for a Client
Source: https://auth0.com/docs/get-started/applications/configure-mtls/configure-mtls-for-a-client

Describes how to configure mTLS authentication for a client.

Learn how to configure mTLS authentication for a client with the [Management API](#configure-mtls-with-management-api) and [Auth0 Dashboard](#configure-mtls-with-auth0-dashboard).

<Tabs>
  <Tab title="Auth0 Dashboard">
    You can use the Auth0 Dashboard to configure mTLS for a client to enable mTLS client authentication to the Authorization Server.

    1. Navigate to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications).
    2. Select the application you want to use with mTLS or [create a new application](/docs/get-started/auth0-overview/create-applications).
    3. Select the **Credentials** tab.
    4. Choose the required **Authentication Method**, which can be either:

       * mTLS with a [self-signed certificate](/docs/customize/custom-domains/self-managed-certificates)
       * mTLS with a certificate authority signed certificate
    5. Once you select your preferred type of certificate, you can:

       * Assign an existing credential (certificate) to the client application
       * Add a new credential by uploading a certificate
  </Tab>

  <Tab title="Management API">
    Use the [Auth0 Management API](https://auth0.com/docs/api/management/v2) to configure mTLS for a client.

    <Callout icon="file-lines">
      The following examples specify **\$management\_access\_token**, or a [Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens). This must be replaced with an access token that contains at least the following scopes:

      * `create:custom_domains`
      * `read:custom_domains`
      * `create:clients`
      * `update:clients`
      * `update:client_credentials`
      * `update:client_keys`
      * `update:tenant_settings`

      To learn more about retrieving an access token with the required scopes, read [Get Access Tokens](/docs/secure/tokens/access-tokens/get-access-tokens).
    </Callout>

    #### Self-signed certificates

    Use self-signed certificates to verify the client’s identity during mTLS authentication. However, self-signed certificates have the following limitations

    * Self-signed certificates are not accepted by some cloud providers such as Amazon.
    * To ensure the stability of our platform, Auth0 limits customers to two registered certificates.

    ##### Generate a certificate

    To authenticate using self-signed mTLS, you must create a new self-signed client certificate.

    The following code sample generates a new self-signed certificate:

    ```bash wrap lines theme={null}
    openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -sha256 -days 365 -nodes -subj "/C=XX/ST=StateName/L=CityName/O=CompanyName/OU=CompanySectionName/CN=CommonNameOrHostname"
    ```

    If using curl or Wget, the PEM certificate must be JSON escaped before you pass it to Auth0. For example, replace a newline is with `\r\n`:

    ```bash wrap lines theme={null}
    -----BEGIN PRIVATE KEY-----\r\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDDXAVKQo2SUMHH\r\no9ecWYNiL5\/yva5NSj8uQjKoeRAsOIOAyOBTLxgwmno13xZ8VDkcT1cHTlC+2CkE\r\noBII4OUbHPVof+dtknkL+jUBdIPX1QvlGSUbzduZE4hEEQ8zH6w4EAA2VN72Bymn\r\nT8i\/+Tz9Dx6M1nkuXPCwM7sYEuq5OrqT5yVB6KByKKElp\/tauJkHp0st04iGDgl2\r\nFJUt3QJFCFewTDDdGq62otVJxHfouXPmHBQjzf+f1CZy+N0q2z+JGRt44YZq+F9y\r\ne3RWawvv2x3TXgRBLpvIKqf99LoPVdwozHl8QODu52dyelvLQ866XLhAALuMwic\/\r\nbQbolnMpAgMBAAECggEAf6LliekFmezNTmQLgIkzP7kh5XRsJu81bEGv20aNfHbH\r\n5CJZ\/b8tLMQgyIWiqURVs9taXtmaA7YyxmTWo5pb1WUMKWQ3je0+zMaCTxsS8Lau\r\n+NV+2zWaHd8XDnGe3qX43QAHQ3gb294+JqQH4vUyFZwFN7sAnXv3fQevW0Ewvics\r\nOua\/xNa7y5hbJUPZiQjRhO+n+gTEqpfsnPWNlm9hk\/wVnnjKvMfstN4zUbznRAoN\r\nW8TK82tiVWAXW4CjgIBtVRZjTA9x3UOtbhcvNzaTRxc+scCpIpAVuurS+ZIKZdpm\r\nNnhiOk3akpLU3KZrm8C5JQRn8cupY9WkfCiLXbMFAQKBgQD9JfVMv6zDeNvExneR\r\n7fZDIT2UAEhYExwRJwQPyxkVPwev9HBYuuaaknIbomWTkt\/B6Q3k3p6VI4lxhnVl\r\nbkpOYl5UquP3VoVROEJts224hKgVcLw6s+i+lZDOAleNgbN7rj82l4BIu+SEj\/7c\r\nz94hAa\/wRRvsW+QnxF1sZnpY+QKBgQDFj2h8I4noFJk3sbbk3qQdi5+49ibWSuhc\r\nXVpU+0dQ1lRlhXYT9cDMc22HRt8hjXUNRhdpXvOqVaFiBjv9wBsmFyaJO3tOK3uE\r\ndBgD4lF03bnbGI7\/I3DivW\/tyEMS5JXI\/qrpdWor+wR30c5M\/45y2AGpjwnoGf+D\r\nX8SAMzknsQKBgQCrSljuIrBK3+eNAWH821CL4d0h3QMWnW+bZ5QG\/70sNCcGd1bh\r\noy3Qn5EYg81JitNfCUw+dihF7\/LbX0jmZjdfTI5Zqfxw6xlweKnyQrvWY+S8BTlI\r\nW138P4Xo74rAlGeXI7NgRCkojgK1dB3W2cyK9vJOmOSpDRCXm\/Y\/GCRnOQKBgCE\/\r\n75\/lA1LSFK9w8401g32NgEZK92JdnRnehFOFLw2F5RJpEeRuGhLO4oJABVHKUwb2\r\n4v3TA0OJwe2Tiwk8CdWxU8UJA8m2O8WhHGGa94apwpwDWB3MwzUGGQ52BAPsAOGh\r\nKva70jCwwKHB5+zBniHqBO2aq1oq9fwQZCwHcvkhAoGBAIa8QMHNrX7AuCSAeR4\/\r\n\/7XrGU1a4oExz417AYgZOuGaYQAI5BMIjRZZ3JTzO\/QsmkzeS1tFuBlih8li\/t4l\r\nE2TdnKhy376A6QWfbTDkJN6gzFeaMKwe98mOHKeq0KZITGYVTSa2AYH5zaro0Yku\r\nonOH1NdyEKFFgxGLg7wveYUW\r\n-----END PRIVATE KEY-----
    ```

    ##### Create a new client

    To create a new client, make a POST call to the [`/clients`](https://auth0.com/docs/api/management/v2/clients/post-clients) endpoint with the following payload:

    * `$client_name`**:** the name for the new client
    * `$credential_name`**:** the name for the public key
    * `$credential_certificate`: the content of `$certificate_pem`generated in the previous step

    ```bash lines theme={null}
    curl --location --request POST 'https://$tenant/api/v2/clients' \
      --header 'Authorization: Bearer $management_access_token' \
      --header 'Content-Type: application/json' \
      --data-raw '{
      "name": "$client_name",
      "app_type": "non_interactive",
      "client_authentication_methods": {
        "self_signed_tls_client_auth": {
          "credentials": [{ 
            "name": "$credential_name", 
            "credential_type": "x509_cert", 
            "pem": "$credential_certificate"
          }]
        }
      },
      "jwt_configuration": {
        "alg": "RS256"
      }
    }'
    ```

    For more information, see the [Create a client](https://auth0.com/docs/api/management/v2/clients/post-clients) API documentation.

    ##### Patch an existing client

    You can update an existing client to accept mTLS client authentication by removing any value in the `token_endpoint_auth_method` field and creating values in the `client_authentication_methods` field.

    <Warning>
      Once you have configured your client for mTLS, you won't be able to authenticate using the Client Secret unless you configure the `token_endpoint_auth_method` to stop using mTLS. To learn more, read [Revert a client to use a Client Secret](#revert-a-client-to-use-a-client-secret).
    </Warning>

    ##### Create the credential resource

    After you generate a certificate, create the credential resource:

    ```bash lines theme={null}
    curl --location --request POST 'https://$tenant/api/v2/clients/$client_id/credentials' \
      --header 'Authorization: Bearer $management_access_token' \
      --header 'Content-Type: application/json' \
      --data-raw '{
      "name": "$credential_name", 
      "credential_type": "x509_cert", 
      "pem": "$credential_certificate"
    }'
    ```

    Auth0 returns a credential ID in the response that you will need to associate the credential with the client.

    For more information, see the [Create a client credential](https://auth0.com/docs/api/management/v2/clients/post-credentials) API documentation.

    ##### Associate the credential with the client and disable `token_endpoint_auth_method`

    Uploaded credentials are not automatically enabled for client authentication. You need to update the client authentication to use the new self-signed client certificate.

    The following PATCH request sets the `token_endpoint_auth_method` to `null`, thus disabling Client Secret authentication. It also updates `client_authentication_methods` with the credential ID:

    ```bash lines theme={null}
    curl --location --request PATCH 'https://$tenant/api/v2/clients/$client_id' \
      --header 'Authorization: Bearer $management_access_token' \
      --header 'Content-Type: application/json' \
      --data-raw '{
      "token_endpoint_auth_method": null, 
      "client_authentication_methods": {
        "self_signed_tls_client_auth": {
          "credentials": [{ "id": $credential.id }]
        }
      }
    }'
    ```

    Once this request has completed, a Client Secret will no longer be accepted and clients must authenticate using mTLS.

    For more information, see the [Update a client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) API documentation.

    #### Certificate authority signed certificates

    Unlike self-signed certificates that are generated by the client and have no trust chain, certificate authority (CA) signed certificates are considered more trustworthy since they are issued by a trusted third party. CA-signed certificates are the only type of certificate accepted by some cloud providers such as Amazon.

    CA-signed certificates have embedded in their identity information the notion of a Distinguished Name (DN). While each individual certificate created by a given CA is unique, they can share a common DN. When using CA-signed certificates, Auth0 stores the DN and compares forwarded client certificates with registered DNs.

    ##### Generate a certificate

    The method of generating a CA-signed client certificate is highly dependent on the Public Key Infrastructure and outside of the scope of this document. We recommend generating at least a [2048-bit RSA key pair](/docs/secure/application-credentials/generate-rsa-key-pair).

    ##### Create a new client

    To create a client, make a POST call to the [`/clients`](https://auth0.com/docs/api/management/v2/clients/post-clients) endpoint with the following payload:

    * `$client_name`**:** the name for the new client
    * `$credential_name`**:** the name for the public key
    * `$credential_certificate`: the content of `$certificate_pem`generated by the CA

    ```bash lines theme={null}
    curl --location --request POST 'https://$tenant/api/v2/clients' \
      --header 'Authorization: Bearer $management_access_token' \
      --header 'Content-Type: application/json' \
      --data-raw '{
      "name": "$client_name",
      "app_type": "non_interactive",
      "client_authentication_methods": {
        "tls_client_auth": {
          "credentials": [{ 
            "name": "$credential_name", 
            "credential_type": "cert_subject_dn", 
            "pem": "$credential_certificate"
          }]
        }
      },
      "jwt_configuration": {
        "alg": "RS256"
      }
    }'
    ```

    Instead of passing the full PEM file, you can also pass the subject DN. The subject DN must match the extracted Distinguished Name (DN) of the client certificates sent during the mTLS handshake.

    <Callout icon="file-lines">
      Subject DN extraction may differ between different ecosystems. The most reliable way to guarantee that the authorization server will match the subject DN is to upload the whole PEM file.
    </Callout>

    The following POST request creates a new client with the subject DN:

    ```bash lines theme={null}
    curl --location --request POST 'https://$tenant/api/v2/clients' \
      --header 'Authorization: Bearer $management_access_token' \
      --header 'Content-Type: application/json' \
      --data-raw '{
      "name": "$client_name",
      "app_type": "non_interactive",
      "client_authentication_methods": {
        "tls_client_auth": {
          "credentials": [{ 
            "name": "$credential_name", 
            "credential_type": "cert_subject_dn", 
            "subject_dn": "C=XX\nST=StateName\nL=CityName\nO=CompanyName\nOU=CompanySectionName\nCN=CommonNameOrHostname"
          }]
        }
      },
      "jwt_configuration": {
        "alg": "RS256"
      }
    }'
    ```

    For more information, see the [Create a client](https://auth0.com/docs/api/management/v2/clients/post-clients) API documentation.

    ##### Patch an existing client

    If you don’t want to create a new client to use mTLS, you can update an existing client to accept mTLS client authentication. This involves removing any value in the `token_endpoint_auth_method` field and creating values in the `client_authentication_methods` field.

    <Warning>
      Once you have configured your client for mTLS, you won't be able to authenticate using the Client Secret unless you configure the `token_endpoint_auth_method` to stop using mTLS. To learn more, read [Revert a client to use a Client Secret](#revert-a-client-to-use-a-client-secret).
    </Warning>

    ##### Create the credential resource

    Once you have [generated a key pair](/docs/secure/application-credentials/generate-rsa-key-pair) exclusively for mTLS, create the credential resource. Make the following POST request to the `/clients` endpoint:

    ```bash lines theme={null}
    curl --location --request POST 'https://$tenant/api/v2/clients/$client_id/credentials' \
      --header 'Authorization: Bearer $management_access_token' \
      --header 'Content-Type: application/json' \
      --data-raw '{
      "name": "$credential_name", 
      "credential_type": "cert_subject_dn", 
      "pem": "$credential_certificate"
    }'
    ```

    Instead of passing the full PEM file, you can pass the subject DN. The subject DN must match the extracted Distinguished Name (DN) of the client certificates sent during the mTLS handshake.

    The following code sample creates the credential resource using the Subject DN:

    ```bash lines theme={null}
    curl --location --request POST 'https://$tenant/api/v2/clients/$client_id/credentials' \
      --header 'Authorization: Bearer $management_access_token' \
      --header 'Content-Type: application/json' \
      --data-raw '{
      "name": "$credential_name", 
      "credential_type": "cert_subject_dn", 
      "subject_dn": "C=XX\nST=StateName\nL=CityName\nO=CompanyName\nOU=CompanySectionName\nCN=CommonNameOrHostname"
    }'
    ```

    When using either method, remember that the credential ID that gets returned in the response is needed to associate the credential with the client.

    For more information, see the [Create a client credential](https://auth0.com/docs/api/management/v2/clients/post-credentials) API documentation.

    ##### Associate the credential with the client and disable `token_endpoint_auth_method`

    Although we have created the credential, we have not yet associated the credential with the client.

    To do so, update  `client_authentication_methods` by making the following PATCH request to the `/clients` endpoint. In the same request, set `token_endpoint_auth_method` to `null`:

    ​​

    ```bash lines theme={null}
    curl --location --request PATCH 'https://$tenant/api/v2/clients/$client_id' \
      --header 'Authorization: Bearer $management_access_token' \
      --header 'Content-Type: application/json' \
      --data-raw '{
      "token_endpoint_auth_method": null, 
      "client_authentication_methods": {
        "tls_client_auth": {
          "credentials": [{ "id": $credential.id }]
        }
      }
    }'
    ```

    Once this request has completed, the client can only be authenticated using mTLS.

    For more information, see the [Update a client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) API documentation.

    #### Revert a client to use a Client Secret

    To restore your client’s configuration to authenticate using a Client Secret, disable `client_authentication_methods` and re-enable `token_endpoint_auth_method` with your desired authentication method.

    In the following PATCH request, set `token_endpoint_auth_method` to `client_secret_post` to re-enable Client Secret authentication:

    ```bash lines theme={null}
    curl --location --request PATCH 'https://$tenant/api/v2/clients/$client_id' \
      --header 'Authorization: Bearer $management_access_token' \
      --header 'Content-Type: application/json' \
      --data-raw '{
      "token_endpoint_auth_method": "client_secret_post", 
      "client_authentication_methods": null
    }'
    ```

    For more information, see the [Update a client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) API documentation.
  </Tab>
</Tabs>

## Learn more

* [Authenticate with mTLS](/docs/get-started/authentication-and-authorization-flow/authenticate-with-mtls)
* [Set up the Customer Edge](/docs/get-started/applications/configure-mtls/set-up-the-customer-edge)
* [Configure mTLS Authentication for a Tenant](/docs/get-started/applications/configure-mtls/configure-mtls-for-a-tenant)


# Configure mTLS Authentication for a Tenant
Source: https://auth0.com/docs/get-started/applications/configure-mtls/configure-mtls-for-a-tenant

Describes how to configure mTLS Authentication for a tenant.

Learn how to configure mTLS authentication for a tenant.

<Callout icon="file-lines">
  The following examples specify **\$management\_access\_token**, or a [Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens). This must be replaced with an access token that contains at least the following scopes:

  * `create:custom_domains`
  * `read:custom_domains`
  * `create:clients`
  * `update:clients`
  * `update:client_credentials`
  * `update:client_keys`
  * `update:tenant_settings`

  To learn more about retrieving an access token with the required scopes, read [Get Access Tokens](/docs/secure/tokens/access-tokens/get-access-tokens).
</Callout>

To begin, you must configure and verify a [custom domain](/docs/customize/custom-domains).

### Create a custom domain

At the tenant level, you must configure a [custom domain](/docs/customize/custom-domains) to accept mTLS headers with the [Management API](https://auth0.com/docs/api/management/v2). Because the [customer edge](/docs/get-started/applications/configure-mtls/set-up-the-customer-edge) is responsible for validating the client certificates, set the `type` as `self_managed_certs` in the POST request:

```bash lines theme={null}
curl --location --request POST 'https://$tenant/api/v2/custom-domains' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "domain":"string",
  "type":"self_managed_certs",
  "verification_method":"txt", 
  "tls_policy":"recommended",
  "custom_client_ip_header":"true-client-ip"
}'
```

A successful request returns an identifier that is used to verify the <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip>. For more information, see the [Configure a new custom domain](https://auth0.com/docs/api/management/v2/custom-domains/post-custom-domains) API documentation.

### Patch an existing custom domain

You can configure an existing custom domain to accept mTLS headers with the [Management API](https://auth0.com/docs/api/management/v2). However, you cannot update the `type` for an already existing custom domain.

<Callout icon="file-lines">
  Only custom domains with the `self_managed_certs` type can be used for mTLS. Auth0 currently does not support the `auth0_managed_certs` type for mTLS.
</Callout>

The following POST request configures an existing custom domain to accept mTLS headers:

```bash lines theme={null}
curl --location --request POST 'https://$tenant/api/v2/custom-domains/:id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "tls_policy":"recommended",
  "custom_client_ip_header":"true-client-ip"
}'
```

For more information, see the [Update custom domain configuration](https://auth0.com/docs/api/management/v2/custom-domains/patch-custom-domains-by-id) API documentation.

### Verify the custom domain

Before Auth0 accepts requests to create and update the custom domain, it must first verify the domain. Use the [Management API](https://auth0.com/docs/api/management/v2) to send the following POST request to verify the custom domain:

```bash wrap lines theme={null}
curl --location --request POST 'https://$tenant/api/v2/custom-domains/:id/verify'
```

Check the `status` field to see its verification status. Once verification is complete, it may take up to 10 minutes before the custom domain can start accepting requests.

When Auth0 verifies the custom domain for the first time, the response includes the `cname_api_key`, which you need to configure your edge/reverse proxy. This key must be kept secret and is used to validate the forwarded requests.

For more information, see the [Verify a custom domain](https://auth0.com/docs/api/management/v2/custom-domains/patch-custom-domains-by-id) API documentation.

### Enable mTLS endpoint aliases

When the mTLS handshake requests a client certificate from the client, the web browser presents users with a modal dialog to select a certificate. This introduces friction in the user experience and should be avoided for endpoints where mTLS is unnecessary such as the `/authorize` endpoint. As a result, customers that support mTLS and non-mTLS traffic on different domains should enable mTLS endpoint aliases.

mTLS endpoint aliases indicate that clients should send mTLS traffic to the endpoints specified in the `mtls_endpoint_aliases` property of the OIDC discovery document. Clients will send non-mTLS traffic to the normal endpoints. For more information about the `mtls_endpoint_aliases` property, see [Call the resource server](/docs/get-started/authentication-and-authorization-flow/authenticate-with-mtls#call-the-resource-server).

You can enable mTLS endpoint aliases with the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> and the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

<Tabs>
  <Tab title="Auth0 Dashboard">
    To enable mTLS endpoint aliases using the Auth0 Dashboard:

    1. Navigate to [Auth0 Dashboard](https://manage.auth0.com/#/tenant/general) and select **Settings** from the side menu.
    2. Under Tenant Settings, select the **Advanced** tab.
    3. Find **Allow mTLS Endpoint Aliases** and toggle it on. This will route mTLS traffic to an endpoint called `mtls.<your custom domain>`**.**
  </Tab>

  <Tab title="Management API">
    To enable mTLS endpoint aliases using the [Management API](https://auth0.com/docs/api/management/v2), set the `enable_endpoint_aliases` property to `true` for your tenant:

    ```bash lines theme={null}
    curl --location --request PATCH 'https://$tenant/api/v2/tenants/settings' \
      --header 'Authorization: Bearer $management_access_token' \
      --header 'Content-Type: application/json' \
      --data-raw '{
      "mtls": {
        "enable_endpoint_aliases": true
      }
    }'
    ```

    mTLS endpoint aliases add the `mtls.` prefix to the configured custom domain. For example, if the configured custom domain is `auth.saasapp.com`, the mTLS endpoint aliases will use the domain `mtls.auth.saasapp.com`. Depending on feedback, customers may be able to configure the mTLS endpoint aliases in the future.

    <Warning>
      The mTLS subdomain is outside of Auth0’s control. Administrators must be aware of the risks of subdomains and act accordingly. This includes, but is not limited to:

      * Ensuring the ownership and ability to administer the top-level domain and subdomains used with mTLS. Failure to do so could result in the loss of both the login handler and the mTLS subdomain. This is especially important when using [custom domains](/docs/customize/custom-domains).
      * Ensuring that you have a SSL certificate for the mTLS subdomain i.e. `mtls.auth.saasapp.com`. A wildcard certificate for `*.saasapp.com` does not include the mTLS subdomain.

      Preventing subdomain takeovers due to dangling DNS entries if an IP is no longer in use. For more information, see the Mozilla Developer Network (MDN) [Subdomain takeovers](https://developer.mozilla.org/en-US/docs/Web/Security/Subdomain_takeovers) documentation.
    </Warning>

    To disable mTLS endpoint aliases, set the `enable_endpoint_aliases` value to `false`. For more information, see the [Update tenant settings](https://auth0.com/docs/api/management/v2/tenants/patch-settings) API documentation.
  </Tab>
</Tabs>

## Learn more

* [Authenticate with mTLS](/docs/get-started/authentication-and-authorization-flow/authenticate-with-mtls)
* [Set up the Customer Edge](/docs/get-started/applications/configure-mtls/set-up-the-customer-edge)
* [Configure mTLS Authentication for a Client](/docs/get-started/applications/configure-mtls/configure-mtls-for-a-client)


# Set up the Customer Edge
Source: https://auth0.com/docs/get-started/applications/configure-mtls/set-up-the-customer-edge

Learn how to set up your customer edge for mTLS authentication.

This section explains how to set up the customer edge network. The specifics of configuring different edge networks are out of the scope of this document. For more information, see the [custom domains](/docs/customize/custom-domains) documentation.

The customer’s edge domain must match the registered <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip>. If mTLS endpoint aliases are enabled, the customer edge must also accept requests on the subdomain used by the mTLS aliases. All requests that arrive at the mTLS subdomain should request a client TLS certificate and verify that the certificate is registered for use. For more information, see [Verify the client certificate](#verify-the-client-certificate).

The mTLS handshake occurs before the edge infrastructure can determine the requested path. Once the TLS session is established, the customer may wish to inspect the path and only forward requests for the following endpoints:

* `/oauth/token`
* `/oauth/par`
* `/userinfo`

If your installation aims for FAPI compliance, additional requirements related to TLS are placed on your edge network. For more information, see the [FAPI1 Baseline](https://openid.net/specs/openid-financial-api-part-1-1_0.html#tls-and-dnssec-considerations), [FAPI1 Advanced](https://openid.net/specs/openid-financial-api-part-2-1_0.html#tls-considerations), and [FAPI2 Baseline](https://openid.net/specs/fapi-2_0-baseline.html#name-network-layer-protections) specifications.

## Verify the client certificate

The customer edge network performs validations that depend on the expected type of the client certificate. To avoid common security problems and pitfalls, use a well-vetted certificate validation library when possible. When the client certificate fails validation, the expected behavior is dependent on the installation and outside of the scope of this document.

### CA-signed certificates

When a certificate is signed by a certificate authority, the trust chain of the certificate must be verified, including the root certificate. The certificate may also be compared against an allow or deny list to ensure the certificate is registered and has not been revoked. We recommend you do **not** use a public certificate authority to sign your client certificates as it may increase the risk of your client applications being impersonated.

### Self-signed certificates

Self-signed certificates are not backed by a chain of trust so a certificate chain cannot be checked. Instead, the certificate thumbprint could be checked against a registered certificate database or forwarded directly to Auth0 to perform this check.

## Forward the request

Once the certificate is verified, requests are forwarded along with several special headers from the customer to the same endpoint on the custom domain’s forwarding target at [Auth0's edge network](/docs/customize/custom-domains/self-managed-certificates). The forwarded request must include the following headers:

* The Custom Domain API key as the `cname-api-key` header.
* The client certificate as the `client-certificate` header. **Note**: Since HTTP headers must be text, the certificate must be converted to a URL component encoded PEM. The header value is limited to 4096 bytes. Therefore, only the first certificate in the chain should be forwarded to Auth0.
* The client certificate CA verification status as the `client-certificate-ca-verified` header. The `client-certificate-ca-verified` header can have the following values:

  * **SUCCESS**: indicates that the client certificate is valid and has been verified by a certificate authority.
  * **FAILED:** indicates that the presented client certificate is valid, however the certificate's trust chain has NOT been verified by a certificate authority. In other words, it’s a self-signed certificate. May include an optional failure reason.

If your configuration supports only CA-signed certificates, you don't need to forward self-signed certificates to the Auth0 edge network, and you can terminate the request earlier. However, if your clients are configured to authenticate using self-signed certificates, Auth0 expects your network edge to send a `client-certificate-ca-verified:FAILED` header. Depending on this header value, Auth0 knows which client authentication method has been used and which client credentials need to be verified against.

## Learn more

* [Authenticate with mTLS](/docs/get-started/authentication-and-authorization-flow/authenticate-with-mtls)
* [Configure mTLS Authentication for a Tenant](/docs/get-started/applications/configure-mtls/configure-mtls-for-a-tenant)
* [Configure mTLS Authentication for a Client](/docs/get-started/applications/configure-mtls/configure-mtls-for-a-client)


# Configure Pushed Authorization Requests (PAR)
Source: https://auth0.com/docs/get-started/applications/configure-par

Learn how to configure Pushed Authorization Requests (PAR) for your application.

<Callout icon="file-lines">
  To use Highly Regulated Identity features, you must have an Enterprise Plan with the Highly Regulated Identity add-on. Refer to [Auth0 Pricing](https://auth0.com/pricing/) for details.
</Callout>

The Auth0 Push Authorization Request (PAR) implementation is based on the [OAuth RFC9126: Push Authorization Request](https://www.rfc-editor.org/rfc/rfc9126.html) specification. For more information, see [Authorization Code Flow with Pushed Authorization Requests](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-par).

By default, PAR is not enabled by your tenant. You can enable it in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> under your tenant settings. To learn more, read [Enable PAR for a tenant](#enable-par-for-a-tenant).

After enabling PAR for your tenant, you can send authorization requests to both the `/oauth/par` and the `/authorize` endpoints. However, to fully secure your <Tooltip href="/docs/glossary?term=authorization+flow">authorization flow</Tooltip>, set PAR as required for an application via the [Management API](https://auth0.com/docs/api/management/v2) or **Application Settings** on the Auth0 Dashboard.

## Enable PAR for a tenant

To enable PAR for a tenant, use the [Auth0 Dashboard](https://manage.auth0.com/).

1. Navigate to Auth0 Dashboard > Settings > Advanced.

2. Scroll down to **Settings** and toggle on **Allow Pushed Authorization Requests (PAR)**.

<Frame>
  <img alt="" />
</Frame>

## Require PAR for an application

<Tabs>
  <Tab title="Auth0 Dashboard">
    <Callout icon="file-lines">
      Your tenant must have **Allow Pushed Authorization Requests (PAR)** enabled at the tenant-level before enabling PAR at the application-level.
    </Callout>

    1. Navigate to Auth0 Dashboard > Applications.
    2. Select the application.
    3. Select the **Application Settings** tab.
    4. In the **Authorization Requests** section, enable the toggle **Require Pushed Authorization Requests (PAR)**.
  </Tab>

  <Tab title="Management API">
    <Callout icon="file-lines">
      Your tenant must have **Allow Pushed Authorization Requests (PAR)** enabled at the tenant-level before enabling PAR at the application-level.
    </Callout>

    Use the following code sample to configure PAR for your application using the Management API:

    ```bash lines theme={null}
    curl -X PATCH --location 'https://TENANT.auth0.com/api/v2/clients/CLIENT_ID' \
      --header 'Authorization: Bearer MANAGEMENT_ACCESS_TOKEN' \
      --header 'Content-Type: application/json' \
      --data-raw '{
       "require_pushed_authorization_requests": true
    }'
    ```
  </Tab>
</Tabs>

## Learn more

* [Authorization Code Flow with Pushed Authorization Requests (PAR)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-par)


# Configure Private Key JWT Authentication
Source: https://auth0.com/docs/get-started/applications/configure-private-key-jwt

Describes how to configure new and existing applications to use Private Key JWT Authentication.

<Callout icon="file-lines">
  Private Key JWT is available for customers on the Enterprise plan. To upgrade, contact [Auth0 pricing](https://auth0.com/pricing/).
</Callout>

Private Key <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> Authentication supports [OIDC Connect Core Client Authentication 1.0](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication) client authentication using JWT assertions signed with asymmetric key pairs. You can create a new application to use `private_key_jwt` or enable existing applications to use private key pairs for authentication.

## Prerequisites

Before configuring an application that authenticates using Private Key JWT, you must [generate an RSA key pair](/docs/secure/application-credentials/generate-rsa-key-pair).

## Configure Private Key JWT

<Tabs>
  <Tab title="Auth0 Dashboard">
    You can use the Auth0 Dashboard to create a new application and configure the credentials or update an existing application.

    We recommend you securely store the current `client_secret` parameter before you set your application credential method to Private Key JWT. The `client_secret` parameter will be hidden once the Private Key JWT configuration is complete.

    #### Configure a new application for `private_key_jwt`

    1. Navigate to [**Auth0 Dashboard > Applications > Application**](https://manage.auth0.com/#/applications).
    2. Select **Create Application**.
    3. Choose your application type.
    4. Under the application settings, select the **Credentials** tab.
    5. Under **Authentication Methods**, select **Private Key JWT**.

       <Frame>
         <img alt="Configure Private Key JWT Authentication - Auth0 Dashboard instructions" />
       </Frame>
    6. Configure credential details:

       1. Enter a name for the credential.
       2. Upload your PEM format or X.509 certificate.
       3. Select the algorithm to sign the assertions.
       4. Optional: Enable custom expiration. Select **Set an explicit expiry date for this Credential** and set a future date.

          <Warning>
            You may receive an invalid certificate error if you are submitting an malformed key material, to avoid any issues it’s best to upload the file directly created by openssl.
          </Warning>
    7. Select **Add Credential**.

    #### Configure an existing application

    1. Navigate to [Auth0 Dashboard > Applications](http://manage.auth0.com/#/applications).
    2. Select the application you want to update.
    3. Select the **Credentials** tab.
    4. Choose **Private Key JWT**.
    5. Configure credential details:

       1. Enter a name for the credential.
       2. Upload your PEM format or X.509 certificate.
       3. Select the algorithm to sign the assertions.
       4. Optional: Enable custom expiration. Select **Set an explicit expiry date for this Credential** and set a future date.
    6. Select **Add Credential**.

    #### Configure an application to use Client Secret authentication

    1. Navigate to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/dashboard/#/applications/) and select the application you want to update.
    2. Select the **Credentials** tab.
    3. Choose **Client Secret (Post)** or **Client Secret (Basic)**.
    4. Select **Save**.

    #### Update credential expiration

    You can update an existing credential with an expiration date with Auth0 Dashboard.

    1. Navigate to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/dashboard/#/applications/) and select the application you want to update.
    2. Select the **Credentials** tab.
    3. Choose the credential you want to update and select **Edit Credential**.

       <Frame>
         <img alt="Dashboard - Applications - Application Settings - Credentials - update expiry date" />
       </Frame>
    4. Select **Set an explicit expiry date for this Credential** and set a future date.
    5. Select **Update Credential**.
  </Tab>

  <Tab title="Management API">
    #### Configure a new application for `private_key_jwt`

    You can create a new application with `private_key_jwt` as the authentication method using the Management API. Make a `POST` call to the [`Create a Client`](https://auth0.com/docs/api/management/v2#!/Clients/get_clients) endpoint with the following payload:

    ```bash lines theme={null}
    curl --location --request POST 'https://{domain}/api/v2/clients' \
      --header 'Authorization: Bearer {managementApiAccessToken} \
      --header 'Content-Type: application/json' \
      --data-raw '{
     "name": "{clientName}",
     "app_type": "non_interactive",
     "client_authentication_methods": {
       "private_key_jwt": {
         "credentials": [
           { 
              "name": "{credentialName}", 
              "credential_type": "public_key", 
              "pem": "{credentialublicKey}",
              "alg": "{algorithm}",
              "expires_at": "{expiresAt}"
           }
         ]
       },
       "jwt_configuration": {
         "alg": "RS256"
       }
     }
    }'
    ```

    <table>
      <thead>
        <tr>
          <th>Parameter</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>algorithm</code></td>
          <td>Algorithm used to sign assertions. Supported values are RS256, RS384 and PS256. If not specified, the algorithm will default to RS256.</td>
        </tr>

        <tr>
          <td><code>clientName</code></td>
          <td>Name for your new client.</td>
        </tr>

        <tr>
          <td><code>credentialName</code></td>
          <td>Name for the public key.</td>
        </tr>

        <tr>
          <td><code>expires\_at</code></td>
          <td>Optional.  Expiration date of the credential in ISO 8601 format. For example, <code>2020-08-20T19:10:06.299Z</code>. Once the expiration date passes, the credential is no longer valid.</td>
        </tr>

        <tr>
          <td><code>managementApiAccessToken</code></td>
          <td><a href="/docs/secure/tokens/access-tokens/management-api-access-tokens">Access token for the Management API</a> with the scope <code>create:credentials</code>.</td>
        </tr>

        <tr>
          <td><code>pem</code></td>
          <td>Public key, or x.509 certificate, encoded in PEM format.</td>
        </tr>

        <tr>
          <td><code>parse\_expiry\_from\_cert</code></td>
          <td>Optional. A boolean that indicates that Auth0 should parse the expiry when provided a certificate. If a certificate is not provided, Auth0 will return an error. <code>parse\_expiry\_from\_cert</code> and <code>expires\_at</code> are also mutually exclusive. In this case, Auth0 will return an error.</td>
        </tr>
      </tbody>
    </table>

    <Callout icon="file-lines">
      The public key PEM should be JSON escaped before being passed to Auth0, in our example, this is the content we need to pass:

      `-----BEGIN PUBLIC KEY-----
            MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA53VzmIVVZZWyNm266l82
            mnoDc9g/snXklax5kChEhqK/WnTUvuXP4Gd4THj8rchxgUGKXd4PF3SUcKyn/qPm
            Tet0idVHk2PwP//FOVgYo5Lb04js0pgZkbyB/WjuMp1w+yMuSn0NYAP7Q9U7DfTb
            jmox8OQt4tCB4m7UrJghGqT8jkPyZO/Ka6/XsyjTYPOUL3t3PD7JShVAgo1mAY6g
            Sr4SORywIiuHsg+59ad7MXGy78LirhtqAcDECKF7VZpxMuEjMLg3o2yzNUeWI2Mg
            IF+t0HbO1E387fvLcuSyai1yWbSr1PXyiB2aXyDpbD4u7d3ux4ahU2opH11lBqvx
            +wIDAQAB -----END PUBLIC KEY-----`
    </Callout>

    The response contains the `client_id` property which will link your application to the resource server. The response also contains a generated `kid` for the credential you created. This will be used later to generate the `client_assertion`.

    <Callout icon="file-lines">
      Auth0 follows the [JSON Web Key Thumbprint](https://datatracker.ietf.org/doc/html/rfc7638) standard to generate the kid of your credentials.

      The kid consists of a base64URL encoded SHA256 digest of of the JWK representation of your public key.
    </Callout>

    #### Configure an existing application

    You can also configure an existing application to use Private Key JWT Authentication with the Auth0 Management API. You will need to remove any values in the `token_endpoint_auth_method` field and create values in the `client_authentication_methods` field.

    <Warning>
      If you update an existing production application to authenticate with `private_key_jwt`, we recommend you securely store your current `client_secret` value for future reference.

      After you configure private\_key\_jwt, you won't be able to access the client\_secret value unless you restore your application's configuration to use a Client Secret.
    </Warning>

    ##### Create the credential resource

    Once you have generated a key pair, create the credential resource. Make the following POST request to the Management API’s [`/clients`](https://auth0.com/docs/api/management/v2#!/Clients/post_clients) endpoint.

    ```bash lines theme={null}
    curl --location --request POST 'https://{domain}/api/v2/clients/{clientId}/credentials' \
      --header 'Authorization: Bearer {managementApiAccessToken} \
      --header 'Content-Type: application/json' \
      --data-raw '{
              "name": "{credentialName}", 
              "credential_type": "public_key", 
              "pem": "{credentialPublicKey}",
              "alg": "{algorithm}",
              "expires_at ": "{expiresAt}",
    }'
    ```

    <table>
      <thead>
        <tr>
          <th>Parameter</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>algorithm</code></td>
          <td>Algorithm used to sign assertions. Supported values are RS256, RS384 and PS256. If not specified, the algorithm default is RS256.</td>
        </tr>

        <tr>
          <td><code>clientId</code></td>
          <td>ID of the application to be updated.</td>
        </tr>

        <tr>
          <td><code>credentialName</code></td>
          <td>Name of the public key.</td>
        </tr>

        <tr>
          <td><code>managementApiAccessToken</code></td>
          <td><a href="/docs/secure/tokens/access-tokens/management-api-access-tokens">Access token for the Management API</a> with the scope <code>create:credentials</code>.</td>
        </tr>

        <tr>
          <td><code>pem</code></td>
          <td>Public key, or x.509 certificate, encoded in PEM format.</td>
        </tr>

        <tr>
          <td><code>expires\_at</code></td>
          <td>Optional.  Expiration date of the credential in ISO 8601 format. For example, <code>2020-08-20T19:10:06.299Z</code>. Once the expiration date passes, the credential is no longer valid.</td>
        </tr>

        <tr>
          <td><code>parse\_expiry\_from\_cert</code></td>
          <td>Optional. A boolean that indicates that Auth0 should parse the expiry when provided a certificate. If a certificate is not provided, Auth0 will return an error. <code>parse\_expiry\_from\_cert</code> and <code>expires\_at</code> are mutually exclusive. In this case, Auth0 will return an error.</td>
        </tr>
      </tbody>
    </table>

    <Callout icon="file-lines">
      The PEM public key should be JSON-escaped before being passed to Auth0. In this example, the content we need to pass is:

      ```pem lines theme={null}
      ----BEGIN PUBLIC KEY-----
      MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA53VzmIVVZZWyNm266l82
      mnoDc9g/snXklax5kChEhqK/WnTUvuXP4Gd4THj8rchxgUGKXd4PF3SUcKyn/qPm
      Tet0idVHk2PwP//FOVgYo5Lb04js0pgZkbyB/WjuMp1w+yMuSn0NYAP7Q9U7DfTb
      jmox8OQt4tCB4m7UrJghGqT8jkPyZO/Ka6/XsyjTYPOUL3t3PD7JShVAgo1mAY6g
      Sr4SORywIiuHsg+59ad7MXGy78LirhtqAcDECKF7VZpxMuEjMLg3o2yzNUeWI2Mg
      IF+t0HbO1E387fvLcuSyai1yWbSr1PXyiB2aXyDpbD4u7d3ux4ahU2opH11lBqvx
      +wIDAQAB
      -----END PUBLIC KEY-----
      ```
    </Callout>

    A credential ID returns in the response. Use the ID for the next step.

    ##### Associate the credential

    After you create the credential, associate it with your application. Your application uses these credentials during authentication with `private_key_jwt`.

    Make a PATCH request to the Management API [`Update a Client`](https://auth0.com/docs/api/management/v2#!/Clients/patch_clients_by_id) endpoint:

    ```bash lines theme={null}
    curl --location --request PATCH 'https://{domain}/api/v2/clients/{clientId} \
      --header 'Authorization: Bearer {managementApiAccessToken} \
      --header 'Content-Type: application/json' \
      --data-raw '{
              "token_endpoint_auth_method": null, 
              "client_authentication_methods": {
                 "private_key_jwt": {
                    "credentials": [{ "id": {credentialId} }]
                 }
              }
       }​​'​​
    ```

    <table>
      <thead>
        <tr>
          <th>Parameter</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>clientId</code></td>
          <td>ID of the application to be updated.</td>
        </tr>

        <tr>
          <td><code>managementApiAccessToken</code></td>
          <td><a href="/docs/secure/tokens/access-tokens/management-api-access-tokens">Access token for the Management API</a> with the scope <code>update:client</code> and <code>update:credentials</code>.</td>
        </tr>

        <tr>
          <td><code>credentialId</code></td>
          <td>ID of the credential you created.</td>
        </tr>

        <tr>
          <td><code>pem</code></td>
          <td>The public key in PEM format.</td>
        </tr>
      </tbody>
    </table>

    <Warning>
      Auth0 does not support use of HS256 as the applications’s JWT signing algorithm. You must have the `jwt_configuration.alg` field set to the RS256 algorithm. To learn how to change the signing algorithm, read [Change Application Signing Algorithms](/docs/get-started/applications/change-application-signing-algorithms).
    </Warning>

    #### Configure an application to use Client Secret authentication

    To restore your application’s configuration to use a Client Secret, you must disable `client_authentication_methods` and re-enable `token_endpoint_auth_method` with the authentication method.

    <Warning>
      Once you have configured your authentication method as `client_secret`, your applications will no longer be able to authenticate using `private_key_jwt` until you have updated them to authenticate using `client_secret`.
    </Warning>

    **Example**

    ```bash lines theme={null}
    curl --location --request PATCH 'https://{domain}/api/v2/clients/{clientId} \
      --header 'Authorization: Bearer {managementApiAccessToken} \
      --header 'Content-Type: application/json' \
      --data-raw '{
              "token_endpoint_auth_method": "{tokenEndpointAuthMethod}", 
              "client_authentication_methods": null
       }​​'​​
    ```

    <table>
      <thead>
        <tr>
          <th>Parameter</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>clientId</code></td>
          <td>ID of the updated application.</td>
        </tr>

        <tr>
          <td><code>managementApiAccessToken</code></td>
          <td><a href="/docs/secure/tokens/access-tokens/management-api-access-tokens">Access token for the Management API</a> with the scopes <code>update:client</code> and <code>update:credentials</code>.</td>
        </tr>

        <tr>
          <td><code>tokenEndpointAuthMethod</code></td>
          <td>Final authentication method. For example: <code>client\_secret\_basic</code> or <code>client\_secret\_post</code>.</td>
        </tr>
      </tbody>
    </table>

    #### Patch credentials with an expiration field

    You can update an existing credential with an expiration date with the Management API [Update a credential](https://auth0.com/docs/api/management/v2#!/Clients/patch_credentials_by_credential_id) endpoint.

    ```bash lines theme={null}
    curl --location --request PATCH 'https://{domain}/api/v2/clients/{clientId}/credentials/{credentialId} ' \
      --header 'Authorization: Bearer {managementApiAccessToken} \
      --header 'Content-Type: application/json' \
      --data-raw '{
              "expires_at": {expiresAt}
       }'
    ```

    <table>
      <thead>
        <tr>
          <th>Parameter</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>managementApiAccessToken</code></td>
          <td>Access tokens for the Management API with the scopes <code> update:credentials</code>.</td>
        </tr>

        <tr>
          <td><code>clientId</code></td>
          <td>The client you want to update.</td>
        </tr>

        <tr>
          <td><code>expires\_at</code></td>
          <td>The expiration date of the credential in ISO 8601 format. For example, <code>2020-08-20T19:10:06.299Z</code>.</td>
        </tr>
      </tbody>
    </table>

    The only field you can update is the `expires_at` field. The rest of the attributes are immutable and require you to rotate the credential to change.
  </Tab>
</Tabs>

## Credential limits

Auth0 enforces a minimum RSA key size of 2048 bits and a maximum key size of 4096 bits. Applications can have a maximum of two credentials configured.

## Rotate credentials

To prevent leaked keys, Auth0 recommends you periodically rotate the key pair. To learn how, read [Rotate Credentials](/docs/get-started/applications/rotate-credentials).

## Learn more

* [Application Credentials](/docs/secure/application-credentials)
* [Credential Settings](/docs/get-started/applications/credentials)
* [Authenticate with Private Key JWT](/docs/get-started/authentication-and-authorization-flow/authenticate-with-private-key-jwt)


# Configure WS-Fed Applications
Source: https://auth0.com/docs/get-started/applications/configure-ws-fed-applications

Describes how to configure a WS-Fed application to use Auth0 as an identity provider.

You can configure a <Tooltip href="/docs/glossary?term=WS-Fed">WS-Fed</Tooltip> application (service provider) to use Auth0 as an <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>. Some commonly used WS-Fed applications are pre-configured in Auth0 and available via [Single Sign-On Integrations](/docs/customize/integrations/sso-integrations). If a WS-Fed application is not listed in <Tooltip href="/docs/glossary?term=Single+Sign-On">Single Sign-On</Tooltip> Integrations, the WS-Fed application configuration can be accessed using the following steps.

1. Go to **Dashboard >** **Applications > Applications**.
2. Click **Create App**.
3. Enter a name, and click **Save**.
4. Go to the **Addons** tab.

   <Callout icon="file-lines">
     Enabling both SAML and WS-Fed addons for a single client is not supported and may lead to inconsistent behavior. Use a separate client for each addon.
   </Callout>
5. Scroll to **WS-Fed Web App**, and enter the **Application Callback URL**. This is your callback URL in the WS-Fed application to which the WS-Fed response will be posted. It may also be called the **ACS** or **Assertion Consumer Service URL** in some applications.
6. Enter the **Realm**. This is an identifier sent by the WS-Fed application and is used to identify the application in the response.

## Configure claims included in the WS-Fed token response

Unlike the <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> Web App addon, the WS-Fed Web App addon does not include configuration settings that allow you to configure the token generated by Auth0. If you need to change the default settings, you can create a rule similar to:

```javascript lines expandable theme={null}
function (user, context, callback) {

  // only apply changes for the WS-Fed application
  if (context.clientName !== 'Your ws-fed application name') {
    return callback(null, user, context);
  }

  // exclude the upn claim creation (defaults to true)
  context.samlConfiguration.createUpnClaim = false;

  // exclude the identities array (defaults to true)
  context.samlConfiguration.mapIdentities = false;

  // exclude claims that were not explicitly mapped (defaults to true)
  context.samlConfiguration.passthroughClaimsWithNoMapping = false;

  // this is the default mapping. Remove or change as you like.
  // Note that the key (left side) is the attribute name (namespace-qualified)
  // and the value (right side) is the property name from the user object.
  // you can also use transient values from the user object. For example, for:
  //    user.calculated_field = <some expression>;
  // then add this mapping:
  //    'some_claim': 'calculated_field', 
  context.samlConfiguration.mappings = {
    'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier': 'user_id',
    'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress': 'email',
    'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name': 'name',
    'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname': 'given_name',
    'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname': 'family_name',
    'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn': 'upn',
    'http://schemas.xmlsoap.org/claims/Group': 'groups'
  };

  callback(null, user, context);
}
```

## Custom domains

To use your WS-Fed apps with a <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip> and with Auth0 as the IdP, update your service provider with new identity provider metadata from Auth0. You can obtain the metadata from:

`https://<YOUR CUSTOM DOMAIN>/wsfed/FederationMetadata/2007-06/FederationMetadata.xml`.

## Encrypted responses

If you require encrypted responses, you should use SAML to connect to ADFS. To learn more, read [Configure ADFS as SAML Identity Provider](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-adfs-saml-connections) and [Sign and Encrypt SAML Requests](/docs/authenticate/protocols/saml/saml-sso-integrations/sign-and-encrypt-saml-requests).

## Learn more

* [Custom Domains](/docs/customize/custom-domains)
* [Auth0 Integrations](/docs/customize/integrations)


# Credential Settings
Source: https://auth0.com/docs/get-started/applications/credentials

Describes the settings related to credentials tab available in the Auth0 Dashboard.

On the [Applications](http://manage.auth0.com/#/applications) page of the Dashboard, locate your application in the list, and click its name to view the available settings. Switch to the **Credentials** tab.

<Callout icon="file-lines">
  The Credentials tab may not be visible in your tenant if you have a public application. To learn more about confidential applications versus public applications, read [Confidential and Public Applications](/docs/get-started/applications/confidential-and-public-applications).
</Callout>

<Frame>
  <img alt="" />
</Frame>

## Authentication Methods

Auth0 offers the following ways your application can authenticate with the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip>:

* **Private Key <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip>**: An asymmetric authentication method for confidential applications. In Private Key JWT, you generate a pair of keys, public and private, to use as credentials. You provide the public key and securely store the private key in your own system without sharing it with Auth0. You use the private key to sign the request sent to the authorization server. You can manage the public keys below in the **Available Credentials** section.
* **<Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip>:** A symmetrical authentication method. In Client Secret authentication, you provide the Client Secret Auth0 assigned when you created the application. You can view and copy the `client_secret` directly from this section.

  * **Client Secret (Basic)**: Use Basic for a confidential application using the `HTTP BASIC` authentication scheme to send a Client Secret.
  * **Client Secret (Post)**: Use Post for a confidential application using request body parameters to send a Client Secret.

To learn more about authentication methods and associated credentials, read [Application Credentials](/docs/secure/application-credentials).

## Available Credentials

<Frame>
  <img alt="" />
</Frame>

**Add New Credential**: Adds a new entry to the list if you have not reached the max number of credentials (2) for the application.

* **Name**: Name of the credential. For example: 4096.
* **Key ID**: Unique Auth0-generated credential identifier. The same credential can’t be uploaded more than once.
* **Algorithm**: Algorithm you select for each credential. We support RS256, PS256, and RS384.
* **Expires At**: `datetime` when the credential is invalid for the declared use. The credential will not be deleted, but will be inoperable. This can be configured in the UI by enabling the **Set an explicit expiry date for this credential** checkbox.

Choose the side menu to enable, disable, or delete credentials.

<Frame>
  <img alt="" />
</Frame>

<Frame>
  <img alt="" />
</Frame>

## Rotate client secret

You may need to occasionally rotate your application’s client secret. To learn more, read [Rotate Client Secrets](/docs/get-started/applications/rotate-client-secret).

## Learn more

* [Application Credentials](/docs/secure/application-credentials)
* [Authenticate with Private Key JWT](/docs/get-started/authentication-and-authorization-flow/authenticate-with-private-key-jwt)
* [Rotate Credentials](/docs/get-started/applications/rotate-credentials)
* [Configure Private Key JWT Authentication](/docs/get-started/applications/configure-private-key-jwt)


# Dynamic Client Registration
Source: https://auth0.com/docs/get-started/applications/dynamic-client-registration

Learn how to dynamically register applications with Auth0 using the Management API.

You can dynamically register third-party applications for your tenant. This feature is based on the [OpenID Connect Dynamic Client Registration specification](https://openid.net/specs/openid-connect-registration-1_0.html).

## Enable dynamic client registration

<Warning>
  Auth0 supports **Open Dynamic Registration**, which means that if you enable this feature, **anyone** will be able to create applications in your tenant without a token.
</Warning>

By default, dynamic application registration is disabled for all tenants. To change this, you have to set the `enable_dynamic_client_registration` flag to `true` in your tenant's settings.

To do so, go to [Dashboard > Settings > Advanced](https://manage.auth0.com/#/tenant/advanced) and enable **Dynamic Client Registration (DCR)**.

Alternatively, you can update this flag using the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> [`/Tenant/patch_settings`](https://auth0.com/docs/api/management/v2#!/Tenants/patch_settings) endpoint.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/tenants/settings' \
    --header 'authorization: Bearer API2_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "flags": { "enable_dynamic_client_registration": true } }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/tenants/settings");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer API2_ACCESS_TOKEN");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("application/json", "{ "flags": { "enable_dynamic_client_registration": true } }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/tenants/settings"

  	payload := strings.NewReader("{ "flags": { "enable_dynamic_client_registration": true } }")

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

  	req.Header.Add("content-type", "application/json")
  	req.Header.Add("authorization", "Bearer API2_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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/tenants/settings")
    .header("content-type", "application/json")
    .header("authorization", "Bearer API2_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "flags": { "enable_dynamic_client_registration": true } }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/tenants/settings',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer API2_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: {flags: {enable_dynamic_client_registration: true}}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer API2_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"flags": @{ @"enable_dynamic_client_registration": @YES } };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/tenants/settings"]
                                                         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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/tenants/settings",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "PATCH",
    CURLOPT_POSTFIELDS => "{ "flags": { "enable_dynamic_client_registration": true } }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer API2_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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "flags": { "enable_dynamic_client_registration": true } }"

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

  conn.request("PATCH", "/{yourDomain}/api/v2/tenants/settings", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/tenants/settings")

  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 API2_ACCESS_TOKEN'
  request["cache-control"] = 'no-cache'
  request.body = "{ "flags": { "enable_dynamic_client_registration": true } }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer API2_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = ["flags": ["enable_dynamic_client_registration": true]] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/tenants/settings")! 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()
  ```
</AuthCodeGroup>

You need to update the `API2_ACCESS_TOKEN` with a valid token with the scope `update:tenant_settings`. To learn more, read [Management API Access Tokens](/docs/secure/tokens/access-tokens/management-api-access-tokens).

## Use dynamic client registration

In this section, we will see how you can dynamically register and configure an application.

### Register your application

To dynamically register an application with Auth0, you need to send an HTTP `POST` message to the Application Registration endpoint: `https://{yourDomain}/oidc/register`. Note that Auth0 supports **Open Dynamic Registration**, which means that the endpoint will accept a registration request without an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>.

To create an application with the name `My Dynamic application` and the callback URLs `https://application.example.com/callback` and `https://application.example.com/callback2`, use the following snippet:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oidc/register' \
    --header 'content-type: application/json' \
    --data '{"client_name":"My Dynamic Application","redirect_uris": ["https://application.example.com/callback", "https://application.example.com/callback2"]}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oidc/register");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"client_name":"My Dynamic Application","redirect_uris": ["https://application.example.com/callback", "https://application.example.com/callback2"]}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/oidc/register"

  	payload := strings.NewReader("{"client_name":"My Dynamic Application","redirect_uris": ["https://application.example.com/callback", "https://application.example.com/callback2"]}")

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

  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/oidc/register")
    .header("content-type", "application/json")
    .body("{"client_name":"My Dynamic Application","redirect_uris": ["https://application.example.com/callback", "https://application.example.com/callback2"]}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oidc/register',
    headers: {'content-type': 'application/json'},
    data: {
      client_name: 'My Dynamic Application',
      redirect_uris: [
        'https://application.example.com/callback',
        'https://application.example.com/callback2'
      ]
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"client_name": @"My Dynamic Application",
                                @"redirect_uris": @[ @"https://application.example.com/callback", @"https://application.example.com/callback2" ] };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oidc/register"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oidc/register",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{"client_name":"My Dynamic Application","redirect_uris": ["https://application.example.com/callback", "https://application.example.com/callback2"]}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"client_name":"My Dynamic Application","redirect_uris": ["https://application.example.com/callback", "https://application.example.com/callback2"]}"

  headers = { 'content-type': "application/json" }

  conn.request("POST", "/{yourDomain}/oidc/register", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oidc/register")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request.body = "{"client_name":"My Dynamic Application","redirect_uris": ["https://application.example.com/callback", "https://application.example.com/callback2"]}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/json"]
  let parameters = [
    "client_name": "My Dynamic Application",
    "redirect_uris": ["https://application.example.com/callback", "https://application.example.com/callback2"]
  ] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oidc/register")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

Where:

* **client\_name**: The name of the Dynamic Application to be created
* **redirect\_uris** (required): An array of URLs that Auth0 will deem valid to call at the end of an authentication flow

Optionally, you can set a value for `token_endpoint_auth_method`, which can be `none` or `client_secret_post` (default value). Use `token_endpoint_auth_method: none` in the request payload if creating a SPA.

The response includes the basic application information.

```json lines theme={null}
HTTP/1.1 201 Created
Content-Type: application/json
{
  "client_name": "My Dynamic Application",
  "client_id": "8SXWY6j3afl2CP5ntwEOpMdPxxy49Gt2",
  "client_secret": "Q5O...33P",
  "redirect_uris": [
    "https://application.example.com/callback",
    "https://application.example.com/callback2"
  ],
  "client_secret_expires_at": 0
}
```

Where:

* **client\_id**: Unique client identifier. This is the ID you will use while configuring your apps to use Auth0. It is generated by the system and it cannot be modified.
* **client\_secret**: Alphanumeric 64-bit <Tooltip href="/docs/glossary?term=client+secret">client secret</Tooltip>. This value is used by applications to authenticate to the Authentication API [`/token`](https://auth0.com/docs/api/authentication#get-token) and for signing and validating <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip>.
* **client\_secret\_expires\_at**: Time at which the `client_secret` will expire. For Auth0 this value will always be zero (`0`) which means that the application never expires.

Make a note of the <Tooltip href="/docs/glossary?term=client+ID">client ID</Tooltip> and client secret, as these are the most important pieces for executing authentication and <Tooltip href="/docs/glossary?term=authorization+flows">authorization flows</Tooltip>. To learn more, read [Authentication and Authorization Flows](/docs/get-started/authentication-and-authorization-flow).

Also, keep in mind that third-party developers are not allowed to modify the application settings. In case this is necessary, they need to contact the tenant owner with their request.

### Configure your application

Now that you have a Client ID and Secret, you can configure your application to authenticate users with Auth0.

We will go through a simple example, that shows how to call an API from a client-side web app, using the [Implicit Flow](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post).

First, you need to configure your application to send the user to the authorization URL:

<AuthCodeBlock />

Where:

* **<Tooltip href="/docs/glossary?term=audience">audience</Tooltip>** (optional): The target API for which the Application is requesting access on behalf of the user. Set this parameter if you need API access.
* **scope** (optional): The scopes for which you want to request authorization. These must be separated by a space. You can request any of the [standard OIDC scopes](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) for users, such as `profile` and `email`, custom claims that must conform to a namespaced format, or any scopes supported by the target API (for example, `read:contacts`). Set this parameter if you need API access. To learn more, read [API Scopes](/docs/get-started/apis/scopes/api-scopes).
* **response\_type**: The response type. For Implicit Grant you can either use `token` or `id_token token`. This will specify the type of token you will receive at the end of the flow. Use `token` to get only an access token, or `id_token token` to get both an ID token and an access token.
* **client\_id**: Your application's client ID.
* **redirect\_uri**: The URL to which the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip> (Auth0) will redirect the User Agent (Browser) after authorization has been granted by the User. The access token (and optionally an ID token) will be available in the hash fragment of this URL. This URL must be specified as a valid callback URL under the **Application Settings** of your application.
* **state**: An opaque value the applications add to the initial request that the authorization server includes when redirecting the back to the application. This value must be used by the application to prevent CSRF attacks.
* **<Tooltip href="/docs/glossary?term=nonce">nonce</Tooltip>**: A string value that will be included in the ID token response from Auth0, used to prevent token replay attacks. It is required for `response_type=id_token token`.

For example:

<AuthCodeBlock />

This call will redirect the user to Auth0, and upon successful authentication, back to your application (specifically to the **redirect\_uri**).

If you need API access, then following the authentication, you need to extract the access token from the hash fragment of the URL, and use it to make calls to the API, by passing it as a `Bearer` token in the `Authorization` header of the HTTP request.

## Use Tenant Access Control List (ACL)

Auth0 provides [Tenant Access Control List (ACL)](/docs/secure/tenant-access-control-list) to manage traffic. For the `/oidc/register` endpoint, you can add the `dcr` scope to an ACL rule to help manage requests. To learn more, read [Reference](/docs/secure/tenant-access-control-list/reference).

## Learn more

* [First-Party and Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/first-party-and-third-party-applications)
* [User Consent and Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/user-consent-and-third-party-applications)


# Enable Android App Links Support
Source: https://auth0.com/docs/get-started/applications/enable-android-app-links-support

Describes how to enable Android App Links support for your Auth0 application using the Auth0 Dashboard.

[Android App Links](https://developer.android.com/training/app-links) allow an application to designate itself as the default handler of a given type of link. For example, clicking a URL in an email would open the link in the designated application. This guide will show you how to enable Android App links support for your Auth0-registered application using Auth0's Dashboard.

1. Go to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), and select the name of the application to view.

   <Frame>
     <img alt="Dashboard Applications List" />
   </Frame>
2. Scroll to the bottom of the **Settings** page, and select **Show Advanced Settings**.
3. Select **Device Settings**, provide the [App Package Name](https://developer.android.com/studio/build/application-id) and the SHA256 fingerprints of your app’s signing certificate for your Android application, and select **Save Changes**.

   <Frame>
     <img alt="Dashboard Applications Application Settings Tab Advanced Settings Device Settings Tab" />
   </Frame>

You can use the following command to generate the fingerprint using the Java keytool in your terminal:
`keytool -list -v -keystore my-release-key.keystore`

To learn more about signing certificates, see Android's [Sign Your App](https://developer.android.com/studio/publish/app-signing.html) developer documentation.

## Test link

1. Navigate to the following URL in your browser: `https://{yourDomain}/.well-known/assetlinks.json`
2. If the link is successful, you will return the following JSON (formatted for readability):

   ```json lines theme={null}
   [{
     "relation": ["delegate_permission/common.handle_all_urls"],
     "target": {
       "namespace": "android_app",
       "package_name": "com.mycompany.app1",
       "sha256_cert_fingerprints":
       ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
     }
   }]
   ```

To learn more about testing your app link, read [Verify Android App Links](https://developer.android.com/training/app-links/verify-site-associations) at [https://developer.android.com](https://developer.android.com).


# Enable Single Sign-On Integrations for Applications
Source: https://auth0.com/docs/get-started/applications/enable-sso-for-applications

Describes how to create a single sign-on (SSO) integration for an application. Only for use with legacy tenants.

By default, seamless <Tooltip href="/docs/glossary?term=single+sign-on">single sign-on</Tooltip> (SSO) is enabled for all new Auth0 tenants; however, **legacy tenants** may [choose whether to enable this feature at the tenant level](/docs/get-started/tenant-settings/enable-sso-for-legacy-tenants). If you have not enabled tenant-level SSO, you may enable it per application.

You can enable an SSO for your application using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

## Prerequisite

Before enabling SSO for an application, you must first create and configure a connection for each <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> you want to use. For social identity providers, make sure the connection is not using developer keys if you use the [Universal Login experience](/docs/authenticate/login/auth0-universal-login).

## Enable SSO

1. Go to [Auth0 Dashboard > Applications > SSO Integrations](https://manage.auth0.com/#/externalapps), and select the name of the integration to view.
2. Scroll to the bottom of the **Settings** page, locate **Use Auth0 instead of the IdP to do Single Sign-on**, enable the toggle, and select **Save Changes**.

## Learn more

* [Single Sign-On Integrations](/docs/customize/integrations/sso-integrations)


# Enable Universal Links Support in Apple Xcode
Source: https://auth0.com/docs/get-started/applications/enable-universal-links-support-in-apple-xcode

Learn how to enable universal links support for your Auth0 app in Apple Xcode using the Auth0 Dashboard.

Universal links establish a verified relationship between domains and applications, so both your Auth0 Application settings and your iOS application need to be in sync. To do this, you need to provide Auth0 with Apple Team ID and Bundle Identifier. You can enable universal links support for your Auth0-registered application using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

## Obtain Apple Team ID and Bundle Identifier

1. To find your Apple **Team ID**, go to your [Apple developer account summary page](https://developer.apple.com/membercenter/index.action#accountSummary).
2. To find your iOS application's **Bundle identifier**, go to its [Xcode project settings](https://developer.apple.com/library/content/documentation/IDEs/Conceptual/AppDistributionGuide/ConfiguringYourApp/ConfiguringYourApp.html) page.

## Provide Apple Team ID and Bundle Identifier to Auth0

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/clients) and select the name of the application to view.

   <Frame>
     <img alt="Dashboard Applications List" />
   </Frame>
2. Scroll to the bottom of the **Settings** page, and select **Show Advanced Settings**.
3. Select **Device Settings**, provide the **Team ID** and the **App bundler identifier** values for your iOS application and select **Save Changes**.

   <Frame>
     <img alt="Dashboard Applications Application Settings Tab Advanced Settings Device Settings Tab" />
   </Frame>

## Test link

Check whether the universal links `apple-app-site-association` file is available for your application by navigating to the following URL in your browser: `{yourDomain}/apple-app-site-association`

If the link is successful, you will see the following JSON (formatted for readability):

```json lines theme={null}
{
  "applinks": {
    "apps": [],
    "details": [{
      "appID": "86WQXF56BC.com.auth0.Passwordless-Email",
      "paths": ["/ios/com.auth0.Passwordless-Email/*"]
    }]
  }
}
```


# Remove Applications
Source: https://auth0.com/docs/get-started/applications/remove-applications

Learn how to remove an Auth0-registered application using the Auth0 Dashboard or the Management API.

You can remove an application using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. Once confirmed, this operation cannot be undone.

## Use the Dashboard

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), and select the name of an application to view.

   <Frame>
     <img alt="Dashboard Applications List" />
   </Frame>
2. Scroll to the bottom of the **Settings** page, locate the **Danger Zone**, select **Delete**, and confirm.

## Use the Management API

Make a `DELETE` call to the [`/Clients/delete_clients_by_id`](https://auth0.com/docs/api/management/v2#!/Clients/delete_clients_by_id) endpoints. Be sure to replace `{yourClientId}` and `MGMT_API_ACCESS_TOKEN` placeholder values with your <Tooltip href="/docs/glossary?term=client+ID">client ID</Tooltip> and Management API <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
     --url 'https://{yourDomain}/api/v2/clients/%7ByourClientId%7D' \
     --header 'authorization: Bearer {yourMgmtApiToken}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/clients/%7ByourClientId%7D");
  var request = new RestRequest(Method.DELETE);
  request.AddHeader("authorization", "Bearer {yourMgmtApiToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/clients/%7ByourClientId%7D"

  	req, _ := http.NewRequest("DELETE", url, nil)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiToken}")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.delete("https://{yourDomain}/api/v2/clients/%7ByourClientId%7D")
    .header("authorization", "Bearer {yourMgmtApiToken}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'DELETE',
    url: 'https://{yourDomain}/api/v2/clients/%7ByourClientId%7D',
    headers: {authorization: 'Bearer {yourMgmtApiToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/clients/%7ByourClientId%7D"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"DELETE"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/clients/%7ByourClientId%7D",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiToken}"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {yourMgmtApiToken}" }

  conn.request("DELETE", "/{yourDomain}/api/v2/clients/%7ByourClientId%7D", headers=headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/clients/%7ByourClientId%7D")

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

  request = Net::HTTP::Delete.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiToken}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/clients/%7ByourClientId%7D")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "DELETE"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Τhe ID of the application to be deleted.</td>
    </tr>

    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td><a href="https://auth0.com/docs/api/management/v2/tokens">Access Tokens for the Management API</a> with the scope <code>delete:clients</code>.</td>
    </tr>
  </tbody>
</table>

## Learn more

* [Register Regular Web Applications](/docs/get-started/auth0-overview/create-applications/regular-web-apps)
* [Register Single-Page Web Applications](/docs/get-started/auth0-overview/create-applications/single-page-web-apps)
* [Register Native Applications](/docs/get-started/auth0-overview/create-applications/native-apps)
* [Register Machine-to-Machine Applications](/docs/get-started/auth0-overview/create-applications/machine-to-machine-apps)


# Revoke Access to APIs Using Application Grants
Source: https://auth0.com/docs/get-started/applications/revoke-api-access



Configuring your application grant so that the tokens you issue last for only a short period means that when it comes time for you to revoke access to a protected resource, you can simply delete the grant. At this point, the party with the <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> only has a limited period between when you delete the grant and the token's expiration to make additional API requests. Because this is an easy (and safe) option to implement, we recommend you deny access to your APIs and other protected resources by revoking application grants.

If, for example, you are using a Machine-to-Machine [application](/docs/get-started/applications) to access your [API](/docs/get-started/apis) and you have a partner that calls your API, and at the end of your existing contract, you and your partner decide not to renew your partnership. You now want to remove your partner's access to your API. The issue, however, is that you've given your partner an access token that lasts for a month.

* What can you do in this situation?
* How might you configure your Auth0 environment to make such situations easier to handle in the future?

## Application grants

The main issue in this scenario is the length of time for which the API access token is valid: one month.

By default, Auth0 issues access tokens that last for 24 hours. Setting the token's lifetime to 24 hours means that your partner must repeat the client credentials exchange (or whichever grant you've implemented) to obtain a new access token every 24 hours. To deny access to your partner due to the expiration of your contract, you can simply delete the application grant so that when their existing token expires, they cannot request a new one.

You can change the lifetime of a token by setting the `token_lifetime` option. The specific lifetime appropriate to your use case will vary, but we recommend setting this value to be as short as possible. A good starting point for determining this value would be the window you consider allowable for the delay between deleting the grant and final use of the API.

### Delete an application grant

To delete an application grant, make the appropriate `DELETE` call to the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>'s [Delete an Application Grant endpoint](https://auth0.com/docs/api/management/v2#!/Client_Grants/delete_client_grants_by_id). As part of the call, you'll need to specify the ID of the application grant you want to delete, which you can obtain via the Management API's [Get all Application Grants endpoint](https://auth0.com/docs/api/management/v2#!/Client_Grants/get_client_grants).

You can also [update an Application's grant types](/docs/get-started/applications/update-grant-types) through the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

## Learn more

* [Data Security](/docs/secure/security-guidance/data-security)


# Rotate Client Secrets
Source: https://auth0.com/docs/get-started/applications/rotate-client-secret

Learn how to rotate an application's client secret using the Auth Dashboard or the Management API.

You can change an application's <Tooltip href="/docs/glossary?term=client+secret">client secret</Tooltip> using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. When you rotate a client secret, you must update any authorized applications with the new value.

<Callout icon="file-lines">
  Client secrets should not be stored in public client applications. To learn more, read [Confidential and Public Applications.](/docs/get-started/applications/confidential-and-public-applications)
</Callout>

<Warning>
  New secrets may be delayed up to thirty seconds while rotating. To minimize downtime, we suggest you store the new client secret in your application's code/system configuration as a fallback to the previous secret. This way, if the client application request doesn't work with the old secret, your app will use the new secret.

  Secrets can be stored in a list (or similar structure) until they're no longer needed. Once you're sure that an old secret is obsolete, you can remove its value from your app's code.
</Warning>

## Use the Dashboard

1. In the Auth0 Dashboard, go to [Applications > Applications](https://manage.auth0.com/#/applications), and then select the name of the application to view.

   <Frame>
     <img alt="Dashboard Applications List" />
   </Frame>
2. Scroll to the bottom of the **Settings** page, locate the **Danger Zone**, select **Rotate**, and confirm.
3. Scroll to the top of the page, and switch to the **Credentials** tab.
4. View your new secret by locating **Client Secret**, and selecting the eye icon.

   <Frame>
     <img alt="Dashboard Applications Application Settings Tab Basic Information" />
   </Frame>
5. Update authorized applications with the new value.

## Use the Management API

1. Call the Management API [Rotate a client secret](https://auth0.com/docs/api/management/v2#!/Clients/post_rotate_secret) endpoint. Replace the `{yourClientId}` and `MGMT_API_ACCESS_TOKEN` placeholder values with your client ID and Management API access token, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
     curl --request POST \
  --url 'https://{yourDomain}/api/v2/clients/%7ByourClientId%7D/rotate-secret' \
  --header 'authorization: Bearer {yourMgmtApiAccessToken}'

  ```

  ```csharp C# theme={null}
     var client = new RestClient("https://{yourDomain}/api/v2/clients/%7ByourClientId%7D/rotate-secret");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  IRestResponse response = client.Execute(request);

  ```

  ```go Go theme={null}
     package main

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

  func main() {

  url := "https://{yourDomain}/api/v2/clients/%7ByourClientId%7D/rotate-secret"

  req, _ := http.NewRequest("POST", url, nil)

  req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

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

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

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

  }

  ```

  ```java Java theme={null}
     HttpResponse response = Unirest.post("https://{yourDomain}/api/v2/clients/%7ByourClientId%7D/rotate-secret")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .asString();

  ```

  ```javascript Node.JS theme={null}
     var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/clients/%7ByourClientId%7D/rotate-secret',
    headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });

  ```

  ```objc Obj-C theme={null}
     #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/clients/%7ByourClientId%7D/rotate-secret"]
                                                        cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                    timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [request setAllHTTPHeaderFields:headers];

  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];

  ```

  ```php PHP theme={null}
     $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/clients/%7ByourClientId%7D/rotate-secret",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}"
    ],
  ]);

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

  curl_close($curl);

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

  ```

  ```python Python theme={null}
     import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" }

  conn.request("POST", "/{yourDomain}/api/v2/clients/%7ByourClientId%7D/rotate-secret", headers=headers)

  res = conn.getresponse()

  data = res.read()

  print(data.decode("utf-8"))

  ```

  ```ruby Ruby theme={null}
     require 'uri'
  require 'net/http'
  require 'openssl'
  url = URI("https://{yourDomain}/api/v2/clients/%7ByourClientId%7D/rotate-secret")
  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE
  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'
  response = http.request(request)
  puts response.read_body

  ```

  ```swift Swift theme={null}
     import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/clients/%7ByourClientId%7D/rotate-secret")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  request.allHTTPHeaderFields = headers

  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()

  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th><strong>Value</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Τhe ID of the application to be updated.</td>
    </tr>

    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td><a href="https://auth0.com/docs/api/management/v2/tokens">Access Tokens for the Management API</a> with the scope  <code>update:client\_keys</code>.</td>
    </tr>
  </tbody>
</table>

2. Update authorized applications with the new value.

### Set a custom client secret

You can use the Management API [Update a client](https://auth0.com/docs/api/management/v2/#!/Clients/patch_clients_by_id) endpoint to to set a client secret manually instead of requesting a rotation to an automatically generated secret. Your application is configured with the future secret as a fallback ahead of the actual rotation.

```bash lines theme={null}
   curl --request PATCH \
   --url https://{TenantDomain}/api/v2/clients/{ClientID} \
   --header 'Authorization: Bearer {AccessToken}' \
   --header 'Content-Type: application/json' \
   --data '{
      "client_secret": "{CustomClientSecret}"
      }'
```

## Learn more

* [View Signing Certificates](/docs/get-started/tenant-settings/signing-keys/view-signing-certificates)
* [Signing Algorithms](/docs/get-started/applications/signing-algorithms)
* [Change Application Signing Algorithms](/docs/get-started/applications/change-application-signing-algorithms)


# Rotate Credentials
Source: https://auth0.com/docs/get-started/applications/rotate-credentials

Describes how to rotate existing credentials in the Auth0 Dashboard.

Auth0 recommends you rotate key material regularly to meet your compliance needs and ensure security is not compromised by leaked private keys. You can use the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to rotate new keys into use. You need to create a new credential, associate it with the `private_key_jwt` authentication method, and remove old or unused credentials.

<Callout icon="file-lines">
  The current application storage limit is two credentials at one time. To repeatedly rotate new credentials, you need to delete unused credentials.
</Callout>

<Tabs>
  <Tab title="Use Auth0 Dashboard">
    To rotate your application credentials with Auth0 Dashboard:

    1. Navigate to [**Auth0 Dashboard > Applications > Application**](https://manage.auth0.com/#/applications) and select the application you want to update.
    2. Switch to the **Credentials** tab.
    3. In the **Available Credentials** section, select **Add New Key**.
    4. Set a name for your new credential, the public key in PEM format, and the algorithm for the new credential.
    5. Select **Add Credential**.
    6. To activate your new credential, navigate to the menu for the credential and choose **Enable for Private Key JWT use**.
    7. Once you have updated your applications to use the new credential, deactivate your original credential:

       1. Select **Disable for Private Key JWT Use**.
       2. Once disabled, return to the credential menu and select **Delete Credential**.
  </Tab>

  <Tab title="Use Management API">
    In the rotation examples below, `credential1` is an existing credential in use, and `credential2` is a new credential to replace the existing one.

    1. Generate a new key pair.

    2. Create the credential resource with a `POST` request to the Management API.

       <Callout icon="file-lines">
         The current application storage limit is two credentials at one time. To repeatedly rotate new credentials, you need to delete unused credentials.
       </Callout>

    3. Make a PATCH request to the Management API [Update a Client](https://auth0.com/docs/api/management/v2#!/Clients/patch_clients_by_id) endpoint to associate the credential to the authentication method `private_key_jwt`:

       ```bash lines theme={null}
       curl --location --request PATCH 'https://{domain}/api/v2/clients/{clientId} \
         --header 'Authorization: Bearer {managementApiAccessToken} \
         --header 'Content-Type: application/json' \
         --data-raw '{
                 "client_authentication_methods": {
                    "private_key_jwt": {
                       "credentials": [{ "id": {credentialId1} }, { "id": {credentialId2} }]
                    }
                 }
          }'
       ```

       <table>
         <thead>
           <tr>
             <th>Parameter</th>
             <th>Description</th>
           </tr>
         </thead>

         <tbody>
           <tr>
             <td><code>clientId</code></td>
             <td>Application you want to update.</td>
           </tr>

           <tr>
             <td><code>credentialId1</code></td>
             <td>ID for the existing credential in use.</td>
           </tr>

           <tr>
             <td><code>credentialId2</code></td>
             <td>ID for the new credential.</td>
           </tr>

           <tr>
             <td><code>managementApiAccessToken</code></td>
             <td><a href="/docs/secure/tokens/access-tokens/management-api-access-tokens">Access token for the Management API</a> with the scopes <code>update:clients</code> and <code>update:credentials</code>.</td>
           </tr>
         </tbody>
       </table>

    4. Update your application to use the new private key to sign assertions for the Auth0 Authentication API.

    5. Remove the unused key from your application.

       ```bash lines theme={null}
       curl --location --request PATCH 'https://{domain}/api/v2/clients/{clientId} \
         --header 'Authorization: Bearer $management_access_token' \
         --header 'Content-Type: application/json' \
         --data-raw '{
                 "client_authentication_methods": {
                    "private_key_jwt": {
                       "credentials": [{ "id": {credentialId2} }]
                    }
                 }
          }'
       ```

    6. Remove the unused key from your application. This will permanently delete the credential from storage.  You must unassociate the credential from your application or you will not be able to remove it.

       ```bash lines theme={null}
       curl --location --request DELETE 'https://{domain}/api/v2/clients/{clientId}/credentials/{credentialId}' \
         --header 'Authorization: Bearer {managementApiAccessToken}
       ```

       <table>
         <thead>
           <tr>
             <th>Parameter</th>
             <th>Description</th>
           </tr>
         </thead>

         <tbody>
           <tr>
             <td><code>clientId</code></td>
             <td>Application you want to update.</td>
           </tr>

           <tr>
             <td><code>credentialId</code></td>
             <td>ID for the old credential you want to delete.</td>
           </tr>

           <tr>
             <td><code>managementApiAccessToken</code></td>
             <td><a href="/docs/secure/tokens/access-tokens/management-api-access-tokens">Access token for the Management API</a> with the scope <code> delete:credentials</code>.</td>
           </tr>
         </tbody>
       </table>
  </Tab>
</Tabs>

### Active credentials

To assure zero downtime, you can leave multiple credentials active during rotation. Applications can function normally using older keys until keys are updated. Applications can send signed assertions with any set of active credentials.

Auth0 recommends you minimize the time that multiple credentials are in use. The example below uses multiple associated credentials:

```bash lines theme={null}
curl --location --request PATCH 'https://$tenant/api/v2/clients/$client_id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
          "client_authentication_methods": {
             "private_key_jwt": {
                "credentials": [{ "id": $credential1.id }, { "id": $credential2.id }]
             }
          }
 }'
```

## Learn more

* [Configure Private Key JWT Authentication](/docs/get-started/applications/configure-private-key-jwt)
* [Application Credentials](/docs/secure/application-credentials)
* [Credential Settings](/docs/get-started/applications/credentials)


# Configure Cross-Origin Resource Sharing
Source: https://auth0.com/docs/get-started/applications/set-up-cors

Describes how to configure Cross-Origin Resource Sharing (CORS) for an Auth0-registered application using the Auth0 Dashboard.

<Card title="Before you start">
  * For security purposes, your application's origin URL must be listed as an approved URL. If you have not already added it to the **Allowed Callback URLs** for your application, you will need to add it to the list of **Allowed Origins (CORS)**.
  * Ensure that **Allowed Web Origins** in your application's **Settings** view is set to the domain making the request. The URLs can contain wildcards for subdomains, but cannot contain relative paths after the domain URL. To learn more, read [Placeholders for Subdomains](/docs/get-started/applications/wildcards-for-subdomains).
  * If you don't enable [Custom Domains](/docs/customize/custom-domains), you will need to create a verification page that uses Auth0.js as the fallback for the cross-origin authentication.
</Card>

Cross-origin resource sharing (CORS) is a mechanism that allows an application to load data (resource) from a domain (origin) that is different from the one that it's hosted on. A CORS policy is an explicit exception to the same-origin policy common to web applications.

For example, if you wanted your application (app.mydomain.com) to fetch a font from Google (fonts.google.com) in the background using Ajax, you would need to configure CORS.

## Configure cross-origin authentication

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and click the name of the application to view.
2. Under **Cross-Origin Authentication**, toggle on **Allow Cross-Origin Authentication**.
3. Locate **Allowed Origins (CORS)**, and enter your application's origin URL. To learn more about Origins, read [Origin on Mozilla MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Origin).
4. Click **Save Changes**.

<Callout icon="file-lines">
  If you do not need to use CORS for your application, ensure that **Allow Cross-Origin Authentication** is toggled off.
</Callout>

## Create cross-origin verification page

There are some cases when third-party cookies will not be available. Certain browser versions do not support third-party cookies and, if they do, they may be disabled in a user's settings.

For [browsers that are supported](#browser-testing-support), you can use the `crossOriginVerification` method from the [Auth0.js SDK](/docs/libraries/auth0js) in your application on a dedicated page to handle cases when third-party cookies are disabled.

For browsers that are not supported, such as Chrome, Opera, and Safari, cross-origin authentication will not work when third-party cookies are disabled unless you enable [Custom Domains](/docs/customize/custom-domains).

<Callout icon="file-lines">
  **Safari's** configuration is labeled as "Prevent cross-site tracking" and uses [Intelligent Tracking Prevention](https://webkit.org/blog/7675/intelligent-tracking-prevention/). Unfortunately, this also prevents third-party cookies from being useful in authentication scenarios. Here's an example of how it affects [token renewal](/docs/troubleshoot/authentication-issues/renew-tokens-when-using-safari).
</Callout>

1. Create a page in your application that instantiates `WebAuth` from [Auth0.js](/docs/libraries/auth0js). Call `crossOriginVerification` immediately. The name of the page is up to you.

<AuthCodeBlock />

When third party cookies are not available, Auth0.js renders an iframe to call a different cross-origin verification flow.
2\. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), and select the application to view.
3\. Under **Cross-Origin Authentication**, add the URL of the callback page you created to the **Cross-Origin Verification Fallback URL** field.

<Warning>
  For production environments, verify that the URL for the page does not point to `localhost`. The page must be in the same domain where the embedded login form is hosted and must have an `https` scheme.
</Warning>

4. Click **Save Changes**.

For more details, view the [cross-origin authentication sample on GitHub](https://github.com/auth0/lock/blob/master/support/callback-cross-auth.html).

## Error codes and descriptions

<Warning>
  Error descriptions are intended to be human-readable. They are subject to change at any time and should not be parsed by any code.
</Warning>

When Auth0.js v9 (and Lock) is used for embedded login, it calls the `/co/authenticate` endpoint, which has the following errors:

<table>
  <thead>
    <tr>
      <th><strong>Status</strong></th>
      <th><strong>Code</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>400</code></td>
      <td><code>invalid\_request</code></td>
      <td>Invalid request body. All and only of client\_id, credential\_type, username, otp, realm are required.</td>
    </tr>

    <tr>
      <td><code>400</code></td>
      <td><code>unsupported\_credential\_type</code></td>
      <td>Unknown credential type parameter.</td>
    </tr>

    <tr>
      <td><code>400</code></td>
      <td><code>invalid\_request</code></td>
      <td>Unknown realm non-existent-connection.</td>
    </tr>

    <tr>
      <td><code>401</code></td>
      <td><code>unauthorized\_client</code></td>
      <td>Cross origin login not allowed.</td>
    </tr>

    <tr>
      <td><code>401</code></td>
      <td><code>password\_leaked</code></td>
      <td>This login attempt has been blocked because the password you're using was previously disclosed through a data breach (not in this application).</td>
    </tr>

    <tr>
      <td><code>403</code></td>
      <td><code>access\_denied</code></td>
      <td>Wrong email or password.</td>
    </tr>

    <tr>
      <td><code>403</code></td>
      <td><code>access\_denied</code></td>
      <td>Authentication error</td>
    </tr>

    <tr>
      <td><code>403</code></td>
      <td><code>blocked\_user</code></td>
      <td>Blocked user</td>
    </tr>

    <tr>
      <td><code>429</code></td>
      <td><code>too\_many\_attempts</code></td>
      <td>Your account has been blocked after multiple consecutive login attempts. We've sent you a notification via your preferred contact method with instructions on how to unblock it.</td>
    </tr>

    <tr>
      <td><code>429</code></td>
      <td><code>too\_many\_attempts</code></td>
      <td>We have detected suspicious login behavior and further attempts will be blocked. Please contact the administrator.</td>
    </tr>
  </tbody>
</table>

In addition, you can also get a generic `403` error without an `error` or `error_description` property. The response body would just include something similar to the following:

`Origin https://test.app is not allowed.`

## Browser testing support

The following browsers can use cross-origin authentication when third-party cookies are disabled:

* Microsoft Internet Explorer

<Card title="Samesite cookie attributes">
  Previously, the [`samesite` cookie attribute](/docs/manage-users/cookies/samesite-cookie-attribute-changes) options were `true`, `false`, `strict` or `lax`. If you didn't set the attribute manually, Auth0 would use the default value of `false`.

  Effective February 2020, Google Chrome v80 changed the way it handles cookies, and Auth0 implemented the following changes accordingly:

  * Cookies without the `samesite` attribute set will be set to `lax`.
  * Cookies with `sameSite=none` must be secured, otherwise they cannot be saved in the browser's cookie jar.

  The goal of these changes are to improve security and help mitigate cross-site resource forgery (CSRF) attacks.
</Card>

## Learn more

* [Embedded Login](/docs/authenticate/login/embedded-login)
* [Cross-Origin Authentication](/docs/authenticate/login/cross-origin-authentication)
* [Application Settings](/docs/get-started/applications/application-settings)
* [SameSite Cookie Attribute Changes](/docs/manage-users/cookies/samesite-cookie-attribute-changes)


# Set Up Database Connections
Source: https://auth0.com/docs/get-started/applications/set-up-database-connections

Describes how to set up database connections for applications using the Auth0 Dashboard.

You can set up database connections for applications using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. The configured database connections can be used to log in to your application. To set up a connection, follow the steps below.

<AccordionGroup>
  <Accordion icon="circle-1" title="1 Start at Auth0 Dashboard">
    Navigate to [Auth0 Dashboard > Authentication > Database](http://manage.auth0.com/#/connections/database), and select **Create DB Connection**.

    <Frame>
      <img alt="Dashboard - Authentication - Database - Database Connections List" />
    </Frame>
  </Accordion>

  <Accordion icon="circle-2" title="Name the connection">
    Enter a name for your connection, and select **Create**.

    <Frame>
      <img alt="Dashboard - Authentication - Database - New DB Connection" />
    </Frame>
  </Accordion>

  <Accordion icon="circle-3" title="Enable the connection">
    Select the **Applications** view, enable the switch for each Auth0 application that should be able to use this connection.

    <Frame>
      <img alt="Dashboard - Connections - Database - Edit -  View Applications" />
    </Frame>
  </Accordion>
</AccordionGroup>

## Learn more

* [Test Database Connections](/docs/get-started/applications/test-database-connections)


# Signing Algorithms
Source: https://auth0.com/docs/get-started/applications/signing-algorithms

Describes signing algorithms and recommendations for configuring them in the Auth0 Dashboard.

<Tooltip href="/docs/glossary?term=Signing+algorithms">Signing algorithms</Tooltip> are algorithms used to sign tokens issued for your application or API. A signature is part of a [JSON Web Token (JWT)](/docs/secure/tokens/json-web-tokens) and is used to verify that the sender of the token is who it says it is and to ensure that the message wasn't changed along the way.

You can select from the following signing algorithms:

* **RS256 (RSA Signature with SHA-256)**: An asymmetric algorithm, which means that there are two keys: one public key and one private key that must be kept secret. Auth0 has the private key used to generate the signature, and the consumer of the <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> retrieves a public key from the metadata endpoints provided by Auth0 and uses it to validate the JWT signature.
* **HS256 (HMAC with SHA-256)**: A symmetric algorithm, which means that there is only one private key that must be kept secret, and it is shared between the two parties. Since the same key is used both to generate the signature and to validate it, care must be taken to ensure that the key is not compromised. This private key (or secret) is created when you register your application (<Tooltip href="/docs/glossary?term=client+secret">client secret</Tooltip>) or API (signing secret) and choose the HS256 signing algorithm.
* **PS256 (RSA Signature with SHA-256)**: An asymmetric algorithm, which means that there are two keys: one public key and one private key that must be kept secret. Auth0 has the private key used to generate the signature, and the consumer of the JWT retrieves a public key from the metadata endpoints provided by Auth0 and uses it to validate the JWT signature. Unlike RS256, the same JWT header and payload will generate a different signature each time.

The most secure practice, and our recommendation, is to use RS256 because:

* With RS256, you are sure that only the holder of the private key (Auth0) can sign tokens, while anyone can check if the token is valid using the public key.
* With RS256, if the private key is compromised, you can implement key rotation without having to re-deploy your application or API with the new secret (which you would have to do if using HS256).

For troubleshooting help, review [Troubleshooting Invalid Token Errors](/docs/troubleshoot/basic-issues/invalid-token-errors).

## Learn more

* [JSON Web Tokens](/docs/secure/tokens/json-web-tokens)
* [Change Application Signing Algorithms](/docs/get-started/applications/change-application-signing-algorithms)
* [Signing Keys](/docs/get-started/tenant-settings/signing-keys)
* [Rotate Signing Keys](/docs/get-started/tenant-settings/signing-keys/rotate-signing-keys)
* [Revoke Signing Keys](/docs/get-started/tenant-settings/signing-keys/revoke-signing-keys)
* [View Signing Certificates](/docs/get-started/tenant-settings/signing-keys/view-signing-certificates)


# Test Database Connections
Source: https://auth0.com/docs/get-started/applications/test-database-connections

Describes how to test database connections for applications using the Auth0 Dashboard.

You can test database connections for applications using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. The configured database connections can be used to log in to your application.

To properly test, you should have already [set up your database connection](/docs/get-started/applications/set-up-database-connections) and [created a user](/docs/manage-users/user-accounts/create-users) for your database connection.

1. Navigate to [Auth0 Dashboard > Authentication > Database](https://manage.auth0.com/#/connections/database), and select the **Try** arrow next to the connection you want to test.

   <Frame>
     <img alt="Dashboard - Authentication - Database - Database Connections List" />
   </Frame>
2. Enter your test user's username and password. If you have configured everything correctly, you will see the **It Works!** page:

   <Frame>
     <img alt="Dashboard - Connections - Database - Try - Success" />
   </Frame>

## Learn more

* [Set Up Database Connections](/docs/get-started/applications/set-up-database-connections)


# Update Application Connections
Source: https://auth0.com/docs/get-started/applications/update-application-connections

Describes how to update an application's enabled connections using the Auth0 Dashboard.

You can change your application's enabled connections using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

1. Go to [Dashboard > Applications](https://manage.auth0.com/#/applications) and click the name of the application to view.

   <Frame>
     <img alt="Dashboard Applications List" />
   </Frame>
2. Click the **Connections** tab, and enable or disable the appropriate connections for the application.

## Learn more

* [View Connections](/docs/authenticate/identity-providers/view-connections)
* [Verify Connections](/docs/troubleshoot/basic-issues/verify-connections)


# Update Grant Types
Source: https://auth0.com/docs/get-started/applications/update-grant-types

Learn how to update an application's grant types using the Auth0 Dashboard or the Management API.

You can change your application's grant types using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## Use the Dashboard

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and select the name of the application to view.

   <Frame>
     <img alt="Dashboard Applications List" />
   </Frame>
2. Scroll to the bottom of the page, and select **Show Advanced Settings**.
3. Select **Grant Types**, and enable or disable the appropriate grants for the application. When finished, select **Save Changes**. The device code grant type is only available for native apps.

   <Frame>
     <img alt="Dashboard Applications Application Settings Tab Advanced Settings Grant Types tab" />
   </Frame>

## Use the Management API

Make a `PATCH` call to the [`/Clients/patch_clients_by_id`](https://auth0.com/docs/api/management/v2#!/Clients/patch_clients_by_id) endpoint. Be sure to replace `{yourClientId}`, `{yourManagementApiAccessToken}`, and `{grantType}` placeholder values with your <Tooltip href="/docs/glossary?term=client+ID">client ID</Tooltip>, Management API <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, and desired grant type, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/clients/%7ByourClientId%7D' \
    --header 'authorization: Bearer {yourMgmtApiAccessToken}' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "grant_types": "{grantTypes}" }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/clients/%7ByourClientId%7D");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("application/json", "{ "grant_types": "{grantTypes}" }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/clients/%7ByourClientId%7D"

  	payload := strings.NewReader("{ "grant_types": "{grantTypes}" }")

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

  	req.Header.Add("content-type", "application/json")
  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")
  	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))

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.patch("https://{yourDomain}/api/v2/clients/%7ByourClientId%7D")
    .header("content-type", "application/json")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .header("cache-control", "no-cache")
    .body("{ "grant_types": "{grantTypes}" }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/clients/%7ByourClientId%7D',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer {yourMgmtApiAccessToken}',
      'cache-control': 'no-cache'
    },
    data: {grant_types: '{grantTypes}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer {yourMgmtApiAccessToken}",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"grant_types": @"{grantTypes}" };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/clients/%7ByourClientId%7D"]
                                                         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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/clients/%7ByourClientId%7D",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "PATCH",
    CURLOPT_POSTFIELDS => "{ "grant_types": "{grantTypes}" }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}",
      "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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "grant_types": "{grantTypes}" }"

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

  conn.request("PATCH", "/{yourDomain}/api/v2/clients/%7ByourClientId%7D", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/clients/%7ByourClientId%7D")

  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 {yourMgmtApiAccessToken}'
  request["cache-control"] = 'no-cache'
  request.body = "{ "grant_types": "{grantTypes}" }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer {yourMgmtApiAccessToken}",
    "cache-control": "no-cache"
  ]
  let parameters = ["grant_types": "{grantTypes}"] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/clients/%7ByourClientId%7D")! 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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Τhe ID of the application to be updated.</td>
    </tr>

    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td><a href="https://auth0.com/docs/api/management/v2/tokens">Access Tokens for the Management API</a> with the scope <code>update:clients</code>.</td>
    </tr>

    <tr>
      <td><code>GRANT\_TYPES</code></td>
      <td>The grant types you would like to enable for the specified application.</td>
    </tr>
  </tbody>
</table>

## Troubleshoot

Attempting to use a flow with an application lacking the appropriate `grant_types` for that flow (or with the field empty) will result in the following error:
``Grant type `grant_type` not allowed for the client.``

## Learn more

* [Application Grant Types](/docs/get-started/applications/application-grant-types)


# Subdomain URL Placeholders
Source: https://auth0.com/docs/get-started/applications/wildcards-for-subdomains

Describes placeholders, including wildcard and organization placeholders, for subdomains function in application configuration.

You can use various placeholders to act as dynamic text entries in your URLs.

## How URL evaluation works

A URL containing an `{organization_name}` placeholder will only be evaluated when all the following conditions are met:

* The application has the `organization_usage` set to `allow` or `require`
* A transaction was performed in the context of an organization (for example, initiating an authorization transaction with the organization parameter: `/authorize?organization=org_bVss9Do3994SIbiH&…`)

URLs with the `{organization_name}` placeholder will be evaluated in addition to exact match URLs (`https://app.exampleco.com`) and URLs with wildcards (`https://*.exampleco.com`). You must not rely on any specific order of evaluation of the URLs.

Avoid registering URLs with wildcard and Organization placeholders in the same configuration field for an application as it may lead to undesirable behavior and make troubleshooting difficult. As an example, consider an application with two **Allowed Callback URLs**: `https://*.exampleco.com` and `https://{organization_name}.exampleco.com`. A `redirect_uri` with the value of `https://company-a.exampleco.com` would be considered valid even if there were no Organizations with the name `company-a` registered in your tenant; this is due to the evaluation of the wildcard placeholder.

## Wildcard URL placeholders

Wildcard placeholders in subdomains **should not** be used in production applications. Auth0 recommends URLs with the `{organization_name}` placeholder where relevant.

Manage these settings in [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) in the following fields:

* **Allowed Callback URLs**: List of URLs to which Auth0 is allowed to redirect users after they authenticate.
* **Allowed Logout URLs**: List of URLs to which you can redirect users after they log out from Auth0.
* **Allows Web Origins**: List of URLs from where an authorization request using [Cross-Origin Authentication](/docs/authenticate/login/cross-origin-authentication), [Device Flow](/docs/get-started/authentication-and-authorization-flow/device-authorization-flow), and [web\_message as the response mode](/docs/authenticate/protocols/oauth) can originate.
* **Allowed Origins (CORS)**: List of URLs that will be allowed to make requests from JavaScript to Auth0 API (typically used with CORS).

Avoid using wildcard placeholders for subdomains in production application callbacks and allowed origins as it can make your application vulnerable to attacks.

You can use the star symbol (`*`) as a wildcard for subdomains, but it must be used in accordance with the following rules in order to properly function:

* The protocol of the URL **must** be `http` or `https`. Protocols such as `com.example.app` and `service:jmx:rmi` will not work.
* The wildcard **must** be located in a subdomain within the hostname component. `https://*.com` will not work.
* The wildcard **must** be located in the subdomain furthest from the root domain. `https://sub.*.example.com` will not work.
* The URL **must not** contain more than one wildcard. `https://*.*.example.com` will not work.
* A wildcard **may** be prefixed and/or suffixed with additional valid hostname characters. `https://prefix-*-suffix.example.com` will work.
* A URL with a valid wildcard **will not** match a URL more than one subdomain level in place of the wildcard. `https://*.example.com` will not work with `https://sub1.sub2.example.com`.

## Organization URL placeholders

You can use `{organization_name}` as a placeholder to dynamically specify a registered organization’s name in a URL (`https://{organization_name}.exampleco.com`). URLs with the `{organization_name}` placeholder should only be used on domains that you fully control (for example, `https://{organization_name}.exampleco.com` where you control the `exampleco.com` domain).

Manage these settings in [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) in the following fields:

* **Allowed Callback URLs**: List of URLs to which Auth0 is allowed to redirect users after they authenticate.
* **Allowed Origins (CORS)**: List of URLs that will be allowed to make requests from JavaScript to Auth0 API (typically used with CORS).

The following restrictions apply when using the `{organization_name}` placeholder:

* The protocol of the URL must be `http:` or `https:`. `com.example.app://{organization_name}.exampleco.com` will not work.
* The placeholder must be located in a subdomain within the hostname component. `https://{organization_name}` or `https://exampleco.com/{organization_name}` will both not work.
* The placeholder must be located in the subdomain furthest from the root domain. `https://sub.{organization_name}.exampleco.com` will not work.
* The URL must not contain more than one placeholder. `https://{organization_name}.{organization_name}.exampleco.com` will not work.
* A placeholder must not be prefixed nor suffixed with additional valid hostname characters. `https://prefix-{organization_name}-suffix.exampleco.com` will not work.
* A placeholder **must not** be used in conjunction with a wildcard in the URL. `https://{organization_name}.*.exampleco.com` will not work.

## Custom domain URL placeholders

You can use `{custom_domain.metadata.KEY}` as a placeholder to dynamically specify a URL based on metada associated with the Custom Domain used in the request. This allows you to support multiple custom domains with different application URLs within the same tenant.

For a comprehensive overview of this feature, see [Multiple Custom Domains](/docs/customize/custom-domains/multiple-custom-domains)

### Validation rules

The following restrictions apply when using Custom Domain placeholders:

* **Public prefix required**: The metadata key used in the placeholder must start with `public_` or `PUBLIC_` (for example, `{custom_domain.metadata.public_callback_subdomain}`). Keys without this prefix are ignored at runtime for security reasons.
* **Protocol**: The protocol of the URL must be `http` or `https`.
* **Location**: The placeholder must be located in the domain or subdomain component. It cannot be used in the URL path.
  * Valid: `https://{custom_domain.metadata.public_app_url}.example.com/login`
  * Invalid: `https://example.com/{custom_domain.metadata.public_path}`
* **Nesting**: You cannot access nested metadata properties. Only top-level keys are supported.
* **No wildcards**: A custom domain placeholder must not be used in conjunction with a wildcard (`*`) in the same URL.
* **Data type**: The value in the custom domain metadata must be a String. If the key does not exist, or the value is not a String, the URL is ignored during validation.

### Supported fields

These placeholders can be configured for the following Application URLs:

* Allowed Callback URLs
* Allowed Logour URLs
* Allowed Web Origins
* Allowed Origins (CORS)

For more information, see [Application Settings](https://auth0.com/docs/get-started/applications/application-settings#application-uris).

<Note>
  Custom domain placeholders are not supported for third-party applications.
</Note>

### Using with Organization placeholders

You can combine the Custom Domain placeholder with the `{organization_name}` placeholder, as long as your flow supports it. Both placeholders are evaluated and replaced at runtime.

## Learn more

* [Confidential and Public Applications](/docs/get-started/applications/confidential-and-public-applications)
* [First-Party and Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/first-party-and-third-party-applications)
* [Enable Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/enable-third-party-applications)


# Test Applications Locally
Source: https://auth0.com/docs/get-started/applications/work-with-auth0-locally

Learn how to develop and test Auth0 applications.

In most cases, authenticating users through Auth0 requires an internet connection. However, you can still develop and test apps that use Auth0 locally. In some cases, you might not need access to an internet connection.

To learn how to structure your development, test, and production environments when using Auth0, see [Set Up Multiple Environments](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments).

## Use JSON Web Tokens with client-side applications

Because [JSON Web Tokens (JWTs)](/docs/secure/tokens/json-web-tokens) are stateless (that is, the app that consumes them cares only about its contents, not any of its previous states), this is one of the easiest scenarios to test locally.

You can obtain <Tooltip href="/docs/glossary?term=JWTs">JWTs</Tooltip> for testing using any of the following methods:

1. Create a test user for a [database connection](/docs/get-started/applications/set-up-database-connections), and programmatically log the user in. Essentially, you are using the [Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow). For detailed implementation instructions, read [Call Your API Using the Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow/call-your-api-using-resource-owner-password-flow).
2. Use a browser bot to play the role of a user, log in and retrieve a JWT.

## Use sessions with server-side applications

Unless your server-side application allows the generation of artificial sessions for testing, you'll need a way to perform a login through Auth0 manually.

For a high-level overview of how to do this, see [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow). For detailed implementation instructions, see our tutorial, [Add Login Using the Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/add-login-auth-code-flow).

## Use local domains with Auth0

If you're developing your application locally, you can use `localhost` and other domains inaccessible by Auth0 (such as those on an intranet) as [callback URLs](/docs/authenticate/login/redirect-users-after-login). For example, during development, you could use `http://localhost:3000/callback` as the callback URL.

1. Go to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications/\{yourClientId}/settings) and click the application.
2. Add the URL to the **Allowed Callback URLs** list.

Because Auth0's main identity protocol is [OpenID Connect (OIDC)](/docs/authenticate/protocols/openid-connect-protocol), Auth0 never needs to directly call your application's server. Instead, Auth0 redirects users to your application's endpoint(s) with required information contained in a query string or hash fragment.

## Divert emails for testing

If you want to test your local application and do not want the emails (creation, validation, etc.) to be delivered to the actual email address of the users your application creates or validates, Auth0 recommends using a custom email provider. For example, a service like [Mailtrap](https://mailtrap.io/signin) or your own custom SMTP server implementation can apply whatever logic you require to trap the emails. This ensures that users do not receive emails but you can access them for validation and troubleshooting. To learn more, read [Configure Test SMTP Email Server](/docs/customize/email/configure-test-smtp-email-servers).

Auth0 does not allow certain "false" domains commonly used during testing. Use real email addresses to avoid disruption or errors.

## Learn more

* [Verify Domain](/docs/troubleshoot/basic-issues/verify-domain)
* [Verify Platform](/docs/troubleshoot/basic-issues/verify-platform)


# Auth0 Overview
Source: https://auth0.com/docs/get-started/auth0-overview

Describes Auth0 services and helps you get started using them with your applications and APIs.

Auth0 is a flexible, drop-in solution to add authentication and authorization services to your applications. Your team and organization can avoid the cost, time, and risk that come with building your own solution to authenticate and authorize users.

Take a look at just a few of Auth0's use cases:

* You built an awesome app and you want to add user authentication and authorization. Your users should be able to log in either with an identifier (username, email, or phone number) and password or with their social accounts (such as Facebook or X). You want to retrieve the user's profile after the login so you can customize the UI and apply your authorization policies.
* You built an API and you want to secure it with [OAuth 2.0](/docs/authenticate/protocols/oauth).
* You have more than one app, and you want to implement [Single Sign-on (SSO)](/docs/authenticate/single-sign-on).
* You built a JavaScript front-end app and a mobile app, and you want them both to securely access your API.
* You have a web app that needs to authenticate users using [Security Assertion Markup Language (SAML)](/docs/authenticate/protocols/saml/saml-configuration).
* You believe passwords are broken and you want your users to log in with one-time codes delivered by email or SMS.
* If one of your user's email addresses is compromised in some site's public data breach, you want to be notified, and you want to notify the users and/or block them from logging in to your app until they reset their password.
* You want to act proactively to block suspicious IP addresses if they make consecutive failed login attempts, in order to avoid DDoS attacks.
* You are part of a large organization that wants to federate your existing enterprise directory service to allow employees to log in to the various internal and third-party applications using their existing enterprise credentials.
* You don't want (or you don't know how) to implement your own user management solution. Password resets, creating, provisioning, blocking, and deleting users, and the UI to manage all these. You just want to focus on your app.
* You want to enforce [multi-factor authentication (MFA)](/docs/secure/multi-factor-authentication) when your users want to access sensitive data.
* You are looking for an identity solution that will help you stay on top of the constantly growing compliance requirements of SOC2, GDPR, PCI DSS, HIPAA, and others.
* You want to monitor users on your site or application. You plan on using this data to create funnels, measure user retention, and improve your sign-up flow.
* You want robust authorization policy to allow your users access to resources based on [their relationship](https://docs.fga.dev/authorization-concepts) to the resource or [their role](/docs/manage-users/access-control/rbac) in your organization.

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/get-started/auth0-overview/dashboard">Auth0 Dashboard</a></td>
      <td>About the Auth0 Dashboard and features you can access to implement authentication and authorization with your applications and APIs.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/auth0-overview/create-tenants">Create Tenants</a></td>
      <td>How to create tenants using the Auth0 Dashboard or the Management API, explore creating multiple tenants and child tenants, and learn about setting up multiple environments.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/auth0-overview/create-applications">Create Applications</a></td>
      <td>How to set up and configure applications in the Auth0 Dashboard.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/auth0-overview/set-up-apis">Register APIs</a></td>
      <td>How to set up and configure APIs in the Auth0 Dashboard.</td>
    </tr>
  </tbody>
</table>

## Learn more

* [Create Tenants](/docs/get-started/auth0-overview/create-tenants)
* [Auth0 Dashboard](/docs/get-started/auth0-overview/dashboard)
* [Architecture Scenarios](/docs/get-started/architecture-scenarios)
* [Protocols](/docs/authenticate/protocols)


# Create Applications
Source: https://auth0.com/docs/get-started/auth0-overview/create-applications

Learn how to set up and configure applications in the Auth0 Dashboard.

An **application** in Auth0 can be a native app that executes on a mobile device, a single-page web app that executes on a browser, or a regular web application that executes on a server.

When you create an application in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, Auth0 assigns it a **<Tooltip href="/docs/glossary?term=client+ID">client ID</Tooltip>** which is an alphanumeric string that is the unique identifier for your application. You will use this ID in your application code when you call Auth0 APIs. You can't modify the client ID.

Another important piece of information is the **<Tooltip href="/docs/glossary?term=client+secret">client secret</Tooltip>**. It must be kept confidential at all times. If anyone gains access to your application's client secret, then they can impersonate your application and access protected resources. It is important that you select the correct application type to help Auth0 check for certain security risks.

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications).
2. Click **Create Application**.
3. Give your new application a descriptive name.
4. Choose from the following app types:

   * **Native Applications**: These applications include mobile, desktop, or hybrid apps running natively on a device (e.g., i0S, Android).
   * **Single-Page Web Applications**: These applications include JavaScript apps that perform most of their user interface logic in a web browser, communicating with a web server primarily using APIs (e.g., AngularJS + Node.js or React).
   * **Regular Web Applications**: These applications are traditional web applications that perform most of their application logic on the server (e.g., Express.js, ASP.NET).
   * **Machine-to-Machine Applications**: These applications include non-interactive applications, such as command-line tools, daemons, IoT devices, or services running on your back-end.
5. Click **Create**.

The **Application** **Details** page appears which includes the following tabs:

<table>
  <thead>
    <tr>
      <th><strong>Settings Tab</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Quick Start</strong></td>
      <td>Shows all the available documentation for your application type.</td>
    </tr>

    <tr>
      <td><strong>Settings</strong></td>
      <td>Shows all available settings for your application. By default, most of the settings will be created for you. To learn more, read <a href="/docs/get-started/applications/application-settings">Application Settings</a>.</td>
    </tr>

    <tr>
      <td><strong>Credentials</strong></td>
      <td>Shows the application’s authentication method and configured credentials. To learn more, read <a href="/docs/secure/application-credentials">Application Credentials</a></td>
    </tr>

    <tr>
      <td><strong>Add-ons</strong></td>
      <td>Allows you to enable plugins associated with an application. These are SAML or WS-Fed web apps for which Auth0 generates access tokens. To learn more, read <a href="/docs/authenticate/protocols/saml/saml-sso-integrations/enable-saml2-web-app-addon">Enable SAML2 Web App Addon</a> and <a href="/docs/get-started/applications/update-application-connections">Configure WS-Fed Applications</a>.</td>
    </tr>

    <tr>
      <td><strong>Connections</strong></td>
      <td>Allows you to enable connections for your application. Connections are sources of users; they can be enabled and shared between multiple applications. To learn more, read <a href="/docs/authenticate/identity-providers">Connections</a>.</td>
    </tr>

    <tr>
      <td><strong>Organizations</strong></td>
      <td>Allows you to authenticate users into organizations to which they belong. To learn more, read <a href="/docs/manage-users/organizations">Organizations</a>.</td>
    </tr>
  </tbody>
</table>

## Learn more

* [Register Native Applications](/docs/get-started/auth0-overview/create-applications/native-apps)
* [Register Single-Page Web Applications](/docs/get-started/auth0-overview/create-applications/single-page-web-apps)
* [Register Regular Web Applications](/docs/get-started/auth0-overview/create-applications/regular-web-apps)
* [Register Machine-to-Machine Applications](/docs/get-started/auth0-overview/create-applications/machine-to-machine-apps)
* [Application Settings](/docs/get-started/applications/application-settings)
* [Remove Applications](/docs/get-started/applications/remove-applications)


# Configure an Identity Provider in Access Gateway
Source: https://auth0.com/docs/get-started/auth0-overview/create-applications/configure-an-identity-provider-in-access-gateway

Configure an identity provider in OAG

To integrate Auth0 with a machine-to-machine (M2M) application, you must first register your app with Auth0 using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and click **Create Application**.

2. Enter a descriptive name for your application, select **Machine to Machine Applications**, and click **Create**.

3. Select the Management API to authorize M2M communication, as this is how OAG interacts with Auth0.

4. Click **Authorize**.

5. Each M2M app that accesses an API must be granted a set of permissions (or scopes) that should be granted by the authenticated user. Select the **Permissions** that you want to be issued as part of your application's <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>. OAG requires the following permissions for the **client** and **users:**

* `read:client, write:client, update:client, delete:client`
* `read:users`

6. Click **Authorize**.

7. Select the **Credentials** tab of your application.

8. Click the **<Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>** and copy it into a text editor app.

9. Click the **<Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip>** and copy it into a text editor app.

10. Continue with the \[Configure an Identity Provider in Access Gateway]\(/docs/Configure an Identity Provider in Access Gateway) procedure.


# Register Machine-to-Machine Applications
Source: https://auth0.com/docs/get-started/auth0-overview/create-applications/machine-to-machine-apps

Learn how to register and configure a machine-to-machine (M2M) application using the Auth0 Dashboard and authorize it using the Management API test feature.

To integrate Auth0 with a machine-to-machine (M2M) application, you must first register your app with Auth0 using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. These apps may include non-interactive apps, such as command-line tools, daemons, IoT devices, or services running on your back-end.

M2M apps are linked to an API and its permissions or [scopes](/docs/get-started/apis/scopes/api-scopes), which are selected from pre-defined values. Make sure you have already [registered the associated API](/docs/get-started/auth0-overview/set-up-apis) with Auth0 and defined scopes for the API before beginning this registration.

If you want to authorize your application to access only the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>, you do not need to register a separate API; the Management API is pre-populated for you.

To integrate Auth0 with a machine-to-machine (M2M) application, you must first register your app with Auth0 using the Auth0 Dashboard.

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and click **Create Application**.
2. Enter a descriptive name for your application, select **Machine to Machine Applications**, and click **Create**.
3. Select the API you want to be able to call from your application.
4. Each M2M app that accesses an API must be granted a set of permissions (or scopes) that should be granted by the authenticated user. To learn how to add permissions, see [Add API Permissions](/docs/get-started/apis/add-api-permissions). Select the **Permissions** that you want to be issued as part of your application's access token, and click **Authorize**.

   <Warning>
     Use the `update:client_grants` and `create:client_grants` scopes with only high-privileged applications, as they allow the client to grant further permissions to itself.
   </Warning>

   Once the new application is created, you can configure **Application Settings** which includes the following tabs:

   <table>
     <thead>
       <tr>
         <th><strong>Settings Tab</strong></th>
         <th><strong>Description</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td><strong>Quick Start</strong></td>
         <td>Shows all the available examples for \$ applications. It also shows you how you can call your API using various technologies. To learn how to accept and validate Access Tokens in your API, see our <a href="/docs/quickstart/backend/nodejs/interactive">Backend/API Quickstarts</a>.</td>
       </tr>

       <tr>
         <td><strong>Settings</strong></td>
         <td>Shows all available settings for your application. By default, Auth0 creates most of these settings for you.</td>
       </tr>

       <tr>
         <td><strong>Credentials</strong></td>
         <td>Shows the application’s authentication method and configured credentials. To learn more, read <a href="/docs/secure/application-credentials">Application Credentials</a></td>
       </tr>

       <tr>
         <td><strong>APIs</strong></td>
         <td>Allows you to authorize additional APIs for use with your Application.</td>
       </tr>
     </tbody>

     <tr>
       <td><strong>Login Experience</strong></td>
       <td>Allows you to configure the login experience for users in your Organization. For more information, see [Understand How Auth0 Organizations Work](/docs/manage-users/organizations/organizations-overview#login-experience)</td>
     </tr>
   </table>

   To learn more, read [Application Settings](/docs/get-started/applications/application-settings).

## Next steps

Once you have registered and configured your application, some common next steps are:

* Configure an identity provider connection and enable it for your application (if needed for your use case).
* Modify your app code to use your Auth0-registered application. See our [Auth0 Quickstarts](/docs/quickstarts), where you'll find detailed instructions and samples for a variety of technologies. You'll also learn how to implement login and logout, handle your user sessions, retrieve and display user profile information, and more.
* Use [Auth0 APIs](/docs/api).

  * The [Authentication API](https://auth0.com/docs/api/authentication) handles all primary identity-related functions (for example, login, logout, and get user profile). Most users consume this API through our Quickstarts, the [Auth0.js library](/docs/libraries/auth0js), or the [Lock widget](/docs/libraries/lock). However, if you are building all of your authentication UI manually, you will have to interact with this API directly.
  * The [Management API](https://auth0.com/docs/api/management/v2) allows you to automate various tasks that can also be accessed via the Dashboard in Auth0 (for example: creating users, setting application grant types).

## Learn more

* [Register APIs](/docs/get-started/auth0-overview/set-up-apis)
* [Create Machine-to-Machine Applications for Testing](/docs/get-started/apis/create-m2m-app-test)
* [Application Settings](/docs/get-started/applications/application-settings)
* [Add API Permissions](/docs/get-started/apis/add-api-permissions)
* [Delete API Permissions](/docs/get-started/apis/delete-api-permissions)


# Register Native Applications
Source: https://auth0.com/docs/get-started/auth0-overview/create-applications/native-apps

Learn how to register and configure a native application using the Auth0 Dashboard.

To integrate Auth0 with a native application, you must first register your app with Auth0 using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. Native apps should use the Authorization Code flow with PKCE for secure authentication. To learn more, read [Authorization Code Flow with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce). These apps may include mobile, desktop, or hybrid apps running natively in a device (for example, iOS, Android).

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and click **Create Application**.
2. Enter a descriptive name for your application, select **Native**, and click **Create**.

   Once you create the application, Auth0 directs you to **Application Settings**, which includes the following tabs:

   <table>
     <thead>
       <tr>
         <th><strong>Settings Tab</strong></th>
         <th><strong>Description</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td><strong>Quick Start</strong></td>
         <td>Shows all the available documentation for your application type.</td>
       </tr>

       <tr>
         <td><strong>Settings</strong></td>
         <td>Shows all available settings for your application. By default, most of the settings will be created for you. To learn more, read <a href="/docs/get-started/applications/application-settings">Application Settings</a>.</td>
       </tr>

       <tr>
         <td><strong>Credentials</strong></td>
         <td>Shows the application’s authentication method and configured credentials. To learn more, read <a href="/docs/secure/application-credentials">Application Credentials</a></td>
       </tr>

       <tr>
         <td><strong>Add-ons</strong></td>
         <td>Allows you to enable plugins associated with an application. Add-ons are primarily used for SAML or WS-Fed integrations and are typically not applicable to native applications. To learn more, read <a href="/docs/authenticate/protocols/saml/saml-sso-integrations/enable-saml2-web-app-addon">Enable SAML2 Web App Addon</a> and <a href="/docs/get-started/applications/update-application-connections">Configure WS-Fed Applications</a>.</td>
       </tr>

       <tr>
         <td><strong>Connections</strong></td>
         <td>Allows you to enable connections for your application. Connections are sources of users; they can be enabled and shared between multiple applications. To learn more, read <a href="/docs/authenticate/identity-providers">Connections</a>.</td>
       </tr>

       <tr>
         <td><strong>Organizations</strong></td>
         <td>Allows you to authenticate users into organizations to which they belong. To learn more, read <a href="/docs/manage-users/organizations">Organizations</a>.</td>
       </tr>

       <tr>
         <td><strong>Login Experience</strong></td>
         <td>Allows you to configure the login experience for users in your Organization. For more information, read [Understand how Auth0 Organizations Work](/docs/manage-users/organizations/organizations-overview#login-experience).</td>
       </tr>
     </tbody>
   </table>

   To learn more, read [Application Settings](/docs/get-started/applications/application-settings).
3. If you're developing a mobile app, provide the necessary iOS/Android parameters in the **Advanced Settings** area, and click **Save Changes**.

   * For iOS apps, [provide your **Team ID** and **App Bundle Identifier**](/docs/get-started/applications/enable-universal-links-support-in-apple-xcode).
   * For Android apps, [provide your **App Package Name** and your **Key Hashes**](/docs/get-started/applications/enable-android-app-links-support).

## Next steps

Once you have registered and configured your application, some common next steps are:

* Configure a connection and enable it for your application.
* Modify your app code to use your Auth0-registered application. See our [Auth0 Quickstarts](/docs/quickstarts), where you'll find detailed instructions and samples for a variety of technologies. You'll also learn how to implement login and logout, handle your user sessions, retrieve and display user profile information, and more.
* Use [Auth0 APIs](/docs/api).

  * The [Authentication API](https://auth0.com/docs/api/authentication) handles all primary identity-related functions (for example, login, logout, and get user profile). Most users consume this API through our Quickstarts, the [Auth0.js library](/docs/libraries/auth0js), or the [Lock widget](/docs/libraries/lock). However, if you are building all of your authentication UI manually, you will have to interact with this API directly.
  * The [Management API](https://auth0.com/docs/api/management/v2) allows you to automate various tasks that can also be accessed via the Dashboard in Auth0 (for example: creating users, setting application grant types).

## Learn more

* [Application Settings](/docs/get-started/applications/application-settings)
* [Add Bot Detection to Native Applications](/docs/secure/attack-protection/bot-detection/bot-detection-native-apps)


# Register Regular Web Applications
Source: https://auth0.com/docs/get-started/auth0-overview/create-applications/regular-web-apps

Learn how to register and configure a regular web application using the Auth Dashboard.

To integrate Auth0 with a regular web app, you must first register your app with Auth0 using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. Regular web apps are traditional web applications that perform most of their application logic on the server (for example, Express.js, ASP.NET). To learn more about application types, read [Application Types](/docs/get-started/applications).

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and click **Create Application**.
2. Enter a descriptive name for your application, select **Regular Web Applications**, and click **Create**.

   Once the new application is created, you can view the **Application Settings** page, which includes the following tabs:

   <table>
     <thead>
       <tr>
         <th><strong>Settings Tab</strong></th>
         <th><strong>Description</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td><strong>Quick Start</strong></td>
         <td>Shows all the available documentation for your application type.</td>
       </tr>

       <tr>
         <td><strong>Settings</strong></td>
         <td>Shows all available settings for your application. By default, most of the settings will be created for you. To learn more, read <a href="/docs/get-started/applications/application-settings">Application Settings</a>.</td>
       </tr>

       <tr>
         <td><strong>Credentials</strong></td>
         <td>Shows the application’s authentication method and configured credentials. To learn more, read <a href="/docs/secure/application-credentials">Application Credentials</a></td>
       </tr>

       <tr>
         <td><strong>Add-ons</strong></td>
         <td>Allows you to enable plugins associated with an application. These are SAML or WS-Fed web apps for which Auth0 generates access tokens. To learn more, read <a href="/docs/authenticate/protocols/saml/saml-sso-integrations/enable-saml2-web-app-addon">Enable SAML2 Web App Addon</a> and <a href="/docs/get-started/applications/update-application-connections">Configure WS-Fed Applications</a>.</td>
       </tr>

       <tr>
         <td><strong>Connections</strong></td>
         <td>Allows you to enable connections for your application. Connections are sources of users; they can be enabled and shared between multiple applications. To learn more, read <a href="/docs/authenticate/identity-providers">Connections</a>.</td>
       </tr>

       <tr>
         <td><strong>Organizations</strong></td>
         <td>Allows you to authenticate users into organizations to which they belong. To learn more, read <a href="/docs/manage-users/organizations">Organizations</a>.</td>
       </tr>

       <tr>
         <td><strong>Login Experience</strong></td>
         <td>Allows you to configure the login experience for users in your Organization. For more information, read [Understand how Auth0 Organizations Work](/docs/manage-users/organizations/organizations-overview#login-experience).</td>
       </tr>
     </tbody>
   </table>

   To learn more, read [Application Settings](/docs/get-started/applications/application-settings).
3. Scroll down and locate the **Trust Token Endpoint IP Header** setting. If your application architecture supports it, enable this setting and click **Save Changes**. This setting helps protect against brute-force attacks by allowing Auth0 to trust IP headers from your proxy.

## Next steps

Once you have registered and configured your application, follow these next steps:

1. Configure a connection and enable it for your application.
2. Implement authentication in your app code by using your Auth0-registered application. See our [Auth0 Quickstarts](/docs/quickstarts), where you'll find detailed instructions and samples for a variety of technologies. You'll also learn how to implement login and logout, handle your user sessions, retrieve and display user profile information, and more.

* Use [Auth0 APIs](/docs/api).

  * The [Authentication API](https://auth0.com/docs/api/authentication) handles all primary identity-related functions (for example, login, logout, and get user profile). Most users consume this API through our Quickstarts, the [Auth0.js library](/docs/libraries/auth0js), or the [Lock widget](/docs/libraries/lock). However, if you are building all of your authentication UI manually, you can interact with this API directly.
  * The [Management API](https://auth0.com/docs/api/management/v2) allows you to automate various tasks that you can also access via the Auth0 Dashboard (for example, creating users and setting application grant types).

## Learn more

* [Application Settings](/docs/get-started/applications/application-settings)
* [Regular Web Applications with Single Sign-On](/docs/get-started/architecture-scenarios/sso-for-regular-web-apps)


# Register Single-Page Web Applications
Source: https://auth0.com/docs/get-started/auth0-overview/create-applications/single-page-web-apps

Learn how to register a single-page web application (SPA) using the Auth0 Dashboard.

To integrate Auth0 with a single-page web app, you must first register your app with Auth0 using the Dashboard.

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and click **Create Application**.
2. Enter a descriptive name for your application, select **Single-Page Web Applications**, and click **Create**.

   Once the new application is created, you can view the **Application Settings** page, which includes the following tabs:

   <table>
     <thead>
       <tr>
         <th><strong>Settings Tab</strong></th>
         <th><strong>Description</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td><strong>Quick Start</strong></td>
         <td>Shows all the available documentation for your application type.</td>
       </tr>

       <tr>
         <td><strong>Settings</strong></td>
         <td>Shows all available settings for your application. By default, most of the settings will be created for you. To learn more, read <a href="/docs/get-started/applications/application-settings">Application Settings</a>.</td>
       </tr>

       <tr>
         <td><strong>Credentials</strong></td>
         <td>Shows the application’s authentication method and configured credentials. To learn more, read <a href="/docs/secure/application-credentials">Application Credentials</a></td>
       </tr>

       <tr>
         <td><strong>Add-ons</strong></td>
         <td>Allows you to enable plugins associated with an application. These are typically used for SAML or WS-Fed integrations, which are not commonly needed for SPAs. To learn more, read <a href="/docs/authenticate/protocols/saml/saml-sso-integrations/enable-saml2-web-app-addon">Enable SAML2 Web App Addon</a> and <a href="/docs/get-started/applications/update-application-connections">Configure WS-Fed Applications</a>.</td>
       </tr>

       <tr>
         <td><strong>Connections</strong></td>
         <td>Allows you to enable connections for your application. Connections are sources of users; they can be enabled and shared between multiple applications. To learn more, read <a href="/docs/authenticate/identity-providers">Connections</a>.</td>
       </tr>

       <tr>
         <td><strong>Organizations</strong></td>
         <td>Allows you to authenticate users into organizations to which they belong. To learn more, read <a href="/docs/manage-users/organizations">Organizations</a>.</td>
       </tr>

       <tr>
         <td><strong>Login Experience</strong></td>
         <td>Allows you to configure the login experience for users in your Organization. For more information, read [Understand how Auth0 Organizations Work](/docs/manage-users/organizations/organizations-overview#login-experience).</td>
       </tr>
     </tbody>
   </table>

   To learn more, read [Application Settings](/docs/get-started/applications/application-settings).

## Next steps

Once you have registered your application, review and complete these configuration steps:

* Configure at least one connection (such as a database connection or social login) and enable it for your application. Without an enabled connection, users cannot authenticate.
* Modify your app code to use your Auth0-registered application. Review our [Auth0 Quickstarts](/docs/quickstarts), where you'll find detailed instructions on how to implement login and logout, handle your user sessions, retrieve and display user profile information, and more.
* Use [Auth0 APIs](/docs/api).

  * The [Authentication API](https://auth0.com/docs/api/authentication) handles all primary identity-related functions (for example, login, logout, and get user profile). Most users consume this API through our Quickstarts, the [Auth0 SPA SDK](/docs/libraries/auth0-spa-js), or the [Lock widget](/docs/libraries/lock). For legacy applications, see the [Auth0.js library](/docs/libraries/auth0js). However, if you are building all of your authentication UI manually, you will have to interact with this API directly.
  * The [Management API](https://auth0.com/docs/api/management/v2) allows you to automate various tasks that can also be accessed via the Dashboard in Auth0 (for example: creating users, setting application grant types).

## Learn more

* [Application Settings](/docs/get-started/applications/application-settings)
* [Authenticate Single-Page Apps With Cookies](/docs/manage-users/cookies/spa-authenticate-with-cookies)
* [Get Management API Access Tokens for Single-Page Applications](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-tokens-for-single-page-applications)


# Create Tenants
Source: https://auth0.com/docs/get-started/auth0-overview/create-tenants

Describes how to create a tenant and learn the basics of Auth0 and familiarize yourself with the terminology.

We will walk through the initial steps of getting started using Auth0 to familiarize you with the key concepts of the Auth0 service. We will use the company **Example-Co** to help describe some of the steps involved.

## Set up an Auth0 account

If you haven't already [signed up](https://auth0.com/signup) for an Auth0 **account**, do so (it's free). You can either use username/email/phone and password or log in with a social provider (such as LinkedIn, Microsoft, GitHub, or Google).

## Create a tenant and domain

Once you create your account you will be asked to create a **tenant**. Everything starts with an Auth0 tenant. This is where you configure your use of Auth0, and then where Auth0 assets - such as [applications](/docs/get-started/applications), [connections](/docs/authenticate/identity-providers), and [user profiles](/docs/get-started/architecture-scenarios/business-to-business/profile-management) - are defined, managed and stored. You access an Auth0 tenant via the Auth0 [Dashboard](/docs/get-started/auth0-overview/dashboard), where you can also create additional, associated tenants. You can create more than one Auth0 tenant so that you can structure your tenants in a way that will isolate different domains of users and also support your Software Development Life Cycle (SDLC).

**Tenant names cannot be changed or reused once deleted.** So, make sure you're happy with the name(s) before you create your Auth0 tenants.

Determining the level of isolation you require when it comes to your user domains is an important step, and together with your branding requirements helps you determine the number of Auth0 tenants needed in your environment. The number of Auth0 tenants you need to manage can quickly grow so consider carefully before creating multiple Auth0 tenants for production.

Tenant characteristics:

* The tenant name has to be unique. It will be used to create your personal domain.
* The tenant name can contain only lowercase alphanumeric characters and hyphens ("-"). It cannot begin or end with a hyphen.
* The tenant name must be a minimum of 3 characters and a maximum of 63 characters.
* The tenant name cannot be changed after creation.
* You can create more than one tenant; in fact, you are encouraged to do so for each environment you may have such as development, staging, or production. To learn more, read [Set Up Multiple Environments](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments).

When you name your tenant, that name becomes part of your Auth0 **domain** until and unless you create a <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip>. This domain is the base URL used to access the Auth0 API and the URL where your users authenticate.

### Region, locality, and sub-locality

The domain name is also made up of the locality value from a **region**. We support the following locality values for the [public cloud deployment option](/docs/deploy-monitor/deployment-options):

<table>
  <thead>
    <tr>
      <th><strong>Region</strong></th>
      <th><strong>Locality</strong></th>
      <th><strong>Sub-localities</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Australia</td>
      <td>AU</td>
      <td>AU</td>
    </tr>

    <tr>
      <td>Canada</td>
      <td>CA</td>
      <td>CA</td>
    </tr>

    <tr>
      <td>Europe</td>
      <td>EU</td>
      <td>EU, EU-2</td>
    </tr>

    <tr>
      <td>Japan</td>
      <td>JP</td>
      <td>JP</td>
    </tr>

    <tr>
      <td>United Kingdom</td>
      <td>UK</td>
      <td>UK</td>
    </tr>

    <tr>
      <td>United States of America</td>
      <td>US</td>
      <td>US, US-3, US-4, US-5</td>
    </tr>
  </tbody>
</table>

Each of these localities is separated into a sub-locality (or **tenant environment**) with a digit after the locality, e.g. `EU-2`. Tenant environments cannot be chosen manually, but localities based on the selected region may be specified, which control the assigned tenant domain and the region where your data will be hosted.

In our example, **Example-Co** chose the name `example-co` and AU as their region. So their domain is `example-co.au.auth0.com`.

## Custom domains

We recommend the use of custom domains, such as `example-co.com`, in production environments to provide your users with the most secure and seamless experience.

If you have a **single-tenant** implementation, custom domain certificates can be managed by Auth0 or self-managed by you.

To learn more, read [Custom Domains](/docs/customize/custom-domains).

## What's next

* **Create and register applications**: Now that you have an account and a domain, you need to register each application that will use our services in the [Auth0 Dashboard](https://manage.auth0.com/#/applications). To learn more, read [Applications in Auth0](/docs/get-started/applications) and [Create Applications](/docs/get-started/auth0-overview/create-applications).
* **Set up connections**: Next, you need to set up how your users will authenticate during log in. Auth0 sits between your app and the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> that authenticates your users (such as Google or Facebook). The relationship between Auth0 and the identity provider is referred to as a **connection**. By using this connection layer, Auth0 keeps your app isolated from any changes that occur with the identity provider's implementation. To learn more, read [Authentication and Authorization](/docs/get-started/identity-fundamentals/authentication-and-authorization) and [Connections](/docs/authenticate/identity-providers).

## Extend Auth0's functionality

Auth0 offers several ways to extend the platform's functionality:

* [Actions](/docs/customize/actions): Actions are secure, tenant-specific, versioned functions written in Node.js that execute at certain points within the Auth0 platform. Use Actions to customize and extend Auth0's capabilities with custom login.
* [Rules](/docs/customize/rules): Rules are functions written in JavaScript or C#, that are executed in Auth0 just after successful authentication and before control returns to your app. Rules can be chained together for modular coding and can be turned on and off individually. You can use Rules for:

  * Access control
  * Webhooks
  * Profile enrichment
  * Multi-factor authentication (MFA)
* [Hooks](/docs/customize/hooks): Hooks allow you to customize the behavior of Auth0 using Node.js code that is executed against extensibility points (which are comparable to webhooks that come with a server). They are secure, self-contained functions associated with specific extensibility points of the Auth0 platform. Auth0 invokes the Hooks at runtime to execute your custom logic.
* [Extensions](/docs/customize/extensions): Auth0 Extensions enable you to install applications or run commands/scripts that extend the functionality of the Auth0 base product. You can either use one of the pre-defined extensions, provided by Auth0, or create your own. Some of the actions you can do with extensions include:

  * Manage the authorizations for users (using groups, roles, and permissions)
  * Import/export users
  * Export logs to other services
  * Deploy scripts from external repositories

## Learn more

* [Tenant Settings](/docs/get-started/tenant-settings)
* [Create Multiple Tenants](/docs/get-started/auth0-overview/create-tenants/create-multiple-tenants)
* [Link Multiple Tenants to a Single Subscription](/docs/get-started/auth0-overview/create-tenants/child-tenants)
* [Set Up Multiple Environments](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments)


# Link Multiple Tenants to a Single Subscription
Source: https://auth0.com/docs/get-started/auth0-overview/create-tenants/child-tenants

Learn how to request linking of multiple tenants under a single Auth0 subscription.

Auth0 offers the ability for customers with an Enterprise subscription to link multiple tenants under a single Auth0 subscription (these linked tenants can also be referred to as child tenants).

This feature can be useful under the following situations:

* Separate development and production tenants while keeping the same feature access on development tenants as available in production tenants
* Own more than one production tenant under a single Enterprise subscription

## Linking tenants

Enterprise subscription automatically allows for users to link tenants under an existing Auth0 subscription by selection "Custom Agreement" option from Create Under when creating new tenants.

<Frame>
  <img alt="" />
</Frame>

If you need to link previously created tenants that are not currently part of your Enterprise subscription, contact your designated Technical Account Manager.

<Callout icon="file-lines">
  You can also link accounts if you have a self-service tenant. To learn more, read [Tenant Management](/docs/get-started/auth0-teams/tenant-management).
</Callout>

## Usage Consolidation

Usage from linked tenants count toward the Enterprise subscription limits and are aggregated under applicable usage and quota reports.

## Learn more

* [Create Multiple Tenants](/docs/get-started/auth0-overview/create-tenants/create-multiple-tenants)
* [Delete or Reset Tenants](/docs/troubleshoot/customer-support/manage-subscriptions/delete-or-reset-tenant)
* [Set Up Multiple Environments](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments)


# Create Multiple Tenants
Source: https://auth0.com/docs/get-started/auth0-overview/create-tenants/create-multiple-tenants

Describes how to create an additional tenant using the Auth0 Dashboard.

You can configure multiple tenants to create [different environments](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments) in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> to allow for complex configurations. For example, you could have two separate domains (one internal and one public-facing), or you may want users to log in differently for different applications. The way to accomplish this is to create more than one Auth0 tenant to allow you to have separate sets of applications, connections, and users for the applications and groups of users that you need to support.

1. Go to the [Auth0 Dashboard](https://manage.auth0.com/#/), select your tenant name, and select **Create Tenant**.

   <Frame>
     <img alt="Dashboard Tenant Drop-Down Menu Create Tenant" />
   </Frame>
2. Enter your desired **Tenant Domain**, select a **Region**, and select **Create**.

## Learn more

* [Multiple Organization Architecture](/docs/get-started/architecture-scenarios/multiple-organization-architecture)
* [Set Up Multiple Environments](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments)
* [Delete or Reset Tenants](/docs/troubleshoot/customer-support/manage-subscriptions/delete-or-reset-tenant)
* [Multi-Tenant Applications Best Practices](/docs/get-started/auth0-overview/create-tenants/multi-tenant-apps-best-practices)
* [Tenant Settings](/docs/get-started/tenant-settings)


# Multi-Tenant Applications Best Practices
Source: https://auth0.com/docs/get-started/auth0-overview/create-tenants/multi-tenant-apps-best-practices

Describes best practices for how to use Auth0 to secure your multi-tenant applications.

Multi-tenancy is an architectural approach featuring a single instance of software that runs on a server and is accessible by multiple groups of users. With multi-tenancy, you can segment users with shared characteristics into groups and grant them separate permissions and levels of access to your application. This allows you to create and maintain tailored experiences for different customers, business units, or other defined groups of users.

In Auth0, the best method for implementing multi-tenancy is [Auth0 Organizations](/docs/manage-users/organizations/organizations-overview). If necessary, other legacy solutions can be used to accommodate distinct business use cases. If you offer a [business-to-business (B2B)](/docs/get-started/architecture-scenarios/business-to-business) product or service, setting up multi-tenancy for your business users may be beneficial for your use case.

The sections below outline the options available for implementing multi-tenancy in Auth0.

<Warning>
  This article uses the software architecture term "tenant" to refer to a group of users who can access your application. When referring to your Auth0 instance, the term "Auth0 tenant" is used.
</Warning>

## Auth0 Organizations

For most multi-tenant use cases, Auth0 Organizations is the ideal solution for you and your users. Auth0 Organizations supports business-to-business (B2B) implementations that have one or more applications that end-users can access.

Common features of B2B implementations include:

* A product that is licensed to another business for use by their employees.
* Multiple organizations that require their own federation and lightweight branding of the authentication experience.
* Separate levels of application access for different groups of users.

With Auth0 Organizations, you can create unique groups of users and tailor their experiences with [role-based access control](/docs/manage-users/access-control/rbac), [customized login pages and email templates](/docs/manage-users/organizations/create-first-organization#customize-prompts-and-email-templates), and more.

To learn more about using Auth0 Organizations to implement multi-tenancy, review [Multiple Organization Architecture](/docs/get-started/architecture-scenarios/multiple-organization-architecture).

## Legacy solutions

If Auth0 Organizations does not satisfy the requirements of your use case, please reach out to our [Professional Services](/docs/get-started/professional-services) team to develop a solution that ensures your success.

Some legacy solutions include:

* Using an Auth0 connection to represent each tenant.
* Using an Auth0 application to represent each tenant.
* Using an Auth0 tenant to represent each tenant.
* Storing tenant details in the user's profile.

### Use Auth0 connections

<Callout icon="file-lines">
  Entity limits may apply. To learn more, read [Entity Limit Policy](/docs/troubleshoot/customer-support/operational-policies/entity-limit-policy). If you have an Enterprise subscription, you will not be constrained due to entity limits, but you may be constrained by a connection that already has thousands of enabled clients.
</Callout>

You can represent each of your tenants with a separate Auth0 connection.

This approach allows you to support scenarios where:

* You have different connection-level requirements, such as varying password policies, for each of your tenants.
* You have user pools from different connections. For example, one tenant could require users to provide username/password credentials, while another tenant could require users to log in through an enterprise <Tooltip href="/docs/glossary?term=IdP">IdP</Tooltip>.

To prompt a user to log in through a specific connection, call the [Auth0 Authentication API Login endpoint](https://auth0.com/docs/api/authentication#login), and include the `connection` parameter.

<Warning>
  If you use [Lock](/docs/libraries#lock) in your application, note that it supports a maximum of 50 database connections per application. Social and enterprise connections are not affected by this limit, but are still subject to the [Entity Limit Policy](/docs/troubleshoot/customer-support/operational-policies/entity-limit-policy).
</Warning>

### Use Auth0 applications

<Callout icon="file-lines">
  Entity limits may apply. To learn more, read [Entity Limit Policy](/docs/troubleshoot/customer-support/operational-policies/entity-limit-policy). If you have an Enterprise subscription, you will not be constrained due to entity limits, but you may be constrained by a connection that already has thousands of enabled clients.
</Callout>

You can represent each of your tenants with a separate Auth0 application.

This approach allows you to uniquely configure each Auth0 application based on varying tenant requirements, such as available connections.

You'll need to track the tenants to which your users belong within your application. When a logs into your application, you'll need to read that information, and direct the user to the appropriate Auth0 application to complete authentication.

To enable a connection for multiple applications with the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>, call the [Update enabled clients for a connection endpoint](https://auth0.com/docs/api/management/v2/connections/patch-clients), and pass the relevant connection ID.

### Use Auth0 tenants

You can represent each of your tenants with a separate Auth0 tenant.

This approach allows you to share access to the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> with users, restricted by tenant, but requires you to configure Auth0 individually for each tenant.

This means that, in addition to managing the features of each Auth0 tenant individually (such as Branding, Actions, and <Tooltip href="/docs/glossary?term=Attack+Protection">Attack Protection</Tooltip>), your application will have to support multiple Auth0 configurations.

### Store tenant details in the user's profile

You can store tenant details in the user's profile and have your application read that information after the user logs in.

This approach allows all of your users, regardless of which tenant to which they belong to, to log in using in a uniform configuration (such as available connections).

To implement this, you could store tenant details in the user's Auth0 profile in the `app_metadata` object, using an identifier of your choice (for example, `"tenant": "customer-group-12345"`). After the user logs in, your application retrieves the `tenant` variable, and then displays a version appropriate to the returned value.


# Set Up Multiple Environments
Source: https://auth0.com/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments

Describes how to use multiple Auth0 tenants to manage various environments.

Development, staging, and production environments are easy to set up in Auth0. Simply create a new tenant for each environment to guarantee isolation between them. You can easily switch between tenants using the tenant chooser from the top left menu on the Dashboard. You can also configure different administrators for each.

Production [rate limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy) only apply to tenants tagged as `Production`. Ensure your tenant's environment tag is set to `Production` before going live, and note the differences between rate limits for different tenants, environments, and fee structures.

You can name your multiple environments any way you prefer. For production environments, we strongly recommend using [custom domains](/docs/customize/custom-domains).

If you have an Enterprise subscription plan, you can create child tenants by [linking multiple tenants to a single subscription](/docs/get-started/auth0-overview/create-tenants/child-tenants); child tenants each gain access to the paid or upgraded features associated with the subscription. You can ensure your development, staging, or testing environments have access to the same features as your production environment by linking them all to the same Enterprise subscription.

## Tag the environment

For each new tenant created, you should specify its environment. You can assign Environment Tags to your tenants to differentiate between development, staging, and production environments.

If your tenant is mixed use, choose the higher environment. For example, a tenant used for both development and production should be set to **Production**.

1. To assign an Environment Tag to a tenant, go to the [Dashboard > Settings > General](https://manage.auth0.com/#/tenant/general).

   <Frame>
     <img alt="Dashboard Tenant Settings General Settings tab" />
   </Frame>
2. Under **Assign Environment Tag**, identify your tenant's environment as **Development**, **Staging**, or **Production**.

   <Frame>
     <img alt="undefined" />
   </Frame>
3. After selecting the environment, click **Save**.

## Migration

Through the [Management API v2](https://auth0.com/docs/api/management/v2), you can automate the migration of assets ([rules](/docs/customize/rules), database [connections](/docs/authenticate/identity-providers), and so forth) between tenants.

For easier configuration management, save your configuration values in the [Dashboard](https://manage.auth0.com/#/rules), instead of hardcoding them into your **rules** or **db connections** scripts.

For example, let's say you want to set a URL for logs. One way to do it is to hardcode it in the rule:

```javascript lines theme={null}
function(user, context, callback){
      var log_url = 'https://someurl/log';
      ...
    }
```

This code, however, is not portable since this URL will likely change from development to production.

The recommended way of working with code that you need to use/move from development to product is via [Rules](https://manage.auth0.com/#/rules) section. If you have not yet created a rule, you'll need to do so. (Otherwise, jump to step 4.)

1. Click **Create Your First Rule**.

2. Choose the **empty rule** template.

3. Enter a name for your new rule, and click **Save**.

4. Go to [Dashboard > Rules](https://manage.auth0.com/#/rules), and scroll to the bottom of the page to set your configuration values (we will use `log_url` for the key name, and `https://someurl/log` for value), then click **Create**.

5. Now, you can write your rule. Edit the rule you created, enter the following code in the code area, and click **Save**.

   ```javascript lines theme={null}
   function(user, context, callback){
         var log_url = configuration.log_url;
         ...
       }
   ```

This code is portable, and when you migrate to production, you only need to change this setting instead of searching your scripts.

## AD/LDAP Connectors

If you use multiple Auth0 tenants with AD/LDAP, you will need to create an AD/LDAP Connection and set up an AD/LDAP Connector for each tenant. This is because each AD/LDAP Connector is tied to a specific Connection within an Auth0 tenant.

Multiple AD/LDAP Connectors can point to the same AD or LDAP directory, but each AD/LDAP Connector can only be used by one Connection within one Auth0 tenant.

If you have multiple AD/LDAP directories against which users will authenticate (for example, to support different departments or customers, each with their own directory), you can set up multiple AD/LDAP Connectors within each Auth0 tenant.

## Learn more

* [Create Multiple Tenants](/docs/get-started/auth0-overview/create-tenants/create-multiple-tenants)
* [Delete or Reset Tenants](/docs/troubleshoot/customer-support/manage-subscriptions/delete-or-reset-tenant)
* [Link Multiple Tenants to a Single Subscription](/docs/get-started/auth0-overview/create-tenants/child-tenants)


# Auth0 Dashboard
Source: https://auth0.com/docs/get-started/auth0-overview/dashboard

Describes the Auth0 Dashboard and all the features you can access to implement authentication and authorization with your applications and APIs..

The [Auth0 Dashboard](https://manage.auth0.com/#) is where you manage all aspects of your Auth0 subscription and configuration.

<Frame>
  <img alt="Auth0 Dashboard Activity page" />
</Frame>

It consists of several sections that you can navigate using the sidebar menu on your left.

<Callout icon="file-lines">
  For best practices around usage of the Teams Dashboard, [see General Usage and Operations Best Practices](/docs/troubleshoot/general-usage-and-operations-best-practices).
</Callout>

## Configure implementation

The following table contains a brief overview of the different Dashboard sections and what you can do in each.

<table>
  <thead>
    <tr>
      <th><strong>Section</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Applications</strong></td>
      <td>Manage your applications, APIs, and single sign-on (SSO) integrations.<br /><strong>Applications</strong>: For each of your apps for which you want to authenticate users with Auth0, register an application.<br /><strong>APIs</strong>: For each of your APIs that you want to secure with Auth0, register an API. Create new APIs and manage existing ones.<br /><strong>SSO Integrations</strong>: View and enable external services for SSO. Create new SSO integrations and configure, review, and manage integration settings.</td>
    </tr>

    <tr>
      <td><strong>Authentication</strong></td>
      <td>Manage the identity providers through which you allow users to authenticate to your apps.<br /><strong>Database</strong>: Securely store and manage identifier/password credentials either in an Auth0 datastore or in your own database. Connect to existing databases using template-based JavaScript scripts that run on Auth0's server during every authentication. Gradually migrate an existing database of legacy credentials to Auth0 as users authenticate (no password reset required).<br /> <strong>Social</strong>: Configure social identity providers (such as Facebook, X, and Github) through which your users can log in.<br /><strong>Enterprise</strong>: Configure enterprise identity providers (such as Active Directory, SAML, and Office 365) through which your users can log in using their enterprise credentials.<br /><strong>Passwordless</strong>: Allow your users to sign up and log in using one-time passcodes (delivered by email or SMS) or one-click links, instead of passwords.</td>
    </tr>

    <tr>
      <td><strong>Organizations</strong></td>
      <td>Manage the organizations you do business with, and customize the experience their users have when accessing your applications.</td>
    </tr>

    <tr>
      <td><strong>User Management</strong></td>
      <td>Manage your users' identities and permissions.<br /> <strong>Users</strong>: View and create user profiles, perform password resets, block and delete users, and more.<br /><strong>Roles</strong>: Create and manage roles for your apps. Roles contain collections of permissions and can be assigned to users.</td>
    </tr>

    <tr>
      <td><strong>Branding</strong></td>
      <td><strong>Universal Login</strong>: Create and customize a login page to which you can direct users to authenticate. <br /><strong>Custom Domains</strong>: Create a custom domain to maintain a consistent experience for your users.<br /><strong>Email Templates</strong>: Use templates to create welcome, password reset, and account verification email-based workflows. <br /><strong>Email Provider</strong>: Designate and configure your custom email provider information.</td>
    </tr>

    <tr>
      <td><strong>Security</strong></td>
      <td>Configure extra layers of security by enabling shields that protect your users against different types of attacks and user access anomalies. <br /><strong>Attack Protection</strong>: Manage settings for bot, IP throttling, brute-force, and breached password attacks. <br /><strong>Multi-factor Auth</strong>: Require additional factors during the login process to prevent unauthorized access. <br /><strong>Monitoring</strong>: Monitor threat intelligence events with one of our data visualization and alerting integrations.</td>
    </tr>

    <tr>
      <td><strong>Actions</strong></td>
      <td>Configure flows such as login, machine-to-machine, user registration, and password resets. Create and manage customized actions used in flows.</td>
    </tr>

    <tr>
      <td><strong>Auth Pipeline</strong></td>
      <td><strong>Rules</strong>: Configure custom JavaScript snippets that are executed in Auth0 as part of each user authentication transaction. You can call external APIs, filter which users can log in to your application, use an AllowList, configure geolocated access, and so on. <br /><strong>Hooks</strong>: Customize the behavior of Auth0 when you use Database Connections by configuring Node.js code that is executed against extensibility points (which are comparable to webhooks that come with a server).</td>
    </tr>

    <tr>
      <td><strong>Monitoring</strong></td>
      <td><strong>Logs</strong>: 	View log data of actions taken in the dashboard by administrators and user logins. <br /><strong>Streams</strong>: Create and manage log event streaming to external data analysis services.</td>
    </tr>

    <tr>
      <td><strong>Marketplace</strong></td>
      <td>Explore integrations that help your business do more with Auth0.</td>
    </tr>

    <tr>
      <td><strong>Extensions</strong></td>
      <td>Extend the Auth0 platform with official and third-party add-ons.</td>
    </tr>

    <tr>
      <td><strong>Settings</strong></td>
      <td>Configure your tenants, manage your Auth0 subscription and payment options, control your tenant administrators and other user roles. Manage other tenant settings related to your custom domains, signing keys, and other advanced settings.</td>
    </tr>

    <tr>
      <td><strong>Get Support</strong></td>
      <td>Go to our <a href="https://support.auth0.com">Support Center</a>. If your plan does not have access to support services, see the <a href="https://community.auth0.com/">Auth0 Community</a>.</td>
    </tr>
  </tbody>
</table>

## Manage account settings

On the top left, you can see your tenant's name and icon, and a little arrow. This arrow displays a dropdown menu that you can use to configure different aspects of your account:

* [**Settings**](/docs/get-started/tenant-settings): Configure several aspects of your tenant.
* [**Invite a member**](/docs/get-started/manage-dashboard-access): Add an additional user as an administrator or other role to your tenant configuration.
* [**Quota Utilization**](https://support.auth0.com/reports/quota): See quota utilization information about your subscription and tenants.
* [**Create tenant**](/docs/get-started/auth0-overview/create-tenants): Use this to create a new tenant.
* **Switch tenant**: If you have [multiple tenants](/docs/get-started/auth0-overview/create-tenants/create-multiple-tenants), use this option to switch between them. If you create an application for one tenant, you will not see it listed for another tenant.

On the top right, you see several clickable options:

* **Search**: Look for apps, marketplace entries, users, and other content related to your tenant.
* **Discuss your needs:** Contact an Auth0 expert to help you reach your goals with Auth0.
* **Docs:** A link to the documentation site you’re reading right now.
* **Notifications bell:** Informs you of new communication from Auth0 or your tenant settings.
* **Profile:** A link to your local tenant profile, as well as options to [change your theme](/docs/get-started/dashboard-profile/light-and-dark-themes) and log out.

## Learn more

* [Create Tenants](/docs/get-started/auth0-overview/create-tenants)
* [Tenant Settings](/docs/get-started/tenant-settings)
* [Application Settings](/docs/get-started/applications/application-settings)
* [Create Users](/docs/manage-users/user-accounts/create-users)
* [API Settings](/docs/get-started/apis/api-settings)
* [Logs](/docs/deploy-monitor/logs)


# About the Activity Page
Source: https://auth0.com/docs/get-started/auth0-overview/dashboard/activity

Learn about the metrics on the Activity page for your Auth0 tenant, including information on active users, failed logins, and more.

The Activity page provides a summary of key data about your Auth0 tenant, including information on active users, failed logins, and more.

## Things to know

* Viewing a tenant's Activity page requires an account with an administrator role (such as Administrator or Owner).
* The **Support Access** role has read-only access to view metrics on the tenant's Activity page but cannot modify settings.
* To ensure data is consistent, the current date cannot be selected in the date picker and data may take up to 24 hours to display.

## Metrics

Here’s what you will see on your tenant's Activity page.

### Totals

At the top of the page, you'll see your tenant's total number of users, applications, APIs, and connections.

<Frame>
  <img alt="Example Dashboard Activity page tenant totals" />
</Frame>

### Daily active users

The number of daily unique users with successful authentication (successful login) or authorization activity (successful token exchange). This is calculated based on successful log events for each user. You can see the number of unique users for each day by hovering your mouse over a point in the graph.

<Frame>
  <img alt="Example Dashboard Activity page Active Users line graph" />
</Frame>

### User retention

The percentage of users that were active during the given time frame, calculated from the number of active users out of the total number of users on the tenant.

<Frame>
  <img alt="Example Dashboard Activity page User Retention line graph" />
</Frame>

### Signups

The number of successful user signups, which includes new user registrations through any configured connection (database, social, enterprise).

<Frame>
  <img alt="Example Dashboard Activity page Sign ups line graph" />
</Frame>

### Failed logins

The number of failed user logins (the `f` [log event type](/docs/deploy-monitor/logs/log-event-type-codes)) over the given time period.

<Frame>
  <img alt="Example Dashboard Activity page Failed Logins line graph" />
</Frame>

## Compare to last period

When **Compare to last period** is enabled:

* The percentage difference is included in the graph. Increases are colored green while decreases are colored red.
* Dotted lines are the last time period and solid lines are the current time period.

<Frame>
  <img alt="Example of mouse hovering over the Dashboard Activity page Active Users line graph" />
</Frame>

## View data by time frame

You can view data for a given time frame by using the datepicker next to the **Compare to last period** checkbox. There are built-in date ranges for the last 7/14/30/60 days, or you can provide the **From** and **To** dates for a custom range.

<Frame>
  <img alt="Example of Dashboard Activity page datepicker form" />
</Frame>


# Register APIs
Source: https://auth0.com/docs/get-started/auth0-overview/set-up-apis

Learn how to register APIs in the Auth0 Dashboard.

<Callout icon="file-lines">
  Before you register any APIs in the Auth0 Dashboard, one API will already exist: the **Auth0 Management API**. To learn more about the features of the Management API and its available endpoints, see [Management API](https://auth0.com/docs/api/management/v2).
</Callout>

1. Go to [Dashboard > Applications > APIs](https://manage.auth0.com/#/apis), and select **+ Create API**.
2. Provide the following information for your API, and click **Create**:

   <table>
     <thead>
       <tr>
         <th><strong>Field</strong></th>
         <th><strong>Description</strong></th>
         <th><strong>Example</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td><strong>Name</strong></td>
         <td>A friendly name for the API. Does not affect any functionality.</td>
         <td><code>yourDomain</code></td>
       </tr>

       <tr>
         <td><strong>Identifier</strong></td>
         <td>A unique identifier for the API. Auth0 recommends using a URL. Auth0 does differentiate between URLs that include the last forward slash. For example, `https://example.com` and `https://example.com/` are two different identifiers. The URL does not have to be a publicly available URL. Auth0 will not call your API. This value cannot be modified afterwards.</td>
         <td>`https://{yourDomain}`</td>
       </tr>

       <tr>
         <td><strong>JSON Web Token (JWT) Profile</strong></td>
         <td>The profile determines the format of the access tokens issued for the API. The available values are <code>Auth0</code> and <code>RFC 9068</code>. To learn more, read <a href="/docs/secure/tokens/access-tokens/access-token-profiles">Access Token Profiles</a>.</td>
         <td><code>Auth0</code></td>
       </tr>

       <tr>
         <td><strong>JSON Web Token (JWT) Signing Algorithm</strong></td>
         <td>The algorithm to sign the access tokens with. The available values are <code>HS256</code>, <code>PS256</code>, <code>RS256</code>. If you select <code>RS256</code>, the token will be signed with the tenant's private key.</td>
         <td><code>RS256</code></td>
       </tr>

       <tr>
         <td><strong>Access Policy for Applications within user flow</strong></td>
         <td>Allow applications to access the API on the user’s behalf. To learn more read, [API Access Policies for Applications](/docs/get-started/apis/api-access-policies-for-applications).</td>
         <td><code>Allow via client-grant</code></td>
       </tr>

       <tr>
         <td><strong>Access Policy for Applications within client flows</strong></td>
         <td>Allow Machine to  Machine applications to access the API.  To learn more read, [API Access Policies for Applications](/docs/get-started/apis/api-access-policies-for-applications).</td>
         <td><code>Allow via client-grant</code></td>
       </tr>
     </tbody>
   </table>
3. Make the implementation changes to your API that are described in the QuickStart. These changes consist of choosing a JWT library from a predefined list and configuring this library to validate the access tokens in your API.

   <Frame>
     <img alt="Dashboard - Applications - APIs - Quickstart" />
   </Frame>

   <Warning>
     If you are creating a new custom API and also have Single-Page or Native applications in your tenant, you must enable Role-based Access Control (RBAC) to keep users logged in to these applications from generating an access token for your API that does not consider scopes. To learn how to enable RBAC for your API, read [Enable Role-Based Access Control for APIs](/docs/get-started/apis/enable-role-based-access-control-for-apis).
   </Warning>

The other available Dashboard views for your API are:

* **Settings**: Lists the settings for your API. Some are editable. Here you can change the token expiration time and enable offline access (this way Auth0 will allow your applications to ask for <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip> for this API).
* **Scopes**: Define the scopes for this API by setting a name and a description.
* **Machine to Machine Applications**: Lists all applications for which the **Client Credentials** grant is enabled. By default, this grant is enabled for regular web applications and machine-to-machine applications. You can authorize any of these applications to request <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> for your API. Optionally, you can select a subset of the defined scopes to limit your authorized application's access.
* **Test**: Execute a sample client credentials flow with any of your authorized applications to check that everything is working as expected.

## Learn more

* [API Settings](/docs/get-started/apis/api-settings)
* [Token Best Practices](/docs/secure/tokens/token-best-practices)
* [Which OAuth 2.0 Flow Should I Use?](/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use)


# Auth0 Teams
Source: https://auth0.com/docs/get-started/auth0-teams

Describes how Auth0 Teams allows you to manage tenants and tenant administrators.

Auth0 Teams provides a single point of visibility and control over your Auth0 resources by providing centralized governance, compliance, and secure collaboration at scale. Teams membership sits on top of the tenant membership account.

The main team member role is referred to as the Team Owner and has visibility into all tenants within their Auth0 Account. As an Auth0 Team Owner, you can manage a single tenant or multiple tenants.

The following features are currently available as part of Auth0 Teams:

* Visibility and control of Teams members
* Visibility into Tenants with relevant details
* Visibility and control of Tenant members
* Ability to enforce <Tooltip href="/docs/glossary?term=Single+Sign-On">Single Sign-On</Tooltip> with your own <Tooltip href="/docs/glossary?term=Identity+provider">Identity provider</Tooltip>
* Ability to restrict tenant creation
* Ability to manage subscription and billing details for self-service subscriptions

<Frame>
  <img alt="Auth0 teams let you manage all tenants and administrators" />
</Frame>

Auth0 Teams currently supports a single Teams instance for all tenants attached to either your subscription or Enterprise contract.

Team Owners manage and configure the tenants and tenant administrators within the Teams instance.

## Getting Started

Auth0 Teams is on by default for new self-service users since 1 November 2023.

Existing Public and Private Cloud Enterprise customers can request to be onboarded into Teams through their Technical Account Manager, Sales Executive, or via support.

For all other subscription types, if you joined Auth0 prior to 1 November 2023, you need to upgrade your plan to the latest version in your tenant's [subscription settings](https://manage.auth0.com/#/tenant/billing/subscription) to have Teams automatically provisioned for you.

## Feature Support Matrix

Features marked with an asterisk are currently in beta for Private Cloud customers.

<table>
  <thead>
    <tr>
      <th>Teams Feature</th>
      <th>Enterprise Private Cloud</th>
      <th>Enterprise Public Cloud</th>
      <th>Self-Service Subscription</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Tenant Management</td>
      <td>✅</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>Tenant Member Management</td>
      <td>✅ \*</td>
      <td>✅</td>
      <td>✅</td>
    </tr>

    <tr>
      <td>SSO Enforcement</td>
      <td>✅ \*</td>
      <td>✅</td>
      <td>❌</td>
    </tr>

    <tr>
      <td>Tenant Creation from Teams</td>
      <td>✅</td>
      <td>❌</td>
      <td>✅</td>
    </tr>
  </tbody>
</table>


# Configure Security Policies
Source: https://auth0.com/docs/get-started/auth0-teams/configure-security-policies

Configure the security policies associated with an Auth0 Team.

<Warning>
  This feature is offered as Early Access to Public Cloud Enterprise tenants and as a Beta release to Private Cloud Enterprise tenants. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0’s release stages, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

Security policies allow [team owners](/docs/get-started/auth0-teams/team-member-management) to configure and implement authentication rules that adhere to your organization's IT security policies for access to infrastructure systems or applications.

## Available Enterprise IdP Connections

Auth0 Teams allows you to connect to your <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> (IdP) to provide single-sign on (<Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip>) for team members.

### Add SSO connection (Beta)

You can configure an SSO connection in the Auth0 Teams Dashboard.

<Callout icon="file-lines">
  Before you add an SSO connection, you need to collect the following information:

  * Your IdP provider (for example: Okta, ADFS, or Google Workspace)
  * Your IdP domain
  * Auth0 Callback URL (`https://auth0.auth0.com/login/callback`)
  * Your Client ID, Client Secret, Sign-in URL, and Signing Certificate (depending on your IdP)
</Callout>

1. Go to [**Security**](https://accounts.auth0.com/teams/#/security-policies).
2. Select + **Add Connection (Beta)**, and then select **Get Started**.
3. Choose an identity provider, and then select **Next**.
4. Follow the instructions to create an application, and then select **Next**.
5. Configure your connection, then select **Create Connection**.
6. Read the prompt, then select **Proceed**.
7. Follow the instructions to grant users and groups access, and then select **Next**.
8. Select **Test Connection** to verify that your connection is configured properly.
9. When ready, select **Enable Connection**.

After you enable your connection, it appears in the **Available Enterprise IdP Connections** section of the **Security Policies** page.

### Configure just-in-time (JIT) provisioning

JIT provisioning enables Auth0 to automatically create an account for team members who log in through an SSO connection.

<Callout icon="file-lines">
  You must enable [Tenant Member Management](/docs/get-started/auth0-teams/tenant-member-management) to configure JIT provisioning.
</Callout>

1. Go to [Security](https://accounts.auth0.com/teams/#/security-policies).
2. Locate the **Available Enterprise IdP Connections** section.
3. Enable the **JIT Membership** toggle for the connection.

## Enforce Single Sign On

Auth0 Teams allows you to require team members to log in through one of your **Available Enterprise IdP Connections**.

<Callout icon="file-lines">
  To enforce SSO, you must be logged in through an SSO connection and have the **Team Owner** role.

  If you are not logged in through an SSO connection, but you have one configured, you can [invite yourself to your Auth0 Team](/docs/get-started/auth0-teams/team-member-management) on that connection.
</Callout>

### Use JIT provisioning

This method allows team members to log in to the SSO connection immediately after it's enabled, and instructs Auth0 to automatically create an account for them after the first time they log in successfully.

1. Enable [Tenant Member Management](/docs/get-started/auth0-teams/tenant-member-management).
2. Enable the **JIT Membership** toggle for the SSO connection.
3. Go to the Teams Dashboard’s Settings page and note your team's permalink value.
4. Instruct all team members to log out of the Auth0 Teams Dashboard and log in via the SSO connection. The URL structure for the team members to follow is `https://accounts.auth0.com/teams/{team-permalink}`.
5. Auth0 automatically creates a new account (on the SSO connection) for each team member.
6. Assign each team member's new account the same [team role](/docs/get-started/auth0-teams/team-member-management) as their old account.
7. (Optional) Delete each team member's old account.

### Manage team and tenant membership manually

This method allows you to manage team members separately from tenant members.

For team members, [send a new invitation from the Teams Dashboard](/docs/get-started/auth0-teams/team-member-management) and instruct them to accept the invitation using the SSO connection.

For tenant members, [send a new invitation from the Auth0 Dashboard](/docs/get-started/manage-dashboard-access/add-dashboard-users) from each tenant they're a member of and instruct them to accept the invitation using the SSO connection.

After accepting the invitation, Private Cloud Enterprise customers that enforce SSO and/or use Tenant Member Management can click the **Continue with Auth0 Teams** login button in their Private Cloud <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

### Configure home-realm discovery (HRD)

If you enable HRD, Auth0 recognizes the domain of the email address a team member enters and directs them to the associated SSO connection.

<Warning>
  Before you enable HRD, make sure your team members are prepared!

  If you're using Team Member Management and JIT provisioning, notify your team members of the new behavior.

  If you're managing team membership manually, ensure all team members have an account on the associated SSO connection and they know how to log in.
</Warning>

1. [Open a ticket](https://support.auth0.com) with Auth0 Support.
2. Let them know you'd like to enable HRD for an Auth0 Teams SSO connection, and provide the following information:

   * Your **Team Name** and **Team Permalink**
   * The name of the SSO connection
   * The domain associated with the SSO connection


# About the Quarterly Snapshot
Source: https://auth0.com/docs/get-started/auth0-teams/quarterly-snapshot

Learn about the Quarterly Snapshot report available to Auth0 Teams members, including how to access it and how to interpret the provided metrics.

The Quarterly Snapshot provides highlights of usage and value at an account level, including aggregated information on how you’re measuring against quota, your identity environment, and threat detection.

The feature is automatically enabled when Auth0 Teams is provisioned. It is exclusively available for select enterprise customers managed by the Digital Technical Account Manager (DTAM).

## Things to know

* The Quarterly Snapshot is accessible only through [Auth0 Teams](/docs/get-started/auth0-teams). Auth0 Teams should be provisioned for the account prior to the calendar quarter start.
* The Quarterly Snapshot is a feature accessible to a select group of Enterprise customers managed by the DTAM.
* Team Owners and Report Viewers can view and download the Quarterly Snapshot in the **Reports** section of the Auth0 Teams dashboard.
* Team Owners can manage the list of Report Viewers through the Auth0 Teams dashboard.
* Metric objects in the Quarterly Snapshots may vary as a result of an accounts entitlements, enabled features, and usage.
* All metrics are aggregated at an account level. For more information, refer to the **Metrics** table below.

## Metrics

Here are the metrics you may see on your Quarterly Snapshot.

<table>
  <thead>
    <tr>
      <th><strong>Metric</strong></th>
      <th><strong>What it measures</strong></th>
      <th><strong>Comments</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Monthly Active Users</td>
      <td>Measures the unique monthly active users on the account as compared to your quota.</td>
      <td>For detailed information on a tenant level, please reference the <a href="https://support.auth0.com/reports/quota">Support Center Quota</a> report.</td>
    </tr>

    <tr>
      <td>Machine to Machine Tokens</td>
      <td>Shows the number of access tokens issued by Auth0 for the <a href="/docs/get-started/authentication-and-authorization-flow/client-credentials-flow">client credentials grant</a>. Tokens issued for Auth0 Management API or other Auth0 built in APIs are not counted.</td>
      <td>For detailed information on a tenant level, please reference the <a href="https://support.auth0.com/reports/quota">Support Center Quota</a> report.</td>
    </tr>

    <tr>
      <td>Active Enterprise Connections</td>
      <td>This metric displays the number of  enterprise connections an account is using.</td>
      <td>For more details about your quota, contact your Account Executive.</td>
    </tr>

    <tr>
      <td>New User Signups</td>
      <td>This displays how many new users (user registrations) were added to your tenant(s)  in the months of this quarter.</td>
      <td>Refer to the <a href="/docs/get-started/auth0-overview/dashboard/activity">Activity Page</a> for more information on new users.</td>
    </tr>

    <tr>
      <td>Dormant Users</td>
      <td>This metric represents the monthly average users that haven’t authenticated in the last month.</td>

      <td />
    </tr>

    <tr>
      <td>Breached Password</td>
      <td>Number of attempts blocked with compromised credentials, as stopped by the <a href="/docs/secure/attack-protection/breached-password-detection">Breached password detection</a> feature.</td>
    </tr>

    <tr>
      <td>Brute-force Protection</td>
      <td>Requests blocked by the <a href="/docs/secure/attack-protection/brute-force-protection">Brute-force Protection</a> feature, if enabled. This metric summarizes all requests blocked specifically on production tenants.</td>
    </tr>

    <tr>
      <td>Suspicious IP Throttling</td>
      <td>Requests blocked by the <a href="/docs/secure/attack-protection/suspicious-ip-throttling">Suspicious IP Throttling</a> feature, if enabled. This metric sums all requests blocked specifically on production tenants.</td>
    </tr>

    <tr>
      <td>Bot Detection</td>
      <td>Requests failed to solve the CAPTCHA challenge. This metric sums all the bot requests that were blocked by the <a href="/docs/secure/attack-protection/bot-detection">Bot Detection</a> feature after failing to solve a CAPTCHA challenge.</td>
    </tr>

    <tr>
      <td>Adaptive MFA</td>
      <td>Requests where <a href="/docs/secure/multi-factor-authentication/adaptive-mfa">MFA</a> challenge was issued due to a low confidence score. This metric sums all login attempts where a multi-factor authentication challenge was issued and the calculated confidence score was low.</td>
    </tr>
  </tbody>
</table>


# Team Activity
Source: https://auth0.com/docs/get-started/auth0-teams/team-activity

Team Activity allows Team Owners to view and audit event logs generated by team member.

Team Activity allows Team Owners to view audit logs associated to member activities performed on their Auth0 account.

Team Activity report is located under the **Reports** section of the Teams Dashboard.

Team Activity provides a summary view of the member who generated the event, the event type, and the date the event was generated.

You can select **View Details** to find more information such as the description of the event, the event status, the IP address of the user who triggered the event, user agent details, and more.

## Event types

Team Activity event types are described below.

<table>
  <thead>
    <tr>
      <th><strong>Event Type</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Team Invitation</td>
      <td>Team member invitation created <br /> Team member invitation deleted</td>
    </tr>

    <tr>
      <td>Team Member</td>
      <td>Team member deleted <br /> Team member role updated</td>
    </tr>

    <tr>
      <td>Security Policy</td>
      <td>Security policy updated <br /> Social connections updated</td>
    </tr>

    <tr>
      <td>Team Setting</td>
      <td>Team settings updated</td>
    </tr>
  </tbody>
</table>

<Callout icon="file-lines">
  Support for dashboard user authentication to Auth0 and Teams Dashboard and other events will be available in the future.
</Callout>

## Event schema

Team Activity event schema is described below.

```json lines theme={null}
{  
    "id": "string", 
    "team_id": "string",
    "user_id": "string",
    "type": "string",
    "description": "string",
    "status": "string",
    "details": "object",
    "ip": "string",
    "hostname": "string",
    "user_agent": "string",
    "version": "string",
    "created_at": "date",
    "team_slug": "string",
    "user": "object"
}
```

<table>
  <thead>
    <tr>
      <th><strong>Name</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>id</code></td>
      <td>string</td>
      <td>Event log unique identification.</td>
    </tr>

    <tr>
      <td><code>team\_id</code></td>
      <td>string</td>
      <td>Unique team identification.</td>
    </tr>

    <tr>
      <td><code>user\_id</code></td>
      <td>string</td>
      <td>The unique identifier for the user that generated the event.</td>
    </tr>

    <tr>
      <td><code>type</code></td>
      <td>string</td>
      <td>Event type.</td>
    </tr>

    <tr>
      <td><code>description</code></td>
      <td>string</td>
      <td>Event type summary.</td>
    </tr>

    <tr>
      <td><code>status</code></td>
      <td>string</td>
      <td>Event status. Possible values are <code>Success</code> or <code>Failure</code>.</td>
    </tr>

    <tr>
      <td><code>details</code></td>
      <td>object</td>
      <td>Details of the logged event.</td>
    </tr>

    <tr>
      <td><code>ip</code></td>
      <td>string</td>
      <td>IP address of the user that generated the event log.</td>
    </tr>

    <tr>
      <td><code>hostname</code></td>
      <td>string</td>
      <td>FQDN of the Auth0 App on which the event was performed.</td>
    </tr>

    <tr>
      <td><code>user\_agent</code></td>
      <td>string</td>
      <td>Web browser and Device OS type and version.</td>
    </tr>

    <tr>
      <td><code>version</code></td>
      <td>string</td>
      <td>Schema version under which the activity log was generated.</td>
    </tr>

    <tr>
      <td><code>created\_at</code></td>
      <td>datetime</td>
      <td>Date and time event log was generated.</td>
    </tr>

    <tr>
      <td><code>team\_slug</code></td>
      <td>string</td>
      <td>Unique text team identifier.</td>
    </tr>

    <tr>
      <td><code>user</code></td>
      <td>object</td>
      <td>Contains name, avatar URL, and Team membership status (boolean).</td>
    </tr>
  </tbody>
</table>

## Audit log retention

The retention of Team Activity audit logs varies by plan. Read our [Pricing](https://auth0.com/pricing) page for more information.


# Team Member Management
Source: https://auth0.com/docs/get-started/auth0-teams/team-member-management

Manage and configure members of your team.

Team Owners can manage and configure Auth0 Teams. Auth0 creates at least one Owner when we provision Teams. We recommend at least two Team Owners, especially if you limit tenant creation to Team Owners.

<Warning>
  **Self-Service Customers**

  When Auth0 provisions a Team, we may automatically assign the **Team Owner** role to the administrator user account . However, this user must manually assign themselves the **Team Owner** role in order to verify their email and receive full account permissions. This user can then invite additional members as needed.
</Warning>

As a Team Owner, you can add, change, and remove team members. The supported roles apart from a Team Owner are Report Viewer and Contributor.

## Team membership roles

### Team Owner

Members with this role have full access to the team dashboard (list of all tenants, tenant creation restriction, team members management) and can access specific tenants of which they are a member.

### Report Viewer

Members with this role can view Quarterly Snapshots. The Report Viewer role is available to select enterprise customers that are managed by the Digital Technical Account Manager (DTAM).

### Contributor

Members with this role can view and access specific tenants of which they are a member.

## View and add team members

### Invite a new team member

1. On the left side of the Teams Dashboard, select **Members**.

   <Frame>
     <img alt="A view of Auth0 Team Members on the Teams Dashboard" />
   </Frame>
2. To invite a new Team Owner, select **Invite a Member**.
3. Enter the email address of the member to invite and select the access level.

   <Frame>
     <img alt="Team member management screenshot" />
   </Frame>
4. Select **Send Invite**.

### Update existing team member role

1. To update the role of an existing Team Member, search for the member in the **Members** list.
2. Select the three-dot menu option and click on the **Assign Role** option.
3. Pick the new role you want to assign the Team Member and click **Assign**.

### Delete an existing team member

If a team member no longer requires access to the team, they can simultaneously be removed from the Teams Dashboard and all team tenants in which they are a user.

<Callout icon="file-lines">
  This feature requires tenant member management. Public Cloud Enterprise customers must activate this feature manually on the Teams settings page.
</Callout>

To delete an existing Team Member:

1. Navigate to the **Members** section on the left side of the Teams Dashboard, then locate the team member.
2. Select the ellipsis to reveal more options and choose **Remove Member**.
3. After you confirm the removal, you will be presented with a toast notification confirming the successful deletion of the team member.

If you only want to remove the team member's access to one or more tenants, go to the [Team Member's details page](/docs/get-started/auth0-teams/tenant-member-management).

## Update team name

Teams allow you to update the Team name visible on the tenant picker for dashboard users. To update the Team name:

1. Select **Settings** on the left side of the Teams Dashboard.
2. Make the necessary changes to the **Team Name** captured within the **Team Information** section.
3. Select **Save**. This change now displays in the tenant picker.


# Tenant Management
Source: https://auth0.com/docs/get-started/auth0-teams/tenant-management

Manage the Auth0 teams information within a given tenant.

Access and modify Team information from within your tenant. If you don't yet have a tenant associated with your account, see [Create Tenants.](/docs/get-started/auth0-overview/create-tenants)

## Access the Teams Dashboard

If you are a Team Owner, you can use the Teams Dashboard to:

* Choose who can create new tenants: Team Owners or all tenant administrators.
* View all tenants created under your Auth0 subscription or custom agreement.
* View and invite Team Owners.

To access the Teams Dashboard from any of your tenants:

1. Select your tenant name from the tenant drop-down menu in the [Auth0 Dashboard](https://manage.auth0.com/dashboard).
2. Find your Teams name at the bottom of the menu and select **Go to team**.

<Frame>
  <img alt="Access the Auth0 Team Dashboard" />
</Frame>

To access the Teams Dashboard using a URL:

1. Navigate to `https://accounts.auth0.com/`
2. If your user account is a member of only one Team, enter your credentials to be taken to your Teams dashboard. If your user account is a member of one or more Teams, select the Team from the list of Teams your user account is associated with to login.

If the option for Teams access isn't visible, try the following:

<table>
  <thead>
    <tr>
      <th>Possible Cause</th>
      <th>Action</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>The current tenant isn’t in Teams.</td>
      <td>Try switching to a different tenant.</td>
    </tr>

    <tr>
      <td>You’re not a Teams owner.</td>
      <td>Ask a Teams owner to invite you to the team.</td>
    </tr>
  </tbody>
</table>

## View tenants

In the Teams Dashboard, you can view all tenants within your Auth0 custom agreement or subscription present in either the Public or Private Cloud Environment. For each tenant, you can review:

* Tenant name
* Region
* Creation date
* Environment (Development, Staging, or Production)
* Tenant administrators

1. Select **Tenants** on the left side of the Teams Dashboard.

   For Private Cloud Environments, select the **Overview** menu drop-down to reveal the **Tenants** menu option.
2. If you’re an administrator for a tenant, select the tenant name to access the tenant. If you are not a tenant administrator, you will not be able to select the tenant.
3. To review tenant members, select **View Members**.

## View private cloud environments

A list of private cloud environments can be viewed from the Teams Dashboard. You are able to view the following information

* Environment name
* Cloud provider type (AWS or Azure)
* Deployment region
* Failover region
* Current environment release version.

1. Select the **Overview** menu drop-down to reveal the **Private Cloud** menu option.

## Link tenants

<Callout icon="file-lines">
  This feature is currently available for the following Team Subscription types:

  * B2C - Essentials
  * B2B - Essentials
  * B2C - Professional
  * B2B - Professional
</Callout>

Linking tenants allows you to share features and quota limits available within your Team Subscription with the linked tenant. Once linked, that tenants subscriptions will be tied to your Team and you would no longer have to individually manage the subscription for that tenant.

You are able to link tenants to your team, if the following conditions are true:

* The tenant is not part of an existing Team.
* You are an administrator of the tenant you want to link.
* You have a Team Owner role on the team.

<Callout icon="file-lines">
  Linking a tenant cancels the subscription attached to the tenant.
</Callout>

If these conditions are met, the tenant will show up as a possible option to link to your team when you select **Link Existing Tenant** from the Tenants page.

## Create new tenant

<Warning>
  This feature is currently available for the following Team Subscription types:

  * B2C - Essentials
  * B2B - Essentials
  * B2C - Professional
  * B2B - Professional
  * Enterprise Private Cloud

  By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/).
</Warning>

Team Owners can create a tenant from within the Teams Dashboard, automatically linking the created tenant with the team, including associating the Team Subscription details (available features and quota limits) with the newly created tenant.

You can do this by clicking on the **Create New Tenant** button on the Tenants page, which will open the Create Tenant form.

## Manage tenants

You can control who can create new tenants under your Auth0 custom agreement or subscription under **Team Settings**. When creating a new tenant, administrators can:

* Link the tenant to custom agreement. The new tenant exists under your custom agreement or subscription. It benefits from the same features, counts toward limits, and is visible to Team Owners.
  or
* Create a tenant under their personal account. The new tenant is not a part of your Teams' custom agreement or subscription. The administrator who creates the tenant can access it with the same login credentials.

To allow administrators to link a tenant to a custom agreement, the Team Owner must:

1. Select **Settings** on the left side of the Teams Dashboard.
2. Select the option **Allow Tenant Admins to Create Tenants under the Teams Account**. If this option is unchecked, then tenant administrators can create personal accounts only.

   <Callout icon="file-lines">
     The **Tenant Creation** option does not apply to Team Owners. Owners have permissions to create new tenants in the Teams instance under the custom agreement or subscription.
   </Callout>
3. Select **Save**.

   <Warning>
     If a Tenant administrator without permission attempts to create tenants, they will be prompted to contact the Team Owner.
   </Warning>

   <Frame>
     <img alt="" />
   </Frame>

## View Team Subscription details

<Callout icon="file-lines">
  This feature is currently available for the following Team Subscription types:

  * B2C - Essentials
  * B2B - Essentials
  * B2C - Professional
  * B2B - Professional
</Callout>

Team Owners can view Team Subscription details by visiting Subscription tab within the Setting page.


# Tenant Member Management
Source: https://auth0.com/docs/get-started/auth0-teams/tenant-member-management

Describes how to use Auth0 Teams to centrally manage Tenant Membership.

Tenant Member Management allows Team Owners to manage tenant access and [roles](/docs/get-started/manage-dashboard-access/feature-access-by-role) for Team members directly in the Teams dashboard.

## Enable Tenant Member Management

<Callout icon="file-lines">
  Tenant Member Management is enabled by default for all Self-service customers and most Public Cloud Enterprise customers.
</Callout>

To enable Tenant Member Management in your Teams dashboard:

1. Go to **Settings**.
2. Locate the **Tenant Member Management** section.
3. Enable the **Manage tenant members** checkbox.
4. Select **Save**.

<Frame>
  <img alt="" />
</Frame>

After you enable Tenant Member Management, a background process replicates all current tenant members as Team members and grants them the **Contributor** role. If a user already has a Team member account, the role with greater privileges is maintained.

## Add tenant access for a Team member

To add tenant access for a Team member through the Teams dashboard:

1. Go to **Members**.
2. Select the Team member to open their **Member details** page.
3. Select **Add Tenant Access**.
4. Type the tenant name into the search window or select a tenant from the dropdown menu. You can select up to five tenants.

   <Callout icon="file-lines">
     Specific Apps option is not presented if more than one tenant is selected. Select individual Tenant to assign Editor -Specific Apps role.
   </Callout>
5. Select the desired role(s) you want to assign to the Team member for all selected tenants.
6. Select **Assign**.

## Edit tenant access for a Team member

To edit tenant access for a Team member through the Teams dashboard:

1. Go to **Members**.
2. Select the Team member to open their **Member details** page, or select **Manage Tenant Access** from the ellipsis menu (**...**) next to their name.
3. Locate the desired tenant and select **Edit Roles** from the ellipsis menu (**...**).
4. Select **Assign**.

<Callout icon="file-lines">
  If a Team member is currently logged in and you edit their role, Auth0 forcibly logs them out and terminates their session. This may result in loss of unsaved work.
</Callout>

## Remove tenant access for a Team member

To remove tenant access for a Team member through the Teams dashboard:

1. Go to **Members**.
2. Select the Team member to open their **Member details** page.
3. Locate the desired tenant and select **Remove Access** from the ellipsis menu (**...**).
4. Select **Assign**.

If you want to remove a Team member from all tenants associated with the Team, [remove them from the Team](/docs/get-started/auth0-teams/team-member-management).


# Troubleshoot Teams
Source: https://auth0.com/docs/get-started/auth0-teams/troubleshoot-teams

Troubleshoot any issues associated with an Auth0 Teams membership.

To ensure undisrupted service, see below to help troubleshoot any issues associated with an Auth0 Teams membership.

<Callout icon="file-lines">
  For best practices around usage of the Teams Dashboard, [see General Usage and Operations Best Practices](/docs/troubleshoot/general-usage-and-operations-best-practices).
</Callout>

#### Add a missing tenant

If you are on a self-service subscription plan and you don’t see a tenant under your Teams instance, verify the [subscription](/docs/troubleshoot/customer-support/manage-subscriptions) details:

1. First verify the [subscription](/docs/troubleshoot/customer-support/manage-subscriptions) details by checking the tenant's subscription.
2. Attempt to link the tenant by following the [Link tenants](/docs/get-started/auth0-teams/tenant-management) guide.

If the subscriptionis an Enterprise Agreementbut is not part of your Teams instance, contact [Auth0 Support](http://support.auth0.com) to assist in adding the tenant.

<Frame>
  <img alt="Screenshot of what to expect when your tenant subscription is an Enterprise Agreement" />
</Frame>

#### Remove an unrecognized admin

If a Tenant administrator is listed as part of a tenant and should not be:

1. If you are a Team Owner and also the tenant admin for the tenant, access the Auth0 Dashboard for the tenant to remove the admin. To learn more, read [Team Member Management](/docs/get-started/auth0-teams/team-member-management).
2. Request a tenant administrator to remove the admin from the tenant.


# Dashboard Profile
Source: https://auth0.com/docs/get-started/dashboard-profile

Explore options in Auth0 Dashboard's Profile menu.

Explore options in <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>'s profile option.

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/get-started/dashboard-profile/light-and-dark-themes">Light and Dark themes</a></td>
      <td>How to choose your preferred theme.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/dashboard-profile/auth0-dashboard-login-session-management">Auth0 Dashboard Login Session Management</a></td>
      <td>How to manage Auth0 Dashboard sessions.</td>
    </tr>
  </tbody>
</table>


# Auth0 Dashboard Login Session Management
Source: https://auth0.com/docs/get-started/dashboard-profile/auth0-dashboard-login-session-management

Describes how Auth0 Dashboard Admins can view and revoke login sessions.

With Login Sessions, <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> administrators can track active sessions from different Dashboard applications across multiple devices and browsers. You can review and revoke sessions created by users accessing the Teams Dashboard, Support Center, and Auth0 Dashboard respectively.

You can see a list of all active sessions within your Auth0 Dashboard [profile page](https://manage.auth0.com/#/profile/sessions).

<Frame>
  <img alt="Auth0 Dashboard > Profile" />
</Frame>

To log out or revoke a session, locate the session of interest and select **Revoke**.

<Callout icon="file-lines">
  Revoking a session does not automatically remove sessions belonging to extensions. However, sessions belonging to extensions are short-lived and do not renew when a login session is revoked or expires.
</Callout>


# Light and Dark themes
Source: https://auth0.com/docs/get-started/dashboard-profile/light-and-dark-themes

How to toggle between light and dark themes for your Dashboard

Auth0 customers can use light mode or dark mode in their tenant Dashboard. You can also set your Dashboard to use the same settings as your local system environment.

There are two ways to change your Dashboard theme:

1. Select the profile dropdown menu at the top-right of your Dashboard.
2. Use the menu to switch between themes.

<Frame>
  <img alt="Where to find the Dark mode and Light mode toggle" />
</Frame>

You may also click **Your Profile** in the same dropdown and scroll to the bottom, where you can choose from the three themes.

<Frame>
  <img alt="Where you can change your theme in the Profile section" />
</Frame>


# Identity Fundamentals
Source: https://auth0.com/docs/get-started/identity-fundamentals

Learn the basics of identity and access management.

Explore topics related to the fundamentals of identity and access management.

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/get-started/identity-fundamentals/identity-and-access-management">Introduction to Identity and Access Management (IAM)</a></td>
      <td>Basic concepts of IAM.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/identity-fundamentals/authentication-and-authorization">Authentication vs. Authorization</a></td>
      <td>About the differences between authentication and authorization.</td>
    </tr>

    <tr>
      <td><a href="/docs/glossary">Glossary</a></td>
      <td>Definitions of various terms related to identity.</td>
    </tr>
  </tbody>
</table>


# Authentication vs. Authorization
Source: https://auth0.com/docs/get-started/identity-fundamentals/authentication-and-authorization

Explore the differences between authentication and authorization.

While often used interchangeably, [authentication](/docs/authenticate) and authorization represent fundamentally different functions. In this article, we compare and contrast the two to show how they protect applications in complementary ways.

## What are authentication and authorization?

In simple terms, authentication is the process of verifying who a user is, while authorization is the process of verifying what they have access to.

Comparing these processes to a real-world example, when you go through security in an airport, you show your ID to authenticate your identity. Then, when you arrive at the gate, you present your boarding pass to the flight attendant, so they can authorize you to board your flight and allow access to the plane.

## Authentication vs. authorization

Here's a quick overview of the differences between authentication and authorization:

<table>
  <thead>
    <tr>
      <th><strong>Authentication</strong></th>
      <th><strong>Authorization</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Determines whether users are who they claim to be</td>
      <td>Determines what users can and cannot access</td>
    </tr>

    <tr>
      <td>Challenges the user to validate credentials (for example, through passwords, answers to security questions, or facial recognition)</td>
      <td>Verifies whether access is allowed through policies and rules</td>
    </tr>

    <tr>
      <td>Usually done before authorization</td>
      <td>Usually done after successful authentication</td>
    </tr>

    <tr>
      <td>Generally, transmits info through an ID Token</td>
      <td>Generally, transmits info through an <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip></td>
    </tr>

    <tr>
      <td>Generally governed by the <Tooltip href="/docs/glossary?term=OpenID+Connect+%28OIDC%29+protocol">OpenID Connect (OIDC) protocol</Tooltip></td>
      <td>Generally governed by the OAuth 2.0 framework</td>
    </tr>

    <tr>
      <td>Example: Employees in a company are required to authenticate through the network before accessing their company email</td>
      <td>Example: After an employee successfully authenticates, the system determines what information the employees are allowed to access</td>
    </tr>
  </tbody>
</table>

In short, access to a resource is protected by both authentication and authorization. If you can't prove your identity, you won't be allowed into a resource. And even if you can prove your identity, if you are not authorized for that resource, you will still be denied access.

Auth0 has products and services for authentication, like [passwordless](/docs/authenticate/passwordless/passwordless-with-universal-login), [multi-factor authentication](/docs/secure/multi-factor-authentication) (<Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip>), and [Single-Sign On (SSO)](/docs/authenticate/single-sign-on) you can configure using <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. For authorization, Auth0 offers [role-based access control](/docs/manage-users/access-control/rbac) (RBAC) or [fine grained authorization](https://docs.fga.dev/fga) <Tooltip href="/docs/glossary?term=FGA">FGA</Tooltip>).


# Introduction to Identity and Access Management (IAM)
Source: https://auth0.com/docs/get-started/identity-fundamentals/identity-and-access-management

Basic overview of the computer software field of identity and access management, written for those new to the space

## What is identity and access management (IAM)?

Identity and access management provides control over user validation and resource access. Commonly known as IAM, this technology ensures that theright people access the right digital resources at the right time and for the right reasons.

## IAM basic concepts

To understand IAM, you must be familiar with some fundamental concepts:

* A **digital resource** is any combination of applications and data in a computer system. Examples of digital resources include web applications, APIs, platforms, devices, or databases.
* The core of IAM is **identity**. Someone wants access to your resource. It could be a customer, employee, member, participant, and so on. In IAM, a **user** account is a <Tooltip href="/docs/glossary?term=digital+identity">digital identity</Tooltip>. User accounts can also represent non-humans, such as software, Internet of Things devices, or robotics.

<Frame>
  <img alt="Simple diagram showing user accessing resource" />
</Frame>

<Frame>
  <img alt="Simple diagram showing that the IAM system controls user access to a resource" />
</Frame>

* **Authentication** is the verification of a digital identity. Someone (or something) authenticates to prove that they’re the user they claim to be.
* **Authorization** is the process of determining what resources a user can access.

## The difference between authentication and authorization

It’s common to confuse authentication and authorization because they seem like a single experience to users. They are two separate processes: authentication proves a user’s identity, while authorization grants or denies the user’s access to certain resources.

You can think of authentication and authorization as the security system for an office building. Users are the people who want to enter the building. Resources that people want to access are areas in the building: floors, rooms, and so on.

**Authentication:** When you enter the building, you must show your photo ID badge to the security guard. The guard compares the photo on the badge to your face. If they match, the guard lets you through the door to try to access different areas of the building. The guard doesn’t tell you what rooms you can access; they only get proof that you are who you claim to be. This is authentication: confirming user identity.

<Frame>
  <img alt="Diagram showing how authentication is like a security guard checking your badge at the door" />
</Frame>

**Authorization:** In this scenario, imagine the elevators and doorways in the building have key sensors for access. The chip in your badge gives you access only to the first floor, which your company occupies. If you swipe your badge to enter any other floor, your access is denied. You can access your private office but not those belonging to your colleagues. You can enter the supply room but not the server room. This is authorization: granting and denying access to different resources based on identity.

<Frame>
  <img alt="Diagram showing how authorization is like a badge that gives you access to only some rooms in a building" />
</Frame>

To learn more about authentication and authorization, read [Authentication vs. Authorization](/docs/get-started/identity-fundamentals/authentication-and-authorization).

## What does IAM do?

Identity and access management gives you control over user validation and resource access:

* How users become a part of your system
* What user information to store
* How users can prove their identity
* When and how often users must prove their identity
* The experience of proving identity
* Who can and cannot access different resources

You integrate IAM with your application, API, device, data store, or other technology. This integration can be very simple. For example, your web application might rely entirely on Facebook for authentication, and have an all-or-nothing authorization policy. Your app performs a simple check: if a user isn’t currently logged in to Facebook in the current browser, you direct them to do so. Once authenticated, all users can access everything in your app.

It’s unlikely that such a simple IAM solution would meet the needs of your users, organization, industry, or compliance standards. In real life, IAM is complex. Most systems require some combination of these capabilities:

* **Seamless signup and login experiences:** Smooth and professional login and signup experiences occur within your app, with your brand’s look and language.
* **Multiple sources of user identities:** Users expect to be able to log in using a variety of social (such as Google or Linkedin), enterprise (such as Microsoft Active Directory), and other [identity providers](/docs/authenticate/identity-providers).
* **<Tooltip href="/docs/glossary?term=Multi-factor+authentication">Multi-factor authentication</Tooltip> (MFA):** In an age when passwords are often stolen, requiring additional proof of identity is the new standard. Fingerprint authentication and one-time passwords are examples of common authentication methods. To learn more, read [Multi-Factor Authentication (MFA)](/docs/secure/multi-factor-authentication).
* **Step-up authentication:** Access to advanced capabilities and sensitive information require stronger proof of identity than everyday tasks and data. Step-up authentication requires additional identity verification for selected areas and features. To learn more, read [Add Step-up Authentication](/docs/secure/multi-factor-authentication/step-up-authentication).
* **<Tooltip href="/docs/glossary?term=Attack+protection">Attack protection</Tooltip>:** Preventing bots and <Tooltip href="/docs/glossary?term=bad+actors">bad actors</Tooltip> from breaking into your system is fundamental to cybersecurity. To learn more, read [Attack Protection](/docs/secure/attack-protection).
* **Role-based access control (RBAC):** As the number of users grows, managing the access of each individual quickly becomes impractical. With RBAC, people who have the same role have the same access to resources. To learn more, read [Role-Based Access Control](/docs/manage-users/access-control/rbac).
* **<Tooltip href="/docs/glossary?term=Fine-grained+authorization">Fine-grained authorization</Tooltip> (FGA):** When you need more options to manage user access to your resources or technologies, you can use relationship-based access control to go beyond role-based. You can give individual users access to certain resources and determine the best solution for your specific use case. To learn more, read [What Is Fine-Grained Authorization?](https://docs.fga.dev/authorization-concepts#what-is-fine-grained-authorization)

Facing this level of complexity, many developers rely on an IAM platform like Auth0 instead of building their own solutions.

## How does IAM work?

“Identity and access management” is not one clearly defined system. IAM is a discipline and a type of framework for solving the challenge of secure access to digital resources.  There’s no limit to the different approaches for implementing an IAM system. This section explores elements and practices in common implementations.

### Identity providers

In the past, the standard for identity and access management was for a system to create and manage its own identity information for its users. Each time a user wanted to use a new web application, they filled in a form to create an account. The application stored all of their information, including login credentials, and performed its own authentication whenever a user signed in.

As the internet grew and more and more applications became available, most people amassed countless user accounts, each with its own account name and password to remember. There are many applications that continue to work this way. But many others now rely on <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> to reduce their development and maintenance burden and their users’ effort.

An identity provider creates, maintains, and manages identity information, and can provide authentication services to other applications. For example, Google Accounts is an identity provider. They store account information such as your user name, full name, job title, and email address. Slate online magazine lets you log in with Google (or another identity provider) rather than go through the steps of entering and storing your information anew.

<Frame>
  <img alt="Screenshot of Slate magazine login" />
</Frame>

Identity providers don’t share your authentication credentials with the apps that rely on them. Slate, for example, doesn’t ever see your Google password. Google only lets Slate know that you’ve proven your identity.

Other identity providers include social media (such as Facebook or LinkedIn), enterprise (such as Microsoft Active Directory), and legal identity providers (such as Swedish BankID).

### Authentication factors

Authentication factors are methods for proving a user’s identity. They commonly fall into these basic types:

<table>
  <thead>
    <tr>
      <th>Factor type</th>
      <th>Examples</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Knowledge (something you know)</td>
      <td>Pin, password</td>
    </tr>

    <tr>
      <td>Possession (something you have)</td>
      <td>Mobile phone, encryption key device</td>
    </tr>

    <tr>
      <td>Inherence (something you are)</td>
      <td>Fingerprint, facial recognition, iris scan</td>
    </tr>
  </tbody>
</table>

IAM systems require one or many authentication factors to verify identity.

### Authentication and authorization standards

Authentication and authorization standards are open specifications and protocols that provide guidance on how to:

* Design IAM systems to manage identity
* Move personal data securely
* Decide who can access resources

These IAM industry standards are considered the most secure, reliable, and practical to implement:

#### OAuth 2.0

<Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> is a delegation protocol for accessing APIs and is the industry-standard protocol for IAM. An open authorization protocol, OAuth 2.0 lets an app access resources hosted by other web apps on behalf of a user without ever sharing the user’s credentials. It’s the standard that allows third-party developers to rely on large social platforms like Facebook, Google, and Twitter for login. To learn more, read [OAuth 2.0 Authorization Framework](/docs/authenticate/protocols/oauth).

#### Open ID Connect

A simple identity layer that sits on top of OAuth 2.0, <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) makes it easy to verify a user’s identity and obtain basic profile information from the identity provider. OIDC is another open standard protocol. To learn more, read [OpenID Connect Protocol](/docs/authenticate/protocols/openid-connect-protocol).

#### JSON web tokens

<Tooltip href="/docs/glossary?term=JSON+web+tokens">JSON web tokens</Tooltip> (JWTs) are an open standard that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. JWTs can be verified and trusted because they’re digitally signed. They can be used to pass the identity of authenticated users between the identity provider and the service requesting the authentication. They also can be authenticated and encrypted. To learn more, read [JSON Web Tokens](/docs/secure/tokens/json-web-tokens).

#### Security Assertion Markup Language (SAML)

<Tooltip href="/docs/glossary?term=Security+Assertion+Markup+Language">Security Assertion Markup Language</Tooltip> (SAML) is an open-standard, XML-based data format that lets businesses communicate user authentication and authorization information to partner companies and enterprise applications that their employees use. To learn more, read [SAML](/docs/authenticate/protocols/saml).

#### Web Services Federation (WS-Fed)

Developed by Microsoft and used extensively in their applications, this standard defines the way <Tooltip href="/docs/glossary?term=security+tokens">security tokens</Tooltip> can be transported between different entities to exchange identity and authorization information. To learn more, read [Web Services Federation Protocol](/docs/authenticate/protocols/ws-fed-protocol).

## Why use an IAM platform?

Why do so many developers choose to build on an identity and access management platform instead of building their own solution from the ground up?

User expectations, customer requirements, and compliance standards introduce significant technical challenges. With multiple user sources, authentication factors, and open industry standards, the amount of knowledge and work required to build a typical IAM system can be enormous. A strong IAM platform has built-in support for all identity providers and authentication factors, offers APIs for easy integration with your software, and relies on the most secure industry standards for authentication and authorization.

For those who haven’t yet decided whether to build or buy an IAM solution, [Build vs. Buy: Guide to Evaluating Identity Management](https://auth0.com/resources/whitepapers/build-vs-buy-evaluating-identity-management) is a useful resource.


# Introduction to Auth0
Source: https://auth0.com/docs/get-started/identity-fundamentals/introduction-to-auth0

Describes Auth0 services and features.

Auth0 is an identity access management (IAM) provider. But what does this mean? If you've read [Introduction to Identity and Access Management (IAM)](/docs/get-started/identity-fundamentals/identity-and-access-management), you know an IAM solution is a gatekeeper to the resources you provide to customers as web applications, APIs, etc. The gatekeeper initiates authorization as outlined in <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip>. The addition of the <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect layer adds authentication to secure your users’ <Tooltip href="/docs/glossary?term=digital+identities">digital identities</Tooltip> and your product.

The Auth0 identity platform supports different application types and frameworks. Whether your application is a regular web app, a mobile app, or a machine-to-machine app, Auth0 provides configurations for the most secure authorization grant, or workflow, for each. You can read more about authorization grants and choose the one for your application in our article [Which OAuth 2.0 Flow Should I Use?](/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use)

Aside from supporting secure protocols, the Auth0 identity platform allows you to customize login services to fit your business, your technology, and your customer base. Using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> and <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>, you can create your own Auth0 instance to authenticate and authorize your customers. You can configure login behaviors, connect your user data store, manage those users, choose an authorization grant, and establish authentication factors for a seamless, scalable product with an impactful user experience.

## Get Started

### Identity fundamentals

You don’t have to be an expert on IAM to integrate Auth0 into your application or API, but you can choose the right configuration for your use case if you know some key concepts. To learn more, read our [Introduction to Identity and Access Management (IAM)](/docs/get-started/identity-fundamentals/identity-and-access-management) article. If you still have questions about planning your implementation, review our [Architecture Scenarios](/docs/get-started/architecture-scenarios) section for walk-throughs of real world scenarios.

### Integrate with Auth0

To start integrating with Auth0, you can either start with our interactive [Quickstart guides](/docs/quickstarts) for initial set-up and quick configurations, or you can register your application manually in the Auth0 Dashboard. In Dashboard, you can create a tenant, or your Auth0 instance, from the ground up. If you prefer to use SDKs, Auth0 offers multiple options for each application type. To see the full offering, navigate to [Auth0 Libraries](/docs/libraries).

You can begin your configuration with general details in the Dashboard tenant settings, such as the name displayed to your users, your company logo, your callback URLs, or where Auth0 redirects your users after authentication. You can review our recommendations by reading [Tenant Settings](/docs/get-started/tenant-settings).

Once you’ve set up the tenant, then you can create and configure your application or API. You can use the instructions in our articles [Create Applications](/docs/get-started/auth0-overview/create-applications) or [Register APIs](/docs/get-started/auth0-overview/set-up-apis) as a starting point.

### Authenticate

The vehicle of authentication is the login form, or the intermediary to allow your users access to your application. Users provide pre-determined credentials, such as username or password, in the login form to verify their digital identities.

Auth0’s <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> is a login form you can customize to accommodate your brand and configure to provide secure access. Some benefits of using Universal Login are:

* <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> login with biometrics
* Choice of <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> methods from email, voice, or Duo
* <Tooltip href="/docs/glossary?term=Single+Sign-on">Single Sign-on</Tooltip> (SSO) capabilities
* Localization support

To learn more, read [Universal Login](/docs/authenticate/login/auth0-universal-login). To find out more about available features, read [Universal Login vs. Classic Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login).

Once you have a login form, you can connect your user store to Auth0. You can connect an existing database, or use a social, legal, or enterprise <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> such as X or Azure Active Directory. New users can sign up with the connection you have configured.

Once you have a login form and user store connection, you can set protocols that work behind the scenes when users log in to your application. The most common protocols are associated with the OAuth 2.0 and OpenID Connect (OIDC) specs you may have reviewed in our [Identity Fundamentals](/docs/get-started/identity-fundamentals) article.

Another protocol to securely transmit information during log in comes in the form of tokens. Tokens from the <Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip>, Auth0’s Authentication API, transmit information between entities.  When a user logs in and access is approved, the Authentication API sends an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, an <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip>, or both depending on the authentication grant you are using to create a session. Access tokens contain information about what scopes, or permissions, the requestor has in your application while ID tokens have requestor information, such as user metadata to better the user experience.

Tokens from the Authentication API are <Tooltip href="/docs/glossary?term=JSON+Web+Tokens">JSON Web Tokens</Tooltip> (JWTs) structured with:

* a header that includes the signature
* the payload that contains statements and attributes about the requestor
* the signature that verifies the token is valid

To learn more about tokens, read [Access Tokens](/docs/secure/tokens/access-tokens), [ID Tokens](/docs/secure/tokens/id-tokens), or [JSON Web Tokens](/docs/secure/tokens/json-web-tokens).

Other protocols, like <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> (Security Assertion Markup Language) and <Tooltip href="/docs/glossary?term=WS-Fed">WS-Fed</Tooltip> (Web Service Federation) are used with more specific systems. SAML works with some identity providers while WS-Fed is used with Microsoft products. You can learn more by exploring the [Protocols](/docs/authenticate/protocols) section of our documentation.

### Manage users

Managing user profiles and access can be time-consuming. If you choose to manage users with your Auth0 instance, you can remove some of the pain points.

You can easily automate CRUD operations and query user profiles using Auth0 Dashboard or the Management API. You can categorize your users into categories with Auth0 Organizations to arrange your customer-base to fit your management style. To learn more, navigate to the [Manage Users](/docs/manage-users) section of our documentation.

Your business model may include levels of access for your users. You may want a subsection of users to have read-only permissions and another subsection with the ability to edit. Auth0’s Authorization Core allows you to implement role-based access control. You can create roles, assign roles to users, and define permissions.

If you want to manage access based on browser behaviors, you can limit the lifetime of a session. A session, or the interaction between the requesting entity and your application or resource, has a lifetime limit. A session can end when the user closes the browser or navigates away from your webpage. You can extend sessions with <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip> that renew access tokens. Configure refresh tokens in the Dashboard.  To learn more, read [Session Lifetime Limits](/docs/manage-users/sessions/session-lifetime-limits) and [Get Refresh Tokens](/docs/secure/tokens/refresh-tokens/get-refresh-tokens).

Cookies, or strings of data, tie into the session and represent an authenticated user. Cookies allow your authenticated users to maintain a session and move between web pages without being forced to re-authenticate.  Once the browser closes, the cookie is cleared by the browser.

### Customize

Your brand is important, and Auth0 offers customization to make the login experience more personalized to your business. You can add your logo and color scheme to your login form as well as use a <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip> to give you ownership of the login URL. To learn more about configuration, read [Custom Domains](/docs/customize/custom-domains).

Universal Login offers numerous features to configure authentication to fit your needs, like Multi-factor authentication, passwordless authentication with device biometrics, and localization. On a more granular level, you can adjust the text of prompts your user receives when an action needs to be completed. You can configure prompts for your users to signup, to enroll a device for authentication, or to send a code to an email/SMS for users to enter for verification. You can also customize email communications to welcome new users, verify enrollment, or reset passwords with email templates. To learn more, read [Customize Universal Login Text Elements](/docs/customize/login-pages/universal-login/customize-text-elements) and [Customize Email Templates](/docs/customize/email/email-templates).

You can also configure certain events with Auth0 Actions. Actions are secure functions that execute during runtime. Actions trigger at different points in the pipeline and have a variety of uses. You could add metadata before the user signs up or redirect users to an external site. To learn more about what Actions can do for you, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

### Secure

Malicious attacks can happen anytime. Auth0 offers several <Tooltip href="/docs/glossary?term=attack+protection">attack protection</Tooltip> options, such as <Tooltip href="/docs/glossary?term=Bot+Detection">Bot Detection</Tooltip> in combination with Google reCAPTCHA Enterprise to prevent cyber attacks. To learn more about Bot Detection configuration, read [Bot Detection](/docs/secure/attack-protection/bot-detection).

Even if you are using your own login page, Auth0 offers other security options you can enable in the Auth0 Dashboard:

* <Tooltip href="/docs/glossary?term=Breached+Password+Detection">Breached Password Detection</Tooltip>
* <Tooltip href="/docs/glossary?term=Brute-Force+Protection">Brute-Force Protection</Tooltip>
* <Tooltip href="/docs/glossary?term=Suspicious+IP+Throttling">Suspicious IP Throttling</Tooltip>

Breached password detection is a security measure against malicious agents with stolen credentials. Brute-force protection safeguards a targeted user account by limiting the amount of login attempts that automatically block the malicious IP and send a notification to the flagged user account. Suspicious IP throttling works where brute force protection leaves off to block traffic from any IP address that attempts rapid signups or logins.

Other security measures depend on how you want your users to authenticate. Enabling multi-factor authentication (MFA) in Universal Login requires users to provide two or more authentication factors. With Auth0, you can customize MFA to trigger under certain circumstances, such as a user logging in from an unknown device or from a questionable IP address. To learn more about configuring MFA, read [Adaptive MFA](/docs/secure/multi-factor-authentication/adaptive-mfa).

### Deploy and monitor

When you’ve finished testing your Auth0 instance and are ready to deploy, you can use our public or private cloud offerings. To learn more about available offerings, read [Deployment Options](/docs/deploy-monitor/deployment-options). If you need a multi-tenant capable environment, you can read more about [Private Cloud on AWS](/docs/deploy-monitor/deploy-private-cloud/private-cloud-on-aws).

To keep your deployment on track, we provide guidance in the form of pre-deployment recommendations, a deployment checklist, best practices, common fixes, and other tips to help make deployment as seamless as possible.

Once you’ve established your production environment ready for users, you can be on the lookout with error tracking and alerts. The System Center Operations Manager allows you to monitor, while event logs can be exported to an analytical tool and allow you insight on trends, user behavior, or issues.


# Auth0 Onboarding
Source: https://auth0.com/docs/get-started/onboarding

Integrate Auth0 into your existing infrastructure by following the  B2B, B2C, or M2M pathway.

Welcome to Auth0 Onboarding!

This section of our documentation is to help you integrate Auth0 into your existing infrastructure and give you the confidence to go live with your integration. In this section, you can find relevant resources.

As a complement to this guided onboarding, you can enroll in our free course [Introduction to Okta](https://www.okta.com/training/introduction-to-okta-formerly-okta-basics), which has relevant modules to assist you as you get started.

Follow our guided onboarding to start your journey with Auth0.

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/get-started/onboarding/self-service-m2m">Self-Service Machine-to-Machine</a></td>
      <td>How to onboard for machine-to-machine authentication.</td>
    </tr>
  </tbody>
</table>

## Resources and support

Along with documentation and possible [architecture scenarios](/docs/get-started/architecture-scenarios), Auth0 has several means of support.

* **Auth0 Community:** Engage in discussions with our [developer community and Auth0 experts](https://community.auth0.com/) or you can review our robust [Documentation](https://auth0.com/docs) and [FAQs](https://community.auth0.com/c/faq).
* **Auth0 Marketplace**: [Marketplace](http://marketplace.auth0.com/) aims to simplify your development process with a straightforward way to add an integration to your application built and supported by trusted Marketplace Partners. The marketplace makes it easier and faster to extend and customize your Auth0 solution. All of the integrations you find in the Marketplace are validated by Auth0, so you know you can trust them.
* **Auth0 Status Page:** Should you encounter service disruptions. Follow [our status page](https://status.auth0.com/) and subscribe to RSS feed to get the latest information around our operational status.

## Learn more

* [Introduction to Auth0](/docs/get-started/identity-fundamentals/introduction-to-auth0)
* [Identity Fundamentals](/docs/get-started/identity-fundamentals)
* [Architecture Scenarios](/docs/get-started/architecture-scenarios)
* [Login](/docs/authenticate/login)
* [Check Auth0 Status](/docs/deploy-monitor/monitor/check-auth0-status)


# Self-Service Machine-to-Machine
Source: https://auth0.com/docs/get-started/onboarding/self-service-m2m

Describes how to onboard with an M2M business case.

If your business case services a non-interactive <Tooltip href="/docs/glossary?term=audience">audience</Tooltip>, like APIs or backend servers, you will onboard with a machine-to-machine (M2M) configuration.

## Use cases

Use the M2M onboarding path if you:

* Support service-to-service communications
* Have scheduled jobs or cron tasks running on servers that need to access protected resources or APIs
* Allow IoT devices to communicate with backend services or APIs
* Have an API layer that needs to communicate with other API layers without user involvement or after a user token has expired
* Have a privileged API that may need to be called before a user has authenticated (i.e. from an Action or custom database script in your Auth0 tenant)
* Use an API Gateway to manage backend services
* Use or support non-interactive applications or other tooling not involving human interaction such as daemons or backend services

<Callout icon="file-lines">
  These services will still need an M2M access token for authentication.
</Callout>

## How to use this guide

This guide is a pathway to create your M2M implementation in Auth0. We provide considerations, best practices, and concepts you should review.

* In Architecture, we advise you to configure Auth0 to support your Software Development Life Cycle and existing infrastructure.
* In Create an account, we provide instructions to create your API instance in Auth0 and an application to support the authentication flow (or grant) needed for machine-to-machine authentication.
* In Authentication, we walk through the grant you need to use for authentication as well as <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> and permissions (or scopes) you can set.
* In Branding, we advise you where to find information on how to configure <Tooltip href="/docs/glossary?term=Custom+Domains">Custom Domains</Tooltip> depending on how you plan to manage certificates.
* In Deployment Automations, you can read about our tooling to assist with deployment.
* In Quality Assurance, you can learn more about unit testing, and the readiness checks we provide in <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

## Architecture

Before you configure your Auth0 account and tenant, or the groups and structures of your Auth0 services, create a map of your existing infrastructure so you can best leverage Auth0’s capabilities in your existing ecosystem.

As mentioned in common scenarios, you may have other non-interactive technologies in your application domain, network domain, or M2M device domain to consider before you configure Auth0. To review an example M2M scenario, read [Server + API](/docs/get-started/architecture-scenarios/server-application-api/part-1). To attempt a hands-on lab working with Node and test API deployment, visit our [GitHub repository](https://www.google.com/url?q=https://github.com/auth0-training/labs-node-working-with-apis\&sa=D\&source=docs\&ust=1723578190947730\&usg=AOvVaw3IXRQG9ogH4pW6LEY047T6).

You may want to create a visualization of your current tech stack as well as plan how Auth0 fits in with your current Software Development Lifecycle (SDLC). This can help you determine how many tenants you may need.

### Considerations

Before you create a new account or configure your first tenant, you may want to consider:

* How you partition or group your APIs to call specific endpoints.

  * This may determine the audience and other claims on access tokens.
* Any third-party consumers to your resource may request an access token for each call. Excessive calls could affect your [rate limit](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations/self-service-public).

  * You can use an API Gateway to limit the number of access tokens a third-party can request. To learn more about API Gateways and Auth0, read [Configure an Identity Provider in Access Gateway](/docs/get-started/auth0-overview/create-applications/configure-an-identity-provider-in-access-gateway).

## Create an account

Now that you have a plan for your architecture, you’ll configure your Auth0 account and tenants. When you sign up for Auth0 services, you will create your first [tenant](/docs/get-started/auth0-overview/create-tenants). This is where you configure Auth0 assets, services, and resources. [Sign up](https://auth0.com/signup) to start.

<Card title="Before you start">
  In the Auth0 Dashboard or with the Auth0 Management API, create:

  * An API to represent your API
  * An M2M application to use the Client Credential Flow

  You may want to plan some configuration details before you create an account.

  * Your tenant name has a role in your Auth0 domain. Before you determine a name, you should review [tenant characteristics](/docs/get-started/auth0-overview/create-tenants#create-a-tenant-and-domain).
  * Which Auth0 features you need for your use case. Some features are only available on Professional and Enterprise plans.
  * Determine if you need to support multiple environments, such as development, staging, and production. To learn more, read [Set Up Multiple Environments](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments).
  * If you have a use case involving thirty-party applications you want to register in a tenant, you can use [Dynamic Application Registration](/docs/get-started/applications/dynamic-client-registration) based on the [OIDC Client Registration](https://openid.net/specs/openid-connect-registration-1_0.html) specification.
</Card>

### Provision a tenant

Now that you have a plan for your architecture, you’ll configure your Auth0 account and <Tooltip href="/docs/glossary?term=Tenant">Tenant</Tooltip>.

<Warning>
  Once you create an API in Auth0 Dashboard, a test application for the API automatically generates. If you create an API programmatically in [Management API](https://auth0.com/docs/api/management/v2/), you may need to create a test application in a separate call.
</Warning>

#### Register an API

In this section, create your API in Auth0.

<Callout icon="file-lines">
  You can always update your API in Auth0 Dashboard or by calling the Management API [Update a resource server](https://auth0.com/docs/api/management/v2/resource-servers/patch-resource-servers-by-id) endpoint.
</Callout>

<Tabs>
  <Tab title="Auth0 Dashboard">
    Start by creating an instance in the Auth0 Dashboard for your APIs.

    1. Follow instructions to [register your API](/docs/get-started/auth0-overview/set-up-apis).

    In the [Authentication](/docs/get-started/onboarding/self-service-m2m#authentication) section, configure your API settings for M2M authentication.
  </Tab>

  <Tab title="Management API">
    To register an API programmatically, use the Management API. You will need an access token to use Management API. To learn how, read [Management API Tokens](/docs/secure/tokens/access-tokens/management-api-access-tokens).

    Use the sample provided in Management API Explorer to call the Management API [Create a Resource Server](https://auth0.com/docs/api/management/v2/resource-servers/post-resource-servers) endpoint and include the following parameters in the body:

    <table>
      <thead>
        <tr>
          <th><strong>Field</strong></th>
          <th><strong>Description</strong></th>
          <th><strong>Example</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><strong>Name</strong></td>
          <td>A friendly name for the API. Does not affect any functionality.</td>
          <td><code>yourDomain</code></td>
        </tr>

        <tr>
          <td><strong>Identifier</strong></td>
          <td>A unique identifier for the API. Auth0 recommends using a URL. Auth0 does differentiate between URLs that include the last forward slash. For example, `https://example.com` and `https://example.com/` are two different identifiers. The URL does not have to be a publicly available URL. Auth0 will not call your API. This value cannot be modified afterwards.</td>
          <td>`https://{yourDomain}`</td>
        </tr>

        <tr>
          <td><strong>JSON Web Token (JWT) Profile</strong></td>
          <td>The profile determines the format of the access tokens issued for the API. The available values are <code>Auth0</code> and <code>RFC 9068</code>. To learn more, read <a href="/docs/secure/tokens/access-tokens/access-token-profiles">Access Token Profiles</a>.</td>
          <td><code>access\_token</code></td>
        </tr>

        <tr>
          <td><strong>JSON Web Token (JWT) Signing Algorithm</strong></td>
          <td>The algorithm to sign the access tokens with. The available values are <code>HS256</code>, <code>PS256</code>, <code>RS256</code>. If you select <code>RS256</code>, the token will be signed with the tenant's private key.</td>
          <td><code>HS256</code></td>
        </tr>
      </tbody>
    </table>
  </Tab>
</Tabs>

### Associate an application

You need to create an association between your application and your API so your application can request access tokens from it. You will learn more about client grants in the Authentication section.

<Callout icon="file-lines">
  Auth0’s API has multiple settings you may need to review before you configure. To learn more, read [API Settings](/docs/get-started/apis/api-settings).
</Callout>

<Tabs>
  <Tab title="Auth0 Dashboard">
    If you create your API in the Dashboard, Auth0 automatically generates a test application and associates it with your API.

    1. Navigate to [Auth0 Dashboard > Applications](https://manage.auth0.com/#/applications).
    2. Select the test M2M test application created when you created your API.

       <Callout icon="file-lines">
         You can create another application for development or production later by following the instructions on [Register Machine-to-Machine Applications](/docs/get-started/auth0-overview/create-applications/machine-to-machine-apps).
       </Callout>
    3. Switch to the **API** view, and then locate the API you’d like to enable for this application.
    4. Enable the **Authorize** toggle, and then select the arrow button on the right to expand the card.
    5. Select **Update**.

       <Frame>
         <img alt="Dashboard > Applications > APIs" />
       </Frame>

       <Callout icon="file-lines">
         In this view, you can select the drop-down and choose the scopes you want to add. We will learn more about scopes when discussing access tokens under the Authentication section.
       </Callout>
  </Tab>

  <Tab title="Management API">
    Create an application to associate with your API. Use the sample provided in Management API Explorer to:

    1. Call the [Create a Client](https://auth0.com/docs/api/management/v2/clients/post-clients) endpoint. You need to set the `app_type` to `non-interactive`.
    2. Call the [Create Client Grant](https://auth0.com/docs/api/management/v2/client-grants/post-client-grants) endpoint to associate your application to your API.

    To learn about application and tenant settings, read [Tenant Settings](/docs/get-started/tenant-settings).
  </Tab>
</Tabs>

## Authentication

When calling one API from another API, or from any situation where there is no authenticated user context, you need a way to authorize the application instead of a user. This is a one step process where the application is authenticated (using a `client_id` and `client_secret`) and then authorized in one call.

For non-interactive applications or services to authentication, you must select a client grant, or authentication flow. The <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> [Client Credentials Flow](https://tools.ietf.org/html/rfc6749#section-4.4) does not require human interaction and is best suited for M2M applications.

<Card title="Before you start">
  In Auth0 Dashboard or Management API, you will:

  * Set your application to use the Client Credentials Flow
  * Update the scopes for your M2M access tokens

  Before you configure your authentication method:

  * Review the [Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow) for machine-to-machine authentication. This is the workflow for non-interactive authentication and authorization.
  * Determine the level of access for your APIs. This helps determine what [scopes](/docs/get-started/apis/scopes/api-scopes), or permissions, you will configure when you create your API.
</Card>

### Configure the Client Credential Flow

You can use the Auth0 Dashboard or <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to set the authentication flow to provide a client credential in exchange for an access token.

Follow the instructions on [Update Grant Types](/docs/get-started/applications/update-grant-types) to use Auth0 Dashboard or Management API.

### M2M access tokens

In token-based authentication, non-interactive clients provide `client_id` and `client_secret` in a call to the [Authentication API token endpoint](/docs/customize/actions/explore-triggers/machine-to-machine-trigger) to get an [access token](/docs/secure/tokens/access-tokens). This access token permits access to your protected API.

The default profile, or format, is the Auth0 token profile associated with two token profiles. You can choose to change the token profile to RFC 9068. To learn more, read [Access Token Profiles](/docs/secure/tokens/access-tokens/access-token-profiles). To verify the token is valid, your API will check the [Signing Algorithms](/docs/get-started/applications/signing-algorithms). The default <Tooltip href="/docs/glossary?term=signing+algorithm">signing algorithm</Tooltip> is RSA256, a key-based algorithm.

<Callout icon="file-lines">
  Auth0 supports other client authentication methods besides providing Client ID and Client Secret as credentials. These methods, including our recommendation of [Private Key JWT](/docs/get-started/authentication-and-authorization-flow/authenticate-with-private-key-jwt) for M2M configurations, are available with an Enterprise plan. To learn more, read [Application Credentials](/docs/secure/application-credentials).
</Callout>

#### Example

A request to the `/oauth/token` endpoint should be similar to the sample below:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=client_credentials \
    --data client_id={yourClientId} \
    --data client_secret={yourClientSecret} \
    --data audience=YOUR_API_IDENTIFIER
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}&audience=YOUR_API_IDENTIFIER", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}&audience=YOUR_API_IDENTIFIER")

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

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}&audience=YOUR_API_IDENTIFIER")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      audience: 'YOUR_API_IDENTIFIER'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=client_credentials" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_secret={yourClientSecret}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&audience=YOUR_API_IDENTIFIER" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}&audience=YOUR_API_IDENTIFIER",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}&audience=YOUR_API_IDENTIFIER"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}&audience=YOUR_API_IDENTIFIER"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/x-www-form-urlencoded"]

  let postData = NSMutableData(data: "grant_type=client_credentials".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&client_secret={yourClientSecret}".data(using: String.Encoding.utf8)!)
  postData.append("&audience=YOUR_API_IDENTIFIER".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

The response should be similar to the sample below:

```json lines theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token":"eyJz93a...k4laUWw",
  "token_type":"Bearer",
  "expires_in":86400
}
```

#### Token expiration

Your access tokens have a limit for how long the token is valid. Since your communications are on the back-channel, you cannot use <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip> to extend sessions, and should consider configuring your access tokens with a 1-hour expiration time. You may need to strike your own balance between security and performance for your specific environment. To learn more, read [Update Access Token Lifetime](/docs/secure/tokens/access-tokens/update-access-token-lifetime).

### Scopes

Before any non-interactive clients or services call your API, you need to define the permissions or Scopes your API allows. You can set the scopes in Auth0 Dashboard to include in your authentication request to Authentication API. To read more examples of ways to use API scopes, read [API Scopes](/docs/get-started/apis/scopes/api-scopes).

To configure scopes, follow the instructions on [Add API Permissions](/docs/get-started/apis/add-api-permissions) for Auth0 Dashboard or use the sample provided for Management API.

<Callout icon="file-lines">
  To add custom claims to an access token, you can use the Actions Machine-to-Machine Flow. To learn more, read Machine to Machine Flow.
</Callout>

## Branding

Even if you service non-interactive clients or services working on the back-channel, you can still customize your experience to align with the look and feel of your existing brand.

### Custom domains

Auth0 supports the use of custom domains when you call the `/authorize` endpoint to request access tokens.

<Card title="M2M Onboarding - custom domains">
  In Auth0 Dashboard, you must:

  * Register and verify your domain before you can use it with your Auth0 services.
  * Determine if you want to manage your own certificate or use an Auth0 managed certificate. To learn more about certificates, read [Certificate management options](/docs/customize/custom-domains#certificate-management-options).
  * Verify the TLS (SSL) version and cipher you want to use for self-managed certificates is supported by Auth0. To learn more, read [TLS (SSL) Versions and Ciphers](/docs/customize/custom-domains/self-managed-certificates/tls-ssl).
</Card>

1. To configure your custom domain with Auth0-managed certificates, follow the instructions on [Configure Custom Domains with Auth0-Managed Certificates](/docs/customize/custom-domains/auth0-managed-certificates).

   1. If you want to manage your own certificates, follow the instructions on [Configure Custom Domains with Self-Managed Certificates](/docs/customize/custom-domains/self-managed-certificates).

      <Callout icon="file-lines">
        You must have an Enterprise subscription to manage certificates in your custom domain. To learn more, read [Auth0 Pricing](https://auth0.com/pricing/) and [Login](/docs/authenticate/login).
      </Callout>
2. Review [API configuration with custom domains](/docs/customize/custom-domains/configure-features-to-use-custom-domains#apis). You may need to adjust your API settings to incorporate a custom domain.

If you experience issues with your custom domain, review [Troubleshoot Custom Domains](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-custom-domains).

## Deployment Automation

Auth0 provides support for a couple of different options when it comes to the deployment automation approaches you can use, and each can be used in conjunction with the other.

<Card title="Best Practice">
  However you configure deployment automation, we’d recommend you unit test your custom code and Actions prior to deployment, and run some integration tests against your tenant post-deployment too.
</Card>

### Deploy CLI Tool

As recommended under the Architecture section, you should have Auth0 tenants for development, test, and production. These tenants should share identical configurations for quality checks and testing; however, you may be faced with errors as a result of mismatched configurations between your environments. For example, each environment will have different <Tooltip href="/docs/glossary?term=Client+IDs">Client IDs</Tooltip> and <Tooltip href="/docs/glossary?term=Client+Secrets">Client Secrets</Tooltip>.

To mitigate these mismatch errors, you can use the Deploy CLI Tool to help you integrate your Auth0 instance with your existing CI/CD pipeline.  With dynamic keyword replacement, you can replace environmental variables on tenants sharing similar configurations. To learn more, read [Deploy CLI Tool](/docs/deploy-monitor/deploy-cli-tool) and [Keyword Replacement](/docs/deploy-monitor/deploy-cli-tool/keyword-replacement).

### Actions Real-time Logs

Actions Real-time Logs displays all logs for custom cSode in real-time, including `console.log` output and other exceptions. If you are using Auth0 Actions or other custom logic, you can use this extension to debug and troubleshoot. To learn more about installation and configuration, read [Actions Real-time Logs](/docs/customize/actions/actions-real-time-logs).

## Quality Assurance

Quality Assurance is important in identifying issues before you go live. Depending on the nature of your project, there are several different types of quality assurance testing that you’re going to want to consider as part of your integration with Auth0:

* How will your APIs perform when subjected to unexpected production loads?
* How will your rate limits be affected by third-party applications?

If you are not using Auth0 widgets or features, like <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>, you will not have the built-in usability and accessibility best practices out-of-the-box on a host of browsers and devices. To ensure functional requirements are met and unexpected events are handled correctly, guidance is provided for testing the integration between your application(s) and Auth0, and for unit testing individual extensibility modules, such as Auth0 Actions. We also recommend you review Auth0’s [penetration testing policy](/docs/troubleshoot/customer-support/operational-policies/penetration-testing-policy) and complete Mock testing you can leverage in conjunction with our [load testing policy](/docs/troubleshoot/customer-support/operational-policies/load-testing-policy) to help ensure your application(s) perform under unexpected load.

### Unit testing

Unit testing is verifying units of extensibility, like Auth0 Actions. If you are using custom code we recommend using a test framework (such as [Mocha](https://mochajs.org/)) to test the additional code before deployment.

### Mock testing

In a balance between Auth0’s [load testing policy](/docs/troubleshoot/customer-support/operational-policies/load-testing-policy) and the desire to load test, it is common practice to create a mock test of Auth0’s endpoints. This is a valuable practice in order to ensure that your configuration works with your expected interfaces without having to restrict your testing, and tools such as [MockServer](http://www.mock-server.com/), [JSON Server](https://github.com/typicode/json-server), or even [Postman](https://learning.getpostman.com/docs/postman/mock_servers/setting_up_mock/) can be used to assist.

## Deployment

Our [Deploy and Monitor](/docs/deploy-monitor) section provides guidance for deployment best practices. We advise your review [Pre-Deploym](/docs/deploy-monitor/pre-deployment-checks)[ent Checks](/docs/deploy-monitor/pre-deployment-checks), especially the built-in [Auth0 Dashboard Readiness Checks](/docs/deploy-monitor/pre-deployment-checks/how-to-run-production-checks).

To review the Readiness Check, select the drop-down menu below your tenant name and environmental tag at [Auth0 Dashboard > Run Readiness Checks](https://manage.auth0.com/#/production-checks).

<Frame>
  <img alt="Auth0 Dashboard > Readiness Checklist" />
</Frame>

You can use the filter to apply the Readiness Checks to selected applications. **These checks do not apply to your configured APIs**.

For checks that do not apply to your specific configuration, you can select **Dismiss** to remove them from the final results.

We advise you to review [Deployment Best Practices](/docs/deploy-monitor/deployment-best-practices) for final checks before you go live and take advantage of [Logs](/docs/deploy-monitor/logs) to monitor your services.

## Learn more

* [Auth0 Overview](/docs/get-started/auth0-overview)
* [Solution Overview (Server Apps + API)](/docs/get-started/architecture-scenarios/server-application-api/part-1)
* [Call Your API Using the Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow/call-your-api-using-the-client-credentials-flow)
* [Retrieve Log Logs Using the Management API](/docs/deploy-monitor/logs/retrieve-log-events-using-mgmt-api)
* [Get Management API Access Tokens for Production](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production)


# Tenant Settings
Source: https://auth0.com/docs/get-started/tenant-settings

Describes the settings related to tenants available in the Auth0 Dashboard.

Use the **Tenant Settings** page in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> at [Dashboard > Settings](https://manage.auth0.com/#/tenant) to configure various settings related to your Auth0 tenant.

## Recommended settings

When you configure your tenant, set the following items:

* **Specify the Environment Tag.** Tenants tagged as **Production** are granted higher rate limits than tenants tagged as **Development** or **Staging**. On non-Enterprise plans, only one tenant per subscription can be tagged as **Production**. To learn more, read [Set Up Multiple Environments](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments).
* **Set the Support Email and Support URL.** If a user encounters an issue while logging in, they'll want to reach out for help. Set these values to direct them to an email address or landing page to get assistance.
* **Configure a custom error page.** If possible, you should host your own custom error page and configure Auth0 to use it instead of the default page. This allows you to provide more complete and customized explanations to users about what to do in the event of an error.
* **Set up a <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip>.** If you are on a paid plan, you can configure a custom domain for your Auth0 tenant. A custom domain unifies the login experience with your brand and provides additional benefits. To learn more, read [Custom Domains](/docs/customize/custom-domains).
* **Set the <Tooltip href="/docs/glossary?term=Single+Sign-On">Single Sign-On</Tooltip> (SSO) session timeout.** The SSO session timeout value specifies the time until a user's session expires. The value is 7 days by default, which is the length of time users can access your Auth0-integrated applications without re-entering their credentials. To learn more, read [Sessions](/docs/manage-users/sessions).
* **Set up tenant members.** Configure additional Auth0 Dashboard users and enable <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA). To learn more, read [Manage Dashboard Access](/docs/get-started/manage-dashboard-access) and [Manage Dashboard Access with Multi-Factor Authentication](/docs/get-started/manage-dashboard-access/add-change-remove-mfa).
* **Disable the Enable Application Connections setting.** If this setting is enabled, all configured connections will be automatically enabled for any new application you create. As a result, users may be able to log in to the application through connections that you did not intend to be available. Disable this setting so you can explicitly enable the connections appropriate for each application.
* **Enable <Tooltip href="/docs/glossary?term=Attack+Protection">Attack Protection</Tooltip>.** Protect your users against brute force attacks and breached passwords. To learn more, read [Attack Protection](/docs/secure/attack-protection).

## General

On the **General** tab, you can customize basic tenant settings.

### Settings

<Frame>
  <img alt="Dashboard Tenant Settings General Settings tab" />
</Frame>

* **Friendly Name**: Name you want to be displayed to your users on the <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> page. Typically this is the name of your company or organization.
* **Logo URL**: URL of the logo you want to be displayed on the Universal Login page. Minimum recommended resolution is 200 pixels (width) by 200 pixels (height).
* **Support Email**: Email address used to contact your support team.
* **Support URL**: Link to your company or organization support page.

### Environment Tag

You can identify your tenant as a production, staging, or development tenant to differentiate it from other tenants. Higher rate limits apply to tenants tagged as Production with a paid subscription. To learn more, read [Set Up Multiple Environments](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments).

<Frame>
  <img alt="undefined" />
</Frame>

### API Authorization Settings

<Frame>
  <img alt="Dashboard Tenant Settings General Tab API Authorization Settings" />
</Frame>

* **Default <Tooltip href="/docs/glossary?term=Audience">Audience</Tooltip>**: API identifier to use for [Authorization Flows](/docs/get-started/authentication-and-authorization-flow). If you enter a value, all <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> issued by Auth0 will specify this API identifier as an audience. Setting the **Default Audience** is equivalent to appending this audience to every authorization request made to your tenant for every application. This will cause new behavior that might result in breaking changes for some of your applications. Please [contact support](/docs/troubleshoot/customer-support/open-and-manage-support-tickets) if you require assistance.
* **Default Directory**: Name of the default connection to be used for both the [Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow) and [Universal Login Experience](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience). Its value should be the exact name of an existing connection for one of the following strategies: `auth0-adldap`, `ad`, `auth0`, `email`, `sms`, `waad`, or `adfs`.

### Error Pages

In the event of an authorization error, you can either display a generic error page to your users or you can redirect users to your own custom error page. To learn more, read [Custom Error Pages](/docs/customize/login-pages/custom-error-pages).

<Frame>
  <img alt="Dashboard Tenant Settings General Error Pages" />
</Frame>

### Languages

<Frame>
  <img alt="Dashboard Tenant Settings General Tab Languages" />
</Frame>

* **Default Language**: Language your tenant will use by default.
* **Supported Languages**: Languages also supported by your tenant.

## Subscription

On the **Subscription** tab, you can review your current subscription and compare features of your current plan to other Auth0 subscription plans. You can also change your subscription plan. To learn more, read [Manage Subscription](/docs/troubleshoot/customer-support/manage-subscriptions).

If you have an Enterprise subscription, please refer to your Auth0 agreement for details.

<Frame>
  <img alt="Auth0 Tenant Settings Subscription tab" />
</Frame>

## Payment

On the **Payment** tab, you can enter or update your billing details.

## Tenant Members

On the **Tenant Members** tab, you can view a list tenant members assigned to your tenant. You may also add or remove tenant members and review their assigned roles and if they have multi-factor authentication (MFA) enabled. To learn more, read [Manage Dashboard Access](/docs/get-started/manage-dashboard-access).

<Frame>
  <img alt="Dashboard Tenant Settings Tenant Members tab" />
</Frame>

## Custom Domains

On the **Custom Domains** tab, you can configure a custom domain to maintain a consistent user experience. When you create a custom domain, users will remain in your domain for login rather than being redirected to your `auth0.com` domain. To learn more, read [Custom Domains](/docs/customize/custom-domains).

<Card title="Availability varies by Auth0 plan">
  Both your specific login implementation and your Auth0 plan or custom agreement affect whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

<Frame>
  <img alt="Dashboard Tenant Settings Custom Domains tab" />
</Frame>

## Signing Keys

On the **Signing Keys** tab, you can securely manage the signing key and certificate used to sign <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip>, access tokens, <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> assertions, and <Tooltip href="/docs/glossary?term=WS-Fed">WS-Fed</Tooltip> assertions that are sent to your applications.

<Frame>
  <img alt="Dashboard Tenant Settings Signing Keys tab" />
</Frame>

* **Rotation Settings**: Settings that allow you to rotate the application signing key and certificate. You can choose whether or not to revoke the signing key upon rotation. To learn more, read [Signing Keys](/docs/get-started/tenant-settings/signing-keys).

  * **Rotate Signing Key**: Rotates the signing key without revoking it; effectively, moves the current key to the previous key. All tokens signed with the previous key will still be valid until it is revoked.
  * **Rotate & Revoke Signing Key**: Rotates the signing key and then revokes it; effectively, moves the current key to the previous key, and then invalidates the previous key. Make sure you have updated your application with the next key in the queue before you rotate and revoke the current key.
* **List of Valid Keys**: List of valid application signing keys for your tenant, which are also available at the Metadata endpoint for your application. Valid keys include:

  * **Next in queue**: Key that will be used when the signing key is next rotated.
  * **Currently used**: Key that is currently in use.
  * **Previously used**: Key that was previously used. Its appearance indicates that the signing key has been rotated, but the previously-used key has not yet been revoked.
* **List of Revoked Keys**: List of the last three revoked keys for your tenant. More data about revoked keys is available in tenant logs.

## Advanced

On the **Advanced** tab, you can configure advanced tenant settings.

### Login and Logout

<Frame>
  <img alt="Dashboard Tenant Settings Advanced Tab Login and Logout" />
</Frame>

* **Tenant Login URI**: URI that points to a route in your application that starts the OIDC login flow by redirecting to the `/authorize` endpoint; it should take the form of `https://mytenant.org/login`. This will only be used in scenarios where Auth0 needs your tenant to start the OIDC login flow. To learn more, see [Configure Default Login Routes](/docs/authenticate/login/auth0-universal-login/configure-default-login-routes).
* **Allowed Logout URLs**: URLs Auth0 can redirect to after logout when no client\_id is specified on the Logout endpoint invocation. Useful as a global list when Single Sign-on (SSO) is enabled. To learn more, read [Logout](docs/authenticate/login/logout).
* **Allowed ACR Values**: List of allowed Authentication Context Class Reference (ACR).  These values are included in the OpenID Configuration document. When populated, values not listed here will be rejected if used in authentication flows.
* **RP-Initiated Logout End Session Endpoint Discovery**: Controls if the logout endpoint is advertised in the OpenID Configuration responses as `end_session_endpoint`.
* **RP-Initiated Logout End-User Confirmation**: Controls whether the user is asked to confirm login if the RP-Initiated logout request does not include the correct hints.
* **Non-Verifiable Callback URI End-User Confirmation**: Controls whether the user is prompted to confirm login when a custom URI scheme is used as callback. Auth0 recommends that you **do not** skip end-user confirmation in these cases. To learn more, read [Measures Against Application Impersonation](docs/secure/security-guidance/measures-against-app-impersonation.mdx).

### Login Session Management

The **Login Session Management** settings configure the login session lifetime that represents the Auth0 <Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip> session layer. The authorization server session layer drives single sign-on (SSO). To learn more, read [Single Sign-on](/docs/authenticate/single-sign-on).

Timeouts for tokens issued by Auth0 can be configured elsewhere. Token timeouts are often used to drive the Application session layer and appear in token claims, such as in the expiration claim for <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) ID tokens or the lifetime assertion for SAML.

<Frame>
  <img alt="Dashboard Tenant Settings Advanced Login Session Management" />
</Frame>

* **Inactivity timeout**: Timeframe (in minutes) after which a user's session will expire if they haven’t interacted with the Authorization Server. It will be superseded by system limits if over 4,320 minutes (3 days) for non-Enterprise plans or 144,000 minutes (100 days) for Enterprise plans.
* **Require log in after**: Timeframe (in minutes) after which a user will be required to log in again, regardless of their activity. It will be superseded by system limits if over 43,200 minutes (30 days) for non-Enterprise plans or 525,600 minutes (365 days) for Enterprise plans.

### Device Flow User Code Format

If you are using the [Device Authorization Flow](/docs/get-started/authentication-and-authorization-flow/device-authorization-flow), these settings configure the randomly generated user code. To learn more, read [Configure Device User Code Settings](/docs/get-started/tenant-settings/configure-device-user-code-settings).

<Frame>
  <img alt="Dashboard Tenant Settings Advanced Tab Device Flow User Code Format" />
</Frame>

* **User Code Character Set**: Character set used to generate the user code.
* **User Code Mask**: Mask used to format the user code. The mask defines the length of the user code and formats it into a friendly, readable value, allowing spaces or hyphens for readability.

### Global client information

The **Global <Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>** and **Global <Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip>** are used to generate tokens for legacy Auth0 APIs. Typically, you will not need these values. If you need to have the global client secret changed, please [contact support](https://support.auth0.com).

<Frame>
  <img alt="Dashboard Tenant Settings Advanced Tab Global Client Information" />
</Frame>

### Settings (Advanced)

<Frame>
  <img alt="Dashboard Tenant Settings Advanced Tab Settings" />
</Frame>

* **Change Password Flow v2**: When enabled, the newest version of the Change Password Flow will be used. The previous version has been deprecated, and we strongly recommend enabling v2. This flag is presented only for backward compatibility, and once enabled, you can no longer disable it. You can customize the user interface for the Change Password widget on the [Universal Login > Password Reset](https://manage.auth0.com/#/password_reset) tab in the Auth0 Dashboard.
* **Dynamic Client Registration (DCR)**: When enabled, third-party developers will be able to dynamically register applications for your APIs. You can also update this flag using the [`/tenant/patch_settings`](https://auth0.com/docs/api/management/v2#!/Tenants/patch_settings) endpoint of the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. By default, this feature is disabled. To learn more, read [Dynamic Client Registration](/docs/get-started/applications/dynamic-client-registration).
* **Resource Parameter Compatibility Profile (Early Access)**: When enabled, Auth0 uses the `resource` parameter to specify which resource server (API) the client application wants to access. When disabled, which is the default, Auth0 uses the `audience` parameter to specify the resource server. When enabled, Auth0 first checks the `audience` parameter, and if not available, it uses the `resource` parameter. The value of the `resource` parameter must be an absolute URI and can be forwarded to an upstream identity provider.
* **Enable Application Connections**: When enabled, all current connections will be enabled for any new application that is created.
* **Use a generic response in public signup API error message**: When enabled, errors generated while using the public signup API will return a generic response. This helps protect against user registration enumeration by preventing <Tooltip href="/docs/glossary?term=bad+actors">bad actors</Tooltip> from being able to guess previously-registered identifiers (username, email, or phone) from reading error response codes, such as `user_exists`.
* **Enable Publishing of Enterprise Connections Information with <Tooltip href="/docs/glossary?term=IdP">IdP</Tooltip> domains**: When enabled, it supports [Home Realm Discovery](/docs/authenticate/login/auth0-universal-login/identifier-first) and [Auth0 Lock](/docs/libraries/lock) relies on a checked public file that includes enterprise connection information. If you don’t require that functionality, you can disable it.
* **Enable email verification flow during login for Azure AD and ADFS connections**: When enabled, users will be presented with an email verification prompt during their first login when using Azure AD or ADFS connections.
* **<Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip> Revocation Deletes Grant**: When enabled, it deletes the underlying grant when you revoke a refresh token using the Authentication API `/oauth/revoke` endpoint.

  <Callout icon="file-lines">
    For existing tenants, this feature is enabled by default to preserve the existing behavior. For new tenants (as of 13 January 2021), this feature is disabled by default to ensure that the revocation of a refresh token will not revoke the grant. If a grant revocation is needed, a separate request must be sent using a grant revocation endpoint.
  </Callout>
* **Allow Organization Names in Authentication API**: When enabled, [/authorize](https://auth0.com/docs/api/authentication#authorize-application) and [SAML](https://auth0.com/docs/api/authentication#saml) endpoints can accept both organization IDs and names. Additionally, ID and access tokens will include both `org_id` and `org_name` claims. Before enabling this setting, review [Use Organization Names in Authentication API](/docs/manage-users/organizations/configure-organizations/use-org-name-authentication-api) for important considerations and potential impacts.
* **Allow Pushed Authorization Requests (PAR):** When enabled, the `/par` endpoint can accept authorization requests pushed to it from a client application. This prevents the client application from sending requests via the insecure front channel (i.e. the browser).

### Extensibility

<Frame>
  <img alt="Dashboard Tenant Settings Advanced Tab Extensibility" />
</Frame>

* **Runtime**: Select the version of the Node.js runtime environment you want to use for Auth0 extensibility features, including [Custom Database Action Scripts](/docs/authenticate/database-connections/custom-db/templates) and [Custom Social Connections](/docs/authenticate/identity-providers/social-identity-providers/oauth2).
* **Verify Custom DB Scripts:** Select and run a Node.js runtime version compatibility check for enabled Custom Databases.

  <Callout icon="file-lines">
    The Verify Custom Database Action Scripts feature:

    * Is available if your tenant has 1 to 10 [database connections](/docs/authenticate/database-connections/custom-db/create-db-connection).
    * Requires [custom database scripts](/docs/authenticate/database-connections/custom-db/templates) to be enabled.
    * Only checks Node.js runtime compatibility. Functionality is not verified.
  </Callout>

### Migrations

In this section, you can choose to enable or disable various migrations that are available.

### Feature Previews

In this section, you can choose to enable or disable feature previews that are available.

### Delete tenant or subscription

Deleted tenants cannot be restored and the tenant name cannot be used again when creating new tenants. To learn how to reset your tenant configuration, read [Delete or Reset Tenants](/docs/troubleshoot/customer-support/manage-subscriptions/delete-or-reset-tenant).

## Learn more

* [Manage Subscriptions](/docs/troubleshoot/customer-support/manage-subscriptions)
* [Delete or Reset Tenants](/docs/troubleshoot/customer-support/manage-subscriptions/delete-or-reset-tenant)
* [Manage Dashboard Access](/docs/get-started/manage-dashboard-access)
* [Signing Keys](/docs/get-started/tenant-settings/signing-keys)
* [Custom Domains](/docs/customize/custom-domains)


# Configure Device User Code Settings
Source: https://auth0.com/docs/get-started/tenant-settings/configure-device-user-code-settings

Learn how to configure the user code generated by your applications during the device authorization flow using the Auth0 Dashboard.

You can configure settings for the user code generated by your application during the [Device Authorization Flow](/docs/get-started/authentication-and-authorization-flow/device-authorization-flow) using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

1. Go to [Dashboard > Settings](https://manage.auth0.com/#/tenant) and click the **Advanced** tab.
2. Scroll to the **Device Flow User Code Format** section, locate **User Code Character Set** and **User Code Mask**, enter the desired settings, and click **Save**.

<table>
  <thead>
    <tr>
      <th>Setting</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Device Flow User Code Format</strong></td>
      <td>Character set used to when randomly generating a user code.</td>
    </tr>

    <tr>
      <td><strong>User Code Mask</strong></td>
      <td>Mask used to define length and format of a randomly-generated user code. Its purpose is to increase the user code's readability and ease of input.</td>
    </tr>
  </tbody>
</table>

## Learn more

* [Device Authorization Flow](/docs/get-started/authentication-and-authorization-flow/device-authorization-flow)
* [Unlink Devices from Users](/docs/manage-users/user-accounts/unlink-devices-from-users)


# Enable Single Sign-On for Tenants
Source: https://auth0.com/docs/get-started/tenant-settings/enable-sso-for-legacy-tenants

Describes how to enable Single Sign-on (SSO) for a tenant using the Auth0 Dashboard. Only for use with legacy tenants.

<Callout icon="file-lines">
  Only for use with legacy tenants. By default, seamless single sign-on (SSO) is enabled for all new Auth0 tenants, however, legacy tenants may choose whether to enable this feature.
</Callout>

You can enable <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> for your tenant using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. If you do not choose to enable tenant-level SSO, you may [enable it per application](/docs/get-started/applications/enable-sso-for-applications). If you do not see this setting available in the Dashboard, you already have Seamless SSO enabled; this toggle is strictly for legacy tenants.

1. Go to [Dashboard > Tenant Settings](https://manage.auth0.com/#/tenant).

   <Frame>
     <img alt="Dashboard Tenant Settings General Settings tab" />
   </Frame>
2. Go to the **Advanced** tab.
3. Scroll to the **Log In Session Management** section. Locate **Enable Seamless SSO**.
4. Enter the **Inactivity timeout** (default 4320 minutes) and **Require log in after** (default 10080 minutes) fields.

Once finished, you should also [configure your session lifetime settings](/docs/manage-users/sessions/configure-session-lifetime-settings).

## Learn more

* [Single Sign-On](/docs/authenticate/single-sign-on)


# Find Your Tenant Name or Tenant ID
Source: https://auth0.com/docs/get-started/tenant-settings/find-your-tenant-name-or-tenant-id

How to find the name of your Auth0 tenant

Every Auth0 tenant has a name. You use this name frequently in your code to identify the tenant. When you see the `{yourTenantId}`, `{yourTenantName}`, `{yourTenant}`, or similar variable in the Auth0 documentation, substitute the variable with the tenant name.

1. Go to the [Auth0 Dashboard](https://manage.auth0.com/#).
2. In the top-left corner, find the tenant name beside the Auth0 logo.

<Frame>
  <img alt="Find the name or ID of your Auth0 tenant" />
</Frame>

## Learn more

* [Tenant Settings](/docs/get-started/tenant-settings)
* [Multi-Tenant Applications Best Practices](/docs/get-started/auth0-overview/create-tenants/multi-tenant-apps-best-practices)


# Signing Keys
Source: https://auth0.com/docs/get-started/tenant-settings/signing-keys

Describes how your tenant's application signing keys work.

When you select our recommended <Tooltip href="/docs/glossary?term=signing+algorithm">signing algorithm</Tooltip> (RS256), Auth0 uses public-key cryptography to establish trust with your applications. In more general terms, we use a signing key that consists of a public and private key pair.

Signing keys are used to sign <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip>, <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip>, <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> assertions, and <Tooltip href="/docs/glossary?term=WS-Fed">WS-Fed</Tooltip> assertions sent to your application or API. The signing key is a JSON web key (JWK) that contains a well-known public key used to validate the signature of a signed <Tooltip href="/docs/glossary?term=JSON+web+token">JSON web token</Tooltip> (JWT). A JSON web key set (JWKS) is a set of keys containing the public keys used to verify any JWT issued by the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip> and signed using the RS256 signing algorithm. The service may only use one JWK for validating web tokens, however, the JWKS may contain multiple keys if the service rotated signing certificates.

## How it works

When a user signs in to your application, we create a token that contains information about the user and sign the token using its private key before we send it back to your application. Auth0 secures the private key, which is unique per tenant.

To verify that the token is valid and originated from Auth0, your application validates the token’s signature using the public key. We provide other application security key management capabilities through both our Dashboard and <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

Auth0 recommends that you rotate keys regularly to ensure you will be ready for action in case of a security breach.

Additional application signing certificates are listed below.

<Callout icon="file-lines">
  These links populate using your active tenant to provide you with accurate information. You must be logged in to `auth0.com/docs` with your tenant credentials to access these links.

  To sign in, select **Log in** to the top right. After logging in, you can switch between tenants by selecting your profile icon and choosing **Switch tenant**.
</Callout>

* <AuthLink href="https://{yourDomain}/cer">CER</AuthLink>
* <AuthLink href="https://{yourDomain}/pem">PEM</AuthLink>
* <AuthLink href="https://{yourDomain}/rawpem">raw PEM</AuthLink>
* <AuthLink href="https://{yourDomain}/pb7">PB7</AuthLink>
* <AuthLink href="https://{yourDomain}/fingerprint">Fingerprint</AuthLink>

You can also retrieve this information for individual applications through the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. To do so, navigate to the **Settings** page for a specific application. Then, expand the **Advanced Settings** and choose the **Certificates** tab.

<Callout icon="file-lines">
  We use the application signing key to sign assertions that are sent to applications. These assertions may include ID tokens, access tokens, SAML assertions, and WS-Fed assertions. Note that these keys are different from those used to sign interactions with connections, including signing SAML requests to Identity Providers (IdPs) and encrypting responses from IdPs.

  By default, SAML assertions for IdP connections are signed, which we recommend. To get public keys you can use to configure the IdP, see [SAML Identity Provider Configuration: Signed Assertions](/docs/authenticate/protocols/saml/saml-identity-provider-configuration-settings).
</Callout>

The rotation and revocation process supports your personal preferences and promotes a graceful transition for your application. If you prefer to update your application first, then rotate and revoke your key, you may do that. Alternatively, if you prefer to rotate your key, and then update your application and revoke your old key, you may also do that.

Available keys include:

* **Currently used**: Key that is currently being used to sign all new assertions.
* **Previously used**: Key that was previously used, but has been rotated out. Assertions that were generated with this key will still work.
* **Next in queue**: Key that is queued and will replace the current key when the application signing key is next rotated.

<Callout icon="file-lines">
  Always test signing key rotation on a development tenant before rotating application signing keys in production.
</Callout>

## Limitations

Rotating your signing key will be subject to a smaller rate limit than other API endpoints. To learn more, read [Management API Rate Limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/management-api-endpoint-rate-limits).

## Learn more

* [Rotate Signing Keys](/docs/get-started/tenant-settings/signing-keys/rotate-signing-keys)
* [Revoke Signing Keys](/docs/get-started/tenant-settings/signing-keys/revoke-signing-keys)
* [View Signing Certificates](/docs/get-started/tenant-settings/signing-keys/view-signing-certificates)
* [Change Application Signing Algorithms](/docs/get-started/applications/change-application-signing-algorithms)


# Customer Provided Public Signing Keys
Source: https://auth0.com/docs/get-started/tenant-settings/signing-keys/customer-signing-keys

Learn how to import your own signing keys to use with Auth0.

<Warning>
  Customer Provided Signing Key is currently in Early Access. To learn more, read Product Release Stages. If you want to participate in Customer Provided Signing Keys, you must have an Enterprise plan. Contact your Technical Account Manager for more information.
</Warning>

Auth0 uses cryptographic keys to sign <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> to ensure that tokens are issued by Auth0. Auth0 signs the tokens with a private signing key and publishes the public key to the tenant’s “well-known” <Tooltip href="/docs/glossary?term=JSON+Web+Token">JSON Web Token</Tooltip> Key Set ([JWKS](/docs/secure/tokens/json-web-tokens/json-web-key-sets)) endpoint: `https://{yourDomain}/.well-known/``jwks.json`.

If you generate your own signing keys, you can import the public key to your tenant’s `/.well-known` JWKS endpoint. Auth0 can be the single distribution point for Auth0 signing keys and your custom signing keys. If your business case requires your application to be embedded in remote devices, you can migrate your existing signing keys for Auth0 to publish the public key to your `/.well-known` endpoint.

When access tokens with your custom signing keys are being issued as a result of a user authentication and <Tooltip href="/docs/glossary?term=authorization+flow">authorization flow</Tooltip>:

* Auth0's Key Management System is responsible for protecting the signing keys you generate and provide.
* Auth0 issues tokens for [authentication and authorization](/docs/get-started/identity-fundamentals/authentication-and-authorization) as the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>.
* Auth0 publishes a list of valid public keys at a distribution URL specific to the tenant.
* A proxy solution receives Auth0 issued tokens and makes them available to legacy applications and APIs.

  <Warning>
    Tokens signed by customer keys cannot be consumed by [Auth0 APIs](/docs/api).
  </Warning>
* Customer applications use the issued access tokens to consume APIs and resources.
* APIs and resources servers validate the signature of the access tokens presented to them by retrieving the public key from Auth0’s JWKS distribution to perform the token signature verification.

## How it works

<Frame>
  <img alt="" />
</Frame>

1. The public part of the signing key is imported to Auth0 and pend publication to Auth0 keys as an aggregated [JWKS](/docs/secure/tokens/json-web-tokens/json-web-key-sets).
2. The public signing key is published to the well-known endpoint of your tenant’s [custom domain](/docs/customize/custom-domains): `{yourCustomDomain}/.well-known/jwks.json`.
3. Auth0 issues access tokens. Those tokens are customized and re-signed with your signing key
4. Your application uses the customized tokens for access to your resources, such as APIs.
5. Auth0 distributes your key by publishing to the `/.wellknown` endpoint.

## Prerequisites

To import custom signing keys into Auth0, you must:

* Configure a <Tooltip href="/docs/glossary?term=Custom+Domain">Custom Domain</Tooltip>. The aggregated JWKS is served from a custom domain and is not available on the canonical domain. To learn more, read [Custom Domains.](/docs/customize/custom-domains)
* Use Auth0’s Private Cloud. You can only import signing keys in Private Cloud environments. To learn more, read about our Private Cloud on [AWS](/docs/deploy-monitor/deploy-private-cloud/private-cloud-on-aws) and [Azure](/docs/deploy-monitor/deploy-private-cloud/private-cloud-on-azure).

## Configure your custom keys with Management API

Use the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to upload your custom keys in the form of JWKS.

To create new (replace all existing) custom keys, make a `PUT` call to the [Create or replace custom signing keys](https://auth0.com/docs/api/management/v2/keys/put-custom-signing-keys) endpoint to import a set of custom public keys into Auth0. Existing custom keys will be replaced by the new set. You can import up to ten custom keys in JWKS format.

<Callout icon="file-lines">
  Once imported, the custom public keys prepend to the list of Auth0-generated keys and will be published to your tenant’s well known endpoint URL for distributing JWKS.
</Callout>

To get a list of existing custom keys, make a `GET` call to the [Get custom signing keys](https://auth0.com/docs/api/management/v2/keys/get-custom-signing-keys) endpoint to retrieve the set of custom keys as an array of JWK objects.

To delete existing custom keys, make a `DELETE` call to the [Delete custom keys](https://auth0.com/docs/api/management/v2/keys/delete-custom-signing-keys) endpoint to delete the custom keys.


# Revoke Signing Keys
Source: https://auth0.com/docs/get-started/tenant-settings/signing-keys/revoke-signing-keys

Learn how to revoke your tenant's application signing key using the Auth0 Dashboard or Management API.

You can revoke your tenant's application or API signing key using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. The signing key is used to sign <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip>, <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip>, <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> assertions, and <Tooltip href="/docs/glossary?term=WS-Fed">WS-Fed</Tooltip> assertions sent to your application or API. To learn more, read [Signing Keys](/docs/get-started/tenant-settings/signing-keys).

## Prerequisites

* Before you can revoke a previously-used signing key, you must first have rotated the key. To learn more, read [Rotate Signing Keys](/docs/get-started/tenant-settings/signing-keys/rotate-signing-keys), or see the **Rotate and revoke signing key** section below.
* Make sure you have updated your application or API with the new key before you revoke the previous key.

<Warning>
  You cannot reuse a signing key after revocation, so be sure that you want to revoke it.
</Warning>

## Use the Dashboard

### Revoke previously used signing key

1. Go to [Dashboard > Settings > Signing Keys](https://manage.auth0.com/#/tenant/signing_keys).
2. In the **List of Valid Keys** section, locate the **Previously Used** key, select the more options (**...**) menu, and select **Revoke Key**.
   The **List of Valid Keys** section lists the current signing key being used by your tenant, plus the next signing key that will be assigned should you choose to rotate your signing keys. If you have previously rotated signing keys, this section also lists the previously-used keys.
   The **List of Revoked Keys** section lists the last three revoked keys for your tenant.
3. Select **Revoke** to confirm.

### Rotate and revoke signing key

1. Go to [Dashboard > Settings > Signing Keys](https://manage.auth0.com/#/tenant/signing_keys).
2. In the **Rotation Settings** section, locate the **Rotate & Revoke Signing Key** section, and select **Rotate & Revoke Key**.
3. Select **Rotate & Revoke** to confirm.

## Use the Management API

<Warning>
  You can only revoke the previously used signing key.
</Warning>

1. To get a list of the signing keys, make a `GET` call to the [Get all Application Signing Keys](https://auth0.com/docs/api/management/v2#!/Keys/get_signing_keys) endpoint.
2. Make a `PUT` call to the [Revoke an Application Signing Key by its Key ID](https://auth0.com/docs/api/management/v2#!/Keys/put_signing_keys) endpoint. Be sure to replace the `{yourKeyId}` and `{yourMgmtApiAccessToken}` placeholder values with your signing key's ID and Management API access token, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
     curl --request PUT \
  --url 'https://{yourDomain}/api/v2/keys/signing/%7ByourKeyId%7D/revoke' \
  --header 'authorization: Bearer {yourMgmtApiAccessToken}'

  ```

  ```csharp C# theme={null}
     var client = new RestClient("https://{yourDomain}/api/v2/keys/signing/%7ByourKeyId%7D/revoke");
  var request = new RestRequest(Method.PUT);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  IRestResponse response = client.Execute(request);

  ```

  ```go Go theme={null}
     package main

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

  func main() {

     url := "https://{yourDomain}/api/v2/keys/signing/%7ByourKeyId%7D/revoke"

     req, _ := http.NewRequest("PUT", url, nil)

     req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

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

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

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

  }

  ```

  ```java Java theme={null}
     HttpResponse response = Unirest.put("https://{yourDomain}/api/v2/keys/signing/%7ByourKeyId%7D/revoke")
     .header("authorization", "Bearer {yourMgmtApiAccessToken}")
     .asString();

  ```

  ```javascript Node.JS theme={null}
     var axios = require("axios").default;

  var options = {
  method: 'PUT',
  url: 'https://{yourDomain}/api/v2/keys/signing/%7ByourKeyId%7D/revoke',
  headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'}
  };

  axios.request(options).then(function (response) {
  console.log(response.data);
  }).catch(function (error) {
  console.error(error);
  });

  ```

  ```objc Obj-C theme={null}
     #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/keys/signing/%7ByourKeyId%7D/revoke"]
                                                        cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"PUT"];
  [request setAllHTTPHeaderFields:headers];

  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];

  ```

  ```php PHP theme={null}
     $curl = curl_init();

  curl_setopt_array($curl, [
  CURLOPT_URL => "https://{yourDomain}/api/v2/keys/signing/%7ByourKeyId%7D/revoke",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_HTTPHEADER => [
     "authorization: Bearer {yourMgmtApiAccessToken}"
  ],
  ]);

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

  curl_close($curl);

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

  ```

  ```python Python theme={null}
     import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" }

  conn.request("PUT", "/{yourDomain}/api/v2/keys/signing/%7ByourKeyId%7D/revoke", headers=headers)

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

  print(data.decode("utf-8"))

  ```

  ```ruby Ruby theme={null}
     require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/keys/signing/%7ByourKeyId%7D/revoke")

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

  request = Net::HTTP::Put.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'

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

  ```

  ```swift Swift theme={null}
     import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/keys/signing/%7ByourKeyId%7D/revoke")! as URL,
                                         cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "PUT"
  request.allHTTPHeaderFields = headers

  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()

  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>YOUR\_KEY\_ID</code></td>
      <td>ID of the signing key to be revoked.  To learn how to find your signing key ID, see <a href="/docs/secure/tokens/json-web-tokens/locate-json-web-key-sets">Locate JSON Web Key Sets</a>.</td>
    </tr>

    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td><a href="https://auth0.com/docs/api/management/v2/tokens">Access Token for the Management API</a> with the scope <code>update:signing\_keys</code>.</td>
    </tr>
  </tbody>
</table>

## Learn more

* [Rotate Signing Keys](/docs/get-started/tenant-settings/signing-keys/rotate-signing-keys)
* [View Signing Certificates](/docs/get-started/tenant-settings/signing-keys/view-signing-certificates)
* [Change Application Signing Algorithms](/docs/get-started/applications/change-application-signing-algorithms)


# Rotate Signing Keys
Source: https://auth0.com/docs/get-started/tenant-settings/signing-keys/rotate-signing-keys

Learn how to rotate your tenant's application or API signing key using the Auth0 Dashboard or the Management API.

You can manually rotate a signing key periodically to change the JSON web key (JWK) key used by applications and APIs to validate tokens. If your application or API **does not** allow for this key change, and it attempts to use an expired signing key to verify a token, the authentication request will fail.

<Warning>
  Auth0 recommends that you execute signing key rotation on a development tenant first, then verify that your applications and APIs still work as expected. After you verify that everything is working properly, perform the same signing key rotation on your production tenant.
</Warning>

Although Auth0 signs with only one signing key at a time, your tenant's <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) discovery document always contains multiple keys. The OIDC discovery document will always include both the current key and the next key, and it may also include the previous key if the previous key has not yet been revoked. To provide a seamless experience in case of an emergency, your application should be able to use any of the keys specified in the document. To learn more about OpenID Connect discovery documents, read [Locate JSON Web Key Sets](/docs/secure/tokens/json-web-tokens/locate-json-web-key-sets).

<Warning>
  To allow you time to update your application with the new signing key, all tokens signed with the previous key will still be valid until you revoke the previous key. To learn more, read [Revoke Signing Keys](/docs/get-started/tenant-settings/signing-keys/revoke-signing-keys).
</Warning>

You can rotate your tenant's application signing key using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## Use the Dashboard

1. Go to [Dashboard > Settings > Signing Keys](https://manage.auth0.com/#/tenant/signing_keys).

   <Frame>
     <img alt="Dashboard Tenant Settings Signing Keys tab" />
   </Frame>
2. Under **Rotation Settings**, locate **Rotate Signing Key**, and select **Rotate Key**.
3. Click **Rotate** to confirm.

   <Frame>
     <img alt="Dashboard Settings Signing Keys Tab Rotate Confirm" />
   </Frame>

## Use the Management API

1. To get a list of the signing keys, make a `GET` call to the [Get all Application Signing Keys](https://auth0.com/docs/api/management/v2#!/Keys/get_signing_keys) endpoint.
2. To rotate the signing key, make a `POST` call to the [Rotate the Application Signing Key](https://auth0.com/docs/api/management/v2#!/Keys/post_signing_keys) endpoint. Be sure to replace the `MGMT_API_ACCESS_TOKEN` placeholder value with your Management API access token.

<AuthCodeGroup>
  ```bash cURL theme={null}
     curl --request POST \
  --url 'https://{yourDomain}/api/v2/keys/signing/rotate' \
  --header 'authorization: Bearer {yourMgmtApiAccessToken}'

  ```

  ```csharp C# theme={null}
     var client = new RestClient("https://{yourDomain}/api/v2/keys/signing/rotate");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  IRestResponse response = client.Execute(request);

  ```

  ```go Go theme={null}
     package main

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

  func main() {

     url := "https://{yourDomain}/api/v2/keys/signing/rotate"

     req, _ := http.NewRequest("POST", url, nil)

     req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

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

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

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

  }

  ```

  ```java Java theme={null}
     HttpResponse response = Unirest.post("https://{yourDomain}/api/v2/keys/signing/rotate")
     .header("authorization", "Bearer {yourMgmtApiAccessToken}")
     .asString();

  ```

  ```javascript Node.JS theme={null}
     var axios = require("axios").default;

  var options = {
  method: 'POST',
  url: 'https://{yourDomain}/api/v2/keys/signing/rotate',
  headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'}
  };

  axios.request(options).then(function (response) {
  console.log(response.data);
  }).catch(function (error) {
  console.error(error);
  });

  ```

  ```objc Obj-C theme={null}
     #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/keys/signing/rotate"]
                                                        cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [request setAllHTTPHeaderFields:headers];

  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];

  ```

  ```php PHP theme={null}
     $curl = curl_init();

  curl_setopt_array($curl, [
  CURLOPT_URL => "https://{yourDomain}/api/v2/keys/signing/rotate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
     "authorization: Bearer {yourMgmtApiAccessToken}"
  ],
  ]);

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

  curl_close($curl);

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

  ```

  ```python Python theme={null}
     import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" }

  conn.request("POST", "/{yourDomain}/api/v2/keys/signing/rotate", headers=headers)

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

  print(data.decode("utf-8"))

  ```

  ```ruby Ruby theme={null}
     require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/keys/signing/rotate")

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

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'

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

  ```

  ```swift Swift theme={null}
     import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/keys/signing/rotate")! as URL,
                                         cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  request.allHTTPHeaderFields = headers

  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()

  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th><strong>Value</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td><a href="https://auth0.com/docs/api/management/v2/tokens">Access Token for the Management API</a> with the scopes <code>create:signing\_keys</code> and <code>update:signing\_keys</code>.</td>
    </tr>
  </tbody>
</table>

## Key rotation impact

### APIs and API gateways accepting access tokens

Most middleware and API gateways leverage the JSON web key set (JWKS) endpoint to retrieve the current and future signing keys at a certain interval. If your middleware and/or API gateways **do not** support this endpoint and require you to manually configure a `*.cer` file, you will need to coordinate the signing key rotation in Auth0 with the reconfiguration of your middleware and gateways.

### Regular web applications

When rotating the signing key in Auth0, you will need to coordinate the reconfiguration of your applications which leverage <Tooltip href="/docs/glossary?term=WS-Fed">WS-Fed</Tooltip> or <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip>. This typically happens when you upload the new public certificate or reconfigure the application by entering the WS-Fed/SAML metadata URL. This will change the JWKS key, which is used by applications to validate tokens, make sure your implementation does not assume JWKS keys don’t change.

## Learn more

* [Revoke Signing Keys](/docs/get-started/tenant-settings/signing-keys/revoke-signing-keys)
* [Locate JSON Web Key Sets](/docs/secure/tokens/json-web-tokens/locate-json-web-key-sets)
* [Change Application Signing Algorithms](/docs/get-started/applications/change-application-signing-algorithms)
* [View Signing Certificates](/docs/get-started/tenant-settings/signing-keys/view-signing-certificates)


# View Signing Certificates
Source: https://auth0.com/docs/get-started/tenant-settings/signing-keys/view-signing-certificates

Describes how to view client secrets and signing keys using the Auth0 Dashboard or the Management API.

You can view your tenant's application <Tooltip href="/docs/glossary?term=client+secrets">client secrets</Tooltip> and signing keys using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. The application signing key is used to sign <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip>, <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip>, <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> assertions, and <Tooltip href="/docs/glossary?term=WS-Fed">WS-Fed</Tooltip> assertions sent to your application. These keys are different from those used to sign interactions with connections, including signing SAML requests to <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> (IdPs) and encrypting responses from IdPs. By default, SAML assertions for IdP connections are signed, which we recommend. To learn more, read [SAML Identity Provider Configuration Settings](/docs/authenticate/protocols/saml/saml-identity-provider-configuration-settings).

## Use the Dashboard

### Tenant settings

1. Go to [Dashboard > Settings > Signing Keys](https://manage.auth0.com/#/tenant/signing_keys).

   <Frame>
     <img alt="Dashboard Tenant Settings Signing Keys tab" />
   </Frame>
2. In the **Rotation Settings** section, locate **List of Valid Keys** and **List of Revoked Keys**.

   1. The **List of Valid Keys** section lists the current signing key being used by your tenant, plus the next signing key that will be assigned should you choose to rotate your signing keys. If you have previously rotated signing keys, this section also lists the previously-used keys.
   2. The **List of Revoked Keys** section lists the last three revoked keys for your tenant.

### Application settings

You can also view an application's signing key and/or client secret depending on the type of <Tooltip href="/docs/glossary?term=signing+algorithm">signing algorithm</Tooltip> you are using.

#### If using the RS256 signing algorithm

1. Go to [Dashboard > Applications](https://manage.auth0.com/#/applications), and select the name of the application to view.
2. Scroll to the bottom of the **Settings** tab, and select **Advanced Settings**.
3. Go to the **Certificates** tab and locate the **Signing Certificate** field.

   <Frame>
     <img alt="Dashboard Applications Advanced Settings Certificates tab" />
   </Frame>

#### If using the HS256 signing algorithm

1. Go to [Dashboard > Applications](https://manage.auth0.com/#/applications), and select the name of the application to view.
2. Under **Basic Information**, locate the **Client Secret** field for the client secret.

   <Frame>
     <img alt="Dashboard Applications Application Settings Tab Basic Information" />
   </Frame>

## Use the Management API

### Get all signing keys

Make a `GET` call to the [`/signing_keys/get_signing_keys`](https://auth0.com/docs/api/management/v2#!/signing_keys/get_signing_keys) endpoint. Be sure to replace the `{yourMgmtApiAccessToken}` placeholder value with your Management API Access Token.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
     --url 'https://{yourDomain}/api/v2/keys/signing' \
     --header 'authorization: Bearer {yourMgmtApiAccessToken}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/keys/signing");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/keys/signing"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.get("https://{yourDomain}/api/v2/keys/signing")
     .header("authorization", "Bearer {yourMgmtApiAccessToken}")
     .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/keys/signing',
    headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/keys/signing"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/keys/signing",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" }

  conn.request("GET", "/{yourDomain}/api/v2/keys/signing", headers=headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/keys/signing")

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

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/keys/signing")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td><a href="https://auth0.com/docs/api/management/v2/tokens">Access Token for the Management API</a> with the scope <code>read:signing\_keys</code>.</td>
    </tr>
  </tbody>
</table>

### Get a single signing key

Make a `GET` call to the [`/signing_keys/get_signing_key`](https://auth0.com/docs/api/management/v2#!/signing_keys/get_signing_key) endpoint. Be sure to replace the `{yourKeyId}` and `{yourMgmtApiAccessToken}` placeholder values with your signing key's ID and Management API Access Token, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
     --url 'https://{yourDomain}/api/v2/keys/signing/%7ByourKeyId%7D' \
     --header 'authorization: Bearer {yourMgmtApiAccessToken}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/keys/signing/%7ByourKeyId%7D");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/keys/signing/%7ByourKeyId%7D"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.get("https://{yourDomain}/api/v2/keys/signing/%7ByourKeyId%7D")
     .header("authorization", "Bearer {yourMgmtApiAccessToken}")
     .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/keys/signing/%7ByourKeyId%7D',
    headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/keys/signing/%7ByourKeyId%7D"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/keys/signing/%7ByourKeyId%7D",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" }

  conn.request("GET", "/{yourDomain}/api/v2/keys/signing/%7ByourKeyId%7D", headers=headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/keys/signing/%7ByourKeyId%7D")

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

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/keys/signing/%7ByourKeyId%7D")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>YOUR\_KEY\_ID</code></td>
      <td>ID of the signing key to be viewed. To learn how to find your signing key ID, see <a href="/docs/secure/tokens/json-web-tokens/locate-json-web-key-sets">Locate JSON Web Key Sets</a>.</td>
    </tr>

    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td><a href="https://auth0.com/docs/api/management/v2/tokens">Access Token for the Management API</a> with the scope <code>read:signing\_keys</code>.</td>
    </tr>
  </tbody>
</table>

## Learn more

* [Revoke Signing Keys](/docs/get-started/tenant-settings/signing-keys/revoke-signing-keys)
* [Rotate Signing Keys](/docs/get-started/tenant-settings/signing-keys/rotate-signing-keys)
* [Signing Algorithms](/docs/get-started/applications/signing-algorithms)
* [Change Application Signing Algorithms](/docs/get-started/applications/change-application-signing-algorithms)


# null
Source: https://auth0.com/docs/index



<BgImage />

<DocsBanner />

<DocsFeatureCards />

<LanguageGrid />

<ProductGrid />

<LearnBasicsGrid />

<Footer />


# Architecture Scenarios
Source: https://auth0.com/docs/get-started/architecture-scenarios

Learn about common Auth0 architecture scenarios that you can use to solve your authorization and authentication needs.

Customers using Auth0 typically have a common set of goals and objectives, and we want to share our real-world customer implementation experiences to help you deliver your solution efficiently.

## Business use cases and planning guides

These planning guides provide strategies for successfully integrating with Auth0 using a phased approach across multiple workstreams.

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong></th>
      <th><strong>Download...</strong>                     </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/business-to-consumer">Business to Consumer</a></td>
      <td>How to build, configure, and deploy your B2C environment for identity and access management.</td>
      <td><a href="https://assets.ctfassets.net/cdy7uua7fh8z/3er1aEQ7Ul0q3c9leJWczR/b1f18b4c16abb7e78b01e4eb2b52bb8e/B2C_Project_Planning.pdf">B2C Planning Guide</a></td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/business-to-business">Business to Business</a></td>
      <td>How to build, configure, and deploy your B2B environment for identity and access management.</td>
      <td><a href="https://assets.ctfassets.net/cdy7uua7fh8z/63F0WOPJdVzsPMxV1Xvp8x/7a329487c5e890d8e820f6a48983b46a/B2B_Project_Planning.pdf">B2B Planning Guide</a></td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/b2e">Business to Employee</a></td>
      <td>How to build, configure, and deploy your B2E environment for identity and access management.</td>
      <td>The <a href="https://assets.ctfassets.net/cdy7uua7fh8z/63F0WOPJdVzsPMxV1Xvp8x/7a329487c5e890d8e820f6a48983b46a/B2B_Project_Planning.pdf">B2B Planning Guide</a> applies in this case too.</td>
    </tr>
  </tbody>
</table>

## Application architecture scenarios

These scenarios describe the different types of technology architectures your application may use and how Auth0 can help. The goal of these scenarios is to walk you through the implementation process from beginning to end.

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/multiple-organization-architecture">Multiple Organizations</a></td>
      <td>How to configure an application architecture that uses either single identity provider organizations or multiple identity provider organizations.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/sso-for-regular-web-apps">Single Sign-On for Regular Web Apps</a></td>
      <td>How to configure and implement a web application that uses SSO for  employees using Active Directory and contractors using a separate user store.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/server-application-api">Server Application + API</a></td>
      <td>How to configure a timesheet API using a cron job to log timesheet entries.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/spa-api">Single Page Application + API</a></td>
      <td>How to configure a timesheet API using a single-page application to log timesheet entries.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/mobile-api">Mobile Application + API</a></td>
      <td>How to configure a timesheet API using a mobile application to log timesheet entries in a centralized database.</td>
    </tr>
  </tbody>
</table>

## Implementation checklists and resources

We provide downloadable spreadsheet checklists that include tasks for each phase of your software development lifecycle (SDLC) project. We also provide other resources to help to get started quickly, test sample code, and try APIs.

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/checklists">Implementation Checklists</a></td>
      <td>How to plan for tasks associated with each phase in your SDLC project.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/implementation-resources">Implementation Resources</a></td>
      <td>About the resources Auth0 provides to help you get started including videos, terminology, white papers, blog posts, quickstarts, APIs, SDKs, the Auth0 Community forum, and our Auth0 Support Center.</td>
    </tr>
  </tbody>
</table>


# Business to Employees
Source: https://auth0.com/docs/get-started/architecture-scenarios/b2e

Explains the architecture scenario of B2E with a large organization that wants to extend their existing enterprise directory service.

The B2E (Business to Employees) scenario involves applications that are used by employee users. These are applications that are targeted toward users who are typically acting on behalf of an organization such as an employer, a university, or a group in which they are a member, as opposed to acting on their own behalf.

Such applications that are custom written by the organization may use the OIDC/<Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> protocol to externalize authentication whereas those that have been purchased will often use the <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> protocol. In either case, the enterprise will typically want to use some form of Enterprise connection, such as a SAML <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip>, ADFS, Google Workspace, Azure AD or a directory service such as AD or OpenLDAP, and less frequently, a custom DB, for authentication of enterprise users.

For a business that is creating or integrating applications with Auth0 for a B2E environment, there are several requirements that are common for this scenario. This guide will summarize the most common requirements for B2E applications and explain the Auth0 features which help meet each need.

## Enterprise providers

Most businesses already have a corporate identity repository which has information on all the employee users and user profile information. It may also contain information on partners and contractors. A common requirement for the B2E scenario therefore, is to allow such users to log in via [Auth0 Enterprise connections](/docs/authenticate/identity-providers/enterprise-identity-providers) such as SAML2 providers, ADFS, Google Workspace, Azure AD or an on-premise corporate directory service. This is attractive to users because it allows them to avoid creating yet another username and password for each application and instead leverage the same login credential across all their enterprise applications.

This is especially attractive to security interests within the company because user credentials are only exposed to the identity stack instead of to each application. Furthermore, this architecture allows the business to retain control over access to applications because the enterprise identity provider provides a single shutoff point. If a user leaves the organization, administrators can simply disable the user’s account in the corporate identity provider and the user can no longer log in to any of the applications using that identity provider.

Auth0 makes it easy to enable login via a wide variety of enterprise providers with just a few simple configuration steps.

## Groups and roles

With a lot of users, you may set up groups and roles to manage access and privileges. Often, these are stored and administered in a directory service.

Auth0 can get user attributes, like groups and roles, from a directory service or enterprise identity provider during authentication. You can then make the attributes available through tokens returned to the application or with the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## Profile translation

Sometimes a directory or identity provider returns attributes in one format, but your application uses another format. Using Auth0's [Rules](/docs/manage-users/user-accounts/metadata/manage-metadata-rules), you can [map and translate user profile attributes](https://auth0.com/rules/saml-attribute-mapping). You can even translate between OIDC/OAuth, SAML, <Tooltip href="/docs/glossary?term=WS-Fed">WS-Fed</Tooltip>, and LDAP.

For example, you retrieve attributes in SAML assertion format from a SAML Identity Provider. With a rule you can then translate the attributes to custom claims in an <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip> for an OIDC/OAuth application.

You can also map SAML attributes to the Auth0 user profile from the dashboard. To do this, go to [Connections > Enterprise > SAMLP Identity Provider](https://manage.auth0.com/#/connections/enterprise), select your SAML connection, and set your attribute mappings in the **Mappings** tab.

## Extensibility with augmented user profiles

You may want to enrich user profiles with attributes or data retrieved from other services. For example, you might receive an address or phone number and wish to translate that into a geographic region. [Auth0 Rules](/docs/customize/rules) enable you to write small snippets of code that execute during the authentication transaction. This lets you execute logic or call other services for user information, then add [user metadata](/docs/manage-users/user-accounts/metadata) to the Auth0 user profile and optionally the resulting tokens sent to your applications.

## Single Sign-on

If you have several internal applications, you can set up [Single Sign-on (SSO)](/docs/authenticate/single-sign-on) across them so users only have to log in once.

Auth0 supports integration with applications that externalize authentication using industry standard identity protocols:

* OIDC/OAuth
* SAML2
* WS-Fed

After some configuration, all your applications can leverage your enterprise identity provider. In this setup, Auth0 is the broker between your applications and enterprise identity providers.

Now when a user signs in to one application, they can access other applications integrated with Auth0 without having to log in again. This will be true until their <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> session expires. You should configure the SSO session length within Auth0 to meet security policies.

## Single Sign-on integrations

You can also integrate purchased applications with Auth0 for Single Sign-on (SSO). Auth0 provides [pre-built integrations](/docs/customize/integrations/sso-integrations) for applications such as:

* Salesforce
* Zendesk
* Slack
* New Relic

## Branding

Branding is an important part of any application. Your logo, colors and styles should be consistent in all parts of the application. You can [customize](/docs/libraries/custom-signup) the login, signup, and error pages displayed by Auth0 so it matches your application. Add your own logo, text, and colors. There's also I18N/L10N support for global rollouts. [Emails for verification or password resets](/docs/customize/email/email-templates) are customizable too.

[Login screens](/docs/libraries/lock/lock-ui-customization) should appear to come from your application’s branded domain name. To maintain consistency, you can define a [custom domain name](/docs/customize/custom-domains) for the login screen displayed by Auth0.

## Multi-factor authentication

Internal or employee applications often deal with sensitive content. [Multi-factor authentication (MFA)](/docs/secure/multi-factor-authentication) helps protect your data and applications. Auth0 provides a variety of ways to implement <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip>. And for more flexibility, you can use Rules to turn it on only for the applications or user groups that need it.

## Logs export

Need to analyze logs or store them long-term? Auth0 provides extensions to [export logs to external tools](/docs/deploy-monitor/logs) for analysis and retention. You can also retrieve log data with the Management API.

## Audit

Companies have many uses for logs data, one of which is audit reports. Auth0 captures a variety of data in log files, which may be useful for your audit reporting. The logs have information on authenticated users, the identity provider used, and when significant administrative changes are made in the <Tooltip href="/docs/glossary?term=Auth0+dashboard">Auth0 dashboard</Tooltip>.

Log events each have an event type. You can use event types as filters when querying log data with the Management API, or when exporting logs to log analysis tools.

## Monitoring

Monitoring the infrastructure and services that your applications depend on is critical. Auth0 provides an [Auth0 Status](https://status.auth0.com/) page you can subscribe to.

Auth0 makes every effort to minimize outages, but if there is any disruption to service, it will appear on the status page. To support requirements for root cause analysis documentation after a disruption, Auth0 conducts internal analysis and publishes the results on the disruption notice when the analysis is completed.

## Attack Protection

An unfortunate part of modern life on the internet is hackers. Hackers are constantly trying to find a way into applications. For example, they may try to log in using common passwords. Or they may use credentials stolen from elsewhere, hoping that users re-used the same passwords at other sites.

Auth0's [Attack Protection](/docs/secure/attack-protection) detects these situations for Auth0 Database connections and provides options for how to respond. Turn on <Tooltip href="/docs/glossary?term=Attack+Protection">Attack Protection</Tooltip> and configure the response options so you can respond appropriately if such an event occurs.

## Github Deployment

Do you manage a lot of your application code in Github? You can deploy code for Actions, Rules, Hooks, or custom database access from there with Auth0's [Github Deployment extension](https://marketplace.auth0.com/integrations/github-actions).

If you have a full continuous integration/continuous deployment pipeline, use the [Auth0 Deploy CLI tool](https://github.com/auth0/auth0-deploy-cli) for greater flexibility.


# Business to Business
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-business

Explains the architecture scenario B2B IAM with a SAAS application.

This guidance is relevant to **all** project stakeholders. We recommend reading it in its entirety at least once, even if you've already started your journey with Auth0. We provide a Project Planning Guide in PDF format, details about how to get started with each phase of the implementation process, and checklists to help you manage the tasks in each phase.

There are many different ways Auth0 can be integrated into the B2B IAM project architecture. Auth0's flexibility comprehensively supports many different use cases however your project may not require all of the capabilities provided by Auth0. Knowing what, when, and how best to implement something will help you focus on completing the necessary tasks at the right time.

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2B IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/63F0WOPJdVzsPMxV1Xvp8x/7a329487c5e890d8e820f6a48983b46a/B2B_Project_Planning.pdf)

## Multiple Organization Architecture (Multitenancy)

Many B2B platforms implement some form of isolation and/or branding for their customers' organization, and this can add complexity to any Identity and Access Management (IAM) system. If this applies to you, then we recommend you take some time to read through our guidance and best practice advice for this type of environment.

[Multiple Organization Architecture](/docs/get-started/architecture-scenarios/multiple-organization-architecture)

## Get started

Customers using Auth0 for Business-to-Business (B2B) projects typically share a common set of goals and objectives, and in the sections that follow we'll focus on our real-world customer implementation experiences to help you deliver your solution efficiently.

<Card title="Best practice">
  Auth0 provides recommendations and best practice suggestions in an ad hoc way throughout this guide in panels like this one. You can also obtain detailed guidance regarding specific functionality by speaking with your account representative or a member of our Auth0 [Professional Services](/docs/get-started/professional-services) team.
</Card>

<table>
  <thead>
    <tr>
      <th><strong>Read</strong></th>
      <th><strong>To learn...</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/business-to-business/architecture">Architecture</a></td>
      <td>How to configure your Auth0 tenant architecture affects your B2B IAM implementation.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/business-to-business/provisioning">Provisioning</a></td>
      <td>About user provisioning functionality and considerations for your B2B IAM implementation.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/business-to-business/authentication">Authentication</a></td>
      <td>How authentication works in your B2B IAM implementation.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/business-to-business/branding">Branding</a></td>
      <td>How to configure Auth0 items to reflect your brand and desired user experience.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/business-to-business/deployment">Deployment Automation</a></td>
      <td>How Auth0 tooling helps to automate tenant deployment.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/business-to-business/quality-assurance">Quality Assurance</a></td>
      <td>About quality assurance considerations for your B2B IAM implementations.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/business-to-business/profile-management">Profile Management</a></td>
      <td>About user profile management planning considerations for your B2B IAM implementation.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/business-to-business/authorization">Authorization</a></td>
      <td>About user authorization and related planning considerations for your B2B IAM implementation.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/business-to-business/logout">Logout</a></td>
      <td>About user logout planning considerations for your B2B IAM implementation.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/business-to-business/operations">Operations</a></td>
      <td>How to operationalize your Auth0 tenant environments.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/business-to-business/launch">Launch Preparation</a></td>
      <td>About launch preparation considerations for your B2B IAM implementation.</td>
    </tr>
  </tbody>
</table>

## Implementation planning checklists

Use the links below to download a spreadsheet that includes tasks for each phase of a Software Development Lifecycle (SDLC) project.

[Analyze Checklist](https://cdn2.auth0.com/docs/media/articles/architecture-scenarios/checklists/Analyze-Checklist.xlsx)

[Design Checklist](https://cdn2.auth0.com/docs/media/articles/architecture-scenarios/checklists/Design-Checklist.xlsx)

[Build Checklist](https://cdn2.auth0.com/docs/media/articles/architecture-scenarios/checklists/Build-Checklist.xlsx)

[Test Checklist](https://cdn2.auth0.com/docs/media/articles/architecture-scenarios/checklists/Test-Checklist.xlsx)

[Deploy Checklist](https://cdn2.auth0.com/docs/media/articles/architecture-scenarios/checklists/Deploy-Checklist.xlsx)

[Monitor Checklist](https://cdn2.auth0.com/docs/media/articles/architecture-scenarios/checklists/Monitor-Checklist.xlsx)


# Architecture (B2B)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-business/architecture

How you configure your Auth0 tenant architecture affects your B2B IAM implementation.

Understanding your application is key to understanding how Auth0 can be leveraged to meet your needs. From experience, our most successful customers start with a visualization of their proposed - or in many cases existing - architecture and use this as a basis for reference as they progress. Understanding where your application fits within your organization is also important; Auth0 [Accounts and Tenants](/docs/get-started/auth0-overview/create-tenants) form the basis for the grouping and structuring of Auth0 assets, and it may be that you’ll need to leverage an existing Auth0 deployment in order to integrate with [Single Sign-on (SSO)](/docs/authenticate/single-sign-on), centralized user [Profile Management](/docs/get-started/architecture-scenarios/business-to-business/profile-management), consolidated billing, or the like.

<Info>
  ### Best Practice

  If you do have multiple applications, and you need to leverage SSO, then we recommend you check out our [How to Implement Single Sign-On](https://auth0.com/learn/how-to-implement-single-sign-on/) training guidance before continuing.
</Info>

The value of investing time on the landscape of the architecture up-front is something that we have found pays dividends in the long run, and there are a number of things you will want to consider when looking at functionality and workflow:

* What should the URL look like when Auth0 needs to present a web page to a user?
* How can Auth0 be structured to support your SDLC (Software Development Lifecycle)?
* How can you ensure that your Auth0 tenants are appropriately associated with your contract?
* What do you need to consider if there are other projects in your organization integrating with Auth0? Particularly projects that target their own, or a different domain of users (for example, applications that only employees will use)?
* How can you align the structure and domain of your customers’ organization with your Auth0 deployment?

Organizations often service more than one domain of user - customers, employees, and affiliates being the most frequently encountered, with typically little to no cross-over: employees, say, don’t use the same applications as customers and vice-versa. In some cases there can also be a need to partition further within a domain - separate groups of customers, say, who use different and unconnected products. Auth0 provides a way to segregate your users and the associated collateral, and [tenant provision](#tenant-provision) covers this in more detail. If you need to provision an independent tenant then you’ll also want to [associate this with your existing Auth0 account](#tenant-association), so that you can take full advantage of the benefits provided at your organization’s contracted subscription level.

<Info>
  ### Best Practice

  It’s not uncommon for companies to have identity requirements that address multiple user communities: customers, partners, employees, etc. So be sure to consider other projects or future requirements when designing your architecture.
</Info>

In addition, you’ll undoubtedly have an established set of processes and procedures as part of your Software Development Lifecycle (SDLC). So you’ll want to check out our [SDLC support](#sdlc-support) guidance regarding Auth0 Tenant provision in support of that too.

For customer-facing applications, we typically see [OpenID Connect (OIDC)](/docs/authenticate/protocols/openid-connect-protocol) as being the most frequently used protocol. OIDC makes use of web based workflows with browser URLs that are presented to the user. Out-of-the-box, client facing URLs as part of Auth0 OIDC support are Auth0 branded, however we recommend using the Auth0 [custom domain](#custom-domains) capability to provide for consistent corporate identity and to also address potential user confidence concerns before they arise.

<Info>
  ### Best Practice

  Other groups within your organization may also be working with Auth0; it’s not uncommon for our customers to have disparate departments that serve different user communities. Identifying these will potentially influence your design choices, and doing so early could mitigate decisions that might prove costly later on.
</Info>

If some or all of your customer organizations each need their own custom URL or they are using social providers that need a custom consent page branded to the organization, then we recommend that you create separate Auth0 tenants for those organizations; see [Tenant provision for complex organizations](#tenant-provision-for-complex-organizations) for further details.

## Tenant provision

Everything starts with an Auth0 tenant. This is where you will be configuring your use of Auth0, and the where Auth0 assets - such as [Applications](/docs/get-started/applications), [Connections](/docs/authenticate/identity-providers) and [user profiles](/docs/get-started/architecture-scenarios/business-to-business/profile-management) are defined, managed and stored. Access to an Auth0 tenant is performed via the Auth0 [Dashboard](/docs/get-started/auth0-overview/dashboard), and via the Dashboard you can also create additional, associated tenants; you’re allowed to create more than one Auth0 tenant so that you can structure your tenants in a way that will isolate different domains of users and also support your [Software Development Life Cycle](#sdlc-support) (SDLC).

<Warning>
  Tenant names cannot be changed, nor reused once deleted. So, make sure you're happy with your name(s) before you create your Auth0 tenants.
</Warning>

Determining the level of isolation you require when it comes to your user domains is an important step, and together with your branding requirements will subsequently help you determine the number of Auth0 tenants that will be required in your production environment. As we recommend you create a full suite of [SDLC supporting tenants](#sdlc-support) for every Auth0 tenant you will run in a production environment, the number of Auth0 tenants you will need to manage can quickly grow. Therefore you should consider carefully before creating multiple Auth0 tenants for production, and should consult our guidance on [Branding](/docs/get-started/architecture-scenarios/business-to-business/branding) before making your final decision.

### Tenant provision for complex organizations

In most cases, provisioning separate Auth0 tenants for your customer's organizations is not necessary. This has become even easier with the release of our new [Organizations feature](/docs/manage-users/organizations/organizations-overview). However, in certain circumstances this can be something that is valuable for reducing the complexity of your setup. For instance, we recommend provisioning a separate Auth0 tenant for your customers' organization as a best practice if:

* Your customer organizations need a custom login URL that is unique to the organization. This is generally the case only if you allow your organizations to have their own vanity URL instead of using a common login URL. Auth0 supports one <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip> per tenant.
* Your customer organizations use social providers for login. In this case, it is often desirable for the organization to have a custom consent page for the social provider that is branded to their organization.

If either of these situations is true, we recommend creating a separate Auth0 tenant for each organization that has one of the above criteria.

<Warning>
  Maintaining multiple Auth0 tenants can add complexity to your system and should not be done unless absolutely necessary.
</Warning>

## Tenant association

To ensure that your [tenants are all associated with your Auth0 contractual agreement](/docs/get-started/auth0-overview/create-tenants/child-tenants) and have the same features, ensure all your tenants are associated with your company account. If you have individual developers that want to create their own sandboxes for testing, make sure they get associated with your account so they have the same permissions too. To do this you should contact your Auth0 representative or the [Auth0 Support Center](https://support.auth0.com).

## Custom domains

When you setup your Auth0 tenant, the URL for accessing that tenant will be of the form `https://{yourTenant}.auth0.com`. Providing a [Custom Domain](/docs/customize/custom-domains) (also known as a vanity URL), for your Auth0 tenant is not only an important factor for supporting your Branding requirements, but more importantly will also provide you with security benefits too:

* Some browsers will, by default, make it [difficult to communicate in an iFrame if you don't have a shared domain](/docs/troubleshoot/authentication-issues/renew-tokens-when-using-safari).
* It's [harder to phish your domain if you have a vanity URL](https://auth0.com/blog/introducing-custom-domains-preview-with-auth0/), as the phisher must also create a vanity URL to mimic yours. For example, with a custom domain you can use your own certificate to get an "Extended Validation", making phishing even harder.

<Callout icon="file-lines">
  You are allowed only one custom domain per Auth0 Tenant. This is because a tenant in Auth0 is intended to represent a “domain” of users. If you need more than one vanity URL, then you likely have more than one domain of users and should be using multiple tenants.
</Callout>

Your custom domain name should also give the user confidence that this is the appropriate place to enter their credentials, and we recommend that you create your custom domain in all environments early on to ensure that you are testing consistently between environments. **It's extremely important to train your users to to look for suspicious URLs when entering their credentials!**

<Info>
  ### Best Practice

  Create a custom domain (a.k.a. `CNAME`) for your Auth0 tenant, and also create one in development too so you can ensure you have managed the `CNAME` correctly. For example, you could create a `CNAME` which maps `login.mycompany.com` to `mycompany-prod.auth0.com`.
</Info>

In almost all cases, customers have been most successful when adopting a strategy of a centralised domain for authentication across multiple product or service brands. This strategy provides users with a consistent UX, and also mitigates the complexity of deploying and maintaining multiple Auth0 tenants in a production environment. If you are considering having multiple domains for different brands, please refer to the [Branding](/docs/get-started/architecture-scenarios/business-to-business/branding) guidance before you begin implementing.

## SDLC support

Every company has some form of Software Development Life Cycle (SDLC), and throughout the development process you will want to align with that strategy. For instance, you need to be able to test your integration with Auth0 in a similar fashion as you test the applications themselves. It is therefore important to [structure Auth0 tenants to support your SDLC](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments), and there is a consistent pattern which our customers typically follow when it comes to the best practices associated with tenant layout for doing so:

<table>
  <thead>
    <tr>
      <th>Environment</th>
      <th>Sample Tenant Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Development</td>
      <td><strong>company-dev</strong></td>
      <td>A shared environment where most of your development work occurs</td>
    </tr>

    <tr>
      <td>QA/Testing</td>
      <td><strong>company-qa</strong> or <strong>company-uat</strong></td>
      <td>An environment for formal testing of the changes you've made</td>
    </tr>

    <tr>
      <td>Production</td>
      <td><strong>company-prod</strong></td>
      <td>The production tenant</td>
    </tr>
  </tbody>
</table>

In some cases you may also want to create one or more sandboxes (e.g., **company-sandbox1**, **company-sandbox2**) so that you can test changes without compromising your development environment. This might be where you test deployment scripts and the like.

<Info>
  ### Best Practice

  You can also take advantage of our [Implementation Checklists](/docs/get-started/architecture-scenarios/checklists) that you can download and customize to meet your implementation project needs.
</Info>

<Callout icon="file-lines">
  Customers with an Enterprise subscription should ensure tenants set up to support their SDLC are properly [linked to their subscription](/docs/get-started/auth0-overview/create-tenants/child-tenants). This will ensure each tenant has a consistent set of features enabled.
</Callout>

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2B IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/63F0WOPJdVzsPMxV1Xvp8x/7a329487c5e890d8e820f6a48983b46a/B2B_Project_Planning.pdf)

## Multiple Organization Architecture (Multitenancy)

Many B2B platforms implement some form of isolation and/or branding for their customers' organization, and this can add complexity to any Identity and Access Management (IAM) system. If this applies to you, then we recommend you take some time to read through our guidance and best practice advice for this type of environment.

[Multiple Organization Architecture](/docs/get-started/architecture-scenarios/multiple-organization-architecture)


# Authentication (B2B)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-business/authentication

How authentication works in your B2B IAM implementation.

In order to provide services to your users, you must be able to identify who those users are. This process is called User Authentication. There are a number of ways to perform authentication of a user - via social media accounts, username and password, <Tooltip href="/docs/glossary?term=passwordless">passwordless</Tooltip> - and it's often recommended that you go beyond a first factor for authenticating the user by enabling <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA).

<Info>
  ### Best Practice

  It's important to consider both security and user experience when designing how you will authenticate your users. Providing for multiple primary factors, and/or enforcing more than one factor during authentication, are ways that you can provide both.
</Info>

There are a number of things you will want to consider when looking at functionality and workflow:

* Where will users enter their credentials?
* How will you keep user credentials safe?
* How will you maintain your authentication system?
* How can you provide password authentication for your users?
* How can you prevent hackers from trying to log in as your users?
* How will you implement authentication in different kinds of applications?
* How can you make login easy for your users when they come from different language backgrounds?
* How will you provide a good user experience as you migrate away from any legacy authentication system?
* What should you consider when integrating applications with Auth0?
* Do you need to provide multi-factor authentication?
* What do you do if you have a service that doesn't have a way for the user to log in ahead of time?
* Can you pass the same user <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> from one API to another?
* What do you do if you need to isolate users by organization?
* How will you handle identifying which organization users belong to?
* What’s the benefit of providing enterprise connections for your organizations?

Auth0 [Universal Login](#universal-login) provides users with a safe and secure experience - no matter whether you choose to provide for user ID/password credentials sign in, or allow the so-called Bring Your Own Identity scenarios provided via [Social Login](https://auth0.com/learn/social-login/). There are also brand recognition benefits to centralizing the login experience with <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>, even if you feel you will also have product-specific [branding](/docs/get-started/architecture-scenarios/business-to-consumer/branding) requirements. The Auth0 UI widgets typically used with Universal Login also provide out-of-the-box support with regards to [internationalization](/docs/customize/internationalization-and-localization/universal-login-internationalization) for users with different language requirements, and out-of-the-box support for Auth0 features such as [MFA](#multi-factor-authentication-mfa-) and [attack protection](#anomaly-detection) allow you to put barriers in place in order to prevent hackers attempting to access users' accounts.

Allowing users to sign in via user ID/password credentials means that you're not reliant on the status of third-party <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> for your users to access your system. You also have the means to require the credentials used to align with your corporate policies. Auth0 assists with this by providing you with multiple options in support of user ID/password logins, and the [guidance provided](#username-and-password-authentication) will help you understand you can leverage these options. Adding [social](#social-authentication) support at some stage, as an additional primary authentication factor, gives you added flexibility and can help you better understand your users without the need to question them further by leveraging the information already stored by the various social login [providers](/docs/authenticate/identity-providers/social-identity-providers).

If you have an existing legacy identity store, you’ll also want to see [User Migration](/docs/get-started/architecture-scenarios/business-to-consumer/provisioning). This section discusses the advantages of migrating to Auth0’s managed identity storage in terms of safety and security.

For customer facing applications, <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect ([OIDC](/docs/authenticate/protocols/openid-connect-protocol)) is the most frequently used industry standard protocol, and OIDC has first-class citizen support in Auth0. Auth0 provides support for various different approaches for integrating various different applications, so you'll want to see the section on [application integration](#application-integration) for the information you'll need to make an informed choice.

When calling one API from another API, or from any situation where there is no authenticated user context - such as one or more cron jobs, report generators, or continuous integration/delivery systems - you will need a way to authorize the application instead of a user. This is a one step process where the application is authenticated (using a <Tooltip href="/docs/glossary?term=client+ID">client ID</Tooltip> and secret) and then authorized in one call. You can learn more about this in our authorization work stream under [machine-to-machine (m2m) authorization](/docs/get-started/architecture-scenarios/business-to-business/authorization).

Often companies need to segregate their users by organization and sometimes users can have access to more than one organization. Knowing which of these scenarios is relevant to your company will help define how to determine in which connection a user exists: whether you need to do it, when you need to do it, and how to accomplish it. See [Home Realm Discovery](#home-realm-discovery) to determine if this is something relevant to your company.

## Universal Login

Do you have, or will you have, more than one application in your system? If the answer to this question is yes, then you will want a centralized sign in experience. To achieve a seamless <Tooltip href="/docs/glossary?term=Single+Sign-on">Single Sign-on</Tooltip> (SSO) experience between multiple applications, it is critical to have a centralized location to redirect your users for authentication. This allows you a way to provide your users with a consistent experience if you add social authentication in the future, add third party applications to your system, or add multi-factor authentication as an option (or requirement) for your users - and also allow you to take advantage of new features for improving your users’ experience with little, if any, added development effort.

<Info>
  ### Best Practice

  If you have more than one application, the best practice is to redirect to a [centralized location](/docs/authenticate/login/auth0-universal-login) to authenticate the user. With Auth0, this means taking advantage of [Universal Login](/docs/authenticate/login/auth0-universal-login), which provides many security and user experience benefits out-of-the-box, including [SSO](/docs/authenticate/single-sign-on).
</Info>

Auth0 Universal Login makes authenticating users a short, easy process which can be accomplished in three easy steps (all of our Quickstarts demonstrate this and our SDKs hide the complexity for you too):

1. Determine how and when you want to [redirect from your application](#application-integration).
2. Set up the appropriate [branding](/docs/get-started/architecture-scenarios/business-to-consumer/branding) and/or customized HTML in your Auth0 configuration.
3. Set up your application to [receive and handle the response](#application-integration) from the Authorization Server.

## Home realm discovery

Home realm discovery (HRD) is the process of identifying which identity provider (or which connection in Auth0) the user belongs to before authenticating them. There are two ways HRD can occur:

* Provide a way for the decision to be made at the application
* Have Home Realm Discovery happen on the Universal Login page

Your system may need to do either or both methods so it is important to understand all approaches to HRD so that you can apply the one(s) that make the most sense to your applications.

### Application driven HRD

A common way of determining which realm a user belongs to is when an application is branded for each organization. As part of this, an organization will typically have its own instance of the application, typically accessed via a different URL. This copy or instance can be physically isolated (running on a separate set of servers) or virtually isolated (running on shared servers) and is generally denoted through either a custom hostname (`companyA.application1.yourcompany.com`) or path (`application1.yourcompany.com/companyA`).

<Info>
  ### Best practice

  If your application already knows the specific connection (IdP) required then you can also pass that along when you redirect the user to `/authorize`, via use of the `connection` query parameter.
</Info>

If this is the case for your application(s), then home realm discovery is a simple matter of storing the `org_id` with the organization-specific application configuration and sending that as the organization parameter when redirecting the user to Universal Login. Doing so will limit the user to that specific organization and its set of configured connections.

<Info>
  ### Best practice

  If an organization needs more than one IdP, then you may have to do a second round of Home Realm Discovery (once the organization has been identified). Auth0 will typically manage this for you if you are using the Organizations Feature.
</Info>

If the user is shared between multiple organizations using a single identity, you must support [Home Realm Discovery on the Universal Login Page](#hrd-through-universal-login). This will allow Universal Login to identify the user first and then present the realms appropriate for that user leading to a better user experience.

Sending the organization and/or connection parameters can be achieved by adding them as a query parameter when you redirect the user to the `/authorize` endpoint. For more information, see the [Authentication API docs](https://auth0.com/docs/api/authentication#authorization-code-flow). However, you will generally accomplish this using the SDK for whichever language your application is written in.

### HRD through Universal Login

There are three main approaches to Home Realm Discovery:

* Discover the realm through the user’s email subdomain.
* Discover the realm by looking up a user identifier in some sort of map of an identifier to realm map.
* Allow the user to choose or enter their realm (or organization).

In both of the first two approaches, you may consider doing “Identifier First Login”. This means that you present only the ability to enter an identifier first. After which, you collect the user’s identifier, and then, based on the identifier, you either automatically redirect the user or present a way for the user to enter their password if redirection is unnecessary. Auth0 provides implementation out of the box to take care of all of this, via the use of [Universal Login](/docs/authenticate/login/auth0-universal-login/identifier-first).

<Warning>
  Though it is possible to implement Identifier First Login or allow a user to select their organization at the application instead of on the Universal Login Page, this can add complexity with respect to single sign on as well as complexity associated with replicating that behavior in all of your applications. Instead Auth0 recommends implementing some form of HRD through Universal Login.
</Warning>

#### HRD through Universal Login using the email subdomain

The simplest way to implement home realm discovery on the universal login page is to utilize the email subdomain of the user’s identifier to map that to their Identity Provider. This, of course, only works in situations where the email subdomain will be a 1:1 mapping to an organization or at least to an Identity Provider.

Auth0’s [Lock](/docs/libraries/lock) widget or [Universal Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience) can do this for you if you are using the domain map in an enterprise connection; however, if you want to build this yourself, you can, but it requires you to build a mapping of email subdomain to connection.

Additionally, when using the Universal Login experience, the [Organizations Feature](/docs/manage-users/organizations/organizations-overview) will help you in two ways:

1. If you have not passed an org\_id to `/authorize` when you initiated the login request, Auth0 will present the user with a prompt to enter the organization they belong to.
2. If the Organization has more than one IdP associated with it, Auth0 will present the user with buttons to choose the organization or a form to enter a username and password.

#### HRD through Universal Login using the Identifier to Realm Map

A second, more complex alternative is to store a map of identifiers to IdP and provide a public endpoint to access that information. Then on the Universal Login page, you can find the connection and redirect back to /authorize with the connection. The main drawbacks to this approach are latency and, more importantly, security when it comes to identifier discovery: if you’re using email addresses, this makes it much easier for someone to discover whether a particular email address is a user of yours.

<Info>
  ### Best practice

  Any public endpoint should have rate limiting applied to it to prevent hackers from using it to discover information and to prevent denial of service attacks.
</Info>

#### HRD through Universal Login using user choice

The other option is to allow your users to choose from a list, if you don’t mind making public the list of organizations who use your product, or by allowing the user to enter their organization name explicitly. This would typically be done before redirecting the user to Universal Login. Once the user tells you which organization they belong to, you can redirect to Auth0 with the connection for that organization specified or have Auth0 simply prompt the user for their username and password if the connection is a database connection.

## Username and password authentication

Nearly every B2C application provides the ability for its customers to create a new set of credentials. This is a common form of authentication that all users are familiar with.

Username password authentication comes in multiple flavors at Auth0. If your application is a green-field application with no existing user base, then a simple Auth0 out-of-the-box [Database Connection](/docs/authenticate/database-connections) will give you everything you need to start authenticating your users. However, if you have a legacy user store (such as your own database of users or an existing LDAP system) you have a couple of different options for migrating your users as discussed in our guidance on [User migration](/docs/get-started/architecture-scenarios/business-to-business/provisioning).

However you end up provisioning the users for your database connection, the authentication of those users is quite similar. It requires you to present users with a form to enter their username and password. As mentioned in the guidance concerning [Universal Login](#universal-login), the simplest and safest way to authenticate users with a username and password is to redirect them to a centralized login page and collect their username and password there. This allows Auth0 to determine whether they have already authenticated and skip the login form entirely when it's not needed.

<Info>
  ### Best Practice

  Collecting credentials only at the centralized login page will reduce the surface area for potential leak of user secrets. It will also reduce the need to collect credentials unnecessarily. See [Universal Login](#universal-login) for more information.
</Info>

## Application integration

Once you've figured out how you want to authenticate your users, the next step is to determine how you will initiate that authentication. Each application will typically have its own starting point.

<Warning>
  Native mobile applications (and desktop applications) should use the system browser for authentication, or they open themselves up to additional security risks. See [Native vs. Browser Login on Mobile](/docs/get-started/authentication-and-authorization-flow/device-authorization-flow/mobile-device-login-flow-best-practices) for more information.
</Warning>

As discussed, we've found that most of our customers use [OpenID Connect (OIDC)](/docs/authenticate/protocols/openid-connect-protocol) as the industry-standard protocol when it comes to their customer-facing applications. Figuring out which OIDC flow to use is your first task, and you will want to start by reviewing the our [grant mapping](/docs/get-started/applications/application-grant-types) guidance in the first instance.

If you want to allow anonymous users access to any part of our application then you need to determine if you will be redirecting right away or prompting your users to redirect only when required (or perhaps some combination of both; see [Redirect Users After Login](/docs/authenticate/login/redirect-users-after-login) for further discussion). If users can [deep link](#deep-linking-to-protected-endpoints) to a protected version (or area) of your site then you will need to determine the links to your application that will result in an automatic redirect to Auth0.

### Anonymous access

It is important to consider the user experience when someone first comes to your application. If your application supports anonymous user access (quite common for eCommerce applications) there are different scenarios to consider:

* Are they returning to the application after having already logged in, or
* If this is the first time they are accessing the application:

  * Have they already accessed a different application that uses the same Auth0 tenant,
  * Have they ever (or perhaps not in a long time) authenticated on this device or browser.

When an anonymous user accesses your application, it can often be desirable for the application to discover if the user has already logged into a different application in the same family, or to remember this user even if the application is a [SPA](/docs/quickstart/spa) with no state. For example, if you can determine that the user is already logged in, you might decide to have the UI header in the application skip displaying a login button and instead have an account or profile menu for the user. To accomplish this you will want to utilize "[silent authentication](/docs/authenticate/login/configure-silent-authentication)". Silent authentication will allow you to check to see if the user is logged in without prompting them to log in if they are not. Then the application can present a login button if necessary. If the user is logged in already, however, then you will receive tokens and will not have to present the user with a login button again.

<Warning>
  Checking for a login session by redirecting to Auth0 can be helpful for your application, but if this will result in a lot of requests, you should employ a throttling mechanism to avoid latency and/or rate limiting.

  Calls to the Management API are subject to [Auth0 Rate Limiting policy](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy). You must take this into consideration, and to assist, Auth0 generally recommends use of the appropriate [Auth0 SDK](/docs/libraries) for your development environment rather than calling our APIs directly.
</Warning>

### Deep linking to protected endpoints

There are a variety of reasons why someone might link directly to a particular page within your application that is only accessible by authenticated users. If this is possible for your application you should automatically redirect your user to Auth0 if they are not authenticated. Once they authenticate and the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip> returns them to your application, you can [redirect them](/docs/authenticate/login/redirect-users-after-login) to where they intended to go in the first place.

### Best Practice

Most modern authentication frameworks support middleware for redirecting to an authorization server such as Auth0. When selecting one, here are some key considerations:

* Support for confidential clients, non-confidential clients, or both
* Support for configuration via [discovery endpoint](/docs/get-started/applications/configure-applications-with-oidc-discovery "Configure Applications with OIDC Discovery") or explicitly inline
* Support for token validation including expirations, signatures, claims and scopes
* Support for <Tooltip href="/docs/glossary?term=Refresh+Tokens">Refresh Tokens</Tooltip> if needed

### Authenticating the user

Authentication is the process of determining user identity. The result of authentication in an OIDC context is an <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip>. This token contains information about the user and should only be able to be obtained if the user authenticates using one or more factors as defined by the authorization server (the most common form being [user ID and password](#username-and-password-authentication)). There are a few things you may also need to consider in addition to obtaining an ID Token:

* Do we also need an [Access Token](/docs/secure/tokens/access-tokens) in order to call a shared API?
* Is your application a single-page application and only requires an [ID Token](/docs/secure/tokens/id-tokens)? See [Authorization Code Grant with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/call-your-api-using-the-authorization-code-flow-with-pkce) for more information.
* Is your application a native application (mobile or desktop) and/or do you need a [Refresh Token](/docs/secure/tokens/refresh-tokens)? See [Authorization Code Grant with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/call-your-api-using-the-authorization-code-flow-with-pkce) for more information.

<Warning>
  Before you go live, you should ensure that **only** the grants that you are using for each application are enabled in your [configuration for your Application](/docs/get-started/applications/update-grant-types).
</Warning>

### Authorization code grant (with or without PKCE)

If your SDK only supports the Authorization Code grant, or you need an Access Token or <Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip>, then Authorization Code grant (with or without [PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce)) can also be used to retrieve an ID Token. The Authorization Code grant includes an additional API call to exchange the code for a token which can result in additional unnecessary latency if all you need is the ID Token. In many cases the [hybrid flow](/docs/get-started/authentication-and-authorization-flow/hybrid-flow) is implemented to provide optimum access to the ID Token while still leveraging Authorization Code grant workflow for the secure and safe retrieval of Access and Refresh Tokens.

<Warning>
  While Auth0 supports the use of implicit grant for browser-based applications requiring only an ID Token, it is recommended to use authorization code grant with [PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce). For detailed information, see [OAuth2 Implicit Grant and SPA](https://auth0.com/blog/oauth2-implicit-grant-and-spa/) on the Auth0 Blog.

  If you need a [Refresh Token](/docs/secure/tokens/refresh-tokens) so that you can obtain a new Access Token or ID Token without having to re-authenticate the user, then you must use the [authorization code grant](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/call-your-api-using-the-authorization-code-flow).
</Warning>

## Attack protection

The reason that authentication systems are important is to prevent <Tooltip href="/docs/glossary?term=bad+actors">bad actors</Tooltip> from accessing applications and user data that they should not. We want to place as many barriers as possible between those bad actors and access to our systems. One of the easiest ways to do this is to ensure that your [attack protection](/docs/secure/attack-protection) with Auth0 is configured correctly, so take a moment to read the guidance on this subject and ensure that it's working correctly for you.

<Info>
  ### Best Practice

  Anomaly detection is handled behind the scenes by Auth0 and provides a great security feature for your product. If you're going to utilize it, ensure that you have set up your [Email Provider](/docs/get-started/architecture-scenarios/business-to-business/operations#email-provider-setup) and configured your [Email Templates](/docs/get-started/architecture-scenarios/business-to-business/branding#email-template-customization) before turning on email delivery to your users.
</Info>

## SSO with legacy systems

In a large scale re-structure it's not always possible—or practical—to update all your applications at once. In fact, our recommended best practice is to plan for an iterative-style approach when it comes to integrating with Auth0. If your applications already participate in Single Sign-on (SSO), and your legacy identity system supports protocols such as OIDC or <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip>, then you have a couple of options available if you want to continue to provide SSO as you integrate with Auth0:

* Update your existing identity provider in your legacy SSO system to redirect to Auth0 for login (e.g., using [SAML](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider)), or
* Have Auth0 redirect to your legacy SSO system to login. This requires configuring your legacy system as an IdP in Auth0 (i.e., either using [SAML](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider) or [OIDC](/docs/authenticate/identity-providers/social-identity-providers)).

<Info>
  ### Best Practice

  Supporting an SSO experience with your legacy system can add complexity, but may be worth it to generate a more seamless user experience as you integrate with Auth0. If you intend to go down this path, planning for it early can help ensure that it is possible to achieve. If you don't already have SSO at a centralized service, then the complexity to add it will unlikely be worth the benefits.
</Info>

This is a complex topic that will likely need some additional investigation depending on your current legacy architecture, and we recommend you only look into this if you currently have SSO support in your legacy system. Note: if you are currently redirecting from your applications to a centralized system to authenticate your users and that system only asks for credentials if you don’t already have a session with the centralized system, then you have a legacy SSO implementation.

## Enterprise Login

The “bring your own identity” scenario has become a must-have for almost all B2B applications. Most enterprise companies expect to be able to integrate their IdP into your application so their employees don't need to store another set of credentials. This is a valuable way of simplifying the user authentication experience without compromising security, and using [Universal Login](#universal-login) makes it easy to start adding support for [Enterprise Connections](/docs/authenticate/identity-providers/enterprise-identity-providers) with minimal disruption.

<Info>
  ### Best Practice

  Once you start supporting enterprise connections for users, you must do some form of [Home Realm Discovery](#home-realm-discovery) so that you can determine which connection to send the user to for authentication.
</Info>

With enterprise connection support, user identities and credentials are managed by the identity provider of your customers' organization, as well as certain identity claims - which Auth0 will use to populate the user [profile](/docs/get-started/architecture-scenarios/business-to-business/profile-management).

<Info>
  ### Best Practice

  "Bring your own identity" is a great feature to provide, but if you don't support this from day one, and sometimes even if you do, you may have an organization that wants to switch to their own IdP after already having used the application for a while. You will need a way to [link user accounts](/docs/manage-users/user-accounts/user-account-linking) to provide an effective way of associating the new identity with the old database identity.
</Info>

## Multi-factor authentication (MFA)

In an era where misuse of user credentials is at an all-time high, protecting your systems when it’s so common for hackers to steal users identity information in general is a challenge. One of the most effective ways though is to provide users with the ability to configure a second factor for protecting their account. More commonly referred to as [Multi-Factor Authentication](/docs/secure/multi-factor-authentication). This will ensure that only a valid user can access their account, even if they use a username and password that may have been compromised from a different application.

<Info>
  ### Best Practice

  It's quite common for customer facing applications to provide users with an *option* for adding a second factor rather than *forcing* them to use a second factor. For more information regarding this, see [providing your users with an option to add MFA](https://auth0.com/learn/multifactor-authentication-customers/).
</Info>

Auth0 supports a number of different options when it comes to enabling MFA for protecting user account access, and there are several practices to ensure that you will truly be providing a flexible second factor barrier to access:

* Auth0 [Guardian](https://auth0.com/multifactor-authentication): a service that provides both Push notification generation and an application for allowing or denying requests. Push sends notification to a user’s pre-registered device - typically a mobile or tablet - from which a user can immediately allow or deny account access via the simple press of a button.
* Time-based One-Time Password ([TOTP](https://auth0.com/blog/from-theory-to-practice-adding-two-factor-to-node-dot-js/)): allows you to register a device - such as Google Authenticator - that will generate a one-time password which changes over time and which can be entered as the second factor to validate a user’s account.
* SMS: for sending a one-time code over SMS which the user is then prompted to enter before they can finish authenticating.
* Voice: for delivering a one-time code through a phone call which the user is then prompted to enter before they can finish authenticating.
* Duo: allows you to use your Duo account for multi-factor authentication.
* Email: allows you to use your email account for multi-factor authentication.

Whilst MFA workflow using technologies such as Guardian or Google Authenticator is typically provided via a separate application that runs on a mobile or tablet device, if you don’t want your customers to have to download a separate application Auth0 also provides you with an [SDK](https://auth0.com/blog/announcing-guardian-whitelabel-sdk/) that you can use to build second factor workflow right in your existing mobile device application(s).

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2B IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/63F0WOPJdVzsPMxV1Xvp8x/7a329487c5e890d8e820f6a48983b46a/B2B_Project_Planning.pdf)

## Multiple Organization Architecture (Multitenancy)

Many B2B platforms implement some form of isolation and/or branding for their customers' organization, and this can add complexity to any Identity and Access Management (IAM) system. If this applies to you, then we recommend you take some time to read through our guidance and best practice advice for this type of environment.

[Multiple Organization Architecture](/docs/get-started/architecture-scenarios/multiple-organization-architecture)


# Authorization (B2B)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-business/authorization

User authorization and related planning considerations for your B2B IAM implementation.

Let's start by taking a step back and talking about Access Control. There isn't one clear cut definition of Access Control in the industry, but if you spend some time searching and reading, you'll see that most authoritative sources agree that it is the umbrella concept that puts all of Authentication, Authorization, Consent, and Policy Enforcement together to ensure that only the right people and services have access to your applications and APIs.

Next, let's look more closely into the distinctions between Authentication, Authorization, Consent, and Policy Enforcement. Your Auth0 tenant (your <Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip>) is typically responsible for Authentication and Consent, and some or all of Authorization and Policy Enforcement. Additionally, an Application or API itself almost always is the primary enforcer of policies, especially where contextual access is required:

* **Authentication**: the process of determining if a principal (a user or application) is who or what they say they are.
* **Authorization**: the process of determining what is allowed, based on the principal, what permissions they have been given, and/or the set of contextually-specific access criteria.
* **Consent**: what permissions the user (<Tooltip href="/docs/glossary?term=Resource+Owner">Resource Owner</Tooltip>) has given permission to an application to do on its behalf. This is generally a requirement of delegated authorization. The user has to give permission to the Client to access the user's data in a different system.
* **Policy Enforcement**: The act of enforcing the policies of the application or API, rejecting or allowing access based on a user's authentication and/or authorization information.

In general, we typically group different types of access control into three distinct categories so that it's easier to understand a) which actor is responsible for storing the information, b) which actor is responsible for making decisions, and c) which is responsible for enforcing the restrictions.

* The first category is where access is either granted or denied to an application or an API in its entirety. Both the data required to enforce this and the enforcement process is typically defined in the context of the Authorization Server For example, by using [`app_metadata`](/docs/manage-users/user-accounts/metadata) associated with a user and a [Rule](/docs/customize/rules) defined in your Auth0 tenant.
* The second category is where access is either granted or denied to a specific subset of application or API functionality. The data required to enforce this is typically stored in the Authorization Server For example, by using `app_metadata` on a user in your Auth0 tenant with the enforcement process performed in the application or API itself. In this scenario, the data is typically communicated as one or more custom claims in an [`id`](/docs/secure/tokens/id-tokens) or [`access`](/docs/secure/tokens/access-tokens) token.
* The third category is where access is either granted or denied depending on what the principal (subject) can operate on within the context of an application or API. Both the data required to enforce this, and the enforcement process is typically defined in the context of the application or API. In this scenario, the data communicated as one or more custom claims in an `id` or `access` token may be consumed with or without data from an external source that is not Auth0.

In addition, Role-based Access Control (RBAC) and Attribute-based Access Control (ABAC) mechanisms can be applied in any of the Access Control categories described above. Whatever your use case then, there are a number of things you will want to consider when looking at the functionality and workflow you require:

* Are there scenarios where access to an entire application or API should be rejected?
* Will you be providing APIs that can be accessed by third-party applications?
* Will your APIs also be accessed by your own (first-party) applications?
* Will your application be calling a third-party API?
* Should your applications and/or APIs be enforcing access control based on user claims?
* What if I need to know which organization an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> or <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> is associated with?

Auth0 supports access restriction for either applications or APIs based on certain conditions. In certain scenarios, you may want to create a Rule that returns an `UnauthorizedError` when, for example, a user attempts access to an application or an API at an incorrect time (as described in this [example](/docs/manage-users/access-control/sample-use-cases-rules-with-authorization#allow-access-only-on-weekdays-for-a-specific-application))—or if the user doesn’t have the right claim(s) contained in their `app_metadata`. For an application using [OpenID Connect (OIDC)](/docs/authenticate/protocols/openid-connect-protocol), this would prevent the allocation of the [ID Token](/docs/secure/tokens/id-tokens) used to authorize access. Similarly, for an API, allocation of any OAuth2 [Access Token](/docs/secure/tokens/access-tokens) (used when calling the API), could be prevented as described in this [example](/docs/manage-users/access-control/sample-use-cases-rules-with-authorization#deny-access-to-anyone-calling-an-api).

<Info>
  ### Best Practice

  In the main, we have found that [OIDC](/docs/authenticate/protocols/openid-connect-protocol) is the most commonly used industry-standard protocol used by Auth0 customers when it comes to authentication in their applications. We have also found that, even though [OAuth2](/docs/authenticate/protocols/oauth) was created as a delegation protocol, it is commonly used within first party applications when there is an API that does not have a shared session with the application.
</Info>

Auth0 also can provide the information needed so that an application can enforce restrictions. For [application level integration](#application-integration), Auth0 allows you to add [custom claims](#id-token-claims) to an ID Token, which your application can then verify and subsequently use to perform policy enforcement. In this case you will need to decide what information you require for your application to make enforcement decisions. If you need to make decisions at an API instead of in your application, you will likely need to use an Access Token instead of an ID token. Continue reading for more information.

<Warning>
  When deciding what data to include in your ID token and/or access token, consider token size, especially if you are passing the token in the URL. Even if you are not passing tokens in the URL, you will also need to consider the potential of exposing sensitive PII (Personally Identifiable Information). Token information is not encrypted, so although it isn't generally a security issue for an ID token to be leaked, it can become a privacy issue depending on the data that is included in the token.
</Warning>

For [API level integration](#api-integration), Auth0 supports both [custom claims](#access-token-claims) as well as [scope](#access-token-scopes) re-configuration, both within the context of an Access Token. Again, you will need to decide what information will be required in order for your API to make access decisions, and your API will need to enforce that by validating the contents of the Access Token.

<Info>
  ### Best Practice

  When deciding whether you should use permissions through custom claims or scopes, you should make sure you understand the nature and purpose of scopes. There is a nice [blog post](https://auth0.com/blog/on-the-nature-of-oauth2-scopes/) on that which is easy to read and helps clear up the topic.
</Info>

For multi-organization scenarios, it can often be important to know which organization an access token (or even an ID token) applies to. Taking care to follow the [best practices](#organization-data-in-an-access-token) can save you time and effort.

## Application integration

In this scenario, your Auth0 tenant provides a token as an indicator of authorized access to an application. For applications utilizing [OpenID Connect (OIDC)](/docs/authenticate/protocols/openid-connect-protocol), the industry-standard protocol we typically find most utilized when it comes to customer facing applications, this would be an ID Token expressed as a [JWT](/docs/secure/tokens/json-web-tokens).

### ID Token claims

Using Rule extensibility, Auth0 allows you to easily [add custom claims to an ID Token](/docs/get-started/apis/scopes/sample-use-cases-scopes-and-claims#add-custom-claims-to-a-token) based on, for example, a user’s [metadata](/docs/manage-users/user-accounts/metadata) content. Your application can then verify the ID Token for the necessary claims, and either allow or prevent access to certain functionality as required. Note that though the process of adding custom claims via Rule is streamlined, the Rule engine is flexible and allows you to write custom code that may have negative effects.

<Info>
  ### Best Practice

  When you are considering adding custom claims, we recommend that you store any access control data you may need to include within claims as part of the user's [`app_metadata`](/docs/manage-users/user-accounts/metadata). Firstly, this prevents you from needing to call an external API to fetch the data, which can negatively impact the performance and scalability of the login sequence. Secondly `app_metadata` **cannot** be modified by a user - so the user cannot directly circumvent any access control restrictions by modifying their own metadata. Also remember to check out our [metadata best practices](/docs/get-started/architecture-scenarios/business-to-business/profile-management#metadata) guidance too.
</Info>

If you are creating different instances of your application for your customer organizations, a common practice is to create a custom claim in your ID token to represent the user's organization. For example:

```js wrap lines theme={null}
context.idToken["http://yourdomain.com/claims/organization"] = "organization A";
```

### ID Token scopes

[OIDC Scopes](/docs/get-started/apis/scopes/openid-connect-scopes) are typically used by an application to obtain consent for authorized access to a user's details during authentication. Each of the pre-defined scopes returns the set of standard claims where defined, and as described in the [OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). The scopes an application requests depend on which user attributes the application needs. Once the requested scopes are authorized by the user, the claims are returned in the ID Token and are also made available via the [/userinfo](https://auth0.com/docs/api/authentication#get-user-info) endpoint.

## API integration

In this scenario your Auth0 tenant can provide an OAuth2 [Access Token](/docs/secure/tokens/access-tokens), typically expressed as a [JWT](/docs/secure/tokens/json-web-tokens), which can be used by your API to restrict access to certain parties. In addition, Auth0 provides support for what is notionally described as both [First-Party and Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/first-party-and-third-party-applications).

Acting as the authorization server, and with the consent of the user (the resource owner), your Auth0 tenant can be used to provide an Access Token—typically expressed as a [JWT](/docs/secure/tokens/json-web-tokens)—to an application (client) so that it can access a protected resources hosted by a <Tooltip href="/docs/glossary?term=resource+server">resource server</Tooltip> on behalf of the resource owner. The issued Access Token is typically passed as the Bearer token in the HTTP Authorization header sent to an API.

Whether you have a single API, or perhaps a suite of logically related [microservice APIs](/docs/get-started/apis/set-logical-api), you can leverage the Access Tokens that Auth0 provides in order to secure access to your service(s). Though relatively easy to set this up in the [Auth0 Dashboard](https://manage.auth0.com/) or through the [Auth0 Management API](https://auth0.com/docs/api/management/v2#!/Resource_Servers/post_resource_servers), it's important to review the different application scenarios and API layouts to determine the best architecture for your system.

<Callout icon="file-lines">
  OAuth2 Access Tokens are primarily designed for use in securing public facing APIs; when expressed as a JWT, an Access Token is a self contained entity which can be verfied without the need to make any additional 3rd party API call. If your APIs do not fall into this category - i.e they are part of an application itself (as in only called by that application) or are sat behing your firewall - then protecting them with tokens may well be overkill, and your existing cookie based (et al) workflow may well suffice.
</Callout>

OAuth2 was designed specifically with third-party access in mind, For example, a scenario might be that a user (resource owner) wants to use an application (a client) that does not belong to the same organization as the service that provides the user's data (the reseource server). In this case, when the application needs to access data that the user owns, it redirects to the organization where the user’s data resides, which in turn authenticates the user and then prompts the user to give the application permission to access their data. This prompting for permission is referred to as providing [consent](/docs/get-started/applications/confidential-and-public-applications/user-consent-and-third-party-applications) and is a large part of what providing support for [third party applications](/docs/get-started/apis/scopes/api-scopes#example-an-api-called-by-a-third-party-application) entails. If you are planning to integrate third-party applications, then it's important you mark them as third-party early on so that Auth0 will handle prompting for user consent.

On the other hand, if your organization owns the application(s), the user data itself and the API(s) through which that data is accessed, then consent is not typically required as the interactions are all [first-party](/docs/get-started/apis/scopes/api-scopes#example-an-api-called-by-a-first-party-application). If you're only creating first-party applications, then you can ensure that you are not presenting your users with any unnecessary consent screen(s) by [allowing user consent to be skipped](/docs/get-started/apis) as part of any resource service definition.

<Warning>
  Though you can configure your applications to be first-party and subsequently configure your APIs to allow first-party clients to ignore consent, if you are using `localhost` then Auth0 cannot verify that the application is truly a first-party app so your users will be prompted for consent anyway. To work around this constraint, when testing on your local machine during development, create a [fake local hostname and use that instead](https://community.auth0.com/t/how-do-i-skip-the-consent-page-for-my-api-authorization-flow/6035).
</Warning>

Alternatively, you may have data relating to a user for which additional [functionality is provided](/docs/get-started/apis/scopes/api-scopes#example-an-api-called-by-a-back-end-service) and for which explicit user consent cannot be obtained (i.e. there is no authenticated user who can provide it). In this scenario, a [list of applications for which Client Credentials grant is enabled](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow) can be defined.

### Access Token claims

As is the case with ID Tokens, you can [add custom claims to Access Tokens](/docs/get-started/apis/scopes/sample-use-cases-scopes-and-claims#add-custom-claims-to-a-token) using Auth0 Rule extensibility. Once added, your API can then verify an Access Token for the necessary claims and either allow or prevent access to certain functionality as required.

<Info>
  ### Best Practice

  When you are considering adding custom claims, we recommend that you store any access control data you may need to include within claims as part of the user's [`app_metadata`](/docs/manage-users/user-accounts/metadata). Firstly, this prevents you from needing to call an external API to fetch the data, which can negatively impact performance and scalability. Secondly `app_metadata` **cannot** be modified by a user - so the user cannot directly circumvent any access control restrictions by modifying their own metadata. Also remember to check out our [metadata best practices](/docs/get-started/architecture-scenarios/business-to-business/profile-management#metadata) guidance too.
</Info>

### Access Token scopes

[OAuth2 Scopes](/docs/get-started/apis/scopes/api-scopes) are typically used as the mechanism by which an API can determine what actions can be performed on behalf of a user. Scopes can be added on a per API basis to [define specific access permissions](/docs/get-started/apis/add-api-permissions) in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or through the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>). Scopes can also be manipulated via Auth0 extensibility (e.g. via a Rule, as in this [example](/docs/get-started/architecture-scenarios/spa-api/part-2#create-a-rule-to-validate-token-scopes)). The scopes an application requests for accessing an API should depend on what functionality the application needs the user to give permission for the application to use. Once the requested scopes are authorized, they will be returned in the Access Token which can be subsequently [verified by said API](/docs/secure/tokens/access-tokens/validate-access-tokens). A good example of this is when you log in to an application that is using a social provider for login: the social provider API requires that the application specifies whether the user will want the application to post items on your behalf. This allows the user to accept or deny this request. This example demonstrates how the user is delegating permission to the application—which is different than the API restricting access based on a user's role, and should be handled differently.

<Info>
  ### Best Practice

  Even though you have the ability to fully manipulate Access Token Scopes via Auth0 extensibility, as a security best practice you should only remove scopes which are not authorized and refrain from adding scopes that were not requested.
</Info>

Though scopes are often used as a way to enforce access permissions for a user, there are situations where it can become [tricky when you use them in this manner](https://auth0.com/blog/on-the-nature-of-oauth2-scopes/). We therefore recommend that you use scopes for their intended purpose (i.e. delegating permission to an application) and use [custom claims](#access-token-claims) for your role-based or other access control scenarios.

## Fine Grained Authorization (FGA)

[Fine Grained Authorization](https://docs.fga.dev/fga-concepts) allows you to grant individual users access to a specific resource or object based on:

* A user's role within an organization, such as `editor` or `admin`
* An attribute of the user or object, such as `manager` for a user or `marketing` for an object
* A relationship between a user and an object, such as a user with view access to a parent folder also has view access to the child folder

With <Tooltip href="/docs/glossary?term=FGA">FGA</Tooltip>, you can create an authorization model to determine what relationship you want to determine user access.

## Role Based Access Control (RBAC)

Auth0 has out-of-box support for Role Based Access Control ([RBAC](/docs/manage-users/access-control/rbac)). RBAC refers to assigning permissions to users based on their role within an organization, and provides for simpler access control by offering a more manageable approach that is less prone to error.

The core RBAC feature can be used in many multi-organization scenarios. See [Organization Data in an Access Tokens](#organization-data-in-an-access-token) for more information on how to ensure your setup can support your RBAC needs.

## Machine-to-Machine (M2M) Authorization

There are many scenarios that require an application without any user-interactive session to obtain an access token in order to call an API. In such scenarios you must authenticate the client instead of the user, and <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> 2 provides the [client credentials](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow) grant type to make this easy to achieve. Some common examples of where this is required include:

* A cron job or other service that needs to communicate with your API (e.g. where a daily report needs to be generated and emailed it to an administrator).
* A separate API the supports privileged access (e.g. the API is not exposed to users directly, but instead to a backend only).
* In certain microservice architectures, where some API layers need to communicate to other API layers without a user involvement, or after a user token has expired.
* A privileged API that may need to be called before a user has authenticated (i.e. from a rule or custom DB script in your Auth0 tenant)

<Info>
  ### best practice

  Traditionally, a special "service account" would have been created in order to cater for these scenarios: a user with a username and password that was configured for services which supported non-interactive use cases. That is no longer a recommended approach for many reasons, and the current best practice is to use [OAuth 2.0 Client Credentials Grant](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow) in these situations.
</Info>

## Organization Data in an Access Token

If you have a separate API from your application in your system that supports your multi-organization application, it is important to restrict operations to only the organization that the token was generated for. This requires that there is some sort of information in the access token to tell the API which organization the access token was issued for. This can be done in a couple of different ways depending on the answers to a couple of simple questions:

1. Will the End Users in this organization potentially have more than one organization, or is each End User isolated to a specific organization?
2. Will you be allowing any Machine-to-Machine (M2M) access to your API?
3. If you are allowing Machine-to-Machine (M2M) access to your API, Will you have any developers who need a single client ID and secret to access multiple organizations (but not all organizations)?
4. Will you be allowing the creating of third-party apps that require consent?

If End Users are isolated to a single organization **and** you will either not be allowing M2M access to your API or you will have a separate <Tooltip href="/docs/glossary?term=client+ID">client ID</Tooltip>/secret for each organization that needs access **and** you will not be allowing third-party apps that require consent, then the simplest approach is to just create a custom claim in the access token [using rules for the user based tokens](#access-token-claims) and [using the client credentials hook for M2M calls](#machine-to-machine-m2m-authorization). You can store organization name in client metadata and extract it from rules or hooks to include in access\_token as a custom claim. RBAC will work out of the box for this approach as well as long as each End User can only belong to one organization.

If End Users have more than one organization they can belong to or you might give a single developer a client ID and secret for M2M calls to more than one organization, the best approach is to create a separate <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> (a separate API instance in your Auth0 tenant) for each organization. This gives you a few nice abilities:

1. First, it allows you to pass the audience as a first-class parameter to Auth0 without having to create a custom parameter. The benefit of this is that Auth0 will help enforce the existence of the audience, and it will pass it to your rules. It will also ensure that an issued refresh token will only work for the specific audience it was originally issued to.
2. It allows you to restrict client grants to only specific organizations out of the box. The alternative is to create a more complicated client credentials hook to attempt to retrieve the restrictions from somewhere else and also require a much more complex and potentially troublesome way to tell the client credentials call which organization to issue the access token for.
3. This also allows you to use the core RBAC feature with Auth0 and ensure that the End Users who have access to more than one organization can have a potentially different role for each organization.

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2B IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/63F0WOPJdVzsPMxV1Xvp8x/7a329487c5e890d8e820f6a48983b46a/B2B_Project_Planning.pdf)

## Multiple Organization Architecture (Multitenancy)

Many B2B platforms implement some form of isolation and/or branding for their customers' organization, and this can add complexity to any Identity and Access Management (IAM) system. If this applies to you, then we recommend you take some time to read through our guidance and best practice advice for this type of environment.

[Multiple Organization Architecture](/docs/get-started/architecture-scenarios/multiple-organization-architecture)


# Branding (B2B)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-business/branding

How to configure Auth0 items to reflect your brand and desired user experience.

Auth0 can be customized with a look and feel that aligns with your organization's brand requirements and user expectations. Branding Auth0 collateral provides a consistent user experience for your customers, and gives them peace of mind that they’re using a product from a trusted and secure provider.

Auth0 provides support for [internationalization (I18N)](/docs/customize/internationalization-and-localization) and localization (L10N), both of which are important if you work on branding for an international clientele. Out-of-box collateral, such as the Auth0 Lock UI widget and <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>, comes ready enabled for multiple language support, with built-in extensibility for adding more languages if what you require [doesn’t already exist](/docs/customize/internationalization-and-localization/lock-internationalization).

<Info>
  ### Best Practice

  Almost all applications need Internationalization and/or Localization in one form or another. Auth0 makes it easy to add, but you need to account for it up front: retro-fitting localization, for example, can be a painful process if left too late.
</Info>

When considering the items you want to brand, as well as how best to brand them, there are a number of things you'll want to review:

* Do you need to brand your login page?
* Do you need to localize your login page?
* If you are sharing an Auth0 tenant across customer organizations, should you add organization-specific branding to their login experience?
* How can you customize emails so that they're not just branded, but vary based on user preference?
* How will users know that they're still on your domain when they see your login page?
* What do you need to do to provide additional browser security (e.g., implement Extended Validation)?
* Where do you want to direct users in the event of errors?

Auth0 provides tremendous flexibility when it comes to customizing and configuring Auth0 pages such as [Universal Login](#universal-login-and-login-pages) and [Password Reset](#password-reset-page-customization). So you can pretty much set up whatever UX look and feel you require. For many, the out-of-the-box experience - with perhaps a little alteration - is all that's required. However, for others the value of their brand and brand awareness requires more extensive customization. This flexibility extends to not only Auth0 pages, but via extensibility can also be applied to the [email templates](#email-template-customization). Auth0 [Custom Domain](#custom-domain-naming) functionality further enhances consumer awareness by providing users with the confidence and peace of mind when it comes to safety and security.

If you are sharing an Auth0 tenant across multiple customer organizations, providing each organization with their own domain of users and managing their credentials, you will need to consider how each user will know which credentials they should use and how they will trust that they are entering them somewhere safe and secure. See [Branding login by organization](#branding-login-by-organization) for details.

While Auth0 provides for default information when it comes to error situations, out-of-the-box information can be somewhat cryptic as the context that can only be provided by you is missing. Auth0 [error page customization](#error-page-customization) guidance can however help mitigate that by allowing you to provide information of a more context-specific nature via your own support organization.

<Info>
  ### Best Practice

  To provide helpful resources for users who experience problems, you should also configure a friendly name and a logo, as well as provide the support email address and URL for your organization. To learn how, see [Dashboard Tenant Settings](/docs/get-started/tenant-settings#settings).
</Info>

## Universal login and login pages

[Universal Login](/docs/authenticate/login/auth0-universal-login) is the recommended method for authenticating users, and it centers around use of the Login page. You can customize the Login page to support your organization's branding requirements.

<Info>
  ### Best Practice

  To customize Universal Login pages, you can modify your [page themes](/docs/customize/login-pages/universal-login/customize-themes) as well as create dynamic [page templates](/docs/customize/login-pages/universal-login/customize-templates).

  If you choose to implement [Classic Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/classic-experience) and customize the Login page script, we strongly recommend that you make use of version control. To do this, you should deploy the script to your Auth0 tenant via [deployment automation](/docs/get-started/architecture-scenarios/business-to-business/deployment) or via one of the [alternative strategies](/docs/customize/login-pages/classic-login/version-control).
</Info>

## Branding login by organization

Whether or not you need to do special customization on the Universal Login page is determined by how you plan to manage your customers’ organization. Before reading through this section, make sure you have read through the [Universal Login section](#universal-login-and-login-pages) and know how you are approaching organizations by reviewing [Multiple Organization Architecture](/docs/get-started/architecture-scenarios/multiple-organization-architecture).

If your organization users will all be isolated from each other, it’s important to make it clear on the Universal Login page which organization the login page is for. The easiest way to do this is to use the [Organizations Feature](/docs/manage-users/organizations/create-first-organization) which provides you a way to store logo, primary color, and background color which will be used to customize the branding on the Universal Login Page once the organization has been identified either by passing org\_id from the application or the user entering their organization at the organization prompt.

## Custom domain naming

By default, the URL associated with your tenant will include its name and possibly a region-specific identifier. For example, tenants based in the US have the a URL similar to `https://example.us.auth0.com` while those based in Europe have something that is of the fashion `https://example.eu.auth0.com`. A [Custom Domain](/docs/customize/custom-domains) offers a way of providing your users with a consistent experience by using a name that’s consistent with your organization's brand.

<Warning>
  Only one custom Domain Name can be applied per Auth0 Tenant, so if you absolutely must have independent domain name branding then you will require an [architecture](/docs/get-started/architecture-scenarios/business-to-consumer/architecture) where multiple Auth0 Tenants are deployed to production.
</Warning>

In addition, <Tooltip href="/docs/glossary?term=Custom+Domain">Custom Domain</Tooltip> functionality offers you complete control over the certificate management process. By default, Auth0 provides standard SSL certificates, but if you configure a custom domain, you can use Extended Validation (EV) SSL certificates or similar to provide the visual, browser-based cues that offer your visitors additional peace of mind.

In general, we see customers having the most success when they use a centralized domain for authentication - this is especially the case if the company offers multiple products or service brands. By using a centralized domain, you can provide end users with a consistent user experience while also minimizing the need to maintain multiple production tenants in Auth0.

<Warning>
  If your customer organizations will be isolated from each other, and you require that users are presented a login page for each organization via a custom domain URL, then your only option is to create a separate tenant for each organization.
</Warning>

## Email template customization

Auth0 makes extensive use of email to provide both user notifications and to drive the functionality needed for secure identity management (for example, email verification, account recovery, and brute force protections), and Auth0 provides a number of templates for these.

<Callout icon="file-lines">
  Before customizing email templates, please set up your [Email Provider](/docs/get-started/architecture-scenarios/business-to-business/operations#email-provider-setup).
</Callout>

Out of the box, the email templates used contain standard verbiage and Auth0 branding. However, you can configure almost every aspect of these templates to reflect the verbiage and user experience you want and make changes to things like the preferred language, accessibility options, and so forth.

Email templates are customized using [Liquid syntax](/docs/customize/email/email-templates/use-liquid-syntax-in-email-templates). If you are interested in customizing your templates based on user preferences, you will also have access to the [metadata](/docs/manage-users/user-accounts/metadata) located in users' profiles, as well as any specific application metadata too.

## Password reset page customization

The [Password Reset](/docs/customize/login-pages/classic-login/customize-password-reset-page) page is used whenever a user takes advantage of password change functionality and, as with the login page, you can customize it to reflect your organization's particular branding requirements.

If your organization users will all be isolated from each other (i.e, each organization gets its own Auth0 [database connection](/docs/authenticate/database-connections)), and you are branding the [Universal Login](#universal-login-and-login-pages) pages by organization, then it's also important to brand things like the password reset page so users know for which organization the password change is occurring. This can be done in a couple of ways:

* Create JavaScript on the Password Reset page that can pull resources from a CDN based on the connection parameter that indicates from which organization the user is coming.
* Create a separate tenant for an organization and use Universal Login to customize what is required for that organization.

## Error page customization

If there are issues encountered during user interactive workflow (e.g. user sign up or login), Auth0 provides error messages that indicate what the problem is under the hood. The default messages are somewhat cryptic, especially to the end user, since they will likely be missing context that only you can supply. As such, we recommend [customizing your error pages](/docs/customize/login-pages/custom-error-pages) to provide the missing context-specific information directly to your users. Furthermore, customizing your error pages allows you to display your branding, not Auth0's, as well as provide useful information to your users as to what should be done next. This information might include a link to a FAQ or how to get in touch with your company's support team or help desk.

<Info>
  ### Best Practice

  Out-of-the-box there is no user interface for customizing Auth0 provided error pages, but you can use the [Tenant Settings endpoint of the Management API](https://auth0.com/docs/api/management/v2#!/Tenants/patch_settings) to configure them. Alternatively, if you can create and host your own error page, then you can have Auth0 direct users to that page instead of using the Auth0-hosted option.
</Info>

## Guardian multi-factor page customization

The <Tooltip href="/docs/glossary?term=Multi-factor+Authentication">Multi-factor Authentication</Tooltip> pages can be customized by adjusting the Universal Login branding options in the [Universal Login Settings](https://manage.auth0.com/#/login_settings) section.

If you need further customization, you can also customize [the full HTML content](/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-classic-login) to reflect your organization's particular UX requirements.

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2B IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/63F0WOPJdVzsPMxV1Xvp8x/7a329487c5e890d8e820f6a48983b46a/B2B_Project_Planning.pdf)


# Deployment Automation (B2B)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-business/deployment

How Auth0 tooling helps to automate tenant deployment.

In addition to adopting best practices for change management and [QA](/docs/get-started/architecture-scenarios/business-to-business/quality-assurance), successful customers will also integrate Auth0 collateral management as part of some automated deployment process. As discussed in the Architecture section under [SDLC support](/docs/get-started/architecture-scenarios/business-to-business/architecture#sdlc-support), you will want to ensure you configure separate Auth0 tenants for development, testing, and production environments, and you will want that configuration to be almost identical for the tenant in each environment. Using deployment automation helps ensure this, so that each environment tenant is configured the same, and you will be less likely to see bugs show up as a result of mismatched configurations between environments.

<Info>
  ### Best Practice

  However you configure deployment automation, we’d recommend you unit test your rules, custom DB scripts, and hooks prior to deployment, and run some integration tests against your tenant post-deployment too. For more details regarding this, see the [Quality Assurance](/docs/get-started/architecture-scenarios/business-to-business/quality-assurance) guidance provided.
</Info>

Auth0 provides support for a couple of different options when it comes to the deployment automation approaches you can use, and each can be used in conjunction with the other if desired:

* The [Auth0 Deploy CLI tooling](/docs/deploy-monitor/deploy-cli-tool) provides you with an easy-to-use script that can help you integrate with your existing Continuous Integration/Continuous Deployment (CI/CD) pipeline.
* If you can’t integrate directly with, or for some reason you don’t have a CI/CD pipeline, then the Auth0 [Source Control Extensions](/docs/customize/extensions) can provide an easy-to-set-up basic automation process with very low maintenance.

<Warning>
  Note that both the Deploy CLI Tool and source control extensions can cause destructive changes; manual changes made directly in the dashboard between automated deployments could be lost! For this reason, if either is used, then **all** changes should be deployed from the source control subsystem referenced via the tooling and not made manually.
</Warning>

Each environment may also need some environment-specific configuration--Application <Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>’s and <Tooltip href="/docs/glossary?term=Client+Secrets">Client Secrets</Tooltip> will be different between the Auth0 tenants, for example--so you’re going to want some way of being able to dynamically reference this rather than having hard-coded values. Auth0 provides support for handling environment-specific configuration information through one of the following two approaches:

* Use [Tenant-specific variables](#tenant-specific-variables)
* Use keyword replacement if using the Auth0 Deploy CLI tool

## Tenant-specific variables

Auth0 allows you to configure variables that are available from within custom [extensibility](/docs/customize/extensions); these can be thought of as environment variables for your Auth0 tenant. Rather than hard code references that change when moving code between development, test, and production environments, you can use a variable name that is configured in the tenant and referenced by the custom extensibility code. This makes it easier for the same custom code to function, without changes, in different tenants because the code can reference variables that will be populated with tenant-specific values at execution time:

* For use of variables in Actions, read [Write Your First Action](/docs/customize/actions/write-your-first-action) to learn how to configure secrets in the editor
* For use of variables in Rules, see how to [configure values](/docs/customize/rules/configuration)
* For use of variables in Hooks, see how to [configure secrets](/docs/customize/hooks/hook-secrets) in the editor
* For use of variables in Custom DB Scripts, see the [configuration parameters](/docs/authenticate/database-connections/custom-db/create-db-connection#step-3-add-configuration-parametersn#step-3-add-configuration-parameters)

<Info>
  ### Best Practice

  It’s a recommended best practice to use variables to contain tenant-specific values as well as any sensitive secrets that should not be exposed in your custom code. If your custom code is deployed in GitHub/Gitlab/Bitbucket/VSTS, then using a tenant-specific variable avoids exposure of sensitive values via your repository.
</Info>

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2B IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/63F0WOPJdVzsPMxV1Xvp8x/7a329487c5e890d8e820f6a48983b46a/B2B_Project_Planning.pdf)

## Multiple Organization Architecture (Multitenancy)

Many B2B platforms implement some form of isolation and/or branding for their customers' organization, and this can add complexity to any Identity and Access Management (IAM) system. If this applies to you, then we recommend you take some time to read through our guidance and best practice advice for this type of environment.

[Multiple Organization Architecture](/docs/get-started/architecture-scenarios/multiple-organization-architecture)


# Launch Preparation (B2B)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-business/launch

Launch preparation considerations for your B2B IAM implementation.

Use this guide as you prepare for the launch of your application. We’ve included reminders about some content you may have viewed earlier during your planning or development phases as well as some new content unique to the launch phase. The sections below are useful to developers and project owners to ensure that you have everything lined up for a smooth launch. There are several things to check so it may help to assign ownership of different sections to different members of your team.

* [Tenant Check](/docs/get-started/architecture-scenarios/business-to-business/launch/tenant-check): Tenant Checks to perform before launch of your B2B IAM implementation.
* [Testing Complete](/docs/get-started/architecture-scenarios/business-to-business/launch/testing): Testing preparation for the launch of your B2B IAM implementation.
* [Operations Readiness](/docs/get-started/architecture-scenarios/business-to-business/launch/operations-readiness): Operations checks to perform before launch of your B2B IAM implementation.
* [Compliance Readiness](/docs/get-started/architecture-scenarios/business-to-business/launch/compliance-readiness): Compliance checks to perform before launch of your B2B IAM implementation.
* [Support Readiness](/docs/get-started/architecture-scenarios/business-to-business/launch/support-readiness): Support readiness for the launch of your B2B IAM implementation.
* [Launch Day Preparation](/docs/get-started/architecture-scenarios/business-to-business/launch/launch-day): Launch preparation considerations for your B2B IAM implementation.

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2B IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/63F0WOPJdVzsPMxV1Xvp8x/7a329487c5e890d8e820f6a48983b46a/B2B_Project_Planning.pdf)


# Compliance Readiness (B2B)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-business/launch/compliance-readiness

Compliance checks to perform before launch of your B2B IAM implementation.

There are several requirements related to privacy and compliance. Auth0 cannot provide legal guidance on your privacy or other regulatory obligations, but we can provide a curated list of privacy requirements below for which Auth0 offers features that may help you meet your obligations. Prior to launch, you should check that you’ve met all your privacy obligations and review the features outlined below to ensure you’re leveraging all the available Auth0 features to help you meet your privacy and compliance requirements.

## Publish privacy policy and obtain user consent

If you collect or process personal data about users, you should have published a privacy policy and have established procedures to ensure your operations abide by the contents of the policy. You also need to obtain a user’s consent for the collection and processing of information. Auth0 provides options for [displaying a link to your privacy policy storing user consent](/docs/secure/data-privacy-and-compliance/gdpr).

## Provide access to view, correct and erase data

Privacy legislation often requires that users have the right to view and correct any data held about them. If you are a data controller, you should provide a mechanism for this. Auth0 customers can build a self-service feature to access and correct data via the <Tooltip href="/docs/glossary?term=management+API">management API</Tooltip>.

## Provide access to data portability

If you are a data controller, you may be obligated to provide users a means to export their data from your system in a transportable format. Auth0 provides user data portability mechanisms to help you satisfy this obligation via both manual export capabilities and the Management API which enables you to implement a self-service feature for users.

## Take steps to minimize personal data

You should have reviewed the personal data you collect about users to ensure it is legitimately required for the purposes of the processing covered in the privacy policy and consent. You should also confirm you have minimized the data you collect, and established a data retention policy. You can optionally elect to encrypt data you store in user metadata for additional protection.

## Data retention policy enforcement automated

You should have a published data retention policy and automate the enforcement of it. The Auth0 management API or the <Tooltip href="/docs/glossary?term=Auth0+dashboard">Auth0 dashboard</Tooltip> can be used to facilitate [erasure of user accounts](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-right-to-access-correct-and-erase-data).

## Protect personal data

Regardless of whether you are a data controller or a data processor, you have obligations to protect the personal data you hold about users. This includes use of encryption where possible, and implementing reasonable security measures to protect user accounts. Prior to launch, you should check if you are using all the security features available from Auth0 to help with this such as Brute Force Detection, <Tooltip href="/docs/glossary?term=Multi-Factor+Authentication">Multi-Factor Authentication</Tooltip> (for both users and administrators), and a strong password policy if using passwords. You should also ensure you have a process ready to respond to Brute Force attacks.

## Supplier evaluation

Another common compliance obligation is to perform due diligence review of the security of any third-party suppliers to which you expose personal data. For Auth0, you will find information to facilitate this task on the Auth0 [security and certifications](https://auth0.com/security/) page where you can view the security certifications Auth0 has obtained.

## Additional resources

Additional resources that may be useful for your compliance requirements include:

* [Auth0 Privacy Policy](https://auth0.com/privacy)
* [Security and Compliance](https://auth0.com/security/)
* [Auth0 Compliance and Certifications](/docs/secure/data-privacy-and-compliance)
* [Auth0 General Data Protection Regulation Compliance](/docs/secure/data-privacy-and-compliance/gdpr)

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2B IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/63F0WOPJdVzsPMxV1Xvp8x/7a329487c5e890d8e820f6a48983b46a/B2B_Project_Planning.pdf)


# Launch Day Preparation (B2B)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-business/launch/launch-day

Launch preparation considerations for your B2B IAM implementation.

## Notifications / announcements

It helps a launch go smoothly if all stakeholders are aware of the impending launch and understand the launch plan as well as their role and responsibilities. In addition to notifying teams that will be actively involved, it can help to notify teams that might be needed if anything goes wrong. Having someone on standby during a launch can help expedite response. Be sure to identify and notify any team that might need to answer questions from customers, including on social media.

### Parties to notify

* Customers
* Business parters, if applicable
* Application team(s) impacted by launch
* Support teams
* Network teams (network changes, on standby, in case of issues)
* Security teams (on standby, in case of issues)
* Marketing teams (ready for announcements, response to issues)
* Social media teams (ready to monitor social media, respond)
* Sales teams (prepared to answer questions from customers)
* Customer success teams (prepared to answer questions from customers)

## Notification plan

Your notification plan should include elements such as the target <Tooltip href="/docs/glossary?term=audience">audience</Tooltip>, the key takeaways for the audience, the message content, the plans for distributing the notification and how to test the messaging.

A list of elements to include in the plan are:

* Target audience (consider both internal & external audiences)
* Message
* Timing
* Dependencies
* Responsible parties (who will send it)
* Mechanism (how it will be communicated)
* Test message and delivery (if applicable - test to ensure notifications sent)

## Notification distribution

A common tactic is to release notifications in batches to spread out the initial onslaught of load and reduce the scope of confusion if there are any unforeseen glitches. It’s easier to correct issues with a small group than during a big-bang launch.

* One approach is to start with a relatively small batch of notifications, and if no issues are identified, increase the size of the batches over time.
* You can also send out batches on a rolling schedule around the globe to spread out load hitting the system at once and have notifications arrive at an optimal time within each timezone to increase the likelihood of the messages being read.
* You can do a soft-launch to a portion of users, such as individual customers, regions or some other grouping that makes sense for your application.

## Outage windows (if needed)

Some organizations require a formal request for an outage window if any outages or downtime is required for a launch. If your organization requires this, be sure to identify if any downtime is required for the cutover or launch (or other dependent systems) and file the necessary outage or change requests in advance of any lead-time requirements.

## Cutover plan (if needed)

Some launches involve cutover from a previous solution to a new solution. If your project fits this scenario, you should be sure to identify everything that needs to happen as well as any dependencies, the responsible party for each task, and necessary timing. You may wish to plan alternates for all important roles or in each region in case anyone is unexpectedly sick or otherwise unavailable. A checklist of items to consider for the cutover plan is:

* Have you documented the cutover plan and rollback plan if needed?
* Are backups needed of anything prior to change?
* Are any preparatory data changes required?
* Any DNS records to be changed?
* Any Firewall changes?
* Any new monitoring targets?
* Any software to be deployed?

## Go / no-go criteria

In your overall launch plan, it is helpful to have go/no-go criteria and to have discussed in advance the types of issues which could occur and which could be worked through vs would require reverting. A launch plan can specify periodic check-in timeframes with criteria of what to assess at each checkpoint and how long to allow an issue to continue unresolved.

For each stage of the launch, it helps to have success criteria defined, that indicate the launch is proceeding as planned and can continue. Some example criteria could be:

* User signups growing with minimal errors
* User logins at expected rate, minimal errors
* Reported support issues below a certain threshold
* No issues identified that could lead to corrupted data

It’s also helpful to have identified criteria which could trigger a “no-go” decision to halt the launch. The risk tolerance for each environment varies, but a few example criteria might include:

* High percent of user signup or login resulting in errors that cannot be resolved quickly
* High number of support issues that cannot be resolved quickly
* Condition identified that could lead to data corruption
* High severity security issue discovered

## Rollback

It is always wise to have a plan for how to rollback or revert a launch, just in case something unforeseeable occurs which cannot be resolved. Reviewing the launch plan for every step which involves a change can help identify the tasks or changes requires to revert a launch or cutover.

The rollback plan should include the steps to take, the sequence, how long each is likely to take and the responsible party. Understanding the cumulative time required to roll back can help to determine the timing of the final go/no-go decision to fit within any required outage window.

If any data is migrated or changed for the launch, the plan should include how to revert it, if needed. Reverting may require running scripts to undo operational changes or restoring a data store from a backup taken before the launch process began.

It is also necessary to plan for the case where some data is entered into a new system before it has to be reverted. Will such data / transactions need to be abandoned with the rollback or will you have a way to capture and apply them elsewhere so they aren’t lost?

If the resolution of issues or process to revert could potentially take longer than one shift, you’ll want to ensure you have a primary and perhaps a secondary person available and prepared to handle things during each work shift. If an issue results in the need for prolonged response, significantly beyond one shift, there are limits for how long people can realistically function without a break. It can help to be prepared with resources for a follow-the-sun issue response effort if needed.

## Standby contacts

As the launch day approaches, it’s a good idea to identify all contacts who might be needed for troubleshooting or resolving issues and request them to be on standby and ready to help if needed. The launch leader should have contact information for each person on the standby list to expedite communications.

If there is a physical or virtual "launch room", the people on standby should know where it is and be ready to join if needed. Having a central room or video conference prepared can expedite communications and troubleshooting across all parties if an issue occurs.

## Success Criteria

A lot of planning goes into a launch in order to be successful, but will you know how to evaluate the launch? If you define success criteria before the launch, you can determine what to monitor and if any additional monitoring or checks need to be in place to evaluate the launch. For example - if one element of the success criteria is the number of sign-ups or logins - do you have a way of monitoring that and has it been tested to ensure it is accurate?

You’ll want statistics to be able to trumpet the success of your launch. You don’t want to find out after the launch that you didn’t capture any data to quantify all the hard work your team put into the launch.

## Risks & mitigations plan

It’s no fun to think of things that could go wrong, but if anything happens, you’ll be glad you did as having a plan can expedite response. A few examples to plan for include:

* Software application bug
* Application incompatibility with user browser settings
* Network failure/outage
* DoS attack
* Hosting environment failure
* Load / capacity issues
* Data / corruption issues
* Security vulnerability discovered

If you had a beta period, it may help to review the results of the beta to identify additional possible failure scenarios.

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2B IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/63F0WOPJdVzsPMxV1Xvp8x/7a329487c5e890d8e820f6a48983b46a/B2B_Project_Planning.pdf)


# Operations Readiness (B2B)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-business/launch/operations-readiness

Operations checks to perform before launch of your B2B IAM implementation.

## Status

You should ensure your operations staff knows how to monitor Auth0 service status and has set up a means to subscribe to updates on Auth0 status.

The Auth0 [status dashboard](https://status.auth0.com/) together with the Auth0 [uptime dashboard](http://uptime.auth0.com/) shows current and past status of the Auth0 service in a human-readable format. If any monitoring alerts are triggered, and as a first step in troubleshooting, your operations staff should check the status dashboard to see if there is a current outage. The public cloud status page also provides a facility for subscribing to outage notifications, and we also recommend that you check the status of any third-party [external services](/docs/deploy-monitor/monitor/check-external-services-status) you depend on, such as Social Providers. Having this information handy can help quickly eliminate possible causes when troubleshooting an issue and should be at the top of a troubleshooting checklist for developers as well as the help desk staff.

<Info>
  ### Best Practice

  Information on how to check the status of Auth0 as well as any dependent services (such as Social Providers) should be at the top of a troubleshooting checklist for both developers and helpdesk staff, and we recommend you subscribe via the Auth0 status page to set up notification of any status updates.
</Info>

In the event of an outage to the public cloud service, Auth0 performs a Root Cause Analysis (RCA) and publishes the results on the Auth0 status page. Auth0 performs a thorough investigation after an outage—including a determination of root cause, as well as contributing factors and how to prevent the issue from occurring again—and as a result, an RCA document can take a few weeks to be published.

## Email provider setup

You should double check that you have set up your own email provider to support production volumes of emails that might be sent to customers for signup, email validation, account recovery and the like.

Auth0 sends [emails](/docs/customize/email) to users for events such as signup welcome, email validation, breached password, and password reset events. You can customize the email templates for each type of event, and advanced customization of email handling is also possible. Auth0 provides a test email provider with limited capacity for basic testing, but you must set up your own email provider for production use, and customization of email templates will not work until you have established your own provider.

<Info>
  ### Best Practice

  The default Auth0 email provider does not support sending production volumes of email or customization of email templates. You should therefore configure your own email provider before deploying to production.
</Info>

## Infrastructure

### Firewalls

If custom code executing in Auth0 (such as in an Action, Rule, Hook, or custom database scripts) will call a service inside your network, or if you configure an on-premise SMTP provider in Auth0, then you may need to configure your firewall to allow [inbound traffic from Auth0](/docs/secure/security-guidance/data-security/allowlist). The IP addresses to allow through the firewall are specific to each region and are listed on the Rules, Hooks, custom database scripts, and email provider configuration screens in your <Tooltip href="/docs/glossary?term=Auth0+dashboard">Auth0 dashboard</Tooltip>.

## NTP

If this is not handled automatically by your hosting environment, you should have scripts which will automatically restart NTP (Network Time Protocol) if it fails and alerts that will notify someone if NTP is not running. Authentication transactions rely on accurate system time because <Tooltip href="/docs/glossary?term=security+tokens">security tokens</Tooltip> may be evaluated as expired when received if there are time discrepancies between sending and receiving systems.

## LoadBalancer timeouts checked

If you use the AD/LDAP connector, you should check the load balancer settings in your environment to see if they terminate long running connections that are inactive. If they do, you can modify the [Auth0 AD/LDAP Connection settings](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-to-auth0) to use the `LDAP_HEARTBEAT_SECONDS` setting to send periodic heartbeat messages to keep the connection open.

## LoadBalancer configuration

If your application maintains server state such that it depends on sticky load balancing to route users to a particular server, it can be beneficial to double check that all load balancer configurations are correct. One load balancer in a pool that is out of sync can cause intermittent errors that are hard to troubleshoot. A quick check of load balancer configuration can avoid such issues in the first place.

## Logs

You should check that you have set up the ability to capture log data, that logs are covered by your data retention policy and you have mechanisms to enforce logs data retention limits. You should also make sure that your development, support, and security teams know how to access logs data for troubleshooting and forensics purposes. Exporting log files to services that provide comprehensive analytics can help you identify patterns such as usage trends and errors.

Auth0 provides extensive capability when it comes to the logging of events, and also in the scanning of logs in order to identify event anomalies (see [logs documentation](/docs/deploy-monitor/logs) for further details). Standard log retention period for Auth0 logs is determined by subscription level with the shortest period being 2 days and the longest period being only 30 days. Leveraging Auth0 support for integrating with external logging services will allow you to retain logs outside of this, and will also provide for log aggregation across your organization.

<Info>
  ### Best Practice

  You should leverage one of the log streaming solutions to send log data to an external log analytics service. This will enable keeping data for longer periods of time and provide advanced analytics on the log data.
</Info>

You should review the log data [retention period](/docs/deploy-monitor/logs/log-data-retention) for your subscription level, and implement a log data export extension to send log data to an external log analytics service. You can use one of our [log streaming solutions](https://marketplace.auth0.com/features/log-streaming) in Auth0 Marketplace.

Development teams can use log files for troubleshooting and detecting intermittent errors that may be hard to find via QA tests. Security teams will probably want log data in case forensic data is ever needed. Exporting log files to services that provide comprehensive analytics can help you see patterns such as usage trends and <Tooltip href="/docs/glossary?term=attack+protection">attack protection</Tooltip> triggers.

### Rate limits and other errors

Auth0 provides a unique error code for errors reported when the [rate limit is exceeded](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy). You should set up automatic scanning of logs to check for rate limit errors so you can proactively address activity that hits rate limits before it causes too much trouble for your users. Auth0 also publishes error codes for other types of errors, and you will find it helpful to scan logs for [authentication errors](/docs/libraries/common-auth0-library-authentication-errors) as well as errors from Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> calls (Management API error codes are shown below each call in the [Management API Explorer](https://auth0.com/docs/api/management/v2)).

<Info>
  ### Best Practice

  Calling the Management API to retrieve user profile information from within a Rule is a common cause of rate limit errors because such API calls can execute for every login as well as periodic session checks.
</Info>

## Monitoring

Be sure to set up proactive monitoring of the Auth0 service as well as end-to-end authentication through your application.

You should establish mechanisms for [monitoring Auth0 implementations](/docs/deploy-monitor/monitor), so your support or operations team receives the timely information needed to proactively handle service outages. Auth0 provides monitoring endpoints that can be incorporated into your monitoring infrastructure. These endpoints are designed to provide a response suitable for consumption by monitoring services. It should be noted that they only provide data on Auth0. For complete end-to-end monitoring, which is essential for checking the ability of users to log in, we recommend that you set up [synthetic transaction monitoring](/docs/deploy-monitor/monitor/monitor-applications). This will provide greater granularity for your monitoring and enable you to detect outages unrelated to Auth0 as well as degradation of performance, so you can respond more proactively.

<Info>
  ### Best Practice

  You should set up the ability to send synthetic login transactions to facilitate end-to-end monitoring of authentication. You can do this with a simple application that uses the [Resource Owner Password Grant](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow/call-your-api-using-resource-owner-password-flow) in combination with a test user that has no privileges, and don’t forget about [Auth0 rate limiting policies](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy) too.
</Info>

## Auth0 Notifications

You should ensure your team is monitoring all of the following communication channels from Auth0 to stay abreast of important announcements and changes.

There are several different types of notifications from Auth0 that you should watch for as they contain important information that could impact your tenant(s) and project.

<Callout icon="file-lines">
  Proactive security notifications and other operational announcements are sent by Auth0 to dashboard administrators. You should ensure that the people who need to receive such messages are dashboard administrators.
</Callout>

### Dashboard notifications

From time to time, Auth0 may send an important announcement related to your tenant. These announcements about your service will be sent to your Auth0 dashboard and depending on the severity of the announcement, via email to the registered Auth0 dashboard administrators. You should make a regular practice of logging in to the dashboard and checking the bell icon at the top for any important notices. In addition, you should review emails from Auth0 in a timely fashion as they may convey important information about changes or actions you need to take.

### Auth0 security bulletins

Auth0 regularly conducts a number of security-related tests, and if any issues are found, will proactively identify and notify customers who need to make security-related changes. Due to the extensible nature of the Auth0 product, however, it may not be possible for Auth0 to identify every impacted customer, so you should regularly check Auth0 [security bulletins](/docs/secure). You should make sure a security contact for your organization is listed in Support Center.

<Info>
  ### Best Practice

  It is a best practice to check the Auth0 [Security Bulletins](/docs/secure/security-guidance/security-bulletins) page periodically and take the recommended action if you are impacted by any security bulletins.
</Info>

### Change log

Auth0 provides information on changes to the service in the Auth0 [change log](https://auth0.com/changelog). You should make a regular practice of reviewing Auth0 change logs to be aware of changes. Support teams researching an issue may find it useful to review the change log to determine if recent changes might be related, especially if these are breaking changes. Development teams will also want to review the change logs to identify new features that may be beneficial.

In addition, you should periodically check the [Auth0 migrations page](/docs/troubleshoot/product-lifecycle/deprecations-and-migrations) for news about upcoming deprecations that might require your team to make changes.

## Automated deployment, version control

While not required, we recommend you set up automated deployment with version control. Using automation to deploy or revert changes to the dev, test, and production environments enables you to respond more efficiently to issues post-launch.

In addition to adopting best practices for change management and [QA](/docs/get-started/architecture-scenarios/business-to-consumer/quality-assurance), successful customers also integrate Auth0 collateral management as part of an automated deployment process. As discussed in the Architecture section under [SDLC support](/docs/get-started/architecture-scenarios/business-to-consumer/architecture#sdlc-support), you should configure separate Auth0 tenants for development, testing, and production environments, where the tenant configuration is the same in each environment. Using deployment automation helps ensure that tenant configuration is consistent across environments, which reduces bugs and other issues.

<Info>
  ### Best Practice

  However you configure deployment automation, we’d recommend you unit test your rules, custom DB scripts, and hooks prior to deployment, and run some integration tests against your tenant post-deployment too. For more details regarding this, see the [Quality Assurance](/docs/get-started/architecture-scenarios/business-to-consumer/quality-assurance) guidance provided.
</Info>

Auth0 provides support for the following deployment automation approaches, which can be used in conjunction if desired:

* The [Auth0 Deploy CLI tooling](/docs/deploy-monitor/deploy-cli-tool) provides an easy-to-use script that integrates with your existing Continuous Integration/Continuous Deployment (CI/CD) pipeline.
* Auth0 [Source Control Extensions](/docs/customize/extensions) provides an easy-to-set-up basic automation process with very low maintenance if you don't have a CI/CD pipeline, or in cases where you cannot directly integrate with a CI/CD pipeline.
* If your development workflow leverages [Terraform](https://www.terraform.io/), [Auth0 Terraform Provider](/docs/deploy-monitor/auth0-terraform-provider) helps you manage your Auth0 tenant configurations.

<Warning>
  Note that both the Deploy CLI Tool and source control extensions can cause destructive changes; manual changes made directly in the dashboard between automated deployments could be lost! For this reason, if either is used, then **all** changes should be deployed from the source control subsystem referenced via the tooling and not made manually.
</Warning>

Each environment may also need some environment-specific configuration—Application <Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>’s and <Tooltip href="/docs/glossary?term=Client+Secrets">Client Secrets</Tooltip> will be different between the Auth0 tenants, for example—so you’re going to want some way of being able to dynamically reference this rather than having hard-coded values. Auth0 provides support for handling environment-specific configuration information through one of the following two approaches:

* Use [Tenant Specific Variables](#tenant-specific-variables)
* Use [keyword replacement](/docs/deploy-monitor/deploy-cli-tool/configure-the-deploy-cli) if using the Auth0 Deploy CLI tool

## Tenant-specific variables

Auth0 allows you to configure variables that are available from within custom [extensibility](/docs/customize/extensions); these can be thought of as environment variables for your Auth0 tenant. Rather than hard code references that change when moving code between development, test, and production environments, you can use a variable name that is configured in the tenant and referenced by the custom extensibility code. This makes it easier for the same custom code to function, without changes, in different tenants as the code can reference variables which will be populated with tenant-specific values at execution time:

* For use of variables in Actions, see [Write Your First Action](/docs/customize/actions/write-your-first-action) to learn how to configure secrets in the editor
* For use of variables in Rules, see how to [configure values](/docs/customize/rules/configuration)
* For use of variables in Hooks, see how to configure [secrets](/docs/customize/hooks/hook-secrets) in the editor
* For use of variables in Custom DB Scripts, see the [configuration parameters](/docs/authenticate/database-connections/custom-db/create-db-connection#step-3-add-configuration-parametersn#step-3-add-configuration-parameters)

<Info>
  ### Best Practice

  It’s a recommended best practice to use variables to contain tenant-specific values as well as any sensitive secrets that should not be exposed in your custom code. If your custom code is deployed in GitHub/Gitlab/Bitbucket/VSTS, then using a tenant-specific variable avoids exposure of sensitive values via your repository.
</Info>

## Backup / Restore

You should have a plan and mechanism in place to support any backup/restore capability needed for your project. This can be done using the Auth0 Management API for data as well as the Automated Deployment capabilities described in the automated deployment section for Auth0 configuration.

As noted in the Auth0 [Data Tenant Restore policy](/docs/troubleshoot/customer-support/operational-policies) and [Data Transfer policy](/docs/troubleshoot/customer-support/operational-policies/data-export-and-transfer-policy), Auth0 does not restore deleted tenants or move data between tenants. Auth0 provides the Auth0 Management API to provide customers a completely flexible capability to backup, restore and move data as needed. Customers can write scripts to retrieve data from Auth0 for backup purposes, and similarly write scripts for use with the Automated Deployment capability to restore any aspect of their Auth0 configuration.

## Versions Up to Date

You should double check that all technologies in your application stack, as well as browser versions used by your users are on current, up-to-date versions as this will impact Auth0’s ability to provide support if issues arise.

* Check you are using the latest supported version of node.js in [Auth0 dashboard settings](/docs/get-started/tenant-settings).
* Check you are using a version of SDK/Libraries supported by Auth0 per the [Auth0 Support Matrix](/docs/troubleshoot/customer-support/product-support-matrix).

## Certificate rollover plan

Certificates may be used in identity deployments. To ensure a certificate expiration does not catch you by surprise, you should have a list of certificates in your environment along with the expiration dates, how you will be notified when expiration draws near and how the certificate rollover process works.

### SAML connections

For <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> connections, you obtain a certificate from the <Tooltip href="/docs/glossary?term=IdP">IdP</Tooltip> and upload it to a SAML connection for the IdP in your Auth0 dashboard. When one of these certificates is about to expire, Auth0 will send email to dashboard administrators warning of the upcoming expiration. You can obtain the new certificate and upload it using the connection configuration screen.

### WS-Fed connections

For <Tooltip href="/docs/glossary?term=Web+Service+Federation">Web Service Federation</Tooltip> (WS-Fed) connections, if you configure them by specifying an ADFS URL, any changes will be picked up by a daily update. You can trigger an update manually by visiting the connection configuration page in the Auth0 dashboard and doing a Save. If a certificate is changed at the remote IdP, Auth0 can be updated by those mechanisms or by uploading a new metadata file in the same connection configuration screen.

## Disaster Recovery / Business Continuity Plan in place

While not an absolute requirement prior to launch, it is useful to have a disaster recovery plan in place to ensure business continuity in the face of different types of disasters, including system outages and natural disasters hitting a region where critical staff is located.

## Processes documented

Another item which is not an absolute requirement, but also recommended is to ensure all processes related to Auth0 are documented. This can include the following:

* Change management for configuration
* Deployment of new changes and any automatic deployment mechanisms used, how to revert to previous version if issues found
* Certificate rollover processes, if any
* Adding or removing new Identity Providers, if applicable
* Changes to user profile structure in Auth0 or in directories Auth0 pulls from
* Adding or removing applications or APIs
* Capturing and exporting logs
* Backup/restore process you have implemented
* User management (forgotten password, lost phone)
* Root cause analysis after an incident

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2B IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/63F0WOPJdVzsPMxV1Xvp8x/7a329487c5e890d8e820f6a48983b46a/B2B_Project_Planning.pdf)


# Support Readiness (B2B)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-business/launch/support-readiness

Support readiness for the launch of your B2B IAM implementation.

## Review Auth0 Policies

When starting to prepare for your launch, be sure to read through [Auth0 Policies](/docs/troubleshoot/customer-support/operational-policies) and prepare your production operations accordingly for any required lead times or responsibilities on your part, according to the policies.

## Review your Support plan, SLAs, Severity definitions and Support center documentation

You should review the specifics of the [support plan](/docs/troubleshoot/customer-support) you’ve purchased and the Service Level Agreements associated with it, to ensure it is adequate for your needs. If you haven’t already done so, explore the [support center](https://support.auth0.com/) and familiarize yourself with support features such as viewing suggested solutions to common issues and [filing tickets](/docs/troubleshoot/customer-support/open-and-manage-support-tickets) and viewing your quota usage. It will be helpful to review the severity level definitions for support tickets so that you file tickets with the correct severity. One important note is that it is not possible today in the Support Center to increase the severity of a support ticket. If you file a ticket for a medium-grade issue which later becomes a high severity issue, you should file a new urgent, high severity ticket that explains anything new that triggers the urgency and references the original ticket for details.

You should also ensure your development and support teams are familiar with the [Auth0 community forum](https://community.auth0.com/), discussed further below. Customers can often find answers there right away to common issues, avoiding the need to file a ticket, so it should be your first stop for technical questions.

## Review the Auth0 community forum

The [Auth0 community forum](https://community.auth0.com/) contains a wealth of information. If you have a question, chances are someone else has already asked the question on the forum. Answers are contributed by both Auth0 staff and the larger community of Auth0 users.

Important notices are posted to the community forum to help you stay abreast of important news. Be sure to check out the “Community” and “FAQ” categories. The Community category contains pro-active posts on product announcements, roadmap information, How-To videos as well as important information about any upcoming feature deprecations.

It’s a good idea to check out the Auth0 Community on a regular basis, not just when you have questions. While you are there, if you see a question you’ve already solved, please contribute your wisdom to help others!

## Gather Auth0 troubleshooting information needed for support tickets

We recommend your support team become familiar with our [troubleshooting guides](/docs/troubleshoot) specific to identity protocols and Auth0. This includes the questions to research and information to collect before posting a question on the Auth0 forum or filing a support ticket. Authentication transactions often span multiple systems so there are some specialized troubleshooting techniques that are helpful to learn.

## Have troubleshooting tools ready

Your team will doubtless have already done some troubleshooting during the development of your application, but we recommend making sure your support team is also familiar with any tools below relevant to your project. If you need to file a ticket, the Auth0 support team may ask for a HAR (HTTP Archive) file to help analyze the issue so it’s helpful for your support staff to be familiar with how to do this.

<Warning>
  Before sharing a HAR file with anyone (including Auth0), ensure that you remove or obfuscate all sensitive data, such as:

  * Confidential user information
  * Personal identifiable information (PII)
  * Confidential application information

  To learn more, read the following articles on [Auth0 Community](https://community.auth0.com):

  * [Sanitizing HTTP Traces](https://community.auth0.com/t/sanitizing-http-traces/119488)
  * [How to Sanitize an HTTP Trace File Automatically](https://community.auth0.com/t/how-to-sanitize-a-http-trace-file-automatically/120583)
  * [How to Manually Redact Sensitive Information](https://community.auth0.com/t/how-to-manually-redact-sensitive-information/122554)
  * [HAR File is Too Large to Upload to the Support Case](https://community.auth0.com/t/har-file-is-too-large-to-upload-to-the-support-case/122488)
</Warning>

### Capture HAR file

A [HAR file](/docs/troubleshoot/troubleshooting-tools/generate-and-analyze-har-files) captures a sequence of browser interactions and is a commonly used tool when debugging authentication issues. The process of authenticating a user often involves redirecting the user’s browser from an application to Auth0, and possibly to another remote <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip>, depending on the type of connection used. You can capture the redirection and the responses and analyze it to find clues about the cause of an issue.

### Analyze HAR file

Analyze the HAR file to obtain valuable troubleshooting information. It shows the sequence of browser redirects involved in an authentication transaction, along with the parameters used. The HAR file also shows if the authentication process stopped mid-stream and if so where, which helps to pinpoint the location of the issue. The HAR file contains tokens returned to the application front-end, and these can be pasted into appropriate viewers to see if they contain the expected contents.

### View JWT

The [jwt.io](https://jwt.io/) tool was written by Auth0 and allows you to view the contents of a <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip>-formatted token. Applications that delegate authentication to Auth0 via OIDC will receive an <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip> from Auth0. Depending on your type of application, the ID Token may be captured in a HAR file. The ID Token is in JWT format and can be pasted into jwt.io to view the contents of the ID Token.

### View SAML request/response

There are many <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> decoders available. The [samltool.io](https://samltool.io/) decoder was written by Auth0 and allows you to view the contents of a SAML Request or Response. Applications that delegate authentication to Auth0 via SAML or use a SAML type of connection in Auth0 will use SAML Requests and Responses. These SAML Requests and Responses may be captured in a HAR file. The requests and responses can be pasted into samltool.io or other SAML decoders to view the contents of the SAML Request or Response.

## Review Auth0 support matrix

One potential cause of issues is using out of date versions of SDKs or libraries. We strongly recommend your team check your software stack, browsers, SDKs and libraries against the [Auth0 support matrix](/docs/troubleshoot/customer-support/product-support-matrix) to ensure you are running on up-to-date, supported versions. In the event of an issue, the Auth0 support team may ask you to upgrade to a supported version. To avoid slowing down progress on issue resolution, be sure you are on up-to-date versions.

## Use Auth0 feedback portal

Auth0 welcomes feedback and ideas from Auth0 customers. If you have a suggestion for our product team, you can submit product feedback directly on the [Product Feedback portal](https://auth0.com/feedback).

## Actions Real-time Logs

For debugging and supporting custom code in Auth0, including Actions, Rules, Hooks, custom database scripts, and custom <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> connections, knowledge of the [Actions Real-time Logs](/docs/customize/actions/actions-real-time-logs) is essential. This enables you to view output from your custom code, including output from console.log statements.

We recommend using Actions Real-time Logs and getting familiar with using it to view log output from your custom code as a debugging and support tool.

## Troubleshooting

You should prepare to [troubleshoot basic issues](/docs/troubleshoot/basic-issues) both during your development as well as after your application or API goes live. Make sure your development and support teams are prepared with knowledge of troubleshooting tools, and the list of common issues to check when troubleshooting an issue.

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2B IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/63F0WOPJdVzsPMxV1Xvp8x/7a329487c5e890d8e820f6a48983b46a/B2B_Project_Planning.pdf)


# Tenant Check (B2B)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-business/launch/tenant-check

Tenant Checks to perform before launch of your B2B IAM implementation.

This section covers a list of configurations to check in your tenant. This should be done periodically during development and sufficiently before launch so you have time to fix anything amiss.

## General tenant check

### Tenant preparation check

Check to ensure you have set up tenant environments to support your SDLC lifecycle and that Dev, Test and Prod tenants are cleanly separated so that ongoing development work after launch doesn’t negatively impact your production environment.

Every company has some form of Software Development Life Cycle (SDLC), and throughout the development process you will want to align with that strategy. For instance, you need to be able to test your integration with Auth0 in a similar fashion as you test the applications themselves. It is therefore important to [structure Auth0 tenants to support your SDLC](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments), and there is a consistent pattern which our customers typically follow when it comes to the best practices associated with tenant layout for doing so:

<table>
  <thead>
    <tr>
      <th>Environment</th>
      <th>Sample Tenant Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Development</td>
      <td><strong>company-dev</strong></td>
      <td>A shared environment where most of your development work occurs</td>
    </tr>

    <tr>
      <td>QA/Testing</td>
      <td><strong>company-qa</strong> or <strong>company-uat</strong></td>
      <td>An environment for formal testing of the changes you've made</td>
    </tr>

    <tr>
      <td>Production</td>
      <td><strong>company-prod</strong></td>
      <td>The production tenant</td>
    </tr>
  </tbody>
</table>

In some cases you may also want to create one or more sandboxes (e.g., **company-sandbox1**, **company-sandbox2**) so that you can test changes without compromising your development environment. This might be where you test deployment scripts and the like.

<Info>
  ### Best Practice

  You can also take advantage of our [Implementation Checklists](/docs/get-started/architecture-scenarios/checklists) that you can download and customize to meet your implementation project needs.
</Info>

### Tenant association check

To ensure that your [tenants are all associated with your Auth0 contractual agreement](/docs/get-started/auth0-overview/create-tenants/child-tenants) and have the same features, ensure all your tenants are associated with your company account. If you have individual developers that want to create their own sandboxes for testing, make sure they get associated with your account so they have the same permissions too. To do this you should contact your Auth0 representative or the [Auth0 Support Center](https://support.auth0.com/center/s/).

### Specify production tenant

To ensure Auth0 recognizes your production tenant, be sure to [set your production tenant](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments#set-the-environment) with the “production” flag in the Support Center.

### Tenant production check

Auth0 provides a [Production Check](/docs/deploy-monitor/pre-deployment-checks) facility to detect many common errors. You should ensure this has been run and any findings from the report mitigated before launch.

In addition, you should check the [best practice configurations advice](/docs/deploy-monitor/pre-deployment-checks/production-checks-best-practices), for which checking cannot be automated.

### Tenant settings check

#### Tenant settings

Make sure to follow the Auth0 [tenant settings](/docs/get-started/tenant-settings) recommendations in configuring your logo as well as your support email and support URL so users know how to get help if an issue occurs. You'll want to check your <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> Session Timeout settings and the list of dashboard admins with access to your production tenant as well.

#### Error page customization

If there are issues encountered during user interactive workflow (e.g. user sign up or login), Auth0 provides error messages that indicate what the problem is under the hood. The default messages are somewhat cryptic, especially to the end user, since they will likely be missing context that only you can supply. As such, we recommend [customizing your error pages](/docs/customize/login-pages/custom-error-pages) to provide the missing context-specific information directly to your users. Furthermore, customizing your error pages allows you to display your branding, not Auth0's, as well as provide useful information to your users as to what should be done next. This information might include a link to a FAQ or how to get in touch with your company's support team or help desk.

<Info>
  ### Best Practice

  Out-of-the-box there is no user interface for customizing Auth0 provided error pages, but you can use the [Tenant Settings endpoint of the Management API](https://auth0.com/docs/api/management/v2#!/Tenants/patch_settings) to configure them. Alternatively, if you can create and host your own error page, then you can have Auth0 direct users to that page instead of using the Auth0-hosted option.
</Info>

#### Legacy feature flags off

If you have an older tenant, you may have various legacy feature flags enabled in your [tenant settings advanced tab](/docs/get-started/tenant-settings). If you have any toggles on in the “Migrations” section of this tab, you should review your usage and make plans to migrate off the legacy feature.

#### Delegated admin extension

While you are checking the list of users with access to your production tenant, don't forget to check any users specified in the [Delegated Admin Extension](/docs/customize/extensions/delegated-administration-extension).

### Custom Domain Naming set up

By default, the URL associated with your tenant will include its name and possibly a region-specific identifier. For example, tenants based in the US have the a URL similar to `https://example.auth0.com` while those based in Europe have something that is of the fashion `https://example.eu.auth0.com`. A [Custom Domain](/docs/customize/custom-domains) offers a way of providing your users with a consistent experience by using a name that’s consistent with your organization's brand.

<Warning>
  Only one custom Domain Name can be applied per Auth0 Tenant, so if you absolutely must have independent domain name branding then you will require an [architecture](/docs/get-started/architecture-scenarios/business-to-business/architecture) where multiple Auth0 Tenants are deployed to production.
</Warning>

In addition, <Tooltip href="/docs/glossary?term=Custom+Domain">Custom Domain</Tooltip> functionality offers you complete control over the certificate management process. By default, Auth0 provides standard SSL certificates, but if you configure a custom domain, you can use Extended Validation (EV) SSL certificates or similar to provide the visual, browser-based cues that offer your visitors additional peace of mind.

In general, we see customers having the most success when they use a centralized domain for authentication - this is especially the case if the company offers multiple products or service brands. By using a centralized domain, you can provide end users with a consistent user experience while also minimizing the need to maintain multiple production tenants in Auth0.

## Application and Connection settings check

Each of your connection settings should be reviewed against the [connection configuration best practices](/docs/authenticate/connection-settings-best-practices).

In addition, you should review that all connections are appropriate and that no experimental connections are left in your production tenant as they could enable unauthorized access.

If you use <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> connections, it is a best practice to configure the connections to sign SAML requests.

## Page customization check

If you use the Auth0 <Tooltip href="/docs/glossary?term=universal+login">universal login</Tooltip> page, password reset page, or Guardian <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip>, you should check that you have adequately customized the pages displayed to the end user.

### Universal Login Page

[Universal Login](/docs/authenticate/login/auth0-universal-login) is the recommended method for authenticating users, and it centers around use of the Login page. You can customize the Login page to support your organization's branding requirements.

<Info>
  ### Best Practice

  To customize Universal Login pages, you can modify your [page themes](/docs/customize/login-pages/universal-login/customize-themes) as well as create dynamic [page templates](/docs/customize/login-pages/universal-login/customize-templates).

  If you choose to implement [Classic Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/classic-experience) and customize the Login page script, we strongly recommend that you make use of version control. To do this, you should deploy the script to your Auth0 tenant via [deployment automation](/docs/get-started/architecture-scenarios/business-to-business/deployment) or via one of the [alternative strategies](/docs/customize/login-pages/classic-login/version-control).
</Info>

### Password reset page

The [Password Reset](/docs/customize/login-pages/classic-login/customize-password-reset-page) page is used whenever a user takes advantage of password change functionality and, as with the login page, you can customize it to reflect your organization's particular branding requirements.

### Guardian

The Multi-factor Authentication pages can be customized by adjusting the Universal Login branding options in the [Universal Login Settings](https://manage.auth0.com/#/login_settings) section.

If you need further customization, you can also customize [the full HTML content](/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-classic-login) to reflect your organization's particular UX requirements.

## Authorization check

If you are using Auth0’s authorization feature, be sure to double check all privileges granted to ensure authorizations are appropriate for your production environment.

## API configuration check

### Access token expiration

You should double check the [API access token expiration settings](/docs/get-started/apis/api-settings) to ensure they are appropriate for each API in your production environment.

### API offline access

If your application does not request <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip>, this should be off.

### Access token signing algorithm

It is recommended that the [API access token signing algorithm](/docs/get-started/applications/signing-algorithms) be set to RS256 rather than HS256 to minimize exposure of the signing key.

### API Access token validation

If you have any custom APIs, be sure to check that they are adequately [validating the access tokens](/docs/secure/tokens/access-tokens/validate-access-tokens) they receive before using the information in them.

## API Scopes

If you have applications making machine-to-machine calls to any of your APIs, you should review the scopes specified for the API to ensure they are all appropriate for your production environment. For further information see the documentation on [client credentials grant](/docs/get-started/applications/update-grant-types).

## Email templates customized

Auth0 makes extensive use of email to provide both user notifications and to drive the functionality needed for secure identity management (for example, email verification, account recovery, and brute force protections), and Auth0 provides a number of templates for these.

<Callout icon="file-lines">
  Before customizing email templates, please set up your [Email Provider](/docs/get-started/architecture-scenarios/business-to-business/operations#email-provider-setup).
</Callout>

Out of the box, the email templates used contain standard verbiage and Auth0 branding. However, you can configure almost every aspect of these templates to reflect the verbiage and user experience you want and make changes to things like the preferred language, accessibility options, and so forth.

Email templates are customized using [Liquid syntax](/docs/customize/email/email-templates/use-liquid-syntax-in-email-templates). If you are interested in customizing your templates based on user preferences, you will also have access to the [metadata](/docs/manage-users/user-accounts/metadata) located in users' profiles, as well as any specific application metadata too.

## Attack protection configured

The reason that authentication systems are important is to prevent <Tooltip href="/docs/glossary?term=bad+actors">bad actors</Tooltip> from accessing applications and user data that they should not. We want to place as many barriers as possible between those bad actors and access to our systems. One of the easiest ways to do this is to ensure that your [attack protection](/docs/secure/attack-protection) with Auth0 is configured correctly, so take a moment to read the guidance on this subject and ensure that it's working correctly for you.

<Info>
  ### Best Practice

  Anomaly detection is handled behind the scenes by Auth0 and provides a great security feature for your product. If you're going to utilize it, ensure that you have set up your [Email Provider](/docs/get-started/architecture-scenarios/business-to-business/operations#email-provider-setup) and configured your [Email Templates](/docs/get-started/architecture-scenarios/business-to-business/branding#email-template-customization) before turning on email delivery to your users.
</Info>

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2B IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/63F0WOPJdVzsPMxV1Xvp8x/7a329487c5e890d8e820f6a48983b46a/B2B_Project_Planning.pdf)


# Testing Complete (B2B)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-business/launch/testing

Testing preparation for the launch of your B2B IAM implementation.

Prior to launch, you should have completed all the testing that applies to your environment.

Quality Assurance is important in identifying issues before they impact your customers and, depending on the nature of your project, there are several different types of quality assurance testing that you’re going to want to consider as part of your integration with Auth0:

* Is your application easy to understand and use, even by those with a disability?
* Does your application need to work across various different browsers and devices?
* Does your application need to work in multinational and/or international environments?
* How will your application perform when subjected to unexpected production loads?
* How can you ensure your application is safe from security-related vulnerabilities?

Auth0 [Universal Login](/docs/authenticate/login/auth0-universal-login) and associated UI widgets (such as [Lock](/docs/libraries/lock)) have already been designed and built following usability and accessibility best practices, and provide tested out-of-box support for a whole host of [browsers and devices](/docs/troubleshoot/customer-support/product-support-matrix). Support for [internationalization](/docs/customize/internationalization-and-localization) (I18N) is also provided out-of-box, with built-in extensibility designed for custom multi-language and localization (L10N) situations.

To ensure functional requirements are met and unexpected events are handled correctly, guidance is provided for testing the [integration](#integration-testing) between your application(s) and Auth0, and for [unit testing](#unit-testing) individual extensibility modules (such as [Rules](/docs/customize/rules/debug-rules), [Hooks](/docs/customize/hooks/update-hooks), and Custom Database scripts). Guidance is also provided regarding Auth0's [penetration testing policy](/docs/troubleshoot/customer-support/operational-policies/penetration-testing-policy) to help when testing for security vulnerability, and also how [Mock](#mock-testing) testing can be leveraged in conjunction with our [load testing policy](/docs/troubleshoot/customer-support/operational-policies/load-testing-policy) to help ensure your application(s) perform under unexpected load.

## Unit testing

The objective of unit testing is to test individual units of code. If you create custom code within Auth0 in the form of Rules, Hooks, and/or Custom DB scripts, you should consider use a testing framework (such as [Mocha](https://mochajs.org/)) to test your code. Companies who have been most successful with Auth0 have found it useful to execute these unit tests prior to [automatically deploying](/docs/get-started/architecture-scenarios/business-to-business/deployment) Auth0 tenant configuration and collateral.

## Integration testing

It is a recommended best practice that you set up different tenants for development, testing, and production as discussed in Architecture guidance for [SDLC support](/docs/get-started/architecture-scenarios/business-to-business/architecture#sdlc-support). Auth0 allows you to configure variables that are available from within custom [extensibility](/docs/customize/extensions); these can be thought of as environment variables for your Auth0 tenant. Rather than hard code references that change when moving code between development, test, and production environments, you can use a variable name that is configured in the tenant and referenced by the custom extensibility code. This makes it easier for the same custom code to function, without changes, in different tenants as the code can reference variables which will be populated with tenant-specific values at execution time:

* For use of variables in Rules, see how to [configure values](/docs/customize/rules/configuration)
* For use of variables in Hooks, see how to configure [secrets](/docs/customize/hooks/hook-secrets) in the editor
* For use of variables in Actions, see Explore Flows and Triggers
* For use of variables in Custom DB Scripts, see the [configuration parameters](/docs/authenticate/database-connections/custom-db/create-db-connection#step-3-add-configuration-parameters)

<Info>
  ### Best Practice

  It’s a recommended best practice to use variables to contain tenant-specific values as well as any sensitive secrets that should not be exposed in your custom code. If your custom code is deployed in GitHub, then using a tenant-specific variable avoids exposure of sensitive values via your GitHub repository.
</Info>

### Test automation

You can automate your overall build process by incorporating deployment automation as well as test automation. This can be used to deploy new versions of configuration and/or custom code to Auth0 and execute automated tests. If the tests uncover any failures, the deployment automation capabilities can be used to revert to the last working version. For further information, see the [deployment automation guidance](/docs/get-started/architecture-scenarios/business-to-business/deployment) provided.

## Mock testing

In a balance between Auth0’s [load testing policy](/docs/troubleshoot/customer-support/operational-policies/load-testing-policy) and the desire to load test, it is common practice among Auth0’s customers to mock out Auth0’s endpoints. This is a valuable practice in order to ensure that your application works with your expected interfaces without having to restrict your testing, and tools such as [MockServer](http://www.mock-server.com/), [JSON Server](https://github.com/typicode/json-server) or even [Postman](https://learning.getpostman.com/docs/postman/mock_servers/setting_up_mock/) can be used to assist.

## Pen testing (optional)

If you will be conducting penetration tests, you should be aware of Auth0’s [penetration testing policy](/docs/troubleshoot/customer-support/operational-policies/penetration-testing-policy) and abide by it. Penetration tests require advance notice to Auth0 so that your tests are not mistaken for malicious activity and shut down.

## Load testing (optional)

If you will be conducting load tests, you should be aware of Auth0’s [load testing policy](/docs/troubleshoot/customer-support/operational-policies/load-testing-policy) and abide by it. Load tests require advance notice to Auth0. In planning your load testing, you will also need to be aware of Auth0’s [API rate limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy).

Load tests require prior approval from Auth0, as explained in the Auth0 load test policy. Be sure to note the lead time for a request to be reviewed and allow enough time for review as well as conducting the tests. If your load test request has been approved, the following guidance can help avoid errors and faulty test results.

* Run an HTTP trace on a test execution of your application to identify all the calls your application or intended test needs to make, and make sure your test includes them so it is representative of what will happen in production.
* Design your test to be mindful of Auth0 API rate limits.
* Use of any custom code in Auth0 (Actions, Rules, Hooks, custom database scripts, custom <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> connections) will invoke the Auth0 custom code sandbox and this may cost more in terms of performance. Turn off Rules unless they are essential to the test. If they are off you will have higher throughput than if they are on.
* Estimate the expected overall load for your production environment and percent of calls to each endpoint and structure your performance test accordingly so it gives you a realistic test result. Different endpoints have different performance costs. Failure to design a representative test will result in misleading results.
* Don’t make calls that depend on the results of earlier calls without checking that pre-requisite calls or responses have completed. Simply building in a delay may not be adequate.
* Be sure to implement adequate error handling. A frequent cause of issues during tests is errors in custom code (Actions, Rules, Hooks, custom database scripts, custom OAuth connection scripts) caused by unhandled exceptions in the custom code.
* Load tests should be written to start at a low level and increase the load gradually, capturing data at each level, to get the most useful results. Starting at a high level and immediately failing gives less information about what the system can sustain.
* It is normal to need to run a performance test multiple times, possibly adjusting the code under test or the test harness/configuration. Be sure to start your testing early to allow enough time for more than one iteration.
* Use your own mail provider account and make sure to arrange ahead of time for enough mail-sending quota or you may be rate-limited by the mail provider. Turn off mail sending if you do not use it.
* Be sure to use your own account credentials for all social connections rather than Auth0 dev keys. In the <Tooltip href="/docs/glossary?term=Auth0+dashboard">Auth0 dashboard</Tooltip>, go to Connections -> Social -> \{name of connection}—to see instructions for how to add your own social provider account credentials into the connection. Note: some social providers do not allow load testing. Check your provider(s) for their policy
* In order to avoid rate limiting, and more accurately simulate real load, your tests will need to send requests for different users, not all requests for the same user. If you use only one or a few users, caching may reduce the effective load and not provide realistic results.
* Be sure to stay within the agreed-upon parameters for the test and the Auth0 load test policy. Auth0 reserves the right to terminate any performance/load testing which does not stay within the bounds of agreed-upon parameters or which extends beyond the scheduled test window.

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2B IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/63F0WOPJdVzsPMxV1Xvp8x/7a329487c5e890d8e820f6a48983b46a/B2B_Project_Planning.pdf)


# Logout (B2B)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-business/logout

User logout planning considerations for your B2B IAM implementation.

[Logout](/docs/authenticate/login/logout) is the act of terminating an authenticated session when it's no longer needed, thus minimizing the likelihood that unauthorized parties can "take over" the session. This is typically achieved by provisioning a logout option on the user interface you provide to your users. Multiple types of sessions can be created when a user logs in (e.g., local application sessions, Auth0 session, third-party <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> sessions), and you will need to determine which of these sessions need to be terminated when the user clicks any **Logout** option.

<Info>
  ### Best Practice

  Your logout behavior should make it clear to a user which session(s) are being terminated, and ideally, will display a visual confirmation of logout afterward.
</Info>

When configuring logout behavior, you'll need to consider:

* Which sessions should be terminated when the user initiates logout?
* What information should you provide to users as confirmation of the sessions terminated?
* Where should users be redirected to after logout completes?
* How long do you want sessions to last in the event that users do not trigger the logout process?
* Should the End User be logged out of all of their application sessions when they log out of one?
* Should the session with an organization's IDP also be terminated at logout?

Given the varying types of sessions that can be created whenever a user logs in, there are several types of logout possible. Local application logout ends the session with the application, whereas Auth0 logout [terminates the Auth0 session](/docs/authenticate/login/logout/log-users-out-of-auth0). If you have organizations that are using their own IDP, you may want to consider a [Federated Logout](#federated-logout) strategy and implement accordingly. Global, or [Single Logout](/docs/authenticate/login/logout/log-users-out-of-applications) (SLO), ends the Auth0 session and also sends a logout request/notice to applications relying on the Auth0 session.

The functionality provided by your application, as well as your use of features like [Single Sign-on (SSO)](/docs/authenticate/single-sign-on), will inform your decision as to what type of logout is required and what visual confirmation you'll need to provide to your users. Regardless of which option you choose, the logout process you implement should make it clear to the user which sessions are being terminated, and also when the logout process has completed.

<Warning>
  If the logout feature in one application terminates an Auth0 SSO session that is used by other applications, the user may lose work if they have uncommitted transactions. Be sure to add the functionality needed to handle such conditions to minimize the likelihood of lost work.
</Warning>

In some situations, a user may be expected to logout of all associated applications when they log out of any one of the applications you provide. This is something that can add complexity. However if you have concerns that users could leave themselves vulnerable (perhaps due to data sensitivity or the like), then you will likely need to review [Single Logout](#single-logout) and implement accordingly.

## Where to send users after logout

Once your user logs out, they will be redirected to a specific location of your choosing. This location is specified as the **logout redirect URL**, and you can [define this as a parameter](/docs/authenticate/login/logout/redirect-users-after-logout) via the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

The URL(s) you use to redirect users after logging out must be [allowlisted in the Dashboard](/docs/authenticate/login/logout#redirect-users-after-logout) to mitigate open-redirect security vulnerabilities. You can allowlist them at the tenant or application levels.

<Callout icon="file-lines">
  If the user logs out and you redirect them back to the application, and the application redirects to an Identity Provider that still has a valid session for the user, the user will be logged in silently to the application. This may appear to the user as if the logout process didn't function properly.
</Callout>

## Automatic termination of sessions

Not all users will trigger the logout process manually, so Auth0 also provides **session timeout** to prevent overly long-lived sessions. This setting is [available and configurable via the Auth0 Dashboard](/docs/get-started/tenant-settings#login-session-management).

## Single Logout

If you are doing [Federated Logout](#federated-logout) you will likely also want to do Single Logout (SLO), and there are two main approaches you can take.

<Warning>
  SLO can add complexity to your system, so you need to ensure that you really need it before adding the extra development and maintenance time to your system.
</Warning>

### Short-lived tokens

<Info>
  ### Best Practice

  You want to avoid making too many calls to your Auth0 tenant to avoid rate limiting and poor performance. A best practice is to only request new tokens if tokens have expired and a user takes an action. This will avoid applications that are simply open, but not in use, from continually polling for new tokens.
</Info>

This is by far the simplest approach to Single Logout. Each application enforces a short time within which a user can use the system, say, 5-10 minutes. On each action a user performs, if the time has expired then either a redirect to Auth0 (for regular web apps), or [Silent Authentication](/docs/authenticate/login/configure-silent-authentication) for client side Single Page Applications will be used to obtain new tokens. Ordinarily new tokens will be issued silently due to the <Tooltip href="/docs/glossary?term=Single+Sign+On">Single Sign On</Tooltip> (SSO) session. However, after logout, all applications will fail to get new tokens silently because the SSO session will have been removed, and the user will need to re-enter their credentials.

<Warning>
  If you are automatically forwarding the user directly to their own IdP as part of an enterprise connection using the connection parameter, this can break this technique unless you are also doing [Federated Logout](#federated-logout)
</Warning>

### Build a logout service

Another technique you can use is to build a logout service that can track and destroy application sessions. Each application would notify the logout service when it creates and removes a session. The (logout) service would either have direct access to all application's server side sessions and destroy them directly, or it will have the ability to make a back-channel call to each application to tell the application that it must remove its session.

This technique can be quite effective as there is low-latency between when a user calls logout, and when they are then logged out of all applications. However it can add complexity and also additional development time for implementation. It will also require some way to ensure that new applications added to the system are added to this service.

## Federated Logout

[Federated User Logout](/docs/authenticate/login/logout/log-users-out-of-idps) may be something that you need to consider for your application. If you or your customers will be using a third-party IdP (i.e., something other than a [Database Identity Provider](/docs/authenticate/database-connections)) then the question of whether you need to log the user out of the IdP when they log out of your application is something you will need to answer. The answer depends on what your users would expect. If the application and/or IdP you use is tied closely to a customer organization and a central part of day-to-day operations, then it may be frustrating for users to get logged out of their IdP when they log out of your application. If not, then being logged out of the IdP may be expected, or in some cases even desired. In most B2B scenarios, our customers find that it is preferable \*not\* to perform federated logout for a user.

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2B IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/63F0WOPJdVzsPMxV1Xvp8x/7a329487c5e890d8e820f6a48983b46a/B2B_Project_Planning.pdf)


# Operations (B2B)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-business/operations

How to operationalize your Auth0 tenant environments.

Operationalization requires configuring or setting up infrastructure to support the scalable, measurable, and quantifiable operation that’s necessary for business continuity. In Auth0, this includes configuring supporting services (such as email providers), monitoring services for your deployment, detecting anomalous situations, and making preparations to recover quickly and smoothly when something goes wrong in a production environment.

Establishing effective operational behaviors is something that successful customers have found pays dividends, and there are a number of things you will want to consider when looking at your workflow:

* What should you do to proactively detect failures?
* How can you obtain data on Auth0’s operational status?
* What should you do about Auth0 security bulletins related to the Auth0 service?
* Does Auth0 provide information regarding impending changes in the Auth0 service?
* How can you check for important notices from Auth0?
* What should you do with Auth0 log data so that you can analyze it and keep it for longer than Auth0’s limited data retention period?
* How can you scan Auth0 logs to determine if peak loads in your application trigger any rate limits or other errors?
* What email services should you use to support production volumes of email messages to users? Can I use Auth0's out-of-box email provider in my production environment?
* Do you need to configure your firewall and what firewall ports will you need to open for internal services that need to receive communications from Auth0 (such as custom databases, web services, and email servers)?
* How will you provision new organizations?
* Do you need to provide self-service provisioning for your customer so that they can configure their own organizational <Tooltip href="/docs/glossary?term=IdPs">IdPs</Tooltip>?

Auth0 supports functionality for [monitoring](#monitoring) Auth0 service operation as well as providing information regarding Auth0 [service status](#service-status). In addition, Auth0 makes security-related bulletins as well as information regarding upcoming changes to the Auth0 service available via various [notifications](#notifications). Auth0 [logging](#logging) services also provide extensive functionality for tracing and identifying operational anomalies, including restrictions encountered due to rate limiting and/or excessive loading.

Out-of-box, Auth0 provides email delivery services to help you accelerate your integration. These services, however, are not meant for scale-of-use in production environments, and do not provide for any specific service level or guarantee when it comes to email delivery. Our best practice recommendation, which customers typically follow, involves configuring your own [email service provider](#email-provider-setup).

You may also need to make changes to [infrastructure](#infrastructure) configuration in order to support integration with Auth0 and to support use of Auth0 extensibility. For example, if you need to provide callbacks to your internal or even external infrastructure (e.g., if you need to make external API calls in Actions, Rules, or Hooks, or via custom database scripts if you need to leverage existing legacy identity storage), then you may need to configure your Firewall settings.

Once you know how you want organizations to be represented in your system, you will want too consider how you are going to provision the organization itself. See [Provisioning organizations](#provisioning-organizations) for more information.

In addition, many of our customers have developed one or more self-service portals for use by their customers' organization admins to provide self-service capabilities for configuring their own [IdPs](#self-service-idp-provisioning).

## Service status

The Auth0 [status dashboard](https://status.auth0.com/) together with the Auth0 [uptime dashboard](http://uptime.auth0.com/) shows current and past status of the Auth0 service in a human-readable format. If any monitoring alerts are triggered, and as a first step in troubleshooting, your operations staff should check the status dashboard to see if there is a current outage. The public cloud status page also provides a facility for subscribing to outage notifications, and we also recommend that you check the status of any third-party [external services](/docs/deploy-monitor/monitor/check-external-services-status) you depend on, such as Social Providers. Having this information handy can help quickly eliminate possible causes when troubleshooting an issue and should be at the top of a troubleshooting checklist for developers as well as the help desk staff.

<Info>
  ### Best Practice

  Information on how to check the status of Auth0 as well as any dependent services (such as Social Providers) should be at the top of a troubleshooting checklist for both developers and helpdesk staff, and we recommend you subscribe via the Auth0 status page to set up notification of any status updates.
</Info>

In the event of an outage to the public cloud service, Auth0 performs a Root Cause Analysis (RCA) and publishes the results on the Auth0 status page. Auth0 performs a thorough investigation after an outage—including a determination of root cause, as well as contributing factors and how to prevent the issue from occurring again—and as a result, an RCA document can take a few weeks to be published.

## Email provider setup

Auth0 sends [emails](/docs/customize/email) to users for events such as signup welcome, email validation, breached password, and password reset events. You can customize the email templates for each type of event, and advanced customization of email handling is also possible. Auth0 provides a test email provider with limited capacity for basic testing, but you must set up your own email provider for production use, and customization of email templates will not work until you have established your own provider.

<Info>
  ### Best Practice

  The default Auth0 email provider does not support sending production volumes of email or customization of email templates. You should therefore configure your own email provider before deploying to production.
</Info>

## Infrastructure

### Firewalls

If custom code executing in Auth0 (such as in an Action, Rule, Hook, or custom database scripts) will call a service inside your network, or if you configure an on-premise SMTP provider in Auth0, then you may need to configure your firewall to allow [inbound traffic from Auth0](/docs/secure/security-guidance/data-security/allowlist). The IP addresses to allow through the firewall are specific to each region and are listed on the Rules, Hooks, custom database scripts, and email provider configuration screens in your <Tooltip href="/docs/glossary?term=Auth0+dashboard">Auth0 dashboard</Tooltip>.

## Logging

Auth0 provides extensive capability when it comes to the logging of events, and also in the scanning of logs in order to identify event anomalies (see [logs documentation](/docs/deploy-monitor/logs) for further details). Standard log retention period for Auth0 logs is determined by subscription level with the shortest period being 2 days and the longest period being only 30 days. Leveraging Auth0 support for integrating with external logging services will allow you to retain logs outside of this, and will also provide for log aggregation across your organization.

<Info>
  ### Best Practice

  You should leverage one of the log streaming solutions to send log data to an external log analytics service. This will enable keeping data for longer periods of time and provide advanced analytics on the log data.
</Info>

You should review the log data [retention period](/docs/deploy-monitor/logs/log-data-retention) for your subscription level, and implement a log data export extension to send log data to an external log analytics service. You can use one of our [log streaming solutions](https://marketplace.auth0.com/features/log-streaming) in Auth0 Marketplace.

Development teams can use log files for troubleshooting and detecting intermittent errors that may be hard to find via QA tests. Security teams will probably want log data in case forensic data is ever needed. Exporting log files to services that provide comprehensive analytics can help you see patterns such as usage trends and <Tooltip href="/docs/glossary?term=attack+protection">attack protection</Tooltip> triggers.

### Rate limits and other errors

Auth0 provides a unique error code for errors reported when the [rate limit is exceeded](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy). You should set up automatic scanning of logs to check for rate limit errors so you can proactively address activity that hits rate limits before it causes too much trouble for your users. Auth0 also publishes error codes for other types of errors, and you will find it helpful to scan logs for [authentication errors](/docs/libraries/common-auth0-library-authentication-errors) as well as errors from Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> calls (Management API error codes are shown below each call in the [Management API Explorer](https://auth0.com/docs/api/management/v2)).

<Info>
  ### Best Practice

  Calling the Management API to retrieve user profile information from within a Rule is a common cause of rate limit errors because such API calls can execute for every login as well as periodic session checks.
</Info>

## Monitoring

You should establish mechanisms for [monitoring Auth0 implementations](/docs/deploy-monitor/monitor), so your support or operations team receives the timely information needed to proactively handle service outages. Auth0 provides monitoring endpoints that can be incorporated into your monitoring infrastructure. These endpoints are designed to provide a response suitable for consumption by monitoring services. It should be noted that they only provide data on Auth0. For complete end-to-end monitoring, which is essential for checking the ability of users to log in, we recommend that you set up synthetic transaction monitoring. This will provide greater granularity for your monitoring and enable you to detect outages unrelated to Auth0 as well as degradation of performance, so you can respond more proactively.

<Info>
  ### Best Practice

  You should set up the ability to send synthetic login transactions to facilitate end-to-end monitoring of authentication. You can do this with a simple application that uses the [Resource Owner Password Grant](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow/call-your-api-using-resource-owner-password-flow) in combination with a test user that has no privileges, and don’t forget about [Auth0 rate limiting policies](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy) too.
</Info>

## Notifications

There are several different types of notifications from Auth0 that you should watch for as they contain important information that could impact your tenant(s) and project.

<Callout icon="file-lines">
  Proactive security notifications and other operational announcements are sent by Auth0 to dashboard administrators. You should ensure that the people who need to receive such messages are dashboard administrators.
</Callout>

### Dashboard notifications

From time to time, Auth0 may send an important announcement related to your tenant. These announcements about your service will be sent to your Auth0 dashboard and depending on the severity of the announcement, via email to the registered Auth0 dashboard administrators. You should make a regular practice of logging in to the dashboard and checking the bell icon at the top for any important notices. In addition, you should review emails from Auth0 in a timely fashion as they may convey important information about changes or actions you need to take.

### Auth0 security bulletins

Auth0 regularly conducts a number of security-related tests, and if any issues are found, will proactively identify and notify customers who need to make security-related changes. Due to the extensible nature of the Auth0 product, however, it may not be possible for Auth0 to identify every impacted customer, so you should regularly check Auth0 [security bulletins](/docs/secure).

<Info>
  ### Best Practice

  It is a best practice to check the Auth0 [Security Bulletins](/docs/secure/security-guidance/security-bulletins) page periodically and take the recommended action if you are impacted by any security bulletins.
</Info>

### Change log

Auth0 provides information on changes to the service in the Auth0 [change log](https://auth0.com/changelog). You should make a regular practice of reviewing Auth0 change logs to be aware of changes. Support teams researching an issue may find it useful to review the change log to determine if recent changes might be related, especially if these are [breaking changes](/docs/troubleshoot/product-lifecycle/deprecations-and-migrations). Development teams will also want to review the change logs to identify new features that may be beneficial.

## Provisioning organizations

### best practice

What you need to do when provisioning an organization will depend on how organizations are represented in your system. This can take some time to step back and consider how users of those organizations will be interacting with your applications. See [Multiple Organization Architecture](https://cdn2.auth0.com/docs/1.14516.0/media/articles/architecture-scenarios/planning/Multiple-Organization-Architecture-Multitenancy-Overview.pdf) to determine how to configure organizations for your IAM system.

When provisioning organizations you need to consider the following:

* You will need to add the organization to your own application configuration and/or database
* You will need to make changes to your Auth0 configuration. This will include doing some or all of the following:

  * Create a unique tenant
  * Add a database connection (if you have isolated users per organization)
  * Add an enterprise connection for this organization

    * This will include working with the organization to either update their existing configuration or add configuration for your Auth0 tenant if they are not a legacy organization.
  * Provision an administrator for the organization
* To avoid mistakes, you may want to create an [Organization Admin Portal](#organization-admin-portal) to make it easier to provision new organizations.

### Organization Admin Portal

An organization admin portal is a portal that allows your administrators to create, modify, and remove organizations. There are multiple activities that need to be done both in your own system and your Auth0 tenant. This portal will likely need to exist in your own system so it has access to your datastores and configuration. However, Auth0 provides the [Auth0 Management API](https://auth0.com/docs/api/management/v2) so that you can incorporate changes to your Auth0 tenant at the same time that you create the changes in your own system.

There are two main approaches that can be taken for creating a new organization. The one you choose depends highly on your tolerance for how long it would take to deploy a new organization.

* **Live Updates to your Auth0 Tenant**: If you want to be able to create new organizations in real-time, then you will likely want to make the changes directly to your Auth0 tenant using the Auth0 Management API. This allows the changes to take place in real-time and allow the addition of a new organization to take effect immediately.

<Warning>
  Live Updates do come with some things to consider. There are certain operations that must be done in serial to avoid issues. Enabling clients on a connection, adding callback URL's to an Application are two examples. Any operation in the Management API where you must retrieve an entire list and re-submit the entire list with the new value added to it are operations that must be done in serial to avoid two parallel operations overwriting one of the values.
</Warning>

* **Change the Repository and Re-deploy**: If you are taking advantage of the Deploy CLI (or a custom CLI) as part of your [CI/CD pipeline](/docs/get-started/architecture-scenarios/business-to-business/deployment), you may prefer to push your changes directly to your repository and then kickoff a new deployment instead. This can take a little more time, but it has benefits associated with version history and the ability to backout a change by re-deploying the previous version.

<Info>
  ### Best Practice

  You may want to have a separate repository just for the items that the organizations need so that you don't have to re-deploy other common components and risk making an error.
</Info>

## Self-Service IdP provisioning

While Auth0 [connections](/docs/authenticate/identity-providers) make it easy to configure IdPs, it can be a time-consuming process to onboard customer organization IdPs especially if you are selling to new customer organizations on a regular basis or existing organizations have changing IdP requirements. As a result, many of our customers have found it worthwhile to build a self-service portal for their customers' organization admins so that they can configure their own IdPs. This cuts down on your IT department's workload. The [Auth0 Management API](https://auth0.com/docs/api/management/v2) provides all necessary [connection management functionality](https://auth0.com/docs/api/management/v2#!/Connections/get_connections) to achieve this.

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2B IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/63F0WOPJdVzsPMxV1Xvp8x/7a329487c5e890d8e820f6a48983b46a/B2B_Project_Planning.pdf)

## Multiple Organization Architecture (Multitenancy)

Many B2B platforms implement some form of isolation and/or branding for their customers' organization, and this can add complexity to any Identity and Access Management (IAM) system. If this applies to you, then we recommend you take some time to read through our guidance and best practice advice for this type of environment.

[Multiple Organization Architecture](/docs/get-started/architecture-scenarios/multiple-organization-architecture)


# Profile Management (B2B)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-business/profile-management

User profile management planning considerations for your B2B IAM implementation.

At some point, you may need to change the information stored in a user’s profile. A user’s profile (also known as the user’s account) is stored in Auth0, and changes to the information it contains may need to happen for a number of different reasons:

* Self-served information updates
* Mandatory updates concerning your organizations T's & C’s
* Changes due to regulatory compliance

<Warning>
  You cannot directly access a user profile across multiple Auth0 tenants. If you’re deploying multiple Auth0 tenants to production then this is something you need to be aware of.
</Warning>

An [Identity Provider](/docs/authenticate/identity-providers) populates a user’s profile using data supplied during the login process, and this is referred to as the [Normalized User Profile](/docs/manage-users/user-accounts/user-profiles/normalized-user-profiles).

<Callout icon="file-lines">
  The Normalized User Profile is updated from the identity provider during login, and you can change the limited set of the information it contains through the Auth0 Management API. You can also use Auth0 extensibility, such as [Rules](/docs/customize/rules), as an alternative to override information in the Normalized User Profile. See [User Profile Data Modification](/docs/manage-users/user-accounts/user-profiles#user-profile-data-modification) for more information.
</Callout>

By default, there is one user profile created for each user identity, and there are a number of things to consider:

* What should you do if you need to store information to help customize a user’s experience?
* What if you need to store user information that didn’t originate from an <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>?
* Why would you need to store user-related information that a user cannot modify?
* What do you do if you need to store user-related information that a user cannot modify?
* What happens if a user forgets their password?
* What should a user do if they want to change their password?
* How do you provide an administrator from a third-party organization with the ability to manage their users?

Auth0 provides for the storage of metadata against a user’s profile, which allows for the capture of additional information, such as preference for language and/or accessibility in order to enhance the user experience. Metadata can be used to store both information that a user can change, and also information they can’t; the latter giving you the capability of associating, for example, a user profile with records in your existing systems without modifying existing implementation.

For users who forget their passwords or who are allowed to change their password via some existing self-service mechanism (or self-service mechanism you have planned), you can leverage Auth0-provided [Password Reset](#password-reset) functionality. This can be integrated with your existing implementation and comes already incorporated with any out-of-box Auth0 UI widgets including [Universal Login](/docs/authenticate/login/auth0-universal-login).

You’ll also want to make sure that you are working with a [verified user account](#account-verification) at all times. Auth0 provides out-of-box mechanisms for doing that too. You should also consider [regulatory compliance](/docs/secure/data-privacy-and-compliance) such as ([GDPR](https://eugdpr.org/) which has very specific requirements when it comes to protecting EU citizens from privacy and data breaches.

Though Auth0 doesn’t currently provide a centralized profile management portal out-of-the-box, for the purpose of self-serviced profile management, you can use the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to build your own or utilize an already built UI. See our Auth0 [community guidance](https://community.auth0.com/t/how-to-allow-the-end-user-to-update-their-own-profile-information/6228) which describes the Management API endpoint. All calls to the Management API will require use of an [Access Token](/docs/secure/tokens/access-tokens).

<Warning>
  Self-service profile management can raise security as well as data privacy concerns. For example, you may want to allow a user to change their email address, however, doing so without following best practice security guidance could result in a user locking themselves out of their account, leaking Personally Identifiable Information (PII), or worse, opening up a potential breach in security.
</Warning>

Alternatively, you can use the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> to [manage aspects of a user’s profile](/docs/manage-users/user-accounts/manage-users-using-the-dashboard). Managing a user’s profile via the Auth0 Dashboard is more of an administrative provision and **should not** be used for self-serviced profile management in a production environment. However, the interface provided by the Dashboard can be extremely useful during development as it provides a quick and simple way of manipulating a user’s profile information.

If you need to provide a way for your customers to have an administrator manage their own users when they are storing those credentials in your system, you can either build something yourself or use an Auth0 Extension. See [Admin Portal](#admin-portal) for more information.

## Metadata

In addition to the Normalized User Profile information, [Metadata](/docs/manage-users/user-accounts/metadata) can be stored in an Auth0 user profile. Metadata provides a way to store information that did not originate from an identity provider, or a way to store information that overrides what an identity provider supplies.

<Info>
  ### Best Practice

  Use of Metadata should follow Auth0 [user data storage best practices](/docs/secure/security-guidance/data-security/user-data-storage#metadata). Metadata storage is not designed to be a general purpose data store, and you should still use your own external storage facility when possible. Metadata size and complexity should also be kept to a minimum, and the Auth0 Management API has a strict set of guidance when it comes to updating and/or deleting metadata associated with a user.
</Info>

You can manipulate metadata via both the Auth0 Management API and the Auth0 Authentication API. As is the case when managing the Normalized User Profile, calls to the Management API for manipulating Metadata requires use of an [Access Token](https://auth0.com/docs/api/management/v2/tokens).

<Warning>
  Calls to the Management API are subject to [Auth0 Rate Limiting policy](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy). You must take this into consideration, and to assist, Auth0 generally recommends use of the appropriate [Auth0 SDK](/docs/libraries) for your development environment rather than calling our APIs directly.
</Warning>

### User metadata

User metadata (also referred to as `user_metadata`) is information that can be stored against a user profile and that a user can read and update as part of any self-service profile management. Metadata of this nature may be something like salutation for a user, or a user’s preferred language which could be used to [customize the emails](/docs/customize/email/email-templates) sent by Auth0.

<Info>
  ### Best Practice

  Store any information that you want use to customize Auth0 emails in metadata and preferably `user_metadata` if the user is allowed to change it, such as information used to determine the language for an email.
</Info>

### App metadata

App metadata (also referred to as `app_metadata`) is, on the other hand, information that can be stored with a user profile but can **only be read or updated with appropriate authorization**; `app_metadata` is not directly accessible to a user. This type of metadata could be something like a flag to indicate that the last set of valid terms and conditions was accepted by the user, and a date to indicate when the user accepted them.

## Password reset

For users who forget their passwords or who are allowed to change their password via some existing self-service mechanism, Auth0 provides [Password Reset](/docs/authenticate/database-connections/password-change) functionality. You can integrate this with your existing implementation and comes already incorporated with out-of-the-box Auth0 UI widgets included as part of [Universal Login](/docs/authenticate/login/auth0-universal-login).

<Warning>
  Password change and password reset is only supported for Auth0 [Database Connection](/docs/authenticate/database-connections/password-change) types.
</Warning>

Auth0 <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> provides built-in UX support for password reset using Auth0 Authentication API functionality. Alternatively, you can use the [Auth0 Authentication API](/docs/authenticate/database-connections/password-change#use-the-authentication-api), through one of the Auth0 SDKs appropriate to your development environment. Email templates used during password reset workflow can also be fully customized, whether you use Auth0 out-of-box UI widgets or customized Universal Login.

You can use the Auth0 Management API, on the other hand, to [directly change the password](/docs/authenticate/database-connections/password-change#directly-set-the-new-password) for a user identity defined using a Database Connection type. You can use the Auth0 Management API as part of any self-service profile management implementation, and also as part of any [Change Password page customization](/docs/get-started/architecture-scenarios/business-to-business/branding).

## Account verification

You’ll also need to work with a verified user account at all times and make use of the mechanisms Auth0 provides. You should also consider regulatory compliance like [GDPR](https://eugdpr.org/) which has very specific requirements for protecting EU citizens from privacy and data breaches.

Auth0 provides out-of-box functionality for sending a [verification email](/docs/customize/email/manage-email-flow) to a user's email address to verify their account. By default, Auth0 automatically sends verification emails for any [Database Connection](/docs/authenticate/database-connections/password-change) identity created as part of [self sign-up](/docs/get-started/architecture-scenarios/business-to-business/provisioning#self-sign-up). However, Auth0 also provides a [Management API endpoint](https://auth0.com/docs/api/v2#!/Tickets/post_email_verification) that you can use to send verification emails in cases where email address validation is not performed by a Social Provider upon user registration.

## Blocking users

[Blocking user access](/docs/manage-users/user-accounts/block-and-unblock-users) in Auth0 provides a way to prevent user login to applications under certain conditions. By default, the Auth0 Dashboard provides an out-of-the-box mechanism to give administrators the ability to both block and unblock user access to all applications, and you can implement this functionality via use of the [Auth0 Management API](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id). You can also use Auth0 extensibility to [disable user access to certain applications](/docs/manage-users/user-accounts/manage-user-access-to-applications) as well as provide more fine-grained [access control](/docs/get-started/architecture-scenarios/business-to-business/authorization).

In addition, the Auth0 Management API provides you with the ability to [unblock](https://auth0.com/docs/api/management/v2#!/User_Blocks/delete_user_blocks_by_id) users disabled due to excessive use of incorrect credentials.

## Admin portal

An admin portal is an application where you can create new users, edit a user’s profile, see activity about a user, etc. This application should be accessible by administrators only. Though Auth0 provides its management dashboard, it is not advised to give access to the management dashboard to many people as there are a lot of ways someone can unintentionally break your Auth0 tenant. Instead, Auth0 provides two other options:

* [**Auth0 Management API**](https://auth0.com/docs/api/management/v2): With the Management API you can easily construct an application that provides administrators the ability to manage users. You can either incorporate this into an existing application that already exists for your administrators, or create a new one with a UI that matches your current applications.
* [**Auth0 Delegated Administration Extension**](/docs/customize/extensions/delegated-administration-extension): This powerful and flexible extension allows you to customize a user administration experience. You can tailor this extension so that you can allow your customer admins to log in and allow them to only see and manage users within their organization.

<Info>
  ### Best practice

  If you are providing your own way for an administrator to manage users, you should only allow administrators to send users a change password link through email rather than allowing administrators to set passwords directly. If you must go against this recommendation and allow your administrators to set someone’s password, you should force the user to change their password at their next login so that only they know the password (and not an administrator as well).
</Info>

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2B IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/63F0WOPJdVzsPMxV1Xvp8x/7a329487c5e890d8e820f6a48983b46a/B2B_Project_Planning.pdf)

## Multiple Organization Architecture (Multitenancy)

Many B2B platforms implement some form of isolation and/or branding for their customers' organization, and this can add complexity to any Identity and Access Management (IAM) system. If this applies to you, then we recommend you take some time to read through our guidance and best practice advice for this type of environment.

[Multiple Organization Architecture](/docs/get-started/architecture-scenarios/multiple-organization-architecture)


# Provisioning (B2B)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-business/provisioning

User provisioning functionality and considerations for your B2B IAM implementation.

Determining how users get signed up is important to address early, and the decisions you make here will influence many of the decisions you will need to make going forward. We’ve found there are a typical set of patterns for how users will get added to your system, and things to take note of when considering workflow design too.

<Info>
  ### Best practice

  While Auth0 supports numerous workflows, web based workflows using Auth0 [Universal Login](/docs/authenticate/login/auth0-universal-login) for sign up are considered both industry and Auth0 best practice as they provide for optimal functionality and the best security.
</Info>

Auth0 supports user sign up via a number of different [identity providers](/docs/authenticate/identity-providers). During sign up, Auth0 provisions the user profile so that it contains the user’s account information. There are a number of things to consider when looking at functionality and workflow:

* Does a user get added to your company's domain or do they belong to or remain in their organization's domain?
* If the user stays in their own domain, do they belong to a single organization or can they belong to multiple organizations?
* How do you provision the organization itself in your system?
* Should you use Auth0 as an identity store?
* Can you use your own (legacy) identity store with Auth0?
* How do you migrate user identities from your identity store to Auth0?
* Can your users sign up using their organization's <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>?
* Can your users be invited or self register?

One of the first determinations to make when providing your service(s) to other businesses is identifying to which domain users belong. Based on the answer to that question, there are a couple of different approaches you can take to provision those users. See [Provisioning organization users](#provisioning-organization-users) for more information. Once you know how you want organizations to be represented in your system, you will want to consider how you are going to provision the organization itself. See [Provisioning organizations](#provisioning-organizations) for more information.

Auth0 provides out-of-the-box identity storage that can be leveraged to store user credentials safely and securely. See [Self Sign Up](#self-sign-up) for more information. If you already have a legacy identity store and you want to offload the management of it, then the [User Migration](#user-migration) capabilities provide you with a number of options to do so.

Alternatively, if you have to maintain your legacy identity store - perhaps because you’ve got applications which you aren’t ready to migrate or which can’t be migrated - then you can use the [identity store proxy](#identity-store-proxy) capability. Allowing your customers to use “bring their own identity” is also an attractive proposition and though we find our customers don’t initially do so, you can use the [Social Sign Up](#social-sign-up) capability to provide it.

## Provisioning organizations

What you need to do when provisioning an organization will depend on how organizations are represented in your system. This can take some time to step back and consider how users of those organizations will be interacting with your applications. See [Multiple Organization Architecture](/docs/get-started/architecture-scenarios/multiple-organization-architecture) to determine how to configure organizations for your IAM system.

When provisioning organizations you need to consider the following:

* You will need to add the organization to your own application configuration and/or database
* You will need to make changes to your Auth0 configuration. This will include doing some or all of the following:

  * In rare cases: create a unique tenant for the organization
  * Create a new Organization in your Auth0 Tenant
  * Add a new a database connection for that Organization (if you have isolated users per organization)
  * Enable the existing shared database connection for that Organization (if you are sharing users)
  * Add an enterprise connection for this Organization and enable it on the Organization

    * This will include working with the organization to either update their existing configuration or add configuration for your Auth0 tenant if they are not a legacy organization.
  * Provision an administrator for the organization
* To avoid mistakes, you may want to create an [Organization Admin Portal](#organization-admin-portal) to make it easier to provision new organizations.
* You may also want to create a Self-Signup portal for your Organizations. This allows your customers to create the organization themselves. This can be part of the [Organization Admin Portal](#organization-admin-portal).

### Organization Admin Portal

An organization admin portal is a portal that allows your administrators to create, modify, and remove organizations. These administrators can either be employees of your company, or customer admins. There are multiple activities that need to be done both in your own system and your Auth0 tenant. This portal will likely need to exist in your own system so it has access to your datastores and configuration. However, Auth0 provides the [Auth0 Management API](https://auth0.com/docs/api/management/v2) so that you can incorporate changes to your Auth0 tenant at the same time that you create the changes in your own system.

There are two main approaches that can be taken for creating a new organization. The one you choose depends highly on your tolerance for how long it would take to deploy a new organization.

* **Live Updates to your Auth0 Tenant**: If you want to be able to create new organizations in real-time, then you will likely want to make the changes directly to your Auth0 tenant using the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. This allows the changes to take place in real-time and allow the addition of a new organization to take effect immediately. Particulary if you are providing Self-Signup for organizations you may want to do this approach.

<Warning>
  Live Updates do come with some things to consider. There are certain operations that must be done in serial to avoid issues. Enabling clients on a connection, adding callback URL's to an Application are two examples. Any operation in the Management API where you must retrieve an entire list and re-submit the entire list with the new value added to it are operations that must be done in serial to avoid two parallel operations overwriting one of the values.
</Warning>

* **Change the Repository and Re-deploy**: If you are taking advantage of the Deploy CLI (or a custom CLI) as part of your [CI/CD pipeline](/docs/get-started/architecture-scenarios/business-to-business/deployment), you may prefer to push your changes directly to your repository and then kickoff a new deployment instead. This can take a little more time, but it has benefits associated with version history and the ability to backout a change by re-deploying the previous version. You may want to have a separate repository just for the items that the organizations need so that you don't have to re-deploy other common components and risk making an error.

## User migration

In addition to hosting the [User Profile](/docs/get-started/architecture-scenarios/business-to-business/profile-management), Auth0 also has the capability to both [proxy](#identity-store-proxy) your own legacy identity store and provide a secure Auth0 hosted replacement. Both of these capabilities are supported via the use of Auth0 [Database Connections](/docs/authenticate/database-connections). If you decide to use Auth0 as a replacement for your legacy identity store then you can [migrate users](/docs/manage-users/user-migration) either all at once with bulk migration, or progressively with automatic migration.

<Info>
  ### Best Practice

  Customers often opt for a two-stage approach to user migration, using Automatic Migration first to migrate as many users as possible, then using Bulk Migration for the users that remain. See [User Migration Scenarios](/docs/manage-users/user-migration/user-migration-scenarios) for more information.
</Info>

Automatic Migration is preferred as it allows users to be migrated individually and also allows them to retain their existing passwords in almost all situations. For Bulk Migration, we recommend using the [Management API](https://auth0.com/docs/api/management/v2#!/Jobs/post_users_imports) over the [User Import/Export extension](/docs/manage-users/user-migration/user-import-export-extension) in all but the most simple cases, as the Management API provides for greater flexibility and control.

With Bulk Migration users typically need to **reset their password once the migration is complete** unless passwords are stored hashed in your legacy identity store using one of the supported algorithms. In this case, you may be able to use bulk migration and **preserve user passwords** as part of the process, depending on the algorithm and the number of salt rounds used. See [Bulk Import Database Schema Examples](/docs/manage-users/user-migration/bulk-user-import-database-schema-and-examples) for more information.

<Warning>
  Importing hashed passwords relies on the source identity store using idiomatic implementations of one of the following algorithms: argon2, bcrypt, hmac, ldap, md4, md5, sha1, sha256, sha512, pbkdf2, and scrypt.
</Warning>

<Info>
  ### Best Practice

  Calls to the Management API are subject to [Auth0 Rate Limiting policy](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy). You must take this into consideration, and to assist, Auth0 generally recommends use of the appropriate [Auth0 SDK](/docs/libraries) for your development environment rather than calling our APIs directly.
</Info>

### Identity store proxy

Auth0 Database Connection types can also be configured to proxy an existing (legacy) identity store. If you need to keep user identities defined in your own legacy store - for example, if you have one or more business critical applications that you can’t migrate to Auth0, but which still need access to these identities - then you can easily integrate with Auth0. See [Authenticate Users Using Your Database](/docs/authenticate/database-connections/custom-db) for more information.

## Provisioning organization users

An organization should map directly to one of your business customers/partners. Each business/partner that you are working with has users who will be logging in. We call those end users "organization users". There are two different approaches to how to store your organization users:

* **Isolated to the organization**: Every user belongs to exactly one organization. It would not make sense for that user to be a part of more than one organization, and even if they were, it would make sense for them to have a separate “identity” for that other organization. For example, a retail employee that works part time at two different stores has two different logins for each of those stores even if the stores both use the SaaS application. To learn more, see [Provisioning users isolated to the organization](#provisioning-users-isolated-to-the-organization).
* **Shared between organizations**: In a case like this, users either create credentials in your company, or they can access other organizations instances of your application using credentials from their own organization. A simple way to look at this is that one user may be authorized to access more than one organization’s instance of the application. A user would understand that they can use the same credentials to access both instances of an application. For example, some doctors contract with multiple clinics and may need to be able to sign into each separate clinic with their same credentials. To learn more, see [Provisioning users shared between organizations](#provisioning-users-shared-between-organizations).

### Provisioning users isolated to the organization

Isolating users to the organization can provide a nice clean barrier between organizations. If no users ever need to access more than one organization (or you would rather force them to create multiple accounts), then this is an attractive approach.

You need to provision those users at the IdP level. Each of the organizations will have its own IdP for accomplishing this. This IdP will come in one of three flavors:

* **Your Auth0 Tenant is the IdP**: A Database Connection in your main tenant dedicated to this organization.
* **Organizations bring their own IdP**: You set up an Enterprise Connection for them.
* **Organizations with more than one IdP**: You enable more than one Enterprise Connection, Social Connection, and also may have a single Database Connection. When the user chooses their organization and attempts to log in, they will be able to choose from all of the connections that have been enabled for that organization.

We recommend using Auth0 as an IdP as a starting point because it’s simple to implement a [user invite workflow](/docs/manage-users/organizations/configure-organizations/invite-members). Compared to other invite flows, the only thing special about this is that the person who is creating the user will have to either select the organization ahead of time, or the system will force the organization to match that of the user doing the inviting (in situations where there is an organization administrator who belongs to that organization only).

<Info>
  ### Best Practice

  If you can utilize the [Organizations Feature](/docs/manage-users/organizations), it will greatly simplify your login system, making it more maintainable and extendable for the future. See [Multiple Organization Architecture](/docs/get-started/architecture-scenarios/multiple-organization-architecture) for a more in-depth view.
</Info>

### Provisioning users shared between organizations

When sharing users between organizations, you will need a way to authorize access. Because you won’t know where a user might belong when authenticating, we typically recommend storing your users in a single domain and then figuring out which organizations they can access by adding them as [members of the organization](/docs/manage-users/organizations/configure-organizations/assign-members). Because of this, provisioning will often be done by starting with a User Invite workflow for the single database connection, and then they will be added to the organization using the management API. You can then use the management API to retrieve which [organizations the user belongs to](/docs/manage-users/organizations/configure-organizations/retrieve-user-membership) if you need to provide a way for them to switch between organizations.

### Deprovisioning limitations

Auth0 will not communicate with the upstream IdP if there is an active <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> session with Auth0 unless you force it with a `prompt=login`. If one of your customer organizations can not manage logout for those users, they may still have access after they’ve been decommissioned. Depending on the IdP, if Auth0 gets a token for their API, you can request information about the user from the IdP in a [rule](/docs/customize/rules) to poll whether that user should still have access or not. If you don’t have this ability, you will have to provide your customer organizations with a way to trigger a block or decommission of users in your system either through an API call or a UI.

## User invite

In most B2B scenarios, only particular individuals are allowed access to the application. As a result, it is often simpler to have an administrator provision user accounts rather than having users sign up and then have an administrator approve them. Provisioning can often be done in an automated fashion when users are added to a centralized system as well.

There are three different personas who might be [inviting users](/docs/customize/email/send-email-invitations-for-application-signup):

* An administrator at your company may create the users for each organization.
* An administrator from each organization may be assigned to creating users.
* Another system responsible for creating users may exist, and that system may then create a user in Auth0. Regardless of the <Tooltip href="/docs/glossary?term=audience">audience</Tooltip>, the technique can be similar. The rest is a matter of using the right authorization model for the application.

The recommended approach for user invite is to use the [Organizations Feature](/docs/manage-users/organizations/configure-organizations/invite-members) to accomplish this. If you are **not** using the Organizations Feature to implement user invites and are building your own, it is important to create each user with the `user.email_verified` parameter set to `false` and a random temporary password. The generated password should only be known to Auth0 and **not** stored in any external system nor passed to the user! Then, use the [Management API](https://auth0.com/docs/api/management/v2#!/Tickets/post_password_change) to send an email to the user with a link to reset their password; you can even modify the email template in Auth0 to reflect that this is part of an invited sign-up workflow too. This ensures that the user's email address belongs to the user being created and the only person who knows the password is the user themselves.

<Warning>
  One of the main principles of OIDC is that no one except the user themselves ever knows their password. If you are doing an invite flow, have your backend system randomly generate a password and then discard it and have your user reset their password before ever logging in. Do not create a temporary password and give it to them to log in the first time.
</Warning>

## Enterprise sign up

Enterprise sign up is synonymous with sign in via [enterprise login](/docs/get-started/architecture-scenarios/business-to-business/authentication)—there’s no distinction here per se, as user [profile](/docs/get-started/architecture-scenarios/business-to-business/profile-management) creation happens automatically upon first enterprise login.

<Info>
  ### best practice

  A nice advantage of allowing your customers to use their own IdP is that they can administer their users and assign roles and access in their own IdP setup instead of forcing you to build administration for them. Working out the mapping for those customers will make this much easier.
</Info>

<Warning>
  If mapping isn't enough and you must put some metadata in your system, keep in mind that Auth0 will not create the user until they log in to the system the first time. Therefore, you will need to use rule extensibility to pull the initial information from somewhere else, or force users to log in the first time before you can add the metadata.
</Warning>

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2B IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/63F0WOPJdVzsPMxV1Xvp8x/7a329487c5e890d8e820f6a48983b46a/B2B_Project_Planning.pdf)

## Multiple Organization Architecture (Multitenancy)

Many B2B platforms implement some form of isolation and/or branding for their customers' organization, and this can add complexity to any Identity and Access Management (IAM) system. If this applies to you, then we recommend you take some time to read through our guidance and best practice advice for this type of environment.

[Multiple Organization Architecture](/docs/get-started/architecture-scenarios/multiple-organization-architecture)


# Quality Assurance (B2B)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-business/quality-assurance

Quality Assurance considerations for your B2B IAM implementation.

Quality Assurance is important in identifying issues before they impact your customers and, depending on the nature of your project, there are several different types of quality assurance testing that you’re going to want to consider as part of your integration with Auth0:

* Is your application easy to understand and use, even by those with a disability?
* Does your application need to work across various different browsers and devices?
* Does your application need to work in multinational and/or international environments?
* How will your application perform when subjected to unexpected production loads?
* How can you ensure your application is safe from security-related vulnerabilities?

Auth0 [Universal Login](/docs/authenticate/login/auth0-universal-login) and associated UI widgets (such as [Lock](/docs/libraries/lock)) have already been designed and built following usability and accessibility best practices, and provide tested out-of-box support for a whole host of [browsers and devices](/docs/troubleshoot/customer-support/product-support-matrix). Support for [internationalization](/docs/customize/internationalization-and-localization) (I18N) is also provided out-of-box, with built-in extensibility designed for custom multi-language and localization (L10N) situations.

To ensure functional requirements are met and unexpected events are handled correctly, guidance is provided for testing the [integration](#integration-testing) between your application(s) and Auth0, and for [unit testing](#unit-testing) individual extensibility modules (such as [Rules](/docs/customize/rules/debug-rules), [Hooks](/docs/customize/hooks/update-hooks), and Custom Database scripts). Guidance is also provided regarding Auth0's [penetration testing policy](/docs/troubleshoot/customer-support/operational-policies/penetration-testing-policy) to help when testing for security vulnerability, and also how [Mock](#mock-testing) testing can be leveraged in conjunction with our [load testing policy](/docs/troubleshoot/customer-support/operational-policies/load-testing-policy) to help ensure your application(s) perform under unexpected load.

## Unit testing

The objective of unit testing is to test individual units of code. If you create custom code within Auth0 in the form of Rules, Hooks, and/or Custom DB scripts, you should consider use a testing framework (such as [Mocha](https://mochajs.org/)) to test your code. Companies who have been most successful with Auth0 have found it useful to execute these unit tests prior to [automatically deploying](/docs/get-started/architecture-scenarios/business-to-business/deployment) Auth0 tenant configuration and collateral.

## Integration testing

It is a recommended best practice that you set up different tenants for development, testing, and production as discussed in Architecture guidance for [SDLC support](/docs/get-started/architecture-scenarios/business-to-business/architecture#sdlc-support). Auth0 allows you to configure variables that are available from within custom [extensibility](/docs/customize/extensions); these can be thought of as environment variables for your Auth0 tenant. Rather than hard code references that change when moving code between development, test, and production environments, you can use a variable name that is configured in the tenant and referenced by the custom extensibility code. This makes it easier for the same custom code to function, without changes, in different tenants as the code can reference variables which will be populated with tenant-specific values at execution time:

* For use of variables in Rules, see how to [configure values](/docs/customize/rules/configuration)
* For use of variables in Hooks, see how to configure [secrets](/docs/customize/hooks/hook-secrets) in the editor
* For use of variables in Actions, see Explore Flows and Triggers
* For use of variables in Custom DB Scripts, see the [configuration parameters](/docs/authenticate/database-connections/custom-db/create-db-connection#step-3-add-configuration-parameters)

<Info>
  ### Best Practice

  It’s a recommended best practice to use variables to contain tenant-specific values as well as any sensitive secrets that should not be exposed in your custom code. If your custom code is deployed in GitHub, then using a tenant-specific variable avoids exposure of sensitive values via your GitHub repository.
</Info>

### Test automation

You can automate your overall build process by incorporating deployment automation as well as test automation. This can be used to deploy new versions of configuration and/or custom code to Auth0 and execute automated tests. If the tests uncover any failures, the deployment automation capabilities can be used to revert to the last working version. For further information, see the [deployment automation guidance](/docs/get-started/architecture-scenarios/business-to-business/deployment) provided.

## Mock testing

In a balance between Auth0’s [load testing policy](/docs/troubleshoot/customer-support/operational-policies/load-testing-policy) and the desire to load test, it is common practice among Auth0’s customers to mock out Auth0’s endpoints. This is a valuable practice in order to ensure that your application works with your expected interfaces without having to restrict your testing, and tools such as [MockServer](http://www.mock-server.com/), [JSON Server](https://github.com/typicode/json-server) or even [Postman](https://learning.getpostman.com/docs/postman/mock_servers/setting_up_mock/) can be used to assist.

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2B IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/63F0WOPJdVzsPMxV1Xvp8x/7a329487c5e890d8e820f6a48983b46a/B2B_Project_Planning.pdf)

## Multiple Organization Architecture (Multitenancy)

Many B2B platforms implement some form of isolation and/or branding for their customers' organization, and this can add complexity to any Identity and Access Management (IAM) system. If this applies to you, then we recommend you take some time to read through our guidance and best practice advice for this type of environment.

[Multiple Organization Architecture](/docs/get-started/architecture-scenarios/multiple-organization-architecture)


# Business to Consumer
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-consumer

Explains the architecture scenario B2C IAM with an eCommerce or SAAS application.

This guidance is relevant to **all** project stakeholders. We recommend reading it in its entirety at least once, even if you've already started your journey with Auth0. We provide a Project Planning Guide in PDF format, details about how to get started with each phase of the implementation process, and checklists to help you manage the tasks in each phase.

There are many different ways Auth0 can be integrated into the CIAM project architecture. Auth0's flexibility comprehensively supports many different use cases however your project may not require all of the capabilities provided by Auth0. Knowing what, when, and how best to implement something will help you focus on completing the necessary tasks at the right time.

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2C IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/3er1aEQ7Ul0q3c9leJWczR/b1f18b4c16abb7e78b01e4eb2b52bb8e/B2C_Project_Planning.pdf)

## Get started

Customers using Auth0 for Business-to-Consumer (B2C) projects typically share a common set of goals and objectives, and in the sections that follow we'll focus on our real-world customer implementation experiences to help you deliver your solution efficiently.

<Info>
  ### Best Practice

  Auth0 provides recommendations and best practice suggestions in an *ad hoc* way throughout this guide in panels like this one. You can also obtain detailed guidance regarding specific functionality by speaking with your account representative or a member of our Auth0 [Professional Services](/docs/get-started/professional-services) team.
</Info>

<table>
  <thead>
    <tr>
      <th><strong>Read</strong></th>
      <th><strong>To learn...</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/business-to-consumer/architecture">Architecture</a></td>
      <td>How to configure your Auth0 tenant architecture affects your B2C IAM implementation.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/business-to-consumer/provisioning">Provisioning</a></td>
      <td>About user provisioning functionality and considerations for your B2C IAM implementation.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/business-to-consumer/authentication">Authentication</a></td>
      <td>How authentication works in your B2C IAM implementation.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/business-to-consumer/branding">Branding</a></td>
      <td>How to configure Auth0 items to reflect your brand and desired user experience.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/business-to-consumer/deployment">Deployment Automation</a></td>
      <td>How Auth0 tooling helps to automate tenant deployment.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/business-to-consumer/quality-assurance">Quality Assurance</a></td>
      <td>About quality assurance considerations for your B2C IAM implementations.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/business-to-consumer/profile-management">Profile Management</a></td>
      <td>About user profile management planning considerations for your B2C IAM implementation.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/business-to-consumer/authorization">Authorization</a></td>
      <td>About user authorization and related planning considerations for your B2C IAM implementation.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/business-to-consumer/logout">Logout</a></td>
      <td>About user logout planning considerations for your B2C IAM implementation.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/business-to-consumer/operations">Operations</a></td>
      <td>How to operationalize your Auth0 tenant environments.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/architecture-scenarios/business-to-consumer/launch">Launch Preparation</a></td>
      <td>About launch preparation considerations for your B2C IAM implementation.</td>
    </tr>
  </tbody>
</table>

## Implementation planning checklists

Use the links below to download a spreadsheet that includes tasks for each phase of a Software Development Lifecycle (SDLC) project.

[Analyze Checklist](https://cdn2.auth0.com/docs/media/articles/architecture-scenarios/checklists/Analyze-Checklist.xlsx)

[Design Checklist](https://cdn2.auth0.com/docs/media/articles/architecture-scenarios/checklists/Design-Checklist.xlsx)

[Build Checklist](https://cdn2.auth0.com/docs/media/articles/architecture-scenarios/checklists/Build-Checklist.xlsx)

[Test Checklist](https://cdn2.auth0.com/docs/media/articles/architecture-scenarios/checklists/Test-Checklist.xlsx)

[Deploy Checklist](https://cdn2.auth0.com/docs/media/articles/architecture-scenarios/checklists/Deploy-Checklist.xlsx)

[Monitor Checklist](https://cdn2.auth0.com/docs/media/articles/architecture-scenarios/checklists/Monitor-Checklist.xlsx)


# Architecture (B2C)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-consumer/architecture

Learn how to configure your Auth0 tenant architecture affects your Business to Consumer (B2C) Identity and Access Management (IAM) implementation.

Understanding your <Tooltip href="/docs/glossary?term=Application">application</Tooltip> is key to understanding how Auth0 can be leveraged to meet your needs. From experience, our most successful customers start with a visualization of their proposed - or in many cases existing - architecture and use this as a basis for reference as they progress. Understanding where your application fits within your organization is also important; Auth0 [Accounts and Tenants](/docs/get-started/auth0-overview/create-tenants) form the basis for the grouping and structuring of Auth0 assets, and it may be that you’ll need to leverage an existing Auth0 deployment in order to integrate with [Single Sign-on (SSO)](/docs/authenticate/single-sign-on), centralized user [Profile Management](/docs/get-started/architecture-scenarios/business-to-consumer/profile-management), consolidated billing, or the like.

<Callout icon="file-lines">
  If you do have multiple applications, and you need to leverage SSO, then we recommend you check out our [How to Implement Single Sign-On](https://auth0.com/learn/how-to-implement-single-sign-on/) training guidance before continuing.
</Callout>

The value of investing time on the landscape of the architecture up-front is something that we have found pays dividends in the long run, and there are a number of things you will want to consider when looking at functionality and workflow:

* What should the URL look like when Auth0 needs to present a web page to a user?
* How can Auth0 be structured to support your SDLC (Software Development Lifecycle)?
* How can you ensure that your Auth0 tenants are appropriately associated with your contract?
* What do you need to consider if there are other projects in your organization integrating with Auth0? Particularly projects that target their own, or a different domain of users (for example, applications that only employees will use)?

<Tooltip href="/docs/glossary?term=Organizations">Organizations</Tooltip> often service more than one domain of user - customers, employees, and affiliates being the most frequently encountered, with typically little to no cross-over: employees, say, don’t use the same applications as customers and vice-versa. In some cases there can also be a need to partition further within a domain - separate groups of customers, say, who use different and unconnected products. Auth0 provides a way to segregate your users and the associated collateral, and [tenant provision](#tenant-provision) covers this in more detail. If you need to provision an independent <Tooltip href="/docs/glossary?term=Tenant">tenant</Tooltip> then you’ll also want to [associate this with your existing Auth0 account](#tenant-association), so that you can take full advantage of the benefits provided at your organization’s contracted <Tooltip href="/docs/glossary?term=Subscription">subscription</Tooltip> level.

<Callout icon="file-lines">
  It’s not uncommon for companies to have identity requirements that address multiple user communities: customers, partners, employees, etc. So be sure to consider other projects or future requirements when designing your architecture.
</Callout>

In addition, you’ll undoubtedly have an established set of processes and procedures as part of your Software Development Lifecycle (SDLC). So you’ll want to check out our [SDLC support](#sdlc-support) guidance regarding Auth0 Tenant provision in support of that too.

For customer-facing applications, we typically see [OpenID Connect (OIDC)](/docs/authenticate/protocols/openid-connect-protocol) as being the most frequently used protocol. OIDC makes use of web based workflows with browser URLs that are presented to the user. Out-of-the-box, client facing URLs as part of Auth0 OIDC support are Auth0 branded, however we recommend using the Auth0 [custom domain](#custom-domains) capability to provide for consistent corporate identity and to also address potential user confidence concerns before they arise.

<Callout icon="file-lines">
  Other groups within your organization may also be working with Auth0; it’s not uncommon for our customers to have disparate departments that serve different user communities. Identifying these will potentially influence your design choices, and doing so early could mitigate decisions that might prove costly later on.
</Callout>

## Tenant provision

Everything starts with an Auth0 tenant. This is where you will be configuring your use of Auth0, and the where Auth0 assets - such as [Applications](/docs/get-started/applications), [Connections](/docs/authenticate/identity-providers) and [user profiles](/docs/get-started/architecture-scenarios/business-to-consumer/profile-management) are defined, managed and stored. Access to an Auth0 tenant is performed via the Auth0 [Dashboard](/docs/get-started/auth0-overview/dashboard), and via the Dashboard you can also create additional, associated tenants; you’re allowed to create more than one Auth0 tenant so that you can structure your tenants in a way that will isolate different domains of users and also support your [Software Development Life Cycle](#sdlc-support) (SDLC).

<Warning>
  Tenant names cannot be changed, nor reused once deleted. So, make sure you're happy with your name(s) before you create your Auth0 tenants.
</Warning>

Determining the level of isolation you require when it comes to your user domains is an important step, and together with your branding requirements will subsequently help you determine the number of Auth0 tenants that will be required in your production environment. As we recommend you create a full suite of [SDLC supporting tenants](#sdlc-support) for every Auth0 tenant you will run in a production environment, the number of Auth0 tenants you will need to manage can quickly grow. Therefore you should consider carefully before creating multiple Auth0 tenants for production, and should consult our guidance on [Branding](/docs/get-started/architecture-scenarios/business-to-consumer/branding) before making your final decision.

## Tenant association

To ensure that your [tenants are all associated with your Auth0 contractual agreement](/docs/get-started/auth0-overview/create-tenants/child-tenants) and have the same features, ensure all your tenants are associated with your company account. If you have individual developers that want to create their own sandboxes for testing, make sure they get associated with your account so they have the same permissions too. To do this you should contact your Auth0 representative or the [Auth0 Support Center](https://support.auth0.com).

## Custom domains

When you setup your Auth0 tenant, the URL for accessing that tenant will be of the form `https://yourTenant.auth0.com`. Providing a [Custom Domain](/docs/customize/custom-domains) (also known as a vanity URL), for your Auth0 tenant is not only an important factor for supporting your Branding requirements, but more importantly will also provide you with security benefits too:

* Some browsers will, by default, make it [difficult to communicate in an iFrame if you don't have a shared domain](/docs/troubleshoot/authentication-issues/renew-tokens-when-using-safari).
* It's [harder to phish your domain if you have a vanity URL](https://auth0.com/blog/introducing-custom-domains-preview-with-auth0/), as the phisher must also create a vanity URL to mimic yours. For example, with a <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip> you can use your own certificate to get an "Extended Validation", making phishing even harder.

<Callout icon="file-lines">
  You are allowed only one custom domain per Auth0 Tenant. This is because a tenant in Auth0 is intended to represent a “domain” of users. If you need more than one vanity URL, then you likely have more than one domain of users and should be using multiple tenants.
</Callout>

Your custom domain name should also give the user confidence that this is the appropriate place to enter their credentials, and we recommend that you create your custom domain in all environments early on to ensure that you are testing consistently between environments. **It's extremely important to train your users to look for suspicious URLs when entering their credentials!**

<Callout icon="file-lines">
  Create a custom domain (a.k.a. `CNAME`) for your Auth0 tenant, and also create one in development too so you can ensure you have managed the `CNAME` correctly. For example, you could create a `CNAME` which maps `login.mycompany.com` to `mycompany-prod.auth0.com`.
</Callout>

In almost all cases, customers have been most successful when adopting a strategy of a centralised domain for authentication across multiple product or service brands. This strategy provides users with a consistent UX, and also mitigates the complexity of deploying and maintaining multiple Auth0 tenants in a production environment. If you are considering having multiple domains for different brands, please refer to the [Branding](/docs/get-started/architecture-scenarios/business-to-consumer/branding) guidance before you begin implementing.

## SDLC support

Every company has some form of Software Development Life Cycle (SDLC), and throughout the development process you will want to align with that strategy. For instance, you need to be able to test your integration with Auth0 in a similar fashion as you test the applications themselves. It is therefore important to [structure Auth0 tenants to support your SDLC](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments), and there is a consistent pattern which our customers typically follow when it comes to the best practices associated with tenant layout for doing so:

<table>
  <thead>
    <tr>
      <th>Environment</th>
      <th>Sample Tenant Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Development</td>
      <td><strong>company-dev</strong></td>
      <td>A shared environment where most of your development work occurs</td>
    </tr>

    <tr>
      <td>QA/Testing</td>
      <td><strong>company-qa</strong> or <strong>company-uat</strong></td>
      <td>An environment for formal testing of the changes you've made</td>
    </tr>

    <tr>
      <td>Production</td>
      <td><strong>company-prod</strong></td>
      <td>The production tenant</td>
    </tr>
  </tbody>
</table>

In some cases you may also want to create one or more sandboxes (e.g., **company-sandbox1**, **company-sandbox2**) so that you can test changes without compromising your development environment. This might be where you test deployment scripts and the like.

<Callout icon="file-lines">
  You can also take advantage of our [Implementation Checklists](/docs/get-started/architecture-scenarios/checklists) that you can download and customize to meet your implementation project needs.
</Callout>

## Project planning guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2C IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/3er1aEQ7Ul0q3c9leJWczR/b1f18b4c16abb7e78b01e4eb2b52bb8e/B2C_Project_Planning.pdf)


# Authentication (B2C)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-consumer/authentication

How authentication works in your B2C IAM implementation.

To provide services to your users, you must be able to identify who those users are. This process is called User Authentication. There are a number of ways to perform authentication of a user—via social media accounts, username and password, <Tooltip href="/docs/glossary?term=passwordless">passwordless</Tooltip>—and it's often recommended that you go beyond a first factor for authenticating the user by enabling <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA).

<Info>
  ### Best Practice

  It's important to consider both security and user experience when designing how you will authenticate your users. Providing for multiple primary factors, and/or enforcing more than one factor during authentication, are ways that you can provide both.
</Info>

There are a number of things you will want to consider when looking at functionality and workflow:

* Where will users enter their credentials?
* How will you keep user credentials safe?
* How will you maintain your authentication system?
* How can you provide password authentication for your users?
* How can you prevent hackers from trying to log in as your users?
* How will you implement authentication in different kinds of applications?
* How can you make login easy for your users when they come from different language backgrounds?
* How will you provide a good user experience as you migrate away from any legacy authentication system?
* What should you consider when integrating applications with Auth0?
* Can users log in using their existing social (e.g., Facebook or Google) accounts?
* Do you need to provide multi-factor authentication?
* What do you do if you have a service that doesn't have a way for the user to log in ahead of time?
* Can you pass the same user <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> from one API to another?

Auth0 [Universal Login](#universal-login) provides users with a safe and secure experience—no matter whether you choose to provide for user ID/password credentials sign in, or allow the so-called Bring Your Own Identity scenarios provided via [Social Login](https://auth0.com/learn/social-login/). There are also brand recognition benefits to centralizing the login experience with <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>, even if you feel you will also have product-specific [branding](/docs/get-started/architecture-scenarios/business-to-consumer/branding) requirements. The Auth0 UI widgets typically used with Universal Login also provide out-of-the-box support with regards to [internationalization](/docs/customize/internationalization-and-localization/universal-login-internationalization) for users with different language requirements, and out-of-the-box support for Auth0 features such as [MFA](#multi-factor-authentication-mfa-) and [attack protection](#anomaly-detection) allow you to put barriers in place in order to prevent hackers attempting to access users' accounts.

Allowing users to sign in via user ID/password credentials means that you're not reliant on the status of third-party <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> for your users to access your system. You also have the means to require the credentials used to align with your corporate policies. Auth0 assists with this by providing you with multiple options in support of user ID/password logins, and the [guidance provided](#username-and-password-authentication) will help you understand you can leverage these options. Adding [social](#social-authentication) support at some stage, as an additional primary authentication factor, gives you added flexibility and can help you better understand your users without the need to question them further by leveraging the information already stored by the various social login [providers](/docs/authenticate/identity-providers/social-identity-providers).

If you have an existing legacy identity store, you’ll also want to see [User Migration](/docs/get-started/architecture-scenarios/business-to-consumer/provisioning). This section discusses the advantages of migrating to Auth0’s managed identity storage in terms of safety and security.

For customer facing applications, <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect ([OIDC](/docs/authenticate/protocols/openid-connect-protocol)) is the most frequently used industry standard protocol, and OIDC has first-class citizen support in Auth0. Auth0 provides support for various different approaches for integrating various different applications, so you'll want to see the section on [application integration](#application-integration) for the information you'll need to make an informed choice.

When calling one API from another API, or from any situation where there is no authenticated user context—such as one or more cron jobs, report generators, or continuous integration/delivery systems—you will need a way to authorize the application instead of a user. This is a one step process where the application is authenticated (using a <Tooltip href="/docs/glossary?term=client+ID">client ID</Tooltip> and secret) and then authorized in one call. You can learn more about this in our authorization workstream under [machine-to-machine (m2m) authorization](/docs/get-started/architecture-scenarios/business-to-consumer/authorization).

## Universal Login

Do you have, or will you have, more than one application in your system? If the answer to this question is yes, then you will want a centralized sign in experience. To achieve a seamless <Tooltip href="/docs/glossary?term=Single+Sign-on">Single Sign-on</Tooltip> (SSO) experience between multiple applications, it is critical to have a centralized location to redirect your users for authentication. This allows you a way to provide your users with a consistent experience if you add social authentication in the future, add third party applications to your system, or add multi-factor authentication as an option (or requirement) for your users—and also allow you to take advantage of new features for improving your users’ experience with little, if any, added development effort.

<Info>
  ### Best Practice

  If you have more than one application, the best practice is to redirect to a [centralized location](/docs/authenticate/login/auth0-universal-login) to authenticate the user. With Auth0, this means taking advantage of [Universal Login](/docs/authenticate/login/auth0-universal-login), which provides many security and user experience benefits out-of-the-box, including [SSO](/docs/authenticate/single-sign-on).
</Info>

Auth0 Universal Login makes authenticating users a short, easy process which can be accomplished in three easy steps (all of our Quickstarts demonstrate this and our SDKs hide the complexity for you too):

1. Determine how and when you want to [redirect from your application](#application-integration).
2. Set up the appropriate [branding](/docs/get-started/architecture-scenarios/business-to-consumer/branding) and/or customized HTML in your Auth0 configuration.
3. Set up your application to [receive and handle the response](#application-integration) from the Authorization Server.

## Username and password authentication

Nearly every B2C application provides the ability for their customers to create a new set of credentials. This is a common form of authentication that all users are familiar with.

Username password authentication comes in multiple flavors at Auth0. If your application is a green-field application with no existing user base, then a simple Auth0 out-of-the-box [Database Connection](/docs/authenticate/database-connections) will give you everything you need to start authenticating your users. However, if you have a legacy user store—such as your own database of users or an existing LDAP system—you have a couple of different options for migrating your users as discussed in our guidance on [User migration](/docs/get-started/architecture-scenarios/business-to-consumer/provisioning).

However you end up provisioning the users for your database connection, the authentication of those users is quite similar. It requires you to present users with a form to enter their username and password. As mentioned in the guidance concerning [Universal Login](#universal-login), the simplest and safest way to authenticate users with a username and password is to redirect them to a centralized login page and collect their username and password there. This allows Auth0 to determine whether they have already authenticated and skip the login form entirely when it's not needed.

<Info>
  ### Best Practice

  Collecting credentials only at the centralized login page will reduce the surface area for potential leak of user secrets. It will also reduce the need to collect credentials unnecessarily. See [Universal Login](#universal-login) for more information.
</Info>

## Application integration

Once you've figured out how you want to authenticate your users, the next step is to determine how you will initiate that authentication. Each application will typically have its own starting point.

<Warning>
  Native mobile applications (and desktop applications) should use the system browser for authentication, or they open themselves up to additional security risks. See [Native vs. Browser Login on Mobile](/docs/get-started/authentication-and-authorization-flow/device-authorization-flow/mobile-device-login-flow-best-practices) for more information.
</Warning>

As discussed, we've found that most of our customers use [OpenID Connect (OIDC)](/docs/authenticate/protocols/openid-connect-protocol) as the industry-standard protocol when it comes to their customer-facing applications. Figuring out which OIDC flow to use is your first task, and you will want to start by reviewing the our [grant mapping](/docs/get-started/applications/application-grant-types) guidance in the first instance.

If you want to allow anonymous users access to any part of our application then you need to determine if you will be redirecting right away or prompting your users to redirect only when required (or perhaps some combination of both; see [Redirect Users After Login](/docs/authenticate/login/redirect-users-after-login) for further discussion). If users can [deep link](#deep-linking-to-protected-endpoints) to a protected version (or area) of your site then you will need to determine the links to your application that will result in an automatic redirect to Auth0.

### Anonymous access

It is important to consider the user experience when someone first comes to your application. If your application supports anonymous user access (quite common for eCommerce applications) there are different scenarios to consider:

* Are they returning to the application after having already logged in, or
* If this is the first time they are accessing the application:

  * Have they already accessed a different application that uses the same Auth0 tenant,
  * Have they ever (or perhaps not in a long time) authenticated on this device or browser.

When an anonymous user accesses your application, it can often be desirable for the application to discover if the user has already logged into a different application in the same family, or to remember this user even if the application is a [SPA](/docs/quickstart/spa) with no state. For example, if you can determine that the user is already logged in, you might decide to have the UI header in the application skip displaying a login button and instead have an account or profile menu for the user. To accomplish this you will want to utilize "[silent authentication](/docs/authenticate/login/configure-silent-authentication)". Silent authentication will allow you to check to see if the user is logged in without prompting them to log in if they are not. Then the application can present a login button if necessary. If the user is logged in already, however, then you will receive tokens and will not have to present the user with a login button again.

<Warning>
  Checking for a login session by redirecting to Auth0 can be helpful for your application, but if this will result in a lot of requests, you should employ a throttling mechanism to avoid latency and/or rate limiting.

  Calls to the Management API are subject to [Auth0 Rate Limiting policy](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy). You must take this into consideration, and to assist, Auth0 generally recommends use of the appropriate [Auth0 SDK](/docs/libraries) for your development environment rather than calling our APIs directly.
</Warning>

### Deep linking to protected endpoints

There are a variety of reasons why someone might link directly to a particular page within your application that is only accessible by authenticated users. If this is possible for your application you should automatically redirect your user to Auth0 if they are not authenticated. Once they authenticate and the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip> returns them to your application, you can [redirect them](/docs/authenticate/login/redirect-users-after-login) to where they intended to go in the first place.

### Best Practice

Most modern authentication frameworks support middleware for redirecting to an authorization server such as Auth0. When selecting one, here are some key considerations:

* Support for confidential clients, non-confidential clients, or both
* Support for configuration via [discovery endpoint](/docs/get-started/applications/configure-applications-with-oidc-discovery "Configure Applications with OIDC Discovery") or explicitly inline
* Support for token validation including expirations, signatures, claims and scopes
* Support for <Tooltip href="/docs/glossary?term=Refresh+Tokens">Refresh Tokens</Tooltip> if needed

### Authenticating the user

Authentication is the process of determining user identity. The result of authentication in an OIDC context is an <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip>. This token contains information about the user and should only be able to be obtained if the user authenticates using one or more factors as defined by the authorization server (the most common form being [user ID and password](#username-and-password-authentication)). There are a few things you may also need to consider in addition to obtaining an ID Token:

* Do we also need an [Access Token](/docs/secure/tokens/access-tokens) in order to call a shared API?
* Is your application a single-page application and only requires an [ID Token](/docs/secure/tokens/id-tokens)? See [Authorization Code Grant with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/call-your-api-using-the-authorization-code-flow-with-pkce) for more information.
* Is your application a native application (mobile or desktop) and/or do you need a [Refresh Token](/docs/secure/tokens/refresh-tokens)? See [Authorization Code Grant with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/call-your-api-using-the-authorization-code-flow-with-pkce) for more information.

<Warning>
  Before you go live, you should ensure that **only** the grants that you are using for each application are enabled in your [configuration for your Application](/docs/get-started/applications/update-grant-types).
</Warning>

### Authorization code grant (with or without PKCE)

If your SDK only supports the Authorization Code grant, or you need an Access Token or <Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip>, then Authorization Code grant (with or without [PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce)) can also be used to retrieve an ID Token. The Authorization Code grant includes an additional API call to exchange the code for a token which can result in additional unnecessary latency if all you need is the ID Token. In many cases the [hybrid flow](/docs/get-started/authentication-and-authorization-flow/hybrid-flow) is implemented to provide optimum access to the ID Token while still leveraging Authorization Code grant workflow for the secure and safe retrieval of Access and Refresh Tokens.

<Warning>
  While Auth0 supports the use of implicit grant for browser-based applications requiring only an ID Token, it is recommended to use authorization code grant with [PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce). For detailed information, see [OAuth2 Implicit Grant and SPA](https://auth0.com/blog/oauth2-implicit-grant-and-spa/) on the Auth0 Blog.

  If you need a [Refresh Token](/docs/secure/tokens/refresh-tokens) so that you can obtain a new Access Token or ID Token without having to re-authenticate the user, then you must use the [authorization code grant](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/call-your-api-using-the-authorization-code-flow).
</Warning>

## Attack protection

The reason that authentication systems are important is to prevent <Tooltip href="/docs/glossary?term=bad+actors">bad actors</Tooltip> from accessing applications and user data that they should not. We want to place as many barriers as possible between those bad actors and access to our systems. One of the easiest ways to do this is to ensure that your [attack protection](/docs/secure/attack-protection) with Auth0 is configured correctly, so take a moment to read the guidance on this subject and ensure that it's working correctly for you.

<Info>
  ### Best Practice

  Anomaly detection is handled behind the scenes by Auth0 and provides a great security feature for your product. If you're going to utilize it, ensure that you have set up your [Email Provider](/docs/get-started/architecture-scenarios/business-to-consumer/operations#email-provider-setup) and configured your [Email Templates](/docs/get-started/architecture-scenarios/business-to-consumer/branding#email-template-customization) before turning on email delivery to your users.
</Info>

## SSO with legacy systems

In a large scale re-structure it's not always possible—or practical—to update all your applications at once. In fact, our recommended best practice is to plan for an iterative-style approach when it comes to integrating with Auth0. If your applications already participate in Single Sign-on (SSO), and your legacy identity system supports protocols such as OIDC or <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip>, then you have a couple of options available if you want to continue to provide SSO as you integrate with Auth0:

* Update your existing identity provider in your legacy SSO system to redirect to Auth0 for login (e.g., using [SAML](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider)), or
* Have Auth0 redirect to your legacy SSO system to login. This requires configuring your legacy system as an IdP in Auth0 (i.e., either using [SAML](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider) or [OIDC](/docs/authenticate/identity-providers/social-identity-providers)).

<Info>
  ### Best Practice

  Supporting an SSO experience with your legacy system can add complexity, but may be worth it to generate a more seamless user experience as you integrate with Auth0. If you intend to go down this path, planning for it early can help ensure that it is possible to achieve. If you don't already have SSO at a centralized service, then the complexity to add it will unlikely be worth the benefits.
</Info>

This is a complex topic that will likely need some additional investigation depending on your current legacy architecture, and we recommend you only look into this if you currently have SSO support in your legacy system. Note: if you are currently redirecting from your applications to a centralized system to authenticate your users and that system only asks for credentials if you don’t already have a session with the centralized system, then you have a legacy SSO implementation.

## Social authentication

The “bring your own identity” scenario offered by Facebook, Google, etc., is a valuable way of simplifying the user authentication experience without compromising security, and using [Universal Login](#universal-login) makes it easy to start adding support for [Social Connections](/docs/authenticate/identity-providers/social-identity-providers) with minimal disruption.

<Warning>
  Auth0 provides a simple way to test social connections using [pre-configured developer keys](/docs/authenticate/identity-providers/social-identity-providers/devkeys). However, these have [limitations](/docs/authenticate/identity-providers/social-identity-providers/devkeys#limitations-of-developer-keys), and before going into production, you’ll need to set up your own application-specific keys by following the [instructions](/docs/authenticate/identity-providers/social-identity-providers) for your chosen social provider(s).
</Warning>

With [social](https://auth0.com/learn/social-login/) support, user identities and credentials are managed by the social provider, as are certain identity claims, which Auth0 will use to populate the user [profile](/docs/get-started/architecture-scenarios/business-to-consumer/profile-management). Auth0 can also provide access to Social Identity Providers' (Social IdPs') [Access Tokens](/docs/secure/tokens/access-tokens), so that your application can also call third-party Social IdP APIs on behalf of the user.

<Info>
  ### Best Practice

  Social is a great feature to provide, but when you offer more than one way to sign in, you need to consider the possibility that your customers will actually use more than one way to sign in. By default, every user identity in Auth0 has its own user profile, so you’ll probably want to consider Auth0's capability to [link user accounts](/docs/manage-users/user-accounts/user-account-linking) to provide an effective way of associating one user profile with multiple identities.
</Info>

The Auth0 [Custom Social Connections extension](/docs/authenticate/identity-providers/social-identity-providers) extends social authentication even further by allowing you to connect with any [OpenID Connect (OIDC)](/docs/authenticate/protocols/openid-connect-protocol) third-party-compliant vendor not supported out of box. For example, support for the government-issued-identity provider [SwissID](https://www.swissid.ch/) can be configured in Auth0 by using a Custom Social Connection.

## Multi-factor authentication (MFA)

In an era where misuse of user credentials is at an all-time high, protecting your systems when it’s so common for hackers to steal users identity information in general is a challenge. One of the most effective ways though is to provide users with the ability to configure a second factor for protecting their account. More commonly referred to as [Multi-Factor Authentication](/docs/secure/multi-factor-authentication). This will ensure that only a valid user can access their account, even if they use a username and password that may have been compromised from a different application.

<Info>
  ### Best Practice

  It's quite common for customer facing applications to provide users with an *option* for adding a second factor rather than *forcing* them to use a second factor. For more information regarding this, see [providing your users with an option to add MFA](https://auth0.com/learn/multifactor-authentication-customers/).
</Info>

Auth0 supports a number of different options when it comes to enabling MFA for protecting user account access, and there are several practices to ensure that you will truly be providing a flexible second factor barrier to access:

* Auth0 [Guardian](https://auth0.com/multifactor-authentication): a service that provides both Push notification generation and an application for allowing or denying requests. Push sends notification to a user’s pre-registered device—typically a mobile or tablet—from which a user can immediately allow or deny account access via the simple press of a button.
* Time-based One-Time Password ([TOTP](https://auth0.com/blog/from-theory-to-practice-adding-two-factor-to-node-dot-js/)): allows you to register a device—such as Google Authenticator—that will generate a one-time password which changes over time and which can be entered as the second factor to validate a user’s account.
* SMS: for sending a one-time code over SMS which the user is then prompted to enter before they can finish authenticating.
* Voice: for delivering a one-time code through a phone call which the user is then prompted to enter before they can finish authenticating.
* Duo: allows you to use your Duo account for multi-factor authentication.
* Email: allows you to use your email account for multi-factor authentication.

Whilst MFA workflow using technologies such as Guardian or Google Authenticator is typically provided via a separate application that runs on a mobile or tablet device, if you don’t want your customers to have to download a separate application Auth0 also provides you with an [SDK](https://auth0.com/blog/announcing-guardian-whitelabel-sdk/) that you can use to build second factor workflow right in your existing mobile device application(s).

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2C IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/3er1aEQ7Ul0q3c9leJWczR/b1f18b4c16abb7e78b01e4eb2b52bb8e/B2C_Project_Planning.pdf)


# Authorization (B2C)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-consumer/authorization

User authorization and related planning considerations for your B2C IAM implementation.

Let's start by taking a step back and talking about Access Control. There isn't one clear cut definition of Access Control in the industry, but if you spend some time searching and reading you'll see that most authoritative sources agree that it is the umbrella concept that puts all of Authentication, Authorization, Consent, and Policy Enforcement together to ensure that only the right people and services have access to your applications and APIs. Next, let's look more closely into the distinctions between Authentication, Authorization, Consent, and Policy Enforcement. Your Auth0 <Tooltip href="/docs/glossary?term=Tenant">tenant</Tooltip> (your <Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip>) is typically responsible for Authentication and Consent, and some or all of Authorization and Policy Enforcement. Additionally, an <Tooltip href="/docs/glossary?term=Application">Application</Tooltip> or API itself almost always is the primary enforcer of policies, especially where contextual access is required:

* **Authentication**: the process of determining if a principal (a user or application) is who or what they say they are.
* **Authorization**: the process of determining what is allowed, based on the principal, what permissions they have been given, and/or the set of contextually specific access criteria.
* **Consent**: what permissions the user (<Tooltip href="/docs/glossary?term=Resource+Owner">Resource Owner</Tooltip>) has given permission to an application to do on its behalf. This is generally a requirement of delegated authorization. The user has to give permission to the Client to access the user's data in a different system.
* **Policy Enforcement**: The act of enforcing the policies of the application or API, rejecting or allowing access based on a user's authentication and/or authorization information.

In general we typically group different types of access control into three distinct categories so that it's easier to understand a) which actor is responsible for storing the information, b) which actor is responsible for making decisions, and c) which is responsible for enforcing the restrictions.

* The first category is where access is either granted or denied to an application or an API in its entirety. Both the data required to enforce this and the enforcement process is typically defined in the context of the Authorization Server For example, by using [`app_metadata`](/docs/manage-users/user-accounts/metadata) associated with a user and a [Action](/docs/customize/actions) defined in your Auth0 tenant.
* The second category is where access is either granted or denied to a specific subset of application or API functionality. The data required to enforce this is typically stored in the Authorization Server For example, by using `app_metadata` on a user in your Auth0 tenant with the enforcement process performed in the application or API itself. In this scenario, the data is typically communicated as one or more custom claims in an [`id`](/docs/secure/tokens/id-tokens) or [`access`](/docs/secure/tokens/access-tokens) token.
* The third category is where access is either granted or denied depending on what the principal (subject) can operate on within the context of an application or API. Both the data required to enforce this, and the enforcement process is typically defined in the context of the application or API. In this scenario, the data communicated as one or more custom claims in an `id` or `access` token may be consumed with or without data from an external source that is not Auth0.

In addition, Role-based Access Control (RBAC) and Attribute-based Access Control (ABAC) mechanisms can be applied in any of the Access Control categories described above. Whatever your use case then, there are a number of things you will want to consider when looking at the functionality and workflow you require:

* Are there scenarios where access to an entire application or API should be rejected?
* Will you be providing APIs that can be accessed by third-party applications?
* Will your APIs also be accessed by your own (first-party) applications?
* Will your application be calling a third-party API?
* Should your applications and/or APIs be enforcing access control based on user claims?

Auth0 supports access restriction for either applications or APIs based on certain conditions. In certain scenarios, you may want to create an Action that denies access using `api.access.deny()` when, for example, a user attempts access to an application or an API at an incorrect time (as described in this [example](/docs/manage-users/access-control/sample-use-cases-actions-with-authorization#allow-access-only-on-weekdays-for-a-specific-application)) - or if the user doesn’t have the right <Tooltip href="/docs/glossary?term=Claim">claim</Tooltip>(s) contained in their `app_metadata`. For an application using [OpenID Connect (OIDC)](/docs/authenticate/protocols/openid-connect-protocol), this would prevent the allocation of the [ID Token](/docs/secure/tokens/id-tokens) used to authorize access. Similarly, for an API, allocation of any OAuth2 [Access Token](/docs/secure/tokens/access-tokens) (used when calling the API), could be prevented as described in this [example](/docs/manage-users/access-control/sample-use-cases-actions-with-authorization#deny-access-to-anyone-calling-an-api).

<Callout icon="file-lines">
  In the main, we have found that [OIDC](/docs/authenticate/protocols/openid-connect-protocol) is the most commonly used industry-standard protocol used by Auth0 customers when it comes to authentication in their applications. We have also found that, even though [OAuth2](/docs/authenticate/protocols/oauth) was created as a delegation protocol, it is commonly used within first party applications when there is an API that does not have a shared session with the application.
</Callout>

Auth0 also can provide the information needed so that an application can enforce restrictions. For [application level integration](#application-integration), Auth0 allows you to add [custom claims](#id-token-claims) to an <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip>, which your application can then verify and subsequently use to perform policy enforcement. In this case you will need to decide what information you require for your application to make enforcement decisions. If you need to make decisions at an API instead of in your application, you will likely need to use an <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> instead of an ID token. Continue reading for more information.

<Warning>
  When deciding what data to include in your ID token and/or access token, consider token size, especially if you are passing the token in the URL. Even if you are not passing tokens in the URL, you will also need to consider the potential of exposing sensitive PII (Personally Identifiable Information). Token information is not encrypted, so although it isn't generally a security issue for an ID token to be leaked, it can become a privacy issue depending on the data that is included in the token.
</Warning>

For [API level integration](#api-integration), Auth0 supports both [custom claims](#access-token-claims) as well as [scope](#access-token-scopes) re-configuration, both within the context of an Access Token. Again, you will need to decide what information will be required in order for your API to make access decisions, and your API will need to enforce that by validating the contents of the Access Token.

<Callout icon="file-lines">
  When deciding whether you should use permissions through custom claims or scopes, you should make sure you understand the nature and purpose of scopes. There is a nice [blog post](https://auth0.com/blog/on-the-nature-of-oauth2-scopes/) on that which is easy to read and helps clear up the topic.
</Callout>

## Application integration

In this scenario, your Auth0 tenant provides a token as an indicator of authorized access to an application. For applications utilizing [OpenID Connect (OIDC)](/docs/authenticate/protocols/openid-connect-protocol), the industry-standard protocol we typically find most utilized when it comes to customer facing applications, this would be an ID Token expressed as a [JWT](/docs/secure/tokens/json-web-tokens).

### ID Token claims

Using Action extensibility, Auth0 allows you to easily [add custom claims to an ID Token](/docs/get-started/apis/scopes/sample-use-cases-scopes-and-claims#add-custom-claims-to-a-token) based on, for example, a user’s [Metadata](/docs/manage-users/user-accounts/metadata) content. Your application can then verify the ID Token for the necessary claims, and either allow or prevent access to certain functionality as required. Note that though the process of adding custom claims via Action is streamlined, the Action runtime is flexible and allows you to write custom code that may have negative effects.

<Callout icon="file-lines">
  When you are considering adding custom claims, we recommend that you store any access control data you may need to include within claims as part of the user's [`app_metadata`](/docs/manage-users/user-accounts/metadata). Firstly, this prevents you from needing to call an external API to fetch the data, which can negatively impact the performance and scalability of the login sequence. Secondly `app_metadata` **cannot** be modified by a user - so the user cannot directly circumvent any access control restrictions by modifying their own <Tooltip href="/docs/glossary?term=Metadata">metadata</Tooltip>. Also remember to check out our [metadata best practices](/docs/get-started/architecture-scenarios/business-to-consumer/profile-management#metadata) guidance too.
</Callout>

### ID Token scopes

[OIDC Scopes](/docs/get-started/apis/scopes/openid-connect-scopes) are typically used by an application to obtain consent for authorized access to a user's details during authentication. Each of the pre-defined scopes returns the set of standard claims where defined, and as described in the [OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). The scopes an application requests depend on which user attributes the application needs. Once the requested scopes are authorized by the user, the claims are returned in the ID Token and are also made available via the [/userinfo](https://auth0.com/docs/api/authentication#get-user-info) endpoint.

## API integration

In this scenario your Auth0 tenant can provide an OAuth2 [Access Token](/docs/secure/tokens/access-tokens), typically expressed as a [JWT](/docs/secure/tokens/json-web-tokens), which can be used by your API to restrict access to certain parties. In addition, Auth0 provides support for what is notionally described as both [First-Party and Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/first-party-and-third-party-applications).

Acting as the authorization server, and with the consent of the user (the resource owner), your Auth0 tenant can be used to provide an Access Token - typically expressed as a [JWT](/docs/secure/tokens/json-web-tokens) - to an application (client) so that it can access a protected resource hosted by a <Tooltip href="/docs/glossary?term=resource+server">resource server</Tooltip> on behalf of the resource owner. The issued Access Token is typically passed as the Bearer token in the HTTP Authorization header sent to an API.

Whether you have a single API, or perhaps a suite of logically related [microservice APIs](/docs/get-started/apis/set-logical-api), you can leverage the Access Tokens that Auth0 provides in order to secure access to your service(s). Though relatively easy to set this up in the [Auth0 Dashboard](https://manage.auth0.com/) or through the [Auth0 Management API](https://auth0.com/docs/api/management/v2#!/Resource_Servers/post_resource_servers), it's important to review the different application scenarios and API layouts to determine the best architecture for your system.

<Callout icon="file-lines">
  OAuth2 Access Tokens are primarily designed for use in securing public facing APIs; when expressed as a JWT, an Access Token is a self contained entity which can be verfied without the need to make any additional 3rd party API call. If your APIs do not fall into this category - i.e they are part of an application itself (as in only called by that application) or are sat behing your firewall - then protecting them with tokens may well be overkill, and your existing cookie based (et al) workflow may well suffice.
</Callout>

OAuth2 was designed specifically with third-party access in mind, for example, a scenario might be that a user (resource owner) wants to use an application (a client) that does not belong to the same organization as the service that provides the user's data (the resource server). In this case, when the application needs to access data that the user owns, it redirects to the organization where the user’s data resides, which in turn authenticates the user and then prompts the user to give the application permission to access their data. This prompting for permission is referred to as providing [consent](/docs/get-started/applications/confidential-and-public-applications/user-consent-and-third-party-applications) and is a large part of what providing support for [third party applications](/docs/get-started/apis/scopes/api-scopes#example-an-api-called-by-a-third-party-application) entails. If you are planning to integrate third-party applications, then it's important you mark them as third-party early on so that Auth0 will handle prompting for user consent.

On the other hand, if your organization owns the application(s), the user data itself and the API(s) through which that data is accessed, then consent is not typically required as the interactions are all [first-party](/docs/get-started/apis/scopes/api-scopes#example-an-api-called-by-a-first-party-application). If you're only creating first-party applications, then you can ensure that you are not presenting your users with any unnecessary consent screen(s) by [allowing user consent to be skipped](/docs/get-started/apis) as part of any resource service definition.

<Warning>
  Though you can configure your applications to be first-party and subsequently configure your APIs to allow first-party clients to ignore consent, if you are using `localhost` then Auth0 cannot verify that the application is truly a first-party app so your users will be prompted for consent anyway. To work around this constraint, when testing on your local machine during development, create a [fake local hostname and use that instead](https://community.auth0.com/t/how-do-i-skip-the-consent-page-for-my-api-authorization-flow/6035).
</Warning>

Alternatively, you may have data relating to a user for which additional [functionality is provided](/docs/get-started/apis/scopes/api-scopes#example-an-api-called-by-a-back-end-service) and for which explicit user consent cannot be obtained (i.e. there is no authenticated user who can provide it). In this scenario, a [list of applications for which Client Credentials grant is enabled](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow) can be defined.

### Access Token claims

As is the case with ID Tokens, you can [add custom claims to Access Tokens](/docs/get-started/apis/scopes/sample-use-cases-scopes-and-claims#add-custom-claims-to-a-token) using Auth0 Action extensibility. Once added, your API can then verify an Access Token for the necessary claims and either allow or prevent access to certain functionality as required.

<Callout icon="file-lines">
  When you are considering adding custom claims, we recommend that you store any access control data you may need to include within claims as part of the user's [`app_metadata`](/docs/manage-users/user-accounts/metadata). Firstly, this prevents you from needing to call an external API to fetch the data, which can negatively impact performance and scalability. Secondly `app_metadata` **cannot** be modified by a user - so the user cannot directly circumvent any access control restrictions by modifying their own metadata. Also remember to check out our [metadata best practices](/docs/get-started/architecture-scenarios/business-to-consumer/profile-management#metadata) guidance too.
</Callout>

### Access Token scopes

[OAuth2 Scopes](/docs/get-started/apis/scopes/api-scopes) are typically used as the mechanism by which an API can determine what <Tooltip href="/docs/glossary?term=Actions">actions</Tooltip> can be performed on behalf of a user. Scopes can be added on a per API basis to [define specific access permissions](/docs/get-started/apis/add-api-permissions) in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or through the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. Scopes can also be manipulated via Auth0 extensibility (e.g. via an Action, as in this [example](/docs/get-started/architecture-scenarios/spa-api/part-2#create-an-action-to-validate-token-scopes)). The scopes an application requests for accessing an API should depend on what functionality the application needs the user to give permission for the application to use. Once the requested scopes are authorized, they will be returned in the Access Token which can be subsequently [verified by said API](/docs/secure/tokens/access-tokens/validate-access-tokens). A good example of this is when you log in to an application that is using a social provider for login: the social provider API requires that the application specifies whether the user will want the application to post items on your behalf. This allows the user to accept or deny this request. This example demonstrates how the user is delegating permission to the application - which is different than the API restricting access based on a user's <Tooltip href="/docs/glossary?term=Role">role</Tooltip>, and should be handled differently.

<Callout icon="file-lines">
  **Best Practice**

  Even though you have the ability to fully manipulate Access Token Scopes via Auth0 extensibility, as a security best practice you should only remove scopes which are not authorized and refrain from adding scopes that were not requested.
</Callout>

Though scopes are often used as a way to enforce access permissions for a user, there are situations where it can become [tricky when you use them in this manner](https://auth0.com/blog/on-the-nature-of-oauth2-scopes/). We therefore recommend that you use scopes for their intended purpose (i.e. delegating permission to an application) and use [custom claims](#access-token-claims) for your role-based or other access control scenarios.

## Fine Grained Authorization (FGA)

[Fine Grained Authorization](https://docs.fga.dev/fga-concepts) allows you to grant individual users access to a specific resource or object based on:

* A user's role within an organization, such as `editor` or `admin`
* An attribute of the user or object, such as `manager` for a user or `marketing` for an object
* A relationship between a user and an object, such as a user with view access to a parent folder also has view access to the child folder

With <Tooltip href="/docs/glossary?term=FGA">FGA</Tooltip>, you can create an authorization model to determine what relationship you want to determine user access.

## Role Based Access Control (RBAC)

Auth0 has out-of-box support for Role Based Access Control ([RBAC](/docs/manage-users/access-control/rbac)). RBAC refers to assigning permissions to users based on their role within an organization, and provides for simpler access control by offering a more manageable approach that is less prone to error.

## Machine-to-Machine (M2M) authorization

There are many scenarios that require an application without any user-interactive session to obtain an access token in order to call an API. In such scenarios you must authenticate the client instead of the user, and <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> 2 provides the [client credentials](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow) grant type to make this easy to achieve. Some common examples of where this is required include:

* A cron job or other service that needs to communicate with your API (e.g. where a daily report needs to be generated and emailed it to an administrator).
* A separate API the supports privileged access (e.g. the API is not exposed to users directly, but instead to a backend only).
* In certain microservice architectures, where some API layers need to communicate to other API layers without a user involvement, or after a user token has expired.
* A privileged API that may need to be called before a user has authenticated (i.e. from an action or custom DB script in your Auth0 tenant)

<Callout icon="file-lines">
  Traditionally, a special "service account" would have been created in order to cater for these scenarios: a user with a username and password that was configured for services which supported non-interactive use cases. That is no longer a recommended approach for many reasons, and the current best practice is to use [OAuth 2.0 Client Credentials Grant](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow) in these situations.
</Callout>

## Project planning guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2C IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/3er1aEQ7Ul0q3c9leJWczR/b1f18b4c16abb7e78b01e4eb2b52bb8e/B2C_Project_Planning.pdf)


# Branding (B2C)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-consumer/branding

How to configure Auth0 items to reflect your brand and desired user experience.

Auth0 can be customized with a look and feel that aligns with your organization's brand requirements and user expectations. Branding Auth0 collateral provides a consistent user experience for your customers, and gives them peace of mind that they’re using a product from a trusted and secure provider.

Auth0 provides support for [internationalization (I18N)](/docs/customize/internationalization-and-localization) and <Tooltip href="/docs/glossary?term=Localization">localization</Tooltip> (L10N), both of which are important if you work on branding for an international clientele. Out-of-box collateral, such as the Auth0 Lock UI widget, comes ready enabled for multiple language support, with built-in extensibility for adding more languages if what you require [doesn’t already exist](/docs/customize/internationalization-and-localization/lock-internationalization).

<Callout icon="file-lines">
  Almost all applications need Internationalization and/or Localization in one form or another. Auth0 makes it easy to add, but you need to account for it up front: retro-fitting localization, for example, can be a painful process if left too late.
</Callout>

When considering the items you want to brand, as well as how best to brand them, there are a number of things you'll want to review:

* Do you need to brand your login page?
* Do you need to localize your login page?
* How can you customize emails so that they're not just branded, but vary based on user preference?
* How will users know that they're still on your domain when they see your login page?
* What do you need to do to provide additional browser security (e.g., implement Extended Validation)?
* Where do you want to direct users in the event of errors?

Auth0 provides tremendous flexibility when it comes to customizing and configuring Auth0 pages such as [Universal Login](#universal-login-and-login-pages) and [Password Reset](#password-reset-page-customization). So you can pretty much set up whatever UX look and feel you require. For many, the out-of-the-box experience - with perhaps a little alteration - is all that's required. However, for others the value of their brand and brand awareness requires more extensive customization. This flexibility extends to not only Auth0 pages, but via extensibility can also be applied to the [email templates](#email-template-customization). Auth0 [Custom Domain](#custom-domain-naming) functionality further enhances consumer awareness by providing users with the confidence and peace of mind when it comes to safety and security.

While Auth0 provides for default information when it comes to error situations, out-of-the-box information can be somewhat cryptic as the context that can only be provided by you is missing. Auth0 [error page customization](#error-page-customization) guidance can however help mitigate that by allowing you to provide information of a more context-specific nature via your own support organization.

<Callout icon="file-lines">
  To provide helpful resources for users who experience problems, you should also configure a friendly name and a logo, as well as provide the support email address and URL for your organization. To learn how, see [Dashboard Tenant Settings](/docs/get-started/tenant-settings#settings).
</Callout>

## Universal login and login pages

[Universal Login](/docs/authenticate/login/auth0-universal-login) is the recommended method for authenticating users, and it centers around use of the Login page. You can customize the Login page to support your organization's branding requirements.

<Callout icon="file-lines">
  If you choose to customize the Universal Login page script, we strongly recommend that you make use of version control. To do this, you should deploy the script to your Auth0 tenant via [deployment automation](/docs/get-started/architecture-scenarios/business-to-consumer/deployment) or via one of the [alternative strategies](/docs/customize/login-pages/classic-login/version-control).
</Callout>

## Custom domain naming

By default, the URL associated with your tenant will include its name and possibly a region-specific identifier. For example, tenants based in the US have the a URL similar to `https://example.auth0.com` while those based in Europe have something that is of the fashion `https://example.eu.auth0.com`. A [Custom Domain](/docs/customize/custom-domains) offers a way of providing your users with a consistent experience by using a name that’s consistent with your organization's brand.

<Warning>
  Only one custom Domain Name can be applied per Auth0 Tenant, so if you absolutely must have independent domain name branding then you will require an [architecture](/docs/get-started/architecture-scenarios/business-to-consumer/architecture) where multiple Auth0 Tenants are deployed to production.
</Warning>

In addition, <Tooltip href="/docs/glossary?term=Custom+Domain">Custom Domain</Tooltip> functionality offers you complete control over the certificate management process. By default, Auth0 provides standard SSL certificates, but if you configure a custom domain, you can use Extended Validation (EV) SSL certificates or similar to provide the visual, browser-based cues that offer your visitors additional peace of mind.

In general, we see customers having the most success when they use a centralized domain for authentication - this is especially the case if the company offers multiple products or service brands. By using a centralized domain, you can provide end users with a consistent user experience while also minimizing the need to maintain multiple production tenants in Auth0.

## Email template customization

Auth0 makes extensive use of email to provide both user notifications and to drive the functionality needed for secure identity management (for example, email verification, account recovery, and brute force protections), and Auth0 provides a number of templates for these.

<Callout icon="file-lines">
  Before customizing email templates, please set up your [Email Provider](/docs/get-started/architecture-scenarios/business-to-consumer/operations#email-provider-setup).
</Callout>

Out of the box, the email templates used contain standard verbiage and Auth0 branding. However, you can configure almost every aspect of these templates to reflect the verbiage and user experience you want and make changes to things like the preferred language, accessibility options, and so forth.

Email templates are customized using [Liquid syntax](/docs/customize/email/email-templates/use-liquid-syntax-in-email-templates). If you are interested in customizing your templates based on user preferences, you will also have access to the [metadata](/docs/manage-users/user-accounts/metadata) located in users' profiles, as well as any specific application metadata too.

## Password reset page customization

The [Password Reset](/docs/customize/login-pages/classic-login/customize-password-reset-page) page is used whenever a user takes advantage of password change functionality and, as with the login page, you can customize it to reflect your organization's particular branding requirements.

## Error page customization

If there are issues encountered during user interactive workflow (e.g. user sign up or login), Auth0 provides error messages that indicate what the problem is under the hood. The default messages are somewhat cryptic, especially to the end user, since they will likely be missing context that only you can supply. As such, we recommend [customizing your error pages](/docs/customize/login-pages/custom-error-pages) to provide the missing context-specific information directly to your users. Furthermore, customizing your error pages allows you to display your branding, not Auth0's, as well as provide useful information to your users as to what should be done next. This information might include a link to a FAQ or how to get in touch with your company's support team or help desk.

<Callout icon="file-lines">
  Out-of-the-box there is no user interface for customizing Auth0 provided error pages, but you can use the [Tenant Settings endpoint of the Management API](https://auth0.com/docs/api/management/v2#!/Tenants/patch_settings) to configure them. Alternatively, if you can create and host your own error page, then you can have Auth0 direct users to that page instead of using the Auth0-hosted option.
</Callout>

## Guardian multi-factor page customization

The Multi-factor Authentication pages can be customized by adjusting the Universal Login branding options in the [Universal Login Settings](https://manage.auth0.com/#/login_settings) section.

If you need further customization, you can also customize [the full HTML content](/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-classic-login) to reflect your organization's particular UX requirements.

## Project planning guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2C IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/3er1aEQ7Ul0q3c9leJWczR/b1f18b4c16abb7e78b01e4eb2b52bb8e/B2C_Project_Planning.pdf)


# Deployment Automation (B2C)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-consumer/deployment

How Auth0 tooling helps to automate tenant deployment.

In addition to adopting best practices for change management and [QA](/docs/get-started/architecture-scenarios/business-to-consumer/quality-assurance), successful customers will also integrate Auth0 collateral management as part of some automated deployment process. As discussed in the Architecture section under [SDLC support](/docs/get-started/architecture-scenarios/business-to-consumer/architecture#sdlc-support), you will want to ensure you configure separate Auth0 tenants for development, testing, and production environments, and you will want that configuration to be almost identical for the tenant in each environment. Using deployment automation helps ensure this, so that each environment tenant is configured the same, and you will be less likely to see bugs show up as a result of mismatched configurations between environments.

<Info>
  ### Best Practice

  However you configure deployment automation, we’d recommend you unit test your rules, custom DB scripts, and hooks prior to deployment, and run some integration tests against your tenant post-deployment too. For more details regarding this, see the [Quality Assurance](/docs/get-started/architecture-scenarios/business-to-consumer/quality-assurance) guidance provided.
</Info>

Auth0 provides support for a couple of different options when it comes to the deployment automation approaches you can use, and each can be used in conjunction with the other if desired:

* The [Auth0 Deploy CLI tooling](/docs/deploy-monitor/deploy-cli-tool) provides you with an easy-to-use script that can help you integrate with your existing Continuous Integration/Continuous Deployment (CI/CD) pipeline.
* If you can’t integrate directly with, or for some reason you don’t have a CI/CD pipeline, then the Auth0 [Source Control Extensions](/docs/customize/extensions) can provide an easy-to-set-up basic automation process with very low maintenance.

<Warning>
  Note that both the Deploy CLI Tool and source control extensions can cause destructive changes; manual changes made directly in the dashboard between automated deployments could be lost! For this reason, if either is used, then **all** changes should be deployed from the source control subsystem referenced via the tooling and not made manually.
</Warning>

Each environment may also need some environment-specific configuration--Application <Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>’s and <Tooltip href="/docs/glossary?term=Client+Secrets">Client Secrets</Tooltip> will be different between the Auth0 tenants, for example--so you’re going to want some way of being able to dynamically reference this rather than having hard-coded values. Auth0 provides support for handling environment-specific configuration information through one of the following two approaches:

* Use [Tenant Specific Variables](#tenant-specific-variables)
* Use keyword replacement if using the Auth0 Deploy CLI tool

## Tenant specific variables

Auth0 allows you to configure variables that are available from within custom [extensibility](/docs/customize/extensions); these can be thought of as environment variables for your Auth0 tenant. Rather than hard code references that change when moving code between development, test, and production environments, you can use a variable name that is configured in the tenant and referenced by the custom extensibility code. This makes it easier for the same custom code to function, without changes, in different tenants as the code can reference variables which will be populated with tenant-specific values at execution time:

* For use of variables in Actions, see [Write Your First Action](/docs/customize/actions/write-your-first-action) to learn how to configure secrets in the editor
* For use of variables in Rules, see how to [configure values](/docs/customize/rules/configuration)
* For use of variables in Hooks, see how to configure [secrets](/docs/customize/hooks/hook-secrets) in the editor
* For use of variables in Custom DB Scripts, see the [configuration parameters](/docs/authenticate/database-connections/custom-db/create-db-connection#step-3-add-configuration-parameters)

<Info>
  ### Best Practice

  It’s a recommended best practice to use variables to contain tenant-specific values as well as any sensitive secrets that should not be exposed in your custom code. If your custom code is deployed in GitHub/Gitlab/Bitbucket/VSTS, then using a tenant-specific variable avoids exposure of sensitive values via your repository.
</Info>

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2C IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/3er1aEQ7Ul0q3c9leJWczR/b1f18b4c16abb7e78b01e4eb2b52bb8e/B2C_Project_Planning.pdf)


# Launch Preparation (B2C)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-consumer/launch

Launch preparation considerations for your B2C IAM implementation.

Use this guide as you prepare for the launch of your application. We’ve included reminders about some content you may have viewed earlier during your planning or development phases as well as some new content unique to the launch phase. The sections below are useful to developers and project owners to ensure that you have everything lined up for a smooth launch. There are several things to check so it may help to assign ownership of different sections to different members of your team.

* [Tenant Check](/docs/get-started/architecture-scenarios/business-to-consumer/launch/tenant-check): Tenant Checks to perform before launch of your B2C IAM implementation.
* [Testing Complete](/docs/get-started/architecture-scenarios/business-to-consumer/launch/testing): Testing preparation for the launch of your B2C IAM implementation.
* [Operations Readiness](/docs/get-started/architecture-scenarios/business-to-consumer/launch/operations-readiness): Operations checks to perform before launch of your B2C IAM implementation.
* [Compliance Readiness](/docs/get-started/architecture-scenarios/business-to-consumer/launch/compliance-readiness): Compliance checks to perform before launch of your B2C IAM implementation.
* [Support Readiness](/docs/get-started/architecture-scenarios/business-to-consumer/launch/support-readiness): Support readiness for the launch of your B2C IAM implementation.
* [Launch Day Preparation](/docs/get-started/architecture-scenarios/business-to-consumer/launch/launch-day): Launch preparation considerations for your B2C IAM implementation.

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2C IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/3er1aEQ7Ul0q3c9leJWczR/b1f18b4c16abb7e78b01e4eb2b52bb8e/B2C_Project_Planning.pdf)


# Compliance Readiness (B2C)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-consumer/launch/compliance-readiness

Compliance checks to perform before launch of your B2C IAM implementation.

There are several requirements related to privacy and compliance. Auth0 cannot provide legal guidance on your privacy or other regulatory obligations, but we can provide a curated list of privacy requirements below for which Auth0 offers features that may help you meet your obligations. Prior to launch, you should check that you’ve met all your privacy obligations and review the features outlined below to ensure you’re leveraging all the available Auth0 features to help you meet your privacy and compliance requirements.

## Publish privacy policy and obtain user consent

If you collect or process personal data about users, you should have published a privacy policy and have established procedures to ensure your operations abide by the contents of the policy. You also need to obtain a user’s consent for the collection and processing of information. Auth0 provides options for [displaying a link to your privacy policy storing user consent](/docs/secure/data-privacy-and-compliance/gdpr).

## Provide access to view, correct and erase data

Privacy legislation often requires that users have the right to view and correct any data held about them. If you are a data controller, you should provide a mechanism for this. Auth0 customers can build a self-service feature to access and correct data via the <Tooltip href="/docs/glossary?term=management+API">management API</Tooltip>.

## Provide access to data portability

If you are a data controller, you may be obligated to provide users a means to export their data from your system in a transportable format. Auth0 provides user data portability mechanisms to help you satisfy this obligation via both manual export capabilities and the Management API which enables you to implement a self-service feature for users.

## Take steps to minimize personal data

You should have reviewed the personal data you collect about users to ensure it is legitimately required for the purposes of the processing covered in the privacy policy and consent. You should also confirm you have minimized the data you collect, and established a data retention policy. You can optionally elect to encrypt data you store in user metadata for additional protection.

## Data retention policy enforcement automated

You should have a published data retention policy and automate the enforcement of it. The Auth0 management API or the <Tooltip href="/docs/glossary?term=Auth0+dashboard">Auth0 dashboard</Tooltip> can be used to facilitate [erasure of user accounts](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-right-to-access-correct-and-erase-data).

## Protect personal data

Regardless of whether you are a data controller or a data processor, you have obligations to protect the personal data you hold about users. This includes use of encryption where possible, and implementing reasonable security measures to protect user accounts. Prior to launch, you should check if you are using all the security features available from Auth0 to help with this such as Brute Force Detection, <Tooltip href="/docs/glossary?term=Multi-Factor+Authentication">Multi-Factor Authentication</Tooltip> (for both users and administrators), and a strong password policy if using passwords. You should also ensure you have a process ready to respond to Brute Force attacks.

## Supplier evaluation

Another common compliance obligation is to perform due diligence review of the security of any third-party suppliers to which you expose personal data. For Auth0, you will find information to facilitate this task on the Auth0 [security and certifications](https://auth0.com/security/) page where you can view the security certifications Auth0 has obtained.

## Additional resources

Additional resources that may be useful for your compliance requirements include:

* [Auth0 Privacy Policy](https://auth0.com/privacy)
* [Security and Compliance](https://auth0.com/security/)
* [Auth0 Compliance and Certifications](/docs/secure/data-privacy-and-compliance)
* [Auth0 General Data Protection Regulation Compliance](/docs/secure/data-privacy-and-compliance/gdpr)

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2C IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/3er1aEQ7Ul0q3c9leJWczR/b1f18b4c16abb7e78b01e4eb2b52bb8e/B2C_Project_Planning.pdf)


# Launch Day Preparation (B2C)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-consumer/launch/launch-day

Launch preparation considerations for your B2C IAM implementation.

## Notifications / announcements

It helps a launch go smoothly if all stakeholders are aware of the impending launch and understand the launch plan as well as their role and responsibilities. In addition to notifying teams that will be actively involved, it can help to notify teams that might be needed if anything goes wrong. Having someone on standby during a launch can help expedite response. Be sure to identify and notify any team that might need to answer questions from customers, including on social media.

### Parties to notify

* Customers
* Business parters, if applicable
* Application team(s) impacted by launch
* Support teams
* Network teams (network changes, on standby, in case of issues)
* Security teams (on standby, in case of issues)
* Marketing teams (ready for announcements, response to issues)
* Social media teams (ready to monitor social media, respond)
* Sales teams (prepared to answer questions from customers)
* Customer success teams (prepared to answer questions from customers)

## Notification plan

Your notification plan should include elements such as the target <Tooltip href="/docs/glossary?term=audience">audience</Tooltip>, the key takeaways for the audience, the message content, the plans for distributing the notification and how to test the messaging.

A list of elements to include in the plan are:

* Target audience (consider both internal & external audiences)
* Message
* Timing
* Dependencies
* Responsible parties (who will send it)
* Mechanism (how it will be communicated)
* Test message and delivery (if applicable - test to ensure notifications sent)

## Notification distribution

A common tactic is to release notifications in batches to spread out the initial onslaught of load and reduce the scope of confusion if there are any unforeseen glitches. It’s easier to correct issues with a small group than during a big-bang launch.

* One approach is to start with a relatively small batch of notifications, and if no issues are identified, increase the size of the batches over time.
* You can also send out batches on a rolling schedule around the globe to spread out load hitting the system at once and have notifications arrive at an optimal time within each timezone to increase the likelihood of the messages being read.
* You can do a soft-launch to a portion of users, such as individual customers, regions or some other grouping that makes sense for your application.

## Outage windows (if needed)

Some organizations require a formal request for an outage window if any outages or downtime is required for a launch. If your organization requires this, be sure to identify if any downtime is required for the cutover or launch (or other dependent systems) and file the necessary outage or change requests in advance of any lead-time requirements.

## Cutover plan (if needed)

Some launches involve cutover from a previous solution to a new solution. If your project fits this scenario, you should be sure to identify everything that needs to happen as well as any dependencies, the responsible party for each task, and necessary timing. You may wish to plan alternates for all important roles or in each region in case anyone is unexpectedly sick or otherwise unavailable. A checklist of items to consider for the cutover plan is:

* Have you documented the cutover plan and rollback plan if needed?
* Are backups needed of anything prior to change?
* Are any preparatory data changes required?
* Any DNS records to be changed?
* Any Firewall changes?
* Any new monitoring targets?
* Any software to be deployed?

## Go / no-go criteria

In your overall launch plan, it is helpful to have go/no-go criteria and to have discussed in advance the types of issues which could occur and which could be worked through vs would require reverting. A launch plan can specify periodic check-in timeframes with criteria of what to assess at each checkpoint and how long to allow an issue to continue unresolved.

For each stage of the launch, it helps to have success criteria defined, that indicate the launch is proceeding as planned and can continue. Some example criteria could be:

* User signups growing with minimal errors
* User logins at expected rate, minimal errors
* Reported support issues below a certain threshold
* No issues identified that could lead to corrupted data

It’s also helpful to have identified criteria which could trigger a “no-go” decision to halt the launch. The risk tolerance for each environment varies, but a few example criteria might include:

* High percent of user signup or login resulting in errors that cannot be resolved quickly
* High number of support issues that cannot be resolved quickly
* Condition identified that could lead to data corruption
* High severity security issue discovered

## Rollback

It is always wise to have a plan for how to rollback or revert a launch, just in case something unforeseeable occurs which cannot be resolved. Reviewing the launch plan for every step which involves a change can help identify the tasks or changes requires to revert a launch or cutover.

The rollback plan should include the steps to take, the sequence, how long each is likely to take and the responsible party. Understanding the cumulative time required to roll back can help to determine the timing of the final go/no-go decision to fit within any required outage window.

If any data is migrated or changed for the launch, the plan should include how to revert it, if needed. Reverting may require running scripts to undo operational changes or restoring a data store from a backup taken before the launch process began.

It is also necessary to plan for the case where some data is entered into a new system before it has to be reverted. Will such data / transactions need to be abandoned with the rollback or will you have a way to capture and apply them elsewhere so they aren’t lost?

If the resolution of issues or process to revert could potentially take longer than one shift, you’ll want to ensure you have a primary and perhaps a secondary person available and prepared to handle things during each work shift. If an issue results in the need for prolonged response, significantly beyond one shift, there are limits for how long people can realistically function without a break. It can help to be prepared with resources for a follow-the-sun issue response effort if needed.

## Standby contacts

As the launch day approaches, it’s a good idea to identify all contacts who might be needed for troubleshooting or resolving issues and request them to be on standby and ready to help if needed. The launch leader should have contact information for each person on the standby list to expedite communications.

If there is a physical or virtual "launch room", the people on standby should know where it is and be ready to join if needed. Having a central room or video conference prepared can expedite communications and troubleshooting across all parties if an issue occurs.

## Success Criteria

A lot of planning goes into a launch in order to be successful, but will you know how to evaluate the launch? If you define success criteria before the launch, you can determine what to monitor and if any additional monitoring or checks need to be in place to evaluate the launch. For example - if one element of the success criteria is the number of sign-ups or logins - do you have a way of monitoring that and has it been tested to ensure it is accurate?

You’ll want statistics to be able to trumpet the success of your launch. You don’t want to find out after the launch that you didn’t capture any data to quantify all the hard work your team put into the launch.

## Risks & mitigations plan

It’s no fun to think of things that could go wrong, but if anything happens, you’ll be glad you did as having a plan can expedite response. A few examples to plan for include:

* Software application bug
* Application incompatibility with user browser settings
* Network failure/outage
* DoS attack
* Hosting environment failure
* Load / capacity issues
* Data / corruption issues
* Security vulnerability discovered

If you had a beta period, it may help to review the results of the beta to identify additional possible failure scenarios.

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2C IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/3er1aEQ7Ul0q3c9leJWczR/b1f18b4c16abb7e78b01e4eb2b52bb8e/B2C_Project_Planning.pdf)


# Operations Readiness (B2C)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-consumer/launch/operations-readiness

Operations checks to perform before launch of your B2C IAM implementation.

## Status

You should ensure your operations staff knows how to monitor Auth0 service status and has set up a means to subscribe to updates on Auth0 status.

The Auth0 [status dashboard](https://status.auth0.com/) together with the Auth0 [uptime dashboard](http://uptime.auth0.com/) shows current and past status of the Auth0 service in a human-readable format. If any monitoring alerts are triggered, and as a first step in troubleshooting, your operations staff should check the status dashboard to see if there is a current outage. The public cloud status page also provides a facility for subscribing to outage notifications, and we also recommend that you check the status of any third-party [external services](/docs/deploy-monitor/monitor/check-external-services-status) you depend on, such as Social Providers. Having this information handy can help quickly eliminate possible causes when troubleshooting an issue and should be at the top of a troubleshooting checklist for developers as well as the help desk staff.

<Info>
  ### Best Practice

  Information on how to check the status of Auth0 as well as any dependent services (such as Social Providers) should be at the top of a troubleshooting checklist for both developers and helpdesk staff, and we recommend you subscribe via the Auth0 status page to set up notification of any status updates.
</Info>

In the event of an outage to the public cloud service, Auth0 performs a Root Cause Analysis (RCA) and publishes the results on the Auth0 status page. Auth0 performs a thorough investigation after an outage—including a determination of root cause, as well as contributing factors and how to prevent the issue from occurring again—and as a result, an RCA document can take a few weeks to be published.

## Email provider setup

You should double check that you have set up your own email provider to support production volumes of emails that might be sent to customers for signup, email validation, account recovery and the like.

Auth0 sends [emails](/docs/customize/email) to users for events such as signup welcome, email validation, breached password, and password reset events. You can customize the email templates for each type of event, and advanced customization of email handling is also possible. Auth0 provides a test email provider with limited capacity for basic testing, but you must set up your own email provider for production use, and customization of email templates will not work until you have established your own provider.

<Info>
  ### Best Practice

  The default Auth0 email provider does not support sending production volumes of email or customization of email templates. You should therefore configure your own email provider before deploying to production.
</Info>

## Infrastructure

### Firewalls

If custom code executing in Auth0 (such as in an Action, Rule, Hook, or Custom DB scripts) will call a service inside your network, or if you configure an on-premise SMTP provider in Auth0, then you may need to configure your firewall to allow [inbound traffic from Auth0](/docs/secure/security-guidance/data-security/allowlist). The IP addresses to allow through the firewall are specific to each region and are listed on the Rules, Hooks, custom database scripts, and email provider configuration screens in your <Tooltip href="/docs/glossary?term=Auth0+dashboard">Auth0 dashboard</Tooltip>.

## NTP

If this is not handled automatically by your hosting environment, you should have scripts which will automatically restart NTP (Network Time Protocol) if it fails and alerts that will notify someone if NTP is not running. Authentication transactions rely on accurate system time because <Tooltip href="/docs/glossary?term=security+tokens">security tokens</Tooltip> may be evaluated as expired when received if there are time discrepancies between sending and receiving systems.

## LoadBalancer timeouts checked

If you use the AD/LDAP connector, you should check the load balancer settings in your environment to see if they terminate long running connections that are inactive. If they do, you can modify the [Auth0 AD/LDAP Connection settings](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-to-auth0) to use the `LDAP_HEARTBEAT_SECONDS` setting to send periodic heartbeat messages to keep the connection open.

## LoadBalancer configuration

If your application maintains server state such that it depends on sticky load balancing to route users to a particular server, it can be beneficial to double check that all load balancer configurations are correct. One load balancer in a pool that is out of sync can cause intermittent errors that are hard to troubleshoot. A quick check of load balancer configuration can avoid such issues in the first place.

## Logs

You should check that you have set up the ability to capture log data, that logs are covered by your data retention policy and you have mechanisms to enforce logs data retention limits. You should also make sure that your development, support, and security teams know how to access logs data for troubleshooting and forensics purposes. Exporting log files to services that provide comprehensive analytics can help you identify patterns such as usage trends and errors.

Auth0 provides extensive capability when it comes to the logging of events, and also in the scanning of logs in order to identify event anomalies (see [logs documentation](/docs/deploy-monitor/logs) for further details). Standard log retention period for Auth0 logs is determined by subscription level with the shortest period being two days and the longest period being only 30 days. Leveraging Auth0 support for integrating with external logging services will allow you to retain logs outside of this, and will also provide for log aggregation across your organization.

<Info>
  ### Best Practice

  You should leverage one of the log streaming solutions to send log data to an external log analytics service. This will enable keeping data for longer periods of time and provide advanced analytics on the log data.
</Info>

You should review the log data [retention period](/docs/deploy-monitor/logs/log-data-retention) for your subscription level, and implement a log data export service to send log data to an external log analytics service. You can use one of our [log streaming solutions](https://marketplace.auth0.com/features/log-streaming) in Auth0 Marketplace.

Development teams can use log files for troubleshooting and detecting intermittent errors that may be hard to find via QA tests. Security teams will probably want log data in case forensic data is ever needed. Exporting log files to services that provide comprehensive analytics can help you see patterns such as usage trends and <Tooltip href="/docs/glossary?term=attack+protection">attack protection</Tooltip> triggers.

### Rate limits and other errors

Auth0 provides a unique error code for errors reported when the [rate limit is exceeded](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy). You should set up automatic scanning of logs to check for rate limit errors so you can proactively address activity that hits rate limits before it causes too much trouble for your users. Auth0 also publishes error codes for other types of errors, and you will find it helpful to scan logs for [authentication errors](/docs/libraries/common-auth0-library-authentication-errors) as well as errors from Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> calls (Management API error codes are shown below each call in the [Management API Explorer](https://auth0.com/docs/api/management/v2)).

<Info>
  ### Best Practice

  Calling the Management API to retrieve user profile information from within a Rule is a common cause of rate limit errors because such API calls can execute for every login as well as periodic session checks.
</Info>

## Monitoring

Be sure to set up proactive monitoring of the Auth0 service as well as end-to-end authentication through your application.

You should establish mechanisms for [monitoring Auth0 implementations](/docs/deploy-monitor/monitor), so your support or operations team receives the timely information needed to proactively handle service outages. Auth0 provides monitoring endpoints that can be incorporated into your monitoring infrastructure. These endpoints are designed to provide a response suitable for consumption by monitoring services. It should be noted that they only provide data on Auth0. For complete end-to-end monitoring, which is essential for checking the ability of users to log in, we recommend that you set up synthetic transaction monitoring. This will provide greater granularity for your monitoring and enable you to detect outages unrelated to Auth0 as well as degradation of performance, so you can respond more proactively.

<Info>
  ### Best Practice

  You should set up the ability to send synthetic login transactions to facilitate end-to-end monitoring of authentication. You can do this with a simple application that uses the [Resource Owner Password Grant](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow/call-your-api-using-resource-owner-password-flow) in combination with a test user that has no privileges, and don’t forget about [Auth0 rate limiting policies](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy) too.
</Info>

## Auth0 Notifications

You should ensure your team is monitoring all of the following communication channels from Auth0 to stay abreast of important announcements and changes.

There are several different types of notifications from Auth0 that you should watch for as they contain important information that could impact your tenant(s) and project.

<Callout icon="file-lines">
  Proactive security notifications and other operational announcements are sent by Auth0 to dashboard administrators. You should ensure that the people who need to receive such messages are dashboard administrators.
</Callout>

### Dashboard notifications

From time to time, Auth0 may send an important announcement related to your tenant. These announcements about your service will be sent to your Auth0 dashboard and depending on the severity of the announcement, via email to the registered Auth0 dashboard administrators. You should make a regular practice of logging in to the dashboard and checking the bell icon at the top for any important notices. In addition, you should review emails from Auth0 in a timely fashion as they may convey important information about changes or actions you need to take.

### Auth0 security bulletins

Auth0 regularly conducts a number of security-related tests, and if any issues are found, will proactively identify and notify customers who need to make security-related changes. Due to the extensible nature of the Auth0 product, however, it may not be possible for Auth0 to identify every impacted customer, so you should regularly check Auth0 [security bulletins](/docs/secure). You should make sure a security contact for your organization is listed in Support Center.

<Info>
  ### Best Practice

  It is a best practice to check the Auth0 [Security Bulletins](/docs/secure/security-guidance/security-bulletins) page periodically and take the recommended action if you are impacted by any security bulletins.
</Info>

### Change log

Auth0 provides information on changes to the service in the Auth0 [change log](https://auth0.com/changelog). You should make a regular practice of reviewing Auth0 change logs to be aware of changes. Support teams researching an issue may find it useful to review the change log to determine if recent changes might be related, especially if these are breaking changes. Development teams will also want to review the change logs to identify new features that may be beneficial.

In addition, you should periodically check the [Auth0 migrations page](/docs/troubleshoot/product-lifecycle/deprecations-and-migrations) for news about upcoming deprecations that might require your team to make changes.

## Automated Deployment, version control

While not required, it is highly recommended that you have deployment automation set up. You can respond more efficiently if you need to make any changes after launch if you have automated the ability to deploy and revert changes to dev, test and production environments.

In addition to adopting best practices for change management and [QA](/docs/get-started/architecture-scenarios/business-to-consumer/quality-assurance), successful customers will also integrate Auth0 collateral management as part of some automated deployment process. As discussed in the Architecture section under [SDLC support](/docs/get-started/architecture-scenarios/business-to-consumer/architecture#sdlc-support), you will want to ensure you configure separate Auth0 tenants for development, testing, and production environments, and you will want that configuration to be almost identical for the tenant in each environment. Using deployment automation helps ensure this, so that each environment tenant is configured the same, and you will be less likely to see bugs show up as a result of mismatched configurations between environments.

<Info>
  ### Best Practice

  However you configure deployment automation, we’d recommend you unit test your rules, custom DB scripts, and hooks prior to deployment, and run some integration tests against your tenant post-deployment too. For more details regarding this, see the [Quality Assurance](/docs/get-started/architecture-scenarios/business-to-consumer/quality-assurance) guidance provided.
</Info>

Auth0 provides support for a couple of different options when it comes to the deployment automation approaches you can use, and each can be used in conjunction with the other if desired:

* The [Auth0 Deploy CLI tooling](/docs/deploy-monitor/deploy-cli-tool) provides you with an easy-to-use script that can help you integrate with your existing Continuous Integration/Continuous Deployment (CI/CD) pipeline.
* If you can’t integrate directly with, or for some reason you don’t have a CI/CD pipeline, then the Auth0 [Source Control Extensions](/docs/customize/extensions) can provide an easy-to-set-up basic automation process with very low maintenance.

<Warning>
  Note that both the Deploy CLI Tool and source control extensions can cause destructive changes; manual changes made directly in the dashboard between automated deployments could be lost! For this reason, if either is used, then **all** changes should be deployed from the source control subsystem referenced via the tooling and not made manually.
</Warning>

Each environment may also need some environment-specific configuration—Application <Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>’s and <Tooltip href="/docs/glossary?term=Client+Secrets">Client Secrets</Tooltip> will be different between the Auth0 tenants, for example—so you’re going to want some way of being able to dynamically reference this rather than having hard-coded values. Auth0 provides support for handling environment-specific configuration information through one of the following two approaches:

* Use [Tenant Specific Variables](#tenant-specific-variables)
* Use [keyword replacement](/docs/deploy-monitor/deploy-cli-tool/configure-the-deploy-cli) if using the Auth0 Deploy CLI tool

## Tenant specific variables

Auth0 allows you to configure variables that are available from within custom [extensibility](/docs/customize/extensions); these can be thought of as environment variables for your Auth0 tenant. Rather than hard code references that change when moving code between development, test, and production environments, you can use a variable name that is configured in the tenant and referenced by the custom extensibility code. This makes it easier for the same custom code to function, without changes, in different tenants as the code can reference variables which will be populated with tenant-specific values at execution time:

* For use of variables in Actions, see [Write Your First Action](/docs/customize/actions/write-your-first-action) to learn how to configure secrets in the editor
* For use of variables in Rules, see how to [configure values](/docs/customize/rules/configuration)
* For use of variables in Hooks, see how to configure [secrets](/docs/customize/hooks/hook-secrets) in the editor
* For use of variables in Custom DB Scripts, see the [configuration parameters](/docs/authenticate/database-connections/custom-db/create-db-connection#step-3-add-configuration-parameters)

<Info>
  ### Best Practice

  It’s a recommended best practice to use variables to contain tenant-specific values as well as any sensitive secrets that should not be exposed in your custom code. If your custom code is deployed in GitHub/Gitlab/Bitbucket/VSTS, then using a tenant-specific variable avoids exposure of sensitive values via your repository.
</Info>

## Backup / Restore

You should have a plan and mechanism in place to support any backup/restore capability needed for your project. This can be done using the Auth0 Management API for data as well as the Automated Deployment capabilities described in the automated deployment section for Auth0 configuration.

As noted in the Auth0 [Data Tenant Restore policy](/docs/troubleshoot/customer-support/operational-policies) and [Data Transfer policy](/docs/troubleshoot/customer-support/operational-policies/data-export-and-transfer-policy), Auth0 does not restore deleted tenants or move data between tenants. Auth0 provides the Auth0 Management API to provide customers a completely flexible capability to backup, restore and move data as needed. Customers can write scripts to retrieve data from Auth0 for backup purposes, and similarly write scripts for use with the Automated Deployment capability to restore any aspect of their Auth0 configuration.

## Versions Up to Date

You should double check that all technologies in your application stack, as well as browser versions used by your users are on current, up-to-date versions as this will impact Auth0’s ability to provide support if issues arise.

* Check you are using the latest supported version of node.js in [Auth0 dashboard settings](/docs/get-started/tenant-settings).
* Check you are using a version of SDK/Libraries supported by Auth0 per the [Auth0 Support Matrix](/docs/troubleshoot/customer-support/product-support-matrix).

## Certificate rollover plan

Certificates may be used in identity deployments. To ensure a certificate expiration does not catch you by surprise, you should have a list of certificates in your environment along with the expiration dates, how you will be notified when expiration draws near and how the certificate rollover process works.

### SAML connections

For <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> connections, you obtain a certificate from the <Tooltip href="/docs/glossary?term=IdP">IdP</Tooltip> and upload it to a SAML connection for the IdP in your Auth0 dashboard. When one of these certificates is about to expire, Auth0 will send email to dashboard administrators warning of the upcoming expiration. You can obtain the new certificate and upload it using the connection configuration screen.

### WS-Fed connections

For <Tooltip href="/docs/glossary?term=WS-Fed">WS-Fed</Tooltip> connections, if you configure them by specifying an ADFS URL, any changes will be picked up by a daily update. You can trigger an update manually by visiting the connection configuration page in the Auth0 dashboard and doing a Save. If a certificate is changed at the remote IdP, Auth0 can be updated by those mechanisms or by uploading a new metadata file in the same connection configuration screen.

## Disaster Recovery / Business Continuity Plan in place

While not an absolute requirement prior to launch, it is useful to have a disaster recovery plan in place to ensure business continuity in the face of different types of disasters, including system outages and natural disasters hitting a region where critical staff is located.

## Processes documented

Another item which is not an absolute requirement, but also recommended is to ensure all processes related to Auth0 are documented. This can include the following:

* Change management for configuration
* Deployment of new changes and any automatic deployment mechanisms used, how to revert to previous version if issues found
* Certificate rollover processes, if any
* Adding or removing new Identity Providers, if applicable
* Changes to user profile structure in Auth0 or in directories Auth0 pulls from
* Adding or removing applications or APIs
* Capturing and exporting logs
* Backup/restore process you have implemented
* User management (forgotten password, lost phone)
* Root cause analysis after an incident

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2C IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/3er1aEQ7Ul0q3c9leJWczR/b1f18b4c16abb7e78b01e4eb2b52bb8e/B2C_Project_Planning.pdf)


# Support Readiness (B2C)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-consumer/launch/support-readiness

Support readiness for the launch of your B2C IAM implementation.

## Review Auth0 Policies

When starting to prepare for your launch, be sure to read through [Auth0 Policies](/docs/troubleshoot/customer-support/operational-policies) and prepare your production operations accordingly for any required lead times or responsibilities on your part, according to the policies.

## Review your Support plan, SLAs, Severity definitions and Support center documentation

You should review the specifics of the [support plan](/docs/troubleshoot/customer-support) you’ve purchased and the Service Level Agreements associated with it, to ensure it is adequate for your needs. If you haven’t already done so, explore the [support center](https://support.auth0.com/) and familiarize yourself with support features such as viewing suggested solutions to common issues and [filing tickets](/docs/troubleshoot/customer-support/open-and-manage-support-tickets) and viewing your quota usage. It will be helpful to review the severity level definitions for support tickets so that you file tickets with the correct severity. One important note is that it is not possible today in the Support Center to increase the severity of a support ticket. If you file a ticket for a medium-grade issue which later becomes a high severity issue, you should file a new urgent, high severity ticket that explains anything new that triggers the urgency and references the original ticket for details.

You should also ensure your development and support teams are familiar with the [Auth0 community forum](https://community.auth0.com/), discussed further below. Customers can often find answers there right away to common issues, avoiding the need to file a ticket, so it should be your first stop for technical questions.

## Review the Auth0 community forum

The [Auth0 community forum](https://community.auth0.com/) contains a wealth of information. If you have a question, chances are someone else has already asked the question on the forum. Answers are contributed by both Auth0 staff and the larger community of Auth0 users.

Important notices are posted to the community forum to help you stay abreast of important news. Be sure to check out the “Community” and “FAQ” categories. The Community category contains pro-active posts on product announcements, roadmap information, How-To videos as well as important information about any upcoming feature deprecations.

It’s a good idea to check out the Auth0 Community on a regular basis, not just when you have questions. While you are there, if you see a question you’ve already solved, please contribute your wisdom to help others!

## Gather Auth0 troubleshooting information needed for support tickets

We recommend your support team become familiar with our [troubleshooting guides](/docs/troubleshoot) specific to identity protocols and Auth0. This includes the questions to research and information to collect before posting a question on the Auth0 forum or filing a support ticket. Authentication transactions often span multiple systems so there are some specialized troubleshooting techniques that are helpful to learn.

## Have troubleshooting tools ready

Your team will doubtless have already done some troubleshooting during the development of your application, but we recommend making sure your support team is also familiar with any tools below relevant to your project. If you need to file a ticket, the Auth0 support team may ask for a HAR (HTTP Archive) file to help analyze the issue so it’s helpful for your support staff to be familiar with how to do this.

<Warning>
  Before sharing a HAR file with anyone (including Auth0), ensure that you remove or obfuscate all sensitive data, such as:

  * Confidential user information
  * Personal identifiable information (PII)
  * Confidential application information

  To learn more, read the following articles on [Auth0 Community](https://community.auth0.com):

  * [Sanitizing HTTP Traces](https://community.auth0.com/t/sanitizing-http-traces/119488)
  * [How to Sanitize an HTTP Trace File Automatically](https://community.auth0.com/t/how-to-sanitize-a-http-trace-file-automatically/120583)
  * [How to Manually Redact Sensitive Information](https://community.auth0.com/t/how-to-manually-redact-sensitive-information/122554)
  * [HAR File is Too Large to Upload to the Support Case](https://community.auth0.com/t/har-file-is-too-large-to-upload-to-the-support-case/122488)
</Warning>

### Capture HAR file

A [HAR file](/docs/troubleshoot/troubleshooting-tools/generate-and-analyze-har-files) captures a sequence of browser interactions and is a commonly used tool when debugging authentication issues. The process of authenticating a user often involves redirecting the user’s browser from an application to Auth0, and possibly to another remote <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip>, depending on the type of connection used. You can capture the redirection and the responses and analyze it to find clues about the cause of an issue.

### Analyze HAR file

Analyze the HAR file to obtain valuable troubleshooting information. It shows the sequence of browser redirects involved in an authentication transaction, along with the parameters used. The HAR file also shows if the authentication process stopped mid-stream and if so where, which helps to pinpoint the location of the issue. The HAR file contains tokens returned to the application front-end, and these can be pasted into appropriate viewers to see if they contain the expected contents.

### View JWT

The [jwt.io](https://jwt.io/) tool was written by Auth0 and allows you to view the contents of a <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip>-formatted token. Applications that delegate authentication to Auth0 via OIDC will receive an <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip> from Auth0. Depending on your type of application, the ID Token may be captured in a HAR file. The ID Token is in JWT format and can be pasted into jwt.io to view the contents of the ID Token.

### View SAML request/response

There are many <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> decoders available. The [samltool.io](https://samltool.io/) decoder was written by Auth0 and allows you to view the contents of a SAML Request or Response. Applications that delegate authentication to Auth0 via SAML or use a SAML type of connection in Auth0 will use SAML Requests and Responses. These SAML Requests and Responses may be captured in a HAR file. The requests and responses can be pasted into samltool.io or other SAML decoders to view the contents of the SAML Request or Response.

## Review Auth0 support matrix

One potential cause of issues is using out of date versions of SDKs or libraries. We strongly recommend your team check your software stack, browsers, SDKs and libraries against the [Auth0 support matrix](/docs/troubleshoot/customer-support/product-support-matrix) to ensure you are running on up-to-date, supported versions. In the event of an issue, the Auth0 support team may ask you to upgrade to a supported version. To avoid slowing down progress on issue resolution, be sure you are on up-to-date versions.

## Use Auth0 feedback portal

Auth0 welcomes feedback and ideas from Auth0 customers. If you have a suggestion for our product team, you can submit product feedback directly on the [Product Feedback portal](https://auth0.com/feedback).

## Actions Real-time Logs

For debugging and supporting custom code in Auth0, including Actions, Rules, Hooks, custom database scripts, and custom <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> connections, knowledge of [Actions Real-time Logs](/docs/customize/actions/actions-real-time-logs) is essential. This enables you to view output from your custom code, including output from `console.log` statements.

We recommend using Actions Real-time Logs and getting familiar with using it to view log output from your custom code as a debugging and support tool.

## Troubleshooting

You should prepare to [troubleshoot basic issues](/docs/troubleshoot/basic-issues) both during your development as well as after your application or API goes live. Make sure your development and support teams are prepared with knowledge of troubleshooting tools, and the list of common issues to check when troubleshooting an issue.

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2C IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/3er1aEQ7Ul0q3c9leJWczR/b1f18b4c16abb7e78b01e4eb2b52bb8e/B2C_Project_Planning.pdf)


# Tenant Check (B2C)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-consumer/launch/tenant-check

Tenant Checks to perform before launch of your B2C IAM implementation.

This section covers a list of configurations to check in your tenant. This should be done periodically during development and sufficiently before launch so you have time to fix anything amiss.

## General tenant check

### Tenant preparation check

Check to ensure you have set up tenant environments to support your SDLC lifecycle and that Dev, Test and Prod tenants are cleanly separated so that ongoing development work after launch doesn’t negatively impact your production environment.

Every company has some form of Software Development Life Cycle (SDLC), and throughout the development process you will want to align with that strategy. For instance, you need to be able to test your integration with Auth0 in a similar fashion as you test the applications themselves. It is therefore important to [structure Auth0 tenants to support your SDLC](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments), and there is a consistent pattern which our customers typically follow when it comes to the best practices associated with tenant layout for doing so:

<table>
  <thead>
    <tr>
      <th>Environment</th>
      <th>Sample Tenant Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Development</td>
      <td><strong>company-dev</strong></td>
      <td>A shared environment where most of your development work occurs</td>
    </tr>

    <tr>
      <td>QA/Testing</td>
      <td><strong>company-qa</strong> or <strong>company-uat</strong></td>
      <td>An environment for formal testing of the changes you've made</td>
    </tr>

    <tr>
      <td>Production</td>
      <td><strong>company-prod</strong></td>
      <td>The production tenant</td>
    </tr>
  </tbody>
</table>

In some cases you may also want to create one or more sandboxes (e.g., **company-sandbox1**, **company-sandbox2**) so that you can test changes without compromising your development environment. This might be where you test deployment scripts and the like.

<Info>
  ### Best Practice

  You can also take advantage of our [Implementation Checklists](/docs/get-started/architecture-scenarios/checklists) that you can download and customize to meet your implementation project needs.
</Info>

### Tenant association check

To ensure that your [tenants are all associated with your Auth0 contractual agreement](/docs/get-started/auth0-overview/create-tenants/child-tenants) and have the same features, ensure all your tenants are associated with your company account. If you have individual developers that want to create their own sandboxes for testing, make sure they get associated with your account so they have the same permissions too. To do this you should contact your Auth0 representative or the [Auth0 Support Center](https://support.auth0.com/center/s/).

### Specify production tenant

To ensure Auth0 recognizes your production tenant, be sure to [set your production tenant](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments#set-the-environment) with the “production” flag in the Support Center.

### Tenant production check

Auth0 provides a [Production Check](/docs/deploy-monitor/pre-deployment-checks) facility to detect many common errors. You should ensure this has been run and any findings from the report mitigated before launch.

In addition, you should check the [best practice configurations advice](/docs/deploy-monitor/pre-deployment-checks/production-checks-best-practices), for which checking cannot be automated.

### Tenant settings check

#### Tenant settings

Make sure to follow the Auth0 [tenant settings](/docs/get-started/tenant-settings) recommendations in configuring your branding as well as your support email and support URL so users know how to get help if an issue occurs. You'll want to check your <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> Session Timeout settings and the list of dashboard admins with access to your production tenant as well.

#### Error page customization

If there are issues encountered during user interactive workflow (e.g. user sign up or login), Auth0 provides error messages that indicate what the problem is under the hood. The default messages are somewhat cryptic, especially to the end user, since they will likely be missing context that only you can supply. As such, we recommend [customizing your error pages](/docs/customize/login-pages/custom-error-pages) to provide the missing context-specific information directly to your users. Furthermore, customizing your error pages allows you to display your branding, not Auth0's, as well as provide useful information to your users as to what should be done next. This information might include a link to a FAQ or how to get in touch with your company's support team or help desk.

<Info>
  ### Best Practice

  Out-of-the-box there is no user interface for customizing Auth0 provided error pages, but you can use the [Tenant Settings endpoint of the Management API](https://auth0.com/docs/api/management/v2#!/Tenants/patch_settings) to configure them. Alternatively, if you can create and host your own error page, then you can have Auth0 direct users to that page instead of using the Auth0-hosted option.
</Info>

#### Legacy feature flags off

If you have an older tenant, you may have various legacy feature flags enabled in your [tenant settings advanced tab](/docs/get-started/tenant-settings). If you have any toggles on in the “Migrations” section of this tab, you should review your usage and make plans to migrate off the legacy feature.

#### Delegated admin extension

While you are checking the list of users with access to your production tenant, don't forget to check any users specified in the [Delegated Admin Extension](/docs/customize/extensions/delegated-administration-extension).

### Custom Domain Naming set up

By default, the URL associated with your tenant will include its name and possibly a region-specific identifier. For example, tenants based in the US have the a URL similar to `https://example.auth0.com` while those based in Europe have something that is of the fashion `https://example.eu.auth0.com`. A [Custom Domain](/docs/customize/custom-domains) offers a way of providing your users with a consistent experience by using a name that’s consistent with your organization's brand.

<Warning>
  Only one custom Domain Name can be applied per Auth0 Tenant, so if you absolutely must have independent domain name branding then you will require an [architecture](/docs/get-started/architecture-scenarios/business-to-consumer/architecture) where multiple Auth0 Tenants are deployed to production.
</Warning>

In addition, <Tooltip href="/docs/glossary?term=Custom+Domain">Custom Domain</Tooltip> functionality offers you complete control over the certificate management process. By default, Auth0 provides standard SSL certificates, but if you configure a custom domain, you can use Extended Validation (EV) SSL certificates or similar to provide the visual, browser-based cues that offer your visitors additional peace of mind.

In general, we see customers having the most success when they use a centralized domain for authentication - this is especially the case if the company offers multiple products or service brands. By using a centralized domain, you can provide end users with a consistent user experience while also minimizing the need to maintain multiple production tenants in Auth0.

## Application and Connection settings check

Each of your connection settings should be reviewed against the [connection configuration best practices](/docs/authenticate/connection-settings-best-practices).

In addition, you should review that all connections are appropriate and that no experimental connections are left in your production tenant as they could enable unauthorized access.

If you use <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> connections, it is a best practice to configure the connections to sign SAML requests.

## Page customization check

If you use the Auth0 <Tooltip href="/docs/glossary?term=universal+login">universal login</Tooltip> page, password reset page, or Guardian <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip>, you should check that you have adequately customized the pages displayed to the end user.

### Universal Login Page

[Universal Login](/docs/authenticate/login/auth0-universal-login) is the recommended method for authenticating users, and it centers around use of the Login page. You can customize the Login page to support your organization's branding requirements.

<Info>
  ### Best Practice

  If you choose to customize the Universal Login page script, we strongly recommend that you make use of version control. To do this, you should deploy the script to your Auth0 tenant via [deployment automation](/docs/get-started/architecture-scenarios/business-to-consumer/deployment) or via one of the [alternative strategies](/docs/customize/login-pages/classic-login/version-control).
</Info>

### Password reset page

The [Password Reset](/docs/customize/login-pages/classic-login/customize-password-reset-page) page is used whenever a user takes advantage of password change functionality and, as with the login page, you can customize it to reflect your organization's particular branding requirements.

### Guardian

The Multi-factor Authentication pages can be customized by adjusting the Universal Login branding options in the [Universal Login Settings](https://manage.auth0.com/#/login_settings) section.

If you need further customization, you can also customize [the full HTML content](/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-classic-login) to reflect your organization's particular UX requirements.

## Authorization check

If you are using Auth0’s authorization feature, be sure to double check all privileges granted to ensure authorizations are appropriate for your production environment.

## API configuration check

### Access token expiration

You should double check the [API access token expiration settings](/docs/get-started/apis/api-settings) to ensure they are appropriate for each API in your production environment.

### API offline access

If your application does not request <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip>, this should be off.

### Access token signing algorithm

It is recommended that the [API access token signing algorithm](/docs/get-started/applications/signing-algorithms) be set to RS256 rather than HS256 to minimize exposure of the signing key.

### API Access token validation

If you have any custom APIs, be sure to check that they are adequately [validating the access tokens](/docs/secure/tokens/access-tokens/validate-access-tokens) they receive before using the information in them.

## API Scopes

If you have applications making machine-to-machine calls to any of your APIs, you should review the scopes specified for the API to ensure they are all appropriate for your production environment. For further information see the documentation on [client credentials grant](/docs/get-started/applications/update-grant-types).

## Email templates customized

Auth0 makes extensive use of email to provide both user notifications and to drive the functionality needed for secure identity management (for example, email verification, account recovery, and brute force protections), and Auth0 provides a number of templates for these.

<Callout icon="file-lines">
  Before customizing email templates, please set up your [Email Provider](/docs/get-started/architecture-scenarios/business-to-consumer/operations#email-provider-setup).
</Callout>

Out of the box, the email templates used contain standard verbiage and Auth0 branding. However, you can configure almost every aspect of these templates to reflect the verbiage and user experience you want and make changes to things like the preferred language, accessibility options, and so forth.

Email templates are customized using [Liquid syntax](/docs/customize/email/email-templates/use-liquid-syntax-in-email-templates). If you are interested in customizing your templates based on user preferences, you will also have access to the [metadata](/docs/manage-users/user-accounts/metadata) located in users' profiles, as well as any specific application metadata too.

## Attack protection configured

The reason that authentication systems are important is to prevent <Tooltip href="/docs/glossary?term=bad+actors">bad actors</Tooltip> from accessing applications and user data that they should not. We want to place as many barriers as possible between those bad actors and access to our systems. One of the easiest ways to do this is to ensure that your [attack protection](/docs/secure/attack-protection) with Auth0 is configured correctly, so take a moment to read the guidance on this subject and ensure that it's working correctly for you.

<Info>
  ### Best Practice

  Anomaly detection is handled behind the scenes by Auth0 and provides a great security feature for your product. If you're going to utilize it, ensure that you have set up your [Email Provider](/docs/get-started/architecture-scenarios/business-to-consumer/operations#email-provider-setup) and configured your [Email Templates](/docs/get-started/architecture-scenarios/business-to-consumer/branding#email-template-customization) before turning on email delivery to your users.
</Info>

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2C IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/3er1aEQ7Ul0q3c9leJWczR/b1f18b4c16abb7e78b01e4eb2b52bb8e/B2C_Project_Planning.pdf)


# Testing Complete (B2C)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-consumer/launch/testing

Testing preparation for the launch of your B2C IAM implementation.

Prior to launch, you should have completed all the testing that applies to your environment.

Quality Assurance is important in identifying issues before they impact your customers and, depending on the nature of your project, there are several different types of quality assurance testing that you’re going to want to consider as part of your integration with Auth0:

* Is your application easy to understand and use, even by those with a disability?
* Does your application need to work across various different browsers and devices?
* Does your application need to work in multinational and/or international environments?
* How will your application perform when subjected to unexpected production loads?
* How can you ensure your application is safe from security-related vulnerabilities?

Auth0 [Universal Login](/docs/authenticate/login/auth0-universal-login) and associated UI widgets (such as [Lock](/docs/libraries/lock)) have already been designed and built following usability and accessibility best practices, and provide tested out-of-box support for a whole host of [browsers and devices](/docs/troubleshoot/customer-support/product-support-matrix). Support for [internationalization](/docs/customize/internationalization-and-localization) (I18N) is also provided out-of-box, with built-in extensibility designed for custom multi-language and localization (L10N) situations.

To ensure functional requirements are met and unexpected events are handled correctly, guidance is provided for testing the [integration](#integration-testing) between your application(s) and Auth0, and for [unit testing](#unit-testing) individual extensibility modules (such as [Rules](/docs/customize/rules/debug-rules), [Hooks](/docs/customize/hooks/update-hooks), and Custom Database scripts). Guidance is also provided regarding Auth0's [penetration testing policy](/docs/troubleshoot/customer-support/operational-policies/penetration-testing-policy) to help when testing for security vulnerability, and also how [Mock](#mock-testing) testing can be leveraged in conjunction with our [load testing policy](/docs/troubleshoot/customer-support/operational-policies/load-testing-policy) to help ensure your application(s) perform under unexpected load.

## Unit testing

The objective of unit testing is to test individual units of code. If you create custom code within Auth0 in the form of Rules, Hooks, and/or Custom DB scripts, you should consider use a testing framework (such as [Mocha](https://mochajs.org/)) to test your code. Companies who have been most successful with Auth0 have found it useful to execute these unit tests prior to [automatically deploying](/docs/get-started/architecture-scenarios/business-to-consumer/deployment) Auth0 tenant configuration and collateral.

## Integration testing

It is a recommended best practice that you set up different tenants for development, testing, and production as discussed in Architecture guidance for [SDLC support](/docs/get-started/architecture-scenarios/business-to-consumer/architecture#sdlc-support). Auth0 allows you to configure variables that are available from within custom [extensibility](/docs/customize/extensions); these can be thought of as environment variables for your Auth0 tenant. Rather than hard code references that change when moving code between development, test, and production environments, you can use a variable name that is configured in the tenant and referenced by the custom extensibility code. This makes it easier for the same custom code to function, without changes, in different tenants as the code can reference variables which will be populated with tenant-specific values at execution time:

* For use of variables in Rules, see how to [configure values](/docs/customize/rules/configuration)
* For use of variables in Hooks, see how to configure [secrets](/docs/customize/hooks/hook-secrets) in the editor
* For use of variables in Actions, see Explore Flows and Triggers
* For use of variables in Custom DB Scripts, see the [configuration parameters](/docs/authenticate/database-connections/custom-db/create-db-connection#step-3-add-configuration-parameters)

<Info>
  ### Best Practice

  It’s a recommended best practice to use variables to contain tenant-specific values as well as any sensitive secrets that should not be exposed in your custom code. If your custom code is deployed in GitHub, then using a tenant-specific variable avoids exposure of sensitive values via your GitHub repository.
</Info>

### Test automation

You can automate your overall build process by incorporating deployment automation as well as test automation. This can be used to deploy new versions of configuration and/or custom code to Auth0 and execute automated tests. If the tests uncover any failures, the deployment automation capabilities can be used to revert to the last working version. For further information, see the [deployment automation guidance](/docs/get-started/architecture-scenarios/business-to-consumer/deployment) provided.

## Mock testing

In a balance between Auth0’s [load testing policy](/docs/troubleshoot/customer-support/operational-policies/load-testing-policy) and the desire to load test, it is common practice among Auth0’s customers to mock out Auth0’s endpoints. This is a valuable practice in order to ensure that your application works with your expected interfaces without having to restrict your testing, and tools such as [MockServer](http://www.mock-server.com/), [JSON Server](https://github.com/typicode/json-server) or even [Postman](https://learning.getpostman.com/docs/postman/mock_servers/setting_up_mock/) can be used to assist.

## Pen testing (optional)

If you will be conducting penetration tests, you should be aware of Auth0’s [penetration testing policy](/docs/troubleshoot/customer-support/operational-policies/penetration-testing-policy) and abide by it. Penetration tests require advance notice to Auth0 so that your tests are not mistaken for malicious activity and shut down.

## Load testing (optional)

If you will be conducting load tests, you should be aware of Auth0’s [load testing policy](/docs/troubleshoot/customer-support/operational-policies/load-testing-policy) and abide by it. Load tests require advance notice to Auth0. In planning your load testing, you will also need to be aware of Auth0’s [API rate limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy).

Load tests require prior approval from Auth0, as explained in the Auth0 load test policy. Be sure to note the lead time for a request to be reviewed and allow enough time for review as well as conducting the tests. If your load test request has been approved, the following guidance can help avoid errors and faulty test results.

* Run an HTTP trace on a test execution of your application to identify all the calls your application or intended test needs to make, and make sure your test includes them so it is representative of what will happen in production.
* Design your test to be mindful of Auth0 API rate limits.
* Use of any custom code in Auth0 (Actions, Rules, Hooks, custom database scripts, custom <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> connections) will invoke the Auth0 custom code sandbox and this may cost more in terms of performance. Turn off Rules unless they are essential to the test. If they are off you will have higher throughput than if they are on.
* Estimate the expected overall load for your production environment and percent of calls to each endpoint and structure your performance test accordingly so it gives you a realistic test result. Different endpoints have different performance costs. Failure to design a representative test will result in misleading results.
* Don’t make calls that depend on the results of earlier calls without checking that pre-requisite calls or responses have completed. Simply building in a delay may not be adequate.
* Be sure to implement adequate error handling. A frequent cause of issues during tests is errors in custom code (Actions, Rules, Hooks, custom database scripts, custom OAuth connection scripts) caused by unhandled exceptions in the custom code.
* Load tests should be written to start at a low level and increase the load gradually, capturing data at each level, to get the most useful results. Starting at a high level and immediately failing gives less information about what the system can sustain.
* It is normal to need to run a performance test multiple times, possibly adjusting the code under test or the test harness/configuration. Be sure to start your testing early to allow enough time for more than one iteration.
* Use your own mail provider account and make sure to arrange ahead of time for enough mail-sending quota or you may be rate-limited by the mail provider. Turn off mail sending if you do not use it.
* Be sure to use your own account credentials for all social connections rather than Auth0 dev keys. In the <Tooltip href="/docs/glossary?term=Auth0+dashboard">Auth0 dashboard</Tooltip>, go to Connections -> Social -> \{name of connection}—to see instructions for how to add your own social provider account credentials into the connection. Note: some social providers do not allow load testing. Check your provider(s) for their policy
* In order to avoid rate limiting, and more accurately simulate real load, your tests will need to send requests for different users, not all requests for the same user. If you use only one or a few users, caching may reduce the effective load and not provide realistic results.
* Be sure to stay within the agreed-upon parameters for the test and the Auth0 load test policy. Auth0 reserves the right to terminate any performance/load testing which does not stay within the bounds of agreed-upon parameters or which extends beyond the scheduled test window.

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2C IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/3er1aEQ7Ul0q3c9leJWczR/b1f18b4c16abb7e78b01e4eb2b52bb8e/B2C_Project_Planning.pdf)


# Logout (B2C)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-consumer/logout

User logout planning considerations for your B2C IAM implementation.

[Logout](/docs/authenticate/login/logout) is the act of terminating an authenticated session when it's no longer needed, thus minimizing the likelihood that unauthorized parties can "take over" the session. This is typically achieved by provisioning a logout option on the user interface you provide to your users. Multiple types of sessions can be created when a user logs in (e.g., local application sessions, Auth0 session, third-party <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> sessions), and you will need to determine which of these sessions need to be terminated when the user clicks any **Logout** option.

<Info>
  ### Best Practice

  Your logout behavior should make it clear to a user which session(s) are being terminated, and ideally, will display a visual confirmation of logout afterward.
</Info>

When configuring logout behavior, you'll need to consider:

* Which sessions should be terminated when the user initiates logout?
* What information should you provide to users as confirmation of the sessions terminated?
* Where should users be redirected to after logout completes?
* How long do you want sessions to last in the event that users do not trigger the logout process?

Given the varying types of sessions that can be created whenever a user logs in, there are several types of logout possible. Local application logout ends the session with the application, whereas Auth0 logout [terminates the Auth0 session](/docs/authenticate/login/logout/log-users-out-of-auth0). If you have organizations that are using their own IDP, you may want to consider a [Federated Logout](/docs/get-started/architecture-scenarios/business-to-consumer/logout#federated-logout) strategy and implement accordingly. Global, or [Single Logout](/docs/authenticate/login/logout/log-users-out-of-applications) (SLO), ends the Auth0 session and also sends a logout request/notice to applications relying on the Auth0 session.

The functionality provided by your application, as well as your use of features like [Single Sign-on (SSO)](/docs/authenticate/single-sign-on), will inform your decision as to what type of logout is required and what visual confirmation you'll need to provide to your users. Regardless of which option you choose, the logout process you implement should make it clear to the user which sessions are being terminated, and also when the logout process has completed.

<Warning>
  If the logout feature in one application terminates an Auth0 SSO session that is used by other applications, the user may lose work if they have uncommitted transactions. Be sure to add the functionality needed to handle such conditions to minimize the likelihood of lost work.
</Warning>

## Where to send users after logout

Once your user logs out, they will be redirected to a specific location of your choosing. This location is specified as the **logout redirect URL**, and you can [define this as a parameter](/docs/authenticate/login/logout/redirect-users-after-logout) via the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

The URL(s) you use to redirect users after logging out must be [allowlisted in the Dashboard](/docs/authenticate/login/logout#redirect-users-after-logout) to mitigate open-redirect security vulnerabilities. You can allowlist them at the tenant or application levels.

<Callout icon="file-lines">
  If the user logs out and you redirect them back to the application, and the application redirects to an Identity Provider that still has a valid session for the user, the user will be logged in silently to the application. This may appear to the user as if the logout process didn't function properly.
</Callout>

## Automatic termination of sessions

Not all users will trigger the logout process manually, so Auth0 also provides **session timeout** to prevent overly long-lived sessions. This setting is [available and configurable via the Auth0 Dashboard](/docs/get-started/tenant-settings#login-session-management).

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2C IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/3er1aEQ7Ul0q3c9leJWczR/b1f18b4c16abb7e78b01e4eb2b52bb8e/B2C_Project_Planning.pdf)


# Operations (B2C)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-consumer/operations

How to operationalize your Auth0 tenant environments.

Operationalization requires configuring or setting up infrastructure to support the scalable, measurable, and quantifiable operation that’s necessary for business continuity. In Auth0, this includes configuring supporting services (such as email providers), monitoring services for your deployment, detecting anomalous situations, and making preparations to recover quickly and smoothly when something goes wrong in a production environment.

Establishing effective operational behaviors is something that successful customers have found pays dividends, and there are a number of things you will want to consider when looking at your workflow:

* What should you do to proactively detect failures?
* How can you obtain data on Auth0’s operational status?
* What should you do about Auth0 security bulletins related to the Auth0 service?
* Does Auth0 provide information regarding impending changes in the Auth0 service?
* How can you check for important notices from Auth0?
* What should you do with Auth0 log data so that you can analyze it and keep it for longer than Auth0’s limited data retention period?
* How can you scan Auth0 logs to determine if peak loads in your application trigger any rate limits or other errors?
* What email services should you use to support production volumes of email messages to users? Can I use Auth0's out-of-box email provider in my production environment?
* Do you need to configure your firewall and what firewall ports will you need to open for internal services that need to receive communications from Auth0 (such as custom databases, web services, and email servers)?

Auth0 supports functionality for [monitoring](/docs/get-started/architecture-scenarios/business-to-consumer/operations#monitoring) Auth0 service operation as well as providing information regarding Auth0 [service status](/docs/get-started/architecture-scenarios/business-to-consumer/operations#service-status). In addition, Auth0 makes security-related bulletins as well as information regarding upcoming changes to the Auth0 service available via various [notifications](/docs/get-started/architecture-scenarios/business-to-consumer/operations#notifications). Auth0 [logging](/docs/get-started/architecture-scenarios/business-to-consumer/operations#logging) services also provide extensive functionality for tracing and identifying operational anomalies, including restrictions encountered due to rate limiting and/or excessive loading.

Out-of-box, Auth0 provides email delivery services to help you accelerate your integration. These services, however, are not meant for scale-of-use in production environments, and do not provide for any specific service level or guarantee when it comes to email delivery. Our best practice recommendation, which customers typically follow, involves configuring your own [email service provider](/docs/get-started/architecture-scenarios/business-to-consumer/operations#email-provider-setup).

You may also need to make changes to [infrastructure](/docs/get-started/architecture-scenarios/business-to-consumer/operations#infrastructure) configuration in order to support integration with Auth0 and to support use of Auth0 extensibility. For example, if you need to provide callbacks to your internal or even external infrastructure (e.g., if you need to make external API calls in Actions, Rules, or Hooks, or via custom database scripts if you need to leverage existing legacy identity storage), then you may need to configure your Firewall settings.

## Service status

The Auth0 [status dashboard](https://status.auth0.com/) together with the Auth0 [uptime dashboard](http://uptime.auth0.com/) shows current and past status of the Auth0 service in a human-readable format. If any monitoring alerts are triggered, and as a first step in troubleshooting, your operations staff should check the status dashboard to see if there is a current outage. The public cloud status page also provides a facility for subscribing to outage notifications, and we also recommend that you check the status of any third-party [external services](/docs/deploy-monitor/monitor/check-external-services-status) you depend on, such as Social Providers. Having this information handy can help quickly eliminate possible causes when troubleshooting an issue and should be at the top of a troubleshooting checklist for developers as well as the help desk staff.

<Info>
  ### Best Practice

  Information on how to check the status of Auth0 as well as any dependent services (such as Social Providers) should be at the top of a troubleshooting checklist for both developers and helpdesk staff, and we recommend you subscribe via the Auth0 status page to set up notification of any status updates.
</Info>

In the event of an outage to the public cloud service, Auth0 performs a Root Cause Analysis (RCA) and publishes the results on the Auth0 status page. Auth0 performs a thorough investigation after an outage—including a determination of root cause, as well as contributing factors and how to prevent the issue from occurring again—and as a result, an RCA document can take a few weeks to be published.

## Email provider setup

Auth0 sends [emails](/docs/customize/email) to users for events such as signup welcome, email validation, breached password, and password reset events. You can customize the email templates for each type of event, and advanced customization of email handling is also possible. Auth0 provides a test email provider with limited capacity for basic testing, but you must set up your own email provider for production use, and customization of email templates will not work until you have established your own provider.

<Info>
  ### Best Practice

  The default Auth0 email provider does not support sending production volumes of email or customization of email templates. You should therefore configure your own email provider before deploying to production.
</Info>

## Infrastructure

### Firewalls

If custom code executing in Auth0 (such as in an Action, Rule, Hook, or custom database scripts) will call a service inside your network, or if you configure an on-premise SMTP provider in Auth0, then you may need to configure your firewall to allow [inbound traffic from Auth0](/docs/secure/security-guidance/data-security/allowlist). The IP addresses to allow through the firewall are specific to each region and are listed on the Rules, Hooks, custom database scripts, and email provider configuration screens in your <Tooltip href="/docs/glossary?term=Auth0+dashboard">Auth0 dashboard</Tooltip>.

## Logging

Auth0 provides extensive capability when it comes to the logging of events, and also in the scanning of logs in order to identify event anomalies (see [logs documentation](/docs/deploy-monitor/logs) for further details). Standard log retention period for Auth0 logs is determined by subscription level with the shortest period being 2 days and the longest period being only 30 days. Leveraging Auth0 support for integrating with external logging services will allow you to retain logs outside of this, and will also provide for log aggregation across your organization.

<Info>
  ### Best Practice

  You should leverage one of the log streaming solutions to send log data to an external log analytics service. This will enable keeping data for longer periods of time and provide advanced analytics on the log data.
</Info>

You should review the log data [retention period](/docs/deploy-monitor/logs/log-data-retention) for your subscription level, and implement a log data export extension to send log data to an external log analytics service. You can use one of our [log streaming solutions](https://marketplace.auth0.com/features/log-streaming) in Auth0 Marketplace.

Development teams can use log files for troubleshooting and detecting intermittent errors that may be hard to find via QA tests. Security teams will probably want log data in case forensic data is ever needed. Exporting log files to services that provide comprehensive analytics can help you see patterns such as usage trends and <Tooltip href="/docs/glossary?term=attack+protection">attack protection</Tooltip> triggers.

### Rate limits and other errors

Auth0 provides a unique error code for errors reported when the [rate limit is exceeded](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy). You should set up automatic scanning of logs to check for rate limit errors so you can proactively address activity that hits rate limits before it causes too much trouble for your users. Auth0 also publishes error codes for other types of errors, and you will find it helpful to scan logs for [authentication errors](/docs/libraries/common-auth0-library-authentication-errors) as well as errors from Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> calls (Management API error codes are shown below each call in the [Management API Explorer](https://auth0.com/docs/api/management/v2)).

<Info>
  ### Best Practice

  Calling the Management API to retrieve user profile information from within a Rule is a common cause of rate limit errors because such API calls can execute for every login as well as periodic session checks.
</Info>

## Monitoring

You should establish mechanisms for [monitoring Auth0 implementations](/docs/deploy-monitor/monitor), so your support or operations team receives the timely information needed to proactively handle service outages. Auth0 provides monitoring endpoints that can be incorporated into your monitoring infrastructure. These endpoints are designed to provide a response suitable for consumption by monitoring services. It should be noted that they only provide data on Auth0. For complete end-to-end monitoring, which is essential for checking the ability of users to log in, we recommend that you set up synthetic transaction monitoring. This will provide greater granularity for your monitoring and enable you to detect outages unrelated to Auth0 as well as degradation of performance, so you can respond more proactively.

<Info>
  ### Best Practice

  You should set up the ability to send synthetic login transactions to facilitate end-to-end monitoring of authentication. You can do this with a simple application that uses the [Resource Owner Password Grant](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow/call-your-api-using-resource-owner-password-flow) in combination with a test user that has no privileges, and don’t forget about [Auth0 rate limiting policies](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy) too.
</Info>

## Notifications

There are several different types of notifications from Auth0 that you should watch for as they contain important information that could impact your tenant(s) and project.

<Callout icon="file-lines">
  Proactive security notifications and other operational announcements are sent by Auth0 to dashboard administrators. You should ensure that the people who need to receive such messages are dashboard administrators.
</Callout>

### Dashboard notifications

From time to time, Auth0 may send an important announcement related to your tenant. These announcements about your service will be sent to your Auth0 dashboard and depending on the severity of the announcement, via email to the registered Auth0 dashboard administrators. You should make a regular practice of logging in to the dashboard and checking the bell icon at the top for any important notices. In addition, you should review emails from Auth0 in a timely fashion as they may convey important information about changes or actions you need to take.

### Auth0 security bulletins

Auth0 regularly conducts a number of security-related tests, and if any issues are found, will proactively identify and notify customers who need to make security-related changes. Due to the extensible nature of the Auth0 product, however, it may not be possible for Auth0 to identify every impacted customer, so you should regularly check Auth0 [security bulletins](/docs/secure). Check with your Technical Account Manager to make sure security contacts for your organization are up to date.

<Info>
  ### Best Practice

  It is a best practice to check the Auth0 [Security Bulletins](/docs/secure/security-guidance/security-bulletins) page periodically and take the recommended action if you are impacted by any security bulletins.
</Info>

### Change log

Auth0 provides information on changes to the service in the Auth0 [change log](https://auth0.com/changelog). You should make a regular practice of reviewing Auth0 change logs to be aware of changes. Support teams researching an issue may find it useful to review the change log to determine if recent changes might be related, especially if these are [breaking changes](/docs/troubleshoot/product-lifecycle/deprecations-and-migrations). Development teams will also want to review the change logs to identify new features that may be beneficial.

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2C IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/3er1aEQ7Ul0q3c9leJWczR/b1f18b4c16abb7e78b01e4eb2b52bb8e/B2C_Project_Planning.pdf)


# Profile Management (B2C)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-consumer/profile-management

User profile management planning considerations for your B2C IAM implementation.

At some point, you may need to change the information stored in a user’s profile. A user’s profile (also known as the user’s account) is stored in Auth0, and changes to the information it contains may need to happen for a number of different reasons:

* Self-served information updates
* Mandatory updates concerning your organizations T's & C’s
* Changes due to regulatory compliance

<Warning>
  You cannot directly access a user profile across multiple Auth0 tenants. If you’re deploying multiple Auth0 tenants to production then this is something you need to be aware of.
</Warning>

An [Identity Provider](/docs/authenticate/identity-providers) populates a user’s profile using data supplied during the login process, and this is referred to as the [Normalized User Profile](/docs/manage-users/user-accounts/user-profiles/normalized-user-profiles).

<Callout icon="file-lines">
  The Normalized User Profile is updated from the identity provider during login, and you can change the limited set of the information it contains through the Auth0 Management API. You can also use Auth0 extensibility, such as [Actions](/docs/customize/actions), as an alternative to override information in the Normalized User Profile. See [User Profile Data Modification](https://auth0.com/docs/manage-users/user-accounts/user-profiles#change-user-profile-data) for more information.
</Callout>

By default, there is one user profile created for each user identity, and there are a number of things to consider:

* What should you do if you need to store information to help customize a user’s experience?
* What if you need to store user information that didn’t originate from an <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>?
* Why would you need to store user-related information that a user cannot modify?
* What do you do if you need to store user-related information that a user cannot modify?
* What happens if a user forgets their password?
* What should a user do if they want to change their password?

Auth0 provides for the storage of metadata against a user’s profile, which allows for the capture of additional information, such as preference for language and/or accessibility in order to enhance the user experience. Metadata can be used to store both information that a user can change, and also information they can’t; the latter giving you the capability of associating, for example, a user profile with records in your existing systems without modifying existing implementation.

For users who forget their passwords or who are allowed to change their password via some existing self-service mechanism (or self-service mechanism you have planned), you can leverage Auth0-provided [Password Reset](#password-reset) functionality. This can be integrated with your existing implementation and comes already incorporated with any out-of-box Auth0 UI widgets including [Universal Login](/docs/authenticate/login/auth0-universal-login).

You’ll also want to make sure that you are working with a [verified user account](#account-verification) at all times. Auth0 provides out-of-box mechanisms for doing that too. You should also consider [regulatory compliance](/docs/secure/data-privacy-and-compliance) such as ([GDPR](https://eugdpr.org/) which has very specific requirements when it comes to protecting EU citizens from privacy and data breaches.

Though Auth0 doesn’t currently provide a centralized profile management portal out-of-the-box, for the purpose of self-serviced profile management, you can use the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to build your own or utilize an already built UI. See our Auth0 [community guidance](https://community.auth0.com/t/how-to-allow-the-end-user-to-update-their-own-profile-information/6228) which describes the Management API endpoint. All calls to the Management API will require use of an [Access Token](/docs/secure/tokens/access-tokens).

<Warning>
  Self-service profile management can raise security as well as data privacy concerns. For example, you may want to allow a user to change their email address, however, doing so without following best practice security guidance could result in a user locking themselves out of their account, leaking Personally Identifiable Information (PII), or worse, opening up a potential breach in security.
</Warning>

Alternatively, you can use the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> to [manage aspects of a user’s profile](/docs/manage-users/user-accounts/manage-users-using-the-dashboard). Managing a user’s profile via the Auth0 Dashboard is more of an administrative provision and **should not** be used for self-serviced profile management in a production environment. However, the interface provided by the Dashboard can be extremely useful during development as it provides a quick and simple way of manipulating a user’s profile information.

## Metadata

In addition to the Normalized User Profile information, metadata can be stored in an Auth0 user profile. Metadata provides a way to store information that did not originate from an identity provider, or a way to store information that overrides what an identity provider supplies.

<Callout icon="file-lines">
  Use of Metadata should follow Auth0 [user data storage best practices](/docs/secure/security-guidance/data-security/user-data-storage#metadata). Metadata storage is not designed to be a general purpose data store, and you should still use your own external storage facility when possible. Metadata size and complexity should also be kept to a minimum, and the Auth0 Management API has a strict set of guidance when it comes to updating and/or deleting metadata associated with a user.
</Callout>

You can manipulate metadata via both the Auth0 Management API and the Auth0 Authentication API. As is the case when managing the Normalized User Profile, calls to the Management API for manipulating Metadata requires use of an [Access Token](https://auth0.com/docs/api/management/v2/tokens).

<Warning>
  Calls to the Management API are subject to [Auth0 Rate Limiting policy](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy). You must take this into consideration, and to assist, Auth0 generally recommends use of the appropriate [Auth0 SDK](/docs/libraries) for your development environment rather than calling our APIs directly.
</Warning>

### User metadata

User metadata (also referred to as `user_metadata`) is information that can be stored against a user profile and that a user can read and update as part of any self-service profile management. Metadata of this nature may be something like salutation for a user, or a user’s preferred language which could be used to [customize the emails](/docs/customize/email/email-templates) sent by Auth0.

<Callout icon="file-lines">
  Store any information that you want use to customize Auth0 emails in metadata and preferably `user_metadata` if the user is allowed to change it, such as information used to determine the language for an email.
</Callout>

### App metadata

App metadata (also referred to as `app_metadata`) is, on the other hand, information that can be stored with a user profile but can **only be read or updated with appropriate authorization**; `app_metadata` is not directly accessible to a user. This type of metadata could be something like a flag to indicate that the last set of valid terms and conditions was accepted by the user, and a date to indicate when the user accepted them.

## Password reset

For users who forget their passwords or who are allowed to change their password via some existing self-service mechanism, Auth0 provides [Password Reset](/docs/authenticate/database-connections/password-change) functionality. You can integrate this with your existing implementation and comes already incorporated with out-of-the-box Auth0 UI widgets included as part of [Universal Login](/docs/authenticate/login/auth0-universal-login).

<Warning>
  Password change and password reset is only supported for Auth0 [Database Connection](/docs/authenticate/database-connections/password-change) types.
</Warning>

Auth0 <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> provides built-in UX support for password reset using Auth0 Authentication API functionality. Alternatively, you can use the [Auth0 Authentication API](/docs/authenticate/database-connections/password-change#authentication-api), through one of the Auth0 SDKs appropriate to your development environment. Email templates used during password reset workflow can also be fully customized, whether you use Auth0 out-of-box UI widgets or customized Universal Login.

You can use the Auth0 Management API, on the other hand, to [directly change the password](/docs/authenticate/database-connections/password-change#directly-set-the-new-password) for a user identity defined using a Database Connection type. You can use the Auth0 Management API as part of any self-service profile management implementation, and also as part of any [Change Password page customization](/docs/get-started/architecture-scenarios/business-to-consumer/branding).

## Account verification

You’ll also need to work with a verified user account at all times and make use of the mechanisms Auth0 provides. You should also consider regulatory compliance like [GDPR](https://eugdpr.org/) which has very specific requirements for protecting EU citizens from privacy and data breaches.

Auth0 provides out-of-box functionality for sending a [verification email](/docs/customize/email/manage-email-flow) to a user's email address to verify their account. By default, Auth0 automatically sends verification emails for any [Database Connection](/docs/authenticate/database-connections/password-change) identity created as part of [self sign-up](/docs/get-started/architecture-scenarios/business-to-consumer/provisioning#self-sign-up). However, Auth0 also provides a [Management API endpoint](https://auth0.com/docs/api/v2#!/Tickets/post_email_verification) that you can use to send verification emails in cases where email address validation is not performed by a Social Provider upon user registration.

## Blocking users

[Blocking user access](/docs/manage-users/user-accounts/block-and-unblock-users) in Auth0 provides a way to prevent user login to applications under certain conditions. By default, the Auth0 Dashboard provides an out-of-the-box mechanism to give administrators the ability to both block and unblock user access to all applications, and you can implement this functionality via use of the [Auth0 Management API](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id). You can also use Auth0 extensibility to [disable user access to certain applications](/docs/manage-users/user-accounts/manage-user-access-to-applications) as well as provide more fine-grained [access control](/docs/get-started/architecture-scenarios/business-to-consumer/authorization).

In addition, the Auth0 Management API provides you with the ability to [unblock](https://auth0.com/docs/api/management/v2#!/User_Blocks/delete_user_blocks_by_id) users disabled due to excessive use of incorrect credentials.

## Linking user accounts

By default, there is one user profile (user account) for each user identity. If you enable login from multiple identity providers - via Facebook or Google [social authentication](/docs/get-started/architecture-scenarios/business-to-consumer/authentication#social-authentication) as well as via Auth0 [username and password authentication](/docs/get-started/architecture-scenarios/business-to-consumer/authentication#username-and-password-authentication) - then each will have a separate user profile. You can use Auth0’s functionality for [linking user accounts](/docs/manage-users/user-accounts/user-account-linking) to create one profile for a user as an aggregate of all their associated identities.

The process of linking accounts merges user profiles in pairs: a primary account and a secondary account must be specified in the linking process. The number of accounts that can be linked, however, extends beyond a single pair. For example, you can use an account which already has multiple accounts merged with it as the primary, and link an additional secondary account to it. This means that one user account can have multiple identities associated with it, which provides a number of advantages:

* Users can log in using multiple identities without creating a separate profile for each one.
* Registered users can use new login identities, but continue using their existing profile.
* Users can carry their profile around, irrespective of which identity they use for login.
* Users can link to an account with more identity information in order to provide a more complete profile.
* Your applications can retrieve connection-specific user profile data.

## De-provisioning

Your application may need to support a user’s request to remove their account (for example, you might need to meet [GDPR](https://eugdpr.org/) requirements). You can implement such a feature, along with a number of other profile-related functions, using the [Management API](https://auth0.com/docs/api/management/v2#!/Users). The Management API allows you to retrieve information stored about a user and update it as required.

Auth0 is capable of supporting various privacy-related requirements including the display of links to consent notices on signup and data protection to support the rights of users to view and correct data you’ve collected about them.

<Callout icon="file-lines">
  [GDPR](https://eugdpr.org/) and other privacy directives require that users have the right to view and correct data held about them. They also have the right to be “forgotten.” You can use the Management API to address these requirements and meet your legislative obligations.
</Callout>

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2C IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/3er1aEQ7Ul0q3c9leJWczR/b1f18b4c16abb7e78b01e4eb2b52bb8e/B2C_Project_Planning.pdf)


# Provisioning (B2C)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-consumer/provisioning

User provisioning functionality and considerations for your B2C IAM implementation.

Determining how users get signed up is important to address early, and the decisions you make here will influence many of the decisions you will need to make going forward. We’ve found there are a typical set of patterns for how users will get added to your system, and things to take note of when considering workflow design too.

<Callout icon="file-lines">
  While Auth0 supports numerous workflows, web based workflows using Auth0 [Universal Login](/docs/authenticate/login/auth0-universal-login) for sign up are considered both industry and Auth0 best practice as they provide for optimal functionality and the best security.
</Callout>

Auth0 supports user sign up via a number of different [identity providers](/docs/authenticate/identity-providers). During sign up, Auth0 provisions the user profile so that it contains the user’s account information. There are a number of things to consider when looking at functionality and workflow:

* Should you use Auth0 as an identity store?
* Can you use your own (legacy) identity store with Auth0?
* How do you migrate user identities from your identity store to Auth0?
* Can your users sign up using their existing social accounts such as Google and Facebook?

Auth0 provides out-of-the-box identity storage that can be leveraged to store user credentials safely and securely. See [Self Sign Up](#self-sign-up) for more information. If you already have a legacy identity store and you want to offload the management of it, then the [User Migration](#user-migration) capabilities provide you with a number of options to do so.

Alternatively, if you have to maintain your legacy identity store - perhaps because you’ve got applications which you aren’t ready to migrate or which can’t be migrated - then you can use the [identity store proxy](#identity-store-proxy) capability. Allowing your customers to use “bring their own identity” is also an attractive proposition and though we find our customers don’t initially do so, you can use the [Social Sign Up](#social-sign-up) capability to provide it.

## User migration

In addition to hosting the [User Profile](/docs/get-started/architecture-scenarios/business-to-consumer/profile-management), Auth0 also has the capability to both [proxy](#identity-store-proxy) your own legacy identity store and provide a secure Auth0 hosted replacement. Both of these capabilities are supported via the use of Auth0 [Database Connections](/docs/authenticate/database-connections). If you decide to use Auth0 as a replacement for your legacy identity store then you can [migrate users](/docs/manage-users/user-migration) either all at once with bulk migration, or progressively with automatic migration.

<Callout icon="file-lines">
  Customers often opt for a two-stage approach to user migration, using Automatic Migration first to migrate as many users as possible, then using Bulk Migration for the users that remain. See [User Migration Scenarios](/docs/manage-users/user-migration/user-migration-scenarios) for more information.
</Callout>

Automatic Migration is preferred as it allows users to be migrated individually and also allows them to retain their existing password in almost all situations. For Bulk Migration, we recommend using the [Management API](https://auth0.com/docs/api/management/v2#!/Jobs/post_users_imports) over the [User Import/Export extension](/docs/manage-users/user-migration/user-import-export-extension) in all but the most simple cases, as the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> provides for greater flexibility and control.

With Bulk Migration users typically need to **reset their password once migration is complete**, unless passwords are stored hashed in your legacy identity store using bcrypt (or you can generate them in bcrypt form). In this case, you may be able to use bulk migration and **preserve user passwords** as part of the process, depending on the bcrypt algorithm and the number of salt rounds used. See [Bulk Import Database Schema Examples](/docs/manage-users/user-migration/bulk-user-import-schema) for more information.

<Callout icon="file-lines">
  Calls to the Management API are subject to [Auth0 Rate Limiting policy](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy). You must take this into consideration, and to assist, Auth0 generally recommends use of the appropriate [Auth0 SDK](/docs/libraries) for your development environment rather than calling our APIs directly.
</Callout>

### Identity store proxy

Auth0 Database Connection types can also be configured to proxy an existing (legacy) identity store. If you need to keep user identities defined in your own legacy store - for example, if you have one or more business critical applications that you can’t migrate to Auth0, but which still need access to these identities - then you can easily integrate with Auth0. See [Authenticate Users Using Your Database](/docs/authenticate/database-connections/custom-db) for more information.

## Self sign up

Self sign up leverages Auth0 [Database Connections](/docs/authenticate/database-connections) to store the user ID, password, and (optional) username identity information collected from new users during the sign up process. Database connection policies governing things such as minimum [username length](/docs/authenticate/database-connections/require-username) or [password strength and complexity](/docs/authenticate/database-connections/password-options) can be configured via the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

<Callout icon="file-lines">
  Auth0 [Universal Login](/docs/authenticate/login/auth0-universal-login) as well Auth0 widgets such as [Lock](https://auth0.com/lock) integrate with Database Connections to provide comprehensive user interface functionality for sign up out-of-the-box. These UI artifacts are fully reactive, and with feature rich configuration and comprehensive customization, you can deploy functionality for user self sign up as well as login.
</Callout>

## Social sign up

Social signup is synonymous with sign in via [social authentication](/docs/get-started/architecture-scenarios/business-to-consumer/authentication) - there’s no distinction here \*per se\*, as user [profile](/docs/get-started/architecture-scenarios/business-to-consumer/profile-management) creation happens automatically upon first social login.

## Project planning guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2C IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/3er1aEQ7Ul0q3c9leJWczR/b1f18b4c16abb7e78b01e4eb2b52bb8e/B2C_Project_Planning.pdf)


# Quality Assurance (B2C)
Source: https://auth0.com/docs/get-started/architecture-scenarios/business-to-consumer/quality-assurance

Quality Assurance considerations for your B2C IAM implementation.

Quality Assurance is important in identifying issues before they impact your customers and, depending on the nature of your project, there are several different types of quality assurance testing that you’re going to want to consider as part of your integration with Auth0:

* Is your application easy to understand and use, even by those with a disability?
* Does your application need to work across various different browsers and devices?
* Does your application need to work in multinational and/or international environments?
* How will your application perform when subjected to unexpected production loads?
* How can you ensure your application is safe from security-related vulnerabilities?

Auth0 [Universal Login](/docs/authenticate/login/auth0-universal-login) and associated UI widgets (such as [Lock](/docs/libraries/lock)) have already been designed and built following usability and accessibility best practices, and provide tested out-of-box support for a whole host of [browsers and devices](/docs/troubleshoot/customer-support/product-support-matrix). Support for [internationalization](/docs/customize/internationalization-and-localization) (I18N) is also provided out-of-box, with built-in extensibility designed for custom multi-language and localization (L10N) situations.

To ensure functional requirements are met and unexpected events are handled correctly, guidance is provided for testing the [integration](#integration-testing) between your application(s) and Auth0, and for [unit testing](#unit-testing) individual extensibility modules (such as [Rules](/docs/customize/rules/debug-rules), [Hooks](/docs/customize/hooks/update-hooks), and Custom Database scripts). Guidance is also provided regarding Auth0's [penetration testing policy](/docs/troubleshoot/customer-support/operational-policies/penetration-testing-policy) to help when testing for security vulnerability, and also how [Mock](#mock-testing) testing can be leveraged in conjunction with our [load testing policy](/docs/troubleshoot/customer-support/operational-policies/load-testing-policy) to help ensure your application(s) perform under unexpected load.

## Unit testing

The objective of unit testing is to test individual units of code. If you create custom code within Auth0 in the form of Rules, Hooks, and/or Custom DB scripts, you should consider use a testing framework (such as [Mocha](https://mochajs.org/)) to test your code. Companies who have been most successful with Auth0 have found it useful to execute these unit tests prior to [automatically deploying](/docs/get-started/architecture-scenarios/business-to-consumer/deployment) Auth0 tenant configuration and collateral.

## Integration testing

It is a recommended best practice that you set up different tenants for development, testing, and production as discussed in Architecture guidance for [SDLC support](/docs/get-started/architecture-scenarios/business-to-consumer/architecture#sdlc-support). Auth0 allows you to configure variables that are available from within custom [extensibility](/docs/customize/extensions); these can be thought of as environment variables for your Auth0 tenant. Rather than hard code references that change when moving code between development, test, and production environments, you can use a variable name that is configured in the tenant and referenced by the custom extensibility code. This makes it easier for the same custom code to function, without changes, in different tenants as the code can reference variables which will be populated with tenant-specific values at execution time:

* For use of variables in Rules, see how to [configure values](/docs/customize/rules/configuration)
* For use of variables in Hooks, see how to configure [secrets](/docs/customize/hooks/hook-secrets) in the editor
* For use of variables in Actions, see Explore Flows and Triggers
* For use of variables in Custom DB Scripts, see the [configuration parameters](/docs/authenticate/database-connections/custom-db/create-db-connection#step-3-add-configuration-parameters)

<Info>
  ### Best Practice

  It’s a recommended best practice to use variables to contain tenant-specific values as well as any sensitive secrets that should not be exposed in your custom code. If your custom code is deployed in GitHub, then using a tenant-specific variable avoids exposure of sensitive values via your GitHub repository.
</Info>

### Test automation

You can automate your overall build process by incorporating deployment automation as well as test automation. This can be used to deploy new versions of configuration and/or custom code to Auth0 and execute automated tests. If the tests uncover any failures, the deployment automation capabilities can be used to revert to the last working version. For further information, see the [deployment automation guidance](/docs/get-started/architecture-scenarios/business-to-consumer/deployment) provided.

## Mock testing

In a balance between Auth0’s [load testing policy](/docs/troubleshoot/customer-support/operational-policies/load-testing-policy) and the desire to load test, it is common practice among Auth0’s customers to mock out Auth0’s endpoints. This is a valuable practice in order to ensure that your application works with your expected interfaces without having to restrict your testing, and tools such as [MockServer](http://www.mock-server.com/), [JSON Server](https://github.com/typicode/json-server) or even [Postman](https://learning.getpostman.com/docs/postman/mock_servers/setting_up_mock/) can be used to assist.

## Project Planning Guide

We provide planning guidance in PDF format that you can download and refer to for details about our recommended strategies.

[B2C IAM Project Planning Guide](https://assets.ctfassets.net/cdy7uua7fh8z/3er1aEQ7Ul0q3c9leJWczR/b1f18b4c16abb7e78b01e4eb2b52bb8e/B2C_Project_Planning.pdf)


# Multiple Organization Architecture
Source: https://auth0.com/docs/get-started/architecture-scenarios/multiple-organization-architecture

An integration guide to multi-tenant architectures that must accommodate application instances for multiple Auth0 Organizations.

There are multiple use cases where users belong to third-party organizations that have signed up for the services you provide. These users may be employees of a third-party organization, customers, or a combination of both. Whatever the situation, this guide will provide you with a high-level overview of common use cases for multi-tenant applications.

B2B applications strive to create a pleasant user experience for the employees and customers of the businesses they serve. To accomplish this, service providers in B2B environments often allow branding to be added to their service for each of the organizations that use it. For example, let’s say you work for AwesomeSaaS (an SaaS software company), and your company uses Human0, an HR application for managing benefits and other HR functions. You access your HR app, and when you log in, the login experience is customized to display the AwesomeSaaS logo and use AwesomeSaaS colors.

As a B2B service provider designing an integration with Auth0, you will need to consider whether or not your customers (i.e., third-party organizations) will allow users from other organizations to log in to their instance of the application, and whether those users should be shared between organizations or isolated to a single organization.

Let’s start by introducing a couple of example applications that will highlight the various use cases. Travel0 is a fictitious company that offers online travel agency services. Travel0 has several applications, but for the purpose of this exercise, we’ll focus on two applications that are marketed directly to organizations:

* **Travel0 Corporate Booking**: Provides organizations with an online application where their employees can log in to and book work-related travel. Organizations that are customers of this application include:

  * **Hoekstra & Associates**: A small law office with just a few employees. They do not have an IT department and don’t have the time or capacity to learn how to set up a corporate Identity Provider (IdP).
  * **Gupta & Smith Law**: A larger law office, but they also do not have an IT department and don’t have the time or capacity to learn how to set up a corporate IdP.
  * **MetaHexa Bank**: A large finance organization. They provide banking and insurance services and have their own IdP.
  * **Many Student University (MSU)**: A large university with several campuses, where each campus has its own IdP.
* **Travel0 Adventure Management**: Allows organizations to create and market adventures such as whitewater rafting. Guides (who are freelance, or employees of some third-party travel/event organization) can use this application to create an account and handle scheduling to lead adventures. Organizations that are customers of this application include:

  * **AdventureZ**: A large tour/event organizer. They have their own IdP that they use for their employees. They rarely need freelancers because they have enough guides on staff, some of whom only work during busy times. They also facilitate their guides’ ability to do freelance work for other companies.
  * **Rocky Mountain High Adventures**: A new group entering the market for the first time. The cofounders run tours; they reach out to freelancers for help during busy times.
  * **Suzie’s Rafting and Ziplines**: This company has been around for a long time. They have a staff of guides that handle most of their events, but they also hire freelancers when busy.

## Terminology

Many of the words used in the provided guidance can mean a number of different things. Take a moment to read through each definition so it’s clear when reading through the examples who is fulfilling what role:

* **Auth0 Tenant** (otherwise known as **<Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip>**)**:** Tenant that you create in Auth0. It is an instance of an Authorization Server and represents one or more user domains.
* **Auth0 Organizations:** Refers to the Auth0 Tenant feature designed to support organizations. An instance of an [Auth0 Organization](/docs/manage-users/organizations/organizations-overview) will typically refer to a specific customer of yours.
* **Employee**: Person who works for your company. They will typically have an account in your <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> (IdP) and may need admin access to one or more Organization Tenant instances. We will only use the term Employee to refer to Employees of your company. For users who belong to your customers' Organizations, see **Organization User**.
* **Identity Provider (IdP)**: Service, such as Auth0, that manages authentication of users, and optionally, provides user profile information and/or credentials management. The service may also provide delegation of credential validation and profile management via the use of a third-party IdP (such as Azure AD, Google, Facebook, etc.)
* **Organization:** Third-party company that is one of you customers. You may refer to an organization instance that is created for your application as a tenant; we will refer to it as an **Organization Tenant** to avoid confusing it with an Auth0 Tenant.
* **Organization Tenant:** Refers to a tenant that has been created for your customer as part of your application subscription/provision. This is different from an Auth0 Tenant.
* **Organization User**: Person who is logging in to the application as a member of an Organization. This may be an employee (of the Organization) or a customer. Any user referenced in an organization context can be considered an Organization User.

## User Isolation

It's important to determine the type of application you provide when it comes to organizational user isolation. There are two fundamental approaches to how and where each of these users are stored: [users isolated by organization](#users-isolated-by-organization) and [users shared between organizations](#users-shared-between-organizations).

<Frame>
  <img alt="Architecture Scenarios - Multitenancy - Diagram - Multiple organizations shared decision" />
</Frame>

The flow diagram above outlines the decision-making process. You should also consider whether [administrative-type access](#administrative-access-to-organizations) is required for an organization instance. This may be for an employee of your organization who acts as an administrator for one or more organizations, or for some other third party that provides help desk services or similar.

The following sections provide detail for each approach to organizational user isolation. Pay close attention to the atypical scenarios associated with each (i.e., where users need access to more than one organization) because these types of use cases often determine which approach more closely aligns with your requirements.

### Users isolated by Organization

Each organization has its own set of users, and users cannot and should not be able to access other organizations. If they attempt to do so, they should be rejected as unauthorized. If desired, you can force your users to create a separate account for each organization they belong to. As a person, they would be considered to be two or more different users.

In this scenario, a user is tied directly to the organization to which they belong or have access. Users have two options for how they log in: A) they create credentials in identity storage provisioned for the appropriate organization (i.e., UserID/Password Database Connection in your Auth0 Tenant), or B) they log in using their own organization’s IdP. In this use case, it would not make sense for a user to be part of multiple organizations, and the better practice would be to create a separate identity for each organization. Using Travel0 Corporate Booking as an example, the diagram below shows how this would look:

<Frame>
  <img alt="Architecture Scenarios - Multitenancy - Diagram - Isolated users" />
</Frame>

Sally is a typical user: she is an employee of MetaHexa Bank, and she can only access MetaHexa Bank’s instance of Travel0 Corporate Booking.

Pat, on the other hand, is an atypical user. Pat is a freelance paralegal, so she works for both Hoekstra & Associates and Gupta & Smith Law; she will access the Travel0 Corporate Booking instance for each using a separate user identity. One of many advantages for this approach is to limit the possibility of errors by forcing Pat to create two separate personas--one for each law firm. When Pat books travel, she must log in separately to the specific organization instance in order to make the booking.

Pat's situation is likely a rare use case. However, she illustrates what needs to be considered when determining user isolating requirements. If you want to isolate users to the organization with which they’re associated, this requires the creation of separate user identities. In this case, there is one identity for Pat when accessing the Hoekstra & Associates instance of Travel0 Corporate Booking, and a separate one for accessing Gupta & Smith Law’s instance of Travel0 Corporate Booking.

#### Use cases when isolating by organization

Applications that have users isolated per organization typically support three different use cases. For the examples in this section, we'll use the Travel0 Corporate Booking application scenarios described in our introduction. Travel0 is the Auth0 customer.

* **Organizations that either don’t have their own IdP or don’t know how to use it**. These tend to be smaller organizations that don’t have an IT department available to configure <Tooltip href="/docs/glossary?term=Single+Sign-On">Single Sign-On</Tooltip> (SSO) with the organization’s Identity Provider (IdP), or else don’t have an organization IdP fit for the task. In our Travel0 Corporate Booking example, Hoekstra & Associates is such an organization.
* **Organizations that prefer to configure their own IdP** so that their employees don’t have to create a new set of credentials for your application. Most organizations fall into this category. In our Travel0 Corporate Booking example, MetaHexa Bank is such an organization.
* **Organizations that require multiple authentication options**. Examples of this type of organization include those that frequently acquire new companies, organizations like schools that allow staff and parents to log in to the same application, and organizations that invite partners or customers to log in to their application instance (i.e., B2B2C organizations). In our examples, Many Student University (MSU) would be such an organization.

For the first two types of organizations, the solution tends to be fairly straightforward. These organizations are considered Single IdP organizations, and the approach is almost always the same. To learn more, read [Single Identity Provider Organizations](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations).

Organizations that have more than one IdP for the organization trend toward a higher order of intricacy, but there are a few approaches that can minimize complexity. To learn more, read [Multiple Identity Provider Organizations](/docs/get-started/architecture-scenarios/multiple-organization-architecture/multiple-idp-orgs).

### Users shared between Organizations

A user may belong to more than one organization, and it would be convenient if that user did not have to have a separate identity/account as they navigate from one organization to another. Organizations can still use their own IdP in such cases.

<Frame>
  <img alt="Architecture Scenarios - Multitenancy - Diagram - Shared users" />
</Frame>

In this scenario, a user is no longer tied directly to the organization to which they belong or have access. Users now have two options for how they log in: A) they create credentials in identity storage provisioned generally (i.e., in a single UserID/Password Database Connection in your Auth0 Tenant), rather than in any identity store specifically allocated in your Auth0 Tenant for the organization, or B) they log in using their own organization’s IdP. Once a user has an identity, they are then given permission to access each of the organizations to which they should have access. This could mean access to just one organization, or it may mean they have access to more than one organization. Users will need to understand that when prompted to log in, they can use the same credentials to access each organization’s instance. Using Travel0 Adventure Management as an example, the diagram above shows how this would look.

Jonno is a typical user. Jonno is an employee of Suzie’s Rafting and Ziplines. Jonno is only able to log in to the instance of Travel0 Adventure Management provisioned to create and guide adventures for Suzie’s Rafting and Ziplines. Jonno’s credentials are either stored in a Database Connection associated with Travel0’s Auth0 Tenant or in Suzie’s Zipline and Rafting’s IdP (depending on whether they want to manage their user identities or not).

Sumana is an atypical user. Sumana is an employee of AdventureZ, but as AdventureZ also coordinates freelance opportunities for the smaller guide companies during high peak times, Sumana has been invited to join Rocky Mountain High Adventures as a freelancer. Sumana is authorized to log in to both AdventureZ and Rocky Mountain’s instances of Travel0 Adventure Management. However, because she has never been invited as a guide to Suzie’s Rafting and Ziplines, she is not authorized to access that instance.

Sumana needs to have the same identity for both organizations because guiding involves the use of a rating system, and Sumana’s ratings need to carry over and be combined between the organizations with which she works. Sumana’s credentials, like Jonno’s, are either stored in a Database Connection associated with Travel0’s Auth0 Tenant, or in AdventureZ’s IdP (depending on whether AdventureZ wants to manage user identities or not). Where her credentials are stored has no bearing on the organization instances to which she has access.

### Administrative access to Organizations

There are scenarios where you will need to provide administrative access across your organizations. Typically, this will be for administrative tasks outside of user Profile/Account management (as described in [Profile Management](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/profile-management)), and you may need to provide access to your employees as well as to third parties.

<Callout icon="file-lines">
  **Best Practice**

  Always enable Multi-factor Authentication (MFA) for Auth0 Tenant administrators who are provided access via the Auth0 Dashboard. Note that you must follow a different process to enable MFA for an Auth0 Tenant administrator than you do to enable MFA for the Auth0 Tenant itself. To learn how to enable MFA for an Auth0 Tenant Administrator, see [Manage Dashboard Access with Multi-factor Authentication](/docs/get-started/manage-dashboard-access/add-change-remove-mfa).
</Callout>

The <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> can be configured via [role-based access control](/docs/get-started/manage-dashboard-access/feature-access-by-role), which will allow you to define specific roles for your employees across your Auth0 Tenant deployment as a whole. You can even leverage your own corporate IdP to provide Auth0 Tenant Administrator authentication for your employees, as well as extended Tenant Administrator access to trusted third-parties.

For other administrative access, you will typically want to build your own API and/or application, which you will use in conjunction with the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. Providing administrative access to your Auth0 Tenant via the Auth0 Dashboard for a wide range of users is not recommended. While building such an application/API is beyond the scope of this document, it’s recommended that you seek help from [Auth0 Professional Services](/docs/get-started/professional-services) before embarking on such an endeavor.

## Learn more

* [Single Identity Provider Organizations](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations)
* [Multiple Identity Provider Organizations](/docs/get-started/architecture-scenarios/multiple-organization-architecture/multiple-idp-orgs)


# Multiple Identity Provider Organizations
Source: https://auth0.com/docs/get-started/architecture-scenarios/multiple-organization-architecture/multiple-idp-orgs

Learn about multiple Identity Provider (IdP) Organizations, in which every Auth0 Organization has more than one Auth0 connection.

In the Multiple <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> (IdP) Organizations scenario, every organization that uses the [Auth0 Organizations](/docs/manage-users/organizations/organizations-overview) feature uses more than one [Auth0 Connection](/docs/authenticate/identity-providers). In many ways, the implementation for this scenario is identical to the implementation for [Single Identity Provider Organizations. I](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations)n fact, the Auth0 Organizations feature supports mix and match, as well as easy transition between the two. However, you should consider a few additional items.

## Connections

In addition to the information that typically is included as part of [Authorization](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/authorization), you can add details regarding the specific [Auth0 Connection](/docs/authenticate/identity-providers) via which first-factor authentication for the user was performed. While not explicitly required, you can add such information to an <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip> and/or <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> as a custom claim in order to provide your application and/or API with additional context that can be used with access control.

As illustrated in the following example, custom claims are typically added via Rule extensibility, which can access Connection specifics via use of the [`context`](/docs/customize/rules/context-object) object:

```js lines theme={null}
context.idToken['http://travel0.net/connection'] = context.connection;     // Connection name claim
context.accessToken['http://travel0.net/connection'] = context.connection; // Connection name claim
```

<Callout icon="file-lines">
  The Rules context object provides access to various aspects of the connection used to first-factor authenticate a user, including the `connection` name, `connectionID`, and `connectionStrategy`. This also provides Rule extensibility with additional information that can be used as part of any [centralized policy enforcement](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/authorization).
</Callout>

### Database Connection

While Auth0 allows you to [provision](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/provisioning) multiple [Database and Custom Database Connections](/docs/authenticate/database-connections), we do not recommend that you associate more than one of these types of connection with an Auth0 Organization. Because Database and Custom Database Connections do not currently support Home Realm Discovery, which is a key component of [Identifier-First Authentication](/docs/authenticate/login/auth0-universal-login/identifier-first), the <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> New Experience cannot select between them if more than one is defined.

<Callout icon="file-lines">
  **Best Practice**

  If you are defining a custom database connection for use with an Auth0 Organization, then make sure that one, and only one, custom database connection is associated with that Auth0 Organization at any given time.
</Callout>

### Enterprise Connection

If your enterprise application uses [Enterprise Federation](/docs/authenticate/enterprise-connections), you can activate [Identifier First Authentication with Home Realm Discovery](/docs/authenticate/login/auth0-universal-login/identifier-first) in its Authentication Profile. Once enabled, Home Realm Discovery detects email addresses from a known domain and automatically sends them to the proper Workforce login.

To learn more, read [Identifier First Authentication](/docs/manage-users/organizations/login-flows-for-organizations#identifier-first-authentication) in [Login Flows for Organizations](/docs/manage-users/organizations/login-flows-for-organizations).

### Social Connection

Other than the considerations described in the [Authentication](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/authentication) section, no additional concerns need to be addressed when Social Connections are used as part of a multiple IdP organization scenario.


# Single Identity Provider Organizations
Source: https://auth0.com/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations

Learn about Single Identity Provider(IdP) Organizations, in which every Auth0 Organization has exactly one Auth0 connection.

In the Single <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> (IdP) Organizations scenario, every organization that uses the [Auth0 Organizations](/docs/manage-users/organizations/organizations-overview) feature uses exactly one Auth0 connection. This feature allows each application to select the appropriate organization defined on the Auth0 Tenant, which will either authenticate user credentials directly or forward the authentication request to the appropriate IdP to handle.

In this scenario, we’ll continue to use the [Travel0 Corporate Booking](/docs/get-started/architecture-scenarios/multiple-organization-architecture) example. In this example, the corporate booking application equates to your application and Travel0 corresponds to your company.

<Frame>
  <img alt="Architecture Scenarios - Multitenancy - Diagram - Isolated users, Shared Apps, Orgs A&B" />
</Frame>

<Warning>
  The Auth0 Organizations feature currently supports applications that use the [SAML](/docs/authenticate/protocols/saml/saml-configuration), [Open ID Connect](/docs/authenticate/protocols/openid-connect-protocol) protocols and/or the [OAuth 2](/docs/authenticate/protocols/oauth) framework. Applications that require [WS-Fed](/docs/authenticate/protocols/ws-fed-protocol) are not supported.
</Warning>

Regardless of how credentials are processed--whether user credentials are stored in a database connection (like with Hoekstra & Associates) or are validated via an enterprise connection (like with MetaHexa Bank) or a social connection--your application behaves the same way. Leveraging the [Organizations](/docs/manage-users/organizations/organizations-overview) feature allows you to configure and control the experience.

## Learn more

* [Single Identity Provider: Provisioning](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/provisioning)
* [Single Identity Provider: Branding](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/branding)
* [Single Identity Provider: Authentication](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/authentication)
* [Single Identity Provider: Authorization](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/authorization)
* [Single Identity Provider: Profile Management](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/profile-management)
* [Single Identity Provider: Logout](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/logout)


# Single Identity Provider: Authentication
Source: https://auth0.com/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/authentication

Learn about authentication users through Organizations for multi-tenant architectures.

In our architecture scenarios, we provide general purpose guidance on [B2B Authentication](/docs/get-started/architecture-scenarios/business-to-business/authentication), including the use of the [Universal Login](/docs/authenticate/login/auth0-universal-login) as a recommended best practice, which we recommend reviewing alongside the guidance provided here.

<Callout icon="file-lines">
  **Best Practice**

  While numerous authentication workflows are supported within Auth0, workflows using Auth0 Universal Login are considered both industry and Auth0 best practice because they provide [optimal functionality and security](/docs/authenticate/login/universal-vs-embedded-login). In particular, Universal Login provides [Single Sign On (SSO) out of the box](https://auth0.com/learn/how-to-implement-single-sign-on/) and helps mitigate attacks such as [phishing](https://auth0.com/blog/all-you-need-to-know-about-the-google-docs-phishing-attack/) and [bucket brigade](/docs/secure/security-guidance/prevent-threats); for this reason, it should be preferred wherever password credentials are supplied by a user. Crucially, the [New Universal Login Experience](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience) is also the only mechanism supported when using the Auth0 Organizations feature.
</Callout>

Authenticating users requires the processing of first-factor credentials. Whether this is performed by Auth0 or by some third-party <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> (IdP), when you use the Auth0 Organizations feature, you must also use Auth0 [Universal Login Experience](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience) capability.

<Callout icon="file-lines">
  Auth0 supports only one authenticated user context per Auth0 Tenant; tenants cannot selectively switch between authenticated user contexts. Changing user context has an impact on any active SSO session, and this extends to the Auth0 Organizations feature. If per-organization contexts are absolutely necessary, then multiple Auth0 Tenants will need to be deployed to production. Because using multiple tenants has ramifications that affect Single Sign-On (SSO), user profile management, and so on, you should carefully consider before going down this route.
</Callout>

## Database Connection

Using our Hoekstra & Associates example, let's see how this Authentication implementation might flow with a user authenticated via an Auth0 Database Connection; most of the workflow described will typically be handled by using the relevant Auth0 SDK or library associated with your technology stack:

<Frame>
  <img alt="Architecture Scenarios - MOA - Isolated Users, Shared Apps, Database Login Flow" />
</Frame>

1. Jennifer from Hoekstra & Associates opens her browser and navigates to Hoekstra & Associates' instance of Travel0 Corporate Booking.

   1. If Jennifer already has a session cookie with Hoekstra & Associates' instance of Travel0 Corporate Booking, then she will typically be logged in to the system, and we will exit here. For more information, see [Single Sign-On](/docs/authenticate/single-sign-on).
2. Hoekstra & Associates' instance of Travel0 Corporate Booking redirects to the Travel0 Auth0 Tenant using [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow) (with or without [PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce)) by calling the `/authorize` endpoint and passing parameters, typically via use of an [Auth0 SDK](/docs/libraries) or third-party library:

   1. `redirect_uri`: [`https://hoekstra.corp.travel0.net/login/callback`](https://hoekstra.corp.travel0.net/login/callback)
   2. `response_type`: `code`
   3. `state`: Unique [state](/docs/secure/attack-protection/state-parameters) generated in this session
   4. `scope`: `openid profile` ...
   5. any necessary additional [OIDC Scopes](/docs/get-started/apis/scopes/openid-connect-scopes), depending on the information required about the user.
   6. `client_id`: Client ID associated with the Application created in the Travel0 Auth0 Tenant for Hoekstra & Associates' instance of Travel0 Corporate Booking.
   7. `organization`: Auth0 Organization to use. Where the organization is known ahead of time, a request to `/authorize` can include this parameter, which is specified in the form `organization=`organization\_id, where organization\_id is set to the identifier associated with the corresponding Auth0 Organization definition in your Auth0 Tenant. Alternatively, you can omit the `organization` parameter from the call to `/authorize` and configure your Auth0 Tenant to prompt the user to select the appropriate organization as part of first-factor authentication. For more information, see [Define Organization Behavior](/docs/manage-users/organizations/configure-organizations/define-organization-behavior).

      <Warning>
        If the `organization` parameter is included on a call to the `/authorize` endpoint, then this should be used consistently for the duration of any session with Auth0. The Organizations feature does not associate any selected organization with the Auth0 SSO session, so omitting the parameter will always prompt the user to select the desire organization.
      </Warning>
3. The Travel0 Auth0 Tenant redirects to `/login` to collect credentials from the user. If Jennifer already has a Database session with Hoekstra & Associates, then steps 3a and 4 will be skipped. For more information, see [Single Sign-On](/docs/authenticate/single-sign-on).

   1. The Universal Login Page, which you can configure to include organization-specific brand collateral as described in [Branding](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/branding), is displayed.
4. The user enters their credentials and clicks `login`.
5. The Travel0 Auth0 Tenant checks the credentials for the user; if valid, the [Rules](/docs/customize/rules) pipeline executes. Rules can be used to handle access control as described in [Authorization](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/authorization). If credentials for the user are invalid, then the user will be prompted to re-enter them.

   <Callout icon="file-lines">
     Automatic membership assignment will be performed if this option has been specified. For more information, see [Grant Just-In-Time Membership to an Organization Connection](/docs/manage-users/organizations/configure-organizations/grant-just-in-time-membership). For [manually-assigned Membership](/docs/manage-users/organizations/configure-organizations/assign-members), validation will fail if the user is not already assigned as a member of the Organization.
   </Callout>
6. Upon successful first-factor authentication and Rules execution, the user is redirected to the `redirect_uri` ([`https://hoekstra.corp.travel0.net/login/callback`](https://hoekstra.corp.travel0.net/login/callback)) with the `state` passed in step 2, as well as a `code`.
7. Hoekstra & Associates' instance of Travel0 Corporate Booking validates the `state` and then calls the Travel0 Auth0 Tenant at [`https://auth.travel0.net/oauth/token`](https://auth.travel0.net/oauth/token), passing the `code` and its `client id` and `client secret` in exchange for the [ID Token](/docs/secure/tokens/id-tokens). The ID Token is then used to generate a session for [`https://hoekstra.corp.travel0.net`](https://hoekstra.corp.travel0.net).
8. Hoekstra & Associates' instance of Travel0 Corporate Booking instance displays the appropriate page to the user.

## Enterprise Connection

Authenticating via an Enterprise Connection follows a very similar process. Using our MetaHexa Bank example, let's see how this Authentication implementation might flow with a user authenticated via the Enterprise Connection to MetaHexa Bank; again, most of the workflow described will typically be handled by using the relevant Auth0 SDK or library associated with your technology stack

<Frame>
  <img alt="Architecture Scenarios - MOA - Isolated Users, Shared Apps, Enterprise Login Flow" />
</Frame>

1. Amintha from MetaHexa Bank opens her browser and navigates to MetaHexa Bank's instance of Travel0 Corporate Booking.

   1. If Amintha already has a session cookie with MetaHexa Bank's instance of Travel0 Corporate Booking, then she will typically be logged in to the system, and we will exit here. For more information, see [Single Sign-On](/docs/authenticate/single-sign-on).
2. MetaHexa Bank's instance of Travel0 Corporate Booking redirects to the Travel0 Auth0 Tenant using [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow) (with or without [PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce)) by calling the `/authorize` endpoint and passing parameters, typically via use of an [Auth0 SDK](/docs/libraries) or third-party library:

   1. `redirect_uri`: [`https://metahexa.corp.travel0.net/login/callback`](https://metahexa.corp.travel0.net/login/callback)
   2. `response_type`: `code`
   3. `state`: Unique [state](/docs/secure/attack-protection/state-parameters) generated in this session
   4. `scope`: `openid profile` ...
   5. any necessary additional [OIDC Scopes](/docs/get-started/apis/scopes/openid-connect-scopes), depending on the information required about the user.
   6. `client_id`: Client ID associated with the Application created in the Travel0 Auth0 Tenant for MetaHexa Bank's instance of Travel0 Corporate Booking.
   7. `organization`: Auth0 Organization to use. Where the organization is known ahead of time, a request to `/authorize` can include this parameter, which is specified in the form `organization=`organization\_id, where organization\_id is set to the identifier associated with the corresponding Auth0 Organization definition in your Auth0 Tenant. Alternatively, you can omit the `organization` parameter from the call to `/authorize` and configure your Auth0 Tenant to prompt the user to select the appropriate organization as part of first-factor authentication. For more information, see [Define Organization Behavior](/docs/manage-users/organizations/configure-organizations/define-organization-behavior).

      <Warning>
        If the `organization` parameter is included on a call to the `/authorize` endpoint, then this should be used consistently for the duration of any session with Auth0. The Organizations feature does not associate any selected organization with the Auth0 SSO session, so omitting the parameter will always prompt the user to select the desire organization.
      </Warning>
   8. `connection`: Name of the configured Auth0 Enterprise Connection for MetaHexa Bank.

      <Callout icon="file-lines">
        **Best Practice**

        Always supply the `connection` parameter. When not provided, the user is prompted to select the Enterprise Connection associated with the upstream Identity Provider (IdP), which is an extra step from a UX perspective.
      </Callout>
3. The Travel Auth0 Tenant redirects to the MetaHexa IdP to authenticate first-factor credentials.

   1. The login page is displayed, and the user enters credentials. If Amintha already has a session with the MetaHexa IdP, then steps 3a and 4 will be skipped. For more information, see [Single Sign-On (SSO)](/docs/authenticate/single-sign-on).
4. The user enters their credentials and clicks `login`.
5. Upon successful first-factor authentication, the [Rules](/docs/customize/rules) pipeline executes. Rules can be used to handle access control as described in [Authorization](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/authorization). If credentials for the user are invalid, then the user will be prompted to re-enter them.

<Callout icon="file-lines">
  Automatic membership assignment will be performed if this option has been specified. For more information, see [Grant Just-In-Time Membership to an Organization Connection](/docs/manage-users/organizations/configure-organizations/grant-just-in-time-membership). For [manually-assigned Membership](/docs/manage-users/organizations/configure-organizations/assign-members), validation will fail if the user is not already assigned as a member of the Organization.
</Callout>

Steps 6 through 8 will match those described in the [Database Connection](#database-connection) scenario, but where Amintha is the user instead of Jennifer, and where MetaHexa Bank (`metahexa.corp.travel0.net`) will be used in place of Hoekstra & Associates.

## Social Connection

Authentication via Social Connection follows a similar pattern to that associated with an [Enterprise Connection](#enterprise-connection), but where the upstream IdP is associated with the social provider rather than any specific organization.

<Warning>
  Auth0 Social Connections are defined at the Tenant level. Typically, only one Social Connection is configured per social provider per Auth0 Tenant, which represents a definition to the Auth0 Tenant overall. Thus, any consent provided by a user will apply across all Auth0 Organizations defined in an Auth0 Tenant and not to any one organization in particular.
</Warning>

With Social Connections, user isolation cannot be modeled consistently on a per-organization basis. Although it may be tempting to model user isolation by creating multiple connections to a social provider, such as by using [Custom Social Connections](/docs/authenticate/identity-providers/social-identity-providers/oauth2), you should refrain from doing so; such a strategy can result in the same user ID being created in multiple connection definitions, which will invariably lead to problems down the line.


# Single Identity Provider: Authorization
Source: https://auth0.com/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/authorization

Learn about authorizing users for Organizations in multi-tenant architectures.

When thinking about authorization, you typically need to consider how you determine what a person is allowed to do and how you communicate this information to your applications and/or APIs. Depending on the applications you have, you may be affected by one or both of these. In our architecture scenarios, we provide general purpose guidance on [B2B Authorization](/docs/get-started/architecture-scenarios/business-to-business/authorization), which we recommend reviewing alongside the guidance provided here.

* [ID Tokens](/docs/secure/tokens/id-tokens) are often used to convey user authorization information to applications through custom claims, which can be added using [Rules](/docs/customize/rules) extensibility. Added claims can allow you to present a user interface in which users don’t have the ability to attempt something they are not permitted to do. Authorization information in an <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip> also provides any application backend with a way to restrict users from bypassing frontend controls for traditional web apps.

<Callout icon="file-lines">
  **Best Practice**

  You can leverage [Auth0 Role-Based Access Control](/docs/manage-users/access-control/rbac) (RBAC) via the [Auth0 Authorization Core](/docs/manage-users/access-control/configure-core-rbac) feature to define access permissions, which can be automatically applied to Access Tokens. For further details, see [Enable Role-Based Access Control for APIs](/docs/get-started/apis/enable-role-based-access-control-for-apis).

  Auth0 RBAC functionality can also provide information that you can add as custom claims to identity tokens (and access tokens, if you prefer manual application). Auth0 Organizations can leverage Auth0 RBAC capability via one or more membership-assigned roles. To learn more, see [Add Roles to Organization Members](/docs/manage-users/organizations/configure-organizations/add-member-roles).
</Callout>

* APIs that provide public-facing access to shared resource services are typically protected via access control mechanisms. For this purpose, Auth0 provides the ability to create an authorization bearer token, or <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> 2 [access token](/docs/secure/tokens/access-tokens), which can convey user authorization information to an API, typically by using Auth0 [Role-Based Access Control (RBAC)](/docs/manage-users/access-control/configure-core-rbac) to apply one or more [membership-assigned roles](/docs/manage-users/organizations/configure-organizations/add-member-roles) or by adding custom claims via [Rules](/docs/customize/rules) extensibility. You can also leverage Auth0 RBAC capability to automatically adjust the `scope` claim of an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>. APIs can then use this information to apply the appropriate level of access control, which allows your API to enforce policy rules without having to do an extra lookup to get information about the user.
* In certain cases, you may want to implement application-level policies at the Auth0 Tenant; this allows you to apply policies to a whole range of applications and resource services (APIs) without needing to modify each one independently. You typically implement this via [Rules](/docs/customize/rules) extensibility.

<Callout icon="file-lines">
  **Best Practice**

  Auth0 Organizations provides Auth0 Rules with access to organization-centric information that can be accessed when authenticating a user. This information is available via the `organization` object contained within the Rules `context` object. The `organization` object also provides access to any metadata provisioned against an Organization definition in Auth0. To learn more, see [Custom Development for Organizations](/docs/manage-users/organizations/custom-development).
</Callout>

## ID token claims

Usually claims can be added to identity tokens as discussed in our [ID Token Claims](/docs/get-started/architecture-scenarios/business-to-consumer/authorization) best practice guidance. When using the Auth0 Organizations feature, an `org_id` claim is automatically added to any identity token (for an example, see [Work with Tokens and Organizations](/docs/manage-users/organizations/using-tokens)) issued for users with organization membership. This parameter is validated by Auth0 SDKs. You can also add supplemental information associated with an Auth0 Organization by adding a custom claim to the identity token:

```js wrap lines theme={null}
context.idToken['http://travel0.net/multifactor'] = context.multifactor;
```

**Note**: If you have configured your tenant to support organization names in the Authentication API, the `org_name` claim is automatically included in ID tokens. To learn more, review [Use Organization Names in Authentication API](/docs/manage-users/organizations/configure-organizations/use-org-name-authentication-api).

### SAML assertion

While the Auth0 Organization feature does not support <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip>-aware applications, a SAML assertion generated by an upstream <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> (IdP) can be configured to populate standard or custom claims in an identity token consumed downstream. For example, you could define the mappings section of a SAML enterprise connection:

```json lines theme={null}
{ 
  "user_id": [
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
  ],
  "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
  "name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
  "given_name": [
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
  ], 
  "family_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
  "groups": "http://schemas.xmlsoap.org/claims/Group"
}
```

In this example, each field will be assigned a value in the `user` object in a Rule, which will either map to standard claims in an identity token or can be mapped using custom claims. To learn more about customizing SAML mappings, see [Connect Your App to SAML Identity Providers: Set up mappings](/docs/authenticate/identity-providers/enterprise-identity-providers/saml#set-up-mappings).

## Access token claims

In addition to any other claims you are adding to your access token for access control decisions (see our general [Access Token Claims](/docs/get-started/architecture-scenarios/business-to-consumer/authorization) best practice guidance), you will typically want to communicate the organization to which the user belongs.

As with the identity token, when using the Auth0 Organizations feature, the `org_id` claim is automatically added to any access token (for an example, see [Work with Tokens and Organizations](/docs/manage-users/organizations/using-tokens)) issued for users with organization membership. You can also add supplemental information associated with an Auth0 Organization by adding a custom claim to the access token:

```js wrap lines theme={null}
context.accessToken['http://travel0.net/multifactor'] = context.multifactor;
```

**Note**: If you have configured your tenant to support organization names in the Authentication API, the `org_name` claim is automatically included in access tokens. To learn more, review [Use Organization Names in Authentication API](/docs/manage-users/organizations/configure-organizations/use-org-name-authentication-api).

Alternatively, you could create a unique API <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> for each organization, which would result in a unique API definition in Auth0. While this mechanism can mitigate the need for employing custom Rule extensibility, the complexity it introduces can be challenging. A simple comparison is as follows:

<table>
  <thead>
    <tr>
      <th><strong>Approach</strong></th>
      <th><strong>Pros</strong></th>
      <th><strong>Cons</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Unique API Audience</td>
      <td><ul><li>Out-of-the-box support for machine-to-machine access for a single organization.</li><li>Audience is a standard claim in an access token.</li><li>Refresh token processing requires no additional organization logic.</li></ul></td>
      <td><ul><li>Must automate the creation of an API for every organization.</li><li>Independent roles may need to be created if using RBAC.</li>Must automate the provisioning of Roles to Membership.<li>API implementation has to process for multiple audiences.</li></ul></td>
    </tr>

    <tr>
      <td>Custom Claim</td>
      <td>Simplifies Auth0 Tenant configuration.</td>
      <td>Custom code needed in a rule to add the organization to the access token.</td>
    </tr>
  </tbody>
</table>

### Roles

The Auth0 Organizations feature also supports [Role-Based Access Control (RBAC)](/docs/manage-users/access-control/rbac) via the [Authorization Core](/docs/manage-users/access-control/configure-core-rbac) feature associated with an Auth0 Tenant. RBAC is [applied at the Auth0 Organization membership level](/docs/manage-users/organizations/configure-organizations/add-member-roles).

<Callout icon="file-lines">
  You can [enable Auth0 Authorization Core RBAC for an API](/docs/get-started/apis/enable-role-based-access-control-for-apis), which will result in the default `scope` claim in access tokens being modified automatically and a `permission` claim being added by default (for an example, see [Work with Tokens and Organizations](/docs/manage-users/organizations/using-tokens)). You can also add role information to identity tokens as custom claims by accessing the `authorization` object available in the Rules `context` object. To learn more, see [Rules with Authorization Sample Use Cases: Add User Roles to Tokens](/docs/manage-users/access-control/sample-use-cases-rules-with-authorization).
</Callout>

## Access control

Resource-level policy enforcement is the responsibility of the applications and/or APIs in your system. If you attempt to enforce policies in a centralized <Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip>, such as your Auth0 Tenant, you will quickly run into a complex control system that is difficult to maintain and understand. Instead, your centralized Authorization Server can ensure that the appropriate information about a user is included in the tokens, so that your applications and APIs have the necessary information to make policy enforcement decisions. At the very least, in situations where there is too much information to contain in a single token (for example, resource-level permissions) or where information changes frequently enough that it would be out of date if accessed directly in the token, your applications and APIs should be able to look up the correct information.

Some high-level policy enforcement, on the other hand, can be handled in a centralized fashion. For example, when using an Auth0 Tenant context, there are some situations in which you could implement a Rule that mitigates the need for every application and/or API to apply the same restrictions. These include:

* blocking access to users from a particular IP address
* implementing specific requirements around Contextual or <Tooltip href="/docs/glossary?term=Adaptive+MFA">Adaptive MFA</Tooltip>
* restricting login to only users who have verified their email address
* restricting access to a certain API audience, so a user cannot obtain an access token for any other API audience or cannot obtain an access token for that audience under certain circumstances. In this case, if you’re creating a custom API Audience for each organization, your Rule must also ensure that the authenticating user belongs to the organization that matches the corresponding API audience.

<Warning>
  Auth0 Management API access is not restricted by organization; access to the Auth0 Management API is made via an access token allocated for use within a machine-to-machine context and cannot be constrained by an Auth0 Organization. Therefore, do not provide your customers with direct access to your instance of the Auth0 Management API. If your customers must manage aspects of their organization, such as user accounts (see [Profile Management](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/profile-management)), then you should build your own independent application and/or API for this purpose.
</Warning>


# Single Identity Provider: Branding
Source: https://auth0.com/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/branding

Learn about customizing branding for Organizations in multi-tenant architectures.

Branding collateral associated with an organization is extremely valuable because using brand collateral provides users with an environment that they know and trust. Using recognized brand collateral also increases user confidence that the information they provide (for example, credentials) will be handled safely and securely. In our architecture scenarios, we provide general guidance on a number of [B2B Branding](/docs/get-started/architecture-scenarios/business-to-business/branding) topics, which we recommend reviewing alongside the guidance provided here.

## Universal Login

Branding a multi-organization environment can be more complex than in a standard environment where you only have to deal with one set of brand collateral. [Auth0 Organizations](/docs/manage-users/organizations/organizations-overview), however, leverages the [Universal Login experience](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience), which provides a number of [page templates](/docs/customize/login-pages/universal-login/customize-templates) to help simplify brand customization. Auth0 Organization configuration itself also allows you to [select basic color scheme branding](/docs/manage-users/organizations/configure-organizations/create-organizations).

### Login page

When using a [Database or Custom Database Connection](/docs/authenticate/database-connections), the Login page is used to obtain first-factor credentials for a user. You can configure the Login page using a set of [template variables](/docs/manage-users/organizations/create-first-organization) available to assist with per-organization customization.

<Callout icon="file-lines">
  You can configure the Login Page to display Enterprise and Social Connections for first-factor authentication, so Login Page branding can be relevant in these cases.
</Callout>

### Password Reset page

Similar to the [Login page](#login-page), the Password Reset page can be configured in scenarios that use a Database or Custom Database Connection. For scenarios involving an Enterprise Connection or a Social Connection, password changes are handled external to Auth0 by the upstream <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> (IdP), so an Auth0 Password Reset page is never displayed.

### Multi-factor Authentication pages

<Tooltip href="/docs/glossary?term=Multi-Factor+Authentication">Multi-Factor Authentication</Tooltip> (MFA) in Auth0 is supported for all methods used to obtain first-factor credentials for a user (i.e., Database or Custom Database Connection, Enterprise Connection, or Social Connection). If you're using MFA, then you will likely want to brand the <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> experience pages associated with MFA, which can be done similarly to [Login page](#login-page) branding.

## Email templates

As with Universal Login page templates, a set of [email template variables](/docs/customize/email/email-templates/supported-liquid-syntax#general-variables) are available to assist with per-organization email customization. The email templates that need to be customized will vary depending on how users are authenticated (in other words, via Database or Custom Database Connection, Enterprise Connection, or Social Connection). To learn more about email template customization when using the Auth0 Organizations feature, see [Create Your First Organization: Email Templates](/docs/manage-users/organizations/create-first-organization).

## Custom Domains

The Auth0 Organizations feature supports only one [Custom Domain](/docs/customize/custom-domains), which is defined at the Auth0 Tenant level. Therefore, we recommend that you use a <Tooltip href="/docs/glossary?term=Custom+Domain">Custom Domain</Tooltip> Name that is organization agnostic. If you absolutely must implement per-organization domain naming, then multiple Auth0 Tenants will need to be deployed to production. Because using multiple tenants has ramifications that affect <Tooltip href="/docs/glossary?term=Single+Sign-On">Single Sign-On</Tooltip> (SSO), user profile management, and so on, you should carefully consider before going down this route.


# Single Identity Provider: Logout
Source: https://auth0.com/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/logout

Learn about logging users out for Organizations in multi-tenant architectures.

Terminating an authenticated session when it's no longer needed, otherwise known as Logout, is a good practice when it comes to security hygiene. Providing logout capability helps mitigate a number of potential security issues, including the likelihood that unauthorized parties can "take over" a session. In our architecture scenarios, we provide general purpose guidance on [B2B Logout](/docs/get-started/architecture-scenarios/business-to-business/logout), which we recommend reviewing alongside the guidance provided here. For this scenario, Logout is almost identical to logout in any other system, so it will have the same level of complexity as described in our standard documentation.

## Database Connection

Using our Hoekstra & Associates example, the following diagram illustrates the flow typically encountered when dealing with a user authenticated via an Auth0 Database Connection. Let’s walk through this flow to see what occurs; note that most of the workflow described will typically be handled by using the relevant Auth0 SDK or library associated with your technology stack:

<Frame>
  <img alt="Architecture Scenarios - MOA - Isolated Users, Shared Apps, Logout Flow" />
</Frame>

1. Jennifer clicks `logout`.
2. Hoekstra & Associates' Instance of Travel0 Corporate Booking redirects the browser to the Travel0 Auth0 Tenant at [https://auth.travel0.net](https://auth.travel0.net) with the following parameters:

   1. `returnTo`: [`https://hoekstra.corp.travel0.net/logoutComplete`](https://hoekstra.corp.travel0.net/logoutComplete)
   2. `client_id`: Client ID associated with the Application created in the Travel0 Auth0 Tenant for the Hoekstra & Associates instance of Travel0 Corporate Booking.

      <Callout icon="file-lines">
        **Best Practice**

        Define Applications independently in Auth0 to make it easier to configure the `returnTo` URL where the corresponding `client_id` is used to provide correct validation of the supplied URL. To learn more, see [Provisioning](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/provisioning).
      </Callout>
3. The Travel0 Auth0 Tenant terminates the Auth0 session established on behalf of the user, removing any SSO information, and redirects the browser to the specified `returnTo` URL.
4. The Hoekstra & Associates Instance of Travel0 Corporate Booking renders a page to let Jennifer know that she successfully logged out, likely with a button to log back in if desired.

   1. At this stage, the Travel0 Corporate Booking instance will typically want to clean up the application session associated with the user, too.

<Callout icon="file-lines">
  If you do not wish to remove the user’s SSO session with Auth0, then the application can simply terminate the application session without redirecting to the `/logout` endpoint on the Auth0 Tenant. While the user will be logged out of the application, they will still have an SSO session with Auth0. In this case, you will likely want to tell the user that they are still logged in to the Auth0 Tenant, and that if they click `login` again, they may not be challenged to enter first-factor credentials.
</Callout>

## Enterprise Connection

For this scenario, implementing Logout can be a little more complex than it is when using a Database Connection. You still have the option to either logout from only the application or to have logout from the application result in logout from the Auth0 Tenant, too. However, you may also have the option of allowing logout from the organization’s <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> (IdP), which most applications avoid, especially if users have access to other corporate applications to which they may need to stay logged in. Avoiding this, however, may result in users who subsequently click the `login` button being authenticated automatically without interactively providing first-factor credentials. Such functionality may make for an unexpected user experience, so you should consider communicating this to the user.

Using our MetaHexa Bank example, let's see how this Logout implementation might flow with a user authenticated via an Enterprise Connection to MetaHexa Bank; again, most of the workflow described will typically be handled by using the relevant Auth0 SDK or library associated with your technology stack:

<Frame>
  <img alt="Architecture Scenarios - MOA - Isolated Users, Shared Apps, Enterprise Logout Flow" />
</Frame>

1. Amintha clicks `logout`.
2. MetaHexa Bank's Instance of Travel0 Corporate Booking redirects the browser to the Travel0 Auth0 Tenant at [https://auth.travel0.net](https://auth.travel0.net) with the following parameters:

   1. `returnTo`: [`https://metahexa.corp.travel0.net/logoutComplete`](https://metahexa.corp.travel0.net/logoutComplete)
   2. `client_id`: Client ID associated with the Application created in the Travel0 Auth0 Tenant for the MetaHexa Bank instance of Travel0 Corporate Booking.
   3. `federated`:  Optional parameter used to log the user out of the MetaHexa Bank IdP. When specified, the browser is redirected to the `/logout` endpoint associated with the MetaHexa Bank IdP, which terminates the user’s session before redirecting the browser back to the Travel0 Auth0 Tenant.

      <Callout icon="file-lines">
        **Best Practice**

        Define Applications independently in Auth0 to make it easier to configure the `returnTo` URL where the corresponding `client_id` is used to provide correct validation of the supplied URL. To learn more, see [Provisioning](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/provisioning).
      </Callout>

Steps 3 and 4 will match those described in the [Database Connection](#database-connection) scenario, but will use Amintha in place of Jennifer and MetaHexa Bank (`metahexa.corp.travel0.net`) in place of Hoekstra & Associates.

## Social Connection

In the context of Social Connections, Logout follows a similar pattern to that associated with an [Enterprise Connection](#enterprise-connection), but the upstream IdP is associated with the social provider rather than any specific organization. You will almost certainly never want to leverage federated logout capability with a social provider because the resulting user experience would be too disruptive.


# Single Identity Provider: Profile Management
Source: https://auth0.com/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/profile-management

Learn about user profile management for Organizations in multi-tenant architectures.

Profile Management in Organization-based scenarios is generally the same as in other architecture scenarios. In our architecture scenarios, we provide general purpose guidance on [B2B Profile Management](/docs/get-started/architecture-scenarios/business-to-business/profile-management), which we recommend reviewing alongside the guidance provided here.

<Warning>
  Before roles associated with a user can be managed, a user account must exist in Auth0. This is true even if you are using the [Auth0 Organizations Role capability associated with Membership](/docs/manage-users/organizations/configure-organizations/add-member-roles). However, user accounts that are provisioned via the [user invitation](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/provisioning) workflow can be assigned a role automatically as part of the invitation process. For details, see the [Invite Organization Members](/docs/manage-users/organizations/configure-organizations/invite-members). If you’re pre-registering a user using some other mechanism, then you must store Role information outside of Auth0 and access/copy it via the use of extensibility (for example, as part of a [Rule](/docs/customize/rules)) during first authentication.
</Warning>

Your application may have an associated specific set of user attributes (for example, user preferences or identifying information you use to better serve the customer) for which you provide some sort of self-service management to users. Additionally/alternatively, you may provide self-service profile management for attributes that are typically maintained by the <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> (IdP).

<Callout icon="file-lines">
  **Best Practice**

  In organization-related scenarios, email addresses should always be verified. Consequently, you should provide self-service email verification functionality for situations in which a user’s email address cannot otherwise be verified. For further details, see [Email Verification](/docs/manage-users/user-accounts/verify-emails).
</Callout>

## Database Connection

Auth0 provides you with the capability to implement self-service profile management support via the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. If you are using Auth0 Organizations to provide [invitation-based user provisioning](/docs/manage-users/organizations/configure-organizations/invite-members), you will likely need to restrict changes to fields that are typically owned by your Auth0 Tenant as the Identity Provider (IdP). For example, you would want to restrict changes to email address because you would not want a user to use an email address other than the one to which their invitation was sent. Restricting changes to the email address field would prevent company-specific emails from going to entered personal email addresses.

Alternatively, you may want to consider providing a few self-service items for users who authenticate via a Database Connection in Auth0. You may want users to be able to:

* change their email address
* change any associated phone numbers
* change their username
* de-provision their accounts as part of regulatory compliance (such as GDPR)
* perform password change processing, which we typically recommend you implement via [password reset](/docs/authenticate/database-connections/password-change#trigger-an-interactive-password-reset-flow) and which will typically leverage the organization-specific branding described in [Branding: Password Reset Page](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/branding).

<Callout icon="file-lines">
  Self-service capability typically needs to be implemented and hosted external to Auth0 and must be very secure.
</Callout>

## Enterprise connection

Because the upstream Identity Provider (IdP) typically handles IdP-managed user profile attributes, profile management can be fairly non-existent for this use case. However, if you use application-specific user attributes, then you may still want to provide self-service capability.

In addition, you will almost certainly want to provide an organization with a way to de-provision users from your Auth0 Tenant. Auth0 does not communicate with an upstream IdP, except when the Auth0 <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> session expires. Because an SSO session's time to expiration will likely be too long for most scenarios in which a user is deleted, an organization administrator will need a way to block or delete a user independently.

## Social connection

In the context of Social Connections, profile management follows a similar pattern to that associated with an [Enterprise Connection](#enterprise-connection), but the upstream IdP is associated with the social provider rather than any specific organization.

## Administration

In certain situations you will want to give your customers access to manage user accounts associated with their organization. This is often true for help-desk-type scenarios in which a help desk operator may update profile information on behalf of a user or help a user unblock an account.

Out of the box, Auth0 provides the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, which is used for general management of an Auth0 Tenant. However, you would not want to give a customer access to your Auth0 Tenant Dashboard because they would then have the ability to manage all users across all organizations, which would not be desirable.

<Warning>
  While the Auth0 Tenant Dashboard can be used to manage user accounts, it does not provide for organizational-level isolation. Giving a customer access to your Auth0 Dashboard allows them to modify users across all organizations, which is not desirable. The Auth0 Delegated Admin dashboard can be configured to provide user account administration that is Auth0-Organization-aware; however, it cannot be used to manage user [Membership](/docs/manage-users/organizations/create-first-organization) or [Invitation](/docs/manage-users/organizations/configure-organizations/invite-members).
</Warning>

If you already provide help-desk-type capability for your customers, then you can use the Auth0 Management API to manage user accounts in Auth0. For example, the Management API can be used to [retrieve organization members](/docs/manage-users/organizations/configure-organizations/retrieve-members) and [organizations to which a user belongs](/docs/manage-users/organizations/configure-organizations/retrieve-user-membership). If you do not already provide help desk capability, then you will need to build this functionality if you require it.


# Single Identity Provider: Provisioning
Source: https://auth0.com/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/provisioning

Learn about provisioning Organizations for multi-tenant architectures.

By using the Auth0 Organizations feature, a single Auth0 Tenant can be provisioned for deployment to a production environment. For all but the most complex architectural scenarios, provisioning of a single Auth0 Tenant for use in a production environment is recommended because it provides ease of integration/use for [Single Sign-On (SSO)](/docs/authenticate/single-sign-on), user [Profile Management](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/profile-management), and so on. Depending on the implementation, you will need to address some additional items concerning setup of your Auth0 Tenant and your corresponding integration.

Branding associated with an organization is extremely valuable because using brand collateral provides users with an environment that they know and trust. Using recognized brand collateral also increases user confidence that the information they provide (for example, credentials) will be handled safely and securely. Default out-of-box Auth0 branding should therefore be replaced. To learn more, see [Branding](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/branding).

## Organizations

You should create an independent Auth0 Organization for each of the organizations you will support. In this case, we’ll create the `hoekstra` organization to represent Hoekstra & Associates in our example, and the `metahexa` organization to represent MetaHexa Bank. You can [create organizations](/docs/manage-users/organizations/configure-organizations/create-organizations) either manually via the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or programmatically via the use of the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## Applications

Depending on how your Organization Tenant implementation is designed, you have different options when creating [Application](/docs/get-started/applications) definitions within your Auth0 Tenant. Whichever option you choose, the [Organization behavior is defined at the application level](/docs/manage-users/organizations/configure-organizations/define-organization-behavior).

If you provision a separate Organization Tenant for each of your customers, then you will typically need an independent Application definition in Auth0 for each. This arrangement will also usually involve sending both the Application-specific `client_id` parameter and the `organization` parameter, which identifies which Auth0 Organization to use, as part of the call to the `/authorize` endpoint. To learn more, see [Authentication](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/authentication).

<Callout icon="file-lines">
  **Best Practice**

  For ease of configuration and maximized security isolation, define Applications in Auth0 independently. Doing so allows items like allowed callback URLs to be configured independently and, following the principle of least privilege, minimizes the potential exposure of any Client ID and Client Secret information.
</Callout>

Alternatively, the use of a single Application definition in Auth0 is supported. In this case, the user will be prompted to specify the required organization as part of first-factor authentication. This will typically require the use of a common Application `client_id`, but the `organization` parameter will be omitted on the call to the `/authorize` endpoint.

## Connections

Next, define the [Connections](/docs/authenticate/identity-providers) that will be used to authenticate users. In this case, we’ll define a [Database Connection](/docs/authenticate/database-connections) for users associated with Hoekstra & Associates and an [Enterprise Connection](/docs/authenticate/identity-providers/enterprise-identity-providers) for users associated with MetaHexa Bank.

<Callout icon="file-lines">
  **Best Practice**

  For Single Identity Provider (IdP) Organizations, create one Connection for each defined organization in order to provide flexibility for a number of use case scenarios. For example, a single [Database or Custom Database Connection](/docs/authenticate/database-connections) per organization allows you to easily delete users associated with organizations that get decommissioned and offers maximum flexibility for organizations that have differing requirements for password complexity.
</Callout>

Once the Connection has been defined, it can be provisioned to the appropriate Auth0 Organization using either the Auth0 Dashboard or Auth0 Management API. For more information, see [Enable Organization Connections](/docs/manage-users/organizations/configure-organizations/enable-connections).

## Users

For users that are authenticated via Connections other than Database or Custom Database Connections, the user is provisioned to the external <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> (IdP) independent of Auth0 and in the normal way. On the other hand, users that are authenticated via Database or Custom Database Connections can be provisioned in a number of different ways. The Auth0 Dashboard and Auth0 Management API can be used to create a user directly in your Auth0 Tenant. We also support [Automatic Migration](/docs/manage-users/user-migration/configure-automatic-migration-from-your-database) and [Bulk Migration](/docs/manage-users/user-migration/bulk-user-imports).

<Warning>
  For a user to be provisioned via the Management API or the Dashboard, you must directly enable a Database or Custom Database Connection for at least one Application. Enabling a Database or Custom Database Connection for an Organization only will not suffice.
</Warning>

Users are then associated with an Auth0 Organization by assigning them memberships, and an Auth0 Organization can be configured to [assign user Membership automatically](/docs/manage-users/organizations/configure-organizations/grant-just-in-time-membership) or [on a manual basis](/docs/manage-users/organizations/configure-organizations/assign-members).

<Callout icon="file-lines">
  For a user to be manually assigned Membership to an organization, that user must already have a [User Profile](/docs/manage-users/user-accounts/user-profiles) defined in Auth0. You can [manually assign Membership](/docs/manage-users/organizations/configure-organizations/assign-members) using either the Auth0 Tenant Dashboard or the Auth0 Management API.
</Callout>

### Invitation

The Auth0 Organization feature also supports the use of Member Invitation. In the Member Invitation workflow, inviting a user to an application will result in the user being provisioned automatically and their user membership being generated automatically.

#### Database Connection

Using our Hoekstra & Associates example, let’s see how this implementation might flow where a Database Connection is used as part of user invitation; most of the workflow described will typically be handled by using the relevant Auth0 SDK or library associated with your technology stack:

<Frame>
  <img alt="Architecture Scenarios - MOA - Isolated Users, Shared Apps, Invitation Flow (Database Connection)" />
</Frame>

1. Jennifer from Hoekstra & Associates receives an email sent from Travel0’s Auth0 Tenant on behalf of Hoekstra & Associates' instance of Travel0 Corporate Booking.

   1. The email was sent as described in [Invite Organization Members](/docs/manage-users/organizations/configure-organizations/invite-members) and may have been triggered using either the Auth0 Dashboard or the Auth0 Management API.
2. Jennifer opens the email and clicks on its contained link. Doing so directs her browser to Hoekstra & Associates' instance of Travel0 Corporate Booking. The base URL used in the link is specified as the [Application Login URI](/docs/get-started/applications/application-settings), which forms part of Hoekstra & Associates' instance of Travel0 Corporate Booking application definition in the Travel0 Auth0 Tenant.

   1. The link contains `organization` and `organization_name` parameters. The `organization` parameter is set to the ID of the corresponding Auth0 Organization definition in your Auth0 Tenant. This will be forwarded to the Auth0 Tenant as part of step 3.
   2. The link also contains the `invitation` parameter, which will also be forwarded as part of step 3.
3. Hoekstra & Associates' instance of Travel0 Corporate Booking redirects to the Travel0 Auth0 Tenant using [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow) (with or without [PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce)) by calling the `/authorize` endpoint and passing parameters similar to the following, typically via use of an [Auth0 SDK](/docs/libraries) or third-party library:

   1. `redirect_uri`: [`https://hoekstra.corp.travel0.net/login/callback`](https://hoekstra.corp.travel0.net/login/callback)
   2. `response_type`: `code`
   3. `state`: Unique [state](/docs/secure/attack-protection/state-parameters) generated in this session
   4. `scope`: `openid profile` ...
   5. any necessary additional [OIDC Scopes](/docs/get-started/apis/scopes/openid-connect-scopes), depending on the information required about the user.
   6. `client_id`: Client ID associated with the Application created in the Travel0 Auth0 Tenant for Hoekstra & Associates' instance of Travel0 Corporate Booking.
   7. `organization`: ID of the inviting organization typically obtained via the link in the email described in step 2. Specified in the form `organization=`organization\_id, where organization\_id is set to the identifier associated with the corresponding Auth0 Organization definition in your Auth0 Tenant.
   8. `invitation`: Additional `invitation` parameter associated with the link in the email, as described in step 2.
4. The Travel0 Auth0 Tenant redirects to `/signup/invitation` to collect a password credential from the user.

   1. A Universal Login Page, which you can configure to display organization-specific brand collateral as described in [Branding](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/branding), is displayed.

      <Warning>
        The invitation workflow associated with the Auth0 Organizations feature does not consider any SSO session held with Auth0. If a user is invited to sign up and they are already signed in, clicking the link in the email will always result in the display of the associated Universal Login Page.
      </Warning>
5. The user enters their password (and any additional credentials, such as user name) and clicks continue. The user ID is set to the email address associated with the user and cannot be changed.
6. The Travel0 Auth0 Tenant checks credentials. If valid, the user is provisioned and Auth0 Organization Membership is set. The user is implicitly authenticated, and the [Rules](/docs/customize/rules) pipeline executes. Rules can be used to handle access control, as described in [Authorization](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/authorization).

   1. If credentials for the user are invalid, then the user will be prompted to re-enter them.
7. Upon successful credential checking and Rules execution, the user is redirected to the `redirect_uri` ([`https://hoekstra.corp.travel0.net/login/callback`](https://hoekstra.corp.travel0.net/login/callback)) with the `state` passed in step 3, as well as a `code`.
8. Hoekstra & Associates' instance of Travel0 Corporate Booking validates the `state` and then calls the Travel0 Auth0 Tenant at [`https://auth.travel0.net/oauth/token`](https://auth.travel0.net/oauth/token), passing the `code` and its `client id` and `client secret` in exchange for the [ID Token](/docs/secure/tokens/id-tokens). The ID token is then used to generate a session for [`https://hoekstra.corp.travel0.net`](https://hoekstra.corp.travel0.net).
9. Hoekstra & Associates' instance of Travel0 Corporate Booking instance displays the appropriate page to the user.

#### Enterprise Connection

Using our MetaHexa Bank example, let’s see how this implementation might flow where an Enterprise Connection is used as part of user invitation; again, most of the workflow described will typically be handled by using the relevant Auth0 SDK or library associated with your technology stack:

<Frame>
  <img alt="Architecture Scenarios - MOA - Isolated Users, Shared Apps, Invitation Flow (Enterprise Connection)" />
</Frame>

1. Amintha from MetaHexa Bank receives an email sent from Travel0’s Auth0 Tenant on behalf of MetaHexa Bank's instance of Travel0 Corporate Booking.

   1. The email was sent as described in [Invite Organization Members](/docs/manage-users/organizations/configure-organizations/invite-members) and may have been triggered using either the Auth0 Dashboard or the Auth0 Management API.
2. Amintha opens the email and clicks on its contained link. Doing so directs her browser to MetaHexa Bank's instance of Travel0 Corporate Booking. The base URL used in the link is specified as the [Application Login URI](/docs/get-started/applications/application-settings), which forms part of MetaHexa Bank's instance of Travel0 Corporate Booking application definition in the Travel0 Auth0 Tenant.

   1. The link contains `organization` and `organization_name` parameters. The `organization` parameter is set to the ID of the corresponding Auth0 Organization definition in your Auth0 Tenant. This will be forwarded to the Auth0 Tenant as part of step 3.
   2. The link also contains the `invitation` parameter, which will also be forwarded as part of step 3.
3. MetaHexa Bank's instance of Travel0 Corporate Booking redirects to the Travel0 Auth0 Tenant using [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow) (with or without [PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce)) by calling the `/authorize` endpoint and passing parameters similar to the following, typically via use of an [Auth0 SDK](/docs/libraries) or third-party library:

   1. `redirect_uri`: [`https://metahexa.corp.travel0.net/login/callback`](https://metahexa.corp.travel0.net/login/callback)
   2. `response_type`: `code`
   3. `state`: Unique [state](/docs/secure/attack-protection/state-parameters) generated in this session
   4. `scope`: `openid profile` ...
   5. any necessary additional [OIDC Scopes](/docs/get-started/apis/scopes/openid-connect-scopes), depending on the information required about the user.
   6. `client_id`: Client ID associated with the Application created in the Travel0 Auth0 Tenant for MetaHexa Bank's instance of Travel0 Corporate Booking.
   7. `organization`: ID of the inviting organization typically obtained via the link in the email described in step 2. Specified in the form `organization=`organization\_id, where organization\_id is set to the identifier associated with the corresponding Auth0 Organization definition in your Auth0 Tenant.
   8. `invitation`: Additional `invitation` parameter associated with the link in the email, as described in step 2.
4. The Travel0 Auth0 Tenant redirects to `/invitation`, where Amintha is informed that she will be redirected to the MetaHexa IdP to authenticate first-factor credentials.

   1. The user confirms, and
   2. Auth0 redirects to the MetaHexa Bank IdP instance, where
   3. The login page is displayed, and the user enters credentials and clicks `login`.
5. If successful, the Auth0 Organization Membership is set, the user is implicitly authenticated, and the [Rules](/docs/customize/rules) pipeline executes. Rules can be used to handle access control as described in [Authorization](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/authorization).

Steps 6 through 8 will match those described in the [Database Connection](#database-connection) scenario, but where Amintha is the user instead of Jennifer, and where MetaHexa Bank (`metahexa.corp.travel0.net`) will be used in place of Hoekstra & Associates.

#### Social Connection

Invitation via Social Connection follows a similar pattern to that associated with an [Enterprise Connection](#enterprise-connections), but the upstream IdP is associated with the social provider rather than any specific organization. For additional considerations with respect to using Social Connections, please see [Authentication](/docs/get-started/architecture-scenarios/multiple-organization-architecture/single-identity-provider-organizations/authentication).


# Server Applications with API
Source: https://auth0.com/docs/get-started/architecture-scenarios/server-application-api

Explains the architecture scenario with server to server communication with secure calls to an API (resource server) on behalf of the application.

In this scenario we will build a Timesheet API for a fictitious company named ExampleCo. The API will allow additional timesheet entries for an employee or a contractor.

We will also be building a cron job which will process timesheet entries from an external system to the centralized timesheet database using the API.

<Info>
  ### TL;DR

  * Auth0 provides API authentication and authorization as a means to secure access to API endpoints (read [API Authentication and Authorization](/docs/get-started/architecture-scenarios/server-application-api/part-1#api-authentication-and-authorization))
  * For authorizing a Machine-to-Machine Application (a CLI, service or daemon where no user interaction is involved) Auth0 supports the Client Credentials grant (read [Client Credentials Grant](/docs/get-started/architecture-scenarios/server-application-api/part-1#client-credentials-grant))
  * Both the Machine-to-Machine Application and the API must be configured in the Auth0 Dashboard (read [Auth0 Configuration](/docs/get-started/architecture-scenarios/server-application-api/part-2))
  * The API will be secured by ensuring that a valid access token (which is implemented as a JSON Web Token) is passed in the HTTP Authorization header when calls are made to the API (read [Implement the API](/docs/get-started/architecture-scenarios/server-application-api/part-3))
  * Upon successful authorization an access token is issued to the Machine-to-Machine Application (read [Get an access token](/docs/get-started/architecture-scenarios/server-application-api/part-3#get-an-access-token))
  * The Machine-to-Machine Application can in turn use this access token to pass along as an HTTP Authorization header to authenticate calls to API endpoints (read [Invoke the API](/docs/get-started/architecture-scenarios/server-application-api/part-3#invoke-the-api))
</Info>

## The Premise

ExampleCo is a consulting startup company. Currently they have approximately 100 employees and also outsource to external contractors. All employees and external contractors are required to complete timesheets every week. For this purpose, they built a timesheets application, a scenario we covered in [Single Sign-On for Regular Web Apps](/docs/get-started/architecture-scenarios/sso-for-regular-web-apps). Internal employees use this web app to fill in their timesheets but some of the external contractors already use another tool to track their timesheets. ExampleCo needs a solution to avoid the double work and decided to build a cron job to read the timesheet entries from this external system and automatically upload those to ExampleCo's backend using an API.

### Goals & Requirements

ExampleCo wants to build a flexible solution that:

* Allows for automated processes working on the backend
* Allows for future application launches, like a mobile application, in the architecture
* Allows for the Timesheets API to be secure and accessed by authorized users and applications
* Allows for a large part of code and business logic for the application to be shared across other apps

## Learn more

* [Solution Overview (Server Apps + API)](/docs/get-started/architecture-scenarios/server-application-api/part-1)
* [Auth0 Configuration (Server Apps + API)](/docs/get-started/architecture-scenarios/server-application-api/part-2)
* [Application Implementation (Server Apps + API)](/docs/get-started/architecture-scenarios/server-application-api/part-3)
* [Conclusion (Server Apps + API)](/docs/get-started/architecture-scenarios/server-application-api/part-4)


# Solution Overview (Server Apps + API)
Source: https://auth0.com/docs/get-started/architecture-scenarios/server-application-api/part-1

Solutions Overview for the Server + API architecture scenario

In order to ensure that only authorized users and applications are allowed access to the Timesheets API, ExampleCo has decided to make use of the [OAuth 2.0 authorization framework](https://tools.ietf.org/html/rfc6749). The framework provides the flexibility the company wants since the different grants can allow them to easily authorize the various types of applications which need to communicate with the Timesheets API.

## OAuth 2.0

By using the <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> authorization framework, ExampleCo’s Regular Web application and the third-party application for external contractors can have limited access to the Timesheets API. Using Auth0, ExampleCo can easily support different [grant types](/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use) or authentication flows without worrying about the OAuth 2.0/<Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) specification, or the many other technical aspects of API authorization.

<Card title="OAuth roles">
  In any OAuth 2.0 flow we can identify the following roles:

  * **Resource Owner**: the entity that can grant access to a protected resource. Typically this is the end-user.
  * **Resource Server**: the server hosting the protected resources. This is the API you want to access.
  * **Client**: an application requesting access to a protected resource on behalf of the Resource Owner.
  * **Authorization Server**: the server that authenticates the Resource Owner, and issues Access Tokens after getting proper authorization. In this case, Auth0's Authentication API.

  [Grants types (or flows)](/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use) determine how these participants interact to grant to the applications limited access to the APIs you are building. As a result, the app will obtain an access token that can be used to call the API on behalf of the user.
</Card>

### Client Credentials Grant

OAuth 2 provides several grant types for different use cases. In this particular use case where a cron job will be uploading timesheets via an API, there is no interactive user (or <Tooltip href="/docs/glossary?term=resource+owner">resource owner</Tooltip>) to grant permissions to the cron job to access the API.

The cron job is also not making the API calls on behalf of any user. Instead the application (the cron job) uses machine-to-machine authorization makes calls to the <Tooltip href="/docs/glossary?term=Resource+Server">Resource Server</Tooltip> (the API) on its own behalf.

For situations like this where there is no user interaction involved, the [Client Credentials Grant](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow) is ideal. With the Client Credentials Grant (defined in [RFC 6749, section 4.4](https://tools.ietf.org/html/rfc6749#section-4.4)), an application can directly request an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> from the <Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip> by using its client credentials (a <Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip> and a <Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip>). Instead of identifying a Resource Owner, this token will represent the application itself.

<Frame>
  <img alt="undefined" />
</Frame>

1. The application authenticates with the Authorization Server using its Client ID and Client Secret.
2. The Authorization Server validates this information and returns an access token.
3. The application can use the access token to call the Resource Server on behalf of itself.

## API Authentication and Authorization

An API is a way to expose functionality of your application to other applications. Other applications can make a request to an API endpoint and receive a response. Similarly, the external application ExampleCo’s contractors use can communicate with the Timesheet API as well as the Regular Web Application ExampleCo built for internal employees.

Since the Timesheets API handles sensitive information (such as PII and financial information), ExampleCo needs to ensure only authorized users and applications can call its' endpoints.

### Access tokens and scopes

APIs can be secured or unsecured. When an application wants to access protected endpoints on an API, it needs to provide an access token (also referred to as `access_token`) as proof that it has the required permissions.

An access token is an opaque string representing an authorization issued to the application and is obtained by authenticating the user with an Authorization Server. The user can then, in turn, authorize the application to access the API on their behalf. To learn more, read [Access Tokens](/docs/secure/tokens/access-tokens).

An API like the Timesheets API can enforce fine-grained control over who can access the various endpoints exposed by the API. These permissions are expressed as scopes.

When ExampleCo’s Regular Web Application or the third-party application authenticates with Auth0 to get an access token, the authentication request includes the list of requested scopes the application requires. If those scopes are allowed, then the access token will contain a list of authorized scopes granted to the application.

The Regular Web App or third-party application includes the access token from the Authorization Server when making requests to the Timesheets API, and the Timesheets API inspects the scope claim to ensure that the required permissions were granted in order to call the particular endpoint.

For example, the timesheet API may accept four different levels of authorization: reading timesheets (scope `read:timesheets`), creating timesheets (scope `create:timesheets`), deleting timesheets (scope `delete:timesheets`) and approving timesheets (scope `approve:timesheets`).

For more information on scopes refer to [Scopes](/docs/get-started/apis/scopes).

When the Regular Web App sends a request to the Timesheets API to create a new timesheet entry, the access token must contain the `create:timesheets` scope or the request will be denied. Similarly, to delete existing timesheets, the access token must contain the `delete:timesheets` scope.

To learn more, read [Scopes](/docs/get-started/apis/scopes).


# Auth0 Configuration (Server Apps + API)
Source: https://auth0.com/docs/get-started/architecture-scenarios/server-application-api/part-2

Auth0 Configuration for the Server + API architecture scenario

In this section, we will review ExampleCo's configurations using the [Auth0 Dashboard](https://manage.auth0.com/#).

## Configure the API

To protect an API, you must register an API using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. Follow instructions on [Register APIs](/docs/get-started/auth0-overview/set-up-apis) to configure the Timesheets API.

### JSON Web Token Profile

<Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> defines the type of profiles, or dialects, for an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>. Auth0 supports two different profiles:

* Auth0 token profile
* RFC 9068 profile

The default is the Auth0 profile. The main difference between these two profiles is the difference in claim names. The Auth0 profile uses `azp` rather than `client_id`. You can learn more about the differences by reading [Access Token Profiles](/docs/secure/tokens/access-tokens/access-token-profiles).

### Signing Algorithms

When you create an API, you must select the algorithm with which your tokens will be signed. The signature is used to verify that the sender of the <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> is who it says it is and to ensure that the message hasn't been changed along the way.

<Callout icon="file-lines">
  The signature is part of a JWT. If you are unfamiliar with JWT structure, please see [JSON Web Token Structure](/docs/secure/tokens/json-web-tokens/json-web-token-structure).
</Callout>

To create the signature, you must take the encoded header, the encoded payload, a secret, the algorithm specified in the header, and sign that. That algorithm, which is part of the JWT header, is the one you select for your API: `HS256,` `RS256,` or `PS256`.

The most secure practice, and our recommendation, is to use **RS256**. Some of the reasons are:

* With RS256, you are sure that only the holder of the private key (Auth0) can sign tokens, while anyone can check if the token is valid using the public key.
* Under HS256, if the private key is compromised you would have to re-deploy the API with the new secret. With RS256, you can request a token that is valid for multiple audiences.
* With RS256, you can implement key rotation without having to re-deploy the API with the new secret.

## Configure the Scopes

In the settings for your API, you will need to configure the Scopes that applications can request during authorization. Navigate to the Permissions tab.

In this section, you can add all four of the scopes discussed before: `batch:upload`, `read:timesheets`, `create:timesheets`, `delete:timesheets`, and `approve:timesheets`. Also add an additional scope: `batch:upload`.

<Callout icon="file-lines">
  For the purpose of this document, we will only be concerned with the `batch:upload` scope because that is all that is required by the cron job. However, for the sake of completeness, we are adding the necessary scopes which will be required by future applications.
</Callout>

<Frame>
  <img alt="Dashboard > APIs > Permissions" />
</Frame>

## Create the Application

When creating an API in the Auth0 Dashboard, a test application for the API will automatically be generated. In the Auth0 Dashboard, navigate to the [Application Section](https://manage.auth0.com/#/applications), and you will see the test application for the Timesheets API.

<Frame>
  <img alt="undefined" />
</Frame>

Go to the settings for the application by selecting the menu option at the end. Rename the application to `Timesheets Import Job`.

For the cron job, you will need a Machine-to-Machine Application. The test application that was generated when the API was created was automatically configured as a Machine-to-Machine Application.

## Configure Application's access to the API

Finally, you must allow the application access to the Timesheets API. Go back to the configuration of the API, and select the Machine to Machine Application tab.

You will see the **Timesheets Import Job** application listed, and it should have access to API as can be seen from the switch to the right of the application name which indicates a value of `Authorized`. If it does not indicate that the application is authorized, simply toggle the value of the switch from `Unauthorized` to `Authorized`.

You will also need to specify which scopes will be included in access tokens that are issued to the application when the application authorizes with Auth0.

Expand the settings for the application by clicking on the down arrow to the far right, and you will see the list of available scopes. The cron job will only require the `batch:upload` scope as it will simply create new timesheets based on the timesheet entries in the external system.

Once you have selected the `batch:upload` scope, save the settings by clicking the **Update** button.

<Frame>
  <img alt="Dashboard - Applications - APIs - Machine to Machine Applications - Authorize" />
</Frame>

Now that we have designed our solution and discussed the configurations needed on Auth0's side, we can proceed with the implementation.


# Application Implementation (Server Apps + API)
Source: https://auth0.com/docs/get-started/architecture-scenarios/server-application-api/part-3

Application Implementation for the Server + API architecture scenario

In this section of the tutorial, we will take an in-depth look into our API and its associated Machine-to-Machine Application. To start at the beginning, read [Server Applications with API](/docs/get-started/architecture-scenarios/server-application-api).

<Callout icon="file-lines">
  For simplicity, we will keep our implementation solely focused on authentication and authorization. As you will see in the samples, the input timesheet entry will be hard-coded, and the API will not persist the timesheet entry. Instead, it will simply echo back some of the info.
</Callout>

## Define the API endpoints

An **API endpoint** is a static URI that represents a resource (collection of data).

For example, a restaurant API might have endpoints such as `/orders` and `/customers`. An application that connects to this API can perform CRUD (create, read, update, delete) operations by calling an API endpoint with the associated HTTP method (`POST`, `GET`, `PUT`, `PATCH`, or `DELETE`).

For ExampleCo's Timesheets API, you will need to configure an endpoint to create timesheet entries.

<table>
  <thead>
    <tr>
      <th><strong>HTTP method</strong></th>
      <th><strong>API endpoint</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>POST</code></td>
      <td><code>/timesheets/upload</code></td>
      <td>Creates a new timesheet entry</td>
    </tr>
  </tbody>
</table>

```json lines theme={null}
{
  'user_id': '007',
  'date': '2017-05-10T17:40:20.095Z',
  'project': 'StoreZero',
  'hours': 5
}
```

If the API processes the request successfully, it sends a response with an `HTTP 201 Created` status code and the body containing a JSON object with a message property that describes the newly-created timesheet:

```json lines theme={null}
{
"message": "Created timesheet 14 for employee 007."
}
```

<Callout icon="file-lines">
  See the implementation in [Node.js](/docs/get-started/architecture-scenarios/server-application-api/api-implementation-nodejs#1-define-the-api-endpoint).
</Callout>

### Secure the API endpoints

To secure your API endpoint(s), you need to implement a middleware function within your API application to handle tokens. This function checks if a token was included with the API request, validates the token, and then confirms if the scope(s) required to perform the requested action are present.

If all criteria are satisfied, the API application responds with the message mentioned previously. If there are any issues with the provided <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> (or it’s not provided at all), the API application sends a response with the `HTTP 401 Unauthorized` status code.

**See the implementation in** [**Node.js**](/docs/get-started/architecture-scenarios/server-application-api/api-implementation-nodejs#2-secure-the-api-endpoint)**.**

#### Get an access token

To get an access token without using our application sample implementation, call the Auth0 Authentication API's [Get Token](https://auth0.com/docs/api/authentication#get-token54) endpoint with the following payload:

```json lines theme={null}
{
  audience: "{yourApiIdentifier}",
  grant_type: "client_credentials",
  client_id: "${account.client_id}",
  client_secret: "${account.client_secret}"
}
```

## Check the application permissions

Now we have secured our API's endpoint with an access token, but we still haven't ensured that the process calling the API has the rights to post a new timesheet entry.

As discussed earlier, each access token may include a list of the permissions that have been granted to the application. These permissions are defined using the `scope` request parameter. To learn how to configure this, see the [Configure the Scopes](/docs/get-started/architecture-scenarios/server-application-api/part-3#configure-the-scopes) paragraph.

For our endpoint, we will require the scope `batch:upload`.

**See the implementation in** [**Node.js**](/docs/get-started/architecture-scenarios/server-application-api/api-implementation-nodejs#3-check-the-client-permissions)**.**

### Implement the Machine-to-Machine Application

In this section, we will see how we can implement a Machine-to-Machine Application for our scenario.

### Get an access token

We will start by invoking the Auth0 `/oauth/token` API endpoint to get an access token.

To do so, we will need the following configuration values you can find in your [application settings](https://manage.auth0.com/#/applications):

* **Domain**: Auth0 Domain and also your tenant identifier. This value will be a part of the API URL: `https://{yourTenant}/oauth/token`.
* **<Tooltip href="/docs/glossary?term=Audience">Audience</Tooltip>**: API identifier.
* **<Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>**: Auth0 Application's Client ID.
* **<Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip>**: Auth0 application's Client Secret.

Our implementation should perform a `POST` operation to the `https://{yourDomain}/oauth/token` endpoint with a payload in the following format:

```json lines theme={null}
{
  "audience": "{yourApiIdentifier}",
  "grant_type": "client_credentials",
  "client_id": "${account.client_id}",
  "client_secret": "${account.client_secret}"
}
```

To learn more, see [Call Your API Using the Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow/call-your-api-using-the-client-credentials-flow).

**See the implementation in** [**Python**](/docs/get-started/architecture-scenarios/server-application-api/cron-implementation-python#get-an-access-token).

## Invoke the API

Now that we have an access token that includes the valid scopes, we can invoke our API.

To do so, we will:

* Build a hard-coded timesheet entry in JSON format.
* Add the access token as an `Authorization` header to our request.
* Make the HTTP `POST` request.
* Parse the response, and print it in the terminal (optional).

**See the implementation in** [**Python**](/docs/get-started/architecture-scenarios/server-application-api/cron-implementation-python#invoke-the-api).


# Regular Web Applications with Single Sign-On
Source: https://auth0.com/docs/get-started/architecture-scenarios/sso-for-regular-web-apps

Regular web app scenario which needs to authenticate users using OpenID Connect (OIDC) single sign-on.

In this scenario, we will build a web application for a fictitious company named ExampleCo. The app is meant to be used by ExampleCo's employees and contractors. Employees will use their existing corporate directory (Active Directory), while contractors will be managed in a separate user store.

<Info>
  ### TL;DR

  * Auth0 supports open standards such as OAuth 2.0 and <Tooltip href="/docs/glossary?term=OpenID+Connect+%28OIDC%29">OpenID Connect (OIDC)</Tooltip> for authentication and authorization (see [Which protocol to use](/docs/get-started/architecture-scenarios/sso-for-regular-web-apps/part-1#which-protocol-to-use))
  * OIDC supports several different authorization flows - the most appropriate one for Web Applications being the Authorization Code Flow (see [Authentication Flow](/docs/get-started/architecture-scenarios/sso-for-regular-web-apps/part-1#authentication-flow))
  * Your application will be configured in Auth0 as an application (see [Application](/docs/get-started/architecture-scenarios/sso-for-regular-web-apps/part-2#application))
  * Identity Providers will be configured in Auth0 as a Connection (see [Connections](/docs/get-started/architecture-scenarios/sso-for-regular-web-apps/part-2#connections))
  * Auth0 provides a Lock widget, which allow users to log in to the application (see [User Login](/docs/get-started/architecture-scenarios/sso-for-regular-web-apps/part-3#user-login))
  * The web application needs to manage session state to keep track of the fact that the user is logged in. Along with this, Auth0 and the Identity Provider is also managing session information. (see [Session Management](/docs/get-started/architecture-scenarios/sso-for-regular-web-apps/part-3#session-management))
  * Conversely, logging a user out also involves three layers of session management (see [User Logout](/docs/get-started/architecture-scenarios/sso-for-regular-web-apps/part-3#user-logout))
  * Access Control can be managed with the Auth0 Authorization Extension (see [Access Control](/docs/get-started/architecture-scenarios/sso-for-regular-web-apps/part-3#access-control))
</Info>

<Callout icon="file-lines">
  By Regular Web App, we mean an app that uses primarily server side, page `GET`, `POST`, and cookies for maintaining state. This is contrast with a Web SPA (Single-Page App), that heavily relies on client side JavaScript code calling an API.
</Callout>

## The Premise

ExampleCo is a consulting startup company. Currently they have approximately 100 employees and they also outsource several activities to external contractors. Most of the employees work from the company's main office, but there are some teams that work remotely. Additionally, some employees frequently travel to customer locations and work from mobile devices.

All employees and external contractors are required to fill in their timesheets every week using spreadsheets. The current system is inefficient and the company decided that they need to move to a better and more automated solution.

The company evaluated several of the available timesheets application and concluded that it would be more cost-effective to build their own in-house solution, since they are looking for a very simple application at the moment. The app will be built using ASP.NET Core, since their developers are already using this technology and they can have the app ready in a week or so.

### Goals & Requirements

ExampleCo wants to launch the new solution quickly so they chose to start simple and build into it as they gather feedback from their employees.

The application should be available to logged in users only. Each user will have a role, and based on this role, they should be able to perform certain actions and view specific data.

<Info>
  ### Authentication vs Authorization

  ExampleCo wants to **authenticate** and **authorize** each user. Authentication has to do with identity: verifying that the user is indeed who they claim to be. Authorization is about deciding which resources a user should have access to, and what they should be allowed to do with those resources.
</Info>

ExampleCo's timesheets app needs to support two roles: User and Admin:

* Someone with the User role can add timesheet entries, by specifying the date, the application and the hours worked. The Admin role also has this same right.
* Those with the User role should have access only to their own timesheets entries.
* Someone with the Admin role can additionally:

  * Approve or reject timesheet entries of other users.
  * Edit the application drop-down list of values (add, edit, delete).

Each user will be required to fill in their timesheets by the end of the week. They can either choose to register daily their timesheets or add the entries for the whole week together. The timesheets will have to be reviewed and approved by an Admin. The rejected entries will have to be updated by each employee and re-submitted for approval.

The company uses Active Directory for all employees and employees will sign into the Timesheet application using their Active Directory credentials. The external contractors can sign in with a username and password. Contractors are not on ExampleCo's corporate directory.

ExampleCo wants to minimize user login burden, but wants to maintain a level of security depending on the operation: submitting timesheet entries is lower risk than approving them. However the approved timesheets are used for customer charging so security is definitely a requirement. The authentication strategy should be flexible so it can adapt as the company grows. For example, they should easily be able to add additional authentication requirements, like <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip>, for Admins.

The solution should be available both to the employees with a physical presence in the company office, as well as to those working remotely, without the overhead of a VPN connection, hence the app should be deployed on a cloud provider like Heroku or Microsoft Azure.

<Frame>
  <img alt="Diagram of the solution" />
</Frame>

## Learn more

* [Solution Overview (Web Apps + SSO)](/docs/get-started/architecture-scenarios/sso-for-regular-web-apps/part-1)
* [Auth0 Configuration (Web Apps + SSO)](/docs/get-started/architecture-scenarios/sso-for-regular-web-apps/part-2)
* [Application Implementation (Web Apps + SSO)](/docs/get-started/architecture-scenarios/sso-for-regular-web-apps/part-3)
* [ASP.NET Core Implementation (Web Apps + SSO)](/docs/get-started/architecture-scenarios/sso-for-regular-web-apps/implementation-aspnetcore)
* [Conclusion (Web Apps + SSO)](/docs/get-started/architecture-scenarios/sso-for-regular-web-apps/part-4)


# ASP.NET Core Implementation (Web Apps + SSO)
Source: https://auth0.com/docs/get-started/architecture-scenarios/sso-for-regular-web-apps/implementation-aspnetcore

The ASP.NET Core implementation for the Single Sign-on (SSO) for Regular Web Apps architecture scenario

Full source code for the ASP.NET Core implementation can be found in [this GitHub repository](https://github.com/auth0-samples/auth0-pnp-webapp-oidc).

## Configure the Cookie and OIDC Middleware

For the purposes this guide we will be using a simple hosted login. You can use the standard cookie and OIDC middleware which is available with ASP.NET Core, so ensure that you install the NuGet packages.

```bash lines theme={null}
Install-Package Microsoft.AspNetCore.Authentication.Cookies
Install-Package Microsoft.AspNetCore.Authentication.OpenIdConnect
```

Then configure the cookie and OIDC middleware inside your application's middleware pipeline.

<AuthCodeBlock />

As you can see in the code above, we have configured two different types of authentication middleware.

The first is the cookie middleware which was registered with the call to `UseCookieAuthentication`. The second is the OIDC middleware which is done with the call to `UseOpenIdConnectAuthentication`.

Once the user has signed in to Auth0 using the OIDC middleware, their information will automatically be stored inside a <Tooltip href="/docs/glossary?term=session+cookie">session cookie</Tooltip>. All you need to do is to configure the middleware as above and it will take care of managing the user session.

The <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) middleware will also extract all the claims from the <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip>, which is sent from Auth0 once the user has authenticated, and add them as claims on the `ClaimsIdentity`.

## Implement the Logout

You can control both the application session and the Auth0 session using the `SignOutAsync` method of the `AuthenticationManager` class, and passing along the authentication scheme from which you want to sign out.

As an example to sign out of the cookie middleware, and thereby clearing the authentication cookie for your application, you can make the following call:

```csharp wrap lines theme={null}
await HttpContext.Authentication.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
```

Similarly you can log the user out from Auth0 by making a call to the `SignOutAsync` method and passing along `Auth0` as the authentication scheme to sign out of.

```csharp lines theme={null}
await HttpContext.Authentication.SignOutAsync("Auth0");
```

For the above to work you will however also need to add extra configuration when registering the OIDC middleware by handling the `OnRedirectToIdentityProviderForSignOut` event. Inside the event you will need to redirect to the [Auth0 logout endpoint](https://auth0.com/docs/api/authentication/reference#logout) which will clear the Auth0 cookie.

```csharp lines theme={null}
app.UseOpenIdConnectAuthentication(new OpenIdConnectOptions("Auth0")
{
    // Some code omitted for brevity
    Events = new OpenIdConnectEvents
    {
        OnRedirectToIdentityProviderForSignOut = context =>
        {
            context.Response.Redirect($"https://{auth0Settings.Value.Domain}/v2/logout?client_id={auth0Settings.Value.ClientId}&returnTo={context.Request.Scheme}://{context.Request.Host}/");
            context.HandleResponse();

            return Task.FromResult(0);
        }
    }
});
```

You will also need to ensure that you add your application's URL to the **Allowed Logout URLs** for your application inside the <Tooltip href="/docs/glossary?term=Auth0+dashboard">Auth0 dashboard</Tooltip>. For more information refer to [Logout](/docs/authenticate/login/logout).

## Implement Admin permissions

The easiest way to integrate the groups into an ASP.NET Core application is to use the built-in [Role-based Authorization](https://docs.asp.net/en/latest/security/authorization/roles.html) available in ASP.NET Core. In order to achieve this we will need to add a Claim of type

```http lines theme={null}
http://schemas.microsoft.com/ws/2008/06/identity/claims/role
```

for each of the groups a user is assigned to.

Once the claims has been added we can easily ensure that a specific action is available only to `Admin` users by decorating the claim with the `[Authorize(Roles = "Admin")]` attribute. You can also check whether a user is in a specific role from code by making a call to `User.IsInRole("Admin")` from inside your controller.

The ASP.NET OIDC middleware will automatically add all claims returned in the <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> as claims to the `ClaimsIdentity`. We would therefore need to extract the information from the `authorization` claim, deserialize the JSON body of the claim, and for each of the groups add a `http://schemas.microsoft.com/ws/2008/06/identity/claims/role` claim to the `ClaimsIdentity`.

```csharp lines expandable theme={null}
app.UseOpenIdConnectAuthentication(new OpenIdConnectOptions("Auth0")
{
    // Some configuration omitted for brevity

    Events = new OpenIdConnectEvents
    {
        OnTicketReceived = context =>
        {
            var options = context.Options as OpenIdConnectOptions;

            // Get the ClaimsIdentity
            var identity = context.Principal.Identity as ClaimsIdentity;
            if (identity != null)
            {
                // Add the groups as roles
                var authzClaim = context.Principal.FindFirst(c => c.Type == "authorization");
                if (authzClaim != null)
                {
                    var authorization = JsonConvert.DeserializeObject<Auth0Authorization>(authzClaim.Value);
                    if (authorization != null)
                    {
                        foreach (var group in authorization.Groups)
                        {
                            identity.AddClaim(new Claim(ClaimTypes.Role, group, ClaimValueTypes.String, options.Authority));
                        }
                    }
                }
            }

            return Task.FromResult(0);
        }
    }
});
```

And subsequently we can add an action which allows Administrators to approve timesheets:

```csharp lines theme={null}
[Authorize(Roles = "Admin")]
public IActionResult TimesheetApproval()
{          
    return View();
}
```


# Solution Overview (Web Apps + SSO)
Source: https://auth0.com/docs/get-started/architecture-scenarios/sso-for-regular-web-apps/part-1

Regular web app scenario solution overview.

In this section, we'll cover the solution we're implementing, including details on identity management, protocols to use, and the authentication flow required.

## Identity Management

ExampleCo decided to use Auth0 as their Identity as a Service (IDaaS) provider. The reasoning behind this decision was that the company did not want to commit resources on training, implementation and maintenance of identity and access management. Furthermore, the company plans on building into this solution in the future, possibly adding a mobile native app and an API to push approved timesheets to their internal systems. Auth0 provides the flexibility to incorporate such changes in their architecture with minimum effort.

<Callout icon="file-lines">
  Identity-as-Service ("IDaaS") is a cloud-based service for identity and access management. The offered services often include Single Sign-on (SSO), federated identity, password management, and more.
</Callout>

## Which protocol to use

The next decision has to do with which protocol to use, <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> with <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) or <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip>.

<Callout icon="file-lines">
  Auth0 implements proven, common and popular identity protocols, both for consumer oriented web products (OAuth 2.0, OAuth 1.0, OpenID) and for enterprise deployments (SAML, WS-Federation, LDAP). You have complete freedom to use the one that best meets your business needs.
</Callout>

**OpenID Connect** is an authentication protocol, based on the OAuth 2.0 family of specifications. It uses simple JSON <Tooltip href="/docs/glossary?term=identity+tokens">identity tokens</Tooltip> (<Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip>) delivered via the OAuth 2.0 protocol.

<Info>
  ### OAuth vs OpenID Connect (OIDC)

  OAuth 2.0 and OpenID Connect (OIDC) are often mistaken for the same thing, but this is not exact.
  **OAuth 2.0** is a protocol that lets you authorize one website (the consumer or application) to access your data from another website (the resource server or provider). For example, you want to authorize a website to access some files from your Dropbox account. The website will redirect you to Dropbox which will ask you whether it should provide access to your files. If you agree the website will be authorized to access your files from Dropbox. At the core, OAuth 2.0 is about resource access and sharing.
  **OpenID Connect**, on the other hand, is a simple identity layer built on top of the OAuth 2.0 protocol. It gives you one login for multiple sites. Each time you need to log in to a website using OIDC, you are redirected to your OpenID site where you login, and then taken back to the website. At the core, OIDC is concerned with user authentication.
</Info>

**SAML** is an XML-based protocol, that provides both authentication and authorization between trusted parties.

Compared to SAML, OpenID Connect is lighter weight and simpler to deal with. SAML is proven, powerful and flexible, but for the requirements of this app, that flexibility and power is not required. Identity federation (one of the most compelling reasons for adopting SAML) is not required here either, And if it ever became a requirement, it can be easily handled by Auth0, in the same way it deals with AD (that uses LDAP).

For these reasons, ExampleCo will use OpenID Connect for their implementation.

## Authentication Flow

OpenID Connect supports more than one flow for authentication. Since our scenario involves a regular web app we will use the Authorization Code Flow.

The flow goes as follows:

1. The web app (called the Client in OIDC terms) initiates the authentication request by redirecting the user-agent (browser) to Auth0 (the Authorization Server in OIDC terms).
2. Auth0 authenticates the user (via the user-agent). The first time the user goes through this flow a consent page will be shown where the permissions that will be given to the Application are listed (for example, post messages, list contacts). The user logs in to the service (unless they are already logged in) and authorizes the application access.
3. Assuming the user grants access, Auth0 redirects the user-agent back to the Application, along with an authorization code in the query string.
4. The Application sends the authorization code to Auth0, along with the application credentials (client\_id and client\_secret), and asks for a token.
5. Auth0 authenticates the Application (using the client\_id and client\_secret) and validates the authorization code. If valid, Auth0 responds back with an ID Token.

<Frame>
  <img alt="undefined" />
</Frame>

<Info>
  ### Form Post Response Mode

  Another option is to use the **OAuth 2.0 Form Post Response Mode** with `response_type=id_token&response_mode=form_post`. Due to the `response_type=id_token` request parameter, the response contains the ID Token directly, instead of the authorization code, while the `response_mode=form_post` encodes the ID Token with the rest of the Authorization Response parameters as HTML form values that are auto-submitted in the User Agent. This way you can have an optimized authentication flow (no need to exchange the code for an ID Token), however you have to make sure that it is supported by the technology you are using to implement your app (ASP .NET Core middleware does support it). For more details refer to the [OAuth 2.0 Form Post Response Mode specification](https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html).
</Info>

The **ID Token** (usually referred to as `id_token` in code samples) is a **JSON Web Token (JWT)** that contains identity data. It is consumed by the application and used to get user information like the user's name, email, and so forth, typically used for UI display.

<Info>
  ### More on tokens

  Tokens are alphanumeric strings used in token-based authentication. They allow users to authenticate with a username and password once and get a token in return which they can use from that point on. They have a limited lifetime duration.

  **JSON Web Tokens (JWTs)** are tokens that conform to the [JSON Web Token Standard](https://tools.ietf.org/html/rfc7519) and contain information about an identity in the form of claims. They are self-contained in that it is not necessary for the recipient to call a server to validate the token. JWTs can be signed using a secret (with the **HMAC** algorithm) or a public/private key pair using **RSA**. You can find more information on JWT [here](/docs/secure/tokens/json-web-tokens).

  The ID Token, which is a JWT, conforms to an industry standard (IETF [RFC 7519](https://tools.ietf.org/html/rfc7519)) and contains three parts: A header, a body and a signature.

  * The header contains the type of token and the hash algorithm used on the contents of the token.
  * The body, also called the payload, contains identity claims about a user. There are some claims with registered names, for things like the issuer of the token, the subject of the token (who the claims are about), and the time of issuance. Any number of additional claims with other names can be added, though care must be taken to keep the JWT within the browser size limitations for URLs.
  * The signature is used by the recipient of a JWT to validate the integrity of the information conveyed in the JWT.
</Info>

### How to validate an ID Token

The validation of an ID Token requires several steps:

1. If the ID Token is encrypted, decrypt it using the keys and algorithms that the Application specified.
2. The Issuer Identifier for the OpenID Provider must match the value of the `iss` (issuer) claim.
3. The `aud` (audience) claim should contain the Application's `client_id` value. The ID Token must be rejected if the ID Token does not list the Application as a valid audience, or if it contains additional audiences not trusted by the Application.
4. If the ID Token contains multiple audiences, the Application should verify that an `azp` claim is present.
5. If an `azp` (authorized party) claim is present, the Application should verify that its `client_id` is the claim value.
6. The Application must validate the signature of ID Tokens according to JWS using the algorithm specified in the JWT `alg` header parameter. The Application must use the keys provided by the Issuer.
7. The `alg` value should be the default of `RS256` or the algorithm sent by the Application in the `id_token_signed_response_alg` parameter during registration.
8. If the JWT `alg` header parameter uses a MAC based algorithm such as `HS256`, `HS384`, or `HS512`, the octets of the UTF-8 representation of the `client_secret` corresponding to the `client_id` contained in the `aud` (audience) claim are used as the key to validate the signature. For MAC based algorithms, the behavior is unspecified if the `aud` is multi-valued or if an `azp` value is present that is different than the `aud` value.
9. The current time must be before the time represented by the `exp` claim.
10. The `iat` claim can be used to reject tokens that were issued too far away from the current time, limiting the amount of time that nonces need to be stored to prevent attacks. The acceptable range is Application specific.
11. If a `nonce` value was sent in the Authentication Request, a `nonce` claim must be present and its value checked to verify that it is the same value as the one that was sent in the Authentication Request. The Application should check the `nonce` value for replay attacks. The precise method for detecting replay attacks is Application specific.
12. If the `acr` claim was requested, the Application should check that the asserted claim value is appropriate.
13. If the `auth_time` claim was requested, either through a specific request for this claim or by using the `max_age` parameter, the Application should check the `auth_time` claim value and request re-authentication if it determines too much time has elapsed since the last End-User authentication.

<Callout icon="file-lines">
  If you store ID Tokens on your server, you must do so securely.
</Callout>


# Auth0 Configuration (Web Apps + SSO)
Source: https://auth0.com/docs/get-started/architecture-scenarios/sso-for-regular-web-apps/part-2

Regular web app scenario configuration for Auth0

In this section, we will review all the configurations we need to apply using the [Auth0 Dashboard](https://manage.auth0.com/#).

## Application

The Auth0 configuration part starts with registering the timesheets app at the <Tooltip href="/docs/glossary?term=Auth0+dashboard">Auth0 dashboard</Tooltip> as an **application**. An application is making protected resource requests on behalf of the <Tooltip href="/docs/glossary?term=resource+owner">resource owner</Tooltip> (end-user).

<Callout icon="file-lines">
  The term "application" does not imply any particular implementation characteristics. An application can be a web app, a mobile app or an SPA. In the case of ExampleCo it is a ASP.NET Core web app.
</Callout>

The main characteristics of an application in Auth0 are:

* **Name**: The canonical name of the application. This is used to identify the application at the portal, emails, logs, and more.
* **<Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>** (read-only): The unique identifier for the application. This is the ID used in the application when setting up authentication with Auth0. It is an auto-generated alphanumeric string.
* **<Tooltip href="/docs/glossary?term=Client+secret">Client secret</Tooltip>** (read-only): A string used to sign and validate tokens which will be used in the different authentication flows. It is auto-generated and it must be kept confidential.
* **Domain**: The domain name assigned to the Auth0 account. The format of the domain is `{account-name}.auth0.com` or `{account-name}.{location}.auth0.com`, for example `ExampleCo.auth0.com`.
* **Callback URL**: The URL where the user is redirected after they authenticate.

### Create an Application

ExampleCo's scenario involves only one application: the timesheets web app. Hence we have to configure one Application at Auth0 side.

To register a database connection, go to the [Dashboard](https://manage.auth0.com/#) and in the side navigation select [Applications](https://manage.auth0.com/#/applications).

Click on the button **+ Create Application**. You will be prompted for the name and the type of the application. We will name our application `Timesheet-App` and select `Regular Web Applications` as the application type.

When you click **Create** you will be navigated to the [Quick Start view](https://manage.auth0.com/#/applications/\{yourClientId}/quickstart). Here you can pick the technology you plan on using to build your app and the relevant how-to quickstart will be displayed.

The other available views are:

* [Settings](https://manage.auth0.com/#/applications/\{yourClientId}/settings)
* [Addons](https://manage.auth0.com/#/applications/\{yourClientId}/addons)
* [Connections](https://manage.auth0.com/#/applications/\{yourClientId}/connections)

### Configure Callback URLs

The **Allowed Callback URLs** field contains the URL(s) where Auth0 will redirect to after the user has authenticated in order for the <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) to complete the authentication process. You can specify multiple valid URLs by comma-separating them. You can use the star symbol as a wildcard for subdomains, for example `*.google.com`. Make sure to specify the protocol, `http://` or `https://`, otherwise the callback may fail in some cases.

The Callback URL for our sample project is `http://localhost:5000/signin-auth0`. Go ahead and set this value to the **Allowed Callback URLs** field if you plan on using our sample, otherwise add the URL you chose to deploy your application to.

## Connections

The next step is to configure the <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> that will be used for authentication at the web app. Each identity provides maps to a **connection** in Auth0. Each application needs at least one connection, and each connection can be used for more than one application.

ExampleCo needs to configure two connections: one Active Directory connection for the internal employees, and one Database connection for external parties.

<Info>
  ### Supported identity providers

  Auth0 supports a vast variety of protocols and identity providers:

  * Social: Allow your users to log in using Google, Facebook, LinkedIn, Github, and many more.
  * Enterprise: Allow your users to log in using Active Directory, ADFS, LDAP, <Tooltip href="/docs/glossary?term=SAML-P">SAML-P</Tooltip>, and many more.
  * Database connections: Create your own user store by configuring a new database connection, and authenticate your users using email/username and password. The credentials can be securely stored either in the Auth0 user store, or in your own database.
  * <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> authentication: Allow your users to login without the need to remember a password and use an authentication channel like SMS or email.
</Info>

### Create a database connection

To register a database connection, follow the steps below:

1. On the [Dashboard](https://manage.auth0.com/#), navigate to **Authentication > Database**.
2. Select **+ Create DB Connection**. On the prompt, enter a name for the connection and configure additional requirements as needed.
3. Review the prompt for accuracy, then select **Create**.

After you create the database connection, you must enable your applications for the connection. An application must be enabled for the connection in order for users to access that application using the connection. To enable your applications, navigate to the Applications tab of the new connection and enable the toggle for each application that requires use of the connection.

For more information on database connections refer to [Database Identity Providers](/docs/authenticate/database-connections).

### Create an Active Directory / LDAP Connection

Next, configure your Active Directory / LDAP connection. On the [Auth0 Dashboard](https://manage.auth0.com/#), navigate to **Authentication > Enterprise**.

There you need to create the AD / LDAP connection and install the AD Connector. You can find details in these documents:

* [How to connect your Active Directory with Auth0](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap)
* [How to install the Active Directory/LDAP Connector](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector)

<Callout icon="file-lines">
  The AD/LDAP Connector, is a bridge between your Active Directory and the Auth0 Service. This bridge is necessary because AD is typically locked down to your internal network, and Auth0 is a cloud service running on a completely different context. [More information](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector)
</Callout>

Once you have configured the connection and the connector, be sure to enable your application to use this AD / LDAP connection:

<Info>
  ### Kerberos support

  The AD/LDAP connector supports Kerberos to make it easer for your users to authenticate when they are on a domain-joined machine within the corporate network. To activate Kerberos on an Active Directory you have to simply enable the option in the dashboard. After enabling Kerberos you'll also be able to configure the **IP Ranges**. When users originate from these IP address ranges this information will be exposed in the SSO endpoint which means client-side SDKs like auth0.js and the Lock will be able to detect Kerberos support and allow Integrated Windows Authentication.
  [More information](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/configure-ad-ldap-connector-with-kerberos)

  <Callout icon="file-lines">
    If you enable Kerberos then you need to make some changes to the AD/LDAP's configuration file. For details refer to: [Modify the AD/LDAP Connector Settings](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-to-auth0).
  </Callout>
</Info>

Now that we have designed our solution and discussed the configurations needed on Auth0 side, we can proceed with integrating Auth0 with our timesheets web app.


# Application Implementation (Web Apps + SSO)
Source: https://auth0.com/docs/get-started/architecture-scenarios/sso-for-regular-web-apps/part-3

Regular web app scenario application implementation

Let's walk through the implementation of our regular web application. We used ASP .NET Core for the implementation, you can find the code in [this GitHub repository](https://github.com/auth0-samples/auth0-pnp-webapp-oidc).

The sample contains an application which uses Active Directory integration to authenticate company employees and an Auth0 database connection for external contractors. Authorization is implemented using rules and claims as we will see in detail in this paragraph.

## User Login

Auth0 provides a Lock widget which serves as a login component for your application, meaning that you do not have to implement your own login screen. The Lock widget seamlessly integrates with all of the connections you configure inside your <Tooltip href="/docs/glossary?term=Auth0+dashboard">Auth0 dashboard</Tooltip>, whether they be database, social or enterprise connections.

There are a number of different ways in which you can implement a Login screen using a web application and Auth0:

* **Hosted Lock**: Use an instance of the Lock widget which is hosted on the Auth0 infrastructure.
* **Embedded Lock**: Embed the Lock widget inside a web page of your application. You have some customization options for the actual Lock widget and full control over the rest of the HTML on the page.
* **Custom UI**: Develop a completely custom web page for the login screen. The custom HTML form will post back to your server which will, in turn, authenticate the user using the Authentication API. For more information on when to use a Custom UI, refer to [Customize Classic Login Pages with Lock or SDK](/docs/customize/login-pages/classic-login/customize-with-lock-sdk).

### Automate Home Realm Discovery (HRD)

By default, Lock will display all the connections available for login. Selecting the appropriate <Tooltip href="/docs/glossary?term=Identity+Providers">Identity Providers</Tooltip> from multiple options is called Home Realm Discovery (HRD). In our case, the options are either authenticating with Active Directory (for company employees) or using email/password for our database connection (external contractors).

You may however want to avoid that first step, where the user needs to choose the Identity Provider (IdP), and have the system identify it instead of asking every time. Lock offers you the following options:

* **Identify the IdP programmatically**: When you initiate an authentication transaction with Auth0 you can optionally send a `connection` parameter. This value maps directly with any connection defined in your dashboard. When using the Hosted version of Lock by calling the `/authorize` endpoint, you can pass along a `connection` query string parameter containing the name of the connection. Alternatively, if you are using Embedded Lock, this is as simple as writing `auth0.show({connections: ['{yourConnection}']});`.

  * There are multiple practical ways of getting the `connection` value. One of them is to use **vanity URLs**: for example, company employees will use `https://internal.yoursite.com`, while external contractors will use `https://external.yoursite.com`.
* **Use email domains**: Lock can use email domains as a way of routing authentication requests. Enterprise connections in Auth0 can be mapped to `domains`. If a connection has this setup, then the password textbox gets disabled automatically when typing an email with a mapped domain. Note that you can associate multiple domains to a single connection.

For additional information on this topic refer to [Select from Multiple Connection Options](/docs/libraries/lock/selecting-from-multiple-connection-options).

## Session Management

When talking about managing sessions, there are typically three layers of sessions we need to consider:

* **Application Session**: The first is the session inside the application. Even though your application uses Auth0 to authenticate users, you will still need to keep track of the fact that the user has logged in to your application. In a normal web application this is achieved by storing information inside a cookie.
* **Auth0 session**: Next, Auth0 will also keep a session and store the user's information inside a cookie. Next time when a user is redirected to the Auth0 Lock screen, the user's information will be remembered.
* **Identity Provider session**: The last layer is the Identity Provider, for example Facebook or Google. When you allow users to sign in with any of these providers, and they are already signed into the provider, they will not be prompted to sign in. They may simply be required to give permissions to share their information with Auth0 and in turn your application.

When developing a web application, you will therefore need to keep track of the fact that the user has logged in to your Web application. You can do this by making use of a cookie-based session to keep track of the fact that the user has signed in, and also store any of the user related information or tokens.

<Info>
  ### How do I control the duration of the user's local application session? Can I drive that from Auth0?

  The web app has full control over the user's local application session. How this is done usually depends on the web stack being used (for example, ASP.NET). Regardless, all approaches ultimately use one or more cookies to control the session. The developer can choose to use the expiration of the JWT ID Token returned by Auth0 to control their session duration or ignore it completely. Some developers store the ID Token itself in session state and end the user's session when it has expired.

  The reason why you would use the expiration of the token to determine the expiration of the local session is because it gives you centralized control of the duration of a user session from the Auth0 Dashboard.
</Info>

The login flow is as follows:

<Frame>
  <img alt="undefined" />
</Frame>

1. **Initiate OIDC Authentication Flow**: The user's browser will send a request to Auth0 to initiate the OIDC flow.
2. **Set SSO Cookie**: Auth0 will set a cookie to store the user's information.
3. **Code exchange and return ID Token**: Auth0 will make a request back to the web server and return the code. The web server will exchange the code for an ID Token.
4. **Set auth cookie and send response**: The web server will send a response back to the browser and set the application authentication cookie to store the user's session information.
5. **Auth cookie sent with every subsequent request**: The application authentication cookie will be sent on every subsequent request as proof that the user is authenticated.

<Info>
  ### How does Auth0's SSO session impact the application's session?

  Auth0 manages its own single-sign-on session. Applications can choose to honor or ignore that SSO session when it comes to maintaining their own local session. The Lock widget even has a special feature where it can detect if an Auth0 SSO session exists and ask the user if they wish to log in again as that same user.

  <Frame>![Lock Widget SSO](https://cdn2.auth0.com/docs/1.14516.0/media/articles/architecture-scenarios/web-app-sso/sso-login.png)</Frame>

  If they do so, they are signed in without having to re-enter their credentials with the actual IDP. Even though the user didn't authenticate, the application still performs an authentication flow with Auth0 and obtains a new ID Token, which can be used to then manage the new local application session.
</Info>

**See the implementation in** [**ASP.NET Core**](/docs/get-started/architecture-scenarios/sso-for-regular-web-apps/implementation-aspnetcore#configure-the-cookie-and-oidc-middleware).

## User Logout

When logging the user out, you will once again need to think about the three layers of sessions which we spoke about before:

* **Application Session**: You need to log out the user from your Web Application, by clearing their session.
* **Auth0 session**: You need to log out the user from Auth0. To do this you redirect the user to `https://{yourDomain}/v2/logout`. Redirecting the user to this URL clears all <Tooltip href="/docs/glossary?term=single+sign-on">single sign-on</Tooltip> cookies set by Auth0 for the user.
* **Identity Provider session**: Although this is not common practice, you can force the user to log out from the Identity Provider used, for example Facebook or Google. To do this add a `federated` query string parameter to the logout URL: `https://{yourDomain}/v2/logout?federated`.

To redirect a user after logout, add a `returnTo` query string parameter with the target URL as the value: `https://{yourDomain}/v2/logout?returnTo=http://www.example.com`. Note, that you will need to add the `returnTo` URL as an **Allowed Logout URLs**. For more information on how to implement this refer to: [Logout](/docs/authenticate/login/logout).

The logout flow (not including federated logout) is as follows:

<Frame>
  <img alt="undefined" />
</Frame>

1. **Initiate Logout Flow**: The logout flow will be initiated from the browser, for example by the user clicking a **Logout** link. A request will be made to the web server.
2. **Clear user’s local session**: The user's Application Session / Cookie will be cleared.
3. **Redirect browser to Auth0 Logout**: The user's browser will be redirected to the Auth0 Logout URL.
4. **Clear SSO Cookie**: Auth0 will clear the user's SSO Cookie.
5. **Redirect to post-logout URL**: Auth0 will return a redirect response and redirect the user's browser to the `returnTo` query string parameter.

**See the implementation in** [**ASP.NET Core**](/docs/get-started/architecture-scenarios/sso-for-regular-web-apps/implementation-aspnetcore#implement-the-logout).

## Access Control

Authorization refers to the process of determining what actions a user can perform inside your application.

You can either implement authorization directly inside your application, independently of Auth0, or use one of the available ways to retrieve the user authorization levels, put them as authorization claims inside the <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip> and validate these claims inside your application, once you retrieve the token, to control access.

There are various ways in which you can retrieve and set the user authorization claims when using Auth0:

* By configuring and using the [Auth0 Authorization Extension](/docs/customize/extensions/authorization-extension).
* By using Active Directory groups. These can be used in combination with the Authorization Extension by mapping Active Directory Groups to Groups you define using the Authorization extension.
* Add metadata to the user's profile by making use of [rules](/docs/customize/rules).
* By calling an external services from inside a rule.

Since in our case the company has already Active Directory set up, we will enforce access control using the Authorization Extension in combination with Active Directory groups.

<Card title="Authorization extension">
  At this point in time the authorization extension is primarily designed to enforce coarse-grained authorization, for example to control access to an application based on a user's group membership. It is not necessarily designed to control fine-grained access (such as whether a user can perform a specific action inside the application), even though this is how we are utilizing it in this instance.
</Card>

All users will implicitly be regular users, but timesheet administrators will be assigned to an `Admin` group which will allow them to approve timesheets. The Authorization Extension allows for mapping groups to existing group membership.

All timesheet administrators will be assigned to the `Timesheet Administrators` group on Active Directory, which will be automatically mapped to the `Admin` group inside the Timesheet Application.

When you install the Authorization Extension, it creates a rule in the background, which does the following:

1. Determine the user's group membership.
2. Store the user's group membership info as part of the `app_metadata`.
3. Add the user's group membership to the outgoing token.
4. Verify that the user has been granted access to the current application.

### Install the Authorization Extension

To install the Authorization extension navigate to the [Extensions](https://manage.auth0.com/#/extensions) view of your Auth0 Dashboard, and select and install the Auth0 Authorization extension.

Once installed, you will see the app listed under Installed Extensions.

When you click on the link to open the extension for the first time, you will be prompted to provide permission for the extension to access your Auth0 account. If you do so, you will be redirected to the Authorization Dashboard.

Once on the Authorization Dashboard, navigate to Groups in the navigation menu, and create a new group called Admin.

<Frame>
  <img alt="undefined" />
</Frame>

After the group has been added you can click on the new group to go to the group management section. Go to the Group Mappings tab and add a new group mapping which will map all Active Directory users in the `Timesheet Admins` groups to the `Admin` group you just created.

<Frame>
  <img alt="undefined" />
</Frame>

Once you click **Save** you can see the new mapping listed.

<Frame>
  <img alt="undefined" />
</Frame>

With the mapping configured you only need to maintain membership to the `Timesheet Admins` group in Active Directory, and those users will be automatically mapped to the `Admin` group inside our application.

For more information refer to the [Authorization Extension documentation](/docs/customize/extensions/authorization-extension).

### Enforce permissions in your application

When you installed the Authorization Extension, it also created an Auth0 rule which will add an `authorization` claim with all the authorization related settings for a particular user. The groups for a user will be added as a sub-claim of the `authorization` claim called `groups` and all the groups a user belongs to will be added as an array to this claim. This is an example of what JSON payload of a ID Token may look like with the groups listed:

```json lines theme={null}
{
  "sub": "1234567890",
  "name": "John Doe",
  "authorization": {
    "groups": ["Admin"]
  }
}
```

In your application you will therefore need to decode the ID Token returned when a user is authenticated, and extract the groups which a user belongs to from the `authorization` claim. You can then store these groups, along with other user information inside the user's session, and subsequently query these to determine whether a user has permissions to perform a certain action based on their group membership.

<Callout icon="file-lines">
  See the implementation in [ASP.NET Core](/docs/get-started/architecture-scenarios/sso-for-regular-web-apps/implementation-aspnetcore#implement-admin-permissions).
</Callout>


# Conclusion (Web Apps + SSO)
Source: https://auth0.com/docs/get-started/architecture-scenarios/sso-for-regular-web-apps/part-4

Regular web app scenario conclusion

In this tutorial we covered a simple scenario: a regular web app, hosted in the cloud, using Auth0 for authentication, while utilizing the existing Active Directory user store. We learned what <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) offers and why it was preferable for this business case, how the Authentication Flow works, what an <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip> is and how to validate and manipulate it, how to configure applications and connections on <Tooltip href="/docs/glossary?term=Auth0+dashboard">Auth0 dashboard</Tooltip>, how to implement user login and logout using Lock, and how session management and access control works.

We started by describing the business case and the requirements and went on explaining how each requirement can be met and the thought process behind each choice that was made.

We used ASP .NET Core for the sample web app implementation, hopefully though after going through this document you are able to build such a web app using the framework you prefer.


# Authentication and Authorization Flows
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow

Learn about the various flows used for authentication and authorization of applications and APIs.

Auth0 uses the [OpenID Connect (OIDC) Protocol](/docs/authenticate/protocols/openid-connect-protocol) and [OAuth 2.0 Authorization Framework](/docs/authenticate/protocols/oauth) to authenticate users and get their authorization to access protected resources. With Auth0, you can easily support different flows in your own applications and APIs without worrying about OIDC/<Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> specifications or other technical aspects of [authentication and authorization](/docs/get-started/identity-fundamentals/authentication-and-authorization).

We support scenarios for server-side, mobile, desktop, client-side, machine-to-machine, and device applications.

If you're not sure which flow to use, we can help you decide. To learn more, read [Which OAuth 2.0 Flow Should I Use?](/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use).

<Callout icon="file-lines">
  During the execution of several flows, your application must also authenticate to the Authorization Server. To learn more about application authentication, read [Application Credentials](/docs/secure/application-credentials).
</Callout>

<Callout icon="file-lines">
  Depending on the application API access policies you configure for an API, you may need to create the corresponding client grants for your application. To learn more, read [Application Access to APIs: Policies and Client Grants](/docs/get-started/applications/application-access-to-apis-client-grants).
</Callout>

## Authorization Code Flow

Because regular web apps are server-side apps where the source code is not publicly exposed, they can use the Authorization Code Flow, which exchanges an Authorization Code for a token.

* [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow)
* [Add Login Using the Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/add-login-auth-code-flow)
* [Call API Using the Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/call-your-api-using-the-authorization-code-flow)

## Authorization Code Flow with Proof Key for Code Exchange (PKCE)

During authentication, mobile and native applications can use the Authorization Code Flow, but they require additional security. Additionally, single-page apps have special challenges. To mitigate these, OAuth 2.0 provides a version of the Authorization Code Flow which makes use of a Proof Key for Code Exchange (PKCE).

* [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce)
* [Add Login Using the Authorization Code Flow with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/add-login-using-the-authorization-code-flow-with-pkce)
* [Call API Using the Authorization Code Flow with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/call-your-api-using-the-authorization-code-flow-with-pkce)

## Authorization Code Flow with enhanced privacy protection

During the authentication and authorization process, some use cases such as [transactional authorization](/docs/secure/highly-regulated-identity/transactional-authorization-with-authorization-code-flow) exchange contextual information, which may contain sensitive data. To protect data and sensitive information, you can use different protocol improvements for the authorization code flow:

* [Authorization Code Flow with Rich Authorization Requests (RAR)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-rar)
* [Authorization Code Flow with Pushed Authorization Requests (PAR)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-par)
* [Authorization Code Flow with JWT-Secured Authorization Requests (JAR)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-jar)
* [JSON Web Encryption (JWE)](/docs/secure/tokens/access-tokens/json-web-encryption)

## Implicit Flow with Form Post

As an alternative to the Authorization Code Flow, OAuth 2.0 provides the Implicit Flow, which is intended for <Tooltip href="/docs/glossary?term=Public+Clients">Public Clients</Tooltip>, or applications which are unable to securely store <Tooltip href="/docs/glossary?term=Client+Secrets">Client Secrets</Tooltip>. While this is no longer considered a best practice for requesting <Tooltip href="/docs/glossary?term=Access+Tokens">Access Tokens</Tooltip>, when used with Form Post response mode, it does offer a streamlined workflow if the application needs only an <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> to perform user authentication.

* [Implicit Flow with Form Post](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post)
* [Add Login Using the Implicit Flow with Form Post](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post/add-login-using-the-implicit-flow-with-form-post)
* [Authenticate SPAs with Cookies](/docs/manage-users/cookies/spa-authenticate-with-cookies)

## Hybrid Flow

Applications that are able to securely store Client Secrets may benefit from the use of the Hybrid Flow, which combines features of the Authorization Code Flow and Implicit Flow with Form Post to allow your application to have immediate access to an ID token while still providing for secure and safe retrieval of access and <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip>. This can be useful in situations where your application needs to immediately access information about the user, but must perform some processing before gaining access to protected resources for an extended period of time.

* [Hybrid Flow](/docs/get-started/authentication-and-authorization-flow/hybrid-flow)
* [Call API Using the Hybrid Flow](/docs/get-started/authentication-and-authorization-flow/hybrid-flow/call-api-hybrid-flow)

## Client Credentials Flow

With machine-to-machine (M2M) applications, such as CLIs, daemons, or services running on your back-end, the system authenticates and authorizes the app rather than a user. For this scenario, typical authentication schemes like identifier + password or social logins don't make sense. Instead, M2M apps use the Client Credentials Flow (defined in OAuth 2.0 RFC 6749, section 4.4).

* [Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow)
* [Call API Using the Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow/call-your-api-using-the-client-credentials-flow)

## Device Authorization Flow

With input-constrained devices that connect to the internet, rather than authenticate the user directly, the device asks the user to go to a link on their computer or smartphone and authorize the device. This avoids a poor user experience for devices that do not have an easy way to enter text. To do this, device apps use the Device <Tooltip href="/docs/glossary?term=Authorization+Flow">Authorization Flow</Tooltip> (drafted in OAuth 2.0). For use with mobile/native applications.

* [Device Authorization Flow](/docs/get-started/authentication-and-authorization-flow/device-authorization-flow)
* [Call API Using the Device Authorization Flow](/docs/get-started/authentication-and-authorization-flow/device-authorization-flow/call-your-api-using-the-device-authorization-flow)

## Resource Owner Password Flow

Though we do not recommend it, highly-trusted applications can use the <Tooltip href="/docs/glossary?term=Resource+Owner">Resource Owner</Tooltip> Password Flow, which requests that users provide credentials (identifier and password), typically using an interactive form. The Resource Owner Password Flow should only be used when redirect-based flows (like the [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow)) cannot be used.

* [Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow)
* [Call API Using the Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow/call-your-api-using-resource-owner-password-flow)

## Client-Initiated Backchannel Authentication Flow

<Callout icon="file-lines">
  Client-Initiated Backchannel Authentication is currently in Early Access. To enable CIBA, contact your Technical Account Manager.
</Callout>

With the Client-Initiated Backchannel Authentication Flow (CIBA), rather than authenticate the user directly, the client application backend initiates an authentication flow to challenge the user for authentication. The authentication itself is performed on a separate authentication device, typically a smartphone running a custom app.

* [Client-Initiated Backchannel Authentication Flow](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow)
* [User Authentication with CIBA](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/user-authentication-with-ciba)
* [User Authorization with CIBA](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/user-authorization-with-ciba)

## Custom Token Exchange

Custom Token Exchange (CTE) enables applications to exchange pre-existing identity tokens for Auth0 tokens by invoking the `/oauth/token` endpoint, as defined in [RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693). For example, you can use the Custom Token Exchange to exchange Auth0 tokens to access another audience on the user’s behalf. To learn more about Custom Token Exchange use cases, read [Example Use Cases](/docs/authenticate/custom-token-exchange/cte-example-use-cases).

By associating a [Custom Token Exchange Profile](/docs/authenticate/custom-token-exchange/configure-custom-token-exchange) with an Action that contains custom logic, you can implement highly customized identity workflows by exchanging one security token for another, all while maintaining control over the authorization logic.


# Authenticate with mTLS
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/authenticate-with-mtls

Learn how to authenticate a client using mTLS.

## mTLS in OAuth/OIDC

Default <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip>/OIDC flows are not always secure because of the following issues:

* The use of a shared <Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip> as a form of client authentication.
* The ability for an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> to be used by unintended parties.

In 2020, the Internet Engineering Task Force (IETF) released [RFC 8705](https://www.rfc-editor.org/rfc/rfc8705) Mutual-TLS (mTLS) client authentication to address these issues. With mTLS authentication, the client certificate with a private key functions like a Client Secret in an OAuth/OIDC flow to verify the client’s identity. If a client is already authenticated at the network layer, there’s no need for a Client Secret at the application layer. Additionally, client certificates can be used with multiple servers to prove a client’s identity to a <Tooltip href="/docs/glossary?term=resource+server">resource server</Tooltip>. Note there are other approaches to solve the above issues, namely [Private Key JWT](/docs/get-started/authentication-and-authorization-flow/authenticate-with-private-key-jwt) and [DPoP](https://datatracker.ietf.org/doc/html/rfc9449) respectively.

To secure an OAuth flow with mTLS, clients send a mTLS certificate to the TLS termination point on the customer edge network when the TLS connection is being established. Before the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip> processes the request, it must first verify the client’s mTLS certificate.

<Frame>
  <img alt="" />
</Frame>

Optionally, mTLS can also be used to ensure an access token is used only by the intended party, known as Sender Constraining or Token Binding. When the client calls the `/oauth/token` endpoint on the authorization server using an mTLS connection, the resulting access token contains information that the resource server uses to verify that the client’s TLS certificate matches that of the access token.

<Frame>
  <img alt="" />
</Frame>

**Note**: mTLS client authentication and mTLS Token Binding can be used independently of each other. mTLS client authentication can be used without mTLS Token Binding, and mTLS Token Binding can be used with other forms of client authentication such as Client Secret or Private Key <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip>. Even if other forms of client authentication are used, the client still sends the client certificate to the authorization server for mTLS Token Binding.

## mTLS at Auth0

mTLS for Auth0 builds on [custom domains](/docs/customize/custom-domains) and leverages the customer’s existing mTLS infrastructure to perform certificate provisioning and verification.

Authenticated client calls to Auth0 that normally require a Client Secret are first sent to the customer edge. This already happens for <Tooltip href="/docs/glossary?term=custom+domains">custom domains</Tooltip> that use customer-managed certificates. The customer edge performs the mTLS handshake with the client and validates the client certificate. Once the client certificate is verified, the request is then forwarded to the tenant’s edge domain at Auth0, including the validated client certificate in an HTTP header along with the correct `cname-api-key` as per the custom domains functionality.

<Frame>
  <img alt="" />
</Frame>

## Call the authorization server

Since mTLS serves both client authentication and access token binding, the client must know whether these features are enabled on the authorization server. In addition, an authorization server’s mTLS endpoints and non-mTLS endpoints may be exposed on different domains.

To get configuration details about the authorization server, the client sends a GET request to the [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) endpoint: `https://<custom-domain>/.well-known/openid-configuration`

A successful response returns the OIDC discovery document, or a JSON object listing the authorization server’s properties and endpoints, including those related to mTLS.

If mTLS client authentication is enabled, the OIDC discovery document includes the `token_endpoint_auth_methods_supported` property, which contains either `tls_client_auth` or `self_signed_tls_client_auth`:

```json lines theme={null}
{
  ...
  "token_endpoint_auth_methods_supported": ["tls_client_auth"]
  ...
}
```

If mTLS Token Binding is enabled, the OIDC discovery document sets the  `tls_client_certificate_bound_access_tokens` property to `true:`

```json lines theme={null}
{
  ...
  "tls_client_certificate_bound_access_tokens": true
  ...
}
```

Environments that support mTLS endpoint aliases expose a new property, `mtls_endpoint_aliases`, that contains a list of endpoints that support mTLS. For clients that support mTLS, the endpoints listed under `mtls_endpoint_aliases` take precedence over the same endpoints exposed outside of `mtls_endpoint_aliases`.

In the following code sample, the `token_endpoint` property is exposed twice. The endpoint to use for mTLS calls is listed under `mtls_endpoint_aliases`, or `https://mtls.auth.bank.com/oauth/token`:

```json lines theme={null}
{
  ...
  "mtls_endpoint_aliases": {
"token_endpoint": "https://mtls.auth.bank.com/oauth/token"
  },
  "token_endpoint": "https://auth.bank.com/oauth/token",
  "pushed_authorization_request_endpoint": "https://auth.bank.com/oauth/par",
  ...
}
```

If an endpoint is not listed under `mtls_endpoint_aliases`, use the same endpoint listed outside of `mtls_endpoint_aliases`. In the example above, `pushed_authorization_request_endpoint` is not listed under `mtls_endpoint_aliases`. As a result, use the `pushed_authorization_request_endpoint` exposed outside of `mtls_endpoint_aliases`, or `https://auth.bank.com/oauth/par`.

For more information, see RFC 8705’s [section on endpoint aliases](https://www.rfc-editor.org/rfc/rfc8705#name-metadata-for-mutual-tls-end).

## Call the resource server

Once a client receives an access token, it can access protected resources on a resource server. If mTLS Token Binding is enabled, the authorization server returns the OIDC discovery document that contains the `tls_client_certificate_bound_access_tokens` property.

When the client calls the resource server with a mTLS-bound access token, the resource server requests a mTLS certificate from the client during the TLS handshake. The resource server should reject requests with an access token that does not match that client certificate with a 401 HTTP status code and an `invalid_token` error code. To learn more, read [Configure Resource Server for Sender Constraining](/docs/secure/sender-constraining/configure-sender-constraining/configure-resource-server-for-sender-constraining).

## Learn more

* [Configure mTLS Authentication](/docs/get-started/applications/configure-mtls)


# Authenticate with Private Key JWT
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/authenticate-with-private-key-jwt

Describes how to build an assertion to use Private Key JWT Authentication.

<Card title="Before you start">
  You need to create a new application in Auth0 Dashboard or convert an existing application before you continue. To learn more, read [Configure Private Key JWT Authentication](/docs/get-started/applications/configure-private-key-jwt).
</Card>

You need to complete two steps when authenticating with `private_key_jwt:`

1. Build the client assertion. This assertion is a JWT signed by the private key when you generated the key pair. To learn how to generate a key pair, read [Configure Private Key JWT Authentication](/docs/get-started/applications/configure-private-key-jwt).
2. Use the assertion to authenticate against Auth0.

## Build the assertion

You can use one of Auth0’s SDKs to build an assertion automatically for you. If you don’t use our SDKs, you will need to construct the assertion yourself.

The assertion is a <Tooltip href="/docs/glossary?term=JSON+Web+Token">JSON Web Token</Tooltip> (JWT) that should contain the following properties and claims:

<Callout icon="file-lines">
  All claims are required unless otherwise stated. To learn more about JWT claims, read [JSON Web Token Claims](/docs/secure/tokens/json-web-tokens/json-web-token-claims).
</Callout>

* Header

  * `alg`: The algorithm used to sign the assertion. The algorithm must match the algorithm specified when you created your application credential.
  * `kid`**:** (optional) The Auth0 generated `kid` of the credential. The `kid` is created when you created the credential.
* Payload

  * `iss`**:** Your application's Client ID. You can find this value in your application settings under [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/dashboard/#/applications/) and select the **Settings** tab.
  * `sub`**:** Your application's Client ID. You also can find this value in your application settings. You can find this value in your application settings under [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/dashboard/#/applications/) and select the **Settings** tab.
  * `aud`**:** The URL of the Auth0 tenant or custom domain that receives the assertion. For example: `https://{yourTenant}.auth0.com/`**.** Include the trailing slash.

    <Callout icon="file-lines">
      If you have configured a custom domain for your Auth0 tenant, this can be used as the `aud` claim. We recommend using the custom domain in this case.
    </Callout>
  * `iat` (optional), `nbf` (optional), and `exp`: Issued At, Not Before, and Expiration claims set to the correct timestamps. A clock skew of up to 10 seconds is allowed for `iat` and `nbf` (if present) to support inter-operability. The client assertion is a one-time use token, and we recommend the shortest possible expiry time. Auth0 supports a maximum of 5 minutes for the lifetime of a token.
  * `jti`: A unique claim ID created by the client. We recommend using the Universally Unique Identifier (UUID) format.

    <Warning>
      This JWT is a one-time use only token and should be considered as such by having a short expiry. We recommend setting a maximum of 1 minute.
    </Warning>

The token must then be signed with the private key you generated when you created or configured your application for Private Key JWT Authentication. To learn how, review the [JSON Web Token specification](https://www.rfc-editor.org/rfc/rfc7519#section-7.1).

We recommend you construct the token using standard tooling or third party libraries that support this functionality out of the box, rather than implementing from scratch yourself.  To learn more about supporting libraries, read the listing at [JWT.io](https://jwt.io/libraries).

### Example

In the example below, the Node.js script uses a [jose package](https://github.com/panva/jose) to generate the assertion:

```javascript lines expandable theme={null}
const { SignJWT } = require('jose')
const crypto = require("crypto");
const uuid = require("uuid");

async function main() {
 const privateKeyPEM = crypto.createPrivateKey(/**
   Read the content of your private key here. We recommend to store your private key
   in a secure infrastructure. 
 */);

 const jwt = await new SignJWT({})
   .setProtectedHeader({ 
      alg: 'RS256', // or RS384 or PS256
      kid: '(OPTIONAL) KID_GENERATED_BY_AUTH0' 
   })
   .setIssuedAt()
   .setIssuer('CLIENT_ID')
   .setSubject('CLIENT_ID')
   .setAudience('https://YOUR_TENANT.auth0.com/') // or your CUSTOM_DOMAIN
   .setExpirationTime('1m')
   .setJti(uuid.v4())
   .sign(privateKeyPEM);
  console.log(jwt)
}

main();
```

Example client assertion signed with a private key:

<Frame>
  <img alt="private key example" />
</Frame>

Corresponds to:

```json lines theme={null}
{
  "alg": "RS256",
  "kid": "my kid"
}
{
  "iat": 1626684584,
  "iss": "my client id",
  "sub": "my client id",
  "aud": "https://mytenant.auth0.com/",
  "exp": 1626684644,
  "jti": "e4dc8ed1-b108-4901-8bbc-c07a791817e7"
}
```

After you generate the JWT with the required information, you are ready to authenticate your application against Auth0.

## Exchange assertion for access tokens

<Callout icon="file-lines">
  The following example uses the [Client Credential Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow). Private Key JWT authentication can be used for other grant types that also allow replacing `client_secret` with `client_assertion`.
</Callout>

To exchange the JWT assertion for an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, call the Authentication API [token endpoint](https://auth0.com/docs/api/authentication#authenticate-user) with the following parameters:

* `$client_assertion`: JWT assertion
* `$resource_server_identifier`: <Tooltip href="/docs/glossary?term=resource+server">resource server</Tooltip> identifier. To learn more, read [Register APIs](/docs/get-started/auth0-overview/set-up-apis).

```bash lines theme={null}
curl --location --request POST 'https://$tenant/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
  --data-urlencode 'client_assertion=$client_assertion' \
  --data-urlencode 'audience=$resource_server_idenifier'
```

## Supported endpoints

In addition to the [https://\$tenant/oauth/token](https://auth0.com/docs/api/authentication#get-token) endpoint, the following Auth0 Authentication API endpoints support `private_key_jwt` authentication for configured applications:

* [POST /oauth/revoke](https://auth0.com/docs/api/authentication#revoke-refresh-token)
* [POST /mfa/challenge](https://auth0.com/docs/api/authentication#challenge-request)
* [POST /passwordless/start](https://auth0.com/docs/api/authentication#get-code-or-link)

## Assertion limits

The maximum length of the JWT assertion is 2048 bytes.

Claims within the assertion have the following limits:

* `iss`: 64 characters
* `sub`: 64 characters
* `jti`: 64 characters
* `alg`: 16 characters


# Authorization Code Flow
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow

Learn how the Authorization Code flow works and why you should use it for regular web apps.

The Authorization Code Flow (defined in [OAuth 2.0 RFC 6749, section 4.1](https://tools.ietf.org/html/rfc6749#section-4.1)), involves exchanging an authorization code for a token.

This flow can only be used for confidential applications (such as Regular Web Applications) because the application's authentication methods are included in the exchange and must be kept secure.

## How Authorization Code Flow works

<Frame>
  <img alt="Auth - Auth code flow- Authorization sequence diagram" />
</Frame>

1. User selects **Login** within application.
2. Auth0's SDK redirects user to Auth0 Authorization Server ([`/authorize`](https://auth0.com/docs/api/authentication/authorization-code-flow/authorize-application) endpoint).
3. Auth0 Authorization Server redirects user to login and authorization prompt.
4. User authenticates using one of the configured login options, and may see a consent prompt listing the permissions Auth0 will give to the application.
5. Auth0 Authorization Server redirects user back to application with single-use authorization code.
6. Auth0's SDK sends authorization code, application's client ID, and application's credentials, such as client secret or Private Key JWT, to Auth0 Authorization Server ([`/oauth/token`](https://auth0.com/docs/api/authentication/authorization-code-flow/get-token) endpoint).
7. Auth0 Authorization Server verifies authorization code, application's client ID, and application's credentials.
8. Auth0 Authorization Server responds with an ID token and access token (and optionally, a refresh token).
9. Application can use the access token to call an API to access information about the user.
10. API responds with requested data.

## How to implement Authorization Code Flow

The easiest way to implement the Authorization Code Flow is to follow our [Regular Web App Quickstarts](/docs/quickstart/webapp).

Alternatively, you can use the Authentication API to implement the Authorization Code Flow. For more information, read [Add Login Using the Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/add-login-auth-code-flow) or [Call Your API Using the Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/call-your-api-using-the-authorization-code-flow).

<Callout icon="file-lines">
  If a browser application, with an Origin header, makes a `POST` request to the `/oauth/token` endpoint, Auth0 doesn’t issue refresh tokens, even if the application has [Allow Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/configure-refresh-token-rotation) enabled and sends the [offline\_access](/docs/secure/tokens/refresh-tokens/configure-refresh-token-rotation#configure-with-the-auth0-spa-sdk) scope.
</Callout>

## Learn more

* [Auth0 Rules](/docs/customize/rules)
* [Auth0 Hooks](/docs/customize/hooks)
* [Tokens](/docs/secure/tokens)
* [Token Best Practices](/docs/secure/tokens/token-best-practices)
* [Which OAuth 2.0 Flow Should I Use?](/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use)


# Authorization Code Flow with Proof Key for Code Exchange (PKCE)
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce

Learn how the Authorization Code flow with Proof Key for Code Exchange (PKCE) works and why you should use it for native and mobile apps.

<Card title="Overview">
  Key Concepts

  * Learn about the OAuth 2.0 grant type, Authorization Code Flow with Proof Key for Code Exchange (PKCE).
  * Use this grant type for applications that cannot store a client secret, such as native or single-page apps.
  * Review different implementation methods with Auth0 SDKs.
</Card>

When <Tooltip href="/docs/glossary?term=public+clients">public clients</Tooltip> (e.g., native and single-page applications) request <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip>, some additional security concerns are posed that are not mitigated by the Authorization Code Flow alone. This is because:

**Native apps**

* Cannot securely store a <Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip>. Decompiling the app will reveal the <Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip>, which is bound to the app and is the same for all users and devices.
* Are vulnerable to authorization code interception and injection attacks. Without a client secret, an attacker who intercepts the authorization code can exchange it for tokens.
* May make use of a custom URL scheme to capture redirects (e.g., MyApp\://) potentially allowing malicious applications to receive an <Tooltip href="/docs/glossary?term=Authorization+Code">Authorization Code</Tooltip> from your <Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip>. Because of this risk, **Auth0 strongly discourages the use of custom URI schemes**. To learn more, read [Measures Against Application Impersonation](/docs/secure/security-guidance/measures-against-app-impersonation.mdx).

**Single-page apps**

* Cannot securely store a Client Secret because their entire source is available to the browser.

Given these situations, <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> provides a version of the Authorization Code Flow which makes use of a Proof Key for Code Exchange (PKCE) (defined in [OAuth 2.0 RFC 7636](https://tools.ietf.org/html/rfc7636)).

The PKCE-enhanced Authorization Code Flow introduces a secret created by the calling application that can be verified by the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip>; this secret is called the Code Verifier. Additionally, the calling app creates a transform value of the Code Verifier called the Code Challenge and sends this value over HTTPS to retrieve an Authorization Code. This way, a malicious attacker can only intercept the Authorization Code, and they cannot exchange it for a token without the Code Verifier.

## How it works

Because the PKCE-enhanced Authorization Code Flow builds upon the [standard Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow), the steps are very similar.

<Frame>
  <img alt="Flows - Authorization Code with PKCE - Authorization sequence diagram" />
</Frame>

1. The user clicks **Login** within the application.
2. Auth0's SDK creates a cryptographically-random `code_verifier` and from this generates a `code_challenge`.
3. Auth0's SDK redirects the user to the Auth0 Authorization Server ([`/authorize` endpoint](https://auth0.com/docs/api/authentication#authorization-code-grant-pkce-)) along with the `code_challenge`.
4. Your Auth0 Authorization Server redirects the user to the login and authorization prompt.
5. The user authenticates using one of the configured login options and may see a consent page listing the permissions Auth0 will give to the application.
6. Your Auth0 Authorization Server stores the `code_challenge` and redirects the user back to the application with an authorization `code`, which is good for one use.
7. Auth0's SDK sends this `code` and the `code_verifier` (created in step 2) to the Auth0 Authorization Server `(`[`/oauth/token` endpoint](https://auth0.com/docs/api/authentication?http#authorization-code-flow-with-pkce44)).
8. Your Auth0 Authorization Server verifies the `code_challenge` and `code_verifier`.
9. Your Auth0 Authorization Server responds with an ID token and access token (and optionally, a refresh token).
10. Your application can use the access token to call an API to access information about the user.
11. The API responds with requested data.

<Callout icon="file-lines">
  If you have [Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation) enabled, a new Refresh Token is generated with each request and issued along with the Access Token. When a Refresh Token is exchanged, the previous Refresh Token is invalidated but information about the relationship is retained by the authorization server.
</Callout>

## How to implement it

The easiest way to implement the Authorization Code Flow with PKCE is to [follow our Native Quickstarts](/docs/quickstart/native) or [follow our Single-Page Quickstarts](/docs/quickstart/spa).

Depending on your application type, you can also use our mobile or single-page app SDKs:

**Mobile**

* [Auth0 Swift SDK](/docs/libraries/auth0-swift)
* [Auth0 Android SDK](/docs/libraries/auth0-android)

**Single-page**

* [Auth0 Single-Page App SDK](/docs/libraries/auth0-single-page-app-sdk)
* [Auth0 React SDK](/docs/libraries/auth0-react)

<Callout icon="file-lines">
  Recent advancements in user privacy controls in browsers adversely impact the user experience by preventing access to third-party cookies; therefore, browser-based flows must use [Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation), which provides a secure method for using refresh tokens in SPAs while providing end-users with seamless access to resources without the disruption in UX caused by browser privacy technology like ITP.
</Callout>

You can follow our tutorials to use our API endpoints to [Add Login Using the Authorization Code Flow with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/add-login-using-the-authorization-code-flow-with-pkce) or [Call Your API Using the Authorization Code Flow with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/call-your-api-using-the-authorization-code-flow-with-pkce).

## Learn more

* [Auth0 Rules](/docs/customize/rules)
* [Auth0 Hooks](/docs/customize/hooks)
* [Tokens](/docs/secure/tokens)
* [Token Best Practices](/docs/secure/tokens/token-best-practices)
* [Which OAuth 2.0 Flow Should I Use?](/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use)


# Add Login Using the Authorization Code Flow with PKCE
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/add-login-using-the-authorization-code-flow-with-pkce

Learn how to add login to your native, mobile, or single-page application using the Authorization Code Flow with Proof Key for Code Exchange (PKCE).

You can add login to your native, mobile, or single-page app using the Authorization Code Flow with PKCE. To learn how the flow works and why you should use it, read [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce). To learn how to call your API from a native, mobile, or single-page app, read [Call Your API Using Authorization Code Flow with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/call-your-api-using-the-authorization-code-flow-with-pkce).

To implement the Authorization Code Flow with Proof Key for Code Exchange (PKCE), you can use the following resources:

* [Auth0 Mobile SDKs](/docs/libraries) and [Auth0 Single-Page App SDK](/docs/libraries/auth0-single-page-app-sdk): The easiest way to implement the flow, which will do most of the heavy lifting for you. Our [Mobile Quickstarts](/docs/quickstart/native) and [Single-Page App Quickstarts](/docs/quickstart/spa) will walk you through the process.
* [Authentication API](https://auth0.com/docs/api/authentication): If you prefer to build your own solution, keep reading to learn how to call our API directly.

Following successful login, your application will have access to the user's <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> and <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>. The ID token will contain basic user profile information, and the access token can be used to call the Auth0 `/userinfo` endpoint or your own protected APIs. To learn more about ID tokens, read [ID Tokens](/docs/secure/tokens/id-tokens). To learn more about access tokens, read [Access Tokens](/docs/secure/tokens/access-tokens).

## Prerequisites

Register your app with Auth0. To learn more, read [Register Native Applications](/docs/get-started/auth0-overview/create-applications/native-apps) or [Register Single-Page Web Applications](/docs/get-started/auth0-overview/create-applications/single-page-web-apps).

* Select an **Application Type** of **Native** or **Single-Page App**, depending on your application type.
* Add an **Allowed Callback URL** of `YOUR_CALLBACK_URL`. Your callback URL format will vary depending on your application type and platform. For details about the format for your application type and platform, see our [Native/Mobile Quickstarts](/docs/quickstart/native) and [Single-Page App Quickstarts](/docs/quickstart/spa).
* Make sure your application's **Grant Types** include **Authorization Code**. To learn more, read [Update Grant Types](/docs/get-started/applications/update-grant-types).

## Create code verifier

Create a `code_verifier`, which is a cryptographically-random, Base64-encoded key that will eventually be sent to Auth0 to request tokens.

To learn more about the algorithm to create the `code_verifier`, read section [4.1 Client Creates a Code Verifier](https://datatracker.ietf.org/doc/html/rfc7636#section-4.1) of the <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> Proof Key for Code Exchange spec.

### Javascript sample

```javascript lines theme={null}
// Dependency: Node.js crypto module
// https://nodejs.org/api/crypto.html#crypto_crypto
function base64URLEncode(str) {
    return str.toString('base64')
        .replace(/\+/g, '-')
        .replace(/\//g, '_')
        .replace(/=/g, '');
}
var verifier = base64URLEncode(crypto.randomBytes(32));
```

### Java sample

```javascript lines theme={null}
// Dependency: Apache Commons Codec
// https://commons.apache.org/proper/commons-codec/
// Import the Base64 class.
// import org.apache.commons.codec.binary.Base64;
SecureRandom sr = new SecureRandom();
byte[] code = new byte[32];
sr.nextBytes(code);
String verifier = Base64.getUrlEncoder().withoutPadding().encodeToString(code);
```

### Android sample

```javascript lines theme={null}
// Dependency: Apache Commons Codec
// https://commons.apache.org/proper/commons-codec/
// Import the Base64 class.
// import org.apache.commons.codec.binary.Base64;
SecureRandom sr = new SecureRandom();
byte[] code = new byte[32];
sr.nextBytes(code);
String verifier = Base64.encodeToString(code, Base64.URL_SAFE | Base64.NO_WRAP | Base64.NO_PADDING);
```

### Swift 5 sample

```javascript lines theme={null}
var buffer = [UInt8](repeating: 0, count: 32)
_ = SecRandomCopyBytes(kSecRandomDefault, buffer.count, &buffer)
let verifier = Data(buffer).base64EncodedString()
    .replacingOccurrences(of: "+", with: "-")
    .replacingOccurrences(of: "/", with: "_")
    .replacingOccurrences(of: "=", with: "")
```

### Objective-C sample

```objc lines theme={null}
NSMutableData *data = [NSMutableData dataWithLength:32];
int result __attribute__((unused)) = SecRandomCopyBytes(kSecRandomDefault, 32, data.mutableBytes);
NSString *verifier = [[[[data base64EncodedStringWithOptions:0]
                        stringByReplacingOccurrencesOfString:@"+" withString:@"-"]
                        stringByReplacingOccurrencesOfString:@"/" withString:@"_"]
                        stringByTrimmingCharactersInSet:[NSCharacterSet characterSetWithCharactersInString:@"="]];
```

## Create code challenge

Generate a `code_challenge` from the `code_verifier` that will be sent to Auth0 to request an `authorization_code`.

To learn more about how the `code_challenge` is derived from the `code_verifier`, read section [4.2 Client Creates the Code Challenge](https://datatracker.ietf.org/doc/html/rfc7636#section-4.) of the OAuth Proof Key for Code Exchange spec.

### Javascript sample

```javascript lines theme={null}
// Dependency: Node.js crypto module
// https://nodejs.org/api/crypto.html#crypto_crypto
function sha256(buffer) {
    return crypto.createHash('sha256').update(buffer).digest();
}
var challenge = base64URLEncode(sha256(verifier));
```

### Java sample

```java lines theme={null}
// Dependency: Apache Commons Codec
// https://commons.apache.org/proper/commons-codec/
// Import the Base64 class.
// import org.apache.commons.codec.binary.Base64;
byte[] bytes = verifier.getBytes("US-ASCII");
MessageDigest md = MessageDigest.getInstance("SHA-256");
md.update(bytes, 0, bytes.length);
byte[] digest = md.digest();
String challenge = Base64.encodeBase64URLSafeString(digest);
```

### Swift 5 sample

```swift lines theme={null}
import CommonCrypto

// ...

guard let data = verifier.data(using: .utf8) else { return nil }
var buffer = [UInt8](repeating: 0, count: Int(CC_SHA256_DIGEST_LENGTH))
_ = data.withUnsafeBytes {
    CC_SHA256($0.baseAddress, CC_LONG(data.count), &buffer)
}
let hash = Data(buffer)
let challenge = hash.base64EncodedString()
    .replacingOccurrences(of: "+", with: "-")
    .replacingOccurrences(of: "/", with: "_")
    .replacingOccurrences(of: "=", with: "")
```

### Objective-C sample

```objc lines theme={null}
// Dependency: Apple Common Crypto library
// http://opensource.apple.com//source/CommonCrypto
u_int8_t buffer[CC_SHA256_DIGEST_LENGTH * sizeof(u_int8_t)];
memset(buffer, 0x0, CC_SHA256_DIGEST_LENGTH);
NSData *data = [verifier dataUsingEncoding:NSUTF8StringEncoding];
CC_SHA256([data bytes], (CC_LONG)[data length], buffer);
NSData *hash = [NSData dataWithBytes:buffer length:CC_SHA256_DIGEST_LENGTH];
NSString *challenge = [[[[hash base64EncodedStringWithOptions:0]
                         stringByReplacingOccurrencesOfString:@"+" withString:@"-"]
                         stringByReplacingOccurrencesOfString:@"/" withString:@"_"]
                         stringByTrimmingCharactersInSet:[NSCharacterSet characterSetWithCharactersInString:@"="]];
```

## Authorize user

Request the user's authorization and redirect back to your app with an `authorization_code`.

Once you've created the `code_verifier` and the `code_challenge`, you must get the user's authorization. This is technically the beginning of the <Tooltip href="/docs/glossary?term=authorization+flow">authorization flow</Tooltip>, and this step may include one or more of the following processes:

\* Authenticating the user;
\* Redirecting the user to an <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> to handle authentication;
\* Checking for active [Single Sign-on (SSO)](/docs/authenticate/single-sign-on) sessions;
\* Obtaining user consent for the requested permission level, unless consent has been previously given.

To authorize the user, your app must send the user to the [authorization URL](https://auth0.com/docs/api/authentication#authorization-code-grant-pkce-), including the `code_challenge` you generated in the previous step and the method you used to generate the `code_challenge`.

### Authorization URL example

<AuthCodeBlock />

### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>response\_type</code></td>
      <td>Denotes the kind of credential that Auth0 will return (<code>code</code> or <code>token</code>). For this flow, the value must be <code>code</code>.</td>
    </tr>

    <tr>
      <td><code>code\_challenge</code></td>
      <td>Generated challenge from the <code>code\_verifier</code>.</td>
    </tr>

    <tr>
      <td><code>code\_challenge\_method</code></td>
      <td>Method used to generate the challenge (e.g., S256). The PKCE spec defines two methods, <code>S256</code> and <code>plain</code>, the former is used in this example and is the <strong>only</strong> one supported by Auth0 since the latter is discouraged.</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Your application's Client ID. You can find this value in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>.</td>
    </tr>

    <tr>
      <td><code>redirect\_uri</code></td>
      <td>The URL to which Auth0 will redirect the browser after authorization has been granted by the user. The Authorization Code will be available in the <code>code</code> URL parameter. You must specify this URL as a valid callback URL in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>. <br /> <br /> <strong>Warning:</strong> Per the <a href="https://tools.ietf.org/html/rfc6749#section-3.1.2">OAuth 2.0 Specification</a>, Auth0 removes everything after the hash and does <em>not</em> honor any fragments.</td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td>Specifies the <a href="/docs/get-started/apis/scopes">scopes</a> for which you want to request authorization, which dictate which claims (or user attributes) you want returned. These must be separated by a space. To get an ID Token in the response, you need to specify a scope of at least <code>openid</code>. If you want to return the user's full profile, you can request <code>openid profile</code>. You can request any of the <a href="https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims">standard OpenID Connect (OIDC) scopes</a> about users, such as <code>email</code>, or <a href="/docs/secure/tokens/json-web-tokens/json-web-token-claims#custom-claims">custom claims</a> conforming to a <a href="/docs/secure/tokens/json-web-tokens/create-custom-claims">namespaced format</a>. Include <code>offline\_access</code> to get a <Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip> (make sure that the <strong>Allow Offline Access</strong> field is enabled in the <a href="https://manage.auth0.com/#/applications">Application Settings</a>).</td>
    </tr>

    <tr>
      <td><code>state</code></td>
      <td>(recommended) An opaque arbitrary alphanumeric string your app adds to the initial request that Auth0 includes when redirecting back to your application. To see how to use this value to prevent cross-site request forgery (CSRF) attacks, see <a href="/docs/secure/attack-protection/state-parameters">Mitigate CSRF Attacks With State Parameters</a>.</td>
    </tr>

    <tr>
      <td><code>connection</code></td>
      <td>(optional) Forces the user to sign in with a specific connection. For example, you can pass a value of <code>github</code> to send the user directly to GitHub to log in with their GitHub account. When not specified, the user sees the Auth0 Lock screen with all configured connections. You can see a list of your configured connections on the <strong>Connections</strong> tab of your application.</td>
    </tr>

    <tr>
      <td><code>organization</code></td>
      <td>(optional) ID of the organization to use when authenticating a user. When not provided, if your application is configured to <strong>Display Organization Prompt</strong>, the user will be able to enter the organization name when authenticating.</td>
    </tr>

    <tr>
      <td><code>invitation</code></td>
      <td>(optional) Ticket ID of the organization invitation. When <a href="/docs/manage-users/organizations/configure-organizations/invite-members">inviting a member to an Organization</a>, your application should handle invitation acceptance by forwarding the <code>invitation</code> and <code>organization</code> key-value pairs when the user accepts the invitation.</td>
    </tr>
  </tbody>
</table>

As an example, your HTML snippet for your authorization URL when adding login to your app might look like:

<AuthCodeBlock />

### Response

If all goes well, you'll receive an `HTTP 302` response. The authorization code is included at the end of the URL:

```http lines theme={null}
HTTP/1.1 302 Found
Location: {yourCallbackUrl}?code={authorizationCode}&state=xyzABC123
```

## Request tokens

Exchange your `authorization_code` and `code_verifier` for tokens.

Now that you have an Authorization Code, you must exchange it for tokens. Using the extracted Authorization Code (`code`) from the previous step, you will need to `POST` to the [token URL](https://auth0.com/docs/api/authentication#authorization-code-pkce-) sending along the `code_verifier`.

### POST to token URL example

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=authorization_code \
    --data 'client_id={yourClientId}' \
    --data 'code_verifier={yourGeneratedCodeVerifier}' \
    --data 'code={yourAuthorizationCode}' \
    --data 'redirect_uri={https://yourApp/callback}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=authorization_code&client_id={yourClientId}&code_verifier=%7ByourGeneratedCodeVerifier%7D&code=%7ByourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=authorization_code&client_id={yourClientId}&code_verifier=%7ByourGeneratedCodeVerifier%7D&code=%7ByourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}")

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

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=authorization_code&client_id={yourClientId}&code_verifier=%7ByourGeneratedCodeVerifier%7D&code=%7ByourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: '{yourClientId}',
      code_verifier: '{yourGeneratedCodeVerifier}',
      code: '{yourAuthorizationCode}',
      redirect_uri: '{https://yourApp/callback}'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=authorization_code" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&code_verifier={yourGeneratedCodeVerifier}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&code={yourAuthorizationCode}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&redirect_uri={https://yourApp/callback}" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=authorization_code&client_id={yourClientId}&code_verifier=%7ByourGeneratedCodeVerifier%7D&code=%7ByourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=authorization_code&client_id={yourClientId}&code_verifier=%7ByourGeneratedCodeVerifier%7D&code=%7ByourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=authorization_code&client_id={yourClientId}&code_verifier=%7ByourGeneratedCodeVerifier%7D&code=%7ByourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/x-www-form-urlencoded"]

  let postData = NSMutableData(data: "grant_type=authorization_code".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&code_verifier={yourGeneratedCodeVerifier}".data(using: String.Encoding.utf8)!)
  postData.append("&code={yourAuthorizationCode}".data(using: String.Encoding.utf8)!)
  postData.append("&redirect_uri={https://yourApp/callback}".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td>Set this to "authorization\_code".</td>
    </tr>

    <tr>
      <td><code>code\_verifier</code></td>
      <td>The cryptographically-random key that was generated in the first step of this tutorial.</td>
    </tr>

    <tr>
      <td><code>code</code></td>
      <td>The <code>authorization\_code</code> retrieved in the previous step of this tutorial.</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Your application's Client ID. You can find this value in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>.</td>
    </tr>

    <tr>
      <td><code>redirect\_uri</code></td>
      <td>The valid callback URL set in your Application settings. This must exactly match the <code>redirect\_uri</code> passed to the authorization URL in the previous step of this tutorial. Note that this must be URL encoded.</td>
    </tr>
  </tbody>
</table>

### Response

If all goes well, you'll receive an HTTP 200 response with a payload containing `access_token`, `refresh_token`, `id_token`, and `token_type` values:

```json lines theme={null}
{
  "access_token":"eyJz93a...k4laUWw",
  "refresh_token":"GEbRxBN...edjnXbL",
  "id_token":"eyJ0XAi...4faeEoQ",
  "token_type":"Bearer",
  "expires_in":86400
}
```

<Warning>
  Validate your tokens before saving them. To learn how, read [Validate ID Tokens](/docs/secure/tokens/id-tokens/validate-id-tokens) and [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens).
</Warning>

[ID tokens](/docs/secure/tokens/id-tokens) contain user information that must be decoded and extracted.

[Access tokens](/docs/secure/tokens/access-tokens) are used to call the [Auth0 Authentication API's /userinfo endpoint](https://auth0.com/docs/api/authentication#get-user-info) or another API. If you are calling your own API, the first thing your API will need to do is [verify the Access token](/docs/secure/tokens/access-tokens/validate-access-tokens).

[Refresh tokens](/docs/secure/tokens/refresh-tokens) are used to obtain a new access token or ID token after the previous one has expired. The `refresh_token` will only be present in the response if you included the `offline_access` scope and enabled **Allow Offline Access** for your API in the Dashboard.

<Warning>
  Refresh tokens must be stored securely since they allow a user to remain authenticated essentially forever.
</Warning>

## Use cases

### Basic authentication request

This example shows the most basic request you can make when authorizing the user in step 1. It displays the Auth0 login screen and allows the user to sign in with any of your configured connections:

<AuthCodeBlock />

Now, when you request tokens, your ID Token will contain the most basic claims. When you decode the ID Token, it will look similar to:

```json lines theme={null}
{
  "iss": "https://auth0pnp.auth0.com/",
  "sub": "auth0|581...",
  "aud": "xvt9...",
  "exp": 1478112929,
  "iat": 1478076929
}
```

### Request user's name and profile picture

In addition to the usual user authentication, this example shows how to request additional user details, such as name and picture.

To request the user's name and picture, you need to add the appropriate scopes when authorizing the user:

<AuthCodeBlock />

Now, when you request tokens, your ID token will contain the requested name and picture claims. When you decode the ID token, it will look similar to:

```json lines theme={null}
{
  "name": "auth0user@...",
  "picture": "https://example.com/profile-pic.png",
  "iss": "https://auth0user.auth0.com/",
  "sub": "auth0|581...",
  "aud": "xvt...",
  "exp": 1478113129,
  "iat": 1478077129
}
```

### Request user log in with GitHub

In addition to the usual user authentication, this example shows how to send users directly to a social identity provider, such as GitHub. For this example to work, you need to go to [Auth0 Dashboard > Authentication > Social](https://manage.auth0.com/#/connections/social) and configure the appropriate connection. Get the connection name from the **Settings** tab.

To send users directly to the GitHub login screen, you need to pass the `connection` parameter and set its value to the connection name (in this case, `github`) when authorizing the user:

<AuthCodeBlock />

Now, when you request tokens, your ID token will contain a `sub` claim with the user's unique ID returned from GitHub. When you decode the ID token, it will look similar to:

```json lines theme={null}
{
  "name": "John Smith",
  "picture": "https://avatars.example.com",
  "email": "jsmith@...",
  "email_verified": true,
  "iss": "https://auth0user.auth0.com/",
  "sub": "github|100...",
  "aud": "xvt...",
  "exp": 1478114742,
  "iat": 1478078742
}
```

## Learn more

* [OAuth 2.0 Authorization Framework](/docs/authenticate/protocols/oauth)
* [OpenID Connect Protocol](/docs/authenticate/protocols/openid-connect-protocol)
* [Tokens](/docs/secure/tokens)


# Call Your API Using the Authorization Code Flow with PKCE
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/call-your-api-using-the-authorization-code-flow-with-pkce

Learn how to call your API from a native, mobile, or single-page application using the Authorization Code flow using Proof Key for Code Exchange (PKCE).

<Callout icon="file-lines">
  This tutorial helps you call your own API from a native, mobile, or single-page app using the Authorization Code Flow with PKCE. To learn how the flow works and why you should use it, read [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce). To learn to add login to your native, mobile, or single-page app, read [Add Login Using Authorization Code Flow with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/add-login-using-the-authorization-code-flow-with-pkce).
</Callout>

Auth0 makes it easy for your app to implement the Authorization Code Flow with Proof Key for Code Exchange (PKCE) using:

* [Auth0 Mobile SDKs](/docs/libraries) and [Auth0 Single-Page App SDK](/docs/libraries/auth0-single-page-app-sdk): The easiest way to implement the flow, which will do most of the heavy-lifting for you. Our [Mobile Quickstarts](/docs/quickstart/native) and [Single-Page App Quickstarts](/docs/quickstart/spa) will walk you through the process.
* [Authentication API](https://auth0.com/docs/api/authentication): If you prefer to build your own solution, keep reading to learn how to call our API directly.

## Prerequisites

**Before beginning this tutorial:**

* [Register the Application with Auth0](/docs/get-started/auth0-overview/create-applications/native-apps).

  * Select an **Application Type** of **Native** or **Single-Page App**, depending on your application type.
  * Add an **Allowed Callback URL** of `{yourCallbackUrl}`. Your callback URL format will vary depending on your application type and platform. For details about the format for your application type and platform, see our [Native/Mobile Quickstarts](/docs/quickstart/native) and [Single-Page App Quickstarts](/docs/quickstart/spa).
  * Make sure the Application's **Grant Types** include **Authorization Code**. To learn how, read [Update Grant Types](/docs/get-started/applications/update-grant-types).
  * If you want your Application to be able to use Refresh Tokens, make sure the Application's **Grant Types** include **Refresh Token**. To learn how, read [Update Grant Types](/docs/get-started/applications/update-grant-types). To learn more about Refresh Tokens, read [Refresh Tokens](/docs/secure/tokens/refresh-tokens).
* [Register your API with Auth0](/docs/get-started/architecture-scenarios/mobile-api/part-2#create-the-api)

  * If you want your API to receive Refresh Tokens to allow it to obtain new tokens when the previous ones expire, enable **Allow Offline Access**.

## Steps

1. [Create code verifier](#create-code-verifier):
   Generate a `code_verifier` that will be sent to Auth0 to request tokens.
2. [Create code challenge](#create-code-challenge):
   Generate a `code_challenge` from the `code_verifier` that will be sent to Auth0 to request an `authorization_code`.
3. [Authorize user](#authorize-user):
   Request the user's authorization and redirect back to your app with an `authorization_code`.
4. [Request tokens](#request-tokens):
   Exchange your `authorization_code` and `code_verifier` for tokens.
5. [Call API](#call-api):
   Use the retrieved Access Token to call your API.
6. [Refresh tokens](#refresh-tokens):
   Use a Refresh Token to request new tokens when the existing ones expire.

Optional: [Explore sample use cases](#sample-use-cases).

### Create code verifier

Create a `code_verifier`, which is a cryptographically-random, Base64-encoded key that will eventually be sent to Auth0 to request tokens.

#### Javascript sample

```javascript lines theme={null}
// Dependency: Node.js crypto module
// https://nodejs.org/api/crypto.html#crypto_crypto
function base64URLEncode(str) {
    return str.toString('base64')
        .replace(/\+/g, '-')
        .replace(/\//g, '_')
        .replace(/=/g, '');
}
var verifier = base64URLEncode(crypto.randomBytes(32));
```

#### Java sample

```java lines theme={null}
// Dependency: Apache Commons Codec
// https://commons.apache.org/proper/commons-codec/
// Import the Base64 class.
// import org.apache.commons.codec.binary.Base64;
SecureRandom sr = new SecureRandom();
byte[] code = new byte[32];
sr.nextBytes(code);
String verifier = Base64.getUrlEncoder().withoutPadding().encodeToString(code);
```

#### Android sample

```kotlin lines theme={null}
// See https://developer.android.com/reference/android/util/Base64
// Import the Base64 class
// import android.util.Base64;
SecureRandom sr = new SecureRandom();
byte[] code = new byte[32];
sr.nextBytes(code);
String verifier = Base64.encodeToString(code, Base64.URL_SAFE | Base64.NO_WRAP | Base64.NO_PADDING);
```

#### Swift 5 sample

```swift lines theme={null}
var buffer = [UInt8](repeating: 0, count: 32)
_ = SecRandomCopyBytes(kSecRandomDefault, buffer.count, &buffer)
let verifier = Data(buffer).base64EncodedString()
    .replacingOccurrences(of: "+", with: "-")
    .replacingOccurrences(of: "/", with: "_")
    .replacingOccurrences(of: "=", with: "")
```

#### Objective-C sample

```objc lines theme={null}
NSMutableData *data = [NSMutableData dataWithLength:32];
int result __attribute__((unused)) = SecRandomCopyBytes(kSecRandomDefault, 32, data.mutableBytes);
NSString *verifier = [[[[data base64EncodedStringWithOptions:0]
                        stringByReplacingOccurrencesOfString:@"+" withString:@"-"]
                        stringByReplacingOccurrencesOfString:@"/" withString:@"_"]
                        stringByTrimmingCharactersInSet:[NSCharacterSet characterSetWithCharactersInString:@"="]];
```

### Create code challenge

Generate a `code_challenge` from the `code_verifier` that will be sent to Auth0 to request an `authorization_code`.

#### Javascript sample

```javascript lines theme={null}
// Dependency: Node.js crypto module
// https://nodejs.org/api/crypto.html#crypto_crypto
function sha256(buffer) {
    return crypto.createHash('sha256').update(buffer).digest();
}
var challenge = base64URLEncode(sha256(verifier));
```

#### Java sample

```java lines theme={null}
// Dependency: Apache Commons Codec
// https://commons.apache.org/proper/commons-codec/
// Import the Base64 class.
// import org.apache.commons.codec.binary.Base64;
byte[] bytes = verifier.getBytes("US-ASCII");
MessageDigest md = MessageDigest.getInstance("SHA-256");
md.update(bytes, 0, bytes.length);
byte[] digest = md.digest();
String challenge = Base64.encodeBase64URLSafeString(digest);
```

#### Swift 5 sample

```swift lines theme={null}
import CommonCrypto

// ...

guard let data = verifier.data(using: .utf8) else { return nil }
var buffer = [UInt8](repeating: 0, count: Int(CC_SHA256_DIGEST_LENGTH))
_ = data.withUnsafeBytes {
    CC_SHA256($0.baseAddress, CC_LONG(data.count), &buffer)
}
let hash = Data(buffer)
let challenge = hash.base64EncodedString()
    .replacingOccurrences(of: "+", with: "-")
    .replacingOccurrences(of: "/", with: "_")
    .replacingOccurrences(of: "=", with: "")
```

#### Objective-C sample

```objc lines theme={null}
// Dependency: Apple Common Crypto library
// http://opensource.apple.com//source/CommonCrypto
u_int8_t buffer[CC_SHA256_DIGEST_LENGTH * sizeof(u_int8_t)];
memset(buffer, 0x0, CC_SHA256_DIGEST_LENGTH);
NSData *data = [verifier dataUsingEncoding:NSUTF8StringEncoding];
CC_SHA256([data bytes], (CC_LONG)[data length], buffer);
NSData *hash = [NSData dataWithBytes:buffer length:CC_SHA256_DIGEST_LENGTH];
NSString *challenge = [[[[hash base64EncodedStringWithOptions:0]
                         stringByReplacingOccurrencesOfString:@"+" withString:@"-"]
                         stringByReplacingOccurrencesOfString:@"/" withString:@"_"]
                         stringByTrimmingCharactersInSet:[NSCharacterSet characterSetWithCharactersInString:@"="]];
```

### Authorize user

Once you've created the `code_verifier` and the `code_challenge`, you must get the user's authorization. This is technically the beginning of the <Tooltip href="/docs/glossary?term=authorization+flow">authorization flow</Tooltip>, and this step may include one or more of the following processes:

\* Authenticating the user;
\* Redirecting the user to an <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> to handle authentication;
\* Checking for active [Single Sign-on (SSO)](/docs/authenticate/single-sign-on) sessions;
\* Obtaining user consent for the requested permission level, unless consent has been previously given.

To authorize the user, your app must send the user to the [authorization URL](https://auth0.com/docs/api/authentication#authorization-code-grant-pkce-), including the `code_challenge` you generated in the previous step and the method you used to generate the `code_challenge`.

#### Example authorization URL

<AuthCodeBlock />

##### Parameters

Note that for authorizing a user when calling a custom API, you:

* must include an <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> parameter
* can include additional scopes supported by the target API

<table>
  <thead>
    <tr>
      <th>Parameter Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>response\_type</code></td>
      <td>Denotes the kind of credential that Auth0 will return (<code>code</code> or <code>token</code>). For this flow, the value must be <code>code</code>.</td>
    </tr>

    <tr>
      <td><code>code\_challenge</code></td>
      <td>Generated challenge from the <code>code\_verifier</code>.</td>
    </tr>

    <tr>
      <td><code>code\_challenge\_method</code></td>
      <td>Method used to generate the challenge (e.g., S256). The PKCE spec defines two methods, <code>S256</code> and <code>plain</code>, the former is used in this example and is the <strong>only</strong> one supported by Auth0 since the latter is discouraged.</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Your application's Client ID. You can find this value in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>.</td>
    </tr>

    <tr>
      <td><code>redirect\_uri</code></td>
      <td>The URL to which Auth0 will redirect the browser after authorization has been granted by the user. The Authorization Code will be available in the <code>code</code> URL parameter. You must specify this URL as a valid callback URL in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>. <br /> <br /> <strong>Warning:</strong> Per the <a href="https://tools.ietf.org/html/rfc6749#section-3.1.2">OAuth 2.0 Specification</a>, Auth0 removes everything after the hash and does <em>not</em> honor any fragments.</td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td>The <a href="/docs/get-started/apis/scopes">scopes</a> for which you want to request authorization. These must be separated by a space. You can request any of the <a href="https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims">standard OpenID Connect (OIDC) scopes</a> about users, such as <code>profile</code> and <code>email</code>, <a href="/docs/secure/tokens/json-web-tokens/json-web-token-claims#custom-claims">custom claims</a> conforming to a <a href="/docs/secure/tokens/json-web-tokens/create-custom-claims">namespaced format</a>, or any scopes supported by the target API (e.g., <code>read:contacts</code>). Include <code>offline\_access</code> to get a <Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip> (make sure that the <strong>Allow Offline Access</strong> field is enabled in the <a href="https://manage.auth0.com/#/apis">Application Settings</a>).</td>
    </tr>

    <tr>
      <td><code>audience</code></td>
      <td>The unique identifier of the API your mobile app wants to access. Use the <strong>Identifier</strong> value on the <a href="https://manage.auth0.com/#/apis">Settings</a> tab for the API you created as part of the prerequisites for this tutorial.</td>
    </tr>

    <tr>
      <td><code>state</code></td>
      <td>(recommended) An opaque arbitrary alphanumeric string your app adds to the initial request that Auth0 includes when redirecting back to your application. To see how to use this value to prevent cross-site request forgery (CSRF) attacks, see <a href="/docs/secure/attack-protection/state-parameters">Mitigate CSRF Attacks With State Parameters</a>.</td>
    </tr>

    <tr>
      <td><code>organization</code></td>
      <td>(optional) ID of the organization to use when authenticating a user. When not provided, if your application is configured to <strong>Display Organization Prompt</strong>, the user will be able to enter the organization name when authenticating.</td>
    </tr>

    <tr>
      <td><code>invitation</code></td>
      <td>(optional) Ticket ID of the organization invitation. When <a href="/docs/manage-users/organizations/configure-organizations/invite-members">inviting a member to an Organization</a>, your application should handle invitation acceptance by forwarding the <code>invitation</code> and <code>organization</code> key-value pairs when the user accepts the invitation.</td>
    </tr>
  </tbody>
</table>

As an example, your HTML snippet for your authorization URL when calling an API might look like:

<AuthCodeBlock />

#### Response

If all goes well, you'll receive an `HTTP 302` response. The authorization code is included at the end of the URL:

```http lines theme={null}
HTTP/1.1 302 Found
Location: {yourCallbackUrl}?code={authorizationCode}&state=xyzABC123
```

### Request tokens

Now that you have an Authorization Code, you must exchange it for tokens. Using the extracted Authorization Code (`code`) from the previous step, you will need to `POST` to the [token URL](https://auth0.com/docs/api/authentication#authorization-code-pkce-) sending along the `code_verifier`.

#### Example POST to token URL

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=authorization_code \
    --data 'client_id={yourClientId}' \
    --data 'code_verifier={yourGeneratedCodeVerifier}' \
    --data 'code={yourAuthorizationCode}' \
    --data 'redirect_uri={https://yourApp/callback}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=authorization_code&client_id={yourClientId}&code_verifier=%7ByourGeneratedCodeVerifier%7D&code=%7ByourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=authorization_code&client_id={yourClientId}&code_verifier=%7ByourGeneratedCodeVerifier%7D&code=%7ByourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}")

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

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=authorization_code&client_id={yourClientId}&code_verifier=%7ByourGeneratedCodeVerifier%7D&code=%7ByourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: '{yourClientId}',
      code_verifier: '{yourGeneratedCodeVerifier}',
      code: '{yourAuthorizationCode}',
      redirect_uri: '{https://yourApp/callback}'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=authorization_code" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&code_verifier={yourGeneratedCodeVerifier}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&code={yourAuthorizationCode}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&redirect_uri={https://yourApp/callback}" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=authorization_code&client_id={yourClientId}&code_verifier=%7ByourGeneratedCodeVerifier%7D&code=%7ByourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=authorization_code&client_id={yourClientId}&code_verifier=%7ByourGeneratedCodeVerifier%7D&code=%7ByourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=authorization_code&client_id={yourClientId}&code_verifier=%7ByourGeneratedCodeVerifier%7D&code=%7ByourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/x-www-form-urlencoded"]

  let postData = NSMutableData(data: "grant_type=authorization_code".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&code_verifier={yourGeneratedCodeVerifier}".data(using: String.Encoding.utf8)!)
  postData.append("&code={yourAuthorizationCode}".data(using: String.Encoding.utf8)!)
  postData.append("&redirect_uri={https://yourApp/callback}".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

##### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td>Set this to "authorization\_code".</td>
    </tr>

    <tr>
      <td><code>code\_verifier</code></td>
      <td>The cryptographically-random key that was generated in the first step of this tutorial.</td>
    </tr>

    <tr>
      <td><code>code</code></td>
      <td>The <code>authorization\_code</code> retrieved in the previous step of this tutorial.</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Your application's Client ID. You can find this value in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>.</td>
    </tr>

    <tr>
      <td><code>redirect\_uri</code></td>
      <td>The valid callback URL set in your Application settings. This must exactly match the <code>redirect\_uri</code> passed to the authorization URL in the previous step of this tutorial. Note that this must be URL encoded.</td>
    </tr>
  </tbody>
</table>

#### Response

If all goes well, you'll receive an HTTP 200 response with a payload containing `access_token`, `refresh_token`, `id_token`, and `token_type` values:

```json lines theme={null}
{
  "access_token":"eyJz93a...k4laUWw",
  "refresh_token":"GEbRxBN...edjnXbL",
  "id_token":"eyJ0XAi...4faeEoQ",
  "token_type":"Bearer",
  "expires_in":86400
}
```

<Warning>
  Validate your tokens before saving them. To learn how, read [Validate ID Tokens](/docs/secure/tokens/id-tokens/validate-id-tokens) and [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens).
</Warning>

[ID tokens](/docs/secure/tokens/id-tokens) contain user information that must be decoded and extracted.

[Access tokens](/docs/secure/tokens/access-tokens) are used to call the [Auth0 Authentication API's /userinfo endpoint](https://auth0.com/docs/api/authentication#get-user-info) or another API. If you are calling your own API, the first thing your API will need to do is [verify the Access token](/docs/secure/tokens/access-tokens/validate-access-tokens).

[Refresh tokens](/docs/secure/tokens/refresh-tokens) are used to obtain a new <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> or <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> after the previous one has expired. The `refresh_token` will only be present in the response if you included the `offline_access` scope and enabled **Allow Offline Access** for your API in the Dashboard.

<Warning>
  Refresh tokens must be stored securely since they allow a user to remain authenticated essentially forever.
</Warning>

### Call API

To call your API from a native/mobile application, the application must pass the retrieved Access Token as a Bearer token in the Authorization header of your HTTP request.

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request GET \
    --url https://myapi.com/api \
    --header 'authorization: Bearer {accessToken}' \
    --header 'content-type: application/json'
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://myapi.com/api");
  var request = new RestRequest(Method.GET);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer {accessToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines expandable theme={null}
  package main

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

  func main() {

  	url := "https://myapi.com/api"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("content-type", "application/json")
  	req.Header.Add("authorization", "Bearer {accessToken}")

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

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

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

  }
  ```

  ```java Java lines theme={null}
  HttpResponse response = Unirest.get("https://myapi.com/api")
    .header("content-type", "application/json")
    .header("authorization", "Bearer {accessToken}")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://myapi.com/api',
    headers: {'content-type': 'application/json', authorization: 'Bearer {accessToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C lines theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer {accessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://myapi.com/api"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP lines expandable theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://myapi.com/api",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {accessToken}",
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("myapi.com")

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer {accessToken}"
      }

  conn.request("GET", "/api", headers=headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://myapi.com/api")

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

  request = Net::HTTP::Get.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer {accessToken}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift lines theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer {accessToken}"
  ]

  let request = NSMutableURLRequest(url: NSURL(string: "https://myapi.com/api")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

### Refresh tokens

You have already received a [refresh token](/docs/secure/tokens/refresh-tokens) if you've been following this tutorial and completed the following:

* configured your API to allow offline access
* included the `offline_access` scope when you initiated the authentication request through the [authorize endpoint](https://auth0.com/docs/api/authentication/reference#authorize-application).

You can use the <Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip> to get a new access token. Usually, a user will need a new access token only after the previous one expires or when gaining access to a new resource for the first time. It's bad practice to call the endpoint to get a new access token every time you call an API, and Auth0 maintains rate limits that will throttle the amount of requests to the endpoint that can be executed using the same token from the same IP.

To refresh your token, make a `POST` request to the `/oauth/token` endpoint in the Authentication API, using `grant_type=refresh_token`.

#### Example POST to token URL

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=refresh_token \
    --data 'client_id={yourClientId}' \
    --data 'refresh_token={yourRefreshToken}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D")

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

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'refresh_token',
      client_id: '{yourClientId}',
      refresh_token: '{yourRefreshToken}'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=refresh_token" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&refresh_token={yourRefreshToken}" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/x-www-form-urlencoded"]

  let postData = NSMutableData(data: "grant_type=refresh_token".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&refresh_token={yourRefreshToken}".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

##### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td>Set this to <code>refresh\_token</code>.</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Your application's Client ID. You can find this value in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>.</td>
    </tr>

    <tr>
      <td><code>refresh\_token</code></td>
      <td>The refresh token to use.</td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td>(optional) A space-delimited list of requested scope permissions. If not sent, the original scopes will be used; otherwise you can request a reduced set of scopes. Note that this must be URL encoded.</td>
    </tr>
  </tbody>
</table>

#### Response

If all goes well, you'll receive an `HTTP 200` response with a payload containing a new `access_token`, its lifetime in seconds (`expires_in`), granted `scope` values, and `token_type`. If the scope of the initial token included `openid`, then the response will also include a new `id_token`:

```json lines theme={null}
{
  "access_token": "eyJ...MoQ",
  "expires_in": 86400,
  "scope": "openid offline_access",
  "id_token": "eyJ...0NE",
  "token_type": "Bearer"
}
```

<Warning>
  Validate your tokens before saving them. To learn how, read [Validate ID Tokens](/docs/secure/tokens/id-tokens/validate-id-tokens) and [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens).
</Warning>

### Sample use cases

#### Customize tokens

You can use Actions to change the returned scopes of Access Tokens and/or add claims to Access and ID Tokens. (To learn more about Actions, read [Auth0 Actions](/docs/customize/actions). ) To do so, add the following Action, which will run after the user authenticates:

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  // Add custom claims to Access Token and ID Token
  api.accessToken.setCustomClaim('https://foo/bar', 'value');
  api.idToken.setCustomClaim('https://fiz/baz', 'some other value');

  // Modify the scope of the Access Token
  api.accessToken.addScope('foo');
  api.accessToken.addScope('bar');
};
```

Scopes will be available in the token after the Action has run.

<Warning>
  Auth0 returns profile information in a structured claim format as defined by the [OpenID Connect (OIDC) specification](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). This means that custom claims added to ID tokens or access tokens must [conform to guidelines and restrictions](/docs/secure/tokens/json-web-tokens/create-custom-claims) to avoid possible collisions.
</Warning>

#### View Sample Application: Mobile App + API

For a sample implementation, see the [Mobile + API](/docs/get-started/architecture-scenarios/mobile-api) architecture scenario. This series of tutorials is accompanied by a [code sample that you can access in GitHub](https://github.com/auth0-samples/auth0-pnp-exampleco-timesheets).

## Learn more

* [OAuth 2.0 Authorization Framework](/docs/authenticate/protocols/oauth)
* [OpenID Connect Protocol](/docs/authenticate/protocols/openid-connect-protocol)
* [Tokens](/docs/secure/tokens)


# Add Login Using the Authorization Code Flow
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/add-login-auth-code-flow

Learn how to add login to your regular web application using the Authorization Code Flow.

You can add login to your regular web application using the Authorization Code Flow. To learn how the flow works and why you should use it, read [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow). To call your API from a regular web app, read [Call Your API Using the Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/call-your-api-using-the-authorization-code-flow).

To implement the Authorization Code Flow, Auth0 provides the following resources:

* [Regular Web App Quickstarts](/docs/quickstart/webapp): The easiest way to implement the flow.
* [Authentication API](https://auth0.com/docs/api/authentication): If you prefer to build your own solution, keep reading to learn how to call our API directly.

Following a successful login, your application will have access to the user's <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> and <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>. The ID token contains basic user profile information, and the access token can be used to call the Auth0 `/userinfo` endpoint or your own protected APIs. To learn more about ID tokens, read [ID Tokens](/docs/secure/tokens/id-tokens). To learn more about access tokens, read [Access Tokens](/docs/secure/tokens/access-tokens).

You will request the user's authorization and redirect back to your app with an `authorization_code`. Then you will exchange the code for tokens.

## Prerequisites

Register your app with Auth0. To learn more, read [Register Regular Web Applications](/docs/get-started/auth0-overview/create-applications/regular-web-apps).

* Select **Regular Web App** as the **Application Type**.
* Add an **Allowed Callback URL** of `{https://yourApp/callback}`.
* Make sure your application's **Grant Types** include **Authorization Code**. To learn more, read [Update Grant Types](/docs/get-started/applications/update-grant-types).

## Authorize user

To begin the flow, you'll need to get the user's authorization. This step may include one or more of the following processes:

* Authenticating the user;
* Redirecting the user to an <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> to handle authentication;
* Obtaining user consent for the requested permission level, unless consent has been previously given.

To authorize the user, your app must send the user to the [authorization URL](https://auth0.com/docs/api/authentication#authorization-code-flow).

### Authorization URL example

<AuthCodeBlock />

### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>response\_type</code></td>
      <td>Denotes the kind of credential that Auth0 will return (<code>code</code> or <code>token</code>). For this flow, the value must be <code>code</code>.</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Your application's Client ID. You can find this value in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>.</td>
    </tr>

    <tr>
      <td><code>redirect\_uri</code></td>
      <td>The URL to which Auth0 will redirect the browser after authorization has been granted by the user. The Authorization Code will be available in the <code>code</code> URL parameter. You must specify this URL as a valid callback URL in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>. <br /> <br /> <strong>Warning:</strong> Per the <a href="https://tools.ietf.org/html/rfc6749#section-3.1.2">OAuth 2.0 Specification</a>, Auth0 removes everything after the hash and does <em>not</em> honor any fragments.</td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td>Specifies the <a href="/docs/get-started/apis/scopes">scopes</a> for which you want to request authorization, which dictate which claims (or user attributes) you want returned. These must be separated by a space. To get an ID Token in the response, you need to specify a scope of at least <code>openid</code>. If you want to return the user's full profile, you can request <code>openid profile</code>. You can request any of the <a href="https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims">standard OpenID Connect (OIDC) scopes</a> about users, such as <code>email</code>, or <a href="/docs/secure/tokens/json-web-tokens/json-web-token-claims#custom-claims">custom claims</a> conforming to a <a href="/docs/secure/tokens/json-web-tokens/create-custom-claims">namespaced format</a>. Include <code>offline\_access</code> to get a <Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip> (make sure that the <strong>Allow Offline Access</strong> field is enabled in the <a href="https://manage.auth0.com/#/applications">Application Settings</a>).</td>
    </tr>

    <tr>
      <td><code>state</code></td>
      <td>(recommended) An opaque arbitrary alphanumeric string your app adds to the initial request that Auth0 includes when redirecting back to your application. To see how to use this value to prevent cross-site request forgery (CSRF) attacks, see <a href="/docs/secure/attack-protection/state-parameters">Mitigate CSRF Attacks With State Parameters</a>.</td>
    </tr>

    <tr>
      <td><code>connection</code></td>
      <td>(optional) Forces the user to sign in with a specific connection. For example, you can pass a value of <code>github</code> to send the user directly to GitHub to log in with their GitHub account. When not specified, the user sees the Auth0 Lock screen with all configured connections. You can see a list of your configured connections on the <strong>Connections</strong> tab of your application.</td>
    </tr>

    <tr>
      <td><code>organization</code></td>
      <td>(optional) ID of the organization to use when authenticating a user. When not provided, if your application is configured to <strong>Display Organization Prompt</strong>, the user will be able to enter the organization name when authenticating.</td>
    </tr>

    <tr>
      <td><code>invitation</code></td>
      <td>(optional) Ticket ID of the organization invitation. When <a href="/docs/manage-users/organizations/configure-organizations/invite-members">inviting a member to an Organization</a>, your application should handle invitation acceptance by forwarding the <code>invitation</code> and <code>organization</code> key-value pairs when the user accepts the invitation.</td>
    </tr>

    <tr>
      <td><code>login\_hint</code></td>
      <td>(optional) Populates the username/email field for the login or signup page when redirecting to Auth0. Supported by the Universal Login experience.</td>
    </tr>
  </tbody>
</table>

As an example, your HTML snippet for your authorization URL when adding login to your app might look like:

<AuthCodeBlock />

### Response

If all goes well, you'll receive an `HTTP 302` response. The authorization code is included at the end of the URL:

```http lines theme={null}
HTTP/1.1 302 Found
Location: {https://yourApp/callback}?code={authorizationCode}&state=xyzABC123
```

## Request tokens

Now that you have an Authorization Code, you must exchange it for tokens. Using the extracted Authorization Code (`code`) from the previous step, you will need to `POST` to the [token URL](https://auth0.com/docs/api/authentication#authorization-code).

### POST to token URL example

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=authorization_code \
    --data 'client_id={yourClientId}' \
    --data 'client_secret={yourClientSecret}' \
    --data 'code=yourAuthorizationCode}' \
    --data 'redirect_uri={https://yourApp/callback}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=authorization_code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&code=yourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=authorization_code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&code=yourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}")

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

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=authorization_code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&code=yourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      code: 'yourAuthorizationCode}',
      redirect_uri: '{https://yourApp/callback}'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=authorization_code" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_secret={yourClientSecret}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&code=yourAuthorizationCode}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&redirect_uri={https://yourApp/callback}" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=authorization_code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&code=yourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=authorization_code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&code=yourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=authorization_code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&code=yourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/x-www-form-urlencoded"]

  let postData = NSMutableData(data: "grant_type=authorization_code".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&client_secret={yourClientSecret}".data(using: String.Encoding.utf8)!)
  postData.append("&code=yourAuthorizationCode}".data(using: String.Encoding.utf8)!)
  postData.append("&redirect_uri={https://yourApp/callback}".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td>Set this to <code>authorization\_code</code>.</td>
    </tr>

    <tr>
      <td><code>code</code></td>
      <td>The <code>authorization\_code</code> retrieved in the previous step of this tutorial.</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Your application's Client ID. You can find this value in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>.</td>
    </tr>

    <tr>
      <td><code>client\_secret</code></td>
      <td>Your application's Client Secret. You can find this value in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>.  To learn more about available application authentication methods, read <a href="/docs/secure/application-credentials">Application Credentials</a>.</td>
    </tr>

    <tr>
      <td><code>redirect\_uri</code></td>
      <td>The valid callback URL set in your Application settings. This must exactly match the <code>redirect\_uri</code> passed to the authorization URL in the previous step of this tutorial. Note that this must be URL encoded.</td>
    </tr>
  </tbody>
</table>

### Response

If all goes well, you'll receive an HTTP 200 response with a payload containing `access_token`, `refresh_token`, `id_token`, and `token_type` values:

```json lines theme={null}
{
  "access_token": "eyJz93a...k4laUWw",
  "refresh_token": "GEbRxBN...edjnXbL",
  "id_token": "eyJ0XAi...4faeEoQ",
  "token_type": "Bearer"
}
```

<Warning>
  Validate your tokens before saving them. To learn how, read [Validate ID Tokens](/docs/secure/tokens/id-tokens/validate-id-tokens) and [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens).
</Warning>

[ID tokens](/docs/secure/tokens/id-tokens) contain user information that must be decoded and extracted.

[Access tokens](/docs/secure/tokens/access-tokens) are used to call the [Auth0 Authentication API's /userinfo endpoint](https://auth0.com/docs/api/authentication#get-user-info) or another API. If you are calling your own API, the first thing your API will need to do is [verify the Access token](/docs/secure/tokens/access-tokens/validate-access-tokens).

[Refresh tokens](/docs/secure/tokens/refresh-tokens) are used to obtain a new access token or ID token after the previous one has expired. The `refresh_token` will only be present in the response if you included the `offline_access` scope and enabled **Allow Offline Access** for your API in the Dashboard.

<Warning>
  Refresh tokens must be stored securely since they allow a user to remain authenticated essentially forever.
</Warning>

## Use cases

### Basic authentication request

This example shows the most basic request you can make when authorizing the user in step 1. It displays the Auth0 login screen and allows the user to sign in with any of your configured connections:

<AuthCodeBlock />

Now, when you request tokens, your ID Token will contain the most basic claims. When you decode the ID Token, it will look similar to:

```json lines theme={null}
{
  "iss": "https://auth0pnp.auth0.com/",
  "sub": "auth0|581...",
  "aud": "xvt9...",
  "exp": 1478112929,
  "iat": 1478076929
}
```

### Request user's name and profile picture

In addition to the usual user authentication, this example shows how to request additional user details, such as name and picture.

To request the user's name and picture, you need to add the appropriate scopes when authorizing the user:

<AuthCodeBlock />

Now, when you request tokens, your ID token will contain the requested name and picture claims. When you decode the ID token, it will look similar to:

```json lines theme={null}
{
  "name": "jerrie@...",
  "picture": "https://s.gravatar.com/avatar/6222081fd7dcea7dfb193788d138c457?s=480&r=pg&d=https%3A%2F%2Fcdn.auth0.com%2Favatars%2Fje.png",
  "iss": "https://auth0pnp.auth0.com/",
  "sub": "auth0|581...",
  "aud": "xvt...",
  "exp": 1478113129,
  "iat": 1478077129
}
```

### Request user log in with GitHub

In addition to the usual user authentication, this example shows how to send users directly to a social identity provider, such as GitHub. You will first need to configure the appropriate connection in [Auth0 Dashboard > Authentication > Social](https://manage.auth0.com/#/connections/social) and get the connection name from the **Settings** tab.

To send users directly to the GitHub login screen, you need to pass the `connection` parameter and set its value to the connection name (in this case, `github`) when authorizing the user in step 1:

<AuthCodeBlock />

Now, when you request tokens, your ID Token will contain a `sub` claim with the user's unique ID returned from GitHub. When you decode the ID token, it will look similar to:

```json lines theme={null}
{
  "name": "Jerrie Pelser",
  "nickname": "jerriep",
  "picture": "https://avatars.githubusercontent.com/u/1006420?v=3",
  "iss": "https://auth0pnp.auth0.com/",
  "sub": "github|100...",
  "aud": "xvt...",
  "exp": 1478114742,
  "iat": 1478078742
}
```

## Learn more

* [OAuth 2.0 Authorization Framework](/docs/authenticate/protocols/oauth)
* [OpenID Connect Protocol](/docs/authenticate/protocols/openid-connect-protocol)
* [Tokens](/docs/secure/tokens)
* [Register Regular Web Applications](/docs/get-started/auth0-overview/create-applications/regular-web-apps)
* [Update Grant Types](/docs/get-started/applications/update-grant-types)


# Authorization Code Flow with JWT-Secured Authorization Requests (JAR)
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-jar

Learn how to use JWT-Secured Authorization Requests (JAR) with the Authorization Code Flow.

<Callout icon="file-lines">
  To use Highly Regulated Identity features, you must have an Enterprise Plan with the Highly Regulated Identity add-on. Refer to [Auth0 Pricing](https://auth0.com/pricing/) for details.
</Callout>

[JWT-Secured Authorization Request (JAR)](https://datatracker.ietf.org/doc/html/rfc9101) is an extension of the OAuth 2.0 protocol that protects the integrity and authenticity of authorization request parameters. By wrapping parameters in a signed [JSON Web Token (JWT)](/docs/secure/tokens/json-web-tokens), you prevent intermediaries from tampering with or viewing sensitive request data.

## Prerequisites

Before using JAR, you must:

1. [Generate a RSA key pair](/docs/secure/application-credentials/generate-rsa-key-pair)
2. Register the public key by uploading it to the Auth0 Dashboard as described in [Configure JWT-Secured Authorization Requests](/docs/get-started/applications/configure-jar)

## How it works

Instead of passing parameters like `scope` or `redirect_uri` as plain text in a URL, the client application wraps them into a signed [JSON Web Token (JWT)](/docs/secure/tokens/json-web-tokens) as the request object:

* Signing: The client application signs the JWT using its private key.
* Verification: The Auth0 Authorization Server receives the JWT and verifies the signature using the public key you registered.
* Processing: If valid, the Auth0 Authorization Server extracts the parameters. If a parameter exists in both the JAR and the query string, the value inside the JAR takes precedence.

## Generate the JAR request

Use the [Auth0 JWT library](https://jwt.io/libraries) to generate a <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> in your preferred language.

### Header

The JWT header tells Auth0 which key and algorithm to use for verification. It must have the following parameters:

* `alg`: The algorithm used to sign the JWT. Must be either RS256, RS384, or PS256.
* `typ`: The type of JWT. Must be either `jwt` or `oauth-authz-req+jwt`.

The header may also contain a `kid` field that identifies the key used to sign the JWT. If a `kid` is present, Auth0 will look for a public key registered during [JAR configuration](/docs/get-started/applications/configure-jar) that has a matching key ID and use that key to verify the JWT’s signature.

### Payload

The payload contains the authorization parameters. It must contain the following claims:

* `iss`: This must contain your app’s `client_id`
* `aud`: This must be your tenant’s domain, with the protocol and a trailing forward slash. For example, `https://{YOUR_DOMAIN}.auth0.com/`

The JWT must also contain any mandatory parameters for the call to `/authorize`. For example:

* `client_id`: This must also contain your app’s `client_id`
* `response_type`: Indicates to Auth0 which <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> flow you want to perform. Use `code` for Authorization Code Grant Flow.

The JWT may contain any of the optional parameters for the <Tooltip href="/docs/glossary?term=authorization+flow">authorization flow</Tooltip> that is being requested, such as `audience`, `scope`, `state`, `redirect_uri`, among others.

In addition, the JWT may contain the following optional claims:

* `iat`: Must be a numeric date.
* `nbf`: Must be a numeric date, representing a time in the past.
* `exp`: Must be a numeric date, representing a time in the future.
* `jti`: Must be a string no longer than 64 bytes.

## Code sample: Generate and sign JAR

The following Node.js example uses the [jsonwebtoken library](https://www.npmjs.com/package/jsonwebtoken?activeTab=readme) to generate and sign a JAR:

```javascript lines expandable theme={null}
const jwt = require('jsonwebtoken');
const crypto = require("crypto");
const fs = require('fs');

const privateKey = fs.readFileSync('{PATH_TO_YOUR_PEM_FILE}');
const client_id = '{YOUR_CLIENT_ID}';
const nonce = crypto.randomBytes(16).toString('hex');

const requestObject = jwt.sign(
{
  iss: client_id,    
  aud: 'https://your_tenant.auth0.com/', // your tenant's domain
  client_id,
  response_type: "code",
  scope: "openid profile",
  redirect_uri : "https://myapp.com/callback", // your app's callback URL
  nonce
},
privateKey,
{
  keyid: '{YOUR_KID}', // optional key id (kid) value from your public key
  algorithm: 'RS256',
  header: {
    typ: 'oauth-authz-req+jwt',
  },
});

console.log(requestObject);
```

## Call the authorization endpoint

You can send the JAR to the Auth0 Authorization Server in the following ways:

1. [Standard JAR request](#standard-jar-request): Pass the signed JWT as a URL-encoded string in the request parameter.
2. [Pushed Authorization Request](#pushed-authorization-request): For enhanced security and to avoid URL length constraints, use PAR.

### Standard JAR request

To call the `/authorize` endpoint using a standard JAR request:

1. Open a new browser window.
2. Pass your <Tooltip href="/docs/glossary?term=Client+ID">client ID</Tooltip> as the `client_id` parameter and the signed and URL-encoded JWT as the `request` parameter.

```bash lines theme={null}
# MacOS
open "https://{YOUR_DOMAIN}.auth0.com/authorize?client_id={YOUR_CLIENT_ID}&request={URL_ENCODED_JWT}"

# Windows
explorer "https://{YOUR_DOMAIN}.auth0.com/authorize?client_id={YOUR_CLIENT_ID}&request={URL_ENCODED_JWT}"
```

### Pushed Authorization Request

To call the `/authorize` endpoint with a pushed authorization request:

1. Send the JAR to the `/oauth/par` endpoint via a back-channel `POST` request.
2. Auth0 will return a `request_uri`, which you can then use to call the `/authorize` endpoint as in a [regular PAR flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-par).

The following cURL request uses PAR and JAR together:

```bash lines theme={null}
curl --location 'https://{YOUR_DOMAIN}.auth0.com/oauth/par' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={YOUR_CLIENT_ID}' \
--data-urlencode 'client_secret={YOUR_CLIENT_SECRET}' \
--data-urlencode 'request={JWT}'
```

## Learn more

* [Configure JWT-secured Authorization Requests (JAR)](/docs/get-started/applications/configure-jar)


# Authorization Code Flow with Pushed Authorization Requests (PAR)
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-par

Learn how to use Pushed Authorization Requests (PAR) with the Authorization Code Flow.

<Callout icon="file-lines">
  To use Highly Regulated Identity features, you must have an Enterprise Plan with the Highly Regulated Identity add-on. Refer to [Auth0 Pricing](https://auth0.com/pricing/) for details.
</Callout>

[Pushed Authorization Request (PAR)](https://datatracker.ietf.org/doc/html/rfc9126) is a backend protocol to push authorization requests directly to the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip>. It is a technical component of the [Financial-Grade API (FAPI) Security Profile 1.0](https://openid.net/specs/openid-financial-api-part-2-1_0.html) tasked with protecting APIs in high-value scenarios.

## How it works

PAR allows your application to push the parameters for <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> authorization requests directly to the authorization server’s PAR endpoint **(1)**. In response, the authorization server sends a request URI value, `request_uri` **(2)**, to use when you call the `/authorize` endpoint **(3)**. The `request_uri` is a reference to the stored authorization requests at the `/par` endpoint so these requests are not exposed **(4)**. To learn more, read [Configure Push Authorization Requests](/docs/get-started/applications/configure-par).

<Frame>
  <img alt="" />
</Frame>

## Benefits

One benefit of using PAR is early validation. In other OAuth 2.0 flows, such as the [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow), end users are redirected to the authorization server for validation. In PAR, request parameters are validated at the beginning of the authorization request before the end user is redirected. It is not ideal to redirect users to show them an error page.

PAR also passes authorization requests on the back channel. Front-channel communications rely on an intermediary (e.g. a browser) via appended HTTPS query parameters (GET, POST). Messages are not sent directly. Back-channel communications are passed in the body of an authenticated backend request for a more direct approach.

Push authorization requests travel via the back-channel, which means:

* The authorization server can trust where the request is coming from, and the requests have not been modified by an end user.
* The request details have not been exposed at the browser bar or history and privacy is preserved at that point of the chain.
* Restrictions on URL length are not a constraint.

## Limitations

* Maximum request payload size is limited to 10 KB.
* Public applications are not currently supported. To learn more, read [Public and Confidential Applications](/docs/get-started/applications/confidential-and-public-applications).

## Call the PAR endpoint

### Requirements

To make a call to the PAR endpoint, you must:

* Set the request content type as `application/x-www-form-urlencoded`.
* Use strings for all passed parameters.
* Include an additional parameter for the application authentication method in the request. Only <Tooltip href="/docs/glossary?term=confidential+clients">confidential clients</Tooltip> support PAR, so the following [application authentication methods](https://auth0.com/docs/api/authentication#authentication-methods) are available: <Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip>, Private Key <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip>, and mTLS. You must use the same application authentication method for the `/token` endpoint when retrieving an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>.

### Supported parameters

PAR endpoint only stores and processes:

* Standard OAuth 2.0 parameters and applicable extensions, which we recognize at the authorization endpoint.
* Up to 10 custom authorization parameters prefixed with `ext-` prefix.

PAR ignores additional custom authorization parameters. Custom authorization parameters are not available in [Auth0 Actions](/docs/customize/actions) and [Logs](/docs/deploy-monitor/logs).

<Callout icon="file-lines">
  If you use custom authorization parameters in Actions, you must prefix them with `ext-`. Otherwise, they will not be available.
</Callout>

### Example PAR request

```bash lines theme={null}
curl --location --request POST https://$tenant/oauth/par \
  -H "content-type: application/x-www-form-urlencoded" \
  -d "client_id=CLIENT_ID"\
"&client_secret=CLIENT_SECRET"\
"&redirect_uri=https://jwt.io"\
"&audience=urn:my-notes-api"\
"&scope=openid%20profile%20read:notes"\
"&response_type=code"
```

### Example PAR Response

In the following example PAR response:

* The `request_uri` is a reference for the stored authorization requests. The request values pass to the GET `/authorize` endpoint as the `request_uri` parameter.
* The `expires_in` is the number of seconds the `request_uri` is valid. After this time frame, the `request_uri` expires if not used. The thirty-second expiration time is a static value and can’t be configured.

```json lines theme={null}
HTTP/1.1 201 Created
 Content-Type: application/json

 {
  "request_uri":
    "urn:ietf:params:oauth:request_uri:6esc_11ACC5bwc014ltc14eY22c",
  "expires_in": 30
 }
```

### Rate limits

For Essential, Professional, and Enterprise production tenants, calls to the PAR endpoint are included in the standard Authentication API rate limit. For more information, see [Rate Limit Configurations](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations) and click your subscription type. Then, click **Authentication API**.

## Call the authorization endpoint

Your application uses the `request_uri` value returned from the `/oauth/par` endpoint in the authorization request and redirects the user agent to the authorization endpoint. To learn more about the `request_uri` parameter, read [Configure Push Authorization Requests](/docs/get-started/applications/configure-par).

The following example directs the user agent to make the following HTTP request:

```http wrap lines theme={null}
GET /authorize?client_id=CLIENT_ID&request_uri=urn%3Aietf%3Aparam...qrwSI HTTP/1.1 Host: TENANT.auth0.com
```

In the case of a valid `request_uri`, the rest of the <Tooltip href="/docs/glossary?term=authorization+flow">authorization flow</Tooltip> looks the same.

### Validation

* PAR is validated by the authorization server at this stage again like any other authorization request.
* `request_uri` value can be used only one time.
* An expired `request_uri` will be rejected by the authorization server.
* A non-PAR request is rejected if PAR is required either on the tenant or client level.

## Learn more

* [Configure Pushed Authorization Requests (PAR)](/docs/get-started/applications/configure-par)


# Authorization Code Flow with Rich Authorization Requests (RAR)
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-rar

Learn how to use Rich Authorization Requests (RAR) with the Authorization Code Flow.

Using [Rich Authorization Requests (RAR)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-rar), clients can request and obtain <Tooltip href="/docs/glossary?term=fine-grained+authorization">fine-grained authorization</Tooltip> data from <Tooltip href="/docs/glossary?term=resource+owners">resource owners</Tooltip>, such as end users.  Clients can pass RAR data to the Pushed Authorization Request (PAR) endpoint as part of the Authorization Code Flow. To learn more, read [Configure Pushed Authorization Requests](/docs/get-started/applications/configure-par).

In a traditional <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> flow, when a client requests access to a <Tooltip href="/docs/glossary?term=resource+server">resource server</Tooltip> using [scopes](/docs/get-started/apis/scopes), the resource owner grants the client access to those resources. In a Rich Authorization Request, clients can pass an `authorization_details` parameter to the `/par` endpoint to request more granular permissions than those requested in scopes. This allows for more fine-grained control over resource access for both clients and resource owners, mitigating security risks associated with over-provisioning access.

Because Auth0 only supports validating `authorization_details` types, you must implement validation for the JSON objects in `authorization_details`. To learn more, read [Configure Rich Authorization Requests](/docs/get-started/apis/configure-rich-authorization-requests).

## How it works

In a Rich Authorization Request, the `authorization_details` parameter is a JSON array of objects, each of which must include a `type` field represented as a string. The `type` field determines the customizable object fields. An `authorization_details` array may contain multiple entries of the same type. To learn more about how to register `authorization_details` types, read [Configure Rich Authorization Requests](/docs/get-started/apis/configure-rich-authorization-requests).

Auth0 presents the `authorization_details` to the user to authorize in a custom consent screen. To learn more, read [Set customized consent prompt](/docs/get-started/apis/configure-rich-authorization-requests#set-customized-consent-prompt).

You must pass the `authorization_details` parameter to the `/par` endpoint, which enables the Auth0 <Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip> to perform early validation of the `type`. The `/par` endpoint passes authorization requests on the back channel to avoid sensitive data leaking in the front channel, such as the browser. Once you’ve passed the authorization request to the `/par` endpoint, the application will redirect to the `/authorize` endpoint and then proceed with the Authorization Code Flow. To learn more, read [Authorization Code Flow with PAR](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-par).

To complete the Authorization Code Flow, exchange the authorization code at the `/oauth/token` endpoint, as in the following example:

```http lines theme={null}
POST https://{YOUR_DOMAIN}.auth0.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id={YOUR_CLIENT_ID}&client_secret={YOUR_CLIENT_SECRET}&code={AUTHORIZATION_CODE}&redirect_uri=https://jwt.io
```

When successful, you should receive a response with the <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> and `authorization_details` array:

```json lines theme={null}
{
  "access_token": "ey...ZQ",
  "expires_in": 86400,
  "authorization_details": [
{
  "type": "money_transfer", 
  "instructedAmount": {"amount": 2500, "currency": "USD"},   
  "sourceAccount": "xxxxxxxxxxx1234", 
  "destinationAccount": "xxxxxxxxxxx9876", 
  "beneficiary": "Hanna Herwitz", 
  "subject": "A Lannister Always Pays His Debts"
}
  ],
  "token_type": "Bearer"
}
```

As part of [JWT best practices](https://datatracker.ietf.org/doc/html/rfc9068#name-privacy-considerations), the client can use `authorization_details` to understand the scope of the authorization granted to it without having to inspect the access token. If the requested <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> is an API that requires [JWE access tokens](/docs/secure/tokens/json-web-tokens), the `/oauth/token`endpoint returns a response that omits all object fields except for `type` from `authorization_details`. Access token claims are unaffected in the response.

```json lines theme={null}
{
  "iss": "https://my_tenant.auth0.com/",
  "sub": "auth0|me",
  "aud": "https://myapi.authzero.com",
  "iat": 1683661385,
  "exp": 1683747785,
  "azp": "my_client",
  "authorization_details": [
{
  "type": "money_transfer", 
  "instructedAmount": {"amount": 2500, "currency": "USD"},   
  "sourceAccount": "xxxxxxxxxxx1234", 
  "destinationAccount": "xxxxxxxxxxx9876", 
  "beneficiary": "Hanna Herwitz", 
  "subject": "A Lannister Always Pays His Debts"
}
  ]
}
```

## Configure RAR for the Authorization Code Flow

Before configuring Rich Authorization Requests for the Authorization Code Flow, you must:

* Create a [custom domain](/docs/customize/custom-domains).
* Create a [custom Universal Login Pages](/docs/customize/login-pages/universal-login/customize-templates) template. To learn how to customize a <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> Page template, read the [Page templates API](/docs/customize/login-pages/universal-login/customize-templates#page-templates-api) documentation.

To configure RAR for the Authorization Code Flow, you need to:

* Register `authorization_details` types for a resource server.
* Set the customized consent prompt.

To learn more, read [Configure Rich Authorization Requests](/docs/get-started/apis/configure-rich-authorization-requests).

## Access `authorization_details` in Actions

<Callout icon="file-lines">
  Auth0 does not support updating RAR using Actions.
</Callout>

Auth0 exposes the `authorization_details` parameter in the [post-login Action](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object) via the `event.transaction.requested_authorization_details` property. You can reference this property in an Action to show transaction details to the user in an [MFA challenge](/docs/secure/highly-regulated-identity/transactional-authorization-with-authorization-code-flow#push-notifications).

## What doesn’t Auth0 support?

Auth0 doesn’t support:

* Updating RAR using Actions.
* Advertising RAR types for clients to discover.
* Validating RAR objects beyond checking that they have a type property that matches allowed types for the API. For more information, see [Configure RAR](/docs/get-started/apis/configure-rich-authorization-requests).

## Learn more

* [Configure Rich Authorization Requests (RAR)](/docs/get-started/apis/configure-rich-authorization-requests)


# Call Your API Using the Authorization Code Flow
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/call-your-api-using-the-authorization-code-flow

Learn how to call your own API from regular web apps using the Authorization Code Flow.

<Callout icon="file-lines">
  This tutorial will help you call your own API using the Authorization Code Flow. If you want to learn how the flow works and why you should use it, see [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow). If you want to learn to add login to your regular web app, see [Add Login Using the Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/add-login-auth-code-flow).
</Callout>

Auth0 makes it easy for your app to implement the <Tooltip href="/docs/glossary?term=Authorization+Code">Authorization Code</Tooltip> Flow using:

* [Regular Web App Quickstarts](/docs/quickstart/webapp): The easiest way to implement the flow.
* [Authentication API](https://auth0.com/docs/api/authentication): If you prefer to build your own solution, keep reading to learn how to call our API directly.

## Prerequisites

**Before beginning this tutorial:**

* [Register your Application with Auth0](/docs/get-started/auth0-overview/create-applications/regular-web-apps).

  * Select an **Application Type** of **Regular Web Apps**.
  * Add an **Allowed Callback URL** of `{https://yourApp/callback}`.
  * Make sure your Application's **Grant Types** include **Authorization Code**. To learn how, read [Update Grant Types](/docs/get-started/applications/update-grant-types).
  * If you want your Application to be able to use [refresh tokens](/docs/secure/tokens/refresh-tokens), make sure the Application's **Grant Types** include **refresh token**. To learn how, read [Update Grant Types](/docs/get-started/applications/update-grant-types). To learn more about Refresh Tokens, read [refresh tokens](/docs/secure/tokens/refresh-tokens).
* [Register your API with Auth0](/docs/get-started/auth0-overview/set-up-apis)

  * If you want your API to receive refresh tokens to allow it to obtain new tokens when the previous ones expire, enable **Allow Offline Access**.

## Steps

<AccordionGroup>
  <Accordion icon="circle-1" title="Authorize user">
    This step may include one or more of the following processes:

    * Authenticating the user
    * Redirecting the user to an Identity Provider to handle authentication
    * Checking for active Single Sign-on (SSO) sessions
    * Obtaining user consent for the requested permission level, unless consent has been previously given.

    To authorize the user, your app must send the user to the [authorization URL](https://auth0.com/docs/api/authentication#authorization-code-grant).

    #### Example authorization URL

    <AuthCodeBlock />

    ##### Parameters

    Note that for authorizing a user when calling a custom API, you:

    * must include an audience parameter
    * can include additional scopes supported by the target API

    <table>
      <thead>
        <tr>
          <th>Parameter Name</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>response\_type</code></td>
          <td>Denotes the kind of credential that Auth0 will return (<code>code</code> or <code>token</code>). For this flow, the value must be <code>code</code>.</td>
        </tr>

        <tr>
          <td><code>client\_id</code></td>
          <td>Your application's Client ID. You can find this value in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>.</td>
        </tr>

        <tr>
          <td><code>redirect\_uri</code></td>
          <td>The URL to which Auth0 will redirect the browser after authorization has been granted by the user. The Authorization Code will be available in the <code>code</code> URL parameter. You must specify this URL as a valid callback URL in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>. <br /> <br /> <strong>Warning:</strong> Per the <a href="https://tools.ietf.org/html/rfc6749#section-3.1.2">OAuth 2.0 Specification</a>, Auth0 removes everything after the hash and does <em>not</em> honor any fragments.</td>
        </tr>

        <tr>
          <td><code>scope</code></td>
          <td>Specifies the <a href="/docs/get-started/apis/scopes">scopes</a> for which you want to request authorization, which dictate which claims (or user attributes) you want returned. These must be separated by a space. You can request any of the <a href="https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims">standard OpenID Connect (OIDC) scopes</a> about users, such as <code>profile</code> or <code>email</code>, <a href="/docs/secure/tokens/json-web-tokens/json-web-token-claims#custom-claims">custom claims</a> conforming to a <a href="/docs/secure/tokens/json-web-tokens/create-custom-claims">namespaced format</a>, or any scopes supported by the target API (e.g., <code>read:contacts</code>). Include <code>offline\_access</code> to get a <Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip> (make sure that the <strong>Allow Offline Access</strong> field is enabled in the <a href="https://manage.auth0.com/#/applications">Application Settings</a>).</td>
        </tr>

        <tr>
          <td><code>audience</code></td>
          <td>The unique identifier of the API your web app wants to access. Use the <strong>Identifier</strong> value on the <a href="https://manage.auth0.com/#/apis">Settings</a> tab for the API you created as part of the prerequisites for this tutorial.</td>
        </tr>

        <tr>
          <td><code>state</code></td>
          <td>(recommended) An opaque arbitrary alphanumeric string your app adds to the initial request that Auth0 includes when redirecting back to your application. To see how to use this value to prevent cross-site request forgery (CSRF) attacks, see <a href="/docs/secure/attack-protection/state-parameters">Mitigate CSRF Attacks With State Parameters</a>.</td>
        </tr>

        <tr>
          <td><code>organization</code></td>
          <td>(optional) ID of the organization to use when authenticating a user. When not provided, if your application is configured to <strong>Display Organization Prompt</strong>, the user will be able to enter the organization name when authenticating.</td>
        </tr>

        <tr>
          <td><code>invitation</code></td>
          <td>(optional) Ticket ID of the organization invitation. When <a href="/docs/manage-users/organizations/configure-organizations/invite-members">inviting a member to an Organization</a>, your application should handle invitation acceptance by forwarding the <code>invitation</code> and <code>organization</code> key-value pairs when the user accepts the invitation.</td>
        </tr>
      </tbody>
    </table>

    As an example, your HTML snippet for your authorization URL when adding login to your app might look like:

    <AuthCodeBlock />

    #### Response

    If all goes well, you'll receive an `HTTP 302` response. The authorization code is included at the end of the URL:

    ```http lines theme={null}
    HTTP/1.1 302 Found
    Location: {https://yourApp/callback}?code={authorizationCode}&state=xyzABC123
    ```
  </Accordion>

  <Accordion icon="circle-2" title="Request tokens">
    Now that you have an Authorization Code, you must exchange it for tokens. Using the extracted Authorization Code (`code`) from the previous step, you will need to `POST` to the [token URL](https://auth0.com/docs/api/authentication#authorization-code).

    #### Example POST to token URL

    <AuthCodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
        --url 'https://{yourDomain}/oauth/token' \
        --header 'content-type: application/x-www-form-urlencoded' \
        --data grant_type=authorization_code \
        --data 'client_id={yourClientId}' \
        --data 'client_secret={yourClientSecret}' \
        --data 'code=yourAuthorizationCode}' \
        --data 'redirect_uri={https://yourApp/callback}'
      ```

      ```csharp C# theme={null}
      var client = new RestClient("https://{yourDomain}/oauth/token");
      var request = new RestRequest(Method.POST);
      request.AddHeader("content-type", "application/x-www-form-urlencoded");
      request.AddParameter("application/x-www-form-urlencoded", "grant_type=authorization_code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&code=yourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}", ParameterType.RequestBody);
      IRestResponse response = client.Execute(request);
      ```

      ```go Go theme={null}
      package main

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

      func main() {

      	url := "https://{yourDomain}/oauth/token"

      	payload := strings.NewReader("grant_type=authorization_code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&code=yourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}")

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

      	req.Header.Add("content-type", "application/x-www-form-urlencoded")

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

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

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

      }
      ```

      ```java Java theme={null}
      HttpResponse response = Unirest.post("https://{yourDomain}/oauth/token")
        .header("content-type", "application/x-www-form-urlencoded")
        .body("grant_type=authorization_code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&code=yourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}")
        .asString();
      ```

      ```javascript Node.JS theme={null}
      var axios = require("axios").default;

      var options = {
        method: 'POST',
        url: 'https://{yourDomain}/oauth/token',
        headers: {'content-type': 'application/x-www-form-urlencoded'},
        data: new URLSearchParams({
          grant_type: 'authorization_code',
          client_id: '{yourClientId}',
          client_secret: '{yourClientSecret}',
          code: 'yourAuthorizationCode}',
          redirect_uri: '{https://yourApp/callback}'
        })
      };

      axios.request(options).then(function (response) {
        console.log(response.data);
      }).catch(function (error) {
        console.error(error);
      });
      ```

      ```objc Obj-C theme={null}
      #import <Foundation/Foundation.h>

      NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

      NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=authorization_code" dataUsingEncoding:NSUTF8StringEncoding]];
      [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
      [postData appendData:[@"&client_secret={yourClientSecret}" dataUsingEncoding:NSUTF8StringEncoding]];
      [postData appendData:[@"&code=yourAuthorizationCode}" dataUsingEncoding:NSUTF8StringEncoding]];
      [postData appendData:[@"&redirect_uri={https://yourApp/callback}" dataUsingEncoding:NSUTF8StringEncoding]];

      NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                             cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                         timeoutInterval:10.0];
      [request setHTTPMethod:@"POST"];
      [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];
      ```

      ```php PHP theme={null}
      $curl = curl_init();

      curl_setopt_array($curl, [
        CURLOPT_URL => "https://{yourDomain}/oauth/token",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => "",
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => "POST",
        CURLOPT_POSTFIELDS => "grant_type=authorization_code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&code=yourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}",
        CURLOPT_HTTPHEADER => [
          "content-type: application/x-www-form-urlencoded"
        ],
      ]);

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

      curl_close($curl);

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

      ```python Python theme={null}
      import http.client
      conn = http.client.HTTPSConnection("")
      payload = "grant_type=authorization_code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&code=yourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}"
      headers = { 'content-type': "application/x-www-form-urlencoded" }
      conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)
      res = conn.getresponse()
      data = res.read()
      print(data.decode("utf-8"))
      ```

      ```ruby Ruby theme={null}
      require 'uri'
      require 'net/http'
      require 'openssl'

      url = URI("https://{yourDomain}/oauth/token")

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

      request = Net::HTTP::Post.new(url)
      request["content-type"] = 'application/x-www-form-urlencoded'
      request.body = "grant_type=authorization_code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&code=yourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}"

      response = http.request(request)
      puts response.read_body
      ```

      ```swift Swift theme={null}
      import Foundation

      let headers = ["content-type": "application/x-www-form-urlencoded"]

      let postData = NSMutableData(data: "grant_type=authorization_code".data(using: String.Encoding.utf8)!)
      postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
      postData.append("&client_secret={yourClientSecret}".data(using: String.Encoding.utf8)!)
      postData.append("&code=yourAuthorizationCode}".data(using: String.Encoding.utf8)!)
      postData.append("&redirect_uri={https://yourApp/callback}".data(using: String.Encoding.utf8)!)

      let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                              cachePolicy: .useProtocolCachePolicy,
                                          timeoutInterval: 10.0)
      request.httpMethod = "POST"
      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()
      ```
    </AuthCodeGroup>

    ##### Parameters

    <table>
      <thead>
        <tr>
          <th>Parameter Name</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>grant\_type</code></td>
          <td>Set this to <code>authorization\_code</code>.</td>
        </tr>

        <tr>
          <td><code>code</code></td>
          <td>The <code>authorization\_code</code> retrieved in the previous step of this tutorial.</td>
        </tr>

        <tr>
          <td><code>client\_id</code></td>
          <td>Your application's Client ID. You can find this value in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>.</td>
        </tr>

        <tr>
          <td><code>client\_secret</code></td>
          <td>Your application's Client Secret. You can find this value in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>.  To learn more about available application authentication methods, read <a href="/docs/secure/application-credentials">Application Credentials</a>.</td>
        </tr>

        <tr>
          <td><code>redirect\_uri</code></td>
          <td>The valid callback URL set in your Application settings. This must exactly match the <code>redirect\_uri</code> passed to the authorization URL in the previous step of this tutorial. Note that this must be URL encoded.</td>
        </tr>
      </tbody>
    </table>

    #### Response

    If all goes well, you'll receive an `HTTP 200` response with a payload containing `access_token`, `refresh_token`, `id_token`, and `token_type` values:

    ```json lines theme={null}
    {
      "access_token": "eyJz93a...k4laUWw",
      "refresh_token": "GEbRxBN...edjnXbL",
      "id_token": "eyJ0XAi...4faeEoQ",
      "token_type": "Bearer"
    }
    ```

    <Warning>
      Validate your tokens before saving them. To learn how, read [Validate ID Tokens](/docs/secure/tokens/id-tokens/validate-id-tokens) and [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens).
    </Warning>

    [ID tokens](/docs/secure/tokens/id-tokens) contain user information that must be decoded and extracted.

    [Access tokens](/docs/secure/tokens/access-tokens) are used to call the [Auth0 Authentication API's /userinfo endpoint](https://auth0.com/docs/api/authentication#get-user-info) or another API. If you are calling your own API, the first thing your API will need to do is [verify the Access token](/docs/secure/tokens/access-tokens/validate-access-tokens).

    [Refresh tokens](/docs/secure/tokens/refresh-tokens) are used to obtain a new access token or ID token after the previous one has expired. The `refresh_token` will only be present in the response if you included the `offline_access` scope and enabled **Allow Offline Access** for your API in the Dashboard.

    <Warning>
      Refresh tokens must be stored securely since they allow a user to remain authenticated essentially forever.
    </Warning>
  </Accordion>

  <Accordion icon="circle-3" title="Make an API call">
    To call your API from a regular web application, the application must pass the retrieved access token as a Bearer token in the Authorization header of your HTTP request.

    <AuthCodeGroup>
      ```bash cURL lines theme={null}
      curl --request GET \
        --url https://myapi.com/api \
        --header 'authorization: Bearer {accessToken}' \
        --header 'content-type: application/json'
      ```

      ```csharp C# lines theme={null}
      var client = new RestClient("https://myapi.com/api");
      var request = new RestRequest(Method.GET);
      request.AddHeader("content-type", "application/json");
      request.AddHeader("authorization", "Bearer {accessToken}");
      IRestResponse response = client.Execute(request);
      ```

      ```go Go lines expandable theme={null}
      package main

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

      func main() {

      	url := "https://myapi.com/api"

      	req, _ := http.NewRequest("GET", url, nil)

      	req.Header.Add("content-type", "application/json")
      	req.Header.Add("authorization", "Bearer {accessToken}")

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

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

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

      }

      ```

      ```java Java lines theme={null}
      HttpResponse response = Unirest.get("https://myapi.com/api")
        .header("content-type", "application/json")
        .header("authorization", "Bearer {accessToken}")
        .asString();
      ```

      ```javascript Node.JS lines theme={null}
      var axios = require("axios").default;

      var options = {
        method: 'GET',
        url: 'https://myapi.com/api',
        headers: {'content-type': 'application/json', authorization: 'Bearer {accessToken}'}
      };

      axios.request(options).then(function (response) {
        console.log(response.data);
      }).catch(function (error) {
        console.error(error);
      });

      ```

      ```objc Obj-C lines theme={null}
      #import <Foundation/Foundation.h>

      NSDictionary *headers = @{ @"content-type": @"application/json",
                                 @"authorization": @"Bearer {accessToken}" };

      NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://myapi.com/api"]
                                                             cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                         timeoutInterval:10.0];
      [request setHTTPMethod:@"GET"];
      [request setAllHTTPHeaderFields:headers];

      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];

      ```

      ```php PHP lines expandable theme={null}
      $curl = curl_init();

      curl_setopt_array($curl, [
        CURLOPT_URL => "https://myapi.com/api",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => "",
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => "GET",
        CURLOPT_HTTPHEADER => [
          "authorization: Bearer {accessToken}",
          "content-type: application/json"
        ],
      ]);

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

      curl_close($curl);

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

      ```python Python lines theme={null}
      import http.client

      conn = http.client.HTTPSConnection("myapi.com")

      headers = {
          'content-type': "application/json",
          'authorization': "Bearer {accessToken}"
          }

      conn.request("GET", "/api", headers=headers)

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

      print(data.decode("utf-8"))
      ```

      ```ruby Ruby lines theme={null}
      require 'uri'
      require 'net/http'
      require 'openssl'
      url = URI("https://myapi.com/api")
      http = Net::HTTP.new(url.host, url.port)
      http.use_ssl = true
      http.verify_mode = OpenSSL::SSL::VERIFY_NONE
      request = Net::HTTP::Get.new(url)
      request["content-type"] = 'application/json'
      request["authorization"] = 'Bearer {accessToken}'
      response = http.request(request)
      puts response.read_body
      ```

      ```swift Swift lines theme={null}
      import Foundation

      let headers = [
        "content-type": "application/json",
        "authorization": "Bearer {accessToken}"
      ]

      let request = NSMutableURLRequest(url: NSURL(string: "https://myapi.com/api")! as URL,
                                              cachePolicy: .useProtocolCachePolicy,
                                          timeoutInterval: 10.0)
      request.httpMethod = "GET"
      request.allHTTPHeaderFields = headers

      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()
      ```
    </AuthCodeGroup>
  </Accordion>

  <Accordion icon="circle-4" title="Exchange refresh token">
    You have already received a [refresh token](/docs/secure/tokens/refresh-tokens) if you've been following this tutorial and completed the following:

    * configured your API to allow offline access
    * included the `offline_access` scope when you initiated the authentication request through the [authorize endpoint](https://auth0.com/docs/api/authentication/reference#authorize-application).

    You can use the Refresh Token to get a new access token. Usually, a user will need a new access token only after the previous one expires or when gaining access to a new resource for the first time. It's bad practice to call the endpoint to get a new access token every time you call an API, and Auth0 maintains rate limits that will throttle the amount of requests to the endpoint that can be executed using the same token from the same IP.

    To refresh your token, make a `POST` request to the `/oauth/token` endpoint in the Authentication API, using `grant_type=refresh_token`.

    ##### Example POST to token URL

    <AuthCodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
        --url 'https://{yourDomain}/oauth/token' \
        --header 'content-type: application/x-www-form-urlencoded' \
        --data grant_type=refresh_token \
        --data 'client_id={yourClientId}' \
        --data 'refresh_token={yourRefreshToken}'
      ```

      ```csharp C# theme={null}
      var client = new RestClient("https://{yourDomain}/oauth/token");
      var request = new RestRequest(Method.POST);
      request.AddHeader("content-type", "application/x-www-form-urlencoded");
      request.AddParameter("application/x-www-form-urlencoded", "grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D", ParameterType.RequestBody);
      IRestResponse response = client.Execute(request);
      ```

      ```go Go theme={null}
      package main

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

      func main() {

      	url := "https://{yourDomain}/oauth/token"

      	payload := strings.NewReader("grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D")

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

      	req.Header.Add("content-type", "application/x-www-form-urlencoded")

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

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

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

      }
      ```

      ```java Java theme={null}
      HttpResponse response = Unirest.post("https://{yourDomain}/oauth/token")
        .header("content-type", "application/x-www-form-urlencoded")
        .body("grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D")
        .asString();
      ```

      ```javascript Node.JS theme={null}
      var axios = require("axios").default;

      var options = {
        method: 'POST',
        url: 'https://{yourDomain}/oauth/token',
        headers: {'content-type': 'application/x-www-form-urlencoded'},
        data: new URLSearchParams({
          grant_type: 'refresh_token',
          client_id: '{yourClientId}',
          refresh_token: '{yourRefreshToken}'
        })
      };

      axios.request(options).then(function (response) {
        console.log(response.data);
      }).catch(function (error) {
        console.error(error);
      });
      ```

      ```objc Obj-C theme={null}
      #import <Foundation/Foundation.h>

      NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

      NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=refresh_token" dataUsingEncoding:NSUTF8StringEncoding]];
      [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
      [postData appendData:[@"&refresh_token={yourRefreshToken}" dataUsingEncoding:NSUTF8StringEncoding]];

      NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                             cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                         timeoutInterval:10.0];
      [request setHTTPMethod:@"POST"];
      [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];
      ```

      ```php PHP theme={null}
      $curl = curl_init();

      curl_setopt_array($curl, [
        CURLOPT_URL => "https://{yourDomain}/oauth/token",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => "",
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => "POST",
        CURLOPT_POSTFIELDS => "grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D",
        CURLOPT_HTTPHEADER => [
          "content-type: application/x-www-form-urlencoded"
        ],
      ]);

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

      curl_close($curl);

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

      ```python Python theme={null}
      import http.client
      conn = http.client.HTTPSConnection("")
      payload = "grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D"
      headers = { 'content-type': "application/x-www-form-urlencoded" }
      conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)
      res = conn.getresponse()
      data = res.read()
      print(data.decode("utf-8"))
      ```

      ```ruby Ruby theme={null}
      require 'uri'
      require 'net/http'
      require 'openssl'
      url = URI("https://{yourDomain}/oauth/token")
      http = Net::HTTP.new(url.host, url.port)
      http.use_ssl = true
      http.verify_mode = OpenSSL::SSL::VERIFY_NONE
      request = Net::HTTP::Post.new(url)
      request["content-type"] = 'application/x-www-form-urlencoded'
      request.body = "grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D"
      response = http.request(request)
      puts response.read_body
      ```

      ```swift Swift theme={null}
      import Foundation

      let headers = ["content-type": "application/x-www-form-urlencoded"]

      let postData = NSMutableData(data: "grant_type=refresh_token".data(using: String.Encoding.utf8)!)
      postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
      postData.append("&refresh_token={yourRefreshToken}".data(using: String.Encoding.utf8)!)

      let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                              cachePolicy: .useProtocolCachePolicy,
                                          timeoutInterval: 10.0)
      request.httpMethod = "POST"
      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()
      ```
    </AuthCodeGroup>

    ###### Parameters

    <table>
      <thead>
        <tr>
          <th>Parameter Name</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>grant\_type</code></td>
          <td>Set this to <code>refresh\_token</code>.</td>
        </tr>

        <tr>
          <td><code>client\_id</code></td>
          <td>Your application's Client ID. You can find this value in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>.</td>
        </tr>

        <tr>
          <td><code>refresh\_token</code></td>
          <td>The refresh token to use.</td>
        </tr>

        <tr>
          <td><code>scope</code></td>
          <td>(optional) A space-delimited list of requested scope permissions. If not sent, the original scopes will be used; otherwise you can request a reduced set of scopes. Note that this must be URL encoded.</td>
        </tr>
      </tbody>
    </table>

    ###### Response

    If all goes well, you'll receive an `HTTP 200` response with a payload containing a new `access_token`, its lifetime in seconds (`expires_in`), granted `scope` values, and `token_type`. If the scope of the initial token included `openid`, then the response will also include a new `id_token`:

    ```json lines theme={null}
    {
      "access_token": "eyJ...MoQ",
      "expires_in": 86400,
      "scope": "openid offline_access",
      "id_token": "eyJ...0NE",
      "token_type": "Bearer"
    }
    ```

    <Warning>
      Validate your tokens before saving them. To learn how, read [Validate ID Tokens](/docs/secure/tokens/id-tokens/validate-id-tokens) and [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens).
    </Warning>
  </Accordion>
</AccordionGroup>

### Sample use cases

#### Customize tokens

You can use Auth0 Actions to modify the scopes of an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> and/or add custom claims to access and <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip>. To learn more about Actions, see [Understand how Auth0 Actions Work.](/docs/customize/actions/actions-overview)

To do so, add the following Post-Login Action, which will run after the user authenticates:

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  // Add custom claims to Access Token and ID Token
  api.accessToken.setCustomClaim('https://foo/bar', 'value');
  api.idToken.setCustomClaim('https://fiz/baz', 'some other value');

  // Modify the scope of the Access Token
  api.accessToken.addScope('foo');
  api.accessToken.addScope('bar');
};
```

<Warning>
  Auth0 returns profile information in a structured claim format as defined by the [OpenID Connect (OIDC) specification](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). This means that custom claims added to ID tokens or access tokens must [conform to guidelines and restrictions](/docs/secure/tokens/json-web-tokens/create-custom-claims) to avoid possible collisions.
</Warning>

## Learn more

* [OAuth 2.0 Authorization Framework](/docs/authenticate/protocols/oauth)
* [OpenID Connect Protocol](/docs/authenticate/protocols/openid-connect-protocol)
* [Tokens](/docs/secure/tokens)


# Client Credentials Exchange
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-exchange

Learn how Hooks can be used with the Client Credentials Exchange extensibility point, which is available for database connections and passwordless connections.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

At the Client Credentials Exchange extensibility point, Hooks let you execute custom actions when an <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> is issued through the Authentication API [`POST /oauth/token` endpoint](https://auth0.com/docs/api/authentication#client-credentials-flow) using the Client Credentials Flow. For example, you may deny the token from being issued, add custom claims to the access token, or modify its scopes. To learn more, read [Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow).

Hooks at this extensibility point are blocking (synchronous), which means they execute as part of the trigger's process and prevent the rest of the Auth0 pipeline from running until the Hook is complete.

<Callout icon="file-lines">
  The `triggerId` for the Client Credentials Exchange extensibility point is `credentials-exchange`. To learn how to create hooks for this extensibility point, read [Create Hooks](/docs/customize/hooks/create-hooks).
</Callout>

To learn about other extensibility points, read Extensibility Points.

## Starter code and parameters

When creating a Hook executed at the Client Credentials Exchange extensibility point, you may find the following starter code helpful. Parameters that can be passed into and used by the Hook function are listed at the top of the code sample.

```javascript lines expandable theme={null}
/**
@param {object} client - client information
@param {string} client.name - client name
@param {string} client.id - client ID
@param {string} client.tenant - Auth0 tenant name
@param {object} client.metadata - client metadata
@param {array|undefined} scope - either an array of strings representing the token's scope claim, or undefined
@param {string} audience - token's audience claim
@param {object} context - Auth0 context info
@param {object} context.webtask - Hook (webtask) context
@param {function} cb - function (error, accessTokenClaims)
*/

module.exports = function(client, scope, audience, context, cb) {
  var access_token = {};
  access_token.scope = scope; // do not remove this line

  // Modify scopes or add extra claims
  // access_token['https://example.com/claim'] = 'bar';
  // access_token.scope.push('extra');

  // Deny the token and respond with an OAuth2 error response
  // if (denyExchange) {
  //   // To return an HTTP 400 with { "error": "invalid_scope", "error_description": "Not authorized for this scope." }
  //   return cb(new InvalidScopeError('Not authorized for this scope.'));
  //
  //   // To return an HTTP 400 with { "error": "invalid_request", "error_description": "Not a valid request." }
  //   return cb(new InvalidRequestError('Not a valid request.'));
  //
  //   // To return an HTTP 500 with { "error": "server_error", "error_description": "A server error occurred." }
  //   return cb(new ServerError('A server error occurred.'));
  // }

  cb(null, access_token);
};
```

Please note:

* The callback function (`cb`) at the end of the sample code signals completion and must be included.

* The line `access_token.scope = scope` ensures that all granted scopes will be present in the access token. Removing it will reset all scopes, and the token will include only scopes you add with the script.

### Default response

When you run a Hook executed at the Client Credentials Exchange extensibility point, the default response object is:

```json lines theme={null}
{
  "scope": "array of strings"
}
```

### Starter code response

Once you've customized the starter code with your scopes and additional claims, you can test the Hook using the runner embedded in the Hook Editor. The runner simulates a call to the Hook with the same body and response that you would get with a Client Credentials Exchange.

<Warning>
  Executing the code using the runner requires a save, which means that the original code will be overwritten.
</Warning>

When you run a Hook based on the starter code, the response object is:

```json lines theme={null}
{
  "audience": "https://my-tenant.auth0.com/api/v2/",
  "client": {
    "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "name": "client-name",
    "tenant": "my-tenant",
    "metadata": {
      "plan": "full"
    }
  },
  "scope": [
    "read:connections"
  ]
}
```

## Sample script: Add an additional scope to the access token

In this example, we use a Hook to add an additional scope to those already existing for the access token.

```js lines theme={null}
module.exports = function(client, scope, audience, context, cb) {
    // Scopes to be added
    var access_token = {};

    // Get the scope that's currently on the Access Token
    // and add it to the object we're working with
    // Do not remove this line!
    access_token.scope = scope;

    // Append the `read:resource` scope
    access_token.scope.push('read:resource');

    // Callback to indicate completion and to return new
    // array of scopes
    cb(null, access_token);
};
```

To learn more, read [Scopes](/docs/get-started/apis/scopes).

### Response

When we run this Hook, the response object is:

```json lines theme={null}
{
  "scope": [
    "read:connections",
    "read:resource"
  ]
}
```

## Sample script: Add a claim to the access token

In this example, we add a namespaced custom claim and its value to the access token. To learn more, read [Create Namespaced Custom Claims](/docs/secure/tokens/json-web-tokens/create-custom-claims).

You can add the following as claims to the issued token:

* The `scope` property of the response object
* Any properties with namespaced property names

The extensibility point ignores all other response object properties.

<Callout icon="file-lines">
  To access a configured Hook Secret from within a hook, use `context.webtask.secrets.SECRET_NAME`.
</Callout>

```js lines theme={null}
module.exports = function(client, scope, audience, context, cb) {
    // Claims to be added
    var access_token = {};

    // New claim to add to the token
    access_token['https://example.com/foo'] = 'bar';

    // Callback to indicate completion and to return new claim
    cb(null, access_token);
  };
```

### Response

When we run this Hook, the response object is:

```json lines theme={null}
{
  "https://example.com/foo": "bar"
}
```

## Sample script: Raise an error or deny an access token

In this example, we use custom Error objects to generate OAuth2 Error Responses. (To learn more, see [OAuth2 RFC - Section 5.2 in the IETF Datatracker](https://tools.ietf.org/html/rfc6749#section-5.2).)

If a plain JavaScript error is returned in the callback, such as:

```js lines theme={null}
module.exports = function(client, scope, audience, context, cb) {
    // Callback to indicate completion and to return new claim
    cb(new Error("Unknown error occurred.");
  };
```

Then when you request a `client_credentials` grant from the `/oauth/token` endpoint, Auth0 will respond with:

```json lines theme={null}
HTTP 500
{ "error": "server_error", "error_description": "Unknown error occurred." }
```

However, if you like additional control over the OAuth2 Error Response, three custom Error objects are available to use instead.

### InvalidScopeError

```js lines theme={null}
module.exports = function(client, scope, audience, context, cb) {
    const invalidScope = ...; // determine if scope is valid

    if(invalidScope) {
      cb(new InvalidScopeError("Scope is not permitted."));
    }
  };
```

Then when you request a `client_credentials` grant is from the `/oauth/token` endpoint, Auth0 responds with:

```json lines theme={null}
HTTP 400
{ "error": "invalid_scope", "error_description": "Scope is not permitted." }
```

### InvalidRequestError

```js lines theme={null}
module.exports = function(client, scope, audience, context, cb) {
    const invalidRequest = ...; // determine if request is valid

    if(invalidRequest) {
      cb(new InvalidRequestError("Bad request."));
    }
  };
```

Then when you request a `client_credentials` grant from the `/oauth/token` endpoint, Auth0 will respond with:

```json lines theme={null}
HTTP 400
{ "error": "invalid_request", "error_description": "Bad request." }
```

### ServerError

```js lines theme={null}
module.exports = function(client, scope, audience, context, cb) {
    callOtherService(function(err, response) {
      if(err) {
        return cb(new ServerError("Error calling remote system: " + err.message));
      }
    });
  };
```

Then when you request a `client_credentials` grant from the `/oauth/token` endpoint, Auth0 responds with:

```json lines theme={null}
HTTP 400
{ "error": "server_error", "error_description": "Error calling remote system: ..." }
```

<Callout icon="file-lines">
  Currently, the behavior of the built-in JavaScript `Error` class and `ServerError` is identical, but the `ServerError` class allows you to be explicit about the OAuth2 error that will be returned.
</Callout>

## Learn more


# Client Credentials Flow
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow

Learn how the Client Credentials flow works and why you should use it for machine-to-machine (M2M) applications.

The Client Credentials Flow (defined in [OAuth 2.0 RFC 6749, section 4.4](https://tools.ietf.org/html/rfc6749#section-4.4)) involves an application exchanging its application credentials, such as <Tooltip href="/docs/glossary?term=client+ID">client ID</Tooltip> and <Tooltip href="/docs/glossary?term=client+secret">client secret</Tooltip>, for an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>.

This flow is best suited for Machine-to-Machine (M2M) applications, such as CLIs, daemons, or backend services, because the system must authenticate and authorize the application instead of a user.

## How it works

<Frame>
  <img alt="Flows - Client Credentials - Authorization sequence diagram(w/Border)" />
</Frame>

1. Application sends application's credentials to the Auth0 Authorization Server. To learn more about client authentication methods, read [Application Credentials](/docs/secure/application-credentials).
2. Auth0 Authorization Server validates application's credentials.
3. Auth0 Authorization Server responds with an access token.
4. Application can use the access token to call an API on behalf of itself. For more information on this process, see [Validate JSON Web Tokens](/docs/secure/tokens/json-web-tokens/validate-json-web-tokens).
5. API responds with requested data.

## How to implement it

The easiest way to implement the Client Credentials Flow is to follow our [Backend Quickstarts](/docs/quickstart/backend).

Alternatively, you can use the Auth0 Authentication API to implement the Client Credentials Flow. For more information, read [Call Your API Using the Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow/call-your-api-using-the-client-credentials-flow).

## Learn more

* [Auth0 Rules](/docs/customize/rules)
* [Auth0 Hooks](/docs/customize/hooks)
* [Tokens](/docs/secure/tokens)
* [Token Best Practices](/docs/secure/tokens/token-best-practices)
* [Which OAuth 2.0 Flow Should I Use?](/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use)


# Call Your API Using the Client Credentials Flow
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow/call-your-api-using-the-client-credentials-flow

Learn how to call your API from a machine-to-machine (M2M) application using the Client Credentials Flow.

<Callout icon="file-lines">
  This tutorial will help you call your API from a machine-to-machine (M2M) application using the Client Credentials Flow. To learn how the flow works and why you should use it, read [Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow).
</Callout>

Auth0 makes it easy for your application to implement the Client Credentials Flow. Following successful authentication, the application will have access to an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, which can be used to call your protected APIs. To learn more about access tokens, read [Access Tokens](/docs/secure/tokens/access-tokens).

## Prerequisites

**Before beginning this tutorial:**

* [Register your API with Auth0](/docs/get-started/auth0-overview/set-up-apis)

  * [Add appropriate API permissions](/docs/get-started/apis/add-api-permissions)
* [Register the M2M Application with Auth0](/docs/get-started/auth0-overview/create-applications/machine-to-machine-apps).

  * Select an **Application Type** of **Machine to Machine Applications**.
  * Choose your previously-registered API.
  * Authorize the M2M Application to call your API.

## Steps

1. [Request tokens](#request-tokens):
   From the authorized application, request an access token for your API.
2. [Call API](#call-api):
   Use the retrieved access token to call your API.

Optional: [Explore sample use cases](#sample-use-cases)

### Request tokens

To access your API, you must request an access token for it. To do so, you will need to `POST` to the [token URL](https://auth0.com/docs/api/authentication#client-credentials).

#### Example POST to token URL

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=client_credentials \
    --data client_id={yourClientId} \
    --data client_secret={yourClientSecret} \
    --data audience=YOUR_API_IDENTIFIER
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}&audience=YOUR_API_IDENTIFIER", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}&audience=YOUR_API_IDENTIFIER")

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

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}&audience=YOUR_API_IDENTIFIER")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      audience: 'YOUR_API_IDENTIFIER'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=client_credentials" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_secret={yourClientSecret}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&audience=YOUR_API_IDENTIFIER" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  [dataTask resume];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}&audience=YOUR_API_IDENTIFIER",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}&audience=YOUR_API_IDENTIFIER"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}&audience=YOUR_API_IDENTIFIER"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/x-www-form-urlencoded"]

  let postData = NSMutableData(data: "grant_type=client_credentials".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&client_secret={yourClientSecret}".data(using: String.Encoding.utf8)!)
  postData.append("&audience=YOUR_API_IDENTIFIER".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

##### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td>Set this to "client\_credentials".</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Your application's Client ID. You can find this value on the <a href="https://manage.auth0.com/#/applications">application's settings tab</a>.</td>
    </tr>

    <tr>
      <td><code>client\_secret</code></td>
      <td>Your application's Client Secret. You can find this value on the <a href="https://manage.auth0.com/#/applications">application's settings tab</a>.  To learn more about available application authentication methods, read <a href="/docs/secure/application-credentials">Application Credentials</a>.</td>
    </tr>

    <tr>
      <td><code>audience</code></td>
      <td>The audience for the token, which is your API. You can find this in the <strong>Identifier</strong> field on your <a href="https://manage.auth0.com/#/apis">API's settings tab</a>.</td>
    </tr>

    <tr>
      <td><code>organization</code></td>
      <td>Optional. The organization name or identifier you want the request to be associated with. To learn more, read <a href="/docs/manage-users/organizations/organizations-for-m2m-applications">Machine-to-Machine Access for Organizations</a>.</td>
    </tr>
  </tbody>
</table>

#### Response

If all goes well, you'll receive an `HTTP 200` response with a payload containing `access_token`, `token_type`, and `expires_in` values:

```json lines theme={null}
{
  "access_token":"eyJz93a...k4laUWw",
  "token_type":"Bearer",
  "expires_in":86400
}
```

<Warning>
  Validate your tokens before saving them. To learn how, read [Validate ID Tokens](/docs/secure/tokens/id-tokens/validate-id-tokens) and [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens).
</Warning>

### Call API

To call your API from the M2M application, the application must pass the retrieved access token as a Bearer token in the Authorization header of your HTTP request.

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request GET \
    --url https://myapi.com/api \
    --header 'authorization: Bearer ACCESS_TOKEN' \
    --header 'content-type: application/json'
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://myapi.com/api");
  var request = new RestRequest(Method.GET);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines expandable theme={null}
  package main

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

  func main() {

  	url := "https://myapi.com/api"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("content-type", "application/json")
  	req.Header.Add("authorization", "Bearer ACCESS_TOKEN")

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

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

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

  }
  ```

  ```java Java lines theme={null}
  HttpResponse response = Unirest.get("https://myapi.com/api")
    .header("content-type", "application/json")
    .header("authorization", "Bearer ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://myapi.com/api',
    headers: {'content-type': 'application/json', authorization: 'Bearer ACCESS_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C lines theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer ACCESS_TOKEN" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://myapi.com/api"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP lines expandable theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://myapi.com/api",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer ACCESS_TOKEN",
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("myapi.com")

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer ACCESS_TOKEN"
      }

  conn.request("GET", "/api", headers=headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://myapi.com/api")

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

  request = Net::HTTP::Get.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift lines theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer ACCESS_TOKEN"
  ]

  let request = NSMutableURLRequest(url: NSURL(string: "https://myapi.com/api")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

### Sample use cases

#### Customize tokens

You can use [Actions](/docs/customize/actions) to deny access tokens based on custom logic and/or add claims to access tokens. Auth0 invokes Actions attached to the client credentials grant at runtime to execute your custom logic.

To learn more, read about the Actions [Machine to Machine Flow](/docs/customize/actions/explore-triggers/machine-to-machine-trigger).

#### View sample application: server client + API

For a sample implementation, read the [Server Client + API](/docs/get-started/architecture-scenarios/server-application-api) architecture scenario. This series of tutorials is accompanied by a [code sample that you can access in GitHub](https://github.com/auth0-samples/auth0-pnp-exampleco-timesheets).

Once your API receives a request with an access token, it will need to validate the token. To learn more, read [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens).

## Learn more

* [Machine to Machine Triggers](/docs/customize/actions/explore-triggers/machine-to-machine-trigger)
* [OpenID Connect Protocol](/docs/authenticate/protocols/openid-connect-protocol)
* [Tokens](/docs/secure/tokens)


# Customize Tokens Using Hooks with Client Credentials Flow
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow/customize-tokens-using-hooks-with-client-credentials-flow

Learn how to use Hooks to change scopes and add custom claims in the access token obtained using the Client Credentials Flow.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

<Warning>
  Because we plan to remove Rules and Hooks functions in 2026, you should create new Rules or Hooks only in your Development environment and only to test migration to Actions.

  To learn how to migrate your Rules to Actions, read [Migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions). To learn how to migrate your Hooks to Actions, read [Migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions).
</Warning>

You can change scopes and add custom claims in the tokens issued through the [Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow) by adding [Hooks](/docs/customize/hooks).

Hooks allow you to customize the behavior of Auth0 using Node.js code. They are secure, self-contained functions associated with specific extensibility points of the Auth0 platform (like the Client Credentials flow). Auth0 invokes the Hooks at runtime to execute your custom logic.

You can manage Hooks using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

<Warning>
  Although you may create multiple hooks for any given extensibility point, each extensibility point may have only one enabled hook at a time. Any subsequent hooks you create for that extensibility point are automatically disabled, so you must explicitly enable them. The enabled hook will be executed for all applications and APIs.
</Warning>

## Prerequisites

Before beginning this tutorial, you must:

* [Register your API with Auth0](/docs/get-started/auth0-overview/set-up-apis)

  * [Add appropriate API permissions](/docs/get-started/apis/add-api-permissions)
* [Register the M2M Application with Auth0](/docs/get-started/auth0-overview/create-applications/machine-to-machine-apps).

  * Select an **Application Type** of **Machine to Machine Applications**.
  * Choose your previously-registered API.
  * Authorize the M2M Application to call your API.

## Steps

1. **Create Hook**: Create a hook that will customize your token.
2. **Test Hook**: Test your new hook by running a Client Credentials Flow and decoding the access token.

### Create a Hook

In this example, you will:

* add an arbitrary claim (`https://foo.com/claim`) to the [Access Token](/docs/secure/tokens/access-tokens)
* add an extra permission to your configured API

Create a Hook to customize your token. When asked to choose an extensibility point, select `Client Credentials Exchange`, and add the following code in the editor:

```js lines theme={null}
module.exports = function(client, scope, audience, context, cb) {
  var access_token = {};
  access_token['https://foo.com/claim'] = 'bar';
  access_token.scope = scope;
  access_token.scope.push('extra');
  cb(null, access_token);
};
```

<Warning>
  Auth0 returns profile information in a structured claim format as defined by the [OpenID Connect (OIDC) specification](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). This means that custom claims added to ID tokens or access tokens must [conform to guidelines and restrictions](/docs/secure/tokens/json-web-tokens/create-custom-claims) to avoid possible collisions.
</Warning>

### Test your Hook

To test the hook you just created you need to run a Client Credentials exchange, get the <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, decode it, and review its contents.

#### Get token

To get a token, make a `POST` call to the [Client Credentials Flow endpoint](https://auth0.com/docs/api/authentication#client-credentials-flow). Be sure to replace CLIENT\_ID, CLIENT\_SECRET, and API\_IDENTIFIER placeholder values with your application's <Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>, your application's <Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip>, and your API's Identifier, respectively. You can find the Client ID and Client Secret in your [Application](https://manage.auth0.com/#/applications) settings and the API Identifier in your [API](https://manage.auth0.com/#/apis) settings.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=client_credentials \
    --data 'client_id={yourClientId}' \
    --data client_secret={yourClientSecret} \
    --data audience=YOUR_API_IDENTIFIER
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}&audience=YOUR_API_IDENTIFIER", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}&audience=YOUR_API_IDENTIFIER")

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

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}&audience=YOUR_API_IDENTIFIER")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      audience: 'YOUR_API_IDENTIFIER'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=client_credentials" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_secret={yourClientSecret}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&audience=YOUR_API_IDENTIFIER" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}&audience=YOUR_API_IDENTIFIER",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}&audience=YOUR_API_IDENTIFIER"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}&audience=YOUR_API_IDENTIFIER"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/x-www-form-urlencoded"]

  let postData = NSMutableData(data: "grant_type=client_credentials".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&client_secret={yourClientSecret}".data(using: String.Encoding.utf8)!)
  postData.append("&audience=YOUR_API_IDENTIFIER".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

A successful response will include:

* an `access_token`,
* its expiration time in seconds (`expires_in`),
* the token's type set as `Bearer` (`token_type`), and
* an `extra` permission (`scope`) (which was added by your Hook)

```json lines theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik5ESTFNa05DTVRGQlJrVTRORVF6UXpFMk1qZEVNVVEzT1VORk5ESTVSVU5GUXpnM1FrRTFNdyJ9.eyJpc3MiOiJodHRwczovL2RlbW8tYWNjb3VudC5hdXRoMC3jb20vIiwic3ViIjoic0FRSlFpQmYxREw0c2lqSVZCb2pFRUZvcmRoa0o4WUNAY2xpZW50cyIsImF1ZCI6ImRlbW8tYWNjb3VudC5hcGkiLCJleHAiOjE0ODc3NjU8NjYsImlhdCI6MTQ4NzY3OTI2Niwic2NvcGUiOiJyZWFkOmRhdGEgZXh0cmEiLCJodHRwczovL2Zvby5jb20vY2xhaW0iOiKoPXIifQ.da-48mHY_7esfLZpvHWWL8sIH1j_2mUYAB49c-B472lCdsNFvpaLoq6OKQyhnqk9_aW_Xhfkusos3FECTrLFvf-qwQK70QtwbkbVye_IuPSTAYdQ2T-XTzGDm9Nmmy5Iwl9rNYLxVs2OoCdfpVMyda0OaI0AfHBgEdKWluTP67OOnV_dF3KpuwtK3dPKWTCo2j9VCa7X1I4h0CNuM79DHhY2wO7sL8WBej7BSNA3N2TUsp_YTWWfrvsr_vVhJf-32G7w_12ms_PNFUwj2C30ZZIPWc-uEkDztyMLdI-lu9q9TLrLdr0dOhfrtfkdeJx4pUSiHdJHf42kg7UAVK6JcA",
  "expires_in": 86400,
  "scope": "extra",
  "token_type": "Bearer"
}
```

#### Decode token

The easiest way to decode the access token and review its contents is to use the [JWT.io Debugger](https://jwt.io/#debugger-io).

Copy your access token and paste it into the editor. The <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> is decoded automatically and its contents are displayed.

Note that the last two items of the **Payload** have both been set by your hook:

* `"scope": "extra"`
* `"https://foo.com/claim": "bar"`

## Learn more

* [Auth0 Hooks](/docs/customize/hooks)
* [Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow)
* [Call Your API Using the Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow/call-your-api-using-the-client-credentials-flow)


# Client-Initiated Backchannel Authentication Flow
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow

Learn how the Client-Initiated Backchannel Authentication Flow works.

<Callout icon="file-lines">
  To use Client-Initiated Backchannel Authentication (CIBA) features, you must have an Enterprise Plan or an appropriate add-on. Refer to [Auth0 Pricing](https://auth0.com/pricing/) for details.
</Callout>

The Client-Initiated Backchannel Authentication (CIBA) Flow is an <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Foundation standard that enables decoupled authentication and authorization using secure backchannel requests. The CIBA flow is designed for use cases where the device initiating a request (the consumption device) is different from the device a user uses to authenticate (the authentication device).

In a CIBA flow, there are two actors:

* Initiating user: The entity that initiates authentication or authorization on the consumption device. This could be a backend application, a human user, such as a customer service agent on a customer service application, or an AI agent performing a task on the end user’s behalf.
* Authorizing user: The end user who receives the authentication or authorization request on the authentication device and provides consent.

By decoupling authentication and authorization from the consumption device, the client application can directly call the OpenID Provider using a backchannel request. This provides enhanced security, as you can use more secure methods for client authentication like [mTLS](/docs/get-started/authentication-and-authorization-flow/authenticate-with-mtls) and [Private Key JWT](/docs/get-started/authentication-and-authorization-flow/authenticate-with-private-key-jwt) with the CIBA flow.

## Use cases

Common use cases for CIBA flow include:

* An AI agent uses human-in-the-loop approvals to request the user’s permission to complete an action requested by the user.
* A user has telephoned a call center, and the agent handling the call would like to access the caller’s personal information on their computer. The caller can consent to this by, for example, approving a push notification on their phone.
* A user would like to access a device with limited input capabilities, such as a bicycle you might rent in a city or a kiosk in a retail setting.
* A user initiates a sensitive transaction on a relatively insecure device and would like to authorize the transaction on a more secure device. For example, they might authorize a payment or change in personal details following a push notification on a personal mobile phone.

## Notification channels

Auth0 supports the following notification channels with CIBA:

* [Auth0 Guardian mobile push notifications](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/mobile-push-notifications-with-ciba): Available for all [Enterprise plans](https://auth0.com/pricing). The user receives a push notification on their enrolled mobile device to authenticate or confirm transaction details. Authentication and authorization happen on the authentication device that receives the push notification. You can enable mobile push notifications with CIBA through:
  * The Auth0 Guardian app
  * A Custom app integrated with the Auth0 Guardian SDK
* [Email notifications](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/email-notifications-with-ciba): Available as an add-on for [paid plans](https://auth0.com/pricing). The user receives an email to their verified email address. The email contains a link, and authentication and authorization happens via the browser.

By default, Auth0 uses and recommends Guardian push notifications for CIBA flows. Guardian push notifications are more secure than other channels such as email, which can be vulnerable to phishing attacks. You have to explicitly enable email notifications for CIBA flows.

## How it works

The following diagram describes the end-to-end CIBA flow:

<Frame>
  <img alt="" />
</Frame>

1. The client application or consumption device requests user authentication or authorization.
2. The client application’s backend submits a `POST` request to the `/bc-authorize` endpoint.
3. Auth0 receives the `POST` request and sends a notification to the authentication device.
4. The authentication device retrieves the authorization details from Auth0 and presents them to the end user.
5. The end user reviews the request, including any contextual authorization details regarding the request.
6. The end user provides their response on the authentication device, which submits the user response to Auth0.
7. The client application’s backend polls the `/token` endpoint and receives the appropriate tokens upon completing the CIBA flow.

<Callout icon="file-lines">
  Because the CIBA flow is used for one-time asynchronous user authentication and authorization, CIBA does not create or store a grant containing the user’s consent for an application to access an API’s resources. If the user later authenticates using a different authentication flow, and that flow requests the same scopes the user previously consented to using CIBA, Auth0 will not have a record of that consent. Therefore, it will prompt the user to consent again.
</Callout>

## Entity Limits

The CIBA flow has the following limits:

* Up to 500 CIBA requests may be created per minute per tenant.
* Up to 5000 pending CIBA requests per tenant at any one time. A pending CIBA request is a request that has been initiated but has not yet received a response from the user. If a CIBA request expires without receiving a response, it may continue to count towards the 5000 limit for up to 24 hours.

## Get started

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To Learn...</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/get-started/applications/configure-client-initiated-backchannel-authentication">Configure Client-Initiated Backchannel Authentication</a></td>
      <td>How to configure the CIBA grant type and notification channel for your application.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/mobile-push-notifications-with-ciba">Mobile push notifications with CIBA</a></td>
      <td>How to authenticate users using the CIBA flow with mobile push notifications.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/email-notifications-with-ciba">Email notifications with CIBA</a></td>
      <td>How to authenticate users using the CIBA flow with email notifications.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/user-authorization-with-ciba">User Authorization with CIBA</a></td>
      <td>How to authorize users using the CIBA with Rich Authorization Requests (RAR) flow.</td>
    </tr>
  </tbody>
</table>


# Email Notifications with CIBA
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/email-notifications-with-ciba

Learn how to authenticate users with the Client-Initiated Backchannel Authentication Flow using email notifications.

<Callout icon="file-lines">
  To use Client-Initiated Backchannel Authentication (CIBA) features, you must have an Enterprise Plan or an appropriate add-on. Refer to [Auth0 Pricing](https://auth0.com/pricing/) for details.
</Callout>

When you use email notifications with CIBA, the user receives an email with a link that redirects them to authenticate or authorize a request in the browser.

When using email notifications with CIBA, the user logs in on the consumption device but completes authentication by clicking a link sent to their verified email address. When the user clicks the verification link, they are redirected to their browser, creating a session that Auth0 uses to track the authentication process and confirm the user's identity. This session is necessary to bridge the gap between the authentication device, in this case, the browser, and the consumption device, such as a Smart TV.

The following diagram explains the end-to-end CIBA with email notifications flow:

<Frame>
  <img alt="" />
</Frame>

The following sections dive step-by-step into how user authentication works with CIBA using email notifications.

* [Prerequisites](#prerequisites)
* [Step 1: Client application initiates a CIBA request](#step-1%3A-client-application-initiates-a-ciba-request)
* [Step 2: Auth0 tenant acknowledges the CIBA request](#step-2%3A-auth0-tenant-acknowledges-the-ciba-request)
* [Step 3: Client application polls for a response](#step-3%3A-client-application-polls-for-a-response)
* [Step 4: Auth0 sends a link to the user's email address](#step-4%3A-auth0-sends-a-link-to-the-user’s-email-address)
* [Step 5: User authenticates in the browser](#step-5%3A-user-authenticates-in-the-browser)
* [Step 6: Browser presents consent details to the user](#step-6%3A-browser-sends-the-user-response-back-to-auth0)
* [Step 7: Auth0 receives user response after the flow completes](#step-7%3A-auth0-receives-user-response-after-the-flow-completes)
* [Step 8: Auth0 returns access token to client application](#step-8%3A-auth0-returns-access-token-to-client-application)

## Prerequisites

To initiate a CIBA email request using Auth0, you must:

* [Configure Client-Initiated Backchannel Authentication](/docs/get-started/applications/configure-client-initiated-backchannel-authentication) for your tenant and application, including [email notifications](/docs/get-started/applications/configure-client-initiated-backchannel-authentication/#configure-email-notifications).
* Set the `requested_expiry` parameter to a value between 301 to 259200 seconds (72 hours). To learn more, read [Configure notification channel](/docs/get-started/applications/configure-client-initiated-backchannel-authentication#configure-notification-channel).
* If using email notifications with CIBA and Rich Authorization Requests (RAR) for [user authorization](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/user-authorization-with-ciba), [set the customized consent prompt](/docs/get-started/apis/configure-rich-authorization-requests#set-customized-consent-prompt).

## Step 1: Client application initiates a CIBA request

Use the [User Search APIs](/docs/manage-users/user-search) to find the authorizing user for whom you’d like to initiate a CIBA request and obtain their user ID.

Once you have a user ID for the authorizing user, use the Authentication API or our [SDKs](/docs/libraries) to send a CIBA request to the `/bc-authorize` endpoint:

<Tabs>
  <Tab title="cURL">
    ```bash lines theme={null}
    curl --location 'https://{YOUR_DOMAIN}.auth0.com/bc-authorize' \
      --header 'Content-Type: application/x-www-form-urlencoded' \
      --data-urlencode 'client_id={YOUR_CLIENT_ID}' \
      --data-urlencode 'client_secret={YOUR_CLIENT_SECRET}' \
      --data-urlencode 'login_hint={ "format": "iss_sub", "iss": "https://{YOUR_DOMAIN}.auth0.com/", "sub": "{USER_ID}" }' \
      --data-urlencode 'scope={SCOPES}' \
      --data-urlencode 'binding_message={BINDING_MESSAGE}'
    ```
  </Tab>

  <Tab title="C#">
    ```csharp lines theme={null}
    var response = await authenticationApiClient.ClientInitiatedBackchannelAuthorization(
                new ClientInitiatedBackchannelAuthorizationRequest()
                {
                    ClientId = "{YOUR_CLIENT_ID}",
                    Scope = "{SCOPES}",
                    ClientSecret = "{YOUR_CLIENT_SECRET}",
                    BindingMessage = "{BINDING_MESSAGE}",
                    LoginHint = new LoginHint()
                    {
                        Format = "iss_sub",
                        Issuer = "https://{YOUR_DOMAIN}.auth0.com/",
                        Subject = "{USER_ID}"
                    }
                }
            );
    ```
  </Tab>

  <Tab title="Go">
    ```go lines theme={null}
    resp, err := authAPI.CIBA.Initiate(context.Background(), ciba.Request{
        ClientID:     mgmtClientID,
        ClientSecret: mgmtClientSecret,
        Scope:        "openid",
        LoginHint: map[string]string{
          "format": "iss_sub",
          "iss":    "https://{YOUR_DOMAIN}.auth0.com/",
          "sub":    "{USER_ID}",
        },
        BindingMessage: "{BINDING_MESSAGE}",
      })
    ```
  </Tab>

  <Tab title="Java">
    ```java lines theme={null}
    //Creating AuthClient Instance
    AuthAPI auth = AuthAPI.newBuilder(domain, clientId, clientSecret).build();

    //Authorize
    Map<String, Object> loginHint = new HashMap<>();
            loginHint.put("format", "iss_sub");
            loginHint.put("iss", "https://{YOUR_DOMAIN}.auth0.com/");
            loginHint.put("sub", "{USER_ID}");

    Request<BackChannelAuthorizeResponse> request = auth.authorizeBackChannel("openid", "{BINDING_MESSAGE}", loginHint);

    BackChannelAuthorizeResponse resp = request.execute().getBody();
    ```
  </Tab>
</Tabs>

<table>
  <thead>
    <tr>
      <th><strong>Parameters</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>tenant</code></td>
      <td>Tenant name. It can also be a custom domain. If the `iss_sub` format is used, then the tenant name is passed within the `iss` claim.</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Client application identifier.</td>
    </tr>

    <tr>
      <td><code>client\_secret</code></td>
      <td>Client authentication method used for user authentication with CIBA, such as Client Secret, Private Key JWT, or mTLS Authentication. If you're using Private Key JWT or mTLS, you don't need to include the client secret.</td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td>Must include <code>openid</code>.<br /><br />The scope can optionally include <code>offline\_access</code> to request a refresh token. However, for one-time authorization of a transaction with the CIBA Flow, a refresh token is not needed and does not have any meaning in this context.<br /></td>
    </tr>

    <tr>
      <td><code>user\_id</code></td>
      <td>User ID for the authorizing user that is passed within the <code>login\_hint</code> structure. If <code>iss\_sub</code> format is used, then the user ID is passed within the <code>sub</code> claim.<br /><br />The user ID may have a different format depending on the external provider.<br /></td>
    </tr>

    <tr>
      <td><code>requested\_expiry</code></td>
      <td>The maximum duration, in seconds, for which the CIBA session should be valid. The CIBA flow's requested expiry is between 1 and  259200 seconds (72 hours), and it defaults to 300 seconds. Include the <code>requested\_expiry</code> parameter to set a custom expiry for the CIBA flow.<br /><br />The <code>requested\_expiry</code> parameter helps determine which notification channel CIBA uses:<ul><li>If you set your <code>requested\_expiry</code> to a value of 300 or lower in seconds, CIBA uses the mobile push notification channel if enabled. If you have not configured MFA for your tenant, the CIBA request fails.</li><li>If you set your <code>requested\_expiry</code> to a value between 301 to 259200 seconds (72 hours), CIBA uses the email notification channel if enabled.</li></ul></td>
    </tr>

    <tr>
      <td><code>binding\_message</code></td>
      <td>Human-readable message used to bind the CIBA flow across the authentication and consumption devices. The binding message is required and up to 64 characters. Use only alphanumeric and <code>+-\_.,:#</code> characters.</td>
    </tr>
  </tbody>
</table>

<Callout icon="file-lines">
  There is a user-specific rate limit where the authorizing user will not be sent more than 5 requests per minute.
</Callout>

## Step 2: Auth0 tenant acknowledges the CIBA request

If the Auth0 tenant successfully receives the `POST` request, you should receive a response containing an `auth-req-id` that references the request:

```json lines theme={null}
{
    "auth_req_id": "eyJh...",
    "expires_in": 300,
    "interval": 5
}
```

The `auth_req_id` value is passed to the `/token` endpoint to poll for the completion of the CIBA flow.

## Step 3: Client application polls for a response

Use the Authentication API or our [SDKs](/docs/libraries) to call the `/token` endpoint using the `urn:openid:params:grant-type:ciba` grant type and the `auth_req_id` you received from the `/bc-authorize` endpoint:

<Tabs>
  <Tab title="cURL">
    ```bash lines theme={null}
    curl --location 'https://{YOUR_DOMAIN}.auth0.com/oauth/token' \
      --header 'Content-Type: application/x-www-form-urlencoded' \
      --data-urlencode 'client_id={YOUR_CLIENT_ID}' \
      --data-urlencode 'client_secret={YOUR_CLIENT_SECRET}' \
      --data-urlencode 'auth_req_id={AUTH_REQ_ID}' \
      --data-urlencode 'grant_type=urn:openid:params:grant-type:ciba'
    ```
  </Tab>

  <Tab title="C#">
    ```csharp lines theme={null}
    var token = await authenticationApiClient.GetTokenAsync(
                new ClientInitiatedBackchannelAuthorizationTokenRequest()
                {
                    AuthRequestId = response.AuthRequestId,
                    ClientId = "{YOUR_CLIENT_ID}",
                    ClientSecret = "{YOUR_CLIENT_SECRET}"
                }
            );
    ```
  </Tab>

  <Tab title="Go">
    ```go lines theme={null}
    token, err := authAPI.OAuth.LoginWithGrant(context.Background(),
          "urn:openid:params:grant-type:ciba",
          url.Values{
            "auth_req_id":   []string{resp.AuthReqID},
            "client_id":     []string{clientID},
            "client_secret": []string{clientSecret},
          },
          oauth.IDTokenValidationOptions{})
    ```
  </Tab>

  <Tab title="Java">
    ```java lines theme={null}
    Request<BackChannelTokenResponse> tokenRequest = auth.getBackChannelLoginStatus(authReqId, "grant-type");

    BackChannelTokenResponse tokenResponse = tokenRequest.execute().getBody();
    ```
  </Tab>
</Tabs>

Until the authorizing user approves the transaction, you should receive the following response:

```json lines theme={null}
{
    "error": "authorization_pending",
    "error_description": "The end-user authorization is pending"
}
```

There is approximately a five-second wait interval for polling. If you poll too frequently, you will receive the following response, where the description varies depending on the backoff interval:

```json lines theme={null}
{
"error": "slow_down",
"error_description": "You are polling faster than allowed. Try again in 10 seconds."
"interval": 10
}
```

To resolve the error, wait until the next interval (in seconds) to poll the `/token` endpoint.

## Step 4: Auth0 sends a link to the user’s email address

The Auth0 Authorization Server uses the `login_hint`, which contains the user ID for the authorizing user, to initiate user authentication on the authentication device:

* The Auth0 Authorization Server sends an email to the user's verified email address.
* The email contains a verification link that the user must click to authenticate. The `binding_message` shows up as the request code.
* The link directs the user to the browser through a request to the `/bc-verify` endpoint, where the `consent` query parameter references the CIBA request awaiting consent.

<Frame>
  <img alt="Auth0 sends email to user's verified email address" />
</Frame>

## Step 5: User authenticates in the browser

If no active session is found, the verification link will ask the user to authenticate. The user clicks the link to proceed with user authentication.

To authenticate, the user enters their verified email address and password. The user must use the credentials provided to the `login_hint` parameter sent to the `/bc-authorize` endpoint when the client application [initiates a CIBA request](#step-1%3A-client-application-initiates-a-ciba-request). Otherwise, the user is prompted with an error message and needs to log out and try again.

<Frame>
  <img alt="User authenticates in the browser" />
</Frame>

Similar to a standard login flow, the`post-login` Actions trigger runs in the CIBA with email flow, enabling customers to provide custom logic to apply access control policies or ask for additional MFA factors. When executed from a CIBA verification link, the `event.transaction.protocol` value is `oidc-ciba-web-link`, allowing you to apply custom rules to this specific type of login. To learn more, read [Login Trigger](https://auth0.com/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger).

Once authenticated, the browser presents the consent details to the user from the Auth0 Consent API, which includes the `binding_message`, `scope`, and `audience`. The scopes are filtered according to your RBAC policy. To learn more, read [Role-Based Access Control](/docs/manage-users/access-control/rbac).

The following code sample is an example response from the Auth0 Consent API:

```json lines theme={null}
{
  "id": "cns_abc123",
  "requested_details": {
    "audience": "https://$tenant.auth0.com/userinfo",
    "scope": ["openid"],
    "binding_message": "21-49-38"
  },
  "created_at": 1746693720
  "expires_at": 1746693750
}
```

The user can accept or decline the authentication request at this point.

## Step 6: Browser sends the user response back to Auth0

The browser sends the user response back to Auth0. Depending on whether the user accepts or rejects the authentication request, Auth0 displays the following consent screens, which you need to customize by [setting the consent prompts](/docs/get-started/apis/configure-rich-authorization-requests#set-customized-consent-prompt):

### User accepts the authentication request

<Frame>
  <img alt="User accepts the authentication request" />
</Frame>

### User rejects the authentication request

<Frame>
  <img alt="User accepts the authentication request" />
</Frame>

## Step 7: Auth0 receives user response after the flow completes

The client application completes the polling upon receiving a response from the `/token` endpoint. A CIBA flow always requires a response, either an approval or decline, from the authorizing user, and existing grants are not checked.

## Step 8: Auth0 returns access token to client application

If the user rejects the email request, Auth0 returns an error response like the following to the client application:

```json lines theme={null}
{
    "error": "access_denied",
    "error_description": "The end-user denied the authorization request or it has been expired"
}
```

If the user approves the email request, Auth0 returns an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> like the following to the client application:

```json lines theme={null}
{
    "access_token": "eyJh...",
    "id_token": "eyJh...",
    "expires_in": 86400,
    "scope": "openid",
    "token_type": "Bearer"
}
```

<Callout icon="file-lines">
  The `refresh_token` will only be present if the `offline_access` scope was included in the initial `/bc-authorize` request.
</Callout>

## Learn more

* [Client-Initiated Backchannel Authentication Flow](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow)
* [Configure Client-Initiated Backchannel Authentication](/docs/get-started/applications/configure-client-initiated-backchannel-authentication)


# Mobile Push Notifications with CIBA
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/mobile-push-notifications-with-ciba

Learn how to authenticate users with the Client-Initiated Backchannel Authentication Flow using mobile push notifications.

<Callout icon="file-lines">
  To use Client-Initiated Backchannel Authentication (CIBA) features, you must have an Enterprise Plan or an appropriate add-on. Refer to [Auth0 Pricing](https://auth0.com/pricing/) for details.
</Callout>

When you use mobile push notifications with CIBA, the user receives a push notification to authenticate or authorize a request on their enrolled mobile device. You can send mobile push notifications with CIBA using the Auth0 Guardian app or a custom app integrated with the Auth0 Guardian SDK.

The CIBA flow with mobile push notifications authenticates and authorizes users on their mobile device, bypassing the need for a browser. Because the consumption device doesn't require an active browser session, the user doesn't need to be logged in before a CIBA request is triggered. This also ensures that the CIBA flow won't impact any existing sessions the user may have.

The following diagram explains the end-to-end CIBA with mobile push notifications flow:

<Frame>
  <img alt="" />
</Frame>

The following sections dive step-by-step into how user authentication works with CIBA using mobile push notifications.

* [Prerequisites](#prerequisites)
* [Step 1: Client application initiates a CIBA request](#step-1%3A-client-application-initiates-a-ciba-request)
* [Step 2: Auth0 tenant acknowledges the CIBA request](#step-2%3A-auth0-tenant-acknowledges-the-ciba-request)
* [Step 3: Client application polls for a response](#step-3%3A-client-application-polls-for-a-response)
* [Step 4: Mobile application receives the push notification](#step-4%3A-mobile-application-receives-the-push-notification)
* [Step 5: Mobile application retrieves the consent details](#step-5%3A-mobile-application-retrieves-the-consent-details)
* [Step 6: Mobile application presents the consent details to the user](#step-6%3A-mobile-application-presents-the-consent-details-to-the-user)
* [Step 7: Mobile application sends the user response back to Auth0](#step-7%3A-mobile-application-sends-the-user-response-back-to-auth0)
* [Step 8: Auth0 receives user response after the flow completes](#step-8%3A-auth0-receives-user-response-after-the-flow-completes)
* [Step 9: Auth0 returns access token to client application](#step-9%3A-auth0-returns-access-token-to-client-application)

## Prerequisites

To initiate a CIBA push request using Auth0, you must:

* [Configure Client-Initiated Backchannel Authentication](/docs/get-started/applications/configure-client-initiated-backchannel-authentication) for your tenant and application, including [mobile push notifications](/docs/get-started/applications/configure-client-initiated-backchannel-authentication/#configure-mobile-push-notifications).
* Set the `requested_expiry` parameter to a value of 300 or lower in seconds. To learn more, read [Configure notification channel](/docs/get-started/applications/configure-client-initiated-backchannel-authentication#configure-notification-channel).

## Step 1: Client application initiates a CIBA request

Use the [User Search APIs](/docs/manage-users/user-search) to find the authorizing user for whom you’d like to initiate a CIBA request and obtain their user ID.

Once you have a user ID for the authorizing user, use the Authentication API or our [SDKs](/docs/libraries) to send a CIBA request to the `/bc-authorize` endpoint:

<Tabs>
  <Tab title="cURL">
    ```bash lines theme={null}
    curl --location 'https://{YOUR_DOMAIN}.auth0.com/bc-authorize' \
      --header 'Content-Type: application/x-www-form-urlencoded' \
      --data-urlencode 'client_id={YOUR_CLIENT_ID}' \
      --data-urlencode 'client_secret={YOUR_CLIENT_SECRET}' \
      --data-urlencode 'login_hint={ "format": "iss_sub", "iss": "https://{YOUR_DOMAIN}.auth0.com/", "sub": "{USER_ID}" }' \
      --data-urlencode 'scope={SCOPES}' \
      --data-urlencode 'binding_message={BINDING_MESSAGE}'
    ```
  </Tab>

  <Tab title="C#">
    ```csharp lines theme={null}
    var response = await authenticationApiClient.ClientInitiatedBackchannelAuthorization(
                new ClientInitiatedBackchannelAuthorizationRequest()
                {
                    ClientId = "{YOUR_CLIENT_ID}",
                    Scope = "openid",
                    ClientSecret = "{YOUR_CLIENT_SECRET}",
                    BindingMessage = "{BINDING_MESSAGE}",
                    LoginHint = new LoginHint()
                    {
                        Format = "iss_sub",
                        Issuer = "https://{YOUR_DOMAIN}.auth0.com/",
                        Subject = "{USER_ID}"
                    }
                }
            );
    ```
  </Tab>

  <Tab title="Go">
    ```go lines theme={null}
    resp, err := authAPI.CIBA.Initiate(context.Background(), ciba.Request{
    		ClientID:     mgmtClientID,
    		ClientSecret: mgmtClientSecret,
    		Scope:        "openid",
    		LoginHint: map[string]string{
    			"format": "iss_sub",
    			"iss":    "https://{YOUR_DOMAIN}.auth0.com/",
    			"sub":    "{USER_ID}",
    		},
    		BindingMessage: "{BINDING_MESSAGE}",
    	})
    ```
  </Tab>

  <Tab title="Java">
    ```java lines theme={null}
    //Creating AuthClient Instance
    AuthAPI auth = AuthAPI.newBuilder(domain, clientId, clientSecret).build();

    //Authorize
    Map<String, Object> loginHint = new HashMap<>();
            loginHint.put("format", "iss_sub");
            loginHint.put("iss", "https://{YOUR_DOMAIN}.auth0.com/");
            loginHint.put("sub", "{USER_ID}");

    Request<BackChannelAuthorizeResponse> request = auth.authorizeBackChannel("openid", "{BINDING_MESSAGE}", loginHint);

    BackChannelAuthorizeResponse resp = request.execute().getBody();
    ```
  </Tab>
</Tabs>

<table>
  <thead>
    <tr>
      <th><strong>Parameters</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>tenant</code></td>
      <td>Tenant name. It can also be a custom domain. If the `iss_sub` format is used, then the tenant name is passed within the `iss` claim.</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Client application identifier.</td>
    </tr>

    <tr>
      <td><code>client\_secret</code></td>
      <td>Client authentication method used for user authentication with CIBA, such as Client Secret, Private Key JWT, or mTLS Authentication. If you're using Private Key JWT or mTLS, you don't need to include the client secret.</td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td>Must include <code>openid</code>.<br /><br />The scope can optionally include <code>offline\_access</code> to request a refresh token. However, for one-time authorization of a transaction with the CIBA Flow, a refresh token is not needed and does not have any meaning in this context.<br /></td>
    </tr>

    <tr>
      <td><code>user\_id</code></td>
      <td>User ID for the authorizing user that is passed within the <code>login\_hint</code> structure. If <code>iss\_sub</code> format is used, then the user ID is passed within the <code>sub</code> claim.<br /><br />The user ID may have a different format depending on the external provider.<br /></td>
    </tr>

    <tr>
      <td><code>requested\_expiry</code></td>
      <td>The maximum duration, in seconds, for which the CIBA session should be valid. The CIBA flow's requested expiry is between 1 and  259200 seconds (72 hours), and it defaults to 300 seconds. Include the <code>requested\_expiry</code> parameter to set a custom expiry for the CIBA flow.<br /><br />The <code>requested\_expiry</code> parameter helps determine which notification channel CIBA uses:<ul><li>If you set your <code>requested\_expiry</code> to a value of 300 or lower in seconds, CIBA uses the mobile push notification channel if enabled. If you have not configured MFA for your tenant, the CIBA request fails.</li><li>If you set your <code>requested\_expiry</code> to a value between 301 to 259200 seconds (72 hours), CIBA uses the email notification channel if enabled.</li></ul></td>
    </tr>

    <tr>
      <td><code>binding\_message</code></td>
      <td>Human-readable message used to bind the CIBA flow across the authentication and consumption devices. The binding message is required and up to 64 characters. Use only alphanumeric and <code>+-\_.,:#</code> characters.</td>
    </tr>
  </tbody>
</table>

<Callout icon="file-lines">
  There is a user-specific rate limit where the authorizing user will not be sent more than 5 requests per minute.
</Callout>

## Step 2: Auth0 tenant acknowledges the CIBA request

If the Auth0 tenant successfully receives the `POST` request, you should receive a response containing an `auth-req-id` that references the request:

```json lines theme={null}
{
    "auth_req_id": "eyJh...",
    "expires_in": 300,
    "interval": 5
}
```

The `auth_req_id` value is passed to the `/token` endpoint to poll for the completion of the CIBA flow.

## Step 3: Client application polls for a response

Use the Authentication API or our [SDKs](/docs/libraries) to call the `/token` endpoint using the `urn:openid:params:grant-type:ciba` grant type and the `auth_req_id` you received from the `/bc-authorize` endpoint:

<Tabs>
  <Tab title="cURL">
    ```bash lines theme={null}
    curl --location 'https://$tenant.auth0.com/oauth/token' \
      --header 'Content-Type: application/x-www-form-urlencoded' \
      --data-urlencode 'client_id=<CLIENT_ID>' \
      --data-urlencode 'client_secret=<CLIENT_SECRET>' \
      --data-urlencode 'auth_req_id=<AUTH_REQ_ID>' \
      --data-urlencode 'grant_type=urn:openid:params:grant-type:ciba'
    ```
  </Tab>

  <Tab title="C#">
    ```csharp lines theme={null}
    var token = await authenticationApiClient.GetTokenAsync(
                new ClientInitiatedBackchannelAuthorizationTokenRequest()
                {
                    AuthRequestId = response.AuthRequestId,
                    ClientId = "<CLIENT_ID>",
                    ClientSecret = "<CLIENT_SECRET>"
                }
            );
    ```
  </Tab>

  <Tab title="Go">
    ```go lines theme={null}
    token, err := authAPI.OAuth.LoginWithGrant(context.Background(),
    			"urn:openid:params:grant-type:ciba",
    			url.Values{
    				"auth_req_id":   []string{resp.AuthReqID},
    				"client_id":     []string{clientID},
    				"client_secret": []string{clientSecret},
    			},
    			oauth.IDTokenValidationOptions{})
    ```
  </Tab>

  <Tab title="Java">
    ```java lines theme={null}
    Request<BackChannelTokenResponse> tokenRequest = auth.getBackChannelLoginStatus(authReqId, "grant-type");

    BackChannelTokenResponse tokenResponse = tokenRequest.execute().getBody();
    ```
  </Tab>
</Tabs>

Until the authorizing user approves the transaction, you should receive the following response:

```json lines theme={null}
{
    "error": "authorization_pending",
    "error_description": "The end-user authorization is pending"
}
```

There is approximately a five-second wait interval for polling. If you poll too frequently, you will receive the following response, where the description varies depending on the backoff interval:

```json lines theme={null}
{
"error": "slow_down",
"error_description": "You are polling faster than allowed. Try again in 10 seconds."
"interval": 10
}
```

To resolve the error, wait until the next interval (in seconds) to poll the `/token` endpoint.

## Step 4: Mobile application receives the push notification

Auth0 sends a push notification to the user's registered mobile app or device via the Auth0 Guardian app or a custom app integrated with the [Auth0 Guardian SDK](/docs/secure/multi-factor-authentication/auth0-guardian).

If you're using a custom app, the [Auth0 Guardian SDK](/docs/secure/multi-factor-authentication/auth0-guardian) provides methods to parse the data received from the push notification and return a ready-to-use `Notification` instance. The `Notification` instance includes a transaction linking ID, or `txlinkid`, that the mobile application uses to retrieve the consent details from Auth0.

The following code samples are example iOS and Android mobile push notification implementations using the Guardian SDK:

<Tabs>
  <Tab title="iOS">
    ```swift lines theme={null}
    //implementing UNUserNotificationCenterDelegate
    func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: (UNNotificationPresentationOptions) -> Void) {
        let userInfo = notification.request.content.userInfo
        if let notification = Guardian.notification(from: userInfo) {
             // Implement this function to display the prompt and handle user's consent/rejection.
             handleGuardianNotification(notification: notification)
        }
    }
    ```
  </Tab>

  <Tab title="Android">
    ```kotlin lines theme={null}
    // at the FCM listener you receive a RemoteMessage
    @Override
    public void onMessageReceived(RemoteMessage message) {
        Notification notification = Guardian.parseNotification(message.getData());
        if (notification != null) {
            // you received a Guardian notification, handle it
            handleGuardianNotification(notification);
            return;
        }
        /* handle other push notifications you might be using ... */
    }
    ```
  </Tab>
</Tabs>

## Step 5: Mobile application retrieves the consent details

Your Auth0 Guardian app or custom app integrated with the Auth0 Guardian SDK retrieves the consent details i.e. the contents of the `binding_message` from the Auth0 Consent API.

If you're using a custom app, the following code samples are example iOS and Android implementations that retrieve data from the Auth0 Consent API:

<Tabs>
  <Tab title="iOS">
    ```swift lines theme={null}
    let device: AuthenticationDevice = // the object you obtained during the initial Guardian SDK enrollment process and stored locally
    if let consentId = notification.transactionLinkingId {
        Guardian
            .consent(forDomain: {yourTenantDomain}, device: device)
            .fetch(consentId: consentId, notificationToken: notification.transactionToken)
            .start{result in
                switch result {
                case .success(let payload):
                    // present consent details to the user
                case .failure(let cause):
                    // something went wrong
            }
        }
    }
    ```
  </Tab>

  <Tab title="Android">
    ```kotlin lines theme={null}
    Enrollment enrollment = // the object you obtained during the initial Guardian SDK enrollment process and stored locally
    if (notification.getTransactionLinkingId() != null) {
        guardian
          .fetchConsent(notification, enrollment)
          .start(new Callback<Enrollment> {
            @Override
            void onSuccess(RichConsent consentDetails) {
                // present consent details to the user 
            }
            @Override
            void onFailure(Throwable exception) {
                // something went wrong 
            }
          });
    }
    ```
  </Tab>
</Tabs>

## Step 6: Mobile application presents the consent details to the user

The Auth0 Consent API responds to the Auth0 Guardian app or your custom app integrated with the Auth0 Guardian SDK with the consent details, including the `binding_message`, `scope`, and `audience`. The scopes returned to the mobile application are filtered according to your RBAC policy. To learn more, read [Role-Based Access Control](/docs/manage-users/access-control/rbac).

The mobile application presents the authentication request and/or the consent details to the user.

The following code sample is an example response from the Auth0 Consent API:

```json lines theme={null}
{
  "id": "cns_abc123",
  "requested_details": {
    "audience": "https://$tenant.auth0.com/userinfo",
    "scope": ["openid"],
    "binding_message": "21-49-38"
  },
  "created_at": 1746693720
  "expires_at": 1746693750
}
```

The user can accept or decline the authentication request at this point.

## Step 7: Mobile application sends the user response back to Auth0

The Auth0 Guardian app or your custom app sends the user response back to Auth0.

If you're using a custom app integrated with the Auth0 Guardian SDK, the following code samples are example iOS and Android implementations that handle the user response:

### User accepts the authentication request

<Tabs>
  <Tab title="iOS">
    ```swift lines theme={null}
    Guardian
        .authentication(forDomain: "{yourTenantDomain}", device: device)
        .allow(notification: notification)
        // or reject(notification: notification, withReason: "hacked")
        .start { result in
            switch result {
            case .success:
                // the auth request was successfully rejected
            case .failure(let cause):
                // something failed, check cause to see what went wrong
            }
        }
    ```
  </Tab>

  <Tab title="Android">
    ```kotlin lines theme={null}
    guardian
        .allow(notification, enrollment)
        .execute(); // or start(new Callback<> ...)
    ```
  </Tab>
</Tabs>

### User rejects the authentication request

<Tabs>
  <Tab title="iOS">
    ```swift lines theme={null}
    Guardian
            .authentication(forDomain: "{yourTenantDomain}", device: device)
            .reject(notification: notification)
            // or reject(notification: notification, withReason: "hacked")
            .start { result in
                switch result {
                case .success:
                    // the auth request was successfully rejected
                case .failure(let cause):
                    // something failed, check cause to see what went wrong
                }
            }
    ```
  </Tab>

  <Tab title="Android">
    ```kotlin lines theme={null}
    guardian
        .reject(notification, enrollment) // or reject(notification, enrollment, reason)
        .execute(); // or start(new Callback<> ...)
    ```
  </Tab>
</Tabs>

## Step 8: Auth0 receives user response after the flow completes

The client application completes the polling upon receiving a response from the `/token` endpoint. A CIBA flow always requires a response, either an approval or decline, from the authorizing user, and existing grants are not checked.

## Step 9: Auth0 returns access token to client application

 If the user rejects the push request, Auth0 returns an error response like the following to the client application:

```json lines theme={null}
{
    "error": "access_denied",
    "error_description": "The end-user denied the authorization request or it has been expired"
}
```

If the user approves the push request, Auth0 returns an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> like the following to the client application:

```json lines theme={null}
{
    "access_token": "eyJh...",
    "id_token": "eyJh...",
    "expires_in": 86400,
    "scope": "openid",
    "token_type": "Bearer"
}
```

<Callout icon="file-lines">
  The `refresh_token` will only be present if the `offline_access` scope was included in the initial `/bc-authorize` request.
</Callout>

## Learn more

* [Client-Initiated Backchannel Authentication Flow](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow)
* [Configure Client-Initiated Backchannel Authentication](/docs/get-started/applications/configure-client-initiated-backchannel-authentication)


# User Authorization with CIBA
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/user-authorization-with-ciba

Learn how to use Rich Authorization Requests with the Client-Initiated Backchannel Flow.

<Callout icon="file-lines">
  To use Client-Initiated Backchannel Authentication (CIBA) features, you must have an Enterprise Plan or an appropriate add-on. Refer to [Auth0 Pricing](https://auth0.com/pricing/) for details.
</Callout>

[Client-Initiated Backchannel Authentication (CIBA)](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow) is an <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> specification that allows a client application to initiate an authentication and/or <Tooltip href="/docs/glossary?term=authorization+flow">authorization flow</Tooltip> without requiring direct user interaction on the initiating application. [Rich Authorization Requests (RAR)](/docs/get-started/apis/configure-rich-authorization-requests) is an OAuth 2.0 extension that allows client applications to request for more complex permissions beyond standard OAuth 2.0 scopes in an authorization request.

You can use CIBA with RAR to pass <Tooltip href="/docs/glossary?term=fine-grained+authorization">fine-grained authorization</Tooltip> data to the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip> in a backchannel request. The `authorization_details` parameter contains details about the request that you can customize in a consent prompt to show the user.

You can authorize users with CIBA using the following notification channels:

* [Mobile push notifications](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/mobile-push-notifications-with-ciba) using the Auth0 Guardian app and a custom app integrated with the Auth0 Guardian SDK.
* [Email notifications](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/email-notifications-with-ciba), which require setting a customized consent prompt.

## Common use cases

Use RAR with the CIBA flow for use cases that require more fine-grained control over resource access. Common use cases include:

1. A payments app prompts the user to confirm a money transfer. The `authorization_details` can be customized to show the transaction details.
2. An AI agent prompts the user with details about a rescheduled doctor’s appointment. The `authorization_details` can be customized to show the new time and date.

## How it works

The User Authorization with CIBA flow is similar to the User Authentication with CIBA flow, where RAR support enables clients to pass the `authorization_details` to the authorization server via the `/bc-authorize` endpoint.

The following sequence diagram explains the end-to-end User Authorization with CIBA flow:

<Frame>
  <img alt="" />
</Frame>

The following sections dive step-by-step into how user authorization works with CIBA.

* [Prerequisites](#prerequisites)
* [Step 1: Client application initiates a CIBA request](#step-1%3A-client-application-initiates-a-ciba-request)
* [Step 2: Auth0 tenant acknowledges the CIBA request](#step-2%3A-auth0-tenant-acknowledges-the-ciba-request)
* [Step 3: Client application polls for a response](#step-3%3A-client-application-polls-for-a-response)
* [Step 4: Authentication device receives the push notification](#step-4%3A-authentication-device-receives-the-notification)
* [Step 5: Authentication device retrieves the consent details](#step-5%3A-authentication-device-retrieves-the-consent-details)
* [Step 6: Authentication device presents the consent details to the user](#step-6%3A-authentication-device-presents-the-consent-details-to-the-user)
* [Step 7: Authentication device sends the user response back to Auth0](#step-7%3A-authentication-device-sends-the-user-response-back-to-auth0)
* [Step 8: Auth0 receives user response after the flow completes](#step-8%3A-auth0-receives-user-response-after-the-flow-completes)
* [Step 9: Auth0 returns access token to the client application](#step-9%3A-auth0-returns-access-token-to-client-application)

## Prerequisites

To initiate a CIBA request using Auth0, you must:

* [Configure Client-Initiated Backchannel Authentication](/docs/get-started/applications/configure-client-initiated-backchannel-authentication) for your tenant and application, including your [notification channel](/docs/get-started/applications/configure-client-initiated-backchannel-authentication#configure-notification-channel).
* [Configure Rich Authorization Requests](/docs/get-started/apis/configure-rich-authorization-requests) for your <Tooltip href="/docs/glossary?term=resource+server">resource server</Tooltip>, which includes registering your `authorization_details` types.
* If you're using email notifications with CIBA with RAR, [set a customized consent prompt](/docs/get-started/apis/configure-rich-authorization-requests#set-customized-consent-prompt).

## Step 1: Client application initiates a CIBA request

Use the [User Search APIs](/docs/manage-users/user-search) to find the authorizing user for whom you’d like to initiate a CIBA request and obtain their user ID.

Once you have a user ID for the authorizing user, use the [Authentication API](https://auth0.com/docs/api/authentication/login/start-back-channel-login) to send a CIBA request with the `authorization_details` to the `/bc-authorize` endpoint:

```bash lines theme={null}
curl --location 'https://{YOUR_DOMAIN}.auth0.com/bc-authorize' \
  --request POST \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id={YOUR_CLIENT_ID}' \
  --data-urlencode 'client_secret={YOUR_CLIENT_SECRET}' \
  --data-urlencode 'login_hint={ "format": "iss_sub", "iss": "https://{YOUR_DOMAIN}.auth0.com/", "sub":"{USER_ID}"}' \
  --data-urlencode 'audience=https://api.example.com' \
  --data-urlencode 'binding_message=Confirm payment of 2500' \
  --data-urlencode 'authorization_details=[{
      "type": "money_transfer", 
      "instructedAmount": {
        "amount": 2500, 
        "currency": "USD"
      }, 
      "sourceAccount": "xxxxxxxxxxx1234", 
      "destinationAccount": "xxxxxxxxxxx9876", 
      "beneficiary": "Hanna Herwitz", 
      "subject": "A Lannister Always Pays His Debts"
    }]'
```

<table>
  <thead>
    <tr>
      <th><strong>Parameters</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>tenant</code></td>
      <td>Tenant name that is passed within the <code>login\_hint</code> structure. It can also be a custom domain. If the `iss_sub` format is used, then the tenant name is passed within the `iss` claim.<br /><br /> **Example**: `login_hint={"format": "iss_sub", "iss": "https://{YOUR_DOMAIN}.auth0.com/", "sub":"{USER_ID"}`</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Client application identifier.</td>
    </tr>

    <tr>
      <td><code>client\_secret</code></td>
      <td>Client authentication method used for user authentication with CIBA, such as Client Secret, Private Key JWT, or mTLS Authentication. If you're using Private Key JWT or mTLS, you don't need to include the client secret.</td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td>Must include <code>openid</code>.<br /><br />The scope can optionally include <code>offline\_access</code> to request a refresh token. However, for one-time authorization of a transaction with the CIBA Flow, a refresh token is not needed and does not have any meaning in this context.<br /></td>
    </tr>

    <tr>
      <td><code>user\_id</code></td>
      <td>User ID for the authorizing user that is passed within the <code>login\_hint</code> structure. If <code>iss\_sub</code> format is used, then the user ID is passed within the <code>sub</code> claim. <br /><br /> **Example**: `login_hint={"format": "iss_sub", "iss": "https://{YOUR_DOMAIN}.auth0.com/", "sub":"{USER_ID}"}` <br /><br />The user ID may have a different format depending on the external provider.<br /></td>
    </tr>

    <tr>
      <td><code>requested\_expiry</code></td>
      <td>The CIBA flow's requested expiry is between 1 and 259200 (72 hours) seconds, and it defaults to 300 seconds. Include the <code>requested\_expiry</code> parameter to set a custom expiry for the CIBA flow.<br /><br />The `requested_expiry` parameter helps determine which notification channel CIBA uses:<ul><li>If you set your `requested_expiry` to a value of 300 or lower in seconds, CIBA uses the mobile push notification channel if enabled. If you have not configured MFA for your tenant, the CIBA request fails.</li><li>If you set your `requested_expiry` to a value between 301 to 259200 seconds, CIBA uses the email notification channel if enabled.</li></ul></td>
    </tr>

    <tr>
      <td><code>binding\_message</code></td>
      <td>Human-readable message used to bind the CIBA flow across the authentication and consumption devices. The binding message is required and up to 64 characters. Use only alphanumeric and <code>+-\_.,:#</code> characters</td>
    </tr>

    <tr>
      <td><code>audience</code></td>
      <td>Unique identifier of the audience for the issued token.</td>
    </tr>

    <tr>
      <td><code>authorization\_details</code></td>
      <td>An optional JSON array of objects that describes the permissions to be authorized. You should register each object’s <code>type</code> value on the resource server using the resource server’s <code>authorization\_details</code> parameter. To learn more, read <a href="/docs/get-started/apis/configure-rich-authorization-requests">Configure Rich Authorization Requests</a>.</td>
    </tr>
  </tbody>
</table>

## Step 2: Auth0 tenant acknowledges the CIBA request

If the Auth0 tenant successfully receives the `POST` request, you should receive a response containing an `auth-req-id` that references the request:

```json lines theme={null}
{
    "auth_req_id": "eyJh...",
    "expires_in": 300,
    "interval": 5
}
```

The `auth_req_id` value is passed to the `/token` endpoint to poll for the completion of the CIBA flow.

## Step 3: Client application polls for a response

Use the [Authentication API](https://auth0.com/docs/api/authentication/login/start-back-channel-login) to call the `/token` endpoint using the `urn:openid:params:grant-type:ciba` grant type and the `auth_req_id` you received from the `/bc-authorize` endpoint:

<Tabs>
  <Tab title="cURL">
    ```bash lines theme={null}
    curl --location 'https://{YOUR_DOMAIN}.auth0.com/oauth/token' \
      --header 'Content-Type: application/x-www-form-urlencoded' \
      --data-urlencode 'client_id={YOUR_CLIENT_ID}' \
      --data-urlencode 'client_secret={YOUR_CLIENT_SECRET}' \
      --data-urlencode 'auth_req_id={AUTH_REQ_ID}' \
      --data-urlencode 'grant_type=urn:openid:params:grant-type:ciba'
    ```
  </Tab>

  <Tab title="C#">
    ```csharp lines theme={null}
    var token = await authenticationApiClient.GetTokenAsync(
                new ClientInitiatedBackchannelAuthorizationTokenRequest()
                {
                    AuthRequestId = response.AuthRequestId,
                    ClientId = "your-client-id",
                    ClientSecret = "your-client-secret"
                }
            );
    ```
  </Tab>

  <Tab title="Go">
    ```go lines theme={null}
    token, err := authAPI.OAuth.LoginWithGrant(context.Background(),
    			"urn:openid:params:grant-type:ciba",
    			url.Values{
    				"auth_req_id":   []string{resp.AuthReqID},
    				"client_id":     []string{clientID},
    				"client_secret": []string{clientSecret},
    			},
    			oauth.IDTokenValidationOptions{})
    ```
  </Tab>

  <Tab title="Java">
    ```java lines theme={null}
    Request<BackChannelTokenResponse> tokenRequest = auth.getBackChannelLoginStatus(authReqId, "grant-type");

    BackChannelTokenResponse tokenResponse = tokenRequest.execute().getBody();
    ```
  </Tab>
</Tabs>

Until the authorizing user approves the transaction, you should receive the following response:

```json lines theme={null}
{
    "error": "authorization_pending",
    "error_description": "The end-user authorization is pending"
}
```

There is approximately a five-second wait interval for polling. If you poll too frequently, you will receive the following response, where the description varies depending on the backoff interval:

```json lines theme={null}
{
"error": "slow_down",
"error_description": "You are polling faster than allowed. Try again in 10 seconds."
"interval": 10
}
```

To resolve the error, wait until the next interval (in seconds) to poll the `/token` endpoint.

## Step 4: Authentication device receives the notification

Depending on the notification channel, Auth0 sends a notification to the authentication device:

* [Mobile push notification](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/mobile-push-notifications-with-ciba#step-4%3A-mobile-application-receives-the-push-notification): Auth0 sends it to the Auth0 Guardian app or a custom mobile app integrated with the Auth0 Guardian SDK.
* [Email notification](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/email-notifications-with-ciba#step-4%3A-auth0-sends-a-link-to-the-user’s-email-address): Auth0 sends it to the user’s verified email address.

## Step 5: Authentication device retrieves the consent details

The authentication device retrieves the consent details i.e. the contents of the `binding_message` from the Auth0 Consent API:

* [Mobile push notification](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/mobile-push-notifications-with-ciba#step-5%3A-mobile-application-retrieves-the-consent-details): The Auth0 Guardian app or a custom app integrated with the Auth0 Guardian SDK calls the Auth0 Consent API to retrieve the consent details.
* [Email notification](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/email-notifications-with-ciba#step-5%3A-user-authenticates-in-the-browser): When the user clicks on the verification link, they are redirected to the browser, which retrieves the consent details from the Auth0 Consent API.

## Step 6: Authentication device presents the consent details to the user

The Auth0 Consent API responds to the authentication device with the consent details, including the `binding_message`, `scope`, `audience`, and `authorization_details` if configured. The scopes returned to the mobile application are filtered according to your RBAC policy. To learn more, read [Role-Based Access Control](/docs/manage-users/access-control/rbac).

The following code sample is an example response from the Auth0 Consent API:

```json lines theme={null}
{
  "id": "cns_2309dsfsd098",
  "requested_details": {
    "audience": "https://api.example.com",
    "scope": ["read:profile", "write:profile"],
    "binding_message": "abc123",
    "authorization_details": [
      {
        "type": "money_transfer",
        "instructedAmount": {
          "amount": 2500,
          "currency": "USD"
        },
        "sourceAccount": "xxxxxxxxxxx1234",
        "destinationAccount": "xxxxxxxxxxx9876",
        "beneficiary": "Hanna Herwitz",
        "subject": "A Lannister Always Pays His Debts"
      }
    ]
  },
  "created_at": 1632739200,
  "expires_at": 1632739200
}
```

The authentication device presents the consent details with the `authorization_details` to the user:

* [Mobile push notification](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/mobile-push-notifications-with-ciba#step-6%3A-mobile-application-presents-the-consent-details-to-the-user): The Auth0 Guardian app renders the `authorization_details` in a consent screen using a push notification.
* [Email notification](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/email-notifications-with-ciba#step-6%3A-browser-sends-the-user-response-back-to-auth0): The browser renders the `authorization_details` in a custom consent screen. To learn how to customize the consent screen, read [Set customized consent prompt](/docs/get-started/apis/configure-rich-authorization-requests#set-customized-consent-prompt).

The user can accept or decline the authorization request at this point.

## Step 7: Authentication device sends the user response back to Auth0

After the user accepts or declines the authorization request, the authentication device sends the user response back to Auth0:

* [Mobile push notification](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/mobile-push-notifications-with-ciba#step-7%3A-mobile-application-sends-the-user-response-back-to-auth0): The Auth0 Guardian app or a custom app integrated with the Auth0 Guardian SDK sends the user response back to Auth0.
* [Email notification](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow/email-notifications-with-ciba#step-6%3A-browser-sends-the-user-response-back-to-auth0): The browser sends the user response back to Auth0.

## Step 8: Auth0 receives user response after the flow completes

The client application completes the polling upon receiving a response from the `/token` endpoint. A CIBA flow always requires a response, either an approval or decline, from the authorizing user, and existing grants are not checked. This means Auth0 treats every CIBA request as a fresh authorization for the authorizing user.

## Step 9: Auth0 returns access token to client application

If the user rejects the push request, Auth0 returns an error response like the following to the client application:

```json lines theme={null}
{
    "error": "access_denied",
    "error_description": "The end-user denied the authorization request or it has been expired"
}
```

If the user approves the push request, Auth0 returns an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> with the `authorization_details` like the following to the client application:

```json lines theme={null}
{
  "id_token": "...",
  "access_token": "...",
  "expires_in": "...",
  "scope": "{SCOPES}",
  "authorization_details": [{
      "type": "money_transfer", 
      "instructedAmount": {
        "amount": 2500, 
        "currency": "USD"
      }, 
      "sourceAccount": "xxxxxxxxxxx1234", 
      "destinationAccount": "xxxxxxxxxxx9876", 
      "beneficiary": "Hanna Herwitz", 
      "subject": "A Lannister Always Pays His Debts"
    }]
}
```

<Callout icon="file-lines">
  The `refresh_token` will only be present if the `offline_access` scope was included in the initial `/bc-authorize` request.
</Callout>

## Query authorization\_details

At compile time, you can query the type and objects of `authorization_details` from the consent details in a strongly typed manner as you would dynamically query JSON:

<Tabs>
  <Tab title="iOS">
    ```swift lines theme={null}
    let requestedDetails: ConsentRequestedDetails = payload.requestedDetails
    let myAuthorizationDetailsTypes = requestedDetails.authorizationDetails[0].objectValue!;
    let type = myAuthorizationDetailsTypes["type"]?.stringValue // Your pre-registered type value
    let stringProperty = myAuthorizationDetailsTypes["string_property"]?.stringValue
    let boolProperty = myAuthorizationDetailsTypes["bool_property"]?.boolValue
    let numericProperty = myAuthorizationDetailsTypes["numeric_property"]?.doubleValue
    let nestedObjectProperty = myAuthorizationDetailsTypes["nested_property"]?.objectValue
    let nestedArrayProperty = myAuthorizationDetailsTypes["nested_array_property"]?.arrayValue
    ```
  </Tab>

  <Tab title="Android">
    ```kotlin lines theme={null}
    RichConsentRequestedDetails requestedDetails = consentDetails.getRequestedDetails();
    Map<String, Object> authorizationDetails = requestedDetails.getAuthorizationDetails().get(0);
    String type = (String) myAuthorizationDetailsTypes.get("type");
    String stringProperty = (String) myAuthorizationDetailsTypes.get("string_property");
    boolean booleanProperty = (boolean) myAuthorizationDetailsTypes.get("boolean_property");
    int numericProperty = (int) myAuthorizationDetailsTypes.get("numeric_property");
    Object nestedObjectProperty = myAuthorizationDetailsTypes.get("nested_property");
    List<Object> nestedArrayProperty = (List<Object>) myAuthorizationDetailsTypes.get("nested_array_property");
    ```
  </Tab>
</Tabs>

If you define a custom type to represent your object, you can use the `filterAuthorizationDetailsByType()` function to return all `authorization_details` objects that match the desired type.

The following code sample queries `authorization_details` with the `payment` type:

<Tabs>
  <Tab title="iOS">
    ```swift lines theme={null}
    // Must implement AuthorizationDetailsType 
    struct Payment : AuthorizationDetailsType { 
    static let type = "payment"; 
    let amount: Double; 
    let currency: String; 
    } 

    ... 

    let requestedDetails: ConsentRequestedDetails = payload.requestedDetails 
    let payments = requestedDetails.filterAuthorizationDetailsByType(Payment.self) 
    let firstPayment = payments.first!
    let type: String = firstPayment.type // "payment" 
    let amount: Double = firstPayment.amount 
    let currency: String = firstPayment.currency
    ```
  </Tab>

  <Tab title="Android">
    ```kotlin lines expandable theme={null}
    @AuthorizatioDetailsType("payment")
    class Payment {
        private String type;
        private int amount;
        private String currency;

        public Payment(String type, int amount, String currency) {
            this.type = type;
            this.amount = amount;
            this.currency = currency;
        }

        public String getType() {
            return type;
        }

        public int getAmount() {
            return amount;
        }

        public String getCurrency() {
            return currency;
        }
    }

    ...

    RichConsentRequestedDetails requestedDetails = consentDetails.getRequestedDetails();
    List<Payment> payments = requestedDetails.filterAuthorizationDetailsByType(Payment.class);
    Payment firstPayment = payments.get(0);
    String type = firstPayment.getType();
    int amount = firstPayment.getAmount();
    String currency = firstPayment.getCurrency();
    ```
  </Tab>
</Tabs>

`filterAuthorizationDetailsByType()` only returns objects matching the specified `authorization_details` type. As a result, your mobile application should present all relevant `authorization_details` to the user for consent, regardless of their type, to ensure a complete understanding of the request

You can also query the `authorization_details` when the AI agent or application polls the `/oauth/token`endpoint for a response:

```bash lines theme={null}
curl --request POST \
  --url "https://{YOUR_DOMAIN}.auth0.com/oauth/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:openid:params:grant-type:ciba" \
  --data-urlencode "client_id={YOUR_CLIENT_ID}" \
  --data-urlencode "client_secret={YOUR_CLIENT_SECRET}" \
  --data-urlencode "auth_req_id={AUTH_REQ_ID}"
```

<table>
  <thead>
    <tr>
      <th><strong>Parameters</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td>Set to the CIBA grant type: <code>urn:openid:params:grant-type:ciba</code></td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Set to the application’s client ID.</td>
    </tr>

    <tr>
      <td><code>client\_secret</code></td>
      <td>Set to the application’s client secret.</td>
    </tr>

    <tr>
      <td><code>auth\_req\_id</code></td>
      <td>Returned from the Auth0 tenant when it acknowledges the CIBA request. References the CIBA request.</td>
    </tr>
  </tbody>
</table>

When the authorizing user approves the request, Auth0 receives the user response, and the CIBA flow completes, returning an access token and `authorization_details` array:

```json lines theme={null}
{ 
  "access_token": "ey...ZQ", 
  "expires_in": 86400, 
  "authorization_details": [{ 
    "type": "money_transfer", 
    "instructedAmount": {
      "amount": 2500, 
      "currency": "USD"
    }, 
    "sourceAccount": "xxxxxxxxxxx1234", 
    "destinationAccount": "xxxxxxxxxxx9876", 
    "beneficiary": "Hanna Herwitz", 
    "subject": "A Lannister Always Pays His Debts" 
  }], 
  "token_type": "Bearer" 
}
```

## Limitations

Auth0 doesn’t support:

* Modifying RAR in Actions for CIBA flows.
* Advertising RAR types for clients to discover, which means you need to pre-register clients with the `authorization_details` types they can send.
* Validating RAR objects beyond checking that they have a `type` property that matches allowed types for the API. Your resource server is responsible for the granular validation of the content within `authorization_details`. For more information, see [Configure RAR](/docs/get-started/apis/configure-rich-authorization-requests).

## Learn more

* [Configure Rich Authorization Requests (RAR)](/docs/get-started/apis/configure-rich-authorization-requests)
* [Authorization Code Flow with Rich Authorization Requests (RAR)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-rar)
* [Configure Client-Initiated Backchannel Authentication](/docs/get-started/applications/configure-client-initiated-backchannel-authentication)


# Device Authorization Flow
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow

Learn how the Device Authorization flow works and why you should use it for input-constrained devices, such as smart TVs and media consoles. For use with native apps.

With input-constrained devices that connect to the internet, rather than authenticate the user directly, the device asks the user to go to a link on their computer or smartphone and authorize the device. This avoids a poor user experience for devices that do not have an easy way to enter text. To do this, device apps use the Device <Tooltip href="/docs/glossary?term=Authorization+Flow">Authorization Flow</Tooltip> (ratified in [OAuth 2.0](https://tools.ietf.org/html/rfc8628)), in which they pass along their <Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip> to initiate the authorization process and get a token.

## How it works

The Device Authorization Flow contains two different paths; one occurs on the device requesting authorization and the other occurs in a browser. The browser flow path, wherein a device code is bound to the session in the browser, occurs in parallel to part of the device flow path.

<Frame>
  <img alt="Flows - Device Authorization - Authorization sequence diagram" />
</Frame>

### Device Flow

1. The user starts the app on the device.
2. The device app requests authorization from the Auth0 Authorization Server using its Client ID (`/oauth/device/code` endpoint).
3. The Auth0 Authorization Server responds with a `device_code`, `user_code`, `verification_uri`, `verification_uri_complete` `expires_in` (lifetime in seconds for `device_code` and `user_code`), and polling `interval`.
4. The device app asks the user to activate using their computer or smartphone. The app may accomplish this by:

   * asking the user to visit the `verification_uri` and enter the `user_code` after displaying these values on-screen
   * asking the user to interact with either a QR Code or shortened URL with embedded user code generated from the `verification_uri_complete`
   * directly navigating to the verification page with embedded user code using `verification_uri_complete`, if running natively on a browser-based device
5. The device app begins polling your Auth0 Authorization Server for an Access Token (**/oauth/token** endpoint) using the time period specified by `interval` and counting from receipt of the last polling request's response. The device app continues polling until either the user completes the browser flow path or the user code expires.
6. When the user successfully completes the browser flow path, your Auth0 Authorization Server responds with an Access Token (and optionally, a Refresh Token). The device app should now forget its `device_code` because it will expire.
7. Your device app can use the Access Token to call an API to access information about the user.
8. The API responds with requested data.

### Browser Flow

1. The user visits the `verification_uri` on their computer, enters the `user_code` and confirms that the device that is being activated is displaying the `user_code`. If the user visits the `verification_uri_complete` by any other mechanism (such as by scanning a QR code), only the device confirmation will be needed.
2. Your Auth0 Authorization Server redirects the user to the login and consent prompt, if needed.
3. The user authenticates using one of the configured login options and may see a consent page asking to authorize the device app.
4. Your device app is authorized to access the API.

## How to implement it

The easiest way to implement the Device Authorization Flow is to follow our tutorial: [Call API Using Device Authorization Flow](/docs/get-started/authentication-and-authorization-flow/device-authorization-flow/call-your-api-using-the-device-authorization-flow).

## Force device reauthorization

To force the user to reauthorize a device, you must revoke the <Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip> assigned to the device. To learn how, read [Unlink Devices from Users](/docs/manage-users/user-accounts/unlink-devices-from-users). Note that the device will not be forced to reauthorize until the current <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> expires and the application tries to use the revoked Refresh Token. To learn more about Refresh Tokens, read [Refresh Tokens](/docs/secure/tokens/refresh-tokens).

## Learn more

* [Tokens](/docs/secure/tokens)
* [Token Best Practices](/docs/secure/tokens/token-best-practices)
* [Which OAuth 2.0 Flow Should I Use?](/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use)
* [Auth0 Actions](/docs/customize/actions)


# Call Your API Using the Device Authorization Flow
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow/call-your-api-using-the-device-authorization-flow

Learn how to call your API from an input-constrained device using the Device Authorization flow.

<Callout icon="file-lines">
  This tutorial will help you call your own API from an input-constrained device using the Device Authorization Flow. If you want to learn how the flow works and why you should use it, see [Device Authorization Flow](/docs/get-started/authentication-and-authorization-flow/device-authorization-flow).
</Callout>

Auth0 makes it easy for your app to implement the Device <Tooltip href="/docs/glossary?term=Authorization+flow">Authorization flow</Tooltip> using:

* [Authentication API](https://auth0.com/docs/api/authentication): Keep reading to learn how to call our API directly. For an interactive experience, read [Device Flow Playground](https://auth0.github.io/device-flow-playground/).

## Prerequisites

Before beginning this tutorial:

* Check limitations (below) to be sure the Device Authorization flow is suitable for your implementation.
* [Register the Application with Auth0](/docs/get-started/auth0-overview/create-applications/native-apps).

  * Select an **Application Type** of **Native**.
  * If necessary, set **Allowed Web Origins**. You can use this to allow localhost as an origin for local development, or to set an allowed origin for specific TV software with architecture subject to CORS (e.g., HTML5 + JS). Most applications will not use this setting.
  * Ensure that the **OIDC Conformant** toggle is enabled. This setting is in the [Dashboard](https://manage.auth0.com/#) under **Applications > Application > Advanced Settings > OAuth**.
  * Make sure the Application's **Grant Types** include **Device Code**. To learn how, read [Update Grant Types](/docs/get-started/applications/update-grant-types).
  * If you want your Application to be able to use Refresh Tokens, make sure the Application's **Grant Types** include **Refresh Token**. To learn how, read [Update Grant Types](/docs/get-started/applications/update-grant-types). To learn more about Refresh Tokens, read [Refresh Tokens](/docs/secure/tokens/refresh-tokens).
* Set up and enable at least one connection for the Application: [Database connections](/docs/get-started/applications/set-up-database-connections), [Social connections](/docs/authenticate/identity-providers/social-identity-providers)
* [Register your API with Auth0](/docs/get-started/architecture-scenarios/mobile-api/part-2#create-the-api)

  * If you want your API to receive Refresh Tokens to allow it to obtain new tokens when the previous ones expire, enable **Allow Offline Access**. To learn more about Refresh Tokens, read [Refresh Tokens](/docs/secure/tokens/refresh-tokens).
* [Configure Device User Code Settings](/docs/get-started/tenant-settings/configure-device-user-code-settings) to define the character set, format, and length of your randomly-generated user code.

## Steps

1. [Request device code](#request-device-code) (Device Flow): Request a device code that the user can use to authorize the device.
2. [Request device activation](#request-device-activation) (Device Flow): Request that the user authorize the device using their laptop or smartphone.
3. [Request tokens](#request-tokens) (Device Flow): Poll the token endpoint to request a token.
4. [Authorize user](#authorize-user) (Browser Flow): The user authorizes the device, so the device can receive tokens.
5. [Receive tokens](#receive-tokens) (Device Flow): After the user successfully authorizes the device, receive tokens.
6. [Call API](#call-your-api) (Device Flow): Use the retrieved Access Token to call your API.
7. [Refresh tokens](#refresh-tokens) (Device Flow): Use a Refresh Token to request new tokens when the existing ones expire.

Optional: [Explore sample use cases](#sample-use-cases).

Optional: [Troubleshoot](#troubleshoot).

### Request device code

Once the user has started their device app and wants to authorize the device, you'll need to get a device code. When the user begins their session in their browser-based device, this code will be bound to that session.

To get the device code, your app must request a code from the [device code URL](https://auth0.com/docs/api/authentication#get-device-code), including the <Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>.

#### Example POST to device code URL

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/device/code' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data 'client_id={yourClientId}' \
    --data 'scope={scope}' \
    --data 'audience={audience}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/device/code");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "client_id={yourClientId}&scope=%7Bscope%7D&audience=%7Baudience%7D", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/oauth/device/code"

  	payload := strings.NewReader("client_id={yourClientId}&scope=%7Bscope%7D&audience=%7Baudience%7D")

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

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.post("https://{yourDomain}/oauth/device/code")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("client_id={yourClientId}&scope=%7Bscope%7D&audience=%7Baudience%7D")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/device/code',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: {client_id: '{yourClientId}', scope: '{scope}', audience: '{audience}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/device/code",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "client_id={yourClientId}&scope=%7Bscope%7D&audience=%7Baudience%7D",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "client_id={yourClientId}&scope=%7Bscope%7D&audience=%7Baudience%7D"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/device/code", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/device/code")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "client_id={yourClientId}&scope=%7Bscope%7D&audience=%7Baudience%7D"

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

##### Device code parameters

Note that when requesting a device code to call a custom API, you:

* must include an <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> parameter
* can include additional scopes supported by the target API

<Callout icon="file-lines">
  If your app wants an Access Token only to retrieve info about the authenticated user, then no audience parameter is required.
</Callout>

<table>
  <thead>
    <tr>
      <th>Parameter Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>client\_id</code></td>
      <td>Your application's Client ID. You can find this value in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>.</td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td>The <a href="/docs/get-started/apis/scopes">scopes</a> for which you want to request authorization. These must be separated by a space. You can request any of the <a href="https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims">standard OIDC scopes</a> about users, such as <code>profile</code> and <code>email</code>, <a href="/docs/secure/tokens/json-web-tokens/json-web-token-claims#custom-claims">custom claims</a> conforming to a <a href="/docs/secure/tokens/json-web-tokens/create-custom-claims">namespaced format</a>, or any <a href="/docs/get-started/apis/scopes/api-scopes">scopes supported by the target API</a> (e.g., <code>read:contacts</code>). Include <code>openid</code> to get an ID Token or to be able to use the <a href="https://auth0.com/docs/api/authentication#user-profile">/userinfo endpoint</a> to retrieve profile information for the user. Include <code>offline\_access</code> to get a Refresh Token (make sure that the <strong>Allow Offline Access</strong> field is enabled in the <a href="https://manage.auth0.com/#/apis">API Settings</a>). Note that this must be URL encoded.</td>
    </tr>

    <tr>
      <td><code>audience</code></td>
      <td>The unique identifier of the API your app wants to access. Use the <strong>Identifier</strong> value on the <a href="https://manage.auth0.com/#/apis">Settings</a> tab for the API you created as part of the prerequisites for this tutorial.  Note that this must be URL encoded.</td>
    </tr>
  </tbody>
</table>

#### Device code response

If all goes well, you'll receive an `HTTP 200` response with a payload containing `device_code`, `user_code`, `verification_uri`, and `expires_in`, `interval`, and `verification_uri_complete` values:

```json lines theme={null}
{
  "device_code": "Ag_EE...ko1p",
  "user_code": "QTZL-MCBW",
  "verification_uri": "https://accounts.acmetest.org/activate",
  "verification_uri_complete": "https://accounts.acmetest.org/activate?user_code=QTZL-MCBW",
  "expires_in": 900,
  "interval": 5
}
```

* `device_code` is the unique code for the device. When the user goes to the `verification_uri` in their browser-based device, this code will be bound to their session.
* `user_code` contains the code that should be input at the `verification_uri` to authorize the device.
* `verification_uri` contains the URL the user should visit to authorize the device.
* `verification_uri_complete` contains the complete URL the user should visit to authorize the device. This allows your app to embed the `user_code` in the URL, if you so choose.
* `expires_in` indicates the lifetime (in seconds) of the `device_code` and `user_code`.
* `interval` indicates the interval (in seconds) at which the app should poll the token URL to request a token.

<Callout icon="file-lines">
  You can [configure the character set, format, and length of your randomly-generated user code](/docs/get-started/tenant-settings/configure-device-user-code-settings) in your tenant settings.

  To prevent brute force attacks, we enforce the following limits on `user_code`:

  **Minimum length**:

  * BASE20 Letters: 8 characters
  * Numbers: 9 characters

  **Maximum length**:

  * 20 characters (including hyphens and spaces, which may be added as separators for readability)

  **Expiration time**:

  * 15 minutes
</Callout>

### Request device activation

Once you have received a `device_code` and `user_code`, you must ask the user to go to the `verification_uri` on their laptop or smartphone and enter the `user_code`:

<Frame>
  <img alt="Auth0 Flows Device Authorization Request, sample page showing two activation methods, user_code and QR code" />
</Frame>

The `device_code` is not intended for the user directly and should not be displayed during the interaction to avoid confusing the user.

<Callout icon="file-lines">
  When building a CLI, you could skip this step and immediately open the browser with `verification_uri_complete`.
</Callout>

### Request tokens

While you are waiting for the user to activate the device, begin polling the token URL to request an <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>. Using the extracted polling interval (`interval`) from the previous step, you will need to `POST` to the [token URL](https://auth0.com/docs/api/authentication#device-auth) sending along the `device_code`.

To avoid errors due to network latency, you should start counting each interval after receipt of the last polling request's response.

#### Example request token POST to token URL

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=urn:ietf:params:oauth:grant-type:device_code \
    --data 'device_code={yourDeviceCode}' \
    --data 'client_id={yourClientId}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code&device_code=%7ByourDeviceCode%7D&client_id={yourClientId}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code&device_code=%7ByourDeviceCode%7D&client_id={yourClientId}")

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

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code&device_code=%7ByourDeviceCode%7D&client_id={yourClientId}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
      device_code: '{yourDeviceCode}',
      client_id: '{yourClientId}'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code&device_code=%7ByourDeviceCode%7D&client_id={yourClientId}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code&device_code=%7ByourDeviceCode%7D&client_id={yourClientId}"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code&device_code=%7ByourDeviceCode%7D&client_id={yourClientId}"

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

##### Token request parameters

<table>
  <thead>
    <tr>
      <th>Parameter Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td>Set this to "urn:ietf:params:oauth:grant-type:device\_code". This is an extension grant type (as defined by Section 4.5 of <a href="https://tools.ietf.org/html/rfc6749#section-4.5">RFC6749</a>). Note that this must be URL encoded.</td>
    </tr>

    <tr>
      <td><code>device\_code</code></td>
      <td>The <code>device\_code</code> retrieved in the previous step of this tutorial.</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Your application's Client ID. You can find this value in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>.</td>
    </tr>
  </tbody>
</table>

#### Token responses

While you wait for the user to authorize the device, you may receive a few different `HTTP 4xx` responses:

##### Authorization pending

You will see this error while waiting for the user to take action. Continue polling using the suggested interval retrieved in the previous step of this tutorial.

```json lines theme={null}
HTTP/1.1 403 Forbidden
{
  "error": "authorization_pending",
  "error_description": "..."
}
```

##### Slow down

You are polling too fast. Slow down and use the suggested interval retrieved in the previous step of this tutorial. To avoid receiving this error due to network latency, you should start counting each interval after receipt of the last polling request's response.

```json lines theme={null}
HTTP/1.1 429 Too Many Requests
{
  "error": "slow_down",
  "error_description": "..."
}
```

##### Expired token

The user has not authorized the device quickly enough, so the `device_code` has expired. Your application should notify the user that the flow has expired and prompt them to reinitiate the flow.

<Warning>
  The `expired_token` error will be returned exactly once; after that, `invalid_grant` is returned. Your device **must** stop polling.
</Warning>

```json lines theme={null}
HTTP/1.1 403 Bad Request
{ 
  "error": "expired_token",
  "error_description": "..."
}
```

##### Access denied

Finally, if access is denied, you will receive:

```json lines theme={null}
HTTP/1.1 403 Forbidden
{
  "error": "access_denied",
  "error_description": "..."
}
```

This can occur for a variety of reasons, including:

* the user refused to authorize the device
* the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip> denied the transaction
* a configured rule denied access (To learn more, read [Auth0 Rules](/docs/customize/rules).)

### Authorize user

The user will either scan the QR code, or else will open the activation page and enter the user code:

<Frame>
  <img alt="Auth0 Flows Device Authorization prompt directing the user to enter the code displayed on their device" />
</Frame>

A confirmation page will be shown to have the user confirm that this is the right device:

<Frame>
  <img alt="Auth0 Flows Device Authorization sample confirmation prompt directing the user to confirm the code" />
</Frame>

The user will complete the transaction by signing in. This step may include one or more of the following processes:

* Authenticating the user;
* Redirecting the user to an <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> to handle authentication;
* Checking for active <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> sessions;
* Obtaining user consent for the device, unless consent has been previously given.

<Frame>
  <img alt="Auth0 Flows Device Authorization User authorization prompt directing the user to log in with email and password or with Google or another identity" />
</Frame>

Upon successful authentication and consent, the confirmation prompt will be shown:

<Frame>
  <img alt="Flows - Device Authorization - Congratulations notification for user" />
</Frame>

At this point, the user has authenticated, and the device has been authorized.

### Receive tokens

While the user has been authenticating and authorizing the device, the device app has continued to poll the token URL to request an Access Token.

Once the user has successfully authorized the device, you'll receive an `HTTP 200` response with a payload containing `access_token`, `refresh_token` (optionally), `id_token` (optionally), `token_type`, and `expires_in` values:

```json lines theme={null}
{
  "access_token":"eyJz93a...k4laUWw",
  "refresh_token":"GEbRxBN...edjnXbL",
  "id_token": "eyJ0XAi...4faeEoQ",
  "token_type":"Bearer",
  "expires_in":86400
}
```

<Warning>
  Validate your tokens before saving them. To learn how, read [Validate ID Tokens](/docs/secure/tokens/id-tokens/validate-id-tokens) and [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens).
</Warning>

Access Tokens are used to call the Auth0 Authentication API's [`/userinfo` endpoint](https://auth0.com/docs/api/authentication#get-user-info) or another API. (To learn more about Access Tokens, read [Access Tokens](/docs/secure/tokens/access-tokens).) You will be able to use the Access Token to call `/userinfo` only if you included the `openid` scope. If you are calling your own API, the first thing your API will need to do is [verify the Access Token](/docs/secure/tokens/access-tokens/validate-access-tokens).

<Tooltip href="/docs/glossary?term=ID+Tokens">ID Tokens</Tooltip> contain user information that must be decoded and extracted. (To learn more about ID Tokens, read [ID Tokens](/docs/secure/tokens/id-tokens).) The `id_token` will only be present in the response if you included the `openid` scope.

<Tooltip href="/docs/glossary?term=Refresh+Tokens">Refresh Tokens</Tooltip> are used to obtain a new Access Token or ID Token after the previous one has expired. (To learn more about Refresh Tokens, read [Refresh Tokens](/docs/secure/tokens/refresh-tokens).) The `refresh_token` will only be present in the response if you included the `offline_access` scope and enabled **Allow Offline Access** for your API in the Dashboard.

<Warning>
  Refresh tokens must be stored securely since they allow a user to remain authenticated essentially forever.
</Warning>

### Call your API

To call your API, the application must pass the retrieved Access Token as a Bearer token in the Authorization header of your HTTP request.

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request GET \
    --url https://myapi.com/api \
    --header 'authorization: Bearer ACCESS_TOKEN' \
    --header 'content-type: application/json'
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://myapi.com/api");
  var request = new RestRequest(Method.GET);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines expandable theme={null}
  package main

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

  func main() {

  	url := "https://myapi.com/api"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("content-type", "application/json")
  	req.Header.Add("authorization", "Bearer ACCESS_TOKEN")

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

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

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

  }
  ```

  ```java Java lines theme={null}
  HttpResponse response = Unirest.get("https://myapi.com/api")
    .header("content-type", "application/json")
    .header("authorization", "Bearer ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://myapi.com/api',
    headers: {'content-type': 'application/json', authorization: 'Bearer ACCESS_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP lines expandable theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://myapi.com/api",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer ACCESS_TOKEN",
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("myapi.com")

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer ACCESS_TOKEN"
      }

  conn.request("GET", "/api", headers=headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://myapi.com/api")

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

  request = Net::HTTP::Get.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

### Refresh tokens

You have already received a Refresh Token if you've been following this tutorial and completed the following:

* configured your API to allow offline access
* included the `offline_access` scope when you initiated the authentication request through the [authorize endpoint](https://auth0.com/docs/api/authentication/reference#authorize-application)

You can use the Refresh Token to get a new Access Token. Usually, a user will need a new Access Token only after the previous one expires or when gaining access to a new resource for the first time. It's bad practice to call the endpoint to get a new Access Token every time you call an API, and Auth0 maintains rate limits that will throttle the amount of requests to the endpoint that can be executed using the same token from the same IP.

To refresh your token, make a `POST` request to the `/oauth/token` endpoint in the Authentication API, using `grant_type=refresh_token`.

#### Example refresh token POST to token URL

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=refresh_token \
    --data 'client_id={yourClientId}' \
    --data 'client_secret={yourClientSecret}' \
    --data 'refresh_token={yourRefreshToken}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=refresh_token&client_id={yourClientId}&client_secret={yourClientSecret}&refresh_token=%7ByourRefreshToken%7D", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=refresh_token&client_id={yourClientId}&client_secret={yourClientSecret}&refresh_token=%7ByourRefreshToken%7D")

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

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=refresh_token&client_id={yourClientId}&client_secret={yourClientSecret}&refresh_token=%7ByourRefreshToken%7D")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'refresh_token',
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      refresh_token: '{yourRefreshToken}'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=refresh_token&client_id={yourClientId}&client_secret={yourClientSecret}&refresh_token=%7ByourRefreshToken%7D",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=refresh_token&client_id={yourClientId}&client_secret={yourClientSecret}&refresh_token=%7ByourRefreshToken%7D"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=refresh_token&client_id={yourClientId}&client_secret={yourClientSecret}&refresh_token=%7ByourRefreshToken%7D"

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

##### Refresh token request parameters

<table>
  <thead>
    <tr>
      <th>Parameter Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td>Set this to "refresh\_token".</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Your application's Client ID. You can find this value in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>.</td>
    </tr>

    <tr>
      <td><code>client\_secret</code></td>
      <td>Your application's Client Secret. You can find this value in your <a href="https://manage.auth0.com/#/Applications/{yourClientSecret}/settings">Application Settings</a>.</td>
    </tr>

    <tr>
      <td><code>refresh\_token</code></td>
      <td>The Refresh Token to use.</td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td>(Optional) A space-delimited list of requested scope permissions. If not sent, the original scopes will be used; otherwise you can request a reduced set of scopes. Note that this must be URL encoded.</td>
    </tr>
  </tbody>
</table>

#### Refresh token response

If all goes well, you'll receive an `HTTP 200` response with a payload containing a new `access_token`, `id_token` (optionally), token lifetime in seconds (`expires_in`), granted `scope` values, and `token_type`:

```json lines theme={null}
{
  "access_token": "eyJ...MoQ",
  "expires_in": 86400,
  "scope": "openid offline_access",
  "id_token": "eyJ...0NE",
  "token_type": "Bearer"
}
```

<Warning>
  Validate your tokens before saving them. To learn how, read [Validate ID Tokens](/docs/secure/tokens/id-tokens/validate-id-tokens) and [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens).
</Warning>

## Sample use cases

### Detect device authorization flow use

You can use Rules to detect whether the current transaction is using the Device Authorization Flow. (To learn more about rules, read [Auth0 Rules](/docs/customize/rules).) To do so, check the `context` object's `protocol` property:

```javascript lines theme={null}
function (user, context, callback) {
   if (context.protocol === 'oauth2-device-code') {
      ...
   }
 
   callback(null, user, context);
}
```

### Sample implementations

* [Device Authorization Playground](https://auth0.github.io/device-flow-playground/)
* [AppleTV (Swift)](https://github.com/pushpabrol/auth0-device-flow-appletv): Simple application that shows how Auth0 can be used with the Device Authorization Flow from an AppleTV.
* [CLI (Node.js)](https://gist.github.com/panva/ebaacfe433a8677bdbf458f6e1132045): Sample implementation of a CLI that uses the Device Authorization Flow instead of the Authorization Code Flow. The major difference is that your CLI does not need to host a web server and listen on a port.

## Troubleshoot

Tenant logs are created for any interaction that takes place and can be used to troubleshoot issues. To learn more, read [Logs](/docs/deploy-monitor/logs).

### Error codes

<table>
  <thead>
    <tr>
      <th>Code</th>
      <th>Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>fdeaz</code></td>
      <td>Failed device authorization request</td>

      <td />
    </tr>

    <tr>
      <td><code>fdeac</code></td>
      <td>Failed device activation</td>

      <td />
    </tr>

    <tr>
      <td><code>fdecc</code></td>
      <td>User canceled the device confirmation</td>

      <td />
    </tr>

    <tr>
      <td><code>fede</code></td>
      <td>Failed Exchange</td>
      <td>Device Code for Access Token</td>
    </tr>

    <tr>
      <td><code>sede</code></td>
      <td>Success Exchange</td>
      <td>Device Code for Access Token</td>
    </tr>
  </tbody>
</table>

### Limitations

To use the Device Authorization Flow, devices must:

* Support Server Name Indication (SNI) when [Custom Domains](/docs/customize/custom-domains) are used
* Have an [Auth0 application type](/docs/get-started/applications) of **Native**
* Have the [Token Endpoint Authentication Method](/docs/get-started/applications/application-settings) set to **None**
* Be [OIDC-conformant](/docs/get-started/applications/application-settings)
* Not be created through [Dynamic Client Registration](/docs/get-started/applications/dynamic-client-registration)

In addition, the Device Authorization Flow does not allow:

* [Social Connections](/docs/authenticate/identity-providers/social-identity-providers) using [Auth0 developer keys](/docs/authenticate/identity-providers/social-identity-providers/devkeys) unless you are using the [Universal Login experience](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience)
* Query string parameters to be accessed from hosted login page or Rules or Actions
* [User account linking](/docs/manage-users/user-accounts/user-account-linking)

We support the full Draft 15, except for <Tooltip href="/docs/glossary?term=confidential+Clients">confidential Clients</Tooltip>. To learn more, read [OAuth 2.0 Device Authorization Grant Draft 15 on ietf.org](https://tools.ietf.org/html/draft-ietf-oauth-device-flow-15).

## Learn more

* [OAuth 2.0 Authorization Framework](/docs/authenticate/protocols/oauth)
* [OpenID Connect Protocol](/docs/authenticate/protocols/openid-connect-protocol)
* [Tokens](/docs/secure/tokens)
* [Logs](/docs/deploy-monitor/logs)


# Hybrid Flow
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/hybrid-flow

Learn how the Hybrid Flow works to provide optimum access to the ID Token while still leveraging the Authorization Code Flow for the secure and safe retrieval of Access and Refresh Tokens.

Applications that are able to securely store [Client Credentials](/docs/secure/application-credentials) may benefit from the use of the Hybrid Flow (defined in the [OpenID Connect specification, section 3.3](https://openid.net/specs/openid-connect-core-1_0.html#HybridFlowAuth)). The Hybrid flow allows your application to have immediate access to an <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> while ensuring secure and safe retrieval of <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> and <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip>. This can be useful in situations where your application needs to immediately access information about the user, but must perform some processing before gaining access to protected resources for an extended period of time.

## How it works

The Hybrid Flow combines steps from the [Implicit Flow with Form Post](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post) and [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow):

1. User selects **Login** within application.
2. Application redirects user to Auth0 Authorization Server ([`/authorize` endpoint](https://auth0.com/docs/api/authentication#authorization-code-flow)), passing along `response_type` parameter indicating type of requested credential (ID token and authorization code), and `response_mode` parameter of `form_post` to ensure security.
3. Auth0 Authorization Server redirects user to login and authorization prompt.
4. User authenticates using one of the configured login options, and may see a consent prompt listing the permissions Auth0 will give to the application.
5. Auth0 Authorization Server redirects user back to application with single-use authorization code, and ID token, access token, or both, depending on provided `response_type`.
6. Application sends authorization code, application's client ID, and application's credentials, such as Client Secret or Private Key JWT, to Auth0 Authorization Server ([`/oauth/token` endpoint](https://auth0.com/docs/api/authentication?http#authorization-code-flow43)).
7. Auth0 Authorization Server verifies authorization code, application's client ID, and application's credentials.
8. Auth0 Authorization Server responds with second ID token and access token (and optionally, a refresh token).
9. Application can use second access token to call an API to access information about user.
10. API responds with requested data.

<Callout icon="file-lines">
  If your application only needs to use Hybrid Flow for sign-on, you will not need a Refresh Token or an Access Token, only an ID Token with claims.
</Callout>

## How to implement it

You can follow our tutorial to use the Authentication API to [Call Your API Using the Hybrid Flow](/docs/get-started/authentication-and-authorization-flow/hybrid-flow/call-api-hybrid-flow).

## Learn more

* [Auth0 Rules](/docs/customize/rules)
* [Auth0 Hooks](/docs/customize/hooks)
* [Tokens](/docs/secure/tokens)
* [Token Best Practices](/docs/secure/tokens/token-best-practices)
* [Which OAuth 2.0 Flow Should I Use?](/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use)
* [Application Credentials](/docs/secure/application-credentials)


# Call Your API Using the Hybrid Flow
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/hybrid-flow/call-api-hybrid-flow

Learn how to execute the Hybrid Flow so your app can use an ID token to access information about the user while obtaining an authorization code that can be exchanged for an Access Token.

<Callout icon="file-lines">
  This tutorial will help you call your own API using the Hybrid Flow. If you want to learn how the flow works and why you should use it, see [Hybrid Flow](/docs/get-started/authentication-and-authorization-flow/hybrid-flow).
</Callout>

Auth0 makes it easy for your app to implement the Authorization Code Flow using:

* [Authentication API](https://auth0.com/docs/api/authentication): If you prefer to build your own solution, keep reading to learn how to call our API directly.

## Prerequisites

**Before beginning this tutorial:**

* [Register your Application with Auth0](/docs/get-started/auth0-overview/create-applications/regular-web-apps).

  * Select the appropriate **Application Type**.
  * Add an **Allowed Callback URL** of `{https://yourApp/callback}`.
  * Make sure your Application's **Grant Types** include **Implicit** and **Authorization Code**. To learn how, read [Update Grant Types](/docs/get-started/applications/update-grant-types).
  * If you want your Application to be able to use Refresh Tokens, make sure the Application's **Grant Types** include **Refresh Token**. To learn how, read [Update Grant Types](/docs/get-started/applications/update-grant-types). To learn more about Refresh Tokens, read [Refresh Tokens](/docs/secure/tokens/refresh-tokens).
* [Register your API with Auth0](/docs/get-started/auth0-overview/set-up-apis)

  * If you want your API to receive Refresh Tokens to allow it to obtain new tokens when the previous ones expire, enable **Allow Offline Access**.

## Steps

1. [Authorize user](#authorize-user):
   Request the user's authorization and redirect back to your app with an authorization code.
2. [Request tokens](#request-tokens):
   Exchange your authorization code for tokens.
3. [Call API](#call-api):
   Use the retrieved Access Token to call your API.
4. [Refresh tokens](#refresh-tokens):
   Use a Refresh Token to request new tokens when the existing ones expire.

Optional: [Explore sample use cases](#sample-use-cases)

### Authorize user

This step may include one or more of the following processes:

* Authenticating the user
* Redirecting the user to an <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> to handle authentication
* Checking for active <Tooltip href="/docs/glossary?term=Single+Sign-on">Single Sign-on</Tooltip> (SSO) sessions
* Obtaining user consent for the requested permission level, unless consent has been previously given.

To authorize the user, your app must send the user to the [authorization URL](https://auth0.com/docs/api/authentication#authorization-code-grant).

#### Example authorization URL

<AuthCodeBlock />

##### Parameters

Note that for authorizing a user when calling a custom API, you:

* must include an <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> parameter
* can include additional scopes supported by the target API

<table>
  <thead>
    <tr>
      <th>Parameter Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>response\_type</code></td>
      <td>Denotes the kind of credential that Auth0 will return (code or token). For this flow, the value must include <code>code</code>, but may also include <code>id\_token</code>, <code>token</code>, or <code>id\_token token</code>. Specifically, <code>id\_token</code> returns an ID Token, and <code>token</code> returns an Access Token.</td>
    </tr>

    <tr>
      <td><code>response\_mode</code></td>
      <td>Specifies the method with which response parameters should be returned. For security purposes, the value should be <code>form\_post</code>. In this mode, response parameters will be encoded as HTML form values that are transmitted via the HTTP POST method and encoded in the body using the <code>application/x-www-form-urlencoded</code> format.</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Your application's Client ID. You can find this value in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>.</td>
    </tr>

    <tr>
      <td><code>redirect\_uri</code></td>
      <td>The URL to which Auth0 will redirect the browser after authorization has been granted by the user. The Authorization Code will be available in the <code>code</code> URL parameter. You must specify this URL as a valid callback URL in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>. <br /> <br /> <strong>Warning:</strong> Per the <a href="https://tools.ietf.org/html/rfc6749#section-3.1.2">OAuth 2.0 Specification</a>, Auth0 removes everything after the hash and does <em>not</em> honor any fragments.</td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td>Specifies the <a href="/docs/get-started/apis/scopes">scopes</a> for which you want to request authorization, which dictate which claims (or user attributes) you want returned. These must be separated by a space. You can request any of the <a href="https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims">standard OpenID Connect (OIDC) scopes</a> about users, such as <code>profile</code> or <code>email</code>, <a href="/docs/secure/tokens/json-web-tokens/json-web-token-claims#custom-claims">custom claims</a> conforming to a <a href="/docs/secure/tokens/json-web-tokens/create-custom-claims">namespaced format</a>, or any scopes supported by the target API (e.g., <code>read:contacts</code>). Include <code>offline\_access</code> to get a <Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip> (make sure that the <strong>Allow Offline Access</strong> field is enabled in the <a href="https://manage.auth0.com/#/applications">Application Settings</a>).</td>
    </tr>

    <tr>
      <td><code>audience</code></td>
      <td>The unique identifier of the API your application wants to access. Use the <strong>Identifier</strong> value on the <a href="https://manage.auth0.com/#/apis">Settings</a> tab for the API you created as part of the prerequisites for this tutorial.</td>
    </tr>

    <tr>
      <td><code>state</code></td>
      <td>(recommended) An opaque arbitrary alphanumeric string your app adds to the initial request that Auth0 includes when redirecting back to your application. To see how to use this value to prevent cross-site request forgery (CSRF) attacks, see <a href="/docs/secure/attack-protection/state-parameters">Mitigate CSRF Attacks With State Parameters</a>.</td>
    </tr>

    <tr>
      <td><code>nonce</code></td>
      <td>A cryptographically random string that your app adds to the initial request and Auth0 includes inside the ID Token, <a href="/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post/mitigate-replay-attacks-when-using-the-implicit-flow">used to prevent token replay attacks</a>.</td>
    </tr>

    <tr>
      <td><code>organization</code></td>
      <td>(optional) ID of the organization to use when authenticating a user. When not provided, if your application is configured to <strong>Display Organization Prompt</strong>, the user will be able to enter the organization name when authenticating.</td>
    </tr>

    <tr>
      <td><code>invitation</code></td>
      <td>(optional) Ticket ID of the organization invitation. When <a href="/docs/manage-users/organizations/configure-organizations/invite-members">inviting a member to an Organization</a>, your application should handle invitation acceptance by forwarding the <code>invitation</code> and <code>organization</code> key-value pairs when the user accepts the invitation.</td>
    </tr>
  </tbody>
</table>

As an example, your HTML snippet for your authorization URL when adding login to your app might look like:

<AuthCodeBlock />

#### Response

If all goes well, you'll receive an `HTTP 302` response. The requested credentials are encoded in the body:

```json lines theme={null}
HTTP/1.1 302 Found
Content-Type: application/x-www-form-urlencoded
code=AUTHORIZATION_CODE&
access_token=ey...MhPw
&expires_in=7200
&token_type=Bearer
id_token=eyJ...acA&
state=xyzABC123
```

Note that the returned values depend on what you requested as a `response_type`.

<table>
  <thead>
    <tr>
      <th>Response Type</th>
      <th>Components</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>code  </code></td>
      <td>Authorization code</td>
    </tr>

    <tr>
      <td><code>id\_token </code></td>
      <td>ID Token</td>
    </tr>

    <tr>
      <td><code>token </code></td>
      <td>Access Token (plus <code>expires\_in</code> and <code>token\_type</code> values)</td>
    </tr>

    <tr>
      <td><code>id\_token token</code></td>
      <td>ID Token, Access Token (plus <code>expires\_in</code> and <code>token\_type</code> values)</td>
    </tr>
  </tbody>
</table>

Auth0 will also return any state value you included in your call to the authorization URL.

<Warning>
  The Access Token that you receive in this transaction is only the first Access Token that you will receive. We do not recommend that it be used to call APIs.
</Warning>

<Warning>
  Validate your tokens before saving them. To learn how, read [Validate ID Tokens](/docs/secure/tokens/id-tokens/validate-id-tokens) and [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens).
</Warning>

When you decode and parse your <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip>, you will notice an additional claim, `c_hash`, which contains a hash of the `code`. This claim is mandatory when an ID token is issued at the same time as a `code`, and you should validate it:

1. Using the hash algorithm specified in the `alg` claim in the ID Token header, hash the octets of the ASCII representation of the `code`.
2. Base64url-encode the left-most half of the hash.
3. Check that the result matches the `c_hash` value.

### Request tokens

Now that you have an Authorization Code, you must exchange it for tokens. Using the extracted Authorization Code (`code`) from the previous step, you will need to `POST` to the [token URL](https://auth0.com/docs/api/authentication#authorization-code).

The <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> you receive in this step is the one you should use to call your API. Make sure you keep it separate from the Access Token you received in the previous step of this tutorial.

#### Example POST to token URL

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=authorization_code \
    --data 'client_id={yourClientId}' \
    --data 'client_secret={yourClientSecret}' \
    --data 'code=yourAuthorizationCode}' \
    --data 'redirect_uri={https://yourApp/callback}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=authorization_code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&code=yourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=authorization_code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&code=yourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}")

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

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=authorization_code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&code=yourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      code: 'yourAuthorizationCode}',
      redirect_uri: '{https://yourApp/callback}'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=authorization_code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&code=yourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=authorization_code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&code=yourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=authorization_code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&code=yourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}"

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

##### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td>Set this to <code>authorization\_code</code>.</td>
    </tr>

    <tr>
      <td><code>code</code></td>
      <td>The <code>authorization\_code</code> retrieved in the previous step of this tutorial.</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Your application's Client ID. You can find this value in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>.</td>
    </tr>

    <tr>
      <td><code>client\_secret</code></td>
      <td>Your application's Client Secret. You can find this value in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>.  To learn more about available application authentication methods, read <a href="/docs/secure/application-credentials">Application Credentials</a>.</td>
    </tr>

    <tr>
      <td><code>redirect\_uri</code></td>
      <td>The valid callback URL set in your Application settings. This must exactly match the <code>redirect\_uri</code> passed to the authorization URL in the previous step of this tutorial. Note that this must be URL encoded.</td>
    </tr>
  </tbody>
</table>

#### Response

If all goes well, you'll receive an `HTTP 200` response with a payload containing `access_token`, `refresh_token`, `id_token`, and `token_type` values:

```json lines theme={null}
{
  "access_token": "eyJz93a...k4laUWw",
  "refresh_token": "GEbRxBN...edjnXbL",
  "id_token": "eyJ0XAi...4faeEoQ",
  "token_type": "Bearer"
}
```

<Warning>
  Validate your tokens before saving them. To learn how, read [Validate ID Tokens](/docs/secure/tokens/id-tokens/validate-id-tokens) and [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens).
</Warning>

[ID tokens](/docs/secure/tokens/id-tokens) contain user information that must be decoded and extracted.

[Access tokens](/docs/secure/tokens/access-tokens) are used to call the [Auth0 Authentication API's /userinfo endpoint](https://auth0.com/docs/api/authentication#get-user-info) or another API. If you are calling your own API, the first thing your API will need to do is [verify the Access token](/docs/secure/tokens/access-tokens/validate-access-tokens).

[Refresh tokens](/docs/secure/tokens/refresh-tokens) are used to obtain a new access token or ID token after the previous one has expired. The `refresh_token` will only be present in the response if you included the `offline_access` scope and enabled **Allow Offline Access** for your API in the Dashboard.

<Warning>
  Refresh tokens must be stored securely since they allow a user to remain authenticated essentially forever.
</Warning>

### Call API

To call your API from a regular web application (or similar cases in which the application credentials can be safely stored), the application must pass the retrieved Access Token as a Bearer token in the Authorization header of your HTTP request.

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request GET \
    --url https://myapi.com/api \
    --header 'authorization: Bearer {accessToken}' \
    --header 'content-type: application/json'
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://myapi.com/api");
  var request = new RestRequest(Method.GET);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer {accessToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines expandable theme={null}
  package main

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

  func main() {

  	url := "https://myapi.com/api"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("content-type", "application/json")
  	req.Header.Add("authorization", "Bearer {accessToken}")

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

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

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

  }
  ```

  ```java Java lines theme={null}
  HttpResponse response = Unirest.get("https://myapi.com/api")
    .header("content-type", "application/json")
    .header("authorization", "Bearer {accessToken}")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://myapi.com/api',
    headers: {'content-type': 'application/json', authorization: 'Bearer {accessToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP lines expandable theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://myapi.com/api",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {accessToken}",
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("myapi.com")

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer {accessToken}"
      }

  conn.request("GET", "/api", headers=headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://myapi.com/api")

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

  request = Net::HTTP::Get.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer {accessToken}'

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

### Refresh tokens

You have already received a [refresh token](/docs/secure/tokens/refresh-tokens) if you've been following this tutorial and completed the following:

* configured your API to allow offline access
* included the `offline_access` scope when you initiated the authentication request through the [authorize endpoint](https://auth0.com/docs/api/authentication/reference#authorize-application).

You can use the <Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip> to get a new access token. Usually, a user will need a new access token only after the previous one expires or when gaining access to a new resource for the first time. It's bad practice to call the endpoint to get a new access token every time you call an API, and Auth0 maintains rate limits that will throttle the amount of requests to the endpoint that can be executed using the same token from the same IP.

To refresh your token, make a `POST` request to the `/oauth/token` endpoint in the Authentication API, using `grant_type=refresh_token`.

#### Example POST to token URL

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=refresh_token \
    --data 'client_id={yourClientId}' \
    --data 'refresh_token={yourRefreshToken}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D")

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

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'refresh_token',
      client_id: '{yourClientId}',
      refresh_token: '{yourRefreshToken}'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D"

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

##### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td>Set this to <code>refresh\_token</code>.</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Your application's Client ID. You can find this value in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>.</td>
    </tr>

    <tr>
      <td><code>refresh\_token</code></td>
      <td>The refresh token to use.</td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td>(optional) A space-delimited list of requested scope permissions. If not sent, the original scopes will be used; otherwise you can request a reduced set of scopes. Note that this must be URL encoded.</td>
    </tr>
  </tbody>
</table>

#### Response

If all goes well, you'll receive an `HTTP 200` response with a payload containing a new `access_token`, its lifetime in seconds (`expires_in`), granted `scope` values, and `token_type`. If the scope of the initial token included `openid`, then the response will also include a new `id_token`:

```json lines theme={null}
{
  "access_token": "eyJ...MoQ",
  "expires_in": 86400,
  "scope": "openid offline_access",
  "id_token": "eyJ...0NE",
  "token_type": "Bearer"
}
```

<Warning>
  Validate your tokens before saving them. To learn how, read [Validate ID Tokens](/docs/secure/tokens/id-tokens/validate-id-tokens) and [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens).
</Warning>

### Sample use cases

#### Customize tokens

You can use rules to change the returned scopes of Access Tokens and/or add claims to Access and ID Tokens. (To learn more about rules, read [Auth0 Rules](/docs/customize/rules).) To do so, add the following rule, which will run after the user authenticates:

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  // Add custom claims to Access Token and ID Token
  api.accessToken.setCustomClaim('https://foo/bar', 'value');
  api.idToken.setCustomClaim('https://fiz/baz', 'some other value');

  // Modify the scope of the Access Token
  api.accessToken.addScope('foo');
  api.accessToken.addScope('bar');
};
```

Scopes will be available in the token after all rules have run.

<Warning>
  Auth0 returns profile information in a structured claim format as defined by the [OpenID Connect (OIDC) specification](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). This means that custom claims added to ID tokens or access tokens must [conform to guidelines and restrictions](/docs/secure/tokens/json-web-tokens/create-custom-claims) to avoid possible collisions.
</Warning>

## Learn more

* [OAuth 2.0 Authorization Framework](/docs/authenticate/protocols/oauth)
* [OpenID Connect Protocol](/docs/authenticate/protocols/openid-connect-protocol)
* [Tokens](/docs/secure/tokens)


# Implicit Flow with Form Post
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post

Learn how the Implicit flow with Form Post works and why you should use it for traditional web apps that need only an ID Token to perform user authentication.

<Warning>
  Don't let the term "implicit" mislead you! Although OAuth now discourages the use of the implicit grant for obtaining access tokens in SPAs, the scenario addressed by Implicit Flow with Form Post is completely different and is **unaffected by the security issues** that led to discouraging use with SPAs. Specifically, Implicit Flow with Form Post applies to traditional web apps as opposed to SPAs. You obtain ID tokens as opposed to access tokens, which have a completely different intended use. The flow uses POST as opposed to placing tokens in URL fragments (as with SPAs) which can expose token bits to browser history attacks, redirect headers, and so on.
</Warning>

You can use <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) with many different flows to achieve web sign-in for a traditional web app. In one common flow, you obtain an <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> using authorization code flow performed by the app backend. This method is effective and robust, however, it requires your web app to obtain and manage a secret. You can avoid that burden if all you want to do is implement sign-in and you don’t need to obtain <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> for invoking APIs.

Implicit Flow with Form Post flow uses OIDC to implement web sign-in that is very similar to the way <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> and WS-Federation operates. The web app requests and obtains tokens through the front channel, without the need for secrets or extra backend calls. With this method, you don’t need to obtain, maintain, use, and protect a secret in your application.

## How it works

<Warning>
  You should use this flow for login-only use cases; if you need to request Access Tokens while logging the user in so you can call an API, use the [Authorization Code Flow with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce) or the [Hybrid Flow](/docs/get-started/authentication-and-authorization-flow/hybrid-flow).
</Warning>

<Frame>
  <img alt="Flows - Implicit with Form Post - Authorization sequence diagram" />
</Frame>

1. The user clicks **Login** in the app.
2. Auth0's SDK redirects the user to the Auth0 Authorization Server (`/authorize` endpoint) passing along a `response_type` parameter of `id_token` that indicates the type of requested credential. It also passes along a `response_mode` parameter of `form_post` to ensure security.
3. Your Auth0 Authorization Server redirects the user to the login and authorization prompt.
4. The user authenticates using one of the configured login options and may see a consent page listing the permissions Auth0 will give to the app.
5. Your Auth0 Authorization Server redirects the user back to the app with an ID Token.

## How to implement it

You can [use our Express OpenID Connect SDK](https://www.npmjs.com/package/express-openid-connect) to securely implement the Implicit Flow with Form Post.

<Callout icon="file-lines">
  The [Auth0 Single-Page App SDK](/docs/libraries/auth0-single-page-app-sdk) and [Single-Page Quickstarts](/docs/quickstart/spa) adhere to the new recommendations and use the [Authorization Code Flow with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce).
</Callout>

Finally, you can follow our tutorials to use our API endpoints to [Add Login Using the Implicit Flow with Form Post](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post/add-login-using-the-implicit-flow-with-form-post).

## Learn more

* [Auth0 Rules](/docs/customize/rules)
* [Auth0 Hooks](/docs/customize/hooks)
* [Tokens](/docs/secure/tokens)
* [Token Best Practices](/docs/secure/tokens/token-best-practices)
* [Which OAuth 2.0 Flow Should I Use?](/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use)
* [Mitigate Replay Attacks When Using the Implicit Flow](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post/mitigate-replay-attacks-when-using-the-implicit-flow)


# Add Login Using the Implicit Flow with Form Post
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post/add-login-using-the-implicit-flow-with-form-post

Learn how to add login to your single-page application (SPA) using the Implicit Flow with Form Post.

You can add login to your single-page application (SPA) using the Implicit Flow with Form Post. To learn how the flow works and why you should use it, read [Implicit Flow with Form Post](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post).

Use the Implicit Flow with Form Post for login-only use cases; if you need to request <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> while logging the user in so you can call your API, use the Authorization Code Flow with PKCE. To learn more, read [Authorization Code Flow with Proof Key for Code Exchange (PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce)).

To implement the Implicit Flow with Form Post, you can use the following resources:

* [Express OpenID Connect SDK](https://www.npmjs.com/package/express-openid-connect): The easiest way to implement the flow, which will do most of the heavy-lifting for you. If you use our Javascript SDK, please ensure you are implementing mitigations that are appropriate for your architecture. To learn more, read [Auth0.js v9 Reference](/docs/libraries/auth0js).
* [Authentication API](https://auth0.com/docs/api/authentication): If you prefer to build your own solution, keep reading to learn how to call our API directly.

Following a successful login, your application will have access to the user's [ID token](/docs/secure/tokens/id-tokens). The <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> will contain basic user profile information.

## Prerequisites

Register your app with Auth0. To learn more, read [Register Single Page Applications](/docs/get-started/auth0-overview/create-applications/single-page-web-apps).

* Select **Single-Page App** as the **Application Type**.
* Add an **Allowed Callback URL** of `{https://yourApp/callback}`.
* Make sure your application's **Grant Types** include **Implicit**. To learn more, read [Update Grant Types](/docs/get-started/applications/update-grant-types).

## Authorize user

Request the user's authorization and redirect back to your app. To begin the flow, you'll need to get the user's authorization. This step may include one or more of the following processes:

* Authenticating the user;
* Redirecting the user to an <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> to handle authentication;
* Checking for active <Tooltip href="/docs/glossary?term=Single+Sign-on">Single Sign-on</Tooltip> (SSO) sessions;
* Obtaining user consent for the requested permission level, unless consent has been previously given.

To authorize the user, your app must send the user to the authorization URL.

### Authorization URL example

<AuthCodeBlock />

### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>response\_type</code></td>
      <td>Denotes the kind of credential that Auth0 will return (code or token). For the Implicit Flow, the value can be <code>id\_token</code>, <code>token</code>, or <code>id\_token token</code>. Specifically, <code>id\_token</code> returns an ID Token, and <code>token</code> returns an Access Token.</td>
    </tr>

    <tr>
      <td><code>response\_mode</code></td>
      <td>Specifies the method with which response parameters should be returned. For security purposes, the value should be <code>form\_post</code>. In this mode, response parameters will be encoded as HTML form values that are transmitted via the HTTP POST method and encoded in the body using the <code>application/x-www-form-urlencoded</code> format.</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Your application's Client ID. You can find this value at your <a href="https://manage.auth0.com/#/applications/{yourClientId}/settings">Application's Settings</a>.</td>
    </tr>

    <tr>
      <td><code>redirect\_uri</code></td>
      <td>The URL to which Auth0 will redirect the browser after authorization has been granted by the user. You must specify this URL as a valid callback URL in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>. <br /> <br /> <strong>Warning:</strong> Per the <a href="https://tools.ietf.org/html/rfc6749#section-3.1.2">OAuth 2.0 Specification</a>, Auth0 removes everything after the hash and does <em>not</em> honor any fragments.</td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td>Specifies the <a href="/docs/get-started/apis/scopes">scopes</a> for which you want to request authorization, which dictate which claims (or user attributes) you want returned. These must be separated by a space. You can request any of the <a href="https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims">standard OpenID Connect (OIDC) scopes</a> about users, such as <code>profile</code> and <code>email</code>, <a href="/docs/secure/tokens/json-web-tokens/json-web-token-claims#custom-claims">custom claims</a> conforming to a <a href="/docs/secure/tokens/json-web-tokens/create-custom-claims">namespaced format</a>, or any scopes supported by the target API (for example, <code>read:contacts</code>).</td>
    </tr>

    <tr>
      <td><code>state</code></td>
      <td>(recommended) An opaque arbitrary alphanumeric string that your app adds to the initial request and Auth0 includes when redirecting back to your application. To see how to use this value to prevent cross-site request forgery (CSRF) attacks, see <a href="/docs/secure/attack-protection/state-parameters">Mitigate CSRF Attacks With State Parameters</a>.</td>
    </tr>

    <tr>
      <td><code>nonce</code></td>
      <td>(required for <code>response\_type</code> containing  <code>id\_token token</code>, otherwise recommended) A cryptographically random string that your app adds to the initial request and Auth0 includes inside the ID Token, <a href="/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post/mitigate-replay-attacks-when-using-the-implicit-flow">used to prevent token replay attacks</a>.</td>
    </tr>

    <tr>
      <td><code>connection</code></td>
      <td>(optional) Forces the user to sign in with a specific connection. For example, you can pass a value of <code>github</code> to send the user directly to GitHub to log in with their GitHub account. When not specified, the user sees the Auth0 Lock screen with all configured connections. You can see a list of your configured connections on the <strong>Connections</strong> tab of your application.</td>
    </tr>

    <tr>
      <td><code>organization</code></td>
      <td>(optional) ID of the organization to use when authenticating a user. When not provided, if your application is configured to <strong>Display Organization Prompt</strong>, the user will be able to enter the organization name when authenticating.</td>
    </tr>

    <tr>
      <td><code>invitation</code></td>
      <td>(optional) Ticket ID of the organization invitation. When <a href="/docs/manage-users/organizations/configure-organizations/invite-members">inviting a member to an Organization</a>, your application should handle invitation acceptance by forwarding the <code>invitation</code> and <code>organization</code> key-value pairs when the user accepts the invitation.</td>
    </tr>
  </tbody>
</table>

As an example, your HTML snippet for your authorization URL when adding login to your app might look like:

<AuthCodeBlock />

### Response

If all goes well, you'll receive an `HTTP 302` response. The requested credentials are encoded in the body:

```json lines theme={null}
HTTP/1.1 302 Found
Content-Type: application/x-www-form-urlencoded
id_token=eyJ...acA&
state=xyzABC123
```

Note that the returned values depend on what you requested as a `response_type`.

<table>
  <thead>
    <tr>
      <th>Response Type</th>
      <th>Components</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>id\_token</td>
      <td>ID Token</td>
    </tr>

    <tr>
      <td>token</td>
      <td>Access Token (plus <code>expires\_in</code> and <code>token\_type</code> values)</td>
    </tr>

    <tr>
      <td>id\_token token</td>
      <td>ID Token, Access Token (plus <code>expires\_in</code> and <code>token\_type</code> values)</td>
    </tr>
  </tbody>
</table>

Auth0 will also return any state value you included in your call to the authorization URL.

<Warning>
  Validate your tokens before saving them. To learn how, read [Validate ID Tokens](/docs/secure/tokens/id-tokens/validate-id-tokens) and [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens).
</Warning>

ID tokens contain user information that must be decoded and extracted.

## Use cases

### Basic authentication request

This example shows the most basic request you can make when authorizing the user in step 1. It displays the Auth0 login screen and allows the user to sign in with any of your configured connections:

<AuthCodeBlock />

This will return an ID token, which you can parse from your redirect URL.

### Request user's name and profile picture

In addition to the usual user authentication, this example shows how to request additional user details, such as name and picture.

To request the user's name and picture, you need to add the appropriate scopes when authorizing the user:

<AuthCodeBlock />

Now, your ID token will contain the requested name and picture claims. When you decode the ID token, it will look similar to:

```json lines theme={null}
{
  "name": "jerrie@...",
  "picture": "https://s.gravatar.com/avatar/6222081fd7dcea7dfb193788d138c457?s=480&r=pg&d=https%3A%2F%2Fcdn.auth0.com%2Favatars%2Fje.png",
  "iss": "https://auth0pnp.auth0.com/",
  "sub": "auth0|581...",
  "aud": "xvt...",
  "exp": 1478113129,
  "iat": 1478077129
}
```

### Request user log in with GitHub

In addition to the usual user authentication, this example shows how to send users directly to a social identity provider, such as GitHub. For this example to work, you need to go to [Auth0 Dashboard > Authentication > Social](https://manage.auth0.com/#/connections/social) and configure the appropriate connection. Get the connection name from the **Settings** tab.

To send users directly to the GitHub login screen, you need to pass the `connection` parameter and set its value to the connection name (in this case, `github`) when authorizing the user:

<AuthCodeBlock />

Now, your ID Token will contain a `sub` claim with the user's unique ID returned from GitHub. When you decode the ID Token, it will look similar to:

```json lines theme={null}
{
  "name": "Jerrie Pelser",
  "nickname": "jerriep",
  "picture": "https://avatars.githubusercontent.com/u/1006420?v=3",
  "iss": "https://auth0pnp.auth0.com/",
  "sub": "github|100...",
  "aud": "xvt...",
  "exp": 1478114742,
  "iat": 1478078742
}
```

## Learn more

* [OAuth 2.0 Authorization Framework](/docs/authenticate/protocols/oauth)
* [OpenID Connect Protocol](/docs/authenticate/protocols/openid-connect-protocol)
* [Tokens](/docs/secure/tokens)
* [Mitigate Replay Attacks When Using the Implicit Flow](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post/mitigate-replay-attacks-when-using-the-implicit-flow)
* [Register Single-Page Web Applications](/docs/get-started/auth0-overview/create-applications/single-page-web-apps)
* [Update Grant Types](/docs/get-started/applications/update-grant-types)


# Mitigate Replay Attacks When Using the Implicit Flow
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post/mitigate-replay-attacks-when-using-the-implicit-flow

Learn how to securely generate and validate a cryptographic nonce for use with the Implicit Flow with Form Post.

To mitigate replay attacks when using the [Implicit Flow with Form Post](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post), a <Tooltip href="/docs/glossary?term=nonce">nonce</Tooltip> must be sent on authentication requests [as required by the OpenID Connect (OIDC) specification](https://openid.net/specs/openid-connect-core-1_0.html#ImplicitAuthRequest).

The nonce is generated by the application, sent as a `nonce` query string parameter in the authentication request, and included in the <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip> response from Auth0. This allows applications to correlate the ID Token response from Auth0 with the initial authentication request.

To learn more about where to include the nonce, see [Add Login Using the Implicit Flow with Form Post](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post/add-login-using-the-implicit-flow-with-form-post).

<Callout icon="file-lines">
  [Auth0.js](/docs/libraries/auth0js) manages `state` and `nonce` parameters for you when using [cross-origin authentication](/docs/authenticate/login/cross-origin-authentication).
</Callout>

## Generate a cryptographically random nonce

One way to generate a cryptographically random nonce is to use a tool like [Nano ID](https://github.com/ai/nanoid) or similar. This does require you to bundle the tool with your JavaScript code, however. If that's not possible, you can take advantage of the fact that [modern browsers](http://caniuse.com/#feat=cryptography) can use the [Web Crypto API](https://www.w3.org/TR/WebCryptoAPI/) to generate cryptographically secure random strings for use as nonces.

```javascript lines theme={null}
function randomString(length) {
    var charset = '0123456789ABCDEFGHIJKLMNOPQRSTUVXYZabcdefghijklmnopqrstuvwxyz+/'
    result = ''

    while (length > 0) {
        var bytes = new Uint8Array(16);
        var random = window.crypto.getRandomValues(bytes);

        random.forEach(function(c) {
            if (length == 0) {
                return;
            }
            if (c < charset.length) {
                result += charset[c];
                length--;
            }
        });
    }
    return result;
}
```

## Persist nonces across requests

The generated nonce must be persisted in your web application using any of the following methods:

* `HttpOnly` <Tooltip href="/docs/glossary?term=session+cookie">session cookie</Tooltip>
* HTML5 local storage value

For example:

```js lines theme={null}
window.localStorage.setItem('nonce', randomString(16));
```

## Validate ID token

Once Auth0 responds with an [ID Token](/docs/secure/tokens/id-tokens), this token must be [validated and decoded](/docs/secure/tokens/id-tokens/validate-id-tokens) as usual.
Its `nonce` claim must contain the exact same value that was sent in the request.
If not, authentication should be rejected by the application.

```javascript lines theme={null}
var jwt = '...'; // validated and decoded ID Token body
if (jwt.nonce === window.localStorage.getItem('nonce')) {
    // Nonce is OK
} else {
    // Nonce is not OK! Token replay attack might be underway
}
```

## Learn more

* [Implicit Flow with Form Post](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post)
* [Add Login Using the Implicit Flow with Form Post](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post/add-login-using-the-implicit-flow-with-form-post)
* [Implicit Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-implicit-flow)


# Resource Owner Password Flow
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow

Learn how the Resource Owner Password flow works and why you should use it for highly-trusted applications.

<Warning>
  Because the Resource Owner Password (ROP) Flow involves the application handling the user's password, it must not be used by third-party clients.
</Warning>

Though we do not recommend it, highly-trusted applications can use the <Tooltip href="/docs/glossary?term=Resource+Owner">Resource Owner</Tooltip> Password Flow (defined in [OAuth 2.0 RFC 6749, section 4.3](https://tools.ietf.org/html/rfc6749#section-4.3) and sometimes called Resource Owner Password Grant or ROPG), which requests that users provide credentials (username/email/phone and password), typically using an interactive form. Because credentials are sent to the backend and can be stored for future use before being exchanged for an <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, it is imperative that the application is absolutely trusted with this information.

Even if this condition is met, the Resource Owner Password Flow should only be used when redirect-based flows (like the [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow)) cannot be used.

## How it works

<Frame>
  <img alt="Diagram - Resource Owner Password Flow" />
</Frame>

1. The user clicks **Login** within the application and enters their credentials.
2. Your application forwards the user's credentials to your Auth0 Authorization Server ([`/oauth/token` endpoint](https://auth0.com/docs/api/authentication#resource-owner-password)).
3. Your Auth0 Authorization Server validates the credentials.
4. Your Auth0 Authorization Server responds with an Access Token (and optionally, a Refresh Token).
5. Your application can use the Access Token to call an API to access information about the user.
6. The API responds with requested data.

## How to implement it

The easiest way to implement the Resource Owner Password Flow is to follow our tutorial to use our API endpoints to [Call Your API Using the Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow/call-your-api-using-resource-owner-password-flow).

## Realm support

Auth0 provides an extension grant that offers similar functionality to the Resource Owner Password grant, but allows you to keep separate user directories (which map to separate connections) and specify which one to use during the flow.

For example, let's say you want to present a dropdown on your application's login user interface that allows users to choose their user type: `Employees` or `Customers`. In this case, you would configure `Employees` and `Customers` as realms (and set up a corresponding connection for each), which allows employee and customer credentials to be kept in separate user directories. When you request a token, you will submit the realm value along with the user's credentials and the submitted realm will be used to verify the password.

To learn more about implementing this extension grant, read [Call Your API Using Resource Owner Password Flow: Configure Realm Support](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow/call-your-api-using-resource-owner-password-flow).

## Rules

Rules will run for the Resource Owner Password Flow (including the Realm extension grant). However, redirect rules won't work. If you try to perform a redirect by specifying `context.redirect` in your rule, the authentication flow will return an error. To learn more about rules, read [Auth0 Rules](/docs/customize/rules). To learn more about redirect rules, read [Redirect Users from Within Rules](/docs/customize/rules/redirect-users).

## MFA support

If you need to use the Resource Owner Password Flow, but require stronger authentication, you can add <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA). To learn how, read [Authenticate Using the Resource Owner Password Flow with MFA](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa).

## Attack protection

When using the Resource Owner Password Flow with <Tooltip href="/docs/glossary?term=brute-force+protection">brute-force protection</Tooltip>, some <Tooltip href="/docs/glossary?term=attack+protection">attack protection</Tooltip> features may fail. Some common issues, however, can be avoided. To learn more, read [Avoid Common Issues with Resource Owner Password Flow and Attack Protection](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow/avoid-common-issues-with-resource-owner-password-flow-and-attack-protection).

## Learn more

* [Auth0 Rules](/docs/customize/rules)
* [Auth0 Hooks](/docs/customize/hooks)
* [Tokens](/docs/secure/tokens)
* [Token Best Practices](/docs/secure/tokens/token-best-practices)
* [Which OAuth 2.0 Flow Should I Use?](/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use)


# Avoid Common Issues with Resource Owner Password Flow and Attack Protection
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow/avoid-common-issues-with-resource-owner-password-flow-and-attack-protection

Learn how to avoid common issues encountered when using the Resource Owner Password Flow to call server-side APIs with attack protection enabled.

<Warning>
  Because the Resource Owner Password (ROP) Flow involves the application handling the user's password, it must not be used by third-party clients.
</Warning>

Though we do not recommend it, highly-trusted applications can call server-side APIs using the [Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow) (sometimes called <Tooltip href="/docs/glossary?term=Resource+Owner">Resource Owner</Tooltip> Password Grant or ROPG), which requests that users provide credentials (username and password), typically using an interactive form. If [brute-force protection is enabled](/docs/secure/attack-protection/brute-force-protection), when Auth0 validates the credentials, we may also [check for attacks](/docs/secure/attack-protection) and perform appropriate actions if an attack is detected.

Unfortunately, when using this flow with <Tooltip href="/docs/glossary?term=brute-force+protection">brute-force protection</Tooltip>, some <Tooltip href="/docs/glossary?term=attack+protection">attack protection</Tooltip> features may fail. Some common issues, however, can be avoided.

## Attack protection and server-side APIs

Brute-force protection and <Tooltip href="/docs/glossary?term=suspicious+IP+throttling">suspicious IP throttling</Tooltip> rely on having the user's IP address. When calling an API from your server, Auth0 treats the IP address of your server as the IP address of the user and provides it as input to the brute-force protection and suspicious IP throttling functionality. This could potentially trigger false positives, causing attack protection to block users or trigger warnings for legitimate requests.

To avoid this, send the user's IP address to Auth0 along with their credentials, and configure your application to trust the IP address.

<Warning>
  Due to security considerations, you may only configure authenticated applications (such as those with authentication based on a client secret) this way. Authenticated applications must only be used from protected resources, which are typically server-side. Do not use them from native applications or Single-page applications (SPAs) because they are not capable of storing secrets.
</Warning>

## Configure your Application to trust the IP address

Register either a [regular web application](/docs/get-started/auth0-overview/create-applications/regular-web-apps) or a [machine-to-machine application](/docs/get-started/auth0-overview/create-applications/machine-to-machine-apps). While configuring the application:

1. Under **Credentials**, select an **Authentication Method** other than `None`.
2. Under **Settings > Advanced Settings**, locate the **OAuth** tab, and enable **Trust Token Endpoint IP Header**, which will set the `auth0-forwarded-for` header as a trusted source of the user's IP address for brute-force protection. This setting will not be available for non-authenticated applications.

## Send the user's IP address from your server

1. When you request tokens using the [Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow/call-your-api-using-resource-owner-password-flow), include an `auth0-forwarded-for` header that contains the value of the user's IP address. Be sure that the IP address you provide really belongs to your user.

   <Warning>
     Trusting headers like the `auth0-forwarded-for` (or, in general, data from applications) as sources for the user's IP address can be risky. Because this header is easy to spoof and makes it possible to bypass attack protection validation, only do this if you know you can trust that header.
   </Warning>
2. Specify AllowLists of IPs to be ignored when triggering brute-force protection and suspicious IP throttling.

<Card title="Allow listing with brute-force protection and suspicious IP throttling">
  If your authenticated application is configured to send the `auth0-forwarded-for` header:

  * Only the IP address contained in the `auth0-forwarded-for` header is checked against the brute-force protection and suspicious IP throttling AllowLists.
  * The proxy IP address is ignored by brute-force protection and suspicious IP throttling, so doesn't need to be added to the AllowLists.
  * If specific clients that use the proxy should not be subject to brute-force protection or suspicious IP throttling, add them to the AllowLists.

  The `auth0-forwarded-for` header will only be accepted for authenticated calls with the Client Secret. If your application is not authenticated or is not configured to send the `auth0-forwarded-for` header:

  * The originating IP address of each request is checked against the brute-force protection and suspicious IP throttling AllowLists.
  * If you AllowList the IP proxy, all traffic passing through the proxy will be exempt from brute-force protection and suspicious IP throttling. This is probably not what you want.
</Card>

### Example

<AuthCodeBlock />

## Handle Breached Password Detection responses

If you’ve enabled [Breached Password Detection](/docs/secure/attack-protection/breached-password-detection) for your tenant, you need to configure your application to handle responses from the [Auth0 Authentication API](https://auth0.com/docs/api/authentication) accordingly.

For example, if you send a password using the ROP flow, and Auth0 detects that it’s been compromised, the Authentication API returns a response with the HTTP `401 Unauthorized` status code and the following body:

```json lines theme={null}
{
    "error": "password_leaked",
    "error_description": "This login attempt has been blocked because the password you're using was previously disclosed through a data breach (not in this application). Please check your email for more information."
}
```

Your application should handle this error, render a message to the user, and [trigger an interactive password reset flow](/docs/authenticate/database-connections/password-change#authentication-api).

## Validate with logs

If your settings are working correctly, you will see the following in the logs:

```bash lines theme={null}
type:  sepft
...
ip:  <ip from auth0-forwarded-for header>
client_ip:  <ip of actual client/proxy>
...
```

## Learn more

* [Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow)
* [Call Your API Using Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow/call-your-api-using-resource-owner-password-flow)
* [Attack Protection](/docs/secure/attack-protection)


# Call Your API Using Resource Owner Password Flow
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow/call-your-api-using-resource-owner-password-flow

Learn how to call your own API from highly-trusted applications using the Resource Owner Password Flow.

<Callout icon="file-lines">
  This tutorial will help you call your own API using the Resource Owner Password Flow. If you want to learn how the flow works and why you should use it, see [Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow).
</Callout>

<Warning>
  Because the Resource Owner Password (ROP) Flow involves the application handling the user's password, it must not be used by third-party clients.
</Warning>

Auth0 makes it easy for your app to implement the <Tooltip href="/docs/glossary?term=Resource+Owner">Resource Owner</Tooltip> Password Flow (sometimes called Resource Owner Password Grant or ROPG) using the [Authentication API](https://auth0.com/docs/api/authentication). Keep reading to learn how to call our API directly.

## Prerequisites

**Before beginning this tutorial:**

* [Register your Application with Auth0](/docs/get-started/auth0-overview/create-applications/regular-web-apps).

  * Select an **Application Type** of **Regular Web Apps**.
  * Add an **Allowed Callback URL** of `{https://yourApp/callback}`. This field cannot be undefined or an error message will be returned.
  * Make sure your Application's **Grant Types** include **Password**. To learn how, read [Update Grant Types](/docs/get-started/applications/update-grant-types).
  * If you want your Application to be able to use Refresh Tokens, make sure the Application's **Grant Types** include **Refresh Token**. To learn how, read [Update Grant Types](/docs/get-started/applications/update-grant-types). To learn more about Refresh Tokens, read [Refresh Tokens](/docs/secure/tokens/refresh-tokens).
* [Register your API with Auth0](/docs/get-started/auth0-overview/set-up-apis)

  * If you want your API to receive Refresh Tokens to allow it to obtain new tokens when the previous ones expire, enable **Allow Offline Access**.
* Set up a connection

  * Make sure your connection is capable of authenticating users by username and password (for example, [database connections](/docs/get-started/applications/set-up-database-connections), or AD/LDAP, ADFS, or Azure Active Directory [enterprise connections](/docs/authenticate/identity-providers/enterprise-identity-providers)).
* Update or disable any [rules](/docs/customize/rules), so they only impact specific connections. If you get an `access_denied` error while testing the Password Owner Resource Grant, this could be due to an access control rule.

## Steps

1. [Configure tenant](#configure-tenant):Set the tenant's default connection.
2. [Request tokens](#request-tokens):
   Exchange your authorization code for tokens.
3. [Call API](#call-api):
   Use the retrieved Access Token to call your API.
4. [Refresh tokens](#refresh-tokens):
   Use a Refresh Token to request new tokens when the existing ones expire.

Optional: [Explore sample use cases](#sample-use-cases)

Optional: [Configure realm support](#configure-realm-support)

Optional: [Configure MFA](#configure-mfa)

Optional: [Configure attack protection](#configure-anomaly-detection)

### Configure tenant

The Resource Owner Password Flow relies on a connection that is capable of authenticating users by username and password, so you must set the default connection for the tenant.

1. Go to [Auth0 Dashboard > Tenant Settings](https://manage.auth0.com/#/tenant), and scroll down to locate the **Default Directory** setting.
2. Enter the name of the connection you would like to use. Make sure it is capable of authenticating users by username and password.

### Request tokens

To call your API, you must first get the user's credentials, typically through an interactive form. Once your application has the credentials, you must exchange them for tokens. To do so, you must `POST` to the [token URL](https://auth0.com/docs/api/authentication#resource-owner-password).

#### Example POST to token URL

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=password \
    --data 'username={username}' \
    --data 'password={password}' \
    --data 'audience={yourApiIdentifier}' \
    --data scope=read:sample \
    --data 'client_id={yourClientId}' \
    --data 'client_secret={yourClientSecret}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=password&username=%7Busername%7D&password=%7Bpassword%7D&audience=%7ByourApiIdentifier%7D&scope=read%3Asample&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=password&username=%7Busername%7D&password=%7Bpassword%7D&audience=%7ByourApiIdentifier%7D&scope=read%3Asample&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D")

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

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=password&username=%7Busername%7D&password=%7Bpassword%7D&audience=%7ByourApiIdentifier%7D&scope=read%3Asample&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'password',
      username: '{username}',
      password: '{password}',
      audience: '{yourApiIdentifier}',
      scope: 'read:sample',
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=password" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&username={username}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&password={password}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&audience={yourApiIdentifier}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&scope=read:sample" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_secret={yourClientSecret}" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=password&username=%7Busername%7D&password=%7Bpassword%7D&audience=%7ByourApiIdentifier%7D&scope=read%3Asample&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=password&username=%7Busername%7D&password=%7Bpassword%7D&audience=%7ByourApiIdentifier%7D&scope=read%3Asample&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=password&username=%7Busername%7D&password=%7Bpassword%7D&audience=%7ByourApiIdentifier%7D&scope=read%3Asample&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/x-www-form-urlencoded"]

  let postData = NSMutableData(data: "grant_type=password".data(using: String.Encoding.utf8)!)
  postData.append("&username={username}".data(using: String.Encoding.utf8)!)
  postData.append("&password={password}".data(using: String.Encoding.utf8)!)
  postData.append("&audience={yourApiIdentifier}".data(using: String.Encoding.utf8)!)
  postData.append("&scope=read:sample".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&client_secret={yourClientSecret}".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

##### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td>Set this to <code>password</code>.</td>
    </tr>

    <tr>
      <td><code>username</code></td>
      <td>The username entered by the user.</td>
    </tr>

    <tr>
      <td><code>password</code></td>
      <td>The password entered by the user.</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Your application's Client ID. You can find this value in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>.</td>
    </tr>

    <tr>
      <td><code>client\_assertion</code></td>
      <td>A JWT containing a signed assertion with your application credentials. Required when Private Key JWT is your application authentication method.</td>
    </tr>

    <tr>
      <td><code>client\_assertion\_type</code></td>
      <td>The value is <code>urn:ietf:params:oauth:client-assertion-type:jwt-bearer</code>. Required when Private Key JWT is the application authentication method.</td>
    </tr>

    <tr>
      <td><code>client\_secret</code></td>
      <td>Your application's Client Secret. Required when Client Secret is the application authentication method. <a href="https://manage.auth0.com/#/applications/{yourClientId}/settings">Application Settings</a> is <code>Post</code> or <code>Basic</code>. If your application is not highly trusted (for example, a SPA), then do not set this parameter.</td>
    </tr>

    <tr>
      <td><code>audience</code></td>
      <td>The audience for the token, which is your API. You can find this in the <strong>Identifier</strong> field on your <a href="https://manage.auth0.com/#/apis">API's settings tab</a>.</td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td>Specifies the <a href="/docs/get-started/apis/scopes">scopes</a> for which you want to request authorization, which dictate which claims (or user attributes) you want returned. These must be separated by a space. You can request any of the <a href="https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims">standard OpenID Connect (OIDC) scopes</a> about users, such as <code>profile</code> or <code>email</code>, <a href="/docs/secure/tokens/json-web-tokens/json-web-token-claims#custom-claims">custom claims</a> conforming to a <a href="/docs/secure/tokens/json-web-tokens/create-custom-claims">namespaced format</a>, or any scopes supported by the target API (e.g., <code>read:contacts</code>). Include <code>offline\_access</code> to get a <Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip> (make sure that the <strong>Allow Offline Access</strong> field is enabled in the <a href="https://manage.auth0.com/#/applications">Application Settings</a>).</td>
    </tr>
  </tbody>
</table>

#### Response

If all goes well, you'll receive an `HTTP 200` response with a payload containing `access_token`, `refresh_token`, `id_token`, `token_type`, and `expires_in` values:

```json lines theme={null}
{
  "access_token": "eyJz93a...k4laUWw",
  "refresh_token": "GEbRxBN...edjnXbL",
  "id_token": "eyJ0XAi...4faeEoQ",
  "token_type": "Bearer",
  "expires_in": 36000
}
```

<Warning>
  Validate your tokens before saving them. To learn how, read [Validate ID Tokens](/docs/secure/tokens/id-tokens/validate-id-tokens) and [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens).
</Warning>

<Warning>
  Refresh tokens must be stored securely since they allow a user to remain authenticated essentially forever.
</Warning>

<Card title="Resource Owner Password flow and standard scopes">
  Because providing a password gives full access, any password-based exchange gives access to all scopes. For example, if you include no [API scopes](/docs/get-started/apis/scopes/api-scopes) in the request, all API scopes will be included in the Access Token. Similarly, if you include only the `openid` scope in the request, all `openid` standard [OpenID Connect scopes](/docs/get-started/apis/scopes/openid-connect-scopes) will be returned. In these cases, the `scope` parameter will be included in the response and will list the issued scopes.
</Card>

<Card title="Get user information without an ID Token">
  If you need the user's information, include the `openid` scope in your request. If the API uses `RS256` as the [signing algorithm](/docs/get-started/applications/signing-algorithms), the Access Token will include `/userinfo` as a valid audience, which means you can use it to invoke the [/userinfo endpoint](https://auth0.com/docs/api/authentication#get-user-info) and retrieve the user's claims.
</Card>

### Call API

To call your API, the application must pass the retrieved <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> as a Bearer token in the Authorization header of your HTTP request.

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request GET \
    --url https://myapi.com/api \
    --header 'authorization: Bearer {accessToken}' \
    --header 'content-type: application/json'
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://myapi.com/api");
  var request = new RestRequest(Method.GET);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer {accessToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines expandable theme={null}
  package main

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

  func main() {

  	url := "https://myapi.com/api"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("content-type", "application/json")
  	req.Header.Add("authorization", "Bearer {accessToken}")

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

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

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

  }
  ```

  ```java Java lines theme={null}
  HttpResponse response = Unirest.get("https://myapi.com/api")
    .header("content-type", "application/json")
    .header("authorization", "Bearer {accessToken}")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://myapi.com/api',
    headers: {'content-type': 'application/json', authorization: 'Bearer {accessToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C lines theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer {accessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://myapi.com/api"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP lines expandable theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://myapi.com/api",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {accessToken}",
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("myapi.com")

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer {accessToken}"
      }

  conn.request("GET", "/api", headers=headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://myapi.com/api")

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

  request = Net::HTTP::Get.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer {accessToken}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift lines theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer {accessToken}"
  ]

  let request = NSMutableURLRequest(url: NSURL(string: "https://myapi.com/api")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

### Refresh tokens

You have already received a [refresh token](/docs/secure/tokens/refresh-tokens) if you've been following this tutorial and completed the following:

* configured your API to allow offline access
* included the `offline_access` scope when you initiated the authentication request through the [authorize endpoint](https://auth0.com/docs/api/authentication/reference#authorize-application).

You can use the <Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip> to get a new access token. Usually, a user will need a new access token only after the previous one expires or when gaining access to a new resource for the first time. It's bad practice to call the endpoint to get a new access token every time you call an API, and Auth0 maintains rate limits that will throttle the amount of requests to the endpoint that can be executed using the same token from the same IP.

To refresh your token, make a `POST` request to the `/oauth/token` endpoint in the Authentication API, using `grant_type=refresh_token`.

#### Example POST to token URL

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=refresh_token \
    --data 'client_id={yourClientId}' \
    --data 'refresh_token={yourRefreshToken}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D")

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

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'refresh_token',
      client_id: '{yourClientId}',
      refresh_token: '{yourRefreshToken}'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=refresh_token" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&refresh_token={yourRefreshToken}" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/x-www-form-urlencoded"]

  let postData = NSMutableData(data: "grant_type=refresh_token".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&refresh_token={yourRefreshToken}".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

##### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td>Set this to <code>refresh\_token</code>.</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Your application's Client ID. You can find this value in your <a href="https://manage.auth0.com/#/Applications/{yourClientId}/settings">Application Settings</a>.</td>
    </tr>

    <tr>
      <td><code>refresh\_token</code></td>
      <td>The refresh token to use.</td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td>(optional) A space-delimited list of requested scope permissions. If not sent, the original scopes will be used; otherwise you can request a reduced set of scopes. Note that this must be URL encoded.</td>
    </tr>
  </tbody>
</table>

#### Response

If all goes well, you'll receive an `HTTP 200` response with a payload containing a new `access_token`, its lifetime in seconds (`expires_in`), granted `scope` values, and `token_type`.

```json lines theme={null}
{
  "access_token": "eyJ...MoQ",
  "expires_in": 86400,
  "scope": "openid offline_access",
  "token_type": "Bearer"
}
```

<Warning>
  Validate your tokens before saving them. To learn how, read [Validate ID Tokens](/docs/secure/tokens/id-tokens/validate-id-tokens) and [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens).
</Warning>

### Sample use cases

#### Customize tokens

You can use Actions to change the returned scopes of Access Tokens and/or add claims to Access and <Tooltip href="/docs/glossary?term=ID+Tokens">ID Tokens</Tooltip>. (To learn more about Actions, read [Auth0 Actions](/docs/customize/actions).) To do so, add the following Action, which will run after the user authenticates:

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  // Add custom claims to Access Token and ID Token
  api.accessToken.setCustomClaim('https://foo/bar', 'value');
  api.idToken.setCustomClaim('https://fiz/baz', 'some other value');

  // Modify the scope of the Access Token
  api.accessToken.addScope('foo');
  api.accessToken.addScope('bar');
};
```

Scopes will be available in the token after the Action has run.

<Warning>
  Auth0 returns profile information in a structured claim format as defined by the [OpenID Connect (OIDC) specification](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). This means that custom claims added to ID tokens or access tokens must [conform to guidelines and restrictions](/docs/secure/tokens/json-web-tokens/create-custom-claims) to avoid possible collisions.
</Warning>

### Configure realm support

Auth0 provides an extension grant that offers similar functionality to the Resource Owner Password grant, but allows you to keep separate user directories (which map to separate connections) and specify which one to use during the flow.

To use this variation, you must:

* Set the `grant_type` request parameter to `http://auth0.com/oauth/grant-type/password-realm`.
* Send an additional request parameter called `realm`, and set it to the name of the realm to which the user belongs. For example, if you have configured a database connection for internal employees named `employees`, and your user belongs to it, then set `realm` to `employees`.

<Card title="Connections as realms">
  Any connection that supports active authentication can be configured as a realm, including [database connections](/docs/get-started/applications/set-up-database-connections), [passwordless connections](/docs/authenticate/passwordless), and [AD/LDAP](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap), [ADFS](/docs/authenticate/identity-providers/enterprise-identity-providers/adfs), and [Azure Active Directory](/docs/authenticate/identity-providers/enterprise-identity-providers/azure-active-directory/v2) enterprise connections.
</Card>

### Configure MFA

If you need to use the Resource Owner Password Flow, but require stronger authentication, you can add <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA). To learn how, read [Authenticate Using the Resource Owner Password Flow with MFA](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa).

### Configure attack protection

When using the Resource Owner Password Flow with <Tooltip href="/docs/glossary?term=brute-force+protection">brute-force protection</Tooltip>, some <Tooltip href="/docs/glossary?term=attack+protection">attack protection</Tooltip> features may fail. Some common issues, however, can be avoided. To learn more, read [Avoid Common Issues with Resource Owner Password Flow and Attack Protection](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow/avoid-common-issues-with-resource-owner-password-flow-and-attack-protection).

## Learn more

* [OAuth 2.0 Authorization Framework](/docs/authenticate/protocols/oauth)
* [OpenID Connect Protocol](/docs/authenticate/protocols/openid-connect-protocol)
* [Tokens](/docs/secure/tokens)


# Custom Token Exchange Flow
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/token-exchange-flow

Learn about the custom token exchange flow.

Custom Token Exchange allows applications to exchange an existing security token—referred to as the `subject_token`—for Auth0 access, ID, and refresh tokens by calling the `/oauth/token` endpoint, in accordance with [RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693).

## How it works

The Custom Token Exchange flow is governed by a single, dedicated [Custom Token Exchange Action](/docs/customize/actions/explore-triggers/signup-and-login-triggers/custom-token-exchange-trigger), which is uniquely selected based on the incoming `subject_token_type` parameter, as configured in a [Custom Token Exchange Profile](/docs/authenticate/custom-token-exchange/configure-custom-token-exchange).

<Frame>
  <img alt="" />
</Frame>

As a prerequisite for the flow, you must define a [Custom Token Exchange Profile](/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#create-custom-token-exchange-profile) that maps a specific `subject_token_type` to the Action that will handle the requests.

When the Custom Token Exchange flow is triggered:

1. The application sends a `POST` request to the `/oauth/token` endpoint with the security token to be exchanged (the `subject_token`) and its corresponding `subject_token_type`.
2. Auth0 validates the client request and credentials.
3. The associated Custom Token Exchange Action is executed. Your custom code must decode and validate the `subject_token`, enforce any necessary authorization policies, and set the user for the transaction to approve the exchange.
4. The rest of the standard Auth0 pipeline executes to generate an Auth0 access token and optionally an ID token and refresh token for the set user.
5. The requesting application can then use these newly issued tokens to securely call APIs on behalf of the user that was set in the Action.

## Get started

To use Custom Token Exchange, you need to [create a Custom Token Exchange Profile](/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#create-custom-token-exchange-profile). The general workflow involves three main configuration steps followed by your API call:

1. [Create and deploy an Action](/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#create-action-for-the-profile) that will contain the logic to control the token exchange. In this Action, write the custom code logic to:
   * Securely decode and validate the incoming `subject_token`.
   * Perform any required authorization steps for the transaction.
   * Set the corresponding user for the transaction using the available methods in the [Custom Token Exchange Actions API Object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/custom-token-exchange-trigger/custom-token-exchange-api-object).
2. [Create the Custom Token Exchange Profile](/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#create-custom-token-exchange-profile) in your tenant. The profile establishes a one-to-one mapping between a specific `subject_token_type` you will use in your requests and the Action you just created.
3. [Enable Custom Token Exchange for your application](/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#enable-custom-token-exchange-for-your-application).

Once you’ve created the Custom Token Exchange Profile, you are ready to:

1. Call your API: You can now make a `POST` request to the `/oauth/token` endpoint with the necessary parameters, including the `subject_token` and the `subject_token_type` that corresponds to your configured profile. To learn more, read [Call your API using Custom Token Exchange](/docs/get-started/authentication-and-authorization-flow/token-exchange-flow/call-your-api-using-the-custom-token-exchange-flow).

## Learn more

* [Custom Token Exchange](/docs/authenticate/custom-token-exchange)
* [Example Use Cases](/docs/authenticate/custom-token-exchange/cte-example-use-cases)
* [Configure Custom Token Exchange](/docs/authenticate/custom-token-exchange/configure-custom-token-exchange)


# Call Your API Using the Custom Token Exchange Flow
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/token-exchange-flow/call-your-api-using-the-custom-token-exchange-flow

Learn how to call your API using the Custom Token Exchange Flow.

To use Custom Token Exchange, make a `POST` request to the `/oauth/token` endpoint with the following parameters:

<Callout icon="file-lines">
  Remember that `subject_tokens` used with Custom Token Exchange can be any token format or type, as long as your Action code can interpret them.
  Each `subject_token_type` maps to a Custom Token Exchange Profile and is associated with an Action that will be executed to control that transaction.
</Callout>

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td>For Custom Token Exchange, use <code>urn:ietf:params:oauth:grant-type:token-exchange</code>.</td>
    </tr>

    <tr>
      <td><code>subject\_token\_type</code></td>
      <td>The type of the subject token. For Custom Token Exchange, this can be any URI scoped under your own ownership, such as `http://acme.com/legacy-token` or <code>urn:acme:legacy-token</code>.<br /><br />The following namespaces are reserved and cannot be used:<ul><li>`http://auth0.com`</li><li>`https://auth0.com`</li><li>`http://okta.com`</li><li>`https://okta.com`</li><li><code>urn:ietf</code></li><li><code>urn:auth0</code></li><li><code>urn:okta</code></li></ul></td>
    </tr>

    <tr>
      <td><code>subject\_token</code></td>
      <td>The subject token, which your action should validate and use to identify the user.</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>The client ID of the application you are using for the Token Exchange. As for other grant types, you can also pass the client ID in the Authorization header using HTTP Basic Auth.</td>
    </tr>

    <tr>
      <td><code>client\_secret</code></td>
      <td>The client secret of the application you are using for the Token Exchange. As for other grant types, you can also pass the client secret in the Authorization header using HTTP Basic Auth.<br /><br />Other alternatives are also available as explained in <a href="https://auth0.com/docs/api/authentication#authentication-methods">Auth0 Authentication API reference docs</a>.<br /><br />Note Custom Token Exchange can be used by public Applications. Make sure to read <a href="#attack-protection">Attack Protection</a> in that case.</td>
    </tr>

    <tr>
      <td><code>audience</code></td>
      <td>The API identifier defined in Auth0. The default tenant audience will be used when not present, as configured in [Tenant Settings](/docs/get-started/tenant-settings).</td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td>(Optional) The OAuth2 scope parameter.</td>
    </tr>

    <tr>
      <td><code>organization</code></td>
      <td>(Optional) The organization identifier you want the request to be associated with. Alternatively, you can specify an organization name if [Use Organization Names in Authentication API](/docs/manage-users/organizations/configure-organizations/use-org-name-authentication-api) is allowed for your tenant. To learn more about how the request is processed, read about the [api.authentication.setOrganization() API method](/docs/customize/actions/explore-triggers/signup-and-login-triggers/custom-token-exchange-trigger/custom-token-exchange-api-object#api-authentication-setorganization-organization).</td>
    </tr>
  </tbody>
</table>

Other extension parameters are ignored, although they are included in the `event.request.body` in the corresponding Action.

## Sample request

```bash lines theme={null}
curl --location 'https://{yourDomain}/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode 'audience=https://api.acme.com' \
--data-urlencode 'scopes=openid offline_access acme-scope1 acme-scope2' \
--data-urlencode 'subject_token_type=urn:acme:external-idp-migration' \
--data-urlencode 'subject_token=t8e7S2D9trQm73e .... iqBR3GjxDtbDVjpfQU' \
--data-urlencode 'client_id=<YOUR_CLIENT_ID>' \
--data-urlencode 'client_secret=<YOUR_CLIENT_SECRET>'
--data-urlencode 'organization=periscope-acme'
```


# Which OAuth 2.0 Flow Should I Use?
Source: https://auth0.com/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use

Learn how to identify the proper OAuth 2.0 flow for your use case.

The [OAuth 2.0 Authorization Framework](/docs/authenticate/protocols/oauth) supports several different flows (or grants). <Tooltip href="/docs/glossary?term=Flow">Flow</Tooltip> are ways of retrieving an <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>. Deciding which one is suited for your use case depends mostly on your [application type](/docs/get-started/applications), but other parameters weigh in as well, like the level of trust for the client, or the experience you want your users to have.

## OAuth 2.0 terminology

* **<Tooltip href="/docs/glossary?term=Resource+Owner">Resource Owner</Tooltip>**: Entity that can grant access to a protected resource. Typically, this is the end-user.
* **Client**: Application requesting access to a protected resource on behalf of the Resource Owner.
* **<Tooltip href="/docs/glossary?term=Resource+Server">Resource Server</Tooltip>**: Server hosting the protected resources. This is the API you want to access.
* **<Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip>**: Server that authenticates the Resource Owner and issues Access Tokens after getting proper authorization. In this case, Auth0.
* **User Agent**: Agent used by the Resource Owner to interact with the Client (for example, a browser or a native application).

## Is the Client the Resource Owner?

The first decision point is about whether the party that requires access to resources is a machine. In the case of machine-to-machine authorization, the Client is also the Resource Owner, so no end-user authorization is needed. An example is a cron job that uses an API to import information to a database. In this example, the cron job is the Client and the Resource Owner since it holds the <Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip> and <Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip> and uses them to get an Access Token from the Authorization Server.

If this case matches your needs, then to learn how this flow works and how to implement it, see [Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow).

## Is the Client a web app executing on the server?

If the Client is a regular web app executing on a server, then the Authorization Code Flow is the flow you should use. Using this the Client can retrieve an Access Token and, optionally, a <Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip>. It's considered the safest choice since the Access Token is passed directly to the web server hosting the Client, without going through the user's web browser and risking exposure.

If this case matches your needs, then to learn how this flow works and how to implement it, see [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow).

## Is the Client absolutely trusted with user credentials?

This decision point may result in the Resource Owner Password Credentials Grant. In this flow, the end-user is asked to fill in credentials (identifier/password), typically using an interactive form. This information is sent to the backend and from there to Auth0. It is therefore imperative that the Client is absolutely trusted with this information.

This grant should only be used when redirect-based flows (like the [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow)) are not possible. If this is your case, then to learn about how this flow works and how to implement it, see [Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow).

## Is the Client a Single-Page App?

If the Client is a Single-Page App (SPA), an application running in a browser using a scripting language like JavaScript, there are two grant options: the Authorization Code Flow with Proof Key for Code Exchange (PKCE) and the Implicit Flow with Form Post. For most cases, we recommend using the Authorization Code Flow with PKCE because the Access Token is not exposed on the client side, and this flow can return [Refresh Tokens](/docs/secure/tokens/refresh-tokens).

To learn more about how this flow works and how to implement it, see [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce). The [Auth0 Single-Page App SDK](/docs/libraries/auth0-single-page-app-sdk) provides high-level API for implementing Authorization Code Flow with PKCE in SPAs.

If your SPA doesn't need an Access Token, you can use the Implicit Flow with Form Post. To learn more about how this flow works and how to implement it, see [Implicit Flow with Form Post](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post).

## Is the Client a Native/Mobile App?

If the Application is a native app, then use the **Authorization Code Flow with Proof Key for Code Exchange (PKCE)**.

To learn more about how this flow works and how to implement it, see [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce).

## I have an application that needs to talk to different resource servers

If a single application needs access tokens for different resource servers, then multiple calls to `/authorize` (that is, multiple executions of the same or different <Tooltip href="/docs/glossary?term=Authorization+Flow">Authorization Flow</Tooltip>) needs to be performed. Each authorization will use a different value for `audience`, which will result in a different access token at the end of the flow. For more information, see the [OAuth 2.0: Audience Information Specification](https://tools.ietf.org/html/draft-tschofenig-oauth-audience-00#section-3).

## Can I try the endpoints before I implement my application?

Sure! You can use our [Authentication API Debugger Extension](/docs/customize/extensions/authentication-api-debugger-extension). You can find detailed instructions per `/grant` endpoint at our [Authentication API Reference](https://auth0.com/docs/api/authentication).

* For the Authorize endpoint, go to [Authorize Application](https://auth0.com/docs/api/authentication#authorize-application) and read the "Test this endpoint" paragraph for the grant you want to test.
* For the <Tooltip href="/docs/glossary?term=Token+endpoint">Token endpoint</Tooltip>, go to [Get Token](https://auth0.com/docs/api/authentication#get-token) and read the "Test this endpoint" section for the grant you want to test.

## Does the Client Application need to challenge users for authentication without browser interaction?

<Callout icon="file-lines">
  Client-Initiated Backchannel Authentication is currently in Early Access. To enable CIBA, contact your Technical Account Manager.
</Callout>

Client-Initiated Backchannel Authentication (CIBA) is an <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Foundation standard for implementing an alternative authentication flow to [OpenID Connect](https://openid.net/developers/how-connect-works/). CIBA differs from the standard OpenID Connect flow in that:

* The client application initiates the authentication process on behalf of the end user.
* There's no need for a browser for user interaction.
* There's direct communication between the client application and the OpenID Provider.

CIBA is useful when the user can't trust the client application, the client application doesn't have a browser, or the user is not in front of the application that requires authentication. Here are some examples of where CIBA flows can be used:

* **User check-in at a retail sales terminal:** For click-collect scenarios, a user can authenticate at a public kiosk and confirm their presence.
* **Authenticating in a call center or at a clerk's desk:** A call center agent can initiate an authentication flow to authenticate a caller, typically using a custom mobile app on a smartphone.
* **Authenticating on a device with no input:** For example, a smart speaker (or another connected device) can use a backend service to contact the user for authentication, typically using a custom mobile app on a smartphone.

CIBA defines two devices:

* **Consumption device**: The device that helps the user consume a service.
* **Authentication device**: The device on which the user will authenticate and grant consent.

To learn more, read [Client-Initiated Backchannel Authentication Flow](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow).


# Manage Dashboard Access
Source: https://auth0.com/docs/get-started/manage-dashboard-access

Describes how to manage your team members to have access permissions on your Auth0 Dashboard.

As an Auth0 tenant administrator, you are responsible for all activities that occur under your Auth0 account and tenants including managing your tenant members. You can add, change, and remove tenant members (dashboard users) in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or from the [Auth0 Teams Dashboard](/docs/get-started/auth0-teams/tenant-member-management). Auth0 recommends that you periodically review the list of Auth0 Dashboard tenant members with access to your Auth0 tenant and make sure that:

* Each person has a legitimate need for tenant member access.
* Members are registered with a company account.
* Former employees no longer have access.
* There's more than one Dashboard admin.

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/get-started/manage-dashboard-access/feature-access-by-role">Dashboard Access by Role</a></td>
      <td>About tenant member roles and Auth0 Dashboard feature access.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/manage-dashboard-access/add-dashboard-users">Add Tenant Members</a></td>
      <td>How to add tenant members to access the Auth0 Dashboard.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/manage-dashboard-access/edit-dashboard-users">Edit Tenant Members</a></td>
      <td>How to edit tenant member roles.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/manage-dashboard-access/remove-dashboard-users">Remove Tenant Members</a></td>
      <td>How to revoke a tenant member's access to the Auth0 Dashboard.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/manage-dashboard-access/add-change-remove-mfa">Add Multi-factor Authentication (MFA) for Auth0 Dashboard Access</a></td>
      <td>How Auth0 Dashboard users can implement multi-factor authentication (MFA).</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/manage-dashboard-access/update-dashboard-user-email">Update Dashboard User Email Addresses</a></td>
      <td>How to update a tenant member's email address.</td>
    </tr>
  </tbody>
</table>

Here are some examples of users who may have special access requirements:

* Support specialists who need to troubleshoot login issues for your app end users.
* Support/IT specialists who need to assign roles and permissions to end users.
* Developers who need to troubleshoot their applications in production environments.
* Product managers who need to analyze their applications' configuration and usage.
* Developers who need to configure settings for their own applications.
* Support/IT specialists that need to create connections for their customers in a B2B use case.


# Multi-Factor Authentication for Dashboard Users
Source: https://auth0.com/docs/get-started/manage-dashboard-access/add-change-remove-mfa

Learn how Auth0 Dashboard users can implement multi-factor authentication (MFA).

<Tooltip href="/docs/glossary?term=Multi-factor+authentication">Multi-factor authentication</Tooltip> (MFA) adds an additional level of security to an Auth0 account. When users with MFA enabled log into the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, Auth0 prompts for their credentials plus an additional piece of identifying information. This ensures that only valid users can access their accounts, even if a <Tooltip href="/docs/glossary?term=bad+actor">bad actor</Tooltip> has compromised a username and password.

Any Dashboard user can self-enroll in MFA in [Your Profile](https://manage.auth0.com/#/profile). The MFA indicator in the [Auth0 Dashboard > Settings > Tenant Members](https://manage.auth0.com/#/tenant/admins) list identifies whether a user has enabled MFA for their account.

Auth0 supports these authentication factors for Dashboard users:

* **WebAuthn with FIDO security keys**: WebAuthn roaming authenticators are removable and cross-platform, like a Yubikey, and can be used on multiple devices. To authenticate with a roaming authenticator, users must connect the authenticator to their device (through USB, NFC, or Bluetooth) and provide proof of presence (by touching it, for example).
* **WebAuthn with device biometrics**: WebAuthn platform authenticators are attached to a device and work on that device only. Examples are the MacBook Touch Bar, Windows Hello, iOS Touch ID or Face ID, and Android fingerprint or face recognition. Because they work on the attached device only, a user must have at least one other factor enrolled in their profile before enrolling device biometrics.
* **Push notification via Guardian**: Sends push notifications to a user's pre-registered device, typically a mobile phone or tablet. The user can immediately allow or deny account access with a button press. The push factor is available with the Guardian mobile app for iOS and Android.
* **One-time passwords (OTP)**: Allows a user to use an authenticator app (such as Google Authenticator) on their personal device. The app generates an OTP that changes over time and can be entered as a second factor to validate the account.
* **SMS notification**: Sends a one-time code over SMS. Auth0 then prompts the user to enter this code before they can complete authentication. SMS as an MFA is available only on tenants attached to a subscription plan.

To learn how to enroll in Dashboard MFA, read [Add Multi-Factor Authentication for Auth0 Dashboard Access](/docs/get-started/manage-dashboard-access/add-change-remove-mfa/add-mfa).

<Callout icon="file-lines">
  Auth0 recommends WebAuthn factors as the most secure and usable authentication methods. To learn more, read [FIDO Authentication with WebAuthn](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn).
</Callout>

<Warning>
  Admins must enable at least one factor to use MFA. Auth0 highly recommends setting up multiple factors so you can still access your account if you lose your primary device.

  An ideal setup is to use three factors:

  1. WebAuthn, Guardian, or OTP as the primary method.
  2. One or more SMS numbers as a backup (available only on tenants attached to a subscription plan).
  3. A recovery code.

  If you can't provide your MFA token and you don’t have proper backup methods, your account may be irrecoverable.
</Warning>

## Learn more

* [Add Multi-Factor Authentication for Auth0 Dashboard Access](/docs/get-started/manage-dashboard-access/add-change-remove-mfa/add-mfa)
* [Remove or Change Dashboard Multi-Factor Authentication](/docs/get-started/manage-dashboard-access/add-change-remove-mfa/remove-or-change-dashboard-multi-factor-authentication)
* [Update Dashboard User Email Addresses](/docs/get-started/manage-dashboard-access/update-dashboard-user-email)
* [Reset Account Passwords](/docs/troubleshoot/customer-support/reset-account-passwords)
* [Troubleshoot Multi-Factor Authentication Issues](/docs/troubleshoot/authentication-issues/troubleshoot-mfa-issues)


# Add Multi-Factor Authentication for Auth0 Dashboard Access
Source: https://auth0.com/docs/get-started/manage-dashboard-access/add-change-remove-mfa/add-mfa

Describes how Auth0 Dashboard users can enroll in multi-factor authentication (MFA).

Each <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> user should self-enroll in <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA). You can enroll in most factors in [Your Profile](https://manage.auth0.com/#/profile). Device biometrics, however, require progressive enrollment.

<Callout icon="file-lines">
  Auth0 recommends WebAuthn factors as the most secure and usable authentication methods. To learn more, read [FIDO Authentication with WebAuthn](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn).
</Callout>

<Warning>
  Admins must enable at least one factor to use MFA. Auth0 highly recommends setting up multiple factors so you can still access your account if you lose your primary device.

  An ideal setup is to use three factors:

  1. WebAuthn, Guardian, or OTP as the primary method.
  2. One or more SMS numbers as a backup (available only on tenants attached to a subscription plan).
  3. A recovery code.

  If you can't provide your MFA token and you don’t have proper backup methods, your account may be irrecoverable.
</Warning>

## Add MFA

To self-enroll for MFA, each Dashboard user must follow these steps:

1. Click on your username in the top right corner of the Dashboard and click [Your Profile](https://manage.auth0.com/#/profile).
2. Find the supported method you want and click **+ ADD** in that row.

   <Frame>
     <img alt="Dashboard - Profile - Multi-Factor - Authentication" />
   </Frame>
3. Follow the on-screen instructions to complete the enrollment.

## Device biometrics

WebAuthn with device biometrics is the only method that you can't add on the Account Settings page. Instead, Auth0 progressively enrolls all of your WebAuthn-capable devices. Auth0 prompts you to enroll those devices after you enroll any other MFA method. These prompts recur each time you log in to Auth0 Dashboard.

<Frame>
  <img alt="undefined" />
</Frame>

As part of the enrollment, Auth0 prompts you to name your devices. This makes it easy to manage them from the Account Settings page.

Browsers with Javascript disabled or without WebAuthn platform authenticator support can't enroll or authenticate with device biometrics. The latest versions of popular browsers and operating systems provide support for WebAuthn with Security Keys. To learn more, read the [browser support section on webauthn.me](https://webauthn.me/browser-support).

## Recovery codes

Immediately after successfully enabling two-factor authentication, Auth0 prompts you to copy a recovery code. If you lose access to all your enrolled factors, you can use this recovery code to log in to your account. Auth0 recommends copying and printing recovery codes or storing them in a safe place, such as a password manager.

If you lose the recovery codes or just want to generate new ones, you can do so from [Your Profile](https://manage.auth0.com/#/profile).

## Log in to the Dashboard with MFA enabled

Logging in with MFA enabled is only slightly different than a normal login. When you enter admin account credentials, a second prompt appears, depending on which type of MFA factors you’ve enabled.

If a user loses access to a primary factor, they can click on **Select Another Method** and try with any of the other factors, including recovery codes. This is why it's so important to enroll in multiple methods to prevent being locked out of your account.

After you successfully add your second authentication factor and you log in from a new device that supports WebAuthn, you see a prompt to "Log in Faster on this Device." This lets you use that device for multi-factor authentication the next time.

## Learn more

* [Multi-Factor Authentication for Dashboard Users](/docs/get-started/manage-dashboard-access/add-change-remove-mfa)
* [Remove or Change Dashboard Multi-Factor Authentication](/docs/get-started/manage-dashboard-access/add-change-remove-mfa/remove-or-change-dashboard-multi-factor-authentication)
* [Troubleshoot Multi-Factor Authentication Issues](/docs/troubleshoot/authentication-issues/troubleshoot-mfa-issues)


# Remove or Change Dashboard Multi-Factor Authentication
Source: https://auth0.com/docs/get-started/manage-dashboard-access/add-change-remove-mfa/remove-or-change-dashboard-multi-factor-authentication

Provides steps for when you change authentication factors or lose/retire a device

Dashboard users can remove or change <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA) factors that are no longer available or wanted. To learn more about MFA for Dashboard users, read [Multi-Factor Authentication for Dashboard Users](/docs/get-started/manage-dashboard-access/add-change-remove-mfa).

<Callout icon="file-lines">
  Auth0 recommends WebAuthn factors as the most secure and usable authentication methods. To learn more, read [FIDO Authentication with WebAuthn](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn).
</Callout>

<Warning>
  Admins must enable at least one factor to use MFA. Auth0 highly recommends setting up multiple factors so you can still access your account if you lose your primary device.

  An ideal setup is to use three factors:

  1. WebAuthn, Guardian, or OTP as the primary method.
  2. One or more SMS numbers as a backup (available only on tenants attached to a subscription plan).
  3. A recovery code.

  If you can't provide your MFA token and you don’t have proper backup methods, your account may be irrecoverable.
</Warning>

## Remove or change an MFA factor from the Dashboard

<Callout icon="file-lines">
  You can’t add a device biometrics factor (such as the MacBook Touch Bar, Windows Hello, iOS Touch ID or Face ID, or Android fingerprint or face recognition) from the Dashboard. To learn how to add a device biometrics authentication factor, read [Add Multi-factor Authentication for Dashboard Users.](/docs/get-started/manage-dashboard-access/add-change-remove-mfa/add-mfa)
</Callout>

Dashboard users who can log in with their current MFA factors can follow these steps:

1. In the top right corner of the Dashboard, click your user name and click [Your profile](https://manage.auth0.com/#/profile).

   <Frame>
     <img alt="Dashboard - Profile - Multi-Factor - Authentication" />
   </Frame>
2. Find the new authentication factor you want to use and click **+ ADD** in that row. Follow the on-screen instructions to complete the enrollment.
3. Still in [Your profile](https://manage.auth0.com/#/profile), find the authentication factor you want to stop using and click **REMOVE**.
4. Click **Yes** to confirm the removal.
5. Auth0 prompts you to authenticate with your current (old) factors. After a successful authentication, Auth0 removes the factor.

## Remove or change a lost MFA factor

Dashboard users who **can’t** log in with their current MFA factors can follow these steps:

1. Attempt to log in to the Dashboard. Auth0 prompts you to authenticate with your current factors.
2. When Auth0 asks for the device or credentials you’ve lost, click on **Try another method**.
3. In the Other Methods box, click a different method to authenticate.
4. Log in to access the Dashboard.
5. In the top right corner of the Dashboard, click your user name and click [Your profile](https://manage.auth0.com/#/profile).

   <Frame>
     <img alt="Dashboard - Profile - Multi-Factor - Authentication" />
   </Frame>
6. Find the authentication method you can no longer use and click **REMOVE**.
7. Click **Yes** to confirm the removal.
8. Auth0 prompts you to authenticate using your current factors again. Repeat steps 2-4 to verify your identity. Auth0 removes the lost factor.

## Get help from Auth0 support

If you are locked out and don’t have access to any of your enabled MFA factors, there is no guarantee that you can regain access to your account. Another administrator must file an Auth0 support ticket on your behalf. In some cases, Auth0 can verify the request and proceed with an MFA reset. However, we may not be able to confirm account ownership. This is why it’s so important to enable multiple and varied factors.

Auth0 support does not reset **end-user** accounts. You are responsible for accounts that access your applications and APIs. To learn about end-user accounts, read [Manage Users](/docs/manage-users).

## Learn more

* [Multi-Factor Authentication for Dashboard Users](/docs/get-started/manage-dashboard-access/add-change-remove-mfa)
* [Add Multi-Factor Authentication for Auth0 Dashboard Access](/docs/get-started/manage-dashboard-access/add-change-remove-mfa/add-mfa)
* [Troubleshoot Multi-Factor Authentication Issues](/docs/troubleshoot/authentication-issues/troubleshoot-mfa-issues)


# Add Tenant Members
Source: https://auth0.com/docs/get-started/manage-dashboard-access/add-dashboard-users

Learn how to add tenant members to access the Auth0 Dashboard.

If you are a tenant administrator, you can add colleagues to the tenant and assign them a specific role to allow them access to the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> features they need.

<Warning>
  If your tenant administrator account authenticates with username and password, you must verify your email address before you can invite other members.
</Warning>

<Callout icon="file-lines">
  If Teams is provisioned for your enterprise account, manage your tenant members via Auth0 Teams. To learn more, read [Team Member Management](/docs/get-started/auth0-teams/team-member-management).
</Callout>

When you add new tenant members, you can assign roles that allow them access without putting production applications and sensitive information at risk. You can assign a user more than one role and the permissions will be combined. For further protection, users can turn on [multi-factor authentication](/docs/get-started/manage-dashboard-access/add-change-remove-mfa) (<Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip>). To learn more about which Dashboard features are accessible with each role, read [Dashboard Access by Role](/docs/get-started/manage-dashboard-access/feature-access-by-role).

<table>
  <thead>
    <tr>
      <th><strong>Role</strong></th>
      <th><strong>Permissions</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Admin</strong></td>
      <td>Read and write access to all resources in the Auth0 Dashboard, including extensions.</td>
    </tr>

    <tr>
      <td><strong>Editor - Connections</strong></td>
      <td>Read, write, and create access to all types of connections.</td>
    </tr>

    <tr>
      <td><strong>Editor - Key Management</strong></td>
      <td>Create and manage cryptographic keys.</td>
    </tr>

    <tr>
      <td><strong>Editor - Organizations</strong></td>
      <td>Read, write, and create access to Organization configuration. Read-only access to Users, Roles, and Connections.</td>
    </tr>

    <tr>
      <td><strong>Editor - Specific Apps</strong></td>
      <td>Read and write access to specific applications only.</td>
    </tr>

    <tr>
      <td><strong>Editor - Users</strong></td>
      <td>User management operations (create, delete, block, unblock, reset MFA, reset password, update metadata, assign roles, etc.) and access to logs.</td>
    </tr>

    <tr>
      <td><strong>Viewer - Users</strong></td>
      <td>Read-only access to users and user-related logs.</td>
    </tr>

    <tr>
      <td><strong>Viewer - Config Settings</strong></td>
      <td>Read-only access to all configuration settings (applications, APIs, rules, security settings, etc.) except for sensitive information such as secrets, billing, users, and logs.</td>
    </tr>

    <tr>
      <td><strong>Support Access - Deprecated</strong></td>
      <td>Access to tickets (submit, view, and update) and aggregated metrics.</td>
    </tr>

    <tr>
      <td><strong>Elevated Support Access</strong></td>
      <td>Read, write, and create access to <strong>all</strong> support tickets created by <strong>all users</strong> on a tenant (Subscripton Tickets in Auth0 Support Center). Access to aggregated metrics.</td>
    </tr>
  </tbody>
</table>

<Card title="Availability varies by Auth0 plan">
  Both your specific login implementation and your Auth0 plan or custom agreement affect whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

1. Go to [Dashboard > Settings > Tenant Members](https://manage.auth0.com/#/tenant/admins).
2. Click **Add Member**.
3. On the **Add New Tenant Member** screen, enter the user's email address and select the roles you would like to assign to them.
4. Click **Invite**.
   Auth0 will send an email to the user with a link for them to click to accept the invitation. Before the user accepts the invitation, they will appear in the Invitations list as pending. If you click the `...` you will see **Remove invitation** or **Copy invitation link**.

<Card title="Missing tenants">
  Users can create Auth0 accounts in different ways. For example, they can sign up with a social provider (e.g., Google, GitHub), then sign up again using their email address. If your tenant members cannot see all of their tenants after logging in, check to see if they have multiple Auth0 accounts. You can view the signup method used by the Dashboard tenant member by going to [Dashboard > Tenant Settings > Tenant Members](https://manage.auth0.com/#/tenant/admins).
</Card>

When the invited user clicks the link to accept the invitation, they will be asked to log in with the invited email address. They can then choose whether to log in with a social provider or to log in with their email address and password. If they choose to log in with their email address and password, they must have already created an account with Auth0, or they will need to sign up first and then accept the invitation again.

## Learn more

* [Dashboard Access by Role](/docs/get-started/manage-dashboard-access/feature-access-by-role)
* [Edit Tenant Members](/docs/get-started/manage-dashboard-access/edit-dashboard-users)
* [Remove Tenant Members](/docs/get-started/manage-dashboard-access/remove-dashboard-users)
* [Troubleshoot Role-Based Access Control and Authorization](/docs/troubleshoot/authentication-issues/troubleshoot-rbac-authorization)
* [Troubleshoot Multi-Factor Authentication Issues](/docs/troubleshoot/authentication-issues/troubleshoot-mfa-issues)
* [Troubleshoot Authentication Issues](/docs/troubleshoot/authentication-issues)


# Configure Single Sign-on for Auth0 Dashboard
Source: https://auth0.com/docs/get-started/manage-dashboard-access/configure-single-sign-on-for-auth0-dashboard

Learn how to configure single sign-on (SSO) for the Auth0 Dashboard.

<Card title="Before you start">
  * Subscribe to an Enterprise plan. For more information, read [Manage Subscriptions](/docs/troubleshoot/customer-support/manage-subscriptions).
  * Determine whether you're using Public Cloud or Private Cloud. For Private Cloud-related prerequisites to these instructions, see [Deploy Private Cloud](/docs/deploy-monitor/deploy-private-cloud).
</Card>

You can configure Auth0 to allow [Tenant Members](/docs/get-started/manage-dashboard-access) to use your own [Enterprise identity provider](/docs/authenticate/identity-providers/enterprise-identity-providers) (<Tooltip href="/docs/glossary?term=IdP">IdP</Tooltip>) to authenticate to the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> through <Tooltip href="/docs/glossary?term=single+sign-on">single sign-on</Tooltip> (SSO).

## How it works

Configuring SSO for the Dashboard requires you to work with Auth0 Support to add an Enterprise connection to the root tenant authority (RTA), which manages the available authentication methods a Tenant Member can use to log in to the Dashboard.

Adding this SSO connection does not restrict Tenant Members from logging in using the existing authentication methods (such as email/password, [LinkedIn](https://marketplace.auth0.com/integrations/linkedin-social-connection), [Microsoft](https://marketplace.auth0.com/integrations/microsoft-account-social-connection), [GitHub](https://marketplace.auth0.com/integrations/github-social-connection), or [Google](https://marketplace.auth0.com/integrations/google-social-connection)).

Configuring SSO for the Dashboard also enables SSO for all public Auth0 sites, such as:

* Auth0 website ([https://auth0.com](https://auth0.com))
* Auth0 Community ([https://community.auth0.com](https://community.auth0.com))
* Auth0 Docs ([https://www.auth0.com/docs](https://www.auth0.com/docs))
* Auth0 Support Center ([https://support.auth0.com](https://support.auth0.com))

### User experience

When an authorized user goes to log in to the Dashboard, they enter their email address for a registered domain (for example, `user@example.com`) into the Auth0 <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> page, and then are redirected to your IdP to complete authentication.

### Limitations

Before you decide to configure SSO for the Dashboard, please consider the restrictions:

* SSO cannot be limited to specific tenants.
* SSO does not support IdP-initiated authentication flows.
* Tenant Member invitations cannot be automated or sent in bulk with the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.
* Tenant Member access cannot be managed by your IdP’s group memberships.
* <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> cannot be enforced for all members of a tenant.

### Considerations

#### Full directory access to Dashboard

When you add your IdP as an available connection for Tenant Members to log in on, all of the users in your IdP’s directory are able to access the Dashboard, but only the Tenant Members who have been invited to a given tenant are able to access that tenant.

When users attempt to access a tenant in the Dashboard without an invitation, the system denies the operation. If users do not belong to any tenants, the system prompts them to [complete their user profile](#complete-user-profiling) and create a new trial tenant. Creating a new trial tenant does not associate it with your Enterprise plan.

#### Residual Tenant Member identities

If a Tenant Member was invited (and had access) to a tenant in the Dashboard using a different identity than the one created on the new connection, they will still—technically—be able to use that identity to access the tenant.

You’ll have to decide if you want to remove their old identity, or keep it as a potential alternative authentication method.

## Configure SSO for the Dashboard

Configuring SSO for the Dashboard requires a series of steps shared between you and Auth0 Support.

### Share IdP configuration data

[Open a ticket with Auth0 Support](/docs/troubleshoot/customer-support/open-and-manage-support-tickets) to share your IdP’s configuration data so they can set up the SSO configuration. Include the following information when you submit your ticket:

* Email domain(s) you’d like to associate with the SSO configuration
* Name of the IdP
* Authentication protocol
* Additional IdP-specific information

There are additional configuration steps required depending on the IdP and authentication protocol you’d like to use:

#### ADFS (SAML)

1. [Create a Relying Party Trust](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust#to-create-a-claims-aware-relying-party-trust-manually) with the following properties:

   <table>
     <thead>
       <tr>
         <th><strong>Property</strong></th>
         <th><strong>Values</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>Entity ID</td>
         <td>`urn:auth0:auth0:{assignedConnectionName}`</td>
       </tr>

       <tr>
         <td>Callback endpoint</td>
         <td>`https://auth0.auth0.com/login/callback`</td>
       </tr>
     </tbody>
   </table>
2. [Add a claim description](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/operations/add-a-claim-description) for each of the following claims:

   <table>
     <thead>
       <tr>
         <th><strong>Claim</strong></th>
         <th><strong>Claim identifier</strong></th>
         <th><strong>Value</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>Name Identifier</td>
         <td><code>[http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier)</code></td>
         <td><code>E-Mail-Addresses</code> or <code>User-Principal-Name</code></td>
       </tr>

       <tr>
         <td>Email Address</td>
         <td><code>[http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress)</code></td>
         <td>N/A</td>
       </tr>

       <tr>
         <td>Name</td>
         <td><code>[http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name)</code></td>
         <td>N/A</td>
       </tr>
     </tbody>
   </table>
3. Enable the SAML 2.0 endpoint.
4. Provide Auth0 Support with the following information:

   * Login endpoint (for example, `https://{yourServer}/adfs/ls`)
   * Signing certificate, or the SAML metadata XML file

#### Azure AD (OIDC)

1. [Create a new App registration](https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app).
2. Set the **Redirect URI** type to Web, and the value to `https://auth0.auth0.com/login/callback`.
3. Select **Register**.
4. [Enable the Implicit Grant](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-implicit-grant-flow#send-the-sign-in-request) for the ID Token.
5. [Add the email claim](https://learn.microsoft.com/en-us/azure/active-directory/develop/active-directory-optional-claims) to the ID Token.
6. Provide Auth0 Support with the following information:

   * The application (client) ID
   * The OIDC metadata endpoint (for example, `https://login. microsoftonline.com/{yourAzureAdTenantId}/v2.0/.well-known/openid-configuration`)

#### Azure AD (SAML)

1. [Create a new Enterprise Application](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal).

2. Set up [single sign-on for SAML](https://learn.microsoft.com/en-us/azure/active-directory/develop/single-sign-on-saml-protocol) with the following properties (you may need to use placeholder values until Auth0 Support can provide you with the SSO connection’s name):

   <table>
     <thead>
       <tr>
         <th><strong>Property</strong></th>
         <th><strong>Value</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>Identifier (Entity ID)</td>
         <td>`urn:auth0:auth0:{assignedConnectionName}`</td>
       </tr>

       <tr>
         <td>Reply (ACS) URL</td>
         <td>`https://auth0.auth0.com/login/callback`</td>
       </tr>

       <tr>
         <td>Sign-on URL</td>
         <td>`https://manage.auth0.com/login?connection={assignedConnectionName}`</td>
       </tr>
     </tbody>
   </table>

3. Leave the **Attributes & Claims** section - including `email`, `Unique User Identifier`, and optionally `name -` unchanged from Azure's suggestions.

4. Provide Auth0 Support with the SAML metadata XML data. You can either:

   * Share the App Federation Metadata URL (for example, `https://login.microsoftonline.com/{azureAdTenantId}/federationmetadata /2007-06/federationmetadata.xml?appid={appId}`).
   * Download the Federation Metadata XML document and attach it to the ticket.

#### Google (SAML)

Auth0 supports configuring SSO for the Dashboard with a Google <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> IdP, but it’s recommended that you direct users to log in with the existing Google authentication method.

When a user logs in to the Google SAML IdP, Auth0 creates a new user identity for them (separate from their existing Google user identity), which may be confusing.

If you’d like to set up SSO for the Dashboard with a Google SAML IdP, read [Generic IdP (SAML)](#generic-idp-saml) for instructions.

#### Okta (SAML)

1. Create a SAML application with the following properties (you may need to use placeholder values until Auth0 Support can provide you with the SSO connection’s name):

   <table>
     <thead>
       <tr>
         <th><strong>Property</strong></th>
         <th><strong>Value</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>Entity ID</td>
         <td>`urn:auth0:auth0:{assignedConnectionName}`</td>
       </tr>

       <tr>
         <td>Callback endpoint (ACS URL)</td>
         <td>`https://auth0.auth0.com/login/callback`</td>
       </tr>
     </tbody>
   </table>

2. Set the **Name Identifier** to send the email address of the user.

3. Provide Auth0 Support with the SAML metadata XML data. You can either:

   * Share the SAML metadata XML URL:

     1. Locate the **SAML Signing Certificates** section.
     2. Select the **Actions** menu.
     3. Select **View IdP metadata**, and then select **Copy Link Address**. It will have this format: `https://{org}.okta.com/app/{appId}/sso/saml/metadata`.
   * Download the SAML metadata XML file and attach it to the ticket.

##### IdP-initiated authentication flows

SSO for the Dashboard does not support IdP-initiated authentication flows. If you want users to be able to select a chiclet to log in to the Dashboard you need to:

1. Hide the SAML app from users.
2. [Create a Bookmark App](https://help.okta.com/en/prod/Content/Topics/Apps/Apps_Bookmark_App.htm) that points to `https://manage.auth0.com/login?connection={assignedConnectionName}`. This is the application that users will be able to select to log in.

Make sure you enable both the SAML application and the Bookmark App for the same set of users that can use the application.

#### OneLogin (SAML)

1. Create a SAML Test Connector (SP) with the following properties (you may need to use placeholder values until Auth0 Support can provide you with the SSO connection’s name):

   <table>
     <thead>
       <tr>
         <th><strong>Property</strong></th>
         <th><strong>Value</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>Entity ID</td>
         <td>`urn:auth0:auth0:{assignedConnectionName}`</td>
       </tr>

       <tr>
         <td>Callback endpoint (ACS URL)</td>
         <td>`https://auth0.auth0.com/login/callback`</td>
       </tr>

       <tr>
         <td>Login URL</td>
         <td>`https://manage.auth0.com/login?connection={assignedConnectionName}`</td>
       </tr>
     </tbody>
   </table>
2. Provide Auth0 Support with the SAML metadata XML file.

#### Generic IdP (OIDC)

1. Register an application (client) with the IdP with the following properties:

   <table>
     <thead>
       <tr>
         <th><strong>Property</strong></th>
         <th><strong>Value</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>Callback URL</td>
         <td>`https://auth0.auth0.com/login/callback`</td>
       </tr>
     </tbody>
   </table>

2. [Add the email claim](/docs/secure/tokens/json-web-tokens/create-custom-claims) to the ID Token.

3. Provide Auth0 Support with the:

   * Application (client) ID
   * Issuer URL or OIDC metadata endpoint (for example, `https://{idpDomain}/[...]/.well-known/openid-configuration`)

<Callout icon="file-lines">
  Auth0 Support will use [Implicit Mode with Form Post flow](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post), if available. If your IdP does not support this, then you’ll need to provide them with your application’s client secret.
</Callout>

#### Generic IdP (SAML)

1. Auth0 Support will provide you with the SSO connection's name.
2. Create a SAML application with the following properties:

   <table>
     <thead>
       <tr>
         <th><strong>Property</strong></th>
         <th><strong>Value</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>Entity ID</td>
         <td>`urn:auth0:auth0:{assignedConnectionName}`</td>
       </tr>

       <tr>
         <td>Callback endpoint</td>
         <td>`https://auth0.auth0.com/login/callback`</td>
       </tr>
     </tbody>
   </table>
3. Ensure that the SAML assertions contain the following claims:

   <table>
     <thead>
       <tr>
         <th><strong>Claim</strong></th>
         <th><strong>Claim identifier</strong></th>
         <th><strong>Value</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>Name Identifier</td>
         <td><code>[http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier)</code></td>
         <td><code>upn</code> or <code>emailaddress</code></td>
       </tr>

       <tr>
         <td>Email Address</td>
         <td><code>[http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress)</code></td>
         <td>N/A</td>
       </tr>

       <tr>
         <td>Name</td>
         <td><code>[http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name)</code></td>
         <td>N/AA</td>
       </tr>
     </tbody>
   </table>
4. Provide Auth0 Support with either the:

   * Sign-in URL and signing certificate
   * SAML metadata XML file

### Set up SSO connection

The Auth0 Support team uses the configuration data you provide to complete initial setup of the SSO connection.

Home Realm Discovery (HRD) is not configured during initial setup.

### Test SSO connection

When initial setup of the SSO connection is complete, the Auth0 Support team has you test the SSO connection to ensure the configuration data was correct, and that Tenant Members can authenticate on the SSO connection in the manner you’re looking for.

The Auth0 Support team provides you with a direct login URL you can use to prompt authentication for the new SSO connection. For example:

`https://manage.auth0.com/login?connection={assignedConnectionName}`

## Enforce SSO with Auth0 Teams

If you use Auth0 Teams with your Enterprise tenant, you can enforce SSO authentication for the tenants that belong to the Teams account. To learn more about tenant administration and management, read [Auth0 Teams](/docs/get-started/auth0-teams).

1. Open a new browser and enter your Teams account and identifier: `https://accounts.auth0.com/teams/{team-identifier}.`

   <Callout icon="file-lines">
     You can get the Teams identifier in the URL or the Teams [**Settings**](https://accounts.auth0.com/teams/#/settings).
   </Callout>

2. Navigate to the **Security** page.

3. [Configure the Security Policies](/docs/get-started/auth0-teams/configure-security-policies) by selecting **Enforce Single Sign On**.

### Enable Home Realm Discovery (optional)

If you’re using Universal Login or Classic Login, you can request to enable HRD, so the login page recognizes the domain of the email address the Tenant Member enters, and then directs them to the new SSO connection.

#### When to enable HRD

If HRD is enabled, Tenant Members that previously used an email/password identity (with an email matching the configured HRD domain) won’t be able to log in through the login page, and HRD is only compatible with email identifiers.

Due to this change in behavior, request to enable HRD only after at least some of the current Tenant Members are aware of the change, and that they know that they’ll either:

* Receive an invitation to join the tenants under the new identity
* Need to re-invite themselves with the new identity

#### How to bypass HRD

If a Tenant Member needs to log in with their email/password identity, you can provide them with a direct login URL:

`https://manage.auth0.com/login?connection=auth0`

This URL bypasses HRD, and allows them to log in with their email/password identity.

#### Example of HRD login behavior

Here’s an example of a list of Tenant Members:

<table>
  <thead>
    <tr>
      <th><strong>Tenant</strong></th>
      <th><strong>Tenant Member</strong></th>
      <th><strong>Connection</strong></th>
      <th><strong>Affected?</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>fabrikam\@us</code></td>
      <td>`user1@example.com`</td>
      <td>email/password</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td><code>fabrikam\@us</code></td>
      <td>`user1@gmail.com`</td>
      <td>google-oauth2</td>
      <td>No</td>
    </tr>

    <tr>
      <td><code>fabrikam\@us</code></td>
      <td>`user2@example.com`</td>
      <td>github</td>
      <td>No</td>
    </tr>

    <tr>
      <td><code>fabrikam\@us</code></td>
      <td>`user3@acme.com`</td>
      <td>email/password</td>
      <td>No</td>
    </tr>

    <tr>
      <td><code>fabrikam\@us</code></td>
      <td>`user4@example.com`</td>
      <td>email/password</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td><code>fabrikam-dev\@us</code></td>
      <td>`user5@example.com`</td>
      <td>email/password</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td><code>fabrikam-dev\@us</code></td>
      <td>`user1@example.com`</td>
      <td>email/password</td>
      <td>Yes</td>
    </tr>
  </tbody>
</table>

If we associate the example.com domain to the new connection, the Tenant Members `user1@gmail.com`, `user2@example.com`, and `user3@acme.com` are able to log in as they have previously, because they use either a social provider, or an email with a unassociated domain.

Alternatively, the Tenant Members `user1@example.com`, `user4@example.com`, and `user5@example.com` are not able to log in as they have previously, because their emails are associated with the domain configured for HRD.

## Migrate existing Tenant Members

The process to migrate existing Tenant Members depends on whether you have enabled HRD.

### How to migrate with HRD disabled

To migrate Tenant Members with HRD disabled, you need to share the direct login URL for the new SSO connection:

`https://manage.auth0.com/login?connection={assignedConnectionName}`

1. [Create a new Tenant Member invitation](/docs/get-started/manage-dashboard-access/add-dashboard-users) for the Tenant Member.
2. Instruct the Tenant Member to:

   1. Log in on the new SSO connection by using the direct login URL before accepting the invitation.

      <Callout icon="file-lines">
        If this is the first time they are logging in on the new SSO connection, they may see a profile enrichment page (at [https://auth.com/profile](https://auth.com/profile)). Do not fill out any fields or select **Next**. Instead, follow the next step.
      </Callout>

   2. Copy and paste the invitation URL they received in the invitation email into the same browser where they logged in on the new SSO connection. Users should not select **Create Account**.

   3. Accept the invitation.

   4. If the user has invitations for other tenants, they can use them at this time.

### How to migrate with HRD enabled

To migrate Tenant members with HRD enabled, you need to follow steps similar to [adding Tenant Members](/docs/get-started/manage-dashboard-access/add-dashboard-users):

1. [Create a new Tenant Member invitation](/docs/get-started/manage-dashboard-access/add-dashboard-users) for the Tenant Member.
2. Instruct the Tenant Member to:

   1. Log out of the Dashboard (if they had previously logged in with an old identity).

      <Callout icon="file-lines">
        If this is the first invitation they are accepting, they may see a “Create a new tenant” or “Create a new account” page. Do not select **Next**. Instead, follow the next step.
      </Callout>

   2. Open the invitation link in the invitation email they received.

   3. Log in on the new connection.

   4. Accept the invitation.


# Edit Tenant Members
Source: https://auth0.com/docs/get-started/manage-dashboard-access/edit-dashboard-users

Learn how to edit Auth0 Dashboard user roles for your Auth0 tenant.

If you are a tenant administrator, you can change a user's assigned role(s). The changes take effect after users refresh their Dashboard.

You can assign a user more than one role and the permissions will be combined. You must have already added the tenant member.

1. Go to [Dashboard > Settings > Tenant Members](https://manage.auth0.com/#/tenant/admins).
2. Click **...** to the right of a user name or email and click **Edit Roles**.
   If you don't see that option, it means that the user has not yet accepted their invitation.
3. Select additional roles or remove roles.
4. Click **Save**.

<Callout icon="file-lines">
  The user's permissions will be visible when they refresh their Dashboard. If the user does not refresh, they may encounter errors indicating that they do not have access to a specific area. If one of those errors occurs, the user will have to log out and log in again.
</Callout>

**Password resets**: To learn more, read [Reset Auth0 Account Password](/docs/troubleshoot/customer-support/reset-account-passwords) if you or one of your Dashboard users is having issues logging in.

**Email address invalid**: To learn more, read [Update Dashboard User Email Addresses](/docs/get-started/manage-dashboard-access/update-dashboard-user-email) to view email addresses for your tenant members and update if necessary.

## Learn more

* [Dashboard Access by Role](/docs/get-started/manage-dashboard-access/feature-access-by-role)
* [Add Tenant Members](/docs/get-started/manage-dashboard-access/add-dashboard-users)
* [Remove Tenant Members](/docs/get-started/manage-dashboard-access/remove-dashboard-users)
* [Troubleshoot Role-Based Access Control and Authorization](/docs/troubleshoot/authentication-issues/troubleshoot-rbac-authorization)


# Dashboard Access by Role
Source: https://auth0.com/docs/get-started/manage-dashboard-access/feature-access-by-role

Describes each tenant member role and provides details about what Auth0 Dashboard features they have access to.

As a tenant administrator, you can assign roles to your colleagues that grant them limited access to the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. This allows tenant members to complete their jobs without putting production applications at risk, while also complying with the principle of least privilege.

<Callout icon="file-lines">
  Every role receives access to [Support Center](https://support.auth0.com/).
</Callout>

## Dashboard roles

You can assign the following roles for Auth0 Dashboard access:

<table>
  <thead>
    <tr>
      <th><strong>Role</strong></th>
      <th><strong>Permissions</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Admin</strong></td>
      <td>Read and write access to all resources in the Auth0 Dashboard, including extensions.</td>
    </tr>

    <tr>
      <td><strong>Editor - Connections</strong></td>
      <td>Read, write, and create access to all types of connections.</td>
    </tr>

    <tr>
      <td><strong>Editor - Key Management</strong></td>
      <td>Create and manage cryptographic keys.</td>
    </tr>

    <tr>
      <td><strong>Editor - Organizations</strong></td>
      <td>Read, write, and create access to Organization configuration. Read-only access to Users, Roles, and Connections.</td>
    </tr>

    <tr>
      <td><strong>Editor - Specific Apps</strong></td>
      <td>Read and write access to specific applications only.</td>
    </tr>

    <tr>
      <td><strong>Editor - Users</strong></td>
      <td>User management operations (create, delete, block, unblock, reset MFA, reset password, update metadata, assign roles, etc.) and access to logs.</td>
    </tr>

    <tr>
      <td><strong>Viewer - Users</strong></td>
      <td>Read-only access to users and user-related logs.</td>
    </tr>

    <tr>
      <td><strong>Viewer - Config Settings</strong></td>
      <td>Read-only access to all configuration settings (applications, APIs, rules, security settings, etc.) except for sensitive information such as secrets, billing, users, and logs.</td>
    </tr>

    <tr>
      <td><strong>Support Access - Deprecated</strong></td>
      <td>Access to tickets (submit, view, and update) and aggregated metrics.</td>
    </tr>

    <tr>
      <td><strong>Elevated Support Access</strong></td>
      <td>Read, write, and create access to <strong>all</strong> support tickets created by <strong>all users</strong> on a tenant (Subscripton Tickets in Auth0 Support Center). Access to aggregated metrics.</td>
    </tr>
  </tbody>
</table>

<Card title="Availability varies by Auth0 plan">
  Your Auth0 plan or custom agreement affects the availability of this feature. To learn more, read [Auth0's Pricing Page](https://auth0.com/pricing).
</Card>

Limited-access roles restrict a tenant member's Dashboard experience to only the sections and actions necessary for their job.

The feature permissions associated with each role are outlined below. If a specific permission is not listed for a role, tenant members given that role will not have access to that area of the Auth0 Dashboard.

<AccordionGroup>
  <Accordion title="Admin">
    Admin users have read/write access to all areas of the Auth0 Dashboard, including extensions.
  </Accordion>

  <Accordion title="Editor - Connections">
    <table>
      <thead>
        <tr>
          <th><strong>Dashboard Section</strong></th>
          <th><strong>Subsection (if applicable)</strong></th>
          <th><strong>Read/Write Access</strong></th>
          <th><strong>Read-Only Access</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Authentication</td>
          <td>Database</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td />

          <td>Social</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td />

          <td>Enterprise</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td />

          <td>Passwordless</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td>Marketplace</td>

          <td />

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td>Get Support</td>
          <td>Support Tickets - Create</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td />

          <td>Usage Reports</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td />

          <td>Compliance</td>
          <td>✅</td>

          <td />
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Editor - Key Management">
    <table>
      <thead>
        <tr>
          <th><strong>Dashboard Section</strong></th>
          <th><strong>Subsection (if applicable)</strong></th>
          <th><strong>Read/Write Access</strong></th>
          <th><strong>Read-Only Access</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Settings</td>
          <td>General</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td />

          <td>Encryption Keys</td>
          <td>✅</td>

          <td />
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Editor - Organizations">
    <table>
      <thead>
        <tr>
          <th><strong>Dashboard Section</strong></th>
          <th><strong>Subsection (if applicable)</strong></th>
          <th><strong>Read/Write Access</strong></th>
          <th><strong>Read-Only Access</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Authentication</td>
          <td>Database</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td />

          <td>Social</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td />

          <td>Enterprise</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td />

          <td>Passwordless</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td>Organizations</td>
          <td>List</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td />

          <td>Overview</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td />

          <td>Members</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td />

          <td>Invitations</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td />

          <td>Connections</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td>User Management</td>
          <td>Users</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td />

          <td>Roles</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td>Marketplace</td>

          <td />

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td>Get Support</td>
          <td>Support Tickets - Create</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td />

          <td>Usage Reports</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td />

          <td>Compliance</td>
          <td>✅</td>

          <td />
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Editor - Specific Apps">
    <table>
      <thead>
        <tr>
          <th><strong>Dashboard Section</strong></th>
          <th><strong>Subsection (if applicable)</strong></th>
          <th><strong>Read/Write Access</strong></th>
          <th><strong>Read-Only Access</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Applications</td>
          <td>Applications</td>
          <td>   ✅ +</td>

          <td />
        </tr>

        <tr>
          <td />

          <td>SSO Integrations</td>
          <td>   ✅ +</td>

          <td />
        </tr>

        <tr>
          <td>Marketplace</td>

          <td />

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td>Get Support</td>
          <td>Support Tickets - Create</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td />

          <td>Usage Reports</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td />

          <td>Compliance</td>
          <td>✅</td>

          <td />
        </tr>
      </tbody>
    </table>

    * Update-only access for specific applications. Users cannot create new applications.
  </Accordion>

  <Accordion title="Editor - Users">
    <table>
      <thead>
        <tr>
          <th><strong>Dashboard Section</strong></th>
          <th><strong>Subsection (if applicable)</strong></th>
          <th><strong>Read/Write Access</strong></th>
          <th><strong>Read-Only Access</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Organizations</td>
          <td>List</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td />

          <td>Members</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td />

          <td>Invitations</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td>User Management</td>
          <td>Users</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td />

          <td>Roles</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td>Monitoring</td>
          <td>Logs</td>

          <td />

          <td>   ✅ +</td>
        </tr>

        <tr>
          <td>Marketplace</td>

          <td />

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td>Get Support</td>
          <td>Support Tickets - Create</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td />

          <td>Usage Reports</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td />

          <td>Compliance</td>
          <td>✅</td>

          <td />
        </tr>
      </tbody>
    </table>

    * Access to user events only.
  </Accordion>

  <Accordion title="Viewer - Users">
    <table>
      <thead>
        <tr>
          <th><strong>Dashboard Section</strong></th>
          <th><strong>Subsection (if applicable)</strong></th>
          <th><strong>Read/Write Access</strong></th>
          <th><strong>Read-Only Access</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Organizations</td>
          <td>List</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td />

          <td>Members</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td>User Management</td>
          <td>Users</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td />

          <td>Roles</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td>Monitoring</td>
          <td>Logs</td>

          <td />

          <td>   ✅ +</td>
        </tr>

        <tr>
          <td>Marketplace</td>

          <td />

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td>Get Support</td>
          <td>Support Tickets - Create</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td />

          <td>Usage Reports</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td />

          <td>Compliance</td>
          <td>✅</td>

          <td />
        </tr>
      </tbody>
    </table>

    * Access to user events only.
  </Accordion>

  <Accordion title="Viewer - Config">
    <table>
      <thead>
        <tr>
          <th><strong>Dashboard Section</strong></th>
          <th><strong>Subsection (if applicable)</strong></th>
          <th><strong>Read/Write Access</strong></th>
          <th><strong>Read-Only Access</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Applications</td>
          <td>Applications</td>

          <td />

          <td>   ✅ +</td>
        </tr>

        <tr>
          <td />

          <td>APIs</td>

          <td />

          <td>   ✅ +</td>
        </tr>

        <tr>
          <td />

          <td>SSO Integrations</td>

          <td />

          <td>   ✅ +</td>
        </tr>

        <tr>
          <td>Authentication</td>
          <td>Database</td>

          <td />

          <td>   ✅ +</td>
        </tr>

        <tr>
          <td />

          <td>Social</td>

          <td />

          <td>   ✅ +</td>
        </tr>

        <tr>
          <td />

          <td>Enterprise</td>

          <td />

          <td>   ✅ +</td>
        </tr>

        <tr>
          <td />

          <td>Passwordless</td>

          <td />

          <td>   ✅ +</td>
        </tr>

        <tr>
          <td>Organizations</td>
          <td>List</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td />

          <td>Overview</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td />

          <td>Connections</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td>User Management</td>
          <td>Roles</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td>Branding</td>
          <td>Universal Login</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td />

          <td>Custom Domains</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td />

          <td>Email Templates</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td />

          <td>Email Providers</td>

          <td />

          <td>   ✅ +</td>
        </tr>

        <tr>
          <td>Security</td>
          <td>Attack Protection</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td />

          <td>Multi-factor Auth</td>

          <td />

          <td>   ✅ +</td>
        </tr>

        <tr>
          <td>Actions</td>
          <td>Flows</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td />

          <td>Library</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td>Auth Pipeline</td>
          <td>Rules</td>

          <td />

          <td>   ✅ +</td>
        </tr>

        <tr>
          <td>Marketplace</td>

          <td />

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td>Settings</td>
          <td>General</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td />

          <td>Advanced</td>

          <td />

          <td>✅</td>
        </tr>

        <tr>
          <td>Get Support</td>
          <td>Support Tickets - Create</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td />

          <td>Usage Reports</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td />

          <td>Compliance</td>
          <td>✅</td>

          <td />
        </tr>
      </tbody>
    </table>

    * Excludes access to secrets.
  </Accordion>

  <Accordion title="Elevated Support Access">
    <table>
      <thead>
        <tr>
          <th><strong>Dashboard Section</strong></th>
          <th><strong>Subsection (if applicable)</strong></th>
          <th><strong>Read/Write Access</strong></th>
          <th><strong>Read-Only Access</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Activity</td>
          <td>Stats</td>
          <td>    ✅ +</td>

          <td />
        </tr>

        <tr>
          <td>Get Support</td>
          <td>Support Tickets - Create</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td />

          <td>Support Tickets - Manage All Users Tickets</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td />

          <td>Usage Reports</td>
          <td>✅</td>

          <td />
        </tr>

        <tr>
          <td />

          <td>Compliance</td>
          <td>✅</td>

          <td />
        </tr>
      </tbody>
    </table>

    * Access to metrics only.
  </Accordion>
</AccordionGroup>

## Log events available to user roles

Logs can contain sensitive data, such as secrets, PII, etc. It is important not to disclose sensitive data to users whose role does not require that information. However, the **Editor - Users** or **Viewer - Users** roles need to have some access to logs to identity user issues. For example, finding out if the user signed up correctly, if the user was blocked, etc.

We allow the **Editor - Users** and **Viewer - Users** with access to a limited set of log types, that are connected to user events. The log events in the list provide the necessary information about user actions but do not disclose sensitive information about other parts of the tenant configuration. To learn more, read [Log Event Type Codes](/docs/deploy-monitor/logs/log-event-type-codes).

```text lines expandable theme={null}
cls
cs
f
fce
fcoa
fcp
fcpn
fcpr
fcu
fdeac
fdeaz
fdecc
fdu
feacft
feccft
fede
fens
feoobft
feotpft
fepft
fepotpft
fercft
fi
flo
fn
fp
fs
fsa
fu
fui
fv
fvr
gd_auth_failed
gd_auth_rejected
gd_auth_succeed
gd_enrollment_complete
gd_otp_rate_limit_exceed
gd_recovery_failed
gd_recovery_rate_limit_exceed
gd_recovery_succeed
gd_send_email
gd_send_email_failure
gd_send_pn
gd_send_pn_failure
gd_send_sms
gd_send_sms_failure
gd_send_voice
gd_send_voice_failure
gd_start_auth
gd_start_enroll
gd_tenant_update
gd_unenroll
gd_update_device_account
limit_mu
limit_wc
mfar
pwd_leak
s
sce
scoa
scp
scpn
scpr
scu
sdu
seacft
sede
sens
seoobft
seotpft
sepft
sercft
si
slo
ss
ssa
sv
svr
ublkdu
w
```

## Limitations

* Users with **Admin** role can invite **Editor - Specific Apps** users to one application at a time. To work around this, the **Admin** user can [edit their role](/docs/get-started/manage-dashboard-access/edit-dashboard-users) to assign multiple applications after the user accepts the invitation.
* The **Viewer - Users** and **Editor - Users** roles don't have access to the Users' **Devices** and **Authorized Apps** sections.
* The [New Activity Page](/docs/get-started/auth0-overview/dashboard/activity) is visible to **Admins** and **Elevated Support Access** users only. **Editor - Users** and **Viewer - Users** can access daily activity (such as logins or signups) through the [Auth0 Management API](https://auth0.com/docs/api/management/v2#!/Stats/get_daily).

## Private Cloud requirements

The **Editor - Users** and the **Viewer - Users** roles require that User Search v3 and Logs Search v3 are enabled in your environment. If your environments don’t support these versions, these two roles are unavailable.

## Learn more

* [Add Tenant Members](/docs/get-started/manage-dashboard-access/add-dashboard-users)
* [Edit Tenant Members](/docs/get-started/manage-dashboard-access/edit-dashboard-users)
* [Remove Tenant Members](/docs/get-started/manage-dashboard-access/remove-dashboard-users)
* [Troubleshoot Role-Based Access Control and Authorization](/docs/troubleshoot/authentication-issues/troubleshoot-rbac-authorization)
* [Check Error Messages](/docs/troubleshoot/basic-issues/check-error-messages)


# Remove Tenant Members
Source: https://auth0.com/docs/get-started/manage-dashboard-access/remove-dashboard-users

Learn how to remove tenant members from access to the Auth0 Dashboard for your Auth0 tenant.

If you are a tenant administrator, you can revoke access to the Dashboard.

1. Go to [Dashboard > Settings > Tenant Members](https://manage.auth0.com/#/tenant/admins).
2. Click **...** to the right of a user name or email and click **Remove**.
3. Click **Save**.

## Learn more

* [Dashboard Access by Role](/docs/get-started/manage-dashboard-access/feature-access-by-role)
* [Add Tenant Members](/docs/get-started/manage-dashboard-access/add-dashboard-users)
* [Edit Tenant Members](/docs/get-started/manage-dashboard-access/edit-dashboard-users)


# Update Dashboard User Email Addresses
Source: https://auth0.com/docs/get-started/manage-dashboard-access/update-dashboard-user-email

Learn how to update Auth0 Dashboard tenant member email addresses.

As a tenant administrator, you can update the email address associated with an existing <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> member by adding a new user with the new email address and removing the user associated with the old email address.

1. Go to [Dashboard > Settings > Tenant Members](https://manage.auth0.com/#/tenants/admins).
2. Click **Add Member**.
3. Enter the new email address and select the access permissions.
4. Click **Invite** to send the email invitation to the user.
5. Once the user accepts the invitation, remove the user associated with the old email address.

<Callout icon="file-lines">
  It is not possible to update your own email address as an end user in Dashboard or through the API. If you need to update the email address associated with your account, please contact your administrator.
</Callout>

## Learn more

* [Reset Account Passwords](/docs/troubleshoot/customer-support/reset-account-passwords)


# Authenticate
Source: https://auth0.com/docs/authenticate

Learn all about how to authenticate using Auth0.

<AuthDocsPipeline />

In authentication, a user or application proves they are who they say they are by providing valid credentials. The most common verification is password, often combined with other methods, such as a fingerprint.

Auth0 simplifies the use of open industry standards like OAuth 2.0, OIDC, and SAML to authenticate. Users can log into your applications with social media credentials, corporate accounts, and a broad range of other credentials.

***

## Add Login

##### Implement Auth0 Universal Login (or an alternative) to control access to your applications.

<Card title="Login" href="/docs/authenticate/login">
  Choose from a variety of user login options.
</Card>

<Card title="Single Sign-On" href="/docs/authenticate/single-sign-on">
  Enable users to log in to one application and automatically authenticate in other applications.
</Card>

<Card title="Passwordless" href="/docs/authenticate/passwordless">
  Let users enter mobile phone numbers or email addresses and receive a one-time code or link to log in without a password.
</Card>

<Card title="Custom Token Exchange" href="/docs/authenticate/custom-token-exchange">
  Learn about Custom Token Exchange Early Access features.
</Card>

***

## Provision Users

##### Source users from social identity providers (such as Facebook or SalesForce), enterprise user stores (such as Active Directory or Google Workspace), a custom database, and more.

<Card title="Identity Providers" href="/docs/authenticate/identity-providers">
  Set up sources of user accounts to authenticate your applications and APIs.
</Card>

<Card title="Database Connections" href="/docs/authenticate/database-connections">
  Authenticate users with an email/username and password and save their credentials in an Auth0-provided user store or in your own database.
</Card>

<Card title="Enterprise Connections" href="/docs/authenticate/enterprise-connections">
  Authenticate users with external, federated identity providers such as Azure AD, Google Workspace, and PingFederate.
</Card>

<Card title="Protocols" href="/docs/authenticate/protocols">
  Easily implement open industry-standard protocols like OAuth 2.0, SAML, and LDAP for authentication and authorization.
</Card>

<Card title="Connection Settings Best Practices" href="/docs/authenticate/connection-settings-best-practices">
  Review best practices when configuring social and database connections.
</Card>


# Login
Source: https://auth0.com/docs/authenticate/login

Learn about the ways to implement login authentication for your users with Auth0 Universal Login or Embedded Login.

Auth0 offers two ways to implement login authentication for your applications:

* **<Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>** where users log in to your application through a page hosted by Auth0.
* **Embedded Login** where users log in to your application through a page you host.

For the vast majority of use cases, we recommend Universal Login. It's safe and easy to implement.

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/authenticate/login/auth0-universal-login">Universal Login</a></td>
      <td>What is Universal Login.</td>
    </tr>

    <tr>
      <td><a href="/docs/authenticate/login/universal-vs-embedded-login">Universal vs. Embedded Login</a></td>
      <td>What the differences are between Universal Login and Embedded Login.</td>
    </tr>

    <tr>
      <td><a href="/docs/authenticate/login/embedded-login">Embedded Login</a></td>
      <td>How Embedded Login works.</td>
    </tr>

    <tr>
      <td><a href="/docs/authenticate/login/cross-origin-authentication">Cross-Origin Authentication</a></td>
      <td>About the cross-origin authentication flow using third-party cookies.</td>
    </tr>

    <tr>
      <td><a href="/docs/authenticate/login/configure-silent-authentication">Silent Authentication</a></td>
      <td>How to keep users logged in to your application using silent authentication.</td>
    </tr>

    <tr>
      <td><a href="/docs/authenticate/login/redirect-users-after-login">Redirect After Login</a></td>
      <td>How to redirect users to URLs after login.</td>
    </tr>

    <tr>
      <td><a href="/docs/authenticate/login/logout">Logout</a></td>
      <td>How logging out works with Auth0.</td>
    </tr>

    <tr>
      <td><a href="/docs/authenticate/login/oidc-conformant-authentication">Adopt OIDC Conformant Auth</a></td>
      <td>What the OIDC-conformant application setting is and its effect on the authentication pipeline.</td>
    </tr>
  </tbody>
</table>

You can also use Client-Initiated Backchannel Authentication to authenticate users with a decoupled authentication flow:

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To Learn...</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow">Client-Initiated Backchannel Authentication Flow</a></td>
      <td>How to build a decoupled authentication flow.</td>
    </tr>
  </tbody>
</table>


# Auth0 Universal Login
Source: https://auth0.com/docs/authenticate/login/auth0-universal-login

Describes how Auth0 Universal Login provides you with the means to prove your users' identities with our authorization server.

Auth0 <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> provides the essential feature of an <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip>: the login flow. When a user needs to prove their identity to gain access to your application, you can redirect them to Universal Login and let Auth0 handle the authentication process.

With Universal Login, you don’t have to complete any integration work to accommodate different methods of authentication. You can start with a simple identifier and password flow, then add additional features, such as social login or <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA), to customize a secure and user-friendly login experience.

Configuring Universal Login is dynamic and does not require any application-level changes, as web pages hosted on Auth0’s centralized <Tooltip href="/docs/glossary?term=authentication+server">authentication server</Tooltip> completely drive the login flow. Additionally, you don’t need to manually update your code for applications to benefit from improvements Auth0 makes to Universal Login.

From the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, you can customize the appearance and behavior of login pages to create a consistent, branded experience. For advanced use cases, you can also change the code of each page individually.

To learn more about the differences between Universal Login and embedded login, review [Centralized Universal Login vs. Embedded Login](/docs/authenticate/login/universal-vs-embedded-login).

## Configure Universal Login

On your Auth0 Dashboard, you can choose which experience to use for default login pages under [Branding > Universal Login > Advanced Options](https://manage.auth0.com/#/universal-login/customizations-new).

Auth0 offers two hosted login experiences:

* **Universal Login** offers a streamlined experience for users and does not require the use of JavaScript for customization.
* **Classic Login** uses JavaScript controls for each page of the login flow.

At this time, Auth0’s active development efforts are focused on Universal Login, and Classic Login no longer receives updates. Unless your specific use case requires the Classic experience, implementing Universal Login is recommended.

To learn more about how these two experiences compare, review [Universal Login vs. Classic Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login).

### Accessibility

Auth0 employs the following standards to improve access to Universal Login flows for people who use assistive technologies:

* [Web Content Accessibility Guidelines (WCAG) version 2.2 AA](https://www.w3.org/WAI/standards-guidelines/wcag/)
* [EN 301 549](https://www.etsi.org/human-factors-accessibility/en-301-549-v3-the-harmonized-european-standard-for-ict-accessibility)

Auth0 Universal Login enables these standards by default. Below are areas that could impact customer customizations:

* Validation errors are shown inline instead of as tooltips so they are accessible to screen readers.
* The default interface component colors are aligned with WCAG guidelines around color contrast.
* Forms use autocorrect.
* The [ARIA](https://www.w3.org/WAI/standards-guidelines/aria/) and other attributes of the interface components allow easy screen reader navigation.
* Email addresses are validated client side and follow the same formatting rules as the server side validation.
* HTML labels are accessible and associated with their respective input fields.
* Password complexity requirements and inline error messages are announced by screen readers.
* All <Tooltip href="/docs/glossary?term=authorization+flow">authorization flow</Tooltip> screens have a useful and distinct page title.
* Required fields include a visual indicator on the label.

### Customize login page

After enabling Universal Login, you can customize your login page directly from the Auth0 Dashboard. Specifically, you can customize page templates and themes, sign-up and login prompts, and other text elements. To learn more, review Customize Universal Login.

If you decide to implement Classic Login, you can customize basic branding options from the Auth0 Dashboard. You can then configure advanced customization with the SDK used to build your login flow. To learn more, review Customize Classic Login.

## Implement Universal Login

After enabling either Universal Login or Classic Login within your tenant, follow the steps below to implement the experience:

1. [Register your application](/docs/get-started/auth0-overview/create-applications) with Auth0.
2. Configure your application to call the [Login endpoint](https://auth0.com/docs/api/authentication#login) of the Authentication API to trigger the login flow and handle the response. and handle the response. You can configure this directly or use one of Auth0's [SDKs](/docs/libraries).
3. Create a [Database](/docs/get-started/applications/set-up-database-connections), [Enterprise](/docs/authenticate/enterprise-connections), or [Social](/docs/authenticate/identity-providers/social-identity-providers) connection and enable it for your application.

### Navigate to the login page

You can call the [Login endpoint](https://auth0.com/docs/api/authentication#login) directly from any browser:

<AuthCodeBlock />

The request must include the following values:

* `response_type` (either `code` or `token`)
* `client_id`
* `redirect_uri`
* `state`

  * To better understand why this value is required review [Prevent Attacks and Redirect Users With OAuth 2.0 State Parameters](/docs/secure/attack-protection/state-parameters).

Optionally, you can include the `connection` parameter to prompt users to authenticate with the specified connection.

### Use the Quickstart guides

For more information on how you can set up Universal Login for your application, review the [Quickstart guides](/docs/quickstarts). Choose the approach that best fits your technologies and follow the Quickstart for a walkthrough of the implementation.

## Learn more

* [Hosted Login vs. Embedded Login](/docs/authenticate/login/universal-vs-embedded-login)
* [Universal Login Experience](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience)
* [Classic Login Experience](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/classic-experience)
* [Universal Login vs. Classic Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login)
* [Universal Login Internationalization](/docs/customize/internationalization-and-localization/universal-login-internationalization)


# Configure Default Login Routes
Source: https://auth0.com/docs/authenticate/login/auth0-universal-login/configure-default-login-routes

Learn how to configure your tenant's and application's default login routes.

In certain cases (described below), Auth0 may need to redirect back to the application's Login Initiation endpoint, using OIDC third-party initiated login. To learn more, read [Initiating Login from a Third Party](https://openid.net/specs/openid-connect-core-1_0.html#ThirdPartyInitiatedLogin) at the [OpenID Foundation](https://openid.net).

You can configure these URIs with the Dashboard in [Application Settings](https://manage.auth0.com/#/applications/settings) or [Tenant Advanced Settings](https://manage.auth0.com/#/tenant/advanced) or with the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

<Tabs>
  <Tab title="Application level">
    <AuthCodeGroup>
      ```bash cURL theme={null}
      curl --request PATCH \
        --url 'https://{yourDomain}/api/v2/clients/{yourClientId}' \
        --header 'authorization: Bearer API2_ACCESS_TOKEN' \
        --header 'cache-control: no-cache' \
        --header 'content-type: application/json' \
        --data '{"initiate_login_uri": "<login_url>"}'
      ```

      ```csharp C# theme={null}
      var client = new RestClient("https://{yourDomain}/api/v2/clients/{yourClientId}");
      var request = new RestRequest(Method.PATCH);
      request.AddHeader("content-type", "application/json");
      request.AddHeader("authorization", "Bearer API2_ACCESS_TOKEN");
      request.AddHeader("cache-control", "no-cache");
      request.AddParameter("application/json", "{"initiate_login_uri": "<login_url>"}", ParameterType.RequestBody);
      IRestResponse response = client.Execute(request);
      ```

      ```go Go theme={null}
      package main

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

      func main() {

      	url := "https://{yourDomain}/api/v2/clients/{yourClientId}"

      	payload := strings.NewReader("{"initiate_login_uri": "<login_url>"}")

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

      	req.Header.Add("content-type", "application/json")
      	req.Header.Add("authorization", "Bearer API2_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))

      }
      ```

      ```java Java theme={null}
      HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/clients/{yourClientId}")
        .header("content-type", "application/json")
        .header("authorization", "Bearer API2_ACCESS_TOKEN")
        .header("cache-control", "no-cache")
        .body("{"initiate_login_uri": "<login_url>"}")
        .asString();
      ```

      ```javascript Node.JS theme={null}
      var axios = require("axios").default;

      var options = {
        method: 'PATCH',
        url: 'https://{yourDomain}/api/v2/clients/{yourClientId}',
        headers: {
          'content-type': 'application/json',
          authorization: 'Bearer API2_ACCESS_TOKEN',
          'cache-control': 'no-cache'
        },
        data: {initiate_login_uri: '<login_url>'}
      };

      axios.request(options).then(function (response) {
        console.log(response.data);
      }).catch(function (error) {
        console.error(error);
      });
      ```

      ```objc Obj-C theme={null}
      #import <Foundation/Foundation.h>

      NSDictionary *headers = @{ @"content-type": @"application/json",
                                 @"authorization": @"Bearer API2_ACCESS_TOKEN",
                                 @"cache-control": @"no-cache" };
      NSDictionary *parameters = @{ @"initiate_login_uri": @"<login_url>" };

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

      NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/clients/{yourClientId}"]
                                                             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];
      ```

      ```php PHP theme={null}
      $curl = curl_init();

      curl_setopt_array($curl, [
        CURLOPT_URL => "https://{yourDomain}/api/v2/clients/{yourClientId}",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => "",
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => "PATCH",
        CURLOPT_POSTFIELDS => "{"initiate_login_uri": "<login_url>"}",
        CURLOPT_HTTPHEADER => [
          "authorization: Bearer API2_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;
      }
      ```

      ```python Python theme={null}
      import http.client

      conn = http.client.HTTPSConnection("")

      payload = "{"initiate_login_uri": "<login_url>"}"

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

      conn.request("PATCH", "/{yourDomain}/api/v2/clients/{yourClientId}", payload, headers)

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

      print(data.decode("utf-8"))
      ```

      ```ruby Ruby theme={null}
      require 'uri'
      require 'net/http'
      require 'openssl'

      url = URI("https://{yourDomain}/api/v2/clients/{yourClientId}")

      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 API2_ACCESS_TOKEN'
      request["cache-control"] = 'no-cache'
      request.body = "{"initiate_login_uri": "<login_url>"}"

      response = http.request(request)
      puts response.read_body
      ```

      ```swift Swift theme={null}
      import Foundation

      let headers = [
        "content-type": "application/json",
        "authorization": "Bearer API2_ACCESS_TOKEN",
        "cache-control": "no-cache"
      ]
      let parameters = ["initiate_login_uri": "<login_url>"] as [String : Any]

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

      let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/clients/{yourClientId}")! 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()
      ```
    </AuthCodeGroup>
  </Tab>

  <Tab title="Tenant level">
    <AuthCodeGroup>
      ```bash cURL theme={null}
      curl --request PATCH \
        --url 'https://{yourDomain}/api/v2/tenants/settings' \
        --header 'authorization: Bearer API2_ACCESS_TOKEN' \
        --header 'cache-control: no-cache' \
        --header 'content-type: application/json' \
        --data '{"default_redirection_uri": "<login_url>"}'
      ```

      ```csharp C# theme={null}
      var client = new RestClient("https://{yourDomain}/api/v2/tenants/settings");
      var request = new RestRequest(Method.PATCH);
      request.AddHeader("content-type", "application/json");
      request.AddHeader("authorization", "Bearer API2_ACCESS_TOKEN");
      request.AddHeader("cache-control", "no-cache");
      request.AddParameter("application/json", "{"default_redirection_uri": "<login_url>"}", ParameterType.RequestBody);
      IRestResponse response = client.Execute(request);
      ```

      ```go Go theme={null}
      package main

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

      func main() {

      	url := "https://{yourDomain}/api/v2/tenants/settings"

      	payload := strings.NewReader("{"default_redirection_uri": "<login_url>"}")

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

      	req.Header.Add("content-type", "application/json")
      	req.Header.Add("authorization", "Bearer API2_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))

      }
      ```

      ```java Java theme={null}
      HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/tenants/settings")
        .header("content-type", "application/json")
        .header("authorization", "Bearer API2_ACCESS_TOKEN")
        .header("cache-control", "no-cache")
        .body("{"default_redirection_uri": "<login_url>"}")
        .asString();
      ```

      ```javascript Node.JS theme={null}
      var axios = require("axios").default;

      var options = {
        method: 'PATCH',
        url: 'https://{yourDomain}/api/v2/tenants/settings',
        headers: {
          'content-type': 'application/json',
          authorization: 'Bearer API2_ACCESS_TOKEN',
          'cache-control': 'no-cache'
        },
        data: {default_redirection_uri: '<login_url>'}
      };

      axios.request(options).then(function (response) {
        console.log(response.data);
      }).catch(function (error) {
        console.error(error);
      });
      ```

      ```objc Obj-C theme={null}
      #import <Foundation/Foundation.h>

      NSDictionary *headers = @{ @"content-type": @"application/json",
                                 @"authorization": @"Bearer API2_ACCESS_TOKEN",
                                 @"cache-control": @"no-cache" };
      NSDictionary *parameters = @{ @"default_redirection_uri": @"<login_url>" };

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

      NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/tenants/settings"]
                                                             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];
      ```

      ```php PHP theme={null}
      $curl = curl_init();

      curl_setopt_array($curl, [
        CURLOPT_URL => "https://{yourDomain}/api/v2/tenants/settings",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => "",
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => "PATCH",
        CURLOPT_POSTFIELDS => "{"default_redirection_uri": "<login_url>"}",
        CURLOPT_HTTPHEADER => [
          "authorization: Bearer API2_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;
      }
      ```

      ```python Python theme={null}
      import http.client

      conn = http.client.HTTPSConnection("")

      payload = "{"default_redirection_uri": "<login_url>"}"

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

      conn.request("PATCH", "/{yourDomain}/api/v2/tenants/settings", payload, headers)

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

      print(data.decode("utf-8"))
      ```

      ```ruby Ruby theme={null}
      require 'uri'
      require 'net/http'
      require 'openssl'

      url = URI("https://{yourDomain}/api/v2/tenants/settings")

      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 API2_ACCESS_TOKEN'
      request["cache-control"] = 'no-cache'
      request.body = "{"default_redirection_uri": "<login_url>"}"

      response = http.request(request)
      puts response.read_body
      ```

      ```swift Swift theme={null}
      import Foundation

      let headers = [
        "content-type": "application/json",
        "authorization": "Bearer API2_ACCESS_TOKEN",
        "cache-control": "no-cache"
      ]
      let parameters = ["default_redirection_uri": "<login_url>"] as [String : Any]

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

      let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/tenants/settings")! 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()
      ```
    </AuthCodeGroup>
  </Tab>
</Tabs>

***

The `login_url` should point to a route in the application that ends up redirecting to Auth0's `/authorize` endpoint, e.g. `https://mycompany.org/login`. Note that it requires `https` and it cannot point to `localhost`. `login_url` can include query parameters and a URI fragment.

As per the OIDC Third Party Initiated Login specification, the `iss` parameter containing Issuer Identifier will be added as a query string parameter to `login_url` before redirecting.

## Redirect default login route scenarios

### Users bookmark login page

When an application initiates the login process, it navigates to `https://{yourDomain}/authorize` with a set of [required parameters](https://auth0.com/docs/api/authentication#login). Auth0 then redirects end-users to an `https://{yourDomain}/login` page, with a URL that looks like:

`https://{yourDomain}/login?state=g6Fo2SBjNTRyanlVa3ZqeHN4d1htTnh&...`

The `state` parameter points to a record in an internal database where we track the status of the authorization transaction. Whenever the transaction completes, or after a set time passes, the record is deleted from the internal database.

If you are using Organizations and the end-user bookmarks the organization login prompt, Auth0 also includes the `organization` parameter when it redirects the user to the default login route.

Sometimes users bookmark the login page, and when they navigate to the bookmarked `/login` URL, the transaction record is no longer there and Auth0 cannot continue with the login flow. In that case, Auth0 will redirect to the default client URL if configured, or the tenant level URL if not. If no default login URL is set, Auth0 will render an error page.

### Complete password reset flow

After completing the password reset flow and the default URI for the application or tenant is configured, users will see a button that will let them navigate back to the login page.

This behavior only happens when you enable the <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> experience. With Classic Login, you need to configure the redirect URL in the Change Password template. To learn more, read [Customize Email Templates](/docs/customize/email/email-templates).

For tenants using Universal Login, the [`/post-password-change`](https://auth0.com/docs/api/management/v2/#!/Tickets/post_password_change) endpoint supports redirecting users back to a specific application. When `client_id` is specified and the application's login URI is set, users will see a button sending them back to the application after completing a password reset.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/tickets/password-change' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'content-type: application/json' \
    --data '{ "user_id": "A_USER_ID", "client_id": "A_CLIENT_ID" }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/tickets/password-change");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddParameter("application/json", "{ "user_id": "A_USER_ID", "client_id": "A_CLIENT_ID" }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/tickets/password-change"

  	payload := strings.NewReader("{ "user_id": "A_USER_ID", "client_id": "A_CLIENT_ID" }")

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

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

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/tickets/password-change")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .body("{ "user_id": "A_USER_ID", "client_id": "A_CLIENT_ID" }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/tickets/password-change',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN'
    },
    data: {user_id: 'A_USER_ID', client_id: 'A_CLIENT_ID'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };
  NSDictionary *parameters = @{ @"user_id": @"A_USER_ID",
                                @"client_id": @"A_CLIENT_ID" };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/tickets/password-change"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/tickets/password-change",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "user_id": "A_USER_ID", "client_id": "A_CLIENT_ID" }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN",
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "user_id": "A_USER_ID", "client_id": "A_CLIENT_ID" }"

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

  conn.request("POST", "/{yourDomain}/api/v2/tickets/password-change", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/tickets/password-change")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request.body = "{ "user_id": "A_USER_ID", "client_id": "A_CLIENT_ID" }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN"
  ]
  let parameters = [
    "user_id": "A_USER_ID",
    "client_id": "A_CLIENT_ID"
  ] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/tickets/password-change")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

### Complete email verification flow

As part of the signup process, users who choose email as their identifier receive an email to verify their email address. If they click on the link, they will land on a page that says that the email was verified, with a button to go back to the application. When clicked, users will be redirected to the login page, and if they already have a valid session, they'll end up being redirected to the application.

This behavior only happens when the Universal Login experience is enabled. With Classic Login, you need to configure the redirect URL in the Verification Email template.

### Invite organization members

When users are invited to join an [Organization](/docs/manage-users/organizations/organizations-overview), they receive an invitation link by email. If they select the link, they are redirected to the configured default login route with invitation-specific parameters appended.

For example, if you have an organization-enabled application with an **Application Login URI** set to `https://myapp.com/login`, then the link sent in the email invitation that an end-user receives will be: `https://myapp.com/login?invitation={invitation_ticket_id}&organization={organization_id}&organization_name={organization_name}`.

Thus, the route in your application must accept `invitation` and `organization` parameters through the query string. To start the invitation acceptance transaction, it should forward both parameters along with the end-user to your Auth0 `/authorize` endpoint.

### Disabled cookies

If a user navigates to `https://{yourDomain}/authorize` with cookies disabled in their browser, Auth0 redirects the user to the application login URI. If the application login URI is not set, the redirect is sent to the tenant login URI instead.

Sending the user back to the login page can potentially cause a redirect loop. To avoid this issue, use a landing page to check the availability of cookies; if disabled, warn the user to enable them if they wish to continue.

## Learn more

* [Customize Email Templates](/docs/customize/email/email-templates)
* [Check API Calls](/docs/troubleshoot/authentication-issues/check-api-calls)
* [Check Error Messages](/docs/troubleshoot/basic-issues/check-error-messages)
* [Manage Authentication Factors with Authentication API](/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis/manage-authenticator-factors-mfa-api)


# Default Auth0 Error Page
Source: https://auth0.com/docs/authenticate/login/auth0-universal-login/error-pages

Describes the default Auth0 error page display information and parameters used for authorization error events.

If your callback URL is valid, when an authorization error occurs, the <Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip> returns the appropriate error and state parameters to your callback URL. In cases where your callback URL is invalid, your application will display the default generic Auth0 error page. Alternatively, you can customize the error pages. To learn more, read [Custom Error Pages](/docs/customize/login-pages/custom-error-pages).

To find the default page name for the generic error page, see [Use Version Control to Manage Your Universal Login Pages](/docs/customize/login-pages/classic-login/version-control).

## Display

The generic error page displays the following information if you have configured the associated fields in your [Tenant Settings](https://manage.auth0.com/#/tenant/).

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Friendly Name</td>
      <td>Name of your company</td>
    </tr>

    <tr>
      <td>Logo URL</td>
      <td>URL of your company logo</td>
    </tr>

    <tr>
      <td>Support Email</td>
      <td>Email address of your company's support team</td>
    </tr>

    <tr>
      <td>Support URL</td>
      <td>URL of your company's support page</td>
    </tr>
  </tbody>
</table>

## Parameters

The Authorization Server returns parameters appended to the URL as a query string.

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>client\_id</code></td>
      <td>Identifier of the Auth0 application.</td>
    </tr>

    <tr>
      <td><code>connection</code></td>
      <td>Connection used at the time of error.</td>
    </tr>

    <tr>
      <td><code>lang</code></td>
      <td>Language set for use at the time of error.</td>
    </tr>

    <tr>
      <td><code>error</code></td>
      <td>Error code of the error.</td>
    </tr>

    <tr>
      <td><code>error\_description</code></td>
      <td>Description of the error.</td>
    </tr>

    <tr>
      <td><code>tracking</code></td>
      <td>Identifier used by Auth0 to find errors in internal logs.</td>
    </tr>
  </tbody>
</table>

Parameters presented vary depending on the error type and are specific to the request. For example, if the request did not contain a `client_id` and resulted in an error, no <Tooltip href="/docs/glossary?term=client+ID">client ID</Tooltip> will be returned by the error page.

## Learn more

* [Customize Error Pages](/docs/customize/login-pages/custom-error-pages)


# Configure Identifier First Authentication
Source: https://auth0.com/docs/authenticate/login/auth0-universal-login/identifier-first

Learn how to configure Identifier First authentication with Universal Login.

Identifier First login flows prompt users for their identifier and authentication method in two separate steps. For example, when you authenticate to Google websites, you enter your email first, click next, and then enter your password.

## How it works

This two-step approach - which works only with the **New <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> Experience** and **Identifier + Password** flows - lets you customize a user's experience depending on the identifier they entered:

* When a user enters a corporate email (for example, `user@acme.com`), you can redirect them to acme.com’s corporate login page.
* If a user enters an email for a personal account, you can prompt them for their password.
* If the user enrolls their device in WebAuthn w/Device Biometrics, they can use their device's biometric authenticator instead of a password.

<Frame>
  <img alt="Auth0 Universal Login Identifier First authentication flow diagram" />
</Frame>

## Configure Identifier First

1. Go to [Dashboard > Authentication > Authentication Profile](https://manage.auth0.com/#/authentication-profiles).
2. Pick the flow you want to use:

   * Identifier + Password: Users will enter their identifier and password on the same screen.
   * Identifier First: Users will enter their identifier on the first screen. If the identifier matches the enterprise connection Identity Provider Home Realm domain, the application will redirect the user to the enterprise connection's login page.
     If not, they will enter their password.
   * Identifier First + Biometrics: The same as above, but if users log in from a device that supports WebAuthn w/Device Biometrics, the application will prompt them to enroll that device, and they can use it in subsequent logins. You can learn more about this feature [here](/docs/authenticate/login/auth0-universal-login/passwordless-login/webauthn-device-biometrics).

## Define Home Realm Discovery identity providers

As noted above, when a user enters their email, Auth0 checks if the domain matches one from a registered Enterprise connection. If there is a match, Auth0 redirects the user to the enterprise <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>’s login page. If the domain does not match, the user must enter their password. This is also known as Home Realm Discovery (HRD).

1. Go to [Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise).
2. Select a connection.
3. In the **Login Experience** tab set a maximum of 1000 domains.
4. (Optional) Choose to display a button in the login page in addition to, or instead of, using the Identity Provider domains.


# Configure Universal Login with Passwordless
Source: https://auth0.com/docs/authenticate/login/auth0-universal-login/passwordless-login

Learn how to configure your login page to use passwordless authentication using the Auth0 Dashboard.

<Card title="Availability varies by Auth0 plan">
  Your Auth0 plan or custom agreement affects whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

<Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> is Auth0's implementation of the authentication flow, which is the key feature of an <Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip>. Each time a user needs to prove their identity, your applications redirect to Universal Login and Auth0 guarantees the user's identity. You can choose to enable <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> authentication when you configure Universal Login in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

First, determine if you want users to use SMS, email, or WebAuthn for device biometrics as the Passwordless authentication method. It is not currently possible to support all three authentication methods in a single login flow.

## Passwordless with email or SMS

You can configure Auth0 so users can authenticate with a magic link or one-time password (OTP) sent to their email, or an OTP sent to their phone number. To learn more, read [Configure Email or SMS for Passwordless Authentication](/docs/authenticate/login/auth0-universal-login/passwordless-login/email-or-sms).

## Passwordless with WebAuthn with device biometrics

When using WebAuthn with Device Biometrics, users will be able to authenticate with their password, or with any of their devices that support WebAuthn with Device Biometrics.

Each time they login from a new device, Auth0 will offer them the option to use biometrics instead of a password. To learn more, read [Passwordless with WebAuthn with Device Biometrics](/docs/authenticate/login/auth0-universal-login/passwordless-login/webauthn-device-biometrics).

<Frame>
  <img alt="Example of setting up a Face ID login for specific domain using WebAuthn" />
</Frame>

## Learn more

* [Configure Email or SMS for Passwordless Authentication](/docs/authenticate/login/auth0-universal-login/passwordless-login/email-or-sms)
* [Configure WebAuthn with Device Biometrics for Passwordless Authentication](/docs/authenticate/login/auth0-universal-login/passwordless-login/webauthn-device-biometrics)


# Configure Email or SMS for Passwordless Authentication
Source: https://auth0.com/docs/authenticate/login/auth0-universal-login/passwordless-login/email-or-sms

Learn how to configure email or SMS for Passwordless authentication.

Auth0 lets you configure <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> so users can authenticate with a magic link or one-time password (OTP) through email, or an OTP through SMS.

To enable <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> authentication with SMS or email, you need to define a [Passwordless connection](/docs/authenticate/passwordless) for your application.

Once you've created the connection, you need to configure Universal Login to use it. You have three options:

## Universal Login

This method uses the Universal Login Experience, which natively supports Passwordless connections. To learn more, read [Passwordless with Universal Login](/docs/authenticate/passwordless/passwordless-with-universal-login).

## Universal Login + Lock (passwordless)

This method uses a custom login page with the **Lock (passwordless)** template, and authenticates user with the [Lock for Web SDK](/docs/libraries/lock):

1. Go to [Dashboard > Branding > Universal Login](https://manage.auth0.com/#/login_settings) and click the **Login** tab.
2. Enable the **Custom Login Page** toggle, and select the **Lock (passwordless)** template. The HTML template will update with code using the Lock widget with Passwordless customization options.
3. Customize the template, and click **Save Changes**.

You can use HTML and CSS to customize the login form, and preview the changes within the Dashboard. To learn more about how to customize the **Lock (passwordless)** template, read the Passwordless section in [Lock for Web SDK](/docs/libraries/lock).

## Universal Login + Custom UI + Auth0.js

This method uses a custom login page with the **Custom Login Form** template, and authenticates users with the [Auth0.js SDK](/docs/libraries/auth0js). To learn more, read [Passwordless Authentication with Universal Login](/docs/authenticate/passwordless/implement-login/universal-login).

## Learn more

* [Configure Universal Login with Passwordless](/docs/authenticate/login/auth0-universal-login/passwordless-login)
* [Configure WebAuthn with Device Biometrics for Passwordless Authentication](/docs/authenticate/login/auth0-universal-login/passwordless-login/webauthn-device-biometrics)


# Configure WebAuthn with Device Biometrics for Passwordless Authentication
Source: https://auth0.com/docs/authenticate/login/auth0-universal-login/passwordless-login/webauthn-device-biometrics

Learn how to configure WebAuthn with device biometrics for passwordless authentication.

You can configure <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> to let users authenticate using [WebAuthn](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn) with Device Biometrics instead of a password.

WebAuthn with Device Biometrics is the most secure and usable authentication factor that's available today, greatly reducing login friction without sacrificing security.

<Warning>
  You must use this feature with an Auth0 database connection. Navigate to [Auth0 Dashboard > Authentication > Database](https://manage.auth0.com/#/connections/database) to choose a database connection. To learn more, read [Database Connections](/docs/authenticate/database-connections).
</Warning>

## Prerequisite

To enable <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> with WebAuthn Device Biometrics, you need to:

1. Make sure the Universal Login experience is enabled and that the HTML for the login page is not customized in [Dashboard > Universal Login](https://manage.auth0.com/#/login_settings).
2. Select **Identifier First + Biometrics** in the [Dashboard > Authentication Profile](https://manage.auth0.com/#/authentication-profiles). This will automatically [enable WebAuthn with Device Biometrics](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-device-biometrics-for-mfa) in the Multi-Factor authentication section if it is not enabled yet.
3. If you use a [custom database connection](/docs/authenticate/database-connections/custom-db), ensure **Import Mode** is set to **On.** If it's not, you can run the [getUser script](/docs/authenticate/database-connections/custom-db/templates/get-user) to the same effect.

## How does it work

Users that authenticate with username/email and password and have a device that [is capable of using WebAuthn with Device Biometrics](https://webauthn.me/browser-support), are given the option of enrolling their device:

<Frame>
  <img alt="Example of setting up a Face ID login for specific domain using WebAuthn" />
</Frame>

After you enable the feature, we provide a few options for users on the Login Faster on This Device dialog box. Users can choose to enroll their device or skip enrollment to reduce the number of times they are prompted:

<table>
  <thead>
    <tr>
      <th>Option</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>Continue</code></td>
      <td>Prompts the user for Biometric Factor Enrollment</td>
    </tr>

    <tr>
      <td><code>Remind me later</code></td>
      <td>Skips enrollment and prompts for enrollment again in two weeks</td>
    </tr>

    <tr>
      <td><code>Not on this device</code></td>
      <td>Does not prompt enrollment for 1 year or as long as the Auth0 cookies are stored in the users' browser</td>
    </tr>
  </tbody>
</table>

<Frame>
  <img alt="Login - webauthn biometrics - log in faster on this device" />
</Frame>

If customers decide to enroll their device, the next time they authenticate from that device they'll be given the option of using their device biometrics or a password:

<Frame>
  <img alt="Example of using Fingerprint or Face Recognition to login to a domain" />
</Frame>

We call this feature 'progressive enrollment', and it's designed to make the transition to WebAuthn-based authentication easy as possible for both developers and users.

## Multi-Factor Authentication

WebAuthn with Device Biometrics allows avoiding requiring another authentication method for performing <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip>. **WebAuthn with Device Biometrics combines two factors in one**: something you have (the device), and something you are (biometrics) or something you know (the passcode).

This has several consequences:

* When you enable MFA in the dashboard, Auth0 will not prompt for MFA if users authenticated with WebAuthn w/Biometrics as first factor.
* When MFA is enabled and users create a new account, they will:

  * Create a user with a username/password.
  * Enroll in MFA, with a non-biometrics authentication method, so they can complete MFA on any device.
  * Optionally enroll with Device Biometrics.

The next time they log in, they can log in with password + another authentication method or with device biometrics.

* When users authenticate using WebAuthn Biometrics as their only authentication method, the `amr` value in the <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip> will be set to `mfa`.
* If you want to enable MFA from our extensibility platform, you’ll be able to consider how users authenticated to decide if they should be prompted for MFA or not. The rule below will only perform MFA if the user did not authenticate with the `webauthn-platform` authentication method:

```javascript javascript lines theme={null}
function (user, context, callback) {
  let authMethods = context.authentication.methods;

  const amr = authMethods.find((method) => method.name === 'webauthn-platform');

  if (!amr) {
    context.multifactor = {
      provider: 'any',
      allowRememberBrowser: false
    };
  }
  return callback(null, user, context);
}
```

This post-login action will have the same effect:

```javascript javascript lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  let authMethods = event.authentication.methods;

  let amr = authMethods.find((method) => method.name === 'webauthn-platform');

   if (!amr) {
     api.multifactor.enable('any');
  }
};
```

## Device Recognition

Auth0 will use the rules to determine if the device is already enrolled or not, and prompt the user for enrollment. To learn more, read [Device recognition](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-device-biometrics-for-mfa#device-recognition) in the article [Configure WebAuthn with Device Biometrics for MFA](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-device-biometrics-for-mfa).

To avoid user enumeration attacks, Auth0 will only prompt users for biometrics as the first factor if users are logging in from a known device. If not, they'll need to login with the password.

For example:

* A user logs-in from Chrome in Windows, and is enrolled with Windows Hello. As part of the enrollment information, Auth0 knows that the user enrolled from a Windows device, and stores a 'known device' to recognize the user agent.
* The next time the user logs in from Chrome, they will be prompted to use Windows Hello instead of a password.
* If the user later logs in from Firefox in Windows, given the 'known device' cookie is not present, users will need to login with their password. As they are already enrolled with Windows Hello, they won't be prompted to enroll again.
* The next time the user logs in from Firefox, they will be prompted to use Windows Hello.

This will not let attackers know if users have an account or not, or if they used WebAuthn device biometrics to authenticate to the site.

## Webauthn.me

Auth0 maintains [webauthn.me](https://a0.to/webauthme-auth0-docs), which has [detailed information](https://webauthn.me/introduction) about WebAuthn and an up-to-date list of browsers supporting WebAuthn.

## Learn more

* [Configure Universal Login with Passwordless](/docs/authenticate/login/auth0-universal-login/passwordless-login)
* [Configure Email or SMS for Passwordless Authentication](/docs/authenticate/login/auth0-universal-login/passwordless-login/email-or-sms)
* [Configure WebAuthn with Device Biometrics for MFA](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-device-biometrics-for-mfa)
* [FIDO Authentication with WebAuthn](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn)


# Universal Login vs. Classic Login
Source: https://auth0.com/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login

Compares features available in the Universal Login and Classic Login experiences

[Auth0 Universal Login](/docs/authenticate/login/auth0-universal-login) provides the essential feature of an <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip>: the login flow. When a user needs to prove their identity to gain access to your application, you can redirect them to <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> and let Auth0 handle the authentication process.

Universal Login is Auth0's primary hosted login solution. [Universal Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience) features easy-to-use customization tools and promotes a simpler, faster experience for end-users. Alternatively, Auth0 also supports [Classic Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/classic-experience), a hosted login experience that uses JavaScript controls for customization.

<Warning>
  At this time, Auth0’s active development efforts are focused on Universal Login, and Classic Login no longer receives updates. Unless your specific use case requires the Classic experience, implementing Universal Login is recommended.
</Warning>

To help you choose the best solution for your needs, the table below compares the features of both login experiences.

<table>
  <thead>
    <tr>
      <th><strong>Feature</strong></th>
      <th><strong>Universal Login</strong></th>
      <th><strong>Classic Login</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Adopt new features without changing HTML</strong></td>
      <td>Yes</td>
      <td>No</td>
    </tr>

    <tr>
      <td><strong>Ongoing development and new feature additions</strong></td>
      <td>Yes</td>
      <td>No</td>
    </tr>

    <tr>
      <td><strong>Lightweight HTML</strong></td>
      <td>Yes</td>
      <td>No</td>
    </tr>

    <tr>
      <td><strong>JavaScript required</strong></td>
      <td>No</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td><strong>Customization</strong></td>
      <td>Yes, using <a href="/docs/customize/login-pages/universal-login/customize-templates" title="Universal login page templates">page templates</a> or the <a href="/docs/customize/login-pages/universal-login/customize-themes">no-code editor</a></td>
      <td>Yes, using HTML, and only for login, multi-factor authentication (MFA), and password reset pages</td>
    </tr>

    <tr>
      <td><strong>No-Code solution</strong></td>
      <td>Yes, using the <a href="/docs/customize/login-pages/universal-login/customize-themes">no-code editor</a></td>
      <td>No</td>
    </tr>

    <tr>
      <td><strong>Passwordless authentication</strong></td>
      <td>Yes</td>
      <td>Yes, with <a href="/docs/authenticate/login/auth0-universal-login/passwordless-login">SMS or Email</a></td>
    </tr>

    <tr>
      <td><strong>Email magic link</strong></td>
      <td>No</td>
      <td><a href="/docs/authenticate/passwordless/authentication-methods/email-magic-link">Yes</a></td>
    </tr>

    <tr>
      <td><strong>Passkeys</strong></td>
      <td><a href="/docs/authenticate/database-connections/passkeys" title="Passkeys">Yes</a></td>
      <td>No</td>
    </tr>

    <tr>
      <td><strong>WebAuthn and device biometrics</strong></td>
      <td><a href="/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn">Yes</a></td>
      <td>No</td>
    </tr>

    <tr>
      <td><strong>Web Content Accessibility Guidelines (WCAG) Compliance</strong></td>
      <td>Yes</td>
      <td>No</td>
    </tr>

    <tr>
      <td><strong>Organizations support</strong></td>
      <td><a href="/docs/manage-users/organizations">Yes</a></td>
      <td>No</td>
    </tr>

    <tr>
      <td><strong>Terms of service acceptance on signup</strong></td>
      <td>Yes</td>
      <td><a href="/docs/libraries/lock/lock-configuration#showterms-boolean-">Yes</a></td>
    </tr>

    <tr>
      <td><strong>Custom fields on signup</strong></td>
      <td>Yes</td>
      <td><a href="/docs/libraries/lock/lock-configuration#additionalsignupfields-array-">Yes</a></td>
    </tr>

    <tr>
      <td><strong>Full localization</strong></td>
      <td>Yes, in <a href="/docs/customize/internationalization-and-localization/universal-login-internationalization">these</a> languages</td>
      <td>Only for the login page</td>
    </tr>

    <tr>
      <td><strong>Customizable localized text on all pages</strong></td>
      <td><a href="/docs/customize/login-pages/universal-login/customize-text-elements">Yes</a></td>
      <td>No</td>
    </tr>

    <tr>
      <td><strong>Email MFA</strong></td>
      <td><a href="/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-email-notifications-for-mfa">Yes</a></td>
      <td>No</td>
    </tr>

    <tr>
      <td><strong>Voice MFA</strong></td>
      <td><a href="/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-sms-voice-notifications-mfa">Yes</a></td>
      <td>No</td>
    </tr>

    <tr>
      <td><strong>Duo MFA</strong></td>
      <td>Yes, but Duo must be the only MFA factor enabled</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td><strong>MFA customization with Actions</strong></td>
      <td><a href="/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-selection-universal-login">Yes</a></td>
      <td>No</td>
    </tr>

    <tr>
      <td><strong>Buttons for enterprise connections</strong></td>
      <td><a href="/docs/authenticate/login/auth0-universal-login/identifier-first#define-home-realm-discovery-identity-providers">Yes</a></td>
      <td>No</td>
    </tr>

    <tr>
      <td><strong>Ability to disable self-service password recovery</strong></td>
      <td>Yes</td>
      <td><a href="/docs/libraries/lock/lock-configuration#allowforgotpassword-boolean">Yes</a></td>
    </tr>

    <tr>
      <td><strong>Custom URLs for password reset and user signup</strong></td>
      <td>Yes, using page templates <strong>and</strong> a custom-built password reset or signup page</td>
      <td><a href="/docs/libraries/lock/lock-configuration#forgotpasswordlink-string-">Yes</a></td>
    </tr>

    <tr>
      <td><strong>Kerberos support for AD/LDAP connections</strong></td>
      <td>No</td>
      <td><a href="/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/configure-ad-ldap-connector-with-kerberos#auto-login-with-lock">Yes</a></td>
    </tr>

    <tr>
      <td><strong>Requires exposing identity provider domains in a public endpoint</strong></td>
      <td>No</td>
      <td><a href="/docs/get-started/tenant-settings#advanced">Yes</a></td>
    </tr>
  </tbody>
</table>

## Learn more

* [Universal Login Experience](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience)
* [Classic Login Experience](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/classic-experience)
* [Hosted Login vs. Embedded Login](/docs/authenticate/login/universal-vs-embedded-login)


# Classic Login Experience
Source: https://auth0.com/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/classic-experience

An overview of the Classic Login experience

Classic Login is an Auth0-hosted login experience that relies on JavaScript for customization. Implementing Classic Login is less complex than embedding the authentication process directly in your app, and it can help prevent the dangers of cross-origin authentication.

Classic Login is built on top of Auth0's JavaScript libraries ([Lock.js](/docs/libraries/lock), [auth0.js](/docs/libraries/auth0js), <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> Widget, and Password Reset). When customizing Classic Login pages in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, the default templates use the same JavaScript libraries to create a more natural transition between the default user interface and a custom one.

After choosing a default template for your Classic Login pages, you can modify it to meet your needs. You can also customize a variety of behavioral and appearance elements of the Lock widget. The Auth0.js templates offer additional flexibility as you can create a custom user interface and modify it to match your application's style.

<Warning>
  At this time, Auth0’s active development efforts are focused on Universal Login, and Classic Login no longer receives updates. Unless your specific use case requires the Classic experience, implementing Universal Login is recommended.

  For a feature comparison between login experiences, review [Universal Login vs. Classic Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login)
</Warning>

## Implement Classic Login

To learn how to set up your application to use Classic Login, read our [Quickstarts](/docs/quickstarts). Choose the approach that best fits your technologies, and the Quickstarts walk you through the implementation.

## Learn more

* [Universal Login vs. Classic Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login)
* [Customize Classic Login](/docs/customize/login-pages/classic-login)
* [Customize Classic Login Pages](/docs/customize/login-pages/classic-login/customization-classic)
* [Customize Classic Login Pages with Lock or SDK](/docs/customize/login-pages/classic-login/customize-with-lock-sdk)
* [Customize MFA for Classic Login](/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-classic-login)


# Universal Login Experience
Source: https://auth0.com/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience

An overview of the Universal Login experience

[Auth0 Universal Login](/docs/authenticate/login/auth0-universal-login) provides the essential feature of an <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip>: the login flow. When a user needs to prove their identity to gain access to your application, you can redirect them to <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> and let Auth0 handle the authentication process.

The Universal Login experience offers a streamlined implementation with easy-to-use customization tools. For advanced customization, you can also create page templates that allow you to modify the code of your login pages. This experience also supports a variety of features, such as [localization](/docs/customize/internationalization-and-localization/universal-login-internationalization), [WebAuthn](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn), [multi-factor authentication (MFA)](/docs/secure/multi-factor-authentication), [Auth0 Organizations](/docs/manage-users/organizations/organizations-overview), and more.

Configuring Universal Login is dynamic and does not require any application-level changes, as web pages hosted on Auth0’s centralized <Tooltip href="/docs/glossary?term=authentication+server">authentication server</Tooltip> drive the login flow. Additionally, you won’t need to manually update your code for your applications to benefit from improvements Auth0 makes to Universal Login.

## Universal Login features and functionality

The following sections provide additional details about the Universal Login experience. For a feature comparison between Universal Login and Classic Login, review [Universal Login vs. Classic Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login).

### Customization

* You can specify a Liquid Template for all pages in the login flow with [Page Templates](/docs/customize/login-pages/universal-login/customize-templates).
* You can customize page branding, including colors, fonts, custom logo URLs, and more, with the [no-code editor](/docs/customize/login-pages/universal-login/customize-themes) in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, or with the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> [Branding](https://auth0.com/docs/api/management/v2#!/Branding/patch_branding) endpoints.
* You can configure the favicon URL with the Auth0 Management API [Branding](https://auth0.com/docs/api/management/v2#!/Branding/patch_branding) endpoints.
* You can customize page text with either the Auth0 Dashboard or the Management API. To learn more, review [Customize Universal Login Text Elements](/docs/customize/login-pages/universal-login/customize-text-elements).
* You can customize signup and login prompts with the Auth0 Management API. To learn more, review [Customize Signup and Login prompts](/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts).

### Login

* You can use [Passwordless with WebAuthn with Device Biometrics](/docs/authenticate/login/auth0-universal-login/passwordless-login/webauthn-device-biometrics).
* If you are using [development keys](/docs/authenticate/identity-providers/social-identity-providers/devkeys) for social providers:

  * Single Sign-on (SSO) and Silent Authentication will work properly. This is not supported in the Classic Login experience.
  * Users receive a warning on the login page stating the tenant is configured with development keys.
* A button is rendered for each social and enterprise connection.
* If you redirect users to the `/login` page directly, they will receive an error unless you configured a default login route. To learn more, review [Configure Default Login Routes](/docs/authenticate/login/auth0-universal-login/configure-default-login-routes). You should always redirect users to the proper authorization request endpoint (e.g., `/authorize` if you are using <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect).
* You can specify the `login_hint` when redirecting to Auth0 and use this information to populate the username/email field for the login or signup page.
* Passkeys are available as an authentication method for [database connections](/docs/authenticate/database-connections). Passkeys are a phishing-resistant alternative to traditional authentication factors (such as username/password) that offer an easier and more secure login experience to users. To learn more, review [Passkeys](/docs/authenticate/database-connections/passkeys).

### Signup

* You can have users land directly on the signup page instead of the login page by specifying the `screen_hint=signup` parameter when redirecting to `/authorize`. You can combine this paramter with `prompt=login` to indicate whether you want to always show the authentication page or skip the page if an existing session exists.

<table>
  <thead>
    <tr>
      <th><code>/authorize</code> parameters</th>
      <th>No existing session</th>
      <th>Existing session</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>no extra parameters</td>
      <td>Shows the login page</td>
      <td>Redirects to the callback url</td>
    </tr>

    <tr>
      <td><code>screen\_hint=signup</code></td>
      <td>Shows the signup page</td>
      <td>Redirects to the callback url</td>
    </tr>

    <tr>
      <td><code>prompt=login</code></td>
      <td>Shows the login page</td>
      <td>Shows the login page</td>
    </tr>

    <tr>
      <td><code>prompt=login\&screen\_hint=signup</code></td>
      <td>Shows the signup page</td>
      <td>Shows the signup page</td>
    </tr>
  </tbody>
</table>

### Multi-factor authentication

* If users have more than one <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> factor enrolled (e.g., SMS and push notifications), the Universal Login MFA page lets the user choose their preferred option.
* You can use voice or email as an MFA factor. To learn more, review [Configure SMS and Voice Notifications for MFA](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-sms-voice-notifications-mfa) and [MFA Factors](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors).
* If you are using the Guardian SDK to create your own native application to handle Push Notifications, you can configure the name of the application and the URLs to download them in the **Push via Auth0 Guardian** option in the [Dashboard > Security > Multi-Factor Auth](https://manage.auth0.com/#/mfa) section.
* If you have a rule that sets the MFA provider to `google-authenticator`, you must enable that OTP factor in the [Dashboard > Security > Multi-Factor Auth](https://manage.auth0.com/#/mfa) section.
* You can use [WebAuthn](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn) for MFA.
* Using [Actions](/docs/customize/actions), you customize your MFA flows to challenge users with a specific factor or series of factors. You can also leverage user metadata, such as roles or Organization memberships, to create more individualized experiences. To learn more, review [Customize MFA Selection in Universal Login](/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-selection-universal-login).

## Password reset

* The Universal Login experience redirects users to the default login route when it succeeds and handles the error cases as part of the Universal Login flow. The Redirect URL in the email template will be ignored. Note that you must provide an **Application Login URI** in the [Dashboard > Applications > Applications](/docs/get-started/applications/application-settings) **Settings** tab for the redirect URLs to work.
* If the database connection is set to **Require Username**, the password reset flow prompts the user for their username and sends a password reset email to the associated email address. To learn more, review [Adding Username for Database Connections](/docs/authenticate/database-connections/require-username).
* Using [Actions](/docs/customize/actions), you can incorporate a secondary challenge into your [password reset flows](/docs/customize/actions/explore-triggers/password-reset-triggers). Specifically, the `post-challenge` trigger allows you to present an additional challenge to users after they complete their first step (typically a link in a password reset email) but before they create their new password. Using this trigger, you can redirect users to an external site, such as a third-party verifier, or challenge them with an additional MFA factor. Users must complete this second challenge in order to update their password.

  * **Note**: You can customize the MFA prompts displayed to users during the password reset flow. To learn more, review [Customize Universal Login Text Prompts.](/docs/customize/login-pages/universal-login/customize-text-elements)

## Custom database connections

When using custom database connections:

* The password reset flow will function properly even if you return errors from the change password script.
* The errors returned in `ValidationErrors` or `WrongUsernameOrPasswordError` will be displayed on the corresponding pages. To learn more, review [Troubleshoot Custom Databases](/docs/authenticate/database-connections/custom-db/error-handling).

## Email verification

After a user clicks the email verification link, they'll be redirected to a page that will confirm that their email is verified. If the default login route is configured, users will be able to click a button and get redirected to it.

## Password autocomplete

Universal Login pages use the [autocomplete attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) for password fields.

On the signup and password reset pages, `autocomplete` is set to `"new-password"`. This signals the password manager to prompt the user to generate a secure, random password. The user has to provide explicit consent to save the password in the password manager.

On the login page `autocomplete` is set to `"current-password"`. The login page automatically fills in the password if it's available in the browser's password manager.

Note that turning off password autocompletion does not increase security:

* Users need to opt-in for saving the password in the browser’s password manager
* Once it’s saved in the password manager, any user with access to the computer can go into the password manager and get the password whether the password is auto-filled on the login screen or not. If users are logged-in to the browser then they are prompted for their password before viewing saved passwords. If not, everyone can see them.
* In the case of Safari, users are asked to enter their Mac password or use Touch ID before the password is completed.

## Implement Universal Login

To learn how to set up your application to use Universal Login, read our [Quickstarts](/docs/quickstarts). Choose the approach that best fits your technologies, and the Quickstarts walk you through the implementation.

## Learn more

* [Configure Default Login Routes](/docs/authenticate/login/auth0-universal-login/configure-default-login-routes)
* [Configure SMS and Voice Notifications for MFA](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-sms-voice-notifications-mfa)
* [Multi-Factor Authentication Factors](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors)
* [Check API Calls](/docs/troubleshoot/authentication-issues/check-api-calls)
* [Check Login and Logout Issues](/docs/troubleshoot/authentication-issues/check-login-and-logout-issues)
* [Troubleshoot Multi-Factor Authentication Issues](/docs/troubleshoot/authentication-issues/troubleshoot-mfa-issues)


# Configure Silent Authentication
Source: https://auth0.com/docs/authenticate/login/configure-silent-authentication

Learn how to keep users logged in to your application using silent authentication.

The [OpenID Connect protocol](/docs/authenticate/protocols/openid-connect-protocol) supports a `prompt=none` parameter on the authentication request that allows applications to indicate that the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip> must not display any user interaction (such as authentication, consent, or <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip>). Auth0 will either return the requested response back to the application, or return an error if the user is not already authenticated or if some type of consent or prompt is required before proceeding.

Use of the [Implicit Flow](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post) in SPAs presents security challenges requiring explicit mitigation strategies. You can use the [Authorization Code Flow with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce) in conjunction with Silent Authentication to renew sessions in SPAs.

<Callout icon="file-lines">
  Recent advancements in user privacy controls in browsers adversely impact the user experience by preventing access to third-party cookies; therefore, browser-based flows must use [Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation), which provides a secure method for using refresh tokens in SPAs while providing end-users with seamless access to resources without the disruption in UX caused by browser privacy technology like ITP.
</Callout>

## Initiate Silent Authentication requests

To initiate a silent authentication request, add the `prompt=none` parameter when you redirect a user to the [`/authorize` endpoint of Auth0's authentication API](https://auth0.com/docs/api/authentication#authorize-application). (The individual parameters on the authentication request will vary depending on the specific needs of your app.)

For example:

<AuthCodeBlock />

The `prompt=none` parameter causes Auth0 to immediately send a result to the specified `redirect_uri` (callback URL) using the specified `response_mode` with one of two possible responses: success or error.

<Callout icon="file-lines">
  Any applicable [rules](/docs/customize/rules) will be executed as part of the silent authentication process.
</Callout>

### Response modes

The `response_mode` parameter determines how Auth0 delivers the authorization response to your application. For silent authentication, you can use:

| Mode          | Delivery Method                    | Use Case                                               |
| ------------- | ---------------------------------- | ------------------------------------------------------ |
| `query`       | Query string (`?code=...`)         | Authorization Code flow with server-side handling      |
| `fragment`    | URL fragment (`#access_token=...`) | Implicit flow (legacy)                                 |
| `web_message` | `postMessage()` API                | **Recommended for SPAs** - no page navigation required |

When using `web_message`, Auth0 renders an HTML page inside a hidden iframe that uses the [HTML5 Web Messaging API](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) to communicate the result back to your application. This allows silent authentication without any visible page redirects or state loss.

<Note>
  To use `response_mode=web_message`, you must add your application's URL to the **Allowed Web Origins** field in your [application settings](https://manage.auth0.com/#/applications). For more details on all response modes, see [OAuth 2.0 Authorization Framework](/docs/authenticate/protocols/oauth#authorization-endpoint).
</Note>

### Successful authentication responses

If the user was already logged in to Auth0 and no other interactive prompts are required, Auth0 will respond exactly as if the user had authenticated manually through the login page. The format of the response depends on the `response_mode` used:

<Tabs>
  <Tab title="web_message">
    When using `response_mode=web_message` with Authorization Code Flow with PKCE (`response_type=code`), Auth0 returns an HTML page that posts the authorization code to your application:

    ```html theme={null}
    <script>
      window.parent.postMessage({
        type: 'authorization_response',
        response: {
          code: 'SplX...GT',
          state: 'your_state_value'
        }
      }, 'https://yourApp.com');
    </script>
    ```

    Your application (or SDK) listens for this message and exchanges the code for tokens. If the user has no valid session, Auth0 posts an error instead:

    ```html theme={null}
    <script>
      window.parent.postMessage({
        type: 'authorization_response',
        response: {
          error: 'login_required',
          error_description: 'Login required',
          state: 'your_state_value'
        }
      }, 'https://yourApp.com');
    </script>
    ```
  </Tab>

  <Tab title="fragment">
    When using `response_mode=fragment` (default for Implicit Flow with `response_type=id_token token`), Auth0 redirects with tokens in the URL fragment:

    ```text theme={null}
    GET https://yourApp.com/callback
        #id_token=eyJhbG...&
        access_token=eyJhbG...&
        state=your_state_value&
        expires_in=86400
    ```
  </Tab>

  <Tab title="query">
    When using `response_mode=query` (default for Authorization Code Flow with `response_type=code`), Auth0 redirects with the code in the query string:

    ```text theme={null}
    GET https://yourApp.com/callback
        ?code=SplX...GT&
        state=your_state_value
    ```
  </Tab>
</Tabs>

These responses are identical in format to a login performed directly without the `prompt=none` parameter. The only difference is that with `prompt=none`, the response is immediate without any user interaction.

### Error responses

If the user was not logged in via <Tooltip href="/docs/glossary?term=Single+Sign-on">Single Sign-on</Tooltip> (SSO) or their SSO session had expired, Auth0 returns an error using the same `response_mode`. For redirect-based modes (`fragment` or `query`):

```text theme={null}
GET https://your_callback_url/
    #error=ERROR_CODE&
    error_description=ERROR_DESCRIPTION&
    state=...
```

For `web_message` mode, the error is posted via `postMessage()` as shown in the example above.

The possible values for `ERROR_CODE` are defined by the [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html#AuthError):

<table>
  <thead>
    <tr>
      <th>Response</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>login\_required</code></td>
      <td>The user was not logged in at Auth0, so silent authentication is not possible. This error can occur based on the way the tenant-level <strong>Log In Session Management</strong> settings are configured; specifically, it can occur after the time period set in the <strong>Require log in after</strong> setting. See <a href="/docs/manage-users/sessions/configure-session-lifetime-settings">Configure Session Lifetime Settings</a> for details.</td>
    </tr>

    <tr>
      <td><code>consent\_required</code></td>
      <td>The user was logged in at Auth0, but needs to give consent to authorize the application.</td>
    </tr>

    <tr>
      <td><code>interaction\_required</code></td>
      <td>The user was logged in at Auth0 and has authorized the application, but needs to be redirected elsewhere before authentication can be completed; for example, when using a <a href="/docs/customize/rules/redirect-users">redirect rule</a>.</td>
    </tr>
  </tbody>
</table>

If any of these errors are returned, the user must be redirected to the Auth0 login page without the `prompt=none` parameter to authenticate.

## Renew expired tokens

You can make a silent authentication request to get new tokens as long as the user still has a valid session at Auth0. The [`checkSession` method from auth0.js](/docs/libraries/auth0js) uses a silent token request in combination with `response_mode=web_message` for SPAs so that the request happens in a hidden iframe. With SPAs, Auth0.js handles the result processing (either the token or the error code) and passes the information through a callback function provided by the application. This results in no UX disruption (no page refresh or lost state).

<Callout icon="file-lines">
  See [Renew Tokens When Using Safari](/docs/troubleshoot/authentication-issues/renew-tokens-when-using-safari) for other important limitations and workarounds with the Safari browser.
</Callout>

### Access Token expiration

<Tooltip href="/docs/glossary?term=Access+Tokens">Access Tokens</Tooltip> are opaque to applications. This means that applications are unable to inspect the contents of Access Tokens to determine their expiration date.

There are two options to determine when an Access Token expires:

* Read the `expires_in` response parameter returned by Auth0.
* Ignore expiration dates altogether. Instead, renew the Access Token if your API rejects a request from the application (such as with a 401).

In the case of the [Implicit Flow](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post), the `expires_in` parameter is returned by Auth0 as a hash parameter following a successful authentication. In the [Authorization Code Flow with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce), it is returned to the backend server when performing the authorization code exchange.

The `expires_in` parameter indicates how many seconds the Access Token will be valid for, and can be used to anticipate expiration of the Access Token.

### Error response

You may receive the `timeout` error response which indicates that timeout during executing `web_message` communication has occurred. This error is typically associated with fallback to cross-origin authentication. To resolve, make sure to add all of the URLs from which you want to perform silent authentication in the **Allowed Web Origins** field for your Application using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

## Poll with checkSession()

In some multi-application scenarios, where Single Logout is desired (a user logging out of one application needs to be logged out of other applications), an application can be set up to periodically poll Auth0 using `checkSession()` to see if a session exists. If the session does not exist, you can then log the user out of the application. The same polling method can be used to implement silent authentication for a Single Sign-on (SSO) scenario.

The poll interval between checks to `checkSession()` should be at least 15 minutes between calls to avoid any issues in the future with rate limiting of this call.

## Silent authentication with Multi-factor Authentication

In some scenarios, you may want to avoid prompting the user for [Multi-factor Authentication (MFA)](/docs/secure/multi-factor-authentication) each time they log in from the same browser. To do this, set up a rule so that MFA occurs only once per session. This is useful when performing silent authentication (`prompt=none`) to renew short-lived Access Tokens in a SPA during the duration of a user's session without having to rely on setting `allowRememberBrowser` to `true`.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const authMethods = event.authentication?.methods || []

  const completedMfa = !!authMethods.find((method) => method.name === 'mfa')

  if (!completedMfa) {
    api.multifactor.enable('any', { allowRememberBrowser: true })
  }
};
```

To learn more, see [Change Authentication Request Frequency](/docs/secure/multi-factor-authentication/customize-mfa).

## Learn more

* [Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation)
* [Configure Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/configure-refresh-token-rotation)
* [Troubleshoot Invalid Token Errors](/docs/troubleshoot/basic-issues/invalid-token-errors)
* [Check API Calls](/docs/troubleshoot/authentication-issues/check-api-calls)
* [Troubleshoot Multi-Factor Authentication Issues](/docs/troubleshoot/authentication-issues/troubleshoot-mfa-issues)


# Cross-Origin Authentication
Source: https://auth0.com/docs/authenticate/login/cross-origin-authentication

An explanation of cross-origin authentication in Auth0 and its compatibility with browsers

When authentication requests are made from your application (via the Lock widget or a custom login form) to Auth0, the user's credentials are sent to a domain that differs from the one that serves your application. Collecting user credentials in an application served from one origin and then sending them to another origin can present certain security vulnerabilities, including the possibility of a phishing attack.

Auth0 provides a cross-origin authentication flow that uses third-party cookies. The use of third-party cookies allows Lock and Auth0's backend to perform the necessary checks to allow for secure authentication transactions across different origins. This helps to prevent phishing when creating a <Tooltip href="/docs/glossary?term=Single+Sign-on">Single Sign-on</Tooltip> experience with the Lock widget or a custom login form in your application and it also helps to create a secure login experience even if SSO is not the goal.

Cross-origin authentication is not recommended and is only necessary when authenticating against a directory using a username and password. Social <Tooltip href="/docs/glossary?term=IdPs">IdPs</Tooltip> and enterprise federation use a different mechanism, redirecting via standard protocols like <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect and <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip>. Additionally, cross-origin authentication is only applicable to embedded login on the web (using Lock or auth0.js). Native applications using embedded login make use of the standard <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> <Tooltip href="/docs/glossary?term=Token+endpoint">Token endpoint</Tooltip>.

## Limitations

Because cross-origin authentication is achieved using third-party cookies, disabling third-party cookies will make cross-origin authentication fail. Some browsers, such as the newest version of Firefox, disable third-party cookies by default, meaning that cross-origin authentication will not work for users on Firefox. The only way to make embedded login work for Firefox users is to use a <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip>, as described below.

There are two approaches you can follow to remediate the issue:

* Enable a [Custom Domain](/docs/customize/custom-domains) on your tenant and host your web application in a domain that has the same top-level domain as your Auth0 custom domain. For example, you host an application at `https://northwind.com` and set your Auth0 custom domain as `https://login.northwind.com`. This way the cookies are no longer third-party (because both your Auth0 tenant and your application are using the same top-level domain), and thus, are not blocked by browsers.
* Create and link a cross-origin verification page that will make cross-origin authentication work in a limited number of browsers even with third-party cookies disabled.

## Learn more

* [Configure Cross-Origin Resource Sharing](/docs/get-started/applications/set-up-cors)
* [Hosted Login vs. Embedded Login](/docs/authenticate/login/universal-vs-embedded-login)
* [Auth0 Universal Login](/docs/authenticate/login/auth0-universal-login)


# Embedded Login
Source: https://auth0.com/docs/authenticate/login/embedded-login

Describes Auth0 Embedded Login used to log users directly into your application, transmitting credentials to the Auth0 server.

Embedded Login allows your users to log directly into your application and transmit their credentials to the Auth0 server for authentication. We do not recommend using Embedded Login. To learn more, read [Centralized Universal Login vs. Embedded Login](/docs/authenticate/login/universal-vs-embedded-login).

If you decide to use Embedded Login, you must [configure your application for Cross-Origin Resource Sharing](/docs/get-started/applications/set-up-cors) and should [configure a custom domain](/docs/customize/custom-domains). You can then implement the [Lock SDK](/docs/libraries/lock) or [Auth0.js SDK](/docs/libraries/auth0js) within your application, or call the [Auth0 Authentication API](https://auth0.com/docs/api/authentication) directly.

Auth0 supports Embedded Login with <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> connections for multiple application types:

* [Embedded Passwordless Login in Native Applications](/docs/authenticate/passwordless/implement-login/embedded-login/native)
* [Embedded Passwordless Login in Regular Web Applications](/docs/authenticate/passwordless/implement-login/embedded-login/webapps)
* [Embedded Passwordless Authentication for Single-Page Apps](/docs/authenticate/passwordless/implement-login/embedded-login/spa)

## Learn more

* [Lock for Web](/docs/libraries/lock)
* [Auth0.js v9 Reference](/docs/libraries/auth0js)
* [Cross-Origin Authentication](/docs/authenticate/login/cross-origin-authentication)


# Logout
Source: https://auth0.com/docs/authenticate/login/logout

Describes how logout works with Auth0.

<Card title="Overview">
  Key Concepts

  * Review different session layers.
  * Learn how to redirect users after logout.
</Card>

You can log a user out of the Auth0 session and (optionally) from the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> (IdP) session. When you're implementing the logout functionality, there are typically three-session layers you need to consider:

1. **Application Session Layer**: The first layer is the session inside your application. Though your application uses Auth0 to authenticate users, you'll still need to track that the user has logged in to your application. In a regular web application, you achieve this by storing information inside a cookie. [Log users out of your applications](/docs/authenticate/login/logout/log-users-out-of-applications) by clearing their sessions. You should handle the application session in your application.
2. **Auth0 Session Layer**: Auth0 also maintains a session for the user and stores their information inside a cookie. The next time a user is redirected to the Auth0 Lock screen, the user's information will be remembered. [Log users out of Auth0](/docs/authenticate/login/logout/log-users-out-of-auth0) by clearing the Single Sign-on (SSO) cookie.
3. **Identity Provider Session Layer**: The last session layer is the identity provider layer (for example, Facebook or Google). When users attempt to sign in with any of these providers and they are already signed into the provider, they will not be prompted again to sign in. The users may be asked to give permission to share their information with Auth0 and, in turn, your application. It is not necessary to log the users out of this session layer, but you can force the logout. (For more information, see [Log Users Out of Identity Providers](/docs/authenticate/login/logout/log-users-out-of-idps) and [Log Users Out of SAML Identity Providers](/docs/authenticate/login/logout/log-users-out-of-saml-idps).)

## Redirect users after logout

After users log out, you can [redirect users](/docs/authenticate/login/logout/redirect-users-after-logout) to a specific URL. You need to register the redirect URL in your tenant or application settings. Auth0 only redirects to URLs from the allow list after logout. If you need different redirects for each application, you can add the URLs to your allow list in your application settings.

## Learn more

* [Log Users Out of Applications](/docs/authenticate/login/logout/log-users-out-of-applications)
* [Log Users Out of Auth0 with OIDC Endpoint](/docs/authenticate/login/logout/log-users-out-of-auth0)
* [Log Users Out of Identity Providers](/docs/authenticate/login/logout/log-users-out-of-idps)
* [Log Users Out of SAML Identity Providers](/docs/authenticate/login/logout/log-users-out-of-saml-idps)
* [Redirect Users with Alternative Logout](/docs/authenticate/login/logout/redirect-users-after-logout)
* [Check Login and Logout Issues](/docs/troubleshoot/authentication-issues/check-login-and-logout-issues)


# OIDC Back-Channel Logout
Source: https://auth0.com/docs/authenticate/login/logout/back-channel-logout

Describes Auth0's OIDC Back-Channel Logout feature.

Auth0 supports the [OpenID Connect Back-Channel Logout 1.0 specification](https://openid.net/specs/openid-connect-backchannel-1_0.html#Backchannel) in all tenants with an Enterprise plan subscription.

This specification leverages the session ID (`sid`) included in <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip> and the Logout Tokens to coordinate session termination via back-channel communication. Different session IDs represent individual sessions of a user agent or device in your tenant. Logout Tokens identify the end-user and session to logout.

## Back-channel communications

To use Back-Channel Logout, an application must expose a Back-Channel Logout URI, reachable from the tenant server, where the application expects to receive the requests with the Logout Token. When an application receives this request, it is compelled to clear the local session state matching the claims in the token.

<Callout icon="file-lines">
  For back-channel logout to work, applications must be able to receive back-channel communications.
</Callout>

### Tokens in OIDC Back-Channel Logout communications

Applications cannot rely on <Tooltip href="/docs/glossary?term=session+cookies">session cookies</Tooltip> to determine which session to terminate when communications are performed via the back-channel. Rather, the service depends on a shared session identifier (`sid`) on ID and Logout Tokens.

When end-users successfully authenticate with Auth0 during login, the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip> issues access and ID tokens. Logout tokens will be generated when a session is destroyed, such as through a logout action or session revocation. Both ID and Logout tokens contain the claims your application needs to facilitate the Back-Channel Logout workflow. To learn more about claims, read [JSON Web Token Claims](/docs/secure/tokens/json-web-tokens/json-web-token-claims).

<Frame>
  <img alt="Workflow for back-channel logout" />
</Frame>

1. Login - During user authentication, the Auth0 tenant adds the `sid` to the ID token.
2. Login - The application stores the received session identifier in its own session store and associates it with the application-specific session.
3. Logout - The IdP calls the pre-registered logout callback URL and posts the Logout Token to this endpoint. The token contains the `user_id` (`sub`) and the `sid` along with other parameters.
4. Logout - The application’s backend needs to validate the Logout Token as per OIDC spec and extract the `sid`. Then the backend can use this token to find the session associated with the identifier and terminate it as necessary.

<Callout icon="file-lines">
  The expected response is `HTTP 200` for successful logout. If you receive `HTTP 400`, an incorrect or misunderstood request, you can use our tips to troubleshoot. To learn more, read [Configure Back-Channel Logout](/docs/authenticate/login/logout/back-channel-logout/configure-back-channel-logout).
</Callout>

### How it works

The sample use case demonstrates how Back-Channel Logout works with more than one application:

<Frame>
  <img alt="Back-channel logout multiple app use case" />
</Frame>

1. During application configuration, Application A registers a Back-Channel Logout URI with Auth0.
2. During application configuration, Application B registers a Back-Channel Logout URI with Auth0.

   <Callout icon="file-lines">
     OIDC Back-Channel Logout URLs must:

     * Be accessible from the IdP
     * Use endpoints with TLS encryption
     * [Validate logout tokens](https://openid.net/specs/openid-connect-backchannel-1_0.html#Validation)
   </Callout>
3. During end-user login, a user authenticates with Auth0 to access Application A.
4. Auth0 sends an ID token with `sid` to Application A. To learn more, read [ID Token Structure](/docs/secure/tokens/id-tokens/id-token-structure).
5. User authenticates with Auth0 to access Application B.
6. Auth0 sends an ID token with the same `sid` to Application B. Your application should store the session information.
7. During logout, Application A or other entities initiate logout on the front-channel.
8. Auth0 terminates the Auth0 session layer via session cookie.
9. Auth0 calls Application A’s Back-Channel Logout URI and posts the Logout Token.
10. Application A validates the Logout Token and terminates the session.
11. Auth0 calls Application B’s Back-Channel Logout URI and posts the Logout Token.
12. Application B validates the Logout Token and terminates the session.

#### Sample token

Your application must be able to parse and validate <Tooltip href="/docs/glossary?term=JWTs">JWTs</Tooltip> to use as Logout Tokens with Auth0. To learn more, read [Validate JSON Web Tokens](/docs/secure/tokens/json-web-tokens/validate-json-web-tokens).

Once your application validates and decodes your token, the contents are similar to the example below:

```json JSON lines theme={null}
{
  "iss": "https://artex-dev.eu.auth0.com/",
  "sub": "auth0|602e93db83fa6f00749a23e6",
  "aud": "TuhNLv7ulXD3RfyLlSMbOvszzwJJFPpO",
  "iat": 1698160928,
  "exp": 1698161048,
  "jti": "44a91215-dfb4-4dfe-a1eb-fcafa911deba",
  "events": {
    "http://schemas.openid.net/event/backchannel-logout": {}
  },
  "trace_id": "81b336a94a4a5707",
  "sid": "375UIp_ID5mCTClIeBEHpXfGwq51tF_L"
}
```

### Auth0 SDKs

A full example and production code is already included under the **Back-Channel Logout Example** section of our [express-openid-connect SDK](https://github.com/auth0/express-openid-connect/blob/master/EXAMPLES.md#11-back-channel-logout).

## Implementation examples

### Session storage

The session storage example is built in Node (Express) and based on the [Express OpenID Connect Web App Sample](https://github.com/auth0-samples/auth0-express-webapp-sample/tree/master/01-Login).

In your application sessions tab, expose the route you configured to receive the Logout Token. Validate the token and terminate the user session.

<Callout icon="file-lines">
  This example uses an in-memory session store for demonstration purposes.
</Callout>

**routes/index.js**

```javascript JavaScript lines expandable theme={null}
const express = require('express');
const router = express.Router();
const { requiresAuth } = require('express-openid-connect');

// middleware to validate the logout token
const requiresValidLogoutToken = require('../middlewares/validateLogoutToken');

// helper function to delete user sessions
const deleteUserSessions = require('../utils/sessions');

// new route to receive backchannel logout tokens
// must be configured in the Application -> Sessions tab 
// in the Auth0 Management Dashboard
router.post(
  '/backchannel-logout',
  requiresValidLogoutToken,
  function (req, res, next) {
    // at this point the logout token is valid, checked by requiresValidLogoutToken middleware
    // you can access it from the request object: req.logoutToken

    // delete user session so the user gets logged out
    deleteUserSessions(
      req.app.locals.sessionStore,
      req.logoutToken.sub,
      req.logoutToken.sid
    );

    res.sendStatus(200);
  }
);

router.get('/', function (req, res, next) {
  res.render('index', {
    title: 'Auth0 Webapp sample Nodejs',
    isAuthenticated: req.oidc.isAuthenticated(),
    headline: process.env.APP_NAME,
    backgroundColor: process.env.BACKGROUND_COLOR,
    baseURL: process.env.BASE_URL,
  });
});

router.get('/profile', requiresAuth(), function (req, res, next) {
  res.render('profile', {
    userProfile: JSON.stringify(req.oidc.user, null, 2),
    title: 'Profile page',
    headline: process.env.APP_NAME,
    backgroundColor: process.env.BACKGROUND_COLOR,
    baseURL: process.env.BASE_URL,
  });
});

module.exports = router;
```

**middlewares/validateLogoutToken.js**

```javascript JavaScript lines expandable theme={null}
// This middleware validates the logout token as defined here:
// https://openid.net/specs/openid-connect-backchannel-1_0.html#Validation

const jose = require('jose');

async function requiresValidLogoutToken(req, res, next) {

  // get remote key set for token verification
  const JWKS = jose.createRemoteJWKSet(
    new URL(process.env.ISSUER_BASE_URL + '/.well-known/jwks.json')
  );

  const logoutToken = req.body.logout_token;

  if (!logoutToken) {
    res.status(400).send('Need logout token');
  }

  try {
    const { payload, protectedHeader } = await jose.jwtVerify(
      logoutToken,
      JWKS,
      {
        issuer: process.env.ISSUER_BASE_URL + '/',
        audience: process.env.CLIENT_ID,
        typ: 'JWT',
        maxTokenAge: '2 minutes',
      }
    );

    // Verify that the Logout token contains a sub claim, a sid claim, or both
    if (!payload.sub && !payload.sid) {
      res
        .status(400)
        .send(
          'Error: Logout token must contain either sub claim or sid claim, or both'
        );
    }

    // Verify that the logout token contains an events claim
    // whose value is a JSON object containing the member name http://schemas.openid.net/event/backchannel-logout
    if (!payload.events['http://schemas.openid.net/event/backchannel-logout']) {
      res
        .status(400)
        .send(
          'Error: Logout token must contain events claim with correct schema'
        );
    }

    // Verify that the Logout token does not contain a nonce claim.
    if (payload.nonce) {
      res
        .status(400)
        .send('Error: Logout token must not contain a nonce claim');
    }

    // attach valid logout token to request object
    req.logoutToken = payload;

    // token is valid, call next middleware
    next();
  } catch (error) {
    res.status(400).send(`Error:  ${error.message}`);
  }
}

module.exports = requiresValidLogoutToken;
```

### Logout token store

A common approach for token storage is to define a logout store as an alternative to the session store model. Your application(s) keeps a collection of Logout Tokens in the persistence level.

Wherever the application wants to check its authentication status, it queries the Logout Token store to find if its session is still active. The logout store flushes obsolete information regularly to keep only the necessary information.

<Frame>
  <img alt="Logout Token Store" />
</Frame>

## Security considerations

Back-Channel Logout Tokens are delivered over the internet, therefore the callback endpoints receiving them must follow the best practices to ensure reliable and secure operation. The recommendations list below is not exhaustive and you must always consider the specific deployment and operational situations to adapt accordingly. In the list below, any apps that handle the Back-Channel Logout Tokens are referenced as “apps”.

* Apps must have the ability to store the session ID (`sid` claim) received during user login in order to retrieve them later when receiving a Back-Channel Logout token.
* Apps must verify any received tokens as per [JWT validation best practices](/docs/secure/tokens/json-web-tokens/validate-json-web-tokens).
* Apps must accept tokens issued only by trusted tenants. A malicious actor can attempt to send tokens issued by other Auth0 tenants - such attempts must be rejected.
* Apps must accept tokens only when they contain a `sid` value (session ID) that the app recognizes. Tokens containing an invalid session ID (being it expired or unrecognized) must be rejected.
* Apps must expose the callback endpoints only via TLS. Unencrypted communication channels are not allowed.
* Apps are recommended to accept requests only from the published list of [outbound IP addresses](/docs/secure/security-guidance/data-security/allowlist).
* Apps are recommended to follow the general best practices in terms of monitoring, logging and rate limiting - however details of these are outside of scope of this document.
* Apps are recommended to regularly clean stale or expired sessions.
* Any changes in the endpoint address must be synchronised with the tenant configuration in order to ensure the Logout Tokens are always delivered to the correct Back-Channel Logout Callback URL.

## Learn more

* [Configure OIDC Back-Channel Logout](/docs/authenticate/login/logout/back-channel-logout/configure-back-channel-logout)
* [Check Login and Logout Issues](/docs/troubleshoot/authentication-issues/check-login-and-logout-issues)
* [Log Users Out of SAML Identity Providers](/docs/authenticate/login/logout/log-users-out-of-saml-idps)
* [Log Users Out of Auth0 with OIDC Endpoint](/docs/authenticate/login/logout/log-users-out-of-auth0)
* [Log Users Out of Applications](/docs/authenticate/login/logout/log-users-out-of-applications)
* [Log Users Out of Identity Providers](/docs/authenticate/login/logout/log-users-out-of-idps)


# Configure OIDC Back-Channel Logout
Source: https://auth0.com/docs/authenticate/login/logout/back-channel-logout/configure-back-channel-logout

Describes how to configure OIDC back-channel logout with your Auth0 services.

<Card title="Before you start">
  To use Back-Channel Logout, your application must meet the following requirements:

  * Your OIDC Back-Channel Logout URI endpoint must be exposed over the internet for your Auth0 tenant to access.
  * Production-ready applications must use TLS. To learn more, read [TLS (SSL) Versions and Ciphers](/docs/customize/custom-domains/self-managed-certificates/tls-ssl).
  * The application must be able to store the provided session identifier (`sid`) and associate it with the user sessions it creates. We recommend production applications use durable session storage.
  * The application must be able to retrieve an existing session by the `sid` during the logout process without using client-side cookies. Cookies exist within the browser and are inaccessible to the logout callback endpoint.
</Card>

## Availability

OIDC Back-Channel Logout is available for all Enterprise plan customers. You should check the OIDC standard `/.well-known/*` metadata endpoint to determine if your application meets the requirements.

```json lines theme={null}
GET https://acme.eu.auth0.com/.well-known/openid-configuration

HTTP 200
{ ..., "backchannel_logout_supported": true, 
  "backchannel_logout_session_supported": true }
```

## Back-Channel Logout restrictions

Back-Channel Logout URLs are called on publicly-exposed endpoints and must adhere to certain restrictions:

1. You must use the HTTPS protocols. Unencrypted HTTP or other protocols are not permitted.
2. You must not use Auth0 subdomains. Some Auth0 subdomains are:

   * auth0.com
   * auth0app.com
   * webtask.io
   * webtask.run
3. We do not recommend using IP addresses without domains. IP addresses must be public IPs to use Back-Channel Logout. IP addresses from internal, reserved, or loopback ranges are not permitted.

## Configure Auth0

Register your application to receive Logout Tokens via <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

<Tabs>
  <Tab title="Auth0 Dashboard">
    #### Subscribe applications

    1. Navigate to [**Auth0 Dashboard > Applications**](https://manage.auth0.com/#/applications).
    2. Choose the application you want to register.
    3. Select the **Settings** tab.
    4. Under the **OpenID Connect Back-Channel Logout > Back-Channel Logout URI**, add the application logout URI that will receive the logout\_tokens
    5. Once complete, select **Save Changes**.

       <Frame>
         <img alt="Auth0 Dashboard > Applications > Settings" />
       </Frame>

    #### Unsubscribe applications

    Unsubscribing your application stops the service from tracking new logins and sending logout events. The service discards pending logout events once your application is unsubscribed.

    To unsubscribe your application, delete the back-channel logout URL.

    1. Navigate to [Auth0 Dashboard > Applications](http://manage.auth0.com/#/applications).
    2. Choose the application you want to register.
    3. Select the **Settings** tab.
    4. Under the **OpenID Connect Back-Channel Logout > Back-Channel Logout URI**
    5. Remove the back-channel URL.
    6. Once complete, select **Save Changes**.

       <Frame>
         <img alt="Auth0 Dashboard > Applications > Settings" />
       </Frame>

    For auditing purposes, the service always logs subscribing or unsubscribing back-channel logout URLs as `API Operation Event` in Auth0 tenant logs. To learn more, read [Logs](/docs/deploy-monitor/logs).
  </Tab>

  <Tab title="Management API">
    #### Subscribe application

    Add the `oidc_logout` property to `PATCH` a client through the Management API:

    ```bash cURL lines theme={null}
    PATCH /api/v2/clients/{id}
    "oidc_logout": {
      "backchannel_logout_urls": ["http://acme.eu.auth0.com/events"]
    }
    ```

    <Callout icon="file-lines">
      The request can include the other application parameters.
    </Callout>

    #### Unsubscribe application

    Remove the `oidc_logout` parameter:

    ```bash cURL lines theme={null}
    PATCH https://acme.eu.auth0.com/api/v2/clients/{id}
    {
      "oidc_logout": {
        "backchannel_logout_urls": []
      }
    }
    ```
  </Tab>
</Tabs>

## Configure your application

Once you have configured Back-Channel Logout via the Auth0 Dashboard or Management API, configure your application to use the service based on the technology or framework.

1. Implement end-user authentication according to your application type.

   1. End-users should be able to log in to the application, and a session should be created.
   2. An ID token should be issued from Auth0 and should be accessible in the application backend for further processing.
2. Extend the login process to save the `sid` and, optionally, sub claims after the ID token is validated.

   1. These claims must be saved against the current application session.
   2. The session management functions should be able to retrieve a specific session by the `sid` value.
3. Configure the Back-Channel Logout endpoint:

   1. The endpoint must process only `HTTP POST` requests.
   2. Extract the `logout_token` parameter and validate it as a regular JWT according to the spec.
   3. Verify that the token contains an events claim with a JSON object value and a member named `http://schemas.openid.net/event/backchannel-logout`.
   4. Verify that the token contains the `sid` and/or `sub` claims.
   5. Verify that the token does NOT contain the `nonce` claim. This is required to prevent abuse by distinguishing the Logout Token from the ID token.
   6. Once the token is validated, retrieve the session corresponding to the received `sid` and/or `sub` value and terminate it. The exact application session termination process depends on the implementation details. For example, this event may need to be communicated to the front-end.

## OIDC Back-Channel Logout request example

Coded token payload:

```bash cURL lines theme={null}
POST /backchannel-logout HTTP/1.1
Host: rp.example.org
Content-Type: application/x-www-form-urlencoded

logout_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImdwY3ZFT0FPREE2T3pXRmw3ODVxbCJ9.eyJpc3MiOiJodHRwczovL2FydGV4LWRldi5ldS5hdXRoMC5jb20vIiwic3ViIjoiYXV0aDB8NjAyZTkzZGI4M2ZhNmYwMDc0OWEyM2U2IiwiYXVkIjoiVHVoTkx2N3VsWEQzUmZ5TGxTTWJPdnN6endKSkZQcE8iLCJpYXQiOjE2OTgxNjA5MjgsImV4cCI6MTY5ODE2MTA0OCwianRpIjoiNDRhOTEyMTUtZGZiNC00ZGZlLWExZWItZmNhZmE5MTFkZWJhIiwiZXZlbnRzIjp7Imh0dHA6Ly9zY2hlbWFzLm9wZW5pZC5uZXQvZXZlbnQvYmFja2NoYW5uZWwtbG9nb3V0Ijp7fX0sInRyYWNlX2lkIjoiODFiMzM2YTk0YTRhNTcwNyIsInNpZCI6IjM3NVVJcF9JRDVtQ1RDbEllQkVIcFhmR3dxNTF0Rl9MIn0.aEoAL_U-EPlf3f7Fup-bu7Yv0S0GOnrkL8Njd6j6UNqZcr5VrWWFf3CWvkRi7Cm6wMgU2qIMhb7643ca8-ajR7zHlMu0Z3r-gfd2D1xudKLyUSC3v2D5WJZz5I8xMZ_LWtIN2W3l4SQFO9MgK_7F3x0WIWXo9KPC9tgOaOLPnsiv__MutM1ZakoCsJPddl5gVM4TYtHOue6WM7SOXZNa3SSiv57YQOX2KNCL7sWmZp_J1OXKy8lsgkNFqiOVwu39p4sgjKYEXQU0G-I0yY_aeNbnlnxFG6OuxaDt_zwg6AvKglLSNGqrrvzy4GsYJi5HMGZ1GsSs7rQLg7Iuu6JM-A
```

<Callout icon="file-lines">
  Token expiration is 2 minutes (120 sec).
</Callout>

Decoded token payload:

```json JSON lines theme={null}
{
   "iss": "https://artex-dev.eu.auth0.com/",
   "sub": "auth0|602e93db83fa6f00749a23e6",
   "aud": "TuhNLv7ulXD3RfyLlSMbOvszzwJJFPpO",
   "iat": 1698160928,
   "exp": 1698161048,
   "jti": "44a91215-dfb4-4dfe-a1eb-fcafa911deba",
   "events": {
         "http://schemas.openid.net/event/backchannel-logout": {}
   },
   "trace_id": "81b336a94a4a5707",
   "sid": "375UIp_ID5mCTClIeBEHpXfGwq51tF_L"
}
```

## Expected responses

* **HTTP 200**:  Confirms user logout from the specific application.
* **HTTP 400**: Indicates an incorrect request. The request is not understood or the token failed validation. Auth0 records the problem in tenant logs but does not attempt further requests for this specific session.

## Troubleshoot issues

### Application did not receive the logout events

If your application did not receive a logout request after a logout event.

1. Make sure your application has a Back-Channel Logout URL registered in Auth0 Dashboard.
2. Ensure the Back-Channel Logout URL is reachable from the Auth0 tenant.
3. Ensure a valid session is established. The end-user must log in to your specific application via Auth0.

   <Callout icon="file-lines">
     Applications receive logout events only if end-users log in to that specific app with Auth0.  If the end-user logs in to other applications, logout events do not trigger.
   </Callout>
4. Check Auth0 tenant logs for messages about unsuccessful logout message delivery.
5. Make sure the logout is triggered via the standard logout endpoint. Other events do not trigger the logout events.
6. If possible, check for blocked requests on the web server and/or application firewall logs.

#### I can't find OIDC Back-Channel Logout tenant logs

This feature will be gradually released to all tenants starting 3 October 2023. You may still receive [tenant log event codes](/docs/deploy-monitor/logs/log-event-type-codes) `sslo` for `oidc_backchannel_logout_succeeded` or `fslo` for `oidc_backchannel_logout_failed`.

### Client app cannot verify the received Logout Token

If the transaction still fails with a 400 error:

1. Check if the token is a standard base64-encoded JWT. Some web servers may truncate long parameters. To learn more, read [Signing Algorithms](/docs/get-started/applications/signing-algorithms).
2. If possible, capture a token and verify that it’s a JWT. Use a verified source, like [JWT.IO](http://jwt.io).
3. Make sure the verification function fetches the tenant signing key dynamically via [JSON Web Key Sets](/docs/secure/tokens/json-web-tokens/json-web-key-sets) (JWKS).

   <Callout icon="file-lines">
     We do not recommend hardcoding a static key. If your configuration requires the static key to be hardcoded, ensure the configuration contains the latest public key from the Auth0 tenant.
   </Callout>

### Response Timeout Errors

Auth0 will wait five seconds for the application OIDC Back-Channel Logout URL to respond. After this time, it will record a "Failed OIDC Back-Channel Logout request" in the tenant logs with an empty response description.

## Learn more

* [Check Login and Logout Issues](/docs/troubleshoot/authentication-issues/check-login-and-logout-issues)
* [Log Users Out of Auth0 with OIDC Endpoint](/docs/authenticate/login/logout/log-users-out-of-auth0)
* [Log Users Out of Applications](/docs/authenticate/login/logout/log-users-out-of-applications)
* [Log Users Out of Identity Providers](/docs/authenticate/login/logout/log-users-out-of-idps)


# OIDC Back-Channel Logout Initiators
Source: https://auth0.com/docs/authenticate/login/logout/back-channel-logout/oidc-back-channel-logout-initiators

Learn how OIDC Back-Channel Logout Initiators work and how to configure them for your application(s).

OIDC Back-Channel Logout Initiators allow you to remotely log out users from their applications based on session termination events. OIDC Back-Channel Logout Initiators work across protocols—for example, an <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>-initiated (IdP-initiated) <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> logout request—and are unaffected by third-party cookie restrictions.

This feature is an extension to the standard OIDC back-channel specification. You can configure it to initiate an OIDC Back-Channel Logout request for specific session termination events, such as a password change or session expiration, or for all session termination events.

Administrators can enable this feature for specific applications with the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## How OIDC Back-Channel Logout Initiators work

Initiators bind an OIDC Back-Channel Logout response to a session termination event. They capture the event and use it to trigger an OIDC logout token in all applications associated with the given session.

<Callout icon="file-lines">
  Initiators do not control session management in your tenant, including session termination events.
</Callout>

The following diagram illustrates how an OIDC Back-Channel Logout Initiator works for a password change event:

<Frame>
  <img alt="" />
</Frame>

## Configure OIDC Back-Channel Logout Initiators

You can configure OIDC Back-Channel Logout Initiators with the Auth0 Management API.

### Management API

You can configure the OIDC Back-Channel Logout Initiators for an application with the Management API by using the [Update a Client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) endpoint.

1. Get an [Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the `update:clients` scope.
2. Call the [Update a Client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) endpoint with the appropriate configuration data in the payload. For example, to log out an application after a password change event, provide the following:

<AuthCodeBlock />

#### Properties

The `backchannel_logout_initiators` object supports the following properties:

<table>
  <thead>
    <tr>
      <th><strong>Property</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Required?</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Supported values</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>mode</code></td>
      <td>string</td>
      <td>Required</td>
      <td>Configuration method for enabling initiators.</td>
      <td><code>custom</code>, <code>all</code></td>
    </tr>

    <tr>
      <td><code>selected\_initiators</code></td>
      <td>array</td>
      <td>Required if <code>mode</code> is <code>custom</code></td>
      <td>List of initiators to enable.</td>
      <td><code>rp-logout</code>, <code>idp-logout</code>, <code>password-changed</code>, <code>session-expired</code>, <code>session-revoked</code>, <code>account-deleted</code>, <code>email-identifier-changed</code></td>
    </tr>
  </tbody>
</table>

##### mode property

The `mode` property determines the configuration method for enabling initiators.

By default, it is set to `custom`, which allows you to specify which initiators you want to enable. If you want your application to logout anytime the IdP session ends, set it to `all`.

The `mode` property supports the following values:

<table>
  <thead>
    <tr>
      <th><strong>Value</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>custom</code></td>
      <td>Enables only the initiators listed in the <code>selected\_initiators</code> array.</td>
    </tr>

    <tr>
      <td><code>all</code></td>
      <td>Automatically enables all current and future initiators.</td>
    </tr>
  </tbody>
</table>

##### selected\_initiators property

The `selected_initiators` property contains the list of initiators to be enabled for the given application.

The `selected_initiators` property supports the following values:

<table>
  <thead>
    <tr>
      <th><strong>Value</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>rp-logout</code></td>
      <td>Request was initiated by a relying party (RP).</td>
    </tr>

    <tr>
      <td><code>idp-logout</code></td>
      <td>Request was initiated by an external identity provider (IdP).</td>
    </tr>

    <tr>
      <td><code>password-changed</code></td>
      <td>Request was initiated by a password change.</td>
    </tr>

    <tr>
      <td><code>session-expired</code></td>
      <td>Request was initiated by session expiration.</td>
    </tr>

    <tr>
      <td><code>session-revoked</code></td>
      <td>Request was initiated by session deletion.</td>
    </tr>

    <tr>
      <td><code>account-deleted</code></td>
      <td>Request was initiated by an account deletion.</td>
    </tr>

    <tr>
      <td><code>email-identifier-changed</code></td>
      <td>Request was initiated by an email identifier change.</td>
    </tr>
  </tbody>
</table>

#### Examples

##### Subscribe an application to all current and future initiators

<AuthCodeBlock />

##### Subscribe an application to password-changed initiator only (rp-logout and idp-logout are required)

<AuthCodeBlock />

##### Unsubscribe all initiators (rp-logout remains the default)

<AuthCodeBlock />

### Dashboard

<Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect Back-Channel Logout can be configured alongside the rest of your application settings. This feature automatically activates once a Back-Channel Logout URI is provided.

<Frame>
  <img alt="Dashboard > Applications > Application Settings" />
</Frame>

#### Selected initiators only

Only the required initiators (`rp-logout` and `idp-logout`) will be subscribed to by default. Any additional initiators, including any added in the future, must first be selected before they can initiate a logout from your application.

Select this option if you want your application to log out only for initiators you select.

#### All supported initiators

All supported initiators, including any added in the future, will be subscribed to by default.

Select this option if you want your application to log out any time the IdP session ends.


# Log Users Out of Applications
Source: https://auth0.com/docs/authenticate/login/logout/log-users-out-of-applications

Describes how to force a user to log out of applications using the Auth0 logout endpoint.

Enterprise users typically have <Tooltip href="/docs/glossary?term=Single+Sign-on">Single Sign-on</Tooltip> (SSO) enabled for multiple applications (e.g., SharePoint, a few .NET applications, a few Java applications, Zendesk). In this case, when users sign out, often they must be signed out for all of their applications.

The Auth0 [RP-initiated logout endpoint](/docs/authenticate/login/logout/log-users-out-of-auth0) works in one of two ways:

* Invalidates the Single Sign-on (SSO) cookie in Auth0. (The cookie still remains in the browser.)
* Signs the user out from the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> (IdP) (such as ADFS or Google).

Redirecting users to the logout endpoint does not cover the scenario where users need to be signed out of all of the applications they used. If you need to provide this functionality you will have to handle this in one of two ways:

* Have short timeouts on your local session and redirect to Auth0 at short intervals to re-authenticate. This can be done by calling `checkSession` from the client which does this redirect in a hidden iFrame. If you take the hidden iFrame approach you need to be aware of [rate limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy) and third-party [cookie](/docs/manage-users/cookies) issues.
* Handle this entirely at the application level by providing your applications a way to notify all other applications when a logout occurs.

If you are using the alternative logout endpoint, review the [API documentation](https://auth0.com/docs/api/authentication#logout).

## Learn more

* [Log Users Out of Auth0 with OIDC Endpoint](/docs/authenticate/login/logout/log-users-out-of-auth0)
* [Log Users Out of Identity Providers](/docs/authenticate/login/logout/log-users-out-of-idps)
* [Log Users Out of SAML Identity Providers](/docs/authenticate/login/logout/log-users-out-of-saml-idps)
* [Redirect Users with Alternative Logout](/docs/authenticate/login/logout/redirect-users-after-logout)


# Log Users Out of Auth0 with OIDC Endpoint
Source: https://auth0.com/docs/authenticate/login/logout/log-users-out-of-auth0

Learn how to log user out with the OIDC Logout Endpoint.

Auth0 implements <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect’s [RP-Initiated Logout 1.0](https://openid.net/specs/openid-connect-rpinitiated-1_0.html) for end-user logout. This standard is part of the OpenID Connect collection of [final specifications](https://openid.net/developers/specs/).

## How it works

RP-Initiated Logout is a scenario in which a <Tooltip href="/docs/glossary?term=relying+party">relying party</Tooltip> (user) requests the OpenID provider (Auth0) to log them out.

1. The user initiates a logout request in your application.
2. Your application directs the user to the Auth0 Authentication API [OIDC Logout](https://auth0.com/docs/api/authentication#oidc-logout) endpoint.
3. Auth0 redirects the user to the appropriate destination based on the provided [OIDC Logout endpoint parameters](#oidc-logout-endpoint-parameters).

## Configure RP-Initiated Logout

To configure RP-Initiated Logout, you must ensure that your application can find the `end_session_endpoint` parameter in your Auth0 tenant’s [discovery metadata document](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig), and that it calls the OIDC Logout endpoint with the necessary parameters.

### Enable endpoint discovery

<Callout icon="file-lines">
  For Auth0 tenants created on or after 14 November 2023, **RP-Initiated Logout End Session Endpoint Discovery** is enabled by default.
</Callout>

You can enable **RP-Initiated Logout End Session Endpoint Discovery** in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or with the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

<Tabs>
  <Tab title="Dashboard">
    To enable **RP-Initiated Logout End Session Endpoint Discovery** in the Dashboard:

    1. Go to [Dashboard > Settings > Advanced](https://manage.auth0.com/#/tenant/advanced).
    2. Locate the **Login and Logout** section.
    3. Enable the **RP-Initiated Logout End Session Endpoint Discovery** toggle.
  </Tab>

  <Tab title="Management API">
    To enable **RP-Initiated Logout End Session Endpoint Discovery** with the Management API:

    1. [Get a Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production) that includes the `update:tenant_settings` scope.
    2. Call the Management API [Update tenant settings](https://auth0.com/docs/api/management/v2/tenants/patch-settings) endpoint with the following payload:

       ```json JSON lines theme={null}
       {
         "oidc_logout": {
           "rp_logout_end_session_endpoint_discovery": true
         }
       }
       ```
  </Tab>
</Tabs>

### Call the OIDC Logout endpoint

<Callout icon="file-lines">
  Most of Auth0’s [SDK libraries](/docs/libraries) are OIDC-compliant and support RP-Initiated Logout by design.
</Callout>

When you call the OIDC Logout endpoint, Auth0 recommends that you provide the `id_token_hint` parameter.

If your application cannot securely store <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip>, you may provide the `logout_hint` and `client_id` parameters instead.

<Callout icon="file-lines">
  You may call the OIDC Logout endpoint with redundant information.

  For example, you may send the `id_token_hint` and `logout_hint` parameters, or the `id_token_hint` and `client_id` parameters.

  In all cases, Auth0 checks for consistent user and session data, and returns an error if there are any discrepancies.
</Callout>

#### OIDC Logout endpoint parameters

The Authentication API [OIDC Logout](https://auth0.com/docs/api/authentication#oidc-logout) endpoint supports the following parameters:

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Required?</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>id\_token\_hint</code></td>
      <td>Recommended</td>
      <td>ID token previously issued for the user. That indicates which user to log out.</td>
    </tr>

    <tr>
      <td><code>logout\_hint</code></td>
      <td>Optional</td>
      <td>Session ID (<code>sid</code>) value that indicates which user to log out.</td>
    </tr>

    <tr>
      <td><code>post\_logout\_redirect\_uri</code></td>
      <td>Optional</td>
      <td>Redirect URL value that indicates where to redirect the user after logout.</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Optional</td>
      <td>Client ID of your application.</td>
    </tr>

    <tr>
      <td><code>federated</code></td>
      <td>Optional</td>
      <td>Directs Auth0 to log the user out of their identity provider.</td>
    </tr>

    <tr>
      <td><code>state</code></td>
      <td>Optional</td>
      <td>Opaque value that the application adds to the initial logout request, and that Auth0 includes when redirecting the back to the <code>post\_logout\_redirect\_uri</code>.</td>
    </tr>

    <tr>
      <td><code>ui\_locales</code></td>
      <td>Optional</td>
      <td>Space-delimited list of locales used to constrain the language list for the request. The first locale on the list must match the enabled locale in your tenant.</td>
    </tr>
  </tbody>
</table>

#### id\_token\_hint parameter

<Callout icon="file-lines">
  Auth0 recommends that you use the `id_token_hint` parameter when you call the OIDC Logout endpoint.
</Callout>

The value of the `id_token_hint` parameter must be the ID token that Auth0 issued to the user after they authenticated.

The ID token contains the registered claims issuer (`iss`), <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> (`aud`), and the Auth0 session ID (`sid`) for verification. To learn more about ID token claims, read [ID Token Structure](/docs/secure/tokens/id-tokens/id-token-structure).

##### Examples

<AuthCodeGroup>
  ```http HTTP theme={null}
  https://{yourDomain}/oidc/logout?id_token_hint={yourIdToken}&post_logout_redirect_uri={yourCallbackUrl}
  ```

  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/oidc/logout' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data 'id_token_hint={yourIdToken}' \
    --data 'post_logout_redirect_uri={yourCallbackUrl}'
  ```
</AuthCodeGroup>

#### logout\_hint parameter

The value of the `logout_hint` parameter must be the session ID (`sid`) of the user’s current Auth0 session.

The session ID (`sid`) is provided as a registered claim within the ID token that Auth0 issued to the user after they authenticated.

<Warning>
  You must use the session ID (`sid`) associated with the ID token issued by Auth0 at the time the current session began. Auth0 disregards requests with values that are random or do not reflect current session data.
</Warning>

##### Example

<AuthCodeBlock />

#### post\_logout\_redirect\_uri parameter

The value of the `post_logout_redirect_uri` parameter must be a valid, encoded URL that has been registered in the list of **Allowed Logout URLs** in your:

1. [Application settings](/docs/get-started/applications/application-settings#application-uris): If you provide the `id_token_hint` parameter, or the `logout_hint` and `client_id` parameters.
2. [Tenant settings](/docs/get-started/tenant-settings#login-and-logout): If you provide only the `logout_hint` parameter.

##### Example

<AuthCodeBlock />

##### Update application Allowed Logout URLs

You can register a URL with your application’s list of **Allowed Logout URLs** in the Auth0 Dashboard or with the Auth0 Management API.

<Tabs>
  <Tab title="Dashboard">
    To register a URL with your application’s list of **Allowed Logout URLs** in the Dashboard:

    1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications).
    2. Select your application.
    3. Locate the **Application URIs** section.
    4. Update **Allowed Logout URLs** following the [provided guidelines](#allowed-logout-urls-guidelines).
  </Tab>

  <Tab title="Management API">
    <Warning>
      When you call the Management API [Update a client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) endpoint, it overwrites all existing configuration data for the fields provided in the request body.

      To avoid accidental loss of data, call the Management API [Get a client](https://auth0.com/docs/api/management/v2/clients/get-clients-by-id) endpoint first to retrieve your application’s current configuration data.
    </Warning>

    To register a URL with your application’s list of **Allowed Logout URLs** with the Management API:

    1. [Get a Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production) that includes the `update:clients` scopes.
    2. Call the Management API [Update a client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) endpoint, and ensure that you include the URL in the value of the `allowed_logout_urls` field within the request body.

    <AuthCodeBlock />
  </Tab>
</Tabs>

##### Update tenant Allowed Logout URLs

You can register a URL with your tenant’s list of **Allowed Logout URLs** in the Auth0 Dashboard or with the Auth0 Management API.

<Tabs>
  <Tab title="Dashboard">
    To register a URL with your tenant’s list of **Allowed Logout URLs** in the Dashboard:

    1. Go to [Dashboard > Settings > Advanced](https://manage.auth0.com/#/tenant/advanced).
    2. Locate the **Login and Logout** section.
    3. Update **Allowed Logout URLs** following the [provided guidelines](#allowed-logout-urls-guidelines).
  </Tab>

  <Tab title="Management API">
    <Warning>
      When you call the Management API [Update tenant settings](https://auth0.com/docs/api/management/v2/tenants/patch-settings) endpoint, it overwrites all existing configuration data for the fields provided in the request body.

      To avoid accidental loss of data, call the Management API [Get tenant settings](https://auth0.com/docs/api/management/v2/tenants/tenant-settings-route) endpoint to retrieve your tenant’s current configuration data first.
    </Warning>

    To register a URL with your tenant’s list of **Allowed Logout URLs** with the Management API:

    1. [Get a Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production) that includes the `update:tenant_settings` scopes.
    2. Call the Management API [Update tenant settings](https://auth0.com/docs/api/management/v2/tenants/patch-settings) endpoint, and ensure that you include the URL in the value of the `allowed_logout_urls` field within the request body.

    <AuthCodeBlock />
  </Tab>
</Tabs>

##### Allowed Logout URLs guidelines

When you update **Allowed Logout URLs**, follow the guidelines below to avoid validation errors:

* Separate multiple URL values with a comma (`,`).
* Include the URL scheme part (for example, `https://`).

You may use an asterisk (`*`) as a wildcard for subdomains (such as `https://*.example.com`), but we recommend that you do not use wildcards in production environments. For more information, read [Subdomain URL Placeholders](/docs/get-started/applications/wildcards-for-subdomains#wildcard-url-placeholders).

##### Add query string parameters to post\_logout\_redirect\_uri

The OIDC Logout endpoint parses query string parameters in the URL provided to the `post_logout_redirect_uri` parameter.

You must include the **exact URL with query string parameters** in your **Allowed Logout URLs**, or the logout request will be denied. The URL must match exactly, including all query parameter names and values.

For example, if you pass `https://example.com/logout?myParam=1234` to the `post_logout_redirect_uri` parameter (encoded as `https%3A%2F%2Fexample.com%2Flogout%3FmyParam%3D1234`), you must include the complete URL `https://example.com/logout?myParam=1234` in your **Allowed Logout URLs**.

<Warning>
  Dynamic query parameter values are not supported. Each unique combination of query parameter names and values must be registered as a separate entry in your **Allowed Logout URLs**.
</Warning>

#### ui\_locales parameter

The value of the `ui_locales` parameter must be a space-delimited list of [supported locales](/docs/customize/internationalization-and-localization/universal-login-internationalization#new-universal-login-experience-localization).

The first value provided in the list must match your [tenant’s Default Language setting](/docs/get-started/tenant-settings#languages).

#### federated parameter

The `federated` parameter does not require a value.

If you include the `federated` parameter when you call the OIDC Logout endpoint, Auth0 attempts to [log the user out of their identity provider](/docs/authenticate/login/logout/log-users-out-of-idps).

## Logout consent prompt

The OIDC standard defines that the logout flow should be interrupted to prompt the user for consent if the OpenID provider cannot verify that the request was made by the user.

Auth0 enforces this behavior by displaying a logout consent prompt if it detects any of the following conditions:

* Neither the `id_token_hint` nor `logout_hint` parameters are provided.
* The ID token's `sid` claim does not correspond to the browser session in the request.
* The value of the `logout_hint` parameter does not match current session data.

<Frame>
  <img alt="" />
</Frame>

If the user confirms the logout request, Auth0 continues the logout flow.

### Disable the logout consent prompt

You may disable the logout consent prompt. If you do, Auth0 does not attempt to detect anomalous behavior and accepts logout requests automatically.

To disable the logout consent prompt in the Dashboard:

1. Go to [Dashboard > Settings > Advanced](https://manage.auth0.com/#/tenant/advanced).
2. Disable the **Show RP-Initiated Logout End-User Confirmation** toggle.

   <Frame>
     <img alt="" />
   </Frame>

## Learn more

* [Log Users Out of Applications](/docs/authenticate/login/logout/log-users-out-of-applications)
* [Log Users Out of Identity Providers](/docs/authenticate/login/logout/log-users-out-of-idps)
* [Log Users Out of SAML Identity Providers](/docs/authenticate/login/logout/log-users-out-of-saml-idps)
* [Redirect Users with Alternative Logout](/docs/authenticate/login/logout/redirect-users-after-logout)


# Log Users Out of Identity Providers
Source: https://auth0.com/docs/authenticate/login/logout/log-users-out-of-idps

Describes how to force a user to log out of their identity provider.

Some providers allow you to force a user to log out of their <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>. Auth0 often accomplishes this by adding the `federated` query string parameter to the redirect at the `/oidc/logout` endpoint.

To do this, add a `federated` query string parameter to the logout URL:

`https://{yourDomain}/oidc/logout?federated`

## Federated logout support

The following identity providers support federated logout:

* Evernote
* Facebook
* Fitbit
* GitHub
* Google

  * Apps
  * OAuth 2.0
* Microsoft

  * Active Directory Federation Services
  * Office 365
  * Windows Azure Active Directory
  * Windows Live
* Salesforce/Salesforce Sandbox
* X
* Yahoo
* Yammer

## Clear application session

The Auth0 Logout endpoint logs you out from Auth0 and, optionally, from your identity provider. It does not log you out of your application! This is something that you must implement on your side. You need to log out the user from your application by clearing their session.

## Alternative logout

To add federated logout to the [alternative logout endpoint](https://auth0.com/docs/api/authentication#logout), add the `federated` query string parameter to the logout URL:

`https://{yourDomain}/v2/logout?federated`

### Alternative logout limitations

* No validation is performed on any URL provided as a value to the `returnTo` parameter, nor any query string or hash information provided as part of the URL.
* The behavior of federated logouts with social providers is inconsistent. Each provider will handle the returnTo parameter differently and for some, it will not work. Please check your social provider's settings to determine how it will behave.
* If you are working with social identity providers such as Google or Facebook, you must set your <Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip> and Secret for these providers in the Dashboard for the logout to function properly.
* If you are an Auth0 Enterprise user, you will typically have <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> enabled for multiple applications, for example, SharePoint, a few .NET applications, a few Java applications, Zendesk, etc. In this case, it's very common that when users sign out, this needs to happen for all of their applications.

## Learn more

* [Log Users Out of Applications](/docs/authenticate/login/logout/log-users-out-of-applications)
* [Log Users Out of Auth0 with OIDC Endpoint](/docs/authenticate/login/logout/log-users-out-of-auth0)
* [Log Users Out of SAML Identity Providers](/docs/authenticate/login/logout/log-users-out-of-saml-idps)
* [Redirect Users with Alternative Logout](/docs/authenticate/login/logout/redirect-users-after-logout)


# Log Users Out of SAML Identity Providers
Source: https://auth0.com/docs/authenticate/login/logout/log-users-out-of-saml-idps

Describes how to log users out of an external SAML identity provider.

Single Logout (SLO) is a feature that allows a user to terminate multiple authentication sessions by performing a single logout action.

Auth0 supports SLO when you [connect your application to a SAML Identity Provider (IdP)](/docs/authenticate/identity-providers/enterprise-identity-providers/saml) and supports limited SLO when you [configure Auth0 as a SAML IdP](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider).

## Configure SLO when application is connected to a SAML IdP

If you’d like Auth0 to [log a user out of their identity provider](/docs/authenticate/login/logout/log-users-out-of-idps), include the `federated` parameter when you call the [Auth0 Authentication API Logout endpoint](https://auth0.com/docs/api/authentication#logout).

You may need to configure additional settings for the <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> connection to ensure that Auth0 sends the logout request to the SAML <Tooltip href="/docs/glossary?term=IdP">IdP</Tooltip>'s logout endpoint:

1. Go to [Auth0 Dashboard > Authentication > Enterprise > SAML](https://manage.auth0.com/#/connections/enterprise/samlp) and select your connection.
2. Toggle on **Enable Sign Out**.
3. Enter the SAML Logout URL provided by the SAML IdP in the **Sign Out URL** field. If you leave this field blank, Auth0 will default to the URL in the **Sign In URL** field.
4. Confirm that the value in the **Protocol Binding** field matches the protocol binding expected by the SAML IdP.

## Configure SLO when Auth0 is the SAML IdP

When Auth0 is the SAML IdP, there are two logout scenarios to consider:

* Application-initiated
* IdP-initiated

For both scenarios, you must [configure the SAML2 Web App addon](/docs/authenticate/protocols/saml/saml-sso-integrations/enable-saml2-web-app-addon) to know where to send logout responses:

1. Go to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and select your application.
2. Navigate to the **Addons** tab and select **SAML2 Web App**.
3. Go to the **Settings** tab.
4. Locate the **Settings** box and add (or update) the `logout` object with the following properties:

   * `callback`: Enter the SLO URL of the application.

   * `slo_enabled`: Enter `true` if you would like to enable IdP-initiated SLO in which Auth0 sends a SAML logout request to the application when the user logs out of the Auth0 SAML IdP. Otherwise, enter `false`.

     ```bash cURL lines theme={null}
     {
       "logout": {
         "callback": "https://myapp.exampleco.com/saml/logout",
         "slo_enabled": true
       }
     }
     ```

By default, Auth0 sends SAML logout responses with the `HTTP-POST` protocol binding. If your application expects the `HTTP-Redirect` protocol binding, add (or update) the `binding` property like so:

```json JSON lines theme={null}
{
  "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
}
```

### Application-initiated logout

When the user initiates logout from an application, it must send a request to the Authentication API [SAML Logout endpoint](https://auth0.com/docs/api/authentication#saml-logout) to trigger SLO.

If your application does not support SLO but does support a redirect URL to send the user to after logout, set the redirect URL to the Authentication API [OIDC Logout endpoint](https://auth0.com/docs/api/authentication#oidc-logout) (or the Authentication API [Auth0 Logout endpoint](https://auth0.com/docs/api/authentication#auth0-logout) if you're using legacy logout). Auth0 won't notify other session participants that a logout was initiated, but we will remove the user’s [Auth0 session](/docs/manage-users/sessions/session-layers).

### IdP-initiated logout

When a user initiates logout from an Auth0 SAML IdP, Auth0 sends a SAML logout response to the URL in the `logout.callback` property within the SAML2 Web App addon’s Settings. You can only specify a single URL for this property.

Due to this constraint, Auth0 does not natively support the scenario where a user needs to be signed out of multiple applications connected to your Auth0 SAML IdP.

You can achieve functionality similar to SLO by configuring your applications to regularly check the status of the user’s Auth0 session and terminate the application session accordingly. To learn more, read about [Session Lifetime Limits](/docs/manage-users/sessions/session-lifetime-limits).

## Learn more

* [Log Users Out of Applications](/docs/authenticate/login/logout/log-users-out-of-applications)
* [Log Users Out of Auth0 with OIDC Endpoint](/docs/authenticate/login/logout/log-users-out-of-auth0)
* [Log Users Out of Identity Providers](/docs/authenticate/login/logout/log-users-out-of-idps)
* [Redirect Users with Alternative Logout](/docs/authenticate/login/logout/redirect-users-after-logout)
* [Troubleshoot SAML Configurations](/docs/troubleshoot/authentication-issues/troubleshoot-saml-configurations)
* [Troubleshoot SAML Errors](/docs/troubleshoot/authentication-issues/saml-errors)


# Redirect Users with Alternative Logout
Source: https://auth0.com/docs/authenticate/login/logout/redirect-users-after-logout

Describes how to redirect users with the legacy logout endpoint.

You can redirect users to a specific URL after they logout. You will need to register the redirect URL in your tenant or application settings. Auth0 only redirects to allow list URLs after logout. If you need different redirects for each application, you can add the URLs to the allow list in your application settings.

1. Add a `returnTo` query string parameter with the target URL as the value. Encode the target URL being passed in. For example, to redirect the user to `https://www.example.com` after logout, make the following request:
   `https://{yourDomain}/v2/logout?returnTo=https%3A%2F%2Fwww.example.com`.
2. Add the non-encoded `returnTo` URL (for example, `https://www.example.com`) as an **Allowed Logout URLs** in one of two places:

   * **Tenant Settings**: For logout requests that do not include the `client_id` parameter, you must add the `returnTo` URL to the **Allowed Logout URLs** list in the [Advanced tab of your Tenant Settings](https://manage.auth0.com/#/tenant/advanced).

     To add a list of URLs that the user may be redirected to after logging out at the tenant level, go to the [Tenant Settings > Advanced](https://manage.auth0.com/#/tenant/advanced) of the Auth0 Dashboard.

     <Frame>
       <img alt="Auth0 Dashboard Settings Advanced Tab Login and Logout" />
     </Frame>
   * **Auth0 Application Settings**: For logout requests that include the `client_id` parameter, you must add the `returnTo` URL to the **Allowed Logout URLs** list in the **Settings** tab of the associated Auth0 application(s).

     <Frame>
       <img alt="Dashboard Applications Application Settings Application URIs" />
     </Frame>

When providing the URL list, you can:

1. Specify multiple, valid, comma-separated URLs.
2. Use `*` as a [wildcard for subdomains](/docs/get-started/applications/wildcards-for-subdomains) (such as `http://*.example.com`).

If the `client_id` parameter is included and the `returnTo` URL is not set, the server returns the user to the first Allowed Logout URLs set in the Dashboard.

In order to avoid validation errors, make sure that you include the protocol part of the URL. For example, setting the value to `*.example.com` will result in a validation error, so you should use `http://*.example.com` instead.

<Callout icon="file-lines">
  To redirect using Auth0's `oidc/logout` endpoint, read [Use OIDC Endpoint to Log Users Out of Auth0](/docs/authenticate/login/logout/log-users-out-of-auth0).
</Callout>

## Federated logouts

[Several providers](/docs/authenticate/login/logout/log-users-out-of-idps#federated-logout-support) support federated logout.

To redirect users from applications using federated logout, initiate federated logout with the following endpoint:

`https://{yourDomain}/v2/logout?federated`

You are responsible for ensuring your application terminates the user session before redirecting.

When the user reaches the `/logout` endpoint, Auth0 terminates the Auth0 session, redirects the user to the <Tooltip href="/docs/glossary?term=Identity+Providers">Identity Providers</Tooltip> logout endpoint, and terminates the session with the Identity Provider.

## Limitations

* The validation of URLs provided as values to the `returnTo` parameter, the query string, and hash information provided as part of the URL are not taken into account.
* The behavior of federated logouts with social providers is inconsistent. Each provider will handle the `returnTo` parameter differently and for some it will not work. Please check your social provider's settings to ensure that they will accept the `returnTo` parameter and how it will behave.
* The URLs provided in the **Allowed Logout URLs** list are case-sensitive, so the URL used for logouts must match the case of the logout URL configured on the dashboard. However, do note that the scheme and host parts are case insensitive. For example, if your URL is `http://www.Example.Com/FooHoo.html`, the `http://www.Example.Com` portion is case insensitive, while the `FooHoo.html` portion is case sensitive.

If you are working with social identity providers such as Google or Facebook, you must set your `Client ID` and `Secret` for these providers in the [Dashboard](https://manage.auth0.com/#) for the logout to function properly.

## Additional requirements for Facebook

Use the `returnTo` parameter to specify how to redirect the user after logout.

Not all IdPs support `returnTo`.

For Facebook, the example code below uses the `returnTo` parameter and specifies a website for the redirect.

<AuthCodeBlock />

## Learn more

* [Log Users Out of Applications](/docs/authenticate/login/logout/log-users-out-of-applications)
* [Log Users Out of Auth0 with OIDC Endpoint](/docs/authenticate/login/logout/log-users-out-of-auth0)
* [Log Users Out of Identity Providers](/docs/authenticate/login/logout/log-users-out-of-idps)
* [Log Users Out of SAML Identity Providers](/docs/authenticate/login/logout/log-users-out-of-saml-idps)
* [Check Login and Logout Issues](/docs/troubleshoot/authentication-issues/check-login-and-logout-issues)


# Universal Logout
Source: https://auth0.com/docs/authenticate/login/logout/universal-logout

Learn how to configure global token revocation for Auth0 connections.

Auth0 supports Universal Logout integrations with Okta Workforce Identity, which logs users out of applications when an administrative or security event occurs.

Universal Logout implements the [Global Token Revocation](https://www.ietf.org/archive/id/draft-parecki-oauth-global-token-revocation-02.html) specification, which goes beyond the established <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect back-channel logout standards by revoking <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip> in addition to user sessions. This comprehensive logout solution spans traditional web applications, single-page applications (SPAs), and native applications that use a mix of refresh tokens, application sessions, and <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> sessions to get new tokens and keep the user logged in.

If you use the [Okta](/docs/authenticate/identity-providers/enterprise-identity-providers/okta), [SAML](/docs/authenticate/identity-providers/enterprise-identity-providers/saml), or [OpenID Connect](/docs/authenticate/identity-providers/enterprise-identity-providers/oidc) connection types to federate with Workforce Identity, you no longer need to build a [global token revocation](https://developer.okta.com/docs/guides/oin-universal-logout-overview/) endpoint to work with Okta Universal Logout. You can instead provide Auth0’s connection-specific endpoint URL to the Okta Workforce administrator, and leverage Auth0’s [OpenID Connect Back-Channel Logout](/docs/authenticate/login/logout/back-channel-logout) to terminate application sessions if necessary.

## How it works

The Auth0 global token revocation endpoint follows the profile documented at [Build Logout for your app](https://developer.okta.com/docs/guides/oin-universal-logout-overview/). It uses the `iss_sub` format to identify users in the logout request, and uses the following URL format:

`https://{yourDomain}/oauth/global-token-revocation/connection/{yourConnectionName}`

When Auth0 receives a request to log out a user, it validates the request using the same key set used to validate <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip> or <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> assertions issued from Okta Workforce Identity. It then terminates all [Auth0 sessions](/docs/manage-users/sessions/session-layers) for the user, revokes Auth0-issued [refresh tokens](/docs/secure/tokens/refresh-tokens), and, if configured, triggers [OpenID Connect Back-Channel Logout](/docs/authenticate/login/logout/back-channel-logout) to revoke application sessions.

<Frame>
  <img alt="User workflow using Universal Logout" />
</Frame>

The time it takes for an application user to lose access depends on the application's type and how it is integrated with Auth0. Auth0 supports a wide range of [application architectures](/docs/get-started/applications) via support for the OIDC and <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> identity standards and Auth0's [Quickstarts and SDKs](/docs/quickstarts). This includes:

* Traditional Web applications that create their own [application sessions](/docs/manage-users/sessions/session-layers) may use refresh tokens and <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> to access APIs through a secure backend.
* Browser-based JavaScript applications that leverage the [Auth0 session layer](/docs/authenticate/login/configure-silent-authentication) or use techniques like [refresh token rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation) to get access tokens needed to access APIs within a Web browser.
* Native or Mobile applications that don’t run in a Web browser and use refresh tokens and access tokens as the primary method of keeping users signed in.

### Revoke refresh tokens and Auth0 user sessions

Applications using refresh tokens or leveraging Auth0 sessions get the following security benefits when the Universal Logout integration is enabled:

* For browser-based apps leveraging [the Auth0 session](/docs/authenticate/login/configure-silent-authentication), the user loses access the next time the application [polls the Auth0 session](/docs/authenticate/login/configure-silent-authentication#poll-with-checksession-), and Auth0 prompts the user to sign in again when redirected
* For apps that use refresh tokens, the user loses access as soon as their current access token expires, which ranges from a few seconds up to the [maximum access token lifetime](/docs/secure/tokens/access-tokens/update-access-token-lifetime) configured in Auth0.

### Revoke application user sessions

For sessions created by web applications, you should use Auth0’s existing [OpenID Connect Back-Channel Logout](/docs/authenticate/login/logout/back-channel-logout/configure-back-channel-logout)  feature to terminate those sessions when Universal Logout terminates the Auth0 user session. To learn more, read the [Auth0 SDK implementation examples](/docs/authenticate/login/logout/back-channel-logout#auth0-sdks).

## Configure Universal Logout in Auth0

Configure Universal Logout by the Auth0 connection type.

### Okta Workforce

1. [Connect your Auth0 tenant to Okta Workforce Identity](/docs/authenticate/identity-providers/enterprise-identity-providers/okta).
2. In Auth0 Dashboard, navigate to [**Authentication > Enterprise > Okta Workforce**](https://manage.auth0.com/#/connections/enterprise/okta). Select your connection and choose **Settings**.
3. Copy the **Revocation Endpoint URL** you will provide to the Okta Workforce administrator.

### OpenID Connect

<Callout icon="file-lines">
  We strongly recommend using the branded **Okta Workforce** connection type for new OpenID Connect integrations. However, Universal Logout can still be enabled on older integrations using the generic OpenID Connect connection type in the OpenID Connect **Settings** of Auth0 Dashboard.
</Callout>

1. In Auth0 Dashboard, navigate to [**Authentication > Enterprise > OpenID Connect**](https://manage.auth0.com/#/connections/enterprise/oidc)**.** Select your connection and choose **Settings**.
2. Copy the **Revocation Endpoint URL** you will provide to the Okta Workforce administrator.

### SAML

1. [Configure Okta as a SAML identity provider](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-okta-as-saml-identity-provider).
2. In Auth0 Dashboard, navigate to [**Authentication > Enterprise > SAML**](https://manage.auth0.com/#/connections/enterprise/samlp). Select your connection and choose **Settings**.
3. For **Subject**, enter the Application ID of the SAML application registered in Okta Workforce Identity. Example: `0oagcc12354688xxxx`. To learn more, read [How to Obtain an Application ID](https://support.okta.com/help/s/article/How-to-obtain-an-application-ID?language=en_US).
4. For **Issuer**, navigate to the registered SAML application in the Okta Workforce Identity organization and copy the [issuer URI](https://developer.okta.com/docs/guides/oin-universal-logout-overview/#endpoint-authentication).

   <Callout icon="file-lines">
     To retrieve this value, WIC admins can navigate to the **Applications** > **Applications > \[Application] > Authentication > Sign-on settings > Sign-on methods > SAML 2.0 > More details** section of the Okta portal.
   </Callout>
5. Copy the **Revocation Endpoint URL**, which you will provide to the Okta Workforce administrator.

## Configure Universal Logout in Okta Workforce Identity

Configure Universal Logout in Okta Workforce Identity to send logout signals to the application using the Auth0 connection. This must be performed by an Okta administrator.

### Prerequisites

You need:

* An Okta Workforce Identity organization with [Identity Threat Protection](https://www.okta.com/products/identity-threat-protection/) enabled, or a [free trial](https://www.okta.com/free-trial/).
* Early access to Universal Logout for Generic SAML and OIDC apps must be enabled for your Okta Workforce Identity organization. To learn more, read [Configure Universal Logout for supported apps](https://help.okta.com/oie/en-us/content/topics/itp/config-universal-logout.htm).

### Configure Okta

Enable Universal Logout in an [Okta Workforce organization](/docs/authenticate/identity-providers/enterprise-identity-providers/okta) for the Auth0 connection.

1. In the Okta portal, select **Applications** > **Applications**.
2. Select the application you registered for the Auth0 integration.
3. Under the **General** tab, select **Logout > Edit**.

   <Frame>
     <img alt="Okta Dashboard image for Universal Logout configuration" />
   </Frame>
4. Choose **Okta system or admin initiates logout**.
5. Enter the URL copied from Auth0 in **Logout Endpoint URL**.
6. Select **Issuer and Subject Identifier** as the **Subject Format**.
7. Select **Save**.

### Test Universal Logout

Test Universal Logout in Okta Workforce Identity by revoking the sessions for a selected user.

1. In the Okta portal, select **Directory > People**.
2. Select a user that is signed into an Auth0 application.
3. Select **More Actions > Clear User Sessions**.

   <Frame>
     <img alt="Test Universal Logout in Okta Dashboard" />
   </Frame>
4. In the dialog, select **Also include logout enabled apps and Okta API tokens**.
5. Select **Clear and Revoke**.

## Logs and Notifications

Auth0 tenant administrators can view the status and details of each Universal Logout request Auth0 receives in [Auth0 Dashboard > Monitoring > Logs](https://manage.auth0.com/#/*/logs). The emitted log event types for Universal Logout are documented in [Log Event Type Codes](/docs/deploy-monitor/logs/log-event-type-codes).

You can also integrate with [Custom Log Streams](/docs/customize/log-streams) to notify external systems when Universal Logout events occur.

## Management API

You can also use the [Management API](https://auth0.com/docs/api/management/v2) to configure Universal Logout programatically. This is useful for automating configurations or building your own configuration outside of the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

For Okta Workforce and OpenID Connections, no input into the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> is required, as only the Auth0 global token revocation endpoint needs to be presented to the Okta Workforce administrator.

For SAML connections, in addition to sharing the endpoint URL, Universal Logout must be configured by setting these attributes on the `connection` object:

* **options.global\_token\_revocation\_jwt\_iss** - The [issuer ID](https://developer.okta.com/docs/guides/oin-universal-logout-overview/#endpoint-authentication) of the SAML application registered in Okta Workforce Identity. Example value: `http://www.okta.com/exkhwkmkwhZUnuA6xxxx`.
* **options.global\_token\_revocation\_jwt\_sub** - The [application ID](https://support.okta.com/help/s/article/How-to-obtain-an-application-ID?language=en_US) of the SAML application registered in Okta Workforce Identity. Example value: `0oagcc12354688xxxx`.

You can use these attributes in Management API calls to [update](https://auth0.com/docs/api/management/v2#!/Connections/patch_connections_by_id) or [create](https://auth0.com/docs/api/management/v2/connections/post-connections)  SAML connections. Review the following JSON example to create a request:

```json JSON lines theme={null}
{
	"strategy": "samlp",
  	"name": "CONNECTION_NAME",
  	"options": {
    	"global_token_revocation_jwt_iss": "ISS_VALUE", 
     	"global_token_revocation_jwt_sub":  "SUB_VALUE",
    	"signInEndpoint": "SIGN_IN_ENDPOINT_URL",
    	"signOutEndpoint": "SIGN_OUT_ENDPOINT_URL",
    	"signatureAlgorithm": "rsa-sha256",
    	"digestAlgorithm": "sha256",
    	"fieldsMap": {
     		...
    	},
    	"signingCert": "BASE64_SIGNING_CERT"
  	}
}
```

To learn more, read [Create an Enterprise connection using the Management API](/docs/authenticate/identity-providers/enterprise-identity-providers/saml#create-an-enterprise-connection-using-the-management-api).


# Force Reauthentication in OIDC
Source: https://auth0.com/docs/authenticate/login/max-age-reauthentication

Describes how relying parties are able to confirm re-authentication has taken place at a specific time interval by using the `max_age` request parameter.

The `prompt=login` mechanism can be subverted by simply stripping the parameter as it passes through the user agent (browser) and is only good for providing a UX hint to the <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> provider (OP) in cases when the <Tooltip href="/docs/glossary?term=relying+party">relying party</Tooltip> (RP) wants to display a link like:

**“Hi Josh. Not you? Click here.”**

However, you should not rely on it to validate that a fresh authentication took place. To mitigate this, the client must validate that re-authentication has taken place using the `auth_time` claim. This claim will be included automatically in the <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> when `prompt=login` or `max_age=0` parameters are given in the authentication request.

You need to pass the `max_age` parameter to the Authorization API [`/authorize` endpoint](https://auth0.com/docs/api/authentication). If you use [Auth0.js](/docs/libraries/auth0js) or [Lock](/docs/libraries/lock/lock-authentication-parameters), you can set the parameter in the appropriate options of the library.

How you implement re-authentication depends on your specific use-case. Make a distinction between simple re-authentication for sensitive operations vs. [step-up](/docs/secure/multi-factor-authentication/step-up-authentication) (i.e. <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip>) for sensitive operations. Both are valid security measures. The former requires the end user to re-enter their password, whereas the latter requires them to use a pre-configured means of multifactor authentication as well.

## Limitations of prompt=login parameters

The [OIDC spec](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) defines the `prompt=login` parameter that can be used to trigger re-authentication UI (usually a login prompt):

<Callout icon="file-lines">
  **prompt**

  OPTIONAL: Space delimited, case sensitive list of ASCII string values that specifies whether the authorization server prompts the end-user for re-authentication and consent. The defined values are:

  **login**

  The authorization server should prompt the end-user for re-authentication. If it cannot re-authenticate the end-user, it must return an error, typically `login_required`.
</Callout>

However, there is an issue with using this parameter to ensure re-authentication: **the RP has no way to validate that a re-authentication action has taken place**. Let's inspect the traffic to understand why. The flow for an authentication request from the RP is as follows:

```http lines theme={null}
https://mydomain.auth0.com/authorize?
client_id=abcd1234
&redirect_uri= https://mydomain.com/callback
&scope=openid profile
&response_type=id_token
&prompt=login
```

Upon successful authentication by the AS, the RP will have an ID token delivered:

```json JSON lines theme={null}
{
  "nickname": "user",
  "name": "user@mydomain.auth0.com",
  "updated_at": "2019-04-01T14:43:03.445Z",
  "iss": "https://jcain0.auth0.com/",
  "sub": "auth0|l33t",
  "aud": "abcd1234",
  "iat": 1554129793,
  "exp": 1554165793
}
```

The trusted identity document returned by the AS **has no claims that validate when the last login occurred**. This becomes a problem when the initial authorization request comes in the form of a 302 redirect through the end user’s browser. If a malicious actor wants to skip the re-authentication step requested by the RP, they simply have to remove the `prompt=login` parameter and the RP doesn't know the difference in the fields contained in the ID token.

Here’s a diagram of a simplified implicit flow using the `prompt=login`parameter:

<Frame>
  <img alt="Force Re-Authentication OIDC Implicit Flow" />
</Frame>

Note that all the end-user has to do is remove the `prompt=login` parameter and the re-authentication step can be skipped:

<Frame>
  <img alt="Simplified Implicit Flow Remove prompt=login" />
</Frame>

The token(s) returned from the first flow above will be identical to the token(s) returned from the second flow. The RP has no specification-defined way of verifying that re-authentication has taken place, and therefore cannot trust that a `prompt=login` has actually yielded a re-authentication.

## max\_age authentication request parameter

Unlike `prompt=login`, the `max_age` authentication request parameter provides a mechanism whereby RPs can positively confirm that re-authentication has taken place within a given time interval. The [OIDC spec](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) states:

<Callout icon="file-lines">
  **max\_age**

  OPTIONAL: Maximum Authentication Age. Specifies the allowable elapsed time in seconds since the last time the end-user was actively authenticated by the OP. If the elapsed time is greater than this value, the OP must attempt to actively re-authenticate the end-user. (The `max_age` request parameter corresponds to the OpenID 2.0 PAPE `max_auth_age` request parameter.) When `max_age` is used, the ID token returned must include an `auth_time` claim value.
</Callout>

The last sentence in the definition is the most important part. When `max_age` is requested by the RP, an `auth_time` claim must be present in the RP. This means that `max_age` can be used in one of two ways:

* **To enforce a minimum session freshness**: If an app has a requirement that users must re-authenticate once per day, this can be enforced in the context of a much longer <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> session by providing `max_age` with a value. These are defined in seconds.
* **To force an immediate re-authentication**: If an app requires that a user re-authenticate prior to access, provide a value of 0 for the `max_age` parameter and the AS will force a fresh login.

This requirement is described as follows:

<Frame>
  <img alt="OIDC re-authentication max_age flow" />
</Frame>

Note that the RP receives a token with the proper amount of information to validate whether or not re-authentication has taken place. The RP can now consult the `auth_time` claim in the ID token to determine whether or not the `max_age` parameter it requested was fulfilled. In this way, the `max_age=0` parameter is impervious to the same kind of client tampering that could subvert the `prompt=login` parameter.

<Warning>
  Keep in mind that it’s solely up to the RP to validate that it is receiving an ID token with an appropriate `auth_time`. This extra validation will need to be covered by application authors and frameworks making use of the `max_age` parameter.
</Warning>

## Use auth\_time claims

We've established that the OIDC spec provides the `max_age` parameter as a way to positively confirm a re-authentication has taken place, but `prompt=login` does not. This does not present very secure options if you want to force a re-authentication:

* **prompt=login**: Only include the `prompt` parameter and not validate that the AS actually re-authenticated.
* **prompt=login & max\_age=999999**: Include an arbitrary `max_age` such that an `auth_time` claim is present. You can validate a re-authentication took place, but the parameters get messy.
* **max\_age=0**: Effectively force a login prompt using only the `max_age` parameter. Note that a recent spec update further clarified this parameter, stating it is effectively the same as `prompt=login`. This one is not feasible since it blends what should be a UX parameter with a session maintenance parameter.

Instead, Auth0 has made a choice to send the `auth_time` claim in the ID token when responding to a`prompt=login`request parameter. This means that you have the option use `prompt=login` AND validate that a re-authentication took place.

### auth\_time validation example

<Callout icon="file-lines">
  You must be sure to implement validation to ensure a re-authentication has taken place. You must validate that a proper `auth_time` has been returned.
</Callout>

The following example uses the [passport-auth0-openidconnect](https://github.com/auth0/passport-auth0-openidconnect) module to demonstrate how to validate re-authentication. The first (and simplest) way is to add the `max_age=0` option to the `Auth0OidcStrategy`:

```javascript JavaScript lines theme={null}
var strategy = new Auth0OidcStrategy(
  {
    domain: process.env.AUTH0_DOMAIN,
    clientID: process.env.AUTH0_CLIENT_ID,
    clientSecret: process.env.AUTH0_CLIENT_SECRET,
    callbackURL: process.env.AUTH0_CALLBACK_URL || 'http://localhost:5000/callback',
    max_age: 0
  },
  function(req, issuer, audience, profile, accessToken, refreshToken, params, cb) {
    // No extra validation required!
    return cb(null, profile);
  });
```

Notice that no further validation steps are required as the strategy already handles validation of the `max_age` parameter:

```javascript JavaScript lines theme={null}
// https://openid.net/specs/openid-connect-basic-1_0.html#IDTokenValidation - check 8.
if (meta.params.max_age && (!jwtClaims.auth_time || ((meta.timestamp - meta.params.max_age) > jwtClaims.auth_time))) {
  return self.error(new Error('auth_time in id_token not included or too old'));
}
```

You can also use `prompt=login` in the same context, but since the standard does not require an `auth_time` to accompany the ID token response, you must handle the validation manually. So, the strategy constructor would be:

```javascript JavaScript lines theme={null}
var strategy = new Auth0OidcStrategy(
  {
    domain: process.env.AUTH0_DOMAIN,
    clientID: process.env.AUTH0_CLIENT_ID,
    clientSecret: process.env.AUTH0_CLIENT_SECRET,
    callbackURL: process.env.AUTH0_CALLBACK_URL || 'http://localhost:5000/callback',
    prompt: 'login'
  },
  function(req, issuer, audience, profile, accessToken, refreshToken, params, cb) {
    const tenSecondsAgo = (Date.now() / 1000) - 10;
    if (isNaN(profile.auth_time) || profile.auth_time < tenSecondsAgo) {
      return cb('prompt=login requested, but auth_time is greater than 10 seconds old', null);
    }

    return cb(null, profile);
  });
```

Unlike `max_age=0`, the client must manually perform validation on the `auth_time` parameter. To learn more, read [Use auth\_time claims](/docs/authenticate/login/max-age-reauthentication#use-auth_time-claims).

<Warning>
  The example above represents a simplified proof-of-concept (it must have authenticated in the last 10 seconds). Ideally, if you want to validate that a re-authentication has occurred, you would need to:

  1. Store the time that the initial authentication request was made.
  2. Upon authentication response, retrieve the time at which the request was sent.
  3. Compare the original authentication request time with the `auth_time` claim to ensure `auth_time` is a later timestamp.

  **Auth0 does not recommend that the approach used in the example be followed in any production systems.**
</Warning>

## Known issues

Auth0 can only guarantee that an exchange took place with the upstream <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>. This may be through the user actually signing in to a third-party identity provider or perhaps the user already had a session and didn't have to sign in again. Either way, Auth0’s exchange with the upstream identity provider will result in an updated `auth_time`.

Forcing re-authentication within the upstream identity provider is not something Auth0 supports because not all providers support this.

The diagram below presents an example flow for a user who chooses to reauthenticate with a federated connection:

<Frame>
  <img alt="Federated connections do not force re-authentication diagram" />
</Frame>

This method assumes you use [database connections](/docs/authenticate/database-connections). External identity providers may or may not support forcing re-authentication. Using `prompt=login` or `prompt=consent` is generally a way to indicate an external (social) identity provider to reauthenticate a user, but Auth0 cannot enforce this.

<Warning>
  Don’t rely on client-side verification (i.e. in the browser) of the ID token or `auth_time` to prevent sensitive operations.
</Warning>

## Learn more

* [Implicit Flow with Form Post](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post)
* [OpenID Connect Protocol](/docs/authenticate/protocols/openid-connect-protocol)


# Native Login
Source: https://auth0.com/docs/authenticate/login/native-login

Learn about the different login options for native mobile applications.

Native mobile applications can use native or browser-based login flows.

In a **browser-based** login flow, the user is shown a web browser and redirected to the Auth0 login page for sign up or log in. For example: an iOS application opens a SafariViewController or an Android application opens a Custom Chrome Tab.

With a **native** login flow, the user signs up or enters their credentials directly into the app.

Regardless of which option you choose, Auth0 supports either.

## Browser-based login

* [Android Quickstart](/docs/quickstart/native/android)
* [iOS Swift Quickstart](/docs/quickstart/native/ios-swift)

## Native embedded login

If you prefer to embed your own login pages within your native/mobile app, you can implement our login widget, Lock, directly into your app with:

* [Lock.swift](/docs/libraries/lock-swift)
* [Lock.Android](/docs/libraries/lock-android)

Examples of native apps with embedded login:

* [Android](https://github.com/auth0-samples/auth0-android-sample/tree/embedded-login)
* [iOS](https://github.com/auth0-samples/auth0-ios-swift-sample/tree/embedded-login/01-Embedded-Login)

### Passwordless

[Embedded Passwordless Login in Native Applications](/docs/authenticate/passwordless/implement-login/embedded-login/native)

### Considerations

* Phishing/security concerns: an unauthorized party could decompile or intercept traffic to/from your application to get the <Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip> and authentication URL. With this information the unauthorized party could create a rogue application, upload it to an application store, and use it to phish for usernames, passwords, and <Tooltip href="/docs/glossary?term=Access+Tokens">Access Tokens</Tooltip>.
* <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip>: users have to enter their credentials for each application.

  * Can implement SSO with native apps by storing refresh tokens on a shared keychain, but this is not compliant with the OAuth 2.0 specifications.
* Takes more time to implement
* No automatic improvements when Auth0 adds new features, have to update app code to take advantage of new features vs UL
* Not compliant with <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> best practices

  * [RFC 8252 OAuth 2.0 for Native Apps](https://tools.ietf.org/html/rfc8252): authorization requests from native apps should only be made through external user-agents, primarily the user's browser

## Native social login

You can add functionality to your native app letting users authenticate with social <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> natively, within the application:

Facebook Login:

* [Add Facebook Login to Native Apps](/docs/authenticate/identity-providers/social-identity-providers/facebook-native)
* [Android - Facebook Login](/docs/quickstart/native/android-facebook-login)
* [iOS Swift - Facebook Login](/docs/quickstart/native/ios-swift)

Sign In with Apple:

* [iOS Swift - Sign In With Apple](/docs/quickstart/native/ios-swift)
* [Add Sign In with Apple to Native iOS Apps](/docs/authenticate/identity-providers/social-identity-providers/apple-native)

### Rate limits

Limits are only applied to requests related to the Native Social Login flows, which are identified based on the body of the requests with the following initial criteria:

<table>
  <thead>
    <tr>
      <th>Request Type</th>
      <th>Body</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td><code>urn:ietf:params:oauth:grant-type:token-exchange</code></td>
    </tr>

    <tr>
      <td><code>subject\_token\_type</code></td>
      <td><code>[http://auth0.com/oauth/token-type/apple-authz-code](http://auth0.com/oauth/token-type/apple-authz-code)</code></td>
    </tr>
  </tbody>
</table>

#### Limits for production tenants of paying customers

<table>
  <thead>
    <tr>
      <th>Endpoint</th>
      <th>Path</th>
      <th>Limited By</th>
      <th>Rate Limit</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Get Token</td>
      <td><code>/oauth/token</code></td>
      <td>Any native social login request</td>
      <td>50 per minute with bursts up to 500 requests</td>
    </tr>
  </tbody>
</table>

#### Limits for non-production tenants of paying customers and all tenants of free customers

<table>
  <thead>
    <tr>
      <th>Endpoint</th>
      <th>Path</th>
      <th>Limited By</th>
      <th>Rate Limit</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Get Token</td>
      <td><code>/oauth/token</code></td>
      <td>Native social login requests and IP</td>
      <td>30 per minute</td>
    </tr>
  </tbody>
</table>


# Adopt OIDC-Conformant Authentication
Source: https://auth0.com/docs/authenticate/login/oidc-conformant-authentication

Learn about the effect of the OIDC-conformant application setting on the authentication pipeline.

Auth0 is a [certified OpenID Connect (OIDC) provider](http://openid.net/certification/). As part of Auth0’s efforts to improve security and standards-based interoperability, we roll out new features exclusively on authentication flows that strictly conform to [OIDC specifications](http://openid.net/specs/openid-connect-core-1_0.html).

We will explain the differences between the OIDC-conformant and legacy pipelines and provide suggestions on how to adapt your existing applications. If you are a developer and/or IT administrator who manages Auth0 integrations in your applications using the [OAuth 2.0 Authorization Framework](/docs/authenticate/protocols/oauth). This information is not applicable if you are using <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> or WS-Federation. All authentication flows are described through HTTP requests rather than in the context of any particular language or library implementation.

All new features target only the OIDC-conformant pipeline, and all legacy Auth0 SDK versions are deprecated, do not receive updates for new features or non-critical security issues, and will eventually be discontinued. In addition, all documentation, libraries, and examples outside of this guide apply to only the OIDC-conformant pipeline. Because of this, we strongly recommend adopting the OIDC-conformant pipeline even if you do not need to leverage any new features or functionality in the immediate future.

## Apply the OIDC-conformant pipeline

Depending on the age of your tenant, you may have different options for applying the OIDC-conformant pipeline.

### New tenants

If you create a new tenant using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, the OIDC-conformant pipeline is used by default. This has been a default setting for the Dashboard since early 2019.

<Callout icon="file-lines">
  You may still have manually disabled the OIDC Conformant setting, in which case you should follow our instructions for older tenants.
</Callout>

### Older tenants

If you want to force all changes outlined in this guide at the same time for a given application so you can encounter all breaking changes during configuration rather than run time, you must:

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), and select the desired application.
2. Scroll to **Advanced Settings** and go to the **OAuth** tab.
3. Enable the **OIDC Conformant** toggle switch and click **Save Changes**.

If you want to use the OIDC-conformant pipeline on a per-authentication-request basis and your application needs to call an API with a <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, initiate the request to the [`/social`](https://auth0.com/docs/api/authentication#social) endpoint with an `audience` parameter.

If you want to use the OIDC-conformant pipeline on a per-authentication-request basis and your application doesn't need to call an API, use the following `audience` parameter:

<AuthCodeBlock />

## Differences

Enabling the OIDC-conformant pipeline results in the following changes to the legacy pipeline.

### APIs

Applications and APIs (resources) should be defined as separate Auth0 entities. To learn more, read [OIDC-Conformant Adoption: APIs](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-apis).

### Access tokens

* APIs should be secured with access tokens instead of <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip>. To learn more about the differences, read [Tokens](/docs/secure/tokens).
* A defined set of standard claims about users can be returned in ID Tokens or in the response from `/userinfo`.
* Custom claims must conform to a named format. To learn more, read [Create Namespaced Custom Claims](/docs/secure/tokens/json-web-tokens/create-custom-claims).
* Responses from `/userinfo` will conform to the OIDC specification, similar to the contents of ID tokens
* Scopes can be used to request either standard claims or custom API permissions.

To learn more, read [OIDC-Conformant Adoptions: Access Tokens](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-access-tokens).

### Authorization flows

* [Authorization Code Flow](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-auth-code-flow): Structural differences exist in the authentication request, authentication response, code exchange request, code exchange response, ID token structure, and access token structure.
* [Client Credentials Flow](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-client-credentials-flow): New flow enabled, which allows applications to authenticate as themselves (rather than on behalf of a user) to programmatically and securely obtain access to an API.
* [Implicit Flow](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-implicit-flow): Structural differences exist in the authentication request, authentication response, ID token structure, and access token structure. Specifically:

  * `response_type=token` only returns an access token. To get an ID token, use `response_type=id_token` or `response_type=token id_token`.
  * ID tokens will be signed asymmetrically using RS256.
  * Authentication requests made without a nonce parameter will be rejected. To learn more, read [Mitigate Replay Attacks When Using Implicit Flow](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post/mitigate-replay-attacks-when-using-the-implicit-flow).
  * Refresh tokens will no longer be returned when using the Implicit Flow for authentication.
* [Resource Owner Password Flow](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-rop-flow): Structural differences exist in the authentication request, authentication response, ID token structure, and access token structure. Specifically:

  * the legacy [resource owner endpoint](https://auth0.com/docs/api/authentication#database-ad-ldap-active-) is disabled, which also disables passwordless authentication for embedded login from that endpoint. To [implement Passwordless with embedded login](/docs/authenticate/login/universal-vs-embedded-login), you must use the Embedded Passwordless API or our SDKs, depending on your application type.
  * the `device` parameter is now considered invalid when requesting a refresh token using the `offline_access` scope.

### Delegation

* **Deprecated**: [`/delegation`](https://auth0.com/docs/api/authentication#delegation) endpoint, except when used to get third-party API tokens.
* OIDC-conformant applications cannot be the source or target of delegation requests.

To learn more, read [OIDC-Conformant Adoption: Delegation](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-delegation).

### Endpoints

* **Deprecated**: `/tokeninfo` endpoint
* **Disabled**: the [`/oauth/access_token`](https://auth0.com/docs/api/authentication#post-oauth-access_token) endpoint (used for social authentication from native mobile applications).
* **Deprecated**: `/ssodata` endpoint
* **Deprecated**: [`/delegation`](https://auth0.com/docs/api/authentication#delegation) endpoint except when used to get third-party API tokens.

### Refresh tokens

* <Tooltip href="/docs/glossary?term=Refresh+tokens">Refresh tokens</Tooltip> will no longer be returned when using the Implicit Flow for authentication.
* Refresh tokens can be used for confidential applications, but <Tooltip href="/docs/glossary?term=refresh+token+rotation">refresh token rotation</Tooltip> can increase security for most flows and should always be used for public applications when using the Authorization Code Flow with PKCE. To learn about confidential applications, read [Confidential and Public Applications](/docs/get-started/applications/confidential-and-public-applications). To learn more about refresh token rotation, read, [Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation).
* When getting new tokens, you should use the `/oauth/token` endpoint.
* The `device` parameter is no longer needed when requesting a refresh token using the `offline_access` scope in authentication requests.

To learn more, read [OIDC-Conformation Adoption: Refresh Tokens](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-refresh-tokens).

### Single Sign-on (SSO)

* <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> can be performed only from Auth0 login pages, which means that you must employ <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>.
* To determine whether users are logged in via SSO, you must use silent authentication. To learn more, read [Configure Silent Authentication](/docs/authenticate/login/configure-silent-authentication).
* **Deprecated**: `/ssodata` endpoint and `getSSOData()` method from `Lock/auth0.js`.

To learn more, read [OIDC-Conformant Adoption: Single Sign-On](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-sso).

### Additional features

* Create third-party applications for your APIs and display consent dialogs for authorization. To learn more, read [User Consent and Third-Party Applications](/docs/get-started/applications/confidential-and-public-applications/user-consent-and-third-party-applications).
* Restrict user profile information provided to applications upon authentication. To learn more, read [User Profiles](/docs/manage-users/user-accounts/user-profiles/user-profile-structure).
* Dynamically register applications. To learn more, read [Dynamic Client Registration](/docs/get-started/applications/dynamic-client-registration).
* [Organizations](/docs/manage-users/organizations) and their related features become available.


# Access Tokens with OIDC
Source: https://auth0.com/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-access-tokens

Learn how the OIDC-conformant pipeline affects the tokens used to secure APIs, including scopes and claims.

Because applications and APIs (resources) are defined as separate Auth0 entities with the OIDC-conformant pipeline, you can get <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> for your APIs. Consequently, all APIs should be secured with access tokens instead of <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip>. To learn more, read [Access Tokens](/docs/secure/tokens/access-tokens) and [ID Tokens](/docs/secure/tokens/id-tokens).

## Claims

The OIDC-conformant pipeline standardizes claims that you can add to ID and access tokens.

### Standard claims

The OIDC specification defines a [](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) set of standard claims about users, such as profile and email, that can be returned in ID tokens or in the response from the `/userinfo` endpoint.

To learn about the OIDC standard claim specification, read [Section 5.1 Standard Claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) in the [OpenID Specification](https://openid.net).

### Custom claims

With the OIDC-conformant pipeline, custom claims may still be added to ID tokens or access tokens, but they must conform to a namespaced format to avoid possible collisions with standard OIDC claims.

To learn how to add a custom claim in the OIDC-conformant pipeline, read [Create Namespaced Custom Claims](/docs/secure/tokens/json-web-tokens/create-custom-claims).

## Scopes

In the OIDC-conformant pipeline, you can configure your applications in Auth0 to use scopes to request that:

* Standard OIDC claims, such as `profile` and `email`, be included in the ID token (if the user consents to provide this information to the application).
* Permissions supported by the API they want to access be included in the access token. For example, you can define your custom API's <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> and required scopes, which will allow you to segregate access to different operations within your API.

To learn more, read [OpenID Connect Scopes](/docs/get-started/apis/scopes/openid-connect-scopes).

## Learn more

* [External APIs with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-apis)
* [Authorization Code Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-auth-code-flow)
* [Client Credentials Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-client-credentials-flow)
* [Delegation with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-delegation)
* [Implicit Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-implicit-flow)
* [Refresh Tokens with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-refresh-tokens)


# External APIs with OIDC
Source: https://auth0.com/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-apis

Learn how the OIDC-conformant pipeline affects your use of external APIs and the tokens used to secure them.

With the OIDC-conformant pipeline, you should define applications and APIs (resources) as separate Auth0 entities. Benefits include:

* Simpler API integration: APIs are no longer tied to applications that call them.
* [Machine-to-machine (M2M)](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow) integration scenarios: Applications can authenticate as themselves (instead of acting on behalf of a user) to programmatically and securely get an <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>.

## Architecture

Suggested OIDC-conformant solutions for different scenarios include:

* **Multiple applications calling an API under a single <Tooltip href="/docs/glossary?term=client+ID">client ID</Tooltip>**: Represent each application with a single Auth0 application, each of which can interact with the API on which the applications depend.
* **Exchange tokens obtained by one application for tokens for a different application with delegation**: Use a multi-application solution, with each application authenticating to the same <Tooltip href="/docs/glossary?term=resource+server">resource server</Tooltip>.
* **Applications do not depend on external APIs; only used to authenticate users**: You do not need to define an API as long as <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip> are:

  * Processed only by the application.
  * Not sent to any external services.

## Learn more

* [Access Tokens with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-access-tokens)
* [Authorization Code Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-auth-code-flow)
* [Client Credentials Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-client-credentials-flow)
* [Delegation with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-delegation)
* [Implicit Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-implicit-flow)
* [Refresh Tokens with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-refresh-tokens)


# Authorization Code Flow with OIDC
Source: https://auth0.com/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-auth-code-flow

Learn how the OIDC-conformant pipeline affects the Authorization Code Flow.

The [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow) is used by server-side applications that are capable of securely storing secrets, or by native applications through [Authorization Code Flow with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce).

The OIDC-conformant pipeline affects the Authorization Code Flow in the following areas:

* Authentication request
* Authentication response
* Code exchange request
* Code exchange response
* <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> structure
* <Tooltip href="/docs/glossary?term=Access+token">Access token</Tooltip> structure

## Authentication request

### Legacy

```http lines theme={null}
GET /authorize?
    response_type=code
    &scope=openid email favorite_color offline_access
    &client_id=123
    &state=af0ifjsldkj
    &redirect_uri=https://app.example.com/callback
    &device=my-device-name
```

The `device` parameter is only needed if requesting a <Tooltip href="/docs/glossary?term=refresh+token">refresh token</Tooltip> by passing the `offline_access` scope. To learn more, read, [Refresh Tokens](/docs/secure/tokens/refresh-tokens).

### OIDC-conformant

```http lines theme={null}
GET /authorize?
    response_type=code
    &scope=openid email offline_access
    &client_id=123
    &state=af0ifjsldkj
    &redirect_uri=https://app.example.com/callback
    &audience=https://api.example.com
```

* `favorite_color` is no longer a valid scope value.
* The `device` parameter is removed.
* The `audience` parameter is optional.

## Authentication response

The response from Auth0 is identical in both pipelines:

```json lines theme={null}
HTTP/1.1 302 Found
Location: https://app.example.com/callback?
    code=SplxlOBeZQQYbYS6WxSbIA
    &state=af0ifjsldkj
```

## Code exchange request - Authorization Code flow

An authorization code can be exchanged in the same way in both pipelines:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data 'grant_type=authorization_code' \
    --data 'client_id={yourClientId}' \
    --data 'client_secret={yourClientSecret}' \
    --data 'code=YOUR_AUTHORIZATION_CODE' \
    --data 'redirect_uri={https://yourApp/callback}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=authorization_code&client_id={yourClientId}&client_secret={yourClientSecret}&code=YOUR_AUTHORIZATION_CODE&redirect_uri={https://yourApp/callback}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=authorization_code&client_id={yourClientId}&client_secret={yourClientSecret}&code=YOUR_AUTHORIZATION_CODE&redirect_uri={https://yourApp/callback}")

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

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=authorization_code&client_id={yourClientId}&client_secret={yourClientSecret}&code=YOUR_AUTHORIZATION_CODE&redirect_uri={https://yourApp/callback}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      code: 'YOUR_AUTHORIZATION_CODE',
      redirect_uri: '{https://yourApp/callback}'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=authorization_code" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_secret={yourClientSecret}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&code=YOUR_AUTHORIZATION_CODE" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&redirect_uri={https://yourApp/callback}" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=authorization_code&client_id={yourClientId}&client_secret={yourClientSecret}&code=YOUR_AUTHORIZATION_CODE&redirect_uri={https://yourApp/callback}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=authorization_code&client_id={yourClientId}&client_secret={yourClientSecret}&code=YOUR_AUTHORIZATION_CODE&redirect_uri={https://yourApp/callback}"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=authorization_code&client_id={yourClientId}&client_secret={yourClientSecret}&code=YOUR_AUTHORIZATION_CODE&redirect_uri={https://yourApp/callback}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/x-www-form-urlencoded"]

  let postData = NSMutableData(data: "grant_type=authorization_code".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&client_secret={yourClientSecret}".data(using: String.Encoding.utf8)!)
  postData.append("&code=YOUR_AUTHORIZATION_CODE".data(using: String.Encoding.utf8)!)
  postData.append("&redirect_uri={https://yourApp/callback}".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

## Code exchange request - Authorization Code flow with PKCE

An authorization code can be exchanged in the same way in both pipelines:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=authorization_code \
    --data 'client_id={yourClientId}' \
    --data code_verifier=YOUR_GENERATED_CODE_VERIFIER \
    --data code=YOUR_AUTHORIZATION_CODE \
    --data 'redirect_uri={https://yourApp/callback}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=authorization_code&client_id={yourClientId}&code_verifier=YOUR_GENERATED_CODE_VERIFIER&code=YOUR_AUTHORIZATION_CODE&redirect_uri={https://yourApp/callback}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=authorization_code&client_id={yourClientId}&code_verifier=YOUR_GENERATED_CODE_VERIFIER&code=YOUR_AUTHORIZATION_CODE&redirect_uri={https://yourApp/callback}")

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

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=authorization_code&client_id={yourClientId}&code_verifier=YOUR_GENERATED_CODE_VERIFIER&code=YOUR_AUTHORIZATION_CODE&redirect_uri={https://yourApp/callback}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: '{yourClientId}',
      code_verifier: 'YOUR_GENERATED_CODE_VERIFIER',
      code: 'YOUR_AUTHORIZATION_CODE',
      redirect_uri: '{https://yourApp/callback}'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=authorization_code" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&code_verifier=YOUR_GENERATED_CODE_VERIFIER" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&code=YOUR_AUTHORIZATION_CODE" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&redirect_uri={https://yourApp/callback}" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=authorization_code&client_id={yourClientId}&code_verifier=YOUR_GENERATED_CODE_VERIFIER&code=YOUR_AUTHORIZATION_CODE&redirect_uri={https://yourApp/callback}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=authorization_code&client_id={yourClientId}&code_verifier=YOUR_GENERATED_CODE_VERIFIER&code=YOUR_AUTHORIZATION_CODE&redirect_uri={https://yourApp/callback}"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=authorization_code&client_id={yourClientId}&code_verifier=YOUR_GENERATED_CODE_VERIFIER&code=YOUR_AUTHORIZATION_CODE&redirect_uri={https://yourApp/callback}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/x-www-form-urlencoded"]

  let postData = NSMutableData(data: "grant_type=authorization_code".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&code_verifier=YOUR_GENERATED_CODE_VERIFIER".data(using: String.Encoding.utf8)!)
  postData.append("&code=YOUR_AUTHORIZATION_CODE".data(using: String.Encoding.utf8)!)
  postData.append("&redirect_uri={https://yourApp/callback}".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

## Code exchange response

### Legacy

```json lines theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
    "access_token": "SlAV32hkKG",
    "token_type": "Bearer",
    "refresh_token": "8xLOxBtZp8",
    "expires_in": 3600,
    "id_token": "eyJ..."
}
```

* The returned Access Token is only valid for calling the [`/userinfo`](https://auth0.com/docs/api/authentication#get-user-info) endpoint.
* A refresh token will be returned only if a `device` parameter was passed and the `offline_access` scope was requested.

### OIDC-conformant

```json lines theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
    "access_token": "eyJ...",
    "token_type": "Bearer",
    "refresh_token": "8xLOxBtZp8",
    "expires_in": 3600,
    "id_token": "eyJ..."
}
```

* The returned access token is valid for optionally calling the API specified in the `audience` parameter and the [`/userinfo`](https://auth0.com/docs/api/authentication#get-user-info) endpoint (provided that the API uses `RS256` as the [signing algorithm](/docs/get-started/applications/signing-algorithms) and `openid` is used as a `scope` parameter). If you are not implementing your own <Tooltip href="/docs/glossary?term=Resource+Server">Resource Server</Tooltip> (API), then you can use `https://{$account.namespace}/userinfo` as the `audience` parameter, which will return an opaque Access Token.
* A refresh token will be returned only if the `offline_access` scope was granted.

## ID token structure

### Legacy

<AuthCodeBlock />

### OIDC-conformant

<AuthCodeBlock />

The `favorite_color` claim must be added through an Auth0 Action. To learn more, read [Create Custom Claims](/docs/secure/tokens/json-web-tokens/create-custom-claims).

## Access token structure (optional)

### Legacy

```bash HTTP lines theme={null}
SlAV32hkKG
```

The returned access token is opaque and only valid for calling the [`/userinfo`](https://auth0.com/docs/api/authentication#get-user-info) endpoint.

### OIDC-conformant

<AuthCodeBlock />

The returned access token is valid for optionally calling the API specified in the `audience` parameter and the [`/userinfo`](https://auth0.com/docs/api/authentication#get-user-info) endpoint (provided that the API uses `RS256` as the <Tooltip href="/docs/glossary?term=signing+algorithm">signing algorithm</Tooltip> and `openid` is used as a `scope` parameter).

If you are not implementing your own resource server (API), then you can use `https://{$account.namespace}/userinfo` as the `audience` parameter, which will return an opaque access token.

## Learn more

* [Access Tokens with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-access-tokens)
* [External APIs with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-apis)
* [Client Credentials Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-client-credentials-flow)
* [Implicit Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-implicit-flow)
* [Refresh Tokens with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-refresh-tokens)
* [Resource Owner Password Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-rop-flow)


# Client Credentials Flow with OIDC
Source: https://auth0.com/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-client-credentials-flow

Learn how the OIDC-conformant pipeline affects the Client Credentials Flow.

The OIDC-conformant pipeline enables the use of the [Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow), which allows applications to authenticate as themselves (rather than on behalf of a user) to programmatically and securely obtain access to an API.

This exchange does not exist in the legacy pipeline; instead, the [Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow) is used to simulate it by creating a **service user**. We strongly discourage this approach in favor of using the Client Credentials Flow, which allows fine-grained permissions to be defined for each API app.

To learn how to execute a Client Credentials Flow, read [Call API Using the Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow/call-your-api-using-the-client-credentials-flow).

## Learn more

* [Access Tokens with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-access-tokens)
* [External APIs with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-apis)
* [Authorization Code Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-auth-code-flow)
* [Implicit Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-implicit-flow)
* [Refresh Tokens with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-refresh-tokens)
* [Resource Owner Password Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-rop-flow)


# Delegation with OIDC
Source: https://auth0.com/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-delegation

Learn how the OIDC-conformant pipeline affects your use of delegation.

<Warning>
  By default, delegation is disabled for tenants without an add-on in use as of 8 June 2017. Legacy tenants who currently use an add-on that requires delegation may continue to use this feature. If delegation functionality is changed or removed from service at some point, customers who currently use it will be notified beforehand and given ample time to migrate.
</Warning>

Traditionally, delegation is used to:

* Exchange an <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> issued to one application for a new one issued to a different application.
* Get a fresh ID token using a [refresh token](/docs/secure/tokens/refresh-tokens).
* Exchange an ID token for a third-party (e.g., Firebase, AWS) API token.

Because the OIDC-conformant pipeline requires that ID tokens no longer be used to secure APIs and <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip> be used only at the [`/oauth/token`](https://auth0.com/docs/api/authentication#refresh-token) endpoint; the [`/delegation`](https://auth0.com/docs/api/authentication#delegation) endpoint is deprecated.

OIDC-conformant applications cannot be the source or target of delegation requests.

## Third-party APIs

Because no OIDC-compliant mechanism exists to get third-party (e.g., Firebase, AWS) API tokens, delegation can still be used to obtain third-party API tokens.

## Learn more

* [Access Tokens with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-access-tokens)
* [External APIs with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-apis)
* [Authorization Code Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-auth-code-flow)
* [Client Credentials Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-client-credentials-flow)
* [Refresh Tokens with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-refresh-tokens)
* [Single Sign-On with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-sso)


# Implicit Flow with OIDC
Source: https://auth0.com/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-implicit-flow

Learn how the OIDC-conformant pipeline affects the Implicit Flow.

Traditionally, the [Implicit Flow](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post) was used by applications that were incapable of securely storing secrets. Using this flow is no longer considered a best practice for requesting <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip>; new implementations should use [Authorization Code Flow with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce). However, when used with Form Post response mode, Implicit Flow does offer a streamlined workflow if the application needs only an <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> to perform user authentication; in these cases, it would be used as part of the [Hybrid Flow](/docs/get-started/authentication-and-authorization-flow/hybrid-flow).

<Tooltip href="/docs/glossary?term=Refresh+tokens">Refresh tokens</Tooltip> will no longer be returned when using the Implicit Flow for authentication.

In addition, the OIDC-conformant pipeline affects the Implicit Flow in the following areas: authentication request, authentication response, ID token structure, and access token structure.

## Authentication request

### Legacy

```http lines theme={null}
GET /authorize?
    response_type=token
    &scope=openid email favorite_color offline_access
    &client_id=123
    &state=af0ifjsldkj
    &redirect_uri=https://app.example.com
    &device=my-device-name
```

The `device` parameter is only needed if requesting a refresh token by passing the `offline_access` scope. To learn more, read [Refresh Tokens](/docs/secure/tokens/refresh-tokens).

### OIDC-conformant

```http lines theme={null}
GET /authorize?
    response_type=token id_token
    &scope=openid email
    &client_id=123
    &state=af0ifjsldkj
    &nonce=jxdlsjfi0fa
    &redirect_uri=https://app.example.com
    &audience=https://api.example.com
```

* `response_type` indicates that we want to receive both an access token and ID token.
* Refresh tokens are not allowed in the implicit grant. Use `prompt=none` instead. To learn more read [Configure Silent Authentication](/docs/authenticate/login/configure-silent-authentication).
* `favorite_color` is no longer a valid scope.
* `audience` is optional.
* `nonce` must be a cryptographically secure random string. To learn more, read [Mitigate Replay Attacks When Using the Implicit Flow](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post/mitigate-replay-attacks-when-using-the-implicit-flow).

## Authentication response

### Legacy

```json lines theme={null}
HTTP/1.1 302 Found
Location: https://app.example.com/#
    access_token=SlAV32hkKG
    &expires_in=86400
    &state=af0ifjsldk
    &id_token=eyJ...
    &refresh_token=8xLOxBtZp8
    &token_type=Bearer
```

* The returned access token is valid for calling the [`/userinfo`](https://auth0.com/docs/api/authentication#get-user-info) endpoint.
* A refresh token will be returned only if a `device` parameter was passed and the `offline_access` scope was requested.

### OIDC-conformant

```json lines theme={null}
HTTP/1.1 302 Found
Location: https://app.example.com/#
    access_token=eyJ...
    &expires_in=86400
    &state=af0ifjsldk
    &id_token=eyJ...
    &token_type=Bearer
```

* The returned access token is valid for calling the [`/userinfo`](https://auth0.com/docs/api/authentication#get-user-info) endpoint (provided that the API specified by the `audience` param uses `RS256` as [signing algorithm](/docs/get-started/applications/signing-algorithms)) and optionally the <Tooltip href="/docs/glossary?term=resource+server">resource server</Tooltip> specified by the `audience` parameter.
* If using `response_type=id_token`, Auth0 will only return an ID token.
  Refresh Tokens are not allowed in the implicit grant. Use `prompt=none` instead.

## ID token structure

### Legacy

<AuthCodeBlock />

### OIDC-conformant

<AuthCodeBlock />

* The `favorite_color` claim must be namespaced and added through a rule. To learn more, read [Create Namespaced Custom Claims](/docs/secure/tokens/json-web-tokens/create-custom-claims).
* After validating the ID token, the application must validate the <Tooltip href="/docs/glossary?term=nonce">nonce</Tooltip> to mitigate replay attacks.

## Access token structure (optional)

### Legacy

```bash HTTP lines theme={null}
SlAV32hkKG
```

The returned Access Token is opaque and only valid for calling the `/userinfo` endpoint.

### OIDC-conformant

<AuthCodeBlock />

* The returned access token is a <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> valid for calling the `/userinfo` endpoint (provided that the API specified by the `audience` param uses `RS256` as [signing algorithm](/docs/get-started/applications/change-application-signing-algorithms)) as well as the resource server specified by the `audience` parameter.
* An opaque access token could still be returned if `/userinfo` is the only specified <Tooltip href="/docs/glossary?term=audience">audience</Tooltip>.

## Learn more

* [Access Tokens with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-access-tokens)
* [External APIs with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-apis)
* [Authorization Code Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-auth-code-flow)
* [Client Credentials Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-client-credentials-flow)
* [Delegation with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-delegation)
* [Refresh Tokens with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-refresh-tokens)


# Refresh Tokens with OIDC
Source: https://auth0.com/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-refresh-tokens

Learn how the OIDC-conformant pipeline affects your use of refresh tokens.

With the OIDC-conformant pipeline, <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip>:

* Will no longer be returned when using the [implicit grant](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post) for authentication.
* Can be used by [confidential applications](/docs/get-started/applications/confidential-and-public-applications).
* Can be used with [Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation) by public applications when using the Authorization Code Flow with PKCE.
* Should use the [`/oauth/token`](https://auth0.com/docs/api/authentication#refresh-token) endpoint to get new tokens because the [`/delegation`](https://auth0.com/docs/api/authentication#delegation) endpoint is deprecated.

In addition, differences exist in the refresh token structure. To learn more, read [Refresh Tokens](/docs/secure/tokens/refresh-tokens).

## Legacy (delegation)

```json lines theme={null}
POST /delegation
Content-Type: 'application/json'
{
  "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
  "client_id": "...",
  "refresh_token": "...",
  "scope": "openid profile"
}
```

## OIDC-conformant (token endpoint)

```http lines theme={null}
POST /oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=123&client_id=123&client_secret=123&scope=openid+profile&audience=https%3A%2F%2Fapi.example.com
```

* `audience` and `client_secret` parameters are optional.
* `client_secret` is not needed when requesting a `refresh_token` for a public application.

<Warning>
  Refresh Tokens must be kept confidential in transit and storage, and they should be shared only among the authorization server and the client to whom the refresh tokens were issued.
</Warning>

## Learn more

* [Access Tokens with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-access-tokens)
* [External APIs with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-apis)
* [Authorization Code Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-auth-code-flow)
* [Client Credentials Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-client-credentials-flow)
* [Delegation with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-delegation)
* [Implicit Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-implicit-flow)


# Resource Owner Password Flow with OIDC
Source: https://auth0.com/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-rop-flow

Learn how the OIDC-conformant pipeline affects the Resource Owner Password (ROP) Flow.

The [Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow) (sometimes called <Tooltip href="/docs/glossary?term=Resource+Owner">Resource Owner</Tooltip> Password Grant or ROPG) is used by highly-trusted applications to provide active authentication. Unlike the authorization code and implicit grants, this authentication mechanism does not redirect users to Auth0. It authenticates users with a single request, exchanging their password credentials for a token.

The OIDC-conformant pipeline affects the Resource Owner Password Flow in the following areas:

* Authentication request
* Authentication response
* <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> structure
* <Tooltip href="/docs/glossary?term=Access+token">Access token</Tooltip> structure

## Authentication request

### Legacy

```json lines theme={null}
POST /oauth/ro HTTP 1.1
Content-Type: application/json
{
  "grant_type": "password",
  "client_id": "123",
  "username": "alice",
  "password": "A3ddj3w",
  "connection": "my-database-connection",
  "scope": "openid email favorite_color offline_access",
  "device": "my-device-name"
}
```

The `device` parameter is only needed if requesting a <Tooltip href="/docs/glossary?term=refresh+token">refresh token</Tooltip> by passing the `offline_access` scope.

### OIDC-conformant

```json lines theme={null}
POST /oauth/token HTTP 1.1
Content-Type: application/x-www-form-urlencoded
grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fpassword-realm&client_id=123&username=alice&password=A3ddj3w&realm=my-database-connection&scope=openid+email+offline_access&audience=https%3A%2F%2Fapi.example.com
```

* The endpoint to execute credential exchanges is `/oauth/token`.
* Auth0's own grant type is used to authenticate users from a specific connection (`realm`). The standard OIDC password grant is also supported, but it does not accept Auth0-specific parameters such as `realm`.
* `favorite_color` is no longer a valid scope.
* The `device` parameter is removed.
* The `audience` parameter is optional.

## Authentication response

### Legacy

```json lines theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
    "access_token": "SlAV32hkKG",
    "token_type": "Bearer",
    "refresh_token": "8xLOxBtZp8",
    "expires_in": 3600,
    "id_token": "eyJ..."
}
```

* The returned access token is only valid for calling the [`/userinfo`](https://auth0.com/docs/api/authentication#get-user-info) endpoint.
* A Refresh Token will be returned only if a `device` parameter was passed and the `offline_access` scope was requested.

### OIDC-conformant

```json lines theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
    "access_token": "eyJ...",
    "token_type": "Bearer",
    "refresh_token": "8xLOxBtZp8",
    "expires_in": 3600,
    "id_token": "eyJ..."
}
```

* The returned access token is valid for calling the `/userinfo` endpoint (provided that the API specified by the `audience` param uses `RS256` as [signing algorithm](/docs/get-started/applications/signing-algorithms)) and optionally the <Tooltip href="/docs/glossary?term=resource+server">resource server</Tooltip> specified by the `audience` parameter.
* The ID token will be forcibly signed using `RS256` if requested by a public application. To learn more, read [Confidential and Public Applications](/docs/get-started/applications/confidential-and-public-applications).
* A refresh token will be returned only if the `offline_access` scope was granted.

## ID Token structure

### Legacy

<AuthCodeBlock />

### OIDC-conformant

<AuthCodeBlock />

* The ID token will be forcibly signed using `RS256` if requested by a public application.
* The `favorite_color` claim must be namespaced and added through a rule. To learn more, read [Create Namespaced Custom Claims](/docs/secure/tokens/json-web-tokens/create-custom-claims).

## Access Token structure (optional)

### Legacy

```json JSON lines theme={null}
SlAV32hkKG
```

The returned Access token is opaque and only valid for calling the `/userinfo` endpoint.

### OIDC-conformant

<AuthCodeBlock />

* The returned access token is a <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> valid for calling the `/userinfo` endpoin (provided that the API specified by the `audience` parameter uses `RS256` as <Tooltip href="/docs/glossary?term=signing+algorithm">signing algorithm</Tooltip>) as well as the resource server specified by the `audience` parameter.
* Note that an opaque access token could still be returned if `/userinfo` is the only specified <Tooltip href="/docs/glossary?term=audience">audience</Tooltip>.

## Standard password grant requests

The Auth0 password realm grant is not defined by standard OIDC, but it is suggested as an alternative to the legacy resource owner endpoint because it supports the Auth0-specific `realm` parameter. The [standard OIDC flow is also supported](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow) when using OIDC authentication.

## Learn more

* [Access Tokens with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-access-tokens)
* [External APIs with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-apis)
* [Authorization Code Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-auth-code-flow)
* [Client Credentials Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-client-credentials-flow)
* [Implicit Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-implicit-flow)
* [Refresh Tokens with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-refresh-tokens)


# Single Sign-On with OIDC
Source: https://auth0.com/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-sso

Learn how the OIDC-conformant pipeline affects your use of Single Sign-On (SSO).

In the context of the OIDC-conformant authentication pipeline, single sign-on (<Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip>) must happen at the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip> (i.e., Auth0) rather than the application, which means that you must employ <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> and redirect users to the login page. To learn more, read [Universal Login](/docs/authenticate/login/auth0-universal-login) and [Single Sign-On](/docs/authenticate/single-sign-on).

At a general level, when performing SSO:

1. If the user is not logged in locally, you should redirect them to your Auth0 login page (`/authorize`) for authentication using a redirect-based flow, such as the [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow) or [Implicit Flow](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post), depending on the type of application.
2. If the user was already logged in through SSO, Auth0 will immediately authenticate them without needing to re-enter credentials.

To determine whether users are logged in via SSO, use silent authentication, which either re-authenticates a user if they are already logged in or returns an error if they need to authenticate. In the legacy authentication pipeline, this could be achieved by using the `/ssodata` endpoint, which is deprecated in the OIDC-conformant pipeline. To learn more about how to configure silent authentication, read [Configure Silent Authentication](/docs/authenticate/login/configure-silent-authentication).

## Learn more

* [Access Tokens with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-access-tokens)
* [External APIs with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-apis)
* [Authorization Code Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-auth-code-flow)
* [Client Credentials Flow with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-client-credentials-flow)
* [Delegation with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-delegation)
* [Refresh Tokens with OIDC](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-refresh-tokens)


# Redirect Users
Source: https://auth0.com/docs/authenticate/login/redirect-users-after-login

Describes how to redirect users to URLs that have not been added to the AllowList.

You can return users to specific pages (URLs) within your application after validating their <Tooltip href="/docs/glossary?term=ID+Tokens">ID Tokens</Tooltip> (authentication). To see an example of how this works, try the [React: Login Quickstart](/docs/quickstart/spa/react).

## Redirect users to callback URLs on the AllowList

Because callback URLs can be manipulated by unauthorized parties, Auth0 recognizes only URLs on the AllowList set in the **Allowed Callback URLs** field of an [Application's Settings](https://manage.auth0.com/#/applications/\{yourClientId}/settings) as valid. To return users to callback URLs on the AllowList, it is necessary for your application to know how to continue the user on their journey.

There are two methods for doing this:

* Using cookies and browser sessions
* Using `state` parameters

During a user's authentication, the `redirect_uri` request parameter is used as a callback URL. This is where your application receives and processes the response from Auth0, and is often the URL to which users are redirected once the authentication is complete. To learn more about how the `redirect_uri` works, see [OAuth 2.0 Authorization Framework](/docs/authenticate/protocols/oauth).

<Tabs>
  <Tab title="Cookie or browser session">
    You can use a cookie or the browser session to store a return URL value. This is a simple solution to implement, however, it can cause issues in cases where a cookie does not persist. There are two separate user sessions initiated in this situation. Each serves a separate purpose and requires some consideration to achieve the desired user experience.

    * **Auth0-provided SSO Session**: Auth0 provides a session for enabling [Single Sign On (SSO)](/docs/authenticate/single-sign-on) to allow your user to maintain an authentication session without being prompted for credentials more than once. This session is maintained by Auth0 and referenced as a cookie bound to your tenant domain (or `CNAME`). There are two [tenant settings](/docs/manage-users/sessions/configure-session-lifetime-settings) that determine the length of the Auth0 Session:

      * The `idle_session_lifetime` is how long the session will remain alive without interaction.
      * The `session_lifetime` is the maximum duration that the session is allowed to remain alive.

      These settings apply to all applications within your tenant and should be configured to align with the security model that matches your use case.
    * **Application Session**: Your application must also maintain a concept of a session. Throughout the user session, your application may need to request additional tokens or renew expired ones. You should store these tokens in your application and reference them using an identifier passed back to the browser using a secure cookie.

    Once your user has authenticated with Auth0 it is up to your application to determine how long it persists this session.
  </Tab>

  <Tab title="State parameters">
    As an alternative method, you can create a deep link using the `state` parameter which your callback would interpret to determine a forwarding path. This solution takes a little more work to implement but guarantees that the application has the information it needs once the redirect is complete. To learn more, read [Prevent Attacks and Redirect Users with OAuth0 2.0 State Parameters](/docs/secure/attack-protection/state-parameters).

    Using this method, you send a random value when starting an authentication request and validate the received value when processing the response (this implies you store something on the client application side, in session or another medium, that allows you to perform the validation). If you receive a response with a state that does not match, you were likely been the target of an attack because this is either a response for an unsolicited request or someone trying to forge the real response.

    Your application type determines the best place to keep the data that allows your app to validate the response. For example, assuming a progressive web app is leveraging a SPA framework then it could store this in local storage while a traditional web app framework would store it in server-side session.
  </Tab>
</Tabs>

## Redirect users to other URLs

Sometimes, the callback URL is not necessarily where you want users redirected after authentication. For example, if a user intends to access a protected page in your application, and that action triggers the request to authenticate, you can store that URL to redirect the user back to their intended page after the authentication finishes. Store the desired URL using the following methods:

* [Redirect users with state parameters](/docs/secure/attack-protection/state-parameters)
* [Redirect users from within rules](/docs/customize/rules/redirect-users)

Choose the option that works best for your application type and the type of [flow](/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use) that you are using. Create the necessary logic in your application to retrieve the stored URL and redirect your users where you want them to go. The [Auth0 SDKs](/docs/libraries) also include support for redirect URLs.

## Learn more

* [Redirect Users with Alternative Logout](/docs/authenticate/login/logout/redirect-users-after-logout)
* [Understand How Progressive Profiling Works](/docs/manage-users/user-accounts/user-profiles/progressive-profiling)


# Hosted Login vs. Embedded Login
Source: https://auth0.com/docs/authenticate/login/universal-vs-embedded-login

Describes the differences between hosted login (Universal Login) and embedded login.

When you design the login experience for your application, you’ll need to decide if you want it to be hosted ([Universal Login](/docs/authenticate/login/auth0-universal-login)) or embedded.

## Hosted login

In a hosted login flow, the application redirects the user to the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip> to perform authentication, and then the authorization server returns the user to the application.

### Universal Login flow

In the typical user authentication experience with <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>:

1. Your application triggers an authentication request by invoking an Auth0 SDK’s login method or by calling the [Auth0 Authentication API Login endpoint](https://auth0.com/docs/api/authentication/login/) directly.
2. Your application redirects the user to the Auth0 authorization server (your Auth0 tenant).
3. Auth0 checks for a session cookie on the [Auth0 Session Layer](/docs/manage-users/sessions/session-layers).

   * If a session cookie is not found, Auth0 redirects the user to Universal Login to authenticate and creates an associated session cookie.
   * If a session cookie is found, Auth0 uses it to authenticate the user.
4. Auth0 returns the user to your application with an [ID token](/docs/secure/tokens/id-tokens) and an [access token](/docs/secure/tokens/access-tokens).

## Embedded login

In an embedded login flow, the user authenticates directly within your application. The application serves the login form, collects the user’s credentials, sends that data to the authentication provider, and then receives a response with the user’s <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> and <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>.

For web applications, embedded login uses [cross-origin authentication](/docs/authenticate/login/cross-origin-authentication) unless you [configure a custom domain](/docs/customize/custom-domains) for your Auth0 tenant. Cross-origin authentication uses third-party cookies to allow for secure authentication transactions across different origins.

## Feature comparison

<table>
  <thead>
    <tr>
      <th><strong>Feature</strong></th>
      <th><strong>Hosted</strong></th>
      <th><strong>Embedded</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong><a href="/docs/authenticate/single-sign-on">Single Sign-on</a></strong></td>
      <td>Full support with Universal Login through the use of <a href="/docs/manage-users/sessions">session cookies</a> on the Auth0 Authorization Server (your Auth0 tenant).</td>
      <td>Limited support. Web applications that use the <a href="/docs/libraries/lock/lock-api-reference#checksession-">Lock</a> or <a href="/docs/libraries/auth0js#using-checksession-to-acquire-new-tokens">Auth0.js</a> libraries can share sessions. Native applications can share sessions with web applications through <a href="/docs/authenticate/single-sign-on/native-to-web">Native to Web SSO</a>.</td>
    </tr>

    <tr>
      <td><strong><a href="/docs/customize">Customization</a></strong></td>
      <td>Universal Login allows you to easily customize many parts of the experience (including theming, page templates, text elements, and prompts). <br /><br />Full customization is supported through <a href="/docs/customize/login-pages/advanced-customizations">Advanced Customizations for Universal Login.</a></td>
      <td>Highest degree of customization, since you fully control the UI/UX of your application.</td>
    </tr>

    <tr>
      <td><strong>Feature management</strong></td>
      <td>Features can be centrally managed within the Auth0 Dashboard or through the Auth0 Management API.<br /><br />For example, when you enable/disable MFA in your Dashboard, it will be immediately reflected in subsequent user logins.</td>
      <td>Features must be managed for each application individually.<br /><br />For example, if you wanted to implement MFA for your web application and for your native application, you’d have to update and release new versions for both.</td>
    </tr>

    <tr>
      <td><strong>User experience</strong></td>
      <td>Users are redirected between your application and the Auth0 Authorization Server during authentication.<br /><br />For native applications, this requires implementation of universal/deep links.</td>
      <td>Users remain in your application during authentication.</td>
    </tr>

    <tr>
      <td><strong>Security and maintenance</strong></td>
      <td>Auth0 monitors security trends and updates Universal Login accordingly.</td>
      <td>You are responsible for following security best practices and implementing provided technologies accordingly.</td>
    </tr>
  </tbody>
</table>

## Best practice

According to [RFC 8252: OAuth 2.0 for Native Apps on IETF](https://www.rfc-editor.org/rfc/rfc8252.txt), only external user-agents (such as the browser) should be used by native applications for authentication flows.

## Learn more

* [Prevent Common Cybersecurity Threats](/docs/secure/security-guidance/prevent-threats)
* [Troubleshoot Custom Domains](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-custom-domains)


# Passwordless Authentication
Source: https://auth0.com/docs/authenticate/passwordless

Learn about the available methods of passwordless authentication supported by Auth0.

<Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> authentication provides users with a seamless and more secure login experience. As technology advances, traditional methods of authentication, such as usernames and passwords, become more prone to cyber attacks (like phishing or keylogging) and potential breaches.

With passwordless authentication, users no longer need to remember or manually enter a password to access an application. Instead, they can use a variety of authentication methods that rely on time-based access links and tokens, stored passkeys, biometrics, or social accounts.

By eliminating the reliance on passwords and other memorized codes, you can provide users with a more convenient way of accessing applications while also reducing the likelihood of data breaches due to stolen or weak passwords.

Auth0 currently supports the following methods of passwordless authentication:

* [Social login](#social-login)
* [Passkeys](#passkeys)
* [SMS-based passwordless authentication](#sms-based-passwordless-authentication)
* [Email-based passwordless authentication](#email-based-passwordless-authentication)
* [Biometrics (WebAuthn)](#biometrics-webauthn-)

Each of these methods provides a unique passwordless login experience to users. To learn more about which method is right for your needs, review the sections below.

### Passwordless connections vs. passwordless authentication

A passwordless connection is a distinct connection type from database, social, or enterprise connections. Passwordless connections are used specifically for:

* [SMS-based passwordless authentication](#sms-based-passwordless-authentication)
* [Email-based passwordless authentication](#email-based-passwordless-authentication)

Even though a user from an Auth0 user database or social provider might share the same email address, the identity associated with their passwordless connection is distinct. [Account linking](/docs/manage-users/user-accounts/user-account-linking) can be used to associate passwordless connection identities with other connection identities.

<Callout icon="file-lines">
  You cannot create passwordless users from the Auth0 Dashboard. Create them directly from the [Management API](https://auth0.com/docs/api/management/v2/users/post-users) if signup is disabled. In the Connection field, use email for passwordless users using an email address and SMS for passwordless users using a mobile phone number.
</Callout>

## Social Login

Social login is a method of authentication that allows users to log in to an application using existing credentials from a social <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>, such as Google or Facebook. As users frequently have their social credentials stored in their browser or device, social login provides a frictionless user experience that requires minimal manual interaction with your application.

The general workflow for social login is as follows:

1. A user arrives at your application’s login screen and selects the **Continue with \[provider]** option.
2. The user follows prompts from the selected provider to authenticate with their existing social credentials.
3. The user is redirected to your application to complete the login process.

For web-based applications, Auth0 supports multiple social identity providers out of the box. Visit the [Social Login](https://marketplace.auth0.com/categories/social-login) section of Auth0 Marketplace to review a full list of supported providers. If a specific provider is not available, you can also configure [custom social login connections](/docs/authenticate/identity-providers/social-identity-providers/oauth2) through the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

For native applications, Auth0 supports social login for select providers:

* [Apple](/docs/authenticate/identity-providers/social-identity-providers/apple-native)
* [Facebook](/docs/authenticate/identity-providers/social-identity-providers/facebook-native)
* Google (coming soon!)

For these applications, Auth0 supports social connection token exchange, which enables authentication without the need for web redirects.

## Passkeys

Passkeys are a phishing-resistant alternative to traditional authentication factors modeled from FIDO® W3C Web Authentication (WebAuthn) and Client to Authenticator Protocol (CTAP) specifications.

Auth0 supports passkeys as an authentication method for database connections and offers two methods of implementation:

* [Universal Login passkeys](/docs/authenticate/database-connections/passkeys) for web-based applications
* [Native passkeys](/docs/authenticate/database-connections/passkeys/native-passkeys-for-mobile-applications) for Android and iOS applications

Passkeys reduce the friction experienced with single-device authentication methods by allowing credentials to sync across devices. Cross-device authentication eliminates the need for users to re-enroll each of their devices.

An example passkeys workflow for web-based applications is as follows:

1. A user arrives at your application’s Universal Login page and enters their email address.
2. The user then has the choice to create a passkey or continue with traditional authentication.
3. When the user selects **Create a new passkey**, the browser’s passkey flow initiates and prompts the user to authenticate with their device credentials, such as biometrics.
4. After local authentication is complete, the passkey is saved to the user’s device and synced with their passkey provider (such as iCloud or Google).

After this process is complete, the user can authenticate with the saved passkey upon subsequent logins to your application.

## SMS-Based Passwordless Authentication

SMS-based passwordless authentication allows users to access applications using single-use codes known as one-time passwords (OTP). With this implementation, OTPs are sent to users’ phone numbers via SMS.

The general workflow for SMS-based OTPs is as follows:

1. A user arrives at your application’s login screen and enters their phone number.
2. Auth0 sends the user an OTP through SMS.
3. The user copies the code and returns to your login screen.
4. The user enters the code in the space provided and logs in to your application.

To learn more about configuring SMS-based passwordless authentication for different login types, review the resources below:

* [Passwordless Authentication with Universal Login](/docs/authenticate/passwordless/passwordless-with-universal-login)
* [Passwordless Authentication with Classic Login](/docs/authenticate/passwordless/implement-login/universal-login)
* [Passwordless Authentication with Embedded Login](/docs/authenticate/passwordless/implement-login/embedded-login)

<Callout icon="file-lines">
  This category of passwordless authentication is currently treated as a unique connection type in your tenant, separate from other database, social, or enterprise connections.

  When a user authenticates with this method, their profile is created on the passwordless connection using Auth0 as the Identity Provider (IdP). As you cannot ensure users will log in with the same email or phone number every time, users may end up with multiple user profiles in the Auth0 datastore. If duplicates are created, you can associate multiple user profiles by [linking their accounts](/docs/manage-users/user-accounts/user-account-linking).

  In some scenarios, a user profile created through this type of passwordless connection may share an identifier (such as email or phone number) with a profile associated with another type of connection, such as enterprise or social. If this occurs, you can use [account linking](/docs/manage-users/user-accounts/user-account-linking) to associate passwordless profiles with identities from other connections.
</Callout>

## Email-Based Passwordless Authentication

Email-based passwordless authentication encompasses two methods:

* [One-time passwords](#one-time-passwords)
* [Magic links](#magic-links)

<Callout icon="file-lines">
  This category of passwordless authentication is currently treated as a unique connection type in your tenant, separate from other database, social, or enterprise connections.

  When a user authenticates with this method, their profile is created on the passwordless connection using Auth0 as the Identity Provider (IdP). As you cannot ensure users will log in with the same email or phone number every time, users may end up with multiple user profiles in the Auth0 datastore. If duplicates are created, you can associate multiple user profiles by [linking their accounts](/docs/manage-users/user-accounts/user-account-linking).

  In some scenarios, a user profile created through this type of passwordless connection may share an identifier (such as email or phone number) with a profile associated with another type of connection, such as enterprise or social. If this occurs, you can use [account linking](/docs/manage-users/user-accounts/user-account-linking) to associate passwordless profiles with identities from other connections.
</Callout>

### One-time passwords

This method of passwordless authentication allows users to access applications using single-use codes known as one-time passwords (OTP). With this implementation, OTPs are sent to users through their email.

The general workflow for email-based OTPs is as follows:

1. A user arrives at your application’s login screen and enters either their email.
2. Auth0 sends an OTP to the user’s email.
3. The user copies the code and returns to your login screen.
4. The user enters the code in the space provided and logs in to your application.

To learn more about configuring email-based passwordless authentication for different login types, review the resources below:

* [Passwordless Authentication with Universal Login](/docs/authenticate/passwordless/passwordless-with-universal-login)
* [Passwordless Authentication with Classic Login](/docs/authenticate/passwordless/implement-login/universal-login)
* [Passwordless Authentication with Embedded Login](/docs/authenticate/passwordless/implement-login/embedded-login)

### Magic Links

Magic links are a method of passwordless authentication that allow users to access an application through a link sent to their email. If the user does not access the link within a specific timeframe, the link becomes inaccessible.

The general workflow for magic links is as follows:

1. A user arrives at your application’s login screen and enters their email.
2. Auth0 sends a magic link to the user at the provided email.
3. The user selects the magic link in their email and automatically logs in to your application.

Magic links can only be implemented in Classic Login. To learn more, review the following resources:

* [Passwordless Authentication with Magic Links](/docs/authenticate/passwordless/authentication-methods/email-magic-link)
* [Passwordless Authentication with Classic Login](/docs/authenticate/passwordless/implement-login/universal-login)

## Biometrics (WebAuthn)

Biometrics is a method of passwordless authentication that uses an individual’s physical attributes to verify their identity and grant them access to an application. Auth0 currently supports biometric authentication using fingerprint scans and facial recognition.

<Callout icon="file-lines">
  While Auth0 still supports the legacy Identifier First with Biometrics authentication method, it is strongly recommended that you use [passkey-based authentication](/docs/authenticate/passwordless#passkeys) instead.
</Callout>

To implement biometrics for your application, the following configurations are required:

* Enabling [Universal Login](/docs/authenticate/login/auth0-universal-login).
* Setting up a [database connection](/docs/authenticate/database-connections).
* Configuring [Identifier First + Biometrics authentication](/docs/authenticate/login/auth0-universal-login/identifier-first).

When implemented, users can choose to enroll their devices in biometrics after logging in to your application with traditional credentials. To enroll in biometrics, a user must be using a device with biometric capabilities, such as a mobile smart device.

The general workflow for biometric authentication is as follows:

1. A user arrives at your application’s Universal Login page and enters their email address.
2. The user first authenticates with their traditional credentials. Then, they are prompted to enroll their device in biometrics.
3. If the user chooses to enroll, they follow their device’s prompts to complete the biometric setup process.

After the user enrolls their device, they can use biometrics as their primary method of authentication upon subsequent logins to your application.

To learn more about biometric authentication, review [Configure WebAuthn with Device Biometrics for Passwordless Authentication](/docs/authenticate/login/auth0-universal-login/passwordless-login/webauthn-device-biometrics).

## Learn more

* [Passwordless Connections Best Practices](/docs/authenticate/passwordless/best-practices)
* [Using Passwordless APIs](/docs/authenticate/passwordless/implement-login/embedded-login/relevant-api-endpoints)


# Passwordless Authentication Methods
Source: https://auth0.com/docs/authenticate/passwordless/authentication-methods

Describes the various authentication methods supported by Auth0 passwordless connections, including email, magic link, and SMS.

With <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> connections, users can log in without a password. Instead, they can use a variety of other authentication methods. Auth0 Passwordless connections support the following authentication methods:

<table>
  <thead>
    <tr>
      <th>Factor</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/authenticate/passwordless/authentication-methods/email-otp">Email</a></td>
      <td>The user is asked to enter their email address, to which Auth0 sends a one-time-use code. The user enters the code into your application.</td>
    </tr>

    <tr>
      <td><a href="/docs/authenticate/passwordless/authentication-methods/email-magic-link">Magic Link</a></td>
      <td>The user is asked to enter their email address, to which Auth0 sends an email with a link in it. The user clicks the link and is directly logged in to your application.</td>
    </tr>

    <tr>
      <td><a href="/docs/authenticate/passwordless/authentication-methods/sms-otp">SMS</a></td>
      <td>The user is asked to enter their phone number, to which Auth0 sends a one-time-use code. By default, Auth0 uses Twilio to send the code, but if you have a custom SMS gateway, you can modify your connection to use that instead.</td>
    </tr>
  </tbody>
</table>


# Single Sign-On
Source: https://auth0.com/docs/authenticate/single-sign-on

Learn what Single Sign-on (SSO) is and how it works.

<Tooltip href="/docs/glossary?term=Single+Sign-on">Single Sign-on</Tooltip> (SSO) occurs when a user logs in to one application and is then signed in to other applications automatically, regardless of the platform, technology, or domain the user is using. The user signs in only one time, hence the name of the feature (Single Sign-on).

For example, if you log in to a Google service such as Gmail, you are automatically authenticated to YouTube, AdSense, Google Analytics, and other Google apps. Likewise, if you log out of your Gmail or other Google apps, you are automatically logged out of all the apps; this is known as Single Logout.

SSO provides a seamless experience for users when using your applications and services. Instead of having to remember separate sets of credentials for each application or service, users can simply log in once and access your full suite of applications.

Whenever users go to a domain that requires authentication, they are redirected to the authentication domain where they may be asked to log in. If the user is already logged in at the authentication domain, they can be immediately redirected to the original domain without signing in again.

## How it works

Single Sign-on and Single Logout are possible through the use of [sessions](/docs/manage-users/sessions). There may be up to three different sessions for a user with SSO:

* Local session maintained by the application
* <Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip> session, if SSO is enabled
* <Tooltip href="/docs/glossary?term=Identity+Provider+%28IdP%29">Identity Provider (IdP)</Tooltip> session, if the user chose to log in through an <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> (such as Google, Facebook, or an enterprise <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> Identity Provider)

With SSO, a central domain performs authentication and then shares the session with other domains. The way a session is shared may differ between SSO protocols, but the general concept is the same.

For example, the authentication domain may generate a signed [JSON Web Token (JWT)](/docs/secure/tokens/json-web-tokens) (encrypted using JSON Web Encryption (JWE)), which contains all the information needed to identify the user for any other domain requiring authentication. This token is passed to the client, but because it is signed, it cannot be modified in any way by the client. The token can be passed to the original domain by a redirect and used by the authentication domain and any other domains to identify the user.

## SSO with Universal Login

The easiest and most secure way to implement Single Sign-on (SSO) with Auth0 is by using [Universal Login](/docs/authenticate/login/auth0-universal-login) for authentication. In fact, currently SSO is only possible with native platforms (like iOS or Android) if the application uses <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>. The [Swift](/docs/quickstart/native/ios-swift) and [Android](/docs/quickstart/native/ios-swift) quick starts provide some examples of using Universal Login.

If you cannot use Universal Login with your application, review the following for additional info on embedded authentication:

* [Lock](/docs/libraries/lock/lock-api-reference)
* [Auth0.js](/docs/libraries/auth0js)

<Callout icon="file-lines">
  If you are using [Passwordless](/docs/authenticate/passwordless/passwordless-with-universal-login) with Single Sign-On, connection parameters `sms` and `email` do not utilize the existing Auth0 session, and the user will be prompted to log in.
</Callout>

### SSO on first login

For SSO with Auth0, the **Central Service** is the Auth0 <Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip>.

Let's look at an example of the SSO flow when a user logs in for the first time:

1. Your application redirects the user to the login page.
2. Auth0 checks to see whether there is an existing SSO cookie.
3. Because this is the first time the user is visiting the login page and no SSO cookie is present, the user will be asked to log in using one of the connections you have configured.

   <Frame>
     <img alt="Example timesheets application login screen" />
   </Frame>
4. Once the user has logged in, Auth0 will set an SSO cookie and redirect the user to your application, returning an ID Token that contains identity information for the user.

### SSO on subsequent logins

Let's look at an example of the SSO flow when a user returns to your website for a subsequent visit:

1. Your application redirects the user to the login page.
2. Auth0 checks to see whether there is an existing SSO cookie.
3. Auth0 finds the SSO cookie, and if necessary, updates it. No login screen is shown.
4. Auth0 redirects the user to your application, returning an ID Token that contains identity information for the user.

### Check user's SSO status

You can check a user's SSO status from an application by calling the `checkSession` method of the `auth0.js` SDK, which will attempt to [silently authenticate](/docs/authenticate/login/configure-silent-authentication) the user within an iframe. Whether the authentication is successful or not indicates whether the user has an active SSO cookie.

## Protocols

### SAML and WS-Federation

Security Assertion Markup Language (SAML) and Web Services Federation (<Tooltip href="/docs/glossary?term=WS-Fed">WS-Fed</Tooltip>) are both [protocols](/docs/authenticate/protocols) that are widely used in SSO implementations. Both SAML and WS-Fed exchange authorization and authentication data in XML format; the main parts of this exchange are the user, the identity provider, and the service provider.

With SAML or WS-Fed:

1. A user requests a resource from the service provider.
2. The service provider checks with the identity provider to see if the user should have access to the resource.
3. The identity provider verifies the user's identity, and if valid, asserts back to the service provider that the user should have access.

### OpenID Connect

<Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) is an authentication protocol commonly used in consumer-facing SSO implementations. The OIDC protocol handles authentication through <Tooltip href="/docs/glossary?term=JSON+Web+Tokens">JSON Web Tokens</Tooltip> and a central identity provider.

With OIDC:

1. A user requests access to an application.
2. The application redirects the user to the identity provider for authentication.
3. The identity provider verifies the user, and if successful, prompts the user to grant data access to the application.
4. If access is granted, the identity provider generates an ID Token, which contains user identity information that the application can consume.
5. The identity provider returns the user to the application.

### AD/LDAP

Lightweight Directory Access Protocol (LDAP) is an application protocol used to access a directory of credentials that can be shared by multiple applications; it is commonly used by intranets. When paired with Active Directory (AD), LDAP provides a centralized location for user identity, so the application makes an authentication request to the LDAP/AD server. The LDAP protocol exchanges information in LDAP Data Interchange Format (LDIF).

## Service-provider-initiated SSO

For [Service-Provider-initiated SSO](/docs/authenticate/single-sign-on/inbound-single-sign-on), Auth0 is the SSO Service Provider (SP).

When a user logs in to an application:

1. The application presents the user with one or more external identity providers.
2. The user selects an identity provider to authenticate with and logs in.
3. Upon successful authentication, the user is returned to the application.

SP-initiated SSO in Auth0 is handled by connections.

## Identity-provider-initiated SSO

For [Identity-Provider-initiated SSO](/docs/authenticate/single-sign-on/outbound-single-sign-on), a third-party Identity Provider (IdP) is the SSO provider.

When a user logs in to an application:

1. The application redirects the user to an identity provider.
2. The third-party identity provider performs authentication and authorization.
3. Upon successful authentication, the user is returned to the application.

When planning an IdP-initiated SSO implementation, you may choose to use Auth0's [SSO Dashboard Extension](/docs/customize/extensions/single-sign-on-dashboard-extension/create-sso-dashboard-application), which allows you to create a dashboard that lists multiple enterprise applications that can be enabled for SSO. This dashboard is then presented to your users to log in.

## Use cases

### Business to Business

For Business to Business (B2B) scenarios, SSO can simplify packaging your application for enterprise consumption. With Auth0, your applications can support common enterprise federation scenarios, such as Active Directory (AD), Lightweight Directory Access Protocol (LDAP), Ping, or Security Assertion Markup Language (SAML). This allows your partners and enterprise customers to log in with their preferred enterprise identity technologies.

* [Case Study: O'Reilly](https://auth0.com/case-studies/oreilly)

### Business to Consumer CIAM

For Business to Consumer (B2C) or Customer Identity Access Management (CIAM) scenarios, SSO can provide frictionless access to your applications or services. You can let customers authenticate through popular social identity providers, such as Google, Facebook, LinkedIn, X, and Microsoft, instead of requiring them to make another account.

* [Case Study: Giving Compass](https://auth0.com/case-studies/giving-compass)

## Learn more

* [Service-Provider-Initiated Single Sign-On](/docs/authenticate/single-sign-on/inbound-single-sign-on)
* [Identity-Provider-Initiated Single Sign-On](/docs/authenticate/single-sign-on/outbound-single-sign-on)
* [API Endpoints for Single Sign-On](/docs/authenticate/single-sign-on/api-endpoints-for-single-sign-on)
* [Troubleshoot SAML Configurations](/docs/troubleshoot/authentication-issues/troubleshoot-saml-configurations)
* [Verify Connections](/docs/troubleshoot/basic-issues/verify-connections)


# API Endpoints for Single Sign-On
Source: https://auth0.com/docs/authenticate/single-sign-on/api-endpoints-for-single-sign-on

Describes Auth0 Authentication API and Management API endpoints relevant when implementing Single Sign-on (SSO).

When implementing <Tooltip href="/docs/glossary?term=Single+Sign-on">Single Sign-on</Tooltip> (SS0) and configuring its settings, the following API endpoints will be helpful to you.

## Authentication API endpoints

### POST /login/callback

For SSO flows initiated by an <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> (IdP), the [POST /login/callback](https://auth0.com/docs/api/authentication#idp-initiated-single-sign-on-sso-flow) endpoint can accept a sign-on <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> request from the identity provider.

## Management API

The <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> features several endpoints designed to help you manage SSO.

To call any of the Management API endpoints, you will need to [obtain an Access Token](https://auth0.com/docs/api/management/v2/tokens).

### Clients

All of your client applications/SSO integrations feature information relevant to your SSO implementation. You can retrieve or change this information by calling one of the Clients endpoints.

Of-interest parameters for each client include:

* `sso`: Flag applicable only for clients created via SSO integrations. If `true`, Auth0 handles SSO; if `false`, the IdP handles SSO.
* `sso_disabled`: Flag used to enable/disable SSO. If `true`, then SSO is disabled; if `false`, SSO is enabled. This option can only be set via the Management API.
* `app_type`: Application type. If the client was created using one of Auth0's built-in SSO integrations, the name of the SSO integration would be listed (e.g., `box` or `concur` instead of `native` or `spa`)

#### Get all clients

The [GET /api/v2/clients](https://auth0.com/docs/api/management/v2#!/Clients/get_clients) endpoint can be used to return information about the client applications you have configured for your tenant.

#### Create a client

The [POST /api/v2/clients](https://auth0.com/docs/api/management/v2#!/Clients/post_clients) endpoint can be used to create a new client application.

#### Get a client

The [GET /api/v2/clients/](https://auth0.com/docs/api/management/v2#!/Clients/get_clients_by_id) endpoint can be used to return information about a specific client you have configured for your tenant.

#### Update a client

The [PATCH /api/v2/clients/](https://auth0.com/docs/api/management/v2#!/Clients/patch_clients_by_id) endpoint can be used to update a specific client, including its SSO-related parameters.

### Tenants

Auth0 allows you to control the following tenant-level parameters that may affect your SSO implementation:

* `session_lifetime`: Length of time for which the user's Auth0 session will stay valid.
* `idle_session_lifetime`: Amount of time that may elapse before the user must sign in again due to inactivity.

### Get tenant settings

The [GET /api/v2/tenants/settings](https://auth0.com/docs/api/management/v2#!/Tenants/get_settings) endpoint retrieves the settings for your tenant.

### Update tenant settings

The [POST /api/v2/connections](https://auth0.com/docs/api/management/v2#!/Tenants/patch_settings) endpoint allows you to update your tenant settings.

## Learn more

* [Deprecation Errors](/docs/troubleshoot/basic-issues/check-deprecation-errors)
* [Check API Calls](/docs/troubleshoot/authentication-issues/check-api-calls)


# Service-Provider-Initiated Single Sign-On
Source: https://auth0.com/docs/authenticate/single-sign-on/inbound-single-sign-on

Overview of Single Sign-on (SSO) initiated by a Service Provider (SP).

For Service-Provider-initiated <Tooltip href="/docs/glossary?term=Single+Sign-On">Single Sign-On</Tooltip> (SSO) implementations, Auth0 is the SSO Service Provider (SP). When a user logs in to an application:

1. The application presents the user with one or more external Identity Providers (IdPs).
2. The user selects an IdP to authenticate with and logs in.
3. Upon successful authentication, the user is returned to the application with an active session.

SP-initiated SSO in Auth0 is handled by connections.

## Auth0 SSO sessions vs. application sessions

When users log in, various [session layers](/docs/manage-users/sessions/session-layers) can be created. For SP-initiated SSO implementations, it's important to understand that the SSO experience is made possible by the Auth0 Session Layer, which is stored centrally on the <Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip>. Leveraging this session layer, users can easily authenticate to different applications, each of which may have its own application session to track whether the user is logged in to it specifically.

## Build your own implementations

### OIDC/OAuth

* Social <Tooltip href="/docs/glossary?term=Identity+Providers">Identity Providers</Tooltip>
* Add a generic OAuth2 Authorization Server to Auth0
* [Auth0 Marketplace](https://marketplace.auth0.com/)

### SAML

* Auth0 provides instructions to configure the following <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> IdPs with Auth0:

  * [Okta](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-okta-as-saml-identity-provider)
  * [OneLogin](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-onelogin-as-saml-identity-provider)
  * [PingFederate 7](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-pingfederate-as-saml-identity-provider)
  * [Salesforce](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-salesforce-as-saml-identity-provider)
  * [SiteMinder](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-siteminder-as-saml-identity-provider)
  * [SSOCircle](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-ssocircle-as-saml-identity-provider)
* We also provide generic instructions to [configure Auth0 as a SAML service provider](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider).
* [Configure Identity-Provider-Initiated Single Sign-On](/docs/authenticate/protocols/saml/saml-sso-integrations/identity-provider-initiated-single-sign-on)

## Limitations

* Native applications can only use [Universal Login](/docs/authenticate/login/auth0-universal-login).
* <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) does not support IdP-initiated SSO.

## Learn more

* [Identity-Provider-Initiated Single Sign-On](/docs/authenticate/single-sign-on/outbound-single-sign-on)
* [API Endpoints for Single Sign-On](/docs/authenticate/single-sign-on/api-endpoints-for-single-sign-on)
* [Troubleshoot SAML Configurations](/docs/troubleshoot/authentication-issues/troubleshoot-saml-configurations)
* [Troubleshoot SAML Errors](/docs/troubleshoot/authentication-issues/saml-errors)


# Native to Web SSO
Source: https://auth0.com/docs/authenticate/single-sign-on/native-to-web

Learn how Auth0's Native to Web SSO works.

Auth0’s Native to Web <Tooltip href="/docs/glossary?term=Single+Sign-On">Single Sign-On</Tooltip> (SSO) feature provides a seamless user experience transitioning authenticated users from your [native application](/docs/authenticate/login/native-login) to your web application.

If your web application relies on embedded WebViews or external browsers to deliver extended or advanced functionality, your users can move between native and web environments in the same authenticated session.

By binding Session Transfer Tokens to the specific device through IP address or ASN, session continuity and security is maintained and ensures the authentication context remains secure throughout the transition.

## How it works

<Frame>
  <img alt="Native to Web SSO workflow" />
</Frame>

1. A user logs in to your native application.
2. Auth0 authenticates the user and returns an access token, refresh token, and ID token.
3. Your native application calls Auth0’s [`/token`](https://auth0.com/docs/api/authentication/authorization-code-flow-with-pkce/get-token-pkce) endpoint to exchange a refresh token for a Session Transfer Token. The Session Transfer Token is bound to a specific IP address or ASN.
4. Auth0 returns the Session Transfer Token for authentication with a web application.
5. Auth0 authorizes the Session Transfer Token as part of the cookie or as a URL parameter, and then returns an [authorization code](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow).
6. The web application exchanges the authorization code for access or refresh tokens at the [`/token`](https://auth0.com/docs/api/authentication/authorization-code-flow/get-token) endpoint.
7. The web application initializes a session for the user.

Learn how to [Configure and Implement Native to Web SSO](/docs/authenticate/single-sign-on/native-to-web/configure-implement-native-to-web)

## Limitations

* Once Native to Web SSO is enabled in a client, the `session_transfer_token` parameter only works for Native to Web SSO
* <Tooltip href="/docs/glossary?term=Refresh+Tokens">Refresh Tokens</Tooltip> originated from a previous Session Transfer Token transaction will not generate new Session Transfer Tokens.


# Configure and Implement Native to Web SSO
Source: https://auth0.com/docs/authenticate/single-sign-on/native-to-web/configure-implement-native-to-web

Learn how to configure your applications to use Native to Web Single Sign-On.

## Configure Native to Web SSO

To use Native to Web <Tooltip href="/docs/glossary?term=Single+Sign-On">Single Sign-On</Tooltip> (SSO), configure your native and web (Single Page App or Regular Web App) to create and manage sessions with the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

You need an [access token](/docs/secure/tokens/access-tokens/management-api-access-tokens) to use the Management API or Auth0 CLI.

To configure Native to Web SSO, you need to create and manage session\_transfer\_tokens and configure your native and web applications.

<Callout icon="file-lines">
  Native to Web SSO supports the following SDKs: [Auth0 Android SDK](https://github.com/auth0/auth0.android/blob/main/EXAMPLES.md#native-to-web-sso-login-ea), [Auth0 Swift SDK](https://github.com/auth0/Auth0.swift/blob/master/EXAMPLES.md#sso-credentials-ea), and [Auth0 React Native SDK](https://github.com/auth0/react-native-auth0/blob/master/EXAMPLES.md#native-to-web-sso-early-access).

  Native to Web SSO support is available in the following tools: [Auth0 Deploy CLI](/docs/deploy-monitor/deploy-cli-tool). [Auth0 Terraform Provider](/docs/deploy-monitor/auth0-terraform-provider) and [Auth0 CLI](https://auth0.github.io/auth0-cli/).

  Native to Web SSO supports any authentication flow that returns a refresh token, such as [Resource Owner Password Flow](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa) and [Authorization Code Flow with Proof Key for Code Exchange](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce).
</Callout>

### Create and manage Session Transfer Tokens

The first Management API call allows your native and web Applications to:

* Create and manage `session_transfer_tokens`
* Create sessions in a web browser via cookies or a URL parameter
* Bind the session to a user's device through an IP address or ASN

For existing applications, make a `PATCH` call to the [Update a Client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) endpoint. To create a new application, make a `POST` call to the [Create a Client](https://auth0.com/docs/api/management/v2/clients/post-clients) endpoint:

```json lines theme={null}
{
  "session_transfer": {
    "can_create_session_transfer_token": false,
    "allowed_authentication_methods": ["cookie", "query"],
    "enforce_device_binding": "ip", // also "none" or "asn",
    "allow_refresh_token": false,
    "enforce_cascade_revocation": true,
    "enforce_online_refresh_tokens": true
  }
}
```

### Configure native applications

Once a user is authenticated, Auth0 returns an [Access token](/docs/secure/tokens/access-tokens), and [ID token](/docs/secure/tokens/id-tokens), and (optionally) a [Refresh token](/docs/secure/tokens/refresh-tokens).

You can configure your native application to exchange a <Tooltip href="/docs/glossary?term=refresh+token">refresh token</Tooltip> for a Session Transfer Token. If your web application does not support cookie injection, your native application also needs to configure your web application’s **Login URI** to inject the Session Transfer Token as a URI parameter.

* Update your native application using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>:

  1. Navigate to [Dashboard > Applications](https://manage.auth0.com/dashboard/#/applications):
  2. Select or [create your application](/docs/get-started/auth0-overview/create-applications#create-applications).
  3. Select the **Settings** tab.
  4. Under **Session Transfer**, enable **Allow Native to Web SSO**.
  5. Select **Require Cascade Revocation** to automatically revoke the web application's session and associated tokens.
  6. Select **Save** to update your application.

<Frame>
  <img alt="Session Transfer Native application" />
</Frame>

* Update your native application using your Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> with the [Update a Client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) endpoint:

<AuthCodeBlock />

* Update your native application using [Auth0 CLI](https://auth0.github.io/auth0-cli/auth0_apps_session-transfer_update.html):

<AuthCodeBlock />

### Configure web applications

Before you enable Session Transfer Token, make sure you have configured your web application’s **Application Login URI** to handle extra parameters. To learn more about URIs, read [Application Settings](/docs/get-started/applications/application-settings#application-uris).

* Update your web application using the Auth0 Dashboard:

  1. Navigate to [Dashboard > Applications](https://manage.auth0.com/dashboard/#/applications):
  2. Select or create your web application.
  3. Select the **Settings** tab.
  4. Under **Session Transfer**, enable **Native to Web SSO Methods**.
  5. Select **Cookie Authentication** and **Query Authentication**.
  6. Enable **Device Binding Method**, either **None**, **ASN Binding** or **IP Address Binding**.
  7. Enable **Allow Refresh Token Requests** to issue new refresh tokens after a session transfer.
  8. Select **Use online refresh tokens**.
  9. Select **Save** to update your web application.

<Frame>
  <img alt="Session Transfer Web application" />
</Frame>

* Update your web application using the Management API Access Token with the [Update a Client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) endpoint:

<AuthCodeBlock />

* Update your web application using [Auth0 CLI](https://auth0.github.io/auth0-cli/auth0_apps_session-transfer_update.html):

<AuthCodeBlock />

## Implement Native to Web SSO

Native to Web Single SSO provides a seamless user experience transitioning authenticated users from your native application to your web application.

To facilitate this, your native application needs to exchange a refresh token for a Session Transfer Token and send the Session Transfer Token, through a URL or cookie, to your web application to authorize the session.

<Callout icon="file-lines">
  * If `allow_refresh_token` is disabled in the client but the application requests `offline_access`, Auth0 will not issue a `refresh_token` but the authentication will still work.

  * If refresh token rotation is enabled, Auth0 returns a new `refresh_token` in the token exchange call. The refresh token exchange should happen immediately before your code opens the web application.
</Callout>

### In your native application

#### Step 1: Exchanging a Refresh Token for a Session Transfer Token

Use the [/token](https://auth0.com/docs/api/authentication/authorization-code-flow-with-pkce/get-token-pkce) endpoint with your native application to exchange the refresh token for a Session Transfer Token.

* Exchange a refresh token for a session transfer token using Swift, Android, or React Native SDKs:

<Tabs>
  <Tab title="Swift SDK">
    ```swift lines theme={null}
    credentialsManager.ssoCredentials { result in
        switch result {
        case .success(let ssoCredentials):
            print("Obtained SSO credentials: \(ssoCredentials)")
        case .failure(let error):
            print("Failed with: \(error)")
        }
    }

    // Or, using async/await

    do {
        let ssoCredentials = try await credentialsManager.ssoCredentials()
        print("Obtained SSO credentials: \(ssoCredentials)")
    } catch {
        print("Failed with: \(error)")
    }
    ```
  </Tab>

  <Tab title="Android SDK">
    ```kotlin lines theme={null}
    secureCredentialsManager.getSsoCredentials(
        mapOf(),  // optional parameters
        object : Callback<SSOCredentials, CredentialsManagerException> {
            override fun onSuccess(result: SSOCredentials) {
                // Use result.sessionTransferToken to authenticate
                // the user in a web session in your app
            }

            override fun onFailure(error: CredentialsManagerException) {
                // Handle error
            }
        }
    )
    ```
  </Tab>

  <Tab title="React Native SDK">
    ```typescript lines theme={null}
    // Using Hooks
    import { useAuth0 } from 'react-native-auth0';

    function MyComponent() {
      const { getSSOCredentials } = useAuth0();

      const openWebApp = async () => {
        try {
          const ssoCredentials = await getSSOCredentials();
          // Use ssoCredentials.sessionTransferToken to authenticate
          // the user in a web session in your app
          console.log('Session Transfer Token:', ssoCredentials.sessionTransferToken);
        } catch (error) {
          console.error('Failed to get SSO credentials:', error);
        }
      };
    }

    // Using Auth0 class
    import Auth0 from 'react-native-auth0';

    const auth0 = new Auth0({
      domain: '{yourDomain}',
      clientId: '{yourClientId}',
    });

    const ssoCredentials = await auth0.credentialsManager.getSSOCredentials();
    console.log('Session Transfer Token:', ssoCredentials.sessionTransferToken);
    ```
  </Tab>
</Tabs>

* Exchange a refresh token for a session transfer token using HTTP:

<AuthCodeBlock />

<Callout icon="file-lines">
  These samples use placeholder variables for dynamic variables. Replace the placeholders using your Auth0 domain, client\_id and an existing refresh\_token.
</Callout>

The Auth0 tenant returns a single-use and short-lived (1-minute lifetime) session\_transfer\_token.

```json lines theme={null}
{
    "access_token": "{session_transfer_token}",
    "issued_token_type": "urn:auth0:params:oauth:token-type:session_transfer_token",
    "token_type": "N_A",
    "expires_in": 60
}
```

<Callout icon="file-lines">
  If refresh token rotation is enabled, the exchange will also return a refresh token.

  If you requested an ID Token during authentication, this call will also return an ID Token.
</Callout>

#### Step 2: Send the Session Transfer Token through a URL or cookie

There are two options to send the  `session_transfer_token` to your web application based on the configured `allowed_authentication_methods`.

##### Option 1: Send the session\_transfer\_token as a cookie

If your web application using WebView or browser supports cookie injection, you can configure your native application to:

* Add the session\_transfer\_token into a cookie.
* Open the web application using WebView or browser.
* Log the web application to your Auth0 tenant or <Tooltip href="/docs/glossary?term=Custom+Domain">Custom Domain</Tooltip>. As the `session_transfer_token` is included in the cookie, the user is not prompted for first-factor authentication.

<AuthCodeBlock />

##### Option 2: Send the session\_transfer\_token as a URL parameter

If your web application does not support cookie injection, you can configure your native application using URL parameters to:

* Add the session\_transfer\_token as a URL parameter.
* Open the web application using  WebView or browser.
* Log the web application appending the `session_transfer_token` as a URL parameter to the [/authorize](https://auth0.com/docs/api/authentication/authorization-code-flow/authorize-application) endpoint. The Auth0 tenant authenticates the user without requiring first-factor authentication, as the session\_transfer\_token is valid and trusted

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request GET \
    --url 'https://your_web_app_login_url/?session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN'
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://your_web_app_login_url/?session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN");
  var request = new RestRequest(Method.GET);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines theme={null}
  package main

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

  func main() {

  	url := "https://your_web_app_login_url/?session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN"

  	req, _ := http.NewRequest("GET", url, nil)

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

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

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

  }
  ```

  ```java Java lines theme={null}
  HttpResponse<String> response = Unirest.get("https://your_web_app_login_url/?session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://your_web_app_login_url/',
    params: {session_transfer_token: 'YOUR_SESSION_TRANSFER_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP lines theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://your_web_app_login_url/?session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
  ]);

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

  curl_close($curl);

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

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("your_web_app_login_url")

  conn.request("GET", "/?session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN")

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://your_web_app_login_url/?session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN")

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

  request = Net::HTTP::Get.new(url)

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

### In your web application

<Callout icon="file-lines">
  When the Session Transfer Token is sent as a cookie, no further configuration is needed as the browser sends the cookie in the `/authorize` endpoint request.
</Callout>

Implement Native to Web Web Single SSO in your web application using URL parameters by:

#### Option 1: Add the Session Transfer Token in your web application request

From the application login URL, redirect to the `/authorize` endpoint when the `session_transfer_token` is sent as a URL parameter.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/authorize?session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN&client_ID={yourClientId}&redirect_uri=YOUR_REDIRECT_URI&response_type=code'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/authorize?session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN&client_ID={yourClientId}&redirect_uri=YOUR_REDIRECT_URI&response_type=code");
  var request = new RestRequest(Method.GET);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/authorize?session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN&client_ID={yourClientId}&redirect_uri=YOUR_REDIRECT_URI&response_type=code"

  	req, _ := http.NewRequest("GET", url, nil)

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/authorize?session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN&client_ID={yourClientId}&redirect_uri=YOUR_REDIRECT_URI&response_type=code")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/authorize',
    params: {
      session_transfer_token: 'YOUR_SESSION_TRANSFER_TOKEN',
      client_ID: '{yourClientId}',
      redirect_uri: 'YOUR_REDIRECT_URI',
      response_type: 'code'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/authorize?session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN&client_ID={yourClientId}&redirect_uri=YOUR_REDIRECT_URI&response_type=code",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  conn.request("GET", "/{yourDomain}/authorize?session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN&client_ID={yourClientId}&redirect_uri=YOUR_REDIRECT_URI&response_type=code")

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

  print(data.decode("utf-8"))
  ```
</AuthCodeGroup>

#### Option 2: Add the Session Transfer Token to web applications using Auth0 SDKs

Auth0 SDKs do not support Native to Web Single SSO automatically and they will not include the `session_transfer_token` in the `/authorize` endpoint request.

Below are examples of web applications using Auth0 SDKs to redirect the `session_transfer_token` in the `/authorize` endpoint request:

##### Node (Express.js)

If your web application uses [Express.js](https://expressjs.com/) or the [Auth0 Express SDK](https://github.com/auth0/express-openid-connect), you can use the code below to add middleware support for `session_transfer_token`.

```javascript javascript lines theme={null}
const baseConfig = {
  authRequired: false,
  auth0Logout: true
};

// Extending the middleware to auto detect session_transfer_token
app.use((req, res, next) => {
  const { session_transfer_token } = req.query;

  // Create a new config for each request to avoid state leakage
  const config = { ...baseConfig };

  if (session_transfer_token) {
    config.authorizationParams = {
      session_transfer_token,
    };
  }

  auth(config)(req, res, next);
});
```

##### Auth0 SPA SDK (@auth0/auth0-spa-js)

If your web application uses the [Auth0 SPA SDK](https://github.com/auth0/auth0-spa-js), you can pass the `session_transfer_token` to `loginWithRedirect()` via `authorizationParams`.

```typescript typescript lines theme={null}
import { Auth0Client } from '@auth0/auth0-spa-js';

const auth0 = new Auth0Client({
  domain: '{yourDomain}',
  clientId: '{yourClientId}',
});

// Get session_transfer_token from URL query params (passed from native app)
const urlParams = new URLSearchParams(window.location.search);
const sessionTransferToken = urlParams.get('session_transfer_token');

// Use loginWithRedirect with the session_transfer_token
if (sessionTransferToken) {
  await auth0.loginWithRedirect({
    authorizationParams: {
      session_transfer_token: sessionTransferToken,
      redirect_uri: window.location.origin,
    },
  });
}
```

##### Auth0 React SDK (@auth0/auth0-react)

If your web application uses the [Auth0 React SDK](https://github.com/auth0/auth0-react), you can use `loginWithRedirect` from the `useAuth0` hook to pass the `session_transfer_token`.

```typescript typescript lines theme={null}
import { useEffect } from 'react';
import { useAuth0 } from '@auth0/auth0-react';

function App() {
  const { loginWithRedirect, isAuthenticated, isLoading } = useAuth0();

  useEffect(() => {
    if (isLoading || isAuthenticated) return;

    const urlParams = new URLSearchParams(window.location.search);
    const sessionTransferToken = urlParams.get('session_transfer_token');

    if (sessionTransferToken) {
      loginWithRedirect({
        authorizationParams: {
          session_transfer_token: sessionTransferToken,
        },
      });
    }
  }, [loginWithRedirect, isLoading, isAuthenticated]);

  return <div>...</div>;
}
```

##### SAML and WS-Federation

If your web application uses <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> or <Tooltip href="/docs/glossary?term=WS-Fed">WS-Fed</Tooltip> service provider and Auth0 as the <Tooltip href="/docs/glossary?term=IdP">IdP</Tooltip>, you can send the `session_transfer_token` as an URL parameter to the Auth0 `/authorize` endpoint and the `redirect_uri` is the SAML or WS-Fed sign-in URL.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/samlp//{yourClientId}?session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN' \
    --header 'cookie: session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN' \
    --cookie session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/samlp//{yourClientId}?session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN");
  var request = new RestRequest(Method.GET);
  request.AddHeader("cookie", "session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/samlp//{yourClientId}?session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("cookie", "session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN")

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

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

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

  ```java Java theme={null}
  HttpResponse response = Unirest.get("https://{yourDomain}/samlp//{yourClientId}?session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN")
    .header("cookie", "session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/samlp//{yourClientId}',
    params: {session_transfer_token: 'YOUR_SESSION_TRANSFER_TOKEN'},
    headers: {cookie: 'session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/samlp//{yourClientId}?session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "cookie: session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'cookie': "session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN" }

  conn.request("GET", "/{yourDomain}/samlp//{yourClientId}?session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN", headers=headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/samlp//{yourClientId}?session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN")

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

  request = Net::HTTP::Get.new(url)
  request["cookie"] = 'session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

## Native to Web SSO with Organizations

Native to Web SSO supports [Organizations](/docs/manage-users/organizations). When a user authenticates with an organization in your native application, the session transfer token includes the organization context.

<Callout icon="file-lines">
  When using Organizations with Native to Web SSO, the `organization` parameter in the web application's `/authorize` request must match the organization associated with the session transfer token. If there is a mismatch, authentication will fail and the user will be prompted to log in again.
</Callout>

To use Organizations with Native to Web SSO:

1. Authenticate the user in your native application with an organization:

```javascript javascript lines theme={null}
// Native app login with organization
await authorize({
  organization: 'org_abc123',
  scope: 'openid profile email offline_access'
});
```

2. When redirecting to the web application, include the same organization in the `/authorize` request:

```bash bash lines theme={null}
https://{yourDomain}/authorize?
  client_id={yourWebClientId}&
  redirect_uri={yourRedirectUri}&
  response_type=code&
  organization=org_abc123&
  session_transfer_token=YOUR_SESSION_TRANSFER_TOKEN
```

If the organization in the `/authorize` request does not match the organization in the session transfer token, the session transfer token is rejected and the user is redirected to the login page to re-authenticate. A warning log is emitted in your tenant logs with the event description "Single Sign-On failed: Session Transfer Token organization mismatch detected."

## Session Transfer Token with Actions

Using `session_transfer_token` with [Actions](/docs/customize/actions) allows you to configure post-authentication risk detection and response capabilities to enhance user protection.

To facilitate this, the post-login Action object **event.session\_transfer\_token** provides relevant information including unique `client_id`, `scope`, `request` information such as `ip`, `asn`, `user_agent` and `geoip` information such as, `cityName`, `countryCode` among others. To learn more, read [Actions Triggers: post-login - Event Object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object).

The Action code below allows you to dynamically reject a transaction based on geolocation information:

```javascript javascript lines theme={null}
/**
* Handler that will be called during the execution of a PostLogin flow.
*
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {
   if(
     event.session_transfer_token &&
     event.session_transfer_token.request.geoip.countryCode !== event.request.geoip.countryCode
     ) {
     api.access.deny("Network mismatch detected")
   }
};
```

### Access Parent Refresh Token Metadata

Native to Web SSO allows you to access metadata from the parent refresh token that was used to initiate the SSO flow. This enables you to pass contextual information collected in the native application (such as device integrity, risk signals, or custom context) into the web session created from the `session_transfer_token`.

Auth0 exposes this information in Post Login Actions via the `event.session.session_transfer.parent_refresh_token.metadata` object. This enables secure, standardized propagation of metadata between platforms.

<Callout icon="file-lines">
  **Example Use Case:** A mobile app collects risk data (device score, location, etc.) and stores it in the refresh token's metadata. When the native app initiates a Native to Web SSO flow, that metadata is automatically available in the corresponding web session via Actions.
</Callout>

The Action code below allows you to perform conditional access logic based on device trust metadata from the native application:

```javascript javascript lines theme={null}
/**
* Handler that will be called during the execution of a PostLogin flow.
*
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {
  // Access metadata from the parent refresh token (native app)
  const parentMetadata = event.session?.session_transfer?.parent_refresh_token?.metadata;

  if (parentMetadata) {
    const deviceTrustLevel = parentMetadata.device_trust;

    if (deviceTrustLevel !== 'high') {
      api.access.deny("Device trust level insufficient.");
    }

    // You can also add claims based on native app context
    if (parentMetadata.subscription_tier) {
      api.idToken.setCustomClaim('subscription_tier', parentMetadata.subscription_tier);
    }
  }
};
```

## Monitoring

You can monitor the Native to Web SSO activity by reviewing the Tenant [logs](/docs/deploy-monitor/logs).

### Token exchange logs

* `sertft` : Successful Refresh Token exchange. This log will correspond to a Native to Web SSO exchange when the `audience` field is `"audience":"urn:$auth0Domain:session_transfer"`
* `fertft`: Failed Refresh Token exchange. This log will correspond to a Native to Web SSO exchange when the `audience` field is `"audience": "urn:$auth0Domain:session_transfer"`

### Session transfer validation warning logs

Auth0 emits warning logs (`w`) when session transfer token validation fails during the `/authorize` request. These logs help you troubleshoot Native to Web SSO issues:

| Event Description                                                                                                        | Cause                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `Single Sign-On failed: Session Transfer Token not found or expired. This may indicate token reuse or expiration.`       | The session transfer token was not found, has already been used, or has expired (tokens are single-use and expire after 1 minute). |
| `Single Sign-On failed: Session Transfer Token device binding validation failed due to IP/ASN mismatch.`                 | The IP address or ASN of the web request does not match the device binding configured for the session transfer token.              |
| `Single Sign-On failed: Session Transfer Token organization mismatch detected.`                                          | The `organization` parameter in the `/authorize` request does not match the organization in the session transfer token.            |
| `Single Sign-On failed: Session Transfer Token user mismatch detected.`                                                  | A pre-existing Auth0 session belongs to a different user than the session transfer token.                                          |
| `Single Sign-On failed: Parent refresh token not found. Session Transfer Token won't be used for session establishment.` | The parent refresh token used to create the session transfer token has been revoked or deleted.                                    |


# Use Case: Configure mobile-to-web payment flows using Native to Web SSO
Source: https://auth0.com/docs/authenticate/single-sign-on/native-to-web/configure-mobile-to-web-payment-flows

Seamlessly transition users from your iOS or Android app into a secure, authenticated subscription flow in your web app using Native to Web Single Sign-On (SSO) and session transfer tokens.

<Card title="Before you start">
  1. Create an Auth0 tenant to register and configure your native and web applications.

  2. Install and configure [Auth0 CLI](https://github.com/auth0/auth0-cli) for your Auth0 tenant.

  3. Add Auth0 Authentication to your native application using the appropriate Quickstarts for your platform:

  * [iOS Swift Quickstart](/docs/quickstart/native/ios-swift/interactive)
  * [Android Quickstart](/docs/quickstart/native/android/interactive)

  4. Add [refresh\_token](/docs/secure/tokens/refresh-tokens/get-refresh-tokens) support to your native application.

  5. Add Auth0 Authentication to your web application using the [React Single Page App Quickstart](/docs/quickstart/spa/react/interactive).
</Card>

[Native to Web Single Sign-On (SSO)](/docs/authenticate/single-sign-on/native-to-web) allows you to create a seamless, secure user experience between your native application and a web-based paid membership flow. Native to Web <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> enables the native application to send the user’s authentication context to the web application using a short-lived, secure `session_transfer_token`.

The sections below outline how you can add:

* To your native application, a Subscribe Now button that lets authenticated users sign up for a paid membership plan using a secure web checkout experience.
* To your web application, a Subscription page that allows user to select membership subscriptions without the user logging-in again.

<Callout icon="file-lines">
  This use case focuses on React-based web applications using the Auth0 React SDK.

  If you are using a different framework, such as Node or Express, the logic for managing `session_transfer_token` whether through a URL parameter or cookie can be adapted accordingly.
</Callout>

## Configure Auth0 CLI

<Callout icon="file-lines">
  Use the [Auth0 CLI](https://github.com/auth0/auth0-cli) to configure your Auth0 tenant. You can also use the [Auth0 Management API](https://auth0.com/docs/api/management/v2); to learn more read [Configure Native to Web SSO](/docs/authenticate/single-sign-on/native-to-web/configure-implement-native-to-web#configure-native-applications).
</Callout>

Follow these steps to authenticate your Auth0 tenant using [Auth0 CLI](https://github.com/auth0/auth0-cli):

1. Initialize the Auth0 CLI

```bash lines theme={null}
auth0 login
```

2. Select **As a user** and follow the login flow.

```bash lines theme={null}
How would you like to authenticate?
> As a user
  As a machine
```

3. Select the Auth0 tenant where you want to enable Native to Web SSO.

## Configure Auth0

### Enable Native to Web SSO in your native application

Native to Web SSO uses a `session_transfer_token` to establish SSO from a native to a web application. The `session_transfer_token` allows Auth0 to identify the user, the origin native application, and additional context securely. To learn more, read [Native to Web SSO](/docs/authenticate/single-sign-on/native-to-web/configure-implement-native-to-web).

Enable Native to Web SSO using Auth0 CLI:

<AuthCodeBlock />

### Enable Native to Web SSO in your web application

Enable the web application to accept the `session_transfer_token` for authentication through a cookie or URL parameter using Auth0 CLI:

<AuthCodeBlock />

If the `session_transfer_token` is injected into the browser with a cookie no additional changes to your web application are required. The only requirement is that the browser navigates to your [application's Login URI](https://sus.auth0.com/docs/get-started/applications/application-settings#application-uris) to handle the redirect of the user to your Auth0 tenant’s `/authorize` endpoint.

<Callout icon="file-lines">
  You can configure the Application Login URI in your application's settings within the Auth0 Dashboard. This is the route Auth0 will redirect users to when initiating login from external sources.
</Callout>

## Create a subscription page in the web application

Add a new `/src/views/` file to create a subscription page:

### Step 1: Add a new view file

Create a file at `src/views/JoinMembership.js`. This file will prompt the users to complete a paid subscription.

```js lines expandable theme={null}
import React, { useEffect } from "react";
import { useAuth0 } from "@auth0/auth0-react";
import { useLocation } from "react-router-dom";
import { Container, Button } from "reactstrap";
import Loading from "../components/Loading";

const JoinMembership = () => {
  const { isAuthenticated, isLoading, loginWithRedirect } = useAuth0();
  const location = useLocation();

  useEffect(() => {
    if (isLoading || isAuthenticated) return;

    const params = new URLSearchParams(location.search);
    const token = params.get("session_transfer_token");

    const redirectOptions = {
      appState: { returnTo: "/join-membership" },
      authorizationParams: {},
    };

    if (token) {
      redirectOptions.authorizationParams.session_transfer_token = token;
    }

    loginWithRedirect(redirectOptions);
  }, [isAuthenticated, isLoading, loginWithRedirect, location.search]);

  if (isLoading) {
    return <Loading />;
  }

  if (!isAuthenticated) {
    return <p>Redirecting to login...</p>;
  }

  return (
    <Container className="mt-5">
      <h1>Choose a Subscription Plan</h1>
      <Button color="primary" className="mb-3" onClick={() => alert("Subscribed to Basic!")}>
        Basic – $5/month
      </Button>
      <Button color="secondary" className="mb-3" onClick={() => alert("Subscribed to Pro!")}>
        Pro – $10/month
      </Button>
      <Button color="success" className="mb-3" onClick={() => alert("Subscribed to Premium!")}>
        Premium – $20/month
      </Button>
    </Container>
  );
};

export default JoinMembership;
```

### Step 2: Add a new route

Edit the file `src/App.js` and add a `/join-membership` route to the new subscription page:

```js lines theme={null}
import JoinMembership from "./views/JoinMembership";

 {/* Redirect to the join membership page */}
<Route path="/join-membership" component={JoinMembership} />
```

The new `/join-membership` route:

* Determines if the user is authenticated. If not, it will redirect the user to the <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> page.
* If a `session_transfer_token` is appended as a URL parameter, the token is passed in the authentication request.
* Once authenticated, the user will be presented with buttons to subscribe to different membership plans.

<Warning>
  Run your React app and go to `http://localhost:3000/join-membership`

  * If the user is authenticated, the user will see the subscription options.
  * If the user is not authenticated, they are automatically redirected to the Auth0 Universal Login page.

    * If the URL includes a `session_transfer_token`, it will be included in the login request to Auth0.
    * If not, the login will proceed using the standard web authentication.

  When the user logs in, the user is returned to the `/join-membership` page to select the subscription options.
</Warning>

## Configure the native application

Your native application needs to exchange the `refresh_token` for a `session_transfer_token` immediately before launching the web application. To do so, add the session transfer exchange and the web application launch logic inside the same event handler, an example is the button’s `onClick` method.

### iOS

The following steps outline how to add mobile-to-web payment to iOS native applications:

#### Step 1: Add a Subscribe to Membership button

To launch the web-based subscription flow from your iOS native app, add a `Subscribe to Membership` button to the `ProfileView.swift` file.

Edit the body of the `ProfileView.swift` file to include a button below the user information:

```swift lines theme={null}
import SwiftUI

struct ProfileView: View {
    let user: User
    var onSubscribe: () -> Void = {}

    var body: some View {
        List {
            Section(header: ProfileHeader(picture: user.picture)) {
                ProfileCell(key: "ID", value: user.id)
                ProfileCell(key: "Name", value: user.name)
                ProfileCell(key: "Email", value: user.email)
                ProfileCell(key: "Email verified?", value: user.emailVerified)
                ProfileCell(key: "Updated at", value: user.updatedAt)
            }

            Section {
                Button("Subscribe to Membership", action: onSubscribe)
            }
        }
    }
}
```

The `ProfileView.swift` file adds a `Subscribe to Membership` button and uses an `onSubscribe` closure to determine the behavior when selected.

#### Step 2: Implement the subscription flow using Native to Web SSO

Edit the `MainView.swift` file to define the behavior of the `Subscribe to Membership` button:

<AuthCodeBlock />

<Callout icon="file-lines">
  This sample uses the audience `https://sample.api.com` for demonstration purposes. You can create an API with this identifier in your Auth0 tenant or replace it with your own API identifier.

  To learn more, read [Set Up APIs](/docs/get-started/auth0-overview/set-up-apis).
</Callout>

This allows the user to select the `Subscribe to Membership` in the native app and immediately start the web application subscription process without logging in again.

### Android

The following steps outline how to add mobile-to-web payment to Android native applications:

#### Step 1: Add a Subscribe button to the main page

To launch the web-based subscription flow from your Android native application, add a `Subscribe to Membership` button to the UI.

Edit the `MainActivity.kt` file and add the following code to the `onCreate()` method:

```kotlin wrap lines theme={null}
binding.buttonSubscribe.setOnClickListener { launchSubscriptionFlow() }
```

Edit the `activity_main.xml` file to include the code below after `@+id/button_patch_metadata` button:

```xml lines theme={null}
<Button
    android:id="@+id/buttonSubscribe"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Subscribe to Membership" />
```

#### Step 2: Implement subscription flow using Native to Web SSO

Edit the `MainActivity.kt` file to define the behavior of the `Subscribe to Membership` button:

1. Extend the login flow and handle the subscription action:

```kotlin lines theme={null}
// Required imports
import com.auth0.android.authentication.storage.SecureCredentialsManager
import com.auth0.android.authentication.storage.SharedPreferencesStorage
import com.auth0.android.result.SSOCredentials
```

2. Update the `onCreate()`method to include the `credentialsManager:`

```kotlin lines theme={null}
override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Set up the account object with the Auth0 application details
        account =  Auth0.getInstance(
            getString(R.string.com_auth0_client_id),
            getString(R.string.com_auth0_domain)
        )

        // Bind the button click with the login action
        binding = ActivityMainBinding.inflate(layoutInflater)
        setContentView(binding.root)
        binding.buttonLogin.setOnClickListener { loginWithBrowser() }
        binding.buttonLogout.setOnClickListener { logout() }
        binding.buttonGetMetadata.setOnClickListener { getUserMetadata() }
        binding.buttonPatchMetadata.setOnClickListener { patchUserMetadata() }
        binding.buttonSubscribe.setOnClickListener { launchSubscriptionFlow() }

        secureCredentialsManager = SecureCredentialsManager(
            this,
            AuthenticationAPIClient(account),
            SharedPreferencesStorage(this)
        )

    }
```

3. Update the `loginwithBrowser()` method to store credentials using the `credentialsManager:`

```kotlin lines theme={null}
private fun loginWithBrowser() {
    WebAuthProvider.login(account)
        .withScheme(getString(R.string.com_auth0_scheme))
        .withScope("openid profile email offline_access")
        .withAudience("https://example.api.com")
        .start(this, object : Callback<Credentials, AuthenticationException> {
            override fun onSuccess(credentials: Credentials) {
                secureCredentialsManager.saveCredentials(credentials)
                cachedCredentials = credentials
                showSnackBar("Success: ${credentials.accessToken}")
                updateUI()
                showUserProfile()
            }

            override fun onFailure(exception: AuthenticationException) {
                showSnackBar("Failure: ${exception.getCode()}")
            }
        })
}
```

<Callout icon="file-lines">
  This sample uses the audience `https://sample.api.com` for demonstration purposes. You can create an API with this identifier in your Auth0 tenant or replace it with your own API identifier.

  To learn more, read [Set Up APIs](/docs/get-started/auth0-overview/set-up-apis).
</Callout>

4. Add the `launchSubscriptionFlow()` method to open the web application:

```kotlin lines expandable theme={null}
private fun launchSubscriptionFlow() {
    secureCredentialsManager.getSsoCredentials(
        mapOf(),  // optional parameters
        object : Callback<SSOCredentials, CredentialsManagerException> {
            override fun onSuccess(result: SSOCredentials) {
                val sessionToken = result.sessionTransferToken

                val cookieValue =
                    "auth0_session_transfer_token=$sessionToken; Path=/; Secure; HttpOnly; SameSite=None"
                val cookieManager = android.webkit.CookieManager.getInstance()
                cookieManager.setAcceptCookie(true)
                cookieManager.setCookie("https://${getString(R.string.com_auth0_domain)}", cookieValue)

                val webView = android.webkit.WebView(this@MainActivity)
                webView.settings.javaScriptEnabled = true
                webView.webViewClient = object : android.webkit.WebViewClient() {
                    override fun shouldOverrideUrlLoading(view: android.webkit.WebView?, url: String?) = false
                }

                webView.loadUrl("http://localhost:3000/join-membership")
                setContentView(webView)
            }

            override fun onFailure(error: CredentialsManagerException) {
                showSnackBar("Failed to get session transfer token: ${error.message}")
            }
        }
    )
}
```

This allows the user to select `Subscribe to Membership` in the native application and immediately start the web application subscription process without logging in again.

## Test your Native to Web SSO implementation

Once everything is configured, run your iOS or Android native application to log in, go to the Profile or to the Mainscreen and select the **Subscribe to Membership** button.

The following takes place:

* The stored `refresh_token` is used to request a secure `session_transfer_token`
* The `session_transfer_token` is injected into a cookie for your Auth0 domain
* A `WKWebView` is used to load your web application’s `/join-membership` route
* The web application receives the `session_transfer_token` and completes login using Native to Web SSO
* The user sees the subscription options immediately in the web application

You have created a seamless experience where a mobile native application user can launch a secure, authenticated flow in a web application without being prompted to log in again.

## Next Steps

* Explore more configuration options for Native to Web SSO:Dive deeper into session lifetime, <Tooltip href="/docs/glossary?term=refresh+token">refresh token</Tooltip> rotation, device binding, and cascade revocation in the [Native to Web SSO documentation](/docs/authenticate/single-sign-on/native-to-web).
* Customize the post-login experience with Progressive Profiling:Use Auth0’s [Progressive Profile Form](/docs/customize/forms/configure-progressive-profile-form) to collect additional user data after login — such as plan preferences, address, or payment intent — before showing subscription options.


# Native to Web SSO and Sessions
Source: https://auth0.com/docs/authenticate/single-sign-on/native-to-web/native-to-web-sso-and-sessions

Learn about Native to Web SSO and Sessions

When a WebView or browser initiates a call to the `/authorize` endpoint, Auth0 determines if there is an active session, and then either reuses the existing session or honors the provided `session_transfer_token`. To avoid session injection risks, Auth0 uses a safe and predefined evaluation to determine if the `session_transfer_token` is valid. To learn more, read [Configure and Implement Native to Web SSO](/docs/authenticate/single-sign-on/native-to-web/configure-implement-native-to-web).

<Callout icon="file-lines">
  Native to Web SSO does not change standard Auth0 [Single Sign-On](/docs/authenticate/single-sign-on) authentication.
</Callout>

**Specific Native to Web <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> flows can result in the following behaviors:**

1. The user is logged in when a valid `session_transfer_token` is sent and there is no pre-existing Auth0 session.
2. The user is logged in when a valid `session_transfer_token` is sent and a pre-existing Auth0 session is found for the same user.
3. The user is prompted to login when a pre-existing Auth0 session is found and the `session_transfer_token` belongs to a different user. Additionally, the pre-existing Auth0 session is revoked.
4. The user is prompted to log in when a pre-existing Auth0 session is found and the `session_transfer_token` is invalid.

## Sessions and refresh token revocation

A [`session_transfer_token`](/docs/authenticate/single-sign-on/native-to-web/configure-implement-native-to-web#create-and-manage-session-transfer-tokens) is used to initiate a secure session in a WebView or browser to securely authenticate the user without being prompted to login. These web sessions may also issue their own <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip>.

Native to Web SSO applies a set of revocation rules to ensure consistent and secure behavior when sessions and refresh tokens are revoked:

* When a refresh token is revoked, it also revokes its associated refresh tokens and sessions if `enforce_cascade_revocation` is enabled in the native application.
* When a web session is revoked, it also revokes its associated refresh tokens  if `enforce_online_refresh_tokens`  is enabled in the web application
* Nested Native to Web SSO is not allowed. A web session created using a `session_transfer_token` cannot generate another `session_transfer_token`.


# Native to Web SSO Best Practices
Source: https://auth0.com/docs/authenticate/single-sign-on/native-to-web/native-to-web-sso-best-practices

Learn about Native to Web SSO best practices

For best results when implementing Native to Web <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip>, Auth0 recommends adhering to the best practices compiled below. These guidelines can help ensure session integrity:

## Use Post Login Actions to limit session lifetime

Use [`post-login`](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) Action triggers to ensure web sessions created through Native to Web SSO are time-boxed appropriately and expire quickly when inactive. 
You can use `post-login` Actions to detect when a session is initiated through a `session_transfer_token` and apply shorter idle and absolute timeouts:

```swift lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  if (event.session_transfer_token) {
    const now = Date.now();

    // Limit the session to 30 minutes total
    api.session.setExpiresAt(now + 30 * 60 * 1000);

    // Set idle timeout to 15 minutes
    api.session.setIdleExpiresAt(now + 15 * 60 * 1000);
  }
};
```

## Bind session\_transfer\_token to the device or IP address

To reduce the risk of token replay if a token is leaked, logged, or intercepted, always bind the [`session_transfer_token`](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id)to the origin environment using `enforce_device_binding`.

## Use secure cookies over query parameters

Send the `session_transfer_token` to the web application using a secure, HTTPOnly cookie scoped to your Auth0 domain to prevent accidental logging or sharing of the token via URLs and to reduce the attack surface for token interception. If you need to use a query parameter (for example, for Chrome Custom Tabs) ensure that the URL uses HTTPS and remove the token from the URL after use.

## Avoid issuing refresh tokens to web apps unless necessary

Only enable [`allow_refresh_token`](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) for web applications that truly need long-lived tokens. In most cases, short-lived <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> combined with silent authentication are sufficient and safer in browser contexts.

## Enable Allow Refresh Tokens when appropriate to set the refresh tokens as “online”

To avoid orphaned credentials and prevent <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip> from lingering after logout, use the [`allow_refresh_token`](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) setting to ensure refresh tokens issued via Native to Web SSO are bound to the session that issued them. If the session is revoked or expires, the refresh token is automatically invalidated.

## Enable enforce cascade revocation

To ensure that all web sessions and refresh tokens associated with a `session_transfer_token` are revoked, enable [`enforce_cascade_revocation`](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) in the native application. This is critical to ensure secure session invalidation across applications.


# Okta Access Gateway
Source: https://auth0.com/docs/authenticate/single-sign-on/okta-access-gateway

Overview of Okta Access Gateway (OAG).

**Okta Access Gateway (OAG)** is a solution designed to extend modern identity to legacy on-prem applications to protect your hybrid cloud. Now, you can easily set up Okta Access Gateway to use Auth0 as the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> to authenticate users and have <Tooltip href="/docs/glossary?term=Single+Sign-On">Single Sign-On</Tooltip> (SSO) when accessing on-prem applications. To learn more about setup, see the [Okta Access Gateway website](https://help.okta.com/oag/en-us/content/topics/access-gateway/ag-main.htm).

After correctly setting up, you can view your OAG Applications as **SSO Integrations** on the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.


# Identity-Provider-Initiated Single Sign-On
Source: https://auth0.com/docs/authenticate/single-sign-on/outbound-single-sign-on

Overview of Single Sign-on (SSO) initiated by Identity Providers (IdPs).

For Identity-Provider-Initiated <Tooltip href="/docs/glossary?term=Single+Sign-On">Single Sign-On</Tooltip> (SSO), a third-party <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> (IdP) is the SSO provider. When a user logs in to an application:

1. The application redirects the user to an identity provider.
2. The third-party identity provider performs authentication and authorization.
3. Upon successful authentication, the user is returned to the application.

## Pre-defined integrations

Auth0 provides IdP-initiated [SSO Integrations](/docs/customize/integrations/sso-integrations) for various services, like [Dropbox](https://marketplace.auth0.com/integrations/dropbox-sso), [Slack](https://marketplace.auth0.com/integrations/slack-sso), or [Zoom](https://marketplace.auth0.com/integrations/zoom-sso). To see the full list, explore [Auth0 Marketplace: SSO Integrations](https://marketplace.auth0.com/features/sso-integrations).

## Build your own implementations

## SAML

* [SAML Identity Provider Configuration Settings](/docs/authenticate/protocols/saml/saml-identity-provider-configuration-settings)

## OIDC

* [Configure Applications with OIDC Discovery](/docs/get-started/applications/configure-applications-with-oidc-discovery)


# Configure Auth0 as SAML Identity Provider
Source: https://auth0.com/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider

Describes how to configure Auth0 to serve as a SAML identity provider in a SAML federation.

You can use Auth0 as the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> in <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> configurations with SAML 2.0.

## SSO integrations with built-in Auth0 support

1. Go to [Dashboard > Applications > SSO Integrations](https://manage.auth0.com/#/externalapps) and select **Create SSO Integration**.
2. Choose an SSO identity provider integration. On the next screen, click **Continue**.
3. Enter the required details for your selected provider and click **Save**.

On the Tutorial view, you will see additional configuration instructions that are specific to the integration you have chosen.

Some of the following integrations make use of the [SAML2 Web App addon](/docs/authenticate/protocols/saml/saml-sso-integrations/enable-saml2-web-app-addon).

* [Amazon Web Services](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-aws)
* [Atlassian](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-atlassian)
* [Cisco-WebEx](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-cisco-webex)
* [DataDog](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-datadog)
* [Egencia](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-egencia)
* [Oracle Eloqua Marketing Cloud](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-addon-eloqua)
* [Freshdesk](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-freshdesk)
* [GitHub Enterprise Cloud](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-github-enterprise-server)
* [GitHub Enterprise Server](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-github-enterprise-server)
* [Google Workspace](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-idp-for-google-g-suite)
* [Heroku](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-heroku)
* [Hosted Graphite](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-hosted-graphite)
* [Litmos](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-litmos)
* [PluralSight](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-pluralsight)
* [Sprout Video](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-sprout-video)
* [Tableau Online](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-tableau-online)
* [Tableau Server](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-tableau-server)
* [Workday](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-workday)
* [Workpath](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-workpath)

## Manually configure SSO integrations

You can manually configure a SAML <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> integration with the SAML2 Web App addon in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. You can configure the SAML addon using the instructions on the screen along with the information available on the service provider's settings.

### Obtain the Application Callback URL from the service provider

Obtain the URL to which the SAML Authentication Assertion should be sent from the service provider. This may be called **Assertion Consumer Service URL**, **Post-back URL**, or **Callback URL**.

### Configure SAML SSO in Auth0

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and either create a new application or click the name of an application to configure.
2. Scroll to the bottom of the **Settings** page and click **Advanced Settings**.
3. Select the **Certificates** tab and click **Download Certificates** and choose **`PEM`** format.
   The certificate will be downloaded to a file called `{yourTenant}.pem`. Save this file; you will need to upload it when you configure the service provider.

   <Frame>
     <img alt="Dashboard Applications Advanced Settings Certificates tab" />
   </Frame>
4. Select the **Endpoints** tab and locate **SAML Protocol URL.**  Copy and save it. You will need to provide it to the service provider.
5. Scroll to the top and select the **Addons** tab.
6. Enable the **SAML2 Web App** toggle.

   <Callout icon="file-lines">
     Enabling both SAML and WS-Fed addons for a single client is not supported and may lead to inconsistent behavior. Use a separate client for each addon.
   </Callout>
7. On the **Settings** tab, enter the **Application Callback URL** from the service provider (or application) to which the SAML assertions should be sent after Auth0 has authenticated the user. This is the Assertion Consumer Service (ACS) URL.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Settings Tab" />
   </Frame>

   <Warning>
     Adding an allowed callback URL to the SAML2 add-on also adds that URL as the first item in the application's allowed callback list. This will impact functionality that relies on the first URL of this list as the default.

     Additionally, if the first URL in the application's allowed callback list is later updated or changed, this will be reflected in the SAML2 add-on which may break its functionality.
   </Warning>
8. Scroll to the bottom of the tab and click **Enable**.
9. If your service provider sends multiple ACS URLs in the SAML request, you will need to add them to the allow list by navigating to your application's **Settings** tab, locating **Allowed Callback URLs**, and adding them.

### Configure SAML SSO on the service provider

1. Go to the SAML Addon **Usage** tab to view the information that you need to configure the service provider application.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Usage Tab" />
   </Frame>
2. Locate **Identity Provider Metadata**, and click **Download** to download the metadata file. Add information to the service provider, so it knows how to send SAML-based authentication requests to Auth0. The instructions provided here are generic. You will need to find the appropriate screens and fields on the service provider.

* If the service provider supports uploading a metadata file, provide the metadata URL obtained on the SAML2 Web Addon **Usage** tab.
* If the service provider does not support uploading a metadata file, configure settings manually, using the information from the SAML Addon's **Usage** view.

  * For a Login URL, use the **Identity Provider Login URL**, which is the URL to which the service provider should send its SAML Authentication Requests.
  * If you have a custom domain, use the custom-domain-based URL rather than your Auth0 domain. Instead of using a URL in this format:
    `https://{yourTenant}.auth0.com/samlp/CLIENTID?connection=Username-Password-Authentication`
    You will want to use one in this format:
    `https://{yourCustomDomain}/samlp/CLIENTID?connection=Username-Password-Authentication`.
  * If you are using [Organizations](/docs/manage-users/organizations), you can direct users to a specific organization's login prompt by providing an organization ID in the query string as the `organization` parameter. Optionally, you can also specify the connection by including the `connection` parameter. Example: `https://{yourTenant}.auth0.com/samlp/CLIENTID?connection=Acme-Saml-Connection&organization=org_123456789`
  * If the service provider also has a field for a Logout URL, enter the **Identity Provider Login URL** again; both login and logout are handled by the same URL.
* Download the certificate from the SAML Addon's **Usage** view and provide it to the service provider. This certificate will be used to validate the signature of the SAML Authentication Assertions sent from Auth0 to the service provider. If the service provider asks for an **Issuer**, this can also be obtained from the SAML Addon's **Usage** view.

### Test configuration

Once you have completed the above configuration, test the login.

* If your application doesn't work the first time, clear your browser history and (ideally) cookies each time before you test. Otherwise, the browser may not pick up the latest version of your HTML page, or it may have stale cookies that impact execution.
* To help troubleshoot SSO, capture an HTTP trace of the interaction. Many tools will capture the HTTP traffic from your browser for analysis.

  * Search the internet for "HTTP Trace" to find and install a tool.
  * Capture the login sequence from start to finish and analyze the trace. Track the sequence of GETs to see how far in the expected sequence you get. You should see a redirect from your original site to the SP and then to the IdP, a post of credentials if you had to log in, then a redirect back to the callback URL or the SP, and then a redirect to the callback URL specified in your application.
* Make sure that cookies and JavaScript are enabled for your browser.
* Use the [http://samltool.io](http://samltool.io) tool to decode a SAML assertion.

## Learn more

* [Customize SAML Assertions](/docs/authenticate/protocols/saml/saml-configuration/customize-saml-assertions)
* [Troubleshoot SAML Configurations](/docs/troubleshoot/authentication-issues/troubleshoot-saml-configurations)
* [SAML Identity Provider Configuration Settings](/docs/authenticate/protocols/saml/saml-identity-provider-configuration-settings)


# Configure Atlassian as SAML Service Provider
Source: https://auth0.com/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-atlassian

Learn how to configure Auth0 as an identity provider using the SAML2 Web App addon for Atlassian.

Use the following <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> configuration for Atlassian.

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and either create a new application or click the name of an application to update.

2. Go to the **Addons** tab and enable the **SAML2 Web App** toggle.

3. On the **Settings** tab, set the **Application Callback URL** from **SP Assertion Consumer Service URL** in the [Atlassian Admin dashboard](https://admin.atlassian.com/).

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Settings Tab" />
   </Frame>

4. Paste the following code into the **Settings** text box and click **Debug**.

   ```json lines theme={null}
   {
     "mappings": {
       "user_id": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
       "given_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
       "family_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
     },
     "nameIdentifierProbes": [
       "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
       "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
       "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
     ],
     "nameIdentifierFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:email"
   }
   ```

5. Scroll to the bottom of the tab and click **Enable**.

6. On the **Usage** tab, locate **Identity Provider Metadata**, and click **Download** to download the metadata file. You'll need this when you configure Auth0 as the identity provider (IdP).

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Usage Tab" />
   </Frame>


# Configure Cisco WebEx as SAML Service Provider
Source: https://auth0.com/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-cisco-webex

Learn how to configure Auth0 as an identity provider using the SAML2 Web App addon for Cisco WebEx.

Use the following <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> configuration for Cisco WebEx.

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and either create a new application or click the name of an application to update.

2. Go to the **Addons** tab and enable the **SAML2 Web App** toggle.

3. On the **Settings** tab, set the **Application Callback URL.** Note that Webex has an option to automatically provision new users. You will need to send that information as claims (`lastname`, and so on). If you integrate Auth0 with Cisco Spark services, read [Single Sign-On with Cisco Spark Services](https://collaborationhelp.cisco.com/article/en-us/lfu88u).

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Settings Tab" />
   </Frame>

4. Paste the following code into the **Settings** text box and click **Debug**.

   ```json lines theme={null}
   {
          "mappings": {
        "email": ["email", "uid", "Name_ID"]
          },
         "createUpnClaim":       false,
         "passthroughClaimsWithNoMapping": false,
         "mapUnknownClaimsAsIs": false,
         "mapIdentities":        false,
         "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
         "nameIdentifierProbes": [
        "email",
          ]
       }
   ```

5. Scroll to the bottom of the tab and click **Enable**.

6. On the **Usage** tab, locate **Identity Provider Metadata**, and click **Download** to download the metadata file. You'll need this when you configure Auth0 as the identity provider in Cisco WebEx.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Usage Tab" />
   </Frame>


# Configure Datadog as SAML Service Provider
Source: https://auth0.com/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-datadog

Learn how to configure Auth0 as an identity provider using the SAML2 Web App addon for Datadog.

Use the following <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> configuration for Datadog.

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and either create a new application or click the name of an application to update.

2. Go to the **Addons** tab and enable the **SAML2 Web App** toggle.

3. On the **Settings** tab, set the **Application Callback URL** to: `https://app.datadoghq.com/account/saml/assertion`.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Settings Tab" />
   </Frame>

4. Paste the following code into the **Settings** text box and click **Debug**.

   ```json lines theme={null}
   {
         "audience": "https://app.datadoghq.com/account/saml/metadata.xml",
          "mappings": {
          },
          "createUpnClaim":       false,
          "passthroughClaimsWithNoMapping": false,
          "mapUnknownClaimsAsIs": false,
          "mapIdentities":        false,
          "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
          "nameIdentifierProbes": [
        "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
          ],
       }
   ```

5. Scroll to the bottom of the page and click **Enable**.

6. On the **Usage** tab, locate **Identity Provider Metadata**, and click **Download** to download the metadata file. You'll need this when you configure Auth0 as the identity provider (IdP).

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Usage Tab" />
   </Frame>


# Configure Egencia as SAML Service Provider
Source: https://auth0.com/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-egencia

Learn how to configure Auth0 as an identity provider using the SAML2 Web App addon for Egencia.

Use the following <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> configuration for Egencia.

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and either create a new application or click the name of an application to update.

2. Go to the **Addons** tab and enable the **SAML2 Web App** toggle.

3. On the **Settings** tab, set the **Application Callback URL** to: `https://www.egencia.com/auth/v1/artifactConsumer`.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Settings Tab" />
   </Frame>

4. Paste the following code into the **Settings** text box and click **Debug**.

   ```json lines theme={null}
   {
         "audience": "https://{yourAccountName}.egencia.com",
          "mappings": {
          },
          "createUpnClaim":       false,
          "passthroughClaimsWithNoMapping": false,
          "mapUnknownClaimsAsIs": false,
          "mapIdentities":        false,
          "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
          "nameIdentifierProbes": [
        "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
          ],
       }
   ```

5. Scroll to the bottom of the tab and click **Enable**.

6. On the **Usage** tab, locate **Identity Provider Metadata**, and click **Download** to download the metadata file. You'll need this when you configure Auth0 as the identity provider (IdP).

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Usage Tab" />
   </Frame>


# Configure Freshdesk as SAML Service Provider
Source: https://auth0.com/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-freshdesk

Learn how to configure Auth0 as an identity provider using the SAML2 Web App addon for Freshdesk.

Use the following <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> configuration for Freshdesk.

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and either create a new application or click the name of an application to update.

2. Go to the **Addons** tab and enable the **SAML2 Web App** toggle.

3. On the **Settings** tab, set the **Application Callback URL** to: `https://{FD Domain}.freshdesk.com/login/saml`.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Settings Tab" />
   </Frame>

   1. It can be found at:
      **Freshworks Dashboard > Security > SAML SSO > Assertion Consumer Service(ACS) URL**
   2. The audience can be found at:
      **Freshworks Dashboard > Security > SAML SSO > Service Provider(SP) Entity ID URL**

4. Paste the following code into the **Settings** text box and click **Debug**.

   ```json lines theme={null}
   {
         "audience": "https://{FD Domain}.freshworks.com/sp/SAML/{xxxxxxxxxxxxxxxxxxx}/metadata",
         "mappings": {
       "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
       "given_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
       "family_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
         },
         "createUpnClaim": false,
         "passthroughClaimsWithNoMapping": false,
         "mapUnknownClaimsAsIs": false,
         "mapIdentities": false,
         "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
         "nameIdentifierProbes": [
       "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
         ]
       }
   ```

5. Scroll to the bottom of the page and click **Enable**.

6. On the **Usage** tab, locate **Identity Provider Metadata**, and click **Download** to download the metadata file. You'll need this when you configure Auth0 as the identity provider.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Usage Tab" />
   </Frame>


# Configure Hosted Graphite as SAML Service Provider
Source: https://auth0.com/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-hosted-graphite

Learn how to configure Auth0 as an identity provider using the SAML2 Web App addon for Hosted Graphite.

Use the following <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> configuration for Hosted Graphite.

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and either create a new application or click the name of an application to update.

2. Go to the **Addons** tab and enable the **SAML2 Web App** toggle.

3. On the **Settings** tab, set the **Application Callback URL** to: `https://www.hostedgraphite.com/complete/saml/{yourUserId}/`.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Settings Tab" />
   </Frame>

4. Paste the following code into the **Settings** text box and click **Debug**.

   ```json lines theme={null}
   {
         "audience": "https://www.hostedgraphite.com/metadata/{yourUserId}/",
         "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
         "nameIdentifierProbes": [
       "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
         ]
       }
   ```

5. Scroll to the bottom of the page and click **Enable**.

6. On the **Usage** tab, locate **Identity Provider Metadata**, and click **Download** to download the metadata file. You'll need this when you configure Auth0 as the identity provider.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Usage Tab" />
   </Frame>


# Configure Litmos as SAML Service Provider
Source: https://auth0.com/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-litmos

Learn how to configure Auth0 as an identity provider using the SAML2 Web App addon for Litmos.

Use the following <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> configuration for Litmos.

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and either create a new application or click the name of an application to update.

2. Go to the **Addons** tab and enable the **SAML2 Web App** toggle.

3. On the **Settings** tab, set the **Application Callback URL** to: `https://{yourDomain}.litmos.com/integration/samllogin`.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Settings Tab" />
   </Frame>

4. Paste the following code into the **Settings** text box and click **Debug**.

   <AuthCodeBlock />

5. Scroll to the bottom of the page and click **Enable**.

6. On the **Usage** tab, locate **Identity Provider Metadata**, and click **Download** to download the metadata file. You'll need this when you configure Auth0 as the identity provider.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Usage Tab" />
   </Frame>


# Configure Pluralsight as SAML Service Provider
Source: https://auth0.com/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-pluralsight

Learn how to configure Auth0 as an identity provider using the SAML2 Web App addon for Pluralsight.

Use the following <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> configuration for Pluralsight.

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and either create a new application or click the name of an application to update.

2. Go to the **Addons** tab and enable the **SAML2 Web App** toggle.

3. On the **Settings** tab, set the **Application Callback URL** to: `https://prod-pf.pluralsight.com/sp/ACS.saml2`.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Settings Tab" />
   </Frame>

4. Paste the following code into the **Settings** text box and click **Debug**.

   ```json lines theme={null}
   {
         "audience":  "www.pluralsight.com",
         "mappings": {
       "user_id":     "id",
       "email":       "email",
       "given_name":  "firstName",
       "family_name": "lastName"
         },
         "createUpnClaim":       false,
         "passthroughClaimsWithNoMapping": false,
         "mapUnknownClaimsAsIs": false,
         "mapIdentities":        false,
         "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
         "nameIdentifierProbes": [
       "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
         ]
       }
   ```

5. Scroll to the bottom of the page and click **Enable**.

6. On the **Usage** tab, locate **Identity Provider Metadata**, and click **Download** to download the metadata file. You'll need this when you configure Auth0 as the identity provider.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Usage Tab" />
   </Frame>


# Configure Sprout Video as SAML Service Provider
Source: https://auth0.com/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-sprout-video

Describes how to configure Auth0 to serve as an identity provider for Sprout Video.

Use the following <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> configuration for Sprout Video.

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and either create a new application or click the name of an application to update.

2. Go to the **Addons** tab and enable the **SAML2 Web App** toggle.

3. On the **Settings** tab, set the **Application Callback URL** that you can obtain from your Sprout Video settings. It will typically be something like: `https://app.sproutvideo.com/auth/sso/consumption`.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Settings Tab" />
   </Frame>

4. Paste the following code into the **Settings** text box and click **Debug**.

   ```json lines theme={null}
   {
        "audience":  "https://{yourSproutVideoAccount}.vids.io",
        "mappings": {  
          "user_id":     "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
          "email":       "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
        },
        "createUpnClaim":       false,
        "passthroughClaimsWithNoMapping": false,
        "mapUnknownClaimsAsIs": false,
        "mapIdentities":        false,
        "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
        "nameIdentifierProbes": [
          "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
        ],
       }
   ```

5. Scroll to the bottom of the page and click **Enable**.

6. On the **Usage** tab, locate **Identity Provider Metadata**, and click **Download** to download the metadata file. You'll need this when you configure Auth0 as the identity provider.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Usage Tab" />
   </Frame>


# Configure Tableau Online as SAML Service Provider
Source: https://auth0.com/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-tableau-online

Learn how to configure Auth0 as an identity provider using the SAML2 Web App addon for Tableau Online.

Use the following <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> configuration for Tableau Online.

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and either create a new application or click the name of an application to update.

2. Go to the **Addons** tab and enable the **SAML2 Web App** toggle.

3. On the **Settings** tab, set the **Application Callback URL** to: `https://sso.online.tableau.com/public/sp/SSO/{yourTableauAlias}`.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Settings Tab" />
   </Frame>

4. Paste the following code into the **Settings** text box and click **Debug**.

   ```json lines theme={null}
   {
        "audience":  "https://sso.online.tableau.com/public/sp/metadata?alias={yourTableauAlias}",
        "recipient": "https://sso.online.tableau.com/public/sp/SSO/{yourTableauAlias}",
        "mappings": {
       "email": "Email"
        },
        "createUpnClaim":       false,
        "passthroughClaimsWithNoMapping": false,
        "mapUnknownClaimsAsIs": false,
        "mapIdentities":        false,
        "signatureAlgorithm":   "rsa-sha256",
        "digestAlgorithm":      "sha256",
        "destination":          "https://sso.online.tableau.com/public/sp/SSO/{yourTableauAlias}",
        "lifetimeInSeconds":    3600,
        "signResponse":         false,
        "nameIdentifierFormat": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
        "nameIdentifierProbes": [
          "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
        ]
       }
   ```

5. Scroll to the bottom of the page and click **Enable**.

6. On the **Usage** tab, locate **Identity Provider Metadata**, and click **Download** to download the metadata file. You'll need this when you configure Auth0 as the identity provider.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Usage Tab" />
   </Frame>


# Configure Tableau Server as SAML Service Provider
Source: https://auth0.com/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-tableau-server

Learn how to configure Auth0 as an identity provider using SAML2 Web App addon for Tableau Server.

Use the following <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> configuration for Tableau Server.

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and either create a new application or click the name of an application to update.

2. Go to the **Addons** tab and enable the **SAML2 Web App** toggle.

3. On the **Settings** tab, set the **Application Callback URL** to: `http://{yourTableauServer}/wg/saml/SSO/index.html`.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Settings Tab" />
   </Frame>

4. Paste the following code into the **Settings** text box and click **Debug**.

   ```json lines theme={null}
   {
        "audience":  "{yourTableauAudience}",
        "recipient": "http://{yourTableauServer}/wg/saml/SSO/index.html",
        "mappings": {
       "email": "username"
        },
        "createUpnClaim":       false,
        "passthroughClaimsWithNoMapping": false,
        "mapUnknownClaimsAsIs": false,
        "mapIdentities":        false,
        "signatureAlgorithm":   "rsa-sha1",
        "digestAlgorithm":      "sha1",
        "destination":          "http://{yourTableauServer}/wg/saml/SSO/index.html",
        "lifetimeInSeconds":    3600,
        "signResponse":         false,
        "nameIdentifierFormat": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
        "nameIdentifierProbes": [
          "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
        ]
       }
   ```

5. Scroll to the bottom of the page and click **Enable**.

6. On the **Usage** tab, locate **Identity Provider Metadata**, and click **Download** to download the metadata file. You'll need this when you configure Auth0 as the identity provider.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Usage Tab" />
   </Frame>


# Configure Workday as SAML Service Provider
Source: https://auth0.com/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-workday

Learn how to configure Auth0 as an identity provider using the SAML2 Web App addon for Workday.

Use the following <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> configuration for Workday.

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and either create a new application or click the name of an application to update.
2. Go to the **Addons** tab and enable the **SAML2 Web App** toggle.
3. On the **Settings** tab, set the **Application Callback URL** to: `https://impl.workday.com/<tenant>/login-saml.htmld`.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Settings Tab" />
   </Frame>
4. Paste the following code into the **Settings** text box and click **Debug**.

   ```json lines theme={null}
   {
         "audience": "http://www.workday.com",
         "recipient": "https://www.myworkday.com/<tenant>/login-saml.htmld",
         "mappings": {
         },
         "createUpnClaim":       false,
         "passthroughClaimsWithNoMapping": false,
         "mapUnknownClaimsAsIs": false,
         "mapIdentities":        false,
         "signResponse":         true,
         "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName",
         "nameIdentifierProbes": [
       "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
         ],
         "authnContextClassRef": "urn:oasis:names:tc:SAML:2.0:ac:classes:X509",
       }
   ```

   Change the subdomain `impl` depending on the Workday data center you are using.
5. Scroll to the bottom of the page and click **Enable**.
6. On the **Usage** tab, locate **Identity Provider Metadata**, and click **Download** to download the metadata file. You'll need this when you configure Auth0 as the identity provider.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Usage Tab" />
   </Frame>


# Configure Workpath as SAML Service Provider
Source: https://auth0.com/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-workpath

Learn how to configure Auth0 as an identity provider using the SAML2 Web App addon for Workpath.

Use the following <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> configuration for Workpath.

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and either create a new application or click the name of an application to update.

2. Go to the **Addons** tab and enable the **SAML2 Web App** toggle.

3. On the **Settings** tab, set the **Application Callback URL** to: `https://api.workpath.com/v1/saml/assert/{yourWorkpathSubdomain}`.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Settings Tab" />
   </Frame>

4. Paste the following code into the **Settings** text box and click **Debug**.

   ```json lines theme={null}
   {
         "audience": "https://api.workpath.com/v1/saml/metadata/{yourWorkpathSubdomain}",
         "mappings": {
       "email": "email",
       "given_name": "first_name",
       "family_name": "last_name"
         }
       }
   ```

5. Scroll to the bottom of the page and click **Enable**.

6. On the **Usage** tab, locate **Identity Provider Metadata**, and click **Download** to download the metadata file. You'll need this when you configure Auth0 as the identity provider.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Usage Tab" />
   </Frame>


# Configure Google Workspace as SAML Service Provider
Source: https://auth0.com/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-idp-for-google-g-suite

Learn how to configure Auth0 as an identity provider using the SAML2 Web App for Google Workspace.

Use the following <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> configuration for Google Workspace.

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and either create a new application or click the name of an application to update.

2. Go to the **Addons** tab and enable the **SAML2 Web App** toggle.

3. On the **Settings** tab, set the **Application Callback URL** to: `https://www.google.com/a/{YOUR-GOOGLE-DOMAIN}/acs`.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Settings Tab" />
   </Frame>

4. Paste the following code into the **Settings** text box and click **Debug**.

   ```json lines theme={null}
   {
         "audience": "https://www.google.com/a/{yourGoogleDomain}/acs",
         "mappings": {
       "nickname": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
         },
         "createUpnClaim": false,
         "passthroughClaimsWithNoMapping": false,
         "mapUnknownClaimsAsIs": false,
         "mapIdentities": false,
         "signatureAlgorithm": "rsa-sha256",
         "digestAlgorithm": "sha256",
         "nameIdentifierFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:email",
         "nameIdentifierProbes": [
       "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
         ],
       }
   ```

5. Scroll to the bottom of the page and click **Enable**.

6. On the **Usage** tab, locate **Identity Provider Metadata**, and click **Download** to download the metadata file. You'll need this when you configure Auth0 as the identity provider (IdP).

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Usage Tab" />
   </Frame>


# Configure Oracle Eloqua Marketing Cloud as SAML Service Provider
Source: https://auth0.com/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-addon-eloqua

Learn how to configure the Auth0 as the identity provider using the SAML2 Web App addon for Oracle Eloqua.

Use the following <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> configuration for Oracle Eloqua Marketing Cloud.

## Configure SAML SSO in Auth0

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and either create a new application or click the name of the application you want to update.
2. Go to the **Addons** tab and enable the **SAML2 Web App** toggle.
3. On the **Settings** tab, set the **Application Callback URL** to: `https://login.eloqua.com/auth/saml2/acs`.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Settings Tab" />
   </Frame>
4. Paste the following code into the **Settings** text box and click **Debug**.

   ```json lines theme={null}
   {
       "audience": "<Service Provider Entity Url from within Eloqua>",
        "recipient": "https://login.eloqua.com/auth/saml2/acs",
          "mappings": {
       "user_id": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
       "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
       "name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
          },
        "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
        "nameIdentifierProbes": [
       "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
       ],
        "destination": "https://login.eloqua.com/auth/saml2/acs"
         }
   ```

   Note that the `audience` is set to `http://foo`. This will be changed when the identity provider settings are completed on the Eloqua side.
5. Scroll to the bottom of the tab and click **Enable**.
6. On the **Usage** tab, locate the **Identity Provider Metadata** and click **Download** to download the metadata file. You'll need this when you configure Auth0 as the identity provider in Eloqua.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Usage Tab" />
   </Frame>

## Configure SAML SSO in Oracle Eloqua

1. Login as Admin on Eloqua and click on **Settings > Users > Single Sign-On > Identity Provider Settings**.
2. Click **Upload Identity Provider from Metadata**. Upload the **Identity Provider metadata** you downloaded from the **Usage** tab in the Auth0 Dashboard.
3. Browse to find the downloaded metadata file.
4. Edit the newly added identity provider and complete the following steps:

   1. Set the **User Identity Mapping** to `Assertion contains the Email Address from the User object` and click **Save**.
   2. From the **Identity Provider Details** copy the **Service Provider Entity URL**.
   3. Within ELOQUA IdP settings, if this is the default IdP, mark this IdP as default.

## Update Audience Restriction in Auth0

Use the **Service Provider Entity URL** copied from the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> settings in Eloqua to set the `audience` restriction in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and click the name of the application you want to update.
2. Go to the **Addons** tab and enable the **SAML2 Web App** toggle.
3. On the **Settings** tab, update the `audience` to the value you copied from Eloqua.

## Test configuration

**Login to Eloqua with Auth0** should be enabled now. You can sign in to Eloqua with both IdP-initiated login and SP-initiated login.

* For SP-initiated login, go to \<[https://login.eloqua.com/auth/saml2>](https://login.eloqua.com/auth/saml2>) and enter your company name and start the SAML login process with Auth0.
* For IdP-Initiated login use the **Identity Provider Login URL** defined here: **Dashboard > Applications > Applications** on the **Addons** tab,  **SAML 2 Web App**, **Usage** tab.


# Configure Amazon Web Services as SAML Service Provider
Source: https://auth0.com/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-aws

Learn how to configure Auth0 as an identity provider using the SAML2 Web App addon for Amazon Web Services (AWS).

Configure the SAML2 Web App addon for Amazon Web Services (AWS) for an application.

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and either create a new application or click the name of an application to update.

2. Go to the **Addons** tab and enable the **SAML2 Web App** toggle.

3. On the **Settings** tab, set the **Application Callback URL** to: `https://signin.aws.amazon.com/saml`.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Settings Tab" />
   </Frame>

4. Paste the following code into the **Settings** text box and click **Debug**. Be sure to replace the `AWS_SSO_ISSUER_URL` and `AWS_SSO_ACS_URL` placeholders with values you copied from AWS.

   ```json lines theme={null}
   {
     "audience": "AWS_SSO_ISSUER_URL",
     "destination": "AWS_SSO_ACS_URL",
     "mappings": {
       "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
       "name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
     },
     "createUpnClaim": false,
     "passthroughClaimsWithNoMapping": false,
     "mapUnknownClaimsAsIs": false,
     "mapIdentities": false,
     "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
     "nameIdentifierProbes": [
       "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
     ]
   }
   ```

5. Scroll to the bottom of the page and click **Enable**.

6. On the **Usage** tab, locate **Identity Provider Metadata**, and click **Download** to download the metadata file. You'll need this when you configure Auth0 as the identity provider.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Usage Tab" />
   </Frame>

To learn how to configure AWS for <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip>, read [Configure Amazon Web Services for Single Sign-On](/docs/customize/integrations/aws/configure-amazon-web-services-for-sso).

## Learn more

* [Use Amazon Web Services Session Tags for Role-Based Access Control](/docs/customize/integrations/aws/session-tags)
* [Configure Amazon Web Services for Single Sign-On](/docs/customize/integrations/aws/configure-amazon-web-services-for-sso)


# Configure GitHub Enterprise Cloud as SAML Service Provider
Source: https://auth0.com/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-github-enterprise-cloud

Learn how to configure Auth0 as an identity provider using the SAML2 Web App addon for a GitHub Enterprise Cloud (github.com) organization.

You can configure Auth0 to serve as an <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> for [GitHub Enterprise Cloud](https://help.github.com/en/articles/about-authentication-with-saml-single-sign-on) (github.com). GitHub requires an enterprise-level subscription to enable using an external <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> IdP.

* To learn about <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> on GitHub, read [About authentication with SAML single sign-on](https://help.github.com/en/articles/about-authentication-with-saml-single-sign-on) on [https://docs.github.com](https://docs.github.com).
* To learn how to configure Auth0 as the identity provider for GitHub Enterprise Server (private instance), read [Configure Auth0 as Identity Provider for GitHub Enterprise Server](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-github-enterprise-server).

## Configure SAML SSO on Auth0

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and create a new application. Give it a meaningful name like **GitHub**. You can choose any application type, but the **Regular Web App** type is recommended.
2. Go to the [Addons](https://manage.auth0.com/#/applications/\{yourClientId}/addons) tab and enable the **SAML2 Web App** toggle.
3. On the **Settings** tab, set the **Application Callback URL** to: `https://github.com/orgs/{YOUR_GITHUB_ORG_NAME}/saml/consume`.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Settings Tab" />
   </Frame>
4. Paste the following code into the **Settings** text box and click **Debug**.

   ```json lines theme={null}
   {
         "audience": "https://github.com/orgs/{yourGitHubOrgName}",
         "mappings": {
       "user_id": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
       "email": "emails",
       "name": "full_name"
         },
         "passthroughClaimsWithNoMapping": false,
         "mapIdentities": false,
         "signatureAlgorithm": "rsa-sha256",
         "digestAlgorithm": "sha256",
         "nameIdentifierProbes": [
       "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"
         ]
       }
   ```

   1. Replace `{YOUR_GITHUB_ORG_NAME}` with the GitHub organization name that corresponds to your subscription. The mapping will send the `user_id` as the **Name Identifier** to GitHub. This is a good option if you enable more than one connection for the GitHub application, as it will ensure uniqueness (every user will have a different ID).
   2. If you are using a single connection, you might want to use the `nickname` or another unique identifier as a friendlier **Name Identifier** (but make sure that the property you choose is unique). As an example, if you want `nickname` as the **Name Identifier**, the `mappings` section above will look like this:
5. Scroll to the bottom of the tab and click **Enable**.
6. On the **Usage** tab, locate **Identity Provider Metadata** and click **Download** to download the metadata file. You will need this when you configure Auth0 as the identity provider.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Usage Tab" />
   </Frame>

## Configure SAML SSO on GitHub

1. Follow the instructions in GitHub for [Enabling and testing SAML Single Sign-on (SSO) for your organization](https://help.github.com/en/articles/enabling-and-testing-saml-single-sign-on-for-your-organization) to complete the configuration on GitHub Enterprise Cloud.
2. You will need the following information:

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Entry</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Sign On URL</td>

      <td>
        `https://{yourDomain}/samlp/{CLIENT_ID}`<br />
        &#x20;will be the <code>client\_id</code> for the GitHub application you just created in Auth0.
      </td>
    </tr>

    <tr>
      <td>Issuer</td>
      <td>`urn:auth0:{yourTenant}`</td>
    </tr>

    <tr>
      <td>Public Certificate</td>

      <td>
        Download it from `https://{yourDomain}/pem`. Open the downloaded file with a text editor, copy the contents and paste it in the text area on GitHub.
      </td>
    </tr>

    <tr>
      <td>Signature method</td>
      <td>`RSA256-SHA256`</td>
    </tr>

    <tr>
      <td>Digest method</td>
      <td>`SHA256`</td>
    </tr>
  </tbody>
</table>

3. As recommended in GitHub's documentation, before enabling SAML SSO for your organization, click **Test SAML configuration** to ensure that the information you've entered is correct.

When setting up SAML single sign-on (SSO) for your organization, you can test your implementation without affecting your organization members by leaving **Require SAML SSO authentication** **for all members of the organization** unchecked.


# Configure GitHub Enterprise Server as SAML Service Provider
Source: https://auth0.com/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-github-enterprise-server

Learn how to configure Auth0 as the identity provider using the SAML2 Web App addon for a GitHub Enterprise Server private instance.

You can configure Auth0 as the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> using the SAML2 Web App addon for [GitHub Enterprise Server](https://help.github.com/en/enterprise/2.16/admin/user-management/using-saml) (i.e. your private GitHub appliance). If you are looking for instructions to set up Auth0 as the identity provider for GitHub Enterprise Cloud (github.com), read [Configure Auth0 as Identity Provider for GitHub Enterprise Cloud](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-github-enterprise-cloud) instead.

## Configure SAML SSO on Auth0

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and create a new application. Give it a meaningful name like **GitHub**. You can choose any application type, but the **Regular Web App** type is recommended.
2. Go to the [Addons](https://manage.auth0.com/#/applications/\{yourClientId}/addons) tab and enable the **SAML2 Web App** toggle.
3. On the **Settings** tab, set the **Application Callback URL** to : `https://github.com/orgs/{yourGitHubOrgName}/saml/consume`.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Settings Tab" />
   </Frame>
4. Paste the following code into the **Settings** text box and click **Debug**.

   ```json lines theme={null}
   {
         "audience": "{yourGitHubServerUrl}",
         "mappings": {
       "user_id": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
       "email": "emails",
       "name": "full_name"
         },
         "passthroughClaimsWithNoMapping": false,
         "mapIdentities": false,
         "signatureAlgorithm": "rsa-sha256",
         "digestAlgorithm": "sha256",
         "nameIdentifierProbes": [
       "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"
         ]
       }
   ```

   Replace `{yourGitHubOrgName}` with the GitHub organization name that corresponds to your GitHub subscription. For example `https://github.yourname.com`.

   1. The above mapping will send the `user_id` as the **Name Identifier** to GitHub. Use this option if you enable more than one connection for the GitHub application, as it will ensure uniqueness (every user will have a different ID).
   2. If you are using a single connection, you might prefer to use the `nickname` or another unique identifier as a friendlier **Name Identifier**, but make sure that the property you choose is unique.
5. Scroll to the bottom of the tab and click **Enable**.
6. On the **Usage** tab, locate **Identity Provider Metadata**, and click **Download** to download the metadata file. You'll need this when you configure Auth0 as the identity provider.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Usage Tab" />
   </Frame>

## Configure SAML SSO on GitHub

Follow the instructions in [Using SAML on Enterprise Server- GitHub Help](https://help.github.com/en/enterprise/admin/user-management/using-saml#configuring-saml-settings) to complete the configuration on GitHub Enterprise Cloud. You will need the following information:

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Entry</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Sign On URL</td>

      <td>
        `https://{yourDomain}/samlp/{CLIENT_ID}`<br />
        &#x20;will be the <code>client\_id</code> for the GitHub application you just created in Auth0.
      </td>
    </tr>

    <tr>
      <td>Issuer</td>
      <td>`urn:auth0:{yourTenant}`</td>
    </tr>

    <tr>
      <td>Public Certificate</td>

      <td>
        Download it from `https://{yourDomain}/pem`. Open the downloaded file with a text editor, copy the contents and paste it in the text area on GitHub.
      </td>
    </tr>

    <tr>
      <td>Signature method</td>
      <td>`RSA256-SHA256`</td>
    </tr>

    <tr>
      <td>Digest method</td>
      <td>`SHA256`</td>
    </tr>
  </tbody>
</table>


# Configure Heroku as SAML Service Provider
Source: https://auth0.com/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-heroku

Learn how to configure the Auth0 as an identity provider using the SAML2 Web App Addon for Heroku.

Use the following <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> configuration for Heroku.

## Configure SAML SSO in Auth0

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and either create a new application or click the name of an application to update.
2. Go to the **Addons** tab and enable the **SAML2 Web App** toggle.
3. On the **Settings** tab, set the **Application Callback URL** to the **ACS URL** for your organization from the Settings page in the Single Sign-On section in Heroku.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Settings Tab" />
   </Frame>
4. Paste the following code into the **Settings** text box and click **Debug**.

   ```json lines theme={null}
   {
        "audience":"THE-HEROKU-ENTITY-ID",
        "mappings": {
          "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
        },
        "createUpnClaim": false,
        "passthroughClaimsWithNoMapping": false,
        "mapUnknownClaimsAsIs": false,
        "mapIdentities": false,
        "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
        "nameIdentifierProbes": [
          "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
        ]
       }
   ```

   The `audience` parameter is the **Heroku Entity ID** from the Settings page in Heroku. It will be formatted like this: `https://sso.heroku.com/saml/{yourHerokuOrg}.`
5. Scroll to the bottom of the page and click **Enable**.
6. On the **Usage** tab, locate **Identity Provider Metadata**, and click **Download** to download the metadata file. You'll need this when you configure Auth0 as the identity provider in Heroku.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Usage Tab" />
   </Frame>

## Configure SAML SSO in Heroku

In Heroku, on the Settings page in the <Tooltip href="/docs/glossary?term=Single+Sign-On">Single Sign-On</Tooltip> section, click **Upload Metadata** and select the file containing the **<Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> Metadata** you downloaded in the previous step.


# Implementation Planning Checklists
Source: https://auth0.com/docs/get-started/architecture-scenarios/checklists

Links to checklists for your implementation.

Click the links below to download a checklist that corresponds to a phase in the SDLC (Software Development Lifecycle). You can open the checklist in any spreadsheet application and customize them to suit your needs.

## Analyze Checklist

[Analyze Checklist Download](https://cdn2.auth0.com/docs/media/articles/architecture-scenarios/checklists/Analyze-Checklist.xlsx)

In the Analyze phase, analyze end-user business requirements and determine project goals as part of the high-level plan for the project. Convert the requirements and goals into system functions that the organization intends to develop. Activities include:

* Gathering business requirements
* Creating process diagrams
* Performing detailed analysis
* Alignment to project plan

## Design Checklist

[Design Checklist Download](https://cdn2.auth0.com/docs/media/articles/architecture-scenarios/checklists/Design-Checklist.xlsx)

In the Design phase, describe the desired features and operations of the system, including business rules, pseudo-code, screen layouts, and other necessary documentation. Activities include:

* Infrastructure design
* System model design

## Build Checklist

[Build Checklist Download](https://cdn2.auth0.com/docs/media/articles/architecture-scenarios/checklists/Build-Checklist.xlsx)

In the Build phase, develop the actual system through implementation of infrastructure and code. Activities include:

* Infrastructure implementation
* Code implementation

## Test Checklist

[Test Checklist Download](https://cdn2.auth0.com/docs/media/articles/architecture-scenarios/checklists/Test-Checklist.xlsx)

In the Test phase, integrate and deploy all implemented code in the testing environment infrastructure. Testing then follows Software Testing Life Cycle activities to check the system for errors, bugs, and defects to verify that system features work as expected (or not). Activities include:

* Write test cases
* Execute test cases

## Deploy Checklist

[Deploy Checklist Download](https://cdn2.auth0.com/docs/media/articles/architecture-scenarios/checklists/Deploy-Checklist.xlsx)

In the Deploy phase, deploy the system to either a staging or production environment, where actual users begin to operate and interact with it.

Eventually, you deploy all components of the system to the production environment when you make a live release.

## Monitor Checklist

[Monitor Checklist Download](https://assets.ctfassets.net/cdy7uua7fh8z/4FYZQXQHknEDkLflShHXBz/d8757810ace0fc9dbabad9b1715d0dbf/Monitor-Checklist.xlsx)

In the Monitor phase, make enhancements, corrections, and changes to ensure the system continues to work and stays updated to meet the business objectives and support the needs of the users. Activities include:

* Monitoring
* Maintenance
* Changes and adjustments
* Upgrade and adapt to future needs


# Implementation Resources
Source: https://auth0.com/docs/get-started/architecture-scenarios/implementation-resources

Learn about all the resources Auth0 provides to help you with your Auth0 implementation.

Auth0 provides a wealth of resources to help you effectively engage with our product and community. This list provides links to the resources available, by category.

## Get started

Resources designed to help you learn the basics of Auth0 include:

* [**Getting Started documentation**](/docs/get-started): Explore the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> and common terms used for components of the Auth0 service. Gain a broad understanding of Auth0 and learn the terminology you might hear when working with Auth0 staff or reading our docs.
* [**Architecture scenarios**](/docs/get-started/architecture-scenarios): Review common architecture scenarios and learn how to implement them with Auth0. Scenarios include tutorials for common architecture patterns, such as a Single-Page Application (SPA) calling an API. High-level descriptions are useful for architects, while tutorials will help development teams.
* [**Implementation guides**](/docs/): Learn how to implement commonly-used features, such as user management and <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA). This information is useful for both architects and developers

## Learn

Auth0 provides numerous tutorials, guides, white papers, and blog posts that focus on both learning and providing quick reference checks.

* [**Docs site**](/docs/): Browse through our docs to explore a wealth of available topics, or use our search to quickly find content related to a topic or term.
* [**Feature descriptions and white papers**](https://auth0.com/learn/): Investigate short descriptions of features, industry case studies, and reference white papers. The Auth0 Learn site provides a quick overview of Auth0 features and their business value; it is helpful for project owners as well as architects and developers.
* [**Blog posts**](https://auth0.com/blog/): Read blog posts written by experts on a variety of topics--from time-honored advice to breaking news in the identity space. Many blog posts are oriented toward architects and developers.

## Run sample code

Once your development team is ready to build, Auth0 provides sample programs, SDKs, and libraries to speed your project along.

* [**Quickstarts**](/docs/quickstarts): Investigate a rich array of small sample programs that demonstrate how to implement the key features you’ll want to include in your program, such as authentication, session management, profile updates, and logout. Quickstarts will give developers a head start on understanding how to integrate applications with Auth0.
* [Libraries and SDKs](/docs/libraries): Simplify your custom application development by using our extensive set of libraries and SDKs, which abstract many of the details of identity protocols for you. Auth0 SDKs support numerous languages and frameworks to simplify your integration with Auth0. We also provide a library for Lock, a login widget, that you can use across several platforms, including iOS and Android.
* [**Management API**](https://auth0.com/docs/api/management/v2): Explore and manipulate objects, configurations, and settings within Auth0. The <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> Explorer allows you to quickly manipulate individual objects and settings on an ad-hoc basis and test API calls before coding them into your applications.
* [**Authentication API**](https://auth0.com/docs/api/authentication): Authenticate and authorize users via the OIDC, <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip>, and <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> protocols. The Authentication API Explorer allows you to experiment with authentication and <Tooltip href="/docs/glossary?term=authorization+flows">authorization flows</Tooltip>, and test API calls before coding them into your applications.

## Try out features and API calls

While building, Auth0 allows you to experiment with and test out various product features.

* **TRY buttons/links**: Quickly try out Auth0 product features. **TRY** buttons are located throughout Auth0 and allow you to experiment with connections, rules, hooks, and email templates.
* [**Authentication API Explorer**](https://auth0.com/docs/api/authentication#introduction): Experiment with authentication and authorization flows, and test API calls before coding them into your applications.
* [**Management API Explorer**](https://auth0.com/docs/api/management/v2): Quickly manipulate individual objects and settings on an ad-hoc basis and test API calls before coding them into your applications.

## Get help

Auth0 resources that help you troubleshoot your implementation include:

* [**Auth0 Community forum**](https://community.auth0.com/): Connect with the world of Auth0 via Auth0 posts, FAQs, and community Q\&As. Architects and developers find this a valuable source of information for learning and connecting with others as well as getting help on issues.
* [**Support Center**](https://support.auth0.com/): View and manage your subscription and tenants, file and view support requests, run automated production checks on a tenant, and view compliance information. Paid subscribers will find the support center a valuable resource if an issue or question cannot be solved by documentation or by searching the forum.

  * [**Create support cases**](/docs/troubleshoot/customer-support/open-and-manage-support-tickets): Create and file a support case if you need help.
  * [**Support Plans and Service Level Agreements**](/docs/troubleshoot/customer-support#defect-responses): Learn about multiple levels of support available for purchase.
  * [**Troubleshooting tips**](/docs/deploy-monitor/deploy-private-cloud/private-cloud-on-aws#what-to-check-before-logging-an-issue) and [**Information to include in your support case**](/docs/deploy-monitor/deploy-private-cloud/private-cloud-on-aws#information-to-provide-when-logging-an-issue): Get advice to help your development and support teams analyze issues.
* [**Supported versions**](/docs/troubleshoot/customer-support/product-support-matrix): Understand which versions of SDKs, browsers, and languages are supported. Architects and developers should review this to ensure your project employs languages, libraries, and SDKs that will allow your implementation to work with Auth0.
* [**Feedback Portal**](https://auth0.com/feedback): Make product suggestions. (You can also do this via the Support Center if you want better visibility into what you’ve filed over time.) Architects and developers can use this site to provide feedback on the Auth0 product for consideration as enhancements in the future.
* [**Professional Services**](/docs/get-started/professional-services): Engage our world-wide professional services team to help speed your project to success. Project owners will find this useful for learning how Auth0 identity experts can help accelerate your project or fill in any temporary skill gaps.

## Set up and monitor operations

When you're ready to plan your launch, Auth0 provides the following resources:

* [**Pre-launch advice**](/docs/deploy-monitor/pre-deployment-checks) and [**Production check**](/docs/deploy-monitor/pre-deployment-checks/how-to-run-production-checks): Get tips and tools to help you plan your launch. Project managers and development and operations teams should explore these tips to leverage advice for a smooth launch.
* [**Operational policies**](/docs/troubleshoot/customer-support/operational-policies): Familiarize yourself with Auth0's policies, so you know lead times for operational requests. Policies are useful for an entire team, but project owners and operations teams in particular should be aware of Auth0's operational policies.
* [**Status Dashboard**](https://status.auth0.com/): Quickly determine the availability of Auth0 services and subscribe to status updates. Although service interruptions are rare, when one occurs Auth0 conducts a root cause analysis and publishes the results on this site. Operations and support teams should be familiar with how to check Auth0 status.
* [**Monitor endpoints**](/docs/deploy-monitor): Learn how to integrate our monitoring endpoints into your monitoring infrastructure. This information is of particular use to operations teams and project owners.
* [**Log data**](/docs/deploy-monitor/logs): Learn about the types of logs Auth0 provides, log data retention, and tools you can use to export log data to external analytical tools for analysis and long-term data storage. This information is useful for developers and operations teams, as well as compliance teams interested in data retention.
* [**Dashboard notices**](/docs/get-started/architecture-scenarios/business-to-consumer/operations#notifications): Stay informed about important announcements from Auth0. From time to time, Auth0 notifies you of important information via your Auth0 Dashboard and (depending on the severity of the information) via email to your registered Auth0 Dashboard Admins. You should regularly log in to the Dashboard and check the bell icon at the top for any important notices.

## Satisfy privacy, security, and compliance needs

View info on Auth0’s privacy policy, security policy, compliance certifications, and how Auth0 can help you with your compliance needs. This information is useful for project owners as well as security, privacy teams, and procurement teams.

* [Privacy and Cookie Policy](https://auth0.com/privacy)
* [Security, Privacy and Compliance](https://auth0.com/security/)
* [Compliance Frameworks and Certifications](/docs/secure/data-privacy-and-compliance)


# Mobile Applications with API
Source: https://auth0.com/docs/get-started/architecture-scenarios/mobile-api

Explains the architecture scenario with a mobile application communicating with an API.

In this scenario we will build a timesheet API for a fictitious company named ExampleCo. The API will allow management of timesheet entries for an employee or a contractor.

We will also be building a mobile application which will be used to view and log timesheet entries in the centralized timesheet database using the API.

<Info>
  ### TL;DR

  * Auth0 provides API Authentication and Authorization as a means to secure access to API endpoints (see [API Authentication and Authorization](/docs/get-started/architecture-scenarios/mobile-api/part-1#api-authentication-and-authorization))
  * For authorizing a mobile app user and granting access to the API, Auth0 supports the [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce) (see [Proof Key for Code Exchange](/docs/get-started/architecture-scenarios/mobile-api/part-1#proof-key-for-code-exchange-pkce-))
  * Both the mobile app and the API must be configured in the Auth0 Dashboard (see [Auth0 Configuration](/docs/get-started/architecture-scenarios/mobile-api/part-2))
  * User Permissions can be enforced using the Authorization Extension (see [Configure the Authorization Extension](/docs/get-started/architecture-scenarios/mobile-api/part-2#configure-the-authorization-extension))
  * The API is secured by ensuring that a valid <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> is passed in the HTTP Authorization header when calls are made to the API (see [Implement the API](/docs/get-started/architecture-scenarios/mobile-api/part-3#secure-the-endpoints))
  * The Auth0.Android SDK can be used to authorize the user of the mobile app and obtain a valid Access Token which can be used to call the API (see [Authorize the User](/docs/get-started/architecture-scenarios/mobile-api/part-3#authorize-the-user))
  * The mobile app can retrieve the user's profile information by decoding the ID Token (see [Get the User Profile](/docs/get-started/architecture-scenarios/mobile-api/part-3#get-the-user-profile))
  * UI Elements can be displayed conditionally based on the scope that was granted to the user (see [Display UI Elements Conditionally Based on Scope](/docs/get-started/architecture-scenarios/mobile-api/part-3#display-ui-elements-conditionally-based-on-scope))
  * The mobile app provides the Access Token in the HTTP Authorization header when making calls to the API (see [Call the API](/docs/get-started/architecture-scenarios/mobile-api/part-3#call-the-api))
  * The mobile app user's Access Token can be renewed to ensure the user does not have to log in again during a session (see [Renew the Token](/docs/get-started/architecture-scenarios/mobile-api/part-3#renew-the-token))
</Info>

## The Premise

ExampleCo is a consulting startup company. Currently they have approximately 100 employees and they also outsource several activities to external contractors. All employees and external contractors are required to fill in their timesheets every week.

The company has built a timesheets application, a scenario we covered in [Single Sign-On for Regular Web Apps](/docs/get-started/architecture-scenarios/sso-for-regular-web-apps). The internal employees use this web app to fill in their timesheets, but the company wants a mobile application for employees and contractors to use while not on the premises. The app will be used to log timesheet entries and send the data to the centralized timesheet database using the API. The app will also allow managers to approve timesheet entries.

### Goals & Requirements

ExampleCo wants to build a flexible solution. There are potential multiple employees and contractors who should be able to log timesheet entries, as well as batch processes which may upload timesheet entries from other, external systems.

Hence the company has decided to develop a single Timesheets API which will be used to log time not only by this mobile app, but by all other apps as well. They want to put in place a security architecture that is flexible enough to accommodate this. ExampleCo wants to ensure that a large part of the code and business logic for the application can be shared across the different applications.

It is required that only authorized users and applications are allowed access to the Timesheets API.

## Learn more

* [Solution Overview (Mobile Apps + API)](/docs/get-started/architecture-scenarios/mobile-api/part-1)
* [Auth0 Configuration (Mobile Apps + API)](/docs/get-started/architecture-scenarios/mobile-api/part-2)
* [API and Mobile Configuration (Mobile Apps + API)](/docs/get-started/architecture-scenarios/mobile-api/part-3)
* [Node.js API Implementation (Mobile Apps + API)](/docs/get-started/architecture-scenarios/mobile-api/api-implementation-nodejs)
* [Android Mobile Application Implementation (Mobile Apps + API)](/docs/get-started/architecture-scenarios/mobile-api/mobile-implementation-android)
* [Conclusion (Mobile Apps + API)](/docs/get-started/architecture-scenarios/mobile-api/part-4)


# Node.js API Implementation (Mobile Apps + API)
Source: https://auth0.com/docs/get-started/architecture-scenarios/mobile-api/api-implementation-nodejs

The Node.js implementation of the API for the Mobile + API architecture scenario

This document is part of the Mobile + API Architecture Scenario and it explains how to implement the API in Node.js. The full source code for the Node.js API implementation can be found in [this GitHub repository](https://github.com/auth0-samples/auth0-pnp-exampleco-timesheets/tree/master/timesheets-api/node).

Please refer to the scenario for information on the implemented solution.

<AccordionGroup>
  <Accordion title="1 Define the API endpoints">
    This implementation uses the [Express web application framework](http://expressjs.com/) to build a Node.js API.

    ##### Create a package.json file

    Create a folder for your API, navigate into it, and run `npm init`. This sets up your `package.json` file.

    Leave the default settings or change them as you see fit.

    Our sample's `package.json` looks like the following:

    ```json lines theme={null}
    {
      "name": "timesheets-api",
      "version": "1.0.0",
      "description": "API used to add timesheet entries for employees and contractors",
      "main": "index.js",
      "scripts": {
        "start": "node index.js",
        "test": "echo \"Error: no test specified\" && exit 1"
      },
      "dependencies": {
        "body-parser": "^1.20.0",
        "cors": "^2.8.5",
        "express": "^4.18.0",
        "express-oauth2-jwt-bearer": "^1.6.0"
      },
      "author": "Auth0",
      "license": "MIT"
    }
    ```

    ##### Install the dependencies

    Next, set the dependencies with the following modules:

    * **express**: This module adds the [Express web application framework](https://expressjs.com/).
    * **cors**: This module adds support for enabling [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), which is required since the API is called from a Single-Page Application that runs on a different domain inside a web browser.
    * **jwks-rsa**: This library retrieves RSA signing keys from a JWKS (JSON Web Key Set) endpoint. Using `expressJwtSecret`, we can generate a secret provider that provides the right signing key to `express-jwt` based on the `kid` in the JWT header. To learn more, refer to the [node-jwks-rsa GitHub repository](https://github.com/auth0/node-jwks-rsa).
    * **express-jwt**: This module authenticates HTTP requests using JWT tokens in your Node.js applications. It provides several functions that make working with JWTs easier. For more information, refer to the [express-jwt GitHub repository](https://github.com/auth0/express-jwt).
    * **body-parser**: This is a Node.js body parsing middleware. It extracts the entire body portion of an incoming request stream and exposes it on `req.body` as something easier with which to interface.

    To install these dependencies run the following:

    ```bash wrap lines theme={null}
    npm install express cors express-jwt jwks-rsa body-parser express-jwt-authz --save
    ```

    ##### Implement the endpoints

    Navigate to your API directory and create a `server.js` file. Your code needs to:

    * Get the dependencies.
    * Implement the endpoint(s).
    * Launch the API server.

    This is our sample implementation:

    ```javascript lines theme={null}
    const express = require('express');
    const app = express();
    const { expressjwt: jwt } = require('express-jwt');
    const jwksRsa = require('jwks-rsa');
    const cors = require('cors');
    const bodyParser = require('body-parser');

    // Enable CORS
    app.use(cors());

    // Enable the use of request body parsing middleware
    app.use(bodyParser.json());
    app.use(bodyParser.urlencoded({
      extended: true
    }));

    // Create timesheets API endpoint
    app.post('/timesheets', function(req, res){
      res.status(201).send({message: "This is the POST /timesheets endpoint"});
    })

    // Launch the API Server at localhost:8080
    app.listen(8080);
    ```

    Launch your API server using `node server` and make an HTTP POST request to `localhost:8080/timesheets`. You should see a JSON response with the message `This is the POST /timesheets endpoint`.

    So now we have our endpoint but anyone can call it. Continue to the next step to see how we can fix this.
  </Accordion>

  <Accordion title="2 Secure the API endpoints">
    In order to validate our token, use the `jwt` function, provided by the [express-jwt middleware](https://github.com/auth0/express-jwt#usage), and the `jwks-rsa` to retrieve our secret. The libraries do the following:

    1. `express-jwt` decodes the token and pass the request, the header, and the payload to `jwksRsa.expressJwtSecret`.
    2. `jwks-rsa` downloads all signing keys from the JWKS endpoint and see if a one of the signing keys matches the `kid` in the header of the JWT. If none of the signing keys match the incoming `kid`, an error will be thrown. If we have a match, pass the right signing key to `express-jwt`.
    3. `express-jwt` continues its own logic to validate the signature of the token, the expiration, `audience` and the `issuer`.

    The steps we will follow in our code are:

    * Create the middleware function to validate the access token.
    * Enable the use of the middleware in our routes.

    You can also write some code to actually save the timesheet to a database. This is our sample implementation (some code is omitted for brevity):

    <AuthCodeBlock />

    If we launch our server now and do an HTTP POST to `localhost:8080/timesheets` we should get the error message `Missing or invalid token` (which is accurate since we didn’t send an access token in our request).

    In order to test the working scenario as well we need to:

    * Get an access token. For details on how to do so refer to: [Get an Access Token](/docs/secure/tokens/access-tokens/get-access-tokens).
    * Invoke the API while adding an `Authorization` header to our request with the value `Bearer ACCESS_TOKEN` (where `ACCESS_TOKEN` is the value of the token we retrieved in the first step).
  </Accordion>

  <Accordion title="3 Check the app permissions">
    In this step, we add the ability to check if the application has permissions (or scopes) and use our endpoint in order to create a timesheet. In particular, we want to ensure that the token has the correct scope, which is `batch:upload`.

    In order to do this, we make use of the `express-jwt-authz` Node.js package, so add that to your project:

    ```bash lines theme={null}
    npm install express-jwt-authz --save
    ```

    Now add a call to `jwtAuthz(...)` to your middleware to ensure that the JWT contain a particular scope in order to execute a particular endpoint.

    We add an additional dependency. The **express-jwt-authz** library, which is used in conjunction with express-jwt, validates the [JWT](/docs/secure/tokens/json-web-tokens) and ensures it bears the correct permissions to call the desired endpoint. For more information, refer to the [express-jwt-authz GitHub repository](https://github.com/auth0/express-jwt-authz).

    This is our sample implementation (some code is omitted for brevity):

    ```javascript lines theme={null}
    // set dependencies - some code omitted
    const jwtAuthz = require('express-jwt-authz');

    // Enable CORS - code omitted

    // Create middleware for checking the JWT - code omitted

    // Enable the use of request body parsing middleware - code omitted

    // create timesheets API endpoint
    app.post('/timesheets', checkJwt, jwtAuthz(['create:timesheets'], { customUserKey: 'auth' }), function(req, res){
      var timesheet = req.body;

      // Save the timesheet to the database...

      //send the response
      res.status(201).send(timesheet);
    })

    // launch the API Server at localhost:8080 - code omitted
    ```

    If we invoke our API with a token that does not include this scope, then we should get the error message Forbidden with the HTTP status code `403`. You can test this by removing this scope from your API.
  </Accordion>

  <Accordion title="4 Determine User Identity">
    The `express-jwt` middleware that is used to validate the JWT also sets `req.user` with the information contained in the JWT. If you want to use the `sub` claim to identify the user uniquely, you can use `req.user.sub`. For the timesheets application, we want to use the email address of the user as a unique identifier.

    ##### Create an Action

    First, [create a new Action](/docs/customize/actions/write-your-first-action) that will add the email address of the user to the access token.

    1. Navigate to [Auth0 Dashboard > Actions > Library](https://manage.auth0.com/#/actions/library), and select **Build Custom**.
    2. Enter a descriptive **Name** for your Action (for example, `Add email to access token`), select the **Login / Post Login** trigger, and select **Create**.
    3. Locate the Actions Code Editor, copy the following JavaScript code into it, and select **Save Draft** to save your changes:

       ```text lines theme={null}
       exports.onExecutePostLogin = async (event, api) => {
         const namespace = 'https://my-app.example.com';
         api.accessToken.setCustomClaim(`${namespace}/email`, event.user.email);
       }
       ```

       <Callout icon="file-lines">
         The `namespace` is used to ensure the claim has a unique name that does not clash with standard OIDC claims or internal services. To learn more about restrictions and guidelines with namespaced and non-namespaced claims, read [Create Custom Claims](/docs/secure/tokens/json-web-tokens/create-custom-claims).
       </Callout>
    4. From the Actions Code Editor sidebar, select Test (play icon), then select **Run** to [test your code](/docs/customize/actions/test-actions).
    5. When you’re ready for the Action to go live, select **Deploy**.

    ##### Add your Action to the Post-Login Trigger

    Next, add the Action you created to the [Post-Login Trigger](https://manage.auth0.com/#/actions/triggers/post-login/). To learn how to attach Actions to Triggers, read [Write Your First Action](/docs/customize/actions/write-your-first-action).

    ##### Retrieve the unique identifier

    Finally, from inside your API, retrieve the value of the claim from `req.auth`. Use that value as the unique user identifier to associate with timesheet entries.

    ```js lines theme={null}
    app.get('/timesheets', checkJwt, jwtAuthz(['read:timesheets'], { customUserKey: 'auth' }), function(req, res) {
      var timesheet = req.body;

      // Associate the timesheet entry with the current user
      var userId = req.auth['https://api.exampleco.com/email'];
      timesheet.user_id = userId;

      // Save the timesheet to the database...

      //send the response
      res.status(201).send(timesheet);
    });
    ```
  </Accordion>
</AccordionGroup>


# Android Mobile Application Implementation (Mobile Apps + API)
Source: https://auth0.com/docs/get-started/architecture-scenarios/mobile-api/mobile-implementation-android

The Android implementation of the API for the Mobile + API architecture scenario

This document is part of the Mobile + API Architecture Scenario and it explains how to implement the mobile application in Android. Please refer to the scenario for information on the implemented solution.

## Step 1. Set Up the Application

### Sample Project

Download a sample project specific to this tutorial to get started.

[Download](/docs/package/v2/timesheets-mobile_android.zip)
[Fork on Github](https://github.com/auth0-samples/auth0-pnp-exampleco-timesheets/tree/master/timesheets-mobile/android)

System Requirements

* Android Studio 2.3
* Android SDK 25
* Emulator - Nexus 5X - Android 6.0

Show requirements

### Set the Dependencies

For this implementation, we will use the following dependencies within the app’s `build.gradle` file:

* [Auth0.Android](https://github.com/auth0/Auth0.Android): this package enables integration with Auth0 to authenticate users.
* [OkHttp](http://square.github.io/okhttp/): this package provides an HTTP application to make requests to the Node.JS API.
* [JWTDecode.Android](https://github.com/auth0/JWTDecode.Android): this package will assist with decoding <Tooltip href="/docs/glossary?term=JWTs">JWTs</Tooltip>.
* AppCompat: this package lets us use the toolbar widget for navigation in our activities.

```groovy lines theme={null}
dependencies {
    compile 'com.squareup.okhttp:okhttp:2.7.5'
    compile 'com.auth0.android:auth0:1.10.0'
    compile 'com.auth0.android:jwtdecode:1.1.1'
    compile 'com.android.support:appcompat-v7:25.3.1'
    testCompile 'junit:junit:4.12'
}
```

### Update the Manifest

Open the application's `AndroidManifest.xml` and add the internet permission:

```xml lines theme={null}
<uses-permission android:name="android.permission.INTERNET" />
```

We’ll also update the application details to utilize the Toolbar widget:

```xml lines theme={null}
<application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.AppCompat.Light.NoActionBar">
    </application>
```

### Set Configuration Values

Set your Auth0 <Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>, Auth0 Domain, and API’s url in the `strings.xml` resource located in `/res/values/strings.xml`:

```xml lines theme={null}
<resources>
    <string name="app_name">ExampleCo Timesheets</string>
    <string name="login">Log in</string>
    <string name="auth0_client_id">...</string>
    <string name="auth0_domain">...</string>
    <string name="api_url">http://10.0.2.2:8080/timesheets</string>
</resources>
```

For this implementation, create directories for activities, models, and utils in the application package.

* `activities/`: this package will contain the `LoginActivity.java`, `TimeSheetActivity.java`, `FormActivity.java`, and `UserActivity.java`.
* `models/`: this package will contain the `TimeSheet.java` and `User.java` data models.
* `utils/`: this package will contain the `UserProfileManager.java`, `TimeSheetAdapter.java`, and `ImageTask.java`

## Step 2. Authorize the User

### Update the Manifest

Open the app's `AndroidManifest.xml` and add the `LoginActivity`:

```xml lines theme={null}
<activity
            android:name="com.auth0.samples.activities.LoginActivity"
            android:launchMode="singleTask">

            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>

            <intent-filter>
                <action android:name="android.intent.action.VIEW" />

                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />

                <data
                    android:host="@string/auth0_domain"
                    android:pathPrefix="/android/com.auth0.samples/callback"
                    android:scheme="demo" />
            </intent-filter>
</activity>
```

### Create the Login Activity

The `LoginActivity` will handle user authorization and be the initial screen users see. We'll create a `login()` method to initialize a `WebAuthProvider` and start authentication. Ensure you provide the correct scheme, <Tooltip href="/docs/glossary?term=audience">audience</Tooltip>, and scope to the `WebAuthProvider`. For this implementation we will use:

* **scheme**: `demo`
* **audience**: `https://api.exampleco.com/timesheet`s (the Node.JS API)
* **response\_type**: `code`
* **scope**: `create:timesheets read:timesheets openid profile email offline_access`. These scopes will enable us to `POST` and `GET` to the Node.JS API, as well as retrieve the user profile and a <Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip>.

```java lines theme={null}
private void login() {
        Auth0 auth0 = new Auth0(getString(R.string.auth0_client_id), getString(R.string.auth0_domain));
        auth0.setOIDCConformant(true);

        WebAuthProvider.init(auth0)
                .withScheme("demo")
                .withAudience("https://api.exampleco.com/timesheets")
                .withResponseType(ResponseType.CODE)
                .withScope("create:timesheets read:timesheets openid profile email offline_access")
                .start(
                    // ...
                );
}
```

In the `login()` method, upon successful authentication we'll redirect the user to the `TimeSheetActivity`.

```java lines expandable theme={null}
package com.auth0.samples.activities;

import android.app.Activity;
import android.app.Dialog;
import android.content.Intent;
import android.os.Bundle;
import android.support.annotation.NonNull;
import android.support.annotation.Nullable;
import android.view.View;
import android.widget.Button;
import android.widget.Toast;

import com.auth0.android.Auth0;
import com.auth0.android.authentication.AuthenticationException;
import com.auth0.android.jwt.JWT;
import com.auth0.android.provider.AuthCallback;
import com.auth0.android.provider.ResponseType;
import com.auth0.android.provider.WebAuthProvider;
import com.auth0.android.result.Credentials;
import com.auth0.samples.R;
import com.auth0.samples.models.User;
import com.auth0.samples.utils.CredentialsManager;
import com.auth0.samples.utils.UserProfileManager;

public class LoginActivity extends Activity {

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.login_activity);
        Button loginWithTokenButton = (Button) findViewById(R.id.loginButton);
        loginWithTokenButton.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View v) {
                login();
            }
        });
    }

    @Override
    protected void onNewIntent(Intent intent) {
        if (WebAuthProvider.resume(intent)) {
            return;
        }
        super.onNewIntent(intent);
    }

    private void login() {
        Auth0 auth0 = new Auth0(getString(R.string.auth0_client_id), getString(R.string.auth0_domain));
        auth0.setOIDCConformant(true);

        WebAuthProvider.init(auth0)
                .withScheme("demo")
                .withAudience("https://api.exampleco.com/timesheets")
                .withResponseType(ResponseType.CODE)
                .withScope("create:timesheets read:timesheets openid profile email")
                .start(LoginActivity.this, new AuthCallback() {
                    @Override
                    public void onFailure(@NonNull final Dialog dialog) {
                        runOnUiThread(new Runnable() {
                            @Override
                            public void run() {
                                dialog.show();
                            }
                        });
                    }

                    @Override
                    public void onFailure(final AuthenticationException exception) {
                        runOnUiThread(new Runnable() {
                            @Override
                            public void run() {
                                Toast.makeText(LoginActivity.this, "Error: " + exception.getMessage(), Toast.LENGTH_SHORT).show();
                            }
                        });
                    }

                    @Override
                    public void onSuccess(@NonNull final Credentials credentials) {
                        runOnUiThread(new Runnable() {
                            @Override
                            public void run() {
                                Toast.makeText(LoginActivity.this, "Log In - Success", Toast.LENGTH_SHORT).show();
                            }
                        });
                        startActivity(new Intent(LoginActivity.this, TimeSheetActivity.class));
                    }
                });
    }
}
```

### Store the Credentials

To store the credentials received after login, we’ll use the `CredentialsManager` from the Auth0.Android library and [SharedPreferences](https://developer.android.com/reference/android/content/SharedPreferences.html) for storage.

Before initializing the `WebAuthProvider` in the `login()` method, we can create the `CredentialsManager`. Passing an `AuthenticationAPIClient` to the `CredentialsManager` enables it to refresh the <Tooltip href="/docs/glossary?term=Access+Tokens">Access Tokens</Tooltip> if they are expired.

```java lines theme={null}
private void login() {
        Auth0 auth0 = new Auth0(getString(R.string.auth0_client_id), getString(R.string.auth0_domain));
        auth0.setOIDCConformant(true);

        AuthenticationAPIClient authAPIClient = new AuthenticationAPIClient(auth0);
        SharedPreferencesStorage sharedPrefStorage = new SharedPreferencesStorage(this);
        final CredentialsManager credentialsManager = new CredentialsManager(authAPIClient, sharedPrefStorage);

        WebAuthProvider.init(auth0)
        // ...
    }
```

Now update the `login()` method so that credentials are stored via the `CredentialsManager` after a successful authentication.

```java lines theme={null}
// ...
@Override
public void onSuccess(@NonNull final Credentials credentials) {
    runOnUiThread(new Runnable() {
        @Override
        public void run() {
            Toast.makeText(LoginActivity.this, "Log In - Success", Toast.LENGTH_SHORT).show();
        }
    });

    credentialsManager.saveCredentials(credentials);
    startActivity(new Intent(LoginActivity.this, TimeSheetActivity.class));
// ...
}
```

## Step 3. Get the User Profile

### Create the User Model

Create a simple User model that will be utilized by the `UserProfileManager` and `UserActivity`.

```java lines theme={null}
package com.auth0.samples.models;

public class User {
    private String email;
    private String name;
    private String pictureURL;

    public User(String email, String name, String pictureURL) {
        this.email = email;
        this.name = name;
        this.pictureURL = pictureURL;
    }

    public String getEmail() {
        return email;
    }

    public String getName() {
        return name;
    }

    public String getPictureURL() {
        return pictureURL;
    }
}
```

### Store the User Profile

To handle storing user profile information we'll create a manager class `UserProfileManager`. The `UserProfileManager` will use [SharedPreferences](https://developer.android.com/reference/android/content/SharedPreferences.html) to store data.

```java lines expandable theme={null}
package com.auth0.samples.utils;

import android.content.Context;
import android.content.SharedPreferences;

import com.auth0.android.result.UserProfile;
import com.auth0.samples.models.User;

public class UserProfileManager {

    private static final String PREFERENCES_NAME = "auth0_user_profile";
    private static final String EMAIL = "email";
    private static final String NAME = "name";
    private static final String PICTURE_URL = "picture_url";

    public static void saveUserInfo(Context context, User userInfo) {
        SharedPreferences sp = context.getSharedPreferences(
                PREFERENCES_NAME, Context.MODE_PRIVATE);

        sp.edit()
                .putString(EMAIL, userInfo.getEmail())
                .putString(NAME, userInfo.getName())
                .putString(PICTURE_URL, userInfo.getPictureURL())
                .apply();
    }

    public static User getUserInfo(Context context) {
        SharedPreferences sp = context.getSharedPreferences(
                PREFERENCES_NAME, Context.MODE_PRIVATE);

        return new User(
                sp.getString(EMAIL, null),
                sp.getString(NAME, null),
                sp.getString(PICTURE_URL, null)
        );
    }

    public static void deleteUserInfo(Context context) {
        SharedPreferences sp = context.getSharedPreferences(
                PREFERENCES_NAME, Context.MODE_PRIVATE);

        sp.edit()
                .putString(EMAIL, null)
                .putString(NAME, null)
                .putString(PICTURE_URL, null)
                .apply();
    }
}
```

Next, update the `login()` method in the `LoginActivity` to retrieve the <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip> and get the user profile from the token with the JWTDecode.Android library. Then store the user profile with the `UserProfileManager`.

```java lines theme={null}
// ...
@Override
public void onSuccess(@NonNull final Credentials credentials) {
    runOnUiThread(new Runnable() {
        @Override
        public void run() {
            Toast.makeText(LoginActivity.this, "Log In - Success", Toast.LENGTH_SHORT).show();
        }
    });

    credentialsManager.saveCredentials(credentials);
    JWT jwt = new JWT(credentials.getIdToken());
    User user = new User(
            jwt.getClaim("email").asString(),
            jwt.getClaim("name").asString(),
            jwt.getClaim("picture").asString()
    );
    UserProfileManager.saveUserInfo(LoginActivity.this, user);

    startActivity(new Intent(LoginActivity.this, TimeSheetActivity.class));
}
// ...
```

## Step 4. Display UI Elements Conditionally Based on Scope

To determine whether a user has permissions to perform certain actions, we can look at the `scope` that was granted to the user during the authentication process. The `scope` will contain a string with all the scopes granted to a user, so to determine whether a particular scope was granted, we simply need to look whether the string of scopes contain the substring for that particular scope.

### Store the Scope

First, we can update the `User` class to store the granted scopes, and then provide a helper method, `hasScope()` which can be used to determine whether the granted scopes contain a particular scope:

```java lines expandable theme={null}
public class User {
    private String email;
    private String name;
    private String pictureURL;
    private String grantedScope;

    public User(String email, String name, String pictureURL, String grantedScope) {
        this.email = email;
        this.name = name;
        this.pictureURL = pictureURL;
        this.grantedScope = grantedScope;
    }

    public String getEmail() {
        return email;
    }

    public String getGrantedScope() { 
        return grantedScope; 
    }

    public String getName() {
        return name;
    }

    public String getPictureURL() {
        return pictureURL;
    }

    public Boolean hasScope(String scope) {
        return grantedScope.contains(scope);
    }
}
```

Also remember to update the `UserProfileManager` to store the extra field:

```java lines expandable theme={null}
public class UserProfileManager {

    private static final String PREFERENCES_NAME = "auth0_user_profile";
    private static final String EMAIL = "email";
    private static final String NAME = "name";
    private static final String PICTURE_URL = "picture_url";
    private static final String SCOPE = "scope";

    public static void saveUserInfo(Context context, User userInfo) {
        SharedPreferences sp = context.getSharedPreferences(
                PREFERENCES_NAME, Context.MODE_PRIVATE);

        sp.edit()
                .putString(EMAIL, userInfo.getEmail())
                .putString(NAME, userInfo.getName())
                .putString(PICTURE_URL, userInfo.getPictureURL())
                .putString(SCOPE, userInfo.getGrantedScope())
                .apply();
    }

    public static User getUserInfo(Context context) {
        SharedPreferences sp = context.getSharedPreferences(
                PREFERENCES_NAME, Context.MODE_PRIVATE);

        return new User(
                sp.getString(EMAIL, null),
                sp.getString(NAME, null),
                sp.getString(PICTURE_URL, null),
                sp.getString(SCOPE, null)
        );
    }

    public static void deleteUserInfo(Context context) {
        SharedPreferences sp = context.getSharedPreferences(
                PREFERENCES_NAME, Context.MODE_PRIVATE);

        sp.edit()
                .putString(EMAIL, null)
                .putString(NAME, null)
                .putString(PICTURE_URL, null)
                .putString(SCOPE, null)
                .apply();
    }
}
```

Next, update the `LoginActivity` to pass along the `scope` so it can be stored in the `User` object:

```java lines theme={null}
// ...
@Override
public void onSuccess(@NonNull final Credentials credentials) {
    runOnUiThread(new Runnable() {
        @Override
        public void run() {
            Toast.makeText(LoginActivity.this, "Log In - Success", Toast.LENGTH_SHORT).show();
        }
    });

    credentialsManager.saveCredentials(credentials);
    JWT jwt = new JWT(credentials.getIdToken());
    String scopes = credentials.getScope();
    User user = new User(
            jwt.getClaim("email").asString(),
            jwt.getClaim("name").asString(),
            jwt.getClaim("picture").asString(),
            credentials.getScope()
    );
    UserProfileManager.saveUserInfo(LoginActivity.this, user);

    startActivity(new Intent(LoginActivity.this, TimeSheetActivity.class));
}
// ...
```

### Display Approval Menu Based on Scope

Now, we can display certain UI elements based on whether the user was granted a particular scope. As an example, we have an approval menu item which should only be visible to users who have been granted the `approve:timesheets` scope.

Below you can see the code from the `BaseActivity` class which checks whether a user has the `approve:timesheets` scope, and based on that will set the visibility of the menu item which displays the approval activity:

```java lines theme={null}
// ...
@Override
public boolean onCreateOptionsMenu(Menu menu) {
    Boolean canApprove = UserProfileManager.getUserInfo(this).hasScope("approve:timesheets");
    MenuInflater inflater = getMenuInflater();
    inflater.inflate(R.menu.actions, menu);
    MenuItem item = menu.findItem(R.id.action_approve);
    item.setVisible(canApprove);
    return super.onCreateOptionsMenu(menu);
}
// ...
```

## Step 5. Call the API

### Update the Manifest

Open the app's `AndroidManifest.xml` and add the `TimeSheetActivity`:

```xml wrap lines theme={null}
<activity android:name="com.auth0.samples.activities.TimeSheetActivity" />
```

### Create the Timesheets Activity Layouts

Next create `timesheet_activity.xml`, the layout for the `TimeSheetsActivity`:

```xml lines theme={null}
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:orientation="vertical"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <android.support.v7.widget.Toolbar
        android:id="@+id/navToolbar"
        android:layout_width="match_parent"
        android:layout_height="?attr/actionBarSize"
        android:background="?attr/colorPrimary"
        android:elevation="4dp"
        android:theme="@style/ThemeOverlay.AppCompat.ActionBar"
        app:popupTheme="@style/ThemeOverlay.AppCompat.Light"/>

    <ListView
        android:id="@+id/timesheetList"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
</LinearLayout>
```

The `ListView` widget will contain individual entries which are represented by the `item_entry.xml` layout:

```xml lines expandable theme={null}
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="vertical" android:layout_width="match_parent"
    android:layout_height="match_parent">

    <TextView
        android:id="@+id/tvUserID"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="UserID"
        android:textStyle="bold" />
    <TextView
        android:id="@+id/tvDate"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Date" />

    <TextView
        android:id="@+id/tvProjectName"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Project"
        android:textStyle="italic" />
    <TextView
        android:id="@+id/tvHours"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Hours" />
</LinearLayout>
```

And for the Toolbar navigation on the `TimeSheetActivity`, we’ll create the `timesheet_action_menu.xml` menu resource (`/res/menu/`):

```xml lines theme={null}
<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">

    <item
        android:id="@+id/action_profile"
        android:title="Profile"
        app:showAsAction="always" />
    <item
        android:id="@+id/action_new"
        android:title="New Timesheet"
        app:showAsAction="always" />
</menu>
```

### Create the Timesheet Model

Create a model for working with timesheet data in our views:

```java lines expandable theme={null}
package com.auth0.samples.models;

import java.util.Date;

/**
 * Created by ej on 7/9/17.
 */

public class TimeSheet {
    private String userID;
    private String projectName;
    private String date;
    private double hours;
    private int ID;

    public TimeSheet(String gUserID, String gProjectName, String gDate, double gHours, int gID) {
        this.userID = gUserID;
        this.projectName = gProjectName;
        this.date = gDate;
        this.hours = gHours;
        this.ID = gID;
    }

    public String getUserID() {
        return userID;
    }

    public String getProjectName() {
        return projectName;
    }

    public String getDateString() {
        return date;
    }

    public double getHours() {
        return hours;
    }

    public int getID() {
        return ID;
    }
}
```

### Create the Timesheet Adapter

The `TimeSheetAdapter` is a utility class which will take an array of timesheet entries and apply them to the `ListView` on the `TimeSheetActivity`.

```java lines expandable theme={null}
package com.auth0.samples.utils;

import android.content.Context;
import android.view.LayoutInflater;
import android.view.View;
import android.view.ViewGroup;
import android.widget.ArrayAdapter;
import android.widget.TextView;
import com.auth0.samples.R;
import com.auth0.samples.models.TimeSheet;
import java.util.ArrayList;

public class TimeSheetAdapter extends ArrayAdapter<TimeSheet> {

    public TimeSheetAdapter(Context context, ArrayList<TimeSheet> timesheets) {
        super(context, 0, timesheets);
    }

    @Override
    public View getView(int position, View convertView, ViewGroup parent) {

        TimeSheet timesheet = getItem(position);

        if (convertView == null) {
            convertView = LayoutInflater.from(getContext()).inflate(R.layout.item_entry, parent, false);
        }

        TextView tvUserID = (TextView) convertView.findViewById(R.id.tvUserID);
        TextView tvDate = (TextView) convertView.findViewById(R.id.tvDate);
        TextView tvProjectName = (TextView) convertView.findViewById(R.id.tvProjectName);
        TextView tvHours = (TextView) convertView.findViewById(R.id.tvHours);

        tvUserID.setText(timesheet.getUserID());
        tvDate.setText(timesheet.getDateString());
        tvProjectName.setText(timesheet.getProjectName());
        tvHours.setText(Double.toString(timesheet.getHours()));

        return convertView;
    }
}
```

### Create the Timesheet Activity

The `TimeSheetActivity` displays the timesheet entries for the logged in user which are stored on the server.

* The `@string/api_url` is set to `http://10.0.2.2:8080/timesheets` so the Android Emulator can connect to the Node.JS API running on `http://localhost:8080`.
* The `callAPI()` method retrieves timesheets from the Node.JS API.
* The `processResults()` method takes the JSON response from `callAPI()` and converts it `TimeSheet` objects.
* The `onCreateOptionsMenu(`) and `onOptionsItemSelected(`) methods handle the Toolbar widget navigation functionality.

```java lines expandable theme={null}
package com.auth0.samples.activities;

import android.content.Intent;
import android.os.Bundle;
import android.support.annotation.Nullable;
import android.support.v7.app.AppCompatActivity;
import android.support.v7.widget.Toolbar;
import android.util.Log;
import android.view.Menu;
import android.view.MenuInflater;
import android.view.MenuItem;
import android.widget.ListView;
import android.widget.Toast;

import com.auth0.android.Auth0;
import com.auth0.android.authentication.AuthenticationAPIClient;
import com.auth0.android.authentication.storage.CredentialsManager;
import com.auth0.android.authentication.storage.CredentialsManagerException;
import com.auth0.android.authentication.storage.SharedPreferencesStorage;
import com.auth0.android.callback.BaseCallback;
import com.auth0.android.result.Credentials;
import com.auth0.samples.R;
import com.auth0.samples.utils.TimeSheetAdapter;
import com.auth0.samples.models.TimeSheet;
import com.squareup.okhttp.Callback;
import com.squareup.okhttp.OkHttpClient;
import com.squareup.okhttp.Request;
import com.squareup.okhttp.Response;

import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;

import java.io.IOException;
import java.util.ArrayList;

public class TimeSheetActivity extends AppCompatActivity {

    private ArrayList<TimeSheet> timesheets = new ArrayList<>();

    private String accessToken;

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.timesheet_activity);
        Toolbar navToolbar = (Toolbar) findViewById(R.id.navToolbar);
        setSupportActionBar(navToolbar);

        Auth0 auth0 = new Auth0(getString(R.string.auth0_client_id), getString(R.string.auth0_domain));
        auth0.setOIDCConformant(true);

        AuthenticationAPIClient authAPIClient = new AuthenticationAPIClient(auth0);
        SharedPreferencesStorage sharedPrefStorage = new SharedPreferencesStorage(this);

        CredentialsManager credentialsManager = new CredentialsManager(authAPIClient, sharedPrefStorage);
        credentialsManager.getCredentials(new BaseCallback<Credentials, CredentialsManagerException>() {
            @Override
            public void onSuccess(Credentials payload) {
                accessToken = payload.getAccessToken();
                callAPI();
            }

            @Override
            public void onFailure(CredentialsManagerException error) {
                Toast.makeText(TimeSheetActivity.this, "Error: " + error.getMessage(), Toast.LENGTH_SHORT).show();
            }
        });
    }

    private void callAPI() {
        final Request.Builder reqBuilder = new Request.Builder()
                .get()
                .url(getString(R.string.api_url))
                .addHeader("Authorization", "Bearer " + accessToken);

        OkHttpClient client = new OkHttpClient();
        Request request = reqBuilder.build();
        client.newCall(request).enqueue(new Callback() {
            @Override
            public void onFailure(Request request, IOException e) {
                Log.e("API", "Error: ", e);
                runOnUiThread(new Runnable() {
                    @Override
                    public void run() {
                        Toast.makeText(TimeSheetActivity.this, "An error occurred", Toast.LENGTH_SHORT).show();
                    }
                });
            }

            @Override
            public void onResponse(final Response response) throws IOException {
                timesheets = processResults(response);
                final TimeSheetAdapter adapter = new TimeSheetAdapter(TimeSheetActivity.this, timesheets);
                runOnUiThread(new Runnable() {
                    @Override
                    public void run() {
                        if (response.isSuccessful()) {
                            ListView listView = (ListView) findViewById(R.id.timesheetList);
                            listView.setAdapter(adapter);
                            adapter.addAll(timesheets);
                        } else {
                            Toast.makeText(TimeSheetActivity.this, "API call failed.", Toast.LENGTH_SHORT).show();
                        }
                    }
                });
            }
        });
    }

    private ArrayList<TimeSheet> processResults (Response response) {
        ArrayList<TimeSheet> timesheets = new ArrayList<>();
        try {
            String jsonData = response.body().string();
            if (response.isSuccessful()) {
                JSONArray timesheetJSONArray = new JSONArray(jsonData);
                for (int i = 0; i < timesheetJSONArray.length(); i++) {
                    JSONObject timesheetJSON = timesheetJSONArray.getJSONObject(i);
                    String userID = timesheetJSON.getString("user_id");
                    String projectName = timesheetJSON.getString("project");
                    String dateStr = timesheetJSON.getString("date");
                    Double hours = timesheetJSON.getDouble("hours");
                    int id = timesheetJSON.getInt("id");

                    TimeSheet timesheet = new TimeSheet(userID, projectName, dateStr, hours, id);
                    timesheets.add(timesheet);
                }
            }
        } catch (IOException e) {
            e.printStackTrace();
        } catch (JSONException e) {
            e.printStackTrace();
        }
        return timesheets;
    }

    @Override
    public boolean onCreateOptionsMenu(Menu menu) {
        MenuInflater inflater = getMenuInflater();
        inflater.inflate(R.menu.timesheet_action_menu, menu);
        return super.onCreateOptionsMenu(menu);
    }

    @Override
    public boolean onOptionsItemSelected(MenuItem item) {
        switch (item.getItemId()) {
            case R.id.action_new:
                startActivity(new Intent(TimeSheetActivity.this, FormActivity.class));
                break;
            case R.id.action_profile:
                startActivity(new Intent(TimeSheetActivity.this, UserActivity.class));
                break;
            default:
                return super.onOptionsItemSelected(item);
        }
        return true;
    }
}
```

## Step 6. View the User Profile

To display the logged in user’s profile we’ll create the `UserActivity`, a corresponding `user_activity.xml` layout, and the `user_action_menu.xml` for the Toolbar navigation. The view will display the user’s name, email, and profile picture.

### Update the Manifest

Open the app's `AndroidManifest.xml` and add the `UserActivity`:

```xml wrap lines theme={null}
<activity android:name="com.auth0.samples.activities.UserActivity" />
```

#### Create the User Activity Layouts

Next create `user_activity.xml`, the layout for the `UserActivity`, with an `ImageView` for the profile picture and `TextViews` for the user's name and email.

```xml lines expandable theme={null}
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:orientation="vertical"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <android.support.v7.widget.Toolbar
        android:id="@+id/navToolbar"
        android:layout_width="match_parent"
        android:layout_height="?attr/actionBarSize"
        android:background="?attr/colorPrimary"
        android:elevation="4dp"
        android:theme="@style/ThemeOverlay.AppCompat.ActionBar"
        app:popupTheme="@style/ThemeOverlay.AppCompat.Light"/>

    <ImageView
        android:id="@+id/ivPicture"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        app:srcCompat="@android:color/darker_gray" />

    <TextView
        android:id="@+id/tvName"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="Name"
        android:textSize="24sp" />

    <TextView
        android:id="@+id/tvEmail"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="Email"
        android:textSize="24sp" />
</LinearLayout>
```

And create the `user_actions_menu.xml` for the `UserActivity` Toolbar:

```xml lines theme={null}
<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">

    <item
        android:id="@+id/action_view"
        android:title="View Timesheets"
        app:showAsAction="always" />
    <item
        android:id="@+id/action_new"
        android:title="New Timesheet"
        app:showAsAction="always" />
</menu>
```

### Load the Profile Picture from URL

In order to load the user profile picture from the URL, create a task which extends `AsyncTask` and executes in the background.

```java lines expandable theme={null}
package com.auth0.samples.utils;

import android.graphics.Bitmap;
import android.graphics.BitmapFactory;
import android.os.AsyncTask;
import android.util.Log;
import android.widget.ImageView;

import java.io.InputStream;
import java.net.URL;

public class ImageTask extends AsyncTask<String, Void, Bitmap> {

    private ImageView bmImage;

    public ImageTask(ImageView bmImage) {
        this.bmImage = bmImage;
    }

    protected Bitmap doInBackground(String... urls) {
        String urldisplay = urls[0];
        Bitmap mIcon11 = null;

        try {
            InputStream in = new URL(urldisplay).openStream();
            mIcon11 = BitmapFactory.decodeStream(in);
        } catch (Exception e) {
            Log.e("Error", e.getMessage());
            e.printStackTrace();
        }
        return mIcon11;
    }

    protected void onPostExecute(Bitmap result) {
        bmImage.setImageBitmap(result);
    }
}
```

### Create the User Activity

In the `onCreate()` method we'll retrieve the user information from the `UserProfileManager` and set the values in the view. As before, the `onCreateOptionsMenu()` and `onOptionsItemSelected()` methods handle the Toolbar widget navigation functionality.

```java lines expandable theme={null}
package com.auth0.samples.activities;

import android.app.Activity;
import android.content.Intent;
import android.os.Bundle;
import android.support.annotation.Nullable;
import android.support.v7.app.AppCompatActivity;
import android.support.v7.widget.Toolbar;
import android.view.Menu;
import android.view.MenuInflater;
import android.view.MenuItem;
import android.widget.ImageView;
import android.widget.TextView;

import com.auth0.samples.R;
import com.auth0.samples.utils.ImageTask;
import com.auth0.samples.utils.UserProfileManager;

public class UserActivity extends AppCompatActivity {

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.user_activity);
        Toolbar navToolbar = (Toolbar) findViewById(R.id.navToolbar);
        setSupportActionBar(navToolbar);

        TextView tvName = (TextView) findViewById(R.id.tvName);
        TextView tvEmail = (TextView) findViewById(R.id.tvEmail);

        tvName.setText(UserProfileManager.getUserInfo(this).getName());
        tvEmail.setText(UserProfileManager.getUserInfo(this).getEmail());

        new ImageTask((ImageView) findViewById(R.id.ivPicture))
                .execute(UserProfileManager.getUserInfo(this).getPictureURL());

                UserProfileManager.getUserInfo(this).getName();
    }

    @Override
    public boolean onCreateOptionsMenu(Menu menu) {
        // Inflate the menu items for use in the action bar
        MenuInflater inflater = getMenuInflater();
        inflater.inflate(R.menu.user_action_menu, menu);
        return super.onCreateOptionsMenu(menu);
    }

    @Override
    public boolean onOptionsItemSelected(MenuItem item) {
        switch (item.getItemId()) {
            case R.id.action_new:
                startActivity(new Intent(UserActivity.this, FormActivity.class));
                break;
            case R.id.action_view:
                startActivity(new Intent(UserActivity.this, TimeSheetActivity.class));
                break;
            default:
                // If we got here, the user's action was not recognized.
                // Invoke the superclass to handle it.
                return super.onOptionsItemSelected(item);

        }
        return true;
    }
}
```

## Step 7. Form for New Timesheets

Next create the `FormActivity` and layout to handle creating new timesheet entries.

### Update the Manifest

Open the app's `AndroidManifest.xml` and add the `FormActivity`:

```xml wrap lines theme={null}
<activity android:name="com.auth0.samples.activities.FormActivity" />
```

### Create the Form Activity Layouts

Create the `form_activity.xml` layout with `EditText` for the project name and hours worked inputs, and a `DatePicker` for the day worked.

```xml lines expandable theme={null}
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/mainForm"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
    android:weightSum="1">

    <android.support.v7.widget.Toolbar
        android:id="@+id/navToolbar"
        android:layout_width="match_parent"
        android:layout_height="?attr/actionBarSize"
        android:background="?attr/colorPrimary"
        android:elevation="4dp"
        android:theme="@style/ThemeOverlay.AppCompat.ActionBar"
        app:popupTheme="@style/ThemeOverlay.AppCompat.Light"/>

    <EditText
        android:id="@+id/editProjectName"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:ems="10"
        android:hint="Project Name"
        android:inputType="textPersonName" />

    <EditText
        android:id="@+id/editHours"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:ems="10"
        android:hint="Hours Worked"
        android:inputType="number|numberDecimal" />

    <DatePicker
        android:id="@+id/datePicker"
        android:layout_width="match_parent"
        android:layout_height="191dp"
        android:layout_weight="0.93" />

    <Button
        android:id="@+id/submitTimeSheetButton"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="Submit" />
</LinearLayout>
```

And create the `form_actions_menu.xml` for the `FormActivity` Toolbar:

```xml lines theme={null}
<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">

    <item
        android:id="@+id/action_profile"
        android:title="Profile"
        app:showAsAction="always" />
    <item
        android:id="@+id/action_view"
        android:title="View Timesheets"
        app:showAsAction="always" />
</menu>
```

### Create the Form Activity

* The `@string/api_url` is set to `http://10.0.2.2:8080/timesheets` so the Android Emulator can connect to the Node.JS API running on `http://localhost:8080`.
* The `onCreate()` method initializes the form and collects the input for the `postAPI()` method when the submit button is pressed.
* The `postAPI()` method will send the user input retrieved from the form to the Node.JS API in JSON format.
* The `clearForm()` method clears the input forms.
* The `onCreateOptionsMenu()` and `onOptionsItemSelected()` methods handle the Toolbar widget navigation functionality.

```java lines expandable theme={null}
package com.auth0.samples.activities;

import android.content.Intent;
import android.os.Bundle;
import android.support.annotation.Nullable;
import android.support.v7.app.AppCompatActivity;
import android.support.v7.widget.Toolbar;
import android.util.Log;
import android.view.Menu;
import android.view.MenuInflater;
import android.view.MenuItem;
import android.view.View;
import android.view.ViewGroup;
import android.widget.Button;
import android.widget.DatePicker;
import android.widget.EditText;
import android.widget.Toast;

import com.auth0.android.Auth0;
import com.auth0.android.authentication.AuthenticationAPIClient;
import com.auth0.android.authentication.storage.CredentialsManager;
import com.auth0.android.authentication.storage.CredentialsManagerException;
import com.auth0.android.authentication.storage.SharedPreferencesStorage;
import com.auth0.android.callback.BaseCallback;
import com.auth0.android.result.Credentials;
import com.auth0.samples.R;
import com.squareup.okhttp.Callback;
import com.squareup.okhttp.MediaType;
import com.squareup.okhttp.OkHttpClient;
import com.squareup.okhttp.Request;
import com.squareup.okhttp.RequestBody;
import com.squareup.okhttp.Response;

import org.json.JSONException;
import org.json.JSONObject;

import java.io.IOException;
import java.util.Calendar;
import java.util.Date;

public class FormActivity extends AppCompatActivity {

    private static final MediaType MEDIA_TYPE_JSON = MediaType.parse("application/json; charset=utf-8");

    private String accessToken;

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.form_activity);
        Toolbar navToolbar = (Toolbar) findViewById(R.id.navToolbar);
        setSupportActionBar(navToolbar);

        Auth0 auth0 = new Auth0(getString(R.string.auth0_client_id), getString(R.string.auth0_domain));
        auth0.setOIDCConformant(true);

        AuthenticationAPIClient authAPIClient = new AuthenticationAPIClient(auth0);
        SharedPreferencesStorage sharedPrefStorage = new SharedPreferencesStorage(this);

        CredentialsManager credentialsManager = new CredentialsManager(authAPIClient, sharedPrefStorage);
        credentialsManager.getCredentials(new BaseCallback<Credentials, CredentialsManagerException>() {
            @Override
            public void onSuccess(Credentials payload) {
                accessToken = payload.getAccessToken();
            }

            @Override
            public void onFailure(CredentialsManagerException error) {
                Toast.makeText(FormActivity.this, "Error: " + error.getMessage(), Toast.LENGTH_SHORT).show();
            }
        });

        Button submitTimeSheetButton = (Button) findViewById(R.id.submitTimeSheetButton);
        final EditText editProjectName = (EditText) findViewById(R.id.editProjectName);
        final EditText editHours = (EditText) findViewById(R.id.editHours);
        final DatePicker datePicker = (DatePicker) findViewById(R.id.datePicker);

        submitTimeSheetButton.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View view) {
                int day = datePicker.getDayOfMonth();
                int month = datePicker.getMonth();
                int year =  datePicker.getYear();

                Calendar calendar = Calendar.getInstance();
                calendar.set(year, month, day);

                postAPI(
                        editProjectName.getText().toString(),
                        calendar.getTime(),
                        editHours.getText().toString()
                );
            }
        });
    }

    private void postAPI(String projectName, Date date, String hours) {

        JSONObject postBody = new JSONObject();
        try {
            postBody.put("project", projectName);
        } catch (JSONException e) {
            e.printStackTrace();
        }
        try {
            postBody.put("date", date);
        } catch (JSONException e) {
            e.printStackTrace();
        }
        try {
            postBody.put("hours", hours);
        } catch (JSONException e) {
            e.printStackTrace();
        }
        String postStr = postBody.toString();

        final Request.Builder reqBuilder = new Request.Builder()
                .post(RequestBody.create(MEDIA_TYPE_JSON, postStr))
                .url(getString(R.string.api_url))
                .addHeader("Authorization", "Bearer " + accessToken);

        OkHttpClient client = new OkHttpClient();
        Request request = reqBuilder.build();

        client.newCall(request).enqueue(new Callback() {
            @Override
            public void onFailure(Request request, IOException e) {
                Log.e("API", "Error: ", e);
                runOnUiThread(new Runnable() {
                    @Override
                    public void run() {
                        Toast.makeText(FormActivity.this, "An error occurred", Toast.LENGTH_SHORT).show();
                    }
                });
            }

            @Override
            public void onResponse(final Response response) throws IOException {
                final String resBody = response.body().string();

                runOnUiThread(new Runnable() {
                    @Override
                    public void run() {
                        if (response.isSuccessful()) {
                            clearForm((ViewGroup) findViewById(R.id.mainForm));
                            Intent intent = new Intent(FormActivity.this, TimeSheetActivity.class);
                            FormActivity.this.startActivity(intent);
                        } else {
                            Toast.makeText(FormActivity.this, "Timesheet creation failed.", Toast.LENGTH_SHORT).show();
                        }
                    }
                });
            }
        });
    }

    private void clearForm(ViewGroup group) {
        for (int i = 0, count = group.getChildCount(); i < count; ++i) {
            View view = group.getChildAt(i);
            if (view instanceof EditText) {
                ((EditText)view).setText("");
            }

            if(view instanceof ViewGroup && (((ViewGroup)view).getChildCount() > 0))
                clearForm((ViewGroup)view);
        }
    }

    @Override
    public boolean onCreateOptionsMenu(Menu menu) {
        MenuInflater inflater = getMenuInflater();
        inflater.inflate(R.menu.form_action_menu, menu);
        return super.onCreateOptionsMenu(menu);
    }

    @Override
    public boolean onOptionsItemSelected(MenuItem item) {
        switch (item.getItemId()) {
            case R.id.action_view:
                startActivity(new Intent(FormActivity.this, TimeSheetActivity.class));
                break;
            case R.id.action_profile:
                startActivity(new Intent(FormActivity.this, UserActivity.class));
                break;
            default:
                return super.onOptionsItemSelected(item);

        }
        return true;
    }
}
```

## Test the App

Before continuing, ensure you have [implemented the Node.JS API](/docs/get-started/architecture-scenarios/mobile-api/api-implementation-nodejs).

1. Start the API by navigating to the API's directory in your terminal and entering the `node server` command.
2. Open the mobile app in Android Studio and press the **Run** button.
3. Select the Nexus 5X API 23 virtual device.
4. Once the emulator has loaded the mobile app, you can login user then, create and view timesheet entries from the running Node.JS API.

That's it! You are done!


# Solution Overview (Mobile Apps + API)
Source: https://auth0.com/docs/get-started/architecture-scenarios/mobile-api/part-1

Solutions Overview for the Mobile + API architecture scenario

In order to ensure that only authorized users and applications are allowed access to the Timesheets API, ExampleCo has decided to make use of the [OAuth 2.0 authorization framework](https://tools.ietf.org/html/rfc6749). The framework provides the flexibility the company wants since the different grants can allow them to easily authorize the various types of applications which need to communicate with the Timesheets API.

## API Authentication and Authorization

An API is a way to expose functionality of your application to other applications. An application can make a request by sending a message to an endpoint on an API and receive information as a response.

An API endpoint can be secured or not. In our case, since the timesheets are sensitive information that affect reviews and payments, it is important to ensure that only authorized users and applications can call the endpoints on our API. When a client application wants to access protected endpoints on an API, it needs to present an <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> as proof that it has the required permissions for making the call to the endpoint.

An Access Token is obtained by authenticating the user with an <Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip> and the user can then, in turn, authorize the application to access the API on their behalf.

<Card title="What is an Access Token?">
  An Access Token (also referred to as `access_token`) is an opaque string representing an authorization issued to the application. It may denote an identifier used to retrieve the authorization information or may self-contain the authorization information (for example, the user's identity, permissions, and so forth) in a verifiable manner.

  It is quite common for Access Tokens to be implemented as [JSON Web Tokens](/docs/secure/tokens/json-web-tokens).

  For more information on Auth0 Access Tokens refer to [Access Token](/docs/secure/tokens/access-tokens).
</Card>

An API can enforce fine-grained control over who can access the various endpoints exposed by the API. These permissions are expressed as scopes.

When a user authorizes a client application, the application can also indicate which permissions it requires. The user is then allowed to review and grant these permissions. These permissions are then included in the Access Token as part of the `scope` claim.

Subsequently, when the client passes along the Access Token when making requests to the API, the API can inspect the `scope` claim to ensure that the required permissions were granted in order to call the particular API endpoint.

<Card title="What are Scopes?">
  Each Access Token may include a list of the permissions that have been granted to the client. When a client authenticates with Auth0, it will specify the list of scopes (or permissions) it is requesting. If those scopes are authorized, then the Access Token will contain a list of authorized scopes.

  For example, the timesheet API may accept four different levels of authorization: reading timesheets (scope `read:timesheets`), creating timesheets (scope `create:timesheets`), deleting timesheets (scope `delete:timesheets`) and approving timesheets (scope `approve:timesheets`).

  When a client asks the API to create a new timesheet entry, then the Access Token should contain the `create:timesheets` scope. In a similar fashion, in order to delete existing timesheets, the Access Token should contain the `delete:timesheets` scope.

  For more information on scopes refer to [Scopes](/docs/get-started/apis/scopes).
</Card>

By using the <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> authorization framework, you can give your own applications or third-party applications limited access to your APIs on behalf of the application itself. Using Auth0, you can easily support different flows in your own APIs without worrying about the OAuth 2.0/<Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) specification, or the many other technical aspects of API authorization.

<Card title="OAuth roles">
  In any OAuth 2.0 flow we can identify the following roles:

  * **Resource Owner**: the entity that can grant access to a protected resource. Typically this is the end-user.
  * **Resource Server**: the server hosting the protected resources. This is the API you want to access.
  * **Client**: an application requesting access to a protected resource on behalf of the Resource Owner.
  * **Authorization Server**: the server that authenticates the Resource Owner, and issues Access Tokens after getting proper authorization. In this case, Auth0's Authentication API.

  [Grants types (or flows)](/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use) determine how these participants interact to grant to the applications limited access to the APIs you are building. As a result, the app will obtain an access token that can be used to call the API on behalf of the user.
</Card>

## Proof Key for Code Exchange (PKCE)

OAuth 2 provides several grant types for different use cases. In this particular use case, we want to access the API from a mobile application, which will use the [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce) to do so.

The [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow) has some security issues when implemented on native applications. For instance, a malicious attacker can intercept the `authorization_code` returned by Auth0 and exchange it for an [Access Token](/docs/secure/tokens/access-tokens) (and possibly a [Refresh Token](/docs/secure/tokens/refresh-tokens)).

The Proof Key for Code Exchange (PKCE) (defined in [RFC 7636](https://tools.ietf.org/html/rfc7636)) is a technique used to mitigate this authorization code interception attack.

With PKCE, the Application creates, for every authorization request, a cryptographically random key called `code_verifier` and its transformed value called `code_challenge`, which is sent to Auth0 to get the `authorization_code`. When the Application receives the `authorization_code`, it will send the code and the `code_verifier` to Auth0's <Tooltip href="/docs/glossary?term=token+endpoint">token endpoint</Tooltip> to exchange them for the requested tokens.

<Frame>
  <img alt="Diagram - Microsite - Auth Code with PKCE" />
</Frame>

1. The native app initiates the flow and redirects the user to Auth0 (specifically to the [/authorize endpoint](https://auth0.com/docs/api/authentication#authorization-code-grant-pkce-)), sending the `code_challenge` and `code_challenge_method` parameters.
2. Auth0 redirects the user to the native app with an `authorization_code` in the query string.
3. The native app sends the `authorization_code` and `code_verifier` together with the `redirect_uri` and the `client_id` to Auth0. This is done using the [/oauth/token endpoint](https://auth0.com/docs/api/authentication?http#authorization-code-pkce-).
4. Auth0 validates this information and returns an Access Token (and optionally a Refresh Token).
5. The native app can use the Access Token to call the API on behalf of the user.

<Callout icon="file-lines">
  If you have [Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation) enabled, a new Refresh Token is generated with each request and issued along with the Access Token. When a Refresh Token is exchanged, the previous Refresh Token is invalidated but information about the relationship is retained by the authorization server.
</Callout>

## Authorization Extension

The [Auth0 Authorization Extension](/docs/customize/extensions/authorization-extension) allows you to provide authorization support in your application, by assigning Roles, Groups and Permissions to Users.

The Authorization Extension creates a [Rule](/docs/customize/rules) which will augment the User profile during the authentication flow with the Roles, Groups and Permissions assigned to the user. You can then use this information to ensure that the Access Token issued to a user only contains scopes which are allowed according to the permissions defined in the Authorization Extension.

PREVIOUS TUTORIAL [Introduction](/docs/get-started/architecture-scenarios/mobile-api)

NEXT TUTORIAL [2. Auth0 Configuration](/docs/get-started/architecture-scenarios/mobile-api/part-2)


# Auth0 Configuration (Mobile Apps + API)
Source: https://auth0.com/docs/get-started/architecture-scenarios/mobile-api/part-2

Auth0 Configuration for the Mobile + API architecture scenario

In this section we will review all the configurations we need to apply at the [Auth0 Dashboard](https://manage.auth0.com/#).

## Create the API

Click on the [APIs menu option](https://manage.auth0.com/#/apis) on the left, and click the Create API button.

You will be required to supply the following details for your API:

* **Name**: a friendly name for the API. Does not affect any functionality.
* **Identifier**: a unique identifier for the API. We recommend using a URL but note that this doesn't have to be a publicly available URL, Auth0 will not call your API at all. This value cannot be modified afterwards.
* **<Tooltip href="/docs/glossary?term=Signing+Algorithm">Signing Algorithm</Tooltip>**: the algorithm to sign the tokens with. The available values are `HS256` and `RS256`. When selecting RS256 the token will be signed with the tenant's private key. To learn more about signing algorithms, see [Signing Algorithms](/docs/get-started/applications/signing-algorithms).

<Frame>
  <img alt="Dashboard - Applications - APIs - Create API - Popup" />
</Frame>

Fill in the required information and click the **Create** button.

#### Signing Algorithms

When you create an API you have to select the algorithm your tokens will be signed with. The signature is used to verify that the sender of the <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> is who it says it is and to ensure that the message wasn't changed along the way.

<Callout icon="file-lines">
  The signature is part of a JWT. If you are unfamiliar with JWT structure, please see [JSON Web Token Structure](/docs/secure/tokens/json-web-tokens/json-web-token-structure).
</Callout>

To create the signature part you have to take the encoded header, the encoded payload, a secret, the algorithm specified in the header, and sign that. That algorithm, which is part of the JWT header, is the one you select for your API: `HS256` or `RS256`.

* **RS256** is an [asymmetric algorithm](https://en.wikipedia.org/wiki/Public-key_cryptography) which means that there are two keys: one public and one private (secret). Auth0 has the secret key, which is used to generate the signature, and the consumer of the JWT has the public key, which is used to validate the signature.
* **HS256** is a [symmetric algorithm](https://en.wikipedia.org/wiki/Symmetric-key_algorithm) which means that there is only one secret key, shared between the two parties. The same key is used both to generate the signature and to validate it. Special care should be taken in order for the key to remain confidential.

The most secure practice, and our recommendation, is to use **RS256**. Some of the reasons are:

* With RS256 you are sure that only the holder of the private key (Auth0) can sign tokens, while anyone can check if the token is valid using the public key.
* Under HS256, If the private key is compromised you would have to re-deploy the API with the new secret. With RS256 you can request a token that is valid for multiple audiences.
* With RS256 you can implement key rotation without having to re-deploy the API with the new secret.

<Callout icon="file-lines">
  For a more detailed overview of the JWT signing algorithms refer to: [JSON Web Token (JWT) Signing Algorithms Overview](https://auth0.com/blog/json-web-token-signing-algorithms-overview/).
</Callout>

### Configure the Permissions

Once the application has been created you will need to configure the Permissions which applications can request during authorization.

In the settings for your API, go to the **Permissions** tab. In this section you can add all four of the scopes which were discussed before, namely `read:timesheets`, `create:timesheets`, `delete:timesheets`, `approve:timesheets`.

<Frame>
  <img alt="Dashboard - Applications - APIs - Permissions" />
</Frame>

## Create the Application

There are four application types in Auth0: **Native App** (used by mobile or desktop apps), **Single-Page Web App**, **Regular Web App**, and **Machine to Machine App** (used by CLIs, Daemons, or services running on your backend). For this scenario we want to create a new Application for our mobile application, hence we will use Native as the application type.

To create a new Application, navigate to the [dashboard](https://manage.auth0.com/#) and click on the [Applications](https://manage.auth0.com/#/applications) menu option on the left. Click the **+ Create Application** button.

Set a name for your Application (we will use `Timesheets Mobile`) and select `Native App` as the type.

Click **Create**.

## Configure the Authorization Extension

You will need to ensure that the Authorization Extension is installed for your tenant. You can refer to the [Authorization Extension documentation](/docs/customize/extensions/authorization-extension) for details on how to do this.

### Define Permissions

You will need to define Permissions which correlates with the scopes you have already defined. In the Authorization Extension, click the Permissions tab, and then click on the **Create Permission** button. In the dialog, capture the details for each permission. Ensure that the name of the permission is exactly the same as the corresponding scope:

Proceed to create the permissions for all the remaining scopes:

### Define Roles

Head over to the Roles tab and create two Roles. Click the **Create Role** button and select the **Timesheets SPA** application. Give the Role a name and description of Employee, and select the `delete:timesheets`, `create:timesheets` and `read:timesheets` permissions. Click on **Save**.

Next, follow the same process to create a **Manager** role, and ensure that you have selected all the permissions:

<Frame>
  <img alt="Dashboard - Extensions - Authorization Extension - Create Manager Role" />
</Frame>

### Assign Users to Roles

You will need to assign all users to either the Manager or the User role. You can do this by going to the Users tab in the Authorization Extension and selecting a user. On the user information screen, go to the Roles tab. You can add a role to the user by clicking the **Add Role to User** button, and selecting the appropriate role for the user.

### Configuring the Authorization Extension

You will also need to ensure that the Rule for the Authorization Extension is published. You can do this by clicking on your user avatar in to top right of the Authorization Extension, and selecting the **Configuration** option:

Ensure that you have enabled **Permissions** and then click the **Publish Rule** button.

### Create a Rule to validate token scopes

The final step in this process is to create a Rule which will validate that the scopes contained in an <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> is valid based on the permissions assigned to the user. Any scopes which are not valid for a user should be removed from the Access Token.

In your <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, go to the Rules tab. You should see the Rule created by the Authorization Extension.

Click on the **Create Rule** button and select the **Empty Rule** template. You can give the Rule a name, such as **Access Token Scopes**, and then specify the following code for the Rule:

```javascript lines theme={null}
function (user, context, callback) {
  if (context.clientName !== 'Timesheets SPA') {
    return callback(null, user, context);
  }

  var permissions = user.permissions || [];
  var requestedScopes = context.request.body.scope || context.request.query.scope;
  var filteredScopes = requestedScopes.split(' ').filter( function(x) {
    return x.indexOf(':') < 0;
  });
  Array.prototype.push.apply(filteredScopes, permissions);
  context.accessToken.scope = filteredScopes.join(' ');

  callback(null, user, context);
}
```

The code above will ensure that all Access Tokens will only contain the properly-formatted scopes (e.g., `action:area` or `delete:timesheets`) which are valid according to a user's permissions. Once you are done you can click on the **Save** button.

Rules execute in the order they are displayed on the Rules page, so ensure that the new rule you created is positioned below the rule for the Authorization Extension, so it executes after the Authorization Extension rule.

PREVIOUS TUTORIAL [1. Solution Overview](/docs/get-started/architecture-scenarios/mobile-api/part-1)

NEXT TUTORIAL [3. API + Mobile Implementation](/docs/get-started/architecture-scenarios/mobile-api/api-implementation-nodejs)


# API and Mobile Configuration (Mobile Apps + API)
Source: https://auth0.com/docs/get-started/architecture-scenarios/mobile-api/part-3

API and Mobile Configuration for the Mobile + API architecture scenario

In this section we will see how we can implement an API for our scenario.

<Callout icon="file-lines">
  For simplicity, we will keep our implementation solely focused on authentication and authorization. As you will see in the samples, the input timesheet entry will be hard-coded, and the API will not persist the timesheet entry. Instead, it will simply echo back some of the info.
</Callout>

## Define the API endpoints

First we need to define the endpoints of our API.

<Card title="What is an API endpoint?">
  An **API endpoint** is a unique URL that represents an object. To interact with this object, you need to point your application to its URL. For example, if you had an API that could return either orders or customers, you might configure two endpoints: `/orders` and `/customers`. Your application would interact with these endpoints using different HTTP methods; for example, `POST /orders` could create a new order or `GET /orders` could retrieve the dataset of one or more orders.
</Card>

For this implementation we will only define two endpoints; one for retrieving a list of all timesheets for an employee, and another which will allow an employee to create a new timesheet entry.

An `HTTP GET` request to the `/timesheets` endpoint will allow a user to retrieve their timesheets, and an `HTTP POST` request to the `/timesheets` endpoint will allow a user to add a new timesheet.

See the implementation in [Node.js](/docs/get-started/architecture-scenarios/mobile-api/api-implementation-nodejs#1-define-the-api-endpoints)

### Secure the Endpoints

When an API receives a request with a bearer <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> as part of the header, the first thing to do is to validate the token. This consists of a series of steps, and if any of these fails then the request must be rejected with a `Missing or invalid token` error message to the calling app.

The validations that the API should perform are:

* Check that the <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> is well formed
* Check the signature
* Validate the standard claims

<Callout icon="file-lines">
  [JWT.io](https://jwt.io/) provides a list of libraries that can do most of the work for you: parse the JWT, verify the signature and the claims.
</Callout>

Part of the validation process is to also check the Client permissions (scopes), but we will address this separately in the next paragraph of this document.

For more information on validating Access Tokens, see [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens).

See the implementation in [Node.js](/docs/get-started/architecture-scenarios/mobile-api/api-implementation-nodejs#2-secure-the-api-endpoints)

### Check the Client's Permissions

By now we have verified that the JWT is valid. The last step is to verify that the client has the permissions required to access the protected resources.

To do so, the API needs to check the [scopes](/docs/get-started/apis/scopes) of the decoded JWT. This claim is part of the payload and it is a space-separated list of strings.

See the implementation in [Node.js](/docs/get-started/architecture-scenarios/mobile-api/api-implementation-nodejs#3-check-the-client-permissions)

### Determine user identity

For both endpoints (retrieving the list of timesheets, and adding a new timesheet) we will need to determine the identity of the user.

For retrieving the list of timesheets this is to ensure that we only return the timesheets belonging to the user making the request, and for adding a new timesheet this is to ensure that the timesheet is associated with the user making the request.

One of the standard JWT claims is the `sub` claim which identifies the principal that is the subject to the claim. In the case of the Implicit Grant flow this claim will contain the user's identity, which will be the unique identifier for the Auth0 user. You can use this to associate any information in external systems with a particular user.

You can also use a custom claim to add another attribute of the user - such as their email address - to the Access Token and use that to uniquely identify the user.

See the implementation in [Node.js](/docs/get-started/architecture-scenarios/mobile-api/api-implementation-nodejs#4-determine-the-user-identity)

## Implement the Mobile App

In this section we will see how we can implement a mobile application for our scenario.

[See the implementation in Android.](/docs/get-started/architecture-scenarios/mobile-api/mobile-implementation-android#1-set-up-the-application)

### Authorize the User

To authorize the user we will implement the [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/call-your-api-using-the-authorization-code-flow-with-pkce). The mobile application should first send the user to the [authorization URL](https://auth0.com/docs/api/authentication#authorization-code-grant-pkce-) along with the `code_challenge` and the method used to generate it:

<AuthCodeBlock />

The `GET` request to the authorization URL should include the following values:

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>client\_id</strong></td>
      <td>The value of your Auth0 Client Id. You can retrieve it from the Settings of your Application at the <a href="https://manage.auth0.com/#/applications">Auth0 Dashboard</a>.</td>
    </tr>

    <tr>
      <td><strong>audience</strong></td>
      <td>The value of your API Identifier. You can retrieve it from the Settings of your API at the <a href="https://manage.auth0.com/#/apis">Auth0 Dashboard</a>.</td>
    </tr>

    <tr>
      <td><strong>scope</strong></td>
      <td>The <a href="/docs/get-started/apis/scopes">scopes</a> which determine the claims to be returned in the ID Token and Access Token. For example, a scope of <code>openid</code> will return an ID Token in the response. In our example mobile app, we use the following scopes: <code>create:timesheets read:timesheets openid profile email offline\_access</code>. These scopes allow the mobile app to call the API, obtain a <Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip>, and return the user's <code>name</code>, <code>picture</code>, and <code>email</code> claims in the ID Token.</td>
    </tr>

    <tr>
      <td><strong>response\_type</strong></td>
      <td>Indicates the Authentication Flow to use. For a mobile application using PKCE, this should be set to <code>code</code>.</td>
    </tr>

    <tr>
      <td><strong>code\_challenge</strong></td>
      <td>The generated code challenge from the code verifier. You can find instructions on generating a code challenge <a href="/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/call-your-api-using-the-authorization-code-flow-with-pkce#authorize-the-user%23create-a-code-verifier">here</a>.</td>
    </tr>

    <tr>
      <td><strong>code\_challenge\_method</strong></td>
      <td>Method used to generate the challenge. Auth0 supports only <code>S256</code>.</td>
    </tr>

    <tr>
      <td><strong>redirect\_uri</strong></td>
      <td>The URL which Auth0 will redirect the browser to after authorization has been granted by the user. The Authorization Code will be available in the code URL parameter. This URL must be specified as a valid callback URL under your <a href="https://manage.auth0.com/#/applications">Application's Settings</a>.</td>
    </tr>
  </tbody>
</table>

[See the implementation in Android.](/docs/get-started/architecture-scenarios/mobile-api/mobile-implementation-android#2-authorize-the-user)

### Get the Credentials

After a successful request to the authorization URL, you should receive the following response:

<AuthCodeBlock />

Next you can exchange the `authorization_code` from the response for an Access Token that can be used to call your API. Perform a `POST` request to the [Token URL](https://auth0.com/docs/api/authentication#authorization-code-pkce-) including the following data:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=authorization_code \
    --data 'client_id={yourClientId}' \
    --data code_verified=YOUR_GENERATED_CODE_VERIFIER \
    --data code=YOUR_AUTHORIZATION_CODE \
    --data 'redirect_uri=https://{https://yourApp/callback}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=authorization_code&client_id={yourClientId}&code_verified=YOUR_GENERATED_CODE_VERIFIER&code=YOUR_AUTHORIZATION_CODE&redirect_uri=https%3A%2F%2F{https://yourApp/callback}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=authorization_code&client_id={yourClientId}&code_verified=YOUR_GENERATED_CODE_VERIFIER&code=YOUR_AUTHORIZATION_CODE&redirect_uri=https%3A%2F%2F{https://yourApp/callback}")

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

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=authorization_code&client_id={yourClientId}&code_verified=YOUR_GENERATED_CODE_VERIFIER&code=YOUR_AUTHORIZATION_CODE&redirect_uri=https%3A%2F%2F{https://yourApp/callback}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: '{yourClientId}',
      code_verified: 'YOUR_GENERATED_CODE_VERIFIER',
      code: 'YOUR_AUTHORIZATION_CODE',
      redirect_uri: 'https://{https://yourApp/callback}'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=authorization_code" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&code_verified=YOUR_GENERATED_CODE_VERIFIER" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&code=YOUR_AUTHORIZATION_CODE" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&redirect_uri=https://{https://yourApp/callback}" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=authorization_code&client_id={yourClientId}&code_verified=YOUR_GENERATED_CODE_VERIFIER&code=YOUR_AUTHORIZATION_CODE&redirect_uri=https%3A%2F%2F{https://yourApp/callback}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=authorization_code&client_id={yourClientId}&code_verified=YOUR_GENERATED_CODE_VERIFIER&code=YOUR_AUTHORIZATION_CODE&redirect_uri=https%3A%2F%2F{https://yourApp/callback}"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=authorization_code&client_id={yourClientId}&code_verified=YOUR_GENERATED_CODE_VERIFIER&code=YOUR_AUTHORIZATION_CODE&redirect_uri=https%3A%2F%2F{https://yourApp/callback}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/x-www-form-urlencoded"]

  let postData = NSMutableData(data: "grant_type=authorization_code".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&code_verified=YOUR_GENERATED_CODE_VERIFIER".data(using: String.Encoding.utf8)!)
  postData.append("&code=YOUR_AUTHORIZATION_CODE".data(using: String.Encoding.utf8)!)
  postData.append("&redirect_uri=https://{https://yourApp/callback}".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>grant\_type</strong></td>
      <td>This must be set to <code>authorization\_code</code>.</td>
    </tr>

    <tr>
      <td><strong>client\_id</strong></td>
      <td>The value of your Auth0 Client Id. You can retrieve it from the Settings of your Application at the <a href="https://manage.auth0.com/#/applications">Auth0 Dashboard</a>.</td>
    </tr>

    <tr>
      <td><strong>code\_verifier</strong></td>
      <td>Cryptographically random key that was used to generate the <code>code\_challenge</code> passed to <a href="https://auth0.com/docs/api/authentication#authorization-code-grant-pkce-">authorization URL</a> (<code>/authorize</code>).</td>
    </tr>

    <tr>
      <td><strong>code</strong></td>
      <td>The <code>authorization\_code</code> received from the previous authorize call.</td>
    </tr>

    <tr>
      <td><strong>redirect\_uri</strong></td>
      <td>The URL must match the <code>redirect\_uri</code> passed in the previous section to <code>/authorize</code>.</td>
    </tr>
  </tbody>
</table>

The response from the Token URL will contain:

```json lines theme={null}
{
  "access_token": "eyJz93a...k4laUWw",
  "refresh_token": "GEbRxBN...edjnXbL",
  "id_token": "eyJ0XAi...4faeEoQ",
  "token_type": "Bearer",
  "expires_in":86400
}
```

* **access\_token**: An Access Token for the API, specified by the `audience`.
* **refresh\_token**: A [Refresh Token](/docs/secure/tokens/refresh-tokens) will only be present if you included the `offline_access` scope AND enabled **Allow Offline Access** for your API in the Dashboard.
* **id\_token**: An <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip> JWT containing user profile information.
* **token\_type**: A string containing the type of token, this will always be a Bearer token.
* **expires\_in**: The amount of seconds until the Access Token expires.

You will need to store the above credentials in local storage for use in calling your API and retrieving the user profile.

[See the implementation in Android](/docs/get-started/architecture-scenarios/mobile-api/mobile-implementation-android#store-credentials).

### Get the User Profile

To retrieve the [User Profile](https://auth0.com/docs/api/authentication?http#user-profile), your mobile application can decode the [ID Token](/docs/secure/tokens/id-tokens) using one of the [JWT libraries](https://jwt.io/#libraries-io). This is done by [verifying the signature](/docs/secure/tokens/id-tokens/validate-id-tokens#verify-the-signature) and [verifying the claims](/docs/secure/tokens/id-tokens/validate-id-tokens#verify-the-claims) of the token. After validating the ID Token, you can access its payload containing the user information:

```json lines theme={null}
{
  "email_verified": false,
  "email": "test.account@userinfo.com",
  "clientID": "q2hnj2iu...",
  "updated_at": "2016-12-05T15:15:40.545Z",
  "name": "test.account@userinfo.com",
  "picture": "https://s.gravatar.com/avatar/dummy.png",
  "user_id": "auth0|58454...",
  "nickname": "test.account",
  "created_at": "2016-12-05T11:16:59.640Z",
  "sub": "auth0|58454..."
}
```

[See the implementation in Android.](/docs/get-started/architecture-scenarios/mobile-api/mobile-implementation-android#3-get-the-user-profile)

### Display UI Elements Conditionally Based on Scope

Based on the `scope` of the user, you may want to show or hide certain UI elements. To determine the scope issued to a user, you will need to inspect the `scope` which was granted when the user was authenticated. This will be a string containing all the scopes, so you therefore need to inspect this string to see whether it contains the required `scope` and based on that make a decision whether to display a particular UI element.

[See the implementation in Android](/docs/get-started/architecture-scenarios/mobile-api/mobile-implementation-android#4-display-ui-elements-conditionally-based-on-scope)

### Call the API

To access secured resources from your API, the authenticated user's Access Token needs to be included in requests that are sent to it. This is accomplished by sending the Access Token in an `Authorization` header using the `Bearer` scheme.

[See the implementation in Android.](/docs/get-started/architecture-scenarios/mobile-api/mobile-implementation-android#5-call-the-api)

### Renew the Token

<Warning>
  Refresh Tokens must be stored securely by an application since they do not expire and allow a user to remain authenticated essentially forever. If Refresh Tokens are compromised or you no longer need them, you can revoke the Refresh Tokens using the [Authentication API](https://auth0.com/docs/api/authentication#revoke-refresh-token).
</Warning>

To refresh your Access Token, perform a `POST` request to the `/oauth/token` endpoint using the <Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip> from your authorization result.

A [Refresh Token](/docs/secure/tokens/refresh-tokens) will only be present if you included the `offline_access` scope in the previous authorization request and enabled **Allow Offline Access** for your API in the Dashboard.

Your request should include:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	req, _ := http.NewRequest("POST", url, nil)

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

  NSData *postData = [[NSData alloc] initWithData:[@"undefined" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", headers=headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/x-www-form-urlencoded"]

  let postData = NSData(data: "undefined".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>grant\_type</strong></td>
      <td>This must be set to <code>refresh\_token</code>.</td>
    </tr>

    <tr>
      <td><strong>client\_id</strong></td>
      <td>The value of your Auth0 Client Id. You can retrieve it from the Settings of your Application at the <a href="https://manage.auth0.com/#/applications">Auth0 Dashboard</a>.</td>
    </tr>

    <tr>
      <td><strong>refresh\_token</strong></td>
      <td>the Refresh Token to use, from the previous authentication result.</td>
    </tr>
  </tbody>
</table>

The response will include the new Access Token:

```json lines theme={null}
{
  "access_token": "eyJz93a...k4laUWw",
  "refresh_token": "GEbRxBN...edjnXbL",
  "id_token": "eyJ0XAi...4faeEoQ",
  "token_type": "Bearer",
  "expires_in":86400
}
```

[See the implementation in Android.](/docs/get-started/architecture-scenarios/mobile-api/mobile-implementation-android#store-the-credentials)


# Conclusion (Mobile Apps + API)
Source: https://auth0.com/docs/get-started/architecture-scenarios/mobile-api/part-4

Conclusion for the Mobile + API architecture scenario

In this document we covered a simple scenario: an API, used by a mobile application to allow employees to capture their timesheets.

We learned about the Authorization Code Grant with PKCE, what an <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> is, how to configure an API in Auth0, how to configure a mobile application to communicate securely with this API, how to define and secure our API endpoints, how to use the provided libraries to validate the Access Token and how to retrieve a new one from Auth0.

We started by describing the business case and the requirements and went on explaining how each requirement can be met and the thought process behind each choice that was made.

We used Node.js for the API implementation and Android for the mobile application. Hopefully though after going through this document you are able to build this using the technologies you prefer.

Don't forget to check back for new business cases and more complex architecture scenarios!


# Server Apps + API: Node.js Implementation for the API
Source: https://auth0.com/docs/get-started/architecture-scenarios/server-application-api/api-implementation-nodejs

The Node.js implementation of the API for the Server Client + API architecture scenario

As part of the [Server + API Architecture Scenario](/docs/get-started/architecture-scenarios/server-application-api), we will implement the Timesheets API in Node.js. Please refer to the scenario for information on the implemented solution.

Full source code for the Node.js API implementation can be found in [this GitHub repository](https://github.com/auth0-samples/auth0-pnp-exampleco-timesheets/tree/master/timesheets-api/node).

## Step 1. Define the API endpoint

We will use the [Express web application framework](http://expressjs.com/) to build our Node.js API.

### Create a package.json File

Create a folder for your API, navigate into it and run `npm init`. This will set up your `package.json` file.

You can leave the default settings or change them as you see fit.

Our sample’s `package.json` looks like the following:

```json lines theme={null}
{
  "name": "timesheets-api",
  "version": "1.0.0",
  "description": "API used to add timesheet entries for employees and contractors",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/auth0-samples/auth0-pnp-timesheets.git"
  },
  "author": "Auth0",
  "license": "MIT",
  "bugs": {
    "url": "https://github.com/auth0-samples/auth0-pnp-timesheets/issues"
  },
  "homepage": "https://github.com/auth0-samples/auth0-pnp-timesheets#readme"
}
```

### Install the Dependencies

Next, we need to set our dependencies. We will use the following modules:

* **express**: This module adds the [Express web application framework](https://expressjs.com/).
* **jwks-rsa**: This library retrieves RSA signing keys from a JWKS (JSON Web Key Set) endpoint. Using `expressJwtSecret` we can generate a secret provider that will provide the right signing key to `express-jwt` based on the `kid` in the <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> header. For more information refer to the [node-jwks-rsa GitHub repository](https://github.com/auth0/node-jwks-rsa).
* **express-jwt**: This module lets you authenticate HTTP requests using JWT tokens in your Node.js applications. It provides several functions that make working with JWTs easier. For more information refer to the [express-jwt GitHub repository](https://github.com/auth0/express-jwt).
* **body-parser**: This is a Node.js body parsing middleware. It extracts the entire body portion of an incoming request stream and exposes it on `req.body` as something easier to interface with.For more information and several alternatives refer to the body-parser GitHub repository.

To install these dependencies run the following:

```bash lines theme={null}
npm install express express-jwt jwks-rsa body-parser --save
```

### Implement the Endpoint

Navigate to your API directory and create a `server.js` file. Your code needs to:

* Set the dependencies.
* Enable the request body parsing middleware.
* Implement the endpoint.
* Launch the API server.

This is our sample implementation:

```javascript lines theme={null}
// set dependencies
const express = require('express');
const app = express();
const jwt = require('express-jwt');
const jwksRsa = require('jwks-rsa');
const bodyParser = require('body-parser');

// enable the use of request body parsing middleware
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({
  extended: true
}));

// create timesheets upload API endpoint
app.post('/timesheets/upload', function(req, res){
  res.status(201).send({message: "This is the POST /timesheets/upload endpoint"});
})

// launch the API Server at localhost:8080
app.listen(8080);
```

Launch your API server using `node server` and make an HTTP POST request to `localhost:8080/timesheets/upload`. You should see a JSON response with a message `This is the POST /timesheets/upload endpoint`.

So now we have our endpoint but anyone can call it. Continue to the next paragraph to see how we can fix this.

## Step 2. Secure the API endpoint

In order to validate our token we will use the `jwt` function, provided by the [express-jwt middleware](https://github.com/auth0/express-jwt#usage), and the `jwks-rsa` package to retrieve the public key from Auth0. The libraries do the following:

1. `express-jwt` will decode the token and pass the request, the header and the payload to `jwksRsa.expressJwtSecret`.
2. `jwks-rsa` will then download all signing keys from the JWKS endpoint and see if a one of the signing keys matches the `kid` in the header of the JWT. If none of the signing keys match the incoming `kid`, an error will be thrown. If we have a match, we will pass the right signing key to `express-jwt`.
3. `express-jwt` will continue its own logic to validate the signature of the token, the expiration, `audience` and the `issuer`.

The steps we will follow in our code are:

* Create the middleware function to validate the <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>.
* Enable the use of the middleware in our routes.

This is also a good time for you to implement the logic to save the timesheet entries to a local database, or whatever other storage mechanism you may prefer. This is our sample implementation (some code is omitted for brevity):

<AuthCodeBlock />

If we launch our server now and do an HTTP POST to `localhost:8080/timesheets/upload` we should get the error message `Missing or invalid token` (which is perfectly fine since we didn’t send an access token in our request).

In order to test the working scenario as well we need to:

* Get an access token. For details on how to do so refer to: [Get an Access Token](/docs/get-started/architecture-scenarios/server-application-api#get-an-access-token)
* Invoke the API while adding an `Authorization` header to our request with the value `Bearer ACCESS_TOKEN` (where `ACCESS_TOKEN` is the value of the token we retrieved in the first step).

## Step 3. Check the Client permissions

In this step we will add to our implementation the ability to check if the client has permissions (or `scope`) to use our endpoint in order to upload a timesheet. In particular we want to ensure that the token has the correct scope, which is `batch:upload`.

In order to do this we will make use of the `express-jwt-authz` Node.js package, so go ahead and add that to your project:

```bash lines theme={null}
npm install express-jwt-authz --save
```

Now it is as simple as adding a call to `jwtAuthz(...)` to your middleware to ensure that the JWT contains a particular scope in order to execute a particular endpoint. This is our sample implementation (some code is omitted for brevity):

```javascript lines theme={null}
// set dependencies - some code omitted
const jwtAuthz = require('express-jwt-authz');

// Create middleware for checking the JWT

// Enable the use of request body parsing middleware
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({
  extended: true
}));

// Batch upload endpoint
app.post('/timesheets/upload', checkJwt, jwtAuthz(['batch:upload']), function(req, res){
  var timesheet = req.body;

  // Save the timesheet entry to the database...

  //send the response
  res.status(201).send(timesheet);
});

// launch the API Server at localhost:8080 - code omitted
```

If we invoke our API with a token that does not include this scope we should get the error message Forbidden with the HTTP status code `403`. You can test this by removing this scope from your API.

That's it! You are done!


# Server Apps + API: Python Implementation for the Cron Job
Source: https://auth0.com/docs/get-started/architecture-scenarios/server-application-api/cron-implementation-python

The Python implementation of the server cron job for the Server Client + API architecture scenario

As part of the [Server + API Architecture Scenario](/docs/get-started/architecture-scenarios/server-application-api), we will explain how to implement the server process in Python. Please refer to the [Server + API Architecture Scenario](/docs/get-started/architecture-scenarios/server-application-api) document for information on the implemented solution.

Full source code for the Python implementation of the server process can be found in [this GitHub repository](https://github.com/auth0-samples/auth0-pnp-exampleco-timesheets/tree/master/timesheets-cron/python).

## Get an access token

In order to make the HTTP request to the Auth0 `/oauth/token` API endpoint we will use the libraries `json`, `urllib` and `urllib2`.

This is our sample implementation:

<AuthCodeBlock />

To test this modify your code to print the `access_token` variable and run the process using `python cron.py`.

## Invoke the API

The steps we follow in our implementation are:

* Build a JSON object containing timesheet data and assign it to a `timesheet` variable.
* Add the API URL and the `timesheet` variable contents to the request body using `urllib2.Request`.
* Add the `Authorization` header to the request.
* Set the `Content-Type` header to `application/json`.
* Invoke the API using `urllib2.urlopen` and add some error handling. Retrieve the response using `json.loads` and print it in the console.

This is our sample implementation (some code is omitted for brevity):

```python lines expandable theme={null}
def main():
  # import libraries - code omitted

  # Configuration Values - code omitted

  # Get an Access Token from Auth0 - code omitted

  #Post new timesheet to API
  timesheet = {'user_id': '007',
                          'date': '2017-05-10T17:40:20.095Z',
                          'project': 'StoreZero',
                          'hours': 5}
  req = urllib2.Request(api_url, data = json.dumps(timesheet))
  req.add_header('Authorization', 'Bearer ' + access_token)
  req.add_header('Content-Type', 'application/json')

  try:
    response = urllib2.urlopen(req)
    res = json.loads(response.read())
    print 'Created timesheet ' + str(res['id']) + ' for employee ' + str(res['user_id'])
  except urllib2.HTTPError, e:
    print 'HTTPError = ' + str(e.code) + ' ' + str(e.reason)
  except urllib2.URLError, e:
    print 'URLError = ' + str(e.reason)
  except httplib.HTTPException, e:
    print 'HTTPException'
  except Exception, e:
    print 'Generic Exception' + str(e)

# Standard boilerplate to call the main() function - code omitted
```

To test this make sure your API is running and run the process using `python cron.py`.

That's it! You are done!


# Conclusion (Server Apps + API)
Source: https://auth0.com/docs/get-started/architecture-scenarios/server-application-api/part-4

Conclusion for the Server + API architecture scenario

In the [Server + API Architecture Scenario](/docs/get-started/architecture-scenarios/server-application-api), we covered a simple, machine-to-machine scenario: an API, used to import timesheet entries in ExampleCo's systems, and a cron job, used by external contractors to send in their timesheets using this API.

We learned about the Client Credentials Grant and <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip>, how to configure an API in Auth0, how to configure a Machine-to-Machine Application to communicate securely with this API, how to define and secure our API endpoints, how to use the provided libraries to validate the access token and how to retrieve a new one from Auth0.

We used Node.js for the API implementation and Python for the non-interactive server process. We hope this examples empowers you to build your own implementation with your preferred technologies.


# Single-Page Applications (SPA) with API
Source: https://auth0.com/docs/get-started/architecture-scenarios/spa-api

Explains the architecture scenario where a single-page application (SPA) talks to an API using OpenID Connect (OIDC), and the OAuth 2.0 Implicit Grant Flow, to authenticate users with Auth0.

In this scenario, we will build a timesheet API for a fictitious company named ExampleCo. The API will allow adding timesheet entries for an employee or a contractor.

We will also be building a single-page application (SPA) which will be used to log timesheet entries and send them to the centralized timesheet database using the API.

<Info>
  ### TL;DR

  * Auth0 provides API Authentication and Authorization as a means to secure access to API endpoints (see [API Authentication and Authorization](/docs/get-started/architecture-scenarios/spa-api/part-1#api-authentication-and-authorization))
  * For authorizing a user of a SPA, Auth0 supports the Implicit Grant (see [Implicit Grant](/docs/get-started/architecture-scenarios/spa-api/part-1#implicit-grant))
  * Both the SPA and the API must be configured in the Auth0 Dashboard (see [Auth0 Configuration](/docs/get-started/architecture-scenarios/spa-api/part-2#auth0-configuration))
  * User Permissions can be enforced using the Authorization Extension (see [Configure the Authorization Extension](/docs/get-started/architecture-scenarios/spa-api/part-2#configure-the-authorization-extension))
  * The API will be secured by ensuring that a valid Access Token is passed in the HTTP Authorization header when calls are made to the API (see [Implement the API](/docs/get-started/architecture-scenarios/spa-api/part-3#implement-the-api))
  * The Auth0.js library can be used to authorize the user of the SPA and obtain a valid Access Token which can be used to call the API (see [Authorize the User](/docs/get-started/architecture-scenarios/spa-api/part-3#authorize-the-user))
  * The SPA can pass the Access Token in the HTTP Authorization header when making calls to the API (see [Call the API](/docs/get-started/architecture-scenarios/spa-api/part-3#call-the-api))
  * The SPA can display UI elements conditionally based on scopes granted to user (see [Display UI Elements Conditionally Based on Scope](/docs/get-started/architecture-scenarios/spa-api/part-3#display-ui-elements-conditionally-based-on-scope))
</Info>

## The Premise

ExampleCo is a consulting startup company. Currently, they have approximately 100 employees and they also outsource several activities to external contractors. All employees and external contractors are required to fill in their timesheets every week.

The company has built a timesheets application, a scenario we covered in [Single Sign-On for Regular Web Apps](/docs/get-started/architecture-scenarios/sso-for-regular-web-apps). The internal employees use this web app to fill in their timesheets but the company wants to replace it with a SPA. The app will be used to log timesheet entries and send the data to the centralized timesheet database using the API. The app will also allow managers to approve timesheet entries.

## Goals & Requirements

ExampleCo wants to build a flexible solution. At the moment only a SPA is required to capture timesheet entries but in the future, the company plans on launching more applications, like a mobile app to accommodate their sales teams. Hence the company has decided to develop a single Timesheets API which will be used to log time not only by this server process but by all future applications as well. They want to put in place a security architecture that is flexible enough to accommodate this. ExampleCo wants to ensure that a large part of the code and business logic for the application can be shared across the different applications.

It is required that only authorized users and applications are allowed access to the Timesheets API.

Two kinds of users will use this SPA: employees and managers. The employees should be able to read, create and delete their own timesheet entries, while the managers should be able to approve timesheets as well.

## Learn more

* [Solution Overview (SPAs + API)](/docs/get-started/architecture-scenarios/spa-api/part-1)
* [Auth0 Configuration (SPAs + API)](/docs/get-started/architecture-scenarios/spa-api/part-2)
* [API and SPA Configuration (SPAs + API)](/docs/get-started/architecture-scenarios/spa-api/part-3)
* [Node.js API Implementation (SPAs + API)](/docs/get-started/architecture-scenarios/spa-api/api-implementation-nodejs)
* [SPA Angular 2 Implementation (SPAs + API)](/docs/get-started/architecture-scenarios/spa-api/spa-implementation-angular2)
* [Conclusion (SPAs + API)](/docs/get-started/architecture-scenarios/spa-api/part-4)


# Node.js API Implementation  (SPAs + API)
Source: https://auth0.com/docs/get-started/architecture-scenarios/spa-api/api-implementation-nodejs

The Node.js implementation of the API for the SPA + API architecture scenario

# Node.js API Implementation (SPAs + API)

This document is part of the SPA + API Architecture Scenario and it explains how to implement the API in Node.js. Please refer to the scenario for information on the implemented solution.

The full source code for the Node.js API implementation can be found in [this GitHub repository](https://github.com/auth0-samples/auth0-pnp-exampleco-timesheets/tree/master/timesheets-api/node).

## Step 1. Define the API endpoints

We will use the [Express web application framework](http://expressjs.com/) to build our Node.js API.

### Create a package.json File

Create a folder for your API, navigate into it and run `npm init`. This will setup your `package.json` file.

You can leave the default settings or change them as you see fit.

Our sample's `package.json` looks like the following:

```json lines theme={null}
{
  "name": "timesheets-api",
  "version": "1.0.0",
  "description": "API used to add timesheet entries for employees and contractors",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/auth0-samples/auth0-pnp-timesheets.git"
  },
  "author": "Auth0",
  "license": "MIT",
  "bugs": {
    "url": "https://github.com/auth0-samples/auth0-pnp-timesheets/issues"
  },
  "homepage": "https://github.com/auth0-samples/auth0-pnp-timesheets#readme"
}
```

### Install the Dependencies

Next, we need to set our dependencies. We will use the following modules:

* **express**: This module adds the [Express web application framework](https://expressjs.com/).
* **cors**: This module adds support for enabling [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) which is required since the API will be called from a Single-Page Application running on a different domain inside a web browser.
* **jwks-rsa**: This library retrieves RSA signing keys from a JWKS (JSON Web Key Set) endpoint. Using `expressJwtSecret` we can generate a secret provider that will provide the right signing key to `express-jwt` based on the `kid` in the <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> header. For more information refer to the [node-jwks-rsa GitHub repository](https://github.com/auth0/node-jwks-rsa).
* **express-jwt**: This module lets you authenticate HTTP requests using JWT tokens in your Node.js applications. It provides several functions that make working with JWTs easier. For more information refer to the [express-jwt GitHub repository](https://github.com/auth0/express-jwt).
* **body-parser**: This is a Node.js body parsing middleware. It extracts the entire body portion of an incoming request stream and exposes it on `req.body` as something easier to interface with.For more information and several alternatives refer to the body-parser GitHub repository.

To install these dependencies run the following:

```bash wrap lines theme={null}
npm install express cors express-jwt jwks-rsa body-parser express-jwt-authz --save
```

### Implement the Endpoints

Navigate to your API directory and create a `server.js` file. Your code needs to:

* Get the dependencies.
* Implement the endpoint(s).
* Launch the API server.

This is our sample implementation:

```javascript lines theme={null}
const express = require('express');
const app = express();
const { expressjwt: jwt } = require('express-jwt');
const jwksRsa = require('jwks-rsa');
const cors = require('cors');
const bodyParser = require('body-parser');

// Enable CORS
app.use(cors());

// Enable the use of request body parsing middleware
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({
  extended: true
}));

// Create timesheets API endpoint
app.post('/timesheets', function(req, res){
  res.status(201).send({message: "This is the POST /timesheets endpoint"});
})

// Launch the API Server at localhost:8080
app.listen(8080);
```

Launch your API server using `node server` and make an HTTP POST request to `localhost:8080/timesheets`. You should see a JSON response with the message `This is the POST /timesheets endpoint`.

So now we have our endpoint but anyone can call it. Continue to the next paragraph to see how we can fix this.

## Step 2. Secure the API endpoints

In order to validate our token we will use the `jwt` function, provided by the [express-jwt middleware](https://github.com/auth0/express-jwt#usage), and the `jwks-rsa` to retrieve our secret. The libraries do the following:

1. `express-jwt` will decode the token and pass the request, the header and the payload to `jwksRsa.expressJwtSecret`.
2. `jwks-rsa` will then download all signing keys from the JWKS endpoint and see if a one of the signing keys matches the `kid` in the header of the JWT. If none of the signing keys match the incoming `kid`, an error will be thrown. If we have a match, we will pass the right signing key to `express-jwt`.
3. `express-jwt` will the continue its own logic to validate the signature of the token, the expiration, `audience` and the `issuer`.

The steps we will follow in our code are:

* Create the middleware function to validate the <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>.
* Enable the use of the middleware in our routes.

You can also write some code to actually save the timesheet to a database. This is our sample implementation (some code is omitted for brevity):

<AuthCodeBlock />

If we launch our server now and do an HTTP POST to `localhost:8080/timesheets` we should get the error message `Missing or invalid token` (which is perfectly fine since we didn’t send an Access Token in our request).

In order to test the working scenario as well we need to:

* Get an Access Token. For details on how to do so refer to: [Get an Access Token](/docs/get-started/architecture-scenarios/server-application-api#get-an-access-token).
* Invoke the API while adding an `Authorization` header to our request with the value `Bearer ACCESS_TOKEN` (where `ACCESS_TOKEN` is the value of the token we retrieved in the first step).

## Step 3. Check the application permissions

In this step we will add to our implementation the ability to check if the application has permissions (or `scope`) to use our endpoint in order to create a timesheet. In particular we want to ensure that the token has the correct scope, which is `batch:upload`.

In order to do this we will make use of the `express-jwt-authz` Node.js package, so go ahead and add that to your project:

```bash lines theme={null}
npm install express-jwt-authz --save
```

Now it is as simple as adding a call to `jwtAuthz(...)` to your middleware to ensure that the JWT contain a particular scope in order to execute a particular endpoint.

We will add an additional dependency. The **express-jwt-authz** library, which is used in conjunction with express-jwt, validates the [JWT](/docs/secure/tokens/json-web-tokens) and ensures it bears the correct permissions to call the desired endpoint. For more information refer to the [express-jwt-authz GitHub repository](https://github.com/auth0/express-jwt-authz).

This is our sample implementation (some code is omitted for brevity):

```javascript lines theme={null}
// set dependencies - some code omitted
const jwtAuthz = require('express-jwt-authz');

// Enable CORS - code omitted

// Create middleware for checking the JWT - code omitted

// Enable the use of request body parsing middleware - code omitted

// create timesheets API endpoint
app.post('/timesheets', checkJwt, jwtAuthz(['create:timesheets'], { customUserKey: 'auth' }), function(req, res){
  var timesheet = req.body;

  // Save the timesheet to the database...

  //send the response
  res.status(201).send(timesheet);
})

// launch the API Server at localhost:8080 - code omitted
```

If we invoke our API with a token that does not include this scope we should get the error message Forbidden with the HTTP status code `403`. You can test this by removing this scope from your API.

## Step 4. Determine the User Identity

The `express-jwt` middleware which is used to validate the JWT, also sets the `req.auth` with the information contained in the JWT. If you want to use the `sub` claim to identify the user uniquely, you can simply use `req.auth.sub`.

In the case of the timesheets application however, we want to use the email address of the user as the unique identifier.

The first thing we need to do is to write a rule which will add the email address of the user to the Access Token. Go to the [Rules section](https://manage.auth0.com/#/rules%7D) of the Dashboard and click on the **Create Rule** button.

You can give the rule a descriptive name, for example `Add email to Access Token`, and then use the following code for the rule:

```javascript lines theme={null}
function (user, context, callback) {
  const namespace = 'https://api.exampleco.com/';
  context.accessToken[namespace + 'email'] = user.email;
  callback(null, user, context);
}
```

The `namespace` is used to ensure the claim has a unique name and does not clash with the names of any of the standard OIDC claims. However, Auth0 supports namespaced and non-namespaced custom claims. For more info on custom claims, see [Create Custom Claims](/docs/secure/tokens/json-web-tokens/create-custom-claims).

Next, inside your API, you can retrieve the value of the claim from `req.auth`, and use that as the unique user identity which you can associate with timesheet entries.

```js lines theme={null}
app.get('/timesheets', checkJwt, jwtAuthz(['read:timesheets'], { customUserKey: 'auth' }), function(req, res) {
  var timesheet = req.body;

  // Associate the timesheet entry with the current user
  var userId = req.auth['https://api.exampleco.com/email'];
  timesheet.user_id = userId;

  // Save the timesheet to the database...

  //send the response
  res.status(201).send(timesheet);
});
```


# Solution Overview (SPAs + API)
Source: https://auth0.com/docs/get-started/architecture-scenarios/spa-api/part-1

Solution overview for the SPA + API architecture scenario

In order to ensure that only authorized users and applications are allowed access to the Timesheets API, ExampleCo has decided to make use of the [OAuth 2.0 authorization framework](https://tools.ietf.org/html/rfc6749). The framework provides the flexibility the company wants since the different grants can allow them to easily authorize the various types of applications which need to communicate with the Timesheets API.

## API Authentication and Authorization

An API is a way to expose functionality of your application to other applications. An application can make a request by sending a message to an endpoint on an API and receive information as a response.

An API endpoint can be secured or not. In our case, since the timesheets are sensitive information that affect reviews and payments, it is important to ensure that only authorized users and applications can call the endpoints on our API. When a client application wants to access protected endpoints on an API, it needs to present an <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> as proof that it has the required permissions for making the call to the endpoint.

An Access Token is obtained by authenticating the user with an <Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip> and the user can then, in turn, authorize the application to access the API on their behalf.

<Card title="What is an Access Token?">
  An Access Token (also referred to as `access_token`) is an opaque string representing an authorization issued to the application. It may denote an identifier used to retrieve the authorization information or may self-contain the authorization information (for example, the user's identity, permissions, and so forth) in a verifiable manner.

  It is quite common for Access Tokens to be implemented as [JSON Web Tokens](/docs/secure/tokens/json-web-tokens).

  For more information on Auth0 Access Tokens refer to [Access Token](/docs/secure/tokens/access-tokens).
</Card>

An API can enforce fine-grained control over who can access the various endpoints exposed by the API. These permissions are expressed as scopes.

When a user authorizes a client application, the application can also indicate which permissions it requires. The user is then allowed to review and grant these permissions. These permissions are then included in the Access Token as part of the `scope` claim.

Subsequently, when the client passes along the Access Token when making requests to the API, the API can inspect the `scope` claim to ensure that the required permissions were granted in order to call the particular API endpoint.

<Card title="What are Scopes?">
  Each Access Token may include a list of the permissions that have been granted to the client. When a client authenticates with Auth0, it will specify the list of scopes (or permissions) it is requesting. If those scopes are authorized, then the Access Token will contain a list of authorized scopes.

  For example, the timesheet API may accept four different levels of authorization: reading timesheets (scope `read:timesheets`), creating timesheets (scope `create:timesheets`), deleting timesheets (scope `delete:timesheets`) and approving timesheets (scope `approve:timesheets`).

  When a client asks the API to create a new timesheet entry, then the Access Token should contain the `create:timesheets` scope. In a similar fashion, in order to delete existing timesheets, the Access Token should contain the `delete:timesheets` scope.

  For more information on scopes refer to [Scopes](/docs/get-started/apis/scopes).
</Card>

By using the <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> authorization framework, you can give your own applications or third-party applications limited access to your APIs on behalf of the application itself. Using Auth0, you can easily support different flows in your own APIs without worrying about the OAuth 2.0/<Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) specification, or the many other technical aspects of API authorization.

<Card title="OAuth roles">
  In any OAuth 2.0 flow we can identify the following roles:

  * **Resource Owner**: the entity that can grant access to a protected resource. Typically this is the end-user.
  * **Resource Server**: the server hosting the protected resources. This is the API you want to access.
  * **Client**: an application requesting access to a protected resource on behalf of the Resource Owner.
  * **Authorization Server**: the server that authenticates the Resource Owner, and issues Access Tokens after getting proper authorization. In this case, Auth0's Authentication API.

  [Grants types (or flows)](/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use) determine how these participants interact to grant to the applications limited access to the APIs you are building. As a result, the app will obtain an access token that can be used to call the API on behalf of the user.
</Card>

## Implicit Grant

OAuth 2.0 provides several **grant types** for different use cases. In this particular use case, we want to access the API from a [client-side app](/docs/quickstart/spa).

The SPA will use the [Implicit Flow (Implicit Grant)](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post) to do so.

The Implicit Grant (defined in [RFC 6749, section 4.1](https://tools.ietf.org/html/rfc6749#section-4.2)) is similar to the grant used in the [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow), but the main difference is that the application receives an Access Token directly, without the need for an `authorization_code`. This happens because the application, which is typically a JavaScript app running within a browser, is less trusted than a web app running on the server, hence cannot be trusted with the `client_secret` (which is required in the Authorization Code Grant).

Once the user authenticates, the application receives the <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip> and Access Token in the hash fragment of the URI. The application can now use the ID Token to obtain information about the user, and Access Token to call the API on behalf of the user.

1. The app initiates the flow and redirects the browser to Auth0 (specifically to the [/authorize endpoint](https://auth0.com/docs/api/authentication#implicit-grant)), so the user can authenticate.
2. Auth0 authenticates the user. The first time the user goes through this flow, and if the application is a third party application, a consent page will be shown where the permissions, that will be given to the Client, are listed (for example, post messages, list contacts, and so forth).
3. Auth0 redirects the user to the app with an Access Token (and optionally an ID Token) in the hash fragment of the URI. The app can now extract the tokens from the hash fragment.
4. The app can use the Access Token to call the API on behalf of the user.

## Authorization Extension

The [Auth0 Authorization Extension](/docs/customize/extensions/authorization-extension) allows you to configure Roles, Groups, and Permissions, and assign them to Users.

* The Permissions are actions that someone can do. For ExampleCo's business needs, we will configure four Permissions: read, create, delete and approve timesheets.
* The Roles are collections of Permissions. ExampleCo's timesheets app will be used by two kinds of users (employees and managers), with different permissions each, so we will configure two Roles: employee and manager.

Since this covers our business case we will not create any Groups.

The Authorization Extension will create a [Rule](/docs/customize/rules) which will read the Roles, Groups, and Permissions assigned to a user and add this information to the [User profile](/docs/customize/rules#rule-syntax) during the authentication flow. We can use this information to ensure that the Access Token issued to a user only contains scopes which are allowed. We can later on proceed to customize our app, like disabling the Approve Timesheets functionality if the user does not have the required permission to do so.


# Auth0 Configuration (SPAs + API)
Source: https://auth0.com/docs/get-started/architecture-scenarios/spa-api/part-2

Auth0 Configuration for the SPA + API architecture scenario

In this section we will review all the configurations we need to apply at the [Auth0 Dashboard](https://manage.auth0.com/#).

## Create the API

Navigate to the [APIs section](https://manage.auth0.com/#/apis) of the dashboard, and click the **Create API** button.

You will be asked to supply the following details for your API:

* **Name**: a friendly name for the API. Does not affect any functionality.
* **Identifier**: a unique identifier for the API. We recommend using a URL but note that this doesn't have to be a publicly available URL, Auth0 will not call your API at all. This value cannot be modified afterwards.
* **<Tooltip href="/docs/glossary?term=Signing+Algorithm">Signing Algorithm</Tooltip>**: the algorithm to sign the tokens with. The available values are `HS256` and `RS256`. When selecting RS256 the token will be signed with the tenant's private key. To learn more about signing algorithms, see [Signing Algorithms](/docs/get-started/applications/signing-algorithms).

<Frame>
  <img alt="Dashboard - Applications - APIs - Create API - Popup" />
</Frame>

Fill in the required information and click the **Create** button.

## Configure the Scopes

Once the application has been created you will need to configure the Scopes which applications can request during authorization.

In the settings for your API, go to the Permissions tab. In this section you can add the scopes for our business case: `read:timesheets`, `create:timesheets`, `delete:timesheets`, and `approve:timesheets`.

<Frame>
  <img alt="Dashboard - Applications - APIs - Permissions" />
</Frame>

## Create the Application

There are four application types in Auth0:

* **Native App** (used by mobile or desktop apps),
* **Single-Page Web App**,
* **Regular Web App** and
* **Machine to Machine App** (used by CLIs, Daemons, or services running on your backend).

For this scenario we want to create a new Application for our SPA, hence we will use Single-Page Application as the application type.

To create a new Application, navigate to the [dashboard](https://manage.auth0.com/#) and click on the [Applications](https://manage.auth0.com/#/applications) menu option on the left. Click the **+ Create Application** button.

Set a name for your Application (we will use `Timesheets SPA`) and select `Single-Page Web App` as the type.

Click **Create**.

That's it for now. When we are done with the SPA implementation we will revisit the dashboard and this Application's settings to make some changes in its configuration.

## Configure the Authorization Extension

You will need to ensure that the Authorization Extension is installed for your tenant. You can refer to the [Authorization Extension documentation](/docs/customize/extensions/authorization-extension) for details on how to do this.

### Define Permissions

You will now define the required Permissions, according to the scopes you have already defined: `read:timesheets`, `create:timesheets`, `delete:timesheets`, and `approve:timesheets`.

In the Authorization Extension, click the **Permissions** tab, and then click on the **Create Permission** button.

In the dialog, capture the details for each permission.

Ensure that the name of the permission is exactly the same as the corresponding scope:

<Frame>
  <img alt="Dashboard - Extensions - Authorization Extension - Create Permission" />
</Frame>

Proceed to create the permissions for all the remaining scopes:

### Define Roles

Next let's configure the two Roles: employee and manager.

Head over to the **Roles** tab, click the **Create Role** button, and select the **Timesheets SPA** application.

Set the **Name** and **Description** to `Employee`, and select the `delete:timesheets`, `create:timesheets` and `read:timesheets` permissions. Click on **Save**.

Next, follow the same process to create a `Manager` role, and ensure that you have selected all the permissions.

### Assign Users to Roles

You need to assign all users to either the `Manager` or the `Employee` role.

You can do this by going to the **Users** tab in the Authorization Extension and selecting a user.

On the user information screen, go to the **Roles** tab. Click **Add Role to User**, and select the appropriate role.

### Configuring the Authorization Extension

You will also need to ensure that the Rule for the Authorization Extension is published.

To do so, click on your user avatar in the top right of the Authorization Extension, and select **Configuration**.

Make sure that **Permissions** are enabled and then click **Publish Rule**.

### Create a Rule to validate token scopes

The final step in this process is to create a Rule to check if the scopes contained in an <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> are valid based on the permissions assigned to the user. Any scopes which are not valid for a user should be removed from the Access Token.

In your <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, go to the **Rules** tab. You should see the Rule created by the Authorization Extension. Click on the **Create Rule** button and select the **Empty Rule** template. You can give the Rule a name, such as **Access Token Scopes**, and then specify the following code for the Rule:

```javascript lines theme={null}
function (user, context, callback) {
  var permissions = user.permissions || [];
  var requestedScopes = context.request.body.scope || context.request.query.scope;
  var filteredScopes = requestedScopes.split(' ').filter( function(x) {
    return x.indexOf(':') < 0;
  });

  var allScopes = filteredScopes.concat(permissions);
  context.accessToken.scope = allScopes.join(' ');

  callback(null, user, context);
}
```

The code above will ensure that all Access Tokens will only contain the properly-formatted scopes (e.g., `action:area` or `delete:timesheets`) which are valid according to a user's permissions. Once you are done you can click on the **Save** button.

Rules execute in the order they are displayed on the Rules page, so ensure that the new rule you created is positioned below the rule for the Authorization Extension, so it executes after the Authorization Extension rule.


# API and SPA Configuration (SPAs + API)
Source: https://auth0.com/docs/get-started/architecture-scenarios/spa-api/part-3

API and SPA Configuration for the SPA + API architecture scenario

In this section we will see how we can implement an API for our scenario.

<Callout icon="file-lines">
  For simplicity, we will keep our implementation solely focused on authentication and authorization. As you will see in the samples, the input timesheet entry will be hard-coded, and the API will not persist the timesheet entry. Instead, it will simply echo back some of the info.
</Callout>

## Define the API endpoints

First we need to define the endpoints of our API.

<Card title="What is an API endpoint?">
  An **API endpoint** is a unique URL that represents an object. To interact with this object, you need to point your application to its URL. For example, if you had an API that could return either orders or customers, you might configure two endpoints: `/orders` and `/customers`. Your application would interact with these endpoints using different HTTP methods; for example, `POST /orders` could create a new order or `GET /orders` could retrieve the dataset of one or more orders.
</Card>

For this implementation we will only define 2 endpoints; one for retrieving a list of all timesheets for an employee, and another which will allow an employee to create a new timesheet entry.

An `HTTP GET` request to the `/timesheets` endpoint will allow a user to retrieve their timesheets, and an `HTTP POST` request to the `/timesheets` endpoint will allow a user to add a new timesheet.

**See the implementation in** [**Node.js**](/docs/get-started/architecture-scenarios/spa-api/api-implementation-nodejs#1-define-the-api-endpoints).

### Secure the Endpoints

When an API receives a request with a bearer <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> as part of the header, the first thing to do is to validate the token. This consists of a series of steps, and if any of these fails then the request must be rejected with a `Missing or invalid token` error message to the calling app.

The validations that the API should perform are:

* Check that the <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> is well formed
* Check the signature
* Validate the standard claims

<Callout icon="file-lines">
  [JWT.io](https://jwt.io/) provides a list of libraries that can do most of the work for you: parse the JWT, verify the signature and the claims.
</Callout>

Part of the validation process is to also check the Application permissions (scopes), but we will address this separately in the next paragraph of this document.

For more information on validating Access Tokens, see [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens).

**See the implementation in** [**Node.js**](/docs/get-started/architecture-scenarios/spa-api/api-implementation-nodejs#2-secure-the-api-endpoints).

### Check the Application's Permissions

By now we have verified that the JWT is valid. The last step is to verify that the application has the permissions required to access the protected resources.

To do so, the API needs to check the [scopes](/docs/get-started/apis/scopes) of the decoded JWT. This claim is part of the payload and it is a space-separated list of strings.

**See the implementation in** [**Node.js**](/docs/get-started/architecture-scenarios/spa-api/api-implementation-nodejs#3-check-the-client-permissions).

### Determine user identity

For both endpoints (retrieving the list of timesheets, and adding a new timesheet) we will need to determine the identity of the user.

For retrieving the list of timesheets this is to ensure that we only return the timesheets belonging to the user making the request, and for adding a new timesheet this is to ensure that the timesheet is associated with the user making the request.

One of the standard JWT claims is the `sub` claim which identifies the principal that is the subject to the claim. In the case of the Implicit Grant flow this claim will contain the user's identity, which will be the unique identifier for the Auth0 user. You can use this to associate any information in external systems with a particular user.

You can also use a custom claim to add another attribute of the user - such as their email address - to the Access Token and use that to uniquely identify the user.

**See the implementation in** [**Node.js**](/docs/get-started/architecture-scenarios/spa-api/api-implementation-nodejs#4-determine-the-user-identity).

## Implement the SPA

In this section we will see how we can implement a SPA for our scenario.

### Authorize the user

To authorize the user we will be using the [auth0.js library](/docs/libraries/auth0js). You can initialize a new instance of the Auth0 application as follows:

<AuthCodeBlock />

You need to pass the following configuration values:

* **clientID**: The value of your Auth0 <Tooltip href="/docs/glossary?term=Client+Id">Client Id</Tooltip>. You can retrieve it from the Settings of your Application at the [Dashboard](https://manage.auth0.com/#/applications%7D).
* **domain**: The value of your Auth0 Domain. You can retrieve it from the Settings of your Application at the [Dashboard](https://manage.auth0.com/#/applications%7D).
* **responseType**: Indicates the Authentication Flow to use. For a SPA which uses the **Implicit Flow**, this should be set to `token id_token`. The `token` part, triggers the flow to return an Access Token in the URL fragment, while the `id_token` part, triggers the flow to return an <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip> as well.
* **<Tooltip href="/docs/glossary?term=audience">audience</Tooltip>**: The value of your API Identifier. You can retrieve it from the [Settings of your API](https://manage.auth0.com/#/apis%7D) at the Dashboard.
* **redirectUri**: The URL to which Auth0 should redirect to after the user has authenticated.
* **scope**: The [scopes](/docs/get-started/apis/scopes) which determine the information to be returned in the ID Token and Access Token. A scope of `openid profile` will return all the user profile information in the ID Token. You also need to request the scopes required to call the API, in this case the `read:timesheets create:timesheets` scopes. This will ensure that the Access Token has these scopes.

To initiate the authentication flow you can call the `authorize()` method:

```js lines theme={null}
auth0.authorize();
```

After the authentication, Auth0 will redirect back to the **redirectUri** you specified when configuring the new instance of the Auth0 application. At this point you will need to call the `parseHash()` method which parses a URL hash fragment to extract the result of an Auth0 authentication response.

The contents of the authResult object returned by parseHash depend upon which authentication parameters were used. It may include the following:

* **idToken**: An ID Token JWT containing user profile information
* **accessToken**: An Access Token for the API, specified by the **audience**.
* **expiresIn**: A string containing the expiration time (in seconds) of the Access Token.

Determine where best to [store the tokens](/docs/secure/security-guidance/data-security/token-storage). If your single-page app has a backend server at all, then tokens should be handled server-side using the [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow) or [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce).

If you have a single-page app (SPA) with no corresponding backend server, your SPA should request new tokens on login and store them in memory without any persistence. To make API calls, your SPA would then use the in-memory copy of the token.

For an example of how to handle sessions in SPAs, check out the [Handle Authentication Tokens](/docs/quickstart/spa/vanillajs#handle-authentication-tokens) section of the [JavaScript Single-Page App Quickstart](/docs/quickstart/spa/vanillajs).

**See the implementation in** [**Angular 2**](/docs/get-started/architecture-scenarios/spa-api/spa-implementation-angular2#2-authorize-the-user).

### Get the User Profile

<Card title="Extract info from the token">
  This section shows how to retrieve the user info using the Access Token and the [/userinfo endpoint](https://auth0.com/docs/api/authentication#get-user-info). To avoid this API call, you can just decode the ID Token [using a library](https://jwt.io/#libraries-io) (make sure you validate it first). If you need additional user information consider using [our Management API](https://auth0.com/docs/api/management/v2#!/Users/get_users_by_id) from your backend.
</Card>

The `client.userInfo` method can be called passing the returned `authResult.accessToken` in order to retrieve the user's profile information. It will make a request to the [/userinfo endpoint](https://auth0.com/docs/api/authentication#get-user-info) and return the `user` object, which contains the user's information, similar to the example below:

```json lines theme={null}
{
    "email_verified": "false",
    "email": "test@example.com",
    "clientID": "AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH",
    "updated_at": "2017-02-07T20:50:33.563Z",
    "name": "tester9@example.com",
    "picture": "https://gravatar.com/avatar/example.png",
    "user_id": "auth0|123456789012345678901234",
    "nickname": "tester9",
    "created_at": "2017-01-20T20:06:05.008Z",
    "sub": "auth0|123456789012345678901234"
}
```

You can access any of these properties in the callback function passed when calling the `userInfo` function:

```javascript lines theme={null}
const accessToken = authResult.accessToken;

auth0.client.userInfo(accessToken, (err, profile) => {
  if (profile) {
    // Get the user’s nickname and profile image
    var nickname = profile.nickname;
    var picture = profile.picture;
  }
});
```

**See the implementation in** [**Angular 2**](/docs/get-started/architecture-scenarios/spa-api/spa-implementation-angular2#3-get-the-user-profile).

### Display UI Elements Conditionally Based on Scope

Based on the `scope` of the user, you may want to show or hide certain UI elements. To determine the scope issued to a user, you will need to store the scope which was initially requested during the authorization process. When a user is authorized, the `scope` will also be returned in the `authResult`.

If the `scope` in the `authResult` is empty, then all the scopes which was requested was granted. If the `scope` in the `authResult` is not empty, it means a different set of scopes were granted, and you should use the ones in `authResult.scope`.

**See the implementation in** [**Angular 2**](/docs/get-started/architecture-scenarios/spa-api/spa-implementation-angular2#4-display-ui-elements-conditionally-based-on-scope).

### Call the API

To access secured resources from your API, the authenticated user's Access Token needs to be included in requests that are sent to it. This is accomplished by sending the Access Token in an `Authorization` header using the `Bearer` scheme.

**See the implementation in** [**Angular 2**](/docs/get-started/architecture-scenarios/spa-api/spa-implementation-angular2#5-call-the-api).

### Renew the Access Token

As a security measure, it is recommended that the lifetime of a user's Access Token be kept short. When you create an API in the <Tooltip href="/docs/glossary?term=Auth0+dashboard">Auth0 dashboard</Tooltip>, the default lifetime is `7200` seconds (2 hours), but this can be controlled on a per-API basis.

Once expired, an Access Token can no longer be used to access an API. In order to obtain access again, a new Access Token needs to be obtained.

Obtaining a new Access Token can be done by repeating the authentication flow, used to obtain the initial Access Token. In a SPA this is not ideal, as you may not want to redirect the user away from their current task to complete the authentication flow again.

In cases like this you can make use of [Silent Authentication](/docs/authenticate/login/configure-silent-authentication). Silent authentication lets you perform an authentication flow where Auth0 will only reply with redirects, and never with a login page. This does however require that the user was already logged in via [Single Sign-on (SSO)](/docs/authenticate/single-sign-on).

**See the implementation in** [**Angular 2**](/docs/get-started/architecture-scenarios/spa-api/spa-implementation-angular2#6-renew-the-access-token).


# Conclusion (SPAs + API)
Source: https://auth0.com/docs/get-started/architecture-scenarios/spa-api/part-4

Conclusion for the SPA + API architecture scenario

In this document we covered a simple scenario involving an API used by a Single-Page Application (SPA) to allow employees to capture their timesheets.

We learned about the Implicit Grant, what an <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> is, how to configure an API in Auth0, how to configure a SPA application to communicate securely with this API, how to define and secure our API endpoints, how to use the provided libraries to validate the Access Token and how to retrieve a new one from Auth0.

We started by describing the business case and the requirements and went on explaining how each requirement can be met and the thought process behind each choice that was made.

We used Node.js for the API implementation and Angular for the SPA. Hopefully though after going through this document you are able to build this using the technologies you prefer.


# SPA Angular 2 Implementation (SPAs + API)
Source: https://auth0.com/docs/get-started/architecture-scenarios/spa-api/spa-implementation-angular2

The Angular 2 implementation of the SPA for the SPA + API architecture scenario

This document is part of the SPA + API Architecture Scenario and it explains how to implement the SPA in Angular 2. Please refer to the scenario for information on the implemented solution.

The full source code for the Angular 2 implementation of the SPA can be found in [this GitHub repository](https://github.com/auth0-samples/auth0-pnp-exampleco-timesheets/tree/master/timesheets-spa/angular).

## Step 1. Configuration

Your application will require certain configuration information. Before carrying on with the rest of the implementation, create an `AuthConfig` interface which will contain various configuration values. Place this interface in a file called `auth0-variables.ts`.

```ts lines theme={null}
interface AuthConfig {
  clientID: string;
  domain: string;
  callbackURL: string;
  apiUrl: string;
}

export const AUTH_CONFIG: AuthConfig = {
  clientID: '',
  domain: '',
  callbackURL: 'http://localhost:4200/callback',
  apiUrl: ''
};
```

## Step 2. Authorize the User

### Create an Authorization Service

The best way to manage and coordinate the tasks necessary for user authentication is to create a reusable service. With the service in place, you'll be able to call its methods throughout your application. An instance of the `WebAuth` object from [auth0.js](/docs/libraries/auth0js) can be created in the service.

```jsx lines expandable theme={null}
import { Injectable } from '@angular/core';
import { AUTH_CONFIG } from './auth0-variables';
import { Router } from '@angular/router';
import 'rxjs/add/operator/filter';
import auth0 from 'auth0-js';

@Injectable()
export class AuthService {

  userProfile: any;
  requestedScopes: string = 'openid profile read:timesheets create:timesheets';

  auth0 = new auth0.WebAuth({
    clientID: AUTH_CONFIG.clientID,
    domain: AUTH_CONFIG.domain,
    responseType: 'token id_token',
    audience: AUTH_CONFIG.apiUrl,
    redirectUri: AUTH_CONFIG.callbackURL,
    scope: this.requestedScopes
  });

  constructor(public router: Router) {}

  public login(): void {
    this.auth0.authorize();
  }

  public handleAuthentication(): void {
    this.auth0.parseHash((err, authResult) => {
      if (authResult && authResult.accessToken && authResult.idToken) {
        window.location.hash = '';
        this.setSession(authResult);
        this.router.navigate(['/home']);
      } else if (err) {
        this.router.navigate(['/home']);
        console.log(err);
        alert('Error: <%= "${err.error}" %>. Check the console for further details.');
      }
    });
  }

  private setSession(authResult): void {
    // Set the time that the Access Token will expire at
    const expiresAt = JSON.stringify((authResult.expiresIn * 1000) + new Date().getTime());

    // If there is a value on the scope param from the authResult,
    // use it to set scopes in the session for the user. Otherwise
    // use the scopes as requested. If no scopes were requested,
    // set it to nothing
    const scopes = authResult.scope || this.requestedScopes || '';

    localStorage.setItem('access_token', authResult.accessToken);
    localStorage.setItem('id_token', authResult.idToken);
    localStorage.setItem('expires_at', expiresAt);
    localStorage.setItem('scopes', JSON.stringify(scopes));
  }

  public logout(): void {
    // Remove tokens and expiry time from localStorage
    localStorage.removeItem('access_token');
    localStorage.removeItem('id_token');
    localStorage.removeItem('expires_at');
    localStorage.removeItem('scopes');
    // Go back to the home route
    this.router.navigate(['/']);
  }

  public isAuthenticated(): boolean {
    // Check whether the current time is past the
    // Access Token's expiry time
    const expiresAt = JSON.parse(localStorage.getItem('expires_at'));
    return new Date().getTime() < expiresAt;
  }

  public userHasScopes(scopes: Array<string>): boolean {
    const grantedScopes = JSON.parse(localStorage.getItem('scopes')).split(' ');
    return scopes.every(scope => grantedScopes.includes(scope));
  }
}
```

The service includes several methods for handling authentication.

* **login**: calls `authorize` from auth0.js which initiates <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>
* **handleAuthentication**: looks for an authentication result in the URL hash and processes it with the `parseHash` method from auth0.js
* **setSession**: sets the user's <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip>, and a time at which the Access Token will expire
* **logout**: removes the user's tokens from browser storage
  isAuthenticated: checks whether the expiry time for the Access Token has passed

### Process the Authentication Result

When a user authenticates via Universal Login and is then redirected back to your application, their authentication information will be contained in a URL hash fragment. The `handleAuthentication` method in the `AuthService` is responsible for processing the hash.

Call `handleAuthentication` in your app's root component so that the authentication hash fragment can be processed when the app first loads after the user is redirected back to it.

```javascript lines theme={null}
// src/app/app.component.ts

import { Component } from '@angular/core';
import { AuthService } from './auth/auth.service';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})

export class AppComponent {

  constructor(public auth: AuthService) {
    auth.handleAuthentication();
  }
}
```

### Add the Callback Component

Using Universal Login means that users are taken away from your application to a page hosted by Auth0. After they successfully authenticate, they are returned to your application where a client-side session is set for them.

You can choose to have users return to any URL in your application that you like; however, it is recommended that you create a dedicated callback route to serve as a central location that the user will be returned to upon successful authentication. Having a single callback route is beneficial for two main reasons:

* It prevents the need to allowlist multiple (and sometimes unknown) callback URLs
* It serves as a place to show a loading indicator while your application sets the user's client-side session

Create a component named `CallbackComponent` and populate it with a loading indicator.

```jsx lines theme={null}
<!-- app/callback/callback.html -->

<div class="loading">
  <img src="/assets/loading.svg" alt="loading">
</div>
```

This example assumes some kind of loading spinner is available in an `assets` directory. See the downloadable sample for a demonstration.

After authentication, users will be taken to the `/callback` route for a brief time where they will be shown a loading indicator. During this time, their client-side session will be set, after which they will be redirected to the `/home` route.

## Step 3. Get the User Profile

<Card title="Extract info from the token">
  This section shows how to retrieve the user info using the Access Token and the [/userinfo endpoint](https://auth0.com/docs/api/authentication#get-user-info). Alternatively, you can just decode the ID Token [using a library](https://jwt.io/#libraries-io) (make sure you validate it first). The output will be the same. If you need additional user information consider using the [our Management API](https://auth0.com/docs/api/management/v2#!/Users/get_users_by_id).
</Card>

To obtain the user's profile, update the existing `AuthService` class. Add a `getProfile` function which will extract the user's Access Token from local storage, and then pass that call the `userInfo` function to retrieve the user's information.

```javascript lines theme={null}
// Existing code from the AuthService class is omitted in this code sample for brevity
@Injectable()
export class AuthService {
  public getProfile(cb): void {
    const accessToken = localStorage.getItem('access_token');
    if (!accessToken) {
      throw new Error('Access Token must exist to fetch profile');
    }

    const self = this;
    this.auth0.client.userInfo(accessToken, (err, profile) => {
      if (profile) {
        self.userProfile = profile;
      }
      cb(err, profile);
    });
  }
}
```

You can now simply call this function from any service where you want to retrieve and display information about the user.

For example you may choose to create a new component to display the user's profile information:

```jsx lines theme={null}
import { Component, OnInit } from '@angular/core';
import { AuthService } from './../auth/auth.service';

@Component({
  selector: 'app-profile',
  templateUrl: './profile.component.html',
  styleUrls: ['./profile.component.css']
})
export class ProfileComponent implements OnInit {

  profile: any;

  constructor(public auth: AuthService) { }

  ngOnInit() {
    if (this.auth.userProfile) {
      this.profile = this.auth.userProfile;
    } else {
      this.auth.getProfile((err, profile) => {
        this.profile = profile;
      });
    }
  }
}
```

The template for this component looks as follows:

```jsx lines theme={null}
<div class="panel panel-default profile-area">
  <div class="panel-heading">
    <h3>Profile</h3>
  </div>
  <div class="panel-body">
    <img src="{{profile?.picture}}" class="avatar" alt="avatar">
    <div>
      <label><i class="glyphicon glyphicon-user"></i> Nickname</label>
      <h3 class="nickname">{{ profile?.nickname }}</h3>
    </div>
    <pre class="full-profile">{{ profile | json }}</pre>
  </div>
</div>
```

## Step 4. Display UI Elements Conditionally Based on Scope

During the authorization process we already stored the actual scopes which a user was granted in the local storage. If the `scope` returned in the `authResult` is not empty, it means that a user was issued a different set of scopes than what was initially requested, and we should therefore use `authResult.scope` to determine the scopes granted to the user.

If the `scope` returned in `authResult` is issued is empty, it means the user was granted all the scopes that were requested, and we can therefore use the requested scopes to determine the scopes granted to the user.

Here is the code we wrote earlier for the `setSession` function that does that check:

```jsx lines theme={null}
private setSession(authResult): void {
  // Set the time that the Access Token will expire at
  const expiresAt = JSON.stringify((authResult.expiresIn * 1000) + new Date().getTime());

  // If there is a value on the `scope` param from the authResult,
  // use it to set scopes in the session for the user. Otherwise
  // use the scopes as requested. If no scopes were requested,
  // set it to nothing
  const scopes = authResult.scope || this.requestedScopes || '';

  localStorage.setItem('access_token', authResult.accessToken);
  localStorage.setItem('id_token', authResult.idToken);
  localStorage.setItem('expires_at', expiresAt);
  localStorage.setItem('scopes', JSON.stringify(scopes));
  this.scheduleRenewal();
}
```

Next we need to add a function to the `AuthService` class which we can call to determine if a user was granted a specific scope:

```jsx lines theme={null}
@Injectable()
export class AuthService {
  // some code omitted for brevity

  public userHasScopes(scopes: Array<string>): boolean {
    const grantedScopes = JSON.parse(localStorage.getItem('scopes')).split(' ');
    return scopes.every(scope => grantedScopes.includes(scope));
  }
}
```

You can call this method to determine whether we should display a specific UI element, or not. As an example we only want to display the **Approve Timesheets** link if the user has the `approve:timesheets` scope. Note in the code below that we added a call to the `userHasScopes` function to determine whether that link should be displayed or not.

```xml lines theme={null}
<nav class="navbar navbar-default">
  <div class="container-fluid">
    <div class="navbar-header">
      <a class="navbar-brand" href="#">Timesheet System</a>
    </div>
    <div class="navbar-collapse collapse">
      <ul class="nav navbar-nav">
        <li><a routerLink="/">Home</a></li>
        <li><a *ngIf="auth.isAuthenticated()" routerLink="/profile">My Profile</a></li>
        <li><a *ngIf="auth.isAuthenticated()" routerLink="/timesheets">My Timesheets</a></li>
        <li><a *ngIf="auth.isAuthenticated() && auth.userHasScopes(['approve:timesheets'])" routerLink="/approval">Approve Timesheets</a></li>
      </ul>
      <ul class="nav navbar-nav navbar-right">
        <li><a *ngIf="!auth.isAuthenticated()" href="javascript:void(0)" (click)="auth.login()">Log In</a></li>
        <li><a *ngIf="auth.isAuthenticated()" href="javascript:void(0)" (click)="auth.logout()">Log Out</a></li>
      </ul>
    </div>
  </div>
</nav>

<main class="container">
  <router-outlet></router-outlet>
</main>
```

### Protect a route

We should also protect a route to not allow a route to be navigated to if a user has not been granted the correct scopes. For this we can add a new `ScopeGuardService` service class:

```jsx lines theme={null}
import { Injectable } from '@angular/core';
import { Router, CanActivate, ActivatedRouteSnapshot } from '@angular/router';
import { AuthService } from './auth.service';

@Injectable()
export class ScopeGuardService implements CanActivate {

  constructor(public auth: AuthService, public router: Router) {}

  canActivate(route: ActivatedRouteSnapshot): boolean {

    const scopes = (route.data as any).expectedScopes;

    if (!this.auth.isAuthenticated() || !this.auth.userHasScopes(scopes)) {
      this.router.navigate(['']);
      return false;
    }
    return true;
  }

}
```

And then use that when we configure the routes to determine whether a route can be activated. Notice the use of the new `ScopeGuardService` in the definition for the `approval` route below:

```javascript lines theme={null}
// app.routes.ts

import { Routes, CanActivate } from '@angular/router';
import { HomeComponent } from './home/home.component';
import { ProfileComponent } from './profile/profile.component';
import { CallbackComponent } from './callback/callback.component';
import { AuthGuardService as AuthGuard } from './auth/auth-guard.service';
import { ScopeGuardService as ScopeGuard } from './auth/scope-guard.service';
import { TimesheetListComponent } from './timesheet-list/timesheet-list.component';
import { TimesheetAddComponent } from './timesheet-add/timesheet-add.component';
import { ApprovalComponent } from './approval/approval.component';

export const ROUTES: Routes = [
  { path: '', component: HomeComponent },
  { path: 'profile', component: ProfileComponent, canActivate: [AuthGuard] },
  { path: 'callback', component: CallbackComponent },
  { path: 'timesheets/add', component: TimesheetAddComponent, canActivate: [AuthGuard] },
  { path: 'timesheets', component: TimesheetListComponent, canActivate: [AuthGuard] },
  { path: 'approval', component: ApprovalComponent, canActivate: [ScopeGuard], data: { expectedScopes: ['approve:timesheets']} },
  { path: '**', redirectTo: '' }
];
```

## Step 5. Call the API

The [angular2-jwt](https://github.com/auth0/angular2-jwt) module can be used to automatically attach <Tooltip href="/docs/glossary?term=JSON+Web+Tokens">JSON Web Tokens</Tooltip> to requests made to your API. It does this by providing an `AuthHttp` class which is a wrapper over Angular's `Http` class.

Install `angular2-jwt`:

```bash lines theme={null}
# installation with npm
npm install --save angular2-jwt

# installation with yarn
yarn add angular2-jwt
```

Create a factory function with some configuration values for `angular2-jwt` and add it to the `providers` array in your application's `@NgModule`. The factory function should have a `tokenGetter` function which fetches the `access_token` from local storage.

```jsx lines theme={null}
import { Http, RequestOptions } from '@angular/http';
import { AuthHttp, AuthConfig } from 'angular2-jwt';

export function authHttpServiceFactory(http: Http, options: RequestOptions) {
  return new AuthHttp(new AuthConfig({
    tokenGetter: (() => localStorage.getItem('access_token'))
  }), http, options);
}

@NgModule({
  declarations: [...],
  imports: [...],
  providers: [
    AuthService,
    {
      provide: AuthHttp,
      useFactory: authHttpServiceFactory,
      deps: [Http, RequestOptions]
    }
  ],
  bootstrap: [...]
})
```

After `angular2-jwt` is configured, you can use the `AuthHttp` class to make secure calls to your API from anywhere in the application. To do so, inject `AuthHttp` in any component or service where it is needed and use it just as you would use Angular's regular `Http` class.

```jsx lines theme={null}
import { Injectable } from '@angular/core';
import { Http } from '@angular/http';
import { AuthHttp } from 'angular2-jwt';
import 'rxjs/add/operator/map';
import { NewTimesheetModel } from '../models/new-timesheet-model';

@Injectable()
export class TimesheetsService {

  constructor(public authHttp: AuthHttp) { }

  addTimesheet(model: NewTimesheetModel) {
    return this.authHttp.post('http://localhost:8080/timesheets', JSON.stringify(model));
  }

  getAllTimesheets() {
    return this.authHttp.get('http://localhost:8080/timesheets')
      .map(res => res.json())
  }
}
```

## Step 6. Renew the Access Token

Renewing the user's Access Token requires to update the Angular SPA. Add a method to the `AuthService` which calls the `checkSession` method from auth0.js. If the renewal is successful, use the existing `setSession` method to set the new tokens in local storage.

```ts lines theme={null}
public renewToken() {
  this.auth0.checkSession({
    audience: AUTH_CONFIG.apiUrl
  }, (err, result) => {
    if (!err) {
      this.setSession(result);
    }
  });
}
```

In the `AuthService` class, add a method called `scheduleRenewal` to set up a time at which authentication should be silently renewed. In the sample below this is set up to happen 30 seconds before the actual token expires. Also add a method called `unscheduleRenewal` which will unsubscribe from the Observable.

```ts lines expandable theme={null}
public scheduleRenewal() {
  if (!this.isAuthenticated()) return;

  const expiresAt = JSON.parse(window.localStorage.getItem('expires_at'));

  const source = Observable.of(expiresAt).flatMap(
    expiresAt => {

      const now = Date.now();

      // Use the delay in a timer to
      // run the refresh at the proper time
      var refreshAt = expiresAt - (1000 * 30); // Refresh 30 seconds before expiry
      return Observable.timer(Math.max(1, refreshAt - now));
    });

  // Once the delay time from above is
  // reached, get a new JWT and schedule
  // additional refreshes
  this.refreshSubscription = source.subscribe(() => {
    this.renewToken();
  });
}

public unscheduleRenewal() {
  if (!this.refreshSubscription) return;
  this.refreshSubscription.unsubscribe();
}
```

Finally you need to initiate the schedule renewal. This can be done by calling `scheduleRenewal` inside your `AppComponent` which will happen when the page is loaded. This will occur after every authentication flow, either when the user explicitly logs in, or when the silent authentication happens.

<Info>
  ### Refresh Token Rotation

  Recent advancements in user privacy controls in browsers adversely impact the user experience by preventing access to third-party cookies. Auth0 recommends using [Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation), which provides a secure method for using refresh tokens in SPAs while providing end-users with seamless access to resources without the disruption in UX caused by browser privacy technology like ITP.
</Info>


# Auth0 for AI Agents
Source: https://auth0.com/docs/get-started/auth0-for-ai-agents

Learn how to leverage Auth0 for AI Agents to secure every layer of your GenAI stack.

Generative AI (GenAI) applications powered by large language models (LLMs) and AI agents are changing how users interact with software. As developers integrate AI capabilities that handle login, data access, and tool execution into their applications, securing these interactions becomes critical.

Auth0 for AI Agents leverages Auth0’s robust identity and access management (IAM) platform to secure every layer of your GenAI stack. It provides comprehensive, enterprise-grade security for:

* **Human users:** Ensure only authorized individuals can interact with AI models and applications.
* **AI agents:** Control autonomous AI agent access to external APIs using <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> scopes.
* **External APIs and tools:** Securely connect AI agents to Google, Slack, GitHub, and more. Auth0 automatically refreshes and exchanges tokens without user intervention.
* **Sensitive data:** Enforce granular, least-privilege permissions to protect sensitive data from unauthorized AI agent access.

To start building with Auth0 for AI Agents, read the [Auth0 for AI Agents documentation](https://auth0.com/ai/docs).

## Use cases

Auth0 for AI Agents empowers developers to build and deploy secure AI-powered applications with:

* **Seamless integrations:** Integrates out-of-the-box with popular AI frameworks like LangChain, LlamaIndex, and the Vercel AI SDK.
* **Comprehensive security controls:** Secures authentication flows with OAuth 2.0 and <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect and manages access for both human users and AI agents.
* **Asynchronous authorization:** Enables human-in-the-loop controls for critical actions.
* **<Tooltip href="/docs/glossary?term=Fine-grained+authorization">Fine-grained authorization</Tooltip> for RAG:** Enforces granular access control within Retrieval Augmented Generation (RAG) pipelines.

### User authentication

Leverage OAuth 2.0 and OpenID Connect to securely authenticate users with [Universal Login](/docs/authenticate/login/auth0-universal-login). With [Client-Initiated Account Linking](https://auth0.com/ai/docs/client-initiated-account-linking), AI agents can request access and connect to multiple <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> on the user’s behalf through Auth0.

### Call APIs on users’ behalf

Using [Token Vault](/docs/secure/tokens/token-vault), AI agents can fetch <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> for external identity providers to call their APIs, all through a single Auth0 integration. For example, you can use Token Vault to:

1. Authenticate a user with an external identity provider like Google.
2. Use OAuth scopes to authorize access to the Google Calendar API.
3. Get an access token to call the Google Calendar API to schedule a meeting.

Auth0 for AI Agents supports the following social, enterprise, and custom identity providers:

* Google
* Microsoft
* Box
* Slack
* GitHub
* OpenID Connect
* Custom connection

### Asynchronous authorization

Add human-in-the-loop controls for critical or delayed actions using secure protocols, such as:

* [Client-Initiated Backchannel Authentication (CIBA)](/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow): Enables AI agents to asynchronously implement secure backchannel authentication and <Tooltip href="/docs/glossary?term=authorization+flows">authorization flows</Tooltip> when user approval is required before taking an action.
* [Rich Authorization Requests (RAR)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-rar): Enhance security by requesting specific authorization permissions for users to approve through push notifications.

### Authorization for RAG

Use [Auth0 FGA](https://docs.fga.dev/) to enforce document and relationship-level access control in your Retrieval Augmented Generation (RAG) pipelines:

* Document-level access control: Performs granular permission checks on RAG data sources.
* Relationship-Based Access Control (ReBAC): Replaces broad roles with precise, fine-grained relationship-based access control decisions.
* Compliance support: Ensures only authorized data is retrieved for data privacy and regulatory compliance.

## AI Framework Integrations

Auth0 for AI Agents integrates out-of-the-box with leading [GenAI frameworks and tools](https://auth0.com/ai/docs/sdks), such as:

* LangChain
* LlamaIndex
* Vercel AI SDK
* GenKit
* Cloudflare Agents
* [Cloudflare Model Context Protocol (MCP) Servers](https://auth0.com/ai/docs/cloudflare-mcp)

## Next steps

Ready to start building? Explore our [quickstarts](https://auth0.com/ai/docs/get-started), [how-tos](https://auth0.com/ai/docs/how-tos), and [SDKs](https://auth0.com/ai/docs/sdks) in the Auth0 for AI Agents documentation.


# Auth0 Guide
Source: https://auth0.com/docs/get-started/auth0-guide

Learn about Auth0 Guide, an AI-powered chatbot that answers your questions about Auth0.

<Callout icon="file-lines">
  Guide is currently in Early Access and is being rolled out to users in the US Public Cloud region. As Guide may occasionally provide incomplete or inaccurate responses, always [review and validate](#how-does-guide-avoid-ai-hallucinations%3F) them using the provided links. To learn more about Auth0 releases, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Callout>

Guide is an AI-powered chatbot that answers your questions about Auth0. It sources information from our [Documentation](https://auth0.com/docs), [Blog](https://auth0.com/blog), and [Community](http://community.auth0.com). For Enterprise subscription customers, Guide also leverages Auth0 tenant data from [Security Center](/docs/secure/security-center) to help you monitor, troubleshoot, and implement tenant security best practices.

Guide answers your questions, such as "How do I set up passkeys?" with a summarized answer and links to relevant documentation and [incident playbooks](/docs/secure/attack-protection/playbooks) for tenant and user security.

## How Guide works

Guide processes your message to determine what you’re asking for, searches Auth0 sources for relevant information, then generates a summarized response based on what it found along with links to the referenced materials.

You can ask follow-up questions, [validate its responses](#how-does-guide-avoid-ai-hallucinations%3F) using the provided links, and give feedback on Guide by rating its responses.

For Enterprise subscription customers: If you [configure security monitoring alerts](/docs/secure/security-center/security-alerts) in Security Center, Guide helps you troubleshoot incidents and suggests security guidance from a relevant [incident playbook](/docs/secure/attack-protection/playbooks).

For example, as shown in the following screenshot, when a significant bot surge triggers your <Tooltip href="/docs/glossary?term=Bot+Detection">Bot Detection</Tooltip> alert, Guide recommends remediation steps from the [Bot Detection Attack playbook](/docs/secure/attack-protection/playbooks/bot-detection-playbook), such as activating CAPTCHA for affected authentication flows, and prompts you to inspect relevant events in the tenant logs.

<Frame>
  <img alt="" />
</Frame>

## Use Guide

You can access Guide by selecting the **Ask Guide** button in the top-right corner of the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

When you select **Ask Guide**, Guide pops up, prompting you to ask about Auth0 features. It may suggest questions relevant to your current location in the Auth0 Dashboard. For example, if you’re under **Branding > <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>**, Guide will prompt you with questions about Universal Login, such as:

* What is Universal Login?
* What are the Benefits of Universal Login?

<Frame>
  <img alt="Select the Ask Guide button in the top-right corner of the Auth0 Dashboard to open it." />
</Frame>

### Questions Guide can answer

Guide can answer questions that relate to the Auth0 product and platform, such as:

* What is Universal Login?
* How do I enable <Tooltip href="/docs/glossary?term=single+sign-on">single sign-on</Tooltip> integrations?
* How do I set up passkeys?

<Frame>
  <img alt="Guide can answer questions that relate to the Auth0 product and platform." />
</Frame>

For Enterprise subscription customers, Guide can answer Auth0 tenant-related questions pertaining to Security Center metrics and data, such as:

* How do I troubleshoot this failed <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> challenge?
* What triggered my bot protection alert threshold?
* What are the remediation steps for a "credential stuffing" alert?

### Questions Guide cannot answer

Guide cannot answer questions that do not relate to the Auth0 product or platform, or are specific to your tenant or configuration, such as:

* What connections do I have enabled?
* How many users logged in to my application last month?
* Which is better? Vim or Emacs?

<Warning>
  Do not submit personal or other sensitive data to Guide.
</Warning>

## Disable Guide

You can disable Guide in your tenant by contacting [Auth0 Support](https://support.auth0.com/).

## Data security in Guide

Your messages are safeguarded by Okta’s enterprise-grade security and compliance standards.

Guide does:

* Use provided messages to search public Auth0 sources for relevant information.

Guide does not:

* Access your account or tenant data.
* Use provided messages for LLM training purposes.
* Share your messages with third parties.

## How does Guide avoid AI hallucinations?

Guide builds responses using content authored by Auth0 and includes links to the documents referenced in all responses. You can follow any referenced link to verify the original source data and learn additional information.


# Auth0 Model Context Protocol (MCP) Server
Source: https://auth0.com/docs/get-started/auth0-mcp-server

Learn how to integrate Auth0 with Model Context Protocol (MCP).

The Auth0 Model Context Protocol (MCP) Server connects AI agents to your Auth0 tenant, allowing them to perform complex, multi-step operations in Auth0 such as creating applications, managing users, or deploying Actions. It leverages the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), a standardized protocol that enables AI agents to communicate with external tools and APIs to execute tasks on your behalf.

Designed for developers who use AI-powered tools like Cursor, Windsurf, or Claude Desktop, the Auth0 MCP Server transforms how developers manage their identity infrastructure, making it faster and easier to work with Auth0 services.

<Frame>
  <img alt="Auth0 Model Context Protocol (MCP) Server allows you to use natural language commands to manage your identity infrastructure through simple conversations with AI clients. " />
</Frame>

## Authentication and credential security

Auth0 MCP Server prioritizes robust security by managing authentication, validating requests, and ensuring secure communication with the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. This includes:

* [OAuth 2.0 Device Authorization Flow](/docs/get-started/authentication-and-authorization-flow/device-authorization-flow): Securely authenticates requests with Auth0.
* [Secure credential storage](/docs/get-started/applications/rotate-credentials): Credentials are securely stored in your system's keychain and never exposed in plain text.
* [Minimal API permissions](/docs/secure/tokens/access-tokens/management-api-access-tokens): Only essential permissions are requested, adhering strictly to the principle of least privilege.

<Frame>
  <img alt="See the full end-to-end authentication flow for Auth0 Model Context Protocol Server." />
</Frame>

## Supported tools and integrations

Auth0 MCP Server currently integrates with the following [MCP clients](https://modelcontextprotocol.io/clients), including:

* [Claude Desktop](https://claude.ai/download)
* [Cursor](https://www.cursor.com/downloads)
* [Windsurf](https://www.windsurf.com/editor)

Additional integrations will be added as major new clients emerge. For a complete list of supported tools and detailed functionality, please refer to our [Auth0 Model Context Protocol (MCP) Server Tools Reference](/docs/get-started/auth0-mcp-server/auth0-mcp-tools-reference).

## Next Steps

Ready to get started? Visit our [Getting Started with Auth0 Model Context Protocol (MCP) Server guide](/docs/get-started/auth0-mcp-server/getting-started-with-auth0-mcp-server) to begin integrating Auth0 MCP Server into your workflow. For developers interested in deeper insights or contributing, check out [our repository on GitHub](https://github.com/auth0/auth0-mcp-server).


# Auth0 Model Context Protocol (MCP) Server Guides
Source: https://auth0.com/docs/get-started/auth0-mcp-server/auth0-mcp-server-guides

Learn about common operations and use cases for Auth0 Model Context Protocol (MCP) Server.

Learn about common operations and use cases for Auth0 Model Content Protocol (MCP) Server. Below are the guides currently available:

[Streamline API Authorization Flows with Auth0 Model Context Protocol (MCP) Server](/docs/get-started/auth0-mcp-server/auth0-mcp-server-guides/streamline-api-authorization-flows-with-auth0-model-context-protocol-mcp)

[Implement Advanced Security Monitoring with Auth0 Model Context Protocol (MCP) Server](/docs/get-started/auth0-mcp-server/auth0-mcp-server-guides/implement-advanced-security-monitoring-with-auth0-model-context-protocol-mcp)


# Implement Advanced Security Monitoring with Auth0 Model Context Protocol (MCP) Server
Source: https://auth0.com/docs/get-started/auth0-mcp-server/auth0-mcp-server-guides/implement-advanced-security-monitoring-with-auth0-model-context-protocol-mcp

Leverage Auth0 Model Context Protocol (MCP) Server and Claude to implement a sophisticated security monitoring and automated response system.

<Card title="Overview">
  Learn how to:

  1. Set up advanced log monitoring for security threats
  2. Create intelligent security actions that respond to suspicious activities
  3. Implement adaptive authentication challenges based on risk assessment
  4. Configure automated notifications for security events
  5. Fine-tune your security system based on real-world data
</Card>

<Card title="Before you start">
  1. Create an Auth0 account with administrative access
  2. Install Auth0 MCP Server and integrate with Claude Desktop
</Card>

Leverage [Auth0 MCP Server](/docs/get-started/auth0-mcp-server) and [Claude](https://claude.ai/) to implement a sophisticated security monitoring and automated response system for your Auth0 tenant. Using natural language interactions, you can quickly set up security measures that would typically require complex scripting and dashboard navigation.

### Step 1: Set up advanced log monitoring

The first step in building a security monitoring system is to understand what normal authentication patterns look like in your environment. With Auth0 MCP Server, you can quickly analyze your logs to establish this baseline.

Ask Claude:

```bash wrap lines theme={null}
Analyze my Auth0 logs from the past week to identify normal authentication patterns. Look for common IP ranges, devices, browsers, and time-of-day patterns.
```

Claude will use the `auth0_search_logs` tool to retrieve and analyze your logs. This analysis gives you a baseline understanding of normal authentication patterns, which is essential for identifying anomalies.

### Step 2: Create security detection Actions

Now that you understand normal patterns, you can create Actions that detect suspicious activities. Instead of writing complex code manually, you can describe the security rules in natural language.

Ask Claude:

```bash lines theme={null}
Create an action that detects the following suspicious activities:
1. Multiple failed login attempts within a short time period
2. Logins from unusual geographic locations for a user
3. Logins at unusual times based on the user's history
4. Rapid account switching from the same IP address
```

Claude will use the `auth0_create_action` tool to generate and create an Action with sophisticated detection logic.

### Step 3: Create automated response Actions

After you have detection in place, next you'll need to create Actions that respond to detected threats. These Actions will implement your security policies based on the risk level.

Ask Claude:

```bash lines theme={null}
Create an action that responds to security threats based on risk score:
1. For low risk (score < 30), allow the login but log the event
2. For medium risk (score 30-60), require additional verification like MFA
3. For high risk (score > 60), block the login and notify security team
```

Claude will use the `auth0_create_action` tool again to create a response Action.

### Step 4: Deploy the security Actions

With your security Actions created, you need to deploy them in the correct sequence to ensure they work together properly.

Ask Claude:

```bash wrap lines theme={null}
Deploy the security detection action first, followed by the response action. They should run in sequence during the login flow.
```

Claude will use the `auth0_deploy_action` tool twice to deploy both Actions in the correct order.

### Step 5: Create custom security challenge Forms

For medium-risk logins that require additional verification, you'll want to create a custom [Form](/docs/customize/forms) that explains the situation to the user.

Ask Claude:

```bash wrap lines theme={null}
Create a custom form for additional security verification that explains to the user why additional verification is needed and provides clear instructions.
```

Claude will use the `auth0_create_form` tool to create a custom Form. After creating the Form, publish it with the `auth0_publish_form` tool.

Ask Claude:

```bash lines theme={null}
Publish the form to my tenant
```

## Step 6: Monitor security events

To ensure your security system is working effectively, you need to monitor security events and analyze patterns.

Ask Claude:

```bash wrap lines theme={null}
Show me all high-risk security events from the past 24 hours, and identify any patterns or trends, using score-based categorization.
```

Claude will use the `auth0_list_logs` tool with specific criteria to find security events.

## Step 7: Fine-tune the security system

Based on your monitoring, you may need to fine-tune your security system to reduce false positives or address specific threats.

Ask Claude:

```bash wrap lines theme={null}
Update the security detection action to be more sensitive to logins from Russia and China, and less sensitive to unusual login times for users in the IT department.
```

Claude will use `auth0_get_action` to retrieve the current Action code, then use `auth0_update_action` to modify it. After updating the Action, deploy it with `auth0_deploy_action`.

Ask Claude:

```bash lines theme={null}
Deploy the action to my tenant.
```

## Conclusion

By using Auth0 MCP Server with Claude, you've implemented a sophisticated security monitoring and response system by:

* Setting up advanced threat detection based on user behavior patterns
* Creating intelligent response mechanisms that adapt to different risk levels
* Implementing custom security challenges for suspicious logins
* Establishing a monitoring system to track security events
* Fine-tuning your security rules based on real-world data

This natural language approach not only saves time but also allows you to implement security best practices without deep expertise in Auth0's Actions system or log query syntax.

## Next steps

* Integrate your security system with external threat intelligence feeds
* Implement automated remediation for compromised accounts
* Create security dashboards for real-time monitoring
* Develop custom risk models based on your organization's specific needs


# Streamline API Authorization Flows with Auth0 Model Context Protocol (MCP) Server
Source: https://auth0.com/docs/get-started/auth0-mcp-server/auth0-mcp-server-guides/streamline-api-authorization-flows-with-auth0-model-context-protocol-mcp

Streamline your API authorization flows with Auth0 Model Context Protocol (MCP) Server.

<Card title="Overview">
  Learn how to:

  1. Explore your current API configurations
  2. Create new API definitions with appropriate scopes
  3. Implement custom authorization logic with Auth0 Actions
  4. Deploy and test your authorization system
  5. Monitor and refine your authorization rules
</Card>

<Card title="Before you start">
  1. Create an Auth0 account with administrative access
  2. Install Auth0 MCP Server and integrate with Claude Desktop
</Card>

Use natural language interactions with [Auth0 MCP Server](/docs/get-started/auth0-mcp-server) to quickly set up and manage a comprehensive API authorization system. By leveraging [Claude's](https://claude.ai/) ability to interact with Auth0 through the Model Context Protocol, you can implement complex authorization patterns in minutes instead of hours.

### Step 1: Explore current API configuration

Before creating new APIs, it's important to understand what's already configured in your tenant. With Auth0 MCP Server, you can quickly get this information through natural language.

Ask Claude:

```bash wrap lines theme={null}
Show me all the resource servers (APIs) currently configured in my Auth0 tenant.
```

Claude will use the `auth0_list_resource_servers` tool to retrieve and display your existing APIs. This gives you a quick overview of your API landscape without having to navigate through the <Tooltip href="/docs/glossary?term=Auth0+dashboard">Auth0 dashboard</Tooltip>.

### Step 2: Create new API definitions

Now that you understand your current configuration, you can create new APIs for your microservices architecture. Instead of configuring each API separately through the dashboard, you can define them all at once.

Ask Claude:

```bash lines theme={null}
I need to create three new APIs for our microservices:
1. An inventory API with read and write scopes
2. An orders API with read and write scopes
3. A customers API with read, write, and admin scopes

Each API should enforce scope validation.
```

Claude will use the `auth0_create_resource_server` tool multiple times to set up these APIs.

### Step 3: Implement authorization logic

After your APIs are defined, you'll need to implement custom authorization logic. With Auth0 MCP Server, you can describe your business rules in natural language and Claude will generate the appropriate Auth0 [Actions](/docs/customize/actions) code.

Ask Claude:

```bash lines theme={null}
Create an Action that enforces the following authorization rules:
1. Verify the requesting application has the appropriate scopes for the API being accessed.
2. For the customers API, requests using the admin scope should only come from our internal IP ranges (10.0.0.0/8 and 172.16.0.0/12).
3. Log all authorization decisions for audit purposes.
```

Claude will use the `auth0_create_action` tool to generate and create an Action with the appropriate code.

### Step 4: Deploy the authorization Action

Once you're satisfied with the Action code, you can deploy it to your production environment with a simple instruction.

Ask Claude:

```bash lines theme={null}
Deploy this action to run during the token issuance process.
```

Claude will use the `auth0_deploy_action` tool to deploy the Action.

### Step 5: Configure client applications

Next, you'll need to configure your client applications to access the appropriate APIs with the correct scopes.

Ask Claude:

```bash wrap lines theme={null}
Create an 'inventory-manager' application on my Auth0 tenant and update the app to access the inventory and orders APIs with read and write permissions, but not the customers API.
```

Claude will first use `auth0_get_application` to retrieve the current configuration, then use `auth0_update_application` to update it.

### Step 6: Verify configuration

To ensure your authorization system is working correctly, you can check the logs for any authorization issues.

Ask Claude:

```bash wrap lines theme={null}
Check the logs for any failed API access attempts in the last hour. Focus on authorization failures.
```

Claude will use `auth0_list_logs` to find relevant log entries.

### Step 7: Refine the authorization rules

Based on the log analysis, you might need to refine your authorization rules. For example, you might need to allow access from additional IP ranges.

Ask Claude:

```bash wrap lines theme={null}
Update the authorization action to also allow requests from our development VPN range 192.168.100.0/24.
```

Claude will use `auth0_get_action` to retrieve the current Action code, then use `auth0_update_action` to modify it.

Finally, Claude will use `auth0_deploy_action` to deploy the updated Action.

### Conclusion

By using Auth0 MCP Server with Claude, you've implemented a comprehensive API authorization system by:

* Creating multiple API definitions with appropriate scopes
* Implementing custom authorization logic with IP-based restrictions
* Configuring client applications to access specific APIs
* Monitoring and refining your authorization rules

This natural language approach not only saves time but also allows you to implement security best practices without deep expertise in Auth0's Actions system or log query syntax.

## Next steps

* Implement additional authorization rules based on user attributes
* Set up regular log monitoring for security analysis
* Create custom dashboards to visualize API usage patterns


# Understanding Scopes
Source: https://auth0.com/docs/get-started/auth0-mcp-server/auth0-mcp-server-guides/understanding-scopes

Understand how to use scopes within the model context protocol

For security purposes, the Auth0 Model Context Protocol server grants no scopes by default and required scopes must be requested during initialization. After your server is initialized, you can manually set scopes using a glob pattern, an example of which is below:

```bash lines theme={null}
# Select all read scopes
npx @auth0/auth0-mcp-server init --scopes 'read:*'

# Select multiple scope patterns (comma-separated)
npx @auth0/auth0-mcp-server init --scopes 'read:*,create:clients,update:actions'
```

Depending on the type of management operation or tool you wish to use, you may need to request additional scopes to successfully execute the MCP operation on your client. Below are the available scopes.

<Accordion title="Management operation scopes">
  <table>
    <thead>
      <tr>
        <th>Management Operation</th>
        <th>MCP Tool</th>
        <th>Required Scope</th>
        <th>Potential Implications</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Get details about a specific Auth0 application</td>
        <td><code>auth0\_get\_application</code></td>
        <td><code>read:clients</code></td>
        <td>Allows viewing potentially sensitive application configuration details</td>
      </tr>

      <tr>
        <td>Get details about a specific Auth0 application</td>
        <td><code>auth0\_get\_application</code></td>
        <td><code>read:clients</code></td>
        <td>Allows viewing potentially sensitive application configuration details</td>
      </tr>

      <tr>
        <td>Create a new Auth0 application</td>
        <td><code>auth0\_create\_application</code></td>
        <td><code>create:clients</code></td>
        <td>Enables creating new applications that could be used for authentication flows</td>
      </tr>

      <tr>
        <td>Update an existing Auth0 application</td>
        <td><code>auth0\_update\_application</code></td>
        <td><code>update:clients</code></td>
        <td>Can modify critical application settings, potentially disrupting authentication for users</td>
      </tr>

      <tr>
        <td>List all resource servers (APIs) in the Auth0 tenant</td>
        <td><code>auth0\_list\_resource\_servers</code></td>
        <td><code>read:resource\_servers</code></td>
        <td>Exposes all API configurations and their scopes</td>
      </tr>

      <tr>
        <td>Get details about a specific Auth0 resource server</td>
        <td><code>auth0\_create\_resource\_server</code></td>
        <td><code>create:resource\_servers</code></td>
        <td>Reveals API configuration details including signing algorithms and token settings</td>
      </tr>

      <tr>
        <td>Create a new Auth0 resource server (API)</td>
        <td><code>auth0\_get\_resource\_server</code></td>
        <td><code>read:resource\_servers</code></td>
        <td>Allows defining new APIs and scopes that could be used for access control</td>
      </tr>

      <tr>
        <td>Update an existing Auth0 resource server (API)</td>
        <td><code>auth0\_update\_resource\_server</code></td>
        <td><code>update:resource\_servers</code></td>
        <td>Can modify API configurations, potentially affecting applications that rely on those APIs</td>
      </tr>

      <tr>
        <td>List all actions in the Auth0 tenant</td>
        <td><code>auth0\_list\_actions</code></td>
        <td><code>read:actions</code></td>
        <td>Reveals all custom code that runs during authentication flows</td>
      </tr>

      <tr>
        <td>Get details about a specific Auth0 action</td>
        <td><code>auth0\_get\_action</code></td>
        <td><code>read:actions</code></td>
        <td>Exposes custom code and logic for authentication flows</td>
      </tr>

      <tr>
        <td>Create a new Auth0 action</td>
        <td><code>auth0\_create\_action</code></td>
        <td><code>create:actions</code></td>
        <td>Allows creation of custom code that can modify authentication flows and user data</td>
      </tr>

      <tr>
        <td>Update an existing Auth0 action</td>
        <td><code>auth0\_update\_action</code></td>
        <td><code>update:actions</code></td>
        <td>Can modify custom code that affects authentication security and behavior</td>
      </tr>

      <tr>
        <td>Deploy an Auth0 action</td>
        <td><code>auth0\_deploy\_action</code></td>
        <td><code>update:actions</code></td>
        <td>Pushes custom code into production, potentially affecting all users' authentication experience</td>
      </tr>

      <tr>
        <td>List logs from the Auth0 tenant</td>
        <td><code>auth0\_list\_logs</code></td>
        <td><code>read:logs</code></td>
        <td>Exposes detailed information about user activity, failed logins, and security events</td>
      </tr>

      <tr>
        <td>Get a specific log entry by ID</td>
        <td><code>auth0\_get\_log</code></td>
        <td><code>read:logs</code></td>
        <td>Provides detailed data about specific authentication events, potentially including PII</td>
      </tr>

      <tr>
        <td>List all forms in the Auth0 tenant</td>
        <td><code>auth0\_list\_forms</code></td>
        <td><code>read:forms</code></td>
        <td>Reveals custom form configurations for login, registration, and password reset</td>
      </tr>

      <tr>
        <td>Get details about a specific Auth0 form</td>
        <td><code>auth0\_get\_form</code></td>
        <td><code>read:forms</code></td>
        <td>Exposes detailed form configuration including field validation and design</td>
      </tr>

      <tr>
        <td>Create a new Auth0 form</td>
        <td><code>auth0\_create\_form</code></td>
        <td><code>create:forms</code></td>
        <td>Allows creation of custom authentication forms that collect user data</td>
      </tr>

      <tr>
        <td>Update an existing Auth0 form</td>
        <td><code>auth0\_update\_form</code></td>
        <td><code>update:forms</code></td>
        <td>Can modify user-facing forms, potentially affecting authentication experience</td>
      </tr>

      <tr>
        <td>Publish an Auth0 form</td>
        <td><code>auth0\_publish\_form</code></td>
        <td><code>update:forms</code></td>
        <td>Makes form changes live for all users, potentially affecting production authentication</td>
      </tr>
    </tbody>
  </table>
</Accordion>


# Auth0 Model Context Protocol (MCP) Server Tools Reference
Source: https://auth0.com/docs/get-started/auth0-mcp-server/auth0-mcp-tools-reference

Reference material for Auth0 Model Context Protocol (MCP) Server.

Consult this reference guide for natural language examples that enable you to interact with your Auth0 tenant using Auth0 MCP Server and any [MCP Client](https://modelcontextprotocol.io/clients).

## Application management

<table>
  <thead>
    <tr>
      <th><strong>Tool</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Natural language examples</strong>                                                                        </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>auth0\_list\_applications</code></td>
      <td>List all applications in the Auth0 tenant or search by name.</td>
      <td>"Show me all my Auth0 applications."<br /><br />"Find applications with 'api' in their name."<br /><br />"What applications do I have in my Auth0 tenant?"</td>
    </tr>

    <tr>
      <td><code>auth0\_get\_application </code></td>
      <td>Get details about a specific Auth0 application.</td>
      <td>"Show me details for the application called 'Customer Portal'."<br /><br />"Get information about my application with client ID ."<br /><br />"What are the callback URLs for my 'Mobile App'?"</td>
    </tr>

    <tr>
      <td><code>auth0\_create\_application </code></td>
      <td>Create a new Auth0 application.</td>
      <td>"Create a new single-page application called 'Analytics Dashboard'."<br /><br />"Set up a new native mobile app called 'iOS Client'."<br /><br />"Create a machine-to-machine application for our background service."</td>
    </tr>

    <tr>
      <td><code>auth0\_update\_application</code></td>
      <td>Update an existing Auth0 application.</td>
      <td>"Update the callback URLs for my 'Web App' to include `https://staging.example.com/callback`."<br /><br />"Change the logout URL for the 'Customer Portal'."<br /><br />"Add development environment metadata to my 'Admin Dashboard' application."</td>
    </tr>
  </tbody>
</table>

## Resource server (API) management

<table>
  <thead>
    <tr>
      <th><strong>Tool</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Natural language examples</strong>                                                                        </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>auth0\_list\_resource\_servers</code></td>
      <td>List all resource servers (APIs) in the Auth0 tenant.</td>
      <td>"Show me all the APIs in my Auth0 tenant."<br /><br />"List my resource servers."<br /><br />"What APIs have I configured in Auth0?"</td>
    </tr>

    <tr>
      <td><code>auth0\_get\_resource\_server</code></td>
      <td>Get details about a specific Auth0 resource server.</td>
      <td>"Show me details for the 'User API'."<br /><br />"What scopes are defined for my 'Payment API'?"<br /><br />"Get information about the resource server with identifier `https://api.example.com`."</td>
    </tr>

    <tr>
      <td><code>auth0\_create\_resource\_server</code></td>
      <td>Create a new Auth0 resource server (API).</td>
      <td>"Create a new API called 'Inventory API' with read and write scopes."<br /><br />"Set up a resource server for our customer data API."<br /><br />"Create an API with the identifier `https://orders.example.com`."</td>
    </tr>

    <tr>
      <td><code>auth0\_update\_resource\_server</code></td>
      <td>Update an existing Auth0 resource server.</td>
      <td>"Add an 'admin' scope to the 'User API'."<br /><br />"Update the token lifetime for my 'Payment API' to 1 hour."<br /><br />"Change the signing algorithm for my API to RS256."</td>
    </tr>
  </tbody>
</table>

## Actions management

<table>
  <thead>
    <tr>
      <th><strong>Tool</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Natural language examples</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>auth0\_list\_actions</code></td>
      <td>List all Actions in the Auth0 tenant.</td>
      <td>"Show me all my Auth0 Actions."<br /><br />"What Actions do I have configured?"<br /><br />"List the Actions in my tenant."</td>
    </tr>

    <tr>
      <td><code>auth0\_get\_action</code></td>
      <td>Get details about a specific Auth0 Action.</td>
      <td>"Show me the code for my 'Enrich User Profile' Action."<br /><br />"Get details about my login flow Action."<br /><br />"What does my 'Add Custom Claims' Action do?"</td>
    </tr>

    <tr>
      <td><code>auth0\_create\_action</code></td>
      <td>Create a new Auth0 Action.</td>
      <td>"Create an Action that adds user roles to tokens."<br /><br />"Set up an Action to log failed login attempts."<br /><br />"Create a post-login Action that checks user location."</td>
    </tr>

    <tr>
      <td><code>auth0\_update\_action</code></td>
      <td>Update an existing Auth0 Action.</td>
      <td>"Update my 'Add Custom Claims' Action to include department information."<br /><br />"Modify the IP filtering logic in my security Action."<br /><br />"Fix the bug in my user enrichment Action."</td>
    </tr>

    <tr>
      <td><code>auth0\_deploy\_action</code></td>
      <td>Deploy an Auth0 Action.</td>
      <td>"Deploy my 'Add Custom Claims' Action to production."<br /><br />"Make my new security Action live."<br /><br />"Deploy the updated user enrichment Action."</td>
    </tr>
  </tbody>
</table>

## Logs management

<table>
  <thead>
    <tr>
      <th><strong>Tool</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Natural language examples</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>auth0\_list\_logs</code></td>
      <td>List logs from the Auth0 tenant</td>
      <td>"Show me recent login attempts."<br /><br /> "Find failed logins from the past 24 hours."<br /><br />"Get authentication logs from yesterday."<br /><br />"Show me successful logins for user [john@example.com](mailto:john@example.com)."</td>
    </tr>

    <tr>
      <td><code>auth0\_get\_log</code></td>
      <td>Get a specific log entry by ID.</td>
      <td>"Show me details for log entry ."<br /><br />"Get more information about this failed login attempt."<br /><br />"What caused this authentication error?"</td>
    </tr>
  </tbody>
</table>

## Forms management

<table>
  <thead>
    <tr>
      <th><strong>Tool</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Natural language examples</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>auth0\_list\_forms</code></td>
      <td>List all Forms in the Auth0 tenant.</td>
      <td>"Show me all my Auth0 Forms."<br /><br />"What login Forms do I have configured?"<br /><br />"List the custom Forms in my tenant."</td>
    </tr>

    <tr>
      <td><code>auth0\_get\_form</code></td>
      <td>Get details about a specific Auth0 Form.</td>
      <td>"Show me the details of my 'Corporate Login' Form."<br /><br />"What does my password reset Form look like?"<br /><br />"Get the configuration for my signup Form."</td>
    </tr>

    <tr>
      <td><code>auth0\_create\_form</code></td>
      <td>Create a new Auth0 Form.</td>
      <td>"Create a new login Form with our company branding."<br /><br />"Set up a custom signup Form that collects department information."<br /><br />"Create a password reset Form with our logo."</td>
    </tr>

    <tr>
      <td><code>auth0\_update\_form</code></td>
      <td>Update an existing Auth0 Form.</td>
      <td>"Update the colors on our login Form to match our new brand guidelines."<br /><br />"Add a privacy policy link to our signup Form."<br /><br />"Change the logo on our password reset Form."</td>
    </tr>

    <tr>
      <td><code>auth0\_publish\_form</code></td>
      <td>Publish an Auth0 Form.</td>
      <td>"Publish my updated login Form."<br /><br />"Make the new signup Form live."<br /><br />"Deploy the password reset Form to production."</td>
    </tr>
  </tbody>
</table>

## Combining Operations

You can also ask [Claude](https://claude.ai/) to perform multiple related operations in sequence:

#### Set up a new API with client access

```bash wrap lines theme={null}
Create a new API called "Inventory API" with read and write scopes, then update my "Admin Dashboard" application to have access to it.
```

#### Create and deploy a security Action

```bash wrap lines theme={null}
Create an Action that requires MFA for users logging in from outside our corporate network, then deploy it to the login flow.
```

#### Analyze security events

```bash wrap lines theme={null}
Show me all failed login attempts from the past week, and identify any patterns or suspicious activity.
```

#### Updating branding across forms

```bash wrap lines theme={null}
Update all our Auth0 forms to use our new logo at <https://example.com/new-logo.png> and change the primary color to #0066CC.
```

## Best Practices

1. Be specific in your requests: Include names, IDs, or other identifying information when referring to specific resources.
2. Use natural language: You don't need to memorize tool names or parameters; simply describe what you want to accomplish.
3. Review before confirming: When Claude suggests changes, review them carefully before confirming.
4. Start simple: Begin with simple queries to get familiar with how Claude interprets your requests.

## Troubleshooting

If Claude is unable to perform an operation, consider the following:

1. Authentication: Ensure you're logged in with the Auth0 CLI (`auth0 login`).
2. Permissions: Verify your account has the necessary permissions in Auth0.
3. Specificity: Try to be more specific in your request.


# Getting Started with Auth0 Model Context Protocol (MCP) Server
Source: https://auth0.com/docs/get-started/auth0-mcp-server/getting-started-with-auth0-mcp-server

Integrate Auth0 Model Context Protocol (MCP) Server with your AI clients.

<Card title="Before you start">
  * Install [Node.js v18 or higher](https://nodejs.org/en/download) on your system.
  * Create an active [Auth0 account](https://auth0.com/)with administrative permissions.
  * Install at least one supported MCP client ([Claude Desktop](https://claude.ai/download), [Cursor](https://www.cursor.com/downloads), or [Windsurf](https://www.windsurf.com/editor), for example).
</Card>

Empower your team and your users by installing [Auth0 Model Context Protocol (MCP) Server](/docs/get-started/auth0-mcp-server) and integrating with several commonly-used [MCP clients](https://modelcontextprotocol.io/clients).

## Installation and configuration

Install Auth0 MCP Server by running one of these commands in your terminal:

### For Claude Desktop (default)

```bash lines theme={null}
npx @auth0/auth0-mcp-server init
```

### For Cursor

```bash lines theme={null}
npx @auth0/auth0-mcp-server init --client cursor
```

### For Windsurf

```bash lines theme={null}
npx @auth0/auth0-mcp-server init --client windsurf
```

### Other MCP clients

To use Auth0 MCP Server with any other MCP Client, you can manually add this configuration to the client and restart for changes to take effect:

```json lines theme={null}
{
  "mcpServers": {
    "auth0": {
      "command": "npx",
      "args": ["-y", "@auth0/auth0-mcp-server", "run"],
      "capabilities": ["tools"],
      "env": {
        "DEBUG": "auth0-mcp"
      }
    }
  }
}
```

## Authenticate with Auth0

Your browser will automatically open to initiate the <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> device <Tooltip href="/docs/glossary?term=authorization+flow">authorization flow</Tooltip>. Log into your Auth0 account and grant the requested permissions.

<Callout icon="file-lines">
  Credentials are securely stored in your system's keychain. You can optionally verify storage through your keychain management tool.
</Callout>

## Verify your integration

### Claude Desktop

1. Restart Claude Desktop to ensure it recognizes the newly installed Auth0 MCP Server.
2. In Claude Desktop, click on the **Tools** icon and verify that Auth0 tools (for example, `auth0_create_action` or `auth0_delete_application`) show up in the **Available MCP Tools** list.
3. Begin a conversation with Claude Desktop and ask help managing your Auth0 tenant.

### Cursor

1. Restart Cursor to ensure it recognizes the newly installed Auth0 MCP Server.
2. In Cursor, open **Settings > MCP** and verify that **Auth0** appears in the **MCP Servers** list.
3. Begin a conversation with Cursor and ask for help managing your Auth0 tenant.

### Windsurf

1. Restart Windsurf to ensure it recognizes the newly installed Auth0 MCP Server.
2. In Windsurf, open **Windsurf Settings > Cascade** and verify that **Auth0** appears in the **Model Context Protocol (MCP) Servers** list.
3. Begin a conversation with Windsurf and ask for help managing your Auth0 tenant.

## Common troubleshooting steps

<Callout icon="file-lines">
  Most connection issues can be resolved by configuring the Auth0 MCP server and restarting the MCP client.
</Callout>

#### Get command line help:

View a list of supported commands and usage examples with:

```bash lines theme={null}
npx @auth0/auth0-mcp-server help
```

#### Authentication issues

Ensure correct permissions in your Auth0 tenant and try re-initializing with:

```bash lines theme={null}
npx @auth0/auth0-mcp-server init
```

#### Connection failures:

1. Confirm the MCP server is actively running with:

   ```ps lines theme={null}
   ps aux | grep auth0-mcp
   ```

2. Restart your AI client after verifying the server is running.

#### Claude Can't Connect to the Server error:

1. Restart Claude Desktop after installation.

2. Check that the server is running with:

   ```ps lines theme={null}
   ps aux | grep auth0-mcp
   ```

#### API errors:

Check your Auth0 token permissions and expiration. Enable debug mode (see below) to view detailed logs.

## Debug configuration issues

#### Enable debug mode

Enable debug mode to view detailed logs:

```bash lines theme={null}
export DEBUG=auth0-mcp
```

#### Debug client logs

Get detailed MCP client logs from Claude Desktop:

```bash lines theme={null}
# Follow logs in real-time
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
```

Get detailed MCP server logs by running the Auth0 MCP Server in debug mode:

```bash lines theme={null}
DEBUG=auth0-mcp npx @auth0/auth0-mcp-server run
```

#### Advanced debugging using MCP Inspector

For advanced troubleshooting, use the MCP Inspector:

```bash wrap lines theme={null}
npx @modelcontextprotocol/inspector -e DEBUG='auth0-mcp' @auth0/auth0-mcp-server run__text in bold__
```

## Next steps

Explore the full capabilities of Auth0 MCP Server by visiting our [Auth0 Model Context Protocol (MCP) Server Tools Reference](/docs/get-started/auth0-mcp-server/auth0-mcp-tools-reference), or check out our Auth0 Model Context Protocol Server Guides for practical examples and use cases.


# Build with AI Tools
Source: https://auth0.com/docs/get-started/build-with-ai-tools

Learn how to use AI tools to index and search the Auth0 knowledge base.

Accelerate your development workflow by connecting AI agents and LLMs directly to the Auth0 knowledge base. Get context-aware answers, code samples, and API references with links to official documentation.

To help your AI tools index and search for the information you need, Auth0 provides:

* LLM context files (`llms.txt`): Structured Markdown files for bulk ingestion.
* Auth0 Docs MCP Server: Hosted MCP Server for AI agents to dynamically query the knowledge base.

## LLM context files

Use LLM context files to help LLMs understand and efficiently ingest the entire Auth0 site directory.

<table>
  <thead>
    <tr>
      <th><strong>Name</strong></th>
      <th><strong>URL</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>llms.txt</code></td>
      <td><code>[https://auth0.com/llms.txt](https://auth0.com/llms.txt)</code></td>
      <td>Concise summaries of all articles; best for quick context.</td>
    </tr>

    <tr>
      <td><code>llms-full.txt</code></td>
      <td><code>[https://auth0.com/docs/llms-full.txt](https://auth0.com/docs/llms-full.txt)</code></td>
      <td>Full content of all articles; best for deep indexing.</td>
    </tr>
  </tbody>
</table>

## Auth0 Docs MCP Server

Connect your AI tools to the Auth0 Docs Model Context Protocol (MCP) Server for real-time access to the most up-to-date documentation on Auth0. The Auth0 Docs MCP Server exposes the `SearchAuth0Docs` tool, which enables AI agents to search the Auth0 knowledge base and return contextual content with relevant links to product documentation.

The Auth0 Docs MCP Server has the following endpoint metadata:

```
Server Name: Auth0 Docs
Server URL: https://auth0.com/docs/mcp
Transport Type: HTTP
```

Learn how to connect your AI tools to the Auth0 Docs MCP Server by following our integration guides.

<Tabs>
  <Tab title="ChatGPT">
    To connect ChatGPT to the Auth0 Docs MCP Server:

    1. Navigate to [Settings > Connectors](https://chatgpt.com/#settings/Connectors).
    2. Select **Create** and provide the metadata for your MCP server:
       * Connector Name: Auth0 Docs MCP Server
       * Description: Indexes and searches the Auth0 knowledge base
       * Connector URL: `https://auth0.com/docs/mcp`
    3. Select **Create**.

    If successful, the Auth0 Docs MCP Server should appear as an installed MCP server. To learn more, read OpenAI's [Connect from ChatGPT](https://developers.openai.com/apps-sdk/deploy/connect-chatgpt/) documentation.
  </Tab>

  <Tab title="Claude">
    To connect Claude to the Auth0 Docs MCP Server:

    1. Navigate to [Settings > Connectors](https://claude.ai/settings/connectors).
    2. Select **Add custom connector**.
    3. Enter the following to add the Auth0 Docs MCP Server:
       * Name: Auth0 Docs MCP Server
       * URL: `https://auth0.com/docs/mcp`
    4. Select **Add**.

    If successful, the Auth0 Docs MCP Server should appear as a custom connector. To learn more, read Model Context Protocol's [Connect to remote MCP Servers](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server#connecting-to-a-remote-mcp-server) documentation.
  </Tab>

  <Tab title="Claude Code">
    To connect Claude Code to the Auth0 Docs MCP Server:

    In your terminal, run:

    ```bash lines theme={null}
    claude mcp add --transport http auth0-docs-mcp-server https://auth0.com/docs/mcp
    ```

    To verify, run:

    ```bash lines theme={null}
    claude mcp list
    ```

    If successful, the Auth0 Docs MCP Server should appear as an installed MCP server. To learn more, read Claude’s [Installing MCP servers](https://docs.anthropic.com/en/docs/claude-code/mcp#installing-mcp-servers) documentation.
  </Tab>

  <Tab title="Codex">
    To connect Codex to the Auth0 Docs MCP Server:

    In your terminal, run:

    ```bash lines theme={null}
    codex mcp add auth0-docs-mcp-server --url https://auth0.com/docs/mcp
    ```

    To verify, run:

    ```bash lines theme={null}
    codex mcp list
    ```

    If successful, the Auth0 Docs MCP Server should appear as an installed MCP server. To learn more, read Codex’s [Model Context Protocol](https://developers.openai.com/codex/mcp) documentation.
  </Tab>

  <Tab title="Cursor">
    To connect Cursor to the Auth0 Docs MCP Server:

    1. Use Command + Shift + P (Ctrl + Shift + P on Windows) to open the command palette and search for **Open MCP settings**.
    2. Select **New MCP Server** to edit your `mcp.json`.
    3. Add the Auth0 Docs MCP Server:

    ```json lines theme={null}
    {
      "mcpServers": {
        "auth0-docs-mcp-server": {
          "url": "https://auth0.com/docs/mcp"
        }
      }
    }
    ```

    If successful, the Auth0 Docs MCP Server should appear as an installed MCP server. To learn more, read Cursor’s [Installing MCP servers](https://cursor.com/docs/context/mcp#installing-mcp-servers) documentation.
  </Tab>

  <Tab title="VS Code">
    To connect VS Code to the Auth0 Docs MCP Server:

    1. Use Command + Shift + P (Ctrl + Shift + P on Windows) to open the command palette and search for **MCP: Add Server**.
    2. Select **HTTP** as the type of MCP server.
    3. Enter the MCP Server URL (`https://auth0.com/docs/mcp`) and set the Server ID to `auth0-docs-mcp-server`.
    4. Select **Global** or **Workspace** to make the MCP server available across all your workspaces or for your current workspace.
    5. Press **Enter** to complete setup. Verify the Auth0 Docs MCP Server appears under **Installed MCP Servers** in your **Extensions**.

    To learn more, read [Add and manage MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).
  </Tab>

  <Tab title="Windsurf">
    To connect Windsurf to the Auth0 Docs MCP Server:

    1. Use Command + Shift + P (Ctrl + Shift + P on Windows) to open Windsurf settings and search for **MCP**.
    2. Select **View Raw Config** to edit your `mcp_config.json`.
    3. Add the Auth0 Docs MCP Server:

    ```json lines theme={null}
    {
      "mcpServers": {
        "auth0-docs-mcp-server": {
          "serverUrl": "https://auth0.com/docs/mcp"
        }
      }
    }
    ```

    4. Save and select **Refresh** to load the new MCP configuration.

    To verify, ask `What MCP servers do you have installed?` in Cascade’s chat. Cascade should list the Auth0 Docs MCP Server as an installed MCP server. To learn more, read Windsurf’s [Model Context Protocol](https://docs.windsurf.com/plugins/cascade/mcp#model-context-protocol-mcp) documentation.
  </Tab>
</Tabs>

## Sample prompts

<Callout icon="file-lines">
  AI tools can make mistakes. Always review responses by referencing the provided documentation links and AI-generated code for accuracy before deploying.
</Callout>

Use the following sample prompts with your AI tools to leverage Auth0 to secure your identity workflow.

### Setup

* How do I customize the consent prompt to render rich authorization requests in a web browser?
* Fetch me instructions on how to set up asynchronous authorization with the Auth0 Guardian app in my mobile application.
* How do I implement refresh token rotation in a Next.js app? Show me the configuration steps and a code example.

### Connections and integrations

* I want to restrict access to this app to users who are members of a specific GitHub Organization. Use the Auth0 Docs MCP Server to find how to configure the GitHub Enterprise Connection and write an Auth0 Action that checks the user's GitHub org membership during login, denying access if they aren't a member.
* Configure a Slack Social Connection. Use the Auth0 Docs MCP Server to find the correct way to map Slack's `team_id` onto the user's ID token. Then, update my local user interface to include this `slack_team_id` field.
* How do I integrate Auth0 into an existing Vercel project?

### AI agents and MCP servers

* Add a tool call to my AI agent that can access the user’s Google calendar and answer questions about their schedule and meetings. Use the Auth0 Docs MCP Server for instructions on using Auth0 to secure login and implementing the tool call to the user’s Google calendar.
* Act as a security engineer. Use the Auth0 Docs MCP Server to find the guide on Authorization for Your MCP Server. Update my current server configuration to require OAuth 2.1 for all incoming connections and verify that it uses the Resource Parameter Compatibility Profile for access tokens.
* Examine my current tool definitions in `server.py`. Use the Auth0 Docs MCP Server to verify whether my implementation of Custom Token Exchange complies with RFC 8693. If you find any discrepancies where user context might be leaked, suggest a fix and provide the updated code.

### Troubleshooting

* Help me troubleshoot a `refresh token doesn’t exist` error when using the refresh token exchange. Use the Token Vault setup instructions as context.
* The logout button isn't clearing the session on the Auth0 side. Search the documentation for the correct Federated Logout URL structure and update my logout handler to use it.
* My login flow is failing with a `401 Unauthorized error`. Use the Auth0 Docs MCP Server to look up common causes for this error with the `auth0-node` SDK and check my `.env` and client initialization for mismatches.


# Custom Token Exchange
Source: https://auth0.com/docs/authenticate/custom-token-exchange

Learn about Custom Token Exchange Early Access features.

<Warning>
  Custom Token Exchange is currently available in Early Access for all Auth0 Enterprise and B2B Pro customers. By using this feature, you agree to the applicable Free Trial terms in [Okta’s Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0’s product release cycle, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To learn more about subscription types, review the Auth0 [pricing](https://auth0.com/pricing) page.
</Warning>

Custom Token Exchange enables applications to exchange their existing tokens for Auth0 tokens when calling the `/oauth/token` endpoint, as defined in [RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693). Common use cases for the Custom Token Exchange include:

* Getting Auth0 tokens for another <Tooltip href="/docs/glossary?term=audience">audience</Tooltip>
* Integrating with an external <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>
* Migrating to Auth0

To learn more, read [Example Use Cases and Code Samples](/docs/authenticate/custom-token-exchange/cte-example-use-cases).

Each Custom Token Exchange request maps to a [Custom Token Exchange Profile](/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#create-custom-token-exchange-profile) that is governed by an [Action](/docs/customize/actions), where you can:

* Write custom code to decode and validate `subject_tokens` passed to the `/oauth/token` endpoint
* Authorize access and set the user to proceed with the transaction.

You can [configure multiple Custom Token Exchange Profiles](/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#create-custom-token-exchange-profile) for an application. After the Auth0 Authorization Server validates that the Custom Token Exchange request is valid and maps to an existing Custom Token Exchange Profile, the [Custom Token Exchange trigger](/docs/customize/actions/explore-triggers/signup-and-login-triggers/custom-token-exchange-trigger) executes the single Action associated with that profile. The application can then leverage the Custom Token Exchange to authenticate and get Auth0 access, ID, and refresh tokens for the user.

<Callout icon="file-lines">
  Custom Token Exchange gives you the added flexibility to set the user for the transaction by taking on the additional responsibility of securely validating the corresponding subject token that identifies the user for the transaction.

  Remember that subject tokens used with Custom Token Exchange can be any token format or type you require, as long as your Action code can interpret them. **You must implement strong validation of the tokens you receive and accept.** If you fail to do so, you open yourself up to different attack vectors, such as spoofing or replay attacks, resulting in bad actors being able to authenticate with someone else’s user ID.

  To learn about different options for implementing secure validation of your subject tokens, read and apply the recommendations included in [Example Use Cases and Code Samples](/docs/authenticate/custom-token-exchange/cte-example-use-cases). Make sure you also take into consideration and apply [Attack Protection](/docs/authenticate/custom-token-exchange/cte-attack-protection) capabilities.
</Callout>

## Tenant logs

Each Custom Token Exchange transaction generates a tenant event log:

* Successful transactions: `secte` logs
* Failed transactions: `fecte` logs

Use the tenant logs to help you troubleshoot any issues you encounter with your token exchange.

## Limitations

Custom Token Exchange in Early Access does not support the following:

* MFA API methods `api.authentication.challengeWith()` and `api.authentication.EnrollWith()`
* When a Custom Token Exchange transaction is associated with an Organization, `api.multifactor.enable()` and MFA policies are not supported
* Custom DB Connections with import mode `ON` are not supported for `setUserByConnection()` operations
* Specific delegation support (e.g. `actor_token` and `actor` claim)
* Third-party and non-OIDC conformant clients


# Configure Custom Token Exchange
Source: https://auth0.com/docs/authenticate/custom-token-exchange/configure-custom-token-exchange

Learn how to configure the Custom Token Exchange by associating an Action with a Custom Token Profile.

<Warning>
  Custom Token Exchange (CTE) is currently available in Early Access for all Auth0 Enterprise and B2B Pro customers. By using this feature, you agree to the applicable Free Trial terms in [Okta’s Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0’s product release cycle, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To learn more about subscription types, review the Auth0 [pricing](https://auth0.com/pricing) page.
</Warning>

To configure the Custom Token Exchange for your application, you need to:

* [Complete the prerequisites](#prerequisites)
* [Enable Custom Token Exchange for your application](#enable-custom-token-exchange-for-your-application)
* [Configure](#configure-custom-token-exchange-profile) and [manage](#manage-custom-token-exchange-profile) a Custom Token Exchange Profile

## Prerequisites

Before configuring the Custom Token Exchange, make sure your application meets the following prerequisites:

* Is a first-party client
* Is OIDC-conformant

To configure your application, navigate to **[Applications > Advanced Settings > OAuth](https://auth0.com/docs/get-started/applications/application-settings#oauth)** in the Auth0 Dashboard.

## Enable Custom Token Exchange for your application

To enable the Custom Token Exchange, [create a new application](/docs/get-started/auth0-overview/create-applications) or update an existing one with the Auth0 Dashboard or the Management API. You can create multiple applications to use Custom Token Exchange.

When you create a new application:

1. By default, Custom Token Exchange is disabled. To enable Custom Token Exchange, use the Management API to make a `POST` call to [Create a Client](https://auth0.com/docs/api/management/v2/clients/post-clients) or a `PATCH` call to [Update a Client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id). Set the `allow_any_profile_of_type` attribute under `token_exchange` to `["custom_authentication"]`:

```json lines theme={null}
{
  "token_exchange": {
    "allow_any_profile_of_type": ["custom_authentication"]
  }
}
```

2. Enable the connection you want to use with Custom Token Exchange for the application.
3. Make sure your application is flagged as [First-Party](/docs/get-started/applications/confidential-and-public-applications/first-party-and-third-party-applications) and it is configured as OIDC Conformant in **[Dashboard > Applications > Advanced Settings > OAuth](/docs/get-started/applications/application-settings#oauth)**.

<Callout icon="file-lines">
  Custom DBs with import mode `ON` are only supported for `setUserById()` operations.
</Callout>

Once you create the application, note the `client_id` and `client_secret` for later use when calling the `/oauth/token` endpoint.

## Configure Custom Token Exchange Profile

Each Custom Token Exchange Profile establishes a one-to-one mapping between a `subject_token_type` and an Action, which contains the code logic for a specific use case.

Custom Token Exchange requests sent to the `/oauth/token` endpoint with a specific `subject_token_type` value will map to the corresponding Custom Token Profile and route to the associated Action for processing.

To create a Custom Token Exchange Profile, you need to:

1. [Create an Action for the profile](#create-action-for-the-profile)
2. [Create the Custom Token Exchange Profile](#create-custom-token-exchange-profile)
3. [Manage the Custom Token Exchange Profile](#manage-custom-token-exchange-profile)

### Create Action for the profile

Use the Custom Token Exchange Event and API objects to write an Action that:

* Decodes and validates the `subject_token` based on the `subject_token_type`. This will provide you with information about the user for the transaction.
* Enforce any authorization policy you may need to apply for the transaction.

Once you are sure the transaction can proceed, set the user. Auth0 will then issue access, ID, and refresh tokens for this user as a form of user authentication.

To learn from example Custom Token Exchange Actions, read [Example Use Cases and Code Samples](/docs/authenticate/custom-token-exchange/cte-example-use-cases).

Once you’ve written your Action, add and and deploy it in the Auth0 Dashboard.

1. Navigate to **Actions > Library**.
2. Select **Create Action > Build from Scratch**.
3. In the **Create Action** dialog, enter a name and select the **Custom Token Exchange** trigger from the drop-down.

<Frame>
  <img alt="" />
</Frame>

4. Select **Create**.
5. **Deploy** the Action.

<Frame>
  <img alt="" />
</Frame>

After you deploy the Action, copy the Action ID that Auth0 has assigned to it. You still need to add your custom logic to the Action. First, get the Action ID to create the Custom Token Exchange Profile.

6. To get the Action ID in the Auth0 Dashboard, navigate to the URL of the browser window. The Action ID should be the last part of the URL, as shown in the following image:

<Frame>
  <img alt="" />
</Frame>

You can also get the Action ID via the Management API. First, get a Management API token to consume the API. Then, make the following `GET` request to the `/actions` endpoint:

```bash lines theme={null}
curl --location 'https://{yourDomain}/api/v2/actions/actions?actionName={yourActionName}' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
```

You should receive the Action ID in the response body within `actions[0].id.` You need the Action ID to create the Custom Token Exchange Profile.

### Create Custom Token Exchange Profile

To create the Custom Token Exchange Profile, use the Management API to make a `POST` request with the following parameters to the `/token-exchange-profiles` endpoint:

```bash lines theme={null}
curl --location 'https://{yourDomain}/api/v2/token-exchange-profiles' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
--data '{
    "name": "<YOUR_PROFILE_NAME>",
    "subject_token_type": "<YOUR_UNIQUE_PROFILE_TOKEN_TYPE_URI>",
    "action_id": "<YOUR_ACTION_ID>",
    "type": "custom_authentication"
}'
```

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>subject\_token\_type</code></td>
      <td>Unique profile token type URI starting with `https://` or <code>urn</code><br /><br />The following namespaces are reserved and you can’t use them:<br /><br /><ul><li>`http://auth0.com`</li><li>`https://auth0.com`</li><li>`http://okta.com`</li><li>`https://okta.com`</li><li><code>urn:ietf</code></li><li><code>urn:auth0</code></li><li><code>urn:okta</code></li></ul></td>
    </tr>

    <tr>
      <td><code>action\_id</code></td>
      <td>Action ID of Action associated with the Custom Token Profile.</td>
    </tr>

    <tr>
      <td><code>type</code></td>
      <td>Should be set to <code>custom\_authentication</code>.</td>
    </tr>
  </tbody>
</table>

If you've successfully created a Custom Token Exchange Profile, you should receive a response like the following:

```json lines theme={null}
{
  "id":"tep_9xqewuejpa2RTltf",
  "name":"<YOUR_PROFILE_NAME>",
  "type":"custom_authentication",
  "subject_token_type":"<YOUR_UNIQUE_PROFILE_TOKEN_TYPE_URI>",
  "action_id":"<YOUR_ACTION_ID>",
  "created_at":"2025-01-30T13:19:00.616Z",
  "updated_at":"2025-01-30T13:19:00.616Z"
}
```

### Manage Custom Token Exchange Profile

To manage your Custom Token Exchange Profile, use the Management API to make requests to the `/token-exchange-profiles` endpoint.

To get all your Custom Token Exchange Profiles, make the following `GET` request to the `/token-exchange-profiles` endpoint. The `/token-exchange-profiles` endpoint supports checkpoint pagination if you have several profiles.

```bash lines theme={null}
curl --location 'https://{yourDomain}/api/v2/token-exchange-profiles' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
```

To update the name or the `subject_token_type` of an existing profile, make the following `PATCH` request to the `/token-exchange-profiles` endpoint.

<Callout icon="file-lines">
  Once the Action is created, you cannot modify the Action ID.
</Callout>

```bash lines theme={null}
curl --location --request PATCH 'https://{yourDomain}/api/v2/token-exchange-profiles/{yourProfileId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
--data '{
    "name": "external-idp-migration",
    "subject_token_type": "urn:partner0:external-idp-migration"
}'
```

To delete a Custom Token Exchange Profile, make the following `DELETE` request to the `/token-exchange-profiles` endpoint:

```bash lines theme={null}
curl --location --request DELETE 'https://{yourDomain}/api/v2/token-exchange-profiles/{yourProfileId}' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
--data ''
```


# Attack Protection with Custom Token Exchange
Source: https://auth0.com/docs/authenticate/custom-token-exchange/cte-attack-protection

Learn how to use Attack Protection with Custom Token Exchange.

<Warning>
  Custom Token Exchange (CTE) is currently available in Early Access for all Auth0 Enterprise and B2B Pro customers. By using this feature, you agree to the applicable Free Trial terms in [Okta’s Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0’s product release cycle, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To learn more about subscription types, review the Auth0 [pricing](https://auth0.com/pricing) page.
</Warning>

To protect against spoofing and replay attacks, which involve unauthorized attempts to compromise or reuse a `subject_token`, Custom Token Exchange supports [Suspicious IP Throttling](/docs/secure/attack-protection/suspicious-ip-throttling). This enables you to indicate in your Actions code when a subject token is invalid, allowing Auth0 to count the number of failed attempts sent from that external IP.

When the number of failed attempts from an IP address reaches a pre-configured threshold, Auth0 blocks traffic for a Custom Token Exchange request coming from that IP with the following error:

```json lines theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
{
    "error": "too_many_attempts",
    "error_description": "We have detected suspicious login behavior and further attempts will be blocked. Please contact the administrator."
}
```

The IP address can start making requests again after a configured period of time.

We recommend you use Suspicious IP Throttling for all Custom Token Exchange use cases, especially with native applications and single-page applications (SPAs). Because non-confidential applications like native applications and SPAs can’t securely store secrets to authenticate themselves, attackers can more easily re-use stolen or leaked subject tokens.

<Callout icon="file-lines">
  To implement Suspicious IP Throttling protection, use `api.access.rejectInvalidSubjectToken` in your Actions code whenever the received subject token does not pass strong validation.
</Callout>

Suspicious IP Throttling is activated by default for Auth0 tenants. When activated, the default settings for Custom Token Exchange will be applied:

* Threshold: 10. Maximum number of failed attempts for an IP address.
* Throttling rate: 6 per hour. One additional attempt will become available after every 10 minutes until the threshold is refilled.

<Frame>
  <img alt="" />
</Frame>

## Configure Suspicious IP Throttling for Custom Token Exchange

You can configure a custom threshold and throttling rate for the Custom Token Exchange with the Management API.

First, [get a Management API token](/docs/secure/tokens/access-tokens/management-api-access-tokens#get-management-api-tokens) to consume the API. Then, make the following `GET` request to the [Get Suspicious IP Throttling settings endpoint](https://auth0.com/docs/api/management/v2/attack-protection/get-suspicious-ip-throttling):

```bash lines theme={null}
curl --location 'https://{yourDomain}/api/v2/attack-protection/suspicious-ip-throttling' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
```

You will receive a response like the following:

```json lines theme={null}
{
  "enabled": true,
  "shields": [
    "admin_notification",
    "block"
  ],
  "allowlist": [],
  "stage": {
    "pre-login": {
      "max_attempts": 100,
      "rate": 864000
    },
    "pre-user-registration": {
      "max_attempts": 50,
      "rate": 1200
    },
    "pre-custom-token-exchange": {
      "max_attempts": 10,
      "rate": 600000
    }
  }
}
```

Use the following `PATCH` request to update the `pre-custom-token-exchange` stage with the needed values. Note that the rate is the interval of time in milliseconds at which new attempts are granted.

```bash lines theme={null}
curl --location --request PATCH 'https://{yourDomain}/api/v2//attack-protection/suspicious-ip-throttling' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
--data '{"stage":{"pre-custom-token-exchange":{"max_attempts":10,"rate":600000}}}'
```


# Example Use Cases
Source: https://auth0.com/docs/authenticate/custom-token-exchange/cte-example-use-cases

Learn about Custom Token Exchange example use cases with code samples for implementation.

<Warning>
  Custom Token Exchange is currently available in Early Access for all Auth0 Enterprise and B2B Pro customers. By using this feature, you agree to the applicable Free Trial terms in [Okta’s Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0’s product release cycle, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To learn more about subscription types, review the Auth0 [pricing](https://auth0.com/pricing) page.
</Warning>

You can use Custom Token Exchange to solve advanced integration scenarios where normal federated login strategies based on redirecting the end user cannot be applied due to technical or user experience constraints. The code provided for the use cases is incomplete and only aims at showing the logical steps you can follow with your code to address the use case. Refer to [code samples](#code-samples) for more detailed code examples.

<Callout icon="file-lines">
  Auth0 recommends using normal, out-of-the-box federated login whenever possible. By allowing you to set the user for the transaction, Custom Token Exchange gives you more flexibility by taking on the additional responsibility of securely validating and handling the transaction.
</Callout>

## Use cases

This section describes example use cases and specific code samples with recommendations for implementing your scenario. To illustrate the use cases, we will use GearUp, a fictional car rental service company.

### Use Case: Seamless migration into Auth0

GearUp has a mobile App used by millions of people and needs to modernize their Identity solution so they’ve decided to switch to Auth0. However, they want to avoid forcing users to re-authenticate as they migrate from their legacy identity provider, or IdP, as that adds friction to the user experience.

To solve this, and to limit risks, GearUp is migrating incrementally. For each user, they wish to exchange the refresh token from their legacy IdP for an Auth0 access token, refresh token and <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> set. This allows their app to seamlessly start using Auth0 as the IdP for this user, as well as consume GearUp APIs using Auth0-issued tokens. Once the exchange is done for all users, the app will be fully migrated and the old IdP can be disconnected–all without impacting end users and GearUp’s business.

<Frame>
  <img alt="" />
</Frame>

As a prerequisite, GearUp has done a [bulk user import](/docs/manage-users/user-migration/bulk-user-imports) into their Auth0 tenant and the mobile app has a valid legacy refresh token for each user to be migrated.

1. The mobile app makes a request to Auth0 to exchange the legacy refresh token, setting it as the subject token.
2. The corresponding Custom Token Exchange profile Action executes. It validates the refresh token with the legacy IdP and gets the external user ID from the user profile. It then applies the required authorization policy and finally sets the user.
3. Auth0 responds with Auth0 access token, ID token, and refresh token.
4. The mobile app can now use the Customer APIs using Auth0 tokens without the user having to re-authenticate.

The following code sample shows how to implement this in the Custom Token Exchange Action. In this case, since user profiles were already imported into an Auth0 database connection:

* We don’t want to create the user.
* We don’t want to update the user profile.

We use the external IdP user ID to set the user in the corresponding connection.

```javascript lines expandable theme={null}
/**
* Handler to be executed while executing a custom token exchange request
* @param {Event} event - Details about the incoming token exchange request.
* @param {CustomTokenExchangeAPI} api - Methods and utilities to define token exchange process.
*/
exports.onExecuteCustomTokenExchange = async (event, api) => {

 // 1. VALIDATE the refresh_token received in the subject_token by using it to get
 // the UserProfile from the external IdP
 const { isValid, user } = await getUserProfile(
   event.transaction.subject_token,
   event.secrets.CLIENT_SECRET,
 );

 if (!isValid) {
   // Mark the subject token as invalid and fail the transaction.
   api.access.rejectInvalidSubjectToken("Invalid subject_token");
 } else {
   // 2. Apply your AUTHORIZATION POLICY as required to determine if the request is valid.
   // Use api.access.deny() to reject the transaction in those cases.

   // 3. When we have the profile, we SET THE USER in the target connection
   api.authentication.setUserByConnection(
     connectionName,
     {
       // only the user_id in the connection is needed, as we are not
       // creating nor updating the user
       user_id: user.sub,
     },
     {
       creationBehavior: "none",
       updateBehavior: "none",
     },
   );
 }
};

/**
* Exchange the refresh token and load the user profile from the legacy IdP
* @param {string} refreshToken
* @param {string} clientSecret
* @returns {Promise<{ isValid: boolean, user?: object }>} If the refresh token was exchanged successfully, returns the user profile
*/
async function getUserProfile(refreshToken, clientSecret) {
 // Add your code here. REFER TO CODE SAMPLES FOR DETAILED EXAMPLES
}
```

### Use Case: Re-use an external authentication provider

Another use case involves GearUp partnering with Air0, a leading travel provider, to offer their car rental services directly within the Air0 single-page application. GearUp offers a JavaScript library that encapsulates the use of their APIs. This way GearUp’s APIs can easily be consumed by Air0’s website where car rental services are being offered.

Once again, the solution needs to be invisible to end users by avoiding re-authentication to GearUp. To solve this problem, GearUp’s JavaScript library can perform a token exchange using the external Air0 ID token as the input. This results in an Auth0 access token that is generated and associated with the corresponding GearUp user based on their email address. Once the GearUp library gets the access token, it can start using GearUp’s APIs to offer car rental services directly within Air0’s website.

<Frame>
  <img alt="" />
</Frame>

As a prerequisite, GearUp has set up Air0 IdP as a federated enterprise or social connection, so the user can authenticate via federate login or alternatively via Custom Token Exchange as follows:

1. The Single Page App gets the ID token from the external IdP once the user authenticates.
2. It then requests the exchanges of the ID token, setting it as the subject token.
3. The corresponding Custom Token Exchange profile Action executes. It validates the ID token and gets the user ID and other profile attributes from the token. It then applies the required authorization policy and finally sets the user.
4. Auth0 responds with Auth0 access token, ID token and refresh token.
5. The javascript code running in the SPA can now use the Customer APIs using Auth0 tokens without the user having to re-authenticate.

The following code exemplifies how to implement this in the Custom Token Exchange Action. In this case:

* We use the external IdP user ID to set the user in the corresponding connection.
* We want to create the user if they don’t yet exist.
* We don’t want to replace the user profile if a more complete set of attributes is obtained via federated login, in case the user already exists.
* We don't want to verify emails when users are created.

```javascript lines expandable theme={null}
const jwksUri = "https://example.com/.well-known/jwks.json";

/**
 * Handler to be executed while executing a custom token exchange request
 * @param {Event} event - Details about the incoming token exchange request.
 * @param {CustomTokenExchangeAPI} api - Methods and utilities to define token exchange process.
 */
exports.onExecuteCustomTokenExchange = async (event, api) => {

  // 1. VALIDATE the id_token received in the subject_token
  const { isValid, payload } = await validateToken(
    event.transaction.subject_token,
  );

  if (!isValid) {
    // Mark the subject token as invalid and fail the transaction.
    api.access.rejectInvalidSubjectToken("Invalid subject_token");
  } else {
    // 2. Apply your AUTHORIZATION POLICY as required to determine if the request is valid.
    // Use api.access.deny() to reject the transaction in those cases.

    // 3. SET THE USER in the target connection.
    // We don't want to verify emails when users are created
    // This example assumes subject_token (id_token) contains standard OIDC claims. Other custom mappings
    // are also possible.
    api.authentication.setUserByConnection(
      'Enterprise-OIDC',
      {
          user_id: formattedUserId,
          email: subject_token.email,
          email_verified: subject_token.email_verified,
          phone_number: subject_token.phone_number,
          phone_verified: subject_token.phone_number_verified,
          username: subject_token.preferred_username,
          name: subject_token.name,
          given_name: subject_token.given_name,
          family_name: subject_token.family_name,
          nickname: subject_token.nickname,
          verify_email: false
      },
      {
          creationBehavior: 'create_if_not_exists',
          updateBehavior: 'none'
      }
    );
  }

  /**
   * Validate the subject token
   * @param {string} subjectToken
   * @returns {Promise<{ isValid: boolean, payload?: object }>} Payload of the token
   */
  async function validateToken(subjectToken) {
    // Add your code here. REFER TO CODE SAMPLES FOR DETAILED EXAMPLES
  }
};
```

Read [code samples](#code-samples) for a more detailed example on how to securely validate <Tooltip href="/docs/glossary?term=JWTs">JWTs</Tooltip>.

### Use Case: Get Auth0 tokens for another audience

GearUp wants to improve how it authorizes calls between its internal microservices to serve API requests. It wants a centralized policy controlling the resources that each service can consume. This can also be solved using Token Exchange.

When the API request first arrives at service A, it exchanges the received access token for a new one that allows it to consume service B as the new audience. If the authorization policy governing the token exchange allows it, service A gets the new token back and can now consume service B. The user ID is kept unchanged in the new token, so the proper user context is retained throughout the process.

<Frame>
  <img alt="" />
</Frame>

The GearUp application has initially obtained an access token to consume API A on behalf of a user:

1. The app sends the request with the initial access token to API A.
2. API A backend service validates the access token and requests to exchange by setting it as the subject token for a new access token to consume API B.
3. The corresponding Custom Token Exchange profile Action executes. It validates the access token and gets the Auth0 user ID from the token. It then applies the required authorization policy and finally sets the user.
4. Auth0 responds with an Auth0 access token to consume the API B audience.
5. API A backend service calls API B using the new access token, which is still associated with the same user.

The following code exemplifies how to implement this in the Custom Token Exchange Action. In this case:

* We use the Auth0 user ID to set the user, so there is no need to set this in the scope of any connection.
* We don’t want to create or update the user.

Refer to [Validate JWTs signed with asymmetric keys](#validate-jwts-signed-with-asymmetric-keys) for expanded code samples on this use case.

```javascript lines expandable theme={null}
const jwksUri = "https://example.com/.well-known/jwks.json";

/**
 * Handler to be executed while executing a custom token exchange request
 * @param {Event} event - Details about the incoming token exchange request.
 * @param {CustomTokenExchangeAPI} api - Methods and utilities to define token exchange process.
 */
exports.onExecuteCustomTokenExchange = async (event, api) => {
  // 1. VALIDATE the access_token received in the subject_token
  const { isValid, payload } = await validateToken(
    event.transaction.subject_token,
  );

  if (!isValid) {
    // Mark the subject token as invalid and fail the transaction.
    api.access.rejectInvalidSubjectToken("Invalid subject_token");
  } else {
    // 2. Apply your AUTHORIZATION POLICY as required to determine if the request is valid.
    // Use api.access.deny() to reject the transaction in those cases.

    // 3. SET THE USER
    api.authentication.setUserById(payload.sub);
  }

  /**
   * Validate the subject token
   * @param {string} subjectToken
   * @returns {Promise<{ isValid: boolean, payload?: object }>} Payload of the token
   */
  async function validateToken(subjectToken) {
    // Add your code here. REFER TO CODE SAMPLES FOR DETAILED EXAMPLES
  }
};
```

Read [code samples](#code-samples) for a more detailed example on how to securely validate JWTs.

### Use case: Perform MFA during Custom Token Exchange

Building upon the [Use Case: Re-use an external authentication provider](#use-case%3A-re-use-an-external-authentication-provider), GearUp now wants to confirm user presence when a token from the external authentication provider is used. This is necessary to mitigate security risks such as token theft or scenarios where MFA is not supported by the external authenticator. GearUp has two options to achieve this: implement an organization-wide MFA policy or programmatically trigger MFA using a Post Login Action.

The next example uses a PostLogin Action to trigger MFA authentication during the Custom Token Exchange transaction. For more details on using MFA grant over embedded APIs, please see the [documentation](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa) for using ROPG with MFA, as Custom Token Exchange follows the same model.

First, define the Action, using `api.multifactor.enable()` to trigger an MFA challenge.  This function is described in [Post Login API documentation](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object).

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  api.multifactor.enable('any');
};

We can now send a token exchange request:

curl --location 'https://{yourDomain}/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode 'audience=https://api.gearup.com' \
--data-urlencode 'scopes=openid offline_access gearup-scope1 gearup-scope2' \
--data-urlencode 'subject_token_type=urn:gearup:external-idp' \
--data-urlencode 'subject_token=t8e7S2D9trQm73e .... iqBR3GjxDtbDVjpfQU' \
--data-urlencode 'client_id=<YOUR_CLIENT_ID>' \
--data-urlencode 'client_secret=<YOUR_CLIENT_SECRET>'
```

This results in an `mfa_required` error that returns an MFA token:

```json lines theme={null}
403 Forbidden
{
  "error": "mfa_required",
  "error_description": "Multifactor authentication required",
  "mfa_token": "<YOUR_MFA_TOKEN>"
}
```

With the `mfa_token` that is returned, the application can then call the MFA API to challenge and verify a factor:

First, return a list of authenticators:

```bash lines theme={null}
curl --location 'https://{yourDomain}.auth0.com/mfa/authenticators' \
--header 'Authorization: Bearer <YOUR_MFA_TOKEN>' \


[
    {
        "id": "sms|dev_1MHoE3huPRB5dcDJ",
        "authenticator_type": "oob",
        "active": true,
        "oob_channel": "sms",
        "name": "XXXXXXXX6220"
    },
    {
        "id": "email|dev_QLGL8cGsvFFnOloK",
        "authenticator_type": "oob",
        "active": true,
        "oob_channel": "email",
        "name": "dloz********@gmai*****"
    }
]
```

Second, use the authenticator ID to trigger a challenge:

```bash lines theme={null}
curl --location 'https://{yourDomain}.auth0.com/mfa/challenge' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<YOUR_CLIENT_ID>' \
--data-urlencode 'client_secret=<YOUR_CLIENT_SECRET>'
--data-urlencode 'mfa_token=<YOUR_MFA_TOKEN>' \
--data-urlencode 'authenticator_id=sms|dev_1MHoE3huPRB5dcDJ' \
--data-urlencode 'challenge_type=oob'
```

The challenge generates the following response:

```json lines theme={null}
{
  "challenge_type": "oob",
  "oob_code": "<YOUR_OOB_CODE>",
  "binding_method": "prompt"
}
```

Use the `mfa_token` and `oob_code` (if returned) to complete the verification process using the token endpoint and receive tokens:

```bash lines theme={null}
curl --location 'https://{yourDomain}.auth0.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=http://auth0.com/oauth/grant-type/mfa-oob' \
--data-urlencode 'mfa_token=<YOUR_MFA_TOKEN>' \
--data-urlencode 'oob_code=<YOUR_OOB_CODE>' \
--data-urlencode 'binding_code=<YOUR_USER_CODE>'
```

Read [code samples](#code-samples) for a more detailed example on how to validate opaque refresh token with the legacy IdP.

## Code samples

The following code samples show best practices for common scenarios for validating incoming subject tokens in a secure and performant way.

Use asymmetric algorithms and keys whenever you can as you don’t need to share any secret with Auth0. This also simplifies key rotation, such as when exposing a JWKS URI endpoint to advertise applicable public keys.

<Callout icon="file-lines">
  It is your responsibility to ensure that subject tokens are protected with a strong algorithm and keys/secrets with enough entropy.
</Callout>

### Validate JWTs signed with asymmetric keys

Consider the following recommendations:

* Use Actions [`api.cache ()`](/docs/customize/actions/explore-triggers/signup-and-login-triggers/custom-token-exchange-trigger/custom-token-exchange-api-object) methods to avoid having to fetch the signing keys for each transaction.
* Adhere to [RFC8725](https://www.rfc-editor.org/rfc/rfc8725.txt) best practices
* Use RS\*, PS\*, ES\* or Ed25519 algorithms
* Do not use or accept the none algorithm
* Use RSA with a minimum length of 2048 bits.

```javascript lines expandable theme={null}
const { jwtVerify, importJWK } = require("jose");

const jwksUri = "https://example.com/.well-known/jwks.json";
const fetchTimeout = 5000; // 5 seconds

const validIssuer = "urn:my-issuer"; // Replace with your issuer

/**
 * Handler to be executed while executing a custom token exchange request
 * @param {Event} event - Details about the incoming token exchange request.
 * @param {CustomTokenExchangeAPI} api - Methods and utilities to define token exchange process.
 */
exports.onExecuteCustomTokenExchange = async (event, api) => {
  const { isValid, payload } = await validateToken(
    event.transaction.subject_token,
  );

  // Apply your authorization policy as required to determine if the request is valid.
  // Use api.access.deny() to reject the transaction in those cases.

  if (!isValid) {
    // Mark the subject token as invalid and fail the transaction.
    api.access.rejectInvalidSubjectToken("Invalid subject_token");
  } else {
    // Set the user in the current request as authenticated, using the user ID from the subject token.
    api.authentication.setUserById(payload.sub);
  }

  /**
   * Validate the subject token
   * @param {string} subjectToken
   * @returns {Promise<{ isValid: boolean, payload?: object }>} Payload of the token
   */
  async function validateToken(subjectToken) {
    try {
      const { payload, protectedHeader } = await jwtVerify(
        subjectToken,
        async (header) => await getPublicKey(header.kid),
        {
          issuer: validIssuer,
        },
      );

      // Perform additional validation on the token payload as required

      return { isValid: true, payload };
    } catch (/** @type {any} */ error) {
      if (error.message === "Error fetching JWKS") {
        throw new Error("Internal error - retry later");
      } else {
        console.log("Token validation failed:", error.message);
        return { isValid: false };
      }
    }
  }

  /**
   * Get the public key to use for key verification. Load from the actions cache if available, otherwise
   * fetch the key from the JWKS endpoint and store in the cache.
   * @param {string} kid - kid (Key ID) of the key to be used for verification
   * @returns {Promise<Object>}
   */
  async function getPublicKey(kid) {
    const cachedKey = api.cache.get(kid);
    let keyData;

    if (!cachedKey) {
      console.log(`Key ${kid} not found in cache`);
      keyData = await fetchKeyFromJWKS(kid);
      // Cache the stringified version
      api.cache.set(kid, JSON.stringify(keyData), { ttl: 600000 });
    } else {
      // Parse the raw JWK object from cache
      keyData = JSON.parse(cachedKey.value);
    }

    //Convert the raw JWK object to a KeyLike object
    return await importJWK(keyData, keyData.alg);
  }

  /**
   * Fetch public signing key from the provided JWKS endpoint, to use for token verification
   * @param {string} kid - kid (Key ID) of the key to be used for verification
   * @returns {Promise<object>}
   */
  async function fetchKeyFromJWKS(kid) {
    const controller = new AbortController();
    setTimeout(() => controller.abort(), fetchTimeout);

    /** @type {any} */
    const response = await fetch(jwksUri);

    if (!response.ok) {
      console.log(`Error fetching JWKS. Response status: ${response.status}`);
      throw new Error("Error fetching JWKS");
    }
    const jwks = await response.json();
    const key = jwks.keys.find((key) => key.kid === kid);
    if (!key) {
      throw new Error("Key not found in JWKS");
    }
    return key;
  }
};
```

### Validate JWTs signed with symmetric keys

Consider the following recommendations:

* Use [Actions Secrets](/docs/customize/actions/write-your-first-action#add-a-secret) to securely store your symmetric secrets.
* Adhere to [RFC8725](https://www.rfc-editor.org/rfc/rfc8725.txt) best practices
* Use secure algorithms such as HS256, along with high entropy random secrets (e.g. of at least 256 bits long)

```javascript lines expandable theme={null}
const { jwtVerify } = require("jose");

const validIssuer = "urn:my-issuer"; // Replace with your issuer

/**
 * Handler to be executed while executing a custom token exchange request
 * @param {Event} event - Details about the incoming token exchange request.
 * @param {CustomTokenExchangeAPI} api - Methods and utilities to define token exchange process.
 */
exports.onExecuteCustomTokenExchange = async (event, api) => {
  // Initialize the shared symmetric key from Actions Secrets
  const encoder = new TextEncoder();
  const symmetricKey = encoder.encode(event.secrets.SHARED_SECRET);

  const { isValid, payload } = await validateToken(
    event.transaction.subject_token,
    symmetricKey,
  );

  // Apply your authorization policy as required to determine if the request is valid.
  // Use api.access.deny() to reject the transaction in those cases.

  if (!isValid) {
    // Mark the subject token as invalid and fail the transaction.
    api.access.rejectInvalidSubjectToken("Invalid subject_token");
  } else {
    // Set the user in the current request as authenticated, using the user ID from the subject token.
    api.authentication.setUserById(payload.sub);
  }
};

/**
 * Validate the subject token
 * @param {string} subjectToken
 * @param {Uint8Array} symmetricKey
 * @returns {Promise<{ isValid: boolean, payload?: object }>} Payload of the token
 */
async function validateToken(subjectToken, symmetricKey) {
  try {
    // Validate token is correctly signed with the shared symmetric key
    // It also checks it is not expired as long as it includes an 'exp' attribute.
    const { payload, protectedHeader } = await jwtVerify(
      subjectToken,
      symmetricKey,
      {
        issuer: validIssuer,
      },
    );

    return { isValid: true, payload };
  } catch (/** @type {any} */ error) {
    console.log("Token validation failed:", error.message);
    return { isValid: false };
  }
}
```

### Validate opaque token with an external service

Use [Action Secrets](/docs/customize/actions/write-your-first-action#add-a-secret) to securely store your external IdP <Tooltip href="/docs/glossary?term=client+secret">client secret</Tooltip>.

```javascript lines expandable theme={null}
const tokenEndpoint = "EXTERNAL_TOKEN_ ENDPOINT";
const userInfoEndpoint = "EXTERNAL_USER_INFO_ENDPOINT";
const clientId = "EXTERNAL_CLIENT_ID";
const connectionName = "YOUR_CONNECTION_NAME";
const fetchTimeout = 5000; // 5 seconds

/**
 * Handler to be executed while executing a custom token exchange request
 * @param {Event} event - Details about the incoming token exchange request.
 * @param {CustomTokenExchangeAPI} api - Methods and utilities to define token exchange process.
 */
exports.onExecuteCustomTokenExchange = async (event, api) => {
  const { isValid, user } = await getUserProfile(
    event.transaction.subject_token,
    event.secrets.CLIENT_SECRET,
  );

  if (!isValid) {
    // Mark the subject token as invalid and fail the transaction.
    api.access.rejectInvalidSubjectToken("Invalid subject_token");
    return;
  }

  // Apply your authorization policy as required to determine if the request is valid.
  // Use api.access.deny() to reject the transaction in those cases.

  // When we have the profile, we set the user in the target connection
  api.authentication.setUserByConnection(
    connectionName,
    {
      // only the user_id in the connection is needed, as we are not
      // creating nor updating the user
      user_id: user.sub,
    },
    {
      creationBehavior: "none",
      updateBehavior: "none",
    },
  );
};

/**
 * Exchange the refresh token and load the user profile from the legacy IdP
 * @param {string} refreshToken
 * @param {string} clientSecret
 * @returns {Promise<{ isValid: boolean, user?: object }>} If the refresh token was exchanged successfully, returns the user profile
 */
async function getUserProfile(refreshToken, clientSecret) {
  const { isValid, accessToken } = await refreshAccessToken(
    refreshToken,
    clientSecret,
  );
  if (!isValid) {
    return { isValid: false };
  }

  const controller = new AbortController();
  setTimeout(() => controller.abort(), fetchTimeout);

  /** @type {any} */
  const response = await fetch(userInfoEndpoint, {
    method: "GET",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
  });

  if (!response.ok) {
    console.log(`Failed to fetch user info. Status: ${response.status}`);
    throw new Error("Error fetching user info");
  }

  const userProfile = await response.json();

  return { isValid: true, user: userProfile };
}

/**
 * Use the Refresh Token with the legacy IdP to validate it and get an access token
 * @param {string} refreshToken
 * @param {string} clientSecret
 * @returns {Promise<{ isValid: boolean, accessToken?: string }>} If the refresh token was exchanged successfully, returns the access token
 */
async function refreshAccessToken(refreshToken, clientSecret) {
  const controller = new AbortController();
  setTimeout(() => controller.abort(), fetchTimeout);

  /** @type {any} */
  let response;

  try {
    response = await fetch(tokenEndpoint, {
      method: "POST",
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
      },
      body: new URLSearchParams({
        grant_type: "refresh_token",
        refresh_token: refreshToken,
        client_id: clientId,
        client_secret: clientSecret,
      }).toString(),
    });
  } catch (error) {
    console.error("Error refreshing token");
    throw error;
  }

  if (!response.ok) {
    const errorBody = await response.json();
    console.error("Error refreshing token:", errorBody.error);

    // If we receive an error indicating the refresh token is invalid (for example, an invalid_grant error),
    // then we should explicitly indicate an invalid token using api.access.rejectInvalidSubjectToken
    // to prevent against brute force attacks on the refresh token by activating Suspicious IP Throttling.
    // For other errors which indicate a generic error making the request to the IdP, we should throw
    // an error to indicate a transient failure.
    if (errorBody.error === "invalid_grant") {
      return { isValid: false };
    } else {
      throw new Error("Error refreshing token");
    }
  }

  // Parse the response, in the form { access_token: "...", expires_in: ..., }
  const data = await response.json();
  console.log("Successfully exchanged refresh token");
  return { isValid: true, accessToken: data.access_token };
}
```


# Multi-Factor Authentication (MFA) with Custom Token Exchange
Source: https://auth0.com/docs/authenticate/custom-token-exchange/cte-multi-factor-authentication

Learn how to use Multi-Factor Authentication (MFA) with Custom Token Exchange.

<Warning>
  Custom Token Exchange is currently available in Early Access for all Auth0 Enterprise and B2B Pro customers. By using this feature, you agree to the applicable Free Trial terms in [Okta’s Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0’s product release cycle, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To learn more about subscription types, review the Auth0 [pricing](https://auth0.com/pricing) page.
</Warning>

To add protection against token theft or other security risks, you can add Multi-factor Authentication to a Custom Token Exchange request using one of the following methods:

* [Enable and configure your MFA policy ](/docs/secure/multi-factor-authentication/enable-mfa) for your tenant
* Use `api.multifactor.enable()`in a Post-Login Action

When you add MFA, the Auth0 Authorization Server rejects the initial Custom Token Exchange call to the `/token` endpoint with a `mfa_required` error. You can use the error in the [Auth0 MFA API](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/mfa-api) to challenge and verify a factor to obtain the requested Auth0 access, ID, and refresh tokens.

<Callout icon="file-lines">
  Custom Token Exchange Early Access does not support `api.authentication.challengeWith()` or `api.authentication.enrollWith()`. If you use those methods with your Post-Login Action, the transaction will fail with a non-recoverable error. Make sure you don't use those methods when `event.transaction.protocol==oauth2-token-exchange` depending on the `subject_token_type` value.
</Callout>

When a Custom Token Exchange transaction is associated with an Organization, `api.multifactor.enable()` and MFA policies are also not supported.

To learn more about how to use the MFA grant, read [Authenticate Using the Resource Owner Password Flow with MFA](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa), as Custom Token Exchange follows the same model. You can also check out a detailed example in [Use case: Perform MFA during Custom Token Exchange](/docs/authenticate/custom-token-exchange/cte-example-use-cases#use-case%3A-perform-mfa-during-custom-token-exchange).


# Database Connections
Source: https://auth0.com/docs/authenticate/database-connections

Learn how to create and use a database connection using either the Auth0 user store or your own user store.

Auth0 provides database connections to authenticate users with an identifier (email, username, or phone number) and password or [passkeys](/docs/authenticate/database-connections/passkeys/configure-passkey-policy). These credentials are securely stored in the Auth0 user store or in your own database.

You can create a new database connection and manage existing ones at [Auth0 Dashboard > Authentication > Database](https://manage.auth0.com/#/connections/database).

## Database options

### Use Auth0 user store

Auth0 provides the database infrastructure to store your users by default. This scenario provides the best performance for the authentication process since all data is stored in Auth0.

The Auth0-hosted database is highly secure. Passwords are never stored or logged in plain text but are hashed with **bcrypt**. Varying levels of password security requirements can also be enforced. To learn more, read [Password Strength in Auth0 Database Connections](/docs/authenticate/database-connections/password-strength).

<Callout icon="file-lines">
  For database connections, Auth0 limits the number of repeat login attempts per user and IP address. To learn more, read [Database login limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#database-login-limits).
</Callout>

To use Auth0's database infrastructure as your user store, you have options to migrate your users to Auth0. The [automatic migration](/docs/manage-users/user-migration/configure-automatic-migration-from-your-database) feature adds your users to the Auth0 database one-at-a-time as each logs in and avoids asking your users to reset their passwords all at the same time. Or, use Management API to create a job to [import users](/docs/manage-users/user-migration/bulk-user-imports). To learn more, read [User Migration Scenarios](/docs/manage-users/user-migration/user-migration-scenarios) for migration examples.

### Use your own database

If you have an existing user store, or wish to store user credentials on your own server, Auth0 enables you to connect to a [custom database](/docs/authenticate/database-connections/custom-db) or repository and use it as the identity provider.

<Frame>
  <img alt="" />
</Frame>

In this scenario, you provide the login script to authenticate the user that will execute each time a user attempts to log in. Optionally, you can [create scripts](/docs/authenticate/database-connections/custom-db/templates) for sign-up, email verification, password reset, and delete user functionality.

The scripts are Node.js code. Auth0 provides [templates](/docs/authenticate/database-connections/custom-db/templates) for most common databases, such as ASP.NET Membership Provider, MongoDB, MySQL, PostgreSQL, SQL Server, Windows Azure SQL Database, and for a web service accessed by Basic Auth. Essentially, you can connect to almost any kind of database or web service with a custom script.

## Learn more

* [Custom Database Connections](docs/authenticate/database-connections/custom-db)
* [Authenticate with Your Own User Store](/docs/authenticate/database-connections/custom-db/overview-custom-db-connections)
* [Create Custom Database Connections](/docs/authenticate/database-connections/custom-db/create-db-connection)
* [Manage Users](/docs/manage-users)


# Activate and Configure Attributes for Flexible Identifiers
Source: https://auth0.com/docs/authenticate/database-connections/activate-and-configure-attributes-for-flexible-identifiers

Describes how identifiers like email and phone must be configured for a database connection.

<Warning>
  Enabling Flexible Identifiers on your tenant has the potential to introduce breaking changes to your production environment. For more information on potential problems and limitations, read [Flexible Identifiers and Attributes](/docs/authenticate/database-connections/flexible-identifiers-and-attributes).
</Warning>

An Attribute for database connections, email, phone number, or username, is part of the Flexible Identifiers. End users sign up, authenticate, and reset passwords with an Attribute. Each Attribute has a unique configuration.

## Activate Attributes

<Tabs>
  <Tab title="New connection" icon="database">
    1. Navigate to [**Auth0 Dashboard > Authentication > Database**](https://manage.auth0.com/#/connections/database).
    2. Select **+Create DB Connection**.
    3. Enter a name for the connection and choose the attributes.
    4. Choose the authentication method for the connection.
  </Tab>

  <Tab title="Existing connection" icon="database">
    1. Navigate to [**Auth0 Dashboard > Authentication > Database**](https://manage.auth0.com/#/connections/database).
    2. Select the Database Connection you want to update from the list.
    3. Select the **Attributes** tab and choose **Activate**.
    4. When prompted to confirm you’ve tested your configuration in a Development environment, select **Proceed**.
    5. On the Attributes screen, select **Add Attribute**, or **Configure** an existing attribute.
  </Tab>
</Tabs>

Default values are assigned to a new connection and can be edited after the connection has been created.

<table>
  <thead>
    <tr>
      <th>Setting</th>
      <th>Value</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Use <code>\{attribute}</code> as Identifier</td>
      <td><code>True</code></td>
    </tr>

    <tr>
      <td>Allow Signup with <code>\{attribute}</code></td>
      <td>Required</td>
    </tr>

    <tr>
      <td>Require <code>\{attribute}</code> on user profile</td>
      <td><code>True</code></td>
    </tr>

    <tr>
      <td>Username Length</td>
      <td>Min: 1 Max: 15</td>
    </tr>

    <tr>
      <td>Allow usernames in email format</td>
      <td><code>False</code></td>
    </tr>

    <tr>
      <td>Allow usernames in phone number format</td>
      <td><code>False</code></td>
    </tr>
  </tbody>
</table>

## Configure Attributes

Select the **Attributes** tab on the connection. Choose from the available Attributes and select **Configure**. Once you've updated Attribute configurations, select **Save**.

<AccordionGroup>
  <Accordion title="Email Attribute Configuration Options">
    <table>
      <thead>
        <tr>
          <th>Option</th>

          <th />
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Use Email as Identifier</td>
          <td>Turning this on will make email an identifier for this connection. Users will be able to use email for login and password reset.</td>
        </tr>

        <tr>
          <td>Verification Method</td>
          <td>Choose Email Verification link or One-Time Password (OTP).</td>
        </tr>

        <tr>
          <td>Allow Signup with Email</td>
          <td>Choose how email will be collected at signup<br /><ul><li><b>Off</b>: Attribute will be blocked from signup flows.</li><li><b>Optional</b>: Attribute will be optional on signup flows.</li><li><b>Required</b>: Signup flows will fail if the attribute is not present.</li></ul><br />Signup flows include:<br /><ul><li>Universal Login</li><li>Authentication API <code>dbconnections/signup</code> endpoint</li></ul></td>
        </tr>

        <tr>
          <td>Verify email on sign up</td>
          <td>Users will be asked to verify their email address via magic link when signing up.</td>
        </tr>

        <tr>
          <td>Require email on user profile</td>
          <td>Requires email to be present across all operations that create or update a user profile on this connection.<br />Will require email is present on the following:<br /><ul><li>Signup flows</li><li>Creating or updating a user via the Management API</li> <li>Bulk user import</li></ul></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Username Attributes and Configuration Options">
    <table>
      <thead>
        <tr>
          <th>Option</th>

          <th />
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Use Username as Identifier</td>
          <td>Turning this on will make username an identifier for this connection. Users will be able to use username for login and password reset.</td>
        </tr>

        <tr>
          <td>Allow Signup with Username</td>
          <td>Choose how the username will be collected at signup<br /><ul><li><b>Off</b>: Attribute will be blocked from signup flows.</li><li><b>Optional</b>: Attribute will be optional on signup flows.</li><li><b>Required</b>: Signup flows will fail if Attribute is not present.</li></ul><br />Signup flows include:<br /><ul><li>Universal Login</li><li>Authentication API <code>dbconnections/signup</code> endpoint</li></ul></td>
        </tr>

        <tr>
          <td>Require username on user profile</td>
          <td>Requires username to be present across all operations that create or update a user profile on this connection.<br />Will require username is present on the following:<br /><ul><li>Signup flows</li><li>Creating or updating a user via the Management API</li> <li>Bulk user import</li></ul></td>
        </tr>

        <tr>
          <td>Username Length</td>
          <td>Set the minimum and maximum values allowed for a user to have as username.</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Phone Number Attributes and Configuration Options">
    <table>
      <thead>
        <tr>
          <th>Option</th>

          <th />
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Use Phone Number as Identifier</td>
          <td>Turning this on will make <code>phone\_number</code> an identifier for this connection. Users will be able to use <code>phone\_number</code> for login and password reset.</td>
        </tr>

        <tr>
          <td>Allow Signup with Phone Number</td>
          <td>Choose how the phone number will be collected at signup<br /><ul><li><b>Off</b>: Attribute will be blocked from signup flows.</li><li><b>Optional</b>: Attribute will be optional on signup flows.</li><li><b>Required</b>: Signup flows will fail if attribute is not present.</li></ul><br />Signup flows include:<br /><ul><li>Universal Login</li><li>Authentication API <code>dbconnections/signup</code> endpoint</li></ul></td>
        </tr>

        <tr>
          <td>Verify phone on signup</td>
          <td>Users will be required to verify their phone number via OTP when signing up.<br />Please ensure you have configured a phone provider or your users will not be able to proceed with signing up.</td>
        </tr>

        <tr>
          <td>Require phone on user profile</td>
          <td>Requires phone to be present across all operations that create or update a user profile on this connection.<br />Will require phone is present on the following:<ul><li>Signup flows</li><li>Creating or updating a user via the Management API</li> <li>Bulk user import</li></ul></td>
        </tr>
      </tbody>
    </table>
  </Accordion>
</AccordionGroup>

### Configure or remove existing Attributes on a connection

All Attributes can be changed or deleted from your <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. Users cannot log in, sign up or reset passwords using the removed Attribute, and a minimum of one Attribute must remain active on every connection.

To change or remove an Attribute, navigate to the **Attributes** tab, then choose **Remove**.

### Revert a connection

To revert a connection back to its original state, use the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> [Update a connection](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id) endpoint with an `options` object that does not include the `attributes` parameter, as shown below.

<Callout icon="file-lines">
  * If you use the `options` parameter, the entire `options` object is overridden. To avoid partial data or other issues, ensure all current parameters are present by copying the contents within the connections `options` object and including it in the PATCH call. The only parameter you should remove is `attributes`.
  * If your tenant has `username` enabled as an Attribute, performing the following action requires you to modify your `username` settings. You'll need to reconfigure your username settings if you choose this path.
</Callout>

```json lines theme={null}
{
"options": {
       }
}
```


# Custom Database Connections
Source: https://auth0.com/docs/authenticate/database-connections/custom-db

Learn about authenticating users using your database as an identity provider.

Use a custom database connection when you want to provide Auth0 with access to your own independent (legacy) identity data store primarily for authentication (filling the role of an <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>) and for migrating user data to Auth0's data store.

Auth0 [Extensibility](/docs/customize/extensions) allows you to add custom logic to build out last-mile solutions for Identity and Access Management (IdAM). Auth0 extensibility includes [Actions](/docs/customize/actions), and [scripts](/docs/authenticate/database-connections/custom-db/templates) for both custom database connections and custom database migration. Each is implemented using [Node.js](https://nodejs.org/en/) running on the Auth0 platform in an Auth0 tenant.

Auth0 extensibility executes at different points in the IAM pipeline:

* **Actions** extend processes called flows, which are made up of one or more triggers, and which represent the logical pipeline through which information moves during a single point in the Auth0 journey. To learn more about available flows and triggers, read [Explore Flows and Triggers](/docs/customize/actions/explore-triggers).
* **Custom database action scripts** can be used to integrate with an existing user identity store, or can be used where [automatic user migration](/docs/manage-users/user-migration) from a legacy identity store is required. Various [templates](/docs/authenticate/database-connections/custom-db/templates) are provided.

Whatever the use case, Auth0 extensibility allows you to tailor IAM operations to your exact requirements. However, if not used in the right way, this can open up the potential for improper or unintended use which can lead to problematic situations down the line. In an attempt to address matters ahead of time, Auth0 provides [best practice guidance](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts) to both designers and implementers, and we recommend reading it in its entirety at least once, even if you've already started your journey with Auth0.

<Card title="Availability varies by Auth0 plan">
  Your Auth0 plan or custom agreement affects whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

## Learn more

* [Authenticate with Your Own User Store](/docs/authenticate/database-connections/custom-db/overview-custom-db-connections)
* [Create Custom Database Connections](/docs/authenticate/database-connections/custom-db/create-db-connection)
* [Custom Database Action Script Templates](/docs/authenticate/database-connections/custom-db/templates)
* [Troubleshoot Custom Databases](/docs/authenticate/database-connections/custom-db/error-handling)


# Create Custom Database Connections
Source: https://auth0.com/docs/authenticate/database-connections/custom-db/create-db-connection

Learn how to create a database connection.

If you have your own user database, you can use it as an <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> in Auth0 to authenticate users. Follow the process to create the custom database connection, create database action scripts, and add configuration parameters.

<Callout icon="file-lines">
  Make sure that your database has the appropriate fields to store [user profiles attributes](/docs/manage-users/user-accounts/user-profiles/user-profile-structure#user-profile-attributes), such as `id`, `nickname`, `email`, and `password`. To learn about Auth0's user profile schema, read [Normalized User Profiles](/docs/manage-users/user-accounts/user-profiles/normalized-user-profiles). To learn more about updating user profiles, read [Update User Profiles Using Your Database](/docs/manage-users/user-accounts/user-profiles/update-user-profiles-using-your-database).
</Callout>

Auth0 allows you to create connections and scripts for most of the commonly-used databases, including:

* ASP.NET Identity
* MongoDB
* MySQL
* PostgreSQL
* SQLServer
* Windows Azure SQL Database
* Web services accessed via Basic Auth

You can connect to any kind of database or web service with a properly-configured custom script. Note that input sanitization must be completed on the customer end; Auth0 does not sanitize or validate any username/password combination passed by a custom database. Custom Database scripts are subject to Auth0's [Rate Limit Policy](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy).

<Card title="Network firewall">
  If you are behind a firewall, this feature may require that you add the appropriate Auth0 IP addresses to the Allow List to work properly.
</Card>

## Create the connection in the Auth0 Dashboard

1. Navigate to [Auth0 Dashboard > Authentication > Database](https://manage.auth0.com/#/connections/database), and select **Create DB Connection**.
2. Configure the connection's settings, and select **Create**:

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Definition</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Name</strong></td>
      <td>The name of the connection. The name must start and end with an alphanumeric character, contain only alphanumeric characters and dashes, and not exceed 35 characters.</td>
    </tr>

    <tr>
      <td><strong>Choose one or more attributes as user identifiers</strong></td>
      <td>Choose the [identifier attribute(s)](/docs/authenticate/database-connections/activate-and-configure-attributes-for-flexible-identifiers) for the connection.</td>
    </tr>

    <tr>
      <td><strong>Choose one or more authentication methods</strong></td>
      <td>Choose an authentication method to challenge users.</td>
    </tr>

    <tr>
      <td><strong>Use my own database</strong></td>
      <td>Toggle on if you have a database you want to connect with Auth0.</td>
    </tr>

    <tr>
      <td><strong>Disable Sign Ups</strong></td>
      <td>Prevents new user signups from public endpoints.</td>
    </tr>

    <tr>
      <td><strong>Promote Connection to Domain Level</strong></td>
      <td>Promote this connection to domain level to be used with third-party applications.</td>
    </tr>
  </tbody>
</table>

Once Auth0 creates your connection, you'll have the following views (in addition to the **Settings** view):

* Attributes
* Authentication Methods
* Custom Database
* Applications

3. Select the **Custom Database** view, and enable the **Use my own database** switch.

   <Frame>
     <img alt="Enable Custom Database Use My Own Database Option" />
   </Frame>

## Create database action scripts

Toggling the **Use my own database** switch enables the **Database Action Scripts** area where you will create scripts to configure how authentication works when using your database. You can write your database action scripts, or you can select a template from the **Templates** dropdown and modifying it as necessary.

You **must** configure a `login` script; additional scripts for user functionality are optional.

The available database action scripts are:

<table>
  <thead>
    <tr>
      <th><strong>Name</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Parameters</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Login</strong> <br /><span>Required</span></td>
      <td>Executes each time a user attempts to log in.</td>
      <td><code>email</code>, <code>password</code></td>
    </tr>

    <tr>
      <td><strong>Create</strong></td>
      <td>Executes when a user signs up.</td>
      <td><code>user</code></td>
    </tr>

    <tr>
      <td><strong>Verify</strong></td>
      <td>Executes after a user follows the verification link.</td>
      <td><code>email</code></td>
    </tr>

    <tr>
      <td><strong>Change Password</strong></td>
      <td>Executes when a user clicks on the confirmation link after a reset password request.</td>
      <td><code>email</code>, <code>newPassword</code></td>
    </tr>

    <tr>
      <td><strong>Get User</strong></td>
      <td>Retrieves a user profile from your database without authenticating the user.</td>
      <td><code>email</code></td>
    </tr>

    <tr>
      <td><strong>Delete</strong></td>
      <td>Executes when a user is deleted using the API or Auth0 Dashboard.</td>
      <td><code>id</code></td>
    </tr>
  </tbody>
</table>

To learn more about the scripts, read [Custom Database Action Script Templates](/docs/authenticate/database-connections/custom-db/templates) and [Custom Database Action Script Execution Best Practices](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/execution).

### Create a Login script

<Card title="Avoid user ID collisions with multiple databases">
  The `id` (or alternatively `user_id`) property in the returned user profile will be used by Auth0 to identify the user.

  If you are using multiple custom database connections, then `id` value must be unique across all the custom database connections to avoid user ID collisions. Our recommendation is to prefix the value of `id` with the connection name (omitting any whitespace). To learn more about user IDs, read [Identify Users](/docs/manage-users/user-accounts/identify-users).
</Card>

The following steps use an example for a MySQL database login script

1. After toggling the **Use my own database** switch, the **Database Action Scripts** area is enabled. Make sure you are on the **Login** tab.
2. Use the **Templates** dropdown to select the MySQL database script template.

   ```javascript lines expandable theme={null}
   function login(email, password, callback) {
     var bcrypt = require('bcrypt');
     var mysql = require('mysql');
     var connection = mysql.createConnection({
       host: 'localhost',
       user: 'me',
       password: 'secret',
       database: 'mydb'
     });
     connection.connect();
     var query = "SELECT id, nickname, email, password " +
       "FROM users WHERE email = ?";
     connection.query(query, [email], function (err, results) {
       if (err) return callback(err);
       if (results.length === 0) return callback(new WrongUsernameOrPasswordError(email));
       var user = results[0];
       bcrypt.compare(password, user.password, function (err, isValid) {
         if (err) {
           callback(err);
         } else if (!isValid) {
           callback(new WrongUsernameOrPasswordError(email));
         } else {
           callback(null, {
             // This prefix (replace with your own custom DB name)
             // ensure uniqueness across different custom DBs if there's the
             // possibility of collisions (e.g. if the user ID is an email address or an integer)
             id: 'MyConnection1|' + user.id.toString(),
             nickname: user.nickname,
             email: user.email
           });
         }
       });
     });
   }
   ```

   The above script connects to a MySQL database and executes a query to retrieve the first user with `email == user.email`.
   With the `bcrypt.compareSync` method, it then validates that the passwords match, and if successful, returns an object containing the user profile information including `id`, `nickname`, and `email`.
   This script assumes that you have a `users` table containing these columns. The `id` returned by Login script is used to construct the user ID attribute of the user profile.
3. Select **Save and Try**.
4. In the pop-up modal, enter your email and password and click **Try**. This provides a dropdown to select from a list of available runtimes, with your current runtime on top.

   <Frame>
     <img alt="Modal to try the login script." />
   </Frame>

Script templates are not used by Auth0 until you select **Save** or **Try**. This is true even if you only modify one script and haven't made changes to any others. You must choose **Save** at least once for all the scripts to be in place.

## Custom database support for Organizations

If you use custom database connections in conjunction with Organizations, you can use the `context` parameter in the script signature to make Organization details like `id`, `name`, and `metadata` available to your custom database action scripts. Organization data is passed in the context object when the associated action happens in the context of an organization; for example, when a user authenticates on an organization’s login prompt, the login action script is passed. To learn more, read [Database Connections](/docs/authenticate/database-connections).

### Enable context object

1. Navigate to [Auth0 Dashboard > Authentication > Database](https://manage.auth0.com/dashboard/us/#/connections/database/).
2. Select your database connection.
3. Under the **Custom Database** tab, find **Context objects in database scripts** and select **Enable**.

   <Warning>
     This feature cannot be disabled once toggled.
   </Warning>
4. On the confirmation prompt, select **Confirm**.

### Use Organization context

Once the context object is enabled in Dashboard, you can add a `context` object to your custom database action scripts, inserted directly preceding the callback parameter. When events are triggered with Organization context, the corresponding data is made available to your custom database action scripts in the format below:

<Tabs>
  <Tab title="Login">
    ```json lines theme={null}
    {
        "organization": {
            "display_name": "My Organization",
            "id": "org_XXXXXX",
            "metadata": {
                "example": "value"
            },
            "name": "my-organization"
        }
    }
    ```
  </Tab>

  <Tab title="Create">
    ```json lines theme={null}
    {
        "organization": {
            "display_name": "My Organization",
            "id": "org_XXXXXX",
            "metadata": {
                "example": "value"
            },
            "name": "my-organization"
        }
    }
    ```
  </Tab>

  <Tab title="Verify">
    ```json lines theme={null}
    {
        "organization": {
            "display_name": "My Organization",
            "id": "org_XXXXXX",
            "metadata": {
                "example": "value"
            },
            "name": "my-organization"
        }
    }
    ```
  </Tab>

  <Tab title="Change Password">
    ```json lines theme={null}
    {
        "organization": {
            "display_name": "My Organization",
            "id": "org_XXXXXX",
            "metadata": {
                "example": "value"
            },
            "name": "my-organization"
        }
    }
    ```
  </Tab>

  <Tab title="Get User">
    ```json lines theme={null}
    {
        "organization": {
            "display_name": "My Organization",
            "id": "org_XXXXXX",
            "metadata": {
                "example": "value"
            },
            "name": "my-organization"
        }
    }
    ```
  </Tab>

  <Tab title="Delete" />
</Tabs>

<Callout icon="file-lines">
  An empty context will always be passed to the `delete` script.
</Callout>

## Add configuration parameters

You can store parameters, like the credentials required to connect to your database, in the **Settings** section below the script editor. These will be available for all of your scripts, and you can access the parameter values using the `configuration` object in your database action scripts (i.e., `configuration.MYSQL_PASSWORD`).

Use the added parameters in your scripts to configure the connection. For example, you might add the following to the MySQL Login script:

```javascript lines theme={null}
function login (username, password, callback) {
  var mysql = require('mysql');
  var connection = mysql.createConnection({
    host     : configuration.MYSQL_HOST,
    user     : 'me',
    password : configuration.MYSQL_PASSWORD,
    database : 'mydb'
  });
}
```

## Learn more

* [Custom Database Connection and Action Script Best Practices](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts)
* [Troubleshoot Custom Databases](/docs/authenticate/database-connections/custom-db/error-handling)
* [Import and Export Users](/docs/manage-users/user-migration)


# Custom Database Connection and Action Script Best Practices
Source: https://auth0.com/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts

Learn about best practices for custom database connections and database action scripts.

<Card title="Availability varies by Auth0 plan">
  Both your specific login implementation and your Auth0 plan or custom agreement affect whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

Extensibility allows admins to add custom login in Auth0 as a mechanism for building out last-mile solutions for Identity and Access Management (IdAM). Each extensibility type uses Node.js and runs on the Auth0 platform in an Auth0 tenant.

Auth0 Extensibility comes in several forms:

* [Actions](/docs/customize/actions): Actions are secure, tenant-specific, versioned functions written in Node.js that execute at certain points within the Auth0 platform. Use actions to customize and extend Auth0's capabilities with custom login.
* [Rules](/docs/customize/rules): Run when artifacts for user authenticity are generated. For example:

  * ID Token in OpenID Connect (OIDC)
  * Access Token in OAuth 2.0
  * An assertion in SAML
* [Hooks](/docs/customize/hooks): Provide additional extensibility when there is an exchange of non-user-related artifacts and when user identities are created such as pre-user registration and post-user registration.

Below are some best practices for using Auth0 Extensibility products:

* Scripts for both custom database connections and migrations are used to integrate with an existing user identity store or where automatic user migration from an independent or legacy identity store are required. For more more configuration information, review [Create Custom Database Connections.](/docs/authenticate/database-connections/custom-db/create-db-connection)
* To avoid user duplications, set a consistent `user_id` on each returned user profile. Additionally, ensure that you don't return the same email address for two different users in the `get_user` or `login` script and make sure both scripts return the same user.
* To support backwards compatibility, `app_metadata` is called `metadata` in custom DB scripts. Since data transfer can be interrupted, use an Action to fetch the metadata that should be in `app_metadata` or `user_metadata` if it's missing.
* Ensure you restrict access to the <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> with an [Action](/docs/customize/actions).

Auth0 Extensibility is a comprehensive and sophisticated capability to tailor IdAM operations, but can also expose your database to improper or unintended use. The documents in this section highlight best practices to both designers and implementers; we recommend reading them in their entirety at least once, even if you've already started your journey with Auth0.

## Learn more

* [Custom Database Connection Anatomy Best Practices](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/anatomy)
* [Custom Database Action Script Environment Best Practices](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/environment)
* [Custom Database Action Script Execution Best Practices](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/execution)
* [Custom Database Connection Security Best Practices](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/connection-security)
* [Error Handling Best Practices](/docs/troubleshoot/error-handling-best-practices)


# Custom Database Connection Anatomy Best Practices
Source: https://auth0.com/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/anatomy

Learn about best practices for custom database connection anatomy.

You typically use a custom database connection to provide access to your own legacy identity store for authentication (sometimes referred to as **legacy authentication**) or [perform user import through automatic migration](/docs/manage-users/user-migration/configure-automatic-migration-from-your-database) (often referred to as **trickle** or **lazy** migration). You can also use custom database connections to proxy access to an Auth0 tenant in scenarios where you use Auth0 multi-tenant architecture. To learn more, read [Multi-Tenant Applications Best Practices](/docs/get-started/auth0-overview/create-tenants/multi-tenant-apps-best-practices).

You typically create and configure custom database connections using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. You create a database connection and then toggle **Use my own database** to enable editing of the database action scripts. A custom database connection can also be created and configured with the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> [Create a connection endpoint](https://auth0.com/docs/api/management/v2#!/Connections/post_connections) and the `auth0` strategy.

<Frame>
  <img alt="Auth0 Dashboard Authentication Database Connection Custom Database Settings Use Own Database Enabled" />
</Frame>

As shown below, you use custom database connections as part of a login workflow to obtain user identity information from your own legacy identity store for authentication or user import.

<Frame>
  <img alt="Custom Database Connection Flow" />
</Frame>

In addition to artifacts common for all database connection types, a custom database connection allows you to configure action scripts—custom code used when interfacing with legacy identity stores. The scripts you choose to configure depend on whether you are creating a connection for legacy authentication or for automatic migration.

Action scripts can be implemented as anonymous functions; however, anonymous functions make it hard to debug when it comes to interpreting the call-stack generated as a result of any exceptional error conditions. For convenience, we recommend providing a function name for each action script. To see some recommended names, read [Custom Database Action Script Execution Best Practices](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/execution).

In a legacy authentication scenario, no new user record is created; the user remains in the legacy identity store and Auth0 uses the identity it contains when authenticating the user. Custom database connections are also used outside of the <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> workflow. For example, a connection's `changePassword` action script is called when a password change operation occurs for a user that resides in a legacy identity store.

## Automatic migration

During automatic migration, Auth0 creates a new user in an identity store (database) managed by Auth0. Auth0 uses the identity in the Auth0-managed identity store when authenticating the user. For this to occur, Auth0 first requires the user to be authenticated against the legacy identity store, and only if this succeeds will the new user be created in the Auth0 managed database. Auth0 creates the new user using the same ID and password that was supplied during authentication.

User creation in an automatic migration scenario typically occurs after the Login action script completes. We recommend that you do not attempt to delete users from a legacy identity store as an inline operation within the Login script, but instead as an independent process. This prevents accidental user deletion should an error condition occur during migration.

With automatic migration, users remain in the legacy identity store and can be deleted or archived if required. A side-effect can occur where a user is deleted from Auth0 but remains in the legacy data store. In this case, a login made by the deleted user could result in either the Login or Get User script executing and the user again migrating from the legacy identity store.

We recommend marking legacy store user identities as migrated before either Login or Get User scripts complete and prior to any eventual legacy store deletion to prevent the unintentional recreation of intentionally-deleted users.

## Size

We recommend that the total size of any action script not exceed 100 KB. The larger the size, the more latency is introduced due to the packaging and transport process employed by the Auth0 platform, and this will have an impact on the performance of your system. Note that the 100 KB limit does not include any `npm` modules that may be referenced as part of any `require` statements.

## Learn more

* [Custom Database Connection Security Best Practices](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/connection-security)
* [Custom Database Action Script Execution Best Practices](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/execution)
* [Custom Database Action Script Environment Best Practices](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/environment)


# Custom Database Connection Security Best Practices
Source: https://auth0.com/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/connection-security

Learn about best practices for custom database connection security.

## Access legacy identity storage via custom API

We recommend that you implement an API to provide least privilege to your legacy identity storage rather than simply opening up general access via the internet.

Protecting legacy identity storage from general access is a recommended best practice. Exposing a (legacy identity) database directly to the internet, for example, can be extremely problematic: database interfaces for SQL and the like are extremely open in terms of functionality, which violates the principle of least privilege when it comes to security.

The alternative is to create a simple (custom) API—protected via use of an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>—that each action script can call. This would act as the interface to the legacy identity store. Client credentials grant flow can then be used to obtain an access token from within a script, and this can be subsequently cached for re-use within the `global` object to improve performance. The API can then provide a discrete number of protected endpoints that perform only the legacy (identity) management functionality required (e.g., read user, change password).

By default, Auth0 will give you a token for any API if you authenticate successfully and include the appropriate <Tooltip href="/docs/glossary?term=audience">audience</Tooltip>. Restricting access to the legacy identity store API by restricting access token allocation via the use of a rule will prevent unauthorized usage and will mitigate a number of attack vector scenarios, such as where redirect to `/authorize` is intercepted and the audience to the API is added.

<Warning>
  Restricting access to the API via Rule will mitigate attack vector scenarios, such as where redirect to `/authorize` is intercepted and the audience to the API is added, and will ensure that only access using specific client credentials is granted.
</Warning>

## Access to legacy identity storage

Whether managing access to legacy identity storage via custom API or using the native interface provided, you should restrict access to the list of IP addresses associated with your Auth0 tenant. To see the list of IP addresses, read [Auth0 IP Addresses for AllowLists](/docs/secure/security-guidance/data-security/allowlist). Adding URLs to the AllowList constrains access to the legacy identity store and ensures that only custom database actions scripts defined in Auth0 are permitted.

<Warning>
  The Auth0 IP address AllowList is shared between all Auth0 tenants defined to a region. Never use the allow list as the sole method of securing access to your legacy identity store; doing so could open up potential security vulnerabilities allowing unauthorized access to your users.
</Warning>

## Learn more

* [Secure](/docs/secure)
* [Token Best Practices](/docs/secure/tokens/token-best-practices)


# Custom Database Action Script Environment Best Practices
Source: https://auth0.com/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/environment

Learn about best practices for the custom database action script environment.

Action scripts execute as a series of called JavaScript functions in an instance of a serverless Webtask container. As part of this, a specific environment is provided, together with a number of artifacts supplied by both the Webtask container and the Auth0 <Tooltip href="/docs/glossary?term=authentication+server">authentication server</Tooltip> (your Auth0 tenant) itself.

## npm modules

Auth0 serverless Webtask containers can make use of a wide range of [`npm`](https://www.npmjs.com/) modules; `npm` modules not only reduce the overall size of action script code implementation, but also provide access to a wide range of pre-built functionality.

By default, a large list of publicly-available `npm` modules are supported out-of-the-box. This list has been compiled and vetted for any potential security concerns. To see which `npm` modules are supported, read [Can I require: Auth0 Extensibility](https://auth0-extensions.github.io/canirequire/).

If you require an `npm` module that is not supported out-of-the-box, then you can make a request via the [Auth0 Extensibility portal](https://auth0-extensions.github.io/canirequire/) or through your Auth0 representative. Auth0 will evaluate your request to determine suitability, if you need to escalate an unresolved request open a support ticket via the [Auth0 support portal](https://support.auth0.com/). There is currently no support in Auth0 for the use of `npm` modules from private repositories.

## Variables

Auth0 action scripts support the notion of environment variables, accessed via what is defined as the globally-available `configuration` object. The `configuration` object should be treated as read-only and should be used for storing sensitive information, such as credentials or API keys for accessing external identity stores. This mitigates having security-sensitive values hardcoded in an action script.

The `configuration` object can also be used to support whatever Software Development Life Cycle (SDLC) best practice strategies you employ, such as [setting up multiple environments](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments), by allowing you to define variables that have tenant-specific values. This mitigates hardcoded values in an action script, which may change depending upon which tenant is executing it.

## global object

Auth0 serverless Webtask containers are provisioned from a pool that is associated with each Auth0 tenant. Each container instance makes available a global object, which can be accessed across all action scripts that execute within it (the container instance). The global object acts as a global variable that is unique to the container and that can be used to define information—or even functions—that can be used across all action scripts that run in it (the container instance).

This means that the global object can be used to cache expensive resources, as long as those resources are not user-specific. For example, an <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> for a third-party (e.g., logging) API that provides non user-specific functionality could be stored. Or it could be used to store an Access Token to your own non user-specific API defined in Auth0 and obtained via use of the Client Credentials flow.

<Warning>
  An action script may execute in any of the container instances already running or in a newly-created container instance (which may subsequently be added to the pool). There is no container affinity for action script execution in Auth0. This means that you should avoid storing any user-specific information in the global object and should always ensure that any declaration made within the global object provides for initialization too.
</Warning>

Each time a Webtask container is recycled, or for each instantiation of a new Webtask container, the global object it defines is reset. Thus, any declaration of assignment within the global object associated with a container should also include provision for initialization. To provide performance flexibility, serverless Webtask containers are provisioned in Auth0 on an ad-hoc basis and are also subject to various recycle policies. In general, we recommend that you do not consider the life of a global object to be anything more than 20 minutes.

## Custom database connection environment checklist

* Make sure that your database has the appropriate fields to store user profiles attributes, such as **id**, **nickname**, **email**, and **password**. To learn more about Auth0's user profile schema and expected fields, read [Normalized User Profiles](/docs/manage-users/user-accounts/user-profiles/normalized-user-profiles). To learn how to update user profiles, read [Update User Profiles Using Your Database](/docs/manage-users/user-accounts/user-profiles/update-user-profiles-using-your-database).
* You can use return errors resulting from your custom database connection for troubleshooting purposes.
* The `id` (or alternatively `user_id`) property in the returned user profile will be used by Auth0 to identify the user. If you are using multiple custom database connections, then the **id** value **must be unique across all the custom database connections** to avoid **user ID** collisions. Our recommendation is to prefix the value of **id** with the connection name (omitting any whitespace). To learn more about user IDs, read [Identify Users](/docs/manage-users/user-accounts/identify-users).
* Latency will be greater compared to Auth0-hosted user stores.
* The database or service must be reachable from the Auth0 servers. You will need to configure inbound connections if your store is behind a firewall.

## Testing a specific runtime version

The runtime version for custom Database scripts is defined at **Dashboard > Settings > Advanced** within the **Extensibility** section.

Follow these steps to test a single custom database script on a specific runtime version:

1. Navigate to **Authentication > Database.**
2. Select the Database connection where you have defined a custom script.
3. From within the selected database connection's page, select the **Custom Database** tab.
4. Scroll to **Database Action Scripts** section of the page.
5. Select the specific script you want to verify (eg. Login, Create etc) on the respective tab.
6. Select **Save and Try**. This loads a modal with specific test parameters and sample context details. Update as needed.
7. Select **Try** from the modal to open a dropdown selector for a specific Node version.
8. The test would trigger upon selecting the desired Node version and results would show up in a message on the same screen.

## Learn more

* [Custom Database Action Script Execution Best Practices](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/execution)
* [Error Handling Best Practices](/docs/troubleshoot/error-handling-best-practices)
* [Debugging Best Practices](/docs/troubleshoot/debugging-best-practices)
* [Deployment Best Practices](/docs/deploy-monitor/deployment-best-practices)
* [Custom Database Connection Security Best Practices](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/connection-security)


# Custom Database Action Script Execution Best Practices
Source: https://auth0.com/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/execution

Learn about best practices for custom database action script execution.

A custom database connection type allows you to configure action scripts, which contain custom code Auth0 uses to interface with your legacy identity store. Action scripts are a named JavaScript function that accepts a predefined set of parameters.

## Webtask containers

Action scripts execute within an individual Webtask container with an execution limit of approximately 20 seconds. After the functions execute, the container is recycled.

When a container is recycled, it terminates the action script’s pending operations. This may result in an error condition being returned and a potential reset of the `global` object. For more information on the `global` object, read [Custom Database Action Script Environment Best Practices](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/environment).

## Asynchronous features

Asynchronous features of JavaScript, including [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) objects and [async functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function), are supported in action scripts.

You can use asynchronous features to execute non-blocking operations within an action script, but make sure that these operations do not exceed the execution limit of the Webtask container. When the Webtask container is recycled, it will terminate any pending operations, which may result in unexpected behavior or an error.

If you are making a call to an external service or API within your action script, set the function to time out after a reasonable duration, and [return an error](#error-handling) if the external service or API cannot be reached.

### Examples

Auth0 supports using [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) objects and [async functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) within action scripts.

#### Promise object

This example uses the built-in JavaScript `fetch` method, which gets a resource from a network then returns a Promise object, written using [promise chains](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises#chaining).

```javascript lines expandable theme={null}
function login(userNameOrEmail, password, callback) {
	const hashedPassword = hash(password);
	const apiEndpoint = 'https://example.com/api/authenticate';
	const options = {
		method: 'POST',
		body: {
			email: userNameOrEmail,
			password: hashedPassword
		}
	};

	fetch(apiEndpoint, options) 
		.then((response) => {
			if (!response.ok) {
				return callback(new Error(`HTTP error! Status: ${response.status}`));
			}

			return response.json();
		})
		.then((response) => {
			if (response.err) {
				return callback(new Error(`Error authenticating user: ${err}`));
			}

			let profile = {
				email: response.profileData.email,
				username: response.profileData.username
			};

			return callback(null, profile);
		})
		.catch((err) => {
			return callback(new Error(`An error occurred: ${err}`));
		});
  }
```

#### Async function

This example uses the built-in JavaScript `fetch` method, which gets a resource from a network then returns a Promise object, written using [async functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function).

```js lines expandable theme={null}
async function login(userNameOrEmail, password, callback) {
	const hashedPassword = hash(password);
	const apiEndpoint = 'https://example.com/api/authenticate';
	const options = {
		method: 'POST',
		body: {
			email: userNameOrEmail,
			password: hashedPassword
		}
	};

	const response = await fetch(apiEndpoint, options);

	if (!response.ok) {
		return callback(new Error(`HTTP error! Status: ${response.status}`));
	}

	const result = response.json();

	if (result.err) {
		return callback(new Error(`Error authenticating user: ${err}`));
	}

	let profile = {
		email: response.profileData.email,
		username: response.profileData.username
	};

	return callback(null, profile);
}
```

## Callback function

The `callback` function signals the action script’s operation is complete and must be called exactly once. An action script should complete immediately after a call to the `callback` function, preferably by explicitly using the `return` statement.

<Warning>
  If the `callback` function is called more than once, then it may lead to unexpected results and/or errors.

  If the `callback` function is not called at all, then execution of the action script will stall, and an error will be returned when the Webtask container is recycled.
</Warning>

### Asynchronous processing

If an action script uses asynchronous processing, then the `callback` function must be called after all asynchronous operations complete.

### Parameters

If the `callback` function is called with no parameters, it will be executed as if a `null` parameter had been provided.

## Size

The total size of implementation for any action script must not exceed 100kB. This size limitation excludes imported `npm` modules. For more information on `npm` modules, read [Custom Database Action Script Environment Best Practices](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/environment).

The larger the size of a script, the more latency is introduced based on the packaging and transport process employed by the Webtask platform. The size impacts the performance of the system.

## Anonymous functions

Action scripts can be implemented as anonymous functions, but it is not recommended that you do so. Anonymous functions make it difficult to debug the action script and interpret the call-stack generated as a result of any exceptional error condition. To learn more about anonymous functions, read [IIFE on MDN Web Docs](https://developer.mozilla.org/en-US/docs/Glossary/IIFE).

## Error handling

Pass an `Error` object to the `callback` function with a descriptive message of the error:

```js lines theme={null}
return callback(new Error('My custom error message'));
```

## Security

### Database interface vs. API

Ensure to secure all communications between Auth0 and your legacy identity store. If your legacy identity store does not already have an API implemented, it is highly recommended that you do so.

If your legacy identity store has an API available, you can [register the API](/docs/get-started/auth0-overview/set-up-apis) through Auth0, and [create an Action](/docs/manage-users/access-control/sample-use-cases-actions-with-authorization#deny-access-to-anyone-calling-an-api) to restrict access from end users.

If your legacy identity store does not have an API available—and implementing one is not feasible—you can still communicate with your database directly. Make sure to [add Auth0 IP addresses to your firewall’s allow list](/docs/secure/security-guidance/data-security/allowlist) to allow inbound traffic from Auth0.

## Identity provider tokens

If the `user` object returns the `access_token` and `refresh_token` properties, Auth0 handles them differently from other types of user information. Auth0 stores them in the `user` object's `identities` property:

```json lines theme={null}
{
	"email": "you@example.com",
	"updated_at": "2019-03-15T15:56:44.577Z",
	"user_id": "auth0|some_unique_id",
	"nickname": "a_nick_name",
	"identities": [ 
		{
			"user_id": "some_unique_id",
			"access_token": "e1b5.................92ba",
			"refresh_token": "a90c.................620b",
			"provider": "auth0", 
			"connection": "custom_db_name",
			"isSocial": false 
		}
  ], 
  "created_at": "2019-03-15T15:56:44.577Z",
  "last_ip": "192.168.1.1",
  "last_login": "2019-03-15T15:56:44.576Z",
  "logins_count": 3
}
```

If you want to retrieve either of these properties with the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>, include the `read:user_idp_tokens` scope when [requesting an Access Token](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production).


# Troubleshoot Custom Databases
Source: https://auth0.com/docs/authenticate/database-connections/custom-db/error-handling

Describes how to handle errors and troubleshoot when using your database as an identity provider.

You can use return errors resulting from your custom database connection for troubleshooting purposes. We will also cover some basic troubleshooting steps for your scripts.

## Types of errors

You may receive different types of errors from a database connection:

<table>
  <thead>
    <tr>
      <th>Error</th>
      <th>Login Script</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>new WrongUsernameOrPasswordError(\<email or user\_id>, \<message>)</code></td>
      <td>Login</td>
      <td>Occurs when the user's credentials are invalid. Passing no arguments or a falsey first argument will result in the error being logged as an <code>fu</code> event (invalid username/email) with an empty string for a <code>user\_id</code>. Providing a truthy first argument will result in the error being logged as an <code>fp</code> event (the user exists, but the password is invalid) with a <code>user\_id</code> value of <code>auth0|\<first argument></code>. To learn more, read <a href="/docs/deploy-monitor/logs/log-event-type-codes">Log Event Type Codes</a>.</td>
    </tr>

    <tr>
      <td><code>new ValidationError(\<user\_exists>, \<message>)</code></td>
      <td>Create</td>
      <td>Occurs when a user already exists in your database.</td>
    </tr>

    <tr>
      <td><code>callback(\<null>,\<false>)</code></td>
      <td>Change Password</td>
      <td>Occurs when the user's password was not updated.</td>
    </tr>

    <tr>
      <td><code>callback(\<null>)</code></td>
      <td>Get User</td>
      <td>Occurs when the user is not found.</td>
    </tr>

    <tr>
      <td><code>new UnauthorizedError(\<message>)</code></td>
      <td>All Login Scripts</td>
      <td>Occurs when something went wrong while trying to reach the database. Preferred way of communicating errors back from custom databases to front-end.</td>
    </tr>

    <tr>
      <td><code>new Error(\<message>)</code></td>
      <td>All Login Scripts</td>
      <td>Occurs when something went wrong while trying to reach the database.</td>
    </tr>

    <tr>
      <td><code>error code: auth0\_idp\_error; user already exists</code></td>
      <td>Create</td>
      <td>Occurs in legacy identity store when you attempt to create a user that already exists in your legacy identity store or in Auth0.</td>
    </tr>

    <tr>
      <td><code>error code: auth0\_idp\_error; user already exists</code></td>
      <td>Delete</td>
      <td>Occurs in legacy identity store when you attempt to delete a user with custom database scripts. Error could also manifest as <code>Error! There was a problem deleting [user@example.com](mailto:user@example.com)</code> or <code>Sandbox Error: Please implement the Delete script for this database connection at [https://manage.auth0.com/#/connections/database](https://manage.auth0.com/#/connections/database)</code>.</td>
    </tr>
  </tbody>
</table>

## Return errors

To return an error, call the **callback** function while passing **error** as the first parameter:

```js lines theme={null}
callback(error);
```

Example:

```js wrap lines theme={null}
callback(new ValidationError('email-too-long', 'Email is too long.'));
```

### Returning errors when using Lock

If you use Lock, you can [customize the error messages](/docs/customize/login-pages/classic-login/customize-lock-error-messages) that will be displayed by adding them to the dictionary.

## Troubleshooting errors

Test the script using the **Try** button.

If you do not get the expected result or you receive an error, use [Actions Real-time Logs](/docs/customize/actions/actions-real-time-logs), use `console.log()` statements in your script, and try the connection again. The output of `console.log()` will print to the Actions Real-time Logs window.

You may experience errors using action scripts to import, create, or delete users. Use `console.logs` to verify the error is a result of using action scripts. To learn more, read [Custom Database Action Script Templates](/docs/authenticate/database-connections/custom-db/templates).


# Authenticate with Your Own User Store
Source: https://auth0.com/docs/authenticate/database-connections/custom-db/overview-custom-db-connections

Learn about authenticating users using your database as an identity provider.

<Card title="Availability varies by Auth0 plan">
  Your Auth0 plan or custom agreement affects whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

Use a custom database connection when you want to provide access to your own independent (legacy) identity data store for the following purposes:

* **Authentication**: Use your database as an <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> in Auth0 to authenticate users. (Referred to as legacy authentication.)
* **Import Users**: Use automatic migration (trickle or lazy migration)
* **Proxy access to an Auth0 tenant**: Use Auth0 multi-tenant architecture.

You can create and configure a custom database connection by doing one of the following tasks:

1. Use the [Create connections](https://auth0.com/docs/api/management/v2#!/Connections/post_connections) endpoint with the `auth0` strategy.
2. Navigate to [Auth0 Dashboard > Authentication > Database](https://manage.auth0.com/#/connections/database), create the connection, and enable the **Use my own database** option to allow database action script editing.

   <Frame>
     <img alt="Enable Custom Database Use My Own Database Option" />
   </Frame>

## How it works

As shown in the diagram below, you use custom database connections as part of <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> workflow in order to obtain user identity information from your own, legacy identity store.

<Frame>
  <img alt="Custom Database Connections Anatomy" />
</Frame>

In addition to artifacts common for all [database connection](/docs/authenticate/database-connections) types, a custom database connection allows you to configure action scripts: custom code that’s used when interfacing with your legacy identity store. Auth0 provides [custom database action script templates](/docs/authenticate/database-connections/custom-db/templates) for configuration, and the ones you use will depend on whether you are creating a custom database connection for legacy authentication or for automatic migration.

<Card title="Best practice">
  Action scripts can be implemented as anonymous functions, however anonymous functions make it hard in debugging situations when it comes to interpreting the call-stack generated as a result of any exceptional error condition. For convenience, we recommend providing a function name for each action script.
</Card>

### Legacy authentication scenario

In a legacy authentication scenario, a new user record is created within Auth0 during the user's first login, but Auth0 does not store a hash of the user's password. Auth0 will always use the legacy identity store and the identity it contains when authenticating the user.

<Callout icon="file-lines">
  Custom database connections are also used outside of Universal Login workflow. For example, a connection's `changePassword` action script is called when a password change operation occurs for a user that resides in a legacy identity store.
</Callout>

### Automatic migration scenario

During automatic or trickle migration, Auth0 creates a new user in an identity store (database) managed by Auth0. From then on, Auth0 always uses the identity in the Auth0 managed identity store for authenticating the user. For this to occur, first Auth0 requires the user be authenticated against the legacy identity store and only if this succeeds will the new user be created. The new user will be created using the same id and password that was supplied during authentication.

<Card title="Best practice">
  Creation of a user in an automatic migration scenario typically occurs after the `login` action script completes. We therefore recommend that you do not attempt any deletion of a user from a legacy identity store as an inline operation (i.e., within the `login` script) but perform the deletion as an independent process. This will prevent accidental deletion of a user should an error condition occur during the migration process.
</Card>

In an automatic migration scenario, users remain in the legacy identity store and can be deleted or archived if required. One side effect of this can occur if a user is deleted from Auth0 but still remains present in the legacy identity store. In this case, a login actioned by the deleted user could result in either the `login` and/or `getUser` script being executed and the user being migrated from the legacy identity store once again.

<Card title="Best practice">
  We recommend marking any legacy user identity as having been migrated before either `login` or `getUser` completes and prior to any eventual legacy store deletion.
</Card>

## Size

The total size of implementation for any action script should not exceed 100 kB. The larger the size the more latency is introduced due to the packaging and transport process employed by the Auth0 serverless Webtask platform, and this will have an impact on the performance of your system.

<Callout icon="file-lines">
  The 100 kB limit does not include any `npm` modules that may be referenced as part of any require statements.
</Callout>

## Environment

Action scripts execute as a series of called JavaScript functions in an instance of a serverless Webtask container. As part of this, a specific environment is provided, together with a number of artifacts supplied by both the Webtask container and the Auth0 <Tooltip href="/docs/glossary?term=authentication+server">authentication server</Tooltip> (your Auth0 tenant) itself.

### npm modules

Auth0 serverless Webtask containers can make use of a [wide range of npm modules](https://auth0-extensions.github.io/canirequire/); `npm` modules not only reduce the overall size of action script code implementation, but also provide access to a wide range of pre-built functionality.

Many publicly available `npm` modules are supported out-of-the-box. The list has been compiled and vetted for any potential security concerns. If you require an `npm` module that is not supported out-of-the-box, then you can make a request through the [Auth0 support portal](https://support.auth0.com) or your Auth0 representative. Auth0 will evaluate your request to determine suitability. There is currently no support in Auth0 for the user of `npm` modules from private repositories.

### Variables

Auth0 action scripts support environment variables, accessed via what is known as the globally-available `configuration` object. To learn more, read the Add Configuration Parameters section in [Create Custom Database Connections](/docs/authenticate/database-connections/custom-db/create-db-connection).

<Card title="Best practice">
  The `configuration` object should be treated as read-only, and should be used for storing sensitive information such as credentials or API keys for accessing external identity stores. This mitigates having security sensitive values hard coded in an action script.
</Card>

The configuration object can also be used to support whatever [Software Development Life Cycle (SDLC)](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments) strategies you employ by allowing you to define variables that have tenant specific values. This mitigates hard coded values in an action script which may change depending upon which tenant is executing it.

### global object

Auth0 serverless Webtask containers are provisioned from a pool that's associated with each Auth0 tenant. Each container instance makes available the `global` object, which can be accessed across all action scripts that execute within the container instance. The `global` object acts as a global variable that’s unique to the container, and that can be used to define information or functions used across all action scripts that run in the container instance.

This means that the `global` object can be used to cache expensive resources as long as those resources are not user-specific. For example, you could use it to store an <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> for a third-party (logging) API that provides non-user-specific functionality. Or you could store an Access Token to your own non-user-specific API defined in Auth0 and obtained via the [Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow).

<Warning>
  An action script may execute in any of the container instances already running, or in a newly created container instance (which may subsequently be added to the pool). There is no container affinity for action script execution in Auth0. This means that you should avoid storing any user-specific information in the `global` object, and should always ensure that any declaration made within the `global` object provides for initialization too.
</Warning>

Each time a Webtask container is recycled, or for each instantiation of a new Webtask container, the `global` object it defines is reset. Thus, any declaration of assignment within the `global` object associated with a container should also include provision for initialization too.

<Card title="Best practice">
  To provide performance flexibility, serverless Webtask containers are provisioned in Auth0 on an ad-hoc basis and are also subject to various recycle policies. In general, we recommend that you do not consider the life of a `global` object to be anything more than 20 minutes.
</Card>

## Security

### Access legacy identity storage via custom API

Protecting legacy identity storage from general access is a recommended best practice. Exposing a database directly to the internet, for example, can be extremely problematic: database interfaces for SQL and the like are extremely open in terms of functionality, which violates the principle of least privilege when it comes to security.

<Card title="Best practice">
  We recommend that you implement an API to provide least privilege to your legacy identity store (database), rather than simply opening up general access via the internet.
</Card>

The alternative is to create a simple (custom) API, protected via use of an access token, that each action script can call. This would act as the interface to the legacy identity store. Client credentials grant flow can then be used to obtain an access token from within a script, and this can subsequently be cached for reuse in the `global` object in order to improve performance. The API can then provide a discrete number of protected endpoints that perform only the legacy management functionality required (for example, `read user`, `change password`).

<Card title="Best practice">
  By default, Auth0 will give you a token for any API if you authenticate successfully and include the appropriate audience. Restricting access to the legacy identity store API by restricting access token allocation via use of a Rule, will prevent unauthorized usage and mitigate a number of attack vector scenarios, such as where redirect to `/authorize` is intercepted and the audience to the API is added.
</Card>

### Allowlist access to legacy identity storage

Whether managing access to a legacy identity store via custom API, or using the native interface provided, restricting access to the list of IP addresses associated with your Auth0 tenant. Allowlisting constrains access to the legacy identity store ensuring that only custom database action scripts defined in Auth0 are permitted.

<Warning>
  The Auth0 IP address allowlist is shared among all Auth0 tenants defined to a region. Never use the allowlist as the sole method of securing access to your legacy identity store; doing so could open up potential security vulnerabilities allowing unauthorized access to your users.
</Warning>

## Learn more

* [Create Custom Database Connections](/docs/authenticate/database-connections/custom-db/create-db-connection)
* [Custom Database Action Script Templates](/docs/authenticate/database-connections/custom-db/templates)
* [Troubleshoot Custom Databases](/docs/authenticate/database-connections/custom-db/error-handling)
* [Import and Export Users](/docs/manage-users/user-migration)


# Custom Database Action Script Templates
Source: https://auth0.com/docs/authenticate/database-connections/custom-db/templates

Learn about custom database action script templates.

<Card title="Availability varies by Auth0 plan">
  Your Auth0 plan or custom agreement affects whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

If you have your own database (known as a legacy data store in Auth0) containing user identity data, you can use it as an <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> to authenticate users.
You create and configure the connection to your legacy data store as a custom database in Auth0. You can choose to migrate data to Auth0's data store from your legacy database incrementally over time, or you can continue to use it without migrating data. We provide script templates to perform functions on the custom database that you can use and customize.

There are two different types of custom database scripts:

* **Automatic Migration**: Whenever a user logs into Auth0, if the user is not yet in Auth0, the script will check the legacy database to see if the user exists there. If found and the **Import users to Auth0** flag is turned on, the user data migrates the user to Auth0 data store. This capability is sometimes called **trickle migration** or **lazy migration**.
* **Legacy Database**: Auth0 will always query the underlying database when a user tries to log in, is created, changes their password, verifies their email, or is deleted. If found and the **Import users to Auth0** flag is **not** turned on, user data stays in the legacy database and does **not** migrate to Auth0.

Auth0 provides the following custom database action scripts:

* [Change Password](/docs/authenticate/database-connections/custom-db/templates/change-password)
* [Create User](/docs/authenticate/database-connections/custom-db/templates/create)
* [Delete User](/docs/authenticate/database-connections/custom-db/templates/delete)
* [Get User](/docs/authenticate/database-connections/custom-db/templates/get-user)
* [Login](/docs/authenticate/database-connections/custom-db/templates/login)
* [Verify User](/docs/authenticate/database-connections/custom-db/templates/verify)
* [Change Email](/docs/authenticate/database-connections/custom-db/templates/change-email)

<Card title="Network firewall">
  If you are behind a firewall, this feature may require that you add the appropriate Auth0 IP addresses to the Allow List to work properly.
</Card>

## Script execution

As described in [Custom Database Connections](/docs/authenticate/database-connections/custom-db), a custom database connection type allows you to configure action scripts: custom code that is used when interfacing with your legacy identity store. Each action script is essentially a named JavaScript function that is passed a number of parameters, with the name of the function and the parameters passed depending on the script.

### Limits

Action script execution supports the asynchronous nature of JavaScript, and constructs such as [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) objects can be used. Asynchronous processing effectively results in suspension pending completion of an operation, and an Auth0 serverless Webtask container typically has a 20-second execution limit, after which the container may be recycled. Recycling a container due to this limit will prematurely terminate operation, ultimately resulting in an error condition being returned (as well as resulting in a potential reset of the `global` object).

### Completion and the callback function

The `callback` function supplied to each action script effectively acts as a signal to indicate completion of operation. An action script should complete immediately following a call to the `callback` function (either implicitly or by explicitly executing a JavaScript return statement) and should refrain from any other operation.

<Warning>
  The Auth0 supplied `callback` function must be called exactly **once**; calling the function more than once within an action script will lead to unpredictable results and/or errors.
</Warning>

<Callout icon="file-lines">
  Where `callback` is executed with no parameters, as in `callback()`, the implication is that function has been called as though `callback(null)` had been executed.
</Callout>

If an action script uses asynchronous processing, then a call to the `callback` function must be deferred to the point where asynchronous processing completes, and must be the final thing called. Asynchronous execution will result in a JavaScript `callback` being executed after the asynchronous operation is complete; this callback is typically fired at some point after the main (synchronous) body of a JavaScript function completes.

<Warning>
  Failure to execute the `callback` function will result in a stall of execution, and ultimately in an error condition being returned. The action script must call the `callback` function exactly once: the `callback` function must be called at least once in order to prevent stall of execution, however it must not be called more than once otherwise unpredictable results and/or errors will occur.
</Warning>

## Learn more

* [Custom Database Action Script Execution Best Practices](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/execution)
* [Troubleshoot Custom Databases](/docs/authenticate/database-connections/custom-db/error-handling)


# Change Email Script Template
Source: https://auth0.com/docs/authenticate/database-connections/custom-db/templates/change-email

Describes the custom database action script for changing a user's email.

The Change Email script implements the defined function when a user's email address or their email address verification status changes. We recommend naming this function `changeEmail`.

The script is only used in a [legacy authentication scenario](/docs/authenticate/database-connections/custom-db/overview-custom-db-connections), and is required if you want to update a user's email address (and/or email address verification status) in Auth0 and your external database in the same operation.

The Change Email script is not configurable through the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. To manage this script, you must use the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> [Create a connection](https://auth0.com/docs/api/management/v2#!/Connections/post_connections) or [Update a connection](https://auth0.com/docs/api/management/v2#!/Connections/patch_connections_by_id) endpoint, or the [Auth0 Deploy CLI](/docs/deploy-monitor/deploy-cli-tool).

<Warning>
  If you manage a custom database connection's Database Action Scripts through the Auth0 Dashboard, the Change Email script will be automatically deleted upon saving.

  To ensure that the Change Email script is not removed accidentally, use the Auth0 Management API or Auth0 Deploy CLI when managing the connection.

  If you manually change a user's email in your custom database, you must patch the user separately; Auth0 will not automatically detect the change.
</Warning>

## ChangeEmail function

The changeEmail function should:

* Update the user's email address in the external database.
* Return an error if the operation failed or an error occurred.

### Definition

The `changeEmail` function accepts four parameters and returns a `callback` function:

```js lines theme={null}
changeEmail(email, newEmail, verified, callback): function
```

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>email</code></td>
      <td>String</td>
      <td>User's current email address.</td>
    </tr>

    <tr>
      <td><code>newEmail</code></td>
      <td>String</td>
      <td>Value to be set as user's new email address in external database.</td>
    </tr>

    <tr>
      <td><code>verified</code></td>
      <td>Boolean</td>
      <td>Email verification status of the new email address.</td>
    </tr>

    <tr>
      <td><code>callback</code></td>
      <td>Function</td>
      <td>Used to pass error data through the pipeline.</td>
    </tr>
  </tbody>
</table>

### Example

This is a pseudo-JavaScript example of how you could implement the `changeEmail` function:

```javascript lines expandable theme={null}
function (email, newEmail, verified, callback) {
  // Prepare the API call
  let options = {
    url: "https://example.com/api/users",
    action: "PATCH",
    body: {
      email: email,
      new_email: newEmail,
      email_verified: verified
    }
  };

  // Call the API
  send(options, err => {
    // Return `false` value in callback if operation failed
    if (err && err.id == "FAIL_CHANGE_EMAIL") {
      return callback(null, false);
    } else if (err) {
      // Return error in callback if unspecified error occurred
      return callback(new Error("My custom error message."));
    }

    // Return `true` value in callback if operation succeeded
    return callback(null, true);
  });
}
```

## Callback function

The `callback` function accepts two parameters and returns a function.

### Definition

```js lines theme={null}
callback(error, operationResult): function
```

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Required</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>error</code></td>
      <td>Object</td>
      <td>Required</td>
      <td>Contains error data.</td>
    </tr>

    <tr>
      <td><code>operationResult</code></td>
      <td>Boolean</td>
      <td>Optional</td>
      <td>Indicates the result of the change email operation.</td>
    </tr>
  </tbody>
</table>

### Return a success

If the change email operation succeeded, return the `callback` function, and pass a `null` value as the `error` parameter and a `true` value as the `operationResult` parameter:

```js lines theme={null}
return callback(null, true);
```

### Return a failure

If the change email operation failed, return the `callback` function, and pass a `null` value as the `error` parameter and a `false` value as the `operationResult` parameter:

```js lines theme={null}
return callback(null, false);
```

### Return an error

If an error occurred, return the `callback` function, and pass relevant error information as the `error` parameter:

```js lines theme={null}
return callback(new Error("My custom error message."));
```

## Learn more

* [Change Password Script Templates](/docs/authenticate/database-connections/custom-db/templates/change-password)
* [Create Script Templates](/docs/authenticate/database-connections/custom-db/templates/create)
* [Delete Script Templates](/docs/authenticate/database-connections/custom-db/templates/delete)
* [Get User Script Templates](/docs/authenticate/database-connections/custom-db/templates/get-user)
* [Login Script Templates](/docs/authenticate/database-connections/custom-db/templates/login)
* [Verify Script Templates](/docs/authenticate/database-connections/custom-db/templates/verify)


# Change Password Script Templates
Source: https://auth0.com/docs/authenticate/database-connections/custom-db/templates/change-password

Describes custom database action script templates for changing a user's password.

The Change Password script implements the defined function to change the specified user's password in the external database. We recommend naming this function `changePassword`.

The script is used only in a [legacy authentication scenario](/docs/authenticate/database-connections/custom-db/overview-custom-db-connections) and is required if you want to change a user's password in the external database. It will execute when a user performs a [password reset workflow](/docs/customize/login-pages/classic-login/customize-password-reset-page), or when a password change workflow is started from the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## ChangePassword function

The `changePassword` function should:

* Update the user's password in the external database.
* Return `true` (or an object containing the `last_password_reset` property) if the password change operation succeeded. If the `last_password_reset` property is present in the object, it will be updated on the user's profile.
* Return `false` if the password change operation failed.
* Return an error if the external database could not be reached.

### Definition

The `changePassword` function accepts three parameters and returns a `callback` function:

```js lines theme={null}
changePassword(email, newPassword, callback): function
```

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>email</code></td>
      <td>String</td>
      <td>User's email address in Auth0 and external database.</td>
    </tr>

    <tr>
      <td><code>newPassword</code></td>
      <td>String</td>
      <td>Value to be set as user's new password in the external database. This value is sent as plaintext to the function and <a href="#Encryption">should be encrypted</a> before being sent to the external database.</td>
    </tr>

    <tr>
      <td><code>callback</code></td>
      <td>Function</td>
      <td>Used to pass data or operation result data through the pipeline.</td>
    </tr>
  </tbody>
</table>

### Example

This is a pseudo-JavaScript example of how you could implement the `changePassword` function. For language-specific examples, read [Language-specific script examples](#language-specific-script-examples).

```javascript lines expandable theme={null}
function changePassword(email, newPassword, callback) {
  // Hash the provided password 
  let hashedPassword = hash(newPassword);

  // Prepare the API call
  let options = {
    url: "https://example.com/api/users",
    body: {
      email: email,
      password: hashedPassword
    }
  };

  // Call the API
  send(options, err => {
    if (err && err.id == "FAIL_CHANGE_PASSWORD") {
      // Return false in callback if password change failed
      return callback(null, false);
    } else if (err) {
      // Return error in callback if other error occurred
      return callback(new Error("My custom error message.");
    } else {
      // Return true in callback if password change operation succeeded
      return callback(null, true);

      // Or return an object containing the `last_password_reset` property 
      // if the password change operation succeeded.
      // If the `last_password_reset` property is present in the object,
      // it will be updated on the user's profile.
      return callback(null, { "last_password_reset": Date.now() });
    }
  });
}
```

### Encryption

<Warning>
  Avoid logging, storing, or transporting the password credential anywhere in its unencrypted form.
</Warning>

To prevent any potential data leak, encrypt the password value using a cryptographic hash encryption library such as `bcrypt`.

#### Example

```js lines theme={null}
bcrypt.hash(password, 10, function (err, hash) {
    if (err) {
        return callback(err);
    } else {
        // Return hashed password
    }
});
```

## Callback function

The `callback` function accepts two parameters and is used to pass error data or indicate the result of the operation.

### Definition

```js lines theme={null}
callback(error, operationResult | resultObj): function
```

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Required</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>error</code></td>
      <td>Object</td>
      <td>Required</td>
      <td>Contains error data.</td>
    </tr>

    <tr>
      <td><code>operationResult</code></td>
      <td>Boolean</td>
      <td>Optional</td>
      <td>Indicates the result of the change password operation.</td>
    </tr>

    <tr>
      <td><code>resultObj</code></td>
      <td>Object</td>
      <td>Optional</td>
      <td>Indicates that the change password operation succeeded. If the <code>last\_password\_reset</code> property is present, it will be updated on the user's profile.</td>
    </tr>
  </tbody>
</table>

### Return a success

If the change password operation succeeded, return the `callback` function, and pass a `null` value as the `error` parameter and a `true` value as the `operationResult` parameter.

#### Example

```js lines theme={null}
return callback(null, true);
```

### Return a success and update last\_password\_reset attribute

If the change password operation succeeded, return the `callback` function, and pass a `null` value as the `error` parameter and an object value as the `profile` parameter. If `last_password_reset` attribute is provided in the object, it will be updated on the user's profile.

#### Example

```js lines theme={null}
return callback(null, { "last_password_reset": Date.now() });
```

### Return a failure

If the change password operation failed, return the `callback` function, and pass a `null` value as the `error` parameter and a `false` value as the `operationResult` parameter.

#### Example

```js lines theme={null}
return callback(null, false);
```

### Return an error

If an error occurs, return `callback` function, and pass relevant error information as the `error` parameter.

#### Example

```js lines theme={null}
return callback(new Error("My custom error message."));
```

## Language-specific script examples

Auth0 provides sample scripts for use with the following languages/technologies:

* [JavaScript](#javascript)
* [ASP.NET Membership Provider (MVC3 - Universal Providers)](#asp-net-membership-provider-mvc3-universal-providers-)
* [ASP.NET Membership Provider (MVC4 - Simple Membership)](#asp-net-membership-provider-mvc4-simple-membership-)
* [MongoDB](#mongodb)
* [MySQL](#mysql)
* [PostgreSQL](#postgresql)
* [SQL Server](#sql-server)
* [Windows Azure SQL Database](#windows-azure-sql-database)

### JavaScript

```javascript lines expandable theme={null}
function changePassword(email, newPassword, callback) {
  // This script should change the password stored for the current user in your
  // database. It is executed when the user clicks on the confirmation link
  // after a reset password request.
  // The content and behavior of password confirmation emails can be customized
  // here: https://manage.auth0.com/#/emails
  // The `newPassword` parameter of this function is in plain text. It must be
  // hashed/salted to match whatever is stored in your database.
  //
  // There are three ways that this script can finish:
  // 1. The user's password was updated successfully:
  //     callback(null, true);
  // 2. The user's password was not updated:
  //     callback(null, false);
  // 3. Something went wrong while trying to reach your database:
  //     callback(new Error("my error message"));
  //
  // If an error is returned, it will be passed to the query string of the page
  // to which the user is being redirected after clicking the confirmation link.
  // For example, returning `callback(new Error("error"))` and redirecting to
  // https://example.com would redirect to the following URL:
  //     https://example.com?email=alice%40example.com&message=error&success=false
  const msg = 'Please implement the Change Password script for this database ' +
    'connection at https://manage.auth0.com/#/connections/database';
  return callback(new Error(msg));
}
```

### ASP.NET Membership Provider (MVC3 - Universal Providers)

```javascript lines expandable theme={null}
function changePassword(email, newPassword, callback) {
  var crypto = require('crypto');
  var Connection = require('tedious').Connection;
  var Request = require('tedious').Request;
  var TYPES = require('tedious').TYPES
  var connection = new Connection({
    userName:  'the username',
    password:  'the password',
    server:    'the server',
    options: {
      database:  'the db name',
      // encrypt: true   for Windows Azure enable this
    }
  });
  /**
   * hashPassword
   *
   * This function creates a hashed version of the password to store in the database.
   *
   * @password  {[string]}      the password entered by the user
   * @return    {[string]}      the hashed password
   */
  function hashPassword(password, salt) {
    // the default implementation uses HMACSHA256 and since Key length is 64
    // and default salt is 16 bytes, Membership will fill the buffer repeating the salt
    var key = Buffer.concat([salt, salt, salt, salt]);
    var hmac = crypto.createHmac('sha256', key);
    hmac.update(Buffer.from(password, 'ucs2'));
    var hashed = hmac.digest('base64');
    return hashed;
  }
  connection.on('debug', function(text) {
      // if you have connection issues, uncomment this to get more detailed info
      //console.log(text);
  }).on('errorMessage', function(text) {
      // this will show any errors when connecting to the SQL database or with the SQL statements
    console.log(JSON.stringify(text));
  });
  connection.on('connect', function (err) {
    if (err) {
      return callback(err);
    }
    updateMembershipUser(email, newPassword, function(err, wasUpdated) {
      if (err) {
        return callback(err); // this will return a 500
      }
      callback(null, wasUpdated);
    });
  });
  function updateMembershipUser(email, newPassword, callback) {
    var salt            = crypto.randomBytes(16);
    var hashedPassword  = hashPassword(newPassword, salt);
    var updateMembership =
      'UPDATE Memberships '+
      'SET Password=@NewPassword, PasswordSalt=@NewSalt, LastPasswordChangedDate=GETDATE() '+
      'WHERE Email=@Email';
    var updateMembershipQuery = new Request(updateMembership, function (membershipErr, membershipCount) {
      if (membershipErr) {
        return callback(membershipErr);
      }
      callback(null, membershipCount > 0);
    });
    updateMembershipQuery.addParameter('NewPassword', TYPES.VarChar, hashedPassword);
    updateMembershipQuery.addParameter('NewSalt',     TYPES.VarChar, salt.toString('base64'));
    updateMembershipQuery.addParameter('Email',       TYPES.VarChar, email);
    connection.execSql(updateMembershipQuery);
  }
}
```

### ASP.NET Membership Provider (MVC4 - Simple Membership)

```javascript lines expandable theme={null}
function changePassword(email, newPassword, callback) {
  var crypto = require('crypto');
  var Connection = require('tedious').Connection;
  var Request = require('tedious').Request;
  var TYPES = require('tedious').TYPES
  var connection = new Connection({
    userName:  'the username',
    password:  'the password',
    server:    'the server',
    options: {
      database:  'the db name',
      // encrypt: true for Windows Azure enable this
    }
  });
  /**
   * hashPassword
   *
   * This function hashes a password using HMAC SHA256 algorithm.
   *
   * @password    {[string]}    password to be hased
   * @salt        {[string]}    salt to be used in the hashing process
   * @callback    {[function]}  callback to be called after hashing the password
   */
  function hashPassword(password, salt, callback) {
    var iterations         = 1000;
    var passwordHashLength = 32;
    crypto.pbkdf2(password, salt, iterations, passwordHashLength, function (err, hashed) {
      if (err) {
        return callback(err);
      }
      var result = Buffer.concat([Buffer.from([0], 1), salt, Buffer.from(hashed, 'binary')]);
      var resultBase64 = result.toString('base64');
      callback(null, resultBase64);
    });
  }
  connection.on('debug', function(text) {
      // if you have connection issues, uncomment this to get more detailed info
      //console.log(text);
  }).on('errorMessage', function(text) {
      // this will show any errors when connecting to the SQL database or with the SQL statements
    console.log(JSON.stringify(text));
  });
  connection.on('connect', function (err) {
    if (err) {
      return callback(err);
    }
    updateMembershipUser(email, newPassword, function(err, wasUpdated) {
      if (err) {
        return callback(err); // this will return a 500
      }
      callback(null, wasUpdated);
    });
  });
  function findUserId(email, callback) {
    var findUserIdFromEmail =
      'SELECT UserProfile.UserId FROM ' +
      'UserProfile INNER JOIN webpages_Membership ' +
      'ON UserProfile.UserId = webpages_Membership.UserId ' +
      'WHERE UserName = @Email';
    var findUserIdFromEmailQuery = new Request(findUserIdFromEmail, function (err, rowCount, rows) {
      if (err) {
        return callback(err);
      }
      // No record found with that email
      if (rowCount < 1) {
        return callback(null, null);
      }
      var userId = rows[0][0].value;
      callback(null, userId);
    });
    findUserIdFromEmailQuery.addParameter('Email', TYPES.VarChar, email);
    connection.execSql(findUserIdFromEmailQuery);
  }
  function updateMembershipUser(email, newPassword, callback) {
    findUserId(email, function (err, userId) {
      if (err) {
        return callback(err);
      }
      if (userId === null) {
        return callback();
      }
      var salt = crypto.randomBytes(16);
      var updateMembership =
        'UPDATE webpages_Membership '+
        'SET Password=@NewPassword, PasswordChangedDate=GETDATE() '+
        'WHERE UserId=@UserId';
      var updateMembershipQuery = new Request(updateMembership, function (err, rowCount) {
        if (err) {
          return callback(err);
        }
        if (rowCount < 1) {
          return callback();
        }
        callback(null, rowCount > 0);
      });
      hashPassword(newPassword, salt, function (err, hashedPassword) {
        if (err) {
          return callback(err);
        }
        updateMembershipQuery.addParameter('NewPassword',   TYPES.VarChar, hashedPassword);
        updateMembershipQuery.addParameter('UserId',        TYPES.VarChar, userId);
        connection.execSql(updateMembershipQuery);
      });
    });
  }
}
```

### MongoDB

```javascript lines theme={null}
function changePassword(email, newPassword, callback) {
  const bcrypt = require('bcrypt');
  const MongoClient = require('mongodb@3.1.4').MongoClient;
  const client = new MongoClient('mongodb://user:pass@mymongoserver.com');
  client.connect(function (err) {
    if (err) return callback(err);
    const db = client.db('db-name');
    const users = db.collection('users');
    bcrypt.hash(newPassword, 10, function (err, hash) {
      if (err) {
        client.close();
        return callback(err);
      }
      users.update({ email: email }, { $set: { password: hash } }, function (err, count) {
        client.close();
        if (err) return callback(err);
        callback(null, count > 0);
      });
    });
  });
}
```

### MySQL

```javascript lines theme={null}
function changePassword(email, newPassword, callback) {
  const mysql = require('mysql');
  const bcrypt = require('bcrypt');
  const connection = mysql({
    host: 'localhost',
    user: 'me',
    password: 'secret',
    database: 'mydb'
  });
  connection.connect();
  const query = 'UPDATE users SET password = ? WHERE email = ?';
  bcrypt.hash(newPassword, 10, function(err, hash) {
    if (err) return callback(err);
    connection.query(query, [ hash, email ], function(err, results) {
      if (err) return callback(err);
      callback(null, results.length > 0);
    });
  });
}
```

### PostgreSQL

```javascript lines theme={null}
function changePassword (email, newPassword, callback) {
  //this example uses the "pg" library
  //more info here: https://github.com/brianc/node-postgres
  const bcrypt = require('bcrypt');
  const postgres = require('pg');
  const conString = 'postgres://user:pass@localhost/mydb';
  postgres.connect(conString, function (err, client, done) {
    if (err) return callback(err);
    bcrypt.hash(newPassword, 10, function (err, hash) {
      if (err) return callback(err);
      const query = 'UPDATE users SET password = $1 WHERE email = $2';
      client.query(query, [hash, email], function (err, result) {
        // NOTE: always call `done()` here to close
        // the connection to the database
        done();
        return callback(err, result && result.rowCount > 0);
      });
    });
  });
}
```

### SQL Server

```javascript lines expandable theme={null}
function changePassword (email, newPassword, callback) {
  //this example uses the "tedious" library
  //more info here: http://tediousjs.github.io/tedious/
  const bcrypt = require('bcrypt');
  const sqlserver = require('tedious@1.11.0');
  const Connection = sqlserver.Connection;
  const Request = sqlserver.Request;
  const TYPES = sqlserver.TYPES;
  const connection = new Connection({
    userName:  'test',
    password:  'test',
    server:    'localhost',
    options:  {
      database: 'mydb'
    }
  });
  const query = 'UPDATE dbo.Users SET Password = @NewPassword WHERE Email = @Email';
  connection.on('debug', function(text) {
    console.log(text);
  }).on('errorMessage', function(text) {
    console.log(JSON.stringify(text, null, 2));
  }).on('infoMessage', function(text) {
    console.log(JSON.stringify(text, null, 2));
  });
  connection.on('connect', function (err) {
    if (err) return callback(err);
    const request = new Request(query, function (err, rows) {
      if (err) return callback(err);
      callback(null, rows > 0);
    });
    bcrypt.hash(newPassword, 10, function (err, hash) {
      if (err) return callback(err);
      request.addParameter('NewPassword', TYPES.VarChar, hash);
      request.addParameter('Email', TYPES.VarChar, email);
      connection.execSql(request);
    });
  });
}
```

### Windows Azure SQL Database

```javascript lines expandable theme={null}
function changePassword (email, newPassword, callback) {
  //this example uses the "tedious" library
  //more info here: http://pekim.github.io/tedious/index.html
  var Connection = require('tedious@1.11.0').Connection;
  var Request = require('tedious@1.11.0').Request;
  var TYPES = require('tedious@1.11.0').TYPES;
  var bcrypt = require('bcrypt');
  var connection = new Connection({
    userName:  'your-user@your-server-id.database.windows.net',
    password:  'the-password',
    server:    'your-server-id.database.windows.net',
    options:  {
      database: 'mydb',
      encrypt:  true
    }
  });
  var query = 'UPDATE dbo.Users SET Password = @NewPassword ' +
    'WHERE Email = @Email';
  connection.on('debug', function(text) {
    // Uncomment next line in order to enable debugging messages
    // console.log(text);
  }).on('errorMessage', function(text) {
    console.log(JSON.stringify(text, null, 2));
  }).on('infoMessage', function(text) {
    // Uncomment next line in order to enable information messages
    // console.log(JSON.stringify(text, null, 2));
  });
  connection.on('connect', function (err) {
    if (err) { return callback(err); }
    var request = new Request(query, function (err, rows) {
      if (err) { return callback(err); }
      console.log('rows: ' + rows);
      callback(null, rows > 0);
    });
    bcrypt.hash(newPassword, 10, function (err, hash) {
      if (err) { return callback(err); }
      request.addParameter('NewPassword', TYPES.VarChar, hash);
      request.addParameter('Email', TYPES.VarChar, email);
      connection.execSql(request);
    });
  });
}
```

## Learn more

* [Create Script Templates](/docs/authenticate/database-connections/custom-db/templates/create)
* [Delete Script Templates](/docs/authenticate/database-connections/custom-db/templates/delete)
* [Get User Script Templates](/docs/authenticate/database-connections/custom-db/templates/get-user)
* [Login Script Templates](/docs/authenticate/database-connections/custom-db/templates/login)
* [Verify Script Templates](/docs/authenticate/database-connections/custom-db/templates/verify)
* [Change Email Script Template](/docs/authenticate/database-connections/custom-db/templates/change-email)


# Create Script Templates
Source: https://auth0.com/docs/authenticate/database-connections/custom-db/templates/create

Describes custom database action script templates for user creation.

The Create script implements the defined function when a user is created. We recommend naming this function `create`.

This script is optional. If it's enabled, when a user signs up through <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> or is created through the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>, Auth0 will run the script to create a corresponding user record in the external database.

When a user is created in Auth0, Auth0 calls a series of scripts:

1. [Get User](/docs/authenticate/database-connections/custom-db/templates/get-user): Verifies that the user does not already exist in Auth0 or the external database.
2. Create: Creates the user in the external database.
3. [Login](/docs/authenticate/database-connections/custom-db/templates/login): Verifies that the user was created successfully.

## Create function

The `create` function should:

* Send the user's profile data to the external database's API.
* Return an error if the user creation operation failed.

### Definition

The `create` function accept two parameters and returns a `callback` function:

```js lines theme={null}
create(user, callback): function
```

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>user</code></td>
      <td>Object. Contains <a href="#user-object-parameter">user profile data</a> sourced from the user creation process.</td>
    </tr>

    <tr>
      <td><code>callback</code></td>
      <td>Function. Used to pass error data through the pipeline.</td>
    </tr>
  </tbody>
</table>

### Example

This is a pseudo-JavaScript example of how you could implement the `create` function. For language-specific examples, read [Language-specific script examples](#language-specific-script-examples).

```javascript lines expandable theme={null}
function create(user, callback) {
  // Send user profile data to external database API
  let hashedPassword = hash(user.password);

  let options = {
    url: "https://example.com/api/create",
    body: {
      email: user.email,
      username: user.username,
      password: hashedPassword
    }
  };

  send(options, err => {
    // Return error in callback if user already exists
    if (err && err.id === "USER_ALREADY_EXISTS") {
      return callback(new ValidationError("user_exists", "My custom error message."));
    } else if (err) {
      // Return error in callback if error occurred
      return callback(new Error("My custom error message."));
    }

    // Return `null` value in callback if user creation operation succeeded
    return callback(null);
  });
}
```

### Encryption

<Warning>
  Avoid logging, storing, or transporting the password credential anywhere in its unencrypted form.
</Warning>

Encrypt the password value using a cryptographic hash encryption library such as `bcrypt` to prevent any potential data leak.

#### Example

```js lines theme={null}
bcrypt.hash(password, 10, function (err, hash) {
    if (err) {
        return callback(err);
    } else {
        // Return hashed password
    }
});
```

## Callback function

The `callback` function accepts one parameter and returns a function.

### Definition

```js lines theme={null}
callback(error): function
```

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Required</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>error</code></td>
      <td>Object</td>
      <td>Required</td>
      <td>Contains error data.</td>
    </tr>
  </tbody>
</table>

### Return a success

If the user creation operation succeeded, return the `callback` function, and pass a `null` value as the `error` parameter.

#### Example

```js lines theme={null}
return callback(null);
```

### Return an error

If an error occurs, return the callback function, and pass relevant error information to the the `error` parameter.

#### ValidationError type object

The `ValidationError` custom error type object allows you to pass data that will be displayed in your [Tenant Logs](/docs/deploy-monitor/logs).

##### Constructor

The `ValidationError` constructor accepts up to two parameters:

```js lines theme={null}
new ValidationError(errorCode[, message]): ValidationError
```

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>errorCode</code></td>
      <td>(Required) String. Specifies the type of error.</td>
    </tr>

    <tr>
      <td><code>message</code></td>
      <td>(Optional) String. Contains information about the error.</td>
    </tr>
  </tbody>
</table>

#### Return error that user already exists

If you return an error with the value of `user_exists` for the `errorCode` parameter, Auth0 will record an `fs` tenant log event.

##### Example

```js wrap lines theme={null}
return callback(new ValidationError("user_exists", "My custom error message."));
```

<table>
  <thead>
    <tr>
      <th><strong>Tenant Log Event Field</strong></th>
      <th><strong>Value</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Code</strong></td>
      <td><code>fs</code></td>
    </tr>

    <tr>
      <td><strong>Event</strong></td>
      <td>Failed Signup</td>
    </tr>

    <tr>
      <td><strong>Description</strong></td>
      <td><code>My custom error message.</code></td>
    </tr>
  </tbody>
</table>

## User object parameter

The `user` object parameter contains a predefined set of properties sourced from the user creation process:

<table>
  <thead>
    <tr>
      <th><strong>Property</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>client\_id</code></td>
      <td>The Auth0 application's client ID if the user signed up through Universal Login, or the API key if the user was created through the Auth0 Dashboard or Management API.</td>
    </tr>

    <tr>
      <td><code>tenant</code></td>
      <td>The Auth0 tenant name.</td>
    </tr>

    <tr>
      <td><code>email</code></td>
      <td>The user's email address.</td>
    </tr>

    <tr>
      <td><code>password</code></td>
      <td>The user's password in plain text.</td>
    </tr>

    <tr>
      <td><code>username</code></td>
      <td>The user's username. Required only if the custom database connection has the <a href="/docs/authenticate/database-connections/require-username"><strong>Requires Username</strong></a> setting enabled.</td>
    </tr>

    <tr>
      <td><code>connection</code></td>
      <td>The Auth0 connection name.</td>
    </tr>

    <tr>
      <td><code>user\_metadata</code></td>
      <td>Contains the properties of the <code>user\_metadata</code> object on the user's Auth0 profile, if the object exists.</td>
    </tr>

    <tr>
      <td><code>app\_metadata</code></td>
      <td>Contains the properties of the <code>app\_metadata</code> object on the user's Auth0 profile, if the object exists.</td>
    </tr>
  </tbody>
</table>

### Username property

If your custom database connection has the [Requires Username](/docs/authenticate/database-connections/require-username) setting enabled, then the [Login](/docs/authenticate/database-connections/custom-db/templates/login) and [Get User](/docs/authenticate/database-connections/custom-db/templates/get-user) scripts must support the `username` property, so you should store it in your external database.

### User and app metadata

The `user_metadata` and `app_metadata` properties do not need to be stored in your external database. Auth0 automatically stores these values as part of the user profile record created internally.

### Custom sign up fields

If you [create and use custom fields](/docs/libraries/custom-signup#using-the-api) during the sign up process, they will be included in the `user` object.

### Example

```js lines theme={null}
{
    client_id: "8tkMo6n1QkKOazqPcSQd8wU7LzXYibgK",
    tenant: "{yourAuth0Tenant}",
    email: "username@domain.com",
    password: "mySuperSecretPassword123",
    username: "username456",
    user_metadata: {
        "language": "en"
    },
    app_metadata: {
        "plan": "full"
    }
}
```

## Language-specific script examples

Auth0 provides sample scripts for use with the following languages/technologies:

* [JavaScript](#javascript)
* [ASP.NET Membership Provider (MVC3 - Universal Providers)](#asp-net-membership-provider-mvc3-universal-providers-)
* [ASP.NET Membership Provider (MVC4 - Simple Membership)](#asp-net-membership-provider-mvc4-simple-membership-)
* [MongoDB](#mongodb)
* [MySQL](#mysql)
* [PostgreSQL](#postgresql)
* [SQL Server](#sql-server)
* [Windows Azure SQL Database](#windows-azure-sql-database)
* [Request with Basic Auth](#request-with-basic-auth)

### JavaScript

```javascript lines expandable theme={null}
function create(user, callback) {
  // This script should create a user entry in your existing database. It will
  // be executed when a user attempts to sign up, or when a user is created
  // through the Auth0 Dashboard or Management API.
  // When this script has finished executing, the Login script will be
  // executed immediately afterwards, to verify that the user was created
  // successfully.
  //
  // The user object will always contain the following properties:
  // * email: the user's email
  // * password: the password entered by the user, in plain text
  // * tenant: the name of this Auth0 account
  // * client_id: the client ID of the application where the user signed up, or
  //              API key if created through the Management API or Auth0 Dashboard
  // * connection: the name of this database connection
  //
  // There are three ways this script can finish:
  // 1. A user was successfully created
  //     callback(null);
  // 2. This user already exists in your database
  //     callback(new ValidationError("user_exists", "my error message"));
  // 3. Something went wrong while trying to reach your database
  //     callback(new Error("my error message"));
  const msg = 'Please implement the Create script for this database connection ' +
    'at https://manage.auth0.com/#/connections/database';
  return callback(new Error(msg));
}
```

### ASP.NET Membership Provider (MVC3 - Universal Providers)

```javascript lines expandable theme={null}
function create(user, callback) {
  const crypto = require('crypto');
  const sqlserver = require('tedious@1.11.0');
  const Connection = sqlserver.Connection;
  const Request = sqlserver.Request;
  const TYPES = sqlserver.TYPES;
  const connection = new Connection({
    userName: 'the username',
    password: 'the password',
    server: 'the server',
    options: {
      database: 'the db name',
      encrypt: true,
      // Required to retrieve userId needed for Membership entity creation
      rowCollectionOnRequestCompletion: true
    }
  });
  const applicationId = 'your-application-id-goes-here';
  /**
   * hashPassword
   *
   * This function creates a hashed version of the password to store in the database.
   *
   * @password  {[string]}      the password entered by the user
   * @return    {[string]}      the hashed password
   */
  function hashPassword(password, salt) {
    // the default implementation uses HMACSHA256 and since Key length is 64
    // and default salt is 16 bytes, Membership will fill the buffer repeating the salt
    const key = Buffer.concat([salt, salt, salt, salt]);
    const hmac = crypto.createHmac('sha256', key);
    hmac.update(Buffer.from(password, 'ucs2'));
    return hmac.digest('base64');
  }
  connection.on('debug', function(text) {
    // if you have connection issues, uncomment this to get more detailed info
    // console.log(text);
  }).on('errorMessage', function(text) {
    // this will show any errors when connecting to the SQL database or with the SQL statements
    console.log(JSON.stringify(text));
  });
  connection.on('connect', function(err) {
    if (err) {
      return callback(err);
    }
    createMembershipUser(user, function(err, user) {
      if (err) return callback(err); // this will return a 500
      if (!user) return callback(); // this will return a 401
      callback(null, user);
    });
  });
  function createMembershipUser(user, callback) {
    const userData = {
      UserName: user.email,
      ApplicationId: applicationId
    };
    const createUser =
      'INSERT INTO Users (UserName, LastActivityDate, ApplicationId, UserId, IsAnonymous) ' +
      'OUTPUT Inserted.UserId ' +
      'VALUES (@UserName, GETDATE(), @ApplicationId, NEWID(), \'false\')';
    const createUserQuery = new Request(createUser, function(err, rowCount, rows) {
      if (err) return callback(err);
      // No records added
      if (rowCount === 0) return callback(null);
      const userId = rows[0][0].value;
      const salt = crypto.randomBytes(16);
      const membershipData = {
        ApplicationId: applicationId,
        Email: user.email,
        Password: hashPassword(user.password, salt),
        PasswordSalt: salt.toString('base64'),
        UserId: userId
      };
      const createMembership =
        'INSERT INTO Memberships (ApplicationId, UserId, Password, PasswordFormat, ' +
        'PasswordSalt, Email, isApproved, isLockedOut, CreateDate, LastLoginDate, ' +
        'LastPasswordChangedDate, LastLockoutDate, FailedPasswordAttemptCount, ' +
        'FailedPasswordAttemptWindowStart, FailedPasswordAnswerAttemptCount, ' +
        'FailedPasswordAnswerAttemptWindowsStart) ' +
        'VALUES ' +
        '(@ApplicationId, @UserId, @Password, 1, @PasswordSalt, ' +
        '@Email, \'false\', \'false\', GETDATE(), GETDATE(), GETDATE(), GETDATE(), 0, 0, 0, 0)';
      const createMembershipQuery = new Request(createMembership, function(err, rowCount) {
        if (err) return callback(err);
        if (rowCount === 0) return callback(null);
        callback(null, rowCount > 0);
      });
      createMembershipQuery.addParameter('ApplicationId', TYPES.VarChar, membershipData.ApplicationId);
      createMembershipQuery.addParameter('Email', TYPES.VarChar, membershipData.Email);
      createMembershipQuery.addParameter('Password', TYPES.VarChar, membershipData.Password);
      createMembershipQuery.addParameter('PasswordSalt', TYPES.VarChar, membershipData.PasswordSalt);
      createMembershipQuery.addParameter('UserId', TYPES.VarChar, membershipData.UserId);
      connection.execSql(createMembershipQuery);
    });
    createUserQuery.addParameter('UserName', TYPES.VarChar, userData.UserName);
    createUserQuery.addParameter('ApplicationId', TYPES.VarChar, userData.ApplicationId);
    connection.execSql(createUserQuery);
  }
}
```

### ASP.NET Membership Provider (MVC4 - Simple Membership)

```javascript lines expandable theme={null}
function create(user, callback) {
  const crypto = require('crypto');
  const sqlserver = require('tedious@1.11.0');
  const Connection = sqlserver.Connection;
  const Request = sqlserver.Request;
  const TYPES = sqlserver.TYPES;
  const connection = new Connection({
    userName: 'the username',
    password: 'the password',
    server: 'the server',
    options: {
      database: 'the db name',
      encrypt: true,
      // Required to retrieve userId needed for Membership entity creation
      rowCollectionOnRequestCompletion: true
    }
  });
  /**
   * hashPassword
   *
   * This function hashes a password using HMAC SHA256 algorithm.
   *
   * @password    {[string]}    password to be hased
   * @salt        {[string]}    salt to be used in the hashing process
   * @callback    {[function]}  callback to be called after hashing the password
   */
  function hashPassword(password, salt, callback) {
    const iterations = 1000;
    const passwordHashLength = 32;
    crypto.pbkdf2(password, salt, iterations, passwordHashLength, 'sha1', function (err, hashed) {
      if (err) return callback(err);
      const result = Buffer.concat([Buffer.from([0], 1), salt, Buffer.from(hashed, 'binary')]);
      const resultBase64 = result.toString('base64');
      callback(null, resultBase64);
    });
  }
  connection.on('debug', function (text) {
    // if you have connection issues, uncomment this to get more detailed info
    // console.log(text);
  }).on('errorMessage', function (text) {
    // this will show any errors when connecting to the SQL database or with the SQL statements
    console.log(JSON.stringify(text));
  });
  connection.on('connect', function (err) {
    if (err) return callback(err);
    const createUser =
      'INSERT INTO UserProfile (UserName) ' +
      'OUTPUT Inserted.UserId ' +
      'VALUES (@UserName)';
    const createUserQuery = new Request(createUser, function (err, rowCount, rows) {
      if (err || rowCount === 0) return callback(err);
      const userId = rows[0][0].value;
      const salt = crypto.randomBytes(16);
      const createMembership =
        'INSERT INTO webpages_Membership ' +
        '(UserId, CreateDate, IsConfirmed, PasswordFailuresSinceLastSuccess, Password, PasswordSalt) ' +
        'VALUES ' +
        '(@UserId, GETDATE(), \'false\', 0, @Password, \'\')';
      const createMembershipQuery = new Request(createMembership, function (err, rowCount) {
        if (err || rowCount === 0) return callback(err);
        callback(null, rowCount > 0);
      });
      hashPassword(user.password, salt, function (err, hashedPassword) {
        if (err) return callback(err);
        createMembershipQuery.addParameter('Password', TYPES.VarChar, hashedPassword);
        createMembershipQuery.addParameter('PasswordSalt', TYPES.VarChar, salt.toString('base64'));
        createMembershipQuery.addParameter('UserId', TYPES.VarChar, userId);
        connection.execSql(createMembershipQuery);
      });
    });
    createUserQuery.addParameter('UserName', TYPES.VarChar, user.email);
    connection.execSql(createUserQuery);
  });
}
```

### MongoDB

```javascript lines expandable theme={null}
function create(user, callback) {
  const bcrypt = require('bcrypt');
  const MongoClient = require('mongodb@3.1.4').MongoClient;
  const client = new MongoClient('mongodb://user:pass@mymongoserver.com');
  client.connect(function (err) {
    if (err) return callback(err);
    const db = client.db('db-name');
    const users = db.collection('users');
    users.findOne({ email: user.email }, function (err, withSameMail) {
      if (err || withSameMail) {
        client.close();
        return callback(err || new Error('the user already exists'));
      }
      bcrypt.hash(user.password, 10, function (err, hash) {
        if (err) {
          client.close();
          return callback(err);
        }
        user.password = hash;
        users.insert(user, function (err, inserted) {
          client.close();
          if (err) return callback(err);
          callback(null);
        });
      });
    });
  });
}
```

### MySQL

```javascript lines theme={null}
function create(user, callback) {
  const mysql = require('mysql');
  const bcrypt = require('bcrypt');
  const connection = mysql({
    host: 'localhost',
    user: 'me',
    password: 'secret',
    database: 'mydb'
  });
  connection.connect();
  const query = 'INSERT INTO users SET ?';
  bcrypt.hash(user.password, 10, function(err, hash) {
    if (err) return callback(err);
    const insert = {
      password: hash,
      email: user.email
    };
    connection.query(query, insert, function(err, results) {
      if (err) return callback(err);
      if (results.length === 0) return callback();
      callback(null);
    });
  });
}
```

### PostgreSQL

```javascript lines theme={null}
function create(user, callback) {
  //this example uses the "pg" library
  //more info here: https://github.com/brianc/node-postgres
  const bcrypt = require('bcrypt');
  const postgres = require('pg');
  const conString = 'postgres://user:pass@localhost/mydb';
  postgres.connect(conString, function (err, client, done) {
    if (err) return callback(err);
    bcrypt.hash(user.password, 10, function (err, hashedPassword) {
      if (err) return callback(err);
      const query = 'INSERT INTO users(email, password) VALUES ($1, $2)';
      client.query(query, [user.email, hashedPassword], function (err, result) {
        // NOTE: always call `done()` here to close
        // the connection to the database
        done();
        return callback(err);
      });
    });
  });
}
```

### SQL Server

```javascript lines expandable theme={null}
function create(user, callback) {
  //this example uses the "tedious" library
  //more info here: http://pekim.github.io/tedious/index.html
  const bcrypt = require('bcrypt');
  const sqlserver = require('tedious@1.11.0');
  const Connection = sqlserver.Connection;
  const Request = sqlserver.Request;
  const TYPES = sqlserver.TYPES;
  const connection = new Connection({
    userName:  'test',
    password:  'test',
    server:    'localhost',
    options:  {
      database: 'mydb'
    }
  });
  const query = 'INSERT INTO dbo.Users SET Email = @Email, Password = @Password';
  connection.on('debug', function(text) {
    console.log(text);
  }).on('errorMessage', function(text) {
    console.log(JSON.stringify(text, null, 2));
  }).on('infoMessage', function(text) {
    console.log(JSON.stringify(text, null, 2));
  });
  connection.on('connect', function (err) {
    if (err) return callback(err);
    const request = new Request(query, function (err, rows) {
      if (err) return callback(err);
      callback(null);
    });
    bcrypt.hash(user.password, 10, function(err, hash) {
      if (err) return callback(err);
      request.addParameter('Email', TYPES.VarChar, user.email);
      request.addParameter('Password', TYPES.VarChar, hash);
      connection.execSql(request);
    });
  });
}
```

### Windows Azure SQL Database

```javascript lines expandable theme={null}
function create (user, callback) {
  //this example uses the "tedious" library
  //more info here: http://pekim.github.io/tedious/index.html
  var Connection = require('tedious@1.11.0').Connection;
  var Request = require('tedious@1.11.0').Request;
  var TYPES = require('tedious@1.11.0').TYPES;
  var bcrypt = require('bcrypt');
  var connection = new Connection({
    userName:  'your-user@your-server-id.database.windows.net',
    password:  'the-password',
    server:    'your-server-id.database.windows.net',
    options:  {
      database: 'mydb',
      encrypt:  true
    }
  });
  var query = "INSERT INTO users (Email, Password) VALUES (@Email, @Password)";
  connection.on('debug', function(text) {
    // Uncomment next line in order to enable debugging messages
    // console.log(text);
  }).on('errorMessage', function(text) {
    console.log(JSON.stringify(text, null, 2));
  }).on('infoMessage', function(text) {
    // Uncomment next line in order to enable information messages
    // console.log(JSON.stringify(text, null, 2));
  });
  connection.on('connect', function (err) {
    if (err) { return callback(err); }
    var request = new Request(query, function (err, rows) {
      if (err) { return callback(err); }
      console.log('rows: ' + rows);
      callback(null);
    });
    bcrypt.hash(user.password, 10, function (err, hashedPassword) {
      if (err) { return callback(err); }
      request.addParameter('Email', TYPES.VarChar, user.email);
      request.addParameter('Password', TYPES.VarChar, hashedPassword);
      connection.execSql(request);
    });
  });
}
```

### Request with Basic Auth

```javascript lines theme={null}
function create(user, callback) {
  const request = require('request');
  request.post({
    url: 'https://myserviceurl.com/users',
    json: user
    //for more options check:
    //https://github.com/mikeal/request#requestoptions-callback
  }, function(err, response, body) {
    if (err) return callback(err);
    callback(null);
  });
}
```

## Troubleshoot

If you are unable to create a user in either your legacy database or Auth0:

1. Check the `console.log()` statements with [Actions Real-Time Logs](/docs/customize/actions/actions-real-time-logs).
2. Find the user in your legacy database and delete accordingly. If the partial user state is in Auth0, use the Management API's [Delete a User](https://auth0.com/docs/api/management/v2#!/Users/delete_users_by_id) endpoint or [Delete a Connection User](https://auth0.com/docs/api/management/v2#!/Connections/delete_users_by_email) endpoint.
3. Make sure **Import Mode** is disabled, then configure the create script.

## Learn more

* [Login Script Templates](/docs/authenticate/database-connections/custom-db/templates/login)
* [Get User Script Templates](/docs/authenticate/database-connections/custom-db/templates/get-user)
* [Delete Script Templates](/docs/authenticate/database-connections/custom-db/templates/delete)
* [Verify Script Templates](/docs/authenticate/database-connections/custom-db/templates/verify)
* [Change Password Script Templates](/docs/authenticate/database-connections/custom-db/templates/change-password)
* [Change Email Script Template](/docs/authenticate/database-connections/custom-db/templates/change-email)


# Delete Script Templates
Source: https://auth0.com/docs/authenticate/database-connections/custom-db/templates/delete

Describes custom database action script templates for user deletion.

The Delete script implements the defined function to delete a specified user from an external database. We recommend naming this function `deleteUser`.

The script is only used in a [legacy authentication scenario](/docs/authenticate/database-connections/custom-db/overview-custom-db-connections), and is required if you want to delete a user from Auth0 and your external database in the same operation.

## DeleteUser function

The `deleteUser` function should:

* Remove the specified user from the external database.
* Return a `null` value if the deletion succeeded.
* Return an error if the deletion failed.

### Definition

The `deleteUser` function accepts two parameters and returns a `callback` function:

```js lines theme={null}
deleteUser(id, callback): function
```

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>id</code></td>
      <td>String</td>
      <td>User’s identity <code>user\_id</code>. Does not start with <code>auth0</code>.</td>
    </tr>

    <tr>
      <td><code>callback</code></td>
      <td>Function</td>
      <td>Used to pass error or profile data through the pipeline.</td>
    </tr>
  </tbody>
</table>

### Example

This is a pseudo-JavaScript example of how you could implement the `deleteUser` function. For language-specific examples, read [Language-specific script examples](/docs/authenticate/database-connections/custom-db/templates/delete#language-specific-script-examples).

```javascript lines theme={null}
function deleteUser(id, callback) {
  // Send user identifier to external database API
  let options = {
    url: "https://example.com/api/deleteUser",
    body: {
      id: id
    }
  };

  send(options, (err, profileData) => {
    // Return error in callback if deletion failed
    if (err) {
      return callback(new Error("My custom error message."));
    }

    // Return null value in callback if deletion succeeded
    return callback(null);
  });
}
```

## Callback function

The `callback` function accepts one parameter and returns a function.

### Definition

```js lines theme={null}
callback(error): function
```

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Required</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>error</code></td>
      <td>Object</td>
      <td>Required</td>
      <td>Contains error data.</td>
    </tr>
  </tbody>
</table>

### Return a success

If the user was successfully deleted in your external database, return the `callback` function, and pass a `null` value for the `error` parameter.

#### Example

```js lines theme={null}
return callback(null);
```

### Return an error

If an error occurs, return the `callback` function, and pass relevant error information to the `error` parameter.

#### Example

```js lines theme={null}
return callback(new Error("My custom error message."));
```

## Language-specific script examples

Auth0 provides sample scripts for use with the following languages/technologies:

* [JavaScript](#javascript)
* [ASP.NET Membership Provider (MVC3 - Universal Providers)](#asp-net-membership-provider-mvc3-universal-providers-)
* [ASP.NET Membership Provider (MVC4 - Simple Membership)](#asp-net-membership-provider-mvc4-simple-membership-)
* [MongoDB](#mongodb)
* [MySQL](#mysql)
* [PostgreSQL](#postgresql)
* [SQL Server](#sql-server)
* [Windows Azure SQL Database](#windows-azure-sql-database)

### JavaScript

```javascript lines theme={null}
function remove (id, callback) {
  // This script remove a user from your existing database.
  // It is executed whenever a user is deleted from the Management API or Auth0 dashboard.
  //
  // There are two ways that this script can finish:
  // 1. The user was removed successfully:
  //     callback(null);
  // 2. Something went wrong while trying to reach your database:
  //     callback(new Error("my error message"));
  var msg = "Please implement the Delete script for this database " +
       "connection at https://manage.auth0.com/#/connections/database";
  return callback(new Error(msg));
}
```

### ASP.NET Membership Provider (MVC3 - Universal Providers)

```javascript lines expandable theme={null}
function remove(id, callback) {
  const sqlserver = require('tedious@1.11.0');
  const Connection = sqlserver.Connection;
  const Request = sqlserver.Request;
  const TYPES = sqlserver.TYPES;
  const connection = new Connection({
    userName: 'the username',
    password: 'the password',
    server: 'the server',
    options: {
      database: 'the db name',
      encrypt: true,
      // Required to retrieve userId needed for Membership entity creation
      rowCollectionOnRequestCompletion: true
    }
  });
  connection.on('debug', function(text) {
    // if you have connection issues, uncomment this to get more detailed info
    // console.log(text);
  }).on('errorMessage', function(text) {
    // this will show any errors when connecting to the SQL database or with the SQL statements
    console.log(JSON.stringify(text));
  });
  connection.on('connect', function(err) {
    if (err) return callback(err);
    executeDelete(['Memberships', 'Users'], function(err) {
      if (err) return callback(err);
      callback(null);
    });
  });
  function executeDelete(tables, callback) {
    const query = tables.map(function(table) {
      return 'DELETE FROM ' + table + ' WHERE UserId = @UserId';
    }).join(';');
    const request = new Request(query, function(err) {
      if (err) return callback(err);
      callback(null);
    });
    request.addParameter('UserId', TYPES.VarChar, id);
    connection.execSql(request);
  }
}
```

### ASP.NET Membership Provider (MVC4 - Simple Membership)

```javascript lines expandable theme={null}
function remove(id, callback) {
  const sqlserver = require('tedious@1.11.0');
  const Connection = sqlserver.Connection;
  const Request = sqlserver.Request;
  const TYPES = sqlserver.TYPES;
  const connection = new Connection({
    userName: 'the username',
    password: 'the password',
    server: 'the server',
    options: {
      database: 'the db name',
      encrypt: true,
      // Required to retrieve userId needed for Membership entity creation
      rowCollectionOnRequestCompletion: true
    }
  });
  connection.on('debug', function (text) {
    // if you have connection issues, uncomment this to get more detailed info
    // console.log(text);
  }).on('errorMessage', function (text) {
    // this will show any errors when connecting to the SQL database or with the SQL statements
    console.log(JSON.stringify(text));
  });
  connection.on('connect', function (err) {
    if (err) return callback(err);
    executeDelete(['webpages_Membership', 'UserProfile'], function (err) {
      if (err) return callback(err);
      callback(null);
    });
  });
  function executeDelete(tables, callback) {
    const query = tables.map(function (table) {
      return 'DELETE FROM ' + table + ' WHERE UserId = @UserId';
    }).join(';');
    const request = new Request(query, function (err) {
      if (err) return callback(err);
      callback(null);
    });
    request.addParameter('UserId', TYPES.VarChar, id);
    connection.execSql(request);
  }
}
```

### MongoDB

```javascript lines theme={null}
function remove(id, callback) {
  const MongoClient = require('mongodb@3.1.4').MongoClient;
  const client = new MongoClient('mongodb://user:pass@mymongoserver.com');
  client.connect(function (err) {
    if (err) return callback(err);
    const db = client.db('db-name');
    const users = db.collection('users');
    users.remove({ _id: id }, function (err) {
      client.close();
      if (err) return callback(err);
      callback(null);
    });
  });
}
```

### MySQL

```javascript lines theme={null}
function remove(id, callback) {
  const mysql = require('mysql');
  const connection = mysql({
    host: 'localhost',
    user: 'me',
    password: 'secret',
    database: 'mydb'
  });
  connection.connect();
  const query = 'DELETE FROM users WHERE id = ?';
  connection.query(query, [ id ], function(err) {
    if (err) return callback(err);
    callback(null);
  });
}
```

### PostgreSQL

```javascript lines theme={null}
function remove(id, callback) {
  //this example uses the "pg" library
  //more info here: https://github.com/brianc/node-postgres
  const postgres = require('pg');
  const conString = 'postgres://user:pass@localhost/mydb';
  postgres.connect(conString, function (err, client, done) {
    if (err) return callback(err);
    const query = 'DELETE FROM users WHERE id = $1';
    client.query(query, [id], function (err) {
      // NOTE: always call `done()` here to close
      // the connection to the database
      done();
      return callback(err);
    });
  });
}
```

### SQL Server

```javascript lines expandable theme={null}
function remove(id, callback) {
  // this example uses the "tedious" library
  // more info here: http://pekim.github.io/tedious/index.html
  const sqlserver = require('tedious@1.11.0');
  const Connection = sqlserver.Connection;
  const Request = sqlserver.Request;
  const TYPES = sqlserver.TYPES;
  const connection = new Connection({
    userName:  'test',
    password:  'test',
    server:    'localhost',
    options:  {
      database: 'mydb'
    }
  });
  const query = 'DELETE FROM dbo.Users WHERE id = @UserId';
  connection.on('debug', function (text) {
    console.log(text);
  }).on('errorMessage', function (text) {
    console.log(JSON.stringify(text, null, 2));
  }).on('infoMessage', function (text) {
    console.log(JSON.stringify(text, null, 2));
  });
  connection.on('connect', function (err) {
    if (err) return callback(err);
    const request = new Request(query, function (err) {
      if (err) return callback(err);
      callback(null);
    });
    request.addParameter('UserId', TYPES.VarChar, id);
    connection.execSql(request);
  });
}
```

### Windows Azure SQL Database

```javascript lines expandable theme={null}
function remove (id, callback) {
  // this example uses the "tedious" library
  // more info here: http://pekim.github.io/tedious/index.html
  var Connection = require('tedious@1.11.0').Connection;
  var Request = require('tedious@1.11.0').Request;
  var TYPES = require('tedious@1.11.0').TYPES;
  var connection = new Connection({
    userName: 'your-user@your-server-id.database.windows.net',
    password: 'the-password',
    server: 'your-server-id.database.windows.net',
    options: {
      database: 'mydb',
      encrypt: true
    }
  });
  connection.on('debug', function (text) {
    console.log(text);
  }).on('errorMessage', function (text) {
    console.log(JSON.stringify(text, null, 2));
  }).on('infoMessage', function (text) {
    console.log(JSON.stringify(text, null, 2));
  });
  connection.on('connect', function (err) {
    if (err) { return callback(err); }
    var query = 'DELETE FROM users WHERE id = @UserId';
    var request = new Request(query, function (err) {
      if (err) { return callback(err); }
      callback(null);
    });
    request.addParameter('UserId', TYPES.VarChar, id);
    connection.execSql(request);
  });
}
```

## Learn more

* [Change Password Script Templates](/docs/authenticate/database-connections/custom-db/templates/change-password)
* [Create Script Templates](/docs/authenticate/database-connections/custom-db/templates/create)
* [Get User Script Templates](/docs/authenticate/database-connections/custom-db/templates/get-user)
* [Login Script Templates](/docs/authenticate/database-connections/custom-db/templates/login)
* [Verify Script Templates](/docs/authenticate/database-connections/custom-db/templates/verify)
* [Change Email Script Template](/docs/authenticate/database-connections/custom-db/templates/change-email)


# Get User Script Templates
Source: https://auth0.com/docs/authenticate/database-connections/custom-db/templates/get-user

Describes custom database action script templates for user search.

The Get User script implements the function executed to determine the current state of existence of a user. We recommend naming this function `getUser`.

This script is required for [automatic migration](/docs/manage-users/user-migration/configure-automatic-migration-from-your-database), and conditionally required for legacy authentication depending on the operations configured for the connection. Auth0 recommends you set permanent `user_id` on the returned user profile to avoid creating duplicate users.

If automatic migration is configured for the connection and the user profile has not yet been created, the script is executed whenever the following operations occur:

* Change email
* Sign up
* Password reset

If legacy authentication is configured for the connection, the script is executed whenever the following operations occur:

* Create user
* Change email
* Change password
* Password reset

## Get User function

The `getUser` function should:

* Send the user's identifier to the external database's API.
* Return the profile data of the user if the user was found.
* Return an error if there was an issue determining whether the user exists or not.

### Definition

The `getUser` function accepts two parameters and returns a `callback` function:

```js lines theme={null}
getUser(email, callback): function
```

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>email</code></td>
      <td>String</td>
      <td>The user's email address.</td>
    </tr>

    <tr>
      <td><code>callback</code></td>
      <td>Function</td>
      <td>Used to pass error or profile data through the pipeline</td>
    </tr>
  </tbody>
</table>

### Example

This is a pseudo-Javascript example of how you could implement the `getUser` function. For language-specific examples, read [Language-specific script examples](#language-specific-script-examples).

```javascript lines expandable theme={null}
function getUser(email, callback) {
  // Send user identifier to external database API
  let options = {
    url: "https://example.com/api/search-users",
    body: {
      email: email
    }
  };

  send(options, (err, profileData) => {
    // Return error in callback if there was an issue finding the user
    if (err) {
      return callback(new Error("Could not determine if user exists or not."));
    } else {
      // Return null in callback if user was not found, return profile data in callback if user was found
      if (!profileData) {
        return callback(null);
      } else {
        let profile = {
          email: profileData.email,
          user_id: profileData.userId
        };

        return callback(null, profile);
      }
    }
  });
}
```

## Callback function

The `callback` function is used to pass user profile data or error data through the pipeline.

### Definition

The `callback` function accepts up to two parameters and returns a function:

```js lines theme={null}
callback(error[,profile]): function
```

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Required</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>error</code></td>
      <td>Object</td>
      <td>Required</td>
      <td>Contains error data.</td>
    </tr>

    <tr>
      <td><code>profile</code></td>
      <td>Object</td>
      <td>Optional</td>
      <td>Contains the user's profile data.</td>
    </tr>
  </tbody>
</table>

### Return the user profile (user found)

<Warning>
  The profile data returned by the Get User script for a user must be consistent with the profile data returned by the Login script.
</Warning>

If the user is found, pass a `null` value to the `error` parameter, and pass the user's profile data to the `profile` parameter in [normalized form](/docs/manage-users/user-accounts/user-profiles/normalized-user-profile-schema). In addition to the standard fields, you can include the `user_metadata`, `app_metadata`, and `mfa_factors` fields.

#### Example

```js lines theme={null}
return callback(null, {
    username: "username",
    user_id: "my-custom-db|username@domain.com",
    email: "username@domain.com",
    email_verified: false,
    user_metadata: {
        language: "en"
    },
    app_metadata: {
        plan: "full"
    },
    mfa_factors: [
      {
        phone: {
          value: "+15551234567"
        }
      },
    ]
});
```

### Return no user profile (user not found)

If the user is not found, pass a `null` value to the `error` parameter, and omit the `profile` parameter.

#### Example

```js lines theme={null}
return callback(null);
```

### Return an error

If an error occurs, pass error data to the `error` parameter with relevant information about what went wrong. For more information, read [Troubleshoot Custom Databases](/docs/authenticate/database-connections/custom-db/error-handling).

#### Example

```js lines theme={null}
return callback(new Error("My custom error message."));
```

## Language-specific script examples

Auth0 provides sample scripts for use with the following languages/technologies:

* [JavaScript](#javascript)
* [ASP.NET Membership Provider (MVC3 - Universal Providers)](#asp-net-membership-provider-mvc3-universal-providers-)
* [ASP.NET Membership Provider (MVC4 - Simple Membership)](#asp-net-membership-provider-mvc4-simple-membership-)
* [MongoDB](#mongodb)
* [MySQL](#mysql)
* [PostgreSQL](#postgresql)
* [SQL Server](#sql-server)
* [Windows Azure SQL Database](#windows-azure-sql-database)
* [Axios](#axios)
* [Stormpath](#stormpath)

### JavaScript

```javascript lines theme={null}
function getByEmail(email, callback) {
  // This script should retrieve a user profile from your existing database,
  // without authenticating the user.
  // It is used to check if a user exists before executing flows that do not
  // require authentication (signup and password reset).
  //
  // There are three ways this script can finish:
  // 1. A user was successfully found. The profile should be in the following
  // format: https://auth0.com/docs/users/normalized/auth0/normalized-user-profile-schema.
  //     callback(null, profile);
  // 2. A user was not found
  //     callback(null);
  // 3. Something went wrong while trying to reach your database:
  //     callback(new Error("my error message"));
  const msg = 'Please implement the Get User script for this database connection ' +
    'at https://manage.auth0.com/#/connections/database';
  return callback(new Error(msg));
}
```

### ASP.NET Membership Provider (MVC3 - Universal Providers)

```javascript lines expandable theme={null}
function getByEmail(email, callback) {
  const sqlserver = require('tedious@1.11.0');
  const Connection = sqlserver.Connection;
  const Request = sqlserver.Request;
  const TYPES = sqlserver.TYPES;
  const connection = new Connection({
    userName: 'the username',
    password: 'the password',
    server: 'the server',
    options: {
      database: 'the db name',
      encrypt: true // for Windows Azure
    }
  });
  connection.on('debug', function(text) {
    // if you have connection issues, uncomment this to get more detailed info
    //console.log(text);
  }).on('errorMessage', function(text) {
    // this will show any errors when connecting to the SQL database or with the SQL statements
    console.log(JSON.stringify(text));
  });
  connection.on('connect', function(err) {
    if (err) return callback(err);
    var user = {};
    const query =
      'SELECT Memberships.UserId, Email, Users.UserName ' +
      'FROM Memberships INNER JOIN Users ' +
      'ON Users.UserId = Memberships.UserId ' +
      'WHERE Memberships.Email = @Username OR Users.UserName = @Username';
    const getMembershipQuery = new Request(query, function(err, rowCount) {
      if (err) return callback(err);
      if (rowCount < 1) return callback();
      callback(null, user);
    });
    getMembershipQuery.addParameter('Username', TYPES.VarChar, email);
    getMembershipQuery.on('row', function(fields) {
      user = {
        user_id: fields.UserId.value,
        nickname: fields.UserName.value,
        email: fields.Email.value
      };
    });
    connection.execSql(getMembershipQuery);
  });
}
```

### ASP.NET Membership Provider (MVC4 - Simple Membership)

```javascript lines expandable theme={null}
function getByEmail(email, callback) {
  const sqlserver = require('tedious@1.11.0');
  const Connection = sqlserver.Connection;
  const Request = sqlserver.Request;
  const TYPES = sqlserver.TYPES;
  const connection = new Connection({
    userName: 'the username',
    password: 'the password',
    server: 'the server',
    options: {
      database: 'the db name',
      encrypt: true // for Windows Azure
    }
  });
  connection.on('debug', function(text) {
    // if you have connection issues, uncomment this to get more detailed info
    //console.log(text);
  }).on('errorMessage', function(text) {
    // this will show any errors when connecting to the SQL database or with the SQL statements
    console.log(JSON.stringify(text));
  });
  connection.on('connect', function(err) {
    if (err) return callback(err);
    var user = {};
    const query =
      'SELECT webpages_Membership.UserId, UserName, UserProfile.UserName from webpages_Membership ' +
      'INNER JOIN UserProfile ON UserProfile.UserId = webpages_Membership.UserId ' +
      'WHERE UserProfile.UserName = @Username';
    const getMembershipQuery = new Request(query, function (err, rowCount) {
      if (err) return callback(err);
      if (rowCount < 1) return callback();
      callback(null, user);
    });
    getMembershipQuery.addParameter('Username', TYPES.VarChar, email);
    getMembershipQuery.on('row', function (fields) {
      user = {
        user_id: fields.UserId.value,
        nickname: fields.UserName.value,
        email: fields.UserName.value
      };
    });
    connection.execSql(getMembershipQuery);
  });
}
```

### MongoDB

```javascript lines theme={null}
function getByEmail(email, callback) {
  const MongoClient = require('mongodb@5.1.0').MongoClient;
  const client = new MongoClient('mongodb://user:pass@mymongoserver.com');
  client.connect(function (err) {
    if (err) return callback(err);
    const db = client.db('db-name');
    const users = db.collection('users');
    users.findOne({ email: email }, function (err, user) {
      client.close();
      if (err) return callback(err);
      if (!user) return callback(null, null);
      return callback(null, {
        user_id: user._id.toString(),
        nickname: user.nickname,
        email: user.email
      });
    });
  });
}
```

### MySQL

```javascript lines theme={null}
function getByEmail(email, callback) {
  const mysql = require('mysql');
  const connection = mysql({
    host: 'localhost',
    user: 'me',
    password: 'secret',
    database: 'mydb'
  });
  connection.connect();
  const query = 'SELECT id, nickname, email FROM users WHERE email = ?';
  connection.query(query, [ email ], function(err, results) {
    if (err || results.length === 0) return callback(err || null);
    const user = results[0];
    callback(null, {
      user_id: user.id.toString(),
      nickname: user.nickname,
      email: user.email
    });
  });
}
```

### PostgreSQL

```javascript lines theme={null}
function loginByEmail(email, callback) {
  //this example uses the "pg" library
  //more info here: https://github.com/brianc/node-postgres
  const postgres = require('pg');
  const conString = 'postgres://user:pass@localhost/mydb';
  postgres.connect(conString, function (err, client, done) {
    if (err) return callback(err);
    const query = 'SELECT id, nickname, email FROM users WHERE email = $1';
    client.query(query, [email], function (err, result) {
      // NOTE: always call `done()` here to close
      // the connection to the database
      done();
      if (err || result.rows.length === 0) return callback(err);
      const user = result.rows[0];
      return callback(null, {
        user_id: user.id,
        nickname: user.nickname,
        email: user.email
      });
    });
  });
}
```

### SQL Server

```javascript lines expandable theme={null}
function getByEmail(email, callback) {
  //this example uses the "tedious" library
  //more info here: http://pekim.github.io/tedious/index.html
  const sqlserver = require('tedious@1.11.0');
  const Connection = sqlserver.Connection;
  const Request = sqlserver.Request;
  const TYPES = sqlserver.TYPES;
  const connection = new Connection({
    userName:  'test',
    password:  'test',
    server:    'localhost',
    options:  {
      database: 'mydb'
    }
  });
  const query = 'SELECT Id, Nickname, Email FROM dbo.Users WHERE Email = @Email';
  connection.on('debug', function (text) {
    console.log(text);
  }).on('errorMessage', function (text) {
    console.log(JSON.stringify(text, null, 2));
  }).on('infoMessage', function (text) {
    console.log(JSON.stringify(text, null, 2));
  });
  connection.on('connect', function (err) {
    if (err) return callback(err);
    const request = new Request(query, function (err, rowCount, rows) {
      if (err) return callback(err);
      callback(null, {
        user_id: rows[0][0].value,
        nickname: rows[0][1].value,
        email: rows[0][2].value
      });
    });
    request.addParameter('Email', TYPES.VarChar, email);
    connection.execSql(request);
  });
}
```

### Windows Azure SQL Database

```javascript lines theme={null}
function getByEmail (name, callback) {
  var profile = {
    user_id:     "103547991597142817347",
    nickname:    "johnfoo",
    email:       "johnfoo@gmail.com",
    name:        "John Foo",
    given_name:  "John",
    family_name: "Foo"
  };
  callback(null, profile);
}
```

### Axios

```js lines expandable theme={null}
async function getUserAsync(email, callback) {
  //should be updated as new versions of axios are made available (https://auth0-extensions.github.io/canirequire/#axios)
  const axios = require("axios@0.22.0");

  let response;

  try {
    response = await axios.post(
      //store API url in connection settings to better support SDLC environments
      configuration.baseAPIUrl + "/getUser",
      //user credentials passed as request body
      {
        email: email,
      },
      {
        timeout: 10000, //end call gracefully if request times out so script can do necessary callback
        headers: {
          //securing api call with apiKey stored in connection settings.
          //quick and easy approach however using M2M tokens is more secure as
          // a secret must not be shared between client and API.
          "x-api-key": configuration.apiKey,
        },
      }
    );
  } catch (e) {
    if (e.response.status === 404) {
      //assuming api returns 404 when no user with specified email/username found
      return callback(null, null);
    }
    //callback for any other error type
    return callback(new Error(e.message));
  }

  try {
    let user = response.data;

    //if using multiple custom db connections in your tenant prefix the
    //user_id with a connection specific key ex: "connName|" + user.user_id
    //this ensures unique user ids across all db connections
    return callback(null, {
      user_id: user.user_id,
      email: user.email,
    });
  } catch (e) {
    return callback(new Error(e.message));
  }
}
```

### Stormpath

```javascript lines expandable theme={null}
function getByEmail(email, callback) {
  // Replace the {yourStormpathClientId} with your Stormpath ID
  var url = 'https://api.stormpath.com/v1/applications/{yourStormpathClientId}/accounts';
  // Add your Stormpath API Client ID and Secret
  var apiCredentials = {
    user : '{yourStormpathApiId}',
    password: '{yourStormpathApiSecret}'
  };
  // Make a GET request to find a user by email
  request({
    url: url,
    method: 'GET',
    auth: apiCredentials,
    qs: { q: email },
    json: true
  }, function (error, response, body) {
    if (response.statusCode !== 200) return callback();
    var user = body.items[0];
    if (!user) return callback();
    var id = user.href.replace('https://api.stormpath.com/v1/accounts/', '');
    return callback(null, {
      user_id: id,
      username: user.username,
      email: user.email,
      email_verified: true
      // Add any additional fields you would like to carry over from Stormpath
    });
  });
}
```

## Learn more

* [Change Password Script Templates](/docs/authenticate/database-connections/custom-db/templates/change-password)
* [Create Script Templates](/docs/authenticate/database-connections/custom-db/templates/create)
* [Delete Script Templates](/docs/authenticate/database-connections/custom-db/templates/delete)
* [Login Script Templates](/docs/authenticate/database-connections/custom-db/templates/login)
* [Verify Script Templates](/docs/authenticate/database-connections/custom-db/templates/verify)
* [Change Email Script Template](/docs/authenticate/database-connections/custom-db/templates/change-email)


# Login Script Templates
Source: https://auth0.com/docs/authenticate/database-connections/custom-db/templates/login

Describes custom database action script templates for user login.

The Login script implements the function executed each time a user is required to authenticate. We recommend naming this function `login`.

This script is required for both legacy authentication and for [automatic migration](/docs/manage-users/user-migration/configure-automatic-migration-from-your-database). If automatic migration is configured for the connection, the migration process triggers after the first time the user logs in successfully. Auth0 recommends you set permanent `user_id` on the returned user profile to avoid creating duplicate users.

## Login function

The `login` function should:

* Send the provided user credentials to the external database’s API.
* Return the profile data of the user if authentication is successful.
* Return an error if authentication is unsuccessful.

### Definition

The `login` function accepts three parameters and returns a `callback` function:

```js lines theme={null}
login(userNameOrEmail, password, callback): function
```

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>userNameOrEmail</code></td>
      <td>String</td>
      <td>The user's username or email.</td>
    </tr>

    <tr>
      <td><code>password</code></td>
      <td>String</td>
      <td>The user's password in plain text.</td>
    </tr>

    <tr>
      <td><code>callback</code></td>
      <td>Function</td>
      <td>Used to pass error or profile data through the pipeline.</td>
    </tr>
  </tbody>
</table>

### Example

This is a pseudo-JavaScript example of how you could implement the `login` function. For language-specific examples, read [Language-specific script examples](#language-specific-script-examples).

```javascript lines expandable theme={null}
function login(userNameOrEmail, password, callback) {
  // Send credentials to external database API
  let hashedPassword = hash(password);

  let options = {
    url: "https://example.com/api/authenticate",
    body: {
      email: userNameOrEmail,
      password: hashedPassword
    }
  };

  send(options, (err, profileData) => {
    // Return error in callback if authentication is unsuccessful
    if (err) {
      return callback(new WrongUsernameOrPasswordError(userNameOrEmail, "My custom error message."));
    } else {
      // Return profile data in callback if authentication is successful
      let profile = {
        username: profileData.username,
        email: profileData.emailAddress,
        user_id: profileData.userId
      };

      return callback(null, profile);
    }
  });
}
```

### Encryption

<Warning>
  Avoid logging, storing, or transporting the password credential anywhere in its unencrypted form.
</Warning>

Encrypt the `password` value using a cryptographic hash encryption library such as `bcrypt` to prevent any potential data leak.

#### Example

```js lines theme={null}
bcrypt.hash(password, 10, function (err, hash) {
    if (err) {
        return callback(err);
    } else {
        // Return hashed password
    }
});
```

## Callback function

The `callback` function is used to pass user profile data or error data through the pipeline.

### Definition

The `callback` function accepts up to two parameters and returns a function:

```js lines theme={null}
callback(error[, profile]): function
```

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Required</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>error</code></td>
      <td>Object</td>
      <td>Required</td>
      <td>Contains error data.</td>
    </tr>

    <tr>
      <td><code>profile</code></td>
      <td>Object</td>
      <td>Optional</td>
      <td>Contains the user's profile data.</td>
    </tr>
  </tbody>
</table>

### Return the user profile

<Warning>
  The profile data returned by the Login script for a user must be consistent with the profile data returned by the Get User script.
</Warning>

If the user authenticates successfully, their profile data must be returned in the `profile` object in [normalized form](/docs/manage-users/user-accounts/user-profiles/normalized-user-profile-schema). In addition to the standard fields, you can include the `user_metadata`, `app_metadata`, and `mfa_factors` fields.

#### Example

```js lines theme={null}
return callback(null, {
    username: "username",
    user_id: "my-custom-db|username@domain.com",
    email: "username@domain.com",
    email_verified: false,
    user_metadata: {
        language: "en"
    },
    app_metadata: {
        plan: "full"
    },
    mfa_factors: [
      {
        phone: {
          value: "+15551234567"
        }
      },
    ]
});
```

### Return an error

If an error occurs, the `error` parameter should contain relevant information about what went wrong.

#### WrongUsernameOrPasswordError type object

The `WrongUsernameOrPasswordError` custom error type object allows you to pass data that will be displayed in your [Tenant Logs](/docs/deploy-monitor/logs).

##### Constructor

The `WrongUsernameOrPasswordError` constructor accepts up to two parameters:

```js wrap lines theme={null}
new WrongUsernameOrPasswordError(userNameOrEmail[, message]): WrongUsernameOrPasswordError
```

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Required</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>userNameOrEmail</code></td>
      <td>String</td>
      <td>Required</td>
      <td>Contains the user's username or email, or a <code>null</code> value.</td>
    </tr>

    <tr>
      <td><code>message</code></td>
      <td>String</td>
      <td>Optional</td>
      <td>Contains information about the error.</td>
    </tr>
  </tbody>
</table>

#### Return error with username or email

If you return an error with a value for the `userNameOrEmail` field, Auth0 will record an `fp` tenant log event.

##### Example

```js wrap lines theme={null}
return callback(new WrongUsernameOrPasswordError(userNameOrEmail, "My custom error message"));
```

<table>
  <thead>
    <tr>
      <th><strong>Tenant Log Event Field</strong></th>
      <th><strong>Value</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Code</strong></td>
      <td><code>fp</code></td>
    </tr>

    <tr>
      <td><strong>Event</strong></td>
      <td>Failed Login (Incorrect Password)</td>
    </tr>

    <tr>
      <td><strong>Description</strong></td>
      <td><code>My custom error message</code></td>
    </tr>
  </tbody>
</table>

#### Return error without username or email

If you return an error with a `null` value for the `userNameOrEmail` field, Auth0 will record an `fu` tenant log event.

##### Example

```js wrap lines theme={null}
return callback(new WrongUsernameOrPasswordError(null, "My custom error message"));
```

<table>
  <thead>
    <tr>
      <th><strong>Tenant Log Event Field</strong></th>
      <th><strong>Value</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Code</strong></td>
      <td><code>fu</code></td>
    </tr>

    <tr>
      <td><strong>Event</strong></td>
      <td>Failed Login (Invalid Email/Username)</td>
    </tr>

    <tr>
      <td><strong>Description</strong></td>
      <td><code>My custom error message</code></td>
    </tr>
  </tbody>
</table>

## Sync user profile attributes at each login

Enable the **Sync user profile attributes at each login** setting if you want Auth0 to update the `name`, `nickname`, `given_name`, `family_name`, and/or `picture` fields with the values returned from the external database on each login.

If you do not enable this setting, the values returned from the external database the first time the user logs in will persist on subsequent logins, even if they've changed in the external database.

## Language-specific script examples

Auth0 provides sample scripts for use with the following languages/technologies:

* [JavaScript](#javascript)
* [ASP.NET Membership Provider (MVC3 - Universal Providers)](#asp-net-membership-provider-mvc3-universal-providers-)
* [ASP.NET Membership Provider (MVC4 - Simple Membership)](#asp-net-membership-provider-mvc4-simple-membership-)
* [MongoDB](#mongodb)
* [MySQL](#mysql)
* [PostgreSQL](#postgresql)
* [SQL Server](#sql-server)
* [Windows Azure SQL Database](#windows-azure-sql-database)
* [Axios](#axios)
* [Stormpath](#stormpath)

### JavaScript

```javascript lines expandable theme={null}
function login(email, password, callback) {
  // This script should authenticate a user against the credentials stored in
  // your database.
  // It is executed when a user attempts to log in or immediately after signing
  // up (as a verification that the user was successfully signed up).
  //
  // Everything returned by this script will be set as part of the user profile
  // and will be visible by any of the tenant admins. Avoid adding attributes
  // with values such as passwords, keys, secrets, etc.
  //
  // The `password` parameter of this function is in plain text. It must be
  // hashed/salted to match whatever is stored in your database. For example:
  //
  //     var bcrypt = require('bcrypt@0.8.5');
  //     bcrypt.compare(password, dbPasswordHash, function(err, res)) { ... }
  //
  // There are three ways this script can finish:
  // 1. The user's credentials are valid. The returned user profile should be in
  // the following format: https://auth0.com/docs/users/normalized/auth0/normalized-user-profile-schema
  //     var profile = {
  //       user_id: ..., // user_id is mandatory
  //       email: ...,
  //       [...]
  //     };
  //     callback(null, profile);
  // 2. The user's credentials are invalid
  //     callback(new WrongUsernameOrPasswordError(email, "my error message"));
  // 3. Something went wrong while trying to reach your database
  //     callback(new Error("my error message"));
  //
  // A list of Node.js modules which can be referenced is available here:
  //
  //    https://tehsis.github.io/webtaskio-canirequire/
  const msg = 'Please implement the Login script for this database connection ' +
    'at https://manage.auth0.com/#/connections/database';
  return callback(new Error(msg));
}
```

### ASP.NET Membership Provider (MVC3 - Universal Providers)

```javascript lines expandable theme={null}
function login(email, password, callback) {
  const crypto = require('crypto');
  const sqlserver = require('tedious@11.0.3');
  const Connection = sqlserver.Connection;
  const Request = sqlserver.Request;
  const TYPES = sqlserver.TYPES;
  const connection = new Connection({
    userName: 'the username',
    password: 'the password',
    server: 'the server',
    options: {
      database: 'the db name',
      encrypt: true // for Windows Azure
    }
  });
  /**
   * hashPassword
   *
   * This function creates a hashed version of the password to store in the database.
   *
   * @password  {[string]}      the password entered by the user
   * @return    {[string]}      the hashed password
   */
  function hashPassword(password, salt) {
    // the default implementation uses HMACSHA256 and since Key length is 64
    // and default salt is 16 bytes, Membership will fill the buffer repeating the salt
    const key = Buffer.concat([salt, salt, salt, salt]);
    const hmac = crypto.createHmac('sha256', key);
    hmac.update(Buffer.from(password, 'ucs2'));
    return hmac.digest('base64');
  }
  connection.on('debug', function(text) {
    // if you have connection issues, uncomment this to get more detailed info
    //console.log(text);
  }).on('errorMessage', function(text) {
    // this will show any errors when connecting to the SQL database or with the SQL statements
    console.log(JSON.stringify(text));
  });
  connection.on('connect', function(err) {
    if (err) return callback(err);
    getMembershipUser(email, function(err, user) {
      if (err || !user || !user.profile || !user.password) return callback(err || new WrongUsernameOrPasswordError(email));
      const salt = Buffer.from(user.password.salt, 'base64');
      if (hashPassword(password, salt).toString('base64') !== user.password.password) {
        return callback(new WrongUsernameOrPasswordError(email));
      }
      callback(null, user.profile);
    });
  });

  // Membership Provider implementation used on Microsoft.AspNet.Providers NuGet
  /**
   * getMembershipUser
   *
   * This function gets a username or email and returns a the user membership provider
   * info, password hashes and salt
   *
   * @usernameOrEmail  {[string]}       the username or email, the method will do a
   *                                    query on both with an OR
   *
   * @callback         {[Function]}     first argument will be the Error if any,
   *                                    and second argument will be a user object
   */
  function getMembershipUser(usernameOrEmail, done) {
    var user = null;
    const query =
      'SELECT Memberships.UserId, Email, Users.UserName, Password ' +
      'FROM Memberships INNER JOIN Users ' +
      'ON Users.UserId = Memberships.UserId ' +
      'WHERE Memberships.Email = @Username OR Users.UserName = @Username';
    const getMembershipQuery = new Request(query, function(err, rowCount) {
      if (err || rowCount < 1) return done(err);
      done(err, user);
    });
    getMembershipQuery.addParameter('Username', TYPES.VarChar, usernameOrEmail);
    getMembershipQuery.on('row', function(fields) {
      user = {
        profile: {
          user_id: fields.UserId.value,
          nickname: fields.UserName.value,
          email: fields.Email.value,
        },
        password: {
          password: fields.Password.value,
          salt: fields.PasswordSalt.value
        }
      };
    });
    connection.execSql(getMembershipQuery);
  }
}
```

### ASP.NET Membership Provider (MVC4 - Simple Membership)

```javascript lines expandable theme={null}
function login(email, password, callback) {
  const crypto = require('crypto');
  const sqlserver = require('tedious@11.0.3');
  const Connection = sqlserver.Connection;
  const Request = sqlserver.Request;
  const TYPES = sqlserver.TYPES;
  const connection = new Connection({
    userName: 'the username',
    password: 'the password',
    server: 'the server',
    options: {
      database: 'the db name',
      encrypt: true // for Windows Azure
    }
  });
  function fixedTimeComparison(a, b) {
    var mismatch = (a.length === b.length ? 0 : 1);
    if (mismatch) {
      b = a;
    }
    for (var i = 0, il = a.length; i < il; ++i) {
      const ac = a.charCodeAt(i);
      const bc = b.charCodeAt(i);
      mismatch += (ac === bc ? 0 : 1);
    }
    return (mismatch === 0);
  }

  /**
   * validatePassword
   *
   * This function gets the password entered by the user, and the original password
   * hash and salt from database and performs an HMAC SHA256 hash.
   *
   * @password      {[string]}      the password entered by the user
   * @originalHash  {[string]}      the original password hashed from the database
   *                                (including the salt).
   * @return        {[bool]}        true if password validates
   */
  function validatePassword(password, originalHash, callback) {
    const iterations = 1000;
    const hashBytes = Buffer.from(originalHash, 'base64');
    const salt = hashBytes.slice(1, 17);
    const hash = hashBytes.slice(17, 49);
    crypto.pbkdf2(password, salt, iterations, hash.length, 'sha1', function(err, hashed) {
      if (err) return callback(err);
      const hashedBase64 = Buffer.from(hashed, 'binary').toString('base64');
      const isValid = fixedTimeComparison(hash.toString('base64'), hashedBase64);
      return callback(null, isValid);
    });
  }

  connection.on('debug', function(text) {
    // if you have connection issues, uncomment this to get more detailed info
    //console.log(text);
  }).on('errorMessage', function(text) {
    // this will show any errors when connecting to the SQL database or with the SQL statements
    console.log(JSON.stringify(text));
  });
  connection.on('connect', function(err) {
    if (err) return callback(err);
    getMembershipUser(email, function(err, user) {
      if (err || !user || !user.profile) return callback(err || new WrongUsernameOrPasswordError(email));
      validatePassword(password, user.password, function(err, isValid) {
        if (err || !isValid) return callback(err || new WrongUsernameOrPasswordError(email));
        callback(null, user.profile);
      });
    });
  });

  // Membership Provider implementation used on Microsoft.AspNet.Providers NuGet
  /**
   * getMembershipUser
   *
   * This function gets a username or email and returns a user info, password hashes and salt
   *
   * @usernameOrEamil   {[string]}    the username or email, the method will do a query
   *                                  on both with an OR
   * @callback          {[Function]}  first argument will be the Error if any, and second
   *                                  argument will be a user object
   */
  function getMembershipUser(usernameOrEmail, done) {
    var user = null;
    const query =
      'SELECT webpages_Membership.UserId, UserName, UserProfile.UserName, Password from webpages_Membership ' +
      'INNER JOIN UserProfile ON UserProfile.UserId = webpages_Membership.UserId ' +
      'WHERE UserProfile.UserName = @Username';
    const getMembershipQuery = new Request(query, function(err, rowCount) {
      if (err || rowCount < 1) return done(err);
      done(err, user);
    });
    getMembershipQuery.addParameter('Username', TYPES.VarChar, usernameOrEmail);
    getMembershipQuery.on('row', function(fields) {
      user = {
        profile: {
          user_id: fields.UserId.value,
          nickname: fields.UserName.value,
          email: fields.UserName.value,
        },
        password: fields.Password.value
      };
    });
    connection.execSql(getMembershipQuery);
  }
}
```

### MongoDB

```javascript lines theme={null}
function login(email, password, callback) {
  const bcrypt = require('bcrypt');
  const MongoClient = require('mongodb@3.1.4').MongoClient;
  const client = new MongoClient('mongodb://user:pass@mymongoserver.com');
  client.connect(function (err) {
    if (err) return callback(err);
    const db = client.db('db-name');
    const users = db.collection('users');
    users.findOne({ email: email }, function (err, user) {
      if (err || !user) {
        client.close();
        return callback(err || new WrongUsernameOrPasswordError(email));
      }
      bcrypt.compare(password, user.password, function (err, isValid) {
        client.close();
        if (err || !isValid) return callback(err || new WrongUsernameOrPasswordError(email));
        return callback(null, {
            user_id: user._id.toString(),
            nickname: user.nickname,
            email: user.email
          });
      });
    });
  });
}
```

### MySQL

```javascript lines theme={null}
function login(email, password, callback) {
  const mysql = require('mysql');
  const bcrypt = require('bcrypt');
  const connection = mysql({
    host: 'localhost',
    user: 'me',
    password: 'secret',
    database: 'mydb'
  });
  connection.connect();
  const query = 'SELECT id, nickname, email, password FROM users WHERE email = ?';
  connection.query(query, [ email ], function(err, results) {
    if (err) return callback(err);
    if (results.length === 0) return callback(new WrongUsernameOrPasswordError(email));
    const user = results[0];
    bcrypt.compare(password, user.password, function(err, isValid) {
      if (err || !isValid) return callback(err || new WrongUsernameOrPasswordError(email));
      callback(null, {
        user_id: user.id.toString(),
        nickname: user.nickname,
        email: user.email
      });
    });
  });
}
```

### PostgreSQL

```javascript lines expandable theme={null}
function login(email, password, callback) {
  //this example uses the "pg" library
  //more info here: https://github.com/brianc/node-postgres
  const bcrypt = require('bcrypt');
  const postgres = require('pg');
  const conString = 'postgres://user:pass@localhost/mydb';
  postgres.connect(conString, function (err, client, done) {
    if (err) return callback(err);
    const query = 'SELECT id, nickname, email, password FROM users WHERE email = $1';
    client.query(query, [email], function (err, result) {
      // NOTE: always call `done()` here to close
      // the connection to the database
      done();
      if (err || result.rows.length === 0) return callback(err || new WrongUsernameOrPasswordError(email));
      const user = result.rows[0];
      bcrypt.compare(password, user.password, function (err, isValid) {
        if (err || !isValid) return callback(err || new WrongUsernameOrPasswordError(email));
        return callback(null, {
          user_id: user.id,
          nickname: user.nickname,
          email: user.email
        });
      });
    });
  });
}
```

### SQL Server

```javascript lines expandable theme={null}
function login(email, password, callback) {
  //this example uses the "tedious" library
  //more info here: http://pekim.github.io/tedious/index.html
  const bcrypt = require('bcrypt');
  const sqlserver = require('tedious@11.0.3');
  const Connection = sqlserver.Connection;
  const Request = sqlserver.Request;
  const TYPES = sqlserver.TYPES;
  const connection = new Connection({
    userName:  'test',
    password:  'test',
    server:    'localhost',
    options:  {
      database: 'mydb',
      rowCollectionOnRequestCompletion: true
    }
  });
  const query = 'SELECT Id, Nickname, Email, Password FROM dbo.Users WHERE Email = @Email';
  connection.on('debug', function (text) {
    console.log(text);
  }).on('errorMessage', function (text) {
    console.log(JSON.stringify(text, null, 2));
  }).on('infoMessage', function (text) {
    console.log(JSON.stringify(text, null, 2));
  });
  connection.on('connect', function (err) {
    if (err) return callback(err);
    const request = new Request(query, function (err, rowCount, rows) {
      if (err || rowCount < 1) return callback(err || new WrongUsernameOrPasswordError(email));
      bcrypt.compare(password, rows[0][3].value, function (err, isValid) {
        if (err || !isValid) return callback(err || new WrongUsernameOrPasswordError(email));
        callback(null, {
          user_id: rows[0][0].value,
          nickname: rows[0][1].value,
          email: rows[0][2].value
        });
      });
    });
    request.addParameter('Email', TYPES.VarChar, email);
    connection.execSql(request);
  });
}
```

### Windows Azure SQL Database

```javascript lines expandable theme={null}
function login(email, password, callback) {
  //this example uses the "tedious" library
  //more info here: http://pekim.github.io/tedious/index.html
  var Connection = require('tedious@11.0.3').Connection;
  var Request = require('tedious@11.0.3').Request;
  var TYPES = require('tedious@11.0.3').TYPES;
  var bcrypt = require('bcrypt');
  var connection = new Connection({
    userName: 'your-user@your-server-id.database.windows.net',
    password: 'the-password',
    server: 'your-server-id.database.windows.net',
    options: {
      database: 'mydb',
      encrypt: true,
      rowCollectionOnRequestCompletion: true
    }
  });
  var query = "SELECT Id, Email, Password " +
    "FROM dbo.Users WHERE Email = @Email";
  connection.on('debug', function (text) {
    // Uncomment next line in order to enable debugging messages
    // console.log(text);
  }).on('errorMessage', function (text) {
    console.log(JSON.stringify(text, null, 2));
    return callback(text);
  }).on('infoMessage', function (text) {
    // Uncomment next line in order to enable information messages
    // console.log(JSON.stringify(text, null, 2));
  });
  connection.on('connect', function (err) {
    if (err) { return callback(err); }
    var request = new Request(query, function (err, rowCount, rows) {
      if (err) {
        callback(new Error(err));
      } else if (rowCount < 1) {
        callback(new WrongUsernameOrPasswordError(email));
      } else {
        bcrypt.compare(password, rows[0][2].value, function (err, isValid) {
          if (err) { callback(new Error(err)); }
          else if (!isValid) { callback(new WrongUsernameOrPasswordError(email)); }
          else {
            callback(null, {
              user_id: rows[0][0].value,
              email: rows[0][1].value
            });
          }
        });
      }
    });
    request.addParameter('Email', TYPES.VarChar, email);
    connection.execSql(request);
  });
}
```

### Axios

```js lines expandable theme={null}
async function loginAsync(email, password, callback) {
  //should be updated as new versions of axios are made available (https://auth0-extensions.github.io/canirequire/#axios)
  const axios = require("axios@0.22.0");

  let response;

  try {
    response = await axios.post(
      //store API url in connection settings to better support SDLC environments
      configuration.baseAPIUrl + "/login",
      //user credentials passed as request body
      {
        email: email,
        password: password,
      },
      {
        timeout: 10000, //end call gracefully if request times out so script can do necessary callback
        headers: {
          //securing api call with apiKey stored in connection settings.
          //quick and easy approach however using M2M tokens is more secure as
          // a secret must not be shared between client and API.
          "x-api-key": configuration.apiKey,
        },
      }
    );
  } catch (e) {
    if (e.response.status === 404) {
      //assuming api returns 404 when email/username/password invalid
      return callback(
        new WrongUsernameOrPasswordError(email, "Invalid credentials provided.")
      );
    }
    //callback for any other error type
    return callback(new Error(e.message));
  }

  try {
    let user = response.data;

    //if using multiple custom db connections in your tenant prefix the
    //user_id with a connection specific key ex: "connName|" + user.user_id
    //this ensures unique user ids across all db connections
    return callback(null, {
      user_id: user.user_id,
      email: user.email,
    });
  } catch (e) {
    return callback(new Error(e.message));
  }
}
```

### Stormpath

```javascript lines expandable theme={null}
function login(username, password, callback) {
  // Replace the {yourStormpathClientId} with your Stormpath ID
  var url = 'https://api.stormpath.com/v1/applications/{yourStormpathClientId}/loginAttempts';
  // Add your Stormpath API Client ID and Secret
  var apiCredentials = {
    user : '{yourStormpathApiId}',
    password: '{yourStormpathApiSecret}'
  };
  // Stormpath requires the user credentials be passed in as a base64 encoded message
  var credentials = Buffer.from(username + ':' + password).toString('base64');
  // Make a POST request to authenticate a user
  request({
    url: url,
    method: 'POST',
    auth: apiCredentials,
    json: {
      type: 'basic',
      // Passing in the base64 encoded credentials
      value: credentials
    }
  }, function (error, response, body) {
    // If response is successful we'll continue
    if (response.statusCode !== 200) return callback();
    // A successful response will return a URL to get the user information
    var accountUrl = body.account.href;
    // Make a second request to get the user info.
    request({
      url: accountUrl,
      auth: apiCredentials,
      json: true
    }, function (errorUserInfo, responseUserInfo, bodyUserInfo) {
      // If we get a successful response, we'll process it
      if (responseUserInfo.statusCode !== 200) return callback();
      // To get the user identifier, we'll strip out the Stormpath API
      var id = bodyUserInfo.href.replace('https://api.stormpath.com/v1/accounts/', '');
      // Finally, we'll set the data we want to store in Auth0 and migrate the user
      return callback(null, {
        user_id : id,
        username: bodyUserInfo.username,
        email: bodyUserInfo.email,
        // We set the users email_verified to true as we assume if they were a valid
        // user in Stormpath, they have already verified their email
        // If this field is not set, the user will get an email asking them to verify
        // their account. You can decide how to handle this for your use case
        email_verified: true
        // Add any additional fields you would like to carry over from Stormpath
      });
    });
  });
}
```

## Learn more

* [Change Password Script Templates](/docs/authenticate/database-connections/custom-db/templates/change-password)
* [Create Script Templates](/docs/authenticate/database-connections/custom-db/templates/create)
* [Delete Script Templates](/docs/authenticate/database-connections/custom-db/templates/delete)
* [Get User Script Templates](/docs/authenticate/database-connections/custom-db/templates/get-user)
* [Verify Script Templates](/docs/authenticate/database-connections/custom-db/templates/verify)
* [Change Email Script Template](/docs/authenticate/database-connections/custom-db/templates/change-email)


# Verify Script Templates
Source: https://auth0.com/docs/authenticate/database-connections/custom-db/templates/verify

Describes custom database action script templates for user email verification.

The Verify script implements the function executed to mark the verification status of a user’s email address in an external database. We recommend naming this function `verify`.

This script is only used in legacy authentication scenarios, and is required to support user email address verification. A verified email address is critical to a number of workflow scenarios in Auth0, and implementing this script will provide support for these out of the box.

If it's enabled, this script is executed when a user clicks on the link in the verification email sent by Auth0.

## Verify function

The `verify` function should:

* Update the `email_verified` (or equivalent) attribute in the user's profile in the external database.
* Return `true` if the update action succeeded.
* Return an error if the update action failed.

### Definition

The `verify` function accepts two parameters and returns a `callback` function:

```js lines theme={null}
verify(email, callback): function
```

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>email</code></td>
      <td>String</td>
      <td>User's email address.</td>
    </tr>

    <tr>
      <td><code>callback</code></td>
      <td>Function</td>
      <td>Used to pass error or profile data through the pipeline.</td>
    </tr>
  </tbody>
</table>

### Example

This is a pseudo-JavaScript example of how you could implement the `login` function. For language-specific examples, read [Language-specific script examples](/docs/authenticate/database-connections/custom-db/templates/verify#language-specific-script-examples).

```javascript lines theme={null}
function verify(email, callback) {
  // Send email to external database API
  let options = {
    url: "https://example.com/api/verify",
    body: {
      email: email
    }
  };

  send(options, (err) => {
    // Return error in callback if update failed
    if (err) {
      return callback(new Error(email, "My custom error message."));
    } else {
      // Return true in callback if update succeeded
      return callback(null, true);
    }
  });
}
```

## Callback function

The `callback` function is used to pass user profile data or error data through the pipeline.

### Definition

The `callback` function accepts up to two parameters and returns a function:

```js lines theme={null}
callback(error, [verified]): function
```

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Required</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>error</code></td>
      <td>Object</td>
      <td>Required</td>
      <td>Contains error data.</td>
    </tr>

    <tr>
      <td><code>verified</code></td>
      <td>Boolean</td>
      <td>Optional</td>
      <td>Contains value that represents the user's verification status in the external database (<code>true</code> or <code>false</code>). Only required if the value is <code>true</code>.</td>
    </tr>
  </tbody>
</table>

### Return a success

If the user's verification status was updated successfully in the external database, pass a `null` value for the `error` parameter, and a `true` value for the `verified` parameter.

<Warning>
  The Verify script does not change the value of the `email_verified` attribute in the user's Auth0 profile, regardless of what value is returned in the `callback` function.

  To update the `email_verified` attribute in the user's Auth0 profile, you must include the `email_verified` attribute and its value in the user profile object returned in the [Login](/docs/authenticate/database-connections/custom-db/templates/login) and [Get User](/docs/authenticate/database-connections/custom-db/templates/get-user) scripts.
</Warning>

#### Example

```js lines theme={null}
callback(null, true);
```

### Return an error

If an error occurs, the `error` parameter should contain relevant information about what went wrong.

#### Example

```js lines theme={null}
return callback(new Error("My custom error message."));
```

## Language-specific script examples

Auth0 provides sample scripts for use with the following languages/technologies:

* [JavaScript](#javascript)
* [ASP.NET Membership Provider (MVC3 - Universal Providers)](#asp-net-membership-provider-mvc3-universal-providers-)
* [ASP.NET Membership Provider (MVC4 - Simple Membership)](#asp-net-membership-provider-mvc4-simple-membership-)
* [MongoDB](#mongodb)
* [MySQL](#mysql)
* [PostgreSQL](#postgresql)
* [SQL Server](#sql-server)
* [Windows Azure SQL Database](#windows-azure-sql-database)

### JavaScript

```javascript lines theme={null}
function verify(email, callback) {
  // This script should mark the current user's email address as verified in
  // your database.
  // It is executed whenever a user clicks the verification link sent by email.
  // These emails can be customized at https://manage.auth0.com/#/emails.
  // It is safe to assume that the user's email already exists in your database,
  // because verification emails, if enabled, are sent immediately after a
  // successful signup.
  //
  // There are two ways that this script can finish:
  // 1. The user's email was verified successfully
  //     callback(null, true);
  // 2. Something went wrong while trying to reach your database:
  //     callback(new Error("my error message"));
  //
  // If an error is returned, it will be passed to the query string of the page
  // where the user is being redirected to after clicking the verification link.
  // For example, returning `callback(new Error("error"))` and redirecting to
  // https://example.com would redirect to the following URL:
  //     https://example.com?email=alice%40example.com&message=error&success=false
  const msg = 'Please implement the Verify script for this database connection ' +
    'at https://manage.auth0.com/#/connections/database';
  return callback(new Error(msg));
}
```

### ASP.NET Membership Provider (MVC3 - Universal Providers)

```javascript lines expandable theme={null}
function verify(email, callback) {
  const sqlserver = require('tedious@1.11.0');
  const Connection = sqlserver.Connection;
  const Request = sqlserver.Request;
  const TYPES = sqlserver.TYPES;
  const connection = new Connection({
    userName: 'the username',
    password: 'the password',
    server: 'the server',
    options: {
      database: 'the db name',
      encrypt: true,
      // Required to retrieve userId needed for Membership entity creation
      rowCollectionOnRequestCompletion: true
    }
  });
  connection.on('debug', function(text) {
    // if you have connection issues, uncomment this to get more detailed info
    //console.log(text);
  }).on('errorMessage', function(text) {
    // this will show any errors when connecting to the SQL database or with the SQL statements
    console.log(JSON.stringify(text));
  });
  connection.on('connect', function(err) {
    if (err) return callback(err);
    verifyMembershipUser(email, function(err, wasUpdated) {
      if (err) return callback(err); // this will return a 500
      callback(null, wasUpdated);
    });
  });
  function verifyMembershipUser(email, callback) {
    // isApproved field is the email verification flag
    const updateMembership =
      'UPDATE Memberships SET isApproved = \'true\' ' +
      'WHERE isApproved = \'false\' AND Email = @Email';
    const updateMembershipQuery = new Request(updateMembership, function(err, rowCount) {
      if (err) {
        return callback(err);
      }
      callback(null, rowCount > 0);
    });
    updateMembershipQuery.addParameter('Email', TYPES.VarChar, email);
    connection.execSql(updateMembershipQuery);
  }
}
```

### ASP.NET Membership Provider (MVC4 - Simple Membership)

```javascript lines expandable theme={null}
function verify (email, callback) {
  const sqlserver = require('tedious@1.11.0');
  const Connection = sqlserver.Connection;
  const Request = sqlserver.Request;
  const TYPES = sqlserver.TYPES;
  const connection = new Connection({
    userName: 'the username',
    password: 'the password',
    server: 'the server',
    options: {
      database: 'the db name',
      encrypt: true,
      // Required to retrieve userId needed for Membership entity creation
      rowCollectionOnRequestCompletion: true
    }
  });
  connection.on('debug', function(text) {
    // if you have connection issues, uncomment this to get more detailed info
    //console.log(text);
  }).on('errorMessage', function(text) {
    // this will show any errors when connecting to the SQL database or with the SQL statements
    console.log(JSON.stringify(text));
  });
  connection.on('connect', function (err) {
    if (err) return callback(err);
    verifyMembershipUser(email, function(err, wasUpdated) {
      if (err) return callback(err); // this will return a 500
      callback(null, wasUpdated);
    });
  });
  function findUserId(email, callback) {
    const findUserIdFromEmail =
      'SELECT UserProfile.UserId FROM ' +
      'UserProfile INNER JOIN webpages_Membership ' +
      'ON UserProfile.UserId = webpages_Membership.UserId ' +
      'WHERE UserName = @Username';
    const findUserIdFromEmailQuery = new Request(findUserIdFromEmail, function (err, rowCount, rows) {
      if (err || rowCount < 1) return callback(err);
      const userId = rows[0][0].value;
      callback(null, userId);
    });
    findUserIdFromEmailQuery.addParameter('Username', TYPES.VarChar, email);
    connection.execSql(findUserIdFromEmailQuery);
  }
  function verifyMembershipUser(email, callback) {
    findUserId(email, function (err, userId) {
      if (err || !userId) return callback(err);
      // isConfirmed field is the email verification flag
      const updateMembership =
        'UPDATE webpages_Membership SET isConfirmed = \'true\' ' +
        'WHERE isConfirmed = \'false\' AND UserId = @UserId';
      const updateMembershipQuery = new Request(updateMembership, function (err, rowCount) {
        return callback(err, rowCount > 0);
      });
      updateMembershipQuery.addParameter('UserId', TYPES.VarChar, userId);
      connection.execSql(updateMembershipQuery);
    });
  }
}
```

### MongoDB

```javascript lines theme={null}
function verify (email, callback) {
  const MongoClient = require('mongodb@3.1.4').MongoClient;
  const client = new MongoClient('mongodb://user:pass@mymongoserver.com');
  client.connect(function (err) {
    if (err) return callback(err);
    const db = client.db('db-name');
    const users = db.collection('users');
    const query = { email: email, email_verified: false };
    users.update(query, { $set: { email_verified: true } }, function (err, count) {
      client.close();
      if (err) return callback(err);
      callback(null, count > 0);
    });
  });
}
```

### MySQL

```javascript lines theme={null}
function verify(email, callback) {
  const mysql = require('mysql');
  const connection = mysql({
    host: 'localhost',
    user: 'me',
    password: 'secret',
    database: 'mydb'
  });
  connection.connect();
  const query = 'UPDATE users SET email_Verified = true WHERE email_Verified = false AND email = ?';
  connection.query(query, [ email ], function(err, results) {
    if (err) return callback(err);
    callback(null, results.length > 0);
  });
}
```

### PostgreSQL

```javascript lines theme={null}
function verify (email, callback) {
  //this example uses the "pg" library
  //more info here: https://github.com/brianc/node-postgres
  const postgres = require('pg');
  const conString = 'postgres://user:pass@localhost/mydb';
  postgres.connect(conString, function (err, client, done) {
    if (err) return callback(err);
    const query = 'UPDATE users SET email_Verified = true WHERE email_Verified = false AND email = $1';
    client.query(query, [email], function (err, result) {
      // NOTE: always call `done()` here to close
      // the connection to the database
      done();
      return callback(err, result && result.rowCount > 0);
    });
  });
}
```

### SQL Server

```javascript lines expandable theme={null}
function verify (email, callback) {
  //this example uses the "tedious" library
  //more info here: http://pekim.github.io/tedious/index.html
  const sqlserver = require('tedious@1.11.0');
  const Connection = sqlserver.Connection;
  const Request = sqlserver.Request;
  const TYPES = sqlserver.TYPES;
  const connection = new Connection({
    userName:  'test',
    password:  'test',
    server:    'localhost',
    options:  {
      database: 'mydb'
    }
  });
  const query = 'UPDATE dbo.Users SET Email_Verified = true WHERE Email_Verified = false AND Email = @Email';
  connection.on('debug', function(text) {
    console.log(text);
  }).on('errorMessage', function(text) {
    console.log(JSON.stringify(text, null, 2));
  }).on('infoMessage', function(text) {
    console.log(JSON.stringify(text, null, 2));
  });
  connection.on('connect', function (err) {
    if (err) return callback(err);
    const request = new Request(query, function (err, rows) {
      if (err) return callback(err);
      callback(null, rows > 0);
    });
    request.addParameter('Email', TYPES.VarChar, email);
    connection.execSql(request);
  });
}
```

### Windows Azure SQL Database

```javascript lines expandable theme={null}
function verify (email, callback) {
  //this example uses the "tedious" library
  //more info here: http://pekim.github.io/tedious/index.html
  var Connection = require('tedious@1.11.0').Connection;
  var Request = require('tedious@1.11.0').Request;
  var TYPES = require('tedious@1.11.0').TYPES;
  var connection = new Connection({
    userName:  'your-user@your-server-id.database.windows.net',
    password:  'the-password',
    server:    'your-server-id.database.windows.net',
    options:  {
      database: 'mydb',
      encrypt:  true
    }
  });
  var query =
    'UPDATE Users SET Email_Verified=\'TRUE\' ' +
    'WHERE Email_Verified=\'FALSE\' AND Email=@Email';
  connection.on('debug', function(text) {
    // Uncomment next line in order to enable debugging messages
    // console.log(text);
  }).on('errorMessage', function(text) {
    console.log(JSON.stringify(text, null, 2));
  }).on('infoMessage', function(text) {
    // Uncomment next line in order to enable information messages
    // console.log(JSON.stringify(text, null, 2));
  });
  connection.on('connect', function (err) {
    if (err) { return callback(err); }
    var request = new Request(query, function (err, rows) {
      if (err) { return callback(err); }
      console.log('rows: ' + rows);
      callback(null, rows > 0);
    });
    request.addParameter('Email', TYPES.VarChar, email);
    connection.execSql(request);
  });
}
```

## Learn more

* [Login Script Templates](/docs/authenticate/database-connections/custom-db/templates/login)
* [Get User Script Templates](/docs/authenticate/database-connections/custom-db/templates/get-user)
* [Create Script Templates](/docs/authenticate/database-connections/custom-db/templates/create)
* [Delete Script Templates](/docs/authenticate/database-connections/custom-db/templates/delete)
* [Change Password Script Templates](/docs/authenticate/database-connections/custom-db/templates/change-password)
* [Change Email Script Template](/docs/authenticate/database-connections/custom-db/templates/change-email)


# Test Custom Database Connections
Source: https://auth0.com/docs/authenticate/database-connections/custom-db/test-custom-database-connections

Describes how to test your custom database connections in Auth0 Dashboard.

If you use the Auth0-hosted database structure to store your users, you can test the connection by authenticating users against the same or a separate tenant.

## Test with import users to Auth0 enabled

When import users is enabled, users are gradually migrated from your external user store to Auth0 user store. In the process, users will be authenticated against the external store the first time they successfully log in. All further login attempts will be executed against the Auth0 user store. To learn more, read about automatic migrations in [Import and Export Users](/docs/manage-users/user-migration).

### Create a test tenant and application

1. Use the Auth0 Dashboard to [create a new tenant](/docs/get-started/auth0-overview/create-tenants).
2. Navigate to [Applications > Applications](https://manage.auth0.com/#/applications/applications) and create a [Machine-to-Machine](https://manage.auth0.com/#/applications/applications/create) application.

   <Warning>
     You need to note the **Client ID** and **Client Secret** when you create the custom database scripts. You need to note the **Client ID** to enable scopes in Management API.
   </Warning>
3. Enable both the **Password** and **Client Credential** grant for this application (both grants should be enabled for this test).

   <Frame>
     <img alt="Auth0 Dashboard > Applications > Advanced Settings" />
   </Frame>
4. To authorize your application, navigate to [Applications > APIs](https://manage.auth0.com/#/apis).
5. Select **Management API**.
6. Under the **Machine-to-Machine Applications** tab, use the toggle to authorize your test application.
7. Select the drop-down menu to enable the following Auth0 Management API scopes:

   * `read:users`
   * `update:users`
   * `delete:users`
   * `create:users`
   * `read:users_app_metadata`
   * `update:users_app_metadata`
   * `create:users_app_metadata`

     <Frame>
       <img alt="Auth0 Dashboard > APIs > Management API >  M2M Tab > App Permissions" />
     </Frame>

### Create test database connections

After you create a tenant and an application in Dashboard, create a source database connection and a target database connection.

1. Navigate to [Authentication > Database](https://manage.auth0.com/#/connections/database) to create a new database connection to be the source.
2. Name your test source connection, enable **Requires Username**, and select **Create**.

   <Callout icon="file-lines">
     You can create users to use in your test by navigating to [User Management > Users](https://manage.auth0.com/#/users). Once you select **Create** **Users** and populate the necessary fields, select the source database under the **Connection** field.
   </Callout>
3. Create a second database to be the target with the same configuration from step 2.

   <Callout icon="file-lines">
     You can set the **Password Policy** to **Non-empty password required** in both target and source databases so you can use simple passwords in your tests.
   </Callout>
4. In your target database, switch to the **Custom Database** view and toggle on **Use my own database**.

   <Callout icon="file-lines">
     If you want to test using Organizations with your custom databases, enable **Context object in database scripts**.
   </Callout>
5. Switch to the **Settings** view and enable **Import Users to Auth0**.
6. Switch to the **Custom Database** view, and then locate the **Database settings** section. Add the following information from your source database created in step 1:

<table>
  <thead>
    <tr>
      <th><strong>Key</strong></th>
      <th><strong>Value</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>client\_id</code></td>
      <td>Client ID of the application you created.</td>
    </tr>

    <tr>
      <td><code>client\_secret</code></td>
      <td>Client Secret of the application you created.</td>
    </tr>

    <tr>
      <td><code>auth0\_domain</code></td>
      <td>Your tenant name in the Auth0 domain: <code>yourTenant.us.auth0.com</code>.</td>
    </tr>

    <tr>
      <td><code>source\_database</code></td>
      <td>Name of the source connection.</td>
    </tr>
  </tbody>
</table>

7. Update the [Login](/docs/authenticate/database-connections/custom-db/test-custom-database-connections#login) and [Get User](/docs/authenticate/database-connections/custom-db/test-custom-database-connections#get-user) database action scripts in your target database. To learn more about best practices using database action scripts, read [Custom Database Connection and Action Scripts Best Practices](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts).
8. Select **Save and Try** on each script. You should monitor Actions Real-time Logs `console.log` output. To learn more, read [Actions Real-time Logs](/docs/customize/actions/actions-real-time-logs).
9. Select **Try Connection** to test the connection live.

## Test without Import Users enabled

1. Repeat steps in [Create a test tenant and application](/docs/authenticate/database-connections/custom-db/test-custom-database-connections#create-a-test-tenant-and-application).
2. Create one test database connection.
3. Make sure **Import Users to Auth0** under your source database settings is disabled. Users will authenticate against the external user store during each login attempt.
4. Update all database actions scripts with the samples below.

### Get User script

The [Get User](/docs/authenticate/database-connections/custom-db/templates/get-user) script implements an executable function that determines the current state of a user.

When **Import Users to Auth0** is enabled, the Get User script runs when a user attempts to sign up to check if the user already exists in the external user store.

The Get User script also runs when a user attempts to:

* Change a user's email address ([Change Email](/docs/authenticate/database-connections/custom-db/templates/change-email) script)
* Log in ([Login](/docs/authenticate/database-connections/custom-db/templates/login) script)
* Change a user's password ([Change Password](/docs/authenticate/database-connections/custom-db/templates/change-password) script)

When **Import Users to Auth0** is disabled, the Get User script runs when a user attempts to sign up to check if the user already exists in the external user store. If a user already exists in the external user store, it will not execute the Create script.

The Get User script also runs when a user attempts to:

* Create a user ([Create](/docs/authenticate/database-connections/custom-db/templates/create) script)
* Change a user's email address ([Change Email](/docs/authenticate/database-connections/custom-db/templates/change-email) script)
* Change a user's password ([Change Password](/docs/authenticate/database-connections/custom-db/templates/change-password) script)

#### Example

```js lines expandable theme={null}
async function getUser(user, context, callback) {
    log(`Script started.`);
    log(`Requesting an Access Token from "${configuration.auth0_domain}".`);
    let accessToken = await getAccessToken();
    accessToken = accessToken.access_token;
    if (!accessToken) return log(`Failed to get an Access Token from "${configuration.auth0_domain}".`, true);
    log(`The Access Token is available. Searching for user "${user}" in "${configuration.source_database}"`);
    user = user.toLowerCase();
    const searchQuery = encodeURI(`identities.connection:"${configuration.source_database}"+AND+(email:${user} OR username:${user})`);
    var options = {
        method: `GET`,
        url: `https://${configuration.auth0_domain}/api/v2/users?q=${searchQuery}`,
        headers: {
            Authorization: `Bearer ${accessToken}`,
        }
    };
    request(options, function (error, response) {
        if (error) return log(`Cannot connect to "${configuration.source_database}" database.`, true);
        let search_results = JSON.parse(response.body);
        let profile = null;
        if (search_results.length > 0) {
            log(`A user "${user}" is FOUND in "${configuration.source_database}" database.`);
            profile = {
                user_id: search_results[0].user_id.toString(),
                nickname: search_results[0].nickname,
                username: search_results[0].username,
                email: search_results[0].email
            };
        } else {
            log(`A user "${user}" is NOT FOUND in "${configuration.source_database}" database.`);
        }
        log(`Script completed!`);
        return callback(null, profile);
    });
    /* -- GET ACCESS TOKEN VIA CLIENT CREDENTIALS -- */
    async function getAccessToken() {
        var options = {
            method: `POST`,
            url: `https://${configuration.auth0_domain}/oauth/token`,
            headers: {
                "Content-Type": `application/x-www-form-urlencoded`,
            },
            form: {
                grant_type: `client_credentials`,
                client_id: configuration.client_id,
                client_secret: configuration.client_secret,
                audience: `https://${configuration.auth0_domain}/api/v2/`
            },
            json: true
        };
        return new Promise(function (resolve) {
            request(options, function (error, response) {
                resolve(error || response.body);
            });
        });
    }
    /* -- LOGGING -- */
    function log(message, error = false) {
        const script_name = `GET USER`;
        const error_label = error ? `(ERROR)` : ``;
        const return_message = `${script_name}: ${error_label} ${message}`;
        console.log(return_message);
        if (error) return callback(new Error(return_message));
    }
}
```

### Login script

The [Login](/docs/authenticate/database-connections/custom-db/templates/login) script implements an executable function that authenticates a user when a user logs in. If the user exists in the target database (Auth0), it authenticates them using that record. Otherwise, it authenticates the user with their record in the source database (external).

#### Example

```javascript lines expandable theme={null}
function login(usernameOrEmail, password, context, callback) {
  log(`Script started.`);
  const jwt = require('jsonwebtoken');
  const options = {
    method: `POST`,
    url: `https://${configuration.auth0_domain}/oauth/token`,
    headers: { "Content-Type": `application/x-www-form-urlencoded` },
    json: true,
    form: {
      grant_type: `http://auth0.com/oauth/grant-type/password-realm`,
      client_id: configuration.client_id,
      client_secret: configuration.client_secret,
      username: usernameOrEmail,
      password: password,
      realm: `${configuration.source_database}`
    }
  };
  request(options, function (error, response, body) {
    log(`Attempting to authenticate a user "${usernameOrEmail}" against "${configuration.source_database}" database in "${configuration.auth0_domain}" tenant.`);
    if (error) return log(`Cannot connect to "${configuration.auth0_domain}" database.`, true);
    if (response.statusCode !== 200) {
      console.log(`LOGIN: (ERROR) ${response.body.error_description}`);
      return callback(new WrongUsernameOrPasswordError(usernameOrEmail, `LOGIN: (ERROR) ${response.body.error_description}`));
    }
    log(`Successfuly authenticated user "${usernameOrEmail}" against "${configuration.source_database}" database in "${configuration.auth0_domain}" tenant.`);
    const decoded_id_token = jwt.decode(body.id_token);
    const profile = {
      user_id: decoded_id_token.sub,
      nickname: decoded_id_token.nickname,
      username: decoded_id_token.username,
      email: decoded_id_token.email
    };
    log(`Script completed.`);
    return callback(null, profile);
  });
  /* -- LOGGING -- */
  function log(message, error = false) {
    const script_name = `LOGIN`;
    const error_label = error ? `(ERROR)` : ``;
    const return_message = `${script_name}: ${error_label} ${message}`;
    console.log(return_message);
    if (error) return callback(new Error(return_message));
  }
}
```

### Create script

The [Create script](/docs/authenticate/database-connections/custom-db/templates/create) implements an executable function that creates a corresponding user record in the external database when a user signs up through <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>, or is created in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or with the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

#### Example

```js lines expandable theme={null}
async function create(user, context, callback) {
  log(`Script started.`);
  log(`Requesting an Access Token from "${configuration.auth0_domain}".`);
  let accessToken = await getAccessToken();
  if (!accessToken.access_token) return log(`Failed to get an Access Token from "${configuration.auth0_domain}".`, true);
  accessToken = accessToken.access_token;
  log(`The Access Token is available. Attempting to create a user "${user.email}" in "${configuration.source_database}"`);
  const options = {
    method: `POST`,
    url: `https://${configuration.auth0_domain}/api/v2/users`,
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": `application/x-www-form-urlencoded`
    },
    form: {
      connection: configuration.source_database,
      email: user.email,
      password: user.password,
      username: user.username
    },
    json: true
  };
  request(options, function (error, response) {
    if (error) return log(`Cannot connect to "${configuration.source_database}" database.`, true);
    switch (response.statusCode) {
      case 201:
        log(`The user "${user.email}" is successfuly created in "${configuration.source_database}" database.`);
        return callback(null);
      case 409:
        return callback(new ValidationError(`user_exists`, `The user already exists in "${configuration.source_database}" database.`));
      default:
        return log(`Failed to create a user "${user.email}" in "${configuration.source_database}" database. Error: "${response.statusCode}, ${response.body.message}"`, true);
    }
  });
  /* -- GET ACCESS TOKEN VIA CLIENT CREDENTIALS -- */
  async function getAccessToken() {
    var options = {
      method: `POST`,
      url: `https://${configuration.auth0_domain}/oauth/token`,
      headers: {
        "Content-Type": `application/x-www-form-urlencoded`,
      },
      form: {
        grant_type: `client_credentials`,
        client_id: configuration.client_id,
        client_secret: configuration.client_secret,
        audience: `https://${configuration.auth0_domain}/api/v2/`
      },
      json: true
    };
    return new Promise(function (resolve) {
      request(options, function (error, response) {
        resolve(error || response.body);
      });
    });
  }
  /* -- LOGGING -- */
  function log(message, error = false) {
    const script_name = `CREATE`;
    const error_label = error ? `(ERROR)` : ``;
    const return_message = `${script_name}: ${error_label} ${message}`;
    console.log(return_message);
    if (error) return callback(new Error(return_message));
  }
}
```

### Delete script

The [Delete script](/docs/authenticate/database-connections/custom-db/templates/delete) implements an executable function that deletes a user from Auth0 and the external database in the same operation when a user is deleted in the Auth0 Dashboard or with the Auth0 Management API.

#### Example

```js lines expandable theme={null}
async function deleteUser(user, context, callback) {
  log(`Script started.`);
  log(`Requesting an Access Token from "${configuration.auth0_domain}".`);
  let accessToken = await getAccessToken();
  if (!accessToken.access_token) return log(`Failed to get an Access Token from "${configuration.auth0_domain}".`, true);
  accessToken = accessToken.access_token;
  log(`The Access Token is available. Attempting to delete a user "${user}" from "${configuration.source_database}"`);
  const options = {
    method: `DELETE`,
    url: `https://${configuration.auth0_domain}/api/v2/users/${user}`,
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": `application/x-www-form-urlencoded`
    },
    json: true
  };
  request(options, function (error, response) {
    if (error) return log(`Cannot connect to "${configuration.source_database}" database.`, true);
    switch (response.statusCode) {
      case 204:
        log(`The user "${user}" is successfuly deleted from "${configuration.source_database}" database.`);
        return callback(null);
      default:
        return log(`Failed to delete a user "${user}" from "${configuration.source_database}" database. Error: "${response.statusCode}, ${response.body.message}"`, true);
    }
  });
  /* -- GET ACCESS TOKEN VIA CLIENT CREDENTIALS -- */
  async function getAccessToken() {
    var options = {
      method: `POST`,
      url: `https://${configuration.auth0_domain}/oauth/token`,
      headers: {
        "Content-Type": `application/x-www-form-urlencoded`,
      },
      form: {
        grant_type: `client_credentials`,
        client_id: configuration.client_id,
        client_secret: configuration.client_secret,
        audience: `https://${configuration.auth0_domain}/api/v2/`
      },
      json: true
    };
    return new Promise(function (resolve) {
      request(options, function (error, response) {
        resolve(error || response.body);
      });
    });
  }
  /* -- LOGGING -- */
  function log(message, error = false) {
    const script_name = `DELETE`;
    const error_label = error ? `(ERROR)` : ``;
    const return_message = `${script_name}: ${error_label} ${message}`;
    console.log(return_message);
    if (error) return callback(new Error(return_message));
  }
}
```

### Verify script

The [Verify script](/docs/authenticate/database-connections/custom-db/templates/verify) implements an executable function that marks the verification status of a user’s email address in the external database when a user clicks on the link in the verification email sent by Auth0.

#### Example

```js lines expandable theme={null}
async function verify(user, context, callback) {
  log(`Script started.`);
  log(`Requesting an Access Token from "${configuration.auth0_domain}".`);
  let accessToken = await getAccessToken();
  if (!accessToken.access_token) return log(`Failed to get an Access Token from "${configuration.auth0_domain}".`, true);
  accessToken = accessToken.access_token;
  log(`The Access Token is available. Searching for user "${user}" in "${configuration.source_database}"`);
  user = user.toLowerCase();
  const searchQuery = encodeURI(`identities.connection:"${configuration.source_database}"+AND+(email:${user} OR username:${user})`);
  var options = {
    method: `GET`,
    url: `https://${configuration.auth0_domain}/api/v2/users?q=${searchQuery}`,
    headers: {
      Authorization: `Bearer ${accessToken}`,
    }
  };
  request(options, function (error, response) {
    if (error) return log(`Cannot connect to "${configuration.source_database}" database.`, true);
    let search_results = JSON.parse(response.body);
    if (search_results.length > 0) {
      log(`A user "${user}" is found in "${configuration.source_database}" database.`);
      const user_id = search_results[0].user_id.toString();
      log(`Attempting to mark user "${user_id}" as verified in "${configuration.source_database}" database`);
      const options = {
        method: `PATCH`,
        url: `https://${configuration.auth0_domain}/api/v2/users/${user_id}`,
        headers: {
          Authorization: `Bearer ${accessToken}`,
          "Content-Type": `application/x-www-form-urlencoded`
        },
        form: {
          email_verified: true,
        },
        json: true
      };
      request(options, function (error, response) {
        if (error) return log(`Cannot connect to "${configuration.source_database}" database.`, true);
        switch (response.statusCode) {
          case 200:
            log(`The user "${user}" is marked as verified in "${configuration.source_database}" database.`);
            return callback(null, true);
          default:
            return log(`Failed to mark a user "${user}" as verified in "${configuration.source_database}" database. Error: "${response.statusCode}, ${response.body.message}"`, true);
        }
      });
    } else {
      log(`A user "${user}" is not found in "${configuration.source_database}" database. Unable to verify.`, true);
    }
  });
  /* -- GET ACCESS TOKEN VIA CLIENT CREDENTIALS -- */
  async function getAccessToken() {
    var options = {
      method: `POST`,
      url: `https://${configuration.auth0_domain}/oauth/token`,
      headers: {
        "Content-Type": `application/x-www-form-urlencoded`,
      },
      form: {
        grant_type: `client_credentials`,
        client_id: configuration.client_id,
        client_secret: configuration.client_secret,
        audience: `https://${configuration.auth0_domain}/api/v2/`
      },
      json: true
    };
    return new Promise(function (resolve) {
      request(options, function (error, response) {
        resolve(error || response.body);
      });
    });
  }
  /* -- LOGGING -- */
  function log(message, error = false) {
    const script_name = `VERIFY`;
    const error_label = error ? `(ERROR)` : ``;
    const return_message = `${script_name}: ${error_label} ${message}`;
    console.log(return_message);
    if (error) return callback(new Error(return_message));
  }
}
```

### Change Password script

The [Change Password script](/docs/authenticate/database-connections/custom-db/templates/change-password) implements an executable function that updates a user's password in the external database when a password change workflow starts from the Auth0 Dashboard or the Auth0 Management API.

#### Example

```js lines expandable theme={null}
async function changePassword(user, newPassword, context, callback) {
  log(`Script started.`);
  log(`Requesting an Access Token from "${configuration.auth0_domain}".`);
  let accessToken = await getAccessToken();
  if (!accessToken.access_token) return log(`Failed to get an Access Token from "${configuration.auth0_domain}".`, true);
  accessToken = accessToken.access_token;
  log(`The Access Token is available. Searching for user "${user}" in "${configuration.source_database}" database.`);
  user = user.toLowerCase();
  const searchQuery = encodeURI(`identities.connection:"${configuration.source_database}"+AND+(email:${user} OR username:${user})`);
  var options = {
    method: `GET`,
    url: `https://${configuration.auth0_domain}/api/v2/users?q=${searchQuery}`,
    headers: {
      Authorization: `Bearer ${accessToken}`,
    }
  };
  request(options, function (error, response) {
    if (error) return log(`Cannot connect to "${configuration.source_database}" database.`, true);
    let search_results = JSON.parse(response.body);
    if (search_results.length > 0) {
      log(`A user "${user}" is found in "${configuration.source_database}" database.`);
      const user_id = search_results[0].user_id.toString();
      log(`Attempting to change password for user "${user_id}" in "${configuration.source_database}" database.`);
      const options = {
        method: `PATCH`,
        url: `https://${configuration.auth0_domain}/api/v2/users/${user_id}`,
        headers: {
          Authorization: `Bearer ${accessToken}`,
          "Content-Type": `application/x-www-form-urlencoded`
        },
        form: {
          password: newPassword,
        },
        json: true
      };
      request(options, function (error, response) {
        if (error) return log(`Cannot connect to "${configuration.source_database}" database.`, true);
        switch (response.statusCode) {
          case 200:
            log(`The user "${user}" password successfully changed in "${configuration.source_database}" database.`);
            return callback(null, true);
          default:
            return log(`Failed to change password for "${user}"  in "${configuration.source_database}" database. Error: "${response.statusCode}, ${response.body.message}"`, true);
        }
      });
    } else {
      log(`A user "${user}" is not found in "${configuration.source_database}" database. Unable to change password.`, true);
    }
  });
  /* -- GET ACCESS TOKEN VIA CLIENT CREDENTIALS -- */
  async function getAccessToken() {
    var options = {
      method: `POST`,
      url: `https://${configuration.auth0_domain}/oauth/token`,
      headers: {
        "Content-Type": `application/x-www-form-urlencoded`,
      },
      form: {
        grant_type: `client_credentials`,
        client_id: configuration.client_id,
        client_secret: configuration.client_secret,
        audience: `https://${configuration.auth0_domain}/api/v2/`
      },
      json: true
    };
    return new Promise(function (resolve) {
      request(options, function (error, response) {
        resolve(error || response.body);
      });
    });
  }
  /* -- LOGGING -- */
  function log(message, error = false) {
    const script_name = `CHANGE PASSWORD`;
    const error_label = error ? `(ERROR)` : ``;
    const return_message = `${script_name}: ${error_label} ${message}`;
    console.log(return_message);
    if (error) return callback(new Error(return_message));
  }
}
```

### Change Email script

The [Change Email](/docs/authenticate/database-connections/custom-db/templates/change-email) script implements an executable function that updates a user's email address when the user changes their email address or their email address verification status.

This script is not available in the Auth0 Dashboard. You must call the Management API [Update a connection](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id) endpoint and provide the `options.customScripts.change_email` property.

#### Example

```js lines expandable theme={null}
async function changeEmail(user, newEmail, verified, callback) {
  log(`Script started.`);
  log(`Requesting an Access Token from "${configuration.auth0_domain}".`);
  let accessToken = await getAccessToken();
  if (!accessToken.access_token) return log(`Failed to get an Access Token from "${configuration.auth0_domain}".`, true);
  accessToken = accessToken.access_token;
  log(`The Access Token is available. Searching for user "${user}" in "${configuration.source_database}" database.`);
  user = user.toLowerCase();
  const searchQuery = encodeURI(`identities.connection:"${configuration.source_database}"+AND+(email:${user} OR username:${user})`);
  var options = {
    method: `GET`,
    url: `https://${configuration.auth0_domain}/api/v2/users?q=${searchQuery}`,
    headers: {
      Authorization: `Bearer ${accessToken}`,
    }
  };
  request(options, function (error, response) {
    if (error) return log(`Cannot connect to "${configuration.source_database}" database.`, true);
    let search_results = JSON.parse(response.body);
    if (search_results.length > 0) {
      log(`A user "${user}" is found in "${configuration.source_database}" database.`);
      const user_id = search_results[0].user_id.toString();
      log(`Attempting to change email / verified status for user "${user_id}" in "${configuration.source_database}" database.`);
      const options = {
        method: `PATCH`,
        url: `https://${configuration.auth0_domain}/api/v2/users/${user_id}`,
        headers: {
          Authorization: `Bearer ${accessToken}`,
          "Content-Type": `application/x-www-form-urlencoded`
        },
        form: {
          email: newEmail,
          email_verified: verified || false
        },
        json: true
      };
      request(options, function (error, response) {
        if (error) return log(`Cannot connect to "${configuration.source_database}" database.`, true);
        switch (response.statusCode) {
          case 200:
            log(`The user "${user}" email / verified status successfully changed in "${configuration.source_database}" database.`);
            return callback(null, true);
          default:
            return log(`Failed to change email / verified status for "${user}"  in "${configuration.source_database}" database. Error: "${response.statusCode}, ${response.body.message}"`, true);
        }
      });
    } else {
      log(`A user "${user}" is not found in "${configuration.source_database}" database. Unable to change email / verified status.`, true);
    }
  });
  /* -- GET ACCESS TOKEN VIA CLIENT CREDENTIALS -- */
  async function getAccessToken() {
    var options = {
      method: `POST`,
      url: `https://${configuration.auth0_domain}/oauth/token`,
      headers: {
        "Content-Type": `application/x-www-form-urlencoded`,
      },
      form: {
        grant_type: `client_credentials`,
        client_id: configuration.client_id,
        client_secret: configuration.client_secret,
        audience: `https://${configuration.auth0_domain}/api/v2/`
      },
      json: true
    };
    return new Promise(function (resolve) {
      request(options, function (error, response) {
        resolve(error || response.body);
      });
    });
  }
  /* -- LOGGING -- */
  function log(message, error = false) {
    const script_name = `CHANGE EMAIL`;
    const error_label = error ? `(ERROR)` : ``;
    const return_message = `${script_name}: ${error_label} ${message}`;
    console.log(return_message);
    if (error) return callback(new Error(return_message));
  }
}
```

## Learn more

* [Password Strength in Auth0 Database Connections](/docs/authenticate/database-connections/password-strength)
* [Custom Database Action Script Environment Best Practices](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/environment)
* [Password Options in Auth0 Database Connections](/docs/authenticate/database-connections/password-options)
* [Configure Identity Provider Connection for User Profile Updates](/docs/manage-users/user-accounts/user-profiles/configure-connection-sync-with-auth0)
* [Connection Settings Best Practices](/docs/authenticate/connection-settings-best-practices)
* [Create Custom Database Connections](/docs/authenticate/database-connections/custom-db/create-db-connection)


# Login Script for IBM DB2
Source: https://auth0.com/docs/authenticate/database-connections/db2-script

Provides a custom callback script for those integrating with IBM DB2.

If you are integrating Auth0 with [IBM DB2](https://www.ibm.com/analytics/us/en/technology/db2), you can use the following script for your login process.

```javascript lines expandable theme={null}
function login (email, password, callback) {
  var ibmdb = require("ibm_db");
  var bcrypt = require('bcrypt');
  var credentials = "";
  credentials += "DRIVER={DB2};";
  credentials += "DATABASE=SAMPLE;";
  credentials += "HOSTNAME=<db2host_url>;";
  credentials += "UID=<user_name>;";
  credentials += "PWD=<password>;";
  credentials += "PORT=50001;";
  credentials += "PROTOCOL=TCPIP";
  ibmdb.open(credentials, function(err, conn) {
    if (err) callback(new Error("Error while trying to connect to auth source"));
    conn.query("select * from =<user_name>.USERS where email='" + email + "'", function(err, data) {
      if (err) callback(new Error(err));
      else {
      if (!bcrypt.compareSync(password, data[0].PASSWORDHASH)) return;
      //map attributes to profile – sample below
      var profile = {
        user_id: data[0].ID,
        nickname: data[0].EMAIL,
        email: data[0].EMAIL,
        given_name : data[0].FIRSTNAME,
        family_name : data[0].LASTNAME
      };
      callback(null,profile);
      }
      conn.close(function() {
      });
    });
  });
}
```


# Flexible Identifiers and Attributes
Source: https://auth0.com/docs/authenticate/database-connections/flexible-identifiers-and-attributes

Describes limitations of Identifiers and Attributes.

<Warning>
  Enabling Flexible Identifiers on your tenant has the potential to introduce breaking changes to your production environment. Test this feature thoroughly in a development environment and note your current connection settings before releasing it widely.
</Warning>

A **Flexible Identifier** is the attribute a user inputs on a login screen to authenticate themselves. You can choose from email, username, phone, or a combination of two or more.

### Attribute and Identifier definitions

For this product, an **Attribute** is a piece of user data that can be stored, such as email, phone number, and username. All Identifiers are Attributes, but only specific attributes are Identifiers.

An **Identifier** is a unique Attribute that recognizes a distinct user in a given connection. Email, phone, and username can uniquely identify an individual and serve as Identifiers, while other attributes contribute to the user's profile without uniquely identifying a user.

### Use Flexible Identifiers

Flexible Identifiers is for general access with the following limitations:

* Flexible Identifiers, including the phone attribute, are only available with [Universal Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience) and you must [configure a phone provider](/docs/customize/phone-messages/configure-phone-messaging-providers).
* You must configure [Identifier First](/docs/authenticate/login/auth0-universal-login/identifier-first) to use phone verification on signup.
* The email address attribute must be enabled to use [Adaptive MFA](/docs/secure/multi-factor-authentication/adaptive-mfa).
* You must have email on the User Profile to use Signup invites for [Organizations](/docs/manage-users/organizations/organizations-overview).
* End users blocked under <Tooltip href="/docs/glossary?term=Brute+Force+Protection">Brute Force Protection</Tooltip> cannot unblock themselves via an SMS message. Other methods are available; to learn more, [read Brute Force Protection](/docs/secure/attack-protection/brute-force-protection).
* Flexible Identifiers moves the identifier field to the first login screen and changes the reset password prompt from email to username.
* OTP tokens for phone and email identifier verification have a lifetime of 900 seconds.

### Issues using Flexible Identifiers

The following is a list of potential issues you may encounter while configuring and managing Flexible Identifiers:

* If the scope `phone` is not specified in the authorization request by your application, you will not receive the `phone_number` claim. To learn more about scopes, [read Scopes](/docs/get-started/apis/scopes).
* Your Get User custom database action script must be valid when **Import Users to Auth0** is set to **on.** To learn more, [read Configure Automatic Migration from Your Database](/docs/manage-users/user-migration/configure-automatic-migration-from-your-database).
* Each user must be assigned a unique username, email address and phone number if **Custom Database with Import Mode** is set to **on**.
* If you use the custom database action script Change Password and want to set `email` and `email_verified` to `True`, you must return the preferred `email_verified` state on the object. To learn more, [read Change Password](/docs/authenticate/database-connections/custom-db/templates/change-password).
* If you use a custom database connection with Import Users to Auth0 toggled off, you must align your user profile properties with the Auth0 normalized user profile. To learn more, [read Normalized User Profile](/docs/manage-users/user-accounts/user-profiles/normalized-user-profiles).
* If you use a custom database connection with Import Users to Auth0 toggled on, Auth0 will check for uniqueness of `phone_number` and `phone_verified.`
* Identifier First prompts display all identifiers on the first screen and remove your previous settings, and the Reset Password prompt will display the input field to Username instead of Email.
* Familiarize yourself with best practices to avoid SMS Pumping attacks. To learn more, read our [whitepaper on SMS Pumping](https://www.okta.com/resources/whitepaper-handling-toll-fraud-and-sms-pumping-with-twilio-in-the-okta-customer-identity/).


# Configure the Flexible Password Policy for Auth0 Database Connections
Source: https://auth0.com/docs/authenticate/database-connections/flexible-password-policy

Use the Flexible Password Policy to define password strength and composition rules for database connections in Auth0.

<Warning>
  The Flexible Password Policy is currently in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal). To learn more about Auth0's product release cycle, read [Product Release Stages](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

The Flexible Password Policy replaces the [legacy password policies](/docs/authenticate/database-connections/password-options) to provide increased granularity and configuration options.

| Policy              | Legacy Behavior                                                                                              | Flexible Password Policy Behavior                                                                                                        |
| ------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Password strength   | Choose from five preset levels of complexity.<br /><br />Silently truncates passwords beyond maximum length. | Customize all complexity requirements independently.<br /><br />Choose behavior for passwords beyond maximum length (truncate or error). |
| Password history    | Configure the number of previous passwords that a user cannot reuse, up to 24.                               | Retains equivalent functionality.                                                                                                        |
| Password dictionary | Uses one built-in dictionary of 10,000 common words.                                                         | Choose between two built-in dictionaries of 10,000 or 100,000 common words.                                                              |
| Block personal data | Blocks a fixed set of user data fields.                                                                      | Fully customize which fields to block, up to 12.                                                                                         |

In the Management API's configuration schema for database connections, the Flexible Password Policy also replaces the legacy password policy `options` objects and values with a single, configurable `password_options` object.

## Prerequisites

The following requirements are necessary to use the Flexible Password Policy:

* You must use a database connection with the Auth0 user store (`"strategy": "auth0"`).

* The tenant must use Universal Login.

* The tenant must not have a custom password reset screen configured.

* If using the Management API, your access token must have the `read:connections` and `update:connections` scopes. Without them, you cannot retrieve or modify the database connection's configuration, respectively.

## Enable the Flexible Password Policy

You can enable the Flexible Password Policy using the Auth0 Dashboard or the Management API.

<Tabs>
  <Tab title="Auth0 Dashboard">
    To enable the Flexible Password Policy from the Auth0 Dashboard:

    1. Go to [Auth0 Dashboard > Authentication > Database](https://manage.auth0.com/#/connections/database), and select the name of the connection you want to edit.

    2. Select the **Authentication Methods** tab. Then, in the **Password** section, select **Configure** to open the **Password** panel.

    3. In the Flexible Password Policy banner at the top, select **Activate**, then select **Confirm**.

    This converts your database connection's existing password policies from the legacy configuration to the Flexible Password Policy configuration and returns you to the **Authentication Methods** tab.

    The same **Authentication Methods > Password > Configure** panel now shows the Flexible Password Policy configuration options in three sections: **Policy**, **Composition**, and **Security**.

    <AccordionGroup>
      <Accordion title="Policy settings">
        The **Policy** section contains the following settings:

        * **Password for login**:  Allow or block users from logging in with a password.

        * **Password on signup**:  Allow or block users from signing up with a password.

        * **Self-service change password**:  Allow or block users from changing their own passwords.

        * **Support users without a password**:  Toggle whether users can be created without a password via the Management and Authentication APIs.
      </Accordion>

      <Accordion title="Composition settings">
        The **Composition** section contains the following settings:

        * **Minimum password length**: Enter the minimum password length.

        * **Additional composition rules**

          * **Required password options**: At least one uppercase letter, at least one lowercase letter, at least one number, at least one special character, and/or at least 3 of 4 of the previous character types.

          * **Block three or more sequential characters**, like ABC or 321

          * **Block three or more identical characters in a row**, like 000

          * **Maximum password length exceeded**: For passwords longer than 72 bytes, choose between **Truncate password** (allow longer passwords but only encrypt the first 72 bytes) or **Show error** (reject passwords longer than 72 bytes).
      </Accordion>

      <Accordion title="Security settings">
        The **Security** section contains the following settings:

        * **Password history**: Prevent password reuse.

          * **Password history size**: Choose the number of previous passwords that users cannot reuse.

        * **Password dictionary**: Prevent users from using passwords in the specified dictionary or in your additional dictionary entries.

          * **Default dictionary**: Choose between the [10,000 common words](https://github.com/danielmiessler/SecLists/blob/master/Passwords/Common-Credentials/10k-most-common.txt) or [100,000 common words](https://github.com/danielmiessler/SecLists/blob/master/Passwords/Common-Credentials/100k-most-used-passwords-NCSC.txt) dictionaries.

          * **Additional dictionary entries**: Enter additional prohibited passwords, one per line.

        * **Block profile data in passwords**: Prevent users from setting passwords that contain the user's profile data.

          * **Select profile fields to block**: Choose from eight common default fields to block.

          * **Additional profile fields to block**: Enter additional profile fields to block.
      </Accordion>
    </AccordionGroup>

    After you modify these settings, click **Save**.
  </Tab>

  <Tab title="Management API">
    To enable the Flexible Password Policy using the Management API, you need update your database connection's `options` configuration:

    1. First, get your database connection's current configuration using the [Get a connection endpoint](https://auth0.com/docs/api/management/v2/connections/get-connections-by-id).

    2. In the `options` object, remove the following legacy password objects and values:

       * `passwordPolicy`
       * `password_complexity_options`
       * `password_history`
       * `password_no_personal_info`
       * `password_dictionary`

    3. In the `options` object, append a single `password_options` object containing your desired Flexible Password Policy configuration.

       You can view the full schema for the `password_options` object in the API reference (as in the [Update a connection endpoint](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id) body parameters).

    4. Update your database connection with the new `options` object using the [Update a connection endpoint](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id).

       <Warning>
         This endpoint overwrites the entire `options` object with the version you provide, so include the entire modified object in your `PATCH` request to preserve your database connection's other configuration.
       </Warning>

    As an example, the following two `options` configurations (one legacy, one Flexible Password Policy) both prevent users from using their five most recent passwords, any words in the 10,000 common words list, or the additional entries `badPassword` and `reallyBadPassword`:

    <Columns>
      <div>
        ```json Legacy password policy example theme={null}
        "password_history": {
            "enable": true,
            "size": 5
        },
        "password_dictionary": {
            "enable": true,
            "dictionary": [
                "badPassword",
                "reallyBadPassword"
            ]
        }
        ```
      </div>

      <div>
        ```json Flexible Password Policy example theme={null}
        "password_options": {
            "history": {
                "active": true,
                "size": 5
            },
            "dictionary": {
                "active": true,
                "default": "en_10k",
                "custom": [
                    "badPassword",
                    "reallyBadPassword"
                ]
            }
        }
        ```
      </div>
    </Columns>

    You can verify the update by getting your database connection's configuration with the [Get a connection endpoint](https://auth0.com/docs/api/management/v2/connections/get-connections-by-id) again. If the response contains the `password_options` object, the Flexible Password Policy is enabled for that database connection.
  </Tab>
</Tabs>

## Revert to the legacy password policies

To revert back to the legacy password policies, you need to use the Management API.

Follow the same process as above to update the database connection with its original `options`, removing the entire `password_options` object.


# Non-Unique Emails
Source: https://auth0.com/docs/authenticate/database-connections/non-unique-emails

How to set up non-unique emails and their related identifiers

<Callout icon="file-lines">
  Non-Unique Emails is currently in Early Access. To learn more about Auth0 releases, review [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Callout>

Non-Unique Emails allows multiple user accounts that share a database connection to use one email address while another attribute (like username or phone number) serves as the primary identifier. Whether you're a parent managing multiple child accounts with one email address or a small business with one email per location, Non-Unique Emails allows you to maintain a secure, account-specific login and password reset experience.

### Considerations

Review the following to ensure Non-Unique Emails is the right fit for your use case.

#### Primary identifier requirements

Email cannot be used as the primary identifier when using Non-Unique Emails. You must configure another attribute as the primary identifier, which will be used for authentication, password resets, and account management.

For more information about identifiers and attributes, read [Flexible Identifiers](/docs/authenticate/database-connections/flexible-identifiers-and-attributes).

#### Password resets

End users must provide their username, phone number, or whichever attribute their administrator configured as the primary attribute when resetting their password. Auth0 uses that primary identifier to locate and reset the account associated with a shared email address.

#### Irreversible settings

Once the email attribute is set to non-unique on a connection, it cannot be changed back to unique. In addition, only new database connections can be created with non-unique email support; you cannot change an existing connection, and you must update your app to use the primary identifier you choose.

#### Flexible identifiers

Flexible Identifiers must be enabled on the database connection to use Non-Unique Emails and they cannot be disabled after the connection is created. When you enable Non-Unique Emails with the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>, Flexible Identifiers are configured for you automatically.

### API behavior changes

`GET /api/v2/users-by-email` returns all users that share the same email address.

`DELETE /api/v2/connections/{id}/users` is not compatible with non-unique email connections.

`POST /dbconnections/change_password` does not work with Non-Unique Email connections because it requires a unique email address to find the user account. Users must use flows that leverage the primary identifier to reset their passwords.

### Enable Non-Unique Emails in the Auth0 Dashboard

1. Go to **Authentication > Database** andcreate a new connection.
2. Navigate to the **Choose one or more attributes as user identifiers** section and toggle Email Address to **On,** then enable the **Allow non-unique email addresses** toggle that appears.
3. Pick either username or phone number to toggle **On** as well to serve as a primary identifier for login and password reset flows.
4. After confirming that email will not be used as an identifier, choose **Create** to save the Connection.

<Frame>
  <img alt="" />
</Frame>

### Enable Non-Unique Emails via the Management API

Use the `POST /api/v2/connections` endpoint in the Management API to create a database connection that supports Non-Unique Emails.

When creating the connection:

* Set **unique: false** in the `options.attributes.email` object to allow multiple accounts with the same email address. Set **identifier.active: false** to ensure that the email cannot act as the primary identifier when it's not unique.
* Choose another attribute as the primary identifier and set **identifier.active: true** for the attribute you chose.

Without a primary identifier besides email, authentication and password reset flows do not work properly. Ensure at least one attribute is set as an active identifier.

#### Example request

Below is an example of a request body to create a database connection that uses a username as the primary identifier and supports non-unique emails:

```json lines expandable theme={null}
{
 "name": "new-non-unique",
 "strategy": "authO",
 "options": {
  "attributes": {
   "email": {
     "unique": false,
     "signup" : {
       "status": "required"
     },
     "identifier": {
      "active": false
     },
     "profile_required": true
   ｝，
   "username": {
    "signup": {
     "status": "required"
   },
   "identifier": {
    "active": true
   ｝，
   "profile_required": true
   }
  }
 }
}
```

### Shared Email Risk Disclaimer

While the **Non-Unique Emails** feature includes safeguards, such as disallowing email as a primary identifier and requiring password resets to be performed using a username or phone number\*\*,\*\* there is still inherent risk when multiple user accounts share the same email address. For example:

* All email communications (e.g., password reset links, notifications) will be delivered to the same inbox, regardless of which user initiated the action.
* This could lead to confusion for users or unintended access to email-based links if the inbox is shared.

By enabling this feature, you acknowledge and accept the responsibility of ensuring that:

* Shared email scenarios are appropriate for your use case.
* End-users are informed and trained accordingly.
* Your application design accounts for potential overlaps in email-based workflows.

This trade-off allows for flexibility but requires thoughtful implementation and clear communication with your users.


# Passkeys
Source: https://auth0.com/docs/authenticate/database-connections/passkeys

Learn about implementing passkeys as an authentication method.

Passkeys are a phishing-resistant alternative to traditional authentication factors (such as identifier/password) that offer an easier and more secure login experience to users. Passkeys are modeled from FIDO® W3C Web Authentication (WebAuthn) and Client to Authenticator Protocol (CTAP) [specifications](https://fidoalliance.org/specs/fido-v2.1-ps-20210615/fido-client-to-authenticator-protocol-v2.1-ps-errata-20220621.html#intro).

Passkeys reduce the friction experienced with single-device authentication methods by allowing credentials to sync across devices and map to associated domains. WebAuthn binds credentials like passkeys to a specific domain identified by the [Relying Party ID attribute](https://www.w3.org/TR/webauthn-2/#relying-party-identifier). The <Tooltip href="/docs/glossary?term=Relying+Party">Relying Party ID</Tooltip> is the domain end user who can enroll and challenge with a passkey. For example, if your web application is served at `login.example.com` and your native application is served at `app.example.com`, you can configure the Relying Party ID to `example.com`. End users are able to authenticate to any `example.com` domain with a single passkey.

| Environment | Root Domain                 | RPID          |
| :---------- | :-------------------------- | :------------ |
| Web         | `https://login.example.com` | `example.com` |
| iOS         | `app.example.com`           | `example.com` |
| Android     | `assetlinks.json`           | `example.com` |

<Warning>
  Relying Party ID for Passkeys is in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal).
</Warning>

With Auth0, you can customize the RPID to the root or parent domain so users can authenticate on mobile applications or web applications using the same passkey. To learn how to customize RPID, read [Configure Passkey Policy](docs/authenticate/database-connections/passkeys/configure-passkey-policy).

To learn more about passkeys, review the FIDO® Alliance [Passkey FAQs](https://fidoalliance.org/passkeys/#faq).

Auth0 supports passkeys as an authentication method for [database connections](/docs/authenticate/database-connections) and offers three methods of implementation:

* Universal Login passkeys for web-based applications
* [Embedded Login native applications](/docs/authenticate/passwordless/implement-login/embedded-login/native)
* [Native passkeys for Android and iOS applications](/docs/authenticate/database-connections/passkeys/native-passkeys-for-mobile-applications)

## User experience flows

Similar to traditional authentication factors, passkeys can support several user experience flows such as signup, login, and account recovery.

<Callout icon="file-lines">
  Auth0 Universal Login currently supports the signup and login user experience flows for passkeys.
</Callout>

### Signup flow

The signup flow requires the user to provide an email address, and then create a passkey on either their current device or another device through cross-device authentication.

1. Prompts the user to enter their email address.

   <Frame>
     <img alt="" />
   </Frame>
2. User enters their email address.

   <Frame>
     <img alt="" />
   </Frame>
3. Prompts the user to create a passkey.

   <Frame>
     <img alt="" />
   </Frame>
4. If the user selects **Create a passkey**, it triggers the browser (or operating system) flow to create a passkey.

   <Frame>
     <img alt="" />
   </Frame>

   * If the user selects **Continue**, it prompts them to authenticate with their device’s credentials.

     <Frame>
       <img alt="" />
     </Frame>
   * If the user selects **Try another way**, it prompts them to create a passkey on another device.

     <Frame>
       <img alt="" />
     </Frame>

### Login flow

The login flow detects if the user has a passkey registered to the current device and then automatically selects it using autofill. If the user has multiple passkeys registered to the device, they can manually select one with a button.

1. Prompts the user for an email address or a passkey.

   <Frame>
     <img alt="" />
   </Frame>
2. User can use autofill or select **Continue with a passkey**.

   <Frame>
     <img alt="" />
   </Frame>

   <Frame>
     <img alt="" />
   </Frame>
3. Prompts the user to authenticate with the device’s credentials.

   <Frame>
     <img alt="" />
   </Frame>

## Account reset

If the user needs to reset their account, they can [trigger an interactive password reset flow](/docs/authenticate/database-connections/password-change#universal-login-page) through <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>.

Passkeys are implemented on the Database (Identifier/Password) connection to guarantee another factor for recovery purposes and to facilitate migration of users from passwords to passkeys.

## Passkeys with MFA enabled

If <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> is enabled, the user may be prompted to complete an MFA challenge after authenticating with a passkey based on settings and risk assessment.

The default behavior is to require the completion of an MFA challenge regardless if the authentication method used was a password or a passkey. Given the high level of security passkeys provide, you may skip MFA for users that have authenticated with a passkey in order to reduce friction. This can be achieved by using a post-login Action.

To learn more, read [Reduce friction with passkeys](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger#reduce-friction-with-passkeys) and [Multi-Factor Authentication](/docs/secure/multi-factor-authentication).

<Callout icon="file-lines">
  FIDO® is a trademark (registered in numerous countries) of [FIDO Alliance, Inc](https://fidoalliance.org/).
</Callout>

## Passkeys with Multiple Custom Domains (MCD)

<Warning>
  Multiple Custom Domains is currently available in Early Access. To use this feature, you must have an Enterprise plan. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal). To learn more about Auth0's product release cycle, read [Product Release Stages](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

If you have Multiple Custom Domains enabled on your tenant, Auth0 maintains a one-to-one relationship between a domain and the passkey for that domain. Uers with a passkey-enabled database can sign up and log in with a passkey, tied to the specific domain it was created on. Users can enroll a Passkey for only one domain (the first one they enroll with, among the multiple custom domains on the tenant).

If you are using Relying Party ID for Passkyes, currently in Early Access, you can set `rp.id` for each custom domain.

For passwordless login, the selected custom domain should be reflected in the Magic Link for the passwordless login flow.


# Configure Passkey Policy
Source: https://auth0.com/docs/authenticate/database-connections/passkeys/configure-passkey-policy

Learn how to enable passkeys as an authentication method and configure your passkey policy.

You can enable passkeys as an authentication method and configure your passkey policy in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

## Prerequisites

To enable passkeys as an authentication method for your database connection, you must configure your Auth0 tenant to fulfill the following prerequisites.

If these prerequisites are not met and you try to enable passkeys, the Auth0 Dashboard displays the **Passkey Authentication Prerequisites** readiness checklist and shows any unmet requirements.

<Frame>
  <img alt="" />
</Frame>

After you enable passkeys as an authentication method for a database connection, you can use the readiness checklist to monitor the status of each requirement and access the relevant settings.

To view the **Passkey Authentication Prerequisites** readiness checklist:

1. In the Auth0 Dashboard, go to [Authentication > Database](https://manage.auth0.com/dashboard/#/connections/database).
2. Select a connection.
3. Switch to the **Authentication Methods** view.
4. Select **Configure** on the **Passkeys** card.

### Enable New Universal Login Experience

Enable and configure the [New Universal Login Experience](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience).

#### Disable Custom Login Page setting

The **Customize Login Page** setting allows you to customize login pages when using a [custom domain](/docs/customize/custom-domains).

1. In the Auth0 Dashboard, go to [Branding > Universal Login > Advanced Options > Login](https://manage.auth0.com/#/login_page).
2. Disable the **Custom Login Page** toggle.

### Enable Identifier First authentication

Enable and configure [Identifier First authentication](/docs/authenticate/login/auth0-universal-login/identifier-first).

### Update database connection settings

You must update specific settings for your database connection to use passkeys as an authentication method.

#### Disable Requires Username setting

The **Requires Username** setting requires users to provide both a username and their email when logging in to a database connection.

1. In the Auth0 Dashboard, go to [Authentication > Database](https://manage.auth0.com/#/connections/database).
2. Select a connection.
3. Switch to the **Settings** view.
4. Disable the **Requires Username** toggle.

#### Disable Use my own database setting unless Import Users to Auth0 setting is enabled

The **Use my own database** setting allows you to use an external database to store users on a [custom database](/docs/authenticate/database-connections/custom-db/create-db-connection) connection.

The **Import Users to Auth0** settings allows you to automatically import users from an external database to Auth0. For more information, read [Import and Export Users](/docs/manage-users/user-migration/user-migration-scenarios).

If the **Import Users to Auth0** setting is not enabled on your tenant, you must disable the **Use my own database** setting to configure passkeys:

1. In the Auth0 Dashboard, go to [Authentication > Database](https://manage.auth0.com/#/connections/database).
2. Select a connection.
3. Switch to the **Custom Database** view.
4. Disable the **Use my own database** toggle.

## Best practices

To ensure the best experience for end users when using passkeys, consider the items below.

* **Configure a <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip>:** When a user enrolls a passkey, it associates with the <Tooltip href="/docs/glossary?term=relying+party">relying party</Tooltip> domain. If the domain name changes at any time, all of the passkeys associated with the old domain become invalid. Configure a [custom domain](/docs/customize/custom-domains) for your tenant prior to enabling passkeys to avoid any interruptions for end-users.
* **Enable passkeys for a single database connection**: Enable passkeys for a maximum of one database connection.
* **Consider limitations for Organization users:** Users cannot use passkeys when creating an account through an [Organization invitation email](/docs/manage-users/organizations/configure-organizations/invite-members). To allow these users to create passkeys, use an alternate method of user creation or ensure [progressive enrollment](#progressive-enrollment) is enabled.

## Enable passkeys as an authentication method

You can enable passkeys as an authentication method for your database connection in the Auth0 Dashboard:

1. Go to [Authentication > Database](https://manage.auth0.com/#/connections/database).
2. Select a connection.
3. Switch to the **Authentication Methods** view.
4. Enable the toggle on the **Passkey** card.

<Callout icon="file-lines">
  Currently, if you enable passkeys for a connection, you must also configure passwords as a backup authentication method. This ensures users can continue to access their accounts from browsers and older devices that may not yet support passkeys.
</Callout>

## Configure your policy

You can configure the passkey policy for your database connection in the Auth0 Dashboard:

1. Go to [Authentication > Database](https://manage.auth0.com/#/connections/database).
2. Select a connection.
3. Switch to the **Authentication Methods** view.
4. Select **Configure** on the **Passkey** card.

<Callout icon="file-lines">
  As passkeys already offer a more secure experience, users leveraging passkeys can choose to skip secondary verification challenges, such as CAPTCHA. Users authenticating with passwords or other traditional methods must continue to complete secondary verification when prompted.
</Callout>

## Configure Relying Party ID (RPID)

<Warning>
  Relying Party ID for Passkeys is in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal).
</Warning>

For end users to enroll and challenge with a single passkey across application types or across the same application type with different subdomains, you need to set the Relying Party ID (RPID) to the parent or root domain. Your native or mobile application served at `app.example.com` and your web application served at `login.example.com` have a root domain of `example.com`. If you set your RPID to `example.com`, your end users can authenticate against both applications with the same passkey tied to the `example.com` domain.

<Callout icon="file-lines">
  When you customize the RPID in the Auth0 Dashboard or Management API, all passkeys for other domains will be unusable, and your end users must re-enroll.
</Callout>

1. Navigate to **[Auth0 Dashboard > Tenant Settings](https://manage.auth0.com/#/tenant/relying_party_ids)**.
2. Select the **Relying Party IDs** tab.
3. Choose **Edit Relying Party ID**.
4. Enter the domain.
5. If this RPID is the root domain, select the checkbox to set the domain as the default for your tenant.
6. Select **Save**.

### Passkey Challenge

This setting determines how users can trigger passkey authentication during login and signup.

<table>
  <thead>
    <tr>
      <th><strong>Passkey authentication UI</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Autofill</td>
      <td>Users must log in with their browser’s autofill feature to leverage passkeys. Autofill allows users to select a saved account from a dropdown menu when engaging with the login prompt. With autofill, users do not need to manually enter their credentials.</td>
    </tr>

    <tr>
      <td>Passkey button</td>
      <td>Users must select the <strong>Continue with a passkey</strong> button on the login prompt.</td>
    </tr>

    <tr>
      <td>Both</td>
      <td>Users can trigger passkey authentication using autofill or by selecting the <strong>Continue with a passkey</strong> button on the login prompt.</td>
    </tr>
  </tbody>
</table>

<Callout icon="file-lines">
  Users can only use autofill if the functionality has been enabled in their browser settings. If autofill is not available, users can log in using the **Passkey** button or their traditional credentials.
</Callout>

<Frame>
  <img alt="" />
</Frame>

### Progressive Enrollment

Enabled by default, progressive enrollment prompts users to create a passkey (if they have not done so already) after logging in with their email and password. This step is not required and users can choose to delay this action every 30 days.

Progressive enrollment is useful when migrating users to a new passkey flow as it offers a more seamless transition between authentication methods.

When a user creates their passkey, it is added to their account as an authentication method. Their standard email or username and password remain valid and can be used to log in as needed. Passkeys do not replace or invalidate users’ standard credentials.

### Local Enrollment

Enabled by default, local enrollment prompts existing users to create a local passkey when using a cross-device passkey to log in to a new device.

For example, existing passkey users can use a QR code to log in to a new device that is within physical proximity of a previously-enrolled device. If local enrollment is enabled in this scenario, the user is prompted to create a local passkey on the new device after they log in with the QR code. If desired, users can choose to skip this action.


# Monitor Passkey Events in Tenant Logs
Source: https://auth0.com/docs/authenticate/database-connections/passkeys/monitor-passkey-events-in-tenant-logs

Learn how to identify and monitor passkey events in your tenant logs.

You can monitor passkey flows associated with your database connections through [tenant logs](/docs/deploy-monitor/logs).

You can view log events in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> ([Monitoring > Logs](https://manage.auth0.com/#/logs)) or retrieve logs using the [Management API](https://auth0.com/docs/api/management/v2/logs/get-logs).

<table>
  <thead>
    <tr>
      <th><strong>Event code</strong></th>
      <th><strong>Scenario</strong></th>
      <th><strong>Notes</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>ss</code></td>
      <td>During signup, a user registered a passkey as their primary authentication method.</td>
      <td>This log event contains the <code>details.authentication\_methods</code> array field with the entry value <code>passkey</code>.<br /><br />If a user registered with a password, this array field contains the entry value <code>pwd</code>.</td>
    </tr>

    <tr>
      <td><code>s</code></td>
      <td>During login, a user authenticated with a passkey.</td>
      <td>This log event contains the <code>details.prompts</code> array which lists the set of prompts a user navigated through during login.<br /><br />If a user authenticated using a passkey, the array contains an element with the following field: <code>"performed\_amr": \["phr"]</code>.</td>
    </tr>

    <tr>
      <td><code>gd\_enrollment\_complete</code></td>
      <td>A progressive or local enrollment flow was successfully completed.</td>
      <td>This log event contains the <code>details.authenticator.type</code> field with the value <code>passkey</code> if a user enrolled a passkey.</td>
    </tr>

    <tr>
      <td><code>gd\_webauthn\_enrollment\_failed</code></td>
      <td>An error occurred during a progressive or local enrollment flow.</td>
      <td>This log event contains the <code>details.authentication\_methods array</code> field with the entry value <code>passkey</code> if a user tried to enroll a passkey.</td>
    </tr>
  </tbody>
</table>


# Native Passkeys API
Source: https://auth0.com/docs/authenticate/database-connections/passkeys/native-passkeys-api

Auth0 Authentication API specs for Native Passkeys

<Callout icon="file-lines">
  Native passkeys is currently available in Early Access. To learn more about Auth0 releases, review [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Callout>

Passkeys are a phishing-resistant alternative to traditional forms of authentication (such as username and password) that offer an easier and more secure user experience. For complete implementation details, review [Native Passkeys for Mobile Applications](/docs/authenticate/database-connections/passkeys/native-passkeys-for-mobile-applications).

Native passkeys use a combination of Auth0 and native iOS or Android APIs to embed challenge flows directly into your mobile application. The endpoints listed below are a subset of the Auth0 Authentication API and are currently available in limited Early Access. To learn more about using this API, review the [Authentication API Introduction](https://auth0.com/docs/api/authentication#introduction).

Passkeys have three related flows:

* **Signup**: Creates a new user account with a passkey as the primary authentication method.
* **Enrollment**: Adds a passkey as an authentication method to an existing user's account.
* **Login**: Challenges an existing user to authenticate using a passkey associated with their account.

## Signup Flow

### Request Signup Challenge

`POST /passkey/register`

Initiates the passkey signup flow for a new user.

In response, Auth0 returns [PublicKeyCredentialCreationOptions](https://www.w3.org/TR/webauthn-3/#dictdef-publickeycredentialcreationoptions) and a session ID. Check `timeout` under `authn_params_public_key` in response for session timeout.

The passkey signup flow supports Organizations through the `organization` parameter, following the behavior described in [Login Flows for Organizations](/docs/manage-users/organizations/login-flows-for-organizations). If your application is configured for **Business Users**, you must provide the `organization` parameter and a valid Organization name or identifier value. After the user registers a passkey, Auth0 enrolls them in the provided Organization.

#### Request Parameters

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>client\_id</code></td>
      <td><strong>Required</strong>. The <code>client\_id</code> of your application.</td>
    </tr>

    <tr>
      <td><code>realm</code></td>
      <td><strong>Optional</strong>. The name of the connection to associate with this user.<br /><br />If a connection is not specified, your tenant's default directory is used.</td>
    </tr>

    <tr>
      <td><code>user\_profile</code></td>
      <td><strong>Required</strong>. An object containing identification information for the user. By default, this includes a valid <code>email</code> and an optional display <code>name</code>.<br /><br />If you have enabled <a href="/docs/authenticate/database-connections/activate-and-configure-attributes-for-flexible-identifiers">Flexible Identifiers</a> for your database connection, you may use a combination of <code>email</code>, <code>phone\_number</code>, or <code>username</code> as identifiers. These options can be required or optional and must match your Flexible Identifier configuration.<br /><br />If the passed identifier (such as <code>email</code>) already exists in the directory, the user should be prompted to complete the Login flow instead.</td>
    </tr>
  </tbody>
</table>

#### Code Samples

##### Request

```text lines theme={null}
POST /passkey/register
Content-Type: application/json

{
  "client_id": "{YOUR_CLIENT_ID}",
  "realm": "{OPTIONAL_CONNECTION}",
  "user_profile": {
	  "email": "{VALID_EMAIL_ADDRESS}",
	  "name": "{OPTIONAL_USER_DISPLAY_NAME}",
  }
}
```

##### Response

```json lines expandable theme={null}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "authn_params_public_key": {
    "challenge": "{GENERATED_CHALLENGE_FOR_THIS_SESSION}",
    "timeout": {MILLISECONDS},
    "rp": {
      "id": "{THE_CUSTOM_DOMAIN}",
      "name": "{THE_CUSTOM_DOMAIN}"
    },
    "pubKeyCredParams": [
      { "type": "public-key", "alg": -8 },
      { type: 'public-key', alg: -7 },
      { type: 'public-key', alg: -257 }
    ],
    "authenticatorSelection": {
      "residentKey": "required",
      "userVerification": "preferred"
    },
    "user": {
      "id": "{GENERATED_ID}",
      "name": "{USER-ENTERED_IDENTIFIER}",
      "displayName": "{USER-ENTERED_DISPLAY_NAME_OR_IDENTIFIER_IF_MISSING}"
    }
  },
  "auth_session": "{SESSION_ID}"
}
```

#### Remarks

* After the challenge request is complete, your application can continue the user registration process using native [Android](https://developer.android.com/identity/passkeys/create-passkeys) or [iOS](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service) APIs.
* You must then [authenticate the new user](#authenticate-new-user) using information retrieved through the native APIs to complete the flow.

### Authenticate New User

<Callout icon="file-lines">
  Native Passkey registration is not currently supported when SMS/Email OTP verification is required on the same connection during signup.
</Callout>

`POST /oauth/token`

Uses the <Tooltip href="/docs/glossary?term=Token+endpoint">Token endpoint</Tooltip> to authenticate the user with the provided credentials to create their account and return the requested tokens.

The `authn_response` parameter is based on the [Web Authentication API specification](https://www.w3.org/TR/webauthn-3/). In the native passkey flow, the information passed to this endpoint can be retrieved through your mobile application’s native APIs:

* [Android registration documentation](https://developer.android.com/identity/passkeys/create-passkeys)
* [iOS registration documentation](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service)

#### Request Parameters

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td><strong>Required</strong>. Include the value: <code>urn:okta:params:oauth:grant-type:webauthn</code></td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td><strong>Required</strong>. The <code>client\_id</code> of your application</td>
    </tr>

    <tr>
      <td><code>realm</code></td>
      <td><strong>Optional</strong>. The name of the connection to associate with the user. If a connection is not specified, your tenant's default directory is used.</td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td><strong>Optional</strong>. Use <code>openid</code> to get an ID token or <code>openid profile email</code> to include user profile information in the ID token.</td>
    </tr>

    <tr>
      <td><code>audience</code></td>
      <td><strong>Optional</strong>. API identifier of the API for which you want to get an access token.</td>
    </tr>

    <tr>
      <td><code>auth\_session</code></td>
      <td><strong>Required</strong>. Session ID returned during the initial passkey challenge request.</td>
    </tr>

    <tr>
      <td><code>authn\_response</code></td>
      <td><strong>Required</strong>. An object containing the following items:<ul><li><code>id</code></li><li><code>rawId</code></li><li><code>type</code></li><li><code>authenticatorAttachment</code></li><li><code>response</code></li></ul></td>
    </tr>

    <tr>
      <td><code>authn\_response.id</code></td>
      <td><strong>Required</strong>. Base64URL credential ID.</td>
    </tr>

    <tr>
      <td><code>authn\_response.rawId</code></td>
      <td><strong>Required</strong>. Base64URL credential ID.</td>
    </tr>

    <tr>
      <td><code>authn\_response.type</code></td>
      <td><strong>Required</strong>. Include the value: <code>public-key</code></td>
    </tr>

    <tr>
      <td><code>authn\_response.authenticatorAttachment</code></td>
      <td><strong>Required</strong>. Include the values:<ul><li><code>platform</code></li><li><code>cross-platform</code></li></ul></td>
    </tr>

    <tr>
      <td><code>authn\_response.response</code></td>
      <td><strong>Required</strong>. An object containing the following items: <ul><li><code>clientDataJSON</code>: Contains JSON-compatible serialization of client data; inherited from the <a href="https://www.w3.org/TR/webauthn-3/#authenticatorresponse">AuthenticatorResponse</a>.</li><li><code>attestationObject</code>: Contains authenticator data and an attestation statement; inherited from the <a href="https://www.w3.org/TR/webauthn-3/#authenticatorresponse">AuthenticatorResponse</a>.</li></ul></td>
    </tr>
  </tbody>
</table>

#### Code Samples

##### Request

```text lines theme={null}
POST /oauth/token
Content-Type: application/json

{
  "grant_type": "urn:okta:params:oauth:grant-type:webauthn",
  "client_id": "{YOUR_CLIENT_ID}",
  "realm": "{OPTIONAL_CONNECTION}",
  "scope": "{OPTIONAL_REQUESTED_SCOPE}",
  "audience": "{OPTIONAL_REQUESTED_AUDIENCE}"
  "auth_session": "{SESSION_ID_FROM_THE_FIRST_REQUEST}",
  "authn_response": {
    "id": "{BASE64URL_ID}",
    "rawId": "{BASE64URL_RAWID}",
    "type": "public-key",
    "authenticatorAttachment": "platform|cross-platform",
    "response": {
      "clientDataJSON": "{BASE64URL_CLIENT_DATA_JSON}",
      "attestationObject": "{BASE64URL_ATTESTATION_OBJECT}",
      {OTHER_PROPERTIES}
    },
  }
}
```

##### Response

```json lines theme={null}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "{BASE64_TOKEN}",
  "refresh_token": "{BASE64_TOKEN}",
  "id_token": "{BASE64_TOKEN}",
  "token_type": "Bearer",
  "expires_in": {SECONDS}
}
```

## Enrollment Flow

Enrolling a new passkey for a user involves a two-step process using the My Account API. This flow ensures that the passkey enrollment is initiated securely and then verified.

Before initiating the enrollment flow, ensure you have an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> with the `create:me:authentication_methods` scope for the `/me` endpoint.

### Initiate Passkey Enrollment

`POST /me/v1/authentication-methods`

The first step is to initiate the enrollment process. This is done by making a POST request to the `/me/v1/authentication-methods` endpoint.

#### Request Parameters

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>type</code></td>
      <td><strong>Required</strong>. Include the value: <code>public-key</code>.</td>
    </tr>

    <tr>
      <td><code>connection</code></td>
      <td><strong>Optional</strong>. The name of the connection in which to create the passkey.</td>
    </tr>

    <tr>
      <td><code>identity</code></td>
      <td><strong>Optional</strong>. The user's identity. Used with linked accounts.</td>
    </tr>
  </tbody>
</table>

#### Code Samples

##### Request

```json lines theme={null}
{
  "type": "passkey",
  "connection": "CONNECTION_NAME",
  "identity": "IDENTITY_USER_ID"
}
```

##### Response

```json lines theme={null}
{
  "authn_params_public_key": {
    "challenge": "GENERATED_CHALLENGE_FOR_THIS_SESSION",
    "timeout": MILLISECONDS,
    "rp": {
      "id": "CUSTOM_DOMAIN",
      "name": "CUSTOM_DOMAIN"
    },
    "pubKeyCredParams": [
      { type: 'public-key', alg: -8 },
      { type: 'public-key', alg: -7 },
      { type: 'public-key', alg: -257 }
    ],
    "authenticatorSelection": {
      "residentKey": "required",
      "userVerification": "preferred"
    },
    "user": {
      "id": "GENERATED_ID",
      "name": "USER_ENTERED_IDENTIFIER",
      "displayName": "USER_ENTERED_DISPLAY_NAME_OR_IDENTIFIER_IF_MISSING"
    }
  },
  "auth_session": "SESSION_ID"
}
```

#### Remarks

* The `auth_session` property in the response body is the identifier of the current authentication session. This must be passed to the `/verify` endpoint.
* After the challenge request is complete, your application can continue the user enrollment process using native [Android](https://developer.android.com/identity/passkeys/create-passkeys) or [iOS](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service) APIs. This will prompt the user to create a passkey with their authenticator (such as fingerprint scanner, security key, or phone).

### Verify Passkey Enrollment

`POST /me/v1/authentication-methods/passkey|new/verify`

<Callout icon="file-lines">
  The ID in the path is always `passkey|new` for new enrollments.
</Callout>

Once the user has successfully created the passkey with their authenticator, the client application will receive an `AuthenticatorAttestationResponse` from the WebAuthn API. This response needs to be sent back to the Auth0 service to complete and verify the enrollment.

* [Android registration documentation](https://developer.android.com/identity/passkeys/create-passkeys)
* [iOS registration documentation](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service)

#### Request Parameters

<table>
  <thead>
    <tr>
      <th><strong>Parameters</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>auth\_session</code></td>
      <td><strong>Required</strong>. The session identifier received in the response of the first POST request to <code>/me/v1/authentication-methods</code>.</td>
    </tr>

    <tr>
      <td><code>authn\_response</code></td>
      <td><strong>Required</strong>. The <code>authn\_response</code> parameter is based on the Web Authentication API specification. In the native passkey flow, the information passed to this endpoint can be retrieved through your mobile application’s native APIs.</td>
    </tr>

    <tr>
      <td><code>authn\_response.id</code></td>
      <td><strong>Required</strong>. Base64URL credential ID.</td>
    </tr>

    <tr>
      <td><code>authn\_response.rawId</code></td>
      <td><strong>Required</strong>. Base64URL credential ID.</td>
    </tr>

    <tr>
      <td><code>authn\_response.type</code></td>
      <td><strong>Required</strong>. Include the value: <code>public-key</code>.</td>
    </tr>

    <tr>
      <td><code>authn\_response.authenticatorAttachment</code></td>
      <td><strong>Required</strong>. Include the values: <code>platform</code>, <code>cross-platform</code>.</td>
    </tr>

    <tr>
      <td><code>authn\_response.response</code></td>
      <td><strong>Required</strong>. An object containing the following items: <ul><li><code>clientDataJson</code>: Contains JSON-compatible serialization of client data; inherited from the <code>AuthenticatorResponse</code>.</li><li><code>attestationObject</code>: Contains authenticator data and an attestation statement; inherited from the <code>AuthenticatorResponse</code>.</li></ul></td>
    </tr>
  </tbody>
</table>

#### Code Samples

##### Request

```json lines theme={null}
{
  "auth_session": "SESSION_ID",
  "authn_response": {
    "id": "BASE64URL_ID",
    "rawId": "BASE64URL_RAWID",
    "type": "public-key",
    "authenticatorAttachment": "platform|cross-platform",
    "response": {
      "clientDataJSON": "BASE64URL_CLIENT_DATA_JSON",
      "attestationObject": "BASE64URL_ATTESTATION_OBJECT"
    }
  }
}
```

#### Remarks

Once this step is completed successfully, the passkey is enrolled for the user and can be used for future authentications.

## Login Flow

### Request Login Challenge

`POST /passkey/challenge`

Initiates the passkey login flow for an existing user who saved a passkey to their account during their initial signup.

In response, Auth0 returns [PublicKeyCredentialRequestOptions](https://www.w3.org/TR/webauthn-3/#dictdef-publickeycredentialrequestoptions), a session ID, and a Relying Party identifier `rpId`. Check `timeout` under `authn_params_public_key` in response for session timeout. The `rpId` returned in the response is the identifier the native device (iOS/Android) uses to look up saved credentials bound to a domain. For a passkey created on a web application (e.g., `example.com`) to be available in the native flow, the `rpId` returned must match the web's `rpId`. To learn how to customize the RPID for your tenant, read [Configure Passkey Policy](/docs/authenticate/database-connections/passkeys/configure-passkey-policy#configure-relying-party-id-rpid).

The passkey login flow supports Organizations through the `organization` parameter, following the behavior described in [Login Flows for Organizations](/docs/manage-users/organizations/login-flows-for-organizations). If your application is configured for **Business Users**, you must provide the `organization` parameter and a valid Organization name or identifier value.

All issued tokens are in the context of the provided Organization. If you enabled [Auto-Membership](/docs/manage-users/organizations/login-flows-for-organizations#auto-membership) for your Organization, the user is automatically enrolled in the Organization after successfully authenticating.

#### Request Parameters

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>client\_id</code></td>
      <td><strong>Required</strong>. The <code>client\_id</code> of your application.</td>
    </tr>

    <tr>
      <td><code>realm</code></td>
      <td><strong>Optional</strong>. The name of the connection to associate with the user.<br /><br />If a connection is not specified, your tenant's default directory is used.</td>
    </tr>
  </tbody>
</table>

#### Code Samples

##### Request

```text lines theme={null}
POST /passkey/challenge
Content-Type: application/json

{
  "client_id": "{YOUR_CLIENT_ID}",
  "realm": "{OPTIONAL_CONNECTION}"
}
```

##### Response

```json lines theme={null}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "authn_params_public_key": {
    "challenge": "{GENERATED_CHALLENGE_FOR_THIS_SESSION}",
    "timeout": {AUTH_TIMEOUT_IN_MILLISECONDS},
    "rpId": "{CUSTOM_DOMAIN}",
    "userVerification": "preferred"
  },
  "auth_session": "{SESSION_ID}"
}
```

#### Remarks

* After the challenge request is complete, your application can continue the login process using native [Android](https://developer.android.com/identity/passkeys/sign-in-with-passkeys) or [iOS](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Connect-to-a-service-with-an-existing-account) APIs.
* You must then [authenticate the existing user](#authenticate-existing-user) using information retrieved through the native APIs to complete the flow.

### Authenticate Existing User

`POST /oauth/token`

Uses the Token endpoint to authenticate the user with the provided credentials and return the requested tokens.

The `authn_response` parameter is based on the [Web Authentication API specification](https://www.w3.org/TR/webauthn-3/). In the native passkey flow, the information passed to this endpoint can be retrieved through your mobile application’s native APIs:

* [Android login documentation](https://developer.android.com/identity/passkeys/sign-in-with-passkeys)
* [iOS login documentation](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Connect-to-a-service-with-an-existing-account)

#### Request Parameters

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td><strong>Required</strong>. Include the value: <code>urn:okta:params:oauth:grant-type:webauthn</code></td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td><strong>Required</strong>. The <code>client\_id</code> of your application</td>
    </tr>

    <tr>
      <td><code>realm</code></td>
      <td><strong>Optional</strong>. The name of the connection to associate with the user. If a connection is not specified, your tenant's default directory is used.</td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td><strong>Optional</strong>. Use <code>openid</code> to get an ID token or <code>openid profile email</code> to include user profile information in the ID token.</td>
    </tr>

    <tr>
      <td><code>audience</code></td>
      <td><strong>Optional</strong>. API identifier of the API for which you want to get an access token.</td>
    </tr>

    <tr>
      <td><code>auth\_session</code></td>
      <td><strong>Required</strong>. Session ID returned during the initial passkey challenge request.</td>
    </tr>

    <tr>
      <td><code>authn\_response</code></td>
      <td><strong>Required</strong>. An object containing the following items:<ul><li><code>id</code></li><li><code>rawId</code></li><li><code>type</code></li><li><code>authenticatorAttachment</code></li><li><code>response</code></li><li><code>clientExtensionResults</code></li></ul></td>
    </tr>

    <tr>
      <td><code>authn\_response.id</code></td>
      <td><strong>Required</strong>. Base64URL credential ID.</td>
    </tr>

    <tr>
      <td><code>authn\_response.rawId</code></td>
      <td><strong>Required</strong>. Base64URL credential ID.</td>
    </tr>

    <tr>
      <td><code>authn\_response.type</code></td>
      <td><strong>Required</strong>. Include the value: <code>public-key</code></td>
    </tr>

    <tr>
      <td><code>authn\_response.authenticatorAttachment</code></td>
      <td><strong>Optional</strong>. Include the values:<ul><li><code>platform</code></li><li><code>cross-platform</code></li></ul></td>
    </tr>

    <tr>
      <td><code>authn\_response.response</code></td>
      <td><strong>Required</strong>. An object containing the following items: <ul><li><code>authenticatorData</code>: Contains <a href="https://www.w3.org/TR/webauthn-3/#authenticator-data">authenticator data</a> returned by the authenticator.</li><li><code>clientDataJSON</code>: Contains JSON-compatible serialization of client data; inherited from the <a href="https://www.w3.org/TR/webauthn-3/#authenticatorresponse">AuthenticatorResponse</a>.</li><li><code>signature</code>: Base64URL signature returned from the authenticator.</li><li><code>userHandle</code>: Base64URL identifier for the user account, returned as <code>user.id</code> in registration step.</li></ul></td>
    </tr>

    <tr>
      <td><code>authn\_response.clientExtensionResults</code></td>
      <td><strong>Optional</strong>. Contains results of processing client extensions requested by the relying party.</td>
    </tr>
  </tbody>
</table>

#### Code Samples

##### Request

```text lines theme={null}
POST /oauth/token
Content-Type: application/json

{
  "grant_type": "urn:okta:params:oauth:grant-type:webauthn",
  "client_id": "{YOUR_CLIENT_ID}",
  "realm": "{OPTIONAL_CONNECTION}",
  "scope": "{OPTIONAL_REQUESTED_SCOPE}",
  "audience": "{OPTIONAL_REQUESTED_AUDIENCE}"
  "auth_session": "{SESSION_ID_FROM_THE_FIRST_REQUEST}",
  "authn_response": {
    "id": "{BASE64URL_ID}",
    "rawId": "{BASE64URL_RAWID}",
    "type": "public-key",
    "authenticatorAttachment": "platform|cross-platform",
    "response": {
      "authenticatorData": "{BASE64URL_AUTHENTICATORDATA}",
      "clientDataJSON": "{BASE64URL_CLIENTDATAJSON}",
      "signature": "{BASE64URL_SIGNATURE}",
      "userHandle": "{BASE64URL_USERHANDLE}"
    },
    "clientExtensionResults": {OPTIONAL_OBJECT}
  },
}
```

##### Response

```json lines theme={null}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "{BASE64_TOKEN}",
  "refresh_token": "{BASE64_TOKEN}",
  "id_token": "{BASE64_TOKEN}",
  "token_type": "Bearer",
  "expires_in": {SECONDS}
}
```


# Native Passkeys for Mobile Applications
Source: https://auth0.com/docs/authenticate/database-connections/passkeys/native-passkeys-for-mobile-applications

Learn how to implement native passkey flows for Android and iOS applications

<Warning>
  Native passkeys is currently available in Early Access. By using this feature, you agree to the applicable Free Trial terms in [Okta’s Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0 releases, review [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

Passkeys are a phishing-resistant alternative to traditional forms of authentication (such as username and password) that offer an easier and more secure user experience. They are modeled from FIDO® W3C Web Authentication (WebAuthn) and Client to Authenticator Protocol (CTAP) [specifications](https://fidoalliance.org/specs/fido-v2.1-ps-20210615/fido-client-to-authenticator-protocol-v2.1-ps-errata-20220621.html#intro).

Auth0 currently supports passkeys as an authentication method for database connections and offers two methods of implementation:

* [Universal Login passkeys](/docs/authenticate/database-connections/passkeys) for web-based applications.
* Native passkeys for Android and iOS applications.
* [Embedded Login for web-based and native applications](/docs/authenticate/passwordless/implement-login/embedded-login)

## How it works

Native passkeys use a combination of the [Auth0 Authentication API](/docs/authenticate/database-connections/passkeys/native-passkeys-api) and native iOS or Android APIs to embed challenge flows directly into your mobile application. This allows you to create an integrated signup and login experience for your application that does not rely on redirecting users through their browsers to complete authentication.

The following example demonstrates what a new user may experience during the passkey signup flow:

1. A new user launches your mobile application and accesses the login screen. Since they are a new user, they select the Sign Up button.
2. On the next screen, the user enters their email address and selects Create Account.
3. Next, the user is asked if they want to create a passkey for your application. To proceed, the user selects Continue.
4. To generate a passkey, the user must locally authenticate on their device using biometrics or another authentication method, such as entering a PIN.
5. After local authentication is complete, a new passkey is saved to the user’s device and synced with their passkey provider, such as iCloud or Google.
6. After the passkey is saved, the user continues your new user registration process to finalize their account.

Once this process is complete, the user can authenticate with their saved passkey the next time they log in to your application.

## Before you begin

### Configure a custom domain

Native passkeys require the use of a <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip>. Before proceeding, ensure you have configured a custom domain for your tenant. To learn more, review [Custom Domains](/docs/customize/custom-domains).

### Configure your passkey policy

Before you can implement native passkeys for Android or iOS applications, you must configure a passkey policy in your Auth0 tenant. To prepare your tenant, follow the steps in [Configure Passkey Policy](/docs/authenticate/database-connections/passkeys/configure-passkey-policy).

### Prepare your application

To prepare your application for native passkeys, you must configure your Device Settings and add the `Passkey` grant. You can complete these configurations through your <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

#### Associated domains

For end users to authenticate with a single passkey with across different application types or application types with different subdomains, set the Relying Party ID to the root or parent domain. To learn more, read [Passkeys](/docs/authenticate/database-connections/passkeys).

### Configure Auth0 Dashboard

1. Navigate to [Applications > Applications](https://manage.auth0.com/#/applications) and select the application you wish to update.
2. At the bottom of the Settings tab, select **Advanced Settings**. Then, choose the **Device Settings** tab.
3. Complete the **iOS** and **Android** sections as needed for your application. Then, click **Save Changes**.
4. In the Advanced Settings section, select the **Grant Types** tab.
5. Enable the **Passkey** grant, then select **Save Changes**.

#### Management API

Call the [Update a Client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) endpoint and:

* Update `grant_types` to include `urn:okta:params:oauth:grant-type:webauthn`.
* Use the `mobile` object to specify iOS and Android device settings as needed.

## Implement passkey flows

You can define the following passkey flows for your application:

* [Signup flow](#signup-flow): Allows new users to generate and save a passkey during the user registration process.
* [Login flow](#login-flow): Allows an existing user who has already enrolled in passkeys to authenticate with their saved passkey during the login process.

### Signup flow

A user initiates the passkey signup flow when they first attempt to log in to your application.

If the user provides an identifier that already exists, it’s recommended that you prompt the user to complete the login flow instead. Otherwise, the action will fail.

#### Flow steps

1. A user visits your application and chooses to register a new account. The user provides an identifier requested by your application, such as their email address.
2. Your application then initiates the signup challenge by calling the [Request Signup Challenge](/docs/authenticate/database-connections/passkeys/native-passkeys-api#request-signup-challenge) endpoint of the Auth0 Authentication API:

<Callout icon="file-lines">
  * If you do not specify a `realm`, your tenant’s default directory is used.
  * By default, email is the required identifier. If you have enabled [Flexible Identifiers](/docs/authenticate/database-connections/activate-and-configure-attributes-for-flexible-identifiers) for your database connection, you may use a combination of `email`, `phone_number`, or `username` instead. These options can be required or optional and must match your Flexible Identifier configuration.
</Callout>

```text lines theme={null}
POST /passkey/register
Content-Type: application/json

{
  "client_id": "{YOUR_CLIENT_ID}",
  "realm": "{OPTIONAL_CONNECTION}",
  "user_profile": {
	  "email": "{VALID_EMAIL_ADDRESS}",
	  "name": "{OPTIONAL_USER_DISPLAY_NAME}",
  }
}
```

3. In response, Auth0 returns [`PublicKeyCredentialCreationOptions`](https://www.w3.org/TR/webauthn-3/#dictdef-publickeycredentialcreationoptions) along with an `auth_session` ID and `rpId` as `rp.id`:

   ```text lines expandable theme={null}
   HTTP/1.1 200 OK
   Content-Type: application/json

   {
     "authn_params_public_key": {
       "challenge": "{GENERATED_CHALLENGE_FOR_THIS_SESSION}",
       "timeout": {MILLISECONDS},
       "rp": {
         "id": "{YOUR_CUSTOM_DOMAIN}",
         "name": "{YOUR_CUSTOM_DOMAIN}"
       },
       "pubKeyCredParams": [
         { type: 'public-key', alg: -8 },
         { type: 'public-key', alg: -7 },
         { type: 'public-key', alg: -257 }
       ],
       "authenticatorSelection": {
         "residentKey": "required",
         "userVerification": "preferred"
       },
       "user": {
         "id": "{GENERATED_ID}",
         "name": "{USER-ENTERED_IDENTIFIER}",
         "displayName": "{USER-ENTERED_DISPLAY_NAME_OR_IDENTIFIER_IF_MISSING}"
       }
     },
     "auth_session": "{SESSION_ID}"
    }
   ```

   <Callout icon="file-lines">
     The returned `rpId` in the response matches the domain used in the webflow for passkeys to work in associated domains.
   </Callout>

4. Your application then completes the user registration process using the appropriate native APIs:

   * Review [Android registration documentation](https://developer.android.com/identity/passkeys/create-passkeys).
   * Review [iOS registration documentation](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service).

5. Your application then uses the credential information obtained through the registration process, including `authn_response` details, to call the [Token](/docs/authenticate/database-connections/passkeys/native-passkeys-api#authenticate-new-user) endpoint:

   ```text lines theme={null}
   POST /oauth/token
   Content-Type: application/json

   {
     "grant_type": "urn:okta:params:oauth:grant-type:webauthn",
     "client_id": "{YOUR_CLIENT_ID}",
     "realm": "{OPTIONAL_CONNECTION}",
     "scope": "{OPTIONAL_REQUESTED_SCOPE}",
     "audience": "{OPTIONAL_REQUESTED_AUDIENCE}"
     "auth_session": "{SESSION_ID_FROM_THE_FIRST_REQUEST}",
     "authn_response": {
       "id": "{BASE64URL_ID}",
       "rawId": "{BASE64URL_RAWID}",
       "type": "public-key",
       "authenticatorAttachment": "platform|cross-platform",
       "response": {
         "clientDataJSON": "{BASE64URL_CLIENT_DATA_JSON}",
         "attestationObject": "{BASE64URL_ATTESTATION_OBJECT}",
         {OTHER_PROPERTIES}
       },
     },
   }
   ```

6. Auth0 creates a new user account and returns the requested tokens to complete the flow:

   ```text lines theme={null}
   HTTP/1.1 200 OK
   Content-Type: application/json

   {
     "access_token": "{BASE64_TOKEN}",
     "refresh_token": "{BASE64_TOKEN}",
     "id_token": "{BASE64_TOKEN}",
     "token_type": "Bearer",
     "expires_in": {SECONDS}
   }
   ```

### Login flow

An existing user initiates the passkey login flow when they attempt to log in to your application. This flow only applies to existing users who have saved passkeys to their accounts during initial signup.

#### Flow Steps

1. A user launches your application and begins the login process. Your application then initiates the login challenge by calling the [Request Login Challenge](/docs/authenticate/database-connections/passkeys/native-passkeys-api#request-login-challenge) endpoint of the Authentication API:

   <Callout icon="file-lines">
     If you do not specify a `realm`, your tenant’s default directory is used.
   </Callout>

   ```text lines theme={null}
   POST /passkey/challenge
   Content-Type: application/json

   {
     "client_id": "{YOUR_CLIENT_ID}",
     "realm": "{OPTIONAL_CONNECTION}"
   }
   ```

2. In response, Auth0 returns [`PublicKeyCredentialRequestOptions`](https://www.w3.org/TR/webauthn-3/#dictdef-publickeycredentialrequestoptions) along with an `auth_session` to continue the flow in your application:

   ```text lines theme={null}
   HTTP/1.1 200 OK
   Content-Type: application/json

   {
     "authn_params_public_key": {
       "challenge": "{GENERATED_CHALLENGE_FOR_THIS_SESSION}",
       "timeout": {AUTH_TIMEOUT_IN_MILLISECONDS},
       "rpId": "{CUSTOM_DOMAIN}",
       "userVerification": "preferred"
     },
     "auth_session": "{SESSION_ID}"
   }
   ```

3. Your application then completes the login process using the appropriate native APIs:

   * Review [Android login documentation](https://developer.android.com/identity/passkeys/sign-in-with-passkeys)
   * Review [iOS login documentation](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Connect-to-a-service-with-an-existing-account).

4. Your application then uses the credential information obtained through the login process, including `authn_response` details, to call the [Token](/docs/authenticate/database-connections/passkeys/native-passkeys-api#authenticate-existing-user) endpoint:

   ```text lines theme={null}
   POST /oauth/token
   Content-Type: application/json

   {
     "grant_type": "urn:okta:params:oauth:grant-type:webauthn",
     "client_id": "{YOUR_CLIENT_ID}",
     "realm": "{OPTIONAL_CONNECTION}",
     "scope": "{OPTIONAL_REQUESTED_SCOPE}",
     "audience": "{OPTIONAL_REQUESTED_AUDIENCE}"
     "auth_session": "{SESSION_ID_FROM_THE_FIRST_REQUEST}",
     "authn_response": {
       "id": "{BASE64URL_ID}",
       "rawId": "{BASE64URL_RAWID}",
       "type": "public-key",
       "authenticatorAttachment": "platform|cross-platform",
       "response": {
         "authenticatorData": "{BASE64URL_AUTHENTICATORDATA}",
         "clientDataJSON": "{BASE64URL_CLIENTDATAJSON}",
         "signature": "{BASE64URL_SIGNATURE}",
         "userHandle": "{BASE64URL_USERHANDLE}"
       },
       "clientExtensionResults": {OPTIONAL_OBJECT}
      }
   }
   ```

5. Auth0 authenticates the credentials and returns the requested tokens to complete the flow:

   ```text lines theme={null}
   HTTP/1.1 200 OK
   Content-Type: application/json

   {
     "access_token": "{BASE64_TOKEN}",
     "refresh_token": "{BASE64_TOKEN}",
     "id_token": "{BASE64_TOKEN}",
     "token_type": "Bearer",
     "expires_in": {SECONDS}
   }
   ```

## References

The following resources can be referenced when implementing native passkeys for your mobile application:

* Auth0 Authentication API

  * [Request signup challenge](/docs/authenticate/database-connections/passkeys/native-passkeys-api#request-signup-challenge)
  * [Authenticate new user](/docs/authenticate/database-connections/passkeys/native-passkeys-api#authenticate-new-user)
  * [Request login challenge](/docs/authenticate/database-connections/passkeys/native-passkeys-api#request-login-challenge)
  * [Authenticate existing user](/docs/authenticate/database-connections/passkeys/native-passkeys-api#authenticate-existing-user)
* Android resources

  * [Registration documentation](https://developer.android.com/identity/passkeys/create-passkeys)
  * [Login documentation](https://developer.android.com/identity/passkeys/sign-in-with-passkeys)
* iOS resources

  * [Registration documentation](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service)
  * [Login documentation](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Connect-to-a-service-with-an-existing-account)


# Change Users' Passwords
Source: https://auth0.com/docs/authenticate/database-connections/password-change

Describes the different ways to reset users' passwords for your Auth0 applications.

<Card title="Overview">
  Key Concepts

  * Trigger a password reset using Auth0 Dashboard or the Management API.
</Card>

This topic describes different ways to reset the password for a user in your database. You can change passwords for users in your [database connections](/docs/authenticate/database-connections) only. Users signing in with [social](/docs/authenticate/identity-providers/social-identity-providers) or [enterprise](/docs/authenticate/identity-providers/enterprise-identity-providers) connections must reset their passwords with the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> (such as Google or Facebook), and the following instructions work only if the user's email address is known.

There are two basic methods for changing a user's password:

* [Trigger an interactive password reset flow](#trigger-an-interactive-password-reset-flow) that sends the user a link through email. The link opens the Auth0 password reset page where the user can enter a new password.
* [Directly set the new password](#directly-set-the-new-password) using the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> or the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

<Callout icon="file-lines">
  Resetting a user's password makes their session expire.
</Callout>

<Card title="Not what you're looking for?">
  * To configure the custom Password Reset page, read [Customize Password Reset Page](/docs/customize/login-pages/classic-login/customize-password-reset-page).
  * To implement custom behavior after a successful password change, read [Actions Triggers: post-change-password](/docs/customize/actions/explore-triggers/password-reset-triggers/post-change-password-trigger).
  * To reset the password to your personal Auth0 user account, read [Reset Account Passwords](/docs/troubleshoot/customer-support/reset-account-passwords).
</Card>

## Trigger an interactive password reset flow

There are two ways to trigger an interactive password reset flow, depending on your use case: through the <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> page or the Authentication API.

### Universal Login page

If your application uses Universal Login, the user can use the Lock widget on the Login screen to trigger a password reset email. With Universal Login, the user can click the **Don't remember your password?** link and then enter their email address. This fires off a POST request to Auth0 that triggers the password reset process. The user [receives a password reset email](#password-reset-email).

### Authentication API

If your application uses an interactive password reset flow through the Authentication API, make a `POST` call. In the `email` field, provide the email address of the user who needs to change their password. If the call is successful, the user [receives a password reset email](#password-reset-email).

If you call the API from the browser, be sure the origin URL is allowed:

Go to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications/\{yourClientId}/settings), and add the URL to the **Allowed Origins (CORS)** list.

If your connection is a custom database, check to see if the user exists in the database before you invoke the Authentication API for `changePassword`.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/dbconnections/change_password' \
    --header 'content-type: application/json' \
    --data '{"client_id": "{yourClientId}","email": "","connection": "Username-Password-Authentication"}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/dbconnections/change_password");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"client_id": "{yourClientId}","email": "","connection": "Username-Password-Authentication"}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/dbconnections/change_password"

  	payload := strings.NewReader("{"client_id": "{yourClientId}","email": "","connection": "Username-Password-Authentication"}")

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

  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/dbconnections/change_password")
    .header("content-type", "application/json")
    .body("{"client_id": "{yourClientId}","email": "","connection": "Username-Password-Authentication"}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/dbconnections/change_password',
    headers: {'content-type': 'application/json'},
    data: {
      client_id: '{yourClientId}',
      email: '',
      connection: 'Username-Password-Authentication'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"client_id": @"{yourClientId}",
                                @"email": @"",
                                @"connection": @"Username-Password-Authentication" };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/dbconnections/change_password"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/dbconnections/change_password",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{"client_id": "{yourClientId}","email": "","connection": "Username-Password-Authentication"}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"client_id": "{yourClientId}","email": "","connection": "Username-Password-Authentication"}"

  headers = { 'content-type': "application/json" }

  conn.request("POST", "/{yourDomain}/dbconnections/change_password", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/dbconnections/change_password")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request.body = "{"client_id": "{yourClientId}","email": "","connection": "Username-Password-Authentication"}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/json"]
  let parameters = [
    "client_id": "{yourClientId}",
    "email": "",
    "connection": "Username-Password-Authentication"
  ] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/dbconnections/change_password")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

### Password reset email

Regardless of how the password reset process was triggered, the user receives email containing a link to reset their password.

<Frame>
  <img alt="Password Reset Email" />
</Frame>

Clicking the link sends the user to the [password reset page](/docs/customize/login-pages/classic-login/customize-password-reset-page).

After submitting the new password, the user sees confirmation that they can now log in with their new credentials.

Notes on password resets:

* The reset password link in the email is valid for one use only.
* If the user receives multiple password reset emails, only the password link in the most recent email is valid.
* The **URL Lifetime** field determines how long the link is valid. From the Auth0 dashboard, you can [customize the Change Password email](/docs/customize/email/email-templates) and [modify the link's lifetime](https://auth0.com/docs/api/authentication/reference#change-password).
* You can extend the password reset flow to include another factor with Auth0 Actions. To learn more, read [Password Reset Flow](/docs/customize/actions/explore-triggers/password-reset-triggers).

With [Classic Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/classic-experience), you can configure a URL to redirect users to after completing the password reset. The URL receives a success indicator and a message. To learn more, read the "Configuring the Redirect-To URL" section in [Customize Email Templates](/docs/customize/email/email-templates).

[Universal Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience) redirects the user to the [default login route](/docs/authenticate/login/auth0-universal-login/configure-default-login-routes) when it succeeds, and handles the error cases as part of the Universal Login flow. This experience ignores the Redirect URL in the email template.

<Card title="Generate Password Reset tickets">
  The Management API provides the [Create a Password Change Ticket](https://auth0.com/docs/api/management/v2#!/Tickets/post_password_change) endpoint, which generates a URL like the one in the password reset email. You can use the generated URL when the email delivery method is not appropriate. Keep in mind that in the default flow, the email delivery verifies the identity of the user. (An impostor wouldn't have access to the email inbox.) If you use the ticket URL, your application is responsible for verifying the identity of the user in some other way.
</Card>

## Directly set the new password

To directly set a new password for the user without sending a password reset email, use either the [Management API](#use-the-management-api) or the [Auth0 Dashboard](#manually-set-users-passwords-using-the-auth0-dashboard).

<Callout icon="file-lines">
  Users do not receive notification when you change their password.
</Callout>

### Use the Management API

If you want to implement your own password reset flow, you can directly change a user's password from a server request to the Management API: make a `PATCH` call to the [Update a User endpoint](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id).

<Callout icon="file-lines">
  If you use Management API to set or update a user's password via the [Update a User endpoint](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id), the strength policy you set in Auth0 Dashboard applies.
</Callout>

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/users/%7BuserId%7D' \
    --header 'authorization: Bearer {yourMgmtApiAccessToken}' \
    --header 'content-type: application/json' \
    --data '{"password": "newPassword","connection": "connectionName"}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/%7BuserId%7D");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  request.AddParameter("application/json", "{"password": "newPassword","connection": "connectionName"}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/users/%7BuserId%7D"

  	payload := strings.NewReader("{"password": "newPassword","connection": "connectionName"}")

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

  	req.Header.Add("content-type", "application/json")
  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/users/%7BuserId%7D")
    .header("content-type", "application/json")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .body("{"password": "newPassword","connection": "connectionName"}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/users/%7BuserId%7D',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer {yourMgmtApiAccessToken}'
    },
    data: {password: 'newPassword', connection: 'connectionName'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer {yourMgmtApiAccessToken}" };
  NSDictionary *parameters = @{ @"password": @"newPassword",
                                @"connection": @"connectionName" };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/%7BuserId%7D"]
                                                         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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/%7BuserId%7D",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "PATCH",
    CURLOPT_POSTFIELDS => "{"password": "newPassword","connection": "connectionName"}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}",
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"password": "newPassword","connection": "connectionName"}"

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer {yourMgmtApiAccessToken}"
      }

  conn.request("PATCH", "/{yourDomain}/api/v2/users/%7BuserId%7D", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/%7BuserId%7D")

  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 {yourMgmtApiAccessToken}'
  request.body = "{"password": "newPassword","connection": "connectionName"}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer {yourMgmtApiAccessToken}"
  ]
  let parameters = [
    "password": "newPassword",
    "connection": "connectionName"
  ] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/%7BuserId%7D")! 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()
  ```
</AuthCodeGroup>

### Manually set users' passwords using the Auth0 Dashboard

Anyone with administrative privileges to your Auth0 tenant can manually change a user's password at [Auth0 Dashboard > User Management > Users](https://manage.auth0.com/#/users).

1. Select the name of the user whose password you want to change.
2. Locate the **Danger Zone** at the bottom of the page.
3. In the red **Change Password** box, select **Change**.

   <Frame>
     <img alt="Manually set password" />
   </Frame>
4. Enter the new password, and select **Save**.


# Configure Password Policies in Auth0 Database Connections
Source: https://auth0.com/docs/authenticate/database-connections/password-options

Enforce password policies in database connection to disallow repeat passwords, common passwords, personal data in passwords, and insufficiently complex passwords.

## Available password policies

When using the Auth0 data store or a custom database connection, you can enforce the following password policies.

| Policy              | Description                                                                                                                                                                                                                                                                      |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Password history    | Users cannot reuse their most recent passwords. Auth0 retains up to 24 passwords of history while this policy is enabled.                                                                                                                                                        |
| Password dictionary | Users cannot use passwords in the [default dictionary list](https://github.com/danielmiessler/SecLists/blob/master/Passwords/Common-Credentials/10k-most-common.txt) of 10,000 common passwords or any additional passwords you prohibit (based on case-insensitive comparison). |
| Block personal data | Users cannot use passwords containing the values of `name`, `username`, `nickname`, `user_metadata.name`, `user_metadata.first`, `user_metadata.last`, or the first part of the their email (before the `@`).                                                                    |
| Password strength   | Users cannot use passwords that do not meet the chosen complexity requirements. There are 5 levels to choose from matching the [OWASP password recommendations](https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/Authentication_Cheat_Sheet.md).                |

You can configure these options in the Auth0 Dashboard or by using the Management API.

## Enforce password policies with the Auth0 Dashboard

<Callout icon="file-lines">
  Password policies for [social and enterprise connections](/docs/authenticate/identity-providers) are enforced by each provider, not by Auth0's database connection password policies.
</Callout>

To enable or disable password policies from the Auth0 Dashboard:

1. Go to [Auth0 Dashboard > Authentication > Database](https://manage.auth0.com/#/connections/database), and select the name of the connection you want to edit.

2. Select the **Authentication Methods** tab. Then, in the **Password** section, select **Configure** to open the **Password** panel.

3. Select the **Security** section to expand it, and then update the policies you want to change:

   * Check or uncheck the **Password history** box. Use the **Password history size** field to choose the number of previous passwords that users cannot reuse.

   * Check or uncheck the **Password dictionary** box. Use the **Additional dictionary entries** text field to specify additional prohibited passwords, one per line.

   * Check or uncheck the **Block Personal Data** box.

4. Select the **Composition** section to expand it, then use the **Strength** slider to choose a level of complexity:

   * **None**: Requires a non-empty password.
   * **Low**: Requires a character length you specify.
   * **Fair**: All previous, and additionally requires a lower-case letter, an upper-case letter, and a number.
   * **Good**: All previous, and additionally requires a special character (`!@#$%^&*`).
   * **Excellent**: All previous, and additionally requires there to be no more than 2 identical characters in a row.

5. Click **Save**.

## Enforce password policies with the Management API

You can use the Management API to configure password policies when you create or update a database connection. For more information, see the following endpoints:

* [Create a connection endpoint](https://auth0.com/docs/api/management/v2/connections/post-connections)
* [Update a connection endpoint](https://auth0.com/docs/api/management/v2/connections/patch_connections_by_id).

You can view a database connection's current password policies in the `options` object returned from the [Get a connection endpoint](https://auth0.com/docs/api/management/v2/connections/get-connections-by-id).


# Adding Username for Database Connections
Source: https://auth0.com/docs/authenticate/database-connections/require-username

Learn how to add a username field for login to database connections.

For database connections, you can have your users sign in with a username instead of their email address.

## Require username

1. Go to [Auth0 Dashboard > Authentication > Database](https://manage.auth0.com/#/connections/database), and select the name of the connection you want to edit.
2. Locate **Requires Username**, and use the toggle to enable or disable requiring a username.

   <Frame>
     <img alt="Enable or disable require username setting" />
   </Frame>

To see how this will affect the login screen, select the **Try Connection** view. Notice that once **Requires Username** is enabled, new users must enter a username and their email address to sign up.

<Frame>
  <img alt="Login form with username" />
</Frame>

Users can then login with either their username or their email address. Users who registered while **Requires Username** was disabled will not have a Username field stored and will have to log in with their email address.

### Username length

The default allowed length for usernames is between 1 and 15 characters. However, using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or via the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> v2, you can modify the length minimum and maximum (up to a maximum length of 128 characters).

### Allowed characters

The username field accepts the following characters:

* Alphanumeric characters (without accent marks, automatically converted to lowercase);
* The at sign (@) character (but email addresses are not allowed);
* The caret (^) character;
* The dollar sign (\$) character;
* The dot (.) character;
* The exclamation (!) character;
* The grave accent (\`) character;
* The minus (-) character;
* The number sign (#) character;
* The plus (+) character;
* The single quote (') character;
* The tilde (\~) character;
* The underscore (\_) character;

No other characters/symbols are allowed, and Auth0 does not validate or sanitize custom database inputs.


# Identity Providers
Source: https://auth0.com/docs/authenticate/identity-providers

Learn about types of identity providers supported by Auth0.

Introduction to the various sources of users for applications, including <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip>, databases, and <Tooltip href="/docs/glossary?term=passwordless">passwordless</Tooltip> authentication methods.

A connection is the relationship between Auth0 and a source of users, which may include external Identity Providers (such as Google or LinkedIn), databases, or passwordless authentication methods. Auth0 sits between your application and its sources of users, which adds a level of abstraction, so your application is isolated from any changes to and idiosyncrasies of each source's implementation.

By default, Auth0 automatically syncs user profile data with each user login, thereby ensuring that changes made in the connection source are automatically updated in Auth0. You can disable synchronization to allow for updating profile attributes from your application.

You can configure any number of connections for your applications.

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/authenticate/identity-providers/social-identity-providers">Social Identity Providers</a></td>
      <td>About the external social Identity Providers supported by Auth0.</td>
    </tr>

    <tr>
      <td><a href="/docs/authenticate/identity-providers/enterprise-identity-providers">Enterprise Identity Providers</a></td>
      <td>About the external enterprise Identity Providers supported by Auth0.</td>
    </tr>

    <tr>
      <td><a href="/docs/authenticate/identity-providers/legal">Legal Identity Providers</a></td>
      <td>About the external legal Identity Providers supported by Auth0.</td>
    </tr>

    <tr>
      <td><a href="/docs/authenticate/identity-providers/pass-parameters-to-idps">Pass Parameters to Identity Providers</a></td>
      <td>How to pass provider-specific parameters to an Identity Provider during authentication.</td>
    </tr>

    <tr>
      <td><a href="/docs/authenticate/identity-providers/calling-an-external-idp-api">Call an Identity Provider API</a></td>
      <td>How to call an external Identity Provider's API.</td>
    </tr>

    <tr>
      <td><a href="/docs/authenticate/identity-providers/adding-scopes-for-an-external-idp">Add Scopes/Permissions to Call Identity Provider APIs</a></td>
      <td>How to work with scopes when calling an external Identity Provider's API.</td>
    </tr>

    <tr>
      <td><a href="/docs/authenticate/identity-providers/view-connections">View Connections</a></td>
      <td>How to view the configured connections for your application using the Auth0 Dashboard.</td>
    </tr>

    <tr>
      <td><a href="/docs/authenticate/identity-providers/retrieve-connection-options">Retrieve Connection Options</a></td>
      <td>How to retrieve the options object for a connection using Auth0's Management API.</td>
    </tr>

    <tr>
      <td><a href="/docs/authenticate/identity-providers/promote-connections-to-domain-level">Promote Connections to Domain Level</a></td>
      <td>How to allow third-party applications to use a connection when your tenant has Dynamic Client Registration enabled.</td>
    </tr>

    <tr>
      <td><a href="/docs/authenticate/identity-providers/test-connections">Test Partner Connections</a></td>
      <td>How partners can test connections.</td>
    </tr>
  </tbody>
</table>


# Add Scopes/Permissions to Call Identity Provider APIs
Source: https://auth0.com/docs/authenticate/identity-providers/adding-scopes-for-an-external-idp

Describes how to add scopes to your IdP connection.

Once a user is logged in, you can get their user profile and then the associated `accessToken` to call the <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> (IdP) APIs as described in [Call an Identity Provider API](/docs/authenticate/identity-providers/calling-an-external-idp-api).

However, if you are receiving `Access Denied` when calling the IdP API, you probably have not requested the correct permissions for the user during login. You can request the correct permissions in one of two ways.

## Change Identity Provider Settings

To configure the scopes/permissions needed from the user, go to [Auth0 Dashboard > Authentication > Social](https://manage.auth0.com/#/connections/social), and select an IdP. You can select the required permissions listed on the configuration screen.

For example, if you click the **Google / Gmail** connection, you can configure Google-specific permissions:

<Frame>
  <img alt="Permissions for Google" />
</Frame>

## Pass Scopes to Authorize endpoint

You can also pass the scopes/permissions you wish to request as a comma-separated list in the `connection_scope` parameter when calling the [authorize endpoint](https://auth0.com/docs/api/authentication#login). For example, if you want to request the `https://www.googleapis.com/auth/contacts.readonly` and `https://www.googleapis.com/auth/analytics` scopes from Google, you can pass these along with the `connection` parameter to ensure the user logs in with their Google account:

<AuthCodeBlock />

<Callout icon="file-lines">
  Please note that in the example request above, the value of the `connection_scope` parameter is URL encoded. The decoded value that is passed to Google is `https://www.googleapis.com/auth/analytics, https://www.googleapis.com/auth/contacts.readonly`
</Callout>


# Call an Identity Provider API
Source: https://auth0.com/docs/authenticate/identity-providers/calling-an-external-idp-api

Describes how to call an external Identity Provider API.

<Callout icon="file-lines">
  If you have [Token Vault](/docs/secure/tokens/token-vault) enabled for your connection, access and refresh tokens will no longer be stored in the user’s `identities` array. Instead, they will be stored in a secure tokenset within the Token Vault. To enable Token Vault, read [Configure Token Vault](/docs/secure/tokens/token-vault/configure-token-vault).
</Callout>

Once you successfully authenticate a user with an external <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> (IdP), such as Facebook or GitHub, the IdP often includes an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> in the user profile it returns to Auth0.

You can retrieve and use this token to call the IdP's API.

<Callout icon="file-lines">
  This article assumes that you have already configured the connection with the IdP of your choice. If not, go to [Identity Providers Supported by Auth0](/docs/authenticate/identity-providers/social-identity-providers), select the IdP you want, and follow the configuration steps.
</Callout>

The process you will follow differs depending on whether your code runs in the backend or the frontend:

* If your code runs in the backend, then we can assume that your server is trusted to safely store secrets (as you will see, we use a secret in the backend scenario). If that's the case, proceed to the [backend section](#from-the-backend) of this article.
* If your code runs in the frontend (for example, it's a SPA, native desktop, or mobile app), then your app cannot hold credentials securely and has to follow an alternate approach. In this case, proceed to the [frontend section](#from-the-frontend) of this article.

## From the backend

Once you authenticate a user, the IdP often includes an Access Token in the user profile it returns to Auth0.

For security and compliance reasons, Auth0 does not send this token to your app as part of the user profile. To get it, you must access the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> and retrieve the full user's profile:

1. Get an Access Token that allows you to call the [Auth0 Management API](https://auth0.com/docs/api/management/v2).
2. Call the Auth0 Management API's [Get Users by ID endpoint](https://auth0.com/docs/api/management/v2#!/Users/get_users_by_id) using the Access Token obtained in step one. This endpoint returns the full user's profile, which contains the IdP Access Token.
3. Extract the IdP Access Token from the response and use it to call the IdP's API.

### Step 1: Get a Token

You will need an Access Token to call the [Management API](https://auth0.com/docs/api/management/v2).

#### Create a test application for the Management API

If this is the first time you are requesting a [Management APIv2 Token](https://auth0.com/docs/api/management/v2/tokens), you will need to create and configure an application that can be used to call the Management API:

1. Navigate to [Auth0 Dashboard > Applications > APIs](https://manage.auth0.com/#/apis), and select the [Auth0 Management API](https://manage.auth0.com/#/apis/management/authorized-clients).
2. Select the **API Explorer** view, and click **Create & Authorize a Test Application**.

This will create a new application and grant all scopes of the Management API, which means that the tokens generated for this application will be able to access all Management API endpoints.

<Card title="Can't see the button?">
  If you don't see this button, it means that you already have at least one authorized application for the Management API. In this case, you can either update the scopes of the existing application and use that, or create a new one following these steps:

  1. Navigate to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), and select **Create Application**.
  2. Select **Machine to Machine Applications**, and then **Create**.
  3. From the **Select an API** dropdown, select `Auth0 Management API`.
  4. Enable required scopes, and select **Authorize**.
  5. Select the **APIs** view, and enable the toggle for **Auth0 Management API**.
</Card>

<Warning>
  For security reasons, we recommend that you assign only the required scopes to the application you will be using. For this particular case, the scopes you need are: `read:users`, `read:user_idp_tokens`. Required scopes are listed for each endpoint in the [Management API Explorer](https://auth0.com/docs/api/management/v2).
</Warning>

To grant or remove scopes from the [registered Auth0 Management API](https://manage.auth0.com/#/apis/management/authorized-clients), select the [**Machine to Machine Applications** view](https://manage.auth0.com/#/apis/management/authorized-clients):

<Frame>
  <img alt="Edit the scopes granted to the Application" />
</Frame>

#### Get the Management API Token

You are now done with configuration and are ready to get your Management API token:

1. From the [registered Auth0 Management API](https://manage.auth0.com/#/apis/management/authorized-clients), select the [**Test** view](https://manage.auth0.com/#/apis/management/test).
2. Choose your application from the **Application** dropdown to pre-populate the ready-to-use snippets with customized variables.
3. Choose your language of preference for the snippet, and copy and run it.
4. Extract the `access_token` property from the response. This is what you will use to access the Management API.

<Card title="What are the snippets doing?">
  The snippets make a `POST` operation to the [/oauth/token endpoint of the Auth0 Authentication API](https://auth0.com/docs/api/authentication#client-credentials), using the **OAuth 2.0 Client Credentials grant**. This is the grant that machine-to-machine processes use to access an API. To learn more about the flow, read [Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow).
</Card>

#### Token expiration

By default, the token you received expires in 24 hours (86,400 seconds). To change this:

1. Navigate to [Auth0 Dashboard > Applications > APIs](https://manage.auth0.com/#/apis), and select the [Auth0 Management API](https://manage.auth0.com/#/apis/management/authorized-clients).
2. Select the **Settings** view, locate the **Token Expiration (Seconds)** field, enter a new value, and click **Save**. The maximum value you can set is 2,592,000 seconds (30 days), though we recommend that you keep the default value.

The next token you generate will use the updated expiration time.

<Warning>
  These tokens **cannot be revoked**. To minimize risk, we recommend issuing short-lived tokens and granting only the necessary scopes for each application. For a production environment, you can configure a simple CLI that will fetch a new token when the old one expires.
</Warning>

### Step 2: Get the full User Profile

To get a user's profile, call the [Get a User endpoint](https://auth0.com/docs/api/management/v2#!/Users/get_users_by_id) of the Management API using the Access Token you extracted in the previous section:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/users/%7BuserId%7D' \
    --header 'authorization: Bearer {yourAccessToken}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/%7BuserId%7D");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer {yourAccessToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/users/%7BuserId%7D"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer {yourAccessToken}")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/users/%7BuserId%7D")
    .header("authorization", "Bearer {yourAccessToken}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/users/%7BuserId%7D',
    headers: {authorization: 'Bearer {yourAccessToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourAccessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/%7BuserId%7D"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/%7BuserId%7D",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourAccessToken}"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {yourAccessToken}" }

  conn.request("GET", "/{yourDomain}/api/v2/users/%7BuserId%7D", headers=headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/%7BuserId%7D")

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

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer {yourAccessToken}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourAccessToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/%7BuserId%7D")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

Replace these values:

* `{userId}`: ID of the user for whom you want to call the IdP's API.
* `{yourAccessToken}`: Access Token you extracted in the previous section.

<Card title="Where do I find the User ID?">
  - For testing purposes, you can find a user ID at [Auth0 Dashboard > User Management > Users](https://manage.auth0.com/#/users). Locate a user, and copy the value of the **user\_id** field.

  - For your implementation, you can either extract the user ID from the `sub` claim in the [ID Token](/docs/secure/tokens/id-tokens), or call the [/userinfo endpoint](https://auth0.com/docs/api/authentication#get-user-info) of the Authentication API and extract it from the `user_id` response property.
</Card>

### Step 3: Extract the IdP Access Token

You can find the Access Token used to call the IdP's API within the user's `identities` array: `user.identities[0].access_token`.

<Callout icon="file-lines">
  For certain Identity Providers, Auth0 will also store a Refresh Token, which you can use to obtain a new Access Token for the IdP. This works for: BitBucket, Google (OAuth 2.0), OAuth 2.0, SharePoint, and Azure AD. To learn more, read [Identity Provider Access Tokens](/docs/secure/tokens/access-tokens/identity-provider-access-tokens).
</Callout>

In most cases, the user will only have one identity, but if the user has signed in multiple times through different connections and you have used [account linking](/docs/manage-users/user-accounts/user-account-linking/link-user-accounts), there may be more.

In this sample response, we see that our user has only one identity: `google-oauth2`.

```json lines expandable theme={null}
{
  "email": "john.doe@test.com",
  "email_verified": true,
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "picture": "https://myavatar/photo.jpg",
  "gender": "male",
  "locale": "en",
  "updated_at": "2017-03-15T07:14:32.451Z",
  "user_id": "google-oauth2|111199914890750704174",
  "nickname": "john.doe",
  "identities": [
    {
      "provider": "google-oauth2",
      "access_token": "ya29.GlsPBCS6ahokDlgCYnVLnDKNE71HBXPEzNhAPoKJLAGKDSe1De3_xclahNcdZXoU-26hCpa8h6240TV86dtaEQ4ZWoeeZduHDq_yeu9QyQqUr--S9B2CR9YJrLTD",
      "expires_in": 3599,
      "user_id": "111199914890750704174",
      "connection": "google-oauth2",
      "isSocial": true
    }
  ],
  "created_at": "2017-03-15T07:13:41.134Z",
  "last_ip": "127.0.0.1",
  "last_login": "2017-03-15T07:14:32.451Z",
  "logins_count": 99
}
```

You are now ready to call the IdP's API. Please refer to the IdP's documentation for specifics on how to do so.

<Warning>
  Don't expose IdP tokens to your client-side application! If your application is public, see the [frontend section](#from-the-frontend) of this article.
</Warning>

<Callout icon="file-lines">
  To learn more about how to request specific scopes for an Identity Provider Access Token, read [Add scopes/permissions to call Identity Provider's APIs](/docs/authenticate/identity-providers/adding-scopes-for-an-external-idp).
</Callout>

## From the frontend

If you are working with a public application (SPA, native desktop, or mobile app), then this is the place to be.

When working with a frontend app, the process for calling IdP APIs differs from the backend process because frontend apps are public applications that **cannot hold credentials securely**. Because SPA code can be viewed and altered, and native/mobile apps can be decompiled and inspected, they cannot be trusted to hold sensitive information like secret keys or passwords.

Specifically, they cannot securely hold the **<Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip>** for the Machine to Machine Application, which you use to call `/oauth/token` during the first step of the backend process.

Instead, you must build a proxy for your backend and expose it to your application as an API.

### Build a proxy

First, you will build a process in your backend that will implement the steps included in [the backend section](#from-the-backend) of this article, and expose it to your application as an API.

You will call the IdP's API from the same backend process, so the Access Token is never exposed to your public application.

Then, you will call your proxy API from your public application using the [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce).

<Card title="Show me how">
  If you haven't implemented this before, you might find our [Single-page Applications (SPA) with API](/docs/get-started/architecture-scenarios/spa-api) architecture scenario useful. It covers a different scenario, but it explains how to configure Auth0, how to call an API from a SPA, and how to implement API validations. It comes with a sample that uses [Angular 2](https://github.com/auth0-samples/auth0-pnp-exampleco-timesheets/tree/master/timesheets-spa/angular) and [Node.js](https://github.com/auth0-samples/auth0-pnp-exampleco-timesheets/tree/master/timesheets-api/node).

  We also offer a [Mobile Applications with API](/docs/get-started/architecture-scenarios/mobile-api) variation (the sample uses [Android](https://github.com/auth0-samples/auth0-pnp-exampleco-timesheets/tree/master/timesheets-mobile/android) and [Node.js](https://github.com/auth0-samples/auth0-pnp-exampleco-timesheets/tree/master/timesheets-api/node)).
</Card>


# Connect Your App to Active Directory using LDAP
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap

Learn how to connect your app to Active Directory (AD) using Lightweight Directory Access Protocol (LDAP) through an enterprise connection.

Auth0 integrates with Active Directory (AD) using Lightweight Directory Access Protocol (LDAP) through an **Active Directory/LDAP Connector** that you install on your network.

The **AD/LDAP Connector** (1), is a bridge between your **Active Directory/LDAP** (2) and the **Auth0 Service** (3). This bridge is necessary because AD/LDAP is typically restricted to your internal network, and Auth0 is a cloud service running in a completely different context.

<Frame>
  <img alt="Overview Diagram of AD/LDAP Connector" />
</Frame>

For [high availability and load balancing](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-high-availability), you can install multiple instances of the connector. All connections are outbound from the connector to the Auth0 Server, so changes to your firewall are generally unnecessary.

## Prerequisites

Before beginning:

* [Register your Application with Auth0](/docs/get-started/auth0-overview/create-applications).

  * Select an appropriate **Application Type**.
  * Add an **Allowed Callback URL** of `{https://yourApp/callback}`.
  * Make sure your Application's [**Grant Types**](/docs/get-started/applications/update-grant-types) include the appropriate flows.

## Steps

To connect your application to Active Directory/LDAP, you must:

1. [Create an enterprise connection in Auth0](#create-an-enterprise-connection-in-auth0) and download the installer
2. [Install the connector on your network](#install-the-connector-on-your-network)
3. [Enable the enterprise connection for your Auth0 Application](#enable-the-enterprise-connection-for-your-auth0-application)
4. [Test the connection](#test-the-connection)

## Create an enterprise connection in Auth0

1. Navigate to [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise), locate **Active Directory / LDAP**, and select its `+`.

   <Frame>
     <img alt="Dashboard - Connections - Enterprise" />
   </Frame>
2. Enter details for your connection, and select **Create**:

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Connection name</strong></td>
      <td>Logical identifier for your connection; it must be unique for your tenant. Once set, this name can't be changed.</td>
    </tr>

    <tr>
      <td><strong>Display name</strong> (optional)</td>
      <td>Text used to customize the login button for Universal Login. When set, the Universal Login login button reads: "Continue with \{Display name}".</td>
    </tr>

    <tr>
      <td><strong>Logo URL</strong> (optional)</td>
      <td>URL of image used to customize the login button for Universal Login. When set, the Universal Login login button displays the image as a 20px by 20px square.</td>
    </tr>

    <tr>
      <td><strong>IdP Domains</strong> (optional)</td>
      <td>Comma-separated list of valid email domains that will be allowed to log in using this connection. Only needed if using the Lock login widget.</td>
    </tr>

    <tr>
      <td><strong>Disable cache</strong></td>
      <td>When enabled, disables caching.</td>
    </tr>

    <tr>
      <td><strong>Use client SSL certificate authentication</strong></td>
      <td>When enabled, uses client SSL certificate authentication.</td>
    </tr>

    <tr>
      <td><strong>Use Windows Integrated Auth (Kerberos)</strong></td>
      <td>When enabled, you will be asked to enter a range of IP addresses. When users log in through these IP addresses, Kerberos will be used; otherwise, AD/LDAP username/password will be requested. Typically, the IP range entered represent intranet addresses.</td>
    </tr>

    <tr>
      <td><strong>Sync user profile attributes at each login</strong></td>
      <td>When enabled, Auth0 automatically syncs user profile data with each user login, thereby ensuring that changes made in the connection source are automatically updated in Auth0.</td>
    </tr>
  </tbody>
</table>

<Frame>
  <img alt="Enter AD / LDAP Connection Details" />
</Frame>

3\. Download the provided installer and make note of the provided **Provisioning Ticket URL**.

<Callout icon="file-lines">
  We ship different versions of the connector to install on Windows or Linux platforms.
</Callout>

## Install the connector on your network

Set up the [AD/LDAP Connector](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector) by following the instructions for your platform:

* [Install the AD/LDAP Connector on Windows](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/install-configure-ad-ldap-connector)
* [Install the AD/LDAP Connector on Non-Microsoft Platforms](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/install-configure-ad-ldap-connector)

## Enable the enterprise connection for your Auth0 application

To use your new AD connection, you must first [enable the connection](/docs/authenticate/identity-providers/enterprise-identity-providers/enable-enterprise-connections) for your Auth0 Applications.

## Test the connection

Now you're ready to [test your connection](/docs/authenticate/identity-providers/enterprise-identity-providers/test-enterprise-connections).

## Next Steps

* [Integrate with Auth0 using one of our libraries](/docs/libraries)
* [Integrate with Auth0 using our Authentication API](https://auth0.com/docs/api/authentication)
* [Read more about the authentication flow](/docs/get-started/authentication-and-authorization-flow)
* [Pass additional parameters to the Identity Provider](/docs/authenticate/identity-providers/pass-parameters-to-idps)
* [Re-prompt users for permissions](/docs/authenticate/identity-providers/social-identity-providers/reprompt-permissions)


# AD/LDAP Connector
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector

Describes the Active Directory LDAP Connector and how it works.

Auth0 integrates with Active Directory (AD) using Lightweight Directory Access Protocol (LDAP) through an Active Directory/LDAP Connector that you install on your network.

<Warning>
  The AD/LDAP Connector is designed for scenarios where your company controls the AD/LDAP server. The connector should **not** be installed on your customer's servers.

  For B2B scenarios where you want to allow your customer's users to access your applications using their enterprise credentials, connect to your customer's federation service (for example, their own Auth0 service, ADFS, or any SAML identity provider) using one of the available enterprise connections.

  If you install an AD/LDAP connector on your customer's servers and it is connected directly to your Auth0 domain, you will have to handle the passwords of your customer's users directly. **Auth0 strongly recommends against these types of deployments and does not support them.**
</Warning>

The AD/LDAP Connector (1), is a bridge between your Active Directory/LDAP (2) and the Auth0 Service (3). This bridge is necessary because AD/LDAP is typically restricted to your internal network, and Auth0 is a cloud service running in a completely different context.

<Frame>
  <img alt="AD/LDAP Connector - integrate AD/LDAP with Auth0 - diagram" />
</Frame>

When a user authenticates with Auth0, they are redirected to the AD/LDAP Connector which validates the user against your AD service and then sends the results of the validation back to Auth0. The AD/LDAP Connector supports authentication based LDAP, Kerberos, and client certificates.

To learn more, see [Configure AD/LDAP Connector Authentication with Kerberos](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/configure-ad-ldap-connector-with-kerberos) and [Configure AD/LDAP Connector Authenticator with Client Certificates](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/configure-ad-ldap-connector-client-certificates).

## Caches

The AD/LDAP Connector caches user profiles and credentials (Auth0 stores a hash of the user's password) to ensure optimal uptime and performance, and updates the data each time a user logs in. The cache is only used when the connector is down or unreachable. The cached data is always stored unless you disable caching credentials in the Dashboard. Values in the cache are case-sensitive, which means that login attempts will only succeed if users provide the exact username that was cached.

## High-availability and load balancing

For high-availability and load balancing, you can install multiple instances of the connector. All connections are outbound from the connector to the Auth0 Server, so changes to your firewall are generally unnecessary.

Each instance of the high-availability cluster will be always up and running and connected to Auth0. Auth0 will send login transactions and other requests to any of the available connectors. If one of the instances fails because of a network or a hardware issue, Auth0 will redirect the login transactions to the other connector. Having a highly available deployment also allows you to update the connector with zero downtime.

## OpenLDAP directories

The Connector comes by default highly optimized for Active Directory. To configure it any other LDAP directories (such as OpenLDAP) you will have to customize these settings in the `config.json` file:

```json lines theme={null}
"LDAP_USER_BY_NAME": "(cn={0})",
"LDAP_SEARCH_QUERY": "(&(objectClass=person)(cn={0}))",
"LDAP_SEARCH_ALL_QUERY": "(objectClass=person)",
```

In some cases, instead of `cn` it might be better to use `uid`.

### OpenDJ example

With the **OpenDJ Control Panel** you can retrieve the list of attributes for each user. This list can help you decide which attribute will be used as the username when authenticating with Auth0.

<Frame>
  <img alt="AD/LDAP Connector OpenDJ Example diagram" />
</Frame>

In this example John's `cn` is **johndoe** and the `mail` field is set to **[johndoe@contoso.com](mailto:johndoe@contoso.com)**. If your organization wants users to authenticate using their username (`cn`) you can set the `LDAP_USER_BY_NAME` setting to `(cn={0})`, but if users should authenticate using their email address you should set it to `(mail={0})`.

## Learn more

* [AD/LDAP Connector System Requirements](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-requirements)
* [Install and Configure AD/LDAP Connector](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/install-configure-ad-ldap-connector)
* [Configure AD/LDAP Connector Authentication with Client Certificates](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/configure-ad-ldap-connector-client-certificates)
* [Configure AD/LDAP Connector Authentication with Kerberos](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/configure-ad-ldap-connector-with-kerberos)
* [Import and Export AD/LDAP Connector Configurations](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/import-export-ad-ldap-connector-configs)
* [Troubleshoot AD/LDAP Connector](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-ad-ldap-connector)


# AD/LDAP Connector Configuration File Schema
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-config-file-schema

Describes the AD/LDAP Connector Configuration file contents.

The AD/LDAP Connector's main configuration file is `config.json`. You can modify this file to make changes that are not available via the AD/LDAP **Connector Admin Console**. You can also view this file to determine which tenant is using a particular Connector. The file is located in the install directory for the AD/LDAP Connector, which (for Windows) is usually found at `C:\Program Files (x86)\Auth0\AD LDAP Connector`. The following settings are supported in this file:

<table>
  <thead>
    <tr>
      <th>Setting</th>
      <th>Description</th>
      <th>Default</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>AD\_HUB</code></td>
      <td>The Auth0 endpoint to which the connector will connect. This value is maintained by the connector.</td>

      <td />
    </tr>

    <tr>
      <td><code>CA\_CERT</code></td>
      <td>An authority certificate or array of authority certificates to check the remote host against.</td>

      <td />
    </tr>

    <tr>
      <td><code>CLIENT\_CERT\_AUTH</code></td>
      <td>Specifies if <strong>Client Certificate Authentication</strong> is enabled or not. This value is configured in Auth0 and maintained by the connector.</td>

      <td />
    </tr>

    <tr>
      <td><code>CONNECTION</code></td>
      <td>The name of the connection in Auth0 which is linked to this instance of the connector. This value is maintained by the connector.</td>

      <td />
    </tr>

    <tr>
      <td><code>CONNECTIONS\_API\_V2\_KEY</code></td>
      <td>A Management API token used to call the Get a connection endpoint. Set this when you need to troubleshoot the connector. This compares the local certificate to the one configured in Auth0 and detects a possible mismatch.</td>

      <td />
    </tr>

    <tr>
      <td><code>FIREWALL\_RULE\_CREATED</code></td>
      <td>Set to <code>true</code> once the Firewall rule has been created for the Kerberos Server (only when Kerberos is enabled).</td>

      <td />
    </tr>

    <tr>
      <td><code>GROUPS</code></td>
      <td>Include the user's groups when enriching the profile.</td>
      <td><code>true</code></td>
    </tr>

    <tr>
      <td><code>GROUP\_PROPERTY</code></td>
      <td>The attribute of the group object used when adding the groups to a user.</td>
      <td><code>cn</code></td>
    </tr>

    <tr>
      <td><code>GROUPS\_CACHE\_SECONDS</code></td>
      <td>Total time in seconds to cache a user's groups.</td>
      <td>600 seconds.</td>
    </tr>

    <tr>
      <td><code>GROUPS\_TIMEOUT\_SECONDS</code></td>
      <td>The timeout in seconds for searching all groups a user belongs to.</td>
      <td>20 seconds</td>
    </tr>

    <tr>
      <td><code>HTTP\_PROXY</code></td>
      <td>The proxy server URL if one is required to connect from the AD/LDAP Connector to Auth0.</td>

      <td />
    </tr>

    <tr>
      <td><code>KERBEROS\_AUTH</code></td>
      <td>Set if <strong>Kerberos Authentication</strong> is enabled or not. This value is configured in Auth0 and maintained by the connector.</td>

      <td />
    </tr>

    <tr>
      <td><code>LAST\_SENT\_THUMBPRINT</code></td>
      <td>Thumbprint of the last certificate which was sent to Auth0.</td>

      <td />
    </tr>

    <tr>
      <td><code>LDAP\_BASE</code></td>
      <td>Defines the location in the directory where the LDAP search begins. For example: <code>DC=fabrikam,DC=local</code>.</td>

      <td />
    </tr>

    <tr>
      <td><code>LDAP\_BASE\_GROUPS</code></td>
      <td>Defines the location in the directory where the LDAP groups search begins.</td>

      <td />
    </tr>

    <tr>
      <td><code>LDAP\_BIND\_PASSWORD</code></td>
      <td>The password of the LDAP user. This setting is automatically removed after the connector initializes.</td>

      <td />
    </tr>

    <tr>
      <td><code>LDAP\_BIND\_CREDENTIALS</code></td>
      <td>The encrypted password of the LDAP user. This setting is automatically added after the connector initializes.</td>

      <td />
    </tr>

    <tr>
      <td><code>LDAP\_BIND\_USER</code></td>
      <td>The user for binding a connection to LDAP.</td>

      <td />
    </tr>

    <tr>
      <td><code>LDAP\_HEARTBEAT\_SEARCH\_QUERY</code></td>
      <td>The LDAP search query used for heartbeat checks.</td>
      <td><code>(&(objectclass=user)(|(sAMAccountName=foo)(UserPrincipalName=foo)))</code></td>
    </tr>

    <tr>
      <td><code>LDAP\_HEARTBEAT\_SECONDS</code></td>
      <td>Time in seconds to keep the LDAP connection open.</td>

      <td />
    </tr>

    <tr>
      <td><code>LDAP\_SEARCH\_ALL\_QUERY</code></td>
      <td>The LDAP query used to list all users in the LDAP store.</td>
      <td><code>(objectCategory=person)</code></td>
    </tr>

    <tr>
      <td><code>LDAP\_SEARCH\_GROUPS</code></td>
      <td>The LDAP query used to find groups in the LDAP store. For example: <code>(&(objectCategory=group)(member=))</code></td>
      <td><code>(member:1.2.840.113556.1.4.1941:=)</code></td>
    </tr>

    <tr>
      <td><code>LDAP\_SEARCH\_QUERY</code></td>
      <td>The LDAP query used to find users in the LDAP store.</td>
      <td><code>(&(objectCategory=person)(anr=))</code></td>
    </tr>

    <tr>
      <td><code>LDAP\_USER\_BY\_NAME</code></td>
      <td>The LDAP query used to find the user during authentication. This setting lets you specify which attribute is considered the user's username. For example, like the common name: the sAMAccountName, UPN, et cetera. This setting also supports multiple values for an OR search, for example: <code>(|(sAMAccountName=)(userPrincipalName=))</code></td>
      <td><code>(sAMAccountName=)</code></td>
    </tr>

    <tr>
      <td><code>LDAP\_URL</code></td>
      <td>The LDAP connection string. For example: <code>ldap\://fabrikam-dc.fabrikam.local</code>.</td>

      <td />
    </tr>

    <tr>
      <td><code>PORT</code></td>
      <td>The port the server runs on when Kerberos or Client Certificate Authentication is enabled.</td>

      <td />
    </tr>

    <tr>
      <td><code>PROVISIONING\_TICKET</code></td>
      <td>The Auth0 provisioning ticket used to communicate with Auth0.</td>

      <td />
    </tr>

    <tr>
      <td><code>REALM</code></td>
      <td>The Auth0 realm, for example: <code>urn:auth0:fabrikam</code>. This value is maintained by the connector.</td>

      <td />
    </tr>

    <tr>
      <td><code>SERVER\_URL</code></td>
      <td>The default connector URL will be <code>server-name:port</code>, but this setting allows you to overwrite this. For example: <code>connector.mycompany.com</code>.</td>

      <td />
    </tr>

    <tr>
      <td><code>SESSION\_SECRET</code></td>
      <td>The session secret used to encrypt the session cookie.</td>

      <td />
    </tr>

    <tr>
      <td><code>SITE\_NAME</code></td>
      <td>When Client Certificate Authentication is enabled, but not possible the AD Connector will show a fallback login page. This setting allows you to specify the title that will show on top of the page.</td>
      <td>Name of the AD connection.</td>
    </tr>

    <tr>
      <td><code>SSL\_CA\_PATH</code></td>
      <td>Absolute path to the base directory where the CA certificate file(s) are located.</td>

      <td />
    </tr>

    <tr>
      <td><code>SSL\_KEY\_PASSWORD</code></td>
      <td>The password for the SSL certificate.</td>

      <td />
    </tr>

    <tr>
      <td><code>SSL\_PFX</code></td>
      <td>Base64 encoded certificate to use for SSL.</td>

      <td />
    </tr>

    <tr>
      <td><code>TENANT\_SIGNING\_KEY</code></td>
      <td>Your Auth0 tenant used to verify JWTs.</td>

      <td />
    </tr>

    <tr>
      <td><code>WSFED\_ISSUER</code></td>
      <td>The issuer being set in the WS-Federation responses. If a connection is configured with email domains, the first email domain configured in Auth0 will be used as issuer.</td>
      <td><code>urn:auth0</code></td>
    </tr>
  </tbody>
</table>

See [Active Directory: LDAP Syntax Filters](https://social.technet.microsoft.com/wiki/contents/articles/5392.active-directory-ldap-syntax-filters.aspx) for information about LDAP queries.


# AD/LDAP Connector System Requirements
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-requirements

Lists all the prerequisites to installing and configuring the connector.

Typically the AD/LDAP Connector needs to be installed by a sys admin or an operations engineer vs. a developer, since it often requires access to production resources. Following is a checklist of things they should consider ahead of the actual install:

## Host servers

The Connector can be installed on an existing server, even a Domain Controller. However, more often it's installed on virtual machines provisioned just for the Connector. Regardless, the host server should have the following hardware and software specifications/configurations:

### Hardware requirements

* **Architecture**: x86 or x86-64
* **CPU cores**: min. 1, recommended 2
* **Storage**: 500MB of free space on disk
* **Operating System**: The connector can run on Windows or Linux. Windows is required if Kerberos authentication will be used.
* **RAM**: min. 2GB

### Windows version

We recommend using a supported version of Windows Server, like Windows Server 2016 or Windows Server 2019. The connector can also run on Windows Server 2012 R2.

### Time synchronization

It is very important to have the Connector host server clock automatically synchronized with an NTP server. Otherwise the connector will fail to start and report a clock skew error.

## Outbound connectivity

The host server requires outbound network connectivity to the following services:

### Auth0

The connector must be installed on a server with outbound connectivity to the Auth0 service at: `https://{yourDomain}` on port 443.

The connector can be installed and configured behind a proxy server but we don't recommend this. Enable a proxy through the environment or configuration variable `HTTP_PROXY`.

### LDAP

The Connector must be installed on a server with access to the LDAP server on port 389 for ldap or 636 for ldaps. Before installing the Connector you should know the LDAP Connection String and the Base DN required to connect to your LDAP directory.

## Inbound connectivity

You do not need inbound connectivity enabled to the Connector unless Kerberos or certificate authentication is enabled. In these cases, the server(s) on which the Connector is installed must be reachable from your users' browsers on port 443. If more than one instance of the connector is installed, you should use a load balancer to direct traffic to one connector or the another.

To learn more, read [Configure AD/LDAP Connector Authentication with Kerberos](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/configure-ad-ldap-connector-with-kerberos) or [Configure AD/LDAP Connector Authentication with Client Certificates](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/configure-ad-ldap-connector-client-certificates).

## Service account

The Connector will be run using a service account that must be a domain user that at a minimum has read access to the directory. You will need the username/password of this account when performing the install.

## One Connector per Auth0 tenant

If you establish multiple Auth0 tenants, for example to isolate development and production environments, you will need to set up an AD/LDAP connection on the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> and with an AD/LDAP Connector for each Auth0 tenant that needs this form of authentication. A Connector is tied to a specific connection within an Auth0 tenant.

It is possible to have multiple Connectors within one Auth0 tenant if you have multiple AD/LDAP directories against which users will authenticate. For example, to support different departments or customers each with their own directory. In addition, multiple Connectors can point to the same AD or LDAP directory but a Connector can only be used by one Auth0 Connection within one Auth0 tenant.

## High availability

The Connector can be installed on multiple host servers for high-availability and redundancy (most organizations provision two) in case one server becomes unavailable. Each server will have the same requirements listed above. No load balancer is required as that is performed by the Auth0 server itself, unless you enable Kerberos or clientcertificate based authentication.

To learn more, read [Deploy AD/LDAP Connectors for High Availability Environments.](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-high-availability)

## Learn more

* [Install and Configure AD/LDAP Connector](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/install-configure-ad-ldap-connector)
* [Deploy AD/LDAP Connectors for High Availability Environments](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-high-availability)
* [Configure AD/LDAP Connector Authentication with Client Certificates](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/configure-ad-ldap-connector-client-certificates)
* [Configure AD/LDAP Connector Authentication with Kerberos](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/configure-ad-ldap-connector-with-kerberos)


# Monitor AD/LDAP Connector with System Center Operations Manager
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-scom

Describes how to monitor the AD/LDAP Connector with System Center Operations Manager (SCOM).

The Auth0 AD/LDAP connector can run as a service on Windows-based machines.

You can monitor the service status using System Center as you would do with any other service.

1. Open the **Add Monitoring Wizard** and select the **Monitoring Type: Windows Service**:

   <Frame>
     <img alt="Monitor AD/LDAP Connector Wizard Screen 1" />
   </Frame>
2. Enter a name and description:

   <Frame>
     <img alt="Monitor AD/LDAP Connector Wizard Screen 2" />
   </Frame>
3. Select the Server in which the AD/LDAP Connector is installed and then choose **Auth0 ADLDAP**:

   <Frame>
     <img alt="Monitor AD/LDAP Connector Wizard Screen 3" />
   </Frame>
4. Select the limits of **CPU** and **Memory limits**. For example, 10% of CPU and 200MB of RAM are good limits to trigger alerts.

We also recommend that you set up a synthetic transaction to monitor end-to-end authentication.

To learn more, see [Monitor Auth0 Using SCOM](/docs/deploy-monitor/monitor/monitor-using-scom).

## Learn more

* [Monitor Auth0 Using System Center Operations Manager](/docs/deploy-monitor/monitor/monitor-using-scom)


# Set Up AD/LDAP Connector Test Environment
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-test-environment

Describes how to create and test an Active Directory Domain Controller.

You can set up a test environment by creating a minimal AD Domain Controller installation on a cloud-deployed virtual machine (VM). You can run your VM on any cloud platform. This example shows how to set one up on Microsoft Azure.

1. Create a virtual machine on the [Azure Management](https://azure.microsoft.com/en-us/features/azure-portal/) console.

2. Click on the **ENDPOINTS** tab of the new VM, and take note of the **PUBLIC PORT** for the **Remote Desktop** endpoint.

3. Open up Microsoft Remote Desktop client (Windows or Mac) or the client of your choice (such as [rdesktop](http://www.rdesktop.org/) for Linux systems). Create a new connection to your VM.

4. Open the connection, disregarding any certificate warnings presented by the Remote Desktop client. If you're prompted to find PC's, devices, and content on the local network, choose **No**.

5. Click the PowerShell icon in the Windows Task Bar to open the **PowerShell Command Prompt**. Install ADDS.

6. Promote the server to a domain controller that manages a FQDN of `mycompany.local`.

7. When prompted for the **SafeModeAdministratorPassword**, enter the Administrator password you used when creating the VM. Click Enter to continue. The promotion script will run and the VM will automatically reboot.

8. Add test groups and users. Log into VM using the Remote Desktop client and open the PowerShell Command Prompt. Run the following script:

   ```text lines theme={null}
   > New-ADGroup -Name "Accounting" -GroupScope "DomainLocal"
   > New-ADGroup -Name "IT" -GroupScope "DomainLocal"

   > New-ADUser -GivenName Bob -Surname Johnson -Name "Bob Johnson" -SamAccountName bob.johnson -Enabled $True -AccountPassword (ConvertTo-SecureString "Pass@word1!" -AsPlainText -force) -PasswordNeverExpires $True
   > New-ADUser -GivenName Mary -Surname Smith -Name "Mary Smith" -SamAccountName mary.smith -Enabled $True -AccountPassword (ConvertTo-SecureString "Pass@word1!" -AsPlainText -force) -PasswordNeverExpires $True

   > Add-ADGroupMember -Identity Accounting -Members "bob.johnson", "mary.smith"
   > Add-ADGroupMember -Identity IT -Members "mary.smith"
   ```

## Install and configure AD/LDAP Connector

1. Navigate to [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise), and create a new **Active Directory/LDAP** connection with the name `auth0-test-ad`. Be sure to copy the **Ticket URL** that is generated at the end of those instructions.
2. On the VM, disable **Internet Explorer Enhanced Security Configuration**.
3. Open **Internet Explorer** with the **Ticket URL** you saved in step 1.
4. Follow the instructions in the browser to download, install, and configure the **Connector**. When you are prompted for the LDAP service account, use the admin account you created for the VM: **Username**: `mycompany\ad-admin,` **Pas**sword: (same as before).
5. When you're done configuring and installing the Connector, reboot the server.
6. Log back into the VM using Remote Desktop.
7. Open the Connector configuration site by navigating to `http://localhost:8357/`.
8. Check that the **Connector** is able to find a user:

   1. Click on the **Search** tab.
   2. Under "Find User by Login", type `mary.smith`.
   3. Click **Search**. You should get JSON back that contains that user's AD profile data:

## Test authentication from Auth0

To ensure that everything is working using your Auth0 account, we're going to configure your **Default App** in Auth0 to use your new **Active Directory / LDAP** Connection, and use the `/authorize` endpoint to initiate an authentication flow.

1. Navigate to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications).

2. Click the **Settings** icon of your **Default App**.

3. Add `http://jwt.io` to the list of the Application's **Allowed Callback URLs**.

4. Click the **Connections** tab.

5. Under **Enterprise**, enable the `auth0-test-ad` **Active Directory / LDAP** connection.

6. Test the authentication flow by opening the following link in your browser:

   <AuthCodeBlock />

7. Log in with one of the test users that was created in the directory:

   * Username: `mary.smith` or `bob.johnson`
   * Password: `Pass@word1!`

8. If everything is working, you should be redirected to the JWT.io website to see the contents of the resulting JWT.


# Point AD/LDAP Connector to Auth0 Connections
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-to-auth0

Describes how to point AD/LDAP Connector instances to a new connections in Auth0.

You may need to point your AD/LDAP Connector instance to a new connection in Auth0, for example, If you have migrated to a new Auth0 tenant, or if you changed the name of the Auth0 connection. Because you can't rename connections in Auth0, you must create a new AD/ LDAP connection and point your existing Connector instances to it.

1. Create the new AD/LDAP connection in the Auth0 dashboard and copy the resulting **TICKET URL**. If you are using the custom domains, you will need to replace the `{yourDomain}` part of the **TICKET URL** with your custom domain, such as `identity.fabrikam.com`.
2. On the AD/LDAP Connector host in the Connector Admin app, perform an export of the existing settings via the **Import / Export** tab. This is just a precaution in case something were to happen in the following steps that would accidentally overwrite your custom settings. If you are running the Connector on a host that does not have a web browser to access to the Connector Admin website, simply make a copy of your `config.json` file.
3. On the AD/LDAP Connector host, edit the `config.json` file and change the value of the `PROVISIONING_TICKET` property to the **TICKET URL** you copied in Step 1.
4. If you moved from one Auth0 tenant to another, remove the property in the `config.json` file that has the name `urn:auth0:{oldAuth0TenantName}`. If this is not removed, the Connector will still function but this old configuration data is not needed.
5. Restart the AD/LDAP Connector service (the **Auth0 ADLDAP** service in Windows).
6. Take a look at the Connector logs (**Troubleshooting** tab in the Connector Admin tool or tail the `logs.log` file) and make sure there is a recent entry that looks something like: `2016-03-10T22:47:32.970Z - debug: [2016-03-10 22:47:32] Loading settings from ticket: {yourTicketUrl}/info`
7. Make sure the new AD/LDAP connection in the Auth0 dashboard is now showing as connected (the dot to the left of the new connection is green and not red).
8. Perform a test authentication through your new connection and make sure you see activity in your Connector logs as well.

## Learn more

* [Troubleshoot AD/LDAP Connector](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-ad-ldap-connector)


# Deploy AD/LDAP Connectors for High Availability Environments
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-high-availability

Describes how to install multiple instances of the connector for higher availability.

You can deploy multiple instances of the AD/LDAP Connector to provide a high-availability environment for your AD/LDAP connection.

## Overview

To deploy multiple instances of the AD/LDAP Connector, you'll need to:

1. Install the AD/LDAP Connector on the primary server.
2. Copy or export the configuration files of the initial installation.
3. Install the AD/LDAP Connector on additional servers.
4. Import the configuration files from the initial installation to the additional connectors.

## Configure primary server

1. Install and configure the AD/LDAP Connector on the first server.
2. Open the troubleshooting screen (`http://localhost:8357/#troubleshoot`) and run the troubleshooting test. Make sure all tests pass.

<table>
  <thead>
    <tr>
      <th>Test</th>
      <th>Description</th>
      <th>Troubleshoot</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Test 1</td>
      <td>Attempts to establish a TCP connection to the LDAP server and port specified.</td>
      <td>Check basic network connectivity and firewall settings that might prevent such a connection.</td>
    </tr>

    <tr>
      <td>Test 2</td>
      <td>Attempts to perform an LDAP bind on the LDAP server and port specified and with the username and password provided.</td>
      <td>Check the LDAP connection string, search path, username and password.</td>
    </tr>

    <tr>
      <td>Test 3</td>
      <td>Attempts to perform an LDAP search against the directory to check the privileges of the specified username.</td>
      <td>Check the privileges of the username in the target directory.</td>
    </tr>

    <tr>
      <td>Test 4</td>
      <td>Attempts to establish a connection to the Auth0 server.</td>
      <td>Check network connectivity and firewall settings that might prevent such a connection.</td>
    </tr>
  </tbody>
</table>

3. Copy or export the configuration files.

## Configure additional server(s)

1. Install the AD/LDAP Connector on the additional server(s), but do not configure it.
2. Import the configuration files from the primary server.
3. Restart the Auth0 AD/LDAP and Auth0 AD/LDAP Admin Windows Services on the new server(s).
4. Open the troubleshooting screen (`http://localhost:8357/#troubleshoot`) and run the troubleshooting test. Make sure all tests pass.

To learn more, read [Install and Configure the AD/LDAP Connector](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/install-configure-ad-ldap-connector) and [Import and Export AD/LDAP Connector Configurations](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/import-export-ad-ldap-connector-configs).

## Verify connections

In the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, go to the [Authentication > Enterprise > Active Directory / LDAP](https://manage.auth0.com/#/connections/enterprise/ad), and confirm that the connection is active.

If you are encountering issues getting your connection online, read [Troubleshoot AD/LDAP Connector](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-ad-ldap-connector).

## Using Kerberos or client certificates

If you enable Kerberos or client certificates for authentication on your AD/LDAP connection, users contact the AD/LDAP Connector directly instead of going through the Auth0 server.

If you are using a high-availability configuration with multiple connectors, Auth0 recommends that you front them with a network load balancer:

1. Use the `SERVER_URL` parameter to publish the public location where the AD/LDAP Connector will be listening to incoming requests.
2. Map the `SERVER_URL` in the network load balancer to all internal instances of the deployed AD/LDAP Connectors. A special distribution policy is not required (for example, uniform round-robin with no sticky sessions works).

To learn more, read [Configure AD/LDAP Connector Authentication with Kerberos](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/configure-ad-ldap-connector-with-kerberos) or [Configure AD/LDAP Connector Authentication with Client Certificates](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/configure-ad-ldap-connector-client-certificates).

## Learn more

* [Install and Configure AD/LDAP Connector](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/install-configure-ad-ldap-connector)
* [Import and Export AD/LDAP Connector Configurations](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/import-export-ad-ldap-connector-configs)
* [Configure AD/LDAP Connector Authentication with Client Certificates](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/configure-ad-ldap-connector-client-certificates)
* [Configure AD/LDAP Connector Authentication with Kerberos](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/configure-ad-ldap-connector-with-kerberos)
* [Point AD/LDAP Connector to Auth0 Connections](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-to-auth0)
* [Update AD/LDAP Connectors](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/update-ad-ldap-connectors)


# Configure AD/LDAP Connector Authentication with Client Certificates
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/configure-ad-ldap-connector-client-certificates

Describes how to setup authentication using client certificates.

The AD/LDAP Connector also allows users to authenticate with a certificate installed on their machine or device.

## Enable client certificates

1. Go to [Auth0 Dashboard > Authentication > Enterprise > Active Directory/LDAP](https://manage.auth0.com/#/connections/enterprise/ad), and select the connection you want to configure.
2. Toggle the **Use client SSL certificate authentication** option in the settings.
3. Provide IP address ranges in the **IP Ranges** field. Only users coming from the given IP ranges are prompted to authenticate using client certificates. Users from different IP ranges are prompted to login with the username and password login form.

## Configure certificates

Once the AD/LDAP connection has been configured in Auth0, you'll need to configure the certificates in the AD/LDAP Connector. Supporting client certificates will require the following:

* An SSL certificate for the Front Facing URL, because the interaction between the end user and the Connector will need to happen over HTTPS.
* One or more CA certificates.
* A Client Certificate signed by the CA for each user that needs to authenticate using Client Certificates.

1. Before uploading certificates to the AD/LDAP connector, convert X.509 certificates to Base64. Use Base64 or Certutil on Windows Server. To learn more, see [Base64 Decode](https://www.base64decode.org/) at Base64decode or [Certutil.exe](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/certutil#BKMK_encode) in Microsoft documentation.
2. Upload the SSL and CA certificates to the AD/LDAP Connector:

   <Frame>
     <img alt="Configure AD/LDAP Connector Authentication with Client Certificates Setup Screen" />
   </Frame>
3. To test, generate a self-signed CA and Client Certificates using **makecert.exe** on Windows, which is part of the Windows SDK:

   ```bash lines theme={null}
   SET ClientCertificateName=jon
       SET RootCertificateName=FabrikamRootCA
       "C:\Program Files (x86)\Microsoft SDKs\Windows\v7.1A\Bin\makecert.exe" -sky exchange -r -n "CN=%RootCertificateName%" -pe -a sha1 -len 2048 -ss My "%RootCertificateName%.cer"
       "C:\Program Files (x86)\Microsoft SDKs\Windows\v7.1A\Bin\makecert.exe" -n "CN=%ClientCertificateName%" -pe -sky exchange -m 96 -ss My -in "%RootCertificateName%" -is my -a sha1
   ```

   It is important that the Client Certificate's subject be in the format of `CN=AD_USERNAME`, for example `CN=jon`.

In an application, when a user starts the sign-in flow using an AD/LDAP Connection:

```js lines theme={null}
auth.signin({
       popup: true,
       connection: 'FabrikamAD',
       scope: 'openid name email'
     }, onLoginSuccess, onLoginFailed);
```

If the user's IP address falls within the configured IP range, they'll be prompted to authenticate with a Client Certificate:

<Frame>
  <img alt="Configure AD/LDAP Connector Authentication with Client Certificates Choose Client Certificate" />
</Frame>

After choosing the certificate the AD/LDAP Connector will validate it and the user will be logged in:

<Frame>
  <img alt="Configure AD/LDAP Connector Authentication with Client Certificates Logged In User" />
</Frame>


# Configure AD/LDAP Connector Authentication with Kerberos
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/configure-ad-ldap-connector-with-kerberos

Describes how to configure AD/LDAP Connector for federating with Kerberos authentication.

You can federate with Active Directory through the AD/LDAP Connector if you use Classic Login. The AD/LDAP Connector enables your users to authenticate when they are on a domain-joined machine within the corporate network.

## Configure Active Directory

1. Go to [Auth0 Dashboard > Authentication > Enterprise > Active Directory/LDAP](https://manage.auth0.com/#/connections/enterprise/ad), and select the connection you want to configure.
2. Enable the **Use Windows Integrated Auth (Kerberos)** switch.

### Auto-detected range for Kerberos

When Kerberos authentication is enabled, the visible IP address of the server where the AD Connector is running is implicitly added to the network IP range. This means that if a user's requests originate from the same visible IP address as that of the AD Connector, then Kerberos authentication will be attempted.

1. Configure the **IP Ranges**. Use [CIDR-notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing). These should be ranges that are visible by Auth0. When Auth0 is running in the cloud, it won't be able to see your user's internal IP address. In that case you'd configure the public facing/WAN IP address(es) of your company.
2. We recommend restarting the Windows Service that hosts the AD Connector every time this setting is changed. This way, changes will take effect immediately.

## Authentication flow

Depending on the users' location, the authentication flow will be different when IP ranges are set. Using Fabrikam as an example, since it uses the SaaS version of Auth0, they configured their Public IP Address (`24.12.34.56/32`) in the connection. Users connecting from within the building will all originate from `24.12.34.56` (as configured on the connection). When they authenticate, the users can follow the AD/LDAP native flow and have a seamless <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> experience.

For this to work, the network must allow the users to connect to the AD/LDAP Connector on the port configured in the `config.json` file. In highly available deployments of the Connector, the address users will be connecting to is the network load balancer in front of all connectors instances.

<Frame>
  <img alt="Configure AD/LDAP Connector Authentication with Kerberos Flow Diagram" />
</Frame>

To learn more, read [Deploy AD/LDAP Connectors for High Availability Environments.](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-high-availability)

On the other hand, when users are not in the corporate network (for example, at a customer site, working from home without VPN) they won't be able to access the AD/LDAP Connector directly. The users will need to enter their username/password, and Auth0 will validate these credentials with the AD/LDAP Connector (which will in turn use Active Directory to validate those credentials).

<Frame>
  <img alt="Configure AD/LDAP Connector Authentication with Kerberos Credentials Flow Diagram" />
</Frame>

## Auto-login with Lock

<Callout icon="file-lines">
  Detecting IP ranges in an AD/LDAP connection and using those ranges with Lock to allow integrated Windows Authentication is a feature that works in Lock 10, but can only be used in Lock 11 in Universal Login scenarios. This feature is disabled in Lock 11 when Lock 11 is used in Embedded Login scenarios.
</Callout>

When an application is using Lock 10 or 11 within the Login Page hosted by Auth0 (typically used for <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip>/WS-Federation protocols and Single Sign-on (SSO) Integrations), there will be a button which allows users to authenticate using "Windows Authentication".

In some cases the requirement could be to automatically sign in the user if Kerberos is possible (based on the IP-address of the end user). The following changes can be added to the Auth0 Login Page to automatically sign in the user if Kerberos is possible:

```html lines expandable theme={null}
<script src="https://cdn.auth0.com/js/lock/11.x.x/lock.min.js"></script>
<script src="https://cdn.auth0.com/js/auth0/9.x/auth0.min.js"></script>
<script src="https://cdn.auth0.com/js/polyfills/1.0/object-assign.min.js"></script>

<script>
  var config = JSON.parse(decodeURIComponent(escape(window.atob('@@config@@'))));

  var lock = new Auth0Lock(config.clientID, config.auth0Domain, {
      //...additional configuration
  });

  function handleError(err) {
    // add proper error handling
    console.log(err);
  };

  var params = Object.assign({
      scope: config.internalOptions.scope,
      _csrf: config.internalOptions._csrf,
      state: config.internalOptions.state,
    },
    {
      /* additional configuration needed for use of custom domains 
      overrides: {
        __tenant: config.auth0Tenant,
        __token_issuer: '{yourCustomDomain}'
      }, */
      domain: config.auth0Domain,
      clientID: config.clientID,
      redirectUri: config.callbackURL,
      responseType: 'code'
    });

  var webAuth = new auth0.WebAuth(params);

  /*
   * Verify if Kerberos is possible, if it is, try to authenticate the user.
   *
   * the response from getSSOData will only have a connection and strategy if 
   * the IP address is within the Kerberos range in the connection's settings
   */
  webAuth.client.getSSOData(true, function(err, data) {
    if (err) handleError(err);

    if (data.connection && data.strategy === 'ad') {
      webAuth.authorize({connection: data.connection}, function(err) {
        if (err) handleError(err);
      });
    } else {
      lock.show();
    }
  });
</script>
```

## Bypass Kerberos at runtime

You can prevent Kerberos from being used, even if the user is logging in from an IP address within the range configured in the connection's settings, by passing `rememberLastLogin: false` to `lock.show()`.

```javascript lines theme={null}
function useKerberos() {
      // return true to use Kerberos, false to bypass
    };
    
    lock.show({rememberLastLogin: useKerberos()});
```

## Enable Kerberos request logging

1. To enable verbose logging of Kerberos requests, add a system level environment variable `DEBUG=kerberos-server`.
2. Restart the Connector.
3. Log in again and check the logs for more information.

## Firefox support for Kerberos

By default, [Firefox](https://www.mozilla.org/firefox) [rejects all "negotiate" requests required to authenticate users with Kerberos](https://developer.mozilla.org/en-US/docs/Mozilla/Integrated_authentication). If you wish to use Firefox with Kerberos, you need to AllowList the server where the connector is installed.

1. Open a Firefox tab and type `about:config` in the address bar.
2. Dismiss any warning message, and in the search box type `negotiate`.
3. Locate the `network.negotiate-auth.trusted-uris` item and double click to change its value.
4. Type the domain name of the server where the connector is installed. If you have multiple instances of the connector behind a load balancer, add the dns name of the balancer.
   The value accepts a comma-separated list of URL prefixes or domains in the form of `mydomain.com, https://myotherdomain.com`.
5. Click **Ok**. You don't need to restart the server for the changes to take effect.

## HTTPS support for Kerberos

Kerberos authentication works over HTTP (not HTTPS). Microsoft Office 365 and other modern products might not work with HTTP.

To resolve this limitation:

1. Set up a reverse proxy and expose the AD/LDAP Connector on an HTTPS domain. You can use the `SERVER_URL` (Front Facing URL) parameter to publish the public location where the AD/LDAP Connector will be listening to incoming requests.
2. Map the `SERVER_URL` in the reverse proxy to all internal instances of the deployed connectors.


# Disable AD/LDAP Connection Credential Caching
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/disable-credential-caching

Learn how to disable credential caching at the connection level for an AD/LDAP enterprise connection using the Auth0 Management Dashboard.

You can disable credential caching at the connection level for an [AD/LDAP connection](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector) using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

1. Go to [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise), and select the **Active Directory/LDAP** connection type.
2. Select the name of the connection you want to edit.
3. Enable the **Disable Cache** toggle.

## Learn more

* [AD/LDAP Connector Configuration File Schema](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-config-file-schema)
* [AD/LDAP Connector System Requirements](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-requirements)
* [Auth0 AD/LDAP Connector Health Monitor Extension](/docs/customize/extensions/ad-ldap-connector-health-monitor)
* [Configure AD/LDAP Connector Authentication with Client Certificates](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/configure-ad-ldap-connector-client-certificates)
* [Install and Configure AD/LDAP Connector](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/install-configure-ad-ldap-connector)
* [Troubleshoot AD/LDAP Connector](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-ad-ldap-connector)


# Import and Export AD/LDAP Connector Configurations
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/import-export-ad-ldap-connector-configs

Describes how to import or export an AD/LDAP Connector configuration from the Connector Admin Console.

You can export the AD/LDAP Connector configuration or import a previously exported configuration. This is useful for deployments with more than one node of the AD/LDAP Connector deployed for high availability. You can set up and test the configuration on one node then export the working configuration and imported into all subsequent nodes.

1. From a browser, go to `http://localhost:8357` to launch the **Connector Admin Console** on the AD/LDAP Connector server.
2. Click **Import / Export** tab.
3. Export a .zip file that contains the `config.json` file, the `certs` folder and the `lib\\profileMapper.js` file from the `%Program Files(x86)%\Auth0\AD LDAP Connector\` folder.
4. To import, upload a backup .zip file on the **Import / Export** tab.

## Learn more

* [Install and Configure AD/LDAP Connector](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/install-configure-ad-ldap-connector)
* [Deploy AD/LDAP Connectors for High Availability Environments](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-high-availability)
* [Update AD/LDAP Connectors](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/update-ad-ldap-connectors)


# Install and Configure AD/LDAP Connector
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/install-configure-ad-ldap-connector

Describes how to install and configure the AD/LDAP Connector.

## Prerequisites

* Ensure that your system meets the [system requirements](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-requirements).
* Ensure that you have already installed [Git](https://git-scm.com/downloads), [Node.js](https://nodejs.org), and [npm](http://blog.npmjs.org/post/85484771375/how-to-install-npm).
* For most platforms, you will need to have root and/or administrator privileges.

## Install the connector for Windows

### Download and run the installer

Go to [Auth0 Dashboard > Authentication > Enterprise > Active Directory/LDAP](https://manage.auth0.com/#/connections/enterprise/ad), and select the connection you want to configure.

In the **Setup** tab, select the **Install For Windows** button to download the latest installer, which is an MSI file.

Run the installer and follow the instructions to install the **AD/LDAP Connector** as a Windows Service.

<Frame>
  <img alt="AD/LDAP Connector Services" />
</Frame>

Once the installation is complete, you will see a screen in a browser pointing to localhost:

<Frame>
  <img alt="AD/LDAP Connector Admin Ticket" />
</Frame>

Enter the **TICKET URL** provided when you provisioned the connection. The **TICKET URL** uniquely identifies this connector in Auth0. The Connector will use this to communicate with Auth0 Server and automatically complete the configuration.

### Link to LDAP

Enter the LDAP settings:

<Frame>
  <img alt="adldap-connector-admin-settings" />
</Frame>

<table>
  <thead>
    <tr>
      <th>Setting</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>LDAP Connection String</strong></td>
      <td>For example, <code>ldap\://ldap.internal.contoso.com</code>. This is the protocol + the domain name or ip address of your LDAP server. Your LDAP server is the local domain controller where Active Directory is installed. The protocol can be either <code>ldap</code> or <code>ldaps</code>. If you need to use <code>ldaps</code> make sure that the certificate is valid in the current server.</td>
    </tr>

    <tr>
      <td><strong>Base DN</strong></td>
      <td>For example, <code>dc=contoso,dc=com</code>. This is the base container for all the queries performed by the connector.</td>
    </tr>

    <tr>
      <td><strong>Username</strong></td>
      <td>For example, <code>cn=svcauth0,dc=services,dc=contoso,dc=com</code> The full distinguish name of a user to perform queries.</td>
    </tr>

    <tr>
      <td><strong>Password</strong></td>
      <td>The password of the user.</td>
    </tr>
  </tbody>
</table>

Once you submit the above information, the connector will perform a series of tests to validate the information you entered. The results are displayed under **Configuration Log** in the console screen.

<Frame>
  <img alt="adldap-connector-admin-settings-ok" />
</Frame>

Make sure that all tests are green.

<table>
  <thead>
    <tr>
      <th>Test</th>
      <th>Description</th>
      <th>Troubleshoot</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Test 1</td>
      <td>Attempts to establish a TCP connection to the LDAP server and port specified.</td>
      <td>Check basic network connectivity and firewall settings that might prevent such a connection.</td>
    </tr>

    <tr>
      <td>Test 2</td>
      <td>Attempts to perform an LDAP bind on the LDAP server and port specified and with the username and password provided.</td>
      <td>Check the LDAP connection string, search path, username and password.</td>
    </tr>

    <tr>
      <td>Test 3</td>
      <td>Attempts to perform an LDAP search against the directory to check the privileges of the specified username.</td>
      <td>Check the privileges of the username in the target directory.</td>
    </tr>

    <tr>
      <td>Test 4</td>
      <td>Attempts to establish a connection to the Auth0 server.</td>
      <td>Check network connectivity and firewall settings that might prevent such a connection.</td>
    </tr>
  </tbody>
</table>

## Install the connector for other platforms

1. Download and install the latest version of the **[Auth0 Active Directory/LDAP Connector](https://github.com/auth0/ad-ldap-connector/releases)** package to `/tmp`. To learn more, review the [AD/LDAP Connector repository](https://github.com/auth0/ad-ldap-connector).

2. Start your server.
   `node server.js`When prompted for the ticket number, enter the full ticket URL from the **Settings** tab of the **Setup AD/LDAP connector** screen in the Auth0 Management Dashboard.

3. You will be prompted to edit the `config.json` configuration file with your LDAP connection and authentication details:

   <AuthCodeBlock />

4. Run `node server.js` once more to start the Connector. Note that the `LDAP_BIND_PASSWORD` line in `config.json` changes to `LDAP_BIND_CREDENTIALS` at this point.

5. Once the Connector is running, you will need to daemonize the Connector (if you don't already have a tool selected, you can consider [systemd](https://www.freedesktop.org/wiki/Software/systemd/)). For example, for using systemd with Ubuntu Xenial, the file `/lib/systemd/system/auth0-adldap.service` could contain the following:

   ```bash theme={null}
   [Unit]
   Description=Auth0 AD LDAP Agent
   After=network.target

   [Service]
   Type=simple
   Restart=always
   User=ubuntu
   WorkingDirectory=/opt/auth0-adldap
   ExecStart=/usr/bin/node server.js
   ```

6. Run `node admin/server.js` to access the admin UI. The admin UI will be running and available on `http://localhost:8357`.

If you get an `Invalid Ticket` message when configuring the Connector for the first time, the most likely cause is a network issue (for example, you have the Connector running behind a proxy).

## Learn more

* [Troubleshoot AD/LDAP Connector](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-ad-ldap-connector)
* [AD/LDAP Connector System Requirements](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-requirements)
* [Point AD/LDAP Connector to Auth0 Connections](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-to-auth0)
* [Configure AD/LDAP Connector Authentication with Client Certificates](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/configure-ad-ldap-connector-client-certificates)
* [Configure AD/LDAP Connector Authentication with Kerberos](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/configure-ad-ldap-connector-with-kerberos)
* [Update AD/LDAP Connectors](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/update-ad-ldap-connectors)


# Map AD/LDAP Profile Attributes to Auth0 User Profile
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/map-ad-ldap-profile-attributes-to-auth0

Describes how to map AD/LDAP profile attributes to Auth0 user profile attributes using the Profile Mapper in the Connector Admin Console.

You can modify the mapping of profile attributes from AD/LDAP attributes to attributes in the Auth0 user profile.

1. From a browser, go to `http://localhost:8357` to launch the **Connector Admin Console** on the AD/LDAP Connector server.
2. Click **Profile Mapper** to open a code editor screen which maps attributes from a source directory service (represented by the `raw_data` variable) to a variable that gets returned to populate the Auth0 user profile.
   The first part of the function instantiates a variable called `profile` and has a mapping for the core portion of the Auth0 User Profile. Additional attributes can be set below that using syntax in the form:
   `profile['department'] = raw_data['companydept'];`
   In this example, `department` is the name of the attribute in the Auth0 user profile and `companydept` is the name of the attribute in the source directory service (such as AD).
3. Click **Save** when you are done modifying the LDAP configuration.
4. After the Connector runs the tests, ensure that all the tests are green.

<table>
  <thead>
    <tr>
      <th>Test</th>
      <th>Description</th>
      <th>Troubleshoot</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Test 1</td>
      <td>Attempts to establish a TCP connection to the LDAP server and port specified.</td>
      <td>Check basic network connectivity and firewall settings that might prevent such a connection.</td>
    </tr>

    <tr>
      <td>Test 2</td>
      <td>Attempts to perform an LDAP bind on the LDAP server and port specified and with the username and password provided.</td>
      <td>Check the LDAP connection string, search path, username and password.</td>
    </tr>

    <tr>
      <td>Test 3</td>
      <td>Attempts to perform an LDAP search against the directory to check the privileges of the specified username.</td>
      <td>Check the privileges of the username in the target directory.</td>
    </tr>

    <tr>
      <td>Test 4</td>
      <td>Attempts to establish a connection to the Auth0 server.</td>
      <td>Check network connectivity and firewall settings that might prevent such a connection.</td>
    </tr>
  </tbody>
</table>


# Update AD/LDAP Connectors
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/update-ad-ldap-connectors

Learn how to update AD/LDAP Connectors.

If there are multiple instances of the AD/LDAP Connector in your deployment, Auth0 recommends that you perform the steps below for each instance one at a time, so that only one instance is down at any point.

## Admin console (Windows)

1. Open the Admin Console by navigating to `http://localhost:8357/`. If the Admin Console has outbound access to the internet it will verify if a new version is available and show this on top of the page:

   <Frame>
     <img alt="Update AD/LDAP Connectors Admin Console Screen" />
   </Frame>
2. Go to the **Update** tab to update the installation on the current machine to the latest version. The update will take about 2 minutes and the updater logs will be displayed in the Admin Console.

## Updater script (Windows)

The updater script will update the AD/LDAP Connector from the command line by running the following steps:

1. Verify if an update is available.
2. Backup the existing configuration, certificates and profileMapper.js.
3. Uninstall the AD/LDAP Connector.
4. Download the update.
5. Install the AD/LDAP Connector.
6. Restore the existing configuration, certificates and profileMapper.js.
7. Start the Windows Service.
8. To run the updater script execute the following statement in the command line:
   `@powershell -NoProfile -ExecutionPolicy Bypass -Command "iex ((new-object net.webclient).DownloadString('https://cdn.auth0.com/connector/windows/update-connector.ps1'))"`

The updater script uses specific PowerShell commands that are only available in Windows PowerShell 3.0 and higher. If you're running on Windows 2008 and Windows 2008 R2 you might need to update your PowerShell version first.

To learn more, see [Download Window Management Framework](https://www.microsoft.com/en-us/download/details.aspx?id=34595).

## Manual update (Windows/Linux)

1. Verify the version you have installed. Hover over the Connector status indicator on the console. The tooltip will indicate the current status and the installed version.
2. Download the latest version of the [installer](https://cdn.auth0.com/connector/windows/adldap-5.0.10.msi?_ga=2.58973869.1675886805.1589821069-1123834949.1586212750).
   Use the GitHub repository [version](https://github.com/auth0/ad-ldap-connector/releases/tag/v5.0.10) for other platforms.
3. Backup your current configuration from the Admin Console or manually.

   1. From the Admin Console, click the **Download** button to generate a .zip file which contains the `config.json` file, the `certs` folder and the `lib\\profileMapper.js` file.
   2. To do it manually, backup the same files listed above from `%Program Files(x86)%\Auth0\AD LDAP Connector\` folder. The path works for Windows. Files in other platforms may be located somewhere else but will contain the same assets.
4. Run the installer and follow the instructions.
5. Close the Configuration dialog without changing anything.
6. Restore files from the Admin Console or manually.

   1. From the Admin Console, upload the .zip file on the **Import / Export** tab.
   2. To do it manually, copy the files you backed up previously.
7. Restart the **Auth0 AD LDAP** service from the service console.


# Connect Your App to ADFS
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/adfs

Learn how to connect your application to Active Directory Federation Services (ADFS) using enterprise connections.

To connect your application to Microsoft's Active Directory Federation Services (ADFS), you will need to provide the following information to your ADFS administrator:

* Realm Identifier: `urn:auth0:{yourTenant}`
* Endpoint: `https://{yourDomain}/login/callback` or `https://<YOUR CUSTOM DOMAIN>/login/callback`, if you are using a [custom domain](/docs/customize/custom-domains).

<Card title="Federated metadata">
  The Federation Metadata file contains information about the ADFS server's certificates. If the Federation Metadata endpoint (`/FederationMetadata/2007-06/FederationMetadata.xml`) is enabled in ADFS, Auth0 can periodically (once a day) look for changes in the configuration, like a new signing certificate added to prepare for a rollover. Because of this, enabling the Federation Metadata endpoint is preferred to providing a standalone metadata file. If you provide a standalone metadata file, we will notify you via email when the certificates are close to their expiration date.
</Card>

You can use a script to to setup the connection or set it up manually.

## Scripted setup

Run the following two commands in the Windows PowerShell window.

<Callout icon="file-lines">
  You must run this script as an administrator of your system.
</Callout>

```powershell wrap lines theme={null}
(new-object Net.WebClient -property @{Encoding = [Text.Encoding]::UTF8}).DownloadString("https://raw.github.com/auth0/adfs-auth0/master/adfs.ps1") | iex
```

<AuthCodeBlock />

For automated integration, this script uses the [ADFS PowerShell SnapIn](http://technet.microsoft.com/en-us/library/adfs2-powershell-basics.aspx) to create and configure a **<Tooltip href="/docs/glossary?term=Relying+Party">Relying Party</Tooltip>** that will issue, for the authenticated user, the following claims: **email**, **upn**, **given name**, and **surname**.

<Callout icon="file-lines">
  If you are using the [custom domains](/docs/customize/custom-domains) feature, you will need to replace the `$webAppEndpoint` value with `https://<YOUR CUSTOM DOMAIN>/login/callback`.
</Callout>

The script creates the Relying Party Trust on ADFS, as follows:

<AuthCodeBlock />

The script also creates rules to output the most common attributes, such as email, UPN, given name, or surname:

```powershell lines theme={null}
$rules = @'
@RuleName = "Store: ActiveDirectory -> Mail (ldap attribute: mail), Name (ldap attribute: displayName), Name ID (ldap attribute: userPrincipalName), GivenName (ldap attribute: givenName), Surname (ldap attribute: sn)"
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
=> issue(store = "Active Directory",
    types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
             "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
             "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
             "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
             "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"), query = ";mail,displayName,userPrincipalName,givenName,sn;{0}", param = c.Value);
'@
Set-ADFSRelyingPartyTrust –TargetName $realm -IssuanceTransformRules $rules
$rSet = New-ADFSClaimRuleSet –ClaimRule '=> issue(Type = "http://schemas.microsoft.com/authorization/claims/permit", Value = "true");'
Set-ADFSRelyingPartyTrust –TargetName $realm –IssuanceAuthorizationRules $rSet.ClaimRulesString
```

## Manual setup part 1: Add a Relying Party Trust

1. Open the ADFS Management Console.
2. On the right side of the console, click **Add Relying Party Trust**\*
3. Click **Start**.
4. Select **Enter data about the relying party manually**, and click **Next**.
5. Type a name (such as `{yourAppName}`), and click **Next**.
6. Use the default (`ADFS 2.0 profile`), and click **Next**.
7. Use the default (`no encryption certificate`), and click **Next**.
8. Check **Enable support for the WS-Federation...**, and type this value in the textbox:
   `https://{yourDomain}/login/callback`,or if you are using a [custom domain](/docs/customize/custom-domains), use `https://<YOUR CUSTOM DOMAIN>/login/callback`
9. Click **Next**.
10. Add a Relying Party Trust identifier with this value:
    `urn:auth0:{yourTenant}`
11. Click **Add**, and then **Next**.
12. Leave the default `Permit all users...`, and click **Next**.
13. Click **Next**, and then **Close**.

## Manual setup part 2: Add a claim issuance policy rule

1. If you're using Windows Server 2019, the Edit Claim Issuance Policy dialog box automatically opens when you finish the Add Relying Party Trust wizard. If you're using Windows 2012 or 2016, follow these steps:

<table>
  <thead>
    <tr>
      <th>In Windows Server 2012</th>
      <th>In Windows Server 2016</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>In the Actions panel on the right side of the console, find the Relying Party Trust you just created. Beneath it, click <strong>Edit Claim Issuance Policy</strong>.</td>
      <td>In the console tree, under ADFS, click <strong>Relying Party Trusts</strong>. On the right side of the console, find the Relying Party Trust you just created. Right-click it and click <strong>Edit Claim Issuance Policy</strong>.</td>
    </tr>
  </tbody>
</table>

2. In the Edit Claim Issuance Policy Window, under Issuance Transform Rules, click **Add Rule...**.
3. Leave the default `Send LDAP Attributes as Claims`.
4. Give the rule a name that describes what it does.
5. Under Attribute Store, select **Active Directory**.
6. Select these mappings under `Mapping of LDAP attributes to outgoing claim types`, and click **Finish**.

<table>
  <thead>
    <tr>
      <th>LDAP Attribute</th>
      <th>Outgoing Claim Type</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>E-Mail-Addresses</td>
      <td>E-Mail Address</td>
    </tr>

    <tr>
      <td>Display-Name</td>
      <td>Name</td>
    </tr>

    <tr>
      <td>User-Principal-Name</td>
      <td>Name ID</td>
    </tr>

    <tr>
      <td>Given-Name</td>
      <td>Given Name</td>
    </tr>

    <tr>
      <td>Surname</td>
      <td>Surname</td>
    </tr>
  </tbody>
</table>

### Add additional LDAP attributes

The mappings in the previous steps are the most commonly used, but if you need additional LDAP attributes with information about the user, you can add more claim mappings.

1. If you closed the window on the previous step, select **Edit Claim Rules** on the context menu for the Relying Party Trust you created, and edit the rule.
2. Create an additional row for every LDAP attribute you need, choosing the attribute name in the left column and desired claim type in the right column.
3. If the claim type you are looking for doesn't exist, you have two options:

   1. Type a [namespace-qualified name](/docs/secure/tokens/json-web-tokens/create-custom-claims) for the new claim (for example, `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/department`).
   2. Register a new claim type (under **ADFS > Services > Claim Descriptions** on the ADFS admin console), and use the claim name in the mapping.
      Auth0 uses the name part of the claim type (for example `department` in `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/department`) as the attribute name for the user profile.

## Next Steps

Now that you have a working connection, the next step is to configure your application to use it. You can follow our step-by-step quickstarts or use our libraries and API.

* [Get started with our Quickstarts](/docs/quickstarts)
* [Configure your application using our Lock login form](/docs/libraries/lock)
* [Configure your application using our Auth0.js library and your own UI](/docs/libraries/auth0js)
* [Use our Authentication API to authenticate](https://auth0.com/docs/api/authentication)


# Connect Your Native App to Microsoft Azure Active Directory Using Resource
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/azure-active-directory-native

Learn how to connect your app to Microsoft Azure Active Directory using an enterprise connection with the Resource Owner flow.

In addition to the WS-Federation and <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect flows, it's also possible to use the [Resource Owner](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow) flow with Azure AD. This flow allows you to capture and validate a user's credentials (email and password) instead of showing the Azure AD login page. For security and <Tooltip href="/docs/glossary?term=Single+Sign-on">Single Sign-on</Tooltip> (SSO) reasons, this is not the recommended approach; still, the <Tooltip href="/docs/glossary?term=Resource+Owner">Resource Owner</Tooltip> flow can be useful in Native mobile scenarios or to batch-process authentication with Azure AD.

This configuration requires two applications: a Web Application and/or Web API, and a Native Application. From Azure AD's point of view, users will be authenticated using the Native Application to gain access to the Web Application and/or Web API.

<Frame>
  <img alt="Overview Diagram of Azure AD Apps using Resource Owner flow" />
</Frame>

## Prerequisites

[Register your Application with Auth0](/docs/get-started/auth0-overview/create-applications):

1. Select **Native** for the **Application Type**.
2. Add an **Allowed Callback URL**. Your callback URL format will vary depending on your platform. For details about the format for your platform, see our [Native Quickstarts](/docs/quickstart/native).
3. Ensure your Application's [Grant Types](/docs/get-started/applications/update-grant-types) include the appropriate flows.

## Steps

To connect your application using Resource Owner flow, you must:

1. [Set up your applications in the Microsoft Azure portal](#set-up-your-applications-in-the-microsoft-azure-portal).
2. [Create an enterprise connection in Auth0](#create-an-enterprise-connection-in-auth0).
3. [Enable the enterprise connection for your Auth0 Application](#enable-the-enterprise-connection-for-your-auth0-application).
4. [Test the connection](#test-the-connection).

<Card title="Microsoft Azure account">
  Before proceeding, you will need a valid Microsoft Azure account and must have **your own** Microsoft Azure AD directory for which you are a Global administrator.

  If you don't have a Microsoft Azure account, you can [sign up for free](https://azure.microsoft.com/en-us/free); then, if necessary, set up an Azure AD directory by following Microsoft's [Quickstart: Create a new tenant in Azure Active Directory - Create a new tenant for your organization](https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/active-directory-access-create-new-tenant#create-a-new-tenant-for-your-organization).

  Alternatively, if you have an Office 365 account, you can use the account's Azure AD instance instead of creating a new one. To access your Office 365 account's Azure AD instance:

  1. [Sign in to Office 365](https://portal.office.com), and navigate to the [Office 365 Admin Center](https://portal.office.com/adminportal/home#/homepage).
  2. Open the **Admin centers** menu drawer located in the left menu, and click on **Azure AD**.
</Card>

## Set up your applications in the Microsoft Azure portal

<Warning>
  Before proceeding, you must have already set up **your own** Microsoft Azure AD directory for which you are a Global administrator. To learn how, follow Microsoft's [Quickstart: Create a new tenant in Azure Active Directory - Create a new tenant for your organization](https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/active-directory-access-create-new-tenant#create-a-new-tenant-for-your-organization).
</Warning>

### Register a new web application

To learn how to register your application with Azure AD, read [Quickstart: Register an application with the Microsoft identity platform on Microsoft Docs](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app).

<Warning>
  If you have more than one Azure AD directory, make sure you are in the correct directory when you register your app.
</Warning>

While setting up your application, make sure you use the following settings:

* If you want to allow users from external organizations (like other Azure AD directories), select **Accounts in any organizational directory (Any Azure AD directory - Multitenant)** when setting **Supported account types**.
* When asked to set a **Redirect URI**, select **Web** and enter your callback URL: `https://{yourDomain}/login/callback`.

<Card title="Find your Auth0 domain name for redirects">
  If your Auth0 domain name is not shown above and you are not using our [custom domains](/docs/customize/custom-domains) feature, your domain name is a concatenation of your tenant name, your regional subdomain, and `auth0.com`, separated by the dot (`.`) symbol.

  For example, if your tenant name is `exampleco-enterprises`, and your tenant is in the US region, your Auth0 domain name would be `exampleco-enterprises.us.auth0.com` and your **Redirect URI** would be `https://exampleco-enterprises.us.auth0.com/login/callback`.

  However, if your tenant is in the US region and was created before June 2020, then your Auth0 domain name would be `exampleco-enterprises.auth0.com` and your **Redirect URI** would be `https://exampleco-enterprises.auth0.com/login/callback`.

  If you are using [custom domains](/docs/customize/custom-domains), your **Redirect URI** would be `https://<YOUR CUSTOM DOMAIN>/login/callback`.
</Card>

During this process, record the **Application (client) ID** that Microsoft generates for your application (you can find this on the application's **Overview** screen) as you will need it later in the tutorial.

### Configure your web application to expose an API

To learn how to configure your Web application to expose an API with Azure AD, read [Quickstart: Configure an application to expose web APIs on Microsoft Docs](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-expose-web-apis).

While configuring your app, make sure you use the following settings:

* When asked to set a **Scope name**, enter `API.Access`.

During this process, record the **Application ID URI** that Microsoft generates for your application as you will need it later in the tutorial.

### Register a new native application

To learn how to register a native application in Azure, read [Quickstart: Register an application with the Microsoft identity platform on Microsoft Docs](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app).

<Warning>
  If you have more than one Azure AD directory, make sure you are in the correct directory when you register your app.
</Warning>

While setting up your app, make sure you use the following settings:

* If you want to allow users from external organizations (like other Azure AD directories), select **Accounts in any organizational directory (Any Azure AD directory - Multitenant)** when setting **Supported account types**.
* When asked to set a **Redirect URI**, select `Public client/native (mobile & desktop)` and enter your callback URL. Your callback URL format will vary depending on your platform. For details about the format for your platform, read [Native Quickstarts](/docs/quickstart/native).

During this process, record the **Application (client) ID** that Microsoft generates for your application (you can find this on the application's **Overview** screen) as you will need it later in the tutorial.

### Create a client secret for your native application

To learn how to create a <Tooltip href="/docs/glossary?term=client+secret">client secret</Tooltip>, read [Quickstart: Configure a client application to access web APIs - Add Credentials to your web application on Microsoft Docs](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-access-web-apis#add-credentials-to-your-web-application).

Generate a **Client secret** and record its value. You will need it later in the tutorial.

<Callout icon="file-lines">
  If you configure an expiring secret, make sure to **record the expiration date**; you will need to renew the key before that day to avoid a service interruption.
</Callout>

### Add permissions for your native application

To learn how to add permissions for your **Native** application, read [Quickstart: Configure a client application to access web APIs - Add permissions to access web APIs on Microsoft Docs](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-access-web-apis#add-permissions-to-access-web-apis).

Auth0 requires that you enable the least privileged permissions necessary (for the Microsoft Graph API and for the Web application you configured to expose an API) for this configuration to work properly. To learn more about Microsoft Graph API permissions, read [Microsoft Graph permissions reference on Microsoft Docs](https://learn.microsoft.com/en-us/graph/permissions-reference).

While setting up your permissions, make sure you use the following settings for Microsoft Graph API:

* When asked for a permission type, choose **Delegated permissions**.

  * Under **User**, select **User.Read** so your app can sign in users and read the signed-in user's profile.
  * Under **Directory**, select **Directory.Read.All** so your app can read directory data on the signed-in user's behalf.

For your Web app that you configured to expose an API, make sure you use the following settings:

* When asked for a permission type, choose **Delegated permissions**.

  * Under **API**, select **API.Access** so your app can access your API on the user's behalf.

## Configure the connection in Auth0

After creating both applications in Azure AD, you can configure the Auth0 connection:

1. Navigate to [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise), locate **Microsoft Azure AD**, and select the add (**+**) button.

   <Frame>
     <img alt="Dashboard - Connections - Enterprise" />
   </Frame>
2. Enter details for your connection, and select **Create**:

<table>
  <thead>
    <tr>
      <th><strong>Field</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Connection name</strong></td>
      <td>Logical identifier for your connection; it must be unique for your tenant. Once set, this name can't be changed.</td>
    </tr>

    <tr>
      <td><strong>Microsoft Azure AD Domain</strong></td>
      <td>Your Azure AD domain name. You can find this on your Azure AD directory's overview page in the Microsoft Azure portal.</td>
    </tr>

    <tr>
      <td><strong>Client ID</strong></td>
      <td>Unique identifier for your registered Azure AD application. Enter the saved value of the <strong>Application (client) ID</strong> for the Native application you registered in Azure AD.</td>
    </tr>

    <tr>
      <td><strong>Client Secret</strong></td>
      <td>String used to gain access to your registered Azure AD application. Enter the saved value of the <strong>Client secret</strong> for the Native app you registered in Azure AD.</td>
    </tr>

    <tr>
      <td><strong>Use common endpoint</strong> (optional)</td>
      <td>When enabled, your application will dynamically accept users from new directories. Typically enabled if you selected a multitenant option for <strong>Supported account types</strong> for the application you registered in Azure AD. When enabled, Auth0 will redirect users to Azure's common login endpoint, and Azure will perform <em>Home Realm Discovery</em> based on the domain of the user's email address.</td>
    </tr>

    <tr>
      <td><strong>Identity API</strong></td>
      <td>API used by Auth0 to interact with Azure AD endpoints. Learn about the differences in behavior in Microsoft's <a href="https://docs.microsoft.com/en-us/azure/active-directory/develop/azure-ad-endpoint-comparison">Why update to Microsoft identity platform (v2.0)</a> doc. Select <code>Azure Active Directory (v1)</code>, and for <strong>App ID URI</strong>, enter the saved value of the <strong>Application ID URI</strong> that was created when you configured your Web application to expose an API.</td>
    </tr>

    <tr>
      <td><strong>Attributes</strong></td>
      <td>Basic attributes for the signed-in user that your app can access. Indicates how much information you want stored in the Auth0 User Profile.</td>
    </tr>

    <tr>
      <td><strong>Extended Attributes</strong> (optional)</td>
      <td>Extended attributes for the signed-in user that your app can access.</td>
    </tr>

    <tr>
      <td><strong>Auth0 APIs</strong> (optional)</td>
      <td>When selected, indicates that you require the ability to make calls to the Azure AD Users API.</td>
    </tr>

    <tr>
      <td><strong>Sync user profile attributes at each login</strong></td>
      <td>When enabled, Auth0 automatically syncs user profile data with each user login, thereby ensuring that changes made in the connection source are automatically updated in Auth0.</td>
    </tr>

    <tr>
      <td><strong>Email Verification</strong></td>
      <td>Choose how Auth0 sets the <code>email\_verified</code> field in the user profile. To learn more, see <a href="/docs/authenticate/identity-providers/enterprise-identity-providers/azuread-adfs-email-verification">Email Verification for Azure AD and ADFS</a>.</td>
    </tr>
  </tbody>
</table>

<Frame>
  <img alt="Create new Azure AD connection" />
</Frame>

## Enable the enterprise connection for your Auth0 application

To use your new Azure AD enterprise connection, you must [enable the connection](/docs/authenticate/identity-providers/enterprise-identity-providers/enable-enterprise-connections) for your Auth0 Applications.

## Test the connection

Now you're ready to [test your connection](/docs/authenticate/identity-providers/enterprise-identity-providers/test-enterprise-connections).

## Group Memberships and Advanced Profile Information

In this native flow, Auth0 will receive an <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> from Azure AD which has been issued for your Azure AD Web application. As a result, features like loading group memberships and advanced profile information will no longer work because the Access Token received by Azure AD can no longer be used to query the Azure AD Graph API for this additional information.

However, if you depend on group memberships and advanced profile information, you can change your configuration to accommodate your needs:

1. In Azure, configure your Native application with additional permissions for the Microsoft Graph API:

   * When asked for a permission type, choose **Delegated permissions**.

     * Under **Directory**, select **Directory.AccessAsUser.All**, so your app can access the directory as the signed-in user.
2. In Auth0, modify your Azure AD enterprise connection:

   * In **Identity API**, select `Azure Active Directory (v1)`, and for **App ID URI**, enter the URI of the Azure AD Graph API:

     ```text lines theme={null}
     https://graph.windows.net
     ```

## Next Steps

* [Integrate with Auth0 using one of our libraries](/docs/libraries)
* [Integrate with Auth0 using our Authentication API](https://auth0.com/docs/api/authentication)
* [Read more about the authentication flow](/docs/get-started/authentication-and-authorization-flow)
* [Pass additional parameters to the Identity Provider](/docs/authenticate/identity-providers/pass-parameters-to-idps)
* [Re-prompt users for permissions](/docs/authenticate/identity-providers/social-identity-providers/reprompt-permissions)


# Connect Your App to Microsoft Azure Active Directory
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/azure-active-directory/v2

Learn how to connect your app to Microsoft Azure Active Directory using an enterprise connection.

<Card title="Overview">
  Key Concepts

  * Follow the steps to register your application with Azure AD and connect to your Auth0 instance.
  * Test the connection before taking your configuration to production.
  * Review the troubleshooting tips.
</Card>

<Warning>
  **Important:** Extended attributes on Azure Active Directory (v1) connections Because Microsoft is deprecating and retiring the Azure AD Graph API, connections using the Azure Active Directory (v1) Identity API can no longer newly enable Get extended profile, Get user groups, or Get nested groups (`options.ext_profile`, `options.ext_groups`, `options.ext_nested_groups`). For existing v1 connections, these options remain only if already enabled, but will stop working entirely once Microsoft’s Graph API retirement is complete in 2025. Extended attributes remain supported for connections using the Microsoft Identity Platform (v2) Identity API, which relies on Microsoft Graph and requires the delegated permissions `User.Read` and `Directory.Read.All`.
</Warning>

You can integrate with Microsoft Azure Active Directory (AD) if you want to let users:

* From within your company use your application from an Azure AD controlled by you or your organization.
* From other companies' Azure ADs use your application. (We recommend that you configure external directories as different connections.)

<Callout icon="file-lines">
  Claims returned from the Azure AD enterprise connection are static; custom or optional claims will not appear in user profiles. If you need to include custom or optional claims in user profiles, use a SAML or OIDC connection instead.
</Callout>

## Steps

To connect your application to Azure AD, you must:

1. [Register your app with Azure AD](#register-your-app-with-azure-ad)
2. [Create an enterprise connection in Auth0](#create-an-enterprise-connection-in-auth0)
3. [Enable the enterprise connection for your Auth0 Application](#enable-the-enterprise-connection-for-your-auth0-application)
4. [Test the connection](#test-the-connection)

### Register your app with Azure AD

To register your app with Azure AD, read Microsoft's [Quickstart: Register an application with the Microsoft identity platform](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app).

<Warning>
  If you have more than one Azure AD directory, make sure you are in the correct directory when you register the app you want to use with Auth0.
</Warning>

During registration, configure the following settings:

<table>
  <thead>
    <tr>
      <th>Option</th>
      <th>Setting</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Supported account types</strong></td>
      <td>To enable SCIM-based user provisioning from this directory, select <strong>Accounts in this organizational directory only (Single tenant)</strong>. To allow users from external organizations (like other Azure AD directories) choose the appropriate multitenant option. Multitenant options include the following: <strong>Accounts in any organizational directory (Any Azure AD directory - Multitenant)</strong>.</td>
    </tr>

    <tr>
      <td><strong>Redirect URI</strong></td>
      <td>Select a Redirect URI type of <strong>Web</strong>, and enter your callback URL: `https://{yourDomain}/login/callback`.</td>
    </tr>
  </tbody>
</table>

<Card title="Find your Auth0 domain name for redirects">
  If your Auth0 domain name is not shown above and you are not using our [custom domains](/docs/customize/custom-domains) feature, your domain name is a concatenation of your tenant name, your regional subdomain, and `auth0.com`, separated by the dot (`.`) symbol.

  For example, if your tenant name is `exampleco-enterprises`, and your tenant is in the US region, your Auth0 domain name would be `exampleco-enterprises.us.auth0.com` and your **Redirect URI** would be `https://exampleco-enterprises.us.auth0.com/login/callback`.

  However, if your tenant is in the US region and was created before June 2020, then your Auth0 domain name would be `exampleco-enterprises.auth0.com` and your **Redirect URI** would be `https://exampleco-enterprises.auth0.com/login/callback`.

  If you are using [custom domains](/docs/customize/custom-domains), your **Redirect URI** would be `https://<YOUR CUSTOM DOMAIN>/login/callback`.
</Card>

During this process, Microsoft generates an **Application (client) ID** for your application; you can find this on the app's **Overview** screen. **Make note of this value.**

#### Create a client secret

To create a <Tooltip href="/docs/glossary?term=client+secret">client secret</Tooltip>, read Microsoft's [Microsoft's Add and manage application credentials in Microsoft Entra ID - Add a Client Secret](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials?source=recommendations\&tabs=client-secret).

Once generated, **make note of this value**.

<Callout icon="file-lines">
  If you configure an expiring secret, make sure to **record the expiration date**; you will need to renew the key before that day to avoid a service interruption.
</Callout>

#### Add permissions

To add permissions, read Microsoft's [Quickstart: Configure a client application to access web APIs - Add permissions to access web APIs](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-access-web-apis#add-permissions-to-access-web-apis).

While configuring permissions, consider the following:

If you want to enable extended attributes (such as E**xtended Profile** or **Security Groups**), then you will need to configure the following permissions for the **Microsoft Graph API**.

<table>
  <thead>
    <tr>
      <th>Delegated Permissions</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Users > User.Read</strong></td>
      <td>So your app can sign in users and read the signed-in users' profiles.</td>
    </tr>

    <tr>
      <td><strong>Directory > Directory.Read.All</strong></td>
      <td>So your app can read directory data on the signed-in user's behalf.</td>
    </tr>
  </tbody>
</table>

### Create an enterprise connection in Auth0

Create and configure an Azure AD Enterprise Connection in Auth0. Make sure you have the **Application (client) ID** and the **Client secret** generated when you set up your app in the Microsoft Azure portal.

1. Navigate to [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise), locate **Microsoft Azure AD**, and select its `+`.

   <Frame>
     <img alt="Dashboard - Connections - Enterprise" />
   </Frame>
2. Enter details for your connection, and select **Create**:

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Connection name</strong></td>
      <td>Logical identifier for your connection; it must be unique for your tenant. Once set, this name can't be changed.</td>
    </tr>

    <tr>
      <td><strong>Microsoft Azure AD Domain</strong></td>
      <td>Your Azure AD domain name. You can find this on your Azure AD directory's overview page in the Microsoft Azure portal.</td>
    </tr>

    <tr>
      <td><strong>Client ID</strong></td>
      <td>Unique identifier for your registered Azure AD application. Enter the saved value of the <strong>Application (client) ID</strong> for the app you just registered in Azure AD.</td>
    </tr>

    <tr>
      <td><strong>Client Secret</strong></td>
      <td>String used to gain access to your registered Azure AD application. Enter the saved value of the <strong>Client secret</strong> for the app you just registered in Azure AD.</td>
    </tr>

    <tr>
      <td><strong>User ID Attribute Type</strong></td>
      <td>Attribute in the ID token that will be mapped to the user\_id property in Auth0. The options correspond to the two supported ID types described in Microsoft's documentation: <a href="https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference#use-claims-to-reliably-identify-a-user">ID token claims reference - Microsoft identity platform</a>.</td>
    </tr>

    <tr>
      <td><strong>Use common endpoint</strong></td>
      <td>(Optional) When enabled, your application will dynamically accept users from new directories. Typically enabled if you selected a multi-tenant option for supported account types for the application you just registered in Azure AD. Auth0 redirects users to Azure's common login endpoint and Azure performs Home Realm Discovery based on the domain of the user's email address.</td>
    </tr>

    <tr>
      <td><strong>Identity API</strong></td>
      <td>API used by Auth0 to interact with Azure AD endpoints. Learn about the differences in behavior in Microsoft's <a href="https://docs.microsoft.com/en-us/azure/active-directory/develop/azure-ad-endpoint-comparison">Why update to Microsoft identity platform (v2.0)</a> doc.</td>
    </tr>

    <tr>
      <td><strong>Attributes</strong></td>
      <td>Basic attributes for the signed-in user that your app can access. Indicates how much information you want stored in the Auth0 User Profile.</td>
    </tr>

    <tr>
      <td><strong>Extended Attributes</strong> (optional)</td>
      <td>Extended attributes for the signed-in user that your app can access.</td>
    </tr>

    <tr>
      <td><strong>Auth0 APIs</strong> (optional)</td>
      <td>When selected, indicates that we require the ability to make calls to the Azure AD API, which allows us to search for users in the Azure AD Graph even if they never logged in to Auth0.</td>
    </tr>

    <tr>
      <td><strong>Email Verification</strong></td>
      <td>Choose how Auth0 sets the <code>email\_verified</code> field in the user profile. To learn more, read <a href="/docs/authenticate/identity-providers/enterprise-identity-providers/azuread-adfs-email-verification">Email Verification for Azure AD and ADFS</a>.</td>
    </tr>

    <tr>
      <td><strong>Purpose</strong></td>
      <td>Enable the connection for Authentication, Connected Accounts for Token Vault, or both. To learn more, read [User authentication vs Connected Accounts](/docs/secure/tokens/token-vault/connected-accounts-for-token-vault#user-authentication-vs-connected-accounts).</td>
    </tr>
  </tbody>
</table>

3. In the **Provisioning** view, you can configure how user profiles get created and updated in Auth0.

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Sync user profile attributes at each login</strong></td>
      <td>When enabled, Auth0 automatically syncs user profile data with each user login, thereby ensuring that changes made in the connection source are automatically updated in Auth0.</td>
    </tr>

    <tr>
      <td><strong>Sync user profiles using SCIM</strong></td>
      <td>When enabled, Auth0 allows user profile data to be synced using SCIM. For more information, read <a href="/docs/authenticate/protocols/scim/configure-inbound-scim">Configure Inbound SCIM</a>.</td>
    </tr>
  </tbody>
</table>

4. In the **Login Experience** view, you can configure how users log in with this connection.

<table>
  <thead>
    <tr>
      <th><strong>Field</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Home Realm Discovery</strong></td>
      <td>Compares a user's email domain with the provided identity provider domains. For more information, read <a href="/docs/authenticate/login/auth0-universal-login/identifier-first">Configure Identifier First Authentication</a></td>
    </tr>

    <tr>
      <td><strong>Display connection button</strong></td>
      <td>This option displays the following choices to customize your application's connection button.</td>
    </tr>

    <tr>
      <td><strong>Button display name</strong> (Optional)</td>
      <td>Text used to customize the login button for Universal Login. When set the button reads: "Continue with \{Button display name}".</td>
    </tr>

    <tr>
      <td><strong>Button logo URL</strong> (Optional)</td>
      <td>URL of image used to customize the login button for Universal Login. When set, the Universal Login login button displays the image as a 20px by 20px square.</td>
    </tr>
  </tbody>
</table>

<Callout icon="file-lines">
  Optional fields are available with Universal Login only. Customers using Classic Login will not see the Add button, Button display name, or Button logo URL.
</Callout>

5. If you have appropriate Azure AD administrative permissions to give consent to the application so users can log in, then click **Continue**.
   You will be asked to [log in to your Azure AD account](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-permissions-and-consent#requesting-consent-for-an-entire-tenant) and give consent. Otherwise, provide the given URL to your administrator so that they can give consent.

### Enable the enterprise connection for your Auth0 application

To use your new Azure AD enterprise connection, you must first [enable the connection](/docs/authenticate/identity-providers/enterprise-identity-providers/enable-enterprise-connections) for your Auth0 Applications.

### Test the connection

Now you're ready to [test your connection](/docs/authenticate/identity-providers/enterprise-identity-providers/test-enterprise-connections).

## Troubleshooting

Here are some troubleshooting tips:

**I registered my application with Azure AD, but when I go back to my Azure Active Directory App registrations, I can't see my application.**

You may have accidentally registered your app in the wrong Azure AD directory (or not have created an Azure AD directory at all before registering your app). It's likely easiest to re-register your app in Azure AD. Make sure you are in the correct directory when you register the app. If you need to create an Azure AD directory, follow Microsoft's [Quickstart: Create a new tenant in Azure Active Directory - Create a new tenant for your organization](https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/active-directory-access-create-new-tenant#create-a-new-tenant-for-your-organization).

**I receive the following error message: "Access cannot be granted to this service because the service listing is not properly configured by the publisher".**

To resolve this, try changing the **Supported account types** for your registered Azure AD app. Make sure you have chosen an appropriate multitenant option in the Azure AD app's Authentication settings. Multitenant options include the following: **Accounts in any organizational directory (Any Azure AD directory - Multitenant)**.

**When users try to log in, we receive the following error message: "invalid\_request; failed to obtain <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>".**

The most likely reason for this error is an invalid or expired Azure AD **Client secret**. To resolve this, generate a new **Client secret** for your app in Azure AD, then update the **Client Secret** in the enterprise connection configured with Auth0.

## Signing Key Rollover in Azure AD

Signing keys are used by the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> to sign the authentication token it issues, and by the consumer application (Auth0 in this case) to validate the authenticity of the generated token.

For security purposes, Azure AD’s signing key [rolls on a periodic basis](https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-signing-key-rollover). If this happens, **you do not need to take any action**. Auth0 will use the new key automatically.

## Remove unverified label

If you're using a <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip>, the application consent prompt for Azure AD login may label your domain as "unverified". To remove the unverified label:

1. Verify the domain for the Auth0 application: [Add your custom domain name using the Azure Active Directory portal](https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/add-custom-domain#add-your-custom-domain-name-to-azure-ad).
2. Assign the verified domain to the Auth0 application: [How to: Configure an application's publisher domain](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-configure-publisher-domain#configure-publisher-domain-using-the-azure-portal).

## Next Steps

* [Integrate with Auth0 using one of our libraries](/docs/libraries)
* [Integrate with Auth0 using our Authentication API](https://auth0.com/docs/api/authentication)
* [Read more about the authentication flow](/docs/get-started/authentication-and-authorization-flow)
* [Pass additional parameters to the Identity Provider](/docs/authenticate/identity-providers/pass-parameters-to-idps)
* [Re-prompt users for permissions](/docs/authenticate/identity-providers/social-identity-providers/reprompt-permissions)


# Email Verification for Azure AD and ADFS
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/azuread-adfs-email-verification

Describes how to control how the `email_verified` field is set for Azure AD and ADFS.

Auth0 user's profile has an `email_verified` field, which can be set in different ways depending on the connection type. For database connections, users must go through an email validation flow to get the email verified. For federated connections, <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> can return the `email_verified` field based on their own criteria.

Azure AD and ADFS cannot guarantee that the emails they return have been verified:

* In ADFS, the ADFS administrator can configure any email they want.
* In Azure AD, depending on how the Azure AD tenant is configured, email addresses returned by Azure AD may or may not correspond to Office mailboxes. Auth0 can't know whether they do or not.

However, if you know how an Azure AD or ADFS is configured and managed, you can decide to trust that the emails from those accounts are verified.

To accommodate both needs, Azure AD and ADFS connections have an **Email Verification** property with two values:

* Always set `email_verified` to `true`
* Always set `email_verified` to `false`

The Azure AD connection also has a **Use Common Endpoint** property. When it's enabled, the user can authenticate with any Azure AD tenant. Given it's not possible to trust that any Azure AD tenant will return verified emails, the **Email Verification** property will need to be set to **Always set** `email_verified` **to** `false`.

When the property is set to **Always set** `email_verified` **to** `false`, users will get `email_verified` set to `false` the next time they log in, unless [syncing user profile attributes at each login](/docs/manage-users/user-accounts/user-profiles/configure-connection-sync-with-auth0) is disabled.

## Azure AD/ADFS Email Verification Migration setting

In previous versions, Auth0 always set the `email_verified` field to `true` in Azure AD and ADFS connections. If you were using Azure AD and ADFS connections in the past, you will have a tenant setting that will override the Connection Setting for **Email Verification** and keep the previous behavior.

You can find the new tenant setting in the [Auth0 Dashboard > Settings > Advanced](https://manage.auth0.com/#/tenant/advanced). Locate the **Migrations** section, then find **Default to** `Email Verification` **setting for Azure AD/ADFS connections**.

<Callout icon="file-lines">
  This setting is only available if:

  * the tenant is older than the date the migration was introduced
  * the tenant has one or more active ADFS or Azure AD connection
</Callout>

<Frame>
  <img alt="Dashboard - Advanced Tenant Settings - Migrations" />
</Frame>

When this setting is disabled, `email_verified` will always be `true` for Azure AD/ADFS connections. When enabled, it will use the `Email Verification` setting at the connection level.

## Email Verification Flow for Azure AD/ADFS connections

If your application requires that the emails from an Azure AD/ADFS connection's users are always verified, you can enable the **Enable email verification flow during login for Azure AD and ADFS connections** option in the tenant's **Advanced Settings** section.

After the user authenticates for the first time with a non-verified email, Auth0 will ask the user to verify their email by entering a one-time-use code that will be sent to their email account:

<Frame>
  <img alt="Auth0 - Email Verification Prompt - One-Time Code" />
</Frame>

If the user completes this step, the `email_verified` field will be set to `true`, and users will not be prompted again for email verification, unless Azure AD or ADFS return a different email for the user.

This new screen is rendered using the <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> experience, even if you are using Classic Login. To learn how to customize it, read [Customize Universal Login Pages](/docs/customize/login-pages/universal-login/customize-templates).

To learn how to customize the email that is sent to users, read [Verify Emails using Auth0](/docs/manage-users/user-accounts/verify-emails).

<Warning>
  When Azure AD does not return an `email` claim, Auth0 maps the [Azure UserPrincipalName](https://docs.microsoft.com/en-us/azure/active-directory/hybrid/plan-connect-userprincipalname) as the email. There is no guarantee that the `UserPrincipalName` value is a mailbox, so Auth0 will **not** display the email verification prompt and the user will have the field `email_verified` set to `false`.
</Warning>


# Choose a Connection Type for Azure AD
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/choose-a-connection-type-for-azure-ad

Describes Azure connection types and features.

You can connected your Auth0 instance to Microsoft Azure Active Directory in three ways. Review the options to determine the best approach for your situation.

Auth0 recommends starting with the native Microsoft Azure AD connection. If you need further customization, review the <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> connection configuration. Also, if your organization has additional restrictions on <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> code flows, review the Enterprise OIDC configuration.

The table below illustrates the main differences in these connection types. Review these capabilities to determine the best connection type for your organization.

<table>
  <thead>
    <tr>
      <th>Connection Type</th>
      <th>“Native” Azure AD</th>
      <th>Enterprise OIDC</th>
      <th>SAML</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Protocol</strong></td>
      <td>OAuth authorization code flow</td>
      <td>OAuth implicit flow OR OAuth authorization code flow</td>
      <td>SAML</td>
    </tr>

    <tr>
      <td><strong>Can receive optional claims from Azure AD?</strong></td>
      <td>No</td>
      <td>Yes</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td><strong>Federated logout support (“Single Logout” or SLO)</strong></td>
      <td>Yes</td>
      <td>No</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td><strong>Receive AD Groups</strong></td>
      <td>Yes, friendly names</td>
      <td>Yes, object IDs</td>
      <td>Yes, object IDs</td>
    </tr>

    <tr>
      <td><strong>Receive Extended Profile</strong></td>
      <td>Yes</td>
      <td>No</td>
      <td>No</td>
    </tr>
  </tbody>
</table>

## Microsoft Azure AD

The first connection type is the **Microsoft Azure AD** connection in [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/dashboard/#/connections/enterprise).

This connection type uses the OAuth authorization code flow. The Microsoft Azure AD connection accepts claims from an `id_token` and directly queries the Microsoft Graph API. If configured, the query searches for groups and additional profile information. Microsoft Azure AD ignores any custom claims included in the `id_token`.

### Connection features and considerations

Because this connection type is the native workflow, it is explicitly compatible with extended AD features. The Azure AD connection maps profile attributes directly to your Auth0 user profiles from the Microsoft Graph API.

The table below compares the Azure AD Graph Attributes across the connection types:

<table>
  <thead>
    <tr>
      <th><strong>Graph Attribute</strong></th>
      <th><strong>Auth0 Profile Attribute</strong></th>
      <th><strong>Data type</strong></th>
      <th><strong>Equivalent optional claim for OIDC or SAML</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>businessPhones</code></td>
      <td><code>phone</code></td>
      <td>array</td>
      <td>N/A</td>
    </tr>

    <tr>
      <td><code>givenName</code></td>
      <td><code>given\_name</code></td>
      <td>string</td>
      <td><code>given\_name</code></td>
    </tr>

    <tr>
      <td><code>jobTitle</code></td>
      <td><code>job\_title</code></td>
      <td>string</td>
      <td>N/A</td>
    </tr>

    <tr>
      <td><code>mobilePhone</code></td>
      <td><code>mobile</code></td>
      <td>string</td>
      <td>N/A</td>
    </tr>

    <tr>
      <td><code>preferredLanguage</code></td>
      <td><code>preferred\_language</code></td>
      <td>string</td>
      <td><code>xms\_pl</code></td>
    </tr>

    <tr>
      <td><code>surname</code></td>
      <td><code>family\_name</code></td>
      <td>string</td>
      <td><code>family\_name</code></td>
    </tr>

    <tr>
      <td><code>userPrincipalName</code></td>
      <td><code>upn</code></td>
      <td>string</td>
      <td><code>upn</code></td>
    </tr>
  </tbody>
</table>

You must [enable permission to query the Microsoft Graph API](/docs/authenticate/identity-providers/enterprise-identity-providers/azure-active-directory/v2#add-permissions) to receive the following extended profile attributes:

* `businessPhones`
* `jobTitle`
* `mobilePhone`

### Group Configuration

If you [enable permission to query the Microsoft Graph API](/docs/authenticate/identity-providers/enterprise-identity-providers/azure-active-directory/v2#add-permissions), Auth0 automatically retrieves groups for the user and maps these to the `groups` attribute in the Auth0 profile. Auth0 maps these group "friendly names" and does not need to configure a custom claim because these groups map directly from the Microsoft Graph API.

## SAML

The SAML connection type uses the SAML protocol and supports attribute mapping and all standard SAML features.

### Connection features and considerations

The SAML connection type is the most flexible of the available connection types because it supports optional claims and [federated logouts](https://docs.microsoft.com/en-us/azure/active-directory/develop/single-sign-out-saml-protocol). If you need both of these features, SAML is the only connection type that supports both simultaneously.

### Group configuration

For Auth0 to accept group information with the SAML connection type, you must configure your Azure AD with optional attributes in the SAML response. Auth0 then maps the groups to the `group_ids` attribute in the user's Auth0 profile.

<Callout icon="file-lines">
  The SAML and OIDC connection types use object identifiers rather than friendly names for groups. You may be able to get friendly names into a SAML response if you have imported groups from on-premises AD. To learn more about group claims, visit [the Microsoft Documentation.](https://docs.microsoft.com/en-us/azure/active-directory/hybrid/how-to-connect-fed-group-claims)
</Callout>

## Enterprise OIDC

The Enterprise Open ID Connect type can use either OAuth Implicit or Authorization Code workflows. This connection maps custom claims in the `id_token` to the Auth0 User Profile. To learn more about authentication flows, visit the [Authentication and Authorization Flows documentation](/docs/get-started/authentication-and-authorization-flow).

### Connection features and considerations

If you cannot provide <Tooltip href="/docs/glossary?term=client+secrets">client secrets</Tooltip> in your login flow due to regulations or privacy protocols, the Implicit Flow the OIDC connection offers could be a preferred method. If you require custom claims but do not want to configure the additional SAML features, the OIDC connection can reduce complexity.

### Group configuration

For Auth0 to accept group information with the OIDC connection type, you must configure your Azure AD with an optional claim to add `groups` in the `id_token` of your request. Auth0 then maps these groups to the `group_ids` attribute in the user’s Auth0 profile.

<Callout icon="file-lines">
  The SAML and OIDC connection types use object identifiers rather than friendly names for groups. You may be able to get friendly names into a SAML response if you have imported groups from on-premises AD. To learn more about group claims, visit [the Microsoft Documentation.](https://docs.microsoft.com/en-us/azure/active-directory/hybrid/how-to-connect-fed-group-claims)
</Callout>

## Learn more

* [Connect Your App to Microsoft Azure Active Directory](/docs/authenticate/identity-providers/enterprise-identity-providers/azure-active-directory/v2)


# Configure PKCE and Claim Mapping for OIDC Connections
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/configure-pkce-claim-mapping-for-oidc

Configure Proof Key for Code Exchange (PKCE) and mapping templates for OpenID Connect and Okta Workforce connections.

Enterprise connections using [OpenID Connect](/docs/authenticate/identity-providers/enterprise-identity-providers/oidc) or O[kta Workforce](/docs/authenticate/identity-providers/enterprise-identity-providers/okta) as the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> can support Proof Key for Code Exchange (PKCE), as well as attribute and token mapping.

## Configure PKCE for OIDC connections

<Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect and Okta Workforce connections are automatically configured to support Proof Key for Code Exchange (PKCE).

If your OIDC identity provider (IdP) supports PKCE through OIDC Discovery metadata, Auth0 will use the strongest algorithm available by default. For more information on OIDC Discovery metadata, review [OpenID’s documentation](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata).

### View PKCE configuration for a connection

You can view the PKCE configuration for a specific connection through the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>:

1. Navigate to **Authentication > Enterprise** and choose your OIDC provider (either OpenID Connect or Okta Workforce).
2. Select the **Settings** tab.
3. In the **General** section, locate the **Connection Profile** field.

<Tabs>
  <Tab title="Auth0 Dashboard">
    You can manage the PKCE configuration for a connection through the Auth0 Dashboard:

    1. Navigate to [**Dashboard > Authenticate >Enterprise**](https://manage.auth0.com/#/connections/enterprise) and choose your OIDC provider (either OpenID Connect or Okta Workforce).
    2. Select the **Settings** tab and locate the **Connection Profile** field.
    3. Set the `pkce` property to one of the [supported values](#supported-pkce-configuration-values) listed below.
    4. Select **Save**.
  </Tab>

  <Tab title="Management API">
    #### Use discovery endpoint

    export const codeExample1 = `curl --request POST \     --url 'https://{yourDomain}/api/v2/connections' \     --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \     --data '{ 
          "strategy": "oidc", 
           "name": "CONNECTION_NAME", 
           "options": { 
             "type": "back_channel", 
             "discovery_url": "https://IDP_DOMAIN/.well-known/openid-configuration", 
             "client_id" : "IDP_CLIENT_ID", 
             "client_secret" : "IDP_CLIENT_SECRET", 
             "scopes": "openid profile", 
             "connection_settings": { "pkce": "auto" }
                       } 
                  }'`;

    <AuthCodeBlock />

    #### Without discovery endpoint

    Without a `discovery_url` the `oidc_metadata` object needs to be populated manually with the necessary fields.

    export const codeExample2 = `curl --request POST \       --url 'https://{yourDomain}/api/v2/connections' \       --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \       --data '{
            "strategy": "oidc",
            "name": "CONNECTION_NAME",
            "options": {
              "type": "back_channel",
              "client_id": "IDP_CLIENT_ID",
              "client_secret": "IDP_CLIENT_SECRET",
              "connection_settings": { "pkce": "auto" },
              "issuer": "https://IDP_DOMAIN",
              "authorization_endpoint": "https://IDP_DOMAIN/authorize",
              "jwks_uri": "https://IDP_DOMAIN/.well-known/jwks.json",
              "scopes": "openid profile",
              "oidc_metadata": {
                "issuer": "https://IDP_DOMAIN",
                "authorization_endpoint": "https://IDP_DOMAIN/authorize",
                "jwks_uri": "https://IDP_DOMAIN/.well-known/jwks.json",
                "token_endpoint": "https://IDP_DOMAIN/token/refresh",
                "code_challenge_methods_supported": ["plain", "S256"]
              }
            }
          }'`;

    <AuthCodeBlock />
  </Tab>
</Tabs>

### Supported PKCE configuration values

Auth0 supports the following values for PKCE configuration:

<table>
  <thead>
    <tr>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>auto</code></td>
      <td>Default value. Uses the strongest algorithm available.</td>
    </tr>

    <tr>
      <td><code>s256</code></td>
      <td>Uses the SHA-256 algorithm. Auth0 does not currently support RS512 tokens.</td>
    </tr>

    <tr>
      <td><code>plain</code></td>
      <td>Uses plaintext as described in the <a href="https://www.rfc-editor.org/rfc/rfc7636#section-4.2" title="Proof Key for Code Exchange by OAuth Public Clients - Code Challenge">PKCE specification</a>.</td>
    </tr>

    <tr>
      <td><code>disabled</code></td>
      <td>Disables support for PKCE.</td>
    </tr>
  </tbody>
</table>

<Warning>
  Setting the `pkce` property to a value other than `auto`may prevent a connection from working properly if the selected value is not supported by the identity provider.

  Do not set the property to `disabled` except when troubleshooting authentication issues.
</Warning>

<Callout icon="file-lines">
  **Azure AD Limitation**

  If you are using an OpenID Connect connection for Azure AD, you must set `pkce` to `s256` as the connection's metadata does not expose the hashing algorithm used. Currently, the [Azure AD Enterprise connection](/docs/authenticate/identity-providers/enterprise-identity-providers/azure-active-directory/v2) does not support PKCE.
</Callout>

## Map Claims for OIDC connections

OpenID Connect and Okta Workforce connections can automatically map claims received from the identity provider (IdP). You can configure this mapping through a library template provided by Auth0 or by entering your own template directly.

<Callout icon="file-lines">
  Mapped claims are not automatically added to an Auth0 ID token. To add claims to an ID token, see [Create custom claims](/docs/secure/tokens/json-web-tokens/create-custom-claims#create-custom-claims).
</Callout>

### Mapping template properties

Mapping templates support the `options.attribute_map` object properties listed below. Templates must be in JSON format with valid key/value pairs.

<table>
  <thead>
    <tr>
      <th><strong>Property</strong></th>
      <th><strong>Required?</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>mapping\_mode</code></td>
      <td>Required</td>
      <td>Method used to map incoming claims.</td>
    </tr>

    <tr>
      <td><code>userinfo\_scope</code></td>
      <td>Optional</td>
      <td>Scopes to send to the IdP's Userinfo endpoint.</td>
    </tr>

    <tr>
      <td><code>attributes</code></td>
      <td>Required</td>
      <td>Object containing mapping details for incoming claims.</td>
    </tr>
  </tbody>
</table>

### Mapping mode

The `mapping_mode` property defines the method used to map incoming claims from the IdP to the Auth0 user profile. `mapping_mode` supports the following values:

<table>
  <thead>
    <tr>
      <th><strong>Value</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>use\_map</code></td>
      <td>Uses the provided template to map the data.</td>
    </tr>

    <tr>
      <td><code>bind\_all</code></td>
      <td>Copies all data elements provided by the IdP.</td>
    </tr>
  </tbody>
</table>

#### Restricted claims

Some claims are reserved for use by Auth0; such claims cannot be used as attribute keys for user profiles.

If you set the `mapping_mode` property to `bind_all`, your IdP may attempt to map values to one or more of these restricted claims. While this does not prevent users from authenticating on your connection, values associated with restricted claims are **not** mapped to the Auth0 user profile.

If you set `mapping_mode` to `use_map`, you can map the incoming restricted claim to a valid one:

```json lines theme={null}
"attribute_map": {
        "mapping_mode": "use_map",
        "attributes": {
            "amr": "{context.tokenset.amr}", // `amr` is a restricted claim and will not be mapped
            "federated_amr": "{context.tokenset.amr}" // `federated_amr` is not a restricted claim and will be mapped
        }
    }
```

For a complete list of restricted claims, review [Create Custom Claims](/docs/secure/tokens/json-web-tokens/create-custom-claims).

### UserInfo scope

The `userinfo_scope` property defines the scopes that Auth0 sends to the IdP’s UserInfo endpoint when requested.

For example, if you want to send the standard OIDC scopes and the `groups` scope when requesting the UserInfo endpoint, you can do so as follows:

```json lines theme={null}
"attribute_map": {
    . . .
    "mapping_mode": "bind_all",
    "userinfo_scope": "openid email profile groups",
    . . .
}
```

### Attributes

The `attributes` property is an object containing mapping information that allows Auth0 to interpret incoming claims from the IdP. Mapping information must be provided as key/value pairs.

The key to the left corresponds to an Auth0 user profile attribute. The value to the right represents the incoming claim from the IdP, which can be expressed as a literal value, a dynamic context object, or a combination of both. Dynamic context objects are template expressions written in the familiar `${variable}` format.

```json lines theme={null}
"attribute_map": {
    . . .
    "attributes": {
        "name": "${context.tokenset.name}",
        "email": "${context.tokenset.email}",
        "username": "${context.tokenset.preferred_username}"
    }
}
```

#### Literal values

A literal value is a static value mapped to a specific profile attribute for all users on your connection.

For example, if you are configuring a SalesForce OIDC connection and want to assign the same SFDC Community ID to all user profiles, you can do so as follows:

```json lines theme={null}
"attribute_map": {
    . . .
    "attributes": {
        …
        "sf_community_id": "3423409219032-32"
    }
}
```

#### Context object

You can map dynamic values to user profile attributes by using the `context` object. This allows you to store unique values for individual profiles, as opposed to literal values that are static across all profiles.

The `context` object supports the following properties:

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>context.connection</code></td>
      <td>Contains the following properties:<br /><br /><li> <code>id</code>: The connection’s unique identifier (for example, <code>con\_4423423423432423</code>).</li><br /><li> <code>strategy</code>: The connection’s strategy (for example, <code>oidc</code>).</li></td>
    </tr>

    <tr>
      <td><code>context.tokenset</code></td>
      <td>Contains the following properties:<br /><br /><li> <code>access\_token</code>: The entire validated access token sent by the IdP.</li><br /><li><code>\<claim name></code>: Any ID token claim sent by the IdP.</li></td>
    </tr>

    <tr>
      <td><code>context.userinfo</code></td>
      <td>Contains the following properties:<br /><br /><li> <code>\<claim name></code>: Any available claim provided by the IdP’s UserInfo endpoint.</li></td>
    </tr>
  </tbody>
</table>

### Examples

#### Simple user claim mapping

This example demonstrates how to map common user claims to the Auth0 user profile with data from the <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip>:

```json lines theme={null}
"attribute_map": {
    . . .
    "attributes": {
        "name": "${context.tokenset.name}",
        "email": "${context.tokenset.email}",
        "username": "${context.tokenset.preferred_username}"
    }
}
```

#### Group claim mapping

This example shows how to map groups to the Auth0 user profile from the incoming IdP:

```json lines theme={null}
"attribute_map": {
    . . .
    "attributes": {
        "federated_groups": "${context.userinfo.groups}",
        "federated_locale": "${context.userinfo.locale}",
        "federated_zoneinfo": "${context.userinfo.zoneinfo}"
    }
}
```

#### Combining literal values and context objects

This example demonstrates how to combine literal values and dynamic template expressions to map a complex value to an attribute on the Auth0 user profile:

```json lines theme={null}
"attribute_map":{
    . . .
    "attributes": {
        "alt_id": "user_email|${context.tokenset.email}",
        . . .
    }
}
```


# Enable Enterprise Connections
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/enable-enterprise-connections

Describes how to enable enterprise connections for applications using the Auth0 Dashboard.

You can enable enterprise connections for applications using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. To enable your enterprise connection, you should have already set it up.

1. Go to [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise), and select the connection type to view.

   <Frame>
     <img alt="Dashboard - Connections - Enterprise" />
   </Frame>
2. Select the name of the connection to view.

   <Frame>
     <img alt="Dashboard - Connections - Enterprise - AD/LDAP - List" />
   </Frame>
3. Select the **Applications** view, and enable or disable the connection for the appropriate application(s).

   <Frame>
     <img alt="Dashboard - Connections - Enterprise - Applications" />
   </Frame>

When you set up your enterprise <Tooltip href="/docs/glossary?term=IdP">IdP</Tooltip> connection, remember that the `connection` parameter passed to Auth0's `/authorize,` `/whr,` or `/wsfed` endpoint will redirect to the upstream IdP **unless** it's connected via database or Active Directory.

## Learn more

* [Test Enterprise Connections](/docs/authenticate/identity-providers/enterprise-identity-providers/test-enterprise-connections)


# Connect Your App to Google Workspace
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/google-apps

Learn how to connect your app to Google Workspace using an enterprise connection.

<Card title="Using Google Social and Enterprise Connections">
  If you have an existing [Google Social Connection](https://marketplace.auth0.com/integrations/google-social-connection) for your application and you create a new Google Workspace connection for the same domain, users affiliated with the social connection with now be logged in with the new enterprise connection. This will occur regardless of whether you enable the Google Workspace enterprise connection.
</Card>

## Prerequisites

Before you begin:

* [Register your Application with Auth0](/docs/get-started/auth0-overview/create-applications).

  * Select an appropriate **Application Type**.
  * Add an **Allowed Callback URL** of **`{https://yourApp/callback}`**.
  * Make sure your Application's [Grant Types](/docs/get-started/applications/update-grant-types) include the appropriate flows.

## Steps

To connect your application to Google Workspace, you must:

1. [Set up your app in Google](#set-up-your-app-in-google)
2. [Create an enterprise connection in Auth0](#create-an-enterprise-connection-in-auth0)
3. [Enable the enterprise connection for your Auth0 Application](#enable-the-enterprise-connection-for-your-auth0-application)
4. [Test the connection](#test-the-connection)

<Card title="Google Workspace account">
  Before proceeding, you will need a valid Google Workspace account and must have **your own** Google Workspace Organization for which you are an administrator.
</Card>

## Set up your app in Google

To allow users to log in using Google Workspace, you must register your application in the Google Cloud console.

<Warning>
  Before proceeding, you must have already set up **your own** Google Workspace Organization for which you are an administrator.
</Warning>

### Register a new application

To learn how to register a new application with Google, follow Google's [Setting up OAuth 2.0](https://support.google.com/googleapi/answer/6158849) doc. During this process, Google will generate a **<Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>** and **<Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip>** for your application; make note of these.

While setting up your app, be sure to use these settings:

* On the **<Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> consent screen**, under **Authorized domains**, add `auth0.com`.
* When asked to select an application type, choose **Web application** and set the following parameters:

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Name</td>
      <td>The name of your application.</td>
    </tr>

    <tr>
      <td>Authorized JavaScript origins</td>
      <td>`https://{yourDomain}`</td>
    </tr>

    <tr>
      <td>Authorized redirect URIs</td>
      <td>`https://{yourDomain}/login/callback`</td>
    </tr>
  </tbody>
</table>

<Card title="Find your Auth0 domain name for redirects">
  If your Auth0 domain name is not shown above and you are not using our [custom domains](/docs/customize/custom-domains) feature, your domain name is a concatenation of your tenant name, your regional subdomain, and `auth0.com`, separated by the dot (`.`) symbol.

  For example, if your tenant name is `exampleco-enterprises`, and your tenant is in the US region, your Auth0 domain name would be `exampleco-enterprises.us.auth0.com` and your **Redirect URI** would be `https://exampleco-enterprises.us.auth0.com/login/callback`.

  However, if your tenant is in the US region and was created before June 2020, then your Auth0 domain name would be `exampleco-enterprises.auth0.com` and your **Redirect URI** would be `https://exampleco-enterprises.auth0.com/login/callback`.

  If you are using [custom domains](/docs/customize/custom-domains), your **Redirect URI** would be `https://<YOUR CUSTOM DOMAIN>/login/callback`.
</Card>

<Warning>
  If your application requests sensitive OAuth scopes, it may be [subject to review by Google](https://developers.google.com/apps-script/guides/client-verification).
</Warning>

### Enable the Admin SDK API

If you plan to connect to Google Workspace enterprise domains, you need to enable the **Admin SDK API**. To learn how, follow Google's [Enable and disable APIs](https://support.google.com/googleapi/answer/6158841) doc.

## Create an enterprise connection in Auth0

<Warning>
  The Google Enterprise connection allows Auth0 user profiles to have up to 200 groups. If a user profile has more than 200 groups, these results may not be shown.

  Google Workspace does not enforce group name uniqueness. To access extended group properties, such as unique IDs and email addresses, review the [Using Identity Provider Tokens from Google](#use-identity-provider-tokens-from-google) section below. If you use Google groups for authorization, you must secure the workspace to prevent unauthorized users from modifying groups.
</Warning>

Next, you will need to create and configure a Google Workspace Enterprise Connection in Auth0. Make sure you have the **Client ID** and **Client Secret** generated when you set up your app in the Google Cloud console.

1. Navigate to [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise), locate **Google Workspace**, and click its `+`.

   <Frame>
     <img alt="Dashboard - Connections - Enterprise" />
   </Frame>
2. Enter details for your connection, and select **Create:**

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Connection name</strong></td>
      <td>Logical identifier for your connection; it must be unique for your tenant. Once set, this name can't be changed.</td>
    </tr>

    <tr>
      <td><strong>Google Workspace Domain</strong></td>
      <td>Google Workspace domain name for your organization.</td>
    </tr>

    <tr>
      <td><strong>Client ID</strong></td>
      <td>Unique identifier for your registered Google application. Enter the saved value of the <strong>Client ID</strong> for the app you just registered in the Google Cloud console.</td>
    </tr>

    <tr>
      <td><strong>Client Secret</strong></td>
      <td>String used to gain access to your registered Google application. Enter the saved value of the <strong>Client Secret</strong> for the app you just registered in the Google Cloud console.</td>
    </tr>

    <tr>
      <td><strong>Attributes</strong></td>
      <td>Basic attributes for the signed-in user that your app can access. Indicates how much information you want stored in the Auth0 User Profile. Options include: <strong>Basic Profile</strong> (<code>email</code>, <code>email verified</code> flag) and <strong>Extended Profile</strong> (name, public profile URL, photo, gender, birthdate, country, language, and timezone).</td>
    </tr>

    <tr>
      <td><strong>Extended Attributes</strong> (optional)</td>
      <td>Extended attributes for the signed-in user that your app can access. Options include: <strong>Groups</strong> (distribution list(s) to which the user belongs, including the Extended Group Attributes Format option that retrieves the group name, group email address, and the unique group ID), <strong>Is Domain Administrator</strong> (indicates whether the user is a domain administrator), <strong>Is Account Suspended</strong> (indicates whether the user's account is suspended), and <strong>Agreed to Terms</strong> (indicates whether the user has agreed to the terms of service).</td>
    </tr>

    <tr>
      <td><strong>Auth0 APIs</strong> (optional)</td>
      <td>When <strong>Enable Users API</strong> is selected, indicates that you require the ability to make calls to the Google Directory API.</td>
    </tr>

    <tr>
      <td><strong>Auth0 User ID</strong> (optional)</td>
      <td>By default, the Auth0 <code>user\_id</code> maps to <code>email</code>. By enabling <strong>Use ID instead of Email for Auth0 User ID</strong>, <code>user\_id</code> instead maps to <code>id</code>. This can only be set for new connections and cannot be changed once configured.</td>
    </tr>

    <tr>
      <td><strong>Sync user profile attributes at each login</strong></td>
      <td>When enabled, Auth0 automatically syncs user profile data with each user login, thereby ensuring that changes made in the connection source are automatically updated in Auth0.</td>
    </tr>

    <tr>
      <td><strong>Purpose</strong></td>
      <td>Enable the connection for Authentication, Connected Accounts for Token Vault, or both. To learn more, read [User authentication vs Connected Accounts](/docs/secure/tokens/token-vault/connected-accounts-for-token-vault#user-authentication-vs-connected-accounts).</td>
    </tr>
  </tbody>
</table>

3. If you have appropriate administrative permissions to configure your Google Workspace settings so you can use Google's Admin APIs, then click **Continue**. Otherwise, provide the given URL to your administrator so that they can adjust the required settings.
4. On the **Login Experience** tab, you can configure how users log in with this connection.

<table>
  <thead>
    <tr>
      <th><strong>Field</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Home Realm Discovery</strong></td>
      <td>Compares a user's email domain with the provided identity provider domains. For more information, read <a href="/docs/authenticate/login/auth0-universal-login/identifier-first">Configure Identifier First Authentication</a></td>
    </tr>

    <tr>
      <td><strong>Display connection button</strong></td>
      <td>This option displays the following choices to customize your application's connection button.</td>
    </tr>

    <tr>
      <td><strong>Button display name</strong> (Optional)</td>
      <td>Text used to customize the login button for Universal Login. When set the button reads: "Continue with \{Button display name}".</td>
    </tr>

    <tr>
      <td><strong>Button logo URL</strong> (Optional)</td>
      <td>URL of image used to customize the login button for Universal Login. When set, the Universal Login login button displays the image as a 20px by 20px square.</td>
    </tr>
  </tbody>
</table>

<Callout icon="file-lines">
  Optional fields are available with Universal Login only. Customers using Classic Login will not see the Add button, Button display name, or Button logo URL.
</Callout>

## Work with the connection

### Enable the enterprise connection for your Auth0 application

To use your new AD connection, you must first [enable the connection](/docs/authenticate/identity-providers/enterprise-identity-providers/enable-enterprise-connections) for your Auth0 Applications.

### Test the connection

Now you're ready to [test your connection](/docs/authenticate/identity-providers/enterprise-identity-providers/test-enterprise-connections).

### Request Refresh Tokens from Google

Google always returns an <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, which is stored in the user profile. If you add `access_type=offline&approval_prompt=force` to the authorization request, Auth0 will forward these parameters to Google. Google will then return a <Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip>, which will also be stored in the user profile.

### Use Identity Provider Tokens from Google

To retrieve additional user and group details beyond what Auth0 retrieves by default, you can use the access tokens returned from Google to call Google's APIs. To securely access these tokens, follow the guidelines provided in [Identity Provider Access Tokens](/docs/secure/tokens/access-tokens/identity-provider-access-tokens).

For Google Workspace, Auth0 stores access tokens and refresh tokens on the `user` object for individual users and on the `connection` object for workspace admins.

To retrieve all extended group properties for a user with Google's Directory Admin API, navigate to the Goolgle Workspace connection in your [Auth0 Dashboard](https://manage.auth0.com/#/connections/enterprise) and enable the **Groups** extended attribute. Then, complete administrator consent using the **Setup** tab.

After these steps are complete, use the [Get a connection](https://auth0.com/docs/api/management/v2/connections/get-connections-by-id) endpoint of the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to retrieve the admin access token stored on the `connection` object. You can then use this token to call Google's [Manage Groups](https://developers.google.com/admin-sdk/directory/v1/guides/manage-groups#get_all_member_groups) endpoint.

**Example call**:

```bash wrap lines theme={null}
curl -H "Authorization: OAuth {admin_access_token}" https://admin.googleapis.com/admin/directory/v1/groups\?userKey={user_key}
```

### Validate authentication with Actions

You can use `post-login` [Actions](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) to validate whether authentication events are coming from legitimate users who are members of a Google organization. This can help mitigate potential vulnerability by preventing unauthorized access to your applications after users are no longer part of your organization.

To verify legitimate Google authentications, use `post-login` Actions to validate the `idp_tenant_domain` claim associated with the user and ensure the value matches the expected organization for that user.

You can only verify `idp_tenant_domain` for users who authenticate with the following connection types:

* Google Social
* Google Workspace
* Google OIDC

#### Example

The following example demonstrates how you can validate the `idp_tenant_domain` using `post-login` Actions.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {

 // Example to block social accounts
 if (event.connection.strategy === 'google-oauth2' 
 && !event.user.idp_tenant_domain) // Non-organization Accounts
 {
   api.access.deny('Account not allowed for login');
 }

 // Example to only permit allowlisted organization accounts
 if (event.connection.strategy === 'google-oauth2' 
 && event.user.idp_tenant_domain != "allowedOrganization.com") 
 {
   api.access.deny('Your Google Organization is not allowed to login');
 }

};
```

### Sync users from Google Workspace to Auth0 with Directory Sync

Auth0 supports using the Google Directory Sync to create and update Auth0 users from your Google Workspace directory rather than relying on user login to refresh user profiles. To learn how, read [Sync Google Workspace Users to Auth0 with Directory Sync](/docs/authenticate/identity-providers/enterprise-identity-providers/google-directory-sync).

### Reauthorize existing connections

If a Google Workspace admin is deleted, any Google Workspace Enterprise connections they have set up and authorized will need to be reauthorized by a new Google Workspace admin to avoid login failures. This can be done by having the new admin use the link in the **Setup** tab for the Google Workspace Enterprise connection.

## Next Steps

* [Integrate with Auth0 using one of our libraries](/docs/libraries)
* [Integrate with Auth0 using our Authentication API](https://auth0.com/docs/api/authentication)
* [Read more about the authentication flow](/docs/get-started/authentication-and-authorization-flow)
* [Pass additional parameters to the Identity Provider](/docs/authenticate/identity-providers/pass-parameters-to-idps)
* [Re-prompt users for permissions](/docs/authenticate/identity-providers/social-identity-providers/reprompt-permissions)


# Sync Google Workspace Users to Auth0 with Directory Sync
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/google-directory-sync

Learn how to use Directory Sync to update user profiles in Auth0 from Google Workspace.

## Prerequisites

Before you begin:

* [Create an Enterprise connection for Google Workspace](/docs/authenticate/identity-providers/enterprise-identity-providers/google-apps).
  * Select **Enable Users API** on the connection under Auth0 APIs in the connection settings.
  * Google Workspace domain admin completes authorization for Auth0 to access the Google Workspace Users API.

## Steps

To set up Google Workspace Directory Sync:

1. [Create or update a Google Workspace enterprise connection](/docs/authenticate/enterprise-connections).
2. [Enable Directory Sync for the connection in Auth0 Dashboard or Management API](/docs/authenticate/identity-providers/enterprise-identity-providers/google-directory-sync#enable-directory-sync).
3. [Enable automated sync, or run a manual one-time sync on-demand](/docs/authenticate/identity-providers/enterprise-identity-providers/google-directory-sync#run-a-manual-sync).

## Enable Directory Sync

Use Auth0 Dashboard or the Management API to enable Directory Sync with your Google Workspace connection.

<Tabs>
  <Tab title="Auth0 Dashboard">
    1. Navigate to [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise).
    2. [Create an enterprise connection](/docs/authenticate/identity-providers/enterprise-identity-providers/google-apps#create-an-enterprise-connection-in-auth0) or open your existing Google Workspace connection.
    3. Select **Enable Users API** under **General** when creating a new connection or on the **Settings** tab of an existing connection.<br />
       A. Save your changes.<br />
       B. Complete administrator consent under the **Setup** tab to authorize Google Workspace.
    4. Select the **Provisioning** tab.
    5. Toggle on **Provision Users Using Directory Sync**.
    6. Configure:<br />
       A. **Attribute Mapping** to control which Google attributes are written into the Auth0 user profile.<br />
       B. **Enable Automated Synchronizations** to run the sync automatically.
    7. Save your changes.
    8. To run an on-demand sync, choose **Synchronize Now**.
  </Tab>

  <Tab title="Management API">
    <Card title="Before you start">
      To call Management API, you need:

      * A [Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens#management-api-access-tokens) with the following scopes:
        * `create:directory_provisionings`
        * `read:directory_provisionings`
        * `update:directory_provisionings`
        * `delete:directory_provisionings`
      * Your Google Workspace connection ID (`CONNECTION_ID`).
    </Card>

    ## Create or enable Directory Sync for the connection

    Call the [Create a directory provisioning configuration](https://auth0.com/docs/api/management/v2/connections/post-directory-provisioning) endpoint.

    ```bash theme={null}
    https://{{YOUR_AUTH0_DOMAIN}}/api/v2/connections/{{CONNECTION-ID}} /directory-provisioning
    ```

    Example request body to enable automatic sync:

    ```json tsx wrap lines expandable theme={null}
    {
        "mapping": [
            {
                "idp": "id",
                "auth0": "id"
            },
            {
                "idp": "primaryEmail",
                "auth0": "email"
            },
            {
                "idp": "primaryEmail",
                "auth0": "primaryEmail"
            },
            {
                "idp": "name.fullName",
                "auth0": "name"
            },
            {
                "idp": "name.givenName",
                "auth0": "given_name"
            },
            {
                "idp": "name.familyName",
                "auth0": "family_name"
            },
            {
                "idp": "isAdmin",
                "auth0": "isAdmin"
            },
            {
                "idp": "isAdmin",
                "auth0": "is_admin"
            },
            {
                "idp": "isDelegatedAdmin",
                "auth0": "isDelegatedAdmin"
            },
            {
                "idp": "agreedToTerms",
                "auth0": "agreedToTerms"
            },
            {
                "idp": "agreedToTerms",
                "auth0": "tou_accepted"
            },
            {
                "idp": "suspended",
                "auth0": "suspended"
            },
            {
                "idp": "suspended",
                "auth0": "is_suspended"
            },
            {
                "idp": "suspended",
                "auth0": "blocked"
            },
            {
                "idp": "suspensionReason",
                "auth0": "suspensionReason"
            },
            {
                "idp": "archived",
                "auth0": "archived"
            },
            {
                "idp": "ipWhitelisted",
                "auth0": "ipWhitelisted"
            },
            {
                "idp": "ipWhitelisted",
                "auth0": "is_ipWhitelisted"
            },
            {
                "idp": "kind",
                "auth0": "kind"
            },
            {
                "idp": "etag",
                "auth0": "etag"
            },
            {
                "idp": "customerId",
                "auth0": "customerId"
            },
            {
                "idp": "orgUnitPath",
                "auth0": "orgUnitPath"
            },
            {
                "idp": "emails",
                "auth0": "emails"
            },
            {
                "idp": "phones",
                "auth0": "phones"
            },
            {
                "idp": "externalIds",
                "auth0": "externalIds"
            },
            {
                "idp": "aliases",
                "auth0": "aliases"
            },
            {
                "idp": "addresses",
                "auth0": "addresses"
            },
            {
                "idp": "organizations",
                "auth0": "organizations"
            },
            {
                "idp": "nonEditableAliases",
                "auth0": "nonEditableAliases"
            },
            {
                "idp": "relations",
                "auth0": "relations"
            },
            {
                "idp": "languages",
                "auth0": "languages"
            },
            {
                "idp": "posixAccounts",
                "auth0": "posixAccounts"
            },
            {
                "idp": "notes",
                "auth0": "notes"
            },
            {
                "idp": "websites",
                "auth0": "websites"
            },
            {
                "idp": "locations",
                "auth0": "locations"
            },
            {
                "idp": "keywords",
                "auth0": "keywords"
            },
            {
                "idp": "gender",
                "auth0": "gender"
            },
            {
                "idp": "ims",
                "auth0": "ims"
            },
            {
                "idp": "creationTime",
                "auth0": "creationTime"
            },
            {
                "idp": "lastLoginTime",
                "auth0": "lastLoginTime"
            },
            {
                "idp": "changePasswordAtNextLogin",
                "auth0": "changePasswordAtNextLogin"
            },
            {
                "idp": "isMailboxSetup",
                "auth0": "isMailboxSetup"
            },
            {
                "idp": "includeInGlobalAddressList",
                "auth0": "includeInGlobalAddressList"
            },
            {
                "idp": "thumbnailPhotoUrl",
                "auth0": "thumbnailPhotoUrl"
            },
            {
                "idp": "thumbnailPhotoEtag",
                "auth0": "thumbnailPhotoEtag"
            },
            {
                "idp": "isEnrolledIn2Sv",
                "auth0": "isEnrolledIn2Sv"
            },
            {
                "idp": "isEnforcedIn2Sv",
                "auth0": "isEnforcedIn2Sv"
            },
            {
                "idp": "recoveryEmail",
                "auth0": "recoveryEmail"
            },
            {
                "idp": "recoveryPhone",
                "auth0": "recoveryPhone"
            },
            {
                "idp": "sshPublicKeys",
                "auth0": "sshPublicKeys"
            },
            {
                "idp": "customSchemas",
                "auth0": "customSchemas"
            },
     {
                "idp": "id",
                "auth0": "app_metadata.externalId"
            },
        ],
        "synchronize_automatically": true
    }
    ```

    ## Verify or update an existing configuration

    To read the configuration settings, call [Get a directory provisioning configuration](https://auth0.com/docs/api/management/v2/connections/get-directory-provisioning)

    ```bash theme={null}
    GET https://{{YOUR_AUTH0_DOMAIN}}/api/v2/connections/{{CONNECTION-ID}} /directory-provisioning
    ```

    To update the connection configuration, call [Patch a directory provisioning configuration](https://auth0.com/docs/api/management/v2/connections/patch-directory-provisioning).

    ```bash theme={null}
    PATCH https://{{YOUR_AUTH0_DOMAIN}}/api/v2/connections/{{CONNECTION-ID}} /directory-provisioning
    ```

    Example request body (disable automatic sync)

    ```json theme={null}
    {
    	"synchronize_automatically": false
    }
    ```

    ## Run a manual sync

    To trigger an on-demand sync, call [Create a directory provisioning configuration](https://auth0.com/docs/api/management/v2/connections/post-synchronizations).

    ```bash theme={null}
    POST https://{{YOUR_AUTH0_DOMAIN}}/api/v2/connections/{{CONNECTION-ID}} /directory-provisioning/synchronizations
    ```

    ## Disable Directory Sync

    To disable Directory Sync for the connection, call [Delete a directory provisioning configuration](https://auth0.com/docs/api/management/v2/connections/delete-directory-provisioning).

    ```bash theme={null}
    DELETE https:// {{YOUR_AUTH0_DOMAIN}} /api/v2/connections/ {{CONNECTION-ID}} /directory-provisioning
    ```
  </Tab>
</Tabs>

## Monitor Directory Sync

Monitor sync activity in Auth0 Logs:

* `directory_sync_started`
* `directory_sync_completed`

## Sync Frequency Limits

* Automated sync runs **every 30 minutes** after the last sync completes.
* A manual sync triggered within 30 minutes of the previous completed job will return a `400 Bad Request` error.

## Best Practices

* For new Google Workspace connections, we recommend using the Google user `id` instead of email for the Auth0 `user_id`.
* If you enable Directory Sync, consider disabling **Sync User Profile Attributes at Login** to avoid conflicting updates from multiple sync methods.


# Connect to OpenID Connect Identity Provider
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/oidc

Learn how to connect to OpenID Connect (OIDC) Identity Providers using an enterprise connection.

## Prerequisites

* [Register your Application with Auth0](/docs/get-started/auth0-overview/create-applications).

  * Select an appropriate **Application Type**.
  * Add an **Allowed Callback URL** of **`{https://yourApp/callback}`**.
  * Make sure your Application's [Grant Types](/docs/get-started/applications/update-grant-types) include the appropriate flows.

## Steps

To connect your application to an OIDC <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip>, you must:

1. [Set up your app in the OpenID Connect Identity Provider](#set-up-your-app-in-the-openid-connect-identity-provider)
2. [Create an enterprise connection in Auth0](#create-an-enterprise-connection-in-auth0)
3. [Enable the enterprise connection for your Auth0 Application](#enable-the-enterprise-connection-for-your-auth0-application)
4. [Test the connection](#test-the-connection)

## Set up your app in the OpenID Connect Identity Provider

To allow users to log in using an OIDC Identity Provider, you must register your application with the IdP. The process of doing this varies depending on the OIDC Identity Provider, so you will need to follow your IdP's documentation to complete this task.

Generally, you will want to make sure that at some point you enter your callback URL: `https://{YOUR_AUTH0_DOMAIN}/login/callback`.

<Card title="Find your Auth0 domain name for redirects">
  If your Auth0 domain name is not shown above and you are not using our [custom domains](/docs/customize/custom-domains) feature, your domain name is a concatenation of your tenant name, your regional subdomain, and `auth0.com`, separated by the dot (`.`) symbol.

  For example, if your tenant name is `exampleco-enterprises`, and your tenant is in the US region, your Auth0 domain name would be `exampleco-enterprises.us.auth0.com` and your **Redirect URI** would be `https://exampleco-enterprises.us.auth0.com/login/callback`.

  However, if your tenant is in the US region and was created before June 2020, then your Auth0 domain name would be `exampleco-enterprises.auth0.com` and your **Redirect URI** would be `https://exampleco-enterprises.auth0.com/login/callback`.

  If you are using [custom domains](/docs/customize/custom-domains), your **Redirect URI** would be `https://<YOUR CUSTOM DOMAIN>/login/callback`.
</Card>

During this process, your OIDC Identity Provider will generate a unique identifier for the registered API, usually called a **<Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>** or an **Application ID**. Make note of this value; you will need it later.

## Create an enterprise connection in Auth0

Before you configure a OIDC Enterprise Connection in Auth0, ensure you have the **Application (Client) ID** and the **<Tooltip href="/docs/glossary?term=Client+secret">Client Secret</Tooltip>** generated when you set up your app in the OIDC provider.

### Create an enterprise connection using the Auth0 Dashboard

<Warning>
  To be configurable through the Auth0 Dashboard, the OpenID Connect (OIDC) Identity Provider (IdP) needs to support [OIDC Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html). Otherwise, you can [configure the connection using the Management API](#configure-the-connection-using-the-management-api).
</Warning>

1. Navigate to [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise), locate **Open ID Connect**, and select **Create**.

   <Frame>
     <img alt="Dashboard - Connections - Enterprise" />
   </Frame>

2. Enter details for your connection, and select **Create:**

<Frame>
  <img alt="Enter OIDC Connection Details" />
</Frame>

| **Field**                                      | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Purpose**                                    | Determines how you intend to use the connection, for user authentication, to connect external accounts to Auth0, or both. To learn more, read [User authentication vs Connected Accounts](/docs/secure/tokens/token-vault/connected-accounts-for-token-vault#user-authentication-vs-connected-accounts)                                                                                                                                                                                                                                                                                                                                                                      |
| **Connection name**                            | Logical identifier for your connection; it must be unique for your tenant. Once set, this name can't be changed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| **OpenID Connect Discovery URL**               | URL where Auth0 can find the <strong><a href="https://openid.net/specs/openid-connect-discovery-1_0.html">well-known OpenID Connect discovery endpoint</a></strong>, usually available at the <code>/.well-known/openid-configuration</code> endpoint. You can enter the base URL or the full URL. You will see a green checkmark if it can be found at that location, a red mark if it cannot be found, or an error message if the file is found but the required information is not present in the configuration file. For more information, read [Configure Applications with OIDC Discovery](/docs/get-started/applications/configure-applications-with-oidc-discovery). |
| **Client ID**                                  | The identifier given to you by your provider. Unique identifier for your registered application. Enter the saved value of the Client ID for the app you registered with the OIDC Identity Provider. Each provider manages this step differently.                                                                                                                                                                                                                                                                                                                                                                                                                             |
| **Communication Channel**                      | Set to <strong>Front Channel</strong> or <strong>Back Channel</strong>. Front Channel uses the OIDC protocol with <code>response\_mode=form\_post</code> and <code>response\_type=id\_token</code>. Back Channel uses <code>response\_type=code</code>.                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **Authentication Method**                      | Choose how your application authenticates with Auth0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **Client Secret**                              | Available if <strong>Back Channel</strong> is chosen earlier. The secret given to you by your provider and each provider manages this step differently.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **Callback URL**                               | URL to which Auth0 redirects users after they authenticate. Ensure that this value is configured for the app you registered with the OIDC Identity Provider.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **Sync user profile attributes at each login** | f selected, your tenant updates the relevant <code>name</code>, <code>nickname</code>, <code>given\_name</code>, <code>family\_name</code>, or <code>picture</code> root attributes each time a user logs in.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| **Promote Connection to Domain Level**         | Allows third-party applications to access the connection.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

3. In the **Settings** view, make additional configuration adjustments, if necessary.

| **Field**                              | **Description**                                                                                                                                                                                                                                                                                                                     |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Connection Name**                    | The name you provided when you created this connection. It can't be changed.                                                                                                                                                                                                                                                        |
| **Connection Metadata**                | Automatically generated when by the Well-Known Endpoint URL you provided in the previous screen, this can be overwritten by uploading a new metadata file.                                                                                                                                                                          |
| **Authentication**                     | Set to **Front Channel** or **Back Channel**. Front Channel uses the OIDC protocol with `response_mode=form_post` and `response_type=id_token`. Back Channel uses `response_type=code`. Select **Manage Authentication** to update on the Credentials tab.                                                                          |
| **Scopes**                             | A comma-separated list of Auth0 scopes to request when connecting to the Identify Provider. This will affect the data stored in the user profile. You are required to include at least the `openid` scope. Note that the connection does not call `/userinfo` endpoint and expects the user claims to be present in the `id_token`. |
| **Callback URL**                       | Some providers need this URL to complete your OIDC connection.                                                                                                                                                                                                                                                                      |
| **User Mapping**                       | Provides templates to map specific user attributes to connection variables.                                                                                                                                                                                                                                                         |
| **Connection Profile**                 | To understand how to change your connection profile, read [Configure PKCE and Claim Mapping for OIDC Connections](/docs/authenticate/identity-providers/enterprise-identity-providers/configure-pkce-claim-mapping-for-oidc).                                                                                                       |
| **Purpose**                            | Determines how you intend to use the connection, for user authentication, to connect external accounts to Auth0, or both. To learn more, read [User authentication vs Connected Accounts](/docs/secure/tokens/token-vault/connected-accounts-for-token-vault#user-authentication-vs-connected-accounts)                             |
| **Global Token Revocation**            | Use the provided endpoint to terminate a user's Auth0 session by revoking refresh tokens. Cna be used with Universal Logout and Okta Workforce Identity Cloud.                                                                                                                                                                      |
| **Promote Connection to Domain Level** | Allows third-party applications to access the connection.                                                                                                                                                                                                                                                                           |

<br />

4. In the **Provisioning** view, configure how user profiles get created and updated in Auth0.

| **Field**                                      | **Description**                                                                                                                                                                                |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sync user profile attributes at each login** | hen enabled, Auth0 automatically syncs user profile data with each user login, thereby ensuring that changes made in the connection source are automatically updated in Auth0.                 |
| **Sync Frequency**                             | Determine how often the user profile should update.                                                                                                                                            |
| **Sync user profiles using SCIM**              | When enabled, Auth0 allows user profile data to be synced using SCIM. For more information, see <a href="/docs/authenticate/protocols/scim/configure-inbound-scim">Configure Inbound SCIM</a>. |

5. In the **Login Experience** view, configure how users log in with this connection.

<table>
  <thead>
    <tr>
      <th><strong>Field</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Home Realm Discovery</strong></td>
      <td>Compares a user's email domain with the provided identity provider domains. For more information, read <a href="/docs/authenticate/login/auth0-universal-login/identifier-first">Configure Identifier First Authentication</a></td>
    </tr>

    <tr>
      <td><strong>Display connection button</strong></td>
      <td>This option displays the following choices to customize your application's connection button.</td>
    </tr>
  </tbody>
</table>

<Callout icon="file-lines">
  Optional fields are available with Universal Login only. Customers using Classic Login will not see the Add button, Button display name, or Button logo URL.
</Callout>

6. Select **Save Changes**.

### Create an enterprise connection using the Management API

These examples will show you the variety of ways you can create the connection using Auth0's <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. You ca configure the connection by either providing a metadata URI or by setting the OIDC URLs explicitly. For more information, read [Identity Providers](/docs/authenticate/identity-providers).

#### Use front-channel with discovery endpoint

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/connections' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --data '{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "front_channel", "discovery_url": "https://IDP_DOMAIN/.well-known/openid-configuration", "client_id" : "IDP_CLIENT_ID",  "scopes": "openid profile" } }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/connections");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddParameter("undefined", "{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "front_channel", "discovery_url": "https://IDP_DOMAIN/.well-known/openid-configuration", "client_id" : "IDP_CLIENT_ID",  "scopes": "openid profile" } }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/connections"

  	payload := strings.NewReader("{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "front_channel", "discovery_url": "https://IDP_DOMAIN/.well-known/openid-configuration", "client_id" : "IDP_CLIENT_ID",  "scopes": "openid profile" } }")

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

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/connections")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .body("{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "front_channel", "discovery_url": "https://IDP_DOMAIN/.well-known/openid-configuration", "client_id" : "IDP_CLIENT_ID",  "scopes": "openid profile" } }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/connections',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN'},
    data: {
      strategy: 'oidc',
      name: 'CONNECTION_NAME',
      options: {
        type: 'front_channel',
        discovery_url: 'https://IDP_DOMAIN/.well-known/openid-configuration',
        client_id: 'IDP_CLIENT_ID',
        scopes: 'openid profile'
      }
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/connections",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "front_channel", "discovery_url": "https://IDP_DOMAIN/.well-known/openid-configuration", "client_id" : "IDP_CLIENT_ID",  "scopes": "openid profile" } }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "front_channel", "discovery_url": "https://IDP_DOMAIN/.well-known/openid-configuration", "client_id" : "IDP_CLIENT_ID",  "scopes": "openid profile" } }"

  headers = { 'authorization': "Bearer MGMT_API_ACCESS_TOKEN" }

  conn.request("POST", "/{yourDomain}/api/v2/connections", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/connections")

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

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request.body = "{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "front_channel", "discovery_url": "https://IDP_DOMAIN/.well-known/openid-configuration", "client_id" : "IDP_CLIENT_ID",  "scopes": "openid profile" } }"

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

#### Use back-channel with discovery endpoint

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/connections' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --data '{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "back_channel", "discovery_url": "https://IDP_DOMAIN/.well-known/openid-configuration", "client_id" : "IDP_CLIENT_ID", "client_secret" : "IDP_CLIENT_SECRET", "scopes": "openid profile" } }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/connections");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddParameter("undefined", "{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "back_channel", "discovery_url": "https://IDP_DOMAIN/.well-known/openid-configuration", "client_id" : "IDP_CLIENT_ID", "client_secret" : "IDP_CLIENT_SECRET", "scopes": "openid profile" } }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/connections"

  	payload := strings.NewReader("{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "back_channel", "discovery_url": "https://IDP_DOMAIN/.well-known/openid-configuration", "client_id" : "IDP_CLIENT_ID", "client_secret" : "IDP_CLIENT_SECRET", "scopes": "openid profile" } }")

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

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/connections")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .body("{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "back_channel", "discovery_url": "https://IDP_DOMAIN/.well-known/openid-configuration", "client_id" : "IDP_CLIENT_ID", "client_secret" : "IDP_CLIENT_SECRET", "scopes": "openid profile" } }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/connections',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN'},
    data: {
      strategy: 'oidc',
      name: 'CONNECTION_NAME',
      options: {
        type: 'back_channel',
        discovery_url: 'https://IDP_DOMAIN/.well-known/openid-configuration',
        client_id: 'IDP_CLIENT_ID',
        client_secret: 'IDP_CLIENT_SECRET',
        scopes: 'openid profile'
      }
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/connections",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "back_channel", "discovery_url": "https://IDP_DOMAIN/.well-known/openid-configuration", "client_id" : "IDP_CLIENT_ID", "client_secret" : "IDP_CLIENT_SECRET", "scopes": "openid profile" } }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "back_channel", "discovery_url": "https://IDP_DOMAIN/.well-known/openid-configuration", "client_id" : "IDP_CLIENT_ID", "client_secret" : "IDP_CLIENT_SECRET", "scopes": "openid profile" } }"

  headers = { 'authorization': "Bearer MGMT_API_ACCESS_TOKEN" }

  conn.request("POST", "/{yourDomain}/api/v2/connections", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/connections")

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

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request.body = "{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "back_channel", "discovery_url": "https://IDP_DOMAIN/.well-known/openid-configuration", "client_id" : "IDP_CLIENT_ID", "client_secret" : "IDP_CLIENT_SECRET", "scopes": "openid profile" } }"

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

#### Use back-channel specifying issuer settings

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/connections' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --data '{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "back_channel", "issuer": "https://IDP_DOMAIN", "authorization_endpoint": "https://IDP_DOMAIN/authorize", "client_secret" : "IDP_CLIENT_SECRET", "client_id" : "IDP_CLIENT_ID",  "scopes": "openid profile" } }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/connections");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddParameter("undefined", "{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "back_channel", "issuer": "https://IDP_DOMAIN", "authorization_endpoint": "https://IDP_DOMAIN/authorize", "client_secret" : "IDP_CLIENT_SECRET", "client_id" : "IDP_CLIENT_ID",  "scopes": "openid profile" } }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/connections"

  	payload := strings.NewReader("{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "back_channel", "issuer": "https://IDP_DOMAIN", "authorization_endpoint": "https://IDP_DOMAIN/authorize", "client_secret" : "IDP_CLIENT_SECRET", "client_id" : "IDP_CLIENT_ID",  "scopes": "openid profile" } }")

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

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/connections")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .body("{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "back_channel", "issuer": "https://IDP_DOMAIN", "authorization_endpoint": "https://IDP_DOMAIN/authorize", "client_secret" : "IDP_CLIENT_SECRET", "client_id" : "IDP_CLIENT_ID",  "scopes": "openid profile" } }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/connections',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN'},
    data: {
      strategy: 'oidc',
      name: 'CONNECTION_NAME',
      options: {
        type: 'back_channel',
        issuer: 'https://IDP_DOMAIN',
        authorization_endpoint: 'https://IDP_DOMAIN/authorize',
        client_secret: 'IDP_CLIENT_SECRET',
        client_id: 'IDP_CLIENT_ID',
        scopes: 'openid profile'
      }
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/connections",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "back_channel", "issuer": "https://IDP_DOMAIN", "authorization_endpoint": "https://IDP_DOMAIN/authorize", "client_secret" : "IDP_CLIENT_SECRET", "client_id" : "IDP_CLIENT_ID",  "scopes": "openid profile" } }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "back_channel", "issuer": "https://IDP_DOMAIN", "authorization_endpoint": "https://IDP_DOMAIN/authorize", "client_secret" : "IDP_CLIENT_SECRET", "client_id" : "IDP_CLIENT_ID",  "scopes": "openid profile" } }"

  headers = { 'authorization': "Bearer MGMT_API_ACCESS_TOKEN" }

  conn.request("POST", "/{yourDomain}/api/v2/connections", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/connections")

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

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request.body = "{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "back_channel", "issuer": "https://IDP_DOMAIN", "authorization_endpoint": "https://IDP_DOMAIN/authorize", "client_secret" : "IDP_CLIENT_SECRET", "client_id" : "IDP_CLIENT_ID",  "scopes": "openid profile" } }"

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

#### Use front-channel specifying issuer settings

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/connections' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --data '{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "front_channel", "issuer": "https://IDP_DOMAIN", "authorization_endpoint": "https://IDP_DOMAIN/authorize", "token_endpoint": "https://IDP_DOMAIN/oauth/token", "client_id" : "IDP_CLIENT_ID",  "scopes": "openid profile" } }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/connections");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddParameter("undefined", "{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "front_channel", "issuer": "https://IDP_DOMAIN", "authorization_endpoint": "https://IDP_DOMAIN/authorize", "token_endpoint": "https://IDP_DOMAIN/oauth/token", "client_id" : "IDP_CLIENT_ID",  "scopes": "openid profile" } }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/connections"

  	payload := strings.NewReader("{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "front_channel", "issuer": "https://IDP_DOMAIN", "authorization_endpoint": "https://IDP_DOMAIN/authorize", "token_endpoint": "https://IDP_DOMAIN/oauth/token", "client_id" : "IDP_CLIENT_ID",  "scopes": "openid profile" } }")

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

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/connections")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .body("{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "front_channel", "issuer": "https://IDP_DOMAIN", "authorization_endpoint": "https://IDP_DOMAIN/authorize", "token_endpoint": "https://IDP_DOMAIN/oauth/token", "client_id" : "IDP_CLIENT_ID",  "scopes": "openid profile" } }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/connections',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN'},
    data: {
      strategy: 'oidc',
      name: 'CONNECTION_NAME',
      options: {
        type: 'front_channel',
        issuer: 'https://IDP_DOMAIN',
        authorization_endpoint: 'https://IDP_DOMAIN/authorize',
        token_endpoint: 'https://IDP_DOMAIN/oauth/token',
        client_id: 'IDP_CLIENT_ID',
        scopes: 'openid profile'
      }
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/connections",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "front_channel", "issuer": "https://IDP_DOMAIN", "authorization_endpoint": "https://IDP_DOMAIN/authorize", "token_endpoint": "https://IDP_DOMAIN/oauth/token", "client_id" : "IDP_CLIENT_ID",  "scopes": "openid profile" } }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "front_channel", "issuer": "https://IDP_DOMAIN", "authorization_endpoint": "https://IDP_DOMAIN/authorize", "token_endpoint": "https://IDP_DOMAIN/oauth/token", "client_id" : "IDP_CLIENT_ID",  "scopes": "openid profile" } }"

  headers = { 'authorization': "Bearer MGMT_API_ACCESS_TOKEN" }

  conn.request("POST", "/{yourDomain}/api/v2/connections", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/connections")

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

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request.body = "{ "strategy": "oidc", "name": "CONNECTION_NAME", "options": { "type": "front_channel", "issuer": "https://IDP_DOMAIN", "authorization_endpoint": "https://IDP_DOMAIN/authorize", "token_endpoint": "https://IDP_DOMAIN/oauth/token", "client_id" : "IDP_CLIENT_ID",  "scopes": "openid profile" } }"

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

## Configure PKCE and claims mapping

This Enterprise connection can support Proof Key for Code Exchange (PKCE), as well as attribute and token mapping. To learn more, review [Configure PKCE and Claim Mapping for OIDC Connections](/docs/authenticate/identity-providers/enterprise-identity-providers/configure-pkce-claim-mapping-for-oidc).

## Enable the enterprise connection for your Auth0 application

To use your new enterprise connection, you must first [enable the connection](/docs/authenticate/identity-providers/enterprise-identity-providers/enable-enterprise-connections) for your Auth0 Applications.

## Test the connection

Now you're ready to [test your connection](/docs/authenticate/identity-providers/enterprise-identity-providers/test-enterprise-connections).

## Manually configure Issuer metadata

If you click **Show Issuer Details** on the Issuer URL endpoint, you can see the data and adjust it if you need to.

## Federate with Auth0

The <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect enterprise connection is useful when federating to another Auth0 tenant. Enter your Auth0 tenant URL (for example, `https://<tenant>.us.auth0.com`) in the **Issuer** field, and enter the Client ID for any application in the tenant to which you want to federate in the **Client ID** field.

<Callout icon="file-lines">
  New tenants will have `us` as part of the URL. Tenants created before the regional domain addition will continue to work. For example, `https://{YOUR ACCOUNT}.auth0.com`.
</Callout>

## Configure Global Token Revocation

This connection type supports a Global Token Revocation endpoint, which allows a compliant identity provider to revoke Auth0 user sessions, revoke <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip>, and trigger back-channel logout for applications using a secure back-channel.

This feature can be used with Universal Logout in Okta Workforce Identity.

For more information and configuration instructions, see [Universal Logout](/docs/authenticate/login/logout/universal-logout).


# Express Configuration with Okta
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/okta/express-configuration

Describes how to set up Express Configuration with Auth0 and the Okta Integration Network (OIN).

The [Okta Integration Network (OIN)](https://www.okta.com/integrations/) is a catalog of SaaS applications for which Okta provides an express setup experience for enabling single sign-in with OpenID Connect, automated user provisioning with SCIM, and [Universal Logout](https://developer.okta.com/docs/guides/oin-universal-logout-overview). Okta administrators use the [Okta Admin Console](https://www.okta.com/okta-administrator-experience) to configure these integrations within their Okta tenant:

<Frame>
  <img alt="Okta Administrator Console" />
</Frame>

Express Configuration enables enterprise customers to securely configure identity integrations with SaaS applications without the need to copy and paste protocol-specific configuration values.

Express Configuration provides these benefits to Okta administrators and SaaS application developers:

* Reduces the time required to set up an application instance by automating the exchange of configuration information between Okta and Auth0.
* Utilizes OAuth 2.0 consent flows for the secure and authorized sharing of sensitive configuration data, reducing potential errors related to credentials and configuration settings.
* Simplifies and standardizes the integration deployment process. Automated workflow enables consistent and repeatable deployments of application integrations across multiple customers or environments, supporting a scalable application ecosystem with less opportunity for human error.
* Eliminates the complexity of manual setup, enabling Okta customer admins to quickly add instances of Auth0-enabled OIN integrations.

## How it works

The Express Configuration API allows Auth0 applications published to the OIN for customers to use Express Configuration on an [Okta connection](/docs/authenticate/identity-providers/enterprise-identity-providers/okta). Express Configuration supports OpenID Connect, SCIM, and Universal Logout within an Auth0 Organization.

Review the Express Configuration workflow for an Auth0 app in the OIN:

<Frame>
  <img alt="express configuration workflow for an Auth0 app in the OIN." />
</Frame>

* An Okta administrator signs in to the Okta portal and selects the Express Configuration-enabled application from the OIN.
* The Okta administrator navigates to the **Sign On** section and select **Express Configure SSO & UL**. This redirects them to an [Auth0 Universal Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience#universal-login-experience) screen.

<Frame>
  <img alt="Okta administrator console > Sign On > Express Configuration" />
</Frame>

* The Okta administrator enters the credentials of an application user who is permitted to perform Express Configuration. In Auth0, this refers to a user who is a member of an [organization](/docs/manage-users/organizations) and is authorized to perform Express Configuration using an [organizational role](/docs/manage-users/organizations/configure-organizations/add-member-roles) or other authorization method.

<Frame>
  <img alt="Auth0 Organziation login" />
</Frame>

* After authenticating, Auth0 prompts the Okta administrator for consent.

<Frame>
  <img alt="Auth0 consent" />
</Frame>

* After consenting, Okta uses the Express Configuration API to automatically configure an [Okta connection](/docs/authenticate/identity-providers/enterprise-identity-providers/okta) within the Auth0 organization to which the Okta administrator belongs.

* The Okta administrator may then assign users to the application instance and see single sign-on working immediately.

Auth0 developers can also configure their OIN integration to allow Express Configuration of SCIM and Universal Logout, both of which are recommended:

* When SCIM is enabled, Okta administrators can configure SCIM by navigating to the **Provisioning** section of the application details and selecting **Express Configure SCIM**.
* When Universal Logout is enabled, it will be automatically configured as part of the OpenID Connect integration.

## Prerequisites

To publish an application to the OIN with Express Configuration enabled, you must have the following:

* An [Okta Integrator Free Plan org](https://developer.okta.com/signup/), with access to either the Super Admin role or the App and Org Admin roles.
* An [Auth0 subscription](https://auth0.com/pricing) that enables the use of the Okta connection type and the Organizations feature for as many customers as you need.
* A SaaS application that has been integrated with Auth0 using a Multi-Organization Architecture.
  * This includes registering your application as a [Regular Web Application](/docs/get-started/auth0-overview/create-applications/regular-web-apps) or [Single-Page Application](/docs/get-started/auth0-overview/create-applications/single-page-web-apps) in Auth0, and enabling each of your customers to sign into that application using their own distinct [identity providers](/docs/authenticate/enterprise-connections).
* An [Auth0 Organization](/docs/manage-users/organizations) is deployed, or can be deployed, for each customer using Express Configuration. Organizations and organizational roles are used to authorize specific users to perform express configuration and create Okta connections only within the organizations to which they belong.
* Your Auth0 tenant should have the [Enable Application Connections](/docs/get-started/tenant-settings#recommended-settings) tenant setting disabled.

<Note>
  **Tip**: To view a sample application that implements a multi-tenant architecture including Auth0 Organizations and organizational roles, refer to the [SaaStart reference application](https://auth0.com/blog/speed-up-your-customer-identity-journey-with-auth0-saastart/).
</Note>

## Configure your application for Express Configuration

The Auth0 Dashboard guides an Auth0 developer through enabling Express Configuration for their application and publishing it to the OIN.

An [Auth0 Admin role](/docs/get-started/manage-dashboard-access/feature-access-by-role) in a production Auth0 tenant is required to complete the end-to-end setup and publishing process.

<Frame>
  <img alt="OIN in Auth0 Dashboard" />
</Frame>

Configure the following Auth0 components to set up Express Configuration in your tenant:

* A registered application with Initiate Login URI Template
* A Connection Profile
* A User Attribute Profile
* Organization login settings
* Administrator login and consent settings

### Register an application with Initiate Login URI Template

1. Register your application as a [Regular Web Application](/docs/get-started/auth0-overview/create-applications/regular-web-apps) or [Single-Page Application](/docs/get-started/auth0-overview/create-applications/single-page-web-apps) in Auth0 Dashboard.
2. Once registered, select the application you created and navigate to the **Okta Integration Network** tab to begin the Express Configuration setup wizard.
3. Select **Get Started**.
4. Review the Prerequisites and select **Continue**.
5. Register an **Initiate Login URI Template**. This template implements an endpoint on your application to automatically redirect end-users to Auth0's `/authorize` endpoint for authentication. To review an example of a login endpoint, review the `/login` route in the [Express SDK Quickstart](/docs/quickstart/webapp/express/interactive).
   * After Express Configuration initiates for an application instance, Okta uses the **Initiate Login URI Template** to launch the application from the [end-user dashboard](https://help.okta.com/en-us/content/topics/settings/new-dashboard-overview.htm).
   * (Optional) Set the `organization_name`, `organization_id,` and `connection_name` for Auth0's `/authorize` endpoint to identify the organization or connection to use. Okta dynamically replaces these variables when the URL is launched from the end-user dashboard. Example: `https://{organization_name}.your-app.com?connection={connection_name}`.

<Frame>
  <img alt="Dashboard>Applications>OIN>URI-template" />
</Frame>

**Initiate Login URI Examples:**

`https://your-app.com/login` <br />
`https://your-app.com/login?connection={connection_name}` <br />
`https://{organization_name}.your-app.com?connection={connection_name}` <br />

#### Connection Profile

In the Initiate Login URI Template, you have the option to add a **Connection Profile**. The Connection Profile (CP) enables Auth0 to specify how the private settings of your connections should be configured when created using Express Configuration, including settings that govern how the connection interacts with Auth0’s Universal Login and Organizations features:

* Options for how the connection name should be created in Auth0
* Options to use SCIM and/or Universal Logout with the connection (Recommended)
* Options to allow end users of the connection to automatically become members of the consenting administrator’s organization
* Options for the **Show as button** setting for the connection on Auth0’s Universal Login page

<Note>
  If you do not have a Connection Profile configured, Auth0 provides a default Connection Profile with common and recommended settings implemented for Express-configured connections.
</Note>

To learn how to customize the default CP, read [Connection Profile](/docs/authenticate/enterprise-connections/connection-profile).

#### User Attribute Profile

In the Initiate Login URI Template, you have the option to add a **User Attribute Profile**. The User Attribute Profile (UAP) allows Auth0 developers to define, manage, and map user attributes consistently across the various protocols supported by Auth0. When used with Express Configuration, the User Attribute Profile allows developers to customize the OpenID Connect and SCIM attribute maps that will be written to the Okta connection generated by Express Configuration.

<Note>
  If you do not have a User Attribute Profile configured, Auth0 provides a default User Attribute Profile with common and recommended mappings for all protocols, including OpenID Connect and SCIM, which are used by the Okta connection type.
</Note>

To learn how to customize the default UAP, read [User Attribute Profile](/docs/authenticate/enterprise-connections/user-attribute-profile).

### Organization login settings

Auth0 Organizations is required to authorize specific organizational users to create isolated connections but is not required to change your application’s existing login flow to support the [organization-based login flow for business users](/docs/manage-users/organizations/configure-organizations/define-organization-behavior).

* If your application currently uses an [Identifier-First login experience](/docs/authenticate/login/auth0-universal-login/identifier-first) and home realm discovery with your applications, see the [Enabling Home Realm Discovery](/docs/authenticate/identity-providers/enterprise-identity-providers/okta/express-configuration#enable-home-realm-discovery) section for information on how to enable home realm discovery.
* If you wish to enable multiple applications in `enabled_clients` to be used with your Express Configuration connections, see Enabling Multiple Auth0 Applications Under a Single Integration.

If your application setup does not currently use an organization-based login flow, you can select the **Enable this application for created connections** setting. When enabled, each Express Configuration on an Okta connection is associated directly with your application. Use the required `enabled_clients` setting on the connection.

### Administrator login and consent settings

When Express Configuration is enabled, Auth0 creates an additional client application ID that is used by the OIN during the administrator consent flow between Okta and Auth0. Okta creates one OIN client for each distinct application integration published to the OIN.

Configure administrator login and consent settings in the application you want to publish to the OIN under **Configure Integration Profile**.

1. Navigate to [Auth0 Dashboard > Applications](https://manage.auth0.com/dashboard/#/applications).
2. Choose the application you want to publish to the OIN.
3. Select Okta Integration Network.
4. Verify you have the necessary prerequisites and select **Continue**.
5. In the **Configure Integration Profile** section, configure options in **Admin Settings**.

<Frame>
  <img alt="Express Configuration Admin Settings" />
</Frame>

* **Admin Login Domain**: Auth0 tenant domain Okta redirects to as part of the consent flow in a Web browser. Use the custom domain name if you have one configured in Auth0. To learn more, read [Custom Domains](docs/customize/custom-domains).

* **Display Name of the OIN Express Configuration Application**: Name of the OIN client application shown in the consent dialog.

* **Admin Login Flow**: Defines the [Organization login](/docs/manage-users/organizations/login-flows-for-organizations) flow for the OIN client application and used when an Okta administrator runs Express Configuration from the Okta console. Select from:

  * **Prompt for Organization**: Admins are first asked to select their Organization and are presented with the login experience for their Auth0 Organization. Admins can sign in using a [pre-existing connection](/docs/manage-users/organizations/configure-organizations/enable-connections) configured in that organization.

  * **Prompt for Credentials**: Admins are first asked to provide their login credentials. When this option is selected, a button will appear that allows you to select the connections that contain the admin users. This can be a shared database connection, a passwordless email connection, or another connection that can be associated with all Auth0 Organizations.

* **Admin Role**:  In order to perform Express Configuration, the admin must be assigned the appropriate permissions. Read [Assign express configuration permissions to users](/docs/authenticate/identity-providers/enterprise-identity-providers/okta/express-configuration#assign-permissions-to-users) for instructions on how to authorize admins in the way that makes the most sense for your current Auth0 deployment.

<Note>
  For the best consent experience, set your tenant’s `use_scope_descriptions_for_consent` flag to `true` as described in [Customize Consent Prompts](/docs/customize/login-pages/customize-consent-prompts). You will have the opportunity to view your consent prompt later in when you test and verify your integration.
</Note>

## Assign permissions to users

For Okta,  administrators must have an application user account with required permissions to perform Express Configuration for an Auth0-powered SaaS application.

For Auth0, any application user may be granted this permission, as long as the user is a member of an [Auth0 Organization](/docs/manage-users/organizations) where the Express-configured connections is created, including:

* A user in a dedicated database connection that has been created exclusively for a single Organization
* A user in a shared database connection who is a member of one or more Organizations
* A user with a passwordless email connection who is a member of one or more Organizations
* A user in a social or existing enterprise connection who is a member of one or more Organizations

Once conditions are met, Auth0 provides flexible ways to asign Express Configuration permissions and allow developers to choose the method most appropriate for their curret Auth0 deployment:

| **Method**                                                                                                                                                                                                                      | **Recommended for...**                                                                                                                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Assign Express Configuration permissions to an existing user role                                                                                                                                                               | Customers wih existing application user [role](/docs/manage-users/access-control/configure-core-rbac/roles) in their Auth0 tenant.                                                                                                                                                                     |
| Assign a new role to application users requiring Express Configuration permissions as exemplified in the [SaaStart reference application](https://auth0.com/blog/speed-up-your-customer-identity-journey-with-auth0-saastart/). | Customers who want to use Auth0’s [role](/docs/manage-users/access-control/configure-core-rbac/roles) feature to grant Express Configuration permissions to individual users. This can be done withAuth0 Dashboard or the Management API.                                                              |
| Use a Post-Login Action to  dynamically assign permissions using attribute-based access control                                                                                                                                 | Customers not currently using Auth0’s [role](/docs/manage-users/access-control/configure-core-rbac/roles) feature and prefer using a Post-Login Action to dynamically assign permissions based on user attributes instead of using the Auth0 Dashboard or making Management API calls to assign roles. |

For tips on provisioning administator accounts to use Express Configuration, read [Customer Enablement](/docs/authenticate/identity-providers/enterprise-identity-providers/okta/express-configuration#customer-enablement).

### Assign permissions to a pre-existing application user role

Use this method of assigning Express Configuration permissions if you use [Auth0’s RBAC feature](/docs/manage-users/access-control/configure-core-rbac/roles) for application roles and API permissions and already have one or more roles that represent an administrative user that would be assigned to an IT administrator deploying the application.

Required API permissions:

| **Permission Name**      | **API (Resource Server) Identifier** |
| ------------------------ | ------------------------------------ |
| `express_configure:sso`  | `urn:auth0:express-configure`        |
| `express_configure:scim` | `urn:auth0:express-configure`        |

To learn more about assigning roles in Auth0 Dashboard and Management API, read [Add permissions to roles](/docs/manage-users/access-control/configure-core-rbac/roles/add-permissions-to-roles).

### Assign a new role to application users

Use this method of assigning Express Configuration permissions if you use [Auth0’s RBAC feature](/docs/manage-users/access-control/configure-core-rbac/roles) for application roles and API permissions, but do not have a role that represents an administrative user, such as an IT administrator, who would be assigned to deploy the application.

This method is also suitable for Auth0 developers who aren’t currently using [Auth0’s RBAC feature](/docs/manage-users/access-control/configure-core-rbac/roles) but want to utilize it to gain granular control over which users are allowed access, using either the Auth0 Dashboard or the Management API.

#### Create a role

Use Auth0 Dashboard, Management API, or [Auth0 CLI](https://auth0.github.io/auth0-cli/auth0_roles_create.html) to [create roles](/docs/manage-users/access-control/configure-core-rbac/roles/create-roles). This example uses Auth0 CLI:

```bash theme={null}
auth0 roles create \
  --name "EXPRESS_CONFIGURE_ADMIN_ROLE" \
  --description "Administrator role for Express Configuration"
```

#### Assign permissions to the role

Assign the `express_configuration:sso` and `express_configuration:scim` permissions to the specified role. Replace `$ROLE_ID` with the role ID that you want to grant permission.

<Note>
  When using this method, you will need to update your customer onboarding process to assign this role to any new organizational users who require Express Configuration permissions.
</Note>

```bash theme={null}
auth0 roles permissions add "$ROLE_ID" \
  --api-id "urn:auth0:express-configure" \
  --permissions "express_configure:sso"
```

```bash theme={null}
auth0 roles permissions add "$ROLE_ID" \
  --api-id "urn:auth0:express-configure" \
  --permissions "express_configure:scim"
```

To learn more on assigning roles to existing organization users, read [Add member roles](/docs/manage-users/organizations/configure-organizations/add-member-roles).

### Assign permissions based on user attributes using a post-login Action

Use this method of assigning Express Configuration permissions if you are using an Auth0 [post-login Action](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) to dynamically assign permissions based on user attributes instead of Role-Based Access Control (RBAC), Management API, or Auth0 Dashboard to assign user roles.

This is appropriate for Auth0 customers who have deployed Auth0 using an attribute-based authorization model using custom permissions in [Auth0 metadata](/docs/manage-users/user-accounts/metadata).

**Example** <br />
The following example uses a post-login Action to assign permissions based on the value of an existing custom user attribute, `user.app_metadata.is_admin`.

```bash theme={null}
/**
* Assigns Express Configuration permissions based on custom logic instead of role assignment
*/
exports.onExecutePostLogin = async (event, api) => {


 //check if request is for EC API access token
 if (event.resource_server && event.resource_server.identifier === "urn:auth0:express-configure") {


   //add permissions based on a custom condition
   if (event.user.app_metadata && event.user.app_metadata.is_admin === true) {
     api.accessToken.addScope("express_configure:sso");
     api.accessToken.addScope("express_configure:scim");
   }
   //else deny access if EC access token is requested
   else {
     api.access.deny('Access denied');
   }
 }
};
```

## Enable home realm discovery

<Note>
  Before you run Express Configuration, you must collect and verify customer email addresses as part of the customer onboarding process to enable HRD.
</Note>

You can use Express Configuration with Auth0 Actions if your application relies on [Identifier-First login experience](/docs/authenticate/login/auth0-universal-login/identifier-first) and uses home realm discovery (HRD) to match users with their identity providers (IdP) based on the email address.

Email addresses should be stored in a location accessible by post-login Actions during the Express Configuration workflow, including:

* One or more email domains can be stored in [organization metadata](/docs/manage-users/organizations/configure-organizations/create-organizations) on the customer’s Auth0 Organization.
* Your post-login action can make an API call to retrieve verified domains from any system in your environment that stores them.

When the administrative user initiates express configuration in the Okta portal and authenticates, these actions add the email domains to the token that Okta receives, which it extracts and uses to set up the Okta connection with the correct HRD configuration.

**Example 1** <br />
In this example, verified domains are stored in connection metadata in the Auth0 Organization, which requires a comma-delimited string of one or more email domains stored in the organization metadata under a key named `domains`.

Example values: `test.com`,`test2.com`

```javascript theme={null}
exports.onExecutePostLogin = async (event, api) => {
if (event.request.query.audience === "urn:auth0:express-configure") {
  if (event.organization && event.organization.metadata && event.organization.metadata.domains)
  {
    var domain_aliases = event.organization.metadata.domains.replace(/ /g,'').split(',');
    var express_configuration = {
      "domain_aliases": domain_aliases
     };
     api.accessToken.setCustomClaim("express_configuration", express_configuration);
  }
}
};
```

**Example 2** <br />
In this example, the post-login Action makes an API call to retrieve verified domains from a storage system in your environment.

```javascript theme={null}
/**
*/
exports.onExecutePostLogin = async (event, api) => {
 if (event.request.query.audience === "urn:auth0:express-configure") {
    const axios = require("axios");
    // configure your custom API call here 
    const domains = await axios.get("https://example.org/endpoint");
     var express_configuration = {
     "domain_aliases": domains
      };
      api.accessToken.setCustomClaim("express_configuration", express_configuration);
  
 }
};
```

### Maintain admin account matching across connections

Auth0 permits provisioning user accounts with the same email address in different connections. An end user can have a database connection, social, or passwordless account with their work email address, and also have the same email address in their federated Okta account.

When using the **Prompt for Credentials** option in the [Admin login and consent flow](/docs/authenticate/identity-providers/enterprise-identity-providers/okta/express-configuration#provision-admin-accounts), home realm discovery starts matching users with a specific domain suffix to the new Okta connection instead of other connection types after it is added to the Organization. To learn more about this Organization login behavior, read [Identifier First Authentication with prompt for credentials](/docs/manage-users/organizations/login-flows-for-organizations#identifier-first-authentication-with-prompt-for-credentials).

This behavior only takes effect when customers run Express Configuration a second time after their initial Auth0 admin user session expires. If the admin account identifier is an email address that matches the new Okta connection, the admin will be redirected there.

This behavior can be managed or avoided using any of the following methods:

* Use the **Prompt for Organization** option in the [Admin login and consent flow](/docs/authenticate/identity-providers/enterprise-identity-providers/okta/express-configuration#provision-admin-accounts).
* Enable Express Configuration permissions for the new Okta account that contains the matching verified email address after it is provisioned.
* If you only use Auth0 Organizations for the Express Configuration admin consent flow and not your application experience, you can solve the issue by disabling the `enable_organization` property described in [Configure SaaS Application Properties](/docs/authenticate/identity-providers/enterprise-identity-providers/okta/express-configuration#configure-saas-application-properties).
* This is not an issue if the admin user identifier is not an email address, such as a username in a database connection.

## Enable multiple applications under a single integration

If you want end-users of a single Express Configuration on an Okta connection to access multiple applications in your tenant, you can set a `linked_clients` property on your registered web application.

To modify this setting, use the Auth0 Management API to [retrieve your registered web application](https://auth0.com/docs/api/management/v2/clients/get-clients-by-id). Replace `{yourAppId}` with the Client ID of your registered application, and `{yourAccessToken}` with a Management APIv2 access token. To learn how to get an access token to use the Management API, read [Management API Access Tokens](/docs/secure/tokens/access-tokens/management-api-access-tokens).

```curl theme={null}
curl --request GET \
  --url 'https://{yourDomain}/api/v2/clients/{yourAppId}' \
  --header 'authorization: Bearer {yourAccessToken}'
```

Extract the `express_configuration` property from the response, add an array of additional application IDs to a `linked_clients` property, and [update your registered web application](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id):

```curl theme={null}
curl --request PATCH \
  --url 'https://{yourDomain}/api/v2/clients/{yourAppId}' \
  --data '{"express_configuration": 
  {"admin_login_domain":"TENANT.auth0.com",
    "connection_profile_id":"cop_xxxxxxxxxxxxxxx",
    "enable_client":true,
    "enable_organization":true,
    "initiate_login_uri_template":"https://example.org",
    "okta_oin_client_id":"LDiGbUeiAYjRB5a4yOGfBvxxxxxxxxxxx",
    "user_attribute_profile_id":"uap_1ctMVQUg8jxxxxxxxxxxxx",   

     "linked_clients": [ 
        { "client_id": "KJM86F2susguvsasSeAsIxxxxxxxxxxx" }, 
	  { "client_id": "FIXwZCf5iUElvqy6eidlfxxxxxxxxxxx" }
      ] 
     }
  }' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/json' \
  --header 'authorization: Bearer {yourAccessToken}'
```

When Express Configuration is run, all of these application IDs in the linked\_clients property will be added to the `enabled_clients` property of the Okta connection.

## Publish your integration to the OIN

After you create a base configuration, you are ready to start the submission process to the OIN. As part of this process, you will be able to fully test Express Configuration end-to-end prior to going live:

1. Register your application in the OIN
2. Request an Express Configuration integration
3. Configure your OIN public key
4. Test and verify your Express Configuration integration
5. Finalize your OIN submission

### Register your application in the OIN

To add Express Configuration to a new or pre-existing application in the OIN, you need:

* An instance of your Auth0-enabled web application to use for testing
* An [Okta Integrator Free Plan org](https://developer.okta.com/signup/), with access to either the Super Admin role or the App and Org Admin roles.
  * Your Okta Integrator Free Plan org must be configured as an [Okta connection](/docs/authenticate/identity-providers/enterprise-identity-providers/okta) in your Auth0 tenant and enabled for use with your Auth0-enabled web application in order to complete basic tests
* Google Chrome browser with the Okta Browser Plugin installed (review [OIN Wizard requirements](https://developer.okta.com/docs/guides/submit-app-prereq/main/#oin-wizard-requirements))

1. Sign in to your Okta Integrator Free Plan org with the user account you used to sign up with, or with an account that has been assigned the `SUPER_ADMIN` role, or the `APP_ADMIN` and `ORG_ADMIN` admin roles in Okta.
2. Navigate to **Applications > Your OIN Integrations** in the Admin Console.
3. If this is a new application, select **Build new OIN integration**. Otherwise, select your existing OIN Integration. The OIN Wizard appears:

<Frame>
  <img alt="Configure Okta OIN" />
</Frame>

4. Under **Add integration capabilities**, select **OpenID Connect (OIDC)** as the SSO protocol.

5. You may optionally select **Universal Logout** and **SCIM 2.0**, both of which are highly recommended for all Okta integrations and supported with Express Configuration.

6. Select **Configure your integration**.

7. Complete the **OIN Catalog Properties** section as desired. For reference, read [OIN Catalog Properties](https://developer.okta.com/docs/guides/submit-oin-app/openidconnect/main/#oin-catalog-properties).

8. Under **OIDC Properties**, set the following fields:<p />
   A. **Redirect URIs** should be the callback URI for your Auth0 tenant. This can use your tenant’s custom domain or your `auth0.com` domain. <br />Example: `https://tenant.auth0.com/login/callback`<p />
   B. (Optional) Set **Initiate Login URI** to the same value you configured for your application in Auth0, as described in Auth0 application and initiate login URI. Okta will use this URL to launch your application from the [end-user dashboard](https://help.okta.com/en-us/content/topics/settings/new-dashboard-overview.htm). <br /> Example: `https://{organization_name}.your-app.com?connection={connection_name}`<p />
   C. (Optional). Set **Post-Logout URL** to the sign-out redirect URIs for your app. This is the location where you want to send your end user after they sign out of your app. You can use integration variables if your sign-out URI varies per tenant. <p />
   D. Set **Configuration guide URL** to link to your customer-facing instructions on how to configure SSO between Okta and your app with Express Configuration. To learn more, read [Customer configuration document guidelines](https://developer.okta.com/docs/guides/submit-app-prereq/main/#customer-configuration-document-guidelines).

   <Frame>
     <img alt="OIN OIDC Settings" />
   </Frame>

9. If **Universal Logout** is selected, set the following fields under Universal logout properties:<p />
   A. Set **Global token revocation** endpoint to your Auth0 tenant name. This value will be dynamically replaced when Express Configuration runs.<p />
   B. Under **Subject format**, select issuer and **Subject identifier**.<p />
   C. Check **Partial support** if you do not use [OIDC back-channel](https://auth0.com/docs/authenticate/login/logout/universal-logout#revoke-application-user-sessions) logout between Auth0 and your application but your application uses [refresh tokens](/docs/secure/tokens/refresh-tokens).<p />

   <Frame>
     <img alt="Okta Admin Console Universal Logout Settings" />
   </Frame>

10. If **SCIM 2.0** is selected, set the following fields under **SCIM provisioning properties**:<p />
    A. Set **Base URL** to your Auth0 tenant name. This value will be dynamically replaced when Express Configuration runs.<p />
    B. Under **User Operations**, select **Create**, **Update**, and **Deactivate**.<p />
    C. Set the link to your customer-facing instructions on how to configure SSO between Okta and your app with Express Configuration. Read [Customer configuration document guidelines](https://developer.okta.com/docs/guides/submit-app-prereq/main/#customer-configuration-document-guidelines).
    <Frame>
      <img alt="OIN Express Configuration SCIM Provisioning" />
    </Frame>

11. Select **Get started with testing**.

12. Proceed to the [Request an express configuration integration](/docs/authenticate/identity-providers/enterprise-identity-providers/okta/express-configuration#request-an-express-configuration-integration) section.

## Request an Express Configuration integration

To enable Express Configuration capabilities for your registered OIN Integration, you send an email to the Okta Express Configuration team at `expressconfig@okta.com` with information copied from both the Okta and Auth0 portal.

**To request an express configuration integration:**

1. Open your email application of choice and compose a new email.
2. Add the recipient: **[expressconfig@okta.com](mailto:expressconfig@okta.com)**.
3. Add the subject: **Express configuration integration request**.
4. Navigate to the [Auth0 Dashboard > Applications > Okta Integration Network > Request Integration](https://manage.auth0.com/dashboard/#/applications/#/okta-integration-network/wizard) section of Auth0 Dashboard and copy the following information into the email body.

<Frame>
  <img alt="Dashboard > Applications > OIN > Request Integrations" />
</Frame>

5. Add the name of your Okta Free Integrator Org, ex: `trial-7513274`, as well as the Okta Display name of your OIN Integration in the email.
6. Send the email.

After receiving the email, the Okta Express Configuration team enables Express Configuration for your registered OIN Integration and responds with a public key you need to upload to the Auth0 Dashboard.

### Configure your OIN public key

After receiving the public key from the Okta Express Configuration team in the previous step, upload it to the [Auth0 Dashboard > Applications > Okta Integration Network > Request Integration](https://manage.auth0.com/dashboard/#/applications/#/okta-integration-network/wizard) section of the Auth0 Dashboard. Select **Save**.

<Frame>
  <img alt="OIN Publc Key upload" />
</Frame>

### Test and verify your integration

After the public key is uploaded, you can test Express Configuration using your Okta Free Integrator organization:

1. Create an Auth0 Organization and username/password account you can share with the Okta OIN Operations team.
   * Follow the instructions in the [Example customer enablement flow](/docs/authenticate/identity-providers/enterprise-identity-providers/okta/express-configuration#example-customer-enablement-flow) to create an Auth0 Organization and username/password account for this purpose.
   * If needed, perform additional work required in your application to allow the test Organization to log in, such as creating a new application tenant.
2. Once you create a test account, sign in to your Okta Integrator Free organization as a user with either the super admin (`SUPER_ADMIN`) role, or the app (`APP_ADMIN`) and organization (`ORG_ADMIN`) admin [roles](https://developer.okta.com/docs/api/openapi/okta-management/guides/roles/#standard-roles).
3. Navigate to **Applications > Your OIN Integrations** in the Okta admin console. Select the name of your OIN integration.
4. Choose **Configure your integration**. Then choose **Get started with testing.**
5. Set **Account URL** to the login page of your application. An Okta OIN operations engineer navigates to this URL and use the account credentials you provide in the subsequent fields to sign in to your app.
6. Set **Username** and **Password** to be the username and password of a test Organization administrator account you configured for testing Express Configuration.
7. Set **Support Contact** to be the email for Okta to contact your company about your integration. This email isn't exposed in the OIN catalog or to your customers. It is only visible to the internal Okta team.
8. Under **OIDC Tests**, select **No** for Just-In Time Provisioning to skip this test, and set **SP Initiate URL** to the initiate login URL of your application instance.
   <Frame>
     <img alt="OIN integration OIDC test" />
   </Frame>
9. Select **Test your integration**.
10. Select **Generate Instance**, then **Done**.
11. Navigate to the **Sign On** tab.
12. To test Express Configuration of Single Sign-On and Universal Logout and select **Express Configure SSO & UL**.
    <Frame>
      <img alt="Express Configuration for SuperSaaS" />
    </Frame>
13. Once you are redirected to Auth0's Universal Login page, sign in with your Organization admin account and consent to data sharing.
14. To test SCIM: select **Provisioning**, and then **Express Configure SCIM**. When redirected to Auth0's Universal Login, continue through the consent prompt. Once complete, the SCIM integration is configured.
15. Next, select the **Assignments** tab and assign a user from your Okta Free Integrator organization for which you have credemtials. If a suitable user doesn't exist, then follow instructions to [Add users manually](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-add-users.htm). If SCIM is enabled, the user should be provisioned to your Auth0 tenant. Confirm using the Auth0 Dashboard.
16. To test SSO: Use the user account you just assigned and the test instance. Log in with the user account credential.
17. To test Universal Logout: follow the instructions on [Test Universal Logout](/docs/authenticate/login/logout/universal-logout#test-universal-logout).

### Finalize your submission

Basic testing is complete with the previous section. To finalize your submission, your configuration must pass some automated tests:

1. On your application instance, select **Begin Testing** to finalize your submission.
2. Next to the name of the instance you just tested with Express Configuration, select **Add to Tester**.
3. To complete the automated SSO tests, select **Run test** for the **IDP flow** and/or **SP flow** tests. These tests require the Okta Browser Plugin. To learn more, read [OIN Wizard Requirements](https://developer.okta.com/docs/guides/submit-app-prereq/main/#oin-wizard-requirements). <p />
   A. Sign in with the Okta Free Integration Organization user you assigned to the application instance. The tests passes as soon as the plugin detects you are able to successfully sign in to your application. For more information on these tests, read [Test your integration](https://developer.okta.com/docs/guides/submit-oin-app/openidconnect/main/#test-your-integration).<p />
   B. If you receive the error message `invalid_request (no connections enabled for the client)` during the login test, wait a few minutes and then try again. Newly-created connections can take a few minutes to work with features like HRD.<p />
4. To complete the required Runscope testing for **SCIM**, follow the instructions on [Test your SCIM API](https://developer.okta.com/docs/guides/submit-oin-app/scim/main/#generate-an-instance-for) using [Okta SCIM 2.0 Spec Tests](https://developer.okta.com/standards/SCIM/SCIMFiles/Okta-SCIM-20-SPEC-Test.json).<p />
   A. For a second SCIM token, use the **Authentication > Enterprise > Okta > \[your-express-configred-connection] > Provisioning >  Sync user profiles using SCIM > Setup** section.<p />
   B. Once complete, enter the shareable Runscope test URL in the **Link to Runscope spec test results** and **Link to Runscope CRUD test results** fields in the OIN Wizard.<p />
5. When complete, select **Submit Integration**.

## Customer enablement

When your application publishes in the OIN, you can update your product documentation to indicate you support Express Configuration with Okta. Your product documentation should indicate the user roles or user types have permission to perform Express Configuration.

If your application already utilizes Auth0 Organizations with Organization administrator roles as exemplified in the [SaaStart reference application](https://auth0.com/blog/speed-up-your-customer-identity-journey-with-auth0-saastart/), you can add the Express Configuration permissions to that role.

If you have not yet deployed Auth0 Organizations for your customers, or don’t implement administrative users in your application, refer to the example customer onboarding flow.

### Example customer enablement flow

In your customer onboarding process, you should collect:

* The name of the customer’s organization
* Email address of the customer administator who should have permissions to perform Express Configuration
* Verfied email domains the customer's IdP issues for users, including the domains for the administrator

Collect this information manually or using the sign up or onboarding experience for your customers. Use the information to create an Auth0 Organization and admin user account for this customer:

1. Create an Auth0 Organization
2. Create the admin user account in an Auth0 connection, such as database or email passwordless.
3. Associate the connection with the Auth0 Organization. Disable **Membership On Authentication**.
4. Add the admin user account as a member of the Auth0 Organization.
5. Assign an organizational role to the admin user with permissions to perform Express Configuration.

#### Auth0 CLI example

**Initialize Auth0 CLI and authenticate**
Authenticate with Auth0 with [Auth0 CLI](https://auth0.github.io/auth0-cli/auth0_roles_create.html).

```bash theme={null}
auth0 login --scopes "create:users,create:organizations,create:organization_members,create:organization_member_roles,create:organization_connections"
```

**Create an Auth0 Organization**
Input the name of the Organization and a short name without spaces. If you collected multiple email suffixes, add them as Organizational metadata.

```bash theme={null}
auth0 orgs create --json \
--display "organization_display_name" \
--name "organization_short_name" \
--metadata 'domains=["domain1.com", "domain2.com"]'
```

Collect the returned `org_id`.

**Create the Organization admin account**
In this example, you create a user in an email passwordless connection, requiring the [`email`](/docs/authenticate/passwordless/authentication-methods/email-otp) connection type. The command requires inputting the email address of the user you authorize to perform Express Configuration.

```bash theme={null}
auth0 api users \
--data '{"email":"user@example.com","connection":"email", "email_verified":true}'
```

<Card title="Tip">
  If you are creating this Organization to provide a username and password test account to the Okta OIN operations team, create the test account in either a shared or dedicated database connection:

  ```bash theme={null}
  auth0 api users \
  --data '{"email":"user@example.com","connection":"db_connection_name_here", "password": "add_a_long_password_here"}'
  ```
</Card>

Collect the returned `user_id`.

**Associate the connection with the Organization**

Retrieve the connection ID:

```bash theme={null}
auth0 api get "connections" -q "name=connection_name_here"
```

Associate the connection ID with the Organization ID, `org_id`.

```bash theme={null}
auth0 api post "organizations/org_id_here/enabled_connections" \
--data '{ "connection_id": "connection_id_here" };
```

**Add the admin user as a member of the Organization**
You need the `org_id` and `user_id`.

```bash theme={null}
auth0 api post "organizations/org_id_here/members" \
--data '{ "members": ["user_id__here"] }'

```

**Assign the Organization role with Express Configuration permissions**
Retrieve the role ID with Express Configuration permissions as configured in [Assign express configuration permissions to users](/docs/authenticate/identity-providers/enterprise-identity-providers/okta/express-configuration#assign-permissions-to-users).

```bash theme={null}
auth0 api get "roles" -q "name_filter=role_name_here"
```

Assign the role ID to the `user_id` and `org_id`.

```bash theme={null}
auth0 api post "organizations/org_id_here/members/user_id_here/roles" --data '{ "roles": ["role_id_here"] }'
```

Once complete, your customer can use the Organization administrator account to perform Express Configuration in their Okta organization with your [OIN integration](/docs/authenticate/identity-providers/enterprise-identity-providers/okta/express-configuration#publish-your-integration-to-the-oin).

### Recommendations to provision admin accounts

Whether you are using existing user accounts or deploying new ones to enable Express Configuration, follow the recommendations below.

#### Use work email

Whether the non-federated admin account is a database, passwordless email, or social user account, it is best to have the value of the `email` attribute match the user’s work email address that will be provisioned with their Okta Enterprise user account (example: `john@mycompany.com`).

Auth0 also recommends to verify these email addresses using an [email verification flow](/docs/manage-users/user-accounts/verify-emails).

#### Use multi-factor authentication

You can add an additional layer of security to the Express Configuration flow by requiring multi-factor authentication at each login.

The example [Post-Login Action](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) demonstrates how you can conditionally challenge for factors like [WebAuthN with device biometrics](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-device-biometrics-for-mfa) and [one-time password delivered over email](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-email-notifications-for-mfa) each time Express Configuration runs.

The example Action requires [enabling these factors](/docs/secure/multi-factor-authentication/enable-mfa#enable-mfa-in-the-auth0-dashboard) in your Auth0 tenant and selecting the **Customize MFA Factors using Actions** option.

```javascript theme={null}
exports.onExecutePostLogin = async (event, api) => {


if (event.resource_server && event.resource_server.identifier === "urn:auth0:express-configure") {


   api.multifactor.enable('any');
  api.authentication.challengeWith({ type: 'email' });


  if (!event.user.enrolledFactors.some(m => m.type === 'webauthn-platform')) {
     api.authentication.enrollWith({type: 'webauthn-platform'});
   } else {
     api.authentication.challengeWith({type: 'webauthn-platform'});
  }
 }
}
```

### Monitor Express Configuration usage

Express Configuration usage can be observed in the [Auth0 tenant logs](/docs/deploy-monitor/logs) by filtering on the **OIN Client ID** for each application you have configured. This includes all admin user login activity, as well as all API operations to create and manage the Okta Enterprise connections.

The OIN Client ID for your application can be viewed in these places:

* In the **Applications > \[Application] > Okta Integration Network > Request Integration > Request Express Configuration** section of the Auth0 Dashboard.

* In the `express_configuration.okta_oin_client_id` property of your application when viewed in the [Auth0 Management API](https://auth0.com/docs/api/management/v2/clients/get-clients-by-id).

To learn more on searching logs with Client ID, read [Log Search Query Syntax](/docs/deploy-monitor/logs/log-search-query-syntax).

## Limitations

* Only one Auth0 tenant can be used in a single OIN integration. If the same application is deployed in multiple Auth0 regions, each region requires its own OIN integration
* One OIN integration in one Okta organization can create one unique Okta connection in one corresponding Auth0 organization. Express configuration is not supported for more than one instance of an OIN application within an Okta organization
* Each unique integration listed in the OIN creates an independent Okta connection. If you have multiple applications that require an [Identifier-First login experience](https://auth0.com/docs/authenticate/login/auth0-universal-login/identifier-first) with home realm discovery, we recommend publishing [multiple applications under a single integration](/docs/authenticate/identity-providers/enterprise-identity-providers/okta/express-configuration#enable-multiple-applications-under-a-single-integration).
* When enabling [multiple applications under a single integration](/docs/authenticate/identity-providers/enterprise-identity-providers/okta/express-configuration#enable-multiple-applications-under-a-single-integration), Okta only shows the main OIN application in its [end-user dashboard](https://help.okta.com/en-us/content/topics/settings/new-dashboard-overview.htm).

## Management API reference

To use [Management API](https://auth0.com/docs/api/management/v2) instead of Auth0 Dashboard to enable Express Configuration for a given application, use the examples below.

### Create the Okta OIN Express Configuration System API

Registers the resource server which will be used to authenticate Organization Admins. This is only required if the dashboard was never used to set up Express Configuration for apps in a tenant.

Example:

```curl theme={null}
POST /api/v2/resource-servers
{
    "name": "Okta OIN Express Configuration API",
    "identifier": "urn:auth0:express-configure"
  }

```

[Endpoint reference](/docs/api/management/v2/resource-servers/post-resource-servers)

### Create User Attribute Profile

Creates a [User Attribute Profile](/docs/authenticate/enterprise-connections/user-attribute-profile). This step is only required if there are no existing profiles, or the developer wishes to use a custom profile.

To start from a set of defaults for the User Attribute profile, call the `GET /api/v2/user-attribute-profiles/templates` endpoint first and use the response in the body of the call to create the User Attribute Profile.

Example:

```curl theme={null}
GET /api/v2/user-attribute-profiles/templates
```

[Endpoint reference](https://auth0.com/docs/api/management/v2/user-attribute-profiles/post-user-attribute-profiles)

```curl theme={null}
POST /api/v2/user-attribute-profiles
{
    "name": "Okta OIN Express Configuration API",
    "identifier": "urn:auth0:express-configure"
}
```

[Endpoint reference](https://auth0.com/docs/api/management/v2/user-attribute-profiles/post-user-attribute-profiles)

### Create Connection Profile

Create a Connection Profile. This step is only required if there are no existing profiles or the developer wants to use a custom profile.

To start from a set of defaults for the Connection profile, call the `GET /api/v2/connection-profiles/templates` endpoint and use the response in the body of the call to create the Connection Profile.

Example:

```curl theme={null}
GET /api/v2/connection-profiles/templates
```

[Endpoint reference](https://auth0.com/docs/api/management/v2/connection-profiles/get-connection-profile-templates)

```curl theme={null}
POST /api/v2/connection-profile
{
    "name": "Okta OIN Express Configuration API",
    "identifier": "urn:auth0:express-configure"
}
```

[Endpoint reference](https://auth0.com/docs/api/management/v2/connection-profiles/post-connection-profiles)

### Create OIN Express Configuration Client

Create the service application that Okta will use during Express Configuration for a given application. This client must be created with the properties shown in the example below.

The `organization_require_behavior` attribute may be customized with one of the values below, which are also explained in [Administrator login and consent settings](/docs/authenticate/identity-providers/enterprise-identity-providers/okta/express-configuration#administrator-login-and-consent-settings).

* `pre_login_prompt`: Prompts for the admin’s organization prior to prompting for credentials.
* `post_login_prompt`: Prompts for the admin’s credentials. For this option, use the `PATCH /api/v2/connections/{id}` endpoint to add the Client ID of the OIN client to the `enabled_clients` property of the connection(s) containing the admin accounts.

Example:

```curl theme={null}
POST /api/v2/clients
{
    "name": "Okta OIN Express Configuration",
    "app_type": "express_configuration",
    "organization_require_behavior": "pre_login_prompt",
    "client_authentication_methods": {
      "private_key_jwt": {
        "credentials": []
      }
    }
}
```

[Endpoint reference](https://auth0.com/docs/api/management/v2/clients/post-clients)

### Configure SaaS application properties

Set the configuration values for the `express_configuration` property on the registered application that will be published to the OIN. Replace the values in the examples with a valid Connection Profile ID, User Attribute Profile ID, OIN client application ID, initiate login URI, and Auth0 tenant domain to use for this integration.

The `linked_clients` attribute corresponds to the setting described in [Enable multiple applications under a single integration](/docs/authenticate/identity-providers/enterprise-identity-providers/okta/express-configuration#enable-multiple-applications-under-a-single-integration).

The `enable_client` attribute corresponds to the setting for `enabled_clients` described in [Organization login settings](/docs/authenticate/identity-providers/enterprise-identity-providers/okta/express-configuration#organization-login-settings).

The `enable_organization` attribute should normally be set to `true`, unless you aren't assigning created connections to their organizations. The Okta app instance can still manage the connection, but Okta users will not become members of the Auth0 Organization. Setting this to false can be useful in the case described in [Maintain admin account matching across connections](/docs/authenticate/identity-providers/enterprise-identity-providers/okta/express-configuration#maintain-admin-account-matching-across-connections).

Example:

```curl theme={null}
PATCH /api/v2/clients/{id}
{
  "express_configuration": {
      "admin_login_domain": "yourAuth0TenantDomain",
      "connection_profile_id": "yourConnectionProfileId",
      "enable_client": true,
      "enable_organization": true,
      "initiate_login_uri_template": "yourInitiateLoginUriTemplate",
      "okta_oin_client_id": "yourOinClientId",
      "user_attribute_profile_id": "yourConnectionProfileId",
"linked_clients": [ 
    { "client_id": "KJM86F2susguvsasSeAsIxxxxxxxxxxx" }, 
    { "client_id": "FIXwZCf5iUElvqy6eidlfxxxxxxxxxxx" }
 ] 
    }
}
```

[Endpoint reference](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id)

### Upload Public Key

Upload the public key provided by the Okta team as a credential of the OIN client application.

Example:

```curl theme={null}
POST /api/v2/clients/{oin_client_id}/credentials
{
  "credential_type": "public_key",
  "pem": "-----BEGIN PUBLIC KEY-----\nMIGf..."
}
```

[Endpoint reference](https://auth0.com/docs/api/management/v2/clients/post-credentials)

### Assign keys to OIN client application

Assign the uploaded public keys from Okta to the OIN service client. Replace `yourCredentialId` with the credential ID received in the previous step.

Example:

```curl theme={null}
PATCH /api/v2/clients/{oin_client_id}
{
 "client_authentication_methods": {
    "private_key_jwt": {
      "credentials": [
        {
          "id": "yourCredentialId",
        }
      ]
    }
  }
}
```

[Endpoint reference](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id)

### Customize your tenants consent prompt

Update tenant settings to display the scope details on the consent page. These settings improve the user experience by providing information about the permissions being granted. This is not required but recommended.

Example:

```curl theme={null}
PATCH /api/v2/tenants/settings
{ 
  "flags": { "use_scope_descriptions_for_consent": true } 
}
```

[Endpoint reference](https://auth0.com/docs/api/management/v2/tenants/patch-settings)


# Connect Your PingFederate Server to Auth0
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/ping-federate

Learn how to create an enterprise connection between a PingFederate Server and Auth0.

Auth0 lets you create [PingFederate Server](https://documentation.pingidentity.com/pingfederate/pf84/#gettingStartedGuide/concept/gettingStarted.html) connections.

## Prerequisites

Before beginning:

* [Register your Application with Auth0](/docs/get-started/auth0-overview/create-applications).

  * Select an appropriate **Application Type**.
  * Add an **Allowed Callback URL** of **`{https://yourApp/callback}`**.
  * Make sure your Application's [Grant Types](/docs/get-started/applications/update-grant-types) include the appropriate flows.

## Steps

As long as your server is configured in the standard way, to connect your PingFederate server to Auth0 you must:

1. [Get the signing certificate from the IdP](#get-the-signing-certificate-from-the-idp) and [convert it to Base64](#convert-signing-certificate-to-base64).
2. [Create an enterprise connection in Auth0](#create-an-enterprise-connection-in-auth0).
3. [Enable the enterprise connection for your Auth0 Application](#enable-the-enterprise-connection-for-your-auth0-application).
4. [Test the connection](#test-the-connection).

<Warning>
  If additional setup is required for your server (such as attribute mapping), then you must [create a new SAML enterprise connection](/docs/authenticate/identity-providers/enterprise-identity-providers/saml) instead.
</Warning>

## Get the signing certificate from the IdP

With PingFederate Server, Auth0 acts as the service provider, so you will need to retrieve an X.509 signing certificate from the <Tooltip href="/docs/glossary?term=IdP">IdP</Tooltip> (in PEM or CER format); later, you will upload this to Auth0. The methods for retrieving this certificate vary, so please see the [PingFederate documentation](https://documentation.pingidentity.com/pingfederate/pf84/index.shtml#concept_digitalSignatureSettings.html) for instructions on managing your server's certificates.

### Convert signing certificate to Base64

Before you upload the X.509 signing certificate to Auth0, you must convert the file to Base64. To do this, either use a [simple online tool](https://www.base64decode.org/) or run the following command in Bash: `cat signing-cert.crt | base64`.

## Create an enterprise connection in Auth0

Next, if your server is configured in the standard way, you will need to create and configure a PingFederate Enterprise Connection in Auth0 and upload your X.509 signing certificate. This task can be performed using Auth0's Dashboard.

<Warning>
  If additional setup is required for your server (such as attribute mapping), then you must [create a new SAML enterprise connection](/docs/authenticate/identity-providers/enterprise-identity-providers/saml) instead.
</Warning>

1. Navigate to [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise), locate **Ping Federate**, and select its `+`.

   <Frame>
     <img alt="Dashboard - Connections - Enterprise" />
   </Frame>
2. Enter details for your connection, and select **Create:**

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Connection name</strong></td>
      <td>Logical identifier for your connection; it must be unique for your tenant. Once set, this name can't be changed.</td>
    </tr>

    <tr>
      <td><strong>PingFederate Server URL</strong></td>
      <td>URL for your PingFederate Server.</td>
    </tr>

    <tr>
      <td><strong>X.509 Signing Certificate</strong></td>
      <td>PingFederate Server public key (encoded in PEM or CER) you retrieved from the IdP earlier in this process.</td>
    </tr>

    <tr>
      <td><strong>Sign Request</strong></td>
      <td>When enabled, the SAML authentication request will be signed. (Be sure to download and provide the PingFederate server with your <a href="https://{yourDomain}/pem">tenant's certificate</a>.)</td>
    </tr>

    <tr>
      <td><strong>Sign Request Algorithm</strong></td>
      <td>Algorithm Auth0 will use to sign the SAML assertions. Ensure this matches your PingFederate Server's configuration.</td>
    </tr>

    <tr>
      <td><strong>Sign Request Digest Algorithm</strong></td>
      <td>Algorithm Auth0 will use for the sign request digest. Ensure this matches your PingFederate Server's configuration.</td>
    </tr>

    <tr>
      <td><strong>Sync user profile attributes at each login</strong></td>
      <td>When enabled, Auth0 automatically syncs user profile data with each user login, thereby ensuring that changes made in the connection source are automatically updated in Auth0.</td>
    </tr>
  </tbody>
</table>

<Frame>
  <img alt="Configure Ping Federate Settings" />
</Frame>

3\. In the **Login Experience** view, configure how users log in with this connection.

<table>
  <thead>
    <tr>
      <th><strong>Field</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Home Realm Discovery</strong></td>
      <td>Compares a user's email domain with the provided identity provider domains. For more information, read <a href="/docs/authenticate/login/auth0-universal-login/identifier-first">Configure Identifier First Authentication</a></td>
    </tr>

    <tr>
      <td><strong>Display connection button</strong></td>
      <td>This option displays the following choices to customize your application's connection button.</td>
    </tr>

    <tr>
      <td><strong>Button display name</strong> (Optional)</td>
      <td>Text used to customize the login button for Universal Login. When set the button reads: "Continue with \{Button display name}".</td>
    </tr>

    <tr>
      <td><strong>Button logo URL</strong> (Optional)</td>
      <td>URL of image used to customize the login button for Universal Login. When set, the Universal Login login button displays the image as a 20px by 20px square.</td>
    </tr>
  </tbody>
</table>

<Callout icon="file-lines">
  Optional fields are available with Universal Login only. Customers using Classic Login will not see the Add button, Button display name, or Button logo URL.
</Callout>

## Enable the enterprise connection for your Auth0 application

To use your new PingFederate enterprise connection, you must first [enable the connection](/docs/authenticate/identity-providers/enterprise-identity-providers/enable-enterprise-connections) for your Auth0 Applications.

## Test the connection

Now you're ready to [test your connection](/docs/authenticate/identity-providers/enterprise-identity-providers/test-enterprise-connections).


# Connect Your App to SAML Identity Providers
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/saml

Learn how to connect to SAML Identity Providers using an enterprise connection.

Auth0 lets you create <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> (IdP) connections.

## Prerequisites

Before beginning:

* [Register your Application with Auth0](/docs/get-started/auth0-overview/create-applications).

  * Select an appropriate **Application Type**.
  * Add an **Allowed Callback URL** of **`{https://yourApp/callback}`**.
  * Make sure your Application's [Grant Types](/docs/get-started/applications/update-grant-types) include the appropriate flows.
* Decide on the name of this enterprise connection

  * The Post-back URL (also called Assertion Consumer Service URL) becomes: `https://{yourDomain}/login/callback?connection={yourConnectionName}`
  * The Entity ID becomes: `urn:auth0:{yourTenant}:{yourConnectionName}`

## Steps

To connect your application to a SAML Identity Provider, you must:

1. Enter the Post-back URL and Entity ID at the IdP (to learn how, read about [SAML Identity Provider Configuration Settings](/docs/authenticate/protocols/saml/saml-identity-provider-configuration-settings)).
2. [Get the signing certificate from the IdP](#get-the-signing-certificate-from-the-idp) and [convert it to Base64](#convert-signing-certificate-to-base64).
3. [Create an enterprise connection in Auth0](#create-an-enterprise-connection-in-auth0).
4. [Enable the enterprise connection for your Auth0 Application](#enable-the-enterprise-connection-for-your-auth0-application).
5. [Set up mappings](#set-up-mappings) (unnecessary for most cases).
6. [Test the connection](#test-the-connection).

## Get the signing certificate from the IdP

With SAML Login, Auth0 acts as the service provider, so you will need to retrieve an X.509 signing certificate from the SAML IdP (in PEM or CER format); later, you will upload this to Auth0. The methods for retrieving this certificate vary, so please see your IdP's documentation if you need additional assistance.

### Convert signing certificate to Base64

You can use the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> or the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> to upload the X.509 signing certificate. If you use the Management API, you must convert the file to Base64. To do this, either use a [simple online tool](https://www.base64decode.org/) or run the following command in Bash: `cat signing-cert.crt | base64`.

## Create an enterprise connection in Auth0

Next, you will need to create and configure a SAML Enterprise Connection in Auth0 and upload your X.509 signing certificate. This task can be performed using either Auth0's Dashboard or Management API.

### Create an enterprise connection using the Dashboard

1. Navigate to [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise), locate **SAML**, and select its `+`.

   <Frame>
     <img alt="Dashboard - Connections - Enterprise" />
   </Frame>
2. Enter details for your connection, and select **Create:**

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Connection name</strong></td>
      <td>Logical identifier for your connection; it must be unique for your tenant and the same name used when setting the Post-back URL and Entity ID at the IdP. Once set, this name can't be changed.</td>
    </tr>

    <tr>
      <td><strong>Sign In URL</strong></td>
      <td>SAML single login URL.</td>
    </tr>

    <tr>
      <td><strong>X.509 Signing Certificate</strong></td>
      <td>Signing certificate (encoded in PEM or CER) you retrieved from the IdP earlier in this process.</td>
    </tr>

    <tr>
      <td><strong>Enable Sign Out</strong></td>
      <td>When enabled, a specific Sign Out URL can be set. Otherwise, the Sign In URL is used by default.</td>
    </tr>

    <tr>
      <td><strong>Sign Out URL</strong> (optional)</td>
      <td>SAML single logout URL.</td>
    </tr>

    <tr>
      <td><strong>User ID Attribute</strong> (optional)</td>
      <td>Attribute in the SAML token that will be mapped to the <code>user\_id</code> property in Auth0.</td>
    </tr>

    <tr>
      <td><strong>Debug Mode</strong></td>
      <td>When enabled, more verbose logging will be performed during the authentication process.</td>
    </tr>

    <tr>
      <td><strong>Sign Request</strong></td>
      <td>When enabled, the SAML authentication request will be signed. (Be sure to download and provide the accompanying certificate so the SAML IdP can validate the assertions' signature.)</td>
    </tr>

    <tr>
      <td><strong>Sign Request Algorithm</strong></td>
      <td>Algorithm Auth0 will use to sign the SAML assertions.</td>
    </tr>

    <tr>
      <td><strong>Sign Request Digest Algorithm</strong></td>
      <td>Algorithm Auth0 will use for the sign request digest.</td>
    </tr>

    <tr>
      <td><strong>Protocol Binding</strong></td>
      <td>HTTP binding supported by the IdP.</td>
    </tr>

    <tr>
      <td><strong>Request Template</strong> (optional)</td>
      <td>Template that formats the SAML request.</td>
    </tr>
  </tbody>
</table>

<Frame>
  <img alt="Configure SAML Settings" />
</Frame>

3\. In the **Provisioning** view, configure how user profiles get created and updated in Auth0.

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Sync user profile attributes at each login</strong></td>
      <td>When enabled, Auth0 automatically syncs user profile data with each user login, thereby ensuring that changes made in the connection source are automatically updated in Auth0.</td>
    </tr>

    <tr>
      <td><strong>Sync user profiles using SCIM</strong></td>
      <td>When enabled, Auth0 allows user profile data to be synced using SCIM. For more information, see <a href="/docs/authenticate/protocols/scim/configure-inbound-scim">Configure Inbound SCIM</a>.</td>
    </tr>
  </tbody>
</table>

4. In the **Login Experience** view, configure how users log in with this connection.

<table>
  <thead>
    <tr>
      <th><strong>Field</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Home Realm Discovery</strong></td>
      <td>Compares a user's email domain with the provided identity provider domains. For more information, read <a href="/docs/authenticate/login/auth0-universal-login/identifier-first">Configure Identifier First Authentication</a></td>
    </tr>

    <tr>
      <td><strong>Display connection button</strong></td>
      <td>This option displays the following choices to customize your application's connection button.</td>
    </tr>

    <tr>
      <td><strong>Button display name</strong> (Optional)</td>
      <td>Text used to customize the login button for Universal Login. When set the button reads: "Continue with \{Button display name}".</td>
    </tr>

    <tr>
      <td><strong>Button logo URL</strong> (Optional)</td>
      <td>URL of image used to customize the login button for Universal Login. When set, the Universal Login login button displays the image as a 20px by 20px square.</td>
    </tr>
  </tbody>
</table>

<Callout icon="file-lines">
  Optional fields are available with Universal Login only. Customers using Classic Login will not see the Add button, Button display name, or Button logo URL.
</Callout>

5. If you have appropriate administrative permissions to complete the integration, click **Continue** to learn about the custom parameters needed to configure your IdP. Otherwise, provide the given URL to your administrator so that they can adjust the required settings.

### Create an enterprise connection using the Management API

You can also use the [Management API](https://auth0.com/docs/api/management/v2) to create your SAML Connection. When doing so, you may choose to specify each SAML configuration field manually or else specify a SAML metadata document that contains the configuration values.

#### Create a connection using specified values

Make a `POST` call to the [Create a Connection endpoint](https://auth0.com/docs/api/management/v2#!/Connections/patch_connections_by_id). Be sure to replace `MGMT_API_ACCESS_TOKEN`, `CONNECTION_NAME`, `SIGN_IN_ENDPOINT_URL`, `SIGN_OUT_ENDPOINT_URL`, and `BASE64_SIGNING_CERT` placeholder values with your Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, connection name, sign in URL, sign out URL, and Base64-encoded signing certificate (in PEM or CER format), respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/connections' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "strategy": "samlp", "name": "CONNECTION_NAME", "options": { "signInEndpoint": "SIGN_IN_ENDPOINT_URL", "signOutEndpoint": "SIGN_OUT_ENDPOINT_URL", "signatureAlgorithm": "rsa-sha256", "digestAlgorithm": "sha256", "fieldsMap": {}, "signingCert": "BASE64_SIGNING_CERT" } }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/connections");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("application/json", "{ "strategy": "samlp", "name": "CONNECTION_NAME", "options": { "signInEndpoint": "SIGN_IN_ENDPOINT_URL", "signOutEndpoint": "SIGN_OUT_ENDPOINT_URL", "signatureAlgorithm": "rsa-sha256", "digestAlgorithm": "sha256", "fieldsMap": {}, "signingCert": "BASE64_SIGNING_CERT" } }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/connections"

  	payload := strings.NewReader("{ "strategy": "samlp", "name": "CONNECTION_NAME", "options": { "signInEndpoint": "SIGN_IN_ENDPOINT_URL", "signOutEndpoint": "SIGN_OUT_ENDPOINT_URL", "signatureAlgorithm": "rsa-sha256", "digestAlgorithm": "sha256", "fieldsMap": {}, "signingCert": "BASE64_SIGNING_CERT" } }")

  	req, _ := http.NewRequest("POST", 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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/connections")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "strategy": "samlp", "name": "CONNECTION_NAME", "options": { "signInEndpoint": "SIGN_IN_ENDPOINT_URL", "signOutEndpoint": "SIGN_OUT_ENDPOINT_URL", "signatureAlgorithm": "rsa-sha256", "digestAlgorithm": "sha256", "fieldsMap": {}, "signingCert": "BASE64_SIGNING_CERT" } }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/connections',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: {
      strategy: 'samlp',
      name: 'CONNECTION_NAME',
      options: {
        signInEndpoint: 'SIGN_IN_ENDPOINT_URL',
        signOutEndpoint: 'SIGN_OUT_ENDPOINT_URL',
        signatureAlgorithm: 'rsa-sha256',
        digestAlgorithm: 'sha256',
        fieldsMap: {},
        signingCert: 'BASE64_SIGNING_CERT'
      }
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"strategy": @"samlp",
                                @"name": @"CONNECTION_NAME",
                                @"options": @{ @"signInEndpoint": @"SIGN_IN_ENDPOINT_URL", @"signOutEndpoint": @"SIGN_OUT_ENDPOINT_URL", @"signatureAlgorithm": @"rsa-sha256", @"digestAlgorithm": @"sha256", @"fieldsMap": @{  }, @"signingCert": @"BASE64_SIGNING_CERT" } };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/connections"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/connections",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "strategy": "samlp", "name": "CONNECTION_NAME", "options": { "signInEndpoint": "SIGN_IN_ENDPOINT_URL", "signOutEndpoint": "SIGN_OUT_ENDPOINT_URL", "signatureAlgorithm": "rsa-sha256", "digestAlgorithm": "sha256", "fieldsMap": {}, "signingCert": "BASE64_SIGNING_CERT" } }",
    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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "strategy": "samlp", "name": "CONNECTION_NAME", "options": { "signInEndpoint": "SIGN_IN_ENDPOINT_URL", "signOutEndpoint": "SIGN_OUT_ENDPOINT_URL", "signatureAlgorithm": "rsa-sha256", "digestAlgorithm": "sha256", "fieldsMap": {}, "signingCert": "BASE64_SIGNING_CERT" } }"

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

  conn.request("POST", "/{yourDomain}/api/v2/connections", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/connections")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request["cache-control"] = 'no-cache'
  request.body = "{ "strategy": "samlp", "name": "CONNECTION_NAME", "options": { "signInEndpoint": "SIGN_IN_ENDPOINT_URL", "signOutEndpoint": "SIGN_OUT_ENDPOINT_URL", "signatureAlgorithm": "rsa-sha256", "digestAlgorithm": "sha256", "fieldsMap": {}, "signingCert": "BASE64_SIGNING_CERT" } }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = [
    "strategy": "samlp",
    "name": "CONNECTION_NAME",
    "options": [
      "signInEndpoint": "SIGN_IN_ENDPOINT_URL",
      "signOutEndpoint": "SIGN_OUT_ENDPOINT_URL",
      "signatureAlgorithm": "rsa-sha256",
      "digestAlgorithm": "sha256",
      "fieldsMap": [],
      "signingCert": "BASE64_SIGNING_CERT"
    ]
  ] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/connections")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td><a href="https://auth0.com/docs/api/management/v2/tokens">Access Token for the Management API</a> with the scope <code>create:connections</code>.</td>
    </tr>

    <tr>
      <td><code>CONNECTION\_NAME</code></td>
      <td>Τhe name of the connection to be created.</td>
    </tr>

    <tr>
      <td><code>SIGN\_IN\_ENDPONT\_URL</code></td>
      <td>SAML single login URL for the connection to be created.</td>
    </tr>

    <tr>
      <td><code>SIGN\_OUT\_ENDPOINT\_URL</code></td>
      <td>SAML single logout URL for the connection to be created.</td>
    </tr>

    <tr>
      <td><code>BASE64\_SIGNING\_CERT</code></td>
      <td>X.509 signing certificate (encoded in PEM or CER) you retrieved from the IdP.</td>
    </tr>
  </tbody>
</table>

Or, in JSON:

```json lines theme={null}
{
	"strategy": "samlp",
  	"name": "CONNECTION_NAME",
  	"options": {
    	"signInEndpoint": "SIGN_IN_ENDPOINT_URL",
    	"signOutEndpoint": "SIGN_OUT_ENDPOINT_URL",
    	"signatureAlgorithm": "rsa-sha256",
    	"digestAlgorithm": "sha256",
    	"fieldsMap": {
     		...
    	},
    	"signingCert": "BASE64_SIGNING_CERT"
  	}
}
```

#### Create a connection using SAML metadata

Rather than specifying each SAML configuration field, you can specify a SAML metadata document that contains the configuration values. When specifying a SAML metadata document, you may provide either the XML content of the document (`metadataXml`) or the URL of the document (`metadataUrl`). When providing the URL, content is downloaded only once; the connection will not automatically reconfigure if the content of the URL changes in the future.

##### Provide metadata document content

Use the `metadataXml` option to provide content of the document:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/connections' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "strategy": "samlp", "name": "CONNECTION_NAME", "options": { "metadataXml": "<EntityDescriptor entityID='''urn:saml-idp''' xmlns='''urn:oasis:names:tc:SAML:2.0:metadata'''>...</EntityDescriptor>" } }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/connections");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("application/json", "{ "strategy": "samlp", "name": "CONNECTION_NAME", "options": { "metadataXml": "<EntityDescriptor entityID='urn:saml-idp' xmlns='urn:oasis:names:tc:SAML:2.0:metadata'>...</EntityDescriptor>" } }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/connections"

  	payload := strings.NewReader("{ "strategy": "samlp", "name": "CONNECTION_NAME", "options": { "metadataXml": "<EntityDescriptor entityID='urn:saml-idp' xmlns='urn:oasis:names:tc:SAML:2.0:metadata'>...</EntityDescriptor>" } }")

  	req, _ := http.NewRequest("POST", 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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/connections")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "strategy": "samlp", "name": "CONNECTION_NAME", "options": { "metadataXml": "<EntityDescriptor entityID='urn:saml-idp' xmlns='urn:oasis:names:tc:SAML:2.0:metadata'>...</EntityDescriptor>" } }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/connections',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: {
      strategy: 'samlp',
      name: 'CONNECTION_NAME',
      options: {
        metadataXml: '<EntityDescriptor entityID='urn:saml-idp' xmlns='urn:oasis:names:tc:SAML:2.0:metadata'>...</EntityDescriptor>'
      }
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"strategy": @"samlp",
                                @"name": @"CONNECTION_NAME",
                                @"options": @{ @"metadataXml": @"<EntityDescriptor entityID='urn:saml-idp' xmlns='urn:oasis:names:tc:SAML:2.0:metadata'>...</EntityDescriptor>" } };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/connections"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/connections",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "strategy": "samlp", "name": "CONNECTION_NAME", "options": { "metadataXml": "<EntityDescriptor entityID='urn:saml-idp' xmlns='urn:oasis:names:tc:SAML:2.0:metadata'>...</EntityDescriptor>" } }",
    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;
  }
  ```

  ```python Python theme={null}
  iimport http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "strategy": "samlp", "name": "CONNECTION_NAME", "options": { "metadataXml": "<EntityDescriptor entityID='urn:saml-idp' xmlns='urn:oasis:names:tc:SAML:2.0:metadata'>...</EntityDescriptor>" } }"

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

  conn.request("POST", "/{yourDomain}/api/v2/connections", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/connections")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request["cache-control"] = 'no-cache'
  request.body = "{ "strategy": "samlp", "name": "CONNECTION_NAME", "options": { "metadataXml": "<EntityDescriptor entityID='urn:saml-idp' xmlns='urn:oasis:names:tc:SAML:2.0:metadata'>...</EntityDescriptor>" } }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = [
    "strategy": "samlp",
    "name": "CONNECTION_NAME",
    "options": ["metadataXml": "<EntityDescriptor entityID='urn:saml-idp' xmlns='urn:oasis:names:tc:SAML:2.0:metadata'>...</EntityDescriptor>"]
  ] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/connections")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

##### Provide a metadata document URL

Use the `metadataUrl` option to provide the URL of the document:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/connections' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "strategy": "samlp", "name": "CONNECTION_NAME", "options": { "metadataUrl": "https://saml-idp/samlp/metadata/uarlU13n63e0feZNJxOCNZ1To3a9H7jX" } }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/connections");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("application/json", "{ "strategy": "samlp", "name": "CONNECTION_NAME", "options": { "metadataUrl": "https://saml-idp/samlp/metadata/uarlU13n63e0feZNJxOCNZ1To3a9H7jX" } }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/connections"

  	payload := strings.NewReader("{ "strategy": "samlp", "name": "CONNECTION_NAME", "options": { "metadataUrl": "https://saml-idp/samlp/metadata/uarlU13n63e0feZNJxOCNZ1To3a9H7jX" } }")

  	req, _ := http.NewRequest("POST", 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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/connections")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "strategy": "samlp", "name": "CONNECTION_NAME", "options": { "metadataUrl": "https://saml-idp/samlp/metadata/uarlU13n63e0feZNJxOCNZ1To3a9H7jX" } }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/connections',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: {
      strategy: 'samlp',
      name: 'CONNECTION_NAME',
      options: {
        metadataUrl: 'https://saml-idp/samlp/metadata/uarlU13n63e0feZNJxOCNZ1To3a9H7jX'
      }
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"strategy": @"samlp",
                                @"name": @"CONNECTION_NAME",
                                @"options": @{ @"metadataUrl": @"https://saml-idp/samlp/metadata/uarlU13n63e0feZNJxOCNZ1To3a9H7jX" } };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/connections"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/connections",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "strategy": "samlp", "name": "CONNECTION_NAME", "options": { "metadataUrl": "https://saml-idp/samlp/metadata/uarlU13n63e0feZNJxOCNZ1To3a9H7jX" } }",
    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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "strategy": "samlp", "name": "CONNECTION_NAME", "options": { "metadataUrl": "https://saml-idp/samlp/metadata/uarlU13n63e0feZNJxOCNZ1To3a9H7jX" } }"

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

  conn.request("POST", "/{yourDomain}/api/v2/connections", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/connections")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request["cache-control"] = 'no-cache'
  request.body = "{ "strategy": "samlp", "name": "CONNECTION_NAME", "options": { "metadataUrl": "https://saml-idp/samlp/metadata/uarlU13n63e0feZNJxOCNZ1To3a9H7jX" } }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = [
    "strategy": "samlp",
    "name": "CONNECTION_NAME",
    "options": ["metadataUrl": "https://saml-idp/samlp/metadata/uarlU13n63e0feZNJxOCNZ1To3a9H7jX"]
  ] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/connections")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

When providing the URL, content is downloaded only once; the connection will not automatically reconfigure if the content of the URL changes in the future.

##### Refresh existing connection information with metadata URL

<Callout icon="file-lines">
  This process will only work if the connection was created with `metadataUrl` manually.
</Callout>

If you have a B2B implementation and federate to Auth0 with your own SAML identity provider, you may need to refresh connection information stored in Auth0, such as signing certificate changes, endpoint URL changes, or new assertion fields. Auth0 does this automatically for ADFS connections, but not for SAML connections.

You can create a batch process (cron job) to do a periodic refresh. The process can run every few weeks and perform a PATCH call to `/api/v2/connections/CONNECTION_ID` endpoint, passing a body containing `{options: {metadataUrl: '$URL'}}` where `$URL` is the same metadata URL with which you created the connection. You use the metadata URL to create a new temporary connection, then compare the properties of the old and new connections. If anything is different, update the new connection and then delete the temporary connection.

1. Create SAML connection with `options.metadataUrl`. The connection object will be populated with information from the metadata.
2. Update metadata content in the URL.
3. Send a PATCH to the `/api/v2/connections/CONNECTION_ID` endpoint with `{options: {metadataUrl: '$URL'}}`. Now the connection object is updated with the new metadata content.

<Warning>
  If you use the `options` parameter, you override the entire `options` object. Be sure all parameters are present.
</Warning>

## Specify a custom Entity ID

To specify a custom Entity ID, use the Management API to override the default `urn:auth0:YOUR_TENANT:YOUR_CONNECTION_NAME`. Set the `connection.options.entityID` property when the connection is first created or by updating an existing connection.

The JSON example below can be used to create a new SAML connection using the SAML IdP’s metadata URL while also specifying a custom Entity ID. The Entity ID is still unique since it is created using the name of the connection.

```json lines theme={null}
{
  "strategy": "samlp", 
  "name": "{yourConnectionName}", 
  "options": { 
    "metadataUrl": "https://saml-idp/samlp/metadata/uarlU13n63e0feZNJxOCNZ1To3a9H7jX",
    "entityId": "urn:your-custom-sp-name:{yourConnectionName}"
  }
}
```

## Enable the enterprise connection for your Auth0 application

To use your new SAML enterprise connection, you must first [enable the connection](/docs/authenticate/identity-providers/enterprise-identity-providers/enable-enterprise-connections) for your Auth0 Applications.

## Set up mappings

<Warning>
  If you're configuring a SAML enterprise connection for a non-standard PingFederate Server, you **must** update the attribute mappings.
</Warning>

Select the **Mappings** view, enter mappings between the `{}`, and select **Save**.

<Frame>
  <img alt="Configure SAML Mappings" />
</Frame>

**Mappings for non-standard PingFederate Servers:**

```json lines theme={null}
{
    "user_id": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
    "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier"
}
```

**Mappings for <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> Circle**

```json lines theme={null}
{
  "email": "EmailAddress",
  "given_name": "FirstName",
  "family_name": "LastName"
}
```

**Map either of two claims to one user attribute**

```json lines theme={null}
{
  "given_name": [
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
  ]
}
```

**How to map name identifier to a user attribute**

```json lines theme={null}
{
  "user_id": [
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
  ]
}
```

## Test the connection

Now you're ready to [test your connection](/docs/authenticate/identity-providers/enterprise-identity-providers/test-enterprise-connections).

## Configure Global Token Revocation

This connection type supports a Global Token Revocation endpoint, which allows a compliant identity provider to revoke Auth0 user sessions, revoke <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip>, and trigger back-channel logout for applications using a secure back-channel.

This feature can be used with Universal Logout in Okta Workforce Identity.

For more information and configuration instructions, see [Universal Logout](/docs/authenticate/login/logout/universal-logout).

## Learn more

* [Universal Logout](/docs/authenticate/login/logout/universal-logout)


# Test Enterprise Connections
Source: https://auth0.com/docs/authenticate/identity-providers/enterprise-identity-providers/test-enterprise-connections

Learn how to test enterprise connections for applications using the Auth Dashboard.

You can test enterprise connections for applications using Auth0's Dashboard.

To properly test, you should have already [set up your enterprise connection](/docs/authenticate/identity-providers/enterprise-identity-providers/enable-enterprise-connections).

1. Navigate to [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise), and select the connection type to view.

   <Frame>
     <img alt="Dashboard - Connections - Enterprise" />
   </Frame>
2. Select the **Try** arrow next to the connection you want to test.

   <Frame>
     <img alt="Dashboard - Connections - Enterprise - AD/LDAP - List" />
   </Frame>
3. Log in and consent to allow access to your app. If you have configured everything correctly, you will see the **It Works!** page.

   <Frame>
     <img alt="Dashboard - Connections - Database - Try - Success" />
   </Frame>


# Legal Identity Providers
Source: https://auth0.com/docs/authenticate/identity-providers/legal

Learn about legal identity providers supported by Auth0.

Through our partner, Criipto, we offer a range of different, and often proprietary, e-ID services of the EU. To explore available options, visit [Auth0 Marketplace: Criipto](https://marketplace.auth0.com/integrations/criipto-verify-e-id).

If you don't find what you need here, please contact [Criipto](https://criipto.com).


# Locate the Connection ID or Name
Source: https://auth0.com/docs/authenticate/identity-providers/locate-the-connection-id

Learn how to find the ID of a connection.

Some user management tasks require a connection ID, which is a unique identifier for a source of users. For example, if you import or export users or connect to <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip>, you must provide a connection ID.

1. Go to [Auth0 Dashboard](https://manage.auth0.com/#/), select **Authentication**, then select the type of connection for which you need the ID.
2. Select the name of the connection for which you need the ID.
3. On the **Settings** view, locate the **Name** field; it contains the connection ID.


# Connect Your Auth0 Application with Okta Workforce Enterprise Connection
Source: https://auth0.com/docs/authenticate/identity-providers/okta

Learn how to connect to Okta as an OpenID Connect (OIDC) Identity Provider using an enterprise connection.

The Okta Workforce Enterprise connection is an officially-supported, streamlined integration, and the preferred method to implement Okta as an <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> (IdP) in Auth0.

This integration allows your customers to manage their employees' access to your application with Okta.

Additionally, if you are using Auth0 for customer identity management and Okta for workforce identity management internally, this integration is effective way to manage your identity spaces.

If the Okta Workforce Enterprise connection does not support your use case, you can [configure Okta as a SAML IdP](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-okta-as-saml-identity-provider) or [configure a custom authorization server](https://developer.okta.com/docs/concepts/auth-servers/#custom-authorization-server) to serve your needs.

## Create Okta OIDC app integration

To learn how to create an Okta OIDC app integration, read [Create OIDC app integrations on Okta Help Center](https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_OIDC.htm).

Use the following settings when you set up your Okta OIDC app integration:

1. Select **OIDC** as the **Sign-in method**.
2. Select **Web application** as the **Application type**, and set the following parameters:

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Name</td>
      <td>The name of your application.</td>
    </tr>

    <tr>
      <td>Sign-in Redirect URIs</td>
      <td>`https://{YOUR_AUTH0_TENANT}.{YOUR_TENANT_REGION}.auth0.com/login/callback`</td>
    </tr>

    <tr>
      <td>Trusted Origins</td>
      <td>`https://{yourDomain}`</td>
    </tr>
  </tbody>
</table>

<Card title="Find your Auth0 domain name for redirects">
  If your Auth0 domain name is not shown above and you are not using our [custom domains](/docs/customize/custom-domains) feature, your domain name is a concatenation of your tenant name, your regional subdomain, and `auth0.com`, separated by the dot (`.`) symbol.

  For example, if your tenant name is `exampleco-enterprises`, and your tenant is in the US region, your Auth0 domain name would be `exampleco-enterprises.us.auth0.com` and your **Redirect URI** would be `https://exampleco-enterprises.us.auth0.com/login/callback`.

  However, if your tenant is in the US region and was created before June 2020, then your Auth0 domain name would be `exampleco-enterprises.auth0.com` and your **Redirect URI** would be `https://exampleco-enterprises.auth0.com/login/callback`.

  If you are using [custom domains](/docs/customize/custom-domains), your **Redirect URI** would be `https://<YOUR CUSTOM DOMAIN>/login/callback`.
</Card>

3. Record the **Client ID** and **Client Secret** that Okta generates for your app integration.

## Add test user to Okta app integration

Create a test user in your Okta Directory to test your app integration:

1. In your Okta Admin Dashboard, navigate to **Directory > People**.
2. Select **Add Person**.
3. Enter user test details, including a password.
4. Save the test user.
5. In the **Directory**, select the new user
6. Navigate to the **Applications** tab for the user and choose **Assign Applications**.
7. Select the application name you created in the previously.

## Create Okta Workforce Enterprise connection in Auth0

Ensure you have the **<Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>** and **<Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip>** of your Okta OIDC app integration available:

1. Go to [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise), locate **Okta Workforce**, and then select the **+** button.

   <Frame>
     <img alt="Dashboard - Connections - Enterprise" />
   </Frame>
2. Enter details for your connection, and then select **Create:**

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Connection name</strong></td>
      <td>Logical identifier for your connection; it must be unique for your tenant. Once set, this name can't be changed.</td>
    </tr>

    <tr>
      <td><strong>Okta Domain</strong></td>
      <td>Okta's domain name for your organization.</td>
    </tr>

    <tr>
      <td><strong>Client ID</strong></td>
      <td>Unique identifier for your registered Okta application. Enter the saved value of the <strong>Client ID</strong> for the app you just registered in the Okta admin console.</td>
    </tr>

    <tr>
      <td><strong>Client Secret</strong></td>
      <td>String used to gain access to your registered Okta application. Enter the saved value of the <strong>Client Secret</strong> for the app you just registered in the Okta admin console.</td>
    </tr>
  </tbody>
</table>

3. In the **Provisioning** view, configure how user profiles get created and updated in Auth0.

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Sync user profile attributes at each login</strong></td>
      <td>When enabled, Auth0 automatically syncs user profile data with each user login, thereby ensuring that changes made in the connection source are automatically updated in Auth0.</td>
    </tr>

    <tr>
      <td><strong>Sync user profiles using SCIM</strong></td>
      <td>When enabled, Auth0 allows user profile data to be synced using SCIM. For more information, see <a href="/docs/authenticate/protocols/scim/configure-inbound-scim">Configure Inbound SCIM</a>.</td>
    </tr>
  </tbody>
</table>

4. Switch to the **Login Experience** view, and configure how your users log in with this connection:

<table>
  <thead>
    <tr>
      <th><strong>Field</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Home Realm Discovery</strong></td>
      <td>Compares a user's email domain with the provided identity provider domains. For more information, read <a href="/docs/authenticate/login/auth0-universal-login/identifier-first">Configure Identifier First Authentication</a></td>
    </tr>

    <tr>
      <td><strong>Display connection button</strong></td>
      <td>This option displays the following choices to customize your application's connection button.</td>
    </tr>

    <tr>
      <td><strong>Button display name</strong> (Optional)</td>
      <td>Text used to customize the login button for Universal Login. When set the button reads: "Continue with \{Button display name}".</td>
    </tr>

    <tr>
      <td><strong>Button logo URL</strong> (Optional)</td>
      <td>URL of image used to customize the login button for Universal Login. When set, the Universal Login login button displays the image as a 20px by 20px square.</td>
    </tr>
  </tbody>
</table>

<Callout icon="file-lines">
  Optional fields are available with Universal Login only. Customers using Classic Login will not see the Add button, Button display name, or Button logo URL.
</Callout>

## Enable connection for Auth0 applications

To use your new Okta Workforce Enterprise connection, you must [enable the connection](/docs/authenticate/identity-providers/enterprise-identity-providers/enable-enterprise-connections) for your Auth0 Applications.

## Test the connection

Now you're ready to [test your connection](/docs/authenticate/identity-providers/enterprise-identity-providers/test-enterprise-connections).

## Configure Global Token Revocation

This connection type supports a Global Token Revocation endpoint, which allows a compliant identity provider to revoke Auth0 user sessions, revoke <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip>, and trigger back-channel logout for applications using a secure back-channel.

This feature can be used with Okta's Universal Logout.

For more information and configuration instructions, see [Universal Logout](/docs/authenticate/login/logout/universal-logout).

## Learn more

* [Handle Declined Authorization Permissions](/docs/authenticate/identity-providers/social-identity-providers/reprompt-permissions)
* [Pass Parameters to Identity Providers](/docs/authenticate/identity-providers/pass-parameters-to-idps)
* [Authentication and Authorization Flows](/docs/get-started/authentication-and-authorization-flow)


# Pass Parameters to Identity Providers
Source: https://auth0.com/docs/authenticate/identity-providers/pass-parameters-to-idps

Describes how to pass parameters to an Identity Provider API.

You can pass provider-specific parameters to an <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> (IdP) during authentication. The values can either be static per connection or dynamic per user.

## Limitations

For this configuration, be aware of the following restrictions:

* Only [valid OAuth 2.0/OIDC parameters](http://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint) are accepted.
* Not all IdPs support upstream parameters. Check with the specific IdP before you proceed with your implementation.
* <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> IdPs do not support upstream parameters.

## Static parameters

Use static parameters to configure your connection to send a standard set of parameters to the IdP when a user logs in.

To configure static parameters, call the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> [Create a connection](https://auth0.com/docs/api/management/v2/#!/Connections/post_connections) or [Update a connection](https://auth0.com/docs/api/management/v2/#!/Connections/patch_connections_by_id) endpoint, and pass the `upstream_params` object in the `options` object with the parameters you'd like to send to the IdP.

### Example: WordPress

WordPress allows you to pass an optional `blog` parameter to its <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> authorization endpoint, and automatically request access to a specified blog for users when they log in. To learn more, read [WordPress's OAuth 2.0 documentation](https://developer.wordpress.com/docs/oauth2/).

To follow this example, you'll need a working [WordPress Social connection](https://marketplace.auth0.com/integrations/wordpress-social-connection).

#### Get the connection

Call the Management API [Get a connection](https://auth0.com/docs/api/management/v2#!/Connections/get_connections_by_id) endpoint to retrieve the existing values of the `options` object:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/{YOUR_WORDPRESS_CONNECTION_ID} \
    --header 'authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
    --header 'content-type: application/json'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/{YOUR_WORDPRESS_CONNECTION_ID}");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer {YOUR_MANAGEMENT_API_TOKEN}");
  request.AddHeader("content-type", "application/json");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/{YOUR_WORDPRESS_CONNECTION_ID}"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer {YOUR_MANAGEMENT_API_TOKEN}")
  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/{YOUR_WORDPRESS_CONNECTION_ID}")
    .header("authorization", "Bearer {YOUR_MANAGEMENT_API_TOKEN}")
    .header("content-type", "application/json")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/{YOUR_WORDPRESS_CONNECTION_ID}',
    headers: {
      authorization: 'Bearer {YOUR_MANAGEMENT_API_TOKEN}',
      'content-type': 'application/json'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/{YOUR_WORDPRESS_CONNECTION_ID}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}",
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = {
      'authorization': "Bearer {YOUR_MANAGEMENT_API_TOKEN}",
      'content-type': "application/json"
      }

  conn.request("GET", "/{YOUR_AUTH0_DOMAIN}/api/v2/connections/{YOUR_WORDPRESS_CONNECTION_ID}", headers=headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/{YOUR_WORDPRESS_CONNECTION_ID}")

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

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer {YOUR_MANAGEMENT_API_TOKEN}'
  request["content-type"] = 'application/json'

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

The `options` object will look similar to:

```json lines theme={null}
{
  "options": {
    "client_id": "", 
    "profile": true, 
    "scope": ["profile"]
  }
}
```

#### Update the connection (static)

Copy the existing `options` object, and then add the `upstream_params` object with the `blog` field as an attribute:

```json lines theme={null}
{
  "options": {
    "client_id": "", 
    "profile": true, 
    "scope": ["profile"],
    "upstream_params": {
      "blog": {"value":"myblog.wordpress.com"}
    }
  }
}
```

Call the Management API [Update a connection](https://auth0.com/docs/api/management/v2/#!/Connections/patch_connections_by_id) endpoint with the `options` object in the body:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/%7ByourWordpressConnectionId%7D' \
    --header 'authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
    --header 'content-type: application/json' \
    --data '{"options":{"client_id":"","profile":true,"scope":["profile"],"upstream_params":{"blog":{"value":"myblog.wordpress.com"}}}}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/%7ByourWordpressConnectionId%7D");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("authorization", "Bearer {YOUR_MANAGEMENT_API_TOKEN}");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"options":{"client_id":"","profile":true,"scope":["profile"],"upstream_params":{"blog":{"value":"myblog.wordpress.com"}}}}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/%7ByourWordpressConnectionId%7D"

  	payload := strings.NewReader("{"options":{"client_id":"","profile":true,"scope":["profile"],"upstream_params":{"blog":{"value":"myblog.wordpress.com"}}}}")

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

  	req.Header.Add("authorization", "Bearer {YOUR_MANAGEMENT_API_TOKEN}")
  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/%7ByourWordpressConnectionId%7D")
    .header("authorization", "Bearer {YOUR_MANAGEMENT_API_TOKEN}")
    .header("content-type", "application/json")
    .body("{"options":{"client_id":"","profile":true,"scope":["profile"],"upstream_params":{"blog":{"value":"myblog.wordpress.com"}}}}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/%7ByourWordpressConnectionId%7D',
    headers: {
      authorization: 'Bearer {YOUR_MANAGEMENT_API_TOKEN}',
      'content-type': 'application/json'
    },
    data: {
      options: {
        client_id: '',
        profile: true,
        scope: ['profile'],
        upstream_params: {blog: {value: 'myblog.wordpress.com'}}
      }
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/%7ByourWordpressConnectionId%7D",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "PATCH",
    CURLOPT_POSTFIELDS => "{"options":{"client_id":"","profile":true,"scope":["profile"],"upstream_params":{"blog":{"value":"myblog.wordpress.com"}}}}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}",
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"options":{"client_id":"","profile":true,"scope":["profile"],"upstream_params":{"blog":{"value":"myblog.wordpress.com"}}}}"

  headers = {
      'authorization': "Bearer {YOUR_MANAGEMENT_API_TOKEN}",
      'content-type': "application/json"
      }

  conn.request("PATCH", "/{YOUR_AUTH0_DOMAIN}/api/v2/connections/%7ByourWordpressConnectionId%7D", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/%7ByourWordpressConnectionId%7D")

  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["authorization"] = 'Bearer {YOUR_MANAGEMENT_API_TOKEN}'
  request["content-type"] = 'application/json'
  request.body = "{"options":{"client_id":"","profile":true,"scope":["profile"],"upstream_params":{"blog":{"value":"myblog.wordpress.com"}}}}"

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

Now every time a user authenticates with this connection, the request to the Wordpress authorization endpoint will include the query parameter `blog=myblog.wordpress.com`.

## Dynamic parameters

Use dynamic parameters to configure your connection to send a set of parameters with values specific to the user to the IdP when they log in.

To configure dynamic parameters, call the Auth0 Management API [Create a connection](https://auth0.com/docs/api/management/v2/#!/Connections/post_connections) or [Update a connection](https://auth0.com/docs/api/management/v2/#!/Connections/patch_connections_by_id) endpoint, pass the `upstream_params` object in the `options` object with the parameters you'd like to send to the IdP, and specify the field that the parameter maps to with the `alias` attribute.

Here's a sample `options` object that we'll revisit later in the X example:

```json lines theme={null}
{
  "options": {
    "upstream_params": {
      "screen_name": {
        "alias": "login_hint"
      }
    }
  }
}
```

### Available fields

These are the available fields for the `alias` attribute:

* `acr_values`
* `audience`
* `client_id`
* `display`
* `id_token_hint`
* `login_hint`
* `max_age`
* `prompt`
* `resource`
* `response_mode`
* `response_type`
* `ui_locales`

### Example: X

X allows you to pass an optional `screen_name` parameter to its OAuth authorization endpoint. The `screen_name` parameter pre-fills the username input box of the login screen with the given value. To learn more, read [X's API reference](https://docs.x.com/fundamentals/authentication/api-reference#get-oauth%2Fauthorize).

To follow this example, you'll need a working [X Social connection](https://marketplace.auth0.com/integrations/twitter-social-connection).

#### Get the connection

Call the Management API [Get a connection](https://auth0.com/docs/api/management/v2#!/Connections/get_connections_by_id) endpoint to retrieve the existing values of the `options` object:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/{YOUR_X_CONNECTION_ID}' \
    --header 'authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
    --header 'content-type: application/json'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/{YOUR_X_CONNECTION_ID}");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer {YOUR_MANAGEMENT_API_TOKEN}");
  request.AddHeader("content-type", "application/json");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/{YOUR_X_CONNECTION_ID}"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer {YOUR_MANAGEMENT_API_TOKEN}")
  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/{YOUR_X_CONNECTION_ID}")
    .header("authorization", "Bearer {YOUR_MANAGEMENT_API_TOKEN}")
    .header("content-type", "application/json")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/{YOUR_X_CONNECTION_ID}',
    headers: {
      authorization: 'Bearer {YOUR_MANAGEMENT_API_TOKEN}',
      'content-type': 'application/json'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/{YOUR_X_CONNECTION_ID}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}",
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = {
      'authorization': "Bearer {YOUR_MANAGEMENT_API_TOKEN}",
      'content-type': "application/json"
      }

  conn.request("GET", "/{YOUR_AUTH0_DOMAIN}/api/v2/connections/{YOUR_X_CONNECTION_ID}", headers=headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/{YOUR_X_CONNECTION_ID}")

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

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer {YOUR_MANAGEMENT_API_TOKEN}'
  request["content-type"] = 'application/json'

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

The `options` object will look something like this:

```text lines theme={null}
"options": {
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "profile": true
}
```

#### Update the connection (dynamic)

Copy the existing `options` object, add the `upstream_params` object with the `screen_name` field as an attribute, and then set the `alias` attribute to `login_hint`:

```json lines theme={null}
{
  "options": {
    "client_id": "", 
    "profile": true, 
    "scope": ["profile"],
    "upstream_params": {
      "screen_name": {
        "alias": "login_hint"
      }
    }
  }
}
```

Call the Management API [Update a connection](https://auth0.com/docs/api/management/v2/#!/Connections/patch_connections_by_id) endpoint with the `options` object in the body:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/{YOUR_X_CONNECTION_ID}' \
    --header 'authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
    --header 'content-type: application/json' \
    --data '{"options": {"client_id": "{YOUR_CLIENT_ID}", "client_secret": "{YOUR_CLIENT_SECRET}", "profile": true, "upstream_params": {"screen_name": {"alias": "login_hint"}}}}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/{YOUR_X_CONNECTION_ID}");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("authorization", "Bearer {YOUR_MANAGEMENT_API_TOKEN}");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"options": {"client_id": "{YOUR_CLIENT_ID}", "client_secret": "{YOUR_CLIENT_SECRET}", "profile": true, "upstream_params": {"screen_name": {"alias": "login_hint"}}}}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/{YOUR_X_CONNECTION_ID}"

  	payload := strings.NewReader("{"options": {"client_id": "{YOUR_CLIENT_ID}", "client_secret": "{YOUR_CLIENT_SECRET}", "profile": true, "upstream_params": {"screen_name": {"alias": "login_hint"}}}}")

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

  	req.Header.Add("authorization", "Bearer {YOUR_MANAGEMENT_API_TOKEN}")
  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/{YOUR_X_CONNECTION_ID}")
    .header("authorization", "Bearer {YOUR_MANAGEMENT_API_TOKEN}")
    .header("content-type", "application/json")
    .body("{"options": {"client_id": "{YOUR_CLIENT_ID}", "client_secret": "{YOUR_CLIENT_SECRET}", "profile": true, "upstream_params": {"screen_name": {"alias": "login_hint"}}}}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/{YOUR_X_CONNECTION_ID}',
    headers: {
      authorization: 'Bearer {YOUR_MANAGEMENT_API_TOKEN}',
      'content-type': 'application/json'
    },
    data: {
      options: {
        client_id: '{YOUR_CLIENT_ID}',
        client_secret: '{YOUR_CLIENT_SECRET}',
        profile: true,
        upstream_params: {screen_name: {alias: 'login_hint'}}
      }
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/{YOUR_X_CONNECTION_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 => "{"options": {"client_id": "{YOUR_CLIENT_ID}", "client_secret": "{YOUR_CLIENT_SECRET}", "profile": true, "upstream_params": {"screen_name": {"alias": "login_hint"}}}}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}",
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"options": {"client_id": "{YOUR_CLIENT_ID}", "client_secret": "{YOUR_CLIENT_SECRET}", "profile": true, "upstream_params": {"screen_name": {"alias": "login_hint"}}}}"

  headers = {
      'authorization': "Bearer {YOUR_MANAGEMENT_API_TOKEN}",
      'content-type': "application/json"
      }

  conn.request("PATCH", "/{YOUR_AUTH0_DOMAIN}/api/v2/connections/{YOUR_X_CONNECTION_ID}", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{YOUR_AUTH0_DOMAIN}/api/v2/connections/{YOUR_X_CONNECTION_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["authorization"] = 'Bearer {YOUR_MANAGEMENT_API_TOKEN}'
  request["content-type"] = 'application/json'
  request.body = "{"options": {"client_id": "{YOUR_CLIENT_ID}", "client_secret": "{YOUR_CLIENT_SECRET}", "profile": true, "upstream_params": {"screen_name": {"alias": "login_hint"}}}}"

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

#### Call the login endpoint

When you call the Authentication API [Login endpoint](https://auth0.com/docs/api/authentication#login) for a user, you can pass their email address to the `login_hint` parameter:

<AuthCodeBlock />

This value will then be passed to the X authorization endpoint as the `screen_name` parameter:

```text lines theme={null}
https://api.x.com/oauth/authorize
  ?oauth_token={yourXAuthToken}
  &screen_name=user@domain.com
```


# Promote Connections to Domain Level
Source: https://auth0.com/docs/authenticate/identity-providers/promote-connections-to-domain-level

Learn how to promote a connection to domain level using the Auth0 Dashboard or Auth0 Management API.

If your tenant has [Dynamic Client Registration](/docs/get-started/applications/dynamic-client-registration) enabled, you can let [third party applications](/docs/get-started/applications/confidential-and-public-applications/enable-third-party-applications) use a connection by promoting it to a domain-level connection. Domain level connections are enabled or disabled for all applications in a tenant.

You can promote a connection using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

<Tabs>
  <Tab title="Auth0 Dashboard">
    You can promote a connection to the domain level directly from the Auth0 Dashboard. This option is available for all connection types (Database, Social, Enterprise, and Passwordless).

    1. Navigate to **Dashboard > Authentication** and select the connection type (e.g., **Database, Social, Enterprise**).
    2. Create a new connection or select an existing one to configure.
    3. Go to the **Settings** tab.
    4. Scroll down to find the **Promote Connection to Domain Level** setting, which is typically in the **Advanced** section.
    5. Enable the toggle switch.

    <Frame>
      <img alt="Promote Connection to Domain Level" />
    </Frame>

    6. Click **Save Changes**.
  </Tab>

  <Tab title="Management API">
    Alternatively, you can promote a connection using a `PATCH` call to the [Update a Connection endpoint](https://auth0.com/docs/api/management/v2#!/Connections/patch_connections_by_id) of the Management API. Be sure to replace the `CONNECTION_ID` and `MGMT_API_ACCESS_TOKEN` placeholder values with your specific information.

    <AuthCodeGroup>
      ```bash cURL theme={null}
      curl --request PATCH \
        --url 'https://{yourDomain}/api/v2/connections/CONNECTION_ID' \
        --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
        --header 'cache-control: no-cache' \
        --header 'content-type: application/json' \
        --data '{ "is_domain_connection": true }'
      ```

      ```csharp C# theme={null}
      var client = new RestClient("https://{yourDomain}/api/v2/connections/CONNECTION_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", "{ "is_domain_connection": true }", ParameterType.RequestBody);
      IRestResponse response = client.Execute(request);
      ```

      ```go Go theme={null}
      package main

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

      func main() {

        url := "https://{yourDomain}/api/v2/connections/CONNECTION_ID"

        payload := strings.NewReader("{ "is_domain_connection": true }")

        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))

      }
      ```

      ```java Java theme={null}
      HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/connections/CONNECTION_ID")
        .header("content-type", "application/json")
        .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
        .header("cache-control", "no-cache")
        .body("{ "is_domain_connection": true }")
        .asString();
      ```

      ```javascript Node.JS theme={null}
      var axios = require("axios").default;

      var options = {
        method: 'PATCH',
        url: 'https://{yourDomain}/api/v2/connections/CONNECTION_ID',
        headers: {
          'content-type': 'application/json',
          authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
          'cache-control': 'no-cache'
        },
        data: {is_domain_connection: true}
      };

      axios.request(options).then(function (response) {
        console.log(response.data);
      }).catch(function (error) {
        console.error(error);
      });
      ```

      ```objc Obj-C theme={null}
      #import <Foundation/Foundation.h>

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

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

      NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/connections/CONNECTION_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];
      ```

      ```php PHP theme={null}
      $curl = curl_init();

      curl_setopt_array($curl, [
        CURLOPT_URL => "https://{yourDomain}/api/v2/connections/CONNECTION_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 => "{ "is_domain_connection": true }",
        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;
      }
      ```

      ```python Python theme={null}
      import http.client

      conn = http.client.HTTPSConnection("")

      payload = "{ "is_domain_connection": true }"

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

      conn.request("PATCH", "/{yourDomain}/api/v2/connections/CONNECTION_ID", payload, headers)

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

      print(data.decode("utf-8"))
      ```

      ```ruby Ruby theme={null}
      require 'uri'
      require 'net/http'
      require 'openssl'

      url = URI("https://{yourDomain}/api/v2/connections/CONNECTION_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 = "{ "is_domain_connection": true }"

      response = http.request(request)
      puts response.read_body
      ```

      ```swift Swift theme={null}
      import Foundation

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

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

      let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/connections/CONNECTION_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()
      ```
    </AuthCodeGroup>

    <table>
      <thead>
        <tr>
          <th>Value</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>CONNECTION\_ID</code></td>
          <td>Τhe ID of the connection to be promoted.</td>
        </tr>

        <tr>
          <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
          <td><a href="https://auth0.com/docs/api/management/v2/tokens">Access Token for the Management API</a> with the <Tooltip href="/docs/glossary?term=scope">scope</Tooltip> <code>update:connections</code>.</td>
        </tr>
      </tbody>
    </table>
  </Tab>
</Tabs>


# Retrieve Connection Options
Source: https://auth0.com/docs/authenticate/identity-providers/retrieve-connection-options

Learn how to retrieve the options object for a connection using the Auth0 Management API.

You can retrieve the options object for a [connection](/docs/authenticate/identity-providers) using Auth0's <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

Make a `GET` call to the [Get Connection endpoint](https://auth0.com/docs/api/management/v2#!/Connections/get_connections_by_id). Be sure to replace `CONNECTION_ID` and `MGMT_API_ACCESS_TOKEN` placeholder values with your connection ID and Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/connections/CONNECTION-ID?fields=options' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/connections/CONNECTION-ID?fields=options");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/connections/CONNECTION-ID?fields=options"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/connections/CONNECTION-ID?fields=options")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/connections/CONNECTION-ID',
    params: {fields: 'options'},
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/connections/CONNECTION-ID?fields=options"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/connections/CONNECTION-ID?fields=options",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN"
    ],
  ]);

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

  curl_close($curl);

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

  ```import http.client theme={null}

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer MGMT_API_ACCESS_TOKEN" }

  conn.request("GET", "/{yourDomain}/api/v2/connections/CONNECTION-ID?fields=options", headers=headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/connections/CONNECTION-ID?fields=options")

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

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer MGMT_API_ACCESS_TOKEN"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/connections/CONNECTION-ID?fields=options")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>CONNECTION\_ID</code></td>
      <td>Τhe ID of the connection for which you want to retrieve the <code>options</code> object.</td>
    </tr>

    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td><a href="https://auth0.com/docs/api/management/v2/tokens">Access Token for the Management API</a> with the scope <code>read:connections</code>.</td>
    </tr>
  </tbody>
</table>


# Social Identity Providers
Source: https://auth0.com/docs/authenticate/identity-providers/social-identity-providers

Learn about the social identity providers supported by Auth0.

Auth0 supports social login for both web-based and native applications. Social login is a method of authentication that allows users to log in to an application using existing credentials from a social <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>, such as Google or Facebook. This is separate from connecting and authorizing applications for an external provider, allowing them to access external APIs on the user’s behalf. To learn more, read [User authentication vs Connected Accounts](/docs/secure/tokens/token-vault/connected-accounts-for-token-vault#user-authentication-vs-connected-accounts).

As users frequently have their social credentials stored in their browser or device, social login provides a frictionless user experience that requires minimal manual interaction with an application.

The sections below outline the social login options available for both web-based and native applications.

## Web-based applications

Auth0 supports a variety of social identity providers for web-based applications. Implementing social login with one or more of these providers allows you to gather up-to-date information about your users while simultaneously offering them a streamlined authentication experience.

You can review the list of supported social identity providers on the [Auth0 Marketplace](https://marketplace.auth0.com/categories/social-login) or the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. If a particular provider is not available, you can also configure custom social connections. To learn more, review [Connect Apps to Generic OAuth2 Authorization Servers](/docs/authenticate/identity-providers/social-identity-providers/oauth2).

<Tabs>
  <Tab title="Auth0 Marketplace">
    The [Social Login](https://marketplace.auth0.com/categories/social-login) section of the Auth0 Marketplace provides information for each supported social connection. To learn more about a specific provider, select the option from the list.

    From there, you can use the **Add Integration** button to launch the configuration process in your Auth0 tenant and the **Installation** tab to review implementation documentation. For a successful implementation, ensure you [register developer keys](/docs/authenticate/identity-providers/social-identity-providers/devkeys) for your selected provider.
  </Tab>

  <Tab title="Auth0 Dashboard">
    To implement social login from the Auth0 Dashboard, navigate to [Authentication > Social](https://manage.auth0.com/#/connections/social) and select **Create Connection**. Then, choose a connection option from the list of supported social identity providers.

    After selecting an option from the list, the configuration process launches. Follow the prompts to configure your selected provider.

    For assistance, select the **Setup Guide** button to the top right to open relevant implementation documentation in a popup. The setup guide contains information on the necessary steps to configure the connection and links to relevant documentation from the social identity provider.

    For a successful implementation, ensure you [register developer keys](/docs/authenticate/identity-providers/social-identity-providers/devkeys) for your selected provider.

    You can also access the Auth0 Marketplace through the Auth0 Dashboard. Navigate to [Marketplace](https://manage.auth0.com/#/marketplace) on the main menu and choose the **Social Login** category. From there, you can review and implement connections with any of the available social identity providers.
  </Tab>
</Tabs>

## Native applications

Auth0 supports social login with select providers for native applications. To learn more, review the resources below:

* [Apple](/docs/authenticate/identity-providers/social-identity-providers/apple-native)
* [Facebook](/docs/authenticate/identity-providers/social-identity-providers/facebook-native)
* [Google](/docs/authenticate/identity-providers/social-identity-providers/google-native)
* [TikTok](/docs/authenticate/identity-providers/social-identity-providers/tiktok)


# Add Sign In with Apple to Native iOS Apps
Source: https://auth0.com/docs/authenticate/identity-providers/social-identity-providers/apple-native

Learn how to add native login functionality to your native app with Apple.

You can add functionality to your native iOS application to allow your users to authenticate using Sign In with Apple. For more implementation details, you can try the Auth0 [iOS Swift - Sign In with Apple Quickstart](/docs/quickstart/native/ios-swift).

## How it works

For a native app, the Sign in with Apple login flow works as follows:

<Frame>
  <img alt="Diagram of the Sign In with Apple Authentication Flow" />
</Frame>

* **Steps 1 & 2**: User authenticates via Apple's SDK on their iOS device, and receive an authorization code in the response. The user does not have to leave the app and use a browser to log in.

  <Warning>
    Avoid using a nonce. It will cause the request to Apple to fail in step 4 and Auth0 will return a 400 error to the user: "Error from Apple connection."
  </Warning>
* **Step 3**: The application calls Auth0's `/oauth/token` endpoint to exchange the Apple authorization code for Auth0 tokens.
* **Step 4 & 5**: The Auth0 platform exchanges the Authorization code with Apple for tokens. Auth0 validates the tokens, and uses the claims in the tokens to construct the identity of the user.
* **Step 6**: Auth0 saves the user profile, executes rules and authorization, then issues Auth0 <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> (<Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip> and <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip>) as requested. These tokens are used to protect your APIs and users managed by Auth0.

## Prerequisites

Before you configure Sign In with Apple for your native app in Auth0, you must:

* Have an [Apple Developer](https://developer.apple.com/programs/) account, which is a paid account with Apple. (There is no free trial available unless you are part of their [iOS Developer University Program](https://developer.apple.com/support/compare-memberships/).)
* [Register Your App in the Apple Developer Portal](https://marketplace.auth0.com/integrations/apple-social-connection) if you have not already done so. Make a note of the following IDs and key for the application connection settings in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>:

  * App ID
  * Apple Team ID
  * Client Secret Signing Key
  * Key ID
* If you are using the Classic Login flow or embedding `Lock.js` in your application, make sure you are using `Lock.js` version 11.16 or later.

## Configure and enable the connection in Auth0

Once you have the credentials you need from your Apple Developer account, you need to configure the application client and the connection settings in Auth0.

1. Navigate to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), choose your application, and select the gear icon to view the settings page.
2. At the bottom of the page, select **Show Advanced Settings** and then the **Device Settings** view. Under **Native Social Login**, enable the **Enable Sign In with Apple** toggle.

   <Frame>
     <img alt="Application Client Settings: Advanced Device Settings" />
   </Frame>
3. Under **iOS**, fill in the **App ID** field with the native app's App ID/Bundle Identifier.
4. Navigate to [Auth0 Dashboard > Authentication > Social](https://manage.auth0.com/#/connections/social), and select **Create Connection**.
5. Select the **Apple** connection and consent.
6. On the **Settings** tab, fill in the following fields:

   * **Apple Team ID**
   * **Client Secret Signing Key**
   * **Key ID**

     <Frame>
       <img alt="Apple Social Connection Settings" />
     </Frame>
7. Select the **Applications** view to enable this connection for your application.
8. Click **Save**.

<Callout icon="file-lines">
  Native apps cannot be tested from the browser. This means that the **Try Connection** button on the Apple connection is used exclusively for testing web-based flows.
</Callout>

## Logout

Since the Native iOS login implementation does not make use of standard browser-based flows, application owners must also take care to perform logout appropriately. When an application needs to perform a logout, it must take the following actions:

* [Revoke the Auth0 Refresh Token](https://auth0.com/docs/api/authentication#revoke-refresh-token)
* Delete the Auth0 refresh token stored in the iCloud Keychain
* Delete the Apple user identifier stored in the iCloud keychain
  Also, keep in mind that logout can result from user actions (for example, clicking a "log out" button) or from a user revoking access to the given app. The latter will be indicated through the native [ASAuthorizationAppleIDProvider.getCredentialState](https://developer.apple.com/documentation/authenticationservices/asauthorizationappleidprovider/3175423-getcredentialstate) method.

<Callout icon="file-lines">
  One nuance of Apple's IdP is that it only returns requested scopes (such as email, first name, and last name) in the ID token on the **first** response. More destructive approaches to logout (such as deleting the user) could result in loss of profile information, which would require end users to deauthorize and reauthorize an app.
</Callout>

## Learn more

* [Rate Limit Policy](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy)


# Test Social Connections with Auth0 Developer Keys
Source: https://auth0.com/docs/authenticate/identity-providers/social-identity-providers/devkeys

Explore what you need to be aware of when using Auth0 Developer Keys with social identity providers.

<Card title="Overview">
  Key Concepts

  * Review the limitations of Auth0's developer keys.
</Card>

When using any of the available [social identity providers](/docs/authenticate/identity-providers/social-identity-providers), you need to register your application with the relevant <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> in order to obtain a <Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip> and <Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip>.

<Warning>
  Auth0 allows you to test a Social Identity Provider without specifying your own Client ID and Client Secret by using Auth0 developer keys. This allows you to quickly enable and test a specific Social Identity Provider, but it should not be used in production.
</Warning>

Auth0 developer keys are not available in [Private Cloud deployments](/docs/deploy-monitor).

For production environments, make sure to [follow the steps for your chosen provider](/docs/authenticate/identity-providers) to obtain the Client ID and Client Secret from the provider to avoid the [limitations](#limitations-of-developer-keys) of using developer keys. For instructions on converting Google developer keys to production keys, [read this Auth0 Developer Lab.](https://developer.auth0.com/resources/labs/authentication/google-social-connection-to-login#set-up-google-production-keys)

<Card title="Custom developer keys">
  One or more connections are using Auth0 development keys which are only intended for use in development and testing. The connections should be configured with your own Developer Keys to enable the consent page to show your logo instead of Auth0's and to configure Single Sign-on (SSO) for these connections. Auth0 development keys are not recommended for Production environments.
</Card>

<Card title="Client ID and Client Secret">
  The exact terminology of a Client ID / Client Secret may differ between various Identity Providers. For example, X refers to these as a Consumer Key / Consumer Secret and LinkedIn refers to an API Key / Secret Key.
</Card>

## Limitations of developer keys

The Auth0 developer keys are to be used for testing purposes so there are a few caveats you need to be aware of when using them. These may cause your application to behave differently--or some functionality to not work at all--depending on whether you use your own Client ID and Client Secret, or whether you use the Auth0 developer keys.

When using the Auth0 developer keys, the authentication flow for the various identity providers may display Auth0's name, logo, and information to your users. When you register your own application, you have the opportunity to use your own logo and other application information instead.

<Frame>
  <img alt="Consent screen" />
</Frame>

## Limitations of developer keys when using Universal Login

If you are using the [Classic Login experience](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/classic-experience) - and in some circumstances, the [Universal Login Experience](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience) - the follow limitations also apply:

1. You cannot use developer keys with [custom domains](/docs/customize/custom-domains).
2. [Single Sign-On](/docs/authenticate/single-sign-on) will not function properly when using the Auth0 developer keys. The reason for this is that the Auth0 developer applications with all the relevant Identity Providers are configured to call back to the URL `https://login.auth0.com/login/callback` instead of the **callback URL** for your own tenant, for example `https://{yourDomain}/login/callback`.
   This results in the SSO cookie not being set on your own tenant domain, so the next time a user authenticates, no SSO cookie will be detected, even if you configured your application to **Use Auth0 instead of the Identity Provider to do Single Sign-on** (legacy tenants only).
3. [Redirecting users from Rules](/docs/customize/rules/redirect-users) will not function properly. This is because redirect rules are resumed on the endpoint `https://{yourDomain}/continue`. When using Auth0's developer keys, the session is established on a special endpoint that is generic and tenant agnostic, and calling `/continue` will not find your previous session, resulting in an error.
4. [Federated Logout](/docs/authenticate/login/logout) does not work. When using the Auth0 developer keys, calling `/v2/logout?federated` will sign the user out of Auth0, but not out of the Social Identity Provider.
5. `prompt=none` won't work on the [/authorize](https://auth0.com/docs/api/authentication/reference#social) endpoint. [Auth0.js](/docs/libraries/auth0js)' checkSession() method uses `prompt=none` internally, so that won't work either.
6. If Auth0 is acting as a SAML Identity Provider, and you use a social connection with the Auth0 developer keys, the generated SAML response will have some errors, like a missing `InResponseTo` attribute or an empty `AudienceRestriction` element.
7. [Multi-Factor Authentication](/docs/secure/multi-factor-authentication) will not function properly. When MFA authentication is successful, a post will generate in `https://{yourDomain}/mf`. When using Auth0's developer keys, the session is established on a special endpoint that is generic and tenant agnostic, and calling `/mf` will not find your previous session, resulting in an error


# Add Facebook Login to Native Apps
Source: https://auth0.com/docs/authenticate/identity-providers/social-identity-providers/facebook-native

Learn how to add login functionality to your native app with Facebook.

You can add functionality to your native application to allow your users to authenticate using Facebook natively, within the application. This does not require redirection via a web browser and will let mobile applications comply with the [Facebook Developer Policy](https://developers.facebook.com/policy/), which requires that mobile applications use the Facebook SDK for [Android](https://developers.facebook.com/docs/android) or [iOS](https://developers.facebook.com/docs/ios) to authenticate.

<Callout icon="file-lines">
  When integrating with the Facebook SDKs, your applications will be sharing data with Facebook. Make sure you understand the data that is being shared and that you reflect it properly in your application's privacy policy. Auth0 has no control over what data will be shared with Facebook via the SDK.

  Check the [Facebook GDPR](https://www.facebook.com/business/m/one-sheeters/gdpr-developer-faqs) page for more information about data collected by the Facebook SDK and Facebook Login.
</Callout>

## How it works

The Native Facebook login flow works as follows:

* **Step 1**: The application authenticates a user via the Facebook SDK and acquires an <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>.
* **Step 2**: The application uses that Access Token to request a special [Facebook Session Info Access Token](https://developers.facebook.com/docs/facebook-login/access-tokens/session-info-access-token).
* **Step 3**: Use the Facebook SDK to retrieve the users's profile.
* **Step 4**: The application can then use the Facebook Session Info token to authenticate with Auth0.

## Prerequisites

Before you configure Native Facebook login for your native app via Auth0, you must:

1. [Set up Facebook as an Auth0 connection](https://marketplace.auth0.com/integrations/facebook-social-connection)
2. [Use the relevant Facebook SDK in your application](https://developers.facebook.com/docs/apis-and-sdks/)
3. Navigate to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), and create an application with Auth0 (if you have not already).
4. At the bottom of the settings page, select **Show Advanced Settings** and then the **Device Settings** view. Under **Native Social Login**, enable the **Enable Sign In with Facebook** toggle.

   <Frame>
     <img alt="Native Social Login Settings" />
   </Frame>

## Implementation

The process to authenticate a user profile using Native Facebook login is a four-step one, from your application's perspective:

### Step 1

The application authenticates a user via the Facebook SDK. It will obtain an Access Token from Facebook.

## Step 2

The application uses the Access Token to request a [Facebook Session Info Access Token](https://developers.facebook.com/docs/facebook-login/access-tokens/session-info-access-token).

This request will look similar to the following:

```json wrap lines theme={null}
GET https://graph.facebook.com/v5.0/oauth/access_token?grant_type=fb_attenuate_token&client_id=457704041391802&fb_exchange_token=<facebook_access_token>
```

and the response:

```json lines theme={null}
{
    "access_token": "XAAGgR4b...1lHWNCpqrAhcpoAZDZD",
    "token_type": "bearer",
    "expires_in": 5183924
}
```

### Step 3

The application needs to retrieve the user profile from Facebook using the Facebook SDK, which will end in a request similar to the following:

```json wrap lines theme={null}
GET https://graph.facebook.com/v5.0/<facebook user id>?access_token=<facebook access token>&fields=email,name
```

### Step 4

The application can then use the session info Access Token and the Facebook user profile to authenticate with Auth0 by calling Auth0's `/oauth/token` endpoint using the Token Exchange flow with the `facebook-session-access-token` token type. If all goes well, Auth0 will return a normal response from the exchange, with the addition of the user profile. The user profile should be a JSON object, encoded as a string.

<AuthCodeBlock />

and the response from Auth0:

```json lines theme={null}
{
    "access_token": "eyJ0eXA..yXQaPLVXg",
    "id_token": "eyJ0.tFE5HPipdOsA",
    "scope": "openid profile email read:appointments",
    "expires_in": 86400,
    "token_type": "Bearer"
}
```

## User Profile and Email Validation

In the previous example, you had to retrieve the User Profile from Facebook and include it in the call to `/oauth/token`. This is because the Facebook Session Access Token cannot be used to directly retrieve the profile, and the Facebook Access Token cannot be sent directly to the server, due to [Apple's AppStore Review Guidelines](https://developer.apple.com/app-store/review/guidelines). Therefore, it must be retrieved in the client and sent to Auth0 in this fashion.

Given that Auth0 can't guarantee that the user profile is the same that was returned by Facebook, it will set the `email_verified` field to `false`.

## Logout

Since the native login implementation does not make use of standard browser-based flows, application owners must also take care to perform logout appropriately. When an application needs to perform a logout, it should also [Revoke the Auth0 Refresh Token](https://auth0.com/docs/api/authentication#revoke-refresh-token).

## Keep reading

* [Native Facebook Login with iOS Swift](/docs/quickstart/native/ios-swift-facebook-login)
* [Native Facebook Login with Android](/docs/quickstart/native/android-facebook-login)
* [Rate Limits on Native Social Logins](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy)


# Add Sign In with Google to Native Android Apps
Source: https://auth0.com/docs/authenticate/identity-providers/social-identity-providers/google-native

Learn how you can implement Sign In with Google for native mobile applications.

[Sign in with Google](https://developers.google.com/identity/gsi/web/guides/overview) allows users to authenticate with an active Google Account, providing users with a seamless login experience for your application. You can implement this feature for your native Android applications using the Credential Manager for Android with Auth0.

Review the sections below to learn more about the steps and methods required for configuring Sign in with Google.

## How it works

This feature uses Android's Credential Manager to facilitate Sign in with Google in your Auth0-protected Android application. The steps below demonstrate the general user workflow for Sign in with Google.

<Frame>
  <img alt="" />
</Frame>

1. A user opens your Android application and chooses to log in with Google.
2. Your Android application uses the Credential Manager to request Sign in with Google.
3. On the account selection prompt, the user chooses their preferred Google account.
4. Google signs the user in locally and handles all authentication.
5. The user completes sign-in with no additional interaction required.
6. Google returns an `id_token` to your Android application.
7. Your Android application sends the `id_token` to your Auth0 tenant for validation. Auth0 validates the `client_id` from the `id_token` against the `client_id` of the Google social connection configured in your tenant.
8. The Auth0 server returns an `access_token` to your Android application.

## Before you begin

Before you begin configuring Sign in with Google, ensure the following are true:

* A [Google social connection](https://marketplace.auth0.com/integrations/google-social-connection) has been set up within your Auth0 tenant.
  * For the **Purpose** setting, enable the connection for Authentication, Connected Accounts for Token Vault, or both. To learn more, read [User authentication vs Connected Accounts](/docs/secure/tokens/token-vault/connected-accounts-for-token-vault#user-authentication-vs-connected-accounts).
* Sign in with Google has been added to your Android application using [Android's Credential Manager](https://developer.android.com/identity/sign-in/credential-manager-siwg).

## Configuring Sign in with Google for Android applications

Implementing Sign in with Google involves three primary steps:

1. Creating credentials in Google Cloud Console.
2. Configuring application details in Auth0.
3. Updating code in your Android application.

The sections below provide technical details for each of these steps.

### Create Credentials in the Google Cloud Console

To get started, you must first configure the following items in your Google Cloud Console:

1. Create an OAuth 2.0 credential with the type set to `Android`. This is referred to as `client_id_native`.
2. Add the SHA1 hash for the native application to the Android Client from Step 1.

   * Google currently only supports SHA1.
3. Create an additional OAuth client for web (`client_id_web`).

   * In some scenarios, you may have already configured this item for your social connections that support web-based Sign in with Google.

<Callout icon="file-lines">
  You cannot use Google Credential Manager with the Android `client_id` or an error will occur. In the ID Token returned from Google, the authorized party (azp) is automatically set to the Android OAuth Client ID, and the audience (aud) is set to the Web OAuth Client ID.

  When invoking the Credentials Manager from Android, the native application should use the `client_id_web` via `.setServerClientId` in the Credentials Manager SDK. `client_id_web` corresponds to the Web Application OAuth 2 Credential in the Google Cloud Console, and it is configured in the Google OAuth2 social connection. For more information, refer to [Google’s documentation](https://developer.android.com/training/sign-in/credential-manager).
</Callout>

### Configure Auth0

The Sign in with Google flow leverages the <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> Token Exchange, which occurs between Auth0 and your Android application.

After creating your credentials in the Google Cloud Console, you can enable Sign in with Google using the Credential Manager for Android. To do so, update your application through either the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

<Tabs>
  <Tab title="Auth0 Dashboard">
    To update the application through the Auth0 Dashboard, follow the steps below:

    1. Navigate to [Applications > Applications](https://manage.auth0.com/#/applications) and choose your native Android application.
    2. On the **Settings** tab, expand the **Advanced Settings** section.
    3. Select the **Device Settings** tab and activate the **Enable Sign in with Google (Android 4.4+) using Credentials Manager** setting.
    4. **For new applications**: On the Device Settings tab, complete the fields in the **Android** section, including **App Package Name**. For more information, review [Enable Android App Links Support](/docs/get-started/applications/enable-android-app-links-support).
    5. Select **Save Changes**.
  </Tab>

  <Tab title="Management API">
    To update your application through the Management API, call the [Update a client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) endpoint as follows:

    ```json lines theme={null}
    PATCH /api/v2/clients/{id}

    { 
      "native_social_login": { 
        "google": { 
          "enabled": true 
        } 
      },
      "mobile": {
        "android": {
          // Update this to reflect the bundle identifier of your App
          "app_package_name": "com.yoursite.yourapp"
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Update code in the Android application

The following example can complement the web flow used for non-Google authentications, such as Microsoft, username and password, or enterprise federations.

```go lines theme={null}
auth0Client.loginWithNativeSocialToken(
  googleCredential.idToken.toString(),
  "http://auth0.com/oauth/token-type/google-id-token")
    .validateClaims()
    .setScope("openid profile email")
    .start(object: Callback < Credentials, AuthenticationException > {
      override fun onFailure(error: AuthenticationException) {
        showSnackBar("Failure a0: $error")

      }

   override fun onSuccess(auth0Creds: Credentials) {
    // Logic to Handle credentials
    }
    })
```

Obtaining the Google `googleCredential` requires the native application code to invoke the Google library. For details, refer to [Google's Credential Manager documentation](https://developer.android.com/training/sign-in/credential-manager).

```go lines expandable theme={null}
// Generate a nonce for token replay protection
val randomNonce = UUID.randomUUID().toString()

// Prepare a Sign in request
val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
    // This must match the Client ID Configured in the auth0 dashboard
    .setServerClientId(
        getString(R.string.com_google_client_id)
    )
	.setNonce(randomNonce)
    .build()

val request: GetCredentialRequest = GetCredentialRequest.Builder()
    .addCredentialOption(googleIdOption)
    .build()

// To Prompt
val credMan = CredentialManager.create(this@MainActivity.baseContext);
val result = credMan.getCredential(
    request = request,
    context = this@MainActivity.baseContext,
)

// Handle outcome 
val creds = result.credential

when (creds) {
    is CustomCredential -> {
        if (creds.type ==
                    GoogleIdTokenCredential.TYPE_GOOGLE_ID_TOKEN_CREDENTIAL
            ) {
                try {
                    val googleCredentials = GoogleIdTokenCredential
                            .createFrom(creds.data)
// Rest of the code
```

## Additional authentication scenarios

While the current Google implementation does not offer clear guidance for enterprise federation and additional <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA) challenges, you can accommodate these capabilities by transitioning to the web experience.

### Enterprise federation

Auth0 supports enterprise federation, which allows you to connect external [enterprise identity providers](/docs/authenticate/identity-providers/enterprise-identity-providers) (such as Okta Workforce, ADFS, or other OIDC-compatible systems) to your Auth0 tenant so that users can then authenticate with their existing corporate credentials.

If you require the use of enterprise federation, redirecting the user to the web-based flow is recommended, instead of relying on the `id_token` as demonstrated in previous examples.

To do so, decode the Google <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> token and pass the `email` provided in the <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> as a `login_hint`. This prevents the end user from having to re-enter their email address in the web flow.

```go lines theme={null}
if (error.isAccessDenied && reason == "Enterprise Domain") {
WebAuthProvider.login(account)
	.withParameters(mapOf("login_hint" to email))
	.start(...)
}
```

### MFA considerations during token exchange

Auth0 returns an error to the application during token exchange when the Google OAuth connection policy requires multi-factor authentication.  This error is included in the response to the application.

When the above error occurs, your application can use WebAuth with the enriched context available in the Google `id_token`. In this scenario, the end user will only see the MFA screen.

```go lines theme={null}
if (error.isMultifactorRequired) {
WebAuthProvider.login(account)
	.withParameters(mapOf(
"login_hint" to email,
"connection" to "google-oauth-2"
))
	.start(...)
}
```


# Connect Apps to Generic OAuth2 Authorization Servers
Source: https://auth0.com/docs/authenticate/identity-providers/social-identity-providers/oauth2

Learn how to add any OAuth2 provider using Auth0 Custom Social Connections.

The most common [identity providers (IdP)](/docs/authenticate/identity-providers) are available in [Auth0 Dashboard](https://manage.auth0.com/#) and in the [Auth0 Marketplace](https://marketplace.auth0.com/features/social-connections). You can, however, add any <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> provider as a **Custom Social Connection** in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

1. In the Dashboard, go to [Authentication > Social](https://manage.auth0.com/#/connections/social).
2. Select **Create Connection**, go to the bottom of the list, and then select **Create Custom**.

The form that appears contains several fields that you must use to configure the custom connection:

* **Connection Name**: Logical identifier for the Connection you are creating. This name cannot be changed, must start and end with an alphanumeric character, and can only contain alphanumeric characters and dashes.
* **Authorization URL**: URL to which users are redirected to log in.

  <Callout icon="file-lines">
    Do not attempt to set the OAuth2 `response_mode` parameter in the authorization URL. This connection only supports the default `response_mode` (`query`).
  </Callout>
* **Token URL**: URL used to exchange the received authorization code for <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> and, if requested, <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip>.
* **Scope**: `scope` parameters to send with the authorization request. Separate multiple scopes with spaces.
* **Separate scopes using a space**: Toggle that determines how scopes are delimited if the `connection_scope` parameter is included when [calling the IdP's API](/docs/authenticate/identity-providers/calling-an-external-idp-api). By default, scopes are delimited by a comma. If the toggle is enabled, scopes are delimited by a space. To learn more, read [Add Scopes/Permissions to Call Identity Provider APIs](/docs/authenticate/identity-providers/adding-scopes-for-an-external-idp).
* **<Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>**: Client ID for Auth0 as an application used to request authorization and exchange the authorization code. To get a Client ID, you will need to register with the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>.
* **<Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip>**: Client Secret for Auth0 as an application used to exchange the authorization code. To get a Client Secret, you will need to register with the identity provider.
* **Fetch User Profile Script**: Node.js script used to call a userinfo URL with the provided access token. To learn more about this script, see [Fetch User Profile Script](#fetch-user-profile-script).
* **Purpose**: Enables the social connection for Authentication, Connected Accounts for Token Vault, or both. To learn more, read [User authentication vs Connected Accounts](/docs/secure/tokens/token-vault/connected-accounts-for-token-vault#user-authentication-vs-connected-accounts).

<Callout icon="file-lines">
  When configuring the custom identity provider, use the callback URL `https://{yourDomain}/login/callback`.
</Callout>

Once you create the custom connection, you will see the **Applications** view and your connection will be subject to Auth0's [Rate Limit Policy](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy). Here, you can enable and disable applications for which you would like the connection to appear.

## Update authentication flow

When you create a connection, the default OAuth 2.0 grant type assigned to the connection is Authorization Code Flow. If you have a public application unable to store a Client Secret, such single-page or native applications, you can use the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to update the connection to use [Authorization Code Flow + PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce). To learn more about <Tooltip href="/docs/glossary?term=authorization+flows">authorization flows</Tooltip>, read [Which OAuth 2.0 Flow Should I Use?](/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use)

1. Make a `GET` request to the [`/get-connections-by-id`](https://auth0.com/docs/api/management/v2/connections/get-connections-by-id) endpoint. The response will be similar to:

   ```json lines theme={null}
   {
     "id": "[connectionID]",
     "options": {
       "email": true,
       "scope": [
         "email",
         "profile"
       ],
       "profile": true
     },
     "strategy": "google-oauth2",
     "name": "google-oauth2",
     "is_domain_connection": false,
     "realms": [
       "google-oauth2"
     ]
   }
   ```

2. Copy the entire `options` object.

3. Make a [`PATCH`](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id) request with the `options` object and add `"pkce_enabled":` `true`.

<Warning>
  If you do not include the entire `options` object, information will be lost and the connection will break.
</Warning>

## Fetch User Profile Script

The fetch user profile script is called after the user has logged in with the OAuth2 provider. Auth0 executes this script to call the OAuth2 provider API and get the user profile:

```javascript lines expandable theme={null}
function fetchUserProfile(accessToken, context, callback) {
  request.get(
    {
      url: 'https://auth.example.com/userinfo',
      headers: {
        'Authorization': 'Bearer ' + accessToken,
      }
    },
    (err, resp, body) => {
      if (err) {
        return callback(err);
      }
      if (resp.statusCode !== 200) {
        return callback(new Error(body));
      }
      let bodyParsed;
      try {
        bodyParsed = JSON.parse(body);
      } catch (jsonError) {
        return callback(new Error(body));
      }
      const profile = {
        user_id: bodyParsed.account.uuid,
        email: bodyParsed.account.email
      };
      callback(null, profile);
    }
  );
}
```

The `user_id` property in the returned profile is required, and the `email` property is optional but highly recommended. To learn more about what attributes can be returned, see [User Profile Root Attributes](/docs/manage-users/user-accounts/user-profiles/root-attributes/update-root-attributes-for-users).

You can filter, add, or remove anything from the profile returned from the provider. However, it is recommended that you keep this script as simple as possible. More sophisticated manipulation of user information can be achieved through the use of [Rules](/docs/customize/rules). One advantage of using Rules is that they apply to any connection.

## Log in using the custom connection

You can use any of the Auth0 standard mechanisms to log a user in with your custom connection. A direct link would look like:

<AuthCodeBlock />

## Modify the icon and display name

To add an icon to the identity provider's login button or change the text used on the login button, you can use the `icon_url` property of the `options` object and the `display_name` property, respectively, via the [Management API](https://auth0.com/docs/api/management/v2#!/Connections/patch_connections_by_id).

<Warning>
  * If `display_name` is not included in your request, the field is overwritten with the Connection `name` value.
  * `display_name` and `icon_url` only affect how the Connection displays in the [Universal Login experience](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience).
</Warning>

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/connections/CONNECTION-ID' \
    --header 'content-type: application/json' \
    --data '{ "options": { "client_id": "...", "client_secret": "...", "icon_url": "https://cdn.example.com/assets/icon.png", "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://public-auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" }, "display_name": "Connection Name"}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/connections/CONNECTION-ID");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{ "options": { "client_id": "...", "client_secret": "...", "icon_url": "https://cdn.example.com/assets/icon.png", "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://public-auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" , "display_name": "Connection Name" }, ParameterType.RequestBody);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/connections/CONNECTION-ID"

  	payload := strings.NewReader("{ "options": { "client_id": "...", "client_secret": "...", "icon_url": "https://cdn.example.com/assets/icon.png", "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://public-auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" }, "display_name": "Connection Name"}")

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

  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/connections/CONNECTION-ID")
    .header("content-type", "application/json")
    .body("{ "options": { "client_id": "...", "client_secret": "...", "icon_url": "https://cdn.example.com/assets/icon.png", "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://public-auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" }, "display_name": "Connection Name"})
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/connections/CONNECTION-ID',
    headers: {'content-type': 'application/json'},
    data: '{ "options": { "client_id": "...", "client_secret": "...", "icon_url": "https://cdn.example.com/assets/icon.png", "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://public-auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" }, "display_name": "Connection Name"}'

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json" };

  NSData *postData = [[NSData alloc] initWithData:[@"{ "options": { "client_id": "...", "client_secret": "...", "icon_url": "https://cdn.example.com/assets/icon.png", "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://public-auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth", "display_name": "Connection Name"} }", dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/connections/CONNECTION-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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/connections/CONNECTION-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 => "{ "options": { "client_id": "...", "client_secret": "...", "icon_url": "https://cdn.example.com/assets/icon.png", "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://public-auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" }, "display_name": "Connection Name"}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "options": { "client_id": "...", "client_secret": "...", "icon_url": "https://cdn.example.com/assets/icon.png", "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://public-auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" }, "display_name": "Connection Name"}"

  headers = { 'content-type': "application/json" }

  conn.request("PATCH", "/{yourDomain}/api/v2/connections/CONNECTION-ID", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/connections/CONNECTION-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.body = "{ "options": { "client_id": "...", "client_secret": "...", "icon_url": "https://cdn.example.com/assets/icon.png", "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://public-auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" }, "display_name": "Connection Name"}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/json"]

  let postData = NSData(data: "{ "options": { "client_id": "...", "client_secret": "...", "icon_url": "https://cdn.example.com/assets/icon.png", "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://public-auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" }, "display_name": "Connection Name"}.data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/connections/CONNECTION-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()
  ```
</AuthCodeGroup>

## Pass provider-specific parameters

You can pass provider-specific parameters to the Authorization endpoint of OAuth 2.0 providers. These can be either static or dynamic.

### Pass static parameters

To pass static parameters (parameters that are sent with every authorization request), you can use the `authParams` element of the `options` when configuring an OAuth 2.0 connection via the [Management API](https://auth0.com/docs/api/management/v2#!/Connections/patch_connections_by_id). The call below will set a static parameter of `custom_param` set to `custom.param.value` on all authorization requests:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/connections/CONNECTION-ID' \
    --header 'content-type: application/json' \
    --data '{ "options": { "client_id": "...", "client_secret": "...", "authParams": { "custom_param": "custom.param.value" }, "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://public-auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" } }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/connections/CONNECTION-ID");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{ "options": { "client_id": "...", "client_secret": "...", "authParams": { "custom_param": "custom.param.value" }, "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://public-auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" } }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/connections/CONNECTION-ID"

  	payload := strings.NewReader("{ "options": { "client_id": "...", "client_secret": "...", "authParams": { "custom_param": "custom.param.value" }, "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://public-auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" } }")

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

  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/connections/CONNECTION-ID")
    .header("content-type", "application/json")
    .body("{ "options": { "client_id": "...", "client_secret": "...", "authParams": { "custom_param": "custom.param.value" }, "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://public-auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" } }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/connections/CONNECTION-ID',
    headers: {'content-type': 'application/json'},
    data: {
      options: {
        client_id: '...',
        client_secret: '...',
        authParams: {custom_param: 'custom.param.value'},
        scripts: {fetchUserProfile: '...'},
        authorizationURL: 'https://public-auth.example.com/oauth2/authorize',
        tokenURL: 'https://auth.example.com/oauth2/token',
        scope: 'auth'
      },
    },
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"options": @{ @"client_id": @"...", @"client_secret": @"...", @"authParams": @{ @"custom_param": @"custom.param.value" }, @"scripts": @{ @"fetchUserProfile": @"..." }, @"authorizationURL": @"https://public-auth.example.com/oauth2/authorize", @"tokenURL": @"https://auth.example.com/oauth2/token", @"scope": @"auth" }
  };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/connections/CONNECTION-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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/connections/CONNECTION-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 => "{ "options": { "client_id": "...", "client_secret": "...", "authParams": { "custom_param": "custom.param.value" }, "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://public-auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" } }"
    CURLOPT_HTTPHEADER => [
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "options": { "client_id": "...", "client_secret": "...", "authParams": { "custom_param": "custom.param.value" }, "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://public-auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" } }"

  headers = { 'content-type': "application/json" }

  conn.request("PATCH", "/{yourDomain}/api/v2/connections/CONNECTION-ID", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/connections/CONNECTION-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.body = "{ "options": { "client_id": "...", "client_secret": "...", "authParams": { "custom_param": "custom.param.value" }, "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://public-auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" }}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/json"]
  let parameters = [
    "options": [
      "client_id": "...",
      "client_secret": "...",
      "authParams": ["custom_param": "custom.param.value"],
      "scripts": ["fetchUserProfile": "..."],
      "authorizationURL": "https://public-auth.example.com/oauth2/authorize",
      "tokenURL": "https://auth.example.com/oauth2/token",
      "scope": "auth"
    ],
  ] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/connections/CONNECTION-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()
  ```
</AuthCodeGroup>

### Pass dynamic parameters

In certain circumstances, you may want to pass a dynamic value to an OAuth 2.0 Identity Provider. In this case, you can use the `authParamsMap` element of the `options` to specify a mapping between one of the existing additional parameters accepted by the [Auth0 `/authorize` endpoint](https://auth0.com/docs/api/authentication#social) to the parameter accepted by the Identity Provider.

Using the same example above, let's assume that you want to pass the `custom_param` parameter to the authorization endpoint, but you want to specify the actual value of the parameter when calling the Auth0 `/authorize` endpoint.

In this case, you can use one of the existing addition parameters accepted by the `/authorize` endpoint, such as `access_type`, and map that to the `custom_param` parameter:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/connections/CONNECTION-ID' \
    --header 'content-type: application/json' \
    --data '{ "options": { "client_id": "...", "client_secret": "...", "authParamsMap": { "custom_param": "access_type" }, "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" } }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/connections/CONNECTION-ID");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{ "options": { "client_id": "...", "client_secret": "...", "authParamsMap": { "custom_param": "access_type" }, "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" } }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/connections/CONNECTION-ID"

  	payload := strings.NewReader("{ "options": { "client_id": "...", "client_secret": "...", "authParamsMap": { "custom_param": "access_type" }, "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" }
    }")

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

  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/connections/CONNECTION-ID")
    .header("content-type", "application/json")
    .body("{ "options": { "client_id": "...", "client_secret": "...", "authParamsMap": { "custom_param": "access_type" }, "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" } }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/connections/CONNECTION-ID',
    headers: {'content-type': 'application/json'},
    data: {
      options: {
        client_id: '...',
        client_secret: '...',
        authParamsMap: {custom_param: 'access_type'},
        scripts: {fetchUserProfile: '...'},
        authorizationURL: 'https://auth.example.com/oauth2/authorize',
        tokenURL: 'https://auth.example.com/oauth2/token',
        scope: 'auth'
      },
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"options": @{ @"client_id": @"...", @"client_secret": @"...", @"authParamsMap": @{ @"custom_param": @"access_type" }, @"scripts": @{ @"fetchUserProfile": @"..." }, @"authorizationURL": @"https://auth.example.com/oauth2/authorize", @"tokenURL": @"https://auth.example.com/oauth2/token", @"scope": @"auth" }
  };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/connections/CONNECTION-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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/connections/CONNECTION-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 => "{ "options": { "client_id": "...", "client_secret": "...", "authParamsMap": { "custom_param": "access_type" }, "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" } }"
    CURLOPT_HTTPHEADER => [
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "options": { "client_id": "...", "client_secret": "...", "authParamsMap": { "custom_param": "access_type" }, "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" } 
  }"

  headers = { 'content-type': "application/json" }

  conn.request("PATCH", "/{yourDomain}/api/v2/connections/CONNECTION-ID", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/connections/CONNECTION-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.body = "{ "options": { "client_id": "...", "client_secret": "...", "authParamsMap": { "custom_param": "access_type" }, "scripts": { "fetchUserProfile": "..." }, "authorizationURL": "https://auth.example.com/oauth2/authorize", "tokenURL": "https://auth.example.com/oauth2/token", "scope": "auth" }
  }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/json"]
  let parameters = [
    "options": [
      "client_id": "...",
      "client_secret": "...",
      "authParamsMap": ["custom_param": "access_type"],
      "scripts": ["fetchUserProfile": "..."],
      "authorizationURL": "https://auth.example.com/oauth2/authorize",
      "tokenURL": "https://auth.example.com/oauth2/token",
      "scope": "auth"
    ],
  ] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/connections/CONNECTION-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()
  ```
</AuthCodeGroup>

Now when calling the `/authorize` endpoint, you can pass the access type in the `access_type` parameter, and that value will in turn be passed along to the authorization endpoint in the `custom_param` parameter.

## Pass extra headers

In some instances, you will need to pass extra headers to the <Tooltip href="/docs/glossary?term=Token+endpoint">Token endpoint</Tooltip> of an OAuth 2.0 provider. To configure extra headers, open the Settings for the Connection, and in the **Custom Headers** field, specify a JSON object with the custom headers as key-value pairs:

```json lines theme={null}
{
    "Header1" : "Value",
    "Header2" : "Value"
}
```

Let's use an example where an Identity Provider may require you to pass an `Authorization` header with [Basic access authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) credentials. In this scenario, you can specify the following JSON object in the **Custom Headers** field:

```json lines theme={null}
{
  "Authorization": "Basic [your credentials]"
}
```

Where `[your credentials]` are the actual credentials to send to the Identity Provider.

## Learn more

* [Social Identity Providers](/docs/authenticate/identity-providers/social-identity-providers)
* [Identity Providers](/docs/authenticate/identity-providers)
* [Protocols](/docs/authenticate/protocols)


# Handle Declined Authorization Permissions
Source: https://auth0.com/docs/authenticate/identity-providers/social-identity-providers/reprompt-permissions

Learn how to re-prompt the user to grant permissions for your application.

When your users are authorizing your application, some providers (such as Facebook) allow the user to select the attributes they wish to share.

By default, this selection is made only when the user authorizes the app for the first time. If your user chooses to not allow certain attributes (such as their email) that are required by your application, the user will not be able to access your application.

In such instances, your user will need to be re-prompted to grant permission to the required attribute(s) to login.

## Re-prompt for permissions

By setting the **prompt=consent** parameter when calling the [/authorize](https://auth0.com/docs/api/authentication/reference#social) endpoint of the [Authorization API](https://auth0.com/docs/api/authentication), your user will be prompted again to grant permissions for your application.

This parameter can also be set using Lock as an [Authentication Parameter](/docs/libraries/lock/lock-authentication-parameters) with **prompt: 'consent'**.

Alternatively, you can set this with [Auth0.js](https://github.com/auth0/auth0.js) using **prompt: 'consent'**.

## Keep reading

* [Learn more about handling declined Facebook permissions](https://developers.facebook.com/docs/facebook-login/handling-declined-permissions)
* [Learn more about GitHub scopes](https://developer.github.com/v3/oauth/#scopes)


# Create a Custom Social Connection with TikTok
Source: https://auth0.com/docs/authenticate/identity-providers/social-identity-providers/tiktok

Learn how to create a custom social connection with TikTok

<Card title="Before you start">
  Before you start configuring your application to use TikTok as a social connection, you need:

  1. A [developer TikTok account](https://developer.tiktok.com/).
  2. An Auth0 account with an application using Auth0 to authenticate your users.
  3. A URL for your Terms of Services page for the [TikTok Application Review Process](https://developers.tiktok.com/doc/getting-started-faq/).
  4. [Node.js](https://nodejs.org/en/) and [ngrok](https://ngrok.com/) installed on your local environment.
</Card>

## Configure TikTok

You can use TikTok as a social login to your application. Access and configure your TikTok developer account using the following steps:

1. In TikTok developer, select **Manage apps**.
2. Select **Connect an app**.
3. Under the **Configuration** section, add an application icon, application name, and description.
4. Under **Platforms**, choose your application type:

   1. For Web applications, add a valid URL.
   2. For Android, add the Android package name, Play Store URL, and application signature(s).
   3. For iOS, add the App Store URL and Bundle ID.
5. Under the Product menu, select **Add Product**.
6. Select the **Login Kit**.
7. Then, select the **TikTok API**.
8. In the Product section, add the URL of your Terms of Service page, the URL of your Privacy Policy page, and your redirect domain to the Login Kit. The redirect domain is your Auth0 domain found in [Dashboard > Applications > Applications](http://manage.auth0.com/#/applications) under the **Settings** tab. For example: `dev-test-1.us.auth0.com`.
9. Select **Save Changes**. Then, select **Submit for review**.
10. Wait until your application status moves from `Staging` to `Production`. It could take up to several hours for TikTok to review your application and update the status.

## Configure Auth0

You must create a custom connection to associate your TikTok instance with Auth0.

1. Navigate to [Auth0 Dashboard > Authentication > Social](http://manage.auth0.com/#/social).
2. Choose **Create Connection**.
3. Scroll to the bottom of the list and choose **Create Custom**.
4. Enter the following to create a **New Custom Social Connection**:

   1. Name: TikTok
   2. Authorization URL: TikTok’s Authorization URL `https://www.tiktok.com/auth/authorize/`
   3. Token URL: This will eventually be your proxy. Use a placeholder URL: `https://example.com`
   4. Scope: `user.info.basic`
   5. Client ID: Client key assigned to you by TikTok
   6. Client Secret: Client secret assigned to you by TikTok
   7. Purpose: Enable the connection for Authentication, Connected Accounts for Token Vault, or both. To learn more, read [User authentication vs Connected Accounts](/docs/secure/tokens/token-vault/connected-accounts-for-token-vault#user-authentication-vs-connected-accounts).
5. Configure the [Fetch User Profile Script](/docs/authenticate/identity-providers/social-identity-providers/oauth2#fetch-user-profile-script) to fetch profile information from [TikTok's user\_info endpoint](https://developers.tiktok.com/doc/tiktok-api-v2-get-user-info/). Map attributes to Auth0’s normalized user profile.

   <Callout icon="file-lines">
     Auth0 only requires the `user_id attribute`, which corresponds to TikTok’s `union_id`.
   </Callout>

```javascript lines theme={null}
function fetchUserProfile(accessToken, context, cb) {
  const axios = require('axios@0.22.0');
  const userInfoEndpoint = 'https://open.tiktokapis.com/v2/user/info?fields=union_id';
  const headers = { 'Authorization': 'Bearer ' + accessToken };

  axios
    .get(userInfoEndpoint, { headers })
    .then(res => {
      if (res.status !== 200) {
        return cb(new Error(res.data));
      }

      const profile = {
        user_id: res.data.user.union_id,
      };

      cb(null, profile);
    })
    .catch(err => cb(err));
}
```

6. Click **Create**.

7. Navigate to the application you want to use with the TikTok connection under [Dashboard > Applications > Applications](http://manage.auth0.com/#/applications).

8. Under the **Connections** tab, toggle on the TikTok option.

## Pass customs parameters to TikTok with the Management API

Since TikTok uses a `client_key` parameter instead of `client_id`, you must use the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to pass the `client_key` parameter during authentication.

To use the Management API, you need to generate an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>.

1. Navigate to Auth0 [Dashboard > Applications > APIs](http://manage.auth0.com/#/apis) and select the **Auth0 Management API**.
2. Select the **API Explorer** tab.
3. Select **Create & Authorize Test Application.**
4. Copy the provided token.
5. Navigate to the [Auth0 Management API Explorer](https://auth0.com/docs/api/management/v2). You may need to open an incognito window.
6. Select **Set API Token** in the top, left-hand corner.

   <Frame>
     <img alt="Screenshot of Set API Token for TikTok" />
   </Frame>
7. Paste the token and select **Set Token**.

You should now be able to configure your Auth0 tenant with the Management API.

### Configure the `client_key` field

1. Use the [Get a connection](https://auth0.com/docs/api/management/v2#!/Connections/get_connections_by_id) method to retrieve the `options` object values. The following is a sample response object:

```json lines theme={null}
{
  "options": {
    "client_id": "",
    "client_secret": "",
    "scope": "user.info.basic"
  }
}
```

2. Add the `upstream_params` object with the `client_key` field:

```json lines theme={null}
{
  "options": {
    "client_id": "",
    "client_secret": "",
    "scope": "user.info.basic",
    "upstream_params": { 
      "client_key": { "value": "<Client Key from TikTok>" } 
    }
  }
}
```

3. Use the [Update a connection](https://auth0.com/docs/api/management/v2#!/Connections/patch_connections_by_id) method with the `options` object as the body. Auth0 will send the `client_key=<value>` parameter to [TikTok's authorization endpoint](https://developers.tiktok.com/doc/login-kit-web/).

## Access token request

You cannot pass custom parameters in a request to the Authentication API's [`/token`](https://developers.tiktok.com/doc/login-kit-manage-user-access-tokens/) endpoint to gain an access or <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip>. You must proxy the request to the <Tooltip href="/docs/glossary?term=token+endpoint">token endpoint</Tooltip> and append the `client_key` parameter programmatically with proxy endpoints in your environment.

### Deploy TikTok integration proxy

1. Use the sample code from the [GitHub](https://github.com/tylerkeesling/tiktok-access-token-proxy) repository and follow the instructions in the README to install dependencies and start the development server.

   1. The example server has one `POST` route, `/proxy/token`. The server should be running on `http://localhost:3333`.
2. Copy the proxy endpoint to be used in your TikTok Developer setup. The proxy endpoint should be something similar to `https://405a-104-129-13b-250.ngrok.io/proxy/token`.
3. In TikTok Developer, navigate back to the social connection configuration. Update the Token URL that you set to `https://example.com` and enter the proxy URL.

Once the configuration is saved, your users should be able to log in with TikTok.


# Test Connections
Source: https://auth0.com/docs/authenticate/identity-providers/test-connections

Describes how to test a connection.

Generally, to test a connection, you must log in to the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

1. Navigate to [Auth0 Dashboard](https://manage.auth0.com/#), and select **Authentication**, then select the type of connection you want to test.
2. Locate the connection you want to test, and select **Try Connection** from its **More Options** menu (**...**).
3. Log in with the identity provider.
4. Wait for the **It Works!** page that displays the result.

Auth0 simulates the authentication flow as if it were an application, displaying the User Profile resulting from a successful authentication.

## Test partner connections

If you are testing a connection that belongs to someone else, and you don't have test credentials with them, it is not possible to be logged in to the Auth0 Dashboard. This is common when connecting to Enterprise connections, such as <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> <Tooltip href="/docs/glossary?term=Identity+Providers">Identity Providers</Tooltip> (IdPs) or Active Directory. The solution? Your partners can test the new connection.

1. Register a test app.

   * Navigate to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), and select **Create Application**. You can give it any name (for example, `Test App`).
   * In the settings of the newly-created app, set **Allowed Callback URLs** to `http://jwt.io`.
   * Select **Save Changes**.
2. Send your partner the link to log in.

   <AuthCodeBlock />

   Replace these two parameters:

   * `client_id`: Client ID of the application created in Step 1.
   * `connection`: Name of the connection you want to test.
3. Test the connection. When your partner follows the link, they will be redirected to their configured Identity Provider (the connection). After successful authentication, they will be sent back to [JWT.io](http://jwt.io) where all user properties will be decoded from the token.

<Callout icon="file-lines">
  The test app is not a real app. [JWT.io](http://jwt.io) is a testing website that decodes tokens sent in a URL fragment.
</Callout>


# View Connections
Source: https://auth0.com/docs/authenticate/identity-providers/view-connections

Describes how to view enabled connections in the Auth0 Dashboard.

You can view all of the available and configured connections using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. The configured connections can be used to log in to your applications.

1. Navigate to [Auth0 Dashboard > Authentication](https://manage.auth0.com/#/connections).
2. Select a connection type:

* [Database](https://manage.auth0.com/#/connections/database)
* [Social](https://manage.auth0.com/#/connections/social)
* [Enterprise](https://manage.auth0.com/#/connections/enterprise)
* [Passwordless](https://manage.auth0.com/#/connections/passwordless)

## Learn more

* [Enable Enterprise Connections](/docs/authenticate/identity-providers/enterprise-identity-providers/enable-enterprise-connections)
* [Set Up Database Connections](/docs/get-started/applications/set-up-database-connections)
* [Update Application Connections](/docs/get-started/applications/update-application-connections)
* [Verify Connections](/docs/troubleshoot/basic-issues/verify-connections)


# Passwordless Authentication with Magic Links
Source: https://auth0.com/docs/authenticate/passwordless/authentication-methods/email-magic-link

Learn how to use Passwordless connections with the magic link authentication factor.

You can configure a <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> connection to send a Magic Link to a user through email to complete authentication.

To learn more, read [Configure Email or SMS for Passwordless Authentication](/docs/authenticate/login/auth0-universal-login/passwordless-login/email-or-sms).

## How it works

When a user opens a Magic Link, Auth0 logs them in directly. It is similar in function to them receiving an email with a one-time password (OTP), returning to your application, and entering the OTP, but without having to actually perform those steps.

### Limitations

Magic Links are not supported for <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>.

When using Magic Links with Classic Login, both the initial request and its response must take place in the same browser or the transaction will fail. This is particularly relevant for iOS users, who cannot change their default web browser.

For example, the user might make the initial request using the Chrome browser, but when the user opens the Magic Link in their email, iOS automatically opens it in Safari (the default browser). If this happens, the transaction will fail.

### Classic Login flow with Magic Links

<Frame>
  <img alt="" />
</Frame>

The user then clicks the button or link in the email and is automatically signed in to your application.

## Configure the connection

1. In the Auth0 Dashboard, go to [Authentication > Passwordless](https://manage.auth0.com/#/connections/passwordless), and then enable the **Email** toggle.
2. Select **Email** to open the configuration window, switch to the **Settings** view, and enter your email's **From**, **Subject**, and **Message** text.

   <Callout icon="file-lines">
     You must change the **From** value to an email address that does not use the `auth0.com` domain for Auth0 to send your custom email templates. If you do not, Auth0 sends the default email template.
   </Callout>
3. Enter any **Authentication Parameters** you would like to include in the generated sign-in link.
4. Decide if you want to **Disable Sign Ups**. If you enable this setting, you can allow passwordless access for only existing users, but may expose your application to the threat of user enumeration attacks. To learn more, read [Passwordless Connections Best Practices](/docs/authenticate/passwordless/best-practices).
5. Select **Save**.

### Multi-language support

The **Message** area supports multiple languages.

To specify a language, call the [Auth0 Authentication API Get Code or Link endpoint](https://auth0.com/docs/api/authentication#get-code-or-link) and set the value of the `x-request-language` header. When this header is not set, the language is extracted from the `accept-language` header, which is automatically set by the browser.

### Message syntax

The **Message** area accepts Liquid syntax. You can use this syntax, combined with parameter values, to programmatically construct elements of the message.

For example, you can reference the `request_language` parameter to change the language of the message:

```liquid lines theme={null}
{% if request_language contains 'dutch' %}
   Hier is uw verificatie code: {{ code }}
{% endif %}
{% if request_language contains 'fr-FR' %}
   Ceci est votre code: {{ code }}
{% endif %}
```

The following parameters are available when defining the message template:

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>code</code></td>
      <td>The password to use.</td>
    </tr>

    <tr>
      <td><code>link</code></td>
      <td>The generated sign-in link.</td>
    </tr>

    <tr>
      <td><code>application.name</code></td>
      <td>The name of the application with which the user is signing up.</td>
    </tr>

    <tr>
      <td><code>request\_language</code></td>
      <td>The requested language for message content.</td>
    </tr>

    <tr>
      <td><code>operation</code></td>
      <td>Indicates when the template has been triggered by an update to a user's email through the API. When triggered, the value is <code>change\_email</code>, otherwise it is <code>null</code>.</td>
    </tr>
  </tbody>
</table>

## Update Classic Login settings

If you are using Classic Login for your application, you must update the page template to implement Magic Links.

1. In the Auth0 Dashboard, go to [**Branding > Universal Login > Advanced Options**](https://manage.auth0.com/#/login_settings).

2. Switch to the **Login** view, locate the **Default Templates** dropdown, and select **Lock (passwordless).**

3. Next, update the `Auth0LockPasswordless` section of code with a new parameter. Add the `passwordlessMethod` to your template.

   ```bash lines theme={null}
   passwordlessMethod: 'link',
   ```

4. Select **Save**.

To learn more about embedded login configuration options, read [Passwordless Authentication with Embedded Login](/docs/authenticate/passwordless/implement-login/embedded-login).

## Enable applications

Switch to the **Applications** view, and enable the applications for which you would like to use Passwordless Email.

## Email providers

Auth0 sends emails from its own SMTP provider by default. Auth0's built-in email provider is designed solely for testing purposes and does not support customization of email templates.

[Configure your own SMTP email provider](/docs/customize/email/smtp-email-providers) to manage, monitor, and troubleshoot your email communications, and customize email templates.

Auth0 supports the following email providers:

* [Mandrill](/docs/customize/email/smtp-email-providers/configure-mandrill-as-external-smtp-email-provider)
* [Amazon SES](/docs/customize/email/smtp-email-providers/configure-amazon-ses-as-external-smtp-email-provider)
* [SendGrid](/docs/customize/email/smtp-email-providers/configure-sendgrid-as-external-smtp-email-provider)
* [SparkPost](/docs/customize/email/smtp-email-providers/configure-sparkpost-as-external-smtp-email-provider)
* [Mailgun](/docs/customize/email/smtp-email-providers/configure-mailgun-as-external-smtp-email-provider)
* [Custom SMTP external email provider](/docs/customize/email/smtp-email-providers/configure-custom-external-smtp-email-provider)


# Passwordless Authentication with Email
Source: https://auth0.com/docs/authenticate/passwordless/authentication-methods/email-otp

Learn how how to use Passwordless connections with the email authentication factor.

You can configure a <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> connection to send a one-time password (OTP) to a user through email to complete authentication.

To learn more, read [Configure Email or SMS for Passwordless Authentication](/docs/authenticate/login/auth0-universal-login/passwordless-login/email-or-sms).

## How it works

When a new user receives an OTP and enters it for the first time on your website, their user profile is created on the `email` connection before being authenticated by Auth0.

If the email address that the OTP was sent to matches an existing user, Auth0 authenticates the user:

### Embedded Login

<Frame>
  <img alt="Passwordless email workflow diagram with embedded login" />
</Frame>

### Universal Login

<Frame>
  <img alt="Passwordless email workflow diagram with universal login" />
</Frame>

## Configure the connection

1. Navigate to [Auth0 Dashboard > Authentication > Passwordless](https://manage.auth0.com/#/connections/passwordless), and enable the **Email** toggle.
2. Select **Email** to open the configuration window, switch to the **Settings** view, and then enter your email's **From**, **Subject**, and **Message** text.

   <Callout icon="file-lines">
     You must change the **From** value to an email address that does not use the `auth0.com` domain for Auth0 to send your custom email templates. If you do not, Auth0 sends the default email template.
   </Callout>
3. Configure **OTP Expiry** and **OTP Length.**

   * Only the last OTP (or link) issued will be accepted. Once the latest one is issued, any others are invalidated. Once used, the latest one is also invalidated.
   * Only three failed attempts to input the OTP are allowed. After this, a new code will need to be requested.
   * The OTP issued will be valid (by default) for three minutes before it expires.
   * If you choose to extend the amount of time it takes for your OTP to expire, you should also extend the length of the OTP. Otherwise, an attacker has a larger window of time to attempt to guess a short code.
4. Decide if you want to **Disable Sign Ups**. If you enable this setting, you can allow passwordless access for only existing users, but may expose your application to the threat of user enumeration attacks. To learn more, read [Passwordless Connections Best Practices](/docs/authenticate/passwordless/best-practices).
5. Select **Save**.

### Multi-language support

The **Message** area supports multiple languages.

To specify a language, call the [Auth0 Authentication API Get Code or Link endpoint](https://auth0.com/docs/api/authentication#get-code-or-link) and set the value of the `x-request-language` header. When this header is not set, the language is extracted from the `accept-language` header, which is automatically set by the browser.

### Message syntax

The **Message** area accepts Liquid syntax. You can use this syntax, combined with parameter values, to programmatically construct elements of the message.

For example, you can reference the `request_language` parameter to change the language of the message:

```liquid lines theme={null}
{% if request_language contains 'dutch' %}
   Hier is uw verificatie code: {{ code }}
{% endif %}
{% if request_language contains 'fr-FR' %}
   Ceci est votre code: {{ code }}
{% endif %}
```

The following parameters are available when defining the message template:

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>code</code></td>
      <td>The password to use.</td>
    </tr>

    <tr>
      <td><code>link</code></td>
      <td>The generated sign-in link.</td>
    </tr>

    <tr>
      <td><code>application.name</code></td>
      <td>The name of the application with which the user is signing up.</td>
    </tr>

    <tr>
      <td><code>request\_language</code></td>
      <td>The requested language for message content.</td>
    </tr>

    <tr>
      <td><code>operation</code></td>
      <td>Indicates when the template has been triggered by an update to a user's email through the API. When triggered, the value is <code>change\_email</code>, otherwise it is <code>null</code>.</td>
    </tr>
  </tbody>
</table>

If the user is logged in through an [Organization](/docs/manage-users/organizations/organizations-overview), the following parameters are also available:

* `organization.id`
* `organization.display_name`
* `organization.name`
* `organization.metadata`
* `organization.branding.logo_url`
* `organization.branding.colors.primary`
* `organization.branding.colors.page_background`

For more information on these parameters and their values, read the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> [Get organization](https://auth0.com/docs/api/management/v2#!/Organizations/get_organizations_by_id) endpoint.

## Enable applications

Switch to the **Applications** view, and enable the applications for which you would like to use Passwordless Email.

## Email providers

Auth0 sends emails from its own SMTP provider by default. Auth0's built-in email provider is designed solely for testing purposes and does not support customization of email templates.

[Configure your own SMTP email provider](/docs/customize/email/smtp-email-providers) to manage, monitor, and troubleshoot your email communications, and customize email templates.

Auth0 supports the following email providers:

* [Mandrill](/docs/customize/email/smtp-email-providers/configure-mandrill-as-external-smtp-email-provider)
* [Amazon SES](/docs/customize/email/smtp-email-providers/configure-amazon-ses-as-external-smtp-email-provider)
* [Azure Communication Services](/docs/customize/email/smtp-email-providers/configure-azure-comm-service-as-smtp-email-provider)
* [SendGrid](/docs/customize/email/smtp-email-providers/configure-sendgrid-as-external-smtp-email-provider)
* [SparkPost](/docs/customize/email/smtp-email-providers/configure-sparkpost-as-external-smtp-email-provider)
* [Mailgun](/docs/customize/email/smtp-email-providers/configure-mailgun-as-external-smtp-email-provider)
* [Custom SMTP external email provider](/docs/customize/email/smtp-email-providers/configure-custom-external-smtp-email-provider)


# Passwordless Authentication with SMS
Source: https://auth0.com/docs/authenticate/passwordless/authentication-methods/sms-otp

Learn how to use Passwordless connections with the SMS authentication method.

You can configure <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> authentication to send a one-time password (OTP) to a user through SMS. To learn more, read [Configure Email or SMS for Passwordless Authentication](/docs/authenticate/login/auth0-universal-login/passwordless-login/email-or-sms).

Auth0 supports using [Twilio](https://www.twilio.com) and a custom phone provider to send OTPs. If you would like to use a custom phone provider with Auth0 Actions, read [Configure a Custom Phone Provider](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider) or [Configure a Custom Phone Provider with Terraform](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider/configure-a-custom-phone-provider-with-terraform).

## How it works

When a new user receives a code and enters it for the first time in your application, their user profile is created on the `sms` connection before being authenticated by Auth0.

If the phone number that the OTP was sent to matches an existing user, Auth0 authenticates the user:

### Embedded Login

<Frame>
  <img alt="SMS workflow for passwordless authentication" />
</Frame>

### Universal Login

<Frame>
  <img alt="Passwordless sms workflow diagram with universal login" />
</Frame>

## Configure the phone provider

1. In the Auth0 Dashboard, navigate to [Branding > Phone Provider](https://manage.auth0.com/#/phone/templates/phone/provider).
2. Enable the Phone Message Provider toggle.

   <Frame>
     <img alt="Auth0 Dashboard > Branding > Phone Provider > Enable Phone Message Provider" />
   </Frame>
3. Select your phone message provider.

   1. To use Twilio, follow [Configure Twilio as a Phone Messaging Provider](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-twilio-as-a-phone-messaging-provider).
   2. To use a custom provider, follow [Configure a Custom Phone Provider](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider) to use Auth0 Actions.
4. Select your delivery method.
5. **Save** your changes.

## Legacy SMS gateway

If Auth0 Action's custom phone provider cannot support your use case, you can manage the custom SMS gateway on [passwordless SMS connections](/docs/authenticate/passwordless) with <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. To learn more, read [Set Up Custom SMS Gateway for Passwordless Connections](/docs/authenticate/passwordless/authentication-methods/use-sms-gateway-passwordless).

### Configure Passwordless SMS settings

1. In **Message**, enter the body text of the SMS.

   <Callout icon="file-lines">
     The `@@password@@` placeholder will automatically be replaced with the one-time password that is sent to the user.
   </Callout>
2. Adjust settings for your **OTP Expiry** and **OTP Length**.

   * Only the last one-time password (or link) issued will be accepted. Once the latest one is issued, any others are invalidated. Once used, the latest one is also invalidated.
   * Only three failed attempts to input the one-time password are allowed. After this, a new code will need to be requested.
   * The one-time password issued will be valid (by default) for three minutes before it expires.
   * If you choose to extend the amount of time it takes for your one-time password to expire, you should also extend the length of the one-time password code. Otherwise, an attacker has a larger window of time to attempt to guess a short code.
3. Decide if you want to **Disable Sign Ups**. If you enable this setting, you can allow passwordless access for only existing users, but may expose your application to the threat of user enumeration attacks. To learn more, read [Passwordless Connections Best Practices](/docs/authenticate/passwordless/best-practices).
4. Select **Save**.

#### Multi-language support

The **Message** area supports multiple languages.

To specify a language, call the [Auth0 Authentication API Get Code or Link endpoint](https://auth0.com/docs/api/authentication#get-code-or-link) and set the value of the `x-request-language` header. When this header is not set, the language is extracted from the `accept-language` header, which is automatically set by the browser.

#### Message syntax

The **Message** area accepts Liquid syntax. You can use this syntax, combined with parameter values, to programmatically construct elements of the message.

For example, you can reference the `request_language` parameter to change the language of the message:

```liquid lines theme={null}
{% if request_language contains 'dutch' %}
   Hier is uw verificatie code: {{ password }}
{% endif %}
{% if request_language contains 'fr-FR' %}
   Ceci est votre code: {{ password }}
{% endif %}
```

The following parameters are available when defining the message template:

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>password</code> or <code>code</code></td>
      <td>The password to use.</td>
    </tr>

    <tr>
      <td><code>phone\_number</code></td>
      <td>The user's phone number.</td>
    </tr>

    <tr>
      <td><code>application.name</code></td>
      <td>The name of the application with which the user is signing up.</td>
    </tr>

    <tr>
      <td><code>request\_language</code></td>
      <td>The requested language for message content.</td>
    </tr>
  </tbody>
</table>

To learn more about using Liquid, read [Liquid for Designers on GitHub](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers).

### Enable applications

Switch to the **Applications** view, and enable the applications for which you would like to use Passwordless SMS.

## Learn more

* [Auth0's Unified Phone Experience](/docs/customize/phone-messages/unified-phone)
* [Use the Unified Phone Experience for Passwordless](/docs/customize/phone-messages/unified-phone/unified-phone-experience-passwordless)
* [Configure Auth0 Unified Phone Experience](/docs/customize/phone-messages/unified-phone/configure-unified-phone)


# Set Up Custom SMS Gateway for Passwordless Connections
Source: https://auth0.com/docs/authenticate/passwordless/authentication-methods/use-sms-gateway-passwordless

Learn how to set up a custom SMS gateway for Passwordless connections.

<Warning>
  This guide is the legacy custom SMS implementation for Passwordless connections and only applies to Auth0 tenants created prior to March 2025.

  New tenants should follow the [Passwordless Authentication with SMS phone provider instructions](/docs/authenticate/passwordless/authentication-methods/sms-otp#configure-the-phone-provider).
</Warning>

This guide will show you how to use a custom SMS gateway to send out your one-time-use codes.

By default, [Passwordless SMS connections](/docs/authenticate/passwordless/authentication-methods/sms-otp) use [Twilio](https://www.twilio.com) to send out one-time use codes. However, if you have a custom SMS gateway, you can modify your connection to use that instead.

<Callout icon="file-lines">
  Auth0 does not support basic SMS authentication.
</Callout>

1. Set up a SMS passwordless connection. To learn how, read the Implement Passwordless section in [Passwordless Connections](/docs/authenticate/passwordless).
2. [Get an Access Token for the Management API](/docs/secure/tokens/access-tokens/management-api-access-tokens). You will need this to make calls to the Management API to update your Passwordless connection.
3. Use the [GET Connections](https://auth0.com/docs/api/management/v2#!/Connections/get_connections) endpoint to retrieve information about the connections associated with your tenant. More specifically, you need to get the ID for your Passwordless SMS connection so that you can use it in a later API call that updates the connection itself.
   Be sure to replace `ACCESS_TOKEN` with the token you obtained in step 1 before making the following call to the Management API:

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request GET \
    --url https://your-auth0-tenant.com/api/v2/connections \
    --header 'authorization: Bearer {yourAccessToken}'
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://your-auth0-tenant.com/api/v2/connections");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer {yourAccessToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines theme={null}
  package main

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

  func main() {

  	url := "https://your-auth0-tenant.com/api/v2/connections"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer {yourAccessToken}")

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

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

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

  }
  ```

  ```java Java lines theme={null}
  HttpResponse response = Unirest.get("https://your-auth0-tenant.com/api/v2/connections")
    .header("authorization", "Bearer {yourAccessToken}")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://your-auth0-tenant.com/api/v2/connections',
    headers: {authorization: 'Bearer {yourAccessToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C lines theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourAccessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://your-auth0-tenant.com/api/v2/connections"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP lines theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://your-auth0-tenant.com/api/v2/connections",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourAccessToken}"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("your-auth0-tenant.com")

  headers = { 'authorization': "Bearer {yourAccessToken}" }

  conn.request("GET", "/api/v2/connections", headers=headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://your-auth0-tenant.com/api/v2/connections")

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

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer {yourAccessToken}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift lines theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourAccessToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://your-auth0-tenant.com/api/v2/connections")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

The response from the endpoint will be an array of objects. Each object represents one connection affiliated with your tenant.
4\. Identify your connection ID. You can find the ID associated with your Passwordless connection by reviewing the array of objects you returned from the [GET Connections endpoint](https://auth0.com/docs/api/management/v2#!/Connections/get_connections) in step 2.
To find the specific object for your Passwordless connection, you can search for the `"name": "sms"` property. Notice that the connection currently displays the Twilio information you provided during the setup process.

```json lines expandable theme={null}
[
    {
        "id": "con_UX85K7K0N86INi9U",
        "options": {
            "disable_signup": false,
            "name": "sms",
            "twilio_sid": "TWILIO_SID",
            "twilio_token": "TWILIO_AUTH_TOKEN",
            "from": "+15555555555",
            "syntax": "md_with_macros",
            "template": "Your SMS verification code is: @@password@@",
            "totp": {
                "time_step": 300,
                "length": 6
            },
            "messaging_service_sid": null,
            "brute_force_protection": true
        },
        "strategy": "sms",
        "name": "sms",
        "is_domain_connection": false,
        "realms": [
            "sms"
        ],
    }
]
```

5. Update the connection. You can do this by making a PATCH call to the [Update a Connection endpoint](https://auth0.com/docs/api/management/v2#!/Connections/patch_connections_by_id). More specifically, you'll be updating the connections `options` object to provide information about the SMS Gateway.

   <Warning>
     You must send the entire `options` object with each call; otherwise, you will overwrite the existing data that is not included in subsequent calls.
   </Warning>

   Make the following changes:

   * Remove both the `twilio_sid` and `twilio_token` parameters
   * Add the `provider` parameter, and set it to `sms_gateway`
   * Add the `gateway_url` parameter, and set it to the URL of your SMS gateway. Auth0 must be able to reach this URL for it to use your gateway to send messages on your behalf.

   Your payload will look something like this:

   ```json lines theme={null}
   {
       "options": {
         "strategy": "sms",
         "provider": "sms_gateway",
         "gateway_url": "{urlOfYourGateway}",
         "from": "+1 234 567",
         "template": "Your verification code is: @@password@@",
         "brute_force_protection": true,
         "forward_req_info": "true",
         "disable_signup": false,
         "name": "sms",
         "syntax": "md_with_macros",
         "totp": {
           "time_step": 300,
           "length": 6
         }
       },
       "is_domain_connection": false,
   }
   ```

## Authenticated requests

If your SMS Gateway accepts authenticated requests that are token-based, you can add the following to your `options` object:

```json lines theme={null}
"gateway_authentication": {
    "method": "bearer",
    "subject": "urn:Auth0",
    "audience": "urn:MySmsGateway",
    "secret": "MySecretToSignTheToken",
    "secret_base64_encoded": false
}
```

When you include `gateway_authentication` in your `options` object, Auth0 adds a [JSON Web Token](/docs/secure/tokens/json-web-tokens) to the `Authorization` header whenever it sends requests to your SMS gateway. The token contains the `gateway_authentication.subject` and `gateway_authentication.audience` values, and is signed with `gateway_authentication.secret`.

If your secret is base64-url-encoded, set `secret_base64_encoded` to `true`.

Once you have updated your connection, Auth0 will send the following to your SMS Gateway every time a user signs up or logs in with your <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> connection.

```json lines theme={null}
{
  "recipient": "+1 399 999",
  "body": "Your verification code is: 12345",
  "sender": "+1 234 567"
}
```

If you set the `forward_req_info` property in the `options` object to `true`, the gateway will also receive information from the HTTP request that initiated the Passwordless process. This includes the IP address of the client calling `/passwordless/start` and its User Agent.

```json lines theme={null}
{
  "recipient": "+1 399 999",
  "body": "Your verification code is: 12345",
  "sender": "+1 234 567",
  "req" : { 
      "ip" : "167.56.227.117",
      "user-agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.109 Safari/537.36"
       }
}
```

## Error handling

Auth0 will only consider the HTTP code returned from the SMS Gateway; it ignores the rest of the response (e.g., response body and response type).

If the SMS Gateway returns an HTTP code other than 200, the `/passwordless/start` endpoint will return an HTTP 400 code and a response that looks like the following:

```json lines theme={null}
{
 "error":"sms_provider_error",
 "error_description":"Unexpected response while calling the SMS gateway: <HTTP Code Returned by the SMS Gateway>"}
}
```

If the SMS Gateway returns HTTP 401, the `error_description` will be **Authentication failed while calling the SMS gateway: 401**. (Please note that the error description verbiage is subject to change at any time.)

Auth0 enforces a timeout of 30 seconds for HTTP calls to custom SMS Gateways. If the SMS Gateway fails to reply within this time frame, the `/passwordless/start` endpoint will also return an HTTP 400 code. The response will have the format shown above and the `error_description` field will be **Timeout while calling the SMS gateway: \<Timeout Code>**. (Again, the error description verbiage is subject to change at any time.)


# Passwordless Connections Best Practices
Source: https://auth0.com/docs/authenticate/passwordless/best-practices

Learn about best practices when working with Passwordless connections.

## Implement login

You can implement <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> authentication by redirecting to Auth0's <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> or by embedding login in your application. We always recommend that you implement Universal Login. To learn why, read [Centralized Universal Login vs. Embedded Login](/docs/authenticate/login/universal-vs-embedded-login).

To learn how to implement Passwordless authentication, read the following articles:

* [Passwordless with Universal Login](/docs/authenticate/passwordless/passwordless-with-universal-login)
* [Passwordless Authentication with Universal Login](/docs/authenticate/passwordless/implement-login/universal-login)
* [Passwordless Authentication with Embedded Login](/docs/authenticate/passwordless/implement-login/embedded-login)

## Use SMS and email as authentication factors

Auth0's passwordless implementation enables authenticating users with a single factor. That single factor can be one-time-use code sent by email or SMS, or a magic link sent by email.

Although using email or SMS can be more secure than a weak password, both have known issues:

* Phone numbers are not sufficient for user authentication. The [SS7 phone routing system used by cellular networks has verified weaknesses](https://thehackernews.com/2017/05/ss7-vulnerability-bank-hacking.html) which have led to it not being recommended as an authentication factor. There are many attack vectors available, ranging from the use of social engineering, to swapping SIM cards and buying access to the SS7 network.
* Email address possession is not sufficient for user authentication (aliases, forwarding, multiple users in one account are all examples). Email providers vary in their security practices and some do not require any establishment of a user's identity. SMTP is a very old protocol, and many providers still route SMTP traffic unencrypted leading to an increased chance of an interception attack.

For these reasons, we recommend that if you use passwordless authentication, you also implement [Multi-factor Authentication (MFA)](/docs/secure/multi-factor-authentication) with a different factor when the user performs a security-sensitive operation.

## Prevent phishing attacks

An example of what a possible phishing attack could look like is as follows:

1. The user clicks a link in a malicious email or website.
2. The user lands on the attacker's fake site, where they are prompted to enter their phone number to authenticate.
3. The user enters their phone number, and the attacker enters the same phone number in the legitimate application.
4. The legitimate application sends an SMS to the user.
5. The user types the one-time-use code in the attacker's website.
6. The attacker can now log in to the legitimate website.

To decrease the chances of success for this attack, the user should expect that the SMS clearly identifies the application. You should configure the SMS template so it mentions the tenant name and/or the Application Name:

```http wrap lines theme={null}
Your verification code for accessing's Acme @@application.name@@ is @@code@@
```

## Prevent brute force attacks

Auth0 has the following protections against brute force attacks:

* Only the most recent one-time-use code (or link) issued will be accepted. Once the latest one is issued, any others are invalidated. Once used, the latest one is also invalidated.
* Only three failed attempts to input any single one-time-use code are allowed. After this, a new code will need to be requested.
* The one-time-use code issued will be valid for three minutes (by default) before it expires.
* If a passwordless user has been blocked [administratively](/docs/manage-users/user-accounts/block-and-unblock-users), Auth0 will not send any OTP codes over SMS or email until the user is unblocked. This behavior protects your SMS and email providers from receiving unnecessary requests.

The one-time-use code expiration time can be altered at [Auth0 Dashboard > Authentication > Passwordless](https://manage.auth0.com/#/connections/passwordless).

## Prevent user enumeration attacks

User enumeration is when a malicious actor uses brute-force techniques to either guess or confirm valid users in a system.

When **Disable Sign Ups** is enabled, your application may become vulnerable to user enumeration attacks. Auth0 recommends that you do not enable this setting to ensure the maximum security of your application and its users.

If you do enable **Disable Signs Ups**, [Brute-force Protection](/docs/secure/attack-protection/brute-force-protection) may mitigate the threat of some of these attacks, but it does not fully protect your application.

## Link accounts

Users might want to authenticate using different passwordless factors during their lifetime. For example, they could initially sign up with an SMS, and later start authenticating with an email. You can achieve that by enabling them to link their different profiles using [account linking](/docs/manage-users/user-accounts/user-account-linking/link-user-accounts).

## Set the auth0-forwarded-for header for rate-limit purposes

The `/passwordless/start` endpoint has a [rate limit](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy) of 50 requests per hour per IP address. If you call the API from the server-side, your backend's IP may easily hit these rate limits. To learn how to address this issue, read the Rate Limiting in Passwordless Endpoints section of [Using Passwordless APIs](/docs/authenticate/passwordless/implement-login/embedded-login/relevant-api-endpoints).


# Implement Login with Passwordless
Source: https://auth0.com/docs/authenticate/passwordless/implement-login

Describes the available methods for implementing passwordless login with Auth0.

You can implement <Tooltip href="/docs/glossary?term=passwordless">passwordless</Tooltip> login using either [hosted login](/docs/authenticate/passwordless/implement-login/universal-login) or [embedded login](/docs/authenticate/passwordless/implement-login/embedded-login).

To learn more about the differences between these two options, read [Hosted Login vs. Embedded Login](/docs/authenticate/login/universal-vs-embedded-login).


# Passwordless Authentication with Embedded Login
Source: https://auth0.com/docs/authenticate/passwordless/implement-login/embedded-login

Describes how to implement Passwordless authentication with Universal Login.

If you'd like to embed the login user interface in your application, you can do it by using our [Embedded Passwordless API](/docs/authenticate/passwordless/implement-login/embedded-login/relevant-api-endpoints) or our SDKs.

Depending on the kind of application you want to build, you'll need to implement it differently:

* For Single Page Applications (SPAs) (for example, Angular or React), read [Embedded Passwordless Authentication for Single-page Applications (SPA)](/docs/authenticate/passwordless/implement-login/embedded-login/spa).
* For Native applications (for example, iOS, Android, or desktop applications), read [Embedded Passwordless Login in Native Applications](/docs/authenticate/passwordless/implement-login/embedded-login/native).
* For Regular Web Applications (for example, NodeJS, Java, Rails, or .NET), read [Embedded Passwordless Login in Regular Web Applications](/docs/authenticate/passwordless/implement-login/embedded-login/webapps).

Embedded login in regular web applications and SPAs require configuration of cross-origin authentication. To learn more, read [Cross-Origin Authentication](/docs/authenticate/login/cross-origin-authentication).

## Learn more

* [Passwordless Authentication](/docs/authenticate/passwordless)
* [Passwordless Connections Best Practices](/docs/authenticate/passwordless/best-practices)
* [Using Passwordless APIs](/docs/authenticate/passwordless/implement-login/embedded-login/relevant-api-endpoints)


# Embedded Passwordless Login in Native Applications
Source: https://auth0.com/docs/authenticate/passwordless/implement-login/embedded-login/native

Describes implementing Passwordless authentication with embedded login in native applications.

To use the Embedded <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> APIs in Native applications, make sure you enable the **Passwordless OTP** grant at [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) in your application's settings under **Advanced Settings** > **Grant Types**.

Passwordless authentication for Native applications consists of two steps:

* Capture the user identifier in your application (the user's email or phone number) and invoke the `/passwordless/start` endpoint to initiate the passwordless flow. The user will get an email or an SMS with a one-time password.
* Prompt the user for the one-time-use code, and call the `/oauth/token` endpoint to get authentication tokens.

Below we list a few code snippets that can be used to call these API endpoints for different scenarios.

**Send a one-time-use password via email**

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/passwordless/start' \
    --header 'content-type: application/json' \
    --data '{"client_id": "{yourClientId}",  "connection": "email",   "email": "USER_EMAIL",  "send": "code"}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/passwordless/start");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"client_id": "{yourClientId}",  "connection": "email",   "email": "USER_EMAIL",  "send": "code"}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/passwordless/start"

  	payload := strings.NewReader("{"client_id": "{yourClientId}",  "connection": "email",   "email": "USER_EMAIL",  "send": "code"}")

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

  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/passwordless/start")
    .header("content-type", "application/json")
    .body("{"client_id": "{yourClientId}",  "connection": "email",   "email": "USER_EMAIL",  "send": "code"}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/passwordless/start',
    headers: {'content-type': 'application/json'},
    data: {
      client_id: '{yourClientId}',
      connection: 'email',
      email: 'USER_EMAIL',
      send: 'code'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"client_id": @"{yourClientId}",
                                @"connection": @"email",
                                @"email": @"USER_EMAIL",
                                @"send": @"code" };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/passwordless/start"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/passwordless/start",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{"client_id": "{yourClientId}",  "connection": "email",   "email": "USER_EMAIL",  "send": "code"}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"client_id": "{yourClientId}",  "connection": "email",   "email": "USER_EMAIL",  "send": "code"}"

  headers = { 'content-type': "application/json" }

  conn.request("POST", "/{yourDomain}/passwordless/start", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/passwordless/start")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request.body = "{"client_id": "{yourClientId}",  "connection": "email",   "email": "USER_EMAIL",  "send": "code"}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/json"]
  let parameters = [
    "client_id": "{yourClientId}",
    "connection": "email",
    "email": "USER_EMAIL",
    "send": "code"
  ] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/passwordless/start")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

**Send a magic link via email**

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/passwordless/start' \
    --header 'content-type: application/json' \
    --data '{ "client_id": "{yourClientId}", "connection": "email", "email": "USER_EMAIL", "send": "link"}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/passwordless/start");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{ "client_id": "{yourClientId}", "connection": "email", "email": "USER_EMAIL", "send": "link"}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/passwordless/start"

  	payload := strings.NewReader("{ "client_id": "{yourClientId}", "connection": "email", "email": "USER_EMAIL", "send": "link"}")

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

  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/passwordless/start")
    .header("content-type", "application/json")
    .body("{ "client_id": "{yourClientId}", "connection": "email", "email": "USER_EMAIL", "send": "link"}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/passwordless/start',
    headers: {'content-type': 'application/json'},
    data: {
      client_id: '{yourClientId}',
      connection: 'email',
      email: 'USER_EMAIL',
      send: 'link'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"client_id": @"{yourClientId}",
                                @"connection": @"email",
                                @"email": @"USER_EMAIL",
                                @"send": @"link" };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/passwordless/start"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/passwordless/start",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "client_id": "{yourClientId}", "connection": "email", "email": "USER_EMAIL", "send": "link"}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "client_id": "{yourClientId}", "connection": "email", "email": "USER_EMAIL", "send": "link"}"

  headers = { 'content-type': "application/json" }

  conn.request("POST", "/{yourDomain}/passwordless/start", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/passwordless/start")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request.body = "{ "client_id": "{yourClientId}", "connection": "email", "email": "USER_EMAIL", "send": "link"}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/json"]
  let parameters = [
    "client_id": "{yourClientId}",
    "connection": "email",
    "email": "USER_EMAIL",
    "send": "link"
  ] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/passwordless/start")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

**Send a one-time-use password via SMS**

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/passwordless/start' \
    --header 'content-type: application/json' \
    --data '{ "client_id": "{yourClientId}",  "connection": "sms",  "phone_number": "USER_PHONE_NUMBER", "send": "code"}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/passwordless/start");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{ "client_id": "{yourClientId}",  "connection": "sms",  "phone_number": "USER_PHONE_NUMBER", "send": "code"}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/passwordless/start"

  	payload := strings.NewReader("{ "client_id": "{yourClientId}",  "connection": "sms",  "phone_number": "USER_PHONE_NUMBER", "send": "code"}")

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

  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/passwordless/start")
    .header("content-type", "application/json")
    .body("{ "client_id": "{yourClientId}",  "connection": "sms",  "phone_number": "USER_PHONE_NUMBER", "send": "code"}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/passwordless/start',
    headers: {'content-type': 'application/json'},
    data: {
      client_id: '{yourClientId}',
      connection: 'sms',
      phone_number: 'USER_PHONE_NUMBER',
      send: 'code'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"client_id": @"{yourClientId}",
                                @"connection": @"sms",
                                @"phone_number": @"USER_PHONE_NUMBER",
                                @"send": @"code" };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/passwordless/start"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/passwordless/start",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "client_id": "{yourClientId}",  "connection": "sms",  "phone_number": "USER_PHONE_NUMBER", "send": "code"}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "client_id": "{yourClientId}",  "connection": "sms",  "phone_number": "USER_PHONE_NUMBER", "send": "code"}"

  headers = { 'content-type': "application/json" }

  conn.request("POST", "/{yourDomain}/passwordless/start", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/passwordless/start")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request.body = "{ "client_id": "{yourClientId}",  "connection": "sms",  "phone_number": "USER_PHONE_NUMBER", "send": "code"}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/json"]
  let parameters = [
    "client_id": "{yourClientId}",
    "connection": "sms",
    "phone_number": "USER_PHONE_NUMBER",
    "send": "code"
  ] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/passwordless/start")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

**Authenticate an SMS user**

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/json' \
    --data '{ "grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp",  "client_id": "{yourClientId}",  "username": "USER_PHONE_NUMBER",  "otp": "code",  "realm": "sms", "audience": "your-api-audience", "scope": "openid profile email"}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{ "grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp",  "client_id": "{yourClientId}",  "username": "USER_PHONE_NUMBER",  "otp": "code",  "realm": "sms", "audience": "your-api-audience", "scope": "openid profile email"}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("{ "grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp",  "client_id": "{yourClientId}",  "username": "USER_PHONE_NUMBER",  "otp": "code",  "realm": "sms", "audience": "your-api-audience", "scope": "openid profile email"}")

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

  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/json'},
    data: {
      grant_type: 'http://auth0.com/oauth/grant-type/passwordless/otp',
      client_id: '{yourClientId}',
      username: 'USER_PHONE_NUMBER',
      otp: 'code',
      realm: 'sms',
      audience: 'your-api-audience',
      scope: 'openid profile email'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"grant_type": @"http://auth0.com/oauth/grant-type/passwordless/otp",
                                @"client_id": @"{yourClientId}",
                                @"username": @"USER_PHONE_NUMBER",
                                @"otp": @"code",
                                @"realm": @"sms",
                                @"audience": @"your-api-audience",
                                @"scope": @"openid profile email" };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp",  "client_id": "{yourClientId}",  "username": "USER_PHONE_NUMBER",  "otp": "code",  "realm": "sms", "audience": "your-api-audience", "scope": "openid profile email"}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp",  "client_id": "{yourClientId}",  "username": "USER_PHONE_NUMBER",  "otp": "code",  "realm": "sms", "audience": "your-api-audience", "scope": "openid profile email"}"

  headers = { 'content-type': "application/json" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request.body = "{ "grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp",  "client_id": "{yourClientId}",  "username": "USER_PHONE_NUMBER",  "otp": "code",  "realm": "sms", "audience": "your-api-audience", "scope": "openid profile email"}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  imimport Foundation

  let headers = ["content-type": "application/json"]
  let parameters = [
    "grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp",
    "client_id": "{yourClientId}",
    "username": "USER_PHONE_NUMBER",
    "otp": "code",
    "realm": "sms",
    "audience": "your-api-audience",
    "scope": "openid profile email"
  ] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

**Authenticate an Email user**

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/json' \
    --data '{"grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp", "client_id": "{yourClientId}", "username": "USER_EMAIL", "otp": "code", "realm": "email", "audience": "your-api-audience", "scope": "openid profile email"}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp", "client_id": "{yourClientId}", "username": "USER_EMAIL", "otp": "code", "realm": "email", "audience": "your-api-audience", "scope": "openid profile email"}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("{"grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp", "client_id": "{yourClientId}", "username": "USER_EMAIL", "otp": "code", "realm": "email", "audience": "your-api-audience", "scope": "openid profile email"}")

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

  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/json")
    .body("{"grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp", "client_id": "{yourClientId}", "username": "USER_EMAIL", "otp": "code", "realm": "email", "audience": "your-api-audience", "scope": "openid profile email"}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/json'},
    data: {
      grant_type: 'http://auth0.com/oauth/grant-type/passwordless/otp',
      client_id: '{yourClientId}',
      username: 'USER_EMAIL',
      otp: 'code',
      realm: 'email',
      audience: 'your-api-audience',
      scope: 'openid profile email'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"grant_type": @"http://auth0.com/oauth/grant-type/passwordless/otp",
                                @"client_id": @"{yourClientId}",
                                @"username": @"USER_EMAIL",
                                @"otp": @"code",
                                @"realm": @"email",
                                @"audience": @"your-api-audience",
                                @"scope": @"openid profile email" };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{"grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp", "client_id": "{yourClientId}", "username": "USER_EMAIL", "otp": "code", "realm": "email", "audience": "your-api-audience", "scope": "openid profile email"}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp", "client_id": "{yourClientId}", "username": "USER_EMAIL", "otp": "code", "realm": "email", "audience": "your-api-audience", "scope": "openid profile email"}"

  headers = { 'content-type': "application/json" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request.body = "{"grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp", "client_id": "{yourClientId}", "username": "USER_EMAIL", "otp": "code", "realm": "email", "audience": "your-api-audience", "scope": "openid profile email"}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/json"]
  let parameters = [
    "grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp",
    "client_id": "{yourClientId}",
    "username": "USER_EMAIL",
    "otp": "code",
    "realm": "email",
    "audience": "your-api-audience",
    "scope": "openid profile email"
  ] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

If you prefer, you can use the Android or iOS SDKs, which wrap this APIs in a platform-friendly way:

* [Lock.Android Passwordless](/docs/libraries/lock-android/lock-android-passwordless)
* [Lock.swift Passwordless](/docs/lock-swift-passwordless)
* [Auth0.Android Passwordless](/docs/libraries/auth0-android/auth0-android-passwordless)
* [Auth0.swift Passwordless](/docs/libraries/auth0-swift/auth0-swift-passwordless)

## Customize MFA with Embedded

<Warning>
  Customizable MFA with the Resource Owner Password Grant, Embedded, or Refresh Token flows is in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/). To learn more, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To participate in the early access, contact [Auth0 Support](https://support.auth0.com/).
</Warning>

Customize <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> with embedded flows. Use the MFA API to allow users to enroll and challenge with factors of their choice that are supported by your application.

When your application requests an <Tooltip href="/docs/glossary?term=access+token+at+the">access token at the</Tooltip> `oauth/token` endpoint, the returned response includes the `mfa_token` to use the MFA API and the `mfa_requirements` parameter with a list of authenticators your application currently supports:

```json lines theme={null}
{
  "error": "mfa_required",
  "error_description": "Multifactor authentication required",
  "mfa_token": "Fe26...Ha",
  "mfa_requirements": {
    "challenge": [
      { "type": "otp" },
      { "type": "push-notification" },
      { "type": "phone" },
      { "type": "recovery-code" }
    ]
  }
}
```

Use the `mfa_token` to call the [`mfa/authenticator`](https://auth0.com/docs/api/authentication/muti-factor-authentication/list-authenticators) endpoint to list all factors the user has enrolled and match the same `type` your application supports. You also need to obtain the matching `authenticator_type` to issue challenges:

```json lines theme={null}
[
  {
    "type": "recovery-code",
    "id": "recovery-code|dev_qpOkGUOxBpw6R16t",
    "authenticator_type": "recovery-code",
    "active": true
  },
  {
    "type": "otp",
    "id": "totp|dev_6NWz8awwC8brh2dN",
    "authenticator_type": "otp",
    "active": true
  }
]
```

Proceed to enforce the MFA challenge by calling the [`request/mfa/challenge`](https://auth0.com/docs/api/authentication/muti-factor-authentication/request-mfa-challenge) endpoint.

Further customize your MFA flow with Auth0 Actions. To learn more, read [Actions Triggers: post-challenge - API Object](/docs/customize/actions/explore-triggers/password-reset-triggers/post-challenge-trigger/post-challenge-api-object).


# Using Passwordless APIs
Source: https://auth0.com/docs/authenticate/passwordless/implement-login/embedded-login/relevant-api-endpoints

Describes how to implement Passwordless authentication using Auth0 APIs.

<Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> APIs can be used in two scenarios:

* When implementing <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> and you want to customize the login page using auth0.js to interact with Auth0.
* When you want to embed the login flow in your application.

To learn more about how to implement Passwordless for Universal Login and Embedded login for different scenarios, read [Passwordless Authentication with Universal Login](/docs/authenticate/passwordless/implement-login/universal-login) or [Passwordless Authentication with Embedded Login](/docs/authenticate/passwordless/implement-login/embedded-login).

## Passwordless endpoints

### POST /passwordless/start

<Callout icon="file-lines">
  You must enable the **Passwordless OTP** grant at [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) in your application's settings under **Advanced Settings** > **Grant Types**.
</Callout>

The [POST /passwordless/start](https://auth0.com/docs/api/authentication#get-code-or-link) endpoint can be called to begin the Passwordless authentication process for both Classic Login and Embedded Login.

Depending on the parameters provided to the endpoint, Auth0 begins the user verification process by sending one of the following:

* A single-use code via email or SMS message
* A single-use link via email

The API call must have the following structure:

<AuthCodeBlock />

If you use a magic link, users will receive a link generated by the Authentication API. Users will select the link and trigger a call to \{`yourAuth0Tenant}.auth0.com/passwordless/verify-redirect`. Auth0 will redirect the user to the application, and the user will be logged in.

If you use a code, your application will need to prompt for that code, and then you should use the `/oauth/token` endpoint, or the `passwordlessLogin` method in the Auth0.js SDK to exchange that code for authentication tokens.

### POST /oauth/token

If you are implementing passwordless for Native Applications or Regular Web Applications, you need to use `/oauth/token` to exchange the OTP code for authentication tokens. You cannot use this endpoint from Single Page Applications.

To achieve this you first need to enable the **Passwordless OTP** grant for your application at [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) in your application's settings under **Advanced Settings** > **Grant Types**.

The user will receive the OTP code and your Native or Web application will prompt the user for it. When the user enters the code, you can complete the authentication flow by calling the `/oauth/token` endpoint with the following parameters:

<AuthCodeBlock />

If all goes well, Auth0 will return a response similar to the following:

```json lines theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token":"eyJz93a...k4laUWw",
"refresh_token":"GEbRxBN...edjnXbL",
"id_token":"eyJ0XAi...4faeEoQ",
"token_type":"Bearer",
"expires_in":86400
}
```

You can then decode the <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip> to get information about the user, or use the <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> to call your API as normal.

## Using Auth0.js

When implementing Passwordless Authentication in Single Page Applications or in a customized Universal Login page, you should [use Auth0.js and the included passwordlessLogin method](/docs/libraries/auth0js). The implementation is complex, so we recommend that you use the library instead of calling the APIs directly.

## Rate limiting in passwordless endpoints

Auth0 rate limits and <Tooltip href="/docs/glossary?term=attack+protection">attack protection</Tooltip> features only consider the IP from the machine that is making the API call. When the API call is made from a backend server, you usually want Auth0 to consider the IP from the end user, not the one from the server.

Auth0 supports specifying an `auth0-forwarded-for` header in API calls, but it is only considered when:

* the API call is made for a confidential application.
* the API call includes the <Tooltip href="/docs/glossary?term=client+secret">client secret</Tooltip>.
* the **Trust <Tooltip href="/docs/glossary?term=Token+Endpoint">Token Endpoint</Tooltip> IP Header** toggle is on.

For a complete explanation, read [Avoid Common Issues with Resource Owner Password Flow and Attack Protection](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow/avoid-common-issues-with-resource-owner-password-flow-and-attack-protection).

## Customize MFA

<Warning>
  Customizable MFA with the Resource Owner Password Grant, Embedded, or Refresh Token flows is in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/). To learn more, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To participate in the early access, contact [Auth0 Support](https://support.auth0.com/).
</Warning>

Customize <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> with the Passwordless API. When your application calls `/oauth/token` endpoint to request an access token, the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip> returns an `mfa_required` error which provides:

* The `mfa_token` you need to call the MFA API for enrollment and challenges.

* The `mfa_requirements` parameter, which provides the factor `type` your application supports for challenges.

```json lines theme={null}
{
  "error": "mfa_required",
  "error_description": "Multifactor authentication required",
  "mfa_token": "Fe26...Ha",
  "mfa_requirements": {
    "challenge": [
      { "type": "otp" },
      { "type": "push-notification" },
      { "type": "phone" },
      { "type": "recovery-code" }
    ]
  }
}
```

Use the `mfa_token` to call the [`mfa/authenticator`](https://auth0.com/docs/api/authentication/muti-factor-authentication/list-authenticators) endpoint to list all factors the user has enrolled and match the same `type` your application supports. You also need to obtain the matching `authenticator_type` to issue challenges:

```json lines theme={null}
[
  {
    "type": "recovery-code",
    "id": "recovery-code|dev_qpOkGUOxBpw6R16t",
    "authenticator_type": "recovery-code",
    "active": true
  },
  {
    "type": "otp",
    "id": "totp|dev_6NWz8awwC8brh2dN",
    "authenticator_type": "otp",
    "active": true
  }
]
```

Enforce the MFA challenge by calling the [`request/mfa/challenge`](https://auth0.com/docs/api/authentication/muti-factor-authentication/request-mfa-challenge) endpoint.

Further customize your MFA flow with Auth0 Actions. To learn more, read [Actions Triggers: post-challenge - API Object](/docs/customize/actions/explore-triggers/password-reset-triggers/post-challenge-trigger/post-challenge-api-object).


# Embedded Passwordless Authentication for SPAs
Source: https://auth0.com/docs/authenticate/passwordless/implement-login/embedded-login/spa

Describes implementing Passwordless authentication with embedded login in single-page applications (SPAs).

<Warning>
  Embedded login for web applications uses [cross-origin authentication](/docs/authenticate/login/cross-origin-authentication) unless you [configure a custom domain](/docs/customize/custom-domains) for your tenant. Cross-origin authentication uses third-party cookies to allow for secure authentication transactions across different origins.
</Warning>

## Using Auth0's SDKs to implement Embedded Login

You can implement <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> Login using Auth0's Lock widget, or if you need complete control of the user experience, you can implement it using Auth0.js:

* [Lock for Web](/docs/libraries/lock)
* [Auth0.js v9 Reference](/docs/libraries/auth0js)

### Configure Cross-Origin Resource Sharing (CORS)

For security purposes, your app's origin URL must be listed as an approved URL. If you have not already added it to the **Allowed Callback URLS** for your application, you will need to add it to the list of **Allowed Origins (CORS)**.

1. Navigate to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), and select the name of your application to see its settings.
2. Locate **Allowed Origins (CORS)**, enter your application's [origin URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Origin), and select **Save Changes**.

## Customize MFA

<Warning>
  Customizable MFA with the Resource Owner Password Grant, Embedded, or Refresh Token flows is in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/). To learn more, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To participate in the early access, contact [Auth0 Support](https://support.auth0.com/).
</Warning>

Customize <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> with embedded flows. Use the MFA API to allow users to enroll and challenge with factors of their choice that are supported by your application.

When using [Lock for Web](/docs/libraries/lock#2-authenticating-and-getting-user-info), the `oauth/token` endpoint returns the `mfa_required` error and includes the `mfa_token` you need to use the MFA API and `mfa_requirements` parameter with a list of authenticators your application currently supports:

```json lines theme={null}
{
  "error": "mfa_required",
  "error_description": "Multifactor authentication required",
  "mfa_token": "Fe26...Ha",
  "mfa_requirements": {
    "challenge": [
      { "type": "otp" },
      { "type": "push-notification" },
      { "type": "phone" },
      { "type": "recovery-code" }
      { "type": "email"} //can only work with challenge
    ]
  }
}
```

Use the `mfa_token` to call the [`mfa/authenticator`](https://auth0.com/docs/api/authentication/muti-factor-authentication/list-authenticators) endpoint to list all factors the user has enrolled and match the same `type` your application supports. You also need to obtain the matching `authenticator_type` to issue challenges:

```json lines theme={null}
[
  {
    "type": "recovery-code",
    "id": "recovery-code|dev_qpOkGUOxBpw6R16t",
    "authenticator_type": "recovery-code",
    "active": true
  },
  {
    "type": "otp",
    "id": "totp|dev_6NWz8awwC8brh2dN",
    "authenticator_type": "otp",
    "active": true
  }
]
```

Proceed to enforce the MFA challenge by calling the [`request/mfa/challenge`](https://auth0.com/docs/api/authentication/muti-factor-authentication/request-mfa-challenge) endpoint.

Further customize your MFA flow with Auth0 Actions. To learn more, read [Actions Triggers: post-challenge - API Object](/docs/customize/actions/explore-triggers/password-reset-triggers/post-challenge-trigger/post-challenge-api-object).


# Embedded Passwordless Login in Regular Web Applications
Source: https://auth0.com/docs/authenticate/passwordless/implement-login/embedded-login/webapps

Describes implementing Passwordless authentication with embedded login in regular applications.

To use the Embedded <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> APIs in Regular Web Applications, make sure you enable the **Passwordless OTP** grant at [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) in your application's settings under **Advanced Settings** > **Grant Types**.

Passwordless authentication for Regular Web Applications consists of two steps:

1. Capture the user identifier in your application (the user's email or phone number) and invoke the `/passwordless/start` endpoint to initiate the passwordless flow. The user will get an email, an SMS with a one-time-use code, or a magic link.
2. If you did not send a magic link, prompt the user for the one-time-use code, and call the `/oauth/token` endpoint to get authentication tokens.

Note that when using magic links, you don't need to call `/oauth/token`. The user will click the magic link and be redirected to the application's callback URL.

Below, we list a few code snippets that can be used to call these API endpoints for different scenarios.

**Send a one-time-use code via email**

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/passwordless/start' \
    --header 'content-type: application/json' \
    --data '{"client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "connection": "email", "email": "{userEmail}","send": "code"}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/passwordless/start");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "connection": "email", "email": "{userEmail}","send": "code"}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/passwordless/start"

  	payload := strings.NewReader("{"client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "connection": "email", "email": "{userEmail}","send": "code"}")

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

  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/passwordless/start")
    .header("content-type", "application/json")
    .body("{"client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "connection": "email", "email": "{userEmail}","send": "code"}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/passwordless/start',
    headers: {'content-type': 'application/json'},
    data: {
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      connection: 'email',
      email: '{userEmail}',
      send: 'code'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"client_id": @"{yourClientId}",
                                @"client_secret": @"{yourClientSecret}",
                                @"connection": @"email",
                                @"email": @"{userEmail}",
                                @"send": @"code" };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/passwordless/start"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/passwordless/start",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{"client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "connection": "email", "email": "{userEmail}","send": "code"}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "connection": "email", "email": "{userEmail}","send": "code"}"

  headers = { 'content-type': "application/json" }

  conn.request("POST", "/{yourDomain}/passwordless/start", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/passwordless/start")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request.body = "{"client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "connection": "email", "email": "{userEmail}","send": "code"}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/json"]
  let parameters = [
    "client_id": "{yourClientId}",
    "client_secret": "{yourClientSecret}",
    "connection": "email",
    "email": "{userEmail}",
    "send": "code"
  ] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/passwordless/start")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

**Send a magic link via email**

You need to specify `send: link`.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/passwordless/start' \
    --header 'content-type: application/json' \
    --data '{"client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "connection": "email", "email": "{userEmail}","send": "link"}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/passwordless/start");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "connection": "email", "email": "{userEmail}","send": "link"}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/passwordless/start"

  	payload := strings.NewReader("{"client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "connection": "email", "email": "{userEmail}","send": "link"}")

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

  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/passwordless/start")
    .header("content-type", "application/json")
    .body("{"client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "connection": "email", "email": "{userEmail}","send": "link"}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/passwordless/start',
    headers: {'content-type': 'application/json'},
    data: {
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      connection: 'email',
      email: '{userEmail}',
      send: 'link'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"client_id": @"{yourClientId}",
                                @"client_secret": @"{yourClientSecret}",
                                @"connection": @"email",
                                @"email": @"{userEmail}",
                                @"send": @"link" };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/passwordless/start"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/passwordless/start",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{"client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "connection": "email", "email": "{userEmail}","send": "link"}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "connection": "email", "email": "{userEmail}","send": "link"}"

  headers = { 'content-type': "application/json" }

  conn.request("POST", "/{yourDomain}/passwordless/start", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/passwordless/start")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request.body = "{"client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "connection": "email", "email": "{userEmail}","send": "link"}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/json"]
  let parameters = [
    "client_id": "{yourClientId}",
    "client_secret": "{yourClientSecret}",
    "connection": "email",
    "email": "{userEmail}",
    "send": "link"
  ] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/passwordless/start")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

**Send a one-time-use password via SMS**

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/passwordless/start' \
    --header 'content-type: application/json' \
    --data '{"client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "connection": "sms", "phone_number": "{userPhoneNumber}","send": "code"}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/passwordless/start");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "connection": "sms", "phone_number": "{userPhoneNumber}","send": "code"}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/passwordless/start"

  	payload := strings.NewReader("{"client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "connection": "sms", "phone_number": "{userPhoneNumber}","send": "code"}")

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

  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/passwordless/start")
    .header("content-type", "application/json")
    .body("{"client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "connection": "sms", "phone_number": "{userPhoneNumber}","send": "code"}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/passwordless/start',
    headers: {'content-type': 'application/json'},
    data: {
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      connection: 'sms',
      phone_number: '{userPhoneNumber}',
      send: 'code'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"client_id": @"{yourClientId}",
                                @"client_secret": @"{yourClientSecret}",
                                @"connection": @"sms",
                                @"phone_number": @"{userPhoneNumber}",
                                @"send": @"code" };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/passwordless/start"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/passwordless/start",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{"client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "connection": "sms", "phone_number": "{userPhoneNumber}","send": "code"}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "connection": "sms", "phone_number": "{userPhoneNumber}","send": "code"}"

  headers = { 'content-type': "application/json" }

  conn.request("POST", "/{yourDomain}/passwordless/start", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/passwordless/start")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request.body = "{"client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "connection": "sms", "phone_number": "{userPhoneNumber}","send": "code"}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/json"]
  let parameters = [
    "client_id": "{yourClientId}",
    "client_secret": "{yourClientSecret}",
    "connection": "sms",
    "phone_number": "{userPhoneNumber}",
    "send": "code"
  ] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/passwordless/start")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

**Authenticate an SMS user**

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/json' \
    --data '{"grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp", "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "username": "USER_PHONE_NUMBER", "otp": "code", "realm": "sms", "audience": "your-api-audience","scope": "openid profile email"}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp", "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "username": "USER_PHONE_NUMBER", "otp": "code", "realm": "sms", "audience": "your-api-audience","scope": "openid profile email"}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("{"grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp", "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "username": "USER_PHONE_NUMBER", "otp": "code", "realm": "sms", "audience": "your-api-audience","scope": "openid profile email"}")

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

  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/json")
    .body("{"grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp", "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "username": "USER_PHONE_NUMBER", "otp": "code", "realm": "sms", "audience": "your-api-audience","scope": "openid profile email"}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/json'},
    data: {
      grant_type: 'http://auth0.com/oauth/grant-type/passwordless/otp',
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      username: 'USER_PHONE_NUMBER',
      otp: 'code',
      realm: 'sms',
      audience: 'your-api-audience',
      scope: 'openid profile email'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"grant_type": @"http://auth0.com/oauth/grant-type/passwordless/otp",
                                @"client_id": @"{yourClientId}",
                                @"client_secret": @"{yourClientSecret}",
                                @"username": @"USER_PHONE_NUMBER",
                                @"otp": @"code",
                                @"realm": @"sms",
                                @"audience": @"your-api-audience",
                                @"scope": @"openid profile email" };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{"grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp", "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "username": "USER_PHONE_NUMBER", "otp": "code", "realm": "sms", "audience": "your-api-audience","scope": "openid profile email"}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp", "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "username": "USER_PHONE_NUMBER", "otp": "code", "realm": "sms", "audience": "your-api-audience","scope": "openid profile email"}"

  headers = { 'content-type': "application/json" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request.body = "{"grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp", "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "username": "USER_PHONE_NUMBER", "otp": "code", "realm": "sms", "audience": "your-api-audience","scope": "openid profile email"}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/json"]
  let parameters = [
    "grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp",
    "client_id": "{yourClientId}",
    "client_secret": "{yourClientSecret}",
    "username": "USER_PHONE_NUMBER",
    "otp": "code",
    "realm": "sms",
    "audience": "your-api-audience",
    "scope": "openid profile email"
  ] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

**Authenticate an Email user**

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/json' \
    --data '{"grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp", "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "username": "{userPhoneNumber}", "otp": "code", "realm": "email", "audience": "your-api-audience", "scope": "openid profile email"}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp", "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "username": "{userPhoneNumber}", "otp": "code", "realm": "email", "audience": "your-api-audience", "scope": "openid profile email"}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("{"grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp", "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "username": "{userPhoneNumber}", "otp": "code", "realm": "email", "audience": "your-api-audience", "scope": "openid profile email"}")

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

  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/json")
    .body("{"grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp", "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "username": "{userPhoneNumber}", "otp": "code", "realm": "email", "audience": "your-api-audience", "scope": "openid profile email"}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/json'},
    data: {
      grant_type: 'http://auth0.com/oauth/grant-type/passwordless/otp',
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      username: '{userPhoneNumber}',
      otp: 'code',
      realm: 'email',
      audience: 'your-api-audience',
      scope: 'openid profile email'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"grant_type": @"http://auth0.com/oauth/grant-type/passwordless/otp",
                                @"client_id": @"{yourClientId}",
                                @"client_secret": @"{yourClientSecret}",
                                @"username": @"{userPhoneNumber}",
                                @"otp": @"code",
                                @"realm": @"email",
                                @"audience": @"your-api-audience",
                                @"scope": @"openid profile email" };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{"grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp", "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "username": "{userPhoneNumber}", "otp": "code", "realm": "email", "audience": "your-api-audience", "scope": "openid profile email"}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp", "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "username": "{userPhoneNumber}", "otp": "code", "realm": "email", "audience": "your-api-audience", "scope": "openid profile email"}"

  headers = { 'content-type': "application/json" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request.body = "{"grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp", "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "username": "{userPhoneNumber}", "otp": "code", "realm": "email", "audience": "your-api-audience", "scope": "openid profile email"}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/json"]
  let parameters = [
    "grant_type": "http://auth0.com/oauth/grant-type/passwordless/otp",
    "client_id": "{yourClientId}",
    "client_secret": "{yourClientSecret}",
    "username": "{userPhoneNumber}",
    "otp": "code",
    "realm": "email",
    "audience": "your-api-audience",
    "scope": "openid profile email"
  ] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

**Authenticate a user through a magic link**

When you send a magic link, you don't need to call an API to authenticate the user. Users will click the link and be redirected to the callback URL.

## Setting the auth0-forwarded-for header for rate-limit purposes

The `/passwordless/start` endpoint has a [rate limit](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy) of 50 requests per hour per IP. If you call the API from the server-side, your backend's IP may easily hit these rate limits. To learn how to address this issue, read the Rate Limiting in Passwordless Endpoints section of [Using Passwordless APIs](/docs/authenticate/passwordless/implement-login/embedded-login/relevant-api-endpoints).

## Customize MFA

<Warning>
  Customizable MFA with the Resource Owner Password Grant, Embedded, or Refresh Token flows is in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/). To learn more, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To participate in the early access, contact [Auth0 Support](https://support.auth0.com/).
</Warning>

Customize <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> with embedded flows. Use the MFA API to allow users to enroll and challenge with factors of their choice that are supported by your application.

When using [Lock for Web](/docs/libraries/lock#2-authenticating-and-getting-user-info), the `oauth/token` endpoint returns the `mfa_required` error and includes the `mfa_token` you need to use the MFA API and `mfa_requirements` parameter with a list of authenticators your application currently supports:

```json lines theme={null}
{
  "error": "mfa_required",
  "error_description": "Multifactor authentication required",
  "mfa_token": "Fe26...Ha",
  "mfa_requirements": {
    "challenge": [
      { "type": "otp" },
      { "type": "push-notification" },
      { "type": "phone" },
      { "type": "recovery-code" }
      { "type": "email"} //can only work with challenge
    ]
  }
}
```

Use the `mfa_token` to call the [`mfa/authenticator`](https://auth0.com/docs/api/authentication/muti-factor-authentication/list-authenticators) endpoint to list all factors the user has enrolled and match the same `type` your application supports. You also need to obtain the matching `authenticator_type` to issue challenges:

```json lines theme={null}
[
  {
    "type": "recovery-code",
    "id": "recovery-code|dev_qpOkGUOxBpw6R16t",
    "authenticator_type": "recovery-code",
    "active": true
  },
  {
    "type": "otp",
    "id": "totp|dev_6NWz8awwC8brh2dN",
    "authenticator_type": "otp",
    "active": true
  }
]
```

Proceed to enforce the MFA challenge by calling the [`request/mfa/challenge`](https://auth0.com/docs/api/authentication/muti-factor-authentication/request-mfa-challenge) endpoint.

Further customize your MFA flow with Auth0 Actions. To learn more, read [Actions Triggers: post-challenge - API Object](/docs/customize/actions/explore-triggers/password-reset-triggers/post-challenge-trigger/post-challenge-api-object).


# Passwordless Authentication with Universal Login
Source: https://auth0.com/docs/authenticate/passwordless/implement-login/universal-login

Describes how to implement Passwordless authentication with Universal Login.

[Universal Login](/docs/authenticate/login/auth0-universal-login) is Auth0's implementation of the login flow. Each time a user needs to prove their identity, your applications redirect to <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> and Auth0 will do what is needed to guarantee the user's identity. It's the preferred way to implement <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> Authentication.

To implement Passwordless Authentication in Universal Login you need to customize the login page's HTML.

1. Go to [Dashboard > Branding > Universal Login](https://manage.auth0.com/#/login_settings) and click **Advanced Options**.

2. Click the **Login** tab, then enable the **Customize Login Page** toggle.

<Frame>
  <img alt="Custom Login" />
</Frame>

3. From the Default Template drop-down menu, choose the **Custom Login Form** template. The HTML template will update with code using CSS and the Auth0.js SDK.

4. Use HTML and CSS to customize the template to your specifications, and click **Save Changes**. To learn more about how to use the Auth0.js SDK with the **Custom Login Form** template, see [Auth0.js SDK](/docs/libraries/auth0js).

5. Select the **Preview** tab to review your changes. Make sure to select the correct application for which you want to preview the login page.

To integrate Universal Login in your application, please refer to our [Quickstarts](/docs/quickstarts), where you'll find complete examples for all application types and popular platforms.

## Learn more

* [Auth0 Universal Login](/docs/authenticate/login/auth0-universal-login)
* [Customize](/docs/customize)


# Passwordless Connection Limitations
Source: https://auth0.com/docs/authenticate/passwordless/passwordless-connection-limitations

Describes some limitations to using passwordless connections.

The type of authentication you want to use depends on which version of <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> you configured with your application. If you are using the Universal Login experience, you can set up [passwordless authentication using WebAuthN with Device Biometrics](/docs/authenticate/login/auth0-universal-login/passwordless-login/webauthn-device-biometrics) or use <Tooltip href="/docs/glossary?term=passwordless">passwordless</Tooltip> connections as described below.

You can set up email or SMS passwordless authentication using the following methods:

1. Universal Login + passwordless connection parameters
2. Classic Login + Lock
3. Classic Login + custom UI + Auth0.js

To learn more about these implementations, read [Configure Email or SMS for Passwordless Authentication](/docs/authenticate/login/auth0-universal-login/passwordless-login/email-or-sms).

### Errors

If you are using an embedded login, we recommend using <Tooltip href="/docs/glossary?term=custom+domains">custom domains</Tooltip>. To learn more, read [Custom Domains](/docs/customize/custom-domains).

## Considerations

* You cannot create passwordless users from the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. Create them directly from the [Management API](https://auth0.com/docs/api/management/v2#!/Users/post_users).
* <Tooltip href="/docs/glossary?term=Refresh+tokens">Refresh tokens</Tooltip> cannot be retrieved when using a passwordless magic link via email, only an OTP.

## Learn more

* [Passwordless Authentication](/docs/authenticate/passwordless)


# Passwordless with Universal Login
Source: https://auth0.com/docs/authenticate/passwordless/passwordless-with-universal-login

The document announces support for Universal Login and Passwordless connections.

<Card title="Before you start">
  * Configure a Passwordless connection. To learn how, read the following articles:

    * [Passwordless Authentication with Email](/docs/authenticate/passwordless/authentication-methods/email-otp)
    * [Passwordless Authentication with Magic Links](/docs/authenticate/passwordless/authentication-methods/email-magic-link)
    * [Passwordless Authentication with SMS](/docs/authenticate/passwordless/authentication-methods/sms-otp)
</Card>

The <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> Experience supports [Passwordless connections](/docs/authenticate/passwordless), which allow users to provide a phone number or email address, and then receive a one-time password (OTP) to complete authentication.

## Enable Passwordless for Universal Login

To configure Universal Login to support <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> connections, you'll need to set the Authentication Profile to use a supported login flow, and update your application to specify the connection during authentication.

### Enable Identifier First

In the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, go to [Authentication > Authentication Profile.](https://manage.auth0.com/?/authentication-profiles)

Select either **Identifier First** or **Identifier First + Biometrics**.

### Update your application

Depending on the type of connections you have enabled for your application, you may need to update your application to specify a Passwordless connection during login:

<table>
  <thead>
    <tr>
      <th><strong>Database connection</strong></th>
      <th><strong>Passwordless connection</strong></th>
      <th><strong>Need to specify?</strong></th>
      <th><strong>User experience</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Yes</td>
      <td>SMS and/or Email</td>
      <td>Yes</td>
      <td>Specified Passwordless connection is presented during login.</td>
    </tr>

    <tr>
      <td>No</td>
      <td>SMS and Email</td>
      <td>No</td>
      <td>Passwordless connection that was created first is presented.</td>
    </tr>

    <tr>
      <td>No</td>
      <td>SMS or Email</td>
      <td>No</td>
      <td>Passwordless connection is presented (along with any enabled Social connections) during login.</td>
    </tr>
  </tbody>
</table>

To specify a Passwordless connection during login, you must pass the `connection` parameter and its value (either `sms` or `email`) to the [Auth0 Authentication API Login endpoint](https://auth0.com/docs/api/authentication#login):

`https://mytenant.us.auth0.com/authorize?client_id={id}&``connection={sms|email}``&scope=…&response_type=code&response_mode=query&state=…&redirect_uri=http%3A%2F%2Flocalhost%3A3000&code_challenge=…`

If you are using one of our SDKs, you can specify a Passwordless connection during initialization. For example:

```js lines theme={null}
auth0 = await createAuth0Client({
     domain: config.domain,
     client_id: config.clientId,
     connection: "email"
  });

auth0 = await createAuth0Client({
     domain: config.domain,
     client_id: config.clientId,
     connection: "sms"
  });
```

<Callout icon="file-lines">
  If you are using Passwordless with Universal Login and [Single Sign-On](/docs/authenticate/single-sign-on), connection parameters `sms` and `email` do not utilize the existing Auth0 session, and the user will be prompted to log in.
</Callout>

### Test the connection

When the user is prompted to enter their OTP, they'll see one of the following screens:

### Signup

<Frame>
  <img alt="" />
</Frame>

### Login

<Frame>
  <img alt="" />
</Frame>


# Sample Use Cases - Rules with Passwordless Authentication
Source: https://auth0.com/docs/authenticate/passwordless/sample-use-cases-rules

Explore examples using rules with passwordless connections.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

With [rules](/docs/customize/rules), you can handle more complicated cases than is possible with [passwordless connections](/docs/authenticate/passwordless) alone. For instance, you can add extra precautions to further ensure possession of an email address or device.

## Require Multi-factor Authentication for users who are outside the corporate network

Let's say you want to require [multi-factor authentication (MFA)](/docs/secure/multi-factor-authentication) for any users who are accessing the application using a <Tooltip href="/docs/glossary?term=passwordless">passwordless</Tooltip> connection from outside your corporate network.

Using a rule, you can check whether a user is authenticating using a passwordless method (`sms`, `email`) and if their session IP falls outside of the designated corporate network, prompt them for a second authentication factor.

<Callout icon="file-lines">
  You could also trigger this rule based on other criteria, such as whether the current IP matches the user's IP allowlist or whether geolocating the user reveals they are in a different country from the one listed in their user profile.
</Callout>

To do this, you would [create the following rule](/docs/customize/rules/create-rules):

```javascript lines theme={null}
function(user, context, callback) {
  const ipaddr = require('ipaddr.js');
  const corp_network = "192.168.1.134/26";
  const current_ip = ipaddr.parse(context.request.ip);
  // is auth method passwordless and IP outside corp network?
  const passwordlessOutside = context.authentication.methods.find(
    (method) => (
      ((method.name === 'sms') || (method.name === 'email')) && 
      (!current_ip.match(ipaddr.parseCIDR(corp_network)))
    )
  );

  // if yes, then require MFA
  if (passwordlessOutside) {
    context.multifactor = {
      provider: 'any',
      allowRememberBrowser: false
    };
  }
  callback(null, user, context);
}
```


# Connection Settings Best Practices
Source: https://auth0.com/docs/authenticate/connection-settings-best-practices

Learn about recommended identity provider connection settings in Auth0.

Here are some best practices for configuring connections. Before you set up connections, take a moment to review what connections are and [learn the basics of authentication](/docs/authenticate) for your application type.

## Use your credentials for social connections

Auth0 provides default credentials for social connections to help you get started. You should replace these temporary credentials with your own to avoid restrictions.

## Review requested data

You should review the data you are requesting from each social connection. Users must grant consent for the requested data. Requesting a lot of unnecessary data may result in users declining the authorization request out of privacy concerns.

## Set password policy for database connections

Configure the password policy for your Auth0 database connections so created users have strong passwords. You can configure the password policy in the database connection settings on the dashboard or with the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

The password policy applies to password resets performed with the <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> Page as well as the Auth0 Management API.

## Disable user signup if it's not appropriate for each database connection

In your database connection settings, specify if self-service user signups should be enabled. If you enabled this during development, review if you should disable it on production tenants.

Only enable this setting for production tenants if you allow end-users to sign up in a self-service manner. If self-service signup is not allowed, disable the feature. You can then add users to the database connection with the Auth0 Management API.

When using the Organizations feature, you can enable self-service signup for a given database connection in the context of a specific organization. When enabled, users can access a Sign Up link on the login prompt and gain membership to a specific organization upon creating their account. For more information, review [Enable Organization Connections](/docs/manage-users/organizations/configure-organizations/enable-connections).

## Review applications enabled for each connection

For each connection, review the list of allowed applications. Make sure there are no unintended authentication paths into an application. By default, new applications may have all of your tenant's connections enabled, which may not be appropriate.

## Use RSA-SHA256 for SAML connections

Configure any <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> connections to sign requests and use RSA-SHA256 as the signature algorithm. This ensures the remote SAML <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> can validate whether the authentication requests came from a legitimate application or not.


# Enterprise Connections
Source: https://auth0.com/docs/authenticate/enterprise-connections

Learn how to create, manage, and monitor usage of Enterprise connections to authenticate users with external identity providers.

Auth0 provides Enterprise connections to authenticate users in an external, federated <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> (IdP) such as Azure AD, Google Workspace, PingFederate, and more.

<Card title="Availability varies by Auth0 plan">
  Your Auth0 plan or custom agreement affects the availability of this feature. To learn more, read [Auth0's Pricing Page](https://auth0.com/pricing).
</Card>

## Create an Enterprise connection

Auth0 supports many identity providers out of the box. To learn more, review [Enterprise Identity Providers](/docs/authenticate/identity-providers/enterprise-identity-providers).

#### OpenID Connect (OIDC) protocol

Enterprise connections using <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect or Okta Workforce as the identity provider can support the following:

* Proof Key for Code Exchange (PKCE)

  * For more information on PKCE, review [Protecting Apps with PKCE](https://www.oauth.com/oauth2-servers/pkce/).
* Attribute claims and <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> mapping
* UserInfo integration

You can currently implement these features for [OpenID Connect](/docs/authenticate/identity-providers/enterprise-identity-providers/oidc) or [Okta Workforce](/docs/authenticate/identity-providers/enterprise-identity-providers/okta) connections. To learn more, review [Configure PKCE and Claim Mapping for OIDC Connections](/docs/authenticate/identity-providers/enterprise-identity-providers/configure-pkce-claim-mapping-for-oidc).

## View Enterprise connections

<Tabs>
  <Tab title="Dashboard">
    Navigate to [**Auth0 Dashboard > Authentication > Enterprise**](https://manage.auth0.com/#/connections/enterprise) to see all available Enterprise connection types. Select a connection type (for example, SAML) to see if there are any configured connections of that type.

    You can also select a configured connection and check the **Applications** tab to see if it is enabled for any applications.
  </Tab>

  <Tab title="Management API">
    Call the Auth0 Management API [Get all Connections endpoint](https://auth0.com/docs/api/management/v2#!/Connections/get_connections) to get information about your connections. Include the `strategy` parameter to filter by connection type.

    The Enterprise connection type `strategy` values are:

    * `ad` (Active Directory/LDAP)
    * `adfs` (ADFS)
    * `auth0-adldap`
    * `google-apps` (Google Workspace)
    * `ip`
    * `office365`
    * `oidc` (OpenID Connect)
    * `pingfederate` (PingFederate)
    * `samlp` (SAML)
    * `sharepoint`
    * `waad` (Microsoft Azure AD)
  </Tab>
</Tabs>

## What is an active Enterprise connection?

An Enterprise connection is considered active if (during the current month) it has both:

* Been enabled for an application.
* Had user activity (for example, login, sign-up, or token exchange).

If an Enterprise connection was never enabled for any application, or was enabled but did not have any user activity during the current month, it is not considered active.

<Callout icon="file-lines">
  The Okta Workforce Enterprise connection is not counted toward your active Enterprise connections limit.
</Callout>

## Learn more

* [Enterprise Identity Providers](/docs/authenticate/identity-providers/enterprise-identity-providers)
* [Enable Enterprise Connections](/docs/authenticate/identity-providers/enterprise-identity-providers/enable-enterprise-connections)
* [View Connections](/docs/authenticate/identity-providers/view-connections)
* [Test Enterprise Connections](/docs/authenticate/identity-providers/enterprise-identity-providers/test-enterprise-connections)
* [Entity Limit Policy](/docs/troubleshoot/customer-support/operational-policies/entity-limit-policy)


# Connection Profile
Source: https://auth0.com/docs/authenticate/enterprise-connections/connection-profile



Auth0 provides Enterprise connections to authenticate users in an external, federated identity provider (IdP) such as Okta, Microsoft Entra ID, Google Workspace, and others. A configured connection will include protocol-specific settings for integrating single sign-in (SSO), user provisioning, and logout integrations with the external IDP, as well as private settings that govern how the connection interacts with Auth0’s Universal Login and Organizations features.
The Connection Profile (CP) enables Auth0 developers to specify how the private settings of an Auth0 connection should be configured when created by third parties

## How it works

* **Profile Definition**<p />
  An administrator creates a Connection Profile that defines the property values that should be written to the connection whenever they are created using one of Auth0 delegated administration features.

* **Flexible Scope**<p />
  Profiles are linked to Self-Service SSO and Okta Express Configuration flows today but are designed for broader reuse, covering provisioning, onboarding, entitlement management, and future Auth0 capabilities.

## Connection Profile properties

A Connection Profile is a `JSON` object that supports these configurable properties, which are applied to all newly created connections.

| **Property**                              | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connection_name_prefix_template`         | Represents the prefix that must be used for naming connections. Maps to the `name` parameter on a connection. This value supports variable substitution for the organization ID and the organization name. The OIN workflow must substitute these values to generate the final prefix. Variables are enclosed in braces (). <p /> Supported variables: <p /> <ul><li><code>org\_id</code>: The Organization ID</li><li><code>org\_name</code>: The <a href="https://auth0.com/docs/manage-users/organizations/configure-organizations/create-organizations#auth0-dashboard">Organization name</a></li></ul> <p /> Example: `con-{org_id}-`                                                                                            |
| `enabled_features`                        | This list specifies the features which will be supported by the configured connection. Features not on the list are not allowed.<p /> Supported values: <ul><li><code>scim</code>: When present, SCIM may be configured on the connection.</li><li><code>universal\_logout</code>: When present, the Universal Logout feature may be used with this connection.</li></ul>                                                                                                                                                                                                                                                                                                                                                             |
| `organization.assign_membership_on_login` | Specifies whether users should automatically be assigned membership in the organization on login. This maps to the `assign_membership_on_login` property of the `enabled_connections` sub-resource of the organization. <Note> For Express Configuration integrations with Okta, `optional` is treated as `required`</Note> <p /><table><thead><tr><th><strong>Connection Profile Value</strong></th><th><strong>Enable Connections<code>assign\_membership\_on\_login</code>Value</strong></th></tr></thead><tbody><tr><td><code>none</code></td><td><code>false</code></td></tr><tr><td><code>optional</code></td><td><code>false</code></td></tr><tr><td><code>required</code></td><td><code>true</code></td></tr></tbody></table> |
| `organization`                            | An object containing settings that are applied to the organization under which the connection is created.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `organization.show_as_button`             | Specifies whether the connection should be shown as a button on the login screen once an organization has been chosen. This maps to the `show_as_button` value on the enabled connection. <table><thead><tr><th><strong>Connection Profile Value</strong></th><th><strong>Connection <code>show\_as\_button</code> Value</strong> </th></tr></thead><tbody><tr><td><code>none</code></td><td><code>false</code></td></tr><tr><td><code>optional</code></td><td><code>true</code></td></tr><tr><td><code>required</code></td><td><code>true</code></td></tr></tbody></table>                                                                                                                                                           |

## Example Connection Profile

```json theme={null}
{
  "organization": {
    "show_as_button": "none",
    "assign_membership_on_login": "none"
  },
  "connection_name_prefix_template": "ec-{org_id}-",
  "enabled_features": [
    "scim",
    "universal_logout"
  ]
}
```

## Create and manage Connection Profiles

A Connection Profile is automatically generated when using the [Express Configuration](/docs/authenticate/identity-providers/enterprise-identity-providers/okta/express-configuration) feature with Okta. In addition, create and manage Connection Profiles using the Auth0 Management API.

### Configure with Management API

To use the Management API, you need to get a [Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens). To manage Connection Profiles, the following Management API endpoints are available:

* `POST` `/api/v2/connection-profiles`
* `GET` `/api/v2/connection-profiles`
* `PATCH` `/api/v2/connection-profiles/{id}`
* `GET` `/api/v2/connection-profiles/{id}`
* `GET` `/api/v2/connection-profiles/templates`

## Learn More

* [Express Configuration](/docs/authenticate/identity-providers/enterprise-identity-providers/okta/express-configuration)
* [Manage Users Using Management API](/docs/manage-users/user-accounts/manage-users-using-the-management-api)


# Private Key JWT Client Authentication for Okta and OIDC Connections
Source: https://auth0.com/docs/authenticate/enterprise-connections/private-key-jwt-client-auth

Learn how to implement Private Key JWT Client Authentication for your enterprise connections.

<Callout icon="file-lines">
  Private Key JWT Client Authentication for OpenID Connect (OIDC) and Okta Workforce connections is currently available in [Early Access](/docs/troubleshoot/product-lifecycle/product-release-stages). By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/).
</Callout>

Private Key <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> Client Authentication is an alternative method of client authentication for <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) and Okta Workforce enterprise connections. While client authentication is most commonly handled by passing a shared <Tooltip href="/docs/glossary?term=client+secret">client secret</Tooltip>, Private Key JWT Client Authentication instead passes a signed JWT for improved application security.

By using this feature, you can avoid some common security shortcomings often seen with standard client secret authentication, such as:

* An increased risk of interception and re-use, as client secrets must be transmitted between parties for every request.
* Limited mechanisms available to enforce expiration and prevent re-use by malicious actors.
* An increased risk of leaks or exposure due to both parties holding the client secret.

You can set up Private Key JWT Client Authentication for your OIDC and Okta Workforce enterprise connections through either the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## How it works

The OIDC Connection flow uses authenticated endpoints such as `/oauth/token` or `/oauth/par` to verify a client’s identity against the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip> or OpenID provider. With Private Key JWT Client Authentication, a signed client assertion JWT is passed to the OpenID provider instead of a client secret.

The client assertion JWT contains the following claims:

* An `aud` (<Tooltip href="/docs/glossary?term=audience">audience</Tooltip>) identifying the OpenID provider’s <Tooltip href="/docs/glossary?term=token+endpoint">token endpoint</Tooltip>.
* A `jti` (JWT ID) to enable one-time use or replay protection.
* An `exp` (expiration time) that limits the token’s validity window.
* A `sub` and `iss` identifying the <Tooltip href="/docs/glossary?term=client+ID">client ID</Tooltip>.

Private Key JWT Client Authentication offers a more secure method of authentication by eliminating the use of shared client secrets. Instead, the JWT is signed using the client’s private key, and the OpenID provider only has access to the public key.

### Private Key JWT Client Authentication Flow

After a user completes authentication with an upstream <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> (IdP), the user is redirected to Auth0 with an authorization code that is exchanged for tokens at the OpenID provider’s token endpoint. When Private Key JWT is enabled for a connection, the call to the OpenID provider’s token endpoint uses a client assertion instead of a client secret for a more secure authentication.

The following steps demonstrate a typical Private Key JWT Client Authentication flow.

<Frame>
  <img alt="A diagram mapping the Private Key JWT Client Authentication flow. " />
</Frame>

<Callout icon="file-lines">
  To complete this flow, you must first configure a new or existing OIDC or Okta Workforce connection with `token_endpoint_auth_method=private_key_jwt` through either your Auth0 Dashboard or the Management API. To learn more, review the [Configure Private Key JWT Client Authentication](#configure-private-key-jwt-client-authentication) section.
</Callout>

1. After configuring your connection, Auth0 automatically generates and stores two public and private key pairs.

   * One key pair is the active `current` set, while the other set is labeled as `next` to support [key rotation](#rotate-signing-keys).
2. Depending on your IDP, you next either:

   * Download the `current` public key and upload the file to the Authorization Server, or:
   * Copy and paste the [`jwks_uri`](#retrieve-signing-keys) to the Authorization Server.
3. A user performs an action that requires authentication, such as logging in to your application.
4. Auth0 sends a request to the Authorization Server to initiate authentication.
5. The Authorization Server displays authentication and consent screens to the user.
6. The user authenticates and provides consent to the Authorization Server.
7. The Authorization Server sends an authorization code to Auth0.
8. Auth0 generates a client assertion JWT and signs it using the `current` private key.
9. Auth0 passes the client assertion JWT to the Authorization Server.
10. The Authorization Server looks up the client based on the provided `client_id`.
11. The Authorization Server fetches public keys from Auth0 if a `jwks_uri` was provided; otherwise, the server identifies the public key registered in step 2.
12. If the `jwks_uri` was requested, Auth0 returns the public keys as JWKS.
13. The Authorization Server validates the JWT by verifying the signature with the `current` public key, identified by `kid` in the header of the `client_assertion` JWT.
14. The Authorization Server generates an access token.
15. The Authorization Server passes the access token to Auth0.
16. Using the access token, Auth0 requests a resource from the Resource Server.
17. The Resource Server provides the resource to complete the flow.

## Configure Private Key JWT Client Authentication

You can configure OIDC and Okta Workforce enterprise connections to use Private Key JWT Client Authentication through either the Auth0 Dashboard or Management API. Steps for each method are provided below.

<Callout icon="file-lines">
  * Private and public signing key pairs are automatically generated by Auth0 per connection.
  * You can currently only use the RS256 algorithm for signing client assertion JWTs.
  * Signed JWTs expire automatically after 60 seconds.
</Callout>

#### Auth0 Dashboard

You can use the Auth0 Dashboard to configure Private Key JWT Client Authentication for both new and existing OIDC and Okta Workforce connections.

<Callout icon="file-lines">
  If your custom OIDC connection uses an IdP that does not advertise support for back-channel communication or `private_key_jwt` as a client authentication method in its metadata, you will not be able to set up Private Key JWT Client Authentication through the Auth0 Dashboard.
</Callout>

<Tabs>
  <Tab title="New Connection">
    1. On your Auth0 Dashboard, navigate to [Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise).
    2. Next to **OpenID Connect** or **Okta Workforce**, select **Create**.
    3. In the **General** section, provide details for your new connection, including its name and discovery URL.
    4. Configure the following fields to enable Private Key JWT:

       * Set **Communication Channel** to **Back Channel**.
       * Set **Authentication Method** to **Private Key JWT**.
    5. Select **Create** to save your new connection.
  </Tab>

  <Tab title="Existing Connection">
    1. On your Auth0 Dashboard, navigate to [Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise).
    2. Next to **OpenID Connect** or **Okta Workforce**, select **Browse**.
    3. Choose the appropriate connection. Then, access its **Credentials** tab.
    4. Under **Authentication Settings**, configure the following:

       * Set **Communication Channel** to **Back Channel**.
       * Set **Authentication Method** to **Private Key JWT**.
    5. Select **Save** at the bottom of the screen.
    6. On the confirmation popup, select **Change** to implement your modifications.
  </Tab>
</Tabs>

#### Management API

You can use the Management API to configure Private Key JWT Client Authentication for both new and existing OIDC connections.

<Tabs>
  <Tab title="New Connection">
    To create a new OIDC connection that uses Private Key JWT Client Authentication, call the [Create a Connection](https://auth0.com/docs/api/management/v2/connections/post-connections) endpoint with the following `connection.options` properties set appropriately:

    <table>
      <thead>
        <tr>
          <th>Property</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>type</code></td>
          <td>Set this property to <code>back\_channel</code>.</td>
        </tr>

        <tr>
          <td><code>token\_endpoint\_auth\_method</code></td>
          <td>Set this property to <code>private\_key\_jwt</code>. <br /><br /> <strong>Notes:</strong><ul><li> By default, this property is set to <code>client\_secret\_post</code>. </li><li>Errors may occur if this property is set to a value other than <code>private\_key\_jwt</code> or <code>client\_secret\_post</code>.</li></ul></td>
        </tr>

        <tr>
          <td><code>token\_endpoint\_auth\_signing\_alg</code></td>
          <td>Set this property to <code>RS256</code>. <br /><br /> <strong>Notes:</strong> <ul><li>This feature does not currently support additional algorithms.</li><li>Omitting this property will default its value to <code>RS256</code>.</li></ul></td>
        </tr>
      </tbody>
    </table>

    **Example POST call**

    ```js lines theme={null}
    POST /api2/connections

    {
      strategy: 'oidc',
      options: {
        type: "back_channel",
        token_endpoint_auth_method: "private_key_jwt",
        token_endpoint_auth_signing_alg: "RS256"
      },
      …
    }
    ```
  </Tab>

  <Tab title="Existing Connection">
    To modify an existing OIDC connection to use Private Key JWT Client Authentication, call the [Update a Connection](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id) endpoint with the following `connection.options` properties set appropriately:

    <table>
      <thead>
        <tr>
          <th>Property</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>type</code></td>
          <td>Set this property to <code>back\_channel</code>.</td>
        </tr>

        <tr>
          <td><code>token\_endpoint\_auth\_method</code></td>
          <td>Set this property to <code>private\_key\_jwt</code>.<br /><br /> <b>Notes:</b> <ul><li> Errors may occur if this property is set to a value other than <code>private\_key\_jwt</code> or <code>client\_secret\_post</code>. </li></ul></td>
        </tr>
      </tbody>
    </table>

    **Example PATCH call**

    ```js lines theme={null}
    PATCH /api2/connections/{id}

    {
      strategy: 'oidc',
      options: {
        type: "back_channel",
        token_endpoint_auth_method: "private_key_jwt"
      },
      …
    }
    ```
  </Tab>
</Tabs>

## Retrieve Signing Keys

After your connection has been configured to use Private Key JWT Client Authentication, you can retrieve its public keys through either the Auth0 Dashboard, the Management API, or a public JWKS URI.

<AccordionGroup>
  <Accordion title="Auth0 Dashboard">
    To retrieve signing keys through the Auth0 Dashboard:

    1. Navigate to [Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise).
    2. Next to **OpenID Connect** or **Okta Workforce**, select **Browse**.
    3. Choose the appropriate connection. Then, access its **Credentials** tab.
    4. Locate the **Credentials** section and select the **Download** icon next to the appropriate signing key.
  </Accordion>

  <Accordion title="Management API">
    To view public keys through the Management API, call the Retrieve Connection Signing Keys endpoint using the ID of your connection.

    <Warning>
      Use of this endpoint requires the `read:connections_keys` scope.
    </Warning>

    **Example GET call**

    ```js lines theme={null}
    GET /api2/connections/{id}/keys
    ```

    **Example response**

    ```js lines expandable theme={null}
    {
        cert: "-----BEGIN CERTIFICATE-----
    MIIDDTCCAfWgAwIBAgIJP...Ek=
    -----END CERTIFICATE-----",
        pkcs7: "-----BEGIN PKCS7-----
    MIIDPAYJKoZIhvcNAQcCo...AA==
    -----END PKCS7-----
    ",
        kid: "E4CXqUP6r92yo0f_sdkdC",
        next: true,
        fingerprint: "7F:33:86:D9:4A:98:B2:DC:B0:41:74:54:DA:31:E7:74:42:32:96:8C",
        thumbprint: "7F3386D94A98B2DCB0417454DA31E7744232968C"
      }, 
      {
        cert: "-----BEGIN CERTIFICATE-----
    MIIDDTCCAfWgAwIBAgI...Ss=
    -----END CERTIFICATE-----",
        pkcs7: "-----BEGIN PKCS7-----
    MIIDPAYJKoZIhvcNAQ...AA==
    -----END PKCS7-----
    ",
        kid: "_4WuXpXlwwmSE65saKWDM",
        current: true,
        current_since: "2025-01-24T08:50:06.662Z",
        fingerprint: "33:7D:6F:35:46:31:AD:6E:69:43:01:A2:77:DF:8E:73:64:F6:E8:5B",
        thumbprint: "337D6F354631AD6E694301A277DF8E7364F6E85B"
      }, 
      {
        cert: "-----BEGIN CERTIFICATE-----
    MIIDDTCCAfWgAwIBA...6Q=
    -----END CERTIFICATE-----",
        pkcs7: "-----BEGIN PKCS7-----
    MIIDPAYJKoZIhvcN...AA==
    -----END PKCS7-----
    ",
        kid: "roUD9STeDy9qBTx5XjaTz",
        previous: true,
        current_since: "2025-01-24T08:48:51.523Z",
        current_until: "2025-01-24T08:50:06.663Z",
        fingerprint: "44:D3:DD:3B:63:99:59:9A:39:D9:F4:F0:4F:1B:AC:BB:18:72:40:5C",
        thumbprint: "44D3DD3B6399599A39D9F4F04F1BACBB1872405C"
      }
    ```
  </Accordion>

  <Accordion title="Public JWKS URI">
    Some identity providers allow public keys for private\_key\_jwt to be provided in the form of a public JWKS (JSON Web Key Set) URI.

    If public keys have been generated for a connection, you can retrieve them by adding the following URI to your IdP configuration:

    ```http wrap lines theme={null}
    https://{auth0 domain}/oauth/connection/{connection name}/.well-known/jwks.json
    ```

    <Warning>
      JWKS URIs count towards global rate limits. You can use caching of public keys to avoid reaching these limits. As best practice, Auth0 recommends a cache interval of at least 5-10 minutes to avoid calling the JWKS URI endpoint with each login attempt.
    </Warning>
  </Accordion>
</AccordionGroup>

## Rotate Signing Keys

Private Key JWT Client Authentication supports signing key rotation for increased security compared to the static, long-lived nature of shared client secrets. Rotating signing keys enhances security by limiting the exposure time of any single key, reducing the window of opportunity for an attacker to compromise it. It also allows for rapid response in the wake of a security incident.

To avoid disruption, Auth0 recommends rotating signing keys after one year. You can use either the Auth0 Dashboard or the Management API to rotate signing keys:

<AccordionGroup>
  <Accordion title="Auth0 Dashboard">
    To rotate your signing keys through the Auth0 Dashboard:

    1. Navigate to [Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise).
    2. Next to **OpenID Connect** or **Okta Workforce**, select **Browse**.
    3. Choose the appropriate connection. Then, access its **Credentials** tab.
    4. In the **Credentials** section, select **Rotate Keys**.
    5. On the popup, select **Save** to confirm the rotation.

    After rotation, any in-flight JWTs signed with the previous key immediately become inactive and may fail verification with your IdP.
  </Accordion>

  <Accordion title="Management API">
    To view public keys through the Management API, call the Rotate Connection Signing Keys endpoint using the ID of your connection.

    <Warning>
      Use of this endpoint requires both `create:connections_keys` and `update:connections_keys` scopes.
    </Warning>

    ```js lines theme={null}
    POST /v2/connections/{id}/keys/rotate
    ```

    After rotation, any in-flight JWTs signed with the previous key immediately become inactive and may fail verification with your IdP.
  </Accordion>
</AccordionGroup>

<Card title="Understanding key rotation">
  On your OIDC or Okta Workforce connection, your signing keys are assigned one of the following statuses:

  * **Current**: The signing key currently in use for the application.
  * **Next**: The next signing key to use for the application after the current key is revoked.
  * **Previous**: An expired or otherwise revoked signing key that is no longer in use.

  When Private Key JWT Client Authentication is first enabled for a connection, only a `current` and `next` keypair is generated. A key is only marked as `previous` after rotation occurs.

  When rotating signing keys, the following changes occur:

  1. The `current` key is removed and revoked, and any JWTs signed with this key will fail verification with the IdP if the IdP was configured with the `jwks_uri`.
  2. The `current` key is assigned the `previous` status.
  3. The `next` key becomes the active key and is given the `current` status. Going forward, client assertion JWTs will be signed with this key.
  4. A new signing key is automatically generated to replace the rotated key. The new signing key has the `next` status.
</Card>

## Learn more

* [Connect Your Auth0 Application with Okta Workforce Enterprise Connection](/docs/authenticate/identity-providers/enterprise-identity-providers/okta)
* [Connect to OpenID Connect Identity Provider](/docs/authenticate/identity-providers/enterprise-identity-providers/oidc)


# Self-Service Single Sign-On
Source: https://auth0.com/docs/authenticate/enterprise-connections/self-service-SSO

Learn how to use Self-Service Single Sign-On to delegate SSO setup to your B2B customers.

<Warning>
  Provisioning and Domain Verification for Self-Service SSO is in Early Access. By using this feature, you agree to the applicable Free Trial terms in [Okta’s Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0’s product release cycle, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

Self-Service <Tooltip href="/docs/glossary?term=Single+Sign-On">Single Sign-On</Tooltip> (SSO) provides business-to-business (B2B) customers with the tools needed to delegate SSO setup to their enterprise customers. By delegating this task, you can streamline your onboarding process and grant customers more autonomy over their sign-on experience. You can also reduce the time and costs associated with managing SSO across your customer base.

Self-Service SSO requires minimal configuration in your Auth0 tenant and provides your customers with a setup assistant that guides them through the enablement process. After a customer completes their setup, the SSO integration is automatically added to your tenant as an [Enterprise connection](/docs/authenticate/enterprise-connections).

<Callout icon="file-lines">
  Users with the following Dashboard roles can engage with this feature:

  * **Admin** and **Editor - Connections** users can create and manage self-service profiles.
  * **Viewer - Config** users can view self-service profiles only.
</Callout>

To learn more about Auth0’s subscription, read [Manage Subscriptions](/docs/troubleshoot/customer-support/manage-subscriptions). To upgrade your subscriptions, contact your Technical Account Manager or [Auth0 Sales](https://auth0.com/get-started?place=header\&type=button\&text=talk%20to%20sales).

**Supported Providers**

Self-Service SSO currently supports the following <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip>:

* Okta Workforce Identity
* Auth0
* Entra ID
* Google Workspace
* Keycloak
* Microsoft Active Directory Federation Services (ADFS)
* PingFederate
* Generic OIDC
* Generic <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip>

Self-Service Provisioning currently supports the following identity providers:

* Okta Workforce Identity
* Entra ID
* Generic OIDC
* Generic SAML

## How it works

Self-Service SSO uses the following components to delegate setup to your customers:

* **Self-service profile**: Defines key elements of customer SSO implementations, such as the identity providers they can use for SSO and which user attributes they must capture, such as email. You can create up to 20 profiles in your tenant for different customers or segments.
* **Self-service access ticket**: Grants your customers admin access to the self-service assistant and sets specific details for the resulting Enterprise connection. Those customer admins can either create new or modify existing connections.
* **SSO setup assistant**: Guides your customer admins through the SSO setup process. To learn more about this experience, review the Self-service assistant experience.

### Self-Service SSO workflow

The steps below provide the general workflow for using Self-Service SSO. These tasks can be completed through either the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> or the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

1. You (the Auth0 customer) create a self-service profile in your tenant.
2. You then create a self-service access ticket associated with that self-service profile. When generating the ticket, you can decide whether your customer admin will create a new connection or modify an existing connection through the self-service assistant.
3. You retrieve the ticket URL from the asset created in Step 2 and send the link to your customer admin.
4. Your customer admin launches the self-service assistant via the ticket URL and follows the steps provided to configure their connection and optionally complete domain verification. If the ticket is for a single Organization with Discovery enabled, the assistant automatically detects domains already verified for that Organization. This allows the admin to associate existing domains with the new connection instantly, bypassing re-verification.
5. A new or updated Enterprise connection pointing to the customer’s application becomes available in your Auth0 tenant.

<Frame>
  <img alt="Workflow diagram for the Self-Service SSO feature." />
</Frame>

## Self-service assistant experience

The self-service assistant is a multi-step experience that guides customer admins through configuring SSO and optionally verifying their domain. This experience includes both interactive elements as well as instructions for making the appropriate changes in their selected IdP system.

While the exact requirements for configuring SSO vary by IdP, the general workflow for the self-service assistant includes the following:

1. **Select Identity Provider**: The customer admin selects which IdP to configure for SSO. The list of options the customer admin can choose from is determined by the associated self-service profile.
2. **Create Application**: The customer admin follows the written instructions to create an application in their selected IdP system.
3. **Configure Connection**: The customer admin completes a brief form to create or modify a connection in Auth0. This form collects information such as the customer’s domain, client ID, and client secret.
4. **Claims Mapping**: The customer admin reviews the required and optional user attributes they must capture through their SSO connection. Then, they map these user attributes, or claims, in their IdP system.
5. **Assign Access**: The customer admin follows the written instructions for their IdP system to grant users or user groups access to your application.
6. **Test SSO**: The customer admin uses the button provided to test their SSO connection in a new tab. Unless domain verification is enabled, the customer admin can complete the setup process after this step to enable their connection.
7. **(Optional) Provisioning**: The customer administrator configures user provisioning for their connection by following the provided instructions:
   * Create the application in their IdP.
   * Generate a SCIM bearer token in the assistant and copy the SCIM bearer token and SCIM endpoint URL into their IdP’s configuration.
   * Review the required and optional attributes defined in the User Attribute Profile (UAP). Map these attributes to the corresponding SCIM fields in their IdP system.
8. **(Optional) Domain verification and association**: Customer admins manage the domains used for authentication and routing. Domain verification requires customers to prove ownership of their domains. Domain association allows the reuse of existing trusted identities.

When a ticket is configured for **one** enabled Organization, verified domains can be automatically synchronized for [Organization Domain Discovery](/docs/manage-users/organizations/login-flows-for-organizations#organization-domain-discovery-optional). Once an IT Admin verifies or associates a domain, end-users can log in using their email address (Home Realm Discovery) and bypass the need for a specific Organization ID or Magic Link.

Depending on how you (the Auth0 customer) configure the access ticket, the experience for customer admins varies. Review the table for more information.

| Configuration                                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Verified Domain Association                                    | Customer admins select and associate existing domains with the new connection without verifying the DNS TXT record if the ticket is scoped to one Organization and the Organization:  <ul><li>Must have the **Allow Use of Domains for Organzation Discovery** option enabled.</li><li>Must have **Domain Verification** set to `Optional` or `Required`.</li></ul> <p /> The assistant automatically detects previously verified domains for that specific Organization.                              |
| Domain Verification set to `Required`                          | Customer admins must successfully verify a new domain via DNS or associate an existing verified domain before they can enable the connection.                                                                                                                                                                                                                                                                                                                                                          |
| Domain Verification set to `Optional`                          | Customer admin can choose to enter a new domain for verification, associate an existing one, or skip the step. In all cases, the admin can enable the connection regardless of the verification status.                                                                                                                                                                                                                                                                                                |
| Domain Verification set to `Off`                               | Custom admins do nothing. This step does not appear to customer admins, and the flow ends after Test SSO.                                                                                                                                                                                                                                                                                                                                                                                              |
| **Allow Use of Domains for Organization Discovery** is enabled | This option is available when generating a ticket for **one** Enabled Organization. When selected: <ul><li>**New Domains**: Any newly verified domain automatically populate both the Organization’s domain list and the Enterprise Connection's `matching_domains`.</li> <li>**Existing Domains**: Any pre-verified domains (limited to 5) or associated domains sync to both the connection and the Organization record upon completion and enables immediate email-based login for users.</li></ul> |

To learn more, review [Manage Self-Service SSO](/docs/authenticate/enterprise-connections/self-service-SSO/manage-self-service-sso).

### Example self-service assistant flow

The images below demonstrate an example self-service assistant experience. In this example, a customer admin configures SSO with Okta Workforce as their IdP.

**1. Select Single Sign-On**

<Frame>
  <img alt="Enterprise-Connection>Self-Service-SSO" />
</Frame>

**2. Select Identity Provider**

<Frame>
  <img alt="The first step of the self-service assistant that customer admins use to configure SSO. " />
</Frame>

**3. Create Application (truncated)**

<Frame>
  <img alt="The second step of the self-service assistant that customer admins use to configure SSO. " />
</Frame>

**4. Configure Connection**

<Frame>
  <img alt="The third step of the self-service assistant that customer admins use to configure SSO. " />
</Frame>

**5. Claims Mapping**

<Frame>
  <img alt="The fourth step of the self-service assistant that customer admins use to configure SSO. " />
</Frame>

**6. Assign Access**

<Frame>
  <img alt="The fifth step of the self-service assistant that customer admins use to configure SSO. " />
</Frame>

**7. Test SSO**

<Frame>
  <img alt="The sixth step of the self-service assistant that customer admins use to configure SSO. " />
</Frame>

**8. Provisioning - Create Application**

<Frame>
  <img alt="Create an application to provision users." />
</Frame>

**9. Provisioning - Configure SCIM**

<Frame>
  <img alt="Confgure SCIM to provision users to your application." />
</Frame>

**10. Provisioning - SCIM Mapping**

<Frame>
  <img alt="Map user attributes to guarantee attributes are passed from IdP to SP." />
</Frame>

**11. Domain Verification**

<Frame>
  <img alt="The last step of the self-service assistant that customer admins use to configure SSO. " />
</Frame>

## Using Self-Service SSO

To learn how you can use Self-Service SSO for your customers, review [Manage Self-Service SSO](/docs/authenticate/enterprise-connections/self-service-SSO/manage-self-service-sso). This resource provides technical information for creating self-service profiles and managing access tickets, as well as useful reference information such as rate limits.


# Manage Self-Service SSO
Source: https://auth0.com/docs/authenticate/enterprise-connections/self-service-SSO/manage-self-service-sso

Use Self-Service SSO to delegate SSO setup to your B2B customers.

<Warning>
  Provisioning and Domain Verification for Self-Service SSO is in Early Access. By using this feature, you agree to the applicable Free Trial terms in [Okta’s Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0’s product release cycle, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

Self-Service <Tooltip href="/docs/glossary?term=Single+Sign-On">Single Sign-On</Tooltip> (SSO) provides business-to-business (B2B) customers with the tools needed to delegate SSO setup to their enterprise customers.

Self-Service SSO requires minimal configuration in your Auth0 tenant and provides your customers with a self-service assistant that guides them through the enablement process. After a customer completes their setup, the SSO integration is automatically added to your tenant as an [Enterprise connection](/docs/authenticate/enterprise-connections).

<Callout icon="file-lines">
  Users with the following Dashboard roles can engage with this feature:

  * **Admin** and **Editor - Connections** users can create and manage self-service profiles.
  * **Viewer - Config** users can view self-service profiles only.
</Callout>

To facilitate Self-Service SSO, you will configure the following components using either the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> or the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>:

* **Self-service profile**: Defines key elements of customer SSO implementations, including the <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> (IdPs) they can use and which user attributes they must capture, such as email. You can create up to 20 profiles in your tenant for different customers or segments.
* **Self-service access ticket**: Grants customer admins access to the [**self-service assistant**](/docs/authenticate/enterprise-connections/self-service-SSO#self-service-assistant-experience) and sets specific details for their resulting Enterprise connection. Access tickets allow customer admins to either create new or modify existing connections.

The sections below provide expanded steps for configuring self-service profiles and generating self-service access tickets to share with customer admins.

## Create self-service profiles

You can create self-service profiles using the Auth0 Dashboard or the Management API.

Self-service profiles are used to determine key elements of customer implementations, including:

* Which identity providers customer admins can use for SSO.
* Which user attributes they must capture through SSO, such as email or family name.
* Branding options that customize the look and feel of the self-service assistant.

You can create up to 20 profiles as needed to accommodate different customers or segments.

<Tabs>
  <Tab title="Auth0 Dashboard">
    To create a self-service profile on the Auth0 Dashboard: 

    1. Navigate to [Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise) and open the **Self-Service SSO** section. Then, select **Create Profile**.
    2. In the space provided, enter a name and optional description for the profile. Then, select **Create**.<br />
          A. **Optional** Attach a User Attribute Profile.
          <Note>
          If you create and attach, or enable an existing User Attribute Profile, you will not have the option to add attributes via the User Profile tab.
          </Note>
             1. Select an existing UAP or create a new one. For a new UAP:<br />
                a. Add a name.<br />
                b. Review mappings to ensure the profile attributes are mapping to your preferred Auth0 attributes.
                   <Frame><img alt="UAP mapping Authentication > Enterprise > Self-Service" /></Frame>
    3. On the **Settings** tab, complete the sections below. Then, select **Save**.
       * **Identity Providers (IdP)**: Enable one or more identity providers. In the self-service assistant, customer admins can select their preferred option from the list of enabled providers.
       * **Branding**: Provide a logo and primary color for the self-service assistant.
       * **Custom Introduction**: Modify or replace the default message as needed. This introduction text displays to customer admins on the landing page of the self-service assistant. Your messaging can include basic formatting options, such as bolding or hyperlinks, and is limited to 2000 characters.
    4. On the **User Profile** tab, add up to 20 user attributes that your customers should capture through SSO, such as email or family name. You can set each attribute as `required` or `optional`.

       * During the self-service assistant flow, customer admins will be prompted to map these defined user attributes to their identity provider to ensure the necessary values are passed to Auth0.
  </Tab>

  <Tab title="Management API">
    To create a self-service profile, first call the Self-Service Profiles endpoint to create the profile. Then, use a PUT call to optionally modify its introduction text.

    #### Create a self-service profile:

    1. Make a POST call to the [Self-Service Profiles](https://auth0.com/docs/api/management/v2/self-service-profiles/post-self-service-profiles) endpoint.
    2. Specify the following parameters in the request body, as needed:

    <table>
      <thead>
        <tr>
          <th><strong>Parameter</strong></th>
          <th><strong>Required?</strong></th>
          <th><strong>Description</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>name</code></td>
          <td>Yes</td>
          <td>String. Maximum length is 100.<br /><br />A user-friendly name for the self-service profile.</td>
        </tr>

        <tr>
          <td><code>description</code></td>
          <td>No</td>
          <td>String. Maximum length is 140.<br /><br />A description of the self-service profile.</td>
        </tr>

        <tr>
          <td><code>allowed\_strategies</code></td>
          <td>No</td>
          <td>Array.<br /><br />One or more identity providers that customer admins can use to implement SSO. If no parameters are selected, all are passed by default. <br /><br />Options include: <br /><br /><ul><li><code>okta</code> for Okta Workforce Identity</li><li><code>waad</code>for Entra ID</li><li><code>google-apps</code> for Google Workspace</li><li><code>keycloak-samlp</code> for Keycloak</li><li><code>adfs</code> for Microsoft Active Directory Federation Services</li><li><code>pingfederate</code> for PingFederate</li><li><code>oidc</code> for generic OIDC</li><li><code>samlp</code> for generic SAML</li></ul></td>
        </tr>

        <tr>
          <td><code>branding</code></td>
          <td>No</td>
          <td>Object. <br /><br />Used to customize the styling of the self-service assistant presented to customer admins.</td>
        </tr>

        <tr>
          <td><code>branding.logo\_url</code></td>
          <td>No</td>
          <td>String. Maximum length is 1024.<br /><br />An HTTPS URL that points to a logo image. If provided, this logo displays to the top right of the self-service assistant.</td>
        </tr>

        <tr>
          <td><code>branding.colors</code></td>
          <td>No</td>
          <td>Object.<br /><br />Sets a primary color for certain elements of the self-service assistant, such as interactive buttons.</td>
        </tr>

        <tr>
          <td><code>branding.colors.primary</code></td>
          <td>Yes, when defining branding.colors.</td>
          <td>String.<br /><br />Specifies the hex value of the primary color used for the self-service assistant.</td>
        </tr>

        <tr>
          <td><code>user\_attributes</code></td>
          <td>No</td>
          <td>Object. Maximum length is 20.<br /><br />Stores mapping information presented to customer admins during the self-service assistant flow. Customer admins are instructed to map these attributes to their identity provider to ensure the specified attributes are passed to Auth0.</td>
        </tr>

        <tr>
          <td><code>user\_attributes\[].name</code></td>
          <td>Yes, when defining user\_attributes.</td>
          <td>String. Maximum length is 255.<br /><br />Name of the user attribute in Auth0.</td>
        </tr>

        <tr>
          <td><code>user\_attributes\[].description</code></td>
          <td>Yes, when defining user attributes.</td>
          <td>String. Maximum length is 255.<br /><br />Human-readable description of the user attribute.</td>
        </tr>

        <tr>
          <td><code>user\_attributes\[].is\_optional</code></td>
          <td>Yes, when defining user attributes.</td>
          <td>Boolean.<br /><br />Indicates whether an attribute is optional or required by the customer in order for the application to function.<br /><br /><ul><li>To set an attribute as required, use <code>true</code>.</li><li>For optional attributes, use <code>false</code>.</li></ul></td>
        </tr>

        <tr>
          <td><code>user\_attribute\_profile\_id</code></td>

          <td>
            No.
          </td>

          <td>
            ID of the [User Attribute Profile](/docs/authenticate/enterprise-connections/user-attribute-profile) to associate with self-service accounts.
          </td>
        </tr>
      </tbody>
    </table>

    **Example Request Body**

    ```json lines theme={null}
    {
      "name": "Example Profile",
      "description": "An example profile for all customers",
      "allowed_strategies": ["okta","adfs","google-apps"],
      "user_attributes": [
        {
          "name": "email",
          "description": "User's email",
          "is_optional": false,
        }
      ],
      "branding": {
         "logo_url": "https://example.com/logo.png",
         "colors": {
           "primary": "#334455"
         }
      }
    }
    ```

    #### Customize your introduction text

    When a customer admin accesses the self-service assistant, they first land on an introduction page that welcomes them to the experience. By default, the following message is provided:

    "You are a few simple steps away from setting up SSO. This setup process involves making some changes to your identity provider. Before you begin, open your identity provider in a separate browser tab or window."

    You can modify this text by making a PUT call to the [Custom Text for Self-Service Profiles](https://auth0.com/docs/api/management/v2/self-service-profiles/put-self-service-profile-custom-text) endpoint.

    <Warning>
      Be aware that this call **overwrites** any messaging currently set for the self-service profile. Ensure your call includes the complete text you wish to display to your customer admins.
    </Warning>

    1. Call `PUT /api/v2/self-service-profiles/{id}/custom-text/{language}/{page}`, where

       * `id` is the profile ID of the self-service profile
       * `language` is set to `en`
       * `page` is set to `get-started`
    2. In the request body, specify the following:

    <table>
      <thead>
        <tr>
          <th><strong>Property</strong></th>
          <th><strong>Description</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>introduction</code></td>
          <td>String. Maximum length is 2000.<br /><br />Full introduction text to display on the landing page of the self-service assistant. Text can include basic formatting options, such as bolding or hyperlinks.<br /><br />Custom text provided through this parameter completely overwrites any previous messaging. For best results, ensure you provide the full message you wish to display to customer admins.<br /><br />Sending an empty body <code>\{}</code> resets any customized messaging to the default text.</td>
        </tr>
      </tbody>
    </table>

    3. In response, the created entity is returned.

    **Example Call**

    ```js lines theme={null}
    PUT /api/v2/self-service-profiles/ssp_1234567890/custom-text/en/get-started

    {
      introduction: "Welcome! With <b>only a few steps</b>, you'll be able to setup your new connection. For assistance, contact <a href="https://www.examplesupportsite.com"> our support team </a>." 
    }
    ```

    **Example Response**

    ```js lines theme={null}
    {
      introduction: "Welcome! With <b>only a few steps</b>, you'll be able to setup your new connection. For assistance, contact <a href="https://www.examplesupportsite.com"> our support team </a>." 
    }
    ```
  </Tab>
</Tabs>

## Manage self-service access tickets

After creating at least one self-service profile, you can generate self-service access tickets using either the Auth0 Dashboard or the Management API.

Self-service access tickets serve two primary purposes:

* Granting customer admins access to the self-service assistant where they can configure a new SSO connection or modify an existing connection.
* Predefining key details and behaviors of new SSO connections your customer admins will configure, such as which applications or organizations will be enabled for the new connection.

When generating access tickets, you can also enable certain features such as <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> IdP-initated SSO, configure Identity Provider Domains (which drive Home Realm Discovery), and domain verification.

#### SAML IdP-initiated SSO

SAML IdP-initiated SSO is a style of implementation that allows identity providers to initiate SSO and redirect users to the service provider for authentication.

When enabling this option for Self-Service SSO, you must provide your default application and response protocol. You can also provide an optional query string to further customize the connection's behavior.

To learn more about these options, review [Configure SAML Identity Provider-Initiated Single Sign-On](/docs/authenticate/protocols/saml/saml-sso-integrations/identity-provider-initiated-single-sign-on).

#### Email domain verification and pre-verified domains

Self-Service SSO supports two ways to associate email domains with an Enterprise connection. Both methods populate the same field: `options.domain_aliases `, which drives Home Realm Discovery (HRD) and conditionally Organization Domains for discovery:

1. Pre-verified domains (tenant-managed): Tenant admin adds known domains directly to the connection.
2. Email Domain Verification (self-managed): Your customer's admin verifies the domain during setup in the self-service assistant.

These mechanisms to associate email domains apply to email domains used for HRD and SSO routing. They are not related to Custom Domain verification at the tenant level.

For a domain to populate with both Organization Domains for Discovery and HRD, the ticket must:

* Include only one `enabled_organization`
* Have either pre-verified domains or Email Verification Required as `Required` or `Optional`
* Enable the checkbox for **Allow the Use of Domains for Organization Discovery**

If more than 5 pre-verified domains exist in the ticket, only the first 5 will be associated with the Organization. All domains will be associated with the connection.

##### Pre-verified domain

Use pre-verified domain to associate email domains to an Enterprise connection at the tenant-level. Added domains are treated as trusted and are written directly to `options.domain_aliases`.

You can provide domains when [generating self-service access tickets](#generate-access-tickets-for-new-connections) through either the Auth0 Dashboard or the Management API.

* **Auth0 Dashboard**: On the **Generate Ticket** page, specify your list of domains with the **Pre-verified Domains** field.
* **Management API**: Set `connection_config.options.domain_aliases` to the list of domains. By default, `use_for_organization_discovery` is set to `true`. Optionally, select the **Allow the Use of Domains for Organization Discovery**.

Domains added by tenant admins are treated as **trusted** and **do not** require the customer admin to complete verification. If you want IT admins to verify a domain instead of the domain treated as **trusted**, set `domain_aliases_config.domain_verification` to `required` or `optional` to prompt verification from the self-service assistant. The **Allow Use of Domains for Organization Discovery** option requires exactly one `enabled_organization` in the ticket.

##### Email domain verification

In contrast to pre-verified domains, email domain verification confirms an IT admin owns the domain they provide during self-service setup. When verification is complete, the verified domain is added to the same `options.domain_aliases` array on the connection.

You can enable verification for IT admins when you generate self-service access tickets:

* **Auth0 Dashboard**: On the **Generate Ticket** page, use the **Domain Verification Requirement** field. Optionally, select the **Allow the Use of Domains for Organization Discovery**.
* **Management API**: Use `domain_aliases_config.domain_verification` and optionally `use_for_organization_discovery ` with one of the following options:
  * `none` (default) : The self-service assistant does not prompt a customer admin to verify their domain.
  * `required`: The self-service assistant prompts the customer admin to verify their domains.
  * `optional`: The self-service assistant prompts the customer admin to verify their domain. The customer admin can choose to either enter their domain for verification or skip the step.

The **Allow Use of Domains for Organization Discovery** options requires exactly **one** Organization in the Enabled Organizations field and Domain Verification set to `Optional` or `Required` or Pre-Verified Domain(s). Verification could take up to 48 hours in some cases, and you may need to issue a follow-up access ticket to let the customer admin return and enable the connection. Access tickets expire five hours after first being opened. Review [Generate access tickets for existing connections](https://auth0.com/docs/authenticate/enterprise-connections/self-service-SSO/manage-self-service-sso#generate-access-tickets-for-existing-connections).

### Generate access tickets for new connections

You can generate access tickets for new connections through either the Auth0 Dashboard or the Management API.

<Warning>
  By default, access ticket URLs remain valid for five days after generation. After accessing the ticket URL, the customer admin has five hours to complete their setup. An access ticket URL can be accessed a maximum of 10 times; once this limit is reached, a new access ticket must be requested.

  If needed, you can revoke an access ticket prior to its expiration to immediately cease access to the self-service assistant.
</Warning>

<Tabs>
  <Tab title="Auth0 Dashboard">
    To generate an access ticket for a new connection through the Auth0 Dashboard:

    1. Navigate to [Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise) and access the **Self-Service SSO** section. Then, select the self-service profile with which you want to create an access ticket.

    2. Select **Generate Ticket** to open the ticket form. Under **Select ticket type**, choose **Create a new connection**.

    3. Under **Ticket configuration**, provide a required name for the connection your customer admin will configure.

    4. In the **Settings** section, configure additional options as needed for the new connection:

       * **Display Name**: A user-friendly name for the connection that displays on Universal Login prompts.
       * **Enabled Clients**: A comma-separated list of client IDs to associate with the connection.
       * **Enabled Organizations**: A comma-separated list of organization IDs to associate with the connection.
       * **Display connection a as button**: Displays the connection as an authentication option on the login screen.
       * **Display connection as a button for organizations**: Displays the connection as an authentication option on the login screen for the specified organizations.
       * **Assign membership on login for organizations**: Automatically grant organization membership to users who authenticate with the connection.
       * **Enable as a domain level connection**: Allow 3rd-party applications to use the connection; requires [Dynamic Client Registration](/docs/get-started/applications/dynamic-client-registration).
       * **Accept SAML IdP-initiated SSO**: Enables [SAML Identity Provider-initiated SSO](/docs/authenticate/protocols/saml/saml-sso-integrations/identity-provider-initiated-single-sign-on).

    5. Under **Domain-Based Discovery**, optionally provide a comma-separated list of IdP domains to compare to users’ email domains. These domains are stored in `options.domain_aliases` and drive HRD. Domains added here are treated as trusted and do not require customer admin verification. For more information, review [Home Realm Discovery](#home-realm-discovery).

    6. Under **Domain Verification Requirement**, choose your desired level of verification:
       * **Off**: Customer admins are not prompted to verify their domain when setting up SSO. **Off** is the default setting for new access tickets.
       * **Optional**: Customer admins are prompted to verify their domain when setting up SSO. However, they can skip this step and enable their connection without completing verification.
       * **Required**: Customer admins must verify their domain when setting up SSO. They will not be able to enable their connection until verification is complete.

    7. Under **Provisioning**, optionally enable **Sync user profiles using provisioning**. When enabled, additional configuration is available:
       * **Bearer Token Expiration**: Define an expiration date for the SCIM bearer token. By default, bearer tokens do not expire.
       * **Bearer Token Permissions (Scopes)**: Choose which actions the token can perform. By default, all provisioning scopes are enabled:
         * `get:users`
         * `post:users`
         * `put:users`
         * `patch:users`
         * `delete:users`

    8. Under **Time to Live**, set an expiration period for the access ticket in seconds. By default, time to live is set to 432000 seconds (which equals five days).

       * Time to Live determines how long an access ticket URL is active **before** a customer admin launches the self-service assistant. It does not determine how long the customer admin has access to the assistant after it’s been launched. The expiration of the self-service assistant itself is 5 hours and cannot be configured.

    9. Under **Metadata**, add up to 10 metadata associated with the connection.

    10. Review your access ticket configuration for accuracy. Then, select **Create Ticket**.

    A Ticket Information popup containing the access ticket URL then displays. Copy and save this URL somewhere safe, as you cannot retrieve this URL again after closing the popup.

    You can share the access ticket URL with your customer admin through email, chat, or another communication channel to grant them access to the self-service assistant. The assistant will then guide them through configuring the SSO connection. To learn more about that experience, review [Self-service assistant experience](/docs/authenticate/enterprise-connections/self-service-SSO#self-service-assistant-experience).
  </Tab>

  <Tab title="Management API">
    To generate an access ticket through the Management API.

    1. Retrieve the ID of the self-service profile you want to associate with the access ticket through the [Retrieve Self-Service Profiles](https://auth0.com/docs/api/management/v2/self-service-profiles/get-self-service-profiles) endpoint.
    2. Call the [SSO Access Ticket](https://auth0.com/docs/api/management/v2/self-service-profiles/post-sso-ticket) endpoint using the ID of the appropriate self-service profile:

    `POST  /api/v2/self-service-profiles/{id}/sso-ticket`

    In the request body, specify the parameters described in the table below.

    <table>
      <thead>
        <tr>
          <th><strong>Parameter</strong></th>
          <th><strong>Description</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>connection\_config</code></td>
          <td>Object.<br /><br />Required when generating an access ticket for <strong>a new SSO connection</strong>. Customer admins will be able to modify key elements of the connection, such as the SAML certificate or OIDC ID or secret.</td>
        </tr>

        <tr>
          <td><code>connection\_config.name</code></td>
          <td><strong>Required</strong>. String.<br /><br />Name for the connection created through the SSO setup assistant. Maximum length is 128.</td>
        </tr>

        <tr>
          <td><code>connection\_config.display\_name</code></td>
          <td><strong>Optional</strong>. String.<br /><br />User-friendly name for the new connection created through the self-service assistant. This name displays on Universal Login prompts. Maximum length is 128.</td>
        </tr>

        <tr>
          <td><code>connection\_config.is\_domain\_connection</code></td>
          <td><strong>Optional</strong>. Boolean.<br /><br />Set to <code>true</code> if the connection is at the domain level; requires <a href="/docs/get-started/applications/dynamic-client-registration">Dynamic Client Registration</a>.</td>
        </tr>

        <tr>
          <td><code>connection\_config.show\_as\_button</code></td>
          <td><strong>Optional</strong>. Boolean.<br /><br />When <code>true</code>, the connection displays as an authentication option on your application's login screen.</td>
        </tr>

        <tr>
          <td><code>connection\_config.metadata</code></td>
          <td><strong>Optional</strong>. Object\[].<br /><br />Metadata associated with the new connection.<br /><br /> Object can contain up to 10 key-value pairs. String values limited to 255 characters.</td>
        </tr>

        <tr>
          <td><code>connection\_config.options</code></td>
          <td><strong>Optional</strong>. Object\[].<br /><br />Options for the new connection, including:<br /><br /><ul><li><code>icon\_url</code></li><li><code>domain\_aliases\[]</code></li><li><code>idpinitiated</code></li></ul></td>
        </tr>

        <tr>
          <td><code>connection\_config.options.icon\_url</code></td>
          <td><strong>Optional</strong>. String.<br /><br />URL of the icon image to use if <code>connection\_config.show\_as\_button</code> is enabled. Must use HTTPS.</td>
        </tr>

        <tr>
          <td><code>connection\_config.options.domain\_aliases</code></td>
          <td><strong>Optional</strong>. String\[].<br /><br />Domains to use for home realm discovery.<br /><br />Domains entered into <code>domain\_aliases</code> are automatically marked as verified. To have a customer admin verify a domain themselves, do not specify this attribute and instead use <code>domain\_aliases\_config</code> (described further on in this table). This option allows you to prompt the customer admin to verify their domain through the self-service assistant.<br /><br />For more information, review <a href="/docs/authenticate/enterprise-connections/self-service-SSO/manage-self-service-sso#domain-verification-and-home-realm-discovery">Domain Verification and Home Realm Discovery</a>.</td>
        </tr>

        <tr>
          <td><code>connection\_config.options.idpinitiated</code></td>
          <td><strong>Optional</strong>. Object.<br /><br />Allows <a href="/docs/authenticate/enterprise-connections/self-service-SSO/manage-self-service-sso#saml-idp-initiated-sso">SAML IdP-initiated SSO</a> and includes the following attributes:<br /><br /><ul><li><code>enabled</code></li><li><code>client\_id</code></li><li><code>client\_protocol</code></li><li><code>client\_authorizequery</code></li></ul><br />For full details, review the <a href="https://auth0.com/docs/api/management/v2/self-service-profiles/post-sso-ticket">SSO Access Ticket</a> endpoint in the Management API Explorer.</td>
        </tr>

        <tr>
          <td><code>enabled\_organizations</code></td>
          <td><strong>Optional</strong>. Object\[].<br /><br />A list of organizations to associate with the new connection.</td>
        </tr>

        <tr>
          <td><code>enabled\_organizations\[].organization\_id</code></td>
          <td><strong>Required</strong> when using <code>enabled\_organizations</code>.<br /><br /> String.<br /><br /> ID of a specific organization to associate with the new connection.<br /><br />You can retrieve IDs through the Organizations section of the <a href="https://manage.auth0.com/#/organizations">Auth0 Dashboard</a>, the <a href="https://auth0.com/docs/api/management/v2/organizations/get-organizations">Get Organizations</a> endpoint, or the <a href="https://auth0.com/docs/api/management/v2/organizations/get-name-by-name">Get Organization by Name</a> endpoint.</td>
        </tr>

        <tr>
          <td><code>enabled\_organizations\[].assign\_membership\_on\_login</code></td>
          <td><strong>Optional</strong>. Boolean.<br /><br />When <code>true</code>, users who log in with the new connection are automatically granted membership to the specified organization.</td>
        </tr>

        <tr>
          <td><code>enabled\_organizations\[].show\_as\_button</code></td>
          <td><strong>Optional</strong>. Boolean.<br /><br />When <code>true</code>, the new connection displays as an authentication option on the Organization login screen for your application.</td>
        </tr>

        <tr>
          <td><code>ttl\_sec</code></td>
          <td><strong>Optional</strong>. Number.<br /><br />Number of seconds an access ticket URL remains active before a customer admin launches the self-service assistant. If unspecified or set to 0, the value defaults to <code>432000</code> (the maximum amount of 5 days).<br /><br />Note that this expiration period does not determine how long a customer admin has access to the self-service after it’s been launched. The expiration of the assistant itself is 5 hours and cannot be configured.</td>
        </tr>

        <tr>
          <td><code>domain\_aliases\_config</code></td>
          <td><strong>Optional</strong>. Object.<br /><br />Contains domain\_verification which is used to determine whether domain verification is required, optional, or disabled.<br /><br />Options for domain\_verification include:<br /><br /><ul><li><code>none</code>: Disables domain verification. You can also disable domain verification by leaving the <code>domain\_aliases\_config</code> object out of your request.</li><li><code>optional</code>: Allows customer admins to skip domain verification during setup.</li><li><code>required</code>: Requires customer admins to verify their domain during setup.</li></ul><br />To learn more, review <a href="/docs/authenticate/enterprise-connections/self-service-SSO/manage-self-service-sso#domain-verification-and-home-realm-discovery">Domain Verification and Home Realm Discovery</a>.</td>
        </tr>
      </tbody>
    </table>

    **Example Request Body**

    ```json lines expandable theme={null}
    {
       "connection_config":{
          "name":"string",
          "display_name":"string",
          "is_domain_connection":true,
          "show_as_button":true,
          "metadata":{
             "key1":"value1",
             "key2":"value2"
          },
          "options":{
             "icon_url":"string",
             "domain_aliases":[
                "acme.corp",
                "okta.com"
             ],
             "idpinitiated": { 
                "enabled": true, 
                "client_id": "string", 
                "client_protocol": "string", 
                "client_authorizequery": "string" 
            }
          }
       },
       "enabled_organizations":[
          {
             "organization_id":"string",
             "assign_membership_on_login":true,
             "show_as_button":true
          }
       ],
       "ttl_sec":0,
       "domain_aliases_config": {
           "domain_verification": "string"
        }
    }
    ```

    In response, you receive a URL to the self-service access ticket:

    ```json lines theme={null}
    {
      "ticket": "https://{domain}/self-service/connections-flow?ticket={id}"
    }
    ```

    After you receive the ticket URL, share the link with your customer admin to grant them access to the self-service assistant. The assistant will then guide them through configuring the SSO connection. To learn more about that experience, review [Self-service assistant experience](/docs/authenticate/enterprise-connections/self-service-SSO#self-service-assistant-experience).

    You can wrap access ticket generation in your own self-service portal or send ticket URLs directly to customer admins through email, chat, or other communication channels.
  </Tab>
</Tabs>

### Generate access tickets for existing connections

You can generate access tickets for existing connections through either the Auth0 Dashboard or the Management API.

<Warning>
  By default, access ticket URLs remain valid for five days after generation. After accessing the ticket URL, the customer admin has five hours to complete their setup. An access ticket URL can be accessed a maximum of 10 times; once this limit is reached, a new access ticket must be requested.

  If needed, you can revoke an access ticket prior to its expiration to immediately cease access to the self-service assistant.
</Warning>

<Callout icon="file-lines">
  If a customer admin initiates **domain verification** through the self-service assistant, they may require an additional access ticket to complete the setup process.

  Domain verification occurs as the final step of the self-service assistant. At this point in the workflow, the connection has been created but not enabled. If domain verification is required, the customer admin cannot enable their connection until verification is complete.

  While verification typically occurs in a timely manner, it may take 24-48 hours in some cases. If this occurs, the customer admin will not be able to use their original access ticket to enable their connection, as tickets expire five hours after they are first accessed.

  To complete this process, you can generate an access ticket that allows the customer admin to modify the connection they configured with their initial ticket. When creating this ticket, ensure you specify the Connection ID of the connection they configured with their first access ticket.
</Callout>

<Tabs>
  <Tab title="Auth0 Dashboard">
    To edit an access ticket through the Auth0 Dashboard:

    1. Navigate to [Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise) and access the Self-Service SSO section. Then, select the self-service profile with which you want to create an access ticket.

    2. Select **Generate Ticket** to open the ticket form. Under **Select ticket type**, choose **Edit an existing connection**.

    3. Under **Ticket configuration**, provide the ID of the existing connection you want the customer admin to modify.

    4. Select **Next**.

    5. Under **Domain Verification**, choose your desired level of verification:

       1. **Off**: Customer admins are not prompted to verify their domain when setting up SSO. This option is selected by default for new access tickets.
       2. **Optional**: Customer admins are prompted to verify their domain when setting up SSO. However, they can skip this step and enable their connection without completing verification.
       3. **Required**: Customer admins must verify their domain when setting up SSO. They will not be able to enable their connection until verification is complete.

    6. Under **Provisioning**, optionally enable **Sync user profiles using provisioning**. When enabled, additional configuration is available:
       * **Bearer Token Expiration**: Define an expiration date for the SCIM bearer token. By default, bearer tokens do not expire.
       * **Bearer Token Permissions (Scopes)**: Choose which actions the token can perform. By default, all provisioning scopes are enabled:
         * `get:users`
         * `post:users`
         * `put:users`
         * `patch:users`
         * `delete:users`

    7. Under **Time to Live**, set an expiration period for the access ticket in seconds. By default, time to live is set to 432000 seconds (which equals five days).

       A. Time to Live determines how long an access ticket URL is active **before** a customer admin launches the self-service assistant. It does not determine how long the customer admin has access to the assistant after it’s been launched. The expiration of the self-service assistant itself is five hours and cannot be configured.

    8. Review your access ticket configuration for accuracy. Then, select **Create Ticket**.

    A Ticket Information popup containing the access ticket URL then displays. Copy and save this URL somewhere safe as you cannot retrieve this URL again after closing the popup.

    You can share the access ticket URL with your customer admin through email, chat, or another communication channel to grant them access to the self-service assistant. The assistant will then guide them through configuring the SSO connection. To learn more about that experience, review [Self-service assistant experience](/docs/authenticate/enterprise-connections/self-service-SSO#self-service-assistant-experience).
  </Tab>

  <Tab title="Management API">
    To generate an access ticket through the Management API, follow the steps below.

    <Callout icon="file-lines">
      You cannot update `connection_config` details for an existing connection through the [SSO Access Ticket](https://auth0.com/docs/api/management/v2/self-service-profiles/post-sso-ticket) endpoint. If you need to modify this information for an existing connection, use the [Update a Connection](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id) endpoint instead.
    </Callout>

    1. Retrieve the ID of the self-service profile you want to associate with the access ticket through the [Retrieve Self-Service Profiles](https://auth0.com/docs/api/management/v2/self-service-profiles/get-self-service-profiles) endpoint.
    2. Call the [SSO Access Ticket](https://auth0.com/docs/api/management/v2/self-service-profiles/post-sso-ticket) endpoint using the ID of the appropriate self-service profile:

       `POST /api/v2/self-service-profiles/{id}/sso-ticket`

       In the request body, specify the following parameters:

    <table>
      <thead>
        <tr>
          <th><strong>Parameter</strong></th>
          <th><strong>Description</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>connection\_id</code></td>
          <td><strong>Required</strong>. String.<br /><br />ID of the connection a customer admin can update through the self-service assistant. Customer admins can modify key elements of the connection, such as the SAML certificate or OIDC ID and secret.<br /><br />Connection IDs can be retrieved through the Authentication section of the <a href="https://manage.auth0.com/#/connections/enterprise">Auth0 Dashboard</a> or the <a href="https://auth0.com/docs/api/management/v2/connections/get-connections">Get All Connections</a> endpoint.\*\*</td>
        </tr>

        <tr>
          <td><code>provisioning\_config</code></td>
          <td> **Optional.** Object. <br /> Determines whether or not customer admin is able to set up SCIM. If the connection is created without all provisioning `scopes`, `get:users`,`post:users`,`put:users`, `patch:users`,`delete:users`, SCIM will not be enabled.</td>
        </tr>

        <tr>
          <td><code>ttl\_sec</code></td>
          <td><strong>Optional</strong>. Number.<br /><br />Number of seconds an access ticket URL remains active before a customer admin launches the self-service assistant. If unspecified or set to <code>0</code>, the value defaults to <code>432000</code> (which equals 5 days). <br /><br />Note that this expiration period does not determine how long a customer admin has access to the self-service assistant after it's been launched. The expiration of the assistant itself is five hours and cannot be configured.</td>
        </tr>

        <tr>
          <td><code>domain\_aliases\_config</code></td>
          <td><strong>Optional</strong>. Object.<br /><br />Contains domain\_verification which is used to determine whether domain verification is required, optional, or disabled.<br /><br />Options for domain\_verification include:<br /><br /><ul><li><code>none</code>: Disables domain verification. You can also disable domain verification by leaving the <code>domain\_aliases\_config</code> object out of your request.</li><li><code>optional</code>: Allows customer admins to skip domain verification during setup.</li><li><code>required</code>: Requires customer admins to verify their domain during setup.</li></ul><br />To learn more, review <a href="/docs/authenticate/enterprise-connections/self-service-SSO/manage-self-service-sso#domain-verification-and-home-realm-discovery">Domain Verification and Home Realm Discovery</a>.</td>
        </tr>
      </tbody>
    </table>

    **Example Request Body**

    ```json lines theme={null}
    {
      "connection_id": "string",
       "ttl_sec":0,
       "domain_aliases_config": {
           "domain_verification": "string"
        }
    }
    ```

    In response, you receive a URL to the self-service access ticket:

    ```json lines theme={null}
    {
      "ticket": "https://{domain}/self-service/connections-flow?ticket={id}"
    }
    ```

    After you receive the ticket URL, share the link with your customer admin to grant them access to the self-service assistant. The assistant will then guide them through configuring the SSO connection. To learn more about that experience, review [Self-service assistant experience](/docs/authenticate/enterprise-connections/self-service-SSO#self-service-assistant-experience).

    You can wrap access ticket generation in your own self-service portal or send ticket URLs directly to customer admins through email, chat, or other communication channels.
  </Tab>
</Tabs>

### Revoke an access ticket

By default, an access ticket URL remains valid for five days. Upon accessing the URL, a customer admin has five hours to complete their setup.

If needed, you can revoke an access ticket prior to its expiration. For example, if an access ticket is shared with the wrong <Tooltip href="/docs/glossary?term=audience">audience</Tooltip>, you can revoke the ticket to prevent unauthorized access to the self-service assistant.

When you revoke an access ticket, its URL immediately becomes invalid, and any associated sessions are terminated. Customer admins with the URL will no longer be able to access the self-service assistant. You can then generate and share new access tickets as needed.

To revoke an access ticket:

1. Retrieve the ID of the self-service profile associated with the access ticket using the [Retrieve Self-Service Profiles](https://auth0.com/docs/api/management/v2/self-service-profiles/get-self-service-profiles) endpoint.
2. Locate the ID of the access ticket you wish to revoke. IDs can be found at the end of the access ticket URL.
3. Call the [Revoke SSO Access Ticket](https://auth0.com/docs/api/management/v2/self-service-profiles/post-revoke) endpoint using the appropriate IDs:

`POST  /api/v2/self-service-profiles/{id}/sso-ticket/{id}/revoke`

In response, a `202 Accepted` is returned.

## References

### APIs

To manage Self-Service SSO, the following [Management API](https://auth0.com/docs/api/management/v2/introduction) endpoints are available:

* [Get self-service profiles](https://auth0.com/docs/api/management/v2/self-service-profiles/get-self-service-profiles)
* [Create a self-service profile](https://auth0.com/docs/api/management/v2/self-service-profiles/post-self-service-profiles)
* [Get a self-service profile by ID](https://auth0.com/docs/api/management/v2/self-service-profiles/get-self-service-profiles-by-id)
* [Delete a self-service profile by ID](https://auth0.com/docs/api/management/v2/self-service-profiles/delete-self-service-profiles-by-id)
* [Update a self-service profile](https://auth0.com/docs/api/management/v2/self-service-profiles/patch-self-service-profiles-by-id)
* [Get custom text for a self-service profile](https://auth0.com/docs/api/management/v2/self-service-profiles/get-self-service-profile-custom-text)
* [Set custom text for a self-service profile](https://auth0.com/docs/api/management/v2/self-service-profiles/put-self-service-profile-custom-text)
* [Create an SSO-access ticket to initiate the self-service SSO flow](https://auth0.com/docs/api/management/v2/self-service-profiles/post-sso-ticket)
* [Revoke an SSO access ticket](https://auth0.com/docs/api/management/v2/self-service-profiles/post-revoke)

### Rate Limits

When using Self-Service SSO, the following rate limits apply:

<table>
  <thead>
    <tr>
      <th>Description</th>
      <th>Endpoint</th>
      <th>Limits</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Manage SSO profiles</td>
      <td><code>/api/v2/self-service-profiles</code></td>
      <td>Review the <a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations">Management API rate limits</a> for your subscription type.</td>
    </tr>

    <tr>
      <td>Create an access ticket</td>
      <td><code>/api/v2/self-service-profiles//sso-ticket</code></td>
      <td>Review the <a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations">Management API rate limits</a> for your subscription type.</td>
    </tr>

    <tr>
      <td>Consume an access ticket</td>
      <td><code>/self-service/connection-flows?ticket=</code></td>
      <td>6 / min / IP</td>
    </tr>

    <tr>
      <td>Load the webapp (including setup assistant) and webapp endpoints</td>
      <td><code>/self-service/\*</code></td>
      <td>50 / min / IP<br />90 / min / tenant</td>
    </tr>
  </tbody>
</table>


# User Attribute Profile
Source: https://auth0.com/docs/authenticate/enterprise-connections/user-attribute-profile

Learn how the User Attribute Profile allows you configure users for SCIM provisioning through the Self-Service experience.

<Warning>
  User Attribute Profile with Self-Service SSO is currently in Early Access for B2B Professional and B2B Enterprise customers. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0 release stages, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

The User Attribute Profile (UAP) provides a consistent way to define, manage, and map user attributes across protocols such as [SCIM](/docs/authenticate/protocols/scim), [SAML](/docs/authenticate/protocols/saml), and [OIDC](/docs/authenticate/login/oidc-conformant-authentication). UAP with [Self-Service SSO](/docs/authenticate/enterprise-connections/self-service-SSO) gives administrators greater control over user identity data by defining user attributes and applying the profile across authentication protocols.

## How it works

* **Profile Definition**<p />
  An administrator creates a User Attribute Profile to define attributes, including:
  * How to display attributes
  * How to make attributes required
  * How attributes map to Auth0 and external identity systems

* **Flexible Scope**<p />
  Profiles are linked to Self-Service SSO flows but are designed for provisioning, onboarding, and entitlement management.

* **Unified Mapping Layer**<p />
  Each attribute supports mappings across authentication protocols with the option to override values for specific providers or connection strategies, such as Okta and Entra ID.

## Attribute mapping and override<p />

UAP supports multi-protocol attribute definitions and strategy overrides for provider-specific needs.

**Attribute mapping**

| **Protocol**  | **Description**                                                                                                                                                                                         |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Auth0 Mapping | Canonical attribute stored in Auth0 (`email`, `name`, `app_metadata.department`).                                                                                                                       |
| OIDC Mapping  | Standard OIDC claims (`sub`, `preferred_username`, `zoneinfo`). To learn more about OIDC standard claims, read [Standard Claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). |
| SAML Mapping  | Supports one or more assertion URIs `(http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress).`                                                                                             |
| SCIM Mapping  | Provisioning attributes (`name.familyName`, `addresses[type eq "work"].country`).                                                                                                                       |

**Strategy overrides**

Some providers use non-standard mappings. UAP allows overrides:

| **Protocol**    | **Description**                                                                       |
| --------------- | ------------------------------------------------------------------------------------- |
| SAML            | Map userName instead of `externalId`.                                                 |
| WAAD (Entra ID) | Use `oid` as the OIDC identifier.                                                     |
| Okta            | Map attributes such as `middleNam`e or `federated_groups` using Okta-specific claims. |

### User ID

The user\_id property defines how to map OIDC claims, SAML attributes, or SCIM attributes to the Auth0 user ID. Every Auth0 user must have an ID, so this mapping is required.

* For OIDC, the choices are rigid (typically `sub`, or `oid` for Azure AD, or `email` for Google).
* For SAML and SCIM, the mapping is more flexible and can point to multiple possible attributes.

### User attributes

The `user_attributes` property contains mapping information allows the system to interpret incoming claims from the IdP and store them as Auth0 user profile attributes.

Each attribute must be provided as a key/value pair:

* The key corresponds to the attribute name.
* The value is an object with:
  * `label`
  * `description`
  * `profile_required`
  * `auth0_mapping`
  * `saml_mapping`
  * `scim_mapping`
  * `oidc_mapping` an object with properties
    * `mapping` represents the incoming claim from the IdP (literal value, dynamic context object, or both using `${variable}` syntax supporting the [context object](/docs/authenticate/identity-providers/enterprise-identity-providers/configure-pkce-claim-mapping-for-oidc#context-object))
    * `display_name` the label shown to end users in self-service flows

### Strategy overrides

The `strategy_overrides` property allows you to specify exceptions for individual identity providers (IdPs), since not all IdPs expose the same identifiers or claims.

Each override defines protocol-specific mappings that replace the defaults defined in `user_id` or `user_attributes`.

## Examples

### User identifier

```json theme={null}
"user_id": {
  "oidc_mapping": "sub",
  "saml_mapping": [
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
  ],
  "scim_mapping": "externalId",
  "strategy_overrides": {
    "waad": {
      "oidc_mapping": "oid"
    },
    "samlp": {
      "scim_mapping": "userName"
    },
    "google-apps": {
      "oidc_mapping": "email"
    }
  }
},
```

* **Default identifier**: `externalId` via SCIM.
* **SAML**: Multiple identifier URIs supported.
* **OIDC**: Uses `sub`.
* **Overrides**: SAML and WAAD customize mappings.

### Email attribute

```json theme={null}
"email": {
  "description": "Email",
  "label": "Email",
  "profile_required": true,
  "auth0_mapping": "email",
  "scim_mapping": "emails[primary eq true].value",
  "oidc_mapping": {
    "mapping": "${context.tokenset.email}",
    "display_name": "email"
  },
  "saml_mapping": [
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
  ],
  "strategy_overrides": {
    "waad": {
      "scim_mapping": "emails[type eq \"work\"].value"
    }
  }
}
```

* Suggested for most profiles.
* Unified across Auth0, OIDC, SAML and SCIM.
* WAAD override ensures correct mapping to work emails.

## Create a User Attribute Profile

You can define a UAP through Self-Service SSO using the Auth0 Dashboard or the Management API. Currently, it can be configured through the Self-Service SSO experience.

### Configure with Auth0 Dashboard

1. Navigate to [**Authentication > Enterprise > Self-Service SSO**](http://manage.auth0.com/*/connections/enterprise/self-service-profiles).
2. Select **+Create Profile**.
3. Provide a **Name** and optional **Description** for the new profile.
4. Add a User Attribute Profile entry by either selecting an existing profile or choosing **+Create New**.
   * For a new profile, provide a **User Profile Attribute Name**.
   * Review mappings to ensure the profile attributes are mapping to your preferred Auth0 attributes.
5. Choose **Create**.

Your new UAP is available to configure for SSO.

### Configure with Management API

To manage User Attribute Profiles, the following [Management API](https://auth0.com/docs/api/management/v2/introduction) endpoints are available:

* `POST` `/api/v2/user-attribute-profiles`
* `GET` `/api/v2/user-attribute-profiles`
* `PATCH` `/api/v2/user-attribute-profiles/{id}`
* `GET` `/api/v2/user-attribute-profiles/{id}`
* `GET` `/api/v2/user-attribute-profiles/templates`
* `GET` `/api/v2/user-attribute-profiles/templates/{id}`

## Learn more

* [Self-Service SSO](/docs/authenticate/enterprise-connections/self-service-SSO)
* [Configure PKCE and Claim Mapping for OIDC Connections](/docs/authenticate/identity-providers/enterprise-identity-providers/configure-pkce-claim-mapping-for-oidc)
* [Map SAML Attributes with Auth0 as IdP/SAML Add-on](/docs/authenticate/protocols/saml/saml-configuration/saml-attribute-mapping-examples)
* [Map AD/LDAP Profile Attributes to Auth0 User Profile](/docs/authenticate/protocols/saml/saml-configuration/saml-attribute-mapping-examples)


# Protocols
Source: https://auth0.com/docs/authenticate/protocols

Describes which authorization protocols Auth0 supports and how they work.

There are a set of open specifications and protocols that specify how to design an authentication and authorization system. They specify how you should manage identity, move personal data securely, and decide who can access applications and data.

The identity industry standards that we use at Auth0 are:

* Open Authorization (<Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip>) 1: the original standard for access delegation. Used as a way for a user to grant websites access to their information on other websites or apps, but without giving them the credentials.
* [Open Authorization (OAuth) 2](/docs/authenticate/protocols/oauth): an authorization standard that allows a user to grant limited access to their resources on one site to another site, without having to expose their credentials. You use this standard every time you log in to a site using your Google account and you are asked if you agree with sharing your email address and your contacts list with that site.
* [OpenID Connect (OIDC)](/docs/authenticate/protocols/openid-connect-protocol): an identity layer that sits on top of OAuth 2 and allows for easy verification of the user's identity, as well as the ability to get basic profile information from the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>.
* [Lightweight Directory Access Protocol (LDAP)](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector): an application protocol used for accessing and maintaining distributed directory information services over an IP network. The function of LDAP is to enable access to an existing directory like Active Directory (AD). Auth0 uses a connector that you install on your network to integrate with AD/LDAP.
* [JSON Web Tokens (JWTs)](/docs/secure/tokens/json-web-tokens): an open standard that defines a compact and self-contained way for securely transmitting information between parties as a JSON object.
* [Security Assertion Markup Language (SAML)](/docs/authenticate/protocols/saml/saml-configuration): an open-standard, XML-based data format that allows businesses to communicate user authentication and authorization information to partner companies and enterprise applications their employees may use.
* [System for Cross-domain Identity Management (SCIM)](/docs/authenticate/protocols/scim): a set of application-level protocols to securely manage and communicate user data across multiple domains. SCIM clients can be integrated to manage CRUD (create, replace, update, delete) operations, apply queries and filters, and create user groups within your organization.
* [WS-Federation (WS-Fed)](/docs/authenticate/protocols/ws-fed-protocol): a standard developed by Microsoft, and used extensively in their applications. It defines the way <Tooltip href="/docs/glossary?term=security+tokens">security tokens</Tooltip> can be transported between different entities to exchange identity and authorization information.


# Lightweight Directory Access Protocol
Source: https://auth0.com/docs/authenticate/protocols/ldap-protocol

Describes how Auth0 supports the Lightweight Directory Access Protocol (LDAP).

The Lightweight Directory Access Protocol (LDAP) is an application protocol, used for accessing and maintaining distributed directory information services over an Internet Protocol (IP) network. The function of LDAP is to enable access to an existing directory like Active Directory (AD). Auth0 uses an [Active Directory/LDAP Connector](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector) that you install on your network to integrate with AD/LDAP.

## Learn more

* [AD/LDAP Connector](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector)
* [Auth0 AD/LDAP Connector Health Monitor Extension](/docs/customize/extensions/ad-ldap-connector-health-monitor)
* [Configure AD/LDAP Connector Authentication with Kerberos](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/configure-ad-ldap-connector-with-kerberos)
* [Deploy AD/LDAP Connectors for High Availability Environments](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-high-availability)
* [Point AD/LDAP Connector to Auth0 Connections](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-to-auth0)


# OAuth 2.0 Authorization Framework
Source: https://auth0.com/docs/authenticate/protocols/oauth

Learn how Auth0 works with the OAuth 2.0 Authorization Framework.

<Card title="Overview">
  Key Concepts

  * Auth0 supports the OAuth 2.0 protocol drafted by the Internet Engineering Task Force (IETF).
  * Read about roles, grant types (or workflows), and endpoints from the OAuth 2.0 spec.
</Card>

The [OAuth 2.0](https://tools.ietf.org/html/rfc6749) authorization framework is a protocol that allows a user to grant a third-party web site or application access to the user's protected resources, without necessarily revealing their long-term credentials or even their identity.

<Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> introduces an authorization layer and separates the role of the client from that of the <Tooltip href="/docs/glossary?term=resource+owner">resource owner</Tooltip>. In OAuth, the client requests access to resources controlled by the resource owner and hosted by the <Tooltip href="/docs/glossary?term=resource+server">resource server</Tooltip> and is issued a different set of credentials than those of the resource owner. Instead of using the resource owner's credentials to access protected resources, the client obtains an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> - a string denoting a specific scope, lifetime, and other access attributes. Access tokens are issued to third-party clients by an <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip> with the approval of the resource owner. Then the client uses the access token to access the protected resources hosted by the resource server.

Auth0 generates access tokens for API authorization scenarios, in [JSON web token (JWT) format](/docs/secure/tokens/json-web-tokens/json-web-token-structure). The permissions represented by the access token, in OAuth terms, are known as [scopes](/docs/get-started/apis/scopes). When an application authenticates with Auth0, it specifies the scopes it wants. If those scopes are authorized by the user, then the access token will represent these authorized scopes.

## Roles

An OAuth 2.0 flow has the following roles:

* **Resource Owner**: Entity that can grant access to a protected resource. Typically, this is the end-user.
* **Resource Server**: Server hosting the protected resources. This is the API you want to access.
* **Client**: Application requesting access to a protected resource on behalf of the Resource Owner.
* **Authorization Server**: Server that authenticates the Resource Owner and issues access tokens after getting proper authorization. In this case, Auth0.

## Grant types

OAuth 2.0 defines four flows to get an access token. These flows are called grant types. [Deciding which one is suited for your case](/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use) depends mostly on your application type.

* [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow): used by Web Apps executing on a server. This is also used by mobile apps, using the [Proof Key for Code Exchange (PKCE) technique](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce).
* [Implicit Flow with Form Post](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post): used by JavaScript-centric apps (Single-Page Applications) executing on the user's browser.
* [Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow): used by highly-trusted apps.
* [Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow): used for machine-to-machine communication.

The specification also provides an extensibility mechanism for defining additional grant types. To learn more about how each grant type works and when it should be used, see [Authentication and Authorization Flows](/docs/get-started/authentication-and-authorization-flow).

## Endpoints

OAuth 2.0 uses two endpoints: the `/authorize` endpoint and the `/oauth/token` endpoint.

### Authorization endpoint

The `/authorize` endpoint is used to interact with the resource owner and get the authorization to access the protected resource. To better understand this, imagine that you want to log in to a service using your Google account. First, the service redirects you to Google in order to authenticate (if you are not already logged in) and then you will get a consent screen, where you will be asked to authorize the service to access some of your data (protected resources); for example, your email address and your list of contacts.

The request parameters of the `/authorize` endpoint are:

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>response\_type</code></td>
      <td>Tells the authorization server which grant to execute.</td>
    </tr>

    <tr>
      <td><code>response\_mode</code></td>
      <td>(Optional) How the result of the authorization request is formatted. Values: <br />- <code>query</code>: for Authorization Code grant. <code>302 Found</code> triggers redirect. <br />- <code>fragment</code>: for Implicit grant. <code>302 Found</code> triggers redirect. <br />- <code>form\_post</code>: <code>200 OK</code> with response parameters embedded in an HTML form as hidden parameters. <br />- <code>web\_message</code>: For Silent Authentication. Uses HTML5 web messaging.</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>The ID of the application that asks for authorization.</td>
    </tr>

    <tr>
      <td><code>redirect\_uri</code></td>
      <td>Holds a URL. A successful response from this endpoint results in a redirect to this URL.</td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td>A space-delimited list of permissions that the application requires.</td>
    </tr>

    <tr>
      <td><code>state</code></td>
      <td>An opaque value, used for security purposes. If this request parameter is set in the request, then it is returned to the application as part of the <code>redirect\_uri</code>.</td>
    </tr>

    <tr>
      <td><code>connection</code></td>
      <td>Specifies the connection type for Passwordless connections</td>
    </tr>
  </tbody>
</table>

You can configure custom query parameters when your application makes the initial call to the `/authorize` endpoint to authenticate a user. You can use custom query parameters to provide additional context to the page template for the <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> experience.

You must enable ID First to use the `connection` parameter. For more information on the `connection` parameter and the Universal Login experience, review [Passwordless for Universal Login](/docs/authenticate/passwordless/passwordless-with-universal-login).

Query parameters prefixed with `ext-` automatically appear in the [page template context](/docs/customize/login-pages/universal-login/customize-templates#custom-query-parameters).

This endpoint is used by the Authorization Code and the Implicit grant types. The authorization server needs to know which grant type the application wants to use since it affects the kind of credential it will issue:

* For the Authorization Code grant, it will issue an authorization code (which can later be exchanged for an access token at the `/oauth/token` endpoint).
* For the Implicit grant, it will issue an access token, which is an opaque string (or a <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> in an Auth0 implementation) that denotes who has authorized which permissions (scopes) to which application.

To inform the authorization server which grant type to use, the `response_type` request parameter is used as follows:

* For the Authorization Code grant, use `response_type=code` to include the authorization code.
* For the Implicit grant, use `response_type=token` to include an access token. An alternative is to use `response_type=id_token token` to include both an access token and an <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip>.

An ID token is a JWT that contains information about the logged in user. It was introduced by <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC).

The [OAuth 2.0 Multiple Response Type Encoding Practices specification](https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html) added a parameter that specifies how the result of the authorization request is formatted. This parameter is called `response_mode`. It is optional and can take the following values:

<table>
  <thead>
    <tr>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>query</code></td>
      <td>This is the default for Authorization Code grant. A successful response is <code>302 Found</code> which triggers a redirect to the <code>redirect\_uri</code>. The response parameters are embedded in the query component (the part after <code>?</code>) of the <code>redirect\_uri</code> in the <code>Location</code> header. <br />For example: <br /><code>HTTP/1.1 302 Found</code> <br /><code>Location: [https://my-redirect-uri.callback?code=js89p2x1](https://my-redirect-uri.callback?code=js89p2x1)</code> where the authorization code is <code>js89p21</code>.</td>
    </tr>

    <tr>
      <td><code>fragment</code></td>
      <td>This is the default for Implicit grant. A successful response is <code>302 Found</code>, which triggers a redirect to the <code>redirect\_uri</code> (which is a request parameter). The response parameters are embedded in the fragment component (the part after <code>#</code>) of the <code>redirect\_uri</code> in the <code>Location</code> header. <br />For example: <br /><code>HTTP/1.1 302 Found</code><br /><code>Location: [https://my-redirect-uri/callback#access\_token=eyB...78f\&amp;token\_type=Bearer\&amp;expires\_in=3600](https://my-redirect-uri/callback#access_token=eyB...78f\&amp;token_type=Bearer\&amp;expires_in=3600)</code>.</td>
    </tr>

    <tr>
      <td><code>form\_post</code></td>
      <td>The response mode is defined by the <a href="https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html">OAuth 2.0 Form Post Response Mode specification</a>. A successful response is <code>200 OK</code> and the parameters are embedded in an HTML form as hidden params. The <code>action</code> of the form is the <code>redirect\_uri</code> and the <code>onload</code> attribute is configured to submit the form. After the HTML is loaded by the browser, a redirect to the <code>redirect\_uri</code> is done.</td>
    </tr>

    <tr>
      <td><code>web\_message</code></td>
      <td>This response mode is defined in <a href="https://tools.ietf.org/html/draft-sakimura-oauth-wmrm-00">OAuth 2.0 Web Message Response Mode specification</a>. It uses HTML5 Web Messaging instead of the redirect for the authorization response from the /authorization endpoint. This is particularly useful when using Silent Authentication. To do this response mode, you must register your app's URL at the <strong>Allowed Web Origins</strong> field in your Auth0 <a href="https://manage.auth0.com/#/applications/{yourClientId}/settings">application settings</a>.</td>
    </tr>
  </tbody>
</table>

### Token endpoint

The `/oauth/token` endpoint is used by the application in order to get an access token or a <Tooltip href="/docs/glossary?term=refresh+token">refresh token</Tooltip>. It is used by all flows except for the Implicit Flow because in that case an access token is issued directly.

* In the Authorization Code Flow, the application exchanges the authorization code it got from the authorization endpoint for an access token.
* In the Client Credentials Flow and Resource Owner Password Credentials Grant Exchange, the application authenticates using a set of credentials and then gets an access token.

## State parameters

Authorization protocols provide a `state` parameter that allows you to restore the previous state of your application. The `state` parameter preserves some state object set by the client in the Authorization request and makes it available to the client in the response. The primary reason for using the state parameter is to mitigate CSRF attacks. See [Use OAuth 2.0 State Parameters](/docs/secure/attack-protection/state-parameters) for details.

## Learn more

* [Prevent Attacks and Redirect Users with OAuth 2.0 State Parameters](/docs/secure/attack-protection/state-parameters)
* [Which OAuth 2.0 Flow Should I Use?](/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use)


# OpenID Connect Protocol
Source: https://auth0.com/docs/authenticate/protocols/openid-connect-protocol

Describes how to use OpenID Connect protocol with Auth0.

## What is OpenID Connect (OIDC)?

<Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) is an identity layer built on top of the <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> framework. It allows third-party applications to verify the identity of the end-user and to obtain basic user profile information. OIDC uses <Tooltip href="/docs/glossary?term=JSON+web+tokens">JSON web tokens</Tooltip> (JWTs), which you can obtain using flows conforming to the OAuth 2.0 specifications. See our [OIDC Handbook](https://auth0.com/resources/ebooks/the-openid-connect-handbook) for more details.

## OpenID vs. OAuth2

While OAuth 2.0 is about resource access and sharing, OIDC is about user authentication. Its purpose is to give you one login for multiple sites. Each time you need to log in to a website using OIDC, you are redirected to your OpenID site where you log in, and then taken back to the website. For example, if you chose to sign in to Auth0 using your Google account then you used OIDC. Once you successfully authenticate with Google and authorize Auth0 to access your information, Google sends information back to Auth0 about the user and the authentication performed. This information is returned in a JWT. You'll receive an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> and if requested, an <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip>.

## OpenID and JWTs

JWTs contain [claims](/docs/secure/tokens/json-web-tokens/json-web-token-claims), which are statements (such as name or email address) about an entity (typically, the user) and additional metadata. The [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html) defines a set of [standard claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). The set of standard claims include name, email, gender, birth date, and so on. However, if you want to capture information about a user and there currently isn't a standard claim that best reflects this piece of information, you can create custom claims and add them to your tokens.

## Configure applications with OIDC and OAuth2

You can automatically [configure your applications with OIDC discovery](/docs/get-started/applications/configure-applications-with-oidc-discovery).

## Learn more

* [Configure Applications with OIDC Discovery](/docs/get-started/applications/configure-applications-with-oidc-discovery)
* [Force Reauthentication in OIDC](/docs/authenticate/login/max-age-reauthentication)
* [Applications in Auth0](/docs/get-started/applications)
* [Single Sign-On](/docs/authenticate/single-sign-on)
* [User Profiles](/docs/manage-users/user-accounts/user-profiles)


# SAML
Source: https://auth0.com/docs/authenticate/protocols/saml

Learn about the Security Assertion Markup Language (SAML) protocol, which is an open-standard, XML-based framework for authentication and authorization between two entities without a password.

The <Tooltip href="/docs/glossary?term=Security+Assertion+Markup+Language">Security Assertion Markup Language</Tooltip> (SAML) protocol is an open-standard, XML-based framework for authentication and authorization between two entities without a password:

* **Service provider** (SP) agrees to trust the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> to authenticate users.
* **Identity provider** (IdP) authenticates users and provides to service providers an authentication assertion that indicates a user has been authenticated.

Auth0 supports the SAML protocol and can serve as the IdP, the SP, or both including:

* SAML2 web applications
* SAML <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> integrations
* IdP-initiated SSO
* Microsoft Active Directory Federation Services (ADFS)
* SAML request signing and encrypting

## Supported SAML bindings and options

Auth0 supports the following SAML bindings:

* HTTP Redirect
* HTTP POST

Auth0 supports the following SAML options:

* Web Browser SSO Profile
* Single Logout Profile
* Name Identifier Management Profile
* Name Identifier Mapping Profile


# SAML Configuration
Source: https://auth0.com/docs/authenticate/protocols/saml/saml-configuration

Describes how Auth0 works with Security Assertion Markup Language (SAML) protocol.

## SAML service providers

Applications, especially custom ones, can authenticate users against an external <Tooltip href="/docs/glossary?term=IdP">IdP</Tooltip> using protocols such as <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) or <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip>. However, you might want to leverage an enterprise <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> provider for authentication, even if you wrote your application to use either protocol.

<Frame>
  <img alt="Protocols SAML SPs Diagram" />
</Frame>

## SAML identity providers

Some applications (such as Salesforce, Box, and Workday) allow users to authenticate against an external IdP using the SAML protocol. You can then integrate the application with Auth0, which serves as the application's SAML IdP. Application users will be redirected to Auth0 to log in, and Auth0 can authenticate them using any backend authentication connection, such as an LDAP directory, a database, or another SAML IdP or Social Provider. Once the user is authenticated, Auth0 returns a SAML assertion to the application that indicates such.

<Frame>
  <img alt="Protocols SAML IdP Diagram" />
</Frame>

Here is a list of IdP services known to support the SAML protocol. There may be additional services beyond what is shown below. The following providers have participated in a Kantara interoperability test and are therefore likely to conform well to the SAML spec.

* adAS
* ADFS
* Dot Net Workflow
* Elastic <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> Team & Enterprise
* Entrust GetAccess & IdentityGuard (check protocol supported)
* EIC (check protocol supported)
* Ilex Sign\&go
* iWelcome
* NetIQ Access Manager
* OpenAM
* RCDevs Open SAMPL IdP
* Optimal IdM VIS Federation Services
* Oracle Access Manager (Oracle Identity Federation merged into this)
* PingFederate (IDP Light)
* RSA Federated Identity (IDP Light)
* SecureAuth
* Symplified
* Tivoli Federated Identity Manager
* TrustBuilder
* Ubisecure SSO
* WSO2 Identity Server

Auth0 provides specific instructions to configure the following SAML identity providers with Auth0:

* [ADFS](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-adfs-saml-connections)
* [Okta](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-okta-as-saml-identity-provider)
* [OneLogin](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-onelogin-as-saml-identity-provider)
* [PingFederate 7](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-pingfederate-as-saml-identity-provider)
* [Salesforce](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-salesforce-as-saml-identity-provider)
* [SiteMinder](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-siteminder-as-saml-identity-provider)
* [SSOCircle](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-ssocircle-as-saml-identity-provider)

## Auth0 as service provider

If Auth0 serves as the service provider in a SAML federation, Auth0 can route authentication requests to an identity provider without already having an account pre-created for a specific user. Using the assertion returned by the identity provider, Auth0 can capture information needed to create a user profile for the user (this process is sometimes called just-in-time provisioning). To learn more, read [Select from Multiple Connection Options](/docs/libraries/lock/selecting-from-multiple-connection-options).

Even though Auth0 doesn't require pre-created user accounts prior to the authentication process, the application integrated with Auth0 might. If this is the case, you have several options when it comes to handling this:

* After the identity provider creates the user, you can use an out-of-band process can create the accompanying user in the application (or Auth0) and add any user profile attributes required by the application. If, after authentication, any attributes are missing in the profile, the application can obtain them from the appropriate source and store them in the Auth0 user profile. The additional attributes are then sent to the application (in addition to any added by the identity provider) the next time the user logs in.
* You can use an Auth0 rule to call an API to retrieve any missing information and dynamically add it to the Auth0 profile (which is then returned to the application). Rules execute after successful authentication, and your application can retrieve profile attributes each time or you can save the attributes to the Auth0 profile.
* Auth0 can pass the basic profile information from the identity provider to the application, which then retrieves any missing information from another source. With the two sets of information, the application creates a local user profile.

You can specify email domains as part of the Auth0 SAMLP Connection configuration to control the IDP that handles a select group of users. For example, if you add email domain `example.com` to the Auth0 SAMLP Connection configuration for Company X, all users with emails with the `example.com` domain get handled by the specific IDP for Company X.

## Auth0 as identity provider

If Auth0 serves as the identity provider in a SAML federation, user accounts may be created multiple ways:

* Using a back-end authentication system, such as an LDAP directory, a database, or another SAML identity provider.
* Using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.
* Calling the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.
* Implementing self-service user signup.

If your application is written to retrieve user profile information from a local store, you'll need to create the local profile after the accounts have been created in Auth0. Some of the ways you might do this include:

* An out-of-band process creating user profiles in the application;
* An Auth0 rule that executes on first login that calls an application API to create the user profile in the application;
* Modifying the application to create user profiles dynamically, based on information in the SAML assertion.

## Test SAML SSO using Auth0 as service and identity provider

You can use Auth0 as both the SAML service provider and the SAML identity provider for testing purposes.

<Frame>
  <img alt="Protocols Auth0 as SAML SP and IdP Diagram" />
</Frame>

## Learn more

* [SAML Single Sign-On Integrations](/docs/authenticate/protocols/saml/saml-sso-integrations)
* [Configure Auth0 as SAML Service Provider](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider)
* [Configure Auth0 as SAML Identity Provider](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider)
* [Test SAML SSO with Auth0 as Service Provider and Identity Provider](/docs/authenticate/protocols/saml/saml-configuration/configure-auth0-as-service-and-identity-provider)
* [SAML Identity Provider Configuration Settings](/docs/authenticate/protocols/saml/saml-identity-provider-configuration-settings)
* [Customize SAML Assertions](/docs/authenticate/protocols/saml/saml-configuration/customize-saml-assertions)


# Test SAML SSO with Auth0 as Service Provider and Identity Provider
Source: https://auth0.com/docs/authenticate/protocols/saml/saml-configuration/configure-auth0-as-service-and-identity-provider

Describes how to configure SAML SSO with Auth0 as both the service provider and identity provider for testing.

You can configure Auth0 as both the service provider (SP) and the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> (IdP) to test your <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> <Tooltip href="/docs/glossary?term=single+sign-on">single sign-on</Tooltip> (SSO) connection.

<Frame>
  <img alt="Protocols Auth0 as SAML SP and IdP Diagram" />
</Frame>

Auth0 only supports using Auth0 as the SP in SAML configurations with SAML 1.1 or SAML 2.0 while you can use Auth0 as the IdP in SAML configurations with SAML 2.0.

You can set up a simple example application for testing that uses Auth0 to authenticate users through SAML SSO using one tenant as the SAML SP and another tenant as the SAML IdP. You will configure two federations for one tenant.

## Create IdP tenant

If you do not already have a secondary Auth0 tenant to serve as a SAML IdP, you will need to create one:

1. Go to the [Auth0 Dashboard](https://manage.auth0.com/#/), select your tenant name and select **Create Tenant**.

   <Frame>
     <img alt="Dashboard Tenant Drop-Down Menu Create Tenant" />
   </Frame>
2. Enter a **Domain**, select a **Region**, and click **Create**.

## Configure IdP tenant

Configure your secondary tenant as an IdP, and register an application to represent your SP tenant.

1. Switch to your IdP tenant. Open the tenant menu, select **Switch Tenant**, and then select your IdP tenant.
2. Navigate to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and select **Create Application**.
3. Enter a name for the application, such as `my-auth0-idp`, select **Regular Web Application** for the application type, and then select **Create**.
4. Go to the bottom of the **Settings** page, and select **Show Advanced Settings**.
5. Switch to the **Certificates** view, then select **Download Certificate**, and choose **PEM**. The certificate will download. You will use this certificate when you configure the SP tenant.
6. Switch to the **Endpoints** view, locate **SAML Protocol URL**, and copy its contents. You will use this URL when you configure the SP tenant.

## Create user to test SAML sequence

1. Go to [Dashboard > User Management > Users](https://manage.auth0.com/#/users) and select **Create User**.
2. Enter an email address for your test user. The domain name should match the service provider tenant email domain that you will configure next. For example, if your user is `john.doe@exampleco.com`, you should enter `exampleco.com` for the email domain.
3. Enter a password for the test user.
4. Use the default value for **Connection**.
5. Select **Create**.

## Configure service provider tenant

Configure the SP tenant to communicate with the IdP tenant for SSO using the SAML protocol.

1. Switch to your SP tenant. Open the tenant menu, select **Switch Tenant**, and then select your SP tenant.
2. Go to [Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise) and select **SAML**.
3. Select **Create Connection**.
4. Enter the following information, and select **Create**:

<table>
  <thead>
    <tr>
      <th>Setting</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Connection Name</td>
      <td>Enter any name, such as <code>SAML-Auth0-IDP</code>.</td>
    </tr>

    <tr>
      <td>Sign In URL</td>
      <td>Enter the SAML Protocol URL value that you copied in above.</td>
    </tr>

    <tr>
      <td>Sign Out URL</td>
      <td>Enter the same URL as for the Sign In URL above.</td>
    </tr>

    <tr>
      <td>X509 Signing Certificate</td>
      <td>Click on the red <strong>UPLOAD CERTIFICATE...</strong> button and select the <code>.pem</code> file you downloaded above.</td>
    </tr>
  </tbody>
</table>

5. Switch to the **Setup** view to see the metadata associated with the tenant. Copy and save the URL.
6. Open a new browser tab and navigate to the URL you copied previously. (If you are logged in on the Auth0 Docs site, the settings will pre-populate with the correct values.)

   1. Locate **Entity ID**, and then copy and save its contents. It will look like: `urn:auth0:{yourTenant}:{yourConnectionName}`. Replace `{yourConnectionName}` with the name of the connection you created for your IdP tenant.
   2. Locate **Metadata**, and copy and save the provided URL. It will look like: `https://{yourDomain}/samlp/metadata?connection={yourConnectionName}`. Replace `{yourConnectionName}` with the name of the connection you created for your IdP tenant.
   3. Go to the URL you previously copied to display the metadata for this connection in the SP tenant. Alternatively, your browser may prompt you to save the metadata file.
   4. Locate the row that starts with **AssertionConsumerService**, and copy and save the value of the **Location** field. It will be a URL of the form: `https://{yourDomain}/login/callback?connection={yourConnectionName}`. This is the URL on your SP tenant that receives the SAML assertion from the IdP tenant. In the next section, you will provide this URL to the IdP tenant so it knows where to send the SAML assertion.

## Add service provider metadata to IdP

Add information about the SP tenant to the IdP tenant so it knows how to receive and respond to SAML authentication requests.

1. Switch to your IdP tenant. Open the tenant menu, select **Switch Tenant**, and then select your IdP tenant.
2. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and select the name of the IdP application you created previously.
3. Switch to the **Addons** view.
4. Select **SAML2 Web App** to view its options, and locate the **Application Callback URL**. Paste the **AssertionConsumerService URL** that you copied previously.
5. In the **Settings** code block, locate the `audience` key, and uncomment it, then remove the comma from the end of the line and replace the original value (`urn:foo`) with the **Entity ID** value you copied previously (including the connection name you created in Step 4 when you configured your service provider tenant).
   The new line should look like: "`audience":"urn:auth0:{yourTenant}:{yourConnectionName}"`.
6. Select **Enable**.

## Test IdP

1. In the same window, scroll up, and select **Debug**. A login screen will appear.
2. Log in with the credentials of the test user you created above. If your configuration is correct, it will display "It works!", and the encoded and decoded SAML response that would be sent to the IdP.
3. Check the decoded SAML response, locate `<saml:Audience>`, and make sure it matches the **Entity ID** you entered on the previous screen.
4. Select **Close this window**.

## Create application to test SAML connection

Create a simple application to test the SAML connection you created.

1. Switch to your SP tenant. Open the tenant menu, select **Switch Tenant**, and then select your SP tenant.
2. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and select **Create Application**.
3. Enter an application name, select **Regular Web Application** as the application type, and then select **Create**.
4. Copy and save the **Domain** and **Client ID** values.
5. Locate the **Allowed Callback URLs** field, and enter `http://jwt.io`.
   This is the list of allowed callback URLs to which users will be redirected after authentication. The URL(s) entered here must match the callback URL in the HTML code created in the next step. Normally you would enter a URL for your application, but to keep this example simple, the test user will be sent to the Auth0 JWT online tool, which provides some information about the JSON Web Token (JWT) returned at the end of the authentication sequence.
6. Select **Save Changes**.
7. Switch to the **Connections** view, locate the SAML connection you created under the **Enterprise** section, and enable it.

## Test connection between service and identity provider

Test to ensure the SAML configuration between your SP tenant and IdP tenant works.

1. Go to [Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise) and select **SAML**.
2. Locate the SAML connection you created, and select the **Try** arrow icon. Since you previously logged in while testing this connection, you should be sent directly to the "It works!" screen. If you see the login screen, log in using your test user's credentials.

If the configuration is set up correctly, you will see "It works!", and the page will display the contents of the SAML authentication assertion sent by the IdP tenant to the Auth0 tenant.

If it is not configured correctly, double-check your steps. If you are still having trouble, consult the troubleshooting section at the end of this document.

## Create a web page for test application

Create a simple web page that invokes the Lock widget triggering the SAML login sequence.

1. Create an HTML page, and insert the following HTML and JavaScript code. Replace `{yourClientId}` and `{yourDomain}` with the actual values of the application you registered above. (If you did not note those values, you can find them in the **Application Settings** on your SP tenant.)

   ```html lines expandable theme={null}
   <!DOCTYPE html>
   <html lang="en">
   <body>
     <button type="button" onclick="login()">Log in</button>
     <script src="https://cdn.auth0.com/js/auth0/9.19.0/auth0.min.js"></script>
     <script>
       var auth0 = new auth0.WebAuth({
         domain: '{yourDomain}',
         clientID: '{yourClientId}',
         redirectUri: 'URL_TO_THIS_PAGE',
         responseType: 'token id_token',
         scope: 'openid email profile'
       })

       auth0.parseHash(function(err, data) {
         if (err) {
           console.log(err)
         }

         if (data) {
           console.log('Login successful!')
           console.log(data)
         }
       })

       window.login = function() {
         auth0.authorize()
       }
     </script>

   </body>
   </html>
   ```

2. You can also replace `audience` with the appropriate value for your application, but for the purposes of this test, a placeholder is sufficient. If you do specify the `audience` parameter, ensure that it matches an identifier of an existing API you have configured in Auth0.

3. Save the HTML file where you can access it from a browser.

## Test sample application

Test the sample HTML application that uses the Auth0 SAML connection you created in your SP tenant to perform SSO authentication against the IdP tenant.

1. Open the HTML file you created above with a browser. You should see a login button.
2. Click **Login**. You should see the Lock widget with one option. If you have other connections turned on for your application, the screen may look different. If you are prompted for an email address, make sure the email address you enter has the same domain name as the domain you entered in the **Settings** view for the application in the first tenant.
3. Click the blue button, which may say **saml** or **ACCESS**. Whether you are prompted for credentials or immediately redirected to the callback URL depends on whether you still have an active session.

## Troubleshoot test scenario

* Clear your browser history and cookies each time before you test. If you do not, the browser may not pick up the latest version of your HTML page, or it may have stale cookies that affect execution.
* Capture an HTTP trace of the interaction. Many tools will capture the HTTP traffic from your browser for analysis.

  * Search the internet for "HTTP Trace" to find and install a tool.
  * Capture the login sequence from start to finish and analyze the trace. Track the sequence of GETs to see how far in the expected sequence you get. You should see a redirect from your original site to the SP tenant and then to the IdP tenant, a POST of credentials if you had to log in, then a redirect back to the callback URL or the SP tenant, and then a redirect to the **Callback URL** specified in your application.
* Ensure that cookies and JavaScript are enabled for your browser.
* Ensure that the **Callback URL** specified in the HTML file is also listed in the **Allowed Callback URLs** field for your application. To do so, go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and select the name of your application, then locate **Allowed Callback URLs**.
* Use the [http://samltool.io](http://samltool.io) tool to decode a SAML assertion.

## Learn more

* [SAML Single Sign-On Integrations](/docs/authenticate/protocols/saml/saml-sso-integrations)
* [Customize SAML Assertions](/docs/authenticate/protocols/saml/saml-configuration/customize-saml-assertions)
* [Deprovision Users in SAML Integrations](/docs/authenticate/protocols/saml/saml-configuration/deprovision-users-in-saml-integrations)
* [SAML Identity Provider Configuration Settings](/docs/authenticate/protocols/saml/saml-identity-provider-configuration-settings)
* [Sign and Encrypt SAML Requests](/docs/authenticate/protocols/saml/saml-sso-integrations/sign-and-encrypt-saml-requests)
* [Troubleshoot SAML Configurations](/docs/troubleshoot/authentication-issues/troubleshoot-saml-configurations)


# Customize SAML Assertions
Source: https://auth0.com/docs/authenticate/protocols/saml/saml-configuration/customize-saml-assertions

Describes how to customize SAML assertions and the SAML and WS-Fed protocol parameters.

You can customize your <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> assertions as well as the SAML and WS-Federation protocol parameters.

## Auth0 as identity provider

Customize SAML assertions when Auth0 acts as the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> by configuring the addon in the Dashboard or by using rules.

### Use the Dashboard

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications/\{yourClientId}/addons) and select the name of the application to view.
2. Select the **Addons** tab.
3. Enable **SAML2 Web App** toggle to view settings and options.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Settings Tab" />
   </Frame>
4. In the **Settings** tab, you can make several types of customizations, such as:

   * Specify an audience other than the default issuer of the SAML request.
   * Specify a recipient.
   * Map profile attributes to specific attribute statements.
   * Change the signature or digest algorithm.
   * Specify whether just the assertion or the entire response should be signed.

### Use Actions

You can use Actions to add more extensive or dynamic customizations to the SAML response. Customizations made in Actions override customizations done using the **Application Addons** view in the Dashboard.

The `api.samlResponse` object is used to override default SAML attributes or add new attributes.

#### Example: Changing the SAML token lifetime and use UPN as NameID

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
	api.samlResponse.setLifetimeInSeconds(36000);
	if (event.user.upn) {
		api.samlResponse.setAttribute('http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier', 'upn');
	}
};
```

#### Example: Include user\_metadata attributes in an assertion

```js lines theme={null}
exports.onExecutePostLogin = (event, api) => {
	event.user.user_metadata = event.user.user_metadata || {};
	event.user.user_metadata.color = 'purple';
	api.samlResponse.setAttribute('http://schemas.xmlsoap.org/ws/2005/05/identity/claims/color', event.user.user_metadata.color);
};
```

## SAML assertion attributes

The following is a list of customization attributes for SAML assertions.

<table>
  <thead>
    <tr>
      <th><strong>Attribute</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>audience</code></td>
      <td>string</td>
      <td>Audience of the SAML assertion. Default is issuer on SAMLRequest.</td>
    </tr>

    <tr>
      <td><code>recipient</code></td>
      <td>string</td>
      <td>Recipient of the SAML assertion (<code>SubjectConfirmationData</code>). Default is <code>AssertionConsumerUrl</code> on SAMLRequest or callback URL if no SAMLRequest was sent.</td>
    </tr>

    <tr>
      <td><code>issuer</code></td>
      <td>string</td>
      <td>Unique identifier of the SAML identity provider, formatted as a URL.</td>
    </tr>

    <tr>
      <td><code>mappings</code></td>
      <td>object</td>
      <td>Mappings between Auth0 profile and the output attributes on the SAML assertion. Default mapping is shown above.</td>
    </tr>

    <tr>
      <td><code>createUpnClaim</code></td>
      <td>boolean</td>
      <td>Whether or not a UPN claim should be created. Default is <code>true</code>.</td>
    </tr>

    <tr>
      <td><code>passthroughClaimsWithNoMapping</code></td>
      <td>boolean</td>
      <td>If <code>true</code> (default), for each claim that is not mapped to the common profile, Auth0  passes through those in the output assertion. If <code>false</code>, those claims won't be mapped.</td>
    </tr>

    <tr>
      <td><code>mapUnknownClaimsAsIs</code></td>
      <td>boolean</td>
      <td>If <code>passthroughClaimsWithNoMapping</code> is <code>true</code> and this is <code>false</code> (default), for each claim not mapped to the common profile Auth0 adds a prefix <code>[http://schema.auth0.com](http://schema.auth0.com)</code>. If <code>true</code> it will pass through the claim as-is.</td>
    </tr>

    <tr>
      <td><code>mapIdentities</code></td>
      <td>boolean</td>
      <td>If <code>true</code> (default), it adds more information in the token such as the provider (Google, ADFS, AD, etc.) and the access token, if available.</td>
    </tr>

    <tr>
      <td><code>signatureAlgorithm</code></td>
      <td>string</td>
      <td>Signature algorithm to sign the SAML assertion or response. Default is <code>rsa-sha1</code>.</td>
    </tr>

    <tr>
      <td><code>digestAlgorithm</code></td>
      <td>string</td>
      <td>Digest algorithm to calculate digest of the SAML assertion or response. Default is <code>sha1</code>.</td>
    </tr>

    <tr>
      <td><code>destination</code></td>
      <td>object</td>
      <td>Destination of the SAML response. If not specified, it will be <code>AssertionConsumerUrl</code> of SAMLRequest or callback URL if there was no SAMLRequest.</td>
    </tr>

    <tr>
      <td><code>lifetimeInSeconds</code></td>
      <td>integer</td>
      <td>Expiration of the token. Default is <code>3600</code> seconds (1 hour).</td>
    </tr>

    <tr>
      <td><code>signResponse</code></td>
      <td>boolean</td>
      <td>Whether or not the SAML response should be signed. By default the SAML assertion will be signed, but not the SAML response. If <code>true</code>, SAML Response will be signed instead of SAML assertion.</td>
    </tr>

    <tr>
      <td><code>nameIdentifierFormat</code></td>
      <td>string</td>
      <td>Default is <code>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</code>.</td>
    </tr>

    <tr>
      <td><code>nameIdentifierProbes</code></td>
      <td>array</td>
      <td>Auth0 will try each of the attributes of this array in order. If one of them has a value, it will use that for the <code>Subject/NameID</code>. The order is: <code>[http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier) (mapped from user\_id)</code>, <code>[http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress) (mapped from email)</code>, <code>[http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name)</code> (mapped from name).</td>
    </tr>

    <tr>
      <td><code>authnContextClassRef</code></td>
      <td>string</td>
      <td>Default is <code>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</code>.</td>
    </tr>

    <tr>
      <td><code>typedAttributes</code></td>
      <td>boolean</td>
      <td>Default is <code>true</code>. When set to <code>true</code>, we infer the <code>xs:type</code> of the element. Types are <code>xs:string</code>, <code>xs:boolean</code>, <code>xs:double </code>and <code>xs:anyType</code>. When set to <code>false</code> all <code>xs:type</code> are <code>xs:anyType</code>.</td>
    </tr>

    <tr>
      <td><code>includeAttributeNameFormat</code></td>
      <td>boolean</td>
      <td>Default is <code>true</code>. When set to <code>true</code>, we infer the <code>NameFormat</code> based on the attribute name. <code>NameFormat</code> values are <code>urn:oasis:names:tc:SAML:2.0:attrname-format:uri</code>, <code>urn:oasis:names:tc:SAML:2.0:attrname-format:basic</code> and <code>urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified</code>. If set to <code>false</code>, the attribute <code>NameFormat</code> is not set in the assertion.</td>
    </tr>

    <tr>
      <td><code>logout</code></td>
      <td>object</td>
      <td>Controls SAML logout. It can contain two properties:<code>callback</code> (string) that contains the service provider (client application) Single Logout Service URL, where Auth0 will send logout requests and responses, and <code>slo\_enabled</code>(boolean) that controls whether Auth0 should notify service providers of session termination. The default value is<code>true</code> (notify service providers).</td>
    </tr>

    <tr>
      <td><code>binding</code></td>
      <td>string</td>
      <td>Optionally indicates the protocol binding used for SAML logout responses. By default Auth0 uses <code>HTTP-POST</code>, but you can switch to <code>HTTP-Redirect</code> by setting <code>"binding"</code> to <code>"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"</code>.</td>
    </tr>

    <tr>
      <td><code>signingCert</code></td>
      <td>string</td>
      <td>Optionally indicates the public key certificate used to validate SAML requests. If set, SAML requests will be required to be signed. A sample value would be <code>"-----BEGIN CERTIFICATE-----\nMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV\n\[..all the other lines..]-----END CERTIFICATE-----\n"</code>.</td>
    </tr>
  </tbody>
</table>

## Learn more

* [Troubleshoot SAML Configurations](/docs/troubleshoot/authentication-issues/troubleshoot-saml-configurations)
* [Troubleshoot SAML Errors](/docs/troubleshoot/authentication-issues/saml-errors)
* [Configure SAML Identity Provider-Initiated Single Sign-On](/docs/authenticate/protocols/saml/saml-sso-integrations/identity-provider-initiated-single-sign-on)


# Deprovision Users in SAML Integrations
Source: https://auth0.com/docs/authenticate/protocols/saml/saml-configuration/deprovision-users-in-saml-integrations

Learn how to deprovision users of your SAML integration.

If you need to remove application access for users, you'll need to deprovision them at a minimum with the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>. Depending on the identity provider, the steps required to deprovision a user account vary. Check with your provider for further instructions.

Once a user's account is removed or disabled with the identity provider, the user will not be able to log in.

You may also want to remove the Auth0 user accounts for those who've been deprovisioned if Auth0 is the service provider or if your app integrates with Auth0. Regardless of whether Auth0 is the identity or service provider, you can remove users using the [Dashboard](https://manage.auth0.com/#/users) or using the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## Learn more

* [Remove Permissions from Users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/remove-permissions-from-users)
* [Troubleshoot SAML Configurations](/docs/troubleshoot/authentication-issues/troubleshoot-saml-configurations)
* [Troubleshoot SAML Errors](/docs/troubleshoot/authentication-issues/saml-errors)


# Map SAML Attributes with Auth0 as IdP/SAML Add-on
Source: https://auth0.com/docs/authenticate/protocols/saml/saml-configuration/saml-attribute-mapping-examples

Provides examples how to map SAML attributes when Auth0 is the identity provider.

When Auth0 is the <Tooltip href="/docs/glossary?term=IdP">IdP</Tooltip>, you can map user attributes through Auth0's SAML2 add-on. Errors could occur if attributes are misconfigured. For example, a user enters username and password successfully, but fails to sign in to the application even though logs in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> show successful login events. Or, your application is missing user information such as name or email.

## Use cases

The user profile below is the example for the following scenarios.

```javascript lines theme={null}
//SAMPLE IdP User Profile
{
   "created_at": "2021-06-21T13:26:08.579Z",
   "email": "testuser@example.com",
...
   "fav_genre": "fiction",
   "user_metadata": {
       "fav_streaming_service": "hulu"
   }
...
}
```

#### No mappings object

When using the SAML2 add-on, an empty mappings object generates by default.

In this example, `fav_genre` and `user_metadata.fav_streaming_service` are undefined but can be customized and mapped to the <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> Response populated by Auth0.

In the example below, `"fav_genre": "fiction"` gets mapped to the  [http://schemas.auth0.com/fav\_genre](http://schemas.auth0.com/fav_food) attribute in the SAML Response with the `fiction` value while`"user_metadata": {"fav_streaming_service": "hulu"}` does not appear in the SAML response at all.

Resulting SAML Response that the IdP sends:

```xml lines theme={null}
<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="_e30cb5f29249a82846eb" InResponseTo="_e33996d83f953ce46225185b3a1c0ad8" Version="2.0" IssueInstant="2021-11-03T21:34:42.493Z" Destination="https://example-dev-tenant.us.auth0.com/login/callback">
...
       <saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
           <saml:Attribute Name="http://schemas.auth0.com/fav_genre" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
               <saml:AttributeValue xsi:type="xs:string">
                   fiction
               </saml:AttributeValue>
           </saml:Attribute>
...
       </saml:AttributeStatement>
   </saml:Assertion>
</samlp:Response>
```

#### Standard mappings example

In the earlier example, not customizing the mappings object resulted in a [http://schemas.auth0.com/fav\_genre](http://schemas.auth0.com/fav_food) attribute in the SAML Response with the `"fiction"` value.

Next, map the attributes in the Mappings Object of the SAML2 add-on settings to account for that.

After doing so, notice how the `"fiction"` value is the same in the SAML Response, but the attribute name in the SAML Response has been changed from the default [http://schemas.auth0.com/fav\_fiction](http://schemas.auth0.com/fav_food) to [http://schemas.auth0.com/books](http://schemas.auth0.com/dinner).

Configuring the SAML2 add-on mappings object:

```json lines theme={null}
"mappings": {
   "fav_genre": "http://schemas.auth0.com/books"
 }
```

This mapping results in the following response:

```xml lines theme={null}
<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="_e30cb5f29249a82846eb" InResponseTo="_e33996d83f953ce46225185b3a1c0ad8" Version="2.0" IssueInstant="2021-11-03T21:34:42.493Z" Destination="https://example-dev-tenant.us.auth0.com/login/callback">
...
       <saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
           <saml:Attribute Name="http://schemas.auth0.com/books" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
               <saml:AttributeValue xsi:type="xs:string">
                   fiction
               </saml:AttributeValue>
           </saml:Attribute>
...
       </saml:AttributeStatement>
   </saml:Assertion>
</samlp:Response>
```

#### Mapping the same value to multiple attributes

There may be scenarios where mapping the SAML Response to multiple attributes with the same value is required.

In this case, there is the option to map the same value from the user profile to multiple attributes in the SAML Response.

How to configure the SAML2 add-on mappings object:

```json lines theme={null}
"mappings": {
   "fav_genre": [
     "http://schemas.auth0.com/movies",
     "http://schemas.auth0.com/books",
     "http://schemas.auth0.com/television"
   ]
 }
```

This mapping results in the following response:

```xml lines theme={null}
<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="_e30cb5f29249a82846eb" InResponseTo="_e33996d83f953ce46225185b3a1c0ad8" Version="2.0" IssueInstant="2021-11-03T21:34:42.493Z" Destination="https://example-dev-tenant.us.auth0.com/login/callback">
...
       <saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
           <saml:Attribute Name="http://schemas.auth0.com/movies" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
               <saml:AttributeValue xsi:type="xs:string">
                   fiction
               </saml:AttributeValue>
           </saml:Attribute>
           <saml:Attribute Name="http://schemas.auth0.com/books" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
               <saml:AttributeValue xsi:type="xs:string">
                   fiction
               </saml:AttributeValue>
           </saml:Attribute>
           <saml:Attribute Name="http://schemas.auth0.com/television" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
               <saml:AttributeValue xsi:type="xs:string">
                   fiction
               </saml:AttributeValue>
           </saml:Attribute>
...
       </saml:AttributeStatement>
   </saml:Assertion>
</samlp:Response>
```


# SAML Identity Provider Configuration Settings
Source: https://auth0.com/docs/authenticate/protocols/saml/saml-identity-provider-configuration-settings

Describes the SAML identity provider configuration settings.

## Common settings

These are the settings used to configure a <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> (IdP).

<Callout icon="file-lines">
  If you have configured a [Custom Domain](/docs/customize/custom-domains), you must use your custom domain CNAME in place of the Auth0 domain. To learn more, read [Configure Features to Use Custom Domains](/docs/customize/custom-domains/configure-features-to-use-custom-domains#configure-saml-identity-providers).
</Callout>

### post-back URL

When using IdP-Initiated <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip>, make sure to include the connection parameter in the post-back URL:

<AuthCodeBlock />

If you are using the [Organizations](/docs/manage-users/organizations) feature, you can optionally include an organization parameter containing the organization ID of the desired organization:

<AuthCodeBlock />

<Callout icon="file-lines">
  In order for users to successfully log-in using this method, the connection must be enabled for the Organization. Additionally, you must either configure [auto-membership](/docs/manage-users/organizations/configure-organizations/grant-just-in-time-membership) for the enabled connection or ensure users have membership for the Organization.
</Callout>

### Entity ID

The ID of the service provider is:

```http lines theme={null}
urn:auth0:{yourTenant}:{yourConnectionName}
```

You can create a custom Entity ID using the property `connection.options.entityId`. To learn more, read [Specify a Custom Entity ID](/docs/authenticate/identity-providers/enterprise-identity-providers/saml#specify-a-custom-entity-id).

You can obtain the custom Entity ID value using the Get a Connection endpoint:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/connections/%7ByourConnectionID%7D' \
    --header 'authorization: Bearer {yourAccessToken}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/connections/%7ByourConnectionID%7D");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer {yourAccessToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/connections/%7ByourConnectionID%7D"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer {yourAccessToken}")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/connections/%7ByourConnectionID%7D")
    .header("authorization", "Bearer {yourAccessToken}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/connections/%7ByourConnectionID%7D',
    headers: {authorization: 'Bearer {yourAccessToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourAccessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/connections/%7ByourConnectionID%7D"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/connections/%7ByourConnectionID%7D",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourAccessToken}"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {yourAccessToken}" }

  conn.request("GET", "/{yourDomain}/api/v2/connections/%7ByourConnectionID%7D", headers=headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/connections/%7ByourConnectionID%7D")

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

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer {yourAccessToken}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourAccessToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/connections/%7ByourConnectionID%7D")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

Replace the `ACCESS_TOKEN` header value, with a Management APIv2 <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>.

### SAML Request Binding

Also called the **Protocol Binding**, is sent to the IdP from Auth0. If possible, dynamically set the value based on `connection.options.protocolBinding`:

<table>
  <thead>
    <tr>
      <th><code>connection.options.protocolBinding</code> value</th>
      <th>SAML Request Binding value</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Empty value ("") or not present</td>
      <td><code>HTTP-Redirect</code></td>
    </tr>

    <tr>
      <td><code>urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect</code></td>
      <td><code>HTTP-Redirect</code></td>
    </tr>

    <tr>
      <td><code>urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST</code></td>
      <td><code>HTTP-POST</code></td>
    </tr>
  </tbody>
</table>

If dynamically setting the value isn't possible, then set as either `HTTP-Redirect` (default) or `HTTP-Post` if you selected this option in **Protocol Binding**.

### SAML Response Binding

How the SAML token is received by Auth0 from IdP, set as `HTTP-Post`.

### NameID format

Unspecified.

### SAML assertion and response

The SAML assertion, and the SAML response can be individually or simultaneously signed.

### SingleLogout service URL

This is where the SAML identity provider will send logout requests and responses:

<AuthCodeBlock />

SAML logout requests must be signed by the identity provider.

## Signed assertions

Use the following links to obtain the public key in different formats:

* <AuthLink href="https://{yourDomain}/cer?cert=connection">CER</AuthLink>
* <AuthLink href="https://{yourDomain}/pem?cert=connection">PEM</AuthLink>
* <AuthLink href="https://{yourDomain}/rawpem?cert=connection">raw PEM</AuthLink>
* <AuthLink href="https://{yourDomain}/pb7?cert=connection">PKCS#7</AuthLink>
* <AuthLink href="https://{yourDomain}/fingerprint?cert=connection">Fingerprint</AuthLink>

Download the certificate in the format requested by the IdP.

### IdP-initiated Single Sign-on

To learn about IdP-initiated SSO, read [Configure SAML IdP-Initiated Single Sign-On](/docs/authenticate/protocols/saml/saml-sso-integrations/identity-provider-initiated-single-sign-on).

## Metadata

Some SAML identity providers can accept importing metadata directly with all the required information. You can access the metadata for your connection in Auth0 here:

<AuthCodeBlock />

## Organizations

Use the ACS URL for your organization in the federated IdP to start the Organizations login flow.

<AuthCodeBlock />

## Learn more

* [Locate the Connection ID or Name](/docs/authenticate/identity-providers/locate-the-connection-id)
* [Customize SAML Assertions](/docs/authenticate/protocols/saml/saml-configuration/customize-saml-assertions)
* [Troubleshoot SAML Configurations](/docs/troubleshoot/authentication-issues/troubleshoot-saml-configurations)


# SAML Single Sign-On Integrations
Source: https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations

Describes the Security Assertion Markup Language (SAML) for single sign-on (SSO) integration options.

When you implement <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> <Tooltip href="/docs/glossary?term=single+sign-on">single sign-on</Tooltip> (SSO), it's important to consider:

* Which system(s) will serve as the authoritative source for user profile information if there's ever a conflict between two or more sources.
* What user profile attributes each application needs.
* How user profile information will be distributed to the systems that need it.

## Identity provider-initiated SSO

You typically set up a SAML federation by configuring SSO initiated by the service provider. The service provider returns a browser redirect so that the user authenticates using the <Tooltip href="/docs/glossary?term=IdP">IdP</Tooltip>. After authentication, the browser redirects the user back to the service provider with a SAML assertion containing information about the authentication status. This is commonly used for consumer-facing scenarios.

You can also configure the IdP to initiate SSO instead of the service provider. In this scenario, the user invokes a URL on the IdP and is prompted to authenticate, then is redirected to the service provider with a SAML assertion. This is commonly used in enterprise scenarios. To learn more, read [Configure SAML Identity Provider-Initiated Single Sign-On](/docs/authenticate/protocols/saml/saml-sso-integrations/identity-provider-initiated-single-sign-on).

## Auth0 as identity provider for SAML SSO integrations

Some of the following integrations make use of the Auth0 SAML2 Web App addon.

* [Amazon Web Services](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-aws)
* [Atlassian](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-atlassian)
* [Cisco-WebEx](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-cisco-webex)
* [DataDog](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-datadog)
* [Egencia](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-egencia)
* [Freshdesk](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-freshdesk)
* [GitHub Enterprise Cloud](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-github-enterprise-server)
* [GitHub Enterprise Server](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-github-enterprise-server)
* [Google Workspace](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-idp-for-google-g-suite)
* [Heroku](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-heroku)
* [Hosted Graphite](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-hosted-graphite)
* [Litmos](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-litmos)
* [Oracle Eloqua Marketing Cloud](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-addon-eloqua)
* [PluralSight](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-pluralsight)
* [Sprout Video](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-sprout-video)
* [Tableau Online](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-tableau-online)
* [Tableau Server](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-tableau-server)
* [Workday](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-workday)
* [Workpath](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-workpath)

To learn more, read [Enable SAML2 Web App Addon](/docs/authenticate/protocols/saml/saml-sso-integrations/enable-saml2-web-app-addon).

## Other SAML identity provider SSO integrations

Auth0 provides SSO integrations for using the following services as identity providers:

* [ADFS](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-adfs-saml-connections)
* [Okta](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-okta-as-saml-identity-provider)
* [OneLogin](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-onelogin-as-saml-identity-provider)
* [PingFederate](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-pingfederate-as-saml-identity-provider)
* [Salesforce](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-salesforce-as-saml-identity-provider)
* [SiteMinder](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-siteminder-as-saml-identity-provider)
* [SSOCircle](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-ssocircle-as-saml-identity-provider)

## Special scenarios

Once you've set up a basic SAML integration, there are a number of additional requirements you might need to implement so that your integration reflects your needs and requirements.

You have set up a connection or an application and that you're altering specific settings for an existing SAML integration, not configuring an integration from scratch.

To learn more about special scenarios, read [Configure Identity Provider-Initiated Single Sign-On](/docs/authenticate/protocols/saml/saml-sso-integrations/identity-provider-initiated-single-sign-on) and [Sign and Encrypt SAML Requests](/docs/authenticate/protocols/saml/saml-sso-integrations/sign-and-encrypt-saml-requests).

## Learn more

* [SAML Identity Provider Configuration Settings](/docs/authenticate/protocols/saml/saml-identity-provider-configuration-settings)
* [Customize SAML Assertions](/docs/authenticate/protocols/saml/saml-configuration/customize-saml-assertions)
* [Configure SAML Identity Provider-Initiated Single Sign-On](/docs/authenticate/protocols/saml/saml-sso-integrations/identity-provider-initiated-single-sign-on)
* [Sign and Encrypt SAML Requests](/docs/authenticate/protocols/saml/saml-sso-integrations/sign-and-encrypt-saml-requests)
* [Troubleshoot SAML Configurations](/docs/troubleshoot/authentication-issues/troubleshoot-saml-configurations)


# Configure Auth0 as SAML Service Provider
Source: https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider

Describes how to configure Auth0 to serve as a service provider in a SAML federation.

To configure Auth0 as the service provider (SP) in a <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> federation, you will need to create an Enterprise connection in Auth0 and then update your SAML <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> (IdP) with the connection's metadata.

Auth0 supports using Auth0 as the SP in configurations that conform to the SAML 1.1 or SAML 2.0 protocol.

## Get metadata and certificate from the IdP

You'll need to collect some configuration metadata from the IdP to create a connection in Auth0:

<table>
  <thead>
    <tr>
      <th><strong>Field</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Sign In URL</td>
      <td>The URL where SAML authentication requests are sent. This is also called the single sign-on (SSO) endpoint.</td>
    </tr>

    <tr>
      <td>Sign Out URL</td>
      <td>The URL where SAML logout requests are sent. This is also called the single logout (SLO) endpoint.</td>
    </tr>

    <tr>
      <td>X509 Signing Certificate</td>
      <td>The public-key certificate required by the SP to validate the signature of the authentication assertions that have been digitally signed by the IdP. Auth0 accepts the .pem and .cer formats.</td>
    </tr>
  </tbody>
</table>

## Create SAML Enterprise connection in Auth0

You can create a SAML Enterprise connection in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or with the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>:

<Tabs>
  <Tab title="Dashboard">
    1. Go to [**Dashboard > Authentication > Enterprise**](https://manage.auth0.com/#/connections/enterprise/samlp) and select **SAML**.
    2. Select **Create Connection**.
    3. Configure the following settings:

    <table>
      <thead>
        <tr>
          <th><strong>Setting</strong></th>
          <th><strong>Description</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Connection Name</td>
          <td>Enter a connection name such as <code>SAML-SP</code>.</td>
        </tr>

        <tr>
          <td>Sign In URL</td>
          <td>Enter the <strong>Sign In URL</strong> that you obtained from the IdP.</td>
        </tr>

        <tr>
          <td>X509 Signing Certificate</td>
          <td>Upload the X509 Signing Certificate file (in <code>.pem</code> or <code>.cer</code> format) that you obtained from the IdP.</td>
        </tr>

        <tr>
          <td>Enable Sign Out</td>
          <td>Enable the <strong>Sign Out URL</strong> field.</td>
        </tr>

        <tr>
          <td>Sign Out URL</td>
          <td>Enter the <strong>Sign Out URL</strong> obtained from the IdP.</td>
        </tr>

        <tr>
          <td>User ID Attribute</td>
          <td>Enter the attribute in the SAML token that will be mapped to the <code>user\_id</code> property in Auth0. If not set, then the <code>user\_id</code> will be retrieved from the following (in listed order):<ul><li><code>[http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier)</code></li><li><code>[http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn)</code></li><li><code>[http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name)</code></li></ul></td>
        </tr>

        <tr>
          <td>Debug Mode</td>
          <td>Enable <strong>Debug Mode</strong> for more verbose logging.</td>
        </tr>

        <tr>
          <td>Sign Request</td>
          <td>Enable signed SAML authentication requests.</td>
        </tr>

        <tr>
          <td>Sign Request Algorithm</td>
          <td>From the dropdown menu, select the hash algorithm to use.</td>
        </tr>

        <tr>
          <td>Sign Request Algorithm Digest</td>
          <td>From the dropdown menu, select the algorithm to use to check the validity of the assertion.</td>
        </tr>

        <tr>
          <td>Protocol Binding</td>
          <td>From the dropdown menu, select one of the following options:<ul><li><code>HTTP-Redirect</code>: Enables messages to be transmitted within URL parameters.</li><li><code>HTTP-POST</code>: Enables messages to be transmitted within an HTML form.</li></ul></td>
        </tr>

        <tr>
          <td>Sync user profile attributes at each login</td>
          <td>Enable syncing user profile attributes during each login.</td>
        </tr>
      </tbody>
    </table>

    4. Select **Create**.
  </Tab>

  <Tab title="Management API">
    The Auth0 Management API [Create a Connection](https://auth0.com/docs/api/management/v2#!/Connections/post_connections) endpoint supports the following properties on the `options` object when creating a SAML connection:

    <table>
      <thead>
        <tr>
          <th><strong>Field</strong></th>
          <th><strong>Type</strong></th>
          <th><strong>Required?</strong></th>
          <th><strong>Description</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>signInEndpoint</code></td>
          <td>String</td>
          <td>Required</td>
          <td>The <strong>Sign In URL</strong> of the IdP.</td>
        </tr>

        <tr>
          <td><code>signingCert</code></td>
          <td>String</td>
          <td>Required</td>
          <td>Contents of the X509 signing certificate (in <code>.pem</code> or <code>.cer</code> format) encoded in Base64.</td>
        </tr>

        <tr>
          <td><code>debug</code></td>
          <td>Boolean</td>
          <td>Optional</td>
          <td>Toggles <strong>Debug Mode</strong>, which includes more verbose logging during the authentication process. Set to <code>false</code> for connections used in production environments.</td>
        </tr>

        <tr>
          <td><code>destinationUrl</code></td>
          <td>String</td>
          <td>Optional</td>
          <td>The URL where Auth0 will send SAML authentication requests. Only required when using a proxy gateway.</td>
        </tr>

        <tr>
          <td><code>digestAlgorithm</code></td>
          <td>String</td>
          <td>Optional</td>
          <td>The algorithm used to encrypt the digest element of authentication requests.<br /><br />Accepted values are <code>sha256</code> and <code>sha1</code>.</td>
        </tr>

        <tr>
          <td><code>disableSignout</code></td>
          <td>Boolean</td>
          <td>Optional</td>
          <td>Toggles the <strong>Sign Out URL</strong>. If <code>false</code>, you must provide a <strong>Sign Out URL</strong> to accept logout requests. If <code>true</code>, logout requests will be sent to the <strong>Sign In URL</strong>.</td>
        </tr>

        <tr>
          <td><code>fieldsMap</code></td>
          <td>Object</td>
          <td>Optional</td>
          <td>Contains attribute mappings to be applied to the authentication responses from the IdP.<br /><br />For example: <code>"email": "[http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier)"</code>.</td>
        </tr>

        <tr>
          <td><code>idpinitiated</code></td>
          <td>Object</td>
          <td>Optional</td>
          <td>Contains options for IdP-Initiated SSO:<ul><li><code>enabled</code>: Boolean. Toggles IdP-Initiated SSO.</li><li><code>client\_id</code>: String. The client ID of the default application.</li><li><code>client\_protocol</code>: String. The response protocol used to communicate with the default application. Accepted values are <code>oauth2</code>, <code>samlp</code>, and <code>wsfed</code>.</li><li><code>client\_authorizequery</code>: String. The query string sent to the default application.</li></ul></td>
        </tr>

        <tr>
          <td><code>protocolBinding</code></td>
          <td>String</td>
          <td>Optional</td>
          <td>The protocol binding used for authentication requests.<br /><br />Accepted values are:<ul><li><code>urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect</code></li><li><code>urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST</code></li></ul></td>
        </tr>

        <tr>
          <td><code>recipientUrl</code></td>
          <td>String</td>
          <td>Optional</td>
          <td>The URL where the IdP will send SAML authentication responses. Only required when using a proxy gateway.</td>
        </tr>

        <tr>
          <td><code>signatureAlgorithm</code></td>
          <td>String</td>
          <td>Optional</td>
          <td>The algorithm used to sign authentication requests.<br /><br />Accepted values are <code>rsa-sha256</code> and <code>rsa-sha1</code>.</td>
        </tr>

        <tr>
          <td><code>signSAMLRequest</code></td>
          <td>Boolean</td>
          <td>Optional</td>
          <td>Toggles the signing of authentication requests sent by Auth0.</td>
        </tr>

        <tr>
          <td><code>user\_id\_attribute</code></td>
          <td>String</td>
          <td>Optional</td>
          <td>The name of the attribute in the authentication responses to map to the User ID property. This field will supersede any mappings for the <code>user\_id</code> property in the <code>fieldsMap</code> object.</td>
        </tr>
      </tbody>
    </table>

    #### Example request

    ```json lines expandable theme={null}
    {
    	"strategy": "samlp",
    	"name": "example-samlp-connection",
    	"options": {
    		"signingCert": "{X509_CERTIFICATE_IN_BASE64}",
    		"signInEndpoint": "https://example.com/samlp/login",
    		"disableSignout": false,
    		"signOutEndpoint": "https://example.com/samlp/logout",
    		"fieldsMap": {
    			"email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
    			"user_id": [
    				"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    				"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn",
    				"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
    			],
    			"given_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
    			"address_name": "http://schemas.auth0.com/address_name",
    			"address_street_address": "http://schemas.auth0.com/address_street_address"
    		},
    		"user_id_attribute": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
    		"idpinitiated": {
    			"enabled": true,
    			"client_id": "{DEFAULT_APPLICATION_CLIENT_ID}",
    			"client_protocol": "oauth2",
    			"client_authorizequery": "response_type=code&scope=openid email profile"
    		},
    		"signSAMLRequest": true,
    		"signatureAlgorithm": "rsa-sha256",
    		"digestAlgorithm": "sha256",
    		"protocolBinding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
    		"debug": true
    	}
    }
    ```
  </Tab>
</Tabs>

### Configure SAML connection for proxy gateways

If you have Auth0 behind a proxy gateway, you’ll need to configure the SAML connection’s `destinationUrl` and `recipientUrl` fields accordingly.

1. Get your SAML connection's current configuration with the Management API [Get a connection](https://auth0.com/docs/api/management/v2/connections/get-connections-by-id) endpoint.
2. Copy the value of the `options` object from the returned response.
3. Add the following fields to the `options` object:

<table>
  <thead>
    <tr>
      <th><strong>Field</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Value</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>destinationUrl</code></td>
      <td>String</td>
      <td>URL of the proxy gateway.</td>
    </tr>

    <tr>
      <td><code>recipientUrl</code></td>
      <td>String</td>
      <td>URL of the proxy gateway.</td>
    </tr>
  </tbody>
</table>

4. Call the Management API [Update a connection](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id) endpoint with the entire updated `options` object in the request body.

### Customize the request template

When Auth0 sends the authentication request to the IdP, the request body contains an `AuthnRequest` object. You can customize the template used for this object:

1. Go to [Dashboard > Authentication > Enterprise > SAML](https://manage.auth0.com/#/connections/enterprise/samlp), and select your connection.
2. Switch to the **Settings** view, and locate the **Request Template** field.
3. Modify the template.
4. Select **Save Changes**.

#### Template variables

Variables can be placed into the `AuthnRequest` template using the `@@VariableName@@` syntax. The following variables are available:

<table>
  <thead>
    <tr>
      <th><strong>Name</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>AssertionConsumerServiceURL</code></td>
      <td>The URL where the IdP sends the response after the user signs in. Include the <code>ProtocolBinding</code> attribute in the request template if you use this.</td>
    </tr>

    <tr>
      <td><code>Connection.\<options-key></code></td>
      <td>Use dot notation on the <code>Connection</code> key to access any of the connection's <code>options</code> values as returned from the Auth0 Management API's <a href="https://auth0.com/docs/api/management/v2/#!/Connections/get_connections_by_id">Get a Connection</a> endpoint. For example, if the connection has <code>options.some\_property: "value"</code>, then you can use <code>@@Connection.some\_property@@</code> in the template.</td>
    </tr>

    <tr>
      <td><code>Destination</code></td>
      <td>The URL where Auth0 sends the request. This should be the <strong>Sign In URL</strong> configured for the connection.</td>
    </tr>

    <tr>
      <td><code>ID</code></td>
      <td>The transaction ID.</td>
    </tr>

    <tr>
      <td><code>IssueInstant</code></td>
      <td>The transaction date timestamp.</td>
    </tr>

    <tr>
      <td><code>Issuer</code></td>
      <td>The entity ID of the SP in <code>urn</code> format. <br /><br />For example, <code>urn:auth0:\<YOUR\_AUTH0\_TENANT\_NAME>:\<YOUR\_AUTH0\_CONNECTION\_NAME></code>.</td>
    </tr>

    <tr>
      <td><code>LoginHint</code></td>
      <td>The username or email of the user logging in. If you are using <a href="/docs/authenticate/login/auth0-universal-login/identifier-first">Identifier First Authentication</a>, Auth0 can send this value to the IdP to pre-populate it in the IdP's login form.</td>
    </tr>

    <tr>
      <td><code>ProtocolBinding</code></td>
      <td>The protocol <a href="https://www.ibm.com/support/knowledgecenter/en/SSPREK_9.0.4/com.ibm.isam.doc/config/concept/fed_SAML20_bindings.html">binding type</a>.</td>
    </tr>

    <tr>
      <td><code>ProviderName</code></td>
      <td>The name of the application that initiated the request. This always returns the Auth0 tenant name.</td>
    </tr>

    <tr>
      <td><code>AssertServiceURLAndDestination</code></td>
      <td>Deprecated. For new configurations, use <code>AssertionConsumerServiceURL</code> and <code>Destination</code> instead.</td>
    </tr>
  </tbody>
</table>

## Configure the IdP

Go to [SAML Identity Provider Configuration Settings](/docs/authenticate/protocols/saml/saml-identity-provider-configuration-settings) to find the metadata you'll need to provide to the IdP.

Auth0 supports all SAML IdPs that conform to the SAML 1.1 or SAML 2.0 protocol. We have detailed instructions for configuring specific providers:

* [ADFS](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-adfs-saml-connections)
* [Okta](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-okta-as-saml-identity-provider)
* [OneLogin](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-onelogin-as-saml-identity-provider)
* [Ping](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-pingfederate-as-saml-identity-provider)
* [Salesforce](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-salesforce-as-saml-identity-provider)
* [SiteMinder](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-siteminder-as-saml-identity-provider)
* [SSOCircle](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-ssocircle-as-saml-identity-provider)

## Test connection

To test your connection in the Dashboard:

1. Go to [Dashboard > Authentication > Enterprise > SAML](https://manage.auth0.com/#/connections/enterprise/samlp).
2. Locate the connection you created, select the **...** (three dots) menu icon, and select **Try**.
3. A Universal Login Page will appear and prompt you to enter credentials.
4. Enter the email address of a user who exists in the IdP. If you configured [Home Realm Discovery](/docs/authenticate/login/auth0-universal-login/identifier-first#define-home-realm-discovery-identity-providers), make sure you enter an email address that uses one of the specified domains.
5. After you are redirected to the login screen for the IdP, log in as you normally would.
6. You will be redirected to a page on Auth0 that displays the contents of the authentication assertion sent to Auth0 from the IdP.

## Troubleshoot connection

If your connection is not working as expected, try the following steps:

* Clear your browser history, cookies, and cache before each test. If you do not, the browser may not pick up the latest configuration information, or it may have stale cookies that affect execution.
* Ensure that your browser allows cookies and has JavaScript enabled.
* [Capture a HAR file](/docs/troubleshoot/troubleshooting-tools/generate-and-analyze-har-files) of the transaction, and then use the [Auth0 SAML Tool](http://samltool.io/) to decode the SAML assertion and inspect its contents.

## Learn more

* [Customize SAML Assertions](/docs/authenticate/protocols/saml/saml-configuration/customize-saml-assertions)
* [Sign and Encrypt SAML Requests](/docs/authenticate/protocols/saml/saml-sso-integrations/sign-and-encrypt-saml-requests)
* [Troubleshoot SAML Configurations](/docs/troubleshoot/authentication-issues/troubleshoot-saml-configurations)
* [Troubleshoot SAML Errors](/docs/troubleshoot/authentication-issues/saml-errors)


# Configure ADFS as SAML Identity Provider
Source: https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-adfs-saml-connections

Learn how to configure a SAML connection against ADFS in Auth0.

Create a custom <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> connection to Microsoft's Active Directory Federation Services (ADFS) to get more flexibility when configuring your mappings. To create the custom connection, you will need to:

1. Configure ADFS.
2. Create a SAML connection where Auth0 acts as the service provider.
3. Edit the Relying Party Trust in ADFS.
4. Enable and test your integration.

## Configure ADFS

### Add Relying Party Trust

To learn how to add a <Tooltip href="/docs/glossary?term=relying+party">relying party</Tooltip> trust, read [Create a relying party trust](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust) at [https://docs.microsoft.com](https://docs.microsoft.com).

#### Create using federation metadata

Follow the steps on [Create a claims aware Relying Party Trust using federation metadata (MSDN)](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-relying-party-trust#to-create-a-claims-aware-relying-party-trust-using-federation-metadata). For the **Federation metadata address** in Step 4, the URL you enter should be in one of these formats:

US: `https://{yourTenantName}.auth0.com/samlp/metadata?connection={connectionName}`

EU: `https://{yourTenantName}.eu.auth0.com/samlp/metadata?connection={connectionName}`

AU: `https://{yourTenantName}.au.auth0.com/samlp/metadata?connection={connectionName}`

JP: `https://{yourTenantName}.jp.auth0.com/samlp/metadata?connection=CONNECTION_NAME`

<Tooltip href="/docs/glossary?term=Custom+domain">Custom domain</Tooltip>: `https://{yourTenantName}/samlp/metadata?connection={connectionName}`

Once you've finished creating the relying party trust, [continue to the next section](#edit-claim-issuance-policy).

#### Create manually

1. Launch your instance of ADFS and start the **Add Relying Party Trust** wizard.
2. On the **Welcome** page, choose **Claims aware** and click **Start**.
3. On the **Select Data Source** page, select **Enter data about the relying party manually** and click **Next**.
4. On the **Specify Display Name** page, provide a descriptive name for your relying party (the typical format is `urn:auth0:{yourTenant}:{yourConnectionName}`) and a brief description under **Notes**. Be sure to replace `{yourConnectionName}` with a unique name you will also use to create a connection in Auth0 in a later step. If you are unsure of the connection name at this time, you can always edit the connection name later. Click **Next**.
5. On the **Configure Certificate** page, click **Next**. (We will come back to configure the certificate later.)
6. On the **Configure URL** page, check the box for **Enable support for the SAML 2.0 WebSSO protocol**. The wizard then asks for a **Relying party SAML 2.0 SSO service URL**. For the time being, provide a placeholder URL; we will return to this step later. Click **Next**.
7. On the **Configure Identifiers** page, indicate that the **Relying party trust identifier** is `urn:auth0:{yourTenant}:{yourConnectionName}` (or whatever value you used as the display name when you started using the wizard). Click **Next**.
8. On the **Choose Access Control Policy** page, select **Permit everyone** and click **Next**.
9. Review the settings you provided on the **Ready to Add Trust** page and click **Next** to save your information. If you were successful, you'll see a message indicating that on the **Finish** page.
10. Make sure that the **Configure claims issuance policy for this application** checkbox is selected, and click **Close**.

### Edit Claim Issuance Policy

After you close the **Add Relying Party Trust** wizard, the **Edit Claim Issuance Policy** window appears.

1. Click **Add Rule...** to launch the wizard.
2. Select **Send LDAP Attributes as Claims** for your **Claim rule template**, and click **Next**.
3. Provide a value for the **Claim rule name**, such as "LDAP Attributes" (it can be anything you want).
4. Choose **Active Directory** as your **Attribute Store**.
5. Map your LDAP attributes to the following outgoing claim types:

<table>
  <thead>
    <tr>
      <th>LDAP Attribute</th>
      <th>Outgoing Claim</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>E-Mail-Addresses</td>
      <td>E-Mail Address</td>
    </tr>

    <tr>
      <td>Display-Name</td>
      <td>Name</td>
    </tr>

    <tr>
      <td>User-Principal-Name</td>
      <td>Name ID</td>
    </tr>

    <tr>
      <td>Given-Name</td>
      <td>Given Name</td>
    </tr>

    <tr>
      <td>Surname</td>
      <td>Surname</td>
    </tr>
  </tbody>
</table>

The `Name ID` outgoing claim should always be present to ensure correct session handling. We strongly recommend adding all of the claims listed above, especially `E-Mail Address`, since they are the ones most commonly used. You can add additional claim mappings if necessary.
6\. Click **Finish**.
7\. In the **Edit Claim Issuance Policy** window, click **Apply**. You can now exit out of this window.

### Export Signing Certificate

Finally, you'll need to export the signing certificate from the ADFS console to upload it to Auth0.

1. Using the left-hand navigation pane, go to **ADFS > Service > Certificates**. Select the **Token-signing** certificate, and right click to select **View Certificate**.
2. On the **Details** tab, click **Copy to File...**. This launches the **Certificate Export Wizard**. Click **Next**.
3. Choose **Base-64 encoded X.509 (.CER)** as the format you'd like to use. Click **Next**.
4. Provide the location to where you want the certificate exported. Click **Next**.
5. Verify that the settings for your certificate are correct and click **Finish**.

## Create SAML connection with Auth0 as service provider

1. Follow the tutorial on creating a SAML connection where [Auth0 acts as the service provider](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider). Where prompted, upload the signing certificate you exported from ADFS.

   The sign in and sign out URLs are usually in the form of `https://your.adfs.server/adfs/ls`.
2. Click **Save**. A page with instructions for creating a new Relying Party Trust in ADFS appears displaying the exact values required for your Auth0 account/connection. Make a note of these values. Here is an example:

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Example Value</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Post-back URL</td>
      <td>`https://<YOUR CUSTOM DOMAIN>/login/callback?connection=YOUR_CONNECTION_NAME` if a custom domain is configured</td>
    </tr>

    <tr>
      <td />

      <td>`https://\{yourDomain}/login/callback?connection=YOUR_CONNECTION_NAME` if not using custom domains</td>
    </tr>

    <tr>
      <td>Entity ID</td>
      <td>`urn:auth0:{yourTenant}:YOUR_CONNECTION_NAME`</td>
    </tr>
  </tbody>
</table>

## Edit Relying Party Trust

1. In the ADFS console, go to **ADFS > Relying Party Trusts** using the left-hand navigation pane. Select the Relying Party Trust you created earlier and click **Properties** (located on the right-hand navigation pane).
2. Select the **Identifiers** tab, and populate the **Relying Party Identifier** with the **Entity ID** value from the previous screen. Be sure to click **Add** to add the identifier to your list.
3. Select the **Endpoints** tab, and select the placeholder URL you provided earlier. Click **Edit...**.
4. Populate the **Trusted URL** with the **Post-back URL** value.
5. Click **OK**. Finally, click **Apply** and exit the Properties window.

## Enable sign requests (optional)

Optionally, you can sign your SAML requests to the ADFS server.

1. Go to the **Settings** page for your SAML-P Identity Provider in the Auth0 Dashboard.
2. Enable **Sign Requests**.
3. Just below the **Sign Requests** toggle is a link to download your certificate.
4. Return to ADFS and load the downloaded certificate using the **Signatures** tab of the Relying Party properties dialog.

## Enable and test the integration

Before you test your integration, make sure that you've completed the following steps:

* Create a user on the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> that you can use to test your new connection.
* Enable your Connection for at least one application.

1. Go to [Authentication > Enterprise > SAML](https://manage.auth0.com/#/connections/enterprise/samlp).
2. Select the connection that you want to test and click the ellipses (...) then click **Try**. The Microsoft Sign in screen will appear. Sign in and click **Next**.

## Learn more

* [Troubleshoot SAML Configurations](/docs/troubleshoot/authentication-issues/troubleshoot-saml-configurations)


# Configure Okta as SAML Identity Provider
Source: https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-okta-as-saml-identity-provider

Learn how to configure Okta as an SAML identity provider (IdP) in Auth0.

<Card title="Before you start">
  * Sign up for an [Okta Integrator Free Plan org](https://developer.okta.com/signup/) account.
</Card>

<Callout icon="file-lines">
  If you want to integrate your Auth0 tenant with Okta Workforce Identity, try using the [Okta Workforce Enterprise connection](/docs/authenticate/identity-providers/enterprise-identity-providers/okta) first.
</Callout>

You can configure Okta as a <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> (IdP) in Auth0 by configuring a SAML Enterprise connection.

## Configure Okta SAML app integration

You can create a SAML app integration in the Okta Developer Console.

### Create app integration

1. Sign in to your [Okta Admin Console](https://login.okta.com).
2. Go to **Create App Integration** and choose **SAML 2.0** from the options.
3. Configure the following settings:

<table>
  <thead>
    <tr>
      <th><strong>Setting</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Example</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Single Sign-On URL</td>
      <td>Auth0 tenant login callback URL.</td>
      <td>`https://{yourAuth0Domain}/login/callback?connection={yourAuth0ConnectionName}`</td>
    </tr>

    <tr>
      <td>Audience URI (SP Entity ID)</td>
      <td>Auth0 connection audience value.</td>
      <td>`urn:auth0:{yourAuth0TenantName}:{yourAuth0ConnectionName}`</td>
    </tr>
  </tbody>
</table>

<Warning>
  The connection name value (`{yourAuth0ConnectionName}`) that you use to configure your Okta SAML app integration must match the name of the SAML connection you create in Auth0.
</Warning>

4. Select **Next**, and then select **Finish** to complete the Okta app integration configuration.

### Record SSO URL and download certificate

The login flow is now directed to the **Sign On** page for the newly-created app.

1. Select **View SAML Setup Instructions**.
2. Record the **Identity Provider Single Sign-On URL**.
3. Download the **X.509 Certificate** in PEM or CER format.
4. Navigate to **Assignments**, and then assign a user to the Okta application.

## Configure SAML connection in Auth0

You can create a SAML Enterprise connection in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

1. Log in to the [Auth0 Dashboard](https://manage.auth0.com/#).
2. Go to [Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise/samlp).
3. Select **Create** (**+** button) next to **SAML**.
4. Configure the following settings:

<table>
  <thead>
    <tr>
      <th><strong>Setting</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Example</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Connection name</td>
      <td>Auth0 connection name.</td>
      <td><code>myoktaconnection</code></td>
    </tr>

    <tr>
      <td>Sign In URL</td>
      <td>Okta URL where user login requests are sent.<br /><br />This is the <strong>Identity Provider Single Sign-On URL</strong> value you recorded previously.</td>
      <td>`https://my_okta_tenant_name.okta.com/app/` <code>my\_okta\_tenant\_namemy\_okta\_saml\_app\_integration\_name/</code> <code>dakflkbzevu5i5zBi939/sso/saml</code></td>
    </tr>

    <tr>
      <td>X509 Signing Certificate</td>
      <td>Okta tenant public key signing certificate.<br /><br />Upload the <strong>X509 Certificate</strong> you downloaded previously.</td>
      <td><code>myOktaTenantSigningCertificate.pem</code></td>
    </tr>
  </tbody>
</table>

5. Select **Create**.

## Enable SAML Enterprise connection in Auth0

You can enable your SAML Enterprise connection in the Auth0 Dashboard.

### Enable SAML Enterprise connection when using Organizations

If you’re using Organizations:

1. Log in to the [Auth0 Dashboard](https://manage.auth0.com/#).
2. Go to [Organizations](https://manage.auth0.com/#/organizations), and select your Organization.
3. Switch to the **Connections** view.
4. Select **Enable Connections**.
5. Select the SAML connection you created previously, and then select **Enable Connection**.

### Enable SAML Enterprise connection when not using Organizations

If you’re not using Organizations:

1. Log in to the [Auth0 Dashboard](https://manage.auth0.com/#).
2. Go to [Authentication > Enterprise > SAML](https://manage.auth0.com/#/connections/enterprise/samlp), and select the SAML connection you created previously.
3. Switch to the **Applications** view, and enable the connection for your chosen application(s).

## Test connection

You can test your connection in the Auth0 Dashboard.

1. Log in to the [Auth0 Dashboard](https://manage.auth0.com/#).
2. Go to [Authentication > Enterprise > SAML](https://manage.auth0.com/#/connections/enterprise/samlp).
3. Locate your connection in the list.
4. Select **More Actions** (**...** button), and then select **Try**.

   * If your connection is configured correctly, you'll see the **It works!** screen.
   * If not, you’ll see an error message with details about what went wrong.

<Warning>
  The **Try** button works only for users logged in to the Auth0 Dashboard. You can't send this to an anonymous user, such as a customer.

  If you don't have an Okta user, you need to create one or [**configure IdP-initiated SSO**](/docs/authenticate/protocols/saml/saml-sso-integrations/identity-provider-initiated-single-sign-on).
</Warning>

<Callout icon="file-lines">
  The user might see the Okta dashboard after authenticating through a Service Provider-initiated login flow. If you integrate your application with Auth0 using the OIDC protocol, Auth0 takes the value of the `state` parameter and passes it to Okta using the SAML `RelayState` parameter. Make sure that you set the `state` parameter to a value that Okta can use.
</Callout>

## Configure Global Token Revocation

This connection type supports a Global Token Revocation endpoint, which allows a compliant identity provider to revoke Auth0 user sessions, revoke <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip>, and trigger back-channel logout for applications using a secure back-channel.

This feature can be used with Universal Logout in Okta Workforce Identity.

For more information and configuration instructions, see [Universal Logout](/docs/authenticate/login/logout/universal-logout).


# Configure OneLogin as SAML Identity Provider
Source: https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-onelogin-as-saml-identity-provider

Learn how to configure OneLogin as a SAML identity provider for use with Auth0.

Configure OneLogin as a <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> by completing the following steps:

1. Configure OneLogin SAML integration
2. Configure SAML connection in Auth0.
3. Test connection.

## Prerequisite

You must have OneLogin developer account.

## Configure OneLogin

1. Log in to the [OneLogin](https://www.onelogin.com/) Dashboard, and click **Apps** > **Add Apps**.
2. Search for **SAML**, and select **SAML Test Connector (IdP w/attr)**.
3. When prompted, change the **Display Name** of your app.
4. Click **SAVE**.
5. Go to the **SSO** tab, and copy the values for **SAML 2.0 Endpoint (HTTP)** and **SLO Endpoint (HTTP)**.
6. Click on the **View Details** link at the **X.509 Certificate** field.
7. Download the X.509 certificate **onelogin.pem**.

## Configure Auth0 connection

1. Go to [Dashboard > Authentication > Enterprise > SAMLP](https://manage.auth0.com/#) and click the **plus** icon to be redirected to the page that allows you to create a new Connection.
2. You will be prompted to provide the appropriate configuration settings for this Connection. The only mandatory fields are:

<table>
  <thead>
    <tr>
      <th>Setting</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Sign In URL</strong></td>
      <td>The SAML 2.0 Endpoint (HTTP) value you noted when setting up your OneLogin app.</td>
    </tr>

    <tr>
      <td><strong>Sign Out URL</strong></td>
      <td>The SLO Endpoint (HTTP) value you noted when setting up your OneLogin app.</td>
    </tr>

    <tr>
      <td><strong>X509 Signing Certificate</strong></td>
      <td>The certificate you downloaded from Onelogin. You will need to upload the certificate directly to Auth0.</td>
    </tr>
  </tbody>
</table>

3. Click **Save** to proceed.
4. In the next window, you'll be provided two options.

   1. If you are a domain administrator, you can click **Continue** for additional instructions on SAML Identity Provider Configuration.
   2. If you are not, you can give your domain administrator the provided URL so that they can finish the configuration.

### Auth0 configuration values

To finish configuration of the SAML application, the admin will need the following information regarding Auth0:

* **SAML Consumer URL**: `https://{yourDomain}/login/callback`
* **SAML <Tooltip href="/docs/glossary?term=Audience">Audience</Tooltip>**: `urn:auth0:{yourTenant}:yourConnectionName`

Also copy the values of the **post-back URL** and the **Entity ID** before heading back to the Configuration tab of your [OneLogin](https://www.onelogin.com/) app:

<table>
  <thead>
    <tr>
      <th>Auth0 value</th>
      <th>OneLogin configuration field</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Post-back URL</td>
      <td>ACS (Consumer) URL and Recipient</td>
    </tr>

    <tr>
      <td>Entity ID</td>
      <td>Audience</td>
    </tr>
  </tbody>
</table>

Also provide a valid regular expression for the **ACS (Consumer) URL Validator**. For example:

`[-a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&//=]*)`

## Test connection

Before testing your connection:

* Be sure that you have a OneLogin user that you can use for testing. If not, go to the **Users** tab on the OneLogin dashboard and add one
* Be sure that your new Auth0 SAMLP connection has been associated with an application (otherwise you will get an `invalid_request: the connection was disabled` error)

Next to your **SAML** connection, click the **Try** button. If all goes well, you will be redirected to a page informing you that the connection works.

## Identity provider-initiated SSO

OneLogin offers an Application Portal/Launcher to its users. If you want to take advantage of this functionality, you will have to change the **SAML Consumer URL** in OneLogin dashboard to include the `connection` parameter (e.g., `https://{yourDomain}/login/callback?connection=onelogin-customer`). Be sure to replace `onelogin-customer` with the name of your Auth0 connection.

Finally, be sure to enable IdP-initiated login for the connection and pick the application to which your user is redirected after the SAML assertion is consumed. To learn more, read [Configure Identity-Provider-Initiated Single Sign-On](/docs/authenticate/protocols/saml/saml-sso-integrations/identity-provider-initiated-single-sign-on).

## Edit connection mappings

If you use OneLogin and Auth0 out of the box, users logging in using OneLogin and created in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> will be missing some profile information you might like to have.

To collect additional user information, edit the appropriate parameters in the OneLogin dashboard, include the parameters in the SAML assertion, and create the mappings in the Auth0 connection.

### User profile attributes

Sometimes the standard User Profile Attributes are not enough for the functionality you want to build. If this is the case, you can use custom attributes in order to enhance the SAML token. Let's work through a basic example.

The SAML token contains, among others, two attributes: `FirstName` and `LastName`. Let's add a new custom attribute, named `FullName`, that will contain the concatenation of first and last name.

1. Navigate to the OneLogin dashboard and edit your app.
2. On the **Parameters** tab, click **Add Parameter**.
3. In the pop-up, set a name for your new custom attribute using the **Field name** text box. Make sure you check the **Include in SAML assertion** flag. Click **Save**.
4. The new attribute you created is displayed. Click on the **Value** field, which is currently displaying `- No default -`.
5. Click the **Value** dropdown menu and select `- Macro -`.
6. At the text box, set the value to `{firstname} {lastname}`. Click **Save**.
7. Test our changes. Go back to [Auth0 dashboard > Authentication > Enterprise > SAML](https://manage.auth0.com/#/connections/enterprise). On your **SAML** connection, click the **Try** button. The result should include the new attribute `FullName`.

You can find more information on Attribute Macros at the [OneLogin Help Center](https://support.onelogin.com/hc/en-us/articles/201174464-Attribute-macros).

### Add new parameter to SAML assertion

For the purposes of demonstration, let's see how we can add the `EmailAddress` information, which is more than the concatenation of two fields we're already sending, to our login.

1. Before you can map users' **EmailAddress**, you must add this field as a custom parameter to the OneLogin dashboard. Set **Field name** to `EmailAddress` and **Value** as `Email`.
2. You can find details on the steps needed to customize the user profile in the section above.
3. Once you've made your changes, save them, and test your connection once again.
4. Review your Auth0 user, making sure that the `EmailAddress` information is now included and that the value is correct.

You are now ready to proceed with mapping the user information fields in Auth0.

1. Go to the **Settings** of your [SAML](https://manage.auth0.com/#/connections/enterprise) and navigate to the tab **Mappings**. For the email addresses, copy the mapping below, and paste it into the text box.
2. Save your changes, and try your connection again. Once you have successfully logged in, go to [Dashboard > User Management > Users](https://manage.auth0.com/#/users), and check your login. You will see additional information for the appropriate user.


# Configure PingFederate as SAML Identity Provider
Source: https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-pingfederate-as-saml-identity-provider

Describes how to configure PingFederate as a SAML identity provider for use with Auth0.

PingFederate is a federation server that provides identity management, <Tooltip href="/docs/glossary?term=single+sign-on">single sign-on</Tooltip>, and API security for the enterprise. See the complete PingFederate instructions to [configure PingFederate as an identity provider](https://docs.pingidentity.com/r/en-us/pingfederate-120/pf_ident_provid_sso_config).

To configure Auth0 to use PingFederate as an <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>, you will use primarily the default values and your Auth0 tenant metadata file to upload the required configuration parameter values for your Auth0 tenant. If the metadata upload fails for some reason, these are the most important configuration parameters:

* **EntityID:** `urn:auth0:{yourTenant}:{yourConnectionName}`
* **Assertion Consumer Service URL:** `https://{yourDomain}/login/callback`
* **Logout URL:** `https://{yourDomain}/logout`
* **HTTP-Redirect** binding for <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> Request
* **HTTP-POST** binding for SAML Response

1. Download your Auth0 metadata file from `https://YOUR_DOMAIN/samlp/metadata?connection=YOUR_CONNECTION_NAME`. Make sure that you use your custom domain if you have one configured. You will upload this file to import your Auth0 tenant information into the PingFederate configuration.
2. Sign on to your PingFederated account and select **Create New** from the **SP Connections** section.
3. Configure the **SP Connection**.

   * Select the **Browser SSO Profiles** as the **Connection Type**.
   * Select **Browser SSO** as the **Connection Options**.
4. Upload the metadata file that you downloaded in step 1. The **Entity ID**, **Connection Name**, and the **Base URL** will be automatically populated based on the information from the metadata file.
5. Configure **Browser SSO**.

   * Select **SP-Initiated SSO** and **SP-Initiated SLO** in **SAML Profiles**.
   * Go to the **Assertion Creation** section and click **Configure Assertion**. Accept all defaults for the next two screens.
6. Go to the **IdP Adapter Mapping** section. This is where users will be authenticated. Likely, you already have one configured in your PingFederate installation. Select one, or add a new one. Auth0 only requires the **NameIdentifier** claim. All other attributes will be passed further to the end application.
7. Configure **Protocol Settings**. Values for **Protocol Settings** are imported from the metadata file. Next, you will see the **Assertion Consumer Service URL** and the Sign-Out URLs. Click **Next** to the **Allowable SAML Bindings** section.
8. Leave **POST** and **Redirect** enabled. Make sure **SAML Assertion** is always signed.
9. Configure **Credentials**. On **Digital Signature Settings**, select your signing certificate and make sure you check the option to include it in the `<KeyInfo>` element.
10. Configure the certificate used to sign incoming requests. You can download the Auth0 certificate (use `https://{yourTenant}.auth0.com/pem`) and upload it here. Auth0 signs `SAMLRequests` by default; you can change that when you configure the connection.
11. Review your settings and set them as **Active** or **Inactive**.
12. Click **Save** at the bottom of the screen. You should see the new SP Connection on the **Main** screen.

## Identity provider-initiated SSO

To use IdP-Initiated SSO, make sure to include the `connection` parameter in the Assertion Consumer Service URL: `https://{yourDomain}/login/callback?connection={yourConnectionName}`.

To learn how to configure Auth0 to route the incoming SAML responses, read [Configure Identity Provider-Initiated Single Sign-On](/docs/authenticate/protocols/saml/saml-sso-integrations/identity-provider-initiated-single-sign-on).


# Configure Salesforce as SAML Identity Provider
Source: https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-salesforce-as-saml-identity-provider

Describes how to Salesforce as SAML identity provider for use with Auth0.

Configure Salesforce as a <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> by completing the following steps:

1. Obtain Salesforce certificate and metadata.
2. Set up Auth0 as a service provider.
3. Configure the Salesforce identity provider (IdP).
4. Grant privileges to users in Salesforce.
5. Test the connection to the Salesforce IdP.

## Prerequisite

Register for a [Salesforce.com](http://salesforce.com) account. You must select one of the account types that include identity provider support.

## Obtain Salesforce certificate and metadata

1. Log in to your [Salesforce](http://salesforce.com) account.
2. Create your [Salesforce Domain](https://help.salesforce.com/apex/HTViewHelpDoc?id=domain_name_setup.htm\&language=en_US).
3. Log into your Salesforce domain `https://{yourDomain}.my.salesforce.com` and click on **Setup** on the top right.
4. In the Quick Find box, enter Single Sign-On Settings, then select **Single Sign-On Settings**, and then click **Edit**.
5. To view the SAML SSO settings, select **SAML Enabled**
6. Select the default certificate and click **Save**.
7. Click **Download Certificate** to download the identity provider certificate.
8. Click **Download Metadata** to download the identity provider metadata.

## Set up Auth0 as a service provider

Configure Auth0 as a service provider to communicate with the Salesforce identity provider for <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip>.

1. Go to the [Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise) and click **SAML**.
2. Click **Create Connection**.
3. In the configuration window, enter the following information:

<table>
  <thead>
    <tr>
      <th>Setting</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Connection Name</strong></td>
      <td>Name your connection. For example <strong>SFIDP</strong>.</td>
    </tr>

    <tr>
      <td><strong>Email Domains</strong></td>
      <td>Enter the email domain name that your users will be loggin in from. For example, if your users have an email domain of <code>abc-example.com</code>, enter that into this field. You can enter multiple domains.</td>
    </tr>

    <tr>
      <td><strong>Sign In URL</strong></td>
      <td>Open the metadata file you downloaded from Salesforce and locate the line that contains the <code>SingleSignOnService</code> binding. The value of the <code>location</code> attribute on this line is your Sign In URL. It will be something like: `https://{sf-account-name}.my.salesforce.com/idp/endpoint/HttpRedirect` where `{sf-account-name}` is your Salesforce domain name.</td>
    </tr>

    <tr>
      <td><strong>Sign Out URL</strong></td>
      <td>Enter the same URL you entered for Sign In URL.</td>
    </tr>
  </tbody>
</table>

4. For the **Certificate**, you convert the certificate downloaded from Salesforce to .pem format with the following command:
   `openssl x509 -in original.crt -out sfcert.pem -outform PEM`where `original.crt` is the filename of the downloaded .crt file.

   1. Click **UPLOAD CERTIFICATE** and select the `.pem` file you just created. (`sfcert.pem` in the example above). You can ignore the rest of the fields for now.
   2. Click **SAVE**.
   3. Click **CONTINUE**. In the window that appears, SAML metadata for the Auth0 Service Provider will be displayed. Keep this window open since you will need to enter some of this information into Salesforce to finish the configuration.

You can access the metadata for an Auth0 SAML connection with this URL syntax: `https://{yourDomain}/samlp/metadata?connection={yourConnectionName}`.

## Configure Salesforce as an identity provider

Configure Salesforce with the metadata from Auth0 so it can receive and respond to SAML-based authentication requests from Auth0.

1. Open [**salesforce.com**](http://salesforce.com).
2. Go to **Setup** > **Manage Apps**. Click **Connected Apps**.
3. Create a new Connected App and fill out the following fields:

<table>
  <thead>
    <tr>
      <th>Setting</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Entity ID</strong></td>
      <td><code>urn:auth0:YOUR\_TENANT:YOUR\_CONNECTION\_NAME</code></td>
    </tr>

    <tr>
      <td><strong>ACS URL</strong></td>
      <td>`https://{yourDomain}/login/callback`</td>
    </tr>

    <tr>
      <td><strong>Subject Type</strong></td>
      <td><code>Persistent ID</code></td>
    </tr>

    <tr>
      <td><strong>Name ID Format</strong></td>
      <td>Choose the one with <code>emailAddress</code></td>
    </tr>

    <tr>
      <td><strong>Issuer</strong></td>
      <td>`https://{your-saleforce-domain}.my.salesforce.com`</td>
    </tr>
  </tbody>
</table>

4. Click **Save** to complete the configuration.

## Grant privileges to users in Salesforce

1. Open [**salesforce.com**](http://salesforce.com) and click **Setup**.
2. Under **Manage Users**, click **Profiles**.
3. Scroll down to find the profile called **Standard User** (on page 2).
4. Click on **Edit** to edit the profile.
5. Scroll down to the **Connected App Access** section.
6. Check the box next to the name of your connected app to enable it for this profile.
7. Click **Save**.
8. Under **Manage Users**, click **Users**.
9. Click **Edit** to edit your test user and set the profile to **Standard User**.
   To use a different Salesforce profile, enable the connected app for that profile and ensure that all users that login through the Salesforce Identity Provider have that profile.

## Test connection to Salesforce

1. Navigate to the [Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise) section of the Auth0 dashboard. Select the **SAMLP Identity Provider**.
2. Click the **Try** button for the SAML connection you created earlier. You should be redirected from Auth0 to the Salesforce login page.
3. Once you are at the **Salesforce login screen**, login with the credentials you provided when you created the Salesforce account.

   1. If the SAML configuration works, your browser will be redirected back to an Auth0 page that says **"It works!!!"**. This page will display the contents of the SAML authentication assertion sent by the Salesforce IDP to Auth0.
   2. If it didn't work, double check the steps above and consult the **troubleshooting** section below.

When troubleshooting SSO, it is often helpful to capture an HTTP trace of the interaction and save it in a HAR file. To learn more, read [Generate and Analyze HAR Files](/docs/troubleshoot/troubleshooting-tools/generate-and-analyze-har-files).

<Warning>
  Before sharing a HAR file with anyone (including Auth0), ensure that you remove or obfuscate all sensitive data, such as:

  * Confidential user information
  * Personal identifiable information (PII)
  * Confidential application information

  To learn more, read the following articles on [Auth0 Community](https://community.auth0.com):

  * [Sanitizing HTTP Traces](https://community.auth0.com/t/sanitizing-http-traces/119488)
  * [How to Sanitize an HTTP Trace File Automatically](https://community.auth0.com/t/how-to-sanitize-a-http-trace-file-automatically/120583)
  * [How to Manually Redact Sensitive Information](https://community.auth0.com/t/how-to-manually-redact-sensitive-information/122554)
  * [HAR File is Too Large to Upload to the Support Case](https://community.auth0.com/t/har-file-is-too-large-to-upload-to-the-support-case/122488)
</Warning>

Once you have an http trace tool, capture the login sequence from start to finish and analyze the trace for the sequence of GETs. You should see a redirect from your original site to the IDP, a post of credentials if you had to log in, and then a redirect back to the callback URL. The HAR file will also contain the SAML response.

Make sure that cookies and JavaScript are enabled for your browser.

Make sure that the user's profile in Salesforce has permission to login via the Salesforce IDP (See section 4 above).


# Configure SiteMinder as SAML Identity Provider
Source: https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-siteminder-as-saml-identity-provider

Learn how to configure SiteMinder as a SAML identity provider for use with Auth0.

Configure SiteMinder as a <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> by completing the following steps.

## Prerequisite

You must have a [SiteMinder](https://www.siteminder.com/login/) account.

## Configure SiteMinder settings

When configuring SiteMinder, you will use the default values for most options. You will also need the following Auth0-related values in the configuration steps below:

* **EntityID:** `urn:auth0:{yourTenant}`
* **Assertion Consumer Service URL:** `https://{yourDomain}/login/callback`
* **Logout URL:** `https://{yourDomain}/logout`
* **HTTP-Redirect** binding for SAML Request
* **HTTP-POST** binding for SAML Response

1. Log into [SiteMinder](https://www.siteminder.com/login/).
2. Open the **SAML Service Provider Dialog**.
3. Provide an appropriate name for this service provider.
4. Define the `NameIdentifier`. There are many ways of generating this for users authenticating with SiteMinder. Typically you will map this value to one of the user properties in the User Directory as `uid`.
5. Configure the service provider general SAML properties:

<table>
  <thead>
    <tr>
      <th>Setting</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>SP ID</strong></td>
      <td><code>urn:auth0:</code></td>
    </tr>

    <tr>
      <td><strong>SAML Version</strong></td>
      <td>2.0</td>
    </tr>

    <tr>
      <td><strong>Skew Time:</strong></td>
      <td>30 seconds</td>
    </tr>
  </tbody>
</table>

6. Configure the **Assertion Consumer Service URL** which is the location where SiteMinder will POST back the SAML token. This Service Provider () only supports the `HTTP-POST` binding for SAML Responses. Use:
   `https://{yourDomain}/login/callback`
7. Check the **HTTP-Post** box.
8. Configure additional user properties to send in the token. Add any other properties you wish to share about the authenticated user to this Service Provider. Common values are: `name`, `lastname`, `email address`, and so on. This Service Provider will use the `NameIdentifier` defined previously as a unique handle of the user. These attributes will be treated as reference information.
9. Enter the **SLO Location URL:**`https://{yourDomain}/logout`
10. (Optional) The service provider supports encryption of assertions.
    To use this option, do the following to download the Service Provider public key certificate.

    1. In the Auth0 Dashboard, click on **Connections** and then **Enterprise.**
    2. Click on SAMLP Identity Provider.
    3. Click on the setup icon (pencil).
    4. In the window which appears, the seventh (last) bullet gives you links to download the .pem or .cer format certificate.
    5. Download the desired certificate and add it to the SiteMinder **Policy Server Keystore**.


# Configure SSOCircle as SAML Identity Provider
Source: https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider/configure-ssocircle-as-saml-identity-provider

Learn how to configure an application to use Auth0 for SAML Single Sign-on (SSO), authenticating users against SSOCircle.

Configure SSOCircle as an <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> by completing the following steps:

1. Obtain SSOCircle metadata.
2. Configure enterprise connection in Auth0.
3. Configure SSOCircle as identity provider.
4. Test connection.

## Prerequisite

You must have a [SSOCircle](https://idp.ssocircle.com/) account.

## Obtain SSOCircle metadata

1. Navigate to [SSOCircle's IDP page](https://idp.ssocircle.com/) to see the metadata required for integration. You will be shown an XML file.
2. From this page, you will need to save the following attributes:

   1. The Location URL for the `SingleSignOnService` attribute with an `HTTP-Redirect` type.
   2. The Location URL for the `SingleLogoutService` attribute with an `HTTP-Redirect` type.
3. [Download](http://www.ssocircle.com/en/idp-tips-tricks/public-idp-configuration) and save the SSOCircle CA Certificate.

## Configure enterprise connection in Auth0

1. Go to [Dashboard > Authentication > Enterprise > SAMLP](https://manage.auth0.com/#/connections) and click the **plus** icon to go to the page that allows you to create a new connection.
2. Provide the appropriate configuration settings for this connection. The only mandatory fields are as follows:

<table>
  <thead>
    <tr>
      <th><strong>Setting</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Example</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Connection name</td>
      <td>Auth0 connection name.</td>
      <td><code>myoktaconnection</code></td>
    </tr>

    <tr>
      <td>Sign In URL</td>
      <td>Okta URL where user login requests are sent.<br /><br />This is the <strong>Identity Provider Single Sign-On URL</strong> value you recorded previously.</td>
      <td>`https://my_okta_tenant_name.okta.com/app/` <code>my\_okta\_tenant\_namemy\_okta\_saml\_app\_integration\_name/</code> <code>dakflkbzevu5i5zBi939/sso/saml</code></td>
    </tr>

    <tr>
      <td>X509 Signing Certificate</td>
      <td>Okta tenant public key signing certificate.<br /><br />Upload the <strong>X509 Certificate</strong> you downloaded previously.</td>
      <td><code>myOktaTenantSigningCertificate.pem</code></td>
    </tr>
  </tbody>
</table>

3. When setting up mappings, use the following JSON to properly map SAML attributes from SSO Circle:

   ```json lines theme={null}
   {
         "email": "EmailAddress",
         "given_name": "FirstName",
         "family_name": "LastName"
       }
   ```

4. Click **Save**. In the next window, you'll be provided two options:

   1. If you are a domain administrator, click **Continue** for additional instructions on SAML identity provider configuration.
   2. If you are not, you can give your domain administrator the provided URL so that they can finish the configuration.

You can access the metadata for an Auth0 <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> connection using a URL with the following format:
`https://{yourDomain}/samlp/metadata?connection={yourConnectionName}`.

You will need to provide this metadata to SSOCircle in the next step.

## Configure SSOCircle as identity provider

1. Log in to your [SSOCircle](http://ssocircle.com) account. You will be directed to your user profile, and to the left of that is a navigation bar.
2. Click **Manage Metadata**.
3. Select **Add New Service Provider**, and provide the following information to configure the new service provider which, in this case, is Auth0:

<table>
  <thead>
    <tr>
      <th>Setting</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>FQDN of the ServiceProvider</strong></td>
      <td><code>auth0.com</code></td>
    </tr>

    <tr>
      <td><strong>Attributes to send in assertion</strong></td>
      <td>Check the box for <code>EmailAddress</code></td>
    </tr>

    <tr>
      <td><strong>Insert your metadata information:</strong></td>
      <td>Paste in the XML metadata that you downloaded after you configured your Auth0 connection.</td>
    </tr>
  </tbody>
</table>

4. Click **Submit**.

## Test connection

### Create Auth0 application

1. Go to the **Applications** page on the [Auth0 Dashboard](https://manage.auth0.com/#) and click **+ New Application**.
2. Provide some basic information about your new application. Choose **Regular Web Applications** as the application type.
3. Click **Create** to finish configuration and begin the Application creation process. You will be directed to the application details page.
4. Click **Settings**.
5. In the **Allowed Callback URL** field, enter the list of allowed callback URLs includes those to which users will be redirected after authentication. The URL(s) entered here must match the **callback URL** in the HTML code you will create in a later step. Normally, you would enter a URL for your application, but to keep this example simple, users will simply be sent to the Auth0 JWT Tool.
6. Click **SAVE CHANGES**.
7. Return to the top of **Settings** and click **Connections**.
8. Scroll to the **Enterprise** section. Find the row for the SAML connection you created above and turn on toggle to enable the SAML connection.

### Test enterprise connection

1. To test your connection, follow the steps in [Test Enterprise Connections](/docs/authenticate/identity-providers/enterprise-identity-providers/test-enterprise-connections).
2. During this process you will be asked to log in and consent.
3. Additionally, if you see a message that says, "Your session has timed out," click the **Return to Login page** link below the message.

If logging in to your application doesn't work the first time, clear your browser's history and cookies before testing again. The browser may not be picking up the latest version of your HTML.

When troubleshooting <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip>, it is often helpful to capture an HTTP trace of the interaction. There are many tools that will capture the HTTP traffic from your browser for analysis (search for "HTTP Trace" to find one appropriate for your needs). Once you have an HTTP tracer, capture the login sequence from start to finish and analyze the trace to see the sequence of `GET` requests to see where the error occurs. You should see:

* A redirect from your original site to the IDP
* A post of credentials (if you were asked to log in)
* A redirect to the callback URL.

Ensure that your browser has enabled cookies and JavaScript.

Check to make sure that the callback URL specified in the HTML is also listed in the **Allowed Callback URLs** field in the **Settings** tab of the Auth0 Application.


# Configure IdP-Initiated SAML Sign-on to OIDC Apps
Source: https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations/configure-idp-initiated-saml-sign-on-to-oidc-apps

Learn how to configure an Auth0 SAML connection to support Identity Provider-initiated sign-on to a SAML Identity Provider for OIDC applications.

Auth0 provides a method to translate an <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip>-initiated (IdP) <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> response into an <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) response for an application.

The OIDC protocol does not support IdP-initiated authentication flows, but this method allows you to simulate an IdP-initiated authentication flow using the [Implicit Flow with Form Post](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post).

<Warning>
  We strongly recommend you start the login flow at the OIDC application rather than at the IdP. To learn more, read [Configure SAML Identity Provider-Initiated Single Sign-On](/docs/authenticate/protocols/saml/saml-sso-integrations/identity-provider-initiated-single-sign-on).
</Warning>

If you’d like to implement this method, you must:

* Add a custom login route handler to your application.
* Update your SAML connection to:

  1. Accept incoming IdP-initiated SAML responses.
  2. Redirect to a default application that sends a Service Provider-initiated authentication request.

## How it works

<Frame>
  <img alt="Identity Provider-initiated SAML sign-in to OIDC applications flow diagram" />
</Frame>

1. User navigates to the SAML IdP’s login endpoint.
2. SAML IdP returns the login page.
3. User submits credentials to the SAML IdP.
4. SAML IdP creates a session for the user and then returns an HTML page with Form Post and the SAML response.
5. Page automatically sends the SAML response to the Auth0 tenant through an HTTP `POST` call.
6. Auth0 tenant redirects the user’s browser to the OIDC application’s custom login route handler with the ID token as a URL fragment.
7. Browser calls the custom login route handler of the OIDC application with the `connection` parameter and the ID token.
8. OIDC application ignores the ID token, parses the `connection` parameter, creates a `state` parameter for the session, and then redirects the user’s browser to the Auth0 tenant’s `/authorize` endpoint.
9. Browser calls the Auth0 tenant’s `/authorize` endpoint with the provided `connection` and `state` parameters.
10. Auth0 tenant generates a SAML login request and then redirects the user’s browser to SAML IdP’s login endpoint.
11. Browser sends the SAML login request to the SAML IdP’s login endpoint.
12. SAML IdP finds the user’s session and then returns an HTML page with Form Post and the SAML response.
13. Page automatically sends the SAML response to the Auth0 tenant through an HTTP `POST` call.
14. Auth0 tenant redirects the user’s browser to the application’s login route handler.
15. Browser calls the application’s login route handler with the provided `state` parameter and ID token.
16. OIDC application verifies the `state` parameter, parses the ID token and creates an application session for the user.

## Create the custom login route handler

The custom login route handler calls your application’s login method. The handler must accept the `connection` parameter and include it in the authentication request sent to your Auth0 tenant.

We recommend that you associate the custom login route handler with a different endpoint than the one associated with your standard login route handler. For example, if your standard login route handler is associated with the `/login` endpoint, you could associate the custom login route handler with the `/startlogin` endpoint.

<Warning>
  If you are not using an Auth0 SDK to handle authentication, you must ensure that your application’s login method passes a `state` parameter value to the `/authorize` endpoint and validates the `state` parameter in the response from the Identity Provider to protect against CSRF attacks. To learn more, read [Prevent Attacks and Redirect Users with OAuth 2.0 State Parameters](/docs/secure/attack-protection/state-parameters).
</Warning>

### Example

If you are using the [Auth0 Single Page App SDK](/docs/libraries/auth0-single-page-app-sdk), you can add a custom login route handler and update the login method to support the connection parameter like so:

```javascript lines expandable theme={null}
const router = {
  "/": () => showContent("content-home"),
  "/profile": () =>
    requireAuth(() => showContent("content-profile"), "/profile"),
  "/login": () => login(),
  "/startlogin": () => startlogin()
};

//new method to start login from idp-initiated callback
const startlogin = async () => {
  console.log(window.location.href)
  let myURL = new URL(window.location.href);
  let conn = myURL.searchParams.get("connection");
  return  login(null, conn);
}

/**
 * Starts the authentication flow
 */
const login = async (targetUrl, connection) => {
  try {
    console.log("Logging in", targetUrl);

    const options = {
      redirect_uri: window.location.origin,
    };

    if (connection) {
      options.connection = connection;
    }

    if (targetUrl) {
      options.appState = { targetUrl };
    }

    await auth0.loginWithRedirect(options);
  } catch (err) {
    console.log("Log in failed", err);
  }
};
```

## Create the query string

The query string contains the `redirect_uri` parameter. The parameter’s value must be URL encoded and is composed of:

1. The application endpoint associated with the custom login route handler.
2. The `connection` parameter with the value of your SAML connection name.

### Example

If your application endpoint is `https://exampleco.com/startlogin` and your SAML connection name is `my-saml-connection`, the query string would be `redirect_uri=https%3A%2F%2Fexampleco.com%2Fstartlogin%3Fconnection%3Dmy-saml-connection`.

## Configure the application

1. Go to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications).
2. Create a new Application to represent the OIDC application in Auth0.
3. Update **Allowed Callback URLs** to include the application endpoint associated with your custom login route handler.

## Configure the connection

1. Go to [Auth0 Dashboard > Authentication > Enterprise > SAML](https://manage.auth0.com/#/connections/enterprise/samlp).
2. Create a new SAML connection.
3. Switch to the **IdP-Initiated SSO** view.
4. Select **Accept Requests.**
5. For **Default Application**, select the application you previously created.
6. For **Response Protocol**, select **OpenID Connect**.
7. For **Query String**, enter the query string you previously created.

## Learn more

* [Connect Your App to SAML Identity Providers](/docs/authenticate/identity-providers/enterprise-identity-providers/saml)
* [Configure SAML Identity Provider-Initiated Single Sign-On](/docs/authenticate/protocols/saml/saml-sso-integrations/identity-provider-initiated-single-sign-on)
* [Log Users Out of SAML Identity Providers](/docs/authenticate/login/logout/log-users-out-of-saml-idps)
* [Troubleshoot SAML Configurations](/docs/troubleshoot/authentication-issues/troubleshoot-saml-configurations)


# Enable SAML2 Web App Addon
Source: https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations/enable-saml2-web-app-addon

Learn how to enable the SAML2 web app add-on for use with Auth0 as a SAML single sign-on (SSO) identity provider.

You can configure a SAML2 Web Application add-on for use with an application.

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications).
2. Identify the application with which you want to use a SAML2 Web Application, and click the Application's name to go to its configuration settings.
3. Go to the **Addons** tab.
4. In the **SAML2 Web App** box, click the slider to enable the Addon.

   <Frame>
     <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Settings Tab" />
   </Frame>
5. Go to the **Settings** tab and provide your **Application Callback URL** that receives the SAML response, as well as the **Settings**. On the **Settings** tab, there is a sample object that you can use when determining which settings you want to enable.
6. Click **Debug** to test if your provided parameters are valid.
7. Click **Save** when done.

## Provide application details

While the specific steps for providing your application details to your SAML2 Web App will vary, you can get the configuration information you need from the **Usage** tab after you set up the addon.

<Frame>
  <img alt="Dashboard Applications Applications Addons Tab SAML2 Web App Usage Tab" />
</Frame>

## Integrations

You can choose from the following integrations:

* [Amazon Web Services](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-aws)
* [GitHub Enterprise Cloud](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-github-enterprise-cloud)
* [GitHub Enterprise Server](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-github-enterprise-server)
* [Heroku](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-heroku)
* [Oracle Eloqua Marketing Cloud](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-addon-eloqua)

## Limitation

The SAML2 Web App addon does not support passive <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> requests (e.g. where `isPassive=true`).

## Learn more

* [Configure Amazon Web Services as SAML Service Provider](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-aws)
* [Configure GitHub Enterprise Cloud as SAML Service Provider](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-github-enterprise-cloud)
* [Configure GitHub Enterprise Server as SAML Service Provider](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-github-enterprise-server)
* [Configure Heroku as SAML Service Provider](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-heroku)
* [Configure Oracle Eloqua Marketing Cloud as SAML Service Provider](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-addon-eloqua)
* [CVE-2017-16897: Security Update for passport-wsfed-saml2 Passport Strategy Library](/docs/secure/security-guidance/security-bulletins/cve-2017-16897)


# Configure SAML Identity Provider-Initiated Single Sign-On
Source: https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations/identity-provider-initiated-single-sign-on

Describes how to configure SAML Identity Provider-initiated Single Sign-on (SSO).

Many instructions for setting up a <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> federation begin with <Tooltip href="/docs/glossary?term=Single+Sign-on">Single Sign-on</Tooltip> (SSO) initiated by the service provider. The service provider redirects the user to the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> (IdP) for the purposes of authentication. This process is commonly used for consumer-facing scenarios.

However, in enterprise scenarios, it is sometimes common to begin with the IdP initiating SSO instead of the service provider. For example, an enterprise might set up a portal to ensure that users navigate to the correct application after they sign on to the portal.

## Risks and considerations

IdP-Initiated flows carry a security risk and are therefore not recommended. The recommendation is to use SP-Initiated flows whenever possible.

Make sure you understand the risks before enabling IdP-Initiated SSO. In this scenario, Auth0 receives the unsolicited response from the IdP and the application receives the unsolicited response from Auth0. Neither entity can verify that the user started the flow. Because of this, enabling this flow opens the possibility of an [Login CSRF attack](https://support.detectify.com/support/solutions/articles/48001048951-login-csrf), where an attacker can trick a legitimate user into unknowingly logging into the application with the identity of the attacker.

### OpenID Connect IdP-initiated flow

<Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) does not support the concept of an IdP-Initiated flow. So while Auth0 offers the possibility of translating a SAML IdP-Initiated flow (from a SAML connection) into an OIDC response for an application, any application that properly implements the OIDC/OAuth2 protocol will reject an unrequested response.

When using OIDC applications, the best option is to have your application create a login endpoint. This endpoint’s sole purpose is to initiate the redirect back to the IdP (your Auth0 tenant).

If you use multiple IdPs, be sure that the login endpoint is either specific to the identity provider or can accept a parameter to identify which IdP initiates the workflow.

An alternative approach is to have users start the login flow at the application.

### Post-back URL

When using IdP-Initiated SSO, make sure to include the connection parameter in the post-back URL:

<AuthCodeBlock />

If you are using the [Organizations](/docs/manage-users/organizations) feature, you can optionally include an organization parameter containing the organization ID of the desired organization:

<AuthCodeBlock />

<Callout icon="file-lines">
  In order for users to successfully log-in using this method, the connection must be enabled for the Organization. Additionally, you must either configure [auto-membership](/docs/manage-users/organizations/configure-organizations/grant-just-in-time-membership) for the enabled connection or ensure users have membership for the Organization.
</Callout>

### Lock/Auth0.js

If your application is a single-page application that uses Lock or Auth0.js to process the authentication results, you must explicitly indicate that you want to allow IdP-Initiated flows and thus open the application to possible Login CSRF attacks.

If you are using Auth0.js, you must update the `webAuth.parseHash` of the library and set the flag `__enableIdPInitiatedLogin` to `true`.

```javascript lines theme={null}
var data = webAuth.parseHash(
      {
        ...
        __enableIdPInitiatedLogin: true
        ...
      }
```

If you're using Lock, you can include the flag using the options parameter sent to the constructor.

`const lock = new Auth0Lock(clientID, domain, options)`

Here's the flag itself:

`var options = { _enableIdPInitiatedLogin: true };`

Note that the `enableIdPInitiatedLogin` flag is preceded by one underscore when used with Lock and two underscores when used with the auth0.js library.

## Set up IDP-initiated SSO

1. Go to the [Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise) and choose **SAMLP Identity Provider**.
2. Under **Settings** you can see the configuration for IdP-Initiated SSO.

   <Frame>
     <img alt="Protocols IdP-initiated SSO Configuration Screen" />
   </Frame>

* **IdP-initiated SSO Behavior**: This option allows you to enable IdP-initiated logins for the SAML connection. Select **Accept Requests** and complete all the required fields.
* **Default Application:** When the IdP initiated login succeeds this is the application where users are routed. This setting shows available applications enabled for this connection. Select the application from the dropdown that you want the users to login with IdP initiated. Only one application can be selected for an IdP-initiated login per SAML connection.
* **Response Protocol:** This is the protocol used to connect your selected **Default Application**. Most commonly, applications are configured with the OpenID Connect protocol (see above). However, if you have configured a SAML2 Web App addon for your application and want to route the SAML assertion you will need to select SAML. Once a valid SAML Assertion has been passed to the postback URL, Auth0 sends a login response to the configured default application’s first allowed callback URL using the chosen response protocol, which can be modified using the query string field to specify a `redirect_uri` if you use OIDC.
  * If the callback URL configured for the application includes a Multiple Custom Domains (MCD) placeholder, the system dynamically populates it using the metadata value that corresponds to the custom domain of the postback URL that received the inital request from the IdP. For more information, see [Multiple Custom Domains](/docs/customize/custom-domains/multiple-custom-domains).
* **Query String:** Query string options help to customize the behavior when the OpenID Connect protocol is used. You can set multiple options similar to setting parameters with a [query string](https://en.wikipedia.org/wiki/Query_string). You can set:

<table>
  <thead>
    <tr>
      <th>Setting</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>redirect\_uri</code></td>
      <td>When the IdP-initiated login has completed the request is then redirected to the first URL listed in the <strong>Allowed Callback URLs</strong> for the application. However, if you set a <code>redirect\_uri</code>, the IdP will redirect to this URL. This adds flexibility for cases such as when you have a set subdomain scheme with a wildcard and you only want to redirect to one specific subdomain.</td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td>Define scopes for the ID token sent. You can set multiple scopes.</td>
    </tr>

    <tr>
      <td><code>response\_type</code></td>
      <td>Set the token for the Implicit Grant Flow for SPAs. You can set code for the Authorization Code Grant Flow for regular web apps.</td>
    </tr>
  </tbody>
</table>

<Warning>
  In an IdP initiated flow, Auth0 servers strip scopes inside a token if the callback URL is an unverified domain. Auth0 defines only `localhost` and [127.0.0.1](http://127.0.0.1/) as unverified domains. If you use either as your callback URL, tokens from the `/userinfo` endpoint will return an empty response. To get a token response with requested scopes, use a verified domain.
</Warning>

Example Query String:
`redirect_uri=https://jwt.io&scope=openid email&response_type=token`

## Application drop-down list limited to 100

If you want to select an application as the **Default Application** in IdP-initiated SSO, and the application isn't in the first 100 applications listed in the drop-down list for your tenant, you must use the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to select that application. You must run a patch:

```json lines theme={null}
{
"options": {
"signInEndpoint": "yourIdpSignInUrl",
"idpinitiated": {
"client_id": "yourClientId",
"client_protocol": "saml",
"client_authorizequery": ""
},
"signingCert": "[copied-from-GET]"
}
}
```

## Learn more

* [Work with Certificates and Keys as Strings](/docs/authenticate/protocols/saml/saml-sso-integrations/work-with-certificates-and-keys-as-strings)


# Sign and Encrypt SAML Requests
Source: https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations/sign-and-encrypt-saml-requests

Describes the special configuration scenario to sign and encrypt SAML requests

To increase the security of your transactions, you can sign or encrypt both your requests and your responses in the <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> protocol. In this article, you'll find configurations for specific scenarios, separated under two use cases:

* Auth0 as the SAML service provider (for example, a SAML connection)
* Auth0 as the SAML <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> (for example, an application configured with the SAML Web App addon)

## Auth0 as the SAML service provider

These scenarios apply when Auth0 is the SAML Service Provider, which means that Auth0 connects to a SAML identity provider by creating a SAML connection.

### Sign the SAML authentication request

If Auth0 is the SAML **service provider**, you can sign the authentication request Auth0 sends to the IdP as follows:

1. Navigate to [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise), and select **SAML**.
2. Select the name of the connection to view.
3. Locate **Sign Request**, and enable its switch.
4. Download the certificate beneath the **Sign Request** switch, and provide it to the IdP so that it can validate the signature.

#### Enable/disable deflate encoding

By default, SAML authentication requests are sent via HTTP-Redirect and use deflate encoding, which puts the signature in a query parameter.

To turn off deflate encoding, you can make a [PATCH call to the Management API's Update a Connection endpoint](https://auth0.com/docs/api/management/v2#!/Connections/patch_connections_by_id) and set the `deflate` option to `false`.

Updating the `options` object for a connection overrides the whole `options` object. To keep previous connection options, get the existing `options` object and add new key/values to it.

Endpoint: `https://{yourDomain}/api/v2/connections/{yourConnectionId}`

Payload:

```json lines theme={null}
{
	{ 
		"options" : {
			[...], // all the other connection options
		  "deflate": false
	}
}
```

### Use a custom key to sign requests

By default, Auth0 uses the tenant private key to sign SAML requests (when the **Sign Request** toggle is enabled). You can also provide your own private/public key pair to sign requests coming from a specific connection.

You can generate your own certificate and private key using this command:

```bash wrap lines theme={null}
openssl req -x509 -nodes -sha256 -days 3650 -newkey rsa:2048 -keyout private_key.key -out certificate.crt
```

Changing the key used to sign requests in the connection can't be done on the Dashboard UI, so you will have to use the [Update a Connection endpoint](https://auth0.com/docs/api/management/v2#!/Connections/patch_connections_by_id) from the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> v2, and add a `signing_key` property to the `options` object, as shown in the payload example below.

Updating the `options` object for a connection overrides the whole `options` object. To keep previous connection options, get the existing `options` object and add new key/values to it.

Endpoint: `https://{yourDomain}/api/v2/connections/{yourConnectionId}`

Payload:

```json lines theme={null}
{
	{ 
		"options" : {
			[...], // all the other connection options
		  "signing_key": {
				"key":"-----BEGIN PRIVATE KEY-----\n...{your private key here}...\n-----END PRIVATE KEY-----",
				"cert":"-----BEGIN CERTIFICATE-----\n...{your public key cert here}...\n-----END CERTIFICATE-----"
			}
    }
	}
}
```

To learn how to get the private key and certificate formatted as a JSON string to use in the payload, see [Work with Certificates and Keys and Strings](/docs/authenticate/protocols/saml/saml-sso-integrations/work-with-certificates-and-keys-as-strings).

### Receive signed SAML authentication responses

If Auth0 is the SAML **service provider**, all SAML responses from your identity provider should be signed to indicate it hasn't been tampered with by an unauthorized third-party.

You will need to configure Auth0 to validate the responses' signatures by obtaining a signing certificate form the identity provider and loading the certificate from the identity provider into your Auth0 Connection:

1. Navigate to [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise), and select **SAML**.
2. Select the name of the connection to view.
3. Locate **X509 Signing Certificate**, and upload the certificate.
4. Select **Save Changes**.

Auth0 can accept a signed response for the assertion, the response, or both.

### Receive encrypted SAML authentication assertions

If Auth0 is the SAML service provider, it may need to receive encrypted assertions from an identity provider. To do this, you must provide the tenant's public key certificate to the IdP. The IdP encrypts the SAML assertion using the public key and sends it to Auth0, which decrypts it using the tenant's private key.

Use the following links to obtain the public key in different formats:

* <AuthLink href="https://{yourDomain}/cer?cert=connection">CER</AuthLink>
* <AuthLink href="https://{yourDomain}/pem?cert=connection">PEM</AuthLink>
* <AuthLink href="https://{yourDomain}/rawpem?cert=connection">raw PEM</AuthLink>
* <AuthLink href="https://{yourDomain}/pb7?cert=connection">PKCS#7</AuthLink>
* <AuthLink href="https://{yourDomain}/fingerprint?cert=connection">Fingerprint</AuthLink>

Download the certificate in the format requested by the IdP.

### Use your key pair to decrypt encrypted responses

As noted above, Auth0 will by default use your tenant's private/public key pair to handle encryption. You can also provide your own public/private key pair if an advanced scenario requires so.

Changing the key pair used to encrypt and decrypt requests in the connection can't be done on the Dashboard UI, so you will have to use the [Update a Connection endpoint](https://auth0.com/docs/api/management/v2#!/Connections/patch_connections_by_id) from the Management API v2, and add a `decryptionKey` property to the `options` object, as shown in the payload example below.

Updating the `options` object for a connection overrides the whole `options` object. To keep previous connection options, get the existing `options` object and add new key/values to it.

Endpoint: `https://{yourDomain}/api/v2/connections/{yourConnectionId}`

Payload:

```json lines theme={null}
{
	{ 
		"options" : {
			[...], // all the other connection options
		  "decryptionKey": {
				"key":"-----BEGIN PRIVATE KEY-----\n...{your private key here}...\n-----END PRIVATE KEY-----",
				"cert":"-----BEGIN CERTIFICATE-----\n...{your public key cert here}...\n-----END CERTIFICATE-----"
			}
	}
}
```

The SAML metadata available for the connection will be updated with the provided certificate so that the identity provider can pick it up to sign the SAML response.

## Auth0 as the SAML identity provider

This scenario applies when Auth0 is the SAML identity provider for an application. This is represented in the Dashboard by an **Application** that has the SAML Web App Addon enabled.

### Sign the SAML responses/assertions

If Auth0 is the SAML identity provider, it will sign SAML assertions with the tenant's private key and provide the service provider with the public key/certificate necessary to validate the signature.

To sign the SAML assertions:

1. Go to [Auth0 Dashboard > Applications](https://manage.auth0.com/#/applications), and select the name of the application to view.
2. Scroll to the bottom of the **Settings** page, select **Show Advanced Settings**, and select the **Certificates** view.
3. Select **Download Certificate**, and select the format in which you'd like to receive your signing certificate.
4. Send your certificate to the service provider.

By default, Auth0 signs the SAML **assertion** within the response. To sign the SAML **response** instead:

1. Navigate to [Auth0 Dashboard > Applications](https://manage.auth0.com/#/applications), and select the name of the application to view.

2. Select the **Addons** view.

3. Select **SAML2 Web App** to view its settings, and locate the **Settings** code block.

4. Locate the **`"signResponse"`** key. Uncomment it (or add it, if required), then set its value to `true` (the default value is `false`). The configuration should look like this:

   ```json lines theme={null}
   {
     [...], // other settings
     "signResponse": true
   }
   ```

#### Change the signing key for SAML responses

By default, Auth0 will use the private/public key pair assigned to your tenant to sign SAML responses or assertions. For very specific scenarios, you might wish to provide your own key pair. You can do so with a rule like this:

```javascript lines expandable theme={null}
/**
* Handler that will be called during the execution of a PostLogin flow.
*
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {

    // replace with the ID of the application that has the SAML Web App Addon enabled
      // for which you want to change the signing key pair.
      const samlIdpClientId = 'YOUR_SAML_APP_CLIENT_ID';

    // only do this for the specific client ID.  If you have multiple IdPs that require 
    // custom certificates, you will have an "if" statement for each one.  
    if (event.client.client_id === samlIdpClientId) {

    // provide your own private key and certificate here  
    // see https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations/work-with-certificates-and-keys-as-strings 
    // for formatting instructions basically you start with a PEM format certificate and
    // replace the line enedings with "\n"
    const signingCert = "-----BEGIN CERTIFICATE-----\nnMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV[..all the other lines..]-----END CERTIFICATE-----\n";
    const signingKey = "-----BEGIN PRIVATE KEY-----\nnMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV[..all the other lines..]-----END PRIVATE KEY-----\n";

    api.samlResponse.setCert(signingCert)    
    api.samlResponse.setKey(signingKey);

  }
  };
```

To learn how to turn the private key and certificate files into strings that you can use in a rule, see [Work with Certificates and Keys and Strings](/docs/authenticate/protocols/saml/saml-sso-integrations/work-with-certificates-and-keys-as-strings).

### Receive signed SAML authentication requests

If Auth0 is the SAML identity provider, it can receive requests signed with the service provider's private key. Auth0 uses the public key/certificate to validate the signature.

To configure signature validation:

1. Download the service provider's certificate with the public key.

2. Navigate to [Auth0 Dashboard > Applications](https://manage.auth0.com/#/applications), and select the name of the application to view.

3. Select the **Addons** view.

4. Select **SAML2 Web App** to view its settings, and locate the **Settings** code block.

5. Locate the **`"signingCert"`** key. Uncomment it (or add it, if required), then set its value to the certificate you downloaded from the service provider. The configuration should look like this:

   ```json lines theme={null}
   {
     [...], // other settings
     "signingCert": "-----BEGIN CERTIFICATE-----\nMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV\n[..all the other lines..]-----END CERTIFICATE-----\n"
   }
   ```

### Send encrypted SAML authentication assertions

If Auth0 is the SAML identity provider, you can use [Actions](/docs/customize/actions) to encrypt the SAML assertions it sends.

You must obtain the certificate and the public key from the service provider. If you only got the certificate, you can derive the public key using `openssl`. Assuming that the certificate file is named `certificate.pem`, you can run:

`openssl x509 -in certificate.pem -pubkey -noout > public_key.pem`

Once you get the certificate and public key files, you must [turn them into strings](/docs/authenticate/protocols/saml/saml-sso-integrations/work-with-certificates-and-keys-as-strings) to use them in an Action. The Action will look like this:

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {

// this Action sets a specific public key to encrypt the SAML assertion generated from Auth0
  if (
    event.client.client_id ===
    "THE_CLIENT_ID_OF_THE_APP_WITH_THE_SAML_APP_ADDON"
  ) {
    const encryptionCert =
      "-----BEGIN CERTIFICATE-----\nnMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV[..all the other lines..]-----END CERTIFICATE-----\n";
    const encryptionPublicKey =
      "-----BEGIN PUBLIC KEY-----\nnMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV[..all the other lines..]-----END PUBLIC KEY-----\n";

    api.samlResponse.setEncryptionCert(encryptionCert);
    api.samlResponse.setEncryptionPublicKey(encryptionPublicKey);
  }
};
```

The following algorithms are used:

* [AES256](http://www.w3.org/2001/04/xmlenc#aes256-cbc) for assertion encryption
* [RSA-OAEP](http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p) (including MGF1 and SHA1) for key transport

## Learn more

* [Work with Certificates and Keys as Strings](/docs/authenticate/protocols/saml/saml-sso-integrations/work-with-certificates-and-keys-as-strings)


# Work with Certificates and Keys as Strings
Source: https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations/work-with-certificates-and-keys-as-strings

Describes how to work with certificates or keys in rules or Management API requests to require a string representation of the file.

You can use the following command in a UNIX shell to concatenate a PEM-formatted certificate with `\n` (escaped new-line):

```bash wrap lines theme={null}
awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' certificate.pem | pbcopy
```

This copies the value into to your clipboard buffer so you can paste it where needed.

### More information

When working with certificates or keys in rules or <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> v2 requests, you will most likely require a string representation of the file.

If you open a certificate file (`cer`, `pem`) with a text editor, you'll see something like this:

```text lines theme={null}
-----BEGIN CERTIFICATE-----
MIICzDCCAbQCCQDH8GvxPIeH+DANBgkqhkiG9w0BAQsFADAoMQswCQYDVQQGEwJh
cjEZMBcGA1UEAwwQaHR0cHM6Ly9uaWNvLmNvbTAeFw0xOTA0MDgxODA3NTVaFw0y
//
// more lines of base64-encoded information
//
nSWyabd+LiBGtLTMB+ZLbOIi3EioWPGw/nHOI8jzPrqhiCLuZCSQmiqrLQYNsc1W
-----END CERTIFICATE-----
```

The lines between the `-----BEGIN CERTIFICATE-----` header and `-----END CERTIFICATE-----` footer contain base64-encoded binary information. Public keys and private keys (.key files) will look similar, with just a different header/footer.

For a string representation of a certificate/key file, you will need to concatenate everything in one line, with a `\n` (escaped new-line) sequence replacing the actual new lines in the file. So from the above sample you'd obtain something like this:

```text lines theme={null}
"-----BEGIN CERTIFICATE-----
\nMIICzDCCAbQCCQDH8GvxPIeH+DANBgkqhkiG9w0BAQsFADAoMQswCQYDVQQGEwJh\n
[..all the other lines..]
-----END CERTIFICATE-----\n"
```

## Learn more

* [Configure Auth0 as SAML Identity Provider](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider)
* [Configure Auth0 as SAML Service Provider](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider)


# System for Cross-domain Identity Management (SCIM)
Source: https://auth0.com/docs/authenticate/protocols/scim

Describes using System for Cross-domain Identity Management (SCIM) schema in identity management

SCIM (System for Cross-domain Identity Management) is a set of application-level protocols to securely manage and communicate user data across multiple domains. SCIM clients can be integrated to manage CRUD (create, replace, update, delete) operations, apply queries and filters, and create user groups within your organization. SCIM allows you to automate user lifecycles and maintain user accounts across platforms.

To read the SCIM specification, read [System for Cross-domain Identity Management: Core Schema](https://datatracker.ietf.org/doc/rfc7643/).

### SCIM with Auth0

Auth0 supplies an extensible, flexible directory designed to support CIAM use cases and focuses on simplifying identity for direct-to-consumer and software-as-a-service applications.

In an Auth0 tenant, you can use isolated directories via Enterprise, Social, or Database connections. To learn more about available connections, read [Identity Providers](/docs/authenticate/identity-providers) or [Database Connections](/docs/authenticate/database-connections).

Auth0 supports inbound SCIM for selected Enterprise <Tooltip href="/docs/glossary?term=Identity+Providers">Identity Providers</Tooltip>. To learn more, read [Configure Inbound SCIM](/docs/authenticate/protocols/scim/configure-inbound-scim).


# Configure Inbound SCIM
Source: https://auth0.com/docs/authenticate/protocols/scim/configure-inbound-scim

Overview of how to configure Inbound SCIM for Enterprise connections

<Card title="Before you start">
  Your Auth0 plan or custom agreement must include Enterprise Connections to use this feature. To learn more, read [Auth0's Pricing Page](https://auth0.com/pricing).

  [Postman](https://www.postman.com/downloads/) must be installed on a local machine to test your Inbound SCIM connections.
</Card>

[SCIM](/docs/authenticate/protocols/scim) is a [protocol](https://tools.ietf.org/html/rfc7644) and [schema](https://tools.ietf.org/html/rfc7643) standard used by enterprise organizations to provision, de-provision, and manage user identity-related information.

Auth0's Inbound SCIM feature supports B2B SaaS developer integrations with Enterprise <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip>. The following Auth0 connection types are currently supported: [SAML](/docs/authenticate/identity-providers/enterprise-identity-providers/saml), [OpenID Connect](/docs/authenticate/identity-providers/enterprise-identity-providers/oidc), [Okta Workforce Identity](/docs/authenticate/identity-providers/enterprise-identity-providers/okta), and [Microsoft Azure AD / Entra ID](/docs/authenticate/identity-providers/enterprise-identity-providers/azure-active-directory/v2).

<Callout icon="file-lines">
  Google Workspace user provisioning is supported through Directory Sync. To sync users from Google Workspace to Auth0, read [Sync Google Workspace Users to Auth0 with Directory Sync](/docs/authenticate/identity-providers/enterprise-identity-providers/google-directory-sync).
</Callout>

## Enable Inbound SCIM for an Enterprise Connection

1. Launch the [Auth0 Dashboard](https://manage.auth0.com/#/), then choose the tenant you want to configure.
2. Navigate to [**Authentication > Enterprise**](https://manage.auth0.com/#/connections/enterprise/)**,** then select from **SAML, OpenID Connect, Okta Workforce,** or **Microsoft Azure AD.**
3. Choose an existing connection or create a new one using [Create Connection](/docs/authenticate/database-connections/custom-db/create-db-connection).
4. Under the **Provisioning** tab for your connection, toggle **Sync user profile attributes at each login** to **Off,** then switch **Sync user profiles using SCIM** to **On.**
5. Select the **Setup** tab under **Sync user profiles using SCIM** to get the SCIM endpoint URL and SCIM tokens needed for testing with Postman.

### Test with Postman

You can download the Postman collection below to test your SCIM configuration:

* [SCIM 2.0 Postman Collection](https://cdn.auth0.com/scim/collections/scim_postman_collection.json)

1. Launch Postman, then select **File > Import…** and move the file **scim\_postman\_collection.json** into the import dialog box.
2. Select the **SCIM 2.0 Tests** collection, then choose the **Variables** tab.
3. Copy the **SCIM Endpoint URL** value from the Auth0 Dashboard and paste it into the **Current Value** field next to the **SCIM-ENDPOINT-URL** variable.
4. In the Auth0 Dashboard choose **Generate New Token**, then pick **Generate Token** and select **Copy and Close.**
5. Switch back to Postman, select the **Authorization** tab, and paste the token value into the **Token** field.
6. Choose **Save.**
7. Run the tests in the order shown, starting with the `POST` command and finishing with `DELETE`. The result of each user operation is in your Auth0 Dashboard under [**User Management > Users**](https://manage.auth0.com/#/users)and in the tenant logs under [**Monitoring > Logs**](https://manage.auth0.com/#/logs).

To test with specific identity providers, see [Configure Inbound SCIM for Identity Providers using SAML or OpenID](/docs/authenticate/protocols/scim/configure-inbound-scim-for-identity-providers-using-saml-or-openid).

## Supported SCIM Operations

Auth0 supports the following SCIM 2.0 operations for managing users:

<table>
  <thead>
    <tr>
      <th>Command</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>POST</code></td>
      <td>Creates a user in Auth0 with attributes from the SCIM 2.0 core schema and enterprise schema extension, described in <a href="https://tools.ietf.org/html/rfc7644#section-3.3">RFC7644 Section 3.3</a>.</td>
    </tr>

    <tr>
      <td><code>GET</code></td>
      <td>Retrieves a user that has already been created in Auth0, using their user\_id value in Auth0 and described in <a href="https://tools.ietf.org/html/rfc7644#section-3.4.1">RFC7644 Section 3.4.1</a>.</td>
    </tr>

    <tr>
      <td><code>PUT</code></td>
      <td>Replaces a user in Auth0 with attributes from the SCIM 2.0 core schema and enterprise schema extension, described in <a href="https://tools.ietf.org/html/rfc7644#section-3.5.1">RFC7644 Section 3.5.1</a>.</td>
    </tr>

    <tr>
      <td><code>PATCH</code></td>
      <td>Updates a user in Auth0 with attributes from the SCIM 2.0 core schema and enterprise schema extension, described in <a href="https://tools.ietf.org/html/rfc7644#section-3.5.2">RFC7644 Section 3.5.2</a>.</td>
    </tr>

    <tr>
      <td><code>DELETE</code></td>
      <td>Deletes a user in Auth0, using their user\_id value in Auth0, described in <a href="https://tools.ietf.org/html/rfc7644#section-3.6">RFC7644 Section 3.6</a>.</td>
    </tr>

    <tr>
      <td><code>SEARCH</code></td>
      <td>Searches for a user in Auth0 using a SCIM filter, described in <a href="https://tools.ietf.org/html/rfc7644#section-3.4.2">RFC7644 Section 3.4.2</a>. Supported operators are Equals (EQ), and (AND), and or (OR).</td>
    </tr>

    <tr>
      <td><code>PUT</code> (Deactivate)</td>
      <td>Replaces a user stored in Auth0 and sets the SCIM active attribute to false, which results in the user being blocked in Auth0.</td>
    </tr>

    <tr>
      <td><code>PATCH</code> (Deactivate)</td>
      <td>Updates a user stored in Auth0 and sets the SCIM active attribute to false, which results in the user being blocked in Auth0.</td>
    </tr>
  </tbody>
</table>

Auth0 uses the SCIM 2.0 [core schema for user resources](https://tools.ietf.org/html/rfc7643) and [Enterprise schema for user resources](https://tools.ietf.org/html/rfc7643), as well as client authentication bearer tokens for broad compatibility with multiple Enterprise identity providers.

### SCIM endpoints and tokens

Each enterprise customer gets a connection-specific SCIM endpoint and token that allows them to provision, de-provision, and manage their user accounts stored in the Auth0 tenant.

The endpoints and tokens are visible and configurable in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> at **Authentication > Enterprise > \[connecton-type] > \[your-connection] > Provisioning >  Sync user profiles using SCIM >  Setup**.

<Frame>
  <img alt="Dashboard screenshot of SCIM setup" />
</Frame>

The **SCIM Endpoint URL** allows SCIM clients to manage user accounts stored in Auth0 for a given identity provider.

The **Generate New Token** option generates up to two active tokens for this SCIM endpoint, allowing the token used by the SCIM client to be updated without downtime. Tokens may also be revoked on this screen by choosing **Delete**.

<Frame>
  <img alt="Dashboard screen for the SCIM token settings" />
</Frame>

The following token generation settings are available:

* **No expiration date:** Select whether the token expires or not.
* **Expiration date in seconds**: if the token has no expiration date, you can choose an expiration time for the token. When the token expires, the SCIM endpoint will return an error response the next time it is used. The minimum allowed expiration time is 900 seconds.
* **List of permissions (scopes):** details which SCIM operations may be performed using this token. The available permissions are:

  * **get:users** - Allows users to be retrieved and searched.
  * **post:users** - Allows users to be created
  * **put:users** - Allows users to be updated using the PUT method.
  * **patch:users** - Allows users to be updated using the PATCH method.
  * **delete:users** - Allows users to be deleted.

### Attribute mapping

Each new connection uses the default attribute map found in the Auth0 Dashboard at **Authentication > Enterprise > \[connecton-type] > \[your-connection] > Provisioning >  Sync user profiles using SCIM >  Mapping,** where the map can be edited and customized to fit your connection's needs.

Core SCIM user attributes defined [RFC 7643 sections 3.1, 4.1,  and 4.3](https://tools.ietf.org/html/rfc7643) may be used.

<table>
  <thead>
    <tr>
      <th>Notes</th>

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>One-to-one mapping</td>
      <td>A selected SCIM attribute (or sub-attribute) can only be mapped to one Auth0 attribute.</td>
    </tr>

    <tr>
      <td>Sub-attribute mapping</td>
      <td>Sub-attribute values within multi-value SCIM attributes such as emails and phoneNumbers can be referenced using SCIM filter syntax with the eq operator. See the default attribute maps for examples.</td>
    </tr>

    <tr>
      <td>Unmappable attributes</td>
      <td>The SCIM id and meta attributes cannot be mapped,  as they are only sent by Auth0 in the SCIM protocol responses. The id value in SCIM responses is always set to the Auth0 user\_id, and the SCIM  password  attribute is not usable for Enterprise connections.</td>
    </tr>

    <tr>
      <td>Omitting SCIM attributes</td>
      <td>If a specific SCIM attribute is not configured to be handled in your attribute map, it will be ignored in all SCIM requests and responses.</td>
    </tr>
  </tbody>
</table>

These SCIM attributes can be mapped to Auth0 [root](/docs/manage-users/user-accounts/user-profiles/root-attributes) and [metadata](/docs/manage-users/user-accounts/metadata/metadata-fields-data) attributes on the user profile.

<table>
  <thead>
    <tr>
      <th>Notes</th>

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>One-to-one mapping</td>
      <td>A selected Auth0 attribute can only be mapped to one SCIM attribute.</td>
    </tr>

    <tr>
      <td>Root attribute mapping</td>
      <td>When mapping to <a href="/docs/manage-users/user-accounts/user-profiles/root-attributes">root</a> attributes, note that only the root attributes listed in <a href="/docs/manage-users/user-accounts/user-profiles/user-profile-structure#user-profile-attributes">User profile attributes</a> can be searched using a SCIM query. If you need an attribute to be searchable that is not in this list, place it in app\_metadata.</td>
    </tr>

    <tr>
      <td>Metadata attribute mapping</td>
      <td>The use of user\_metadata is allowed, but generally not recommended for synchronized attributes as it is intended to store attributes that can be edited directly by the end user. Use app\_metadata or root attributes instead.</td>
    </tr>

    <tr>
      <td>Blocked attribute behavior</td>
      <td>The mapping to the Auth0 blocked attribute has a special behavior when it is mapped to the SCIM active attribute. When active contains a value of true or false, Auth0 reverses the value and sets Auth0 blocked attribute to false or true, respectively.</td>
    </tr>
  </tbody>
</table>

Auth0 also allows you to provision attributes using SCIM in parallel with attributes provisioned during login. For more information, see **Sync additional attributes at login** below.

### Logs and outbound notifications

You can view the full details of all the SCIM requests that Auth0 receives in the [**Monitoring > Logs**](https://manage.auth0.com/#/logs) section of the Auth0 Dashboard. In addition, you can integrate with [Custom Log Streams](/docs/customize/log-streams) to be notified when a user is created, updated, or deleted using SCIM and the SCIM log stream [filter category](/docs/customize/log-streams/event-filters#scim-events).

### Session revocation and backchannel logout

When Auth0 receives a SCIM message to deactivate and block a user, it terminates all Auth0 sessions for the user, revokes <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip>, and (if configured) triggers [OpenID Connect backchannel logout](/docs/authenticate/login/logout/back-channel-logout/configure-back-channel-logout) for your applications.

## Deployment guidelines

#### Leverage integration galleries for streamlined setup

To give your customers a tailored experience for setting up both SCIM and <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip>, consider listing your application in the [Okta Integration Network](https://www.okta.com/integrations/) and other workforce identity provider integration galleries that you plan to integrate with.

#### Test SCIM in lower-level environments first

Do not enable SCIM in a production Auth0 tenant before thoroughly testing your integration in a development or staging Auth0 tenant.

#### Send SCIM tokens securely

Never send SCIM tokens in plaintext, over email, or via insecure channels. Use a secure communication service like [SendSafely](https://www.sendsafely.com/) or integrate your app's self-service console with the [Auth0 Management API](/docs/authenticate/protocols/scim/manage-an-inbound-scim-deployment-with-the-management-api) to issue SCIM tokens directly to your customers.

#### Information exchange

When providing an Auth0 SCIM endpoint to your customer, they will require the following information to use it successfully:

* The SCIM endpoint URL for the Auth0 connection
* The SCIM token required for the SCIM endpoint URL

These are also recommended:

* The list of SCIM attributes supported for the Auth0 connection, as configured in your SCIM attribute map
* Any additional instructions required to configure their SCIM client to work with your SCIM configuration. For Okta Workforce and Microsoft Entra ID setup guidance, see [Configure Inbound SCIM for Identity Providers using SAML or OpenID](/docs/authenticate/protocols/scim/configure-inbound-scim-for-identity-providers-using-saml-or-openid)

## Advanced topics

#### Sync additional attributes at login

If you are integrating with an identity provider that does not support the same set of user attributes across <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip>/OIDC, and SCIM, you can access the additional attributes by enabling **Sync user profile attributes at login** in parallel with SCIM provisioning.

When **Sync user profile attributes at login** is enabled, all [root](/docs/manage-users/user-accounts/user-profiles/root-attributes) attributes on the user profile are overwritten each time a user logs in. To avoid potential conflicts between SCIM and login sync, follow these guidelines:

* Ensure common Auth0 root attributes like `email` and `username` are mapped in your [SAML](/docs/authenticate/protocols/saml/saml-configuration) or [OpenID Connect](/docs/authenticate/identity-providers/enterprise-identity-providers/configure-pkce-claim-mapping-for-oidc) attribute map if they are also present in your SCIM attribute map.
* In your SCIM attribute map, map all of the other SCIM attributes (except the `active` attribute) to values inside the Auth0 `app_metadata` attribute.

#### Sync roles

Auth0 supports syncing the SCIM 2.0 `roles` user attribute as defined in [RFC7643](https://datatracker.ietf.org/doc/html/rfc7643). To accept roles, ensure the SCIM attribute map for your connection maps the SCIM `roles` attribute to an Auth0 user attribute like `app_metadata.roles`.

To learn how to sync application-specific roles from Okta Workforce Identity, read [How to Add Multi-value Roles in SCIM Cloud Integration](https://support.okta.com/help/s/article/How-to-add-multivalue-roles-in-SCIM-Cloud-integration). For Microsoft Entra ID roles, read [Customize user provisioning attribute-mappings for SaaS applications in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/customize-application-attributes#provisioning-a-role-to-a-scim-app).

#### Sync groups

Auth0 does not support a `/groups` endpoint for provisioning full group objects and group memberships as defined in [RFC7644 Section 3.2](https://datatracker.ietf.org/doc/html/rfc7644#section-3.2). However, if an identity provider supports sending a list of groups over SAML or <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect, read the previous section for guidelines on how to sync attributes at login.

#### Organizations

For SCIM-provisioned users to become members of an Organization, the connection must be configured to **Enable Auto-Membership** as described in [Grant Just-In-Time Membership to an Organization Connection](/docs/manage-users/organizations/configure-organizations/grant-just-in-time-membership).

#### Account linking

When using [user account linking](/docs/manage-users/user-accounts/user-account-linking), the SCIM-provisioned user account must be set as the primary user account. Setting as a secondary account will change the SCIM `id` attribute which goes against the [SCIM 2.0 core schema specification](https://datatracker.ietf.org/doc/html/rfc7643#section-3.1). Account linking Enterprise user accounts to social and personal user accounts is not recommended.

## Learn more

* [Configure Inbound SCIM for Identity Providers using SAML or OpenID](/docs/authenticate/protocols/scim/configure-inbound-scim-for-identity-providers-using-saml-or-openid)
* [Inbound SCIM for Okta Workforce Connections](/docs/authenticate/protocols/scim/inbound-scim-for-okta-workforce-connections)
* [Inbound SCIM for Okta Workforce SAML Connections](/docs/authenticate/protocols/scim/inbound-scim-for-okta-workforce-saml-connections)
* [Inbound SCIM for Azure AD SAML Connections](/docs/authenticate/protocols/scim/inbound-scim-for-azure-ad-saml-connections)
* [Inbound SCIM for New Azure AD Connections](/docs/authenticate/protocols/scim/inbound-scim-for-new-azure-ad-connections)
* [Inbound SCIM for Older Azure AD Connections](/docs/authenticate/protocols/scim/inbound-scim-for-older-azure-ad-connections)


# Configure Inbound SCIM for Identity Providers using SAML or OpenID
Source: https://auth0.com/docs/authenticate/protocols/scim/configure-inbound-scim-for-identity-providers-using-saml-or-openid

Walkthrough for Other Identity Provider Setup via OpenID or SAML SCIM

#### SAML Identity Providers

Any <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> using a [SAML Connection type](/docs/authenticate/identity-providers/enterprise-identity-providers/saml) must support outbound user provisioning using a SCIM 2.0 client or be used in concert with an external provisioning service that provides outbound user provisioning. Review the [official SCIM documentation](https://scim.cloud/#Implementations2) for a list of known SCIM 2.0 client implementations.

For instructions on how to configure SCIM for specific SAML identity providers, read [Inbound SCIM for Okta Workforce SAML Connections](/docs/authenticate/protocols/scim/inbound-scim-for-okta-workforce-saml-connections) and [Inbound SCIM for Azure AD SAML Connections](/docs/authenticate/protocols/scim/inbound-scim-for-azure-ad-saml-connections)

#### OpenID Connect Identity Providers

Any <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect identity provider using an [OpenID Connect connection](/docs/authenticate/identity-providers/enterprise-identity-providers/oidc) must support outbound user provisioning using a SCIM 2.0 client or be used in concert with an external provisioning service that provides outbound user provisioning. Review the [official SCIM documentation](https://scim.cloud/#Implementations2) for a list of known SCIM 2.0 client implementations.

To enable full user lifecycle management, your OpenID Connect identity provider must be configured to send the same value in both the [ID token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) `sub` attribute and the SCIM `externalId` attribute. These values are typically the identity provider's unique system identifier for the user, which Auth0 uses to identify the user during login.

For instructions on how to configure SCIM for specific OpenID Connect identity providers, read [Inbound SCIM for Okta Workforce Connections](/docs/authenticate/protocols/scim/inbound-scim-for-okta-workforce-connections), [Inbound SCIM for New Azure AD Connections](/docs/authenticate/protocols/scim/inbound-scim-for-new-azure-ad-connections), and [Inbound SCIM for Older Azure AD Connections](/docs/authenticate/protocols/scim/inbound-scim-for-older-azure-ad-connections).


# Inbound SCIM for Microsoft Entra ID SAML Connections
Source: https://auth0.com/docs/authenticate/protocols/scim/inbound-scim-for-azure-ad-saml-connections

Walkthrough for Microsoft Entra ID (formerly Azure Active Directory) connection setup via SAML SCIM.

<Card title="Before you start">
  To use this feature, your Auth0 plan or custom agreement must include Enterprise Connections. To learn more, read [Auth0's Pricing Page](https://auth0.com/pricing).

  To test an inbound SCIM connection, you need to install [Postman](https://www.postman.com/downloads/) locally.
</Card>

To provision users to your Auth0 SCIM endpoint, you need to configure a non-gallery enterprise application in Microsoft Entra ID (formerly Azure Active Directory).

## Configure SCIM settings in Auth0

1. From the [<Tooltip href="/docs/glossary?term=Auth0%20Dashboard">Auth0 Dashboard</Tooltip>](https://manage.auth0.com/#/), go to **Authentication > Enterprise > SAML > \[YOUR\_AUTH0\_CONNECTION] > Provisioning**.
2. Toggle **Sync user profiles using SCIM** to on. This opens a new section on the same page with additional configuration.
3. Verify the following configuration:
   A. In the **Mapping** tab, make sure the **SCIM attribute containing the User ID** field is set to **userName**.
   B. In the **Additional Mappings** section, verify the following values:
   ```json lines theme={null}
   {
       "scim": "emails[type eq \"work\"].value",
       "auth0": "email"
   },
   ```
   You can also view the [attribute mapping](/docs/authenticate/protocols/scim/configure-inbound-scim#attribute-mapping) and make sure the extended SCIM attributes are mapped to your preferred Auth0 attributes.
4. If necessary, select **Save Changes**.

## Retrieve SCIM endpoint URL and token

To configure SCIM in a Microsoft Entra ID tenant, you need a SCIM endpoint URL and token from Auth0. You can get these values from the Auth0 Dashboard:

1. From the [Auth0 Dashboard](https://manage.auth0.com/#/), go to **Authentication > Enterprise > SAML > \[your-connection] > Provisioning**.
2. In the **Sync user profiles using SCIM > Setup** section, copy the **SCIM Endpoint URL**.
3. In the same section, under **Bearer Token**, select **Generate New Token**. Choose the token's expiration date and scopes, then select **Generate Token**. The default requires scopes used by Azure AD are `get:users`, `post:users`, `patch:users`, and `delete:users`.
4. Copy the bearer token. For security, this is the only time the token is visible.

You can also get these values programmatically using the Management API's SCIM endpoints, such as [`/v2/connections/{id}/scim-configuration/tokens`](https://auth0.com/docs/api/management/v2/connections/get-scim-tokens).

For best practices, read the [Configure Inbound SCIM deployment guidelines](/docs/authenticate/protocols/scim/configure-inbound-scim#deployment-guidelines).

## Configure SCIM in Entra ID for SAML apps

If your SAML application is not already registered, follow [Configure IdP-Initiated SAML Login with Azure as the IdP](https://support.auth0.com/center/s/article/Configure-IdP-Initiated-SAML-Login-with-Azure-as-the-IdP) to register a custom, non-gallery enterprise application in an Entra ID tenant.

Then, to configure SCIM:

1. From the Microsoft Entra admin center, navigate to **Entra ID > Enterprise apps > \[YOUR\_APPLICATION]**.
2. Continue to **Manage > Properties** and set **Assignment Required** to **Yes**.
3. Go to **Manage > Users and Groups** and assign the Azure AD users you want to provision. When you assign a <Tooltip href="/docs/glossary?term=Group">group</Tooltip>, the users from that group are provisioned.
4. Navigate to **Manage > Provisioning** and select **Get started**.
5. Set the **Provisioning Mode** to **Automatic**.
6. Expand the **Admin Credentials** section and configure the following parameters:
   * Set the **Tenant URL** field to the SCIM endpoint URL you saved in the previous step, and append the query parameter `?aadOptscim062020` to the end of the URL. This is [Microsoft's recommended workaround for a known SCIM 2.0 issue](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/application-provisioning-config-problem-scim-compatibility).
   * Set the **Secret Token** to the token value you saved in the previous step, then select **Save**.
7. Expand the **Mappings** section, then select **Provision Azure Active Directory Users** to open the **Attribute Mapping** screen.
   <Frame>
     <img alt="SAML Azure Attribute Mapping" />
   </Frame>
8. In the attribute mapping table row containing `emails[type eq "work"].value` and `mail`, select **Edit** to go to the **Edit Attribute** screen and configure the following parameters:
   * Set **Match objects using this attribute** to **Yes**.
   * Set **Matching precedence** to **2**.
9. Select **OK** to save the configuration. This closes the **Edit Attribute** screen. Then, on the **Attribute Mapping** screen, select **Save**.

## Testing

1. On the Enterprise application overview screen, go to **Manage > Provisioning > Provision on Demand** to test the SCIM connection.
2. Go to **Select a user or group** and enter the name of a user that you assigned to the application, then select the user and choose **Provision**. This creates the user in the Auth0 tenant.
3. Set the **Provisioning Status** to **On** in order to [provision all assigned users](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/configure-automatic-user-provisioning-portal#provisioning-status).


# Inbound SCIM for New Azure AD Connections
Source: https://auth0.com/docs/authenticate/protocols/scim/inbound-scim-for-new-azure-ad-connections

Walkthrough for Azure Connection Setup via OpenID SCIM

<Card title="Before you start">
  Ensure your Auth0 tenant is connected to Azure AD using the [Microsoft Azure AD connection type](/docs/authenticate/identity-providers/enterprise-identity-providers/azure-active-directory/v2).

  This integration will require two applications to be registered in Azure AD: the OpenID Connect integration and the SCIM integration. To streamline this setup process for your customers, consider [publishing your app in the Azure Active Directory app gallery](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-howto-app-gallery-listing#step-6---submit-your-app).
</Card>

Auth0 can be integrated with Microsoft Azure Active Directory (now known as Microsoft Entra ID) with the [Microsoft Azure AD connection type](/docs/authenticate/identity-providers/enterprise-identity-providers/azure-active-directory/v2), which uses the <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) protocol for user authentication. These instructions are for new Azure AD connections; for older connections using pairwise user identifiers (`sub)`, see [Older Connections](/docs/authenticate/protocols/scim/inbound-scim-for-older-azure-ad-connections).

### Configure SCIM settings in Auth0

1. Launch the [Auth0 Dashboard](https://manage.auth0.com/#/), go to **Authentication > Enterprise > Microsoft Azure AD > \[your-connection] > Settings.**
2. Ensure that **User ID Attribute Type** is set to **User Object Identifier (oid)** and **Use Common Endpoint** toggle is **Disabled**.
3. Select the **Provisioning tab** and disable **Sync user profile attributes at each login** unless you want to [sync additional attributes at login](/docs/authenticate/protocols/scim/configure-inbound-scim).
4. In the same section, enable **Sync user profiles using SCIM**.
5. Under the **Mapping** tab, ensure the **SCIM attribute containing the User ID** setting is set to **externalId**.
6. Review the **Additional Mappings** to ensure the extended SCIM attributes are mapped to your preferred Auth0 attributes. See [attribute mapping](/docs/authenticate/protocols/scim/configure-inbound-scim#attribute-mapping) for details.

### Retrieve SCIM endpoint URL and token

This section uses the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, but these steps can also be managed with the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. See the [Deployment Guidelines](/docs/authenticate/protocols/scim/configure-inbound-scim#deployment-guidelines) section for best practices.

1. In the [Auth0 dashboard](https://manage.auth0.com/#/), browse to the SCIM **Setup** tab, then copy the **SCIM Endpoint URL** and paste it somewhere safe.
2. Generate SCIM token by clicking **Generate New Token** and set an expiration date for the token if you wish.
3. Select the scopes you want to allow. The default scopes required by Azure AD are `get:users`, `post:users`, `patch:users`, and `delete:users`.

### Configure SCIM in Azure AD for OIDC Apps

1. Confirm that an OpenID Connect application has already been registered to handle user authentication in the **Microsoft Entra ID > App registrations** section of the [Azure portal](https://portal.azure.com).
2. Confirm that your OpenID Connect application has **Assignment Required** set to **Yes** in the **Microsoft Entra ID > Enterprise applications > \[your-oidc-app] > Manage > Properties** section, and has users assigned in the **Users and Groups** tab.
3. Next, register a new  **Non-gallery** application in the [Azure portal](https://portal.azure.com) by browsing to **Microsoft Entra ID > Enterprise applications > New application > Create your own application,** entering an application name, and selecting **Create**.
4. Go to the **Users and Groups** tab and assign the same Azure AD users and groups that are assigned to the registered OpenID Connect app.
5. Select the **Provisioning** tab, select **Get started**, and choose **Automatic** as the **Provisioning Mode.**
6. Select **Admin Credentials**, then enter the **SCIM Endpoint URL** value you saved earlier as the **Tenant URL**. At the end of the URL, add `?aadOptscim062020` query parameter to fix [known Azure AD issues described here.](https://learn.microsoft.com/en-us/azure/active-directory/app-provisioning/application-provisioning-config-problem-scim-compatibility)
7. Paste the token value into the **Secret Token** field and select **Save.**
8. Go to **Mappings** and select **Provision Microsoft Entra ID Users,** then go to **Attribute Mappings** and edit the attributes of the line containing `externalId` and `mailNickname`.
9. In the **Edit Attribute** screen, change **Source attribute** to **objectId,** then choose **OK**.
10. Go back to **Attribute Mappings** and select the line containing `emails[type eq "work"].value and mail`.
11. In the **Edit Attribute** screen, change **Match objects using this attribute** to **Yes**,thenset **Matching precedence** to **2** and choose **OK.** The attribute mapping screen looks like this as you continue to use the **Attribute Mappings** section to configure additional SCIM attributes:

<Frame>
  <img alt="SAML Azure Attribute Mapping" />
</Frame>

**Save** the attribute mappings, then select **X** in the upper-right corner to return to the **Provisioning** screen.

#### Testing

1. On the Enterprise application overview screen, select **Manage > Provisioning** and then **Provision on Demand** to test the SCIM connection.
2. Go to **Select a user or group** and type the name of a user that you assigned to the application, then select the user and choose **Provision**. This creates the user in the Auth0 tenant.
3. Provision all assigned users by [following the instructions](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/configure-automatic-user-provisioning-portal#provisioning-status) to set the **Provisioning Status** to **On**.


# Inbound SCIM for Okta Workforce Connections
Source: https://auth0.com/docs/authenticate/protocols/scim/inbound-scim-for-okta-workforce-connections

Walkthrough for Okta WIC Connection Setup via OpenID SCIM

<Card title="Before you start">
  Enable Okta Workforce Identity as an identity provider by following the instructions on the [Identity Providers help page](/docs/authenticate/identity-providers/enterprise-identity-providers/okta).

  This integration will require two applications to be registered in Okta Workforce: the OpenID Connect integration and the SCIM integration. The same users and groups must be assigned to both. To eliminate this requirement and streamline the setup process for your customers, [submit your app to the Okta Integration Network](https://developer.okta.com/docs/guides/submit-app-overview/).
</Card>

This section describes how to configure a custom <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect and SCIM app integration in an Okta Workforce Identity tenant, which can be used to provision users to your Auth0 SCIM endpoint.

For information on configuring a <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> and SCIM integration with Okta Workforce Identity, see [Inbound SCIM for Okta Workforce SAML Connections](/docs/authenticate/protocols/scim/inbound-scim-for-okta-workforce-saml-connections) instead.

### Configure SCIM settings in Auth0

1. Launch the [Auth0 Dashboard](https://manage.auth0.com/#/) and go to the **Authentication > Enterprise > Okta Workforce > \[your-connection] > Provisioning.**
2. Disable **Sync user profile attributes at each login** unless you want to [sync additional attributes at login](/docs/authenticate/protocols/scim/configure-inbound-scim).
3. In the same section, enable **Sync user profiles using SCIM**.
4. On the **Mapping** tab, ensure the **SCIM attribute containing the User ID** is set to **externalId**.

You can also check **Additional Mappings** to ensure the extended SCIM attributes are mapped to your preferred Auth0 attributes.

### Retrieve SCIM endpoint URL and token

1. In the Auth0 dashboard, browse to the SCIM **Setup** tab and copy the **SCIM Endpoint URL,** then paste it somewhere safe.
2. Select **Generate New Token** and set an optional expiration date for the token. You can optionally select the scopes you want to grant to Okta Workforce; the default requires scopes used by Okta Workforce are `get:users`, `post:users`, and `put:users`.

### Configure SCIM in Okta Workforce for OIDC Apps

1. Confirm that an OpenID Connect application [has already been registered](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm) in the Okta Workforce tenant for OIDC-based user authentication.
2. Confirm that your OpenID Connect application has [disabled Federation Broker Mode](https://help.okta.com/en-us/content/topics/apps/apps-fbm-main.htm).
3. Register a second application in the Okta portal by selecting **Applications** > **Applications,** then choose **Create App Integration, Secure Web Authentication**, and **Next**.
4. On the **General App Settings** page, set a name and a URL, then select **Do not display application icon to users**. The URL entered is not used in the SCIM integration.
5. Select **Finish**.
6. Navigate to the **General** tab, then choose **Edit** and go to the **Provisioning** section.
7. Choose **SCIM,** then **Save**.
8. Navigate to the integration's **Provisioning** tab and then the **Integration** tab.
9. Select **Edit,** then go to the **SCIM connector base URL** section and enter the **SCIM Endpoint URL** value you copied earlier.
10. For **Unique identifier field for users**, enter **userName**.
11. Under **Supported provisioning actions**, select **Push New Users** and **Push Profile Updates,** then choose **HTTP Header** as the **Authentication Mode.**
12. Paste the token value into the **Authorization** field, picking **Test Connection Configuration** if you want to test the connection. Choose **Save**.
13. Browse to **Provisioning > Settings > To App** and choose **Edit**.
14. Enable **Create Users, Update User Attributes,** and **Deactivate users.** Choose **Save**.
15. Under the **Attribute Mappings** section, use the **X** button to **delete** the following lines, which are not needed and may cause issues during PUT operations:

<table>
  <thead>
    <tr>
      <th>Attribute</th>
      <th>Value</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Primary email type</td>
      <td><code>(user.email != null && user.email != '') ? 'work' : ‘'</code></td>
    </tr>

    <tr>
      <td>Primary phone type</td>
      <td><code>(user.primaryPhone != null && user.primaryPhone != '') ? 'work' : ‘'</code></td>
    </tr>

    <tr>
      <td>Address type</td>
      <td><code>(user.streetAddress != null && user.streetAddress != '') ? 'work' : ‘'</code></td>
    </tr>
  </tbody>
</table>

Use the **Attribute Mappings** section to configure any additional SCIM attributes you want Okta WIC to send to your SCIM endpoint. If you add custom attributes, they must include a valid SCIM 2.0 external namespace property. For more information on external namespaces, read [Okta's help section](https://support.okta.com/help/s/article/Receiving-Invalid-externalNamespace-task-error-when-assigning-a-user-to-a-SCIMenabled-application).

You can now test user provisioning in the **Assignments** tab and test update operations by editing the user attributes in the **Directory > People** section of your Okta admin portal.


# Inbound SCIM for Okta Workforce SAML Connections
Source: https://auth0.com/docs/authenticate/protocols/scim/inbound-scim-for-okta-workforce-saml-connections

Walkthrough for Okta WIC Connection Setup via SAML SCIM

<Card title="Before you start">
  Create a [SAML Connection](/docs/authenticate/identity-providers/enterprise-identity-providers/saml) in your Auth0 tenant and [connect it to a corresponding custom SAML application](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_saml.htm) in your Okta Workforce Identity Dashboard.
</Card>

This section describes how to configure a custom <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> and SCIM app integration in an Okta Workforce Identity tenant, which can be used to provision users to your Auth0 SCIM endpoint.

### Configure SCIM settings in Auth0

1. Launch the [Auth0 Dashboard](https://manage.auth0.com/#/) and go to **Authentication > Enterprise > SAML > \[Connection] > Provisioning.**

2. Disable **Sync user profile attributes at each login** unless you want to [sync additional attributes at login](/docs/authenticate/protocols/scim/configure-inbound-scim).

3. In the same section, enable **Sync user profiles using SCIM**.

4. Under the **Mapping** tab, ensure the **SCIM attribute containing the User ID** setting is set to **userName**.

5. Review the **Additional Mappings** to ensure the extended SCIM attributes are mapped to your preferred Auth0 attributes, reviewing [attribute mapping](/docs/authenticate/protocols/scim/configure-inbound-scim#attribute-mapping) for details. If you receive phone numbers and physical addresses, note that Okta Workforce sends these as `phoneNumbers[primary eq true].value` and `addresses[primary eq true].*` by default.

6. Map the SCIM `userName` attribute to the Auth0 `email` attribute so Okta can [find and match existing users](https://developer.okta.com/docs/reference/scim/scim-20/#create-users) if this connection has already been deployed to production using the email address as the login ID and no Auth0 `username` attribute is set on the existing user profiles. In **Additional Mappings** find the following attribute pair:

   ```json lines theme={null}
   {
       "scim": "userName",
       "auth0": "username"
     }
   ```

   Replace it with the one below, then remove the mapping to `emails[primary eq true].value`.

   ```json lines theme={null}
   {
       "scim": "userName",
       "auth0": "email"
     }
   ```

7. Choose **Save Changes.**

### Retrieve SCIM endpoint URL and token

1. In the Auth0 dashboard, browse to the SCIM **Setup** tab and copy the **SCIM Endpoint URL,** then paste it somewhere safe.
2. Select **Generate New Token** and set an optional expiration date for the token. You can optionally select the scopes you want to grant to Okta Workforce; the default scopes used by Okta Workforce are `get:users`, `post:users`, and `put:users`.

### Configure SCIM in Okta Workforce for SAML Apps

1. Go to your Okta Workforce Identity SAML application, select the **General** tab, then choose **Edit** for **App Settings.**

2. In the **Provisioning** section, select **SCIM** and then **Save**.

3. Under the **General** tab, also confirm that [Federation Broker Mode](https://help.okta.com/en-us/content/topics/apps/apps-fbm-main.htm) is disabled.

4. Select the **Provisioning** tab, then go to **Integration** tab and select **Edit**.

5. Enter the **SCIM Endpoint URL** value you copied earlier into the **SCIM connector base URL** section.

6. For **Unique identifier field for users**, enter **userName**.

7. Under **Supported provisioning actions**, select `Push New Users` and `Push Profile Updates`, then choose **HTTP Header** as the **Authentication Mode.**

8. Paste the SCIM token into the **Authorization** field, then choose **Test Connection Configuration** if you want to test the new connection. Select **Save**.

   <Frame>
     <img alt="Inbound SCIM WIC Configuration" />
   </Frame>

9. Browse to **Provisioning > Settings > To App** and choose **Edit,** then enable the **Create Users, Update User Attributes,** and **Deactivate users** operations. Select **Save**.

   <Frame>
     <img alt="" />
   </Frame>

10. Under the **Attribute Mappings** section, use the **X** button to **delete** the following lines:

<table>
  <thead>
    <tr>
      <th>Attribute</th>
      <th>Value</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Primary email type</td>
      <td><code>(user.email != null && user.email != '') ? 'work' : ‘'</code></td>
    </tr>

    <tr>
      <td>Primary phone type</td>
      <td><code>(user.primaryPhone != null && user.primaryPhone != '') ? 'work' : ‘'</code></td>
    </tr>

    <tr>
      <td>Address type</td>
      <td><code>(user.streetAddress != null && user.streetAddress != '') ? 'work' : ‘'</code></td>
    </tr>
  </tbody>
</table>

Use the **Attribute Mappings** section to configure any additional SCIM attributes you want Okta WIC to send to your SCIM endpoint. If you add custom attributes, they must include a valid SCIM 2.0 external namespace property. For more information on external namespaces, read [Okta's help section](https://support.okta.com/help/s/article/Receiving-Invalid-externalNamespace-task-error-when-assigning-a-user-to-a-SCIMenabled-application).

You can now test user provisioning in the **Assignments** tab and test update operations by editing the user attributes in the **Directory > People** section of your Okta admin portal.


# Inbound SCIM for Older Azure AD Connections
Source: https://auth0.com/docs/authenticate/protocols/scim/inbound-scim-for-older-azure-ad-connections

OpenID Inbound SCIM for Older Azure Connections

<Card title="Before you start">
  Ensure your Auth0 tenant is connected to Azure AD using the [Microsoft Azure AD connection type](/docs/authenticate/identity-providers/enterprise-identity-providers/azure-active-directory/v2).

  This integration will require two applications to be registered in Azure AD: the OpenID Connect integration and the SCIM integration. To streamline this setup process for your customers, consider [publishing your app in the Azure Active Directory app gallery](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-howto-app-gallery-listing#step-6---submit-your-app).
</Card>

Auth0 can integrate with Microsoft Azure Active Directory (now known as Microsoft Entra ID) with the [Microsoft Azure AD connection type](/docs/authenticate/identity-providers/enterprise-identity-providers/azure-active-directory/v2), which uses the <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) protocol for user authentication. This section describes how to configure a non-gallery enterprise application to manage user accounts in update- and delete-only mode, which makes it possible to use SCIM with older Azure AD connections in which [pairwise IDs](https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference#use-claims-to-reliably-identify-a-user) are present.

For new connections, see [New Connections](/docs/authenticate/protocols/scim/inbound-scim-for-new-azure-ad-connections).

### Configure SCIM settings in Auth0

1. In your [Auth0 Dashboard](https://manage.auth0.com/#/), go to **Authentication > Enterprise > Microsoft Azure AD > \[your-connection] > Settings.**
2. Ensure that **User ID Attribute Type** is set to **Pairwise Subject Identifier (sub)** and the **Use Common Endpoint** toggle is **Disabled**.
3. Select the **Provisioning** taband enable both **Sync user profile attributes at each login** and **Sync user profiles using SCIM**.
4. On the **Mapping** tab, ensure the **SCIM attribute containing the User ID** setting is set to **externalId**.
5. Review the **Additional Mappings** to ensure the extended SCIM attributes are mapped to your preferred Auth0 attributes. See [attribute mapping](/docs/authenticate/protocols/scim/configure-inbound-scim#attribute-mapping) for details.

### Retrieve SCIM endpoint URL and token

This section uses the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, but you can also complete these steps with the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. See the [Deployment Guidelines](/docs/authenticate/protocols/scim/configure-inbound-scim#deployment-guidelines) section for best practices.

1. In the Auth0 dashboard, navigate to the SCIM **Setup** tab and copy the **SCIM Endpoint URL**. Make note of this URL as you will need to provide it in a future step.
2. Generate SCIM token by clicking **Generate New Token** and set an expiration date for the token if desired.
3. Select the following scopes: `get:users`, `patch:users`, and `delete:users`.

### Configure SCIM in Azure AD for OIDC Apps

1. Confirm that an OpenID Connect application has already been registered for your app in the **Microsoft Entra ID > App registrations** section of the [Azure portal](https://portal.azure.com).
2. Next, register a new **Non-gallery** application in the [Azure portal](https://portal.azure.com) by browsing to **Microsoft Entra ID > Enterprise applications > New application > Create your own application,** entering an application name, and selecting **Create**.
3. Go to the **Users and Groups** tab and assign the Azure AD users and groups who currently have access.
4. Select the **Provisioning** tab, select **Get started**, and choose **Automatic** as the **Provisioning Mode.**
5. Select **Admin Credentials**, then enter the **SCIM Endpoint URL** value you saved earlier as the **Tenant URL**. At the end of the URL, add the `?aadOptscim062020` query parameter to fix [known Azure AD issues](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/application-provisioning-config-problem-scim-compatibility).
6. Paste the token value into the **Secret Token** field and select **Save.**
7. Go to **Mappings** and select **Provision Azure Active Directory Users,** then find **Provision Azure Active Directory Users** and deselect **Create** under **Target Object Actions.**

   <Frame>
     <img alt="Azure AD Mappings for Inbound SCIM " />
   </Frame>
8. Go to **Attribute Mappings** and edit the attributes of the line containing `externalId` and `mailNickname`
9. On the **Edit Attribute** screen, change **Source attribute** to **objectId,** then choose **OK**.
10. Return to **Attribute Mappings** and select the line containing `emails[type eq "work"].value` and `mail`
11. On the **Edit Attribute** screen, change **Match objects using this attribute** to **Yes,** thenset **Matching precedence** to **2** and choose **OK.**

    <Frame>
      <img alt="Edit Attribute in Azure AD for Inbound SCIM " />
    </Frame>
12. Choose **Save** to save the attribute mappings. The following view appears:

    <Frame>
      <img alt="Attribute Mapping on Azure for Inbound SCIM" />
    </Frame>
13. Select **X** in the upper-right corner to return to the **Provisioning** screen.

#### Testing

1. On the Enterprise application overview screen, select **Manage > Provisioning** and then **Provision on Demand** to test the SCIM connection.
2. Go to **Select a user or group** and type the name of a user that you assigned to the application, then select the user and choose **Provision**. If the user is not present in the Auth0 tenant, you receive an error. If the user is present in the Auth0 tenant, a message confirms that the user has been updated.
3. Turn on provisioning by following [Microsoft's instructions](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/configure-automatic-user-provisioning-portal#provisioning-status) to set the **Provisioning Status** to **On**.


# Manage an Inbound SCIM Deployment with the Management API
Source: https://auth0.com/docs/authenticate/protocols/scim/manage-an-inbound-scim-deployment-with-the-management-api

Manage an Inbound SCIM Deployment with the Management API

To learn more about the supported SCIM management operations and how to use them, go to the [Auth0 Management API Explorer](https://auth0.com/docs/api/management/v2) and expand the **Connections** tab. The <Tooltip href="/docs/glossary?term=management+API">management API</Tooltip> can enable, update, and remove the SCIM configuration for a selected connection, as well as create and delete SCIM tokens.

### Register a client app for management API communication

To use the Auth0 management API, register a machine-to-machine client application that has the permissions necessary to manage your SCIM configuration.

1. From the [Auth0 Dashboard](https://manage.auth0.com/#/), select **Applications**.
2. Select **Create Application**.
3. Enter a name, select **Machine to Machine App**, and select **Create**.
4. On your new app, select the **APIs** tab, and set **Auth0 Management API** to **Authorized**.
5. Under **Permissions**, select `read:scim_config`, `create:scim_config`, `update:scim_config`, `delete:scim_config`, `create:scim_token`, `read:scim_token`, and `delete:scim_token.`
6. Select **Update**.
7. Follow the instructions in [Management API Access Tokens](/docs/secure/tokens/access-tokens/management-api-access-tokens) to learn how to get tokens and call the [Auth0 Management API v2](https://auth0.com/docs/api/management/v2/connections/post-scim-configuration) endpoints.


# Web Services Federation Protocol
Source: https://auth0.com/docs/authenticate/protocols/ws-fed-protocol

Describes how Auth0 works with the Web Services Federation (WS-Fed) protocol.

Web Services Federation (WS-Federation or <Tooltip href="/docs/glossary?term=WS-Fed">WS-Fed</Tooltip>) is part of the larger WS-Security framework and an extension to the functionality of WS-Trust. The features of WS-Federation can be used directly by SOAP applications and web services. WS-Fed is a protocol that can be used to negotiate the issuance of a token. You can use this protocol for your applications (such as a Windows Identity Foundation-based app) and for <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> (such as Active Directory Federation Services or Azure AppFabric Access Control Service).

## For applications

When you register an application in Auth0, it will automatically be assigned a WS-Fed endpoint of the form:

`https://{yourDomain}/wsfed/{yourClientId}`

You can find all available options for configuring WS-Fed under the [advanced settings](https://manage.auth0.com/#/applications/\{yourClientId}/settings) area for your application.

You will need to configure the **<Tooltip href="/docs/glossary?term=Relying+Party">Relying Party</Tooltip>**, which can be done using the following metadata endpoint:

`https://{yourDomain}/wsfed/FederationMetadata/2007-06/FederationMetadata.xml`

You can also use the **samlConfiguration** object, available in [rules](/docs/customize/rules), to configure claims sent via the token, as well as other lower-level WS-Fed and <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip>-P settings.

When redirecting your users to your WS-Fed endpoint, you can use the following (optional) parameters:

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>wa=wsignin1.0</code></td>
      <td>Whether Auth0 should issue a token for the relying party (default)</td>
    </tr>

    <tr>
      <td><code>wa=wsignout1.0</code></td>
      <td>Whether Auth0 should clear the user session/log the user out</td>
    </tr>

    <tr>
      <td><code>wreply=</code></td>
      <td>Where the response should be sent</td>
    </tr>

    <tr>
      <td><code>wctx=</code></td>
      <td>Your application's state</td>
    </tr>

    <tr>
      <td><code>whr=</code></td>
      <td>Connection to be used (allows users to skip the Auth0 login page)</td>
    </tr>

    <tr>
      <td><code>wfresh=0</code></td>
      <td>Whether the user must re-authenticate, even if there's a session in place (<code>0</code> requires re-authentication)</td>
    </tr>
  </tbody>
</table>

Here's a sample of what your URL with the optional parameters might look like:

`https://{yourDomain}/wsfed/{yourClientId}?whr=google-oauth2`

## Identity providers

If you're using Auth0 with an identity provider that uses the WS-Federation protocol (such as Active Directory Federation Services, Azure AppFabric Access Control Service, and IdentityServer), the easiest way to set up your integration is to create and use the ADFS connection type in the Dashboard. There are two ways to accomplish this:

* Import the Federation Metadata file
* Enable the Federation Metadata endpoint to check for changes

### Import Federation metadata file

When setting up an ADFS-based connection, you can import the required parameters by providing Auth0 with the Federation Metadata endpoint or by importing/uploading your federation metadata file.

<Frame>
  <img alt="Protocols WS-Fed Import Federation Metadata File ADFS Connection Screen" />
</Frame>

You will be presented with the instructions you need to finish configuring the integration.

### Enable the Federation Metadata endpoint

The federation metadata file contains information about the identity provider's certificates. If you provide the Federation Metadata endpoint (typically of the form ending with `/FederationMetadata/2007-06/FederationMetadata.xml`), Auth0 can check daily for changes in the configuration, such as the addition of a new signing certificate that was added in preparation for a rollover. Because of this, enabling the Federation Metadata endpoint is preferred to providing a standalone metadata file. If you provide a standalone metadata file, we will notify you via email when the certificates are close to their expiration date.

If the Federation Metadata contains both the primary and secondary certificates, you can use both in Auth0.

To roll over certificates using the Federation Metadata endpoint:

1. Generate a new certificate, and add it as the secondary certificate for your ADFS environment. This should be done at least **two days** before the expiration of your active primary certificate.
2. Allow Auth0 to obtain your new certificate from the Federation Metadata endpoint. Auth0 checks your endpoints once a day, so be sure to allow sufficient time for Auth0 to complete this step.
   Alternatively, you can manually complete this step by logging in to the Auth0 Dashboard, navigating to the appropriate ADFS connection, and click **Save**. This action results in Auth0 downloading the certificates immediately.
3. Set the now-secondary certificate as the primary certificate before the existing primary certificate expires in your ADFS environment.

##

## Learn more

* [Configure WS-Fed Applications](/docs/get-started/applications/configure-ws-fed-applications)


# Manage Users
Source: https://auth0.com/docs/manage-users

Learn about working with users, user profiles, and user metadata in Auth0.

<AuthDocsPipeline />

Auth0's hosted cloud database stores user data that is available to you via user profiles. The user information itself can come from a variety of sources, including identity providers, your own databases, and enterprise connections (such as Active Directory or SAML).

***

## Manage Users

##### Import, group, and administer users and control their access.

<Card title="User Accounts" href="/docs/manage-users/user-accounts">
  Migrate, find, organize, and administer user accounts and user data.
</Card>

<Card title="User Migration" href="/docs/manage-users/user-migration">
  Import users from external applications using custom database connections, the Auth0 Management API, or the User Import/Export extension.
</Card>

<Card title="User Search" href="/docs/manage-users/user-search">
  Retrieve user profile details using the Auth0 Management API.
</Card>

<Card title="Organizations" href="/docs/manage-users/organizations">
  Manage your partners and customers and control the ways that end-users access your applications.
</Card>

<Card title="My Account API" href="/docs/manage-users/my-account-api"> </Card>

***

## Manage Access

##### Control who can interact within your applications.

<Card title="Access Control" href="/docs/manage-users/access-control">
  Control users’ access to applications and information based on roles.
</Card>

<Card title="Sessions" href="/docs/manage-users/sessions">
  Define groups of interactions (such as page views, events, social interactions, and e-commerce transactions) between a user and an application that take place within a given timeframe.
</Card>

<Card title="Cookies" href="/docs/manage-users/cookies">
  Control how cookies work with your applications.
</Card>


# Auth0 Organizations
Source: https://auth0.com/docs/manage-users/organizations

Describes the Auth0 Organizations feature details.

<Card title="Availability varies by Auth0 plan">
  Both your specific login implementation and your Auth0 plan or custom agreement affect whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

The Organizations feature represents a broad update to the Auth0 platform that allows our business-to-business (B2B) customers to better manage their partners and customers, and to customize the ways that end-users access their applications and APIs. Auth0 customers can use Organizations to:

* Represent their business customers and partners in Auth0 and manage their membership.
* Configure branded, federated login flows for each business.
* Offer machine-to-machine access for their business customers and partners to consume their B2B APIs.
* Build administration capabilities into their products, using Organizations APIs, so that those businesses can manage their own organizations.

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/manage-users/organizations/organizations-overview">Understand How Auth0 Organizations Work</a></td>
      <td>How Auth0 Organizations work.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/organizations/create-first-organization">Create Your First Organization</a></td>
      <td>How to create and configure an Organization and define its behavior.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/organizations/custom-development">Custom Development</a></td>
      <td>How to extend Auth0 Organizations using metadata and rules or APIs and SDKs to create custom dashboards for your users.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/organizations/using-tokens">Work with Tokens</a></td>
      <td>How to work with tokens and Organizations.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/organizations/configure-organizations">Configure Organizations</a></td>
      <td>How to configure Organizations using the Dashboard or Management API.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/organizations/organizations-for-m2m-applications">Machine-to-Machine Access to Organizations</a></td>
      <td>How to configure and use Client Credentials access in the scope of Organizations.</td>
    </tr>
  </tbody>
</table>


# User Accounts
Source: https://auth0.com/docs/manage-users/user-accounts

Learn about working with user accounts in Auth0.

Auth0's hosted cloud database stores a variety of information on your users that is accessible to you. This information is available to you via a user profile, and your users are grouped by tenant. The user information itself can come from a variety of sources, including <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip>, your own databases, and enterprise connections (Active Directory, <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip>).

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/manage-users/user-accounts/manage-users-using-the-dashboard">Manage Users Using the Dashboard</a></td>
      <td>How to manage users in the Auth0 Dashboard.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/user-accounts/manage-users-using-the-management-api">Manage Users Using the Management API</a></td>
      <td>The elements of a user profile, how to create a user, and how to view users and their profile details.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/user-accounts/user-profiles">User Profiles</a></td>
      <td>The basics of Auth0 user profiles.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/user-accounts/metadata">Metadata</a></td>
      <td>How user metadata and app metadata can be used to store information that does not originate from an identity provider.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/user-accounts/verify-emails">Verify Emails Using Auth0</a></td>
      <td>Proper usage of the <code>email\_verified</code> field in a user profile.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/user-accounts/user-account-linking">User Account Linking</a></td>
      <td>How, when a user has two accounts with the same email, to prompt the user to link them.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/user-accounts/create-users">Create Users</a></td>
      <td>How to create users using the Auth0 Dashboard.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/user-accounts/identify-users">Identify Users</a></td>
      <td>How to uniquely identify users.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/user-accounts/view-user-details">View User Details</a></td>
      <td>How to use the view user details in the Auth0 Dashboard.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/user-accounts/change-user-picture">Change User Pictures</a></td>
      <td>How to change your users' pictures.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/user-accounts/manage-user-access-to-applications">Manage User Access to Applications</a></td>
      <td>How to restrict user access to certain applications in your tenant.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/user-accounts/block-and-unblock-users">Block and Unblock Users</a></td>
      <td>How to block or unblock a user's access to your applications.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/user-accounts/unlink-devices-from-users">Unlink Devices from Users</a></td>
      <td>How to unlink devices assigned to users in the Auth0 Dashboard.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/user-accounts/delete-users">Delete Users</a></td>
      <td>How to delete users in the Auth0 Dashboard.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/user-accounts/get-user-information-on-unbounce-landing-pages">Get User Information on Unbounce Landing Pages</a></td>
      <td>How to create a UI element that will trigger the login with a provider.</td>
    </tr>
  </tbody>
</table>


# Block and Unblock Users
Source: https://auth0.com/docs/manage-users/user-accounts/block-and-unblock-users

Describes how to block and unblock users.

You can use the Dashboard to block or unblock a specific user's access to your applications. If a blocked user tries to log in to an application, they will be redirected from the application with the error message `user is blocked` in the URL. Blocking users does not expire. You must unblock the user to allow the user to have access to your applications again.

## Block users

1. Go to the [Dashboard > User Management > Users](https://manage.auth0.com/#/users).
2. To the right of the user's name that you want to block, click **...** and choose **Block**.
   Alternatively, you can click the user's name and scroll to the bottom of the **Details** tab, next to **Block user**, click **Block**.

## Unblock users

To unblock users, we provide multiple methods, which match the way in which the user was blocked. Users can be blocked in a few different ways:

* blocked automatically due to the user providing an excessive number of incorrect credentials
* blocked through the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> by an administrator
* blocked through the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> by updating the user profile to set `blocked` to `false`

### Unblock a user who was automatically blocked

When a user is blocked due to the user providing an excessive number of incorrect credentials, you can use Auth0's Management API to unblock them.

Use the [Unblock by Identifier endpoint](https://auth0.com/docs/api/management/v2#!/User_Blocks/delete_user_blocks) to pass an identifier (username, phone number, or email):

```bash wrap lines theme={null}
curl -X DELETE  https://{yourAuth0Tenant}.auth0.com/api/v2/user-blocks/john.doe%40gmail.com
```

Or use the [Updat](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id)[e a User endpoint](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id) to patch the `user_id`:

```bash wrap lines theme={null}
curl -X PATCH -H "Content-Type: application/json" -d '{"blocked":false}' https://{yourAuth0Tenant}.auth0.com/api/v2/users/{user_id}
```

### Unblock a user who was blocked through the user profile

When a user is blocked through their user profile using either the Management API or by an administrator using the Auth0 Dashboard, you can unblock them in one of two ways: by having an administrator unblock them through their user profile using the Auth0 Dashboard or by updating the `blocked` attribute in their user profile using the Management API.

#### Using the Auth0 Dashboard

To unblock a user using the Auth0 Dashboard, an administrator should:

1. Go to the [Dashboard > User Management > Users](https://manage.auth0.com/#/users).
2. To the right of the user's name you want to unblock, click **...** and choose **Unblock**. Alternatively, you can click a previously blocked user's name and scroll to the bottom of the **Details** tab, next to **Unblock user**, click **Unblock.**

#### Using the Management API

<Callout icon="file-lines">
  If you use the Management API to reset a user's password, it also unblocks the user.
</Callout>

To unblock a user using the Management API, use the [Update a User endpoint](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id) to set the `blocked` attribute to `false`:

```bash wrap lines theme={null}
curl -X PATCH -H "Content-Type: application/json" -d '{"blocked":false}' https://{yourAuth0Tenant}.auth0.com/api/v2/users/{user_id}
```

## Learn more

* [Manage User Access to Applications](/docs/manage-users/user-accounts/manage-user-access-to-applications)


# Change User Pictures
Source: https://auth0.com/docs/manage-users/user-accounts/change-user-picture

Learn how to use user metadata to change a user's picture field and how to change the default picture for all users.

Auth0 normalizes common profile properties in the User Profile, this includes the `name`, `picture` field and more. The picture field is populated by either the social provider profile picture or the Gravatar image associated with the user's email address.

By default, all database users will have a placeholder image with their initials. When you authenticate the user, this picture field is referred to as `user.picture`.

## Use the Management API

The `user.picture` attribute is not directly editable when provided by <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> other than Auth0 such as Google, Facebook, or X. To edit this attribute, you must configure your connection sync with Auth0 so that user attributes will be updated from the identity provider only on user profile creation. To learn more, read [Configure Identity Provider Connection for User Profile Updates](/docs/manage-users/user-accounts/user-profiles/configure-connection-sync-with-auth0). Root attributes will then be available to be edited individually or by bulk import using the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. To learn more, read [Bulk User Imports](/docs/manage-users/user-migration/bulk-user-imports).

Alternatively, you can use metadata to store the picture attribute for users. For example, if your app provides a way to upload profile pictures, once the picture is uploaded, you can set the URL to the picture in the `user.user_metadata.picture`:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/users/USER_ID' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'content-type: application/json' \
    --data '{"user_metadata": {"picture": "https://example.com/some-image.png"}}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/USER_ID");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"user_metadata": {"picture": "https://example.com/some-image.png"}}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/users/USER_ID"

  	payload := strings.NewReader("{"user_metadata": {"picture": "https://example.com/some-image.png"}}")

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

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

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/users/USER_ID")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("content-type", "application/json")
    .body("{"user_metadata": {"picture": "https://example.com/some-image.png"}}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/users/USER_ID',
    headers: {
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'content-type': 'application/json'
    },
    data: {user_metadata: {picture: 'https://example.com/some-image.png'}}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"user_metadata": @{ @"picture": @"https://example.com/some-image.png" } };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/USER_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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/USER_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 => "{"user_metadata": {"picture": "https://example.com/some-image.png"}}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN",
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"user_metadata": {"picture": "https://example.com/some-image.png"}}"

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

  conn.request("PATCH", "/{yourDomain}/api/v2/users/USER_ID", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/USER_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["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request["content-type"] = 'application/json'
  request.body = "{"user_metadata": {"picture": "https://example.com/some-image.png"}}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "content-type": "application/json"
  ]
  let parameters = ["user_metadata": ["picture": "https://example.com/some-image.png"]] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/USER_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()
  ```
</AuthCodeGroup>

## Use Actions

To ensure that the picture from the `user_metadata` is returned in the <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip>, we'll need to [create a new Action](/docs/customize/actions/write-your-first-action) to check whether the `event.user.user_metadata.picture` attribute is present, and if so, replace the `user.picture` attribute with that value. This ensures that the picture from the `user_metadata` is returned in the `picture` claim of the ID Token.

1. Navigate to [Auth0 Dashboard > Actions > Library](https://manage.auth0.com/#/actions/library), and select **Build Custom**.

2. Enter a descriptive **Name** for your Action (for example, `Change user pictures`), select the `Login / Post Login` trigger because you’ll be adding the Action to the Login flow, then select **Create**.

3. Locate the Actions Code Editor, copy the following JavaScript code into it, and select **Save Draft** to save your changes:

   ```js lines theme={null}
   exports.onExecutePostLogin = async (event, api) => {
     const { picture } = event.user.user_metadata;
     if (picture) {
       // Return the persisted user_metadata.picture in the ID token
       api.idToken.setCustomClaim("picture", picture)
     }
   };
   ```

4. From the Actions Code Editor sidebar, select Test (play icon), then select **Run** to [test your code](/docs/customize/actions/test-actions).

5. When you’re ready for the Action to go live, select **Deploy**.

Finally, add the Action you created to the [Login Flow](https://manage.auth0.com/#/actions/flows/login/). To learn how to attach Actions to Flows, read the "Attach the Action to a flow" section in [Write Your First Action](/docs/customize/actions/write-your-first-action).

## Change default picture for all users

To change the default picture for all users who have not set a profile picture, you can use an Action. For example:

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const DEFAULT_PROFILE_IMAGE = '{yourDefaultImageUrl}';
  api.idToken.setCustomClaim("picture", {defaultProfileImage});
};
```

In this Action, the custom picture is returned in the ID Token and overrides any `picture` property that may come from an external identity provider login, such as Google.

## Limitations

The Auth0 data store is limited and to prevent your application's data from exceeding the limits, we recommend that you use an external database to store user pictures. This allows you to keep your Auth0 data store small and to use a more efficient external database to hold the additional data. To learn more, read [User Data Storage](/docs/secure/security-guidance/data-security/user-data-storage).

## Learn more

* [User Profile Structure](/docs/manage-users/user-accounts/user-profiles/user-profile-structure)
* [User Profile Root Attributes](/docs/manage-users/user-accounts/user-profiles/root-attributes)
* [Understand How Metadata Works in User Profiles](/docs/manage-users/user-accounts/metadata)
* [Manage Metadata Using the Management API](/docs/manage-users/user-accounts/metadata/manage-metadata-api)
* [Manage Metadata with Rules](/docs/manage-users/user-accounts/metadata/manage-metadata-rules)
* [Bulk User Imports](/docs/manage-users/user-migration/bulk-user-imports)


# Create Users
Source: https://auth0.com/docs/manage-users/user-accounts/create-users

Describes how to create users in the Auth0 Dashboard.

You can create a user using Auth0's Dashboard or via the [Auth0 Management API](https://auth0.com/docs/api/management/v2/users/post-users).

1. Go to [Dashboard > User Management > Users](https://manage.auth0.com/#/users) and select **Create User**.
2. Select the **Connection** and then enter your user's **Email**, **Password**.

   <table>
     <thead>
       <tr>
         <th><strong>Attribute</strong></th>
         <th><strong>Description</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>Connection</td>
         <td>The database connection to use to authenticate the user. The dropdown lists all the configured database connections in your tenant. The connection you use must be associated with an application, otherwise you will receive an error message that says the connection is disabled.</td>
       </tr>

       <tr>
         <td>Email</td>
         <td>The user's email address. The email address format should conform to the specification provided in <a href="https://datatracker.ietf.org/doc/html/rfc5321#section-4.1.2">RFC 5321 on IETF</a></td>
       </tr>

       <tr>
         <td>Password</td>
         <td>The user's password. There is no maximum limit for password length.</td>
       </tr>
     </tbody>
   </table>
3. Select **Create**.
   The user is created and you will be directed to the newly-created user's profile.

If you enable [Multiple Custom Domains](/docs/customize/custom-domains/multiple-custom-domains), you have the option to select **Domain** under the **Connection** section to select the notification domain for your tenant.

If you enable [Flexible Identifiers](/docs/authenticate/database-connections/flexible-identifiers-and-attributes), in addition to **email** you can select your user's **username**, **phone** or a combination of two or more.

## Learn more

* [Assign Permissions to Users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/assign-permissions-to-users)
* [Assign Roles to Users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/assign-roles-to-users)
* [Identify Users](/docs/manage-users/user-accounts/identify-users)
* [Delete Users](/docs/manage-users/user-accounts/delete-users)


# Delete Users
Source: https://auth0.com/docs/manage-users/user-accounts/delete-users

Describes how to delete users.

1. Go to the [Dashboard > User Management > Users](https://manage.auth0.com/#/users).
2. Click the name of the user you want to delete.
3. On the **Details** tab, scroll to the bottom, next to **Delete user**, and click **Delete**.<br />

   A popup will warn you that the action cannot be undone and prompt you to confirm that you want to delete the user. Click the **Yes, Delete It** button to confirm. This will permanently delete the user.


# Deny User Access to an API with Rules
Source: https://auth0.com/docs/manage-users/user-accounts/deny-api-access

Learn how to use Auth0's Authorization Extension to deny users access to an API using rules.

<Callout icon="file-lines">
  For use with Auth0’s Authorization Extension only. If you are using the Authorization Core feature set, you should use the [built-in token dialects](/docs/get-started/apis/enable-role-based-access-control-for-apis#token-dialect-options) instead. To learn more, read [Authorization Core vs. Authorization Extension](/docs/manage-users/access-control/authorization-core-vs-authorization-extension).
</Callout>

Go to [Dashboard > Auth0 Pipeline > Rules](https://manage.auth0.com/#/rules). You can set up [Rules](/docs/customize/rules) for a number of different purposes, from user management to enriching user profiles. If you need to deny a user access to your API, you can create Roles with assigned scopes, then create a rule to remove scopes from the <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>:

```javascript lines theme={null}
{
function (user, context, callback) {
  var permissions = user.permissions || [];
  var requestedScopes = context.request.body.scope || context.request.query.scope;
  var filteredScopes = requestedScopes.split(' ').filter( function(x) {
      return x.indexOf(':') < 0;
  });

  var allScopes = filteredScopes.concat(permissions);
  context.accessToken.scope = allScopes.join(' ');

  callback(null, user, context);
}
```


# Get User Information on Unbounce Landing Pages
Source: https://auth0.com/docs/manage-users/user-accounts/get-user-information-on-unbounce-landing-pages

How to get user information with one-click social authentication on Unbounce landing pages.

## Auth0 Configuration

1. Create an Auth0 account and navigate to the [dashboard](https://manage.auth0.com/#).
2. Go to [Dashboard > Applications](https://manage.auth0.com/#/applications) and click **+ Create Application**. Pick the `Single-Page Application` option and go to **Settings**. Note the **Client ID** and **Domain**.
3. Add the `callback URL` in both **Allowed Callback URLs** and **Allowed Origins (CORS)**. Make it your Unbounce page URL. For example: `http://unbouncepages.com/changeit`.
4. Go to [Dashboard > Authentication > Social](https://manage.auth0.com/#/connections/social) and enable the social providers you want to support.

## Unbounce Configuration

1. Create a new UI element, like a button, that will trigger the login with the provider. Note the UI element's ID under **Properties > Element Metadata**.
2. Add a new JavaScript to your Unbounce landing page, select `Before Body End Tag` under `Placement` and add this code. Also make sure to check jQuery as a dependency.

<AuthCodeBlock />

You should use the <Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip> and Domain of the application you just configured.

Next, you need a way to pass the information coming from the social providers to Unbounce:

1. Creating a Form and add `Hidden fields` for each field. For example: the `name` and `email` fields.
2. Return to the JavaScript editor at Unbounce.
3. Add a click handler for each button to trigger the social authentication.

   1. Replace the button ID you took note of previously and the [connection name](/docs/authenticate/identity-providers/locate-the-connection-id). For example, for Google you would use `google-oauth2` and for LinkedIn, `linkedin`.
   2. Make sure that you replace the IDs properly. Instead of `#name` and `#email` you should put the ID of the form fields in question (you can see them while editing the form, under `Field Name and ID`).

```js lines theme={null}
$('#{buttonId}').bind('click', function() { 
  webAuth.authorize({
    connection: '{yourConnectionName}'
  });
});

// After authentication occurs, the parseHash method parses a URL hash fragment to extract the result of an Auth0 authentication response.

webAuth.parseHash({ hash: window.location.hash }, function(err, authResult) { 
  if (err) { 
    return console.log(err); 
  }

  if (authResult != null && authResult.accessToken != null) {
    webAuth.client.userInfo(authResult.accessToken, function(err, user) {
      $('#name').val(user.name); 
      $('#email').val(user.email); 
    }); 
  } 

});
```

Now you will be able to see the information provided by the <Tooltip href="/docs/glossary?term=IdP">IdP</Tooltip> in the `Leads` section of your Unbounce Admin Panel, after the user submits the form.


# Identify Users
Source: https://auth0.com/docs/manage-users/user-accounts/identify-users

Learn how to uniquely identify users.

There are two recommended options to uniquely identify your users:

1. By the `user_id` property. This is guaranteed to be unique (within a tenant) per user (such as `{identity provider id}|{unique id in the provider}` or `facebook|1234567890`). A user may have the same `user_id` property across multiple Auth0 tenants, but consistency is not guaranteed.
2. By a natural key, like the `email` property. In this case, it is recommended that you enable email verification and only use this option with providers that require that users verify their emails.

For [regular](/docs/authenticate/database-connections/auth0-user-store) and [custom](/docs/authenticate/database-connections/custom-db) database connections, avoid creating duplicate `user_id`s within a tenant for different database connections. If you expect possible collisions between IDs from different connections, you should use a prefix identifying the connection.

The following code sample shows a custom database connection identified with the prefix, `MyConnection1|`:

```javascript lines theme={null}
function login (email, password, callback) {
  var user = getUserFromDB(email);
  var profile = {
    user_id: 'MyConnection1|' + user.id,
    email: user.email,
    [...]
  };
  callback(null, profile);
}
```


# Manage User Access to Applications
Source: https://auth0.com/docs/manage-users/user-accounts/manage-user-access-to-applications

Explains the basics of a user profile, how to create a user and view users and their profile details.

All users associated with a single Auth0 tenant are shared between the tenant's applications (and therefore have access to the applications).

* To keep users separate and restrict their access, we recommend that you [create an additional tenant](/docs/get-started/auth0-overview/create-tenants/create-multiple-tenants) with applications you want groups of users to access.

* To restrict users' access to certain applications, you can use [rules](/docs/customize/rules).

  * Inside a rule, the `context.clientName` and `context.clientID` variables are available to check which application the user is using for login.
  * See [this rule for an example](https://github.com/auth0/rules/blob/aeaf93bc058408e260192d0941a688963449d6be/src/rules/simple-user-whitelist-for-app.js).

* To restrict users from applications by configuring a new connection and only giving access to a specific application.

  * Go to [Dashboard > Authentication > Social](https://manage.auth0.com/#/connections/social) and click on a connection.
  * On the **Applications** tab, enable/disable applications.

* To disable users' access to your applications, you can [block and unblock users](/docs/manage-users/user-accounts/block-and-unblock-users) in the Dashboard.

## Learn more

* [Create Multiple Tenants](/docs/get-started/auth0-overview/create-tenants/create-multiple-tenants)
* [Select from Multiple Connection Options](/docs/libraries/lock/selecting-from-multiple-connection-options)
* [Set Up Multiple Environments](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments)


# Manage Users Using the Dashboard
Source: https://auth0.com/docs/manage-users/user-accounts/manage-users-using-the-dashboard

Describes how to manage users in the Auth0 Dashboard.

You can use the Dashboard to manage your users. To begin, go to [Dashboard > User Management > Users](https://manage.auth0.com/#/users). This is where you create, view, modify, or delete users.

<Card title="Availability varies by Auth0 plan">
  Both your specific login implementation and your Auth0 plan or custom agreement affect whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

By default, user profile attributes provided by <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> other than Auth0 (such as Google, Facebook, or X) are not directly editable because they are updated from the identity provider each time the user logs in. Fore more information on attributes from identity providers, read [Configure Identity Provider Connection for User Profile Updates](/docs/manage-users/user-accounts/user-profiles/configure-connection-sync-with-auth0).

To be able to edit the `name`, `nickname`, `given_name`, `family_name`, or `picture` root attributes on the normalized user profile, you must [configure your connection sync with Auth0](/docs/manage-users/user-accounts/user-profiles/configure-connection-sync-with-auth0) so that user attributes will be updated from the identity provider only on user profile creation. These root attributes will then be available to be edited individually or by bulk imports

To learn how to manage <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> access for your team members, read [Manage Dashboard Access](/docs/get-started/manage-dashboard-access).

## Learn more

* [Search for Users](/docs/manage-users/user-search)
* [User Profiles](/docs/manage-users/user-accounts/user-profiles)
* [Import and Export Users](/docs/manage-users/user-migration)


# Manage Users Using the Management API
Source: https://auth0.com/docs/manage-users/user-accounts/manage-users-using-the-management-api

Learn how to create a user and view users and their profile details using the Management API.

In addition to using the Dashboard, you can retrieve, create, update or delete users using the [Management API](https://auth0.com/docs/api/management/v2#!/Users/get_users). If you want to call the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> directly, you will first need to generate the appropriate <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>. To learn more, read [Access Tokens for the Management API](/docs/secure/tokens/access-tokens/management-api-access-tokens). Alternatively, you can use an SDK to implement the functionality you need to call the Management API from your application. For a list of available SDKs, read [the SDKs section of our Support Matrix](/docs/troubleshoot/customer-support/product-support-matrix).

To learn how to manage <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> access for your team members, read [Manage Dashboard Access](/docs/get-started/manage-dashboard-access).

## Permissions

Use the following permissions to get an access token for the machine-to-machine applications. To learn more, read [Register Machine-to-Machine Applications.](/docs/get-started/auth0-overview/create-applications/machine-to-machine-apps)

<table>
  <thead>
    <tr>
      <th>Permissions</th>
      <th>Descriptions</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>read:users</code></td>
      <td>Applications can search and retrieve any user records stored in an Auth0 tenant. This includes reading via the <code>/api/v2/users</code> , <code>/api/v2/users-by-email</code>, and <code>/api/v2/jobs/users-export</code> endpoints.</td>
    </tr>

    <tr>
      <td><code>create:users</code></td>
      <td>Applications can create users in any database or passwordless connection in an Auth0 tenant. This includes creating via the <code>/api/v2/users</code> and <code>/api/v2/jobs/users-import</code> endpoints.</td>
    </tr>

    <tr>
      <td><code>update:users</code></td>
      <td>Applications can update any user stored in an Auth0 tenant. This includes updating via the <code>/api/v2/users</code> endpoint.</td>
    </tr>

    <tr>
      <td><code>update:users\_app\_metadata</code></td>
      <td>Applications can update only the <code>user.app\_metadata</code> attribute for any user stored in an Auth0 tenant. This includes updating via the <code>/api/v2/users endpoint</code>.</td>
    </tr>

    <tr>
      <td><code>delete:users</code></td>
      <td>Applications can delete any user stored in an Auth0 tenant. This includes deleting via the <code>/api/v2/users</code> endpoint.</td>
    </tr>
  </tbody>
</table>

## Limitations

By default, user profile attributes provided by <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> other than Auth0 (such as Google, Facebook, or X) are not directly editable because they are updated from the identity provider each time the user logs in. Fore more information on attributes from identity providers, read [Configure Identity Provider Connection for User Profile Updates](/docs/manage-users/user-accounts/user-profiles/configure-connection-sync-with-auth0).

To be able to edit the `name`, `nickname`, `given_name`, `family_name`, or `picture` root attributes on the normalized user profile, you must [configure your connection sync with Auth0](/docs/manage-users/user-accounts/user-profiles/configure-connection-sync-with-auth0) so that user attributes will be updated from the identity provider only on user profile creation. These root attributes will then be available to be edited individually or by bulk imports

You can set passwords using the `create` or `update` endpoints, but for security purposes, passwords cannot be viewed with the `get` or `list user` commands. The right side of the API explorer provides hints on the user profile attributes which can be viewed or modified for any given call.

## Endpoints

* Use the [`/users`](https://auth0.com/docs/api/management/v2/users/get-users) endpoint to [retrieve information about all users](https://auth0.com/docs/api/management/v2/users/get-users). You can also include search criteria to find specific users.
* Use the [`/user_id`](https://auth0.com/docs/api/management/v2/users/get-users-by-id) to [retrieve information about one user](https://auth0.com/docs/api/management/v2/users/get-users-by-id) based on the `user_id`. The `user_id` is an internal identifier that consists of a connection name and a unique identifier for the user. The `user_id` is different from the <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip>.
* The [`/userinfo`](https://auth0.com/docs/api/authentication/reference#get-user-info) endpoint takes as input the [Auth0 access token and returns user profile information](https://auth0.com/docs/api/authentication/reference#get-user-info). This endpoint will include the results of any rules that may have altered the user profile during the authentication transaction, but the resulting user profile will not be filtered by any [Scoping](/docs/get-started/apis/scopes/api-scopes).
* The [`/tokeninfo`](https://auth0.com/docs/api/authentication/reference#get-token-info) endpoint takes as input the [Auth0 ID token and returns user profile information](https://auth0.com/docs/api/authentication/reference#get-token-info). This endpoint will return a result that does not include the results of any rules that alter the user profile.

## Learn more

* [Check Error Messages](/docs/troubleshoot/basic-issues/check-error-messages)
* [Check API Calls](/docs/troubleshoot/authentication-issues/check-api-calls)
* [Check User Profiles](/docs/troubleshoot/authentication-issues/check-user-profiles)
* [Auth0.swift: User Management](/docs/libraries/auth0-swift/auth0-swift-user-management)
* [Auth0.Android: User Management](/docs/libraries/auth0-android/auth0-android-user-management)


# Understand How Metadata Works in User Profiles
Source: https://auth0.com/docs/manage-users/user-accounts/metadata

Describes Auth0 user, application, and client metadata. Learn how you can use metadata to store information that does not originate from an identity provider.

Auth0 provides a comprehensive system for storing metadata in the Auth0 user profile. You can use metadata to do the following activities:

* Store application-specific data in the user profile.
* Record whether or not specific operations have occurred for a user.
* Cache the results of expensive operations on the user profile so they can be re-used in future logins.
* Store information that does not originate from an <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> or that overrides what an identity provider supplies.

The metadata can be modified as part of a user’s login flow.

You can configure connection sync so that user root attributes are updated by the identity provider only on user profile creation. You can then edit root attributes individually or by bulk import. To learn more, read [Configure Identify Provider Connection for User Profiles Updates](/docs/manage-users/user-accounts/user-profiles/configure-connection-sync-with-auth0).

## Metadata types

Auth0 uses three types of metadata to store specific kinds of information.

<table>
  <thead>
    <tr>
      <th><strong>Metadata Type</strong></th>
      <th><strong>Field Name</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>User Information</strong></td>
      <td><code>user\_metadata</code></td>
      <td>Stores user attributes such as preferences that do not impact a user's core functionality. This data <strong>can</strong> be edited by logged in users if you build a form using the Management API and should <strong>not</strong> be used as a secure data store.</td>
    </tr>

    <tr>
      <td><strong>Access Information</strong></td>
      <td><code>app\_metadata</code></td>
      <td>Stores information such as permissions, Auth0 plan, and external IDs that can impact user access to features. This data <strong>cannot</strong> be edited by users and there are restrictions for what can be stored in this field.</td>
    </tr>

    <tr>
      <td><strong>Application Information</strong></td>
      <td><code>client\_metadata</code> in the <code>Client</code> object, <code>context.clientMetadata</code> in Rules, and <code>event.client.metadata</code> in post-login Actions.</td>
      <td>Stores information about an application (or <em>client</em> in OIDC OAuth2 terminology). For example, the URL for the application home page (any value that Auth0 doesn’t set in the application settings).</td>
    </tr>
  </tbody>
</table>

## Manage metadata

You can create and update metadata using Rules, the Authentication API, the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>, the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, and the Lock library.

For custom DB scripts and the `fetchUserProfile` script of custom social connections, you can create and update metadata using the `metadata` object.

### Use Actions

[Actions](/docs/customize/actions) are secure, tenant-specific, versioned functions written in Node.js that execute at certain points within the Auth0 platform. Actions are used to customize and extend Auth0's capabilities with custom logic. They can also be used to [enrich the user profile](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger).

For example, you can create a `post-login` Action that uses custom claims to copy `user_metadata` properties to <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip>. You can then retrieve users' `user_metadata` through the [Get User Info](https://auth0.com/docs/api/authentication#get-user-info) endpoint of the Authentication API.

To learn more, read [Manage User Metadata with the post-login Action Trigger](/docs/manage-users/user-accounts/metadata/manage-user-metadata).

### Use the Management API

A user can request an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> with the appropriate scopes and use the following [Management API](https://auth0.com/docs/api/management/v2) endpoints to view, create, or update `user_metadata`, or remove an <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> configuration.

<table>
  <thead>
    <tr>
      <th><strong>Task</strong></th>
      <th><strong>Endpoint</strong></th>
      <th><strong>Scope</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>View</td>
      <td><a href="https://auth0.com/docs/api/management/v2#!/Users/get_users_by_id"><code>GET /api/v2/users/</code></a></td>
      <td><code>read:current\_user</code></td>
    </tr>

    <tr>
      <td>Create</td>
      <td><a href="https://auth0.com/docs/api/management/v2#!/Users/post_users"><code>PATCH /api/v2/users/</code></a></td>
      <td><code>create:current\_user\_metadata</code></td>
    </tr>

    <tr>
      <td>Update</td>
      <td><a href="https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id"><code>PATCH /api/v2/users/</code></a></td>
      <td><code>update:current\_user\_metadata</code></td>
    </tr>

    <tr>
      <td>Delete</td>
      <td><a href="https://auth0.com/docs/api/management/v2#!/Users/delete_multifactor_by_provider"><code>DELETE /api/v2/users//multifactor/</code></a></td>
      <td><code>update:users</code></td>
    </tr>
  </tbody>
</table>

An access token is required to call the Auth0 Management API. To learn more, read [Access Tokens for the Management API](https://auth0.com/docs/api/management/v2/tokens) and [Get Management API Tokens for SPAs](https://auth0.com/docs/api/management/v2/get-access-tokens-for-spas).

### Use the Dashboard

Use the Auth0 Dashboard to configure application metadata which contains key/value pairs. To learn more, read [Configure Application Metadata](/docs/get-started/applications/configure-application-metadata).

### Use the Lock library

Use the [Lock](/docs/libraries/lock) library to define, add, read, and update `user_metadata.` Read `user_metadata` properties the same way you would read any other user profile property. For example, the following code snippet retrieves the value associated with `user_metadata.hobby` and assigns it to an element on the page:

```javascript lines theme={null}
// Use the accessToken acquired upon authentication to call getUserInfo
lock.getUserInfo(accessToken, function(error, profile) {
  if (!error) {
    document.getElementById('hobby').textContent = profile.user_metadata.hobby;
  }
});
```

You can use `additionalSignUpFields` to add custom fields to user sign-up forms. When a user adds data in a custom field, Auth0 stores entered values in that user's `user_metadata`. To learn more about adding `user_metadata` on signup, read [Additional Signup Fields](/docs/libraries/lock/lock-configuration#additionalsignupfields).

## Custom database connections and metadata

If you have a [custom database connection](/docs/authenticate/database-connections#using-your-own-user-store), you can use the Authentication API [`/dbconnections/signup`](https://auth0.com/docs/api/authentication?shell#signup) endpoint to set the `user_metadata` for a user. To learn more about working with metadata during a custom signup process, read [Custom Signup](/docs/libraries/custom-signup).

When you set the `user_metadata` field using the Authentication API `/dbconnections/signup` endpoint, you are limited to a maximum of 10 string fields and 500 characters.

## Custom emails and metadata

Use metadata to store information that you want to use to customize Auth0 emails. For example, use `user_metadata.lang` if you want the user to be able to change the field's value, then use the information to customize the language for an email. To learn more, read [Customize Email Templates](/docs/customize/email/email-templates).

If you are having issues with Lock, review [Deprecation Errors](/docs/troubleshoot/basic-issues/check-deprecation-errors). If you are having issues with the Management API, review [Check API Calls](/docs/troubleshoot/authentication-issues/check-api-calls)

## Learn more

* [Metadata Field Names and Data Types](/docs/manage-users/user-accounts/metadata/metadata-fields-data)
* [Manage Metadata with Rules](/docs/manage-users/user-accounts/metadata/manage-metadata-rules)
* [Manage Metadata Using the Management API](/docs/manage-users/user-accounts/metadata/manage-metadata-api)
* [Manage Metadata with Lock](/docs/manage-users/user-accounts/metadata/manage-metadata-lock)
* [Configure Application Metadata](/docs/get-started/applications/configure-application-metadata)
* [Manage User Metadata with the post-login Action Trigger](/docs/manage-users/user-accounts/metadata/manage-user-metadata)


# Configure Application Metadata
Source: https://auth0.com/docs/manage-users/user-accounts/metadata/configure-application-metadata

Learn how to configure, update, and delete application metadata (client_metadata and clientMetadata)  in the Auth0 Dashboard Applications Advanced Settings.

Application metadata is optional and consists of customizable keys and values (max 255 characters each), that you can set for each application. Metadata is exposed in the `Client` object as `client_metadata`, and in Rules as `context.clientMetadata`. You might store, for example, the URL for the application’s home page (a field that Auth0 doesn’t provide by default in the application settings).

Client metadata is stored as part of the application (client) properties. To learn more about data types, field names, and storage limitations, read [Metadata Field Names and Data Types](/docs/manage-users/user-accounts/metadata/metadata-fields-data).

<Card title="Where to store client secrets">
  Where to store the secret depends on the scope of the secret:

  * Is it just one secret per application? Then `client_metadata` would be a good place.
  * Is it the same secret for the whole system (i.e., for all applications or many)? Then the rule’s configuration values might be a better choice
  * Is it a different secret for each user? Then storing in `app_metadata` might be better.
</Card>

<Warning>
  Claims in the ID token are not encrypted, so depending on the flow that you use, the user might be able to get the token and inspect the contents. Auth0 does **not** recommend storing a secret in that way.
</Warning>

Existing applications will have no value for this property.

You can access application metadata in [Actions](/docs/customize/actions):

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  if (event.client.metadata.SKIP_VERIFICATION === "yes"){
    return;
  }
  // ... continue this Action
}
```

... or in [Rules](/docs/customize/rules):

```javascript lines theme={null}
function applicationMetadataExample (user, context, callback){
  context.clientMetadata = context.clientMetadata || {};
  if (context.clientMetadata.SKIP_VERIFICATION === "yes"){
    return callback();
  }
  // ... continue this Rule
}
```

You can read and add to the application metadata using either the Dashboard or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. To learn how to manage client metadata with the Management API, read [Manage Metadata Using the Management API](/docs/manage-users/user-accounts/metadata/manage-metadata-api).

## Add application metadata key/value pairs

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and select the application.
2. Scroll down and click **Advanced Settings**.
3. On the **Application Metadata** tab, enter the key's name and value, then click **Add**.

   <Frame>
     <img alt="Dashboard Applications Applications Settings Tab Advanced Settings Application Metadata Tab" />
   </Frame>
4. Click **Save Changes**.

## Update application metadata value

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and select the application.
2. Scroll down and click **Advanced Settings**.
3. On the **Application Metadata** tab, enter the key's name that you want to change and enter a new value, then click **Add**.
4. Click **Save Changes**

## Delete application metadata

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and select the application.
2. Scroll down and click **Advanced Settings**.
3. On the **Application Metadata** tab locate the key/value pair you want to delete and click the trash can icon.
4. Confirm the deletion.
5. Click **Save Changes**.

## Learn more

* [Metadata Field Names and Data Types](/docs/manage-users/user-accounts/metadata/metadata-fields-data)
* [Manage Metadata Using the Management API](/docs/manage-users/user-accounts/metadata/manage-metadata-api)
* [Manage Metadata with Rules](/docs/manage-users/user-accounts/metadata/manage-metadata-rules)
* [Rotate Client Secrets](/docs/get-started/applications/rotate-client-secret)


# Manage Metadata Using the Management API
Source: https://auth0.com/docs/manage-users/user-accounts/metadata/manage-metadata-api

Learn how to create, update, merge, and delete metadata with the Management API.

## User metadata

### Create user metadata

To create a user with the following profile details:

```json lines theme={null}
{
    "email": "jane.doe@example.com",
    "user_metadata": {
        "hobby": "surfing"
    },
    "app_metadata": {
        "plan": "full"
    }
}
```

Make the following `POST` call to the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> [`/post_users`](https://auth0.com/docs/api/management/v2#!/Users/post_users) endpoint to create the user and set the property values:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/users' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'content-type: application/json' \
    --data '{"email": "jane.doe@example.com", "user_metadata": {"hobby": "surfing"}, "app_metadata": {"plan": "full"}}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"email": "jane.doe@example.com", "user_metadata": {"hobby": "surfing"}, "app_metadata": {"plan": "full"}}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/users"

  	payload := strings.NewReader("{"email": "jane.doe@example.com", "user_metadata": {"hobby": "surfing"}, "app_metadata": {"plan": "full"}}")

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

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

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/users")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("content-type", "application/json")
    .body("{"email": "jane.doe@example.com", "user_metadata": {"hobby": "surfing"}, "app_metadata": {"plan": "full"}}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/users',
    headers: {
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'content-type': 'application/json'
    },
    data: {
      email: 'jane.doe@example.com',
      user_metadata: {hobby: 'surfing'},
      app_metadata: {plan: 'full'}
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"email": @"jane.doe@example.com",
                                @"user_metadata": @{ @"hobby": @"surfing" },
                                @"app_metadata": @{ @"plan": @"full" } };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{"email": "jane.doe@example.com", "user_metadata": {"hobby": "surfing"}, "app_metadata": {"plan": "full"}}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN",
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"email": "jane.doe@example.com", "user_metadata": {"hobby": "surfing"}, "app_metadata": {"plan": "full"}}"

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

  conn.request("POST", "/{yourDomain}/api/v2/users", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users")

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

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request["content-type"] = 'application/json'
  request.body = "{"email": "jane.doe@example.com", "user_metadata": {"hobby": "surfing"}, "app_metadata": {"plan": "full"}}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "content-type": "application/json"
  ]
  let parameters = [
    "email": "jane.doe@example.com",
    "user_metadata": ["hobby": "surfing"],
    "app_metadata": ["plan": "full"]
  ] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

### Update user metadata

You can update a user's metadata by making a `PATCH` call to the Management API [`/patch_users_by_id`](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id) endpoint.

Assuming you created a user with the following metadata values:

```json lines theme={null}
{
    "email": "jane.doe@example.com",
    "user_metadata": {
        "hobby": "surfing"
    },
    "app_metadata": {
        "plan": "full"
    }
}
```

To update `user_metadata` and add the user's home address as a second-level property:

```json lines theme={null}
{
    "addresses": {
        "home": "123 Main Street, Anytown, ST 12345"
    }
}
```

You would make the following `PATCH` call:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/users/user_id' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'content-type: application/json' \
    --data '{"user_metadata": {"addresses": {"home": "123 Main Street, Anytown, ST 12345"}}}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/user_id");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"user_metadata": {"addresses": {"home": "123 Main Street, Anytown, ST 12345"}}}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/users/user_id"

  	payload := strings.NewReader("{"user_metadata": {"addresses": {"home": "123 Main Street, Anytown, ST 12345"}}}")

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

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

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/users/user_id")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("content-type", "application/json")
    .body("{"user_metadata": {"addresses": {"home": "123 Main Street, Anytown, ST 12345"}}}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/users/user_id',
    headers: {
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'content-type': 'application/json'
    },
    data: {user_metadata: {addresses: {home: '123 Main Street, Anytown, ST 12345'}}}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"user_metadata": @{ @"addresses": @{ @"home": @"123 Main Street, Anytown, ST 12345" } } };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/user_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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/user_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 => "{"user_metadata": {"addresses": {"home": "123 Main Street, Anytown, ST 12345"}}}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN",
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"user_metadata": {"addresses": {"home": "123 Main Street, Anytown, ST 12345"}}}"

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

  conn.request("PATCH", "/{yourDomain}/api/v2/users/user_id", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/user_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["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request["content-type"] = 'application/json'
  request.body = "{"user_metadata": {"addresses": {"home": "123 Main Street, Anytown, ST 12345"}}}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "content-type": "application/json"
  ]
  let parameters = ["user_metadata": ["addresses": ["home": "123 Main Street, Anytown, ST 12345"]]] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/user_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()
  ```
</AuthCodeGroup>

The user's profile will now appear as follows:

```json lines theme={null}
{
    "email": "jane.doe@example.com",
    "user_metadata": {
        "hobby": "surfing",
        "addresses": {
            "home": "123 Main Street, Anytown, ST 12345"
        }
    },
    "app_metadata": {
        "plan": "full"
    }
}
```

<Warning>
  When you send a `PATCH` call in which you have set a property's value to `null` (for example, `{user_metadata: {color: null}}`), Auth0 **deletes** the property/value from the database. Also, patching the metadata itself with an empty object removes the metadata completely.
</Warning>

### Merge user metadata

Only properties at the root level are merged into the object. All lower-level properties will be replaced.

For example, to add a user's work address as an additional inner property, you would have to include the complete contents of the `addresses` property. Since the `addresses` object is a root-level property, it will be merged into the final JSON object representing the user, but its sub-properties will not.

```json lines theme={null}
{
  "user_metadata": {
    "addresses": {
      "home": "123 Main Street, Anytown, ST 12345",
      "work": "100 Industrial Way, Anytown, ST 12345"
    }
  }
}
```

Therefore, the corresponding `PATCH` call to the API would be:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/users/user_id' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'content-type: application/json' \
    --data '{"user_metadata": {"addresses": {"home": "123 Main Street, Anytown, ST 12345", "work": "100 Industrial Way, Anytown, ST 12345"}}}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/user_id");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"user_metadata": {"addresses": {"home": "123 Main Street, Anytown, ST 12345", "work": "100 Industrial Way, Anytown, ST 12345"}}}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/users/user_id"

  	payload := strings.NewReader("{"user_metadata": {"addresses": {"home": "123 Main Street, Anytown, ST 12345", "work": "100 Industrial Way, Anytown, ST 12345"}}}")

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

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

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/users/user_id")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("content-type", "application/json")
    .body("{"user_metadata": {"addresses": {"home": "123 Main Street, Anytown, ST 12345", "work": "100 Industrial Way, Anytown, ST 12345"}}}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/users/user_id',
    headers: {
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'content-type': 'application/json'
    },
    data: {
      user_metadata: {
        addresses: {
          home: '123 Main Street, Anytown, ST 12345',
          work: '100 Industrial Way, Anytown, ST 12345'
        }
      }
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"user_metadata": @{ @"addresses": @{ @"home": @"123 Main Street, Anytown, ST 12345", @"work": @"100 Industrial Way, Anytown, ST 12345" } } };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/user_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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/user_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 => "{"user_metadata": {"addresses": {"home": "123 Main Street, Anytown, ST 12345", "work": "100 Industrial Way, Anytown, ST 12345"}}}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN",
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"user_metadata": {"addresses": {"home": "123 Main Street, Anytown, ST 12345", "work": "100 Industrial Way, Anytown, ST 12345"}}}"

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

  conn.request("PATCH", "/{yourDomain}/api/v2/users/user_id", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/user_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["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request["content-type"] = 'application/json'
  request.body = "{"user_metadata": {"addresses": {"home": "123 Main Street, Anytown, ST 12345", "work": "100 Industrial Way, Anytown, ST 12345"}}}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "content-type": "application/json"
  ]
  let parameters = ["user_metadata": ["addresses": [
        "home": "123 Main Street, Anytown, ST 12345",
        "work": "100 Industrial Way, Anytown, ST 12345"
      ]]] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/user_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()
  ```
</AuthCodeGroup>

### Delete user metadata

You can delete `user_metadata`:

```json lines theme={null}
{
  "user_metadata": {}
}
```

## App metadata

Patching the metadata with an empty object removes the metadata completely. For example, sending this body removes everything in `app_metadata`:

```json lines theme={null}
{
  "app_metadata": {}
}
```

## Client metadata

### Create applications with client metadata

A `clientMetadata` object can be included when creating a new application via the `POST /api/v2/` applications endpoint.

### Read client metadata

Client metadata is included in the response to the `GET /api/v2/clients` and `GET /api/v2/client/{id}` endpoints.

### Update client metadata

Client metadata can be updated using the [`PATCH /api/v2/clients/{id}`](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id) endpoint, supplying an application object with the `clientMetadata property`, which has a value that consists of an object containing the metadata you'd like to change.

**Application before:**

```json lines theme={null}
{
  ...
  "name": "myclient",
  "client_metadata": {
    "mycolor": "red",
    "myflavor": "grape"
  }
  ...
}
```

Request: `PATCH /api/v2/client/myclientid123` with body:

```json lines theme={null}
{ "client_metadata": { "mycolor": "blue" } }
```

**Application after:**

```json lines theme={null}
{
  "name": "myclient",
  "client_metadata": {
    "mycolor": "blue",
    "myflavor": "grape"
  }
  ...
}
```

### Delete client metadata properties and values

Client metadata keys can be removed by issuing a PATCH, as described in "Update app\_metadata" above, but supplying `null` for the key value. This behavior matches that of the `user_metadata` and `app_metadata` properties in the `PATCH` [/api/v2/users/](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id) endpoint.

## Learn more

* [Management API Access Tokens](/docs/secure/tokens/access-tokens/management-api-access-tokens)
* [Configure Application Metadata](/docs/get-started/applications/configure-application-metadata)


# Manage Metadata with Lock
Source: https://auth0.com/docs/manage-users/user-accounts/metadata/manage-metadata-lock

Learn how to manage user and app metadata with the Auth0 Lock library.

You can use the [Lock library](/docs/libraries/lock) to define, add, read, and update the `user_metadata.` You can read the user's `user_metadata` properties the same way you would read any other user profile property. For example, the following code snippet retrieves the value associated with `user_metadata.hobby` and assigns it to an element on the page:

```javascript lines theme={null}
// Use the accessToken acquired upon authentication to call getUserInfo
lock.getUserInfo(accessToken, function(error, profile) {
  if (!error) {
    document.getElementById('hobby').textContent = profile.user_metadata.hobby;
  }
});
```

You can use `additionalSignUpFields` to add custom fields to user sign-up forms. When a user adds data in a custom field, Auth0 stores entered values in that user's `user_metadata`. To learn more about adding `user_metadata` on signup, read [Additional Signup Fields](/docs/libraries/lock/lock-configuration#additionalsignupfields-array-).

## Learn more

* [Lock for Web](/docs/libraries/lock)
* [Lock API Reference](/docs/libraries/lock/lock-api-reference)
* [Deprecation Errors](/docs/troubleshoot/basic-issues/check-deprecation-errors)


# Manage Metadata with Rules
Source: https://auth0.com/docs/manage-users/user-accounts/metadata/manage-metadata-rules

Learn how to manage with app metadata, user metadata, and client metadata using Rules.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

You can read, update, and delete metadata using [Auth0 Rules](/docs/customize/rules). In the following sections, we will refer to this example where the user and their information is represented by the following JSON snippet:

```json lines theme={null}
{
  "user_id": "jdoe",
  "email": "john.doe@example.com",
  "app_metadata": {
    "roles": [ "writer" ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue"
    }
  }
}
```

## Read metadata

You can read metadata using rules with the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. You can also search for profile-related information in `user_metadata`, such as:

* `name`
* `nickname`
* `given_name`
* `family_name`

By default, user profile attributes provided by <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> other than Auth0 (such as Google, Facebook, or X) are not directly editable because they are updated from the identity provider each time the user logs in. Fore more information on attributes from identity providers, read [Configure Identity Provider Connection for User Profile Updates](/docs/manage-users/user-accounts/user-profiles/configure-connection-sync-with-auth0).

To be able to edit the `name`, `nickname`, `given_name`, `family_name`, or `picture` root attributes on the normalized user profile, you must [configure your connection sync with Auth0](/docs/manage-users/user-accounts/user-profiles/configure-connection-sync-with-auth0) so that user attributes will be updated from the identity provider only on user profile creation. These root attributes will then be available to be edited individually or by bulk imports

As an example, assume the following metadata is stored for a user with the email address `jane.doe@example.com`:

```json lines theme={null}
{
    "email": "jane.doe@example.com",
    "user_metadata": {
        "hobby": "surfing"
    },
    "app_metadata": {
        "plan": "full"
    }
}
```

Using the example metadata above, you can refer to specific items from the dataset in [Auth0 Rules](/docs/customize/rules) or via a call to the [Management API](/docs/manage-users/user-accounts/metadata) as follows:

```js lines theme={null}
console.log(user.email); // "jane.doe@example.com"
console.log(user.user_metadata.hobby); // "surfing"
console.log(user.app_metadata.plan); // "full"
```

Any valid JSON snippet can be used as metadata, but note that `user.app_metadata` is `Undefined` by default.

To read the available metadata, you will need to access the correct user property.

### Read app metadata

You can make a decision based on the user's roles:

```javascript lines theme={null}
function(user, context, callback){
  user.app_metadata = user.app_metadata || {};
  if (user.app_metadata.roles.indexOf('writer')){
    // code to be executed
  }
  ...
}
```

### Read user metadata

You can base decisions on specific preferences, such as a color preference:

```javascript lines theme={null}
function(user, context, callback){
  user.user_metadata = user.user_metadata || {};
  if (user.user_metadata.preferences.color === 'black'){
    // code to be executed
  }
  ...
}
```

### Read application metadata (clientMetadata)

Application metadata (`clientMetadata`) is an optional, top-level property of the `context` object. Existing applications will have no value for this property.

```javascript lines theme={null}
function(user, context, callback){
  context.clientMetadata = context.clientMetadata || {};
  if (context.clientMetadata.usersuppliedkey1 === 'black'){
    // this code would not be executed for the user
  }
  ...
}
```

## Update metadata

<Callout icon="file-lines">
  Use Rules to map SAML attributes that Auth0 receives from the IdP into `user_metadata` or `app_metadata`.
</Callout>

### Update app metadata

To add an administrative role to the user:

```javascript lines theme={null}
function(user, context, callback){
  user.app_metadata = user.app_metadata || {};
  // update the app_metadata that will be part of the response
  user.app_metadata.roles = user.app_metadata.roles || [];
  user.app_metadata.roles.push('administrator');

  // persist the app_metadata update
  auth0.users.updateAppMetadata(user.user_id, user.app_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}
```

This results in the following JSON representation of the user profile details:

```json lines theme={null}
{
  "user_id": "jdoe",
  "email": "john.doe@example.com",
  "app_metadata": {
    "roles": [ "writer", "administrator" ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue"
    }
  }
}
```

### Update user metadata

To add the user's `fontSize` preference to the user profile:

```javascript lines theme={null}
function(user, context, callback){
  user.user_metadata = user.user_metadata || {};
  // update the user_metadata that will be part of the response
  user.user_metadata.preferences = user.user_metadata.preferences || {};
  user.user_metadata.preferences.fontSize = 12;

  // persist the user_metadata update
  auth0.users.updateUserMetadata(user.user_id, user.user_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}
```

This results in the following JSON representation of the user profile details:

```json lines theme={null}
{
  "user_id": "jdoe",
  "email": "john.doe@example.com",
  "app_metadata": {
    "roles": [ "writer" ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue",
      "fontSize": 12
    }
  }
}
```

### Update app and user metadata simultaneously

To reduce the rule's processing time, you may update both the `app_metadata` and `user_metadata` in the same rule:

```javascript lines expandable theme={null}
function(user, context, callback){

  var q = require('q');

  user.app_metadata = user.app_metadata || {};
  user.user_metadata = user.user_metadata || {};
  // update the user_metadata that will be part of the response
  user.user_metadata.preferences = user.user_metadata.preferences || {};
  user.user_metadata.preferences.fontSize = 12;

  // update the app_metadata that will be part of the response
  user.app_metadata.roles = user.app_metadata.roles || [];
  user.app_metadata.roles.push('admin');

  // persist the app_metadata update
  var appMetadataPromise  = auth0.users.updateAppMetadata(user.user_id, user.app_metadata);

  // persist the user_metadata update
  var userMetadataPromise = auth0.users.updateUserMetadata(user.user_id, user.user_metadata);

  // using q library to wait for all promises to complete
  q.all([userMetadataPromise, appMetadataPromise])
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}
```

This results in the following JSON representation of the user profile details:

```json lines theme={null}
{
  "user_id": "jdoe",
  "email": "john.doe@example.com",
  "app_metadata": {
    "roles": [ "writer", "admin" ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue",
      "fontSize": 12
    }
  }
}
```

## Delete metadata

### Delete app metadata properties and values

To delete a property, set the property's value to `null`.

#### Delete user's roles example

To delete the user's roles, use the following sample rule:

```javascript lines theme={null}
function(user, context, callback){
  user.app_metadata = user.app_metadata || {};
  // update the app_metadata that will be part of the response
  user.app_metadata.roles = null;

  // persist the app_metadata update
  auth0.users.updateAppMetadata(user.user_id, user.app_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}
```

This results in the following JSON representation of the user profile:

```json lines theme={null}
{
  "user_id": "jdoe",
  "email": "john.doe@example.com",
  "app_metadata": { },
  "user_metadata": {
    "preferences": {
      "color": "blue"
    }
  }
}
```

#### Delete single property value example

To delete a single value of a property, remove that specific value. For example, to remove the `writer` role from the user profile:

```javascript lines theme={null}
function(user, context, callback){
  user.app_metadata = user.app_metadata || {};
  user.app_metadata.roles = user.app_metadata.roles || [];

  var index = user.app_metadata.roles.indexOf('writer');

  if (index !== -1){
    // update the app_metadata that will be part of the response
    user.app_metadata.roles.splice(index, 1);
  }

  // persist the app_metadata update
  auth0.users.updateAppMetadata(user.user_id, user.app_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}
```

This results in the following JSON representation of the user profile:

```json lines theme={null}
{
  "user_id": "google-oauth2|1234",
  "email": "john.doe@gmail.com",
  "app_metadata": {
    "roles": [ ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue"
    }
  }
}
```

Note that the `roles` property still exists but does not contain any value.

### Delete user metadata properties and values

To delete the user's color preference:

```javascript lines theme={null}
function(user, context, callback){
  user.user_metadata = user.user_metadata || {};
  // update the user_metadata that will be part of the response
  user.user_metadata.preferences = user.user_metadata.preferences || {};
  delete user.user_metadata.preferences.color;

  // persist the user_metadata update
  auth0.users.updateUserMetadata(user.user_id, user.user_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
  });
}
```

This results in the following JSON representation of the user profile details:

```json lines theme={null}
{
  "user_id": "jdoe",
  "email": "john.doe@example.com",
  "app_metadata": {
    "roles": [ "writer" ]
  },
  "user_metadata": {
    "preferences": { }
  }
}
```

## Learn more

* [Use the Management API from within Rules](/docs/customize/rules/use-management-api)
* [Context Object Properties in Rules](/docs/customize/rules/context-object)
* [Auth0 Rules](/docs/customize/rules)


# Manage User Metadata with the post-login Action Trigger
Source: https://auth0.com/docs/manage-users/user-accounts/metadata/manage-user-metadata

Learn how to use the post-login Action trigger to modify user_metadata and app_metadata as part of a user’s login flow.

Auth0 provides a rich system for storing [metadata](/docs/manage-users/user-accounts/metadata) on the Auth0 user profile. You can configure a `post-login` trigger to modify `user_metadata` and `app_metadata` as part of a user’s login flow. Post-login triggers are useful for tasks such as storing application-specific data on the user profile, capturing user operation logs, mapping <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> attributes to the metadata field, or caching expensive operation values on the User profile for re-used in future logins.

The `post-login` `api` object provides common operations that can be performed in this trigger. To manage user metadata, we want to use the `api.user.setAppMetadata` and `api.user.setUserMetadata` methods. For example, to guard against some behavior running more than once for a specific user, consider an Action that looks like this:

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  if (event.user.app_metadata.didAnExpensiveTask) {
    console.log(`Skipping the expensive task because it already occurred for ${event.user.email}.`);
    return;
  }
  // do and expensive task
  api.user.setAppMetadata("didAnExpensiveTask", true);
};
```

Here, we added a check at the start of the Action to see if we have already performed the expensive task for this user. If the metadata field exists, then we return from the function.

At the end of the Action, we call `api.user.setAppMetadata` to signal that we would like to store some metadata on the user object. At the end of each trigger’s execution, Actions will update the user profile as a single operation. If several calls are made to `setUserMetadata` actions, even if they are made in different actions as part of the same flow, Actions will only update the user profile a single time--at the end of the trigger’s execution.

<Callout icon="file-lines">
  Multiple `setUserMetadata` or `setAppMetadata` calls will be batched together into a single user profile update at the end of the trigger’s execution, even if they are made by different Actions.
</Callout>

## Best practices

Beware of storing too much data in the Auth0 profile. This data is intended to be used for authentication and authorization purposes, and users can edit their own `user_metadata` field, so don't store sensitive data in it. The metadata and search capabilities of Auth0 are not designed for marketing research or anything else that requires heavy search or update frequency. Your system is likely to run into scalability and performance issues if you use Auth0 for this purpose. A better approach is to store data in an external system and store a pointer (the user ID) in Auth0 so that backend systems can fetch the data if needed.

## Rate limits

<Warning>
  Setting user and app metadata is subject to your tenant’s rate limits and may affect login throughput.
</Warning>

Even though a single call is made to update the user profile, that operation is still subject to your tenant’s "Write User" [rate limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/management-api-endpoint-rate-limits). If the Rate Limit is hit when attempting to update metadata, Actions will retry the request as long as a `429` HTTP status code is returned. The delay between retries is governed by the value of the `X-RateLimit-Reset` header returned as part of the `429` response.

## Redirects

In the event of a Redirect invoked with `api.redirect.sendUserTo()`, any pending user or app metadata updates will be applied to the user profile before the user is redirected to the external site. To learn more, see [Redirecting With Actions](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/redirect-with-actions).

## Learn more

* [Redirect with Actions](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/redirect-with-actions)


# Metadata Field Names and Data Types
Source: https://auth0.com/docs/manage-users/user-accounts/metadata/metadata-fields-data

Describes user metadata, app metadata, and application (client) metadata field names, data types, and limitations and restrictions.

Auth0 distinguishes between three types of metadata used to store specific kinds of information.

<Warning>
  Auth0 metadata is not a secure data store and should not be used to store sensitive information, such as high-risk secrets and Personally Identifiable Information (PII) like social security numbers or credit card numbers. Auth0 customers are strongly encouraged to evaluate the data stored in metadata and only store that which is necessary for identity and access management purposes.
</Warning>

<table>
  <thead>
    <tr>
      <th><strong>Metadata Type</strong></th>
      <th><strong>Field Name</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>User Information</strong></td>
      <td><code>user\_metadata</code></td>
      <td>Stores user attributes such as preferences that do not impact a user's core functionality. This data <strong>can</strong> be edited by logged in users if you build a form using the Management API and should <strong>not</strong> be used as a secure data store.</td>
    </tr>

    <tr>
      <td><strong>Access Information</strong></td>
      <td><code>app\_metadata</code></td>
      <td>Stores information such as permissions, Auth0 plan, and external IDs that can impact user access to features. This data <strong>cannot</strong> be edited by users and there are restrictions for what can be stored in this field.</td>
    </tr>

    <tr>
      <td><strong>Application Information</strong></td>
      <td><code>client\_metadata</code> in the <code>Client</code> object, <code>context.clientMetadata</code> in Rules, and <code>event.client.metadata</code> in post-login Actions.</td>
      <td>Stores information about an application (or <em>client</em> in OIDC OAuth2 terminology). For example, the URL for the application home page (any value that Auth0 doesn’t set in the application settings).</td>
    </tr>
  </tbody>
</table>

## Metadata field names

### Accepted characters

Field names must not contain the `.` (dot) or `$` (dollar sign) characters.

For example, this is not allowed:

```json lines theme={null}
{
  "preference.color": "pink"
}
```

But you can expand it like this:

```json lines theme={null}
{
    "preference": { 
        "color": "pink" 
    }
}
```

### Dynamic field names

Field names should be static. Dynamic field names reduce indexing efficiency and cause degradation in search queries. A static schema is easier to search, manipulate, and work with.

Instead of doing this:

```json lines theme={null}
{
    "participants": [
        "Alice": {
            "role": "sender"
         },
        "Bob": {
            "role": "receiver"
        }
    ]
}
```

Do this:

```json lines theme={null}
{
    "participants": [
        {
            "name": "Alice",
            "role": "sender"
        },
        {
            "name" : "Bob",
            "role": "receiver"
        }
    ]
}
```

### Name collision

Avoid using the same name for `app_metadata` fields and root profile fields. The `app_metadata` field is merged onto the root profile in both Rules and Actions, which may override root profile fields.

For example, if a user has a `groups` field present on their root profile (returned from a <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>) and a `groups` field within `app_metadata`, their profile might look like this:

```json lines theme={null}
{
    "user_id": "samlp|example-samlp-connection|username@domain.com",
    "groups": [
        "external-group-1",
        "external-group-2"
    ],
    "app_metadata": {
        "groups": [
            "internal-group-1",
            "internal-group-2"
        ]
    }
}
```

When you read the `groups` field on the [User object](/docs/customize/rules/user-object-in-rules) from a [Rule](/docs/manage-users/user-accounts/metadata/manage-metadata-rules), it will return: `["internal-group-1", "internal-group-2"]`.

## Metadata data types

Metadata fields support all [JSON-compatible data types](https://datatracker.ietf.org/doc/html/rfc7159):

* String
* Number
* Array
* Object

Make sure to keep data types consistent between users. For example, if you store a value as a string for one user (`user.user_metadata.age = "23"`) and as a number for another user (`user.user_metadata.age = 23`), you may encounter issues when retrieving the data.

## Limitations and restrictions

### Rate limits

When you update metadata during login with [Rules](/docs/manage-users/user-accounts/metadata/manage-metadata-rules) or [Actions](/docs/manage-users/user-accounts/metadata/manage-user-metadata), you are subject to your tenant’s rate limits. To learn more, read [Management API Endpoint Rate Limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/management-api-endpoint-rate-limits).

<Warning>
  You should only store data related to user authentication in metadata. The storage and search capabilities of Auth0 are designed for use cases that do not require heavy search and/or update frequency.

  If you need to maintain detailed profile-related data for users, you should do so in an external system. You can store the user’s identifier from that system as a metadata field in Auth0.
</Warning>

### Size limits and storage

* There is a 1 MB per-user limit on user data that can be indexed, queried, and returned by the [user search endpoint](https://auth0.com/docs/api/management/v2/users/get-users). If a user profile is larger than 1 MB, any attribute values larger than 256 characters within `app_metadata` and `user_metadata` will not be searchable or returned in a search result. If the user profile is still over 1 MB after omitting these large values, then none of the `app_metadata` and `user_metadata` attributes will be searchable or returnable for that user. Auth0 captures and logs instances where a user profile is still over 1MB after omittances under the `wum` [event code](/docs/deploy-monitor/logs/log-event-type-codes). The [get user endpoint](https://auth0.com/docs/api/management/v2/users/get-users-by-id) must be used to retrieve all metadata attributes for oversized user profiles.
* When you set the `user_metadata` field using the Auth0 Authentication API [Signup endpoint](https://auth0.com/docs/api/authentication?javascript#signup), you can include a maximum of 10 string fields whose values do not exceed 500 characters each. For an example of working with metadata during a custom signup process, read [Custom Signup](/docs/libraries/custom-signup).
* The `client_metadata` field can have a maximum of 10 keys. Its keys and values have a maximum length of 255 characters each and cannot contain UTF-8 special characters.

### Restrictions

The `app_metadata` field must not contain any of these properties:

* `__tenant`
* `_id`
* `blocked`
* `clientID`
* `created_at`
* `email_verified`
* `email`
* `globalClientID`
* `global_client_id`
* `identities`
* `lastIP`
* `lastLogin`
* `loginsCount`
* `metadata`
* `multifactor_last_modified`
* `multifactor`
* `updated_at`
* `user_id`

## Learn more

* [Manage Metadata with Rules](/docs/manage-users/user-accounts/metadata/manage-metadata-rules)
* [Manage Metadata Using the Management API](/docs/manage-users/user-accounts/metadata/manage-metadata-api)
* [Configure Application Metadata](/docs/get-started/applications/configure-application-metadata)
* [User Data Storage](/docs/secure/security-guidance/data-security/user-data-storage)


# Resend Verification Emails
Source: https://auth0.com/docs/manage-users/user-accounts/resend-verification-emails

Describes how to resend verification emails to users via the Auth0 Management Dashboard and the Auth0 Management API.

If you need to resend a verification email to a user, you can resend it using the Auth0 User Management Dashboard or the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

<Tabs>
  <Tab title="Use Auth0 Dashboard">
    You can use the Auth0 Dashboard to resend a verification email to a user.

    1. In the Dashboard, go to [**User Management > Users**](https://manage.auth0.com/#/users).
    2. Select the user.
    3. Select the **Actions** dropdown menu, and then select **Send Verification Email**.

    If you enable [Multiple Custom Domains](/docs/customize/custom-domains/multiple-custom-domains), you have the option **Domain** to select the notification domain for your tenant.
  </Tab>

  <Tab title="Use Auth0 Management API">
    You can use the Auth0 Management API to resend a verification email to a user.

    1. Get a [Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the `update:users` scope.
    2. Call the Management API [Send an email address verification email](https://auth0.com/docs/api/management/v2#!/Jobs/post_verification_email) endpoint with the user's `user_id`.

    #### Request example

    ```json lines theme={null}
    {
       "user_id":"auth0|62463410c0242d00699461c8"
    }
    ```

    #### Response example

    ```json lines theme={null}
    {
       "type":"verification_email",
       "status":"pending",
       "created_at":"2022-03-31T23:08:05.612Z",
       "id":"job_PyfpRHlmpkSoDmCv"
    }
    ```

    If you enable [Multiple Custom Domains](/docs/customize/custom-domains/multiple-custom-domains), you need to include the `auth0-custom-domain` HTTP header. To learn more, review [Multiple Custom Domains](/docs/customize/custom-domains/multiple-custom-domains#customize-email-handling-using-the-management-api).

    #### Check job status

    You can check the status of the job created with the Management API [Send an email address verification email](https://auth0.com/docs/api/management/v2#!/Jobs/post_verification_email) endpoint.

    1. Get the job's `id` (returned in the response).
    2. Call the Management API [Get a job](https://auth0.com/docs/api/management/v2#!/Jobs/get_jobs_by_id) endpoint with the job's `id`.

    ##### Response example

    ```json lines theme={null}
    {
       "type":"verification_email",
       "status":"completed",
       "created_at":"2022-03-31T23:08:05.612Z",
       "id":"job_PyfpRHlmpkSoDmCv"
    }
    ```
  </Tab>
</Tabs>


# Unlink Devices from Users
Source: https://auth0.com/docs/manage-users/user-accounts/unlink-devices-from-users

Describes how to unlink devices assigned to a user using the Auth0 Dashboard.

You can unlink the devices assigned to a user using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. This revokes the <Tooltip href="/docs/glossary?term=refresh+token">refresh token</Tooltip> for the selected device.

1. Go to [Dashboard > User Management > Users](https://manage.auth0.com/#/users) and click the name of the user.
2. Click the **Devices** view, then click the trashcan icon next to the device you want to unlink, and confirm.

   <Frame>
     <img alt="Dashboard - Users & Roles - Users - Devices View" />
   </Frame>

## Learn more

* [Configure Device User Code Settings](/docs/get-started/tenant-settings/configure-device-user-code-settings)
* [Device Authorization Flow](/docs/get-started/authentication-and-authorization-flow/device-authorization-flow)


# User Account Linking
Source: https://auth0.com/docs/manage-users/user-accounts/user-account-linking

Understand how user accounts can be linked in Auth0 from various identity providers.

<Callout icon="file-lines">
  Connected Accounts enables a single Auth0 user profile to be linked to multiple external accounts. When you enable Connected Accounts for a supported external provider, Auth0 automatically adds the account for that provider to the user profile after the user successfully logs in. To learn more, read [Connected Accounts for Token Vault](/docs/secure/tokens/token-vault/connected-accounts-for-token-vault).
</Callout>

Auth0 supports the linking of user accounts from various <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip>. This allows a user to authenticate from any of their accounts and still be recognized by your app and associated with the same user profile.

<Card title="Availability varies by Auth0 plan">
  Both your specific login implementation and your Auth0 plan or custom agreement affect whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

Auth0 treats all identities as separate by default. For example, if a user logs in first against the Auth0 database and then via Google or Facebook, these two attempts would appear to Auth0 as two separate users. You can implement functionality to enable a user to explicitly link accounts. In this scenario, the user would log in with an initial provider, perhaps Google. Your application would provide a link or button to enable them to link another account to the first one. The user would click on this link/button and your application would make a call so that when the user logs in with the second provider, the second account is linked with the first.

## Advantages of linking accounts

* Allows users to log in with any identity provider without creating a separate profile for each
* Allows registered users to use a new social or <Tooltip href="/docs/glossary?term=passwordless">passwordless</Tooltip> login but continue using their existing profile
* Allows users that registered using a passwordless login to link to an account with a more complete profile
* Allows your apps to retrieve user profile data stored in various connections

## Precautions

Insecurely linking accounts can allow malicious actors to access legitimate user accounts. Please remain aware of the following:

For both manual and automatic account links, your tenant should request authentication for **both** accounts before linking occurs.

In addition, **every** manual account link should prompt the user to enter credentials.

## How it works

The process of linking accounts merges two existing user profiles into a single one. When linking accounts, a **primary account** and a **secondary account** must be specified.

In the example below you can see how the resulting linked profile will be for the sample primary and secondary accounts.

<AuthCodeGroup>
  ```json Profile of primary account lines expandable theme={null}
  {
    "email": "your0@email.com",
    "email_verified": true,
    "name": "John Doe",
    "given_name": "John",
    "family_name": "Doe",
    "picture": "https://lh3.googleusercontent..../photo.jpg",
    "gender": "male",
    "locale": "en",
    "user_id": "google-oauth2|115015401343387192604",
    "identities": [
      {
        "provider": "google-oauth2",
        "user_id": "115015401343387192604",
        "connection": "google-oauth2",
        "isSocial": true
      }
    ],
    "user_metadata": {
      "color": "red"
    },
    "app_metadata": {
      "roles": [
        "Admin"
      ]
    },
    ...
  }
  ```

  ```json Profile of secondary account lines theme={null}
  {
    "phone_number": "+14258831929",
    "phone_verified": true,
    "name": "+14258831929",
    "updated_at": "2015-10-08T18:35:18.102Z",
    "user_id": "sms|560ebaeef609ee1adaa7c551",
    "identities": [
      {
        "user_id": "560ebaeef609ee1adaa7c551",
        "provider": "sms",
        "connection": "sms",
        "isSocial": false
      }
    ],
    "user_metadata": {
      "color": "blue"
    },
    "app_metadata": {
      "roles": [
        "AppAdmin"
      ]
    },
    ...
  }
  ```

  ```json Linked profile lines expandable theme={null}
  {
    "email": "your0@email.com",
    "email_verified": true,
    "name": "John Doe",
    "given_name": "John",
    "family_name": "Doe",
    "picture": "https://lh3.googleusercontent..../photo.jpg",
    "gender": "male",
    "locale": "en",
    "user_id": "google-oauth2|115015401343387192604",
    "identities": [
      {
        "provider": "google-oauth2",
        "user_id": "115015401343387192604",
        "connection": "google-oauth2",
        "isSocial": true
      },
      {
        "profileData": {
          "phone_number": "+14258831929",
          "phone_verified": true,
          "name": "+14258831929"
        },
        "user_id": "560ebaeef609ee1adaa7c551",
        "provider": "sms",
        "connection": "sms",
        "isSocial": false
      }
    ],
    "user_metadata": {
      "color": "red"
    },
    "app_metadata": {
      "roles": [
        "Admin"
      ]
    },
    ...
  }
  ```
</AuthCodeGroup>

Note that:

* The `user_id` and all other main profile properties continue to be those of the primary identity
* The first identity in the `user.identities` array is the primary identity
* The secondary account is now embedded in the `user.identities` array of the primary profile
* The attributes of the secondary account are placed inside the `profileData` field of the corresponding identity inside the array
* The `user_metadata` and `app_metadata` of the primary account have not changed
* The `user_metadata` and `app_metadata` of the secondary account are discarded
* There is no automatic merging of user profiles with associated identities
* The secondary account is removed from the users list
* If you delete the primary account, the secondary account is deleted as well

### Metadata merge

Metadata is not automatically merged during account linking. If you want to merge it, you have to do it manually using the Manage API [`/users/patch_users_by_id`](https://auth0.com/docs/api/v2#!/Users/patch_users_by_id) endpoint.

The [Auth0 Node.js SDK for APIv2](https://github.com/auth0/node-auth0/) is also available.

To learn more, read [Understand How Metadata Works in User Profiles](/docs/manage-users/user-accounts/metadata)

## Scenarios

There are two different ways of implementing account linking:

* User-initiated account linking: allow your users to link their accounts using an admin screen in your app.
* Suggested account linking: identify accounts with the same email address and prompt the user in your app to link them.

### User-initiated account linking

Typically, account linking will be initiated by an authenticated user. Your app must provide the UI, such as a **Link accounts** button on the user's profile page.

To learn more about how to implement user-initiated account linking in a Single Page Application, read [Client-Side Account Linking](/docs/manage-users/user-accounts/user-account-linking/user-initiated-account-linking-client-side-implementation). To learn more about how to implement user-initiated account linking in a Regular Web Application, read [Server-Side Account Linking](/docs/manage-users/user-accounts/user-account-linking/suggested-account-linking-server-side-implementation).

### Suggested account linking

You can find accounts with the same email, and prompt the users to link them. For example, a user can create an account with Google with the `user@gmail.com`, and then log in with Facebook, with an account linked to the same email.

If that occurs, you can show users the list of available accounts so they can link them, by first authenticating with the account they will be linking to.

You can also use the [Account Link Extension](/docs/customize/extensions/account-link-extension) to achieve the same outcome.

<Warning>
  Previously, in some cases, you could use ID Tokens to link and unlink user accounts. This functionality is being deprecated. You will have to use Access Tokens in all cases.
</Warning>

## Learn more

* [Link User Accounts](/docs/manage-users/user-accounts/user-account-linking/link-user-accounts)
* [Unlink User Accounts](/docs/manage-users/user-accounts/user-account-linking/unlink-user-accounts)
* [User-Initiated Account Linking: Client-Side Implementation](/docs/manage-users/user-accounts/user-account-linking/user-initiated-account-linking-client-side-implementation)
* [User Account Linking: Server-Side Implementation](/docs/manage-users/user-accounts/user-account-linking/suggested-account-linking-server-side-implementation)


# Link User Accounts
Source: https://auth0.com/docs/manage-users/user-accounts/user-account-linking/link-user-accounts

Understand how to link user accounts from various identity providers, so your users can authenticate from any account and be recognized by your app.

<Card title="Availability varies by Auth0 plan">
  Both your specific login implementation and your Auth0 plan or custom agreement affect whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

You can link user accounts through a variety of methods:

* Action with external linking application
* Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>
* Auth0.js library

## Action with external linking application

You can use an Action along with an external linking application to link user accounts with the Management API.

<Warning>
  **Auth0 does not automatically change to the correct primary** **user** after Account Linking, so it must be changed within the Actions code upon successful Account Linking.

  **Every manual account link should prompt the user to enter credentials**. Your tenant should request authentication for both accounts before linking occurs to avoid allowing malicious actors to access legitimate user accounts.
</Warning>

The following steps illustrate an example implementation:

1. Action identifies the potential user accounts to link (if they exist).

2. Action redirects the user to an external linking application with a token payload that contains candidate user identities:

   ```json lines theme={null}
   {
     "current_identity": {
       "user_id": event.user.user_id,
       "provider": event.connection.strategy,
       "connection": event.connection.name
     },
     "candidate_identities": [
       {
         "user_id": USER_ID_1,
         "provider": PROVIDER_1,
         "connection": CONNECTION_1
       },
       {
         "user_id": USER_ID_2,
         "provider": PROVIDER_2,
         "connection": CONNECTION_2
       },
       ...
     ]
   }
   ```

3. External linking application prompts the user to authenticate using the credentials for the account they wish to link.

4. External linking application redirects the user back to the Action with a token payload that contains the primary and secondary user identities:

   ```json lines theme={null}
   {
     "primary_identity": {
       "user_id": PRIMARY_USER_ID,
       "provider": PRIMARY_PROVIDER_STRATEGY,
       "connection": PRIMARY_CONNECTION_NAME,
     },
     "secondary_identity": {
       "user_id": SECONDARY_USER_ID,
       "provider": SECONDARY_PROVIDER_STRATEGY,
       "connection": SECONDARY_CONNECTION_NAME,
     }
   }
   ```

5. Action validates the authenticity and contents of the token.

6. Action calls the Management API to link the accounts based on the results from the external linking application.

7. Action switches to the primary user if it doesn’t match the `event.user.user_id`.

### Example: Account linking Action

```javascript lines expandable theme={null}
const { ManagementClient, AuthenticationClient } = require('auth0');

/**
 * @constant {string} - Account linking timestamp key
 */
const ACCOUNT_LINKING_TIMESTAMP_KEY = 'account_linking_timestamp';

/**
 * @constant {number} - TTL leeway factor
 */
const TTL_LEEWAY_FACTOR = .2;

/**
 * @constant {string[]} - Properties to complete based on identities
 */
const PROPERTIES_TO_COMPLETE = [
  'given_name',
  'family_name',
  'name'
];

/**
* @param {Event} event
* @param {PostLoginAPI} api
* @returns {Promise<string>} - Management API access token
*/
const getManagementAccessToken = async (event, api) => {
  const managementApiTokenCacheKey = `mgmt-api-token-${event.secrets.MANAGEMENT_API_CLIENT_ID}`;
  const { value: cachedAccessToken } = api.cache.get(managementApiTokenCacheKey) || {};

  if (cachedAccessToken) {
    return cachedAccessToken;
  }

  const authentication = new AuthenticationClient({
    domain: event.secrets.MANAGEMENT_API_DOMAIN,
    clientId: event.secrets.MANAGEMENT_API_CLIENT_ID,
    clientSecret: event.secrets.MANAGEMENT_API_CLIENT_SECRET
  });

  const { data: { access_token: accessToken, expires_in: expiresIn } } = await authentication.oauth.clientCredentialsGrant({
    audience: `https://${event.secrets.MANAGEMENT_API_DOMAIN}/api/v2/`,
  });

  api.cache.set(managementApiTokenCacheKey, accessToken, {
    ttl: expiresIn - expiresIn * TTL_LEEWAY_FACTOR
  });

  return accessToken;
}

/**
* @param {Event} event
* @param {PostLoginAPI} api
* @returns {Promise<ManagementClient>} - Auth0 management client
*/
const getManagementClient = async (event, api) => {
  const token = await getManagementAccessToken(event, api);

  return new ManagementClient({
    domain: event.secrets.MANAGEMENT_API_DOMAIN,
    token,
  });
}

/**
 * @typedef `{Object}` CandidateUsersIdentities
 * @property {string} user_id
 * @property {string} provider
 * @property {string} connection
 */

/**
 * @typedef `{Object}` CandidateUsers
 * @property {string} email
 * @property `{Boolean}` email_verified
 * @property {string} user_id
 * @property {CandidateUsersIdentities[]} identities
 */

/**
 * @typedef `{Object}` CandidateIdentities
 * @property {User['user_id']} user_id
 * @property {string} connection
 * @property {string} provider
 */

/**
 * @typedef `{Object}` LinkedIdentity
 * @property {User['user_id']} user_id
 */

/**
* @param {Event} event
* @param {PostLoginAPI} api
* @returns {Promise<CandidateUsers[]>} - List of users with the same email address
*/
const getUsersWithSameEmail = async (event, api) => {
  const management = await getManagementClient(event, api);

  const { data } = await management.usersByEmail.getByEmail({
    email: event.user.email,
    fields: 'email,email_verified,user_id,identities',
    include_fields: true,
  });

  return data;
}

/**
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {CandidateUsers[]} candidateUsers - List of users that match the same email address
* @returns {CandidateIdentities[]} - List of candidate identities
*/
const getCandidateIdentitiesWithVerifiedEmail = (event, candidateUsers) => {
  // Removes current user from candidate identities and checks the email is verified
  return candidateUsers
    .filter((user) => user.user_id !== event.user.user_id && user.email_verified === true)
    .filter((user) => user.identities)
    // .flatMap((user) => user.identities)
    .map((user) => {
      return {
        user_id: user.user_id,
        provider: user.identities[0].provider,
        connection: user.identities[0].connection
      }
    });
}

/**
* @param {Event} event
* @param {PostLoginAPI} api
* @returns {Promise<LinkedIdentity[]>} - Linked identity response
*/
const linkIdentities = async (event, api, primaryIdentity, secondaryIdentity) => {
  const management = await getManagementClient(event, api);

  const { data } = await management.users.link({
    id: primaryIdentity.user_id
  }, {
    provider: secondaryIdentity.provider,
    user_id: secondaryIdentity.user_id
  });

  return data;
}

/**
* @param {Event} event
* @param {PostLoginAPI} api
* @returns {void}
*/
const completeProperties = (event, api) => {
  // go over each property and try to get missing
  // information from secondary identities for ID Token
  for (const property of PROPERTIES_TO_COMPLETE) {
    if (!event.user[property]) {
      for(const identity of event.user.identities) {
        if (identity.profileData && identity.profileData[property]) {
          api.idToken.setCustomClaim(property, identity.profileData[property]);
          break;
        }
      }
    }
  }
}

/**
* Handler that will be called during the execution of a PostLogin flow.
*
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {
  if (
    !event.secrets.MANAGEMENT_API_DOMAIN ||
    !event.secrets.MANAGEMENT_API_CLIENT_ID ||
    !event.secrets.MANAGEMENT_API_CLIENT_SECRET ||
    !event.secrets.SESSION_TOKEN_SHARED_SECRET ||
    !event.secrets.ACCOUNT_LINKING_SERVICE_URL
  ) {
    console.log('Missing required configuration for account linking action. Skipping.');
    return;
  }

  // We won't process users for account linking until they have verified their email address.
  // We might consider rejecting logins here or redirecting users to an external tool to
  // remind the user to confirm their email address before proceeding.
  //
  // In this example, we simply won't process users unless their email is verified.
  if (!event.user.email_verified) {
    return;
  }

  // Account linking has already been processed and completed for this user. No further work
  // to be done in this Action.
  if (event.user.app_metadata[ACCOUNT_LINKING_TIMESTAMP_KEY] !== undefined) {
    completeProperties(event, api);
    return;
  }

  try {
    const candidateUsers = await getUsersWithSameEmail(event, api);

    // If there are no candidates, skip
    if (!Array.isArray(candidateUsers) || candidateUsers.length === 0) {
      return;
    }

    const candidateIdentities = getCandidateIdentitiesWithVerifiedEmail(event, candidateUsers);

    // If there are no candidates, skip
    if (candidateIdentities.length === 0) {
      return;
    }

    // Encode the current user and an array of their candidate identities
    const sessionToken = api.redirect.encodeToken({
      payload: {
        current_identity: {
          user_id: event.user.user_id,
          provider: event.connection.strategy,
          connection: event.connection.name
        },
        candidate_identities: candidateIdentities,
      },
      secret: event.secrets.SESSION_TOKEN_SHARED_SECRET,
      expiresInSeconds: 20
    });

    // Redirect to your Account Linking UX
    api.redirect.sendUserTo(event.secrets.ACCOUNT_LINKING_SERVICE_URL, {
      query: {
        session_token: sessionToken
      }
    });
  } catch (err) {
    console.error(err);
    // Handle error
  }
};

/**
* Handler that will be invoked when this action is resuming after an external redirect. If your
* onExecutePostLogin function does not perform a redirect, this function can be safely ignored.
*
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onContinuePostLogin = async (event, api) => {
  // Validate the session token passed to `/continue?state` and extract the `user_id` claim. 
  const { primary_identity: primaryIdentity, secondary_identity: secondaryIdentity } = api.redirect.validateToken({
    secret: event.secrets.SESSION_TOKEN_SHARED_SECRET,
    tokenParameterName: 'session_token',
  });

  try {
    const linkedIdentity = await linkIdentities(event, api, primaryIdentity, secondaryIdentity);

    if (linkedIdentity !== undefined && linkedIdentity.length > 1) {
      if (primaryIdentity.user_id !== event.user.user_id) {
        // The account linking service indicated that the primary user changed.
        api.authentication.setPrimaryUser(primaryIdentity.user_id);
      }
      // Mark the user as having been processed for account linking
      api.user.setAppMetadata(ACCOUNT_LINKING_TIMESTAMP_KEY, Date.now());

      completeProperties(event, api);
    } else {
      // Handle error
      api.access.deny('Account linking failure');
    }
  } catch (err) {
    console.error(err);
    // Handle error
  }
};
```

## Management API

You can use the Management API [Link a user account](https://auth0.com/docs/api/v2#!/Users/post_identities) endpoint in two ways:

* User-initiated client-side account linking using <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> with the `update:current_user_identities` scope.
* Server-side account linking using access tokens with the `update:users` scope.

### User-initiated client-side account linking

For user-initiated client-side account linking, you need an access token that contains the following items in the payload:

* `update:current_user_identites` scope
* `user_id` of the primary account as part of the URL
* <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> of the secondary account that is signed with RS256 and includes an `aud` claim identifying the client that matches the value of the requesting access token's `azp` claim.

An access token that contains the `update:current_user_identities` scope can only be used to update the information of the currently logged-in user. Therefore, this method is suitable for scenarios where the user initiates the linking process.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities' \
    --header 'authorization: Bearer MANAGEMENT_API_ACCESS_TOKEN' \
    --header 'content-type: application/json' \
    --data '{"link_with":"SECONDARY_ACCOUNT_ID_TOKEN"}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer MANAGEMENT_API_ACCESS_TOKEN");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"link_with":"SECONDARY_ACCOUNT_ID_TOKEN"}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities"

  	payload := strings.NewReader("{"link_with":"SECONDARY_ACCOUNT_ID_TOKEN"}")

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

  	req.Header.Add("authorization", "Bearer MANAGEMENT_API_ACCESS_TOKEN")
  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities")
    .header("authorization", "Bearer MANAGEMENT_API_ACCESS_TOKEN")
    .header("content-type", "application/json")
    .body("{"link_with":"SECONDARY_ACCOUNT_ID_TOKEN"}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities',
    headers: {
      authorization: 'Bearer MANAGEMENT_API_ACCESS_TOKEN',
      'content-type': 'application/json'
    },
    data: {link_with: 'SECONDARY_ACCOUNT_ID_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MANAGEMENT_API_ACCESS_TOKEN",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"link_with": @"SECONDARY_ACCOUNT_ID_TOKEN" };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{"link_with":"SECONDARY_ACCOUNT_ID_TOKEN"}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MANAGEMENT_API_ACCESS_TOKEN",
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"link_with":"SECONDARY_ACCOUNT_ID_TOKEN"}"

  headers = {
      'authorization': "Bearer MANAGEMENT_API_ACCESS_TOKEN",
      'content-type': "application/json"
      }

  conn.request("POST", "/{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities")

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

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer MANAGEMENT_API_ACCESS_TOKEN'
  request["content-type"] = 'application/json'
  request.body = "{"link_with":"SECONDARY_ACCOUNT_ID_TOKEN"}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer MANAGEMENT_API_ACCESS_TOKEN",
    "content-type": "application/json"
  ]
  let parameters = ["link_with": "SECONDARY_ACCOUNT_ID_TOKEN"] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

### Server-side account linking

For server-side account linking, you need an access token that contains the following items in the payload:

* `update:users` scope
* `user_id` of the primary account as part of the URL
* `user_id` of the secondary account
* ID token of the secondary account that is signed with RS256 and includes an `aud` claim identifying the client that matches the value of the requesting access token's `azp` claim.

Access tokens that contain the `update:users` scope can be used to update the information of any user. Therefore, this method is intended for use in server-side code only.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities' \
    --header 'authorization: Bearer MANAGEMENT_API_ACCESS_TOKEN' \
    --header 'content-type: application/json' \
    --data '{"provider":"SECONDARY_ACCOUNT_PROVIDER", "user_id": "SECONDARY_ACCOUNT_USER_ID"}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer MANAGEMENT_API_ACCESS_TOKEN");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"provider":"SECONDARY_ACCOUNT_PROVIDER", "user_id": "SECONDARY_ACCOUNT_USER_ID"}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities"

  	payload := strings.NewReader("{"provider":"SECONDARY_ACCOUNT_PROVIDER", "user_id": "SECONDARY_ACCOUNT_USER_ID"}")

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

  	req.Header.Add("authorization", "Bearer MANAGEMENT_API_ACCESS_TOKEN")
  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities")
    .header("authorization", "Bearer MANAGEMENT_API_ACCESS_TOKEN")
    .header("content-type", "application/json")
    .body("{"provider":"SECONDARY_ACCOUNT_PROVIDER", "user_id": "SECONDARY_ACCOUNT_USER_ID"}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities',
    headers: {
      authorization: 'Bearer MANAGEMENT_API_ACCESS_TOKEN',
      'content-type': 'application/json'
    },
    data: {provider: 'SECONDARY_ACCOUNT_PROVIDER', user_id: 'SECONDARY_ACCOUNT_USER_ID'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MANAGEMENT_API_ACCESS_TOKEN",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"provider": @"SECONDARY_ACCOUNT_PROVIDER",
                                @"user_id": @"SECONDARY_ACCOUNT_USER_ID" };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{"provider":"SECONDARY_ACCOUNT_PROVIDER", "user_id": "SECONDARY_ACCOUNT_USER_ID"}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MANAGEMENT_API_ACCESS_TOKEN",
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"provider":"SECONDARY_ACCOUNT_PROVIDER", "user_id": "SECONDARY_ACCOUNT_USER_ID"}"

  headers = {
      'authorization': "Bearer MANAGEMENT_API_ACCESS_TOKEN",
      'content-type': "application/json"
      }

  conn.request("POST", "/{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities")

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

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer MANAGEMENT_API_ACCESS_TOKEN'
  request["content-type"] = 'application/json'
  request.body = "{"provider":"SECONDARY_ACCOUNT_PROVIDER", "user_id": "SECONDARY_ACCOUNT_USER_ID"}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer MANAGEMENT_API_ACCESS_TOKEN",
    "content-type": "application/json"
  ]
  let parameters = [
    "provider": "SECONDARY_ACCOUNT_PROVIDER",
    "user_id": "SECONDARY_ACCOUNT_USER_ID"
  ] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

The secondary user account's `user_id` and `provider` can be deduced by its unique identifier. For example, for the identifier `google-oauth2|108091299999329986433`:

* `provider` is `google-oauth2`
* `user_id` is `108091299999329986433`

Alternatively, you can you can send the secondary account's ID token instead of the `provider` and `user_id`:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities' \
    --header 'authorization: Bearer MANAGEMENT_API_ACCESS_TOKEN' \
    --header 'content-type: application/json' \
    --data '{"link_with":"SECONDARY_ACCOUNT_ID_TOKEN"}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer MANAGEMENT_API_ACCESS_TOKEN");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"link_with":"SECONDARY_ACCOUNT_ID_TOKEN"}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities"

  	payload := strings.NewReader("{"link_with":"SECONDARY_ACCOUNT_ID_TOKEN"}")

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

  	req.Header.Add("authorization", "Bearer MANAGEMENT_API_ACCESS_TOKEN")
  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities")
    .header("authorization", "Bearer MANAGEMENT_API_ACCESS_TOKEN")
    .header("content-type", "application/json")
    .body("{"link_with":"SECONDARY_ACCOUNT_ID_TOKEN"}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities',
    headers: {
      authorization: 'Bearer MANAGEMENT_API_ACCESS_TOKEN',
      'content-type': 'application/json'
    },
    data: {link_with: 'SECONDARY_ACCOUNT_ID_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MANAGEMENT_API_ACCESS_TOKEN",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"link_with": @"SECONDARY_ACCOUNT_ID_TOKEN" };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{"link_with":"SECONDARY_ACCOUNT_ID_TOKEN"}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MANAGEMENT_API_ACCESS_TOKEN",
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"link_with":"SECONDARY_ACCOUNT_ID_TOKEN"}"

  headers = {
      'authorization': "Bearer MANAGEMENT_API_ACCESS_TOKEN",
      'content-type': "application/json"
      }

  conn.request("POST", "/{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities")

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

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer MANAGEMENT_API_ACCESS_TOKEN'
  request["content-type"] = 'application/json'
  request.body = "{"link_with":"SECONDARY_ACCOUNT_ID_TOKEN"}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer MANAGEMENT_API_ACCESS_TOKEN",
    "content-type": "application/json"
  ]
  let parameters = ["link_with": "SECONDARY_ACCOUNT_ID_TOKEN"] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

## Auth0.js library

You can use the Auth0.js library to perform client-side account linking. Read [Auth0.js v9 Reference > User management](/docs/libraries/auth0js#user-management) to learn more.

## Learn more

* [User Account Linking: Server-Side Implementation](/docs/manage-users/user-accounts/user-account-linking/suggested-account-linking-server-side-implementation)
* [User-Initiated Account Linking: Client-Side Implementation](/docs/manage-users/user-accounts/user-account-linking/user-initiated-account-linking-client-side-implementation)
* [Unlink User Accounts](/docs/manage-users/user-accounts/user-account-linking/unlink-user-accounts)


# User Account Linking: Server-Side Implementation
Source: https://auth0.com/docs/manage-users/user-accounts/user-account-linking/suggested-account-linking-server-side-implementation

Describes how to link user accounts with a regular web app using server-side code using a sample scenario.

Auth0 supports the linking of user accounts from various <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip>. You can use server-side code to link accounts on a regular web application, engaging the user and asking them for permission before proceeding. Your code will authenticate users and search for and identify users using their email addresses. Your application will then prompt the user to link their accounts by authenticating with the target account's credentials, and later link the accounts.

You can find the full source of this sample application [on GitHub](https://github.com/auth0-samples/auth0-link-accounts-sample/tree/master/RegularWebApp).

1. Log the user into your application.<br />

   The user authenticates to your application using [Universal Login](/docs/authenticate/login/auth0-universal-login). To learn more, read the [Regular Web App Quickstart](/docs/quickstart/webapp), asking for a token for the Auth0 Management API audience (audience=`https://{yourDomain}/api/v2/`).

2. Search for users with identical email addresses.<br />

   You can get the user profile and the list of users with the same verified email.

   ```javascript lines expandable theme={null}
   router.get("/", async (req, res) => {
     const { sub, email_verified } = req.openid.user;
     //fetch user profile containing the user_metadata and app_metadata properties
     try {
       let getUsersWithSameVerifiedEmail = [];
       const getUserProfile = auth0Client.getUser(sub);
       if (email_verified)
         // account linking is only offered verified email
         getUsersWithSameVerifiedEmail = auth0Client.getUsersWithSameVerifiedEmail(
           req.openid.user
         );

       const [user, suggestedUsers] = await Promise.all([
         getUserProfile,
         getUsersWithSameVerifiedEmail,
       ]);

       const flashError = clear(req);
       res.render("user", {
         user,
         suggestedUsers,
         wrongAccountError: flashError && flashError === Errors.WrongAccount,
       });
     } catch (err) {
       debug("GET /user[s] failed: %o", err);
       res.render("error", err);
     }
   });
   ```

   To get a list of all of the user records with the same email address, your application calls the Auth0 Management API's [Get Users By Email endpoint](https://auth0.com/docs/api/v2#!/users-by-email/get_users_by_email) using a [Management API Access Token](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the `read:users` scope.

   ```javascript lines theme={null}
   const request = require('request');
   class Auth0Client {
   ...
   async getUsersWithSameVerifiedEmail({ sub, email }) {
     return await this.request({
       url: `${process.env.ISSUER_BASE_URL}/api/v2/users-by-email?email=${email}`,
     });
   }
   ```

3. Prompt the user to link accounts.

   1. If Auth0 returns one or more records with matching email addresses, the user will see the list along with the following message prompting them to link the accounts.
   2. If the user wants to link a given account, they can click **Link** next to the appropriate account.

      <Frame>
        <img alt="Example application with server-side account linking page" />
      </Frame>

4. When the user clicks **Link**, your application will ask the user to authenticate with the target account, and then perform account linking.

   <Warning>
     To retain and merge the `user_metadata` from the secondary account, you must retrieve and merge it into the metadata for the primary account before calling the API endpoint. After the accounts are linked, the metadata for the secondary account is discarded.

     When you initiate account linking, you can select which identity will be used as the primary account and which as the secondary. This choice will depend on which set of attributes you want to retain in the primary profile.
   </Warning>

   The following code snippet shows how to verify and merge metadata:

   ```javascript lines expandable theme={null}
   async function accountLink(req, res, next) {
   const {
     linking: { targetUserId },
   } = req.appSession;
   const { sub: authenticatedTargetUserId } = req.openidTokens.claims();
   if (authenticatedTargetUserId !== targetUserId) {
     debug(
       "Skipping account linking as the authenticated user(%s)  is different than target linking user (%s)",
       authenticatedTargetUserId,
       targetUserId
     );
     set(req, Errors.WrongAccount);
     return next();
   }

   debug(
     "User %s succesfully authenticated. Account linking with %s... ",
     authenticatedTargetUserId,
     targetUserId
   );
   const { id_token: targetIdToken } = req.openidTokens;
   const { sub: primaryUserId } = req.appSession.claims;

   try {
     await mergeMetadata(primaryUserId, authenticatedTargetUserId);
     await auth0Client.linkAccounts(primaryUserId, targetIdToken);
     debug("Accounts linked.");
   } catch (err) {
     debug("Linking failed %o", err);
   } finally {
     next();
   }
   }
   ```

5. Your application calls the Auth0 Management API's [Link a User Account endpoint](https://auth0.com/docs/api/v2#!/Users/post_identities) using a [Management API Access Token](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the `update:users` scope.

## Metadata merge example

The following example shows explicitly how the `user_metadata` and `app_metadata` from the secondary account gets merged into the primary account using the [Node.js Auth0 SDK for API V2](https://github.com/auth0/node-auth0).

```javascript lines expandable theme={null}
/*
 * Recursively merges user_metadata and app_metadata from secondary into primary user.
 * Data of primary user takes preponderance.
 * Array fields are joined.
 */
async function mergeMetadata(primaryUserId, secondaryUserId) {
  // load both users with metedata.
  const [primaryUser, secondaryUser] = await Promise.all(
    [primaryUserId, secondaryUserId].map((uid) => auth0Client.getUser(uid))
  );

  const customizerCallback = function (objectValue, sourceValue) {
    if (_.isArray(objectValue)) {
      return sourceValue.concat(objectValue);
    }
  };
  const mergedUserMetadata = _.merge(
    {},
    secondaryUser.user_metadata,
    primaryUser.user_metadata,
    customizerCallback
  );
  const mergedAppMetadata = _.merge(
    {},
    secondaryUser.app_metadata,
    primaryUser.app_metadata,
    customizerCallback
  );
  await auth0Client.updateUser(primaryUserId, {
    user_metadata: mergedUserMetadata,
    app_metadata: mergedAppMetadata,
  });
}
```

## Learn more

* [Check API Calls](/docs/troubleshoot/authentication-issues/check-api-calls)
* [Troubleshoot Invalid Token Errors](/docs/troubleshoot/basic-issues/invalid-token-errors)


# Unlink User Accounts
Source: https://auth0.com/docs/manage-users/user-accounts/user-account-linking/unlink-user-accounts

Learn how to use the Management API Unlink a User Account endpoint to unlink an identity from the target user account making it a separate user account again.

Use the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> [Unlink a User Account](https://auth0.com/docs/api/management/v2#!/Users/delete_user_identity_by_user_id) endpoint or the Auth0.js library to unlink an identity from the target user account making it a separate user account again.

The result of the unlinking process is the following:

* The secondary account is removed from the identities array of the primary account.
* A new secondary user account is created.
* The secondary account will have no metadata.

If your goal is to delete the secondary identity entirely, you must first unlink the accounts, and then [delete the newly created secondary account](/docs/manage-users/user-accounts/delete-users).

Depending on from where you call the endpoint, use one of these two scopes:

* `update:current_user_identities` from [client-side code](/docs/manage-users/user-accounts/user-account-linking/user-initiated-account-linking-client-side-implementation)
* `update:users` from [server-side code](/docs/manage-users/user-accounts/user-account-linking/suggested-account-linking-server-side-implementation)

The endpoint uses the following parameters:

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>id</code></td>
      <td><code>string</code></td>
      <td>ID of the primary user account (required)</td>
    </tr>

    <tr>
      <td><code>provider</code></td>
      <td><code>string</code></td>
      <td>identity provider name of the secondary linked account (e.g. <code>google-oauth2</code>)</td>
    </tr>

    <tr>
      <td><code>user\_id</code></td>
      <td><code>string</code></td>
      <td>ID of the secondary linked account (e.g. <code>123456789081523216417</code> part after the \`</td>
    </tr>
  </tbody>
</table>

If your instance has users from multiple providers, you may also include `[connection_name]|` before the `user_id` stringto name the provider (for example, `"user-id": "google-oauth2|123456789081523216417").`

## Response example

```json lines theme={null}
[
  {
    "connection": "Initial-Connection",
    "user_id": "5457edea1b8f22891a000004",
    "provider": "auth0",
    "isSocial": false,
    "access_token": "",
    "profileData": {
      "email": "",
      "email_verified": false,
      "name": "",
      "username": "johndoe",
      "given_name": "",
      "phone_number": "",
      "phone_verified": false,
      "family_name": ""
    }
  }
]
```

## Use JWT from the primary account

To unlink accounts, call the Management API [Unlink a User Account endpoint](https://auth0.com/docs/api/v2#!/Users/delete_user_identity_by_user_id) using the <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> from the primary account for authorization:

<AuthCodeBlock />

## Use Access Token with the update:users scope

If you need to unlink two or more user accounts, call the Management API [Unlink a User Account endpoint](https://auth0.com/docs/api/v2#!/Users/delete_user_identity_by_user_id) using an [Management API Access Token](https://auth0.com/docs/api/v2/tokens) with the `update:users` scope.

```javascript lines theme={null}
function unlinkAccount(secondaryProvider, secondaryUserId) {
  var primaryUserId = localStorage.getItem('user_id');
  var primaryAccessToken = localStorage.getItem('access_token');

  // Uses the Access Token of the primary user as a bearer token to identify the account
  // which will have the account unlinked to, and the user id of the secondary user, to identify
  // the user that will be unlinked from the primary account.

  $.ajax({
    type: 'DELETE',
    url: 'https://' + AUTH0_DOMAIN +'/api/v2/users/' + primaryUserId +
         '/identities/' + secondaryProvider + '/' + secondaryUserId,
    headers: {
      'Authorization': 'Bearer ' + primaryAccessToken
    }
  }).then(function(identities){
    alert('unlinked!');
    showLinkedAccounts(identities);
  }).fail(function(jqXHR){
    alert('Error unlinking Accounts: ' + jqXHR.status + ' ' + jqXHR.responseText);
  });
}
```

## Unlink accounts from server-side code

1. Update the user in session with the new array of identities (each of which represent a separate user account).

```javascript lines theme={null}
const ensureLoggedIn = require('connect-ensure-login').ensureLoggedIn();
const Auth0Client = require('../Auth0Client');
const express = require('express');
const router = express.Router();
...
router.post('/unlink-accounts/:targetUserProvider/:targetUserId',ensureLoggedIn, (req,res,next) => {
  Auth0Client.unlinkAccounts(req.user.id, req.params.targetUserProvider, req.params.targetUserId)
  .then( identities => {
    req.user.identities = req.user._json.identities = identities;
    res.send(identities);
  })
  .catch( err => {
    console.log('Error unlinking accounts!',err);
    next(err);
  });
});
```

1. Call the Management API v2 [Unlink a User Account endpoint](https://auth0.com/docs/api/v2#!/Users/delete_user_identity_by_user_id) using an [Management API Access Token](https://auth0.com/docs/api/v2/tokens) with the `update:users` scope.

<AuthCodeBlock />

## Learn more

* [Link User Accounts](/docs/manage-users/user-accounts/user-account-linking/link-user-accounts)
* [User Account Linking: Server-Side Implementation](/docs/manage-users/user-accounts/user-account-linking/suggested-account-linking-server-side-implementation)
* [User-Initiated Account Linking: Client-Side Implementation](/docs/manage-users/user-accounts/user-account-linking/user-initiated-account-linking-client-side-implementation)


# User-Initiated Account Linking: Client-Side Implementation
Source: https://auth0.com/docs/manage-users/user-accounts/user-account-linking/user-initiated-account-linking-client-side-implementation

Learn how to provide a client-side UI that allows users to authenticate to their other accounts and link these to their primary account using a SPA.

Auth0 supports the linking of user accounts from various <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip>. One way to implement this functionality is to enable the user to explicitly link accounts. In this scenario, the user authenticates through the UI of your Single Page Application (SPA) and can later use a link or button to link another account to the first one. When the user clicks on this link/button, your application makes a call so that when the user logs in with the second provider, the second account is linked with the first.

When you initiate account linking, you can select which identity to use as the primary account and which to use as the secondary. This choice depends on which set of attributes you want to retain in the primary profile, as you will only retain the attributes from the primary account.

Create a React Sample Single Page Application with this project [on GitHub](https://github.com/auth0-samples/auth0-link-accounts-sample/tree/master/SPA).

In this project, open the `auth_config.json` file in your text editor and update the domain and `client_id` with your details.

Add `http://localhost:3000` in the “Allowed Callback URLs”, “Allowed Logout URLs”, “Allowed Web Origins” field.

1. Log the user in to your application.<br /><br />

   The user authenticates to your SPA using using [Universal Login](/docs/authenticate/login/auth0-universal-login), requesting an [Access Token for the Management API](https://auth0.com/docs/api/management/v2/get-access-tokens-for-spas).<br /><br />

   In the typical SPA login, the callback is handled client-side by the same page, and a JWT is received after successful authentication. To learn more, read the [Single-Page App Quickstart](/docs/quickstart/spa).

2. The user initiates account linking. Your SPA must provide a UI for the user to initiate a link to their other accounts. For example, your SPA could contain a user's settings page:<br /><br />

   When the user clicks on the **Link Account** button, your app redirects the user to the Universal Login page, when they log in with the connection they want to link to. After successful authentication, use the obtained token to link the accounts.<br /><br />

   You could also add a button for each connection (e.g. 'Link Facebook Account', 'Link Google Account') and redirect the user to `/authorize` with the `connection` parameter set (e.g. `/authorize?connection=facebook`).

   <Frame>
     <img alt="Example profile page with user account linking" />
   </Frame>

3. Link accounts by calling the Auth0 Management API's [Link a User Account endpoint](https://auth0.com/docs/api/v2#!/Users/post_identities).

   <Warning>
     To retain and merge the `user_metadata` from the secondary account, you must retrieve and merge it into the metadata for the primary account before calling the API endpoint. After the accounts are linked, the metadata for the secondary account is discarded.

     When you initiate account linking, you can select which identity will be used as the primary account and which as the secondary. This choice will depend on which set of attributes you want to retain in the primary profile.
   </Warning>

4. In the `linkAccount` function, call the Management API. Authenticate with the API using the primary JWT, which is the Access Token, and link using the primary user's ID and the secondary JWT, which is the secondary user's ID Token.

   ```javascript lines expandable theme={null}
   const linkAccount = async () => {
     const accessToken = await auth0.getTokenSilently();
     const { sub } = await auth0.getUser();
     // authenticateUser should authenticate the user with the account to be linked
     // See the Github sample for more details
     const {
       __raw: targetUserIdToken,
       email_verified,
       email,
     } = await authenticateUser();
     if (!email_verified) {
       throw new Error(
         `Account linking is only allowed to a verified account. Please verify your email ${email}.`
       );
     }
     await fetch(`https://${config.domain}/api/v2/users/${sub}/identities`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
         Authorization: `Bearer ${accessToken}`,
       },
       body: JSON.stringify({
         link_with: targetUserIdToken,
       }),
     });
   };
   ```

<Card title="Account Linking: Access Tokens vs. ID Tokens">
  Previously, in some cases, you could use ID Tokens to link and unlink user accounts. This functionality is being deprecated. You will have to use Access Tokens in all cases. The change in the unlinking of accounts is that you can no longer use an ID Token in the Authorization header. An Access Token must be used instead. The functionality is still available but not recommended and affected users are encouraged to migrate. See [Migration Guide: Account Linking with Access Tokens vs. ID Tokens](/docs/troubleshoot/product-lifecycle/past-migrations/link-user-accounts-with-access-tokens-migration) for details.
</Card>

## Learn more

* [Link User Accounts](/docs/manage-users/user-accounts/user-account-linking/link-user-accounts)
* [Unlink User Accounts](/docs/manage-users/user-accounts/user-account-linking/unlink-user-accounts)
* [User Account Linking: Server-Side Implementation](/docs/manage-users/user-accounts/user-account-linking/suggested-account-linking-server-side-implementation)


# User Profiles
Source: https://auth0.com/docs/manage-users/user-accounts/user-profiles

Understand how user profiles work in Auth0.

To access any of the applications in your tenant, each user must have a profile in the tenant. User profiles contain information about your users such as name and contact information. You can manage user profiles through the [Auth0 Dashboard](/docs/get-started/auth0-overview/dashboard) and the [Auth0 Management API](https://auth0.com/docs/api/management/v2).

## User data sources

User data can come from many sources, including your own databases as well as social, legal, and enterprise <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip>. Some examples include Google, Facebook, Active Directory, or <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip>. You can normalize user data that comes from any supported data source.

User profile attributes can include information from the identity provider. These are examples:

<table>
  <thead>
    <tr>
      <th>User data from...</th>
      <th>Might include...</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>LinkedIn</td>
      <td>Current employer or degrees achieved</td>
    </tr>

    <tr>
      <td>Facebook</td>
      <td>Profile picture, birthday, or relationship status</td>
    </tr>

    <tr>
      <td>Active Directory</td>
      <td>Employee number, job title, or department</td>
    </tr>
  </tbody>
</table>

Auth0 refers to all user data sources as **connections** because Auth0 connects to them to authenticate the user.

### User data normalization

Auth0 supports a variety of [Identity Providers](/docs/authenticate/identity-providers) and [Database Connections](/docs/authenticate/database-connections). Each connection can return a different set of user attributes. Sometimes different connections use different names for the same attribute. For example, `surname` from one connection might be `last_name` and `family_name` from other user data sources.

To handle this complexity, Auth0 provides a [normalized user profile](/docs/manage-users/user-accounts/user-profiles/normalized-user-profiles), an Auth0-specific standard for storing user data.

<Callout icon="file-lines">
  To view the Auth0 [user profile data structure](/docs/manage-users/user-accounts/user-profiles/user-profile-structure), go to [Dashboard > User Management > Users](https://manage.auth0.com/#/users) and then click on a user.
</Callout>

### User profile attribute mapping

#### AD/LDAP connector

For Active Directory or any other LDAP connections that use the Auth0 AD/LDAP connector, there is a mechanism for mapping user profile attributes in the directory service to the Auth0 normalized user profile. A `profileMapper.js` file, located in the installation directory of the AD/LDAP connector, maps the attributes when a user authenticates.

#### SAML assertions

If your application uses the SAML protocol to communicate with Auth0, one of two mechanisms match the user attributes to the Auth0 normalized user profile:

<table>
  <thead>
    <tr>
      <th>If Auth0 is a...</th>
      <th>Then...</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>SAML Service Provider</td>
      <td>Use the SAML connection's Mappings tab to map attributes coming from an IDP to attributes in the Auth0 user profile: Go to <a href="https://manage.auth0.com/#/connections/database/enterprise/samlp">Dashboard  > Authentication > Enterprise > SAMLP</a>. Click on the name of the SAML connection and click <strong>Mappings</strong>.</td>
    </tr>

    <tr>
      <td>SAML Identity Provider</td>
      <td>Use the Settings tab of Application AddOns to map attributes from the Auth0 user profile to attributes in the SAML Assertion sent back to the Service Provider: Go to <a href="https://manage.auth0.com/#/connections/database/applications">Dashboard  > Applications</a>. Click on the name of your application, click <strong>Addons</strong>, and click <strong>SAML2 Web App</strong>.</td>
    </tr>
  </tbody>
</table>

### Account linking

Users can log into an application initially using one connection (such as a custom database), then later log in using a different connection (such as Facebook). In this case, the `user_id` for the second authentication is different from the `user_id` for the first authentication.

Auth0 provides a mechanism to link the two accounts. When Auth0 links the two accounts, it stores two elements in the `identities` array portion of the user profile, one for each connection.

Auth0 does not merge user profile attributes from multiple providers. Auth0 sources **core** user profile attributes from the first provider used.

To learn more, read [User Account Linking](/docs/manage-users/user-accounts/user-account-linking).

### Caching user profiles

Auth0 caches the user profile received from a connection before passing it on to the calling application. This cache is in the Auth0 database. Each time the user authenticates, Auth0 updates the cache. To learn more, read [Update User Profile Using Your Database](/docs/manage-users/user-accounts/user-profiles/update-user-profiles-using-your-database).

## Custom user profile data

Auth0 lets you store [metadata](/docs/manage-users/user-accounts/metadata), which is data related to each user that has not come from the identity provider. You can use `user_metadata` to store custom attributes such as the user's favorite color or hobby.

## Change user profile data

You can modify a user's profile information in a number of ways.

* [Scopes](/docs/get-started/apis/scopes): The authentication flows supported by Auth0 include an optional parameter that lets you specify a scope. This controls the user profile information (claims) included in the <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> (<Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip>).
* [Auth0 Dashboard](/docs/manage-users/user-accounts/manage-users-using-the-dashboard): The Dashboard lets you manually edit the `user_metadata` and `app_metadata` portions of any user’s profile.
* [Management API](/docs/manage-users/user-accounts/manage-users-using-the-management-api): You can read, update, and delete user profiles stored in the Auth0 database.
* [Custom database scripts](/docs/authenticate/database-connections/custom-db/templates): If you’re using a custom database as a connection, you can write scripts to implement lifecycle events such as create, login, verify, delete and change password. Auth0 provides templates for these scripts that you can modify for the particular database and schema.
* [Rules](/docs/manage-users/user-accounts/metadata/manage-metadata-rules): Use Rules to augment the user profile during the authentication transaction, and optionally persist those changes back to Auth0.

## Access user profiles

Both apps and the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> can access a user's profile information.

### Access user profiles from apps

Once Auth0 completes authentication and returns control to your application, it provides the user profile to the application. At a low level, you can accomplish this using one of the application [protocols](/docs/authenticate/protocols) supported by Auth0. However, most developers prefer to use the Auth0 SDKs. To learn more, read [Quickstarts](/docs/quickstarts).

One SDK is the Auth0 Lock widget, which provides a user login interface. To learn more, read:

* [Lock for Web](/docs/libraries/lock)
* [Lock Swift](/docs/libraries/lock-swift)
* [Lock.Android](/docs/libraries/lock-android)

If you want your web app to have a custom login UI, you can use Auth0.js. This headless JavaScript library for Auth0 invokes authentication flow (and other tasks) and receives a User Profile object in return. To learn more, read [Auth0.js v9 Reference](/docs/libraries/auth0js).

### Access user profiles from the Management API

Auth0 provides a REST API that allows applications and services to access and manipulate the User Profile object.

The API Explorer lets users interactively explore the Management API. It provides:

* API calls available
* Information required for each call
* Information returned by each call

With the explorer, users can try each endpoint in the explorer UI or via a CuRL command on the command line. To try one of the Management API commands, go to the [API Explorer](https://auth0.com/docs/api/management/v2). Select the access required under **Scopes** within the command you choose, such as `update:users`, and then click **TRY**.

The Auth0 Authentication API is specifically for authentication flows. To learn more, read [Authentication API Explorer](https://auth0.com/docs/api/authentication). Typically, most of these endpoints are used by the various Auth0 SDKs, not your own code.

## The difference between user profiles and tokens

In the authentication flows described above, Auth0 returns a set of tokens in lieu of a full user profile.

One of the returned tokens is the ID token, which is a JSON Web Token (JWT) that contains user profile attributes represented in the form of claims. These claims are statements about the user. A claim can be trusted if the consumer of the token can verify its signature, which (in the case of HS256) is generated with the Auth0 app’s <Tooltip href="/docs/glossary?term=client+secret">client secret</Tooltip>. If your app uses RS256 encryption, the ID token will be signed with a private key and verified with a public key. Your app can then decode the JWT and get the user information contained in its payload. Examples of this information are the user's name, email, and other data that is typically part of the user experience.

The claims within a JWT generally contain only a subset of the information available in the user profile. The purpose is to minimize the token size. To learn more, read [JSON Web Tokens](/docs/secure/tokens/json-web-tokens).

There are three other types of tokens that can be returned during authentication:

* Auth0 <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>
* Third-party provider access token
* <Tooltip href="/docs/glossary?term=Refresh+token">Refresh token</Tooltip>

To learn more about tokens and claims, read [Tokens](/docs/secure/tokens).

## Learn more

* [Check User Profiles](/docs/troubleshoot/authentication-issues/check-user-profiles)
* [Troubleshoot Custom Domains](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-custom-domains)
* [Troubleshoot SAML Errors](/docs/troubleshoot/authentication-issues/saml-errors)
* [Verify Connections](/docs/troubleshoot/basic-issues/verify-connections)
* [Check API Calls](/docs/troubleshoot/authentication-issues/check-api-calls)
* [Auth0.Android Login, Logout, and User Profiles](/docs/libraries/auth0-android/auth0-android-login-logout-and-user-profiles)


# Configure Identity Provider Connection for User Profile Updates
Source: https://auth0.com/docs/manage-users/user-accounts/user-profiles/configure-connection-sync-with-auth0

Learn how to update connection preferences for an upstream identity provider so you can control when user profile root attributes are updated.

You can update connection preferences for an upstream <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> so you can control when updates to user profile root attributes are allowed using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

By default, user profile attributes provided by identity providers other than Auth0 (such as Google, Facebook, or X) are not directly editable because they are updated from the identity provider each time the user logs in.

To be able to edit the name, nickname, given\_name, family\_name, or picture root attributes on the normalized user profile, you must configure your connection sync with Auth0 so that user attributes will be updated from the identity provider only on user profile creation.

<Callout icon="file-lines">
  **Sync Users at Login** does not apply to passwordless connections, and cannot be enabled through the Tenant UI or Management API.
</Callout>

You can edit [root attributes individually](/docs/manage-users/user-accounts/user-profiles/root-attributes/update-root-attributes-for-users) or as a [bulk import](/docs/manage-users/user-accounts/user-profiles/root-attributes/set-root-attributes-during-user-import) using the Management API.

## Use the Dashboard

1. Go to [Auth0 Dashboard > Authentication](https://manage.auth0.com/#/connections), and select the type of connection: Database, Social, Enterprise, or Passwordless.
2. Select the name of a connection to see its settings.
3. Locate the **Advanced** section, toggle the **Sync user profile attributes at each login** switch to the desired setting, and select **Save**.

## Use the Management API

Before completing this step, you should first [retrieve the existing values of the connection's `options` object](/docs/authenticate/identity-providers/retrieve-connection-options) to avoid overriding the current values. If you do not, parameters missing from the original object will be lost after you update.

Make a `PATCH` call to the [Update a Connection endpoint](https://auth0.com/docs/api/management/v2#!/Connections/patch_connections_by_id). Make sure you include the original options values in the call to avoid overriding the current values. Also, be sure to replace `CONNECTION_ID`, `MGMT_API_ACCESS_TOKEN`, and `ATTRIBUTE_UPDATE_VALUE` placeholder values with your connection ID, Management API <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, and attribute update value, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/connections/CONNECTION_ID' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{"options":{"set_user_root_attributes": "ATTRIBUTE_UPDATE_VALUE"}}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/connections/CONNECTION_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", "{"options":{"set_user_root_attributes": "ATTRIBUTE_UPDATE_VALUE"}}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/connections/CONNECTION_ID"

  	payload := strings.NewReader("{"options":{"set_user_root_attributes": "ATTRIBUTE_UPDATE_VALUE"}}")

  	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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/connections/CONNECTION_ID")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{"options":{"set_user_root_attributes": "ATTRIBUTE_UPDATE_VALUE"}}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/connections/CONNECTION_ID',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: {options: {set_user_root_attributes: 'ATTRIBUTE_UPDATE_VALUE'}}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"options": @{ @"set_user_root_attributes": @"ATTRIBUTE_UPDATE_VALUE" } };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/connections/CONNECTION_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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/connections/CONNECTION_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 => "{"options":{"set_user_root_attributes": "ATTRIBUTE_UPDATE_VALUE"}}",
    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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"options":{"set_user_root_attributes": "ATTRIBUTE_UPDATE_VALUE"}}"

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

  conn.request("PATCH", "/{yourDomain}/api/v2/connections/CONNECTION_ID", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/connections/CONNECTION_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 = "{"options":{"set_user_root_attributes": "ATTRIBUTE_UPDATE_VALUE"}}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = ["options": ["set_user_root_attributes": "ATTRIBUTE_UPDATE_VALUE"]] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/connections/CONNECTION_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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>CONNECTION\_ID</code></td>
      <td>ID of the connection for which you want to allow updates to root attributes.</td>
    </tr>

    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td><a href="https://auth0.com/docs/api/management/v2/tokens">Access Token for the Management API</a> with the scope <code>update:connections</code>.</td>
    </tr>

    <tr>
      <td><code>ATTRIBUTE\_UPDATE\_VALUE</code></td>
      <td>Indicates when you want to allow updates to user profile root attributes. Valid values are <code>on\_first\_login</code> and <code>on\_each\_login</code>. Defaults to <code>on\_each\_login</code> for new connections.</td>
    </tr>
  </tbody>
</table>

## Learn more

* [Retrieve Connection Options](/docs/authenticate/identity-providers/retrieve-connection-options)
* [Set Root Attributes During User Import](/docs/manage-users/user-accounts/user-profiles/root-attributes/set-root-attributes-during-user-import)
* [Set Root Attributes During User Signup](/docs/manage-users/user-accounts/user-profiles/root-attributes/set-root-attributes-during-user-sign-up)
* [Update Root Attributes for Users](/docs/manage-users/user-accounts/user-profiles/root-attributes/update-root-attributes-for-users)
* [Promote Connections to Domain Level](/docs/authenticate/identity-providers/promote-connections-to-domain-level)


# Normalized User Profile Schema
Source: https://auth0.com/docs/manage-users/user-accounts/user-profiles/normalized-user-profile-schema

Normalized User Profile schema reference.

The attributes that Auth0 maps to a common schema are listed below.

Fields that are always generated:

* `name`: the user's full name.
* `nickname`: by default, the local part of the user's email.
* `picture`: the URL of the [user's picture](/docs/manage-users/user-accounts/change-user-picture). If unavailable, Auth0 uses the Gravatar image associated with the user's email address.
* `user_id`: the user's unique identifier. This is unique per Connection, but the same for all apps that authenticate via that Connection.

By default, a user's `name`, `nickname`, and `picture` attributes provided by <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> other than Auth0 (such as Google, Facebook, or X) are not directly editable since they are updated from the identity provider each time a user logs in. If you want to be able to edit these attributes, you must [configure your connection sync with Auth0](/docs/manage-users/user-accounts/user-profiles/configure-connection-sync-with-auth0) so that user attributes will be updated from the identity provider only on user profile creation. Root attributes will then be available to be [edited individually](https://auth0.com/docs/api/management/guides/users/update-root-attributes-users) or [by bulk import](https://auth0.com/docs/api/management/guides/users/update-root-attributes-users) using the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

Fields that are generated when the details are available:

* `email`: the user's email address.
* `email_verified`: a boolean indicating if the user's email address has been verified.
* `given_name`: the user's first name.
* `family_name`: the user's last name.

When creating a user with the [Create a User Management API endpoint](https://auth0.com/docs/api/management/v2#!/Users/post_users) you can submit the `given_name` and `family_name`. By default, a user's `given_name` and `family_name` attributes provided by identity providers other than Auth0 (such as Google, Facebook, or X) are not directly editable since they are updated from the identity provider each time a user logs in. If you want to be able to edit these attributes, you must [configure your connection sync with Auth0](/docs/manage-users/user-accounts/user-profiles/configure-connection-sync-with-auth0) so that user attributes will be updated from the identity provider only on user profile creation. Root attributes will then be available to be [edited individually](https://auth0.com/docs/api/management/guides/users/update-root-attributes-users) or [by bulk import](https://auth0.com/docs/api/management/guides/users/update-root-attributes-users) using the Management API

If you are writing a login script for a [custom database](/docs/authenticate/database-connections/custom-db) you are responsible for returning the information in the user profile. A unique and immutable `user_id` property is mandatory to correctly identify the user (see [Uniquely Identify Users](/docs/manage-users/user-accounts/identify-users)).

## Additional Attributes

The User Profile includes an array of identities. In the most common case (logging in with a single provider), the array contains only one element. If the user has multiple accounts linked, the array will have an element for each associated account. See [User Account Linking](/docs/manage-users/user-accounts/user-account-linking) for more information.

The `identities` array contains the following attributes:

* `connection`: the name of the connection.
* `isSocial`: indicates if the provider is a Social provider.
* `provider`: the provider of the connection.
* `user_id`: the unique identifier of the user for this connection.

Auth0 passes all other properties supplied by the identity provider to your app, even if they are not mapped to the standard attributes listed above.


# Normalized User Profiles
Source: https://auth0.com/docs/manage-users/user-accounts/user-profiles/normalized-user-profiles

Understand how Auth0 normalizes common user properties in the user profile.

The normalized user profile is an Auth0-specific way of standardizing and storing user-related information. Because every <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> (IdP) provides a different set of information about a user, Auth0 normalizes common profile properties into a protocol-agnostic representation of the user when storing user-related claims. For example, `family_name` in the normalized user profile contains details that may be returned to an IdP as `surname` or `last_name`.

As such, the Auth0 claims included in the normalized user profile differ from the standard set of claims that can be returned in <Tooltip href="/docs/glossary?term=ID+Tokens">ID Tokens</Tooltip> from the [Authentication API's `oauth/token` endpoint](https://auth0.com/docs/api/authentication#get-token) or in the response from the [`/userinfo`](https://auth0.com/docs/api/authentication#user-profile) endpoint (both of which follow the requirements detailed in the OIDC specification).

To learn about the attributes included in the normalized user profile and understand how you can work with them, read [User Profile Structure](/docs/manage-users/user-accounts/user-profiles/user-profile-structure).

## Learn more

* [Sample User Profiles](/docs/manage-users/user-accounts/user-profiles/sample-user-profiles)
* [User Profile Root Attributes](/docs/manage-users/user-accounts/user-profiles/root-attributes)
* [User Data Storage](/docs/secure/security-guidance/data-security/user-data-storage)
* [Check User Profiles](/docs/troubleshoot/authentication-issues/check-user-profiles)
* [Check API Calls](/docs/troubleshoot/authentication-issues/check-api-calls)


# Understand How Progressive Profiling Works
Source: https://auth0.com/docs/manage-users/user-accounts/user-profiles/progressive-profiling

Understand how progressive profiling can gather information about users over time as they engage with your website or application.

Progressive profiling is the process of incrementally collecting additional information about your users as they engage with your website or application. You can gather detailed user information only when relevant to a user's activities.

For example, you could collect the user's name, email, and password during signup, then ask them for the name of their company and their job title the next time they log in. You can also use [Auth0 Forms](/docs/customize/forms/configure-progressive-profile-form) to design a flow that collects user information.

<Callout icon="file-lines">
  When you ask users for additional information, avoid asking for information that you may already have. For example, if a user signs up through a social connection that uses the OpenID Connect protocol (such as Google or Facebook), the identity provider (IdP) may return more user information than you think. To learn more, read [OpenID Connect Scopes](/docs/get-started/apis/scopes/openid-connect-scopes#standard-claims).
</Callout>

Implementing progressive profiling improves your users' experience by:

* Shortening registration forms.
* Avoiding repetitive questions.
* Collecting more relevant information.
* Increasing conversion rates.

## How it works

Every time a user authenticates through Auth0, Auth0 updates their user profile. The data used to update their profile can come from different sources:

* Attributes supplied by the <Tooltip href="/docs/glossary?term=IdP">IdP</Tooltip>.
* Attributes created dynamically with [Auth0 Actions](/docs/customize/actions).
* Attributes returned from calling APIs such as [FullContact](https://www.fullcontact.com/) and [Clearbit](https://clearbit.com/).
* Attributes managed by the application.

## Use action triggers

With the `post-login` action trigger, you can modify a user's `user_metadata` and `app_metadata` fields during the login flow. This is useful for tasks such as storing application-specific data on the user's profile, recording whether or not specific operations have occurred for a user, or caching the results of expensive operations on the user profile so they can be re-used for future logins. To learn more, read [Manage User Metadata with the post-login Action Trigger](/docs/manage-users/user-accounts/metadata/manage-user-metadata).

## Use the Management API

You can use the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> [Update a User](https://auth0.com/docs/api/management/v2/#!/Users/patch_users_by_id) endpoint to update the profile data of an authenticated user, including the `app_metadata` and `user_metadata` fields. To learn more, read [Manage Metadata Using the Management API](/docs/manage-users/user-accounts/metadata/manage-metadata-api).

## Use the Lock library

You can use the `additionalSignUpFields` option to add custom fields to user signup forms. When a user enters data into a custom field, Auth0 stores the value in their profile's `user_metadata` field. To learn more, read [Lock Configuration Options](/docs/libraries/lock/lock-configuration#additionalsignupfields-array-).

## Learn more

* [Understand How Metadata Works in User Profiles](/docs/manage-users/user-accounts/metadata)
* [Manage User Metadata with the post-login Action Trigger](/docs/manage-users/user-accounts/metadata/manage-user-metadata)


# User Profile Root Attributes
Source: https://auth0.com/docs/manage-users/user-accounts/user-profiles/root-attributes

Learn about root attributes available for the Auth0 normalized user profile and methods of updating them.

Auth0's normalized user profile contains a number of root attributes (attributes stored at the first, or root, level of the object), some of which may be updated. To learn more about the user profile structure and its attributes, read [User Profile Structure.](/docs/manage-users/user-accounts/user-profiles/user-profile-structure)

Methods for updating root attributes vary depending on connection type.

## Auth0 as the identity provider

When Auth0 is the <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> (IdP), subscribers may:

* Set root attributes [on user sign-up](https://auth0.com/docs/api/management/guides/users/set-root-attributes-user-signup) (via the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> or via public signup)
  or [on import](https://auth0.com/docs/api/management/guides/users/set-root-attributes-user-import)
* [Update root attributes individually](https://auth0.com/docs/api/management/guides/users/update-root-attributes-users) via the Management API

Auth0 is the IdP for the following connection types:

* [Regular database connections](/docs/authenticate/database-connections)
* [Custom database connections](/docs/authenticate/database-connections/custom-db) with import mode
* [Passwordless connections](/docs/authenticate/passwordless)

## Upstream identity providers

When an upstream IdP (like Google or Facebook) is used, subscribers have two options:

* The upstream IdP sets the root attributes when users are first created and then
  automatically updates them with each subsequent login. This is the default behavior.
* The upstream IdP sets the root attributes on user creation only and does not
  update them on subsequent logins, thereby allowing subscribers to [update root attributes individually](https://auth0.com/docs/api/management/guides/users/update-root-attributes-users) via the Management API. To enable this, you will need to [configure your connection sync with Auth0](https://auth0.com/docs/api/management/guides/connections/configure-connection-sync).

Upstream Identity Providers handle the following connection types:

* [Social connections](/docs/authenticate/identity-providers#social)
* [Enterprise connections](/docs/authenticate/identity-providers#enterprise)
* [Legal identity connections](/docs/authenticate/identity-providers#legal-identities)


# Set Root Attributes During User Import
Source: https://auth0.com/docs/manage-users/user-accounts/user-profiles/root-attributes/set-root-attributes-during-user-import

Learn how to set root attributes for users during import using the Auth0 Management API.

This guide will show you how to set root attributes for a user during import using Auth0's <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. This allows you to minimize the number of API calls required to set root attributes when importing users. To see which attributes you can import, visit [Normalized User Profile Structure](/docs/manage-users/user-accounts/user-profiles/user-profile-structure).

Make a `POST` call to the [Create Job to Import Users endpoint](https://auth0.com/docs/api/management/v2#!/Jobs/post_users_imports). Be sure to replace `MGMT_API_ACCESS_TOKEN`, `CONNECTION_ID`, and `JSON_USER_FILE_PATH` placeholder values with your Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, connection ID, and users filename, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/jobs/usersimports' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'content-type: multipart/form-data ' \
    --data '{ "connection_id": "CONNECTION_ID", "users": "JSON_USER_FILE_PATH" }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/jobs/usersimports");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "multipart/form-data ");
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddParameter("multipart/form-data ", "{ "connection_id": "CONNECTION_ID", "users": "JSON_USER_FILE_PATH" }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/jobs/usersimports"

  	payload := strings.NewReader("{ "connection_id": "CONNECTION_ID", "users": "JSON_USER_FILE_PATH" }")

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

  	req.Header.Add("content-type", "multipart/form-data ")
  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/jobs/usersimports")
    .header("content-type", "multipart/form-data ")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .body("{ "connection_id": "CONNECTION_ID", "users": "JSON_USER_FILE_PATH" }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/jobs/usersimports',
    headers: {
      'content-type': 'multipart/form-data ',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN'
    },
    data: '{ "connection_id": "CONNECTION_ID", "users": "JSON_USER_FILE_PATH" }'
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"multipart/form-data ",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };

  NSData *postData = [[NSData alloc] initWithData:[@"{ "connection_id": "CONNECTION_ID", "users": "JSON_USER_FILE_PATH" }" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/jobs/usersimports"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/jobs/usersimports",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "connection_id": "CONNECTION_ID", "users": "JSON_USER_FILE_PATH" }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN",
      "content-type: multipart/form-data "
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "connection_id": "CONNECTION_ID", "users": "JSON_USER_FILE_PATH" }"

  headers = {
      'content-type': "multipart/form-data ",
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN"
      }

  conn.request("POST", "/{yourDomain}/api/v2/jobs/usersimports", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/jobs/usersimports")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'multipart/form-data '
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request.body = "{ "connection_id": "CONNECTION_ID", "users": "JSON_USER_FILE_PATH" }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "multipart/form-data ",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN"
  ]

  let postData = NSData(data: "{ "connection_id": "CONNECTION_ID", "users": "JSON_USER_FILE_PATH" }".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/jobs/usersimports")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th><strong>Value</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td><a href="https://auth0.com/docs/api/management/v2/tokens">Access Token for the Management API</a> with the <Tooltip href="/docs/glossary?term=scope">scope</Tooltip> <code>create:users</code>.</td>
    </tr>

    <tr>
      <td><code>CONNECTION\_ID</code></td>
      <td>ID of the connection to which the users will be inserted. You can retrieve this info using the <a href="https://auth0.com/docs/api/management/v2#!/Connections/get_connections">Get All Connections endpoint</a>.</td>
    </tr>

    <tr>
      <td><code>JSON\_USER\_FILE\_PATH</code></td>
      <td>Filename of the file that contains the users to be imported. File should be in JSON format and include root attributes for users. For a list of available attributes, see <a href="/docs/manage-users/user-accounts/user-profiles/user-profile-structure#attributes">User Profile Attributes</a>. For an example of the file format, see <a href="/docs/manage-users/user-migration/bulk-user-import-database-schema-and-examples">Bulk User Import Database Schema and Examples</a>.</td>
    </tr>
  </tbody>
</table>

## Learn more

* [User Profile Structure](/docs/manage-users/user-accounts/user-profiles/user-profile-structure)
* [Update Root Attributes for Users](/docs/manage-users/user-accounts/user-profiles/root-attributes/update-root-attributes-for-users)
* [Set Root Attributes During User Signup](/docs/manage-users/user-accounts/user-profiles/root-attributes/set-root-attributes-during-user-sign-up)


# Set Root Attributes During User Signup
Source: https://auth0.com/docs/manage-users/user-accounts/user-profiles/root-attributes/set-root-attributes-during-user-sign-up

Learn how to set root attributes for users during signup using the Auth0 Management API.

You can set root attributes for a user during sign-up using Auth0's <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. This allows you to minimize the number of API calls required to set root attributes when creating users.

Make a `POST` call to the [Create a User endpoint](https://auth0.com/docs/api/management/v2#!/Users/post_users). Be sure to replace `MGMT_API_ACCESS_TOKEN`, `CONNECTION_NAME`, `EMAIL_VALUE`, `PASSWORD_VALUE`, `GIVEN_NAME_VALUE`, `FAMILY_NAME_VALUE`, `NAME_VALUE`, `NICKNAME_VALUE`, and `PICTURE` placeholder values with your Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, initial connection name, email address, password, given name, family name, name, nickname, and picture URL, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/users' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "connection": CONNECTION_NAME, "email": EMAIL_VALUE, "password": PASSWORD_VALUE, "given_name": GIVEN_NAME_VALUE, "family_name": FAMILY_NAME_VALUE,"name": NAME_VALUE, "nickname": NICKNAME_VALUE,"picture": PICTURE_VALUE }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("application/json", "{ "connection": CONNECTION_NAME, "email": EMAIL_VALUE, "password": PASSWORD_VALUE, "given_name": GIVEN_NAME_VALUE, "family_name": FAMILY_NAME_VALUE,"name": NAME_VALUE, "nickname": NICKNAME_VALUE,"picture": PICTURE_VALUE }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/users"

  	payload := strings.NewReader("{ "connection": CONNECTION_NAME, "email": EMAIL_VALUE, "password": PASSWORD_VALUE, "given_name": GIVEN_NAME_VALUE, "family_name": FAMILY_NAME_VALUE,"name": NAME_VALUE, "nickname": NICKNAME_VALUE,"picture": PICTURE_VALUE }")

  	req, _ := http.NewRequest("POST", 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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/users")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "connection": CONNECTION_NAME, "email": EMAIL_VALUE, "password": PASSWORD_VALUE, "given_name": GIVEN_NAME_VALUE, "family_name": FAMILY_NAME_VALUE,"name": NAME_VALUE, "nickname": NICKNAME_VALUE,"picture": PICTURE_VALUE }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/users',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: '{ "connection": CONNECTION_NAME, "email": EMAIL_VALUE, "password": PASSWORD_VALUE, "given_name": GIVEN_NAME_VALUE, "family_name": FAMILY_NAME_VALUE,"name": NAME_VALUE, "nickname": NICKNAME_VALUE,"picture": PICTURE_VALUE }'
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

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

  NSData *postData = [[NSData alloc] initWithData:[@"{ "connection": CONNECTION_NAME, "email": EMAIL_VALUE, "password": PASSWORD_VALUE, "given_name": GIVEN_NAME_VALUE, "family_name": FAMILY_NAME_VALUE,"name": NAME_VALUE, "nickname": NICKNAME_VALUE,"picture": PICTURE_VALUE }" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "connection": CONNECTION_NAME, "email": EMAIL_VALUE, "password": PASSWORD_VALUE, "given_name": GIVEN_NAME_VALUE, "family_name": FAMILY_NAME_VALUE,"name": NAME_VALUE, "nickname": NICKNAME_VALUE,"picture": PICTURE_VALUE }",
    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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "connection": CONNECTION_NAME, "email": EMAIL_VALUE, "password": PASSWORD_VALUE, "given_name": GIVEN_NAME_VALUE, "family_name": FAMILY_NAME_VALUE,"name": NAME_VALUE, "nickname": NICKNAME_VALUE,"picture": PICTURE_VALUE }"

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

  conn.request("POST", "/{yourDomain}/api/v2/users", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users")

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

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request["cache-control"] = 'no-cache'
  request.body = "{ "connection": CONNECTION_NAME, "email": EMAIL_VALUE, "password": PASSWORD_VALUE, "given_name": GIVEN_NAME_VALUE, "family_name": FAMILY_NAME_VALUE,"name": NAME_VALUE, "nickname": NICKNAME_VALUE,"picture": PICTURE_VALUE }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]

  let postData = NSData(data: "{ "connection": CONNECTION_NAME, "email": EMAIL_VALUE, "password": PASSWORD_VALUE, "given_name": GIVEN_NAME_VALUE, "family_name": FAMILY_NAME_VALUE,"name": NAME_VALUE, "nickname": NICKNAME_VALUE,"picture": PICTURE_VALUE }".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th><strong>Value</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td><a href="https://auth0.com/docs/api/management/v2/tokens">Access Token for the Management API</a> with the <Tooltip href="/docs/glossary?term=scope">scope</Tooltip> <code>create:users</code>.</td>
    </tr>

    <tr>
      <td><code>CONNECTION\_NAME</code></td>
      <td>Name of the connection through which the initial user information was received.</td>
    </tr>

    <tr>
      <td><code>EMAIL\_VALUE</code></td>
      <td>Email address of the user to be created.</td>
    </tr>

    <tr>
      <td><code>PASSWORD\_VALUE</code></td>
      <td>Password of the user to be created.</td>
    </tr>

    <tr>
      <td><code>GIVEN\_NAME\_VALUE</code></td>
      <td>Given name of the user to be created.</td>
    </tr>

    <tr>
      <td><code>FAMILY\_NAME\_VALUE</code></td>
      <td>Family name of the user to be created.</td>
    </tr>

    <tr>
      <td><code>NAME\_VALUE</code></td>
      <td>Full name of the user to be created.</td>
    </tr>

    <tr>
      <td><code>NICKNAME\_VALUE</code></td>
      <td>Nickname of the user to be created.</td>
    </tr>

    <tr>
      <td><code>PICTURE\_VALUE</code></td>
      <td>URL of the picture for the user to be created.</td>
    </tr>
  </tbody>
</table>

<Callout icon="file-lines">
  If you are using Lock or the [public signup endpoint](https://auth0.com/docs/api/authentication#signup) for user sign-up, you can set root attributes using the same method.
</Callout>

## Learn more

* [User Profile Structure](/docs/manage-users/user-accounts/user-profiles/user-profile-structure)
* [Update Root Attributes for Users](/docs/manage-users/user-accounts/user-profiles/root-attributes/update-root-attributes-for-users)
* [Set Root Attributes During User Import](/docs/manage-users/user-accounts/user-profiles/root-attributes/set-root-attributes-during-user-import)


# Update Root Attributes for Users
Source: https://auth0.com/docs/manage-users/user-accounts/user-profiles/root-attributes/update-root-attributes-for-users

Learn how to update root attributes in existing user profiles using the Auth0 Management API.

You can update root attributes for an existing user profile using Auth0's <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

Auth0's [Normalized User Profile](/docs/manage-users/user-accounts/user-profiles/user-profile-structure) features root attributes that you can update. The specific root attributes that you can update depend on the [connection](/docs/authenticate/identity-providers) type you're using. For details relevant to the connection you are using, see [User Profile Root Attributes](/docs/manage-users/user-accounts/user-profiles/root-attributes).

Make a `PATCH` call to the [Update a User endpoint](https://auth0.com/docs/api/management/v2/users/patch-users-by-id). Be sure to replace `USER_ID`, `MGMT_API_ACCESS_TOKEN`, `GIVEN_NAME_VALUE`, `FAMILY_NAME_VALUE`, `NAME_VALUE`, `NICKNAME_VALUE`, and `PICTURE` placeholder values with your user ID, Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, given name, family name, name, nickname, and picture URL, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/users/USER_ID' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "given_name": GIVEN_NAME_VALUE, "family_name": FAMILY_NAME_VALUE,"name": NAME_VALUE, "nickname": NICKNAME_VALUE,"picture": PICTURE_VALUE }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/USER_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", "{ "given_name": GIVEN_NAME_VALUE, "family_name": FAMILY_NAME_VALUE,"name": NAME_VALUE, "nickname": NICKNAME_VALUE,"picture": PICTURE_VALUE }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/users/USER_ID"

  	payload := strings.NewReader("{ "given_name": GIVEN_NAME_VALUE, "family_name": FAMILY_NAME_VALUE,"name": NAME_VALUE, "nickname": NICKNAME_VALUE,"picture": PICTURE_VALUE }")

  	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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/users/USER_ID")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "given_name": GIVEN_NAME_VALUE, "family_name": FAMILY_NAME_VALUE,"name": NAME_VALUE, "nickname": NICKNAME_VALUE,"picture": PICTURE_VALUE }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/users/USER_ID',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: '{ "given_name": GIVEN_NAME_VALUE, "family_name": FAMILY_NAME_VALUE,"name": NAME_VALUE, "nickname": NICKNAME_VALUE,"picture": PICTURE_VALUE }'
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

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

  NSData *postData = [[NSData alloc] initWithData:[@"{ "given_name": GIVEN_NAME_VALUE, "family_name": FAMILY_NAME_VALUE,"name": NAME_VALUE, "nickname": NICKNAME_VALUE,"picture": PICTURE_VALUE }" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/USER_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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/USER_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 => "{ "given_name": GIVEN_NAME_VALUE, "family_name": FAMILY_NAME_VALUE,"name": NAME_VALUE, "nickname": NICKNAME_VALUE,"picture": PICTURE_VALUE }",
    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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "given_name": GIVEN_NAME_VALUE, "family_name": FAMILY_NAME_VALUE,"name": NAME_VALUE, "nickname": NICKNAME_VALUE,"picture": PICTURE_VALUE }"

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

  conn.request("PATCH", "/{yourDomain}/api/v2/users/USER_ID", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/USER_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 = "{ "given_name": GIVEN_NAME_VALUE, "family_name": FAMILY_NAME_VALUE,"name": NAME_VALUE, "nickname": NICKNAME_VALUE,"picture": PICTURE_VALUE }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]

  let postData = NSData(data: "{ "given_name": GIVEN_NAME_VALUE, "family_name": FAMILY_NAME_VALUE,"name": NAME_VALUE, "nickname": NICKNAME_VALUE,"picture": PICTURE_VALUE }".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/USER_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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th><strong>Value</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>USER\_ID</code></td>
      <td>Τhe ID of the user to be updated.</td>
    </tr>

    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td><a href="https://auth0.com/docs/api/management/v2/tokens">Access Token for the Management API</a> with the <Tooltip href="/docs/glossary?term=scope">scope</Tooltip> <code>update:users</code>.</td>
    </tr>

    <tr>
      <td><code>GIVEN\_NAME\_VALUE</code></td>
      <td>Given name of the user to be updated.</td>
    </tr>

    <tr>
      <td><code>FAMILY\_NAME\_VALUE</code></td>
      <td>Family name of the user to be updated.</td>
    </tr>

    <tr>
      <td><code>NAME\_VALUE</code></td>
      <td>Full name of the user to be updated.</td>
    </tr>

    <tr>
      <td><code>NICKNAME\_VALUE</code></td>
      <td>Nickname of the user to be updated.</td>
    </tr>

    <tr>
      <td><code>PICTURE\_VALUE</code></td>
      <td>URL of the picture for the user to be updated.</td>
    </tr>
  </tbody>
</table>

## Removing attributes

Setting any value to `null` will remove the attribute for the user.

## Learn more

* [User Profile Structure](/docs/manage-users/user-accounts/user-profiles/user-profile-structure)
* [Set Root Attributes During User Import](/docs/manage-users/user-accounts/user-profiles/root-attributes/set-root-attributes-during-user-import)
* [Set Root Attributes During User Signup](/docs/manage-users/user-accounts/user-profiles/root-attributes/set-root-attributes-during-user-sign-up)


# Sample User Profiles
Source: https://auth0.com/docs/manage-users/user-accounts/user-profiles/sample-user-profiles

Examples of user profiles.

## Google User Profile

This is a sample user profile from a user that logged in through **Google**:

```json lines theme={null}
{
  "email": "johnfoo@gmail.com",
  "email_verified": true,
  "family_name": "Foo",
  "gender": "male",
  "given_name": "John",
  "identities": [
    {
      "provider": "google-oauth2",
      "user_id": "103547991597142817347",
      "connection": "google-oauth2",
      "isSocial": true
    }
  ],
  "locale": "en",
  "name": "John Foo",
  "nickname": "FooJon",
  "picture": "https://lh4.googleusercontent.com/-OdsbOXom9qE/AAAAAAAAAAI/AAAAAAAAADU/_j8SzYTOJ4I/photo.jpg",
  "user_id": "google-oauth2|103547991597142817347"
}
```

## Microsoft Account User Profile

This is a sample profile from **Microsoft Account**:

```json lines theme={null}
{
  "email": "bobdoe@outlook.com",
  "email_verified": true,
  "emails": [
    "bobdoe@outlook.com",
    "bobdoe@outlook.com"
  ],
  "family_name": "Doe",
  "given_name": "Bob",
  "identities": [
    {
      "provider": "windowslive",
      "user_id": "4cf0a30169d55031",
      "connection": "windowslive",
      "isSocial": true
    }
  ],
  "locale": "en_US",
  "name": "Bob Doe",
  "nickname": "doebob@outlook.com",
  "picture": "https://secure.gravatar.com/avatar/c89b2bb92df91508e14172097a5e17da?s=480&r=pg&d=https%3A%2F%2Fssl.gstatic.com%2Fs2%2Fprofiles%2Fimages%2Fsilhouette80.png",
  "user_id": "windowslive|4cf0a30169d55031"
}
```

## Office 365 User Profile

This is a sample profile from **Office 365 (Microsoft Azure Active Directory)**:

```json lines theme={null}
{
  "email": "jeff@foo.onmicrosoft.com",
  "family_name": "Jeff",
  "given_name": "Beth",
  "identities": [
    {
      "user_id": "10030000838D23AF@MicrosoftOnline.com",
      "provider": "office365",
      "connection": "foo-onmicrosoft",
      "isSocial": false
    }
  ],
  "name": "Jeff Beth",
  "nickname": "jeff@auth0.onmicrosoft.com",
  "picture": "https://secure.gravatar.com/avatar/a7f86ddd090d5a4cb833b97baab2aca1?s=480&r=pg&d=https%3A%2F%2Fssl.gstatic.com%2Fs2%2Fprofiles%2Fimages%2Fsilhouette80.png",
  "tenantid": "75696069-df44-4310-9bcf-08b45e3007c9",
  "upn": "jeff@foo.onmicrosoft.com",
  "user_id": "office365|10030000838D23AF@MicrosoftOnline.com"
}
```

## ADFS User Profile

This is a sample profile from **ADFS (Active Directory Federation Services)**:

```json lines theme={null}
{
  "email": "john@fabrikam.com",
  "family_name": "Fabrikam",
  "email_verified": false,
  "given_name": "John",
  "identities": [
    {
      "user_id": "john@fabrikam.com",
      "provider": "adfs",
      "connection": "auth10.com",
      "isSocial": false
    }
  ],
  "issuer": "https://adfs.fabrikam.com",
  "name": "John Fabrikam",
  "nickname": "john",
  "picture": "https://secure.gravatar.com/avatar/5426f6b9d63ad92d60e6fe9fdf83aa21?s=480&r=pg&d=https%3A%2F%2Fssl.gstatic.com%2Fs2%2Fprofiles%2Fimages%2Fsilhouette80.png",
  "user_id": "adfs|john@fabrikam.com"
}
```


# Update User Profiles Using Your Database
Source: https://auth0.com/docs/manage-users/user-accounts/user-profiles/update-user-profiles-using-your-database

Learn how to update user profiles when using your own database as an identity provider.

Update user profiles when [using your own database as an identity provider](/docs/authenticate/database-connections/custom-db) by doing the following tasks:

* Use the [Management API](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id).
* Update the user in your database.
* [Configure user migration](/docs/manage-users/user-migration/configure-automatic-migration-from-your-database) from your database to Auth0.

## Update users with the Management API

When using your own database for authentication, you can use the [Management API](https://auth0.com/docs/api/management/v2) to update the following fields:

* `app_metadata`
* `user_metadata`
* `blocked`

If you need to update other user fields, you will need to do it directly in your database.

## Update users in your database

You can update user profiles in your database as you normally do, and Auth0 will update its cached user profile the next time that user logs in.

The user profile in the custom database can be implemented with any user profile structure, but you need to map it in the Login call to the Auth0 normalized user profile attributes as shown in the "Login" custom database template.

Access the custom database templates are accessed via
Connections -> Database -> Custom Database. Be sure to turn on the "Use my own database" toggle to enable editing the scripts.

See the [User profile cache](#user-profile-cache) section below for a brief overview of how Auth0 caches user profiles.

## Update users through migration

If you have [enabled user migration](/docs/manage-users/user-migration/configure-automatic-migration-from-your-database), and a user has already been migrated to the Auth0 database, then Auth0 will not query your database again for the user profile. Therefore, all changes made in the custom database for that user will never reflect in Auth0.

Once a user has been migrated, you will also be able to update fields, such as `name`, `nickname`, `given_name`, `family_name`, `picture`, `email`, and `email_verified` via the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

However, rules for updating other user fields will still apply as described in the [Normalized User Profile](/docs/manage-users/user-accounts/user-profiles/normalized-user-profiles).

## User profile cache

Auth0 caches the user profile received from a [database connection](/docs/authenticate/database-connections) before sending it to the client application. This cache is stored in the Auth0 database and is refreshed each time the user authenticates.

The cached values for the [Normalized User Profile](/docs/manage-users/user-accounts/user-profiles/normalized-user-profile-schema) fields are based on the values returned from the Login Script of your custom database connection.

The User Profile is cached for several reasons. First, caching allows you the option of implementing [Single Sign-on (SSO)](/docs/authenticate/single-sign-on) at the Auth0 layer to avoid going to the connection for every request. Additionally, this provides resilience if a connection is temporarily unavailable.

## Learn more

* [Check API Calls](/docs/troubleshoot/authentication-issues/check-api-calls)
* [Check User Profiles](/docs/troubleshoot/authentication-issues/check-user-profiles)


# User Profile Structure
Source: https://auth0.com/docs/manage-users/user-accounts/user-profiles/user-profile-structure

Lists the attributes that are available on the Auth0 user profile

Auth0's normalized user profile consists of a few different components:

* **Details**: Core User Profile object, which contains basic info, such as name, email, and timestamp of the user's latest login, in pre-defined attributes. This object may also contain info from a user's source connection. Most of the user attributes are root attributes (attributes stored at the first, or root, level of the `user` object), and some of these are editable.
* **Metadata**: Two sub-objects that operate as secondary storage to store additional user info in customizable attributes: `user_metadata` and `app_metadata`. To learn more, including when to use `app_metadata` and `user_metadata`, read [Understand How Metadata Works in User Profiles](/docs/manage-users/user-accounts/metadata).

## User profile attributes

The following attributes are available on the user profile. Many are root attributes (attributes stored at the first, or root, level of the `user` object), and some may be updated, imported, and exported, as noted below.

If there are user fields that should not be stored by Auth0 due to privacy reasons, you can add the attributes you do not want persisting in Auth0 databases to the DenyList. To learn more, read [Add User Attributes to the Deny List](/docs/secure/security-guidance/data-security/denylist).

By default, user profile attributes provided by <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> other than Auth0 (such as Google, Facebook, or X) are not directly editable because they are updated from the identity provider each time the user logs in. Fore more information on attributes from identity providers, read [Configure Identity Provider Connection for User Profile Updates](/docs/manage-users/user-accounts/user-profiles/configure-connection-sync-with-auth0).

To be able to edit the `name`, `nickname`, `given_name`, `family_name`, or `picture` root attributes on the normalized user profile, you must [configure your connection sync with Auth0](/docs/manage-users/user-accounts/user-profiles/configure-connection-sync-with-auth0) so that user attributes will be updated from the identity provider only on user profile creation. These root attributes will then be available to be edited individually or by bulk imports

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Type</th>
      <th>Description</th>
      <th><a href="/docs/manage-users/user-search">Search?</a></th>
      <th><a href="https://auth0.com/docs/api/management/guides/users/update-root-attributes-users">Update?</a></th>
      <th><a href="/docs/manage-users/user-migration/bulk-user-imports">Import?</a></th>
      <th><a href="/docs/manage-users/user-migration/bulk-user-imports#request-bulk-import">Upsert during import?</a></th>
      <th><a href="/docs/manage-users/user-migration/bulk-user-exports">Export?</a></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>app\_metadata</code></td>
      <td>object</td>
      <td>Custom fields that store info about a user that influences the user's access, such as support plan, security roles (if not using the Authorization Core feature set), or access control groups. To learn more, read <a href="/docs/manage-users/user-accounts/metadata">Metadata Overview</a>.</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
    </tr>

    <tr>
      <td><code>blocked</code></td>
      <td>boolean</td>
      <td>Indicates whether the user has been blocked. Importing enables subscribers to ensure that users remain blocked when migrating to Auth0.</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
      <td>N</td>
      <td>Y</td>
    </tr>

    <tr>
      <td><code>blocked\_for</code></td>
      <td>array (object)</td>
      <td>IP addresses that have been blocked under suspicion of a bruteforce attack.</td>
      <td>N</td>
      <td>N</td>
      <td>N</td>
      <td>N</td>
      <td>N</td>
    </tr>

    <tr>
      <td><code>created\_at</code></td>
      <td>date time</td>
      <td>Timestamp indicating when the user profile was first created.</td>
      <td>Y</td>
      <td>N</td>
      <td>N</td>
      <td>N</td>
      <td>Y</td>
    </tr>

    <tr>
      <td><code>email</code></td>
      <td>text</td>
      <td>(unique) The user's email address.</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
      <td>N</td>
      <td>Y</td>
    </tr>

    <tr>
      <td><code>email\_verified</code></td>
      <td>boolean</td>
      <td>Indicates whether the user has verified their email address.</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
    </tr>

    <tr>
      <td><code>family\_name</code></td>
      <td>text</td>
      <td>The user's family name.</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
    </tr>

    <tr>
      <td><code>given\_name</code></td>
      <td>text</td>
      <td>The user's given name.</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
    </tr>

    <tr>
      <td><code>guardian\_authenticators</code></td>
      <td>array (object)</td>
      <td>Detailed information about the guardian backup authorization methods the user has set up, including SMS and Recovery Codes.</td>
      <td>N</td>
      <td>N</td>
      <td>N</td>
      <td>N</td>
      <td>N</td>
    </tr>

    <tr>
      <td><code>identities</code></td>
      <td>array (object)</td>
      <td><p>Contains info retrieved from the identity provider with which the user originally authenticates. Users may also <a href="/docs/manage-users/user-accounts/user-account-linking">link their profile to multiple identity providers</a>; those identities will then also appear in this array. The contents of an individual identity provider object varies by provider, but it will typically include the following:</p><ul><li><code>connection</code> (text): Name of the Auth0 connection used to authenticate the user.</li><li><code>isSocial</code> (boolean): Indicates whether the connection is a social one.</li><li><code>provider</code> (text): Name of the entity that is authenticating the user, such as Facebook, Google, SAML, or your own provider.</li><li><code>user\_id</code> (text): User's unique identifier for this connection/provider.</li><li><code>profileData</code> (object): User info associated with the connection. When profiles are linked, it is populated with the associated user info for secondary accounts.</li></ul>In some cases, it will also include an API Access Token to be used with the provider.</td>
      <td>Y</td>
      <td>N</td>
      <td>N</td>
      <td>N</td>
      <td>Y</td>
    </tr>

    <tr>
      <td><code>last\_ip</code></td>
      <td>text</td>
      <td>IP address associated with the user's last login.</td>
      <td>Y</td>
      <td>N</td>
      <td>N</td>
      <td>N</td>
      <td>Y</td>
    </tr>

    <tr>
      <td><code>last\_login</code></td>
      <td>date time</td>
      <td>Timestamp indicating when the user last logged in. If a user is blocked and logs in, the blocked session updates <code>last\_login</code>. If you are using this property from inside a <a href="/docs/customize/rules">Rule</a> using the <code>user\<</code> object, its value will be associated with the login that triggered the rule; this is because rules execute after login.</td>
      <td>Y</td>
      <td>N</td>
      <td>N</td>
      <td>N</td>
      <td>Y</td>
    </tr>

    <tr>
      <td><code>last\_password\_reset</code></td>
      <td>date time</td>
      <td>Timestamp indicating the last time the user's password was reset/changed. At user creation, this field does not exist. This property is only available for Database connections.</td>
      <td>N</td>
      <td>N</td>
      <td>N</td>
      <td>N</td>
      <td>Y</td>
    </tr>

    <tr>
      <td><code>logins\_count</code></td>
      <td>integer</td>
      <td>Number of times the user has logged in. If a user is blocked and logs in, the blocked session is counted in <code>logins\_count</code>.</td>
      <td>Y</td>
      <td>N</td>
      <td>N</td>
      <td>N</td>
      <td>Y</td>
    </tr>

    <tr>
      <td><code>multifactor</code></td>
      <td>array (string)</td>
      <td>List of multi-factor providers with which the user is enrolled.</td>
      <td>N</td>
      <td>N</td>
      <td>N</td>
      <td>N</td>
      <td>Y</td>
    </tr>

    <tr>
      <td><code>multifactor\_last\_modified</code></td>
      <td>date time</td>
      <td>Date and time of the last update to a user's multifactor authentication.</td>
      <td>N</td>
      <td>N</td>
      <td>N</td>
      <td>N</td>
      <td>Y</td>
    </tr>

    <tr>
      <td><code>name</code></td>
      <td>text</td>
      <td>The user's full name.</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
    </tr>

    <tr>
      <td><code>nickname</code></td>
      <td>text</td>
      <td>The user's nickname.</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
    </tr>

    <tr>
      <td><code>phone\_number</code></td>
      <td>text</td>
      <td>The user's phone number. Only valid for users with SMS connections.</td>
      <td>Y</td>
      <td>Y</td>
      <td>N</td>
      <td>N</td>
      <td>Y</td>
    </tr>

    <tr>
      <td><code>phone\_verified</code></td>
      <td>boolean</td>
      <td>Indicates whether the user has been verified their phone number. Only valid for users with SMS connections.</td>
      <td>Y</td>
      <td>Y</td>
      <td>N</td>
      <td>N</td>
      <td>Y</td>
    </tr>

    <tr>
      <td><code>picture</code></td>
      <td>text</td>
      <td>URL pointing to <a href="/docs/manage-users/user-accounts/change-user-picture">the user's profile picture</a>.</td>
      <td>N</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
    </tr>

    <tr>
      <td><code>tenant</code></td>
      <td>text</td>
      <td>Name of the tenant being used.</td>
      <td>N</td>
      <td>N</td>
      <td>N</td>
      <td>N</td>
      <td>N</td>
    </tr>

    <tr>
      <td><code>updated\_at</code></td>
      <td>date time</td>
      <td>Timestamp indicating when the user's profile was last updated/modified. Changes to <code>last\_login</code> are considered updates, so most of the time, <code>updated\_at</code> will match <code>last\_login</code>.</td>
      <td>Y</td>
      <td>N</td>
      <td>N</td>
      <td>N</td>
      <td>Y</td>
    </tr>

    <tr>
      <td><code>user\_id</code></td>
      <td>text</td>
      <td>(unique) The user's identifier. Importing allows user records to be synchronized across multiple systems without using mapping tables.</td>
      <td>Y</td>
      <td>N</td>
      <td>Y</td>
      <td>N</td>
      <td>Y</td>
    </tr>

    <tr>
      <td><code>user\_metadata</code></td>
      <td>object</td>
      <td>Custom fields that store info about a user that does not impact what they can or cannot access, such as work address, home address, or user preferences. To learn more, read <a href="/docs/manage-users/user-accounts/metadata">Metadata Overview</a>.</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
    </tr>

    <tr>
      <td><code>username</code></td>
      <td>text</td>
      <td>(unique) The user's username.</td>
      <td>Y</td>
      <td>Y</td>
      <td>Y</td>
      <td>N</td>
      <td>Y</td>
    </tr>
  </tbody>
</table>

### User profile validation

Auth0 accepts a specific validation schema for certain fields in the user profile. See the table below for a list of requirements when setting profile attribute values.

<Callout icon="file-lines">
  All characters are converted to lowercase when saved to the User Profile.

  This is true for all Auth0 database connections. When Auth0 DB is not the source of truth (for example, custom DB with import mode off) as well as other kinds of social enterprise connections where Auth0 is not the source of truth, the email is retained as-is and not converted to lower case.
</Callout>

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Character Limit</th>
      <th>Validation</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>email</code></td>
      <td>email</td>
      <td>The maximum length is 64 characters for the user/local part and 256 characters for the domain part.</td>

      <td>
        <a href="https://json-schema.org/understanding-json-schema/reference/string#email-addresses">JSON validation schema</a>.

        <br />

        <p>Regex: </p>

        <br />
      </td>
    </tr>

    <tr>
      <td><code>username</code></td>
      <td>string</td>
      <td>The default allowed length for usernames is between 1 and 15 characters. Up to a maximum length of 128 characters.</td>
      <td>The username field accepts the following characters:<br /> Alphanumeric characters (without accent marks, automatically converted to lowercase);<br /> The at sign (@) character (but email addresses are not allowed);<br /> The caret (^) character;<br /> The dollar sign (\$) character;<br /> The dot (.) character;<br /> The exclamation (!) character;<br /> The grave accent (\`) character;<br /> The minus (-) character;<br /> The number sign (#) character;<br /> The plus (+) character;<br /> The single quote (') character;<br /> The tilde (\~) character;<br /> The underscore (\_) character;<br /> No other characters/symbols are allowed, and Auth0 does not validate or sanitize custom database inputs.</td>
    </tr>

    <tr>
      <td><code>phone\_number</code></td>
      <td>phone</td>
      <td>Standardized Format <br /> Phone numbers need to be in E.164 format</td>

      <td>
        <br />
      </td>
    </tr>

    <tr>
      <td><code>password</code></td>
      <td>string</td>
      <td>The minimum password length you can set is 1 byte, while the maximum is 72 bytes.</td>
      <td>Standard Characters: ASCII characters in the range of 33-126 are valid, including:<br /> A through Z uppercase characters, <br /> a through z lower case characters, <br /> 0 through 9 numeric characters, <br /> special characters allowed. <br /></td>
    </tr>

    <tr>
      <td><code>name</code></td>
      <td>string</td>
      <td>1-150 characters</td>
      <td>All UTF-8 characters are supported</td>
    </tr>

    <tr>
      <td><code>nickname</code></td>
      <td>string</td>
      <td>1-350 characters</td>
      <td>All UTF-8 characters are supported</td>
    </tr>

    <tr>
      <td><code>family\_name</code></td>
      <td>string</td>
      <td>1-150 characters</td>
      <td>All UTF-8 characters are supported</td>
    </tr>

    <tr>
      <td><code>given\_name</code></td>
      <td>string</td>
      <td>1-150 characters</td>
      <td>All UTF-8 characters are supported</td>
    </tr>
  </tbody>
</table>

Three other fields are not technically part of the user profile, but may be of interest when importing users:

* `password_hash` (text): Hashed password for the user's connection. When users are created, Auth0 uses [bcrypt](https://auth0.com/blog/hashing-in-action-understanding-bcrypt/) to secure the password. Importing compatible hashed passwords allows users to retain their passwords, thereby providing a smoother experience. Compatible passwords should be hashed using bcrypt  or  and have 10 saltRounds. Note that you can provide this field only when the user is first imported; you cannot update it later.
* `custom_password_hash` (object): Hashed password for the user's connection when created using an alternate algorithm. Used in place of the `password_hash` field. During the bulk import process, you can update the `custom_password_hash` if the user did not login using the initially imported `custom_password_hash.`

## Learn more

* [Bulk User Imports](/docs/manage-users/user-migration/bulk-user-imports)
* [Bulk User Import Database Schema and Examples](/docs/manage-users/user-migration/bulk-user-import-database-schema-and-examples)
* [Check User Profiles](/docs/troubleshoot/authentication-issues/check-user-profiles)


# Use Verified Email in User Profiles
Source: https://auth0.com/docs/manage-users/user-accounts/user-profiles/verified-email-usage

Outlines proper usage of the email_verified field in a user profile.

The `email_verified` field of a user profile indicates whether the user has verified their email address. Email verification is optional, but valid email addresses are required for certain actions, such as sending email communications, password reset/recovery links, and <Tooltip href="/docs/glossary?term=passwordless">passwordless</Tooltip> magic links to users.

An email is usually verified immediately after the user account is created or when the user logs in to the application for the first time. It's a good way to know that the person signing up actually owns the email at that moment.

Since email verification happens once at that specific moment, we can't ensure that a person who logs in with the user account at a later time still owns the email address that was verified.

In case of federated <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip>, they sometimes report if the user has a verified email, and based on that, Auth0 sets the `email_verified` field in the user profile. This, however, transfers the responsibility to the identity provider to do it properly - something we can't ensure. We also don't know if the verified email from that provider is still owned by the user.

For all of these reasons, we need to be careful on what we can assume based on a verified email.

## When does Auth0 set emails as verified?

When users signup with email and password, they get a verification email with a link. When they click the link, Auth0 verifies their email. To learn more, read [Customize Email Templates](/docs/customize/email/email-templates).

When users authenticate with a federated identity provider (e.g. a social or enterprise connection), the value of the `email_verified` field will match what the identity provider returns in the user profile. If they identity provider does not return any value, it will be set to `false`.

## Verified Emails and Account Linking

When you want to [link two user accounts](/docs/manage-users/user-accounts/user-account-linking), you need to make sure that the user still has access to both accounts. The only way to achieve that is to have users authenticate with both accounts before linking them.

You **should not automatically link accounts based on the user's emails**. Always prompt users to authenticate again before doing that. This will prevent scenarios like:

* John Doe, an employee of Travel0, signs up to a site using his corporate email `john.doe@travel0.com` and a password. Months later, John Doe leaves Travel0, and a new John Doe is hired, with the same email account. That person goes to the same website, and authenticates with his corporate identity provider (such as Google Workspace), and gets the account automatically linked to the other user.
* Federated identity providers can make mistakes on how they handle email verification and can report that users own an email they do not.

On the other hand, we recommend you to still check for the `email_verified` field before performing account linking, to mitigate scenarios like:

* An attacker creates a Google account `attacker@gmail.com`.
* Attacker creates a new database users with the victim's email (e.g. `victim@hotmail.com`).
* Attacker links both accounts.
* Attacker sends a phishing attack to victim.
* The victim tries to sign-up, they are told the user already exists and get offered to reset the password.
* The user enters their password and logs into the attacker's account, which now has access to whatever data the victim enters in the application.

## Verified Emails and Authorization Decisions

In the same way that you can't fully trust the email, you can't fully trust the email domain either.

If your application needs to restrict access based on the user's employer, the fact that a user is logged in with an email from a specific corporate domain does not guarantee that it should be granted access.

For example:

* If your application allows customers to sign up for new accounts, and employees from different companies authenticate using their corporate credentials, a user that signs up with a `user@acme.com` account shouldn't be granted access to the same feature set that a user authenticating with acme.com's corporate directory.
* If your application supports authenticating with Azure AD, and the directory supports guest users, you can get users from any domain logging-in from that Azure AD tenant. You should not give guest users the same access level as the rest of the users authenticating with that tenant.

As a general recommendation, **you should not use the email's domain to make authorization decisions**. If you need to check if the user belongs to a specific organization, it's better to rely on the connection they used to authenticate, or in connection-specific attributes like the Azure AD's tenant id.

## Learn more

* [Link User Accounts](/docs/manage-users/user-accounts/user-account-linking/link-user-accounts)
* [User-Initiated Account Linking: Client-Side Implementation](/docs/manage-users/user-accounts/user-account-linking/user-initiated-account-linking-client-side-implementation)
* [User Account Linking: Server-Side Implementation](/docs/manage-users/user-accounts/user-account-linking/suggested-account-linking-server-side-implementation)


# Verify Emails using Auth0
Source: https://auth0.com/docs/manage-users/user-accounts/verify-emails

Overview of the different ways to verify user emails using Auth0

When using an email address supplied by a user, it is important to verify the user has access to that email. This is true anytime you send an email to a user or if you use email as an index for search. Auth0 does not recommend using an email address as a way to validate that a user is who they say they are.

Email verification is crucial for applications that:

* Use email addresses as one of the primary ways to index users
* Send out emails to users
* Use email addresses to recommend account linking
* Let users create accounts connected to an email address

Auth0 provides several ways to add email verification to your application, as well as [a Marketplace extension](https://marketplace.auth0.com/integrations/auth-0-require-email-verification) that requires users to verify their emails before signing in.

<Warning>
  While email verification lowers the risk of accounts being compromised, it is not a perfect solution. Your application may also need other security measures.
</Warning>

## Choose the right approach

There are several ways to mark emails as verified or unverified. To figure out which method is right for you, here are a few questions to ask yourself or your team:

* Am I storing (or planning to store) identifiers and passwords in Auth0 (or in a database connected through Auth0)?
* Do I have special email verification requirements that prevent me from using Auth0's built in verify email flow?
* Do I need to bulk set a large number of users to email verified?
* Do I have users coming from Azure AD, ADFS, or other enterprise connections that will need their emails verified?

If you are storing identifiers and passwords in Auth0 or using a custom DB connection to store users in your own system then you can likely use Auth0's [built-in email verification flow](#magic-link-in-a-verification-email).

If you have requirements preventing you from using Auth0's built in flow or you need to bulk set a large number of users, we have [API endpoints](#custom-or-bulk-verification-with-the-management-api) to help.

Lastly, if you have users from enterprise connections, some of those connections have special email verification workflows. To learn more, read [Special Verification Support](#special-verification-support).

## Email verification links

A common way to verify emails with Auth0 is to send an email verification link to the user. When the user clicks the link, the user's `email_verified` flag is set to `true`.

**By default, Auth0 emails verification links to users when they sign up.**

You can also customize when Auth0 sends verification emails. For example, if you need to verify emails in bulk or if you want to delay verification until the user performs an action requiring a verified email.

There are two ways to control when the user gets the verification email :

* Use the [email verification job](https://auth0.com/docs/api/management/v2#!/Jobs/post_verification_email). This triggers Auth0 to send the verification email using the verify email template
* Create an [email verification ticket](https://auth0.com/docs/api/management/v2#!/Tickets/post_email_verification) and send the email yourself, including the ticket the user should use to verify their email

## One-time passwords

One-time passwords (OTPs) can be emailed to each new user at the time of account creation to ensure every user has an verified email. Because email verification links can lead to accidental verification by email scanners or the users themselves, OTPs ensures each user actively verifies an existing email address. To use OTPs, your tenant must have [Universal Login](/docs/authenticate/login/auth0-universal-login), [Flexible Identifiers](/docs/authenticate/database-connections/flexible-identifiers-and-attributes), and [Identifer-First login](/docs/authenticate/login/auth0-universal-login/identifier-first) enabled.

<Callout icon="file-lines">
  OTP tokens for phone and email identifier verification have a lifetime of 900 seconds.
</Callout>

To set up OTPs, go to [**Authentication > Database**](https://manage.auth0.com/#/authentication) and select the connection to change, then pick **Attributes**, locate **Email,** choose the menu button,and enable **One-Time Password (OTP)**.

<Frame>
  <img alt="" />
</Frame>

## Custom or bulk verification with the Management API

<Warning>
  This works for social and database connections but does not work for enterprise connections. Keep in mind, the `email_verified` field may be overwritten by the social identity provider if the data comes from them.
</Warning>

In some cases you may want to verify email through other means. For example, you have a list of users to verify in bulk or you have some other means for verifying a user's email through a custom workflow you've built yourself.

In these cases you can use the [PATCH `/api/v2/users` endpoint](https://auth0.com/docs/api/management/v2/#!/Users/patch_users_by_id) to set `email_verified` to `true`.

## Special verification support

For Azure AD and ADFS enterprise connections, Auth0 supports some custom email verification workflows. This can help you ensure users coming from other systems have verified emails in an accurate and secure way. To learn more, read [Email Verification for Azure AD and ADFS](/docs/authenticate/identity-providers/enterprise-identity-providers/azuread-adfs-email-verification).

## Learn more

* [Check API Calls](/docs/troubleshoot/authentication-issues/check-api-calls)
* [Check User Profiles](/docs/troubleshoot/authentication-issues/check-user-profiles)


# View User Details
Source: https://auth0.com/docs/manage-users/user-accounts/view-user-details

How to view users and their profile details.

The [Users](https://manage.auth0.com/#/users) page lists the users who are associated with your apps. To open a particular user, click the user profile picture or name in the "Name" column. The User Details page will open and display information for that user.

The User Details page has links for five tabs:

1. Details
2. Devices
3. History
4. Locations
5. Raw JSON

## User Details: Details Tab

The Details tab contains three sections that provide a high-level overview of the information in the user's profile:

* **User Identity** provides at-a-glance details about the user, including the identifier they used, associated Connections, and access rights.
* **Metadata** displays the `app_metadata` and `user_metadata` information. You can edit these values.
* **<Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> Attributes** displays the information retrieved from the authentication provider. Note that identity provider attributes are read-only.
* **Passkeys** displays the [passkeys](/docs/authenticate/database-connections/passkeys) created by the user.
* **<Tooltip href="/docs/glossary?term=Multi-Factor+Authentication">Multi-Factor Authentication</Tooltip>** displays the user's enrolled [MFA](/docs/secure/multi-factor-authentication) factors.
  If you enable [Multiple Custom Domains](/docs/customize/custom-domains/multiple-custom-domains), you have the **Domain** option to select the notification domain for your tenant.

## User Details: Devices Tab

The Devices tab lists the devices with which the user has requested authentication. Requesting authorization on a device links the device to the user's account.

Login details for the user are associated with the <Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip> assigned to that device. To revoke the Refresh Token, click **Unlink** next to the device.

## User Details: History Tab

The History tab displays a log of the user's account activity for the past 2 days.

The logs include information about:

* Events that have occurred
* When the events occurred
* The apps associated with the events
* The identity provider used for authentication
* The originating IP addresses for the events
* Where the events originated

## User Details: Locations Tab

The Locations tab displays a map with pins indicating the user's location(s) when they logged in to the apps.

## User Details: Raw JSON Tab

The Raw JSON tab displays all of the information contained on the user's profile in JSON format so you can quickly view all of the available information about the user.


# Import and Export Users
Source: https://auth0.com/docs/manage-users/user-migration

Overview of importing users from external applications into Auth0.

<Warning>
  The **User Import/Export Extension** will be deprecated in September 2025. You can access the same features now available [directly in the Auth0 Management Dashboard](/docs/manage-users/user-migration/bulk-user-import-export).
</Warning>

Auth0 supports importing users from external applications using custom database connections, the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>, or the User Import/Export Extension.

## Automatic migrations

Auth0 supports automatic migration of users from a [custom database connection](/docs/authenticate/database-connections/custom-db) to Auth0. This practice is sometimes known as **trickle migration** or **lazy migration**. By activating this feature, your users are:

* Moved to Auth0 the first time they log in after you set up the integration.
* Not asked to reset their password as a result of the migration.

<Card title="Availability varies by Auth0 plan">
  Both your specific login implementation and your Auth0 plan or custom agreement affect whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

When a user authenticates via a custom database connection marked for import to Auth0, the following process takes place:

* Auth0 authenticates migrated users against the Auth0 database.
* If the user has not been migrated, Auth0 executes your custom login script and, upon successfully log in, adds the user to the Auth0 database.
* Subsequent logins result in the user's credentials retrieved from Auth0, **NOT** your custom database.
* New users are automatically added to the Auth0 database.

<Frame>
  <img alt="User Migration Diagram" />
</Frame>

## Bulk user imports with the Management API

If you already have a user database, you can use our [`/post_users_imports`](https://auth0.com/docs/api/management/v2#!/Jobs/post_users_imports) Management API endpoint to populate a database connection with this information.

## Migrate users with the User Import/Export feature

The User Import/Export feature allows you to:

* Bulk import your existing database users into Auth0.
* Search for and export some (or all) of your Auth0 database users.

To use bulk import, you must be Dashboard Editor - Users or an Admin. To use bulk export, you must be Dashboard Viewer - Users, Editor - Users, or an Admin.

You can import and export user data using the [User Import/Export feature](/docs/manage-users/user-migration/bulk-user-import-export) available on the dashboard.

## Learn more

* [Configure Automatic Migration from Your Database](/docs/manage-users/user-migration/configure-automatic-migration-from-your-database)
* [Bulk User Imports](/docs/manage-users/user-migration/bulk-user-imports)
* [User Import / Export Extension](/docs/manage-users/user-migration/user-import-export-extension)


# Bulk User Exports
Source: https://auth0.com/docs/manage-users/user-migration/bulk-user-exports

Learn how to export lists of users and user metadata.

You can use the `POST /api/v2/jobs/users-exports` endpoint to create a job that exports all users associated with a [connection](/docs/authenticate/identity-providers), or all users in the tenant.

For a list of user profile fields that can be exported, read [User Profile Structure](/docs/manage-users/user-accounts/user-profiles/user-profile-structure).

When you create your job, you'll need to provide:

* [ID for the connection](/docs/authenticate/identity-providers/locate-the-connection-id) from which you want to export users (optional)
* Format of the export file (CSV or JSON-compatible)
* Maximum number of user records to be exported (optional, will export all records if omitted)
* User-related fields (such as user ID or name) that you want included in the export

You'll also need a valid [Management API Access Token](https://auth0.com/docs/api/management/v2/tokens).

## Create a request body

Optionally, find the `connection_id` and your Auth0 tenant domain name in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. Create a new text file with the request body below:

```json lines theme={null}
{
   "connection_id":"connection_id",
   "format":"csv",
   "limit":20,
   "fields":[
      {
         "name":"user_id"
      },
      {
         "name":"email"
      },
      {
         "name":"user_metadata.country"
      }
   ]
}
```

Update the `connection_id` with your database connection ID, or remove it to export all users in the tenant.

## Request example

Required Scopes: `read:users`

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/jobs/users-exports' \
    --header 'authorization: Bearer {yourMgmtAPIAccessToken}' \
    --header 'content-type: application/json' \
    --data '{"connection_id": "{yourConnectionId}", "format": "csv", "limit": 5, "fields": [{"name": "email"}, { "name": "identities[0].connection", "export_as": "provider" }]}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/jobs/users-exports");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer {yourMgmtAPIAccessToken}");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"connection_id": "{yourConnectionId}", "format": "csv", "limit": 5, "fields": [{"name": "email"}, { "name": "identities[0].connection", "export_as": "provider" }]}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/jobs/users-exports"

  	payload := strings.NewReader("{"connection_id": "{yourConnectionId}", "format": "csv", "limit": 5, "fields": [{"name": "email"}, { "name": "identities[0].connection", "export_as": "provider" }]}")

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

  	req.Header.Add("authorization", "Bearer {yourMgmtAPIAccessToken}")
  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/jobs/users-exports")
    .header("authorization", "Bearer {yourMgmtAPIAccessToken}")
    .header("content-type", "application/json")
    .body("{"connection_id": "{yourConnectionId}", "format": "csv", "limit": 5, "fields": [{"name": "email"}, { "name": "identities[0].connection", "export_as": "provider" }]}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/jobs/users-exports',
    headers: {
      authorization: 'Bearer {yourMgmtAPIAccessToken}',
      'content-type': 'application/json'
    },
    data: {
      connection_id: '{yourConnectionId}',
      format: 'csv',
      limit: 5,
      fields: [{name: 'email'}, {name: 'identities[0].connection', export_as: 'provider'}]
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtAPIAccessToken}",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"connection_id": @"{yourConnectionId}",
                                @"format": @"csv",
                                @"limit": @5,
                                @"fields": @[ @{ @"name": @"email" }, @{ @"name": @"identities[0].connection", @"export_as": @"provider" } ] };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/jobs/users-exports"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/jobs/users-exports",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{"connection_id": "{yourConnectionId}", "format": "csv", "limit": 5, "fields": [{"name": "email"}, { "name": "identities[0].connection", "export_as": "provider" }]}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtAPIAccessToken}",
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"connection_id": "{yourConnectionId}", "format": "csv", "limit": 5, "fields": [{"name": "email"}, { "name": "identities[0].connection", "export_as": "provider" }]}"

  headers = {
      'authorization': "Bearer {yourMgmtAPIAccessToken}",
      'content-type': "application/json"
      }

  conn.request("POST", "/{yourDomain}/api/v2/jobs/users-exports", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/jobs/users-exports")

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

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer {yourMgmtAPIAccessToken}'
  request["content-type"] = 'application/json'
  request.body = "{"connection_id": "{yourConnectionId}", "format": "csv", "limit": 5, "fields": [{"name": "email"}, { "name": "identities[0].connection", "export_as": "provider" }]}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer {yourMgmtAPIAccessToken}",
    "content-type": "application/json"
  ]
  let parameters = [
    "connection_id": "{yourConnectionId}",
    "format": "csv",
    "limit": 5,
    "fields": [
      ["name": "email"],
      [
        "name": "identities[0].connection",
        "export_as": "provider"
      ]
    ]
  ] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/jobs/users-exports")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

The response should look something like this:

```json lines theme={null}
{
  "type": "users_export",
  "status": "pending",
  "connection_id": "con_0000000000000001",
  "format": "csv",
  "limit": 5,
  "fields": [
    {
      "name": "user_id"
    },
    {
      "name": "name"
    },
    {
      "name": "email"
    },
    {
      "name": "identities[0].connection",
      "export_as": "provider"
    }
  ],
  "connection": "Username-Password-Authentication",
  "created_at": "2017-11-02T23:34:03.803Z",
  "id": "job_coRQCC3MHztpuTlo"
}
```

## Include user metadata in exported CSV

If you export user data in CSV format and want to include metadata information, specify each metadata field that you want to export. You can export up to 30 fields.

<Warning>
  You cannot export the entirety of `app_metadata` or `user_metadata` in CSV. You must specify fields of metadata objects explicitly.

  To export `app_metadata` or `user_metadata` as single objects, use the JSON-compatible format and include the desired field in the `fields` parameter of the request body. For example:

  `{"name":"app_metadata"}`

  As you can only export up to 30 fields, using the JSON format is recommended if the user data has many fields.
</Warning>

For example, for metadata structured like this:

```json lines theme={null}
{
  "consent": {
      "given": true,
      "date": "01/23/2019",
      "text_details": "{yourURL}"
  }
}
```

The export request (for all three fields) would look like this:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/jobs/users-exports' \
    --header 'authorization: Bearer {yourMgmtAPIAccessToken}' \
    --header 'content-type: application/json' \
    --data '{"connection_id": "{yourConnectionId}", "format": "csv", "limit": 5, "fields": [{"name": "email"}, {"name": "user_metadata.consent.given"}, {"name": "user_metadata.consent.date"}, {"name": "user_metadata.consent.text_details"}]}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/jobs/users-exports");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer {yourMgmtAPIAccessToken}");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"connection_id": "{yourConnectionId}", "format": "csv", "limit": 5, "fields": [{"name": "email"}, {"name": "user_metadata.consent.given"}, {"name": "user_metadata.consent.date"}, {"name": "user_metadata.consent.text_details"}]}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/jobs/users-exports"

  	payload := strings.NewReader("{"connection_id": "{yourConnectionId}", "format": "csv", "limit": 5, "fields": [{"name": "email"}, {"name": "user_metadata.consent.given"}, {"name": "user_metadata.consent.date"}, {"name": "user_metadata.consent.text_details"}]}")

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

  	req.Header.Add("authorization", "Bearer {yourMgmtAPIAccessToken}")
  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/jobs/users-exports")
    .header("authorization", "Bearer {yourMgmtAPIAccessToken}")
    .header("content-type", "application/json")
    .body("{"connection_id": "{yourConnectionId}", "format": "csv", "limit": 5, "fields": [{"name": "email"}, {"name": "user_metadata.consent.given"}, {"name": "user_metadata.consent.date"}, {"name": "user_metadata.consent.text_details"}]}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/jobs/users-exports',
    headers: {
      authorization: 'Bearer {yourMgmtAPIAccessToken}',
      'content-type': 'application/json'
    },
    data: {
      connection_id: '{yourConnectionId}',
      format: 'csv',
      limit: 5,
      fields: [
        {name: 'email'},
        {name: 'user_metadata.consent.given'},
        {name: 'user_metadata.consent.date'},
        {name: 'user_metadata.consent.text_details'}
      ]
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtAPIAccessToken}",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"connection_id": @"{yourConnectionId}",
                                @"format": @"csv",
                                @"limit": @5,
                                @"fields": @[ @{ @"name": @"email" }, @{ @"name": @"user_metadata.consent.given" }, @{ @"name": @"user_metadata.consent.date" }, @{ @"name": @"user_metadata.consent.text_details" } ] };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/jobs/users-exports"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/jobs/users-exports",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{"connection_id": "{yourConnectionId}", "format": "csv", "limit": 5, "fields": [{"name": "email"}, {"name": "user_metadata.consent.given"}, {"name": "user_metadata.consent.date"}, {"name": "user_metadata.consent.text_details"}]}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtAPIAccessToken}",
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"connection_id": "{yourConnectionId}", "format": "csv", "limit": 5, "fields": [{"name": "email"}, {"name": "user_metadata.consent.given"}, {"name": "user_metadata.consent.date"}, {"name": "user_metadata.consent.text_details"}]}"

  headers = {
      'authorization': "Bearer {yourMgmtAPIAccessToken}",
      'content-type': "application/json"
      }

  conn.request("POST", "/{yourDomain}/api/v2/jobs/users-exports", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/jobs/users-exports")

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

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer {yourMgmtAPIAccessToken}'
  request["content-type"] = 'application/json'
  request.body = "{"connection_id": "{yourConnectionId}", "format": "csv", "limit": 5, "fields": [{"name": "email"}, {"name": "user_metadata.consent.given"}, {"name": "user_metadata.consent.date"}, {"name": "user_metadata.consent.text_details"}]}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer {yourMgmtAPIAccessToken}",
    "content-type": "application/json"
  ]
  let parameters = [
    "connection_id": "{yourConnectionId}",
    "format": "csv",
    "limit": 5,
    "fields": [["name": "email"], ["name": "user_metadata.consent.given"], ["name": "user_metadata.consent.date"], ["name": "user_metadata.consent.text_details"]]
  ] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/jobs/users-exports")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

<Callout icon="file-lines">
  In user-export CSV files, we escape string data types in conformance with OWASP standards for CSV injection mitigation:

  * Double-quote characters are prepended with a double-quote character.
  * Each string is prepended with a single-quote character.
  * Each string is wrapped in double quotes.

  This does not apply to Auth0-generated dates in ISO 8601 format.
</Callout>

### JSON-compatible format

If you export the data in JSON-compatible format, you only need to provide the root property; you do not need to name each individual inner property since they will be included automatically.

Auth0's export files use the [NDJSON](https://github.com/ndjson/ndjson-spec) format due to the large size of the export files, while the import functionality expects a JSON file.

Before you can import users using an export generated by Auth0, you'll need to convert the file from NDJSON to JSON using the library of your choice (such as [jq](https://stedolan.github.io/jq/)).

In this case, for the same example we used before, the request would look like this:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/jobs/users-exports' \
    --header 'authorization: Bearer {yourMgmtAPIAccessToken}' \
    --header 'content-type: application/json' \
    --data '{"connection_id": "{yourConnectionId}", "format": "json", "limit": 5, "fields": [{"name": "email"}, {"name": "user_metadata.consent"}]}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/jobs/users-exports");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer {yourMgmtAPIAccessToken}");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"connection_id": "{yourConnectionId}", "format": "json", "limit": 5, "fields": [{"name": "email"}, {"name": "user_metadata.consent"}]}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/jobs/users-exports"

  	payload := strings.NewReader("{"connection_id": "{yourConnectionId}", "format": "json", "limit": 5, "fields": [{"name": "email"}, {"name": "user_metadata.consent"}]}")

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

  	req.Header.Add("authorization", "Bearer {yourMgmtAPIAccessToken}")
  	req.Header.Add("content-type", "application/json")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/jobs/users-exports")
    .header("authorization", "Bearer {yourMgmtAPIAccessToken}")
    .header("content-type", "application/json")
    .body("{"connection_id": "{yourConnectionId}", "format": "json", "limit": 5, "fields": [{"name": "email"}, {"name": "user_metadata.consent"}]}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/jobs/users-exports',
    headers: {
      authorization: 'Bearer {yourMgmtAPIAccessToken}',
      'content-type': 'application/json'
    },
    data: {
      connection_id: '{yourConnectionId}',
      format: 'json',
      limit: 5,
      fields: [{name: 'email'}, {name: 'user_metadata.consent'}]
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtAPIAccessToken}",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"connection_id": @"{yourConnectionId}",
                                @"format": @"json",
                                @"limit": @5,
                                @"fields": @[ @{ @"name": @"email" }, @{ @"name": @"user_metadata.consent" } ] };

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

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/jobs/users-exports"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/jobs/users-exports",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{"connection_id": "{yourConnectionId}", "format": "json", "limit": 5, "fields": [{"name": "email"}, {"name": "user_metadata.consent"}]}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtAPIAccessToken}",
      "content-type: application/json"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"connection_id": "{yourConnectionId}", "format": "json", "limit": 5, "fields": [{"name": "email"}, {"name": "user_metadata.consent"}]}"

  headers = {
      'authorization': "Bearer {yourMgmtAPIAccessToken}",
      'content-type': "application/json"
      }

  conn.request("POST", "/{yourDomain}/api/v2/jobs/users-exports", payload, headers)

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

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/jobs/users-exports")

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

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer {yourMgmtAPIAccessToken}'
  request["content-type"] = 'application/json'
  request.body = "{"connection_id": "{yourConnectionId}", "format": "json", "limit": 5, "fields": [{"name": "email"}, {"name": "user_metadata.consent"}]}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer {yourMgmtAPIAccessToken}",
    "content-type": "application/json"
  ]
  let parameters = [
    "connection_id": "{yourConnectionId}",
    "format": "json",
    "limit": 5,
    "fields": [["name": "email"], ["name": "user_metadata.consent"]]
  ] as [String : Any]

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

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/jobs/users-exports")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

## Check export status

Once you've created your job to export your users, you can check on its status using the [Get a Job endpoint](https://auth0.com/docs/api/management/v2#!/Jobs/get_jobs_by_id).

Provide the ID of the job (which you received in the response when creating the job). If you're using the sample request below, replace the placeholder `{yourJobId}` with the value of the ID.

Require Scopes: `create:users`, `read:users`, `create:passwords_checking_job`

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/jobs/%7ByourJobId%7D' \
    --header 'authorization: Bearer {yourMgmtAPIAccessToken}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/jobs/%7ByourJobId%7D");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer {yourMgmtAPIAccessToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

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

  func main() {

  	url := "https://{yourDomain}/api/v2/jobs/%7ByourJobId%7D"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer {yourMgmtAPIAccessToken}")

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

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

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

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/jobs/%7ByourJobId%7D")
    .header("authorization", "Bearer {yourMgmtAPIAccessToken}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/jobs/%7ByourJobId%7D',
    headers: {authorization: 'Bearer {yourMgmtAPIAccessToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtAPIAccessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/jobs/%7ByourJobId%7D"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/jobs/%7ByourJobId%7D",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtAPIAccessToken}"
    ],
  ]);

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

  curl_close($curl);

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

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {yourMgmtAPIAccessToken}" }

  conn.request("GET", "/{yourDomain}/api/v2/jobs/%7ByourJobId%7D", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/jobs/%7ByourJobId%7D")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer {yourMgmtAPIAccessToken}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourMgmtAPIAccessToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/jobs/%7ByourJobId%7D")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

You should get a response like the following:

```json lines expandable theme={null}
{
  "type": "users_export",
  "status": "completed",
  "connection_id": "con_lCvO...a",
  "format": "csv",
  "limit": 5,
  "fields": [
    {
      "name": "user_id"
    },
    {
      "name": "name"
    },
    {
      "name": "email"
    },
    {
      "name": "identities[0].connection",
      "export_as": "provider"
    }
  ],
  "location": "pus3-auth0-export-users-us-east-2.s3.us-east-2.amazonaws.com/job_coRQCC3MHztpuTlo/auth0docs2.csv.gz?Expires=1509725589&Key-Pair-Id=APKAJPL62IJALBDMSSCA&Signature=l2JaFXP~BATnfagb64PK-qbX9QaZREDYNW0q5QeHuV-MaDpZjpABDXfHHLh2SsCMQz~UO-QsCSfI81l0lvCKzZPZL6cZHK7f~ixlZOK~MHKJuvMqsUZMbNluNAwhFmgb2fZ86yrB1c-l2--H3lMELAk7hKUwwSrNBlsfbMgQ-i41nMNnsYdy3AVlNVQkwZyx~w-IEHfJDHsqyjia-jfDbIOLQvr8~D9PwZ-xOzROxDwgxrt3undtz80bkgP5hRKOAbHC7Y-iKWa2bzNZYHqzowTrlh7Ta60cblJR46NfF9cNqn9jqRGVv-lsvUD9FxnImCCk~DL6npJnzNLjHvn4-CaWq6KdQnwWgCnZ3LZkxXDVWLLIQQaoc6i~xbuGnnbtKRePFSnpqbt2mAUYasdxTOWuUVK8wHhtfZmRYtCpwZcElXFO9Qs~PTroYZEiS~UHH5byMLt2x4ChkHnTG7pIhLAHN~bCOLk8BN2lOkDBUASEVtuJ-1i6cKCDqI2Ro9YaKZcCYzeQvKwziX6cgnMchmaZW77~RMOGloi2EffYE31OJHKiSVRK7RGTykaYN5S2Sg7W0ZOlLPKBtCGRvGb8rJ6n3oPUiOC3lSp7v0~dkx1rm-jO8mKWZwVtC0~4DVaXsn8KXNbj0LB4mjKaDHwXs16uH1-aCfFnMK7sZC2VyCU_",
  "connection": "Username-Password-Authentication",
  "created_at": "2017-11-02T23:34:03.803Z",
  "id": "job_coRQCC3MHztpuTlo"
}
```

## Find export data

You can access your export files using the URL provided as the value for the **location** parameter. The name of your tenant is also the name of your file. For example, if your tenant name is `auth0docs`, then your file will be `auth0docs.csv` or `auth0docs.json`. When you navigate to the URL, you will automatically begin downloading the file.

The download link is valid for 60 seconds. If this time period expires, you have 24 hours to call it again before the job expires.

## Job Cleanup

All of your job-related data is automatically deleted after 24 hours and cannot be accessed afterward. As such, **we strongly recommend storing the job results using the storage mechanism of your choice**.

## Filter example

You may want to filter your exported .csv file for particular subset of your data, like the date users last logged in to your application.

1. Make a `POST` call to Management API's [Create export user's job](https://auth0.com/docs/api/management/v2/jobs/post-users-exports) endpoint to export users to a `.csv` file:

   1. Create a new job:

      ```bash lines theme={null}
      curl -L 'https://{account.namespace}/api/v2/jobs/users-exports' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer MGMT_API_TOKEN' \
      -d '{"format":"csv"}'
      ```

   2. Check the status:

      ```bash lines theme={null}
      curl -L 'https://{account.namespace}/api/v2/jobs/JOB_ID' \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer MGMT_API_TOKEN'
      ```

2. Navigate to the file in your downloads on your local machine.

3. Use a command-line tool to add a filter. For this example, we are using [Miller](https://miller.readthedocs.io/en/latest/installing-miller/):

   ```bash wrap lines theme={null}
   mlr --csv filter '$last_login >= "2024-01-01T00:00:00Z"' file.csv > filtered.csv
   ```


# Bulk User Import / Export
Source: https://auth0.com/docs/manage-users/user-migration/bulk-user-import-export

Instructions on how to bulk import and export user data into Auth0 using the Dashboard.

<Card title="Before you start">
  To use this feature, you must have **Editor - Users** or **Admin** permissions. For more information about Dashboard roles, read [Dashboard Access by Role](/docs/get-started/manage-dashboard-access/feature-access-by-role).
</Card>

You can bulk import and export user data into Auth0 using the Dashboard. Bulk imports and exports are useful for migrating users from an existing database to Auth0 or from Auth0 to a different service. All jobs initiated through the Dashboard are logged and tracked by job IDs.

For a list of user profile fields that can be imported and exported, read [User Profiles](/docs/manage-users/user-accounts/user-profiles).

### Import users

To import users to your tenant:

1. In the Auth0 Dashboard, go to [**User Management > Users**](https://manage.auth0.com/#/users). If no users exist in your tenant, choose **Import Users**. If users exist, choose **Import/Export Users > Import Users**.
2. Upload a JSON file (maximum file size 500kb) formatted to the [specifications found here](/docs/manage-users/user-migration/bulk-user-import-database-schema-and-examples).
3. Select the database connection to import users into, noting that only database connections are supported and the custom database you choose must have import mode enabled for at least one application.

   1. (Optional) Select **Upsert pre-existing users in connection** to update existing users with matching identifiers
   2. (Optional) Select **Send completion email to all tenant owners**.
4. Choose **Import Users** to submit the job. Only submit one job per import submission.

To monitor the jobs you submitted, go to **View Jobs** on the Import/Export Users screen and choose **More info** on any job. Job statuses include **Job creation failed**, **Job created, user import failed**, and **Job created, user import succeeded**.

<Frame>
  <img alt="" />
</Frame>

### Export users

<Frame>
  <img alt="" />
</Frame>

To export users from your tenant:

1. In the Dashboard, go to **User Management > Users,** then choose **Import/Export Users > Export Users**.
2. Select the database connection you want to export users from and choose JSON or CSV for your export format.
3. Specify which fields to export:

   1. Choose **Add default fields** to include standard user attributes.
   2. Update field names for your output file.
   3. Add custom user attributes as needed.
4. (Optional) Select **Export as sample** to preview the structure with up to 10 users.
5. Select **Export Users** to submit the job.

To monitor and download export jobs, go to **View jobs** in the **Import/Export Users** screen. Choose **Check Status** to monitor job progress, **Download export** to retrieve the result, or **More info** to review errors or job metadata.

### Update user profiles

The [Auth0 Management API](https://auth0.com/docs/api/management/v2/users/patch-users-by-id) allows bulk user profile updates to `user_metadata` and `app_metadata`.

This process can result in data loss; always create a backup of your user database in the event of data corruption. In addition, this process cannot block multiple users and each user must be blocked individually in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or with the [Auth0 Management API](https://auth0.com/docs/api/management/v2/users/patch-users-by-id).

To bulk-update user profiles:

1. Using the export process above, create a complete export file including all your user attributes.
2. Choose JSON format for your export.
3. When the export is complete, download the file containing your users.

###

### Update your configuration

<Warning>
  Do not change the user email address because it is the lookup key for users in the database.
</Warning>

Make a copy of the JSON file you downloaded in the previous step, then open the copy of the JSON file in a text editor. Your user schema should be similar to the one below:

```json lines expandable theme={null}
[
   {
      "Id":"auth0|626737a9813c000069daf462",
      "Nickname":"testuser1",
      "Name":"testuser1@auth0.com",
      "email":"testuser1@auth0.com",
      "Connection":"Username-Password-Authentication",
      "Created At":"2022-04-26T00:07:05.098Z",
      "Updated At":"2022-07-06T14:54:19.214Z"
   },
   {
      "Id":"auth0|62d1a1853bdcf11ff5dca672",
      "Nickname":"testuser2",
      "Name":"testuser2@auth0.com",
      "email":"testuser2@auth0.com",
      "Connection":"Username-Password-Authentication",
      "Created At":"2022-07-15T17:19:01.531Z",
      "Updated At":"2022-07-15T17:19:01.532Z"
   },
   {
      "Id":"auth0|62d1a1a524f32a4185c9ce23",
      "Nickname":"testuser3",
      "Name":"testuser3@auth0.com",
      "email":"testuser3@auth0.com",
      "Connection":"Username-Password-Authentication",
      "Created At":"2022-07-15T17:19:33.484Z",
      "Updated At":"2022-07-15T17:19:33.484Z"
   }
]
```

<Callout icon="file-lines">
  The Id must have a unique `connection|id`. If the same user Id exists in multiple connections, your update will fail.
</Callout>

To add an attribute, create a new field in each user schema and update with a value. In the example below, the **Family Name** attribute has a value of **Smith** with a comma after the new attribute value.

You can also add the `email_verified` attribute to multiple users and set the value to `true`.

```json lines theme={null}
{
   "Id":"auth0|626737a9813c000069daf462",
   "Nickname":"testuser1",
   "Family Name":"Smith",
   "Name":"testuser1@auth0.com",
   "email":"testuser1@auth0.com",
   "email_verified":true,
   "Connection":"Username-Password-Authentication",
   "Created At":"2022-04-26T00:07:05.098Z",
   "Updated At":"2022-07-06T14:54:19.214Z"
}
```

Save the changes to your user file.

<Callout icon="file-lines">
  This process cannot block multiple users. You must block users individually in the Auth0 Dashboard or with the [Auth0 Management API](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id).
</Callout>

To import updated user profile data, upload your updated user profile file and update several users in one job. **Upsert pre-existing users in connection** must be true/selected for existing users to be updated.


# Bulk User Import Schema and Examples
Source: https://auth0.com/docs/manage-users/user-migration/bulk-user-import-schema

Learn how to perform bulk user imports with the Management API.

The users file must have an array with the users' information in JSON format.

<Callout icon="file-lines">
  The file size limit for a bulk import is 500KB. You will need to start multiple imports if your data exceeds this size.
</Callout>

## User JSON schema

The following JSON schema describes valid users:

```json lines expandable theme={null}
{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "The user's email address.",
      "format": "email"
    },
    "email_verified": {
      "type": "boolean",
      "default": false,
      "description": "Indicates whether the user has verified their email address."
    },
    "user_id": {
      "type": "string",
      "description": "The user's unique identifier. This will be prepended by the connection strategy."
    },
    "username": {
      "type": "string",
      "description": "The user's username."
    },
    "given_name": {
      "type": "string",
      "description": "The user's given name."
    },
    "family_name": {
      "type": "string",
      "description": "The user's family name."
    },
    "name": {
      "type": "string",
      "description": "The user's full name."
    },
    "nickname": {
      "type": "string",
      "description": "The user's nickname."
    },
    "picture": {
      "type": "string",
      "description": "URL pointing to the user's profile picture."
    },
    "blocked": {
      "type": "boolean",
      "description": "Indicates whether the user has been blocked."
    },
    "password_hash": {
      "type": "string",
      "description": "Hashed password for the user. Passwords should be hashed using bcrypt $2a$ or $2b$ and have 10 saltRounds."
    },
    "custom_password_hash": {
      "type": "object",
      "description": "A more generic way to provide the users password hash. This can be used in lieu of the password_hash field when the users password hash was created with an alternate algorithm. Note that this field and password_hash are mutually exclusive.",
      "properties": {
        "algorithm": {
          "type": "string",
          "enum": [
            "argon2",
            "bcrypt",
            "hmac",
            "ldap",
            "md4",
            "md5",
            "sha1",
            "sha256",
            "sha512",
            "pbkdf2",
            "scrypt"
          ],
          "description": "The algorithm that was used to hash the password."
        },
        "hash": {
          "type": "object",
          "properties": {
            "value": {
              "type": "string",
              "description": "The password hash."
            },
            "encoding": {
              "type": "string",
              "enum": [
                "base64",
                "hex",
                "utf8"
              ],
              "description": "The encoding of the provided hash. Note that both upper and lower case hex variants are supported, as well as url-encoded base64."
            },
            "digest": {
              "type": "string",
              "description": "The algorithm that was used to generate the HMAC hash",
              "enum": [
                "md4",
                "md5",
                "ripemd160",
                "sha1",
                "sha224",
                "sha256",
                "sha384",
                "sha512",
                "whirlpool"
              ]
            },
            "key": {
              "type": "object",
              "description": "The key that was used to generate the HMAC hash",
              "required": [
                "value"
              ],
              "properties": {
                "value": {
                  "type": "string",
                  "description": "The key value"
                },
                "encoding": {
                  "type": "string",
                  "enum": [
                    "base64",
                    "hex",
                    "utf8"
                  ],
                  "default": "utf8",
                  "description": "The key encoding"
                }
              }
            }
          }
        },
        "salt": {
          "type": "object",
          "properties": {
            "value": {
              "type": "string",
              "description": "The salt value used to generate the hash."
            },
            "encoding": {
              "type": "string",
              "enum": [
                "base64",
                "hex",
                "utf8"
              ],
              "default": "utf8",
              "description": "The encoding of the provided salt. Note that both upper and lower case hex variants are supported, as well as url-encoded base64."
            },
            "position": {
              "type": "string",
              "enum": [
                "prefix",
                "suffix"
              ],
              "default": "prefix",
              "description": "The position of the salt when the hash was calculated. For example; MD5('salt' + 'password') = '67A1E09BB1F83F5007DC119C14D663AA' would have \"position\":\"prefix\"."
            }
          },
          "required": [
            "value"
          ]
        },
        "password": {
          "type": "object",
          "properties": {
            "encoding": {
              "type": "string",
              "enum": [
                "ascii",
                "utf8",
                "utf16le",
                "ucs2",
                "latin1",
                "binary"
              ],
              "default": "utf8",
              "description": "The encoding of the password used to generate the hash. On login, the user-provided password will be transcoded from utf8 before being checked against the provided hash. For example; if your hash was generated from a ucs2 encoded string, then you would supply \"encoding\":\"ucs2\"."
            }
          }
        },
        "keylen": {
          "type": "integer",
          "description": "Desired key length in bytes for the scrypt hash. Must be an integer greater than zero. Required when algorithm is set to scrypt."
        },
        "cost": {
          "type": "integer",
          "default": 16384,
          "description": "CPU/memory cost parameter used for the scrypt hash. Must be a power of two greater than one. Only used when algorithm is set to scrypt."
        },
        "blockSize": {
          "type": "integer",
          "default": 8,
          "description": "Block size parameter used for the scrypt hash. Must be a positive integer. Only used when algorithm is set to scrypt."
        },
        "parallelization": {
          "type": "integer",
          "default": 1,
          "description": "Parallelization parameter used for the scrypt hash. Must be a positive integer. Only used when algorithm is set to scrypt."
        }
      },
      "required": [
        "algorithm",
        "hash"
      ],
      "additionalProperties": false
    },
    "app_metadata": {
      "type": "object",
      "description": "Data related to the user that does affect the application's core functionality."
    },
    "user_metadata": {
      "type": "object",
      "description": "Data related to the user that does not affect the application's core functionality."
    },
    "mfa_factors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "totp": {
            "type": "object",
            "properties": {
              "secret": {
                "type": "string",
                "pattern": "^[A-Z2-7]+$",
                "description": "The OTP secret is used with authenticator apps (Google Authenticator, Microsoft Authenticator, Authy, 1Password, LastPass). It must be supplied in un-padded Base32 encoding, such as: JBTWY3DPEHPK3PNP"
              }
            },
            "additionalProperties": false,
            "required": [
              "secret"
            ]
          },
          "phone": {
            "type": "object",
            "properties": {
              "value": {
                "type": "string",
                "pattern": "^\\+[0-9]{1,15}$",
                "description": "The phone number for SMS MFA. The phone number should include a country code and begin with +, such as: +12125550001"
              }
            },
            "additionalProperties": false,
            "required": [
              "value"
            ]
          },
          "email": {
            "type": "object",
            "properties": {
              "value": {
                "type": "string",
                "format": "email",
                "description": "The email address for MFA"
              }
            },
            "additionalProperties": false,
            "required": [
              "value"
            ]
          }
        },
        "maxProperties": 1,
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 10
    }
  },
  "required": [
    "email"
  ],
  "additionalProperties": false
}
```

To learn more about JSON schema, read [jsonschema.org](http://json-schema.org).

## Properties

You can import users with the following properties:

<table>
  <thead>
    <tr>
      <th><strong>Property</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Upsert During Import?</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>app\_metadata</code></td>
      <td>object</td>
      <td>Data that can affect the application's core functionality or what the user can access. Data stored in <code>app\_metadata</code> cannot be edited by users. This may include things such as support plans, roles or access groups.</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td><code>blocked</code></td>
      <td>boolean</td>
      <td>Indicates whether the user has been blocked.</td>
      <td>No</td>
    </tr>

    <tr>
      <td><code>email</code></td>
      <td>string</td>
      <td>The user's email address.</td>
      <td>No</td>
    </tr>

    <tr>
      <td><code>email\_verified</code></td>
      <td>boolean</td>
      <td>Indicates whether the user has verified their email address. Set to <code>false</code> by default if <code>email</code> is updated by upsert but not <code>email\_verified</code>.</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td><code>family\_name</code></td>
      <td>string</td>
      <td>The user's family name.</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td><code>given\_name</code></td>
      <td>string</td>
      <td>The user's given name.</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td><code>name</code></td>
      <td>string</td>
      <td>The user's full name.</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td><code>nickname</code></td>
      <td>string</td>
      <td>The user's nickname.</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td><code>picture</code></td>
      <td>string</td>
      <td>URL pointing to the user's profile picture.</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td><code>user\_id</code></td>
      <td>string</td>
      <td>The user's unique identifier. This will be prepended by the connection strategy.</td>
      <td>No</td>
    </tr>

    <tr>
      <td><code>user\_metadata</code></td>
      <td>object</td>
      <td>Data that does not impact what users can or cannot access, such as work address, home address, or user preferences.</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td><code>username</code></td>
      <td>string</td>
      <td>The user's username.</td>
      <td>No</td>
    </tr>

    <tr>
      <td><code>password\_hash</code></td>
      <td>string</td>
      <td>Hashed password for the user's connection. When users are created, Auth0 uses <a href="https://auth0.com/blog/hashing-in-action-understanding-bcrypt/">bcrypt</a> to secure the password. Importing hashed passwords lets users keep their passwords for a smoother experience. Compatible passwords should be hashed using bcrypt $2a$ or $2b$ and have 10 saltRounds. This property can only be provided when the user is first imported and cannot be updated later.</td>
      <td>No</td>
    </tr>

    <tr>
      <td><code>custom\_password\_hash</code></td>
      <td>object</td>
      <td>A more generic way to provide the user's password hash. This can be used instead of the <code>password\_hash</code> field when the user's password hash was created with an alternate algorithm. During the bulk import process, you can update the <code>custom\_password\_hash</code> if the user did not login using the initially imported <code>custom\_password\_hash</code>.</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td><code>mfa\_factors</code></td>
      <td>array</td>
      <td>The MFA factors that can be used to authenticate this user</td>
      <td>No</td>
    </tr>
  </tbody>
</table>

To learn more about `app_metadata` and `user_metadata`, read [Understand How Metadata Works in User Profiles](/docs/manage-users/user-accounts/metadata).

## App metadata

The `user.app_metadata` object must **not** contain any of these properties:

* `__tenant`
* `_id`
* `blocked`
* `clientID`
* `created_at`
* `email_verified`
* `email`
* `globalClientID`
* `global_client_id`
* `identities`
* `lastIP`
* `lastLogin`
* `loginsCount`
* `metadata`
* `multifactor_last_modified`
* `multifactor`
* `updated_at`
* `user_id`

## Custom password hash

The `user.custom_password_hash` object can be used instead of the `user.password_hash` property when the user's password hash was created with an alternate algorithm. Note this field and `password_hash` are mutually exclusive.

The `user.custom_password_hash` object has the following properties:

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>algorithm</code></td>
      <td>string</td>
      <td>The algorithm used to hash the password. Must be one of: <ul><li><code>argon2</code></li><li><code>bcrypt</code></li><li><code>hmac</code></li><li><code>ldap</code></li><li><code>md4</code></li><li><code>md5</code></li><li><code>sha1</code></li><li><code>sha256</code></li><li><code>sha512</code></li><li><code>pbkdf2</code></li><li><code>scrypt</code></li></ul></td>
    </tr>

    <tr>
      <td><code>hash</code></td>
      <td>object</td>
      <td> </td>
    </tr>

    <tr>
      <td><code>hash.value</code></td>
      <td>string</td>
      <td>The password hash.</td>
    </tr>

    <tr>
      <td><code>hash.encoding</code></td>
      <td>string</td>
      <td>The encoding of the provided hash. Must be one of: <ul><li><code>base64</code></li><li><code>hex</code></li><li><code>utf8</code></li></ul>Upper and lower case hex variants are supported, as well as url-encoded base64.</td>
    </tr>

    <tr>
      <td><code>hash.digest</code></td>
      <td>string</td>
      <td>The algorithm used to generate the HMAC hash. Must be one of: <ul><li><code>md4</code></li><li><code>md5</code></li><li><code>ripemd160</code></li><li><code>sha1</code></li><li><code>sha224</code></li><li><code>sha256</code></li><li><code>sha384</code></li><li><code>sha512</code></li><li><code>whirlpool</code></li></ul></td>
    </tr>

    <tr>
      <td><code>hash.key</code></td>
      <td>object</td>
      <td>The key used to generate the HMAC hash.</td>
    </tr>

    <tr>
      <td><code>hash.key.value</code></td>
      <td>string</td>
      <td>The key value.</td>
    </tr>

    <tr>
      <td><code>hash.key.encoding</code></td>
      <td>string</td>
      <td>The key encoding. Must be one of: <ul><li><code>base64</code></li><li><code>hex</code></li><li><code>utf8</code></li></ul>By default, <code>hash.key.encoding</code> is <code>utf8</code>.</td>
    </tr>

    <tr>
      <td><code>salt</code></td>
      <td>object</td>
      <td> </td>
    </tr>

    <tr>
      <td><code>salt.value</code></td>
      <td>string</td>
      <td>The salt value used to generate the hash.</td>
    </tr>

    <tr>
      <td><code>salt.encoding</code></td>
      <td>string</td>
      <td>The encoding of the provided salt. Must be one of: <ul><li><code>base64</code></li><li><code>hex</code></li><li><code>utf8</code></li></ul> Upper and lower case hex variants are supported, as well as url-encoded base64. By default, <code>salt.encoding</code> is <code>utf8</code>.</td>
    </tr>

    <tr>
      <td><code>salt.position</code></td>
      <td>string</td>
      <td>The position of the salt when the hash was calculated. By default, <code>salt.position</code> is <code>prefix</code>.</td>
    </tr>

    <tr>
      <td><code>password.encoding</code></td>
      <td>string</td>
      <td>The encoding of the password used to generate the hash. Must be one of: <ul><li><code>ascii</code></li><li><code>utf8</code></li><li><code>utf16le</code></li><li><code>ucs2</code></li><li><code>latin1</code></li><li><code>binary</code></li></ul> On login, the user-provided password will be transcoded from <code>password.encoding</code> before being checked against the provided hash. For example, if your hash was generated from a <code>ucs2</code> encoded string, then you would set: <code> "encoding": "ucs2"</code></td>
    </tr>

    <tr>
      <td><code>keylen</code></td>
      <td>integer</td>
      <td>Desired key length in bytes for the scrypt hash. Must be an integer greater than zero. <br />This parameter is required when <code>algorithm</code> is set to <code>scrypt</code>.</td>
    </tr>

    <tr>
      <td><code>cost</code></td>
      <td>integer</td>
      <td>CPU/memory cost parameter used for the scrypt hash. Must be a power of two greater than one. By default, <code>cost</code> is 16384.<br />This parameter is only used when <code>algorithm</code> is set to <code>scrypt</code>.</td>
    </tr>

    <tr>
      <td><code>blockSize</code></td>
      <td>integer</td>
      <td>Block size parameter used for the scrypt hash. Must be a positive integer. By default, <code>blockSize</code> is 8.<br />This parameter is only used when <code>algorithm</code> is set to <code>scrypt</code>.</td>
    </tr>

    <tr>
      <td><code>parallelization</code></td>
      <td>integer</td>
      <td>Parallelization parameter used for the scrypt hash. Must be a positive integer. By default, <code>parallelization</code> is 1.<br />This parameter is only used when <code>algorithm</code> is set to <code>scrypt</code>.</td>
    </tr>
  </tbody>
</table>

### Update custom password hash

During the bulk import process, you can update the `custom_password_hash` if the user did not login using the initially imported `custom_password_hash`. For example, you can submit the below JSON twice to the[`/api/v2/jobs/users-imports`](https://auth0.com/docs/api/management/v2?_ga=2.169020323.346193905.1601302257-746691936.1587131255#!/Jobs/post_users_imports) endpoint with different values for `custom_password_hash`. On the second submit, send the `upsert` flag to `true`.

```json lines theme={null}
[
    {
    	"user_id": "2000",
        "email": "examplecouser20@gmail.com",
        "given_name": "ExampleCo User",
        "name" : "ExampleCoUser20",
        "custom_password_hash": {
            "algorithm": "bcrypt",
            "hash": {
                "value": "$2a$10$aHF7mbpWT6tZ7PJVtwtjNelaKbszikcYBCB2jibvbFcGFmOsu/s4K"
            }
        }
    }
]
```

You can use the [Bcrypt Password Generator](https://www.browserling.com/tools/bcrypt) at browserling.com to generate bcrypt password hashes.

### Supported hash algorithms

Auth0 currently supports imports of user passwords hashed by:

* [Argon2](https://github.com/p-h-c/phc-winner-argon2)
* [bcrypt](https://auth0.com/blog/hashing-in-action-understanding-bcrypt/)
* [LDAP](https://tools.ietf.org/html/rfc2307#section-5.3) (`RFC-2307 "userPassword"`)
* [HMAC](https://tools.ietf.org/html/rfc2104)
* [MD4](https://tools.ietf.org/html/rfc1320)
* [MD5](https://tools.ietf.org/html/rfc1321)
* [SHA1](https://tools.ietf.org/html/rfc3174)
* [SHA256 and SHA512](https://tools.ietf.org/html/rfc4634)
* [PBKDF2](https://tools.ietf.org/html/rfc2898#section-5.2)
* [scrypt](https://datatracker.ietf.org/doc/rfc7914/)

Please consider the following sections when providing a `custom_password_hash`.

#### Argon2

When the `algorithm` is set to `argon2`:

* `hash.encoding` must be `utf8`.
* `hash.salt` is not allowed.
* `hash.value` must be in PHC string format, specified in [P-H-C / phc-string-format](https://github.com/P-H-C/phc-string-format/blob/master/phc-sf-spec.md) on GitHub. It also must conform to the requirements specified in [Auth0 / magic](https://github.com/auth0/magic#magicpasswordhash--magicverifypassword) on GitHub.
* `hash.value` must include the base64 encoded salt (as specified in the `PHC` documentation).

#### bcrypt

When the `algorithm` is set to `bcrypt`:

* `hash.encoding` must be `utf8`.
* `hash.salt` is allowed in conjunction with with salt encoding and position.
* `hash.value` must include one of these prefixes:

  * `$2a$`
  * `$2b$`
  * `$2y$`

  Other prefixes, such as `$2$`, `$sha1$`, and `$2x$`, are not supported at this time.

For example, this was generated from the string `hello` using a cost parameter of 10:

`$2b$10$nFguVi9LsCAcvTZFKQlRKeLVydo8ETv483lkNsSFI/Wl1Rz1Ypo1K`

The `bcrypt` algorithm processes a maximum of 72 bytes of input when computing password hashes or performing comparisons and the length of `salt.value` counts towards the 72-byte input limit. Any input beyond the 72 byte limit is truncated; for example, if the salt consumes 10 bytes, the maximum password length for hashing or comparison is 62 bytes.

Passwords longer than the reduced limit are truncated, potentially weakening password strength or introducing hash collisions. Always validate password lengths before hashing.

#### HMAC

When the `algorithm` is set to `hmac`:

* `hash.encoding` must be either `hex` or `base64`.
* `hash.digest` is required and must be one of these:

  * `md4`
  * `md5`
  * `ripemd160`
  * `sha1`
  * `sha224`
  * `sha256`
  * `sha384`
  * `sha512`
  * `whirlpool`
* `hash.key.value` is required.
* `hash.key.encoding` must be either `base64` or `hex` or `utf8`.

#### LDAP

When the `algorithm` is set to `ldap`:

* `hash.encoding` must be `utf8`.
* `salt` is not allowed.
* `hash.value` must adhere to the format outlined in [RFC-2307 section-5.3](https://tools.ietf.org/html/rfc2307#section-5.3) on IETF Datatracker.
* The scheme should be one of `md5|smd5|sha*|ssha*` see [here](https://www.openldap.org/faq/data/cache/347.html) for more info.
* Note that the [crypt](https://www.openldap.org/faq/data/cache/344.html) scheme is **not supported** due to system/implementation dependent behavior. To learn more, read [Open LDAP Admin Guide - 14.4.2. CRYPT password storage scheme](https://www.openldap.org/doc/admin24/guide.html#CRYPT%20password%20storage%20scheme).

#### MD or SHA

When the `algorithm` is set to `md4`, `md5`, `sha1`, `sha256`, or `sha512`:

* `hash.encoding` must be either `hex` or `base64`.

#### PBKDF2

When the `algorithm` is set to `pbkdf2`:

* `hash.encoding` must be `utf8`.
* `hash.salt` is not allowed.
* `hash.value` should be in PHC string format, specified in [P-H-C / phc-string-format](https://github.com/P-H-C/phc-string-format/blob/master/phc-sf-spec.md) on GitHub.
* `hash.value` must include the B64 encoded salt (base64 omitting padding characters `=`, as specified in the `PHC` documentation).
* `hash.value` should include `i` (iterations) and `l` (keylen) parameters. If these parameters are omitted, they will default to `i=100000` and `l=64`.
* The `id` should be in a `pbkdf2-<digest>` format (`pbkdf2-sha512`, `pbkdf2-md5`, etc). The supported digests are:

  * `RSA-MD4`
  * `RSA-MD5`
  * `RSA-MDC2`
  * `RSA-RIPEMD160`
  * `RSA-SHA1`
  * `RSA-SHA1-2`
  * `RSA-SHA224`
  * `RSA-SHA256`
  * `RSA-SHA384`
  * `RSA-SHA512`
  * `md4`
  * `md4WithRSAEncryption`
  * `md5`
  * `md5WithRSAEncryption`
  * `mdc2`
  * `mdc2WithRSA`
  * `ripemd`
  * `ripemd160`
  * `ripemd160WithRSA`
  * `rmd160`
  * `sha1`
  * `sha1WithRSAEncryption`
  * `sha224`
  * `sha224WithRSAEncryption`
  * `sha256`
  * `sha256WithRSAEncryption`
  * `sha384`
  * `sha384WithRSAEncryption`
  * `sha512`
  * `sha512WithRSAEncryption`
  * `ssl3-md5`
  * `ssl3-sha1`
  * `whirlpool`

#### scrypt

When the `algorithm` is set to `scrypt`:

* `hash.encoding` must be either `hex` or `base64`.
* `keylen` parameter is required.
* `cost` parameter can be specified; if not, it will default to 16384.
* `blockSize` parameter can be specified; if not, it will default to 8.
* `parallelization` parameter can be specified; if not, it will default to 1.

### MFA factors

The `user.mfa_factors` array contains <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> enrollments for the user. To learn more, read [Multi-Factor Authentication in Auth0](/docs/secure/multi-factor-authentication). Importing enrollments prevents the need for users to re-enroll in MFA after they're imported. The supported enrollment types are:

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>email</code></td>
      <td>object</td>
      <td> </td>
    </tr>

    <tr>
      <td><code>email.value</code></td>
      <td>string</td>
      <td>The email address for MFA.</td>
    </tr>

    <tr>
      <td><code>phone</code></td>
      <td>object</td>
      <td> </td>
    </tr>

    <tr>
      <td><code>phone.value</code></td>
      <td>string</td>
      <td>The phone number for SMS MFA. Must have a country code and begin with <code>+</code>, such as: <code>"+12125550001"</code></td>
    </tr>

    <tr>
      <td><code>totp</code></td>
      <td>object</td>
      <td> </td>
    </tr>

    <tr>
      <td><code>totp.secret</code></td>
      <td>string</td>
      <td>The OTP secret for MFA authentication with authenticator apps (Google Authenticator, Microsoft Authenticator, Authy, 1Password, LastPass). Must be in un-padded Base32 encoding, for example: <code>"JBTWY3DPEHPK3PNP"</code></td>
    </tr>
  </tbody>
</table>

## Examples

### Basic example

A file with the following contents is valid:

```json lines theme={null}
[
  {
    "email": "john.doe@contoso.com",
    "email_verified": false,
    "app_metadata": {
        "roles": ["admin"],
        "plan": "premium"
    },
    "user_metadata": {
        "theme": "light"
    }
  }
]
```

### Custom password hash examples

Some example users with hashes provided:

```json lines expandable theme={null}
[
    {
        "email": "antoinette@contoso.com",
        "email_verified": false,
        "custom_password_hash": {
            "algorithm": "md4",
            "hash": {
                "value": "AbuUujgF0pPPkJPSFRTpmA==",
                "encoding": "base64"
            }
        }
    },
    {
        "email": "mary@contoso.com",
        "email_verified": false,
        "custom_password_hash": {
            "algorithm": "sha256",
            "hash": {
                "value": "d24e794fce503c3ddb1cd1ba1dd5d9b250cf9917336a0316fefd87fecf79200f",
                "encoding": "hex"
            },
            "salt": {
                "value": "abc123",
                "position": "prefix"
            }
        }
    },
    {
        "email": "velma@contoso.com",
        "email_verified": false,
        "custom_password_hash": {
            "algorithm": "bcrypt",
            "hash": {
                "value": "$2b$10$C9hB01.YxRSTcn/ZOOo4j.TW7xCKKFKBSF.C7E0xiUwumqIDqWUXG"
            }
        }
    },
    {
        "email": "edward@contoso.com",
        "email_verified": false,
        "custom_password_hash": {
            "algorithm": "argon2",
            "hash": {
                "value": "$argon2id$v=19$m=65536,t=2,p=1$J6Q/82PCyaNpYKRELJyTZg$m04qUAB8rexWDR4+/0f+SFB+4XMFxt7YAvAq2UycYos"
            }
        }
    },
    {
        "email": "terrell@contoso.com",
        "email_verified": false,
        "custom_password_hash": {
            "algorithm": "pbkdf2",
            "hash": {
                "value": "$pbkdf2-md4$i=100000,l=64$+N375B8q0Fw$fp2R9KAM4hK/votGHC5Fu+jhqbxUD8+Nic/EMSGvNC3UP/k7wSHI0uXluHRSkZfl/BOheYqNOemayG90ZaSSQw",
                "encoding": "utf8"
            }
        }
    },
    {
        "email": "cecil@contoso.com",
        "email_verified": false,
        "custom_password_hash": {
            "algorithm": "pbkdf2",
            "hash": {
                "value": "$pbkdf2-sha512$i=100000,l=64$KNyFsA2rWoE$I2CQGI9H0JxdDf3kERRI97kPCGxh0KWBIV3MxyaS191gDGfzVBGyS4BibhgqWQ0/ails8mHuU9ckASxHOOq58w"
            }
        }
    },
    {
        "email": "sean@contoso.com",
        "email_verified": false,
        "custom_password_hash": {
            "algorithm": "ldap",
            "hash": {
                "value": "{SSHA384}/cgEjdoZh85DhurDeOQEMO1rMlAur93SVPbYe5XSD4lF7nNuvrBju5hUeg9A6agRemgSXGl5YuE=",
                "encoding": "utf8"
            }
        }
    },
    {
        "email": "peter@contoso.com",
        "email_verified": false,
        "custom_password_hash": {
            "algorithm": "hmac",
            "hash": {
                "value": "cg7f42jH39/2EaAU4wNd4s2lKIk=",
                "encoding": "base64",
                "digest": "sha1",
                "key": {
                    "value": "736868",
                    "encoding": "hex"
                }
            }
        }
    },
    {
        "email": "carmella@contoso.com",
        "email_verified": false,
        "custom_password_hash": {
            "algorithm": "scrypt",
            "hash": {
                "value": "097f6197e1b41538f723e32aa7a68e8d76227d8e432ce5faa4882a913032db29",
                "encoding": "hex"
            },
            "salt": {
                "value": "abc123",
                "encoding": "utf8"
            },
            "keylen": 32,
            "cost": 4096
        }
    }
]
```

### MFA factors examples

As you might expect, the `user.mfa_factors` array allows you to provide the user's MFA enrollments. The supported enrollment types are:

* Phone: Used for sms-based verification.
* TOTP: OTP secret for use with MFA type apps (Google Authenticator, Microsoft Authenticator, Authy, 1Password, LastPass).
* Email: Used for email-based verification.

Some examples of users with MFA factors:

```json lines expandable theme={null}
[
    {
        "email": "antoinette@contoso.com",
        "mfa_factors": [
            {
                "totp": {
                    "secret": "2PRXZWZAYYDAWCD"
                }
            },
            {
                "phone": {
                    "value": "+15551112233"
                }
            },
            {
                "email": {
                    "value": "antoinette@antoinette.biz"
                }
            }
        ]
    },
    {
        "email": "mary@contoso.com",
        "mfa_factors": [
            {
                "totp": {
                    "secret": "JBTWY3DPEHPK3PNP"
                }
            }
        ]
    },
    {
        "email": "velma@contoso.com",
        "mfa_factors": [
            {
                "phone": {
                    "value": "+15551234567"
                }
            },
        ]
    },
    {
        "email": "edward@contoso.com",
        "mfa_factors": [
            {
                "email": {
                    "value": "edward@edward.biz"
                }
            }
        ]
    }
]
```

## Learn more

* [Bulk User Imports](/docs/manage-users/user-migration/bulk-user-imports)
* [Bulk User Exports](/docs/manage-users/user-migration/bulk-user-exports)
* [Configure Automatic Migration from Your Database](/docs/manage-users/user-migration/configure-automatic-migration-from-your-database)


# Bulk User Imports
Source: https://auth0.com/docs/manage-users/user-migration/bulk-user-imports

Learn how to perform bulk user imports with the Management API.

You can bulk import user data into Auth0 using the [Create Import Users Job](https://auth0.com/docs/api/management/v2#!/Jobs/post_users_imports) endpoint. Bulk imports are useful for migrating users from an existing database or service to Auth0.

<Warning>
  If you try to use more than one migration method (for example, automatic migration then bulk user import), you may encounter a `DUPLICATED_USER` error. This error indicates that the user exists in Auth0's internal user store but not in your tenant. To correct this error, delete the user with the Auth0 Management API [Delete a Connection User](https://auth0.com/docs/api/management/v2#!/Connections/delete_users_by_email) endpoint and then re-attempt the import.
</Warning>

## Prerequisites

Before you launch the import users job:

* Configure a database connection to import the users into and enable it for at least one application.
* If you are importing passwords, make sure the passwords are hashed using one of the supported algorithms. Users with passwords hashed by unsupported algorithms will need to reset their password when they log in for the first time after the bulk import.
* If you are importing <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> enrollments, make sure they are a supported type: `email`, `phone`, or `totp`.
* [Get a Management API token](/docs/secure/tokens/access-tokens/management-api-access-tokens) for job endpoint requests.

<Callout icon="file-lines">
  If you are using an export file from an Auth0 tenant, you must convert the exported file from `ndjson` to [JSON](/docs/manage-users/user-migration/bulk-user-exports#json-compatible-format). To keep the same user IDs, you must remove the `auth0| prefix` from all imported user IDs.

  The import process automatically adds the `auth0| prefix` to the imported user IDs. If you do not remove the `auth0|` prefix before importing, the user IDs return as `auth0|auth0|...`
</Callout>

## Create users JSON file

Create a JSON file with the user data you want to import into Auth0. How you export user data to a JSON file will vary depending on your existing user database. The <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> endpoint expects sections of the JSON file. So instead of using `fs.readFileSync`, it requires `fs.createReadStream`. The endpoint expects a piped read stream instead of the whole JSON file.

To learn more about the JSON file schema and see examples, read [Bulk Import Database Schema and Examples](/docs/manage-users/user-migration/bulk-user-import-database-schema-and-examples).

<Callout icon="file-lines">
  The file size limit for a bulk import is 500KB. You will need to start multiple imports if your data exceeds this size.
</Callout>

## Request bulk user import

To start a bulk user import job, make a `POST` request to the [Create Import Users Job](https://auth0.com/docs/api/management/v2#!/Jobs/post_users_imports) endpoint. Be sure to replace the `MGMT_API_ACCESS_TOKEN`, `USERS_IMPORT_FILE.json`, `CONNECTION_ID`, and `EXTERNAL_ID` placeholder values with your Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, users JSON file, database [connection ID](/docs/authenticate/identity-providers/locate-the-connection-id), and external ID, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/jobs/users-imports' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --form users=@USERS_IMPORT_FILE.json \
    --form connection_id=CONNECTION_ID \
    --form external_id=EXTERNAL_ID
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/jobs/users-imports");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("content-type", "multipart/form-data; boundary=---011000010111000001101001");
  request.AddParameter("multipart/form-data; boundary=---011000010111000001101001", "-----011000010111000001101001\r
  Content-Disposition: form-data; name="users"; filename="USERS_IMPORT_FILE.json"\r
  Content-Type: text/json\r
  \r
  \r
  -----011000010111000001101001\r
  Content-Disposition: form-data; name="connection_id"\r
  \r
  CONNECTION_ID\r
  -----011000010111000001101001\r
  Content-Disposition: form-data; name="external_id"\r
  \r
  EXTERNAL_ID\r
  -----011000010111000001101001--\r
  ", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/jobs/users-imports"

  	payload := strings.NewReader("-----011000010111000001101001\r
  Content-Disposition: form-data; name="users"; filename="USERS_IMPORT_FILE.json"\r
  Content-Type: text/json\r
  \r
  \r
  -----011000010111000001101001\r
  Content-Disposition: form-data; name="connection_id"\r
  \r
  CONNECTION_ID\r
  -----011000010111000001101001\r
  Content-Disposition: form-data; name="external_id"\r
  \r
  EXTERNAL_ID\r
  -----011000010111000001101001--\r
  ")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
  	req.Header.Add("content-type", "multipart/form-data; boundary=---011000010111000001101001")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/jobs/users-imports")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("content-type", "multipart/form-data; boundary=---011000010111000001101001")
    .body("-----011000010111000001101001\r
  Content-Disposition: form-data; name="users"; filename="USERS_IMPORT_FILE.json"\r
  Content-Type: text/json\r
  \r
  \r
  -----011000010111000001101001\r
  Content-Disposition: form-data; name="connection_id"\r
  \r
  CONNECTION_ID\r
  -----011000010111000001101001\r
  Content-Disposition: form-data; name="external_id"\r
  \r
  EXTERNAL_ID\r
  -----011000010111000001101001--\r
  ")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/jobs/users-imports',
    headers: {
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'content-type': 'multipart/form-data; boundary=---011000010111000001101001'
    },
    data: '-----011000010111000001101001\r
  Content-Disposition: form-data; name="users"; filename="USERS_IMPORT_FILE.json"\r
  Content-Type: text/json\r
  \r
  \r
  -----011000010111000001101001\r
  Content-Disposition: form-data; name="connection_id"\r
  \r
  CONNECTION_ID\r
  -----011000010111000001101001\r
  Content-Disposition: form-data; name="external_id"\r
  \r
  EXTERNAL_ID\r
  -----011000010111000001101001--\r
  '
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"content-type": @"multipart/form-data; boundary=---011000010111000001101001" };
  NSArray *parameters = @[ @{ @"name": @"users", @"fileName": @"USERS_IMPORT_FILE.json", @"contentType": @"text/json" },
                           @{ @"name": @"connection_id", @"value": @"CONNECTION_ID" },
                           @{ @"name": @"external_id", @"value": @"EXTERNAL_ID" } ];
  NSString *boundary = @"---011000010111000001101001";

  NSError *error;
  NSMutableString *body = [NSMutableString string];
  for (NSDictionary *param in parameters) {
      [body appendFormat:@"--%@\r
  ", boundary];
      if (param[@"fileName"]) {
          [body appendFormat:@"Content-Disposition:form-data; name="%@"; filename="%@"\r
  ", param[@"name"], param[@"fileName"]];
          [body appendFormat:@"Content-Type: %@\r
  \r
  ", param[@"contentType"]];
          [body appendFormat:@"%@", [NSString stringWithContentsOfFile:param[@"fileName"] encoding:NSUTF8StringEncoding error:&error]];
          if (error) {
              NSLog(@"%@", error);
          }
      } else {
          [body appendFormat:@"Content-Disposition:form-data; name="%@"\r
  \r
  ", param[@"name"]];
          [body appendFormat:@"%@", param[@"value"]];
      }
  }
  [body appendFormat:@"\r
  --%@--\r
  ", boundary];
  NSData *postData = [body dataUsingEncoding:NSUTF8StringEncoding];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/jobs/users-imports"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/jobs/users-imports",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "-----011000010111000001101001\r
  Content-Disposition: form-data; name="users"; filename="USERS_IMPORT_FILE.json"\r
  Content-Type: text/json\r
  \r
  \r
  -----011000010111000001101001\r
  Content-Disposition: form-data; name="connection_id"\r
  \r
  CONNECTION_ID\r
  -----011000010111000001101001\r
  Content-Disposition: form-data; name="external_id"\r
  \r
  EXTERNAL_ID\r
  -----011000010111000001101001--\r
  ",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN",
      "content-type: multipart/form-data; boundary=---011000010111000001101001"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "-----011000010111000001101001\r
  Content-Disposition: form-data; name="users"; filename="USERS_IMPORT_FILE.json"\r
  Content-Type: text/json\r
  \r
  \r
  -----011000010111000001101001\r
  Content-Disposition: form-data; name="connection_id"\r
  \r
  CONNECTION_ID\r
  -----011000010111000001101001\r
  Content-Disposition: form-data; name="external_id"\r
  \r
  EXTERNAL_ID\r
  -----011000010111000001101001--\r
  "

  headers = {
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
      'content-type': "multipart/form-data; boundary=---011000010111000001101001"
      }

  conn.request("POST", "/{yourDomain}/api/v2/jobs/users-imports", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/jobs/users-imports")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request["content-type"] = 'multipart/form-data; boundary=---011000010111000001101001'
  request.body = "-----011000010111000001101001\r
  Content-Disposition: form-data; name="users"; filename="USERS_IMPORT_FILE.json"\r
  Content-Type: text/json\r
  \r
  \r
  -----011000010111000001101001\r
  Content-Disposition: form-data; name="connection_id"\r
  \r
  CONNECTION_ID\r
  -----011000010111000001101001\r
  Content-Disposition: form-data; name="external_id"\r
  \r
  EXTERNAL_ID\r
  -----011000010111000001101001--\r
  "

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "content-type": "multipart/form-data; boundary=---011000010111000001101001"
  ]
  let parameters = [
    [
      "name": "users",
      "fileName": "USERS_IMPORT_FILE.json",
      "contentType": "text/json"
    ],
    [
      "name": "connection_id",
      "value": "CONNECTION_ID"
    ],
    [
      "name": "external_id",
      "value": "EXTERNAL_ID"
    ]
  ]

  let boundary = "---011000010111000001101001"

  var body = ""
  var error: NSError? = nil
  for param in parameters {
    let paramName = param["name"]!
    body += "--\(boundary)\r
  "
    body += "Content-Disposition:form-data; name="\(paramName)""
    if let filename = param["fileName"] {
      let contentType = param["content-type"]!
      let fileContent = String(contentsOfFile: filename, encoding: String.Encoding.utf8)
      if (error != nil) {
        print(error)
      }
      body += "; filename="\(filename)"\r
  "
      body += "Content-Type: \(contentType)\r
  \r
  "
      body += fileContent
    } else if let paramValue = param["value"] {
      body += "\r
  \r
  \(paramValue)"
    }
  }

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/jobs/users-imports")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>users</code></td>
      <td>File in JSON format that contains the users to import.</td>
    </tr>

    <tr>
      <td><code>connection\_id</code></td>
      <td>ID of the connection to which users will be inserted. You can retrieve the ID using the <a href="https://auth0.com/docs/api/management/v2#!/Connections/get_connections">GET /api/v2/connections</a> endpoint.</td>
    </tr>

    <tr>
      <td><code>upsert</code></td>
      <td>Boolean value; <code>false</code> by default. When set to <code>false</code>, pre-existing users that match on email address, user ID, phone, or username will fail. When set to true, pre-existing users that match on email address will be updated, but only with upsertable attributes. For a list of user profile fields that can be upserted during import, see <a href="/docs/manage-users/user-accounts/user-profiles/user-profile-structure#user-profile-attributes">User Profile Structure: User profile attributes</a>. Note: Providing a duplicated user entry in the import file will cause an error. In this case, Auth0 will not do an insert followed by an update.</td>
    </tr>

    <tr>
      <td><code>external\_id</code></td>
      <td>Optional user-defined string that can be used to correlate multiple jobs. Returned as part of the job status response.</td>
    </tr>

    <tr>
      <td><code>send\_completion\_email</code></td>
      <td>Boolean value; <code>true</code> by default. When set to <code>true</code>, sends a completion email to all tenant owners when the import job is finished. If you do <em>not</em> want emails sent, you must explicitly set this parameter to <code>false</code>.</td>
    </tr>
  </tbody>
</table>

If the request is successful, you'll receive a response similar to the following:

```json lines theme={null}
{
  "status": "pending",
  "type": "users_import",
  "created_at": "",
  "id": "job_abc123",
  "connection_id": "CONNECTION_ID",
  "upsert": false,
  "external_id": "EXTERNAL_ID",
  "send_completion_email": true
}
```

The returned entity represents the import job.

When the user import job finishes and if `send_completion_email` was set to `true`, the tenant administrator(s) will get an email notifying them that job either failed or succeeded. An email for a job that failed might notify the administrator(s) that it failed to parse the users JSON file when importing users.

### Concurrent import jobs

The [Create Import Users Job](https://auth0.com/docs/api/management/v2#!/Jobs/post_users_imports) endpoint has a limit of two concurrent import jobs. Requesting additional jobs while there are two pending returns a `429 Too Many Requests` response:

```json lines theme={null}
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "There are 2 active import users jobs, please wait until some of them are finished and try again
}
```

## Check job status

To check a job's status, make a `GET` request to the [Get a Job](https://auth0.com/docs/api/management/v2#!/Jobs/get_jobs_by_id) endpoint. Be sure to replace the `MGMT_API_ACCESS_TOKEN` and `JOB_ID` placeholder values with your Management API Access Token and user import job ID.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/jobs/JOB_ID' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'content-type: application/json'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/jobs/JOB_ID");
  var request = new RestRequest(Method.GET);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/jobs/JOB_ID"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("content-type", "application/json")
  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/jobs/JOB_ID")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/jobs/JOB_ID',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/jobs/JOB_ID"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/jobs/JOB_ID",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN"
      }

  conn.request("GET", "/{yourDomain}/api/v2/jobs/JOB_ID", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/jobs/JOB_ID")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN"
  ]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/jobs/JOB_ID")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

Depending on the status of the user import job, you'll receive a response similar to one of the following:

**Pending**

```json lines theme={null}
{
  "status": "pending",
  "type": "users_import",
  "created_at": "",
  "id": "job_abc123",
  "connection_id": "CONNECTION_ID",
  "external_id": "EXTERNAL_ID"
}
```

**Completed**

If a job is completed, the job status response will include totals of successful, failed, inserted, and updated records.

```json lines theme={null}
{
  "status": "completed",
  "type": "users_import",
  "created_at": "",
  "id": "job_abc123",
  "connection_id": "CONNECTION_ID",
  "external_id": "EXTERNAL_ID",
  "summary": {
    "failed": 0,
    "updated": 0,
    "inserted": 1,
    "total": 1
  }
}
```

**Failed**

If there is an error in the job, it will return as failed. However, note that invalid user information, such as an invalid email, will not make the entire job fail.

```json lines theme={null}
{
  "status": "failed",
  "type": "users_import",
  "created_at": "",
  "id": "job_abc123",
  "connection_id": "CONNECTION_ID",
  "external_id": "EXTERNAL_ID",
}
```

To learn details for failed entries see **Retrieve failed entries** below.

## Job timeouts

All user import jobs timeout after **two (2) hours**. If your job does not complete within this time frame, it is marked as failed.

Furthermore, all of your job-related data is automatically deleted after 24 hours and cannot be accessed afterward. As such, **we strongly recommend storing job results using the storage mechanism of your choice**.

## Retrieve failed entries

<Warning>
  All of the job-related data is automatically deleted after 24 hours and cannot be accessed thereafter. Because of this, we strongly recommend storing the job results using the storage mechanism of your choice.
</Warning>

If there were errors in the user import job, you can get the error details by making a `GET` request to the [Get Job Error Details](https://auth0.com/docs/api/management/v2#!/Jobs/get_errors) endpoint. Be sure to replace the `MGMT_API_ACCESS_TOKEN` and `JOB_ID` placeholder values with your Management API Access Token and user import job ID.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/jobs/JOB_ID/errors' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'content-type: application/json'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/jobs/JOB_ID/errors");
  var request = new RestRequest(Method.GET);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/jobs/JOB_ID/errors"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("content-type", "application/json")
  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/jobs/JOB_ID/errors")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/jobs/JOB_ID/errors',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/jobs/JOB_ID/errors"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/jobs/JOB_ID/errors",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN"
      }

  conn.request("GET", "/{yourDomain}/api/v2/jobs/JOB_ID/errors", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/jobs/JOB_ID/errors")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN"
  ]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/jobs/JOB_ID/errors")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

If the request is successful, you'll receive a response similar to the following. Sensitive fields such as `hash.value` will be redacted in the response.

```json lines theme={null}
[
    {
        "user": {
            "email": "test@test.io",
            "user_id": "7af4c65cb0ac6e162f081822422a9dde",
            "custom_password_hash": {
                "algorithm": "ldap",
                "hash": {
                    "value": "*****"
                }
            }
        },
        "errors": [
            {
                "code": "...",
                "message": "...",
                "path": "..."
            }
        ]
    }
]
```

Each error object will include an error code and a message explaining the error in more detail. The possible error codes are:

* ANY\_OF\_MISSING
* ARRAY\_LENGTH\_LONG
* ARRAY\_LENGTH\_SHORT
* CONFLICT
* CONFLICT\_EMAIL
* CONFLICT\_USERNAME
* CONNECTION\_NOT\_FOUND
* DUPLICATED\_USER
* ENUM\_MISMATCH
* FORMAT
* INVALID\_TYPE
* MAX\_LENGTH
* MAXIMUM
* MFA\_FACTORS\_FAILED
* MIN\_LENGTH
* MINIMUM
* NOT\_PASSED
* OBJECT\_REQUIRED
* PATTERN

## Best practices for large-scale migrations

When importing large user populations (requiring 10 or more jobs), follow these recommendations to ensure a successful migration:

### File size and chunking

Split user records into small chunks of less than 400KB per file. This allows for approximately 1,000 users per job with fewer than 10 metadata fields per user, while staying well under the 500KB file size limit.

### Job scheduling and concurrency

Since Auth0 restricts user imports to two concurrent jobs per tenant, use a job scheduler framework (such as [Bull](https://github.com/OptimalBits/bull) or [Agenda](https://github.com/agenda/agenda)) to:

* Schedule import jobs systematically
* Enforce the required concurrency limit
* Track import progress to restart where you left off if interrupted
* Maintain job history and current statuses

### Error handling strategy

* Do not interrupt the import process on single user failures. Import all users and handle issues afterward.
* Implement a "finalizer" job that reviews all spawned jobs and collects failed records into a new file.
* Fix any errors in the collected failed records and import them as a new job.
* Include a retry strategy to handle network connection drops and temporary failures.

### Upsert mode considerations

Use caution when enabling `upsert` mode:

* Imports with upsert are slower than standard imports.
* Upsert mode does not support merging of `user_metadata` or `app_metadata`. The existing metadata will be completely overwritten with new values.
* Only use upsert mode when you need to update existing users and understand these limitations.

### Data retention

Remember that all job-related data is automatically deleted after 24 hours. Store job results and error details using your own storage mechanism for long-term tracking and analysis.

## Learn more

* [Configure Automatic Migration from Your Database](/docs/manage-users/user-migration/configure-automatic-migration-from-your-database)
* [User Import / Export Extension](/docs/manage-users/user-migration/user-import-export-extension)
* [Bulk User Import Database Schema and Examples](/docs/manage-users/user-migration/bulk-user-import-database-schema-and-examples)
* [User Migration Scenarios](/docs/manage-users/user-migration/user-migration-scenarios)


# Configure Automatic Migration from Your Database
Source: https://auth0.com/docs/manage-users/user-migration/configure-automatic-migration-from-your-database

Learn how to enable automatic user migration with your custom database.

Configure your Database connection to automatically migrate your users from an external user store to Auth0 with [custom database action scripts](/docs/authenticate/database-connections/custom-db/templates).

<Warning>
  If you try to use more than one migration method (for example, automatic migration then bulk user import), you may encounter a `DUPLICATED_USER` error. This error indicates that the user exists in Auth0's internal user store but not in your tenant. To correct this error, delete the user with the Auth0 Management API [Delete a Connection User](https://auth0.com/docs/api/management/v2#!/Connections/delete_users_by_email) endpoint and then re-attempt the import.
</Warning>

## Configure Database connection as custom

Create a Database connection, and then set it to custom.

1. Go to [Auth0 Dashboard > Authentication > Database](https://manage.auth0.com/#/connections/database) and select the database to view.
2. Select the **Custom Database** view, and toggle on **Use my own database**.

   <Frame>
     <img alt="Auth0 Dashboard Authentication Database Connection Custom Database Settings Use Own Database Enabled" />
   </Frame>
3. Select the **Settings** view, toggle on **Import Users to Auth0**, and select **Save**.

## Configure Database Action Scripts

Select the **Custom Database** view, and then locate **Database Action Scripts**.

<Frame>
  <img alt="Dashboard Authentication Database Connection Custom Database tab Database Action Scripts" />
</Frame>

### Login

The [Login](/docs/authenticate/database-connections/custom-db/templates/login) script executes each time a user who is not found in the Auth0 attempts to log in. It verifies that the user exists in the external user store without reprompting the user for their password.

### Get User

The [Get User](/docs/authenticate/database-connections/custom-db/templates/get-user) script executes after any of the following scenarios:

* A user initiates signup attempt.
* A user initiates a change password flow.
* A user enters their login identifier when using Identifier First + Biometrics.
* The <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> [Update a User's Email or Username](https://auth0.com/docs/api/v2#!/Users/patch_users_by_id) or [Create User](https://auth0.com/docs/api/management/v2#!/Users/post_users) endpoint is called.

If a user who has not been migrated confirms a password change and logs in successfully, their user profile will be created in the Auth0 with the new password. This user profile contains all the data returned in the Get User script. All subsequent logins for this user will be performed directly in Auth0.

## Verify user migration is complete

Verify that all users have been migrated to the Auth0 user store using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the Auth0 Management API.

1. Go to [Auth0 Dashboard > User Management > Users](https://manage.auth0.com/#/users), and review the list of users.
2. Use the Management API [List or Search Users](https://auth0.com/docs/api/v2#!/Users/get_users) endpoint.

## Disconnect external user store

Reconfigure the Database Action Scripts as no operation functions. This will prevent Auth0 from reaching out to your external user store to authenticate users.

<Callout icon="file-lines">
  Make sure to leave the **Import Users to Auth0** option turned on. If you turn this option off Auth0 will only use the scripts to authenticate and perform other user actions instead of using the users that were imported locally.
</Callout>

1. Go to [Auth0 Dashboard > Authentication > Database](https://manage.auth0.com/#/connections/database), and then select your Database connection.

2. Switch to the **Custom Database** view, and then locate **Database Action Scripts.**

3. Update the **Login** script.

   ```javascript lines theme={null}
   function login (email, password, callback) {
     return callback(null, null);
   }
   ```

4. Update the **Get User** script.

   ```javascript lines theme={null}
   function getByEmail (email, callback) {
     return callback(null, null);
   }
   ```

## Troubleshoot user migration issues

If you encounter any issues with automatic migration, first read [Custom Database Connection and Action Script Best Practices](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts).

### User already exists

The most common scenarios when you may encounter this issue:

* You delete a user from your Database connection and then try to recreate the user.
* You attempt to create a new user on your Database connection when the user already exists in your external user store.
* A user's migration process was interrupted.

During the user migration process, Auth0 first creates a partial user profile in an internal user store, and then creates a full user profile on your Database connection. If an issue occurs that prevents this full user profile from being created, you may encounter the `The user already exists` error.

You can usually resolve this issue by deleting the user from the Database connection, deleting the user from the internal user store, and then reattempting the migration process.

1. Check the `console.log()` statements with the [Actions Real-time Logs](/docs/customize/actions/actions-real-time-logs).
2. Delete the user with the Management API [Delete a User](https://auth0.com/docs/api/management/v2#!/Users/delete_users_by_id) endpoint.
3. Delete the user with the Management API [Delete a Connection User](https://auth0.com/docs/api/management/v2#!/Connections/delete_users_by_email) endpoint.
4. Instruct the user to log in or change their password to reattempt migration.

### Missing metadata

If a user is interrupted during the login or change password flow that initiates the migration process, Auth0 may not be able to transfer their metadata (`user_metadata` or `app_metadata`) along with their other profile data.

You can mitigate this scenario by creating an [Action](/docs/customize/actions) that verifies the user's profile is missing metadata, retrieves it from the external use store, and then stores it in Auth0.

## Learn more

* [Bulk User Imports](/docs/manage-users/user-migration/bulk-user-imports)
* [User Import / Export Extension](/docs/manage-users/user-migration/user-import-export-extension)


# User Import / Export Extension
Source: https://auth0.com/docs/manage-users/user-migration/user-import-export-extension

Learn about the User Import/Export extension, which allows you to import and export users from or to any database you have configured in your account.

<Warning>
  The **User Import/Export Extension** will be deprecated in September 2025. You can access the same features now available [directly in the Auth0 Management Dashboard](/docs/manage-users/user-migration/bulk-user-import-export).
</Warning>

The **User Import / Export Extension** allows you to:

* Bulk import your existing database users into Auth0
* Search for and export some (or all) of your Auth0 database users

For a list of user profile fields that can be imported and exported, see [User Profile Attributes](/docs/manage-users/user-accounts/user-profiles/user-profile-structure).

You must be a Dashboard Admin to use this extension.

## Install the extension

To install this extension, go to [Auth0 Dashboard > Extensions](https://manage.auth0.com/#/extensions), and select **User Import / Export**.

The extension does not require any additional configuration before it can be installed, so select **Install** in the informational pop-up window to proceed.

## Use the extension

After you've installed your extension, you'll see it listed in your list of installed extensions. Click on **Import / Export Extension** to launch.

You'll be asked to grant permission for the extension to access your Auth0 account for the listed activities the first time you launch the extension.

<Frame>
  <img alt="Dashboard Extensions Authorize the Users Import/Export Extension" />
</Frame>

Click the **check mark** to proceed.

There are two ways of using this extension:

* Bulk import your existing database users into Auth0
* Search for and export some (or all) of your Auth0 database users

Both use cases are explained in further detail below.

### Import users

By default, any time you open the extension, you'll see the **User Import** screen (if you're on the export screen, you can return to this screen by click **Import** in the left-hand navigation bar).

To import your users, drag and drop a valid JSON file ([schema and examples here](/docs/manage-users/user-migration/bulk-user-import-database-schema-and-examples)) onto the area that says **Drop your file here, or click to select**. Alternatively, you can click on this area to browse your files and select the appropriate JSON file. The JSON file should contain the list of users that you are planning to import.

<Callout icon="file-lines">
  If you are using an export file from an Auth0 tenant, you must convert the exported file from `ndjson` to [JSON](/docs/manage-users/user-migration/bulk-user-exports#json-compatible-format). To keep the same user IDs, you must remove the `auth0| prefix` from all imported user IDs.

  The import process automatically adds the `auth0| prefix` to the imported user IDs. If you do not remove the `auth0|` prefix before importing, the user IDs return as `auth0|auth0|...`
</Callout>

Select the database connection for which your users will be imported. Please make sure that the connection you choose has been enabled for at least one application.

Click **Start Importing Users** to begin the import process.

When done, you'll see the following **Completed** message.

<Frame>
  <img alt="Dashboard Extensions Users Import Export Import Complete" />
</Frame>

Once you've imported your users, you can manage them individually using [Auth0 Dashboard > User Management > Users](https://manage.auth0.com/#/users).

### Export users

<Callout icon="file-lines">
  Auth0 uses the ndjson format due to the large size of export files. Before you can import users, you'll need to convert from **ndjson** to **json** using the library of your choice (such as [jq](https://stedolan.github.io/jq/)). When exporting users intended to later be imported, user field names should be left as their defaults and not mapped to a Column Name.
</Callout>

To export your existing Auth0 users associated with database connections, select **Export**.

<Frame>
  <img alt="Dashboard Extensions Users Import Export Export Users page" />
</Frame>

Under **User Fields**, you can decide which user attributes or expressions should be included in the export. The user attribute can be a static value like `user.user_metadata.name`, or it can be a JavaScript expression like `user.user_metadata.name || user.name`. Expressions will be evaluated during the export runtime. The **column name** value is how the value will be represented in the export.

You can click the **Add Default Fields** button to automatically select the default fields and populate their column names (this is also a good way for you to visualize how parameters/expressions will appear).

You can remove extraneous attributes/expressions by clicking on its associated **trash can** icon.

Under **Settings**, you can:

* Configure how your exported users are listed by providing a **User Attribute** by which users should be sorted (as well as whether the users should be sorted in ascending or descending order)
* Choose your **Export Format**; you can choose between JSON and CSV files

  <Frame>
    <img alt="Dashboard Extensions Users Import Export Settings Export Format" />
  </Frame>

When you're ready, click **Export X Users** (where `X` is the number of users you're exporting).

You can download the file containing your users when the export is complete; you may need to use a third-party extraction tool if you run Windows 10 or lower.

## Update Users

The Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> allows bulk user profile updates to `user_metadata` and `app_metadata` with the User Import/Export Extension.

<Callout icon="file-lines">
  Auth0 does not currently support bulk import for Passwordless. Use [Auth0 Management API](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id) to update users individually.
</Callout>

### Export users

Using the [export process above](/docs/customize/extensions/user-import-export-extension#export-users), create a complete export file including all your user attributes.

Choose the JSON format for your export.

Download the file containing your users when the export is complete.

### Update your configuration

Make a **copy** of the JSON file you downloaded in the previous step.

<Warning>
  This process can result in data loss. Create a backup of your user database in the event of data corruption.
</Warning>

Open the copy of the JSON file in a text editor. Your user schema should be similar to the one below:

```json lines expandable theme={null}
[
   {
      "Id":"auth0|626737a9813c000069daf462",
      "Nickname":"testuser1",
      "Name":"testuser1@auth0.com",
      "email":"testuser1@auth0.com",
      "Connection":"Username-Password-Authentication",
      "Created At":"2022-04-26T00:07:05.098Z",
      "Updated At":"2022-07-06T14:54:19.214Z"
   },
   {
      "Id":"auth0|62d1a1853bdcf11ff5dca672",
      "Nickname":"testuser2",
      "Name":"testuser2@auth0.com",
      "email":"testuser2@auth0.com",
      "Connection":"Username-Password-Authentication",
      "Created At":"2022-07-15T17:19:01.531Z",
      "Updated At":"2022-07-15T17:19:01.532Z"
   },
   {
      "Id":"auth0|62d1a1a524f32a4185c9ce23",
      "Nickname":"testuser3",
      "Name":"testuser3@auth0.com",
      "email":"testuser3@auth0.com",
      "Connection":"Username-Password-Authentication",
      "Created At":"2022-07-15T17:19:33.484Z",
      "Updated At":"2022-07-15T17:19:33.484Z"
   }
]
```

Do not change the user email address because it is the lookup key for users in the database.

<Callout icon="file-lines">
  The Id must have a unique `connection|id`. If the same user Id exists in multiple connections, your update will fail.
</Callout>

To add an attribute, create a new field in each user schema and update with a value. In the example below, the "Family Name" attribute has a value of "Smith" with a comma after the new attribute value.

You can also add the `email_verified` attribute to multiple users and set the value to `true`.

```json lines theme={null}
{
   "Id":"auth0|626737a9813c000069daf462",
   "Nickname":"testuser1",
   "Family Name":"Smith",
   "Name":"testuser1@auth0.com",
   "email":"testuser1@auth0.com",
   "email_verified":true,
   "Connection":"Username-Password-Authentication",
   "Created At":"2022-04-26T00:07:05.098Z",
   "Updated At":"2022-07-06T14:54:19.214Z"
}
```

Save the changes to your user file.

<Callout icon="file-lines">
  This process cannot block multiple users. You must block users individually in the Auth0 Dashboard or with the [Auth0 Management API](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id).
</Callout>

### Import updated user profile data

The `users-import` endpoint allows you to upload your updated user profile file and update several users in one job. Navigate to the [Create import users job endpoint](https://auth0.com/docs/api/management/v2/#!/Jobs/post_users_imports).

Add your user file to the users parameter and add the database connection ID of the database you want to update.

The upsert value should be `true` to update the already existing user information.
To add your updates, select **Try** or use Postman to import the users.

Use the `job_id` to verify the status with the `jobs` [endpoint](https://auth0.com/docs/api/management/v2/#!/Jobs/get_jobs_by_id).


# User Migration Scenarios
Source: https://auth0.com/docs/manage-users/user-migration/user-migration-scenarios

User migrations scenarios from various platforms using multiple methods.

Here are some sample scenarios for migrating users from Gigya, Okta, and Stormpath to Auth0. Each of these scenarios assumes that you have accounts on those platforms.

## Prerequisites

Configure the [custom database connection](/docs/authenticate/database-connections/custom-db).

1. Create a new database connection at [Dashboard > Authentication > Database](https://manage.auth0.com/#/connections/database). Be sure to select the **Custom Database** view, and enable the **Use my own database** switch.
2. Connect the database to the application: In your database connection settings, select the **Applications** view. Locate the **Applications Using This Connection** section, and enable the database connection for each application.

## Scenario 1: Migrate Users from Gigya to Auth0

1. Export Gigya users:
   Use [Gigya's IdentitySync](https://help.sap.com/docs/SAP_CUSTOMER_DATA_CLOUD/8b8d6fffe113457094a17701f63e3d6a/2b717202e42a4165aa7f75f7eecab64f.html) to transform and export user data to match a target schema. To learn more about this process, see [Gigya IdentitySync: Using IdentitySync](https://help.sap.com/docs/SAP_CUSTOMER_DATA_CLOUD/8b8d6fffe113457094a17701f63e3d6a/2b717202e42a4165aa7f75f7eecab64f.html?locale=en-US).<br /><br />

   Follow the instructions to transform your Gigya database's user data to the correct [schema](/docs/manage-users/user-migration/bulk-user-import-database-schema-and-examples) and export the transformed data to JSON format.
2. Import your Gigya users into Auth0:
   You can import users with either the [User Import/Export Extension](/docs/manage-users/user-migration/user-import-export-extension) or the [Management API](https://auth0.com/docs/api/management/v2).

   * **User Import/Export Extension**: Go to [Auth0 Dashboard > Extensions](https://manage.auth0.com/#/extensions), select the **User Import / Export** extension, and install it. Once the extension is installed, you can click it to open an import/export interface.<br /><br />

     Drag your exported Gigya users JSON file into the designated upload area, and select the database you created earlier. Select **Start Importing Users** to begin your import. To learn more, see [User Import/Export Extension](/docs/manage-users/user-migration/user-import-export-extension).
   * **Management API**: [Create a job](https://auth0.com/docs/api/management/v2#!/Jobs/post_users_imports) to import your users to Auth0. For detailed instructions, read [Bulk User Imports](/docs/manage-users/user-migration/bulk-user-imports).

## Scenario 2: Migrate Users from Okta to Auth0

1. Enable importing users: Go to [Auth0 Dashboard > Authentication > Database](https://manage.auth0.com/#/connections/database) and select your database connection. In its **Settings**, enable the **Import Users to Auth0** option.
2. Create the [Login script](/docs/authenticate/database-connections/custom-db/templates/login): The **Login** script is executed when a user attempts to log in, but their account is not found in the Auth0 database. You must create a script that will call the Okta [Primary Authentication](https://developer.okta.com/docs/api/resources/authn.html#primary-authentication) endpoint, passing the email and password as the `username` and `password` parameters.
   On successful authentication, Okta will return an [Authentication Transaction object](https://developer.okta.com/docs/api/resources/authn.html#authentication-transaction-model), containing the [user's profile](https://developer.okta.com/docs/api/resources/authn.html#user-profile-object) in the [embedded resources](https://developer.okta.com/docs/api/resources/authn.html#embedded-resources). You can then extract the user's information and pass it to Auth0 in the callback function.<br /><br />

   In your database connection's **Custom Database** view, locate **Database Action Scripts**, and select **Login**.

   ```javascript lines expandable theme={null}
   function login (email, password, callback) {
     // Replace {yourOktaDomain} with your own Okta domain
     var url = 'https:/{yourOktaDomain}/api/v1/authn';

     // Make the POST request to authenticate a user
     request({
       url: url,
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
         'Accept': 'application/json'
       },
       body: {
         username: email,
         password: password,
         options: {
           multiOptionalFactorEnroll: false,
           warnBeforePasswordExpired: false
         }
       },
       json: true
     }, function (error, response, body) {
       // Ensure we have a successful response
       if (response.statusCode !== 200) return callback();

       // Get the user from the response body
       var user = body._embedded.user;

       // Set the data we want to store in Auth0 and migrate the user
       return callback(null, {
           user_id : user.id,
           username: user.profile.login,
           email: user.profile.login,
           // We set the users email_verified to true as we assume if they were a valid
           // user in Okta, they have already verified their email
           // If this field is not set, the user will get an email asking them to verify
           // their account
           email_verified: true,
           name: user.profile.firstName + ' ' + user.profile.lastName
         });
     });
   }
   ```

   Click the **Try** button above the script to test whether the script works.
3. Create the [Get User script](/docs/authenticate/database-connections/custom-db/templates/get-user): The **Get User** script is executed when the user attempts to reset their password but their account is not found in the Auth0 database. You will need to create a script that calls the Okta [Get User with Login](https://developer.okta.com/docs/api/resources/users.html#get-user-with-login) endpoint, passing the user's email as the `login` parameter.
   You will also need to [Create an API token](https://developer.okta.com/docs/api/getting_started/getting_a_token.html) which must be passed to this endpoint in the `Authorization` header.
   If successful, Okta will return a [User object](https://developer.okta.com/docs/api/resources/users.html#user-model) with the user's information. Once again, you can extract the user's information and pass it to Auth0 in the callback function.<br /><br />

   In your database connection's **Custom Database** view, locate **Database Action Scripts**, and select **Get User**.

   ```javascript lines expandable theme={null}
   function getByEmail(email, callback) {
     // Replace {yourOktaDomain} with your own Okta domain
     var url = 'https://{yourOktaDomain}/api/v1/users/' + encodeURIComponent(email);

     // Make a GET request to find a user by email
     // Replace {yourOktaApiToken} with an Okta API Token 
     // (see https://developer.okta.com/docs/api/getting_started/getting_a_token.html) 
     request({
       url: url,
       method: 'GET',
       headers: {
         'Content-Type': 'application/json',
         'Accept': 'application/json',
         'Authorization': 'SSWS ' + '{yourOktaApiToken}'
       },
       json: true
     }, function (error, response, body) {
       // Ensure we have a successful response
       if (response.statusCode !== 200) return callback();

       // Set the data we want to store in Auth0 and migrate the user
       return callback(null, {
         user_id: body.id,
         username: body.profile.login,
         email: body.profile.login,
         email_verified: true,
         name: body.profile.firstName + ' ' + body.profile.lastName
       });
     });
   }
   ```

   Click the **Try** button above the script to test whether the script works.
4. Test the custom database connection: Click **Try connection**. The [Auth0 Lock widget](/docs/libraries/lock) will appear. Enter the email address and password for the Okta user, and click **Log In.** You should see a web page indicating that the connection works, with information about the user.
5. To see the newly imported users, go to [Auth0 Dashboard > User Management > Users](https://manage.auth0.com/#/users).

## Scenario 3: Migrate users from Stormpath to Auth0

1. Enable importing users: Go to [Auth0 Dashboard > Authentication > Database](https://manage.auth0.com/#/connections/database) and select your database connection. In its **Settings**, enable the **Import Users to Auth0** option.
2. Enable applications for your connection: Select the **Applications** view. Enable the applications that will use the database connection.
3. Create the [Login script](/docs/authenticate/database-connections/custom-db/templates/login): The **Login** script is executed when a user attempts to log in, but their account is not found in the Auth0 database. You will need to create a script that calls Stormpath's API to authenticate the user, passing the user credentials as the `username` and `password` parameters.<br /><br />

   On successful authentication, the response from Stormpath will include the user account URL. Perform a second request to the account URL to retrieve the user's information. You can then extract the user's information and pass it to Auth0 in the callback function.

   ```javascript lines expandable theme={null}
   function login(username, password, callback) {
     // Replace the {yourStormpathClientId} attribute with your Stormpath ID
     var url = 'https://api.stormpath.com/v1/applications/{yourStormpathClientId}/loginAttempts';

     // Stormpath requires the user credentials be passed in as a base64 encoded message
     var message = username + ':' + password;
     var pass = new Buffer(message).toString('base64');

     // Here we are making the POST request to authenticate a user
     request({
       url: url,
       method: 'POST',
       auth: {
         // Your API Client ID
         user: '{yourStormpathClientId}',
         // Your API Client Secret
         password: '{yourStormpathClientSecret}'
       },
       headers: {
         'Content-Type': 'application/json'
       },
       json: {
         type: 'basic',
         // Passing in the base64 encoded credentials
         value: pass
       }
     }, function (error, response, body) {
       // If response is successful we'll continue
       if (response.statusCode !== 200) return callback();
       // A successful response will return a URL to get the user information
       var accountUrl = body.account.href;

       // We'll make a second request to get the user info. This time it will be a GET request
       request({
         url: accountUrl,
         method: 'GET',
         auth: {
           // Your API Client ID
           user: '{yourStormpathClientId}',
           // YOUR API Client Secret
           password: '{yourStormpathClientSecret}'
         }
       }, function (errorUserInfo, responseUserInfo, bodyUserInfo) {
         // If we get a successful response, we'll process it
         if (responseUserInfo.statusCode !== 200) return callback();

         var parsedBody = JSON.parse(bodyUserInfo);
         // To get the user identifier, we'll strip out the Stormpath API
         var id = parsedBody.href.replace('https://api.stormpath.com/v1/accounts/', '');

         // Finally, we'll set the data we want to store in Auth0 and migrate the user
         return callback(null, {
           user_id : id,
           username: parsedBody.username,
           email: parsedBody.email,
           // We set the users email_verified to true as we assume if they were a valid
           // user in Stormpath, they have already verified their email
           // If this field is not set, the user will get an email asking them to verify
           // their account
           email_verified: true,
           // Add any additional fields you would like to carry over from Stormpath
         });
       });
     });
   }
   ```

   Click the **Try** button above the script to test and see whether the script works.
4. Create the [Get User script](/docs/authenticate/database-connections/custom-db/templates/get-user): The **Get User** script is executed when the user attempts to do a password reset but their account is not found in the Auth0 database. You will need to create a script that will call the `/accounts` endpoint of the Stormpath API, passing the user's email as the `email` parameter.
   If successful, Stormpath will return the user's information. You can extract the user's information and pass it to Auth0 in the callback function.

   ```javascript lines expandable theme={null}
   function getByEmail(email, callback) {
     // Replace the {yourStormpathClientId} attribute with your Stormpath ID
     var url = 'https://api.stormpath.com/v1/applications/{yourStormpathClientId}/accounts';

     request({
       url: url,
       method: 'GET',
       auth: {
         // Your API Client ID
         user: '{yourStormpathClientId}',
         // YOUR API Client Secret
         password: '{yourStormpathClientSecret}'
       },
       qs: { q: email }
     }, function (error, response, body) {
       if (response.statusCode !== 200) return callback();

       var parsedBody = JSON.parse(body);
       var user = parsedBody.items[0];

       if (!user) return callback();

       var id = user.href.replace('https://api.stormpath.com/v1/accounts/', '');

       return callback(null, {
         user_id: id,
         username: user.username,
         email: user.email,
         email_verified: true,
         // Add any additional fields you would like to carry over from Stormpath
       });
     });
   }
   ```

   Click the **Try** button above the script to test and see whether the script works.
5. Test the custom database connection: Click **Try connection**. The [Auth0 Lock widget](/docs/libraries/lock) will appear. Enter the email address and password for the Stormpath user, and click **Log In.** You should see a web page indicating that the connection works, with information about the user.
6. To see the newly imported users, go to [Dashboard > User Management > Users](https://manage.auth0.com/#/users).


# Search for Users
Source: https://auth0.com/docs/manage-users/user-search

Understand how the Auth0 Management API search endpoints allow you to search for and retrieve user profiles.

User search allows you to retrieve user profile details using Auth0's [Management API](https://auth0.com/docs/api/management/v2). Search results can be [viewed](/docs/manage-users/user-search/view-search-results-by-page), [sorted](/docs/manage-users/user-search/sort-search-results), and [exported](/docs/manage-users/user-migration/bulk-user-exports).

Most user profile fields are not returned as part of an [ID Token](/docs/secure/tokens/id-tokens), nor are they included in the response from the [`/userinfo` endpoint](https://auth0.com/docs/api/authentication#get-user-info) of the Authentication API.

When searching for users in Auth0, you can use multiple endpoints to search for ID, email, or other criteria:

## Search Result Terminology

We use the following terms to describe the user search results:

* **Eventually consistent**: Search results may not reflect a recently-completed write operation. However, if you repeat your request after a short period of time, the response will return up-to-date data.
* **Immediately consistent**: Search results will reflect the results of all successful write operations, including those that occurred shortly prior to your request.

## Learn more

* [User Search Query Syntax](/docs/manage-users/user-search/user-search-query-syntax)
* [Retrieve Users with the Get Users Endpoint](/docs/manage-users/user-search/retrieve-users-with-get-users-endpoint)
* [Sort Search Results](/docs/manage-users/user-search/sort-search-results)


# Retrieve Users with Get Users by Email Endpoint
Source: https://auth0.com/docs/manage-users/user-search/retrieve-users-with-get-users-by-email-endpoint

Learn how to retrieve lists of users using the get-users-by-email endpoint.

The [`GET /api/v2/users-by-email` endpoint](https://auth0.com/docs/api/management/v2#!/Users_By_Email/get_users_by_email) allows you to search for users using their email addresses. The search looks for an exact match to the provided email address and is case-sensitive.

This endpoint is **immediately consistent**, and as such, we recommend that you use this endpoint for:

* User searches run during the authentication process.
* User searches run as part of the account linking process.

The request must include a [Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens).

## Request example

Required Scopes: `read:users`

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/users-by-email?email=%7BuserEmailAddress%7D' \
    --header 'authorization: Bearer {yourMgmtApiAccessToken}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users-by-email?email=%7BuserEmailAddress%7D");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users-by-email?email=%7BuserEmailAddress%7D"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/users-by-email?email=%7BuserEmailAddress%7D")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/users-by-email',
    params: {email: '{userEmailAddress}'},
    headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users-by-email?email=%7BuserEmailAddress%7D"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users-by-email?email=%7BuserEmailAddress%7D",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" }

  conn.request("GET", "/{yourDomain}/api/v2/users-by-email?email=%7BuserEmailAddress%7D", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users-by-email?email=%7BuserEmailAddress%7D")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users-by-email?email=%7BuserEmailAddress%7D")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

```json lines expandable theme={null}
[
  {
    "email": "john.doe@gmail.com",
    "email_verified": false,
    "username": "johndoe",
    "phone_number": "+199999999999999",
    "phone_verified": false,
    "user_id": "usr_5457edea1b8f33391a000004",
    "created_at": "",
    "updated_at": "",
    "identities": [
      {
        "connection": "Initial-Connection",
        "user_id": "5457edea1b8f22891a000004",
        "provider": "auth0",
        "isSocial": false
      }
    ],
    "app_metadata": {},
    "user_metadata": {},
    "picture": "",
    "name": "",
    "nickname": "",
    "multifactor": [
      ""
    ],
    "last_ip": "",
    "last_login": "",
    "logins_count": 0,
    "blocked": false,
    "given_name": "",
    "family_name": ""
  }
]
```


# Retrieve Users with the Get Users by ID Endpoint
Source: https://auth0.com/docs/manage-users/user-search/retrieve-users-with-get-users-by-id-endpoint

Learn how to retrieve lists of users using the get-users-by-id endpoint.

The [`GET /api/v2/users/{id}` endpoint](https://auth0.com/docs/api/management/v2#!/Users/get_users_by_id) allows you to retrieve a specific user using their Auth0 user ID.

This endpoint is **immediately consistent**, and as such, we recommend that you use this endpoint for:

* User searches run during the authentication process.
* User searches run as part of the account linking process.

The user ID should be URL encoded since it may contain characters that do not work well in a URL.

The request must include a [Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens).

## Request example

Required Scopes: `read:users`

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/users/%7BuserId%7D' \
    --header 'authorization: Bearer {yourMgmtApiAccessToken}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/%7BuserId%7D");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users/%7BuserId%7D"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/users/%7BuserId%7D")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/users/%7BuserId%7D',
    headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/%7BuserId%7D"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/%7BuserId%7D",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" }

  conn.request("GET", "/{yourDomain}/api/v2/users/%7BuserId%7D", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/%7BuserId%7D")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/%7BuserId%7D")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

```json lines expandable theme={null}
{
  "email": "john.doe@gmail.com",
  "email_verified": false,
  "username": "johndoe",
  "phone_number": "+199999999999999",
  "phone_verified": false,
  "user_id": "usr_5457edea1b8f33391a000004",
  "created_at": "",
  "updated_at": "",
  "identities": [
    {
      "connection": "Initial-Connection",
      "user_id": "5457edea1b8f22891a000004",
      "provider": "auth0",
      "isSocial": false
    }
  ],
  "app_metadata": {},
  "user_metadata": {},
  "picture": "",
  "name": "",
  "nickname": "",
  "multifactor": [
    ""
  ],
  "last_ip": "",
  "last_login": "",
  "logins_count": 0,
  "blocked": false,
  "given_name": "",
  "family_name": ""
}
```


# Retrieve Users with the Get Users Endpoint
Source: https://auth0.com/docs/manage-users/user-search/retrieve-users-with-get-users-endpoint

Learn how to retrieve lists of users using the get_users endpoint.

The [`GET /api/v2/users` endpoint](https://auth0.com/docs/api/management/v2#!/Users/get_users) allows you to retrieve a list of users. Using this endpoint, you can:

* Search based on a variety of criteria
* Select the fields to be returned
* Sort the returned results

This endpoint is **eventually consistent**, and as such, we recommend that you use this endpoint for back office processes such as changing the display name of an existing user.

## Request example

To search for users, make a `GET` request to the [`/api/v2/users` endpoint](https://auth0.com/docs/api/management/v2#!/Users/get_users). The request must include a [Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens). Pass your search query to the `q` parameter and set the `search_engine` parameter to `v3`.

For example, to search for a user whose email is exactly `jane@exampleco.com`, use `q=email:"jane@exampleco.com"`:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3' \
    --header 'authorization: Bearer {yourMgmtApiAccessToken}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/users',
    params: {q: 'email:"jane@exampleco.com"', search_engine: 'v3'},
    headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" }

  conn.request("GET", "/{yourDomain}/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users?q=email%3A%22jane%40exampleco.com%22&search_engine=v3")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

If successful, you'll receive a response like this:

```json lines expandable theme={null}
[
  {
    "email": "jane@exampleco.com",
    "email_verified": false,
    "username": "janedoe",
    "phone_number": "+199999999999999",
    "phone_verified": false,
    "user_id": "auth0|5457edea1b8f22891a000004",
    "created_at": "",
    "updated_at": "",
    "identities": [
      {
        "connection": "Initial-Connection",
        "user_id": "5457edea1b8f22891a000004",
        "provider": "auth0",
        "isSocial": false
      }
    ],
    "app_metadata": {},
    "user_metadata": {},
    "picture": "",
    "name": "",
    "nickname": "",
    "multifactor": [
      ""
    ],
    "last_ip": "",
    "last_login": "",
    "logins_count": 0,
    "blocked": false,
    "given_name": "",
    "family_name": ""
  }
]
```

## Query examples

Below are some examples of the kinds of queries you can make with the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

<table>
  <thead>
    <tr>
      <th>Use case</th>
      <th>Query</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Search for all users whose name contains "john"</td>
      <td><code>name:\*john\*</code></td>
    </tr>

    <tr>
      <td>Search all users whose name is exactly "jane"</td>
      <td><code>name:"jane"</code></td>
    </tr>

    <tr>
      <td>Search for all user names starting with "john"</td>
      <td><code>name:john\*</code></td>
    </tr>

    <tr>
      <td>Search for user names that start with "jane" and end with "smith"</td>
      <td><code>name:jane\*smith</code></td>
    </tr>

    <tr>
      <td>Search for all users whose email is exactly "[john@exampleco.com](mailto:john@exampleco.com)"</td>
      <td><code>email:"[john@exampleco.com](mailto:john@exampleco.com)"</code></td>
    </tr>

    <tr>
      <td>Search for all users whose email is exactly "[john@exampleco.com](mailto:john@exampleco.com)" or "[jane@exampleco.com](mailto:jane@exampleco.com)" using <code>OR</code></td>
      <td><code>email:("[john@exampleco.com](mailto:john@exampleco.com)" OR "[jane@exampleco.com](mailto:jane@exampleco.com)")</code></td>
    </tr>

    <tr>
      <td>Search for users without verified email</td>
      <td><code>email\_verified:false OR NOT \_exists\_:email\_verified</code></td>
    </tr>

    <tr>
      <td>Search for users who have the <code>user\_metadata</code> field named <code>full\_name</code> with the value of "John Smith"</td>
      <td><code>user\_metadata.full\_name:"John Smith"</code></td>
    </tr>

    <tr>
      <td>Search for users from a specific connection</td>
      <td><code>identities.connection:"google-oauth2"</code></td>
    </tr>

    <tr>
      <td>Search for all users that have never logged in</td>
      <td><code>(NOT \_exists\_:logins\_count OR logins\_count:0)</code></td>
    </tr>

    <tr>
      <td>Search for all users who logged in before 2018</td>
      <td><code>last\_login:\[\* TO 2017-12-31]</code></td>
    </tr>

    <tr>
      <td>Search for all users whose last login was in December 2017</td>
      <td><code>last\_login:\[2017-11 TO 2017-12]</code>, <code>last\_login:\[2017-12-01 TO 2017-12-31]</code></td>
    </tr>

    <tr>
      <td>Search for all users with logins count >= 100 and \<= 200</td>
      <td><code>logins\_count:\[100 TO 200]</code></td>
    </tr>

    <tr>
      <td>Search for all users with logins count >= 100</td>
      <td><code>logins\_count:\[100 TO \*]</code></td>
    </tr>

    <tr>
      <td>Search for all users with logins count > 100 and \< 200</td>
      <td><code>logins\_count:\{100 TO 200}</code></td>
    </tr>

    <tr>
      <td>Search for all users whose email domain is "exampleco.com"</td>
      <td><code>email.domain:"exampleco.com"</code></td>
    </tr>
  </tbody>
</table>

## Limitations

* The endpoint returns a maximum of 50 users, even if more users match your query.
* If you need to return more than 50 users, use the `page` parameter to show more pages of results. Each page contains 50 users. For example, you can specify `&page=2` to show results 51-100, specify `&page=3` to show results 101-150, and so on. However, this endpoint never returns a total of more than 1000 users with the same search criteria, even with paging.
* There is a 1 MB per-user limit on user data that can be indexed, queried, and returned by the [user search endpoint](https://auth0.com/docs/api/management/v2/users/get-users). For more information on how this affects custom metadata larger than 1MB, see [Metadata Field Names and Data Types](/docs/manage-users/user-accounts/metadata/metadata-fields-data#size-limits-and-storage). The [get user endpoint](https://auth0.com/docs/api/management/v2/users/get-users-by-id) must be used to retrieve all user attributes for oversized user profiles.
* By default, the `GET /api/v2/users` endpoint returns results in a deterministic order so the same query yields the same logically ordered results each time. This behavior is controlled by the `primary_order` query parameter:

  * `primary_order=true` (default): results across identical queries are consistently ordered.
  * `primary_order=false`: results are returned in a non-deterministic order, which can enhance performance for complex queries.
* If your application does not require consistent ordering of search results and your queries are short enough not to rely on pagination, set `primary_order=false` to improve query performance.
* If you need a complete export of all of your users, use the [export job](https://auth0.com/docs/api/management/v2#!/Jobs/post_users_exports) or the [User Import / Export](/docs/customize/extensions/user-import-export-extension) extension.
* If you get the error `414 Request-URI Too Large` this means that your query string is larger than the supported length. In this case, refine your search.

We do **not** recommend that you use this endpoint for:

* Operations that require immediate consistency. Instead, use the [Get Users by Email endpoint](/docs/manage-users/user-search/retrieve-users-with-get-users-by-email-endpoint) or the [Get Users by ID endpoint](/docs/manage-users/user-search/retrieve-users-with-get-users-by-id-endpoint).
* User exports. Instead, use the [User Export endpoint](/docs/manage-users/user-migration/bulk-user-exports).
* Operations that require user search as part of authentication processes. Instead, use the Get Users by Email endpoint or the Get Users by ID endpoint.
* Searching for Users for [Account Linking](/docs/manage-users/user-accounts/user-account-linking) by Email. Instead, use the Get Users by Email endpoint.

## Learn more

* [User Search Query Syntax](/docs/manage-users/user-search/user-search-query-syntax)
* [Sort Search Results](/docs/manage-users/user-search/sort-search-results)
* [View Search Results by Page](/docs/manage-users/user-search/view-search-results-by-page)
* [Bulk User Exports](/docs/manage-users/user-migration/bulk-user-exports)
* [Check API Calls](/docs/troubleshoot/authentication-issues/check-api-calls)


# Sort Search Results
Source: https://auth0.com/docs/manage-users/user-search/sort-search-results

Learn how to sort search results by passing a field:order value to the sort parameter.

To sort user search results, pass a `field:order` value to the `sort` parameter when making your request. The `field` is the name of the field to sort by, while order can be set to `1` for ascending order and `-1` for descending.

Sorting by `app_metadata` or `user_metadata` is not supported.

For example, to sort users in ascending order by the `created_at` field you can pass the value `created_at:1` to the `sort` parameter:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/users?q=logins_count%3A%5B100%20TO%20200%5D&sort=created_at%3A1&search_engine=v3' \
    --header 'authorization: Bearer {yourMgmtApiAccessToken}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users?q=logins_count%3A%5B100%20TO%20200%5D&sort=created_at%3A1&search_engine=v3");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users?q=logins_count%3A%5B100%20TO%20200%5D&sort=created_at%3A1&search_engine=v3"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/users?q=logins_count%3A%5B100%20TO%20200%5D&sort=created_at%3A1&search_engine=v3")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/users',
    params: {q: 'logins_count:[100 TO 200]', sort: 'created_at:1', search_engine: 'v3'},
    headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users?q=logins_count%3A%5B100%20TO%20200%5D&sort=created_at%3A1&search_engine=v3"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users?q=logins_count%3A%5B100%20TO%20200%5D&sort=created_at%3A1&search_engine=v3",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" }

  conn.request("GET", "/{yourDomain}/api/v2/users?q=logins_count%3A%5B100%20TO%20200%5D&sort=created_at%3A1&search_engine=v3", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users?q=logins_count%3A%5B100%20TO%20200%5D&sort=created_at%3A1&search_engine=v3")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users?q=logins_count%3A%5B100%20TO%20200%5D&sort=created_at%3A1&search_engine=v3")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

To learn more about `sort` and other parameters, read the [Management API Explorer](https://auth0.com/docs/api/management/v2#!/Users/get_users) documentation.


# User Search Best Practices
Source: https://auth0.com/docs/manage-users/user-search/user-search-best-practices

Learn about best practices when searching for users in Auth0

Here are some best practices for user search:

* You need a token to make requests to the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. To learn more, read [Management API Access Tokens](/docs/secure/tokens/access-tokens/management-api-access-tokens).
* To perform user search requests, the `read:users` scope is required.
* Leverage non-deterministic search: if your application does not require consistent ordering of search results and your queries are short enough not to rely on pagination, set `primary_order=false` to improve query performance.
* To get the latest search results, use an **immediately consistent** endpoint during authentication processes, such as [Get Users by ID](/docs/manage-users/user-search/retrieve-users-with-get-users-by-id-endpoint) and [Get Users by Email](/docs/manage-users/user-search/retrieve-users-with-get-users-by-email-endpoint). Searches using these endpoints reflect the results of all successful write operations including those that occurred shortly prior to your request.
* Use a well-known schema for metadata:

  * Use consistent data types for properties.
  * Avoid dynamic property names.
  * Avoid large schema sizes and deep structures.
  * Avoid storing data you do not need for authentication and authorization purposes.
* Search queries time out (HTTP status code 503) if they're not completed in two seconds or less. Queries that take longer indicate that it's either an expensive query or that the query has an error resulting in it not completing quickly.
* Search queries with user-defined attributes in `app_metadata` and `user_metadata` may experience time outs. We advise you do not use [List or search users](https://auth0.com/docs/api/management/v2/users/get-users) for critical operations.
* Don't use a search criteria that returns a large data set (more than 1000 results).
* Don't use existence queries (for example, "give me all users with a property regardless of its value").
* Don't poll the search APIs.
* Don't perform user search requests within login flow extension points, such as Rules or `post-login` Actions.
* Don't use large metadata fields (try to keep metadata fields to 2 KB or less).
* Using wildcard on searches can affect performance. In some cases, wildcard searches on large data sets can result in time out errors. We also recommend avoiding wildcards prefixed to the search term, while using them as suffixes yields better performance.
* Escape the space character to improve performance (e.g., `q=name:John Doe` should be written as `q=name:John\ Doe`).


# User Search Query Syntax
Source: https://auth0.com/docs/manage-users/user-search/user-search-query-syntax

Describes Auth0's user search query string syntax.

<Callout icon="file-lines">
  This content describes the current Auth0 user search, version 3.
</Callout>

When searching for users, you can create queries using [Lucene query syntax](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html) to refine your search.

The query string is parsed into a series of terms and operators:

* A term can be a single word such as `jane` or `smith`.
* A term can be a phrase surrounded by double quotes (`"green apple"`), which will match all words in the phrase in the same order.
* A term without a field name will not match text in the [user metadata](/docs/manage-users/user-accounts/metadata) fields.
* Multiple terms can be grouped together with parentheses to form sub-queries.
* Search values for the normalized user fields (`email`, `name`, `given_name`, `family_name`, and `nickname`) are case insensitive. All other fields (including all `app_metadata`/`user_metadata` fields) are case sensitive.
* Operators (`AND`, `OR`, `NOT`) work on all normalized user fields and root metadata fields.
* Operators should always be capitalized.

## Searchable fields

You can search for users using all the [normalized user profile fields](/docs/manage-users/user-accounts/user-profiles/normalized-user-profile-schema) and the fields below:

<table>
  <thead>
    <tr>
      <th>Search Field</th>
      <th>Data Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>phone\_number</code></td>
      <td>text</td>
      <td>The user's phone number. Only valid for users with SMS connections.</td>
    </tr>

    <tr>
      <td><code>phone\_verified</code></td>
      <td>boolean</td>
      <td>The <code>true/false</code> value indicates whether the user's phone number has been verified. Only valid for users with SMS connections.</td>
    </tr>

    <tr>
      <td><code>logins\_count</code></td>
      <td>integer</td>
      <td>The number of times the user has logged in. If a user is blocked and logs in, the blocked session is counted in <code>logins\_count</code> and updates the <code>last\_login</code> value.</td>
    </tr>

    <tr>
      <td><code>created\_at</code></td>
      <td>date time</td>
      <td>The timestamp of when the user profile was first created.</td>
    </tr>

    <tr>
      <td><code>updated\_at</code></td>
      <td>date time</td>
      <td>The timestamp of when the user's profile was last updated/modified.</td>
    </tr>

    <tr>
      <td><code>last\_login</code></td>
      <td>date time</td>
      <td>The timestamp of when the user last logged in. In case this property executes from inside a <a href="/docs/customize/rules">Rule</a> with the <code>user</code> object, the value will be associated with the login that triggered the rule (since rules execute after the actual login).</td>
    </tr>

    <tr>
      <td><code>last\_ip</code></td>
      <td>text (valid IP address)</td>
      <td>The IP address associated with the user's last login.</td>
    </tr>

    <tr>
      <td><code>blocked</code></td>
      <td>boolean</td>
      <td>The <code>true</code> or <code>false</code> value indicates if the user has been blocked. Note: <code>true</code> <em>only</em> brings back users blocked via the Admin Dashboard and Management API; it does not bring back users blocked by brute force anomaly detection.</td>
    </tr>

    <tr>
      <td><code>email.domain</code></td>
      <td>text</td>
      <td>The domain part of the user's email.</td>
    </tr>

    <tr>
      <td><code>organization\_id</code></td>
      <td>text (valid organization ID)</td>
      <td>The organization that the user is a member of</td>
    </tr>
  </tbody>
</table>

Metadata fields may be used with:

* boolean
* numeric: integer or double
* text
* objects: in order to search a scalar value nested in another object, use the path to the field. For example, `app_metadata.subscription.plan:"gold"`
* arrays: in order to search fields in objects nested in arrays, use the path to the field and ignore the array level. For example, `user_metadata.addresses.city:"Paris"`

Metadata fields that contain an empty array, empty object, or `null` value are not indexed and cannot be searched for.

Range and wildcard searches are not available on `user_metadata` fields.

## Exact match

To find exact matches, use double quotes: `name:"jane smith"`.

For example, to find users with the name `jane smith`, use `q=name:"jane smith"`:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/users?q=name%3A%22jane%20smith%22&search_engine=v3' \
    --header 'authorization: Bearer {yourMgmtApiAccessToken}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users?q=name%3A%22jane%20smith%22&search_engine=v3");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users?q=name%3A%22jane%20smith%22&search_engine=v3"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/users?q=name%3A%22jane%20smith%22&search_engine=v3")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/users',
    params: {q: 'name:"jane smith"', search_engine: 'v3'},
    headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users?q=name%3A%22jane%20smith%22&search_engine=v3"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users?q=name%3A%22jane%20smith%22&search_engine=v3",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" }

  conn.request("GET", "/{yourDomain}/api/v2/users?q=name%3A%22jane%20smith%22&search_engine=v3", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users?q=name%3A%22jane%20smith%22&search_engine=v3")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users?q=name%3A%22jane%20smith%22&search_engine=v3")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

## Wildcards

Wildcard searches can be run on terms using the asterisk character (`*`) to replace zero or more characters. Wildcard searches are not available on `user_metadata` fields.

#### Examples

* `name:john*` returns all users with `john` at the beginning of their names.
* `name:j*` returns all users with `j` at the beginning of their names.
* `q=name:john*` returns all users whose names start with `john`.
* For suffix matching, literals must have 3 characters or more. For example, `name:*usa` is allowed, but `name:*sa` is not.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/users?q=name%3Ajohn*&search_engine=v3' \
    --header 'authorization: Bearer {yourMgmtApiAccessToken}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users?q=name%3Ajohn\*&search_engine=v3");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users?q=name%3Ajohn*&search_engine=v3"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/users?q=name%3Ajohn*&search_engine=v3")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/users',
    params: {q: 'name:john*', search_engine: 'v3'},
    headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users?q=name%3Ajohn*&search_engine=v3"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users?q=name%3Ajohn*&search_engine=v3",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" }

  conn.request("GET", "/{yourDomain}/api/v2/users?q=name%3Ajohn*&search_engine=v3", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users?q=name%3Ajohn*&search_engine=v3")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users?q=name%3Ajohn*&search_engine=v3")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

## Ranges

You can use ranges in your user search queries. Range searches are not available on user metadata fields.

* For inclusive ranges, use square brackets: `[min TO max]`.
* For exclusive ranges, use curly brackets: `{min TO max}`.
* Curly and square brackets can be combined in the same range expression: `logins_count:[100 TO 200}`.
* Use ranges in combination with wildcards. For example, to find all users with more than 100 logins, use `q=logins_count:{100 TO *]`.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/users?q=logins_count%3A%7B100%20TO%20*%5D&search_engine=v3' \
    --header 'authorization: Bearer {yourMgmtApiAccessToken}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users?q=logins_count%3A%7B100%20TO%20\*%5D&search_engine=v3");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users?q=logins_count%3A%7B100%20TO%20*%5D&search_engine=v3"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/users?q=logins_count%3A%7B100%20TO%20*%5D&search_engine=v3")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/users',
    params: {q: 'logins_count:{100 TO *]', search_engine: 'v3'},
    headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users?q=logins_count%3A%7B100%20TO%20*%5D&search_engine=v3"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users?q=logins_count%3A%7B100%20TO%20*%5D&search_engine=v3",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" }

  conn.request("GET", "/{yourDomain}/api/v2/users?q=logins_count%3A%7B100%20TO%20*%5D&search_engine=v3", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users?q=logins_count%3A%7B100%20TO%20*%5D&search_engine=v3")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users?q=logins_count%3A%7B100%20TO%20*%5D&search_engine=v3")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

## Searchable Profile Attribute Examples

When searching for users in the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>, you can filter users by `user_metadata` or `app_metadata`. To do so, you can use Lucene Search Syntax with the `q` parameter.

Because the Auth0 Management API [list or the search users](https://auth0.com/docs/api/management/v2#!/Users/get_users) endpoint is limited to 1000 results (10 pages of 100 records), filtering is a useful way of ensuring that the most relevant results are returned.

Below is a sample of a user profile `user_metadata`:

```json lines theme={null}
{
  "favorite_color": "blue",
  "approved": false,
  "preferredLanguage": "en",
  "preferences": {
    "fontSize": 13
  },
  "addresses":{
    "city":["Paris","Seattle"]
  }
}
```

### Filter metadata attributes

To return a `user_metadata` value, update the `q` query with a filter for the attribute.

For `user_metadata` values, you can query the profile directly:

`q: _exists_:user_metadata.fav_color`

This query returns all user profiles with the `fav_color` attribute in the `user_metadata`.

### Filter metadata nested object attributes and values

You can also search on nested objects in `user_metadata`:

`q: _exists_:user_metadata.preferences.fontSize`

This queries all user profiles with `preferences.fontSize` configured in the `user_metadata`.

To search for the values of a nested object from another object, review the query below:

`q: user_metadata.preferences.fontSize:13`

This query returns all user profiles that match the `fontSize` attribute with the value of `13`.

### Filter metadata nested array values

You can use the query below to search fields in nested arrays:

`q: user_metadata.addresses.city:"Seattle"`

This returns all user profiles that return the value of `Seattle` from the `address.city` attributes in the `user_metadata`.

## Learn more

* [Sort Search Results](/docs/manage-users/user-search/sort-search-results)
* [View Search Results by Page](/docs/manage-users/user-search/view-search-results-by-page)
* [Retrieve Users with the Get Users Endpoint](/docs/manage-users/user-search/retrieve-users-with-get-users-endpoint)


# View Search Results by Page
Source: https://auth0.com/docs/manage-users/user-search/view-search-results-by-page

Learn how to view search results page by page and include totals.

To page the user search results, use the `page`, `per_page`, and `include_totals` parameters at your request.

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>page</code></td>
      <td>The page number, zero based. When this is not set, we return a maximum of 50 records, regardless of how many records exist.</td>
    </tr>

    <tr>
      <td><code>per\_page</code></td>
      <td>The amount of users per page.</td>
    </tr>

    <tr>
      <td><code>include\_totals</code></td>
      <td>Set to <code>true</code> to include a query summary as part of the result.</td>
    </tr>
  </tbody>
</table>

## Sample request

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/users?q=logins_count%3A%5B100%20TO%20200%5D&page=2&per_page=10&include_totals=true&search_engine=v3' \
    --header 'authorization: Bearer {yourMgmtApiAccessToken}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users?q=logins_count%3A%5B100%20TO%20200%5D&page=2&per_page=10&include_totals=true&search_engine=v3");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users?q=logins_count%3A%5B100%20TO%20200%5D&page=2&per_page=10&include_totals=true&search_engine=v3"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/users?q=logins_count%3A%5B100%20TO%20200%5D&page=2&per_page=10&include_totals=true&search_engine=v3")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/users',
    params: {
      q: 'logins_count:[100 TO 200]',
      page: '2',
      per_page: '10',
      include_totals: 'true',
      search_engine: 'v3'
    },
    headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users?q=logins_count%3A%5B100%20TO%20200%5D&page=2&per_page=10&include_totals=true&search_engine=v3"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users?q=logins_count%3A%5B100%20TO%20200%5D&page=2&per_page=10&include_totals=true&search_engine=v3",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" }

  conn.request("GET", "/{yourDomain}/api/v2/users?q=logins_count%3A%5B100%20TO%20200%5D&page=2&per_page=10&include_totals=true&search_engine=v3", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users?q=logins_count%3A%5B100%20TO%20200%5D&page=2&per_page=10&include_totals=true&search_engine=v3")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users?q=logins_count%3A%5B100%20TO%20200%5D&page=2&per_page=10&include_totals=true&search_engine=v3")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

## Sample response

A sample response body for the values set in the above sample request is as follows:

```json lines theme={null}
{
    "start": 20,
    "limit": 10,
    "length": 10,
    "users": [
        {
            ...
        }
    ],
    "total": 79
}
```

## Limitation

Auth0 limits the total number of users you can retrieve to 1000 (for example, 100 users per page for 10 pages). When the `page` parameter is not set, we return a maximum of 50 records, regardless of how many records exist.

## Keep reading

To learn more about the `page`, `per_page` and other parameters, read the [Management API Explorer](https://auth0.com/docs/api/management/v2#!/Users/get_users) documentation.


# Customize
Source: https://auth0.com/docs/customize

Learn how to brand, customize, and localize your login pages, domain names, emails sent to users, and consent prompts.

<AuthDocsPipeline />

Auth0 lets you customize your users’ entire authentication experience. You can:

* Brand and internationalize all interaction with end users
* Define your own logic to customize and extend how Auth0 works
* Integrate Auth0 with third-party software to add capabilities

***

## Brand Customization

##### Seamlessly integrate Auth0 with your own brand and localize the experience for international users.

<Card title="Customize Login Pages" href="/docs/customize/login-pages">
  Customize the Universal Login and Classic Login experiences
</Card>

<Card title="Custom Domains" href="/docs/customize/custom-domains">
  Unify the login experience with your own brand and products.
</Card>

<Card title="Customize Emails" href="/docs/customize/email">
  Brand and modify the content and flow of email to end users.
</Card>

<Card title="Customize Multi-factor Authentication SMS and Voice Messages" href="/docs/customize/customize-sms-or-voice-messages">
  Learn how to customize SMS and voice messages sent by Auth0 during enrollment and verification.
</Card>

<Card title="Internationalization and Localization" href="/docs/customize/internationalization-and-localization">
  Learn how to handle different languages within your Auth0 applications.
</Card>

***

## Code Customization

##### Create Actions to customize and extend Auth0’s capabilities with custom logic. Or maintain legacy Rules and Hooks.

<Card title="Actions" href="/docs/customize/actions">
  Customize Auth0 capabilities with secure, tenant-specific, versioned functions that execute at certain points during the Auth0 runtime.
</Card>

<Card title="Events" href="/docs/customize/events">
  Use Auth0 Events to build event streams.
</Card>

<Card title="Forms" href="/docs/customize/forms">
  Extend your identity flows with additional steps and custom logic with Forms.
</Card>

<Card title="Rules" href="/docs/customize/rules">
  Maintain legacy rules that your applications use in the authentication pipeline.
</Card>

<Card title="Hooks" href="/docs/customize/hooks">
  Maintain legacy hooks for selected extensibility points of the Auth0 platform.
</Card>

***

## Third-Party Customization

##### Take advantage of third-party integrations and Auth0 extensions to expand what Auth0 can do for your systems.

<Card title="Extensions" href="/docs/customize/extensions">
  Use Auth0 Extensions to install applications or run commands/scripts that extend the capabilities of the Auth0 base product.
</Card>

<Card title="Integrations" href="/docs/customize/integrations">
  Reduce implementation time with Auth0-reviewed integrations you can trust.
</Card>

<Card title="Log Streams" href="/docs/customize/log-streams">
  Monitor and respond to events such as changed passwords or new registrations with your own business logic.
</Card>


# Customize Login Pages
Source: https://auth0.com/docs/customize/login-pages

Explore topics related to login page customization

[Auth0 Universal Login](/docs/authenticate/login/auth0-universal-login) provides the essential feature of an <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip>: the login flow. When a user needs to prove their identity to gain access to your application, you can redirect them to <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> and let Auth0 handle the authentication process.

Universal Login is Auth0's primary hosted login solution. [Universal Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience) features easy-to-use customization tools and promotes a simpler, faster experience for end-users. Alternatively, Auth0 also supports [Classic Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/classic-experience), a hosted login experience that uses JavaScript controls for customization.

For a comparison between login experiences, review [Universal Login vs. Classic Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login).

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/customize/login-pages/universal-login">Customize Universal Login </a></td>
      <td>How to customize the Universal Login experience.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/login-pages/classic-login">Customize Classic Login</a></td>
      <td>How to customize the Classic Login experience.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/login-pages/customize-consent-prompts">Customize Consent Prompts</a></td>
      <td>How to customize the consent prompt presented to users during authorization.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/login-pages/custom-error-pages">Customize Error Pages</a></td>
      <td>How to create a custom error page for authorization error events.</td>
    </tr>
  </tbody>
</table>


# Advanced Customizations for Universal Login (ACUL)
Source: https://auth0.com/docs/customize/login-pages/advanced-customizations

An overview of Auth0's Advanced Customization for Universal Login

**Advanced Customizations for Universal Login (ACUL)**  extends the capabilities of [Universal Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience#universal-login-experience) to support multi-branding, complex security configurations, and integration of numerous analytic platforms.

<video />

With ACUL, you can write code in your preferred framework, integrate your existing analytics and A/B testing platforms, and define the user-experience. The [ACUL SDKs](/docs/customize/login-pages/advanced-customizations/reference) act as the connection between your custom code and Universal Login.

## Benefits

* Extend the capabilities of Auth0’s Universal Login to support multiple brands in one tenant.
* Take advantage of Auth0’s features, such as [Passkeys](/docs/authenticate/database-connections/passkeys), [Bot Detection](/docs/secure/attack-protection/bot-detection), and [MFA factors](/docs/secure/multi-factor-authentication), without rebuilding your authentication logic.
* Integrate advanced analytics and A/B testing to optimize the user journey.
* Use the ACUL SDKs to build with your own tech stack. You can:
  * Use any third-party CSS, JS, or component library
  * Integrate your preferred analytics platform, such as Heap, Mixpanel, etc.
  * Build with your preferred frontend framework, such as Vue or React

## Use cases

You want to use ACUL with your Universal Login implementation if:

* You need to apply specific brand standards to your authentication flows.
* You need to provide a Multi-branding experience.
* You need to provide UI-level A/B testing or detailed analytics.
* You need to provide a localized Universal Login in languages that Auth0 does not currently support.
* You need to add complex or custom logic to your authentication flows.

To learn more, read [ACUL Use Cases](/docs/customize/login-pages/advanced-customizations/acul-use-cases).

## How it works

<img alt="How it works ACUL" />

<img alt="How it works ACUL" />

**Build time** begins when you build your customized authentication screens in your own environment.

Use the [ACUL SDKs](/docs/customize/login-pages/advanced-customizations/reference) to submit your custom code to define prompts and screens with your preferred frontend tech stack, like React or Angular. When you push commits, your CI/CD pipeline runs the build process, compiles your application into static JavaScript and CSS assets, and uploads these assets to your private cloud storage, which serves as your own content delivery network (CDN).

**Run time** begins when your application redirects end-users to your Auth0 login page.

Auth0 recognizes the authentication screens you configured to use ACUL and serves a minimal host page. The user's browser loads this page, which contains HTML tags pointing to your asset URLs on your CDN. The browser downloads your JavaScript and CSS, verifies their integrity using the SRI hashes, and renders your custom UI. From here, your application code and the ACUL SDK manage the rest of the user's interaction

## Requirements

To start with Advanced Customization for Universal Login, you must have:

* An Auth0 development tenant configured with [Universal Login](/docs/authenticate/login/auth0-universal-login) and a [custom domain](/docs/customize/custom-domains).

<Callout icon="file-lines">
  We recommend you create a tenant for testing, development, and production with appropriate environment tags.
</Callout>

* An Auth0 [First Party Application](/docs/get-started/auth0-overview/create-applications#create-applications)
* A CDN with an included CI/CD pipeline, such as GitHub, to host assets.

| Read...                                                                                               | To learn...                                         |
| ----------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| [Configure ACUL](/docs/customize/login-pages/advanced-customizations/configure)                       | How to configure ACUL with your Auth0 tenant.       |
| [ACUL Quickstart](/docs/customize/login-pages/advanced-customizations/quickstart)                     | How to get started with an ACUL sample application. |
| [ACUL Development Workflow](/docs/customize/login-pages/advanced-customizations/development-workflow) | About the ACUL development workflow.                |
| [ACUL Deployment Workflow](/docs/customize/login-pages/advanced-customizations/deployment-workflow)   | About the ACUL deployment workflow.                 |
| [ACUL Use Cases](/docs/customize/login-pages/advanced-customizations/acul-use-cases)                  | About ACUL use cases.                               |
| [ACUL SDKs and resources](/docs/customize/login-pages/advanced-customizations/reference)              | About ACUL SDKs and developer resources.            |


# ACUL Use Cases
Source: https://auth0.com/docs/customize/login-pages/advanced-customizations/acul-use-cases

Learn about ACUL use cases

ACUL supports various tech stacks to fully customize the login experience for your end-users and to fit numerous business cases with advanced customization.
Use the following scenarios to customize your Universal Login [themes](/docs/customize/login-pages/universal-login/customize-themes), [templates](/docs/customize/login-pages/universal-login/customize-templates), and [text elements](/docs/customize/login-pages/universal-login/customize-text-elements). To learn more about Auth0’s hosted login, read [Auth0 Universal Login](/docs/authenticate/login/auth0-universal-login).

## Use cases

| Read...                                                                                                                                                       | To learn...                                                          |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| [Create a theme with Tailwind](/docs/customize/login-pages/advanced-customizations/acul-use-cases/create-theme-tailwind)                                      | How to create a theme with Tailwind CSS variables with ACUL screens. |
| [Integrate a custom component](/docs/customize/login-pages/advanced-customizations/acul-use-cases/integrate-custom-component)                                 | How to integrate a custom component libary to an ACUL screen.        |
| [Migrate from Classic Login to Universal Login with ACUL](/docs/customize/login-pages/advanced-customizations/acul-use-cases/migrate-classic-universal-login) | How to migrate from Classic to Universal Login with ACUL.            |


# Configure ACUL
Source: https://auth0.com/docs/customize/login-pages/advanced-customizations/configure

Learn how to configure ACUL

You can configure ACUL using the Auth0 Dashboard, Management API, and Infrastructure-as-Code(IaC) tools.

<Callout icon="file-lines">
  To configure ACUL, make sure your custom configuration files and assets are hosted on a public CDN.
</Callout>

## Auth0 Dashboard

You can use the Dashboard to customize your screens with ACUL:

A. Navigate to [Dashboard > Branding > Universal Login](https://manage.auth0.com/dashboard/#/universal-login/customizations-new)

1. Select **Customize authentication screens**.
2. Select a <code>screen</code> to  customize.
3. From **Settings > Rendering mode** select **Advanced mode**.
4. (Optional) Select **Use custom page template**.
5. (Optional) Select **Advanced mode filters**.

<Frame>
  <img alt="Auth0 Dashboard ACUL page" />
</Frame>

6. Select **Head Tags** to add your own HTML `Head Tags`.
7. (Optional) Select **Additional Data** to select which additional data to send to the browser.

B. Select **Save & Publish**

**Use the ACUL rendering configuration object**

The ACUL rendering configuration is a single JSON object that is used to enable ACUL and list all the available properties, per screen, which consist of specific assets, context data, and applicable conditional logic. The ACUL rendering configuration object can be used with IaC tools and the Auth0 Management API.

To learn more, review the [`/v2/prompts/patch-rendering`](https://auth0.com/docs/api/management/v2/prompts/patch-rendering) endpoint.

## Infrastructure-as-Code (IaC)

Configure ACUL with IaC tools, including:

* The **Auth0 CLI's** [`auth0 acul`](https://auth0.github.io/auth0-cli/auth0_acul.html) command.
* The **Auth0 Terraform Provider's** [`auth0_prompt_screen_renderer`](https://registry.terraform.io/providers/auth0/auth0/latest/docs/resources/prompt_screen_renderer) resource.
* The **Auth0 Deploy CLI's** [`prompts`](https://github.com/auth0/auth0-deploy-cli/blob/master/docs/resource-specific-documentation.md#prompts) resource.

## Auth0 Management API

Use ACUL Management API endpoints to configure Universal Login screens individually or to update multiple screens with one API call. You must have [Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens) in the request.

**Individual screen configuration**

* The [`GET /v2/prompts/{prompt}/screen/{screen}/rendering` endpoint](/docs/api/management/v2/prompts/get-rendering) allows you to retrieve the configuration for a single screen.

* The [`PATCH /v2/prompts/{prompt}/screen/{screen}/rendering` endpoint](/docs/api/management/v2/prompts/patch-rendering) allows you to configure ACUL on a single screen.

**Bulk screen configuration**

* The [`GET /v2/prompts/rendering` endpoint](/docs/api/management/v2/prompts/get-all-rendering) allows you to retrieve configurations for all the screens.

* The [`PATCH /v2/prompts/rendering` endpoint](/docs/api/management/v2/prompts/patch-bulk-rendering) allows you to update screens in bulk.


# ACUL Deployment Workflow
Source: https://auth0.com/docs/customize/login-pages/advanced-customizations/deployment-workflow

Learn about ACUL deployment workflow

<Callout icon="file-lines">
  To follow this workflow, make sure you have:

  * An Auth0 development tenant configured with [Universal Login](docs/authenticate/login/auth0-universal-login) and a [custom domain](/docs/customize/custom-domains).
  * An Auth0 [First Party Application](/docs/get-started/auth0-overview/create-applications#create-applications)
  * [Identifier First Authentication](/docs/authenticate/login/auth0-universal-login/identifier-first) enabled in your Auth0 tenant.
  * An AWS account with permissions to create IAM roles, S3 buckets, and configure CloudFront
  * A GitHub repository containing your custom login screens
</Callout>

The ACUL production deployment workflow builds and deploys your ACUL screens and configures your tenant to use them. It uses GitHub Actions to:

* Build your screen asset bundles
  * The workflow reads the [config/deploy\_config.yml](https://github.com/auth0-samples/auth0-acul-samples/blob/6cb4dcc43defd1a9cf586da9307d7d2348e696ae/react/.github/config/deploy_config.yml) file to determine which screens are marked for deployment.
  * If deployment targets are found, the workflow builds your ACUL assets, by using Vite and comping the code into the `/dist` directory.
* Upload your assets to AWS S3
  * The workflow securely authenticates with AWS using [OpenID Connect (OIDC)](docs/authenticate/protocols/openid-connect-protocol).
  * It uploads the contents of the `/dist` directory to your S3 bucket.
* Configure your Auth0 tenant
  * The workflow uses [Auth0 CLI](https://auth0.github.io/auth0-cli/) with a M2M application to configure the screens in your tenant.
  * It maps each screen to the correct Auth0 screen using the [config/screen-to-prompt-mapping.js](https://github.com/auth0-samples/auth0-acul-samples/blob/6cb4dcc43defd1a9cf586da9307d7d2348e696ae/react/.github/config/screen-to-prompt-mapping.js) file.
  * It updates the Auth0 screen customization settings to point to your assets at CloudFront CDN.

Once configured, a `git push` to the `main` branch of your project starts the GitHub workflow.

<Callout icon="file-lines">
  To read a complete example of the ACUL production deployment workflow, read [ACUL GITHUB ACTIONS](https://github.com/auth0-samples/auth0-acul-samples/blob/6cb4dcc43defd1a9cf586da9307d7d2348e696ae/react/.github/GITHUB_ACTIONS.md) on Github.
</Callout>

### 1. Auth0 configuration

Create a [Machine-to-Machine](/docs/get-started/auth0-overview/create-applications/machine-to-machine-apps) application to grant permissions to the GitHub workflow to update your tenant settings.

1. Navigate to [Auth0 Dashboard > Applications](https://manage.auth0.com/#/applications).
2. Select **Create Application**.
3. Select **Machine to Machine Applications**.
4. Under **Name**, add a descriptive name, for example: `GitHub ACUL Deployment`.
5. Select **Create**.
6. Under **Authorize Machine to Machine Application**, select **Auth0 Management API**.
7. Select these specific permissions:
   * `read:branding`
   * `update:branding`
   * `read:prompts`
   * `update:prompts`
   * `read:custom_domains`
8. Select **Authorize**.
9. Navigate to the **Settings** tab and note down:
   * `Domain`
   * `Client ID`
   * `Client Secret`

### 2. Upload and serve your assets with Amazon web services

To upload and serve your assets, you need an AWS S3 bucket and to set CloudFront as the CDN.

* **Create an AWS S3 Bucket**. Block all public access so this bucket is private. This private bucket stores your assets.
* **Set Up a CloudFront Distribution**. This CDN securely serves your assets. It should be configured to use your S3 bucket as its `Origin` using Origin Access Control (OAC).

### 3. Create an AWS IAM role for GitHub Action

Create an **IAM Role** in AWS to grant GitHub Actions permission to upload files to AWS S3.

<Callout icon="file-lines">
  * This IAM role must use Web Identity (OIDC), trusting `token.actions.githubusercontent.com`.
  * The role needs a policy granting `s3:PutObject`, `s3:DeleteObject`, and `s3:ListBucket` permissions on your S3 bucket.
</Callout>

### 4. Configure your GitHub repository

To configure your GitHub repository:

1. Navigate to **GitHub > Settings**.
2. Select **Secrets and Variables** and then **Actions**.
3. Select **New repository secret**.

Add the following repository secrets:

* `AWS_S3_ARN`: The ARN of the IAM role you created.
* `S3_BUCKET_NAME`: The name of your S3 bucket.
* `AWS_REGION`: The region where your S3 bucket is located. For example, `us-east-1`.
* `S3_CDN_URL`: Your CloudFront distribution's domain name. Do not add a trailing slash. For example, [https://d1234abcdef.cloudfront.net](https://d1234abcdef.cloudfront.net).
* `AUTH0_DOMAIN`: Your Auth0 tenant domain.
* `AUTH0_CLIENT_ID`: The Client ID from your M2M application.
* `AUTH0_CLIENT_SECRET`: The Client Secret from your M2M application.

### 5. Configure your deployment

You can control which screens are deployed by editing the configuration files located in the `.github/config/` directory:

* [`config/deploy_config.yml`](https://github.com/auth0-samples/auth0-acul-samples/blob/6cb4dcc43defd1a9cf586da9307d7d2348e696ae/react/.github/config/deploy_config.yml): Your main control panel. Set a screen to `true` to deploy it or `false` to skip it.
* [`config/screen-to-prompt-mapping.js`](https://github.com/auth0-samples/auth0-acul-samples/blob/6cb4dcc43defd1a9cf586da9307d7d2348e696ae/react/.github/config/screen-to-prompt-mapping.js): Maps your internal screen directory names. Example: `mfa-sms-challenge` to the official Auth0 prompt name `mfa-sms`.
* [`config/context-configuration.js`](https://github.com/auth0-samples/auth0-acul-samples/blob/6cb4dcc43defd1a9cf586da9307d7d2348e696ae/react/.github/config/context-configuration.js): Defines Auth0 context data. Example: branding settings should be made available to your custom screens.


# ACUL Development Workflow
Source: https://auth0.com/docs/customize/login-pages/advanced-customizations/development-workflow

Learn about ACUL development workflow

There are two primary modes for the development of your ACUL screens: local development and live tenant integration testing.

## Local development

Customize your ACUL screens locally with the [Auth0 CLI](https://github.com/auth0/auth0-cli/) command `auth0 acul dev`. Quickly iterate your ACUL screens without any delays or backend dependencies with the [Universal Login Context Inspector](https://github.com/auth0/ul-context-inspector).

The Universal Login Context Inspector provides mock context data to test your authentication screens against tenant specific configurations.

<Frame>
  <img alt="Universal Login Context Inspector" />
</Frame>

* Select **Screen** to see your available ACUL configured screens with default mock context data.
* Select **Data Source** to select mock context data served from **Auth0 CDN** or mock context data from your **Local Development** project's `public/screens/{prompt}/{screen}` directory.
* Select the **Download JSON** icon to download the context data for a selected screen.

## Live tenant integration testing

Live tenant integration with the Auth0 CLI command `auth0 acul dev --connected` allows for End-to-End testing of your custom screen UIs and verifies integration with your Auth0 tenant.
Use `--connected` mode for integration testing after the UI is largely complete, as each reload restarts the authentication flow.

When using `auth0 acul dev --connected`

* Select your ACUL project's directory.
* Select `npm run build` to build the project and configure your Auth0 tenant.
* Select the **port** to serve your local assets, by default `55444` and start the local server in the background.
* Optionally, allow `--connected` mode to continually monitor watch for changes to the project's  `/dist/assets` directory.

Open a new terminal and run `auth0 test login` to test the login flow on your tenant.

<Callout icon="file-lines">
  In `--connected` mode, The Auth0 CLI command watches for file changes, rebuilds assets, and automatically updates your tenant's configuration.
</Callout>

To learn more, read [Auth0 CLI](https://auth0.github.io/auth0-cli/auth0_acul_dev.html) on GitHub.


# ACUL Quickstart
Source: https://auth0.com/docs/customize/login-pages/advanced-customizations/quickstart

Get started with ACUL quickstart

<Card title="Before you start">
  You need:

  * An Auth0 development tenant configured with [Universal Login](/docs/authenticate/login/auth0-universal-login) and a [custom domain](/docs/customize/custom-domains).
  * An Auth0 [First Party Application](/docs/get-started/auth0-overview/create-applications#create-applications).
  * [Identifier First Authentication](/docs/authenticate/login/auth0-universal-login/identifier-first) enabled in your Auth0 tenant.
  * [Node.js](http://Node.js) V22
  * [Auth0 CLI](https://auth0.github.io/auth0-cli/) installed and configured with your development tenant.
</Card>

The Auth0 CLI allows you to implement and test Advanced Customization for Universal Login (ACUL) screens. It simplifies customizing authentication screens (such as Login, Signup, Passwordless, and Passkey enrollment) to exactly match your web applications.

Follow these steps to create an ACUL project and a custom `login_id` screen using Auth0 CLI:

## 1. Initialize an ACUL sample application

<Callout icon="file-lines">
  If you have not configured your development tenant with Auth0 CLI, use the `auth0 login` command to configure your tenant.
</Callout>

Navigate to a location to build your project and run the following command:

```bash theme={null}
auth0 acul init "Your_App_Name"
```

1. Select **React (with ACUL React SDK)**.
2. Select the **login-id** screen.
3. At **Would you like to proceed with installing the required dependencies using 'npm install'?** Enter **y**.

Auth0 CLI creates a new project directory with the provided application name.

<Callout icon="file-lines">
  If you did not select **y** to install the required dependencies, navigate to your project directory and run the `npm install` command.
</Callout>

## 2. (Optional) Add additional screens to your project

Select additional screens for your project by running the following command:

```bash theme={null}
auth0 acul screen add SCREEN_NAME 
```

## 3. Launch the Login Id screen with Universal Login Context Inspector

Use the UL context inspector to launch the Login ID screen:

1. Navigate to your project directory and run the following command:

```bash theme={null}
auth0 acul dev
```

2. Confirm the project directory
3. Select the port to share the local assets, by default Port `55444`

The Universal Login Context Inspector opens a new browser window with the Login Id screen.

## 4. Update the sample Login Id screen

<Callout icon="file-lines">
  The command auth0 acul dev builds the ACUL screens, hosts your assets locally, and continuously watches for updates to the assets directory; allowing you to test your screens locally. To learn more, read [Auth0 CLI acul](https://auth0.github.io/auth0-cli/auth0_acul_dev.html) command documentation.
</Callout>

1. In your project directory, edit the `/src/index.css` directory and update the logo widget with your logo url:

`--ul-theme-widget-logo-url: "Your-Logo-URL";`

2. Save the change.

The local dev server automatically refreshes with the latest change.

## 5. Customize the context data for your authentication screens

Using the Universal Login Context Inspector, you can customize the default context data to test your authentication screens against tenant specific configurations.

1. Create a local version of the mock context data for a screen in your project:

Select the **Download JSON** icon to download the mock context data file.

<Frame>
  <img alt="Auth0 Dashboard ACUL page" />
</Frame>

2. Rename and move the downloaded file to the `public/screens/{prompt}/{screen}` and add it to the `public/manifest.json file` in your project's directory.

For example, the downloaded `login-id-login-id-context.json` file is renamed `login-id.json` and is moved to `/public/screens/login-id/login-id.json`.

3. Select **Local Development** from the Universal Login Context Inspector **Data source** to load the local version of the mock context for the screen.

To learn more, read [Auth0 CLI ACUL](https://auth0.github.io/auth0-cli/auth0_acul_dev.html) documentation.


# Customize Classic Login
Source: https://auth0.com/docs/customize/login-pages/classic-login

Learn how to customize the Classic Login experience

Classic Login is an Auth0-hosted login experience that relies on JavaScript for customization. Implementing Classic Login is less complex than embedding the authentication process directly in your app, and it can help prevent the dangers of cross-origin authentication.

Classic Login serves as an alternative to [Universal Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience). For a feature comparison between the two login experiences, review [Universal Login vs. Classic Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login).

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/customize/login-pages/classic-login/customization-classic">Customize Classic Login Pages</a></td>
      <td>How to customize the Classic Login experience.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/login-pages/classic-login/customize-with-lock-sdk">Customize Classic Login Pages with Lock or SDK</a></td>
      <td>How to customize Classic Login pages using the Lock widget or a custom interface.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/login-pages/classic-login/customize-lock-error-messages">Customize Lock Error Messages</a></td>
      <td>How to customize error messages served to users in the Classic Login experience.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/login-pages/classic-login/customize-password-reset-page">Customize Classic Password Reset Pages</a></td>
      <td>How to customize the Classic Login password reset page.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/login-pages/classic-login/version-control">Classic Login Page Version Control</a></td>
      <td>How to implement version control for your custom page content.</td>
    </tr>
  </tbody>
</table>


# Customize Classic Login Pages
Source: https://auth0.com/docs/customize/login-pages/classic-login/customization-classic

Learn how to customize the login page for the Classic Login experience.

[Classic Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/classic-experience) is an Auth0-hosted login experience that relies on JavaScript for page customization.

From the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, you can configure basic customization options that apply to all login pages. For advanced customization, you can directly modify the HTML template of one or more pages.

Additionally, you can manage your page content using the [version control syste](/docs/customize/login-pages/classic-login/version-control) of your choice.

## Basic Customization

You can configure the following options from the Auth0 Dashboard under [Branding > Universal Login > Settings tab](https://manage.auth0.com/#/login_settings):

* Company Logo (recommended size: 150 x 150 pixels)
* Primary Color
* Background Color

By default, these settings affect all Classic Login pages, such as the login screen or password reset page. If you directly modify the HTML template of one or more pages and edit any attributes related to these options, those attributes will supersede these settings.

## Advanced Customization

For further customization, you can directly modify the HTML template of the following pages:

* Login (see below)
* [Password reset](/docs/customize/login-pages/classic-login/customize-password-reset-page)
* [Multi-factor authentication](/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-classic-login)

### Responsibility for updates

**When you enable customization for a specific page, you assume responsibility for maintaining that page**, as it will no longer receive automatic updates from Auth0. Such maintenance includes updating the version numbers of any included Auth0 SDKs or widgets.

As sensitive security-related information often flows through the login page, introducing cross-site scripting (XSS) vulnerabilities is a point of concern. Additionally, if your organization uses [home realm discovery](/docs/get-started/architecture-scenarios/business-to-business/authentication#home-realm-discovery) in conjunction with Classic Login, a list of available connections is publicly visible in the Auth0.setClient property. Considering this, Auth0 encourages you to exercise caution when using third-party JavaScript on your login page.

### Enable page customization

To enable customization for a specific page, follow the steps below:

1. On the Auth0 Dashboard, navigate to [Branding > Universal Login](https://manage.auth0.com/#/login_settings).
2. Select one of the following tabs:

   * **Login**
   * **Password Reset**
   * **Multi-Factor Authentication**
3. Enable the **Customize Page** toggle located at the top of the tab.
4. Repeat steps 2 and 3 as needed.

After enabling customization for a page, you can modify its HTML template through the code editor located below the toggle.

<Warning>
  If you enable customization to inspect page code but decide not to customize it, ensure you disable the **Customize Page** toggle when finished so that Auth0 can render the default pages.
</Warning>

### Customize the Login page

To customize the login page template, you must first choose a base template to work from.

1. On the Auth0 Dashboard, navigate to [Branding > Universal Login > Login tab](https://manage.auth0.com/#/login_page).
2. Enable the **Customize Login Page** toggle.
3. Above the HTML code editor, select an option from the **Default Templates** menu.

The available templates use the following libraries:

* [Lock](/docs/libraries/lock)
* [Lock (Passwordless Mode)](/docs/libraries/lock)
* [Auth0.js](/docs/libraries/auth0js)
* [Authentication API](https://auth0.com/docs/api/authentication)

You can use these libraries within Classic Login or embed them directly into an application. To better understand how you can customize your login experience, review the documentation for your preferred library.

#### Lock template

If you plan on using the default login page and require only minimal changes, you can use the Lock template to modify the behavior of the Lock widget on the login page.

For example, you can configure the Lock widget to:

* Direct users to the signup page instead of the login page by default
* Customize the login page with different colors, text, or default languages
* Present users with only one or more specific login methods

To learn more about customizing the Lock widget, review the [Lock Configuration Options](/docs/libraries/lock/lock-configuration).

#### Custom Login Form template

If you want to significantly modify the login page, you can use the Custom Login Form template as a guide. This template shows you how to get the values you need with the Auth0.js SDK. You can then modify the style and layout of the login page as desired. Any CSS customization **must** be inline, as you cannot host a separate CSS file in your Auth0 tenant.

## Learn more

* [Classic Login Experience](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/classic-experience)
* [Customize Classic Login Pages with Lock or SDK](/docs/customize/login-pages/classic-login/customize-with-lock-sdk)
* [Customize MFA for Classic Login](/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-classic-login)


# Customize Lock Error Messages
Source: https://auth0.com/docs/customize/login-pages/classic-login/customize-lock-error-messages

Customizing error messages with Lock

You can customize the error messages that will be displayed in certain situations by providing a `languageDictionary` option. A full listing of available `languageDictionary` fields to customize can be found in the GitHub repository's [English Dictionary file for Lock](https://github.com/auth0/lock/blob/master/src/i18n/en.js). Below is an example of some customized error messages:

<AuthCodeBlock />

## Custom errors in Rules

If you are returning custom error codes from a [rule](/docs/customize/rules) or a custom database script, you can handle custom errors:

* In your application's redirect URL by reading the `error` and `error_mesage` query string parameters.
* By redirecting the user back to your hosted pages with a custom error message and displaying the message with a [flash message](/docs/libraries/lock/lock-api-reference).

## Learn more

* [Lock for Web](/docs/libraries/lock)


# Customize Classic Password Reset Page
Source: https://auth0.com/docs/customize/login-pages/classic-login/customize-password-reset-page

Learn how to customize a Classic Login password reset page.

<Card title="Resetting a password?">
  This page describes how you can customize a Classic Login password reset page.

  If you need assistance resetting a password, review the following documentation instead:

  * For tenant administrators resetting other users' passwords: [Change Users' Passwords](/docs/authenticate/database-connections/password-change)
  * For individuals resetting their own passwords: [Reset Auth0 Account Password](/docs/troubleshoot/customer-support/reset-account-passwords)
</Card>

If you are using Classic Login, the password reset page provides your users with a way to change their passwords if they cannot log in. Within the password reset page, Auth0 handles all required functionality, including:

* Hosting the page itself
* Redirecting the user wanting to reset their password as necessary
* Ensuring the user's password meets your defined requirements
* Automatically redirecting the user after they reset their password

To create a consistently branded experience throughout the login flow, you can customize how the password reset prompt displays to users. You can also update the password reset page to display certain personal information if appropriate.

## Enable password reset page customization

The password reset page is enabled for all Auth0 users by default and does not require customization. However, you can enable [advanced customization](/docs/customize/login-pages/classic-login/customization-classic) if you wish to update the branding and other elements of the password reset page.

To enable advanced customization from the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>:

1. Navigate to [Branding > Universal Login > Password Reset tab](https://manage.auth0.com/#/password_reset).
2. Enable the **Customize Password Reset Page** toggle.

In the code editor below the toggle, you can now directly modify the page template.

## Edit password reset page

After enabling customization for the password reset page, you can use the built-in code editor to modify its HTML, style the page using CSS, and change the JavaScript used to retrieve and display custom variables. Ensure you select **Save Changes** below the code editor to save your updates.

### Display custom information on the Password Reset Page

You can display personalized information on the password reset page. This is done by editing the embedded JavaScript using the password reset page editor:

```js lines expandable theme={null}
new Auth0ChangePassword({
      container:         "change-password-widget-container",     // required
      email:             "{{email}}",                            // DO NOT CHANGE THIS
      csrf_token:        '{{csrf_token}}',                       // DO NOT CHANGE THIS
      ticket:            '{{ticket}}',                           // DO NOT CHANGE THIS
      password_policy:   '{{password_policy}}',                  // DO NOT CHANGE THIS
      theme: {
        icon: "{{tenant.picture_url | default: '//cdn.auth0.com/styleguide/1.0.0/img/badge.png'}}",
        primaryColor: "#ea5323"
      },
      dict: {
        // passwordPlaceholder: "your new password",
        // passwordConfirmationPlaceholder: "confirm your new password",
        // passwordConfirmationMatchError: "Please ensure the password and the confirmation are the same.",
        // passwordStrength: {
        //   containsAtLeast: "Contain at least %d of the following %d types of characters:",
        //   identicalChars: "No more than %d identical characters in a row (such as, \"%s\" not allowed)",
        //   nonEmpty: "Non-empty password required",
        //   numbers: "Numbers (such as 0-9)",
        //   lengthAtLeast: "At least %d characters in length",
        //   lowerCase: "Lower case letters (a-z)",
        //   shouldContain: "Should contain:",
        //   specialCharacters: "Special characters (such as !@#$%^&*)",
        //   upperCase: "Upper case letters (A-Z)"
        // },
        // successMessage: "Your password has been reset successfully.",
        // configurationError: "An error occurred. There appears to be a misconfiguration in the form.",
        // networkError: "The server cannot be reached, there is a problem with the network.",
        // timeoutError: "The server cannot be reached, please try again.",
        // serverError: "There was an error processing the password reset.",
        // headerText: "Enter a new password for<br />{email}",
        // title: "Change Password",
        // weakPasswordError: "Password is too weak."
        // passwordHistoryError: "Password has previously been used."
      }
    });
```

For example, the sample template snippet below shows the variable `tenant.picture_url`. This variable returns the Logo URL value defined in [Dashboard > Settings](https://manage.auth0.com/#/tenant).

```js lines theme={null}
new Auth0ChangePassword({
      theme: {
        icon: "{{tenant.picture_url | default: '//cdn.auth0.com/styleguide/1.0.0/img/badge.png'}}",
      }
    });
```

Auth0 retrieves the logo at the URL and displays it on the password reset prompt. If Auth0 can't resolve the URL, it'll display the default image.

#### Custom variables

You can use the following custom variables to display personalized information on the password reset page:

<table>
  <thead>
    <tr>
      <th>Variable</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>email</code></td>
      <td>The email address of the user requesting the password change</td>
    </tr>

    <tr>
      <td><code>ticket</code></td>
      <td>The ticket representing the given password reset request</td>
    </tr>

    <tr>
      <td><code>csrf\_token</code></td>
      <td>Token used to prevent CSRF activity</td>
    </tr>

    <tr>
      <td><code>tenant.name</code></td>
      <td>The name associated with your Auth0 tenant</td>
    </tr>

    <tr>
      <td><code>tenant.friendly\_name</code></td>
      <td>The name displayed for your Auth0 tenant</td>
    </tr>

    <tr>
      <td><code>tenant.picture\_url</code></td>
      <td>The URL leading to the logo representing you in Auth0</td>
    </tr>

    <tr>
      <td><code>tenant.support\_email</code></td>
      <td>The support email address for your company displayed to your Auth0 users</td>
    </tr>

    <tr>
      <td><code>tenant.support\_url</code></td>
      <td>The support URL for your company displayed to your Auth0 users</td>
    </tr>

    <tr>
      <td><code>lang</code></td>
      <td>The user's language</td>
    </tr>

    <tr>
      <td><code>password\_policy</code></td>
      <td>The active connection's security policy. You can see what this is using `https://manage.auth0.com/#/connections/database/con_YOUR-CONNECTION-ID/security`. Be sure to provide your connection ID in the URL.)</td>
    </tr>

    <tr>
      <td><code>password\_complexity\_options</code></td>
      <td>Object containing settings for the password complexity requirements</td>
    </tr>

    <tr>
      <td><code>min\_length</code></td>
      <td>The minimum length required for newly-created passwords. Can range from 1 to 128 characters in length</td>
    </tr>
  </tbody>
</table>

**Notes:**

* You can set/check the values for your tenant variables in the Settings area in [Dashboard > Settings](https://manage.auth0.com/#/tenant).
* You cannot make customizations conditional based on the Application ID (`client_id`).

#### Custom error messages

If your custom database script returns a custom error, you can map an error description using the `dict` property:

```js lines theme={null}
new Auth0ChangePassword({
  // ...other options
  dict: {
    yourCustomError: 'This is a custom error message'
  }
});

function changePassword(email, newPassword, callback) {
  callback(new ValidationError('yourCustomError'));
}
```

## Update password reset prompt

If you do not enable customization for the password reset page, Auth0 will handle updates necessary for the script, including changes to the version number of the included password reset prompt.

**When you enable customization for the password reset page**, you assume responsibility for updating and maintaining the script. This includes updating the version number for the password reset prompt. With customization enabled, Auth0 cannot update your script automatically without potentially interfering with the changes you've made.

The current version of the password reset prompt is 1.5.5. Use this link to call the latest version, including future minor version updates:

`https://cdn.auth0.com/js/change-password-1.5.min.js`

## Revert changes

To revert the password reset page to an earlier design, you can:

* Revert to the last saved template by clicking **Reset to Last.**
* Revert to the default template provided by Auth0 by clicking **Reset to Default**.

## Learn more

* [Customize Classic Login Pages](/docs/customize/login-pages/classic-login/customization-classic)
* [Customize MFA for Classic Login](/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-classic-login)
* [Check Error Messages](/docs/troubleshoot/basic-issues/check-error-messages)
* [Self Change Password Errors](/docs/troubleshoot/authentication-issues/self-change-password-errors)


# Customize Classic Login Pages with Lock or SDK
Source: https://auth0.com/docs/customize/login-pages/classic-login/customize-with-lock-sdk

Learn how to customize the Classic Login page with Lock or a custom UI built on top of an Auth0 SDK.

Classic Login is an Auth0-hosted login experience that relies on JavaScript for [advanced customization](/docs/customize/login-pages/classic-login/customization-classic). Implementing Classic Login is less complex than embedding the authentication process directly in your app, and it can help prevent the dangers of cross-origin authentication.

By default, the Classic Login page uses the Lock widget for user authentication. However, you can also customize templates for Lock in <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> Mode or a custom UI built with the Auth0.js SDK.

To customize your Classic Login page templates, you must first enable advanced customization. To do so, follow the steps below:

1. On the Auth0 Dashboard, navigate to [Branding > Universal Login > Login tab](https://manage.auth0.com/#/login_page).
2. Enable the **Customize Login Page** toggle.
3. Above the HTML code editor, select the Default Templates menu and choose the desired option.

The templates available include:

* Lock
* Lock (passwordless)
* Custom Login Form

Both Lock templates allow you to customize the Lock widget used for authentication. The Lock widget provides a standard set of behaviors and a customizable user interface. Alternatively, you can use the Custom Login Form template to customize your login page with the [Auth0 SDK for Web](/docs/libraries/auth0js) or [Authentication API](https://auth0.com/docs/api/authentication).

Auth0 SDKs are client-side libraries that **do not** offer a user interface but allow for expanded customization of the behavior and appearance of the login page. The Authentication API provides direct integration without the use of Auth0 SDKs.

The template you use to customize your login page will depend on the unique needs of your application. The sections below provide an overview of each option: Lock, Auth0 SDKs, or the Authentication API.

## Using the Lock widget

[Lock](/docs/libraries/lock) is a login form that makes it easy for your users to authenticate using a selected connection. Lock automatically handles most of the details involved in creating and authenticating users.

With Lock, you will be implementing a UI that:

* Is robust and provides an excellent user experience on any device with any resolution
* Has a simple design that fits in with most websites with just a few tweaks to its custom color
* Adapts to your configuration, displaying the appropriate form controls for each available connection and only those that are allowed (such as signup or password reset)
* Selects the correct connection automatically. You may specify a desired default behavior for ambiguous cases
* Remembers the last used connection for a given user
* Automatically accommodates internationalization
* Provides instant password policy checking at signup

Although you cannot alter Lock's behavior significantly, you can configure several basic options to make Lock look and behave differently.

Consider using Lock if:

* You like the structure, look, and feel of the widget.
* You prefer a streamlined implementation of Classic Login with a ready-made responsive UI.
* Your process includes many of the use cases that Lock handles out of the box:

  * Enterprise logins
  * Databases with password policies
  * User signup and password reset
  * Authentication using social providers
  * Avatars

### Sample login customization scripts

#### Customize the application logo

The example script below customizes the logo for each application, or you can set a default logo. The minimum recommended resolution is 200 pixels (width) by 200 pixels (height). Add the `logouturl` configuration to the `<scripts>` block:

```javascript lines theme={null}
var logourl = "https://example.com/defaultlogo1.png"; //set default logo
if(config.clientID === "HUXwC72R3qr9JJo9ImPsdzJbtY8aD5kS")
{
    logourl = "https://example.com/defaultlogo2.png";
}
theme: {
    logo: logourl,
    primaryColor: colors.primary ? colors.primary : 'green'
},
```

#### Customize the signup terms

The example below customizes the signup terms for your application. You can add custom language to display when users signup.

```javascript lines theme={null}
var languageDictionary;

languageDictionary = {
    signUpTerms: "I agree to the <a href='https://my-app-url.com/terms' target='_blank'>terms of service</a> and <a href='https://my-app-url.com/privacy' target='_blank'>privacy policy</a>."
};
```

## Using the Auth0 SDK for Web

If the requirements of your app cannot be met by the standardized behavior of Lock, or if you have a complex custom authentication process, a custom user interface is needed. You may also prefer this option if you have an existing user interface that you wish to use.

With [Auth0's library for Web](/docs/libraries/auth0js), you can customize the behavior and flow of the process used to trigger signup and authentication. You can also directly use the Authentication API, without any wrapper at all, if you so choose.

Unlike with Lock, neither of these options includes a user interface. You will have complete control over the user experience for signup and authentication flow, and for the UI aspects of layout, look and feel, branding, internationalization, RTL support, and more.

Consider implementing a custom user interface in conjunction with an Auth0 library or the Authentication API for your app if:

* You have strict requirements for the appearance of the user interface
* You have strict requirements for file sizes - the Auth0 libraries are significantly smaller than Lock, and if you instead choose to deal with the API directly, that would not require any additional weight.
* You are comfortable with HTML, CSS, and JavaScript - you'll be creating your own UI
* You only need to handle username/password and social provider authentication
* You have multiple database or Active Directory Connections

You can also see specific examples of the usage of both Lock and Auth0 SDKs for a wide variety of programming languages and platforms in our [Quickstarts](/docs/quickstart). These guides may further assist you in your decision about which to use for your specific app needs.

## Learn more

* [Classic Login Experience](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/classic-experience)
* [Add Bot Detection to Custom Login Pages](/docs/secure/attack-protection/bot-detection/bot-detection-custom-login-pages)
* [Deprecation Errors](/docs/troubleshoot/basic-issues/check-deprecation-errors)


# Classic Login Page Version Control
Source: https://auth0.com/docs/customize/login-pages/classic-login/version-control

Learn how to back up your Classic Login pages using the Auth0 source control extensions

You can use version control software to manage the source code of your Classic Login pages. Using version control for your content may be especially beneficial if you use a CI/CD flow for your tenant configuration and have customized the HTML of one or more Classic Login pages.

To implement version control, use the Auth0 Marketplace integration for your preferred method:

* [GitLab Pipelines](https://marketplace.auth0.com/integrations/gitlab-pipeline)
* [GitHub Actions](https://marketplace.auth0.com/integrations/github-actions)
* [Bitbucket Pipelines](https://marketplace.auth0.com/integrations/bitbucket-pipeline)
* [Microsoft Azure Pipelines](https://marketplace.auth0.com/integrations/azure-pipeline)

The general deployment process requires the following steps:

1. Create a folder in your version control repository with the appropriate name (`pages`).
2. Create an HTML page (`login.html`, `password_reset.html`, `guardian_multifactor.html`, or `error_page.html`) within that folder.
3. Create a JSON file with the same name as your HTML page for each hosted page that you wish to source control. To enable the page, the JSON file needs to contain the following:

`{
"enabled": true
}`

For example:
`your-repo/pages/error_page.html
your-repo/pages/error_page.json`

## Learn more

* [Auth0 Universal Login](/docs/authenticate/login/auth0-universal-login)


# Customize Error Pages
Source: https://auth0.com/docs/customize/login-pages/custom-error-pages

Learn how to create a custom error page for authorization error events.

When an authorization error occurs, and your callback URL is valid, the <Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip> returns the appropriate error and state parameters to your callback URL. If your callback URL is invalid, your application will display the [default Auth0 error page](/docs/authenticate/login/auth0-universal-login/error-pages).

Your application may also display the default Auth0 error page for reasons other than an invalid callback URL, such as:

* Required parameters are missing when calling the Auth0 Authentication API [Login endpoint](https://auth0.com/docs/api/authentication#login).
* User opens an expired password reset link (when using the Classic Login experience).
* User navigates to a bookmarked login page and a [Default Login Route](/docs/authenticate/login/auth0-universal-login/configure-default-login-routes) is not specified.

## Parameters

If you choose to configure a custom error page, the Authorization Server will return parameters appended to the URL as a query string.

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>client\_id</code></td>
      <td>Identifier of the Auth0 application.</td>
    </tr>

    <tr>
      <td><code>connection</code></td>
      <td>Connection used at the time of error.</td>
    </tr>

    <tr>
      <td><code>lang</code></td>
      <td>Language set for use at the time of error.</td>
    </tr>

    <tr>
      <td><code>error</code></td>
      <td>Error code of the error.</td>
    </tr>

    <tr>
      <td><code>error\_description</code></td>
      <td>Description of the error.</td>
    </tr>

    <tr>
      <td><code>tracking</code></td>
      <td>Identifier used by Auth0 to find errors in internal logs.</td>
    </tr>
  </tbody>
</table>

Parameters presented vary depending on the error type and are specific to the request. For example, if the request which resulted in an error did not contain a `client_id`, the Authorization Server will not return the `client_id` parameter.

## Display a custom error page

If you want to display a custom error page, you have two options:

1. Redirect users to a custom error page using either the Auth0 Dashboard or the Auth0 Management API.
2. Configure Auth0 to render a custom error page on your behalf via the Management API.

### Redirect users to a custom error page using the Dashboard

Use the Dashboard to configure Auth0 to redirect users to a custom error page:

1. Navigate to [Auth0 Dashboard > Tenant Settings](https://manage.auth0.com/#/tenant/).
2. Locate the **Error Pages** section.
3. Select the **Redirect users to your own error page** option.
4. Enter the URL of the error page you would like your users to see, and select **Save**.

### Redirect users to a custom error page using the Management API

Use the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> [Update Tenant Settings](https://auth0.com/docs/api/management/v2/#!/Tenants/patch_settings) endpoint. Replace the `{mgmtApiAccessToken}` placeholder value with your Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, and update the value of the `url` field in the JSON body to point to the location of the error page.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/tenants/settings' \
    --header 'authorization: Bearer {mgmtApiAccessToken}' \
    --header 'content-type: application/json' \
    --data '{"error_page": {"html": "", "show_log_link":false, "url": "http://www.example.com"}}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/tenants/settings");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("authorization", "Bearer {mgmtApiAccessToken}");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"error_page": {"html": "", "show_log_link":false, "url": "http://www.example.com"}}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/tenants/settings"

  	payload := strings.NewReader("{"error_page": {"html": "", "show_log_link":false, "url": "http://www.example.com"}}")

  	req, _ := http.NewRequest("PATCH", url, payload)

  	req.Header.Add("authorization", "Bearer {mgmtApiAccessToken}")
  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/tenants/settings")
    .header("authorization", "Bearer {mgmtApiAccessToken}")
    .header("content-type", "application/json")
    .body("{"error_page": {"html": "", "show_log_link":false, "url": "http://www.example.com"}}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/tenants/settings',
    headers: {
      authorization: 'Bearer {mgmtApiAccessToken}',
      'content-type': 'application/json'
    },
    data: {error_page: {html: '', show_log_link: false, url: 'http://www.example.com'}}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {mgmtApiAccessToken}",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"error_page": @{ @"html": @"", @"show_log_link": @NO, @"url": @"http://www.example.com" } };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/tenants/settings"]
                                                         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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/tenants/settings",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "PATCH",
    CURLOPT_POSTFIELDS => "{"error_page": {"html": "", "show_log_link":false, "url": "http://www.example.com"}}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {mgmtApiAccessToken}",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"error_page": {"html": "", "show_log_link":false, "url": "http://www.example.com"}}"

  headers = {
      'authorization': "Bearer {mgmtApiAccessToken}",
      'content-type': "application/json"
      }

  conn.request("PATCH", "/{yourDomain}/api/v2/tenants/settings", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/tenants/settings")

  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["authorization"] = 'Bearer {mgmtApiAccessToken}'
  request["content-type"] = 'application/json'
  request.body = "{"error_page": {"html": "", "show_log_link":false, "url": "http://www.example.com"}}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer {mgmtApiAccessToken}",
    "content-type": "application/json"
  ]
  let parameters = ["error_page": [
      "html": "",
      "show_log_link": false,
      "url": "http://www.example.com"
    ]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/tenants/settings")! 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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td><a href="https://auth0.com/docs/api/management/v2/tokens">Access Token for the Management API</a> with the scope <code>update:tenant\_settings</code>.</td>
    </tr>

    <tr>
      <td><code>show\_log\_link</code></td>
      <td>Indicates whether to show a link to the error in your tenant logs. Valid values are <code>true</code> and <code>false</code>.</td>
    </tr>

    <tr>
      <td><code>url</code></td>
      <td>Location of the custom error page to which you want to redirect.</td>
    </tr>
  </tbody>
</table>

### Render a custom error page

<Callout icon="file-lines">
  When errors are shown as part of the Classic Login widget (such as an expired password reset link), an Auth0-hosted custom error page will not be rendered, even if configured.
</Callout>

Use the Management API [Update Tenant Settings](https://auth0.com/docs/api/management/v2/#!/Tenants/patch_settings) endpoint. Replace the `{mgmtApiAccessToken}` placeholder value with your Management API Access Token, and update the value of the `html` field in the JSON body to a string containing the HTML of your page.

You can use Liquid syntax to include the following variables:

* `{client_id}`
* `{connection}`
* `{lang}`
* `{error}`
* `{error_description}`
* `{tracking}`

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request PATCH \
    --url https://login.auth0.com/api/v2/tenants/settings \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'content-type: application/json' \
    --data '{"error_page": {"html": "<h1>{{error | escape }} {{error_description | escape }} This error was generated {{'\''now'\'' | date: '\''%Y %h'\''}}.</h1>", "show_log_link": false, "url": ""}}'
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://login.auth0.com/api/v2/tenants/settings");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{\"error_page\": {\"html\": \"

  # {{error | escape }} {{error_description | escape }} This error was generated {{'now' | date: '%Y %h'}}.

  \", \"show_log_link\": false, \"url\": \"\"}}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines expandable theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://login.auth0.com/api/v2/tenants/settings"

  	payload := strings.NewReader("{\"error_page\": {\"html\": \"<h1>{{error | escape }} {{error_description | escape }} This error was generated {{'now' | date: '%Y %h'}}.</h1>\", \"show_log_link\": false, \"url\": \"\"}}")

  	req, _ := http.NewRequest("PATCH", url, payload)

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java lines theme={null}
  HttpResponse<String> response = Unirest.patch("https://login.auth0.com/api/v2/tenants/settings")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("content-type", "application/json")
    .body("{\"error_page\": {\"html\": \"<h1>{{error | escape }} {{error_description | escape }} This error was generated {{'now' | date: '%Y %h'}}.</h1>\", \"show_log_link\": false, \"url\": \"\"}}")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://login.auth0.com/api/v2/tenants/settings',
    headers: {
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'content-type': 'application/json'
    },
    data: {
      error_page: {
        html: '<h1>{{error | escape }} {{error_description | escape }} This error was generated {{\'now\' | date: \'%Y %h\'}}.</h1>',
        show_log_link: false,
        url: ''
      }
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C lines expandable theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"error_page": @{ @"html": @"<h1>{{error | escape }} {{error_description | escape }} This error was generated {{'now' | date: '%Y %h'}}.</h1>", @"show_log_link": @NO, @"url": @"" } };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://login.auth0.com/api/v2/tenants/settings"]
                                                         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];
  ```

  ```php PHP lines expandable theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://login.auth0.com/api/v2/tenants/settings",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "PATCH",
    CURLOPT_POSTFIELDS => "{\"error_page\": {\"html\": \"<h1>{{error | escape }} {{error_description | escape }} This error was generated {{'now' | date: '%Y %h'}}.</h1>\", \"show_log_link\": false, \"url\": \"\"}}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("login.auth0.com")

  payload = "{\"error_page\": {\"html\": \"<h1>{{error | escape }} {{error_description | escape }} This error was generated {{'now' | date: '%Y %h'}}.</h1>\", \"show_log_link\": false, \"url\": \"\"}}"

  headers = {
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
      'content-type': "application/json"
      }

  conn.request("PATCH", "/api/v2/tenants/settings", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://login.auth0.com/api/v2/tenants/settings")

  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["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request["content-type"] = 'application/json'
  request.body = "{\"error_page\": {\"html\": \"<h1>{{error | escape }} {{error_description | escape }} This error was generated {{'now' | date: '%Y %h'}}.</h1>\", \"show_log_link\": false, \"url\": \"\"}}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift lines expandable theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "content-type": "application/json"
  ]
  let parameters = ["error_page": [
      "html": "<h1>{{error | escape }} {{error_description | escape }} This error was generated {{'now' | date: '%Y %h'}}.</h1>",
      "show_log_link": false,
      "url": ""
    ]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://login.auth0.com/api/v2/tenants/settings")! 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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td><a href="https://auth0.com/docs/api/management/v2/tokens">Access Token for the Management API</a> with the scope <code>update:tenant\_settings</code>.</td>
    </tr>

    <tr>
      <td><code>show\_log\_link</code></td>
      <td>Indicates whether to show a link to the error in your tenant logs. Valid values are <code>true</code> and <code>false</code>.</td>
    </tr>

    <tr>
      <td><code>html</code></td>
      <td>HTML of the custom error page you want to render.</td>
    </tr>
  </tbody>
</table>

To prevent XSS vulnerabilities, sanitize your custom template using Liquid's [escape](https://shopify.github.io/liquid/filters/escape/) and [strip\_html](https://shopify.github.io/liquid/filters/strip_html/) filters.

## Learn more

* [Auth0 Universal Login](/docs/authenticate/login/auth0-universal-login)


# Customize Consent Prompts
Source: https://auth0.com/docs/customize/login-pages/customize-consent-prompts

Describes how to customize the consent prompt presented to users during authorization.

When a third-party application requests scopes, users see a consent prompt. By default, this prompt uses the scope **name** to generate text and groups all scopes for a resource, displaying the resource's actions in a single line.

If you require a specialized consent prompt, for example, parental consent, you need to build your own custom consent form. Be aware that laws vary according to country.

For example, let's say you have an Auth0-registered API with the following defined scopes:

* `read:messages`: Be able to read your email messages
* `write:messages`: Write messages

The consent prompt will display **Messages: read and write your messages**.

Instead, you can use your defined scope **description** to generate this text. In this case, the consent dialog would display: **Be able to read your email messages**, **Write messages**.

This change is made at the tenant level, so it will affect consent prompts for all APIs on the tenant.

## Use scope descriptions to generate consent prompt text

Set your tenant's **use\_scope\_descriptions\_for\_consent** flag to `true` by making the following API call:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/tenants/settings' \
    --header 'authorization: Bearer API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "flags": { "use_scope_descriptions_for_consent": true } }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/tenants/settings");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer API_ACCESS_TOKEN");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("application/json", "{ "flags": { "use_scope_descriptions_for_consent": true } }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/tenants/settings"

  	payload := strings.NewReader("{ "flags": { "use_scope_descriptions_for_consent": true } }")

  	req, _ := http.NewRequest("PATCH", url, payload)

  	req.Header.Add("content-type", "application/json")
  	req.Header.Add("authorization", "Bearer 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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/tenants/settings")
    .header("content-type", "application/json")
    .header("authorization", "Bearer API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "flags": { "use_scope_descriptions_for_consent": true } }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/tenants/settings',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: {flags: {use_scope_descriptions_for_consent: true}}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"flags": @{ @"use_scope_descriptions_for_consent": @YES } };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/tenants/settings"]
                                                         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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/tenants/settings",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "PATCH",
    CURLOPT_POSTFIELDS => "{ "flags": { "use_scope_descriptions_for_consent": true } }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer 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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "flags": { "use_scope_descriptions_for_consent": true } }"

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer API_ACCESS_TOKEN",
      'cache-control': "no-cache"
      }

  conn.request("PATCH", "/{yourDomain}/api/v2/tenants/settings", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/tenants/settings")

  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 API_ACCESS_TOKEN'
  request["cache-control"] = 'no-cache'
  request.body = "{ "flags": { "use_scope_descriptions_for_consent": true } }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = ["flags": ["use_scope_descriptions_for_consent": true]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/tenants/settings")! 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()
  ```
</AuthCodeGroup>

## Use scope names to generate consent prompt text

Set your tenant's **use\_scope\_descriptions\_for\_consent** flag to `false` by making the following API call:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/tenants/settings' \
    --header 'authorization: Bearer API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "flags": { "use_scope_descriptions_for_consent": false } }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/tenants/settings");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer API_ACCESS_TOKEN");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("application/json", "{ "flags": { "use_scope_descriptions_for_consent": false } }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/tenants/settings"

  	payload := strings.NewReader("{ "flags": { "use_scope_descriptions_for_consent": false } }")

  	req, _ := http.NewRequest("PATCH", url, payload)

  	req.Header.Add("content-type", "application/json")
  	req.Header.Add("authorization", "Bearer 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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/tenants/settings")
    .header("content-type", "application/json")
    .header("authorization", "Bearer API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "flags": { "use_scope_descriptions_for_consent": false } }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/tenants/settings',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: {flags: {use_scope_descriptions_for_consent: false}}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"flags": @{ @"use_scope_descriptions_for_consent": @NO } };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/tenants/settings"]
                                                         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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/tenants/settings",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "PATCH",
    CURLOPT_POSTFIELDS => "{ "flags": { "use_scope_descriptions_for_consent": false } }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer 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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "flags": { "use_scope_descriptions_for_consent": false } }"

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer API_ACCESS_TOKEN",
      'cache-control': "no-cache"
      }

  conn.request("PATCH", "/{yourDomain}/api/v2/tenants/settings", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/tenants/settings")

  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 API_ACCESS_TOKEN'
  request["cache-control"] = 'no-cache'
  request.body = "{ "flags": { "use_scope_descriptions_for_consent": false } }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = ["flags": ["use_scope_descriptions_for_consent": false]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/tenants/settings")! 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()
  ```
</AuthCodeGroup>

## Learn more

* [Scopes](/docs/get-started/apis/scopes)
* [Sample Use Cases: Scopes and Claims](/docs/get-started/apis/scopes/sample-use-cases-scopes-and-claims)
* [OpenID Connect Scopes](/docs/get-started/apis/scopes/openid-connect-scopes)
* [API Scopes](/docs/get-started/apis/scopes/api-scopes)
* [Auth0 Security Bulletin for Assigning Scopes Based on Email Address](/docs/secure/security-guidance/security-bulletins/2019-09-05-scopes)


# Customize Universal Login
Source: https://auth0.com/docs/customize/login-pages/universal-login

An overview of Universal Login customization

[Auth0 Universal Login](/docs/authenticate/login/auth0-universal-login) provides the essential feature of an <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip>: the login flow. When a user needs to prove their identity to gain access to your application, you can redirect them to <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> and let Auth0 handle the authentication process.

Configuring Universal Login is dynamic and does not require any application-level changes, as web pages hosted on Auth0’s centralized <Tooltip href="/docs/glossary?term=authentication+server">authentication server</Tooltip> completely drive the login flow. Additionally, you don’t need to manually update your code for your applications to benefit from improvements Auth0 makes to Universal Login.

From the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, you can customize the appearance and behavior of login pages to create a consistent, branded experience. For advanced use cases, you can also change the code of each page individually.

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/customize/login-pages/universal-login/customize-themes">Customize Universal Login Page Themes</a></td>
      <td>How to customize Universal Login branding with the no-code editor.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/login-pages/universal-login/customize-templates">Customize Universal Login Page Templates</a></td>
      <td>How to use page templates for advanced customization.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/login-pages/universal-login/customize-text-elements">Customize Universal Login Text Elements</a></td>
      <td>How to modify the text displayed on Universal Login pages.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts">Customize Signup and Login Prompts</a></td>
      <td>How to add custom content to Universal Login signup and login prompts.</td>
    </tr>
  </tbody>
</table>


# Customize Signup and Login Prompts
Source: https://auth0.com/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts

Learn how to customize signup and login prompts for Universal Login

<Card title="Before you start">
  1. Make sure your tenant has a [**Custom Domain**](/docs/customize/custom-domains) configured.
  2. Confirm you are using [**Universal Login**](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience) for all signup and login prompts, and ensure the **Customize Login Page** toggle has been disabled for Login Prompts.
  3. Check that you have a [Custom Page Template](/docs/customize/login-pages/universal-login/customize-templates#custom-sign-up-prompts) configured.
</Card>

**Customize Signup and Login Prompts** is a feature that allows customers with <Tooltip href="/docs/glossary?term=Custom+Domain">Custom Domain</Tooltip> and Custom Page Template enabled to add custom fields and content to their app’s signup and login prompts.

#### Use Cases

Customize Signup and Login Prompts supports two use cases: **custom content** and **data capture.**

**Custom content** is static content like text, links, or images placed directly on the signup and login prompts.

**Data capture** uses form elements dynamically added to the signup and login prompts, which is useful for collecting and validating user consent or user-produced data like surname.

Data capture is available for database connections authenticated by password . When using a <Tooltip href="/docs/glossary?term=passwordless">passwordless</Tooltip> connection, data capture is available when authenticating by email or SMS one-time password. Passkeys and magic links are not yet supported.

<Warning>
  Only use Signup and Login Prompt Customizations to convey or collect sensitive or regulated data as permitted under your agreement with Okta.
</Warning>

#### Terminology

A **prompt** is a specific step in a given authentication flow. Each prompt has at least one **screen** and, depending on tenant configuration, each supported screen has either four or six **entry points,** which arelocations in the screen where custom code (**partials**) can be inserted.

The following prompts can be customized:

* `signup`
* `signup-id`
* `signup-password`
* `login`
* `login-id`
* `login-password`
* `login-passwordless`

  * `login-passwordless-sms-otp`
  * `login-passwordless-email-code`

Partials support HTML, CSS, Javascript, and [Liquid syntax](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers) to power conditional logic and dynamic variables. In addition, any Liquid variable that is available to the [Page Template](/docs/customize/login-pages/universal-login/customize-templates) is also supported.

These entry points available when a database or passwordless connection is enabled:

* `form-content-start`
* `form-content-end`
* `form-footer-start`
* `form-footer-end`

The following entry points are available when at least one social or enterprise connection is enabled:

* `secondary-actions-start`
* `secondary-actions-end`

<Frame>
  <img alt="Screenshots of each Custom Prompt option and their partials" />
</Frame>

#### Use the Management API to Manage Partials

Partials can be a maximum of 10,000 characters and are managed by the [Auth0 Management API](https://auth0.com/docs/api/management/v2/prompts/put-partials) at `/v2/prompts/{prompts_name}/partials`. Every prompt must specify the `Screen` when adding, updating, or deleting a partial. Below is an example call to view all existing partials for a prompt, noting that `ulp-container` prefix is not required when referencing entry points in API calls.

```json lines theme={null}
GET /api/v2/prompts/signup-id/partials
# response
# success code: 200
# not found code: 404
body: {
  "signup-id": {
    "form-content-start": "<div>HTML or Liquid</div>...",
    "form-content-end": "<div>HTML or Liquid</div>..."
  }
}
```

Partials can also be managed using Auth0 CLI’s <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> Customize Interface by running `auth0 ul customize` in your terminal.

<Frame>
  <img alt="An image showing the command-line interface for Partials. " />
</Frame>

#### Style and Validate Form Inputs

Customize Signup and Login Prompts offers pre-built styles and support for client-side validations for certain HTML form elements. The following elements are supported:

* `<input type="text">`
* `<input type="number">`
* `<input type="checkbox">`
* `<input type="password">`
* `<input type="email">`
* `<input type="tel">`
* `<input type="url">`
* `<select>`
* `<textarea>`

To use pre-built input styles, wrap your form element of choice in a `<div>` with the `ulp-field` class. Similarly, add the `ulp-error` class to the same `<div>` to use pre-built error styles. If the `ulp-error-info` element is present, a styled error message will also be displayed.

#### Client-Side Validation

The feature's client-side validation framework allows customers to validate user input using HTML attributes to execute one or more custom validation functions. Validation functions can be included directly in the Partial or included in the `<head>` of the page template.

To add client-side validation to a form element:

* Reference the validation function using the `data-ulp-validation-function` attribute on the `<div class="ulp-error-info">` element.
* Declare which DOM events the validation function should be run on using the `data-ulp-validation-event-listeners` attribute on the `<div class="ulp-error-info">` element, noting that validations run automatically on submission.
* For WCAG compliance, inputs must be programmatically linked to their error messages - for example, by using `aria-describedby="error-id"` and `aria-invalid="true"` - to ensure screen readers announce validation errors.

<AccordionGroup>
  <Accordion title="Input Field Elements: Pre-built styling for input fields">
    ```html lines theme={null}
    <div class="ulp-field">
      <label for="first-name">First Name</label>
      <input type="text" name="ulp-first-name" id="first-name">
      <div class="ulp-error-info">
        First Name is Required
      </div>
    </div>
    ```
  </Accordion>

  <Accordion title="Select Elements: Pre-built styling for select fields">
    ```html lines theme={null}
    <div class="ulp-field">
      <label for="preferred-language">Preferred Language</label>
      <select name="ulp-preferred-language" id="preferred-language">
        <option></option>
        <option value="english">English</option>
        <option value="french">French</option>
        <option value="spanish">Spanish</option>
      </select>
      <div class="ulp-error-info">
        Please Select a Language.
      </div>
    </div>
    ```
  </Accordion>

  <Accordion title="Text Elements: Pre-built styling for text fields">
    ```html lines theme={null}
    <div class="ulp-field">
      <label for="comments">Comments</label>
      <textarea type="text" name="ulp-comments" id="comments"></textarea>
      <div class="ulp-error-info">
        Please provide an answer.
      </div>
    </div>
    ```
  </Accordion>

  <Accordion title="Checkbox Elements: Pre-built styling for checkbox fields">
    ```html lines theme={null}
    <div class="ulp-field">
      <input type="checkbox" name="ulp-terms-of-service" id="terms-of-service">
      <label for="terms-of-service">
        I agree to the <a href="#">Terms of Service</a>
      </label>
      <div class="ulp-error-info">
        Please agree to the Terms of Service.
      </div>
    </div>
    ```
  </Accordion>

  <Accordion title="Phone Number Validation: Client-Side Phone Number Validation">
    ```javascript lines theme={null}
    // Validation Function
    <script>
      function validatePhoneFunction(element, formSubmitted) {
        if (!formSubmitted) {
          return true;
        }
        return element.value.replace(/\D/g, '').length === 10;
      }
    </script>

    // Custom Input Field including the validation error HTML
    <div class="ulp-field">
      <label for="ulp-field-phone">Phone Number</label>
      <input type="text" name="ulp-field-phone" id="ulp-field-phone">
      <div
        class="ulp-error-info"
        data-ulp-validation-function="validatePhoneFunction"
        data-ulp-validation-event-listeners="blur,change,input,focus">
        Invalid phone number
      </div>
    </div>
    ```
  </Accordion>

  <Accordion title="Screen Reader Validation: Validation for accessible error messages">
    ```html lines theme={null}
    <script>
      function requiredTextFunction(element, formSubmitted) {
        if (!formSubmitted) return true;
        return element.value.trim().length > 0;
      }
    </script>

    <div class="ulp-field">
      <label for="ulp-phone">Phone Number</label>
      <input
        type="text"
        id="ulp-phone"
        name="ulp-field-phone"
        aria-describedby="error-phone-required"
        aria-invalid="true"
        required
      >
      <div
        id="error-phone-required"
        class="ulp-error-info"
        role="alert"
        data-ulp-validation-function="requiredTextFunction"
        data-ulp-validation-event-listeners="change"
      >
        Phone number is required
      </div>
    </div>
    ```
  </Accordion>
</AccordionGroup>

<Warning>
  Be cautious when using third-party JavaScript on your signup page. Sensitive security-related information often flows through the signup page, leaving it vulnerable to cross-site scripting.

  Whenever possible, Auth0 recommends validating user-provided data before submitting.
</Warning>

#### Localize Content

Partial content can be localized by defining new custom text variables using the [Custom Text API](https://auth0.com/docs/api/management/v2/prompts/put-custom-text-by-language). Up to thirty custom text variables can be defined per screen/language combination.

##### Create or Update a Custom Text Variable

The Custom Text API is available [here](https://auth0.com/docs/api/management/v2/prompts/get-custom-text-by-language) and each variable follows a `var-<name>` naming convention. Calls to the API must specify the screen when adding, updating, or deleting a custom text variable. Markdown links are supported and are converted to HTML `<a>` elements before being displayed to users.

Below is an example call to add a variable for the text of a terms of service checkbox label in English and Spanish. See the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to learn more.

```json lines theme={null}
# PUT /api/v2/prompts/signup-id/custom-text/en
{
  "signup": {
    "var-tos": "I agree with the [Terms of Service](https://en.example.com/tos)"
  }
}

# PUT /api/v2/prompts/signup-id/custom-text/es
{
  "signup": {
    "var-tos": "Estoy de acuerdo con los [Términos de Servicio](https://es.example.com/tos)"
  }
}
```

##### Use a Custom Text Variable in a Partial

Custom text variables are referenced in partials using the `prompts.screen.text` object; the reference for the `var-tos` example in the previous section is `prompt.screen.texts.varTos`. See below for an example of how to use a previously created variable in a partial on the Signup ID Prompt, noting that the Management API's `var-tos` variable is referenced as `varTos` in the partial.

```json lines theme={null}
# PUT api/v2/prompts/signup/partials
{
  "signup": {
    "form-content-end": "<div class='ulp-field'><input type='checkbox' name='ulp-terms-of-service' id='terms-of-service'><label for='terms-of-service'>{{ prompt.screen.texts.varTos }}</label></div>"
  }
}
```

#### Validate and Save Captured Data

Data captured by custom form elements is available in Actions, and Auth0 recommends that the collected data be validated.

<Warning>
  When using custom form elements, you must include the `ulp-` prefix with any input names to ensure the data can be used with Actions.
</Warning>

Each Action receives the captured data as an object on the `event.request.body`. Customers can return a validation error by using the `api.validation.error` function.

When using a database connection:

* Data from the Signup Prompts is accessible on the Pre User Registration trigger, and if a validation error is returned, the user is prevented from registering.
* Data from Login Prompts is accessible on the Post Login trigger, and if a validation error is returned, the validation error is forwarded to the customer’s application error page.

When using a Passwordless connection:

* Data from both the Signup and Login Prompts is accessible on the Post Login trigger, and if a validation error is returned, the validation error is forwarded to the customer’s application error page.

<Warning>
  Sanitize any data that you collect on the form before saving or rendering it.

  * Ensure any data being saved has passed through [Liquid’s `{{escape}}` helper function](https://shopify.github.io/liquid/filters/escape/)
  * If you render data in an Email Template, remove Liquid syntax
  * If you render data on a webpage, escape HTML entities
  * If you save data to a database, use parameterized queries
  * If you pass data into query string, encode with eg: `{{encodeURI}}` or `{{encodeURIParam}}`

  For more information regarding risk mitigation and best practices for securely storing data see [this cheatsheet](https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html).
</Warning>

##### Save to User Metadata

From the Action, captured data can be sent to an external API for validation and storage or saved in `user_metadata` on the user via `api.user.setUserMetadata`.

```js lines theme={null}
// Given this code in the signup form
// <div class="ulp-field">
//   <label for="full-name">Full Name</label>
//   <input type="text" name="ulp-full-name" id="full-name">
// </div>

exports.onExecutePreUserRegistration = async (event, api) => {
  const fullName = event.request.body['ulp-full-name'];
  if(!fullName) {
    api.validation.error("invalid_payload", "Missing Name");
    return;
  }

  api.user.setUserMetadata("fullName", fullName);
};
```

## Learn more

* [Use Dynamic Variables to Internationalize Custom Form Elements](/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts/use-dynamic-variables-to-internationalize-custom-form-elements)


# Configure Flexible Connection Switching
Source: https://auth0.com/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts/connection-switching

Learn how you can implement flexible connection switching with Universal Login

Flexible connection switching is an optional feature that allows users to choose their method of authentication when logging in to an application. When implemented, your application's login screen presents users with the option to authenticate with either traditional database credentials or a <Tooltip href="/docs/glossary?term=passwordless">passwordless</Tooltip> connection. Users who select a [passwordless connection](/docs/authenticate/passwordless) receive a one-time password (OTP) through email or SMS that they can use to log in to your application.

Flexible connection switching uses [custom Universal Login prompts](/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts) to provide users with a more autonomous authentication experience.

## Before you begin

Before you can implement flexible connection switching, ensure the following requirements are met:

* Use [Universal Login](/docs/authenticate/login/auth0-universal-login).

  * This feature is not available for custom login pages.
* Configure a [custom domain](/docs/customize/custom-domains).
* Enable the following for your application:

  * [Identifier First authentication](/docs/authenticate/login/auth0-universal-login/identifier-first)
  * [Database connection](/docs/authenticate/database-connections)
  * [Email or SMS passwordless authentication](/docs/authenticate/login/auth0-universal-login/passwordless-login/email-or-sms)

## Implement flexible connection switching

To implement this feature, use the [Auth0 Management API](https://auth0.com/docs/api/management/v2) to configure custom signup and login prompt partials. Partials refer to custom code inserted into an entry point within a prompt screen, such as the login screen. To learn more, review [Customize Signup and Login Prompts](/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts).

To implement flexible connection switching, you will configure custom prompt partials with the following parameters:

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Example</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>state</code></td>
      <td>Renders the current page's state value, which is opaque and used for security purposes.<br /><br />To learn more about current screen information, review <a href="/docs/customize/login-pages/universal-login/customize-templates#current-screen-information">Customize Univeral Login Page Templates</a>.</td>
      <td><code>\<input type='hidden' name='state' value='\{\{state}}'></code></td>
    </tr>

    <tr>
      <td><code>connection</code></td>
      <td>Name and type of the connection.<br /><br />For passwordless connections, value is either <code>email</code> or <code>sms</code>.</td>
      <td><code>\<input type='hidden' name='connection' value='email'></code></td>
    </tr>
  </tbody>
</table>

<Warning>
  In the code samples below, ensure you replace the placeholders with the appropriate values:

  * Replace `{yourDomain}` with `yourdomain.auth0.com`.
  * Replace `{mgmtApiToken}` with your access token.
</Warning>

### Configure signup prompt

You can configure the `signup-password` prompt using the [Set partials for a prompt](https://auth0.com/docs/api/management/v2/prompts/put-partials) endpoint:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PUT \
    --url 'https://{yourDomain}/api/v2/prompts/signup-password/partials' \
    --header 'authorization: Bearer {mgmtApiToken}' \
    --header 'content-type: application/json' \
    --data '{"signup-password":{"form-footer-start":"<form method=\"post\" data-form-secondary=\"true\"><input type=\"hidden\" name=\"state\" value=\"{{state}}\"> <input type=\"hidden\" name=\"connection\" value=\"email\"> <button type=\"submit\" id=\"switchConnectionButton\" style=\"background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;\" data-action-button-secondary=\"true\"> <span>Send a secure code by email</span> </button></form>"}}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/prompts/signup-password/partials");
  var request = new RestRequest(Method.PUT);
  request.AddHeader("authorization", "Bearer {mgmtApiToken}");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"signup-password":{"form-footer-start":"<form method=\"post\" data-form-secondary=\"true\"><input type=\"hidden\" name=\"state\" value=\"{{state}}\"> <input type=\"hidden\" name=\"connection\" value=\"email\"> <button type=\"submit\" id=\"switchConnectionButton\" style=\"background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;\" data-action-button-secondary=\"true\"> <span>Send a secure code by email</span> </button></form>"}}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/prompts/signup-password/partials"

  	payload := strings.NewReader("{"signup-password":{"form-footer-start":"<form method=\\"post\\" data-form-secondary=\\"true\\"><input type=\\"hidden\\" name=\\"state\\" value=\\"{{state}}\\"> <input type=\\"hidden\\" name=\\"connection\\" value=\\"email\\"> <button type=\\"submit\\" id=\\"switchConnectionButton\\" style=\\"background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;\\" data-action-button-secondary=\\"true\\"> <span>Send a secure code by email</span> </button></form>"}}")

  	req, _ := http.NewRequest("PUT", url, payload)

  	req.Header.Add("authorization", "Bearer {mgmtApiToken}")
  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.put("https://{yourDomain}/api/v2/prompts/signup-password/partials")
    .header("authorization", "Bearer {mgmtApiToken}")
    .header("content-type", "application/json")
    .body("{"signup-password":{"form-footer-start":"<form method=\"post\" data-form-secondary=\"true\"><input type=\"hidden\" name=\"state\" value=\"{{state}}\"> <input type=\"hidden\" name=\"connection\" value=\"email\"> <button type=\"submit\" id=\"switchConnectionButton\" style=\"background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;\" data-action-button-secondary=\"true\"> <span>Send a secure code by email</span> </button></form>"}}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PUT',
    url: 'https://{yourDomain}/api/v2/prompts/signup-password/partials',
    headers: {authorization: 'Bearer {mgmtApiToken}', 'content-type': 'application/json'},
    data: {
      'signup-password': {
        'form-footer-start': '<form method="post" data-form-secondary="true"><input type="hidden" name="state" value="{{state}}"> <input type="hidden" name="connection" value="email"> <button type="submit" id="switchConnectionButton" style="background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;" data-action-button-secondary="true"> <span>Send a secure code by email</span> </button></form>'
      }
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {mgmtApiToken}",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"signup-password": @{ @"form-footer-start": @"<form method="post" data-form-secondary="true"><input type="hidden" name="state" value="{{state}}"> <input type="hidden" name="connection" value="email"> <button type="submit" id="switchConnectionButton" style="background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;" data-action-button-secondary="true"> <span>Send a secure code by email</span> </button></form>" } };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/prompts/signup-password/partials"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"PUT"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/prompts/signup-password/partials",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_POSTFIELDS => "{"signup-password":{"form-footer-start":"<form method=\\"post\\" data-form-secondary=\\"true\\"><input type=\\"hidden\\" name=\\"state\\" value=\\"{{state}}\\"> <input type=\\"hidden\\" name=\\"connection\\" value=\\"email\\"> <button type=\\"submit\\" id=\\"switchConnectionButton\\" style=\\"background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;\\" data-action-button-secondary=\\"true\\"> <span>Send a secure code by email</span> </button></form>"}}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {mgmtApiToken}",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"signup-password":{"form-footer-start":"<form method=\\"post\\" data-form-secondary=\\"true\\"><input type=\\"hidden\\" name=\\"state\\" value=\\"{{state}}\\"> <input type=\\"hidden\\" name=\\"connection\\" value=\\"email\\"> <button type=\\"submit\\" id=\\"switchConnectionButton\\" style=\\"background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;\\" data-action-button-secondary=\\"true\\"> <span>Send a secure code by email</span> </button></form>"}}"

  headers = {
      'authorization': "Bearer {mgmtApiToken}",
      'content-type': "application/json"
      }

  conn.request("PUT", "/{yourDomain}/api/v2/prompts/signup-password/partials", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/prompts/signup-password/partials")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Put.new(url)
  request["authorization"] = 'Bearer {mgmtApiToken}'
  request["content-type"] = 'application/json'
  request.body = "{"signup-password":{"form-footer-start":"<form method=\\"post\\" data-form-secondary=\\"true\\"><input type=\\"hidden\\" name=\\"state\\" value=\\"{{state}}\\"> <input type=\\"hidden\\" name=\\"connection\\" value=\\"email\\"> <button type=\\"submit\\" id=\\"switchConnectionButton\\" style=\\"background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;\\" data-action-button-secondary=\\"true\\"> <span>Send a secure code by email</span> </button></form>"}}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer {mgmtApiToken}",
    "content-type": "application/json"
  ]
  let parameters = ["signup-password": ["form-footer-start": "<form method="post" data-form-secondary="true"><input type="hidden" name="state" value="{{state}}"> <input type="hidden" name="connection" value="email"> <button type="submit" id="switchConnectionButton" style="background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;" data-action-button-secondary="true"> <span>Send a secure code by email</span> </button></form>"]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/prompts/signup-password/partials")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "PUT"
  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()
  ```
</AuthCodeGroup>

As a result, a **Send a secure code by email button** is added to the `signup-password` screen. When a user selects this button, it submits a form body containing the login state parameter and the name of the desired connection.

### Configure login prompts

For best results, configuring the login prompt for both password and passwordless connections is recommended.

You can configure the `login-password` prompt using the [Set partials for a prompt](https://auth0.com/docs/api/management/v2/prompts/put-partials) endpoint:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PUT \
    --url 'https://{yourDomain}/api/v2/prompts/login-password/partials' \
    --header 'authorization: Bearer {mgmtApiToken}' \
    --header 'content-type: application/json' \
    --data '{"login-password":{"form-footer-start":"<form method=\"post\" data-form-secondary=\"true\"><input type=\"hidden\" name=\"state\" value=\"{{state}}\"> <input type=\"hidden\" name=\"connection\" value=\"email\"> <button type=\"submit\" id=\"switchConnectionButton\" style=\"background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;\" data-action-button-secondary=\"true\"> <span>Send a secure code by email</span> </button></form>"}}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/prompts/login-password/partials");
  var request = new RestRequest(Method.PUT);
  request.AddHeader("authorization", "Bearer {mgmtApiToken}");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"login-password":{"form-footer-start":"<form method=\"post\" data-form-secondary=\"true\"><input type=\"hidden\" name=\"state\" value=\"{{state}}\"> <input type=\"hidden\" name=\"connection\" value=\"email\"> <button type=\"submit\" id=\"switchConnectionButton\" style=\"background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;\" data-action-button-secondary=\"true\"> <span>Send a secure code by email</span> </button></form>"}}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/prompts/login-password/partials"

  	payload := strings.NewReader("{"login-password":{"form-footer-start":"<form method='post' data-form-secondary='true'><input type='hidden' name='state' value='{{state}}'> <input type='hidden' name='connection' value='email'> <button type='submit' id='switchConnectionButton' style='background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;' data-action-button-secondary='true'> <span>Send a secure code by email</span> </button></form>"}}")

  	req, _ := http.NewRequest("PUT", url, payload)

  	req.Header.Add("authorization", "Bearer {mgmtApiToken}")
  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }n(string(body))
  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.put("https://{yourDomain}/api/v2/prompts/login-password/partials")
    .header("authorization", "Bearer {mgmtApiToken}")
    .header("content-type", "application/json")
    .body("{"login-password":{"form-footer-start":"<form method=\"post\" data-form-secondary=\"true\"><input type=\"hidden\" name=\"state\" value=\"{{state}}\"> <input type=\"hidden\" name=\"connection\" value=\"email\"> <button type=\"submit\" id=\"switchConnectionButton\" style=\"background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;\" data-action-button-secondary=\"true\"> <span>Send a secure code by email</span> </button></form>"}}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PUT',
    url: 'https://{yourDomain}/api/v2/prompts/login-password/partials',
    headers: {authorization: 'Bearer {mgmtApiToken}', 'content-type': 'application/json'},
    data: {
      'login-password': {
        'form-footer-start': '<form method='post' data-form-secondary='true'><input type='hidden' name='state' value='{{state}}'> <input type='hidden' name='connection' value='email'> <button type='submit' id='switchConnectionButton' style='background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;' data-action-button-secondary='true'> <span>Send a secure code by email</span> </button></form>'
      }
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {mgmtApiToken}",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"login-password": @{ @"form-footer-start": @"<form method='post' data-form-secondary='true'><input type='hidden' name='state' value='{{state}}'> <input type='hidden' name='connection' value='email'> <button type='submit' id='switchConnectionButton' style='background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;' data-action-button-secondary='true'> <span>Send a secure code by email</span> </button></form>" } };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/prompts/login-password/partials"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"PUT"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/prompts/login-password/partials",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_POSTFIELDS => "{"login-password":{"form-footer-start":"<form method='post' data-form-secondary='true'><input type='hidden' name='state' value='{{state}}'> <input type='hidden' name='connection' value='email'> <button type='submit' id='switchConnectionButton' style='background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;' data-action-button-secondary='true'> <span>Send a secure code by email</span> </button></form>"}}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {mgmtApiToken}",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"login-password":{"form-footer-start":"<form method='post' data-form-secondary='true'><input type='hidden' name='state' value='{{state}}'> <input type='hidden' name='connection' value='email'> <button type='submit' id='switchConnectionButton' style='background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;' data-action-button-secondary='true'> <span>Send a secure code by email</span> </button></form>"}}"

  headers = {
      'authorization': "Bearer {mgmtApiToken}",
      'content-type': "application/json"
      }

  conn.request("PUT", "/{yourDomain}/api/v2/prompts/login-password/partials", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/prompts/login-password/partials")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Put.new(url)
  request["authorization"] = 'Bearer {mgmtApiToken}'
  request["content-type"] = 'application/json'
  request.body = "{"login-password":{"form-footer-start":"<form method='post' data-form-secondary='true'><input type='hidden' name='state' value='{{state}}'> <input type='hidden' name='connection' value='email'> <button type='submit' id='switchConnectionButton' style='background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;' data-action-button-secondary='true'> <span>Send a secure code by email</span> </button></form>"}}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer {mgmtApiToken}",
    "content-type": "application/json"
  ]
  let parameters = ["login-password": ["form-footer-start": "<form method='post' data-form-secondary='true'><input type='hidden' name='state' value='{{state}}'> <input type='hidden' name='connection' value='email'> <button type='submit' id='switchConnectionButton' style='background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;' data-action-button-secondary='true'> <span>Send a secure code by email</span> </button></form>"]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/prompts/login-password/partials")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "PUT"
  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()
  ```
</AuthCodeGroup>

As a result, a **Send a secure code by email button** is added to the `login-password` screen. When a user selects this button, it submits a form body containing the login state parameter and the name of the desired connection.

Similarly, you can configure the `login-passwordless` prompt using the [Set partials for a prompt](https://auth0.com/docs/api/management/v2/prompts/put-partials) endpoint:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PUT \
    --url 'https://{yourDomain}/api/v2/prompts/login-passwordless/partials' \
    --header 'authorization: Bearer {mgmtApiToken}' \
    --header 'content-type: application/json' \
    --data '{"login-passwordless-email-code":{"form-footer-start":"   Use Password Instead "}}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/prompts/login-passwordless/partials");
  var request = new RestRequest(Method.PUT);
  request.AddHeader("authorization", "Bearer {mgmtApiToken}");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"login-passwordless-email-code":{"form-footer-start":"   Use Password Instead "}}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/prompts/login-passwordless/partials"

  	payload := strings.NewReader("{"login-passwordless-email-code":{"form-footer-start":"<form method='post' data-form-secondary='true'><input type='hidden'  name='state' value='{{state}}'> <input type='hidden' name='connection' value='Username-Password-Authentication'> <button type='submit' id='switchConnectionButton' style='background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;' data-action-button-secondary='true'> <span>Use Password Instead</span> </button></form>"}}")

  	req, _ := http.NewRequest("PUT", url, payload)

  	req.Header.Add("authorization", "Bearer {mgmtApiToken}")
  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.put("https://{yourDomain}/api/v2/prompts/login-passwordless/partials")
    .header("authorization", "Bearer {mgmtApiToken}")
    .header("content-type", "application/json")
    .body("{"login-passwordless-email-code":{"form-footer-start":"   Use Password Instead "}}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PUT',
    url: 'https://{yourDomain}/api/v2/prompts/login-passwordless/partials',
    headers: {authorization: 'Bearer {mgmtApiToken}', 'content-type': 'application/json'},
    data: {
      'login-passwordless-email-code': {
        'form-footer-start': '<form method='post' data-form-secondary='true'><input type='hidden'  name='state' value='{{state}}'> <input type='hidden' name='connection' value='Username-Password-Authentication'> <button type='submit' id='switchConnectionButton' style='background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;' data-action-button-secondary='true'> <span>Use Password Instead</span> </button></form>'
      }
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {mgmtApiToken}",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"login-passwordless-email-code": @{ @"form-footer-start": @"<form method='post' data-form-secondary='true'><input type='hidden'  name='state' value='{{state}}'> <input type='hidden' name='connection' value='Username-Password-Authentication'> <button type='submit' id='switchConnectionButton' style='background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;' data-action-button-secondary='true'> <span>Use Password Instead</span> </button></form>" } };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/prompts/login-passwordless/partials"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"PUT"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/prompts/login-passwordless/partials",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_POSTFIELDS => "{"login-passwordless-email-code":{"form-footer-start":"<form method='post' data-form-secondary='true'><input type='hidden'  name='state' value='{{state}}'> <input type='hidden' name='connection' value='Username-Password-Authentication'> <button type='submit' id='switchConnectionButton' style='background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;' data-action-button-secondary='true'> <span>Use Password Instead</span> </button></form>"}}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {mgmtApiToken}",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"login-passwordless-email-code":{"form-footer-start":"<form method='post' data-form-secondary='true'><input type='hidden'  name='state' value='{{state}}'> <input type='hidden' name='connection' value='Username-Password-Authentication'> <button type='submit' id='switchConnectionButton' style='background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;' data-action-button-secondary='true'> <span>Use Password Instead</span> </button></form>"}}"

  headers = {
      'authorization': "Bearer {mgmtApiToken}",
      'content-type': "application/json"
      }

  conn.request("PUT", "/{yourDomain}/api/v2/prompts/login-passwordless/partials", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/prompts/login-passwordless/partials")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Put.new(url)
  request["authorization"] = 'Bearer {mgmtApiToken}'
  request["content-type"] = 'application/json'
  request.body = "{"login-passwordless-email-code":{"form-footer-start":"<form method='post' data-form-secondary='true'><input type='hidden'  name='state' value='{{state}}'> <input type='hidden' name='connection' value='Username-Password-Authentication'> <button type='submit' id='switchConnectionButton' style='background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;' data-action-button-secondary='true'> <span>Use Password Instead</span> </button></form>"}}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer {mgmtApiToken}",
    "content-type": "application/json"
  ]
  let parameters = ["login-passwordless-email-code": ["form-footer-start": "<form method='post' data-form-secondary='true'><input type='hidden'  name='state' value='{{state}}'> <input type='hidden' name='connection' value='Username-Password-Authentication'> <button type='submit' id='switchConnectionButton' style='background: #635dff; width: 100%; padding: 12px 16px; border: none; color: white;' data-action-button-secondary='true'> <span>Use Password Instead</span> </button></form>"]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/prompts/login-passwordless/partials")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "PUT"
  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()
  ```
</AuthCodeGroup>


# Configure Flexible Language Selection
Source: https://auth0.com/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts/language-selection

Learn how you can add a preferred language menu to Universal Login prompts.

Flexible language selection is an optional feature that allows users to select their preferred language on <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> prompts associated with your application, such as the login screen. You can configure this feature individually for different Universal Login prompts.

After implementing this feature for a specific prompt, a language selection menu is added to the associated screen. Users can choose a preferred language from this menu to automatically render the prompt in that language.

<Frame>
  <img alt="Two Universal Login prompts showing the language selection menu. " />
</Frame>

## Before you begin

Before you can implement flexible language selection, ensure the following requirements are met:

* Use [Universal Login](/docs/authenticate/login/auth0-universal-login).

  * This feature is not available for custom login pages.
* Configure a [custom domain](/docs/customize/custom-domains).
* Enable the languages you plan to add to your prompts in your Auth0 tenant.

  * On the Auth0 Dashboard, navigate to [Settings > General > Languages](https://manage.auth0.com/#/tenant/general) and enable one or more desired languages.

    * For more information, review [Universal Login Internationalization](/docs/customize/internationalization-and-localization/universal-login-internationalization).

## Implement flexible language selection

Setting up flexible language selection includes two primary steps:

1. Preparing your page template to facilitate language selection.
2. Configuring individual prompts to display language selection to users.

### Prepare your Universal Login page template

To get started, add the following script to your [Universal Login page template](/docs/customize/login-pages/universal-login/customize-templates) to facilitate language selection.

```html lines theme={null}
<script>
  function updateSelectedLanguage() {
    const selectElement = document.getElementById('language');
    const selectedValue = selectElement.value;
    const options = selectElement.options;
    for (let i = 0; i < options.length; i++) {
      if (options[i].value === selectedValue) {
        options[i].selected = true;
      } else {
        options[i].selected = false;
      }
    }
    document.getElementById('changeLanguage').click();
  }
</script>
```

This script enables Universal Login prompts to render a dynamic language selection menu. Users can access this menu to apply their preferred language to a configured prompt.

To add this script to your page template, use the [Set Template for Universal Login](https://auth0.com/docs/api/management/v2/branding/put-universal-login) endpoint.

<Warning>
  Be aware that this call will **overwrite any existing configurations** you have made to your Universal Login page template. To avoid any disruptions, ensure you include all necessary page template customizations in this call.
</Warning>

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PUT \
    --url 'https://{yourDomain}/api/v2/branding/templates/universal-login' \
    --header 'authorization: Bearer MANAGEMENT_API_TOKEN' \
    --header 'content-type: text/html' \
    --data '<!DOCTYPE html>
  <html>
  <head>{%- auth0:head -%}</head>
  <body class='''_widget-auto-layout'''>{%- auth0:widget -%}</body>
  <script>
    function updateSelectedLanguage() {
      const selectElement = document.getElementById('''language''');
      const selectedValue = selectElement.value;
      const options = selectElement.options;
      for (let i = 0; i < options.length; i++) {
        if (options[i].value === selectedValue) {
          options[i].selected = true;
        } else {
          options[i].selected = false;
        }
      }
      document.getElementById('''changeLanguage''').click();
    }
  </script>'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/branding/templates/universal-login");
  var request = new RestRequest(Method.PUT);
  request.AddHeader("content-type", "text/html");
  request.AddHeader("authorization", "Bearer MANAGEMENT_API_TOKEN");
  request.AddParameter("text/html", "

  {%- auth0:head -%}
  {%- auth0:widget -%}
  ", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/branding/templates/universal-login"

  	payload := strings.NewReader("<!DOCTYPE html>
  <html>
  <head>{%- auth0:head -%}</head>
  <body class='_widget-auto-layout'>{%- auth0:widget -%}</body>
  <script>
    function updateSelectedLanguage() {
      const selectElement = document.getElementById('language');
      const selectedValue = selectElement.value;
      const options = selectElement.options;
      for (let i = 0; i < options.length; i++) {
        if (options[i].value === selectedValue) {
          options[i].selected = true;
        } else {
          options[i].selected = false;
        }
      }
      document.getElementById('changeLanguage').click();
    }
  </script>")

  	req, _ := http.NewRequest("PUT", url, payload)

  	req.Header.Add("content-type", "text/html")
  	req.Header.Add("authorization", "Bearer MANAGEMENT_API_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.put("https://{yourDomain}/api/v2/branding/templates/universal-login")
    .header("content-type", "text/html")
    .header("authorization", "Bearer MANAGEMENT_API_TOKEN")
    .body("<!DOCTYPE html>
  <html>
  <head>{%- auth0:head -%}</head>
  <body class='_widget-auto-layout'>{%- auth0:widget -%}</body>
  <script>
    function updateSelectedLanguage() {
      const selectElement = document.getElementById('language');
      const selectedValue = selectElement.value;
      const options = selectElement.options;
      for (let i = 0; i < options.length; i++) {
        if (options[i].value === selectedValue) {
          options[i].selected = true;
        } else {
          options[i].selected = false;
        }
      }
      document.getElementById('changeLanguage').click();
    }
  </script>")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PUT',
    url: 'https://{yourDomain}/api/v2/branding/templates/universal-login',
    headers: {'content-type': 'text/html', authorization: 'Bearer MANAGEMENT_API_TOKEN'},
    data: '<!DOCTYPE html>
  <html>
  <head>{%- auth0:head -%}</head>
  <body class='_widget-auto-layout'>{%- auth0:widget -%}</body>
  <script>
    function updateSelectedLanguage() {
      const selectElement = document.getElementById('language');
      const selectedValue = selectElement.value;
      const options = selectElement.options;
      for (let i = 0; i < options.length; i++) {
        if (options[i].value === selectedValue) {
          options[i].selected = true;
        } else {
          options[i].selected = false;
        }
      }
      document.getElementById('changeLanguage').click();
    }
  </script>'
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"text/html",
                             @"authorization": @"Bearer MANAGEMENT_API_TOKEN" };

  NSData *postData = [[NSData alloc] initWithData:[@"<!DOCTYPE html>
  <html>
  <head>{%- auth0:head -%}</head>
  <body class='_widget-auto-layout'>{%- auth0:widget -%}</body>
  <script>
    function updateSelectedLanguage() {
      const selectElement = document.getElementById('language');
      const selectedValue = selectElement.value;
      const options = selectElement.options;
      for (let i = 0; i < options.length; i++) {
        if (options[i].value === selectedValue) {
          options[i].selected = true;
        } else {
          options[i].selected = false;
        }
      }
      document.getElementById('changeLanguage').click();
    }
  </script>" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/branding/templates/universal-login"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"PUT"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/branding/templates/universal-login",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_POSTFIELDS => "<!DOCTYPE html>
  <html>
  <head>{%- auth0:head -%}</head>
  <body class='_widget-auto-layout'>{%- auth0:widget -%}</body>
  <script>
    function updateSelectedLanguage() {
      const selectElement = document.getElementById('language');
      const selectedValue = selectElement.value;
      const options = selectElement.options;
      for (let i = 0; i < options.length; i++) {
        if (options[i].value === selectedValue) {
          options[i].selected = true;
        } else {
          options[i].selected = false;
        }
      }
      document.getElementById('changeLanguage').click();
    }
  </script>",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MANAGEMENT_API_TOKEN",
      "content-type: text/html"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "<!DOCTYPE html>
  <html>
  <head>{%- auth0:head -%}</head>
  <body class='_widget-auto-layout'>{%- auth0:widget -%}</body>
  <script>
    function updateSelectedLanguage() {
      const selectElement = document.getElementById('language');
      const selectedValue = selectElement.value;
      const options = selectElement.options;
      for (let i = 0; i < options.length; i++) {
        if (options[i].value === selectedValue) {
          options[i].selected = true;
        } else {
          options[i].selected = false;
        }
      }
      document.getElementById('changeLanguage').click();
    }
  </script>"

  headers = {
      'content-type': "text/html",
      'authorization': "Bearer MANAGEMENT_API_TOKEN"
      }

  conn.request("PUT", "/{yourDomain}/api/v2/branding/templates/universal-login", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/branding/templates/universal-login")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Put.new(url)
  request["content-type"] = 'text/html'
  request["authorization"] = 'Bearer MANAGEMENT_API_TOKEN'
  request.body = "<!DOCTYPE html>
  <html>
  <head>{%- auth0:head -%}</head>
  <body class='_widget-auto-layout'>{%- auth0:widget -%}</body>
  <script>
    function updateSelectedLanguage() {
      const selectElement = document.getElementById('language');
      const selectedValue = selectElement.value;
      const options = selectElement.options;
      for (let i = 0; i < options.length; i++) {
        if (options[i].value === selectedValue) {
          options[i].selected = true;
        } else {
          options[i].selected = false;
        }
      }
      document.getElementById('changeLanguage').click();
    }
  </script>"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "text/html",
    "authorization": "Bearer MANAGEMENT_API_TOKEN"
  ]

  let postData = NSData(data: "<!DOCTYPE html>
  <html>
  <head>{%- auth0:head -%}</head>
  <body class='_widget-auto-layout'>{%- auth0:widget -%}</body>
  <script>
    function updateSelectedLanguage() {
      const selectElement = document.getElementById('language');
      const selectedValue = selectElement.value;
      const options = selectElement.options;
      for (let i = 0; i < options.length; i++) {
        if (options[i].value === selectedValue) {
          options[i].selected = true;
        } else {
          options[i].selected = false;
        }
      }
      document.getElementById('changeLanguage').click();
    }
  </script>".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/branding/templates/universal-login")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "PUT"
  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()
  ```
</AuthCodeGroup>

### Configure individual Universal Login prompts

Next, add language selection to one or more Universal Login prompts by configuring custom prompt partials. Partials refer to custom code inserted into an entry point within a prompt screen, such as the login screen. To learn more, review [Customize Signup and Login Prompts](/docs/customize/internationalization-and-localization/universal-login-internationalization).

To add language selection to a specific prompt, use the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to configure custom prompt partials with the following parameters:

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Example Value</strong>                             </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>language</code></td>
      <td>Required.<br /><br />One or more languages to include in the language selection menu displayed to users.</td>
      <td><code>es</code>,<code>fr</code>,<code>en</code></td>
    </tr>

    <tr>
      <td><code>persist</code></td>
      <td>Required.<br /><br />Determines whether the language should persist across the session.</td>
      <td><code>session</code></td>
    </tr>

    <tr>
      <td><code>action</code></td>
      <td>Optional.<br /><br />Use this parameter in situations where you want users to be able to update their language without advancing the prompt.<br /><br />If the value is provided, the form is <strong>not</strong> automatically submitted when a user changes their language. Otherwise, the prompt automatically advances when a different language is selected.</td>
      <td><code>change-language</code></td>
    </tr>
  </tbody>
</table>

Access the sections below to review code samples for different types of Universal Login prompts.

<Warning>
  In the code samples below, ensure you replace the placeholders with the appropriate values:

  * Replace `{yourDomain}` with `yourdomain.auth0.com`.
  * Replace `{mgmtApiToken}` with your access token.
</Warning>

<AccordionGroup>
  <Accordion title="Signup Prompt: Identifier + Password">
    To add language selection to the `signup` prompt, use the [Set partials for a prompt](https://auth0.com/docs/api/management/v2/prompts/put-partials) endpoint:

    <AuthCodeGroup>
      ```bash cURL theme={null}
      curl --request PUT \
        --url 'https://{yourDomain}/api/v2/prompts/signup/partials' \
        --header 'authorization: Bearer {mgmtApiToken}' \
        --header 'content-type: application/json' \
        --data '{
          "signup": {
              "form-content-start": "<div class="ulp-field"><label for="language">Preferred Language</label><select name="language"id="language"  onchange=updateSelectedLanguage()><option></option><option value="en" {% if locale == "en" %}selected{% endif %}>English</option><option value="fr" {% if locale == "fr" %}selected{% endif %}>French</option><option value="es" {% if locale == "es" %}selected{% endif %}>Spanish</option></select></div><input type="hidden" name="persist" value="session"/><input name="action" id="changeLanguage" type="submit" value="change-language" style="display:none" formnovalidate/>"
          }
      }'
      ```

      ```csharp C# theme={null}
      var client = new RestClient("https://{yourDomain}/api/v2/prompts/signup/partials");
      var request = new RestRequest(Method.PUT);
      request.AddHeader("content-type", "application/json");
      request.AddHeader("authorization", "Bearer {mgmtApiToken}");
      request.AddParameter("application/json", "{
          "signup": {
              "form-content-start": "<div class=\\"ulp-field\\"><label for=\\"language\\">Preferred Language</label><select name=\\"language\\"id=\\"language\\"  onchange=updateSelectedLanguage()><option></option><option value=\\"en\\" {% if locale == \\"en\\" %}selected{% endif %}>English</option><option value=\\"fr\\" {% if locale == \\"fr\\" %}selected{% endif %}>French</option><option value=\\"es\\" {% if locale == \\"es\\" %}selected{% endif %}>Spanish</option></select></div><input type=\\"hidden\\" name=\\"persist\\" value=\\"session\\"/><input name=\\"action\\" id=\\"changeLanguage\\" type=\\"submit\\" value=\\"change-language\\" style=\\"display:none\\" formnovalidate/>"
          }
      }", ParameterType.RequestBody);
      IRestResponse response = client.Execute(request);
      ```

      ```go Go theme={null}
      package main

      import (
      	"fmt"
      	"strings"
      	"net/http"
      	"io/ioutil"
      )

      func main() {

      	url := "https://{yourDomain}/api/v2/prompts/signup/partials"

      	payload := strings.NewReader("{
          "signup": {
              "form-content-start": "<div class=\\"ulp-field\\"><label for=\\"language\\">Preferred Language</label><select name=\\"language\\"id=\\"language\\"  onchange=updateSelectedLanguage()><option></option><option value=\\"en\\" {% if locale == \\"en\\" %}selected{% endif %}>English</option><option value=\\"fr\\" {% if locale == \\"fr\\" %}selected{% endif %}>French</option><option value=\\"es\\" {% if locale == \\"es\\" %}selected{% endif %}>Spanish</option></select></div><input type=\\"hidden\\" name=\\"persist\\" value=\\"session\\"/><input name=\\"action\\" id=\\"changeLanguage\\" type=\\"submit\\" value=\\"change-language\\" style=\\"display:none\\" formnovalidate/>"
          }
      }")

      	req, _ := http.NewRequest("PUT", url, payload)

      	req.Header.Add("content-type", "application/json")
      	req.Header.Add("authorization", "Bearer {mgmtApiToken}")

      	res, _ := http.DefaultClient.Do(req)

      	defer res.Body.Close()
      	body, _ := ioutil.ReadAll(res.Body)

      	fmt.Println(res)
      	fmt.Println(string(body))

      }
      ```

      ```java Java theme={null}
      HttpResponse<String> response = Unirest.put("https://{yourDomain}/api/v2/prompts/signup/partials")
        .header("content-type", "application/json")
        .header("authorization", "Bearer {mgmtApiToken}")
        .body("{
          "signup": {
              "form-content-start": "<div class=\\"ulp-field\\"><label for=\\"language\\">Preferred Language</label><select name=\\"language\\"id=\\"language\\"  onchange=updateSelectedLanguage()><option></option><option value=\\"en\\" {% if locale == \\"en\\" %}selected{% endif %}>English</option><option value=\\"fr\\" {% if locale == \\"fr\\" %}selected{% endif %}>French</option><option value=\\"es\\" {% if locale == \\"es\\" %}selected{% endif %}>Spanish</option></select></div><input type=\\"hidden\\" name=\\"persist\\" value=\\"session\\"/><input name=\\"action\\" id=\\"changeLanguage\\" type=\\"submit\\" value=\\"change-language\\" style=\\"display:none\\" formnovalidate/>"
          }
      }")
        .asString();
      ```

      ```javascript Node.JS theme={null}
      var axios = require("axios").default;

      var options = {
        method: 'PUT',
        url: 'https://{yourDomain}/api/v2/prompts/signup/partials',
        headers: {'content-type': 'application/json', authorization: 'Bearer {mgmtApiToken}'},
        data: {
          signup: {
            'form-content-start': '<div class="ulp-field"><label for="language">Preferred Language</label><select name="language"id="language"  onchange=updateSelectedLanguage()><option></option><option value="en" {% if locale == "en" %}selected{% endif %}>English</option><option value="fr" {% if locale == "fr" %}selected{% endif %}>French</option><option value="es" {% if locale == "es" %}selected{% endif %}>Spanish</option></select></div><input type="hidden" name="persist" value="session"/><input name="action" id="changeLanguage" type="submit" value="change-language" style="display:none" formnovalidate/>'
          }
        }
      };

      axios.request(options).then(function (response) {
        console.log(response.data);
      }).catch(function (error) {
        console.error(error);
      });
      ```

      ```objc Obj-C theme={null}
      #import <Foundation/Foundation.h>

      NSDictionary *headers = @{ @"content-type": @"application/json",
                                 @"authorization": @"Bearer {mgmtApiToken}" };
      NSDictionary *parameters = @{ @"signup": @{ @"form-content-start": @"<div class="ulp-field"><label for="language">Preferred Language</label><select name="language"id="language"  onchange=updateSelectedLanguage()><option></option><option value="en" {% if locale == "en" %}selected{% endif %}>English</option><option value="fr" {% if locale == "fr" %}selected{% endif %}>French</option><option value="es" {% if locale == "es" %}selected{% endif %}>Spanish</option></select></div><input type="hidden" name="persist" value="session"/><input name="action" id="changeLanguage" type="submit" value="change-language" style="display:none" formnovalidate/>" } };

      NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

      NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/prompts/signup/partials"]
                                                             cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                         timeoutInterval:10.0];
      [request setHTTPMethod:@"PUT"];
      [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];
      ```

      ```php PHP theme={null}
      $curl = curl_init();

      curl_setopt_array($curl, [
        CURLOPT_URL => "https://{yourDomain}/api/v2/prompts/signup/partials",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => "",
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => "PUT",
        CURLOPT_POSTFIELDS => "{
          "signup": {
              "form-content-start": "<div class=\\"ulp-field\\"><label for=\\"language\\">Preferred Language</label><select name=\\"language\\"id=\\"language\\"  onchange=updateSelectedLanguage()><option></option><option value=\\"en\\" {% if locale == \\"en\\" %}selected{% endif %}>English</option><option value=\\"fr\\" {% if locale == \\"fr\\" %}selected{% endif %}>French</option><option value=\\"es\\" {% if locale == \\"es\\" %}selected{% endif %}>Spanish</option></select></div><input type=\\"hidden\\" name=\\"persist\\" value=\\"session\\"/><input name=\\"action\\" id=\\"changeLanguage\\" type=\\"submit\\" value=\\"change-language\\" style=\\"display:none\\" formnovalidate/>"
          }
      }",
        CURLOPT_HTTPHEADER => [
          "authorization: Bearer {mgmtApiToken}",
          "content-type: application/json"
        ],
      ]);

      $response = curl_exec($curl);
      $err = curl_error($curl);

      curl_close($curl);

      if ($err) {
        echo "cURL Error #:" . $err;
      } else {
        echo $response;
      }
      ```

      ```python Python theme={null}
      import http.client

      conn = http.client.HTTPSConnection("")

      payload = "{
          "signup": {
              "form-content-start": "<div class=\\"ulp-field\\"><label for=\\"language\\">Preferred Language</label><select name=\\"language\\"id=\\"language\\"  onchange=updateSelectedLanguage()><option></option><option value=\\"en\\" {% if locale == \\"en\\" %}selected{% endif %}>English</option><option value=\\"fr\\" {% if locale == \\"fr\\" %}selected{% endif %}>French</option><option value=\\"es\\" {% if locale == \\"es\\" %}selected{% endif %}>Spanish</option></select></div><input type=\\"hidden\\" name=\\"persist\\" value=\\"session\\"/><input name=\\"action\\" id=\\"changeLanguage\\" type=\\"submit\\" value=\\"change-language\\" style=\\"display:none\\" formnovalidate/>"
          }
      }"

      headers = {
          'content-type': "application/json",
          'authorization': "Bearer {mgmtApiToken}"
          }

      conn.request("PUT", "/{yourDomain}/api/v2/prompts/signup/partials", payload, headers)

      res = conn.getresponse()
      data = res.read()

      print(data.decode("utf-8"))
      ```

      ```ruby Ruby theme={null}
      require 'uri'
      require 'net/http'
      require 'openssl'

      url = URI("https://{yourDomain}/api/v2/prompts/signup/partials")

      http = Net::HTTP.new(url.host, url.port)
      http.use_ssl = true
      http.verify_mode = OpenSSL::SSL::VERIFY_NONE

      request = Net::HTTP::Put.new(url)
      request["content-type"] = 'application/json'
      request["authorization"] = 'Bearer {mgmtApiToken}'
      request.body = "{
          "signup": {
              "form-content-start": "<div class=\\"ulp-field\\"><label for=\\"language\\">Preferred Language</label><select name=\\"language\\"id=\\"language\\"  onchange=updateSelectedLanguage()><option></option><option value=\\"en\\" {% if locale == \\"en\\" %}selected{% endif %}>English</option><option value=\\"fr\\" {% if locale == \\"fr\\" %}selected{% endif %}>French</option><option value=\\"es\\" {% if locale == \\"es\\" %}selected{% endif %}>Spanish</option></select></div><input type=\\"hidden\\" name=\\"persist\\" value=\\"session\\"/><input name=\\"action\\" id=\\"changeLanguage\\" type=\\"submit\\" value=\\"change-language\\" style=\\"display:none\\" formnovalidate/>"
          }
      }"

      response = http.request(request)
      puts response.read_body
      ```

      ```swift Swift theme={null}
      import Foundation

      let headers = [
        "content-type": "application/json",
        "authorization": "Bearer {mgmtApiToken}"
      ]
      let parameters = ["signup": ["form-content-start": "<div class="ulp-field"><label for="language">Preferred Language</label><select name="language"id="language"  onchange=updateSelectedLanguage()><option></option><option value="en" {% if locale == "en" %}selected{% endif %}>English</option><option value="fr" {% if locale == "fr" %}selected{% endif %}>French</option><option value="es" {% if locale == "es" %}selected{% endif %}>Spanish</option></select></div><input type="hidden" name="persist" value="session"/><input name="action" id="changeLanguage" type="submit" value="change-language" style="display:none" formnovalidate/>"]] as [String : Any]

      let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

      let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/prompts/signup/partials")! as URL,
                                              cachePolicy: .useProtocolCachePolicy,
                                          timeoutInterval: 10.0)
      request.httpMethod = "PUT"
      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()
      ```
    </AuthCodeGroup>
  </Accordion>

  <Accordion title="Login Prompt: Identifier First">
    To add language selection to the `login-id` prompt, use the [Set partials for a prompt](https://auth0.com/docs/api/management/v2/prompts/put-partials) endpoint:

    <AuthCodeGroup>
      ```bash cURL theme={null}
      curl --request PUT \
        --url 'https://{yourDomain}/api/v2/prompts/login-id/partials' \
        --header 'authorization: Bearer {mgmtApiToken}' \
        --header 'content-type: application/json' \
        --data '{
          "login-id": {
              "form-content-start": "<div class="ulp-field"><label for="language">Preferred Language</label><select name="language"id="language"  onchange=updateSelectedLanguage()><option></option><option value="en" {% if locale == "en" %}selected{% endif %}>English</option><option value="fr" {% if locale == "fr" %}selected{% endif %}>French</option><option value="es" {% if locale == "es" %}selected{% endif %}>Spanish</option></select></div><input type="hidden" name="persist" value="session"/><input name="action" id="changeLanguage" type="submit" value="change-language" style="display:none" formnovalidate/>"
          }
      }'
      ```

      ```csharp C# theme={null}
      var client = new RestClient("https://{yourDomain}/api/v2/prompts/login-id/partials");
      var request = new RestRequest(Method.PUT);
      request.AddHeader("content-type", "application/json");
      request.AddHeader("authorization", "Bearer {mgmtApiToken}");
      request.AddParameter("application/json", "{
          "login-id": {
              "form-content-start": "<div class=\\"ulp-field\\"><label for=\\"language\\">Preferred Language</label><select name=\\"language\\"id=\\"language\\"  onchange=updateSelectedLanguage()><option></option><option value=\\"en\\" {% if locale == \\"en\\" %}selected{% endif %}>English</option><option value=\\"fr\\" {% if locale == \\"fr\\" %}selected{% endif %}>French</option><option value=\\"es\\" {% if locale == \\"es\\" %}selected{% endif %}>Spanish</option></select></div><input type=\\"hidden\\" name=\\"persist\\" value=\\"session\\"/><input name=\\"action\\" id=\\"changeLanguage\\" type=\\"submit\\" value=\\"change-language\\" style=\\"display:none\\" formnovalidate/>"
          }
      }", ParameterType.RequestBody);
      IRestResponse response = client.Execute(request);
      ```

      ```go Go theme={null}
      package main

      import (
      	"fmt"
      	"strings"
      	"net/http"
      	"io/ioutil"
      )

      func main() {

      	url := "https://{yourDomain}/api/v2/prompts/login-id/partials"

      	payload := strings.NewReader("{
          "login-id": {
              "form-content-start": "<div class=\\"ulp-field\\"><label for=\\"language\\">Preferred Language</label><select name=\\"language\\"id=\\"language\\"  onchange=updateSelectedLanguage()><option></option><option value=\\"en\\" {% if locale == \\"en\\" %}selected{% endif %}>English</option><option value=\\"fr\\" {% if locale == \\"fr\\" %}selected{% endif %}>French</option><option value=\\"es\\" {% if locale == \\"es\\" %}selected{% endif %}>Spanish</option></select></div><input type=\\"hidden\\" name=\\"persist\\" value=\\"session\\"/><input name=\\"action\\" id=\\"changeLanguage\\" type=\\"submit\\" value=\\"change-language\\" style=\\"display:none\\" formnovalidate/>"
          }
      }")

      	req, _ := http.NewRequest("PUT", url, payload)

      	req.Header.Add("content-type", "application/json")
      	req.Header.Add("authorization", "Bearer {mgmtApiToken}")

      	res, _ := http.DefaultClient.Do(req)

      	defer res.Body.Close()
      	body, _ := ioutil.ReadAll(res.Body)

      	fmt.Println(res)
      	fmt.Println(string(body))

      }
      ```

      ```java Java theme={null}
      HttpResponse<String> response = Unirest.put("https://{yourDomain}/api/v2/prompts/login-id/partials")
        .header("content-type", "application/json")
        .header("authorization", "Bearer {mgmtApiToken}")
        .body("{
          "login-id": {
              "form-content-start": "<div class=\\"ulp-field\\"><label for=\\"language\\">Preferred Language</label><select name=\\"language\\"id=\\"language\\"  onchange=updateSelectedLanguage()><option></option><option value=\\"en\\" {% if locale == \\"en\\" %}selected{% endif %}>English</option><option value=\\"fr\\" {% if locale == \\"fr\\" %}selected{% endif %}>French</option><option value=\\"es\\" {% if locale == \\"es\\" %}selected{% endif %}>Spanish</option></select></div><input type=\\"hidden\\" name=\\"persist\\" value=\\"session\\"/><input name=\\"action\\" id=\\"changeLanguage\\" type=\\"submit\\" value=\\"change-language\\" style=\\"display:none\\" formnovalidate/>"
          }
      }")
        .asString();
      ```

      ```javascript Node.JS theme={null}
      var axios = require("axios").default;

      var options = {
        method: 'PUT',
        url: 'https://{yourDomain}/api/v2/prompts/login-id/partials',
        headers: {'content-type': 'application/json', authorization: 'Bearer {mgmtApiToken}'},
        data: {
          'login-id': {
            'form-content-start': '<div class="ulp-field"><label for="language">Preferred Language</label><select name="language"id="language"  onchange=updateSelectedLanguage()><option></option><option value="en" {% if locale == "en" %}selected{% endif %}>English</option><option value="fr" {% if locale == "fr" %}selected{% endif %}>French</option><option value="es" {% if locale == "es" %}selected{% endif %}>Spanish</option></select></div><input type="hidden" name="persist" value="session"/><input name="action" id="changeLanguage" type="submit" value="change-language" style="display:none" formnovalidate/>'
          }
        }
      };

      axios.request(options).then(function (response) {
        console.log(response.data);
      }).catch(function (error) {
        console.error(error);
      });
      ```

      ```objc Obj-C theme={null}
      #import <Foundation/Foundation.h>

      NSDictionary *headers = @{ @"content-type": @"application/json",
                                 @"authorization": @"Bearer {mgmtApiToken}" };
      NSDictionary *parameters = @{ @"login-id": @{ @"form-content-start": @"<div class="ulp-field"><label for="language">Preferred Language</label><select name="language"id="language"  onchange=updateSelectedLanguage()><option></option><option value="en" {% if locale == "en" %}selected{% endif %}>English</option><option value="fr" {% if locale == "fr" %}selected{% endif %}>French</option><option value="es" {% if locale == "es" %}selected{% endif %}>Spanish</option></select></div><input type="hidden" name="persist" value="session"/><input name="action" id="changeLanguage" type="submit" value="change-language" style="display:none" formnovalidate/>" } };

      NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

      NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/prompts/login-id/partials"]
                                                             cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                         timeoutInterval:10.0];
      [request setHTTPMethod:@"PUT"];
      [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];
      ```

      ```php PHP theme={null}
      $curl = curl_init();

      curl_setopt_array($curl, [
        CURLOPT_URL => "https://{yourDomain}/api/v2/prompts/login-id/partials",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => "",
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => "PUT",
        CURLOPT_POSTFIELDS => "{
          "login-id": {
              "form-content-start": "<div class=\\"ulp-field\\"><label for=\\"language\\">Preferred Language</label><select name=\\"language\\"id=\\"language\\"  onchange=updateSelectedLanguage()><option></option><option value=\\"en\\" {% if locale == \\"en\\" %}selected{% endif %}>English</option><option value=\\"fr\\" {% if locale == \\"fr\\" %}selected{% endif %}>French</option><option value=\\"es\\" {% if locale == \\"es\\" %}selected{% endif %}>Spanish</option></select></div><input type=\\"hidden\\" name=\\"persist\\" value=\\"session\\"/><input name=\\"action\\" id=\\"changeLanguage\\" type=\\"submit\\" value=\\"change-language\\" style=\\"display:none\\" formnovalidate/>"
          }
      }",
        CURLOPT_HTTPHEADER => [
          "authorization: Bearer {mgmtApiToken}",
          "content-type: application/json"
        ],
      ]);

      $response = curl_exec($curl);
      $err = curl_error($curl);

      curl_close($curl);

      if ($err) {
        echo "cURL Error #:" . $err;
      } else {
        echo $response;
      }
      ```

      ```python Python theme={null}
      import http.client

      conn = http.client.HTTPSConnection("")

      payload = "{
          "login-id": {
              "form-content-start": "<div class=\\"ulp-field\\"><label for=\\"language\\">Preferred Language</label><select name=\\"language\\"id=\\"language\\"  onchange=updateSelectedLanguage()><option></option><option value=\\"en\\" {% if locale == \\"en\\" %}selected{% endif %}>English</option><option value=\\"fr\\" {% if locale == \\"fr\\" %}selected{% endif %}>French</option><option value=\\"es\\" {% if locale == \\"es\\" %}selected{% endif %}>Spanish</option></select></div><input type=\\"hidden\\" name=\\"persist\\" value=\\"session\\"/><input name=\\"action\\" id=\\"changeLanguage\\" type=\\"submit\\" value=\\"change-language\\" style=\\"display:none\\" formnovalidate/>"
          }
      }"

      headers = {
          'content-type': "application/json",
          'authorization': "Bearer {mgmtApiToken}"
          }

      conn.request("PUT", "/{yourDomain}/api/v2/prompts/login-id/partials", payload, headers)

      res = conn.getresponse()
      data = res.read()

      print(data.decode("utf-8"))
      ```

      ```ruby Ruby theme={null}
      require 'uri'
      require 'net/http'
      require 'openssl'

      url = URI("https://{yourDomain}/api/v2/prompts/login-id/partials")

      http = Net::HTTP.new(url.host, url.port)
      http.use_ssl = true
      http.verify_mode = OpenSSL::SSL::VERIFY_NONE

      request = Net::HTTP::Put.new(url)
      request["content-type"] = 'application/json'
      request["authorization"] = 'Bearer {mgmtApiToken}'
      request.body = "{
          "login-id": {
              "form-content-start": "<div class=\\"ulp-field\\"><label for=\\"language\\">Preferred Language</label><select name=\\"language\\"id=\\"language\\"  onchange=updateSelectedLanguage()><option></option><option value=\\"en\\" {% if locale == \\"en\\" %}selected{% endif %}>English</option><option value=\\"fr\\" {% if locale == \\"fr\\" %}selected{% endif %}>French</option><option value=\\"es\\" {% if locale == \\"es\\" %}selected{% endif %}>Spanish</option></select></div><input type=\\"hidden\\" name=\\"persist\\" value=\\"session\\"/><input name=\\"action\\" id=\\"changeLanguage\\" type=\\"submit\\" value=\\"change-language\\" style=\\"display:none\\" formnovalidate/>"
          }
      }"

      response = http.request(request)
      puts response.read_body
      ```

      ```swift Swift theme={null}
      import Foundation

      let headers = [
        "content-type": "application/json",
        "authorization": "Bearer {mgmtApiToken}"
      ]
      let parameters = ["login-id": ["form-content-start": "<div class="ulp-field"><label for="language">Preferred Language</label><select name="language"id="language"  onchange=updateSelectedLanguage()><option></option><option value="en" {% if locale == "en" %}selected{% endif %}>English</option><option value="fr" {% if locale == "fr" %}selected{% endif %}>French</option><option value="es" {% if locale == "es" %}selected{% endif %}>Spanish</option></select></div><input type="hidden" name="persist" value="session"/><input name="action" id="changeLanguage" type="submit" value="change-language" style="display:none" formnovalidate/>"]] as [String : Any]

      let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

      let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/prompts/login-id/partials")! as URL,
                                              cachePolicy: .useProtocolCachePolicy,
                                          timeoutInterval: 10.0)
      request.httpMethod = "PUT"
      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()
      ```
    </AuthCodeGroup>
  </Accordion>

  <Accordion title="Login Prompt: Passwordless (Email)">
    To add language selection to the `login-passwordless-email-code` prompt, use the [Set partials for a prompt](https://auth0.com/docs/api/management/v2/prompts/put-partials) endpoint:

    <AuthCodeGroup>
      ```bash cURL theme={null}
      curl --request PUT \
        --url 'https://{yourDomain}/api/v2/prompts/login-passwordless/partials' \
        --header 'authorization: Bearer {mgmtApiToken}' \
        --header 'content-type: application/json' \
        --data '{
          "login-passwordless-email-code": {
            "form-content-start": "<div class="ulp-field"><label for="language">Preferred Language</label><select name="language"id="language"  onchange=updateSelectedLanguage()><option></option><option value="en" {% if locale == "en" %}selected{% endif %}>English</option><option value="fr" {% if locale == "fr" %}selected{% endif %}>French</option><option value="es" {% if locale == "es" %}selected{% endif %}>Spanish</option></select></div><input type="hidden" name="persist" value="session"/><input name="action" id="changeLanguage" type="submit" value="change-language" style="display:none" formnovalidate/>"
        }
      }'
      ```

      ```csharp C# theme={null}
      var client = new RestClient("https://{yourDomain}/api/v2/prompts/login-passwordless/partials");
      var request = new RestRequest(Method.PUT);
      request.AddHeader("content-type", "application/json");
      request.AddHeader("authorization", "Bearer {mgmtApiToken}");
      request.AddParameter("application/json", "{
          "login-passwordless-email-code": {
            "form-content-start": "<div class=\\"ulp-field\\"><label for=\\"language\\">Preferred Language</label><select name=\\"language\\"id=\\"language\\"  onchange=updateSelectedLanguage()><option></option><option value=\\"en\\" {% if locale == \\"en\\" %}selected{% endif %}>English</option><option value=\\"fr\\" {% if locale == \\"fr\\" %}selected{% endif %}>French</option><option value=\\"es\\" {% if locale == \\"es\\" %}selected{% endif %}>Spanish</option></select></div><input type=\\"hidden\\" name=\\"persist\\" value=\\"session\\"/><input name=\\"action\\" id=\\"changeLanguage\\" type=\\"submit\\" value=\\"change-language\\" style=\\"display:none\\" formnovalidate/>"
        }
      }", ParameterType.RequestBody);
      IRestResponse response = client.Execute(request);
      ```

      ```go Go theme={null}
      package main

      import (
      	"fmt"
      	"strings"
      	"net/http"
      	"io/ioutil"
      )

      func main() {

      	url := "https://{yourDomain}/api/v2/prompts/login-passwordless/partials"

      	payload := strings.NewReader("{
          "login-passwordless-email-code": {
            "form-content-start": "<div class=\\"ulp-field\\"><label for=\\"language\\">Preferred Language</label><select name=\\"language\\"id=\\"language\\"  onchange=updateSelectedLanguage()><option></option><option value=\\"en\\" {% if locale == \\"en\\" %}selected{% endif %}>English</option><option value=\\"fr\\" {% if locale == \\"fr\\" %}selected{% endif %}>French</option><option value=\\"es\\" {% if locale == \\"es\\" %}selected{% endif %}>Spanish</option></select></div><input type=\\"hidden\\" name=\\"persist\\" value=\\"session\\"/><input name=\\"action\\" id=\\"changeLanguage\\" type=\\"submit\\" value=\\"change-language\\" style=\\"display:none\\" formnovalidate/>"
        }
      }")

      	req, _ := http.NewRequest("PUT", url, payload)

      	req.Header.Add("content-type", "application/json")
      	req.Header.Add("authorization", "Bearer {mgmtApiToken}")

      	res, _ := http.DefaultClient.Do(req)

      	defer res.Body.Close()
      	body, _ := ioutil.ReadAll(res.Body)

      	fmt.Println(res)
      	fmt.Println(string(body))

      }
      ```

      ```java Java theme={null}
      HttpResponse<String> response = Unirest.put("https://{yourDomain}/api/v2/prompts/login-passwordless/partials")
        .header("content-type", "application/json")
        .header("authorization", "Bearer {mgmtApiToken}")
        .body("{
          "login-passwordless-email-code": {
            "form-content-start": "<div class=\\"ulp-field\\"><label for=\\"language\\">Preferred Language</label><select name=\\"language\\"id=\\"language\\"  onchange=updateSelectedLanguage()><option></option><option value=\\"en\\" {% if locale == \\"en\\" %}selected{% endif %}>English</option><option value=\\"fr\\" {% if locale == \\"fr\\" %}selected{% endif %}>French</option><option value=\\"es\\" {% if locale == \\"es\\" %}selected{% endif %}>Spanish</option></select></div><input type=\\"hidden\\" name=\\"persist\\" value=\\"session\\"/><input name=\\"action\\" id=\\"changeLanguage\\" type=\\"submit\\" value=\\"change-language\\" style=\\"display:none\\" formnovalidate/>"
        }
      }")
        .asString();
      ```

      ```javascript Node.JS theme={null}
      var axios = require("axios").default;

      var options = {
        method: 'PUT',
        url: 'https://{yourDomain}/api/v2/prompts/login-passwordless/partials',
        headers: {'content-type': 'application/json', authorization: 'Bearer {mgmtApiToken}'},
        data: {
          'login-passwordless-email-code': {
            'form-content-start': '<div class="ulp-field"><label for="language">Preferred Language</label><select name="language"id="language"  onchange=updateSelectedLanguage()><option></option><option value="en" {% if locale == "en" %}selected{% endif %}>English</option><option value="fr" {% if locale == "fr" %}selected{% endif %}>French</option><option value="es" {% if locale == "es" %}selected{% endif %}>Spanish</option></select></div><input type="hidden" name="persist" value="session"/><input name="action" id="changeLanguage" type="submit" value="change-language" style="display:none" formnovalidate/>'
          }
        }
      };

      axios.request(options).then(function (response) {
        console.log(response.data);
      }).catch(function (error) {
        console.error(error);
      });
      ```

      ```objc Obj-C theme={null}
      #import <Foundation/Foundation.h>

      NSDictionary *headers = @{ @"content-type": @"application/json",
                                 @"authorization": @"Bearer {mgmtApiToken}" };
      NSDictionary *parameters = @{ @"login-passwordless-email-code": @{ @"form-content-start": @"<div class="ulp-field"><label for="language">Preferred Language</label><select name="language"id="language"  onchange=updateSelectedLanguage()><option></option><option value="en" {% if locale == "en" %}selected{% endif %}>English</option><option value="fr" {% if locale == "fr" %}selected{% endif %}>French</option><option value="es" {% if locale == "es" %}selected{% endif %}>Spanish</option></select></div><input type="hidden" name="persist" value="session"/><input name="action" id="changeLanguage" type="submit" value="change-language" style="display:none" formnovalidate/>" } };

      NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

      NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/prompts/login-passwordless/partials"]
                                                             cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                         timeoutInterval:10.0];
      [request setHTTPMethod:@"PUT"];
      [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];
      ```

      ```php PHP theme={null}
      $curl = curl_init();

      curl_setopt_array($curl, [
        CURLOPT_URL => "https://{yourDomain}/api/v2/prompts/login-passwordless/partials",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => "",
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => "PUT",
        CURLOPT_POSTFIELDS => "{
          "login-passwordless-email-code": {
            "form-content-start": "<div class=\\"ulp-field\\"><label for=\\"language\\">Preferred Language</label><select name=\\"language\\"id=\\"language\\"  onchange=updateSelectedLanguage()><option></option><option value=\\"en\\" {% if locale == \\"en\\" %}selected{% endif %}>English</option><option value=\\"fr\\" {% if locale == \\"fr\\" %}selected{% endif %}>French</option><option value=\\"es\\" {% if locale == \\"es\\" %}selected{% endif %}>Spanish</option></select></div><input type=\\"hidden\\" name=\\"persist\\" value=\\"session\\"/><input name=\\"action\\" id=\\"changeLanguage\\" type=\\"submit\\" value=\\"change-language\\" style=\\"display:none\\" formnovalidate/>"
        }
      }",
        CURLOPT_HTTPHEADER => [
          "authorization: Bearer {mgmtApiToken}",
          "content-type: application/json"
        ],
      ]);

      $response = curl_exec($curl);
      $err = curl_error($curl);

      curl_close($curl);

      if ($err) {
        echo "cURL Error #:" . $err;
      } else {
        echo $response;
      }
      ```

      ```python Python theme={null}
      import http.client

      conn = http.client.HTTPSConnection("")

      payload = "{
          "login-passwordless-email-code": {
            "form-content-start": "<div class=\\"ulp-field\\"><label for=\\"language\\">Preferred Language</label><select name=\\"language\\"id=\\"language\\"  onchange=updateSelectedLanguage()><option></option><option value=\\"en\\" {% if locale == \\"en\\" %}selected{% endif %}>English</option><option value=\\"fr\\" {% if locale == \\"fr\\" %}selected{% endif %}>French</option><option value=\\"es\\" {% if locale == \\"es\\" %}selected{% endif %}>Spanish</option></select></div><input type=\\"hidden\\" name=\\"persist\\" value=\\"session\\"/><input name=\\"action\\" id=\\"changeLanguage\\" type=\\"submit\\" value=\\"change-language\\" style=\\"display:none\\" formnovalidate/>"
        }
      }"

      headers = {
          'content-type': "application/json",
          'authorization': "Bearer {mgmtApiToken}"
          }

      conn.request("PUT", "/{yourDomain}/api/v2/prompts/login-passwordless/partials", payload, headers)

      res = conn.getresponse()
      data = res.read()

      print(data.decode("utf-8"))
      ```

      ```ruby Ruby theme={null}
      require 'uri'
      require 'net/http'
      require 'openssl'

      url = URI("https://{yourDomain}/api/v2/prompts/login-passwordless/partials")

      http = Net::HTTP.new(url.host, url.port)
      http.use_ssl = true
      http.verify_mode = OpenSSL::SSL::VERIFY_NONE

      request = Net::HTTP::Put.new(url)
      request["content-type"] = 'application/json'
      request["authorization"] = 'Bearer {mgmtApiToken}'
      request.body = "{
          "login-passwordless-email-code": {
            "form-content-start": "<div class=\\"ulp-field\\"><label for=\\"language\\">Preferred Language</label><select name=\\"language\\"id=\\"language\\"  onchange=updateSelectedLanguage()><option></option><option value=\\"en\\" {% if locale == \\"en\\" %}selected{% endif %}>English</option><option value=\\"fr\\" {% if locale == \\"fr\\" %}selected{% endif %}>French</option><option value=\\"es\\" {% if locale == \\"es\\" %}selected{% endif %}>Spanish</option></select></div><input type=\\"hidden\\" name=\\"persist\\" value=\\"session\\"/><input name=\\"action\\" id=\\"changeLanguage\\" type=\\"submit\\" value=\\"change-language\\" style=\\"display:none\\" formnovalidate/>"
        }
      }"

      response = http.request(request)
      puts response.read_body
      ```

      ```swift Swift theme={null}
      import Foundation

      let headers = [
        "content-type": "application/json",
        "authorization": "Bearer {mgmtApiToken}"
      ]
      let parameters = ["login-passwordless-email-code": ["form-content-start": "<div class="ulp-field"><label for="language">Preferred Language</label><select name="language"id="language"  onchange=updateSelectedLanguage()><option></option><option value="en" {% if locale == "en" %}selected{% endif %}>English</option><option value="fr" {% if locale == "fr" %}selected{% endif %}>French</option><option value="es" {% if locale == "es" %}selected{% endif %}>Spanish</option></select></div><input type="hidden" name="persist" value="session"/><input name="action" id="changeLanguage" type="submit" value="change-language" style="display:none" formnovalidate/>"]] as [String : Any]

      let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

      let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/prompts/login-passwordless/partials")! as URL,
                                              cachePolicy: .useProtocolCachePolicy,
                                          timeoutInterval: 10.0)
      request.httpMethod = "PUT"
      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()
      ```
    </AuthCodeGroup>
  </Accordion>
</AccordionGroup>


# Use Actions to Validate and Store End-user Data Gathered By Signup Prompt Customizations
Source: https://auth0.com/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts/use-actions-to-validate-and-store-end-user-data-gathered-by-signup-prompt

Learn how to use Auth0 Actions to validate and store end-user data.

You can use [Signup Prompt Customization](/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts) along with the `pre-user-registration` trigger to add end-user supplied data (like a user's phone number or location) from the signup prompt to `user_metadata`. Optionally, you can validate this data and show a validation error in the prompt.

### Prerequisites

* Tenant has a [Custom Domain](/docs/customize/custom-domains) verified
* Tenant has a [Page Template](/docs/customize/login-pages/universal-login/customize-templates) set

### Add A Field To The Signup Prompt

Use the [Management API](https://auth0.com/docs/api/management/v2/prompts/put-custom-text-by-language) to insert a custom field into a prompt using one of the [Entry Points](/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts#-signup-prompt-entry-points). This example adds the following content to the `ulp-container-form-content-start` insertion point:

```html lines theme={null}
<div class="ulp-field">
  <label for="first-name">First Name</label>
  <input type="text" name="ulp-first-name" id="first-name">
</div>
```

The result is a First Name section in the signup prompt:

<Frame>
  <img alt="" />
</Frame>

### Create An Action In The Pre-User Registration Trigger

You can build a custom pre-user registration action by going to [**Actions > Library > Build Custom**](https://manage.auth0.com/dashboard/us/dev-6endizjt/actions/library)**.**

<Frame>
  <img alt="" />
</Frame>

Inside the code editor, update the `onExecutePreUserRegistration` handler:

```js lines theme={null}
exports.onExecutePreUserRegistration = async (event, api) => {
  const firstName = event.request.body['ulp-first-name'];
  api.user.setUserMetadata("firstName", firstName);
};
```

Optionally, you can validate the user input and send a validation error by calling the `api.validation.error` method, then deploy the action:

```js lines theme={null}
exports.onExecutePreUserRegistration = async (event, api) => {
  const firstName = event.request.body['ulp-first-name'];
  if(!firstName) {
    api.validation.error("invalid_payload", "Missing first name");
    return;
  }

  api.user.setUserMetadata("firstName", firstName);
};
```

### Add The Action To The Flow

Navigate to [**Actions > Flows > Pre User Registration > Add Action > Custom**](https://manage.auth0.com/dashboard/us/dev-6endizjt/actions/flows/pre-user-signup/), then drag and drop your new action into the registration flow and select **Apply**.

<Frame>
  <img alt="" />
</Frame>

### Test The Action

Sign up for an account in your test flow and leave the **First Name** field blank. You will see an error on submit:

<Frame>
  <img alt="" />
</Frame>

After you enter a name in the **First Name** field, you are able to submit successfully:

<Frame>
  <img alt="" />
</Frame>

### Verify That The Data Was Saved On user\_metadata

Navigate to [**User Management > Users**](https://manage.auth0.com/dashboard/us/dev-6endizjt/users), then confirm the data has been saved by viewing the Details tab:

<Frame>
  <img alt="" />
</Frame>


# Use Dynamic Variables to Internationalize Custom Form Elements
Source: https://auth0.com/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts/use-dynamic-variables-to-internationalize-custom-form-elements

Learn how dynamic variables can create multi-language login prompts.

You can render [Sign-Up Prompt Customizations](/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts) differently depending on contextual data. It uses the `locale` variable to conditionally render form inputs and define validation behavior.

The following use case works with the `locale` variable to render a Terms of Service message and checkbox. Any variable exposed to [Page Templates](/docs/customize/login-pages/universal-login/customize-templates#available-variables) can be substituted.

### Prerequisites

* Tenant has a verified [Custom Domain](/docs/customize/custom-domains)
* Tenant has a Page Template set

### Enable fr and es locales

Go to your <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, then navigate to Settings > General and enable the locales:

<Frame>
  <img alt="" />
</Frame>

### Conditionally render Custom Fields

Use <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to add a template partial to the `form-content-end` signup prompt <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> Prompt container. In the case where the locale is `es` or `fr`, you may want to render a Terms of Service message and a checkbox.

```liquid lines theme={null}
{% if locale == 'fr' %}
  <div class="ulp-field">
    <input
      type="checkbox"
      name="ulp-terms-of-service"
      id="terms-of-service">
    <label for="terms-of-service">
      J'accepte les
      <a href="https://fr.example.com/tos">termes et conditions</a>
    </label>
  </div>
{% endif %}
{% if locale == 'es' %}
  <div class="ulp-field">
    <input
      type="checkbox"
      name="ulp-terms-of-service"
      id="terms-of-service">
    <label for="terms-of-service">
      Estoy de acuerdo con los
      <a href="https://es.example.com/tos">términos y condiciones</a>
    </label>
  </div>
{% endif %}
```

The following request is sent to the **Set custom text for a specific prompt** endpoint in the [Management API](https://auth0.com/docs/api/management/v2/prompts/put-custom-text-by-language):

```javascript lines theme={null}
// PUT prompts/signup/partials

{
  "signup": {
    "form-content-end": "{% if locale..."
  }
}
```

Your signup prompt now displays a ToS message and checkbox only when the locale is set to `fr` or `es`:

<Frame>
  <img alt="" />
</Frame>

<Frame>
  <img alt="" />
</Frame>

<Frame>
  <img alt="" />
</Frame>

To test your output, go to **Manage Dashboard** and navigate to [Branding > Universal Login > Customization Options](https://manage.auth0.com/dashboard/us/dev-6endizjt/universal-login/customizations/colors), then right-click the **Try button** and copy the link address. Append the following query parameters to the copied url and navigate to the new url: `&screen_hint=signup&ui_locales=fr` (or `es`).

### Add validation

When the locale is `fr,` you can validate that the checkbox is checked before continuing. Update the template partial using the following validation code:

```liquid lines expandable theme={null}
{% if locale == 'fr' %}
  <div class="ulp-field">
    <input
      type="checkbox"
      name="ulp-terms-of-service"
      id="terms-of-service">
    <label for="terms-of-service">
      J'accepte les
      <a href="https://fr.example.com/tos">termes et conditions</a>
    </label>

    <!-- NEW -->
    <div
      class="ulp-error-info"
      data-ulp-validation-function="requiredFunction"
      data-ulp-validation-event-listeners="change">
      Vous devez accepter les termes et conditions pour continuer
    </div>
    <!-- END NEW -->
  </div>
{% endif %}
{% if locale == 'es' %}
  <div class="ulp-field">
    <input
      type="checkbox"
      name="ulp-terms-of-service"
      id="terms-of-service">
    <label for="terms-of-service">
      Estoy de acuerdo con los
      <a href="https://es.example.com/tos">términos y condiciones</a>
    </label>
  </div>
{% endif %}

<!-- NEW -->
<script>
  function requiredFunction(element, formSubmitted) {
    if (! formSubmitted) {
      return true;
    }
    return element.checked;
  }
</script>
<!-- END NEW -->
```

With this validation in place, only users with the `fr` locale are required to consent to the ToS.

<Frame>
  <img alt="" />
</Frame>

<Callout icon="file-lines">
  The validations in this use case happen client-side and are intended to be a user convenience. They are not guaranteed to run; for example, the user’s browser may have Javascript turned off. In addition, validations can be modified by curious or malicious actors. To ensure the integrity of validation logic, client-side validations should be paired with server-side validations.
</Callout>


# Customize Universal Login Page Templates
Source: https://auth0.com/docs/customize/login-pages/universal-login/customize-templates

Learn how to create login page templates for the Universal Login experience.

You can customize <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> pages by providing a page template created with the [Liquid template language](https://shopify.github.io/liquid/basics/introduction/). With page templates, you can define the content displayed around Universal Login prompts, such as the login box or an <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> challenge. As the same page template is used for all login flow pages, this method of customization allows you to easily implement a consistent, branded experience for users.

To use customized page templates, you must configure a [Custom Domain](/docs/customize/custom-domains) for your tenant. Further, you can only update Universal Login page templates with the [Management API](https://auth0.com/docs/api/management/v2).

<Callout icon="file-lines">
  The term `prompt` refers to a specific step of the login flow, such as the sign-up page or an MFA challenge. The variables and code samples on this page may use the term `prompt` or the term `widget`. While these terms are synonymous in the context of Universal Login, they are **not** interchangeable within your code.  To ensure successful customization, verify you are using the appropriate term listed for any elements you add to your code.
</Callout>

## Page template requirements

When creating a Universal Login page template, you must include the following tags:

<table>
  <thead>
    <tr>
      <th><strong>Tag</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>auth0:widget</code></td>
      <td>Contains HTML for the prompt displayed on every page of the login flow, such as the Login page or Reset Password page</td>
    </tr>

    <tr>
      <td><code>auth0:head</code></td>
      <td>Contains the tags required for rendering the prompt</td>
    </tr>
  </tbody>
</table>

To center the prompt on the page, add `class="_widget-auto-layout"` to the `<body>` element. You can omit this attribute to manually position the prompt as needed.

<Warning>
  **Page template limitations:**

  * CSS class names change each time Auth0 builds the project. Custom CSS that targets these classes will break with each new build.
  * The HTML structure of Universal Login pages is subject to change. Avoid customizations that rely on the HTML structure to prevent any interruptions.

  To learn more, review [CSS customization](#css-customization).
</Warning>

##### Example template:

The following example demonstrates the simplest Universal Login page template you can create with the required tags:

```liquid lines theme={null}
<!DOCTYPE html>
{% assign resolved_dir = dir | default: "auto" %}
<html lang="{{locale}}" dir="{{resolved_dir}}">
  <head>
    {%- auth0:head -%}
  </head>
  <body class="_widget-auto-layout">
    {%- auth0:widget -%}
  </body>
</html>
```

<Warning>
  If you use Storybook to view your template, be aware that the `<script>` tag breaks the rendering as it cannot parse these tags correctly.  As a workaround, use backticks (\`) and plus sign (+) characters to properly inject the `<script>` tag into your template code.

  **Example**:

  ``<scr`+`ipt>console.log("test");</scr`+`ipt>``
</Warning>

## Page template variables

Page templates support a variety of context variables that impact how a page is rendered.

For example, you can use these variables to:

* Render different content depending on the application associated with the login flow. For example, you may manage two brands that require different page designs.
* Render different content depending on the specific prompt. For example, you may want to add information about what your application offers on the Login page but prefer the MFA flow to only display the MFA challenge prompt.
* Add a footer with user support information, such as links to your support page or contact information.

### Available variables

Page templates support the following variables:

#### Application

<table>
  <thead>
    <tr>
      <th><strong>Variable</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Example</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>application.id</code></td>
      <td>Your application client ID</td>
      <td>XXXXXXXXXXXXXXXXXXXXXXXXX</td>
    </tr>

    <tr>
      <td><code>application.name</code></td>
      <td>The name of your application</td>
      <td>My Application</td>
    </tr>

    <tr>
      <td><code>application.logo\_url</code></td>
      <td>URL of the application logo</td>
      <td>`https://example.com/mylogo.png`</td>
    </tr>

    <tr>
      <td><code>application.metadata</code></td>
      <td>Your application metadata</td>

      <td>
        ```json lines theme={null}
        {
          "attribute1": "value",
          "attribute2": "value",
          "attribute3": "value"
        }
        ```
      </td>
    </tr>
  </tbody>
</table>

#### Branding

<table>
  <thead>
    <tr>
      <th><strong>Variable</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Example</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>branding.logo\_url</code></td>
      <td>URL of your application logo</td>
      <td>`https://example.com/mylogo.png`</td>
    </tr>

    <tr>
      <td><code>branding.colors.primary</code></td>
      <td>Your primary branding color</td>
      <td>#000000</td>
    </tr>

    <tr>
      <td><code>branding.colors.page\_background</code></td>
      <td>Background color for Universal Login pages</td>
      <td>#FFFFFF</td>
    </tr>
  </tbody>
</table>

#### Tenant

<table>
  <thead>
    <tr>
      <th><strong>Variable</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Example</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>tenant.friendly\_name</code></td>
      <td>Your tenant's display name</td>
      <td>My Tenant</td>
    </tr>

    <tr>
      <td><code>tenant.support\_email</code></td>
      <td>Support email address for your tenant</td>
      <td>[support@example.com](mailto:support@example.com)</td>
    </tr>

    <tr>
      <td><code>tenant.support\_url</code></td>
      <td>Support page URL for your tenant</td>
      <td>`https://example.com/support`</td>
    </tr>

    <tr>
      <td><code>tenant.enabled\_locales</code></td>
      <td>Comma-separated list of locales enabled for your tenant</td>
      <td><code>en, es</code></td>
    </tr>
  </tbody>
</table>

#### Organizations

The following variables refer to the [Auth0 Organizations](/docs/manage-users/organizations/organizations-overview) feature.

<table>
  <thead>
    <tr>
      <th><strong>Variable</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Example</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>organization.id</code></td>
      <td>ID of Organization</td>
      <td>org\_XXXXXXXXXXXXXXX</td>
    </tr>

    <tr>
      <td><code>organization.display\_name</code></td>
      <td>Display name of Organization</td>
      <td>My Organization</td>
    </tr>

    <tr>
      <td><code>organization.name</code></td>
      <td>Internal name of Organization</td>
      <td>my-organization</td>
    </tr>

    <tr>
      <td><code>organization.metadata</code></td>
      <td>Organization metadata</td>

      <td>
        ```json lines theme={null}
        {
          "attribute1": "value",
          "attribute2": "value",
          "attribute3": "value"
        }
        ```
      </td>
    </tr>

    <tr>
      <td><code>organization.branding.logo\_url</code></td>
      <td>URL of Organization logo</td>
      <td>`https://example.com/orglogo.png`</td>
    </tr>

    <tr>
      <td><code>organization.branding.colors.primary</code></td>
      <td>Primary branding color for Organization</td>
      <td>#000000</td>
    </tr>

    <tr>
      <td><code>organization.branding.colors.page\_background</code></td>
      <td>Background color for Organization's login pages</td>
      <td>#FFFFFF</td>
    </tr>
  </tbody>
</table>

#### Current user information

You can only use the following variables for pages that render after authentication.

<table>
  <thead>
    <tr>
      <th><strong>Variables</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Example</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>user.user\_id</code></td>
      <td>ID of the user profile</td>
      <td>auth0|XXXXXXXXXXXXXXXXXXXX</td>
    </tr>

    <tr>
      <td><code>user.picture</code></td>
      <td>URL of the user's profile picture</td>
      <td>`https://example.com/userimage`</td>
    </tr>

    <tr>
      <td><code>user.email</code></td>
      <td>Email address of user</td>
      <td>[user@example.com](mailto:user@example.com)</td>
    </tr>

    <tr>
      <td><code>user.email\_verified</code></td>
      <td>Boolean of email verification status (true/false)</td>
      <td>true</td>
    </tr>

    <tr>
      <td><code>user.user\_metadata</code></td>
      <td><code>user\_metadata</code> object of the user profile</td>

      <td>
        ```json lines theme={null}
        {
          "attribute1": "value",
          "attribute2": "value",
          "attribute3": "value"
        }
        ```
      </td>
    </tr>

    <tr>
      <td><code>user.family\_name</code></td>
      <td>Family (last) name of user</td>
      <td>Smith</td>
    </tr>

    <tr>
      <td><code>user.given\_name</code></td>
      <td>Given (first) name of user</td>
      <td>Abigail</td>
    </tr>

    <tr>
      <td><code>user.name</code></td>
      <td>Full name of user</td>
      <td>Abigail Smith</td>
    </tr>

    <tr>
      <td><code>user.nickname</code></td>
      <td>Nickname (alias) of user</td>
      <td>Abby</td>
    </tr>

    <tr>
      <td><code>user.username</code></td>
      <td>Internal name of user</td>
      <td>asmith</td>
    </tr>
  </tbody>
</table>

#### Current screen information

<table>
  <thead>
    <tr>
      <th><strong>Variables</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Example</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>dir</code></td>
      <td>Indicates the direction of the element's text.</td>
      <td><code>auto</code>, <code>rtl</code>, <code>ltr</code></td>
    </tr>

    <tr>
      <td><code>locale</code></td>
      <td>Locale used to render the page; matches one of the <a href="/docs/customize/internationalization-and-localization/universal-login-internationalization">supported tenant languages</a></td>
      <td>en-US</td>
    </tr>

    <tr>
      <td><code>prompt.name</code></td>
      <td>Name of the currently rendered <a href="#prompts">Universal Login prompt</a></td>
      <td>mfa</td>
    </tr>

    <tr>
      <td><code>prompt.screen.name</code></td>
      <td>Name of the currently rendered Universal Login screen</td>
      <td>mfa-login-options</td>
    </tr>

    <tr>
      <td><code>prompt.screen.texts</code></td>
      <td>All localized texts from the current screen</td>

      <td>
        ```json lines theme={null}
        {
          "pageTitle": "Available methods"
        }
        ```
      </td>
    </tr>

    <tr>
      <td><code>state</code></td>
      <td>Renders the current page's state value, which is opaque and used for security purposes.</td>

      <td />
    </tr>
  </tbody>
</table>

### Prompts

The term `prompt` refers to a specific step of the login flow. A specific prompt may consist of one or more screens. You can manage prompts through the [Auth0 Dashboard](https://manage.auth0.com/#/custom_text) or the prompts endpoints of the [Management API](https://auth0.com/docs/api/management/v2).

The sections below provide details for each available prompt.

<AccordionGroup>
  <Accordion title="brute-force-protection">
    ## Screen: brute-force-protection-unblock

    <Frame>
      <img alt="brute-force-protection-unblock reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Unblock My Account</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Unblock My Account</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: brute-force-protection-unblock-success

    <Frame>
      <img alt="brute-force-protection-unblock-success reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Unblock My Account</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Unblock My Account</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: brute-force-protection-unblock-failure

    <Frame>
      <img alt="brute-force-protection-unblock-failure reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Unblock My Account</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Unblock My Account</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="common">
    ## Screen: redeem-ticket

    <Frame>
      <img alt="redeem-ticket reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Loading...</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Javascript is not enabled on your browser, please click button to continue.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="consent">
    ## Screen: consent

    <Frame>![consent reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/consent.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Authorize \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Authorize App</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Hi \$\{userName},</td>
          <td><code>pickerTitle</code></td>
        </tr>

        <tr>
          <td>Tenant and Audience selector</td>
          <td><code>audiencePickerAltText</code></td>
        </tr>

        <tr>
          <td>\$\{clientName} is requesting access to your account.</td>
          <td><code>messageMultipleTenants</code></td>
        </tr>

        <tr>
          <td>$\{clientName} is requesting access to your \$\{companyName} account.</td>
          <td><code>messageSingleTenant</code></td>
        </tr>

        <tr>
          <td>Accept</td>
          <td><code>acceptButtonText</code></td>
        </tr>

        <tr>
          <td>Decline</td>
          <td><code>declineButtonText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Invalid action</td>
          <td><code>invalid-action</code></td>
        </tr>

        <tr>
          <td>Audience is required</td>
          <td><code>invalid-audience</code></td>
        </tr>

        <tr>
          <td>Invalid scope, must be an array</td>
          <td><code>invalid-scope</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="device-flow">
    ## Screen: device-code-activation

    <Frame>![device-code-activation reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/device-code-activation.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your device code to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Enter the code displayed on your device</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Enter your one-time code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Device Activation</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Invalid or expired user code</td>
          <td><code>invalid-expired-code</code></td>
        </tr>

        <tr>
          <td>Please enter the code displayed on your device</td>
          <td><code>no-code</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: device-code-activation-allowed

    <Frame>![device-code-activation-allowed reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/device-code-activation-allowed.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Login successful \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Your device is now connected.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Congratulations, you're all set!</td>
          <td><code>eventTitle</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: device-code-activation-denied

    <Frame>![device-code-activation-denied reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/device-code-activation-denied.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Login error \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>We are not able to activate your device.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Activation Denied</td>
          <td><code>eventTitle</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: device-code-confirmation

    <Frame>![device-code-confirmation reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/device-code-confirmation.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Confirm your device code to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Please confirm this is the code displayed on your \$\{clientName}:</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Secure code</td>
          <td><code>inputCodeLabel</code></td>
        </tr>

        <tr>
          <td>Device Confirmation</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Confirm</td>
          <td><code>confirmButtonText</code></td>
        </tr>

        <tr>
          <td>Cancel</td>
          <td><code>cancelButtonText</code></td>
        </tr>

        <tr>
          <td>If you did not initiate this action or you do not recognize this device select cancel.</td>
          <td><code>confirmationText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="email-otp-challenge">
    ## Screen: email-otp-challenge

    <Frame>![email-otp-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/email-otp-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your email code to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>We've sent an email with your code to \$\{email}</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Enter the code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Resend</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive an email?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>OTP Code must have 6 numeric characters</td>
          <td><code>invalid-otp-code-format</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>You have exceeded the amount of emails. Wait a few minutes and try again.</td>
          <td><code>too-many-email</code></td>
        </tr>

        <tr>
          <td>Please enter a code</td>
          <td><code>no-code</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="email-verification">
    ## Screen: email-verification-result

    <Frame>![email-verification-result reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/email-verification-result.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Email verification status \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Email Verified</td>
          <td><code>verifiedTitle</code></td>
        </tr>

        <tr>
          <td>Error</td>
          <td><code>errorTitle</code></td>
        </tr>

        <tr>
          <td>Your email address was successfully verified.</td>
          <td><code>verifiedDescription</code></td>
        </tr>

        <tr>
          <td>This account is already verified.</td>
          <td><code>alreadyVerifiedDescription</code></td>
        </tr>

        <tr>
          <td>User account does not exist or the verification code is invalid.</td>
          <td><code>invalidAccountOrCodeDescription</code></td>
        </tr>

        <tr>
          <td>Your email address could not be verified.</td>
          <td><code>unknownErrorDescription</code></td>
        </tr>

        <tr>
          <td>Back to \$\{clientName}</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>This ticket was expired.</td>
          <td><code>auth0-users-expired-ticket</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>custom-script-error-code</code></td>
        </tr>

        <tr>
          <td>This ticket was already used.</td>
          <td><code>auth0-users-used-ticket</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later</td>
          <td><code>auth0-users-validation</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="invitation">
    ## Screen: accept-invitation

    <Frame>![accept-invitation reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/accept-invitation.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Accept your invitation to sign up \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>You've Been Invited!</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>"\$\{inviterName}" has invited you ("\$\{email}") to join "\$\{companyName}" on "\$\{clientName}".</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="login">
    ## Screen: login

    <Frame>![login reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/login.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Log in</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Welcome</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Log in to \<%= "${companyName}" %&gt; to continue to &lt;%= "$" %>.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Or</td>
          <td><code>separatorText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Continue with \<%= "" %></td>
          <td><code>federatedConnectionButtonText</code></td>
        </tr>

        <tr>
          <td>Sign up</td>
          <td><code>signupActionLinkText</code></td>
        </tr>

        <tr>
          <td>Don't have an account?</td>
          <td><code>signupActionText</code></td>
        </tr>

        <tr>
          <td>Forgot password?</td>
          <td><code>forgotPasswordText</code></td>
        </tr>

        <tr>
          <td>Password</td>
          <td><code>passwordPlaceholder</code></td>
        </tr>

        <tr>
          <td>Username or email address</td>
          <td><code>usernamePlaceholder</code></td>
        </tr>

        <tr>
          <td>Email address</td>
          <td><code>emailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone number</td>
          <td><code>phonePlaceholder</code></td>
        </tr>

        <tr>
          <td>Username</td>
          <td><code>usernameOnlyPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone or Username or Email</td>
          <td><code>phoneOrUsernameOrEmailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone number or Email address</td>
          <td><code>phoneOrEmailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone Number or Username</td>
          <td><code>phoneOrUsernamePlaceholder</code></td>
        </tr>

        <tr>
          <td>Username or Email address</td>
          <td><code>usernameOrEmailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Edit</td>
          <td><code>editEmailText</code></td>
        </tr>

        <tr>
          <td>Alerts</td>
          <td><code>alertListTitle</code></td>
        </tr>

        <tr>
          <td>You've Been Invited!</td>
          <td><code>invitationTitle</code></td>
        </tr>

        <tr>
          <td>Log in to accept \<%= "${inviterName}" %&gt;'s invitation to join &lt;%= "$" %> on \<%= "\$" %>.</td>
          <td><code>invitationDescription</code></td>
        </tr>

        <tr>
          <td>\<%= "\$" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Show password</td>
          <td><code>showPasswordText</code></td>
        </tr>

        <tr>
          <td>Hide password</td>
          <td><code>hidePasswordText</code></td>
        </tr>

        <tr>
          <td>Wrong username or password</td>
          <td><code>wrong-credentials</code></td>
        </tr>

        <tr>
          <td>Wrong email or password</td>
          <td><code>wrong-email-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect username or password</td>
          <td><code>wrong-username-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect phone number or password</td>
          <td><code>wrong-phone-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect email address, username, or password</td>
          <td><code>wrong-email-username-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect email address, phone number, username, or password. Phone numbers must include the country code.</td>
          <td><code>wrong-email-phone-username-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect email address, phone number, or password. Phone numbers must include the country code.</td>
          <td><code>wrong-email-phone-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect phone number, username or password. Phone numbers must include the country code.</td>
          <td><code>wrong-phone-username-credentials</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>Invalid or expired user code</td>
          <td><code>invalid-expired-code</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>custom-script-error-code</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later</td>
          <td><code>auth0-users-validation</code></td>
        </tr>

        <tr>
          <td>We are sorry, something went wrong when attempting to log in</td>
          <td><code>authentication-failure</code></td>
        </tr>

        <tr>
          <td>Invalid connection</td>
          <td><code>invalid-connection</code></td>
        </tr>

        <tr>
          <td>We have detected suspicious login behavior and further attempts will be blocked. Please contact the administrator.</td>
          <td><code>ip-blocked</code></td>
        </tr>

        <tr>
          <td>Invalid connection</td>
          <td><code>no-db-connection</code></td>
        </tr>

        <tr>
          <td>We have detected a potential security issue with this account. To protect your account, we have prevented this login. Please reset your password to proceed.</td>
          <td><code>password-breached</code></td>
        </tr>

        <tr>
          <td>Your account has been blocked after multiple consecutive login attempts.</td>
          <td><code>user-blocked</code></td>
        </tr>

        <tr>
          <td>Too many login attempts for this user. Please wait, and try again later.</td>
          <td><code>same-user-login</code></td>
        </tr>

        <tr>
          <td>Please enter an email address</td>
          <td><code>no-email</code></td>
        </tr>

        <tr>
          <td>Password is required</td>
          <td><code>no-password</code></td>
        </tr>

        <tr>
          <td>Username is required</td>
          <td><code>no-username</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="login-id">
    ## Screen: login-id

    <Frame>![login-id reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/login-id.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Log in</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Welcome</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Log in to \<%= "${companyName}" %&gt; to continue to &lt;%= "$" %>.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Or</td>
          <td><code>separatorText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Continue with \<%= "" %></td>
          <td><code>federatedConnectionButtonText</code></td>
        </tr>

        <tr>
          <td>Can't log in to your account?</td>
          <td><code>forgotPasswordText</code></td>
        </tr>

        <tr>
          <td>Sign up</td>
          <td><code>signupActionLinkText</code></td>
        </tr>

        <tr>
          <td>Don't have an account?</td>
          <td><code>signupActionText</code></td>
        </tr>

        <tr>
          <td>Password</td>
          <td><code>passwordPlaceholder</code></td>
        </tr>

        <tr>
          <td>Username or email address</td>
          <td><code>usernamePlaceholder</code></td>
        </tr>

        <tr>
          <td>Email address</td>
          <td><code>emailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone number</td>
          <td><code>phonePlaceholder</code></td>
        </tr>

        <tr>
          <td>Username</td>
          <td><code>usernameOnlyPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone or Username or Email</td>
          <td><code>phoneOrUsernameOrEmailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone number or Email address</td>
          <td><code>phoneOrEmailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone Number or Username</td>
          <td><code>phoneOrUsernamePlaceholder</code></td>
        </tr>

        <tr>
          <td>Username or Email address</td>
          <td><code>usernameOrEmailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Edit</td>
          <td><code>editEmailText</code></td>
        </tr>

        <tr>
          <td>Alerts</td>
          <td><code>alertListTitle</code></td>
        </tr>

        <tr>
          <td>\<%= "\$" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Continue with a passkey</td>
          <td><code>passkeyButtonText</code></td>
        </tr>

        <tr>
          <td>Wrong username or password</td>
          <td><code>wrong-credentials</code></td>
        </tr>

        <tr>
          <td>Wrong email or password</td>
          <td><code>wrong-email-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect username or password</td>
          <td><code>wrong-username-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect phone number or password</td>
          <td><code>wrong-phone-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect email address, username, or password</td>
          <td><code>wrong-email-username-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect email address, phone number, username, or password. Phone numbers must include the country code.</td>
          <td><code>wrong-email-phone-username-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect email address, phone number, or password. Phone numbers must include the country code.</td>
          <td><code>wrong-email-phone-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect phone number, username or password. Phone numbers must include the country code.</td>
          <td><code>wrong-phone-username-credentials</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>Invalid or expired user code</td>
          <td><code>invalid-expired-code</code></td>
        </tr>

        <tr>
          <td>Username can only contain alphanumeric characters or: '\<%= "${characters}" %&gt;'. Username should have between &lt;%= "$" %> and \<%= "\$" %> characters.</td>
          <td><code>invalid-username</code></td>
        </tr>

        <tr>
          <td>Invalid Login ID entered</td>
          <td><code>invalid-login-id</code></td>
        </tr>

        <tr>
          <td>Enter a valid email address or phone number. Phone numbers must include the country code.</td>
          <td><code>invalid-email-phone</code></td>
        </tr>

        <tr>
          <td>Enter a valid email address or username</td>
          <td><code>invalid-email-username</code></td>
        </tr>

        <tr>
          <td>Enter a valid phone number or username. Phone numbers must include the country code.</td>
          <td><code>invalid-phone-username</code></td>
        </tr>

        <tr>
          <td>Enter a valid email address, phone number, or username. Phone numbers must include the country code.</td>
          <td><code>invalid-email-phone-username</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>custom-script-error-code</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later</td>
          <td><code>auth0-users-validation</code></td>
        </tr>

        <tr>
          <td>We are sorry, something went wrong when attempting to log in</td>
          <td><code>authentication-failure</code></td>
        </tr>

        <tr>
          <td>Invalid connection</td>
          <td><code>invalid-connection</code></td>
        </tr>

        <tr>
          <td>We have detected suspicious login behavior and further attempts will be blocked. Please contact the administrator.</td>
          <td><code>ip-blocked</code></td>
        </tr>

        <tr>
          <td>Invalid connection</td>
          <td><code>no-db-connection</code></td>
        </tr>

        <tr>
          <td>Email does not match any enterprise directory</td>
          <td><code>no-hrd-connection</code></td>
        </tr>

        <tr>
          <td>We have detected a potential security issue with this account. To protect your account, we have prevented this login. Please reset your password to proceed.</td>
          <td><code>password-breached</code></td>
        </tr>

        <tr>
          <td>Your account has been blocked after multiple consecutive login attempts.</td>
          <td><code>user-blocked</code></td>
        </tr>

        <tr>
          <td>Too many login attempts for this user. Please wait, and try again later.</td>
          <td><code>same-user-login</code></td>
        </tr>

        <tr>
          <td>Please enter an email address</td>
          <td><code>no-email</code></td>
        </tr>

        <tr>
          <td>Password is required</td>
          <td><code>no-password</code></td>
        </tr>

        <tr>
          <td>Username is required</td>
          <td><code>no-username</code></td>
        </tr>

        <tr>
          <td>Enter a valid phone number</td>
          <td><code>invalid-phone-number</code></td>
        </tr>

        <tr>
          <td>Password and passkey are not allowed</td>
          <td><code>conflict-password-passkey</code></td>
        </tr>

        <tr>
          <td>Password is not allowed</td>
          <td><code>password-not-allowed</code></td>
        </tr>

        <tr>
          <td>Passkey is not allowed</td>
          <td><code>passkey-not-allowed</code></td>
        </tr>

        <tr>
          <td>Please select a passkey</td>
          <td><code>no-passkey</code></td>
        </tr>

        <tr>
          <td>Passkey authentication failed</td>
          <td><code>passkey-authentication-failed</code></td>
        </tr>

        <tr>
          <td>Something went wrong. Please try again later.</td>
          <td><code>invalid-passkey</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="login-password">
    ## Screen: login-password

    <Frame>![login-password reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/login-password.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your password to log in</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Enter Your Password</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Enter your password for \<%= "${companyName}" %&gt; to continue to &lt;%= "$" %></td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Or</td>
          <td><code>separatorText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Continue with \<%= "" %></td>
          <td><code>federatedConnectionButtonText</code></td>
        </tr>

        <tr>
          <td>Sign up</td>
          <td><code>signupActionLinkText</code></td>
        </tr>

        <tr>
          <td>Don't have an account?</td>
          <td><code>signupActionText</code></td>
        </tr>

        <tr>
          <td>Forgot password?</td>
          <td><code>forgotPasswordText</code></td>
        </tr>

        <tr>
          <td>Password</td>
          <td><code>passwordPlaceholder</code></td>
        </tr>

        <tr>
          <td>Username or email address</td>
          <td><code>usernamePlaceholder</code></td>
        </tr>

        <tr>
          <td>Email address</td>
          <td><code>emailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Edit</td>
          <td><code>editEmailText</code></td>
        </tr>

        <tr>
          <td>Edit email address</td>
          <td><code>editLinkScreenReadableText</code></td>
        </tr>

        <tr>
          <td>Alerts</td>
          <td><code>alertListTitle</code></td>
        </tr>

        <tr>
          <td>You've Been Invited!</td>
          <td><code>invitationTitle</code></td>
        </tr>

        <tr>
          <td>Log in to accept \<%= "${inviterName}" %&gt;'s invitation to join &lt;%= "$" %> on \<%= "\$" %>.</td>
          <td><code>invitationDescription</code></td>
        </tr>

        <tr>
          <td>\<%= "\$" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Use Fingerprint or Face Recognition</td>
          <td><code>useBiometricsText</code></td>
        </tr>

        <tr>
          <td>Show password</td>
          <td><code>showPasswordText</code></td>
        </tr>

        <tr>
          <td>Hide password</td>
          <td><code>hidePasswordText</code></td>
        </tr>

        <tr>
          <td>Wrong username or password</td>
          <td><code>wrong-credentials</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>Invalid or expired user code</td>
          <td><code>invalid-expired-code</code></td>
        </tr>

        <tr>
          <td>Wrong email or password</td>
          <td><code>wrong-email-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect username or password</td>
          <td><code>wrong-username-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect phone number or password</td>
          <td><code>wrong-phone-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect email address, username, or password</td>
          <td><code>wrong-email-username-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect email address, phone number, username, or password. Phone numbers must include the country code.</td>
          <td><code>wrong-email-phone-username-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect email address, phone number, or password. Phone numbers must include the country code.</td>
          <td><code>wrong-email-phone-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect phone number, username or password. Phone numbers must include the country code.</td>
          <td><code>wrong-phone-username-credentials</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>custom-script-error-code</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later</td>
          <td><code>auth0-users-validation</code></td>
        </tr>

        <tr>
          <td>We are sorry, something went wrong when attempting to log in</td>
          <td><code>authentication-failure</code></td>
        </tr>

        <tr>
          <td>Invalid connection</td>
          <td><code>invalid-connection</code></td>
        </tr>

        <tr>
          <td>We have detected suspicious login behavior and further attempts will be blocked. Please contact the administrator.</td>
          <td><code>ip-blocked</code></td>
        </tr>

        <tr>
          <td>Invalid connection</td>
          <td><code>no-db-connection</code></td>
        </tr>

        <tr>
          <td>We have detected a potential security issue with this account. To protect your account, we have prevented this login. Please reset your password to proceed.</td>
          <td><code>password-breached</code></td>
        </tr>

        <tr>
          <td>Your account has been blocked after multiple consecutive login attempts.</td>
          <td><code>user-blocked</code></td>
        </tr>

        <tr>
          <td>Too many login attempts for this user. Please wait, and try again later.</td>
          <td><code>same-user-login</code></td>
        </tr>

        <tr>
          <td>Please enter an email address</td>
          <td><code>no-email</code></td>
        </tr>

        <tr>
          <td>Password is required</td>
          <td><code>no-password</code></td>
        </tr>

        <tr>
          <td>Username is required</td>
          <td><code>no-username</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="login-passwordless">
    ## Screen: login-passwordless-email-code

    <Frame>
      <img alt="login-passwordless-email-code reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your email code to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>We've sent an email with your code to \$\{email}</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Enter the code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Resend</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive an email?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Code is invalid</td>
          <td><code>invalid-verification-code</code></td>
        </tr>

        <tr>
          <td>Code could not be sent. Please try again later.</td>
          <td><code>passwordless-authenticator-error</code></td>
        </tr>

        <tr>
          <td>Something went wrong. Please try again later.</td>
          <td><code>passwordless-unknown-error</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: login-passwordless-email-link

    <Frame>
      <img alt="login-passwordless-email-link reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Email Sign In Link \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Email sent</td>
          <td><code>successTitle</code></td>
        </tr>

        <tr>
          <td>Something went wrong</td>
          <td><code>errorTitle</code></td>
        </tr>

        <tr>
          <td>Email sent. Check your inbox for a login link.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Please try again later.</td>
          <td><code>unknownErrorDescription</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: login-passwordless-sms-otp

    <Frame>
      <img alt="login-passwordless-sms-otp reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your phone code to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>We've sent a text message to:</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Edit</td>
          <td><code>editText</code></td>
        </tr>

        <tr>
          <td>Enter the 6-digit code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Resend</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive a code?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Code is invalid</td>
          <td><code>invalid-verification-code</code></td>
        </tr>

        <tr>
          <td>Code could not be sent. Please try again later.</td>
          <td><code>passwordless-authenticator-error</code></td>
        </tr>

        <tr>
          <td>Something went wrong. Please try again later.</td>
          <td><code>passwordless-unknown-error</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="login-email-verification">
    ## Screen: login-email-verification

    <Frame>![login-email-verification reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/login-email-verification.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your email code to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>We've sent an email with your code to \$\{email}</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Enter the code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Resend</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive an email?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>Verify Your Email</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>OTP Code must have 6 numeric characters</td>
          <td><code>invalid-otp-code-format</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>Invalid or expired user code</td>
          <td><code>invalid-expired-code</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>You have exceeded the amount of emails. Wait a few minutes and try again.</td>
          <td><code>too-many-email</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="logout">
    ## Screen: logout

    <Frame>
      <img alt="logout reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Logout \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Logout</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Hi \$\{userName},</td>
          <td><code>userSalute</code></td>
        </tr>

        <tr>
          <td>Are you sure you want to log out from \$\{clientName}?</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Yes</td>
          <td><code>acceptButtonText</code></td>
        </tr>

        <tr>
          <td>No</td>
          <td><code>declineButtonText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="mfa">
    ## Screen: mfa-detect-browser-capabilities

    <Frame>
      <img alt="mfa-detect-browser-capabilities reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Reload</td>
          <td><code>reloadButtonText</code></td>
        </tr>

        <tr>
          <td>JavaScript Required</td>
          <td><code>noJSErrorTitle</code></td>
        </tr>

        <tr>
          <td>Your browser does not have JavaScript enabled. Please enable and press the Reload page button.</td>
          <td><code>noJSErrorDescription</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-enroll-result

    <Frame>![mfa-enroll-result reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-enroll-result.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>MFA enrollment status</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>You're All Set!</td>
          <td><code>enrolledTitle</code></td>
        </tr>

        <tr>
          <td>You have successfully added a new authentication factor.</td>
          <td><code>enrolledDescription</code></td>
        </tr>

        <tr>
          <td>Invalid Link</td>
          <td><code>invalidTicketTitle</code></td>
        </tr>

        <tr>
          <td>This link is invalid or expired.</td>
          <td><code>invalidTicketDescription</code></td>
        </tr>

        <tr>
          <td>Expired Link</td>
          <td><code>expiredTicketTitle</code></td>
        </tr>

        <tr>
          <td>This link is expired.</td>
          <td><code>expiredTicketDescription</code></td>
        </tr>

        <tr>
          <td>Already used</td>
          <td><code>alreadyUsedTitle</code></td>
        </tr>

        <tr>
          <td>This link has already been used. Please get a new link to enroll with Multi-factor Authentication.</td>
          <td><code>alreadyUsedDescription</code></td>
        </tr>

        <tr>
          <td>Two-factor Verification has Already Been Enabled.</td>
          <td><code>alreadyEnrolledDescription</code></td>
        </tr>

        <tr>
          <td>Something Went Wrong</td>
          <td><code>genericError</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-login-options

    <Frame>![mfa-login-options reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-login-options.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>List of other login methods \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backText</code></td>
        </tr>

        <tr>
          <td>Other Methods</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>SMS</td>
          <td><code>authenticatorNamesSMS</code></td>
        </tr>

        <tr>
          <td>Phone</td>
          <td><code>authenticatorNamesVoice</code></td>
        </tr>

        <tr>
          <td>Phone</td>
          <td><code>authenticatorNamesPhone</code></td>
        </tr>

        <tr>
          <td>Notification via \$\{appName} app</td>
          <td><code>authenticatorNamesPushNotification</code></td>
        </tr>

        <tr>
          <td>Google Authenticator or similar</td>
          <td><code>authenticatorNamesOTP</code></td>
        </tr>

        <tr>
          <td>Email</td>
          <td><code>authenticatorNamesEmail</code></td>
        </tr>

        <tr>
          <td>Recovery code</td>
          <td><code>authenticatorNamesRecoveryCode</code></td>
        </tr>

        <tr>
          <td>Notification via DUO app</td>
          <td><code>authenticatorNamesDUO</code></td>
        </tr>

        <tr>
          <td>Security Key</td>
          <td><code>authenticatorNamesWebauthnRoaming</code></td>
        </tr>

        <tr>
          <td>Fingerprint or Face Recognition</td>
          <td><code>authenticatorNamesWebauthnPlatform</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-begin-enroll-options

    <Frame>![mfa-begin-enroll-options reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-begin-enroll-options.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Add another authentication method \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backText</code></td>
        </tr>

        <tr>
          <td>Keep Your Account Safe</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Add another authentication method.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>SMS</td>
          <td><code>authenticatorNamesSMS</code></td>
        </tr>

        <tr>
          <td>Phone</td>
          <td><code>authenticatorNamesVoice</code></td>
        </tr>

        <tr>
          <td>Phone</td>
          <td><code>authenticatorNamesPhone</code></td>
        </tr>

        <tr>
          <td>Notification via \$\{appName} app</td>
          <td><code>authenticatorNamesPushNotification</code></td>
        </tr>

        <tr>
          <td>Google Authenticator or similar</td>
          <td><code>authenticatorNamesOTP</code></td>
        </tr>

        <tr>
          <td>Email</td>
          <td><code>authenticatorNamesEmail</code></td>
        </tr>

        <tr>
          <td>Recovery code</td>
          <td><code>authenticatorNamesRecoveryCode</code></td>
        </tr>

        <tr>
          <td>Notification via DUO app</td>
          <td><code>authenticatorNamesDUO</code></td>
        </tr>

        <tr>
          <td>Security Key</td>
          <td><code>authenticatorNamesWebauthnRoaming</code></td>
        </tr>

        <tr>
          <td>Fingerprint or Face Recognition</td>
          <td><code>authenticatorNamesWebauthnPlatform</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="mfa-email">
    ## Screen: mfa-email-challenge

    <Frame>![mfa-email-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-email-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your email code to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Go Back</td>
          <td><code>backText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>We've sent an email with your code to</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter the code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>Resend</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive an email?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>OTP Code must have 6 numeric characters</td>
          <td><code>invalid-otp-code-format</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>Notification was not sent. Try resending the code.</td>
          <td><code>no-transaction-in-progress</code></td>
        </tr>

        <tr>
          <td>You have exceeded the amount of emails. Wait a few minutes and try again.</td>
          <td><code>too-many-email</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>We couldn't send the email. Please try again later.</td>
          <td><code>mfa-email-challenge-authenticator-error</code></td>
        </tr>

        <tr>
          <td>Please enter a code</td>
          <td><code>no-code</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-email-list

    <Frame>![mfa-email-list reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-email-list.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>List of available email addresses \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backText</code></td>
        </tr>

        <tr>
          <td>Enrolled Email Addresses</td>
          <td><code>title</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="mfa-otp">
    ## Screen: mfa-otp-enrollment-qr

    <Frame>![mfa-otp-enrollment-qr reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-otp-enrollment-qr.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Scan the code to log in using a one-time password \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Secure Your Account</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Scan the QR Code below using your preferred authenticator app and then enter the provided one-time code below.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Trouble Scanning?</td>
          <td><code>codeEnrollmentText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter your one-time code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Then</td>
          <td><code>separatorText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>OTP Code must have 6 numeric characters</td>
          <td><code>invalid-otp-code-format</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>Too many failed codes. Wait for some minutes before retrying.</td>
          <td><code>too-many-failures</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>You are already enrolled on MFA.</td>
          <td><code>user-already-enrolled</code></td>
        </tr>

        <tr>
          <td>Please enter a code</td>
          <td><code>no-code</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-otp-enrollment-code

    <Frame>![mfa-otp-enrollment-code reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-otp-enrollment-code.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Copy the code to log in using a one-time password \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Secure code to copy</td>
          <td><code>altText</code></td>
        </tr>

        <tr>
          <td>Copy code</td>
          <td><code>copyCodeButtonText</code></td>
        </tr>

        <tr>
          <td>Manually enter the following code into your preferred authenticator app and then enter the provided one-time code below.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter your one-time code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Secure Your Account</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Too many failed codes. Wait for some minutes before retrying.</td>
          <td><code>too-many-failures</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>Please enter a code</td>
          <td><code>no-code</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-otp-challenge

    <Frame>![mfa-otp-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-otp-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your one-time password to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Check your preferred one-time password application for a code.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter your one-time code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Use password</td>
          <td><code>usePasswordText</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>Too many failed codes. Wait for some minutes before retrying.</td>
          <td><code>too-many-failures</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>Please enter a code</td>
          <td><code>no-code</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="mfa-phone">
    ## Screen: mfa-phone-challenge

    <Frame>![mfa-phone-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-phone-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Use your phone number to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>We will send a 6-digit code to the following phone number:</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>continueButtonText</code></td>
        </tr>

        <tr>
          <td>Choose another phone number.</td>
          <td><code>changePhoneText</code></td>
        </tr>

        <tr>
          <td>Text message</td>
          <td><code>smsButtonText</code></td>
        </tr>

        <tr>
          <td>Voice call</td>
          <td><code>voiceButtonText</code></td>
        </tr>

        <tr>
          <td>How do you want to receive the code?</td>
          <td><code>chooseMessageTypeText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter your phone number</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>There was a problem sending the SMS</td>
          <td><code>send-sms-failed</code></td>
        </tr>

        <tr>
          <td>There was a problem making the voice call</td>
          <td><code>send-voice-failed</code></td>
        </tr>

        <tr>
          <td>Phone number can only include digits.</td>
          <td><code>invalid-phone-format</code></td>
        </tr>

        <tr>
          <td>It seems that your phone number is not valid. Please check and retry.</td>
          <td><code>invalid-phone</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-sms</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-voice</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>Please enter a phone number</td>
          <td><code>no-phone</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-phone-enrollment

    <Frame>![mfa-phone-enrollment reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-phone-enrollment.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your phone number to log in using a phone code \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Secure Your Account</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Enter your country code and phone number to which we can send a 6-digit code:</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>continueButtonText</code></td>
        </tr>

        <tr>
          <td>Text message</td>
          <td><code>smsButtonText</code></td>
        </tr>

        <tr>
          <td>Voice call</td>
          <td><code>voiceButtonText</code></td>
        </tr>

        <tr>
          <td>How do you want to receive the code?</td>
          <td><code>chooseMessageTypeText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter your phone number</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>There was a problem sending the SMS</td>
          <td><code>send-sms-failed</code></td>
        </tr>

        <tr>
          <td>There was a problem making the voice call</td>
          <td><code>send-voice-failed</code></td>
        </tr>

        <tr>
          <td>We couldn't send the SMS. Please try again later.</td>
          <td><code>sms-authenticator-error</code></td>
        </tr>

        <tr>
          <td>Phone number can only include digits.</td>
          <td><code>invalid-phone-format</code></td>
        </tr>

        <tr>
          <td>It seems that your phone number is not valid. Please check and retry.</td>
          <td><code>invalid-phone</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-sms</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-voice</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again. \[<strong>note: this error is not typically reachable</strong>]</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>Please enter a phone number</td>
          <td><code>no-phone</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="mfa-push">
    ## Screen: mfa-push-welcome

    <Frame>![mfa-push-welcome reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-push-welcome.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Install the application \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Secure Your Account</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>In order to continue, install the \$\{appName} app via the app store from your mobile device.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Google Play</td>
          <td><code>androidButtonText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>App Store</td>
          <td><code>iosButtonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-push-enrollment-qr

    <Frame>![mfa-push-enrollment-qr reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-push-enrollment-qr.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Scan the code to log in using a push notification \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Secure Your Account</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Scan the QR Code below using the \$\{appName} app on your mobile device.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>You must scan the QR code with the \$\{appName} app on your mobile device.</td>
          <td><code>enrollment-transaction-pending</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-push-challenge-push

    <Frame>![mfa-push-challenge-push reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-push-challenge-push.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Accept the push notification to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>We’ve sent a notification to the following device via the \$\{appName} app:</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>I've responded on my device</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>Resend</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive a notification?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>Manually Enter Code</td>
          <td><code>enterOtpCode</code></td>
        </tr>

        <tr>
          <td>OR</td>
          <td><code>separatorText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>You must accept the notification via the \$\{appName} app on your mobile device.</td>
          <td><code>challenge-transaction-pending</code></td>
        </tr>

        <tr>
          <td>We have not received a confirmation, please slow down.</td>
          <td><code>polling-interval-exceeded</code></td>
        </tr>

        <tr>
          <td>We have received too many notification requests. Wait a few minutes and try again.</td>
          <td><code>too-many-push</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>We have not received a confirmation, please try scanning the code again.</td>
          <td><code>mfa-push-verify-transaction-pending</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the enrollment. Please try again later.</td>
          <td><code>mfa-push-verify-authenticator-error</code></td>
        </tr>

        <tr>
          <td>We couldn't send the notification. Please try again later.</td>
          <td><code>mfa-push-challenge-authenticator-error</code></td>
        </tr>

        <tr>
          <td>Notification rejected</td>
          <td><code>transaction-rejected</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-push-list

    <Frame>![mfa-push-list reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-push-list.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>List of available devices \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backText</code></td>
        </tr>

        <tr>
          <td>Registered Devices</td>
          <td><code>title</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="mfa-recovery-code">
    ## Screen: mfa-recovery-code-enrollment

    <Frame>![mfa-recovery-code-enrollment reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-recovery-code-enrollment.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Copy your recovery code for safe keeping \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Almost There!</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Copy this recovery code and keep it somewhere safe. You’ll need it if you ever need to log in without your device.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Secure code to copy</td>
          <td><code>altText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>I have safely recorded this code</td>
          <td><code>checkboxText</code></td>
        </tr>

        <tr>
          <td>Copy code</td>
          <td><code>copyCodeButtonText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Please confirm you have recorded the code</td>
          <td><code>no-confirmation</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-recovery-code-challenge

    <Frame>![mfa-recovery-code-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-recovery-code-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your recovery code to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Enter the recovery code you were provided during your initial enrollment.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter your recovery code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>Recovery code must have 24 alphanumeric characters</td>
          <td><code>invalid-code-format</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>Please confirm you have recorded the code</td>
          <td><code>no-confirmation</code></td>
        </tr>

        <tr>
          <td>Too many failed codes. Wait for some minutes before retrying.</td>
          <td><code>too-many-failures</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="mfa-sms">
    ## Screen: mfa-country-codes

    <Frame>![mfa-country-codes reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-country-codes.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Select your country code \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backText</code></td>
        </tr>

        <tr>
          <td>Select a Country Code</td>
          <td><code>title</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-sms-enrollment

    <Frame>![mfa-sms-enrollment reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-sms-enrollment.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your phone number to log in using a text message \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Secure Your Account</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Enter your phone number below. An SMS will be sent to that number with a code to enter on the next screen.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter your phone number</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>There was a problem sending the SMS</td>
          <td><code>send-sms-failed</code></td>
        </tr>

        <tr>
          <td>We couldn't send the SMS. Please try again later.</td>
          <td><code>sms-authenticator-error</code></td>
        </tr>

        <tr>
          <td>Phone number can only include digits.</td>
          <td><code>invalid-phone-format</code></td>
        </tr>

        <tr>
          <td>Seems that your phone number is not valid. Please check and retry.</td>
          <td><code>invalid-phone</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-sms</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>Please enter a phone number</td>
          <td><code>no-phone</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-sms-challenge

    <Frame>![mfa-sms-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-sms-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your phone code to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>We've sent a text message to:</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Edit</td>
          <td><code>editText</code></td>
        </tr>

        <tr>
          <td>Edit phone number</td>
          <td><code>editLinkScreenReadableText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter the 6-digit code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>Resend</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive a code?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>or</td>
          <td><code>resendVoiceActionSeparatorTextBefore</code></td>
        </tr>

        <tr>
          <td>get a call</td>
          <td><code>resendVoiceActionText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>OTP Code must have 6 numeric characters</td>
          <td><code>invalid-otp-code-format</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>There was a problem sending the SMS</td>
          <td><code>send-sms-failed</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>We couldn't send the SMS. Please try again later.</td>
          <td><code>sms-authenticator-error</code></td>
        </tr>

        <tr>
          <td>Notification was not sent. Try resending the code.</td>
          <td><code>no-transaction-in-progress</code></td>
        </tr>

        <tr>
          <td>Too many failed codes. Wait for some minutes before retrying.</td>
          <td><code>too-many-failures</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-sms</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>Please enter a code</td>
          <td><code>no-code</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-sms-list

    <Frame>![mfa-sms-list reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-sms-list.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>List of available phone numbers \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backText</code></td>
        </tr>

        <tr>
          <td>Enrolled Phone Numbers</td>
          <td><code>title</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="mfa-voice">
    ## Screen: mfa-voice-enrollment

    <Frame>![mfa-voice-enrollment reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-voice-enrollment.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your phone number to log in using a phone code \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Secure Your Account</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Enter your phone number below. A voice call will be placed on that number with a code to enter on the next screen.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter your phone number</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>There was a problem sending the SMS</td>
          <td><code>send-sms-failed</code></td>
        </tr>

        <tr>
          <td>Phone number can only include digits.</td>
          <td><code>invalid-phone-format</code></td>
        </tr>

        <tr>
          <td>Seems that your phone number is not valid. Please check and retry.</td>
          <td><code>invalid-phone</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-sms</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>Please enter a phone number</td>
          <td><code>no-phone</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-voice-challenge

    <Frame>![mfa-voice-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-voice-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your phone code to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>We've sent a 6-digit code via voice phone call to the following phone number:</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Edit</td>
          <td><code>editText</code></td>
        </tr>

        <tr>
          <td>Edit phone number</td>
          <td><code>editLinkScreenReadableText</code></td>
        </tr>

        <tr>
          <td>Choose another phone number.</td>
          <td><code>changePhoneText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter the 6-digit code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>Call again</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive a call?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>or</td>
          <td><code>resendSmsActionSeparatorTextBefore</code></td>
        </tr>

        <tr>
          <td>send a text</td>
          <td><code>resendSmsActionText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>OTP Code must have 6 numeric characters</td>
          <td><code>invalid-otp-code-format</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>There was a problem making the voice call</td>
          <td><code>send-voice-failed</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>We couldn't make the voice call. Please try again later.</td>
          <td><code>voice-authenticator-error</code></td>
        </tr>

        <tr>
          <td>Notification was not sent. Try resending the code.</td>
          <td><code>no-transaction-in-progress</code></td>
        </tr>

        <tr>
          <td>Too many failed codes. Wait for some minutes before retrying.</td>
          <td><code>too-many-failures</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-voice</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>Please enter a code</td>
          <td><code>no-code</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="mfa-webauthn">
    ## Screen: mfa-webauthn-platform-enrollment

    <Frame>
      <img alt="mfa-webauthn-enrollment reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Log in faster on this device \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Log In Faster on This Device</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Trust this device? You can quickly and securely log in the next time using this device's fingerprint or face recognition.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Awaiting device confirmation</td>
          <td><code>awaitingConfirmation</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>continueButtonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Remind me later</td>
          <td><code>snoozeEnrollmentButtonText</code></td>
        </tr>

        <tr>
          <td>Not on this device</td>
          <td><code>refuseAddingDeviceText</code></td>
        </tr>

        <tr>
          <td>Not now</td>
          <td><code>skipAddingDeviceText</code></td>
        </tr>

        <tr>
          <td>We could not start the device enrollment. Please try again later.</td>
          <td><code>webauthn-platform-associate-error</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-webauthn-roaming-enrollment

    <Frame>
      <img alt="mfa-webauthn-guidance-enrollment reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Register your security key \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Adding Your Security Key</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Security Keys can be used as an additional authentication factor.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Awaiting Security Key</td>
          <td><code>awaitingConfirmation</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Use security key</td>
          <td><code>continueButtonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Connect your Security Key and continue.</td>
          <td><code>instructions1</code></td>
        </tr>

        <tr>
          <td>Follow the steps on the browser.</td>
          <td><code>instructions2</code></td>
        </tr>

        <tr>
          <td>Name your Security Key to easily identify it later.</td>
          <td><code>instructions3</code></td>
        </tr>

        <tr>
          <td>We could not start the security key enrollment. Please try again later.</td>
          <td><code>webauthn-associate-error</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-webauthn-platform-challenge

    <Frame>
      <img alt="mfa-webauthn-challenge-user-initiated reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Use fingerprint or face recognition to login \$\{clientName}</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Press the button below and follow your browser's steps to log in.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Awaiting device confirmation</td>
          <td><code>awaitingConfirmation</code></td>
        </tr>

        <tr>
          <td>Too many failed authentication attempts. Please try again later.</td>
          <td><code>too-many-webauthn-challenge-attempts-error</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>continueButtonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Use password</td>
          <td><code>usePasswordText</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>We could not start the device verification. Please try again later.</td>
          <td><code>webauthn-platform-challenge-error</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-webauthn-roaming-challenge

    <Frame>
      <img alt="mfa-webauthn-challenge-user-initiated reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Use your security key to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Make sure your Security Key is nearby. Once you continue, you will be prompted to use it.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Awaiting Security Key</td>
          <td><code>awaitingConfirmation</code></td>
        </tr>

        <tr>
          <td>Too many failed authentication attempts. Please try again later.</td>
          <td><code>too-many-webauthn-challenge-attempts-error</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Use security key</td>
          <td><code>continueButtonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>We could not start the security key verification. Please try again later.</td>
          <td><code>webauthn-challenge-error</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-webauthn-change-key-nickname

    <Frame>
      <img alt="mfa-webauthn-change-key-nickname reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Name your security key \$\{clientName}</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>If you own multiple keys, this alias will help you identify the right one.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>\$\{userName}'s key</td>
          <td><code>nickname</code></td>
        </tr>

        <tr>
          <td>Security key name</td>
          <td><code>nicknamePlaceholder</code></td>
        </tr>

        <tr>
          <td>Name your device</td>
          <td>\$\{clientName}</td>
        </tr>

        <tr>
          <td>If you own multiple devices, this alias will help you identify the right one.</td>
          <td><code>descriptionPlatform</code></td>
        </tr>

        <tr>
          <td>$\{userName}'s \$\{deviceName}</td>
          <td><code>nicknamePlatform</code></td>
        </tr>

        <tr>
          <td>Device name</td>
          <td><code>nicknamePlaceholderPlatform</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>We could not update your key's name. Please try again.</td>
          <td><code>webauthn-patch-nickname-error</code></td>
        </tr>

        <tr>
          <td>We could not update your Device's name. Please try again.</td>
          <td><code>webauthn-platform-patch-nickname-error</code></td>
        </tr>

        <tr>
          <td>Name is required</td>
          <td><code>no-nickname</code></td>
        </tr>

        <tr>
          <td>Name is too short</td>
          <td><code>nickname-too-short</code></td>
        </tr>

        <tr>
          <td>Name is too long</td>
          <td><code>nickname-too-long</code></td>
        </tr>

        <tr>
          <td>An error occurred while retrieving your information. Please try again.</td>
          <td><code>error-while-retrieving-authenticator</code></td>
        </tr>

        <tr>
          <td>An error occurred while trying to save the name . Please try again.</td>
          <td><code>error-while-patching</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-webauthn-enrollment-success

    <Frame>
      <img alt="mfa-webauthn-enrollment-success reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Security key successful \$\{clientName}</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Device registration successful \$\{clientName}</td>
          <td><code>titlePlatform</code></td>
        </tr>

        <tr>
          <td>You have successfully registered your Security Key.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>You have successfully registered your device.</td>
          <td><code>descriptionPlatform</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-webauthn-error

    <Frame>![mfa-webauthn-error reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-webauthn-error.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Try again</td>
          <td><code>tryAgainLinkText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Security key registration error</td>
          <td>\$\{clientName}</td>
        </tr>

        <tr>
          <td>Security Key Verification Failed</td>
          <td><code>errorTitleChallenge</code></td>
        </tr>

        <tr>
          <td>Device registration error</td>
          <td>\$\{clientName}</td>
        </tr>

        <tr>
          <td>Something Went Wrong</td>
          <td><code>errorTitlePlatformChallenge</code></td>
        </tr>

        <tr>
          <td>Something went wrong. Please try again or try using another method.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>If you already registered this device, please try again. If not, try using another method.</td>
          <td><code>descriptionPlatform</code></td>
        </tr>

        <tr>
          <td>No Thanks</td>
          <td><code>refuseAddingAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Use password</td>
          <td><code>usePasswordText</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-webauthn-not-available-error

    <Frame>![mfa-webauthn-not-available-error reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-webauthn-not-available-error.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Security keys are not supported \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Security Keys Are Not Supported</td>
          <td><code>errorTitle</code></td>
        </tr>

        <tr>
          <td>We are sorry but your browser or device does not support Security Keys. Try using another browser or log in from another device.</td>
          <td><code>errorDescription</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Use password</td>
          <td><code>usePasswordText</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="organizations">
    ## Screen: organization-selection

    <Frame>![organization-selection reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/organization-selection.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your organization \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Enter your \$\{companyName} Organization Name to continue</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Enter your Organization Name</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Enter Organization</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>The organization you entered is invalid</td>
          <td><code>invalid-organization</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: organization-picker

    <Frame>![organization-picker reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/organization-picker-rev2.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Choose an Organization</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>is a part of multiple organizations.</td>
          <td><code>loggedInText</code></td>
        </tr>

        <tr>
          <td>is used as a personal account and is a part of multiple organizations.</td>
          <td><code>loggedInTextB2C</code></td>
        </tr>

        <tr>
          <td>Choose an Organization</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Choose an Account to Continue</td>
          <td><code>titleB2C</code></td>
        </tr>

        <tr>
          <td>\<%= "\$" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>OR</td>
          <td><code>separatorText</code></td>
        </tr>

        <tr>
          <td>Continue with personal account</td>
          <td><code>continueTextB2C</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="reset-password">
    ## Screen: reset-password-request

    <Frame>![reset-password-request reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-request.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Reset your password</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Forgot Your Password?</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Back to \<%= "\$" %></td>
          <td><code>backToLoginLinkText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Enter your email address and we will send you instructions to reset your password.</td>
          <td><code>descriptionEmail</code></td>
        </tr>

        <tr>
          <td>Enter your username and we will send you instructions to reset your password.</td>
          <td><code>descriptionUsername</code></td>
        </tr>

        <tr>
          <td>Email address</td>
          <td><code>placeholderEmail</code></td>
        </tr>

        <tr>
          <td>Username</td>
          <td><code>placeholderUsername</code></td>
        </tr>

        <tr>
          <td>Email address</td>
          <td><code>emailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Username</td>
          <td><code>usernamePlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone number</td>
          <td><code>phonePlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone or Username or Email</td>
          <td><code>phoneOrUsernameOrEmailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone number or Email address</td>
          <td><code>phoneOrEmailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone Number or Username</td>
          <td><code>phoneOrUsernamePlaceholder</code></td>
        </tr>

        <tr>
          <td>Username or Email address</td>
          <td><code>usernameOrEmailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Enter your Email address and we will send you instructions to reset your password.</td>
          <td><code>emailDescription</code></td>
        </tr>

        <tr>
          <td>Enter your Username and we will send you instructions to reset your password.</td>
          <td><code>usernameDescription</code></td>
        </tr>

        <tr>
          <td>Enter your Phone number and we will send you instructions to reset your password.</td>
          <td><code>phoneDescription</code></td>
        </tr>

        <tr>
          <td>Enter your Phone number or Username or Email address and we will send you instructions to reset your password.</td>
          <td><code>phoneOrUsernameOrEmailDescription</code></td>
        </tr>

        <tr>
          <td>Enter your Phone number or Email address and we will send you instructions to reset your password.</td>
          <td><code>phoneOrEmailDescription</code></td>
        </tr>

        <tr>
          <td>Enter your Phone number or Username and we will send you instructions to reset your password.</td>
          <td><code>phoneOrUsernameDescription</code></td>
        </tr>

        <tr>
          <td>Enter your Username or Email address and we will send you instructions to reset your password.</td>
          <td><code>usernameOrEmailDescription</code></td>
        </tr>

        <tr>
          <td>\<%= "\$" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>This ticket was expired.</td>
          <td><code>auth0-users-expired-ticket</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>custom-script-error-code</code></td>
        </tr>

        <tr>
          <td>This ticket was already used.</td>
          <td><code>auth0-users-used-ticket</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later</td>
          <td><code>auth0-users-validation</code></td>
        </tr>

        <tr>
          <td>We had a problem sending the email, please try again later.</td>
          <td><code>reset-password-error</code></td>
        </tr>

        <tr>
          <td>You have exceeded the amount of emails. Wait a few minutes and try again.</td>
          <td><code>too-many-email</code></td>
        </tr>

        <tr>
          <td>You have exceeded the amount of emails. Wait a few minutes and try again.</td>
          <td><code>too-many-requests</code></td>
        </tr>

        <tr>
          <td>Please enter an email address</td>
          <td><code>no-email</code></td>
        </tr>

        <tr>
          <td>Username is required</td>
          <td><code>no-username</code></td>
        </tr>

        <tr>
          <td>Please enter a phone number</td>
          <td><code>no-phone\_number</code></td>
        </tr>

        <tr>
          <td>Phone number is not valid.</td>
          <td><code>invalid-phone-format</code></td>
        </tr>

        <tr>
          <td>Invalid Login ID entered</td>
          <td><code>invalid-login-id</code></td>
        </tr>

        <tr>
          <td>Enter a valid email address or phone number. Phone numbers must include the country code.</td>
          <td><code>invalid-email-phone</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password-email

    <Frame>![reset-password-email reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-email.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Check your email</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Check Your Email</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backButtonText</code></td>
        </tr>

        <tr>
          <td>Please check the email address \<%= "\$" %> for instructions to reset your password.</td>
          <td><code>emailDescription</code></td>
        </tr>

        <tr>
          <td>Resend email</td>
          <td><code>resendLinkText</code></td>
        </tr>

        <tr>
          <td>Please check the email address associated with the username \<%= "\$" %> for instructions to reset your password.</td>
          <td><code>usernameDescription</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password

    <Frame>![reset-password reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Reset your password</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Change Your Password</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Enter a new password below to change your password.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Reset password</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>New password</td>
          <td><code>passwordPlaceholder</code></td>
        </tr>

        <tr>
          <td>Re-enter new password</td>
          <td><code>reEnterpasswordPlaceholder</code></td>
        </tr>

        <tr>
          <td>Your password must contain:</td>
          <td><code>passwordSecurityText</code></td>
        </tr>

        <tr>
          <td>\<%= "\$" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Show password</td>
          <td><code>showPasswordText</code></td>
        </tr>

        <tr>
          <td>Hide password</td>
          <td><code>hidePasswordText</code></td>
        </tr>

        <tr>
          <td>Fail</td>
          <td><code>accessibilityError</code></td>
        </tr>

        <tr>
          <td>Pass</td>
          <td><code>accessibilityValid</code></td>
        </tr>

        <tr>
          <td>This ticket was expired.</td>
          <td><code>auth0-users-expired-ticket</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>custom-script-error-code</code></td>
        </tr>

        <tr>
          <td>This ticket was already used.</td>
          <td><code>auth0-users-used-ticket</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later</td>
          <td><code>auth0-users-validation</code></td>
        </tr>

        <tr>
          <td>Enter a new password.</td>
          <td><code>no-password-reset</code></td>
        </tr>

        <tr>
          <td>New password confirmation is missing</td>
          <td><code>no-re-enter-password</code></td>
        </tr>

        <tr>
          <td>Password contains user information</td>
          <td><code>password-contains-user-information</code></td>
        </tr>

        <tr>
          <td>This combination of credentials was detected in a public data breach on another website. To continue, please use a different password to keep your account secure.</td>
          <td><code>password-breached-reset</code></td>
        </tr>

        <tr>
          <td>Passwords don't match</td>
          <td><code>password-mismatch</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password-success

    <Frame>![reset-password-success reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-success.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Password reset successful</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Password Changed!</td>
          <td><code>eventTitle</code></td>
        </tr>

        <tr>
          <td>Your password has been changed successfully.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Back to \<%= "\$" %></td>
          <td><code>buttonText</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password-error

    <Frame>![reset-password-error reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-error.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Password reset error</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Back to \<%= "\$" %></td>
          <td><code>backToLoginLinkText</code></td>
        </tr>

        <tr>
          <td>To reset your password, return to the login page and select "Forgot Your Password" to send a new email.</td>
          <td><code>descriptionExpired</code></td>
        </tr>

        <tr>
          <td>Something went wrong. Please return to the login page and select "Forgot Your Password" to try again.</td>
          <td><code>descriptionGeneric</code></td>
        </tr>

        <tr>
          <td>This link has already been used. To reset your password, return to the login page and select "Forgot Your Password" to send a new email.</td>
          <td><code>descriptionUsed</code></td>
        </tr>

        <tr>
          <td>Link Expired</td>
          <td><code>eventTitleExpired</code></td>
        </tr>

        <tr>
          <td>Please Try Again</td>
          <td><code>eventTitleGeneric</code></td>
        </tr>

        <tr>
          <td>Invalid Link</td>
          <td><code>eventTitleUsed</code></td>
        </tr>

        <tr>
          <td>This ticket was expired.</td>
          <td><code>auth0-users-expired-ticket</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>custom-script-error-code</code></td>
        </tr>

        <tr>
          <td>This ticket was already used.</td>
          <td><code>auth0-users-used-ticket</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later</td>
          <td><code>auth0-users-validation</code></td>
        </tr>

        <tr>
          <td>We had a problem sending the email, please try again later.</td>
          <td><code>reset-password-error</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password-mfa-email-challenge

    <Frame>![reset-password-mfa-email-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-mfa-email-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your one-time password to change your password for</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Go Back</td>
          <td><code>backText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>We've sent an email with your code to</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter the code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>Resend</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive an email?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>\<%= "\$" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>OTP Code must have 6 numeric characters</td>
          <td><code>invalid-otp-code-format</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>Notification was not sent. Try resending the code.</td>
          <td><code>no-transaction-in-progress</code></td>
        </tr>

        <tr>
          <td>You have exceeded the amount of emails. Wait a few minutes and try again.</td>
          <td><code>too-many-email</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>We couldn't send the email. Please try again later.</td>
          <td><code>mfa-email-challenge-authenticator-error</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password-mfa-otp-challenge

    <Frame>![reset-password-mfa-otp-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-mfa-otp-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your one-time password to change your password for</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Check your preferred one-time password application for a code.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter your one-time code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>\<%= "\$" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Use password</td>
          <td><code>usePasswordText</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>Too many failed codes. Wait for some minutes before retrying.</td>
          <td><code>too-many-failures</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password-mfa-phone-challenge

    <Frame>![reset-password-mfa-phone-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-mfa-phone-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your one-time password to change your password for</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>We will send a 6-digit code to the following phone number:</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>continueButtonText</code></td>
        </tr>

        <tr>
          <td>Choose another phone number.</td>
          <td><code>changePhoneText</code></td>
        </tr>

        <tr>
          <td>Text message</td>
          <td><code>smsButtonText</code></td>
        </tr>

        <tr>
          <td>Voice call</td>
          <td><code>voiceButtonText</code></td>
        </tr>

        <tr>
          <td>How do you want to receive the code?</td>
          <td><code>chooseMessageTypeText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter your phone number</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>\<%= "\$" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>There was a problem sending the SMS</td>
          <td><code>send-sms-failed</code></td>
        </tr>

        <tr>
          <td>There was a problem making the voice call</td>
          <td><code>send-voice-failed</code></td>
        </tr>

        <tr>
          <td>Phone number can only include digits.</td>
          <td><code>invalid-phone-format</code></td>
        </tr>

        <tr>
          <td>It seems that your phone number is not valid. Please check and retry.</td>
          <td><code>invalid-phone</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-sms</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-voice</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>Please enter a phone number</td>
          <td><code>no-phone</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password-mfa-push-challenge-push

    <Frame>![reset-password-mfa-push-challenge-push reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-mfa-push-challenge-push.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your one-time password to change your password for</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>We’ve sent a notification to the following device via the \<%= "\$" %> app:</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>I've responded on my device</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>Resend</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive a notification?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>Manually Enter Code</td>
          <td><code>enterOtpCode</code></td>
        </tr>

        <tr>
          <td>OR</td>
          <td><code>separatorText</code></td>
        </tr>

        <tr>
          <td>\<%= "\$" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>You must accept the notification via the \<%= "\$" %> app on your mobile device.</td>
          <td><code>challenge-transaction-pending</code></td>
        </tr>

        <tr>
          <td>We have not received a confirmation, please slow down.</td>
          <td><code>polling-interval-exceeded</code></td>
        </tr>

        <tr>
          <td>We have received too many notification requests. Wait a few minutes and try again.</td>
          <td><code>too-many-push</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>We have not received a confirmation, please try scanning the code again.</td>
          <td><code>mfa-push-verify-transaction-pending</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the enrollment. Please try again later.</td>
          <td><code>mfa-push-verify-authenticator-error</code></td>
        </tr>

        <tr>
          <td>We couldn't send the notification. Please try again later.</td>
          <td><code>mfa-push-challenge-authenticator-error</code></td>
        </tr>

        <tr>
          <td>Notification rejected</td>
          <td><code>transaction-rejected</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password-mfa-recovery-code-challenge

    <Frame>![reset-password-mfa-recovery-code-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-mfa-recovery-code-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your one-time password to change your password for</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Enter the recovery code you were provided during your initial enrollment.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter your recovery code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>\<%= "\$" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>Recovery code must have 24 alphanumeric characters</td>
          <td><code>invalid-code-format</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>Please confirm you have recorded the code</td>
          <td><code>no-confirmation</code></td>
        </tr>

        <tr>
          <td>Too many failed codes. Wait for some minutes before retrying.</td>
          <td><code>too-many-failures</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password-mfa-sms-challenge

    <Frame>![reset-password-mfa-sms-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-mfa-sms-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your one-time password to change your password for</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>We've sent a text message to:</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Edit</td>
          <td><code>editText</code></td>
        </tr>

        <tr>
          <td>Edit phone number</td>
          <td><code>editLinkScreenReadableText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter the 6-digit code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>Resend</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive a code?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>or</td>
          <td><code>resendVoiceActionSeparatorTextBefore</code></td>
        </tr>

        <tr>
          <td>get a call</td>
          <td><code>resendVoiceActionText</code></td>
        </tr>

        <tr>
          <td>\<%= "\$" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>OTP Code must have 6 numeric characters</td>
          <td><code>invalid-otp-code-format</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>There was a problem sending the SMS</td>
          <td><code>send-sms-failed</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>We couldn't send the SMS. Please try again later.</td>
          <td><code>sms-authenticator-error</code></td>
        </tr>

        <tr>
          <td>Notification was not sent. Try resending the code.</td>
          <td><code>no-transaction-in-progress</code></td>
        </tr>

        <tr>
          <td>Too many failed codes. Wait for some minutes before retrying.</td>
          <td><code>too-many-failures</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-sms</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password-mfa-voice-challenge

    <Frame>![reset-password-mfa-voice-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-mfa-voice-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your one-time password to change your password for</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>We've sent a 6-digit code via voice phone call to the following phone number:</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Edit</td>
          <td><code>editText</code></td>
        </tr>

        <tr>
          <td>Edit phone number</td>
          <td><code>editLinkScreenReadableText</code></td>
        </tr>

        <tr>
          <td>Choose another phone number.</td>
          <td><code>changePhoneText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter the 6-digit code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>Call again</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive a call?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>or</td>
          <td><code>resendSmsActionSeparatorTextBefore</code></td>
        </tr>

        <tr>
          <td>send a text</td>
          <td><code>resendSmsActionText</code></td>
        </tr>

        <tr>
          <td>\<%= "\$" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>OTP Code must have 6 numeric characters</td>
          <td><code>invalid-otp-code-format</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>There was a problem making the voice call</td>
          <td><code>send-voice-failed</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>We couldn't make the voice call. Please try again later.</td>
          <td><code>voice-authenticator-error</code></td>
        </tr>

        <tr>
          <td>Notification was not sent. Try resending the code.</td>
          <td><code>no-transaction-in-progress</code></td>
        </tr>

        <tr>
          <td>Too many failed codes. Wait for some minutes before retrying.</td>
          <td><code>too-many-failures</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-voice</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password-mfa-webauthn-platform-challenge

    <Frame>![reset-password-mfa-webauthn-platform-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-mfa-webauthn-platform-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Verify with fingerprint or face recognition</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Use fingerprint or face recognition to reset password</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Press the button below and follow your browser's steps to log in.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Awaiting device confirmation</td>
          <td><code>awaitingConfirmation</code></td>
        </tr>

        <tr>
          <td>Too many failed authentication attempts. Please try again later.</td>
          <td><code>too-many-webauthn-challenge-attempts-error</code></td>
        </tr>

        <tr>
          <td>\<%= "\$" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>continueButtonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Use password</td>
          <td><code>usePasswordText</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>We could not start the device verification. Please try again later.</td>
          <td><code>webauthn-platform-challenge-error</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password-mfa-webauthn-roaming-challenge

    <Frame>![reset-password-mfa-webauthn-roaming-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-mfa-webauthn-roaming-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Use your security key to reset password</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Make sure your Security Key is nearby. Once you continue, you will be prompted to use it.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Awaiting Security Key</td>
          <td><code>awaitingConfirmation</code></td>
        </tr>

        <tr>
          <td>Too many failed authentication attempts. Please try again later.</td>
          <td><code>too-many-webauthn-challenge-attempts-error</code></td>
        </tr>

        <tr>
          <td>\<%= "\$" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Use security key</td>
          <td><code>continueButtonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>We could not start the security key verification. Please try again later.</td>
          <td><code>webauthn-challenge-error</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="passkey-enrollment">
    ## Screen: passkey-enrollment

    <Frame>![passkey-enrollment reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/passkey-enrollment.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Create a passkey for <code>\$\{clientName}</code> on this device.</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Log in <code>\$\{clientName}</code>.</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Log in to <code>$\{companyName}</code> to continue to <code>$\{clientName}</code>.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>No need to remember a password.</td>
          <td><code>passkeyBenefit1Title</code></td>
        </tr>

        <tr>
          <td>Webauthn platform icon</td>
          <td><code>passkeyBenefit1ImgAltText</code></td>
        </tr>

        <tr>
          <td>With passkeys, you can use things like your fingerprint or face to login.</td>
          <td><code>passkeyBenefit1Description</code></td>
        </tr>

        <tr>
          <td>Works on all of your devices.</td>
          <td><code>passkeyBenefit2Title</code></td>
        </tr>

        <tr>
          <td>Device globe</td>
          <td><code>passkeyBenefit2ImgAltText</code></td>
        </tr>

        <tr>
          <td>Passkeys will automatically be available across your synced devices.</td>
          <td><code>passkeyBenefit2Description</code></td>
        </tr>

        <tr>
          <td>Keep your account safer.</td>
          <td><code>passkeyBenefit3Title</code></td>
        </tr>

        <tr>
          <td>Shield with check mark.</td>
          <td><code>passkeyBenefit3ImgAltText</code></td>
        </tr>

        <tr>
          <td>Passkeys offer state-of-the-art phishing resistance.</td>
          <td><code>passkeyBenefit3Description</code></td>
        </tr>

        <tr>
          <td>Create a passkey.</td>
          <td><code>createButtonText</code></td>
        </tr>

        <tr>
          <td>Continue without passkeys.</td>
          <td><code>continueButtonText</code></td>
        </tr>

        <tr>
          <td>Create a new passkey.</td>
          <td><code>createButtonResetText</code></td>
        </tr>

        <tr>
          <td>Create a new password.</td>
          <td><code>usePasswordButtonText</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backButtonText</code></td>
        </tr>

        <tr>
          <td>Don't show me this again.</td>
          <td><code>checkboxText</code></td>
        </tr>

        <tr>
          <td>The user already exists.</td>
          <td><code>error\_email-in-use</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>error\_auth0-users-validation</code></td>
        </tr>

        <tr>
          <td>Password and passkey are not allowed.</td>
          <td><code>error\_conflict-password-passkey</code></td>
        </tr>

        <tr>
          <td>Password is not allowed.</td>
          <td><code>error\_password-not-allowed</code></td>
        </tr>

        <tr>
          <td>Passkey is not allowed.</td>
          <td><code>error\_passkey-not-allowed</code></td>
        </tr>

        <tr>
          <td>Something went wrong. Please try again later.</td>
          <td><code>error\_invalid-passkey</code></td>
        </tr>

        <tr>
          <td>Something went wrong. Please try again later.</td>
          <td><code>error\_passkey-enrollment-failure</code></td>
        </tr>

        <tr>
          <td>You have created the maximum number of passkeys for your account.</td>
          <td><code>error\_passkey-enrollment-max-allowed-reached</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="passkey-enrollment-local">
    ## Screen: passkey-enrollment-local

    <Frame>![passkey-enrollment-local reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/passkey-enrollment-local.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Create a passkey for <code>\$\{clientName}</code> on this device.</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Log in <code>\$\{clientName}</code>.</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Log in to <code>$\{companyName}</code> to continue to <code>$\{clientName}</code>.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Sign in quickly with this device.</td>
          <td><code>passkeyBenefit1Title</code></td>
        </tr>

        <tr>
          <td>Lock</td>
          <td><code>passkeyBenefit1ImgAltText</code></td>
        </tr>

        <tr>
          <td>You won't need to use another device's passkey next time you sign in.</td>
          <td><code>passkeyBenefit1Description</code></td>
        </tr>

        <tr>
          <td>No need to remember a password.</td>
          <td><code>passkeyBenefit2Title</code></td>
        </tr>

        <tr>
          <td>Webauthn platform icon.</td>
          <td><code>passkeyBenefit2ImgAltText</code></td>
        </tr>

        <tr>
          <td>With passkeys, you can use things like your fingerprint or face to login.</td>
          <td><code>passkeyBenefit2Description</code></td>
        </tr>

        <tr>
          <td>Create a new passkey.</td>
          <td><code>createButtonText</code></td>
        </tr>

        <tr>
          <td>Continue without a new passkey.</td>
          <td><code>continueButtonText</code></td>
        </tr>

        <tr>
          <td>Don't show me this again.</td>
          <td><code>checkboxText</code></td>
        </tr>

        <tr>
          <td>Something went wrong. Please try again later.</td>
          <td><code>error\_passkey-enrollment-failure</code></td>
        </tr>

        <tr>
          <td>You have created the maximum number of passkeys for your account.</td>
          <td><code>error\_passkey-enrollment-max-allowed-reached</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="phone-identifier-challenge">
    ## Screen: phone-identifier-challenge

    <Frame>
      <img alt="phone-identifier-challenge reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your phone code to log in</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>We've sent a text message to:</td>
          <td><code>smsDescription</code></td>
        </tr>

        <tr>
          <td>We've sent a 6-digit code via voice phone call to the following phone number:</td>
          <td><code>voiceDescription</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backButtonText</code></td>
        </tr>

        <tr>
          <td>Enter the 6-digit code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Resend</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive a code?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>or</td>
          <td><code>resendVoiceActionSeparatorTextBefore</code></td>
        </tr>

        <tr>
          <td>or</td>
          <td><code>resendSmsActionSeparatorTextBefore</code></td>
        </tr>

        <tr>
          <td>send a text</td>
          <td><code>resendSmsActionText</code></td>
        </tr>

        <tr>
          <td>get a call</td>
          <td><code>resendVoiceActionText</code></td>
        </tr>

        <tr>
          <td>\<%= "\$" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Code has been resent.</td>
          <td><code>resendLimitReachedText</code></td>
        </tr>

        <tr>
          <td>OTP Code must have 6 numeric characters</td>
          <td><code>invalid-otp-code-format</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>There was a problem making the voice call</td>
          <td><code>send-voice-failed</code></td>
        </tr>

        <tr>
          <td>There was a problem sending the SMS</td>
          <td><code>send-sms-failed</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>We couldn't make the voice call. Please try again later.</td>
          <td><code>voice-authenticator-error</code></td>
        </tr>

        <tr>
          <td>We couldn't send the SMS. Please try again later.</td>
          <td><code>sms-authenticator-error</code></td>
        </tr>

        <tr>
          <td>Notification was not sent. Try resending the code.</td>
          <td><code>no-transaction-in-progress</code></td>
        </tr>

        <tr>
          <td>Too many failed codes. Wait for some minutes before retrying.</td>
          <td><code>too-many-failures</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-voice</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-sms</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="phone-identifier-enrollment">
    ## Screen: phone-identifier-enrollment

    <Frame>
      <img alt="phone-identifier-enrollment reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Use your phone number to log in</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>We will send a 6-digit code to the following phone number:</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>continueButtonText</code></td>
        </tr>

        <tr>
          <td>Choose another phone number.</td>
          <td><code>changePhoneText</code></td>
        </tr>

        <tr>
          <td>Text message</td>
          <td><code>smsButtonText</code></td>
        </tr>

        <tr>
          <td>Voice call</td>
          <td><code>voiceButtonText</code></td>
        </tr>

        <tr>
          <td>How do you want to receive the code?</td>
          <td><code>chooseMessageTypeText</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backButtonText</code></td>
        </tr>

        <tr>
          <td>Enter your phone number</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>\<%= "\$" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>There was a problem sending the SMS</td>
          <td><code>send-sms-failed</code></td>
        </tr>

        <tr>
          <td>There was a problem making the voice call</td>
          <td><code>send-voice-failed</code></td>
        </tr>

        <tr>
          <td>Phone number can only include digits.</td>
          <td><code>invalid-phone-format</code></td>
        </tr>

        <tr>
          <td>It seems that your phone number is not valid. Please check and retry.</td>
          <td><code>invalid-phone</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-sms</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-voice</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>Please enter a phone number</td>
          <td><code>no-phone</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="signup">
    ## Screen: signup

    <Frame>![signup reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/signup.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Sign up</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Welcome</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Sign Up to \<%= "${companyName}" %&gt; to continue to &lt;%= "$" %>.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Or</td>
          <td><code>separatorText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Email address</td>
          <td><code>emailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Continue with \<%= "" %></td>
          <td><code>federatedConnectionButtonText</code></td>
        </tr>

        <tr>
          <td>Log in</td>
          <td><code>loginActionLinkText</code></td>
        </tr>

        <tr>
          <td>Already have an account?</td>
          <td><code>loginActionText</code></td>
        </tr>

        <tr>
          <td>Password</td>
          <td><code>passwordPlaceholder</code></td>
        </tr>

        <tr>
          <td>Your password must contain:</td>
          <td><code>passwordSecurityText</code></td>
        </tr>

        <tr>
          <td>Username</td>
          <td><code>usernamePlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone number</td>
          <td><code>phonePlaceholder</code></td>
        </tr>

        <tr>
          <td>Email address (Optional)</td>
          <td><code>emailOptionalPlaceholder</code></td>
        </tr>

        <tr>
          <td>Username (Optional)</td>
          <td><code>usernameOptionalPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone number (Optional)</td>
          <td><code>phoneOptionalPlaceholder</code></td>
        </tr>

        <tr>
          <td>\<%= "\$" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Show password</td>
          <td><code>showPasswordText</code></td>
        </tr>

        <tr>
          <td>Hide password</td>
          <td><code>hidePasswordText</code></td>
        </tr>

        <tr>
          <td>Fail</td>
          <td><code>accessibilityError</code></td>
        </tr>

        <tr>
          <td>Pass</td>
          <td><code>accessibilityValid</code></td>
        </tr>

        <tr>
          <td>The user already exists.</td>
          <td><code>email-in-use</code></td>
        </tr>

        <tr>
          <td>The password is too weak</td>
          <td><code>password-too-weak</code></td>
        </tr>

        <tr>
          <td>The password is too weak</td>
          <td><code>password-policy-not-conformant</code></td>
        </tr>

        <tr>
          <td>The password is too common</td>
          <td><code>password-too-common</code></td>
        </tr>

        <tr>
          <td>Password has previously been used</td>
          <td><code>password-previously-used</code></td>
        </tr>

        <tr>
          <td>Passwords don't match</td>
          <td><code>password-mismatch</code></td>
        </tr>

        <tr>
          <td>Password contains user information</td>
          <td><code>password-contains-user-information</code></td>
        </tr>

        <tr>
          <td>Username can only contain alphanumeric characters or: '\<%= "${characters}" %&gt;'. Username should have between &lt;%= "$" %> and \<%= "\$" %> characters.</td>
          <td><code>invalid-username</code></td>
        </tr>

        <tr>
          <td>The username must not be longer than \<%= "\$" %> characters.</td>
          <td><code>invalid-username-max-length</code></td>
        </tr>

        <tr>
          <td>The username must have at least \<%= "\$" %> characters.</td>
          <td><code>invalid-username-min-length</code></td>
        </tr>

        <tr>
          <td>The username has invalid characters.</td>
          <td><code>invalid-username-invalid-characters</code></td>
        </tr>

        <tr>
          <td>The username cannot be an email.</td>
          <td><code>invalid-username-email-not-allowed</code></td>
        </tr>

        <tr>
          <td>The username provided is in use already.</td>
          <td><code>username-taken</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>custom-script-error-code</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later</td>
          <td><code>auth0-users-validation</code></td>
        </tr>

        <tr>
          <td>Invalid connection</td>
          <td><code>invalid-connection</code></td>
        </tr>

        <tr>
          <td>We have detected suspicious login behavior and further attempts will be blocked. Please contact the administrator.</td>
          <td><code>ip-blocked</code></td>
        </tr>

        <tr>
          <td>Too many signups from the same IP</td>
          <td><code>ip-signup-blocked</code></td>
        </tr>

        <tr>
          <td>Invalid connection</td>
          <td><code>no-db-connection</code></td>
        </tr>

        <tr>
          <td>Please enter an email address</td>
          <td><code>no-email</code></td>
        </tr>

        <tr>
          <td>Password is required</td>
          <td><code>no-password</code></td>
        </tr>

        <tr>
          <td>Enter a new password.</td>
          <td><code>no-password-reset</code></td>
        </tr>

        <tr>
          <td>New password confirmation is missing</td>
          <td><code>no-re-enter-password</code></td>
        </tr>

        <tr>
          <td>Username is required</td>
          <td><code>no-username</code></td>
        </tr>

        <tr>
          <td>At least one identifier is required</td>
          <td><code>no-identifier</code></td>
        </tr>

        <tr>
          <td>This combination of credentials was detected in a public data breach on another website. Before your account is created, please use a different password to keep it secure.</td>
          <td><code>password-breached</code></td>
        </tr>

        <tr>
          <td>We encountered an issue when attempting to sign up with a phone number. Please contact support for assistance.</td>
          <td><code>invalid-phone-attribute-config</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="signup-id">
    ## Screen: signup-id

    <Frame>![signup-id reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/signup-id.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Sign up</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Create Your Account</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Sign Up to \<%= "${companyName}" %&gt; to continue to &lt;%= "$" %>.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Or</td>
          <td><code>separatorText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Phone number</td>
          <td><code>phonePlaceholder</code></td>
        </tr>

        <tr>
          <td>Email address</td>
          <td><code>emailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Continue with \<%= "" %></td>
          <td><code>federatedConnectionButtonText</code></td>
        </tr>

        <tr>
          <td>Log in</td>
          <td><code>loginActionLinkText</code></td>
        </tr>

        <tr>
          <td>Already have an account?</td>
          <td><code>loginActionText</code></td>
        </tr>

        <tr>
          <td>Password</td>
          <td><code>passwordPlaceholder</code></td>
        </tr>

        <tr>
          <td>Your password must contain:</td>
          <td><code>passwordSecurityText</code></td>
        </tr>

        <tr>
          <td>Username</td>
          <td><code>usernamePlaceholder</code></td>
        </tr>

        <tr>
          <td>Email address (Optional)</td>
          <td><code>emailOptionalPlaceholder</code></td>
        </tr>

        <tr>
          <td>Username (Optional)</td>
          <td><code>usernameOptionalPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone number (Optional)</td>
          <td><code>phoneOptionalPlaceholder</code></td>
        </tr>

        <tr>
          <td>\<%= "\$" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>The user already exists.</td>
          <td><code>email-in-use</code></td>
        </tr>

        <tr>
          <td>The password is too weak</td>
          <td><code>password-too-weak</code></td>
        </tr>

        <tr>
          <td>The password is too weak</td>
          <td><code>password-policy-not-conformant</code></td>
        </tr>

        <tr>
          <td>The password is too common</td>
          <td><code>password-too-common</code></td>
        </tr>

        <tr>
          <td>Password has previously been used</td>
          <td><code>password-previously-used</code></td>
        </tr>

        <tr>
          <td>Passwords don't match</td>
          <td><code>password-mismatch</code></td>
        </tr>

        <tr>
          <td>Username can only contain alphanumeric characters or: '\<%= "${characters}" %&gt;'. Username should have between &lt;%= "$" %> and \<%= "\$" %> characters.</td>
          <td><code>invalid-username</code></td>
        </tr>

        <tr>
          <td>The username must not be longer than \<%= "\$" %> characters.</td>
          <td><code>invalid-username-max-length</code></td>
        </tr>

        <tr>
          <td>The username must have at least \<%= "\$" %> characters.</td>
          <td><code>invalid-username-min-length</code></td>
        </tr>

        <tr>
          <td>The username has invalid characters.</td>
          <td><code>invalid-username-invalid-characters</code></td>
        </tr>

        <tr>
          <td>The username cannot be an email.</td>
          <td><code>invalid-username-email-not-allowed</code></td>
        </tr>

        <tr>
          <td>The username provided is in use already.</td>
          <td><code>username-taken</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>custom-script-error-code</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later</td>
          <td><code>auth0-users-validation</code></td>
        </tr>

        <tr>
          <td>Invalid connection</td>
          <td><code>invalid-connection</code></td>
        </tr>

        <tr>
          <td>We have detected suspicious login behavior and further attempts will be blocked. Please contact the administrator.</td>
          <td><code>ip-blocked</code></td>
        </tr>

        <tr>
          <td>Too many signups from the same IP</td>
          <td><code>ip-signup-blocked</code></td>
        </tr>

        <tr>
          <td>Invalid connection</td>
          <td><code>no-db-connection</code></td>
        </tr>

        <tr>
          <td>Email does not match any enterprise directory</td>
          <td><code>no-hrd-connection</code></td>
        </tr>

        <tr>
          <td>Please enter an email address</td>
          <td><code>no-email</code></td>
        </tr>

        <tr>
          <td>Password is required</td>
          <td><code>no-password</code></td>
        </tr>

        <tr>
          <td>Enter a new password.</td>
          <td><code>no-password-reset</code></td>
        </tr>

        <tr>
          <td>New password confirmation is missing</td>
          <td><code>no-re-enter-password</code></td>
        </tr>

        <tr>
          <td>Username is required</td>
          <td><code>no-username</code></td>
        </tr>

        <tr>
          <td>At least one identifier is required</td>
          <td><code>no-identifier</code></td>
        </tr>

        <tr>
          <td>Enter a valid phone number</td>
          <td><code>invalid-phone-number</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="signup-password">
    ## Screen: signup-password

    <Frame>![signup-password reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/signup-password.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Create a password to sign up</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Create Your Account</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Set your password for \<%= "${companyName}" %&gt; to continue to &lt;%= "$" %></td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Or</td>
          <td><code>separatorText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Phone number</td>
          <td><code>phonePlaceholder</code></td>
        </tr>

        <tr>
          <td>Email address</td>
          <td><code>emailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Edit</td>
          <td><code>editEmailText</code></td>
        </tr>

        <tr>
          <td>Edit</td>
          <td><code>editPhoneText</code></td>
        </tr>

        <tr>
          <td>Edit</td>
          <td><code>editUsernameText</code></td>
        </tr>

        <tr>
          <td>Edit email address</td>
          <td><code>editLinkScreenReadableText</code></td>
        </tr>

        <tr>
          <td>Continue with \<%= "" %></td>
          <td><code>federatedConnectionButtonText</code></td>
        </tr>

        <tr>
          <td>Log in</td>
          <td><code>loginActionLinkText</code></td>
        </tr>

        <tr>
          <td>Already have an account?</td>
          <td><code>loginActionText</code></td>
        </tr>

        <tr>
          <td>Password</td>
          <td><code>passwordPlaceholder</code></td>
        </tr>

        <tr>
          <td>Your password must contain:</td>
          <td><code>passwordSecurityText</code></td>
        </tr>

        <tr>
          <td>Username</td>
          <td><code>usernamePlaceholder</code></td>
        </tr>

        <tr>
          <td>Email address (Optional)</td>
          <td><code>emailOptionalPlaceholder</code></td>
        </tr>

        <tr>
          <td>Username (Optional)</td>
          <td><code>usernameOptionalPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone number (Optional)</td>
          <td><code>phoneOptionalPlaceholder</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backButtonText</code></td>
        </tr>

        <tr>
          <td>Accept your invitation to sign up</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Sign Up to accept \<%= "${inviterName}" %&gt;'s invitation to join &lt;%= "$" %> on \<%= "\$" %>.</td>
          <td><code>invitationDescription</code></td>
        </tr>

        <tr>
          <td>\<%= "\$" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Show password</td>
          <td><code>showPasswordText</code></td>
        </tr>

        <tr>
          <td>Hide password</td>
          <td><code>hidePasswordText</code></td>
        </tr>

        <tr>
          <td>Fail</td>
          <td><code>accessibilityError</code></td>
        </tr>

        <tr>
          <td>Pass</td>
          <td><code>accessibilityValid</code></td>
        </tr>

        <tr>
          <td>The user already exists.</td>
          <td><code>email-in-use</code></td>
        </tr>

        <tr>
          <td>The password is too weak</td>
          <td><code>password-too-weak</code></td>
        </tr>

        <tr>
          <td>The password is too weak</td>
          <td><code>password-policy-not-conformant</code></td>
        </tr>

        <tr>
          <td>The password is too common</td>
          <td><code>password-too-common</code></td>
        </tr>

        <tr>
          <td>Password has previously been used</td>
          <td><code>password-previously-used</code></td>
        </tr>

        <tr>
          <td>Passwords don't match</td>
          <td><code>password-mismatch</code></td>
        </tr>

        <tr>
          <td>Password contains user information</td>
          <td><code>password-contains-user-information</code></td>
        </tr>

        <tr>
          <td>Username can only contain alphanumeric characters or: '\<%= "${characters}" %&gt;'. Username should have between &lt;%= "$" %> and \<%= "\$" %> characters.</td>
          <td><code>invalid-username</code></td>
        </tr>

        <tr>
          <td>The username must not be longer than \<%= "\$" %> characters.</td>
          <td><code>invalid-username-max-length</code></td>
        </tr>

        <tr>
          <td>The username must have at least \<%= "\$" %> characters.</td>
          <td><code>invalid-username-min-length</code></td>
        </tr>

        <tr>
          <td>The username has invalid characters.</td>
          <td><code>invalid-username-invalid-characters</code></td>
        </tr>

        <tr>
          <td>The username cannot be an email.</td>
          <td><code>invalid-username-email-not-allowed</code></td>
        </tr>

        <tr>
          <td>The username provided is in use already.</td>
          <td><code>username-taken</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>custom-script-error-code</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later</td>
          <td><code>auth0-users-validation</code></td>
        </tr>

        <tr>
          <td>Invalid connection</td>
          <td><code>invalid-connection</code></td>
        </tr>

        <tr>
          <td>We have detected suspicious login behavior and further attempts will be blocked. Please contact the administrator.</td>
          <td><code>ip-blocked</code></td>
        </tr>

        <tr>
          <td>Too many signups from the same IP</td>
          <td><code>ip-signup-blocked</code></td>
        </tr>

        <tr>
          <td>Invalid connection</td>
          <td><code>no-db-connection</code></td>
        </tr>

        <tr>
          <td>Please enter an email address</td>
          <td><code>no-email</code></td>
        </tr>

        <tr>
          <td>Password is required</td>
          <td><code>no-password</code></td>
        </tr>

        <tr>
          <td>Enter a new password.</td>
          <td><code>no-password-reset</code></td>
        </tr>

        <tr>
          <td>New password confirmation is missing</td>
          <td><code>no-re-enter-password</code></td>
        </tr>

        <tr>
          <td>Username is required</td>
          <td><code>no-username</code></td>
        </tr>

        <tr>
          <td>Enter a valid phone number</td>
          <td><code>invalid-phone-number</code></td>
        </tr>

        <tr>
          <td>This combination of credentials was detected in a public data breach on another website. Before your account is created, please use a different password to keep it secure.</td>
          <td><code>password-breached</code></td>
        </tr>

        <tr>
          <td>We encountered an issue when attempting to sign up with a phone number. Please contact support for assistance.</td>
          <td><code>invalid-phone-attribute-config</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="status">
    ## Screen: status

    <Frame>
      <img alt="status reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Something Went Wrong</td>
          <td><code>passwordless-no-session-title</code></td>
        </tr>

        <tr>
          <td>The link must be opened on the same device and browser from which you submitted your email address.</td>
          <td><code>passwordless-no-session</code></td>
        </tr>

        <tr>
          <td>Start over from this device or browser</td>
          <td><code>passwordless-no-session-link</code></td>
        </tr>

        <tr>
          <td>Something Went Wrong</td>
          <td><code>mfa-required-title</code></td>
        </tr>

        <tr>
          <td>Two-factor authentication is required to access this application. To enable this, please contact your system administrator.</td>
          <td><code>mfa-required</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>custom-script-error-code</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>auth0-users-validation</code></td>
        </tr>

        <tr>
          <td>We are sorry, something went wrong when attempting to log in</td>
          <td><code>authentication-failure</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>
</AccordionGroup>

### Custom query parameters

You can also use query parameters within the context by passing them to the `/authorize` endpoint when initiating the authentication request. These custom query parameters must have the `ext-` prefix.

The following example uses the `ext-ga` and `ext-test` query parameters to the login page template:

```html lines theme={null}
<!DOCTYPE html>
<html>
  <head>
    {%- auth0:head -%}
  </head>
  <body>
    {%- auth0:widget -%}
  </body>
  <pre style='background: wheat'>
    <b>Value of the ext-ga parameter:</b>{{ transaction.params.ext-ga }}
    <b>Value of the ext-test parameter:</b>{{ transaction.params.ext-test }}
  </pre>
</html>
```

Custom query parameters have the following limitations:

* Each `ext-` parameter name must be unique
* One authorize request can can contain a maximum of ten ext- parameters
* The `ext-` parameter name must start with ext-, contain only \[a-zA-z0-9\_-], and be a maximum of 28 characters, as in the following: `/^ext-[\w-]{1,28}$/`
* The `ext-` parameter value must contain only \[a-zA-Z0-9-.\*\~@+ /:\_], and be a maximum of 255 characters, as in the following: `/^[-\w.*~@+ /:]{1,255}$/`

### Custom signup prompts

If you use custom signup prompts, you must enable custom page templates. The following is the minimum template that allows custom signup prompts to render:

```html lines theme={null}
<!DOCTYPE html>
<html>
  <head>
    {%- auth0:head -%}
    <style>
      body._widget-auto-layout {
        --page-background-image: url('https://REPLACE/WITH/YOUR/BACKGROUND/IMAGE.png');
        background-color: var(--page-background-color);
        background-image: var(--page-background-image);
        background-position: center;
        background-size: cover;
        background-repeat: no-repeat;
      }
    </style>
    <title>{{ prompt.screen.texts.pageTitle }}</title>
  </head>
  <body class="_widget-auto-layout">
    {%- auth0:widget -%}
  </body>
</html>
```

To learn more, review [Customize Signup and Login Prompts](/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts).

## Examples

### Login box + image layout

The following template will show the login box to the left, and an image to the right only for the login/signup pages. The rest of the pages will look like the default ones.

```html lines expandable theme={null}
<!DOCTYPE html>
<html lang="{{locale}}">
  <head>
    {%- auth0:head -%}
    <style>
      body {
        background-image: url("https://images.unsplash.com/photo-1592450865877-e3a318ec3522?ixlib=rb-1.2.1&auto=format&fit=crop&w=2255&q=80");
        background-size: cover;
        background-position: center;
        background-repeat: no-repeat;
      }
      .prompt-wrapper {
        position: relative;
        display: flex;
        align-items: center;
        width: 480px;
        height: 100%;
        justify-content: center;
        background-color: rgb(60,60,60);
      }
    </style>
    <title>{{ prompt.screen.texts.pageTitle }}</title>

  </head>
  <body class="_widget-auto-layout">
    {% if prompt.name == "login" or prompt.name == "signup" %} 
        <div class="prompt-wrapper">
        {%- auth0:widget -%}
        </div>
    {% else %}
        {%- auth0:widget -%}
    {% endif %}
  </body>
</html>
```

<Frame>
  <img alt="Universal Login box with email username/password and image layout example" />
</Frame>

### Page footers

The example below adds a gray footer with links to Privacy Policy and Terms of Services:

```html lines expandable theme={null}
<!DOCTYPE html><html lang="{{locale}}">
  <head>
    {%- auth0:head -%}
    <style>
      body {
        background-image: radial-gradient(white, rgb(200, 200, 200));
      }
      .footer {
        background-color: rgb(120, 120, 120);
        position: absolute;
        bottom: 0;
        left: 0;
        padding: 16px 0; 
        width: 100%;
        color: white;
        /* Use a high z-index for future-proofing */
        z-index: 10;
      }
      .footer ul {
        text-align: center;
      }
      .footer ul li {
        display: inline-block;
        margin: 0 4px;
      }
      .footer ul li:not(:first-of-type) {
        margin-left: 0;
      }
      .footer ul li:not(:first-of-type)::before {
        content: '';
        display: inline-block;
        vertical-align: middle;
        width: 4px;
        height: 4px;
        margin-right: 4px;
        background-color: white;
        border-radius: 50%;
      }
      .footer a {
        color: white;
      }
    </style>
     <title>{{ prompt.screen.texts.pageTitle }}</title>
  </head>
  <body class="_widget-auto-layout">
    {%- auth0:widget -%}
    <footer class="footer">
      <ul>
        <li><a href="https://company.com/privacy">Privacy Policy</a></li>
        <li><a href="https://company.com/terms">Terms of Service</a></li>
      </ul>
    </footer>
  </body></html>
```

<Frame>
  <img alt="Universal Login box with email address/password and footers layout example" />
</Frame>

## Page templates API

To set the page template, you need to use the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. You first need to get a Management API token with the `update:branding`, `read:branding`, `delete:branding` scopes. If you are using the `API Explorer Application` to generate tokens, make sure those scopes are enabled for the `Auth0 Management API`.

To set the template, you need to use the following endpoint:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PUT \
    --url 'https://{yourDomain}/api/v2/branding/templates/universal-login' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'content-type: text/html' \
    --data '<!DOCTYPE html><html><head>{%- auth0:head -%}</head><body>{%- auth0:widget -%}</body></html>'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/branding/templates/universal-login");
  var request = new RestRequest(Method.PUT);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("content-type", "text/html");
  request.AddParameter("text/html", "
  {%- auth0:head -%}{%- auth0:widget -%}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/branding/templates/universal-login"

  	payload := strings.NewReader("<!DOCTYPE html><html><head>{%- auth0:head -%}</head><body>{%- auth0:widget -%}</body></html>")

  	req, _ := http.NewRequest("PUT", url, payload)

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
  	req.Header.Add("content-type", "text/html")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.put("https://{yourDomain}/api/v2/branding/templates/universal-login")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("content-type", "text/html")
    .body("<!DOCTYPE html><html><head>{%- auth0:head -%}</head><body>{%- auth0:widget -%}</body></html>")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PUT',
    url: 'https://{yourDomain}/api/v2/branding/templates/universal-login',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN', 'content-type': 'text/html'},
    data: '<!DOCTYPE html><html><head>{%- auth0:head -%}</head><body>{%- auth0:widget -%}</body></html>'
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"content-type": @"text/html" };

  NSData *postData = [[NSData alloc] initWithData:[@"<!DOCTYPE html><html><head>{%- auth0:head -%}</head><body>{%- auth0:widget -%}</body></html>" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/branding/templates/universal-login"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"PUT"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/branding/templates/universal-login",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_POSTFIELDS => "<!DOCTYPE html><html><head>{%- auth0:head -%}</head><body>{%- auth0:widget -%}</body></html>",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN",
      "content-type: text/html"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "<!DOCTYPE html><html><head>{%- auth0:head -%}</head><body>{%- auth0:widget -%}</body></html>"

  headers = {
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
      'content-type': "text/html"
      }

  conn.request("PUT", "/{yourDomain}/api/v2/branding/templates/universal-login", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/branding/templates/universal-login")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Put.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request["content-type"] = 'text/html'
  request.body = "<!DOCTYPE html><html><head>{%- auth0:head -%}</head><body>{%- auth0:widget -%}</body></html>"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "content-type": "text/html"
  ]

  let postData = NSData(data: "<!DOCTYPE html><html><head>{%- auth0:head -%}</head><body>{%- auth0:widget -%}</body></html>".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/branding/templates/universal-login")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "PUT"
  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()
  ```
</AuthCodeGroup>

To retrieve the template, you need to use the following endpoint:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/branding/templates/universal-login' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/branding/templates/universal-login");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/branding/templates/universal-login"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/branding/templates/universal-login")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/branding/templates/universal-login',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/branding/templates/universal-login"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/branding/templates/universal-login",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer MGMT_API_ACCESS_TOKEN" }

  conn.request("GET", "/{yourDomain}/api/v2/branding/templates/universal-login", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/branding/templates/universal-login")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer MGMT_API_ACCESS_TOKEN"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/branding/templates/universal-login")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

To delete the template, you need to use the following endpoint:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url 'https://{yourDomain}/api/v2/branding/templates/universal-login' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/branding/templates/universal-login");
  var request = new RestRequest(Method.DELETE);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/branding/templates/universal-login"

  	req, _ := http.NewRequest("DELETE", url, nil)

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.delete("https://{yourDomain}/api/v2/branding/templates/universal-login")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'DELETE',
    url: 'https://{yourDomain}/api/v2/branding/templates/universal-login',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/branding/templates/universal-login"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"DELETE"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/branding/templates/universal-login",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer MGMT_API_ACCESS_TOKEN" }

  conn.request("DELETE", "/{yourDomain}/api/v2/branding/templates/universal-login", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/branding/templates/universal-login")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Delete.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer MGMT_API_ACCESS_TOKEN"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/branding/templates/universal-login")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "DELETE"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

The maximum size for the Page Template is 100KB. If that is not big enough, consider moving images/css files outside of the Page Template code.

## CSS customization

<Warning>
  **Page template limitations:**

  * CSS class names change each time Auth0 builds the project. Custom CSS that targets these classes will break with each new build.
  * The HTML structure of Universal Login pages is subject to change. Avoid customizations that rely on the HTML structure to prevent any interruptions.
</Warning>

There are a few things that you can customize using CSS:

* You can resize the login prompt by enclosing the variables below in `<style>` tags in the `<head>` element.

  * Use `--prompt-width` to adjust the container width. Its default value is 400px.
  * For [Forms](/docs/customize/forms): Use `--form-max-width` to set the maximum form width. Its default value is 500px.

    * To apply your code to the Form page only, include `{% if prompt.name == "custom-form" %} in the <head> element`.
* You can use a Google font by importing it and overriding the `--font-family` CSS variable.
* You can hide the tenant logo by adding `class="_hide-prompt-logo"` in the `<body>` element.
* You can specify a custom logo by adding `class="_use-custom-prompt-logo"` in the `<body>` element. This would let you, for example, change the login page logo depending on the application:

```html lines expandable theme={null}
<!DOCTYPE html>
<html lang="{{locale}}">

  <head>
    <title>Welcome to {{ application.name }} </title>
    {%- auth0:head -%}
    <style>
      :root {
        --prompt-width: 800px;
      }
      {% if application.name == "Auth0 Community" %}
      #custom-prompt-logo {
      background-image: url('https://cdn.auth0.com/manhattan/versions/1.3312.0/assets/badge.png');
      }
      {% elsif application.name == "Auth0 Dashboard" %}
      #custom-prompt-logo {
      background-image: url('https://cdn.auth0.com/blog/auth0rta/theme/logos/auth0-logo-black.png');
      }
      {% endif %}
  </style>

  </head>

  <body class="_widget-auto-layout _use-custom-prompt-logo">
    {%- auth0:widget -%}
  </body>

</html>
```

The current implementation does not support further CSS customization. If you look at the HTML that is generated, you will see code like:

```text lines theme={null}
.c10d15918.c7b3b8672 {
  background: #D00E17;
}
```

## Using the Auth0 CLI

You can use the [Auth0 CLI](https://github.com/auth0/auth0-cli) to easily update Page Templates.

In the Auth0 CLI, run:

`auth0 universal-login customize`

The Auth0 CLI will open two windows:

* A browser window with a [Storybook](https://storybook.js.org/) that shows the login page with the page template applied:

<Frame>
  <img alt="Page Templates Storybook" />
</Frame>

* The default editor, with the page template code:

<Frame>
  <img alt="undefined" />
</Frame>

You can now change the page template code, and you will be able to preview the changes in your browser window.

Once you close the window, you’ll be asked if you want to save the template. If you answer **Yes**, the template will be uploaded to your tenant.

## Troubleshooting

If the template is not being applied, verify that you're navigating to `{customDomain}/authorize`. If you're navigating to `{yourDomain}/authorize`, Auth0 will not render the page template.


# Customize Universal Login Text Elements
Source: https://auth0.com/docs/customize/login-pages/universal-login/customize-text-elements

Learn how to customize Universal Login text elements using the Auth0 Dashboard or Management API

<Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> consists of a set of pages that facilitate several account-related actions, such as logging in, enrolling <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> factors, or resetting passwords. Auth0 provides the text on these pages in several languages.

In some cases, you may want to modify the text on these pages to better match your application's tone or specific needs.

You can customize the text displayed on [Universal Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience) pages in all supported languages through either the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. The following definitions, values, and variables apply to both methods.

## Configure prompts and screens

You can customize any of the available [prompts and screens](#prompt-values) through the Auth0 Dashboard or the [Management API](https://auth0.com/docs/api/management/v2).

<Tabs>
  <Tab title="Use the Dashboard">
    You can use the Dashboard to customize New Universal Login text prompts.

    1. In the Dashboard, go to [**Branding > Universal Login > Advanced Options**](https://manage.auth0.com/#/custom_text), and then select **Custom Text**.
    2. Select the **Prompt** and **Screen** that you want to edit, then make your desired changes. A live preview is available on the right.
    3. When you're ready for your changes to appear on your production environment, select **Save Changes.**
  </Tab>

  <Tab title="Use the Management API">
    You can use the Management API to customize New Universal Login text prompts.

    1. Get a [Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production) with the `read:prompts` and `update:prompts` scopes.
    2. Call the Management API [Get custom text for a prompt](https://auth0.com/docs/api/management/v2#!/Prompts/get_custom_text_by_language) endpoint to get the existing configuration data for the specified prompt and language.
    3. Modify the configuration data as desired, using the [supported parameters](#supported-parameters) and [prompt values](#prompt-values) for reference.
    4. Call the Management API [Set custom text for a specific prompt](https://auth0.com/docs/api/management/v2#!/Prompts/put_custom_text_by_language) endpoint with the updated configuration data.

       <Warning>
         The Management API [Set custom text for a specific prompt](https://auth0.com/docs/api/management/v2#!/Prompts/put_custom_text_by_language) endpoint replaces all existing configuration data for the specified prompt with the configuration data provided in the `body` parameter.

         If you want to configure multiple `screen` values for a specified prompt, you must include all of them in a single call to the Management API.
       </Warning>

    #### Example

    You could set the `description` text component for the `login` prompt's `login` screen to `Log in to ACME's website` by calling the Management API [Set custom text for a specific prompt](https://auth0.com/docs/api/management/v2#!/Prompts/put_custom_text_by_language) endpoint like so:

    <AuthCodeGroup>
      ```bash cURL theme={null}
      curl --request PUT \
        --url 'https://{yourDomain}/api/v2/prompts/login/custom-text/en' \
        --header 'authorization: Bearer {yourMgmtApiAccessToken}' \
        --header 'content-type: application/json' \
        --data '{ "login": { "description": "Login to ACME'''s Website" } }'
      ```

      ```csharp C# theme={null}
      var client = new RestClient("https://{yourDomain}/api/v2/prompts/login/custom-text/en");
      var request = new RestRequest(Method.PUT);
      request.AddHeader("content-type", "application/json");
      request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
      request.AddParameter("application/json", "{ "login": { "description": "Login to ACME's Website" } }", ParameterType.RequestBody);
      IRestResponse response = client.Execute(request);
      ```

      ```go Go theme={null}
      package main

      import (
      	"fmt"
      	"strings"
      	"net/http"
      	"io/ioutil"
      )

      func main() {

      	url := "https://{yourDomain}/api/v2/prompts/login/custom-text/en"

      	payload := strings.NewReader("{ "login": { "description": "Login to ACME's Website" } }")

      	req, _ := http.NewRequest("PUT", url, payload)

      	req.Header.Add("content-type", "application/json")
      	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

      	res, _ := http.DefaultClient.Do(req)

      	defer res.Body.Close()
      	body, _ := ioutil.ReadAll(res.Body)

      	fmt.Println(res)
      	fmt.Println(string(body))

      }
      ```

      ```java Java theme={null}
      HttpResponse<String> response = Unirest.put("https://{yourDomain}/api/v2/prompts/login/custom-text/en")
        .header("content-type", "application/json")
        .header("authorization", "Bearer {yourMgmtApiAccessToken}")
        .body("{ "login": { "description": "Login to ACME's Website" } }")
        .asString();
      ```

      ```javascript Node.JS theme={null}
      var axios = require("axios").default;

      var options = {
        method: 'PUT',
        url: 'https://{yourDomain}/api/v2/prompts/login/custom-text/en',
        headers: {
          'content-type': 'application/json',
          authorization: 'Bearer {yourMgmtApiAccessToken}'
        },
        data: {login: {description: 'Login to ACME's Website'}}
      };

      axios.request(options).then(function (response) {
        console.log(response.data);
      }).catch(function (error) {
        console.error(error);
      });
      ```

      ```php PHP theme={null}
      $curl = curl_init();

      curl_setopt_array($curl, [
        CURLOPT_URL => "https://{yourDomain}/api/v2/prompts/login/custom-text/en",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => "",
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => "PUT",
        CURLOPT_POSTFIELDS => "{ "login": { "description": "Login to ACME's Website" } }",
        CURLOPT_HTTPHEADER => [
          "authorization: Bearer {yourMgmtApiAccessToken}",
          "content-type: application/json"
        ],
      ]);

      $response = curl_exec($curl);
      $err = curl_error($curl);

      curl_close($curl);

      if ($err) {
        echo "cURL Error #:" . $err;
      } else {
        echo $response;
      }
      ```

      ```python Python theme={null}
      import http.client

      conn = http.client.HTTPSConnection("")

      payload = "{ "login": { "description": "Login to ACME's Website" } }"

      headers = {
          'content-type': "application/json",
          'authorization': "Bearer {yourMgmtApiAccessToken}"
          }

      conn.request("PUT", "/{yourDomain}/api/v2/prompts/login/custom-text/en", payload, headers)

      res = conn.getresponse()
      data = res.read()

      print(data.decode("utf-8"))
      ```

      ```ruby Ruby theme={null}
      require 'uri'
      require 'net/http'
      require 'openssl'

      url = URI("https://{yourDomain}/api/v2/prompts/login/custom-text/en")

      http = Net::HTTP.new(url.host, url.port)
      http.use_ssl = true
      http.verify_mode = OpenSSL::SSL::VERIFY_NONE

      request = Net::HTTP::Put.new(url)
      request["content-type"] = 'application/json'
      request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'
      request.body = "{ "login": { "description": "Login to ACME's Website" } }"

      response = http.request(request)
      puts response.read_body
      ```
    </AuthCodeGroup>

    #### Delete custom text for a prompt

    If you want to delete all custom text for a prompt, call the Management API [Set custom text for a specific prompt](https://auth0.com/docs/api/management/v2#!/Prompts/put_custom_text_by_language) endpoint with an empty object (`{}`) as the `body` parameter:

    <AuthCodeGroup>
      ```bash cURL theme={null}
      curl --request PUT \
        --url 'https://{yourDomain}/api/v2/prompts/login/custom-text/en' \
        --header 'authorization: Bearer {yourMgmtApiAccessToken}' \
        --header 'content-type: application/json' \
        --data '{}'
      ```

      ```csharp C# theme={null}
      var client = new RestClient("https://{yourDomain}/api/v2/prompts/login/custom-text/en");
      var request = new RestRequest(Method.PUT);
      request.AddHeader("content-type", "application/json");
      request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
      request.AddParameter("application/json", "{}", ParameterType.RequestBody);
      IRestResponse response = client.Execute(request);
      ```

      ```go Go theme={null}
      package main

      import (
      	"fmt"
      	"strings"
      	"net/http"
      	"io/ioutil"
      )

      func main() {

      	url := "https://{yourDomain}/api/v2/prompts/login/custom-text/en"

      	payload := strings.NewReader("{}")

      	req, _ := http.NewRequest("PUT", url, payload)

      	req.Header.Add("content-type", "application/json")
      	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

      	res, _ := http.DefaultClient.Do(req)

      	defer res.Body.Close()
      	body, _ := ioutil.ReadAll(res.Body)

      	fmt.Println(res)
      	fmt.Println(string(body))

      }
      ```

      ```java Java theme={null}
      HttpResponse<String> response = Unirest.put("https://{yourDomain}/api/v2/prompts/login/custom-text/en")
        .header("content-type", "application/json")
        .header("authorization", "Bearer {yourMgmtApiAccessToken}")
        .body("{}")
        .asString();
      ```

      ```javascript Node.JS theme={null}
      var axios = require("axios").default;

      var options = {
        method: 'PUT',
        url: 'https://{yourDomain}/api/v2/prompts/login/custom-text/en',
        headers: {
          'content-type': 'application/json',
          authorization: 'Bearer {yourMgmtApiAccessToken}'
        },
        data: {}
      };

      axios.request(options).then(function (response) {
        console.log(response.data);
      }).catch(function (error) {
        console.error(error);
      });
      ```

      ```php PHP theme={null}
      $curl = curl_init();

      curl_setopt_array($curl, [
        CURLOPT_URL => "https://{yourDomain}/api/v2/prompts/login/custom-text/en",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => "",
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => "PUT",
        CURLOPT_POSTFIELDS => "{}",
        CURLOPT_HTTPHEADER => [
          "authorization: Bearer {yourMgmtApiAccessToken}",
          "content-type: application/json"
        ],
      ]);

      $response = curl_exec($curl);
      $err = curl_error($curl);

      curl_close($curl);

      if ($err) {
        echo "cURL Error #:" . $err;
      } else {
        echo $response;
      }
      ```

      ```python Python theme={null}
      import http.client

      conn = http.client.HTTPSConnection("")

      payload = "{}"

      headers = {
          'content-type': "application/json",
          'authorization': "Bearer {yourMgmtApiAccessToken}"
          }

      conn.request("PUT", "/{yourDomain}/api/v2/prompts/login/custom-text/en", payload, headers)

      res = conn.getresponse()
      data = res.read()

      print(data.decode("utf-8"))
      ```

      ```ruby Ruby theme={null}
      require 'uri'
      require 'net/http'
      require 'openssl'

      url = URI("https://{yourDomain}/api/v2/prompts/login/custom-text/en")

      http = Net::HTTP.new(url.host, url.port)
      http.use_ssl = true
      http.verify_mode = OpenSSL::SSL::VERIFY_NONE

      request = Net::HTTP::Put.new(url)
      request["content-type"] = 'application/json'
      request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'
      request.body = "{}"

      response = http.request(request)
      puts response.read_body
      ```
    </AuthCodeGroup>
  </Tab>
</Tabs>

### Supported parameters

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Definition</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>prompt</code></td>
      <td>The step in the login flow. For a list of available values, read <a href="#prompt-values">Prompt values</a>.</td>
    </tr>

    <tr>
      <td><code>language</code></td>
      <td>The language that the customization applies to. For a list of available languages, read <a href="/docs/customize/internationalization-and-localization/universal-login-internationalization">Universal Login Internationalization</a>.</td>
    </tr>

    <tr>
      <td><code>screen</code></td>
      <td>The specific screen within a prompt.</td>
    </tr>

    <tr>
      <td><code>key</code></td>
      <td>The identifier of a text component.</td>
    </tr>

    <tr>
      <td><code>text</code></td>
      <td>The message displayed to the user.</td>
    </tr>
  </tbody>
</table>

### Prompt values

The term `prompt` refers to a specific step in the login flow. Each `prompt` has at least one `screen`, and each `screen` has a set of text components that you can customize.

The available `prompt` values are:

<AccordionGroup>
  <Accordion title="async-approval-flow">
    ## Screen: async-approval-error

    <Frame>
      <img alt="async-approval-error reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Request Review error</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>This request is no longer valid.</td>
          <td><code>expired-description</code></td>
        </tr>

        <tr>
          <td>Request Expired</td>
          <td><code>expired-title</code></td>
        </tr>

        <tr>
          <td>Wrong account</td>
          <td><code>wrong-user-title</code></td>
        </tr>

        <tr>
          <td>This request is for a different account. To continue, please log out and try again with the correct account.</td>
          <td><code>wrong-user-description</code></td>
        </tr>

        <tr>
          <td>Log out and try again</td>
          <td><code>wrong-user-link-text</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: async-approval-accepted

    <Frame>
      <img alt="async-approval-accepted reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Request approved</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>You may now close this window.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Request approved</td>
          <td><code>eventtitle</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: async-approval-denied

    <Frame>
      <img alt="async-approval-denied reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Request declined</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>You may now close this window.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Request declined</td>
          <td><code>eventtitle</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="brute-force-protection">
    ## Screen: brute-force-protection-unblock

    <Frame>
      <img alt="brute-force-protection-unblock reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Unblock My Account</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Unblock My Account</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: brute-force-protection-unblock-success

    <Frame>
      <img alt="brute-force-protection-unblock-success reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Unblock My Account</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Unblock My Account</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: brute-force-protection-unblock-failure

    <Frame>
      <img alt="brute-force-protection-unblock-failure reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Unblock My Account</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Unblock My Account</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="captcha">
    ## Screen: interstitial-captcha

    <Frame>
      <img alt="interstitial-captcha screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Complete the challenge to proceed | \$</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Please complete the challenge to proceed.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Enter the code shown above</td>
          <td><code>captchaCodePlaceholder</code></td>
        </tr>

        <tr>
          <td>We couldn’t load the security challenge. Please try again. (Error code: #)</td>
          <td><code>captcha-client-failure</code></td>
        </tr>

        <tr>
          <td>We are sorry, something went wrong while validating the captcha response. Please try again.</td>
          <td><code>captcha-validation-failure</code></td>
        </tr>

        <tr>
          <td>Select the checkbox to verify you are not a robot.</td>
          <td><code>invalid-recaptcha</code></td>
        </tr>

        <tr>
          <td>Solve the challenge question to verify you are not a robot.</td>
          <td><code>invalid-captcha</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="common">
    ## Screen: redeem-ticket

    <Frame>
      <img alt="redeem-ticket reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Loading...</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Javascript is not enabled on your browser, please click button to continue.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="consent">
    ## Screen: consent

    <Frame>![consent reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/consent.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Authorize \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Authorize App</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Hi \$\{userName},</td>
          <td><code>pickerTitle</code></td>
        </tr>

        <tr>
          <td>Tenant and Audience selector</td>
          <td><code>audiencePickerAltText</code></td>
        </tr>

        <tr>
          <td>\$\{clientName} is requesting access to your account.</td>
          <td><code>messageMultipleTenants</code></td>
        </tr>

        <tr>
          <td>$\{clientName} is requesting access to your \$\{companyName} account.</td>
          <td><code>messageSingleTenant</code></td>
        </tr>

        <tr>
          <td>Accept</td>
          <td><code>acceptButtonText</code></td>
        </tr>

        <tr>
          <td>Decline</td>
          <td><code>declineButtonText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Invalid action</td>
          <td><code>invalid-action</code></td>
        </tr>

        <tr>
          <td>Audience is required</td>
          <td><code>invalid-audience</code></td>
        </tr>

        <tr>
          <td>Invalid scope, must be an array</td>
          <td><code>invalid-scope</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="custom-form">
    ## Screen: custom-form

    <Frame>
      <img alt="custom form screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Form \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="device-flow">
    ## Screen: device-code-activation

    <Frame>![device-code-activation reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/device-code-activation.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your device code to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Enter the code displayed on your device</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Enter your one-time code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Device Activation</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Invalid or expired user code</td>
          <td><code>invalid-expired-code</code></td>
        </tr>

        <tr>
          <td>Please enter the code displayed on your device</td>
          <td><code>no-code</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: device-code-activation-allowed

    <Frame>![device-code-activation-allowed reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/device-code-activation-allowed.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Login successful \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Your device is now connected.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Congratulations, you're all set!</td>
          <td><code>eventTitle</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: device-code-activation-denied

    <Frame>![device-code-activation-denied reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/device-code-activation-denied.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Login error \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>We are not able to activate your device.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Activation Denied</td>
          <td><code>eventTitle</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: device-code-confirmation

    <Frame>![device-code-confirmation reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/device-code-confirmation.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Confirm your device code to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Please confirm this is the code displayed on your \$\{clientName}:</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Secure code</td>
          <td><code>inputCodeLabel</code></td>
        </tr>

        <tr>
          <td>Device Confirmation</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Confirm</td>
          <td><code>confirmButtonText</code></td>
        </tr>

        <tr>
          <td>Cancel</td>
          <td><code>cancelButtonText</code></td>
        </tr>

        <tr>
          <td>If you did not initiate this action or you do not recognize this device select cancel.</td>
          <td><code>confirmationText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="email-identifier-challenge">
    ## Screen: email-identifier-challenge

    <Frame>
      <img alt="email-identifier-challenge reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your email code to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>We've sent an email with your code to \$\{email}</td>
          <td><code>emailDescription</code></td>
        </tr>

        <tr>
          <td>6-digit code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Resend</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive an code?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Welcome</td>
          <td><code>titleWhenEmailFieldShown</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>The code must have 6 numeric characters</td>
          <td><code>invalid-otp-code-format</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>You have exceeded the allowed number of codes. Please go back and try again.</td>
          <td><code>too-many-otps</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backButtonText</code></td>
        </tr>

        <tr>
          <td>Enter the 6-digit code sent to your email address</td>
          <td><code>descriptionWhenEmailFieldShown</code></td>
        </tr>

        <tr>
          <td>Enter the code shown above</td>
          <td><code>captchaCodePlaceholder</code></td>
        </tr>

        <tr>
          <td>Code has been resent.</td>
          <td><code>resendLimitReachedText</code></td>
        </tr>

        <tr>
          <td>Continue with a password</td>
          <td><code>switchToPasswordButtonText</code></td>
        </tr>

        <tr>
          <td>Or</td>
          <td><code>separatorText</code></td>
        </tr>

        <tr>
          <td>Notification was not sent. Try resending the code.</td>
          <td><code>no-transaction-in-progress</code></td>
        </tr>

        <tr>
          <td>Too many failed codes. Wait for some minutes before retrying.</td>
          <td><code>too-many-failures</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>We are sorry, something went wrong while validating the captcha response. Please try again.</td>
          <td><code>captcha-validation-failure</code></td>
        </tr>

        <tr>
          <td>Select the checkbox to verify you are not a robot.</td>
          <td><code>invalid-recaptcha</code></td>
        </tr>

        <tr>
          <td>Solve the challenge question to verify you are not a robot.</td>
          <td><code>invalid-captcha</code></td>
        </tr>

        <tr>
          <td>We couldn’t load the security challenge. Please try again. (Error code: #)</td>
          <td><code>captcha-client-failure</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later</td>
          <td><code>auth0-users-validation</code></td>
        </tr>

        <tr>
          <td>Account not found. Go back and select sign up.</td>
          <td><code>invalid-user</code></td>
        </tr>

        <tr>
          <td>We have detected suspicious login behavior and further attempts will be blocked. Please contact the administrator.</td>
          <td><code>ip-blocked</code></td>
        </tr>

        <tr>
          <td>Your account has been blocked after multiple consecutive login attempts.</td>
          <td><code>user-blocked</code></td>
        </tr>

        <tr>
          <td>Too many login attempts for this user. Please wait, and try again later.</td>
          <td><code>same-user-login</code></td>
        </tr>

        <tr>
          <td>Account already exists. Go back and select log in.</td>
          <td><code>user-account-exists</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="email-otp-challenge">
    ## Screen: email-otp-challenge

    <Frame>![email-otp-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/email-otp-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your email code to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>We've sent an email with your code to \$\{email}</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Enter the code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Resend</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive an email?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>OTP Code must have 6 numeric characters</td>
          <td><code>invalid-otp-code-format</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>You have exceeded the amount of emails. Wait a few minutes and try again.</td>
          <td><code>too-many-email</code></td>
        </tr>

        <tr>
          <td>Please enter a code</td>
          <td><code>no-code</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="email-verification">
    ## Screen: email-verification-result

    <Frame>![email-verification-result reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/email-verification-result.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Email verification status \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Email Verified</td>
          <td><code>verifiedTitle</code></td>
        </tr>

        <tr>
          <td>Error</td>
          <td><code>errorTitle</code></td>
        </tr>

        <tr>
          <td>Your email address was successfully verified.</td>
          <td><code>verifiedDescription</code></td>
        </tr>

        <tr>
          <td>This account is already verified.</td>
          <td><code>alreadyVerifiedDescription</code></td>
        </tr>

        <tr>
          <td>User account does not exist or the verification code is invalid.</td>
          <td><code>invalidAccountOrCodeDescription</code></td>
        </tr>

        <tr>
          <td>Your email address could not be verified.</td>
          <td><code>unknownErrorDescription</code></td>
        </tr>

        <tr>
          <td>Back to \$\{clientName}</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>This ticket was expired.</td>
          <td><code>auth0-users-expired-ticket</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>custom-script-error-code</code></td>
        </tr>

        <tr>
          <td>This ticket was already used.</td>
          <td><code>auth0-users-used-ticket</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later</td>
          <td><code>auth0-users-validation</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="invitation">
    ## Screen: accept-invitation

    <Frame>![accept-invitation reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/accept-invitation.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Accept your invitation to sign up \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>You've Been Invited!</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>"\$\{inviterName}" has invited you ("\$\{email}") to join "\$\{companyName}" on "\$\{clientName}".</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="login">
    ## Screen: login

    <Frame>![login reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/login.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Log in</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Welcome</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Log in to \<%= "\$\{companyName}" %> to continue to \<%= "\$" %>.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Or</td>
          <td><code>separatorText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Continue with \<%= "" %></td>
          <td><code>federatedConnectionButtonText</code></td>
        </tr>

        <tr>
          <td>Sign up</td>
          <td><code>signupActionLinkText</code></td>
        </tr>

        <tr>
          <td>Don't have an account?</td>
          <td><code>signupActionText</code></td>
        </tr>

        <tr>
          <td>Forgot password?</td>
          <td><code>forgotPasswordText</code></td>
        </tr>

        <tr>
          <td>Password</td>
          <td><code>passwordPlaceholder</code></td>
        </tr>

        <tr>
          <td>Username or email address</td>
          <td><code>usernamePlaceholder</code></td>
        </tr>

        <tr>
          <td>Email address</td>
          <td><code>emailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone number</td>
          <td><code>phonePlaceholder</code></td>
        </tr>

        <tr>
          <td>Username</td>
          <td><code>usernameOnlyPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone or Username or Email</td>
          <td><code>phoneOrUsernameOrEmailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone number or Email address</td>
          <td><code>phoneOrEmailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone Number or Username</td>
          <td><code>phoneOrUsernamePlaceholder</code></td>
        </tr>

        <tr>
          <td>Username or Email address</td>
          <td><code>usernameOrEmailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Edit</td>
          <td><code>editEmailText</code></td>
        </tr>

        <tr>
          <td>Alerts</td>
          <td><code>alertListTitle</code></td>
        </tr>

        <tr>
          <td>You've Been Invited!</td>
          <td><code>invitationTitle</code></td>
        </tr>

        <tr>
          <td>Log in to accept \<%= "${inviterName}" %&gt;'s invitation to join &lt;%= "\$\{companyName}" %> on \<%= "\$" %>.</td>
          <td><code>invitationDescription</code></td>
        </tr>

        <tr>
          <td>\<%= "\$\{companyName}" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Show password</td>
          <td><code>showPasswordText</code></td>
        </tr>

        <tr>
          <td>Hide password</td>
          <td><code>hidePasswordText</code></td>
        </tr>

        <tr>
          <td>Wrong username or password</td>
          <td><code>wrong-credentials</code></td>
        </tr>

        <tr>
          <td>Wrong email or password</td>
          <td><code>wrong-email-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect username or password</td>
          <td><code>wrong-username-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect phone number or password</td>
          <td><code>wrong-phone-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect email address, username, or password</td>
          <td><code>wrong-email-username-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect email address, phone number, username, or password. Phone numbers must include the country code.</td>
          <td><code>wrong-email-phone-username-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect email address, phone number, or password. Phone numbers must include the country code.</td>
          <td><code>wrong-email-phone-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect phone number, username or password. Phone numbers must include the country code.</td>
          <td><code>wrong-phone-username-credentials</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>Invalid or expired user code</td>
          <td><code>invalid-expired-code</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>custom-script-error-code</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later</td>
          <td><code>auth0-users-validation</code></td>
        </tr>

        <tr>
          <td>We are sorry, something went wrong when attempting to log in</td>
          <td><code>authentication-failure</code></td>
        </tr>

        <tr>
          <td>Invalid connection</td>
          <td><code>invalid-connection</code></td>
        </tr>

        <tr>
          <td>We have detected suspicious login behavior and further attempts will be blocked. Please contact the administrator.</td>
          <td><code>ip-blocked</code></td>
        </tr>

        <tr>
          <td>Invalid connection</td>
          <td><code>no-db-connection</code></td>
        </tr>

        <tr>
          <td>We have detected a potential security issue with this account. To protect your account, we have prevented this login. Please reset your password to proceed.</td>
          <td><code>password-breached</code></td>
        </tr>

        <tr>
          <td>Your account has been blocked after multiple consecutive login attempts.</td>
          <td><code>user-blocked</code></td>
        </tr>

        <tr>
          <td>Too many login attempts for this user. Please wait, and try again later.</td>
          <td><code>same-user-login</code></td>
        </tr>

        <tr>
          <td>Please enter an email address</td>
          <td><code>no-email</code></td>
        </tr>

        <tr>
          <td>Password is required</td>
          <td><code>no-password</code></td>
        </tr>

        <tr>
          <td>Username is required</td>
          <td><code>no-username</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="login-id">
    ## Screen: login-id

    <Frame>![login-id reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/login-id.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Log in</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Welcome</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Log in to \<%= "\$\{companyName}" %> to continue to \<%= "\$" %>.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Or</td>
          <td><code>separatorText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Continue with \<%= "" %></td>
          <td><code>federatedConnectionButtonText</code></td>
        </tr>

        <tr>
          <td>Can't log in to your account?</td>
          <td><code>forgotPasswordText</code></td>
        </tr>

        <tr>
          <td>Sign up</td>
          <td><code>signupActionLinkText</code></td>
        </tr>

        <tr>
          <td>Don't have an account?</td>
          <td><code>signupActionText</code></td>
        </tr>

        <tr>
          <td>Password</td>
          <td><code>passwordPlaceholder</code></td>
        </tr>

        <tr>
          <td>Username or email address</td>
          <td><code>usernamePlaceholder</code></td>
        </tr>

        <tr>
          <td>Email address</td>
          <td><code>emailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone number</td>
          <td><code>phonePlaceholder</code></td>
        </tr>

        <tr>
          <td>Username</td>
          <td><code>usernameOnlyPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone or Username or Email</td>
          <td><code>phoneOrUsernameOrEmailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone number or Email address</td>
          <td><code>phoneOrEmailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone Number or Username</td>
          <td><code>phoneOrUsernamePlaceholder</code></td>
        </tr>

        <tr>
          <td>Username or Email address</td>
          <td><code>usernameOrEmailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Edit</td>
          <td><code>editEmailText</code></td>
        </tr>

        <tr>
          <td>Alerts</td>
          <td><code>alertListTitle</code></td>
        </tr>

        <tr>
          <td>\<%= "\$\{companyName}" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Continue with a passkey</td>
          <td><code>passkeyButtonText</code></td>
        </tr>

        <tr>
          <td>Wrong username or password</td>
          <td><code>wrong-credentials</code></td>
        </tr>

        <tr>
          <td>Wrong email or password</td>
          <td><code>wrong-email-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect username or password</td>
          <td><code>wrong-username-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect phone number or password</td>
          <td><code>wrong-phone-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect email address, username, or password</td>
          <td><code>wrong-email-username-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect email address, phone number, username, or password. Phone numbers must include the country code.</td>
          <td><code>wrong-email-phone-username-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect email address, phone number, or password. Phone numbers must include the country code.</td>
          <td><code>wrong-email-phone-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect phone number, username or password. Phone numbers must include the country code.</td>
          <td><code>wrong-phone-username-credentials</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>Invalid or expired user code</td>
          <td><code>invalid-expired-code</code></td>
        </tr>

        <tr>
          <td>Username can only contain alphanumeric characters or: '\<%= "${characters}" %&gt;'. Username should have between &lt;%= "$" %> and \<%= "\$" %> characters.</td>
          <td><code>invalid-username</code></td>
        </tr>

        <tr>
          <td>Invalid Login ID entered</td>
          <td><code>invalid-login-id</code></td>
        </tr>

        <tr>
          <td>Enter a valid email address or phone number. Phone numbers must include the country code.</td>
          <td><code>invalid-email-phone</code></td>
        </tr>

        <tr>
          <td>Enter a valid email address or username</td>
          <td><code>invalid-email-username</code></td>
        </tr>

        <tr>
          <td>Enter a valid phone number or username. Phone numbers must include the country code.</td>
          <td><code>invalid-phone-username</code></td>
        </tr>

        <tr>
          <td>Enter a valid email address, phone number, or username. Phone numbers must include the country code.</td>
          <td><code>invalid-email-phone-username</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>custom-script-error-code</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later</td>
          <td><code>auth0-users-validation</code></td>
        </tr>

        <tr>
          <td>We are sorry, something went wrong when attempting to log in</td>
          <td><code>authentication-failure</code></td>
        </tr>

        <tr>
          <td>Invalid connection</td>
          <td><code>invalid-connection</code></td>
        </tr>

        <tr>
          <td>We have detected suspicious login behavior and further attempts will be blocked. Please contact the administrator.</td>
          <td><code>ip-blocked</code></td>
        </tr>

        <tr>
          <td>Invalid connection</td>
          <td><code>no-db-connection</code></td>
        </tr>

        <tr>
          <td>Email does not match any enterprise directory</td>
          <td><code>no-hrd-connection</code></td>
        </tr>

        <tr>
          <td>We have detected a potential security issue with this account. To protect your account, we have prevented this login. Please reset your password to proceed.</td>
          <td><code>password-breached</code></td>
        </tr>

        <tr>
          <td>Your account has been blocked after multiple consecutive login attempts.</td>
          <td><code>user-blocked</code></td>
        </tr>

        <tr>
          <td>Too many login attempts for this user. Please wait, and try again later.</td>
          <td><code>same-user-login</code></td>
        </tr>

        <tr>
          <td>Please enter an email address</td>
          <td><code>no-email</code></td>
        </tr>

        <tr>
          <td>Password is required</td>
          <td><code>no-password</code></td>
        </tr>

        <tr>
          <td>Username is required</td>
          <td><code>no-username</code></td>
        </tr>

        <tr>
          <td>Enter a valid phone number</td>
          <td><code>invalid-phone-number</code></td>
        </tr>

        <tr>
          <td>Password and passkey are not allowed</td>
          <td><code>conflict-password-passkey</code></td>
        </tr>

        <tr>
          <td>Password is not allowed</td>
          <td><code>password-not-allowed</code></td>
        </tr>

        <tr>
          <td>Passkey is not allowed</td>
          <td><code>passkey-not-allowed</code></td>
        </tr>

        <tr>
          <td>Please select a passkey</td>
          <td><code>no-passkey</code></td>
        </tr>

        <tr>
          <td>Passkey authentication failed</td>
          <td><code>passkey-authentication-failed</code></td>
        </tr>

        <tr>
          <td>Something went wrong. Please try again later.</td>
          <td><code>invalid-passkey</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="login-password">
    ## Screen: login-password

    <Frame>![login-password reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/login-password.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your password to log in</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Enter Your Password</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Enter your password for \<%= "\$\{companyName}" %> to continue to \<%= "\$" %></td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Or</td>
          <td><code>separatorText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Continue with \<%= "" %></td>
          <td><code>federatedConnectionButtonText</code></td>
        </tr>

        <tr>
          <td>Sign up</td>
          <td><code>signupActionLinkText</code></td>
        </tr>

        <tr>
          <td>Don't have an account?</td>
          <td><code>signupActionText</code></td>
        </tr>

        <tr>
          <td>Forgot password?</td>
          <td><code>forgotPasswordText</code></td>
        </tr>

        <tr>
          <td>Password</td>
          <td><code>passwordPlaceholder</code></td>
        </tr>

        <tr>
          <td>Username or email address</td>
          <td><code>usernamePlaceholder</code></td>
        </tr>

        <tr>
          <td>Email address</td>
          <td><code>emailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Edit</td>
          <td><code>editEmailText</code></td>
        </tr>

        <tr>
          <td>Edit email address</td>
          <td><code>editLinkScreenReadableText</code></td>
        </tr>

        <tr>
          <td>Alerts</td>
          <td><code>alertListTitle</code></td>
        </tr>

        <tr>
          <td>You've Been Invited!</td>
          <td><code>invitationTitle</code></td>
        </tr>

        <tr>
          <td>Log in to accept \<%= "${inviterName}" %&gt;'s invitation to join &lt;%= "\$\{companyName}" %> on \<%= "\$" %>.</td>
          <td><code>invitationDescription</code></td>
        </tr>

        <tr>
          <td>\<%= "\$\{companyName}" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Use Fingerprint or Face Recognition</td>
          <td><code>useBiometricsText</code></td>
        </tr>

        <tr>
          <td>Show password</td>
          <td><code>showPasswordText</code></td>
        </tr>

        <tr>
          <td>Hide password</td>
          <td><code>hidePasswordText</code></td>
        </tr>

        <tr>
          <td>Wrong username or password</td>
          <td><code>wrong-credentials</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>Invalid or expired user code</td>
          <td><code>invalid-expired-code</code></td>
        </tr>

        <tr>
          <td>Wrong email or password</td>
          <td><code>wrong-email-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect username or password</td>
          <td><code>wrong-username-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect phone number or password</td>
          <td><code>wrong-phone-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect email address, username, or password</td>
          <td><code>wrong-email-username-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect email address, phone number, username, or password. Phone numbers must include the country code.</td>
          <td><code>wrong-email-phone-username-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect email address, phone number, or password. Phone numbers must include the country code.</td>
          <td><code>wrong-email-phone-credentials</code></td>
        </tr>

        <tr>
          <td>Incorrect phone number, username or password. Phone numbers must include the country code.</td>
          <td><code>wrong-phone-username-credentials</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>custom-script-error-code</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later</td>
          <td><code>auth0-users-validation</code></td>
        </tr>

        <tr>
          <td>We are sorry, something went wrong when attempting to log in</td>
          <td><code>authentication-failure</code></td>
        </tr>

        <tr>
          <td>Invalid connection</td>
          <td><code>invalid-connection</code></td>
        </tr>

        <tr>
          <td>We have detected suspicious login behavior and further attempts will be blocked. Please contact the administrator.</td>
          <td><code>ip-blocked</code></td>
        </tr>

        <tr>
          <td>Invalid connection</td>
          <td><code>no-db-connection</code></td>
        </tr>

        <tr>
          <td>We have detected a potential security issue with this account. To protect your account, we have prevented this login. Please reset your password to proceed.</td>
          <td><code>password-breached</code></td>
        </tr>

        <tr>
          <td>Your account has been blocked after multiple consecutive login attempts.</td>
          <td><code>user-blocked</code></td>
        </tr>

        <tr>
          <td>Too many login attempts for this user. Please wait, and try again later.</td>
          <td><code>same-user-login</code></td>
        </tr>

        <tr>
          <td>Please enter an email address</td>
          <td><code>no-email</code></td>
        </tr>

        <tr>
          <td>Password is required</td>
          <td><code>no-password</code></td>
        </tr>

        <tr>
          <td>Username is required</td>
          <td><code>no-username</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="login-passwordless">
    ## Screen: login-passwordless-email-code

    <Frame>
      <img alt="login-passwordless-email-code reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your email code to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>We've sent an email with your code to \$\{email}</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Enter the code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Resend</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive an email?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Code is invalid</td>
          <td><code>invalid-verification-code</code></td>
        </tr>

        <tr>
          <td>Code could not be sent. Please try again later.</td>
          <td><code>passwordless-authenticator-error</code></td>
        </tr>

        <tr>
          <td>Something went wrong. Please try again later.</td>
          <td><code>passwordless-unknown-error</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: login-passwordless-email-link

    <Frame>
      <img alt="login-passwordless-email-link reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Email Sign In Link \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Email sent</td>
          <td><code>successTitle</code></td>
        </tr>

        <tr>
          <td>Something went wrong</td>
          <td><code>errorTitle</code></td>
        </tr>

        <tr>
          <td>Email sent. Check your inbox for a login link.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Please try again later.</td>
          <td><code>unknownErrorDescription</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: login-passwordless-sms-otp

    <Frame>
      <img alt="login-passwordless-sms-otp reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your phone code to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>We've sent a text message to:</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Edit</td>
          <td><code>editText</code></td>
        </tr>

        <tr>
          <td>Enter the 6-digit code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Resend</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive a code?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Code is invalid</td>
          <td><code>invalid-verification-code</code></td>
        </tr>

        <tr>
          <td>Code could not be sent. Please try again later.</td>
          <td><code>passwordless-authenticator-error</code></td>
        </tr>

        <tr>
          <td>Something went wrong. Please try again later.</td>
          <td><code>passwordless-unknown-error</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="login-email-verification">
    ## Screen: login-email-verification

    <Frame>![login-email-verification reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/login-email-verification.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your email code to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>We've sent an email with your code to \$\{email}</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Enter the code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Resend</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive an email?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>Verify Your Email</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>OTP Code must have 6 numeric characters</td>
          <td><code>invalid-otp-code-format</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>Invalid or expired user code</td>
          <td><code>invalid-expired-code</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>You have exceeded the amount of emails. Wait a few minutes and try again.</td>
          <td><code>too-many-email</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="logout">
    ## Screen: logout

    <Frame>
      <img alt="logout reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Logout \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Logout</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Hi \$\{userName},</td>
          <td><code>userSalute</code></td>
        </tr>

        <tr>
          <td>Are you sure you want to log out from \$\{clientName}?</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Yes</td>
          <td><code>acceptButtonText</code></td>
        </tr>

        <tr>
          <td>No</td>
          <td><code>declineButtonText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="mfa">
    ## Screen: mfa-detect-browser-capabilities

    <Frame>
      <img alt="mfa-detect-browser-capabilities reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Reload</td>
          <td><code>reloadButtonText</code></td>
        </tr>

        <tr>
          <td>JavaScript Required</td>
          <td><code>noJSErrorTitle</code></td>
        </tr>

        <tr>
          <td>Your browser does not have JavaScript enabled. Please enable and press the Reload page button.</td>
          <td><code>noJSErrorDescription</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-enroll-result

    <Frame>![mfa-enroll-result reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-enroll-result.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>MFA enrollment status</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>You're All Set!</td>
          <td><code>enrolledTitle</code></td>
        </tr>

        <tr>
          <td>You have successfully added a new authentication factor.</td>
          <td><code>enrolledDescription</code></td>
        </tr>

        <tr>
          <td>Invalid Link</td>
          <td><code>invalidTicketTitle</code></td>
        </tr>

        <tr>
          <td>This link is invalid or expired.</td>
          <td><code>invalidTicketDescription</code></td>
        </tr>

        <tr>
          <td>Expired Link</td>
          <td><code>expiredTicketTitle</code></td>
        </tr>

        <tr>
          <td>This link is expired.</td>
          <td><code>expiredTicketDescription</code></td>
        </tr>

        <tr>
          <td>Already used</td>
          <td><code>alreadyUsedTitle</code></td>
        </tr>

        <tr>
          <td>This link has already been used. Please get a new link to enroll with Multi-factor Authentication.</td>
          <td><code>alreadyUsedDescription</code></td>
        </tr>

        <tr>
          <td>Two-factor Verification has Already Been Enabled.</td>
          <td><code>alreadyEnrolledDescription</code></td>
        </tr>

        <tr>
          <td>Something Went Wrong</td>
          <td><code>genericError</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-login-options

    <Frame>![mfa-login-options reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-login-options.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>List of other login methods \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backText</code></td>
        </tr>

        <tr>
          <td>Other Methods</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>SMS</td>
          <td><code>authenticatorNamesSMS</code></td>
        </tr>

        <tr>
          <td>Phone</td>
          <td><code>authenticatorNamesVoice</code></td>
        </tr>

        <tr>
          <td>Phone</td>
          <td><code>authenticatorNamesPhone</code></td>
        </tr>

        <tr>
          <td>Notification via \$\{appName} app</td>
          <td><code>authenticatorNamesPushNotification</code></td>
        </tr>

        <tr>
          <td>Google Authenticator or similar</td>
          <td><code>authenticatorNamesOTP</code></td>
        </tr>

        <tr>
          <td>Email</td>
          <td><code>authenticatorNamesEmail</code></td>
        </tr>

        <tr>
          <td>Recovery code</td>
          <td><code>authenticatorNamesRecoveryCode</code></td>
        </tr>

        <tr>
          <td>Notification via DUO app</td>
          <td><code>authenticatorNamesDUO</code></td>
        </tr>

        <tr>
          <td>Security Key</td>
          <td><code>authenticatorNamesWebauthnRoaming</code></td>
        </tr>

        <tr>
          <td>Fingerprint or Face Recognition</td>
          <td><code>authenticatorNamesWebauthnPlatform</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-begin-enroll-options

    <Frame>![mfa-begin-enroll-options reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-begin-enroll-options.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Add another authentication method \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backText</code></td>
        </tr>

        <tr>
          <td>Keep Your Account Safe</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Add another authentication method.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>SMS</td>
          <td><code>authenticatorNamesSMS</code></td>
        </tr>

        <tr>
          <td>Phone</td>
          <td><code>authenticatorNamesVoice</code></td>
        </tr>

        <tr>
          <td>Phone</td>
          <td><code>authenticatorNamesPhone</code></td>
        </tr>

        <tr>
          <td>Notification via \$\{appName} app</td>
          <td><code>authenticatorNamesPushNotification</code></td>
        </tr>

        <tr>
          <td>Google Authenticator or similar</td>
          <td><code>authenticatorNamesOTP</code></td>
        </tr>

        <tr>
          <td>Email</td>
          <td><code>authenticatorNamesEmail</code></td>
        </tr>

        <tr>
          <td>Recovery code</td>
          <td><code>authenticatorNamesRecoveryCode</code></td>
        </tr>

        <tr>
          <td>Notification via DUO app</td>
          <td><code>authenticatorNamesDUO</code></td>
        </tr>

        <tr>
          <td>Security Key</td>
          <td><code>authenticatorNamesWebauthnRoaming</code></td>
        </tr>

        <tr>
          <td>Fingerprint or Face Recognition</td>
          <td><code>authenticatorNamesWebauthnPlatform</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="mfa-email">
    ## Screen: mfa-email-challenge

    <Frame>![mfa-email-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-email-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your email code to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Go Back</td>
          <td><code>backText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>We've sent an email with your code to</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter the code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>Resend</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive an email?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>OTP Code must have 6 numeric characters</td>
          <td><code>invalid-otp-code-format</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>Notification was not sent. Try resending the code.</td>
          <td><code>no-transaction-in-progress</code></td>
        </tr>

        <tr>
          <td>You have exceeded the amount of emails. Wait a few minutes and try again.</td>
          <td><code>too-many-email</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>We couldn't send the email. Please try again later.</td>
          <td><code>mfa-email-challenge-authenticator-error</code></td>
        </tr>

        <tr>
          <td>Please enter a code</td>
          <td><code>no-code</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-email-list

    <Frame>![mfa-email-list reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-email-list.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>List of available email addresses \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backText</code></td>
        </tr>

        <tr>
          <td>Enrolled Email Addresses</td>
          <td><code>title</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="mfa-otp">
    ## Screen: mfa-otp-enrollment-qr

    <Frame>![mfa-otp-enrollment-qr reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-otp-enrollment-qr.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Scan the code to log in using a one-time password \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Secure Your Account</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Scan the QR Code below using your preferred authenticator app and then enter the provided one-time code below.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Trouble Scanning?</td>
          <td><code>codeEnrollmentText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter your one-time code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Then</td>
          <td><code>separatorText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>OTP Code must have 6 numeric characters</td>
          <td><code>invalid-otp-code-format</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>Too many failed codes. Wait for some minutes before retrying.</td>
          <td><code>too-many-failures</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>You are already enrolled on MFA.</td>
          <td><code>user-already-enrolled</code></td>
        </tr>

        <tr>
          <td>Please enter a code</td>
          <td><code>no-code</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-otp-enrollment-code

    <Frame>![mfa-otp-enrollment-code reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-otp-enrollment-code.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Copy the code to log in using a one-time password \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Secure code to copy</td>
          <td><code>altText</code></td>
        </tr>

        <tr>
          <td>Copy code</td>
          <td><code>copyCodeButtonText</code></td>
        </tr>

        <tr>
          <td>Manually enter the following code into your preferred authenticator app and then enter the provided one-time code below.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter your one-time code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Secure Your Account</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Too many failed codes. Wait for some minutes before retrying.</td>
          <td><code>too-many-failures</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>Please enter a code</td>
          <td><code>no-code</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-otp-challenge

    <Frame>![mfa-otp-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-otp-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your one-time password to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Check your preferred one-time password application for a code.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter your one-time code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Use password</td>
          <td><code>usePasswordText</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>Too many failed codes. Wait for some minutes before retrying.</td>
          <td><code>too-many-failures</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>Please enter a code</td>
          <td><code>no-code</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="mfa-phone">
    ## Screen: mfa-phone-challenge

    <Frame>![mfa-phone-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-phone-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Use your phone number to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>We will send a 6-digit code to the following phone number:</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>continueButtonText</code></td>
        </tr>

        <tr>
          <td>Choose another phone number.</td>
          <td><code>changePhoneText</code></td>
        </tr>

        <tr>
          <td>Text message</td>
          <td><code>smsButtonText</code></td>
        </tr>

        <tr>
          <td>Voice call</td>
          <td><code>voiceButtonText</code></td>
        </tr>

        <tr>
          <td>How do you want to receive the code?</td>
          <td><code>chooseMessageTypeText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter your phone number</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>There was a problem sending the SMS</td>
          <td><code>send-sms-failed</code></td>
        </tr>

        <tr>
          <td>There was a problem making the voice call</td>
          <td><code>send-voice-failed</code></td>
        </tr>

        <tr>
          <td>Phone number can only include digits.</td>
          <td><code>invalid-phone-format</code></td>
        </tr>

        <tr>
          <td>It seems that your phone number is not valid. Please check and retry.</td>
          <td><code>invalid-phone</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-sms</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-voice</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>Please enter a phone number</td>
          <td><code>no-phone</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-phone-enrollment

    <Frame>![mfa-phone-enrollment reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-phone-enrollment.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your phone number to log in using a phone code \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Secure Your Account</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Enter your country code and phone number to which we can send a 6-digit code:</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>continueButtonText</code></td>
        </tr>

        <tr>
          <td>Text message</td>
          <td><code>smsButtonText</code></td>
        </tr>

        <tr>
          <td>Voice call</td>
          <td><code>voiceButtonText</code></td>
        </tr>

        <tr>
          <td>How do you want to receive the code?</td>
          <td><code>chooseMessageTypeText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter your phone number</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>There was a problem sending the SMS</td>
          <td><code>send-sms-failed</code></td>
        </tr>

        <tr>
          <td>There was a problem making the voice call</td>
          <td><code>send-voice-failed</code></td>
        </tr>

        <tr>
          <td>We couldn't send the SMS. Please try again later.</td>
          <td><code>sms-authenticator-error</code></td>
        </tr>

        <tr>
          <td>Phone number can only include digits.</td>
          <td><code>invalid-phone-format</code></td>
        </tr>

        <tr>
          <td>It seems that your phone number is not valid. Please check and retry.</td>
          <td><code>invalid-phone</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-sms</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-voice</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again. \[<strong>note: this error is not typically reachable</strong>]</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>Please enter a phone number</td>
          <td><code>no-phone</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="mfa-push">
    ## Screen: mfa-push-welcome

    <Frame>![mfa-push-welcome reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-push-welcome.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Install the application \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Secure Your Account</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>In order to continue, install the \$\{appName} app via the app store from your mobile device.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Google Play</td>
          <td><code>androidButtonText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>App Store</td>
          <td><code>iosButtonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-push-enrollment-qr

    <Frame>![mfa-push-enrollment-qr reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-push-enrollment-qr.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Scan the code to log in using a push notification \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Secure Your Account</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Scan the QR Code below using the \$\{appName} app on your mobile device.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>You must scan the QR code with the \$\{appName} app on your mobile device.</td>
          <td><code>enrollment-transaction-pending</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-push-challenge-push

    <Frame>![mfa-push-challenge-push reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-push-challenge-push.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Accept the push notification to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>We’ve sent a notification to the following device via the \$\{appName} app:</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>I've responded on my device</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>Resend</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive a notification?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>Manually Enter Code</td>
          <td><code>enterOtpCode</code></td>
        </tr>

        <tr>
          <td>OR</td>
          <td><code>separatorText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>You must accept the notification via the \$\{appName} app on your mobile device.</td>
          <td><code>challenge-transaction-pending</code></td>
        </tr>

        <tr>
          <td>We have not received a confirmation, please slow down.</td>
          <td><code>polling-interval-exceeded</code></td>
        </tr>

        <tr>
          <td>We have received too many notification requests. Wait a few minutes and try again.</td>
          <td><code>too-many-push</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>We have not received a confirmation, please try scanning the code again.</td>
          <td><code>mfa-push-verify-transaction-pending</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the enrollment. Please try again later.</td>
          <td><code>mfa-push-verify-authenticator-error</code></td>
        </tr>

        <tr>
          <td>We couldn't send the notification. Please try again later.</td>
          <td><code>mfa-push-challenge-authenticator-error</code></td>
        </tr>

        <tr>
          <td>Notification rejected</td>
          <td><code>transaction-rejected</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-push-list

    <Frame>![mfa-push-list reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-push-list.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>List of available devices \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backText</code></td>
        </tr>

        <tr>
          <td>Registered Devices</td>
          <td><code>title</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="mfa-recovery-code">
    ## Screen: mfa-recovery-code-enrollment

    <Frame>![mfa-recovery-code-enrollment reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-recovery-code-enrollment.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Copy your recovery code for safe keeping \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Almost There!</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Copy this recovery code and keep it somewhere safe. You’ll need it if you ever need to log in without your device.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Secure code to copy</td>
          <td><code>altText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>I have safely recorded this code</td>
          <td><code>checkboxText</code></td>
        </tr>

        <tr>
          <td>Copy code</td>
          <td><code>copyCodeButtonText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Please confirm you have recorded the code</td>
          <td><code>no-confirmation</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-recovery-code-challenge

    <Frame>![mfa-recovery-code-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-recovery-code-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your recovery code to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Enter the recovery code you were provided during your initial enrollment.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter your recovery code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>Recovery code must have 24 alphanumeric characters</td>
          <td><code>invalid-code-format</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>Please confirm you have recorded the code</td>
          <td><code>no-confirmation</code></td>
        </tr>

        <tr>
          <td>Too many failed codes. Wait for some minutes before retrying.</td>
          <td><code>too-many-failures</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="mfa-sms">
    ## Screen: mfa-country-codes

    <Frame>![mfa-country-codes reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-country-codes.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Select your country code \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backText</code></td>
        </tr>

        <tr>
          <td>Select a Country Code</td>
          <td><code>title</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-sms-enrollment

    <Frame>![mfa-sms-enrollment reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-sms-enrollment.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your phone number to log in using a text message \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Secure Your Account</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Enter your phone number below. An SMS will be sent to that number with a code to enter on the next screen.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter your phone number</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>There was a problem sending the SMS</td>
          <td><code>send-sms-failed</code></td>
        </tr>

        <tr>
          <td>We couldn't send the SMS. Please try again later.</td>
          <td><code>sms-authenticator-error</code></td>
        </tr>

        <tr>
          <td>Phone number can only include digits.</td>
          <td><code>invalid-phone-format</code></td>
        </tr>

        <tr>
          <td>Seems that your phone number is not valid. Please check and retry.</td>
          <td><code>invalid-phone</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-sms</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>Please enter a phone number</td>
          <td><code>no-phone</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-sms-challenge

    <Frame>![mfa-sms-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-sms-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your phone code to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>We've sent a text message to:</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Edit</td>
          <td><code>editText</code></td>
        </tr>

        <tr>
          <td>Edit phone number</td>
          <td><code>editLinkScreenReadableText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter the 6-digit code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>Resend</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive a code?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>or</td>
          <td><code>resendVoiceActionSeparatorTextBefore</code></td>
        </tr>

        <tr>
          <td>get a call</td>
          <td><code>resendVoiceActionText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>OTP Code must have 6 numeric characters</td>
          <td><code>invalid-otp-code-format</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>There was a problem sending the SMS</td>
          <td><code>send-sms-failed</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>We couldn't send the SMS. Please try again later.</td>
          <td><code>sms-authenticator-error</code></td>
        </tr>

        <tr>
          <td>Notification was not sent. Try resending the code.</td>
          <td><code>no-transaction-in-progress</code></td>
        </tr>

        <tr>
          <td>Too many failed codes. Wait for some minutes before retrying.</td>
          <td><code>too-many-failures</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-sms</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>Please enter a code</td>
          <td><code>no-code</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-sms-list

    <Frame>![mfa-sms-list reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-sms-list.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>List of available phone numbers \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backText</code></td>
        </tr>

        <tr>
          <td>Enrolled Phone Numbers</td>
          <td><code>title</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="mfa-voice">
    ## Screen: mfa-voice-enrollment

    <Frame>![mfa-voice-enrollment reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-voice-enrollment.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your phone number to log in using a phone code \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Secure Your Account</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Enter your phone number below. A voice call will be placed on that number with a code to enter on the next screen.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter your phone number</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>There was a problem sending the SMS</td>
          <td><code>send-sms-failed</code></td>
        </tr>

        <tr>
          <td>Phone number can only include digits.</td>
          <td><code>invalid-phone-format</code></td>
        </tr>

        <tr>
          <td>Seems that your phone number is not valid. Please check and retry.</td>
          <td><code>invalid-phone</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-sms</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>Please enter a phone number</td>
          <td><code>no-phone</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-voice-challenge

    <Frame>![mfa-voice-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-voice-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your phone code to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>We've sent a 6-digit code via voice phone call to the following phone number:</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Edit</td>
          <td><code>editText</code></td>
        </tr>

        <tr>
          <td>Edit phone number</td>
          <td><code>editLinkScreenReadableText</code></td>
        </tr>

        <tr>
          <td>Choose another phone number.</td>
          <td><code>changePhoneText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter the 6-digit code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>Call again</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive a call?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>or</td>
          <td><code>resendSmsActionSeparatorTextBefore</code></td>
        </tr>

        <tr>
          <td>send a text</td>
          <td><code>resendSmsActionText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>OTP Code must have 6 numeric characters</td>
          <td><code>invalid-otp-code-format</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>There was a problem making the voice call</td>
          <td><code>send-voice-failed</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>We couldn't make the voice call. Please try again later.</td>
          <td><code>voice-authenticator-error</code></td>
        </tr>

        <tr>
          <td>Notification was not sent. Try resending the code.</td>
          <td><code>no-transaction-in-progress</code></td>
        </tr>

        <tr>
          <td>Too many failed codes. Wait for some minutes before retrying.</td>
          <td><code>too-many-failures</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-voice</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>Please enter a code</td>
          <td><code>no-code</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="mfa-webauthn">
    ## Screen: mfa-webauthn-platform-enrollment

    <Frame>
      <img alt="mfa-webauthn-enrollment reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Log in faster on this device \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Log In Faster on This Device</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Trust this device? You can quickly and securely log in the next time using this device's fingerprint or face recognition.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Awaiting device confirmation</td>
          <td><code>awaitingConfirmation</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>continueButtonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Remind me later</td>
          <td><code>snoozeEnrollmentButtonText</code></td>
        </tr>

        <tr>
          <td>Not on this device</td>
          <td><code>refuseAddingDeviceText</code></td>
        </tr>

        <tr>
          <td>Not now</td>
          <td><code>skipAddingDeviceText</code></td>
        </tr>

        <tr>
          <td>We could not start the device enrollment. Please try again later.</td>
          <td><code>webauthn-platform-associate-error</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-webauthn-roaming-enrollment

    <Frame>
      <img alt="mfa-webauthn-guidance-enrollment reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Register your security key \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Adding Your Security Key</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Security Keys can be used as an additional authentication factor.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Awaiting Security Key</td>
          <td><code>awaitingConfirmation</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Use security key</td>
          <td><code>continueButtonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Connect your Security Key and continue.</td>
          <td><code>instructions1</code></td>
        </tr>

        <tr>
          <td>Follow the steps on the browser.</td>
          <td><code>instructions2</code></td>
        </tr>

        <tr>
          <td>Name your Security Key to easily identify it later.</td>
          <td><code>instructions3</code></td>
        </tr>

        <tr>
          <td>We could not start the security key enrollment. Please try again later.</td>
          <td><code>webauthn-associate-error</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-webauthn-platform-challenge

    <Frame>
      <img alt="mfa-webauthn-challenge-user-initiated reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Use fingerprint or face recognition to login \$\{clientName}</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Press the button below and follow your browser's steps to log in.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Awaiting device confirmation</td>
          <td><code>awaitingConfirmation</code></td>
        </tr>

        <tr>
          <td>Too many failed authentication attempts. Please try again later.</td>
          <td><code>too-many-webauthn-challenge-attempts-error</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>continueButtonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Use password</td>
          <td><code>usePasswordText</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>We could not start the device verification. Please try again later.</td>
          <td><code>webauthn-platform-challenge-error</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-webauthn-roaming-challenge

    <Frame>
      <img alt="mfa-webauthn-challenge-user-initiated reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Use your security key to log in \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Make sure your Security Key is nearby. Once you continue, you will be prompted to use it.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Awaiting Security Key</td>
          <td><code>awaitingConfirmation</code></td>
        </tr>

        <tr>
          <td>Too many failed authentication attempts. Please try again later.</td>
          <td><code>too-many-webauthn-challenge-attempts-error</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Use security key</td>
          <td><code>continueButtonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>We could not start the security key verification. Please try again later.</td>
          <td><code>webauthn-challenge-error</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-webauthn-change-key-nickname

    <Frame>
      <img alt="mfa-webauthn-change-key-nickname reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Name your security key \$\{clientName}</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>If you own multiple keys, this alias will help you identify the right one.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>\$\{userName}'s key</td>
          <td><code>nickname</code></td>
        </tr>

        <tr>
          <td>Security key name</td>
          <td><code>nicknamePlaceholder</code></td>
        </tr>

        <tr>
          <td>Name your device</td>
          <td>\$\{clientName}</td>
        </tr>

        <tr>
          <td>If you own multiple devices, this alias will help you identify the right one.</td>
          <td><code>descriptionPlatform</code></td>
        </tr>

        <tr>
          <td>$\{userName}'s \$\{deviceName}</td>
          <td><code>nicknamePlatform</code></td>
        </tr>

        <tr>
          <td>Device name</td>
          <td><code>nicknamePlaceholderPlatform</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>We could not update your key's name. Please try again.</td>
          <td><code>webauthn-patch-nickname-error</code></td>
        </tr>

        <tr>
          <td>We could not update your Device's name. Please try again.</td>
          <td><code>webauthn-platform-patch-nickname-error</code></td>
        </tr>

        <tr>
          <td>Name is required</td>
          <td><code>no-nickname</code></td>
        </tr>

        <tr>
          <td>Name is too short</td>
          <td><code>nickname-too-short</code></td>
        </tr>

        <tr>
          <td>Name is too long</td>
          <td><code>nickname-too-long</code></td>
        </tr>

        <tr>
          <td>An error occurred while retrieving your information. Please try again.</td>
          <td><code>error-while-retrieving-authenticator</code></td>
        </tr>

        <tr>
          <td>An error occurred while trying to save the name . Please try again.</td>
          <td><code>error-while-patching</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-webauthn-enrollment-success

    <Frame>
      <img alt="mfa-webauthn-enrollment-success reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Security key successful \$\{clientName}</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Device registration successful \$\{clientName}</td>
          <td><code>titlePlatform</code></td>
        </tr>

        <tr>
          <td>You have successfully registered your Security Key.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>You have successfully registered your device.</td>
          <td><code>descriptionPlatform</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-webauthn-error

    <Frame>![mfa-webauthn-error reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-webauthn-error.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Try again</td>
          <td><code>tryAgainLinkText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Security key registration error</td>
          <td>\$\{clientName}</td>
        </tr>

        <tr>
          <td>Security Key Verification Failed</td>
          <td><code>errorTitleChallenge</code></td>
        </tr>

        <tr>
          <td>Device registration error</td>
          <td>\$\{clientName}</td>
        </tr>

        <tr>
          <td>Something Went Wrong</td>
          <td><code>errorTitlePlatformChallenge</code></td>
        </tr>

        <tr>
          <td>Something went wrong. Please try again or try using another method.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>If you already registered this device, please try again. If not, try using another method.</td>
          <td><code>descriptionPlatform</code></td>
        </tr>

        <tr>
          <td>No Thanks</td>
          <td><code>refuseAddingAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Use password</td>
          <td><code>usePasswordText</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: mfa-webauthn-not-available-error

    <Frame>![mfa-webauthn-not-available-error reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/mfa-webauthn-not-available-error.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Security keys are not supported \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Security Keys Are Not Supported</td>
          <td><code>errorTitle</code></td>
        </tr>

        <tr>
          <td>We are sorry but your browser or device does not support Security Keys. Try using another browser or log in from another device.</td>
          <td><code>errorDescription</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Use password</td>
          <td><code>usePasswordText</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="organizations">
    ## Screen: organization-selection

    <Frame>![organization-selection reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/organization-selection.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your organization \$\{clientName}</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Enter your \$\{companyName} Organization Name to continue</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Enter your Organization Name</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Enter Organization</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>\$\{companyName}</td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>The organization you entered is invalid</td>
          <td><code>invalid-organization</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: organization-picker

    <Frame>![organization-picker reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/organization-picker-rev2.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Choose an Organization</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>is a part of multiple organizations.</td>
          <td><code>loggedInText</code></td>
        </tr>

        <tr>
          <td>is used as a personal account and is a part of multiple organizations.</td>
          <td><code>loggedInTextB2C</code></td>
        </tr>

        <tr>
          <td>Choose an Organization</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Choose an Account to Continue</td>
          <td><code>titleB2C</code></td>
        </tr>

        <tr>
          <td>\<%= "\$\{companyName}" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>OR</td>
          <td><code>separatorText</code></td>
        </tr>

        <tr>
          <td>Continue with personal account</td>
          <td><code>continueTextB2C</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="reset-password">
    ## Screen: reset-password-request

    <Frame>![reset-password-request reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-request.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Reset your password</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Forgot Your Password?</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Back to \<%= "\$" %></td>
          <td><code>backToLoginLinkText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Enter your email address and we will send you instructions to reset your password.</td>
          <td><code>descriptionEmail</code></td>
        </tr>

        <tr>
          <td>Enter your username and we will send you instructions to reset your password.</td>
          <td><code>descriptionUsername</code></td>
        </tr>

        <tr>
          <td>Email address</td>
          <td><code>placeholderEmail</code></td>
        </tr>

        <tr>
          <td>Username</td>
          <td><code>placeholderUsername</code></td>
        </tr>

        <tr>
          <td>Email address</td>
          <td><code>emailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Username</td>
          <td><code>usernamePlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone number</td>
          <td><code>phonePlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone or Username or Email</td>
          <td><code>phoneOrUsernameOrEmailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone number or Email address</td>
          <td><code>phoneOrEmailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone Number or Username</td>
          <td><code>phoneOrUsernamePlaceholder</code></td>
        </tr>

        <tr>
          <td>Username or Email address</td>
          <td><code>usernameOrEmailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Enter your Email address and we will send you instructions to reset your password.</td>
          <td><code>emailDescription</code></td>
        </tr>

        <tr>
          <td>Enter your Username and we will send you instructions to reset your password.</td>
          <td><code>usernameDescription</code></td>
        </tr>

        <tr>
          <td>Enter your Phone number and we will send you instructions to reset your password.</td>
          <td><code>phoneDescription</code></td>
        </tr>

        <tr>
          <td>Enter your Phone number or Username or Email address and we will send you instructions to reset your password.</td>
          <td><code>phoneOrUsernameOrEmailDescription</code></td>
        </tr>

        <tr>
          <td>Enter your Phone number or Email address and we will send you instructions to reset your password.</td>
          <td><code>phoneOrEmailDescription</code></td>
        </tr>

        <tr>
          <td>Enter your Phone number or Username and we will send you instructions to reset your password.</td>
          <td><code>phoneOrUsernameDescription</code></td>
        </tr>

        <tr>
          <td>Enter your Username or Email address and we will send you instructions to reset your password.</td>
          <td><code>usernameOrEmailDescription</code></td>
        </tr>

        <tr>
          <td>\<%= "\$\{companyName}" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>This ticket was expired.</td>
          <td><code>auth0-users-expired-ticket</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>custom-script-error-code</code></td>
        </tr>

        <tr>
          <td>This ticket was already used.</td>
          <td><code>auth0-users-used-ticket</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later</td>
          <td><code>auth0-users-validation</code></td>
        </tr>

        <tr>
          <td>We had a problem sending the email, please try again later.</td>
          <td><code>reset-password-error</code></td>
        </tr>

        <tr>
          <td>You have exceeded the amount of emails. Wait a few minutes and try again.</td>
          <td><code>too-many-email</code></td>
        </tr>

        <tr>
          <td>You have exceeded the amount of emails. Wait a few minutes and try again.</td>
          <td><code>too-many-requests</code></td>
        </tr>

        <tr>
          <td>Please enter an email address</td>
          <td><code>no-email</code></td>
        </tr>

        <tr>
          <td>Username is required</td>
          <td><code>no-username</code></td>
        </tr>

        <tr>
          <td>Please enter a phone number</td>
          <td><code>no-phone\_number</code></td>
        </tr>

        <tr>
          <td>Phone number is not valid.</td>
          <td><code>invalid-phone-format</code></td>
        </tr>

        <tr>
          <td>Invalid Login ID entered</td>
          <td><code>invalid-login-id</code></td>
        </tr>

        <tr>
          <td>Enter a valid email address or phone number. Phone numbers must include the country code.</td>
          <td><code>invalid-email-phone</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password-email

    <Frame>![reset-password-email reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-email.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Check your email</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Check Your Email</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backButtonText</code></td>
        </tr>

        <tr>
          <td>Please check the email address \<%= "\$" %> for instructions to reset your password.</td>
          <td><code>emailDescription</code></td>
        </tr>

        <tr>
          <td>Resend email</td>
          <td><code>resendLinkText</code></td>
        </tr>

        <tr>
          <td>Please check the email address associated with the username \<%= "\$" %> for instructions to reset your password.</td>
          <td><code>usernameDescription</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password

    <Frame>![reset-password reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Reset your password</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Change Your Password</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Enter a new password below to change your password.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Reset password</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>New password</td>
          <td><code>passwordPlaceholder</code></td>
        </tr>

        <tr>
          <td>Re-enter new password</td>
          <td><code>reEnterpasswordPlaceholder</code></td>
        </tr>

        <tr>
          <td>Your password must contain:</td>
          <td><code>passwordSecurityText</code></td>
        </tr>

        <tr>
          <td>\<%= "\$\{companyName}" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Show password</td>
          <td><code>showPasswordText</code></td>
        </tr>

        <tr>
          <td>Hide password</td>
          <td><code>hidePasswordText</code></td>
        </tr>

        <tr>
          <td>Fail</td>
          <td><code>accessibilityError</code></td>
        </tr>

        <tr>
          <td>Pass</td>
          <td><code>accessibilityValid</code></td>
        </tr>

        <tr>
          <td>This ticket was expired.</td>
          <td><code>auth0-users-expired-ticket</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>custom-script-error-code</code></td>
        </tr>

        <tr>
          <td>This ticket was already used.</td>
          <td><code>auth0-users-used-ticket</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later</td>
          <td><code>auth0-users-validation</code></td>
        </tr>

        <tr>
          <td>Enter a new password.</td>
          <td><code>no-password-reset</code></td>
        </tr>

        <tr>
          <td>New password confirmation is missing</td>
          <td><code>no-re-enter-password</code></td>
        </tr>

        <tr>
          <td>Password contains user information</td>
          <td><code>password-contains-user-information</code></td>
        </tr>

        <tr>
          <td>This combination of credentials was detected in a public data breach on another website. To continue, please use a different password to keep your account secure.</td>
          <td><code>password-breached-reset</code></td>
        </tr>

        <tr>
          <td>Passwords don't match</td>
          <td><code>password-mismatch</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password-success

    <Frame>![reset-password-success reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-success.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Password reset successful</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Password Changed!</td>
          <td><code>eventTitle</code></td>
        </tr>

        <tr>
          <td>Your password has been changed successfully.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Back to \<%= "\$" %></td>
          <td><code>buttonText</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password-error

    <Frame>![reset-password-error reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-error.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Password reset error</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Back to \<%= "\$" %></td>
          <td><code>backToLoginLinkText</code></td>
        </tr>

        <tr>
          <td>To reset your password, return to the login page and select "Forgot Your Password" to send a new email.</td>
          <td><code>descriptionExpired</code></td>
        </tr>

        <tr>
          <td>Something went wrong. Please return to the login page and select "Forgot Your Password" to try again.</td>
          <td><code>descriptionGeneric</code></td>
        </tr>

        <tr>
          <td>This link has already been used. To reset your password, return to the login page and select "Forgot Your Password" to send a new email.</td>
          <td><code>descriptionUsed</code></td>
        </tr>

        <tr>
          <td>Link Expired</td>
          <td><code>eventTitleExpired</code></td>
        </tr>

        <tr>
          <td>Please Try Again</td>
          <td><code>eventTitleGeneric</code></td>
        </tr>

        <tr>
          <td>Invalid Link</td>
          <td><code>eventTitleUsed</code></td>
        </tr>

        <tr>
          <td>This ticket was expired.</td>
          <td><code>auth0-users-expired-ticket</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>custom-script-error-code</code></td>
        </tr>

        <tr>
          <td>This ticket was already used.</td>
          <td><code>auth0-users-used-ticket</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later</td>
          <td><code>auth0-users-validation</code></td>
        </tr>

        <tr>
          <td>We had a problem sending the email, please try again later.</td>
          <td><code>reset-password-error</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password-mfa-email-challenge

    <Frame>![reset-password-mfa-email-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-mfa-email-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your one-time password to change your password for</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Go Back</td>
          <td><code>backText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>We've sent an email with your code to</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter the code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>Resend</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive an email?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>\<%= "\$\{companyName}" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>OTP Code must have 6 numeric characters</td>
          <td><code>invalid-otp-code-format</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>Notification was not sent. Try resending the code.</td>
          <td><code>no-transaction-in-progress</code></td>
        </tr>

        <tr>
          <td>You have exceeded the amount of emails. Wait a few minutes and try again.</td>
          <td><code>too-many-email</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>We couldn't send the email. Please try again later.</td>
          <td><code>mfa-email-challenge-authenticator-error</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password-mfa-otp-challenge

    <Frame>![reset-password-mfa-otp-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-mfa-otp-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your one-time password to change your password for</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Check your preferred one-time password application for a code.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter your one-time code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>\<%= "\$\{companyName}" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Use password</td>
          <td><code>usePasswordText</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>Too many failed codes. Wait for some minutes before retrying.</td>
          <td><code>too-many-failures</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password-mfa-phone-challenge

    <Frame>![reset-password-mfa-phone-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-mfa-phone-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your one-time password to change your password for</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>We will send a 6-digit code to the following phone number:</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>continueButtonText</code></td>
        </tr>

        <tr>
          <td>Choose another phone number.</td>
          <td><code>changePhoneText</code></td>
        </tr>

        <tr>
          <td>Text message</td>
          <td><code>smsButtonText</code></td>
        </tr>

        <tr>
          <td>Voice call</td>
          <td><code>voiceButtonText</code></td>
        </tr>

        <tr>
          <td>How do you want to receive the code?</td>
          <td><code>chooseMessageTypeText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter your phone number</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>\<%= "\$\{companyName}" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>There was a problem sending the SMS</td>
          <td><code>send-sms-failed</code></td>
        </tr>

        <tr>
          <td>There was a problem making the voice call</td>
          <td><code>send-voice-failed</code></td>
        </tr>

        <tr>
          <td>Phone number can only include digits.</td>
          <td><code>invalid-phone-format</code></td>
        </tr>

        <tr>
          <td>It seems that your phone number is not valid. Please check and retry.</td>
          <td><code>invalid-phone</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-sms</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-voice</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>Please enter a phone number</td>
          <td><code>no-phone</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password-mfa-push-challenge-push

    <Frame>![reset-password-mfa-push-challenge-push reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-mfa-push-challenge-push.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your one-time password to change your password for</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>We’ve sent a notification to the following device via the \<%= "\$" %> app:</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>I've responded on my device</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>Resend</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive a notification?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>Manually Enter Code</td>
          <td><code>enterOtpCode</code></td>
        </tr>

        <tr>
          <td>OR</td>
          <td><code>separatorText</code></td>
        </tr>

        <tr>
          <td>\<%= "\$\{companyName}" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>You must accept the notification via the \<%= "\$" %> app on your mobile device.</td>
          <td><code>challenge-transaction-pending</code></td>
        </tr>

        <tr>
          <td>We have not received a confirmation, please slow down.</td>
          <td><code>polling-interval-exceeded</code></td>
        </tr>

        <tr>
          <td>We have received too many notification requests. Wait a few minutes and try again.</td>
          <td><code>too-many-push</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>We have not received a confirmation, please try scanning the code again.</td>
          <td><code>mfa-push-verify-transaction-pending</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the enrollment. Please try again later.</td>
          <td><code>mfa-push-verify-authenticator-error</code></td>
        </tr>

        <tr>
          <td>We couldn't send the notification. Please try again later.</td>
          <td><code>mfa-push-challenge-authenticator-error</code></td>
        </tr>

        <tr>
          <td>Notification rejected</td>
          <td><code>transaction-rejected</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password-mfa-recovery-code-challenge

    <Frame>![reset-password-mfa-recovery-code-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-mfa-recovery-code-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your one-time password to change your password for</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Enter the recovery code you were provided during your initial enrollment.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter your recovery code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>\<%= "\$\{companyName}" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>Recovery code must have 24 alphanumeric characters</td>
          <td><code>invalid-code-format</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>Please confirm you have recorded the code</td>
          <td><code>no-confirmation</code></td>
        </tr>

        <tr>
          <td>Too many failed codes. Wait for some minutes before retrying.</td>
          <td><code>too-many-failures</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password-mfa-sms-challenge

    <Frame>![reset-password-mfa-sms-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-mfa-sms-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your one-time password to change your password for</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>We've sent a text message to:</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Edit</td>
          <td><code>editText</code></td>
        </tr>

        <tr>
          <td>Edit phone number</td>
          <td><code>editLinkScreenReadableText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter the 6-digit code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>Resend</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive a code?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>or</td>
          <td><code>resendVoiceActionSeparatorTextBefore</code></td>
        </tr>

        <tr>
          <td>get a call</td>
          <td><code>resendVoiceActionText</code></td>
        </tr>

        <tr>
          <td>\<%= "\$\{companyName}" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>OTP Code must have 6 numeric characters</td>
          <td><code>invalid-otp-code-format</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>There was a problem sending the SMS</td>
          <td><code>send-sms-failed</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>We couldn't send the SMS. Please try again later.</td>
          <td><code>sms-authenticator-error</code></td>
        </tr>

        <tr>
          <td>Notification was not sent. Try resending the code.</td>
          <td><code>no-transaction-in-progress</code></td>
        </tr>

        <tr>
          <td>Too many failed codes. Wait for some minutes before retrying.</td>
          <td><code>too-many-failures</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-sms</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password-mfa-voice-challenge

    <Frame>![reset-password-mfa-voice-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-mfa-voice-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your one-time password to change your password for</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>We've sent a 6-digit code via voice phone call to the following phone number:</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Edit</td>
          <td><code>editText</code></td>
        </tr>

        <tr>
          <td>Edit phone number</td>
          <td><code>editLinkScreenReadableText</code></td>
        </tr>

        <tr>
          <td>Choose another phone number.</td>
          <td><code>changePhoneText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Enter the 6-digit code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>Call again</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive a call?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>or</td>
          <td><code>resendSmsActionSeparatorTextBefore</code></td>
        </tr>

        <tr>
          <td>send a text</td>
          <td><code>resendSmsActionText</code></td>
        </tr>

        <tr>
          <td>\<%= "\$\{companyName}" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>OTP Code must have 6 numeric characters</td>
          <td><code>invalid-otp-code-format</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>There was a problem making the voice call</td>
          <td><code>send-voice-failed</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>We couldn't make the voice call. Please try again later.</td>
          <td><code>voice-authenticator-error</code></td>
        </tr>

        <tr>
          <td>Notification was not sent. Try resending the code.</td>
          <td><code>no-transaction-in-progress</code></td>
        </tr>

        <tr>
          <td>Too many failed codes. Wait for some minutes before retrying.</td>
          <td><code>too-many-failures</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-voice</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password-mfa-webauthn-platform-challenge

    <Frame>![reset-password-mfa-webauthn-platform-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-mfa-webauthn-platform-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Verify with fingerprint or face recognition</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Use fingerprint or face recognition to reset password</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Press the button below and follow your browser's steps to log in.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Awaiting device confirmation</td>
          <td><code>awaitingConfirmation</code></td>
        </tr>

        <tr>
          <td>Too many failed authentication attempts. Please try again later.</td>
          <td><code>too-many-webauthn-challenge-attempts-error</code></td>
        </tr>

        <tr>
          <td>\<%= "\$\{companyName}" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>continueButtonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Use password</td>
          <td><code>usePasswordText</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>We could not start the device verification. Please try again later.</td>
          <td><code>webauthn-platform-challenge-error</code></td>
        </tr>
      </tbody>
    </table>

    ## Screen: reset-password-mfa-webauthn-roaming-challenge

    <Frame>![reset-password-mfa-webauthn-roaming-challenge reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/reset-password-mfa-webauthn-roaming-challenge.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Use your security key to reset password</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Make sure your Security Key is nearby. Once you continue, you will be prompted to use it.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Awaiting Security Key</td>
          <td><code>awaitingConfirmation</code></td>
        </tr>

        <tr>
          <td>Too many failed authentication attempts. Please try again later.</td>
          <td><code>too-many-webauthn-challenge-attempts-error</code></td>
        </tr>

        <tr>
          <td>\<%= "\$\{companyName}" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Use security key</td>
          <td><code>continueButtonText</code></td>
        </tr>

        <tr>
          <td>Try another method</td>
          <td><code>pickAuthenticatorText</code></td>
        </tr>

        <tr>
          <td>Remember this device for 30 days</td>
          <td><code>rememberMeText</code></td>
        </tr>

        <tr>
          <td>We could not start the security key verification. Please try again later.</td>
          <td><code>webauthn-challenge-error</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="passkey-enrollment">
    ## Screen: passkey-enrollment

    <Frame>![passkey-enrollment reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/passkey-enrollment.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Create a passkey for <code>\$\{clientName}</code> on this device.</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Log in <code>\$\{clientName}</code>.</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Log in to <code>$\{companyName}</code> to continue to <code>$\{clientName}</code>.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>No need to remember a password.</td>
          <td><code>passkeyBenefit1Title</code></td>
        </tr>

        <tr>
          <td>Webauthn platform icon</td>
          <td><code>passkeyBenefit1ImgAltText</code></td>
        </tr>

        <tr>
          <td>With passkeys, you can use things like your fingerprint or face to login.</td>
          <td><code>passkeyBenefit1Description</code></td>
        </tr>

        <tr>
          <td>Works on all of your devices.</td>
          <td><code>passkeyBenefit2Title</code></td>
        </tr>

        <tr>
          <td>Device globe</td>
          <td><code>passkeyBenefit2ImgAltText</code></td>
        </tr>

        <tr>
          <td>Passkeys will automatically be available across your synced devices.</td>
          <td><code>passkeyBenefit2Description</code></td>
        </tr>

        <tr>
          <td>Keep your account safer.</td>
          <td><code>passkeyBenefit3Title</code></td>
        </tr>

        <tr>
          <td>Shield with check mark.</td>
          <td><code>passkeyBenefit3ImgAltText</code></td>
        </tr>

        <tr>
          <td>Passkeys offer state-of-the-art phishing resistance.</td>
          <td><code>passkeyBenefit3Description</code></td>
        </tr>

        <tr>
          <td>Create a passkey.</td>
          <td><code>createButtonText</code></td>
        </tr>

        <tr>
          <td>Continue without passkeys.</td>
          <td><code>continueButtonText</code></td>
        </tr>

        <tr>
          <td>Create a new passkey.</td>
          <td><code>createButtonResetText</code></td>
        </tr>

        <tr>
          <td>Create a new password.</td>
          <td><code>usePasswordButtonText</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backButtonText</code></td>
        </tr>

        <tr>
          <td>Don't show me this again.</td>
          <td><code>checkboxText</code></td>
        </tr>

        <tr>
          <td>The user already exists.</td>
          <td><code>error\_email-in-use</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>error\_auth0-users-validation</code></td>
        </tr>

        <tr>
          <td>Password and passkey are not allowed.</td>
          <td><code>error\_conflict-password-passkey</code></td>
        </tr>

        <tr>
          <td>Password is not allowed.</td>
          <td><code>error\_password-not-allowed</code></td>
        </tr>

        <tr>
          <td>Passkey is not allowed.</td>
          <td><code>error\_passkey-not-allowed</code></td>
        </tr>

        <tr>
          <td>Something went wrong. Please try again later.</td>
          <td><code>error\_invalid-passkey</code></td>
        </tr>

        <tr>
          <td>Something went wrong. Please try again later.</td>
          <td><code>error\_passkey-enrollment-failure</code></td>
        </tr>

        <tr>
          <td>You have created the maximum number of passkeys for your account.</td>
          <td><code>error\_passkey-enrollment-max-allowed-reached</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="passkey-enrollment-local">
    ## Screen: passkey-enrollment-local

    <Frame>![passkey-enrollment-local reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/passkey-enrollment-local.png)</Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Create a passkey for <code>\$\{clientName}</code> on this device.</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Log in <code>\$\{clientName}</code>.</td>
          <td><code>pageTitle</code></td>
        </tr>

        <tr>
          <td>Log in to <code>$\{companyName}</code> to continue to <code>$\{clientName}</code>.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Sign in quickly with this device.</td>
          <td><code>passkeyBenefit1Title</code></td>
        </tr>

        <tr>
          <td>Lock</td>
          <td><code>passkeyBenefit1ImgAltText</code></td>
        </tr>

        <tr>
          <td>You won't need to use another device's passkey next time you sign in.</td>
          <td><code>passkeyBenefit1Description</code></td>
        </tr>

        <tr>
          <td>No need to remember a password.</td>
          <td><code>passkeyBenefit2Title</code></td>
        </tr>

        <tr>
          <td>Webauthn platform icon.</td>
          <td><code>passkeyBenefit2ImgAltText</code></td>
        </tr>

        <tr>
          <td>With passkeys, you can use things like your fingerprint or face to login.</td>
          <td><code>passkeyBenefit2Description</code></td>
        </tr>

        <tr>
          <td>Create a new passkey.</td>
          <td><code>createButtonText</code></td>
        </tr>

        <tr>
          <td>Continue without a new passkey.</td>
          <td><code>continueButtonText</code></td>
        </tr>

        <tr>
          <td>Don't show me this again.</td>
          <td><code>checkboxText</code></td>
        </tr>

        <tr>
          <td>Something went wrong. Please try again later.</td>
          <td><code>error\_passkey-enrollment-failure</code></td>
        </tr>

        <tr>
          <td>You have created the maximum number of passkeys for your account.</td>
          <td><code>error\_passkey-enrollment-max-allowed-reached</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="phone-identifier-challenge">
    ## Screen: phone-identifier-challenge

    <Frame>
      <img alt="phone-identifier-challenge reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Enter your phone code to log in</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>We've sent a text message to:</td>
          <td><code>smsDescription</code></td>
        </tr>

        <tr>
          <td>We've sent a 6-digit code via voice phone call to the following phone number:</td>
          <td><code>voiceDescription</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backButtonText</code></td>
        </tr>

        <tr>
          <td>Enter the 6-digit code</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>Resend</td>
          <td><code>resendActionText</code></td>
        </tr>

        <tr>
          <td>Didn't receive a code?</td>
          <td><code>resendText</code></td>
        </tr>

        <tr>
          <td>or</td>
          <td><code>resendVoiceActionSeparatorTextBefore</code></td>
        </tr>

        <tr>
          <td>or</td>
          <td><code>resendSmsActionSeparatorTextBefore</code></td>
        </tr>

        <tr>
          <td>send a text</td>
          <td><code>resendSmsActionText</code></td>
        </tr>

        <tr>
          <td>get a call</td>
          <td><code>resendVoiceActionText</code></td>
        </tr>

        <tr>
          <td>\<%= "\$\{companyName}" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Code has been resent.</td>
          <td><code>resendLimitReachedText</code></td>
        </tr>

        <tr>
          <td>OTP Code must have 6 numeric characters</td>
          <td><code>invalid-otp-code-format</code></td>
        </tr>

        <tr>
          <td>The code you entered is invalid</td>
          <td><code>invalid-code</code></td>
        </tr>

        <tr>
          <td>There was a problem making the voice call</td>
          <td><code>send-voice-failed</code></td>
        </tr>

        <tr>
          <td>There was a problem sending the SMS</td>
          <td><code>send-sms-failed</code></td>
        </tr>

        <tr>
          <td>We couldn't verify the code. Please try again later.</td>
          <td><code>authenticator-error</code></td>
        </tr>

        <tr>
          <td>We couldn't make the voice call. Please try again later.</td>
          <td><code>voice-authenticator-error</code></td>
        </tr>

        <tr>
          <td>We couldn't send the SMS. Please try again later.</td>
          <td><code>sms-authenticator-error</code></td>
        </tr>

        <tr>
          <td>Notification was not sent. Try resending the code.</td>
          <td><code>no-transaction-in-progress</code></td>
        </tr>

        <tr>
          <td>Too many failed codes. Wait for some minutes before retrying.</td>
          <td><code>too-many-failures</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-voice</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-sms</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="phone-identifier-enrollment">
    ## Screen: phone-identifier-enrollment

    <Frame>
      <img alt="phone-identifier-enrollment reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Use your phone number to log in</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Verify Your Identity</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>We will send a 6-digit code to the following phone number:</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>continueButtonText</code></td>
        </tr>

        <tr>
          <td>Choose another phone number.</td>
          <td><code>changePhoneText</code></td>
        </tr>

        <tr>
          <td>Text message</td>
          <td><code>smsButtonText</code></td>
        </tr>

        <tr>
          <td>Voice call</td>
          <td><code>voiceButtonText</code></td>
        </tr>

        <tr>
          <td>How do you want to receive the code?</td>
          <td><code>chooseMessageTypeText</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backButtonText</code></td>
        </tr>

        <tr>
          <td>Enter your phone number</td>
          <td><code>placeholder</code></td>
        </tr>

        <tr>
          <td>\<%= "\$\{companyName}" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>There was a problem sending the SMS</td>
          <td><code>send-sms-failed</code></td>
        </tr>

        <tr>
          <td>There was a problem making the voice call</td>
          <td><code>send-voice-failed</code></td>
        </tr>

        <tr>
          <td>Phone number can only include digits.</td>
          <td><code>invalid-phone-format</code></td>
        </tr>

        <tr>
          <td>It seems that your phone number is not valid. Please check and retry.</td>
          <td><code>invalid-phone</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-sms</code></td>
        </tr>

        <tr>
          <td>You have exceeded the maximum number of phone messages per hour. Wait a few minutes and try again.</td>
          <td><code>too-many-voice</code></td>
        </tr>

        <tr>
          <td>Your enrollment transaction expired, you will need to start again.</td>
          <td><code>transaction-not-found</code></td>
        </tr>

        <tr>
          <td>Please enter a phone number</td>
          <td><code>no-phone</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="signup">
    ## Screen: signup

    <Frame>![signup reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/signup.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Sign up</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Welcome</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Sign Up to \<%= "\$\{companyName}" %> to continue to \<%= "\$" %>.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Or</td>
          <td><code>separatorText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Email address</td>
          <td><code>emailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Continue with \<%= "" %></td>
          <td><code>federatedConnectionButtonText</code></td>
        </tr>

        <tr>
          <td>Log in</td>
          <td><code>loginActionLinkText</code></td>
        </tr>

        <tr>
          <td>Already have an account?</td>
          <td><code>loginActionText</code></td>
        </tr>

        <tr>
          <td>Password</td>
          <td><code>passwordPlaceholder</code></td>
        </tr>

        <tr>
          <td>Your password must contain:</td>
          <td><code>passwordSecurityText</code></td>
        </tr>

        <tr>
          <td>Username</td>
          <td><code>usernamePlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone number</td>
          <td><code>phonePlaceholder</code></td>
        </tr>

        <tr>
          <td>Email address (Optional)</td>
          <td><code>emailOptionalPlaceholder</code></td>
        </tr>

        <tr>
          <td>Username (Optional)</td>
          <td><code>usernameOptionalPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone number (Optional)</td>
          <td><code>phoneOptionalPlaceholder</code></td>
        </tr>

        <tr>
          <td>\<%= "\$\{companyName}" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Show password</td>
          <td><code>showPasswordText</code></td>
        </tr>

        <tr>
          <td>Hide password</td>
          <td><code>hidePasswordText</code></td>
        </tr>

        <tr>
          <td>Fail</td>
          <td><code>accessibilityError</code></td>
        </tr>

        <tr>
          <td>Pass</td>
          <td><code>accessibilityValid</code></td>
        </tr>

        <tr>
          <td>The user already exists.</td>
          <td><code>email-in-use</code></td>
        </tr>

        <tr>
          <td>The password is too weak</td>
          <td><code>password-too-weak</code></td>
        </tr>

        <tr>
          <td>The password is too weak</td>
          <td><code>password-policy-not-conformant</code></td>
        </tr>

        <tr>
          <td>The password is too common</td>
          <td><code>password-too-common</code></td>
        </tr>

        <tr>
          <td>Password has previously been used</td>
          <td><code>password-previously-used</code></td>
        </tr>

        <tr>
          <td>Passwords don't match</td>
          <td><code>password-mismatch</code></td>
        </tr>

        <tr>
          <td>Password contains user information</td>
          <td><code>password-contains-user-information</code></td>
        </tr>

        <tr>
          <td>Username can only contain alphanumeric characters or: '\<%= "${characters}" %&gt;'. Username should have between &lt;%= "$" %> and \<%= "\$" %> characters.</td>
          <td><code>invalid-username</code></td>
        </tr>

        <tr>
          <td>The username must not be longer than \<%= "\$" %> characters.</td>
          <td><code>invalid-username-max-length</code></td>
        </tr>

        <tr>
          <td>The username must have at least \<%= "\$" %> characters.</td>
          <td><code>invalid-username-min-length</code></td>
        </tr>

        <tr>
          <td>The username has invalid characters.</td>
          <td><code>invalid-username-invalid-characters</code></td>
        </tr>

        <tr>
          <td>The username cannot be an email.</td>
          <td><code>invalid-username-email-not-allowed</code></td>
        </tr>

        <tr>
          <td>The username provided is in use already.</td>
          <td><code>username-taken</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>custom-script-error-code</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later</td>
          <td><code>auth0-users-validation</code></td>
        </tr>

        <tr>
          <td>Invalid connection</td>
          <td><code>invalid-connection</code></td>
        </tr>

        <tr>
          <td>We have detected suspicious login behavior and further attempts will be blocked. Please contact the administrator.</td>
          <td><code>ip-blocked</code></td>
        </tr>

        <tr>
          <td>Too many signups from the same IP</td>
          <td><code>ip-signup-blocked</code></td>
        </tr>

        <tr>
          <td>Invalid connection</td>
          <td><code>no-db-connection</code></td>
        </tr>

        <tr>
          <td>Please enter an email address</td>
          <td><code>no-email</code></td>
        </tr>

        <tr>
          <td>Password is required</td>
          <td><code>no-password</code></td>
        </tr>

        <tr>
          <td>Enter a new password.</td>
          <td><code>no-password-reset</code></td>
        </tr>

        <tr>
          <td>New password confirmation is missing</td>
          <td><code>no-re-enter-password</code></td>
        </tr>

        <tr>
          <td>Username is required</td>
          <td><code>no-username</code></td>
        </tr>

        <tr>
          <td>At least one identifier is required</td>
          <td><code>no-identifier</code></td>
        </tr>

        <tr>
          <td>This combination of credentials was detected in a public data breach on another website. Before your account is created, please use a different password to keep it secure.</td>
          <td><code>password-breached</code></td>
        </tr>

        <tr>
          <td>We encountered an issue when attempting to sign up with a phone number. Please contact support for assistance.</td>
          <td><code>invalid-phone-attribute-config</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="signup-id">
    ## Screen: signup-id

    <Frame>![signup-id reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/signup-id.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Sign up</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Create Your Account</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Sign Up to \<%= "\$\{companyName}" %> to continue to \<%= "\$" %>.</td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Or</td>
          <td><code>separatorText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Phone number</td>
          <td><code>phonePlaceholder</code></td>
        </tr>

        <tr>
          <td>Email address</td>
          <td><code>emailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Continue with \<%= "" %></td>
          <td><code>federatedConnectionButtonText</code></td>
        </tr>

        <tr>
          <td>Log in</td>
          <td><code>loginActionLinkText</code></td>
        </tr>

        <tr>
          <td>Already have an account?</td>
          <td><code>loginActionText</code></td>
        </tr>

        <tr>
          <td>Password</td>
          <td><code>passwordPlaceholder</code></td>
        </tr>

        <tr>
          <td>Your password must contain:</td>
          <td><code>passwordSecurityText</code></td>
        </tr>

        <tr>
          <td>Username</td>
          <td><code>usernamePlaceholder</code></td>
        </tr>

        <tr>
          <td>Email address (Optional)</td>
          <td><code>emailOptionalPlaceholder</code></td>
        </tr>

        <tr>
          <td>Username (Optional)</td>
          <td><code>usernameOptionalPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone number (Optional)</td>
          <td><code>phoneOptionalPlaceholder</code></td>
        </tr>

        <tr>
          <td>\<%= "\$\{companyName}" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>The user already exists.</td>
          <td><code>email-in-use</code></td>
        </tr>

        <tr>
          <td>The password is too weak</td>
          <td><code>password-too-weak</code></td>
        </tr>

        <tr>
          <td>The password is too weak</td>
          <td><code>password-policy-not-conformant</code></td>
        </tr>

        <tr>
          <td>The password is too common</td>
          <td><code>password-too-common</code></td>
        </tr>

        <tr>
          <td>Password has previously been used</td>
          <td><code>password-previously-used</code></td>
        </tr>

        <tr>
          <td>Passwords don't match</td>
          <td><code>password-mismatch</code></td>
        </tr>

        <tr>
          <td>Username can only contain alphanumeric characters or: '\<%= "${characters}" %&gt;'. Username should have between &lt;%= "$" %> and \<%= "\$" %> characters.</td>
          <td><code>invalid-username</code></td>
        </tr>

        <tr>
          <td>The username must not be longer than \<%= "\$" %> characters.</td>
          <td><code>invalid-username-max-length</code></td>
        </tr>

        <tr>
          <td>The username must have at least \<%= "\$" %> characters.</td>
          <td><code>invalid-username-min-length</code></td>
        </tr>

        <tr>
          <td>The username has invalid characters.</td>
          <td><code>invalid-username-invalid-characters</code></td>
        </tr>

        <tr>
          <td>The username cannot be an email.</td>
          <td><code>invalid-username-email-not-allowed</code></td>
        </tr>

        <tr>
          <td>The username provided is in use already.</td>
          <td><code>username-taken</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>custom-script-error-code</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later</td>
          <td><code>auth0-users-validation</code></td>
        </tr>

        <tr>
          <td>Invalid connection</td>
          <td><code>invalid-connection</code></td>
        </tr>

        <tr>
          <td>We have detected suspicious login behavior and further attempts will be blocked. Please contact the administrator.</td>
          <td><code>ip-blocked</code></td>
        </tr>

        <tr>
          <td>Too many signups from the same IP</td>
          <td><code>ip-signup-blocked</code></td>
        </tr>

        <tr>
          <td>Invalid connection</td>
          <td><code>no-db-connection</code></td>
        </tr>

        <tr>
          <td>Email does not match any enterprise directory</td>
          <td><code>no-hrd-connection</code></td>
        </tr>

        <tr>
          <td>Please enter an email address</td>
          <td><code>no-email</code></td>
        </tr>

        <tr>
          <td>Password is required</td>
          <td><code>no-password</code></td>
        </tr>

        <tr>
          <td>Enter a new password.</td>
          <td><code>no-password-reset</code></td>
        </tr>

        <tr>
          <td>New password confirmation is missing</td>
          <td><code>no-re-enter-password</code></td>
        </tr>

        <tr>
          <td>Username is required</td>
          <td><code>no-username</code></td>
        </tr>

        <tr>
          <td>At least one identifier is required</td>
          <td><code>no-identifier</code></td>
        </tr>

        <tr>
          <td>Enter a valid phone number</td>
          <td><code>invalid-phone-number</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="signup-password">
    ## Screen: signup-password

    <Frame>![signup-password reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/signup-password.png)</Frame>

    <table>
      <thead>
        <tr>
          <th>Text</th>
          <th>Key</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Create a password to sign up</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Create Your Account</td>
          <td><code>title</code></td>
        </tr>

        <tr>
          <td>Set your password for \<%= "\$\{companyName}" %> to continue to \<%= "\$" %></td>
          <td><code>description</code></td>
        </tr>

        <tr>
          <td>Or</td>
          <td><code>separatorText</code></td>
        </tr>

        <tr>
          <td>Continue</td>
          <td><code>buttonText</code></td>
        </tr>

        <tr>
          <td>Phone number</td>
          <td><code>phonePlaceholder</code></td>
        </tr>

        <tr>
          <td>Email address</td>
          <td><code>emailPlaceholder</code></td>
        </tr>

        <tr>
          <td>Edit</td>
          <td><code>editEmailText</code></td>
        </tr>

        <tr>
          <td>Edit</td>
          <td><code>editPhoneText</code></td>
        </tr>

        <tr>
          <td>Edit</td>
          <td><code>editUsernameText</code></td>
        </tr>

        <tr>
          <td>Edit email address</td>
          <td><code>editLinkScreenReadableText</code></td>
        </tr>

        <tr>
          <td>Continue with \<%= "" %></td>
          <td><code>federatedConnectionButtonText</code></td>
        </tr>

        <tr>
          <td>Log in</td>
          <td><code>loginActionLinkText</code></td>
        </tr>

        <tr>
          <td>Already have an account?</td>
          <td><code>loginActionText</code></td>
        </tr>

        <tr>
          <td>Password</td>
          <td><code>passwordPlaceholder</code></td>
        </tr>

        <tr>
          <td>Your password must contain:</td>
          <td><code>passwordSecurityText</code></td>
        </tr>

        <tr>
          <td>Username</td>
          <td><code>usernamePlaceholder</code></td>
        </tr>

        <tr>
          <td>Email address (Optional)</td>
          <td><code>emailOptionalPlaceholder</code></td>
        </tr>

        <tr>
          <td>Username (Optional)</td>
          <td><code>usernameOptionalPlaceholder</code></td>
        </tr>

        <tr>
          <td>Phone number (Optional)</td>
          <td><code>phoneOptionalPlaceholder</code></td>
        </tr>

        <tr>
          <td>Go back</td>
          <td><code>backButtonText</code></td>
        </tr>

        <tr>
          <td>Accept your invitation to sign up</td>
          <td>\<%= "\$" %></td>
        </tr>

        <tr>
          <td>Sign Up to accept \<%= "${inviterName}" %&gt;'s invitation to join &lt;%= "\$\{companyName}" %> on \<%= "\$" %>.</td>
          <td><code>invitationDescription</code></td>
        </tr>

        <tr>
          <td>\<%= "\$\{companyName}" %></td>
          <td><code>logoAltText</code></td>
        </tr>

        <tr>
          <td>Show password</td>
          <td><code>showPasswordText</code></td>
        </tr>

        <tr>
          <td>Hide password</td>
          <td><code>hidePasswordText</code></td>
        </tr>

        <tr>
          <td>Fail</td>
          <td><code>accessibilityError</code></td>
        </tr>

        <tr>
          <td>Pass</td>
          <td><code>accessibilityValid</code></td>
        </tr>

        <tr>
          <td>The user already exists.</td>
          <td><code>email-in-use</code></td>
        </tr>

        <tr>
          <td>The password is too weak</td>
          <td><code>password-too-weak</code></td>
        </tr>

        <tr>
          <td>The password is too weak</td>
          <td><code>password-policy-not-conformant</code></td>
        </tr>

        <tr>
          <td>The password is too common</td>
          <td><code>password-too-common</code></td>
        </tr>

        <tr>
          <td>Password has previously been used</td>
          <td><code>password-previously-used</code></td>
        </tr>

        <tr>
          <td>Passwords don't match</td>
          <td><code>password-mismatch</code></td>
        </tr>

        <tr>
          <td>Password contains user information</td>
          <td><code>password-contains-user-information</code></td>
        </tr>

        <tr>
          <td>Username can only contain alphanumeric characters or: '\<%= "${characters}" %&gt;'. Username should have between &lt;%= "$" %> and \<%= "\$" %> characters.</td>
          <td><code>invalid-username</code></td>
        </tr>

        <tr>
          <td>The username must not be longer than \<%= "\$" %> characters.</td>
          <td><code>invalid-username-max-length</code></td>
        </tr>

        <tr>
          <td>The username must have at least \<%= "\$" %> characters.</td>
          <td><code>invalid-username-min-length</code></td>
        </tr>

        <tr>
          <td>The username has invalid characters.</td>
          <td><code>invalid-username-invalid-characters</code></td>
        </tr>

        <tr>
          <td>The username cannot be an email.</td>
          <td><code>invalid-username-email-not-allowed</code></td>
        </tr>

        <tr>
          <td>The username provided is in use already.</td>
          <td><code>username-taken</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>custom-script-error-code</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later</td>
          <td><code>auth0-users-validation</code></td>
        </tr>

        <tr>
          <td>Invalid connection</td>
          <td><code>invalid-connection</code></td>
        </tr>

        <tr>
          <td>We have detected suspicious login behavior and further attempts will be blocked. Please contact the administrator.</td>
          <td><code>ip-blocked</code></td>
        </tr>

        <tr>
          <td>Too many signups from the same IP</td>
          <td><code>ip-signup-blocked</code></td>
        </tr>

        <tr>
          <td>Invalid connection</td>
          <td><code>no-db-connection</code></td>
        </tr>

        <tr>
          <td>Please enter an email address</td>
          <td><code>no-email</code></td>
        </tr>

        <tr>
          <td>Password is required</td>
          <td><code>no-password</code></td>
        </tr>

        <tr>
          <td>Enter a new password.</td>
          <td><code>no-password-reset</code></td>
        </tr>

        <tr>
          <td>New password confirmation is missing</td>
          <td><code>no-re-enter-password</code></td>
        </tr>

        <tr>
          <td>Username is required</td>
          <td><code>no-username</code></td>
        </tr>

        <tr>
          <td>Enter a valid phone number</td>
          <td><code>invalid-phone-number</code></td>
        </tr>

        <tr>
          <td>This combination of credentials was detected in a public data breach on another website. Before your account is created, please use a different password to keep it secure.</td>
          <td><code>password-breached</code></td>
        </tr>

        <tr>
          <td>We encountered an issue when attempting to sign up with a phone number. Please contact support for assistance.</td>
          <td><code>invalid-phone-attribute-config</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="status">
    ## Screen: status

    <Frame>
      <img alt="status reference screenshot" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th><strong>Text</strong></th>
          <th><strong>Key</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Something Went Wrong</td>
          <td><code>passwordless-no-session-title</code></td>
        </tr>

        <tr>
          <td>The link must be opened on the same device and browser from which you submitted your email address.</td>
          <td><code>passwordless-no-session</code></td>
        </tr>

        <tr>
          <td>Start over from this device or browser</td>
          <td><code>passwordless-no-session-link</code></td>
        </tr>

        <tr>
          <td>Something Went Wrong</td>
          <td><code>mfa-required-title</code></td>
        </tr>

        <tr>
          <td>Two-factor authentication is required to access this application. To enable this, please contact your system administrator.</td>
          <td><code>mfa-required</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>custom-script-error-code</code></td>
        </tr>

        <tr>
          <td>Something went wrong, please try again later.</td>
          <td><code>auth0-users-validation</code></td>
        </tr>

        <tr>
          <td>We are sorry, something went wrong when attempting to log in</td>
          <td><code>authentication-failure</code></td>
        </tr>
      </tbody>
    </table>
  </Accordion>
</AccordionGroup>

## Variables

Some screens have variables in the text that are replaced at runtime based on contextual information. As different variables are available for each screen, it is not guaranteed that a given variable will work anywhere other than their original screen.

<table>
  <thead>
    <tr>
      <th><strong>Variable</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>\$\{clientName}</td>
      <td>Auth0 Application Name</td>
    </tr>

    <tr>
      <td>\$\{connectionName}</td>
      <td>Connection Name (e.g. Google)</td>
    </tr>

    <tr>
      <td>\$\{tenantName}</td>
      <td>Auth0 Tenant name</td>
    </tr>

    <tr>
      <td>\$\{organizationName}</td>
      <td>Name of the user’s organization if the user is authenticating in the context of an Organization</td>
    </tr>

    <tr>
      <td>\$\{companyName}</td>
      <td>Auth0 Tenant name, or Organization name if the user is authenticating in the context of an Organization</td>
    </tr>

    <tr>
      <td>\$\{userName}</td>
      <td>Name of the logged user</td>
    </tr>

    <tr>
      <td>\$\{email}</td>
      <td>Email of the logged user</td>
    </tr>

    <tr>
      <td>\$\{appName}</td>
      <td>Name of the custom Guardian Push application</td>
    </tr>
  </tbody>
</table>

## Learn more

* [Universal Login Experience](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience)
* [Universal Login Internationalization](/docs/customize/internationalization-and-localization/universal-login-internationalization)
* [Customize Universal Login Page Templates](/docs/customize/login-pages/universal-login/customize-templates)


# Customize Universal Login Page Themes
Source: https://auth0.com/docs/customize/login-pages/universal-login/customize-themes

Describes how to use the no-code editor to customize themes for Universal Login pages.

You can create a consistently branded login experience for your users by styling your <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> prompts. With the Universal Login no-code editor, you can easily customize the colors, fonts, borders, and backgrounds of the prompts displayed to users throughout the login flow.

The no-code editor allows you to customize your Universal Login branding theme. To customize the text included in each prompt, review [Customize Universal Login Text Elements](/docs/customize/login-pages/universal-login/customize-text-elements). For expanded customization capabilities, review [Customize Universal Login Page Templates](/docs/customize/login-pages/universal-login/customize-templates).

<Callout icon="file-lines">
  To leverage the no-code editor, you must have [Universal Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience) enabled. The Classic Login experience does not support this editor.
</Callout>

## Universal Login no-code editor

To customize your Universal Login theme, follow the steps below:

1. On the Auth0 Dashboard, navigate to [Branding > Universal Login > Customization Options](https://manage.auth0.com/#/universal-login/customizations/colors).
2. Select a [theme component](#theme-components) (e.g., Colors) from the Styles menu. Then, customize the options listed to the right.
3. After customizing your theme, select **Save and Publish**.

After you save your theme, you can access a live preview of your login experience to review and test your screens. To launch the preview in a new tab, select **Try** above the no-code editor.

<Frame>
  <img alt="" />
</Frame>

### Theme components

To create your desired Universal Login theme, the Styles menu contains the following components:

<AccordionGroup>
  <Accordion title="Color">
    Select an input field to change the color of the element. To choose specific colors, you can:

    * Use the color picker.
    * Input the Hex code or RGB value.
    * Select the eyedropper tool to choose a color from your screen for the available elements.

    <Frame>
      <img alt="" />
    </Frame>

    <table>
      <thead>
        <tr>
          <th>Element</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Primary button</td>
          <td>Fills primary button, or button that triggers the next action, with color choice.</td>
        </tr>

        <tr>
          <td>Primary button label</td>
          <td>Changes color of text within primary button.</td>
        </tr>

        <tr>
          <td>Secondary button border</td>
          <td>Changes border on input fields.</td>
        </tr>

        <tr>
          <td>Secondary button label</td>
          <td>Changes text within clickable secondary fields.</td>
        </tr>

        <tr>
          <td>Links and focused components</td>
          <td>Changes text color of links that lead users to trigger another workflow, such as reset password or try another authentication method.</td>
        </tr>

        <tr>
          <td>Base focus color</td>
          <td>Changes the color of buttons when the mouse hovers over the button before selection.</td>
        </tr>

        <tr>
          <td>Base hover color</td>
          <td>Changes the color of a button when user clicks on it.</td>
        </tr>

        <tr>
          <td>Header</td>
          <td>Changes the text color of the title in the header.</td>
        </tr>

        <tr>
          <td>Body text</td>
          <td>Changes the text color of body text.</td>
        </tr>

        <tr>
          <td>Widget background</td>
          <td>Changes the background color of widgets.</td>
        </tr>

        <tr>
          <td>Widget border</td>
          <td>Changes the border color of the widgets.</td>
        </tr>

        <tr>
          <td>Input labels and placeholders</td>
          <td>Changes the text of input field labels and placeholder text.</td>
        </tr>

        <tr>
          <td>Input filled text</td>
          <td>Changes text color users type in input fields. For example, username and password fields.</td>
        </tr>

        <tr>
          <td>Input border</td>
          <td>Changes border color of input fields.</td>
        </tr>

        <tr>
          <td>Input background</td>
          <td>Changes background color of input fields.</td>
        </tr>

        <tr>
          <td>Icons</td>
          <td>Changes color of icons inside input fields.</td>
        </tr>

        <tr>
          <td>Error</td>
          <td>Changes color of error messages within widgets.</td>
        </tr>

        <tr>
          <td>Success</td>
          <td>Changes color of success message within widgets.</td>
        </tr>
      </tbody>
    </table>

    Once you make a change, the preview window displays several examples of the widgets with your specified changes.

    <Frame>
      <img alt="" />
    </Frame>
  </Accordion>

  <Accordion title="Fonts">
    To change the default font, enter the URL to any WOFF (Web Open Font Format) file in the input field. Your WOFF files need to be hosted using a CDN with CORS enabled or a hosting site with Access-Control-Allow-Origin header.

    Under the font URL panel, adjust the general text size under the **Reference text size** pixel option. You should note the rest of the options do not change when the reference text is changed.

    Change the following elements individually:

    * Title
    * Subtitle
    * Body Text
    * Button Text
    * Input Labels
    * Links

    When you select an option to configure, the preview pane displays the location of the element on the widget and adjusts to the specified size.

    <Frame>
      <img alt="" />
    </Frame>
  </Accordion>

  <Accordion title="Borders">
    To customize the borders, buttons styles, input fields, and widget corners adjust the slider or choose from the available options.

    <table>
      <thead>
        <tr>
          <th>Option</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Button border weight</td>
          <td>Adjusts width of border around input fields inside login prompts.</td>
        </tr>

        <tr>
          <td>Buttons style</td>
          <td>Changes shape of clickable buttons inside widgets. Available options are: sharp corners, rounded corners, or pill-shaped style.</td>
        </tr>

        <tr>
          <td>Button border radius</td>
          <td>Adjusts corners of clickable buttons when you select rounded corners.</td>
        </tr>

        <tr>
          <td>Input border weight</td>
          <td>Adjusts width of borders of input fields and clickable buttons inside login prompts.</td>
        </tr>

        <tr>
          <td>Inputs style</td>
          <td>Changes shape of input fields inside login prompts. Available options are: sharp corners, rounded corners, or pill-shaped style.</td>
        </tr>

        <tr>
          <td>Input border radius</td>
          <td>Adjusts corners of input fields when you select rounded corners.</td>
        </tr>

        <tr>
          <td>Widget corner radius</td>
          <td>Changes shape of the widget from sharp to rounded corners.</td>
        </tr>

        <tr>
          <td>Widget border weight</td>
          <td>Adjusts width of widget border.</td>
        </tr>

        <tr>
          <td>Shadow</td>
          <td>Checkbox to allow widgets to have a shadow.</td>
        </tr>
      </tbody>
    </table>

    <Frame>
      <img alt="" />
    </Frame>
  </Accordion>

  <Accordion title="Widget">
    Add the URL of your logo to configure the position, height, text alignment, and social login location.

    <table>
      <thead>
        <tr>
          <th>Element</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Logo position</td>
          <td>Choose the location of the widget to be on the left, right, or center of the page. You can also choose to hide the logo.</td>
        </tr>

        <tr>
          <td>Logo URL</td>
          <td>Enter the URL location of your custom logo. Auth0 recommends SVG files.</td>
        </tr>

        <tr>
          <td>Logo Height</td>
          <td>Adjust the size of your logo at the top of the widget.</td>
        </tr>

        <tr>
          <td>Header Text Alignment</td>
          <td>Choose if text within the header should be left, right, or center justified.</td>
        </tr>

        <tr>
          <td>Social Buttons Layout</td>
          <td>Choose if text should be at the top or bottom of the button.</td>
        </tr>
      </tbody>
    </table>

    <Frame>
      <img alt="" />
    </Frame>
  </Accordion>

  <Accordion title="Page backgrounds">
    Add a background image URL to choose a background to display in the prompt widget. The No-Code Editor supports other image formats such as PNGs and JPEGs.

    <Callout icon="file-lines">
      Auth0 recommends you use a JPEG image format at least 2000px wide.
    </Callout>

    Then, choose if the widget aligns center, left, or right on the screen.

    <Frame>
      <img alt="" />
    </Frame>
  </Accordion>
</AccordionGroup>

## Management API

You can also customize your Universal Login theme with the [Management API](https://auth0.com/docs/api/management/v2). Specifically, you can use the Branding endpoints to:

* [Create a new branding theme](https://auth0.com/docs/api/management/v2/branding/post-branding-theme)
* [Retrieve the default branding theme](https://auth0.com/docs/api/management/v2/branding/get-default-branding-theme)
* [Retrieve a specific branding theme](https://auth0.com/docs/api/management/v2/branding/get-branding-theme)
* [Delete a branding theme](https://auth0.com/docs/api/management/v2/branding/delete-branding-theme)
* [Update the current theme](https://auth0.com/docs/api/management/v2/branding/patch-branding-theme)


# Access Control
Source: https://auth0.com/docs/manage-users/access-control

Explore topics related to access control, including role-based access control (RBAC), authorization policies, and the differences between Auth0's core authorization feature and the authorization extension.

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/manage-users/access-control/rbac">Role-Based Access Control</a></td>
      <td>About the concept of role-based access control and how it applies in Auth0.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/access-control/authorization-policies">Authorization Policies</a></td>
      <td>About the concept of authorization policies and how they apply in Auth0.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/access-control/rules-for-authorization-policies">Rules for Authorization Policies</a></td>
      <td>How rules apply to authorization policies and Auth0's role-based access control (RBAC) system.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/access-control/sample-use-cases-role-based-access-control">Sample Use Cases: Role-Based Access Control</a></td>
      <td>How to implement roles-based authorization (RBAC) in different scenarios and explore how to use rules with RBAC.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/access-control/sample-use-cases-actions-with-authorization">Sample Use Cases: Actions with Authorization</a></td>
      <td>How to use actions with roles-based access control (RBAC). For use with our Authorization Core feature set.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/access-control/sample-use-cases-rules-with-authorization">Sample Use Cases: Rules with Authorization</a></td>
      <td>How to use rules with roles-based access control (RBAC). For use with our Authorization Core feature set.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/access-control/authorization-core-vs-authorization-extension">Authorization Core vs. Authorization Extension</a></td>
      <td>About the differences between Auth0's core RBAC release and the Authorization Extension.</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/access-control/configure-core-rbac">Configure Core RBAC</a></td>
      <td>How to configure Auth0 Core Authorization features for role-based access control (RBAC) of your APIs.</td>
    </tr>
  </tbody>
</table>


# Authorization Core vs. Authorization Extension
Source: https://auth0.com/docs/manage-users/access-control/authorization-core-vs-authorization-extension

Understand the differences between Auth0's core RBAC release and the Authorization Extension.

<Warning>
  We plan to deprecate Rules and Hooks in 2024, and at that time, Rules and Hooks-based Extensions will be out of support. We highly recommend that you migrate to Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience.

  To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life.](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/)
</Warning>

Auth0 currently provides two ways of implementing [role-based access control (RBAC)](/docs/manage-users/access-control/rbac): our Core implementation and our Authorization Extension. Our Core implementation improves performance and scalability.

We recommend using Authorization Core for most implementations. If you are looking to represent teams, business customers, or partners in a B2B or SaaS application, we recommend representing them as [Organizations](/docs/manage-users/organizations/organizations-overview) and using Authorization Core. The Authorization Extension does not have support for Organizations.

To help you decide which feature is right for your implementation, we present the differences between the two:

| Feature                                                                  | Authorization Core                                                                                             | Authorization Extension                                                                                                                                             |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Enhanced performance and scalability                                     | Yes - Read [Entity Limit Policy](/docs/troubleshoot/customer-support/operational-policies/entity-limit-policy) | No - Limited to 500KB of data (1000 groups, 3000 users, where each user is a member of 3 groups; or 20 groups, 7000 users, where each user is a member of 3 groups) |
| Create/edit/delete Roles                                                 | Yes                                                                                                            | Yes                                                                                                                                                                 |
| Roles can contain permissions from one or more APIs                      | Yes                                                                                                            | No                                                                                                                                                                  |
| Users and Roles can be assigned to Groups                                | No                                                                                                             | Yes                                                                                                                                                                 |
| Roles are attached to specific applications                              | No                                                                                                             | Yes                                                                                                                                                                 |
| Create/edit/delete Users                                                 | Yes                                                                                                            | Yes                                                                                                                                                                 |
| Search Users by user, email, connection                                  | Yes                                                                                                            | Yes                                                                                                                                                                 |
| Search Users by identity provider, login count, last login, phone number | Yes                                                                                                            | No                                                                                                                                                                  |
| Search Users using Lucene syntax                                         | Yes                                                                                                            | No                                                                                                                                                                  |
| User import/export via JSON                                              | Not currently                                                                                                  | Yes                                                                                                                                                                 |
| Create custom authorization policies                                     | Yes                                                                                                            | No                                                                                                                                                                  |

## Learn more

* [Authorization Policies](/docs/manage-users/access-control/authorization-policies)
* [Configure Core Authorization Features for Role-Based Access Control](/docs/manage-users/access-control/configure-core-rbac)
* [Entity Limit Policy](/docs/troubleshoot/customer-support/operational-policies/entity-limit-policy)
* [Authorization Extension](/docs/customize/extensions/authorization-extension)
* [Troubleshoot Authorization Extension](/docs/troubleshoot/authentication-issues/troubleshoot-authorization-extension)
* [Troubleshoot Role-Based Access Control and Authorization](/docs/troubleshoot/authentication-issues/troubleshoot-rbac-authorization)


# Authorization Policies
Source: https://auth0.com/docs/manage-users/access-control/authorization-policies

Understand the concept of authorization policies and how they apply in Auth0.

Behind the scenes, role-based authorization uses a pre-configured authorization policy, which contains conditions that allow code to evaluate whether a user should be permitted to access a protected API.

The authorization policy determines:

* how to define and organize the users or roles that are affected by the policy
* what logic and conditions apply to the policy and whether their outcome permits or denies access

When using Auth0's core authorization and [role-based access control (RBAC)](/docs/manage-users/access-control/rbac), the policy includes evaluating the roles and permissions assigned to users. To use these features, you must [enable role-based access control for APIs](/docs/get-started/apis/enable-role-based-access-control-for-apis).

You can further customize the authorization policy by using [rules](/docs/customize/rules). To learn more, read [Rules for Authorization Policies](/docs/manage-users/access-control/rules-for-authorization-policies).


# Configure Core Authorization Features for Role-Based Access Control
Source: https://auth0.com/docs/manage-users/access-control/configure-core-rbac

Learn how to configure Auth0 Core Authorization features for role-based access control (RBAC) of your APIs.

The core Authorization features of Auth0 allow for role-based access control (RBAC) of your APIs.

For RBAC to work properly, you must enable it for your API using either the Dashboard or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. To learn more, read [Enable Role-Based Access Control for APIs](/docs/get-started/apis/enable-role-based-access-control-for-apis).

Authorization Core functionality is different from the Authorization Extension. For a comparison between the two products, read [Authorization Core vs. Authorization Extension](/docs/manage-users/access-control/authorization-core-vs-authorization-extension).

To use the core functionality most efficiently, you should do the following:

1. [Register API with Auth0](/docs/get-started/auth0-overview/set-up-apis)
2. [Define permissions for API](/docs/get-started/apis/add-api-permissions)
3. [Create roles](/docs/manage-users/access-control/configure-core-rbac/roles/create-roles)
4. [Assign roles to users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/assign-roles-to-users)
5. [Assign permissions to users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/assign-permissions-to-users), if needed.

## Learn more

* [Enable Role-Based Access Control for APIs](/docs/get-started/apis/enable-role-based-access-control-for-apis)
* [Manage Role-Based Access Control Roles](/docs/manage-users/access-control/configure-core-rbac/roles)
* [Manage Role-Based Access Control Users](/docs/manage-users/access-control/configure-core-rbac/rbac-users)
* [Manage Role-Based Access Control Permissions](/docs/manage-users/access-control/configure-core-rbac/manage-permissions)


# Enable Role-Based Access Control for APIs
Source: https://auth0.com/docs/manage-users/access-control/configure-core-rbac/enable-role-based-access-control-for-apis

Learn how to enable role-based access control (RBAC) for an API using the Auth0 Dashboard or the Management API.

You can enable [role-based access control (RBAC)](/docs/manage-users/access-control/rbac) using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. This enables the API Authorization Core feature set.

When RBAC is enabled, the `scope` claim of the <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> 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, an application can request any permission defined for the API, and the `scope` claim includes all requested permissions.

<Callout icon="file-lines">
  If you configure any [Actions](/docs/customize/actions) that modify access token scopes, they will override the scopes set by RBAC.
</Callout>

## Dashboard

1. Go to [Dashboard > Applications > APIs](https://manage.auth0.com/#/apis) and click the name of the API to view.

   <Frame>
     <img alt="Dashboard Applications APIs List" />
   </Frame>
2. Scroll to **RBAC Settings** and enable the **Enable RBAC** toggle.

   <Frame>
     <img alt="Auth0 Dashboard API Settings RBAC toggle" />
   </Frame>
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.
   Once you’ve enabled the **Add Permissions in the Access Token** toggle, Auth0 also updates your token dialect based on the [access token profile](/docs/secure/tokens/access-tokens/access-token-profiles) you’ve set for the API:

   * If your token dialect is `access_token`, Auth0 updates it to `access_token_authz`, which is equivalent to the `access_token` profile with the `permissions` claim included.
   * If your token dialect is `rfc9068_profile`, Auth0 updates it to `rfc9068_profile_authz`, which is equivalent to the `rfc9068_profile` with the `permissions` claim included.

   To learn more about the available token dialects, read [Token dialect options](#token-dialect-options).

## Management API

To enable RBAC using the Management API, make a PATCH request to the [Update a resource server endpoint](https://auth0.com/docs/api/management/v2/resource-servers/patch-resource-servers-by-id). In the PATCH request, set `enforce_policies` to `true`:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/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" }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/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);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/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();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/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);
  });
  ```

  ```objc Obj-C theme={null}
  #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://{yourDomain}/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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/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;
  }
  ```

  ```python Python theme={null}
  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", "/{yourDomain}/api/v2/resource-servers/API_ID", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/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
  ```

  ```swift Swift theme={null}
  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://{yourDomain}/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()
  ```
</AuthCodeGroup>

Replace `API_ID`, `MGMT_API_ACCESS_TOKEN`, and `TOKEN_DIALECT` with their respective values, as shown in the following table:

| Parameter               | Description                                                                                                                      |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `API_ID`                | ID of the API for which you want to enable RBAC.                                                                                 |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](https://auth0.com/docs/api/management/v2/tokens) with the scope `update:resource_servers`. |
| `TOKEN_DIALECT`         | Dialect of the access token for the specified API. To learn more, read [Token dialect options](#token-dialect-options).          |

### Token dialect options

Auth0 supports the following token dialects:

| Value                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access_token`          | The Auth0 default token profile generates an access token formatted as a [JSON Web Token (JWT)](/docs/secure/tokens/json-web-tokens). 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. To learn more, read [Access Token Profiles](/docs/secure/tokens/access-tokens/access-token-profiles).                                                           |
| `access_token_authz`    | The Auth0 default token profile (`access_token`) with the `permissions` claim. 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.                                                                       |
| `rfc9068_profile`       | The RFC 9068 token profile generates an access token formatted as a JWT following the [IETF JWT Profile for OAuth 2.0 Access Tokens (RFC 9068)](https://datatracker.ietf.org/doc/html/rfc9068). 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. To learn more, read [Access Token Profiles](/docs/secure/tokens/access-tokens/access-token-profiles). |
| `rfc9068_profile_authz` | The RFC 9068 token profile (`rfc9068_profile`) with the `permissions` claim. 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.                                                                         |

## Learn more

* [Manage Role-Based Access Control Users](/docs/manage-users/access-control/configure-core-rbac/rbac-users)
* [Manage Role-Based Access Control Permissions](/docs/manage-users/access-control/configure-core-rbac/manage-permissions)
* [Sample Use Cases: Role-Based Access Control](/docs/manage-users/access-control/sample-use-cases-role-based-access-control)
* [Troubleshoot Role-Based Access Control and Authorization](/docs/troubleshoot/authentication-issues/troubleshoot-rbac-authorization)


# Manage Role-Based Access Control Permissions
Source: https://auth0.com/docs/manage-users/access-control/configure-core-rbac/manage-permissions

Learn how to manage permissions in a role-based access control (RBAC) system using the Auth0 Management Dashboard. For use with Auth0's API Authorization Core feature set.

This guide will show you how to manage permissions in a [role-based access control (RBAC)](/docs/manage-users/access-control/rbac) system. These permissions are used with the API Authorization Core feature set.

We provide various functions to help you manage your permissions, which you can access through either the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>:

* [Add API permissions](/docs/get-started/apis/add-api-permissions)
* [Delete API permissions](/docs/get-started/apis/delete-api-permissions)
* [Add permissions to roles](/docs/manage-users/access-control/configure-core-rbac/roles/add-permissions-to-roles)
* [Assign permissions to users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/assign-permissions-to-users)
* [View role permissions](/docs/manage-users/access-control/configure-core-rbac/roles/view-role-permissions)
* [View user permissions](/docs/manage-users/access-control/configure-core-rbac/rbac-users/view-user-permissions)
* [Remove role permissions](/docs/manage-users/access-control/configure-core-rbac/roles/remove-permissions-from-roles)
* [Remove user permissions](/docs/manage-users/access-control/configure-core-rbac/rbac-users/remove-permissions-from-users)

## Learn more

* [Manage Role-Based Access Control Users](/docs/manage-users/access-control/configure-core-rbac/rbac-users)
* [Manage Role-Based Access Control Roles](/docs/manage-users/access-control/configure-core-rbac/roles)


# Manage Role-Based Access Control Users
Source: https://auth0.com/docs/manage-users/access-control/configure-core-rbac/rbac-users

Learn how to manage users in a role-based access control (RBAC) system using the Auth0 Management Dashboard. For use with Auth0's API Authorization Core feature set.

You can manage users in a role-based access control (RBAC) system.

We provide various functions to help you manage your users, which you can access through either the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>:

* [Assign roles to users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/assign-roles-to-users)
* [View roles assigned to users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/view-user-roles)
* [Remove roles from users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/remove-roles-from-users)
* [Assign permissions to users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/assign-permissions-to-users)
* [View user permissions](/docs/manage-users/access-control/configure-core-rbac/rbac-users/view-user-permissions)
* [Remove permissions from users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/remove-permissions-from-users)

## Learn more

* [Troubleshoot Role-Based Access Control and Authorization](/docs/troubleshoot/authentication-issues/troubleshoot-rbac-authorization)


# Assign Permissions to Users
Source: https://auth0.com/docs/manage-users/access-control/configure-core-rbac/rbac-users/assign-permissions-to-users

Learn how to assign permissions to a user using the Auth0 Dashboard or the Management API.

You can assign [permissions](/docs/manage-users/access-control/rbac) to a user using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. The assigned permissions can be used with the API Authorization Core feature set.

<Warning>
  Adding permissions directly to a user circumvents the benefits of role-based access control (RBAC) and is not typically recommended.
</Warning>

## Prerequisites

* For role-based access control (RBAC) to work properly, you must enable it for your API using either the Dashboard or the Management API. The Authorization Core functionality is different from the Authorization Extension. For a comparison, read [Authorization Core vs. Authorization Extension](/docs/manage-users/access-control/authorization-core-vs-authorization-extension).
* [Set up an API](/docs/get-started/auth0-overview/set-up-apis) in the Dashboard.
* Permissions are selected from pre-defined values. If your list of roles is blank, make sure you [add permissions](/docs/get-started/apis/add-api-permissions) for your API.

## Dashboard

There are two ways to assign a permission to a user. You can choose a user from the **Users** list and then assign a permission or you can go to the **User Details** (user profile) page for an individual user and choose a permission to assign in the **Permissions** tab.

### Assign permission in user list

1. Go to [Dashboard > User Management > Users](https://manage.auth0.com/#/users).
2. Click `...` next to the user you want to modify, and select **Assign Permissions**.
3. Select the API from which you want to assign permissions, then select the permissions to assign to the user, and click **Add Permissions**.

### Assign permissions in user profile

You can also assign permissions to users from their individual profile page.

1. Go to [Dashboard > User Management > Users](https://manage.auth0.com/#/users), and click the name of the user to view.
2. Click the **Permissions** tab, and click **Assign Permissions**.
3. Select the API from which you want to assign permissions, then select the permissions to assign to the user, and click **Add Permissions**.

## Management API

Make a `POST` call to the [Assign User Permissions endpoint](https://auth0.com/docs/api/management/v2#!/Users/post_permissions). Be sure to replace `USER_ID`, `MGMT_API_ACCESS_TOKEN`, `API_IDENTIFIER`, and `PERMISSION_NAME` placeholder values with your user ID, Management API <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, API identifier(s), and permission name(s), respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/users/USER_ID/permissions' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "permissions": [ { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" } ] }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/USER_ID/permissions");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("application/json", "{ "permissions": [ { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" } ] }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users/USER_ID/permissions"

  	payload := strings.NewReader("{ "permissions": [ { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" } ] }")

  	req, _ := http.NewRequest("POST", 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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/users/USER_ID/permissions")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "permissions": [ { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" } ] }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/users/USER_ID/permissions',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: {
      permissions: [
        {
          resource_server_identifier: 'API_IDENTIFIER',
          permission_name: 'PERMISSION_NAME'
        },
        {
          resource_server_identifier: 'API_IDENTIFIER',
          permission_name: 'PERMISSION_NAME'
        }
      ]
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"permissions": @[ @{ @"resource_server_identifier": @"API_IDENTIFIER", @"permission_name": @"PERMISSION_NAME" }, @{ @"resource_server_identifier": @"API_IDENTIFIER", @"permission_name": @"PERMISSION_NAME" } ] };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/USER_ID/permissions"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/USER_ID/permissions",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "permissions": [ { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" } ] }",
    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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "permissions": [ { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" } ] }"

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
      'cache-control': "no-cache"
      }

  conn.request("POST", "/{yourDomain}/api/v2/users/USER_ID/permissions", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/USER_ID/permissions")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request["cache-control"] = 'no-cache'
  request.body = "{ "permissions": [ { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" } ] }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = ["permissions": [
      [
        "resource_server_identifier": "API_IDENTIFIER",
        "permission_name": "PERMISSION_NAME"
      ],
      [
        "resource_server_identifier": "API_IDENTIFIER",
        "permission_name": "PERMISSION_NAME"
      ]
    ]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/USER_ID/permissions")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

| Value                   | Description                                                                                                           |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `USER_ID`               | Τhe ID of the user for whom you want to assign permissions.                                                           |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](https://auth0.com/docs/api/management/v2/tokens) with the scope `update:users`. |
| `API_IDENTIFIER`        | Identifier(s) of the API(s) associated with the permission(s) you would like to assign for the specified user.        |
| `PERMISSION_NAME`       | Name(s) of the permission(s) you would like to assign for the specified user.                                         |

## Learn more

* [Remove Permissions from Users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/remove-permissions-from-users)
* [View User Permissions](/docs/manage-users/access-control/configure-core-rbac/rbac-users/view-user-permissions)


# Assign Roles to Users
Source: https://auth0.com/docs/manage-users/access-control/configure-core-rbac/rbac-users/assign-roles-to-users

Learn how to assign roles to a user using the Auth0 Dashboard or the Management API.

You can assign [roles](/docs/manage-users/access-control/rbac) to a user using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. The assigned roles can be used with the API Authorization Core feature set.

## Prerequisites

* For role-based access control (RBAC) to work properly, you must enable it for your API using either the Dashboard or the Management API. The Authorization Core functionality is different from the Authorization Extension. For a comparison, read [Authorization Core vs. Authorization Extension](/docs/manage-users/access-control/authorization-core-vs-authorization-extension).
* Roles are selected from pre-defined values. If your list of roles is blank, make sure you [create roles](/docs/manage-users/access-control/configure-core-rbac/roles/create-roles) first.

## Dashboard

There are two ways to assign a role to a user. You can choose a user from the **Users** list and then assign a role or you can go to the **User Details** (user profile) page for an individual user and choose a role to assign in the **Roles** tab.

If you have more than 50 roles, only the first 50 are shown in the Roles tab. Other roles may be assigned via the Management API.

### Assign roles in user list

1. Go to [Dashboard > User Management > Users](https://manage.auth0.com/#/users).
2. Click `...` next to the user you want to modify, and select **Assign Roles**.
3. Choose the role(s) you wish to assign, then click **Assign**.

### Assign roles in user profile

You can also assign roles to users from their individual profile page.

1. Go to [Dashboard > User Management > Users](https://manage.auth0.com/#/users) and click the name of the user.
2. Click the **Roles** view, and click **Assign Role**.
3. Choose the role you wish to assign and click **Assign.**

## Management API

Make a `POST` call to the [Assign User Roles endpoint](https://auth0.com/docs/api/management/v2#!/Users/post_user_roles). Be sure to replace `USER_ID`, `MGMT_API_ACCESS_TOKEN`, and `ROLE_ID` placeholder values with your user ID, Management API <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, and role ID(s), respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/users/USER_ID/roles' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "roles": [ "ROLE_ID", "ROLE_ID" ] }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/USER_ID/roles");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("application/json", "{ "roles": [ "ROLE_ID", "ROLE_ID" ] }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users/USER_ID/roles"

  	payload := strings.NewReader("{ "roles": [ "ROLE_ID", "ROLE_ID" ] }")

  	req, _ := http.NewRequest("POST", 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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/users/USER_ID/roles")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "roles": [ "ROLE_ID", "ROLE_ID" ] }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/users/USER_ID/roles',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: {roles: ['ROLE_ID', 'ROLE_ID']}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"roles": @[ @"ROLE_ID", @"ROLE_ID" ] };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/USER_ID/roles"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/USER_ID/roles",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "roles": [ "ROLE_ID", "ROLE_ID" ] }",
    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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "roles": [ "ROLE_ID", "ROLE_ID" ] }"

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
      'cache-control': "no-cache"
      }

  conn.request("POST", "/{yourDomain}/api/v2/users/USER_ID/roles", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/USER_ID/roles")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request["cache-control"] = 'no-cache'
  request.body = "{ "roles": [ "ROLE_ID", "ROLE_ID" ] }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = ["roles": ["ROLE_ID", "ROLE_ID"]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/USER_ID/roles")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

| Value                   | Description                                                                                                                             |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `USER_ID`               | Τhe ID of the user to be updated.                                                                                                       |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](https://auth0.com/docs/api/management/v2/tokens) with the scopes `read:roles` and `update:users`. |
| `ROLE_ID`               | ID(s) of the role(s) you would like to add for the specified user.                                                                      |

## Learn more

* [Manage Role-Based Access Control Roles](/docs/manage-users/access-control/configure-core-rbac/roles)
* [View Roles Assigned to Users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/view-user-roles)
* [Create Roles](/docs/manage-users/access-control/configure-core-rbac/roles/create-roles)
* [Delete Roles](/docs/manage-users/access-control/configure-core-rbac/roles/delete-roles)
* [Remove Roles from Users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/remove-roles-from-users)
* [Add Permissions to Roles](/docs/manage-users/access-control/configure-core-rbac/roles/add-permissions-to-roles)


# Remove Permissions from Users
Source: https://auth0.com/docs/manage-users/access-control/configure-core-rbac/rbac-users/remove-permissions-from-users

Learn how to remove permissions directly assigned to a user using the Auth0 Dashboard or the Management API.

You can remove the permissions directly assigned to a user using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. The assigned permissions are used with the API Authorization Core feature set. To learn more, read [Role-Based Access Control](/docs/manage-users/access-control/rbac).

## Prerequisites

For role-based access control (RBAC) to work properly, you must enable it for your API using either the Dashboard or the Management API. The Authorization Core functionality is different from the Authorization Extension. For a comparison, read [Authorization Core vs. Authorization Extension](/docs/manage-users/access-control/authorization-core-vs-authorization-extension).

## Use the Dashboard

1. Go to [Dashboard > User Management > Users](https://manage.auth0.com/#/users) and click the name of the user.
2. Click the **Permissions** view, then click the trash can icon next to the permission you want to remove, and confirm.

   <Frame>
     <img alt="Auth0 Dashboard User Detail list of permissions assigned to this user" />
   </Frame>

## Use the Management API

Make a `DELETE` call to the [Delete User Permissions endpoint](https://auth0.com/docs/api/management/v2#!/Users/delete_permissions). Be sure to replace `USER_ID`, `MGMT_API_ACCESS_TOKEN`, `API_ID`, and `PERMISSION_NAME` placeholder values with your user ID, Management API <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, API ID(s), and permission name(s), respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url 'https://{yourDomain}/api/v2/users/USER_ID/permissions' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "permissions": [ { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" } ] }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/USER_ID/permissions");
  var request = new RestRequest(Method.DELETE);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("application/json", "{ "permissions": [ { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" } ] }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users/USER_ID/permissions"

  	payload := strings.NewReader("{ "permissions": [ { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" } ] }")

  	req, _ := http.NewRequest("DELETE", 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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.delete("https://{yourDomain}/api/v2/users/USER_ID/permissions")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "permissions": [ { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" } ] }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'DELETE',
    url: 'https://{yourDomain}/api/v2/users/USER_ID/permissions',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: {
      permissions: [
        {resource_server_identifier: 'API_ID', permission_name: 'PERMISSION_NAME'},
        {resource_server_identifier: 'API_ID', permission_name: 'PERMISSION_NAME'}
      ]
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"permissions": @[ @{ @"resource_server_identifier": @"API_ID", @"permission_name": @"PERMISSION_NAME" }, @{ @"resource_server_identifier": @"API_ID", @"permission_name": @"PERMISSION_NAME" } ] };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/USER_ID/permissions"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"DELETE"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/USER_ID/permissions",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_POSTFIELDS => "{ "permissions": [ { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" } ] }",
    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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "permissions": [ { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" } ] }"

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
      'cache-control': "no-cache"
      }

  conn.request("DELETE", "/{yourDomain}/api/v2/users/USER_ID/permissions", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/USER_ID/permissions")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Delete.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request["cache-control"] = 'no-cache'
  request.body = "{ "permissions": [ { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" } ] }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = ["permissions": [
      [
        "resource_server_identifier": "API_ID",
        "permission_name": "PERMISSION_NAME"
      ],
      [
        "resource_server_identifier": "API_ID",
        "permission_name": "PERMISSION_NAME"
      ]
    ]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/USER_ID/permissions")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "DELETE"
  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()
  ```
</AuthCodeGroup>

| Value                   | Description                                                                                                           |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `USER_ID`               | Τhe ID of the user to be updated.                                                                                     |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](https://auth0.com/docs/api/management/v2/tokens) with the scope `update:users`. |
| `API_ID`                | ID(s) of the API(s) associated with the permission(s) you would like to remove for the specified user.                |
| `PERMISSION_NAME`       | Name(s) of the permission(s) you would like to remove for the specified user.                                         |

## Learn more

* [Assign Permissions to Users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/assign-permissions-to-users)
* [Remove Permissions from Roles](/docs/manage-users/access-control/configure-core-rbac/roles/remove-permissions-from-roles)
* [View Role Permissions](/docs/manage-users/access-control/configure-core-rbac/roles/view-role-permissions)
* [Manage Role-Based Access Control Permissions](/docs/manage-users/access-control/configure-core-rbac/manage-permissions)


# Remove Roles from Users
Source: https://auth0.com/docs/manage-users/access-control/configure-core-rbac/rbac-users/remove-roles-from-users

Learn how to remove roles assigned to a user using the Auth0 Dashboard or the Management API.

You can remove the [roles](/docs/manage-users/access-control/rbac) assigned to a user using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. The assigned roles are used with the API Authorization Core feature set.

## Prerequisites

For role-based access control (RBAC) to work properly, you must enable it for your API using either the Dashboard or the Management API. The Authorization Core functionality is different from the Authorization Extension. For a comparison, read [Authorization Core vs. Authorization Extension](/docs/manage-users/access-control/authorization-core-vs-authorization-extension).

## Dashboard

1. Go to [Dashboard > User Management > Users](https://manage.auth0.com/#/users) and click the name of the user to view.
2. Click the **Roles** view, then click the trashcan icon next to the role you want to remove.

## Management API

Make a `DELETE` call to the [Delete User Roles endpoint](https://auth0.com/docs/api/management/v2#!/Users/delete_user_roles). Be sure to replace `USER_ID`, `MGMT_API_ACCESS_TOKEN`, and `ROLE_ID` placeholder values with your user ID, Management API <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, and role ID(s), respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url 'https://{yourDomain}/api/v2/users/USER_ID/roles' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "roles": [ "ROLE_ID", "ROLE_ID" ] }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/USER_ID/roles");
  var request = new RestRequest(Method.DELETE);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("application/json", "{ "roles": [ "ROLE_ID", "ROLE_ID" ] }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users/USER_ID/roles"

  	payload := strings.NewReader("{ "roles": [ "ROLE_ID", "ROLE_ID" ] }")

  	req, _ := http.NewRequest("DELETE", 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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.delete("https://{yourDomain}/api/v2/users/USER_ID/roles")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "roles": [ "ROLE_ID", "ROLE_ID" ] }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'DELETE',
    url: 'https://{yourDomain}/api/v2/users/USER_ID/roles',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: {roles: ['ROLE_ID', 'ROLE_ID']}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"roles": @[ @"ROLE_ID", @"ROLE_ID" ] };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/USER_ID/roles"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"DELETE"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/USER_ID/roles",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_POSTFIELDS => "{ "roles": [ "ROLE_ID", "ROLE_ID" ] }",
    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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "roles": [ "ROLE_ID", "ROLE_ID" ] }"

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
      'cache-control': "no-cache"
      }

  conn.request("DELETE", "/{yourDomain}/api/v2/users/USER_ID/roles", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/USER_ID/roles")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Delete.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request["cache-control"] = 'no-cache'
  request.body = "{ "roles": [ "ROLE_ID", "ROLE_ID" ] }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = ["roles": ["ROLE_ID", "ROLE_ID"]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/USER_ID/roles")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "DELETE"
  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()
  ```
</AuthCodeGroup>

| Value                   | Description                                                                                                           |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `USER_ID`               | Τhe ID of the user to be updated.                                                                                     |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](https://auth0.com/docs/api/management/v2/tokens) with the scope `update:users`. |
| `ROLE_ID`               | ID(s) of the role(s) you would like to remove for the specified user.                                                 |

## Learn more

* [Delete Roles](/docs/manage-users/access-control/configure-core-rbac/roles/delete-roles)
* [Remove Permissions from Roles](/docs/manage-users/access-control/configure-core-rbac/roles/remove-permissions-from-roles)
* [View Roles Assigned to Users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/view-user-roles)
* [View Users Assigned to Roles](/docs/manage-users/access-control/configure-core-rbac/roles/view-users-assigned-to-roles)


# View User Permissions
Source: https://auth0.com/docs/manage-users/access-control/configure-core-rbac/rbac-users/view-user-permissions

Learn how to view permissions assigned to a user using the Auth0 Dashboard and Management API.

You can view the [permissions](/docs/manage-users/access-control/rbac) assigned to a user using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. This task can also be performed using the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. The assigned permissions are used with the API Authorization Core feature set.

## Prerequisites

For role-based access control (RBAC) to work properly, you must enable it for your API using either the Dashboard or the Management API. The Authorization Core functionality is different from the Authorization Extension. For a comparison, read [Authorization Core vs. Authorization Extension](/docs/manage-users/access-control/authorization-core-vs-authorization-extension).

## Dashboard

1. Go to [Dashboard > Manage Users > Users](https://manage.auth0.com/#/users) and click the name of the user to view.
2. Click the **Permissions** view.

   <Frame>
     <img alt="Auth0 Dashboard User Detail list of permissions assigned to this user" />
   </Frame>

The following information is displayed for each permission:

| Column      | Description                                                                                  |
| ----------- | -------------------------------------------------------------------------------------------- |
| Name        | Name of the permission from the permission definition.                                       |
| Description | Description of the permission from the permission definition.                                |
| API         | Name of the API to which the permission is attached.                                         |
| Assignment  | Indicates whether the permission is directly assigned to the user or is assigned via a role. |

## Management API

Make a `GET` call to the [Get User Permissions endpoint](https://auth0.com/docs/api/management/v2#!/Users/get_permissions). Be sure to replace `USER_ID` and `MGMT_API_ACCESS_TOKEN` placeholder values with your user ID and Management API <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/users/USER_ID/permissions' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/USER_ID/permissions");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users/USER_ID/permissions"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/users/USER_ID/permissions")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/users/USER_ID/permissions',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/USER_ID/permissions"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/USER_ID/permissions",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer MGMT_API_ACCESS_TOKEN" }

  conn.request("GET", "/{yourDomain}/api/v2/users/USER_ID/permissions", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/USER_ID/permissions")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer MGMT_API_ACCESS_TOKEN"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/USER_ID/permissions")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

| Value                   | Description                                                                                                         |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `USER_ID`               | Τhe ID of the user for whom you want to get permissions.                                                            |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](https://auth0.com/docs/api/management/v2/tokens) with the scope `read:users`. |

## Learn more

* [Assign Permissions to Users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/assign-permissions-to-users)
* [Remove Permissions from Users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/remove-permissions-from-users)


# View Roles Assigned to Users
Source: https://auth0.com/docs/manage-users/access-control/configure-core-rbac/rbac-users/view-user-roles

Learn how to view roles assigned to a user using the Auth0 Dashboard or the Management API.

You can view the [roles](/docs/manage-users/access-control/rbac) assigned to a user using Auth0's Dashboard. This task can also be performed using the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. The assigned roles are used with the API Authorization Core feature set.

## Prerequisites

For role-based access control (RBAC) to work properly, you must enable it for your API using either the Dashboard or the Management API. The Authorization Core functionality is different from the Authorization Extension. For a comparison, read [Authorization Core vs. Authorization Extension](/docs/manage-users/access-control/authorization-core-vs-authorization-extension).

## Dashboard

1. Go to [Dashboard > User Management > Users](https://manage.auth0.com/#/users) and click the name of the user to view.
2. Click the **Roles** tab.

The following information is displayed for each role:

| Column      | Description                                       |
| ----------- | ------------------------------------------------- |
| Name        | Name of the role from the role definition.        |
| Description | Description of the role from the role definition. |

## Management API

Make a `GET` call to the [Get User Roles endpoint](https://auth0.com/docs/api/management/v2#!/Users/get_user_roles). Be sure to replace `USER_ID` and `MGMT_API_ACCESS_TOKEN` placeholder values with your user ID and Management API <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/users/USER_ID/roles' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/USER_ID/roles");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users/USER_ID/roles"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/users/USER_ID/roles")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/users/USER_ID/roles',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/USER_ID/roles"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/USER_ID/roles",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer MGMT_API_ACCESS_TOKEN" }

  conn.request("GET", "/{yourDomain}/api/v2/users/USER_ID/roles", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/USER_ID/roles")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer MGMT_API_ACCESS_TOKEN"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/USER_ID/roles")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

| Value                   | Description                                                                                                                           |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `USER_ID`               | Τhe ID of the user for whom you want to get roles.                                                                                    |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](https://auth0.com/docs/api/management/v2/tokens) with the scopes `read:users` and `read:roles`. |

## Learn more

* [View User Details](/docs/manage-users/user-accounts/view-user-details)


# Manage Role-Based Access Control Roles
Source: https://auth0.com/docs/manage-users/access-control/configure-core-rbac/roles

Learn how to manage roles using the Auth0 Management Dashboard. For use with Auth0's API Authorization Core feature set.

<Callout icon="file-lines">
  The [Authorization Core](/docs/manage-users/access-control/rbac) feature set and [Authorization Extension](/docs/customize/extensions/authorization-extension) are completely separate features. To manage groups, roles, or permissions, you need to use the feature they were originally created in.
</Callout>

For role-based access control (RBAC) to work properly, you must enable it for your API using either the Dashboard or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. The Authorization Core functionality is different from the Authorization Extension. For a comparison, read [Authorization Core vs. Authorization Extension](/docs/manage-users/access-control/authorization-core-vs-authorization-extension).

We provide various functions to help you manage your roles, which you can access through either the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the Auth0 Management API:

* [Create roles](/docs/manage-users/access-control/configure-core-rbac/roles/create-roles)
* [Edit role definitions](/docs/manage-users/access-control/configure-core-rbac/roles/edit-role-definitions)
* [Add permissions to roles](/docs/manage-users/access-control/configure-core-rbac/roles/add-permissions-to-roles)
* [Remove permissions from roles](/docs/manage-users/access-control/configure-core-rbac/roles/remove-permissions-from-roles)
* [View role permissions](/docs/manage-users/access-control/configure-core-rbac/roles/view-role-permissions)
* [View role users](/docs/manage-users/access-control/configure-core-rbac/roles/view-users-assigned-to-roles)
* [Delete roles](/docs/manage-users/access-control/configure-core-rbac/roles/delete-roles)

## Learn more

* [Assign Roles to Users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/assign-roles-to-users)
* [Register APIs](/docs/get-started/auth0-overview/set-up-apis)
* [Add API Permissions](/docs/get-started/apis/add-api-permissions)
* [Troubleshoot Role-Based Access Control and Authorization](/docs/troubleshoot/authentication-issues/troubleshoot-rbac-authorization)


# Add Permissions to Roles
Source: https://auth0.com/docs/manage-users/access-control/configure-core-rbac/roles/add-permissions-to-roles

Learn how to add permissions to roles using the Auth0 Dashboard or the Management API.

You can add permissions to [roles](/docs/manage-users/access-control/rbac) using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. The roles and their permissions can be used with the API Authorization Core feature set.

## Prerequisites

* For role-based access control (RBAC) to work properly, you must enable it for your API using either the Dashboard or the Management API. The Authorization Core functionality is different from the Authorization Extension. For a comparison, read [Authorization Core vs. Authorization Extension](/docs/manage-users/access-control/authorization-core-vs-authorization-extension).
* Roles are selected from pre-defined values. If your list of roles is blank, you need to [create a role](/docs/manage-users/access-control/configure-core-rbac/roles/create-roles).
* [Set up an API](/docs/get-started/auth0-overview/set-up-apis) in the Auth0 Dashboard.
* Permissions are selected from predefined values. If your list of permissions is blank, you need to [add permissions](/docs/get-started/apis/add-api-permissions) to your API.

## Dashboard

1. Go to [Dashboard > User Management > Roles](https://manage.auth0.com/#/roles) and click the name of the role to view.
2. Click the **Permissions** tab, then click **Add Permissions**.
3. Select the API from which you want to assign permissions, then select the permissions to add to the role, and click **Add Permissions**.

## Management API

Make a `POST` call to the [Add Role Permissions endpoint](https://auth0.com/docs/api/management/v2#!/Roles/post_role_permission_assignment). Be sure to replace `ROLE_ID`, `MGMT_API_ACCESS_TOKEN`, `API_IDENTIFIER`, and `PERMISSION_NAME` placeholder values with your role ID, Management API <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, API identifier (<Tooltip href="/docs/glossary?term=audience">audience</Tooltip>), and permission name(s), respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/roles/ROLE_ID/permissions' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "permissions": [ { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" } ] }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/roles/ROLE_ID/permissions");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("application/json", "{ "permissions": [ { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" } ] }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/roles/ROLE_ID/permissions"

  	payload := strings.NewReader("{ "permissions": [ { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" } ] }")

  	req, _ := http.NewRequest("POST", 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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/roles/ROLE_ID/permissions")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "permissions": [ { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" } ] }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/roles/ROLE_ID/permissions',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: {
      permissions: [
        {
          resource_server_identifier: 'API_IDENTIFIER',
          permission_name: 'PERMISSION_NAME'
        },
        {
          resource_server_identifier: 'API_IDENTIFIER',
          permission_name: 'PERMISSION_NAME'
        }
      ]
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"permissions": @[ @{ @"resource_server_identifier": @"API_IDENTIFIER", @"permission_name": @"PERMISSION_NAME" }, @{ @"resource_server_identifier": @"API_IDENTIFIER", @"permission_name": @"PERMISSION_NAME" } ] };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/roles/ROLE_ID/permissions"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/roles/ROLE_ID/permissions",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "permissions": [ { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" } ] }",
    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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "permissions": [ { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" } ] }"

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
      'cache-control': "no-cache"
      }

  conn.request("POST", "/{yourDomain}/api/v2/roles/ROLE_ID/permissions", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/roles/ROLE_ID/permissions")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request["cache-control"] = 'no-cache'
  request.body = "{ "permissions": [ { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_IDENTIFIER", "permission_name": "PERMISSION_NAME" } ] }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = ["permissions": [
      [
        "resource_server_identifier": "API_IDENTIFIER",
        "permission_name": "PERMISSION_NAME"
      ],
      [
        "resource_server_identifier": "API_IDENTIFIER",
        "permission_name": "PERMISSION_NAME"
      ]
    ]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/roles/ROLE_ID/permissions")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

| Value                   | Description                                                                                                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ROLE_ID`               | Τhe ID of the role for which you want to add permissions.                                                                                                                  |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](https://auth0.com/docs/api/management/v2/tokens) with the scope `update:roles`.                                                      |
| `API_IDENTIFIER`        | This is the identifier of the API associated with the permission(s) you would like to add for the specified role, otherwise known as the audience. This is not the API ID. |
| `PERMISSION_NAME`       | Name(s) of the permission(s) you would like to add for the specified role.                                                                                                 |

## Learn more

* [Assign Roles to Users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/assign-roles-to-users)
* [Remove Permissions from Roles](/docs/manage-users/access-control/configure-core-rbac/roles/remove-permissions-from-roles)


# Create Roles
Source: https://auth0.com/docs/manage-users/access-control/configure-core-rbac/roles/create-roles

Learn how to create a role using the Auth0 Dashboard or the Management API.

You can create [roles](/docs/manage-users/access-control/rbac) using Auth0's Dashboard or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. The roles can be used with the API Authorization Core feature set.

## Prerequisites

* For role-based access control (RBAC) to work properly, you must enable it for your API using either the Dashboard or the Management API. The Authorization Core functionality is different from the Authorization Extension. For a comparison, read [Authorization Core vs. Authorization Extension](/docs/manage-users/access-control/authorization-core-vs-authorization-extension).
* [Set up an API](/docs/get-started/auth0-overview/set-up-apis) in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.
* Permissions are selected from predefined values. If your list of permissions is blank, you need to [add permissions](/docs/get-started/apis/add-api-permissions) to your API.

## Dashboard

1. Go to [Dashboard > User Management > Roles](https://manage.auth0.com/#/roles) and click **Create Role**.
2. Name the role and add a description, then click **Create**.

## Management API

Make a `POST` call to the [Create Role endpoint](https://auth0.com/docs/api/management/v2#!/Roles/post_roles). Be sure to replace `MGMT_API_ACCESS_TOKEN`, `ROLE_NAME`, and `ROLE_DESC` placeholder values with your Management API <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, role name, and role description, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/roles' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "name": "ROLE_NAME", "description": "ROLE_DESC" }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/roles");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("application/json", "{ "name": "ROLE_NAME", "description": "ROLE_DESC" }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/roles"

  	payload := strings.NewReader("{ "name": "ROLE_NAME", "description": "ROLE_DESC" }")

  	req, _ := http.NewRequest("POST", 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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/roles")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "name": "ROLE_NAME", "description": "ROLE_DESC" }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/roles',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: {name: 'ROLE_NAME', description: 'ROLE_DESC'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"name": @"ROLE_NAME",
                                @"description": @"ROLE_DESC" };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/roles"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/roles",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "name": "ROLE_NAME", "description": "ROLE_DESC" }",
    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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "name": "ROLE_NAME", "description": "ROLE_DESC" }"

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
      'cache-control': "no-cache"
      }

  conn.request("POST", "/{yourDomain}/api/v2/roles", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/roles")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request["cache-control"] = 'no-cache'
  request.body = "{ "name": "ROLE_NAME", "description": "ROLE_DESC" }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = [
    "name": "ROLE_NAME",
    "description": "ROLE_DESC"
  ] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/roles")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

| **Value**               | **Description**                                                                                                       |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](https://auth0.com/docs/api/management/v2/tokens) with the scope `create:roles`. |
| `ROLE_NAME`             | Name of the role you would like to create.                                                                            |
| `ROLE_DESC`             | User-friendly description of the role.                                                                                |

## Learn more

* [Add Permissions to Roles](/docs/manage-users/access-control/configure-core-rbac/roles/add-permissions-to-roles)
* [Remove Permissions from Roles](/docs/manage-users/access-control/configure-core-rbac/roles/remove-permissions-from-roles)
* [Assign Roles to Users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/assign-roles-to-users)
* [Delete Roles](/docs/manage-users/access-control/configure-core-rbac/roles/delete-roles)


# Delete Roles
Source: https://auth0.com/docs/manage-users/access-control/configure-core-rbac/roles/delete-roles

Learn how to delete a role using the Auth0 Dashboard or the Management API.

You can delete a [role](/docs/manage-users/access-control/rbac) using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. Roles are used with the API Authorization Core feature set.

For role-based access control (RBAC) to work properly, you must enable it for your API using either the Dashboard or the Management API. The Authorization Core functionality is different from the Authorization Extension. For a comparison, read [Authorization Core vs. Authorization Extension](/docs/manage-users/access-control/authorization-core-vs-authorization-extension).

## Dashboard

1. Go to [Dashboard > User Management > Roles](https://manage.auth0.com/#/roles) and click the name of the role to view.
2. Click **Remove this Role**, and confirm.

## Management API

Make a `DELETE` call to the [Delete Role endpoint](https://auth0.com/docs/api/management/v2#!/Roles/delete_roles_by_id). Be sure to replace `ROLE_ID` and `MGMT_API_ACCESS_TOKEN` placeholder values with your role ID and Management API <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url 'https://{yourDomain}/api/v2/roles/ROLE_ID' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/roles/ROLE_ID");
  var request = new RestRequest(Method.DELETE);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/roles/ROLE_ID"

  	req, _ := http.NewRequest("DELETE", url, nil)

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.delete("https://{yourDomain}/api/v2/roles/ROLE_ID")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'DELETE',
    url: 'https://{yourDomain}/api/v2/roles/ROLE_ID',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/roles/ROLE_ID"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"DELETE"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/roles/ROLE_ID",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer MGMT_API_ACCESS_TOKEN" }

  conn.request("DELETE", "/{yourDomain}/api/v2/roles/ROLE_ID", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/roles/ROLE_ID")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Delete.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer MGMT_API_ACCESS_TOKEN"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/roles/ROLE_ID")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "DELETE"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

| Value                   | Description                                                                                                           |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `ROLE_ID`               | Τhe ID of the role you want to delete.                                                                                |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](https://auth0.com/docs/api/management/v2/tokens) with the scope `delete:roles`. |

## Learn more

* [Create Roles](/docs/manage-users/access-control/configure-core-rbac/roles/create-roles)


# Edit Role Definitions
Source: https://auth0.com/docs/manage-users/access-control/configure-core-rbac/roles/edit-role-definitions

Learn how to edit a role definition using the Auth0 Dashboard and the Management API.

You can edit a [role](/docs/manage-users/access-control/rbac) definition using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. Roles are used with the API Authorization Core feature set.

## Prerequisite

For role-based access control (RBAC) to work properly, you must enable it for your API using either the Dashboard or the Management API. The Authorization Core functionality is different from the Authorization Extension. For a comparison, read [Authorization Core vs. Authorization Extension](/docs/manage-users/access-control/authorization-core-vs-authorization-extension).

## Dashboard

1. Go to [Dashboard > User Management > Roles](https://manage.auth0.com/#/roles) and click the name of the role to view.
2. Edit the role name and description, then click **Save**.

## Management API

Make a `PATCH` call to the [Update Role endpoint](https://auth0.com/docs/api/management/v2#!/Roles/patch_roles_by_id). Be sure to replace `ROLE_ID`, `MGMT_API_ACCESS_TOKEN`, `ROLE_NAME`, and `ROLE_DESC` placeholder values with your role ID, Management API <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, role name, and role description, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/roles/ROLE_ID' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "name": "ROLE_NAME", "description": "ROLE_DESC" }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/roles/ROLE_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", "{ "name": "ROLE_NAME", "description": "ROLE_DESC" }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/roles/ROLE_ID"

  	payload := strings.NewReader("{ "name": "ROLE_NAME", "description": "ROLE_DESC" }")

  	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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/roles/ROLE_ID")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "name": "ROLE_NAME", "description": "ROLE_DESC" }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/roles/ROLE_ID',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: {name: 'ROLE_NAME', description: 'ROLE_DESC'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"name": @"ROLE_NAME",
                                @"description": @"ROLE_DESC" };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/roles/ROLE_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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/roles/ROLE_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 => "{ "name": "ROLE_NAME", "description": "ROLE_DESC" }",
    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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "name": "ROLE_NAME", "description": "ROLE_DESC" }"

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
      'cache-control': "no-cache"
      }

  conn.request("PATCH", "/{yourDomain}/api/v2/roles/ROLE_ID", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/roles/ROLE_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 = "{ "name": "ROLE_NAME", "description": "ROLE_DESC" }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = [
    "name": "ROLE_NAME",
    "description": "ROLE_DESC"
  ] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/roles/ROLE_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()
  ```
</AuthCodeGroup>

| Value                   | Description                                                                                                           |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `ROLE_ID`               | Τhe ID of the role for which you want to edit the definition.                                                         |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](https://auth0.com/docs/api/management/v2/tokens) with the scope `update:roles`. |
| `ROLE_NAME`             | Name of the role.                                                                                                     |
| `ROLE_DESC`             | User-friendly description of the role.                                                                                |

## Learn more

* [Assign Roles to Users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/assign-roles-to-users)


# Remove Permissions from Roles
Source: https://auth0.com/docs/manage-users/access-control/configure-core-rbac/roles/remove-permissions-from-roles

Learn how to remove permissions added to a role using the Auth0 Dashboard or the Management API.

You can remove the [permissions](/docs/manage-users/access-control/rbac) assigned to a role using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. The assigned permissions and roles are used with the API Authorization Core feature set.

## Prerequisite

For role-based access control (RBAC) to work properly, you must enable it for your API using either the Dashboard or the Management API. The Authorization Core functionality is different from the Authorization Extension. For a comparison, read [Authorization Core vs. Authorization Extension](/docs/manage-users/access-control/authorization-core-vs-authorization-extension).

## Dashboard

1. Go to [Dashboard > User Management > Roles](https://manage.auth0.com/#/roles) and click the name of the role to view.
2. Click the **Permissions** view, then click the trashcan icon next to the permission you want to remove, and confirm.

## Management API

Make a `DELETE` call to the [Delete Role Permissions endpoint](https://auth0.com/docs/api/management/v2#!/Roles/delete_role_permission_assignment). Be sure to replace `ROLE_ID`, `MGMT_API_ACCESS_TOKEN`, `API_ID`, and `PERMISSION_NAME` placeholder values with your role ID, Management API <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, API ID(s), and permission name(s), respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url 'https://{yourDomain}/api/v2/roles/ROLE_ID/permissions' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "permissions": [ { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" } ] }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/roles/ROLE_ID/permissions");
  var request = new RestRequest(Method.DELETE);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("application/json", "{ "permissions": [ { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" } ] }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/roles/ROLE_ID/permissions"

  	payload := strings.NewReader("{ "permissions": [ { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" } ] }")

  	req, _ := http.NewRequest("DELETE", 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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.delete("https://{yourDomain}/api/v2/roles/ROLE_ID/permissions")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "permissions": [ { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" } ] }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'DELETE',
    url: 'https://{yourDomain}/api/v2/roles/ROLE_ID/permissions',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: {
      permissions: [
        {resource_server_identifier: 'API_ID', permission_name: 'PERMISSION_NAME'},
        {resource_server_identifier: 'API_ID', permission_name: 'PERMISSION_NAME'}
      ]
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"permissions": @[ @{ @"resource_server_identifier": @"API_ID", @"permission_name": @"PERMISSION_NAME" }, @{ @"resource_server_identifier": @"API_ID", @"permission_name": @"PERMISSION_NAME" } ] };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/roles/ROLE_ID/permissions"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"DELETE"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/roles/ROLE_ID/permissions",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_POSTFIELDS => "{ "permissions": [ { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" } ] }",
    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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "permissions": [ { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" } ] }"

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
      'cache-control': "no-cache"
      }

  conn.request("DELETE", "/{yourDomain}/api/v2/roles/ROLE_ID/permissions", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/roles/ROLE_ID/permissions")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Delete.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request["cache-control"] = 'no-cache'
  request.body = "{ "permissions": [ { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" }, { "resource_server_identifier": "API_ID", "permission_name": "PERMISSION_NAME" } ] }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = ["permissions": [
      [
        "resource_server_identifier": "API_ID",
        "permission_name": "PERMISSION_NAME"
      ],
      [
        "resource_server_identifier": "API_ID",
        "permission_name": "PERMISSION_NAME"
      ]
    ]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/roles/ROLE_ID/permissions")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "DELETE"
  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()
  ```
</AuthCodeGroup>

| Value                   | Description                                                                                                           |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `ROLE_ID`               | Τhe ID of the role for which you want to remove permissions.                                                          |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](https://auth0.com/docs/api/management/v2/tokens) with the scope `update:roles`. |
| `API_ID`                | ID(s) of the API(s) associated with the permission(s) you would like to remove for the specified role.                |
| `PERMISSION_NAME`       | Name(s) of the permission(s) you would like to remove for the specified role.                                         |

## Learn more

* [View Role Permissions](/docs/manage-users/access-control/configure-core-rbac/roles/view-role-permissions)
* [Add API Permissions](/docs/get-started/apis/add-api-permissions)
* [Delete API Permissions](/docs/get-started/apis/delete-api-permissions)
* [Manage Role-Based Access Control Permissions](/docs/manage-users/access-control/configure-core-rbac/manage-permissions)
* [Sample Use Cases: Role-Based Access Control](/docs/manage-users/access-control/sample-use-cases-role-based-access-control)


# View Role Permissions
Source: https://auth0.com/docs/manage-users/access-control/configure-core-rbac/roles/view-role-permissions

Learn how to view permissions added to a role using the Auth0 Dashboard or the Management API.

You can view the [permissions](/docs/manage-users/access-control/rbac) added to a role using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. The assigned permissions and roles are used with the API Authorization Core feature set.

## Prerequisites

For role-based access control (RBAC) to work properly, you must enable it for your API using either the Dashboard or the Management API. The Authorization Core functionality is different from the Authorization Extension. For a comparison, read [Authorization Core vs. Authorization Extension](/docs/manage-users/access-control/authorization-core-vs-authorization-extension).

## Dashboard

1. Go to [Dashboard > User Management > Roles](https://manage.auth0.com/#/roles) and click the name of the role to view.
2. Click the **Permissions** view.

The following information is displayed for each permission:

| Column      | Description                                                   |
| ----------- | ------------------------------------------------------------- |
| Name        | Name of the permission from the permission definition.        |
| Description | Description of the permission from the permission definition. |
| API         | Name of the API to which the permission is attached.          |

## Management API

Make a `GET` call to the [Get Role Permissions endpoint](https://auth0.com/docs/api/management/v2#!/Roles/get_role_permission). Be sure to replace `ROLE_ID` and `MGMT_API_ACCESS_TOKEN` placeholder values with your role ID and Management API <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/roles/ROLE_ID/permissions' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/roles/ROLE_ID/permissions");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/roles/ROLE_ID/permissions"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/roles/ROLE_ID/permissions")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/roles/ROLE_ID/permissions',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/roles/ROLE_ID/permissions"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/roles/ROLE_ID/permissions",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer MGMT_API_ACCESS_TOKEN" }

  conn.request("GET", "/{yourDomain}/api/v2/roles/ROLE_ID/permissions", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/roles/ROLE_ID/permissions")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer MGMT_API_ACCESS_TOKEN"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/roles/ROLE_ID/permissions")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

| Value                   | Description                                                                                                         |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `ROLE_ID`               | Τhe ID of the role for which you want to get permissions.                                                           |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](https://auth0.com/docs/api/management/v2/tokens) with the scope `read:roles`. |

## Learn more

* [Manage Role-Based Access Control Permissions](/docs/manage-users/access-control/configure-core-rbac/manage-permissions)
* [Add API Permissions](/docs/get-started/apis/add-api-permissions)
* [Delete API Permissions](/docs/get-started/apis/delete-api-permissions)
* [Remove Permissions from Roles](/docs/manage-users/access-control/configure-core-rbac/roles/remove-permissions-from-roles)


# View Users Assigned to Roles
Source: https://auth0.com/docs/manage-users/access-control/configure-core-rbac/roles/view-users-assigned-to-roles

Describes how to view users assigned to a role using the Auth0 Dashboard or Management API.

You can view the users assigned to a [role](/docs/manage-users/access-control/rbac) using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. Roles are used with the API Authorization Core feature set.

## Prerequisites

For role-based access control (RBAC) to work properly, you must enable it for your API using either the Dashboard or the Management API. The Authorization Core functionality is different from the Authorization Extension. For a comparison, read [Authorization Core vs. Authorization Extension](/docs/manage-users/access-control/authorization-core-vs-authorization-extension).

## Dashboard

1. Go to [Dashboard > User Management > Roles](https://manage.auth0.com/#/users) and click the name of the role to view.
2. Click the **Users** tab.

The following information is displayed for each user:

| Column        | Description                                 |
| ------------- | ------------------------------------------- |
| Picture       | User's picture from the user profile.       |
| Name          | User's name from the user profile.          |
| Email address | User's email address from the user profile. |

## Management API

To retrieve a list of users assigned to a role, see [Get a Role's Users](https://auth0.com/docs/api/management/v2#!/Roles/get_role_user).

## Learn more

* [Assign Roles to Users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/assign-roles-to-users)
* [Create Roles](/docs/manage-users/access-control/configure-core-rbac/roles/create-roles)
* [Delete Roles](/docs/manage-users/access-control/configure-core-rbac/roles/delete-roles)
* [Edit Role Definitions](/docs/manage-users/access-control/configure-core-rbac/roles/edit-role-definitions)
* [Remove Permissions from Roles](/docs/manage-users/access-control/configure-core-rbac/roles/remove-permissions-from-roles)
* [Remove Roles from Users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/remove-roles-from-users)


# Role-Based Access Control
Source: https://auth0.com/docs/manage-users/access-control/rbac

Understand the concept of role-based access control and how it applies in Auth0.

Role-based access control (RBAC) refers to the idea of assigning permissions to users based on their role within an organization. It offers a simple, manageable approach to access management that is less prone to error than assigning permissions to users individually.

When using RBAC for Role Management, you analyze the needs of your users and group them into roles based on common responsibilities. You then assign one or more roles to each user and one or more permissions to each role. The user-role and role-permissions relationships make it simple to perform user assignments since users no longer need to be managed individually, but instead have privileges that conform to the permissions assigned to their role(s).

For example, if you were using RBAC to control access for an HR application, you could give HR managers a role that allows them to update employee details, while other employees would be able to view only their own details.

When planning your access control strategy, it's best practice to assign users the fewest number of permissions that allow them to get their work done.

<Callout icon="file-lines">
  For a more robust authorization model, review [Fine-Grained Authorization (FGA)](https://docs.fga.dev/authorization-concepts) for attribute-based and relationship-based authorization.
</Callout>

## Benefits of RBAC

With RBAC, access management is easier as long as you adhere strictly to the role requirements. RBAC helps you:

* create systematic, repeatable assignment of permissions
* easily audit user privileges and correct identified issues
* quickly add and change roles, as well as implement them across APIs
* cut down on the potential for error when assigning user permissions
* integrate third-party users by giving them pre-defined roles
* more effectively comply with regulatory and statutory requirements for confidentiality and privacy

## RBAC Model

### Roles

Essentially, a role is a collection of permissions that you can apply to users. Using roles makes it easier to add, remove, and adjust permissions than assigning permissions to users individually. As your user base increases in scale and complexity, roles become particularly useful.

You can also use roles to collect permissions defined for various APIs. For example, say you have a marketing module that allows users to create and distribute newsletters to customers. Your marketing content specialist creates all of the newsletters and prepares them for distribution. Similarly, you have an event module that allows users to create, publish, and manage event registration. Your event coordinator creates the events. Once the VP of Marketing approves the newsletters and events, their assistant publishes the events and distributes the newsletters. In this case, your Newsletter API could have a `distribute:newsletters` permission and your Event API could have a `publish:events` permission. These permissions could then be gathered into a role called `Marketing Publisher` and assigned to the VP of Marketing's assistant.

In addition, Organization-specific roles can be [added to Organization members](/docs/manage-users/organizations/configure-organizations/add-member-roles) and used to allow access in your application based on the organizations with which an end-user is logging in. This is particularly useful when supporting multi-tenant & SaaS products, where a particular user might have a privileged role in one organization, but not in others.

## Overlapping role assignments

RBAC is an additive model, so if you have overlapping role assignments, your effective permissions are the union of your role assignments.

For example, let's say you have an API that provides data for an event application. You create a role of `Organizer` and assign it permissions that allow it to view, create, and edit events. You also create a role of `Registrant` and assign it permissions that allow it to view and register for events. Any users with both `Organizer` and `Registrant` roles will be able to view, create, edit, and register for events.

## Role-based access control in Auth0

Currently, we provide two ways of implementing role-based access control (RBAC), which you can use in place of or in combination with your API's own internal access control system:

* [Authorization Core](/docs/manage-users/access-control/configure-core-rbac)
* [Authorization Extension](/docs/customize/extensions/authorization-extension)

We are expanding our Authorization Core feature set to match the functionality of the Authorization Extension. Our new core RBAC implementation improves performance and scalability and will eventually provide a more flexible RBAC system than the Authorization Extension.

For now, both implement the key features of RBAC and allow you to restrict the custom scopes defined for an API to those that have been assigned to the user as permissions. For a comparison, see [Authorization Core vs. Authorization Extension](/docs/manage-users/access-control/authorization-core-vs-authorization-extension).

<Callout icon="file-lines">
  The [Authorization Core](/docs/manage-users/access-control/rbac) feature set and [Authorization Extension](/docs/customize/extensions/authorization-extension) are completely separate features. To manage groups, roles, or permissions, you need to use the feature they were originally created in.
</Callout>

<Callout icon="file-lines">
  Although the [Delegated Administration Extension (DAE)](/docs/customize/extensions/delegated-administration-extension) and the [Authorization Core](/docs/manage-users/access-control/rbac) feature set are completely separate features, you can use the Authorization Core feature set to create and manage roles for the DAE using Actions. To learn how, see [Sample Use Cases: Actions with Authorization](/docs/manage-users/access-control/sample-use-cases-actions-with-authorization).
</Callout>

### Extending RBAC

You can provide more control by using [rules](/docs/customize/rules) to restrict access based on a combination of attributes, such as user department, time of day, location of access, or any other user or API attribute (for example, username, security clearance, or API name).

For more info about using rules with authorization policies, see [Rules with Authorization Policies](/docs/manage-users/access-control/rules-for-authorization-policies).

## Learn more

* [Enable Role-Based Access Control for APIs](/docs/get-started/apis/enable-role-based-access-control-for-apis)
* [Troubleshoot Role-Based Access Control and Authorization](/docs/troubleshoot/authentication-issues/troubleshoot-rbac-authorization)
* [Troubleshoot Authorization Extension](/docs/troubleshoot/authentication-issues/troubleshoot-authorization-extension)


# Rules for Authorization Policies
Source: https://auth0.com/docs/manage-users/access-control/rules-for-authorization-policies

Understand how rules apply to authorization policies and Auth0's role-based access system (RBAC).

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

You can append [Rules](/docs/customize/rules) to the pre-configured authorization policy to exercise additional control over permitting or denying user access. A rule contains custom code that makes an authorization decision based on appropriate logic. When combined with other rules, it helps define what happens in different contexts.

Rules can restrict access based on any combination of attributes you store for users, such as user department, time of day, location, or any other user or API attribute (like username, security clearance, or API name).

For example, if you were using rules to provide finely-grained access control at a non-profit organization, you could give only W2 employees working in the Research and Development department in the New Delhi office access to an application.

For samples of rule implementations with authorization policies, read [Sample Use Cases: Rules with Authorization](/docs/manage-users/access-control/sample-use-cases-rules-with-authorization).

## Rules in the authorization process

Based on the order in which they run, rules can change the outcome of the authorization decision prior to the permissions being added to the <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>. The basic process with rules injected is as follows:

1. The user tries to authenticate with the application.
2. Auth0 brings the request to the selected identity provider.
3. Once the identity provider confirms that user credentials are valid, all created rules run in the order in which they are configured in the Dashboard.
4. Assuming no rule has restricted the user's access, the user is authorized to access the application.

## Learn more

* [Role-Based Access Control](/docs/manage-users/access-control/rbac)
* [Configure Core Authorization Features for Role-Based Access Control](/docs/manage-users/access-control/configure-core-rbac)


# Sample Use Cases: Actions with Authorization
Source: https://auth0.com/docs/manage-users/access-control/sample-use-cases-actions-with-authorization

Learn how to use Actions with roles-based access control (RBAC).

Auth0 [Actions](/docs/customize/actions) allow you to modify or complement the outcome of the decision made by a pre-configured [authorization policy](/docs/manage-users/access-control/authorization-policies) so that you can handle more complicated cases than is possible with [role-based access control (RBAC)](/docs/manage-users/access-control/rbac) alone. Based on the order in which they run, Actions can change the outcome of an authorization decision prior to permissions being added to the <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>. They can also allow you to customize the content of your tokens.

## Allow access only on weekdays for a specific application

Let's say you have an application that you want to make sure is only accessible during weekdays. [Create a new Action](/docs/customize/actions/write-your-first-action), and select the `Login / Post Login` trigger because you’ll be adding the Action to the Login flow. Copy the following code to the Actions Code Editor:

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  if (event.client.name === "APP_NAME") {
    const d = new Date().getDay();

    if (d === 0 || d === 6) {
      api.access.deny("This app is only available during the week.");
    }
  }
}
```

Finally, add the Action you created to the [Login Flow](https://manage.auth0.com/#/actions/flows/login/). To learn how to attach Actions to Flows, read the "Attach the Action to a flow" section in [Write Your First Action](/docs/customize/actions/write-your-first-action).

If a user attempts to access the application during the weekend, access will be denied, even if they authenticate and have the appropriate privileges.

## Allow access only to users who are inside the corporate network

Let's say you want to allow access to an application, but only for users who are accessing the application from inside your corporate network. [Create a new Action](/docs/customize/actions/write-your-first-action), and select the `Login / Post Login` trigger because you’ll be adding the Action to the Login flow. Copy the following code to the Actions Code Editor:

```js lines theme={null}
const ipaddr = require("ipaddr.js");

exports.onExecutePostLogin = async (event, api) => {
  const corpNetwork = "192.168.1.134/26";
  const currentIp = ipaddr.parse(event.request.ip);

  if (!currentIp.match(ipaddr.parseCIDR(corpNetwork))) {
    api.access.deny("This app is only available from inside the corporate network.");
  };
};
```

Finally, add the Action you created to the [Login Flow](https://manage.auth0.com/#/actions/flows/login/). To learn how to attach Actions to Flows, read the "Attach the Action to a flow" section in [Write Your First Action](/docs/customize/actions/write-your-first-action).

If the user is outside the corporate network, they will be denied access even if they successfully authenticate and have the appropriate privileges.

<Callout icon="file-lines">
  To use an `npm` library like `ipaddr.js`, you must add the library as a dependency to the Action. To learn more, read the "Add a dependency" section in [Write Your First Action](/docs/customize/actions/write-your-first-action).
</Callout>

## Deny access to anyone calling an API

Let's say you want to deny access to all users who are calling an API. This means that you need to deny access depending on the `identifier` value for your API, which you can find in the **API <Tooltip href="/docs/glossary?term=Audience">Audience</Tooltip>** field of your API at [Auth0 Dashboard > Applications > APIs](https://manage.auth0.com/#/apis). [Create a new Action](/docs/customize/actions/write-your-first-action), and select the `Login / Post Login` trigger because you’ll be adding the Action to the Login flow. Copy the following code to the Actions Code Editor:

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  // In Actions, an API will be referred to as a Resource Server.
  const { identifier } = event.resource_server || {};
  if (identifier === "https://api.example.com") {
    api.access.deny("end_users_not_allowed");
  }
}
```

Finally, add the Action you created to the [Login Flow](https://manage.auth0.com/#/actions/flows/login/). To learn how to attach Actions to Flows, read the "Attach the Action to a flow" section in [Write Your First Action](/docs/customize/actions/write-your-first-action).

In this case, the `identifier` value for the API is `https://api.example.com`, so this is the audience we will refuse.

## Add user roles to tokens

To add user roles to Auth0-issued tokens, use the `event.authorization` object along with the `api.idToken.setCustomClaim` and `api.accessToken.setCustomClaim` methods. [Create a new Action](/docs/customize/actions/write-your-first-action), and select the `Login / Post Login` trigger because you’ll be adding the Action to the Login flow. Copy the following code to the Actions Code Editor:

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://my-app.example.com';
  if (event.authorization) {
    api.idToken.setCustomClaim(`${namespace}/roles`, event.authorization.roles);
    api.accessToken.setCustomClaim(`${namespace}/roles`, event.authorization.roles);
  }
}
```

Finally, add the Action you created to the [Login Flow](https://manage.auth0.com/#/actions/flows/login/). To learn how to attach Actions to Flows, read the "Attach the Action to a flow" section in [Write Your First Action](/docs/customize/actions/write-your-first-action).

Remember:

* The <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> returned to the requesting application is built and signed at the end of the trigger processing. The final, signed JWT is not accessible in an Action.

## Deny access to specific JA3/JA4 fingerprints

The `event.security_context` object contains the JA3/JA4 fingerprint values for the current transaction.

[Create a new Action](/docs/customize/actions/write-your-first-action), and select the `Login / Post Login` trigger because you’ll be adding the Action to the Login flow. Copy the following code to the Actions Code Editor:

```js lines theme={null}
exports.onExecutePreUserRegistration = async (event, api) => {
  const clientJa4 = event?.security_context?.ja4;
  console.log('[ACTION]', {clientJa4});
  const badFingerprints = ['t13d1517h2_8daaf6152771_b6f405a00624','t13d1516h2_8daaf6152771_d8a2da3f94cd'];
  if (clientJa4 && badFingerprints.includes(clientJa4)){
    api.access.deny('suspicious_tls_fingerprint', 'Your TLS fingerprint has been flagged as suspicious');
  }
};
```

Finally, add the Action you created to the [Login Flow](https://manage.auth0.com/#/actions/flows/login/). To learn how to attach Actions to Flows, read the "Attach the Action to a flow" section in [Write Your First Action](/docs/customize/actions/write-your-first-action).


# Sample Use Cases: Role-Based Access Control
Source: https://auth0.com/docs/manage-users/access-control/sample-use-cases-role-based-access-control

Learn how to implement roles-based authorization (RBAC) in different scenarios and explore how to use rules with RBAC.

Let's take a look at an example of why you might need and how you could use [role-based access control (RBAC)](/docs/manage-users/access-control/rbac) in your <Tooltip href="/docs/glossary?term=authorization+flow">authorization flow</Tooltip>.

Let's say you are a business who provides business-to-business software-as-a-service to non-profit organizations. Your product allows non-profits to create, manage, and market products to potential donors. Your application contains several different modules, two of which are:

* a gift shop point of sale (POS) module that enables non-profits to effectively create pop-up t-shirt shops and manage their sales.
* a marketing module that allows non-profits to create and distribute newsletters to their donors.

You want to use Auth0 to control the access of your non-profit customers to different parts of your application. Without RBAC, all non-profit employees and volunteers will have access to all features of your application, which is not ideal, especially since one of them is an animal rescue who has a variety of volunteers with knowledge of only the area in which they volunteer.

Instead, you implement RBAC, [creating some permissions](/docs/get-started/apis/add-api-permissions) that users of your gift shop POS module would need:

* `read:catalog-item`
* `read:customer-profile`
* `create:invoice`

And to make these easier to manage, you [create a role](/docs/manage-users/access-control/configure-core-rbac/roles/create-roles) called `Gift Shop Manager` and [add these permissions to that role](/docs/manage-users/access-control/configure-core-rbac/roles/add-permissions-to-roles).

Similarly, you create permissions for users of your marketing module, which include:

* `create:newsletter`
* `edit:newsletter`
* `delete:newsletter`
* `send:newsletter`
* `edit:distribution-list`

And you create a role called `Newsletter Admin` and add these permissions to that role.

Now, when your animal rescue brings in their volunteer, Astrid, to run their pop-up t-shirt shop, Astrid can be [assigned the role](/docs/manage-users/access-control/configure-core-rbac/rbac-users/assign-roles-to-users) of `Gift Shop Manager`. When you assign this role to Astrid, she is granted all the permissions that you assigned to the role. Since Astrid knows nothing about publishing newsletters (and isn't the best with email), you never assigned her the `Newsletter Admin` role, so she never has access to the marketing module.

From a more technical perspective, when Astrid logs into your product, Auth0 authenticates and authorizes her and includes the permissions in the returned <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>. Then, your product inspects the token to learn which module to display to Astrid.

By using Auth0's RBAC, you avoid building and maintaining separate authorization systems; instead, you use the token you already receive during authorization. And when Astrid moves away or decides she is tired of running the gift shop and would rather coordinate the foster program, you can easily [remove the Gift Shop Manager role](/docs/manage-users/access-control/configure-core-rbac/rbac-users/remove-roles-from-users) from her and assign her a new role.

And if maintaining the roles and permissions for all of your customers becomes too unwieldy, you can also use the Auth0 API to create a module within your product that allows customers to manage their own RBAC, thereby reducing liability and cutting staffing costs.


# Sample Use Cases: Rules with Authorization
Source: https://auth0.com/docs/manage-users/access-control/sample-use-cases-rules-with-authorization

Learn how to use rules with roles-based access control (RBAC). For use with our Authorization Core feature set.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

With [rules](/docs/customize/rules), you can modify or complement the outcome of the decision made by the pre-configured [authorization policy](/docs/manage-users/access-control/authorization-policies) to handle more complicated cases than is possible with [role-based access control (RBAC)](/docs/manage-users/access-control/rbac) alone. Based on the order in which they run, rules can change the outcome of the authorization decision prior to the permissions being added to the <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>. They can also allow you to customize the content of your tokens.

## Allow access only on weekdays for a specific application

Let's say you have an application that you want to make sure is only accessible during weekdays. To do this, you would [create the following rule](/docs/customize/rules/create-rules):

```js lines theme={null}
function (user, context, callback) {

  if (context.clientName === 'APP_NAME') {
    const d = Date.getDay();

    if (d === 0 || d === 6) {
      return callback(new UnauthorizedError('This app is only available during the week.'));
    }
  }

  callback(null, user, context);
}
```

If a user attempts to access the application during the weekend, access will be denied, even if they authenticate and have the appropriate privileges.

## Allow access only to users who are inside the corporate network

Let's say you want to allow access to an application, but only for users who are accessing the application from inside your corporate network. To do this, you would create the following rule:

```js lines theme={null}
function (user, context, callback) {
  const ipaddr = require('ipaddr.js@1.9.0');
  const corp_network = "192.168.1.134/26";
  const current_ip = ipaddr.parse(context.request.ip);

  if (!current_ip.match(ipaddr.parseCIDR(corp_network))) {
    return callback(new UnauthorizedError('This app is only available from inside the corporate network.'));
  };

  callback(null, user, context);
}
```

If the user is outside the corporate network, they will be denied access even if they successfully authenticate and have the appropriate privileges.

## Deny access to anyone calling an API

Let's say you want to deny access to all users who are calling an API. This means that you need to deny access depending on the `audience` value for your API, which you can find in the **API <Tooltip href="/docs/glossary?term=Audience">Audience</Tooltip>** field of your API in [Dashboard > Applications > APIs](https://manage.auth0.com/#/apis). To do this, you would create the following rule:

```js lines theme={null}
function (user, context, callback) {
  /*
   *  Denies access to user-based flows based on audience
   */
  var audience = '';
  audience = audience
              || (context.request && context.request.query && context.request.query.audience)
              || (context.request && context.request.body && context.request.body.audience);
  if (audience === 'http://todoapi2.api' || !audience) {
    return callback(new UnauthorizedError('end_users_not_allowed'));
  }
  return callback(null, user, context);
}
```

In this case, the `audience` value for the API is `http:://todoapi2.api`, so this is the audience we will refuse. If anyone tries to access the API with this `audience` value, they will be denied access and receive an `HTTP 401` response.

## Add user roles to tokens

If you [enable RBAC for APIs](/docs/get-started/apis/enable-role-based-access-control-for-apis) along with "Add Permissions in the Access Token" (or enable RBAC via the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> and set the **Token Dialect** to `access_token_authz`), you will receive user permissions in your Access Tokens. To add user roles to tokens, you would use the `context.authorization` object when you create the following rule:

```js lines theme={null}
function (user, context, callback) {
  const namespace = 'http://demozero.net';
  const assignedRoles = (context.authorization || {}).roles;

  let idTokenClaims = context.idToken || {};
  let accessTokenClaims = context.accessToken || {};

  idTokenClaims[`${namespace}/roles`] = assignedRoles;
  accessTokenClaims[`${namespace}/roles`] = assignedRoles;

  context.idToken = idTokenClaims;
  context.accessToken = accessTokenClaims;

  callback(null, user, context);
}
```

## Manage Delegated Administration Extension roles using the Authorization Core feature set

Although the [Delegated Administration Extension (DAE)](/docs/customize/extensions/delegated-administration-extension) and the Authorization Core feature set are completely separate features, you can use the Authorization Core feature set to create and manage roles for the DAE if you use a rule.

1. [Create DAE roles](/docs/manage-users/access-control/configure-core-rbac/roles/create-roles) using the Authorization Core feature set. The names of the roles you create must match the names of the [pre-defined DAE roles](/docs/customize/extensions/delegated-administration-extension#assign-roles-to-users).
2. [Assign the DAE roles you created to the appropriate users](/docs/manage-users/access-control/configure-core-rbac/rbac-users/assign-roles-to-users) using the Authorization core feature set.
3. Add user roles to the DAE namespace in the ID Token. To do so, [create the following rule](/docs/customize/rules/create-rules), remembering to replace the `CLIENT_ID` placeholder value with your application's Client ID:

```js lines theme={null}
function (user, context, callback) {
    if (context.clientID === 'CLIENT_ID') {
        const namespace = 'https://example.com/auth0-delegated-admin';
        context.idToken[namespace] = {
            roles: (context.authorization || {}).roles
        };
    }
    callback(null, user, context);
}
```

<Warning>
  Auth0 returns profile information in a structured claim format as defined by the [OpenID Connect (OIDC) specification](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). This means that custom claims added to ID tokens or access tokens must [conform to guidelines and restrictions](/docs/secure/tokens/json-web-tokens/create-custom-claims) to avoid possible collisions.
</Warning>


# Cookies
Source: https://auth0.com/docs/manage-users/cookies

Describes what cookies are and how they can be used with sessions to track user authentication.

Cookies are strings of data that a web server sends to the browser. When a browser sends a future request to the web server, it sends the same string to the web server along with its request.

<Callout icon="file-lines">
  Previously in Auth0, the `samesite` cookie attribute options were `true`, `false`, `strict` or `lax`. If you didn't set the attribute manually, Auth0 would use the default value of `false`.
  Effective February 2020, Google Chrome v80 changed the way it handles cookies. To that end, Auth0 implemented the following changes to how it handles cookies:

  * Cookies without the `samesite` attribute set will be set to `lax`.
  * Cookies with `sameSite=none` must be secured, otherwise they cannot be saved in the browser's cookie jar.

  The goal of these changes are to improve security and help mitigate CSRF attacks.
</Callout>

Websites typically use cookies to ensure that users are recognized when they move between pages, so they don't get asked to log in again every time. Websites also use cookies to remember information users have entered. For example, e-commerce sites use cookies to remember the items placed in a shopping cart.

Users can choose whether to accept cookies by changing the settings in their browser.

## Cookie-based authentication

Typically, single-page apps (such as React, Vue, and AngularJS + Node), native mobile apps (such as iOS and Android), and web APIs (written in Node, Ruby, ASP.NET, or a mix of those) benefit most from token-based authentication. Traditional, server-side web applications have traditionally used cookie-based authentication.

Cookie-based authentication is implemented by each web platform differently, but at the end of the day, they all end up setting some cookie (tied to a session on the server) which represents the authenticated user. On each request, that cookie is sent and the session is deserialized from some store (in memory if it's a single server or some persistent storage if it's a server farm). We provide SDKs for most of the platforms that will tie into the corresponding authentication subsystem (such as passport on node, IPrincipal on .NET or Java, and so on).

When you build an application that requires authentication, you can use sessions and cookies to determine if a user is authenticated each time a request is made. To do this, you can choose to use either stateful or stateless cookies.

### Stateful cookies

Stateful cookies contain a pointer to a database record that stores the session information.

**Pros**:

* Have no limitations on amount of session information stored.
* Can easily clear a user's session--just remove the record from the database.

**Cons**:

* Requires a database to store the session data (but most web applications already have this).
* Increases latency because you have to make database calls to read the session (and sometimes write it) for each HTTP request a user makes.
* Can be challenging to scale when you have many users and therefore many reads/writes to your database.

### Stateless cookies

Stateless cookies are self-contained; they include all session information that you need (for authenticated users, the user ID) and reside on the client. To prevent external tampering, stateless cookies should be encrypted (or at least signed).

**Pros**:

* Can implement easily; doesn’t require a special backend.
* Reduces latency because you don't have to call a database.
* Easy to scale.

**Cons**:

* Must restrict stored session information because cookies are limited in size (max 4KB in most browsers). Although session information may be split between multiple cookies, we don't recommend it.
* Makes it difficult to revoke a session, because there is no record in a database you can delete; you’ll need to find other methods to forcefully clear a session.
* If using multiple web servers, must make sure all servers have the key to encrypt/decrypt or sign the cookie.

## Learn more

* [Sessions](/docs/manage-users/sessions)
* [Authentication API Cookies](/docs/manage-users/cookies/authentication-api-cookies)
* [SameSite Cookie Attribute Changes](/docs/manage-users/cookies/samesite-cookie-attribute-changes)
* [Secure](/docs/secure)


# Authentication API Cookies
Source: https://auth0.com/docs/manage-users/cookies/authentication-api-cookies

Learn about Authentication API cookies, including what they are, what they are used for, and how they should be handled.

The Auth0 Authentication API uses a set of HTTP cookies to enable [single sign-on (SSO)](/docs/authenticate/single-sign-on), [multi-factor authentication (MFA)](/docs/secure/multi-factor-authentication), and [attack protection](/docs/secure/attack-protection) capabilities. The table below shows some of the cookies that the Authentication API relies on and describes their purposes:

| **Cookie**          | **Feature**                 | **Purpose**                                                                                                   |
| ------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `auth0`             | Single Sign-on              | Used to implement the [Auth0 session layer](/docs/manage-users/sessions/session-layers).                      |
| `auth0_compat`      | Single Sign-on              | Fallback cookie for single sign-on on browsers that don’t support the `sameSite=None` attribute.              |
| `auth0-mf`          | Multi-factor Authentication | Used to establish the trust level for a given device.                                                         |
| `auth0-mf_compat`   | Multi-factor Authentication | Fallback cookie for multi-factor authentication on browsers that don’t support the `sameSite=None` attribute. |
| `a0_users:sess`     | Classic Login               | Used for CSRF protection in Classic Login flows.                                                              |
| `a0_users:sess.sig` | Classic Login               | Used for CSRF protection in Classic Login flows.                                                              |
| `did`               | Attack Protection           | Device identification for attack protection.                                                                  |
| `did_compat`        | Attack Protection           | Fallback cookie for anomaly detection on browsers that don’t support the `sameSite=None` attribute.           |

<Warning>
  Auth0 does not support scenarios in which the noted Authentication cookies are modified in any way, including the addition, modification, or removal of cookie attributes, whether through non-standard browsers, browser add-ons, or HTTP proxies.
</Warning>

## Cookies and custom domains

If you are using [custom domains](/docs/customize/custom-domains), cookies from the Authentication API are sent to the custom host name, or CNAME you set up in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. Each cookie's domain attribute, which specifies the domain for which the cookie is valid, is defined in the cookie request header and domain-matches with the domain attribute.

If no domain is specified, the domain attribute defaults to the request-host. If you use IETF’s [HTTP State Management Mechanism](https://datatracker.ietf.org/doc/html/rfc2109#section-2) spec to set cookies on the parent domain, the cookie will be shared with all subdomains of the parent domain.

For example, you set your CNAME to `login.example_domain.com` as a subdomain of `example_domain.com`. You host other applications under the parent domain, such as `app1.example_domain.com` and `app2.example_domain.com`. When users visit `login.example_domain.com`, cookies from `app1.example_domain.com` and `app2.example_domain.com` may be sent along with requests to Auth0’s Authentication API.

To safeguard our platform and because these cookies may grow to a considerable size and can be shared with other subdomains, Auth0 may reject requests carrying excessively large (multiple kilobytes) headers. Applications should be designed such that excessively large cookies are not sent to the Auth0 Authentication API. To learn more about cookie behavior with <Tooltip href="/docs/glossary?term=custom+domains">custom domains</Tooltip>, read [Sending Cookies to the Origin Server](https://datatracker.ietf.org/doc/html/rfc2109#section-4.3.4).

## Learn more

* [SameSite Cookie Attribute Changes](/docs/manage-users/cookies/samesite-cookie-attribute-changes)
* [Verify Domain](/docs/troubleshoot/basic-issues/verify-domain)
* [Troubleshoot Multi-Factor Authentication Issues](/docs/troubleshoot/authentication-issues/troubleshoot-mfa-issues)


# SameSite Cookie Attribute Changes
Source: https://auth0.com/docs/manage-users/cookies/samesite-cookie-attribute-changes

Describes how browser changes, such as the SameSite cookie attribute, affects your web applications that embed content from third-party domains.

Cookies, which are used for authentication and the maintenance of sessions, can be secured by setting attributes. Auth0 uses cookies for the following:

* OIDC Enterprise with `form_post`
* <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> HTTP-POST Binding
* Web message (aka `checkSession`)

## SameSite attributes

You can add [SameSite cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite) attributes in the `set-cookie` HTTP response header to restricts browser behavior. It may prevent the browser from sending the cookie's `key=value` pair based on the type of interaction that triggered the HTTP request.

Accepted attribute values are as follows:

| Attribute | Description                                                                                                                                                            |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `strict`  | Send the cookie if the user is navigating within the website origin bounds                                                                                             |
| `lax`     | Send the cookie if the user is navigating between domains but not for 3rd party contexts (iframes or posts)                                                            |
| `none`    | Send the cookie with requests crossing the website origin bounds. Unless other conditions are present (i.e., third-party cookies are blocked), do not send the cookie. |

Some of the cookie attributes you may be familiar with include:

| Attribute           | Description                                                                                                                                                                           |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `httpOnly`          | Allows a cookie to be sent only with HTTP requests; not readable using Javascript's `document.cookie`                                                                                 |
| `secure`            | Allows the browser to send the cookie only to a secure context; whether the context is considered secure or not is browser-dependent, but this typically requires the use of HTTPS    |
| `max-age / expires` | Controls whether the cookie is a **session** cookie (e.g., dropped when your browser terminates its session) or **persistent** (e.g., the cookie persists beyond the browser session) |

The browser, upon receipt, parses the headers and updates its cookie jar accordingly.

## Browser cookie changes

As of February 2020, Google Chrome v80 changed the way it handles cookies. Auth0 implemented the following changes in the way it handles cookies:

* Cookies without the `SameSite` attribute set will be set to `lax`
* Cookies with `SameSite=none` must be secured; otherwise they cannot be saved in the browser's cookie jar

The goal of these changes is to improve security and help mitigate CSRF attacks.

These changes affect the following cookies:

* `auth0` (handles user sessions)
* `auth0-mf` (handles information relevant to <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip>)
* `did` (the identifier for a device/user agent)

For these cookies, Auth0 will:

* Set the `SameSite` attribute to `none`, with the cookie requiring the use of HTTPS (regardless of environment)
* Set fallback cookies in the event that a legacy browser does not support `SameSite` being set to `None`. These fallback cookies are `auth0_compat`, `auth0-mf_compat` and `did_compat`

The diagram below shows what happens during a fresh interaction. The end user requests a page not previously visited. The server changes the way it renders when the visitor returns and sets a seen cookie. The grey part of the `set-cookie` header is the actual cookie `key=value.` The red portion are the cookie attributes the browser stores in the cookie jar to decide later if it should include the cookie `key+value` pair in requests.

<Frame>
  <img alt="sameSite Cookie Attributes Fresh Interaction Flow" />
</Frame>

The following diagram shows what happens if you make the same request using the same browsing session. The request goes to the same server, and because the cookie attributes don't prohibit the seen cookie to be sent, it is automatically included as a cookie header in the request. The server will now respond differently based on the fact that it received this cookie.

<Frame>
  <img alt="sameSite Cookie Attributes Cookie Return Interaction flow" />
</Frame>

## Features affected

The table below shows how the `SameSite` attribute changes may affect your apps.

| App Behavior                                                                                                                                         | Affected by Change |
| ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| Cookies set as `sameSite=none` when the website is not `https://`                                                                                    | Yes                |
| Cookies don't have explicit `sameSite` attribute value set and are required in a cross-origin context (such as HTTP form\_post, embedding an iframe) | Yes                |
| Native apps (everything not cookies + web based)                                                                                                     | No (M2M)           |
| Already setting an explicit `sameSite` cookie attribute value                                                                                        | No                 |
| Different subdomain on the same eTLD+1 (app is on the same eTLD+1 as the custom domain Auth0 tenant)                                                 | Potentially        |

If you are using a web app with sessions (e.g. for saving user preferences, shopping carts, etc.), and you allow users to sign in using <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> such as Google, Github, or Auth0, then you rely on cookies to achieve that functionality. There are browser cookie behavior changes that may break the user experience. Google Chrome, for example, is the first browser vendor to roll out a change that might not be compatible with your web application.

You may notice that the Google Chrome and Microsoft Edge specs for setting `SameSite` to undefined has changed from `SameSite` defaulting to `none` to `lax` instead.

For example, let's say you build a new UI and have several services that you proxy to via an Auth0 gateway. At this gateway, you create a cookie session. If you make a cross-origin request, you may see this warning in the Javascript console:

`A cookie associated with a cross-site resource (URL) was set without the SameSite attribute. A future release of Chrome will only deliver cookies with cross-site requests if they are set with SameSite=None and Secure. You can review cookies in developer tools under Application>Storage>Cookies and see more details at https://www.chromestatus.com/feature/5088147346030592 and https://www.chromestatus.com/feature/5633521622188032`

## Actions you need to take

To prepare for this change, you should:

* Review the list of [unsupported browsers](https://www.chromium.org/updates/same-site/incompatible-clients).
* Set your application to use `SameSite=none` if it uses `response_mode=form_post` when interacting with Auth0 (note that Chrome makes no exceptions, even for `localhost`)
* Set your cookie as secure if its `SameSite` attribute equals `None.` Otherwise, it will be rejected by the browser. If you use HTTP for your Callback URLs, these will break if you use such cookies for binding the authorization request state/<Tooltip href="/docs/glossary?term=nonce">nonce</Tooltip>. Therefore, you must either use HTTPS or set `SameSite=lax`


# Authenticate Single-Page Apps With Cookies
Source: https://auth0.com/docs/manage-users/cookies/spa-authenticate-with-cookies

Describes how to use your backend server to authenticate a single-page app (SPA) with cookies.

Securing a single-page app (SPA) can be a challenge. However, if your SPA meets the following criteria, then you can simplify your implementation by using cookies to authenticate.

* Served to the client using your own backend.
* Has the same domain as your backend.
* Makes API calls that require authentication to your backend.

Here is a description of this approach as well as a sample implementation using [Node.js](https://nodejs.org/en/).

## How it works

The steps below show how tokens are retrieved and used. In this approach, the [Implicit Flow with Form Post](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post) is used instead of a traditional [Authorization Code Flow with Proof Key for Code Exchange](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce). This is because Form Post Response Mode is a simpler way to implement login when it’s your own resource you are requesting to access.

<Frame>
  <img alt="Authenticate Single-Page Apps Using Cookies How it Works part 1 diagram" />
</Frame>

1. The user accesses a protected route using the browser, or performs some action that requires an authentication step to be initiated (such as clicking on a Login button)
2. The browser client redirects to a `/login` route on the backend, or to the protected route depending on what the user did
3. The backend constructs a request to the authorization server’s `/authorize` endpoint and redirects the browser client there
4. The user is prompted to authenticate themselves using whatever method the authorization server presents
5. The authorization server POSTs the tokens to the redirect URI as a URL-encoded form post. The backend is able to retrieve those tokens by parsing the body data.

At this point, the user is authenticated and the backend has the required tokens. A cookie can now be created to represent this state on the client. The client browser is then redirected to a route that serves the SPA and also receives the authentication cookie.

From now on, this cookie is traded between the client and backend when API calls are made using an AJAX call. On each request, the backend verifies if the cookie is still valid and if so, allows the request to continue.

<Frame>
  <img alt="Authenticate Single-Page Apps Using Cookies How it Works part 2 diagram" />
</Frame>

### Invalid or missing cookies

When implementing this approach you'll need to handle cases where the authentication cookie is invalid or missing. The API call to the backend from the client happens in the background, so the client has to deal with any response from the server indicating the user should reauthenticate.

In the following sample application, this case is handled in a naive way by prompting the user to re-authenticate if the API call results in a 302 Redirect result. The 302 occurs because, upon unsuccessful validation of the cookie, the server tries to redirect to the Authorization endpoint of the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip> and sends this response to the client.

## Example

The example application uses Node.js and Express to demonstrate the concepts covered above.

### Prerequisites

* To follow along, make sure you have the [latest version of Node](https://nodejs.org/en/download/) installed.
* Once Node is installed, [download or clone the source code](https://github.com/auth0-blog/spa-cookie-demo/) and open the project folder inside a terminal window.

  ```bash lines theme={null}
  # Clone the tutorial respository using SSH
  git clone git@github.com:auth0-blog/spa-cookie-demo
  # ... or if you use HTTPS:
  git clone https://github.com/auth0-blog/spa-cookie-demo.git
  # Move into the project directory
  cd spa-cookie-demo
  ```
* The `master` branch represents the state of the application before any authentication is added. If you would like to refer to the final version of the application, check out the `with-oidc` branch:
  `git checkout with-oidc`

### Initialize the Node.js app

Install the application dependencies by running `npm install` from your terminal window. To run the application, use `npm run dev`. This starts the Express server. Go to [http://localhost:3000](http://localhost:3000/) in your browser to view the application.

The development servers uses `nodemon`, which automatically restarts whenever it detects any file changes.

### Explore the application

With the application open at [http://localhost:3000](http://localhost:3000/), click the **Call API** button. You should see a message displayed on the screen.

<Frame>
  <img alt="SPA Authentication with Cookies Explore the Application screen" />
</Frame>

Note that you were able to make the API call without being logged in. Let's fix that by adding some middleware that requires the user to authenticate before the API call can be made.

### Set up environment

For the application to work with authentication, `express-openid-connect` requires some environment variables to be present. For this application, these variables can be specified in a `.env` file. Create a `.env` file in the root of the project directory and populate it with the following:

```shell .env lines theme={null}
ISSUER_BASE_URL="<YOUR OIDC URL>"
CLIENT_ID="<YOUR OIDC CLIENT ID>"
BASE_URL="http://localhost:3000"
APP_SESSION_SECRET="<YOUR SECRET VALUE>"
```

### Set up app in Auth0

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and click **Create Application**.
2. Name your new application, select **Regular Web Applications**, and click **Create**
3. In the **Settings** for your new app, add `http:/localhost:3000/callback` to **Allowed Callback URLs**.
4. Add `http:/localhost:3000` to **Allowed Logout URLs**.
5. Click **Save Changes**.
6. Go to [Dashboard > Authentication > Social](https://manage.auth0.com/#/connections/social) and set up some social connections. Enable them for your app in the **Application** options in the **Connections** tab. The example uses username/password database, Facebook, Google, and X.
7. On the **Settings** screen, note the domain and client ID settings at the top.
8. There are two values that need to be configured as part of the application. Reopen the `.env` file and set these values:

   <AuthCodeBlock />

### Run the app

1. With the server and environment configuration done, find your browser window that has the application open. If you've closed the browser and stopped the server, run the following from the terminal to restart the application:
   `npm run dev`
2. Open `http://localhost:3000` in the browser. From a user interface perspective, the app should look the same, however this time when the **Call API** button is clicked, you should receive a warning that the user is not logged in. Also note that you do not see the "Hello, World" message as before since the call to the API has been rejected.
3. Click **Log in now** to log in. Once you have been authenticated, you'll return to the app and see an updated UI that reflects your new logged-in state. You should be able to press the **Call API** button once more to invoke an API call to the server, and it now works.
4. Click the **Profile** link at the top of the page to show user information retrieved from the ID token.

## Learn more

* [Implicit Flow with Form Post](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post)
* [Secure](/docs/secure)
* [SameSite Cookie Attribute Changes](/docs/manage-users/cookies/samesite-cookie-attribute-changes)


# My Account API
Source: https://auth0.com/docs/manage-users/my-account-api

Learn how you can empower your users to manage their own account information with the My Account API.

<Warning>
  The My Account API is available in Limited Early Access. To request access, contact your Auth0 account manager. To learn more about Auth0's product release cycle, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

The Auth0 My Account API provides a dedicated set of endpoints for users to manage their own account information. Customers can use these APIs to build self-service experiences in their applications or progressively add details to a user account.

The My Account API operates within the context of the currently logged-in user and can be used directly within user-facing applications.

<Callout icon="file-lines">
  **Using Auth0 domain vs. custom domain**

  The My Account API supports using your canonical Auth0 domain or your custom domain, but you must use the same one throughout the entire process, including:

  * Getting an access token
  * Setting the `audience` value
  * Calling the My Account API endpoint

  For more information, read [Custom Domains](/docs/customize/custom-domains).
</Callout>

## Activate the My Account API

You can activate the My Account API for your tenant in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>:

1. Navigate to **Applications > APIs**.
2. Locate the **MyAccount API** banner.
3. Select **Activate**.

<Frame>
  <img alt="" />
</Frame>

By default, the My Account API is created with the following application API access policies:

* `require_client_grant` for user flows
* `deny_all` for client (machine-to-machine) flows

For an application to access the My Account API on the user's behalf, you must explicitly create a client grant for that application, which allows you to define the maximum scopes the application can request. Alternatively, you can change the policy for user access flows to `allow_all`, which allows any application in your tenant to request any scope from the My Account API.

Auth0 does not recommend using `allow_all` for user access flows because the My Account API exposes sensitive information and operations. You should follow a least privilege principle with My Account API to ensure applications only get access to what they truly need, minimizing potential security risks.

The final permissions granted to the application will be determined by the intersection of the scopes allowed by the application API access policy, the Role-Based Access Control (RBAC) permissions assigned to the end user, and any user consent given (if applicable).

<Callout icon="file-lines">
  You cannot update the application API policy for client access to the My Account API, which means you cannot access the My Account API using the Client Credentials Flow.
</Callout>

To learn more about how to manage application API access policies and their associated client grants, read [Application Access to APIs: Client Grants](/docs/get-started/applications/application-access-to-apis-client-grants).

## Get an access token

You can get an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> for the My Account API in the same way you’d get an access token for one of your own APIs.

<Callout icon="file-lines">
  If you’re going to allow the My Account API to perform sensitive operations (such as enrolling an authentication method), we strongly recommend that you use [step-up authentication](/docs/secure/multi-factor-authentication/step-up-authentication) to enforce additional security policies through [multi-factor authentication (MFA)](/docs/secure/multi-factor-authentication).
</Callout>

If you’re using <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>, read the following articles:

* [Call Your API Using the Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/call-your-api-using-the-authorization-code-flow)
* [Call Your API Using the Authorization Code Flow with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/call-your-api-using-the-authorization-code-flow-with-pkce)

If you’re using embedded login, read the following articles:

* [Call Your API Using Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow/call-your-api-using-resource-owner-password-flow)
* [Login Flow with Native Passkeys API](/docs/authenticate/database-connections/passkeys/native-passkeys-api#login-flow)

### Audience

The <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> of the My Account API is `https://{yourDomain}/me/`.

### Scope

The My Account API supports the following scopes:

<table>
  <thead>
    <tr>
      <th><strong>Scope</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>create:me:authentication\_methods</code></td>
      <td>Allows the user to enroll a new authentication method.</td>
    </tr>

    <tr>
      <td><code>read:me:authentication\_methods</code></td>
      <td>Allows the user to view existing authentication methods.</td>
    </tr>

    <tr>
      <td><code>update:me:authentication\_methods</code></td>
      <td>Allows the user to modify existing authentication methods.</td>
    </tr>

    <tr>
      <td><code>delete:me:authentication\_methods</code></td>
      <td>Allows the user to modify existing authentication methods.</td>
    </tr>

    <tr>
      <td><code>read:me:factors</code></td>
      <td>Allows the user to view the factors they can enroll.</td>
    </tr>
  </tbody>
</table>

For [Connected Accounts with Token Vault](/docs/secure/tokens/connected-accounts-for-token-vault), the My Account API supports the following scopes:

<table>
  <thead>
    <tr>
      <th><strong>Scope</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>create:me:connected\_accounts</code></td>
      <td>Allows the user to connect a new account to their user profile.</td>
    </tr>

    <tr>
      <td><code>read:me:connected\_accounts</code></td>
      <td>Allows the user to view the existing connected accounts linked to their user profile.</td>
    </tr>

    <tr>
      <td><code>delete:me:connected\_accounts</code></td>
      <td>Allows the user to delete a connected account from their user profile.</td>
    </tr>
  </tbody>
</table>

### Examples

#### Universal Login with authorization code flow

##### Step 1: Request authorization code

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/authorize?response_type=code&client_id={yourClientId}&redirect_uri=%7ByourRedirectUri%7D&scope=create%3Ame%3Aauthentication_methods&offline_access=&audience=https%3A%2F%2F{yourDomain}%2Fme%2F'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/authorize?response_type=code&client_id={yourClientId}&redirect_uri=%7ByourRedirectUri%7D&scope=create%3Ame%3Aauthentication_methods&offline_access=&audience=https%3A%2F%2F{yourDomain}%2Fme%2F");
  var request = new RestRequest(Method.GET);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/authorize?response_type=code&client_id={yourClientId}&redirect_uri=%7ByourRedirectUri%7D&scope=create%3Ame%3Aauthentication_methods&offline_access=&audience=https%3A%2F%2F{yourDomain}%2Fme%2F"

  	req, _ := http.NewRequest("GET", url, nil)

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/authorize?response_type=code&client_id={yourClientId}&redirect_uri=%7ByourRedirectUri%7D&scope=create%3Ame%3Aauthentication_methods&offline_access=&audience=https%3A%2F%2F{yourDomain}%2Fme%2F")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/authorize',
    params: {
      response_type: 'code',
      client_id: '{yourClientId}',
      redirect_uri: '{yourRedirectUri}',
      scope: 'create:me:authentication_methods',
      offline_access: '',
      audience: 'https://{yourDomain}/me/'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/authorize?response_type=code&client_id={yourClientId}&redirect_uri=%7ByourRedirectUri%7D&scope=create%3Ame%3Aauthentication_methods&offline_access=&audience=https%3A%2F%2F{yourDomain}%2Fme%2F"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/authorize?response_type=code&client_id={yourClientId}&redirect_uri=%7ByourRedirectUri%7D&scope=create%3Ame%3Aauthentication_methods&offline_access=&audience=https%3A%2F%2F{yourDomain}%2Fme%2F",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  conn.request("GET", "/{yourDomain}/authorize?response_type=code&client_id={yourClientId}&redirect_uri=%7ByourRedirectUri%7D&scope=create%3Ame%3Aauthentication_methods&offline_access=&audience=https%3A%2F%2F{yourDomain}%2Fme%2F")

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/authorize?response_type=code&client_id={yourClientId}&redirect_uri=%7ByourRedirectUri%7D&scope=create%3Ame%3Aauthentication_methods&offline_access=&audience=https%3A%2F%2F{yourDomain}%2Fme%2F")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/authorize?response_type=code&client_id={yourClientId}&redirect_uri=%7ByourRedirectUri%7D&scope=create%3Ame%3Aauthentication_methods&offline_access=&audience=https%3A%2F%2F{yourDomain}%2Fme%2F")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"

  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()
  ```
</AuthCodeGroup>

##### Step 2: Exchange code for access token

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/json' \
    --data '{"grant_type": "authorization_code","client_id": "{yourClientId}","client_secret": "{yourClientId}","code": "{yourAuthorizationCode}","redirect_uri": "{yourRedirectUri}","audience": "{yourAudience}","scope": "create:me:authentication_methods","offline_access": ""}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"grant_type": "authorization_code","client_id": "{yourClientId}","client_secret": "{yourClientId}","code": "{yourAuthorizationCode}","redirect_uri": "{yourRedirectUri}","audience": "{yourAudience}","scope": "create:me:authentication_methods","offline_access": ""}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("{"grant_type": "authorization_code","client_id": "{yourClientId}","client_secret": "{yourClientId}","code": "{yourAuthorizationCode}","redirect_uri": "{yourRedirectUri}","audience": "{yourAudience}","scope": "create:me:authentication_methods","offline_access": ""}")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/json")
    .body("{"grant_type": "authorization_code","client_id": "{yourClientId}","client_secret": "{yourClientId}","code": "{yourAuthorizationCode}","redirect_uri": "{yourRedirectUri}","audience": "{yourAudience}","scope": "create:me:authentication_methods","offline_access": ""}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/json'},
    data: {
      grant_type: 'authorization_code',
      client_id: '{yourClientId}',
      client_secret: '{yourClientId}',
      code: '{yourAuthorizationCode}',
      redirect_uri: '{yourRedirectUri}',
      audience: '{yourAudience}',
      scope: 'create:me:authentication_methods',
      offline_access: ''
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"grant_type": @"authorization_code",
                                @"client_id": @"{yourClientId}",
                                @"client_secret": @"{yourClientId}",
                                @"code": @"{yourAuthorizationCode}",
                                @"redirect_uri": @"{yourRedirectUri}",
                                @"audience": @"{yourAudience}",
                                @"scope": @"create:me:authentication_methods",
                                @"offline_access": @"" };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{"grant_type": "authorization_code","client_id": "{yourClientId}","client_secret": "{yourClientId}","code": "{yourAuthorizationCode}","redirect_uri": "{yourRedirectUri}","audience": "{yourAudience}","scope": "create:me:authentication_methods","offline_access": ""}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"grant_type": "authorization_code","client_id": "{yourClientId}","client_secret": "{yourClientId}","code": "{yourAuthorizationCode}","redirect_uri": "{yourRedirectUri}","audience": "{yourAudience}","scope": "create:me:authentication_methods","offline_access": ""}"

  headers = { 'content-type': "application/json" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request.body = "{"grant_type": "authorization_code","client_id": "{yourClientId}","client_secret": "{yourClientId}","code": "{yourAuthorizationCode}","redirect_uri": "{yourRedirectUri}","audience": "{yourAudience}","scope": "create:me:authentication_methods","offline_access": ""}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/json"]
  let parameters = [
    "grant_type": "authorization_code",
    "client_id": "{yourClientId}",
    "client_secret": "{yourClientId}",
    "code": "{yourAuthorizationCode}",
    "redirect_uri": "{yourRedirectUri}",
    "audience": "{yourAudience}",
    "scope": "create:me:authentication_methods",
    "offline_access": ""
  ] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

#### Embedded login with native passkeys

##### Step 1: Request login challenge

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/passkey/challenge' \
    --header 'content-type: application/json' \
    --data '{"client_id": "{yourDomain}"}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/passkey/challenge");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"client_id": "{yourDomain}"}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/passkey/challenge"

  	payload := strings.NewReader("{"client_id": "{yourDomain}"}")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/passkey/challenge")
    .header("content-type", "application/json")
    .body("{"client_id": "{yourDomain}"}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/passkey/challenge',
    headers: {'content-type': 'application/json'},
    data: {client_id: '{yourDomain}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"client_id": @"{yourDomain}" };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/passkey/challenge"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/passkey/challenge",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{"client_id": "{yourDomain}"}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"client_id": "{yourDomain}"}"

  headers = { 'content-type': "application/json" }

  conn.request("POST", "/{yourDomain}/passkey/challenge", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/passkey/challenge")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request.body = "{"client_id": "{yourDomain}"}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/json"]
  let parameters = ["client_id": "{yourDomain}"] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/passkey/challenge")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

##### Step 2: Authenticate existing user

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/json' \
    --data '{  "grant_type": "urn:okta:params:oauth:grant-type:webauthn",  "client_id": "{yourClientId}",  "scope": "create:me:authentication_methods offline_access",  "audience": "https://{yourDomain}/me/"  "auth_session": "{sessionIdFromTheFirstRequest}",  "authn_response": "{authenticatorResponse}"}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{ "grant_type": "urn:okta:params:oauth:grant-type:webauthn", "client_id": "{yourClientId}", "scope": "create:me:authentication_methods offline_access", "audience": "https://{yourDomain}/me/" "auth_session": "{sessionIdFromTheFirstRequest}", "authn_response": "{authenticatorResponse}"}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("{  "grant_type": "urn:okta:params:oauth:grant-type:webauthn",  "client_id": "{yourClientId}",  "scope": "create:me:authentication_methods offline_access",  "audience": "https://{yourDomain}/me/"  "auth_session": "{sessionIdFromTheFirstRequest}",  "authn_response": "{authenticatorResponse}"}")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/json")
    .body("{  "grant_type": "urn:okta:params:oauth:grant-type:webauthn",  "client_id": "{yourClientId}",  "scope": "create:me:authentication_methods offline_access",  "audience": "https://{yourDomain}/me/"  "auth_session": "{sessionIdFromTheFirstRequest}",  "authn_response": "{authenticatorResponse}"}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/json'},
    data: '{  "grant_type": "urn:okta:params:oauth:grant-type:webauthn",  "client_id": "{yourClientId}",  "scope": "create:me:authentication_methods offline_access",  "audience": "https://{yourDomain}/me/"  "auth_session": "{sessionIdFromTheFirstRequest}",  "authn_response": "{authenticatorResponse}"}'
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json" };

  NSData *postData = [[NSData alloc] initWithData:[@"{  "grant_type": "urn:okta:params:oauth:grant-type:webauthn",  "client_id": "{yourClientId}",  "scope": "create:me:authentication_methods offline_access",  "audience": "https://{yourDomain}/me/"  "auth_session": "{sessionIdFromTheFirstRequest}",  "authn_response": "{authenticatorResponse}"}" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{  "grant_type": "urn:okta:params:oauth:grant-type:webauthn",  "client_id": "{yourClientId}",  "scope": "create:me:authentication_methods offline_access",  "audience": "https://{yourDomain}/me/"  "auth_session": "{sessionIdFromTheFirstRequest}",  "authn_response": "{authenticatorResponse}"}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{  "grant_type": "urn:okta:params:oauth:grant-type:webauthn",  "client_id": "{yourClientId}",  "scope": "create:me:authentication_methods offline_access",  "audience": "https://{yourDomain}/me/"  "auth_session": "{sessionIdFromTheFirstRequest}",  "authn_response": "{authenticatorResponse}"}"

  headers = { 'content-type': "application/json" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  rrequire 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request.body = "{  "grant_type": "urn:okta:params:oauth:grant-type:webauthn",  "client_id": "{yourClientId}",  "scope": "create:me:authentication_methods offline_access",  "audience": "https://{yourDomain}/me/"  "auth_session": "{sessionIdFromTheFirstRequest}",  "authn_response": "{authenticatorResponse}"}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/json"]

  let postData = NSData(data: "{  "grant_type": "urn:okta:params:oauth:grant-type:webauthn",  "client_id": "{yourClientId}",  "scope": "create:me:authentication_methods offline_access",  "audience": "https://{yourDomain}/me/"  "auth_session": "{sessionIdFromTheFirstRequest}",  "authn_response": "{authenticatorResponse}"}".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

## Rate limits

During Early Access, the My Account API is limited at a tenant level to 25 requests per second.

## Cross-Origin Requests

If you intend to call the My Account API directly from a browser-based application (like a Single Page Application) running on a different domain than your Auth0 tenant, you will encounter browser security policies known as Cross-Origin Resource Sharing (CORS). By default, browsers block these cross-origin requests.

To allow your application to successfully make requests to the API, you must add your application's domain (its "origin") to your client's configuration:

1. Navigate to [Dashboard > Applications](https://manage.auth0.com/#/applications). Select the application to view.
2. Under Cross-Origin Authentication, toggle on Allow Cross-Origin Authentication.
3. Locate **Allowed Origins (CORS)**, and enter your application's origin URL.
4. Select **Save**.

To learn more, read [Configure Cross-Origin Resource Sharing](/docs/get-started/applications/set-up-cors).

<Callout icon="file-lines">
  If you do not need to use CORS for your application, ensure that Allow Cross-Origin Authentication is toggled off. Adding your application's URL to this list tells Auth0 to trust requests from that origin, allowing your client-side application to access the API.
</Callout>


# Configure Organizations
Source: https://auth0.com/docs/manage-users/organizations/configure-organizations

Reference the various options you have to configure organizations.

You can configure Organizations using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. To learn more about the steps involved in configuring your organization, read [Create Your First Organization](/docs/manage-users/organizations/create-first-organization).

<Card title="Availability varies by Auth0 plan">
  Your Auth0 plan or custom agreement affects whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

| **Read...**                                                                                                                                           | **To learn...**                                                                                                                             |
| ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| [Create Organizations](/docs/manage-users/organizations/configure-organizations/create-organizations)                                                 | How to create organizations using the Dashboard or the Management API.                                                                      |
| [Delete Organizations](/docs/manage-users/organizations/configure-organizations/delete-organizations)                                                 | How to delete organizations using the Dashboard or the Management API.                                                                      |
| [Use Organization Names in Authentication API](/docs/manage-users/organizations/configure-organizations/use-org-name-authentication-api)              | How to use organization names in the `/authorize` and `SAML` endpoints of the Authentication API.                                           |
| [Define Organization Behavior](/docs/manage-users/organizations/configure-organizations/define-organization-behavior)                                 | How to define organization behavior within applications.                                                                                    |
| [Enable Organization Connections](/docs/manage-users/organizations/configure-organizations/enable-connections)                                        | How to enable organization connections using the Dashboard or the Management API.                                                           |
| [Disable Organization Connections](/docs/manage-users/organizations/configure-organizations/disable-connections)                                      | How to disable organization connections using the Dashboard or the Management API.                                                          |
| [Invite Organization Members](/docs/manage-users/organizations/configure-organizations/invite-members)                                                | How to invite new team members to your organization.                                                                                        |
| [Send Organization Membership Invitations](/docs/manage-users/organizations/configure-organizations/send-membership-invitations)                      | How to send organization membership invitations to users using the Dashboard or the Management API.                                         |
| [Grant Just-In-Time Membership to an Organization Connection](/docs/manage-users/organizations/configure-organizations/grant-just-in-time-membership) | How to grant just-in-time membership to allow users that log in via a connection to automatically be granted membership to an organization. |
| [Assign Members Directly](/docs/manage-users/organizations/configure-organizations/assign-members)                                                    | How to assign members to an organization using the Dashboard or the Management API.                                                         |
| [Remove Members Directly](/docs/manage-users/organizations/configure-organizations/remove-members)                                                    | How to remove members from an organization using the Dashboard or the Management API.                                                       |
| [Add Roles to Organization Members](/docs/manage-users/organizations/configure-organizations/add-member-roles)                                        | How to add member roles to organizations using the Dashboard or the Management API.                                                         |
| [Remove Roles from Organization Members](/docs/manage-users/organizations/configure-organizations/remove-member-roles)                                | How to remove member roles from organizations using the Dashboard or the Management API.                                                    |
| [Retrieve Organizations](/docs/manage-users/organizations/configure-organizations/retrieve-organizations)                                             | How to retrieve Organizations using the Dashboard or the Management API.                                                                    |
| [Search for Organizations](/docs/manage-users/organizations/configure-organizations/search-for-organizations)                                         | How to search for Organizations using the Dashboard.                                                                                        |
| [Retrieve Connections](/docs/manage-users/organizations/configure-organizations/retrieve-connections)                                                 | How to retrieve Organization connections using the Auth0 Management API.                                                                    |
| [Retrieve Members](/docs/manage-users/organizations/configure-organizations/retrieve-members)                                                         | How to retrieve a list of members for an organization using the Dashboard or the Management API.                                            |
| [Retrieve User's Memberships](/docs/manage-users/organizations/configure-organizations/retrieve-user-membership)                                      | How to retrieve a list of organizations to which a user is assigned membership using the Management API.                                    |
| [Retrieve Member Roles](/docs/manage-users/organizations/configure-organizations/retrieve-member-roles)                                               | How to retrieve a list of roles assigned to a member of an organization using the Dashboard or the Management API.                          |

## Learn more

* [Understand How Auth0 Organizations Work](/docs/manage-users/organizations/organizations-overview)
* [Create Your First Organization](/docs/manage-users/organizations/create-first-organization)
* [Custom Development with Organizations](/docs/manage-users/organizations/custom-development)
* [Work with Tokens and Organizations](/docs/manage-users/organizations/using-tokens)


# Add Roles to Organization Members
Source: https://auth0.com/docs/manage-users/organizations/configure-organizations/add-member-roles

Learn how to add roles to Organization members using the Auth0 Dashboard or Management API.

Each [organization](/docs/manage-users/organizations/organizations-overview) member can be assigned one or more roles, which are applied when users log in through the organization. To learn more about roles and their behavior, read [Role-based Access Control](/docs/manage-users/access-control/rbac).

You can add roles to members in organizations using either the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

To enable a role for an organization member, you must have already [created the role](/docs/manage-users/access-control/configure-core-rbac/roles/create-roles) in your tenant.

## Auth0 Dashboard

To add roles to an organization member via the Auth0 Dashboard:

1. Navigate to [Auth0 Dashboard > Organizations](https://manage.auth0.com/#/organizations), and select the organization for which you want to configure membership.
2. Select the **Members** view, and select the name of the member to which you would like to add a role.
3. Select **Assign** role.
4. Enter the role name(s) you would like to assign to the member, and select **Add role(s) to organization**.

## Management API

To add roles to an organization member via the Management API:
Make a `POST` call to the `Create Organization Member Roles` endpoint. Be sure to replace `ORG_ID`, `MGMT_API_ACCESS_TOKEN`, `USER_ID`, and `ROLE_ID` placeholder values with your organization ID, Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, user ID, and role ID, respectively.

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request POST \
    --url https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "roles": [ "ROLE_ID", "ROLE_ID", "ROLE_ID" ] }'
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("application/json", "{ \"roles\": [ \"ROLE_ID\", \"ROLE_ID\", \"ROLE_ID\" ] }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines expandable theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles"

  	payload := strings.NewReader("{ \"roles\": [ \"ROLE_ID\", \"ROLE_ID\", \"ROLE_ID\" ] }")

  	req, _ := http.NewRequest("POST", 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))

  }
  ```

  ```java Java lines theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ \"roles\": [ \"ROLE_ID\", \"ROLE_ID\", \"ROLE_ID\" ] }")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: {roles: ['ROLE_ID', 'ROLE_ID', 'ROLE_ID']}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C lines expandable theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"roles": @[ @"ROLE_ID", @"ROLE_ID", @"ROLE_ID" ] };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP lines expandable theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ \"roles\": [ \"ROLE_ID\", \"ROLE_ID\", \"ROLE_ID\" ] }",
    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;
  }
  ```

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("{yourDomain}")

  payload = "{ \"roles\": [ \"ROLE_ID\", \"ROLE_ID\", \"ROLE_ID\" ] }"

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
      'cache-control': "no-cache"
      }

  conn.request("POST", "/api/v2/organizations/ORG_ID/members/USER_ID/roles", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request["cache-control"] = 'no-cache'
  request.body = "{ \"roles\": [ \"ROLE_ID\", \"ROLE_ID\", \"ROLE_ID\" ] }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift lines expandable theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = ["roles": ["ROLE_ID", "ROLE_ID", "ROLE_ID"]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

<Callout icon="file-lines">
  **Find Your Auth0 Domain**

  If your Auth0 domain is your tenant name, your regional subdomain (unless your tenant is in the US region and was created before June 2020), plus `.auth0.com`. For example, if your tenant name were `travel0`, your Auth0 domain name would be `travel0.us.auth0.com`. (If your tenant were in the US and created before June 2020, then your domain name would be `https://travel0.auth0.com`.)

  If you are using custom domains, this should be your custom domain name.
</Callout>

| Value                   | Description                                                                                                                                              |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ORG_ID`                | ID of the organization for which you want to add roles to a member.                                                                                      |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the scope `create:organization_member_roles`. |
| `USER_ID`               | ID of the user to which you want to add the specified role(s).                                                                                           |
| `ROLE_ID`               | ID of the role you want to add to the specified user for the specified organization. Maximum of 100 roles per user.                                      |

##### Response status codes

Possible response status codes are as follows:

| Status code | Error code             | Message                                                                                              | Cause                                                                              |
| ----------- | ---------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `204`       |                        | Roles successfully associated with user.                                                             |                                                                                    |
| `400`       | `invalid_body`         | Invalid request body. The message will vary depending on the cause.                                  | The request payload is not valid.                                                  |
| `400`       | `invalid_query_string` | Invalid request query string. The message will vary depending on the cause.                          | The query string is not valid.                                                     |
| `401`       |                        | Invalid token.                                                                                       |                                                                                    |
| `401`       |                        | Invalid signature received for JSON Web Token validation.                                            |                                                                                    |
| `401`       |                        | Client is not global.                                                                                |                                                                                    |
| `403`       | `insufficient_scope`   | Insufficient scope; expected any of: `create:organization_member_roles`.                             | Tried to read/write a field that is not allowed with provided bearer token scopes. |
| `429`       |                        | Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. |                                                                                    |


# Assign Members to an Organization
Source: https://auth0.com/docs/manage-users/organizations/configure-organizations/assign-members

Learn how to assign members directly to an Organization using either the Auth0 Dashboard or Management API.

To assign a member to your [organization](/docs/manage-users/organizations/organizations-overview), you must have already [created the user](/docs/manage-users/user-accounts/create-users) in your tenant. If you cannot find a user, you can [invite them](/docs/manage-users/organizations/configure-organizations/invite-members) instead.

To manage members directly, you can use either the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## Auth0 Dashboard

To assign members via the Auth0 Dashboard:

1. Navigate to [Auth0 Dashboard > Organizations](https://manage.auth0.com/#/organizations), and select the organization for which you want to configure membership.
2. Select the **Members** view, select **Add members**, and select **Add Users**.
3. Enter the name(s) of the user you would like to assign as a member to the organization, and select **Add user(s) to organization**.

## Management API

To assign members via the Management API:

Make a `POST` call to the `Create Organization Members` endpoint. Be sure to replace `ORG_ID`, `MGMT_API_ACCESS_TOKEN`, and `USER_ID` placeholder values with your organization ID, Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, and user IDs, respectively.

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request POST \
    --url https://{yourDomain}/api/v2/organizations/ORG_ID/members \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "members": [ "USER_ID", "USER_ID", "USER_ID" ] }'
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/organizations/ORG_ID/members");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("application/json", "{ \"members\": [ \"USER_ID\", \"USER_ID\", \"USER_ID\" ] }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines expandable theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/organizations/ORG_ID/members"

  	payload := strings.NewReader("{ \"members\": [ \"USER_ID\", \"USER_ID\", \"USER_ID\" ] }")

  	req, _ := http.NewRequest("POST", 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))

  }
  ```

  ```java Java lines theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/organizations/ORG_ID/members")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ \"members\": [ \"USER_ID\", \"USER_ID\", \"USER_ID\" ] }")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/organizations/ORG_ID/members',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: {members: ['USER_ID', 'USER_ID', 'USER_ID']}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C lines expandable theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"members": @[ @"USER_ID", @"USER_ID", @"USER_ID" ] };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/organizations/ORG_ID/members"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP lines expandable theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/organizations/ORG_ID/members",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ \"members\": [ \"USER_ID\", \"USER_ID\", \"USER_ID\" ] }",
    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;
  }
  ```

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("{yourDomain}")

  payload = "{ \"members\": [ \"USER_ID\", \"USER_ID\", \"USER_ID\" ] }"

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
      'cache-control': "no-cache"
      }

  conn.request("POST", "/api/v2/organizations/ORG_ID/members", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/organizations/ORG_ID/members")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request["cache-control"] = 'no-cache'
  request.body = "{ \"members\": [ \"USER_ID\", \"USER_ID\", \"USER_ID\" ] }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift lines expandable theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = ["members": ["USER_ID", "USER_ID", "USER_ID"]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/organizations/ORG_ID/members")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

<Callout icon="file-lines">
  **Find Your Auth0 Domain**

  If your Auth0 domain is your tenant name, your regional subdomain (unless your tenant is in the US region and was created before June 2020), plus `.auth0.com`. For example, if your tenant name were `travel0`, your Auth0 domain name would be `travel0.us.auth0.com`. (If your tenant were in the US and created before June 2020, then your domain name would be `https://travel0.auth0.com`.)

  If you are using custom domains, this should be your custom domain name.
</Callout>

| Value                   | Description                                                                                                                                         |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ORG_ID`                | ID of the organization for which you want to assign membership.                                                                                     |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the scope `create:organization_members`. |
| `USER_ID`               | ID of the user(s) you want to assign to the specified organization. You can send a maximum of 10 members per organization per request.              |

### Response status codes

Possible response status codes are as follows:

| Status code | Error code             | Message                                                                                              | Cause                                                                              |
| ----------- | ---------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `204`       |                        | Members successfully added to organization.                                                          |                                                                                    |
| `400`       | `invalid_body`         | Invalid request body. The message will vary depending on the cause.                                  | The request payload is not valid.                                                  |
| `400`       | `invalid_query_string` | Invalid request query string. The message will vary depending on the cause.                          | The query string is not valid.                                                     |
| `401`       |                        | Invalid token.                                                                                       |                                                                                    |
| `401`       |                        | Invalid signature received for JSON Web Token validation.                                            |                                                                                    |
| `401`       |                        | Client is not global.                                                                                |                                                                                    |
| `403`       | `insufficient_scope`   | Insufficient scope; expected any of: `create:organization_members`.                                  | Tried to read/write a field that is not allowed with provided bearer token scopes. |
| `429`       |                        | Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. |                                                                                    |


# Create Organization Domains
Source: https://auth0.com/docs/manage-users/organizations/configure-organizations/create-org-domains

Learn how to create or delete Organization Discovery Domains using the Auth0 Dashboard and Management API.

<Warning>
  Organization Discovery Domain is currently available in [Early Access](/docs/troubleshoot/product-lifecycle/product-release-stages). By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/).
</Warning>

Use Organization domains during the login flows to include a prompt for users to choose the correct Organization. When configured, verified domains help Auth0 detect a user’s organization automatically or narrow organization options when users enter their email address.

To learn more, read [Login Flows for Organizations](/docs/manage-users/organizations/login-flows-for-organizations).

## Create an Organization domain

Create Organization domains in the Auth0 Dashboard or with the Auth0 Management API.

<Tabs>
  <Tab title="Auth0 Dashboard">
    To create an Organization domain in the Auth0 Dashboard:

    1. Navigate to [Auth0 Dashboard > Organizations](https://manage.auth0.com/#/organizations).
    2. Select the **Domains** tab.
    3. Choose **Add Domain**.
    4. Enter the domain information and status.
    5. Select **Add Domain**.

    | Field  | Description                                                                                                                                                          |
    | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | Domain | Domain Email to associate for organization discovery  (for example, `Travel0.com`). Must be a valid domain format. Defaults to pending until ownership is confirmed. |
  </Tab>

  <Tab title="Management API">
    <Callout icon="file-lines">
      <b>Find your Auth0 domain</b>

      Your Auth0 domain is your tenant name, your regional subdomain, and `auth0.com`, unless your tenant was created before June 2020 in the US region.

      Example: If your tenant name is Travel0 and your region US, then your Auth0 domain is `travel0.us.auth0.com.` If your tenant was created before June 2020 in the US region, then your domain name would be `https://travel0.auth0.com`.

      If you have a custom domains configured and verified in Auth0 Dashboard, your domain is your custom domain name. To learn more, read [Custom Domains](/docs/customize/custom-domains).
    </Callout>

    Call the Management API `Create Organization Discovery Domain` endpoint. Ensure you replace the placeholder values with the appropriate values from your tenant.

    ```bash theme={null}
    curl --request POST \
      --url 'https://{yourDomain}/api/v2/organizations/{ORGANIZATION_ID}/discovery-domains' \
      --header 'authorization: Bearer {MGMT_API_ACCESS_TOKEN}' \
      --header 'cache-control: no-cache' \
      --header 'content-type: application/json' \
      --data '{
        "domain": "{DOMAIN}",
        "status": "{STATUS}"
      }'
    ```

    | Placeholder             | Description                                                                                                                          |
    | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
    | `MGMT_API_ACCESS_TOKEN` | [Access Token for Management API](/docs/tokens/management-api-access-tokens) with the scope `create:organization_discovery_domains`. |
    | `ORGANIZATION_ID`       | ID of the organization to which you want to add the discovery domain (e.g., `org_abc123`).                                           |
    | `DOMAIN`                | Required. Email domain you want to associate for Organization Discovery  (for example, example.com).                                 |
    | `STATUS`                | Optional. Initial status for the domain. Common values: `pending`, `verified`.                                                       |

    | Status code | Error description      | Message                                                                                                     | Cause                                                                         |
    | ----------- | ---------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
    | `201`       |                        | Discovery domain successfully created. The domain record was added to the organization.                     |                                                                               |
    | `400`       | `invalid_body`         | Invalid request body. The message will vary depending on the cause.                                         | The request payload is not valid.                                             |
    | `400`       | `invalid_query_string` | Invalid query string. The message will vary depending on the cause.                                         | The query string is not valid.                                                |
    | `401`       |                        | Invalid token.                                                                                              |                                                                               |
    | `403`       | `insufficient_scope`   | Insufficient scope; expected any of: `create:organization_discovery_domains`.                               | Tried to write a field that is not allowed with provided bearer token scopes. |
    | `409`       | `conflict`             | An organization domain with the same name already exists.                                                   | An organization domain  with the same name already exists.                    |
    | `429`       |                        | Too many requests. Check the `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. |                                                                               |
  </Tab>
</Tabs>


# Create Organizations
Source: https://auth0.com/docs/manage-users/organizations/configure-organizations/create-organizations

Learn how to create Organizations using the Auth0 Dashboard and Management API.

You can create [organizations](/docs/manage-users/organizations/organizations-overview) using either the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

<Card title="Availability varies by Auth0 plan">
  Your Auth0 plan or custom agreement affects whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

## Auth0 Dashboard

To create an organization via the Auth0 Dashboard:

1. Navigate to [Auth0 Dashboard > Organizations](https://manage.auth0.com/#/organizations).
2. Select **Create Organization**.
3. Enter basic information for your organization, and select **Add Organization**:

   | **Field**        | **Description**                                                                                                                                                                                                                                                                                                                                                             |
   | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | **Name**         | Name of the organization you would like to create. This is the name that an end-user would type in the pre-login prompt to identify which organization they wanted to log in through. Unique logical identifier. May contain lowercase alphabetical characters, numbers, underscores (`_`), and dashes (`-`). Can start with a number. Must be between 1 and 50 characters. |
   | **Display Name** | User-friendly name to display.                                                                                                                                                                                                                                                                                                                                              |
4. Locate the **Branding** section and customize your organization, then select **Save changes**:

   | **Field**                 | **Description**                                                                               |
   | ------------------------- | --------------------------------------------------------------------------------------------- |
   | **Organization Logo**     | Logo to display. Minimum recommended resolution is 200 pixels (width) by 200 pixels (height). |
   | **Primary Color**         | Color for primary elements.                                                                   |
   | **Page Background Color** | Color for background.                                                                         |
5. Locate the **Metadata** section and add any necessary metadata key/value pairs to the organization, then select **Add**.

## Management API

To create an organization via the Management API:

Make a `POST` call to the `Create Organizations` endpoint. Ensure you replace the placeholder values with the appropriate values from your tenant. For more details, review the parameter chart below.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/organizations' \
    --header 'authorization: Bearer {MGMT_API_ACCESS_TOKEN}' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "name": "ORG_NAME", "display_name": "ORG_DISPLAY_NAME", "branding": [ { "logo_url": "{orgLogo}", "colors": [ { "primary": "{orgPrimaryColor}", "page_background": "{orgPageBackground}" } ] } ], "metadata": [ { "{key}": "{value}", "{key}": "{value}", "{key}": "{value}" } ] }, "enabled_connections": [ { "connection_id": "{connectionId}", "assign_membership_on_login": "{assignMembershipOption}" }, { "connection_id": "{connectionId}", "assign_membership_on_login": "{assignMembershipOption}" } ] }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/organizations");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer {MGMT_API_ACCESS_TOKEN}");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("application/json", "{ "name": "ORG_NAME", "display_name": "ORG_DISPLAY_NAME", "branding": [ { "logo_url": "{orgLogo}", "colors": [ { "primary": "{orgPrimaryColor}", "page_background": "{orgPageBackground}" } ] } ], "metadata": [ { "{key}": "{value}", "{key}": "{value}", "{key}": "{value}" } ] }, "enabled_connections": [ { "connection_id": "{connectionId}", "assign_membership_on_login": "{assignMembershipOption}" }, { "connection_id": "{connectionId}", "assign_membership_on_login": "{assignMembershipOption}" } ] }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/organizations"

  	payload := strings.NewReader("{ "name": "ORG_NAME", "display_name": "ORG_DISPLAY_NAME", "branding": [ { "logo_url": "{orgLogo}", "colors": [ { "primary": "{orgPrimaryColor}", "page_background": "{orgPageBackground}" } ] } ], "metadata": [ { "{key}": "{value}", "{key}": "{value}", "{key}": "{value}" } ] }, "enabled_connections": [ { "connection_id": "{connectionId}", "assign_membership_on_login": "{assignMembershipOption}" }, { "connection_id": "{connectionId}", "assign_membership_on_login": "{assignMembershipOption}" } ] }")

  	req, _ := http.NewRequest("POST", 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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/organizations")
    .header("content-type", "application/json")
    .header("authorization", "Bearer {MGMT_API_ACCESS_TOKEN}")
    .header("cache-control", "no-cache")
    .body("{ "name": "ORG_NAME", "display_name": "ORG_DISPLAY_NAME", "branding": [ { "logo_url": "{orgLogo}", "colors": [ { "primary": "{orgPrimaryColor}", "page_background": "{orgPageBackground}" } ] } ], "metadata": [ { "{key}": "{value}", "{key}": "{value}", "{key}": "{value}" } ] }, "enabled_connections": [ { "connection_id": "{connectionId}", "assign_membership_on_login": "{assignMembershipOption}" }, { "connection_id": "{connectionId}", "assign_membership_on_login": "{assignMembershipOption}" } ] }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/organizations',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer {MGMT_API_ACCESS_TOKEN}',
      'cache-control': 'no-cache'
    },
    data: '{ "name": "ORG_NAME", "display_name": "ORG_DISPLAY_NAME", "branding": [ { "logo_url": "{orgLogo}", "colors": [ { "primary": "{orgPrimaryColor}", "page_background": "{orgPageBackground}" } ] } ], "metadata": [ { "{key}": "{value}", "{key}": "{value}", "{key}": "{value}" } ] }, "enabled_connections": [ { "connection_id": "{connectionId}", "assign_membership_on_login": "{assignMembershipOption}" }, { "connection_id": "{connectionId}", "assign_membership_on_login": "{assignMembershipOption}" } ] }'
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer {MGMT_API_ACCESS_TOKEN}",
                             @"cache-control": @"no-cache" };

  NSData *postData = [[NSData alloc] initWithData:[@"{ "name": "ORG_NAME", "display_name": "ORG_DISPLAY_NAME", "branding": [ { "logo_url": "{orgLogo}", "colors": [ { "primary": "{orgPrimaryColor}", "page_background": "{orgPageBackground}" } ] } ], "metadata": [ { "{key}": "{value}", "{key}": "{value}", "{key}": "{value}" } ] }, "enabled_connections": [ { "connection_id": "{connectionId}", "assign_membership_on_login": "{assignMembershipOption}" }, { "connection_id": "{connectionId}", "assign_membership_on_login": "{assignMembershipOption}" } ] }" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/organizations"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/organizations",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "name": "ORG_NAME", "display_name": "ORG_DISPLAY_NAME", "branding": [ { "logo_url": "{orgLogo}", "colors": [ { "primary": "{orgPrimaryColor}", "page_background": "{orgPageBackground}" } ] } ], "metadata": [ { "{key}": "{value}", "{key}": "{value}", "{key}": "{value}" } ] }, "enabled_connections": [ { "connection_id": "{connectionId}", "assign_membership_on_login": "{assignMembershipOption}" }, { "connection_id": "{connectionId}", "assign_membership_on_login": "{assignMembershipOption}" } ] }",
    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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "name": "ORG_NAME", "display_name": "ORG_DISPLAY_NAME", "branding": [ { "logo_url": "{orgLogo}", "colors": [ { "primary": "{orgPrimaryColor}", "page_background": "{orgPageBackground}" } ] } ], "metadata": [ { "{key}": "{value}", "{key}": "{value}", "{key}": "{value}" } ] }, "enabled_connections": [ { "connection_id": "{connectionId}", "assign_membership_on_login": "{assignMembershipOption}" }, { "connection_id": "{connectionId}", "assign_membership_on_login": "{assignMembershipOption}" } ] }"

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer {MGMT_API_ACCESS_TOKEN}",
      'cache-control': "no-cache"
      }

  conn.request("POST", "/{yourDomain}/api/v2/organizations", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/organizations")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer {MGMT_API_ACCESS_TOKEN}'
  request["cache-control"] = 'no-cache'
  request.body = "{ "name": "ORG_NAME", "display_name": "ORG_DISPLAY_NAME", "branding": [ { "logo_url": "{orgLogo}", "colors": [ { "primary": "{orgPrimaryColor}", "page_background": "{orgPageBackground}" } ] } ], "metadata": [ { "{key}": "{value}", "{key}": "{value}", "{key}": "{value}" } ] }, "enabled_connections": [ { "connection_id": "{connectionId}", "assign_membership_on_login": "{assignMembershipOption}" }, { "connection_id": "{connectionId}", "assign_membership_on_login": "{assignMembershipOption}" } ] }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer {MGMT_API_ACCESS_TOKEN}",
    "cache-control": "no-cache"
  ]

  let postData = NSData(data: "{ "name": "ORG_NAME", "display_name": "ORG_DISPLAY_NAME", "branding": [ { "logo_url": "{orgLogo}", "colors": [ { "primary": "{orgPrimaryColor}", "page_background": "{orgPageBackground}" } ] } ], "metadata": [ { "{key}": "{value}", "{key}": "{value}", "{key}": "{value}" } ] }, "enabled_connections": [ { "connection_id": "{connectionId}", "assign_membership_on_login": "{assignMembershipOption}" }, { "connection_id": "{connectionId}", "assign_membership_on_login": "{assignMembershipOption}" } ] }".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/organizations")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

<Callout icon="file-lines">
  **Find Your Auth0 Domain**

  If your Auth0 domain is your tenant name, your regional subdomain (unless your tenant is in the US region and was created before June 2020), plus `.auth0.com`. For example, if your tenant name were `travel0`, your Auth0 domain name would be `travel0.us.auth0.com`. (If your tenant were in the US and created before June 2020, then your domain name would be `https://travel0.auth0.com`.)

  If you are using custom domains, this should be your custom domain name.
</Callout>

| **Value**                  | **Description**                                                                                                                                                                                                                                                                                                                                                             |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MGMT_API_ACCESS_TOKEN`    | [Access Token for the Management API](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the scope `create:organizations`.                                                                                                                                                                                                                                |
| `ORG_NAME`                 | Name of the organization you would like to create. This is the name that an end-user would type in the pre-login prompt to identify which organization they wanted to log in through. Unique logical identifier. May contain lowercase alphabetical characters, numbers, underscores (`_`), and dashes (`-`). Can start with a number. Must be between 1 and 50 characters. |
| `ORG_DISPLAY_NAME`         | Optional. User-friendly name of the organizations that can be displayed in the login flow and email templates.                                                                                                                                                                                                                                                              |
| `ORG_LOGO`                 | Optional. URL of the organization’s logo.                                                                                                                                                                                                                                                                                                                                   |
| `ORG_PRIMARY_COLOR`        | Optional. HEX color code for primary elements.                                                                                                                                                                                                                                                                                                                              |
| `ORG_BACKGROUND_COLOR`     | Optional. HEX color code for background.                                                                                                                                                                                                                                                                                                                                    |
| `KEY`/`VALUE`              | Optional. String key/value pairs that represent metadata for the organization. Maximum of 255 characters each. Maximum of 25 metadata pairs.                                                                                                                                                                                                                                |
| `CONNECTION_ID`            | Optional. ID of the connection you want to enable for the specified organization. Enabled connections are displayed on the organization's login prompt, so users can access your application(s) through them.                                                                                                                                                               |
| `ASSIGN_MEMBERSHIP_OPTION` | Optional. Indicates whether you want users that log in with the enabled connection to automatically be granted membership in the specified organization. When set to `true`, users will automatically be granted membership. When set to `false`, they will not automatically be granted membership.                                                                        |

### Response status codes

Possible response status codes are as follows:

| **Status code** | **Error code**          | **Message**                                                                                          | **Cause**                                                                          |
| --------------- | ----------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `201`           |                         | Organization successfully created.                                                                   |                                                                                    |
| `400`           | `invalid_body`          | Invalid request body. The message will vary depending on the cause.                                  | The request payload is not valid.                                                  |
| `400`           | `invalid_query_string`  | Invalid request query string. The message will vary depending on the cause.                          | The query string is not valid.                                                     |
| `401`           |                         | Invalid token.                                                                                       |                                                                                    |
| `401`           |                         | Invalid signature received for JSON Web Token validation.                                            |                                                                                    |
| `401`           |                         | Client is not global.                                                                                |                                                                                    |
| `403`           | `insufficient_scope`    | Insufficient scope; expected any of: `create:organizations`.                                         | Tried to read/write a field that is not allowed with provided bearer token scopes. |
| `409`           | `organization_conflict` | An organization with the same name already exists.                                                   | An organization with the same name already exists.                                 |
| `429`           |                         | Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. |                                                                                    |


# Define Organization Behavior
Source: https://auth0.com/docs/manage-users/organizations/configure-organizations/define-organization-behavior

Learn to define organization behavior within applications for Auth0's Organizations feature.

When representing your application in Auth0, you can specify what types of users the application should support. Some applications support individuals logging in with personal accounts, while others are intended for use by members of [organizations](/docs/manage-users/organizations/organizations-overview). Some should support both. This is known as organization behavior and can be set for each application that you connect to Auth0.

For example, your application could have:

* A generic marketing landing page that has a **Log in** button that takes your users to the Auth0 login flow without an Organization.
* A separate URL for each of your B2B customers (e.g., Acme users go to `acme.yourcompany.com`) that redirects users to Auth0 with an Organization, so that your users see Acme’s <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> Login button.

You can define Organization behavior to allow either of these scenarios. Additionally, you can configure Organization behavior such that if your application requires that an Organization be provided but your user accidentally is sent to Auth0 without an organization, they would see a prompt that would allow them to enter the name of their organization.

You can define organization behavior using either the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## Auth0 Dashboard

To define organization behavior via the Auth0 Dashboard:

1. Navigate to [Auth0 Dashboard > Applications](https://manage.auth0.com/#/applications), and select the application for which you want to configure organizations.
2. Switch to the Login Experience view and configure the appropriate settings:

<table>
  <thead>
    <tr>
      <th><strong>Field</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>API Mapping</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Type of Users</strong></td>

      <td>
        Determines which category of users can log in to your application.<br /><br />
        Options include:

        <ul>
          <li>
            <strong>Individuals</strong>: Users can sign up with a personal account and log directly in to your application. Individual users cannot log in using an Organization.
          </li>

          <li>
            <strong>Business Users</strong>: Users must be a member of an Organization in order to log in. When selected, you must either provide an Organization when you redirect users to the <code>/authorize</code> endpoint or set your Login Flow to Prompt for Organization.
          </li>

          <li>
            <strong>Both</strong>: Users can log in as an Organization member or sign up with a personal account.
          </li>
        </ul>
      </td>

      <td>
        <strong>Type of Users</strong> maps to <code>organization\_usage</code><br /><br />
        Options:

        <ul>
          <li><strong>Individuals</strong> maps to <code>deny</code></li>
          <li><strong>Business Users</strong> maps to <code>require</code></li>
          <li><strong>Both</strong> maps to <code>allow</code></li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><strong>Login Flow</strong></td>

      <td>
        Determines the initial login prompt presented to users when they access your application. You can only configure this field if Type of Users is set to Businsess Users or Both.<br /><br />
        Options include:

        <ul>
          <li>
            <strong>Prompt for Credentials</strong>: Users are first asked to provide their login credentials. After logging in, users can select their Organization.
          </li>

          <li>
            <strong>Prompt for Organization</strong>: Users are first asked to select their Organization. Then, they can provide their credentials to log in.
          </li>

          <li>
            <strong>No Prompt</strong>: Auth0 does not dictate which login prompt is given to users. Instead, your application is responsible for sending the required parameters to Auth0 to display the appropriate prompt.
          </li>
        </ul>
      </td>

      <td>
        <strong>Login Flow</strong> maps to <code>organization\_require\_behavior</code><br /><br />
        Options:

        <ul>
          <li><strong>Prompt for Credentials</strong> maps to <code>post\_login\_prompt</code></li>
          <li><strong>Prompt for Organization</strong> maps to <code>pre\_login\_prompt</code></li>
          <li><strong>No Prompt</strong> maps to <code>no\_prompt</code></li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><strong>Organization Discovery</strong></td>

      <td>
        Defines the method used to identify the user’s organization before authentication. Only available with Prompt for Organization Login Flow. <br /><br /> Options include:

        <ul>
          <li>
            <strong>Prompt for Organization Email</strong>: Users are first asked to provide their email address associated with their Organization.
          </li>

          <li>
            <strong>Prompt for Organization Name</strong>: Users are first asked to provide the name of their Organization.
          </li>

          <li>
            <strong>Prompt for Organization Email and Name</strong>: Users are first asked to provide the name of their Organization or email associated with their Organization.
          </li>
        </ul>
      </td>

      <td>
        <ul>
          <li>
            <strong>Prompt for Emails</strong>: maps to `email`.
          </li>

          <li>
            <strong>Prompt for Organization</strong>: maps to `organization_name`.
          </li>

          <li>
            <strong>Prompt for Organization Email and Name</strong>: maps to `email` and `organization_name`.
          </li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

3. Select **Save changes**.

## Management API

Make a `PATCH` call to the [Update a Client endpoint](https://auth0.com/docs/api/management/v2#!/Clients/patch_clients_by_id). Be sure to replace `client_id`, `mgmt_api_access_token`, `organization_usage`, and `organization_require_behavior` placeholder values with your <Tooltip href="/docs/glossary?term=client+ID">client ID</Tooltip>, Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, organization use option, and organization behavior option, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/clients/CLIENT_ID' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "organization_usage": "ORG_USAGE", "organization_require_behavior": "ORG_REQUIRE_BEHAVIOR" }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/clients/CLIENT_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", "{ "organization_usage": "ORG_USAGE", "organization_require_behavior": "ORG_REQUIRE_BEHAVIOR" }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/clients/CLIENT_ID"

  	payload := strings.NewReader("{ "organization_usage": "ORG_USAGE", "organization_require_behavior": "ORG_REQUIRE_BEHAVIOR" }")

  	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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/clients/CLIENT_ID")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "organization_usage": "ORG_USAGE", "organization_require_behavior": "ORG_REQUIRE_BEHAVIOR" }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/clients/CLIENT_ID',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: {
      organization_usage: 'ORG_USAGE',
      organization_require_behavior: 'ORG_REQUIRE_BEHAVIOR'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"organization_usage": @"ORG_USAGE",
                                @"organization_require_behavior": @"ORG_REQUIRE_BEHAVIOR" };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/clients/CLIENT_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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/clients/CLIENT_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 => "{ "organization_usage": "ORG_USAGE", "organization_require_behavior": "ORG_REQUIRE_BEHAVIOR" }",
    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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "organization_usage": "ORG_USAGE", "organization_require_behavior": "ORG_REQUIRE_BEHAVIOR" }"

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
      'cache-control': "no-cache"
      }

  conn.request("PATCH", "/{yourDomain}/api/v2/clients/CLIENT_ID", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/clients/CLIENT_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 = "{ "organization_usage": "ORG_USAGE", "organization_require_behavior": "ORG_REQUIRE_BEHAVIOR" }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = [
    "organization_usage": "ORG_USAGE",
    "organization_require_behavior": "ORG_REQUIRE_BEHAVIOR"
  ] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/clients/CLIENT_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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>CLIENT\_ID</code></td>
      <td>ID of the application for which you want to add organization behavior.</td>
    </tr>

    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>

      <td>
        <a href="/docs/secure/tokens/access-tokens/management-api-access-tokens">Access Tokens for the Management API</a> with the scope <code>update:clients</code>.
      </td>
    </tr>

    <tr>
      <td><code>ORGANIZATION\_USAGE</code></td>

      <td>
        Dictates whether your application can support users logging into an organization. Options include:

        <ul>
          <li><code>deny</code>: (Default) Users cannot log in using an organization.</li>
          <li><code>allow</code>: Users can log in with or without an Organization. When selected, you must provide an organization when you redirect users to the <code>/authorize</code> endpoint.</li>
          <li><code>require</code>: Users must log in using an organization. When selected, you must either provide an organization when you redirect users to the <code>/authorize</code> endpoint or set <code>organization\_require\_behavior</code> to <code>pre\_login\_prompt</code> to allow users to choose an organization before they log in.</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><code>ORGANIZATION\_REQUIRE\_BEHAVIOR</code></td>

      <td>
        Determines the Login Flow presented to users accessing your application. Only applicable when <code>organization\_usage</code> is set to <code>require</code> or <code>allow</code>.<br /><br />Options include:

        <ul>
          <li><code>no\_prompt</code>: (Default) Display no prompt. Requests without a valid organization parameter are rejected.</li>
          <li><code>pre\_login\_prompt</code>: Prompt users to select an Organization before they can log in. You can only use this option if <code>organization\_usage</code> is set to <code>require</code>.</li>
          <li><code>post\_login\_prompt</code>: Prompt users to log in with their credentials. After they log in, prompt users to select their Organization.</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><code>ORGANIZATION\_DISCOVERY\_METHODS</code></td>

      <td>
        Determines the method to identify a user’s organization before authentication. Only applicable when <code>organization\_require\_behavior</code> is <code>pre\_login\_prompt</code> and <code>organization\_usage</code> is set to require or allow.

        <ul>
          <li>
            <code>email</code>: (Default) Users are prompted to enter their email address associated with their Organization.
          </li>

          <li>
            <code>organization\_name</code>: Users are prompted to enter the name associated with their Organization.
          </li>

          <li>
            <code>Organization name</code> and <code>email</code>: Users are prompted for the email address or name associated with their Organization.
          </li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

### Response status codes

Possible response status codes are as follows:

| Status code | Error code                | Message                                                                                                                                              | Cause                                                                              |
| ----------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `200`       |                           | Client successfully updated.                                                                                                                         |                                                                                    |
| `400`       | `invalid_uri`             | Invalid request URI. The message will vary depending on the cause.                                                                                   | The path is not valid.                                                             |
| `400`       | `invalid_body`            | Invalid request body. The message will vary depending on the cause.                                                                                  | The request payload is not valid.                                                  |
| `401`       |                           | Invalid token.                                                                                                                                       |                                                                                    |
| `401`       |                           | Client is not global.                                                                                                                                |                                                                                    |
| `401`       |                           | Invalid signature received for JSON Web Token validation.                                                                                            |                                                                                    |
| `403`       | `insufficient_scope`      | Insufficient scope; expected any of: `update:clients`.                                                                                               | Tried to read/write a field that is not allowed with provided bearer token scopes. |
| `403`       | `insufficient_scope`      | Some fields cannot be updated with the permissions granted by the bearer token scopes. The message will vary depending on the fields and the scopes. | Tried to read/write a field that is not allowed with provided bearer token scopes. |
| `403`       | `operation_not_supported` | The account is not allowed to perform this operation.                                                                                                | The account is not allowed to perform this operation.                              |
| `404`       | `inexistent_client`       | Client not found.                                                                                                                                    | Inexistent resource. Specified application does not exist.                         |
| `429`       |                           | Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.                                                 |                                                                                    |


# Delete Organization Domains
Source: https://auth0.com/docs/manage-users/organizations/configure-organizations/delete-org-domains

Learn how to create or delete Organization Discovery Domains using the Auth0 Dashboard and Management API.

<Warning>
  Organizations Discovery Domain is currently available in [Early Access](/docs/troubleshoot/product-lifecycle/product-release-stages). By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/).
</Warning>

When deleting an Organization discovery domain, the association between the domain and the organization will be permanently removed.

<Warning>
  Once you confirm a Discovery Domain for deletion, this operation cannot be undone.
</Warning>

Delete an Organization domains in the Auth0 Dashboard or with the Management API.

<Tabs>
  <Tab title="Auth0 Dashboard">
    To delete an organization domain in the Auth0 Dashboard:

    1. Navigate to Navigate to [Auth0 Dashboard > Organizations](https://manage.auth0.com/#/organizations).
    2. Select the **Domains** tab.
    3. Choose **Add Domain**.
    4. Locate the domain you want to remove.
    5. Open the actions menu (⋮) next to the domain and select **Delete**.
    6. Confirm the deletion.
  </Tab>

  <Tab title="Management API">
    <Callout icon="file-lines">
      <b>Find your Auth0 domain</b>

      Your Auth0 domain is your tenant name, your regional subdomain, and `auth0.com`, unless your tenant was created before June 2020 in the US region.

      Example: If your tenant name is Travel0 and your region US, then your Auth0 domain is `travel0.us.auth0.com.` If your tenant was created before June 2020 in the US region, then your domain name would be `https://travel0.auth0.com`.

      If you have a custom domains configured and verified in Auth0 Dashboard, your domain is your custom domain name. To learn more, read [Custom Domains](/docs/customize/custom-domains).
    </Callout>

    Call the Management API `Delete Organization Discovery Domain` endpoint. Ensure you replace the placeholder values with the appropriate values from your tenant.

    ```bash theme={null}
    curl --request DELETE \
      --url 'https://{yourDomain}/api/v2/organizations/{ORGANIZATION_ID}/discovery-domains/{ORGANIZATION_DOMAIN_ID}' \
      --header 'authorization: Bearer {MGMT_API_ACCESS_TOKEN}'
    ```

    | <b>Value</b>             | <b>Description</b>                                                                                                 |
    | ------------------------ | ------------------------------------------------------------------------------------------------------------------ |
    | `MGMT_API_ACCESS_TOKEN`  | [Access Token for Management API](/docs/tokens/management-api-access-tokens) with the scope `delete:organization`. |
    | `ORGANIZATION_ID`        | ID of the organization to which you want to add the discovery domain (for example, `org_abc123`).                  |
    | `ORGANIZATION_DOMAIN_ID` | Required. Email domain you want to associate for Organization Discovery  (for example, `example.com`).             |

    | <b> Status code </b> | <b> Error description </b> | <b>Message</b>                                                                                              | <b>Cause</b>                                                                       |
    | -------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
    | `204`                |                            | Discovery domain was deleted.                                                                               |                                                                                    |
    | `400`                | `invalid_uri`              | Invalid request URI. The message will vary depending on the cause.                                          | The path is not valid.                                                             |
    | `401`                |                            | Invalid token.                                                                                              |                                                                                    |
    | `401`                |                            | Invalid signature received for JSON Web Token (JWT) validation.                                             |                                                                                    |
    | `403`                | `insufficient_scope`       | Insufficient scope; expected any of: `delete:organization_discovery_domains`.                               | Tried to read/write a field that is not allowed with provided bearer token scopes. |
    | `404`                |                            | The Organization domain does not exist.                                                                     |                                                                                    |
    | `429`                |                            | Too many requests. Check the `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. |                                                                                    |
  </Tab>
</Tabs>


# Delete Organizations
Source: https://auth0.com/docs/manage-users/organizations/configure-organizations/delete-organizations

Learn how to delete Organizations using the Auth0 Dashboard or Management API.

When deleting an [organization](/docs/manage-users/organizations/organizations-overview), the association between all users’ membership and the deleted organization will be removed, though the users themselves will not be deleted from your tenant.

<Warning>
  Once confirmed, this operation cannot be undone.
</Warning>

You can delete organizations using either the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## Auth0 Dashboard

To delete an organization via the Auth0 Dashboard:

1. Navigate to [Auth0 Dashboard > Organizations](https://manage.auth0.com/#/organizations), and select the organization you want to delete.
2. Scroll to locate the **Danger Zone** section, select **Delete**, and confirm.

## Management API

Make a `DELETE` call to the `Delete Organization` endpoint. Be sure to replace the `ORG_ID` and `MGMT_API_ACCESS_TOKEN` placeholder values with your organization ID and Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url 'https://{yourDomain}/api/v2/organizations/ORG_ID' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/organizations/ORG_ID");
  var request = new RestRequest(Method.DELETE);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/organizations/ORG_ID"

  	req, _ := http.NewRequest("DELETE", url, nil)

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.delete("https://{yourDomain}/api/v2/organizations/ORG_ID")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'DELETE',
    url: 'https://{yourDomain}/api/v2/organizations/ORG_ID',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/organizations/ORG_ID"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"DELETE"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/organizations/ORG_ID",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer MGMT_API_ACCESS_TOKEN" }

  conn.request("DELETE", "/{yourDomain}/api/v2/organizations/ORG_ID", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/organizations/ORG_ID")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Delete.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer MGMT_API_ACCESS_TOKEN"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/organizations/ORG_ID")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "DELETE"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

<Callout icon="file-lines">
  **Find Your Auth0 Domain**

  If your Auth0 domain is your tenant name, your regional subdomain (unless your tenant is in the US region and was created before June 2020), plus `.auth0.com`. For example, if your tenant name were `travel0`, your Auth0 domain name would be `travel0.us.auth0.com`. (If your tenant were in the US and created before June 2020, then your domain name would be `https://travel0.auth0.com`.)

  If you are using custom domains, this should be your custom domain name.
</Callout>

| Value                   | Description                                                                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `ORG_ID`                | ID of the organization you want to delete.                                                                                                   |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the scope `delete:organizations`. |

#### Response status codes

Possible response status codes are as follows:

| Status code | Error code           | Message                                                                                              | Cause                                                                              |
| ----------- | -------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `204`       |                      | The organization was deleted.                                                                        |                                                                                    |
| `400`       | `invalid_uri`        | Invalid request URI. The message will vary depending on the cause.                                   | The path is not valid.                                                             |
| `401`       |                      | Invalid token.                                                                                       |                                                                                    |
| `401`       |                      | Invalid signature received for JSON Web Token validation.                                            |                                                                                    |
| `403`       | `insufficient_scope` | Insufficient scope; expected any of: `delete:organizations`.                                         | Tried to read/write a field that is not allowed with provided bearer token scopes. |
| `404`       |                      | The organization does not exist.                                                                     |                                                                                    |
| `429`       |                      | Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. |                                                                                    |


# Disable Organization Connections
Source: https://auth0.com/docs/manage-users/organizations/configure-organizations/disable-connections

Learn how to disable organization connections using the Auth0 Dashboard or Management API.

You can disable connections for [organizations](/docs/manage-users/organizations/organizations-overview) using either the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## Auth0 Dashboard

To disable a connection via the Auth0 Dashboard:

1. Navigate to [Auth0 Dashboard > Organizations](https://manage.auth0.com/#/organizations), and select the organization for which you want to configure connections.
2. Select the **Connections** view, locate the connection you want to remove, and expand its **More Options** (**...**) menu.
3. Select **Remove Connection**, and confirm.

## Management API

Make a `DELETE` call to the `Delete Organization Connections` endpoint. Be sure to replace the `ORG_ID`, `MGMT_API_ACCESS_TOKEN`, and `CONNECTION_ID` placeholder values with your organization ID, Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, and connection ID, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url 'https://{yourDomain}/api/v2/organizations/ORG_ID/enabled_connections/CONNECTION_ID' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/organizations/ORG_ID/enabled_connections/CONNECTION_ID");
  var request = new RestRequest(Method.DELETE);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/organizations/ORG_ID/enabled_connections/CONNECTION_ID"

  	req, _ := http.NewRequest("DELETE", url, nil)

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.delete("https://{yourDomain}/api/v2/organizations/ORG_ID/enabled_connections/CONNECTION_ID")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'DELETE',
    url: 'https://{yourDomain}/api/v2/organizations/ORG_ID/enabled_connections/CONNECTION_ID',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/organizations/ORG_ID/enabled_connections/CONNECTION_ID"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"DELETE"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/organizations/ORG_ID/enabled_connections/CONNECTION_ID",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer MGMT_API_ACCESS_TOKEN" }

  conn.request("DELETE", "/{yourDomain}/api/v2/organizations/ORG_ID/enabled_connections/CONNECTION_ID", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/organizations/ORG_ID/enabled_connections/CONNECTION_ID")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Delete.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer MGMT_API_ACCESS_TOKEN"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/organizations/ORG_ID/enabled_connections/CONNECTION_ID")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "DELETE"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

<Callout icon="file-lines">
  **Find Your Auth0 Domain**

  If your Auth0 domain is your tenant name, your regional subdomain (unless your tenant is in the US region and was created before June 2020), plus `.auth0.com`. For example, if your tenant name were `travel0`, your Auth0 domain name would be `travel0.us.auth0.com`. (If your tenant were in the US and created before June 2020, then your domain name would be `https://travel0.auth0.com`.)

  If you are using custom domains, this should be your custom domain name.
</Callout>

| Value                   | Description                                                                                                                                             |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ORG_ID`                | ID of the organization for which you want to disable a connection.                                                                                      |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the scope `delete:organization_connections`. |
| `CONNECTION_ID`         | ID of the connection you want to disable for the organization.                                                                                          |

### Response status codes

Possible response status codes are as follows:

| Status code | Error code           | Message                                                                                              | Cause                                                                              |
| ----------- | -------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `204`       |                      | Connection successfully removed from organization.                                                   |                                                                                    |
| `401`       |                      | Invalid token.                                                                                       |                                                                                    |
| `401`       |                      | Invalid signature received for JSON Web Token validation.                                            |                                                                                    |
| `401`       |                      | Client is not global.                                                                                |                                                                                    |
| `403`       | `insufficient_scope` | Insufficient scope; expected any of: `delete:organization_connections`.                              | Tried to read/write a field that is not allowed with provided bearer token scopes. |
| `429`       |                      | Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. |                                                                                    |


# Enable Organization Connections
Source: https://auth0.com/docs/manage-users/organizations/configure-organizations/enable-connections

Learn to enable Organization connections using the Auth0 Dashboard and Management API.

You can enable specific connections for each [organization](/docs/manage-users/organizations/organizations-overview) to provide users with different login options. After you enable a connection, it is added to the organization login prompt, and users can authenticate through that connection to access your applications.

To enable a connection for an organization, the connection **must** already exist in your tenant. Supported connections include [database connections](/docs/authenticate/database-connections), [social connections](/docs/authenticate/identity-providers/social-identity-providers), and [enterprise connections](/docs/authenticate/identity-providers/enterprise-identity-providers).

## Organization Properties

When using organizations, some connections have additional properties that you can configure:

<table>
  <thead>
    <tr>
      <th><strong>Property</strong></th>
      <th><strong>Connection Types</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Membership On Authentication</td>
      <td>All connection types</td>

      <td>
        When enabled, this property automatically assigns organization membership to end-users the first time they authenticate with the connection. <br /><br />
        Membership on Authentication is useful in scenarios where all users with the ability to authenticate with a specific connection can be assumed to be members of an organization.
      </td>
    </tr>

    <tr>
      <td>Organization Signup</td>
      <td>Database connections only</td>

      <td>
        This property determines whether or not end-users can access a signup link on the login prompt that allows them to gain membership to an Organization. To use Organization Signup, you must also enable Membership On Authentication.<br /><br />
        Organization Signup is useful is scenarios where users need self-service access to join Organizations, such as:

        <ul>
          <li>When Organizations are used to model open-membership user populations such as workspaces.</li>
          <li>In business-to-business-to-consumer (B2B2C) use cases where users can freely sign up for accounts.</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>Display connection as a button</td>
      <td>Enterprise connections only</td>

      <td>
        This optional property determines whether or not a specific connection displays as an option on the organization login prompt. <br /><br />
        <strong>Note</strong>: If this option is disabled for a connection, end-users can still authenticate via the connection and log in to applications in the context of the organization by sending the connection parameter directly in the authorization request. <br /><br />
        They can also authenticate with this connection if you are using the <a href="/docs/authenticate/login/auth0-universal-login/identifier-first">Identifier First with Home Realm Discovery</a> authentication profile in combination with the <a href="/docs/manage-users/organizations/login-flows-for-organizations#configure-the-login-flow-for-your-application">Prompt for Credentials</a> organization login flow. <br /><br />
        This only works if you do <b>not</b> provide an <code>org\_id</code> with the authorization request.
      </td>
    </tr>
  </tbody>
</table>

<Warning>
  End-users can only log in to applications in the context of a specific organization through connections that have been enabled for that organization.
</Warning>

## Configure Organization Connections

You can configure connections for organizations using either the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

<Tabs>
  <Tab title="Auth0 Dashboard">
    #### Auth0 Dashboard

    To enable a connection via the Auth0 Dashboard:

    1. Navigate to [Auth0 Dashboard > Organizations](https://manage.auth0.com/#/organizations), and select the organization for which you want to configure connections.
    2. Select the **Connections** view, then select **Enable Connections**.
    3. Choose the connection you want to enable, and select **Enable Connection**.
    4. In the Authentication section, locate **Membership On Authentication** and choose whether to enable or disable auto-membership. When enabled, auto-membership automatically adds all users logging in with the connection as members of the organization.
    5. **For Database connections only**: In the Organization Signup section, choose whether to enable or disable self-service signups. When enabled, users can access a signup link on the login prompt to create their account and automatically gain membership to the organization.

       * To enable this property, you must first enable **Membership on Authentication**.
       * **Note**: Organization Signup takes priority over the Database connection’s signup configuration. When Organization Signup is enabled, users can still sign up to an Organization or accept an Organization invite, even if signups are disabled at the Database connection level.
    6. **For Enterprise connections only**: In the Connection button section, optionally enable the **Display connection as a button** property to display the connection as an option on the organization login prompt.

       <Callout icon="file-lines">
         If all enabled connections within the Organization are enterprise connections, and all connections are hidden, Auth0 returns an error that reads `Message: no connections enabled for the organization are visible` when users access the application.
       </Callout>
    7. Select **Save**.
  </Tab>

  <Tab title="Management API">
    #### Management API

    To enable a connection via the Management API:

    Make a `POST` call to the `Create Organization Connections` endpoint. Ensure you update the following placeholder values with the appropriate information:

    * Replace `{orgId}` with your organization ID.
    * Replace `{mgmtApiAccessToken}` with your Management API access token.
    * Replace `{connectionId}` with a specific connection ID.
    * Replace `{assignMembershipOption}` with `true` or `false` with respect to your Membership on Authentication selection.
    * **For Database connections only**: Replace `{isSignupEnabled}` with `true` or `false` with respect to your signup selection.
    * **For Enterprise connections only**: Replace `{showAsButtonOption}` with `true` or `false` with respect to your Connection Button selection.

    <AuthCodeGroup>
      ```bash cURL lines theme={null}
      curl --request POST \
        --url https://%7ByourAuth0Domain%7D/api/v2/organizations/%7BorgId%7D/enabled_connections \
        --header 'authorization: Bearer {yourMgmtApiAccessToken}' \
        --header 'cache-control: no-cache' \
        --header 'content-type: application/json' \
        --data '{ "connection_id": "{connectionId}", "assign_membership_on_login": "{assignMembershipOption}","is_signup_enabled","{isSignupEnabled}", "show_as_button": "{showAsButtonOption}" }'
      ```

      ```csharp C# lines theme={null}
      var client = new RestClient("https://%7ByourAuth0Domain%7D/api/v2/organizations/%7BorgId%7D/enabled_connections");
      var request = new RestRequest(Method.POST);
      request.AddHeader("content-type", "application/json");
      request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
      request.AddHeader("cache-control", "no-cache");
      request.AddParameter("application/json", "{ \"connection_id\": \"{connectionId}\", \"assign_membership_on_login\": \"{assignMembershipOption}\",\"is_signup_enabled\",\"{isSignupEnabled}\", \"show_as_button\": \"{showAsButtonOption}\" }", ParameterType.RequestBody);
      IRestResponse response = client.Execute(request);
      ```

      ```go Go lines expandable theme={null}
      package main

      import (
      	"fmt"
      	"strings"
      	"net/http"
      	"io/ioutil"
      )

      func main() {

      	url := "https://%7ByourAuth0Domain%7D/api/v2/organizations/%7BorgId%7D/enabled_connections"

      	payload := strings.NewReader("{ \"connection_id\": \"{connectionId}\", \"assign_membership_on_login\": \"{assignMembershipOption}\",\"is_signup_enabled\",\"{isSignupEnabled}\", \"show_as_button\": \"{showAsButtonOption}\" }")

      	req, _ := http.NewRequest("POST", url, payload)

      	req.Header.Add("content-type", "application/json")
      	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")
      	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))

      }
      ```

      ```java Java lines theme={null}
      HttpResponse<String> response = Unirest.post("https://%7ByourAuth0Domain%7D/api/v2/organizations/%7BorgId%7D/enabled_connections")
        .header("content-type", "application/json")
        .header("authorization", "Bearer {yourMgmtApiAccessToken}")
        .header("cache-control", "no-cache")
        .body("{ \"connection_id\": \"{connectionId}\", \"assign_membership_on_login\": \"{assignMembershipOption}\",\"is_signup_enabled\",\"{isSignupEnabled}\", \"show_as_button\": \"{showAsButtonOption}\" }")
        .asString();
      ```

      ```javascript Node.JS lines theme={null}
      var axios = require("axios").default;

      var options = {
        method: 'POST',
        url: 'https://%7ByourAuth0Domain%7D/api/v2/organizations/%7BorgId%7D/enabled_connections',
        headers: {
          'content-type': 'application/json',
          authorization: 'Bearer {yourMgmtApiAccessToken}',
          'cache-control': 'no-cache'
        },
        data: '{ "connection_id": "{connectionId}", "assign_membership_on_login": "{assignMembershipOption}","is_signup_enabled","{isSignupEnabled}", "show_as_button": "{showAsButtonOption}" }'
      };

      axios.request(options).then(function (response) {
        console.log(response.data);
      }).catch(function (error) {
        console.error(error);
      });
      ```

      ```objc Obj-C lines expandable theme={null}
      #import <Foundation/Foundation.h>

      NSDictionary *headers = @{ @"content-type": @"application/json",
                                 @"authorization": @"Bearer {yourMgmtApiAccessToken}",
                                 @"cache-control": @"no-cache" };

      NSData *postData = [[NSData alloc] initWithData:[@"{ "connection_id": "{connectionId}", "assign_membership_on_login": "{assignMembershipOption}","is_signup_enabled","{isSignupEnabled}", "show_as_button": "{showAsButtonOption}" }" dataUsingEncoding:NSUTF8StringEncoding]];

      NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://%7ByourAuth0Domain%7D/api/v2/organizations/%7BorgId%7D/enabled_connections"]
                                                             cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                         timeoutInterval:10.0];
      [request setHTTPMethod:@"POST"];
      [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];
      ```

      ```php PHP lines expandable theme={null}
      $curl = curl_init();

      curl_setopt_array($curl, [
        CURLOPT_URL => "https://%7ByourAuth0Domain%7D/api/v2/organizations/%7BorgId%7D/enabled_connections",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => "",
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => "POST",
        CURLOPT_POSTFIELDS => "{ \"connection_id\": \"{connectionId}\", \"assign_membership_on_login\": \"{assignMembershipOption}\",\"is_signup_enabled\",\"{isSignupEnabled}\", \"show_as_button\": \"{showAsButtonOption}\" }",
        CURLOPT_HTTPHEADER => [
          "authorization: Bearer {yourMgmtApiAccessToken}",
          "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;
      }
      ```

      ```python Python lines theme={null}
      import http.client

      conn = http.client.HTTPSConnection("")

      payload = "{ \"connection_id\": \"{connectionId}\", \"assign_membership_on_login\": \"{assignMembershipOption}\",\"is_signup_enabled\",\"{isSignupEnabled}\", \"show_as_button\": \"{showAsButtonOption}\" }"

      headers = {
          'content-type': "application/json",
          'authorization': "Bearer {yourMgmtApiAccessToken}",
          'cache-control': "no-cache"
          }

      conn.request("POST", "%7ByourAuth0Domain%7D/api/v2/organizations/%7BorgId%7D/enabled_connections", payload, headers)

      res = conn.getresponse()
      data = res.read()

      print(data.decode("utf-8"))
      ```

      ```ruby Ruby lines theme={null}
      require 'uri'
      require 'net/http'
      require 'openssl'

      url = URI("https://%7ByourAuth0Domain%7D/api/v2/organizations/%7BorgId%7D/enabled_connections")

      http = Net::HTTP.new(url.host, url.port)
      http.use_ssl = true
      http.verify_mode = OpenSSL::SSL::VERIFY_NONE

      request = Net::HTTP::Post.new(url)
      request["content-type"] = 'application/json'
      request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'
      request["cache-control"] = 'no-cache'
      request.body = "{ \"connection_id\": \"{connectionId}\", \"assign_membership_on_login\": \"{assignMembershipOption}\",\"is_signup_enabled\",\"{isSignupEnabled}\", \"show_as_button\": \"{showAsButtonOption}\" }"

      response = http.request(request)
      puts response.read_body
      ```

      ```swift Swift lines expandable theme={null}
      import Foundation

      let headers = [
        "content-type": "application/json",
        "authorization": "Bearer {yourMgmtApiAccessToken}",
        "cache-control": "no-cache"
      ]

      let postData = NSData(data: "{ "connection_id": "{connectionId}", "assign_membership_on_login": "{assignMembershipOption}","is_signup_enabled","{isSignupEnabled}", "show_as_button": "{showAsButtonOption}" }".data(using: String.Encoding.utf8)!)

      let request = NSMutableURLRequest(url: NSURL(string: "https://%7ByourAuth0Domain%7D/api/v2/organizations/%7BorgId%7D/enabled_connections")! as URL,
                                              cachePolicy: .useProtocolCachePolicy,
                                          timeoutInterval: 10.0)
      request.httpMethod = "POST"
      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()
      ```
    </AuthCodeGroup>

    <Callout icon="file-lines">
      **Find Your Auth0 Domain**

      If your Auth0 domain is your tenant name, your regional subdomain (unless your tenant is in the US region and was created before June 2020), plus `.auth0.com`. For example, if your tenant name were `travel0`, your Auth0 domain name would be `travel0.us.auth0.com`. (If your tenant were in the US and created before June 2020, then your domain name would be `https://travel0.auth0.com`.)

      If you are using custom domains, this should be your custom domain name.
    </Callout>

    <table>
      <thead>
        <tr>
          <th><strong>Value</strong></th>
          <th><strong>Description</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>ID of the organization for which you want to enable a connection.</td>
        </tr>

        <tr>
          <td><a href="/docs/secure/tokens/access-tokens/management-api-access-tokens">Access Token for the Management API</a> with the scope <code>create:organization\_connections</code>.</td>
        </tr>

        <tr>
          <td>ID of the connection you want to enable for the specified organization.</td>
        </tr>

        <tr>
          <td>Indicates whether you want users that log in with this connection to automatically be granted membership in the organization. When set to <code>true</code>, users will automatically be granted membership. When set to <code>false</code>, they will not automatically be granted membership.</td>
        </tr>

        <tr>
          <td>
            Determines whether users can access a self-service signup link on the login prompt. When set to <code>true</code>, the signup link displays on the prompt. When set to <code>false</code>, the link remains hidden.<br /><br />
            <strong>Note</strong>: To enable this option, you must also set  to <code>true</code>.
          </td>
        </tr>

        <tr>
          <td>Indicates whether you want a specific Enterprise connection to display as an option on the organization login prompt. When set to <code>true</code>, the connection displays as a button on the prompt. When set to <code>false</code>, the connection is hidden on the prompt.</td>
        </tr>
      </tbody>
    </table>

    ##### Response status codes

    Possible response status codes are as follows:

    | **Status code** | **Error code**       | **Message**                                                                                          | **Cause**                                                                          |
    | --------------- | -------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
    | `201`           |                      | Connection successfully added to organization.                                                       |                                                                                    |
    | `401`           |                      | Invalid token.                                                                                       |                                                                                    |
    | `401`           |                      | Invalid signature received for JSON Web Token validation.                                            |                                                                                    |
    | `401`           |                      | Client is not global.                                                                                |                                                                                    |
    | `403`           | `insufficient_scope` | Insufficient scope; expected any of: `create:organizations_connections`.                             | Tried to read/write a field that is not allowed with provided bearer token scopes. |
    | `429`           |                      | Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. |                                                                                    |
  </Tab>
</Tabs>


# Grant Just-In-Time Membership to an Organization Connection
Source: https://auth0.com/docs/manage-users/organizations/configure-organizations/grant-just-in-time-membership

Learn how to grant Just-in-Time (JIT) membership to organizations.

Granting just-in-time membership allows users that log in via an enabled connection to automatically be given membership to an [organization](/docs/manage-users/organizations/organizations-overview).

To automatically grant membership when users log in to an organization, you must first [configure and enable a connection](/docs/manage-users/organizations/configure-organizations/enable-connections) for the organization. While enabling your connection, select **Enable Auto-Membership** to allow all users logging in with the connection to be automatically added as members of this organization.


# Invite Organization Members
Source: https://auth0.com/docs/manage-users/organizations/configure-organizations/invite-members

Learn how to invite members to organizations via email.

<Card title="Availability varies by Auth0 plan">
  Both your specific login implementation and your Auth0 plan or custom agreement affect whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

If you would like to assign a member to an [Organization](/docs/manage-users/organizations/organizations-overview), but the user does not yet exist in your data store (or the user exists in your data store but is not yet a member of your organization), you can invite them to the organization. In this case, the user will receive an email containing a link that will allow them to create an account or log in and join the organization, optionally with predefined roles, and be redirected to your application so that they can immediately start using it.

<Warning>
  Organization member roles are separate from the roles assigned to users through Auth0's [Role-Based Access Control](/docs/manage-users/access-control/rbac). When a predefined role is applied to a user who accepts an invitation to an Organization, the assigned role only applies when the user is logging in via that Organization. You can [see Organization Member roles](/docs/manage-users/organizations/configure-organizations/retrieve-member-roles) in the Dashboard.
</Warning>

To configure the invitation flow:

1. [Integrate the membership invitation flow into your application](#integrate-the-membership-invitation-flow-into-your-application)
2. [Customize the user invitation flow](#customize-the-user-invitation-flow)
3. [Send membership invitations](#send-membership-invitations)

<Callout icon="file-lines">
  **Limitations**

  * Auth0 can send user invitations only via email. If you prefer to send the invitation in another way, you can choose to only generate an invitation URL.
  * Invited users must log in or create an account with the email address to which the invitation was sent.
</Callout>

## Integrate the membership invitation flow into your application

For user invitations to work, you must set up a route in your application as part of the invitation acceptance flow and [configure an associated default login route](/docs/authenticate/login/auth0-universal-login/configure-default-login-routes) for your tenant or application. A link to the configured URI will be included in the email invitation that is sent to users.

### Configure the URI

If the URI should be shared across all of your applications, you can set the **Tenant Login URL** at [Auth0 Dashboard > Settings > Advanced](https://manage.auth0.com/#/tenant/advanced). Otherwise, you can set the URI on a per-application basis by using **Application Login URI** in your application's settings, which you can reach from [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications).

### Specify route behavior

The route in your application must accept the `invitation` and `organization` parameters in the query string, and then call the Auth0 Authentication API [Authorization](https://auth0.com/docs/api/authentication#authorize-application) endpoint with both parameters.

<Callout icon="file-lines">
  To support multi-tenant scenarios where the organization name is used as a subdomain or path variable in your application (for example, `acme.myapp.com`), the `organization_name` parameter is also included in the invitation link sent to users. This parameter does not need to be sent to the Authentication API [Authorization](https://auth0.com/docs/api/authentication#authorize-application) endpoint.
</Callout>

For example, if you have an organization-enabled application with an **Application Login URI** set to `https://myapp.com/login`, then the link in the email invitation sent to the end user would be: `https://myapp.com/login?invitation={invitation_ticket_id}&organization={organization_id}&organization_name={organization_name}`.

## Customize the user invitation flow

<Callout icon="file-lines">
  To customize the user invitation flow, you must use custom domains. Free plans get one free custom domain; additional custom domains are available with any paid pricing plan.
</Callout>

To customize the user invitation prompt and email that the user receives, modify the <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> prompt and email templates. To learn more, read these pages:

* [Universal Login Page Templates](/docs/customize/login-pages/universal-login/customize-templates)
* [Universal Login Internationalization](/docs/customize/internationalization-and-localization/universal-login-internationalization)
* [Customize Email Templates](/docs/customize/email/email-templates)

### Localization

Since the locale of the invited user is not known ahead of time, you can send an optional `user_metadata` parameter to the invitation endpoint using the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. When localizing the user invitation flow, you can access this parameter through the **User Invitation** email template and [use the same logic as you would with other multilingual email templates](/docs/customize/email/email-templates).

For the invited user to see the invitation in the appropriate language, your application will need to send the `ui_locales` parameter or the invited user's browser must send the appropriate `Accept-Language` header. To learn more, read [Customize Email Templates: Multilingual Email Templates](/docs/customize/email/email-templates).

## Send membership invitations

You can [send organization membership invitations](/docs/manage-users/organizations/configure-organizations/send-membership-invitations) to users using either the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the Management API. If you prefer to send the invitation using your own email service, you can choose to only generate an invitation URL. Otherwise, the user will receive an email containing the link, which will allow them to log in to the organization using a configured connection.

<Callout icon="file-lines">
  When a user accepts an invitation, their email address will be marked as verified.

  If the user accepts an invitation through federated login, then the identity provider must return the email address that matches the email address to which the invitation was sent. The email verification will not be overridden with the value returned by the identity provider on subsequent logins.

  If the user does not accept an invitation before it expires, the invitation will be marked as expired and eventually deleted from the [Auth0 Dashboard](/docs/get-started/auth0-overview/dashboard).
</Callout>


# Remove Roles from Organization Members
Source: https://auth0.com/docs/manage-users/organizations/configure-organizations/remove-member-roles

Learn how to remove roles from Organization members using the Auth0 Dashboard or Management API.

You can remove roles from [organization](/docs/manage-users/organizations/organizations-overview) members using either the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## Auth0 Dashboard

To remove a role from an organization member via the Auth0 Dashboard:

1. Navigate to [Auth0 Dashboard > Organizations](https://manage.auth0.com/#/organizations), and select the organization for which you want to configure membership.
2. Select the **Members** view, and click the name of the member from which you would like to remove a role.
3. Locate the role you would like to remove, click its trash can icon, and confirm.

## Management API

To remove roles from an organization member via the Management API:
Make a `DELETE` call to the `Delete Organization Member Roles` endpoint. Be sure to replace the `ORG_ID`, `MGMT_API_ACCESS_TOKEN`, `USER_ID`, and `ROLE_ID` placeholder values with your organization ID, Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, user ID, and role ID, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url 'https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --data '{ "roles": [ "ROLE_ID", "ROLE_ID", "ROLE_ID" ] }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles");
  var request = new RestRequest(Method.DELETE);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("undefined", "{ "roles": [ "ROLE_ID", "ROLE_ID", "ROLE_ID" ] }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles"

  	payload := strings.NewReader("{ "roles": [ "ROLE_ID", "ROLE_ID", "ROLE_ID" ] }")

  	req, _ := http.NewRequest("DELETE", url, payload)

  	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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.delete("https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "roles": [ "ROLE_ID", "ROLE_ID", "ROLE_ID" ] }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'DELETE',
    url: 'https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN', 'cache-control': 'no-cache'},
    data: {roles: ['ROLE_ID', 'ROLE_ID', 'ROLE_ID']}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"roles": @[ @"ROLE_ID", @"ROLE_ID", @"ROLE_ID" ] };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"DELETE"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_POSTFIELDS => "{ "roles": [ "ROLE_ID", "ROLE_ID", "ROLE_ID" ] }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN",
      "cache-control: no-cache"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "roles": [ "ROLE_ID", "ROLE_ID", "ROLE_ID" ] }"

  headers = {
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
      'cache-control': "no-cache"
      }

  conn.request("DELETE", "/{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Delete.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request["cache-control"] = 'no-cache'
  request.body = "{ "roles": [ "ROLE_ID", "ROLE_ID", "ROLE_ID" ] }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = ["roles": ["ROLE_ID", "ROLE_ID", "ROLE_ID"]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "DELETE"
  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()
  ```
</AuthCodeGroup>

<Callout icon="file-lines">
  **Find Your Auth0 Domain**

  If your Auth0 domain is your tenant name, your regional subdomain (unless your tenant is in the US region and was created before June 2020), plus `.auth0.com`. For example, if your tenant name were `travel0`, your Auth0 domain name would be `travel0.us.auth0.com`. (If your tenant were in the US and created before June 2020, then your domain name would be `https://travel0.auth0.com`.)

  If you are using custom domains, this should be your custom domain name.
</Callout>

| Value                   | Description                                                                                                                                              |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ORG_ID`                | ID of the organization for which you want to remove roles from a member.                                                                                 |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the scope `delete:organization_member_roles`. |
| `USER_ID`               | ID of the user from which you want to remove the specified role(s).                                                                                      |
| `ROLE_ID`               | ID of the role you want to remove from the specified user for the specified organization.                                                                |

### Response status codes

Possible response status codes are as follows:

| Status code | Error code             | Message                                                                                              | Cause                                                                              |
| ----------- | ---------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `204`       |                        | Roles successfully removed from organization member.                                                 |                                                                                    |
| `400`       | `invalid_body`         | Invalid request body. The message will vary depending on the cause.                                  | The request payload is not valid.                                                  |
| `400`       | `invalid_query_string` | Invalid request query string. The message will vary depending on the cause.                          | The query string is not valid.                                                     |
| `401`       |                        | Invalid token.                                                                                       |                                                                                    |
| `401`       |                        | Invalid signature received for JSON Web Token validation.                                            |                                                                                    |
| `401`       |                        | Client is not global.                                                                                |                                                                                    |
| `403`       | `insufficient_scope`   | Insufficient scope; expected any of: `delete:organization_member_roles`.                             | Tried to read/write a field that is not allowed with provided bearer token scopes. |
| `429`       |                        | Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. |                                                                                    |


# Remove Members From Organizations
Source: https://auth0.com/docs/manage-users/organizations/configure-organizations/remove-members

Learn how to remove members from Organizations directly using the Auth0 Dashboard or Management API.

You can remove members from [organizations](/docs/manage-users/organizations/organizations-overview) using either the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. Removing a user from an organization will remove only that user’s membership in the given organization; it will not remove the user from the connection or the Auth0 tenant. The removal process takes approximately 5 - 10 seconds.

## Auth0 Dashboard

To remove a member via the Auth0 Dashboard:

1. Navigate to [Auth0 Dashboard > Organizations](https://manage.auth0.com/#/organizations), and select the organization for which you want to configure membership.
2. Select the **Members** view, locate the member you want to remove, and expand its **More Options** (**...**) menu.
3. Select **Remove member**, and confirm.

## Management API

To remove members via the Management API:
Make a `DELETE` call to the `Delete Organization Members` endpoint. Be sure to replace the `ORG_ID`, `MGMT_API_ACCESS_TOKEN`, and `USER_ID` placeholder values with your organization ID, Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, and user ID, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url 'https://{yourDomain}/api/v2/organizations/ORG_ID/members' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --data '{ "members": [ "USER_ID", "USER_ID", "USER_ID" ] }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/organizations/ORG_ID/members");
  var request = new RestRequest(Method.DELETE);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("undefined", "{ "members": [ "USER_ID", "USER_ID", "USER_ID" ] }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/organizations/ORG_ID/members"

  	payload := strings.NewReader("{ "members": [ "USER_ID", "USER_ID", "USER_ID" ] }")

  	req, _ := http.NewRequest("DELETE", url, payload)

  	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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.delete("https://{yourDomain}/api/v2/organizations/ORG_ID/members")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "members": [ "USER_ID", "USER_ID", "USER_ID" ] }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'DELETE',
    url: 'https://{yourDomain}/api/v2/organizations/ORG_ID/members',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN', 'cache-control': 'no-cache'},
    data: {members: ['USER_ID', 'USER_ID', 'USER_ID']}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"members": @[ @"USER_ID", @"USER_ID", @"USER_ID" ] };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/organizations/ORG_ID/members"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"DELETE"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/organizations/ORG_ID/members",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_POSTFIELDS => "{ "members": [ "USER_ID", "USER_ID", "USER_ID" ] }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN",
      "cache-control: no-cache"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "members": [ "USER_ID", "USER_ID", "USER_ID" ] }"

  headers = {
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
      'cache-control': "no-cache"
      }

  conn.request("DELETE", "/{yourDomain}/api/v2/organizations/ORG_ID/members", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/organizations/ORG_ID/members")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Delete.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request["cache-control"] = 'no-cache'
  request.body = "{ "members": [ "USER_ID", "USER_ID", "USER_ID" ] }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = ["members": ["USER_ID", "USER_ID", "USER_ID"]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/organizations/ORG_ID/members")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "DELETE"
  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()
  ```
</AuthCodeGroup>

<Callout icon="file-lines">
  **Find Your Auth0 Domain**

  If your Auth0 domain is your tenant name, your regional subdomain (unless your tenant is in the US region and was created before June 2020), plus `.auth0.com`. For example, if your tenant name were `travel0`, your Auth0 domain name would be `travel0.us.auth0.com`. (If your tenant were in the US and created before June 2020, then your domain name would be `https://travel0.auth0.com`.)

  If you are using custom domains, this should be your custom domain name.
</Callout>

| Value                   | Description                                                                                                                                         |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ORG_ID`                | ID of the organization for which you want to remove membership.                                                                                     |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the scope `delete:organization_members`. |
| `USER_ID`               | ID of the user(s) you want to remove from the specified organization.                                                                               |

### Response status codes

Possible response status codes are as follows:

| Status code | Error code             | Message                                                                                              | Cause                                                                              |
| ----------- | ---------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `204`       |                        | Users successfully removed from organization.                                                        |                                                                                    |
| `400`       | `invalid_body`         | Invalid request body. The message will vary depending on the cause.                                  | The request payload is not valid.                                                  |
| `400`       | `invalid_query_string` | Invalid request query string. The message will vary depending on the cause.                          | The query string is not valid.                                                     |
| `401`       |                        | Invalid token.                                                                                       |                                                                                    |
| `401`       |                        | Invalid signature received for JSON Web Token validation.                                            |                                                                                    |
| `401`       |                        | Client is not global.                                                                                |                                                                                    |
| `403`       | `insufficient_scope`   | Insufficient scope; expected any of: `delete:organization_members`.                                  | Tried to read/write a field that is not allowed with provided bearer token scopes. |
| `429`       |                        | Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. |                                                                                    |


# Retrieve Organization Connections
Source: https://auth0.com/docs/manage-users/organizations/configure-organizations/retrieve-connections

Learn how to retrieve Organization connections using the Auth0 Management API.

When working with [organizations](/docs/manage-users/organizations/organizations-overview) programmatically, you may need to retrieve a list of connections enabled for an organization.

You can view the connections associated with an organization using either the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## Auth0 Dashboard

1. Navigate to [Auth0 Dashboard > Organizations](https://manage.auth0.com/#/organizations), and select the organization.
2. Select the **Connections** view.

## Management API

Make a `GET` call to the `Get Organization Connections` endpoint. Be sure to replace the `ORG_ID` and `MGMT_API_ACCESS_TOKEN` placeholder values with your organization ID and Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/organizations/ORG_ID/enabled_connections' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/organizations/ORG_ID/enabled_connections");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/organizations/ORG_ID/enabled_connections"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/organizations/ORG_ID/enabled_connections")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/organizations/ORG_ID/enabled_connections',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/organizations/ORG_ID/enabled_connections"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/organizations/ORG_ID/enabled_connections",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer MGMT_API_ACCESS_TOKEN" }

  conn.request("GET", "/{yourDomain}/api/v2/organizations/ORG_ID/enabled_connections", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/organizations/ORG_ID/enabled_connections")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer MGMT_API_ACCESS_TOKEN"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/organizations/ORG_ID/enabled_connections")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

<Callout icon="file-lines">
  **Find Your Auth0 Domain**

  If your Auth0 domain is your tenant name, your regional subdomain (unless your tenant is in the US region and was created before June 2020), plus `.auth0.com`. For example, if your tenant name were `travel0`, your Auth0 domain name would be `travel0.us.auth0.com`. (If your tenant were in the US and created before June 2020, then your domain name would be `https://travel0.auth0.com`.)

  If you are using custom domains, this should be your custom domain name.
</Callout>

| Value                   | Description                                                                                                                                           |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ORG_ID`                | ID of the organization for which you want to retrieve enabled connections.                                                                            |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the scope `read:organization_connections`. |

### Response status codes

Possible response status codes are as follows:

| Status code | Error code           | Message                                                                                              | Cause                                                                              |
| ----------- | -------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `200`       |                      | Connections successfully retrieved.                                                                  |                                                                                    |
| `400`       | `invalid_body`       | Invalid request body. The message will vary depending on the cause.                                  | The request payload is not valid.                                                  |
| `401`       |                      | Invalid token.                                                                                       |                                                                                    |
| `401`       |                      | Invalid signature received for JSON Web Token validation.                                            |                                                                                    |
| `401`       |                      | Client is not global.                                                                                |                                                                                    |
| `403`       | `insufficient_scope` | Insufficient scope; expected any of: `read:organization_connections`.                                | Tried to read/write a field that is not allowed with provided bearer token scopes. |
| `429`       |                      | Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. |                                                                                    |


# Retrieve Member Roles for an Organization
Source: https://auth0.com/docs/manage-users/organizations/configure-organizations/retrieve-member-roles

Learn how to retrieve member roles for an Organization using the Auth0 Dashboard and Management API.

When working with [organizations](/docs/manage-users/organizations/organizations-overview) programmatically, you may need to retrieve a list of roles assigned to a member of an organization.

You can view the roles associated with an organization member using either the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## Auth0 Dashboard

1. Navigate to [Auth0 Dashboard > Organizations](https://manage.auth0.com/#/organizations), and select the organization for which you want to view membership.
2. Select the **Members** view, and select the user for whom you want to view roles.

## Management API

Make a `GET` call to the `Get Organization Member Roles` endpoint. Be sure to replace the `ORG_ID`, `USER_ID`, and `MGMT_API_ACCESS_TOKEN` placeholder values with your organization ID, member's user ID, and Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer MGMT_API_ACCESS_TOKEN" }

  conn.request("GET", "/{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer MGMT_API_ACCESS_TOKEN"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/organizations/ORG_ID/members/USER_ID/roles")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

<Callout icon="file-lines">
  **Find Your Auth0 Domain**

  If your Auth0 domain is your tenant name, your regional subdomain (unless your tenant is in the US region and was created before June 2020), plus `.auth0.com`. For example, if your tenant name were `travel0`, your Auth0 domain name would be `travel0.us.auth0.com`. (If your tenant were in the US and created before June 2020, then your domain name would be `https://travel0.auth0.com`.)

  If you are using custom domains, this should be your custom domain name.
</Callout>

| Value                   | Description                                                                                                                                            |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ORG_ID`                | ID of the organization for which you want to retrieve a member's roles.                                                                                |
| `USER_ID`               | User ID of the member for which you want to retrieve roles.                                                                                            |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the scope `read:organization_member_roles`. |

#### Response status codes

Possible response status codes are as follows:

| Status code | Error code             | Message                                                                                              | Cause                                                                              |
| ----------- | ---------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `200`       |                        | Roles successfully retrieved.                                                                        |                                                                                    |
| `400`       | `invalid_query_string` | Invalid request query string. The message will vary depending on the cause.                          | The query string is not valid.                                                     |
| `401`       |                        | Invalid token.                                                                                       |                                                                                    |
| `401`       |                        | Invalid signature received for JSON Web Token validation.                                            |                                                                                    |
| `401`       |                        | Client is not global.                                                                                |                                                                                    |
| `403`       | `insufficient_scope`   | Insufficient scope; expected any of: `read:organization_member_roles`.                               | Tried to read/write a field that is not allowed with provided bearer token scopes. |
| `429`       |                        | Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. |                                                                                    |


# Retrieve Organization Members
Source: https://auth0.com/docs/manage-users/organizations/configure-organizations/retrieve-members

Learn how to retrieve Organization members using the Auth0 Management API.

When working with [organizations](/docs/manage-users/organizations/organizations-overview) programmatically, you may need to retrieve a list of members for an organization.

You can view the members associated with an organization using either the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## Auth0 Dashboard

1. Navigate to [Auth0 Dashboard > Organizations](https://manage.auth0.com/#/organizations), and select the organization for which you want to view membership.
2. Select the **Members** view.

## Management API

<Warning>
  Up to 1000 organization members can be displayed using the Auth0 Dashboard or Management API, though more may exist.
</Warning>

Make a `GET` call to the `Get Organization Members` endpoint. Be sure to replace the `ORG_ID` and `MGMT_API_ACCESS_TOKEN` placeholder values with your organization ID and Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/organizations/ORG_ID/members' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/organizations/ORG_ID/members");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/organizations/ORG_ID/members"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/organizations/ORG_ID/members")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/organizations/ORG_ID/members',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/organizations/ORG_ID/members"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/organizations/ORG_ID/members",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer MGMT_API_ACCESS_TOKEN" }

  conn.request("GET", "/{yourDomain}/api/v2/organizations/ORG_ID/members", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/organizations/ORG_ID/members")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer MGMT_API_ACCESS_TOKEN"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/organizations/ORG_ID/members")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

<Callout icon="file-lines">
  **Find Your Auth0 Domain**

  If your Auth0 domain is your tenant name, your regional subdomain (unless your tenant is in the US region and was created before June 2020), plus `.auth0.com`. For example, if your tenant name were `travel0`, your Auth0 domain name would be `travel0.us.auth0.com`. (If your tenant were in the US and created before June 2020, then your domain name would be `https://travel0.auth0.com`.)

  If you are using custom domains, this should be your custom domain name.
</Callout>

| Value                   | Description                                                                                                                                       |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ORG_ID`                | ID of the organization for which you want to retrieve members.                                                                                    |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the scope `read:organization_members`. |

### Response status codes

Possible response status codes are as follows:

| Status code | Error code           | Message                                                                                              | Cause                                                                              |
| ----------- | -------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `200`       |                      | Members successfully retrieved.                                                                      |                                                                                    |
| `400`       | `invalid_paging`     | Requesting page exceeds the allowed maximum of 1000 records.                                         | API has been limited to only return up to 1000 records.                            |
| `400`       | `invalid_body`       | Invalid request body. The message will vary depending on the cause.                                  | The request payload is not valid.                                                  |
| `401`       |                      | Invalid token.                                                                                       |                                                                                    |
| `401`       |                      | Invalid signature received for JSON Web Token validation.                                            |                                                                                    |
| `401`       |                      | Client is not global.                                                                                |                                                                                    |
| `403`       | `insufficient_scope` | Insufficient scope; expected any of: `read:organization_members`.                                    | Tried to read/write a field that is not allowed with provided bearer token scopes. |
| `429`       |                      | Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. |                                                                                    |


# Retrieve Organizations
Source: https://auth0.com/docs/manage-users/organizations/configure-organizations/retrieve-organizations

Learn how to retrieve Organizations using the Auth0 Dashboard and Management API.

When working with [organizations](/docs/manage-users/organizations/organizations-overview) programmatically, you may need to retrieve either a list of all organizations or organizations individually by name or ID.

<Warning>
  The Management API should be accessed using only a confidential client. Its use is subject to [Auth0 Management API rate limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/management-api-endpoint-rate-limits).
</Warning>

## Retrieve tenant organizations

You can retrieve all organizations for a tenant via the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

<Warning>
  To retrieve more than 1000 results, you must use the checkpoint pagination method. To learn more, see the [Get Organizations endpoint](https://auth0.com/docs/api/management/v2#!/Organizations/get_organizations) in our API Explorer.
</Warning>

Make a `GET` call to the `Get Organizations` endpoint. Be sure to replace the `MGMT_API_ACCESS_TOKEN` placeholder value with your Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/organizations' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/organizations");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/organizations"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/organizations")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/organizations',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/organizations"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/organizations",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer MGMT_API_ACCESS_TOKEN" }

  conn.request("GET", "/{yourDomain}/api/v2/organizations", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/organizations")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer MGMT_API_ACCESS_TOKEN"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/organizations")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

<Callout icon="file-lines">
  **Find Your Auth0 Domain**

  If your Auth0 domain is your tenant name, your regional subdomain (unless your tenant is in the US region and was created before June 2020), plus `.auth0.com`. For example, if your tenant name were `travel0`, your Auth0 domain name would be `travel0.us.auth0.com`. (If your tenant were in the US and created before June 2020, then your domain name would be `https://travel0.auth0.com`.)

  If you are using custom domains, this should be your custom domain name.
</Callout>

| Value                   | Description                                                                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the scope `read:organizations`. |

### Response status codes

Possible response status codes are as follows:

| Status code | Error code             | Message                                                                                              | Cause                                                                              |
| ----------- | ---------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `200`       |                        | Organizations successfully retrieved.                                                                |                                                                                    |
| `400`       | `invalid_paging`       | Requesting page exceeds the allowed maximum of 1000 records.                                         | API has been limited to only return up to 1000 records.                            |
| `400`       | `invalid_query_string` | Invalid request query string. The message will vary depending on the cause.                          | The query string is not valid.                                                     |
| `401`       |                        | Invalid token.                                                                                       |                                                                                    |
| `401`       |                        | Invalid signature received for JSON Web Token validation.                                            |                                                                                    |
| `401`       |                        | Client is not global.                                                                                |                                                                                    |
| `403`       | `insufficient_scope`   | Insufficient scope; expected any of: `read:organizations`.                                           | Tried to read/write a field that is not allowed with provided bearer token scopes. |
| `429`       |                        | Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. |                                                                                    |

## Retrieve organization by ID

You can retrieve an organization by its ID through the Management API.

Make a `GET` call to the `Get Organization` endpoint. Be sure to replace the `ORG_ID` and `MGMT_API_ACCESS_TOKEN` placeholder values with your organization ID and Management API Access Token, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/organizations/ORG_ID' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/organizations/ORG_ID");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/organizations/ORG_ID"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/organizations/ORG_ID")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/organizations/ORG_ID',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/organizations/ORG_ID"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/organizations/ORG_ID",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer MGMT_API_ACCESS_TOKEN" }

  conn.request("GET", "/{yourDomain}/api/v2/organizations/ORG_ID", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/organizations/ORG_ID")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer MGMT_API_ACCESS_TOKEN"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/organizations/ORG_ID")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

<Callout icon="file-lines">
  **Find Your Auth0 Domain**

  If your Auth0 domain is your tenant name, your regional subdomain (unless your tenant is in the US region and was created before June 2020), plus `.auth0.com`. For example, if your tenant name were `travel0`, your Auth0 domain name would be `travel0.us.auth0.com`. (If your tenant were in the US and created before June 2020, then your domain name would be `https://travel0.auth0.com`.)

  If you are using custom domains, this should be your custom domain name.
</Callout>

| Value                   | Description                                                                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `ORG_ID`                | ID of the organization you want to retrieve.                                                                                               |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the scope `read:organizations`. |

### Response status codes

Possible response status codes are as follows:

| Status code | Error code             | Message                                                                                              | Cause                                                                              |
| ----------- | ---------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `200`       |                        | Organization successfully retrieved.                                                                 |                                                                                    |
| `400`       | `invalid_query_string` | Invalid request query string. The message will vary depending on the cause.                          | The query string is not valid.                                                     |
| `401`       |                        | Invalid token.                                                                                       |                                                                                    |
| `401`       |                        | Invalid signature received for JSON Web Token validation.                                            |                                                                                    |
| `401`       |                        | Client is not global.                                                                                |                                                                                    |
| `403`       | `insufficient_scope`   | Insufficient scope; expected any of: `read:organizations`.                                           | Tried to read/write a field that is not allowed with provided bearer token scopes. |
| `429`       |                        | Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. |                                                                                    |

## Retrieve organization by name

You can retrieve an organization by its name through the Management API.

Make a `GET` call to the `Get Organization by Name` endpoint. Be sure to replace the `ORG_NAME` and `MGMT_API_ACCESS_TOKEN` placeholder values with your organization ID and Management API Access Token, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/organizations/name/ORG_NAME' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/organizations/name/ORG_NAME");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/organizations/name/ORG_NAME"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/organizations/name/ORG_NAME")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/organizations/name/ORG_NAME',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/organizations/name/ORG_NAME"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/organizations/name/ORG_NAME",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer MGMT_API_ACCESS_TOKEN" }

  conn.request("GET", "/{yourDomain}/api/v2/organizations/name/ORG_NAME", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/organizations/name/ORG_NAME")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer MGMT_API_ACCESS_TOKEN"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/organizations/name/ORG_NAME")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

<Callout icon="file-lines">
  **Find Your Auth0 Domain**

  If your Auth0 domain is your tenant name, your regional subdomain (unless your tenant is in the US region and was created before June 2020), plus `.auth0.com`. For example, if your tenant name were `travel0`, your Auth0 domain name would be `travel0.us.auth0.com`. (If your tenant were in the US and created before June 2020, then your domain name would be `https://travel0.auth0.com`.)

  If you are using custom domains, this should be your custom domain name.
</Callout>

| Value                   | Description                                                                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `ORG_ NAME`             | Name of the organization you want to retrieve. Maximum length of 50 characters.                                                            |
| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the scope `read:organizations`. |

### Response status codes

Possible response status codes are as follows:

| Status code | Error code             | Message                                                                                              | Cause                                                                              |
| ----------- | ---------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `200`       |                        | Organizations successfully retrieved.                                                                |                                                                                    |
| `400`       | `invalid_query_string` | Invalid request query string. The message will vary depending on the cause.                          | The query string is not valid.                                                     |
| `401`       |                        | Invalid token.                                                                                       |                                                                                    |
| `401`       |                        | Invalid signature received for JSON Web Token validation.                                            |                                                                                    |
| `401`       |                        | Client is not global.                                                                                |                                                                                    |
| `403`       | `insufficient_scope`   | Insufficient scope; expected any of: `read:organizations`.                                           | Tried to read/write a field that is not allowed with provided bearer token scopes. |
| `429`       |                        | Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. |                                                                                    |


# Retrieve User's Organization Memberships
Source: https://auth0.com/docs/manage-users/organizations/configure-organizations/retrieve-user-membership

Learn how to retrieve Organization memberships for a user using the Auth0 Management API.

When working with [organizations](/docs/manage-users/organizations/organizations-overview) programmatically, you may need to retrieve a list of organizations to which a user is assigned membership.

## Management API

<Warning>
  Up to 1000 organization members can be displayed using the Auth0 Dashboard or Management API, though more may exist.
</Warning>

Make a `GET` call to the `Get User Organizations` endpoint. Be sure to replace the `USER_ID` and `MGMT_API_ACCESS_TOKEN` placeholder values with the user ID and your <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/users/USER_ID/organizations' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/USER_ID/organizations");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users/USER_ID/organizations"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/users/USER_ID/organizations")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/users/USER_ID/organizations',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/USER_ID/organizations"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/USER_ID/organizations",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer MGMT_API_ACCESS_TOKEN" }

  conn.request("GET", "/{yourDomain}/api/v2/users/USER_ID/organizations", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/USER_ID/organizations")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer MGMT_API_ACCESS_TOKEN"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/USER_ID/organizations")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

<Callout icon="file-lines">
  **Find Your Auth0 Domain**

  If your Auth0 domain is your tenant name, your regional subdomain (unless your tenant is in the US region and was created before June 2020), plus `.auth0.com`. For example, if your tenant name were `travel0`, your Auth0 domain name would be `travel0.us.auth0.com`. (If your tenant were in the US and created before June 2020, then your domain name would be `https://travel0.auth0.com`.)

  If you are using custom domains, this should be your custom domain name.
</Callout>

\| Value | Description |
\| `USER_ID` | ID of the user for which you want to retrieve organization membership. |
\| `MGMT_API_ACCESS_TOKEN` | [Access Token for the Management API](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the scope `read:organizations`. |

### Response status codes

Possible response status codes are as follows:

| Status code | Error code             | Message                                                                                              | Cause                                                                              |
| ----------- | ---------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `200`       |                        | Organizations successfully retrieved.                                                                |                                                                                    |
| `400`       | `invalid_uri`          | `invalid_request_uri`                                                                                | The path is not valid.                                                             |
| `400`       | `invalid_query_string` | Invalid request query string. The message will vary depending on the cause.                          | The query string is not valid.                                                     |
| `401`       |                        | Invalid token.                                                                                       |                                                                                    |
| `401`       |                        | Invalid signature received for JSON Web Token validation.                                            |                                                                                    |
| `403`       | `insufficient_scope`   | Insufficient scope; expected any of: `read:organizations`.                                           | Tried to read/write a field that is not allowed with provided bearer token scopes. |
| `404`       |                        | User not found                                                                                       |                                                                                    |
| `429`       |                        | Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. |                                                                                    |


# Search for Organizations
Source: https://auth0.com/docs/manage-users/organizations/configure-organizations/search-for-organizations

Learn how to search for Organizations using the Auth0 Dashboard.

From the Organizations section of your [Auth0 Dashboard](https://manage.auth0.com/#/organizations), you can search for [organizations](/docs/manage-users/organizations/organizations-overview) by name or display name.

<Frame>
  <img alt="Auth0 Dashboard - Organizations - Search Bar " />
</Frame>

The dropdown menu beside the search bar allows you to search by Name or Display Name. Entering three or fewer characters into the search bar will return exact matches only. If you enter four or more characters, fuzzy matches containing the string provided will be returned. For example, if you have an organization named "Big Holdings, Co.", and you enter the search terms `hold` or `ings`, the Big Holdings, Co. organization will be returned.

Searches return a maximum of 50 results. If the desired result isn’t found, try using a more specific search term.

<Warning>
  The organization search employs eventual consistency. Recently created or modified organizations may not immediately display in search results; however, the results will eventually accurately reflect the entities within your tenant.
</Warning>


# Search Organization Members
Source: https://auth0.com/docs/manage-users/organizations/configure-organizations/search-organization-members

How to use User Search to find members of an Organization

In addition to [listing organization members](/docs/manage-users/organizations/configure-organizations/retrieve-members), you can use [User Search](/docs/manage-users/user-search) to find users filtered by organization membership by using the `organization_id` parameter in a search.

For example, below is a filter for users that have an `acme.com` email domain but are not members of the Acme organization:

`email.domain:"acme.com" AND NOT organization_id:"ACME_ORG_ID"`

The following finds all users that are in the Acme organization and log in with a specific database connection.

`organization_id:"ACME_ORG_ID" AND identities.connection:"my-db-connection-name"`

The example below finds users whose email addresses start with jane and are members of the Acme organization.

`organization_id:"ACME_ORG_ID" AND email:jane*`

See [User Search](/docs/manage-users/user-search) for more details.


# Send Organization Membership Invitations
Source: https://auth0.com/docs/manage-users/organizations/configure-organizations/send-membership-invitations

Learn how to send membership invitations for Organizations using the Auth0 Dashboard or Management API.

You can send [organization](/docs/manage-users/organizations/organizations-overview) membership invitations to users using either the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## Auth0 Dashboard

To invite members via the Auth0 Dashboard:

1. Navigate to [Auth0 Dashboard > Organizations](https://manage.auth0.com/#/organizations), and select the organization for which you want to configure membership.
2. Select the **Invitations** view, and select **Invite Members**.
3. Select the Application to which you would like to invite the member, enter the email address of the user you would like to invite to the organization, and select **Send Invite(s)**.

   <Callout icon="file-lines">
     Optionally, you can specify the connection with which you want users to accept the invitation, and roles you want assigned to the organization member when they accept.
   </Callout>

If you enable [Multiple Custom Domains](/docs/customize/custom-domains/multiple-custom-domains), you have the option to select **Domain** under the **Send Invite(s)** section to select the notification domain for your tenant.

## Management API

<Warning>
  If you are exposing the invitation feature from an admin dashboard you have customized for your application, use a [confidential application](/docs/get-started/applications/confidential-and-public-applications) to validate the authenticated user belongs to an organization before inviting new members, or you can restrict users from inviting new members unless they are assigned a specific role.
</Warning>

To invite members via the Management API:
Make a `POST` call to the Create Organization Invitations endpoint. Be sure to replace `ORG_ID`, `MGMT_API_ACCESS_TOKEN`, `NAME_OF_USER`, `EMAIL_ADDRESS`, `CLIENT_ID`, `CONNECTION_ID`, `EXP_TIME`, `ROLE_ID`, and `SEND_INVITATION_EMAIL_OPTION` placeholder values with your organization ID, Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, name of invited user, email address of invited user, <Tooltip href="/docs/glossary?term=client+ID">client ID</Tooltip>, connection ID, expiration time, and role IDs, respectively.

```json lines theme={null}
{
  "method": "POST",
  "url": "https://{yourDomain}/api/v2/organizations/ORG_ID/invitations",
"headers": [
  { "name": "Content-Type", "value": "application/json" },
  { "name": "Authorization", "value": "Bearer MGMT_API_ACCESS_TOKEN" },
  { "name": "Cache-Control", "value": "no-cache" }
  ],
  "postData": {
  "mimeType": "application/json",
  "text" : "{ \"inviter\": { \"name\": \"NAME_OF_USER\"}, \"invitee\": { \"email\": \"EMAIL_ADDRESS\" }, \"client_id\": \"CLIENT_ID\", \"connection_id\": \"CONNECTION_ID\", \"ttl_sec\": \"EXP_TIME\", \"roles\": [ \"ROLE_ID\", \"ROLE_ID\", \"ROLE_ID\" ], \"send_invitation_email\": \"SEND_EMAIL_INVITATION_OPTION\" }"
  }
}
```

If you enable [Multiple Custom Domains](/docs/customize/custom-domains/multiple-custom-domains), you need to include the `auth0-custom-domain` HTTP header. To learn more, review [Multiple Custom Domains](/docs/customize/custom-domains/multiple-custom-domains#customize-email-handling-using-the-management-api).

<Callout icon="file-lines">
  **Find Your Auth0 Domain**

  If your Auth0 domain is your tenant name, your regional subdomain (unless your tenant is in the US region and was created before June 2020), plus `.auth0.com`. For example, if your tenant name were `travel0`, your Auth0 domain name would be `travel0.us.auth0.com`. (If your tenant were in the US and created before June 2020, then your domain name would be `https://travel0.auth0.com`.)

  If you are using custom domains, this should be your custom domain name.
</Callout>

| Value                          | Description                                                                                                                                                                                           |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ORG_ID`                       | ID of the organization for which you want to assign membership.                                                                                                                                       |
| `MGMT_API_ACCESS_TOKEN`        | [Access Token for the Management API](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the scope `create:organization_invitations`.                                               |
| `NAME_OF_USER`                 | Name of the user to whom you want to send the invitation. Maximum of 300 characters.                                                                                                                  |
| `EMAIL_ADDRESS`                | Email address to which the invitation should be sent.                                                                                                                                                 |
| `CLIENT_ID`                    | ID of the application to which the invited user should authenticate.                                                                                                                                  |
| `CONNECTION_ID`                | ID of the connection through which the invited member should authenticate.                                                                                                                            |
| `EXP_TIME`                     | Number of seconds before the invitation expires. If unspecified or set to 0, defaults to 604800 seconds (7 days). Maximum of 2592000 seconds (30 days).                                               |
| `ROLE_ID`                      | ID of the role(s) you want to assign to the invited user for the specified organization. Maximum of 50 roles per member.                                                                              |
| `SEND_INVITATION_EMAIL_OPTION` | Indicates whether Auth0 should send the email. Values are `true` or `false`. When set to `false`, Auth0 will generate an invitation URL that you can deliver to users through your own email service. |

### Response status codes

Possible response status codes are as follows:

| Status code | Error code             | Message                                                                                                                                                                                               | Cause                                                                              |
| ----------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `200`       |                        | Invitation successfully created.                                                                                                                                                                      |                                                                                    |
| `400`       | `invalid_body`         | The specified client\_id does not exist.                                                                                                                                                              | The request payload is not valid.                                                  |
| `400`       | `invalid_body`         | The specified connection does not exist.                                                                                                                                                              | The request payload is not valid.                                                  |
| `400`       | `invalid_body`         | Passwordless connections are not supported.                                                                                                                                                           | The request payload is not valid.                                                  |
| `400`       | `invalid_body`         | A default login route is required to generate the invitation url. To learn more, see [Configure default login routes](/docs/authenticate/login/auth0-universal-login/configure-default-login-routes). | The request payload is not valid.                                                  |
| `400`       | `invalid_body`         | One or more of the specified roles do not exist: role1, role2'.                                                                                                                                       | The request payload is not valid.                                                  |
| `400`       | `invalid_body`         | Invalid request body. The message will vary depending on the cause.                                                                                                                                   | The request payload is not valid.                                                  |
| `400`       | `invalid_query_string` | Invalid request query string. The message will vary depending on the cause.                                                                                                                           | The query string is not valid.                                                     |
| `401`       |                        | Invalid token.                                                                                                                                                                                        |                                                                                    |
| `401`       |                        | Invalid signature received for JSON Web Token validation.                                                                                                                                             |                                                                                    |
| `401`       |                        | Client is not global.                                                                                                                                                                                 |                                                                                    |
| `403`       | `insufficient_scope`   | Insufficient scope; expected any of: `create:organization_invitations`.                                                                                                                               | Tried to read/write a field that is not allowed with provided bearer token scopes. |
| `404`       |                        | No organization found by that id.                                                                                                                                                                     |                                                                                    |
| `429`       |                        | Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.                                                                                                  |                                                                                    |


# Use Organization Names in Authentication API
Source: https://auth0.com/docs/manage-users/organizations/configure-organizations/use-org-name-authentication-api

Setup, security considerations, and best practices for using organization names in the Authentication API.

By default, the [Authentication API](https://auth0.com/docs/api/authentication) uses organization IDs to identify specific organizations. If needed, you can configure your tenant to also use organization names as an identifier. However, there are usability and security implications to consider before enabling this feature. To better understand the potential impact, review the [Considerations and recommendations](#considerations-and-recommendations) section.

## How it works

Configuring your tenant to support organization names in the Authentication API results in the following:

* The `organization` parameter in the [/authorize](https://auth0.com/docs/api/authentication#authorize-application) and [SAML](https://auth0.com/docs/api/authentication#saml) endpoints can accept both organization names and IDs.
* Access and <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip> automatically include both `org_name` and `org_id` claims.

<Callout icon="file-lines">
  - [Organizations](/docs/manage-users/organizations/configure-organizations/create-organizations) can be configured with two names: a required Name value that serves as a unique logical identifier and an optional, user-friendly Display Name. The `org_name` parameter only accepts the required Name value and does not support Display Name values.
  - This feature is managed at the tenant level. It cannot be individually enabled for specific organizations.
</Callout>

You can enable this feature through your <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>:

* **Auth0 Dashboard**: Select [Settings](/docs/get-started/tenant-settings) from the left-side menu and choose the **Advanced** tab. In the **Settings** section, enable the **Allow Organization Names in Authentication API** toggle.
* **Management API**: Use the `PATCH /api/v2/tenants/settings` endpoint to set `allow_organization_name_in_authentication_api` to `true`. For more information, review the [Management API](https://auth0.com/docs/api/management/v2) documentation.

### Example flow

The following example demonstrates an authorization code flow that uses organization names.

1. Call the `/authorize` endpoint passing your organization name for the `organization` parameter:

<AuthCodeBlock />

2. After obtaining the authorization code, call the `POST /oauth/token` endpoint to retrieve access and ID tokens:

<AuthCodeBlock />

3. The decoded tokens returned contain both the `org_id` and `org_name` claims:

```json lines theme={null}
{
    "sub": "google-oauth2|10...17",
    "aud": [
        "https://yourApp"
    ],
    "iat": 1686840988,
    "exp": 1686927388,
    "azp": "Suo...qTd",
    "scope": "openid profile",
    "org_id": "{yourOrganizationId}",
    "org_name": "{yourOrganizationName}"
}
```

## Considerations and recommendations

Before using organization names in the Authentication API, it is important to understand the primary differences between organization names and IDs.

Unlike organization IDs (which remain static), you can change the name of an organization at any time after initial creation. Additionally, you can reuse organization names within a single tenant as long as it's only assigned to **exactly one** organization at a time. In practice, this means you can change the name of one of your organizations and reuse its original name for another organization in your tenant. Organization names are only unique within a single tenant; the same name may be used for two or more organizations across multiple tenants.

In general, using organization IDs is recommended when validating tokens. However, if using organization names is more appropriate for your use case, consider the implications below when implementing the feature.

### Usability and security considerations

Consider the potential impacts below when using organization names to request and validate tokens:

* **Organization names can be reused**: Long-lived tokens do not expire when an organization changes its name, and the org\_name claims in those tokens retain their original value. If the original name is later reused by a different organization, such tokens may grant users unauthorized access to data and resources managed by the new organization.
* **Organization names are only unique within a single tenant**: If your API does not verify `iss` (issuer) claims in tokens, an organization with the same name in a different tenant could generate tokens that are incorrectly accepted by your API.
* **Organization names can be changed**: If you change the name of an organization, your applications must provide the new organization name in Authentication API requests. As tokens can be long-lived, the `org_name` claim in a token may no longer match the current organization name, which could prevent applications from granting access to the appropriate organization.

### Recommended best practices

Due to the possible security and usability impacts, using IDs instead of names to validate tokens is recommended when working with organizations. If you choose to use organization names, follow the best practices below for an optimal experience:

* Always validate the `iss` claim to ensure a token was issued by your Auth0 tenant.
* Avoid reusing organization names that previously existed in your tenant. To prevent reuse and ensure previously issued tokens cannot be used to access different organizations, maintain an accurate and up-to-date record of historic organization names.
* Avoid renaming organizations once they are in use unless absolutely necessary. If you choose to rename an organization, be aware that existing access and ID tokens do not automatically contain the new organization name. After renaming an organization, ensure you prompt users to log in again.


# Create Your First Organization
Source: https://auth0.com/docs/manage-users/organizations/create-first-organization

Learn how to create your first organization.

To begin using the [Organizations](/docs/manage-users/organizations/organizations-overview) feature, you must create and configure your organizations.

<Card title="Availability varies by Auth0 plan">
  Your Auth0 plan or custom agreement affects whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

## Create an organization

When you [create an organization](/docs/manage-users/organizations/configure-organizations/create-organizations), the settings you define are used to customize the login page and email templates that end-users see when they authenticate in the context of the organization.

When using Organizations out-of-the-box, these settings will override the settings for <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> pages. To learn more about further customizing the login page or email templates, read [Customize prompts and email templates](#customize-prompts-and-email-templates).

## Define organization behavior

You may be familiar with applications like Heroku that present different behaviors depending on whether a user logs in with a personal account or selects an organization associated with their business account. Auth0 allows you to define similar organization behavior at the application level.

For each application you create in Auth0, you can decide whether end-users should log in directly or be required to authenticate in the context of an organization. For applications that require users to log in via an organization, you can also specify what happens if one is not provided to the login flow.

You may also want to update your Application's **Allowed Callback URLs** and **Allowed Origins (CORs)** [application settings](/docs/get-started/applications/application-settings) to include Organization [placeholders for subdomains](/docs/get-started/applications/wildcards-for-subdomains).

## Customize prompts and email templates

When using Organizations with Universal Login out-of-the-box prompts, the branding settings you configure when you [create organizations](/docs/manage-users/organizations/configure-organizations/create-organizations) override the branding for Universal Login pages and email templates. If you would like to further modify the Universal Login pages and emails that the end-user receives, you can customize page and email templates.

### Page templates

<Callout icon="file-lines">
  To access page template customization, you must use custom domains, which is a feature of any paid pricing plan.
</Callout>

To modify Universal Login page, customize a page template using the [Liquid template language](https://shopify.github.io/liquid/) and template variables, then apply the template using the Universal Login Page Templates API. To learn more, read [Universal Login Page Templates](/docs/customize/login-pages/universal-login/customize-templates).

Because the same template is used for all pages, you can implement consistent login pages with minimum effort.

The simplest template you can write is:

```html lines theme={null}
<!DOCTYPE html>
<html>
  <head>
    {%- auth0:head -%}
  </head>
  <body>
    {%- auth0:widget -%}
  </body>
</html>
```

The following tags must be present in the template:

* `auth0:widget`: Contains the HTML that structures the widget displayed on every page type (e.g., Login, Reset Password).
* **`auth0:head`**: Contains tags required to render the widget.

To center the widget in the page, replace the `<body>` tag with `<body class="_widget-auto-layout">`.

### Email templates

To modify emails the end-user receives, customize an email template using the [Liquid template language](https://shopify.github.io/liquid/) and template variables. To learn more, read [Customize Email Templates](/docs/customize/email/email-templates).

The following email templates can be further customized for organizations:

* **Welcome**: Received by the end-user once they verify their email address or, if email verification is disabled, when they sign up (or log in for the first time).
* **Password Change**: Received by the end-user when they request a password change. Contains a link that redirects them to the Password Reset page.
* **Invite User**: Received by the end-user when they are invited to an organization. Contains a link that redirects them to your configured default login route. To learn more, read [Invite Organization Members](/docs/manage-users/organizations/configure-organizations/invite-members).

### Template variables

Page and email templates may access a set of context variables that you can use to impact how the template is rendered.

For lists of available variables, read [Universal Login Page Templates](/docs/customize/login-pages/universal-login/customize-templates) for page template variables and [Customize Email Templates](/docs/customize/email/email-templates) for common email template variables.

Additional variables are available to the page template when a user logs in through an organization:

* `organization.id`
* `organization.display_name`
* `organization.name`
* `organization.metadata`
* `organization.branding.logo_url`
* `organization.branding.colors.primary`
* `organization.branding.colors.page_background`

<Callout icon="file-lines">
  Organization parameters are exposed to an email template only when the associated email is triggered in the context of an organization. For example, the user invitation email is always triggered in the context of an organization, so organization parameters are always exposed to its template. However, welcome emails may or may not be triggered in the context of an organization, so organization parameters will not always be available to its template.
</Callout>

## Configure Organization domains

<Warning>
  Organization Domains for Discovery is currently in Early Access. By using this feature, you agree to the applicable Free Trial terms in [Okta’s Master Subscription Agreement](https://www.okta.com/legal). To learn more about release stages, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

During pre-login, Auth0 can detect a user’s Organizations by either the Organization name or the email domain which they enter. In order to associate an Organization with a domain, you can create Organization domains. Auth0 then automatically routes them to the correct Identity Provider (IdP).

<Note>
  Note: Users must still enter their full email address or Organization name during login. Auth0 uses that information to determine the associated Organization.
</Note>

### Add a domain to an Organization

Tenant administrators can add and manage domains in the Domains section of an Organization in the Auth0 Dashboard or through the Management API.

To add a domain in the Auth0 Dashboard:

1. Navigate to [Auth0 Dashboard > Organizations](https://manage.auth0.com/#/organizations).
2. Select the name of the Organization. Select **Domains**.
3. Choose **Add Domain**.
4. Enter the domain (for example, `travel0.com`)
5. Once verified, the domain will appear as Verified and will be used for pre-login organization discovery.

<Note>
  Only verified domains are used during domain discovery. Pending or unverified domains will not trigger routing.
</Note>

For details on how domain discovery affects login behavior, read [Login Flows for Organizations](https://auth0.com/docs/manage-users/organizations/login-flows-for-organizations).

## Configure organization membership

Each organization has its own associated members, which represent the users who can access your applications by logging in through the organization’s configured login page.

SaaS and B2B applications are usually provided to teams rather than to isolated individual users. In this context, a team could be an entire company, a small set of employees (for example, the marketing department), or even a transient group of users that are organized around a purpose (for example, a group of neighbors who have signed up to work with a charity and are competing as a team to raise the most money for a cause).

Organizations in Auth0 are flexible enough to support all of these use cases, but require some planning when building an application that supports teams. One of the first things to consider is how to manage team membership, which you can accomplish by:

* [Inviting users via email](/docs/manage-users/organizations/configure-organizations/invite-members)
* [Granting just-in-time membership](/docs/manage-users/organizations/configure-organizations/grant-just-in-time-membership) to users that log in via an enabled connection
* Directly managing membership via the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> or <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> by [assigning members](/docs/manage-users/organizations/configure-organizations/assign-members) or [removing members](/docs/manage-users/organizations/configure-organizations/remove-members)

Once membership is defined, you can [retrieve members of organizations](/docs/manage-users/organizations/configure-organizations/retrieve-members) or [retrieve a user's organization membership](/docs/manage-users/organizations/configure-organizations/retrieve-user-membership).

## Assign roles to members

Each organization member can be assigned one or more roles, which are applied when users log in through the organization. Specifically, you can [add roles to organization members](/docs/manage-users/organizations/configure-organizations/add-member-roles), [remove roles from organization members](/docs/manage-users/organizations/configure-organizations/remove-member-roles), or [retrieve member roles for an organization](/docs/manage-users/organizations/configure-organizations/retrieve-member-roles). You can use roles and their associated permissions to control access to [applications that you build](/docs/manage-users/organizations/custom-development). To learn more about roles, read [Role-base Access Control](/docs/manage-users/access-control/rbac).

## Learn more

* [Understand How Auth0 Organizations Work](/docs/manage-users/organizations/organizations-overview)
* [Custom Development with Organizations](/docs/manage-users/organizations/custom-development)
* [Work with Tokens and Organizations](/docs/manage-users/organizations/using-tokens)
* [Configure Organizations](/docs/manage-users/organizations/configure-organizations)


# Custom Development with Organizations
Source: https://auth0.com/docs/manage-users/organizations/custom-development

Learn to use Actions and SDKs with Auth0 organizations.

You can extend Auth0 capabilities using [organization](/docs/manage-users/organizations/organizations-overview) metadata and Actions, or use our APIs and SDKs to build organization administration dashboards for your users.

<Card title="Availability varies by Auth0 plan">
  Your Auth0 plan or custom agreement affects whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

## Extensibility

Organizations support our extensibility points, so you can define properties within organization metadata and expose that data to [Actions](/docs/customize/actions). This allows you to customize capabilities for individual customers or applications; for example, you can execute custom logic in Actions for certain customers based on their subscription plan by storing that information in organization metadata.

### Actions event object

The Action event object stores contextual information about the current authentication transaction, such as the user's IP address, application, or location.

If you change token content using the `event` object within an Action, your changes will be available in tokens after all Actions have finished running.

## SDKs

To allow members to self-manage their organizations, you can assign roles to members, and use our API and SDKs to build dashboards in your products. Administrators can configure <Tooltip href="/docs/glossary?term=Single+Sign-On">Single Sign-On</Tooltip> (SSO), invite users to organizations, assign members to organizations, assign roles to members, and so on.

Example tasks you may want to perform with organizations using the SDKs are outlined below.

<Callout icon="file-lines">
  The examples below reference the `org_id` claim available by default in ID and access tokens. However, you can configure your tenant to also support the use of organization names in the Authentication API. This results in tokens containing both the `org_id` and `org_name` claims. If present, validate the `org_name` claim in addition to `org_id` to ensure the received values correspond to a trusted entity.

  In general, using organization IDs is the preferred method for validating tokens. However, organization names can be used if they are more appropriate for your use case. To understand the potential implications of using organization names to validate tokens, review [Use Organization Names in Authentication API](/docs/manage-users/organizations/configure-organizations/use-org-name-authentication-api).
</Callout>

### I want users to log in to a specified organization

When defining a new client, pass the organization ID into an organization parameter. Then on callback, ensure that the organization returned in the <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> is the same one that was sent in the `/authorize` request by validating the `org_id` claim in the same way that other claims like `exp` and `nonce` are validated.

To learn more, read:

* [Add Login Using the Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/add-login-auth-code-flow)
* [Call Your API Using the Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/call-your-api-using-the-authorization-code-flow)
* [Add Login Using the Authorization Code Flow with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/add-login-using-the-authorization-code-flow-with-pkce)
* [Call Your API Using the Authorization Code Flow with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/call-your-api-using-the-authorization-code-flow-with-pkce)
* [Add Login Using the Implicit Flow with Form Post](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post/add-login-using-the-implicit-flow-with-form-post)
* [Call Your API Using the Hybrid Flow](/docs/get-started/authentication-and-authorization-flow/hybrid-flow/call-api-hybrid-flow)
* [Customize session inactivity timeout based on Organization](/docs/manage-users/sessions/manage-sessions-actions)

### From my application, I want to get the organization to which the authenticated user logged in

If the user was authenticated using an organization, the organization ID will appear in the `org_id` claim in the ID token. Using the Auth0 SPA SDK, this can be retrieved as follows:

`const { org_id } = await client.getIdTokenClaims();`

### From my API, I want to get the organization with which the access token was issued

If the user was authenticated using an organization and an <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> was specified, the <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> will be a <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> and will contain the `org_id` claim with the ID of the organization to which the user logged in.

This can be validated along with the other claims on the backend, as in the following example for Ruby:

```ruby lines theme={null}
class JsonWebToken
  def self.verify(token)
    decoded = JWT.decode(token, nil,
               true, # Verify the signature of this token
               algorithms: 'RS256',
               iss: 'https://YOUR_DOMAIN/',
               verify_iss: true,
               aud: Rails.application.secrets.auth0_api_audience,
               verify_aud: true) do |header|
      jwks_hash[header['kid']]
    end

    // Retrieve the organization ID value from the decoded token
    org = decoded[0]['org_id']
  end
end
```

<Callout icon="file-lines">
  **Find Your Auth0 Domain**

  If your Auth0 domain is your tenant name, your regional subdomain (unless your tenant is in the US region and was created before June 2020), plus `.auth0.com`. For example, if your tenant name were `travel0`, your Auth0 domain name would be `travel0.us.auth0.com`. (If your tenant were in the US and created before June 2020, then your domain name would be `https://travel0.auth0.com`.)

  If you are using custom domains, this should be your custom domain name.
</Callout>

## Learn more

* [Understand How Auth0 Organizations Work](/docs/manage-users/organizations/organizations-overview)
* [Create Your First Organization](/docs/manage-users/organizations/create-first-organization)
* [Work with Tokens and Organizations](/docs/manage-users/organizations/using-tokens)
* [Configure Organizations](/docs/manage-users/organizations/configure-organizations)
* [Auth0 Actions](/docs/customize/actions)


# Login Flows for Organizations
Source: https://auth0.com/docs/manage-users/organizations/login-flows-for-organizations

How to use Auth0 Login Flow with your Organization

[Auth0 Organizations](/docs/manage-users/organizations) allows leaders of B2B products or SaaS applications to build multi-tenant architectures, store identification tokens appropriately, and minimize end user login friction.

# Configure the login experience of your application

Your application can be configured in the **Login Experience** tab to support three user types:

1. Individuals
2. Business Users
3. Both

<Frame>
  <img alt="" />
</Frame>

Applications designed explicitly for consumers - for example, Netflix or Spotify - likely do not need Organization management. By choosing **Individuals**, users log in to the application directly and Organization context is not provided.

B2B or SaaS applications - for example, Slack or Jira - are better-served by **Business Users,** so end users can only access your application in the context of an Auth0 Organization. Users in multiple Organizations are directed to the Organization Picker after the login flow, which displays the first 20 organizations they joined.

<Frame>
  <img alt="" />
</Frame>

Choose **Both** if your end user may maintain both a personal and business account with your application. For example, Github often stores both personal and professional code repositories.

You can configure your application's user type through the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> (as described above) or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. Specifically, use the `organization_usage` parameter of the [Update a client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) endpoint to set the appropriate type of user. For more information on both methods, review [Define Organization Behavior](/docs/manage-users/organizations/configure-organizations/define-organization-behavior).

# Configure the Login Flow for your Application

After selecting **Business Users** or **Both**, you can further customize the experience that your users have when logging into your application. Most organizations should choose **Prompt for Credentials**, then enable [Identifier First Authentication](/docs/authenticate/login/auth0-universal-login/identifier-first). If you already know the Organization with which a user is attempting to log in, the **No Prompt** option along with [Custom Development with Organizations](/docs/manage-users/organizations/custom-development) allows your app to maintain a branded and customized login flow.

<Frame>
  <img alt="" />
</Frame>

Administrators can further curate the end user experience by enabling the **Prompt for Organization** toggle, which requires users to identify the Organization they’re logging into  by either the Organization Name or Organization Email.

<Callout icon="file-lines">
  **Note**: Even when selecting Prompt for Credentials, you can still direct users to [log in with a specific organization’s login prompt](/docs/manage-users/organizations/custom-development#i-want-users-to-log-in-to-a-specified-organization) as needed.
</Callout>

You can configure the login flow for your application through the Auth0 Dashboard (as described above) or the Management API. Specifically, use the `organization_require_behavior` parameter of the [Update a client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) endpoint to set the appropriate flow. For more information on both methods, review [Define Organization Behavior](/docs/manage-users/organizations/configure-organizations/define-organization-behavior).

## **Identifier First Authentication with prompt for credentials**

If your enterprise application uses [Enterprise Federation](/docs/authenticate/enterprise-connections), you can activate [Identifier First Authentication with Home Realm Discovery](/docs/authenticate/login/auth0-universal-login/identifier-first) in its Authentication Profile. Once enabled, Home Realm Discovery detects email addresses from a known domain and automatically sends them to the proper Workforce login.

<Frame>
  <img alt="" />
</Frame>

In this flow, exactly one Auth0 [Database Connection](/docs/authenticate/database-connections/custom-db) can be used as a fallback when a user’s email domain does not match the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> (IdP) domain of any enterprise connections. Users are shown your application’s login prompt instead of an organization’s login prompt, and [Connections that are enabled for the Application](/docs/get-started/applications/update-application-connections) are visible to the user.

After a user provides an email address, Auth0 matches it with Enterprise Connections enabled for this application **and** all Enterprise Connections enabled for Organizations. If a match is found, the user is directed to authenticate with the associated IdP. If no match is found, a password field is displayed.

## **Identifier First Authentication with prompt for Organization**

<Frame>
  <img alt="" />
</Frame>

Auth0 also supports Organization Domain Discovery, which can optionally be used to detect the user’s Organization before Identifier First Authentication runs. Together, these features streamline enterprise login flows while maintaining clarity and control across multi-organization environments.

When a user begins authentication, Auth0 first determines the Organization (if applicable) and then identifies the correct Identity Provider (IdP) or connection for authentication.

### **User input**

The user begins by entering either:

* Their email address (for example, `alice@rockymountainadventures.com`)
* Their organization name (for example, `Rocky Mountain High Adventures`)

### **Organization Domain Discovery (optional)**

If a tenant has configured verified Organization domains and no `organization` parameter is provided, Auth0 attempts to determine the user’s organization automatically:

* If exactly one Organization matches, Auth0 automatically selects it and continues the Identifier First Authentication flow in that Organization’s context.
* If multiple Organizations share the same domain or name (for example, both AdventureZ and Granite Outpost each configured `travelco.com`), Auth0 displays an Organization selector so the user can choose. Once chosen, Auth0 continues the Identifier First Authentication flow.
* Only verified domains are used for discovery; pending domains are ignored.
* If no match is found, Auth0 proceeds with standard Identifier First Authentication.

If the application’s **Login Experience > Type of Users** setting is configured as:

* **Both**: The prompt screen will include both the Organization Prompt and an option to Continue with Personal Account.
* **Business Users**: The option to continue with a personal account will not be displayed, and the user must log in with an Organization.

In both cases, Organization Domain Discovery attempts to determine whether the user belongs to a specific organization or should continue with a personal account if permitted before moving into Identifier First Authentication.

## **Identifier First Authentication**

The goal of Identifier First Authentication is to determine which connection or Identity Provider (IdP) to route the user.

Once the organization (if any) is determined, Auth0 applies Identifier First Authentication with Home Realm Discovery:

* If a `connection` parameter is provided, Auth0 uses it to route the user to that specific connection.
* Otherwise, Auth0 examines all Enterprise Connections enabled for both the application and the organization (if applicable).

If a matching IdP is found based on the user’s email domain, Auth0 redirects the user to that IdP for authentication.

If no match is found, or if the user’s email domain does not correspond to any enabled IdP, Auth0 falls back to the Auth0 Database Connection (if one is enabled for the application). In this fallback state, users see your application’s login prompt instead of an organization’s login prompt, and all connections enabled for the application.

<Callout icon="file-lines">
  There are use cases - such as multiple database configurations assigned to different Organizations - in which Auth0 cannot determine which IdP an user’s email is associated with. In these cases, select Prompt for Organization as your login initiation prompt or send the `organization` parameter to Auth0.
</Callout>

You can use the Management API to configure Identifier First Authentication. Specifically, use the `identifier_first` parameter of the [Update prompts settings](https://auth0.com/docs/api/management/v2/prompts/patch-prompts) endpoint.

## Auto-Membership

Instead of inviting or assigning users to an Organization directly, you may want to allow any user that is able to authenticate with a federated IdP to be granted access to an Organization. For these scenarios, Auth0 recommends the [Auto-Membership](/docs/manage-users/organizations/configure-organizations/grant-just-in-time-membership) setting.

Auto-membership is typically triggered by [directing a user to log in using the Organization’s login prompt](/docs/manage-users/organizations/custom-development), which can pass the connection and organization parameters on the user’s behalf. If a user’s desired organization cannot be determined prior to login, the Prompt for Credentials flow grants membership to the sole organization with auto-membership configured.

However, there may be scenarios in which you cannot determine a user’s desired organization prior to sending them to log in. In this case, you can use the aforementioned Prompt for Credentials flow but note that the user will only be granted membership in the organization if one and only one organization has this connection set as an enabled connection for the organization with auto-membership activated.

You can use the Management API to configure auto-membership. Specifically, use the `assign_membership_on_login` parameter of the [Modify an organization's connection](https://auth0.com/docs/api/management/v2/organizations/patch-enabled-connections-by-connection-id) endpoint.


# Machine-to-Machine (M2M) Access for Organizations
Source: https://auth0.com/docs/manage-users/organizations/organizations-for-m2m-applications

Learn about machine-to-machine access for Organizations.

<Card title="Availability varies by Auth0 plan">
  This feature is available for B2B Professional, Enterprise, and Enterprise premium plans. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

The [Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow) is used by an application to obtain <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> for itself rather than for a user. This is useful in machine-to-machine use cases such as bots, CLIs, backend or daemon processes, or any application that consumes APIs on its own behalf. While end users are not involved, the Client Credentials Flow should still be scoped per organization to ensure that only allowed applications can access each organization’s data.

<Callout icon="file-lines">
  To scope each request to a given organization, include the corresponding `org_id` claim to machine-to-machine tokens. API servers must consider and enforce this claim when authorizing access to API resources and data. To learn more, read [Work with Tokens and Organizations](/docs/manage-users/organizations/using-tokens).
</Callout>

Machine-to-Machine Access for Organizations enables you to define the organizations that a given application can access for each API using the Client Credentials Flow. To learn more, read the following:

| **Read...**                                                                                                                                                | **To learn...**                                                                                    |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| [Configure Your Application For M2M Access](/docs/manage-users/organizations/organizations-for-m2m-applications/configure-your-application-for-m2m-access) | General application settings to control M2M access to Organizations for each API in your tenant.   |
| [Authorize M2M Access](/docs/manage-users/organizations/organizations-for-m2m-applications/authorize-m2m-access)                                           | How to grant an application access to one or more specific organizations.                          |
| [Revoke M2M Access](/docs/manage-users/organizations/organizations-for-m2m-applications/revoke-m2m-access)                                                 | How to revoke a grant for an application to access one or more specific organizations.             |
| [Audit M2M Access](/docs/manage-users/organizations/organizations-for-m2m-applications/audit-m2m-access)                                                   | How to check currently configured M2M access for each application and organization in your tenant. |

Let’s consider our fictitious [Travel0 company](/docs/manage-users/organizations/organizations-overview#sample-scenario) to show two relevant example use cases.

## Open up APIs to third-party applications

Using Auth0 Organizations and the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>, Travel0 offers a self-service portal where customers can create and manage their own organization. Travel0 wants to make it easy for customers to build bots to help end users find and purchase adventures. Therefore, as part of this portal, Travel0 allows customers to register their applications (e.g. the bots) to consume the Travel0 API on their own behalf using machine-to-machine access. In this use case, cross-organization access must be correctly controlled so that applications belonging to one organization can only access that organization’s data via the Travel0 API.

**Machine-to-Machine Access for Organizations allows you to configure Client Credentials access for each API by associating it with a specific organization**. In the following diagram, the applications of our example organization, org\_X, can only access the Travel0 API within the scope of org\_X. You can also configure access from a single application to several organizations in cases where aggregators are used. With M2M Access for Organizations, you control which applications can access a specific organization using machine-to-machine access on a per API basis.

<Frame>
  <img alt="" />
</Frame>

## Isolation of organizations for internal applications

Travel0 also has some internal processes and CLI tools that need to access the Travel0 API using the Client Credentials Flow. To apply a unified access control strategy on the API, Travel0 wants requests from its own applications to be scoped to a specific organization to ensure only the right data is accessed in each case.

<Frame>
  <img alt="" />
</Frame>

Machine-to-Machine Access to Organizations enables you to configure an application to access any organization for each API in your tenant using the Client Credentials Flow.


# Audit M2M Access
Source: https://auth0.com/docs/manage-users/organizations/organizations-for-m2m-applications/audit-m2m-access

Learn how to audit M2M access for an application.

Machine-to-Machine Access to Organizations can be granted by directly associating a client grant to an organization or allowing access to any organization in the client grant settings. Both scenarios can be audited via the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>, where you can view or retrieve a list of client grants associated with an organization for an application. To learn more about how M2M access to Organizations permissions work, read [Configure Your Application for M2M Access](/docs/manage-users/organizations/organizations-for-m2m-applications/configure-your-application-for-m2m-access) and [Authorize M2M Access](/docs/manage-users/organizations/organizations-for-m2m-applications/authorize-m2m-access).

## Access granted via direct association

Use the [Auth0 Dashboard](https://manage.auth0.com/) and [Management API](https://auth0.com/docs/api/management/v2) to audit M2M access for client grants that are directly associated to an organization.

<Tabs>
  <Tab title="Auth0 Dashboard">
    To view the application client grants that have been authorized for a specific organization on the Auth0 Dashboard:

    1. Navigate to **Organizations** and choose the organization you wish to inspect.
    2. Select the **Machine-to-Machine Access** tab. You will get a paginated list of all the applications that can access an API for this organization via direct association.
    3. Choose an applicationto review the authorized APIs listed for that application.

    <Frame>
      <img alt="" />
    </Frame>
  </Tab>

  <Tab title="Management API">
    Client grants associated with an organization can be retrieved via the [Organization Client Grants](https://auth0.com/docs/api/management/v2/organizations/get-organization-client-grants) API endpoint:

    <AuthCodeBlock />

    Alternatively, if you want to retrieve information on applications that can access at least one of the API for an organization, you can use the `q` query parameter on the [Get Clients API endpoint](https://auth0.com/docs/api/management/v2/clients/get-clients) with the search term `client_grant.organization_id:{organization_id}`. Use the Lucene syntax, which is similar to the [User Search Query Syntax](/docs/manage-users/user-search/user-search-query-syntax).

    <AuthCodeBlock />
  </Tab>
</Tabs>

## Access granted to any organization

Use the [Auth0 Dashboard](https://manage.auth0.com/) and [Management API](https://auth0.com/docs/api/management/v2) to audit M2M access for applications that have access granted to any organization.

<Tabs>
  <Tab title="Auth0 Dashboard">
    1. Navigate to **Organizations**.
    2. Select the **Machine to Machine Access** tab. You will get a paginated list of all the applications that can access at least one of the API for an organization.
    3. Choose an application to review the authorized APIs listed for that application.

    <Frame>
      <img alt="" />
    </Frame>
  </Tab>

  <Tab title="Management API">
    Client grants with the `allow_any_organization` parameter can be retrieved via the [Get Client Grants](https://auth0.com/docs/api/management/v2/client-grants/get-client-grants) API endpoint:

    <AuthCodeBlock />

    Alternatively, if you want to retrieve information on applications that can access at least one of the APIs for any organization, you can use the `q` query parameter on the [Get Client Grants](https://auth0.com/docs/api/management/v2/client-grants/get-client-grants) API endpoint with the search term `client_grant.allow_any_organization:true`. Use the Lucene syntax, which is similar to the [User Search Query Syntax](/docs/manage-users/user-search/user-search-query-syntax).

    <AuthCodeBlock />
  </Tab>
</Tabs>

## Search applications based on organization access

<Callout icon="file-lines">
  Search results are eventually consistent.
</Callout>

The following table shows the search terms supported to query applications with the `q` parameter on the `/clients` endpoint:

| **Field**                                        | **Description**                                                                               |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `client_grant.organization_id:{organization_id}` | Use to search for applications that can access at least one of the APIs for an organization.  |
| `client_grant.allow_any_organization:true`       | Use to search for applications that can access at least one of the APIs for any organization. |

## Tenant logs

Machine-to-Machine Access for Organizations is also reflected in tenant logs. You can check the `organization` associated to the request in the corresponding `seccft` tenant log.

The following code sample is an example `seccft` tenant log with organization information:

```json lines theme={null}
{
  "date": "2024-10-24T19:06:17.460Z",
  "type": "seccft",
  "description": "Client Credentials for Access Token",
  "connection_id": "",
  "client_id": "qoQKtXuhdSibs1jUeXk3mmCwXoAafGnO",
  "client_name": "jwt.io (Test Application)",
  "ip": "130.41.219.72",
  "user_agent": "Other 0.0.0 / Other 0.0.0",
  "hostname": "david-test.test-aws-abundant-lobster-6004.auth0c.com",
  "user_id": "",
  "user_name": "",
  "organization_id": "org_mPdwToiiHHOtz0SH",
  "organization_name": "cc_test",
  "audience": "https://jwt.io.com",
  "scope": "read:data",
  "$event_schema": {
    "version": "1.0.0"
  },
  "log_id": "90020241024190617517817000000000000001223372036854775862",
  "tenant_name": "david-test",
  "_id": "90020241024190617517817000000000000001223372036854775862",
  "isMobile": false,
  "id": "90020241024190617517817000000000000001223372036854775862"
}
```


# Authorize M2M Access
Source: https://auth0.com/docs/manage-users/organizations/organizations-for-m2m-applications/authorize-m2m-access

Learn how to authorize M2M access for your application.

To authorize Machine-to-Machine access for an application, you must enable it to use an organization for a specific API. To do so, you must associate the application's client grant to the corresponding API with the organization. Once associated, the application can use the organization when requesting tokens for the API and scopes defined in the client grant. You will need to define this association for each API your application needs to access for the organization.

You can authorize M2M access for an application using the [Auth0 Dashboard](https://manage.auth0.com/) or [Management API](https://auth0.com/docs/api/management/v2).

<Tabs>
  <Tab title="Auth0 Dashboard">
    To associate an application’s client grant to an organization via the Auth0 Dashboard:

    1. Navigate to **Organizations** and choose the organization you want to associate with.
    2. Select the **Machine-to-Machine Access** tab.
    3. Click **Add Access.**
    4. Click the application you want to associate with the organization.
    5. Select an API.
    6. Click **Save.**

    <Frame>
      <img alt="" />
    </Frame>
  </Tab>

  <Tab title="Management API">
    Application client grants can be associated with an organization via the [Associate client grant to organization](https://auth0.com/docs/api/management/v2/organizations/create-organization-client-grants) endpoint:

    <AuthCodeBlock />
  </Tab>
</Tabs>


# Configure Your Application For M2M Access
Source: https://auth0.com/docs/manage-users/organizations/organizations-for-m2m-applications/configure-your-application-for-m2m-access

Learn how to configure your application for M2M access using the Auth0 Dashboard and Management API.

After creating the application, configure it for machine-to-machine access by following these steps:

1. [Define organization behavior](#define-organization-behavior) for each API you need to access.
2. In cases where the application should only access specific organizations i.e. not all of them, [Authorize M2M Access](/docs/manage-users/organizations/organizations-for-m2m-applications/authorize-m2m-access) for each API you need to access for those specific organizations.

## Define organization behavior

You can configure how your application uses Organizations during the Client Credentials Flow for each API, such as whether the application must use an organization or can access any organization or only explicitly associated ones.

The following table explains the fields for defining organization behavior for M2M access:

### Define organization behavior table

<table>
  <thead>
    <tr>
      <th><strong>Field</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>API Mapping</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Organization Support</td>

      <td>
        Determines how this application may use organizations when accessing via the Client Credentials Flow.

        <br />

        <br />

        Options include:

        <ul>
          <li><b>None:</b> The application <i>must not</i> use organizations. This is the default value.</li>
          <li><b>Optional:</b> The application <i>may decide</i> whether to use an organization.</li>
          <li><b>Required:</b> The application <i>must</i> use an organization.</li>
        </ul>
      </td>

      <td>
        Organization Support maps to <code>organization\_usage</code>.

        <br />

        <br />

        Options:

        <ul>
          <li><b>None</b> maps to <code>deny</code></li>
          <li><b>Optional</b> maps to <code>allow</code></li>
          <li><b>Required</b> maps to <code>required</code></li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>Allow machine-to-machine access to any organization</td>

      <td>
        Determines whether this application can access any organization or is limited to a set of explicitly associated organizations when using the Client Credentials Flow. By default, this behavior is not allowed.

        <br />

        <br />

        <b>Warning:</b> Enabling machine-to-machine access to any organization allows the application to access any organization without it being explicitly associated. It should only be enabled for trusted internal applications.
      </td>

      <td>
        Allow machine-to-machine access to any organization maps to <code>allow\_any\_organization</code>.

        <br />

        <br />

        Options:

        <ul>
          <li>Checked maps to <code>true</code></li>
          <li>Unchecked maps to <code>false</code></li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

### Define organization behavior for an application

To define organization behavior for an application, use the [Auth0 Dashboard](https://manage.auth0.com/) or [Management API](https://auth0.com/docs/api/management/v2).

<Tabs>
  <Tab title="Auth0 Dashboard">
    For a machine-to-machine application, define organization behavior via the Auth0 Dashboard:

    1. Navigate to **Auth0 Dashboard > Applications**, and select the application for which you want to configure Organizations.
    2. Switch to the **APIs** tab and expand the `client_grant` details for the API you wish to configure access to.
    3. Configure the appropriate settings as explained in the [Define organization behavior table](#define-organization-behavior-table).
    4. Select **Save.**

    Alternatively, if it is not a machine-to-machine application:

    1. Navigate to **Auth0 Dashboard > APIs**, and select the API for which you want to configure Organizations access.
    2. Switch to the **Machine To Machine Applications** tab. It shows all applications, not just Machine-to-Machine applications. Locate your application.
    3. To authorize access, click the toggle for your application. Then, click your application to expand the configuration details.
    4. Configure the appropriate settings as explained in the [Define organization behavior table](#define-organization-behavior-table).
    5. Select **Save**.
  </Tab>

  <Tab title="Management API">
    You can also define organization behavior for an application using the Management API. The `client_grant` object controls your application’s access to an API, where you must configure the `client_grant` for each API your application needs to access. To configure the `client_grant` for M2M access, use the [Create client grant](https://auth0.com/docs/api/management/v2/client-grants/post-client-grants) or [Update client grant](https://auth0.com/docs/api/management/v2/client-grants/patch-client-grants-by-id) endpoints and the [Define organization behavior table](#define-organization-behavior-table) to update the appropriate settings.

    The following code sample creates a `client_grant` object with M2M access:

    <AuthCodeBlock />

    The following code sample updates a `client_grant` object with M2M access:

    <AuthCodeBlock />
  </Tab>
</Tabs>

## Set default organization

Some clients do not support non-standard fields in the [Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow). Therefore, they cannot send the required `organization` parameter to the `/oauth/token` endpoint. For these clients, you can set a default organization that is automatically applied to any Client Credentials request from the application when `none` is specified and organization support is `required` by the API.

<Callout icon="file-lines">
  Default organization is applied when `organization_usage=require` for the API (i.e. target audience).
</Callout>

The following table explains the fields for setting a default organization for machine-to-machine access:

### Set default organization table

<table>
  <thead>
    <tr>
      <th><strong>Field</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>API Mapping</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Default Organization for Machine-to-Machine Access</td>
      <td>Defines which organization to apply to Client Credentials requests that do not contain an organization</td>

      <td>
        Default Organization for Machine-to-Machine Access maps to the default\_organization object with the following properties:

        <ul>
          <li><code>organization\_id</code>: The ID of the organization to use</li>

          <li>
            <code>flows</code>: The authentication flow to use for the default organization.

            <br />

            <br />

            This setting is hidden in the UI and defaults to <code>\["client\_credentials"]</code>
          </li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

### Set default organization for an application

To set the default organization for an application, use the [Auth0 Dashboard](https://manage.auth0.com/) or [Management API](https://auth0.com/docs/api/management/v2).

<Tabs>
  <Tab title="Auth0 Dashboard">
    To enable a default organization for an application via the Auth0 Dashboard:

    1. Navigate to **Auth0 Dashboard > Applications**, and select the application for which you want to configure.
    2. Select the **Organizations** tab.
    3. Configure the appropriate settings as explained in the [Set default organization table](#set-default-organization-table).
    4. Click **Save.**

    <Frame>
      <img alt="" />
    </Frame>
  </Tab>

  <Tab title="Management API">
    You can configure the default organization for an application via the [Create a client](https://auth0.com/docs/api/management/v2/clients/post-clients) or [Update a client](https://auth0.com/docs/api/management/v2#!/Clients/patch_clients_by_id) endpoints. The only currently supported flow value is `client_credentials`.

    The following code sample updates a client with a default organization:

    <AuthCodeBlock />
  </Tab>
</Tabs>


# Revoke M2M Access
Source: https://auth0.com/docs/manage-users/organizations/organizations-for-m2m-applications/revoke-m2m-access

Learn how to revoke M2M access for an application.

To revoke M2M access, or remove access to an organization for your application, you must delete the association between its client grant(s) and the organization. Once this association is deleted, the application will no longer be permitted to use the organization when requesting new tokens for the API defined in the grant.

<Callout icon="file-lines">
  Revoking M2M access does not impact applications that have been granted access to any organization. To learn more, read [Define Organization Behavior](/docs/manage-users/organizations/organizations-for-m2m-applications/configure-your-application-for-m2m-access#define-organization-behavior).
</Callout>

<Tabs>
  <Tab title="Auth0 Dashboard">
    To remove the association between an application’s client grant and an organization via the [Auth0 Dashboard](https://manage.auth0.com/):

    1. Navigate to **Organizations** and choose the organization you wish to remove the association from.
    2. Select the **Machine-to-Machine Access** tab.
    3. Choose an application.
    4. Uncheck the box next to the APIs you wish to disassociate with the organization.
    5. Click **Save**.

    <Frame>
      <img alt="" />
    </Frame>
  </Tab>

  <Tab title="Management API">
    Associations between application client grants and organizations can be deleted via the [Disassociate client grants from organizations](https://auth0.com/docs/api/management/v2/organizations/delete-client-grants-by-grant-id) endpoint:

    ```bash lines theme={null}
    curl -X DELETE --location "https://{yourDomain}/api/v2/organizations/{ORG_id}/client-grants/{GRANT_ID}" \
      --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' ;
    ```
  </Tab>
</Tabs>


# Understand How Auth0 Organizations Work
Source: https://auth0.com/docs/manage-users/organizations/organizations-overview

Describes how Auth0 Organizations work, use cases, a sample scenario, planning, and limitations.

<Card title="Availability varies by Auth0 plan">
  Both your specific login implementation and your Auth0 plan or custom agreement affect whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

## Business cases

The Auth0 Organizations feature best supports business-to-business (B2B) implementations that have applications that end-users access.

<Frame>
  <img alt="B2B Organizations Business Case diagram" />
</Frame>

Common features of B2B implementations include:

* A product that is licensed to another business for use by their employees.
* Each organization requires its own federation and lightweight branding of the authentication experience.
* Access levels in the application can be represented by roles that are assigned to members of each organization.

Let’s explore some example business cases to highlight the ways in which Organizations can help.

## Sample scenario

Travel0 is a fictitious company that offers online travel services and has set up an Auth0 tenant. Travel0 has several applications, but we’ll focus on one application that could benefit from using Organizations.

**Travel0 Adventure Management**: An online application that allows its customers to create and market adventures, such as whitewater rafting, horseback riding, and zip lining. Each adventure is led by a guide who can use the application to sign up and manage scheduling. Guides may be either employed by the customer directly or freelance.

Customers of the application include:

* **Granite Outpost Rafting and Ziplines**: An established company that directly employs their large staff of guides, but sometimes also reaches out to freelance guides. They have their own <Tooltip href="/docs/glossary?term=IdP">IdP</Tooltip> that they use for their employees.
* **AdventureZ**: A large event company that directly employs a large number of guides, but also uses freelancers, though rarely. They also facilitate their direct employees’ ability to freelance for other companies who are in need of guides. They have their own IdP that they use for their employees.
* **Rocky Mountain High Adventures**: A new company just coming to market. The co-founders run most of their tours, and they reach out to freelancers for help during busy times. They don’t have an IT staff, and have neither the time nor inclination to set up their own identity provider (IdP). They have a contract with AdventureZ that allows any AdventureZ employees to freelance for them.

## Planning considerations

When setting up organizations, consider the following:

* **Login experience**: Will users be required to select an organization when logging in? Will users see the application’s default login page or a customized login page for their organization?
* **Connection model**: Will any users be shared between organizations? Do users need to be able to log in using an organization’s own internal identity provider?
* **Roles**: Does the application need users to have specific roles assigned within their organizations? Do you intend to build a custom dashboard that allows administrators to self-manage their organizations using assigned roles?

### Login experience

First, you must decide what the user should experience when they log in to an organization. You can choose to send the end-user directly to a specific Organization’s login prompt in Auth0, or you can send them to a prompt in which they can enter the name of the Organization with which they want to log in.

Additionally, you must choose whether to use the default <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> page that is configured for your application or to customize a login page specific to each organization using page templates. To learn more, see [Create Your First Organization](/docs/manage-users/organizations/create-first-organization).

### Connection model

Each organization will usually map directly to one of your business customers or partners, but users can be members of multiple organizations. Understanding how users map to customer organizations will help you determine how to model your organizations and connections. There are two user scenarios:

* **Users are isolated to an organization**: Every user is a member of exactly one organization. Either users will never need to be part of multiple organizations, or it would make more sense for users to create a separate identity for each organization.
* **Users are shared between organizations**: Any user may belong to multiple organizations and should be able to use the same identity to navigate between organizations.

Using our Travel0 Adventure Management example, let’s assume the following users:

* **Jonno**: A guide who is directly employed by Rocky Mountain High Adventures and who should be able to log in to only Rocky Mountain’s organization.
  Because Rocky Mountain does not have its own IdP, Jonno’s credentials are stored in the Travel0 database connection and Jonno is assigned membership to the Rocky Mountain organization.
* **Hiroko**: A guide who is directly employed by Granite Outpost Rafting and Ziplines and who should be able to log in to only Granite Outpost’s organization.
  Because Granite Outpost has its own IdP, Hiroko’s credentials may be stored in either the Travel0 database connection or an enterprise connection that Granite Outpost has set up to represent their IdP, and then Hiroko must also be assigned membership in Granite Outpost’s organization. If using Granite Outpost’s IdP, then the enterprise connection must also be enabled for the organization.
* **Emilio**: A guide who freelances for both Rocky Mountain High Adventures and Granite Outpost Rafting and Ziplines and should be able to log in to both organizations.
  If we want Emilio to be able to use the same credentials for both organizations, then Emilio’s credentials should be stored in the Travel0 database connection, and Emilio should be assigned membership in both Rocky Mountain and Granite Outpost organizations.
  Otherwise, Emilio will need to set up one set of credentials in the Travel0 database connection for Rocky Mountain High Adventures and be assigned membership in the Rocky Mountain High organization, then set up another set of credentials in either the Travel0 database connection or Granite Outpost’s enterprise connection and be assigned membership in the Granite Outpost organization. Finally, if using Granite Outpost’s IdP, the configured enterprise connection must be enabled for the Granite Outpost organization.
* **Sumana**: A guide who is directly employed by AdventureZ, but sometimes freelances for Rocky Mountain High Adventures under the contract Rocky Mountain has with AdventureZ. AdventureZ and Rocky Mountain have rating systems for their guides, and Sumana’s ratings need to carry over from AdventureZ to Rocky Mountain and be combined between organizations.
  Either Sumana’s credentials should be stored in the Travel0 database connection and membership should be assigned for both the Rocky Mountain and AdventureZ organizations, or if AdventureZ wants to share their IdP, then Sumana’s credentials should be stored in an enterprise connection that AdventureZ has set up to represent their IdP and the configured enterprise connection must be enabled for both the Rocky Mountain and AdventureZ organizations.
  If Sumana is also invited to freelance for Granite Outpost Rafting and Ziplines, then her credentials could be stored in the Travel0 database connection or she could be added to Granite Outpost’s IdP, and membership should be assigned to the Granite Outpost organization.

Once you have determined how many organizations you will have and what your connection model should look like, you can set up [database](/docs/authenticate/database-connections), [social](/docs/authenticate/identity-providers/social-identity-providers), or [enterprise](/docs/authenticate/identity-providers/enterprise-identity-providers) connections; [create organizations](/docs/manage-users/organizations/configure-organizations/create-organizations); and [configure organization membership](/docs/manage-users/organizations/configure-organizations/invite-members) or [enable organization connections](/docs/manage-users/organizations/configure-organizations/enable-connections).

### Roles

Members of organizations can be [assigned roles](/docs/manage-users/organizations/configure-organizations/add-member-roles). You can use these roles to define access control for your application. For example, if you built a dashboard for your users using our API and SDKs, you could assign an administrator role to certain members and allow them to self-manage their organizations through your dashboard.

<Warning>
  The Management API should be accessed using only a confidential client. Its use is subject to [Auth0 Management API rate limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/management-api-endpoint-rate-limits).
</Warning>

## Limitations

The Auth0 Organizations feature has the following limitations:

* Your Auth0 subscription plan affects the availability of this feature. To learn more, read [Auth0 Pricing](https://auth0.com/pricing/).
* Supported only for Universal Login (not supported for Classic Login or Lock.js).
* Organizations-enabled applications are not compatible with the following grants and protocols: <Tooltip href="/docs/glossary?term=Resource+Owner">Resource Owner</Tooltip> Password, Device <Tooltip href="/docs/glossary?term=Authorization+Flow">Authorization Flow</Tooltip>, <Tooltip href="/docs/glossary?term=WS-Fed">WS-Fed</Tooltip> (Auth0 as IdP).
* Does not support:

  * Custom domains per organization (For example, using the sample scenario, if Rocky Mountain High Adventures and Granite Outpost Rafting and Ziplining could both use `login.travel0.com` as login domains, then Organizations would be useful. Alternatively, if Rocky Mountain High Adventures wanted to use `login.rockymountain.com` and Granite Outpost wanted to use `login.graniteoutpost.com`, then you would need to use multiple Auth0 tenants.
  * Integration with the Delegated Administration Extension.
  * Integration with the Authorization Extension.
  * Integration with third-party applications.

## Learn more

* [Create Your First Organization](/docs/manage-users/organizations/create-first-organization)
* [Custom Development with Organizations](/docs/manage-users/organizations/custom-development)
* [Work with Tokens and Organizations](/docs/manage-users/organizations/using-tokens)
* [Configure Organizations](/docs/manage-users/organizations/configure-organizations)
* [Entity Limit Policy](/docs/troubleshoot/customer-support/operational-policies/entity-limit-policy)


# Work with Tokens and Organizations
Source: https://auth0.com/docs/manage-users/organizations/using-tokens

Learn how tokens work with Auth0's Organizations feature and how to authenticate users belonging to an organization.

<Card title="Availability varies by Auth0 plan">
  Your Auth0 plan or custom agreement affects whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

Most identity (ID) tokens and <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> returned by Auth0 are <Tooltip href="/docs/glossary?term=JSON+Web+Tokens">JSON Web Tokens</Tooltip> (JWTs) containing a variety of claims, which are pieces of information asserted about a subject. For example, an [ID token](/docs/secure/tokens/id-tokens) (which is always a JWT) can contain a claim called `name` that asserts that the name of the user authenticating is "John Doe".

There are two types of JWT claims:

* **Registered**: Claims defined by the [JWT specification](https://tools.ietf.org/html/rfc7519) to ensure interoperability with third-party, or external, applications. [OpenID Connect (OIDC)](/docs/authenticate/protocols/openid-connect-protocol) standard claims are reserved claims.
* **Custom**: Claims that you define yourself. These claims can be non-registered, collision-resistant public claims or non-registered, non-public private claims subject to collision. Name these claims carefully, such as through [namespacing](/docs/secure/tokens/json-web-tokens/create-custom-claims), to avoid collision with reserved claims or other custom claims. It can be challenging to deal with two claims of the same name that contain differing information.

To learn more about claims, read [JSON Web Token Claims](/docs/secure/tokens/json-web-tokens/json-web-token-claims).

## Authenticate users through an organization

To authenticate a user through an organization, an `organization` parameter is added to a call to the `/authorize` endpoint. Examples of tokens returned when a user logs in through organizations are provided below.

<Callout icon="file-lines">
  By default, ID and access tokens only include organization IDs. However, you can configure your tenant to allow the use of organization names in the Authentication API. When configured, ID and access tokens contain both the `org_id` and `org_name` claims. To learn more, review [Use Organization Names in Authentication API](/docs/manage-users/organizations/configure-organizations/use-org-name-authentication-api).
</Callout>

### ID token

In the following example, note that `https://marketplace/roles` and `https://namespace.exampleco.com/` are custom claims that have been added to the token, while the other included claims are standard.

```json lines theme={null}
{
  "https://marketplace/roles": [
    "marketplace-administrator"
  ],
  "https://namespace.exampleco.com": "my custom claim",
  "nickname": "firstName.lastName",
  "name": "firstName.lastName@email.com",
  "picture": "https://s.gravatar.com/avatar/638",
  "updated_at": "2021-03-23T11:34:14.566z",
  "email": "username@exampleco.com",
  "email_verified": true,
  "sub": "auth0|602c0dcab993d10073daf680",
  "org_id": "org_9ybsU1dN2dKfDkBi"
}
```

### Access token

```json lines theme={null}
{
  "iss": "https://exampleco.auth0.com/",
  "sub": "auth0|602c0dcab993d10073daf680",
  "aud": [
    "https://example-api/",
    "https://exampleco.auth0.com/userinfo"  
  ],
  "iat": 1616499255,
  "exp": 1616585655,
  "azp": "ENDmmAJsbwI1hOG1KPJddQ8LHjV6kLkV",
  "scope": "openid profile email",
  "org_id": "org_9ybsU1dN2dKfDkBi",
  "permissions": [
    "delete:stuff",
    "read:stuff",
    "write:stuff"  
  ]
}
```

## Machine-to-Machine access to an organization

In machine-to-machine use cases, an `organization` parameter is added to the Client Credentials request to the `/oauth/token` endpoint so that an application can obtain an access token for itself rather than a user.

<Callout icon="file-lines">
  By default, ID and access tokens only include organization IDs. However, you can configure your tenant to allow the use of organization names in the Authentication API. When configured, ID and access tokens contain both the `org_id` and `org_name` claims. To learn more, read [Use Organization Names in the Authentication API](/docs/manage-users/organizations/configure-organizations/use-org-name-authentication-api).
</Callout>

The following code sample is an example access token returned in machine-to-machine use cases:

```json lines theme={null}
{
  "iss": "https://exampleco.auth0.com/",
  "sub": "CS2MNgcX1VZFCJaEzfKw2VPAAS0gzhqP@clients",
  "aud": "https://example-api",
  "iat": 1727782196,
  "exp": 1727868596,
  "scope": "scope1 scope2",
  "org_id": "org_vIK75NKFvaozQsFy",
  "org_name": "acme",
  "gty": "client-credentials",
  "azp": "CS2MNgcX1VZFCJaEzfKw2VPAAS0gzhqP"
}
```

## Validate tokens

When the `organization` parameter is added to a call to the `/authorize` endpoint or the `/oauth/token` endpoint, Auth0 SDKs automatically validate the `org_id` claim, which is returned as part of any generated tokens. However, for security purposes, additional validation should be performed when tokens are received.

<Callout icon="file-lines">
  If you have configured your tenant to allow the use of organization names in the Authentication API, ID and access tokens contain both the `org_id` and `org_name` claims. If present, validate the `org_name` claim in addition to `org_id` to ensure the received values correspond to a trusted entity.

  In general, using organization IDs is the preferred method for validating tokens. However, organization names can be used if they are more appropriate for your use case. To understand the potential implications of using organization names to validate tokens, review [Use Organization Names in Authentication API](/docs/manage-users/organizations/configure-organizations/use-org-name-authentication-api).
</Callout>

**For web applications:**

If no `organization` parameter was passed to the `/authorize` endpoint, but an `org_id` claim is present in the <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip>, then your application should validate the claim to ensure that the value received is expected or known and that it corresponds to an entity your application trusts, such as a paying customer. If the claim cannot be validated, then the application should deem the token invalid.

**For APIs:**

If an `org_id` claim is present in the access token, then your API should validate the claim to ensure that the value received is expected or known and that it corresponds to an entity your application trusts, such as a paying customer. If the claim cannot be validated, then the API should deem the token invalid.

In particular:

* The `iss` (issuer) claim should be checked to ensure the token was issued by Auth0.
* The `org_id` claim should be checked to ensure it is a value that is already known to the application. This could be validated against a known list of organization IDs, or perhaps checked in conjunction with the current request URL. For example, the subdomain may hint at which organization should be used when validating the ID Token.

Normally, validating only the issuer would be enough to ensure that the token was issued by Auth0. In the case of organizations, however, additional checks should be made to ensure that the organization within your Auth0 tenant is expected.

It is also very important that your API servers segment access to data and resources based on the `org_id`. This ensures that only information about a given organization can be accessed or modified when the `org_id` value corresponding to that organization is received in the access token.

## Learn more

* [Understand How Auth0 Organizations Work](/docs/manage-users/organizations/organizations-overview)
* [Create Your First Organization](/docs/manage-users/organizations/create-first-organization)
* [Custom Development with Organizations](/docs/manage-users/organizations/custom-development)
* [Configure Organizations](/docs/manage-users/organizations/configure-organizations)


# Sessions
Source: https://auth0.com/docs/manage-users/sessions

Describes what sessions are and how the are used in Auth0.

A session is a group of interactions between a user and an application during a given timeframe. A single session may consist of multiple activities (such as page views, events, social interactions, and e-commerce transactions) and can store this information temporarily while the user is connected.

With a standard Set-Cookie header implementation, a session ends when a user leaves a website or closes their browser. To prevent users from having to log in every time, applications can extend sessions by setting a maximum lifetime for the <Tooltip href="/docs/glossary?term=session+cookie">session cookie</Tooltip>. Sessions end when a user logs out or a session lifetime limit is reached.

To learn more, review [Auth0 Privacy and Cookie Policy](https://auth0.com/privacy).

## Session use cases

Auth0 maintains a login session for any user who authenticates through an application. When a user performs a new standard login, Auth0 resets the login session. Updating a password, email, or phone number also causes a user's Auth0 session to expire.

When you build an application requiring authentication, you can use sessions to determine whether a user is authenticated each time a request occurs. Depending on how your app has been built, different <Tooltip href="/docs/glossary?term=authorization+flows">authorization flows</Tooltip> are recommended to support a more secure experience for users.

For example, consider an OIDC-compliant (<Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect) website called storezero.io.

<Frame>
  <img alt="Example e-commerce website Storezero.io" />
</Frame>

Storezero.io does not require its users to log in to complete purchases. However, users must log in to view the My Account section of the site.

For the use cases listed below, consider a scenario where a user wants to review their previous orders prior to checking out. To do so, they navigate to the All Orders page of the My Account section and are prompted to log in.

### Login flows

Most types of applications (such as web apps, single-page apps, and native apps) should use the [Authorization Code Flow with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce) to facilitate login authentication. This flow involves exchanging an authorization code for tokens.

<Callout icon="file-lines">
  The Authorization Code Flow with PKCE replaces the prior use of implicit flow for single-page apps without a backend. New developments must use this flow to ensure optimal security. Migrating existing apps using implicit flow to the PKCE-enhanced authorization code flow is also highly recommended.
</Callout>

#### User logs in with username and password

In this example, a user manually logs in using their username and password:

1. Auth0's SDK creates a local session and redirects the user to the Auth0 authorization server (`/authorize` endpoint).
2. The authorization server creates a session, then redirects the user to the login and authorization prompt.
3. The user authenticates using their username and password.
4. The Auth0 authorization server updates the user’s previously-created session to indicate they are logged in.
5. Depending on the flow used, the authorization server returns the user to your application, along with either an ID token or an authorization code.
6. Your application exchanges the token or authorization code for an access token and completes the flow.

With this flow, two sessions are created:

* The **local session** (storezero.io), which indicates to the application whether a user is authenticated.
* The **<Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip> session** (storezero.auth0.com), which indicates to the server whether a user is authenticated. The server session can also optionally track details about the authentication.

  * For example, the authorization server can track if a user leveraged [multi-factor authentication (MFA)](/docs/secure/multi-factor-authentication). This information can then be used to determine whether a user should be prompted to log in or use MFA the next time they arrive at the authorization server.

#### User logs in with identity provider

In this example, the user opts to log in with Facebook instead of their username and password:

1. Auth0's SDK creates a local session and redirects the user to the Auth0 authorization server (`/authorize` endpoint).
2. The authorization server creates a session, then redirects the user to the login and authorization prompt.
3. Upon choosing to log in with Facebook, the authorization server redirects the user to Facebook.
4. Facebook creates a session and authenticates the user. Facebook then updates its session to indicate the user is logged in.
5. Facebook returns the user to the Auth0 authorization server. The authorization server then updates its session to indicate the user is logged in.
6. Depending on the flow used, the authorization server returns the user to your application, along with either an ID token or an authorization code.
7. Your application exchanges the token or authorization code for an access token and completes the flow.

In this scenario, three sessions are created: the **local session** (storezero.io), the **authorization server session** (storezero.auth0.com), and an **<Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> (IdP) session** (facebook.com).

The IdP session on Facebook's server authenticates the user and provides a seamless <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> experience. As there is a high probability that users are already logged in to Facebook, users are often authenticated without having to manually provide their Facebook credentials.

### Session management for SPAs

In the previous examples, a local session is created when the user initiates either login flow. This local session can keep users logged in and determine when they need to reauthenticate.

However, local sessions are not available for applications without backends, such as single-page apps (SPAs). Instead, these applications use a different approach known as [silent authentication](/docs/authenticate/login/configure-silent-authentication) to keep users logged in.

Silent authentication uses the session on the authorization server to determine when a user must reauthenticate. A hidden iframe redirects authentication requests to the authorization server along with the `prompt=none` parameter. This parameter prevents the server from prompting the user for input.

* If the session on the authorization server has not expired, the transaction continues seamlessly. The server sends an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> through WMRM (Web Message Response Mode), which leverages `postMessage`.
* If the session on the authorization has expired or the user logs out, the redirect in the iframe returns an error. The application must then direct the user to the authorization server for reauthentication.

## Learn more

* [Session Layers](/docs/manage-users/sessions/session-layers)
* [Session Lifetime Limits](/docs/manage-users/sessions/session-lifetime-limits)
* [Configure Session Lifetime Settings](/docs/manage-users/sessions/configure-session-lifetime-settings)
* [Cookies](/docs/manage-users/cookies)
* [SameSite Cookie Attribute Changes](/docs/manage-users/cookies/samesite-cookie-attribute-changes)
* [Authenticate Single-Page Apps With Cookies](/docs/manage-users/cookies/spa-authenticate-with-cookies)


# Use Cases Configure Keep Me Signed In using Sessions
Source: https://auth0.com/docs/manage-users/sessions/configure-keep-me-signed-in-sessions

Learn how to configure an ephemeral sessions in Auth0.

<Card title="Before you start">
  Ensure you have:

  * A [Custom Domain](/docs/customize/custom-domains) configured Auth0 tenant configured for your application

  * [Auth0 CLI](https://auth0.github.io/auth0-cli/auth0_actions.html) installed and authenticated.

  * A [post-login Action](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger)

  * An Auth0 tenant session using the [non-persistent](/docs/manage-users/sessions/session-lifecycle) sessions policy

  * (Optional) Configure session's Idle and absolute session timeout values
</Card>

The **Keep Me Signed In** experience provides users the option to stay logged-in on a trusted device.

<Frame>
  <img alt="Login image" />
</Frame>

* If the **Keep Me Signed In** checkbox is selected, it sets a persistent session which survives browser restarts.

* If the **Keep Me Signed In** checkbox is not selected, it sets a non-persistent session which expires when the browser closes.

Using [non-persistent (ephemeral) sessions](/docs/manage-users/sessions/session-lifecycle) with [Actions](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger), the server securely handles this logic without exposing refresh tokens to the frontend.

Using Custom Prompts, Auth0 CLI, and ephemeral sessions via Actions, you can implement a secure and modern "Keep Me Signed In" flow with no refresh tokens, no client-side session hacks, and full backend control.

This solution is ideal for customers prioritizing:

* Zero-trust browser session handling

* Minimal session persistence

* Trusted device overrides

## 1. Configure a Universal Login page and Add a custom prompt

To gather the user’s **Keep Me Signed In** preference, you need to customize [Universal Login](/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts) by configuring a page template and adding a custom prompt using Auth0 CLI.

### Optional: Enable the Universal Login page template

<Callout icon="file-lines">
  This step is only required if your tenant does not have a Universal Login template configured.
</Callout>

Use the following command to create or update the page template:

```bash lines theme={null}
auth0 universal-login templates update
```

The customization editor opens the login page template. You can use any HTML structure that fits your brand.

Here is a minimal example template with a background and wrapped widget:

```html lines theme={null}
<!DOCTYPE html>
<html lang="{{locale}}">
  <head>
    {%- auth0:head -%}
    <style>
      body {
        background-image: url("https://images.unsplash.com/photo-1643916861364-02e63ce3e52f");
        background-size: cover;
        background-position: center;
      }
      .prompt-wrapper {
        display: flex;
        align-items: center;
        justify-content: center;
        height: 100%;
        background-color: rgba(0, 0, 0, 0.3);
      }
    </style>
    <title>{{ prompt.screen.texts.pageTitle }}</title>
  </head>
  <body class="_widget-auto-layout">
    {% if prompt.name == "login" or prompt.name == "signup" %}
      <div class="prompt-wrapper">
        {%- auth0:widget -%}
      </div>
    {% else %}
      {%- auth0:widget -%}
    {% endif %}
  </body>
</html>
```

Save and close the editor, the Auth0 CLI prompts you to confirm:

```bash lines theme={null}
Do you want to save the template? Yes

▸ Successfully updated the template for the New Universal Login Experience!
```

## 2. Add a Keep Me Signed In checkbox using Auth0 CLI

To add a checkbox into the Universal Login screen, follow these steps:

### Launch the customization editor

1. Open the customization editor for the login-id or login prompt  depending on your tenant configuration:

```bash lines theme={null}
auth0 universal-login customize -p login-id
```

2. Select **standard** for rendering mode

```bash lines theme={null}
Rendering Mode: standard
```

The customization editor launches at a local address:

```bash lines theme={null}
http://localhost:52649
```

<Callout icon="file-lines">
  If you are unsure whether your tenant uses `login` or `login-id`, refer to Auth0’s [prompt customization](/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts).
</Callout>

### Configure the checkbox

Open the **Partials** option in the customization editor:

1. Set **Prompt** to: `login-id` (or `login`)

2. Set **Screen** to: `login-id` (or `login`)

3. Set **Partial** to: `form-footer-end`

<Frame>
  <img alt="Auth0 CLI partials" />
</Frame>

Add the following HTML snippet:

```html lines theme={null}
<div class="ulp-field">
  <input type="checkbox" name="ulp-remember-me" id="remember-me">
  <label for="remember-me">Stay signed in on this device?</label>
</div>
```

This renders the checkbox underneath the login form.

### Deploy your changes

Select **Deploy Changes** in the top-right corner to save and apply the customization.

## Checkpoint

Log in using Universal Login.
The login screen includes a **Keep Me Signed** In checkbox.

<Frame>
  <img alt="Login image" />
</Frame>

## 3. Create a Post-Login Action using Auth0 CLI

Create a new file called `set-session-persistence.js` for use with Auth0 CLI and add the following code:

```javascript lines theme={null}
exports.onExecutePostLogin = async (event, api) => {

  // Apply the change only when the parameter is available
  if (event.request.body['ulp-remember-me']) {
    api.session.setCookieMode('persistent');
  } 
};
```

Use Auth0 CLI to create or update your post-login Action using the `set-session-persistence.js` file:

```bash lines theme={null}
auth0 actions create --name kmsi --trigger post-login --code "$(cat set-session-persistence.js)"
```

Auth0 CLI returns the Action Id:

```bash lines theme={null}
ID             f54c4aae-431f-4290-a7e0-cfc6a3f28386
NAME           kmsi
TYPE           post-login
STATUS         pending
DEPLOYED       ✗
LAST DEPLOYED
LAST UPDATED   0 seconds ago
CREATED        0 seconds ago
CODE           exports.onExecutePostLogin = async (event, api) => {
                   if (event.request.body['ulp-remember-me']) {
                     api.session.setCookieMode("persistent");
                   } else {
                     api.session.setCookieMode("non-persistent");
                   }
                 };
```

Deploy your Action using its `id`:

```bash lines theme={null}
auth0 actions deploy <id>
```

Navigate to the [Auth0 Dashboard > Actions > Triggers > Post-Login](https://manage.auth0.com/#/actions/triggers/post-login) to add the new action to the current flow and select **Apply**.

<Frame>
  <img alt="Dashboard Actions Triggers Post Login" />
</Frame>

### Optional - Set session duration for trusted devices

You can use `api.session.setExpiresAt()` or `api.session.setIdleExpiresAt()` methods to further customize session lifetimes.

```javascript lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  if (event.request.body['ulp-remember-me']) {
    api.session.setCookieMode("persistent");

    const now = Date.now();
    api.session.setExpiresAt(now + 7 * 24 * 60 * 60 * 1000); // 7 days
  } else {
    api.session.setCookieMode("nonpersistent");
  }
};
```

## 4. Test implementation

To verify the session behavior, you can:

Log in using Universal Login, and select the **Keep Me Signed** In checkbox.

* In the tenant logs, search for (event types `s` or `ssa`)

  * `cookie: { mode: "non-persistent" }`

  * `cookie: { mode: "persistent" }`

* Search for `event.session.cookie.mode` in your Actions


# Configure Session Lifetime
Source: https://auth0.com/docs/manage-users/sessions/configure-session-lifetime

Describes how to configure session lifetime for a tenant using the Auth0 Dashboard, the Management API and Actions.

To configure a session lifetime, you can use the Auth0 [Dashboard](/docs/get-started/auth0-overview/dashboard), [Management API](https://auth0.com/docs/api/management/v2), or a [Post-Login Action](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger).

## Auth0 Dashboard

To configure the session lifetime using Auth0 Dashboard:

1. Navigate to **Dashboard > Tenant Settings** and select the **Advanced** view.

2. Under **Session Expiration**, you can configure:

<table>
  <thead>
    <tr>
      <th><strong>Session Policy</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Idle Session Lifetime (Persistent)</strong></td>
      <td>Maximum time (in minutes) of inactivity before a persistent session expires.</td>
    </tr>

    <tr>
      <td><strong>Idle Session Lifetime (Non-Persistent)</strong></td>
      <td>Maximum time (in minutes) of inactivity before a non-persistent session expires.</td>
    </tr>

    <tr>
      <td><strong>Maximum Session Lifetime  (Persistent)</strong></td>
      <td>Maximum time (in minutes) a persistent session can exist, even if the user is active.</td>
    </tr>

    <tr>
      <td><strong>Maximum Session Lifetime (Non-Persistent)</strong></td>
      <td>Maximum time (in minutes) a non persistent session can exist, even if  the user is active.</td>
    </tr>
  </tbody>
</table>

<Frame>
  <img alt="Dashboard > Tenant > Settings > Advanced > Session Expiration" />
</Frame>

## Auth0 Management API

To configure the session lifetime using the Auth0 Management API:

<Callout icon="file-lines">
  Calls to the `/api/v2/tenants/settings` endpoint require a [Management API access token](/docs/secure/tokens/access-tokens) with the `update:tenant_settings` scope.
</Callout>

Make a `PATCH` request to the [/api/v2/tenants/settings](/docs/api/management/v2/tenants/patch-settings) endpoint:

```bash cURL theme={null}
curl --request PATCH \
  --url 'https://<your-domain>/api/v2/tenants/settings' \
  --header 'Authorization: Bearer MGMT_API_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{\
    "session_lifetime": SESSION_LIFETIME_VALUE,\
    "idle_session_lifetime": IDLE_SESSION_LIFETIME_VALUE,\
    "ephemeral_session_lifetime": EPHEMERAL_SESSION_LIFETIME_VALUE,\
    "idle_ephemeral_session_lifetime": EPHEMERAL_IDLE_SESSION_LIFETIME_VALUE\
  }'
```

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>session\_lifetime</code></td>
      <td>Maximum duration (in hours) for absolute timeout.</td>
    </tr>

    <tr>
      <td><code>idle\_session\_lifetime</code></td>
      <td>Maximum duration (in hours) before a session expires due to inactivity.</td>
    </tr>

    <tr>
      <td><code>ephemeral\_session\_lifetime</code></td>
      <td>Maximum duration (in hours) for absolute timeout.</td>
    </tr>

    <tr>
      <td><code>idle\_ephemeral\_session\_lifetime</code></td>
      <td>Maximum duration (in hours) before a session expires due to inactivity.</td>
    </tr>
  </tbody>
</table>

## Auth0 Post-Login Actions

You can configure session behavior dynamically using `api.session` methods with a [post-login Action](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger). This allows you to override default tenant session settings on a per-login basis, based on user or context-specific logic.

Use cases include:

* Shortening timeouts for high-risk logins

* Extending timeouts for trusted users or organizations

* Adjusting cookie persistence based on application type

The `api.session` methods available to configure session lifetimes are:

* `api.session.setExpiresAt`

* `api.session.setIdleExpiresAt`

* `api.session.setCookieMode`

<Callout icon="file-lines">
  The `api.session` methods only apply to the current session and must be called during the login transaction. These methods require that the event property `event.session.id` is available.
</Callout>

To learn more, read [Sessions with Actions](/docs/manage-users/sessions/manage-sessions-actions).


# Manage Multi-Site Sessions with Auth0 SDK
Source: https://auth0.com/docs/manage-users/sessions/manage-multi-site-sessions

Describes the workflow with the auth0-spa-js SDK to support multi-site session management.

## Short-lived sessions

This workflow shows how the auth0-spa-js SDK should be implemented to support multi-site session management. In this scenario, it is assumed that the tenant <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> Inactivity Timeout is set to 300 seconds, and the <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip> Expiration of each SPA application is set to 150 seconds. This is considered a "short-lived" session.

### SDK features

#### PKCE flow

For all methods of retrieving an ID Token or <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, the SDK manages all the intricacies of the Proof Key for Code Exchange workflow. No additional effort or configuration is needed for this to work.

#### Deep linking

To improve the user experience the SDK includes an `appState` parameter for the `loginWithRedirect()` method. Details about the current app are packaged as part of the request to the Auth server that will be returned upon successful authentication. Allowing a seamless continuation of the user journey.

In the Quickstart, the `PrivateRoute` component sets a state parameter of `targetUrl` and the `onRedirectCallback` function of `index.js` unpacks this value to redirect the user when authentication is complete.

#### Token storage

To keep the returned tokens stored in the safest manner possible all tokens are placed into a local cache. The ID and Access Tokens are stored as pairs with the <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> and scope values being used to retrieve the tokens as needed.

Additionally the cache tokens are removed once either the ID Token or Access Token expires so that if a token is in the cache it can be assumed to stil be valid.

#### Call APIs

The `getTokenSilently()` method is used to leverage the token cache first, and if none exists, will launch an invisible iframe to retrieve a new token. For this purpose all requests to APIs can use this method to construct the bearer token header without the need for additional logic to handle for expired tokens.

In the Quickstart, the `ExternalService` view makes a request to the express API using this feature.

#### Warn users to continue their sessions

In the case where a user has not taken any actions that would cause the Auth0 session to be updated, Auth0 recommends that you raise a warning to the user to choose to explicitly continue their session.

The intent of this approach allows the session to go inactive if the user is no longer present, but otherwise provides a means to trigger the silent token refresh so that the can continue their session without the need to be prompted again for credentials.

To learn more about inactivity timers and timeout modals, read [Application-specific logout URLs](/docs/manage-users/sessions/configure-session-lifetime-settings).

### Example workflow

1. Initial Authentication
2. Maintaining Auth0 Session
3. Seamless SSO
4. Prompting user to extend session
5. User explicitly logs out of application
6. User returns to initial app after logging out

#### Initial authentication

1. New tab is opened
2. Requests to login
3. User enters credentials
4. SSO cookie (with expiration) is set
5. Token exchange performed

<Frame>
  <img alt="Diagram of Initial Authentication flow" />
</Frame>

#### Maintain Auth0 session

1. User requests data from protected resource
2. `getTokenSilently()` called
3. Resource retrieved
4. User updates data from protected resource
5. `getTokenSilently()` called

   1. Iframe opened
   2. Token exchange performed
6. Resource is updated

<Frame>
  <img alt="Diagram of maintaining a session" />
</Frame>

#### Seamless SSO

1. User navigates to a private route
2. Check with `isAuthenticated()`
3. If false, `loginWithRedirect()`

<Frame>
  <img alt="Diagram of seamless SSO flow for sessions" />
</Frame>

#### Prompt user to extend session

1. At 240 seconds prompt user with keep session alive with modal that lasts 60 seconds
2. If they choose to maintain session, `getTokenSilently()`

<Frame>
  <img alt="Diagram of prompting a user to maintain a session" />
</Frame>

#### User explicitly logs out of application

1. User chooses to logout
2. `logout()` called

   1. Token cache cleared
   2. Call `/oidc/logout`
   3. Clear SSO cookie & delete session data
   4. Redirect user to logout page

<Frame>
  <img alt="Diagram of a user logging out" />
</Frame>

#### User returns to initial application after logging out

1. User requests data from protected resource
2. `getTokenSilently()` called
3. Application-dependent behavior

<Frame>
  <img alt="Diagram of user returning to application after logging out" />
</Frame>

## Long-lived sessions

Auth0 supports long-lived sessions for enterprise plans. With long-lived sessions, you can configure session limits with up to 100 days of inactivity (idle timeout) and up to one year in total duration (absolute timeout). If you have quarterly, monthly, or other timelines, this allows you to reduce friction for end-users and provide access to low-risk content and capabilities. In addition, media companies can leverage long-lived sessions for improving user experiences through seamless access to content. You can also make the choices between long-lived sessions and password validation based on your requirements around user experience and security.

Workflow details would change in the case of a long-lived session where the application session would most likely be shorter than the [Single Sign-on (SSO)](/docs/authenticate/single-sign-on) session.

To learn more, read [Configure Session Lifetime Limits](/docs/manage-users/sessions/configure-session-lifetime-settings) and [Update Access Token Lifetime](/docs/secure/tokens/access-tokens/update-access-token-lifetime).

##

## Learn more

* [Troubleshoot Invalid Token Errors](/docs/troubleshoot/basic-issues/invalid-token-errors)
* [Check API Calls](/docs/troubleshoot/authentication-issues/check-api-calls)


# Sessions with Actions
Source: https://auth0.com/docs/manage-users/sessions/manage-sessions-actions

Learn about managing sessions with Actions

Using Sessions with [Actions](/docs/customize/actions) allows you to configure post-authentication risk detection and response capabilities to protect your applications and users against session hijacking. You can also dynamically customize the [session lifetime limits](/docs/manage-users/sessions/configure-session-lifetime-settings).

To facilitate this, post-login Actions feature two key objects:

* **event.session**: Provides relevant information including unique `id`, `created_at`, `expires_at`, `idle_expires_at`, `updated_at` dates, `clients`, `authentication_at`, and `device` information, such as `ASN`, `IP`, and `User_agent`.
* **api.session:** Allows you to manage existing sessions by revoking sessions or changing `expiry` dates.

The `event.session` and `api.session` objects both support interactive web-based flows, including [authorization code flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow), implicit flow, device code flow, as well as <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> and <Tooltip href="/docs/glossary?term=WS-Fed">WS-Fed</Tooltip>.

You can use the `event.session` object to review timestamps of the latest interactions and evaluate risks associated with the current transactions. You can also combine the `event.session` object with other event objects, such as `event.authentication` or `event.request`.

You can then use the `api.session` object to either reset the existing session expiry dates or revoke the session.

To learn more about these objects, review:

* [Event object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object): Learn about the session Event object and properties.
* [API object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object): Learn about the session API object and methods.

## Revoke sessions with Actions

The post-login **api.session.revoke(reason, options)** method allows you to react to risks associated with a transaction. This method includes an option to allow you to preserve the <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip> bound to the revoked transaction.

In addition to revoking the session, the method will also initiate a `session-revoked` [OIDC Back-Channel Logout Initiator](/docs/authenticate/login/logout/back-channel-logout/oidc-back-channel-logout-initiators) to log out users from all applications bound to the current session and log a [session\_revoked](/docs/deploy-monitor/logs/log-event-type-codes) event in the tenant logs.

You can use this method to:

* Invalidate the current session transaction in Auth0
* Deny the current transaction
* Revoke all [refresh tokens](/docs/secure/tokens/refresh-tokens) associated with the existing session with a matching `session_id` value.

  * This is a customizable option; you can choose to preserve the refresh tokens rather than revoke them. This operation runs asynchronously and eventually becomes consistent.

<Callout icon="file-lines">
  If you want to use the `api.session.revoke(reason,options)` method, ensure that the property event.session.id exists.

  Different from `api.access.deny()`, `api.session.revoke()` will deny the current transaction and also revoke the session, therefore first factor authentication will be required again
</Callout>

### Monitor revoke log events

The revoke operation adds the following log event in your [tenant logs](/docs/deploy-monitor/logs):

A `session_revoked` event code indicating a revoked session with its associated `session_id` attribute.

## Change sessions expiry dates with Actions

You can modify session [expiry dates](/docs/manage-users/sessions/session-lifetime-limits) with the following post-login methods:

* **api.session.setExpiresAt(absolute)** allows you to define a new absolute (Require log in after) session expiration date for a specified session.
* **api.session.setIdleExpiresAt(idle)** allows you to set a new inactivity timeout date for a specified session.

You can use these methods to dynamically customize the session lifetime and inactivity policies based on:

* A user’s organization
* A user’s Auth0 connection
* A specific user’s group membership or profile
* Risk assessment
* Any other dynamic criteria available during the execution of the Action

<Callout icon="file-lines">
  If you want to use the `api.session.setExpiresAt(absolute)` and `api.session.setIdleExpiresAt(idle)` methods, ensure that a property of the event.session object exists, such as `event.session.id`.

  The `api.session.setIdleExpiresAt(idle)` method sets the session inactivity timeout for  the current interaction. If the method is not reapplied, subsequent successful interactions will override the inactivity timeout using the session inactivity timeout settings.
</Callout>

## Set session cookie persistence with Actions

The post-login **api.session.setCookieMode(options)** method allows you to modify the session cookie persistence. You can configure whether a session cookie is persistent or non-persistent.

Non-persistent (ephemeral) sessions enhance security by existing only in memory. These sessions are cleared when a browser or application is closed, which makes them ideal for sensitive workflows such as untrusted device access or step-up authentication scenarios.

You can use this method to:

* Enforce ephemeral sessions for users in high-risk roles or groups

* Require reauthentication when the browser is closed for certain devices or IP ranges

* Shorten session lifespan for untrusted or shared environments (e.g., public computers)

This method accepts the following parameters:

<table>
  <thead>
    <tr>
      <th><strong>Property</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>persistent</code></td>
      <td>string</td>
      <td>The session is stored in a persistent cookie and survives browser restarts, unless manually cleared.</td>
    </tr>

    <tr>
      <td><code>non-persistent</code></td>
      <td>string</td>
      <td>The session is stored in memory only and cleared when the browser or application is closed.</td>
    </tr>
  </tbody>
</table>

<Callout icon="file-lines">
  The `api.session.setCookieMode()` method overrides the default tenant setting for the current session.

  Auth0 retains the persistence setting throughout the session and does not need to be set again in future silent authentication flows.

  The `api.session.setCookieMode()` method must be used within a post-login Action. If it is used in a context where `api.session` is not available, the call fails silently.
</Callout>

To learn how to implement session cookie persistence, read [Configure Keep Me Signed In using Sessions](/docs/manage-users/sessions/configure-keep-me-signed-in-sessions).

## Limitations

Sessions issued before the release of the post-login API methods `api.session.setExpiresAt(absolute)` and `api.session.setIdleExpiresAt(idle)` will not contain the following event.session property: `last_interacted_at.`

Sessions issued before the release of the post-login API method `api.session.revoke(reason, options)` will not contain the following event.session.device properties:

* `initial_ip`
* `initial_asn`
* `initial_user_agent`

For security reasons, inactivity and absolute timeouts cannot be set above the session settings defined in the [session lifetime limits](/docs/manage-users/sessions/configure-session-lifetime-settings) for the tenant. If you attempt to set a date above the lifetime limits, the API methods will update up to the lifetime limits and log a warning event (`w`) in the tenant logs.

## Use cases: Revoke a session

You can use [Actions](/docs/customize/actions) to configure risk detections and revoke risky sessions and their associated refresh tokens with the post-login `api.session.revoke(reason, options)` method and the `event.session` object.

### Revoke a session due to ASN network binding

You can use the post-login object properties, `event.session.device.initial_asn` and `event.request.asn` to bind session transactions to a specific [autonomous system number (ASN)](https://www.arin.net/resources/guide/asn/) network for their duration and require a re-authentication if the ASN network changes.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const sessionInitialAsn = event.session?.device?.initial_asn;
  const sessionCurrentAsn = event.request.asn;

  // if there is a session and the ASN changes
  if (
    sessionInitialAsn &&
    sessionCurrentAsn &&
    sessionInitialAsn != sessionCurrentAsn
  ) {
    api.session.revoke( "Invalid network change. Login again from a trusted network" )
  }
};
```

In this example, a check occurs at the start of the Action to verify that the `event.session.device.initial_asn` and `event.request.asn` properties remain within the same ASN network during the transaction. If this check fails, the Action calls  `api.session.revoke()` to:

* Invalidate the session
* Deny the current transaction
* Revoke all its associated refresh tokens
* Prompt for re-authentication

### Revoke a session due to an IP binding

You can use the post-login object properties `event.session.device.initial_ip` and `event.request.ip` to ensure a session transaction stays with the same IP address for its duration. In this scenario, any IP change is considered a risk, and the user will be prompted to re-authenticate.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const sessionInitialIp = event.session?.device?.initial_ip;
  const sessionCurrentIp = event.request.ip;

  // if there is a session and the IP changes
  if (
    sessionInitialIp &&
    sessionCurrentIp &&
    sessionInitialIp != sessionCurrentIp
  ) {
    api.session.revoke("Invalid IP change")
  }
};
```

In this example, a check occurs at the start of the Action to verify that the `event.session.device.initial_ip` and `event.request.ip` properties remain with the same IP address during the transaction. If the check fails, the Action then calls  `api.session.revoke()` to:

* Invalidate the session
* Deny the current transaction
* Revoke all its associated refresh tokens
* Prompt for re-authentication

## Use cases: Customize a session expiry dates

You can use [Actions](/docs/customize/actions) to customize session idle and absolute expiration dates. Specifically, you can configure the expiry dates for a particular session transaction using the post-login `api.session.setExpiresAt(absolute)` and `api.session.setIdleExpiresAt(idle)` methods and the `event.session` object.

### Customize absolute session expiration time based on connections

You can use the following post-login object properties, to define a lifetime for the connection used to authenticate a user.

* event.session.created\_at
* event.session.expires\_at

And using the Auth0 [Management API](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id) to create a connection metadata , `event.connection.metadata.session_timeout define` a specific connection timeout.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const created = Date.parse(event.session?.created_at ?? "");

  // desired session lifetime for this connection in milliseconds, configured as connection metadata
  const connection_lifetime = event.connection?.metadata?.session_timeout;

  // if there is a session lifetime defined for the connection, set it
  if (event.session?.id && connection_lifetime) {
    api.session.setExpiresAt(created + Number(connection_lifetime));
  }
};
```

In this example, a check occurs at the start of the Action to verify that there is a  `session_timeout` defined in the current connection. In that case, the Action sets the session expiration to be equal to when the session was `created` plus the `connection_lifetime`.

### Customize session inactivity timeout based on the Organization

You can define a `current_time` variable and using a new Organization metadata called `idle_session_timeout` set the idle timeout desired for an organization.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  // The Organization metadata is configured with a shorter idle timeout for sessions (in milliseconds)
  const idle_organization_lifetime =
    event.organization?.metadata?.idle_session_timeout;

  // If the organization has an specific idle timeout defined, set the timeout
  if (event.session?.id && idle_organization_lifetime) {
    const current_time = new Date().getTime();

    api.session.setIdleExpiresAt(
      current_time + Number(idle_organization_lifetime),
    );
  }
};
```

In this example, if there is a specific idle timeout defined for the Organization, the Action sets the session inactivity timeout to be equal to the `current_time` plus the `idle_organization_lifetime` .


# Manage User Sessions with Auth0 Management API
Source: https://auth0.com/docs/manage-users/sessions/manage-user-sessions-with-auth0-management-api

Learn how to manage user sessions with the Auth0 Management API.

Auth0 uses [sessions](/docs/manage-users/sessions) to maintain the authentication state of a user across requests.

<Callout icon="file-lines">
  The Auth0 Management API session management endpoints are available to customers on Enterprise plans. To learn more, read [Pricing](https://auth0.com/pricing).
</Callout>

## Management API endpoints

The [Management API](https://auth0.com/docs/api/management/v2) provides out-of-band access to the internals of user sessions in the [Auth0 Session Layer](/docs/manage-users/sessions/session-layers), and deletion methods to force session termination.

### Session resource

You can view or delete a specific session with the following endpoints:

<table>
  <thead>
    <tr>
      <th><strong>Name</strong></th>
      <th><strong>URL</strong></th>
      <th><strong>Required scope(s)</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Introspect a specific session by ID</td>
      <td><code>GET /api/v2/sessions/</code></td>
      <td><code>read:sessions</code></td>
    </tr>

    <tr>
      <td>Delete a specific session by ID</td>
      <td><code>DELETE /api/v2/sessions/</code></td>
      <td><code>delete:sessions</code></td>
    </tr>
  </tbody>
</table>

### User resource

You can list or delete all sessions for a given user with the following endpoints:

<table>
  <thead>
    <tr>
      <th><strong>Name</strong></th>
      <th><strong>URL</strong></th>
      <th><strong>Required scope(s)</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>List sessions details of a user</td>
      <td><code>GET /api/v2/users//sessions</code></td>
      <td><code>read:sessions</code></td>
    </tr>

    <tr>
      <td>Delete all user sessions</td>
      <td><code>DELETE /api/v2/users//sessions</code></td>
      <td><code>delete:sessions</code></td>
    </tr>
  </tbody>
</table>

## Session properties

The session endpoints return relevant information about the session and its history.

<table>
  <thead>
    <tr>
      <th><strong>Field</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Session ID</td>
      <td>The session ID is a persistent identifier of the session in the Auth0 tenant.<br /><br />Note that the session ID corresponds to the <code>sid</code> claim already in ID Tokens and Logout Tokens and can be used to cross-reference these entities.</td>
    </tr>

    <tr>
      <td>Relevant Time</td>
      <td>Session creation, authentication time, and expiry information.</td>
    </tr>

    <tr>
      <td>Device Information</td>
      <td>The device property traces details related to the user agent (for example, browser) used in the interactions with this Auth0 session.</td>
    </tr>

    <tr>
      <td>Authentication Information</td>
      <td>Contains summary information about the methods used to authenticate in this session.</td>
    </tr>
  </tbody>
</table>

For detailed information about these fields, refer to the [Management API documentation](https://auth0.com/docs/api/management/v2).

## OIDC Back-Channel Logout Initiators

Session deletion events are connected to [OIDC Back-Channel Logout](/docs/authenticate/login/logout/back-channel-logout) through the `session-deleted` initiator. To learn more, read [OIDC Back-Channel Logout Initiators](/docs/authenticate/login/logout/back-channel-logout/oidc-back-channel-logout-initiators).

## Sessions and refresh tokens

Sessions and <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip> collaborate to reduce the friction of user authentication while optimizing security. To learn more, read [Best Practices for Application Session Management on Auth0 Blog](https://auth0.com/blog/application-session-management-best-practices).

Refresh tokens can remain active after a session has expired or been deleted, or after the user logs out. You can use the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to [manage refresh tokens](/docs/secure/tokens/manage-refresh-tokens-with-auth0-management-api) independently or in collaboration with sessions.

## Limitations

Delete session operations run asynchronously, and are eventually consistent.

## Learn more

* [Log Users Out of Auth0 with OIDC Endpoint](/docs/authenticate/login/logout/log-users-out-of-auth0)
* [OIDC Back-Channel Logout](/docs/authenticate/login/logout/back-channel-logout)
* [OIDC Back-Channel Logout Initiators](/docs/authenticate/login/logout/back-channel-logout/oidc-back-channel-logout-initiators)
* [Configure OIDC Back-Channel Logout](/docs/authenticate/login/logout/back-channel-logout/configure-back-channel-logout)


# Session Layers
Source: https://auth0.com/docs/manage-users/sessions/session-layers

Describes layers created when users log in.

There are typically three session layers that can be created when your users log in:

* **Application Session Layer**: This layer is the session inside your application. Though your application uses Auth0 to authenticate users, your application also tracks that the user has logged in to your application; in a regular web application, for example, you achieve this by storing this information inside a cookie.
* **Auth0 Session Layer**: Auth0 also maintains a session on the <Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip> for the user and stores their user information inside a cookie. This layer is used so that the next time a user is redirected to Auth0 for login the user's information will be remembered. This session layer makes the <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> experience possible for inbound SSO implementations.
* **<Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> Session Layer**: When users attempt to sign in using an identity providers such as Facebook or Google, and they already have a valid sign-in (with whichever provider they choose) they will not be prompted again to sign in though they may be asked to give permission to share their information with Auth0 and, in turn, your application.

### Session logout

Logout in the context of Auth0 implementations is the act of terminating an authenticated session. It is a security best practice to terminate sessions when they’re no longer needed to avoid a potential takeover by unauthorized parties.

Auth0 provides tools to help you give users the ability to log out; this includes options for providing different levels of logout and also determining where the user will land after the logout is complete.

* **Application Session Layer Logout**: Logging users out of your applications typically results in their application session being cleared, and this should be handled by your application: for the Application Session Layer, there is nothing within your Auth0 tenant that you need to use to facilitate session termination. This will require you to utilize whatever application session stack you are using to clear out any session related information. Note that some of the Auth0 SDKs do provide some support for application sessions; please check the documentation to see if there is any local SDK session removal that needs to be done.
* **Auth0 Session Layer Logout**: You can log users out of the Auth0 session layer by redirecting them to the Auth0 Logout endpoint so Auth0 can clear the SSO cookie.

  <Callout icon="file-lines">
    Generally, you clear an Auth0 session by diverting users to the `/logout` endpoint. However, if you call the [Update a User](https://auth0.com/docs/api/management/v2/#!/Users/patch_users_by_id) endpoint to reset user attributes (passing values `email`, `email_verified`, `phone_number`, and `password`), `auth0.checkSession` does not renew the session, and the user must re-login.
  </Callout>
* **Identity Provider Session Layer Logout**: It is not necessary to log the users out of this session layer, but you can use Auth0 to force the logout if required.

#### Redirect URLs

Logging out of your Auth0 Session Layer will require you to redirect the user to `https://{yourCNAME}` or `{yourTenant}.auth0.com/oidc/logout` - typically performed via use of the appropriate method in the Auth0 SDK for your technology stack. This will clear your Auth0 session. You will also want to add a query parameter for that request called `id_token_hint` - this parameter should contain a URL that has been pre-registered and protects you against open redirect attacks.

Auth0 only redirects to AllowListed URLs after logout and there are two places you can configure these. The first place you can set this is at your Auth0 tenant level where you can put the set of logout URLs that are shared between all applications. The second place is in the application settings: if you need different redirects for each application, you can allowlist the URLs in your application settings. This allows you to set logout URLs in an application-specific context.

#### Session lifetime and session timeout

You can set the behavior in cases where a user doesn’t explicitly log out of your application. Auth0 provides [session lifetime](/docs/manage-users/sessions/session-lifetime-limits) limits to deal with Auth0 session termination in this scenario.

#### Federated logout

You can also log the users out of the identity provider session layer. While this is not recommended, for many providers, Auth0 provides this behavior by having you add the `federated` query parameter to the redirect to `/oidc/logout`. This redirects the user to their identity provider and logs them out there as well. To learn more about federated logout, review the article [Log Users Out of Identity Providers](/docs/authenticate/login/logout/log-users-out-of-idps).

## Learn more

* [Session Lifetime Limits](/docs/manage-users/sessions/session-lifetime-limits)


# Session Lifecycle
Source: https://auth0.com/docs/manage-users/sessions/session-lifecycle

Learn about the Session Lifecycle.

An Auth0 session lifecycle begins when a user logs in, remains active with user interaction, and ends when the session expires or is explicitly terminated.

Auth0 considers a session active when a user interacts with the Authorization server.

For example:

* Calls to the [/authorize](/docs/api/authentication/authorization-code-flow/authorize-application) endpoint
* Issue [silent authentication](/docs/authenticate/login/configure-silent-authentication)
* Log in to a new application using [single sign on](/docs/authenticate/single-sign-on)

A session can be persistent or non-persistent; this allows you to configure how a session cookie behaves in a browser.

* **Persistent sessions** store cookies with a future expiration timestamp.
* **Non-persistent sessions** store cookies with `Expires=0`. It tells the browser to delete the cookie when the browser is closed.

<Callout icon="file-lines">
  Session cookie persistence behavior depends on the browser implementation. Auth0 cannot guarantee that all browsers will delete non-persistent cookies as expected.
  To learn more read [Cookies](https://auth0.com/docs/manage-users/cookies).
</Callout>

## Session lifetime

Persistent and non-persistent sessions can be configured with their own Idle and Absolute (Maximum) lifetimes to define a session expiration.

### Idle timeout

Idle timeout defines the maximum duration of inactivity allowed. Each time a user interacts with Auth0 via Single Sign-On (SSO), silent authentication or /authorize, the idle timer resets. If no interaction with Auth0 happens during the configured period, the session expires.

### Absolute timeout (Maximum)

Absolute timeout defines the maximum duration a session can remain valid regardless of user activity. Once absolute timeout is reached, the session expires and the user will need to reauthenticate.

Learn how to [Configure Session Lifetime](/docs/manage-users/sessions/configure-session-lifetime).

## Session lifetime limits

Session lifetime has the following limits:

<table>
  <thead>
    <tr>
      <th><strong>Session type</strong></th>
      <th><strong>Timeout type</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Maximum (Self-Service plans)</strong></th>
      <th><strong>Maximum (Enterprise Plans)</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Non-persistent</td>
      <td>Inactivity timeout</td>
      <td>Timeframe after which a session expires if there’s no interaction with the Authorization Server</td>
      <td>3 days</td>
      <td>100 days</td>
    </tr>

    <tr>
      <td />

      <td>Require Login after</td>
      <td>Maximum session lifetime, regardless of activity</td>
      <td>30 days</td>
      <td>365 days</td>
    </tr>

    <tr>
      <td>Persistent</td>
      <td>Inactivity timeout</td>
      <td>Timeframe after which a session expires if there’s no interaction with the Authorization Server</td>
      <td>3 days</td>
      <td>100 days</td>
    </tr>

    <tr>
      <td />

      <td>Require Login after</td>
      <td>Maximum session lifetime, regardless of activity</td>
      <td>30 days</td>
      <td>365 days</td>
    </tr>
  </tbody>
</table>

## Next steps

* To learn more about using Actions to configure the session lifecycle, read [Sessions with Actions](/docs/manage-users/sessions/manage-sessions-actions).

* To learn more about Auth0 Management API Session Management Endpoints, read [Sessions with Management API](docs/manage-users/sessions/manage-user-sessions-with-auth0-management-api).


# Session Metadata
Source: https://auth0.com/docs/manage-users/sessions/session-metadata

Learn about Auth0 session metadata

Session metadata allows the storage of customizable keys and values (maximum 255 characters each) in an Auth0 user [session](/docs/manage-users/sessions).

Use cases for session metadata include:

* Track device information, such as device name or login location
* Store session-level flags, for example, `user_accepted_terms`
* Share state between multiple Actions in the same flow
* Drive conditional logic for logout or token issuance

You can use session metadata information downstream systems such as audit, analytics, and revocation pipelines that may need to be aware of a user’s organization data.

To learn more, read [Use case: Organization Information in Session Metadata](/docs/manage-users/sessions/session-metadata/add-organization-information).

You can access and modify session metadata during a session’s [lifecycle](/docs/manage-users/sessions/session-lifecycle) using Auth0 [Actions](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) and the [Management API](https://auth0.com/docs/api/management/v2). In addition, you can include session metadata in the [OpenID Connect Back-Channel Logout](/docs/authenticate/login/logout/back-channel-logout) token.

To learn more, read [how to Configure Session Metadata](/docs/manage-users/sessions/session-metadata/configure-session-metadata).

<Warning>
  Auth0 Session Metadata is not a secure data store and should not be used to store sensitive information. This includes secrets and high-risk PII like social security numbers or credit card numbers, etc. Auth0 customers are strongly encouraged to evaluate the data stored in metadata and only store that which is necessary for identity and access management purposes. To learn more, read [Auth0 General Data Protection Regulation Compliance](/docs/secure/data-privacy-and-compliance/gdpr).
</Warning>

## Limitations

* Session metadata is available only when created in a browser-based session
* Auth0 does not support session metadata with the following:
  * Resource Owner Password Flow
  * Native Passkeys
  * Native Social Logins such as Sign in with Apple, Google, or Facebook


# Use Cases: Organization Information in Session Metadata
Source: https://auth0.com/docs/manage-users/sessions/session-metadata/add-organization-information

Learn how to add organization metadata in session metadata

Session metadata makes the user context data portable and visible across the session lifecycle and in logout events.

Downstream systems can use session metadata information to conduct audits, perform analytics, and apply revocation pipelines, among other uses.

<Warning>
  Auth0 Session Metadata is not a secure data store and should not be used to store sensitive information. This includes secrets and high-risk PII like social security numbers or credit card numbers, etc. Auth0 customers are strongly encouraged to evaluate the data stored in metadata and only store that which is necessary for identity and access management purposes. To learn more, read [Auth0 General Data Protection Regulation Compliance](/docs/secure/data-privacy-and-compliance/gdpr).
</Warning>

## Add organization information to session metadata

You can use [Actions](/docs/customize/actions) to store the organization’s identifiers in a session with the [post-login](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) `api.session.setMetadata()` method and query it with the `event.session.metadata` object.

Post-Login Action code:

```javascript lines theme={null}
/**
 * Post-Login Action (simple)
 * Adds organization context to session metadata so it appears in subsequent Actions,
 * the Management API, and (if enabled) the Back-Channel Logout token.
 */
exports.onExecutePostLogin = async (event, api) => {
  // Only proceed if the transaction targets an Organization
  if (!event.organization) return;

  // Keep values short and string-only (session metadata requires strings)
  const orgId = String(event.organization.id || "");
  const orgSlug = String(event.organization.name || "");
  const orgDisplay = String(event.organization.display_name || orgSlug);

  // Minimal, idempotent writes (only a few keys to stay well under limits)
  api.session.setMetadata("org_id", orgId);
  api.session.setMetadata("org_slug", orgSlug);
  api.session.setMetadata("org_name", orgDisplay);
};
```

The session metadata is available for subsequent Actions, retrievable via the [Management API](https://auth0.com/docs/api/management/v2) and can be included in the [OpenID Connect Back-Channel Logout](/docs/authenticate/login/logout/back-channel-logout) token.

* In subsequent Actions,  you can query the data via the `event.session.metadata` object:

```javascript lines theme={null}
const orgId = event.session.metadata?.org_id;
```

* If you use the Management API, you can query the data via the [/api/v2/sessions/](https://auth0.com/docs/api/management/v2/sessions/get-session) endpoint:

```bash lines theme={null}
GET /api/v2/sessions/{id}
```

Sample response:

```json lines theme={null}
{
  "session_metadata": {
    "org_id": "org_abc123",
    "org_slug": "acme",
    "org_name": "Acme Corp"
  }
}
```

<Callout icon="file-lines">
  Calls to the `/api/v2/sessions/{id}` endpoint require a [Management API access token](/docs/secure/tokens/access-tokens) with the `update:session` scope.
</Callout>

* If you have an [OIDC Back-Channel Logout session metadata](/docs/manage-users/sessions/session-metadata/configure-session-metadata) configured application, the `logout_token` includes the session metadata:

```json lines theme={null}
{
  "events": { "http://schemas.openid.net/event/backchannel-logout": {} },
  "session_metadata": {
    "org_id": "org_abc123",
    "org_slug": "acme",
    "org_name": "Acme Corp"
  }
}
```


# Configure Session Metadata
Source: https://auth0.com/docs/manage-users/sessions/session-metadata/configure-session-metadata

Learn how to configure Auth0 session metadata

To configure session metadata, you can use an Auth0 [Post-Login Action](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) and the [Management API](https://auth0.com/docs/api/management/v2). You can also include it in the [OpenID Connect Back-Channel Logout](/docs/authenticate/login/logout/back-channel-logout) token.

<Warning>
  Auth0 Session Metadata is not a secure data store and should not be used to store sensitive information. This includes secrets and high-risk PII like social security numbers or credit card numbers, etc. Auth0 customers are strongly encouraged to evaluate the data stored in metadata and only store that which is necessary for identity and access management purposes. To learn more, read [Auth0 General Data Protection Regulation Compliance](/docs/secure/data-privacy-and-compliance/gdpr).
</Warning>

## Auth0 Management API

You can manage session metadata CRUD (create, replace, update, delete) requests using the Management API:

<Callout icon="file-lines">
  Calls to the `/api/v2/sessions/{id}` endpoint require a [Management API access token](/docs/secure/tokens/access-tokens) with the `update:session` scope.
</Callout>

### Retrieve existing session metadata

Make a `GET` request to the [`/api/v2/sessions/{id}`](https://auth0.com/docs/api/management/v2/sessions/get-session) endpoint:

```bash lines theme={null}
GET /api/v2/sessions/{id}
```

### Add or update existing session metadata

Make a `PATCH` request to the [`/api/v2/sessions/{id}`](https://auth0.com/docs/api/management/v2/sessions/patch-sessions-by-id) endpoint:

```bash lines theme={null}
PATCH /api/v2/sessions/{id}
Content-Type: application/json

{
  "session_metadata": {
    "my_metadata": "my new metadata"
  }
}
```

### Delete session metadata

Make a `PATCH` request to the [`/api/v2/sessions/{id}`](https://auth0.com/docs/api/management/v2/sessions/patch-sessions-by-id) endpoint:

```bash lines theme={null}
PATCH /api/v2/sessions/{id}
Content-Type: application/json

{
  "session_metadata": {}
}
```

## Auth0 Post-Login Actions

You can manage session metadata CRUD operations using the `api.session` objects with a [post-login Action](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger). This allows you to manage session metadata based on user or context-specific logic.

### Retrieve existing session metadata

Use the `event.session.metadata?.deviceName` object to read the `deviceName` metadata:

```javascript lines theme={null}
const device = event.session.metadata?.deviceName;
```

<Callout icon="file-lines">
  The `event.session.metadata` object includes metadata set in:
  \*Previous Actions within the same flow
  \*Prior transactions if the session was reused
</Callout>

### Add or update existing metadata

Use the `api.session.setMetadata()` method to update the session metadata:

```javascript lines theme={null}
api.session.setMetadata("deviceName", "Auth0's iPhone");
```

Changes are immediately available in the `event.session` object in subsequent Actions.

### Delete session metadata

Use the following `api.session` objects to delete session metadata:

* `api.session.deleteMetadata("key")` deletes the specified session metadata

* `api.session.evictMetadata()` deletes all session metadata

To learn more about these objects, review:

* [Event object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object): Learn about the refresh token Event object and properties.
* [API object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object): Learn about the refresh token API object and methods.

## OIDC Back-Channel Logout

You can configure the `logout_token` to include session metadata using the Auth0 [Dashboard](/docs/get-started/auth0-overview/dashboard) or the [Management API](https://auth0.com/docs/api/management/v2).

### Auth0 Dashboard

To configure OIDC Back-Channel Logout token with session metadata:

1. Navigate to [Dashboard > Applications](https://manage.auth0.com/#/applications) and select your application.

2. Select the **Settings** tab.

3. Under **OpenID Connect Back-Channel Logout > Back-Channel Logout URL**, add the application logout URI that will receive the logout\_tokens.

4. Set **Back-Channel Logout Initiators** to either:

   * **Selected initiators only** or

   * **All supported initiators**

5. Toggle on **Include Session Metadata**.

6. Select **Save Changes**.

Once configured, the `logout_token` will include all stored session metadata.

### Auth0 Management API

You can use the [`/api/v2/clients/{id}`](https://auth0.com/docs/api/management/v2/sessions/patch-sessions-by-id) endpoint to update your application to include session metadata in the `logout_token`.

Make a `PATCH` request to the [`/api/v2/sessions/{id}`](https://auth0.com/docs/api/management/v2/sessions/patch-sessions-by-id) endpoint:

```json lines theme={null}
"oidc_backchannel_logout": {
  "backchannel_logout_initiators": {
    "mode": "all"
  },
  "backchannel_logout_urls": [
    "https://httpdump.app/inspect/9bccf574-e55f-4b2e-9822-f37372588fc1"
  ],
  "backchannel_logout_session_metadata": {
    "include": true
  }
}
```

## Error handling

You can review Session metadata log events by navigating to [Dashboard > Monitoring > Logs](https://manage.auth0.com/#/logs) or retrieve logs using the [Management API logs](/docs/api/management/v2/logs/get-logs) endpoint.

* If an error occurs while adding or updating Session metadata with Actions, the authentication transaction fails and an error is returned to the callback URL.

A failure `f` event code is logged with its correspoding error:

```json lines theme={null}
{
  "error": "access_denied",
  "error_description": "Failed to set session metadata: Invalid metadata: Metadata keys may only include letters, numbers, underscores, or hyphens",
  "state": "my-custom-state"
}
```

* If a failure occurs when managing Session metadata using the Auth0 Management API, the API responds with an `HTTP status: 400` error and its corresponding message:

```json lines theme={null}
{
  "statusCode": 400,
  "message": "Metadata must not exceed 25 entries. Each key and value must be ≤ 255 characters."
}
```


# Action Coding Guidelines
Source: https://auth0.com/docs/customize/actions/action-coding-guidelines

Write clear, concise, and secure Actions code with our coding guidelines.

Follow the guidelines below to write performant, secure, and clear Actions code for a streamlined production environment.

## Actions basics

* Use the minimum number of HTTP requests possible and set a reasonable timeout (less than 10 seconds) to avoid accumulated requests during login.
* Use [application metadata](/docs/get-started/applications/configure-application-metadata) to filter for specific applications to determine if an Action should be run.

  * Example: application specific values or application grouping values used to variate partially or fully the Action execution.
* Use `user_metadata`/`app_metadata` to persist custom data in the user profile.

  * Example: user preferences or state values.
* Use [transaction metadata](/docs/customize/actions/transaction-metadata) to share data between [post-login triggers](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) during the same execution.

  * Example: values retrieved from external services or calculated that need to be reused across subsequent Actions and are related to the current execution.
* Use cache for data to be shared by Actions belonging to different executions.

  * Example: values retrieved from external services or calculated that need to be reused by Actions and are unrelated to the user or the specific current execution.
* Ensure that Actions, which provide verification or trigger <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip>, cannot be bypassed unintentionally or maliciously.
* Actions should never intentionally throw an error; if processes stop because of an error or condition, use the appropriate `api` method like `api.access.deny()`.
* Use `event.request.hostname` for the domain used in Authentication API calls; this could be the default Auth0 tenant domain or a [custom domain](/docs/customize/custom-domains).

## Actions Modules

* Use Actions Modules when there is a need to reuse functions across different Actions, preventing code redundancy.
* Save object instantiation time when possible, by implementing [Singleton pattern](https://en.wikipedia.org/wiki/Singleton_pattern) to reuse object instances at the Action Module.
* Follow the applicable guidelines shared in this document regarding coding, security, logging, dependencies, and user data.
* When using an Action Module from an Action, always be aware of the module version that is being used.

<Callout icon="file-lines">
  When you publish a new Action Module version, Auth0 does not automatically upgrade the version referenced by the Actions, preventing potential breakage when the upgrade is not compatible with the Action.
</Callout>

## Coding basics

* Check for strict equals `===` with any incoming or stored data.
* Use a `return` statement when the Action process should stop.
* Run a code linter, like [ESLint](https://eslint.org), and an analyzer, like [Semgrep](https://semgrep.dev/docs/getting-started/), to improve code quality and find issues automatically.

## Security basics

* Do not write secrets or sensitive code artifacts in plain text as part of your Actions code. Instead, use the [Secrets Manager](/docs/customize/actions/write-your-first-action#add-a-secret) or leverage your own manager by integrating it within the Actions code.
* Do not transmit unencrypted personally-identifiable information (PII) in plain sight, like in URLs or error messages.
* Always use HTTPS URLs for redirects and API calls.
* AllowList IP addresses when possible.
* Watch for incoming data that can be tampered with (URL parameters, user agent, and so on).

## Defensive coding

* [Catch errors](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Control_flow_and_error_handling#exception_handling_statements) and handle as necessary.
* Use guard clauses and return early if the Action processing should not continue.

## Logging

* Never log sensitive data, secrets, or PII.
* Stay under the maximum of 256 characters logged per Action.

## Dependencies

* Use trusted and maintained packages.
* Check for outstanding CVEs using [`npm`'s audit feature](https://docs.npmjs.com/cli/v6/commands/npm-audit) or an automated dependency checker connected to a repository.
* Use the latest version of a package when possible.

## User data

* Check if an email is verified with `event.user.email_verified` if it is being used in a sensitive or high-security context.
* Different Connections provide different user profile data; the only guaranteed [user profile field](/docs/manage-users/user-accounts/user-profiles/user-profile-structure) is the `user_id`.

## Redirect Actions in the Login Flow

* The token returned by `api.redirect.encodeToken` is signed but not encrypted, so sensitive data or PII should not be included in the payload.
* The Login Flow runs after a successful login, which includes:

  * SSO (no login form shown)
  * silent authentication (checking a session using `prompt=none` in the authorization URL)
  * refresh token exchange (no user interaction)
  * RO password grants (credentials gathered from an application and exchanged with the token endpoint)
* Actions that redirect need to take the above cases into account and either deny access if interaction is required or intensionally allow bypassing, which puts the burden on the application requesting login.


# Actions NPM
Source: https://auth0.com/docs/customize/actions/actions-npm

Code your project's Actions using @auth0/actions NPM package.

The [**`@auth0/actions`** NPM package](https://www.npmjs.com/package/@auth0/actions) is the **official Actions library** that facilitates the **Auth0 Actions TypeScript definitions**. This helps you code and test your project’s Actions in external editors and IDEs.

### Benefits

This library helps you with the following use cases:

* **IDE / Code Editor Assistance**: By referencing this library, IDEs and code editors can help developers coding with **autocompletion**, **object and function definitions**, and **error checking**.
* **TypeScript Development**: Although Actions are still coded and work using Node.js CommonJS, this library enables Actions development on external projects using **TypeScript** which then can be built and deployed as Common JS to the Auth0 Tenant.
* **Unit Testing Improvements**: By enabling TypeScript development on external projects, this library allows developers to follow best practices and to **improve their Unit Testing** based on the TypeScript definitions.
* **AI Actions Generation**: This library gets us one step closer for AI to be able to generate more accurate Action examples.

***

### How It Works

#### Installation

Use one of the following package managers to install the package as a **development dependency**:

> The package must be used as a development dependency to supplement your development tools.

* **NPM**: `npm install @auth0/actions --save-dev`
* **Yarn**: `yarn add @auth0/actions --dev`
* **Pnpm**: `pnpm add @auth0/actions --save-dev`

***

#### Import

The library has the following **structure**:

```bash theme={null}
@auth0/actions
│
└───credentials-exchange
│   └───v1
│   └───v2
└───custom-email-provider
│   └───v1
└───custom-phone-provider
│   └───v1
└───custom-token-exchange
│   └───v1
└───event-stream
│   └───v1
└───password-reset-post-challenge
│   └───v1
└───post-change-password
│   └───v1
│   └───v2
└───post-login
│   └───v1
│   └───v2
│   └───v3
└───post-user-registration
│   └───v1
│   └───v2
└───pre-user-registration
│   └───v1
│   └───v2
└───send-phone-message
    └───v2
```

The import statement should be based on each **trigger name** and **version number** considering the previous library structure.

**Follow the pattern**: `@auth0/actions/[trigger_name]/[trigger_version]`

**For example**: `@auth0/actions/post-login/v3`

Use one of the following alternatives to import the TypeScript definitions into your Actions depending on your technology:

Use this alternative when you want IntelliSense without changing your existing JavaScript code structure:

<Tabs>
  <Tab title="JSDoc @import">
    Use this alternative when you want IntelliSense without changing your existing JavaScript code structure:

    ```javascript theme={null}
    /** @import {Event, PostLoginAPI} from "@auth0/actions/post-login/v3" */

    /**
    * Handler that will be called during the execution of a PostLogin flow.
    *
    * @param {Event} event - Details about the user and the context in which they are logging in.
    * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
    */
    exports.onExecutePostLogin = async (event, api) => {
      // Your code
    }
    ```
  </Tab>

  <Tab title="JSDoc @param">
    Use this alternative for type safety in JavaScript files using import statements in JSDoc comments:

    ```javascript theme={null}
    /**
    * Handler that will be called during the execution of a PostLogin flow.
    *
    * @param {import('@auth0/actions/post-login/v3').Event} event - Details about the user and the context in which they are logging in.
    * @param {import('@auth0/actions/post-login/v3').PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
    */
    exports.onExecutePostLogin = async (event, api) => {
      // Your code
    };
    ```
  </Tab>

  <Tab title="TypeScript import">
    Use this alternative when developing with TypeScript for full type checking and modern syntax:

    ```javascript theme={null}
    import type { Event, PostLoginAPI } from '@auth0/actions/post-login/v3';

    /**
    * Handler that will be called during the execution of a PostLogin flow.
    *
    * @param {Event} event - Details about the user and the context in which they are logging in.
    * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
    */
    exports.onExecutePostLogin = async (event: Event, api: PostLoginAPI) => {
      // Your code
    };
    ```
  </Tab>
</Tabs>

<Warning>
  When using TypeScript, you must compile your code to JavaScript before deploying to Auth0. The Auth0 Actions runtime only executes JavaScript.Use the TypeScript compiler (`tsc`) to transpile your `.ts` files to `.js` files, before it can be deployed. You must also include JSDoc comments to enable IntelliSense in the Dashboard.
</Warning>

### Examples

The following Actions examples are intentionally presented in both JavaScript and TypeScript to provide a direct, side-by-side comparison.

#### Configuration

<Tabs>
  <Tab title="JavaScript">
    In your `package.json`, define any development dependencies to have intelliSense help when writing your Action:

    ```javascript theme={null}
    {
      "name": "actions-js",
      "version": "1.0.0",
      "description": "Actions JS",
      "main": "example.js",
      "author": "John Doe",
      "license": "ISC",
      "devDependencies": {
        "@auth0/actions": "^0.7.1"
      }
    }
    ```
  </Tab>

  <Tab title="TypeScript">
    In your `package.json`, define any development dependencies to have intelliSense help when writing your Action.

    ```typescript theme={null}
    {
      "name": "actions-ts",
      "version": "1.0.0",
      "description": "Actions TS",
      "main": "example.ts",
      "author": "John Doe",
      "license": "ISC",
      "devDependencies": {
        "@auth0/actions": "^0.7.1",
        "@types/node": "22.14.0",
        "typescript": "^5.9.2"
      }
    }
    ```

    In your `tsconfig.json`, define any development dependencies to have intelliSense help when writing your Action.

    ```typescript theme={null}
    {
      "compilerOptions": {
        "target": "ES2020",
        "module": "NodeNext",
        "moduleResolution": "nodenext",
        "esModuleInterop": true,
        "allowSyntheticDefaultImports": true,
        "strict": true,
        "outDir": "dist",
        "declaration": true,
        "sourceMap": true,
        "allowJs": true,
        "checkJs": false,
        "resolveJsonModule": true,
        "skipLibCheck": true,
        "forceConsistentCasingInFileNames": true,
        "isolatedModules": true
      },
      "include": [
        "**/*.ts"
      ],
      "exclude": [
        "node_modules",
        "dist"
      ]
    }
    ```
  </Tab>
</Tabs>

### Post-Login access control and ID token custom claims

The following example Action would execute during the Post-Login flow. It checks if the user has roles assigned, and calls `api.access.deny()` if none are found. If roles are present, it proceeds to set the custom claim on the ID token.

The import statement declares the availability of external types to your code. This allows the editor to know the structure of the `event` and `api` objects.

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    /** @import {Event, PostLoginAPI} from "@auth0/actions/post-login/v3" */

    const CUSTOM_CLAIM_NAMESPACE = 'https://example.com';

    /**
    * Handler that will be called during the execution of a PostLogin flow.
    *
    * @param {Event} event - Details about the user and the context in which they are logging in.
    * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
    */
    exports.onExecutePostLogin = async (event, api) => {
      const roles = event.authorization?.roles;

      if (roles === undefined || roles.length === 0) {
        api.access.deny('Restricted');
        return;
      }

      api.idToken.setCustomClaim(`${CUSTOM_CLAIM_NAMESPACE}/roles`, roles);
    }
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import type { Event, PostLoginAPI } from '@auth0/actions/post-login/v3';

    const CUSTOM_CLAIM_NAMESPACE = 'https://example.com';

    /**
    * Handler that will be called during the execution of a PostLogin flow.
    *
    * @param {Event} event - Details about the user and the context in which they are logging in.
    * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
    */
    exports.onExecutePostLogin = async (event: Event, api: PostLoginAPI) => {
      const roles = event.authorization?.roles;

      if (roles === undefined || roles.length === 0) {
        api.access.deny('Restricted');
        return;
      }

      api.idToken.setCustomClaim(`${CUSTOM_CLAIM_NAMESPACE}/roles`, roles);
    };
    ```
  </Tab>
</Tabs>

To learn more about @auth0/actions, visit: [https://www.npmjs.com/package/@auth0/actions](https://www.npmjs.com/package/@auth0/actions).

To learn more about writing Actions, see [Write Your First Action](/docs/customize/actions/write-your-first-action).


# Understand How Auth0 Actions Work
Source: https://auth0.com/docs/customize/actions/actions-overview

Describes how Auth0 Actions work and what you can accomplish with them.

Actions are secure, tenant-specific, [versioned](/docs/customize/actions/manage-versions) functions written in Node.js that execute at certain points within the Auth0 platform. Actions are used to customize and extend Auth0's capabilities with custom logic.

<Callout icon="file-lines">
  Auth0 Actions uses modern JavaScript's [promise-based programming model](https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Async_JS/Promises), a basis for asynchronous functions in Actions.
</Callout>

The processes that can be extended in this way are called triggers. Trigger groupings represents the logical pipeline through which information moves during a single point in the Auth0 journey. Multiple Actions can be added to a trigger, with each Action executing in the order in which it was placed. Some triggers are executed synchronously, blocking the flow in which they are involved, and some are executed asynchronously, as indicated in the table below.

Actions are a cornerstone to our overall extensibility product at Auth0. With Actions, you can add essential custom logic to your login and identity flows specific to your needs. Actions also allow you to connect external integrations that enhance your overall extensibility experience. For example, you can add an Action to your login trigger to verify credentials such as a License or Passport using a Marketplace Partner who specializes in identity proofing.

## What can you do with Actions?

What an Action can do is determined by where it is executed within the Auth0 runtime environment.

<AccordionGroup>
  <Accordion title="Signup & Login: When a user is added to a database or passwordless connection.">
    <table>
      <thead>
        <tr>
          <th>Trigger</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>pre-user-registration</code></td>
          <td>Triggers before a user is created. Does not run for social connections.</td>
        </tr>

        <tr>
          <td><code>post-user-registration</code></td>
          <td>Triggers asynchronously after a user is created. Does not run for social connections.</td>
        </tr>

        <tr>
          <td><code>post-login</code></td>
          <td>Triggers after a user is authenticated but token hasn't issued.</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="MFA Notifications: When using SMS as a factor for Multi-factor Authentication (MFA) or to configure a custom provider.">
    <table>
      <thead>
        <tr>
          <th>Trigger</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>send-phone-message</code></td>
          <td>Triggers when using a custom provider to send the messages for the enrollment and the challenge process. Does not run social connection.</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Password reset: When a password reset request is initiated.">
    <table>
      <thead>
        <tr>
          <th>Trigger</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>post-change-password</code></td>
          <td>Triggers after a password is changed.  Does not run for Social connections.</td>
        </tr>

        <tr>
          <td><code>password-reset-post-challenge</code></td>
          <td>Triggers after the first challenge is completed and before the password is reset.</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Machine to Machine: When an application, instead of a user, is authenticated and authorized to use your APIs.">
    <table>
      <thead>
        <tr>
          <th>Trigger</th>
          <th>Description</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>credentials-exchange</code></td>
          <td>Triggers before an access token is returned.</td>
        </tr>
      </tbody>
    </table>
  </Accordion>
</AccordionGroup>

## Key benefits of Actions

### Improved developer experience

* When editing an Action within the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, you will have access to rich type information and inline documentation about what is possible within each trigger, which makes it easy to discover what capabilities each Trigger supports.
* An Action can be edited and tested without affecting the version that is currently serving production traffic.
* If an issue is found within an Action, it can be rolled back to a previous version.

### Reuse custom functions

* Create, manage, and share functions between Actions using [Actions Modules](/docs/customize/actions/modules/actions-modules-overview).

### Access to npm packages

* You can use nearly all [public `npm` packages](https://www.npmjs.com/) within Actions.

### Observability

* When Auth0 executes Actions, it captures key metrics about them and links them to [Auth0 Logs](/docs/deploy-monitor/logs).
* When debugging, use the [Actions Real-time Logs](/docs/customize/actions/actions-real-time-logs) feature.

### Multiple Actions on every trigger

* Every Action trigger supports multiple independent Actions.

## Get started

* [Write your first Action](/docs/customize/actions/write-your-first-action).
* Review the current [Action Coding Guidelines](/docs/customize/actions/action-coding-guidelines).
* Review the current [Actions Limitations](/docs/customize/actions/limitations).

## Learn more

* [Write Your First Action](/docs/customize/actions/write-your-first-action)
* [Explore Triggers](/docs/customize/actions/explore-triggers)
* [Actions Limitations](/docs/customize/actions/limitations)
* [Manage Versions](/docs/customize/actions/manage-versions)
* [Migrate from Actions Beta to Final](/docs/customize/actions/migrate/migrate-from-actions-beta-to-final)


# Actions Real-time Logs
Source: https://auth0.com/docs/customize/actions/actions-real-time-logs

Learn how to use the Auth0 Actions Real-time Logs.

The Actions Real-time Logs feature displays all logs in real-time for the custom code in your account. This includes all `console.log` output and exceptions. These logs are helpful while debugging your Actions, Custom Database scripts, and Custom Social Connections.

<Warning>
  When using the Actions Real-time Logs, be cautious about logging sensitive information. For example, the parameters functions received as an input for Actions, Custom Database Scripts, or Custom Social Connections, may contain explicit or implicit sensitive information. Logging complete objects may lead to the disclosure of sensitive information in the real-time logs.

  Auth0 strongly discourages such practices. **We suggest that you be aware of the objects that you log and ensure sensitive information is not logged, as well as avoiding logging any kind of sensitive information explicitly.**
</Warning>

## How to use

To view the real-time logs for your custom code:

1. Navigate to [Auth0 Dashboard > Monitoring > Actions Logs](https://manage.auth0.com/#/tenant/action-logs).
2. Wait until the stream is connected. Connectivity attempts automatically.
3. Once connected, log entries appear in the main panel as they occur.

<Frame>
  <img alt="Real-time action logs in dashboard" />
</Frame>

## Features

The Actions Real-time logs panel allows you to monitor system activity as it happens. This provides live feedback on Actions executed through the dashboard, making it easier to identify issues, confirm successful operations, or simply observe system behavior in real-time. See below for a detailed list of the current functionality available in this feature.

### Live log streaming

Log entries are streamed live as they are generated by Actions. As each Action is executed, its corresponding log entry appears in the log panel automatically, with no need to refresh the page.

### Connection status

The top of the panel displays the current connection status between your browser and the log stream. This helps you confirm whether logs are actively being received. Common statuses include:

<table>
  <thead>
    <tr>
      <th>Status</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Connecting To Log Stream...</td>
      <td>Attempting to establish a connection.</td>
    </tr>

    <tr>
      <td>CONNECTED</td>
      <td>Successfully connected and receiving logs.</td>
    </tr>

    <tr>
      <td>DISCONNECTED</td>
      <td>Not currently connected to the stream.</td>
    </tr>
  </tbody>
</table>

### Search functionality

Use the search bar at the top of the panel to filter the log entries. You can search by:

* Keywords or phrases
* Specific error codes
* Exact log messages

This is especially useful when scanning large volumes of logs for a specific Action or issue.

### Options menu (...)

Click the **Options** menu in the top-right corner of the log panel to access additional controls.

* **Local Time:** Toggles the timestamp display for log entries between the server's default time (often UTC) and the user's local browser time.
* **Download:** Allows you to download the currently displayed logs as a JSON file for offline analysis, sharing, or archival.
* **Clear Logs:** Clears all log entries currently visible in the display window. This does not delete logs from system storage, only your current view.

### Scroll to bottom

When new entries arrive and are out of view, a **Scroll to bottom** button appears in the log panel. Clicking this will jump you to the most recent log entry, ensuring you're always up-to-date with the latest activity.

## Debug an Action

The following example describes how to create a generic Hello World Action, run it, and use the Actions Real-time Logs to see the results.

1. Follow the instructions to [Write Your First Action](/docs/customize/actions/write-your-first-action) to write a Post Login Action using the code example below:

   ```javascript lines theme={null}
   /**
   * Handler that will be called during the execution of a PostLogin flow.
   *
   * @param {Event} event - Details about the user and the context in which they are logging in.
   * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
   */
   exports.onExecutePostLogin = async (event, api) => {
     console.log('Hello World!');
   };

   /**
   * Handler that will be invoked when this action is resuming after an external redirect. If your
   * onExecutePostLogin function does not perform a redirect, this function can be safely ignored.
   *
   * @param {Event} event - Details about the user and the context in which they are logging in.
   * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
   */
   // exports.onContinuePostLogin = async (event, api) => {
   // };
   ```

2. Open a new tab, navigate to Navigate to [Auth0 Dashboard > Monitoring > Actions Logs](https://manage.auth0.com/#/tenant/action-logs)

3. Once the stream is connected, switch to your Action Editor and run a test.

4. Your results should appear in real-time in your Actions Real-time Logs.

#### Supported statements

The following table outlines the JavaScript console statements supported by the real-time logging feature:

<table>
  <thead>
    <tr>
      <th>Statement</th>
      <th>Description</th>
      <th>Use Case</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>console.log()</code></td>
      <td>General-purpose logging of information.</td>
      <td>Basic informational messages, variable values.</td>
    </tr>

    <tr>
      <td><code>console.info()</code></td>
      <td>Informational messages highlighting application progress or state.</td>
      <td>Reporting successful operations, application milestones.</td>
    </tr>

    <tr>
      <td><code>console.warn()</code></td>
      <td>Indicates potential issues or unexpected situations that are not critical errors.</td>
      <td>Flagging non-critical problems, deprecated features.</td>
    </tr>

    <tr>
      <td><code>console.error()</code></td>
      <td>Reports errors that have occurred within the application.</td>
      <td>Indicating failures, exceptions, and critical issues.</td>
    </tr>

    <tr>
      <td><code>console.trace()</code></td>
      <td>Displays a stack trace, showing the sequence of function calls leading to the current point.</td>
      <td>Debugging complex call flows, understanding the origin of issues.</td>
    </tr>
  </tbody>
</table>

## Learn more

* [Write Your First Action](/docs/customize/actions/write-your-first-action)


# Templates for Actions
Source: https://auth0.com/docs/customize/actions/actions-templates

The Actions Template gallery offers our customers a wide variety of starter templates on their way to creating an action

The Actions Template gallery offers a variety of starter templates for creating an Action. These templates provide sample code covering various triggers and use cases, such as <Tooltip href="/docs/glossary?term=Multi-factor+Authentication">Multi-factor Authentication</Tooltip>, Access Control, and Profile Enrichment.

Templates provide starter code that you can modify and use as a building block as part of a trigger. Once you select a template for your specific use case, you can then customize the code to fit the individual needs of your application.

For a step-by-step guide on using Actions Templates, see [Write Your First Action](/docs/customize/actions/write-your-first-action).

<Callout icon="file-lines">
  The Actions templates are also available at: [https://github.com/auth0/opensource-marketplace](https://github.com/auth0/opensource-marketplace).
</Callout>

## Best Practices

<Callout icon="file-lines">
  Action Templates are designed for educational purposes only.

  These templates consist of incomplete code snippets, and should not be used in a production environment under any circumstances. Developers are responsible for securely developing and completing the Action Template before deploying to a production environment.
</Callout>

* Ensure that the templates are custom for your specific environment. As the code is incomplete, you must personalize and complete the samples before importing them into a production environment.
* Do not deploy a template without editing and completing it beforehand.
* Actions Templates often contain tags in the comments, which should not be modified or deleted.
* Always use the latest version of any `npm` package.
* Actions Templates target the latest Node.js versions by default. After creating a template, you can modify it to support additional Node.js version(s) as necessary.

Please review all [Actions Coding Guidelines](/docs/customize/actions/action-coding-guidelines) as they apply here as well.


# Explore Triggers
Source: https://auth0.com/docs/customize/actions/explore-triggers

Learn about triggers, which are events that automatically invokes an Action when a specific operation, such as a user logging in, occurs at runtime.

Triggers are points in the Auth0 process where Actions can be added for required customization. Multiple Actions can be placed in a Trigger, executing in sequence. Excluding the Custom Token Exchange, triggers can be synchronous (blocking) or asynchronous (non-blocking). Each trigger has specific Objects and APIs. They may differ based on your connection (such as <Tooltip href="/docs/glossary?term=passwordless">passwordless</Tooltip> connection).

To explore reference Objects and APIs for specific Actions for a trigger, select the trigger below, noting Auth0's definition of a [passwordless connection](/docs/authenticate/passwordless).

#### Signup and Login

When a user is added to a database or passwordless connection (Signup), or as part of a user's authentication transaction (Login).

<table>
  <thead>
    <tr>
      <th>Trigger</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>pre-user-registration</code></td>
      <td>Triggers before a user is created.</td>
    </tr>

    <tr>
      <td><code>post-user-registration</code></td>
      <td>Triggers asynchronously after a user is created.</td>
    </tr>

    <tr>
      <td><code>post-login</code></td>
      <td>Triggers after a user is authenticated but before a token is issued.</td>
    </tr>
  </tbody>
</table>

#### MFA Notifications

When using SMS as a factor for <Tooltip href="/docs/glossary?term=Multi-Factor+Authentication">Multi-Factor Authentication</Tooltip> (MFA) or to configure a custom provider.

<table>
  <thead>
    <tr>
      <th>Trigger</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>send-phone-message</code></td>
      <td>Triggers when using a custom provider to send the messages for the enrollment and the challenge process.</td>
    </tr>
  </tbody>
</table>

#### Password Reset

When a password reset request is initiated.

<table>
  <thead>
    <tr>
      <th>Trigger</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>post-change-password</code></td>
      <td>Triggers after a password is changed.</td>
    </tr>

    <tr>
      <td><code>password-reset-post-challenge</code></td>
      <td>Triggers after the first challenge is completed and before the password is reset.</td>
    </tr>
  </tbody>
</table>

#### Machine to Machine

When an application, instead of a user, is authenticated and authorized to use your APIs.

<table>
  <thead>
    <tr>
      <th>Trigger</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>credentials-exchange</code></td>
      <td>Triggers before an access token is returned.</td>
    </tr>
  </tbody>
</table>

### Custom Token Exchange

When a Custom Token Exchange Request is received to log a user in.

<table>
  <thead>
    <tr>
      <th>Trigger</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>custom-token-exchange</code></td>
      <td>Triggers at first step for the transaction, before the post-login trigger.</td>
    </tr>
  </tbody>
</table>


# Event Stream Triggers
Source: https://auth0.com/docs/customize/actions/explore-triggers/event-stream-triggers

Learn about the Event Stream Actions.

<Warning>
  **Event Stream Actions are currently available in Early Access**.

  To learn more about Auth0's product release cycle, review [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

Event Stream Actions are logic-based functions that execute asynchronously when specific events occur within your Auth0 tenant. These are non-blocking actions and won't impact the latency of your user's experience.

Each Event Stream Action is associated with an Event Stream, and listens for a pre-defined set of Event Types (for example, successful logins, password changes, or user deletions). When a subscribed event occurs, the Action is triggered. Unlike Login or Pre-Registration Actions, Event Stream Actions run in the background and do not affect the primary transaction of the user.

<Frame>
  <img alt="Diagram showing the TBD." />
</Frame>

These Actions are non-blocking (asynchronous), suscribed to a specific set of [Event Types](/docs/customize/events/event-types).

## Triggers

### Event Stream

The `event-stream` Actions are functions executed when subscribed Event Types happen.

#### References

* [Event object](/docs/customize/actions/explore-triggers/event-stream-triggers/event-stream-event-object): Provides context for both Event Stream message and Action execution.
* [API object](/docs/customize/actions/explore-triggers/event-stream-triggers/event-stream-api-object): Provides methods to modify the flow behavior.

## Use cases

### Synchronization

A event-stream Action can be used to communicate a particular event to an external service based on custom logic. The following Action demonstrates how to securely forward an event message to an external service using a stored API key.

```javascript lines theme={null}
/**
* Handler to be executed while processing events in an Event Stream.
* @param {Event} event - Details about the incoming event.
* @param {EventStreamAPI} api - Methods and utilities to define event stream processing.
*/
exports.onExecuteEventStream = async (event, api) => {
  const message = event.message;

  try {
    await fetch(event.secrets.URL, {
      method: 'POST',
      headers: {
        'X-API-Key': event.secrets.API_KEY,
      },
      body: JSON.stringify(message),
    });
  } catch (err) {
    throw new Error('External service failure');
  }

  return;
};
```

To learn more about writing Actions, read [Write Your First Action](/docs/customize/actions/write-your-first-action).

To learn more about creating an Event Stream, read [Create an Event Stream](/docs/customize/events/create-an-event-stream#create-an-event-stream-actions).


# Actions Triggers: event-stream - API Object
Source: https://auth0.com/docs/customize/actions/explore-triggers/event-stream-triggers/event-stream-api-object

Learn about the event-stream Action trigger's API object.

The API object for the event-stream Actions trigger includes:

## `api.cache`

\[Limited Early Access]
Store and retrieve data that persists across executions.

### `api.cache.delete(key)`

Delete a record describing a cached value at the supplied
key if it exists.

<ResponseField name="key" type="string">
  The key of the cache record to delete.
</ResponseField>

### `api.cache.get(key)`

Retrieve a record describing a cached value at the supplied key,
if it exists. If a record is found, the cached value can be found
at the `value` property of the returned object.

<ResponseField name="key" type="string">
  The key of the record stored in the cache.
</ResponseField>

### `api.cache.set(key, value, options)`

Store or update a string value in the cache at the specified key.

Values stored in this cache are scoped to the Trigger in which they
are set. They are subject to the [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations).

Values stored in this way will have lifetimes of *up to* the specified
`ttl` or `expires_at` values. If no lifetime is specified, a default of
lifetime of 24 hours will be used. Lifetimes may not exceed the maximum
duration listed at [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations).

**Important**: This cache is designed for short-lived, ephemeral data. Items may not be
available in later transactions even if they are within their supplied their lifetime.

<ResponseField name="key" type="string">
  The key of the record to be stored.
</ResponseField>

<ResponseField name="value" type="string">
  The value of the record to be stored.
</ResponseField>

<ResponseField name="options" type="cachesetoptions">
  Options for adjusting cache behavior.

  <Expandable title="options properties">
    <ResponseField name="expires_at" type="number">
      The absolute expiry time in milliseconds since the unix epoch.
      While cached records may be evicted earlier, they will
      never remain beyond the the supplied `expires_at`.

      *Note*: This value should not be supplied if a value was also
      provided for `ttl`. If both options are supplied, the
      earlier expiry of the two will be used.
    </ResponseField>

    <ResponseField name="ttl" type="number">
      The time-to-live value of this cache entry in milliseconds.
      While cached values may be evicted earlier, they will
      never remain beyond the the supplied `ttl`.

      *Note*: This value should not be supplied if a value was also
      provided for `expires_at`. If both options are supplied, the
      earlier expiry of the two will be used.
    </ResponseField>
  </Expandable>
</ResponseField>


# Actions Triggers: event-stream - Event Object
Source: https://auth0.com/docs/customize/actions/explore-triggers/event-stream-triggers/event-stream-event-object

Learn about the event-stream Action trigger's event object, which provides contextual information about the trigger execution.

The `event` object for the event-stream Actions trigger provides contextual information about the trigger execution.

## `event.message`

<ResponseField name="event.message" type="dictionary">
  \[Limited Early Access] The CloudEvent message containing all event properties.

  <Expandable title="message properties">
    <ResponseField name="id" type="string">
      Identifies the event.
    </ResponseField>

    <ResponseField name="type" type="string">
      Describes the type of event related to the originating occurrence.
    </ResponseField>

    <ResponseField name="data" type="dictionary">
      The event payload.
    </ResponseField>

    <ResponseField name="source" type="string">
      Identifies the context in which an event happened.
    </ResponseField>

    <ResponseField name="specversion" type="string">
      The version of the CloudEvents specification which the event uses.
    </ResponseField>

    <ResponseField name="time" type="string">
      Timestamp of when the occurrence happened. Must adhere to RFC 3339.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.secrets`

<ResponseField name="event.secrets" type="secrets">
  Secret values securely associated with this Action.
</ResponseField>


# Machine to Machine Triggers
Source: https://auth0.com/docs/customize/actions/explore-triggers/machine-to-machine-trigger

Learn about the Actions Machine to Machine Flow and the credentials-exchange Action trigger, which runs as part of the Machine to Machine Flow.

The Machine to Machine trigger runs when an <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> is being issued via the [Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow).

<Frame>
  <img alt="Diagram showing the Actions Machine to Machine Flow and when the triggers inside of it run." />
</Frame>

Actions in this flow are blocking (synchronous), which means they execute as part of a trigger's process and will prevent the rest of the Auth0 pipeline from running until the Action is complete.

## Triggers

### M2M / Client Credentials

The `credentials-exchange` trigger is a function executed before the access token is returned.

#### References

* [Event object](/docs/customize/actions/explore-triggers/machine-to-machine-trigger/credentials-exchange-event-object): Provides contextual information about the request for a client credentials exchange.
* [API object](/docs/customize/actions/explore-triggers/machine-to-machine-trigger/credentials-exchange-api-object): Provides methods for changing the behavior of the flow.

## Common use cases

### Access control

A credentials-exchange Action can be used to deny an access token based on custom logic.

```javascript lines theme={null}
/**
 * @param {Event} event - Details about client credentials grant request.
 * @param {CredentialsExchangeAPI} api - Interface whose methods can be used to change the behavior of client credentials grant.
 */
exports.onExecuteCredentialsExchange = async (event, api) => {
  if (event.request.geoip.continentCode === "NA") {
    api.access.deny('invalid_request', "Access from North America is not allowed.");
  }
};
```

### Add custom claims to the access token

A credentials-exchange Action can be used to add custom claims to an access token.

```javascript lines theme={null}
/**
 * @param {Event} event - Details about client credentials grant request.
 * @param {CredentialsExchangeAPI} api - Interface whose methods can be used to change the behavior of client credentials grant.
 */
exports.onExecuteCredentialsExchange = async (event, api) => {
  api.accessToken.setCustomClaim("https://my-api.exampleco.com/request-ip", event.request.ip);  
};
```

<Callout icon="file-lines">
  We strong recommend using namespaced custom claim in the form of a URI. To learn more about namespaced and non-namespaced custom claims, read [Create Custom Claims](/docs/secure/tokens/json-web-tokens/create-custom-claims).
</Callout>


# Actions Triggers: credentials-exchange - API Object
Source: https://auth0.com/docs/customize/actions/explore-triggers/machine-to-machine-trigger/credentials-exchange-api-object

Learn about the credentials-exchange Action trigger's API object.

The API object for the credentials-exchange Actions trigger includes:

## `api.access`

Control availability to the access token.

### `api.access.deny(code, reason)`

Mark the current token exchange as denied.

<ResponseField name="code" type="string">
  The protocol-specific error code justifying the rejection of the login.

  Allowed values: `invalid_scope`, `invalid_request`, `server_error`
</ResponseField>

<ResponseField name="reason" type="string">
  A human-readable explanation for rejecting the access token grant.
</ResponseField>

## `api.accessToken`

Request changes to the access token being issued.

### `api.accessToken.setCustomClaim(key, value)`

Set a custom claim on the Access Token that will be issed.

<ResponseField name="key" type="string">
  Name of the claim (note that this may need to be a fully-qualified url).
</ResponseField>

<ResponseField name="value" type="unknown">
  The value of the claim.
</ResponseField>

## `api.cache`

Make changes to the cache.

### `api.cache.delete(key)`

Delete a record describing a cached value at the supplied
key if it exists.

<ResponseField name="key" type="string">
  The key of the cache record to delete.
</ResponseField>

### `api.cache.get(key)`

Retrieve a record describing a cached value at the supplied key,
if it exists. If a record is found, the cached value can be found
at the `value` property of the returned object.

<ResponseField name="key" type="string">
  The key of the record stored in the cache.
</ResponseField>

### `api.cache.set(key, value, options)`

Store or update a string value in the cache at the specified key.

Values stored in this cache are scoped to the Trigger in which they
are set. They are subject to the [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations).

Values stored in this way will have lifetimes of *up to* the specified
`ttl` or `expires_at` values. If no lifetime is specified, a default of
lifetime of 24 hours will be used. Lifetimes may not exceed the maximum
duration listed at [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations).

**Important**: This cache is designed for short-lived, ephemeral data. Items may not be
available in later transactions even if they are within their supplied their lifetime.

<ResponseField name="key" type="string">
  The key of the record to be stored.
</ResponseField>

<ResponseField name="value" type="string">
  The value of the record to be stored.
</ResponseField>

<ResponseField name="options" type="cachesetoptions">
  Options for adjusting cache behavior.

  <Expandable title="options properties">
    <ResponseField name="expires_at" type="number">
      The absolute expiry time in milliseconds since the unix epoch.
      While cached records may be evicted earlier, they will
      never remain beyond the the supplied `expires_at`.

      *Note*: This value should not be supplied if a value was also
      provided for `ttl`. If both options are supplied, the
      earlier expiry of the two will be used.
    </ResponseField>

    <ResponseField name="ttl" type="number">
      The time-to-live value of this cache entry in milliseconds.
      While cached values may be evicted earlier, they will
      never remain beyond the the supplied `ttl`.

      *Note*: This value should not be supplied if a value was also
      provided for `expires_at`. If both options are supplied, the
      earlier expiry of the two will be used.
    </ResponseField>
  </Expandable>
</ResponseField>


# Actions Triggers: credentials-exchange - Event Object
Source: https://auth0.com/docs/customize/actions/explore-triggers/machine-to-machine-trigger/credentials-exchange-event-object

Learn about the credentials-exchange Action trigger's event object, which provides contextual information about the trigger execution.

The `event` object for the credentials-exchange Actions trigger provides contextual information about the trigger execution.

## `event.accessToken`

<ResponseField name="event.accessToken" type="dictionary">
  Information about the access token to be issued.

  <Expandable title="accessToken properties">
    <ResponseField name="customClaims" type="dictionary" />

    <ResponseField name="scope" type="array of strings" />
  </Expandable>
</ResponseField>

## `event.client`

<ResponseField name="event.client" type="dictionary">
  Information about the Client used during this token exchange.

  <Expandable title="client properties">
    <ResponseField name="client_id" type="string">
      The client id of the application the user is logging in to.
    </ResponseField>

    <ResponseField name="metadata" type="dictionary">
      An object for holding other application properties.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the application (as defined in the Dashboard).
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.custom_domain`

<ResponseField name="event.custom_domain" type="dictionary">
  Details about the custom domain associated with the current transaction.

  <Expandable title="custom_domain properties">
    <ResponseField name="domain" type="string">
      The custom domain name.
    </ResponseField>

    <ResponseField name="domain_metadata" type="dictionary">
      Custom domain metadata as key-value pairs.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.organization`

<ResponseField name="event.organization" type="dictionary">
  Details about the Organization associated with the current transaction.

  <Expandable title="organization properties">
    <ResponseField name="id" type="string">
      The Organization identifier.
    </ResponseField>

    <ResponseField name="display_name" type="string">
      The friendly name of the Organization.
    </ResponseField>

    <ResponseField name="metadata" type="dictionary">
      Metadata associated with the Organization.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the Organization.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.request`

<ResponseField name="event.request" type="dictionary">
  Details about the request that initiated the transaction.

  <Expandable title="request properties">
    <ResponseField name="body" type="dictionary">
      The body of the POST request. This data will only be available during refresh token, Client Credential Exchange flows and PreUserRegistration Action.
    </ResponseField>

    <ResponseField name="geoip" type="dictionary">
      <Expandable title="geoip properties">
        <ResponseField name="cityName" type="string" />

        <ResponseField name="continentCode" type="string" />

        <ResponseField name="countryCode" type="string" />

        <ResponseField name="countryCode3" type="string" />

        <ResponseField name="countryName" type="string" />

        <ResponseField name="latitude" type="number" />

        <ResponseField name="longitude" type="number" />

        <ResponseField name="subdivisionCode" type="string" />

        <ResponseField name="subdivisionName" type="string" />

        <ResponseField name="timeZone" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="hostname" type="string">
      The hostname that is being used for the authentication flow.
    </ResponseField>

    <ResponseField name="ip" type="string">
      The originating IP address of the request.
    </ResponseField>

    <ResponseField name="language" type="string">
      The language requested by the browser.
    </ResponseField>

    <ResponseField name="method" type="string">
      The HTTP method used for the request
    </ResponseField>

    <ResponseField name="user_agent" type="string">
      The value of the `User-Agent` header received when initiating the transaction.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.resource_server`

<ResponseField name="event.resource_server" type="object">
  Information about the Resource Server that is issuing the access token.

  <Expandable title="resource_server properties">
    <ResponseField name="identifier" type="string">
      The identifier of the resource server. For example: `https://your-api.example.com`.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.tenant`

<ResponseField name="event.tenant" type="object">
  Information about the Tenant used during this token exchange.

  <Expandable title="tenant properties">
    <ResponseField name="id" type="string">
      The name of the tenant.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.transaction`

<ResponseField name="event.transaction" type="object">
  Information about the Credentials Exchange transaction.

  <Expandable title="transaction properties">
    <ResponseField name="correlation_id" type="string">
      Correlation ID can be provided in the initial authentication request when the application redirects to Universal Login. You can use value to correlate logs and requests from your Action code with the user flow.
    </ResponseField>

    <ResponseField name="requested_scopes" type="array of strings">
      The scopes specified (if any) when requesting the access token.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.secrets`

<ResponseField name="event.secrets" type="secrets">
  Secret values securely associated with this Action.
</ResponseField>


# MFA Notifications Triggers
Source: https://auth0.com/docs/customize/actions/explore-triggers/mfa-notifications-trigger

Learn about Action's Send Phone Message flow and the send-phone-message Action trigger, which runs for the enrollment and challenge process if you have used SMS as a factor for Multi-factor Authentication (MFA).

The Send Phone Message trigger allows you to execute code when using SMS/Voice as a factor for [Multi-factor Authentication (MFA)](/docs/secure/multi-factor-authentication). When using a [custom provider](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-sms-voice-notifications-mfa#custom-phone-messaging-providers) to send the messages, this flow's `send-phone-message` trigger is required to configure your custom provider.

<Frame>
  <img alt="Diagram of the Actions Send Phone Message Flow." />
</Frame>

Actions in this flow are blocking (synchronous), which means they execute as part of a trigger's process and will prevent the rest of the Auth0 pipeline from running until the Action is complete.

## Triggers

### Send Phone Message

The `send-phone-message` trigger will run for the enrollment process and the challenge process (`event.message_options.action`). It will also run for the `voice` message type when using the New experience for <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> (`event.message_options.message_type === 'voice'`).

#### References

* [Event object](/docs/customize/actions/explore-triggers/mfa-notifications-trigger/send-phone-message-event-object): Provides contextual information about the message to be sent and the user to be challenged or enrolled.
* [API object](/docs/customize/actions/explore-triggers/mfa-notifications-trigger/send-phone-message-api-object): Provides methods for changing the behavior of the flow.

## Common use cases

### Use a custom SMS provider

```javascript lines theme={null}
const AWS = require("aws-sdk");

/**
 * Handler that will be called during the execution of a SendPhoneMessage flow.
 *
 * @param {Event} event - Details about the user and the context in which they are logging in.
 */
exports.onExecuteSendPhoneMessage = async (event) => {
  const text = event.message_options.text;
  const recipient = event.message_options.recipient;

  const awsSNS = new AWS.SNS({
    apiVersion: "2010-03-31",
    region: event.secrets.AWS_REGION,
    credentials: new AWS.Credentials(event.secrets.AWS_ACCESS_KEY_ID, event.secrets.AWS_SECRET_ACCESS_KEY)
  });

  const params = { Message: text, PhoneNumber: recipient };

  return awsSNS
    .publish(params)
    .promise();
};
```

<Callout icon="file-lines">
  For this Action to execute properly, the Action must contain secrets named `AWS_REGION`, `AWS_ACCESS_KEY_ID`, and `AWS_SECRET_ACCESS_KEY`, and must have a dependency on the `aws-sdk` NPM package.
</Callout>


# Actions Triggers: send-phone-message - API Object
Source: https://auth0.com/docs/customize/actions/explore-triggers/mfa-notifications-trigger/send-phone-message-api-object

Learn about the send-phone-message Action trigger's API object.

The API object for the send-phone-message Actions trigger includes:

## `api.cache`

Store and retrieve data that persists across executions.

### `api.cache.delete(key)`

Delete a record describing a cached value at the supplied
key if it exists.

<ResponseField name="key" type="string">
  The key of the cache record to delete.
</ResponseField>

### `api.cache.get(key)`

Retrieve a record describing a cached value at the supplied key,
if it exists. If a record is found, the cached value can be found
at the `value` property of the returned object.

<ResponseField name="key" type="string">
  The key of the record stored in the cache.
</ResponseField>

### `api.cache.set(key, value, options)`

Store or update a string value in the cache at the specified key.

Values stored in this cache are scoped to the Trigger in which they
are set. They are subject to the [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations).

Values stored in this way will have lifetimes of *up to* the specified
`ttl` or `expires_at` values. If no lifetime is specified, a default of
lifetime of 24 hours will be used. Lifetimes may not exceed the maximum
duration listed at [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations).

**Important**: This cache is designed for short-lived, ephemeral data. Items may not be
available in later transactions even if they are within their supplied their lifetime.

<ResponseField name="key" type="string">
  The key of the record to be stored.
</ResponseField>

<ResponseField name="value" type="string">
  The value of the record to be stored.
</ResponseField>

<ResponseField name="options" type="cachesetoptions">
  Options for adjusting cache behavior.

  <Expandable title="options properties">
    <ResponseField name="expires_at" type="number">
      The absolute expiry time in milliseconds since the unix epoch.
      While cached records may be evicted earlier, they will
      never remain beyond the the supplied `expires_at`.

      *Note*: This value should not be supplied if a value was also
      provided for `ttl`. If both options are supplied, the
      earlier expiry of the two will be used.
    </ResponseField>

    <ResponseField name="ttl" type="number">
      The time-to-live value of this cache entry in milliseconds.
      While cached values may be evicted earlier, they will
      never remain beyond the the supplied `ttl`.

      *Note*: This value should not be supplied if a value was also
      provided for `expires_at`. If both options are supplied, the
      earlier expiry of the two will be used.
    </ResponseField>
  </Expandable>
</ResponseField>


# Actions Triggers: send-phone-message - Event Object
Source: https://auth0.com/docs/customize/actions/explore-triggers/mfa-notifications-trigger/send-phone-message-event-object

Learn about the send-phone-message Action trigger's event object, which provides contextual information about the trigger execution.

The `event` object for the send-phone-message Actions trigger provides contextual information about the trigger execution.

## `event.client`

<ResponseField name="event.client" type="dictionary">
  Information about the Client with which this transaction was initiated.

  <Expandable title="client properties">
    <ResponseField name="client_id" type="string">
      The client id of the application the user is logging in to.
    </ResponseField>

    <ResponseField name="metadata" type="dictionary">
      An object for holding other application properties.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the application (as defined in the Dashboard).
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.custom_domain`

<ResponseField name="event.custom_domain" type="dictionary">
  Details about the custom domain associated with the current transaction.

  <Expandable title="custom_domain properties">
    <ResponseField name="domain" type="string">
      The custom domain name.
    </ResponseField>

    <ResponseField name="domain_metadata" type="dictionary">
      Custom domain metadata as key-value pairs.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.message_options`

<ResponseField name="event.message_options" type="object">
  Details about the message that is sent to the user.

  <Expandable title="message_options properties">
    <ResponseField name="action" type="string">
      The flow that triggered this action.

      Allowed values: `enrollment`, `second-factor-authentication`
    </ResponseField>

    <ResponseField name="code" type="string">
      One-time password that the user needs to use to enter in the form.
    </ResponseField>

    <ResponseField name="message_type" type="string">
      How the message will be delivered, either by 'sms' or 'voice'.

      Allowed values: `sms`, `voice`
    </ResponseField>

    <ResponseField name="recipient" type="string">
      Phone number where the message will be sent.
    </ResponseField>

    <ResponseField name="text" type="string">
      Content of the message to be sent.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.request`

<ResponseField name="event.request" type="dictionary">
  Details about the request that initiated the transaction.

  <Expandable title="request properties">
    <ResponseField name="geoip" type="dictionary">
      <Expandable title="geoip properties">
        <ResponseField name="cityName" type="string" />

        <ResponseField name="continentCode" type="string" />

        <ResponseField name="countryCode" type="string" />

        <ResponseField name="countryCode3" type="string" />

        <ResponseField name="countryName" type="string" />

        <ResponseField name="latitude" type="number" />

        <ResponseField name="longitude" type="number" />

        <ResponseField name="subdivisionCode" type="string" />

        <ResponseField name="subdivisionName" type="string" />

        <ResponseField name="timeZone" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="hostname" type="string">
      The hostname that is being used for the authentication flow.
    </ResponseField>

    <ResponseField name="ip" type="string">
      The originating IP address of the request.
    </ResponseField>

    <ResponseField name="language" type="string">
      The language requested by the browser.
    </ResponseField>

    <ResponseField name="method" type="string">
      The HTTP method used for the request
    </ResponseField>

    <ResponseField name="user_agent" type="string">
      The value of the `User-Agent` header received when initiating the transaction.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.security_context`

<ResponseField name="event.security_context" type="object">
  An object containing fingerprint signatures. This will be available only if the client is using cloudflare. The JA3/JA4 fingerprint can be null or empty in some cases. The most common case is for HTTP requests because JA3 and JA4 are calculated in TLS. It can also be empty due to the Worker sending requests within the same zone or to a zone that is not proxied (or a third party).

  <Expandable title="security_context properties">
    <ResponseField name="ja3" type="string">
      JA3 fingerprint signature. This will be available only if the client is using a TLS connection.
    </ResponseField>

    <ResponseField name="ja4" type="string">
      JA4 fingerprint signature. This will be available only if the client is using a TLS connection.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.tenant`

<ResponseField name="event.tenant" type="object">
  Details about the Tenant associated with the current transaction.

  <Expandable title="tenant properties">
    <ResponseField name="id" type="string">
      The name of the tenant.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.transaction`

<ResponseField name="event.transaction" type="object">
  Details about the current transaction.

  <Expandable title="transaction properties">
    <ResponseField name="correlation_id" type="string">
      Correlation ID can be provided in the initial authentication request when the application redirects to Universal Login. You can use value to correlate logs and requests from your Action code with the user flow.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.user`

<ResponseField name="event.user" type="dictionary">
  An object describing the user on whose behalf the current transaction was initiated.

  <Expandable title="user properties">
    <ResponseField name="app_metadata" type="dictionary">
      Custom fields that store info about a user that influences the user's access, such as support plan, security roles, or access control groups.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Timestamp indicating when the user profile was first created.
    </ResponseField>

    <ResponseField name="email" type="string">
      (unique) User's email address.
    </ResponseField>

    <ResponseField name="email_verified" type="boolean">
      Indicates whether the user has verified their email address.
    </ResponseField>

    <ResponseField name="family_name" type="string">
      User's family name.
    </ResponseField>

    <ResponseField name="given_name" type="string">
      User's given name.
    </ResponseField>

    <ResponseField name="last_password_reset" type="string">
      Timestamp indicating the last time the user's password was reset/changed. At user creation, this field does not exist. This property is only available for Database connections.
    </ResponseField>

    <ResponseField name="name" type="string">
      User's full name.
    </ResponseField>

    <ResponseField name="nickname" type="string">
      User's nickname.
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      User's phone number.
    </ResponseField>

    <ResponseField name="phone_verified" type="boolean">
      Indicates whether the user has verified their phone number.
    </ResponseField>

    <ResponseField name="picture" type="string">
      URL pointing to the [user's profile picture](https://auth0.com/docs/users/change-user-picture).
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      Timestamp indicating when the user's profile was last updated/modified.
    </ResponseField>

    <ResponseField name="user_id" type="string">
      (unique) User's unique identifier.
    </ResponseField>

    <ResponseField name="user_metadata" type="dictionary">
      Custom fields that store info about a user that does not impact what they can or cannot access, such as work address, home address, or user preferences.
    </ResponseField>

    <ResponseField name="username" type="string">
      (unique) User's username.
    </ResponseField>

    <ResponseField name="identities" type="array of objects">
      Contains info retrieved from the identity provider with which the user originally authenticates. Users may also link their profile to multiple identity providers; those identities will then also appear in this array. The contents of an individual identity provider object varies by provider.

      <Expandable title="identities properties">
        <ResponseField name="connection" type="string">
          Name of the Auth0 connection used to authenticate the user.
        </ResponseField>

        <ResponseField name="isSocial" type="boolean">
          Indicates whether the connection is a social one.
        </ResponseField>

        <ResponseField name="profileData" type="dictionary">
          User information associated with the connection. When profiles are linked, it is populated with the associated user info for secondary accounts.
        </ResponseField>

        <ResponseField name="provider" type="string">
          Name of the entity that is authenticating the user, such as Facebook, Google, SAML, or your own provider.
        </ResponseField>

        <ResponseField name="user_id" type="string">
          User's unique identifier for this connection/provider.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.secrets`

<ResponseField name="event.secrets" type="secrets">
  Secret values securely associated with this Action.
</ResponseField>


# Password Reset Triggers
Source: https://auth0.com/docs/customize/actions/explore-triggers/password-reset-triggers

Learn about the Actions Password Reset Flow, which is executed after a user completes the first challenge but before the user sets a password.

The Password Reset triggers run during the password reset process when a user completes the first challenge, typically a link to the [user's email](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-email-authenticators), but before a new password is set. You can use this to challenge a user with an additional <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA) factor or to redirect the user to an external site, such as a third-party verifier.

After verification, users can provide the new password for their account.

<Frame>
  <img alt="To use the Password Reset Flow, navigate to Dashboard > Actions > Flows " />
</Frame>

Actions in this flow are blocking (synchronous), which means they execute as part of a trigger's process and will prevent the rest of the Auth0 pipeline from running until the Action is complete.

<Callout icon="file-lines">
  In order for these Actions to run properly, you must have Universal Login enabled. These Actions cannot be triggered when using Classic Login.
</Callout>

## Triggers

### PostChallenge

The `post-challenge` trigger is a function that executes after a user completes the first password reset challenge, typically an email magic link. You can create up to four Actions in your tenant that leverage the `post-challenge` trigger.

#### References

* [Event object](/docs/customize/actions/explore-triggers/password-reset-triggers/post-challenge-trigger/post-challenge-event-object): Provides contextual information about a single user logging in via Auth0.
* [API object](/docs/customize/actions/explore-triggers/password-reset-triggers/post-challenge-trigger/post-challenge-api-object): Provides methods for changing the behavior of the flow.

## Limitations

The Password Reset Flow does not support [Active Directory/LDAP connections](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap).

## Common use cases

### Secure password reset with additional MFA factors

A `password-reset` / `post-challenge` Actions can issue an MFA challenge after the user completes the first challenge. For example, you can issue a WebAuthn-based challenge as a secondary factor if your tenant has WebAuthN enabled as a factor.

```javascript lines theme={null}
/**@type {PasswordResetPostChallengeAction}**/
module.exports.onExecutePostChallenge = async (event, api) => {
  const enrolledFactors = event.user.enrolledFactors.map((x) => ({
    type: x.type
  }));
  api.authentication.challengeWith({ type: 'webauthn-roaming' }, { additionalFactors: enrolledFactors });
};
```

### Redirect users to a third-party application

In addition to an MFA challenge, you can also try adding a redirect in the custom Action, for example, to a third-party verifier or risk assessor.

```javascript lines theme={null}
/** @type {PasswordResetPostChallengeAction}
 * This sample action redirects the user to an example app
 * and then continues the action after the redirect to challenge
 * the user with an MFA factor
 */

module.exports.onExecutePostChallenge = async (event, api) => {
  // Send the user to https://my-app.example.com
  api.redirect.sendUserTo('https://my-app.example.com');
};

module.exports.onContinuePostChallenge = async (event, api) => {
  const enrolledFactors = event.user.enrolledFactors.map((x) => ({
    type: x.type
  }));

  // Challenge the user with email otp OR another enrolled factor
  api.authentication.challengeWith({ type: 'email' }, { additionalFactors: enrolledFactors });

  // Example of how to challenge the user with multiple options
  // in this case email otp OR sms otp
  // api.authentication.challengeWithAny([{ type: 'email' }, { type: 'sms' }]);
};
```

The Actions pipeline is not active while Auth0 redirects the user. Once the user continues the Auth0 login process, the Actions pipeline resumes. Actions that were executed prior to the redirect are not executed again. To learn more, review [Redirect with Actions](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/redirect-with-actions).


# Post-challenge trigger
Source: https://auth0.com/docs/customize/actions/explore-triggers/password-reset-triggers/post-challenge-trigger

post-challenge-trigger

See the articles below for more information on Post-challenge triggers.

* [Actions Triggers: post-challenge - Event Object](/docs/customize/actions/explore-triggers/password-reset-triggers/post-challenge-trigger/post-challenge-event-object)
* [Actions Triggers: post-challenge - API Object](/docs/customize/actions/explore-triggers/password-reset-triggers/post-challenge-trigger/post-challenge-api-object)


# Actions Triggers: password-reset-post-challenge - API Object
Source: https://auth0.com/docs/customize/actions/explore-triggers/password-reset-triggers/post-challenge-trigger/post-challenge-api-object

Learn about the password-reset-post-challenge Action trigger's API object.

The API object for the password-reset-post-challenge Actions trigger includes:

## `api.access`

Modify the access of the user that is attempting to reset their password.

### `api.access.deny(reason)`

Mark the current password reset attempt as denied. This will prevent the end-user from completing
the password reset flow. This will *NOT* cancel other user-related side-effects
requested by this Action. The password reset flow will immediately stop following the
completion of this action and no further Actions will be executed.

<ResponseField name="reason" type="string">
  A human-readable explanation for rejecting the password reset. This may be presented
  directly in end-user interfaces.
</ResponseField>

## `api.authentication`

Request changes to the authentication state of the current user's session.

### `api.authentication.challengeWith(factor, options)`

Request a challenge for multifactor authentication using the supplied factor and optional additional factors.

When a multifactor challenge is requested, subsequent Actions will not be run until that challenge has been
fulfilled by the user. A user will have satisfied the challenge in any of the following situations:

1. They successfully complete the challenge for the default factor.
2. They successfully complete the challenge for any of the optional factors described in `additionalFactors`.

If any of the factors requested has already been challenged successfully in the current transaction, it will
be ignored.

If a factor is requested is not enabled on the tenant, it will be ignored. If a factor is requested that the user
has not enrolled, it will be ignored. If none of the requested factors is enabled or enrolled, the authentication
transaction will fail (i.e. login will not complete).

<Note>
  This method will result in a factor challenge screen being shown if the user has not already satisfied
  the requirements of the challenge. If `additionalFactors` are supplied, the user will have the option to
  select another factor if they choose to.
</Note>

<ResponseField name="factor" type="factorselector">
  An object describing the type of factor its options that should be used for the initial challenge.

  <Expandable title="factor properties">
    <ResponseField name="type" type="string">
      A type of authentication factor such as `push-notification`, `phone`, `email`, `otp`, `webauthn-roaming`, `webauthn-platform`, and `recovery-code`.

      Allowed values: `otp`, `email`, `webauthn-platform`, `webauthn-roaming`, `recovery-code`
    </ResponseField>

    <ResponseField name="options" type="dictionary">
      Additional options for configuring a factor of a given type.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="options" type="challengewithoptions">
  Additional options which can also specify `additionalFactors` as a property.

  <Expandable title="options properties">
    <ResponseField name="additionalFactors" type="array of objects" />
  </Expandable>
</ResponseField>

### `api.authentication.challengeWithAny(factors)`

Request a challenge for multifactor authentication using any of the supplied factors (showing a factor selection
screen first).

When a multifactor challenge is requested, subsequent Actions will not be run until that challenge has been
fulfilled by the user. A user will have satisfied the challenge in any of the following situations:

1. They successfully complete the challenge for any of the factors.

If any of the factors requested has already been challenged successfully in the current transaction, it will
be ignored.

If a factor is requested is not enabled on the tenant, it will be ignored. If a factor is requested that the user
has not enrolled, it will be ignored. If none of the requested factors is enabled or enrolled, the authentication
transaction will fail (i.e. login will not complete).

<Note>
  This method will result in the factor selector screen being shown if the user has not already satisfied
  the requirements of the challenge. If there is a preferred factor, the `api.authentication.challengeWith()` method
  is preferred. The factor selector screen will not be shown if only one factor is passed in or is valid.
</Note>

<ResponseField name="factors" type="array of objects">
  An array of factors.
</ResponseField>

## `api.redirect`

Configure and initiate external redirects.

### `api.redirect.encodeToken(options)`

Create a session token suitable for using as a query string parameter redirect target (via `sendUserTo`)
that contains data whose authenticity must be provable by the target endpoint. The target endpoint
can verify the authenticity and integrity of the data by checking the JWT's signature
using a shared secret.

The shared secret should be stored as a **secret** of the Action and will be readable at
`event.secrets['<secret_name>']`.

<ResponseField name="options" type="tokencreationoptions">
  Configure how sensitive data is encoded into the query parameters of the
  resulting url.

  <Expandable title="options properties">
    <ResponseField name="expiresInSeconds" type="number">
      Number of seconds before this token will expire
    </ResponseField>

    <ResponseField name="payload" type="dictionary">
      The data intended to be passed to the target of the redirect and whose authenticity
      and integrity must be provable.
    </ResponseField>

    <ResponseField name="secret" type="string">
      A secret that will be used to sign a JWT that is shared with the redirect target. The
      secret value should be stored as a **secret** and retrieved using
      `event.secrets['<secret_name>']`.
    </ResponseField>
  </Expandable>
</ResponseField>

### `api.redirect.sendUserTo(url, options)`

Cause the password reset pipeline to trigger a browser redirect to the target `url` immediately after
this action completes. The `createUrl` helper method is provided to simplify encoding
data as a query parameter in the target `url` such that the data's authenticity and
integrity can be verified by the target endpoint.

<ResponseField name="url" type="string" />

<ResponseField name="options" type="sendusertooptions">
  <Expandable title="options properties">
    <ResponseField name="query" type="dictionary">
      An object representing additional query string parameters that should be appended to
      the redirect URL.
    </ResponseField>
  </Expandable>
</ResponseField>

### `api.redirect.validateToken(options)`

Retrieve the data encoded in a JWT token passed to the `/continue` endpoint while verifying
the authenticity and integrity of that data.

<ResponseField name="options" type="validatesessiontokenoptions">
  Options for retrieving the data encoded in a JWT token passed to the
  `/continue` endpoint following a rediret.

  <Expandable title="options properties">
    <ResponseField name="secret" type="string" />

    <ResponseField name="tokenParameterName" type="string">
      The name of the query or body parameter that was sent to the /continue endpoint.
    </ResponseField>
  </Expandable>
</ResponseField>

## `api.cache`

Make changes to the cache.

### `api.cache.delete(key)`

Delete a record describing a cached value at the supplied
key if it exists.

<ResponseField name="key" type="string">
  The key of the cache record to delete.
</ResponseField>

### `api.cache.get(key)`

Retrieve a record describing a cached value at the supplied key,
if it exists. If a record is found, the cached value can be found
at the `value` property of the returned object.

<ResponseField name="key" type="string">
  The key of the record stored in the cache.
</ResponseField>

### `api.cache.set(key, value, options)`

Store or update a string value in the cache at the specified key.

Values stored in this cache are scoped to the Trigger in which they
are set. They are subject to the [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations).

Values stored in this way will have lifetimes of *up to* the specified
`ttl` or `expires_at` values. If no lifetime is specified, a default of
lifetime of 24 hours will be used. Lifetimes may not exceed the maximum
duration listed at [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations).

**Important**: This cache is designed for short-lived, ephemeral data. Items may not be
available in later transactions even if they are within their supplied their lifetime.

<ResponseField name="key" type="string">
  The key of the record to be stored.
</ResponseField>

<ResponseField name="value" type="string">
  The value of the record to be stored.
</ResponseField>

<ResponseField name="options" type="cachesetoptions">
  Options for adjusting cache behavior.

  <Expandable title="options properties">
    <ResponseField name="expires_at" type="number">
      The absolute expiry time in milliseconds since the unix epoch.
      While cached records may be evicted earlier, they will
      never remain beyond the the supplied `expires_at`.

      *Note*: This value should not be supplied if a value was also
      provided for `ttl`. If both options are supplied, the
      earlier expiry of the two will be used.
    </ResponseField>

    <ResponseField name="ttl" type="number">
      The time-to-live value of this cache entry in milliseconds.
      While cached values may be evicted earlier, they will
      never remain beyond the the supplied `ttl`.

      *Note*: This value should not be supplied if a value was also
      provided for `expires_at`. If both options are supplied, the
      earlier expiry of the two will be used.
    </ResponseField>
  </Expandable>
</ResponseField>

## `api.prompt`

Renders a custom prompt.

### `api.prompt.render(promptId, promptOptions)`

Renders a custom prompt.

<ResponseField name="promptId" type="string">
  The prompt ID.
</ResponseField>

<ResponseField name="promptOptions" type="promptoptions">
  The render options.

  <Expandable title="promptOptions properties">
    <ResponseField name="fields" type="dictionary">
      Key-value pairs to populate field values (client-side).
    </ResponseField>

    <ResponseField name="vars" type="dictionary">
      Key-value pairs to inject variables (server-side).
    </ResponseField>
  </Expandable>
</ResponseField>

## `api.transaction`

Configure the transaction.

### `api.transaction.setResultUrl(url, options)`

Set the URL that the user should be redirected to after the password reset.

<ResponseField name="url" type="string">
  The URL to redirect the user to.
</ResponseField>

<ResponseField name="options" type="resulturloptions">
  <Expandable title="options properties">
    <ResponseField name="query" type="dictionary">
      The query parameters to include in the URL.
    </ResponseField>
  </Expandable>
</ResponseField>


# Actions Triggers: password-reset-post-challenge - Event Object
Source: https://auth0.com/docs/customize/actions/explore-triggers/password-reset-triggers/post-challenge-trigger/post-challenge-event-object

Learn about the password-reset-post-challenge Action trigger's event object, which provides contextual information about the trigger execution.

The `event` object for the password-reset-post-challenge Actions trigger provides contextual information about the trigger execution.

## `event.authentication`

<ResponseField name="event.authentication" type="dictionary">
  Details about authentication obtained during the password reset flow.

  <Expandable title="authentication properties">
    <ResponseField name="methods" type="array of objects">
      Contains the authentication methods a user has completed during their session.

      Array elements can be one of the following schemas:

      <Tabs>
        <Tab title="First Factor">
          <ResponseField name="name" type="string">
            The name of the first factor that was completed. Values include the following:

            * `federated` A social or enterprise connection was used to authenticate the user as the first factor.
            * `pwd` A password was used to authenticate a database connection user as the first factor.
            * `passkey` A passkey was used to authenticate a database connection user as the first factor.
            * `sms` A Passwordless SMS connection was used to authenticate the user as the first factor.
            * `email` A Passwordless Email connection was used to authenticate the user as the first factor or verify email for password reset.
            * `phone_number` A phone number was used for password reset.
            * `mock` Used for internal testing.
            * May also be a URL denoting a custom authentication method (as second or later factor).
          </ResponseField>

          <ResponseField name="timestamp" type="string" />
        </Tab>

        <Tab title="Multi-factor Authentication">
          <ResponseField name="name" type="string">
            The user completed multi-factor authentication (second or later factors).

            Allowed values: `mfa`
          </ResponseField>

          <ResponseField name="timestamp" type="string" />
        </Tab>
      </Tabs>
    </ResponseField>

    <ResponseField name="riskAssessment" type="dictionary">
      Supplemental risk assessment. This is available only if the Akamai Integration is enabled and Akamai forwards the headers for the transaction.

      <Expandable title="riskAssessment properties">
        <ResponseField name="supplemental" type="dictionary">
          Supplemental signals sent from third party providers to assist in risk assessments.

          <Expandable title="supplemental properties">
            <ResponseField name="akamai" type="dictionary">
              \[Limited Early Access] Supplemental risk assessment. This is available only if Akamai Account Protector is enabled and Akamai forwards the headers for the transaction.

              <Expandable title="akamai properties">
                <ResponseField name="akamaiBot" type="object">
                  The bot detection results as forwarded by Akamai Bot Manager.

                  <Expandable title="akamaiBot properties">
                    <ResponseField name="type" type="string">
                      The type of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="action" type="string">
                      The action of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="botCategory" type="array of strings">
                      The bot category of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="botScore" type="number">
                      The bot score of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="botScoreResponseSegment" type="string">
                      The bot score response segment of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="botnetId" type="string">
                      The botnet ID of the Akamai bot manager results.
                    </ResponseField>
                  </Expandable>
                </ResponseField>

                <ResponseField name="akamaiUserRisk" type="dictionary">
                  The user risk detection results as forwarded by Akamai Account Protector.

                  <Expandable title="akamaiUserRisk properties">
                    <ResponseField name="action" type="string">
                      The action of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="allow" type="number">
                      The allowed status of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="emailDomain" type="string">
                      The email domain of the user.
                    </ResponseField>

                    <ResponseField name="general" type="dictionary">
                      The general risk of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="ouid" type="string">
                      The OUID of the user.
                    </ResponseField>

                    <ResponseField name="requestid" type="string">
                      The request ID of the user.
                    </ResponseField>

                    <ResponseField name="risk" type="dictionary">
                      The risk of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="score" type="number">
                      The score of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="status" type="number">
                      The status of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="trust" type="dictionary">
                      The trust of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="username" type="string">
                      The username of the user.
                    </ResponseField>

                    <ResponseField name="uuid" type="string">
                      The UUID of the Akamai user risk assessment.
                    </ResponseField>
                  </Expandable>
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.authorization`

<ResponseField name="event.authorization" type="object">
  An object containing information describing the authorization granted to the user who is logging in.

  <Expandable title="authorization properties">
    <ResponseField name="roles" type="array of strings">
      An array containing the names of a user's assigned roles.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.client`

<ResponseField name="event.client" type="dictionary">
  Information about the Client with which this password reset transaction was initiated.

  <Expandable title="client properties">
    <ResponseField name="client_id" type="string">
      The client id of the application the user is logging in to.
    </ResponseField>

    <ResponseField name="metadata" type="dictionary">
      An object for holding other application properties.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the application (as defined in the Dashboard).
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.connection`

<ResponseField name="event.connection" type="dictionary">
  Details about the Connection that was used to authenticate the user.

  <Expandable title="connection properties">
    <ResponseField name="id" type="string">
      The connection's unique identifier.
    </ResponseField>

    <ResponseField name="metadata" type="dictionary">
      Metadata associated with the connection.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the connection used to authenticate the user (such as `twitter` or `some-g-suite-domain`).
    </ResponseField>

    <ResponseField name="strategy" type="string">
      The type of connection. For social connections, `event.connection.strategy === event.connection.name`. For enterprise connections, the strategy is `waad` (Windows Azure AD), `ad` (Active Directory/LDAP), `auth0` (database connections), and so on.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.custom_domain`

<ResponseField name="event.custom_domain" type="dictionary">
  Details about the custom domain associated with the current transaction.

  <Expandable title="custom_domain properties">
    <ResponseField name="domain" type="string">
      The custom domain name.
    </ResponseField>

    <ResponseField name="domain_metadata" type="dictionary">
      Custom domain metadata as key-value pairs.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.organization`

<ResponseField name="event.organization" type="dictionary">
  Details about the Organization associated with the current transaction.

  <Expandable title="organization properties">
    <ResponseField name="id" type="string">
      The Organization identifier.
    </ResponseField>

    <ResponseField name="display_name" type="string">
      The friendly name of the Organization.
    </ResponseField>

    <ResponseField name="metadata" type="dictionary">
      Metadata associated with the Organization.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the Organization.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.prompt`

<ResponseField name="event.prompt" type="dictionary">
  Collected data from rendered custom prompts.

  <Expandable title="prompt properties">
    <ResponseField name="id" type="string">
      The prompt ID.
    </ResponseField>

    <ResponseField name="fields" type="dictionary">
      Fields and hidden fields data.
    </ResponseField>

    <ResponseField name="vars" type="dictionary">
      Shared variables data.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.request`

<ResponseField name="event.request" type="dictionary">
  Details about the request that initiated the transaction.

  <Expandable title="request properties">
    <ResponseField name="body" type="dictionary">
      The body of the POST request. This data will only be available during refresh token and Client Credential Exchange flows and Post Login Action.
    </ResponseField>

    <ResponseField name="geoip" type="dictionary">
      <Expandable title="geoip properties">
        <ResponseField name="cityName" type="string" />

        <ResponseField name="continentCode" type="string" />

        <ResponseField name="countryCode" type="string" />

        <ResponseField name="countryCode3" type="string" />

        <ResponseField name="countryName" type="string" />

        <ResponseField name="latitude" type="number" />

        <ResponseField name="longitude" type="number" />

        <ResponseField name="subdivisionCode" type="string" />

        <ResponseField name="subdivisionName" type="string" />

        <ResponseField name="timeZone" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="hostname" type="string">
      The hostname that is being used for the authentication flow.
    </ResponseField>

    <ResponseField name="ip" type="string">
      The originating IP address of the request.
    </ResponseField>

    <ResponseField name="language" type="string">
      The language requested by the browser.
    </ResponseField>

    <ResponseField name="method" type="string">
      The HTTP method used for the request
    </ResponseField>

    <ResponseField name="query" type="dictionary">
      The query string parameters sent to the authorization request.
    </ResponseField>

    <ResponseField name="user_agent" type="string">
      The value of the `User-Agent` header received when initiating the transaction.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.stats`

<ResponseField name="event.stats" type="object">
  Login statistics for the current user.

  <Expandable title="stats properties">
    <ResponseField name="logins_count" type="number">
      The number of times this user has logged in.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.tenant`

<ResponseField name="event.tenant" type="object">
  Details about the Tenant associated with the current transaction.

  <Expandable title="tenant properties">
    <ResponseField name="id" type="string">
      The name of the tenant.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.transaction`

<ResponseField name="event.transaction" type="dictionary">
  Details about the current transaction.

  <Expandable title="transaction properties">
    <ResponseField name="correlation_id" type="string">
      Correlation ID can be provided in the initial authentication request when the application redirects to Universal Login. You can use value to correlate logs and requests from your Action code with the user flow.
    </ResponseField>

    <ResponseField name="locale" type="string">
      The locale to be used for this transaction as determined by comparing the browser's requested languages to the tenant's language settings.
    </ResponseField>

    <ResponseField name="login_hint" type="string">
      Hint to the Authorization Server about the login identifier the End-User might use to log in (if necessary).
    </ResponseField>

    <ResponseField name="state" type="string">
      An opaque arbitrary alphanumeric string your app adds to the initial request that Auth0 includes when redirecting back to your application.
    </ResponseField>

    <ResponseField name="ui_locales" type="array of strings">
      The ui\_locales provided in the original authentication request.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.user`

<ResponseField name="event.user" type="dictionary">
  An object describing the user on whose behalf the current transaction was initiated.

  <Expandable title="user properties">
    <ResponseField name="app_metadata" type="dictionary">
      Custom fields that store info about a user that influences the user's access, such as support plan, security roles, or access control groups.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Timestamp indicating when the user profile was first created.
    </ResponseField>

    <ResponseField name="email" type="string">
      (unique) User's email address.
    </ResponseField>

    <ResponseField name="email_verified" type="boolean">
      Indicates whether the user has verified their email address.
    </ResponseField>

    <ResponseField name="family_name" type="string">
      User's family name.
    </ResponseField>

    <ResponseField name="given_name" type="string">
      User's given name.
    </ResponseField>

    <ResponseField name="last_password_reset" type="string">
      Timestamp indicating the last time the user's password was reset/changed. At user creation, this field does not exist. This property is only available for Database connections.
    </ResponseField>

    <ResponseField name="name" type="string">
      User's full name.
    </ResponseField>

    <ResponseField name="nickname" type="string">
      User's nickname.
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      User's phone number.
    </ResponseField>

    <ResponseField name="phone_verified" type="boolean">
      Indicates whether the user has verified their phone number.
    </ResponseField>

    <ResponseField name="picture" type="string">
      URL pointing to the [user's profile picture](https://auth0.com/docs/users/change-user-picture).
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      Timestamp indicating when the user's profile was last updated/modified.
    </ResponseField>

    <ResponseField name="user_id" type="string">
      (unique) User's unique identifier.
    </ResponseField>

    <ResponseField name="user_metadata" type="dictionary">
      Custom fields that store info about a user that does not impact what they can or cannot access, such as work address, home address, or user preferences.
    </ResponseField>

    <ResponseField name="username" type="string">
      (unique) User's username.
    </ResponseField>

    <ResponseField name="enrolledFactors" type="array of objects">
      An array of authentication factors that the user has enrolled. Empty array means the user has no enrolled factors.  If enrolledFactors is undefined, the system was unable fetch the information, the user may or may not have enrolled factors.

      <Expandable title="enrolledFactors properties">
        <ResponseField name="type" type="string">
          The type of authentication factor such as `push-notification`, `phone`, `email`, `otp`, `webauthn-roaming` and `webauthn-platform`.
        </ResponseField>

        <ResponseField name="options" type="dictionary">
          Additional options describing this instance of the enrolled factor.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="identities" type="array of objects">
      Contains info retrieved from the identity provider with which the user originally authenticated. Users may also link their profile to multiple identity providers; those identities will then also appear in this array. The contents of an individual identity provider object varies by provider.

      <Expandable title="identities element properties">
        <ResponseField name="connection" type="string">
          Name of the Auth0 connection used to authenticate the user.
        </ResponseField>

        <ResponseField name="isSocial" type="boolean">
          Indicates whether the connection is a social one.
        </ResponseField>

        <ResponseField name="profileData" type="dictionary">
          User information associated with the connection. When profiles are linked, it is populated with the associated user info for secondary accounts.
        </ResponseField>

        <ResponseField name="provider" type="string">
          Name of the entity that is authenticating the user, such as Facebook, Google, SAML, or your own provider.
        </ResponseField>

        <ResponseField name="user_id" type="string">
          User's unique identifier for this connection/provider.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.secrets`

<ResponseField name="event.secrets" type="secrets">
  Secret values securely associated with this Action.
</ResponseField>


# Post Change Password Trigger
Source: https://auth0.com/docs/customize/actions/explore-triggers/password-reset-triggers/post-change-password-trigger

Learn about the Post Change Password flow and the post-change-password Action trigger, which runs after a Database connection user resets or changes their password. This trigger can be used to notify another system that the user’s password has changed.

The Post Change Password trigger runs after a user resets or changes their password. You can use this trigger to email the user after a password change or to notify another system that the user’s password has changed, so that other sessions not managed by Auth0 can be revoked.

<Frame>
  <img alt="Diagram showing the Actions Post Change Password Flow." />
</Frame>

Actions in this flow are non-blocking (asynchronous), which means the Auth0 pipeline will continue to run without waiting for the Action to finish its execution. Thus, the Action's outcome does not affect the Auth0 transaction.

## Triggers

### Post Change Password

The `post-change-password` trigger runs after a database connection user resets or changes their password.

Multiple Actions can be bound to this trigger, and the Actions will run in order. However, these Actions will be run asynchronously and will not block the password reset process.

### Reference

* [Event object](/docs/customize/actions/explore-triggers/password-reset-triggers/post-change-password-trigger/post-change-password-event-object): Provides contextual information about the user and the connection on which the password was changed.
* [API object](/docs/customize/actions/explore-triggers/password-reset-triggers/post-change-password-trigger/post-change-password-api-object): Provides methods for changing the behavior of the flow.

## Common use cases

### Invalidate the user’s session in another system

A post-change-password Action can be used to invalidate the user's session in another system:

```javascript lines theme={null}
const axios = require("axios");

/**
 * @param {Event} event - Details about user whose password was changed.
 */
exports.onExecutePostChangePassword = async (event) => {
  axios.post("https://my-api.exampleco.com/revoke-session", { params: { email: event.user.email }});
};
```

<Callout icon="file-lines">
  To use an `npm` library like `axios`, you must add the library to the Action as a dependency. To learn more, read the "Add a dependency" section in [Write Your First Action](/docs/customize/actions/write-your-first-action).
</Callout>

### Send an email after the user changes their password

```javascript lines expandable theme={null}
const axios = require("axios");

exports.onExecutePostChangePassword = async (event) => {
  try {
    // https://sendgrid.api-docs.io/v3.0/mail-send
    axios.post('https://api.sendgrid.com/v3/mail/send',
      {
        personalizations: [{
          to: [{ email: event.user.email }]
        }],
        from: { email: 'admin@exampleco.com' },
        subject: 'Your password was changed',
        content: [{
          type: 'text/plain',
          value: 'The password for your ' + event.connection.name + ' account ' + event.user.email + ' was recently changed.'
        }]
      },
      {
        headers: {
          'Authorization': 'Bearer ' + event.secrets.SENDGRID_API_KEY
        },
      }
    );
  } catch (err) {
    console.log(`Error sending email to ${event.user.email}:`, err.message)
  }
};
```


# Actions Triggers: post-change-password - API Object
Source: https://auth0.com/docs/customize/actions/explore-triggers/password-reset-triggers/post-change-password-trigger/post-change-password-api-object

Learn about the post-change-password Action trigger's API object.

The API object for the post-change-password Actions trigger includes:

## `api.cache`

Store and retrieve data that persists across executions.

### `api.cache.delete(key)`

Delete a record describing a cached value at the supplied
key if it exists.

<ResponseField name="key" type="string">
  The key of the cache record to delete.
</ResponseField>

### `api.cache.get(key)`

Retrieve a record describing a cached value at the supplied key,
if it exists. If a record is found, the cached value can be found
at the `value` property of the returned object.

<ResponseField name="key" type="string">
  The key of the record stored in the cache.
</ResponseField>

### `api.cache.set(key, value, options)`

Store or update a string value in the cache at the specified key.

Values stored in this cache are scoped to the Trigger in which they
are set. They are subject to the [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations).

Values stored in this way will have lifetimes of *up to* the specified
`ttl` or `expires_at` values. If no lifetime is specified, a default of
lifetime of 24 hours will be used. Lifetimes may not exceed the maximum
duration listed at [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations).

**Important**: This cache is designed for short-lived, ephemeral data. Items may not be
available in later transactions even if they are within their supplied their lifetime.

<ResponseField name="key" type="string">
  The key of the record to be stored.
</ResponseField>

<ResponseField name="value" type="string">
  The value of the record to be stored.
</ResponseField>

<ResponseField name="options" type="cachesetoptions">
  Options for adjusting cache behavior.

  <Expandable title="options properties">
    <ResponseField name="expires_at" type="number">
      The absolute expiry time in milliseconds since the unix epoch.
      While cached records may be evicted earlier, they will
      never remain beyond the the supplied `expires_at`.

      *Note*: This value should not be supplied if a value was also
      provided for `ttl`. If both options are supplied, the
      earlier expiry of the two will be used.
    </ResponseField>

    <ResponseField name="ttl" type="number">
      The time-to-live value of this cache entry in milliseconds.
      While cached values may be evicted earlier, they will
      never remain beyond the the supplied `ttl`.

      *Note*: This value should not be supplied if a value was also
      provided for `expires_at`. If both options are supplied, the
      earlier expiry of the two will be used.
    </ResponseField>
  </Expandable>
</ResponseField>


# Actions Triggers: post-change-password - Event Object
Source: https://auth0.com/docs/customize/actions/explore-triggers/password-reset-triggers/post-change-password-trigger/post-change-password-event-object

Learn about the post-change-password Action trigger's event object, which provides contextual information about the trigger execution.

The `event` object for the post-change-password Actions trigger provides contextual information about the trigger execution.

## `event.authentication`

<ResponseField name="event.authentication" type="dictionary">
  Details about supplemental authentication signals obtained during the password change flow.

  <Expandable title="authentication properties">
    <ResponseField name="riskAssessment" type="dictionary">
      Details about risk assessments information for different flows.

      <Expandable title="riskAssessment properties">
        <ResponseField name="supplemental" type="dictionary">
          Supplemental signals sent from third party providers to assist in risk assessments.

          <Expandable title="supplemental properties">
            <ResponseField name="akamai" type="dictionary">
              \[Limited Early Access] Supplemental risk assessment. This is available only if Akamai Account Protector is enabled and Akamai forwards the headers for the transaction.

              <Expandable title="akamai properties">
                <ResponseField name="akamaiBot" type="object">
                  The bot detection results as forwarded by Akamai Bot Manager.

                  <Expandable title="akamaiBot properties">
                    <ResponseField name="type" type="string">
                      The type of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="action" type="string">
                      The action of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="botCategory" type="array of strings">
                      The bot category of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="botScore" type="number">
                      The bot score of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="botScoreResponseSegment" type="string">
                      The bot score response segment of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="botnetId" type="string">
                      The botnet ID of the Akamai bot manager results.
                    </ResponseField>
                  </Expandable>
                </ResponseField>

                <ResponseField name="akamaiUserRisk" type="dictionary">
                  The user risk detection results as forwarded by Akamai Account Protector.

                  <Expandable title="akamaiUserRisk properties">
                    <ResponseField name="action" type="string">
                      The action of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="allow" type="number">
                      The allowed status of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="emailDomain" type="string">
                      The email domain of the user.
                    </ResponseField>

                    <ResponseField name="general" type="dictionary">
                      The general risk of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="ouid" type="string">
                      The OUID of the user.
                    </ResponseField>

                    <ResponseField name="requestid" type="string">
                      The request ID of the user.
                    </ResponseField>

                    <ResponseField name="risk" type="dictionary">
                      The risk of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="score" type="number">
                      The score of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="status" type="number">
                      The status of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="trust" type="dictionary">
                      The trust of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="username" type="string">
                      The username of the user.
                    </ResponseField>

                    <ResponseField name="uuid" type="string">
                      The UUID of the Akamai user risk assessment.
                    </ResponseField>
                  </Expandable>
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.connection`

<ResponseField name="event.connection" type="dictionary">
  Details about the Connection that was used for the current transaction.

  <Expandable title="connection properties">
    <ResponseField name="id" type="string">
      The connection's unique identifier.
    </ResponseField>

    <ResponseField name="metadata" type="dictionary">
      Metadata associated with the connection.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the connection used to authenticate the user (such as `twitter` or `some-g-suite-domain`).
    </ResponseField>

    <ResponseField name="strategy" type="string">
      The type of connection. For social connections, `event.connection.strategy === event.connection.name`. For enterprise connections, the strategy is `waad` (Windows Azure AD), `ad` (Active Directory/LDAP), `auth0` (database connections), and so on.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.custom_domain`

<ResponseField name="event.custom_domain" type="dictionary">
  Details about the custom domain associated with the current transaction.

  <Expandable title="custom_domain properties">
    <ResponseField name="domain" type="string">
      The custom domain name.
    </ResponseField>

    <ResponseField name="domain_metadata" type="dictionary">
      Custom domain metadata as key-value pairs.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.request`

<ResponseField name="event.request" type="dictionary">
  Details about the request that initiated the transaction.

  <Expandable title="request properties">
    <ResponseField name="geoip" type="dictionary">
      <Expandable title="geoip properties">
        <ResponseField name="cityName" type="string" />

        <ResponseField name="continentCode" type="string" />

        <ResponseField name="countryCode" type="string" />

        <ResponseField name="countryCode3" type="string" />

        <ResponseField name="countryName" type="string" />

        <ResponseField name="latitude" type="number" />

        <ResponseField name="longitude" type="number" />

        <ResponseField name="subdivisionCode" type="string" />

        <ResponseField name="subdivisionName" type="string" />

        <ResponseField name="timeZone" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="hostname" type="string">
      The hostname that is being used for the authentication flow.
    </ResponseField>

    <ResponseField name="ip" type="string">
      The originating IP address of the request.
    </ResponseField>

    <ResponseField name="language" type="string">
      The language requested by the browser.
    </ResponseField>

    <ResponseField name="method" type="string">
      The HTTP method used for the request
    </ResponseField>

    <ResponseField name="user_agent" type="string">
      The value of the `User-Agent` header received when initiating the transaction.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.tenant`

<ResponseField name="event.tenant" type="object">
  Details about the Tenant associated with the current transaction.

  <Expandable title="tenant properties">
    <ResponseField name="id" type="string">
      The name of the tenant.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.transaction`

<ResponseField name="event.transaction" type="object">
  Details about the current transaction.

  <Expandable title="transaction properties">
    <ResponseField name="correlation_id" type="string">
      Correlation ID can be provided in the initial authentication request when the application redirects to Universal Login. You can use value to correlate logs and requests from your Action code with the user flow.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.user`

<ResponseField name="event.user" type="object">
  An object describing the user on whose behalf the current transaction was initiated.

  <Expandable title="user properties">
    <ResponseField name="email" type="string">
      (unique) User's email address.
    </ResponseField>

    <ResponseField name="email_verified" type="boolean">
      Indicates whether the user has verified their email address.
    </ResponseField>

    <ResponseField name="last_password_reset" type="string">
      Timestamp indicating the last time the user's password was reset/changed. At user creation, this field does not exist. This property is only available for Database connections.
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      (unique) User's phone number.
    </ResponseField>

    <ResponseField name="phone_verified" type="boolean">
      Indicates whether the user has verified their phone number.
    </ResponseField>

    <ResponseField name="user_id" type="string">
      (unique) User's unique identifier.
    </ResponseField>

    <ResponseField name="username" type="string">
      (unique) User's username.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.secrets`

<ResponseField name="event.secrets" type="secrets">
  Secret values securely associated with this Action.
</ResponseField>


# Signup and Login Triggers
Source: https://auth0.com/docs/customize/actions/explore-triggers/signup-and-login-triggers

Signup and Login Triggers

For more information on Signup and Login triggers, see the sections below.

<table>
  <thead>
    <tr>
      <th>Trigger</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger">Login Trigger</a></td>
      <td>The Login triggers run when a user logs in to any application in an Auth0 tenant.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger">Pre-user Registration Trigger</a></td>
      <td>The Pre-user Registration trigger runs before a user is added to a Database or Passwordless Connection.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/actions/explore-triggers/signup-and-login-triggers/post-user-registration-trigger">Post-user Registration Trigger</a></td>
      <td>The Post-user Registration trigger runs after a user is added to a Database or Passwordless Connection.</td>
    </tr>
  </tbody>
</table>


# Custom Token Exchange Trigger
Source: https://auth0.com/docs/customize/actions/explore-triggers/signup-and-login-triggers/custom-token-exchange-trigger

Learn about the Custom Token Exchange Trigger, which is executed when the Auth0 Authorization Server receives a Custom Token Exchange Request to log a user in.

<Warning>
  Custom Token Exchange (CTE) is currently available in Early Access for all Auth0 Enterprise and B2B Pro customers. By using this feature, you agree to the applicable Free Trial terms in [Okta’s Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0’s product release cycle, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To learn more about subscription types, review the Auth0 [pricing](https://auth0.com/pricing) page.
</Warning>

After the Auth0 Authorization Server validates that the Custom Token Exchange request is valid and maps to an existing [Custom Token Exchange Profile](/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#create-custom-token-exchange-profile), the `custom-token-exchange` trigger executes the single Action associated with that profile. If the Action successfully completes and sets a user for the transaction, `post-login` Actions and the rest of the Auth0 pipeline are then executed for that logged-in user.

<Frame>
  <img alt="" />
</Frame>

Actions in this flow are blocking (synchronous), which means they execute as part of a trigger’s process and will prevent the rest of the Auth0 pipeline from running until the Action is complete.

## Custom Token Exchange vs Post Login Actions

The Post Login Actions trigger executes after the Custom Token Exchange Action runs for the user you set for the transaction. For other use cases, such as adding custom claims to access tokens, use the [Post Login Action trigger](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger).

The Custom Token Exchange uses the token exchange grant type, where the `event.transaction.protocol` is set to `oauth2-token-exchange` in the Post Login Action trigger. Both the Custom Token Exchange and Native Social Login use the token exchange grant type. To distinguish between the two, use the value of the `subject_token_type`, which should correspond to one of your Custom Token Exchange Profiles.

<Callout icon="file-lines">
  Custom Token Exchange Early Access doesn’t support  `api.authentication.challengeWith()` or `api.authentication.enrollWith()`. If you use those methods with your Post-Login Actions, the transaction will fail with a non-recoverable error. Make sure you skip those two methods when `event.transaction.protocol==oauth2-token-exchange` depending on the `subject_token_type` value.
</Callout>

## Triggers

### Custom Token Exchange

The `custom-token-exchange` trigger is the first step in the Auth0 pipeline. This function is executed after the received Custom Token Exchange request has been validated and successfully mapped to an existing profile.

### References

* [Event object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/custom-token-exchange-trigger/custom-token-exchange-event-object): Provides contextual information about the a Token Exchange request, including the subject\_token, IP address, client, and more.
* [API object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/custom-token-exchange-trigger/custom-token-exchange-api-object): Provides methods to use with your Token Exchange Action that allows you to set the user, reject the transaction, set user metadata and access the Actions cache, and more.

## Common Use Cases

To learn about common Custom Token Exchange use cases, read [Example Use Cases](/docs/authenticate/custom-token-exchange/cte-example-use-cases).


# Actions Triggers: custom-token-exchange - API Object
Source: https://auth0.com/docs/customize/actions/explore-triggers/signup-and-login-triggers/custom-token-exchange-trigger/custom-token-exchange-api-object

Learn about the custom-token-exchange Action trigger's API object.

The API object for the custom-token-exchange Actions trigger includes:

## `api.access`

Modify the access of the token exchange request, such as rejecting the request.

### `api.access.deny(code, reason)`

Mark the current token exchange as denied.

If the request is being denied due to an invalid subject token, we recommend that api.access.rejectInvalidSubjectToken be used instead,
to distinguish between brute force attempts on the subject token, and other reasons to deny the request.

<ResponseField name="code" type="string">
  The error code justifying the rejection of the token exchange. Can be invalid\_request, server\_error, or any custom code
</ResponseField>

<ResponseField name="reason" type="string">
  A human-readable explanation for rejecting the token exchange request.
</ResponseField>

```js theme={null}
exports.onExecuteCustomTokenExchange = async (event, api) => {

  // 1. Validate subject_token
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // 2. Apply your authorization policy on the user
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }

  // if user is authorized, go on as indicated here

};
```

### `api.access.rejectInvalidSubjectToken(reason)`

Mark the provided subject token from the request as invalid. This will cause the request to be
rejected with an "invalid\_request" error code.

This will signal to the Attack Protection features that an invalid subject token has been provided,
so that protections to prevent brute force attacks on the subject token can be applied.

<ResponseField name="reason" type="string">
  A human-readable explanation for rejecting the token exchange request.
</ResponseField>

```js theme={null}
exports.onExecuteCustomTokenExchange = async (event, api) => {

  try {
    // Validate subject_token
    const subject_token = await validateToken(event.transaction.subject_token, jwksUri);
    // set the user for the transaction
    api.authentication.setUserById(subject_token.id);

  } catch (error) {
    if (error.message === 'Invalid Token') {
      // If specifically the problem is the subject_token is invalid
      console.error('Invalid Token error');
      api.access.rejectInvalidSubjectToken('Invalid subject_token');
    } else {
      // if there is any other unexpected error, throw a server error
      throw error;
    }
  }

};
```

## `api.authentication`

Indicate the result of the authentication of the subject token, to specify the user whom tokens will be issued for.

### `api.authentication.setUserById(user_id)`

Indicate the user corresponding to the subject\_token, by providing the userId. The token exchange request will issue tokens for this user.
This must be an existing user.
Note: Exactly one of api.authentication.setUserByConnection api.authentication.setUserById must be called by the Custom Token Exchange action.

<ResponseField name="user_id" type="string">
  The ID of the user; must be an existing user.
</ResponseField>

```js theme={null}
exports.onExecuteCustomTokenExchange = async (event, api) => {

  // 1. Validate subject_token
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // 2. Apply your authorization policy on the user
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }

  // 3. Set the user for the transaction
  api.authentication.setUserById(subject_token.sub);

  return;
};
```

### `api.authentication.setUserByConnection(connection_name, user_attributes, options)`

Indicate the user corresponding to the subject\_token, by providing a connection and user attributes.
The token exchange request will issue tokens for this user.

This can be either an existing user, or a new user. If the user does not exist, it will be created.
The user\_id property of the user\_profile will be used to determine if the user already exists.

Note: Exactly one of api.authentication.setUserByConnection api.authentication.setUserById must be called by the Custom Token Exchange action.

<ResponseField name="connection_name" type="string">
  Name of the connection the user should be stored in.
</ResponseField>

<ResponseField name="user_attributes" type="setuserbyconnectionuserattributes">
  The user's profile attributes, including user\_id, and optionally other attributes such as email, name, etc.

  The user\_id field is required, and should be the unique identifier of the user within the connection;
  this will be used to determine if the user exists or should be created. In existing users, this user\_id
  can be found by inspecting the identities array of the normalized user profile.

  If the user already exists, the following user attributes cannot be updated: email, email\_verified, phone, phone\_verified, username.
  If these do not match the existing user, an error will be returned.

  <Expandable title="user_attributes properties">
    <ResponseField name="email" type="string">
      The user's email.
    </ResponseField>

    <ResponseField name="email_verified" type="boolean">
      Whether this email address is verified (true) or unverified (false). User will receive a verification email after creation if email\_verified is false or not specified.
    </ResponseField>

    <ResponseField name="family_name" type="string">
      The user's family name(s).
    </ResponseField>

    <ResponseField name="given_name" type="string">
      The user's given name(s).
    </ResponseField>

    <ResponseField name="name" type="string">
      The user's full name.
    </ResponseField>

    <ResponseField name="nickname" type="string">
      The user's nickname.
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      The user's phone number (following the E.164 recommendation).
    </ResponseField>

    <ResponseField name="phone_verified" type="boolean">
      Whether this phone number has been verified (true) or not (false).
    </ResponseField>

    <ResponseField name="picture" type="string">
      A URI pointing to the user's picture.
    </ResponseField>

    <ResponseField name="user_id" type="string">
      The user's unique identifier within the connection.
    </ResponseField>

    <ResponseField name="username" type="string">
      The user's username.
    </ResponseField>

    <ResponseField name="verify_email" type="boolean">
      Whether the user will receive a verification email after creation (true) or no email (false). Overrides behavior of email\_verified parameter.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="options" type="setuserbyconnectionoptions">
  Options to control the behavior of the setUserByConnection command.

  * `creationBehavior` - behavior to apply if no user with the specified user\_id exists in the connection.
    Can be 'create\_if\_not\_exists', which will cause a new user to be created using the supplied user attributes;
    or 'none', which will result in no user being created and an error being returned if no user exists.

  * `updateBehavior` - Behavior to apply if a user with specified user\_id already exists in the connection.
    Can be 'replace', which results in the existing user's attributes being replaced with the specified
    user attributes; or 'none' which means the existing user will not be modified.

  <Expandable title="options properties">
    <ResponseField name="creationBehavior" type="string">
      Behaviour to apply if no user with the specified user\_id exists in the connection. Can be 'create\_if\_not\_exists', which will cause a new user to be created using the supplied user attributes; or 'none', which will result in no user being created and an error being returned if no user exists.

      Allowed values: `create_if_not_exists`, `none`
    </ResponseField>

    <ResponseField name="updateBehavior" type="string">
      Behaviour to apply if a user with specified user\_id already exists in the connection. Can be 'replace', which results in the existing user's attributes being replaced with the specified user attributes; or 'none' which means the existing user will not be modified.

      Allowed values: `none`, `replace`
    </ResponseField>
  </Expandable>
</ResponseField>

```js Set user by connection with full profile attributes theme={null}
exports.onExecuteCustomTokenExchange = async (event, api) => {

  // 1. Validate subject_token
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // 2. Apply your authorization policy on the user
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }

  // 3. Set the user for the transaction
  api.authentication.setUserByConnection(
    'My Connection',
    {
      user_id: subject_token.sub,
      email: subject_token.email,
      email_verified: subject_token.email_verified,
      phone_number: subject_token.phone_number,
      phone_verified: subject_token.phone_number_verified,
      username: subject_token.preferred_username,
      name: subject_token.name,
      given_name: subject_token.given_name,
      family_name: subject_token.family_name,
      nickname: subject_token.nickname,
      verify_email: false
    },
    {
      creationBehavior: 'create_if_not_exists',
      updateBehavior: 'none'
    }
  );

  return;
};
```

```js Create a user without verifying email theme={null}
exports.onExecuteCustomTokenExchange = async (event, api) => {

  // Validate subject_token
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // Create a user but don't verify email
  api.authentication.setUserByConnection(
    'My Connection',
    {
      user_id: subject_token.sub,
      email: subject_token.email,
      email_verified: false,
      verify_email: false
    },
    {
      creationBehavior: 'create_if_not_exists',
      updateBehavior: 'none'
    }
  );

  return;
};
```

### `api.authentication.setOrganization(organization_id_or_name)`

Set the organization for the user associated with the token exchange.

<ResponseField name="organization_id_or_name" type="string">
  The ID or name of the organization to set for the user.
</ResponseField>

```js theme={null}
exports.onExecuteCustomTokenExchange = async (event, api) => {

  // 1. Validate subject_token
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // 2. Apply your authorization policy on the user
  const isAuthorized = await authorizeAccess(subject_token.sub);
  if (!isAuthorized) {
    api.access.deny('Unauthorized_login', 'User cannot login due to reason: X');
  }

  // 3. Set the organization for the transaction
  api.authentication.setOrganization('org_xS525r979AS33MSf');

  // 4. Set the user for the transaction. You may also use setUserByConnection()
  api.authentication.setUserById(subject_token.sub);

  return;
};
```

## `api.user`

Request changes to the user corresponding to the subject token.

### `api.user.setAppMetadata(key, value)`

Set application-specific metadata for the user corresponding to the subject token.

<ResponseField name="key" type="string">
  The metadata property to be set.
</ResponseField>

<ResponseField name="value" type="unknown">
  The value of the metadata property. This may be set to `null` to remove the
  metadata property.
</ResponseField>

```js theme={null}
exports.onExecuteCustomTokenExchange = async (event, api) => {
  // Validate subject_token
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // set the user for the transaction
  api.authentication.setUserById(subject_token.id);

  // set user group based on info contained in subject_token
  api.user.setAppMetadata('group', subject_token.group);

  return;
};
```

### `api.user.setUserMetadata(key, value)`

Set general metadata for the user corresponding to the subject token.

<ResponseField name="key" type="string">
  The metadata property to be set.
</ResponseField>

<ResponseField name="value" type="unknown">
  The value of the metadata property. This may be set to `null` to remove the
  metadata property.
</ResponseField>

```js theme={null}
exports.onExecuteCustomTokenExchange = async (event, api) => {
  // Validate subject_token
  const subject_token = await validateToken(event.transaction.subject_token, jwksUri);

  // set the user for the transaction
  api.authentication.setUserById(subject_token.id);

  // set user preferred_locale based on info contained in subject_token
  api.user.setUserMetadata('preferred_locale', subject_token.locale);

  return;
};
```

## `api.cache`

Store and retrieve data that persists across executions.

### `api.cache.delete(key)`

Delete a record describing a cached value at the supplied
key if it exists.

<ResponseField name="key" type="string">
  The key of the cache record to delete.
</ResponseField>

### `api.cache.get(key)`

Retrieve a record describing a cached value at the supplied key,
if it exists. If a record is found, the cached value can be found
at the `value` property of the returned object.

<ResponseField name="key" type="string">
  The key of the record stored in the cache.
</ResponseField>

### `api.cache.set(key, value, options)`

Store or update a string value in the cache at the specified key.

Values stored in this cache are scoped to the Trigger in which they
are set. They are subject to the [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations).

Values stored in this way will have lifetimes of *up to* the specified
`ttl` or `expires_at` values. If no lifetime is specified, a default of
lifetime of 24 hours will be used. Lifetimes may not exceed the maximum
duration listed at [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations).

**Important**: This cache is designed for short-lived, ephemeral data. Items may not be
available in later transactions even if they are within their supplied their lifetime.

<ResponseField name="key" type="string">
  The key of the record to be stored.
</ResponseField>

<ResponseField name="value" type="string">
  The value of the record to be stored.
</ResponseField>

<ResponseField name="options" type="cachesetoptions">
  Options for adjusting cache behavior.

  <Expandable title="options properties">
    <ResponseField name="expires_at" type="number">
      The absolute expiry time in milliseconds since the unix epoch.
      While cached records may be evicted earlier, they will
      never remain beyond the the supplied `expires_at`.

      *Note*: This value should not be supplied if a value was also
      provided for `ttl`. If both options are supplied, the
      earlier expiry of the two will be used.
    </ResponseField>

    <ResponseField name="ttl" type="number">
      The time-to-live value of this cache entry in milliseconds.
      While cached values may be evicted earlier, they will
      never remain beyond the the supplied `ttl`.

      *Note*: This value should not be supplied if a value was also
      provided for `expires_at`. If both options are supplied, the
      earlier expiry of the two will be used.
    </ResponseField>
  </Expandable>
</ResponseField>


# Actions Triggers: custom-token-exchange - Event Object
Source: https://auth0.com/docs/customize/actions/explore-triggers/signup-and-login-triggers/custom-token-exchange-trigger/custom-token-exchange-event-object

Learn about the custom-token-exchange Action trigger's event object, which provides contextual information about the trigger execution.

The `event` object for the custom-token-exchange Actions trigger provides contextual information about the trigger execution.

## `event.client`

<ResponseField name="event.client" type="dictionary">
  Information about the Client with which this transaction was initiated.

  <Expandable title="client properties">
    <ResponseField name="client_id" type="string">
      The client id of the application the user is logging in to.
    </ResponseField>

    <ResponseField name="metadata" type="dictionary">
      An object for holding other application properties.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the application (as defined in the Dashboard).
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.organization`

<ResponseField name="event.organization" type="dictionary">
  Details about the Organization associated with the current transaction.

  <Expandable title="organization properties">
    <ResponseField name="id" type="string">
      The Organization identifier.
    </ResponseField>

    <ResponseField name="display_name" type="string">
      The friendly name of the Organization.
    </ResponseField>

    <ResponseField name="metadata" type="dictionary">
      Metadata associated with the Organization.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the Organization.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.request`

<ResponseField name="event.request" type="dictionary">
  Details about the request that initiated the transaction.

  <Expandable title="request properties">
    <ResponseField name="body" type="dictionary">
      The body of the POST request. This data will only be available during refresh token, Client Credential Exchange flows and PreUserRegistration Action.
    </ResponseField>

    <ResponseField name="geoip" type="dictionary">
      <Expandable title="geoip properties">
        <ResponseField name="cityName" type="string" />

        <ResponseField name="continentCode" type="string" />

        <ResponseField name="countryCode" type="string" />

        <ResponseField name="countryCode3" type="string" />

        <ResponseField name="countryName" type="string" />

        <ResponseField name="latitude" type="number" />

        <ResponseField name="longitude" type="number" />

        <ResponseField name="subdivisionCode" type="string" />

        <ResponseField name="subdivisionName" type="string" />

        <ResponseField name="timeZone" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="hostname" type="string">
      The hostname that is being used for the authentication flow.
    </ResponseField>

    <ResponseField name="ip" type="string">
      The originating IP address of the request.
    </ResponseField>

    <ResponseField name="language" type="string">
      The language requested by the browser.
    </ResponseField>

    <ResponseField name="method" type="string">
      The HTTP method used for the request
    </ResponseField>

    <ResponseField name="user_agent" type="string">
      The value of the `User-Agent` header received when initiating the transaction.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.resource_server`

<ResponseField name="event.resource_server" type="object">
  Details about the resource server to which the access is being requested.

  <Expandable title="resource_server properties">
    <ResponseField name="identifier" type="string">
      The identifier of the resource server. For example: `https://your-api.example.com`.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.tenant`

<ResponseField name="event.tenant" type="object">
  Details about the Tenant associated with the current transaction.

  <Expandable title="tenant properties">
    <ResponseField name="id" type="string">
      The name of the tenant.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.transaction`

<ResponseField name="event.transaction" type="object">
  Details about the current custom token exchange transaction.

  <Expandable title="transaction properties">
    <ResponseField name="requested_scopes" type="array of strings">
      The scopes requested (if any) provided in the token exchange request.
    </ResponseField>

    <ResponseField name="requested_token_type" type="string">
      The type of token to be generated by Auth0. For example: urn:ietf:params:oauth:token-type:access\_token.
    </ResponseField>

    <ResponseField name="subject_token" type="string">
      The subject token provided in the token exchange request.
    </ResponseField>

    <ResponseField name="subject_token_type" type="string">
      The subject\_token\_type provided in the token exchange request.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.secrets`

<ResponseField name="event.secrets" type="secrets">
  Secret values securely associated with this Action.
</ResponseField>


# Login Trigger
Source: https://auth0.com/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger

Learn about the Actions Login Flow and the post-login Action trigger, which is executed after a user logs in and when a Refresh Token is requested.

The Login trigger executes when a user successfully authenticates against an application on an Auth0 tenant. This also includes post-signup authentication.

<Frame>
  <img alt="Diagram showing the Actions Login Flow." />
</Frame>

Actions in this trigger are blocking (synchronous), which means they execute as part of a trigger's process and prevent the rest of the Auth0 pipeline from running until the Action is complete.

## Triggers

### Login / Post Login

The `post-login` trigger is a function executed after a user logs in and when a <Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip> is exchanged.

#### References

* [Event object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object): Provides contextual information about a single user logging in via Auth0.
* [API object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object): Provides methods for changing the behavior of the flow.

## Common use cases

### Access control

A post-login Action can be used to provide custom logic used to deny access to a user who is attempting to access an application:

```javascript lines theme={null}
/**
 * @param {Event} event - Details about the user and the context in which they are logging in.
 * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
 */
exports.onExecutePostLogin = async (event, api) => {
  if (event.user.email && event.user.email.endsWith("@example.com") && event.client.name === "My SPA") {
    api.access.deny(`Access to ${event.client.name} is not allowed.`);
  }
};
```

### Allow access only on weekdays for a specific application

If you have an application that you want to make sure is only accessible during weekdays, you can create the following Action:

```javascript lines theme={null}
/**
 * @param {Event} event - Details about the user and the context in which they are logging in.
 * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
 */
 exports.onExecutePostLogin = async (event, api) => {
  if (event.client.name === "APP_NAME") {
    const d = new Date().getDay();

    if (d === 0 || d === 6) {
      api.access.deny("This app is only available during the week.");
    }
  }
}
```

### Deny access to anyone calling an API

Let's say you want to deny access to all users who are calling an API. This means that you need to deny access depending on the <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> value for your API, which you can find in the **API Audience** field of your API in [Dashboard > Applications > APIs](https://manage.auth0.com/#/apis). To do this, you would create the following Action:

```javascript lines theme={null}
/**
 * @param {Event} event - Details about the user and the context in which they are logging in.
 * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
 */
 exports.onExecutePostLogin = async (event, api) => {
  // In Actions, an API will be referred to as a Resource Server.
  if (event.resource_server && event.resource_server.identifier === "http://todoapi2.api") {
    api.access.deny("end_users_not_allowed");
  }
}
```

### Add user roles to ID and Access tokens

To add user roles to Auth0-issued tokens, use the `event.authorization` object along with the `api.idToken.setCustomClaim` and `api.accessToken.setCustomClaim` methods:

```javascript lines theme={null}
/**
 * @param {Event} event - Details about the user and the context in which they are logging in.
 * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
 */
exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://my-app.example.com';
  if (event.authorization) {
    api.idToken.setCustomClaim(`${namespace}/roles`, event.authorization.roles);
    api.accessToken.setCustomClaim(`${namespace}/roles`, event.authorization.roles);
  }
}
```

* A custom claim cannot include certain terms, and we strongly recommend using namespaced claim that takes the form of a URI. See [our documentation on custom claims](/docs/secure/tokens/json-web-tokens/create-custom-claims) for more information.
* The <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> returned to the requesting application is built and signed at the end of the trigger processing. The final, signed JWT is not accessible in an Action.

### Enrich the user profile

Auth0 provides a system for storing metadata on a [User Profile](/docs/manage-users/user-accounts/user-profiles/normalized-user-profiles). In order to set `user_metadata` or `app_metadata` on a user’s profile during their login, use the `api.user.setUserMetadata` or `api.user.setAppMetadata` functions.

```javascript lines theme={null}
/**
 * @param {Event} event - Details about the user and the context in which they are logging in.
 * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
 */
exports.onExecutePostLogin = async (event, api) => {
  api.user.setUserMetadata("favorite_color", "blue");
};
```

Once all post-login actions have been executed, Actions will update the user profile in a single operation. This operation is subject to the "Write Users" [rate limit](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/management-api-endpoint-rate-limits).

### Enforce custom MFA policy

A post-login Action can be used to dynamically require <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> for a user according to your application’s needs.

```javascript lines theme={null}
/**
 * @param {Event} event - Details about the user and the context in which they are logging in.
 * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
 */
exports.onExecutePostLogin = async (event, api) => {
  // Require MFA for anyone logging in from North America.
  if (event.request.geoip.continentCode === "NA") {
    api.multifactor.enable("any");
  };
};
```

An MFA Provider must be configured in order to enable MFA during a login. To learn more, read [Multi-Factor Authentication](/docs/secure/multi-factor-authentication).

### Reduce friction with passkeys

A post-login Action can be used to reduce the friction by dynamically skipping MFA for a user that has authenticated with a passkey.

```javascript lines theme={null}
/**
* Handler that will be called during the execution of a PostLogin flow.
*
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {
 // Check if a passkey was used to authenticate
 const skipMFA = event.authentication?.methods.some(
   (method) => method.name === "passkey"
 );

 // If a passkey was used skip MFA
 if (skipMFA) {
   api.multifactor.enable("none");
 }
};
```

The connection must have passkeys and MFA enabled. To learn more, read [Passkeys](/docs/authenticate/database-connections/passkeys) and [Multi-Factor Authentication](/docs/secure/multi-factor-authentication).

### Redirect the user to an external site

Similar to [Redirect Rules](/docs/customize/rules/redirect-users), a post-login Action can be used to send the user to an external site. When completed, the user can be redirected back to Auth0 to continue their login flow. In the example below, a Redirect Action is used to prompt the user to provide their favorite color.

```javascript lines expandable theme={null}
/**
 * @param {Event} event - Details about the user and the context in which they are logging in.
 * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
 */
exports.onExecutePostLogin = async (event, api) => {
  // Skip the redirect if the user has already chosen a favorite color.
  if (event.user.user_metadata.favorite_color) {
    return;
  }

  const token = api.redirect.encodeToken({
    secret: event.secrets.MY_SHARED_SECRET,
    payload: {
      email: event.user.email,
    },
  });

  // Send the user to https://my-app.example.com along
  // with a `session_token` query string param.
  api.redirect.sendUserTo("https://my-app.example.com", { 
    query: { session_token: token }
  });
};

/**
 * @param {Event} event - Details about the user and the context in which they are logging in.
 * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
 */
exports.onContinuePostLogin = async (event, api) => {
  // Once the /continue endpoint has been called, unpack the signed token
  // and store the favorite color as user metadata.

  const payload = api.redirect.validateToken({
    secret: event.secrets.MY_SHARED_SECRET,
  });

  api.user.setUserMetadata("favorite_color", payload.favorite_color);
};
```

The Actions pipeline will be suspended while the user is redirected. Once the user continues their Auth0 login process, the Actions pipeline will resume where it was suspended. Actions that were executed prior to the Redirect will not be executed again.

To learn more about Redirect Actions, read [Redirect with Actions](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/redirect-with-actions).

### Modify scopes on an access token

When modifying the scopes associated with an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, ensure you adhere to the best practices surrounding audience specification.

* Always check for expected audience before adding scopes.
* Prevent using untrusted input when adding scopes.

```javascript lines theme={null}
/**
 * @param {Event} event - Details about the user and the context in which they are logging in.
 * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
 */
exports.onExecutePostLogin = async (event, api) => {
  if (event.request.query.audience === 'https://example.com/api') {
    api.accessToken.addScope("read:xyz");
  }
};
```

### Deny access to specific JA3/JA4 fingerprints

The `event.security_context` object contains the JA3/JA4 fingerprint values for the current transaction.

```js lines theme={null}
exports.onExecutePreUserRegistration = async (event, api) => {
  const clientJa4 = event?.security_context?.ja4;
  console.log('[ACTION]', {clientJa4});
  const badFingerprints = ['t13d1517h2_8daaf6152771_b6f405a00624','t13d1516h2_8daaf6152771_d8a2da3f94cd'];
  if (clientJa4 && badFingerprints.includes(clientJa4)){
    api.access.deny('suspicious_tls_fingerprint', 'Your TLS fingerprint has been flagged as suspicious');
  }
};
```

## Learn more

* [Manage User Metadata with the post-login Action Trigger](/docs/manage-users/user-accounts/metadata/manage-user-metadata)
* [Redirect with Actions](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/redirect-with-actions)
* [Understand How Metadata Works in User Profiles](/docs/manage-users/user-accounts/metadata)


# Actions Triggers: post-login - API Object
Source: https://auth0.com/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object

Learn about the post-login Action trigger's API object.

The API object for the post-login Actions trigger includes:

## `api.access`

Modify the access of the user that is logging in, such as rejecting the login attempt.

### `api.access.deny(reason)`

Mark the current login attempt as denied. This will prevent the end-user from completing
the login flow. This will *NOT* cancel other user-related side-effects (such as metadata
changes) requested by this Action. The login flow will immediately stop following the
completion of this action and no further Actions will be executed.

<ResponseField name="reason" type="string">
  A human-readable explanation for rejecting the login. This may be presented
  directly in end-user interfaces.
</ResponseField>

## `api.accessToken`

Request changes to the access token being issued.

### `api.accessToken.setCustomClaim(key, value)`

Set a custom claim on the Access Token that will be issued upon completion of the login flow.

<ResponseField name="key" type="string">
  Name of the claim (note that this may need to be a fully-qualified url).
</ResponseField>

<ResponseField name="value" type="unknown">
  The value of the claim.
</ResponseField>

### `api.accessToken.addScope(scope)`

Add a scope on the Access Token that will be issued upon completion of the login flow.

<ResponseField name="scope" type="string">
  The scope to be added.
</ResponseField>

### `api.accessToken.removeScope(scope)`

Remove a scope on the Access Token that will be issued upon completion of the login flow.

<ResponseField name="scope" type="string">
  The scope to be removed.
</ResponseField>

## `api.authentication`

Request changes to the authentication state of the current user's session.

### `api.authentication.challengeWith(factor, options)`

Request a challenge for multifactor authentication using the supplied factor and optional additional factors.

When a multifactor challenge is requested, subsequent Actions will not be run until that challenge has been
fulfilled by the user. A user will have satisfied the challenge in any of the following situations:

1. They successfully complete the challenge for the default factor.
2. They successfully complete the challenge for any of the optional factors described in `additionalFactors`.

If any of the factors requested has already been challenged successfully in the current transaction, it will
be ignored.

If a factor is requested is not enabled on the tenant, it will be ignored. If a factor is requested that the user
has not enrolled, it will be ignored. If none of the requested factors is enabled or enrolled, the authentication
transaction will fail (i.e. login will not complete).

<Note>
  This method will result in a factor challenge screen being shown if the user has not already satisfied
  the requirements of the challenge. If `additionalFactors` are supplied, the user will have the option to
  select another factor if they choose to.
</Note>

<ResponseField name="factor" type="factorselector">
  An object describing the type of factor its options that should be used for the initial challenge.

  <Expandable title="factor properties">
    <ResponseField name="type" type="string">
      A type of authentication factor such as `push-notification`, `phone`, `email`, `otp`, `webauthn-roaming`, `webauthn-platform`, and `recovery-code`.

      Allowed values: `otp`, `email`, `webauthn-platform`, `webauthn-roaming`, `recovery-code`
    </ResponseField>

    <ResponseField name="options" type="dictionary">
      Additional options for configuring a factor of a given type.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="options" type="challengewithoptions">
  Additional options which can also specify `additionalFactors` as a property. Factor-specific options (for example `otpFallback` for `push-notification`) belong on `factor.options`.

  <Expandable title="options properties">
    <ResponseField name="additionalFactors" type="array of objects" />
  </Expandable>
</ResponseField>

```js Challenge with a specific factor theme={null}
api.authentication.challengeWith({
  type: 'phone',
  options: { preferredMethod: 'both' }
});
```

```js Challenge with additional factors theme={null}
api.authentication.challengeWith({
  type: 'otp'
}, {
  additionalFactors: [{
    type: 'push-notification'
  }, {
    type: 'phone'
  }]
});
```

```js Challenge with push notification and disable OTP fallback theme={null}
api.authentication.challengeWith({
  type: 'push-notification',
  options: { otpFallback: false }
});
```

### `api.authentication.challengeWithAny(factors)`

Request a challenge for multifactor authentication using any of the supplied factors (showing a factor selection
screen first).

When a multifactor challenge is requested, subsequent Actions will not be run until that challenge has been
fulfilled by the user. A user will have satisfied the challenge in any of the following situations:

1. They successfully complete the challenge for any of the factors.

If any of the factors requested has already been challenged successfully in the current transaction, it will
be ignored.

If a factor is requested is not enabled on the tenant, it will be ignored. If a factor is requested that the user
has not enrolled, it will be ignored. If none of the requested factors is enabled or enrolled, the authentication
transaction will fail (i.e. login will not complete).

<Note>
  This method will result in the factor selector screen being shown if the user has not already satisfied
  the requirements of the challenge. If there is a preferred factor, the `api.authentication.challengeWith()` method
  is preferred. The factor selector screen will not be shown if only one factor is passed in or is valid.
</Note>

<ResponseField name="factors" type="array of objects">
  An array of factors.
</ResponseField>

### `api.authentication.enrollWith(factor, options)`

Request an enrollment for multifactor authentication using the supplied factor and optional additional factors.

When a multifactor enrollment is requested, subsequent Actions will not be run until that enrollment has been
fulfilled by the user.

If any of the factors requested has already been enrolled or challenged successfully in the current transaction, it will
be ignored.

If a factor that is not enabled in the tenant is requested, it will be ignored.
If a factor that the user has already enrolled is requested, it will be ignored.
If none of the requested factors is enabled and not enrolled, the authentication
transaction will fail (i.e. login will not complete).

<ResponseField name="factor" type="enrollmentfactorselector">
  An object describing the type of factor that should be used for the initial enrollment prompts and its options.

  <Expandable title="factor properties">
    <ResponseField name="type" type="string">
      A type of authentication factor such as `push-notification`, `phone`, `otp`, `webauthn-roaming`, `webauthn-platform`, and `recovery-code`.

      Possible values:

      * `otp`
      * `webauthn-platform`
      * `webauthn-roaming`
      * `recovery-code`
      * `push`
      * `push-notification`
    </ResponseField>

    <ResponseField name="options" type="dictionary">
      Additional options for configuring a factor of a given type.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="options" type="enrollwithoptions">
  Additional options which can also specify `additionalFactors` as a property.

  <Expandable title="options properties">
    <ResponseField name="additionalFactors" type="array of objects" />
  </Expandable>
</ResponseField>

```js Enroll with additional factors theme={null}
api.authentication.enrollWith({
  type: 'otp'
}, {
  additionalFactors: [{
    type: 'push-notification'
  }, {
    type: 'phone'
  }]
});
```

### `api.authentication.enrollWithAny(factors)`

Request an enrollment for multifactor authentication using any of the supplied factors (showing a factor selection
screen first).

When a multifactor enrollment is requested, subsequent Actions will not be run until that enrollment has been
fulfilled by the user.

If any of the factors requested has already been enrolled successfully in the current transaction, it will
be ignored.

If a factor that is not enabled in the tenant is requested, it will be ignored.
If a factor that the user has already enrolled is requested, it will be ignored.
If none of the requested factors is enabled and not enrolled, the authentication
transaction will fail (i.e. login will not complete).

<Note>
  If there is a preferred factor, the `api.authentication.enrollWith()` method
  is preferred. The factor selector screen will not be shown if only one factor is passed in or is valid.
</Note>

<ResponseField name="factors" type="array of objects">
  An array of additional factors.
</ResponseField>

### `api.authentication.recordMethod(provider_url)`

Indicate that a custom authentication method has been completed in the current
session. This method will then be available in the `event.authentication.methods`
array in subsequent logins.

**IMPORTANT**: This API is only available from within the `onContinuePostLogin`
function for `PostLogin` Actions. In other words, this may be used to record the
completion of a custom authentication method after redirecting the user via
`api.redirect.sendUserTo()`.

<ResponseField name="provider_url" type="string">
  An `http:` or `https:` URL that uniquely represents the completed
  authentication method.
</ResponseField>

### `api.authentication.setPrimaryUser(primary_user_id)`

Change the primary user for the login transaction.

In scenarios that require linking users, the user identity used to initiate the login may no longer
exist as a discrete user. That identity may now be a secondary identity of an existing user. In
such situations, the `setPrimaryUser()` function can be used to indicate that the subject of the
login should be changed.

**IMPORTANT**: Insecurely linking accounts can allow malicious actors to access legitimate
user accounts.

**IMPORTANT**: The identity used to authenticate the login *must* be among the secondary identities
of the user referenced by `primary_user_id`. The login will fail and tokens will not be issued
otherwise.

<ResponseField name="primary_user_id" type="string">
  The user ID of the user for whom tokens should be issued (the `sub` claim).
</ResponseField>

## `api.idToken`

Request changes to the ID token being issued.

### `api.idToken.setCustomClaim(key, value)`

Set a custom claim on the ID Token that will be issued upon completion of the login flow.

<ResponseField name="key" type="string">
  Name of the claim (note that this may need to be a fully-qualified url).
</ResponseField>

<ResponseField name="value" type="unknown">
  The value of the claim.
</ResponseField>

## `api.multifactor`

Set or remove the requirement for multifactor authentication on the login attempt.

### `api.multifactor.enable(provider, options)`

Enable multifactor authentication for this login flow. When enabled, users must complete the
configured multifactor challenge. The actual multifactor challenge will be deferred to the
end of the login flow.

<ResponseField name="provider" type="string">
  The name of the multifactor provider to use or the value `"any"` to use any
  of the configured providers.

  Allowed values: `duo`, `none`, `guardian`, `google-authenticator`, `any`
</ResponseField>

<ResponseField name="options" type="object">
  Additional options for enabling multifactor challenges.

  <Expandable title="options properties">
    <ResponseField name="allowRememberBrowser" type="boolean">
      When provider is set to `google-authenticator` or `duo`, the user is prompted for MFA once
      every 30 days. When provider is set to `guardian`, the MFA prompt displays the enrollment
      checkbox for users to choose whether or not to enroll. Defaults to `false`. To learn more,
      read [Customize Multi-Factor Authentication Pages](https://auth0.com/docs/secure/multi-factor-authentication/customize-mfa).
    </ResponseField>

    <ResponseField name="providerOptions" type="object">
      Additional options to configure the challenge, only available for the `duo` provider.
    </ResponseField>
  </Expandable>
</ResponseField>

## `api.redirect`

Configure and initiate external redirects.

### `api.redirect.encodeToken(options)`

Create a session token suitable for using as a query string parameter redirect target (via `sendUserTo`)
that contains data whose authenticity must be provable by the target endpoint. The target endpoint
can verify the authenticity and integrity of the data by checking the JWT's signature
using a shared secret.

The shared secret should be stored as a **secret** of the Action and will be readable at
`event.secrets['<secret_name>']`.

<ResponseField name="options" type="tokencreationoptions">
  Configure how sensitive data is encoded into the query parameters of the
  resulting url.

  <Expandable title="options properties">
    <ResponseField name="expiresInSeconds" type="number">
      Number of seconds before this token will expire
    </ResponseField>

    <ResponseField name="payload" type="dictionary">
      The data intended to be passed to the target of the redirect and whose authenticity
      and integrity must be provable.
    </ResponseField>

    <ResponseField name="secret" type="string">
      A secret that will be used to sign a JWT that is shared with the redirect target. The
      secret value should be stored as a **secret** and retrieved using
      `event.secrets['<secret_name>']`.
    </ResponseField>
  </Expandable>
</ResponseField>

### `api.redirect.sendUserTo(url, options)`

Cause the login pipeline to trigger a browser redirect to the target `url` immediately after
this action completes. The `createUrl` helper method is provided to simplify encoding
data as a query parameter in the target `url` such that the data's authenticity and
integrity can be verified by the target endpoint.

<ResponseField name="url" type="string" />

<ResponseField name="options" type="sendusertooptions">
  <Expandable title="options properties">
    <ResponseField name="query" type="dictionary">
      An object representing additional query string parameters that should be appended to
      the redirect URL.
    </ResponseField>
  </Expandable>
</ResponseField>

### `api.redirect.canRedirect()`

<Warning>
  **Deprecated.** The `canRedirect` method should not be relied upon to determine whether a
  redirect is allowed or not in this flow. Instead, it is recommended that clients
  appropriately handle any `interaction_required` errors arising from a redirect requested
  in a non-interactive flow.
</Warning>

Indicates if the current transaction is eligibile for a user redirect. Certain protocols such
as `oauth2-resource-owner`, `oauth2-refresh-token` do not support
redirecting the user. A request with `prompt=none` is also not eligible for a redirect.

### `api.redirect.validateToken(options)`

Retrieve the data encoded in a JWT token passed to the `/continue` endpoint while verifying
the authenticity and integrity of that data.

<ResponseField name="options" type="validatesessiontokenoptions">
  Options for retrieving the data encoded in a JWT token passed to the
  `/continue` endpoint following a rediret.

  <Expandable title="options properties">
    <ResponseField name="secret" type="string" />

    <ResponseField name="tokenParameterName" type="string">
      The name of the query or body parameter that was sent to the /continue endpoint.
    </ResponseField>
  </Expandable>
</ResponseField>

## `api.user`

Make changes to the metadata of the user that is logging in.

### `api.user.setAppMetadata(key, value)`

Set application-specific metadata for the user that is logging in.

Note: This method should not be used in callbacks. Invoking this method won't update the metadata immediately.
You can call this several times throughout multiple actions of the same flow and the engine will aggregate the
changes and update the metadata at once before the flow is completed. This function works only with metadata that
are in the object format.

<ResponseField name="key" type="string">
  The metadata property to be set.
</ResponseField>

<ResponseField name="value" type="unknown">
  The value of the metadata property. This may be set to `null` to remove the
  metadata property.
</ResponseField>

### `api.user.setUserMetadata(key, value)`

Set general metadata for the user that is logging in.

Note: This method should not be used in callbacks. Invoking this method won't update the metadata immediately.
You can call this several times throughout multiple actions of the same flow and the engine will aggregate the
changes and update the metadata at once before the flow is completed. This function works only with metadata that
are in the object format.

<ResponseField name="key" type="string">
  The metadata property to be set.
</ResponseField>

<ResponseField name="value" type="unknown">
  The value of the metadata property. This may be set to `null` to remove the
  metadata property.
</ResponseField>

## `api.cache`

Make changes to the cache.

### `api.cache.delete(key)`

Delete a record describing a cached value at the supplied
key if it exists.

<ResponseField name="key" type="string">
  The key of the cache record to delete.
</ResponseField>

### `api.cache.get(key)`

Retrieve a record describing a cached value at the supplied key,
if it exists. If a record is found, the cached value can be found
at the `value` property of the returned object.

<ResponseField name="key" type="string">
  The key of the record stored in the cache.
</ResponseField>

### `api.cache.set(key, value, options)`

Store or update a string value in the cache at the specified key.

Values stored in this cache are scoped to the Trigger in which they
are set. They are subject to the [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations).

Values stored in this way will have lifetimes of *up to* the specified
`ttl` or `expires_at` values. If no lifetime is specified, a default of
lifetime of 24 hours will be used. Lifetimes may not exceed the maximum
duration listed at [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations).

**Important**: This cache is designed for short-lived, ephemeral data. Items may not be
available in later transactions even if they are within their supplied their lifetime.

<ResponseField name="key" type="string">
  The key of the record to be stored.
</ResponseField>

<ResponseField name="value" type="string">
  The value of the record to be stored.
</ResponseField>

<ResponseField name="options" type="cachesetoptions">
  Options for adjusting cache behavior.

  <Expandable title="options properties">
    <ResponseField name="expires_at" type="number">
      The absolute expiry time in milliseconds since the unix epoch.
      While cached records may be evicted earlier, they will
      never remain beyond the the supplied `expires_at`.

      *Note*: This value should not be supplied if a value was also
      provided for `ttl`. If both options are supplied, the
      earlier expiry of the two will be used.
    </ResponseField>

    <ResponseField name="ttl" type="number">
      The time-to-live value of this cache entry in milliseconds.
      While cached values may be evicted earlier, they will
      never remain beyond the the supplied `ttl`.

      *Note*: This value should not be supplied if a value was also
      provided for `expires_at`. If both options are supplied, the
      earlier expiry of the two will be used.
    </ResponseField>
  </Expandable>
</ResponseField>

## `api.samlResponse`

Configure custom SAML configurations and attributes.

### `api.samlResponse.setAttribute(attribute, value)`

Set attributes on the SAML assertion being issued to the authenticated user.

<ResponseField name="attribute" type="string">
  The SAML attribute to be set.
</ResponseField>

<ResponseField name="value" type="samlattributevalue">
  The value of the SAML claim. Setting this value to `null` or
  `undefined` will remove the claim from the assertion.
</ResponseField>

### `api.samlResponse.setAudience(audience)`

Audience of the SAML assertion.
Default is issuer on SAMLRequest.

<ResponseField name="audience" type="string" />

### `api.samlResponse.setRecipient(recipient)`

Recipient of the SAML assertion (SubjectConfirmationData).
Default is AssertionConsumerUrl on SAMLRequest or callback URL if no SAMLRequest was sent.

<ResponseField name="recipient" type="string" />

### `api.samlResponse.setCreateUpnClaim(createUpnClaim)`

Whether or not a UPN claim should be created. Default is true.

<ResponseField name="createUpnClaim" type="boolean" />

### `api.samlResponse.setPassthroughClaimsWithNoMapping(passthroughClaimsWithNoMapping)`

If true (default), for each claim that is not mapped to the common profile, Auth0 passes through those in the output assertion.
If false, those claims won't be mapped.

<ResponseField name="passthroughClaimsWithNoMapping" type="boolean" />

### `api.samlResponse.setMapUnknownClaimsAsIs(mapUnknownClaimsAsIs)`

If passthroughClaimsWithNoMapping is true and this is false (default), for each claim not mapped to the common profile Auth0 adds a prefix `http://schema.auth0.com`.
If true it will pass through the claim as-is.

<ResponseField name="mapUnknownClaimsAsIs" type="boolean" />

### `api.samlResponse.setMapIdentities(mapIdentities)`

If true (default), it adds more information in the token such as the provider (Google, ADFS, AD, etc.) and the access token, if available.

<ResponseField name="mapIdentities" type="boolean" />

### `api.samlResponse.setSignatureAlgorithm(signatureAlgorithm)`

Signature algorithm to sign the SAML assertion or response.
Default is rsa-sha256.

<ResponseField name="signatureAlgorithm" type="string">
  Allowed values: `rsa-sha256`
</ResponseField>

### `api.samlResponse.setSignatureAlgorithm(signatureAlgorithm)`

<Warning>
  **Deprecated.** Use rsa-sha256 instead, rsa-sha1 is not recommended.
</Warning>

<ResponseField name="signatureAlgorithm" type="string">
  Allowed values: `rsa-sha1`
</ResponseField>

### `api.samlResponse.setDigestAlgorithm(digestAlgorithm)`

Digest algorithm to calculate digest of the SAML assertion or response.
Default is sha256.

<ResponseField name="digestAlgorithm" type="string">
  Allowed values: `sha256`
</ResponseField>

### `api.samlResponse.setDigestAlgorithm(digestAlgorithm)`

<Warning>
  **Deprecated.** Use 'sha256' instead, 'sha1' is not recommended.
</Warning>

<ResponseField name="digestAlgorithm" type="string">
  Allowed values: `sha1`
</ResponseField>

### `api.samlResponse.setDestination(destination)`

Destination of the SAML response. If not specified, it will be AssertionConsumerUrl of SAMLRequest or callback URL if there was no SAMLRequest.

<ResponseField name="destination" type="string" />

### `api.samlResponse.setLifetimeInSeconds(lifetimeInSeconds)`

Expiration of the token.
Default is 3600 seconds (1 hour).

<ResponseField name="lifetimeInSeconds" type="number" />

### `api.samlResponse.setSignResponse(signResponse)`

Whether or not the SAML response should be signed.
By default the SAML assertion will be signed, but not the SAML response.
If true, SAML Response will be signed instead of SAML assertion.
Default to false.

<ResponseField name="signResponse" type="boolean" />

### `api.samlResponse.setNameIdentifierFormat(nameIdentifierFormat)`

Default is urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified.

<ResponseField name="nameIdentifierFormat" type="string" />

### `api.samlResponse.setNameIdentifierProbes(nameIdentifierProbes)`

Auth0 will try each of the attributes of this array in order.
If one of them has a value, it will use that for the Subject/NameID.

The order is:

* [http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier) (mapped from user\_id),
* [http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress) (mapped from email),
* [http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name](http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name) (mapped from name).

<ResponseField name="nameIdentifierProbes" type="array of strings" />

### `api.samlResponse.setAuthnContextClassRef(authnContextClassRef)`

Default is urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified.

<ResponseField name="authnContextClassRef" type="string" />

### `api.samlResponse.setSigningCert(signingCert)`

Optionally indicates the public key certificate used to validate SAML requests.
If set, SAML requests will be required to be signed.
A sample value would be "-----BEGIN CERTIFICATE-----\nMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV\n\[..all the other lines..]-----END CERTIFICATE-----\n".

<ResponseField name="signingCert" type="string" />

### `api.samlResponse.setIncludeAttributeNameFormat(includeAttributeNameFormat)`

When set to true, we infer the NameFormat based on the attribute name. NameFormat values are urn:oasis:names:tc:SAML:2.0:attrname-format:uri, urn:oasis:names:tc:SAML:2.0:attrname-format:basic and urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified.
If set to false, the attribute NameFormat is not set in the assertion.
Default is true.

<ResponseField name="includeAttributeNameFormat" type="boolean" />

### `api.samlResponse.setTypedAttributes(typedAttributes)`

When set to true, we infer the xs:type of the element. Types are xs:string, xs:boolean, xs:double and xs:anyType.
When set to false all xs:type are xs:anyType.
Default is true.

<ResponseField name="typedAttributes" type="boolean" />

### `api.samlResponse.setEncryptionCert(encryptionCert)`

Optionally specify a certificate used to encrypt the SAML assertion.
The certificate should be obtained from the service provider.
Both the certificate and public key must be specified.
A sample value would be "-----BEGIN CERTIFICATE-----\nMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV\n\[..all the other lines..]-----END CERTIFICATE-----\n".

<ResponseField name="encryptionCert" type="string" />

### `api.samlResponse.setEncryptionPublicKey(encryptionPublicKey)`

Optionally specify a public key used to encrypt the SAML assertion.
The public key should be obtained from the service provider.
Both the public key and certificate must be specified.
A sample value would be "-----BEGIN PUBLIC KEY-----\nnMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV\n\[..all the other lines..]-----END PUBLIC KEY-----\n".

<ResponseField name="encryptionPublicKey" type="string" />

### `api.samlResponse.setCert(cert)`

By default, Auth0 will use the private/public key pair assigned to your tenant to sign SAML responses or assertions.
For very specific scenarios, you might wish to provide your own certificate and private key.

Both the certificate and private key must be specified.
A sample value would be "-----BEGIN CERTIFICATE-----\nMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV\n\[..all the other lines..]-----END CERTIFICATE-----\n".

<ResponseField name="cert" type="string" />

### `api.samlResponse.setKey(key)`

By default, Auth0 will use the private/public key pair assigned to your tenant to sign SAML responses or assertions.
For very specific scenarios, you might wish to provide your own certificate and private key.

Since this private key is sensitive, **we recommend using the Add Secret functionality of Actions**.
See here for more details: [https://auth0.com/docs/customize/actions/write-your-first-action#add-a-secret](https://auth0.com/docs/customize/actions/write-your-first-action#add-a-secret)

Both the certificate and private key must be specified.
A sample value would be "-----BEGIN PRIVATE KEY-----\nnMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV\n\[..all the other lines..]-----END PRIVATE KEY-----\n".

<ResponseField name="key" type="string" />

### `api.samlResponse.setRelayState(relayState)`

Optionally specify a RelayState used to return to service provider

<ResponseField name="relayState" type="string" />

### `api.samlResponse.setIssuer(issuer)`

Optionally specify the issuer of the SAML assertion.
Default is urn:auth0:TENANT

<ResponseField name="issuer" type="string" />

## `api.validation`

Prevent user from logging in by throwing a validation error.

### `api.validation.error(errorCode, errorMessage)`

Throw an error when there is a validation error.

<ResponseField name="errorCode" type="string">
  A customer defined error code for the validation error.
</ResponseField>

<ResponseField name="errorMessage" type="string">
  A customer defined message for the validation error.
</ResponseField>

## `api.rules`

Identify if a rule has been executed in the current transaction.

### `api.rules.wasExecuted(ruleId)`

Check whether a Rule with a specific ID has been executed in the current transaction.

<ResponseField name="ruleId" type="string">
  The Rule ID.
</ResponseField>

## `api.prompt`

Renders a custom prompt.

### `api.prompt.render(promptId, promptOptions)`

Renders a custom prompt.

<ResponseField name="promptId" type="string">
  The prompt ID.
</ResponseField>

<ResponseField name="promptOptions" type="promptoptions">
  The render options.

  <Expandable title="promptOptions properties">
    <ResponseField name="fields" type="dictionary">
      Key-value pairs to populate field values (client-side).
    </ResponseField>

    <ResponseField name="vars" type="dictionary">
      Key-value pairs to inject variables (server-side).
    </ResponseField>
  </Expandable>
</ResponseField>

## `api.refreshToken`

Request changes to the current user's refresh token.

### `api.refreshToken.revoke(reason)`

\[Enterprise Customers] Revoke the current user refresh token and mark the current refresh token exchange attempt as denied. This will prevent
the end-user from completing the refresh token exchange flow and revoke the currently used refresh token.
The refresh token exchange flow will immediately stop following the completion of this action and no further Actions will be executed.

This method can be used only during Refresh Token Exchange flow, when `event.transaction.protocol === "oauth2-refresh-token"`.

<ResponseField name="reason" type="string">
  A human-readable explanation for rejecting the refresh token exchange. This may be presented
  directly in end-user interfaces.
</ResponseField>

### `api.refreshToken.setExpiresAt(absolute)`

\[Enterprise Customers] Sets a new absolute expiration time for the current refresh token.
The expiration cannot be set higher than the maximum refresh token lifetime set in the settings.
When called multiple times, the earliest expiration time will be used.

<ResponseField name="absolute" type="number">
  Required, the new absolute expiration time in milliseconds since the unix epoch, after which the Refresh Token will be considered invalid.
</ResponseField>

### `api.refreshToken.setIdleExpiresAt(inactivity)`

\[Enterprise Customers] Sets a new idle expiration time for the current refresh token.
The expiration cannot be set higher than the maximum absolute refresh token lifetime set in the settings.
When called multiple times, the earliest expiration time will be used.

<ResponseField name="inactivity" type="number">
  Required, the new idle inactivity time in milliseconds since the unix epoch, after which the Refresh Token will be considered invalid
  if it is not used during this period.
</ResponseField>

## `api.session`

Request changes to the current user's session.

### `api.session.revoke(reason, options)`

\[Enterprise Customers] Revoke the current user session and mark the current login attempt as denied. This will prevent
the end-user from completing the login flow and revoke their session. The login flow will immediately
stop following the completion of this action and no further Actions will be executed.

<ResponseField name="reason" type="string">
  A human-readable explanation for rejecting the login. This may be presented
  directly in end-user interfaces.
</ResponseField>

<ResponseField name="options" type="sessionrevocationoptions">
  <Expandable title="options properties">
    <ResponseField name="preserveRefreshTokens" type="boolean">
      Default to false. If true, the system ends the session and keeps the refresh tokens. The application may continue to get access tokens for the duration of the refresh token lifetime.
    </ResponseField>
  </Expandable>
</ResponseField>

```js Revoke the session while preserving refresh tokens theme={null}
api.session.revoke('reason', { preserveRefreshTokens: true });
```

### `api.session.setExpiresAt(absolute)`

\[Enterprise Customers] Sets a new absolute expiration time for the current session.
The expiration cannot be set higher than the maximum session lifetime set in the tenant settings.
When called multiple times, the earliest expiration time will be used.

<ResponseField name="absolute" type="number">
  Required, the new absolute expiration time in milliseconds since the unix epoch, after which the Session will be considered invalid.
</ResponseField>

### `api.session.setIdleExpiresAt(inactivity)`

\[Enterprise Customers] Sets a new idle expiration time for the current session.
The expiration cannot be set higher than the maximum absolute session lifetime set in the tenant settings.
When called multiple times, the earliest expiration time will be used.

<ResponseField name="inactivity" type="number">
  Required, the new inactivity expiration time in milliseconds since the unix epoch, after which the Session will be considered invalid if there
  is no user interaction during this period.
</ResponseField>

### `api.session.setCookieMode(mode)`

\[Enterprise Customers] \[Early Access] Sets the cookie mode for the current session, allowing it to be either 'persistent' or 'non-persistent' (ephemeral).
This determines how the session cookie is handled in the browser:

* 'persistent': The cookie will be stored until it expires or is deleted by the user.
* 'non-persistent' (ephemeral): The cookie will be deleted when the browser is closed.

If multiple setCookieMode invocations are made, only the last one will take effect. In case 'non-persistent' is set, the cookie will be deleted when the browser is closed, however, the session itself will remain valid until its absolute or idle expiration time is reached
or the session is revoked through our available APIs. For more information on cookie modes, please refer to our documentation.

<ResponseField name="mode" type="string">
  Required, the cookie mode for the current session.
  Can be either 'persistent' or 'non-persistent' (ephemeral).

  Allowed values: `persistent`, `non-persistent`
</ResponseField>

### `api.session.setMetadata(key, value)`

\[Enterprise Customers] \[Limited Early Access] Sets a key value pair in the metadata object of the current session.

<ResponseField name="key" type="string">
  Required, the key to set in the metadata object.
</ResponseField>

<ResponseField name="value" type="string">
  Required, the value to set for the key in the metadata object, null values will delete the provided metadata key.
</ResponseField>

### `api.session.deleteMetadata(key)`

\[Enterprise Customers] \[Limited Early Access] Deletes a key in the metadata object of the current session.

<ResponseField name="key" type="string">
  Required, the key to delete from the metadata object.
</ResponseField>

### `api.session.evictMetadata()`

\[Enterprise Customers] \[Limited Early Access] Deletes all keys from the metadata object of the current session.

## `api.transaction`

Make changes to the transaction.

### `api.transaction.setMetadata(key, value)`

Store or update the value in the transaction metadata for a specified key.

Metadata modified using this method is updated in real-time in the
`event.transaction.metadata` object.

<ResponseField name="key" type="string">
  The key of the property to be set.
</ResponseField>

<ResponseField name="value" type="txmetadatavalue">
  The value of the property. This may be set to `null` to remove the
  metadata property.
</ResponseField>


# Actions Triggers: post-login - Event Object
Source: https://auth0.com/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object

Learn about the post-login Action trigger's event object, which provides contextual information about the trigger execution.

The `event` object for the post-login Actions trigger provides contextual information about the trigger execution.

## `event.authentication`

<ResponseField name="event.authentication" type="dictionary">
  Details about authentication signals obtained during the login flow.

  <Expandable title="authentication properties">
    <ResponseField name="methods" type="array of objects">
      Contains the authentication methods a user has completed during their session.

      Array elements can be one of the following schemas:

      <Tabs>
        <Tab title="First Factor">
          <ResponseField name="name" type="string">
            The name of the first factor that was completed. Values include the following:

            * `federated` A social or enterprise connection was used to authenticate the user as the first factor.
            * `pwd` A password was used to authenticate a database connection user as the first factor.
            * `passkey` A passkey was used to authenticate a database connection user as the first factor.
            * `sms` A Passwordless SMS connection was used to authenticate the user as the first factor.
            * `email` A Passwordless Email connection was used to authenticate the user as the first factor or verify email for password reset.
            * `phone_number` A phone number was used for password reset.
            * `mock` Used for internal testing.
            * May also be a URL denoting a custom authentication method (as second or later factor).
          </ResponseField>

          <ResponseField name="timestamp" type="string" />
        </Tab>

        <Tab title="Multi-factor Authentication">
          <ResponseField name="name" type="string">
            The user completed multi-factor authentication (second or later factors).

            Allowed values: `mfa`
          </ResponseField>

          <ResponseField name="timestamp" type="string" />
        </Tab>
      </Tabs>
    </ResponseField>

    <ResponseField name="riskAssessment" type="dictionary">
      Details about risk assessments obtained during the login or password reset flow.

      <Expandable title="riskAssessment properties">
        <ResponseField name="assessments" type="object">
          <Expandable title="assessments properties">
            <ResponseField name="ImpossibleTravel" type="object">
              Determines if the user is logging in from a location signaling impossible travel.

              <Expandable title="ImpossibleTravel properties">
                <ResponseField name="code" type="string">
                  Possible values:

                  * `minimal_travel_from_last_login`
                  * `travel_from_last_login`
                  * `substantial_travel_from_last_login`
                  * `impossible_travel_from_last_login`
                  * `invalid_travel`
                  * `missing_geoip`
                  * `anonymous_proxy`
                  * `unknown_location`
                  * `initial_login`
                  * `location_history_not_found`
                  * `assessment_not_available`
                </ResponseField>

                <ResponseField name="confidence" type="string">
                  Allowed values: `low`, `medium`, `high`, `neutral`
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="NewDevice" type="object">
              Determines if the user is logging in from a known device.

              <Expandable title="NewDevice properties">
                <ResponseField name="code" type="string">
                  Possible values:

                  * `initial_login`
                  * `assessment_not_available`
                  * `match`
                  * `partial_match`
                  * `no_match`
                  * `unknown_device`
                  * `no_device_history`
                </ResponseField>

                <ResponseField name="confidence" type="string">
                  Allowed values: `low`, `medium`, `high`, `neutral`
                </ResponseField>

                <ResponseField name="details" type="object">
                  <Expandable title="details properties">
                    <ResponseField name="device" type="string">
                      Allowed values: `known`, `unknown`
                    </ResponseField>

                    <ResponseField name="useragent" type="string">
                      Allowed values: `known`, `unknown`
                    </ResponseField>
                  </Expandable>
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="UntrustedIP" type="object">
              Shows if the IP was found in Auth0's repository of low reputation IPs.

              <Expandable title="UntrustedIP properties">
                <ResponseField name="code" type="string">
                  Allowed values: `assessment_not_available`, `not_found_on_deny_list`, `found_on_deny_list`, `invalid_ip_address`
                </ResponseField>

                <ResponseField name="confidence" type="string">
                  Allowed values: `low`, `medium`, `high`, `neutral`
                </ResponseField>

                <ResponseField name="details" type="object">
                  <Expandable title="details properties">
                    <ResponseField name="category" type="string" />

                    <ResponseField name="ip" type="string">
                      The originating IP address of the request.
                    </ResponseField>

                    <ResponseField name="matches" type="string" />

                    <ResponseField name="source" type="string" />
                  </Expandable>
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="confidence" type="string">
          Overall risk score

          Allowed values: `low`, `medium`, `high`, `neutral`
        </ResponseField>

        <ResponseField name="supplemental" type="dictionary">
          \[Limited Early Access] Supplemental risk assessment.

          <Expandable title="supplemental properties">
            <ResponseField name="akamai" type="dictionary">
              <Expandable title="akamai properties">
                <ResponseField name="akamaiBot" type="object">
                  The bot detection results as forwarded by Akamai Bot Manager.

                  <Expandable title="akamaiBot properties">
                    <ResponseField name="type" type="string">
                      The type of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="action" type="string">
                      The action of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="botCategory" type="array of strings">
                      The bot category of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="botScore" type="number">
                      The bot score of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="botScoreResponseSegment" type="string">
                      The bot score response segment of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="botnetId" type="string">
                      The botnet ID of the Akamai bot manager results.
                    </ResponseField>
                  </Expandable>
                </ResponseField>

                <ResponseField name="akamaiUserRisk" type="dictionary">
                  The user risk detection results as forwarded by Akamai Account Protector.

                  <Expandable title="akamaiUserRisk properties">
                    <ResponseField name="action" type="string">
                      The action of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="allow" type="number">
                      The allowed status of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="emailDomain" type="string">
                      The email domain of the user.
                    </ResponseField>

                    <ResponseField name="general" type="dictionary">
                      The general risk of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="ouid" type="string">
                      The OUID of the user.
                    </ResponseField>

                    <ResponseField name="requestid" type="string">
                      The request ID of the user.
                    </ResponseField>

                    <ResponseField name="risk" type="dictionary">
                      The risk of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="score" type="number">
                      The score of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="status" type="number">
                      The status of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="trust" type="dictionary">
                      The trust of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="username" type="string">
                      The username of the user.
                    </ResponseField>

                    <ResponseField name="uuid" type="string">
                      The UUID of the Akamai user risk assessment.
                    </ResponseField>
                  </Expandable>
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="version" type="string" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.authorization`

<ResponseField name="event.authorization" type="object">
  An object containing information describing the authorization granted to the user who is logging in.

  <Expandable title="authorization properties">
    <ResponseField name="roles" type="array of strings">
      An array containing the names of a user's assigned roles.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.client`

<ResponseField name="event.client" type="dictionary">
  Information about the Client with which this login transaction was initiated.

  <Expandable title="client properties">
    <ResponseField name="client_id" type="string">
      The client id of the application to which the user is logging in.
    </ResponseField>

    <ResponseField name="metadata" type="dictionary">
      An object for holding other application properties.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the application (as defined in the Dashboard).
    </ResponseField>

    <ResponseField name="refresh_token" type="object">
      \[Private Early Access] An object for holding refresh token configuration properties.

      <Expandable title="refresh_token properties">
        <ResponseField name="policies" type="array of objects">
          \[Private Early Access] A collection of policies governing multi-resource refresh token exchange (MRRT), defining how refresh tokens can be used across different resource servers

          <Expandable title="policies properties">
            <ResponseField name="audience" type="string">
              \[Private Early Access] The specific resource server (audience) to which this MRRT policy applies.
            </ResponseField>

            <ResponseField name="scope" type="array of strings">
              The scopes of access that are authorized for the resource server (audience).
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.connection`

<ResponseField name="event.connection" type="dictionary">
  Details about the Connection that was used to authenticate the user.

  <Expandable title="connection properties">
    <ResponseField name="id" type="string">
      The connection's unique identifier.
    </ResponseField>

    <ResponseField name="metadata" type="dictionary">
      Metadata associated with the connection.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the connection used to authenticate the user (such as `twitter` or `some-g-suite-domain`).
    </ResponseField>

    <ResponseField name="strategy" type="string">
      The type of connection. For social connections, `event.connection.strategy === event.connection.name`. For enterprise connections, the strategy is `waad` (Windows Azure AD), `ad` (Active Directory/LDAP), `auth0` (database connections), and so on.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.custom_domain`

<ResponseField name="event.custom_domain" type="dictionary">
  Details about the custom domain associated with the current transaction.

  <Expandable title="custom_domain properties">
    <ResponseField name="domain" type="string">
      The custom domain name.
    </ResponseField>

    <ResponseField name="domain_metadata" type="dictionary">
      Custom domain metadata as key-value pairs.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.organization`

<ResponseField name="event.organization" type="dictionary">
  Details about the Organization associated with the current transaction.

  <Expandable title="organization properties">
    <ResponseField name="id" type="string">
      The Organization identifier.
    </ResponseField>

    <ResponseField name="display_name" type="string">
      The friendly name of the Organization.
    </ResponseField>

    <ResponseField name="metadata" type="dictionary">
      Metadata associated with the Organization.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the Organization.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.prompt`

<ResponseField name="event.prompt" type="dictionary">
  Collected data from rendered custom prompts.

  <Expandable title="prompt properties">
    <ResponseField name="id" type="string">
      The prompt ID.
    </ResponseField>

    <ResponseField name="fields" type="dictionary">
      Fields and hidden fields data.
    </ResponseField>

    <ResponseField name="vars" type="dictionary">
      Shared variables data.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.refresh_token`

<ResponseField name="event.refresh_token" type="object">
  \[Enterprise Customers] The current refresh token.

  <Expandable title="refresh_token properties">
    <ResponseField name="id" type="string">
      \[Enterprise Customers] The ID of the refresh token.
    </ResponseField>

    <ResponseField name="client_id" type="string">
      \[Enterprise Customers] The ID of the client associated with the refresh token.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      \[Enterprise Customers] Timestamp of when the refresh token was created.
    </ResponseField>

    <ResponseField name="device" type="object">
      <Expandable title="device properties">
        <ResponseField name="initial_asn" type="string">
          \[Enterprise Customers] First autonomous system number associated with this refresh token.
        </ResponseField>

        <ResponseField name="initial_ip" type="string">
          \[Enterprise Customers] First IP address associated with this refresh token.
        </ResponseField>

        <ResponseField name="initial_user_agent" type="string">
          \[Enterprise Customers] First user agent of the device associated with this refresh token.
        </ResponseField>

        <ResponseField name="last_asn" type="string">
          \[Enterprise Customers] Last autonomous system number from which this refresh token was last exchanged.
        </ResponseField>

        <ResponseField name="last_ip" type="string">
          \[Enterprise Customers] Last IP address from which this refresh token was last exchanged.
        </ResponseField>

        <ResponseField name="last_user_agent" type="string">
          \[Enterprise Customers] Last user agent of the device from which this refresh token was last exchanged.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="expires_at" type="string">
      \[Enterprise Customers] Timestamp of when the refresh token will absolutely expire.
    </ResponseField>

    <ResponseField name="idle_expires_at" type="string">
      \[Enterprise Customers] Timestamp of when the refresh token will idle expire.
    </ResponseField>

    <ResponseField name="last_exchanged_at" type="string">
      \[Enterprise Customers] Timestamp of when the refresh token was last successfully exchanged.
    </ResponseField>

    <ResponseField name="resource_servers" type="array of objects">
      <Expandable title="resource_servers properties">
        <ResponseField name="audience" type="string">
          \[Enterprise Customers] The audience of the refresh token.
        </ResponseField>

        <ResponseField name="scopes" type="string">
          \[Enterprise Customers] Scopes of the refresh token.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="rotating" type="boolean">
      \[Enterprise Customers] If the refresh token is a rotating refresh token.
    </ResponseField>

    <ResponseField name="session_id" type="string">
      \[Enterprise Customers] The ID of the session bound to the refresh token.
    </ResponseField>

    <ResponseField name="session_transfer" type="object">
      \[Enterprise Customers] This object is defined when the session is created from a session transfer token (Native to Web SSO), undefined otherwise.

      <Expandable title="session_transfer properties">
        <ResponseField name="parent_refresh_token" type="object">
          \[Enterprise Customers] This object is defined when the refresh token is created from a session initiated as a result of session transfer (Native to Web SSO), undefined otherwise.

          <Expandable title="parent_refresh_token properties">
            <ResponseField name="id" type="string">
              \[Enterprise Customers] The ID of the parent refresh token from which this session/refresh token was created as a result of a session transfer (Native to Web SSO).
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="user_id" type="string">
      \[Enterprise Customers] The ID of the user bound to the refresh token.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.request`

<ResponseField name="event.request" type="dictionary">
  Details about the request that initiated the transaction.

  <Expandable title="request properties">
    <ResponseField name="asn" type="string">
      The ASN (autonomous system number) of the user-agent making the request.
    </ResponseField>

    <ResponseField name="body" type="dictionary">
      The body of the POST request. This data will only be available during refresh token and Client Credential Exchange flows and Post Login Action.
    </ResponseField>

    <ResponseField name="geoip" type="dictionary">
      <Expandable title="geoip properties">
        <ResponseField name="cityName" type="string" />

        <ResponseField name="continentCode" type="string" />

        <ResponseField name="countryCode" type="string" />

        <ResponseField name="countryCode3" type="string" />

        <ResponseField name="countryName" type="string" />

        <ResponseField name="latitude" type="number" />

        <ResponseField name="longitude" type="number" />

        <ResponseField name="subdivisionCode" type="string" />

        <ResponseField name="subdivisionName" type="string" />

        <ResponseField name="timeZone" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="hostname" type="string">
      The hostname that is being used for the authentication flow.
    </ResponseField>

    <ResponseField name="ip" type="string">
      The originating IP address of the request.
    </ResponseField>

    <ResponseField name="language" type="string">
      The language requested by the browser.
    </ResponseField>

    <ResponseField name="method" type="string">
      The HTTP method used for the request
    </ResponseField>

    <ResponseField name="query" type="dictionary">
      The query string parameters sent to the authorization request.
    </ResponseField>

    <ResponseField name="user_agent" type="string">
      The value of the `User-Agent` header received when initiating the transaction.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.resource_server`

<ResponseField name="event.resource_server" type="object">
  Details about the resource server to which the access is being requested.

  <Expandable title="resource_server properties">
    <ResponseField name="identifier" type="string">
      The identifier of the resource server. For example: `https://your-api.example.com`.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.security_context`

<ResponseField name="event.security_context" type="object">
  An object containing fingerprint signatures. This will be available only if the client is using cloudflare. The JA3/JA4 fingerprint can be null or empty in some cases. The most common case is for HTTP requests because JA3 and JA4 are calculated in TLS. It can also be empty due to the Worker sending requests within the same zone or to a zone that is not proxied (or a third party).

  <Expandable title="security_context properties">
    <ResponseField name="ja3" type="string">
      JA3 fingerprint signature. This will be available only if the client is using a TLS connection.
    </ResponseField>

    <ResponseField name="ja4" type="string">
      JA4 fingerprint signature. This will be available only if the client is using a TLS connection.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.session`

<ResponseField name="event.session" type="dictionary">
  The current login session.

  <Expandable title="session properties">
    <ResponseField name="id" type="string">
      The ID of the current session.
    </ResponseField>

    <ResponseField name="authenticated_at" type="string">
      \[Enterprise Customers] The date and time when the session was last authenticated.
    </ResponseField>

    <ResponseField name="clients" type="array of objects">
      \[Enterprise Customers] List of client details for the session.

      <Expandable title="clients properties">
        <ResponseField name="client_id" type="string">
          \[Enterprise Customers] ID of client for the session.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="cookie" type="object">
      \[Enterprise Customers] Cookie configuration for the session, which determines how the session cookie is handled by the User Agent.

      <Expandable title="cookie properties">
        <ResponseField name="mode" type="string">
          \[Enterprise Customers] The persistence mode of the session cookie. When set to 'non-persistent' (ephemeral), the cookie will be deleted when the browser is closed. When set to 'persistent', the cookie will be stored until it expires or is deleted by the user.

          Allowed values: `persistent`, `non-persistent`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="string">
      \[Enterprise Customers] The date and time when the session was created.
    </ResponseField>

    <ResponseField name="device" type="object">
      \[Enterprise Customers] Metadata related to the device used in the session.

      <Expandable title="device properties">
        <ResponseField name="initial_asn" type="string">
          \[Enterprise Customers] First autonomous system number associated with this session.
        </ResponseField>

        <ResponseField name="initial_ip" type="string">
          \[Enterprise Customers] First IP address associated with this session.
        </ResponseField>

        <ResponseField name="initial_user_agent" type="string">
          \[Enterprise Customers] First user agent of the device associated with this session.
        </ResponseField>

        <ResponseField name="last_asn" type="string">
          \[Enterprise Customers] Last autonomous system number from which this user logged in.
        </ResponseField>

        <ResponseField name="last_ip" type="string">
          \[Enterprise Customers] Last IP address from which this user logged in.
        </ResponseField>

        <ResponseField name="last_user_agent" type="string">
          \[Enterprise Customers] Last user agent of the device from which this user logged in.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="expires_at" type="string">
      \[Enterprise Customers] The date and time when the session will expire.
    </ResponseField>

    <ResponseField name="idle_expires_at" type="string">
      \[Enterprise Customers] The date and time when the session will expire if idle.
    </ResponseField>

    <ResponseField name="last_interacted_at" type="string">
      \[Enterprise Customers] The date and time when the session was last successfully interacted with.
    </ResponseField>

    <ResponseField name="metadata" type="dictionary">
      \[Enterprise Customers] \[Limited Early Access] Session Metadata
    </ResponseField>

    <ResponseField name="session_transfer" type="dictionary">
      \[Enterprise Customers] \[Limited Early Access] This object is defined when the session is created from a session transfer token (Native to Web SSO), undefined otherwise.

      <Expandable title="session_transfer properties">
        <ResponseField name="parent_refresh_token" type="dictionary">
          \[Enterprise Customers] This object is defined when the refresh token is created from a session initiated as a result of session transfer (Native to Web SSO), undefined otherwise.

          <Expandable title="parent_refresh_token properties">
            <ResponseField name="id" type="string">
              \[Enterprise Customers] The ID of the parent refresh token from which this session/refresh token was created as a result of a session transfer (Native to Web SSO).
            </ResponseField>

            <ResponseField name="metadata" type="dictionary">
              \[Enterprise Customers] The metadata of the parent refresh token from which this session/refresh token was created as a result of a session transfer (Native to Web SSO).
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      \[Enterprise Customers] The date and time when the session was last updated.
    </ResponseField>

    <ResponseField name="user_id" type="string">
      \[Enterprise Customers] ID of the user which can be used when interacting with other APIs.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.session_transfer_token`

<ResponseField name="event.session_transfer_token" type="dictionary">
  \[Private Early Access] Details of the current session transfer token being used to establish Single Sign-On (SSO) from a native application to a web application.

  <Expandable title="session_transfer_token properties">
    <ResponseField name="client_id" type="string">
      \[Private Early Access] The client identifier of the application that issued the token.
    </ResponseField>

    <ResponseField name="request" type="dictionary">
      \[Private Early Access] Details about the request that issued the token.

      <Expandable title="request properties">
        <ResponseField name="asn" type="string">
          \[Private Early Access] The Autonomous System Number (ASN) associated with the request that issued the token.
        </ResponseField>

        <ResponseField name="geoip" type="dictionary">
          <Expandable title="geoip properties">
            <ResponseField name="cityName" type="string" />

            <ResponseField name="continentCode" type="string" />

            <ResponseField name="countryCode" type="string" />

            <ResponseField name="countryCode3" type="string" />

            <ResponseField name="countryName" type="string" />

            <ResponseField name="latitude" type="number" />

            <ResponseField name="longitude" type="number" />

            <ResponseField name="subdivisionCode" type="string" />

            <ResponseField name="subdivisionName" type="string" />

            <ResponseField name="timeZone" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="ip" type="string">
          \[Private Early Access] The IP address associated with the request that issued the token.
        </ResponseField>

        <ResponseField name="user_agent" type="string">
          \[Private Early Access] The User-Agent string of the device that issued the token.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="scope" type="array of strings">
      \[Private Early Access] The scopes requested when the token was issued.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.stats`

<ResponseField name="event.stats" type="object">
  Login statistics for the current user.

  <Expandable title="stats properties">
    <ResponseField name="logins_count" type="number">
      The number of times this user has logged in.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.tenant`

<ResponseField name="event.tenant" type="object">
  Details about the Tenant associated with the current transaction.

  <Expandable title="tenant properties">
    <ResponseField name="id" type="string">
      The name of the tenant.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.transaction`

<ResponseField name="event.transaction" type="dictionary">
  Details about the current transaction.

  <Expandable title="transaction properties">
    <ResponseField name="id" type="string">
      Unique identifier for the transaction. Populated for all browser-based login flows.
    </ResponseField>

    <ResponseField name="acr_values" type="array of strings">
      Any acr\_values provided in the original authentication request.
    </ResponseField>

    <ResponseField name="linking_id" type="string">
      Dynamic Linking ID that allows developers to reference this transaction.
    </ResponseField>

    <ResponseField name="locale" type="string">
      The locale to be used for this transaction as determined by comparing the browser's requested languages to the tenant's language settings.
    </ResponseField>

    <ResponseField name="login_hint" type="string">
      Hint to the Authorization Server about the login identifier the End-User might use to log in (if necessary).
    </ResponseField>

    <ResponseField name="prompt" type="array of strings">
      List of instructions indicating whether the user may be prompted for re-authentication and consent.
    </ResponseField>

    <ResponseField name="protocol" type="string">
      Possible values:

      * `oidc-basic-profile`
      * `oidc-ciba`
      * `oidc-ciba-web-link`
      * `oidc-implicit-profile`
      * `oauth2-device-code`
      * `oauth2-resource-owner`
      * `oauth2-resource-owner-jwt-bearer`
      * `oauth2-password`
      * `oauth2-webauthn`
      * `oauth2-access-token`
      * `oauth2-refresh-token`
      * `oauth2-token-exchange`
      * `oidc-hybrid-profile`
      * `samlp`
      * `wsfed`
      * `wstrust-usernamemixed`
    </ResponseField>

    <ResponseField name="redirect_uri" type="string">
      The URL to which Auth0 will redirect the browser after the transaction is completed.
    </ResponseField>

    <ResponseField name="requested_authorization_details" type="array of objects">
      The details of a rich authorization request per Section 2 of the Rich Authorization Requests spec at [https://datatracker.ietf.org/doc/html/draft-ietf-oauth-rar#section-2](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-rar#section-2).

      <Expandable title="requested_authorization_details properties">
        <ResponseField name="type" type="string">
          The type of authorization details as a string. The value of the type field determines the allowable contents of the object which contains it.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="requested_scopes" type="array of strings">
      The scopes requested (if any) when starting this authentication flow.
    </ResponseField>

    <ResponseField name="response_mode" type="string">
      Informs the Authorization Server of the mechanism to be used for returning parameters from the Authorization Endpoint.

      Allowed values: `query`, `fragment`, `form_post`, `web_message`
    </ResponseField>

    <ResponseField name="response_type" type="array of strings">
      Denotes the kind of credential that Auth0 will return.
    </ResponseField>

    <ResponseField name="state" type="string">
      An opaque arbitrary alphanumeric string your app adds to the initial request that Auth0 includes when redirecting back to your application.
    </ResponseField>

    <ResponseField name="ui_locales" type="array of strings">
      The ui\_locales provided in the original authentication request.
    </ResponseField>

    <ResponseField name="correlation_id" type="string">
      Correlation ID can be provided in the initial authentication request when the application redirects to Universal Login. You can use value to correlate logs and requests from your Action code with the user flow.
    </ResponseField>

    <ResponseField name="metadata" type="dictionary">
      An object containing shared data across custom Actions for the duration of a transaction.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.user`

<ResponseField name="event.user" type="dictionary">
  An object describing the user on whose behalf the current transaction was initiated.

  <Expandable title="user properties">
    <ResponseField name="app_metadata" type="dictionary">
      Custom fields that store info about a user that influences the user's access, such as support plan, security roles, or access control groups.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Timestamp indicating when the user profile was first created.
    </ResponseField>

    <ResponseField name="email" type="string">
      (unique) User's email address.
    </ResponseField>

    <ResponseField name="email_verified" type="boolean">
      Indicates whether the user has verified their email address.
    </ResponseField>

    <ResponseField name="family_name" type="string">
      User's family name.
    </ResponseField>

    <ResponseField name="given_name" type="string">
      User's given name.
    </ResponseField>

    <ResponseField name="last_password_reset" type="string">
      Timestamp indicating the last time the user's password was reset/changed. At user creation, this field does not exist. This property is only available for Database connections.
    </ResponseField>

    <ResponseField name="name" type="string">
      User's full name.
    </ResponseField>

    <ResponseField name="nickname" type="string">
      User's nickname.
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      User's phone number.
    </ResponseField>

    <ResponseField name="phone_verified" type="boolean">
      Indicates whether the user has verified their phone number.
    </ResponseField>

    <ResponseField name="picture" type="string">
      URL pointing to the [user's profile picture](https://auth0.com/docs/users/change-user-picture).
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      Timestamp indicating when the user's profile was last updated/modified.
    </ResponseField>

    <ResponseField name="user_id" type="string">
      (unique) User's unique identifier.
    </ResponseField>

    <ResponseField name="user_metadata" type="dictionary">
      Custom fields that store info about a user that does not impact what they can or cannot access, such as work address, home address, or user preferences.
    </ResponseField>

    <ResponseField name="username" type="string">
      (unique) User's username.
    </ResponseField>

    <ResponseField name="enrolledFactors" type="array of objects">
      An an array of authentication factors that the user has enrolled.

      <Expandable title="enrolledFactors properties">
        <ResponseField name="type" type="string">
          The type of authentication factor such as `push-notification`, `phone`, `email`, `otp`, `webauthn-roaming` and `webauthn-platform`.
        </ResponseField>

        <ResponseField name="options" type="dictionary">
          Additional options describing this instance of the enrolled factor.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="multifactor" type="array of strings">
      List of multi-factor authentication (MFA) providers with which the user is enrolled. This array is updated when the user enrolls in MFA and when an administrator resets a user's MFA enrollments.
    </ResponseField>

    <ResponseField name="identities" type="array of objects">
      Contains info retrieved from the identity provider with which the user originally authenticates. Users may also link their profile to multiple identity providers; those identities will then also appear in this array. The contents of an individual identity provider object varies by provider.

      <Expandable title="identities element properties">
        <ResponseField name="connection" type="string">
          Name of the Auth0 connection used to authenticate the user.
        </ResponseField>

        <ResponseField name="isSocial" type="boolean">
          Indicates whether the connection is a social one.
        </ResponseField>

        <ResponseField name="profileData" type="dictionary">
          User information associated with the connection. When profiles are linked, it is populated with the associated user info for secondary accounts.
        </ResponseField>

        <ResponseField name="provider" type="string">
          Name of the entity that is authenticating the user, such as Facebook, Google, SAML, or your own provider.
        </ResponseField>

        <ResponseField name="user_id" type="string">
          User's unique identifier for this connection/provider.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.secrets`

<ResponseField name="event.secrets" type="secrets">
  Secret values securely associated with this Action.
</ResponseField>


# Redirect with Actions
Source: https://auth0.com/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/redirect-with-actions

Learn how to use post-login Actions to redirect users before an authentication transaction is complete.

You can use post-login Actions to redirect users before an authentication transaction is complete. This lets you implement custom authentication flows that require additional user interaction beyond the standard login form.

Redirects are commonly used to do custom [Multi-factor Authentication (MFA)](/docs/secure/multi-factor-authentication) in Auth0, but they can also be used to:

* Allow for custom privacy policy acceptance, terms of service, and data disclosure forms.
* Perform a one-time collection of additional required profile data securely.
* Allow remote Active Directory users to change their password.
* Require users to provide additional verification when logging in from unknown locations.
* Gather more information about your users than they provided at initial signup.

## Overview

At a high level, a Redirect Action works in the following manner:

1. An Action issues a redirect to a URL.
2. The Actions pipeline is suspended after that Action completes its execution.
3. The user is redirected to the URL along with a `state` parameter.
4. When the external flow has concluded, the external site redirects the user to a `/continue` endpoint along with the `state` parameter.
5. The Actions pipeline is resumed on the same Action that invoked the redirect.

## Start a redirect

Call the `api.redirect.sendUserTo()` function as follows:

```javascript lines theme={null}
/**
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {
  api.redirect.sendUserTo("https://my-app.exampleco.com");
};
```

Actions will finish the execution of this Action, and then suspend the actions pipeline to send the user to the `https://my-app.exampleco.com`. In other words, any Actions that are bound to the post-login triggers that run after the Action invoking the redirect will not execute until the authentication flow has been resumed. If you are familiar with Redirect Rules, then note that this is a key difference between Redirect Actions and Redirect Rules.

<Callout icon="file-lines">
  Unlike Redirect Rules, Redirect Actions will suspend the Actions pipeline when a redirect is issued and will resume in the same Action that issued the redirect when the authentication flow is continued.
</Callout>

After the Action has finished executing, Auth0 redirects the user to the URL specified in the `api.redirect.sendUserTo()` function. Auth0 also passes a `state` parameter in that URL. For example:

`https://my-app.exampleco.com/?state=abc123`

Your redirect URL will need to extract the `state` parameter and send it back to Auth0 to resume the authentication transaction. State is an opaque value used to prevent [Cross-Site Request Forgery (CSRF) attacks](/docs/secure/security-guidance/prevent-threats).

## Resume the authentication flow

After the redirect, resume authentication by redirecting the user to the `/continue` endpoint and including the `state` parameter you received in the URL. If you do not send the original state back to the `/continue` endpoint, Auth0 will lose the context of the login transaction and the user will not be able to log in due to an `invalid_request` error.

For example:

`https://{yourAuth0Domain}/continue?state=THE_ORIGINAL_STATE`

In this example, `THE_ORIGINAL_STATE` is the value that Auth0 generated and sent to the redirect URL. For example, if your Action redirects to `https://my-app.exampleco.com/`, Auth0 would use a redirect URL similar to `https://my-app.exampleco.com/?state=abc123`, making `abc123` the `THE_ORIGINAL_STATE`. To resume the authentication transaction, you would redirect to:

`https://{yourAuth0Domain}/continue?state=abc123`

When a user has been redirected to the `/continue` endpoint, the Actions pipeline will resume on the same Action that invoked the redirect by calling the `onContinuePostLogin` function. For redirects to work properly, you must have a function with the following signature in the same Action that invoked the redirect:

```javascript lines theme={null}
/**
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {
  api.redirect.sendUserTo("https://my-app.exampleco.com");
};

/**
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/

exports.onContinuePostLogin = async (event, api) => {
}
```

## Pass data to the external site

To pass data to the external site, we recommend encoding that data in a signed [JWT](/docs/secure/tokens/json-web-tokens) so that your application can be certain it was not tampered with during transit. With Actions, this can be done with the `api.redirect.encodeToken` and `api.redirect.sendUserTo` functions:

```javascript lines expandable theme={null}
/**
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {
  const yourDomain = event.secrets.YOUR_AUTH0_DOMAIN || event.request.hostname

  // Craft a signed session token
  const token = api.redirect.encodeToken({
    secret: event.secrets.MY_REDIRECT_SECRET,
    expiresInSeconds: 60, 
    payload: {
      // Custom claims to be added to the token
      email: event.user.email,
      externalUserId: 1234,
      continue_uri: `https://${yourDomain}/continue`
    },
  });

  // Send the user to https://my-app.exampleco.com along
  // with a `session_token` query string param including
  // the email.
  api.redirect.sendUserTo("https://my-app.exampleco.com", {
    query: { session_token: token }
  });
}
```

The code above appends a `session_token` query string parameter to the URL used in the redirect (in addition to the `state` parameter that Auth0 adds automatically). This token will contain the following:

<table>
  <thead>
    <tr>
      <th>Token Element</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>sub</code></td>
      <td>Auth0 <code>user\_id</code> of the user.</td>
    </tr>

    <tr>
      <td><code>iss</code></td>
      <td>Hostname of your Auth0 tenant domain (e.g., <code>example.auth0.com</code>).</td>
    </tr>

    <tr>
      <td><code>exp</code></td>
      <td>Expiration time (in seconds) specified with the <code>expiresInSeconds</code> parameter. Should be as short as possible to avoid re-use of the token. Defaults to 900 seconds (15 minutes).</td>
    </tr>

    <tr>
      <td><code>ip</code></td>
      <td>IP Address of the originating authentication request.</td>
    </tr>

    <tr>
      <td><code>email</code></td>
      <td>Custom claim with a value specified in the <code>payload.email</code> parameter.</td>
    </tr>

    <tr>
      <td><code>externalUserId</code></td>
      <td>Custom claim with a value specified in the <code>payload.externalUserId</code> parameter.</td>
    </tr>

    <tr>
      <td><code>signature</code></td>
      <td>Using the secret specified above, the token will be signed with HS256 algorithm.</td>
    </tr>
  </tbody>
</table>

### Ensure the token has not been tampered with

The external system should verify that this token has not been tampered with during transit. To accomplish this, the remote system should ensure the token’s signature is valid and, if applicable, that the session in the external system belongs to the same Auth0 user provided in the `sub` claim of the token.

## Pass data back to Auth0

After the user completes the custom flow in the external site, they should be redirected to the `/continue` endpoint. In some situations, you may want to pass data back to Auth0 to impact the authentication or <Tooltip href="/docs/glossary?term=authorization+flow">authorization flow</Tooltip> for that user (for example, if you are implementing CAPTCHA checks or custom <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip>).

### Use app metadata where possible

If possible, the remote system should use the [Auth0 Management API](https://auth0.com/docs/api/management/v2/) to store custom information as application metadata on the Auth0 user profile. When the Auth0 Action flow is resumed, this information will be available on the `event.user.app_metadata` object. This approach avoids passing sensitive information to Auth0 on the front channel.

### Be selective when storing data on the Auth0 user profile

Avoid storing too much data in the Auth0 profile. This data is intended to be used for authentication and authorization purposes. The metadata and search capabilities of Auth0 are not designed for scenarios that require high search or update frequency, such as marketing research. Your system is likely to run into scalability and performance issues if you use Auth0 for these kinds of purposes.

If your application requires access to substantive user data, the recommended approach is to store that data in an external system and store a foreign key (the user ID) in Auth0 so that back-end systems can fetch the data if needed.

## Send data on the front channel

Passing information back and forth in the front channel opens up surface area for <Tooltip href="/docs/glossary?term=bad+actors">bad actors</Tooltip> to attack. If information must be sent on the front channel, then consider the following guidance:

### Pass information back to the Action

A signed session token should be used to send sensitive information back to Auth0. This token can be easily validated within an Action with the following code:

```javascript lines theme={null}
/**
 * @param {Event} event - Details about the user and the context in which they are logging in.
 * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
 */
exports.onContinuePostLogin = async (event, api) => {
  const payload = api.redirect.validateToken({
    secret: event.secrets.PRECONFIGURED_SECRET,
    tokenParameterName: 'my_token',
  });

  // use the data encoded in the token, such as: 
  api.idToken.setCustomClaim('color', payload.favorite_color);
}
```

The token will be validated to ensure that:

* The signature is valid.
* The token is not expired.
* The `state` claim within the token matches the `state` parameter used as part of the redirect.

<table>
  <thead>
    <tr>
      <th>Token Element</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>sub</code></td>
      <td>Auth0 <code>user\_id</code> of the user.</td>
    </tr>

    <tr>
      <td><code>iss</code></td>
      <td>Application that is targeted for the redirect.</td>
    </tr>

    <tr>
      <td><code>exp</code></td>
      <td>Should be as short as possible to avoid reuse of the token.</td>
    </tr>

    <tr>
      <td><code>state</code></td>
      <td>state parameter sent to the remote site as part of the redirect. This must be included in the token to avoid replay attacks.</td>
    </tr>

    <tr>
      <td><code>other</code></td>
      <td>Any other custom claims will be exposed as the <code>payload</code> in the code above.</td>
    </tr>

    <tr>
      <td><code>signature</code></td>
      <td>Token should be signed with the HS256 algorithm.</td>
    </tr>
  </tbody>
</table>

To avoid replay attacks, the token should be sent back to Auth0 by making a POST request to the `/continue` endpoint. The `tokenParameterName` option in the code allows you to specify the name of the field that contains your token.

## Custom authentication methods

After a successful redirect in the login pipeline, Actions can record custom authentication method events in the user's session. The `event.authentication.methods` array will contain an entry for the custom method for the duration of the user's browser session. Each entry in this array has a timestamp indicating when the authentication method was recorded.

A custom action can trigger a redirect if the required custom method is not in the `event.authentication.methods` array or if the entry is too old.

You can use `api.redirect.sendUserTo()` to send the user to a page that implements a custom authentication method. You can use the `api.authentication.recordMethod()` in the `exports.onContinuePostLogin` handler to store a record of the completed method in the user's session.

The record stored in the `event.authentication.methods` array will have a `name` property matching the URL chosen in `api.authentication.recordMethod()`. The URL captured here allows you to search through the current transaction's completed authentication methods to determine if your custom method already completed.

Your workflow may require the custom method to be re-performed periodically during the life of a user's session. For example, custom MFA scenarios may require user re-verification after a specified timeframe.

The example below compares the timestamp of an existing record to determine when to rerun the custom method:

```javascript lines expandable theme={null}
const CUSTOM_METHOD_URL = "https://path.to.prompt";
const PROMPT_TTL = 1000 * 60 * 60 * 24; // 24h

/**
 * Handler that will be called during the execution of a PostLogin flow.
 *
 * @param {Event} event - Details about the user and the context in which
 * they are logging in.
 * @param {PostLoginAPI} api - Interface whose methods can be used to
 * change the behavior of the login.
 */
exports.onExecutePostLogin = async (event, api) => {
  // Search authentication method records for an entry representing our
  // custom method.
  const methodRecord = event.authentication?.methods.find((record) =>
    validateCustomRecord(record, CUSTOM_METHOD_URL, PROMPT_TTL)
  );

  if (!methodRecord) {
    const sessionToken = api.redirect.encodeToken({
      payload: {
        user_id: event.user.user_id,
      },
      secret: event.secrets.SESSION_TOKEN_SECRET,
    });

    // We didn't find a valid record, so we send the user to the
    // URL that implements the custom method with the signed
    // data we encoded in `sessionToken`.
    api.redirect.sendUserTo(CUSTOM_METHOD_URL, {
      query: { session_token: sessionToken },
    });
  }
};

/**
 * Handler that will be invoked when this action is resuming after an
 * external redirect. If your onExecutePostLogin function does not perform
 * a redirect, this function can be safely ignored.
 *
 * @param {Event} event - Details about the user and the context in which
 * they are logging in.
 * @param {PostLoginAPI} api - Interface whose methods can be used to
 * change the behavior of the login.
 */
exports.onContinuePostLogin = async (event, api) => {
  const payload = api.redirect.validateToken({
    secret: event.secrets.SESSION_TOKEN_SECRET,
    tokenParameterName: "session_token",
  });

  if (!validateSessionToken(payload)) {
    return api.access.deny("Unauthorized");
  }

  // Record the completion of our custom authentication method.
  // THIS NEW API IS ONLY AVAILABLE IN `onContinuePostLogin`.
  api.authentication.recordMethod(CUSTOM_METHOD_URL);
};

function validateCustomRecord(record, url, ttl) {
  if (!record) {
    // No record means it isn't valid.
    return false;
  }

  if (record.url !== url) {
    // This isn't a record of our custom method.
    return false;
  }

  // Timestamps are rendered as ISO8601 strings.
  const timestamp = new Date(record.timestamp);

  // The record is valid if it was recorded recently enough.
  return timestamp.valueOf() >= Date.now() - ttl;
}

function validateSessionToken(payload) {
  // Custom validation logic for the data returned by the
  // custom method goes here.
  return true;
}
```

The `api.authentication.recordMethod()` API is only available in the `exports.onContinuePostLogin` handler. This avoids potential login exploits by recording the custom method after completing the redirect.

## Restrictions and limitations

Redirect Actions won't work with:

* [Resource Owner endpoint](https://auth0.com/docs/api/authentication/reference#resource-owner)
* [Password exchange](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow)
* [Refresh Token exchange](/docs/secure/tokens/refresh-tokens)

### Resource Owner endpoint

It is impossible to use redirect Actions when you are calling the Authentication API [Get Token](https://auth0.com/docs/api/authentication#resource-owner-password) endpoint for the <Tooltip href="/docs/glossary?term=Resource+Owner">Resource Owner</Tooltip> Password flow. Since the user is not in a redirect flow to begin with, you can not redirect the user in an Action.

### Flows where prompt=none

Since the goal of `prompt=none` is to avoid any scenario where the user will be required to enter input, any redirection will result in an `error=interaction_required`.

Since Actions run after an authentication session is created, you cannot use `prompt=none` if you have a redirect rule that is attempting to block access to tokens under certain conditions (for example, custom MFA, CAPTCHA with login, and so on).

You cannot create a redirect flow that blocks token access and bypasses the redirect Action if `prompt=none` because after a failed attempt, a user can simply call again with `prompt=none` and get tokens because their authentication session has been created even though Actions failed the first time.

### Refresh tokens

Due to the fact that using a <Tooltip href="/docs/glossary?term=refresh+token">refresh token</Tooltip> requires a back-channel call to the Authentication API [Get Token](https://auth0.com/docs/api/authentication#refresh-token) endpoint, this will also fail if attempting to redirect.

It is difficult to securely verify that any restrictions on login were carried out. There is not a consistent session ID in the context that could be used to collect information associated with the session such as this user passed MFA challenges. Therefore, you cannot use `prompt=none` at all.

Any time `api.redirect.sendUserTo()` is called in an Action, if `prompt=none` was passed, then the authorization fails with `error=interaction_required`, but since the user's session is created even if Actions fail, we can't trust that a user passed redirect challenges and therefore can't use `prompt=none` as a way to get tokens.

In this specific case, we recommend that you use refresh tokens exclusively, because you can ensure that a user passed challenges if those challenges are required to generate a refresh token.

## Learn more

* [Manage User Metadata with the post-login Action Trigger](/docs/manage-users/user-accounts/metadata/manage-user-metadata)


# Post-user Registration Trigger
Source: https://auth0.com/docs/customize/actions/explore-triggers/signup-and-login-triggers/post-user-registration-trigger

Learn about the Post User Registration Flow and post-user-registration Action trigger, which runs after a user has been created for a Database or Passwordless connection.

The Post-user Registration trigger runs after a user is added to a Database or <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> Connection.

<Frame>
  <img alt="Diagram of the Actions Post User Registration Flow." />
</Frame>

Actions in this flow are non-blocking (asynchronous), which means the Auth0 pipeline will continue to run without waiting for the Action to finish its execution. Thus, the Action's outcome does not affect the Auth0 transaction.

## Triggers

### Post User Registration

The `post-user-registration` triggers runs after a user has been created for a Database or Passwordless connection. This trigger can be used to notify another system that a user has registered for your application. Multiple actions can be bound to this trigger, and the actions will run in order. However, these actions will be run asynchronously and will not block the user registration process.

### References

* [Event object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/post-user-registration-trigger/post-user-registration-event-object): Provides contextual information about the newly-created user.
* [API object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/post-user-registration-trigger/api-object): Provides methods for changing the behavior of the flow.

## Common use cases

### Notify Slack when a new user registers

```javascript lines theme={null}
/**
* Handler that will be called during the execution of a PostUserRegistration flow.
* 
 * @param {Event} event - Details about the context and user that has registered.
 * @param {PostUserRegistrationAPI} api - Interface whose methods can be used to change the behavior of post user registration.
 */

exports.onExecutePostUserRegistration = async (event, api) => {
  const { IncomingWebhook } = require("@slack/webhook");
  const webhook = new IncomingWebhook(event.secrets.SLACK_WEBHOOK_URL);

  const text = `New User: ${event.user.email}`;
  const channel = '#some_channel';

  webhook.send({ text, channel });
};
```

<Callout icon="file-lines">
  For this Action to execute properly, the Action must contain a secret named `SLACK_WEBHOOK_URL` and must have a dependency on the `@slack/webhook` `npm` package.
</Callout>

### Store the Auth0 user id in a remote system

A post-user-registration Action can be used to store the Auth0 user ID in a remote system.

```javascript lines theme={null}
/**
* Handler that will be called during the execution of a PostUserRegistration flow.
* 
* @param {Event} event - Details about the context and user that has registered.
* @param {PostUserRegistrationAPI} api - Interface whose methods can be used to change the behavior of post user registration.
*/

const axios = require("axios");

exports.onExecutePostUserRegistration = async (event, api) => {
  await axios.post("https://my-api.exampleco.com/users", { params: { email: event.user.email }});
};
```

<Callout icon="file-lines">
  To use an `npm` library like `axios`, you must add the library to the Action as a dependency. To learn more, read the "Add a dependency" section in [Write Your First Action](/docs/customize/actions/write-your-first-action).
</Callout>

### Deny access to specific JA3/JA4 fingerprints

The `event.security_context` object contains the JA3/JA4 fingerprint values for the current transaction.

```js lines theme={null}
exports.onExecutePreUserRegistration = async (event, api) => {
  const clientJa4 = event?.security_context?.ja4;
  console.log('[ACTION]', {clientJa4});
  const badFingerprints = ['t13d1517h2_8daaf6152771_b6f405a00624','t13d1516h2_8daaf6152771_d8a2da3f94cd'];
  if (clientJa4 && badFingerprints.includes(clientJa4)){
    api.access.deny('suspicious_tls_fingerprint', 'Your TLS fingerprint has been flagged as suspicious');
  }
};
```


# Actions Triggers: post-user-registration - API Object
Source: https://auth0.com/docs/customize/actions/explore-triggers/signup-and-login-triggers/post-user-registration-trigger/post-user-registration-api-object

Learn about the post-user-registration Action trigger's API object.

The API object for the post-user-registration Actions trigger includes:

## `api.cache`

Store and retrieve data that persists across executions.

### `api.cache.delete(key)`

Delete a record describing a cached value at the supplied
key if it exists.

<ResponseField name="key" type="string">
  The key of the cache record to delete.
</ResponseField>

### `api.cache.get(key)`

Retrieve a record describing a cached value at the supplied key,
if it exists. If a record is found, the cached value can be found
at the `value` property of the returned object.

<ResponseField name="key" type="string">
  The key of the record stored in the cache.
</ResponseField>

### `api.cache.set(key, value, options)`

Store or update a string value in the cache at the specified key.

Values stored in this cache are scoped to the Trigger in which they
are set. They are subject to the [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations).

Values stored in this way will have lifetimes of *up to* the specified
`ttl` or `expires_at` values. If no lifetime is specified, a default of
lifetime of 24 hours will be used. Lifetimes may not exceed the maximum
duration listed at [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations).

**Important**: This cache is designed for short-lived, ephemeral data. Items may not be
available in later transactions even if they are within their supplied their lifetime.

<ResponseField name="key" type="string">
  The key of the record to be stored.
</ResponseField>

<ResponseField name="value" type="string">
  The value of the record to be stored.
</ResponseField>

<ResponseField name="options" type="cachesetoptions">
  Options for adjusting cache behavior.

  <Expandable title="options properties">
    <ResponseField name="expires_at" type="number">
      The absolute expiry time in milliseconds since the unix epoch.
      While cached records may be evicted earlier, they will
      never remain beyond the the supplied `expires_at`.

      *Note*: This value should not be supplied if a value was also
      provided for `ttl`. If both options are supplied, the
      earlier expiry of the two will be used.
    </ResponseField>

    <ResponseField name="ttl" type="number">
      The time-to-live value of this cache entry in milliseconds.
      While cached values may be evicted earlier, they will
      never remain beyond the the supplied `ttl`.

      *Note*: This value should not be supplied if a value was also
      provided for `expires_at`. If both options are supplied, the
      earlier expiry of the two will be used.
    </ResponseField>
  </Expandable>
</ResponseField>


# Actions Triggers: post-user-registration - Event Object
Source: https://auth0.com/docs/customize/actions/explore-triggers/signup-and-login-triggers/post-user-registration-trigger/post-user-registration-event-object

Learn about the post-user-registration Action trigger's event object, which provides contextual information about the trigger execution.

The `event` object for the post-user-registration Actions trigger provides contextual information about the trigger execution.

## `event.authentication`

<ResponseField name="event.authentication" type="dictionary">
  Details about supplemental authentication signals obtained during the registration flow.

  <Expandable title="authentication properties">
    <ResponseField name="riskAssessment" type="dictionary">
      Details about risk assessments information for different flows.

      <Expandable title="riskAssessment properties">
        <ResponseField name="supplemental" type="dictionary">
          Supplemental signals sent from third party providers to assist in risk assessments.

          <Expandable title="supplemental properties">
            <ResponseField name="akamai" type="dictionary">
              \[Limited Early Access] Supplemental risk assessment. This is available only if Akamai Account Protector is enabled and Akamai forwards the headers for the transaction.

              <Expandable title="akamai properties">
                <ResponseField name="akamaiBot" type="object">
                  The bot detection results as forwarded by Akamai Bot Manager.

                  <Expandable title="akamaiBot properties">
                    <ResponseField name="type" type="string">
                      The type of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="action" type="string">
                      The action of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="botCategory" type="array of strings">
                      The bot category of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="botScore" type="number">
                      The bot score of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="botScoreResponseSegment" type="string">
                      The bot score response segment of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="botnetId" type="string">
                      The botnet ID of the Akamai bot manager results.
                    </ResponseField>
                  </Expandable>
                </ResponseField>

                <ResponseField name="akamaiUserRisk" type="dictionary">
                  The user risk detection results as forwarded by Akamai Account Protector.

                  <Expandable title="akamaiUserRisk properties">
                    <ResponseField name="action" type="string">
                      The action of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="allow" type="number">
                      The allowed status of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="emailDomain" type="string">
                      The email domain of the user.
                    </ResponseField>

                    <ResponseField name="general" type="dictionary">
                      The general risk of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="ouid" type="string">
                      The OUID of the user.
                    </ResponseField>

                    <ResponseField name="requestid" type="string">
                      The request ID of the user.
                    </ResponseField>

                    <ResponseField name="risk" type="dictionary">
                      The risk of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="score" type="number">
                      The score of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="status" type="number">
                      The status of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="trust" type="dictionary">
                      The trust of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="username" type="string">
                      The username of the user.
                    </ResponseField>

                    <ResponseField name="uuid" type="string">
                      The UUID of the Akamai user risk assessment.
                    </ResponseField>
                  </Expandable>
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.connection`

<ResponseField name="event.connection" type="dictionary">
  Details about the Connection that was used to register the user.

  <Expandable title="connection properties">
    <ResponseField name="id" type="string">
      The connection's unique identifier.
    </ResponseField>

    <ResponseField name="metadata" type="dictionary">
      Metadata associated with the connection.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the connection used to authenticate the user (such as `twitter` or `some-g-suite-domain`).
    </ResponseField>

    <ResponseField name="strategy" type="string">
      The type of connection. For social connections, `event.connection.strategy === event.connection.name`. For enterprise connections, the strategy is `waad` (Windows Azure AD), `ad` (Active Directory/LDAP), `auth0` (database connections), and so on.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.custom_domain`

<ResponseField name="event.custom_domain" type="dictionary">
  Details about the custom domain associated with the current transaction.

  <Expandable title="custom_domain properties">
    <ResponseField name="domain" type="string">
      The custom domain name.
    </ResponseField>

    <ResponseField name="domain_metadata" type="dictionary">
      Custom domain metadata as key-value pairs.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.request`

<ResponseField name="event.request" type="dictionary">
  Details about the request that initiated the transaction.

  <Expandable title="request properties">
    <ResponseField name="geoip" type="dictionary">
      <Expandable title="geoip properties">
        <ResponseField name="cityName" type="string" />

        <ResponseField name="continentCode" type="string" />

        <ResponseField name="countryCode" type="string" />

        <ResponseField name="countryCode3" type="string" />

        <ResponseField name="countryName" type="string" />

        <ResponseField name="latitude" type="number" />

        <ResponseField name="longitude" type="number" />

        <ResponseField name="subdivisionCode" type="string" />

        <ResponseField name="subdivisionName" type="string" />

        <ResponseField name="timeZone" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="hostname" type="string">
      The hostname that is being used for the authentication flow.
    </ResponseField>

    <ResponseField name="ip" type="string">
      The originating IP address of the request.
    </ResponseField>

    <ResponseField name="language" type="string">
      The language requested by the browser.
    </ResponseField>

    <ResponseField name="method" type="string">
      The HTTP method used for the request
    </ResponseField>

    <ResponseField name="user_agent" type="string">
      The value of the `User-Agent` header received when initiating the transaction.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.security_context`

<ResponseField name="event.security_context" type="object">
  An object containing fingerprint signatures. This will be available only if the client is using cloudflare. The JA3/JA4 fingerprint can be null or empty in some cases. The most common case is for HTTP requests because JA3 and JA4 are calculated in TLS. It can also be empty due to the Worker sending requests within the same zone or to a zone that is not proxied (or a third party).

  <Expandable title="security_context properties">
    <ResponseField name="ja3" type="string">
      JA3 fingerprint signature. This will be available only if the client is using a TLS connection.
    </ResponseField>

    <ResponseField name="ja4" type="string">
      JA4 fingerprint signature. This will be available only if the client is using a TLS connection.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.tenant`

<ResponseField name="event.tenant" type="object">
  Details about the Tenant associated with the current transaction.

  <Expandable title="tenant properties">
    <ResponseField name="id" type="string">
      The name of the tenant.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.transaction`

<ResponseField name="event.transaction" type="dictionary">
  Details about the current transaction.

  <Expandable title="transaction properties">
    <ResponseField name="acr_values" type="array of strings">
      Any acr\_values provided in the original authentication request.
    </ResponseField>

    <ResponseField name="locale" type="string">
      The locale to be used for this transaction as determined by comparing the browser's requested languages to the tenant's language settings.
    </ResponseField>

    <ResponseField name="login_hint" type="string">
      Hint to the Authorization Server about the login identifier the End-User might use to log in (if necessary).
    </ResponseField>

    <ResponseField name="prompt" type="array of strings">
      List of instructions indicating whether the user may be prompted for re-authentication and consent.
    </ResponseField>

    <ResponseField name="protocol" type="string">
      Possible values:

      * `oidc-basic-profile`
      * `oidc-ciba`
      * `oidc-ciba-web-link`
      * `oidc-implicit-profile`
      * `oauth2-device-code`
      * `oauth2-resource-owner`
      * `oauth2-resource-owner-jwt-bearer`
      * `oauth2-password`
      * `oauth2-webauthn`
      * `oauth2-access-token`
      * `oauth2-refresh-token`
      * `oauth2-token-exchange`
      * `oidc-hybrid-profile`
      * `samlp`
      * `wsfed`
      * `wstrust-usernamemixed`
    </ResponseField>

    <ResponseField name="redirect_uri" type="string">
      The URL to which Auth0 will redirect the browser after the transaction is completed.
    </ResponseField>

    <ResponseField name="requested_scopes" type="array of strings">
      The scopes requested (if any) when starting this authentication flow.
    </ResponseField>

    <ResponseField name="response_mode" type="string">
      Informs the Authorization Server of the mechanism to be used for returning parameters from the Authorization Endpoint.

      Allowed values: `query`, `fragment`, `form_post`, `web_message`
    </ResponseField>

    <ResponseField name="response_type" type="array of strings">
      Denotes the kind of credential that Auth0 will return.
    </ResponseField>

    <ResponseField name="state" type="string">
      An opaque arbitrary alphanumeric string your app adds to the initial request that Auth0 includes when redirecting back to your application.
    </ResponseField>

    <ResponseField name="ui_locales" type="array of strings">
      The ui\_locales provided in the original authentication request.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.user`

<ResponseField name="event.user" type="dictionary">
  An object describing the user on whose behalf the current transaction was initiated.

  <Expandable title="user properties">
    <ResponseField name="app_metadata" type="dictionary">
      Custom fields that store info about a user that influences the user's access, such as support plan, security roles, or access control groups.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Timestamp indicating when the user profile was first created.
    </ResponseField>

    <ResponseField name="email" type="string">
      (unique) User's email address.
    </ResponseField>

    <ResponseField name="email_verified" type="boolean">
      Indicates whether the user has verified their email address.
    </ResponseField>

    <ResponseField name="family_name" type="string">
      User's family name.
    </ResponseField>

    <ResponseField name="given_name" type="string">
      User's given name.
    </ResponseField>

    <ResponseField name="last_password_reset" type="string">
      Timestamp indicating the last time the user's password was reset/changed. At user creation, this field does not exist. This property is only available for Database connections.
    </ResponseField>

    <ResponseField name="name" type="string">
      User's full name.
    </ResponseField>

    <ResponseField name="nickname" type="string">
      User's nickname.
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      User's phone number.
    </ResponseField>

    <ResponseField name="phone_verified" type="boolean">
      Indicates whether the user has verified their phone number.
    </ResponseField>

    <ResponseField name="picture" type="string">
      URL pointing to the [user's profile picture](https://auth0.com/docs/users/change-user-picture).
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      Timestamp indicating when the user's profile was last updated/modified.
    </ResponseField>

    <ResponseField name="user_id" type="string">
      (unique) User's unique identifier.
    </ResponseField>

    <ResponseField name="user_metadata" type="dictionary">
      Custom fields that store info about a user that does not impact what they can or cannot access, such as work address, home address, or user preferences.
    </ResponseField>

    <ResponseField name="username" type="string">
      (unique) User's username.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.secrets`

<ResponseField name="event.secrets" type="secrets">
  Secret values securely associated with this Action.
</ResponseField>


# Pre-user Registration Trigger
Source: https://auth0.com/docs/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger

Learn about the Pre User Registration Flow, which runs when a user attempts to register through a Database or Passwordless connection. It can be used to add metadata to the user profile before it is created or to deny a registration.

The Pre-user Registration trigger runs before a user is added to a Database or <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> Connection.

<Frame>
  <img alt="Diagram showing the Actions Pre User Registration Flow." />
</Frame>

Actions in this flow are blocking (synchronous), which means they execute as part of a trigger's process and will prevent the rest of the Auth0 pipeline from running until the Action is complete.

## Triggers

### Pre-user Registration

The `pre-user-registration`  triggers runs when a user attempts to register through a Database or Passwordless connection. This trigger can be used to add metadata to the user profile before it is created or to deny a registration with custom logic.

<Warning>
  You cannot currently use `pre-user-registration` Actions to add metadata to passwordless users.
</Warning>

#### References

* [Event object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger/pre-user-registration-event-object): Provides contextual information about the request to register a new user.
* [API object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger/pre-user-registration-api-object): Provides methods for changing the behavior of the flow.

## Common use cases

### Deny registration by location

A pre-user registration Action can be used to prevent a user from signing up.

```javascript lines theme={null}
/**
 * @param {Event} event - Details about registration event.
 * @param {PreUserRegistrationAPI} api
 */
exports.onExecutePreUserRegistration = async (event, api) => {
  if (event.request.geoip.continentCode === "NA") {

    // localize the error message 
    const LOCALIZED_MESSAGES = {
      en: 'You are not allowed to register.',
      es: 'No tienes permitido registrarte.'
    };

    const userMessage = LOCALIZED_MESSAGES[event.request.language] || LOCALIZED_MESSAGES['en'];
    api.access.deny('no_signups_from_north_america', userMessage);
  }
};
```

### Set metadata in the user profile

A pre-user registration Action can be used to add metadata to the user profile before it is created.

<Warning>
  You cannot currently use `pre-user-registration` Actions to add metadata to passwordless users.
</Warning>

```javascript lines theme={null}
/**
 * @param {Event} event - Details about registration event.
 * @param {PreUserRegistrationAPI} api
 */
exports.onExecutePreUserRegistration = async (event, api) => {
  api.user.setUserMetadata("screen_name", "username");  
};
```

### Store a user ID from another system in the user profile

A pre-user registration Action can be used to store a user ID from another system in the user profile.

```javascript lines expandable theme={null}
const axios = require('axios');

const REQUEST_TIMEOUT = 2000; // Example timeout

/**
* Handler that will be called during the execution of a PreUserRegistration flow.
*
* @param {Event} event - Details about the context and user that is attempting to register.
* @param {PreUserRegistrationAPI} api - Interface whose methods can be used to change the behavior of the signup.
*/
exports.onExecutePreUserRegistration = async (event, api) => {
  try {
    // Set a secret USER_SERVICE_URL = 'https://yourservice.com'
    const remoteUser = await axios.get(event.secrets.USER_SERVICE_URL, {
      timeout: REQUEST_TIMEOUT,
      params: {
        email: event.user.email 
      }
    });

    if (remoteUser) {
      api.user.setAppMetadata('my-api-user-id', remoteUser.id); 
    }
  } catch (err) {
    api.validation.error('custom_error', 'Custom Error');
  }
};
```

<Callout icon="file-lines">
  To use an `npm` library like `axios`, you must add the library to the Action as a dependency. To learn more, read the "Add a dependency" section in [Write Your First Action](/docs/customize/actions/write-your-first-action).
</Callout>

### Deny access to specific JA3/JA4 fingerprints

The `event.security_context` object contains the JA3/JA4 fingerprint values for the current transaction.

```js lines theme={null}
exports.onExecutePreUserRegistration = async (event, api) => {
  const clientJa4 = event?.security_context?.ja4;
  console.log('[ACTION]', {clientJa4});
  const badFingerprints = ['t13d1517h2_8daaf6152771_b6f405a00624','t13d1516h2_8daaf6152771_d8a2da3f94cd'];
  if (clientJa4 && badFingerprints.includes(clientJa4)){
    api.access.deny('suspicious_tls_fingerprint', 'Your TLS fingerprint has been flagged as suspicious');
  }
};
```


# Actions Triggers: pre-user-registration - API Object
Source: https://auth0.com/docs/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger/pre-user-registration-api-object

Learn about the pre-user-registration Action trigger's API object.

The API object for the pre-user-registration Actions trigger includes:

## `api.access`

Modify the access of the user that is logging in, such as rejecting the login attempt.

### `api.access.deny(reason, userMessage)`

Deny the user from being able to register. The signup flow will immediately stop following the
completion of this action and no further Actions will be executed.

<ResponseField name="reason" type="string">
  An internal reason describing why this registration attempt is being denied. This value
  will appear in tenant logs.
</ResponseField>

<ResponseField name="userMessage" type="string">
  A human-readable explanation for rejecting the registration attempt. This may be presented
  directly in end-user interfaces.
</ResponseField>

## `api.user`

Make changes to the metadata of the user that is logging in.

### `api.user.setAppMetadata(key, value)`

Set application-specific metadata for the user that is logging in.

Note: This method should not be used in callbacks. Invoking this method won't update the metadata immediately.
You can call this several times throughout multiple actions of the same flow and the engine will aggregate the
changes and update the metadata at once before the flow is completed.

<ResponseField name="key" type="string">
  The metadata property to be set.
</ResponseField>

<ResponseField name="value" type="unknown">
  The value of the metadata property. This may be set to `null` to remove the
  metadata property.
</ResponseField>

### `api.user.setUserMetadata(key, value)`

Set general metadata for the user that is logging in.

Note: This method should not be used in callbacks. Invoking this method won't update the metadata immediately.
You can call this several times throughout multiple actions of the same flow and the engine will aggregate the
changes and update the metadata at once before the flow is completed.

<ResponseField name="key" type="string">
  The metadata property to be set.
</ResponseField>

<ResponseField name="value" type="unknown">
  The value of the metadata property. This may be set to `null` to remove the
  metadata property.
</ResponseField>

### `api.user.setUserId(user_id)`

Set user\_id for the user that is logging in.

<ResponseField name="user_id" type="string">
  The user\_id to assign to user
</ResponseField>

## `api.cache`

Store and retrieve data that persists across executions.

### `api.cache.delete(key)`

Delete a record describing a cached value at the supplied
key if it exists.

<ResponseField name="key" type="string">
  The key of the cache record to delete.
</ResponseField>

### `api.cache.get(key)`

Retrieve a record describing a cached value at the supplied key,
if it exists. If a record is found, the cached value can be found
at the `value` property of the returned object.

<ResponseField name="key" type="string">
  The key of the record stored in the cache.
</ResponseField>

### `api.cache.set(key, value, options)`

Store or update a string value in the cache at the specified key.

Values stored in this cache are scoped to the Trigger in which they
are set. They are subject to the [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations).

Values stored in this way will have lifetimes of *up to* the specified
`ttl` or `expires_at` values. If no lifetime is specified, a default of
lifetime of 24 hours will be used. Lifetimes may not exceed the maximum
duration listed at [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations).

**Important**: This cache is designed for short-lived, ephemeral data. Items may not be
available in later transactions even if they are within their supplied their lifetime.

<ResponseField name="key" type="string">
  The key of the record to be stored.
</ResponseField>

<ResponseField name="value" type="string">
  The value of the record to be stored.
</ResponseField>

<ResponseField name="options" type="cachesetoptions">
  Options for adjusting cache behavior.

  <Expandable title="options properties">
    <ResponseField name="expires_at" type="number">
      The absolute expiry time in milliseconds since the unix epoch.
      While cached records may be evicted earlier, they will
      never remain beyond the the supplied `expires_at`.

      *Note*: This value should not be supplied if a value was also
      provided for `ttl`. If both options are supplied, the
      earlier expiry of the two will be used.
    </ResponseField>

    <ResponseField name="ttl" type="number">
      The time-to-live value of this cache entry in milliseconds.
      While cached values may be evicted earlier, they will
      never remain beyond the the supplied `ttl`.

      *Note*: This value should not be supplied if a value was also
      provided for `expires_at`. If both options are supplied, the
      earlier expiry of the two will be used.
    </ResponseField>
  </Expandable>
</ResponseField>

## `api.validation`

Modify the access of the user that is logging in, such as rejecting the login attempt due to validation errors.

### `api.validation.error(errorCode, errorMessage)`

Deny the user from being able to register. The signup flow will immediately stop following the
completion of this action and no further Actions will be executed.

<ResponseField name="errorCode" type="string">
  A customer defined error code describing why this registration attempt is being denied. This value
  will appear in tenant logs.
</ResponseField>

<ResponseField name="errorMessage" type="string">
  A customer defined explanation for rejecting the registration attempt. This may be presented
  directly in end-user interfaces.
</ResponseField>


# Actions Triggers: pre-user-registration - Event Object
Source: https://auth0.com/docs/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger/pre-user-registration-event-object

Learn about the pre-user-registration Action trigger's event object, which provides contextual information about the trigger execution.

The `event` object for the pre-user-registration Actions trigger provides contextual information about the trigger execution.

## `event.authentication`

<ResponseField name="event.authentication" type="dictionary">
  Details about authentication obtained during the pre user registration flow.

  <Expandable title="authentication properties">
    <ResponseField name="riskAssessment" type="dictionary">
      Details about risk assessments information for different flows.

      <Expandable title="riskAssessment properties">
        <ResponseField name="supplemental" type="dictionary">
          Supplemental signals sent from third party providers to assist in risk assessments.

          <Expandable title="supplemental properties">
            <ResponseField name="akamai" type="dictionary">
              \[Limited Early Access] Supplemental risk assessment. This is available only if Akamai Account Protector is enabled and Akamai forwards the headers for the transaction.

              <Expandable title="akamai properties">
                <ResponseField name="akamaiBot" type="object">
                  The bot detection results as forwarded by Akamai Bot Manager.

                  <Expandable title="akamaiBot properties">
                    <ResponseField name="type" type="string">
                      The type of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="action" type="string">
                      The action of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="botCategory" type="array of strings">
                      The bot category of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="botScore" type="number">
                      The bot score of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="botScoreResponseSegment" type="string">
                      The bot score response segment of the Akamai bot manager results.
                    </ResponseField>

                    <ResponseField name="botnetId" type="string">
                      The botnet ID of the Akamai bot manager results.
                    </ResponseField>
                  </Expandable>
                </ResponseField>

                <ResponseField name="akamaiUserRisk" type="dictionary">
                  The user risk detection results as forwarded by Akamai Account Protector.

                  <Expandable title="akamaiUserRisk properties">
                    <ResponseField name="action" type="string">
                      The action of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="allow" type="number">
                      The allowed status of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="emailDomain" type="string">
                      The email domain of the user.
                    </ResponseField>

                    <ResponseField name="general" type="dictionary">
                      The general risk of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="ouid" type="string">
                      The OUID of the user.
                    </ResponseField>

                    <ResponseField name="requestid" type="string">
                      The request ID of the user.
                    </ResponseField>

                    <ResponseField name="risk" type="dictionary">
                      The risk of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="score" type="number">
                      The score of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="status" type="number">
                      The status of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="trust" type="dictionary">
                      The trust of the Akamai user risk assessment.
                    </ResponseField>

                    <ResponseField name="username" type="string">
                      The username of the user.
                    </ResponseField>

                    <ResponseField name="uuid" type="string">
                      The UUID of the Akamai user risk assessment.
                    </ResponseField>
                  </Expandable>
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.client`

<ResponseField name="event.client" type="dictionary">
  Information about the Client with which this transaction was initiated.

  <Expandable title="client properties">
    <ResponseField name="client_id" type="string">
      The client id of the application the user is logging in to.
    </ResponseField>

    <ResponseField name="metadata" type="dictionary">
      An object for holding other application properties.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the application (as defined in the Dashboard).
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.connection`

<ResponseField name="event.connection" type="dictionary">
  Details about the Connection that was used to register the user.

  <Expandable title="connection properties">
    <ResponseField name="id" type="string">
      The connection's unique identifier.
    </ResponseField>

    <ResponseField name="metadata" type="dictionary">
      Metadata associated with the connection.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the connection used to authenticate the user (such as `twitter` or `some-g-suite-domain`).
    </ResponseField>

    <ResponseField name="strategy" type="string">
      The type of connection. For social connections, `event.connection.strategy === event.connection.name`. For enterprise connections, the strategy is `waad` (Windows Azure AD), `ad` (Active Directory/LDAP), `auth0` (database connections), and so on.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.custom_domain`

<ResponseField name="event.custom_domain" type="dictionary">
  Details about the custom domain associated with the current transaction.

  <Expandable title="custom_domain properties">
    <ResponseField name="domain" type="string">
      The custom domain name.
    </ResponseField>

    <ResponseField name="domain_metadata" type="dictionary">
      Custom domain metadata as key-value pairs.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.request`

<ResponseField name="event.request" type="dictionary">
  Details about the request that initiated the transaction.

  <Expandable title="request properties">
    <ResponseField name="body" type="dictionary">
      The body of the POST request. This data will only be available during refresh token, Client Credential Exchange flows and PreUserRegistration Action.
    </ResponseField>

    <ResponseField name="geoip" type="dictionary">
      <Expandable title="geoip properties">
        <ResponseField name="cityName" type="string" />

        <ResponseField name="continentCode" type="string" />

        <ResponseField name="countryCode" type="string" />

        <ResponseField name="countryCode3" type="string" />

        <ResponseField name="countryName" type="string" />

        <ResponseField name="latitude" type="number" />

        <ResponseField name="longitude" type="number" />

        <ResponseField name="subdivisionCode" type="string" />

        <ResponseField name="subdivisionName" type="string" />

        <ResponseField name="timeZone" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="hostname" type="string">
      The hostname that is being used for the authentication flow.
    </ResponseField>

    <ResponseField name="ip" type="string">
      The originating IP address of the request.
    </ResponseField>

    <ResponseField name="language" type="string">
      The language requested by the browser.
    </ResponseField>

    <ResponseField name="method" type="string">
      The HTTP method used for the request
    </ResponseField>

    <ResponseField name="user_agent" type="string">
      The value of the `User-Agent` header received when initiating the transaction.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.security_context`

<ResponseField name="event.security_context" type="object">
  An object containing fingerprint signatures. This will be available only if the client is using cloudflare. The JA3/JA4 fingerprint can be null or empty in some cases. The most common case is for HTTP requests because JA3 and JA4 are calculated in TLS. It can also be empty due to the Worker sending requests within the same zone or to a zone that is not proxied (or a third party).

  <Expandable title="security_context properties">
    <ResponseField name="ja3" type="string">
      JA3 fingerprint signature. This will be available only if the client is using a TLS connection.
    </ResponseField>

    <ResponseField name="ja4" type="string">
      JA4 fingerprint signature. This will be available only if the client is using a TLS connection.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.tenant`

<ResponseField name="event.tenant" type="object">
  Details about the Tenant associated with the current transaction.

  <Expandable title="tenant properties">
    <ResponseField name="id" type="string">
      The name of the tenant.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.transaction`

<ResponseField name="event.transaction" type="dictionary">
  Details about the current transaction.

  <Expandable title="transaction properties">
    <ResponseField name="acr_values" type="array of strings">
      Any acr\_values provided in the original authentication request.
    </ResponseField>

    <ResponseField name="locale" type="string">
      The locale to be used for this transaction as determined by comparing the browser's requested languages to the tenant's language settings.
    </ResponseField>

    <ResponseField name="login_hint" type="string">
      Hint to the Authorization Server about the login identifier the End-User might use to log in (if necessary).
    </ResponseField>

    <ResponseField name="prompt" type="array of strings">
      List of instructions indicating whether the user may be prompted for re-authentication and consent.
    </ResponseField>

    <ResponseField name="protocol" type="string">
      Possible values:

      * `oidc-basic-profile`
      * `oidc-ciba`
      * `oidc-ciba-web-link`
      * `oidc-implicit-profile`
      * `oauth2-device-code`
      * `oauth2-resource-owner`
      * `oauth2-resource-owner-jwt-bearer`
      * `oauth2-password`
      * `oauth2-webauthn`
      * `oauth2-access-token`
      * `oauth2-refresh-token`
      * `oauth2-token-exchange`
      * `oidc-hybrid-profile`
      * `samlp`
      * `wsfed`
      * `wstrust-usernamemixed`
    </ResponseField>

    <ResponseField name="redirect_uri" type="string">
      The URL to which Auth0 will redirect the browser after the transaction is completed.
    </ResponseField>

    <ResponseField name="requested_scopes" type="array of strings">
      The scopes requested (if any) when starting this authentication flow.
    </ResponseField>

    <ResponseField name="response_mode" type="string">
      Informs the Authorization Server of the mechanism to be used for returning parameters from the Authorization Endpoint.

      Allowed values: `query`, `fragment`, `form_post`, `web_message`
    </ResponseField>

    <ResponseField name="response_type" type="array of strings">
      Denotes the kind of credential that Auth0 will return.
    </ResponseField>

    <ResponseField name="state" type="string">
      An opaque arbitrary alphanumeric string your app adds to the initial request that Auth0 includes when redirecting back to your application.
    </ResponseField>

    <ResponseField name="ui_locales" type="array of strings">
      The ui\_locales provided in the original authentication request.
    </ResponseField>

    <ResponseField name="correlation_id" type="string">
      Correlation ID can be provided in the initial authentication request when the application redirects to Universal Login. You can use value to correlate logs and requests from your Action code with the user flow.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.user`

<ResponseField name="event.user" type="dictionary">
  An object describing the user who is attempting to register.

  <Expandable title="user properties">
    <ResponseField name="app_metadata" type="dictionary">
      Custom fields that store info about a user that influences the user's access, such as support plan, security roles, or access control groups.
    </ResponseField>

    <ResponseField name="email" type="string">
      (unique) User's email address.
    </ResponseField>

    <ResponseField name="family_name" type="string">
      User's family name.
    </ResponseField>

    <ResponseField name="given_name" type="string">
      User's given name.
    </ResponseField>

    <ResponseField name="name" type="string">
      User's full name.
    </ResponseField>

    <ResponseField name="nickname" type="string">
      User's nickname.
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      User's phone number.
    </ResponseField>

    <ResponseField name="picture" type="string">
      URL pointing to the [user's profile picture](https://auth0.com/docs/users/change-user-picture).
    </ResponseField>

    <ResponseField name="user_metadata" type="dictionary">
      Custom fields that store info about a user that does not impact what they can or cannot access, such as work address, home address, or user preferences.
    </ResponseField>

    <ResponseField name="username" type="string">
      (unique) User's username.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.secrets`

<ResponseField name="event.secrets" type="secrets">
  Secret values securely associated with this Action.
</ResponseField>


# Actions Limitations
Source: https://auth0.com/docs/customize/actions/limitations

Learn about the limitations involved with using Auth0 Actions.

The following limitations exist when using Actions:

<Callout icon="file-lines">
  Learn more about Entity Limits, read: [Actions Entity Limits](/docs/troubleshoot/customer-support/operational-policies/entity-limit-policy#actions).
</Callout>

## Actions

* Each Action should not exceed 100 kB. The larger the size, the more latency is introduced, which may have an impact on the performance of your system. This size limit does not include any `npm` modules that may be referenced as part of any `require` statements.

## Actions Modules

* Each Action Module can have dependencies to NPM Modules, but not to other Actions Modules.
* **Actions Modules do not have their own runtime.** They run in the runtime of the Action that includes them.

<Warning>
  **When you build an Action Module, Auth0 builds it with the builder runtime. However, when the module is executed, it uses the runtime of the Action that imports it.**

  *Example:*

  *If your Action Module uses Node.js API calls that are deprecated in Node.js 22, Actions using Node.js 18 runtime will work fine, but Actions using Node.js 22 runtime will fail.*
</Warning>

<Callout icon="file-lines">
  Write Actions Modules using Node.js APIs that are compatible with all runtime versions you plan to support.
</Callout>

## Account Linking (setPrimaryUser)

* `primary_user_id` is limited to 128 characters
* `setPrimaryUser` can be called once per transaction
* Any userMetadata set in the same Action as `setPrimaryUser` is discarded and will be lost. Subsequent Actions within the same transaction will retain userMetadata on the new primary user.
* `setPrimaryUser` can not be used in the same transaction where a Rule sets `context.primaryUser.`

## Cached data

* Cached items persist for a maximum of 24 hours.
* A maximum of 20 entries can be cached per Trigger.
* Cache keys have a maximum size of 64 bytes and values have a maximum size of 4kB.
* The cumulative size of cached keys and their values must not exceed 8kB.
* The cache should be available for all Actions in the same trigger for a single execution reliably, however for subsequent executions (such as a different flow, another user login, or a user returning from a redirect action) it is not guaranteed.
* Actions that perform an Execution that yields back (such as a redirect) may result in subsequent actions being scheduled on a separate instance with a different cache state. Cached data could be inconsistent from one Action to the next even if it is the same execution.

## Executions

* Each execution of a trigger must complete in 20 seconds or less or the processing will end in an error. Limiting HTTP requests is the best way to keep within this time limit.
* Each execution of a trigger must complete in 20 seconds or less or the processing will end in an error. Limiting long-running processes, like outbound HTTP requests without a timeout, is necessary to keep within this time limit. An Action that [redirects users to an external page](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/redirect-with-actions) has a separate timeout before the redirect and after.
* A new `event.request` object is issued anytime an Action trigger is suspended and then subsequently resumed (for example, due to a redirect or <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> challenge).

## Logs

* A maximum of 256 characters may be persistently stored for `console.log()` outputs for each Action.
* Execution logs are retained for 10 days.

## Programming languages

* We do not support Typescript in actions. Source files must be written in JavaScript before being deployed.

## Secrets

* Each secret key may have a maximum length of 128 characters.
* Each secret value may have a maximum length of 4096 characters.

## SAML attributes

* A maximum of 100 <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> attributes can be changed or added by Actions.
* SAML attribute names have a maximum size of 1kB.
* SAML values have a maximum size of 2kB.
* The total SAML assertions have a maximum size of 10kB.

## SAML configuration

* `audience` has a maximum size of 2kB
* `recipient` has a maximum size of 2kB
* `destination` has a maximum size of 2kB
* `nameIdentifierFormat` has a maximum size of 0.5kB
* `nameIdentifierProbes` has a maximum of 10 probes with a maximum size of 0.5kB each
* `authnContextClassRef` has a maximum size of 0.5kB
* `signingCert` has a maximum size of 4kB
* `encryptionCert` has a maximum size of 4kB
* `encryptionPublicKey` has a maximum size of 4kB
* `cert` has a maximum size of 4kB
* `key` has a maximum size of 4kB

## Service requests

* Calls made to the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> and User Metadata updates are [rate limited](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/management-api-endpoint-rate-limits).
* HTTP calls to external services originate from [these IP addresses](/docs/secure/security-guidance/data-security/allowlist).

## Transaction metadata

* Is available only on [post-login Actions](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger).
* Is not persisted beyond the completion of an authentication trigger.
* Cannot be accessed outside of the Actions within the same transaction.
* Keys are limited to 64 characters.
* Values are limited to 8 KB.
* Values only support `string`, `number`, and `boolean` types.
* Has a maximum total metadata size of 16 KB within the same transaction.
* Will not accept numbers that fail a safety check as valid values. Unsafe integer values should be safely serialized by the Developer. To learn more, read about [safe integers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isSafeInteger).

## Upstream tokens from external IdPs

* Retrieving External <Tooltip href="/docs/glossary?term=IdP">IdP</Tooltip> tokens from the Identities array

## User metadata and app metadata

* Each session may have a maximum of 32kB each of user metadata persistence and 32kB of app metadata persistence.

## Learn more

* [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview)


# Actions Modules
Source: https://auth0.com/docs/customize/actions/modules/actions-modules-overview

Describes how to share functions between Actions.

<Warning>
  Actions Modules is currently available in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0’s release stages, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

Actions Modules allow you to create, manage, and share reusable code across different Actions within your Auth0 Tenant.

Previously, each Action operated independently, making it difficult to share common functions between them without using external dependencies like NPM Modules. With Actions Modules, now it's possible to:

* Create custom modules with functions hosted by Auth0.
* Use the functions defined at each custom module within one or more Actions.
* Each custom module can define independent secrets and add dependencies to NPM modules.

To learn more about writing Actions with Actions Modules, read [Write Your First Action Module](/docs/customize/actions/modules/write-your-first-action-module).

<Callout icon="file-lines">
  Actions Modules are not bound to a particular Trigger or Action type, therefore, the functions defined in them can be reused across Actions bound to different Triggers.
</Callout>

To learn more about Actions Modules Limitations, read [Actions Limitations](/docs/customize/actions/limitations).

## Performance

By adopting Actions Modules according to the [Coding Guidelines](/docs/customize/actions/action-coding-guidelines), you can improve execution performance by sharing and reusing objects that have a costly instantiation process.

<Callout icon="file-lines">
  However, the improvement is not guaranteed, as it depends on the specific use case, the implementation, and the load and frequency of executions.
</Callout>


# Write Your First Action Module
Source: https://auth0.com/docs/customize/actions/modules/write-your-first-action-module

Describes how to use Auth0 Actions Modules

## Get Started

Use the quickstart to write an Action Module and use it from an Action to send logs to an external service.

<Steps>
  <Step title="Create an Action Module">
    To use an Action Module from a specific Action, you first need to create the Action Module and then add/use it in an Action.

    <Tabs>
      <Tab title="Dashboard">
        1. Navigate to [Auth0 Dashboard > Actions > Library](https://manage.auth0.com/#/actions/library) then select **Modules**.
        2. Select **Create Module**.
        3. Enter a **Name**.
        4. Select **Create**.

        Auth0 displays the Code Editor

        <Frame>
          <img alt="Actions Modules - New Action Module" />
        </Frame>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Add a Secret">
    Each Action Module can contain secret key/values pairs. Use these to hold sensitive information, such as API Keys, certificates, and values that may change across environments.

    <Tabs>
      <Tab title="Dashboard">
        Let’s store the external service URL as a Secret.

        1. Select the **<svg><path /></svg>** icon from the code editor's left sidebar.
        2. Select **Add Secret**.
        3. Enter the **Name** as `SERVICE_URL`.
        4. Enter the external service URL at the **Value** field.
        5. Select **Create**.

        <Frame>
          <img alt="Actions Modules - Secret added" />
        </Frame>

        Auth0 adds the Secret to the Action Module Secret list.
      </Tab>
    </Tabs>

    **Extra Step:** Repeat the steps to store an `API_KEY` as a Secret that you will send in the headers to the external service in each request.

    <Callout icon="file-lines">
      Once you create a Secret, Auth0 never reveals its value. Auth0 encrypts all Secrets and stores them securely.
    </Callout>

    <Warning>
      Each **Action Module Secret** is independent from other **Actions Modules** and **Actions Secrets**.
    </Warning>

    <Callout icon="file-lines">
      Use **Secrets** at the Action Module by typing `actions.secrets.[secret_key]`.
    </Callout>
  </Step>

  <Step title="Add Custom Logic">
    Now, add the following code to your Action Module.

    <Tabs>
      <Tab title="Dashboard">
        Add the following code to your Action Module:

        ```javascript lines theme={null}
        module.exports = {
          sendLog: async (code, message) => {
            try {
              await fetch(actions.secrets.SERVICE_URL, {
                method: 'POST',
                headers: {
                  'X-API-Key': actions.secrets.API_KEY,
                },
                body: JSON.stringify({
                  code,
                  message
                }),
              });

              console.log({
                code,
                message
              });
            } catch (err) {
              throw new Error('External service failure');
            }

            return;
          }
        };
        ```
      </Tab>
    </Tabs>

    <Callout icon="file-lines">
      Be aware of:

      * [Coding Guidelines](/docs/customize/actions/action-coding-guidelines#actions-modules)
      * [Limitations](/docs/customize/actions/limitations#actions-modules)
    </Callout>
  </Step>

  <Step title="Save the Draft">
    You can save a draft of your Action Module.

    <Tabs>
      <Tab title="Dashboard">
        1. Select **Save Draft**.

        <Frame>
          <img alt="Actions Modules - Draft saved" />
        </Frame>
      </Tab>
    </Tabs>

    This saves your Action Module without publishing a new version, so it does not affect Actions using it.
  </Step>

  <Step title="Publish the Action Module">
    Once you are satisfied with the Action Module code, it’s time to **Publish** it.

    <Tabs>
      <Tab title="Dashboard">
        1. Select **Publish**.

        <Callout icon="file-lines">
          Publishing an Action Module takes a snapshot of it at that time and records it as an **Action Module Version**.
        </Callout>

        2. Select **View Version History**.

        <Frame>
          <img alt="Actions Modules - Version History" />
        </Frame>

        Auth0 displays the list of Action Module Versions including the draft.
      </Tab>
    </Tabs>

    You are now able to start using the Action Module in an Action.

    <Warning>
      Each **Action** must explicitly reference the **Action Module Version**, preventing automatic upgrades that could introduce unexpected errors.
    </Warning>
  </Step>

  <Step title="Add the Action Module in an Action">
    Let’s add the Action Module in an Action.

    <Tabs>
      <Tab title="Dashboard">
        1. Navigate to [Auth0 Dashboard > Actions > Library](https://manage.auth0.com/#/actions/library) then select a specific **Action**.
        2. Once at the Action Editor, select the **<svg><path /></svg>** icon from the left sidebar.
        3. Select **Add Module**.
        4. Select a Module **Name** and **Version**.
        5. Select **Add**.

        <Frame>
          <img alt="Actions - Add Action Module" />
        </Frame>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Use the Action Module in the Action">
    Now, let’s use the Action Module in the Action.

    <Tabs>
      <Tab title="Dashboard">
        1. Add the **require** statement.

        ```javascript lines theme={null}
        const logger = require('actions:logger');
        ```

        <Callout icon="file-lines">
          The **require** statement references the Action Module with the format **actions:\[module-name]**.
        </Callout>

        2. Add the call to `logger.sendLog` in the **Action function**, where you want to send logs.

        ```javascript lines theme={null}
        await logger.sendLog('logger_success', 'Your Action was able to use the Logger Action Module');
        ```

        3. Select **Deploy** the Action.

        <Frame>
          <img alt="Actions - Use Action Module" />
        </Frame>
      </Tab>
    </Tabs>

    <Warning>
      Remember to bind the Action to a Trigger.
    </Warning>
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a fully functional **Action Module** being used by an **Action**.
</Check>

***

## Advanced Usage

<Accordion title="NPM Dependencies">
  Each **Action Module** can add/use **[NPM Dependencies](https://www.npmjs.com/)**.

  <Tabs>
    <Tab title="Dashboard">
      1. Select the **<svg><path /></svg>** icon from the code editor's left sidebar.
      2. Select **Add Dependency**.
      3. Enter the **Name** of the **NPM package**.
      4. Enter the **Version** of the **NPM package**.
      5. Select **Create**.

      <Frame>
        <img alt="Actions Modules - Dependency added" />
      </Frame>

      Auth0 adds the Dependency to the Action Module Dependency list.
    </Tab>
  </Tabs>

  <Callout icon="file-lines">
    Use the listed **Dependencies** at the Action Module by requiring them through `require('[package-name]')`.
  </Callout>

  <Warning>
    When you save this Action, Auth0 resolves the latest version of your dependency and replaces it with a specific version number to keep future updates to the package from breaking your Action.

    You can provide a specific version instead of latest.
  </Warning>
</Accordion>


# Actions Transaction Metadata
Source: https://auth0.com/docs/customize/actions/transaction-metadata

Describes how to pass user or application metadata between login and post-login Actions.

Actions Transaction Metadata stores, accesses, and/or shares, custom metadata within a [post-login](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) Action for the duration of a transaction.

Previously, each Action operated independently, making it difficult to pass information between them. With Actions Transaction Metadata, now it's possible to:

* Share data across Actions, such as API responses or intermediate calculations.
* Eliminate the need to re-fetch or re-calculate the same information in different Actions.

<Callout icon="file-lines">
  Before using transaction metadata in development, we recommend reviewing the limitations. To learn more, read [Actions Limitations](/docs/customize/actions/limitations).
</Callout>

## How it works

Use the [post-login API object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object) `api.transaction.setMetadata` to set the key/value pair in order to store transaction metadata.

Use the [post-login Event object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object) `event.transaction.metadata` to access stored key/value pair in the same Action or subsequent Actions on the post-login trigger for a single execution.

The API and Event objects accept the following parameters:

<table>
  <thead>
    <tr>
      <th><strong>Value</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>Key</code></td>
      <td><code>String</code></td>
      <td>The key of the metadata property to be set.</td>
    </tr>

    <tr>
      <td><code>Value</code></td>
      <td><code>String</code>, <code>Number</code>, <code>Boolean</code></td>
      <td>The value of the metadata property.<br />Set to <code>null</code> removes the property.</td>
    </tr>
  </tbody>
</table>

To learn more about writing Actions, read [Write Your First Action](/docs/customize/actions/write-your-first-action).

## Latency

Using Actions Transaction Metadata could cause a nominal additional latency. Any latency would be proportional to the metadata payload size and would be relevant when Action suspensions happen. For example, triggering <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip>, redirecting from Actions, or rendering Forms, could cause latency issues due to the need of reloading data from storage.

Still, the potential latency should be minimal than the redundant outgoing HTTP requests to retrieve data the sequence of Actions needs.

## Examples

### Access metadata immediately

Set key/value pairs in transaction metadata and access values immediately.

```text lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  api.transaction.setMetadata('hello', 'Auth0');

  console.log('Hello ', event.transaction?.metadata?.hello);
  /* Outputs "Hello Auth0" */
};
```

### Set supported values

Set values of types: `string`, `number`, and `boolean`.

```text lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  api.transaction.setMetadata('string_value', 'Auth0');
  api.transaction.setMetadata('boolean_value', true);
  api.transaction.setMetadata('number_value', 12);

  console.log('string_value', event.transaction?.metadata?.string_value);
  /* Outputs "string_value Auth0" */
  console.log('boolean_value', event.transaction?.metadata?.boolean_value);
  /* Outputs "boolean_value true" */
  console.log('number_value', event.transaction?.metadata?.number_value);
  /* Outputs "number_value 12" */
};
```

### Serialize values

Serialize values as `strings` within [limits](/docs/customize/actions/limitations#transaction-metadata).

<Callout icon="file-lines">
  You cannot set values of types: `object` or `array`, but you can serialize as `strings.`
</Callout>

```text lines expandable theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const serialized_object_value = JSON.stringify({
    string_value: 'Auth0',
    boolean_value: true,
    number_value: 12
  });

  api.transaction.setMetadata('serialized_object_value', serialized_object_value);

  const serialized_array_value = JSON.stringify([
    'Auth0',
    true,
    12
  ]);
  api.transaction.setMetadata('serialized_array_value', serialized_array_value);

  console.log('serialized_object_value',
    JSON.parse(event.transaction?.metadata?.serialized_object_value)
  );
  /* Outputs "serialized_object_value { string_value: 'Auth0', boolean_value: true, number_value: 12 }" */

  console.log('serialized_array_value',
    JSON.parse(event.transaction?.metadata?.serialized_array_value)
  );
  /* Outputs "serialized_array_value [ 'Auth0', true, 12 ]" */
};
```

### Share values between Actions

Share key/value pairs between Actions in the same execution sequence.

**Action 1**

Set `hello` key with `Auth0` value with the `api` object `setMetadata` method.

```text lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  api.transaction.setMetadata('hello', 'Auth0');
};
```

**Action 2**

Log the `Auth0` value for `hello` key in the transaction metadata with the `event` object `transaction.metadata` property to access the set values.

```text lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  console.log('Hello', event.transaction?.metadata?.hello);
  /* Outputs "Hello Auth0" */
};
```

### Update metadata

Set an existing key with a different value to update metadata.

**Action 1**

Set transaction metadata key/value pair as `custom_tx_id` and `xyz123`.

```text lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  api.transaction.setMetadata('custom_tx_id', 'xyz123');
};
```

**Action 2**

Log the key as `custom_tx_id` and the value as `xyz123`. Then, set `custom_tx_id` to `abc456` to log again with the latest value for `custom_tx_id` in the transaction metadata.

```text lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  console.log('custom_tx_id', event.transaction?.metadata?.custom_tx_id);
  /* Outputs "custom_tx_id xyz123" */

  api.transaction.setMetadata('custom_tx_id', 'abc456');

  console.log('custom_tx_id', event.transaction?.metadata?.custom_tx_id);
  /* Outputs "custom_tx_id abc456" */
};
```

**Action 3**

Log the `abc456` value for `custom_tx_id`.

```text lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  console.log('custom_tx_id', event.transaction?.metadata?.custom_tx_id);
  /* Outputs "custom_tx_id abc456" */
};
```

### Remove metadata

Remove transaction metadata values by nullifying the value of each particular key.

**Action 1**

Set `custom_tx_id` in the transaction metadata.

```text lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  api.transaction.setMetadata('custom_tx_id', 'xyz123');
};
```

**Action 2**

Set `custom_tx_id` to `null` and log the `null` value for `custom_tx_id`.

```text lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  console.log('custom_tx_id', event.transaction?.metadata?.custom_tx_id);
  /* Outputs "custom_tx_id xyz123" */

  api.transaction.setMetadata('custom_tx_id', null);

  console.log('custom_tx_id', event.transaction?.metadata?.custom_tx_id);
  /* Outputs "custom_tx_id undefined" */
};
```

**Action 3**

Logs the `null` value for `custom_tx_id`.

```text lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  console.log('custom_tx_id', event.transaction?.metadata?.custom_tx_id);
  /* Outputs "custom_tx_id undefined" */
};
```

### Preserve values on redirect to external sites

Preserve transaction metadata during [redirects](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/redirect-with-actions). Values are available when users continue the authentication flow.

**Action 1**

Sets a `custom_tx_id` in the transaction metadata.

```text lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  api.transaction.setMetadata('custom_tx_id', 'xyz123');
};
```

**Action 2**

Redirects to an external site sending a token with the `custom_tx_id` from the transaction metadata. Then it compares the `custom_tx_id` value at the transaction metadata with the one passed to the external site that has been sent back in the payload of another token.

```text lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const token = api.redirect.encodeToken({
    secret: event.secrets.REDIRECT_SECRET,
    expiresInSeconds: 60, 
    payload: {
      custom_tx_id: event.transaction?.metadata?.custom_tx_id,
      continue_uri: `https://${event.secrets.TENANT_DOMAIN}/continue`
    },
  });

  api.redirect.sendUserTo(event.secrets.REDIRECT_URL, {
    query: { session_token: token }
  });
};

exports.onContinuePostLogin = async (event, api) => {
  const payload = api.redirect.validateToken({
    secret: event.secrets.REDIRECT_SECRET
  });

  console.log('Does custon_tx_id match?',
    payload?.custom_tx_id === event.transaction?.metadata?.custom_tx_id
  );
  /* Outputs "Does custon_tx_id match? True" */
};
```

### Preserve values on Forms rendering

[Render Forms using Actions](/docs/customize/forms/render) and transaction metadata values would be preserved and available when users continue the authentication flow.

To learn more about using Forms with Actions, read [Render Forms using Actions](/docs/customize/forms/render).

**Action 1**

Sets a `custom_tx_id` in the transaction metadata.

```text lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  api.transaction.setMetadata('custom_tx_id', 'xyz123');
};
```

**Action 2**

Renders a Form. Then it logs the preserved `custom_tx_id` when continuing the Actions execution.

```text lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  api.prompt.render(event.secrets.FORM_ID);
};

exports.onContinuePostLogin = async (event, api) => {
  console.log('custon_tx_id', event.transaction?.metadata?.custom_tx_id);
  /* Outputs "custom_tx_id xyz123" */
};
```

### Share values with Forms

You can render Forms using Actions and pass transaction metadata values to the Form.

**Action 1**

Sets a `custom_tx_id` in the transaction metadata.

```text lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  api.transaction.setMetadata('custom_tx_id', 'xyz123');
};
```

**Action 2**

Renders a Form passing the `custom_tx_id` from the transaction metadata as `vars` parameter. Then it compares the `custom_tx_id` value at the transaction metadata with the one passed to the Form, when continuing the Actions execution.

```text lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  api.prompt.render(event.secrets.FORM_ID, {
    vars: {
      custom_tx_id: event.transaction?.metadata?.custom_tx_id
    }
  });
};

exports.onContinuePostLogin = async (event, api) => {
  console.log('Does custon_tx_id match?',
    event.prompt?.vars?.custom_tx_id === event.transaction?.metadata?.custom_tx_id
  );
  /* Outputs "Does custon_tx_id match? True" */
};
```


# Action Use Cases
Source: https://auth0.com/docs/customize/actions/use-cases

Explore a variety of examples of implementations using Actions.

The following is a list of Actions for implementing a variety of functionality in Auth0.

## Access Control

* [Allow access only on weekdays for a specific application](/docs/manage-users/access-control/sample-use-cases-actions-with-authorization#allow-access-only-on-weekdays-for-a-specific-application)
* [Allow access only to users who are inside the corporate network](/docs/manage-users/access-control/sample-use-cases-actions-with-authorization#allow-access-only-to-users-who-are-inside-the-corporate-network)
* [Only allow users with specific email addresses to log in](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger#access-control)

## API Authorization

* [Add user roles to tokens](/docs/manage-users/access-control/sample-use-cases-actions-with-authorization#add-user-roles-to-tokens)
* [Add a user's email address to the Access Token](/docs/get-started/architecture-scenarios/mobile-api/api-implementation-nodejs#4-determine-the-user-identity)
* [Deny access to anyone calling an API](/docs/manage-users/access-control/sample-use-cases-actions-with-authorization#deny-access-to-anyone-calling-an-api)
* [Add custom claims to a token](/docs/get-started/apis/scopes/sample-use-cases-scopes-and-claims#add-custom-claims-to-a-token)
* [Exchange an existing Auth0 token to access another audience on behalf of the same user](/docs/authenticate/custom-token-exchange/cte-example-use-cases#use-case%3A-get-auth0-tokens-for-another-audience)

## Compliance

* [Update user profile metadata with user consent choice and redirect users to a consent page hosted by a third party](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-track-consent-with-lock)
* [Enable Strong Customer Authentication (SCA) and dynamically link operation details to authorize a sensitive transaction](/docs/secure/highly-regulated-identity/transactional-authorization-with-authorization-code-flow)

## Multifactor

* [Require Multi-factor Authentication for users who are outside the corporate network](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger#enforce-custom-mfa-policy)
* [Send a verification email](/docs/customize/actions/explore-triggers/password-reset-triggers/post-change-password-trigger#send-an-email-after-the-user-changes-their-password)

## User Profile and Identity

* [Set a default user picture](/docs/manage-users/user-accounts/change-user-picture#change-default-picture-for-all-users)
* [Retrieve user preferences from an external source and add to the user identity](/docs/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger#store-a-user-id-from-another-system-in-the-user-profile)

## Advanced Integration Use Cases

* [Seamless migration into Auth0](/docs/authenticate/custom-token-exchange/cte-example-use-cases#use-case%3A-seamless-migration-into-auth0)
* [Re-use an external authentication provider](/docs/authenticate/custom-token-exchange/cte-example-use-cases#use-case%3A-re-use-an-external-authentication-provider)


# Write Your First Action
Source: https://auth0.com/docs/customize/actions/write-your-first-action

Learn how to write an Action, which includes choosing a flow, creating an Action and configuring it, and binding it to the flow.

This guide will walk you through how to create and deploy your first Action using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. When you finish, you should understand the basic functionality that you will use with all Actions and you will be familiar with the programming model. What you will learn constitutes the foundation of writing any Action, regardless of its purpose or the flow.

## The goal: notify Slack on user login

You are creating an Action that sends a message to a Slack channel when a user logs in. While this tutorial will use the Post Login trigger, the information provided here is useful for triggers of any type.

To accomplish this task, you will do the following:

* [Create an Action](#create-an-action)
* [Add a Secret](#add-a-secret)
* [Add a dependency](#add-a-dependency)
* [Save the Draft](#save-the-draft)
* [Add custom logic](#add-custom-logic)
* [Test an Action](#test-an-action)
* [Deploy an Action](#deploy-the-action)
* [Attach an Action to a Flow](#attach-the-action-to-a-flow)
* [See the results of an Action in Tenant Logs](#observe-actions-in-tenant-logs)

## Prerequisites

Because this Action will be sending messages to a Slack channel, you need to [create an Incoming Webhook for a Slack Workspace](https://api.slack.com/messaging/webhooks). Once you have a Slack Webhook URL, you may continue with this guide.

## Create an Action

To get an Action working in a specific flow, you need to create the Action and then add it to a flow.

1. Navigate to [Auth0 Dashboard > Actions > Library,](https://manage.auth0.com/#/actions/library) then select **Create Action** > **Build from scratch**.
2. Enter a **Name** and select the **Login / Post Login** trigger since you’ll be adding an Action to the Login flow, then select **Create.**

The Actions Code Editor appears:

<Frame>
  <img alt="Actions Code Editor" />
</Frame>

## Create an Action from a Template

The Actions Template gallery offers a variety of starter templates on their way to creating an Action. To create an Action from a Template:

1. Navigate to [Auth0 Dashboard > Actions > Library](https://manage.auth0.com/#/actions/library), then select **Create Action.**
2. Select **Choose from template**.
3. Select the template that you would like to use for building an Action.
4. You should now see a read-only preview of the code within the template. To proceed, select **Use this template**.
5. Enter a name, and select **Create**.

## Add a Secret

Each Action can contain Secret values, which are suitable for holding sensitive information, such as <Tooltip href="/docs/glossary?term=Access+Tokens">Access Tokens</Tooltip> and API Keys. Let’s store the Slack Webhook URL as a Secret.

1. Select the Key Icon from the code editor's left sidebar
2. Select **Add Secret**.
3. Give the Secret the following name: `SLACK_WEBHOOK_URL`.
4. Paste in the Webhook URL provided by Slack and select **Create**.

You’ll see that the Secret has been added to the Action and you can use the new secret via intelligent code complete by typing `event.secrets`.

<Frame>
  <img alt="Actions Code Editor - Your Secret has been added in the Secrets section." />
</Frame>

<Callout icon="file-lines">
  Once a Secret has been created, its value will never be revealed. Auth0 encrypts all Secrets and stores them securely.
</Callout>

## Add a dependency

You’ll be using the [`@slack/webhook` `npm` package](https://www.npmjs.com/package/@slack/webhook) to make it easy to send a message to Slack. You can use nearly any public `npm` package in an Action as long as it can be installed without relying on [native add-ons](https://www.npmjs.com/package/node-gyp).

To add the dependency:

1. Select the Dependency icon (cube icon) in the sidebar.
2. For **Name**, enter `@slack/webhook`.

   By default, your Action will use the latest version of the dependency at the time the dependency was added.
3. Select **Create**, and the Dependency should be added to the Action:

   <Frame>
     <img alt="Actions Code Editor: Your dependency has been added." />
   </Frame>

<Callout icon="file-lines">
  When you save this Action, the latest version of your dependency will be resolved and replaced with a specific version number to keep future updates to the package from breaking your Action.
</Callout>

## Save the Draft

Select **Save Draft**. Your Action is saved, but it won’t be executed as part of any user flows yet. With Actions, you have the opportunity to create, edit, and test Actions before they affect any traffic in your Auth0 tenant. Once you’re happy with the behavior of the Action, you’ll deploy the Action and add it to a Flow later.

## Add custom logic

Now that the Action has been configured with a Secret and a dependency, let’s write some code!

Every Action has an event object that contains read-only, contextual information relevant to the associated trigger. If you start typing `event.` in the Editor, you should be presented with all the available properties of the event. To learn more about which information is available on each trigger, read [Explore Flows and Triggers](/docs/customize/actions/explore-triggers).

Let’s use our Action to notify Slack. Add this code to your action:

```javascript lines theme={null}
const { IncomingWebhook } = require('@slack/webhook');

exports.onExecutePostLogin = async (event, api) => {
    const url = event.secrets.SLACK_WEBHOOK_URL;
    const webhook = new IncomingWebhook(url);

    // Send the notification
    await webhook.send({ text: "Logging In..." });
};
```

Select **Save Draft** to save your Action.

## Test the Action

Before you run this Action in your tenant with real user traffic, test it to ensure it behaves as expected.

1. Select the Test (triangle) icon in the sidebar. In the Payload section, you’ll see editable JSON data relevant to the trigger that you selected when you created the Action.

   <Frame>
     <img alt="Actions Code Editor: Test Runner panel" />
   </Frame>
2. Select the **Run** button, and you should see a message appear in your Slack channel.

## Deploy the Action

Now that we’re satisfied that the Action is working as expected, it’s time to deploy it.

Select **Deploy**. Deploying an Action takes a snapshot of the Action at that time and records it as an **Action Version**.

Select **Version History**, and you should see the Action recorded as Version 1:

<Frame>
  <img alt="Actions: Version History" />
</Frame>

You are now free to update your Action and save it without affecting Version 1 of your Action. Auth0 will only execute the currently deployed version of an Action, so until you deploy an action again, Version 1 will be executed by Auth0.

## Attach the Action to a Flow

The final step in configuring a new Action so that it’s executed as part of your tenant’s traffic is to attach it to a Flow.

1. Navigate to [Auth0 Dashboard > Actions > Flows](https://manage.auth0.com/#/actions/flows) to see a list of the available Flows:
2. Select the [Login flow](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) and drag `my-slack-action` into the flow.

   <Frame>
     <img alt="Actions Flows: Login Flow" />
   </Frame>
3. Select **Apply**.

The Action is now running for real user traffic within your tenant. If you’d like a more robust testing environment, consider [setting up multiple Auth0 environments](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments).

## Observe Actions in Tenant Logs

Now that your Action is running as part of the Login flow, Auth0 captures information about each Action execution in the tenant logs. To view this, navigate to [Auth0 Dashboard > Monitoring > Logs](https://manage.auth0.com/#/logs), and select a **Successful Login** event.

You should see an **Action Details** view that contains information about any Actions that were executed as part of that flow.

<Frame>
  <img alt="Tenant Logs: Action Details view" />
</Frame>

## Next steps

Now that you’ve written your first Action, check out [Explore Flows and Triggers](/docs/customize/actions/explore-triggers) to learn how to perform some common tasks with Actions.


# Custom Domains
Source: https://auth0.com/docs/customize/custom-domains

Understand how a custom domain (CNAME or vanity URL) can help you unify your brand and show continuity to your users.

<Card title="Overview">
  Key Concepts

  * Configure Auth0 services to work your custom domain.
  * Complete the verification process for your custom domain through Auth0 Dashboard.
  * Check the table of features that work with custom domain.
  * Review how custom domains work with URIs and token requests.
  * Decide if you are going to manage your certificates or if you want Auth0 to manage certificates for you.
</Card>

You can use your own domain name (also known as a CNAME or vanity URL) on authentication pages. A <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip> lets you unify the login experience with your own brand and products. Your users see a URL that displays your brand such as `login.YOUR_DOMAIN.com` instead of `YOUR_DOMAIN.auth0.com.` The custom domain in Auth0 is like a "mask" for your tenant domain URL.

You can configure your custom domain when you create your tenant or you can add a custom domain to an existing implementation with minor code and configuration changes.

## Benefits of using a custom domain

With a custom domain, your users feel confident that they are providing their credentials to the right party. Authentication happens within the context of your brand which helps you build brand loyalty. Users are not redirected to a third-party site that breaks the branding context. This prevents users from becoming confused about whether they are still making a transaction or operation with you.

Containing your authentication services in one place makes your application architecture more maintainable. Applications gain only the access they need and authentication services scale easily. Other security benefits of using a custom domain include:

* Some browsers, by default, make it difficult to communicate in an iFrame if you don't have a shared domain.
* It's harder to phish your domain if you have a vanity URL because the phisher must create a vanity URL to mimic yours. For example, with a custom domain, you can use your own certificate to get an Extended Validation, making phishing harder.
* [Passkeys](/docs/authenticate/database-connections/passkeys), a phishing-resistant alternative to traditional authentication factors, are bound to your custom domain by the relying party ID attribute `rpId`.

<Callout icon="file-lines">
  Before you configure your custom domain, we recommend you use the parent or root domain (e.g. `yourDomain.com`) rather than a subdomain (`login.yourDomain.com`). If your custom domain in Auth0 is set to the root domain, end users can use a single passkey to authenticate across native or mobile web applications. To learn more, read [Configure Passkey Policy](/docs/authenticate/database-connections/passkeys/configure-passkey-policy#configure-relying-party-id-rpid).
</Callout>

## How it works

You configure a custom domain on the [Auth0 Dashboard > Branding > Custom Domains](https://manage.auth0.com/#/custom_domains) tab in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. Add your custom domain, choose your certification type and follow the instructions. You will complete a verification process for your domain that varies depending on whether you use an Auth0-managed or a self-managed certificate. When you create a CNAME, you must declare it to Auth0 so that Auth0 can verify it and use the custom domain. After you configure and verify the custom domain, you must [configure the Auth0 features](/docs/customize/custom-domains/configure-features-to-use-custom-domains) to use the new custom domain.

<Callout icon="file-lines">
  To set up a free custom domain, Auth0 tenants must have a valid credit card on file for verification purposes and fraud prevention. The credit card will not be charged.
</Callout>

Auth0 recommends that you create your custom domain during the development phase (before you go to production) so that you can ensure that you have managed the CNAME correctly. For example, you can create a CNAME that maps `login.YOUR_DOMAIN.com` to `YOUR_DOMAIN.auth0.com`.

<Callout icon="file-lines">
  Auth0 does not provide a static list of IP addresses because they are subject to change. We recommend that you add your custom domain to the [Allow List](/docs/secure/security-guidance/data-security/allowlist) instead.
</Callout>

You can update an existing tenant to use a custom domain. Your existing integrations using `YOUR_DOMAIN.auth0.com` will continue to work. After the change, your users must log in again because existing sessions will no longer be valid. In addition, users may need to delete the browser cookie associated with your custom domain if errors are present during login. If you use embedded Lock or an SDK, you can choose to use the standard domain setting or a custom domain.

<Warning>
  Your custom domain must abide by HTTP best practices. If the field order is not correct, you could potentially send duplicate headers. See [RFC 7230 HTTP/1.1 Message Syntax Routing - Field Order](https://tools.ietf.org/html/rfc7230#section-3.2.2) for details.
</Warning>

### Custom domains and authentication

The following Auth0 authentication features support the use of custom domains.

<table>
  <thead>
    <tr>
      <th><strong>Feature or Flow</strong></th>
      <th><strong>Details</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Universal Login</td>
      <td>For a seamless and secure user experience</td>
    </tr>

    <tr>
      <td>MFA</td>
      <td>All factors</td>
    </tr>

    <tr>
      <td>Guardian</td>
      <td>Android SDK/Swift SDK/MFA Widget version 1.3.3/Guardian.js version 1.3.0 or later</td>
    </tr>

    <tr>
      <td>Emails</td>
      <td>Links included in the emails use your custom domain</td>
    </tr>

    <tr>
      <td>Connections</td>
      <td>Database, social, Google Workspace, Azure AD, ADFS, AD/LDAP</td>
    </tr>

    <tr>
      <td><Tooltip href="/docs/glossary?term=Lock">Lock</Tooltip></td>
      <td>Version 11 with cross-origin authentication</td>
    </tr>

    <tr>
      <td><Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip></td>
      <td>With Universal Login (The email link sent using the custom domain if the option is enabled in <strong>Dashboard > Tenant Settings > Custom Domains</strong>.)</td>
    </tr>

    <tr>
      <td><Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip></td>
      <td>Connections and applications</td>
    </tr>

    <tr>
      <td>WS-Federation</td>
      <td>Auth0 as identity provider using WS-Fed add-on</td>
    </tr>

    <tr>
      <td>OAuth 2.0/OIDC-Compliant flows</td>
      <td>Using the <a href="https://auth0.com/docs/api/authentication/authorization-code-flow/authorize-application"><code>/authorize</code></a> and <a href="https://auth0.com/docs/api/authentication/authorization-code-flow/get-token"><code>/oauth/token</code></a> endpoints</td>
    </tr>
  </tbody>
</table>

### Custom domains and URIs

Auth0 uses certain metadata endpoints for interoperability and configuration of third-party <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> and applications. When the metadata contains URIs that point back to Auth0, the URL can be either the Auth0 subdomain or your custom domain depending on the hostname you used to request the metadata. For example:

<table>
  <thead>
    <tr>
      <th><strong>If you use</strong></th>
      <th><strong>Reference Inside Metadata</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`https://travel0.auth0.com/.well-known/...`</td>
      <td>`https://travel0.auth0.com/...`</td>
    </tr>

    <tr>
      <td>`https://travel0.auth0.com/samlp/metadata/...`</td>
      <td>`https://travel0.auth0.com/...`</td>
    </tr>

    <tr>
      <td>`https://login.travel0.com/samlp/metadata/...`</td>
      <td>`https://login.travel0.com/...`</td>
    </tr>
  </tbody>
</table>

To learn more, review [Redirect Users After Login](/docs/authenticate/login/redirect-users-after-login).

This flexibility applies to the following authentication scenarios:

* [Configure Applications with OpenID Connect Discovery](/docs/get-started/applications/configure-applications-with-oidc-discovery)
* [Configure Auth0 as SAML Service Provider](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-auth0-saml-service-provider)
* [Configure Auth0 as SAML Identity Provider](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider)

### Custom domains and token requests

Auth0 issues tokens with the `iss` claim for the domain you used with the token request. For example:

<table>
  <thead>
    <tr>
      <th><strong>If you use</strong></th>
      <th><strong>Claim value for iss</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`https://travel0.auth0.com/authorize...`<br />`https://travel0.auth0.com/oauth/token...`</td>
      <td>`https://travel0.auth0.com/`</td>
    </tr>

    <tr>
      <td>`https://login.travel0.com/authorize...`<br />`https://login.travel0.com/oauth/token...`</td>
      <td>`https://login.travel0.com/`</td>
    </tr>
  </tbody>
</table>

If you obtain an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> for the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> using an <Tooltip href="/docs/glossary?term=authorization+flow">authorization flow</Tooltip> with your custom domain, you must call the Management API using the custom domain or your token will be considered invalid. The token's `iss` claim is independent of the <Tooltip href="/docs/glossary?term=audience">audience</Tooltip>. Audience values remain the same for tokens obtained using a custom domain. To learn more about tokens, review [Management API Access Tokens](/docs/secure/tokens/access-tokens/management-api-access-tokens).

## Certificate management options

### Auth0-managed certificates

Auth0 can manage the certificates for your custom domain and manage the SSL handshake directly. You add a CNAME record on the domain, Auth0 validates the record and generates the certificate on Auth0 servers. The certificate renews automatically every three months. Once verified, [configure your Auth0 features](/docs/customize/custom-domains/configure-features-to-use-custom-domains) to start using your custom domain. To learn more, review [Configure Custom Domains with Auth0-Managed Certificates](/docs/customize/custom-domains/auth0-managed-certificates).

### Self-managed certificates

You can obtain and [manage your own certificates](/docs/customize/custom-domains/self-managed-certificates) in Custom Domains. In this case, you are responsible for handling SSL certificates and setting up and managing a reverse proxy to send content to Auth0. Auth0 negotiates SSL with the proxy not directly with the end-user client. The proxy, in turn, negotiates SSL with the end-user. To prevent someone from trying to use your Auth0 account from a domain you don't own, Auth0 needs to validate that the domain belongs to you: You need to provide Auth0 with a header (`cname-api-key`) to validate. You must be an Auth0 Enterprise subscriber to use this option.

Auth0 provides instructions to configure a reverse proxy for the following providers:

* [Google Cloud Platform with Load Balancing](/docs/customize/custom-domains/self-managed-certificates/configure-gcp-as-reverse-proxy)
* [Cloudflare](/docs/customize/custom-domains/self-managed-certificates/configure-cloudflare-for-use-as-reverse-proxy)
* [AWS CloudFront](/docs/customize/custom-domains/self-managed-certificates/configure-aws-cloudfront-for-use-as-reverse-proxy)
* [Azure CDN](/docs/customize/custom-domains/self-managed-certificates/configure-azure-cdn-for-use-as-reverse-proxy)

## Learn more

* [Configure Features to Use Custom Domains](/docs/customize/custom-domains/configure-features-to-use-custom-domains)
* [Configure Custom Domains with Auth0-Managed Certificates](/docs/customize/custom-domains/auth0-managed-certificates)
* [Configure Custom Domains with Self-Managed Certificates](/docs/customize/custom-domains/self-managed-certificates)
* [Troubleshoot Custom Domains](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-custom-domains)


# Configure Custom Domains with Auth0-Managed Certificates
Source: https://auth0.com/docs/customize/custom-domains/auth0-managed-certificates

Learn how to configure custom domains where Auth0 manages the TLS (SSL) certificates.

If you want Auth0 to manage the certificates for your <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip>, you only need to add a CNAME record on the domain. Auth0 validates the record and then generates the certificate on Auth0 servers. These certificates are renewed automatically every three months. You can configure this easily, and you won't have to maintain the certificates yourself.

To set up your custom domain using Auth0-managed certificates, you must provide your domain name to Auth0 and verify that you own that domain. Once verified, you will need to configure your Auth0 features to start using your custom domain.

## Provide your domain name to Auth0

1. Go to [Dashboard > Settings > Custom Domains](https://manage.auth0.com/#/tenant/custom_domains) or [Dashboard > Branding > Custom Domains](https://manage.auth0.com/#/custom_domains). Enter your custom domain in the provided box, and select **Auth0-managed certificates.**
2. Click **Add Domain**.You can only add one domain per tenant even though the **Add Domain** button still appears after you add a domain.

## Verify ownership

Before you can use the domain with Auth0, you'll need to verify that you own it.

1. Go to [Dashboard > Branding > Custom Domains](https://manage.auth0.com/#/branding/custom_domains) and add the CNAME verification record listed in the Dashboard to your domain's DNS record.

   <Frame>
     <img alt="Auth0 Branding Custom Domains Auth0-Managed Certificate Verify Domain" />
   </Frame>
2. Click **Verify** to proceed.
   It may take a few minutes before Auth0 is able to verify your CNAME record, depending on your DNS settings. If Auth0 was able to verify your domain name, you'll see a confirmation window. This means the verification process is complete. Within 1 to 2 minutes, your custom domain should be ready to use.

## Add CNAME verification record to DNS record

Once added, the CNAME record must be present at all times to avoid issues during certificate renewal.

<Callout icon="file-lines">
  Auth0 recommends turning off CNAME flattening unless it's strictly necessary because CNAME flattening for Auth0 managed certificates is an unsupported configuration and may cause the custom domain to break without notice.
</Callout>

If you need to enable CNAME flattening for all subdomains managed by Cloudfare and also configure a specific subdomain to be an Auth0 custom domain, consider [delegating the subdomain](https://developers.cloudflare.com/dns/manage-dns-records/how-to/subdomains-outside-cloudflare/) for Auth0 to another DNS provider.
This will enable you to use CNAME flattening for all subdomains except the one used for Auth0.

The following steps may vary for your domain host provider.

1. Log in to your domain management service.
2. Create a new record.

   <table>
     <thead>
       <tr>
         <th>Parameter</th>
         <th>Value</th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td><strong>Record type</strong></td>
         <td><strong>CNAME</strong></td>
       </tr>

       <tr>
         <td><strong>Name</strong></td>
         <td>Enter your custom domain name (such as <strong>login.northwind.com</strong>).</td>
       </tr>

       <tr>
         <td><strong>Time to Live (TTL)</strong></td>
         <td>Use default value.</td>
       </tr>

       <tr>
         <td><strong>Value</strong></td>
         <td>Paste in the <strong>CNAME</strong> value provided by the Auth0 Dashboard for your domain's DNS record.</td>
       </tr>
     </tbody>
   </table>
3. When done, save your record.

If Auth0 was able to verify your domain name, you'll see a confirmation window. This means the verification process is complete. Within 1 to 2 minutes, your custom domain should be ready to use.

<Callout icon="file-lines">
  If your DNS provider enables a proxy on the CNAME record by default, it will leave the custom domain in a pending state indefinitely. You may need to check your DNS provider settings and disable the proxy.
</Callout>

If you are unable to complete the verification process, wait at least 4 hours before repeating these steps. To avoid any interruptions to your service, do not recreate the custom domain when reverifying. For troubleshooting guidelines, see [Troubleshoot Custom Domains](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-custom-domains).

## Additional steps for specific Auth0 features

There are additional configuration steps you must complete depending on which Auth0 features you are using. To learn more, see [Configure Features to Use Custom Domains](/docs/customize/custom-domains/configure-features-to-use-custom-domains).

## Learn more

* [Configure Features to Use Custom Domains](/docs/customize/custom-domains/configure-features-to-use-custom-domains)
* [TLS (SSL) Versions and Ciphers](/docs/customize/custom-domains/self-managed-certificates/tls-ssl)
* [Troubleshoot Custom Domains](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-custom-domains)
* [Configure Custom Domains with Self-Managed Certificates](/docs/customize/custom-domains/self-managed-certificates)


# Configure Features to Use Custom Domains
Source: https://auth0.com/docs/customize/custom-domains/configure-features-to-use-custom-domains

Learn how to configure a custom domain for Auth0 authentication features.

To configure Auth0 features to use your <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip>, you may need to complete additional steps depending on the features you are using. For example, you may need to make changes before you can use your custom domain on your login page or to call your APIs.

If you have been using Auth0 for some time and decide to enable a custom domain, you will have to migrate your existing apps and update the settings as described below, including to any VPN or firewall you use. Note that existing sessions created at `{yourDomain}` will no longer be valid once you start using your custom domain, so users will have to log in again.

## Prerequisites

You should have already configured and verified your custom domain.

## Features

<table>
  <thead>
    <tr>
      <th><strong>Feature</strong></th>
      <th><strong>Section to read</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> with a customized login page</td>
      <td><a href="#universal-login">Universal Login</a></td>
    </tr>

    <tr>
      <td>Lock embedded in your application</td>
      <td><a href="#embedded-lock">Embedded Lock</a></td>
    </tr>

    <tr>
      <td>Auth0 SPA SDK, Auth0.js, or other Auth0 SDKs</td>
      <td><a href="#auth0-spa-sdk-auth0-js-and-other-sdks">Auth0 SPA SDK, Auth0.js, and other SDKs</a></td>
    </tr>

    <tr>
      <td>Custom domain with Auth0 emails and phone notifications</td>
      <td><a href="#use-custom-domains-in-emails-and-phone">Use custom domains in emails and phone notifications</a></td>
    </tr>

    <tr>
      <td>Social identity providers</td>
      <td><a href="#configure-social-identity-providers">Configure social identity providers</a></td>
    </tr>

    <tr>
      <td>Google Workspace connections with your custom domain</td>
      <td><a href="#configure-g-suite-connections">Configure Google Workspace connections</a></td>
    </tr>

    <tr>
      <td>Issue Access Tokens for your APIs or access Auth0 APIs from your application</td>
      <td><a href="#apis">APIs</a></td>
    </tr>

    <tr>
      <td><Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> Identity Providers</td>
      <td><a href="#configure-saml-identity-providers">Configure SAML identity providers</a></td>
    </tr>

    <tr>
      <td>SAML applications</td>
      <td><a href="#configure-saml-applications">Configure SAML applications</a></td>
    </tr>

    <tr>
      <td>Web Service Federation (WS-Fed) applications</td>
      <td><a href="#configure-ws-fed-applications">Configure WS-Fed applications</a></td>
    </tr>

    <tr>
      <td>Azure AD connections</td>
      <td><a href="#configure-azure-ad-connections">Configure Azure AD connections</a></td>
    </tr>

    <tr>
      <td>ADFS connections</td>
      <td><a href="#configure-adfs-connections">Configure ADFS connections</a></td>
    </tr>

    <tr>
      <td>AD/LAP connections with Kerberos support</td>
      <td><a href="#configure-ad-ldap-connections">Configure AD/LAP connections</a></td>
    </tr>
  </tbody>
</table>

## Universal Login

If you use [Auth0 Universal Login](/docs/authenticate/login/auth0-universal-login) and you have customized the login page, you must update the code to use your custom domain. If you use the **default** login page without customization, you do not need to make any changes. To learn more, read Auth0 <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>.

If you use [Lock for Web](/docs/libraries/lock), you must set the `configurationBaseUrl` and `overrides` options as seen in the following sample script:

```javascript lines theme={null}
var lock = new Auth0Lock(config.clientID, config.auth0Domain, {
  //code omitted for brevity
  configurationBaseUrl: config.clientConfigurationBaseUrl,
  overrides: {
  	__tenant: config.auth0Tenant,
  	__token_issuer: config.authorizationServer.issuer
  },
  //code omitted for brevity
});
```

If you use [Auth0.js](/docs/libraries/auth0js) on the Universal Login page, you must set the `overrides` option.

```javascript lines theme={null}
var webAuth = new auth0.WebAuth({
  clientID: config.clientID,
  domain: config.auth0Domain,
  //code omitted for brevity
  overrides: {
  	__tenant: config.auth0Tenant,
  	__token_issuer: config.authorizationServer.issuer
  },
  //code omitted for brevity
});
```

For most, the Auth0.js and Lock libraries retrieve the tenant name (required for `/usernamepassword/login`) and the issuer (required for `id_token` validation) from the domain. However, if you're a Private Cloud customer who uses a proxy or a custom domain name where the domain name is different from the tenant/issuer, you can use `__tenant` and `__token_issuer` to provide your unique values.

## Embedded Lock

If you use [Lock for Web](/docs/libraries/lock) embedded in your application, you must update the code to use your custom domain when initializing Lock. You will also need to set the `configurationBaseUrl` to the appropriate CDN URL.

<AuthCodeBlock />

The CDN URL varies by region. Use `https://cdn.[us|eu|au|jp].auth0.com` (`us` for US, `eu` for Europe, `au` for Australia, or `jp` for Japan).

<Callout icon="file-lines">
  The CDN URL varies by region. Tenants created before 11 June 2020 should use `https://cdn.auth0.com` if the region is the United States, or add `eu`, `au`, `jp` for Europe, Australia, or Japan. If your tenant was created after 11 June 2020, use `https://cdn.us.auth0.com` if the region is the United States.
</Callout>

## Auth0 SPA SDK, Auth0.js, and other SDKs

If you use the [Auth0 SPA SDK](/docs/libraries/auth0-single-page-app-sdk), [Auth0.js](/docs/libraries/auth0js), or [other SDKs](/docs/troubleshoot/customer-support/product-support-matrix#auth0-sdks), you will have to initialize the SDK using your custom domain. For example, if you are using the Auth0.js SDK, you must set the following:

<AuthCodeBlock />

And for the Auth0 SPA SDK:

<AuthCodeBlock />

See APIs section below if you use a custom domain and also intend to perform [Management API actions with Auth0.js](/docs/libraries/auth0js#user-management).

## Use custom domains in emails and phone notifications

If you want to use your custom domain with your Auth0 emails or phone notifications, you must enable this feature.

1. Go to [Auth0 Dashboard > Branding > Custom Domains](https://manage.auth0.com/#/branding/custom_domains).
2. Enable the **Use Custom Domain in Emails** toggle.

## Configure Social identity providers

If you want to use your custom domain with Social <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> (IdP), you must update your IdP's list of Authorized Redirect URIs to include your custom domain (such as `https://login.northwind.com/login/callback`).

You cannot use [Auth0 developer keys](/docs/authenticate/identity-providers/social-identity-providers/devkeys) with custom domains.

## Configure Google Workspace connections

If you want to use your custom domain with Google Workspace connections, you must update the Authorized Redirect URI in your <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> Client Settings. In the Google Cloud Console, go to **Credentials**, choose your OAuth client in the list, and you will see a settings page with the app <Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>, secret, and other fields. In the **Authorized redirect URIs** field, add a URL in the format `https://<YOUR-CUSTOM-DOMAIN>/login/callback` that includes your custom domain (such as `https://login.northwind.com/login/callback`).

## APIs

API identifiers (i.e. `audience`) will not change. This is a constant value for each API, and despite the fact that it's conventional to use a URI, it is completely independent of the domain used to obtain the token.

Auth0 issues tokens with the `iss` claim of whichever domain you used to obtain the token.

##### Auth0 APIs

Continue to use your default tenant domain name (such as `https://{yourDomain}/userinfo` and `https://{yourDomain}/api/v2/`) instead of your custom domain when specifying an `audience`. This is the only place to use your default tenant domain.

All requests (i.e. obtaining the token, and actually calling the API) must use the same domain. Tokens obtained via a custom domain must be used on an Auth0 API using the same custom domain.

If you use an authentication flow with your Custom Domain to request <Tooltip href="/docs/glossary?term=Access+Tokens">Access Tokens</Tooltip> to access the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>, you must call the Management API endpoint with your Custom Domain too.

```json lines theme={null}
POST https://mycustomdomain.com/oauth/token
... // other parameters 
...
audience:https://defaulttenant.eu.auth0.com/api/v2/
```

Your Access Token request should be something similar to

```json lines theme={null}
GET https://mycustomdomain.com/api/v2/clients

Headers:
Authorization: Bearer <access_token>
```

##### Custom APIs

If you use Auth0 with a custom domain to issue Access Tokens for your APIs, you must validate the <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> issuer(s) against your custom domain. For example, if you use the [express-jwt](https://github.com/auth0/express-jwt) middleware, you must make the following change:

```js lines theme={null}
app.use(jwt({
  issuer: 'https://<YOUR-CUSTOM-DOMAIN>/',
  //code omitted for brevity
}));
```

## Configure SAML identity providers

To use your custom domain with <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> Identity Providers (IdPs), you must update your **Assertion Consumer Service (ACS) URL(s)** with the Identity Provider(s). Depending on what is supported by the IdP, you can do this in one of two ways:

1. You can get the service provider metadata from Auth0 at `https://<YOUR-CUSTOM-DOMAIN>/samlp/metadata?connection=<YOUR-CONNECTION-NAME>`. This will include the updated ACS URL. Then, you must manually update this value in your IdP(s) settings. This change to your IdP(s) must happen at the same time as you begin using your custom domain in your applications. This can pose a problem if there are multiple IdPs to configure.
2. If supported by the IdP, you can use signed requests to fulfill this requirement:

* Download the signing certificate from `https://<TENANT>.auth0.com/pem`. Note that `https://<YOUR-CUSTOM-DOMAIN>.com/pem` will return the same certificate
* Give the certificate to the IdP(s) to upload. This enables the IdP to validate the signature on the `AuthnRequest` message that Auth0 sends to the IdP
* The IdP will import the certificate and, if necessary, signature verification should be enabled (exact steps vary by IdP)
* Turn on the **Sign Request** toggle in the Dashboard under **Connections > Enterprise > SAML > CONNECTION**. This will trigger Auth0 to sign the SAML `AuthnRequest` messages it sends to the IdP.

Once this is done, and you start using your custom domain when you initiate an authentication request in your application, the IdP will receive that custom domain in your signed request. Because your application’s signed request is trusted, the IdP should automatically override whatever was configured as your ACS URL and replace it with the value sent in the signed request. However, there are IdPs that do **not** accept the ACS URL in the signed request, so you must check with yours first to confirm whether this is supported or not.

If this is supported, it will prevent you from having to change one or many IdP settings all at the same time and allow you to prepare them to accept your signed requests ahead of time. You can then change the statically configured ACS URL in your IdP settings at a later date as well.

Note that if your SAML identity provider is configured to use your custom domain, testing the connection via the **Try** button in the Dashboard will **not** work and the default links for downloading metadata from Auth0 will always show the default domain, not the custom domain.

If you have an IdP-initiated authentication flow, you will need to update the IdP(s) and your application(s) at the same time to use the custom domain.

## Configure SAML applications

If you want to use your custom domain with SAML applications (when Auth0 is the IdP), you must update your service provider with new identity provider metadata from Auth0. You can obtain the updated metadata reflecting the custom domain from `https://<YOUR-CUSTOM-DOMAIN>/samlp/metadata/<YOUR-CLIENT-ID>`. Note that the issuer entity ID for the assertion returned by Auth0 will change when using a custom domain (from something like `urn:northwind.auth0.com` to one with the custom domain, such as `urn:login.northwind.com`).

If you have an IdP-initiated authentication flow, you will need to update the URL used to invoke the IdP-initiated authentication flow to reflect the custom domain. Instead of `https://<TENANT>.auth0.com/samlp/<YOUR-CLIENT-ID>`, you should use `https://<YOUR-CUSTOM-DOMAIN>/samlp/<YOUR-CLIENT-ID>`.

## Configure WS-Fed applications

If you want to use your custom domain with <Tooltip href="/docs/glossary?term=WS-Fed">WS-Fed</Tooltip> applications with Auth0 as the IdP, you must update your Service Provider with new identity provider metadata from Auth0. You can obtain the metadata reflecting the custom domain from `https://<YOUR-CUSTOM-DOMAIN>/wsfed/FederationMetadata/2007-06/FederationMetadata.xml`.

## Configure Azure AD connections

If you want to use your custom domain with Azure AD connections, you must update the Allowed Reply URL in your Azure AD settings. In your Azure Active Directory, go to **Apps registrations** and select your app. Then click **Settings -> Reply URLs** and add a URL with your custom domain in the format `https://<YOUR-CUSTOM-DOMAIN>/login/callback` (such as `https://login.northwind.com/login/callback`).

## Configure ADFS connections

If you want to use your custom domain with ADFS connections, you must update the endpoint in your ADFS settings. This will need to be updated to use your custom domain in the callback URL in the format `https://<YOUR-CUSTOM-DOMAIN>/login/callback` (such as `https://login.northwind.com/login/callback`).

## Configure AD/LDAP connections

If you do not need Kerberos support, AD/LDAP connections do not require further configuration.

In order to use AD/LDAP connections with Kerberos support, you will need to update the Ticket endpoint to work with the custom domain. As mentioned in the [Auth0 AD/LDAP connector documentation](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-to-auth0#point-an-ad-ldap-connector-to-a-new-connection), the `config.json` file needs to be modified, with the `PROVISIONING_TICKET` value changed to use your custom domain in the format `https://<YOUR-CUSTOM-DOMAIN>/p/ad/jUG0dN0R`.

Once this change is saved, you need to restart the AD/LDAP Connector service for the change to take effect.

## Learn more

* [Configure Custom Domains with Auth0-Managed Certificates](/docs/customize/custom-domains/auth0-managed-certificates)
* [Configure Custom Domains with Self-Managed Certificates](/docs/customize/custom-domains/self-managed-certificates)
* [Troubleshoot Custom Domains](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-custom-domains)
* [Check API Calls](/docs/troubleshoot/authentication-issues/check-api-calls)
* [Troubleshoot SAML Configurations](/docs/troubleshoot/authentication-issues/troubleshoot-saml-configurations)


# Multiple Custom Domains
Source: https://auth0.com/docs/customize/custom-domains/multiple-custom-domains



<Warning>
  Multiple Custom Domains is currently available in Early Access. To use this feature, you must have an Enterprise plan. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal). To learn more about Auth0's product release cycle, read [Product Release Stages](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

Within Auth0, a <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip> allows you to unify the login experience with your own brand and products. Multiple custom domains EA capability enables you to configure up to 1000 custom domains within a single Auth0 tenant. Please see the prerequisites below, including the applicable limits and conditions at General Availability (GA).

## Prerequisites

Before getting started with MCD, review the requirements below:

* Your tenant is on an Enterprise plan ([Public Cloud or Private Cloud deployments](/docs/deploy-monitor/deployment-options)). For more information, see
  Manage Subscriptions.
* Your Enterprise plan will provide a base entitlement of up to 20 custom domains per tenant in the MCD General Availability (GA) release.
* EA allows up to 1,000 custom domains per tenant for experimentation and validation. Once MCD GA launches, the base entitlement of up to 20 custom domains will apply. Any domains beyond the base entitlement will require an additional add-on SKU.
* You must be able to prove ownership of the configured custom domains.

## Configure Multiple Custom Domains

Auth0 will enable the MCD feature on tenants requested by EA participants. You can then add MCD to a tenant with the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> or in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

<Tabs>
  <Tab title="Auth0 Dashboard">
    To create a custom domain in the Auth0 Dashboard:

    1. Navigate to **Auth0 Dashboard** > **Branding > Custom Domains**.
    2. Select **+Add custom domain**.
    3. In the configuration form, provide the following information:

       * **Domain:** A [fully-qualified domain name](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) that you own. For example: `my.custom-domain.com`.
       * **Certificate type:** Choose [**Auth0-managed certificates**](/docs/customize/custom-domains/auth0-managed-certificates) or [**Self-managed certificates**](/docs/customize/custom-domains/self-managed-certificates).
       * **Metadata (Key/Value):** Add optional metadata like `region`, `client_name`, or `client_id`, to help organize and filter your domains.
    4. Once you have configured the custom domain details, select **Save**.

    Your newly added domain name will show as `pending` until verification is complete.
  </Tab>

  <Tab title="Management API">
    To create a custom domain with the Management API, you need a machine-to-machine (M2M) application that is  authorized to use the  Management API. For more information, review. For more information, review [Management API Access Tokens](/docs/secure/tokens/access-tokens/management-api-access-tokens).

    1. Navigate to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and select **Create Application**.
    2. Enter a descriptive name for your application and choose **Machine to Machine Applications**. Then, select **Create**.
    3. Switch to the **APIs** view and then enable toggle for the `Auth0 Management API`.
    4. Expand the row to configure API’s permissions. For MCD, you must select the following:

       * `read:custom_domains`
       * `create:custom_domains`
       * `update:custom_domains`
       * `delete:custom_domains`
    5. Select **Update**.
    6. Navigate to the **Settings** tab to gather your **Client ID**, **Client Secret**, and **Domain**.
    7. Review [Get Management API Access Tokens](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production) to retrieve and store your access token.

    #### Create a Custom Domain

    You can create a new custom domain by sending a `POST` request to the `/api/v2/custom-domains` endpoint. See the example below to create a new custom domain using the Management API explorer, using the credentials retrieved above:

    <AuthCodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
        --url 'https://{yourDomain}/api/v2/custom-domains' \
        --header 'accept: application/json' \
        --header 'authorization: Bearer {yourMgmtApiAccessToken}' \
        --header 'content-type: application/json' \
        --data '{ 
       "domain": "your.example-custom-domain.com", 
       "type": "auth0_managed_certs", 
       "tls_policy": "recommended", 
       "custom_client_ip_header": "true-client-ip", 
       "domain_metadata": {
          "environment": "development"} 
      }'
      ```

      ```csharp C# theme={null}
      var client = new RestClient("https://{yourDomain}/api/v2/custom-domains");
      var request = new RestRequest(Method.POST);
      request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
      request.AddHeader("content-type", "application/json");
      request.AddHeader("accept", "application/json");
      request.AddParameter("application/json", "{ 
       "domain": "your.example-custom-domain.com", 
       "type": "auth0_managed_certs", 
       "tls_policy": "recommended", 
       "custom_client_ip_header": "true-client-ip", 
       "domain_metadata": {
       "environment": "development"} 
      }", ParameterType.RequestBody);
      IRestResponse response = client.Execute(request);
      ```

      ```go Go theme={null}
      package main

      import (
      	"fmt"
      	"strings"
      	"net/http"
      	"io/ioutil"
      )

      func main() {

      	url := "https://{yourDomain}/api/v2/custom-domains"

      	payload := strings.NewReader("{ 
       "domain": "your.example-custom-domain.com", 
       "type": "auth0_managed_certs", 
       "tls_policy": "recommended", 
       "custom_client_ip_header": "true-client-ip", 
       "domain_metadata": {
          "environment": "development"} 
      }")

      	req, _ := http.NewRequest("POST", url, payload)

      	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")
      	req.Header.Add("content-type", "application/json")
      	req.Header.Add("accept", "application/json")

      	res, _ := http.DefaultClient.Do(req)

      	defer res.Body.Close()
      	body, _ := ioutil.ReadAll(res.Body)

      	fmt.Println(res)
      	fmt.Println(string(body))

      }
      ```

      ```java Java theme={null}
      HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/custom-domains")
        .header("authorization", "Bearer {yourMgmtApiAccessToken}")
        .header("content-type", "application/json")
        .header("accept", "application/json")
        .body("{ 
       "domain": "your.example-custom-domain.com", 
       "type": "auth0_managed_certs", 
       "tls_policy": "recommended", 
       "custom_client_ip_header": "true-client-ip", 
       "domain_metadata": {
          "environment": "development"} 
      }")
        .asString();
      ```

      ```javascript Node.JS theme={null}
      var axios = require("axios").default;

      var options = {
        method: 'POST',
        url: 'https://{yourDomain}/api/v2/custom-domains',
        headers: {
          authorization: 'Bearer {yourMgmtApiAccessToken}',
          'content-type': 'application/json',
          accept: 'application/json'
        },
        data: {
          domain: 'your.example-custom-domain.com',
          type: 'auth0_managed_certs',
          tls_policy: 'recommended',
          custom_client_ip_header: 'true-client-ip',
          domain_metadata: {environment: 'development'}
        }
      };

      axios.request(options).then(function (response) {
        console.log(response.data);
      }).catch(function (error) {
        console.error(error);
      });
      ```

      ```objc Obj-C theme={null}
      #import <Foundation/Foundation.h>

      NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}",
                                 @"content-type": @"application/json",
                                 @"accept": @"application/json" };
      NSDictionary *parameters = @{ @"domain": @"your.example-custom-domain.com",
                                    @"type": @"auth0_managed_certs",
                                    @"tls_policy": @"recommended",
                                    @"custom_client_ip_header": @"true-client-ip",
                                    @"domain_metadata": @{ @"environment": @"development" } };

      NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

      NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/custom-domains"]
                                                             cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                         timeoutInterval:10.0];
      [request setHTTPMethod:@"POST"];
      [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];
      ```

      ```php PHP theme={null}
      $curl = curl_init();

      curl_setopt_array($curl, [
        CURLOPT_URL => "https://{yourDomain}/api/v2/custom-domains",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => "",
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => "POST",
        CURLOPT_POSTFIELDS => "{ 
       "domain": "your.example-custom-domain.com", 
       "type": "auth0_managed_certs", 
       "tls_policy": "recommended", 
       "custom_client_ip_header": "true-client-ip", 
       "domain_metadata": {
          "environment": "development"} 
      }",
        CURLOPT_HTTPHEADER => [
          "accept: application/json",
          "authorization: Bearer {yourMgmtApiAccessToken}",
          "content-type: application/json"
        ],
      ]);

      $response = curl_exec($curl);
      $err = curl_error($curl);

      curl_close($curl);

      if ($err) {
        echo "cURL Error #:" . $err;
      } else {
        echo $response;
      }
      ```

      ```python Python theme={null}
      import http.client

      conn = http.client.HTTPSConnection("")

      payload = "{ 
       "domain": "your.example-custom-domain.com", 
       "type": "auth0_managed_certs", 
       "tls_policy": "recommended", 
       "custom_client_ip_header": "true-client-ip", 
       "domain_metadata": {
          "environment": "development"} 
      }"

      headers = {
          'authorization': "Bearer {yourMgmtApiAccessToken}",
          'content-type': "application/json",
          'accept': "application/json"
          }

      conn.request("POST", "/{yourDomain}/api/v2/custom-domains", payload, headers)

      res = conn.getresponse()
      data = res.read()

      print(data.decode("utf-8"))
      ```

      ```ruby Ruby theme={null}
      require 'uri'
      require 'net/http'
      require 'openssl'

      url = URI("https://{yourDomain}/api/v2/custom-domains")

      http = Net::HTTP.new(url.host, url.port)
      http.use_ssl = true
      http.verify_mode = OpenSSL::SSL::VERIFY_NONE

      request = Net::HTTP::Post.new(url)
      request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'
      request["content-type"] = 'application/json'
      request["accept"] = 'application/json'
      request.body = "{ 
       "domain": "your.example-custom-domain.com", 
       "type": "auth0_managed_certs", 
       "tls_policy": "recommended", 
       "custom_client_ip_header": "true-client-ip", 
       "domain_metadata": {
          "environment": "development"} 
      }"

      response = http.request(request)
      puts response.read_body
      ```

      ```swift Swift theme={null}
      import Foundation

      let headers = [
        "authorization": "Bearer {yourMgmtApiAccessToken}",
        "content-type": "application/json",
        "accept": "application/json"
      ]
      let parameters = [
        "domain": "your.example-custom-domain.com",
        "type": "auth0_managed_certs",
        "tls_policy": "recommended",
        "custom_client_ip_header": "true-client-ip",
        "domain_metadata": ["environment": "development"]
      ] as [String : Any]

      let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

      let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/custom-domains")! as URL,
                                              cachePolicy: .useProtocolCachePolicy,
                                          timeoutInterval: 10.0)
      request.httpMethod = "POST"
      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()
      ```
    </AuthCodeGroup>

    If successful, you should see the following returned with the details of your new custom domain, including it's verification status. The `status` is initially returned as `pending`.

    ```json lines theme={null}
    {
        "custom_domain_id": "cd_abc123def456",
        "domain": "your.example-custom-domain.com",
        "primary": false,
        "status": "pending",
        "type": "auth0_managed_certs",
        "verification": {
            "methods": [
                {
                    "name": "CNAME",
                    "record": "yourtenant.auth0.com",
                    "domain": "your.example-custom-domain.com"
                }
            ]
        },
        "tls_policy": "recommended",
        "domain_metadata": {
            "environment": "development"
        }
    }
    ```
  </Tab>
</Tabs>

## MCD features

MCD offers many key features and functionalities to more effectively manage your Auth0 implementation and improve user experience. You are responsible for owning and registering your desired custom domains with a domain name registrar.

The [Auth0 Management API](https://auth0.com/docs/api/management/v2/custom-domains/get-custom-domains) provides comprehensive support for **Create, Read, Update, Delete, and Verify** operations for these custom domains, offering full programmatic control over their lifecycle.

MCD EA supports the following Auth0 SDKs: [Node.js](https://github.com/auth0/node-auth0) and [Go](https://github.com/auth0/go-auth0).

### Domain verification

The method for verifying domain name ownership depends on your chosen management type:

<table>
  <thead>
    <tr>
      <th><strong>Domain Type</strong></th>
      <th><strong>Verification Method</strong></th>
      <th><strong>Details</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong><a href="/docs/customize/custom-domains/auth0-managed-certificates">Auth0-Managed</a></strong></td>
      <td>CNAME DNS record</td>
      <td>Configure this record to confirm domain ownership and activate your domain.</td>
    </tr>

    <tr>
      <td><strong><a href="/docs/customize/custom-domains/self-managed-certificates">Self-Managed</a></strong></td>
      <td>TXT DNS record</td>
      <td>Specific TXT record details are provided in the Create API response.</td>
    </tr>
  </tbody>
</table>

After your custom domain has been verified by Auth0, you can use it immediately to configure Auth0 features for your users. For more information, read [Configure Features to Use Custom Domains](/docs/customize/custom-domains/configure-features-to-use-custom-domains).

### Metadata for enhanced management

You can provision up to 10 metadata fields per custom domain for easier organization and future customization. In upcoming releases, these metadata fields will enable advanced customization of email templates, <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>, and authentication logic.

### Customize email templates

Leverage your custom domain information to personalize and brand your email templates, ensuring a consistent user experience.  To facilitate this, MCD provides the `custom_domain.domain` variable for use in Liquid Syntax.

For example, you could set the **From Address** of your email template to `support@{{ custom_domain.domain }}` , which would render as `support@my.custom-domain.com`. This variable is available through Liquid Syntax in the **From Address**, **Subject**, and **Message** fields. To learn more, read [Customize Email Templates](/docs/customize/email/email-templates).

#### Customize email handling using the Management API

If you configured Multiple Custom Domains and enabled [Use Custom Domains in Emails](/docs/customize/custom-domains/configure-features-to-use-custom-domains#use-custom-domains-in-emails), the `auth0-custom-domain` HTTP header is available when using the Auth0 Management API. The header is passed as the value for the `domain object` in email templates.

<Callout icon="file-lines">
  The `auth0-custom-domain` HTTP header is required if MCD is configured with at least 1 domain in `ready` state.
  If you are moving from a single custom domain to MCD, you must update your existing Management API email requests to include the `auth0-custom-domain` HTTP header .
</Callout>

The following Management API endpoints accept the `auth0-custom-domain` HTTP header:

* [Send an email address verification email](https://auth0.com/docs/api/management/v2#!/Jobs/post_verification_email)
* [Create an email verification ticket](https://auth0.com/docs/api/management/v2/tickets/post-email-verification)
* [Create invitations to an organization](https://auth0.com/docs/api/management/v2/organizations/post-invitations)
* [Create a user](https://auth0.com/docs/api/management/v2/users/post-users)
* [Create a multi-factor authentication enrollment ticket](https://auth0.com/docs/api/management/v2/guardian/post-ticket)
* [Create a password change ticket](https://auth0.com/docs/api/management/v2/tickets/post-password-change)
* [Update a user](https://auth0.com/docs/api/management/v2/users/patch-users-by-id)

For example: To create a password change ticket using Auth0 SDK for [Node.js](https://github.com/auth0/node-auth0).

```javascript lines theme={null}
const { ManagementClient } = require('auth0');

const auth0 = new ManagementClient({
    domain: '{yourDomain}',
    clientId: '{yourClientId}',
    clientSecret: '{yourClientSecret}',
    scope: 'create:passwords_tickets',
    headers: {
        'auth0-custom-domain': 'my-custom-domain.com'
    }
});

(async () => {
    try {
        const ticket = await auth0.tickets.changePassword({
            user_id: 'auth0|abc123',
            result_url: 'https://example.com/success'
        });
        console.log('Password change ticket created:', ticket.data.ticket);
    } catch (err) {
        console.error('Error creating password change ticket:', err);
    }
})();
```

Sample response: The custom domain is passed in the header used to generate the ticket URL.

```json lines theme={null}
{
    "ticket": "https://my-custom-domain.com/u/reset-verify?ticket=abc123"
}
```

##### Response messages

When you provide the `auth0-custom-domain` HTTP header, the following additional response types are possible:

<table>
  <thead>
    <tr>
      <th><strong>HTTP status code</strong></th>
      <th><strong>Message</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>409</code></td>
      <td>The tenant has multiple verified custom domains.</td>
    </tr>

    <tr>
      <td><code>400</code></td>
      <td>The custom domain does not exist for the tenant.</td>
    </tr>

    <tr>
      <td><code>400</code></td>
      <td>The <code>auth0-custom-domain</code> HTTP header has an invalid format.</td>
    </tr>
  </tbody>
</table>

<Callout icon="file-lines">
  If you enable MCD and use the Auth0 Dashboard to configure Email templates, the **Try** feature will not allow you to test with a custom domain.
</Callout>

### Multiple Custom Domains with Actions

Auth0 [Actions](/docs/customize/actions) allows you to create custom logic handling of your different transactions based on the custom domain.

For example, you could create an Action that directs a user to an associated [Organization](/docs/manage-users/organizations), or enforce a specific [access control policy](/docs/customize/actions/use-cases#api-authorization).

To facilitate this, post-login Actions features the object `event.request.hostname`, which provides the hostname being used for the authentication flow.

#### Use case: Restrict user access to an Organization based on custom domain

Store a domain allowlist and denylist (for example, `allow_domains` and `deny_domains`) in your Organization’s metadata.

Create an Action that:

1. Gets the user’s domain through the `event.request.hostname` property
2. Compares that domain with both lists
3. Allows or denies the user access accordingly

```js lines expandable theme={null}
exports.onExecutePostLogin = async (event, api) => {
    const customDomain = event?.custom_domain?.domain;
    
    console.log(`org ${event?.organization?.name} accessed from domain ${customDomain || event?.request?.hostname}`);

    if (event?.organization?.metadata?.deny_domains && event?.organization?.metadata?.allow_domains) {
        console.warn(`[WARNING] configuration issue. org ${event?.organization?.name} has both deny_domains and allow_domains`);
    }

    // Check either deny (A) allow (B) not both
    // (A) checks org's deny_list
    const isDomainDenied = () =>
        (event?.organization?.metadata?.deny_domains ? event?.organization?.metadata?.deny_domains.split(',').map(d => d.trim()).includes(customDomain) : false);
        
    if (isDomainDenied()) {
        return api.access.deny(`access to org ${event?.organization?.name} not allowed on domain ${customDomain}`);
    }

    // (B) checks org's allow_list
    const isDomainAllowed = () =>
        (event?.organization?.metadata?.allow_domains ? event?.organization?.metadata?.allow_domains.split(',').map(d => d.trim()).includes(customDomain) : false);
        
    if (!isDomainAllowed()) {
        return api.access.deny(`access to org ${event?.organization?.name} not allowed on domain ${customDomain}`);
    }
};
```

<Callout icon="file-lines">
  MCD GA will introduce a new custom domain Action object, which will include custom domain metadata. Your Action code will need to be updated at GA if you use the new object.
</Callout>

### Custom domain attributes

The MCD EA release introduces the following attributes related to custom domain verification and SSL/TLS certificate management. These additions provide granular insights into the provisioning and operational status of custom domains. Please be aware that the attributes and their descriptions outlined in this document are subject to change in future releases.

#### Updated attributes

<table>
  <thead>
    <tr>
      <th><strong>Attribute</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>status</code></td>
      <td>A new enumeration value, <code>failed</code>, has been added to the <code>status</code> attribute. This value indicates that the custom domain verification process has encountered an error and was unsuccessful. This is in addition to the existing supported values <code>pending</code> and <code>ready</code>.</td>
    </tr>
  </tbody>
</table>

#### New attributes

The following attributes are supported for Auth0-managed domains only:

<table>
  <thead>
    <tr>
      <th><strong>Attribute</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>verification.status</code></td>
      <td>Status of the DNS record verification process. Possible values are: <code>verified</code>, <code>pending</code>, and <code>failed</code>.</td>
    </tr>

    <tr>
      <td><code>verification.error\_msg</code></td>
      <td>In the event that <code>verification.status</code> indicates a failure, this string attribute will contain a human-readable error message providing context for the verification failure.</td>
    </tr>

    <tr>
      <td><code>verification.last\_verified\_at</code></td>
      <td>This timestamp attribute records the date and time of the last successful verification of the custom domain. The format of this timestamp will adhere to ISO 8601.</td>
    </tr>

    <tr>
      <td><code>certificate</code></td>
      <td>This object encapsulates information related to the SSL/TLS certificate associated with the custom domain.</td>
    </tr>

    <tr>
      <td><code>certificate.status</code></td>
      <td>This attribute indicates the current provisioning status of the SSL/TLS certificate. Possible values will include states such as <code>provisioning</code>, <code>provisioned</code>, <code>provisioning\_failed</code>, and <code>renewing\_failed</code>.</td>
    </tr>

    <tr>
      <td><code>certificate.error\_msg</code></td>
      <td>If the <code>certificate.status</code> is <code>provisioning\_failed</code> or <code>renewing\_failed</code>, this string attribute will provide a user-friendly error message detailing the reason for the failure.</td>
    </tr>

    <tr>
      <td><code>certificate.certificate\_authority</code></td>
      <td>This string attribute specifies the Certificate Authority that issued the SSL/TLS certificate for the custom domain.</td>
    </tr>

    <tr>
      <td><code>certificate.renews\_before</code></td>
      <td>For Auth0-managed custom domains, this new timestamp attribute indicates the date and time before which the SSL/TLS certificate must be renewed. The format of this timestamp will adhere to ISO 8601.</td>
    </tr>
  </tbody>
</table>

### Limitations

With MCD currently in Early Access (EA), we are aware of limitations to the functionality and existing feature set. Please see below for more information:

* The WebAuthn RPID is currently limited to a single domain configuration and is currently incompatible with customers using multiple custom domains.


# Multiple Custom Domains Best Practices
Source: https://auth0.com/docs/customize/custom-domains/multiple-custom-domains/mcd-best-practices

Best practices for MCD

<Warning>
  Multiple Custom Domains is currently available in Early Access. To use this feature, you must have an Enterprise plan. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal). To learn more about Auth0's product release cycle, read [Product Release Stages](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

Implementing Multiple <Tooltip href="/docs/glossary?term=Custom+Domains">Custom Domains</Tooltip> (MCD) effectively requires thoughtful planning and adherence to best practices. By following these guidelines, you can ensure scalability, maintain robust security, and deliver a consistent brand experience across all your custom domains.

## Verify ownership of domains

Make sure you are ready to verify ownership of your custom domains in a timely manner. Leaving domains unverified for too long can clutter your space and complicate the management process.

## Use metadata to stay organized

You can also make use of the metadata fields available for each custom domain. These fields will enable efficient searching and filtering your custom domains in a future release. In addition, MCD General Availability will release metadata to enable enhanced customization of email templates, presentation of the login UI, and even authentication logic, for example. letting you associate a brand (based on metadata) with a specific Auth0 Organization.

## Implement security features

When your tenant is set up to use Multiple Custom Domains, it is crucial to implement measures that prevent potential misuse or phishing. To safeguard against end-user authentication requests involving a domain from an unrelated organization, consider these strategies:

* Use [Advanced Customization for Universal Login](/docs/customize/login-pages/advanced-customizations) in your flow to implement custom logic that blocks authentication based on the domain. This can involve inspecting request parameters and then redirecting or displaying an error.
* Modify your Auth0-hosted custom page templates to include code that inspects the domain and prevents authentication attempts from unauthorized domains.

## Keep branding consistent

MCD adds another dimension to your branding efforts. Your users expect consistency across all their touchpoints with your branded products and services. MCD supports customizations across various aspects to help you achieve this:

* Login page customizationthrough <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>.
* Invitation, password reset, and other emailsthrough email templates.
* Error page customization.

For comprehensive guidance, please refer to general [B2B](/docs/get-started/architecture-scenarios/business-to-business/branding) and [B2C](/docs/get-started/architecture-scenarios/business-to-consumer/branding) branding guidelines.


# Multiple Custom Domain Use Cases
Source: https://auth0.com/docs/customize/custom-domains/multiple-custom-domains/mcd-use-cases

Use cases for MCD

<Warning>
  Multiple Custom Domains is currently available in Early Access. To use this feature, you must have an Enterprise plan. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal). To learn more about Auth0's product release cycle, read [Product Release Stages](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

Auth0 Multiple <Tooltip href="/docs/glossary?term=Custom+Domains">Custom Domains</Tooltip> (MCD) feature offers powerful flexibility, allowing organizations to manage diverse branding, regional requirements, and partner integrations all from a single Auth0 tenant. This simplifies identity management while providing a seamless, branded experience for your users.

### Single brand, multiple top-level domains (TLDs)

Some businesses, like airlines, require different top-level domain names (for example: `.com`, `.co.uk`, `.com.au`) even with a single user base. This is often driven by jurisdictional regulations or customer preferences. With MCD, you can easily create this setup in Auth0, running a single tenant with a unified user store while offering multiple top-level domains. For example, your primary website might be `exampleco.com`, but you can also operate `exampleco.co.uk` and `exampleco.com.au`.

### Multiple brands, single user base

It is common for businesses to own several brands, each with its own domain, but benefit from a single user store and other unified features of a single Auth0 tenant. In retail, for instance, a company might manage distinct brands offering upscale home furniture (`brand1-home-furniture.com`) and office furniture (`brand2-office-furniture.com`). MCD allows these brands to maintain separate domain names while sharing a centralized user store and Auth0 setup.

### White-labeled B2B SaaS

Many SaaS providers offer their services in a white-labeled model. Imagine job-saas.com, a platform for managing job applications. Client companies can host `job-saas.com` services under a subdomain of their own and customize its look and feel, such as `jobs.client-a.com` and `jobs.client-b.com`. With MCD, `job-saas.com` can maintain its entire Auth0 configuration in a single tenant, yet offer different organizations and custom domains directly to its customers.


# SAML Migration for Custom Domains
Source: https://auth0.com/docs/customize/custom-domains/multiple-custom-domains/saml-migration

Migrate your existing SAML Federation Connection from a legacy Auth0 custom domain to a new one, allowing your tenants to leverage Multiple Custom Domain (MCD) capabilities.

<Warning>
  Multiple Custom Domains is currently available in Early Access. To use this feature, you must have an Enterprise plan. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal). To learn more about Auth0's product release cycle, read [Product Release Stages](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

Migrate your existing SAML Federation Connection from a legacy Auth0 custom domain to a new one, allowing your tenants to leverage Multiple Custom Domain (MCD) capabilities.

External Identity Providers (IdPs) are often hardcoded to your old domain, which requires you to deploy a smart reverse proxy that intercepts the SAML response sent to your old domain and securely point it to a new custom domain.

This ensures a seamless migration for federated users, allowing you to immediately use your new domain without waiting for mandatory configuration updates from your IdP.

## Prerequisites

This process requires configuration via Terraform to set up the Auth0 components and deployment of a Cloudflare Worker for the proxy logic.

Before getting started with your migration, review the requirements below:

* A tenant on an Enterprise plan with MCD enabled.
* Two verified custom domains configured in your Auth0 tenant:
  1. **Old legacy domain** (for the proxy)
  2. **New target domain** (for the application)
* Terraform CLI and `Node.js/npm` installed.
* Cloudflare account with access to the domain hosting your custom domains.

## How it works

This migration strategy uses a smart reverse proxy to bridge the gap between your legacy custom domain and your new domain. This proxy is deployed on the old domain to intercept the SAML authentication response sent by your external Identity Provider (IdP).

This is necessary because the IdP's configuration is hardcoded to your old domain's endpoint. The proxy modifies the SAML payload's control fields (like `Destination` and `Recipient`) to accurately reflect the new custom domain.

Finally, the proxy forwards this corrected payload to the new domain's login endpoint. This enables a zero-downtime cutover to your new domain without requiring manual configuration changes from your IdP partners.

## Setup and configuration

To setup and configure your migration:

1. Clone the migration repository:

```bash theme={null}
git clone https://github.com/abbaspour/auth0-mcd-federation-migration.git
cd auth0-mcd-federation-migration
```

2. Install dependencies:

```bash theme={null}
npm install
```

3. Create a `terraform.auto.tfvars` file in your `tf` firectory with the required credentials and domain information:

```bash theme={null}
# Auth0 Service Provider (SP) variables
auth0_domain = "your-sp-tenant.auth0.com"
auth0_existing_custom_domain = "oldfed.example.com"
auth0_new_custom_domain = "id.example2.com"
auth0_tf_client_id = "your-sp-client-id"
auth0_tf_client_secret = "your-sp-client-secret"

# Auth0 Identity Provider (IDP) variables
auth0_idp_domain = "your-idp-tenant.auth0.com"
auth0_idp_tf_client_id = "your-idp-client-id"
auth0_idp_tf_client_secret = "your-idp-client-secret"

# Cloudflare variables
cloudflare_api_key = "your-cloudflare-api-key"
cloudflare_email = "your-cloudflare-email"
cloudflare_zone_id = "your-cloudflare-zone-id"
```

4. Initialize and apply Terraform:

```bash theme={null}
cd tf
terraform init
terraform apply
```

This creates the necessary SAML application and connection, configures the DNS via Cloudflare, and prepares the environment variables for the worker.

### Deploy the Cloudflare worker

This proxy handles the SAML response interception and redirection logic. To deploy:

1. Deploy the Cloudflare proxy:

```bash theme={null}
cd ..
npx wrangler deploy
```

2. The worker automatically receives the required environment variables (like `AUTH0_EDGE_LOCATION` and `NEW_SP_DOMAIN`) from the Terraform output.

### Temporarily update SAML connection parameters

Your old domain receives the SAML response before being reposted to the new domain. Therefore, the SAML Connection's expected validation parameters must temporarily point to the old domain's callback URL to avoid mismatch errors.

1. Obtain a Management API access token for your service provider tenant, with `read:connections` and `update:connections` scopes:

   ```bash theme={null}
   cd bin/
   export access_token='<sp-tenant-management-api-token>'
   ```

2. Update destination URL:

   ```bash theme={null}
   ./sp-set-destination-url.sh -i <saml-connection-id> -d [https://oldfed.example.com/login/callback](https://oldfed.example.com/login/callback)
   ```

3. Update recipient URL:

   ```bash theme={null}
   ./sp-set-recipient-url.sh -i <saml-connection-id> -r [https://oldfed.example.com/login/callback](https://oldfed.example.com/login/callback)
   ```


# Configure Custom Domains with Self-Managed Certificates
Source: https://auth0.com/docs/customize/custom-domains/self-managed-certificates

Learn how to configure custom domains where you are responsible for TLS (SSL) certificates, the reverse proxy to handle SSL termination, and forwarding requests to Auth0.

<Callout icon="file-lines">
  You must have an Enterprise subscription to manage certificates in your custom domain. To learn more, read [Auth0 Pricing](https://auth0.com/pricing) and [Login](/docs/authenticate/login).
</Callout>

If you choose to manage the certificates for your <Tooltip href="/docs/glossary?term=custom+domains">custom domains</Tooltip> without assistance from Auth0, you need to know how to manage your own proxy and certificates for inbound connections that require multiple DNS records on the domain. You have to purchase or provide the certificates and manage the renewals yourself. You will also need a reverse proxy where the certificate will be installed. Once the domain is verified, we will accept traffic from the proxy.

Choose this option to:

* Have more control of your certificates (such as choosing your own CA or certificate expiration).
* Enable additional monitoring over your API calls to Auth0.

To set up your custom domain using self-managed certificates, you need to provide your domain name to Auth0, verify that you own that domain, and configure the reverse proxy. Once your custom domain has been set up, you will need to configure your Auth0 features to start using your custom domain.

<Callout icon="file-lines">
  Your proxy to Auth0 must use TLS (SSL) version 1.2 or newer.
</Callout>

## Provide your domain name to Auth0

1. Go to [Dashboard > Settings > Custom Domains](https://manage.auth0.com/#/tenant/custom_domains) or [Dashboard > Branding > Custom Domains](https://manage.auth0.com/#/custom_domains). Enter your custom domain in the provided box, and select **Self-managed Certificates** from the drop-down menu.
2. Choose **Add Domain**.
   You can only add one domain per tenant even though the **Add Domain** button still appears after you add a domain.

## Verify ownership

Before you can use the domain with Auth0, you'll need to verify that you own it.

1. Go to [Dashboard > Branding > Custom Domains](https://manage.auth0.com/#/branding/custom_domains).

   <Frame>
     <img alt="Auth0 Branding Custom Domains Self-Managed Certificate Verify Domain" />
   </Frame>
2. Add the TXT verification information to your domain's DNS record.
   These steps may vary for your domain host provider:

   1. Keep the Auth0 custom domain page open in your browser so you can copy values.
   2. Log in to your domain management service.
   3. Create a new record, and save it with these settings:

      <table>
        <thead>
          <tr>
            <th><strong>Parameter</strong></th>
            <th><strong>Value</strong></th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>Record type</td>
            <td>TXT</td>
          </tr>

          <tr>
            <td>Name</td>
            <td>Copy and paste your domain's <strong>TXT Record</strong> value from Auth0.</td>
          </tr>

          <tr>
            <td>Time to Live (TTL)</td>
            <td>Use default value.</td>
          </tr>

          <tr>
            <td>Value</td>
            <td>Copy and paste your domain's <strong>TXT Content</strong> value from Auth0.</td>
          </tr>
        </tbody>
      </table>
3. Click **Verify** to proceed.

   It may take a few minutes before Auth0 can verify your domain, depending on your DNS settings.

   If Auth0 successfully verified your domain name, you'll see a confirmation window.
   Save the information provided in this window, specifically the `cname-api-key` value, since this is the **only** time you'll see this value.

   <Callout icon="file-lines">
     For security purposes, this value is hashed when stored, so it cannot be recovered. If you fail to capture the `cname-api-key` at this time, you will have to recreate the custom domains.
   </Callout>

   The verification process is complete, and within 1 to 2 minutes, your custom domain should be ready to use. If you are unable to complete the verification process within three days, repeat these steps.

## Configure reverse proxy

The reverse proxy server retrieves resources on behalf of your application from one or more servers. These resources are then returned to the application, appearing as if they originated from the proxy server itself.

You can use a service such as [Cloudflare](/docs/customize/custom-domains/self-managed-certificates/configure-cloudflare-for-use-as-reverse-proxy), [Azure CDN](/docs/customize/custom-domains/self-managed-certificates/configure-azure-cdn-for-use-as-reverse-proxy), [Google Cloud Platform](/docs/customize/custom-domains/self-managed-certificates/configure-gcp-as-reverse-proxy), or [AWS Cloudfront](/docs/customize/custom-domains/self-managed-certificates/configure-aws-cloudfront-for-use-as-reverse-proxy) and configure settings for your custom domain. You will add the new CNAME value to your DNS for your custom domain pointing to the reverse proxy server domain name for distribution.

1. After you've created the reverse proxy settings on your service, go to [Auth0 Dashboard > Branding > Custom Domains](https://manage.auth0.com/#/branding/custom_domains) tab.
2. Add a new CNAME record to your DNS for your custom domain pointing to the service domain name for your distribution. You can find this by looking for the **Distribution ID** on your reverse proxy server configuration.
   Once added, the CNAME record must be present at all times to avoid issues during certificate renewal.
3. The way you configure the proxy server will vary depending on the service you use. You will likely need to configure the following types of settings:

* [Distribution](#distribution-settings)
* [Origin custom headers](#origin-custom-header-settings)
* [Origin hostname](#origin-hostname-settings)
* [Default cache behavior](#default-cache-behavior-settings)

### Distribution settings

<table>
  <thead>
    <tr>
      <th><strong>Setting</strong></th>
      <th><strong>Value</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Origin Domain Name</td>
      <td>Set this to the <strong>Origin Domain Name</strong> value obtained from the Auth0 Dashboard during the Custom Domains setup process.</td>
    </tr>

    <tr>
      <td>Origin ID</td>
      <td>A description for the origin. This value lets you distinguish between multiple origins in the same distribution and therefore must be unique.</td>
    </tr>

    <tr>
      <td>Origin Protocol Policy</td>
      <td>Set to <code>HTTPS Only</code>.</td>
    </tr>

    <tr>
      <td>Alternate Domain Names (CNAMEs)</td>
      <td>Set to your custom domain name (the same one your configured in the Auth0 Dashboard).</td>
    </tr>
  </tbody>
</table>

### Origin custom header settings

<table>
  <thead>
    <tr>
      <th><strong>Setting</strong></th>
      <th><strong>Value</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Header Name</td>
      <td>Set to <code>cname-api-key</code>.</td>
    </tr>

    <tr>
      <td>Value</td>
      <td>Set to the CNAME API Key value that you were given immediately after you verified ownership of your domain name with Auth0.</td>
    </tr>
  </tbody>
</table>

### Origin hostname settings

<table>
  <thead>
    <tr>
      <th><strong>Setting</strong></th>
      <th><strong>Value</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Origin hostname</td>
      <td>Enter <code>\{yourTenant}-\<CUSTOM\_DOMAIN\_ID>.edge.tenants.us.auth0.com</code>, making sure to replace <code>\<CUSTOM\_DOMAIN\_ID></code> with the value of the Origin Domain Name (custom domain ID) you received from Auth0 when setting up the new custom domain. If your tenants are not in the US region, use one of the following: <ul><li>EU: <code>\{yourTenant}-\<CUSTOM\_DOMAIN\_ID>.edge.tenants.eu.auth0.com</code></li><li>AU: <code>\{yourTenant}-\<CUSTOM\_DOMAIN\_ID>.edge.tenants.au.auth0.com</code></li><li>JP: <code>\{yourTenant}-\<CUSTOM\_DOMAIN\_ID>.edge.tenants.jp.auth0.com</code></li></ul> For example, if your CUSTOM\_DOMAIN\_ID is:<br /><br /> <code>cd\_TXIdNgQ07HrAFVmz</code> <br /><br />For a US tenant, then the Origin hostname should be:<br /><br /><code>US: -cd-txIdngq07hrafvmz.edge.tenants.us.auth0.com</code></td>
    </tr>

    <tr>
      <td>Host header</td>
      <td>Use the name you provided for the Origin hostname.</td>
    </tr>
  </tbody>
</table>

For more information on retrieving the details of your custom domain, see [Get custom domain configurations](https://auth0.com/docs/api/management/v2/custom-domains/get-custom-domains).

### Default cache behavior settings

<table>
  <thead>
    <tr>
      <th><strong>Setting</strong></th>
      <th><strong>Value</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Viewer Protocol Policy</td>
      <td>Select <strong>Redirect HTTP to HTTPS</strong>.</td>
    </tr>

    <tr>
      <td>Allowed HTTP Methods</td>
      <td>Select <strong>GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE</strong>.</td>
    </tr>

    <tr>
      <td>Cache Based on Selected Request Headers</td>
      <td>Select <strong>Allow list</strong>.</td>
    </tr>

    <tr>
      <td>Allow List Headers</td>
      <td>The following headers should be allowed: <code>User-Agent</code>, <code>Origin</code>, <code>Referer</code>, <code>Authorization</code>, <code>Accept</code>, and <code>Accept-Language</code>.</td>
    </tr>

    <tr>
      <td>Forward Cookies</td>
      <td>Select <strong>All</strong>.</td>
    </tr>

    <tr>
      <td>Query String Forwarding and Caching</td>
      <td>Select <strong>Forward all, cache based on all</strong>.</td>
    </tr>
  </tbody>
</table>

## Additional steps for specific Auth0 features

There are additional configuration steps you must complete depending on which Auth0 features you are using. To learn more, read [Configure Features to Use Custom Domains](/docs/customize/custom-domains/configure-features-to-use-custom-domains).

Cloudflare uses a feature called [CNAME flattening](https://developers.cloudflare.com/dns/cname-flattening/), which affects Auth0 verification and certificate renewal in the way that it handles DNS records. We recommend that you turn off CNAME flattening unless it's absolutely necessary.

Because this feature puts you in control of your own certificates, you need to design mitigation strategies (like a web application firewall) for blocking requests in case of attacks. For more information, read [our blog](https://auth0.com/blog/the-future-of-bot-protection-smarter-attacks-demand-a-layered-approach/) about the future of bot protection.

## Learn more

* [Configure Features to Use Custom Domains](/docs/customize/custom-domains/configure-features-to-use-custom-domains)
* [Configure Google Cloud Platform with Load Balancing as Reverse Proxy](/docs/customize/custom-domains/self-managed-certificates/configure-gcp-as-reverse-proxy)
* [Configure Cloudflare as Reverse Proxy](/docs/customize/custom-domains/self-managed-certificates/configure-cloudflare-for-use-as-reverse-proxy)
* [Configure AWS CloudFront as Reverse Proxy](/docs/customize/custom-domains/self-managed-certificates/configure-aws-cloudfront-for-use-as-reverse-proxy)
* [Configure Azure CDN as Reverse Proxy](/docs/customize/custom-domains/self-managed-certificates/configure-azure-cdn-for-use-as-reverse-proxy)
* [Configure Akamai as Reverse Proxy](/docs/customize/custom-domains/self-managed-certificates/configure-akamai-for-use-as-reverse-proxy)


# Configure Akamai as Reverse Proxy
Source: https://auth0.com/docs/customize/custom-domains/self-managed-certificates/configure-akamai-for-use-as-reverse-proxy

Learn how to set up Akamai for use as the custom domain proxy for Auth0.

<Card title="Availability varies by Auth0 plan">
  Both your specific login implementation and your Auth0 plan or custom agreement affect whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

To set up an Akamai product as a reverse proxy, complete the following:

1. Verify the ownership of your custom domain. To learn more, read [Verify Ownership](/docs/customize/custom-domains/auth0-managed-certificates#verify-ownership).
2. Go to [Dashboard > Settings > Custom Domains](https://manage.auth0.com/#/tenant/custom_domains) to gather the distribution, origin custom header, origin hostname, and default cache behavior settings. Then, use this information to update your Akamai custom domain settings to point to the reverse proxy server domain. To learn more, read [Configure reserve proxy](/docs/customize/custom-domains/self-managed-certificates#configure-reverse-proxy).
3. Update the custom domain client IP header using the Management API PATCH  `/api/v2/custom-domains/{id}` endpoint as below:

   ```json lines theme={null}
   { 
   "custom_client_ip_header": "true-client-ip" 
   }
   ```

   To learn more, read [Update custom domain configuration](https://auth0.com/docs/api/management/v2#!/Custom_Domains/patch_custom_domains_by_id).

For details on how to configure Akamai as a reverse proxy using the information above, refer to Akamai documentation or customer support.

## Learn more

* [Troubleshoot Custom Domains](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-custom-domains)


# Configure AWS CloudFront as Reverse Proxy
Source: https://auth0.com/docs/customize/custom-domains/self-managed-certificates/configure-aws-cloudfront-for-use-as-reverse-proxy

Learn how to configure AWS CloudFront for use as the custom domain proxy for Auth0.

<Card title="Availability varies by Auth0 plan">
  Both your specific login implementation and your Auth0 plan or custom agreement affect whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

You can configure AWS CloudFront for use as the reverse proxy with <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip> names for your Auth0 tenant.

1. Log in to AWS, and navigate to [CloudFront](https://console.aws.amazon.com/cloudfront).
2. Click **Create Distribution**.
3. You can choose the delivery method for your content. Click **Get Started** under the **Web** section.
4. Configure your distribution settings. Here are the values you'll need to change.

   <table>
     <thead>
       <tr>
         <th>Setting</th>
         <th>Value</th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>Origin Domain Name</td>
         <td>Set this to the <strong>Origin Domain Name</strong> value obtained from the Auth0 Dashboard during the Custom Domains setup process</td>
       </tr>

       <tr>
         <td>Origin ID</td>
         <td>A description for the origin. This value lets you distinguish between multiple origins in the same distribution and therefore must be unique.</td>
       </tr>

       <tr>
         <td>Origin Protocol Policy</td>
         <td>Set to <code>HTTPS Only</code></td>
       </tr>

       <tr>
         <td>Alternate Domain Names (CNAMEs)</td>
         <td>Set to your custom domain name (the same one your configured in the Auth0 Dashboard)</td>
       </tr>

       <tr>
         <td>SSL Certificate</td>
         <td>Set to the SSL Certificate for your custom domain stored in AWS Certificate Manager (ACM) in the US East(N. Virginia) Region or in IAM.</td>
       </tr>
     </tbody>
   </table>
5. Provide information on the **Origin Custom Headers** (the **Header Name** and **Value** fields appear only after you've provided an **Origin Domain Name**)

   <table>
     <thead>
       <tr>
         <th>Setting</th>
         <th>Value</th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>Header Name</td>
         <td>Set to <code>cname-api-key</code></td>
       </tr>

       <tr>
         <td>Value</td>
         <td>Set to the CNAME API Key value that you were given immediately after you verified ownership of your domain name with Auth0</td>
       </tr>
     </tbody>
   </table>
6. Configure the **Default Cache Behavior Settings**. Here are the values you'll need to change

   <table>
     <thead>
       <tr>
         <th>Setting</th>
         <th>Value</th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>Viewer Protocol Policy</td>
         <td>Select <strong>Redirect HTTP to HTTPS</strong></td>
       </tr>

       <tr>
         <td>Allowed HTTP Methods</td>
         <td>Select <strong>GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE</strong></td>
       </tr>

       <tr>
         <td>Cache and origin request settings</td>
         <td>Select <strong>Legacy cache settings</strong></td>
       </tr>

       <tr>
         <td>Cache Based on Selected Request Headers</td>
         <td>Select <strong>Include the following headers</strong></td>
       </tr>

       <tr>
         <td>Add Headers</td>
         <td>Enter <code>User-Agent</code> and click <strong>Add Custom >></strong> to add the custom header. Do the same for <code>Authorization</code>, <code>Origin</code>, <code>Referer</code>, <code>Accept-Language</code>, and <code>Accept</code> headers.</td>
       </tr>

       <tr>
         <td>Forward Cookies</td>
         <td>Select <strong>All</strong></td>
       </tr>

       <tr>
         <td>Query Strings</td>
         <td>Select <strong>All</strong></td>
       </tr>
     </tbody>
   </table>
7. Scroll to the bottom of the page and click **Create Distribution**.
   You'll see your newly-created distribution in your CloudFront Distributions list. Note that the Status will reflect `In progress` until the distribution is Deployed.
8. Add a new CNAME record to your DNS for your custom domain pointing to the CloudFront Domain Name for your Distribution. This can be found by clicking on your Distribution ID, under the General tab, Domain Name (for example, `e2zwy42nt1feu7.cloudfront.net`). You can also use an Alias record if Route 53 is configured for your domain.

## Learn more

* [Configure Features to Use Custom Domains](/docs/customize/custom-domains/configure-features-to-use-custom-domains)
* [Troubleshoot Custom Domains](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-custom-domains)
* [TLS (SSL) Versions and Ciphers](/docs/customize/custom-domains/self-managed-certificates/tls-ssl)


# Configure Azure CDN as Reverse Proxy
Source: https://auth0.com/docs/customize/custom-domains/self-managed-certificates/configure-azure-cdn-for-use-as-reverse-proxy

Learn how to set up Azure CDN for use as the custom domain proxy for Auth0.

<Card title="Availability varies by Auth0 plan">
  Your Auth0 plan or custom agreement affects whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

To set up Azure CDN as a reverse proxy, an Azure CDN Premium plan is required.

1. [Configure Custom Domains with Self-Managed Certificates](/docs/customize/custom-domains/self-managed-certificates) if you haven't already. Make note of the **Origin Domain Name** and **cname-api-key** values since you'll need these later.
2. Login to the [Azure Portal](https://portal.azure.com/).
3. [Create a new Azure CDN profile and endpoint](https://learn.microsoft.com/en-us/azure/cdn/cdn-create-new-endpoint). For the CDN endpoint settings, provide the **Origin Domain Name** from Auth0 Dashboard.
4. [Add your custom domain to your Azure CDN endpoint](https://learn.microsoft.com/en-us/azure/cdn/cdn-map-content-to-custom-domain?tabs=azure-dns%2Cazure-portal%2Cazure-portal-cleanup).
5. [Configure HTTPS for your Azure CDN custom domain](https://learn.microsoft.com/en-us/azure/cdn/cdn-custom-ssl?tabs=option-1-default-enable-https-with-a-cdn-managed-certificate). This process requires you to verify ownership of the domain. Once done, it may take up to 6 hours to deploy the certificate to all of the CDN pop locations.
6. Set up the configuration for the custom domain communication with Auth0 using the Azure CDN Rules engine. (To learn more, see [Override HTTP behavior using the Azure CDN from Verizon Premium rules engine](https://learn.microsoft.com/en-us/previous-versions/azure/cdn/cdn-verizon-premium-rules-engine) in Microsoft documentation.) [Create a new Azure CDN Rule](https://learn.microsoft.com/en-us/previous-versions/azure/cdn/cdn-verizon-premium-rules-engine#tutorial) with the following settings:

   <table>
     <thead>
       <tr>
         <th>Setting</th>
         <th>Value</th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>Name/Description</td>
         <td>Auth0 Custom Domain</td>
       </tr>

       <tr>
         <td>Type of requests</td>
         <td>Select the <strong>Edge CName</strong> option, then select your custom domain name from the list.</td>
       </tr>
     </tbody>
   </table>
7. Add the following **Features** to your Azure CDN Rule:
   We recommend creating another Azure CDN Rule to deny the usage of the **azureedge.net** CNAME.

   <table>
     <thead>
       <tr>
         <th>Setting</th>
         <th>Value</th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>Bypass Cache</td>
         <td><strong>Enabled</strong></td>
       </tr>

       <tr>
         <td>Modify Client Request Header</td>
         <td>Select <strong>Override</strong>, enter <strong>cname-api-key</strong> for the name, and enter the CNAME API Key provided by Auth0 as the value.</td>
       </tr>
     </tbody>
   </table>
8. Once the Azure CDN Rule is approved, the status will change from Pending XML to Active XML. At this point, Azure CDN will be publishing the rules and certificates. When Azure finishes processing all changes, you can use your custom domain.

## Learn more

* [Configure Features to Use Custom Domains](/docs/customize/custom-domains/configure-features-to-use-custom-domains)
* [Troubleshoot Custom Domains](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-custom-domains)
* [TLS (SSL) Versions and Ciphers](/docs/customize/custom-domains/self-managed-certificates/tls-ssl)


# Configure Cloudflare as Reverse Proxy
Source: https://auth0.com/docs/customize/custom-domains/self-managed-certificates/configure-cloudflare-for-use-as-reverse-proxy

Learn how to set up Cloudflare for use as the custom domain proxy for Auth0.

<Card title="Availability varies by Auth0 plan">
  Your Auth0 plan or custom agreement affects the availability of this feature. To learn more, read [Auth0's Pricing Page](https://auth0.com/pricing).
</Card>

To set up Cloudflare as a reverse proxy using the recommended approach, a Cloudflare Enterprise Plan with the following features is required:

| Feature               | Description                                                                                                                                                                                                                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Host Header Override  | Rewrite Host headers using different Cloudflare rules. To learn more, read [Rewrite Host headers on Cloudflare Docs](https://developers.cloudflare.com/rules/origin-rules/tutorials/change-uri-path-and-host-header/).                                                                            |
| True-Client-IP Header | Enabling the True-Client-IP Header adds the True-Client-IP header to all requests to your origin server, which includes the end user’s IP address. To learn more, read [Understanding the True-Client-IP Header on Cloudflare](https://developers.cloudflare.com/network/true-client-ip-header/). |

## Configure Cloudflare

<Warning>
  As a prerequisite, the parent domain for your chosen custom domain must be [added and activated within the Cloudflare dashboard](https://developers.cloudflare.com/learning-paths/get-started/add-domain-to-cf/minimize-downtime/#activate-your-domain). Also, confirm that your desired custom domain does not already exist within your Cloudflare zone. If it already exists, Cloudflare verification will fail.
</Warning>

To configure Cloudflare as a reverse proxy, you’ll need to create a CNAME record, a Page Rule, and a Transform Rule in Cloudflare.

1. [Configure and verify a Custom Domain with Self-Managed Certificates](/docs/customize/custom-domains/self-managed-certificates) if you haven't already. Make note of the **Origin Domain Name** and **cname-api-key** values since you'll need these later.
2. In the Cloudflare dashboard for the target zone, [create a CNAME record](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/#create-dns-records) with the following settings:

   <table>
     <thead>
       <tr>
         <th><strong>Setting</strong></th>
         <th><strong>Value</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>Name</td>
         <td>The custom domain name.</td>
       </tr>

       <tr>
         <td>Target</td>
         <td>The <strong>Origin Domain Name</strong> value recorded earlier.</td>
       </tr>

       <tr>
         <td>Proxy Status</td>
         <td><code>Proxied</code></td>
       </tr>
     </tbody>
   </table>
3. [Create a Page Rule](https://developers.cloudflare.com/rules/page-rules/) scoped to all URLs under the chosen custom domain and with the following settings:

   <table>
     <thead>
       <tr>
         <th><strong>Setting</strong></th>
         <th><strong>Value</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>Host Header Override</td>
         <td>The <strong>Origin Domain Name</strong> value recorded earlier.</td>
       </tr>

       <tr>
         <td>True-Client-IP</td>
         <td><code>Enable</code></td>
       </tr>
     </tbody>
   </table>
4. [Create a Transform Rule](https://developers.cloudflare.com/rules/transform/request-header-modification/create-dashboard/):

   1. Switch to the **Modify Request Header** view.
   2. Select **Create Rule** and provide a name of your choice.
   3. Under **When incoming requests match**, select **Custom filter expression** and set an expression that scopes the Rule to requests associated with the chosen custom domain. For example, use an exact match on the **Hostname** field.
   4. Under Modify request header, select **Set static**, and then set the following fields:

      <table>
        <thead>
          <tr>
            <th><strong>Field</strong></th>
            <th><strong>Value</strong></th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>Header name</td>
            <td><code>cname-api-key</code></td>
          </tr>

          <tr>
            <td>Value</td>
            <td>The <strong>cname-api-key</strong> value recorded earlier.</td>
          </tr>
        </tbody>
      </table>
5. Ensure that [Always Use HTTPS](https://developers.cloudflare.com/ssl/edge-certificates/additional-options/always-use-https/) is enabled and [encryption mode](https://developers.cloudflare.com/ssl/origin-configuration/ssl-modes/) is set, at least, to **Full** for your chosen custom domain.

<Callout icon="file-lines">
  While it is possible to use Cloudflare Workers instead of Page and Transform rules to set up a reverse proxy that meets the requirements for a self-managed certificate custom domain, we recommend using the rules-based approach because it eliminates the need for custom code.
</Callout>

## Configure Auth0

Call the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> [Update custom domain configuration](https://auth0.com/docs/api/management/v2#!/Custom_Domains/patch_custom_domains_by_id) endpoint with the following payload in the body:

```json lines theme={null}
{
  "custom_client_ip_header": "true-client-ip"
}
```

## Learn more

* [Configure Features to Use Custom Domains](/docs/customize/custom-domains/configure-features-to-use-custom-domains)
* [Troubleshoot Custom Domains](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-custom-domains)
* [TLS (SSL) Versions and Ciphers](/docs/customize/custom-domains/self-managed-certificates/tls-ssl)


# Configure Google Cloud Platform with Load Balancing as Reverse Proxy
Source: https://auth0.com/docs/customize/custom-domains/self-managed-certificates/configure-gcp-as-reverse-proxy

Learn how to set up Google Cloud Platform (GCP) with load balancing for use as the custom domain proxy for Auth0.

<Callout icon="file-lines">
  Auth0 custom domains are available with any paid [subscription plan](https://manage.auth0.com/#/tenant/billing/subscription). If you want to manage the SSL/TLS certificates yourself, you will need an **Enterprise** subscription. For more information, see [Auth0 pricing plans](https://auth0.com/pricing).
</Callout>

You can set up Google Cloud Platform (GCP) with load balancing as a reverse proxy. The following diagram describes components in the configuration.

* **Google Cloud Platform Load Balancer** distributes traffic across multiple instances of applications.
* **Internet Network Endpoint Group** is a backend that resides outside of Google Cloud. See [Internet Network endpoint group](https://cloud.google.com/load-balancing/docs/negs/internet-neg-concepts) for details.

<Frame>
  <img alt="Google Cloud Platform with Load Balancing as Reverse Proxy flow diagram" />
</Frame>

1. [Configure Custom Domains with Self-Managed Certificates](/docs/customize/custom-domains/self-managed-certificates) if you haven't already. Make note of the **Origin Domain Name** and `cname-api-key` values for use later.
2. Verify ownership of the domain by adding a TXT record in your DNS server in the [Auth0 Dashboard > Tenant Settings > Custom Domains](https://manage.auth0.com/#/tenant/custom_domains) and click **Verify**.
3. Once GCP has verified your domain, log in to the [GCP console](https://console.cloud.google.com).
4. Go to **Network Services > Load Balancing**. Click **Create Load Balancer**. To learn more, read [Google Cloud Platform Load Balancing](https://cloud.google.com/load-balancing/docs) in Google Cloud documentation.

   1. Select **HTTP(S) Load Balancing**.
   2. Select **From Internet to my VMs** because we need to route the traffic from Internet to Auth0. Click **Continue**.
   3. Provide a name for the load balancer such as `auth0-reverse-proxy` and click **Create**.
5. Configure the backend.

   1. Create an internet network endpoint group (NEG) which is a backend that resides outside of Google Cloud. To learn more, see [Internet network endpoint groups overview](https://cloud.google.com/load-balancing/docs/negs/internet-neg-concepts) in Google Cloud documentation.
   2. Select the newly created Internet NEG as a backend in the backend service configuration and set the `cname-api-key` and `host` value (origin domain name) from your Auth0 tenant.
   3. Click **Done**.
6. Set up the `host` and `path` rules.

   1. Choose **Action** as **Route traffic to a single backend**.
   2. In **Host rewrite**, enter your origin domain name from your Auth0 tenant that you saved earlier.
   3. Click **Create**.
7. Configure the frontend.

   1. Create a certificate. The easiest method is to choose **Google-managed certificate** because Google automatically provisions the SSL certificate for you.
   2. If you do not choose a Google-managed certificate, then it is your responsibility to renew and upload the SSL certificate with your certificate authority before it expires.
8. Review and finalize the configuration.
   It will take a minute for GCP to configure the load balancer. Typical issues that might cause an error include:

   * **Invalid API key**: The `cname-api-key` was not set to Auth0 from GCP.
   * **403 Forbidden**: The `host` header was not sent to Auth0 from GCP.
9. Update your DNS records to [connect your domain to your load balancer](https://cloud.google.com/load-balancing/docs/https/setup-global-ext-https-external-backend#update_dns).

## Learn more

* [Configure Features to Use Custom Domains](/docs/customize/custom-domains/configure-features-to-use-custom-domains)
* [Troubleshoot Custom Domains](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-custom-domains)
* [TLS (SSL) Versions and Ciphers](/docs/customize/custom-domains/self-managed-certificates/tls-ssl)


# TLS (SSL) Versions and Ciphers
Source: https://auth0.com/docs/customize/custom-domains/self-managed-certificates/tls-ssl

Check supported TLS versions and ciphers if you are using a reverse proxy configured for use with self-managed certificates

<Card title="Before you start">
  Auth0's network edge requires a Server Name Indication (SNI) to be set on all requests. Most clients set SNI by default; if your web client does not, consult your web client documentation to determine how to manually set an SNI.
</Card>

Auth0’s network edge has a secure set of allowed SSL/TLS version/cipher suite combinations. When connecting to Auth0 services using a reverse proxy with self-managed certificates, you **must** use a supported TLS version and cipher suite. During the TLS handshake, communication between the server and client specifies the TLS version and cipher suite. If you are not using a supported version, a failure could occur.

## Supported Versions

<Callout icon="file-lines">
  If you are using self-managed certificates in your custom domain, they must be compatible with one of the below TLS versions and ciphers. For security purposes, a protocol or cipher could be removed from support without notice.
</Callout>

Auth0 requires using TLS version 1.2 or 1.3 with the supported ciphers.

#### TLS 1.3 Supported Ciphers

TLS\_AES\_128\_GCM\_SHA256
TLS\_AES\_256\_GCM\_SHA384
TLS\_CHACHA20\_POLY1305\_SHA256

#### TLS 1.2 Supported Ciphers

TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_GCM\_SHA256
TLS\_ECDHE\_ECDSA\_WITH\_AES\_256\_GCM\_SHA384
TLS\_ECDHE\_ECDSA\_WITH\_CHACHA20\_POLY1305\_SHA256
TLS\_ECDHE\_RSA\_WITH\_AES\_128\_GCM\_SHA256
TLS\_ECDHE\_RSA\_WITH\_AES\_256\_GCM\_SHA384
TLS\_ECDHE\_RSA\_WITH\_CHACHA20\_POLY1305\_SHA256

#### TLS RFCs

[TLS 1.2](https://tools.ietf.org/html/rfc5246)

[TLS 1.3](https://tools.ietf.org/html/rfc8446)

#### TLS Parameters

To learn more, read [Transport Layer Security (TLS) Parameters](https://www.iana.org/assignments/tls-parameters) for the Internet Assigned Numbers Authority (IANA) list of registered parameters including ciphers.

## Deprecated versions

<Warning>
  Although they remain available in some environments, the following TLS 1.2 cipher suites are deprecated and will reach end-of-support in June 2026. To learn more, read [Weak TLS 1.2 Cipher Suites](/docs/troubleshoot/product-lifecycle/deprecations-and-migrations#weak-tls-1-2-cipher-suites).
</Warning>

TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_CBC\_SHA
TLS\_ECDHE\_ECDSA\_WITH\_AES\_256\_CBC\_SHA
TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_CBC\_SHA256
TLS\_ECDHE\_ECDSA\_WITH\_AES\_256\_CBC\_SHA384
TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA
TLS\_ECDHE\_RSA\_WITH\_AES\_256\_CBC\_SHA
TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA256
TLS\_ECDHE\_RSA\_WITH\_AES\_256\_CBC\_SHA384
TLS\_RSA\_WITH\_AES\_128\_GCM\_SHA256
TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA
TLS\_RSA\_WITH\_AES\_256\_GCM\_SHA384
TLS\_RSA\_WITH\_AES\_256\_CBC\_SHA
TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA256
TLS\_RSA\_WITH\_AES\_256\_CBC\_SHA256

## Learn more

* [Configure Cloudflare as Reverse Proxy](/docs/customize/custom-domains/self-managed-certificates/configure-cloudflare-for-use-as-reverse-proxy)
* [Troubleshoot Custom Domains](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-custom-domains)


# Customize Multi-factor Authentication SMS and Voice Messages
Source: https://auth0.com/docs/customize/customize-sms-or-voice-messages

Learn how to customize SMS and voice messages sent by Auth0 during enrollment and verification.

You can customize SMS and voice messages sent by Auth0 during enrollment (when associating a device to Guardian) and verification (when an authentication message is sent to the device):

1. Go to [Dashboard > Security > Multi-factor Auth](https://manage.auth0.com/#/security/mfa), and click **Phone Message**.
2. Customize your message templates, and click **Save**.

You can customize templates for two message types:

* **Enrollment**: Message sent by Auth0 during device enrollment.
* **Verification**: Message sent by Auth0 to verify the possession of the device.

## Syntax

[Liquid](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers) syntax is the supported templating engine you use when accessing user attributes in SMS templates. The following attributes are available:

<table>
  <thead>
    <tr>
      <th>Attribute</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>message\_type</code></td>
      <td>Indicates which kind of message is sent; <code>sms</code> or <code>voice</code>.</td>
    </tr>

    <tr>
      <td><code>code</code></td>
      <td>Enrollment/verification code. When sending voice messages. Variable values are separated by dots between the digits (<code>1.2.3.4.5</code>) so it can be pronounced accurately by voice messaging providers.</td>
    </tr>

    <tr>
      <td><code>locale</code></td>
      <td>For Universal Login or MFA API. Designates the language.</td>
    </tr>

    <tr>
      <td><code>requestInfo.lang</code></td>
      <td>For Classic Login localization. Browser accept-language header. For example: <code>es-AR,es;q=8.0</code>, <code>en-US,en</code>.</td>
    </tr>

    <tr>
      <td><code>tenant.friendlyName</code></td>
      <td>The <strong>Friendly Name</strong> set in <strong>Dashboard > Tenant Settings</strong>.</td>
    </tr>
  </tbody>
</table>

## Example

```liquid lines theme={null}
{% if message_type == "voice" %}
  {% if locale contains "fr" %}
  Bonjour, vous avez demandé à recevoir un code de vérification pour vous enregister avec {{tenant.friendly_name}}. Votre code est: {{pause}} {{code}}. Je répète, votre code est: {{pause}}{{code}}.
  {% elsif locale contains "es" %}
  Usted ha requerido un código de verificación para inscribirse con {{tenant.friendly_name}}. Su código es: {{pause}}{{code}}. Repito, su código es: {{pause}}{{code}}.
  {% else %}
  Hello, you requested a verification code to enroll with {{tenant.friendly_name}}. Your code is: {{pause}}{{code}}. I repeat, your code is: {{pause}}{{code}}.
  {% endif %}
{% else %}
  {% if locale contains "fr" %}
  {{code}} est votre code de vérification pour vous enregistrer avec {{tenant.friendly_name}}.
  {% elsif locale contains "es" %}
  {{code}} es su código para inscribirse con {{tenant.friendly_name}}.
  {% else %}
  {{code}} is your verification code to enroll with {{tenant.friendly_name}}.
  {% endif %}
{% endif %}
```

## Localization

The endpoints support the `x-request-language` header and you can use it to send the locale. See [Multi-Language Support](/docs/authenticate/passwordless/authentication-methods/sms-otp#multi-language-support) for details.

This is also supported in the <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> API (`POST /mfa/associate` and `POST /mfa/challenge` endpoints). When it's sent, that locale will be available in the `locale` variable in the MFA SMS/voice template.

You must also select those languages in **Tenant > Settings** (under **Supported Languages**) for this to work.

## Learn more

* [Multi-Factor Authentication (MFA)](/docs/secure/multi-factor-authentication)
* [Configure SMS and Voice Notifications for MFA](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-sms-voice-notifications-mfa)
* [Enroll and Challenge SMS and Voice Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-challenge-sms-voice-authenticators)


# Customize Emails
Source: https://auth0.com/docs/customize/email

Manage and customize emails sent by Auth0, including account verification, welcome messages, and breached password detection.

Auth0 offers several email-based workflows, like [user account verification](/docs/manage-users/user-accounts/verify-emails) and [breached password detection](/docs/secure/attack-protection/breached-password-detection).

To use these workflows, start by configuring an [external SMTP email provider](/docs/customize/email/smtp-email-providers) using credentials from a supported provider (like your Mandrill API key or Amazon SES access keys) or SMTP server details.

To manage and customize emails further, you can:

* **Modify the appearance and content** of emails using [email templates](/docs/customize/email/email-templates) and Liquid, an open-source template language.

* **Fully control the email delivery process** by writing an <Tooltip href="/docs/glossary?term=Actions">Action</Tooltip> that sends requests to your email provider's API and implements custom logic for your use case.

* **Trigger emails or create tickets outside the default workflows** using the Management API.

During development, you can use our [built-in email provider](/docs/customize/email/smtp-email-providers#use-the-built-in-smtp-email-provider-for-development) to check email delivery and preview how emails appear during testing.

## Overview

| Read...                                                                                                                       | To learn...                                                                                                                                                                                                                                                      |
| ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [SMTP Email Providers](/docs/customize/email/smtp-email-providers)                                                            | <ul><li>How to configure an email provider with a supported integration or SMTP server details</li><li>How to write a custom email provider Action</li><li>The limits of the built-in email provider</li><li>How to troubleshoot email delivery issues</li></ul> |
| [Email Templates](/docs/customize/email/email-templates)                                                                      | <ul><li>How to customize emails sent as part of Auth0 workflows</li> <li>About the Liquid syntax and template-specific variables supported in email templates</li></ul>                                                                                          |
| [Customize Email and Ticket Handling with the Management API](/docs/customize/email/manage-email-flow)                        | <ul><li>How to send workflow-based emails on demand</li><li>How to generate URLs used in email workflows on demand</li></ul>                                                                                                                                     |
| [Implement User Invitations using Password Reset Emails](/docs/customize/email/send-email-invitations-for-application-signup) | <ul><li>How to implement invitations for new user accounts on your Auth0 application using Auth0's password reset workflow</li></ul>                                                                                                                             |


# Email Templates
Source: https://auth0.com/docs/customize/email/email-templates

Enable and customize emails sent by Auth0 workflows using email templates.

Emails sent as part of Auth0 workflows each have a corresponding email template which determines the email's from address, subject, message body, and more.

After you [configure an external SMTP email provider](/docs/customize/email/smtp-email-providers), you can modify email templates to customize your emails.

Content fields in email templates support [Liquid](https://liquidjs.com/index.html), an open-source templating language that extends the functionality of HTML. Liquid lets you:

* Dynamically populate variables with data, like replacing `{{ user.name }}` with the user's name
* Implement logic, like `if`/`else` statements
* Modify data with filters for string and array manipulation, math operators, and more

You can enable, disable, and customize email templates on the [email templates page of the dashboard](https://manage.auth0.com/#/templates).

## Overview

| Read...                                                                                      | To learn...                                                                     |
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| [Customize email templates](/docs/customize/email/email-templates/customize-email-templates) | How to customize email templates                                                |
| [Supported Liquid syntax](/docs/customize/email/email-templates/supported-liquid-syntax)     | About Liquid syntax (tags, filters, and variables) supported in email templates |

## Available email templates

The following is a summary of available email templates:

| Email template name         | Sent when...                                                                                                                                                                                                                   | Contains...                                                       |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
| Blocked account email       | Access to an account from a specific IP address is blocked by [brute-force protection](/docs/secure/attach-protection/brute-force-protection).                                                                                 | A link to re-enable the origin of the request.                    |
| Change password code email  | A user requests a password change                                                                                                                                                                                              | A link to the password reset page and a code to use on that page. |
| Change password link email  | A user requests a password change                                                                                                                                                                                              | A link to the password reset page.                                |
| MFA enrollment email        | An admin sends an [Auth0 Guardian](/docs/secure/multi-factor-authentication/auth0-guardian) MFA enrollment invitation.                                                                                                         | A link that shows the MFA enrollment experience.                  |
| MFA verification code email | A user using a MFA email verifier needs a MFA verification code                                                                                                                                                                | An MFA verification code                                          |
| Password breach alert email | Auth0 detects that the user is trying to access the application with a password that has been leaked by a third party                                                                                                          | Informational content                                             |
| Passwordless OTP email      | A user logs in with <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> email authentication                                                                                                               |                                                                   |
| User invitation email       | A user is invited to an organization or application                                                                                                                                                                            | A link to join the organization                                   |
| Verification code email     | You have enabled code-based verification and a user signs up or logs in for the first time, or you have enabled the Adaptive MFA policy and there is a low-confidence transaction for which account ownership must be verified | A code that the user needs to enter during authentication         |
| Verification link email     | A user signs up or logs in for the first time                                                                                                                                                                                  | A link to verify the user's email                                 |
| Welcome email               | The user verifies their email address (if this template is enabled), or when the user signs up or logs in for the first time (if disabled)                                                                                     | Informational content                                             |

## Email template limits

* Email template customization is not available when using the built-in email provider. To use email templates, [configure an external SMTP email provider](/docs/customize/email/smtp-email-providers).

* Each type of email has exactly one template. You can use Liquid to implement conditionals and other logic for use cases like multilingual emails.

* Email templates do not support plain text emails. All emails must be HTML.

* In the MFA enrollment email template, the `connection.name` variable is not available.

* In the Passwordless OTP email template, only the `email` property of the `user` object is available.

* Unlike other email templates, the Passwordless OTP email template is configured on the [Passwordless Connections email settings page](https://manage.auth0.com/#/connections/passwordless) rather than the Email Templates page.

* For security purposes, the **From Address** in email templates may not contain `@auth0.com`. If you enter an `@auth0.com` email address in From Addresses, your tenant sends only default emails, ignoring any customization. Private Cloud users may configure a similar domain DenyList.


# Customize Email Templates
Source: https://auth0.com/docs/customize/email/email-templates/customize-email-templates

Instructions on how to use email templates to customize the appearance and content of emails sent by Auth0's email-based workflows.

<Warning>
  To customize email templates, you must [configure an external SMTP email provider](/docs/customize/email/smtp-email-providers). Email templates are not available when using Auth0's built-in email provider.
</Warning>

## Customize email templates

To customize an email template:

1. Go to [Dashboard > Branding > Email Templates](https://manage.auth0.com/#/templates).

2. From the **Template** dropdown, select the email template you want to update.

3. On the email template page, update the fields you want to customize.

   The **From address**, **Subject**, **Redirect To**, and **Message** fields support Liquid. To learn more, read [Supported Liquid Syntax](/docs/customize/email/email-templates/supported-liquid-syntax).

4. Click **Save** to save your changes, **Try** to test your changes, or **Reset** to revert your changes.

### From Address

The **From Address** field sets the email address users see as the sender when receiving an email from Auth0. If unset, emails use the email address in the **From** field configured for your email provider.

When setting the **From Address** field, to allow Auth0 to send digitally-signed emails on your behalf, you must configure two forms of email authentication:

* [Sender Policy Framework (SPF)](https://en.wikipedia.org/wiki/Sender_Policy_Framework), which authorizes specific IP addresses to send email from a domain

* [DomainKeys Identified Mail (DKIM)](https://en.wikipedia.org/wiki/DKIM), which cryptographically signs emails so mail servers can verify that it was sent from the reported domain

Without SPF and DKIM configured, the emails may not be delivered, may be caught by spam filters, or may display "On Behalf Of" and expose the sender (your email provider) in addition to the from address.

To configure SPF and DKIM, you need to create TXT records for your domain. The values for the TXT records and other process details vary, so follow your email provider's instructions for this configuration.

In general, the TXT record for SPF should have the host name set to `@` or empty, and the value to `v=spf1 include:<YOUR_PROVIDER_SPF_DOMAIN> -all`. The TXT record for DKIM should have the host name set to the domain you use to send emails and the value set to the DKIM signature you generate with your provider.

### Subject

The **Subject** field sets the subject line of the email. If unset, Auth0 automatically populates the subject depending on the type of email.

### Message

The **Message** field sets the HTML content of the message body. Each template comes with a default message body which you can modify or discard entirely to write your own.

### URL Lifetime and Redirect to

Email templates that include a link (**Verification Email (Link)**, **Change Password (Link)**, and **Blocked Account Email**) have two additional fields to manage these links:

* The **URL lifetime** field sets how long a link remains valid before it expires. By default, the lifetime is 432,000 seconds (five days).

* The **Redirect To** field sets a URL where a user is redirected after completing the action at an included link.

<Callout icon="file-lines">
  Universal Login currently ignores the value of the **Redirect To** field in the **Password Reset** template and instead redirects to the [default login route](/docs/authenticate/login/auth0-universal-login/configure-default-login-routes) or an [error page](/docs/authenticate/login/auth0-universal-login/error-pages).

  To customize the password reset **Redirect To** URL when using Universal Login, use [`api.transaction.setResultURL()` from the `post-challenge` Actions trigger](/docs/customize/actions/explore-triggers/password-reset-triggers/post-challenge-trigger/post-challenge-api-object#api-transaction-setresulturl-url,-options)
</Callout>

Two query parameters are appended to the **Redirect To** URL:

* `success` set to `true` or `false` indicating whether the action was successful
* `message` set to an additional description of the outcome, like "Access expired." or "Your email was verified. You can continue using the application."

If you have issues with the placement of query parameters in **Redirect To** URLs for single-page applications (SPAs), the following workaround may help.

<Accordion title="Workaround for Redirect To URL query parameters in SPFs">
  [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) defines the expected order of a URL as `scheme|authority|path|query|fragment`. However, SPA frameworks (like Angular) typically expect URLs in the `scheme|authority|path|fragment|query` format, which has the query after the fragment.

  This can cause an issue with the placement of query parameters in **Redirect To** URLs. If your SPA's **Redirect To** URL is `http://localhost:3000/#/register`, the user is redirected to `http://localhost:3000/?exampleParameter=exampleValue#/register` instead of to `http://localhost:3000/#/register?exampleParameter=exampleValue`.

  To work around this limitation of SPA frameworks, you can:

  1. Add a server-side URL as the **Redirect To** URL with a `route` parameter that records the SPA route for the redirect.

     For example, `http://localhost:3000/register?route=register`.

  2. Create a server-side route controller that reads the `route` and other parameters from the URL, redirects to the SPA route specified in `route` parameter, and appends the other parameters received from Auth0.

     For example:

     ```javascript lines wrap theme={null}
     var express = require('express');
     var router = express.Router();
     // To read query strings params and stringify them:
     var qs = require('qs');

     router.get('/register', function(req, res, next) {
         // Retrieve the route param that contains the SPA client side
         // route that the user needs to be redirected to.
         var route = req.query.route;

         // Remove route from the query parameters.
         delete req.query.route;

         // Send a 302 redirect for the expected route.
         res.redirect('http://localhost:3000/#/' + route + '?' +  qs.stringify(req.query));
     });

     module.exports = router;
     ```
</Accordion>

## Test updated templates

To test, click **Try**, enter a valid email address that you have access to view, and choose the correct connection type. Auth0 sends the email for a default app that shares your tenant name (not your tenant's friendly name).

To test templates for different applications, create a sample user to go through the relevant flows.

You can trigger verification emails manually for specific applications and users using the Management API [Send an email address verification email](https://auth0.com/docs/api/management/v2#!/Jobs/post_verification_email) endpoint.

## Example customization use cases

Customizing email templates enables many use cases. For example:

<AccordionGroup>
  <Accordion title="Dynamic Redirect To URL">
    You can set up different **Redirect To** URLs based on your application name. For example:

    ```liquid theme={null}
    {% if application.name == 'JWT.io' %}
        https://jwt.io
    {% else %}
        https://auth0.com
    {% endif %}
    ```

    Because the application name is encoded for security, use an encoded value (especially if your application name contains a character that changes once encoded). For example, use `My%20App` instead of `My App`.
  </Accordion>

  <Accordion title="Multilingual Subject and Message">
    Using Liquid, you can use the `request_language` parameter to pull the language setting from the header value or default to the user's browser language setting.

    For example:

    ```liquid lines theme={null}
    {% assign language = request_language %}
      {% if language %}
        {% assign language = request_language | slice: 0,2 %}
      {% endif %}
    {% if language == 'es' %}
      Cuenta de Example: bloqueada
    {% elsif language == 'de' %}
      Ihr Example wurde gesperrt
    {% elsif language == 'fr' %}
      Compte Example bloqué
    {% elsif language == 'ja' %}
      Example アカウントがブロックされました
    {% elsif language == 'pt' %}
      Conta da Example bloqueada
    {% elsif language == 'zh' %}
      Example　帐户被阻止
    {% else %}
      Example account blocked
    {% endif %}
    ```

    You can also use the `user_metadata.lang` property to alter the content based on the user's preferred language. For example, you can [use an Action](/docs/customize/actions/actions-overview) to set the `user_metadata.lang` property, then read the `user_metadata.lang` parameter in your email templates to send emails in the appropriate language.
  </Accordion>
</AccordionGroup>

For more granular control, you can send emails outside of their standard workflows and create tickets (generated URLs for email workflow actions, like password resets) using the Management API. The Management API's email and ticket endpoints have additional parameters that let you customize their behavior.

To learn more, read [Customize Email and Ticket Handling with the Management API](/docs/customize/email/manage-email-flow).


# Supported Liquid Syntax
Source: https://auth0.com/docs/customize/email/email-templates/supported-liquid-syntax

A list of Liquid tags, filters, and common variables supported in email templates.

For an overview of Liquid syntax, read the [LiquidJS introduction](https://liquidjs.com/tutorials/intro-to-liquid.html). It has a brief summary of Liquid's two kinds of markup:

* **Outputs**, which output HTML.

  The syntax for outputs is a variable or value and optional list of filters surrounded by `{{` and `}}`. For example, `{{ user.name }}`.

* **Tags**, which control template rendering and implement logic.

  The syntax for tags is a tag name and optional arguments surrounded by`{%` and `%}`. For example, `{% if user_metadata.lang == 'it' %} Ciao! {% endif %}`.

This page lists the tags, filters, and variables supported in email templates.

## Tags

All email templates support the following Liquid tags:

| Category     | Tags                                    |
| ------------ | --------------------------------------- |
| Iteration    | `for`, `cycle`, `tablerow`              |
| Control flow | `if`, `unless`, `elsif`, `else`, `case` |
| Variable     | `assign`, `increment`, `decrement`      |
| File         | `include`, `layout`                     |
| Language     | `raw`, `comment`                        |

You can view descriptions and examples of Liquid tags on the [LiquidJS tags page](https://liquidjs.com/tags/overview.html).

### debug tag

To support debugging and development, our custom `{% debug %}` tag outputs a summary of the template variables available to your template when it was rendered.

## Filters

All email templates support the following Liquid filters:

| Category | Filters                                                                                                                                                                                            |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Math     | `plus`, `minus`, `modulo`, `times`, `floor`, `ceil`, `round`, `divided_by`, `abs`, `at_least`, `at_most`                                                                                           |
| String   | `append`, `prepend`, `capitalize`, `upcase`, `downcase`, `strip`, `lstrip`, `rstrip`, `strip_newlines`, `split`, `replace`, `replace_first`, `remove`, `remove_first`, `truncate`, `truncatewords` |
| HTML/URI | `escape`, `escape_once`, `url_encode`, `url_decode`, `strip_html`, `newline_to_br`                                                                                                                 |
| Array    | `slice`, `map`, `sort`, `sort_natural`, `first`, `last`, `join`, `reverse`, `size`                                                                                                                 |
| Date     | `date`                                                                                                                                                                                             |
| Misc     | `default`                                                                                                                                                                                          |

You can view descriptions and examples of Liquid filters on the [LiquidJS filters page](https://liquidjs.com/filters/overview.html).

## General variables

The following variables are available to the **From Address**, **Subject**, and **Message** fields in every template (unless otherwise noted).

To use untrusted properties in email templates, escape them with the `escape` filter (for example, `{{ user.name | escape }}`).

* The `application` object, with access to the standard client properties like `application.name` and `application.metadata`

* `request_language` language selection for users

* `connection.name`

<Warning>
  - In the MFA enrollment email template, the `connection.name` variable is not available.
</Warning>

* Tenant-related information defined in [Tenant Settings](https://manage.auth0.com/#/tenant):
  * `tenant`, which is the raw tenant name
  * `friendly_name`
  * `support_email`
  * `support_url`

* The following `user` variables:
  * `user.email`
  * `user.email_verified`
  * `user.picture` (**untrusted**)
  * `user.nickname` (**untrusted**)
  * `user.given_name` (**untrusted**)
  * `user.family_name` (**untrusted**)
  * `user.name` (**untrusted**)
  * `user.app_metadata`, user attributes that can impact a user's core functionality, such as how an application functions or what the user can access, including their support plan, security roles, and access control groups
  * `user.user_metadata` (**untrusted** if containing user-provided information), user attributes that do not impact a user's core functionality, including user preferences

<Warning>
  In the Passwordless OTP email template, only the `email` property of the `user` object is available.
</Warning>

* When a user logs in through an [Organization](/docs/manage-users/organizations/organizations-overview), the following additional variables are available:
  * `organization.id`
  * `organization.display_name`
  * `organization.name`
  * `organization.metadata`
  * `organization.branding.logo_url`
  * `organization.branding.colors.primary`
  * `organization.branding.colors.page_background`

* Multiple <Tooltip href="/docs/glossary?term=custom+domains">custom domains</Tooltip> variables:

  * `custom_domain.domain`, the tenant's domain name
  * `custom_domain.domain_metadata`, the custom domain's metadata fields (key-value pairs)

### Redirect To variables

In email templates with a **Redirect To** URL field, only the following three variables are supported:

* `application.name` (or its synonym `client.name`)
* `application.clientID`
* `application.callback_domain` (or its synonym `client.callback_domain`), which contains the origin of the first URL listed in the application's **Allowed Callback URL** list. This is an origin and therefore includes the protocol (like `https://`) in addition to the domain.

  The callback domain lets you redirect users to a path of the application that triggered the action by using a syntax like `{{ application.callback_domain }}/result_page`.

## Template-specific variables

In addition to the common Liquid variables available to all email templates, the following email templates have additional variables available.

### Blocked account email template variables

* `user.source_ip`
* `user.city`
* `user.country`

### Change password (code) email template variables

* `code`, the password change code

### Change password (link) email template variables

* `url`, the password reset link

### MFA enrollment email template variables

* `link`, the MFA enrollment link.

### Passwordless OTP email template variables

* `send`, with a value of `link`, `link_ios`, `link_android` or `code` depending on the type of passwordless email requested
* `code` with the one-time-use code to access the application
* `link` with the link that can be clicked by the user to gain access to the application (only for link-type passwordless emails)
* `operation`, with a value of `change_email` for a passwordless email change operation

### User invitation email template variables

* `inviter.name`
* `roles.id`
* `roles.name`
* `roles.description`

### Verification email (code) template variables

* `code`, the verification code

### Verification email (link) template variables

* `url`, the verification link


# Customize Email and Ticket Handling with the Management API
Source: https://auth0.com/docs/customize/email/manage-email-flow

Use the Management API to send emails outside of standard workflows, create tickets on demand, and customize ticket behavior.

The <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> has several email-related endpoints which you can use to augment the standard email workflows. For example, you can:

* Send some email types (like MFA enrollment emails) on demand

* Create tickets, which are generated URLs for email workflow actions (like password resets), on demand

* Customize the behavior of tickets, like setting different **Return To** URLs for verification emails or configuring password reset tickets to verify the user's email address.

## Verification email endpoints

Outside of the email verification workflow, you can use the [Send an email address verification email endpoint](https://auth0.com/docs/api/management/v2/jobs/post_verification_email) to send these emails on demand.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/jobs/verification-email' \
    --header 'authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
    --header 'content-type: application/json' \
    --data '{ "user_id": "{USER_ID_OF_EMAIL_RECIPIENT}", "client_id": "{YOUR_APP_CLIENT_ID}","identity": {"user_id": "5457edea1b8f22891a000004","provider": "google-oauth2"}, "organization_id": "{YOUR_ORGANIZATION_ID}" }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/jobs/verification-email");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer {YOUR_MANAGEMENT_API_TOKEN}");
  request.AddParameter("application/json", "{ "user_id": "{USER_ID_OF_EMAIL_RECIPIENT}", "client_id": "{YOUR_APP_CLIENT_ID}","identity": {"user_id": "5457edea1b8f22891a000004","provider": "google-oauth2"}, "organization_id": "{YOUR_ORGANIZATION_ID}" }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
      "fmt"
      "strings"
      "net/http"
      "io/ioutil"
  )

  func main() {
      url := "https://{yourDomain}/api/v2/jobs/verification-email"
      payload := strings.NewReader("{ "user_id": "{USER_ID_OF_EMAIL_RECIPIENT}", "client_id": "{YOUR_APP_CLIENT_ID}","identity": {"user_id": "5457edea1b8f22891a000004","provider": "google-oauth2"}, "organization_id": "{YOUR_ORGANIZATION_ID}" }")

      req, _ := http.NewRequest("POST", url, payload)
      req.Header.Add("content-type", "application/json")
      req.Header.Add("authorization", "Bearer {YOUR_MANAGEMENT_API_TOKEN}")

      res, _ := http.DefaultClient.Do(req)
      defer res.Body.Close()
      body, _ := ioutil.ReadAll(res.Body)

      fmt.Println(res)
      fmt.Println(string(body))
  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/jobs/verification-email")
      .header("content-type", "application/json")
      .header("authorization", "Bearer <YOUR_MANAGEMENT_API_TOKEN>")
      .body("{ "user_id": "{USER_ID_OF_EMAIL_RECIPIENT}", "client_id": "{YOUR_APP_CLIENT_ID}","identity": {"user_id": "5457edea1b8f22891a000004","provider": "google-oauth2"}, "organization_id": "{YOUR_ORGANIZATION_ID}" }")
      .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
      method: 'POST',
      url: 'https://{yourDomain}/api/v2/jobs/verification-email',
      headers: {
          'content-type': 'application/json',
          authorization: 'Bearer {YOUR_MANAGEMENT_API_TOKEN}'
      },
      data: {
          user_id: '{USER_ID_OF_EMAIL_RECIPIENT}',
          client_id: '{YOUR_APP_CLIENT_ID}',
          identity: {user_id: '5457edea1b8f22891a000004', provider: 'google-oauth2'},
          organization_id: '{YOUR_ORGANIZATION_ID}'
      }
  };

  axios.request(options).then(function (response) {
      console.log(response.data);
  }).catch(function (error) {
      console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer {YOUR_MANAGEMENT_API_TOKEN}" };
  NSDictionary *parameters = @{ @"user_id": @"{USER_ID_OF_EMAIL_RECIPIENT}",
                                @"client_id": @"{YOUR_APP_CLIENT_ID}",
                                @"identity": @{ @"user_id": @"5457edea1b8f22891a000004", @"provider": @"google-oauth2" },
                                @"organization_id": @"{YOUR_ORGANIZATION_ID}" };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest
      requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/jobs/verification-email"]
      cachePolicy:NSURLRequestUseProtocolCachePolicy
      timeoutInterval:10.0
  ];

  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
      CURLOPT_URL => "https://{yourDomain}/api/v2/jobs/verification-email",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_ENCODING => "",
      CURLOPT_MAXREDIRS => 10,
      CURLOPT_TIMEOUT => 30,
      CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
      CURLOPT_CUSTOMREQUEST => "POST",
      CURLOPT_POSTFIELDS => "{ "user_id": "{USER_ID_OF_EMAIL_RECIPIENT}", "client_id": "{YOUR_APP_CLIENT_ID}","identity": {"user_id": "5457edea1b8f22891a000004","provider": "google-oauth2"}, "organization_id": "{YOUR_ORGANIZATION_ID}" }",
      CURLOPT_HTTPHEADER => [
          "authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}",
          "content-type: application/json"
      ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
      echo "cURL Error #:" . $err;
  } else {
      echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")
  payload = "{ "user_id": "{USER_ID_OF_EMAIL_RECIPIENT}", "client_id": "{YOUR_APP_CLIENT_ID}","identity": {"user_id": "5457edea1b8f22891a000004","provider": "google-oauth2"}, "organization_id": "{YOUR_ORGANIZATION_ID}" }"
  headers = {
      'content-type': "application/json",
      'authorization': "Bearer {YOUR_MANAGEMENT_API_TOKEN}"
  }

  conn.request("POST", "/{yourDomain}/api/v2/jobs/verification-email", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/jobs/verification-email")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer {YOUR_MANAGEMENT_API_TOKEN}'
  request.body = "{ "user_id": "{USER_ID_OF_EMAIL_RECIPIENT}", "client_id": "{YOUR_APP_CLIENT_ID}","identity": {"user_id": "5457edea1b8f22891a000004","provider": "google-oauth2"}, "organization_id": "{YOUR_ORGANIZATION_ID}" }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
      "content-type": "application/json",
      "authorization": "Bearer {YOUR_MANAGEMENT_API_TOKEN}"
  ]
  let parameters = [
      "user_id": "{USER_ID_OF_EMAIL_RECIPIENT}",
      "client_id": "{YOUR_APP_CLIENT_ID}",
      "identity": [
          "user_id": "5457edea1b8f22891a000004",
          "provider": "google-oauth2"
      ],
      "organization_id": "{YOUR_ORGANIZATION_ID}"
  ] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
  let request = NSMutableURLRequest(
      url: NSURL(string: "https://{yourDomain}/api/v2/jobs/verification-email")! as URL,
      cachePolicy: .useProtocolCachePolicy,
      timeoutInterval: 10.0
  )

  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

Additionally, you can use the [Create an email verification ticket](https://auth0.com/docs/api/management/v2/tickets/post-email-verification) endpoint to generate email verification tickets.

## Password change endpoints

Outside of the change password link workflow, you can use the [Create a password change ticket](https://auth0.com/docs/api/management/v2/tickets/post-password-change) endpoint to generate password change tickets.

The change password link template has a **Redirect To** field which supports variables, like the user's ID. For more granular control, you can email the user a password reset ticket that you generate using this endpoint and set the `result_url` based your own criteria.

This endpoint also lets you customize whether to verify the user's email or include the email address as part of the `return_url`.

## MFA enrollment endpoints

Outside of the MFA enrollment workflow, you can use the [Create a multi-factor authentication enrollment ticket](https://auth0.com/docs/api/management/v2/guardian/post-ticket) endpoint to generate MFA enrollment tickets and optionally send an email with the created ticket.

When using Universal Login, this endpoint also lets you specify which factor the user must enroll with and whether a user already enrolled with MFA can enroll with additional factors.


# Implement User Invitations for Application Sign-Up using Password Reset Emails
Source: https://auth0.com/docs/customize/email/send-email-invitations-for-application-signup

How to implement a way to invite users to sign up for an account in an Auth0 application.

<Warning>
  Looking for how to invite users to an Organization? Read [Invite Organization Members](/docs/manage-users/organizations/configure-organizations/invite-members) instead.
</Warning>

One way to manage sign-ups for an Auth0 application is with user invitations.

In a typical user invitation workflow, an application administrator creates a new user account and then sends an email invitation to a user with an activation link. When the user follows the link, they set a password for the account, and can then log in.

A user invitation system can be useful for use cases like restricting sign-ups or creating accounts in bulk.

## Implementing user invitations for application sign-up on Auth0

On Auth0, you can implement user invitations using the password change workflow.

* By styling the Universal Login or Classic Login password reset page to additionally support a user invitation experience, you can use a password change link as an invitation to a new user account.

* By similarly customizing the password change email template, you can use Auth0's password change workflow to generate the password change link and send the invitation email using your tenant's [configured SMTP provider](/docs/customize/email/smtp-email-providers).

<Callout icon="file-lines">
  If you already have an external email solution and don't want to configure an SMTP provider on your tenant, you can [use the Management API to generate the password change ticket](https://auth0.com/docs/api/management/v2/tickets/post-password-change) and email the ticket link to the user yourself instead of using Auth0's email template and workflow.
</Callout>

This implementation relies on a user metadata property (named `user.app_metadata.needsInvitation` in these instructions) which indicates that the user has an outstanding invitation: when it's `true`, the user receives the user invitation experience; otherwise, they receive the regular password reset experience.

### 1. Customize the password change email template

First, [customize the password change (link) email template](/docs/customize/email/email-templates/customize-email-templates) to handle both user invitation and password change workflows.

[Use Liquid](/docs/customize/email/email-templates/supported-liquid-syntax) to check whether the user metadata property for an outstanding invitation is set and send the appropriate message. For example:

```liquid lines theme={null}
{% if user.app_metadata.needsInvitation %}
    // User invitation email content here
{% else %}
    // Password change email content here
{% endif %}
```

Additionally, append a query parameter to the password reset link in the message body to indicate which experience the user should see on the password reset page. For example, you can append `type=invite` or `type=reset`.

### 2. Style the password reset page

Based on the query parameter you set in the template, style the password reset page to support both user invitation and password change workflows based on the query parameter.

For instructions with Universal Login, read [Customize Universal Login](/docs/customize/login-pages/universal-login). For instructions with Classic Login, read [Customize Password Reset Page](/docs/customize/login-pages/classic-login/customize-password-reset-page).

### 3. Create a post-login Action to unset the invitation property

Once the user sets their password and logs in for the first time, they no longer need an invitation and should receive the password change experience in the future.

To handle this, [create a post-login Action](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) that sets `user.app_metadata.needsInvitation` to `false`:

```javascript theme={null}
exports.onExecutePostLogin = async (event, api) => {
    if (event.user.app_metadata.needsInvitation) {
        api.user.setAppMetadata("needsInvitation", false);
    }
};
```

### 4. Send user invitations

To send a user invitation, [create a new Auth0 database user from the dashboard](/docs/authenticate/database-connections) or the [Create a User endpoint](https://auth0.com/docs/api/management/v2/#!/Users/post_users) in the Management API and:

* Set the `user.email_verified` parameter set to `false`.

* Set `user.app_metadata.needsInvitation` to `true`.

Then, call the Authentication API's [Change password endpoint](https://auth0.com/docs/api/authentication/change-password/change-password) to send the invitation email to the user.

## Learn more

To control where the user is redirected after setting their password:

* For Universal Login, [customize the password reset flow login route](/docs/authenticate/login/auth0-universal-login/configure-default-login-routes#complete-password-reset-flow).

* For Classic Login, set the **Redirect To** field in the email template.

For more information on email configuration, you can read:

* [Customize Email Templates](/docs/customize/email/email-templates)

* [Configure External SMTP Email Providers](/docs/customize/email/smtp-email-providers)


# SMTP Email Provider Overview
Source: https://auth0.com/docs/customize/email/smtp-email-providers

Configure an external SMTP email provider to send emails in production and to use email templates to customize their appearance and content.

Auth0's email-based workflows handle when emails are sent and what the emails contain. To deliver the outgoing mail, you need an SMTP server or service from an external email provider.

You can configure a single email provider to handle all emails sent from your tenant. We offer three options for this configuration: integration with third-party email providers we support, direct SMTP server connections, or custom configuration with Actions.

## Supported Email Provider Integrations

Our email provider integrations let you configure your tenant by adding API credentials from a supported third-party provider.

We support the following providers:

* [Amazon SES](/docs/customize/email/smtp-email-providers/amazon-ses)
* [Azure Communication Services](/docs/customize/email/smtp-email-providers/azure-communication-services)
* [Mandrill](/docs/customize/email/smtp-email-providers/mandrill)
* [Microsoft 365 Exchange Online](/docs/customize/email/smtp-email-providers/microsoft-365-exchange-online)
* [SendGrid](/docs/customize/email/smtp-email-providers/sendgrid)
* [SparkPost](/docs/customize/email/smtp-email-providers/sparkpost)
* [Mailgun](/docs/customize/email/smtp-email-providers/mailgun)

## Custom Configuration with Actions

You can write an <Tooltip href="/docs/glossary?term=MFA">Action</Tooltip> to connect to any external email provider. This lets you implement custom logic for your use case and have more control over the email delivery process.

For more information, read [Custom Email Provider Configuration with Actions](/docs/customize/email/smtp-email-providers/custom).

## SMTP Server Configuration

You can configure your tenant by adding SMTP server details directly. This is a good option if:

* We don't support integration with your chosen email provider and you don't need or want to write an Action for configuration.

* You want to set up a dummy SMTP server (like [Debug Mail](https://debugmail.io/), [FakeSMTP](https://nilhcem.github.io/FakeSMTP/), or [smtp4dev](https://github.com/rnwood/smtp4dev)) for testing.

We don't allow certain false domains commonly used during testing. Use real email addresses to avoid disruption or errors.

For instructions, read [Configure an Email Provider with SMTP Server Details](/docs/customize/email/configure-custom-smtp-email-provider).

## The Built-In Email Provider

The built-in email provider is available by default and requires no configuration. However, it does not support production use and has the following limits:

* You cannot use custom email templates.

* You cannot customize the **From Address**. All emails are sent from `no-reply@auth0user.net`.

* You are limited to sending 10 emails per minute, regardless of email type.

* If your emails have a high bounce rate, we may reduce or temporarily block the ability to send email from your tenant.

To remove these limits and use emails in production, set up an external SMTP email provider.


# Configure Amazon Simple Email Service (SES) as an Email Provider
Source: https://auth0.com/docs/customize/email/smtp-email-providers/amazon-ses

Instructions on how to configure Amazon Simple Email Service (SES) as an email provider with Auth0.

## Prerequisites

* You must have an [Amazon AWS](http://aws.amazon.com/ses/) account.

* You must configure your provider to allow inbound connections from specific [Auth0 IP addresses](/docs/secure/security-guidance/data-security/allowlist).

You can use API or SMTP credentials. To learn more, see Amazon's [Using Credentials With Amazon SES](http://docs.aws.amazon.com/ses/latest/DeveloperGuide/using-credentials.html).

## Configure Amazon SES with API credentials

1. Log in to your [Amazon AWS](http://aws.amazon.com/ses/) account.
2. [Verify your domain](http://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-domains.html).
3. [Verify email addresses](http://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-email-addresses.html)
4. [Request production access](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/request-production-access.html?icmpid=docs_ses_console).
5. [Get your AWS access keys](http://docs.aws.amazon.com/ses/latest/DeveloperGuide/get-aws-keys.html). Copy these keys; you will need to enter these values into Auth0.
6. [Attach a policy with the proper permissions](http://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage.html). Attach a policy with the `ses:SendRawEmail` and `ses:SendEmail` permissions, as in this example:

   ```json lines theme={null}
   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
                   "ses:SendRawEmail",
                   "ses:SendEmail"
               ],
               "Resource": "*"
           }
       ]
   }
   ```
7. Navigate to Auth0 [Dashboard > Branding > Email Provider](https://manage.auth0.com/#/branding/email_provider).
8. Activate the **Use my own email provider** toggle.
9. Click the **Amazon Web Services** logo.
10. Provide a **From** email address, enter your AWS **Access Key Id** and **Secret Access Key**, select your **Region**.
11. Click **Save**.

## Configure Amazon SES with SMTP credentials

1. Log in to your [Amazon AWS](https://aws.amazon.com/ses/) account.
2. [Verify your domain](http://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-domains.html).
3. [Request production access](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/request-production-access.html?icmpid=docs_ses_console).
4. [Get your SMTP credentials](http://docs.aws.amazon.com/ses/latest/DeveloperGuide/smtp-credentials.html). Copy the security credentials; you will need to enter these values into Auth0.
5. Navigate to [Dashboard > Branding > Email Provider](https://manage.auth0.com/#/emails/provider).
6. Activate the **Use my own email provider** toggle.
7. Click the **SMTP** logo.
8. Provide a **From** email address, then enter your SMTP server **Host**, **Port**, **Username**, and **Password**, and click **Save**. You can use `email-smtp.us-east-1.amazonaws.com` (using the appropriate region rather than `us-east-1`) for **Host** and `587` for **Port**.

## Send a test email

Send a test email using the **Send Test Email** button. If the configuration is correct, you receive a confirmation email. If you do not receive an email after a few minutes, check your [Auth0 logs](https://manage.auth0.com/#/logs) for error codes.

Once configured, the [Amazon SES console](https://console.aws.amazon.com/ses) displays delivery insights for all emails that have been sent to your users.


# Configure Azure Communication Services as an Email Provider
Source: https://auth0.com/docs/customize/email/smtp-email-providers/azure-communication-services

Instructions on how to configure Azure Communication Services as an email provider with Auth0.

## Prerequisites

* You must have an [Microsoft Azure](https://azure.microsoft.com/en-us) account.

* You must configure your provider to allow inbound connections from specific [Auth0 IP addresses](/docs/secure/security-guidance/data-security/allowlist).

## Configure Azure Communication Services

First, create a resource in Microsoft Azure:

1. Log in to your [Microsoft Azure](https://azure.microsoft.com/en-us) account.
2. Enter "Communication Services" in the search bar.
3. Create a [Communication Services](https://learn.microsoft.com/en-us/azure/communication-services/quickstarts/create-communication-resource) resource if you do not have one.
4. Select **Create**.
5. Under the **Tools** settings, select **Keys**. Retrieve your [Communication Services connection string](https://learn.microsoft.com/en-us/azure/communication-services/quickstarts/create-communication-resource).
6. Under **Primary Key**, copy the **Connection string** value.
   A valid connection string follows the format `endpoint=COMMUNICATION_SERVICES_URL;accesskey=ACCESS_KEY`.

Next, configure your email provider in Auth0:

1. Go to [Dashboard > Branding > Email Provider](https://manage.auth0.com/#/branding/email_provider).

2. Select **Use my own email provider**.

3. Select **Azure Communication Services**.

4. Enter a **From** email address.

   <Warning>
     Azure Communications Services only supports a raw email address (`user@example.com`) in the **From** field.
   </Warning>

5. Add the Azure Communication Services **Connection string**.

6. Select **Save**.

## Send a test email

Send a test email using the **Send Test Email** button. If the configuration is correct, you receive a confirmation email. If you do not receive an email after a few minutes, check your [Auth0 logs](https://manage.auth0.com/#/logs) for error codes.

Once configured, the Communication Services [Metrics Monitor](https://learn.microsoft.com/en-us/azure/communication-services/concepts/metrics#chat-api-request-metric-operations) page displays delivery insights for all emails that have been sent to your users.


# Custom Email Provider Configuration with Actions
Source: https://auth0.com/docs/customize/email/smtp-email-providers/custom

Write an Action to deliver messages to your email provider and implement custom logic for your use case.

For more customization in your email provider configuration, you can configure your tenant with an <Tooltip href="/docs/glossary?term=Action">Action</Tooltip>.

Instead of using our email provider or SMTP server integrations, you write the code for your Action to deliver messages to your chosen email provider or SMTP server.

This gives you more control over the email delivery process and lets you implement custom logic for your use case, like retrying failures, changing recipients, or creating Organization-specific logic.

| Read...                                                                                                                                                           | To learn...                                                                                                            |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| [Configure an Custom Email Provider Action](/docs/customize/email/smtp-email-providers/custom/configure-action)                                                   | How to use the Auth0 Dashboard or the Terraform Auth0 provider to configure your tenant with an email provider Action. |
| [Action Triggers: custom-email-provider Event Object](/docs/customize/email/configure-a-custom-email-provider/action-triggers-custom-email-provider-event-object) | The properties available in the `custom-email-provider` Actions trigger `event` object.                                |
| [Action Triggers: custom-email-provider API Object](/docs/customize/email/configure-a-custom-email-provider/action-triggers-custom-email-provider-api-object)     | The properties available in the `custom-email-provider` Actions trigger API object.                                    |


# Actions Triggers: custom-email-provider - API Object
Source: https://auth0.com/docs/customize/email/smtp-email-providers/custom/action-triggers-custom-email-provider-api-object

Learn about the custom-email-provider Action trigger's API object.

The API object for the custom-email-provider Actions trigger includes:

## `api.cache`

Make changes to the cache.

### `api.cache.delete(key)`

Delete a record describing a cached value at the supplied
key if it exists.

<ResponseField name="key" type="string">
  The key of the cache record to delete.
</ResponseField>

### `api.cache.get(key)`

Retrieve a record describing a cached value at the supplied key,
if it exists. If a record is found, the cached value can be found
at the `value` property of the returned object.

<ResponseField name="key" type="string">
  The key of the record stored in the cache.
</ResponseField>

### `api.cache.set(key, value, options)`

Store or update a string value in the cache at the specified key.

Values stored in this cache are scoped to the Trigger in which they
are set. They are subject to the [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations).

Values stored in this way will have lifetimes of *up to* the specified
`ttl` or `expires_at` values. If no lifetime is specified, a default of
lifetime of 24 hours will be used. Lifetimes may not exceed the maximum
duration listed at [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations).

**Important**: This cache is designed for short-lived, ephemeral data. Items may not be
available in later transactions even if they are within their supplied their lifetime.

<ResponseField name="key" type="string">
  The key of the record to be stored.
</ResponseField>

<ResponseField name="value" type="string">
  The value of the record to be stored.
</ResponseField>

<ResponseField name="options" type="cachesetoptions">
  Options for adjusting cache behavior.

  <Expandable title="options properties">
    <ResponseField name="expires_at" type="number">
      The absolute expiry time in milliseconds since the unix epoch.
      While cached records may be evicted earlier, they will
      never remain beyond the the supplied `expires_at`.

      *Note*: This value should not be supplied if a value was also
      provided for `ttl`. If both options are supplied, the
      earlier expiry of the two will be used.
    </ResponseField>

    <ResponseField name="ttl" type="number">
      The time-to-live value of this cache entry in milliseconds.
      While cached values may be evicted earlier, they will
      never remain beyond the the supplied `ttl`.

      *Note*: This value should not be supplied if a value was also
      provided for `expires_at`. If both options are supplied, the
      earlier expiry of the two will be used.
    </ResponseField>
  </Expandable>
</ResponseField>

## `api.notification`

Informs if we should consider the notification event as to be retried or to be dropped.
See each of these methods for further details on the actual behaviour.
If several calls are made, only the last one is considered.

### `api.notification.drop(reason)`

When called, the notification event is considered failed without recovery:
We will log an error for this event, but won't be sending it again to the action in the future.
If you need this notification event to be retried, consider calling retry instead.

<ResponseField name="reason" type="string">
  this reason will be part of the log entry, this will help you analyze the error further. Please note that this field is limited to 1024 characters and will be truncated if larger.
</ResponseField>

### `api.notification.retry(reason)`

When called, the notification event is considered failed, but recoverable:
We will log an error for this event, but we will retry it up to 5 times in the next minutes.
If you consider that this notification event should not be retried, consider calling drop instead.

<ResponseField name="reason" type="string">
  this reason will be part of the log entry, this will help you analyze the error further. Please note that this field is limited to 1024 characters and will be truncated if larger.
</ResponseField>


# Actions Triggers: custom-email-provider - Event Object
Source: https://auth0.com/docs/customize/email/smtp-email-providers/custom/action-triggers-custom-email-provider-event-object

Learn about the custom-email-provider Action trigger's event object, which provides contextual information about the trigger execution.

The `event` object for the custom-email-provider Actions trigger provides contextual information about the trigger execution.

## `event.client`

<ResponseField name="event.client" type="dictionary">
  Information about the Client with which this login transaction was initiated.

  <Expandable title="client properties">
    <ResponseField name="client_id" type="string">
      The client id of the application the user is logging in to.
    </ResponseField>

    <ResponseField name="metadata" type="dictionary">
      An object for holding other application properties.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the application (as defined in the Dashboard).
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.connection`

<ResponseField name="event.connection" type="dictionary">
  Details about the Connection that was used to authenticate the user.

  <Expandable title="connection properties">
    <ResponseField name="id" type="string">
      The connection's unique identifier.
    </ResponseField>

    <ResponseField name="metadata" type="dictionary">
      Metadata associated with the connection.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the connection used to authenticate the user (such as `twitter` or `some-g-suite-domain`).
    </ResponseField>

    <ResponseField name="strategy" type="string">
      The type of connection. For social connections, `event.connection.strategy === event.connection.name`. For enterprise connections, the strategy is `waad` (Windows Azure AD), `ad` (Active Directory/LDAP), `auth0` (database connections), and so on.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.custom_domain`

<ResponseField name="event.custom_domain" type="dictionary">
  Details about the custom domain associated with the current transaction.

  <Expandable title="custom_domain properties">
    <ResponseField name="domain" type="string">
      The custom domain name.
    </ResponseField>

    <ResponseField name="domain_metadata" type="dictionary">
      Custom domain metadata as key-value pairs.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.notification`

<ResponseField name="event.notification" type="object">
  <Expandable title="notification properties">
    <ResponseField name="from" type="string">
      Email address of the sender for the email.
    </ResponseField>

    <ResponseField name="html" type="string">
      Rendered HTML template.
    </ResponseField>

    <ResponseField name="locale" type="string">
      The locale we rendered the message in, example `en_US`, as defined in the BCP-47 specification.
    </ResponseField>

    <ResponseField name="message_type" type="string">
      The type of message that is being send, like `verify_email` or `welcome_email`.

      Possible values:

      * `verify_email`
      * `verify_email_by_code`
      * `reset_email`
      * `reset_email_by_code`
      * `welcome_email`
      * `verification_code`
      * `mfa_oob_code`
      * `enrollment_email`
      * `blocked_account`
      * `stolen_credentials`
      * `try_provider_configuration_email`
      * `organization_invitation`
    </ResponseField>

    <ResponseField name="subject" type="string">
      Subject to be attached to the email.
    </ResponseField>

    <ResponseField name="text" type="string">
      Rendered text template.
    </ResponseField>

    <ResponseField name="to" type="string">
      Email address of the recipient.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.organization`

<ResponseField name="event.organization" type="dictionary">
  Details about the Organization associated with the current transaction.

  <Expandable title="organization properties">
    <ResponseField name="id" type="string">
      The Organization identifier.
    </ResponseField>

    <ResponseField name="display_name" type="string">
      The friendly name of the Organization.
    </ResponseField>

    <ResponseField name="metadata" type="dictionary">
      Metadata associated with the Organization.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the Organization.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.request`

<ResponseField name="event.request" type="dictionary">
  <Expandable title="request properties">
    <ResponseField name="geoip" type="dictionary">
      <Expandable title="geoip properties">
        <ResponseField name="cityName" type="string" />

        <ResponseField name="continentCode" type="string" />

        <ResponseField name="countryCode" type="string" />

        <ResponseField name="countryCode3" type="string" />

        <ResponseField name="countryName" type="string" />

        <ResponseField name="latitude" type="number" />

        <ResponseField name="longitude" type="number" />

        <ResponseField name="subdivisionCode" type="string" />

        <ResponseField name="subdivisionName" type="string" />

        <ResponseField name="timeZone" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="hostname" type="string">
      The hostname that is being used for the authentication flow.
    </ResponseField>

    <ResponseField name="ip" type="string">
      The originating IP address of the request.
    </ResponseField>

    <ResponseField name="query" type="dictionary">
      The query string parameters sent to the authorization request.
    </ResponseField>

    <ResponseField name="user_agent" type="string">
      The value of the `User-Agent` header received when initiating the transaction.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.tenant`

<ResponseField name="event.tenant" type="object">
  <Expandable title="tenant properties">
    <ResponseField name="id" type="string">
      The name of the tenant.
    </ResponseField>

    <ResponseField name="friendly_name" type="string">
      The friendly name for the tenant, usually a more human-readable version of the ID.
    </ResponseField>

    <ResponseField name="home_url" type="string">
      The home URL for the tenant, if defined and as found in its settings.
    </ResponseField>

    <ResponseField name="logo_url" type="string">
      The logo URL for the tenant, if defined and as found in its settings.
    </ResponseField>

    <ResponseField name="support_email" type="string">
      The email to the tenant's support service, if defined and as found in its settings.
    </ResponseField>

    <ResponseField name="support_url" type="string">
      The url to the tenant's support service, if defined and as found in its settings.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.transaction`

<ResponseField name="event.transaction" type="object">
  Details about the current transaction for tracing purposes.

  <Expandable title="transaction properties">
    <ResponseField name="correlation_id" type="string">
      A unique identifier to correlate this request across multiple services for distributed tracing.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.user`

<ResponseField name="event.user" type="dictionary">
  An object describing the user on whose behalf the current transaction was initiated.

  <Expandable title="user properties">
    <ResponseField name="app_metadata" type="dictionary">
      Custom fields that store info about a user that influences the user's access, such as support plan, security roles, or access control groups.
    </ResponseField>

    <ResponseField name="email" type="string">
      (unique) User's email address.
    </ResponseField>

    <ResponseField name="email_verified" type="boolean">
      Indicates whether the user has verified their email address.
    </ResponseField>

    <ResponseField name="family_name" type="string">
      User's family name.
    </ResponseField>

    <ResponseField name="given_name" type="string">
      User's given name.
    </ResponseField>

    <ResponseField name="name" type="string">
      User's full name.
    </ResponseField>

    <ResponseField name="nickname" type="string">
      User's nickname.
    </ResponseField>

    <ResponseField name="picture" type="string">
      URL pointing to the [user's profile picture](https://auth0.com/docs/users/change-user-picture).
    </ResponseField>

    <ResponseField name="user_id" type="string">
      (unique) User's unique identifier.
    </ResponseField>

    <ResponseField name="user_metadata" type="dictionary">
      Custom fields that store info about a user that does not impact what they can or cannot access, such as work address, home address, or user preferences.
    </ResponseField>

    <ResponseField name="username" type="string">
      (unique) User's username.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.secrets`

<ResponseField name="event.secrets" type="secrets">
  Secret values securely associated with this Action.
</ResponseField>


# Configure an Email Provider with a Customized Action
Source: https://auth0.com/docs/customize/email/smtp-email-providers/custom/configure-action

Write an Action that delivers messages to your email provider from either the Auth0 Dashboard or Terraform Auth0 provider, and implement custom logic for your use case.

## Configure an email provider Action using the Auth0 Dashboard

To use the Auth0 Dashboard to configure your tenant with a custom email provider Action:

1. Go to [Auth0 Dashboard > Branding > Email Provider](https://manage.auth0.com/#/templates/provider).

2. Enable the **Use my own email provider** toggle.

3. In the **Email Provider** Section, select **Custom Provider**.

4. In the **From** field, enter the default email address from which emails are sent.

5. In the code editor, write your Action code to deliver messages to your email provider. Use your provider's documentation on their API or SMTP connection details.

   In the left menu of the code editor, you can click the key icon to add secrets (for example, to authenticate with an API) and click the box to add dependencies.

6. When you're finished writing the Action, click **Save** to deploy it.

To test your configuration, click **Send Test Email**.

Like other Actions, you can use the [Management API](https://auth0.com/docs/api/management/v2/actions/get-actions) to manage the Action and its [versions](/docs/customize/actions/manage-versions). All Actions are subject to the same [limitations](/docs/customize/actions/limitations).

## Configure an email provider Action using Terraform

The [Terraform Auth0 provider](https://registry.terraform.io/providers/auth0/auth0/latest/docs) uses the [Auth0 Management API](https://auth0.com/docs/api/management/v2) to perform actions on the Auth0 platform.

You can use the Terraform Auth0 provider to create a custom email provider Action and configure your tenant to use it.

### 1. Unbind or delete conflicting Actions

You can have at most one Action bound to the `custom-email-provider` trigger.

If your tenant is already configured with a custom email provider Action, reset it before creating a new email provider Action with Terraform:

1. Go to [Auth0 Dashboard > Branding > Email Provider](https://manage.auth0.com/#/templates/provider).
2. In the **Email Provider** section, click **Custom Provider**.
3. Below the Actions code editor, click **Reset**.

You can check if you have other deployed actions bound to the `custom-email-provider` trigger using the Management API:

1. [List your Actions](https://auth0.com/docs/api/management/v2/actions/get-actions) to identify any duplicate Actions.
2. [Update their trigger bindings](https://auth0.com/docs/api/management/v2/actions/patch-bindings) or [delete the Actions](https://auth0.com/docs/api/management/v2/actions/delete-action).

### 2. Create a new email provider Action

Use the [Terraform `auth0_action` resource](https://registry.terraform.io/providers/auth0/auth0/latest/docs/resources/action) to create an Action that supports the `custom-email-provider` trigger. Set `deploy = true` to immediately create a new version of the Action.

```terraform lines theme={null}
resource "auth0_action" "custom_email_provider" {
  name    = "Custom Email Provider"
  runtime = "node20"
  deploy  = true
  code    = <<-EOT
    /**
    * Handler to be executed while sending an email notification
    * @param {Event} event - Details about the user and the context in which they are logging in.
    * @param {CustomEmailProviderAPI} api - Methods and utilities to help change the behavior of sending a email notification.
    */
    exports.onExecuteCustomEmailProvider = async (event, api) => {
      // Code goes here
      return;
    };
  EOT
  supported_triggers {
    id      = "custom-email-provider"
    version = "v1"
  }
}
```

In the function stub, write your Action code to deliver messages to your email provider. Use your provider's documentation on their API or SMTP server details.

### 3. Bind the Action to the email provider trigger

Use the [Terraform `auth0_trigger_action` resource](https://registry.terraform.io/providers/auth0/auth0/latest/docs/resources/trigger_action) to bind the Action to the `custom-email-provider` trigger:

```terraform lines theme={null}
resource "auth0_trigger_action" "custom_email_provider" {
  trigger = "custom-email-provider"
  actions {
    id           = auth0_action.custom_email_provider.id
    display_name = auth0_action.custom_email_provider.name
  }
   depends_on = [
    auth0_action.custom_email_provider
  ]
 }
```

### 4. Configure your tenant's email provider with the Action

Use the [Terraform `auth0_email_provider` resource](https://registry.terraform.io/providers/auth0/auth0/latest/docs/resources/email_provider) to configure your tenant to use the email provider Action:

```terraform lines theme={null}
resource "auth0_email_provider" "custom_email_provider" {
  name                 = "custom"
  enabled              = true
  default_from_address = "accounts@example.com"
  credentials {}
  depends_on = [
    auth0_trigger_actions.custom_email_provider
  ]
```

If you create a new email provider Action with Terraform and it does not take effect, you may have already had a deployed Action bound to the `custom-email-provider` trigger. To troubleshoot and fix this issue, follow the first step of this article to [unbind or delete conflicting Actions](#1-unbind-or-delete-conflicting-actions).

## Example Email Provider Action

This is an example Action for the `custom-email-provider` trigger.

In this code sample, the function `onExecuteCustomEmailProvider` takes two arguments from the [`custom-email-provider` event object](/docs/customize/email/configure-a-custom-email-provider/action-triggers-custom-email-provider-event-object): `event`, which contains information about the user and the context of the notification, and `api`, which provides helper methods for custom behavior while sending notifications.

```javascript lines expandable theme={null}
/**
 * Handler to be executed while sending an email notification.
 * @param {Event} event - Details about the user and the context in which they are logging in.
 * @param {CustomEmailProviderAPI} api - Methods and utilities to help change the behavior of sending an email notification.
 */
exports.onExecuteCustomEmailProvider = async (event, api) => {
  // Define the email payload
  const emailPayload = {
    from: {
      name: "Test Sender",
      email: "sender@example.com"
    },
    to: [{ email: event.user.email }],
    subject: event.notification.message_type,
    html: event.notification.html,
    text: event.notification.text,
  };
  try {
    // Make the API call to send the email
    const response = await fetch('https://api.example.com/send-email', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${event.secrets.api_key}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(emailPayload),
    });
    if (response.ok) {
      console.log('Email sent successfully');
    } else if (response.status >= 500) {
      api.notification.retry(
        `Internal Server Error received from Messaging Proxy. Status code: ${response.status}.`
      );
      return;
    }
  } catch (error) {
    console.error(`Error sending email: ${error.message}`);
    api.notification.drop(`An unexpected error occurred. Error: ${error.message}`);
  }
  return;
};
```

To learn more about Actions, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).


# Configure Mailgun as an Email Provider
Source: https://auth0.com/docs/customize/email/smtp-email-providers/mailgun

Instructions on how to configure Mailgun as an email provider with Auth0.

## Prerequisites

* You must have a [Mailgun](https://mailgun.com) account.

* You must configure your provider to allow inbound connections from specific [Auth0 IP addresses](/docs/secure/security-guidance/data-security/allowlist).

## Configure Mailgun

1. Log in to your [Mailgun](https://mailgun.com).
2. Navigate to Mailgun **Sending > Domains**, and add your custom domain. Mailgun allows sending emails from only verified domains.
3. Navigate to Mailgun **Settings > API Keys**. Your API key was created when you signed up for your account; copy it from **Private API Key**.
4. Navigate to Auth0 [Dashboard > Branding > Email Provider](https://manage.auth0.com/#/branding/email_provider).
5. Activate the **Use my own email provider** toggle.
6. Click the **Mailgun** logo.
7. Provide a **From** email address, enter the **Domain** you previously added to Mailgun, enter the Mailgun **API Key** you previously copied, select your **Region**.
8. Click **Save**.

## Send a test email

Send a test email using the **Send Test Email** button. If the configuration is correct, you receive a confirmation email. If you do not receive an email after a few minutes, check your [Auth0 logs](https://manage.auth0.com/#/logs) for error codes.

Once configured, the [Mailgun Dashboard](https://app.mailgun.com/app/dashboard) displays delivery insights for all emails that have been sent to your users.


# Configure Mandrill as an Email Provider
Source: https://auth0.com/docs/customize/email/smtp-email-providers/mandrill

Instructions on how to configure Mandrill as an email provider with Auth0.

## Prerequisites

* You must have a [Mandrill](https://www.mandrill.com/signup/) account.

* You must configure your provider to allow inbound connections from specific [Auth0 IP addresses](/docs/secure/security-guidance/data-security/allowlist).

## Configure Mandrill

1. Log in to [Mandrill](https://www.mandrill.com/signup/).
2. Navigate to Mandrill [Settings](https://mandrillapp.com/settings), and click **Add API key**. Copy this key value.
3. Navigate to Auth0 [Dashboard > Branding > Email Provider](https://manage.auth0.com/#/branding/email_provider).
4. Activate the **Use my own email provider** toggle.
5. Click the **Mandrill** logo.
6. Provide a **From** email address and enter the Mandrill **API Key** you previously copied.
7. Click **Save**.

## Send a test email

Send a test email using the **Send Test Email** button. If the configuration is correct, you receive a confirmation email. If you do not receive an email after a few minutes, check your [Auth0 logs](https://manage.auth0.com/#/logs) for error codes.

Once configured, the Mandrill [Outbound Activity](https://mandrillapp.com/activity) page displays delivery insights for all emails that have been sent to your users.


# Configure Microsoft 365 Exchange Online as an Email Provider
Source: https://auth0.com/docs/customize/email/smtp-email-providers/microsoft-365-exchange-online

Instructions on how to configure 365 Exchange Online as an email provider with Auth0.

## Prerequisites

* You must have a [Microsoft 365](https://www.microsoft.com/en-us/microsoft-365) account with an active subscription.

* Your Microsoft 365 subscription must be licensed to send emails through Exchange Online. You need at a minimum a paid subscription to Microsoft Business Basic plan to use the Microsoft Graph API for Exchange Online.

* You must configure your provider to allow inbound connections from specific [Auth0 IP addresses](/docs/secure/security-guidance/data-security/allowlist).

## Configure Microsoft 365 Exchange Online

1. Log in to [Microsoft Azure](https://azure.microsoft.com/) account with your Microsoft 365 account.
2. Register a [Microsoft Entra ID Application](https://learn.microsoft.com/en-us/azure/healthcare-apis/register-application) resource if you currently do not have one.
3. Navigate to your Active Directory Application resource. Select **Services > App registrations**, and then select the application you will be using to send emails.
4. Configure the required application permissions by navigating to **Manage > API permissions**.
5. Add the `Mail.Send`[permission](https://learn.microsoft.com/en-us/azure/healthcare-apis/register-application#api-permissions) by selecting **Add a permission > Microsoft Graph > Application permissions** selector.

   <Callout icon="file-lines">
     Before you configure **Application permissions**, you will need administrative consent.
   </Callout>
6. Retrieve required provider configurations:

   1. Navigate to the **Application Overview** to retrieve your application [Client ID and Tenant ID](https://learn.microsoft.com/en-us/azure/healthcare-apis/register-application#application-id-client-id).
   2. Navigate to **Manage > Certificates & secrets** and collect the **Value** to create an application [secret](https://learn.microsoft.com/en-us/azure/healthcare-apis/register-application#certificates--secrets).
   3. Retrieve the organization **User Email** that will send the emails through the application by **Search > Users**. Select **Services > Users**, select your authorized user, and then collect their **User Email** from their properties.
7. Navigate to Auth0 [Dashboard > Branding > Email Provider](https://manage.auth0.com/#/branding/email_provider).
8. Activate the **Use my own email provider** toggle.
9. Click the **Microsoft 365** logo.
10. Provide the **From** email address. Then, enter the **Tenant ID**, **Client ID**, and **Client Secret** from step 6, and then click **Save**.

## Send a test email

Send a test email using the **Send Test Email** button. If the configuration is correct, you receive a confirmation email. If you do not receive an email after a few minutes, check your [Auth0 logs](https://manage.auth0.com/#/logs) for error codes.

Once configured, the Microsoft Exchange [Email Usage](https://admin.microsoft.com/#/reportsUsage/EmailActivity) page displays delivery insights for all emails that have been sent to your users.


# Configure SendGrid as an Email Provider
Source: https://auth0.com/docs/customize/email/smtp-email-providers/sendgrid

Instructions on how to configure SendGrid as an email provider with Auth0.

## Prerequisites

* You must have a [SendGrid](https://sendgrid.com) account. If you have a Microsoft Azure subscription, you can get a free account in the Azure Marketplace.

* You must configure your provider to allow inbound connections from specific [Auth0 IP addresses](/docs/secure/security-guidance/data-security/allowlist).

## Configure SendGrid

1. Log in to your [SendGrid](https://sendgrid.com) account.
2. Navigate to SendGrid **Settings > API Keys**, and click **Create API Key**.
3. Type a name for your key and select **Restricted Access**.
4. Under **Access Details**, click to expand **Mail Send**.
5. Set the **Mail Send** permission to **Full Access**.
6. Click **Save** and copy the key value.
7. Navigate to Auth0 [Dashboard > Branding > Email Provider](https://manage.auth0.com/#/branding/email_provider).
8. Activate the **Use my own email provider** toggle.
9. Click the **SendGrid** logo.
10. Type a **From** email address, paste the SendGrid **API Key** you copied, and click **Save**.

If you are using [passwordless authentication with email](/docs/authenticate/passwordless#email), the **From** email address value for your <Tooltip href="/docs/glossary?term=passwordless">passwordless</Tooltip> connection must match the **From** email address value you're using for SendGrid.

## Send a test email

Send a test email using the **Send Test Email** button. If the configuration is correct, you receive a confirmation email. If you do not receive an email after a few minutes, check your [Auth0 logs](https://manage.auth0.com/#/logs) for error codes.

Once configured, the SendGrid [Email Activity](https://sendgrid.com/logs/index) page displays delivery insights for all emails that have been sent to your users.


# Configure an Email Provider using SMTP Server Details
Source: https://auth0.com/docs/customize/email/smtp-email-providers/smtp-server

Instructions on how to configure an SMTP server as an email provider with Auth0.

You can configure your tenant with SMTP server details from an email provider or mail server you run.

<Callout icon="file-lines">
  If we support your email provider directly, we recommend using that integration (instead of SMTP server details) because it supports more secure authentication protocols.
</Callout>

## SMTP server requirements

The SMTP server must:

* Support [SMTP AUTH](https://en.wikipedia.org/wiki/SMTP_Authentication) with the LOGIN protocol.
* Support [TLS 1.2](https://en.wikipedia.org/wiki/STARTTLS) or higher.
* Have a certificate signed by a public certificate authority (CA).
* Allow inbound connections from [Auth0 IP addresses](/docs/secure/security-guidance/data-security/allowlist).

## Configure tenants with an SMTP server

You can configure your tenant with an SMTP server using the Auth0 Dashboard or using the Management API.

### Using the Auth0 Dashboard

To configure your tenant with an SMTP server using the Auth0 Dashboard:

1. Go to [Auth0 Dashboard > Branding > Email Provider](https://manage.auth0.com/#/branding/email-provider).
2. Enable the **Use my own email provider** toggle.
3. Select **SMTP**.
4. Enter a **From** email address, and then enter your SMTP server's **Host**, **Port**, **Username**, and **Password**.

   We recommend port 587 if available because it is the current default SMTP port and supports TLS. Some providers may require use of the older port 465. We recommend against port 25, the original SMTP port, because it is blocked by many providers and ISPs.
5. Click **Save**.

You can then send a test email by clicking the **Send Test Email** button. If you do not receive a confirmation email after a few minutes, check your [Auth0 logs](https://manage.auth0.com/#/logs) for any failures.

### Using the Management API

To configure your tenant with an SMTP server using the Management API, use the `/api/v2/emails/provider` endpoint.

* To configure an email provider for the first time, send a [`POST` request to `/api/v2/emails/provider`](/docs/api/management/v2/emails/post-provider).

* To update an existing email provider, send a [`PATCH` request to `/api/v2/emails/provider`](/docs/api/management/v2/emails/patch-provider). When changing the host, port, or username, you [must supply a password](/docs/troubleshoot/product-lifecycle/deprecations-and-migrations#allow-omitting-password-on-smtp-email-provider-host-related-changes).

## Additional considerations

* If you need support for authentication protocols other than LOGIN, you can [write an Action to connect to your SMTP server](/docs/customize/email/configure-a-custom-email-provider).

* In April 2026, Microsoft Exchange Online plans to [retire basic authentication for SMTH AUTH](https://techcommunity.microsoft.com/blog/exchange/exchange-online-to-retire-basic-auth-for-client-submission-smtp-auth/4114750), which affects the `smtp.office365.com` and `smtp-legacy.office365.com` endpoints.

  We recommend using our integrations for [Microsoft Office 365 Exchange Online](/docs/customize/email/smtp-email-providers/configure-365-exchange-as-smtp-email-provider) and [Azure Communication Services Email](/docs/customize/email/smtp-email-providers/configure-azure-comm-service-as-smtp-email-provider).


# Configure SparkPost as an Email Provider
Source: https://auth0.com/docs/customize/email/smtp-email-providers/sparkpost

Instructions on how to configure SparkPost as an email provider with Auth0.

## Prerequisites

* You must have a [SparkPost](https://www.sparkpost.com/) account.

* You must configure your provider to allow inbound connections from specific [Auth0 IP addresses](/docs/secure/security-guidance/data-security/allowlist).

## Configure SparkPost

1. Log in to your [SparkPost](https://www.sparkpost.com/) account.
2. Navigate to SparkPost [Sending Domains](https://app.sparkpost.com/account/sending-domains), and add your custom domain. SparkPost allows sending emails from only verified domains.
3. Navigate to SparkPost [Account API Keys](https://app.sparkpost.com/account/credentials), and click **New API key**. Save this key value and ensure it has `Transmissions: Read/Write` access. Copy this key value.
4. Navigate to Auth0 [Dashboard > Branding > Email Provider](https://manage.auth0.com/#/branding/email_provider).
5. Activate the **Use my own email provider** toggle.
6. Click the **SparkPost** logo.
7. Provide a **From** email address, enter the SparkPost **API Key** you previously copied, select your **Region**. If you are changing to the EU region in an account that was already configured for the US region, you must replace the **API Key** in Auth0 with a Sparkpost EU API Key.
8. Click **Save**.

## Send a test email

Send a test email using the **Send Test Email** button. If the configuration is correct, you receive a confirmation email. If you do not receive an email after a few minutes, check your [Auth0 logs](https://manage.auth0.com/#/logs) for error codes.

If you haven't registered a <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip> with SparkPost, you can send a maximum of five test emails from the `sparkpostbox.com` domain. For more details, see SparkPost's [Transmissions: The Sandbox Domain](https://developers.sparkpost.com/api/transmissions.html#header-the-sandbox-domain).

Once configured, the SparkPost [Message Events](https://app.sparkpost.com/reports/message-events) page displays delivery insights for all emails that have been sent to your users.


# Troubleshoot Email Provider Delivery Issues
Source: https://auth0.com/docs/customize/email/smtp-email-providers/troubleshooting

Steps to find and resolve email provider and email delivery issues.

If you have email delivery issues with an external email provider, try the troubleshooting options below.

## View email notification errors

If you have configured an external email provider but are not receiving notifications that emails are being sent, verify your provider configuration details in Auth0.

To view log data regarding email notification errors, go to [Dashboard > Monitoring > Logs](https://manage.auth0.com/#/logs) and filter results on the **Failed Sending Notification** event type.

## Review your infrastructure and domain configuration

Configure your email provider with the following authentication standards:

* DomainKeys Identified Mail ([DKIM](http://dkim.org/))
* Sender Policy Framework ([SPF](https://datatracker.ietf.org/doc/rfc7208/))
* Domain-based Message Authentication, Reporting, and Conformance ([DMARC](https://dmarc.org/))

You can use several tools to review the settings of DNS records relating to DKIM, SPF, and DMARC. Built-in command line tools like `dig` and `nslookup` can help you diagnose your MX records and other common routing issues.

Online tools like [MXToolBox](https://mxtoolbox.com/) and [DNSChecker](https://dnschecker.org/all-tools.php) can also analyze settings related to authentication standards and are helpful in identifying misconfigurations or changes needed in your email settings.

<Warning>
  The tools above are not maintained by or affiliated with Auth0.
</Warning>

## Troubleshoot Microsoft 365 Exchange Online issues

If you use Microsoft 365 Exchange Online as your email provider, your emails may be quarantined if Exchange deems them as high risk. This can happen when emails route from an outside source.

If Exchange quarantines messages, an administrator can view the messages in a special inbox and determine if there is a DMARC alignment failure, causing the messages to appear as spam.

## Troubleshoot SendGrid issues

If you use SendGrid as your email provider, your emails may be suppressed if the recipient's email server rejects the message. To learn more, read [Different Types of Suppression in SendGrid Docs](https://docs.sendgrid.com/ui/sending-email/index-suppressions#different-types-of-suppressions).

In certain cases, SendGrid will [drop a message](https://www.twilio.com/docs/sendgrid/glossary/drops) to a specific email address in order to protect your sender reputation.

If you are using [passwordless authentication with email](/docs/authenticate/passwordless#email), ensure that the **From** email address value for your <Tooltip href="/docs/glossary?term=passwordless">passwordless</Tooltip> connection matches the **From** email address value you're using for SendGrid.

## Contact Auth0 support

If you review your custom email provider settings and ensure your domain implements DKIM, SPF, and DMARC protocols and your email delivery is still failing, you may need to contact the Auth0 support team for review.

Our support team can verify if your email provider receives messages and the error returned if they are not accepted. To learn more, read [Open and Manage Support Tickets](/docs/troubleshoot/customer-support/open-and-manage-support-tickets).


# Internationalization and Localization
Source: https://auth0.com/docs/customize/internationalization-and-localization

Learn how to internationalize and localize emails, login prompts, and Lock password options.

You can handle different languages within your applications with Auth0. The following resources have references in more than one programming language:

* [Universal Login Internationalization](/docs/customize/internationalization-and-localization/universal-login-internationalization)
* [Lock: Internationalization](/docs/customize/internationalization-and-localization/lock-internationalization)
* [Lock.swift: Internationalization](/docs/customize/internationalization-and-localization/lock-swift-internationalization)
* [Lock.Android: Internationalization](/docs/customize/internationalization-and-localization/lock-android-internationalization)
* [Customize Translation of Lock Password Options](/docs/customize/internationalization-and-localization/password-options-translation)


# Lock.Android Internationalization
Source: https://auth0.com/docs/customize/internationalization-and-localization/lock-android-internationalization

Internationalization support in Lock.Android

By default, **Lock.Android** displays all text in English. If you wish to display text in another language, you may provide a `strings.xml` file and define values to be used for the various text items that Lock might display.

Android asks the device what locale was configured by the user and tries to fetch the list of localized texts for that language. For this to work, the developer needs to add each translation file into the app by using a special folder naming convention as per Android standards. More information can be found in the [Android developer docs](https://developer.android.com/training/basics/supporting-devices/languages).

Some of the default values provided by Lock include:

```xml lines theme={null}
<resources>
  <string name="com_auth0_lock_social_error_authentication">Error parsing Authentication data</string>
  <string name="com_auth0_lock_social_error_title">There was an error during authentication</string>
  ...
</resources>
```

By providing your own `strings.xml` file, these values can be adjusted as such:

```xml lines theme={null}
<resources>
  <string name="com_auth0_lock_social_error_authentication">There was an authentication error!</string>
  <string name="com_auth0_lock_social_error_title">Social login error!!</string>
  ...
</resources>
```

## Lock String Values

For a full list of the names used by Lock, see the [default strings.xml file](https://github.com/auth0/Lock.Android/blob/master/lib/src/main/res/values/strings.xml) in the Lock.Android repository.


# Lock Internationalization
Source: https://auth0.com/docs/customize/internationalization-and-localization/lock-internationalization

Lock v11 supports multiple languages, and allows for the addition of other custom language files, as well as for customizing the values of specific pieces of text that are displayed in the Lock widget.

You can change the language of Lock by using the `language` configuration option. This will pull the corresponding language file from the `i18n` directory in Lock.

## Provided languages

Take a look at the [i18n directory](https://github.com/auth0/lock/blob/master/src/i18n/) for language files.

<table>
  <thead>
    <tr>
      <th>Language</th>
      <th>Code</th>
      <th>Source</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Afrikaans</td>
      <td><code>'af'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/af.js">af.js</a></td>
    </tr>

    <tr>
      <td>Catalan</td>
      <td><code>'ca'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/ca.js">ca.js</a></td>
    </tr>

    <tr>
      <td>Chinese</td>
      <td><code>'zh'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/zh.js">zh.js</a></td>
    </tr>

    <tr>
      <td>Chinese (Taiwan)</td>
      <td><code>'zh-tw'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/zh-tw.js">zh-tw\.js</a></td>
    </tr>

    <tr>
      <td>Croatian</td>
      <td><code>'hr'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/hr.js">hr.js</a></td>
    </tr>

    <tr>
      <td>Czech</td>
      <td><code>'cs'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/cs.js">cs.js</a></td>
    </tr>

    <tr>
      <td>Danish</td>
      <td><code>'da'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/da.js">da.js</a></td>
    </tr>

    <tr>
      <td>Dutch</td>
      <td><code>'nl'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/nl.js">nl.js</a></td>
    </tr>

    <tr>
      <td>English</td>
      <td><code>'en'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/en.js">en.js</a></td>
    </tr>

    <tr>
      <td>Estonian</td>
      <td><code>'et'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/et.js">et.js</a></td>
    </tr>

    <tr>
      <td>Farsi (Persian)</td>
      <td><code>'fa'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/fa.js">fa.js</a></td>
    </tr>

    <tr>
      <td>Finnish</td>
      <td><code>'fi'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/fi.js">fi.js</a></td>
    </tr>

    <tr>
      <td>French</td>
      <td><code>'fr'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/fr.js">fr.js</a></td>
    </tr>

    <tr>
      <td>German</td>
      <td><code>'de'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/de.js">de.js</a></td>
    </tr>

    <tr>
      <td>Greek</td>
      <td><code>'el</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/el.js">el.js</a></td>
    </tr>

    <tr>
      <td>Hebrew</td>
      <td><code>'he'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/he.js">he.js</a></td>
    </tr>

    <tr>
      <td>Hungarian</td>
      <td><code>'hu'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/hu.js">hu.js</a></td>
    </tr>

    <tr>
      <td>Italian</td>
      <td><code>'it'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/it.js">it.js</a></td>
    </tr>

    <tr>
      <td>Japanese</td>
      <td><code>'ja'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/ja.js">ja.js</a></td>
    </tr>

    <tr>
      <td>Korean</td>
      <td><code>'ko'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/ko.js">ko.js</a></td>
    </tr>

    <tr>
      <td>Lithuanian</td>
      <td><code>'lt'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/lt.js">lt.js</a></td>
    </tr>

    <tr>
      <td>Norwegian</td>
      <td><code>'no'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/no.js">no.js</a></td>
    </tr>

    <tr>
      <td>Norwegian (Bokmål)</td>
      <td><code>'nb'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/nb.js">nb.js</a></td>
    </tr>

    <tr>
      <td>Norwegian (Nynorsk)</td>
      <td><code>'nn'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/nn.js">nn.js</a></td>
    </tr>

    <tr>
      <td>Polish</td>
      <td><code>'pl'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/pl.js">pl.js</a></td>
    </tr>

    <tr>
      <td>Portuguese (Brazil)</td>
      <td><code>'pt-br'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/pt-br.js">pt-br.js</a></td>
    </tr>

    <tr>
      <td>Romanian</td>
      <td><code>'ro'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/ro.js">ro.js</a></td>
    </tr>

    <tr>
      <td>Russian</td>
      <td><code>'ru'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/ru.js">ru.js</a></td>
    </tr>

    <tr>
      <td>Slovak</td>
      <td><code>'sk'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/sk.js">sk.js</a></td>
    </tr>

    <tr>
      <td>Slovenian</td>
      <td><code>'sl'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/sl.js">sl.js</a></td>
    </tr>

    <tr>
      <td>Spanish</td>
      <td><code>'es'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/es.js">es.js</a></td>
    </tr>

    <tr>
      <td>Swedish</td>
      <td><code>'sv'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/sv.js">sv.js</a></td>
    </tr>

    <tr>
      <td>Turkish</td>
      <td><code>'tr'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/tr.js">tr.js</a></td>
    </tr>

    <tr>
      <td>Ukrainian</td>
      <td><code>'ua'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/uk.js">ua.js</a></td>
    </tr>

    <tr>
      <td>Vietnamese</td>
      <td><code>'vi'</code></td>
      <td><a href="https://github.com/auth0/lock/blob/master/src/i18n/vi.js">vi.js</a></td>
    </tr>
  </tbody>
</table>

## Set language option

To use the following examples, you'll need to first include Lock in your page:

`<script src="https://cdn.auth0.com/js/lock/11.14/lock.min.js"></script>`

Next define your `options` object and include the `language` option. The `language` option needs to be a string matching the name of the corresponding file in the `i18n` directory [within Lock](https://github.com/auth0/lock/tree/master/src/i18n). Then instantiate Lock.

<AuthCodeBlock />

Translation data for Lock comes from language files which have key-value pairs representing various translations. For some languages, certain values may be missing, in which case you will see a warning: `language does not have property <missing prop>`. We encourage you to submit a [pull request](https://github.com/auth0/lock/tree/master/src/i18n) to add these missing values. Alternatively, you may define the missing values in your Lock `options` (see below).

## Replace dictionary terms

You can also customize your own specific dictionary items using the `languageDictionary` option. This is useful if you are using one of the supported languages, but change the specific wording of a few items. For example, you might re-word the `title` or change the way other labels display to the user while leaving the remaining text on the widget intact.

<AuthCodeBlock />

For an example of available `languageDictionary` property names and how to structure a `language` file, see the [English dictionary file for Lock](https://github.com/auth0/lock/blob/master/src/i18n/en.js).

The `languageBaseUrl` option, which takes a string value (a URL), overrides the language source URL for Auth0's provided translations. By default, it uses the Auth0's CDN URL `https://cdn.auth0.com` because that is where the provided language translations are stored. By providing another value, you can use your own source for the language translations as needed for your applications. Your language source should be a JavaScript file.


# Lock.swift Internationalization
Source: https://auth0.com/docs/customize/internationalization-and-localization/lock-swift-internationalization

Internationalization support in Lock.Swift

By default, **Lock v2 for iOS** displays all text in English. If you wish to display text in another language, or you wish to alter the text values for your application, you may provide a `Lock.strings` file and define values to be used for the various text items that Lock might display.

More information about how to handle languages can be found in the official Apple documentation on [Internationalization and Localization](https://developer.apple.com/library/content/documentation/MacOSX/Conceptual/BPInternational/Introduction/Introduction.html#//apple_ref/doc/uid/10000171i-CH1-SW1)

## Lock String Values

For a full list of the terms used by Lock, see the base [Lock.strings](https://raw.githubusercontent.com/auth0/Lock.swift/master/Lock/Base.lproj/Lock.strings) file in the Lock.swift repository.

### Providing alternative English strings

If you want to change some or all of the existing terms, you can do this by downloading and adding the [Lock.strings](https://raw.githubusercontent.com/auth0/Lock.swift/master/Lock/Base.lproj/Lock.strings) file to your project.

Select the **Lock.strings** file and in the `File inspector` click on `Localize...`

<Frame>
  <img alt="Lock.swift: Localize" />
</Frame>

Then select `English`:

<Frame>
  <img alt="Lock.swift: Localize English" />
</Frame>

Now lets take a couple of terms in **Lock.strings** and update them with alternative text:

`// Forgot password
"com.auth0.lock.database.button.forgot_password" = "Did you forget your password?";
// tos & privacy
"com.auth0.lock.database.button.tos" = "Signing up is an indication of your agreement to our terms of\n service and privacy policy";`

### Supporting other languages

To add another language you first of all need to add the new language under `Project/Info`

<Frame>
  <img alt="Lock.swift: Add language" />
</Frame>

Add the new language and ensure that **Lock.strings** is selected

<Frame>
  <img alt="Lock.swift: Add Language step 2" />
</Frame>

You will notice under **Lock.strings** a new file has been created for your specified language, based upon the **Reference Language** selection.

Now you are ready to translate to your desired language.

### Notes

Some terms use parameters and it's important to note their placement in your translation. In particular multiple parameter terms such as:

`// No more than %@{count} identical characters in a row (such as, \"%@{identical sample}\" not allowed)
"com.auth0.lock.error.password.no_more_identical" = "No more than %1$d identical characters in a row (such as, \"%2$@\" not allowed)";`


# Customize Translation of Lock Password Options
Source: https://auth0.com/docs/customize/internationalization-and-localization/password-options-translation

Learn how to customize the translation of Lock password options.

You can customize the translation of the following Lock password features in your own code:

* Password Strength
* Password History
* Change Password widget

To customize any of these features, you must include version 1.1 or higher of the Change Password widget library:

`<script src="https://cdn.auth0.com/js/change-password-1.1.min.js"></script>`

To translate the text of each of the Lock password features, include the following code, replacing all strings with text in the desired language:

### Password Strength

```js lines theme={null}
dict: {
    passwordStrength: {
      containsAtLeast: "Contain at least %d of the following %d types of characters:",
      identicalChars: "No more than %d identical characters in a row (such as, \"%s\" not allowed)",
      nonEmpty: "Non-empty password required",
      numbers: "Numbers (such as 0-9)",
      lengthAtLeast: "At least %d characters in length",
      lowerCase: "Lower case letters (a-z)",
      shouldContain: "Should contain:",
      specialCharacters: "Special characters (such as !@#$%^&*)",
      upperCase: "Upper case letters (A-Z)"
    }
}
```

### Password History

```js lines theme={null}
dict: {
  passwordHistoryError: "Password has previously been used"
}
```

### Change Password widget

```js lines theme={null}
dict: {
    passwordPlaceholder: "your new password",
    passwordConfirmationPlaceholder: "confirm your new password",
    passwordConfirmationMatchError: "Please ensure the password and the confirmation are the same.",
    successMessage: "Your password has been reset successfully.",
    configurationError: "An error occurred. There appears to be a misconfiguration in the form.",
    networkError: "The server cannot be reached, there is a problem with the network.",
    timeoutError: "The server cannot be reached, please try again.",
    serverError: "There was an error processing the password reset.",
    headerText: "Enter a new password for<br />{email}",
    title: "Change Password",
    weakPasswordError: "Password is too weak."
}
```


# Universal Login Internationalization
Source: https://auth0.com/docs/customize/internationalization-and-localization/universal-login-internationalization

Describes the languages you can choose to localize your login pages.

## Universal Login localization

The <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> experience is localized to the following languages. Entries marked with an asterisk are read right to left.

<table>
  <thead>
    <tr>
      <th><strong>Language</strong></th>
      <th><strong>Code</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Albanian</td>
      <td><code>sq</code></td>
    </tr>

    <tr>
      <td>Amharic</td>
      <td><code>am</code></td>
    </tr>

    <tr>
      <td>Arabic\*</td>
      <td><code>ar</code></td>
    </tr>

    <tr>
      <td>Arabic (Egypt)\*</td>
      <td><code>ar-EG</code></td>
    </tr>

    <tr>
      <td>Arabic (Saudi Arabia)\*</td>
      <td><code>ar-SA</code></td>
    </tr>

    <tr>
      <td>Armenia</td>
      <td><code>hy</code></td>
    </tr>

    <tr>
      <td>Azerbaijani</td>
      <td><code>az</code></td>
    </tr>

    <tr>
      <td>Basque</td>
      <td><code>eu-ES</code></td>
    </tr>

    <tr>
      <td>Bengali</td>
      <td><code>bn</code></td>
    </tr>

    <tr>
      <td>Bosnian</td>
      <td><code>bs</code></td>
    </tr>

    <tr>
      <td>Bulgarian</td>
      <td><code>bg</code></td>
    </tr>

    <tr>
      <td>Catalan</td>
      <td><code>ca-ES</code></td>
    </tr>

    <tr>
      <td>Chinese - Hong Kong</td>
      <td><code>zh-HK</code></td>
    </tr>

    <tr>
      <td>Chinese - Simplified</td>
      <td><code>zh-CN</code></td>
    </tr>

    <tr>
      <td>Chinese - Traditional</td>
      <td><code>zh-TW</code></td>
    </tr>

    <tr>
      <td>Croatian</td>
      <td><code>hr</code></td>
    </tr>

    <tr>
      <td>Czech</td>
      <td><code>cs</code></td>
    </tr>

    <tr>
      <td>Danish</td>
      <td><code>da</code></td>
    </tr>

    <tr>
      <td>Dutch</td>
      <td><code>nl</code></td>
    </tr>

    <tr>
      <td>English</td>
      <td><code>en</code></td>
    </tr>

    <tr>
      <td>English - Canada</td>
      <td><code>en-CA</code></td>
    </tr>

    <tr>
      <td>Estonian</td>
      <td><code>et</code></td>
    </tr>

    <tr>
      <td>Farsi (Persian)\*</td>
      <td><code>fa</code></td>
    </tr>

    <tr>
      <td>Finnish</td>
      <td><code>fi</code></td>
    </tr>

    <tr>
      <td>French</td>
      <td><code>fr-FR</code></td>
    </tr>

    <tr>
      <td>French - Canada</td>
      <td><code>fr-CA</code></td>
    </tr>

    <tr>
      <td>Galician</td>
      <td><code>gl-ES</code></td>
    </tr>

    <tr>
      <td>Georgian</td>
      <td><code>ka</code></td>
    </tr>

    <tr>
      <td>German</td>
      <td><code>de</code></td>
    </tr>

    <tr>
      <td>Greek</td>
      <td><code>el</code></td>
    </tr>

    <tr>
      <td>Gujrati</td>
      <td><code>gu</code></td>
    </tr>

    <tr>
      <td>Hebrew\*</td>
      <td><code>he</code></td>
    </tr>

    <tr>
      <td>Hindi</td>
      <td><code>hi</code></td>
    </tr>

    <tr>
      <td>Hungarian</td>
      <td><code>hu</code></td>
    </tr>

    <tr>
      <td>Icelandic</td>
      <td><code>is</code></td>
    </tr>

    <tr>
      <td>Indonesian</td>
      <td><code>id</code></td>
    </tr>

    <tr>
      <td>Italian</td>
      <td><code>it</code></td>
    </tr>

    <tr>
      <td>Japanese</td>
      <td><code>ja</code></td>
    </tr>

    <tr>
      <td>Kannada</td>
      <td><code>kn</code></td>
    </tr>

    <tr>
      <td>Korean</td>
      <td><code>ko</code></td>
    </tr>

    <tr>
      <td>Latvian</td>
      <td><code>lv</code></td>
    </tr>

    <tr>
      <td>Lithuanian</td>
      <td><code>lt</code></td>
    </tr>

    <tr>
      <td>Macedonian</td>
      <td><code>mk</code></td>
    </tr>

    <tr>
      <td>Malay</td>
      <td><code>ms</code></td>
    </tr>

    <tr>
      <td>Malayalam</td>
      <td><code>ml</code></td>
    </tr>

    <tr>
      <td>Marathi</td>
      <td><code>mr</code></td>
    </tr>

    <tr>
      <td>Mongolian</td>
      <td><code>mn</code></td>
    </tr>

    <tr>
      <td>Montenegrine</td>
      <td><code>cnr</code></td>
    </tr>

    <tr>
      <td>Myanmar</td>
      <td><code>my</code></td>
    </tr>

    <tr>
      <td>Norwegian</td>
      <td><code>no</code></td>
    </tr>

    <tr>
      <td>Norwegian - Bokmål</td>
      <td><code>nb</code></td>
    </tr>

    <tr>
      <td>Norwegian - Nynorsk</td>
      <td><code>nn</code></td>
    </tr>

    <tr>
      <td>Polish</td>
      <td><code>pl</code></td>
    </tr>

    <tr>
      <td>Portuguese - Brazil</td>
      <td><code>pt-BR</code></td>
    </tr>

    <tr>
      <td>Portuguese - Portugal</td>
      <td><code>pt-PT</code></td>
    </tr>

    <tr>
      <td>Punjabi</td>
      <td><code>pa</code></td>
    </tr>

    <tr>
      <td>Romanian</td>
      <td><code>ro</code></td>
    </tr>

    <tr>
      <td>Russian</td>
      <td><code>ru</code></td>
    </tr>

    <tr>
      <td>Serbian</td>
      <td><code>sr</code></td>
    </tr>

    <tr>
      <td>Slovak</td>
      <td><code>sk</code></td>
    </tr>

    <tr>
      <td>Slovenian</td>
      <td><code>sl</code></td>
    </tr>

    <tr>
      <td>Somali</td>
      <td><code>so</code></td>
    </tr>

    <tr>
      <td>Spanish</td>
      <td><code>es</code></td>
    </tr>

    <tr>
      <td>Spanish - Argentina</td>
      <td><code>es-AR</code></td>
    </tr>

    <tr>
      <td>Spanish - Latin America</td>
      <td><code>es-419</code></td>
    </tr>

    <tr>
      <td>Spanish - Mexico</td>
      <td><code>es-MX</code></td>
    </tr>

    <tr>
      <td>Swahili</td>
      <td><code>sw</code></td>
    </tr>

    <tr>
      <td>Swedish</td>
      <td><code>sv</code></td>
    </tr>

    <tr>
      <td>Tagalog</td>
      <td><code>tl</code></td>
    </tr>

    <tr>
      <td>Tamazight</td>
      <td><code>zgh</code></td>
    </tr>

    <tr>
      <td>Tamil</td>
      <td><code>ta</code></td>
    </tr>

    <tr>
      <td>Telugu</td>
      <td><code>te</code></td>
    </tr>

    <tr>
      <td>Thai</td>
      <td><code>th</code></td>
    </tr>

    <tr>
      <td>Turkish</td>
      <td><code>tr</code></td>
    </tr>

    <tr>
      <td>Ukrainian</td>
      <td><code>uk</code></td>
    </tr>

    <tr>
      <td>Urdu\*</td>
      <td><code>ur</code></td>
    </tr>

    <tr>
      <td>Vietnamese</td>
      <td><code>vi</code></td>
    </tr>

    <tr>
      <td>Welsh</td>
      <td><code>cy</code></td>
    </tr>
  </tbody>
</table>

### Language selection

The language to render the pages will be selected based on:

* The languages supported by Auth0, which are listed above.
* The list of languages configured in the Dashboard's [Tenant Settings](https://manage.auth0.com/#/tenant) section, where you can select the languages your tenant supports and select a default one. By default, the list has only English selected, but you can select the ones you need.
* The value of the `ui_locales` parameter sent to the [Authorization Request endpoint](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest), which can be used to constrain the language list for an application or session. You can provide a space-delimited list of locales. The first locale on the list must match the enabled locale in your tenant to reflect in the UI.
* The `Accept-Language` HTTP header sent by the browser. The pages will be rendered in this language if it is allowed by the settings above. If not, pages will be rendered in the default language.

To add a language that's not listed above, use the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to make a `PATCH` call to the [Tenants endpoint](https://auth0.com/docs/api/management/v2/tenants/patch-settings) with the following body, replacing `he` with the language code you want to add:

```json lines theme={null}
{
  "enabled_locales": [
    "en","he"
  ]
}
```

After it's added, specify the language in the`ui_locales` query parameter of the login request.

You can also specify the enabled languages for the tenant via the Management API using the [Update Tenant Settings endpoint](https://auth0.com/docs/api/management/v2#!/Tenants/patch_settings). The first language in the list will be the default one.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/tenants/settings' \
    --header 'authorization: Bearer API2_ACCESS_TOKEN' \
    --header 'content-type: application/json' \
    --data '{ "enabled_locales" : [ "en", "es"]}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/tenants/settings");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer API2_ACCESS_TOKEN");
  request.AddParameter("application/json", "{ "enabled_locales" : [ "en", "es"]}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/tenants/settings"

  	payload := strings.NewReader("{ "enabled_locales" : [ "en", "es"]}")

  	req, _ := http.NewRequest("PATCH", url, payload)

  	req.Header.Add("content-type", "application/json")
  	req.Header.Add("authorization", "Bearer API2_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/tenants/settings")
    .header("content-type", "application/json")
    .header("authorization", "Bearer API2_ACCESS_TOKEN")
    .body("{ "enabled_locales" : [ "en", "es"]}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/tenants/settings',
    headers: {'content-type': 'application/json', authorization: 'Bearer API2_ACCESS_TOKEN'},
    data: {enabled_locales: ['en', 'es']}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer API2_ACCESS_TOKEN" };
  NSDictionary *parameters = @{ @"enabled_locales": @[ @"en", @"es" ] };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/tenants/settings"]
                                                         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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/tenants/settings",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "PATCH",
    CURLOPT_POSTFIELDS => "{ "enabled_locales" : [ "en", "es"]}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer API2_ACCESS_TOKEN",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "enabled_locales" : [ "en", "es"]}"

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer API2_ACCESS_TOKEN"
      }

  conn.request("PATCH", "/{yourDomain}/api/v2/tenants/settings", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/tenants/settings")

  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 API2_ACCESS_TOKEN'
  request.body = "{ "enabled_locales" : [ "en", "es"]}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer API2_ACCESS_TOKEN"
  ]
  let parameters = ["enabled_locales": ["en", "es"]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/tenants/settings")! 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()
  ```
</AuthCodeGroup>

### Right-to-left languages

<Callout icon="file-lines">
  Right-to-left text is currently in Early Access. To request this feature, [contact Auth0 Support](https://support.auth0.com/center/s/), and to learn more about Auth0's product release cycle, read [Product release stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Callout>

Right-to-left (RtL) language support allows your tenant to display Arabic (standard, Egyptian, and Saudi Arabian), Persian, Hebrew, and Urdu text. Tenants that use RtL text must be [WCAG 2.2 AA compliant](/docs/authenticate/login/auth0-universal-login#accessibility), and if your tenant uses page templates, you must update the HTML tag to include the `dir` element.

```liquid lines theme={null}
{% assign resolved_dir = dir | default: "auto" %}
<html lang="{{locale}}" dir="{{resolved_dir}}">
```

### Limitations

* The `ui_locales` parameter can only be used in <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> flows, as it’s not available in <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> or WS-Federation.
* The `ui_locales` parameter is not forwarded to upstream <Tooltip href="/docs/glossary?term=IdPs">IdPs</Tooltip>. To learn more about passing parameters to IdPs, read [Pass Parameters to Identity Providers](/docs/authenticate/identity-providers/pass-parameters-to-idps).
* It is not possible to localize the scopes in the Consent page.

### Known issues

* The ULP renders the HTML `lang` attribute for the language code `fr-FR` as `fr`.
* The ULP renders the HTML `lang` attribute for the language code `pt-PT` as `pt`.

## Classic Login localization

In the Classic Login experience, localization is done using our JavaScript widgets for [login](/docs/customize/internationalization-and-localization/lock-internationalization), the [password reset page](/docs/customize/login-pages/classic-login/customize-password-reset-page) and [password policies](/docs/customize/internationalization-and-localization/password-options-translation).

The [MFA page](/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-classic-login) by default uses the Auth0 <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> Widget, which cannot be localized. You can create localized versions by using [guardian.js](https://github.com/auth0/auth0-guardian.js).

It is not possible to localize the Consent page.

## Learn more

* [Customize Universal Login Page Templates](/docs/customize/login-pages/universal-login/customize-templates)
* [Customize Classic Login Pages with Lock or SDK](/docs/customize/login-pages/classic-login/customize-with-lock-sdk)


# Create a theme with Tailwind
Source: https://auth0.com/docs/customize/login-pages/advanced-customizations/acul-use-cases/create-theme-tailwind

Learn how to create a theme using tailwind CSS with ACUL

<Card title="Before you start">
  You need:

  * An Auth0 development tenant configured with [Universal Login](/docs/authenticate/login/auth0-universal-login) and a [custom domain](/docs/customize/custom-domains).
  * An Auth0 [First Party Application](/docs/get-started/auth0-overview/create-applications#create-applications).
  * Enable [Identifier First Authentication](/docs/authenticate/login/auth0-universal-login/identifier-first) in your Auth0 tenant.
  * [Node.js](http://Node.js) V22+
  * The [Auth0 CLI Tool](https://github.com/auth0/auth0-cli) [authenticated to your existing tenant](https://github.com/auth0/auth0-cli?tab=readme-ov-file#authenticating-to-your-tenant).
  * To review the [ACUL Quickstart guide](/docs/customize/login-pages/advanced-customizations/quickstart)
</Card>

Universal Login provides a number of [prompts](/docs/customize/login-pages/universal-login/customize-signup-and-login-prompts#terminology), or steps in the authentication process, each step includes at least one screen. You can use ACUL to apply a theme to all your custom screens.

For example:

<Frame>![login-id reference screenshot](https://cdn2.auth0.com/docs/1.14516.0/media/articles/universal-login/text-customization/login-id.png)</Frame>

You can apply a theme to this Login screen using [Tailwind CSS v4](https://tailwindcss.com/docs/installation/using-vite).

All theme and branding customizations are located in ACUL project `src/index.css` directory.

1. Use the Auth0 CLI tool to create an ACUL project with the screens to apply a new theme.

```bash theme={null}
auth0 acul init <Your-App-Name>
```

2. Edit the CSS file `src/index.css`.

```css theme={null}
/* In src/index.css */
:root {
  /* Change these CSS variables to match your brand's primary color */
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);

  /* Override the theme variables to reference your custom color*/  
  --color-primary-button: var(--ul-theme-color-primary-button);

  /* You can also override specific component colors directly */
  --color-header: var(--primary-foreground);
  --color-body-text: #000000;
  --color-widget-bg: white;
  --color-widget-border: transparent;
  /* ... and many more */
}
```

<Callout icon="file-lines">
  CSS variables in the `@theme inline` block are used by the base components.
  CSS variables prefixed with `--ul-theme-` are set to the default Universal Login styling and are automatically overridden by the Branding theme set in your tenant at runtime. To learn more, read the `src/utils/theme/themeEngine.ts` file in your project's directory.
</Callout>


# Integrate a Custom Component Library
Source: https://auth0.com/docs/customize/login-pages/advanced-customizations/acul-use-cases/integrate-custom-component

Learn how to integrate a custom component library with ACUL

<Card title="Before you start">
  You need:

  * An Auth0 development tenant configured with [Universal Login](/docs/authenticate/login/auth0-universal-login) and a [custom domain](/docs/customize/custom-domains).
  * An Auth0 [First Party Application](/docs/get-started/auth0-overview/create-applications#create-applications).
  * Enable [Identifier First Authentication](/docs/authenticate/login/auth0-universal-login/identifier-first) in your Auth0 tenant.
  * [Node.js](http://Node.js) V22+
  * The [Auth0 CLI Tool](https://github.com/auth0/auth0-cli) [authenticated to your existing tenant](https://github.com/auth0/auth0-cli?tab=readme-ov-file#authenticating-to-your-tenant).
  * To review the [ACUL Quickstart guide](/docs/customize/login-pages/advanced-customizations/quickstart)
</Card>

With ACUL, you can use your choice of component libraries to customize your Universal Login prompt screens. The following examples uses [Shadcn](https://ui.shadcn.com/docs), a library of reusable components and the Auth0 `login-passwordless-email-code` screen. In this example, replace the default OTP input with Shadcn’s [InputOTP](https://ui.shadcn.com/docs/components/input-otp) component.

1. Use the Auth0 CLI tool to create an ACUL project.

```bash theme={null}
auth0 acul init <Your-App-Name>
```

Select the `login-passwordless-email-code` screen

2. Run the ACUL local development server to edit and view your screen updates.

```bash theme={null}
auth0 acul dev
```

3. Initialize Shadcn in the root of your project:

```bash theme={null}
npx shadcn-ui@latest init
```

4. Follow the CLI prompts to create the `components.json` file to hold the configuration for your project and a `src/lib/utils.ts` file.

5. Add the component files to `src/components/ui/input-otp.tsx`:

```bash theme={null}
npx shadcn-ui@latest add input-otp
```

6. Integrate the component:
   a. Navigate to `src/screens/login-passwordless-email-code/components/IdentifierForm.tsx` and open the file.
   b. Import the InputOTP components and replace the existing input field. You also need to manage the state of the OTP code and use the correct SDK hook.

```bash theme={null}
// In IdentifierForm.tsx
import { useState } from 'react';
import { useEmailOtpChallenge } from '@auth0/auth0-acul-react'; 
import {
  InputOTP,
  InputOTPGroup,
  InputOTPSlot,
} from '@/components/ui/input-otp'; // Import from ShadCN

// ... inside your component
const { submit } = useEmailOtpChallenge(); 
const [otp, setOtp] = useState('');

const handleSubmit = (e) => {
  e.preventDefault();
  submit({ code: otp }); // Call the submit method with the code
};

return (
  <form onSubmit={handleSubmit}>
    {/* ... other UI elements ... */}
    <InputOTP maxLength={6} value={otp} onChange={setOtp}>
      <InputOTPGroup>
        <InputOTPSlot index={0} />
        <InputOTPSlot index={1} />
        <InputOTPSlot index={2} />
        <InputOTPSlot index={3} />
        <InputOTPSlot index={4} />
        <InputOTPSlot index={5} />
      </InputOTPGroup>
    </InputOTP>
    <Button type="submit">Verify Code</Button>
  </form>
);
```

7. Run the screen locally with the ACUL Context Inspector to see your new component:

```bash theme={null}
auth0 acul dev -s  login-passwordless-email-code
```

8. Connect your local dev environment to your test tenant to try the new screen in a live authentication flow:

```bash theme={null}
auth0 acul dev --connected --screen login-passwordless-email-code
```

9. Follow the prompts to build your local assets, start the local dev server, and update the ACUL configuration on your tenant.

10. Test the passwordless authentication flow:

```bash theme={null}
auth0 test login
```


# Migrate from Classic Login to Universal Login with ACUL
Source: https://auth0.com/docs/customize/login-pages/advanced-customizations/acul-use-cases/migrate-classic-universal-login

Describes how to migrate from Classic Login to Universal Login with ACUL.

<Warning>
  At this time, Auth0’s active development efforts are focused on Universal Login, and Classic Login no longer receives updates. Unless your specific use case requires the Classic experience, implementing Universal Login is recommended.
  For a feature comparison between login experiences, review [Universal Login vs. Classic Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login).
</Warning>

We recommend migrating your [Classic Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/classic-experience#classic-login-experience) screen implementation to [Universal Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience) using [Advanced Customizations for Universal Login (ACUL)](/docs/customize/login-pages/advanced-customizations#advanced-customizations-for-universal-login-acul).

<Card title="Before you start">
  You need:

  * An Auth0 development tenant configured with [Universal Login](/docs/authenticate/login/auth0-universal-login) and a [custom domain](/docs/customize/custom-domains).
  * [Auth0 CLI](https://auth0.github.io/auth0-cli/) installed and configured with your development tenant.
  * A [GitHub](https://github.com/) repository to contain your ACUL custom loign screens.
  * An inventory of your Classic Login experience assets:
    * UI components.
    * CSS/theme tokens and brand assets.
    * Validation rules (email format, required fields).
    * Error handling behavior.
</Card>

## Initialize an ACUL project

<Callout icon="file-lines">
  If you have not configured your development tenant with Auth0 CLI, use the [auth0 login](https://auth0.github.io/auth0-cli/auth0_login.html) command.
</Callout>

Navigate to a location to build your ACUL project and run the following command:

```bash theme={null}
auth0 acul init acul-login --screens login-id,login-password
```

Auth0 CLI initializes your project with pre-built `login-id` and `login-password` authentication screens.

To learn more, read [auth0 aclu on GitHub](https://auth0.github.io/auth0-cli/auth0_acul_init.html).

## Customize ACUL screens

Customize the `login-id` and `login-password` screens to align to your organization standards.

You should consider the following:

* Reuse existing CSS/theme and React components.
* Apply branding (assets, typography, layout).
* Add basic client-side validation (email required/format; password required).
* Standardize error presentation (consistent and accessible).

You can develop your ACUL screens locally to customize them using the command:

```bash theme={null}
auth0 acul dev
```

To learn more, read [ACUL Development Workflow](/docs/customize/login-pages/advanced-customizations/development-workflowhttps://auth0.com/docs/customize/login-pages/advanced-customizations/development-workflow).

## Validate the ACUL migration

To validate the user end-to-end login experience, you can use the [auth0 acul](https://auth0.github.io/auth0-cli/auth0_acul_dev.html) command:

```bash theme={null}
auth0 acul dev --connected
```

You need to test and ensure the following:

* The authentication flow uses your custom UI for the `login-id` and `login-password` screens and that they display correctly.
* Wrong password and other server-side error messages are clearly rendered.
* Users are successfully redirected back to your application.
* Email validation, if enabled, behaves as expected.

To learn more, read [ACUL live tenant integration testing](/docs/customize/login-pages/advanced-customizations/development-workflow#live-tenant-integration-testing).

## Deploy ACUL screens to production tenant

The ACUL screen project includes a deployment setup you can use, as a starting point, to deploy your screens to production.

The ACUL deployment steps include:

* Building your screen asset bundles.
* Publishing them to your CDN.
* Enabling ACUL to your Auth0 production tenant.

To learn more, read [ACUL Deployment workflow](/docs/customize/login-pages/advanced-customizations/deployment-workflow).

## Cutover and rollback strategy

Unless you are using a proxy to direct traffic to different tenants, migration from Classic to Universal Login can not be done in a gradual rollout.

For single tenant migrations, we suggest treating it as a controlled production change:

* Complete staging validation.
* Cut over during a planned window.
* Have a clear rollback strategy and procedure.

If your organization requires a progressive rollout, you need two tenants and a proxy server:

<Warning>
  This is an architectural strategy, not a built-in Auth0 feature, and should be reviewed with your security and networking teams.
</Warning>

* Tenant A: current Classic Login.
* Tenant B: Universal Login with ACUL enabled.
* Use a proxy/traffic-splitting layer to route a percentage of authorization traffic to Tenant B and ramp up over time.

## Learn more

* [Advanced Customizations for Universal Login (ACUL)](/docs/customize/login-pages/advanced-customizations)

* [ACUL React SDK Reference Documentation](docs/libraries/acul/react-sdk)

* [Auth0 CLI Reference Documentation](https://auth0.github.io/auth0-cli/auth0_acul.html)

* [ACUL Sample Application](https://github.com/auth0-samples/auth0-acul-samples)


# ACUL SDKs and Resources
Source: https://auth0.com/docs/customize/login-pages/advanced-customizations/reference

Learn about ACUL SDKs and resources

Auth0 supplies a choice of SDKs to use with ACUL.

## ACUL SDKs

* [Auth0 ACUL React SDK](/docs/libraries/acul/react-sdk)
  Provides React Hooks to simplify integration within React applications.

* [Auth0 ACUL JS SDK](/docs/libraries/acul/js-sdk)
  The core JavaScript library (written in Typescript), suitable for use with any frontend framework or plain JavaScript.

## ACUL sample applications

The [ACUL sample applications](https://github.com/auth0-samples/auth0-acul-samples) include a full build pipeline, deployment workflows, and implementations for common Universal Login screens. These sample applications assist you in the development of your screens. The samples are available in React using the ACUL React and JS SDKs.

You can use the `auth0 acul init` command to initialize a starter React project with either the ACUL React or JS SDKs. To learn more, read [Auth0 CLI](https://github.com/auth0/auth0-cli) on GitHub.

## ACUL resources

Auth0 provides several resources to customize your Universal Login experience.

### Auth0 Management API

Update individual Universal Login screens or configure multiple screens at once with Management API. To use Auth0 Management API, you must have an [access token](/docs/secure/tokens/access-tokens/management-api-access-tokens).

**Individual screen configuration**

* The [`GET /v2/prompts/{prompt}/screen/{screen}/rendering` endpoint](/docs/api/management/v2/prompts/get-rendering) allows you to retrieve the configuration for a single screen.

* The [`PATCH /v2/prompts/{prompt}/screen/{screen}/rendering` endpoint](/docs/api/management/v2/prompts/patch-rendering) allows you to configure ACUL on a single screen.

**Bulk screen configuration**

* The [`GET /v2/prompts/rendering` endpoint](/docs/api/management/v2/prompts/get-all-rendering) allows you to retrieve configurations for all the screens.

* The [`PATCH /v2/prompts/rendering` endpoint](/docs/api/management/v2/prompts/patch-bulk-rendering) allows you to update screens in bulk.

### Auth0 developer tools

Auth0 provides several tools to simplify tenant management including ACUL configuration.

* **Auth0 CLI**<p />
  Use the `acul` commands to scaffold projects, develop locally, and  deploy your screen configurations. To learn more, read [Auth0 CLI](https://github.com/auth0/auth0-cli) on GitHub.

* **Auth0 Deploy CLI**<p />
  Manage your entire tenant configuration as code, including ACUL rendering settings defined in JSON files. To learn more, read [Auth0 Deploy CLI](https://github.com/auth0/auth0-deploy-cli) on GitHub.

* **Auth0 Terraform provider**<p />
  Define your ACUL screen configurations . To learn more, read [`promt_screen_renderer resource`](https://registry.terraform.io/providers/auth0/auth0/latest/docs/resources/prompt_screen_renderer) on Terraform.


# Customize Phone Messages
Source: https://auth0.com/docs/customize/phone-messages

Learn how to customize your phone message flow in the Auth0 Dashboard.

Auth0’s default phone message flow addresses the requirements of most applications. You may want to customize your phone message flow, such as in the following use cases:

* Localize your phone messages to meet the needs of different target markets.
* Set a custom sending phone number or select a different phone message provider based on the custom domain or region.
* Enable different phone message templates per application, tenant, or custom domain.

The [Auth0 Management API](https://auth0.com/docs/api/management/v2) provides endpoints to help you manage your phone message flow to control when and how phone messages are sent. You can also implement and manage your own custom phone endpoints using the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## Learn more

* [Configure Phone Messaging Providers](/docs/customize/phone-messages/configure-phone-messaging-providers)
* [Customize Phone Templates](/docs/customize/phone-messages/customize-phone-templates)


# Configure Phone Messaging Providers
Source: https://auth0.com/docs/customize/phone-messages/configure-phone-messaging-providers

Learn how to configure phone messaging providers in the Auth0 Dashboard.

<Callout icon="file-lines">
  Phone messaging providers are currently in Early Access. To learn more about Auth0 releases, review [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Callout>

Auth0 allows you to configure your own phone messaging provider to help you manage, monitor, and troubleshoot your SMS and voice communications. You can only configure one phone provider for all SMS and voice communications per tenant.

Auth0 currently supports the following phone messaging providers:

* [Twilio](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-twilio-as-a-phone-messaging-provider)
* [Custom phone provider](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider)

You can also configure a custom phone provider using Actions. To learn more, read [Configure a Custom Phone Provider](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider) and [Actions Triggers: custom-phone-provider Event Object](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider/actions-triggers-custom-phone-provider-event-object).

\~Auth0

## Learn more

* [Configure Twilio as a Phone Messaging Provider](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-twilio-as-a-phone-messaging-provider)


# Configure a Custom Phone Provider
Source: https://auth0.com/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider

Learn how to configure a custom phone provider using Actions

You can configure a custom phone provider for SMS messages using a [phone number as a user identifier](/docs/authenticate/database-connections/activate-and-configure-attributes-for-flexible-identifiers). A custom phone provider uses [Actions](/docs/customize/actions/actions-overview) to route the SMS messages to a phone provider of your choice when verifying phone numbers and resetting passwords.

You may want to configure a custom phone provider for the following use cases:

* Use different phone providers based on application context, which may include different geographic regions where phone provider message prices can vary significantly.
* Use different phone providers based on organization context, where some B2B customers may require specific providers.

You can configure a custom phone provider with the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## Configure a custom phone provider with the Auth0 Dashboard or Management API

To configure a custom phone provider, you must use the `custom-phone-provider` Action trigger that is not available in the Auth0 Actions editor. To learn more, read [Example custom-phone-provider Action](#example-custom-phone-provider-action).

<Tabs>
  <Tab title="Auth0 Dashboard">
    #### Add a custom phone provider with the Auth0 Dashboard

    To configure a new custom phone provider in the Auth0 Dashboard:

    1. Navigate to [Branding > Phone Provider](https://manage.auth0.com/dashboard/#/phone/templates/phone/provider). This takes you to the Phone Message Provider page. By default, the Twilio phone provider is selected.
    2. Select the **Custom** phone provider option in the Phone Provider section.
    3. Select the **Delivery Method:**

       1. Text: The verification code will be delivered to your users via SMS.
       2. Voice: The verification code will be delivered to your users via Voice Message.
    4. Under **Provider Configuration**, write your actions code to configure a custom phone provider:

       1. Consult with your provider's documentation to understand how to deliver messages to their API.
       2. Add any required secrets to authenticate with the API.
       3. (Optional) You can edit the Action using the full Actions editor interface by clicking the **Edit in Expanded Editor** button. After editing your action in the Actions editor, **Save** and **Deploy** the Action from that interface. Click the **Back to Phone Provider** link at the top of the Actions editor page to return to the Phone Message Provider page. You will need to select the **Custom** phone provider option again in the Phone Provider section.
    5. Click the **Save** button at the bottom of the page.

    When you click **Save,** the Action automatically saves and deploys. To test the custom phone provider configuration before using it in a production environment, click **Send Test Message**.

    <Callout icon="file-lines">
      You cannot click **Send Test Message** to test your custom phone provider until after you save your custom phone provider configuration.
    </Callout>

    #### Edit a custom phone provider with the Auth0 Dashboard

    To edit an existing custom phone provider in the Auth0 Dashboard:

    1. Navigate to [Branding > Phone Provider](https://manage.auth0.com/dashboard/#/phone/templates/phone/provider). This takes you to the Phone Message Provider page.
    2. Modify the Action code on the Phone Message Provider page as needed.

       1. (Optional) You can edit the Action using the full Actions editor interface by clicking the **Edit in Expanded Editor** button. After editing your Action in the Actions editor, **Save** and **Deploy** the Action from that interface. Then click the **Back to Phone Provider** link at the top of the Actions editor page.
    3. Click the **Save** button at the bottom of the page.

    When you click **Save,** the Action automatically saves and deploys. To test the custom phone provider configuration before using it in a production environment, click **Send Test Message**.
  </Tab>

  <Tab title="Management API">
    #### Add a custom phone provider with the Management API

    You can also configure a custom phone provider using the Management API. This is a multi-step process:

    1. Create an [Action](https://auth0.com/docs/api/management/v2/actions/post-action) and set the `supported_triggers.id` to `custom-phone-provider`.

       1. Consult with your provider's documentation to understand how to deliver messages to their API.
       2. Add any required secrets to authenticate with the API.
    2. [Deploy](https://auth0.com/docs/api/management/v2/actions/post-deploy-action) the action.
    3. Set the [phone provider](https://auth0.com/docs/api/management/v2/branding/create-phone-provider) to `custom`.

    <Callout icon="file-lines">
      The Action you create with the `custom-phone-provider` trigger will not appear in the Actions library.
    </Callout>

    <Callout icon="file-lines">
      If no Action is deployed and you try to configure a `custom` provider, Auth0 will return an error with `"errorCode":"custom_email_provider_deployed_action_not_found"`.
    </Callout>

    #### Edit a custom phone provider with the Management API

    You can also edit a custom phone provider using the Management API.

    1. (Optional) If you don’t know the specific Action ID, you can [get the list of actions](https://auth0.com/docs/api/management/v2/actions/get-actions) via the Management API. The response will include an Actions object. The Action used for the custom phone provider can be identified by the `supported_triggers.id`, which should be set to `custom-phone-provider`.
    2. [Update the Action](https://auth0.com/docs/api/management/v2/actions/patch-action) as needed.
    3. [Deploy](https://auth0.com/docs/api/management/v2/actions/post-deploy-action) the Action.
  </Tab>
</Tabs>

An example of a custom phone provider you can configure is [Twilio Verify](https://www.twilio.com/docs/verify). To learn more, read [Configure custom phone provider with Twilio Verify](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider/configure-a-custom-phone-provider-with-twilio-verify).

## Example custom-phone-provider Action

The `custom-phone-provider` trigger is different from the `send-phone-message` trigger, which should not be used for configuring a custom phone provider. To learn more, read the following:

* [Action Triggers: custom-phone-provider API Object](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider/action-triggers-custom-phone-provider-api-object)
* [Action Triggers: custom-phone-provider Event Object](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider/actions-triggers-custom-phone-provider-event-object)

The following code sample is a `custom-phone-provider` Action that has the functionality of a `send-phone-message` Action:

```javascript lines expandable theme={null}
/**
* Handler to be executed while sending a phone notification*
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {CustomPhoneProviderAPI} api - Methods and utilities to help change the behavior of sending a phone notification.
*/
exports.onExecuteCustomPhoneProvider = async (event, api) => {

  if (event.notification.message_type.startsWith('otp')) {
    const body = {
      from: event.notification.from,
      action: event.notification.message_type === 'otp_verify' ? 'second-factor-authenticator' : 'enrollment',
      language: event.notification.locale,
      recipient: event.notification.recipient,
      message_type: event.notification.delivery_method,
      text: event.notification.as_text,
      code: event.notification.code,
    };

    const response = await fetch(event.secret.SERVICE_URL, {
      method: 'POST',
      headers: {
        authorization: `Bearer ${event.secrets.TOKEN}`,
      },
      body: JSON.stringify(body),
    });

    console.log(response);
  }

  return;
};
```


# Actions Triggers: custom-phone-provider - API Object
Source: https://auth0.com/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider/action-triggers-custom-phone-provider-api-object

Learn about the custom-phone-provider Action trigger's API object.

The API object for the custom-phone-provider Actions trigger includes:

## `api.cache`

Make changes to the cache.

### `api.cache.delete(key)`

Delete a record describing a cached value at the supplied
key if it exists.

<ResponseField name="key" type="string">
  The key of the cache record to delete.
</ResponseField>

### `api.cache.get(key)`

Retrieve a record describing a cached value at the supplied key,
if it exists. If a record is found, the cached value can be found
at the `value` property of the returned object.

<ResponseField name="key" type="string">
  The key of the record stored in the cache.
</ResponseField>

### `api.cache.set(key, value, options)`

Store or update a string value in the cache at the specified key.

Values stored in this cache are scoped to the Trigger in which they
are set. They are subject to the [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations).

Values stored in this way will have lifetimes of *up to* the specified
`ttl` or `expires_at` values. If no lifetime is specified, a default of
lifetime of 24 hours will be used. Lifetimes may not exceed the maximum
duration listed at [Actions Cache Limits](https://auth0.com/docs/customize/actions/limitations).

**Important**: This cache is designed for short-lived, ephemeral data. Items may not be
available in later transactions even if they are within their supplied their lifetime.

<ResponseField name="key" type="string">
  The key of the record to be stored.
</ResponseField>

<ResponseField name="value" type="string">
  The value of the record to be stored.
</ResponseField>

<ResponseField name="options" type="cachesetoptions">
  Options for adjusting cache behavior.

  <Expandable title="options properties">
    <ResponseField name="expires_at" type="number">
      The absolute expiry time in milliseconds since the unix epoch.
      While cached records may be evicted earlier, they will
      never remain beyond the the supplied `expires_at`.

      *Note*: This value should not be supplied if a value was also
      provided for `ttl`. If both options are supplied, the
      earlier expiry of the two will be used.
    </ResponseField>

    <ResponseField name="ttl" type="number">
      The time-to-live value of this cache entry in milliseconds.
      While cached values may be evicted earlier, they will
      never remain beyond the the supplied `ttl`.

      *Note*: This value should not be supplied if a value was also
      provided for `expires_at`. If both options are supplied, the
      earlier expiry of the two will be used.
    </ResponseField>
  </Expandable>
</ResponseField>

## `api.notification`

Informs if we should consider the notification event as to be retried or to be dropped.
See each of these methods for further details on the actual behaviour.
If several calls are made, only the last one is considered.

### `api.notification.drop(reason)`

When called, the notification event is considered failed without recovery:
We will log an error for this event, but won't be sending it again to the action in the future.
If you need this notification event to be retried, consider calling retry instead.

<ResponseField name="reason" type="string">
  this reason will be part of the log entry, this will help you analyze the error further. Please note that this field is limited to 1024 characters and will be truncated if larger.
</ResponseField>

### `api.notification.retry(reason)`

When called, the notification event is considered failed, but recoverable:
We will log an error for this event, but we will retry it up to 5 times in the next minutes.
If you consider that this notification event should not be retried, consider calling drop instead.

<ResponseField name="reason" type="string">
  this reason will be part of the log entry, this will help you analyze the error further. Please note that this field is limited to 1024 characters and will be truncated if larger.
</ResponseField>


# Actions Triggers: custom-phone-provider - Event Object
Source: https://auth0.com/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider/actions-triggers-custom-phone-provider-event-object

Learn about the custom-phone-provider Action trigger's event object, which provides contextual information about the trigger execution.

The `event` object for the custom-phone-provider Actions trigger provides contextual information about the trigger execution.

## `event.client`

<ResponseField name="event.client" type="dictionary">
  Information about the Client with which this login transaction was initiated.

  <Expandable title="client properties">
    <ResponseField name="client_id" type="string">
      The client id of the application the user is logging in to.
    </ResponseField>

    <ResponseField name="metadata" type="dictionary">
      An object for holding other application properties.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the application (as defined in the Dashboard).
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.connection`

<ResponseField name="event.connection" type="dictionary">
  Details about the Connection that was used to authenticate the user.

  <Expandable title="connection properties">
    <ResponseField name="id" type="string">
      The connection's unique identifier.
    </ResponseField>

    <ResponseField name="metadata" type="dictionary">
      Metadata associated with the connection.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the connection used to authenticate the user (such as `twitter` or `some-g-suite-domain`).
    </ResponseField>

    <ResponseField name="strategy" type="string">
      The type of connection. For social connections, `event.connection.strategy === event.connection.name`. For enterprise connections, the strategy is `waad` (Windows Azure AD), `ad` (Active Directory/LDAP), `auth0` (database connections), and so on.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.custom_domain`

<ResponseField name="event.custom_domain" type="dictionary">
  Details about the custom domain associated with the current transaction.

  <Expandable title="custom_domain properties">
    <ResponseField name="domain" type="string">
      The custom domain name.
    </ResponseField>

    <ResponseField name="domain_metadata" type="dictionary">
      Custom domain metadata as key-value pairs.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.notification`

<ResponseField name="event.notification" type="object">
  <Expandable title="notification properties">
    <ResponseField name="as_text" type="string">
      The text, as we rendered it, ready to be delivered as a text message.
    </ResponseField>

    <ResponseField name="as_voice" type="string">
      The text, as we rendered it, ready to be delivered as a voicetext message.
    </ResponseField>

    <ResponseField name="code" type="string">
      The One Time Password that we drawn for this message for some types (e.g. `otp_verify`, `otp_enroll`). If provided, it is important to have it conveyed to the end-user.
    </ResponseField>

    <ResponseField name="delivery_method" type="string">
      The way the message should be delivered. Could be `text` or `voice`.

      Allowed values: `text`, `voice`
    </ResponseField>

    <ResponseField name="from" type="string">
      The E.164 compliant phone number for the sender.
    </ResponseField>

    <ResponseField name="locale" type="string">
      The locale we rendered the message in, example `en_US`, as defined in the BCP-47 specification.
    </ResponseField>

    <ResponseField name="message_type" type="string">
      The type of message that is being send, like `otp_verify` or `blocked_account`.

      Allowed values: `otp_verify`, `otp_enroll`, `blocked_account`, `change_password`, `password_breach`
    </ResponseField>

    <ResponseField name="recipient" type="string">
      The E.164 compliant phone number for the recipient.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.organization`

<ResponseField name="event.organization" type="dictionary">
  Details about the Organization associated with the current transaction.

  <Expandable title="organization properties">
    <ResponseField name="id" type="string">
      The Organization identifier.
    </ResponseField>

    <ResponseField name="display_name" type="string">
      The friendly name of the Organization.
    </ResponseField>

    <ResponseField name="metadata" type="dictionary">
      Metadata associated with the Organization.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the Organization.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.request`

<ResponseField name="event.request" type="dictionary">
  Details about the request that initiated the transaction.

  <Expandable title="request properties">
    <ResponseField name="geoip" type="dictionary">
      <Expandable title="geoip properties">
        <ResponseField name="cityName" type="string" />

        <ResponseField name="continentCode" type="string" />

        <ResponseField name="countryCode" type="string" />

        <ResponseField name="countryCode3" type="string" />

        <ResponseField name="countryName" type="string" />

        <ResponseField name="latitude" type="number" />

        <ResponseField name="longitude" type="number" />

        <ResponseField name="subdivisionCode" type="string" />

        <ResponseField name="subdivisionName" type="string" />

        <ResponseField name="timeZone" type="string" />
      </Expandable>
    </ResponseField>

    <ResponseField name="hostname" type="string">
      The hostname that is being used for the authentication flow.
    </ResponseField>

    <ResponseField name="ip" type="string">
      The originating IP address of the request.
    </ResponseField>

    <ResponseField name="language" type="string">
      The language requested by the browser.
    </ResponseField>

    <ResponseField name="method" type="string">
      The HTTP method used for the request
    </ResponseField>

    <ResponseField name="user_agent" type="string">
      The value of the `User-Agent` header received when initiating the transaction.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.tenant`

<ResponseField name="event.tenant" type="object">
  <Expandable title="tenant properties">
    <ResponseField name="id" type="string">
      The name of the tenant.
    </ResponseField>

    <ResponseField name="friendly_name" type="string">
      The friendly name for the tenant, usually a more human-readable version of the ID.
    </ResponseField>

    <ResponseField name="home_url" type="string">
      The home URL for the tenant, if defined and as found in its settings.
    </ResponseField>

    <ResponseField name="logo_url" type="string">
      The logo URL for the tenant, if defined and as found in its settings.
    </ResponseField>

    <ResponseField name="support_email" type="string">
      The email to the tenant's support service, if defined and as found in its settings.
    </ResponseField>

    <ResponseField name="support_url" type="string">
      The url to the tenant's support service, if defined and as found in its settings.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.transaction`

<ResponseField name="event.transaction" type="object">
  Details about the current transaction for tracing purposes.

  <Expandable title="transaction properties">
    <ResponseField name="correlation_id" type="string">
      A unique identifier to correlate this request across multiple services for distributed tracing.
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.user`

<ResponseField name="event.user" type="dictionary">
  An object describing the user on whose behalf the current transaction was initiated.

  <Expandable title="user properties">
    <ResponseField name="app_metadata" type="dictionary">
      Custom fields that store info about a user that influences the user's access, such as support plan, security roles, or access control groups.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Timestamp indicating when the user profile was first created.
    </ResponseField>

    <ResponseField name="email" type="string">
      (unique) User's email address.
    </ResponseField>

    <ResponseField name="email_verified" type="boolean">
      Indicates whether the user has verified their email address.
    </ResponseField>

    <ResponseField name="family_name" type="string">
      User's family name.
    </ResponseField>

    <ResponseField name="given_name" type="string">
      User's given name.
    </ResponseField>

    <ResponseField name="last_password_reset" type="string">
      Timestamp indicating the last time the user's password was reset/changed. At user creation, this field does not exist. This property is only available for Database connections.
    </ResponseField>

    <ResponseField name="name" type="string">
      User's full name.
    </ResponseField>

    <ResponseField name="nickname" type="string">
      User's nickname.
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      User's phone number.
    </ResponseField>

    <ResponseField name="phone_verified" type="boolean">
      Indicates whether the user has verified their phone number.
    </ResponseField>

    <ResponseField name="picture" type="string">
      URL pointing to the [user's profile picture](https://auth0.com/docs/users/change-user-picture).
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      Timestamp indicating when the user's profile was last updated/modified.
    </ResponseField>

    <ResponseField name="user_id" type="string">
      (unique) User's unique identifier.
    </ResponseField>

    <ResponseField name="user_metadata" type="dictionary">
      Custom fields that store info about a user that does not impact what they can or cannot access, such as work address, home address, or user preferences.
    </ResponseField>

    <ResponseField name="username" type="string">
      (unique) User's username.
    </ResponseField>

    <ResponseField name="identities" type="array of objects">
      Contains info retrieved from the identity provider with which the user originally authenticates. Users may also link their profile to multiple identity providers; those identities will then also appear in this array. The contents of an individual identity provider object varies by provider.

      <Expandable title="identities properties">
        <ResponseField name="connection" type="string">
          Name of the Auth0 connection used to authenticate the user.
        </ResponseField>

        <ResponseField name="isSocial" type="boolean">
          Indicates whether the connection is a social one.
        </ResponseField>

        <ResponseField name="profileData" type="dictionary">
          User information associated with the connection. When profiles are linked, it is populated with the associated user info for secondary accounts.
        </ResponseField>

        <ResponseField name="provider" type="string">
          Name of the entity that is authenticating the user, such as Facebook, Google, SAML, or your own provider.
        </ResponseField>

        <ResponseField name="user_id" type="string">
          User's unique identifier for this connection/provider.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## `event.secrets`

<ResponseField name="event.secrets" type="secrets">
  Secret values securely associated with this Action.
</ResponseField>


# Configure a Custom Phone Provider with Terraform
Source: https://auth0.com/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider/configure-a-custom-phone-provider-with-terraform

Learn how to configure a custom phone provider using Terraform Auth0 Provider

You can configure a [custom phone provider](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider) with the Terraform Auth0 provider. The Terraform Auth0 provider is used to interact with the [Auth0 Management API](https://auth0.com/docs/api/management/v2) in order to configure an Auth0 Tenant. To learn more, review Terraform’s [Auth0 Provider](https://registry.terraform.io/providers/auth0/auth0/latest/docs) documentation.

<Callout icon="file-lines">
  * If you are using Terraform to configure a custom phone provider, delete your existing Auth0 tenant custom [phone](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider) provider.
  * Auth0 has a maximum limit of one Action for Actions associated with the following triggers: custom-phone-provider and custom-email-provider.
</Callout>

The following steps outline how to a custom phone provider using Terraform:

1. Create an [`auth0_action`](https://registry.terraform.io/providers/auth0/auth0/latest/docs/resources/phone_provider):

```terraform lines theme={null}
resource "auth0_action" "custom_phone_provider" {
  name    = "Custom Phone Provider"
  runtime = "node22"
  deploy  = true
  code    = <<-EOT
    /**
    * Handler to be executed while sending a phone notification
    * @param {Event} event - Details about the user and the context in which they are logging in.
    * @param {CustomPhoneProviderAPI} api - Methods and utilities to help change the behavior of sending a phone notification.
    */
    exports.onExecuteCustomPhoneProvider = async (event, api) => {
      // Code goes here
      return;
    };
  EOT
  supported_triggers {
    id      = "custom-phone-provider"
    version = "v1"
  }
}
```

<Callout icon="file-lines">
  In order to bind a Terraform `auth0_action` to an `auth0_trigger_action`, set the auth0\_action to `deploy = true`. To learn more, read Terraform's [auth0\_action](https://registry.terraform.io/providers/auth0/auth0/latest/docs/resources/action) documentation.
</Callout>

2. Bind the `auth0_action` to the custom-phone-provider `auth0_trigger_action`:

```terraform lines theme={null}
resource "auth0_trigger_action" "custom_phone_provider" {
  trigger = "custom-phone-provider"
  actions {
    id           = auth0_action.custom_phone_provider.id
    display_name = auth0_action.custom_phone_provider.name
  }
  depends_on = [
    auth0_action.custom_phone_provider
  ]
}
```

3. Configure the `auth0_phone_provider` resource to use the `auth0_action`:

```terraform lines theme={null}
resource "auth0_phone_provider" "custom_phone_provider" {
  depends_on = [auth0_trigger_actions.custom_phone_provider] # Ensure the action is created first with `custom-phone-provider` as the supported_triggers
  name       = "custom"                         # Indicates a custom implementation
  disabled   = false                            # Disable the default phone provider
  configuration {
    delivery_methods = ["text", "voice"]
  }
  credentials {}
},
```

To learn more, read Terraform’s [auth0\_phone\_provider](https://registry.terraform.io/providers/auth0/auth0/latest/docs/resources/phone_provider) documentation.

## Troubleshoot

**Scenario: Custom phone provider configured using Terraform is not taking effect, and the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> displays a different Action.**

You may have multiple custom provider Actions with `deploy: true`. Auth0 has a maximum limit of one Action for Actions associated with the following triggers: `custom-phone-provider` and `custom-email-provider`.

* If you encounter this scenario, it’s recommended that you [list your Actions](https://auth0.com/docs/api/management/v2/actions/get-actions) to identify any duplicates to delete.
* If you encounter this scenario after managing your custom providers through multiple methods (Terraform, Auth0 Dashboard, <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>, and/or Auth0 SDKs) it is advisable to reset the custom provider configuration. We recommend you refrain from using multiple methods to manage your custom provider.

To reset the custom phone provider, navigate to [Auth0 Dashboard > Branding > Phone Provider](https://manage.auth0.com/#/phone/templates/phone/provider). Then, select the **Reset** button under Provider Configuration to restore your custom provider to its default.


# Configure a Custom Phone Provider with Twilio Verify
Source: https://auth0.com/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider/configure-a-custom-phone-provider-with-twilio-verify

Learn how to configure a custom phone provider with Twilio Verify

You can configure a custom phone provider with [Twilio Verify](https://www.twilio.com/docs/verify), which helps fight fraud and protect user accounts. This sets up Twilio Verify as your custom phone provider.

## Prerequisites

You must have a [Twilio](https://twilio.com/) account with a valid SMS and/or phone delivery option.

## Set up Twilio Verify service

You can create a Twilio Verify service through the [Twilio Console](https://www.twilio.com/console/verify/services) or the [Verify REST API](https://www.twilio.com/docs/verify/api/service#create-a-verification-service). You will need the following to connect your Auth0 custom phone provider with Twilio Verify:

* TWILIO\_ACCOUNT\_SID
* TWILIO\_AUTH\_TOKEN
* TWILIO\_VERIFY\_SID

## Connect custom phone provider with Twilio Verify

1. In the Auth0 Dashboard, navigate to [Branding > Phone Provider](https://manage.auth0.com/dashboard/#/phone/templates/phone/provider). This takes you to the **Phone Message Provider** page.
2. Select **Custom** as a **Phone Provider**.
3. Under **Provider Configuration**, add the following code sample to allow the Twilio API to send phone messages to a user's phone number:

```javascript lines expandable theme={null}
/**
* Handler to be executed while sending a phone notification
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {CustomPhoneProviderAPI} api - Methods and utilities to help change the behavior of sending a phone notification.
*/
exports.onExecuteCustomPhoneProvider = async (event, api) => {
 const { TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_VERIFY_SID } = event.secrets;

  const client = require('twilio')(TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN);

  // map auth0 voice value to call
  const messageType = event.notification.delivery_method === 'voice' ? 'call' : 'sms';

  const { recipient, code } = event.notification;

  // add this to fix " 1333444999  "
  // "333 444 5555"
  const sanitizedNumber = recipient.replace(/\s/g, '').trim();

  await client.verify.v2.services(TWILIO_VERIFY_SID)
    .verifications.create({
      to: sanitizedNumber,
      channel: messageType,
      customCode: code
    })

};
```

3. Click the **Key** icon to open the **Secrets** menu. Add the following values from your Twilio Verify service setup:

* TWILIO\_ACCOUNT\_SID
* TWILIO\_AUTH\_TOKEN
* TWILIO\_VERIFY\_SID

4. To load the Twilio helper library, click the **Dependency** icon. Then, click the **Add Dependency** button. When the **Add Dependency** pop-up window appears, enter the following:

* **Name:** Twilio
* **Version:** latest (should be auto populated)

When you click **Create**, Auth0 will search for the Twilio helper library and load the latest version.

5. Click **Save**. When you click **Save,** the Action automatically saves and deploys. To test the custom phone provider configuration before using it in a production environment, click **Send Test Message**.


# Configure Twilio as a Phone Messaging Provider
Source: https://auth0.com/docs/customize/phone-messages/configure-phone-messaging-providers/configure-twilio-as-a-phone-messaging-provider

Learn how to configure Twilio as a Phone Messaging Provider in the Auth0 Dashboard.

## Prerequisites

You must have a [Twilio](https://twilio.com/) account with a valid SMS and/or phone delivery option.

## Configure Twilio

1. Log in to your [Twilio](https://www.twilio.com/login) account.
2. Go to your [Twilio Console](https://console.twilio.com/). You will need your Twilio SID and Twilio Auth Token when configuring Twilio in your Auth0 Dashboard.
3. Go to Auth0 [Dashboard > Branding > Phone Provider](https://manage.auth0.com/#/branding/phone/provider). Select **Twilio** as your **Phone Provider**.
4. Select a **Delivery Method**. You can choose **Text**, **Voice**, or both as delivery methods for your customers.
5. For the **Twilio Provider Settings**, select an **SMS Source**:

   1. If you select **Use From**, enter a default phone number from which customers will receive phone messages.
   2. If you select [Messaging Service](https://www.twilio.com/docs/messaging/services), enter your Twilio Messaging Service SID. You can find this value in your Twilio Console.
   3. Enter your Twilio SID and Twilio Auth Token from the Twilio Console. Click **Save**.

## Test phone

Click the **Try** button to send a test phone message. If you have successfully configured Twilio as an external phone provider, Auth0 will send a confirmation phone message using the selected delivery method. If you do not receive a phone message after a few minutes, check your [Auth0 logs](https://manage.auth0.com/#/logs) for failures.

The Twilio [Messaging Activity](https://console.twilio.com/us1/develop/sms/overview) page displays delivery insights for all SMS that have been sent to your users.


# Customize Phone Templates
Source: https://auth0.com/docs/customize/phone-messages/customize-phone-templates

Learn how to customize phone templates in the Auth0 Dashboard.

## Prerequisites

Before customizing your phone templates, configure your phone provider using a third-party service like Twilio. To learn more, read [Configure Phone Messaging Providers](/docs/customize/phone-messages/configure-phone-messaging-providers).

## Get started

Go to the [Auth0 Dashboard](https://manage.auth0.com/#/phone). Under **Branding > Phone Templates,** Auth0 provides the following customizable phone templates:

* **Blocked Account**: Alerts the customer that their account has been blocked as a result of suspicious activity.
* **Change Password**: Sends the customer their password change code.
* **One Time Password - Enrollment**: Sends the customer the verification code for one-time password (OTP) enrollment.
* **One Time Password - Verify**: Sends the customer the verification code for one-time password (OTP) verification.

Once you select a phone template, enable it by toggling the **Status**. Now, you can customize the **From** phone number and the **Text Message Template**.

## From phone number

The default **From** phone number is the one you set while configuring your phone provider. To learn more, read [Configure Phone Messaging Providers](/docs/customize/phone-messages/configure-phone-messaging-providers).

To set a custom **From** phone number for a phone template, enter the phone number from which customers will receive messages.

**Note:** If you set up Twilio as your phone provider and selected [Messaging Services](https://www.twilio.com/docs/messaging/services) as the SMS source, you won’t be able to set a custom **From** phone number. Instead, Twilio chooses one of the phone numbers in your Messaging Service's sender pool based on your Twilio configuration. To learn more, read the Twilio [Messaging Services](https://www.twilio.com/docs/messaging/services) documentation.

## Text Message Template

In the **Text Message Template** body, Auth0 enables you to dynamically generate content using the Liquid templating language. Using Liquid syntax, you can access a number of contextual variables that Auth0 replaces with the relevant values when rendering the phone messages. To learn more about Liquid, read [Liquid for Designers](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers) on GitHub.

Auth0 exposes the same set of [contextual variables](/docs/customize/email/email-templates#common-variables) that you can access using Liquid syntax for phone templates as it does for email templates. The markup rules for customizing phone templates using Liquid syntax are the same as those for customizing email templates. To learn how to use Liquid syntax to customize a phone template, read [Use Liquid Syntax in Email Templates](/docs/customize/email/email-templates/use-liquid-syntax-in-email-templates).

## Test phone template

Once you’ve finished customizing your phone template, click the **Try** button. Auth0 sends the phone message to a default app named after your tenant name. To test templates for different applications, create a sample user to go through the phone message flows.


# Auth0's Unified Phone Experience
Source: https://auth0.com/docs/customize/phone-messages/unified-phone

Learn about Auth0's Unified Phone Experience for phone provider configuration.

Auth0 allows you to configure a phone provider for <Tooltip href="/docs/glossary?term=Multi-Factor+Authentication">Multi-Factor Authentication</Tooltip> (MFA) and <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> at the tenant-level with the Unified Phone Experience. This eliminates the need to configure a phone provider in multiple locations while maintaining flexibility when configuring delivery methods.

Tenants with configured phone providers can migrate to the Unified Phone Experience and maintain phone messaging capabilities in one place. New tenants are automatically enrolled in the Unified Phone Experience.

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/customize/phone-messages/unified-phone/use-auth0s-unified-phone-experience-for-multi-factor-authentication">Use Auth0’s Unified Phone Experience for Multi-Factor Authentication</a></td>
      <td>How to migrate existing Multi-Factor Authentication configurations to the Unified Phone Experience</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/phone-messages/unified-phone/unified-phone-experience-passwordless">Use Auth0’s Unified Phone Experience for Passwordless</a></td>
      <td>How to migrate existing Passwordless configurations to the Unified Phone Experience</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/phone-messages/unified-phone/configure-unified-phone">Configure Auth0 Unified Phone Experience</a></td>
      <td>How to configure Multi-Factor Authentication and Passwordless with the Unified Phone Experience.</td>
    </tr>
  </tbody>
</table>


# Configure Auth0 Unified Phone Experience
Source: https://auth0.com/docs/customize/phone-messages/unified-phone/configure-unified-phone

Learn how to configure Auth0's Unified Phone Experience for MFA and Passwordless.

<Card title="Before you start">
  If you use [Passwordless SMS authentication](/docs/authenticate/passwordless/authentication-methods/use-sms-gateway-passwordless), [MFA SMS and voice notifications](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-sms-voice-notifications-mfa), or Phone as ID, you need to configure a phone provider with the Unified Phone Experience.

  If you need different providers for MFA, Passwordless, and/or Phone as ID, you must configure a [custom phone provider](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider) using Auth0 Actions.
</Card>

The Unified Phone Experience centralizes all phone provider configurations in one location in your tenant. This centralization eliminates the need to configure a phone provider multiple times for various phone authentication factors.

If you want to try out phone messaging capabilities, you need to configure a tenant-level phone provider.

<Callout icon="file-lines">
  Auth0 does not provide feedback to the end user on whether a phone message has been sent successfully with the tenant-level provider. To troubleshoot issues, review the [tenant logs](/docs/deploy-monitor/logs).
</Callout>

## Configure MFA

You can use the Unified Phone Experience with SMS, Voice, and SMS + Voice delivery methods and factors. To learn more about <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> with Auth0, read [Multi-Factor Authentication](/docs/secure/multi-factor-authentication).

1. In the Auth0 Dashboard, navigate to [**Branding > Phone Provider**](https://manage.auth0.com/#/phone/templates/phone/provider).
2. Enable the Phone Message Provider toggle.

   <Frame>
     <img alt="Auth0 Dashboard > Branding > Phone Provider > Enable Phone Message Provider" />
   </Frame>
3. Select your phone message provider.

   1. To use Twilio as your phone provider, follow [Configure Twilio as a Phone Messaging Provider](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-twilio-as-a-phone-messaging-provider).
   2. To use a custom provider, follow [Configure a Custom Phone Provider](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider) to use Auth0 Actions.
4. Select your delivery method(s).

   <Callout icon="file-lines">
     Desired MFA factors must be a subset of the delivery methods you configure at the tenant-level.
   </Callout>
5. **Save** your changes.
6. Once complete, navigate to [Security > Multi-factor Auth](https://manage.auth0.com/#/security/mfa).
7. Select **Phone Message**.
8. Choose the authentication factors.
9. **Save** your changes.

## Configure Passwordless

You can use the Unified Phone Experience with a <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> SMS connection. To learn more about passwordless authentication with Auth0, read [Passwordless Connections](/docs/authenticate/passwordless).

1. In the Auth0 Dashboard, navigate to [**Branding > Phone Provider**](https://manage.auth0.com/#/phone/templates/phone/provider).
2. Enable the Phone Message Provider toggle.

   <Frame>
     <img alt="Auth0 Dashboard > Branding > Phone Provider > Enable Phone Message Provider" />
   </Frame>
3. Select your phone message provider.

   1. To use Twilio as your phone provider, follow [Configure Twilio as a Phone Messaging Provider](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-twilio-as-a-phone-messaging-provider).
   2. To use a custom provider, follow follow [Configure a Custom Phone Provider](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider) to use Auth0 Actions.
4. Select your delivery method.

   <Callout icon="file-lines">
     If you do not select **Text** as a configured delivery method, your integration with Passwordless will not work.
   </Callout>
5. **Save** your changes.
6. Once complete, navigate to [**Authentication > Passwordless > SMS**](https://manage.auth0.com/#/connections/passwordless).
7. **Save** your changes.
8. If you are using Twilio:

   1. Navigate to [**Applications > Applications**](https://manage.auth0.com/#/applications).
   2. Select the application(s) you want to use for your Twilio SMS connection for Passwordless.
   3. Under **Connections**, enable the SMS (Twilio) option.
   4. Return to [**Authentication > Passwordless > SMS**](https://manage.auth0.com/#/connections/passwordless).
   5. Under the **Applications** tab, enable all applications you want to use for Passwordless SMS.
   6. **Save** your changes.

<Callout icon="file-lines">
  If you have a use case in need of the legacy [MFA](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-sms-voice-notifications-mfa) and [Passwordless](/docs/authenticate/passwordless/authentication-methods/use-sms-gateway-passwordless) experience, contact [Auth0 Support](/docs/troubleshoot/customer-support).
</Callout>

### Test your phone provider

Test the tenant-level provider before using it in a production environment:

1. Navigate to [**Branding > Phone Provider**](https://manage.auth0.com/#/phone/templates/phone/provider).
2. Select **Send Test Message** to test the tenant-level provider before using it in a production environment.

## Configure phone templates

The tenant-level phone provider uses [Liquid syntax](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers) to inject contextual variables into your phone message content. To configure your phone templates, follow the instructions in [Customize Phone Templates](/docs/customize/phone-messages/customize-phone-templates).

## Disable phone provider

If you configure the Unified Phone Experience and then disable it, existing integrations with your phone provider could break, including your MFA phone factor.

<Frame>
  <img alt="" />
</Frame>


# Use the Unified Phone Experience for Passwordless
Source: https://auth0.com/docs/customize/phone-messages/unified-phone/unified-phone-experience-passwordless

Learn how to configure the Unified Phone Experience for Passwordless authentication.

<Card title="Before you start">
  To migrate to the Unified Phone Experience, you must:

  * Have Multi-Factor Authentication (MFA) SMS, Voice, or SMS+Voice notifications enabled and configured in your tenant, or
  * Have Passwordless SMS enabled and configured in your tenant

  If you have not configured either MFA or Passwordless, read [Configure Auth0's Unified Phone Experience](/docs/customize/phone-messages/unified-phone/configure-unified-phone) to start from the beginning.

  If you have both MFA and Passwordless integrations with different providers, you must use a [Custom Phone Provider](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider).

  If you utilize Phone as ID, you are automatically using Auth0's Unified Phone Experience and no additional action is needed.
</Card>

The Unified Phone Experience centralizes all your phone provider configurations in one location in your tenant. You won’t need to configure a phone provider multiple times for various phone authentication factors. To learn more about phone factors for <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip>, read [Passwordless Authentication with SMS](/docs/authenticate/passwordless/authentication-methods/sms-otp).

If you already have a phone provider configured for Passwordless, you can migrate your configuration to the Unified Phone Experience and apply your configuration at the tenant-level.

<Callout icon="file-lines">
  Auth0 does not provide feedback to the end user on whether a phone message has been sent successfully with the tenant-level provider. To troubleshoot issues, review the [tenant logs](/docs/deploy-monitor/logs).
</Callout>

## Update your phone provider

To use the Unified Phone Experience, you need to:

* Verify current settings
* Configure your provider:

  * Configure Twilio
  * Configure a custom phone provider
* Update delivery methods

### Verify current settings

1. To verify your current Passwordless settings, navigate to [**Auth0 Dashboard > Authentication > Passwordless > SMS**](https://manage.auth0.com/#/connections/passwordless).
2. Select **Phone Message**.
3. If you are able to use the Unified Phone Experience, a banner advises you to configure a tenant-level provider:

<Frame>
  <img alt="Dashboard > Authentication > Passwordless > SMS" />
</Frame>

<Callout icon="file-lines">
  If you must use the legacy experience to configure your phone provider, and the toggle to use a tenant-level provider is missing, contact [Auth0 Support](/docs/troubleshoot/customer-support).
</Callout>

### Configure Twilio as a tenant-level provider

If you are using Twilio as your phone provider for Passwordless, you must add the Twilio SID and AuthToken to the Unified Phone Experience. You can copy the Twilio SID from your existing configuration, but you will need to get the value of the AuthToken from Twilio.

1. Navigate to [**Branding > Phone Provider**](https://manage.auth0.com/#/phone/templates/phone/provider).
2. Select and configure your provider:

   <Frame>
     <img alt="Branding > Phone Provider > Twilio" />
   </Frame>

   1. Choose Twilio as your phone provider.
   2. Choose your delivery methods.
   3. Enter Twilio settings.
3. **Save** your changes.
4. Select **Send Test Message** to test the tenant-level provider before using it in a production environment.
5. Enable a tenant-level provider.

   1. Navigate to [**Authentication > Passwordless > SMS**](https://manage.auth0.com/#/connections/passwordless).
   2. Select **Use Tenant-level Messaging Provider**

      <Warning>
        If no toggle exists in your tenant, you are already using the Unified Phone experience.
      </Warning>
6. **Save** your changes.

### Create a new custom-phone-provider Action for Passwordless

The Unified Phone Experience does not use the [custom SMS gateway](/docs/authenticate/passwordless/authentication-methods/use-sms-gateway-passwordless) you configured for Passwordless SMS. You can use the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to configure a custom phone provider with Auth0 Actions. To learn more, read [Configure a Custom Phone Provider](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider).

##### Configure Passwordless custom-phone-provider

To configure your Custom SMS Gateway phone configuration via phone provider Action:

1. Navigate to [**Branding > Phone Provider**](https://manage.auth0.com/#/phone/templates/phone/provider).
2. Select your provider:

   1. Choose **Custom**.
   2. Under **Provider Configuration**, add your new `custom-phone-provider` Actions that forwards the Passwordless notification to a custom SMS gateway.
3. **Save** your changes.
4. Select **Send Test Message** to test the tenant-level provider before using it in a production environment.
5. Navigate to [**Authentication > Passwordless > SMS**](https://manage.auth0.com/#/connections/passwordless) to enable the **Use Tenant-level Messaging Provider**.
6. **Save** your changes.

##### Custom SMS gateway to custom-phone-provider example

```javascript lines expandable theme={null}
const request = require('<favorite_http_client>');
/**
* Handler to be executed while sending a phone notification
* 
@param
 {Event} event - Details about the user and the context in which they are logging in.
* 
@param
 {CustomPhoneProviderAPI} api - Methods and utilities to help change the behavior of sending a phone notification.
*/
exports.onExecuteCustomPhoneProvider = async (event, api) => {
  const notificationType = event.notification.message_type;
  switch (notificationType) {
    case '<otp_verify>': {
      const req = {
        url: event.secrets.GATEWAY_URL,
        method: 'POST',
        headers: {
          'User-Agent': 'Auth0'
        },
        body: {
          recipient: event.notification.recipient,
          body: event.notification.as_text, // or event.notification.as_voice
          sender: event.notification.from, // TODO: sender is missed we need to check if we want to add it.
          req: event.request || {}, // if not enabled, it will come as undefined
        }
      }
      const response = await request(req);
      console.log(response.statusCode);
      return
    }
    default: {
      // handle other notifications as usual
      return;
    }
  }
};
```

### Update delivery methods

<table>
  <thead>
    <tr>
      <th><b>Phone factors</b></th>
      <th><b>Current tenant-level delivery method</b></th>
      <th><b>Desired tenant-level delivery method</b></th>
      <th><b>User action</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>SMS</td>
      <td>SMS</td>
      <td>SMS + Voice</td>
      <td>None</td>
    </tr>

    <tr>
      <td>SMS</td>
      <td>SMS</td>
      <td>Voice</td>
      <td>User must update Passwordless phone factors to be a subset of the delivery methods enabled for the tenant-level provider</td>
    </tr>

    <tr>
      <td>SMS</td>
      <td>SMS + Voice</td>
      <td>Voice</td>
      <td>User must update Passwordless phone factors to be a subset of the delivery methods enabled for the tenant-level provider</td>
    </tr>

    <tr>
      <td>SMS</td>
      <td>SMS + Voice</td>
      <td>SMS</td>
      <td>None</td>
    </tr>
  </tbody>
</table>

## Disable phone provider

If you configure the Unified Phone Experience and then disable it, existing integrations with your phone provider, including Passwordless, could break.

<Frame>
  <img alt="" />
</Frame>


# Use Auth0's Unified Phone Experience for Multi-Factor Authentication
Source: https://auth0.com/docs/customize/phone-messages/unified-phone/use-auth0s-unified-phone-experience-for-multi-factor-authentication

Migrate your phone provider configuration to the Unified Phone Experience.

<Card title="Before you start">
  To migrate to the Unified Phone Experience, you must:

  * Have Multi-Factor Authentication (MFA) SMS, Voice, or SMS+Voice notifications enabled and configured in your tenant, or
  * Have Passwordless SMS enabled and configured in your tenant

  If you have not configured either MFA or Passwordless, read [Configure Auth0's Unified Phone Experience](/docs/customize/phone-messages/unified-phone/configure-unified-phone) to start from the beginning.

  If you have both MFA and Passwordless integrations with different providers, you must use a [Custom Phone Provider](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider).

  If you utilize Phone as ID, you are automatically using Auth0's Unified Phone Experience and no additional action is needed.
</Card>

The Unified Phone Experience centralizes all your phone provider configurations in one location in your tenant. You won’t need to configure a phone provider multiple times for various phone authentication factors. To learn more about phone factors for <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip>, read [SMS and voice notifications for MFA](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-sms-voice-notifications-mfa).

If you already have a phone provider configured for Multi-Factor Authentication (MFA), you can migrate your configuration to the Unified Phone Experience and apply your configuration at the tenant-level.

<Callout icon="file-lines">
  Auth0 does not provide feedback to the end user on whether a phone message has been sent successfully with the tenant-level provider. To troubleshoot issues, review the [tenant logs](/docs/deploy-monitor/logs).
</Callout>

## Update your phone provider

To use the Unified Phone Experience, you need to:

* Verify current settings
* Configure your provider:

  * Configure Twilio
  * Configure a custom phone provider
* Update your phone factors and delivery methods
* Update <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> endpoints
* Update Auth0 Actions triggers

### Verify current settings

1. To verify your current MFA settings, navigate to [**Auth0 Dashboard > Security > Multi-factor Auth**](https://manage.auth0.com/#/security/mfa).
2. Select **Phone Message**.
3. If you are able to use the Unified Phone Experience, a banner advises you to configure a tenant-level provider:

   <Frame>
     <img alt="" />
   </Frame>

<Callout icon="file-lines">
  If you must use the legacy experience to configure your phone provider, and the toggle to use a tenant-level provider is missing, contact [Auth0 Support](/docs/troubleshoot/customer-support).
</Callout>

### Configure Twilio as a tenant-level provider

If you are using Twilio as your phone provider for Multi-Factor Authentication, you must add the Twilio SID and AuthToken to the Unified Phone Experience. You can copy the Twilio SID from your existing configuration, but you will need to get the value of the AuthToken from Twilio.

1. Navigate to [**Branding > Phone Provider**](https://manage.auth0.com/#/phone/templates/phone/provider).
2. Select and configure your provider:

   <Frame>
     <img alt="Branding > Phone Provider > Twilio" />
   </Frame>

   1. Choose Twilio as your phone provider.
   2. Choose your delivery methods.
   3. Enter Twilio settings.

      <Callout icon="file-lines">
        Desired MFA factors must be a subset of the delivery methods you configure at the tenant-level.
      </Callout>
3. **Save** your changes.
4. Select **Send Test Message** to test the tenant-level provider before using it in a production environment.
5. Enable a tenant-level provider.

   1. For MFA, navigate to [**Security > Multi-factor Auth > Phone Message**.](https://manage.auth0.com/#/security/mfa)
   2. Select **Use Tenant-level Messaging Provider**.

      <Warning>
        If no toggle exists in your tenant, you are already using the Unified Phone experience.
      </Warning>
6. **Save** your changes.

### Configure a custom provider with Auth0 Actions

The Unified Phone Experience uses the `custom-phone-provider` Actions Trigger for phone notifications rather than the `send-phone-message` Actions Trigger for custom phone notifications.

You cannot directly migrate your `send-phone-message` Actions trigger to the `custom-phone-provider` Actions trigger because:

* There is no 1:1 mapping between message and notification types.
* Migrating secrets and dependencies associated with the send-phone-message Actions trigger could cause security concerns or break the tenant experience.
* Actions can support more than one trigger and could be difficult to migrate. For example, Actions can support both the `send-phone-message` and `post-login` triggers.
* The `send-phone-message` and `custom-phone-provider` Actions triggers support different event types:

  * `send-phone-message` supports the SMS and Voice message types. To learn more, read [Action triggers: send-phone-message Event Object](/docs/customize/actions/explore-triggers/mfa-notifications-trigger/send-phone-message-event-object).
  * `custom-phone-provider` supports the `otp_verify`, `otp_enroll`, `blocked_account`, `change_password`, and `password_breach` notification types. To learn more, read [Actions triggers: custom-phone-provider Event Object](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider/actions-triggers-custom-phone-provider-event-object).
* You can only set one Action per custom phone provider. If you have already set an Action for a custom phone provider, you **must** disable it before associating it with a new Action.

As a result, you need to translate your existing `send-phone-message` into a new `custom-phone-provider` using the new contextual variables:

<AccordionGroup>
  <Accordion title="Core payload">
    <table>
      <thead>
        <tr>
          <th><b><code>send-phone-message</code> context object</b></th>
          <th><b><code>custom-phone-provider</code> context object</b></th>
          <th><b>Status</b></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>text</code></td>
          <td><code>notification.as\_text</code> and <code>notification.as\_voice</code></td>
          <td>Updated</td>
        </tr>

        <tr>
          <td><code>message\_type</code></td>
          <td><code>notification.message\_type</code> <ul><li>Note the difference in values: <code>second-factor-authentication</code> vs <code>otp\_enroll</code>, <code>verify</code> vs <code>otp\_verify</code>)</li></ul></td>
          <td>Updated</td>
        </tr>

        <tr>
          <td><code>action</code></td>
          <td><code>notification.delivery\_method</code></td>
          <td>Updated</td>
        </tr>

        <tr>
          <td><code>language</code></td>
          <td><code>notification.locale</code></td>
          <td>Updated</td>
        </tr>

        <tr>
          <td><code>code</code></td>
          <td><code>notification.code</code></td>
          <td>Updated</td>
        </tr>

        <tr>
          <td><code>recipient</code></td>
          <td><code>notification.recipient</code></td>
          <td>Updated</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Request data">
    <table>
      <thead>
        <tr>
          <th><b> <code>send-phone-message</code> context object </b></th>
          <th><b>Tenant-level provider context object</b></th>
          <th><b> Status </b></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>ip</code></td>
          <td><code>ip</code></td>
          <td>Unchanged</td>
        </tr>

        <tr>
          <td><code>user\_agent</code></td>
          <td><code>user\_agent</code></td>
          <td>Unchanged</td>
        </tr>

        <tr>
          <td><code>language</code></td>
          <td><code>language</code></td>
          <td>Updated</td>
        </tr>

        <tr>
          <td><code>method</code></td>
          <td><code>method</code> optional</td>
          <td>Updated</td>
        </tr>

        <tr>
          <td><code>hostname</code></td>
          <td><code>hostname</code> optional</td>
          <td>Updated</td>
        </tr>

        <tr>
          <td><code>geoip</code></td>
          <td><code>geoip</code></td>
          <td>Updated</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Tenant data">
    <table>
      <thead>
        <tr>
          <th><b> <code>send-phone-message</code> context object </b></th>
          <th><b>Tenant-level provider context object</b></th>
          <th><b> Status </b></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>tenant.id</code></td>
          <td><code>tenant</code></td>
          <td>Updated</td>
        </tr>

        <tr>
          <td>N/A</td>
          <td><code>tenant.home\_url</code></td>
          <td>New</td>
        </tr>

        <tr>
          <td>N/A</td>
          <td><code>tenant.logo\_url</code></td>
          <td>New</td>
        </tr>

        <tr>
          <td>N/A</td>
          <td><code>tenant.support\_email</code></td>
          <td>New</td>
        </tr>

        <tr>
          <td>N/A</td>
          <td><code>tenant.support\_url</code></td>
          <td>New</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Application data">
    <table>
      <thead>
        <tr>
          <th><b> <code>send-phone-message</code> context object </b></th>
          <th><b>Tenant-level provider context object</b></th>
          <th><b> Status </b></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>client.client\_metadata</code></td>
          <td><code>client.metadata</code></td>
          <td>Updated</td>
        </tr>

        <tr>
          <td><code>client.client\_id</code></td>
          <td><code>client.client\_id</code></td>
          <td>Unchanged</td>
        </tr>

        <tr>
          <td><code>client.name</code></td>
          <td><code>client.name</code></td>
          <td>Unchanged</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="User data">
    <table>
      <thead>
        <tr>
          <th><b> <code>send-phone-message</code> context object </b></th>
          <th><b>Tenant-level provider context object</b></th>
          <th><b> Status </b></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>user.user\_id</code></td>
          <td><code>user.user\_id</code></td>
          <td>Unchanged</td>
        </tr>

        <tr>
          <td><code>user.name</code></td>
          <td><code>user.name</code></td>
          <td>Unchanged</td>
        </tr>

        <tr>
          <td><code>user.email</code></td>
          <td><code>user.email</code></td>
          <td>Unchanged</td>
        </tr>

        <tr>
          <td><code>user.app\_metadata</code></td>
          <td><code>user.app\_metadata</code></td>
          <td>Unchanged</td>
        </tr>

        <tr>
          <td><code>user.user\_metadata</code></td>
          <td><code>user.user\_metadata</code></td>
          <td>Unchanged</td>
        </tr>

        <tr>
          <td><code>user.email\_verified</code></td>
          <td><code>user.email\_verified</code></td>
          <td>Unchanged</td>
        </tr>

        <tr>
          <td><code>user.phone\_number</code></td>
          <td><code>user.phone\_number</code></td>
          <td>Unchanged</td>
        </tr>

        <tr>
          <td><code>user.phone\_verified</code></td>
          <td><code>user.phone\_verified</code></td>
          <td>Unchanged</td>
        </tr>

        <tr>
          <td><code>user.picture</code></td>
          <td><code>user.picture</code></td>
          <td>Unchanged</td>
        </tr>

        <tr>
          <td><code>user.created\_at</code></td>
          <td><code>user.created\_at</code></td>
          <td>Unchanged</td>
        </tr>

        <tr>
          <td><code>user.updated\_at</code></td>
          <td><code>user.updated\_at</code></td>
          <td>Unchanged</td>
        </tr>

        <tr>
          <td><code>user.multifactor</code></td>
          <td><code>user.multifactor</code></td>
          <td>Unchanged</td>
        </tr>

        <tr>
          <td><code>user.identities</code></td>
          <td>N/A</td>
          <td>Removed</td>
        </tr>

        <tr>
          <td><code>user.family\_name</code></td>
          <td><code>user.family\_name</code></td>
          <td>Unchanged</td>
        </tr>

        <tr>
          <td><code>user.given\_name</code></td>
          <td><code>user.given\_name</code></td>
          <td>Unchanged</td>
        </tr>

        <tr>
          <td><code>user.nickname</code></td>
          <td><code>user.nickname</code></td>
          <td>Unchanged</td>
        </tr>

        <tr>
          <td><code>user.username</code></td>
          <td><code>user.username</code></td>
          <td>Unchanged</td>
        </tr>

        <tr>
          <td>N/A</td>
          <td><code>user.login\_count</code></td>
          <td>New</td>
        </tr>
      </tbody>
    </table>
  </Accordion>
</AccordionGroup>

For a complete list of the contextual variables, read [Customize Phone Templates](/docs/customize/phone-messages/customize-phone-templates).

Review the custom phone provider example:

```javascript lines expandable theme={null}
const { fetch } = require('undici');
/**
* Handler to be executed while sending a phone notification
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {CustomPhoneProviderAPI} api - Methods and utilities to help change the behavior of sending a phone notification.
*/
exports.onExecuteCustomPhoneProvider = async (event, api) => {

  if (event.notification.message_type.startsWith('otp')) {
    const body = {
      from: event.notification.from,
      action: event.notification.message_type === 'otp_verify' ? 'second-factor-authenticator' : 'enrollment',
      language: event.notification.locale,
      recipient: event.notification.recipient,
      message_type: event.notification.delivery_method,
      text: event.notification.as_text,
      code: event.notification.code,
    };

    const response = await fetch(event.secrets['MY_ENDPOINT'], {
      method: 'POST',
      headers: {
        authorization: `Bearer ${event.secrets['MY_SECRET']}`,
      },
      body: JSON.stringify(body),
    });

    console.log(response.status); // 200
    console.log(await response.text()); // request's response body!
  }

  return;
};
```

#### Configure MFA custom-phone-provider

To continue and configure your MFA `custom-phone-provider` trigger:

1. Navigate to [**Branding > Phone Provider**](https://manage.auth0.com/#/phone/templates/phone/provider).
2. Select your provider:

   1. Choose **Custom**.
   2. Under **Provider Configuration**, add your translated `send-phone-message` Action code in the embedded code editor.
3. **Save** your changes.
4. Select **Send Test Message** to test the tenant-level provider before using it in a production environment.
5. Navigate back to [**Security > Multi-factor Auth > Phone Message**](https://manage.auth0.com/#/security/mfa) to enable the **Use Tenant-level Messaging Provider**.
6. **Save** your changes.

### Update MFA phone factors and delivery methods

<Warning>
  If you have not enabled a tenant-level provider in the Auth0 Dashboard, you won’t be able to configure phone SMS and voice phone factors for MFA.

  <Frame>
    <img alt="Unified phone MFA no tenant provider configured warning" />
  </Frame>
</Warning>

If you want to update the current notification MFA factor(s) to a different type during the migration to the Unified Phone Experience, some configuration changes may be necessary.

<table>
  <thead>
    <tr>
      <th><b>Current MFA Phone factors</b></th>
      <th><b>Desired MFA factors</b></th>
      <th><b>Tenant-level delivery method</b></th>
      <th><b>User action</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>SMS</td>
      <td>Voice</td>
      <td>SMS</td>
      <td>User must update tenant-level provider to allow for desired MFA phone factor</td>
    </tr>

    <tr>
      <td>SMS</td>
      <td>Voice</td>
      <td>SMS + Voice</td>
      <td>None</td>
    </tr>

    <tr>
      <td>SMS</td>
      <td>SMS + Voice</td>
      <td>SMS</td>
      <td>User must update tenant-level provider to allow for desired MFA phone factor</td>
    </tr>

    <tr>
      <td>SMS</td>
      <td>SMS + Voice</td>
      <td>SMS + Voice</td>
      <td>None</td>
    </tr>

    <tr>
      <td>Voice</td>
      <td>SMS</td>
      <td>SMS + Voice</td>
      <td>User must update tenant-level provider to allow for desired MFA phone factor</td>
    </tr>

    <tr>
      <td>Voice</td>
      <td>SMS</td>
      <td>SMS + Voice</td>
      <td>None</td>
    </tr>

    <tr>
      <td>Voice</td>
      <td>SMS + Voice</td>
      <td>Voice</td>
      <td>User must update tenant-level provider to allow for desired MFA phone factor</td>
    </tr>

    <tr>
      <td>Voice</td>
      <td>SMS + Voice</td>
      <td>SMS + Voice</td>
      <td>None</td>
    </tr>

    <tr>
      <td>SMS + Voice</td>
      <td>SMS</td>
      <td>SMS + Voice</td>
      <td>None</td>
    </tr>

    <tr>
      <td>SMS + Voice</td>
      <td>Voice</td>
      <td>SMS + Voice</td>
      <td>None</td>
    </tr>
  </tbody>
</table>

If you want to update the current tenant-level phone provider delivery method(s) to a different type during the migration to the Unified Phone Experience, some configuration changes may be necessary.

<table>
  <thead>
    <tr>
      <th><b>MFA Phone factors</b></th>
      <th><b>Current tenant-level delivery method</b></th>
      <th><b>Desired tenant-level delivery method</b></th>
      <th><b>User action</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>SMS</td>
      <td>SMS</td>
      <td>SMS + Voice</td>
      <td>None</td>
    </tr>

    <tr>
      <td>SMS</td>
      <td>SMS</td>
      <td>Voice</td>
      <td>User must update MFA phone factors to be a subset of the delivery methods enabled for the tenant-level provider</td>
    </tr>

    <tr>
      <td>SMS</td>
      <td>SMS + Voice</td>
      <td>Voice</td>
      <td>User must update MFA phone factors to be a subset of the delivery methods enabled for the tenant-level provider</td>
    </tr>

    <tr>
      <td>SMS</td>
      <td>SMS + Voice</td>
      <td>SMS</td>
      <td>None</td>
    </tr>

    <tr>
      <td>Voice</td>
      <td>Voice</td>
      <td>SMS</td>
      <td>User must update MFA phone factors to be a subset of the delivery methods enabled for the tenant-level provider</td>
    </tr>

    <tr>
      <td>Voice</td>
      <td>Voice</td>
      <td>SMS + Voice</td>
      <td>None</td>
    </tr>

    <tr>
      <td>Voice</td>
      <td>SMS + Voice</td>
      <td>SMS</td>
      <td>User must update MFA phone factors to be a subset of the delivery methods enabled for the tenant-level provider</td>
    </tr>

    <tr>
      <td>Voice</td>
      <td>SMS + Voice</td>
      <td>Voice</td>
      <td>None</td>
    </tr>

    <tr>
      <td>SMS + Voice</td>
      <td>SMS + Voice</td>
      <td>SMS</td>
      <td>None</td>
    </tr>

    <tr>
      <td>SMS + Voice</td>
      <td>SMS + Voice</td>
      <td>Voice</td>
      <td>None</td>
    </tr>
  </tbody>
</table>

### Update Guardian endpoints with Management API

The Unified Phone Experience uses specific endpoints for notifications. If you’ve been using [Auth0 Guardian](/docs/secure/multi-factor-authentication/auth0-guardian) for push notifications and one-time passwords, you must update your configuration to use the new Phone Provider Branding endpoints.

The following Guardian endpoints will no longer work with the Unified Phone Experience:

<table>
  <thead>
    <tr>
      <th><b>Send-phone-message Guardian endpoint</b></th>
      <th><b>Scope</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><ul><li><a href="https://auth0.com/docs/api/management/v2/guardian/get-phone-twilio-factor-provider">Get Twilio configuration</a></li><li><a href="https://auth0.com/docs/api/management/v2/guardian/get-sms-twilio-factor-provider">Get Twilio SMS configuration</a></li></ul></td>
      <td><code>read:guardian\_factors</code></td>
    </tr>

    <tr>
      <td><ul><li><a href="https://auth0.com/docs/api/management/v2/guardian/get-guardian-phone-providers">Get phone provider configuration</a></li><li><a href="https://auth0.com/docs/api/management/v2/guardian/get-sms-providers">Get phone provider SMS configuration</a></li></ul></td>
      <td><code>read:guardian\_factors</code></td>
    </tr>

    <tr>
      <td><ul><li><a href="https://auth0.com/docs/api/management/v2/guardian/put-twilio">Update Twilio configuration</a></li><li><a href="https://auth0.com/docs/api/management/v2/guardian/put-sms-twilio-factor-provider">Update Twilio SMS configuration</a></li></ul></td>
      <td><code>update:guardian\_factors</code></td>
    </tr>

    <tr>
      <td><ul><li><a href="https://auth0.com/docs/api/management/v2/guardian/put-phone-providers">Update phone provider configuration</a></li><li><a href="https://auth0.com/docs/api/management/v2/guardian/put-sms-providers">Update SMS configuration</a></li></ul></td>
      <td><code>update:guardian\_factors</code></td>
    </tr>

    <tr>
      <td><ul><li><a href="https://auth0.com/docs/api/management/v2/guardian/get-factor-phone-templates">Get enrollment and verification phone templates</a></li><li><a href="https://auth0.com/docs/api/management/v2/guardian/get-factor-sms-templates">Get SMS enrollment and verification templates</a></li></ul></td>
      <td><code>read:guardian\_factors</code></td>
    </tr>

    <tr>
      <td><ul><li><a href="https://auth0.com/docs/api/management/v2/guardian/put-factor-phone-templates">Update enrollment and verification phone templates</a></li><li><a href="https://auth0.com/docs/api/management/v2/guardian/put-factor-sms-templates">Update SMS enrollment and verification templates</a></li></ul></td>
      <td><code>update:guardian\_factors</code></td>
    </tr>
  </tbody>
</table>

Replace the Guardian endpoints with the new Phone Provider Branding endpoints and scopes:

<table>
  <thead>
    <tr>
      <th><b>Phone Provider Branding endpoint</b></th>
      <th><b>Scope</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><ul><li><a href="https://auth0.com/docs/api/management/v2/branding/get-branding-phone-providers">Get the phone providers set for a tenant</a></li><li><a href="https://auth0.com/docs/api/management/v2/branding/get-phone-provider">Get the phone provider</a></li></ul></td>
      <td><code>read:phone\_providers</code></td>
    </tr>

    <tr>
      <td><ul><li><a href="https://auth0.com/docs/api/management/v2/branding/update-phone-provider">Update the phone provider</a></li></ul></td>
      <td><code>update:phone\_providers</code></td>
    </tr>

    <tr>
      <td><ul><li><a href="https://auth0.com/docs/api/management/v2/branding/create-phone-provider">Configure the phone provider</a></li></ul></td>
      <td><code>create:phone\_providers</code></td>
    </tr>

    <tr>
      <td><ul><li><a href="https://auth0.com/docs/api/management/v2/branding/get-phone-templates">Get list of phone notification templates</a></li><li><a href="https://auth0.com/docs/api/management/v2/branding/get-phone-template">Get a phone notification template</a></li></ul></td>
      <td><code>read:phone\_templates</code></td>
    </tr>

    <tr>
      <td><ul><li><a href="https://auth0.com/docs/api/management/v2/branding/update-phone-template">Update a phone notification template</a></li></ul></td>
      <td><code>update:phone\_templates</code></td>
    </tr>

    <tr>
      <td><ul><li><a href="https://auth0.com/docs/api/management/v2/branding/create-phone-template">Create a phone notification template</a></li></ul></td>
      <td><code>create:phone\_templates</code></td>
    </tr>

    <tr>
      <td><ul><li><a href="https://auth0.com/docs/api/management/v2/branding/delete-phone-provider">Delete a phone template</a></li></ul></td>
      <td><code>delete:phone\_templates</code></td>
    </tr>

    <tr>
      <td><ul><li><a href="https://auth0.com/docs/api/management/v2/branding/delete-phone-provider">Delete a phone provider</a></li></ul></td>
      <td><code>delete:phone\_providers</code></td>
    </tr>
  </tbody>
</table>

The following Guardian endpoints work with the Unified Phone Experience and will not need to be updated:

<table>
  <thead>
    <tr>
      <th><b>MFA phone factor endpoint</b></th>
      <th><b>Scope</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><ul><li><a href="https://auth0.com/docs/api/management/v2/guardian/get-message-types">Get enabled phone factors</a></li></ul></td>
      <td><code>read:guardian\_factors</code></td>
    </tr>

    <tr>
      <td><ul><li><a href="https://auth0.com/docs/api/management/v2/guardian/put-message-types">Update enabled phone factors</a></li></ul></td>
      <td><code>update:guardian\_factors</code></td>
    </tr>

    <tr>
      <td><ul><li><a href="https://auth0.com/docs/api/management/v2/guardian/get-guardian-phone-providers">Get phone provider configuration</a></li></ul></td>
      <td><code>read:guardian\_factors</code></td>
    </tr>

    <tr>
      <td><ul><li><a href="https://auth0.com/docs/api/management/v2/guardian/put-phone-providers">Update phone provider configuration</a></li></ul></td>
      <td><code>update:guardian\_factors</code></td>
    </tr>
  </tbody>
</table>

## Disable phone provider

If you configure the Unified Phone Experience and then disable it, existing integrations with your phone provider, including MFA, could break.

<Frame>
  <img alt="" />
</Frame>


# Actions Unit Test
Source: https://auth0.com/docs/customize/actions/actions-unit-test

The **Actions NPM (`@auth0/actions`)** package enables the use of TypeScript development on external projects, allowing developers to follow best practices and improve their **Unit Testing** based on the TypeScript definitions.

# Auth0 Actions Unit Test

The **Actions NPM (`@auth0/actions`)** package enables the use of TypeScript development on external projects, allowing developers to follow best practices and improve their unit testing based on the TypeScript definitions.

***

## How it works

Follow the installation and import guidelines described at: [How Actions NPM works](/docs/customize/actions/actions-npm#how-it-works).

To unit test an Action, you must mock the `event` and `api` objects that your Action function receives. You can create these mocks using the TypeScript definitions included in `auth0/actions`, which ensures your tests accurately reflect the production environment. Testing frameworks like Jest are ideal for managing mocking and functionality.

The Unit Tests can be run in a local environment, version control, or CI/CD process, improving the overall quality assurance and validations before impacting changes on Auth0 Tenants.

***

## Examples

The following examples provide validation for a series of scenarios by mocking the necessary objects.

<Note>
  The examples use **Jest** (`https://www.npmjs.com/package/jest`), but any testing library can be used.
</Note>

### Configuration

In your `package.json`, define any development dependencies to have IntelliSense help when writing your Action.

<Tabs>
  <Tab title="Javascript">
    ```javascript theme={null}
    {
      "name": "actions-js",
      "version": "1.0.0",
      "description": "Actions JS",
      "main": "example.js",
      "scripts": {
        "test": "jest"
      },
      "author": "John Doe",
      "license": "ISC",
      "devDependencies": {
        "@auth0/actions": "^0.7.1",
        "jest": "^29.7.0"
      }
    }
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    {
      "name": "actions-ts",
      "version": "1.0.0",
      "description": "Actions TS",
      "main": "example.ts",
      "scripts": {
        "test": "jest"
      },
      "author": "John Doe",
      "license": "ISC",
      "devDependencies": {
        "@auth0/actions": "^0.7.1",
        "@types/jest": "^29.5.12",
        "@types/node": "22.14.0",
        "jest": "^29.7.0",
        "ts-jest": "^29.1.2",
        "typescript": "^5.9.2"
      }
    }
    ```

    In your `tsconfig.json` file, define how the TypeScript compiler should work:

    ```typescript theme={null}
    {
      "compilerOptions": {
        "target": "ES2020",
        "module": "NodeNext",
        "moduleResolution": "nodenext",
        "esModuleInterop": true,
        "allowSyntheticDefaultImports": true,
        "strict": true,
        "outDir": "dist",
        "declaration": true,
        "sourceMap": true,
        "allowJs": true,
        "checkJs": false,
        "resolveJsonModule": true,
        "skipLibCheck": true,
        "forceConsistentCasingInFileNames": true,
        "isolatedModules": true
      },
      "include": [
        "**/*.ts"
      ],
      "exclude": [
        "node_modules",
        "dist"
      ]
    }
    ```

    In your `jest.config.js`, define `Jest` environment presets:

    ```typescript theme={null}
    module.exports = {
      preset: 'ts-jest',
      testEnvironment: 'node',
    };
    ```
  </Tab>
</Tabs>

## Pre-user registration access control and user metadata setup

The following example Action checks if the user email has a forbidden email domain, and calls `api.access.deny()` when matching. Otherwise, it checks if the full name has being provided through Custom Prompts additional fields and proceeds to set the full name at the user profile `user_metadata`, otherwise sends a validation error to Universal Login.

<Tabs>
  <Tab title="Javascript">
    ```javascript theme={null}
    /** @import {Event, PreUserRegistrationAPI} from "@auth0/actions/pre-user-registration/v2" */

    /**
    * Handler that will be called during the execution of a PreUserRegistration flow.
    *
    * @param {Event} event - Details about the context and user that is attempting to register.
    * @param {PreUserRegistrationAPI} api - Interface whose methods can be used to change the behavior of the signup.
    */
    exports.onExecutePreUserRegistration = async (event, api) => {
      const user = event.user;

      if (user.email?.endsWith('@example.com')) {
        api.access.deny('forbidden', 'Forbidden email domain')
        return;
      }

      const fullName = event.request.body['ulp-fullName'];

      if (fullName === undefined) {
        api.validation.error('invalid_payload', 'Missing full name');
        return;
      }

      api.user.setUserMetadata('full_name', fullName);
    }
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import type { Event, PreUserRegistrationAPI } from '@auth0/actions/pre-user-registration/v2';

    /**
    * Handler that will be called during the execution of a PreUserRegistration flow.
    *
    * @param {Event} event - Details about the context and user that is attempting to register.
    * @param {PreUserRegistrationAPI} api - Interface whose methods can be used to change the behavior of the signup.
    */
    exports.onExecutePreUserRegistration = async (event: Event, api: PreUserRegistrationAPI) => {
      const user = event.user;

      if (user.email?.endsWith('@example.com')) {
        api.access.deny('forbidden', 'Forbidden email domain')
        return;
      }

      const fullName = event.request.body['ulp-fullName'];

      if (fullName === undefined) {
        api.validation.error('invalid_payload', 'Missing full name');
        return;
      }

      api.user.setUserMetadata('full_name', fullName);
    };
    ```
  </Tab>
</Tabs>

The Unit Test performs some validations to maximize code coverage, by mocking `event` and `api` objects.

<Tabs>
  <Tab title="Javascript">
    ```javascript theme={null}
    const { onExecutePreUserRegistration } = require('./preUserRegistration');

    describe('onExecutePreUserRegistration', () => {
      const mockApi = {
        access: {
          deny: jest.fn(),
        },
        user: {
          setUserMetadata: jest.fn(),
        },
        validation: {
          error: jest.fn(),
        },
      };

      beforeEach(() => {
        jest.resetAllMocks();
      });

      afterEach(() => {
        jest.resetAllMocks();
      });

      it('forbids email domain', async () => {
        const mockEvent = {
          user: {
            email: 'johndoe@example.com',
          }
        };

        await onExecutePreUserRegistration(mockEvent, mockApi);

        expect(mockApi.access.deny).toHaveBeenCalledWith('forbidden', 'Forbidden email domain');
        expect(mockApi.validation.error).not.toHaveBeenCalled();
        expect(mockApi.user.setUserMetadata).not.toHaveBeenCalled();
      });

      it('allows email domain without full name', async () => {
        const mockEvent = {
          request: {
            body: {},
          },
          user: {
            email: 'johndoe@test.com',
          },
        };

        await onExecutePreUserRegistration(mockEvent, mockApi);

        expect(mockApi.access.deny).not.toHaveBeenCalled();
        expect(mockApi.validation.error).toHaveBeenCalledWith('invalid_payload', 'Missing full name');
        expect(mockApi.user.setUserMetadata).not.toHaveBeenCalled();
      });

      it('allows email domain with full name', async () => {
        const mockEvent = {
          request: {
            body: {
              'ulp-fullName': 'John Doe'
            },
          },
          user: {
            email: 'johndoe@test.com',
          },
        };

        await onExecutePreUserRegistration(mockEvent, mockApi);

        expect(mockApi.access.deny).not.toHaveBeenCalled();
        expect(mockApi.validation.error).not.toHaveBeenCalled();
        expect(mockApi.user.setUserMetadata).toHaveBeenCalledWith('full_name', 'John Doe');
      });
    });
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const { onExecutePreUserRegistration } = require('./preUserRegistration');

    describe('onExecutePreUserRegistration', () => {
      const mockApi = {
        access: {
          deny: jest.fn(),
        },
        user: {
          setUserMetadata: jest.fn(),
        },
        validation: {
          error: jest.fn(),
        },
      };

      beforeEach(() => {
        jest.resetAllMocks();
      });

      afterEach(() => {
        jest.resetAllMocks();
      });

      it('forbids email domain', async () => {
        const mockEvent = {
          user: {
            email: 'johndoe@example.com',
          }
        };

        await onExecutePreUserRegistration(mockEvent, mockApi);

        expect(mockApi.access.deny).toHaveBeenCalledWith('forbidden', 'Forbidden email domain');
        expect(mockApi.validation.error).not.toHaveBeenCalled();
        expect(mockApi.user.setUserMetadata).not.toHaveBeenCalled();
      });

      it('allows email domain without full name', async () => {
        const mockEvent = {
          request: {
            body: {},
          },
          user: {
            email: 'johndoe@test.com',
          },
        };

        await onExecutePreUserRegistration(mockEvent, mockApi);

        expect(mockApi.access.deny).not.toHaveBeenCalled();
        expect(mockApi.validation.error).toHaveBeenCalledWith('invalid_payload', 'Missing full name');
        expect(mockApi.user.setUserMetadata).not.toHaveBeenCalled();
      });

      it('allows email domain with full name', async () => {
        const mockEvent = {
          request: {
            body: {
              'ulp-fullName': 'John Doe'
            },
          },
          user: {
            email: 'johndoe@test.com',
          },
        };

        await onExecutePreUserRegistration(mockEvent, mockApi);

        expect(mockApi.access.deny).not.toHaveBeenCalled();
        expect(mockApi.validation.error).not.toHaveBeenCalled();
        expect(mockApi.user.setUserMetadata).toHaveBeenCalledWith('full_name', 'John Doe');
      });
    });
    ```
  </Tab>
</Tabs>

## Custom email provider and HTTP request

The following example Action attempts to send a message via HTTP request to an external service, handling the potential request error to drop the notification. It uses secrets for the external service URL and authorization API Key.

<Tabs>
  <Tab title="Javascript">
    ```javascript theme={null}
    /** @import {Event, CustomEmailProviderAPI} from "@auth0/actions/custom-email-provider/v1" */

    /**
    * Handler to be executed while sending an email notification
    *
    * @param {Event} event - Details about the user and the context in which they are logging in.
    * @param {CustomEmailProviderAPI} api - Methods and utilities to help change the behavior of sending a email notification.
    */
    exports.onExecuteCustomEmailProvider = async (event, api) => {
      const notification = event.notification;
      const message = {
        body: notification.html
      };

      try {
        await fetch(event.secrets.URL, {
          method: 'POST',
          headers: {
            'X-API-Key': event.secrets.API_KEY,
          },
          body: JSON.stringify(message),
        });
      } catch (err) {
        api.notification.drop('External service failure');
      }
    }

    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    /** @import {Event, CustomEmailProviderAPI} from "@auth0/actions/custom-email-provider/v1" */

    /**
    * Handler to be executed while sending an email notification
    *
    * @param {Event} event - Details about the user and the context in which they are logging in.
    * @param {CustomEmailProviderAPI} api - Methods and utilities to help change the behavior of sending a email notification.
    */
    exports.onExecuteCustomEmailProvider = async (event, api) => {
      const notification = event.notification;
      const message = {
        body: notification.html
      };

      try {
        await fetch(event.secrets.URL, {
          method: 'POST',
          headers: {
            'X-API-Key': event.secrets.API_KEY,
          },
          body: JSON.stringify(message),
        });
      } catch (err) {
        api.notification.drop('External service failure');
      }
    }

    ```
  </Tab>
</Tabs>

The Unit Test performs some validations to maximize code coverage, by mocking event and api objects, in addition to the fetch function.

<Tabs>
  <Tab title="Javascript">
    ```javascript theme={null}
    const { onExecuteCustomEmailProvider } = require('./customEmailProvider');

    describe('onExecuteCustomEmailProvider', () => {
      const mockApi = {
        notification: {
          drop: jest.fn(),
        },
      };

      const mockEvent = {
        notification: {
          html: '<h1>Hello world</h1>',
        },
        secrets: {
          URL: 'https://example.com/service',
          API_KEY: 'ApiKeySecret1234.',
        },
        user: {
          email: 'johndoe@example.com',
        },
      };

      beforeEach(() => {
        jest.resetAllMocks();
      });

      afterEach(() => {
        jest.resetAllMocks();
      });

      it('succeeds on external service request', async () => {
        jest.spyOn(global, 'fetch').mockImplementationOnce(() => Promise.resolve({
          ok: true,
          status: 200,
          json: async () => ({ message: 'Success!' }),
        }));

        await onExecuteCustomEmailProvider(mockEvent, mockApi);

        expect(global.fetch).toHaveBeenCalled();
        expect(mockApi.notification.drop).not.toHaveBeenCalled();
      });

      it('fails on external service request', async () => {
        jest.spyOn(global, 'fetch').mockImplementationOnce(() => Promise.reject({
          ok: false,
          status: 500,
          json: async () => ({ error: 'Server Error' }),
        }));

        await onExecuteCustomEmailProvider(mockEvent, mockApi);

        expect(mockApi.notification.drop).toHaveBeenCalledWith('External service failure');
      });
    });

    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const { onExecuteCustomEmailProvider } = require('./customEmailProvider');

    describe('onExecuteCustomEmailProvider', () => {
      const mockApi = {
        notification: {
          drop: jest.fn(),
        },
      };

      const mockEvent = {
        notification: {
          html: '<h1>Hello world</h1>',
        },
        secrets: {
          URL: 'https://example.com/service',
          API_KEY: 'ApiKeySecret1234.',
        },
        user: {
          email: 'johndoe@example.com',
        },
      };

      beforeEach(() => {
        jest.resetAllMocks();
      });

      afterEach(() => {
        jest.resetAllMocks();
      });

      it('succeeds on external service request', async () => {
        jest.spyOn(global, 'fetch').mockImplementationOnce(() => Promise.resolve({
          ok: true,
          status: 200,
          json: async () => ({ message: 'Success!' }),
        } as Response));

        await onExecuteCustomEmailProvider(mockEvent, mockApi);

        expect(global.fetch).toHaveBeenCalled();
        expect(mockApi.notification.drop).not.toHaveBeenCalled();
      });

      it('fails on external service request', async () => {
        jest.spyOn(global, 'fetch').mockImplementationOnce(() => Promise.reject({
          ok: false,
          status: 500,
          json: async () => ({ error: 'Server Error' }),
        } as Response));

        await onExecuteCustomEmailProvider(mockEvent, mockApi);

        expect(mockApi.notification.drop).toHaveBeenCalledWith('External service failure');
      });
    });

    ```
  </Tab>
</Tabs>

To learn more about `@auth0/actions`, visit: [https://www.npmjs.com/package/@auth0/actions](https://www.npmjs.com/package/@auth0/actions).

To learn more about writing Actions, read [Write Your First Action](/docs/customize/actions/write-your-first-action).


# Manage Dependencies
Source: https://auth0.com/docs/customize/actions/manage-dependencies

Learn how to install and manage dependencies inside of Auth0 Actions.

Actions allows you to use packages from the [`npm` registry](https://www.npmjs.com/). You can install and manage dependencies for your Actions using either the Actions Code Editor in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## Add a dependency using the Actions Code Editor

To add a dependency on a package from the public `npm` registry:

1. Navigate to [Auth0 Dashboard > Actions > Library](https://manage.auth0.com/#/actions/library), and select your Action.

2. Locate the Actions Code Editor, and select Modules (cube icon) in its sidebar.

3. Select **Add Module**,and enter the name of the module. To use the latest available version of the package, you can leave the version field blank.

4. In your Actions code, require the module. For example, if you added the Axios package, you would add the following line at the top of your code in the Actions Code Editor:

   ```javascript lines theme={null}
   const axios = require('axios');
   ```

## Add a dependency using the Auth0 Management API

Alternatively, you can add a dependency using the Auth0 Management API's [Create Action endpoint](https://auth0.com/docs/api/management/v2#!/Actions/post_action). When calling the endpoint, specify the dependencies in the payload:

```bash lines theme={null}
curl -H "Authorization: Bearer {managementApiToken}" \
     -X POST  -H "Content-Type: application/json" \
     -d '{ \
            "name":"my-action", \
            "supported_triggers":[{"id":"post-login","version":"v2"}], \
            "code":"module.exports = () => {}",\
            "dependencies": [{\
                "name":"lodash",\
                "version":"4.17.21"\
            }],\
            "runtime":"node14"\
        }' \
    https://{yourTenant}.com/api/v2/actions/actions
```

## Security considerations

Third-party packages can contain vulnerabilities and malicious code, so we recommend auditing packages before using them in your Actions. We also recommend that you continuously monitor packages for vulnerabilities using software composition analysis tools.

## Limitations for dependencies in Actions

### No native module support

Native modules cannot be used in Actions. When executing an Action that depends on a native module, the Action will error with a message containing `Compilation failed: Cannot find module`.

To check whether an `npm` package is native, navigate to the public Github repository for the `npm` package and review the languages the code uses in the sidebar. If the languages include C/C++, the package is likely native. Popular examples include `bcrypt` and `sqlite3`.

### No private module or private registry support

Private `npm` modules and private `npm` registries cannot be used with Actions. Actions uses the [public `npm` registry](https://registry.npmjs.org).


# Manage Versions
Source: https://auth0.com/docs/customize/actions/manage-versions

Learn about the Actions version history, which allows you to compare between drafted and deployed versions of Actions, and revert to previous versions when necessary.

With the Actions version history, you can compare between drafted and deployed versions of Actions, and revert to previous versions when necessary.

## Deploy Actions

Before an Action can be bound to a flow, the Action must be deployed.

1. Navigate to [Auth0 Dashboard > Actions > Custom Actions](https://manage.auth0.com/#/actions/library).
2. Choose your Action.
3. Select **Deploy**.

The selected Action will be deployed and added to the collection of available actions for flows. Additionally, a new draft version of the deployed Action will be created for future editing. Because secrets and dependencies are tied to versions, any saved secrets or dependencies will be available to the new draft.

## Revert Actions

When necessary, you can revert to the last known good version of an Action.

1. Navigate to [Auth0 Dashboard > Actions > Custom Actions](https://manage.auth0.com/#/actions/library).
2. Choose your Action.
3. Select **Version History**.
4. Select the version to which you want to revert, and click **Revert**.

   <Callout icon="file-lines">
     In the version history, “Draft” denotes a version that has never been deployed.
   </Callout>

A new copy of the selected version will be created and deployed. Additionally, a new draft version of the deployed Action will be created for future editing. Because secrets and dependencies are tied to versions, any saved secrets or dependencies will be available to the new draft.


# Migrate to Actions
Source: https://auth0.com/docs/customize/actions/migrate

Learn how to migrate to Actions from Rules, Hooks, and earlier versions of Actions.

To take advantage of the features provided by Auth0 Actions, you may need to migrate current code from Rules, Hooks, and earlier versions of Actions.

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/customize/actions/migrate/migrate-from-rules-to-actions">Migrate from Rules to Actions</a></td>
      <td>How to convert your existing Rules to post-login Actions.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/actions/migrate/migrate-a-rule-to-an-action">Migration Tooling</a></td>
      <td>How to use the Migration Tool to migrate from Rules to Actions.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/actions/migrate/migrate-from-hooks-to-actions">Migrate from Hooks to Actions</a></td>
      <td>How to convert your existing Hooks to Actions.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/actions/migrate/migrate-from-actions-beta-to-final">Migrate from Actions Beta To Final</a></td>
      <td>How to migrate Actions that you created during the Actions Beta period.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/actions/migrate/actions-migration-limitations">Actions Migration Limitations</a></td>
      <td>Explore the current limitations when migrating between legacy extensibility offerings and Actions.</td>
    </tr>
  </tbody>
</table>


# Actions Migration Limitations
Source: https://auth0.com/docs/customize/actions/migrate/actions-migration-limitations

Limitations for migration-specific activities when migrating from Rules & Hooks to Actions

To take advantage of the features provided by Auth0 Actions, you may need to migrate your current code from Rules, Hooks, or earlier versions of Actions. However, you should be aware of the current limitations when migrating between legacy extensibility offerings and Actions.

For more information, see [Migrate to Actions](/docs/customize/actions/migrate).

## Rule specific differences

* Re-use of functions between Actions is not currently supported, as each Action execution is autonomous. You must explicitly define the required functions for each Action.
* [`accessToken`](/docs/libraries/lock/lock-api-reference#getuserinfo-) is currently limited to 100 scopes.
* The event object in Actions does not currently provide an alternative for the following [context attributes](/docs/customize/rules/context-object)from within a Rule:

  * `context.connectionOptions`
* Actions only support the following properties within [`event.user.identities`](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object):

  * `connection`
  * `provider`
  * `user_id`
  * `profileData`
  * `isSocial`

<Callout icon="file-lines">
  If you are using additional properties within `user.identities` object in Rules, they are not supported within an Action. This includes any token from upstream IdP for federated users.
</Callout>

* Standard claims of an `idToken` or `accessToken` cannot be deleted using an Action.
* Actions can only return `access denied`error codes and does not support returning an `unauthorized` error code.
* Actions only support modifying the primary user between linked accounts.

## Hooks specific differences

* You can not modify scopes in a machine-to-machine client credential flowas was possible with a Hook.


# Migration tooling
Source: https://auth0.com/docs/customize/actions/migrate/migrate-a-rule-to-an-action

Description on how to use the Rule migration tooling in the Auth0 dashboard

Simplify the migration process of Rules to Actions by using the Rule Migration tooling in the [Auth0 Dashboard](https://manage.auth0.com/). In addition to facilitating the switch from a Rule to an Action, the new tooling also offers built-in guidance and fixes for common Rule patterns.

## Before migration

Before you start the migration, visit [Migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions). This migration guide is an excellent resource that explains the differences between Rules and Actions and is a helpful tool in the migration journey.

### Rule migration order

Rules execute before Actions, which implies that Rules should be migrated in reverse runtime order. Migrate the last Rule to execute in your existing flow and work your way to the first Rule in reverse, chronological order.

Failing to migrate in this order can result in errors due to unanticipated side effects caused by dependencies in the ordering of Rules and Actions.

### Safely rolling back

The migration tooling allows you to safely and easily roll back if something goes wrong. Re-enable your Rule and skip the corresponding Action logic.

## Migrating a Rule

To begin migrating your Rule, select **Auth Pipeline > Rules**. Once selected, your Rules appear with an option to migrate each of them individually.

<Frame>
  <img alt="" />
</Frame>

<Callout icon="file-lines">
  Only migration begins when you chose Migrate to Action. As a developer, you can choose when to activate the new Action.
</Callout>

### Migrate to Action

After selecting **Migrate to Action**, the tooling prompts you to create a new Action.

<Frame>
  <img alt="" />
</Frame>

After you select **Create,** the new Action is created and you are presented with the Actions Editor.

<Frame>
  <img alt="" />
</Frame>

If the Rule is migrated to Actions and still active, the Rule exits before the logic runs.

This runs by calling `api.rules.wasExecuted()`. If the `wasExecuted` function consumes a string containing the Rule ID, it returns `true` if the Rule has already run (and otherwise, returns `false`).

This is a helpful tool to prevent your logic from running twice. As soon as you disable the referenced Rule, the function returns `false` and the business logic now executes in the Action.

<Callout icon="file-lines">
  The Rule ID value populates automatically for any rule that is migrated using the **Migrate to Action** feature.
</Callout>

For more information about the `api.rules.wasExecuted()` function, refer to [Actions Triggers: post-login - API Object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object).

## Rewrite Rule code

Select the **Rules** button in the Actions Editor to load the Rules Migration tool. There, you can quickly reference the code of the migrated Rule. You should review the code of the selected Rule in the sidebar.

Copy the contents of the Rule function and paste it under the `// YOUR CODE HERE` comment in the Action. It’s likely that this code is not adapted for the Actions programming model.

<Frame>
  <img alt="" />
</Frame>

The Actions Editor provides feedback where code must be refactored. The editor also provides suggestions on how to automatically fix most situations - to review the suggestion or fix, hover over the underlined code:

<Frame>
  <img alt="" />
</Frame>

You may be able to apply Action-specific updates by selecting an option from the **Quick Fix** modal.

<Frame>
  <img alt="" />
</Frame>

When you select the recommended fix, your code automatically updates to be compatible.

<Frame>
  <img alt="" />
</Frame>

There are some situations where fixes cannot be applied automatically but guidance is still provided:

<Frame>
  <img alt="" />
</Frame>

For example: in the case of the Rule’s `callback` function, it is recommended to use [`api.access.deny`](/docs/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger/pre-user-registration-api-object) for errors, or just `return` in successful cases.

### Test the new Action

Actions can be tested directly in the editor, as this is an essential part of the migration journey. For more information, review [Test Actions](/docs/customize/actions/test-actions).

<Warning>
  We highly recommend you validate all migration logic in a development tenant before you enable it in production.
</Warning>

### Automatically enabling the Action

When the Action code is updated and you are ready to make the switch:

1. Select **Deploy**.
2. On the alert that confirms your deployment, select **Add to flow**.
3. Add your newly created Action to the flow, then select **Apply.**
4. Select **Continue**, **and disable any Rules selected** to simultaneously enable the new Action and disable the original Rule. If you are not ready, select **Cancel**, and you can disable the Rule later to activate the migrated Action logic.

For more information on adding your Action to the flow, refer to [Write your first Action](/docs/customize/actions/write-your-first-action).

<Callout icon="file-lines">
  If you re-enable a Rule, the corresponding Action logic is skipped.
</Callout>

## Migrate remaining rules

This process can be repeated to migrate each Rule in your login flow. Remember, Rules should be migrated in the reverse order they execute during the login flow.


# Migrate from Hooks to Actions
Source: https://auth0.com/docs/customize/actions/migrate/migrate-from-hooks-to-actions

Learn how to migrate your existing Auth0 Hooks code to Auth0 Actions code.

When converting existing Hooks to Actions, you should associate the new Action with the Trigger that corresponds to the type of Hook. If you follow the steps below and use the mappings we identify within them, the functionality should be identical.

## Plan your migration

Deployed Actions run after active Hooks, so you can either convert Hooks one at a time in the Dashboard or all at once using the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

You will need to convert code, and then activate the Action and deactivate the Hook. Activating the Action and deactivating the Hook can be done quickly in succession, but depending on the order, there might be a short period of time where either both or neither are running.

Because of this, we recommend migrating your pipeline step by step: convert pieces of your Hooks code to Action code, test in a staging environment, then go live with one piece at a time. Because active Hooks run before deployed Actions, you can keep some logic in Hooks as you build and test other logic in Actions.

<Card title="Tips when planning your migration">
  * Use flags to avoid duplicating expensive or one-time operations.
  * Make sure to run changes at a time when impact and traffic will be lowest.
  * Consider using the [Auth0 Deploy CLI](/docs/deploy-monitor/deploy-cli-tool) to script, test, and quickly implement the migration all at once or iteratively.
</Card>

## Understand limitations

While Actions can handle the vast majority of things that Hooks can, you should be aware of a few limitations before you start your migration .(Remember: you can have both Hooks and Actions running as you migrate.)

* Actions cannot persist data, like <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> or API responses, across executions.
* Actions are not provided with [an access token for the Management API](/docs/customize/rules/use-management-api) or [access to the global `auth0` object](/docs/customize/actions/action-coding-guidelines#global-object) as in Hooks.

For the full list of limitations, see [Actions Limitations](/docs/customize/actions/limitations).

## Convert code

To convert a Hook to an Action, you must replace Hook-specific code with Actions code. This section covers the tasks you will need to perform to turn a functioning Hook into its equivalent Action.

<Card title="Tips when converting code">
  * In general, look for the read-only properties of objects passed into the Hooks function on the Actions `event` object.
  * Use the Actions Code Editor in the Auth0 Dashboard to write your code; it will help by highlighting errors and supplying auto-complete suggestions.
  * Before you go live, thoroughly [test your new Actions](/docs/customize/actions/test-actions) in a [staging or test environment](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments).
</Card>

### Copy Hook code to a new Action

<Callout icon="file-lines">
  We recommend copying your Hook code into a new Action and using the Actions Code Editor in the Auth0 Dashboard; it will help you identify outstanding issues with your code.
</Callout>

1. Log in to your production tenant, and copy the code from the Hook you want to convert.
2. Switch to a non-production tenant, and navigate to [Auth0 Dashboard > Actions > Library](https://manage.auth0.com/#/select-tenant?path=/actions/library).
3. Select **Build Custom**, then:

   * Enter a **Name** for your Action that matches the name of the Hook you're converting.

   * Locate **Trigger**, and select the appropriate trigger\*\*:\*\*

     <table>
       <thead>
         <tr>
           <th>Type of Hook</th>
           <th>Actions Trigger</th>
         </tr>
       </thead>

       <tbody>
         <tr>
           <td>Client Credentials Exchange</td>
           <td>M2M/Client-Credentials</td>
         </tr>

         <tr>
           <td>Pre-User-Registration</td>
           <td>Pre User Registration</td>
         </tr>

         <tr>
           <td>Post-User-Registration</td>
           <td>Post User Registration</td>
         </tr>

         <tr>
           <td>Post-Change-Password</td>
           <td>Post Change Password</td>
         </tr>

         <tr>
           <td>Send Phone Message</td>
           <td>Send Phone Message</td>
         </tr>
       </tbody>
     </table>

   * Locate **Runtime**, and select **Node 18.**

   * Select **Create**.
4. In the code block of the Actions Code Editor, paste the Hook code you want to convert below the exported function.
5. Make the changes detailed in the rest of this article as you move the code into the function.
   You should also read about the `event` object associated with the new Actions Trigger; you'll see links to the relevant documentation when you get to the [Change how data is accessed](#change-how-data-is-accessed) section later in this guide.

### Change the function declaration

Hooks functions are exported using a default export, while Actions functions use named exports. Depending on the type of Hook you are converting, the named export will change. Mappings include:

<table>
  <thead>
    <tr>
      <th>Type of Hook</th>
      <th>Named Export</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Client Credentials Exchange</td>
      <td><code>onExecuteCredentialsExchange</code></td>
    </tr>

    <tr>
      <td>Pre-User Registration</td>
      <td><code>onExecutePreUserRegistration</code></td>
    </tr>

    <tr>
      <td>Post-User Registration</td>
      <td><code>onExecutePostUserRegistration</code></td>
    </tr>

    <tr>
      <td>Post-Change Password</td>
      <td><code>onExecutePostChangePassword</code></td>
    </tr>

    <tr>
      <td>Send Phone Message</td>
      <td><code>onExecuteSendPhoneMessage</code></td>
    </tr>
  </tbody>
</table>

**Before**

```javascript lines theme={null}
module.exports = async function myHooksFunction(){}
```

**After**

```javascript lines theme={null}
// Client Credentials Exchange
exports.onExecuteCredentialsExchange = async (event, api) => {}

// Pre-User Registration
exports.onExecutePreUserRegistration = async (event, api) => {}

// Post-User Registration
exports.onExecutePostUserRegistration = async (event) => {}

// Post-Change Password
exports.onExecutePostChangePassword = async (event) => {}

// Send Phone Message
exports.onExecuteSendPhoneMessage = async (event) => {}
```

### Convert dependencies

Hooks and Actions handle dependencies in a similar way. With both, dependencies are added separately via UI or Management API and included in the code. Also with both, you can require any package that is available in the `npm` Registry.

<Callout icon="file-lines">
  If your `npm` modules are not on the latest version, this is a great time to get up to date!
</Callout>

1. Search for `require` statements inside your Hook code.
2. Remove version numbers, but make a note of them.
3. Add the dependency by following the steps in the "Add a Dependency" section of [Write Your First Action](/docs/customize/actions/write-your-first-action) (if the dependency is not a [core NodeJS module](https://github.com/nodejs/node/tree/master/lib); if the dependency is a core NodeJS module, you do not need to include it).
4. Move the found `require` statements outside of the `function` declaration.

### Convert secrets

Hooks and Actions handle secrets in a similar way. With both, Secrets are added per Hook/Action via UI or Management API and included in the code.

To convert secrets from Hooks to Actions:

1. Save the values needed for the specific Action you are working on.
2. Add a Secret for each value you need to access from inside the Action. To learn how, read the **Add a Secret** section in [Write Your First Action](/docs/customize/actions/write-your-first-action).
3. Convert your code:

**Before**

```javascript lines theme={null}
async function (user, context, cb) {
    const { SECRET_NAME } = context.webtask.secrets;

    // ... additional code
}
```

**After**

```javascript lines theme={null}
async (event, api) => {
    const { SECRET_NAME } = event.secrets;

	// ... additional code
};
```

As with Hooks, Auth0 encrypts all secret values at rest.

### Change how data is accessed

With Hooks, data about the user, client, request, and other contextual data are stored in multiple arguments passed into the Hook function. In Actions, this data has been reshaped and moved to the `event` object. Many of the properties moved over as-is, but some have been combined to increase clarity.

Depending on the type of Hook you are converting, the `event` object will change:

* [Client Credentials Exchange - Actions Event Object](/docs/customize/actions/explore-triggers/machine-to-machine-trigger/credentials-exchange-event-object)
* [Post-Change Password - Actions Event Object](/docs/customize/actions/explore-triggers/password-reset-triggers/post-change-password-trigger/post-change-password-event-object)
* [Post-User Registration - Actions Event Object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/post-user-registration-trigger/post-user-registration-event-object)
* [Pre-User Registration - Actions Event Object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger/pre-user-registration-event-object)
* [Send Phone Message - Actions Event Object](/docs/customize/actions/explore-triggers/mfa-notifications-trigger/send-phone-message-event-object)

**Before**

```javascript lines theme={null}
async function (user, context, cb) {
	const clientId = context.clientID;
	const tenant = context.connection.tenant

	// ... additional code
}
```

**After**

```javascript lines theme={null}
async (event, api) => {
	const clientId = event.client.client_id;
	const tenant = event.tenant.id;

	// ... additional code
};
```

<Callout icon="file-lines">
  Unlike the Hooks `context` object, data stored on or modified in properties of the `event` object does not persist in subsequent Actions. If your Hook is setting data on these properties to trigger core functionality, you will need to use the `api` interface available in the [Machine to Machine](/docs/customize/actions/explore-triggers/machine-to-machine-trigger/credentials-exchange-api-object) and [Pre User Registration](/docs/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger/pre-user-registration-api-object) Actions Flows to persist data across Actions.
</Callout>

### Convert callbacks

When a Hook is finished processing, it must call the `callback()` function to complete its execution. Conversely, Actions do not use a callback mechanism; therefore, you will need to remove all instances of `callback()` from your Actions function.

If you were previously using the `callback()` function in a Client Credentials Exchange or Pre User Registration Hook to fail the request or update a user, you will still be able to do this in Actions through a new `api` interface.

#### Client Credentials Exchange

If you were adding extra claims to the access token in a Client Credentials Exchange Hook:

```javascript lines theme={null}
// Client Credentials Exchange Hook
module.exports = function(client, scope, audience, context, cb) {
  var access_token = {};
  access_token.scope = scope;

  access_token['https://example.com/claim'] = 'bar';
  cb(null, access_token);
};
```

You can now use the Actions [Client Credentials Exchange API Object](/docs/customize/actions/explore-triggers/machine-to-machine-trigger/credentials-exchange-api-object):

```javascript lines theme={null}
// Client Credentials Exchange Action
exports.onExecuteCredentialsExchange = async (event, api) => {
  api.accessToken.setCustomClaim("https://example.com/claim", 'bar');  
};
```

#### Pre User Registration

If you were adding extra claims to the access token in a Pre User Registration Hook:

```javascript lines theme={null}
// Pre User Registration Hook
module.exports = function (user, context, cb) {
	if (user.app_metadata.condition === "success") {
      var response = {};
      response.user = { user_metadata: { favorite_color: "purple" } };
      // This Hook succeeded, proceed with the next Hook.
	  return callback(null, response);
	}

	if (user.app_metadata.condition === "failure") {
		// This Hook failed, stop the login with an error response.
		return callback(new Error("Failure message"));
	}

	// ... additional code
};
```

You can now use the [Pre User Registration API Object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger/pre-user-registration-api-object):

```javascript lines theme={null}
// Pre User Registration Action
exports.onExecutePreUserRegistration = async (event, api) => {
	if (event.user.app_metadata.condition === "success") {
		// This Action succeeded, proceed with next Action.
		api.user.setUserMetadata("favorite_color", "purple");
		return;
	}

	if (event.user.app_metadata.condition === "failure") {
		// This Action failed, stop the call with an error response.
		return api.access.deny("Failure message");
	}

	// ... additional code
};
```

## Complete the migration

Once your new Actions code has been written and tested, you must activate the Action and deactivate the Hook. These two tasks can be done quickly in succession, but depending on the order, there might be a short period of time where either both or neither are running. Because active Hooks run before deployed Actions, you can keep some logic in Rules as you build and test other logic in Actions.


# Migrate from Rules to Actions
Source: https://auth0.com/docs/customize/actions/migrate/migrate-from-rules-to-actions

Learn how to migrate your existing Auth0 Rules code to Auth0 Actions code.

When converting existing Rules to Actions, you should associate the new Action with the Post-Login (`post-login`) Trigger of the Login Flow. If you follow the steps below and keep your Actions in the same order as your original Rules, the functionality should be identical.

## Plan your migration

Post-Login Actions run after existing Rules, so you can either convert Rules one at a time in the Dashboard or all at once using the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

You will need to convert code, and then activate the Action and deactivate the Rule. Activating the Action and deactivating the Rule can be done quickly in succession, but depending on the order, there might be a short period of time where either both or neither are running.

Because of this, we recommend migrating your pipeline step by step: convert pieces of your Rules code to Action code, test in a staging environment, then go live with one piece at a time. Because active Rules run before deployed Actions, if you start at the end of your Rules pipeline and work backwards, you can keep some logic in Rules as you build and test other logic in Actions.

<Card title="Tips when planning your migration">
  * Keep your Actions and Rules 1:1, so functionality can be turned off and on in blocks and tested.
  * Use flags in user metadata to avoid duplicating expensive or one-time operations.
  * Start at the end of your Rules pipeline and work backwards; because active Rules run before deployed Actions, you can keep some logic in Rules as you build and test other logic in Actions.
  * Make sure to run changes at a time when impact and traffic will be lowest.
  * Consider temporarily [customizing your login page](/docs/customize) to halt logins if the cutover could cause invalid logins or gaps in protection.
  * Consider using the [Auth0 Deploy CLI](/docs/deploy-monitor/deploy-cli-tool) to script, test, and quickly implement the migration all at once or iteratively.
</Card>

## Understand limitations

While Actions can handle the vast majority of things that Rules can, you should be aware of a few limitations before you start your migration. (Remember: you can have both Rules and Actions running as you migrate.)

* Actions are not provided with [an access token for the Management API](/docs/customize/rules/use-management-api) or access to the global `auth0` object as in Rules. To learn how Management API calls can still be made, read the [Convert Code](#convert-code) section.

For the full list of limitations, see [Actions Limitations](/docs/customize/actions/limitations).

## Convert code

To convert a Rule to an Action, you must replace Rule-specific code with Actions code. This section covers the tasks you will need to perform to turn a functioning Rule into its equivalent Action.

<Card title="Tips when converting code">
  * In general, look for the read-only properties of Rules `user` and `context` objects on the Actions `event` object. Look for any side effects your Actions have on the system (like failing a login or updating user metadata) in the `api` object functions.
  * Use the Actions Code Editor in the Auth0 Dashboard to write your code; it will help by highlighting errors and supplying auto-complete suggestions.
  * Before you go live, thoroughly [test your new Actions](/docs/customize/actions/test-actions) in a [staging or test environment](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments).
</Card>

### Copy Rule code to a new Action

<Callout icon="file-lines">
  We recommend copying your Rule code into a new Action and using the Actions Code Editor in the Auth0 Dashboard; it will help you identify outstanding issues with your code.
</Callout>

1. Log in to your production tenant, and copy the code from the Rule you want to convert.
2. Switch to a non-production tenant, and navigate to [Auth0 Dashboard > Actions > Library](https://manage.auth0.com/#/select-tenant?path=/actions/library).
3. Select **Build Custom**, then:

   * Enter a **Name** for your Action that matches the name of the Rule you're converting.
   * Locate **Trigger**, and select **Login / Post Login**.
   * Locate **Runtime**, and select **Node 16.**
   * Select **Create**.
4. In the code block of the Actions Code Editor, paste the Rule code you want to convert below the exported `onExecutePostLogin` function.
5. Make the changes detailed in the rest of this article as you move the code into the function.

### Change the function declaration

Rules use a plain, declared function with `user`, `context`, and `callback` parameters, while Actions use a function exported to a specific name. Make the following change; for now, ignore any errors that appear.

**Before**

```js lines theme={null}
async function myRulesFunction(user, context, callback) {
    // ... additional code
}
```

**After**

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
	// ... additional code
};
```

### Change how user data is accessed

In Rules, data about the user logging in is stored in the [`user` object](/docs/customize/rules/user-object-in-rules). In Actions, this data is found in the `user` property of the [`event` object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object). The majority of existing properties are accessible in this new location.

<Callout icon="file-lines">
  Data stored or modified in properties in the `event` object are not accessible in other Actions.
</Callout>

**Before**

```javascript lines theme={null}
function myRulesFunction(user, context, callback) {
	const userEmail = user.email;
	const userId = user.user_id;

	// This property could be undefined in Rules.
	const userAppMetadata = user.app_metadata || {};

	// ... additional code
}
```

**After**

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
	const userEmail = event.user.email;
	const userId = event.user.user_id;

	// This property will never be undefined in Actions.
	const userAppMetadata = event.user.app_metadata;

	// ... additional code
};
```

### Change how context data is accessed

In Rules, data about the current login session is stored in the [`context` object](/docs/customize/rules/context-object). For Actions, this data has been reshaped and moved to the [`event` object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object). Many of the properties moved over as-is, but some have been combined to increase clarity.

<Callout icon="file-lines">
  Data stored or modified in properties in the `event` object are not accessible in other Actions. If your Rule triggers core functionality by setting data on these properties, like `context.idToken` or `context.multifactor`, please read one of the sections below that addresses your use case.
</Callout>

**Before**

```javascript lines theme={null}
function myRulesFunction(user, context, callback) {
	const clientId = context.clientID;
	const clientMetadata = context.clientMetadata || {};

	const connectionId = context.connectionID;
	const connectionMetadata = context.connectionMetadata || {};

	const protocol = context.protocol;

	const tenant = context.tenant;

	// ... additional code
}
```

**After**

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
	const clientId = event.client.client_id;
	const clientMetadata = event.client.metadata;

	const connectionId = event.connection.id;
	const connectionMetadata = event.connection.metadata;

	const protocol = event.transaction.protocol;

	const tenant = event.tenant.id;

	// ... additional code
};
```

### Convert dependencies

Rules include dependencies in a way that requires including the version number in a `require` statement. Actions use a more standard CommonJS syntax and require that the versions be indicated outside of the code editor.

In Rules, only specific versions of specific packages are allowed, and adding new packages and versions requires a request to Auth0. In Actions, you can require any package that is available in the `npm` Registry.

<Callout icon="file-lines">
  If your `npm` modules are not on the latest version, this is a great time to get up to date!
</Callout>

1. Search for `require` statements inside your Rule code.
2. Remove version numbers, but make a note of them.
3. Add the dependency by following the steps in the "Add a Dependency" section of [Write Your First Action](/docs/customize/actions/write-your-first-action) (if the dependency is not a [core NodeJS module](https://github.com/nodejs/node/tree/main/lib); if the dependency is a core NodeJS module, you do not need to include it).
4. Move the found `require` statements outside of the `function` declaration:

**Before**

```javascript lines theme={null}
function myRulesFunction(user, context, callback) {
	const dependency = require("dependency@1.2.3");

	// ... additional code
}
```

**After**

```javascript lines theme={null}
const dependency = require("dependency"); // v1.2.3
exports.onExecutePostLogin = async (event, api) => {
	// ... additional code
};
```

### Convert callbacks

When a Rule is finished processing, it must call the `callback()` function and pass in an error if the login fails. Conversely, Actions can return on success, or call an `api` method with a message if the login fails. All instances of `callback()` in a Rule should be removed or replaced with `api.access.deny()` for failure. In both Rules and Actions, if processing needs to stop for a specific condition, use a `return` statement.

**Before**

```javascript lines theme={null}
function myRulesFunction(user, context, callback) {
	const userAppMetadata = user.app_metadata || {};
	if (userAppMetadata.condition === "success") {
		// This Rule succeeded, proceed with next Rule.
		return callback(null, user, context);
	}

	if (userAppMetadata.condition === "failure") {
		// This Rule failed, stop the login with an error response.
		return callback(new Error("Failure message"));
	}

	// ... additional code
}
```

**After**

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
	if (event.user.app_metadata.condition === "success") {
		// This Action succeeded, proceed with next Action.
		return;
	}

	if (event.user.app_metadata.condition === "failure") {
		// This Action failed, stop the login with an error response.
		return api.access.deny("Failure message");
	}

	// ... additional code
};
```

### Change handling of secrets

In Rules, you set configuration values globally, which means that all Rules can access all secret values. (To learn more, read [Store Rule Configurations](/docs/customize/rules/configuration).) In Actions, you set configuration values for each individual Action. You can't access an Action's secret value from outside the context of the Action.

To convert secrets from Rules to Actions:

1. Save the values needed for the specific Action you are working on.
2. Add a Secret for each value you need to access from inside the Action. To learn how, read the **Add a Secret** section in [Write Your First Action](/docs/customize/actions/write-your-first-action).
3. Convert your code:

**Before**

```javascript lines theme={null}
function myRulesFunction (user, context, callback) {
  const { CLIENT_ID, CLIENT_SECRET } = configuration;

  // ... additional code
}
```

**After**

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const { CLIENT_ID, CLIENT_SECRET } = event.secrets;

  // ... additional code
}
```

As with Rules, Auth0 encrypts all secret values at rest.

### Convert custom claims in tokens

Rules and Actions can both add custom claims to ID and <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip>. In Rules, this is a property of the `context` object, while Actions uses a method on the [`api` object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object).

**Before**

```javascript lines theme={null}
function myRulesFunction(user, context, callback) {
	const userAppMetadata = user.app_metadata || {};
	const namespace = "https://namespace/";

	context.idToken[`${namespace}/emp_id`] = userAppMetadata.emp_id;
	context.accessToken[`${namespace}/emp_id`] = userAppMetadata.emp_id;

	// ... additional code
}
```

**After**

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
	const namespace = "https://namespace/";

	api.idToken.setCustomClaim(
		`${namespace}/emp_id`, 
		event.user.app_metadata.emp_id
	); 		   

	api.accessToken.setCustomClaim(
		`${namespace}/emp_id`, 
		event.user.app_metadata.emp_id
	);

	// ... additional code
};
```

### Convert multi-factor triggering

In Rules, <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> can be triggered by modifying the `multifactor` property of the [`context` object](/docs/customize/rules/context-object). In Actions, this is done with a [method on the `api` object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object).

**Before**

```javascript lines theme={null}
function myRulesFunction(user, context, callback) {
	if (user.app_metadata.needs_mfa === true) {
		context.multifactor = { 
			provider: "any", 
			allowRememberBrowser: false,
		};
	}

	// ... additional code
}
```

**After**

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
	if (event.user.app_metadata.needs_mfa === true) {
		api.multifactor.enable("any", { allowRememberBrowser: false });
	}

	// ... additional code
};
```

### Convert user metadata updates

Updating the `user_metadata` and `app_metadata` properties in Rules requires a call to the Management API, which can lead to [rate limit](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/management-api-endpoint-rate-limits) errors. Actions, however, provides a way to indicate multiple user metadata changes but only call the Management API once.

**Before**

```javascript lines theme={null}
function myRulesFunction(user, context, callback) {
	user.app_metadata = user.app_metadata || {}; 
	user.app_metadata.roles = user.app_metadata.roles || [];
	user.app_metadata.roles.push("administrator"); 

	auth0.users
		.updateAppMetadata(user.user_id, user.app_metadata) 
		.then(() => callback(null, user, context))
		.catch((err) => callback(err));

	// ... additional code
}
```

If subsequent Rules need to update the user metadata, then they would have to call the Management API separately, making it more likely that you would hit the [rate limit](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/management-api-endpoint-rate-limits).

**After**

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
	const userRolesUpdated = event.user.app_metadata.roles || [];
	userRolesUpdated.push("administrator"); 

	// Note the two different methods here. 
	api.user.setAppMetadata("roles", userRolesUpdated);
	api.user.setUserMetadata("hasRoles", true);

	// ... additional code
};
```

If subsequent Actions needed to update the user metadata, then they would need to call `api.user.setUserMetadata` or `api.user.setAppMetadata`. In Actions, multiple calls to these functions across one or more Actions will result in a single Management API call once the flow is complete.

### Convert other Management API calls

In general, we do not recommend calling the Management API from a high-traffic, critical path like Rules or Actions. Requests to all Auth0 APIs are [rate limited](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy), including calls from extensibility points, and calling an API for all logins could easily result in failed logins at high-traffic times.

However, If the calls are necessary and are configured to avoid rate limits, it's possible to call the Management API from within Actions. As mentioned in the "Understand limitations" section earlier in this article, Actions are not provided with an access token for the Management API, so you will need to get an access token before activating your Action:

1. [Register a Machine-to-Machine application and authorize it for the Management API](/docs/get-started/auth0-overview/create-applications/machine-to-machine-apps).
2. Save the **Client ID** and **Client Secret** in the Action.
3. [Get an access token for the Management API](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production).
4. Call the Management API:

   <Warning>
     Actions cannot persist data across executions, so it's not possible to cache the access token for any length of time; because every Management API call also requires an Authentication API call, calling the Management API is a very expensive operation.
   </Warning>

**Before**

```javascript lines theme={null}
function myRulesFunction(user, context, callback) {
	const ManagementClient = require("auth0@2.9.1").ManagementClient; 
	const managementClientInstance = new ManagementClient({
		// These come from built-in Rules globals
		token: auth0.accessToken, 
		domain: auth0.domain,
	}); 

	managementClientInstance.users.assignRoles(
		{ id: user.user_id }, 
		{ roles: ["ROLE_ID_TO_ADD"] }, 
		(error, user) => {
			if (error) {
				return callback(error);
			}

			// ... additional code
		}
	);
}
```

**After**

```javascript lines theme={null}
const auth0Sdk = require("auth0");
exports.onExecutePostLogin = async (event, api) => {
	const ManagementClient = auth0Sdk.ManagementClient;

	// This will make an Authentication API call
	const managementClientInstance = new ManagementClient({
		// These come from a machine-to-machine application
		domain: event.secrets.M2M_DOMAIN,
		clientId: event.secrets.M2M_CLIENT_ID,
		clientSecret: event.secrets.M2M_CLIENT_SECRET,
		scope: "update:users"
	});

	managementClientInstance.users.assignRoles(
		{ id: event.user.user_id }, 
		{ roles: ["ROLE_ID_TO_ADD"]}, 
		(error, user) => {
			if (error) {
				return api.access.deny(error.message);
			}

			// ... additional code
		}
	);
};
```

### Convert redirects

Rules can redirect a user who is logging in to an external page, then wait for a response. In this case, all Rules before the redirection will run twice--once before the redirect and once on the response. The logic for the redirect and the response are typically contained in the same Rule.

In Actions, the Action pipeline is paused when the redirect happens and picks up once the user returns. Also, the exported redirect triggering function is separate from the redirect callback.

<Callout icon="file-lines">
  Doing all redirects correctly in Actions is beyond the scope of this guide. For more detailed information, read [Redirect with Actions](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/redirect-with-actions).
</Callout>

**Before**

```javascript lines theme={null}
function myRulesFunction(user, context, callback) {
    if (context.protocol === "redirect-callback") {
        // User was redirected to the /continue endpoint
        user.app_metadata.wasRedirected = true;
        return callback(null, user, context);
    } else if (
        context.protocol === "oauth2-password" ||
        context.protocol === "oauth2-refresh-token" ||
        context.protocol === "oauth2-resource-owner"
    ) {
        // User cannot be redirected
        return callback(null, user, context);
    }
    // User is logging in directly
    if (!user.app_metadata.wasRedirected) {
        context.redirect = {
            url: "https://example.com",
        };
        callback(null, user, context);
    }
}
```

**After**

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
    api.accessToken.setClaim("https://dev.TLD/wasRedirected", true)
```

### Convert current SSO clients references

The Rules `context.sso` object provides details about the current session and clients using it. For more information, see the `context.sso` entry in [Context Object Properties in Rules](/docs/customize/rules/context-object). Similar information is available in the Actions `event.session` object.

**Before**

```javascript lines theme={null}
function (user, context, callback) {

  const clients = context.sso?.current_clients ?? []; 

  if (clients.length > 0) { 
	context.idToken.clients = clients.join(" "); 
  }

  return callback(null, user, context);
}
```

**After**

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const clients = event?.session?.clients ?? []; 

  if (clients.length > 0) { 
    api.idToken.setCustomClaim('clients', clients.map(c=> c?.client_id).join(" ")); 
  }
};
```

## Complete the migration

Once your new Actions code has been written and tested, you must activate the Action and deactivate the Rule. These two tasks can be done quickly in succession, but depending on the order, there might be a short period of time where either both or neither are running. Because active Rules run before deployed Actions, if you start at the end of your Rules pipeline and work backwards, you can keep some logic in Rules as you build and test other logic in Actions.


# Test Actions
Source: https://auth0.com/docs/customize/actions/test-actions

Learn how to test and debug Auth0 Actions

Depending on where you are in your implementation, you have several different options available to test and debug Auth0 Actions.

We recommend that you test individual actions from the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> as you implement them. Once you are ready, you should verify that the end-to-end flow works as expected using tenant logs through the Auth0 Dashboard.

## Test individual Actions

You can test individual Actions using the Actions Code Editor. The editor's test capability simulates a call to the Action using a sample payload based on the flow with which the Action is associated. To test an individual Action:

1. Navigate to [Auth0 Dashboard > Actions](https://manage.auth0.com/#/actions), and choose the Flow and Action that you would like to edit.
2. Locate the Actions Code Editor, and select **Test** (the play icon) from its sidebar. Edit the payload in the Test sidebar to analyze the outcome of different payloads.
3. Select **Run**.

The test results show the steps that the Action took, console output, any errors that occurred, and useful statistics about the execution of the Action.

<Frame>
  <img alt="Screenshot of the testing module inside of the Action Code Editor" />
</Frame>

<Callout icon="file-lines">
  You can also test an Action using the Management API's [**Test an Action** endpoint](https://auth0.com/docs/api/management/v2#!/Actions/post_test_action) and providing a payload corresponding with the flow with which the Action is associated. To get a sample payload, test the Action using the Test capability of the Actions Code Editor.
</Callout>

## Debug deployed Actions

Now that you have tested your Action, it’s time to deploy it and observe its execution. Assuming you have deployed your Action and added it to a flow (to learn how to attach Actions to Flows, read the "Attach the Action to a flow" section in [Write Your First Action](/docs/customize/actions/write-your-first-action)), you can debug your live Action in a few steps.

### Verify end-to-end Login Flow

For a `post-login` Action, you can verify the end-to-end-login flow by executing a login attempt for your tenant:

1. Navigate to [Auth0 Dashboard > Authentication > Authentication Profile](https://manage.auth0.com/#/authentication-profiles), and select **Try**. A window containing a sample login will open.
2. Proceed through the login flow. The login flow will execute any configured Actions.

Once complete, you will be redirected to a page that either lists the user profile attributes that your applications will receive or shows an error message explaining what went wrong.

### Analyze tenant logs

Whenever a trigger executes that has an associated Action bound to its flow, your [tenant logs](/docs/deploy-monitor/logs/view-log-events) will include Action execution details.

In the tenant logs list, you can see logs associated with Actions and choose to view them. In the example below, the log type of `Success Login` is associated with an Action on the `post-login` trigger of this tenant.

<Frame>
  <img alt="Screenshot of Tenant Log List in the Auth0 Dashboard, showing logs that are associated with Action execution." />
</Frame>

Some examples of log types associated with Actions include:

<table>
  <thead>
    <tr>
      <th><strong>Name</strong></th>
      <th><strong>Trigger(s)</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Success Login</td>
      <td><a href="/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger">post-login</a></td>
    </tr>

    <tr>
      <td>Failed Login</td>
      <td><a href="/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger">post-login</a></td>
    </tr>

    <tr>
      <td>Success Exchange</td>
      <td><a href="/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger">post-login</a></td>
    </tr>

    <tr>
      <td>Failed Exchange</td>
      <td><a href="/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger">post-login</a></td>
    </tr>

    <tr>
      <td>Success Change Password</td>
      <td><a href="/docs/customize/actions/explore-triggers/password-reset-triggers/post-change-password-trigger">post-change-password</a></td>
    </tr>

    <tr>
      <td>Failed Change Password</td>
      <td><a href="/docs/customize/actions/explore-triggers/password-reset-triggers/post-change-password-trigger">post-change-password</a></td>
    </tr>

    <tr>
      <td>Successful Signup</td>
      <td><a href="/docs/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger">pre-user-registration</a></td>
    </tr>

    <tr>
      <td>Failed Signup</td>
      <td><a href="/docs/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger">pre-user-registration</a></td>
    </tr>

    <tr>
      <td>Success Exchange</td>
      <td><a href="/docs/customize/actions/explore-triggers/machine-to-machine-trigger">credentials-exchange</a></td>
    </tr>

    <tr>
      <td>Failed Exchange</td>
      <td><a href="/docs/customize/actions/explore-triggers/machine-to-machine-trigger">credentials-exchange</a></td>
    </tr>
  </tbody>
</table>

To view detailed Action execution information, select the log that is associated with an Action execution, then select the **Action Details** view. In Action Details, you can see execution statistics, console output, and any errors that may have occurred.

<Frame>
  <img alt="Screenshot of individual log associated with Actions testing." />
</Frame>

## Unit test Actions

​You can unit test your Auth0 Actions by mocking the event and api passed into your Action function. Your Actions can live in version control or local directory, and you can use a tool like Jest to automatically test your Actions. In the following example, we use the [Login / Post Login](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) trigger and [Jest](https://jestjs.io/) to mock and test.

**Action code:**

```javascript lines theme={null}
// action.js

exports.onExecutePostLogin = async (event, api) => {
  const namespace = "https://my-app.example.com";
  if (event.authorization) {
    api.idToken.setCustomClaim(`${namespace}/favorite_color`, "pink");
  }
};
```

**Test file code:**

```javascript lines theme={null}
// action.spec.js

const { onExecutePostLogin } = require("./action.js");
test("sets favorite_color ID token claim to pink", async () => {
  const namespace = "https://my-app.example.com";
  const mockFunction = jest.fn();
  const mockApi = { idToken: { setCustomClaim: mockFunction } };
  const mockEvent = {authorization: {}};

  await onExecutePostLogin(mockEvent, mockApi);
  expect(mockFunction).toBeCalledWith(
    `${namespace}/favorite_color`,
    "pink"
  );
});
```

## Best practices

When building Actions on Auth0, [we recommend that you create a dedicated Auth0 tenant per environment](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments). Doing so allows you to isolate your production user base from your other environments, as well as configure different administrators per environment (for example, engineers might not have access to production configuration).

<Callout icon="file-lines">
  If you wish to entirely manage, test, and deploy your Actions via a CLI or CI/CD pipeline, you can use the [Deploy CLI Tool](/docs/deploy-monitor/deploy-cli-tool).
</Callout>


# Events
Source: https://auth0.com/docs/customize/events

Learn more about using Events for Auth0

<Warning>
  **Events are currently available in Early Access**.

  To learn more about Auth0's product release cycle, review [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

Events offer Auth0 customers an API-based method of synchronizing, correlating, or orchestrating changes that occur within Auth0 or 3rd-party <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> (IdPs) to external apps or 3rd-party services.

## Use cases

Events are real-time notifications about specific actions – initially changes to a user, but eventually others – that have occurred within your Auth0 tenant. You can create event streams that listen for these events to orchestrate asynchronous changes (i.e., changes to an entity or flow that have been completed) in Auth0 and forward them to one of many destinations for external processing. Events support a variety of use cases, including:

* Sending emails to new customers to welcome them or ask them to verify their email address.
* Monitoring user lifecycle changes so that you can update CRM (customer relationship management) or billing systems.

## Resources

To get started with Events, review the following:

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/customize/events/event-types">Events Types </a></td>
      <td>How to work with supported event types.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/events/create-an-event-stream">Create an Event Stream</a></td>
      <td>How to create an Event Stream with AWS EventBridge or webhooks.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/events/event-testing-observability-and-failure-recovery">Event Testing, Observability, and Failure Recovery</a></td>
      <td>How to test and manage your active event streams.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/events/events-best-practices">Events Best Practices</a></td>
      <td>Best practices for working with events.</td>
    </tr>
  </tbody>
</table>


# Create an Event Stream
Source: https://auth0.com/docs/customize/events/create-an-event-stream

Learn how you can create event streams using AWS EventBridge or webhooks.

<Warning>
  **Events are currently available in Early Access**.

  To learn more about Auth0's product release cycle, review [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

By subscribing to events, and delivering them to a destination of your choice using event streams, you can facilitate a number of related use cases, including:

* Sending emails to new customers to welcome them or ask them to verify their email address.
* Monitoring user lifecycle changes so that you can update CRM (customer relationship management) or billing systems.

You can create an event stream using either AWS EventBridge or webhooks. The sections below outline the setup process for both options.

## Access Management API (optional)

Event streams can either be provisioned using the <Tooltip href="/docs/glossary?term=Auth0+dashboard">Auth0 dashboard</Tooltip> or the [Auth0 Management API](https://auth0.com/docs/api/management/v2). If using the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>, before you can set up an event stream, you need to create a machine-to-machine (M2M) application and authenticate with a Management API token. For more information, review [Management API Access Tokens](/docs/secure/tokens/access-tokens/management-api-access-tokens).

1. Navigate to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and select **Create Application**.
2. Enter a descriptive name for your application and choose **Machine to Machine Applications**. Then, select **Create**.
3. Select the API you want to call from your application. In this case, use the **Auth0 Management API**.
4. Choose the permissions that you want to be issued as part of your application's access token, then select **Authorize**. For testing purposes, select:

   * `read:event_streams`
   * `create:event_streams`
   * `update:event_streams`
   * `delete:event_streams`
   * `read:event_deliveries`
   * `update:event_deliveries`
   * `create:users`
5. Navigate to the **Settings** tab to gather your **Client ID**, **Client Secret**, and **Domain**.
6. Review [Get Management API Access Tokens](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production) to retrieve and store your access token.

## AWS EventBridge

The information below describes how you can create and enable an event stream using AWS EventBridge.

### EventBridge prerequisites

To use AWS EventBridge for event streams, you will need the following:

* AWS account

  * Your AWS account must have permissions to use EventBridge. If you don’t have an account, sign up at [https://aws.amazon.com/eventbridge/](https://aws.amazon.com/eventbridge/).
* AWS IAM permissions
* AWS EventBridge event bus
* AWS account ID & region

### Create an event stream (EventBridge)

<Tabs>
  <Tab title="Management API">
    Event streams allow you to capture real-time changes within your Auth0 tenant and send them to an external system for processing.

    Before setting up an event stream, you need to identify the [event types](/docs/customize/events/event-types) you want to monitor. Then, you will use your AWS account ID and region to set up your event stream, as demonstrated below.

    This example uses the Auth0 CLI to create an event stream that subscribes to the `user.created` event, which triggers whenever a new user is registered in your tenant.

    ```bash wrap lines theme={null}
    auth0 events create --name ng-demo-eventbridge --type eventbridge --subscriptions "user.created" --configuration '{"aws_account_id":"<your-aws-account-id>","aws_region":"<your-aws-region>"}'
    ```

    If successful, this call returns the following JSON with your event stream `id`. New event streams are enabled by default.

    ```json lines theme={null}
    {
      "id": "est_8of6RXoM1997qikH7NS11h",
      "status": "enabled",
      "name": "ng-demo-eventbridge",
      "subscriptions": [
        {
          "event_type": "user.created"
        }
      ],
      "created_at": "2025-01-29T18:08:43.440Z",
      "updated_at": "2025-01-29T18:08:43.440Z",
      "destination": {
        "type": "eventbridge",
        "configuration": {
          "aws_account_id": "<your-aws-account-id>",
          "aws_region": "<your-aws-region>",
          "aws_partner_event_source": "default"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Dashboard">
    To create an event stream in the Auth0 Dashboard using AWS EventBridge:

    1. Navigate to **Auth0 Dashboard** > **Event Streams (Early)**.
    2. Select **+Create Event Stream**.
    3. From the list of stream types, select **AWS EventBridge**. This will open the configuration form for your new EventBridge stream.
    4. **Configure Stream Details:** In the configuration form, you will need to provide the following information:

       * **Stream Name:**

         Enter a descriptive name for your event stream. This will help you identify it within the Auth0 Dashboard.
       * **AWS Account ID:**

         Enter the 12-digit AWS account ID where you want the Auth0 events to be sent.
       * **AWS Region:**

         Select the specific AWS Region where your EventBridge event bus is located.
    5. **Select Event Types:** In the **Select Event Types** section, choose the specific Auth0 event types you want to include in this stream. You can select multiple event types based on your requirements (e.g., `user.created`, `user.updated`, `user.deleted`).
    6. **Save Changes:** Once you have configured the stream name, AWS details, and selected your desired event types, click the **Save Changes** button.

    Your new event stream is now created, and Auth0 can begin publishing the selected event types to the specified AWS EventBridge event bus. You can monitor the status and manage your event stream from the Event Streams (Early) page in the Auth0 Dashboard.
  </Tab>

  <Tab title="Terraform">
    <Note>
      Before getting started with Terraform, you need to:

      * Install the Terraform CLI
      * Install the Auth0 CLI and authenticate with `auth0 login`
      * Have your AWS Account ID and AWS region for configuring an EventBridge stream
    </Note>

    ### File configuration

    To provision your event stream using Terraform, you need a structured project directory. See below for an example configuration when setting this up for the first time:

    ```bash theme={null}

    auth0-event-streams/
    ├── main.tf             # Core configuration: defines providers and the 'auth0_event_stream' resource.
    ├── variables.tf        # Variable declaration: defines inputs like 'aws_account_id' and 'aws_region'.
    └── terraform.tfvars    # Variable values: holds the actual configuration values (e.g., "123456789012").

    ```

    ### Define variables

    In your `variables.tf` file, declare the necessary input variables your stream configuration needs:

    ```bash theme={null}
    variable "aws_account_id" {
      description = "The 12-digit AWS Account ID where the EventBridge event bus resides."
      type        = string
    }

    variable "aws_region" {
      description = "The AWS region (e.g., us-east-1) for the EventBridge event bus."
      type        = string
    }
    ```

    ### Set variable values

    In your `terraform.tfvars` file, provide the actual values for your specific environment:

    ```bash theme={null}
    aws_account_id = "<your-aws-account-id>" # e.g., "123456789012"
    aws_region     = "<your-aws-region>"     # e.g., "us-east-1"
    ```

    ### Set environment variables

    In your terminal, set the three required environment variables using the credentials you copied in Access Management API (optional) above.

    ```bash theme={null}
    export AUTH0_DOMAIN="your-tenant-name.auth0.com"
    export AUTH0_CLIENT_ID="your_m2m_client_id"
    export AUTH0_CLIENT_SECRET="your_m2m_client_secret"
    ```

    ## Create an event stream

    This example uses the `auth0_event_stream` resource to create an event stream that subscribes to the `user.created` event, which triggers whenever a new user is registered in your tenant. Use the following sample in your `main.tf` file:

    ```hcl theme={null}
    terraform {
      required_providers {
        auth0 = {
          source  = "auth0/auth0"
          version = ">= 1.0.0" 
        }
      }
    }

    provider "auth0" {}

    resource "auth0_event_stream" "eventbridge_stream" {
      name             = "ng-demo-eventbridge-tf"
      destination_type = "eventbridge" # Required
      subscriptions    = ["user.created"]

      eventbridge_configuration {
        aws_account_id = var.aws_account_id
        aws_region     = var.aws_region
      }
    }
    ```

    If successful, this call returns the following JSON with your event stream `id`. New event streams are enabled by default.

    After you have created and saved all three of the files above, you are ready to create your stream.

    1. Initialize the provider

    ```bash theme={null}
    terraform init
    ```

    2. Review your changes:

    ```bash theme={null}
    terraform plan
    ```

    3. Create the stream:

    ```bash theme={null}
    terraform apply
    ```
  </Tab>
</Tabs>

## Webhooks

As an alternative to AWS EventBridge, you can use webhooks to facilitate event streams.

To get started, first set up a webhook handler to receive real-time notifications when a specific event occurs.  Then, you can create your event stream.

You can either create a basic webhook handler by following the instructions below, or you can use an existing service such as:

* Vercel
* Inngest

If you decide to use an existing service, you can proceed to [Create an event stream (webhook)](#create-an-event-stream-webhooks-). Otherwise, follow the instructions below to create your own basic webhook handler.

### Webhook prerequisites

Ensure you have the following installed to properly write your webhook handler:

* `node.js`
* `jq`
* `npm`
* `ngrok`

### Write the webhook handler

1. Install `express` to your `node_modules` folder and your `package.json` dependencies.

2. Install `dotenv` to your root directory to use a `.env` file for storing environment variables.

3. Create a `webhook.js` fle to receive the `user.created` event and store it in a database.

   ```javascript lines expandable theme={null}
   const express = require('express');
   const app = express();

   // Authorization middleware
   app.use((req, res, next) => {
     const token = req.headers["authorization"];
     if (token !== `Bearer ${API_TOKEN}`) {
       return res.status(401).json({ error: "Unauthorized" });
     }
     next();
   });

   // Webhook endpoint
   app.post("/webhook", async (req, res) => {
     console.log("Webhook received:", JSON.stringify(req.body, null, 2));

     const eventData = req.body;
     const { id, type, time, data } = eventData;
     const user = data.object;

     try {
       switch (type) {
         case "user.created":
           await handleUserCreated(user, time);
           break;
         case "user.updated":
           await handleUserUpdated(user, time);
           break;
         case "user.deleted":
           await handleUserDeleted(user, time);
           break;
         default:
           await handleDefaultEvent(id, type, time, data);
       }

       console.log(`Webhook event of type '${type}' committed to the database.`);
       res.sendStatus(204);
     } catch (err) {
       console.error("Error processing webhook:", err);
       res.status(500).json({ error: "Internal server error" });
     }
   });

   // Specific function for handling the user created event
   // In this example we're making sure users are also created in our own database
   async function handleUserCreated(user, time) {
     const { user_id, email, name, nickname, created_at, updated_at } = user;

     const query = `
       INSERT INTO users (user_id, email, name, nickname, created_at, updated_at, raw_user, last_event_processed)
       VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
     `;
     const values = [
       user_id,
       email,
       name,
       nickname,
       created_at,
       updated_at,
       user,
       time,
     ];

     try {
       await getPool().query(query, values);
     } catch (err) {
       if (err.code === "23505") {
         console.error(`Duplicate user_id=${user_id}, skipping insert.`);
       } else {
         console.error(`Database error while creating user_id=${user_id}:`, err);
         throw err;
       }
     }
   }
   ```

4. In the root of your project, create a `.env` file and add your API token using:

   ```bash lines theme={null}
   API_TOKEN=`openssl rand -hex 32`
   echo "API_TOKEN=$API_TOKEN" > .env
   ```

5. Start your server:

   ```bash lines theme={null}
   node webhook.js
   ```

6. To test the Webhook, expose your webhook handler using a tool like ngrok:

   ```bash lines theme={null}
   ngrok http 3000
   ```

   This provides a public URL for your local webhook handler, for example:

   ```bash lines theme={null}
   http://localhost:3000
   ```

### Create an event stream (webhooks)

Event streams allow you to capture real-time changes within your Auth0 tenant and send them to an external system for processing.

Before setting up an event stream, you need to identify the [event types](/docs/customize/events/event-types) you want to monitor. You will then use your webhook handler to create an event stream, as demonstrated below.

<Tabs>
  <Tab title="Management API">
    This example uses the Auth0 CLI to create an event stream that subscribes to the `user.created` event, which triggers whenever a new user is registered in your tenant. The event data is then forwarded to a webhook endpoint for further processing.

    ```bash lines theme={null}
    source .env # Make sure you are in the webhook directory where you created your .env file
    WEBHOOK_URL="<ngrok URL>/webhook"

    auth0 events create -n my-event1 -t webhook -s "user.created" -c '{"webhook_endpoint":"'"${WEBHOOK_URL}"'","webhook_authorization":{"method":"bearer","token":'"${API_TOKEN}"'"}}'
    ```

    If successful, this returns the following JSON with your event stream `id`. New event streams are enabled by default.

    ```hcl theme={null}
    {
      "id": "est_8of6RXoM1997qikH7NS11h",
      "status": "enabled",
      "name": "ng-demo-2",
      "subscriptions": [
        {
          "event_type": "user.created"
        }
      ],
      "created_at": "2025-01-29T18:08:43.440Z",
      "updated_at": "2025-01-29T18:08:43.440Z",
      "destination": {
        "type": "webhook",
        "configuration": {
          "webhook_endpoint": "https://example.com/webhook",
          "webhook_authorization": {
            "method": "bearer"
          }
        }
      }
    }
    ```

    #### Verify the event stream

    After you create an event stream, you can verify that the event stream exists using the following command:

    ```bash lines theme={null}
    auth0 events show <EVENT_STREAM_ID>
    ```
  </Tab>

  <Tab title="Dashboard">
    To create an event stream in the Auth0 Dashboard using AWS EventBridge:

    1. Navigate to **Auth0 Dashboard** > **Event Streams (Early)**.
    2. Select **+Create Event Stream**.
    3. From the list of stream types, select **Webhook**. This will open the configuration form for your new webhook stream.
    4. **Configure Stream Details:** In the configuration form, you will need to provide the following information:

       * **Stream Name:**

         Enter a descriptive name for your event stream. This will help you identify it within the Auth0 Dashboard.
       * **Endpoint:** Enter the complete URL of the HTTP endpoint where you want Auth0 to send the events. This is the service that will receive and process the event data.
       * **Authentication Method:** Choose the authentication method required by your endpoint.
       * **Authorization Token:** If you selected **Bearer Token** as the authentication method, enter the required authorization token here.
    5. **Select Event Types:** In the **Select Event Types** section, choose the specific Auth0 event types you want to include in this stream. You can select multiple event types based on your requirements (e.g., `user.created`, `user.updated`, `user.deleted`).
    6. **Save Changes:** Once you have configured the stream name, AWS details, and selected your desired event types, click the **Save Changes** button.

    Your new event stream is now created, and Auth0 can begin publishing the selected event types to the specified Webhook. You can monitor the status and manage your event stream from the Event Streams (Early) page in the Auth0 Dashboard.
  </Tab>

  <Tab title="Terraform">
    ### File configuration

    To provision your event stream using Terraform, you'll need a structured project directory. See below for an example configuration when setting this up for the first time:

    ```bash theme={null}
    auth0-event-streams/
    ├── main.tf             # Core configuration: defines providers and the 'auth0_event_stream' resource.
    ├── variables.tf        # Variable declaration: defines inputs like 'aws_account_id' and 'aws_region'.
    └── terraform.tfvars    # Variable values: holds the actual configuration values (e.g., "123456789012").
    ```

    ### Define variables

    In your `variables.tf` file, declare the necessary input variables your stream configuration will need:

    ```bash theme={null}
    variable "api_token" {
      description = "The secret token used for Webhook Bearer Authorization."
      type        = string
      sensitive   = true 
    }

    variable "webhook_endpoint_url" {
      description = "The public HTTPS URL for the webhook handler (e.g., your ngrok URL)."
      type        = string
    }
    ```

    ### Environment configuration

    Using the API token generated above, securely set the environment variable in your terminal using the `TF_VAR_` prefix:

    ```bash wrap lines theme={null}
    export AUTH0_DOMAIN="your-tenant-name.auth0.com"
    export AUTH0_CLIENT_ID="your_m2m_client_id"
    export AUTH0_CLIENT_SECRET="your_m2m_client_secret"
    ```

    If successful, this returns the following JSON with your event stream `id`. New event streams are enabled by default.

    ```bash theme={null}
    export TF_VAR_api_token="${API_TOKEN}"

    export AUTH0_DOMAIN="your-tenant-name.auth0.com"
    export AUTH0_CLIENT_ID="your_m2m_client_id"
    export AUTH0_CLIENT_SECRET="your_m2m_client_secret"
    ```

    ## Create an event stream

    This example uses the `auth0_event_stream` resource to create an event stream that subscribes to the `user.created` event, which triggers whenever a new user is registered in your tenant. Use the following sample in your `main.tf` file:

    If successful, this call returns the following JSON with your event stream `id`. New event streams are enabled by default.

    ```hcl theme={null}
    terraform {
      required_providers {
        auth0 = {
          source  = "auth0/auth0"
          version = ">= 1.0.0" 
        }
      }
    }

    provider "auth0" {}

    resource "auth0_event_stream" "webhook_stream" {
      name             = "my-webhook-handler-stream-tf"
      destination_type = "webhook" 
      subscriptions    = ["user.created"] 

      webhook_configuration {
        webhook_endpoint = var.webhook_endpoint_url

        webhook_authorization {
          method = "bearer"
          token  = var.api_token 
        }
      }
    }
    ```

    After you have created and saved all three of the files above, you are ready to create your stream.

    1. Initialize the provider

    ```bash theme={null}
    terraform init
    ```

    2. Run the plan:

    ```bash theme={null}
    URL="<your-ngrok-url>/webhook"
    terraform plan -var="webhook_endpoint_url=${URL}"
    ```

    3. Create the stream:

    ```bash theme={null}
    terraform apply -var="webhook_endpoint_url=https://<your-ngrok-url>/webhook"
    ```
  </Tab>
</Tabs>

After the stream is active, you can test the event stream. For more information, review [**Event Testing, Observability, and Failure Recovery**](/docs/customize/events/event-testing-observability-and-failure-recovery).

## Auth0 Actions

The information below describes how you can create and enable an event stream using Auth0 Actions.

### Create an event stream (Actions)

<Tabs>
  <Tab title="Management API">
    Event streams allow you to capture real-time changes within your Auth0 tenant and send them to an external system for processing.

    Before setting up an event stream, you need to identify the [event types](/docs/customize/events/event-types) you want to monitor. This example uses the Auth0 CLI to create an event stream that subscribes to the `user.created` event, which triggers whenever your tenant registers a new user.

    ```bash wrap lines theme={null}
    auth0 event-streams create \
      --name actions-1 \
      --type action \
      --subscriptions "user.created,user.updated,user.deleted" \
      --configuration '{"action_id":"385db79f-28a4-43d9-909d-6f5511dd6632"}'
    ```

    If successful, this call returns the following JSON with your event stream `id`. New event streams are enabled by default.

    ```json lines theme={null}
    {
        "configuration": {
          "action_id": "act_xyz789...",
          "status": "enabled"
      }
    }
    ```
  </Tab>

  <Tab title="Dashboard">
    To create an event stream in the Auth0 Dashboard using Auth0 Actions:

    1. Navigate to **Auth0 Dashboard** > **Event Streams (Early)**.

    2. Select **+Create Event Stream**.                .

    3. From the list of stream types, select **+Auth0 Actions**. This opens the configuration form for your new Auth0 Actions stream.

    4. **Configure Stream Details:** In the configuration form, you need to provide the following information:

       * **Stream Name:**

         Enter a descriptive name for your event stream. This will help you identify it within the Auth0 Dashboard.

    5. **Select Event Types:** In the **Select Event Types** section, choose the specific Auth0 event types you want to include in this stream. You can select multiple event types based on your requirements (e.g., `Created`, `Updated`, `Deleted`).

    6. In the **Action Editor**, write your handler code. The system requires the `onExecuteEventStream` function. You can use the `api` object to manage success or failure states.

    ```javascript theme={null}
    /**
     * Handler that will be called during the execution of an Event Stream.
     * @param {Event} event - Details about the Cloud Event.
     * @param {EventStreamAPI} api - Interface whose methods can be used to handle the event.
     */
    exports.onExecuteEventStream = async (event, api) => {
      const eventType = event.message.type;
      const eventData = event.message.data;

      console.log(`Received event: ${eventType}`);

      // Custom Logic: e.g., Send data to an external API
      // await axios.post('https://my-crm.com/ingest', eventData);

      // FAILURE HANDLING:
      // To trigger a retry, either throw an error or use api.message.fail()
      if (!eventData) {
         // api.message.fail('No data received');
         throw new Error('No data received');
      }

      // SUCCESS:
      // If the function ends without error, the event is marked delivered.
    };
    ```

    7. **Save Changes:** Once you have configured the stream name and Action handler, the system automatically creates the Action, bind it to a stream, and enables it.

    Your new event stream is now created, and Auth0 can begin publishing the selected event types to the specified Auth0 Action. You can monitor the status and manage your event stream from the Event Streams (Early) page in the Auth0 Dashboard.
  </Tab>
</Tabs>

## Learn more

* [Event Types](/docs/customize/events/event-types)
* [Event Testing, Observability, and Failure Recovery](/docs/customize/events/event-testing-observability-and-failure-recovery)
* [Events Best Practices](/docs/customize/events/events-best-practices)


# Event Testing, Observability, and Failure Recovery
Source: https://auth0.com/docs/customize/events/event-testing-observability-and-failure-recovery

Learn more about testing and managing your events and event streams.

<Warning>
  **Events are currently available in Early Access**.

  To learn more about Auth0's product release cycle, review [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

The following sections provide information about testing event streams and managing events.

## Test the event stream

After you create and enable an event stream using either AWS EventBridge or webhooks, you can test the new stream. Currently, Auth0 does not support sending events to disabled event streams.

To test your event stream, first create a user for your application by running the following with your preferred credentials:

<Tabs>
  <Tab title="Auth0 CLI">
    ```bash lines theme={null}
    auth0 users create # follow prompts to create a test user
    ```
  </Tab>

  <Tab title="cURL">
    ```bash lines theme={null}
    curl -s \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -X POST https://$TENANT/api/v2/users \
      -d '{
            "email": "nick-testing-21@example.com",
            "password": "Password123!",
            "connection": "Username-Password-Authentication"
          }'
    ```
  </Tab>
</Tabs>

After the user is created, it should trigger the `user.created` event in your event stream and return a response. In this example, webhooks are used to facilitate the event stream.

```json lines expandable theme={null}
"Webhook received": {
  "id": "evt_6SfwXrtm8nVcjzzNCFFH1L",
  "source": "urn:auth0:",
  "specversion": "1.0",
  "type": "user.created",
  "time": "2025-02-02T17:56:01.573Z",
  "data": {
    "object": {
      "created_at": "2025-02-02T17:56:01.566Z",
      "email": "nick-testing-21@example.com",
      "email_verified": false,
      "identities": [
        {
          "connection": "Username-Password-Authentication",
          "isSocial": false,
          "provider": "auth0",
          "user_id": "679fb1b1e809445f129bc18d"
        }
      ],
      "name": "nick-testing-21@example.com",
      "nickname": "nick-testing-21",
      "picture": "test.png",
      "updated_at": "2025-02-02T17:56:01.566Z",
      "user_id": "auth0|679fb1b1e809445f129bc18d"
    }
  },
  "a0tenant": "acme",
  "a0stream": "est_38ANnv8pQhqsZrX2VFbftv",
  "a0purpose": "test"
}
```

You can list the event delivery failures for a specific event stream by running:

<Tabs>
  <Tab title="Auth0 CLI">
    ```bash lines theme={null}
    auth0 api get event-streams/$EVENT_STREAM_ID/deliveries
    ```
  </Tab>

  <Tab title="cURL">
    ```bash lines theme={null}
    curl -s -H "Authorization: Bearer $TOKEN" \
      "https://$TENANT/api/v2/event-streams/${EVENT_STREAM_ID}/deliveries" | jq .
    ```
  </Tab>
</Tabs>

If an empty delivery failure array is returned, your event stream is running correctly.

## Observability

To ensure the reliability of event streams, implement a monitoring process that periodically checks for delivery failures and triggers alerts when necessary.

### Polling Deliveries endpoint

Poll the Deliveries endpoint every **5 minutes** to check for failed events. Use the following API call to fetch recent event deliveries:

<Tabs>
  <Tab title="Auth0 CLI">
    ```bash lines theme={null}
    auth0 api get event-streams/$EVENT_STREAM_ID/deliveries
    ```
  </Tab>

  <Tab title="cURL">
    ```bash lines theme={null}
    curl -s -H "Authorization: Bearer $TOKEN" \
      "https://$TENANT/api/v2/event-streams/${EVENT_STREAM_ID}/deliveries" | jq .
    ```
  </Tab>
</Tabs>

If failures are detected:

* Log the failed event details.
* Alert the appropriate team or system to review and diagnose the issue.

## Recovery

Event delivery will automatically retry. To learn more, review [Best Practices](/docs/customize/events/event-testing-observability-and-failure-recovery#batch-redelivery-of-failed-events).

If failures occur, use the Redelivery API to attempt event delivery again.

### Redeliver a single failed event

To retry a specific failed event, use:

<Tabs>
  <Tab title="Auth0 CLI">
    ```bash lines theme={null}
    EVENT_ID=<your event id>
    auth0 api POST event-streams/$EVENT_STREAM_ID/redeliver/$EVENT_ID --data '{}'
    ```
  </Tab>

  <Tab title="cURL">
    ```bash lines theme={null}
    curl -s -X POST -H "Authorization: Bearer $TOKEN" \
      "https://<your-domain>/api/v2/event-streams/$EVENT_STREAM_ID/redeliver/$EVENT_ID"
    ```
  </Tab>
</Tabs>

### Batch redelivery of failed events

To retry all failed events in the event stream:

<Tabs>
  <Tab title="Auth0 CLI">
    ```bash wrap lines theme={null}
    auth0 api POST event-streams/$EVENT_STREAM_ID/redeliver --data '{}'
    ```
  </Tab>

  <Tab title="cURL">
    ```bash lines theme={null}
    curl -s -X POST -H "Authorization: Bearer $TOKEN" \
      "https://<your-tenant>.auth0.com/api/v2/event-streams/<event_stream_id>/redeliver"
    ```
  </Tab>
</Tabs>

### Auto-disable mechanism

Auth0 automatically disables an event stream if excessive failures occur.

<table>
  <thead>
    <tr>
      <th><strong>Condition</strong></th>
      <th><strong>Action taken</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>500 consecutive failures</td>
      <td>Event stream is disabled automatically.</td>
    </tr>

    <tr>
      <td>5000 total failures</td>
      <td>Event stream is disabled automatically.</td>
    </tr>
  </tbody>
</table>

* If an event stream is auto-disabled, you **must** use the Redelivery API to process any failed events.
* The event stream **cannot** be manually re-enabled until the total failure count drops below 5000.
* Once the number of failures is reduced, you can re-enable the stream via API.

## Learn more

* [Event Types](/docs/customize/events/event-types)
* [Create an Event Stream](/docs/customize/events/create-an-event-stream)
* [Events Best Practices](/docs/customize/events/events-best-practices)


# Event Types
Source: https://auth0.com/docs/customize/events/event-types

Learn more about supported Event types.

<Warning>
  **Events are currently available in Early Access**.

  To learn more about Auth0's product release cycle, review [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

You can create event streams that listen for different types of events, such as the creation of a new user profile. The sections below outline specific details for currently supported event types.

## Event object

Events are published using a schema that conforms to the [CloudEvent specification](https://cloudevents.io/):

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Required</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>id</td>
      <td>string</td>
      <td>Yes</td>
      <td>Identifies the event.</td>
    </tr>

    <tr>
      <td>source</td>
      <td>URI-reference</td>
      <td>Yes</td>
      <td>Identifies the tenant that generated the event, including its environment.</td>
    </tr>

    <tr>
      <td>specversion</td>
      <td>string</td>
      <td>Yes</td>
      <td>The version of the CloudEvents specification that the event uses.</td>
    </tr>

    <tr>
      <td>type</td>
      <td>string</td>
      <td>Yes</td>
      <td>The type of event.</td>
    </tr>

    <tr>
      <td>time</td>
      <td>timestamp</td>
      <td>Yes</td>
      <td>Timestamp of when the event happened.</td>
    </tr>

    <tr>
      <td>dataschema</td>
      <td>URI</td>
      <td>Yes</td>
      <td>Identifies the schema that data adheres to.</td>
    </tr>

    <tr>
      <td>data</td>
      <td>object</td>
      <td>Yes</td>
      <td>Additional information related to the event. This field varies based on the type of event.</td>
    </tr>
  </tbody>
</table>

```json lines expandable theme={null}
{
  "id": "evt_<unique-id>",
  "source": "urn:auth0:<your-tenant>:users",
  "spec_version": "1.0",
  "type": "com.auth0.user.<event-type>",
  "time": "2025-01-29T14:36:25.794Z",
  "dataschema": "https://<your-tenant>.auth0.com/api/v2/schemas/user.<event-type>",
  "data": {
    "object": {
      "user_id": "<user-id>",
      "email": "<email>",
      "email_verified": <true/false>,
      "family_name": "<family-name>",
      "given_name": "<given-name>",
      "name": "<full-name>",
      "nickname": "<nickname>",
      "phone_number": "<phone-number>",
      "phone_verified": <true/false>,
      "user_metadata": {
        "hobby": "<user-hobby>"
      },
      "app_metadata": {
        "external_user_id": "<external-id>"
      },
      "identities": [
        {
          "connection": "<connection-name>",
          "user_id": "<identity-user-id>",
          "provider": "<identity-provider>",
          "isSocial": <true/false>
        }
      ],
      "created_at": "<user-created-time>",
      "updated_at": "<user-updated-time>",
      "picture": "<profile-picture-url>"
    }
  }
}
```

For more information on Event Types, see the [Events Catalog](https://auth0.com/docs/events/).

## Learn more

* [Create an Event Stream](/docs/customize/events/create-an-event-stream)
* [Event Testing, Observability, and Failure Recovery](/docs/customize/events/event-testing-observability-and-failure-recovery)
* [Events Best Practices](/docs/customize/events/events-best-practices)


# Events Best Practices
Source: https://auth0.com/docs/customize/events/events-best-practices

Review best practices for using Events in Auth0

<Warning>
  **Events are currently available in Early Access**.

  To learn more about Auth0's product release cycle, review [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

For best results when developing event streams, Auth0 recommends adhering to the best practices compiled below. These guidelines can help reduce friction, increase efficiency, and promote a best-in-class eventing journey.

### Use asynchronous queues to process events

On receiving an event, respond with an HTTP 2XX OK (e.g., 200OK, 202 Accepted, 204 No Content)  to signal that the event was successfully delivered. Without this response, Auth0 considers the event delivery a failure and will retry in accordance with the behavior described under [System behavior during failed event deliveries](#system-behavior-during-failed-event-deliveries).

To avoid scalability issues, configure your handler to process incoming events with an asynchronous queue. If processing events synchronously, any large spike in webhook deliveries (for example, during the beginning of the month when all subscriptions renew) may overwhelm your endpoint hosts. Asynchronous queues allow you to process the concurrent events at a rate your system can support.

### Ignore duplicate events

Webhook endpoints may occasionally receive the same event more than once. You can guard against duplicated event receipts by logging the event IDs you’ve processed.

### Handle out-of-sequence events

Auth0 does not guarantee that events are delivered in the same sequence that they are generated. For example, when a user is created and then immediately updated such that another user is linked to it, you may receive:

* `user.updated (for User 1)`
* `user.created (for User 1)`
* `user.deleted (for User 2)`
* `user.updated (for User 2)`

To ensure you do not overwrite your data with stale information, check the timestamp of the incoming webhook data against the timestamp of the data in your system. Each `data.object` in the payload includes a `created_at` field and an `updated_at` field.

### Listen for specific event types

Configure your webhook endpoints to receive only the types of events required by your integration. Listening for extra events (or all events) puts undue strain on your server and is not recommended.

You can change the events that a webhook endpoint receives by [updating event streams](/docs/customize/events/create-an-event-stream).

### System behavior during failed event deliveries

Currently, Auth0  only allows four total attempts, including the initial attempt and three retries with exponential backoff (1s, 2s, 4s).  If you receive a 4XX, the event fails immediately with no retries, as retrying is unlikely to change the response.

If your endpoint still does not respond successfully after this time, the event is marked as failed, and Auth0 will no longer retry sending it. For more information on failing events, review [Event Stream Testing, Observability, and Failure Recovery](/docs/customize/events/event-testing-observability-and-failure-recovery).

### Disable failing event streams

Event streams are automatically disabled in the following scenarios:

* Auth0 receives 500 failures (i.e., anything other than a `2XX`) in a row.
* The Event Stream reaches 5000 total failed deliveries.
* Auth0 receives three consecutive delivery attempt failures (i.e., anything other than a `2XX`).

  * If you wish to permit more delivery attempt failures, submit a support ticket requesting the number of failures you wish to permit, and Auth0 will review your request.

## Learn more

* [Event Types](/docs/customize/events/event-types)
* [Create an Event Stream](/docs/customize/events/create-an-event-stream)
* [Event Testing, Observability, and Failure Recovery](/docs/customize/events/event-testing-observability-and-failure-recovery)


# Auth0 Extensions
Source: https://auth0.com/docs/customize/extensions

Describes Auth0 extensions that enable you to install applications or run commands and scripts that extend the functionality of Auth0.

<Warning>
  We plan to deprecate Rules and Hooks in 2024, and at that time, Rules and Hooks-based Extensions will be out of support. We highly recommend that you migrate to Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience.

  To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life.](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/)
</Warning>

Auth0 Extensions allow you to install applications or run commands/scripts that extend the functionality of the Auth0 base product. Each extension is separate from all other extensions and is subject to Auth0's [Rate Limit Policy](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy). Auth0 defines extensions per tenant, so data is stored by the pair `tenant\extension`.

<Callout icon="file-lines">
  To implement and manage extensions on your Auth0 Dashboard, you must have the Admin role.
</Callout>

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/customize/extensions/authorization-extension">Authorization Extension</a></td>
      <td>How to use the extension to control user authorization behavior during runtime.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/extensions/delegated-administration-extension">Delegated Administration Extension</a></td>
      <td>How to use the extension to expose the Users section of the Auth0 Dashboard to a select group of users without allowing them access to the rest of the Dashboard.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/extensions/single-sign-on-dashboard-extension">Single Sign-On Dashboard Extension</a></td>
      <td>How to use the extension to manage single sign-on login for your users on multiple enterprise applications.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/extensions/authentication-api-debugger-extension">Authentication API Debugger Extension</a></td>
      <td>How to use the Authentication API Debugger to test various endpoints.</td>
    </tr>

    <tr>
      <td><a href="/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector">AD/LDAP Connector</a></td>
      <td>How to use the AD/LDAP Connector extension.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/extensions/account-link-extension">Account Link Extension</a></td>
      <td>How to use the account link extension.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/extensions/user-import-export-extension">User Import/Export Extension</a></td>
      <td>How to use the user import/export extension.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/log-streams/custom-log-streams">Export Log Events with Extensions</a></td>
      <td>How to use log export extensions to export logs to third-party services such as Application Insights, Loggly, and MixPanel.</td>
    </tr>
  </tbody>
</table>


# Account Link Extension
Source: https://auth0.com/docs/customize/extensions/account-link-extension

Learn about the Account Link extension, which allows users with two accounts with the same email to be prompted to link them.

The Account Link extension prompts users that may have created a second account by mistake to link the new account with their old one upon their first login. The user may choose to either link the two accounts or keep them separate if creating the second account was intentional.

## How does the extension work?

The extension triggers after authentication when the email address of the user who authenticated matches the email address of an existing user account attached to a different <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>.

For example, if a user logs in with their Facebook account using the email `john@acme.com` and then later authenticates with Google using the same email address, they will be prompted with a page similar to the following:

<Frame>
  <img alt="Dashboard - Extensions - Account Link - Extension Example" />
</Frame>

The extension does not automatically link users with the same email, even if emails are verified, because verified emails are not enough evidence to prove that the user can currently authenticate to both accounts.

If the user selects **Continue**, they will be redirected to Facebook to authenticate. If the user is already logged in, Facebook will redirect back to the application, and the user will be automatically linked. If they are not logged in, they will be prompted to authenticate with their Facebook credentials. After Facebook redirects back to Auth0, the Facebook account will be linked with the Google account. This process ensures that the user has the credentials to authenticate to both accounts, which allows the accounts to be linked safely and correctly.

### Limitations

Note that the extension does not support <Tooltip href="/docs/glossary?term=passwordless">passwordless</Tooltip> connections, flows started using device authorization, or the <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> and WS-federation protocols. For connections not supported by the Account Link extension, see [Account Linking – Server-Side Implementation](/docs/manage-users/user-accounts/user-account-linking/suggested-account-linking-server-side-implementation) and [User Initiated Account Linking – Client-Side Implementation](/docs/manage-users/user-accounts/user-account-linking/user-initiated-account-linking-client-side-implementation) as alternative options.

## Install and configure extension

Go to [Auth0 Dashboard > Extensions](https://manage.auth0.com/#/extensions), and select **Auth0 Account Link**. The **Install Extension** window opens.

The extension will create a new application named `auth0-account-link` to use internally and a new rule to redirect users to the extension if they login with a new account that has an email matching an existing account.

<Callout icon="file-lines">
  If you rotate your application client secret associated with the Account Link Extension, you need to uninstall the extension, reinstall, and reconfigure with the new application secret.
</Callout>

To test, create a React Sample Single Page Application with [this project](https://github.com/auth0-samples/auth0-link-accounts-sample.git).

Open the `auth_config.json` file in your text editor and update the domain and `client_id` with your details.

Add `http://localhost:3000` in the “Allowed Callback URLs”, “Allowed Logout URLs”, “Allowed Web Origins” field.

Log in to `http://localhost:3000` and select a connection. Enter an email address that is already associated with a verified user with a different type of connection.

To link the account, select **Continue.**

Once logged in, check the user details on the <Tooltip href="/docs/glossary?term=Auth0+dashboard">Auth0 dashboard</Tooltip>, we can see the user accounts are linked.

## Set up extension

### Change application name

We recommend changing the name of the default application used for the extension to something descriptive and easy to read for your customers, like `Account Linking`, since it will appear on the **Login Page** when they authenticate their primary account.

### Update the login page

By default, Auth0's <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> allows a user to both log in and sign up, as one may expect. However, when the account linking asks you to authenticate your primary account in order to link it with the new account, providing a signup option can be confusing for users.

To learn more about what you can do with Universal Login, see [Auth0 Universal Login](/docs/authenticate/login/auth0-universal-login).

To prevent this, we send a query parameter to let the login page know that it should hide the **Sign Up** option. For this query parameter to take effect, however, you must customize the login page.

1. Go to [Auth0 Dashboard > Branding > Universal Login](https://manage.auth0.com/#/login_settings), and select the **Login** view.
2. Enable the **Customize Login Page** switch to enable the custom editor below. In the editor, we're going to add a new line to the Lock config.
3. Toward the bottom of the object configuring the Lock widget, add the following line (after the `closable` setting):
   `allowSignUp: !config.extraParams.prevent_sign_up,`

   <Frame>
     <img alt="Dashboard - Branding - Universal Login - Login Setting - Account Link Hosted Page Code Example" />
   </Frame>
4. Save your changes and attempt to link an account. You'll notice that the **Sign Up** option is no longer present and your users are safe from an extra level of confusion.

   <Frame>
     <img alt="Account Link Hosted Page Example" />
   </Frame>

<Callout icon="file-lines">
  Hiding the Signup link is not supported in the Universal Login Experience.
</Callout>

## Customize theme

At installation (or any time after by clicking the **Settings** icon for the Account Link Extension), you can add a URL to a custom stylesheet if you would like to customize the extension page to look a bit different from the default theme.

<Frame>
  <img alt="Account Link Customize Theme" />
</Frame>

## Administration Panel

You can customize your account linking login page and widget using the extension administration panel.

1. Go to [Dashboard > Extensions > Installed Extensions > Auth0 Account Link](https://manage.auth0.com/#/extensions/installed).
2. You will be redirected to the admin site. There you can edit the HTML code of your hosted page and change some settings of the account linking widget such as title, logo, color, and language.

   <Warning>
     Do not remove `{{ ExtensionCSS }}`, `{{ CustomCSS }}`, `{{ Auth0Widget }}`, or `{{ ExtensionScripts }}` from the HTML code of the site. This will cause the extension to not display the account linking widget.
   </Warning>

## Custom domains

If you're using a <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip>, you'll need to set the configs rule `customDomain` with the custom domain (for example, `auth.custom.com`).

1. Go to [Auth0 Dashboard > Auth Pipeline > Rules](https://manage.auth0.com/#/rules).
2. By default, line 27 of the rule is:
   `issuer: auth0.domain`You will need to change this to:
   `issuer: "myCustomDomain.com"
   Make` sure to omit the protocol portion of the URL.

## Learn more

* [User Account Linking](/docs/manage-users/user-accounts/user-account-linking)
* [Link User Accounts](/docs/manage-users/user-accounts/user-account-linking/link-user-accounts)
* [User Account Linking: Server-Side Implementation](/docs/manage-users/user-accounts/user-account-linking/suggested-account-linking-server-side-implementation)
* [User-Initiated Account Linking: Client-Side Implementation](/docs/manage-users/user-accounts/user-account-linking/user-initiated-account-linking-client-side-implementation)
* [Migrate to Access Tokens for Account Linking](/docs/troubleshoot/product-lifecycle/past-migrations/link-user-accounts-with-access-tokens-migration)


# Auth0 AD/LDAP Connector Health Monitor Extension
Source: https://auth0.com/docs/customize/extensions/ad-ldap-connector-health-monitor

Learn how to install and use the Auth0 AD/LDAP Connector Health Monitor extension.

The Auth0 AD/LDAP Connector Health Monitor exposes an API endpoint of your choice so that you can monitor your AD/LDAP connectors.

## Configure the extension

To install and configure this extension:

1. Navigate to [Auth0 Dashboard > Extensions](https://manage.auth0.com/#/extensions), and select **Auth0 AD/LDAP Connector Health Monitor**. The **Install Extension** window opens.
2. Set the following configuration parameters, and select **Install**:

* **Auth0\_Domain**: The domain for your Auth0 application, which you can find in your [Auth0 Application Settings](https://manage.auth0.com/#/applications/\{yourClientId}/settings).
* **Auth0\_Global\_Client\_ID**: The Global <Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip> for your Auth0 application, which you can find in the **Global Application Information** section of your [Tenant Advanced Settings](https://manage.auth0.com/#/tenant/advanced).
* **Auth0\_Global\_Client\_Secret**: The Global <Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip> for your Auth0 application, which you can find in the **Global Application Information** section of your [Tenant Advanced Settings](https://manage.auth0.com/#/tenant/advanced).

## Use the extension

To access the URL to use with your monitoring service:

1. Navigate to [Auth0 Dashboard > Extensions](https://manage.auth0.com/#/extensions), and click **Installed Extensions**.

2. Select **Auth0 AD/LDAP Connector Health Monitor**. A new window with a JSON snippet similar to this opens:

   ```json lines theme={null}
   {
     "message": "Use this url: 'https://sandbox.it.auth0.com/api/run/auth0user/auth0-ldap-conector-health-monitor?connection={MY-LDAP-CONNECTOR}' for monitoring your AD/LDAP connector."
   }
   ```

3. Enter the ID of your LDAP connection. To get the ID, go to  [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise), click the connection, and copy the value from the **Identifier** field.

Once finished, the provided URL can be used with your monitoring service to monitor your AD/LDAP connectors.

## Learn more

* [Troubleshoot AD/LDAP Connector](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-ad-ldap-connector)


# Authentication API Debugger Extension
Source: https://auth0.com/docs/customize/extensions/authentication-api-debugger-extension

Learn how to configure and use the Auth0 Authentication API Debugger extension.

The Authentication API Debugger extension allows you to test various endpoints of the Auth0 Authentication API.

## Install the extension

To install this extension:

1. Navigate to [Auth0 Dashboard > Extensions](https://manage.auth0.com/#/extensions), and select **Auth0 Authentication API Debugger**. The **Install Extension** window opens.
2. Select **Install**.

## Authorize the extension

Because the extension will communicate with the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> on your behalf to retrieve details about the Applications you have configured in your <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, you will need to authorize its access.

To authorize the extension:

1. If you're following this guide, you should already be on the [Installed Extensions](https://manage.auth0.com/#/extensions) view of [Auth0 Dashboard > Extensions](https://manage.auth0.com/#/extensions). Select **Auth0 Authentication API Debugger** to launch the extension. A consent dialog will appear, requesting access to your account.
2. Consent to allow the extension to access your account. After you consent, the extension launches.

## Configure the extension

After the extension is installed, you should apply the basic configuration. To configure the extension:

1. If you're following this guide, you should already have launched the extension. Select the **Configuration** view.

   <Frame>
     <img alt="Dashboard - Extensions - Authentication API Debugger - Configuration" />
   </Frame>
2. Set the following configuration parameters, and select **Save**:

* **Domain**: The domain for your tenant. This field is read-only and is displayed for informational purposes.
* **Application**: The Application for which you want to initiate any authentication flows. You can manage your Applications at [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications).
* **Callback URL**: The callback URL for this extension. You must also add this URL to the **Allowed Callback URLs** in the selected Application's settings.
* **State**: Optional state information that can be sent with the authentication flow.
* **Connection**: The name of the connection with which you want to log in. You can use this parameter to bypass the main login screen and go directly for the login screen of the relevant <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip>.

## Execute the flows

After configuring the extension, you can execute any of the flows by selecting the **OAuth2/OIDC** view.

<Callout icon="file-lines">
  For some of the flows, you may need to specify more settings than those applied for the basic configuration. These settings will depend on which flow is being executed, so we suggest that you see the [Auth0 Authentication API documentation](/docs/api) to learn more about the applicable parameters for each flow.
</Callout>

<Frame>
  <img alt="Dashboard - Extensions - Authentication API Debugger - OAuth OIDC Settings" />
</Frame>

Once you have executed a particular flow, you will see a screen that displays the information returned from Auth0. The exact information returned will depend on which flow was executed. An example of the results after executing a normal **OAuth2/OIDC Login** flow is as follows:

<Frame>
  <img alt="Dashboard - Extensions - Authentication API Debugger - Flow Executed" />
</Frame>

To execute another flow, select the **Login** view to return to the **Configuration** screen.


# Authorization Extension
Source: https://auth0.com/docs/customize/extensions/authorization-extension

Learn how to use the Authorization Extension to control user authorization behavior during runtime.

<Callout icon="file-lines">
  The [Authorization Core](/docs/manage-users/access-control/rbac) feature set and [Authorization Extension](/docs/customize/extensions/authorization-extension) are completely separate features. To manage groups, roles, or permissions, you need to use the feature they were originally created in.
</Callout>

The Authorization Extension provides support for user authorization via Groups, Roles, and Permissions. You can define the expected behavior during the login process, and your configuration settings will be captured in a rule that's executed during runtime. To learn more, read [Auth0 Rules](/docs/customize/rules).

With the Authorization Extension, you can store authorization data like groups, roles, or permissions in the outgoing token issued by Auth0. Your application can then consume this information by inspecting the token and take appropriate actions based on the user's current authorization context.

With the Authorization Extension, roles and permissions are set on a per-application basis. If you need the same roles or permissions on another application, you'll have to create them separately. Conversely, the [Authorization Core](/docs/manage-users/access-control/rbac) feature set provides much more flexibility with roles and permissions.

## Prerequisites

Before you can use the extension, you'll need to:

1. [Install](/docs/customize/extensions/authorization-extension/install-authorization-extension) the extension.
2. [Configure](/docs/customize/extensions/authorization-extension/configure-authorization-extension) how the extension will behave during the login transaction.
3. [Set up](/docs/customize/extensions/authorization-extension/set-up-authorization-extension-users) users, groups, roles, and permissions.

## Manage data

You can easily move data into or out of the extension using a JSON file. To learn more, read [Import and Export Authorization Extension Data](/docs/customize/extensions/authorization-extension/import-and-export-authorization-extension-data).

## Add functionality

Once the extension is up and running, you can add additional functionality to it.

* [Enable API access to the extension](/docs/customize/extensions/authorization-extension/enable-api-access-to-authorization-extension): Learn how you can automate provisioning and query the authorization context of your users in real-time, using the extension's API.
* [Explore Authorization Extension API endpoints](https://auth0.com/docs/api/authorization-extension): Learn about the Authorization Extension's API endpoints and how you can use them.
* [Use Authorization Extension data in rules](/docs/customize/extensions/authorization-extension/use-rules-with-the-authorization-extension): Learn how you can use rules to configure extra logic for your logins.

## Troubleshoot

Review our tips for [troubleshooting](/docs/troubleshoot/authentication-issues/troubleshoot-authorization-extension) page for commonly-encountered issues.

## Upgrade from previous versions

### Upgrade from version 2.6 or later

Upgrades from version 2.6 or later do not have breaking changes and require no special action.

### Upgrade from versions before 2.6

Authorization Extension 2.6 contains breaking changes that result from changed logic for storing and handling the API Key; these require you to perform additional steps upon upgrade, as detailed below. Failing to complete these steps will result in either an `InvalidApiKey` or `You are not allowed to access this application` error on rule execution. For more information, see the [GitHub changelog](https://github.com/auth0/auth0-authorization-extension/blob/master/CHANGELOG.md).

1. Go to [Auth0 Dashboard > Extensions](https://manage.auth0.com/#/extensions), and select the **Installed Extensions** view.
2. Locate **Auth0 Authorization**, select **Upgrade**, and confirm. Wait for the upgrade to complete.

#### Rotate the extension's API key

1. Select **Auth0 Authorization** to open the extension.
2. From the dropdown menu in the top-right of the extension dashboard, select **Configuration**.
3. Locate the **API Key** section, and select **Rotate**.

#### Republish the extension's rule

Select **Publish Rule**.

#### Delete the old extension rule if it exists

1. Go to [Auth0 Dashboard > Auth Pipeline > Rules](https://manage.auth0.com/#/rules).
2. Locate the `auth0-authz` rule. If it does not exist, you are done; otherwise, continue with the following steps.
3. Locate the `auth0-authorization-extension` rule and drag it into the position below the `auth0-authz` rule.
4. Check that the `auth0-authz` rule:

   * Was authored by the Authorization Extension and has not been modified manually
   * Will not change the authorization flow in a way that will grant access or privileges to undesired users if it is removed
5. If the above conditions are true, use the toggle to disable the `auth0-authz` rule. After verifying that everything works appropriately, you can decide whether to leave the rule disabled or remove it entirely.

## Learn more

* [Install Authorization Extension](/docs/customize/extensions/authorization-extension/install-authorization-extension)
* [Configure Authorization Extension](/docs/customize/extensions/authorization-extension/configure-authorization-extension)
* [Enable API Access to Authorization Extension](/docs/customize/extensions/authorization-extension/enable-api-access-to-authorization-extension)
* [Import and Export Authorization Extension Data](/docs/customize/extensions/authorization-extension/import-and-export-authorization-extension-data)
* [Use Rules with the Authorization Extension](/docs/customize/extensions/authorization-extension/use-rules-with-the-authorization-extension)
* [Troubleshoot Authorization Extension](/docs/troubleshoot/authentication-issues/troubleshoot-authorization-extension)


# Configure Authorization Extension
Source: https://auth0.com/docs/customize/extensions/authorization-extension/configure-authorization-extension

Learn how to configure the Authorization Extension.

<Callout icon="file-lines">
  Auth0 provides two ways to implement role-based access control (RBAC), which you can use in place of or in combination with your API's own internal access control system:

  * [Authorization Core](/docs/manage-users/access-control/rbac)
  * [Authorization Extension](/docs/customize/extensions/authorization-extension)

  The Authorization Core feature set matches the functionality of the Authorization Extension, improves performance and scalability, and provides a more flexible RBAC system than the Authorization Extension.

  Currently, both implement the key features of RBAC and allow you to restrict the custom scopes defined for an API to those that have been assigned to the user as permissions.
</Callout>

Before the extension can enforce your authorization logic, you need to configure how it will behave during the login transaction. Your configuration settings will be captured in a [rule](/docs/customize/rules) that executes during runtime.

## Prerequisites

[Install the Authorization Extension](/docs/customize/extensions/authorization-extension/migrate-to-authorization-extension-v2)

## Configure extension

1. Go to [Auth0 Dashboard > Extensions](https://manage.auth0.com/#/extensions), and select **Auth0 Authorization**.
2. Choose **Configuration** at the top right of the **Authorization Dashboard**.

   <Frame>
     <img alt="Dashboard - Authorization Extension Dashboard - Configuration" />
   </Frame>
3. This brings you to the **Rule Configuration** section of the **Configuration** page. All of the changes you make in the sections under **Token Contents**, such as those related to groups, roles, and permissions, will be reflected in the rule you export at the completion of this step.

   <Frame>
     <img alt="Authorization Extension Configuration" />
   </Frame>

### ApiKey

The rule uses the ApiKey to communicate with the Authorization Extension API and get the policy. The ApiKey is stored as a rule config and will be created automatically when the rule is published. To rotate the ApiKey, click the **Rotate** button; when the ApiKey is rotated, the rule config will be updated automatically.

## Add authorization information to the token issued

You can store authorization data like groups, roles, or permissions in the outgoing token issued by Auth0. Your application can then consume this information by inspecting the token and take appropriate actions based on the user's current authorization context.

To add groups, roles, and/or permissions information to the outgoing token, enable the slider next to the option you want to be included.

<Warning>
  Storing too much data in the token may cause performance issues or even prevent the issuance of the token. Be sure to store only what you need. If you need a large amount of user data readily available, consider using persistence instead of adding the data to the token.
</Warning>

### Merge authorization data from IdP

You might have users that receive groups, roles, or permissions from the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> (IdP) you're using, such as Active Directory. If you want to merge these items (to preserve them) with the ones defined in the Authorization Extension, make sure you enable the appropriate **Passthrough** options. Enable the slider next to the appropriate merges you want enabled.

### Store authorization information in user profiles

If your authorization context is large (for example, the user might belong to many groups or have been granted many permissions), you might find it useful to store some of the authorization content in the users' profiles. This allows you to store less information in the token, which means you're less likely to see performance-related issues or even problems with token issuance. **Persistence** is the process by which you store groups, roles, and permissions information in the users' profiles.

The data will be stored in the user's `app_metadata` field, and you can then use the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> or the [Dashboard](https://manage.auth0.com/#/users) to retrieve this information after the user has logged in.

<Frame>
  <img alt="Authorization Extension - Configuration - Persistence" />
</Frame>

## Save changes to rule

Once you've configured your rule, click **Publish Rule**. This creates a rule for your tenant that executes after each user login.

### View rule

If you'd like to see the rule you've created, you can do so at [Auth0 Dashboard > Auth Pipeline > Rules](https://manage.auth0.com/#/rules).

You can open the rule to see the exact rules configuration.

## Learn more

* [Import and Export Authorization Extension Data](/docs/customize/extensions/authorization-extension/import-and-export-authorization-extension-data)
* [Enable API Access to Authorization Extension](/docs/customize/extensions/authorization-extension/enable-api-access-to-authorization-extension)
* [Use Rules with the Authorization Extension](/docs/customize/extensions/authorization-extension/use-rules-with-the-authorization-extension)
* [Set Up Users in Authorization Extension Dashboard](/docs/customize/extensions/authorization-extension/set-up-authorization-extension-users)
* [Troubleshoot Authorization Extension](/docs/troubleshoot/authentication-issues/troubleshoot-authorization-extension)
* [Migrate to Authorization Extension v2](/docs/customize/extensions/authorization-extension/migrate-to-authorization-extension-v2)


# Enable API Access to Authorization Extension
Source: https://auth0.com/docs/customize/extensions/authorization-extension/enable-api-access-to-authorization-extension

Describes how to enable API access to the Authorization Extension.

<Callout icon="file-lines">
  Auth0 provides two ways to implement role-based access control (RBAC), which you can use in place of or in combination with your API's own internal access control system:

  * [Authorization Core](/docs/manage-users/access-control/rbac)
  * [Authorization Extension](/docs/customize/extensions/authorization-extension)

  The Authorization Core feature set matches the functionality of the Authorization Extension, improves performance and scalability, and provides a more flexible RBAC system than the Authorization Extension.

  Currently, both implement the key features of RBAC and allow you to restrict the custom scopes defined for an API to those that have been assigned to the user as permissions.
</Callout>

Once configured and set up, your extension should contain users, as well as groups, roles, and permissions. You can automate provisioning and query the authorization context of your users in real-time if you enable API access to your extension.

## Enable API access

1. Go to [Auth0 Dashboard > Extensions > Auth0 Authorization](https://manage.auth0.com/#/extensions).
2. To get to **API** section, select your Auth0 tenant name on the top right of the **Authorization Dashboard**, then select **API**.

   <Frame>
     <img alt="Dashboard - Extensions - Authorization Extensions Dashboard - Select API" />
   </Frame>
3. On the **Settings** page, enable the **API Access** switch.

   <Frame>
     <img alt="Dashboard - Extensions - Authorization Extensions Dashboard - Enable API Access" />
   </Frame>
4. Once API Access is enabled, you'll be able to see or control (within the extension) some of the parameters of the tokens issued by the API. You can control the **time to expiration** of the token, as well as view the token's **audience**, **issuer**, and **URL** to access the API.

   <Frame>
     <img alt="Dashboard - Extensions - Authorization Extensions Dashboard - API Access Enabled" />
   </Frame>

## Access extension API

When you enabled API access to the extension, Auth0 automatically created an API for your use in the [Auth0 Dashboard](https://manage.auth0.com/#/apis). To access the API, you'll need to create a Machine to Machine Application, which is the entity that interacts with the API itself.

### Create applications

1. Navigate to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), and select **Create Application**. Name your new Application, and choose the **Machine to Machine Application** type. Select **Create** to proceed.
   You'll be redirected to the **Quick Start** page of the Application, where you can customize the living documentation based on the API with which you'll use the Application. Select the API that Auth0 created for your extension (it should be called **auth0-authorization-extension-api** or similar).
   Since this is the first time you're working with the API and Application together, you'll see a message that says, "This application is not authorized for this API." To authorize the application for use with the API, select **Navigate to the API and Authorize**.

   <Frame>
     <img alt="Dashboard - Authorization Extensions - Client Quick Start" />
   </Frame>
2. You'll see a list of Machine to Machine Applications you can use with your API. Enable the switch next to the Application you just created to authorize it.

   <Frame>
     <img alt="Dashboard - Authorization Extension - Clients for API" />
   </Frame>

   Once you've authorized the Application, you'll see the **Grant ID**. You can also select the **Scopes** to be granted to the Application. The scopes you grant depends on the endpoints you want to access.
3. If you make any changes to the scopes, select **Update** to save.

   <Frame>
     <img alt="Dashboard - Authorization Extension Dashboard - Client Scopes" />
   </Frame>

### Get access token

To access the API, you'll need to [ask for and obtain the appropriate token](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow/call-your-api-using-the-client-credentials-flow).

### Call the API

You can call the API via:

* An HTML request
* A cURL command

You can also find detailed information about the endpoints, as well as samples on how to call each endpoint using the three methods above, in the [Authorization Extension API Explorer](https://auth0.com/docs/api/authorization-extension).

You can also refer to the **API Explorer**, which documents everything you can do via command line once you've enabled access to your extension via API.

Select the **Explorer** page for the API documentation.

<Frame>
  <img alt="Authorization Extension API Explorer" />
</Frame>

## Learn more

* [Use Rules with the Authorization Extension](/docs/customize/extensions/authorization-extension/use-rules-with-the-authorization-extension)
* [Import and Export Authorization Extension Data](/docs/customize/extensions/authorization-extension/import-and-export-authorization-extension-data)
* [Troubleshoot Authorization Extension](/docs/troubleshoot/authentication-issues/troubleshoot-authorization-extension)


# Import and Export Authorization Extension Data
Source: https://auth0.com/docs/customize/extensions/authorization-extension/import-and-export-authorization-extension-data

Describes how to import and export Authorization Extension Data.

<Callout icon="file-lines">
  Auth0 provides two ways to implement role-based access control (RBAC), which you can use in place of or in combination with your API's own internal access control system:

  * [Authorization Core](/docs/manage-users/access-control/rbac)
  * [Authorization Extension](/docs/customize/extensions/authorization-extension)

  The Authorization Core feature set matches the functionality of the Authorization Extension, improves performance and scalability, and provides a more flexible RBAC system than the Authorization Extension.

  Currently, both implement the key features of RBAC and allow you to restrict the custom scopes defined for an API to those that have been assigned to the user as permissions.
</Callout>

You can import new data from or export existing authorization data to a JSON file. This can be useful when moving environments.

<Callout icon="file-lines">
  Roles and permissions are linked to specific applications. If you export your JSON file and import it into a different environment, you will need to change the client ID for these records.
</Callout>

1. Go to the **Import/Export** section by clicking **Configuration** on the drop-down menu accessible by clicking on your tenant name at the top right of the **Authorization Dashboard**.

   <Frame>
     <img alt="Dashboard - Authorization Extension Dashboard - Configuration" />
   </Frame>

2. Select **Import/Export**.

   <Frame>
     <img alt="Dashboard - Authorization Extension Dashboard - Configuration - Import Export" />
   </Frame>

3. Use this form to copy and paste or edit the JSON data. Then, click either the **Import** or **Export** button to begin the import/export process. Here is an example of the JSON file:

   ```json lines expandable theme={null}
   {
     "configuration": [
       {
         "_id": "v1",
         "rolesInToken": true
       }
     ],
     "groups": [
       {
         "name": "Admin",
         "description": "Administrators of the company",
         "_id": "f185e4aa-0c28-4da7-8639-ae998512c838"
       },
       {
         "_id": "5f5371c6-c8ff-4c7c-825e-c5ef8ac51cad",
         "name": "HR",
         "description": "Human Resources",
         "members": [
           "auth0|59c13f5ed6e34e41877c0810"
         ],
         "roles": [
           "6ab494d6-2592-4af0-a62f-2c13646143d0"
         ],
         "nested": [
           "59f2adac-9016-4051-ad02-dd5196b8f99e"
         ]
       },
       {
         "name": "Trainers",
         "description": "HR Trainers for New Employees",
         "_id": "59f2adac-9016-4051-ad02-dd5196b8f99e"
       }
     ],
     "permissions": [
       {
         "applicationType": "client",
         "applicationId": "fhginJh46igC6Rj630UeZBhUyDrgvJ08",
         "description": "approve company expenditures",
         "name": "Approve Expenses",
         "_id": "e61f10f4-837e-4011-a52f-53618bd659e7"
       },
       {
         "applicationType": "client",
         "applicationId": "fhginJh46igC6Rj630UeZBhUyDrgvJ08",
         "description": "approve hiring of employees",
         "name": "Hire employees",
         "_id": "03b94d9b-8893-413d-bdb3-451192264594"
       }
     ],
     "roles": [
       {
         "applicationType": "client",
         "applicationId": "fhginJh46igC6Rj630UeZBhUyDrgvJ08",
         "description": "Control over HR-related tasks",
         "name": "HR Manager",
         "permissions": [
           "e61f10f4-837e-4011-a52f-53618bd659e7",
           "03b94d9b-8893-413d-bdb3-451192264594"
         ],
         "_id": "6ab494d6-2592-4af0-a62f-2c13646143d0"
       }
     ]
   }
   ```

## Learn more

* [Enable API Access to Authorization Extension](/docs/customize/extensions/authorization-extension/enable-api-access-to-authorization-extension)
* [Use Rules with the Authorization Extension](/docs/customize/extensions/authorization-extension/use-rules-with-the-authorization-extension)
* [Troubleshoot Authorization Extension](/docs/troubleshoot/authentication-issues/troubleshoot-authorization-extension)


# Install Authorization Extension
Source: https://auth0.com/docs/customize/extensions/authorization-extension/install-authorization-extension

Describes how to install the Auth0 Authorization Extension.

<Callout icon="file-lines">
  Auth0 provides two ways to implement role-based access control (RBAC), which you can use in place of or in combination with your API's own internal access control system:

  * [Authorization Core](/docs/manage-users/access-control/rbac)
  * [Authorization Extension](/docs/customize/extensions/authorization-extension)

  The Authorization Core feature set matches the functionality of the Authorization Extension, improves performance and scalability, and provides a more flexible RBAC system than the Authorization Extension.

  Currently, both implement the key features of RBAC and allow you to restrict the custom scopes defined for an API to those that have been assigned to the user as permissions.
</Callout>

## Prerequisite

Before you begin, make sure that you have an existing application that can be used with the Authorization Extension. You can use the following types of applications:

* Native apps
* Regular web apps
* Single-page apps

Applications without an assigned type or machine-to-machine apps cannot be used with this extension.

## Install extension

1. Go to [Auth0 Dashboard > Extensions](https://manage.auth0.com/#/extensions).
2. Select **Auth0 Authorization** and answer the prompt to install.
3. Choose where you would like to store your data: Webtask Storage or Amazon S3 bucket.

Once the extension is installed, you will see it listed under the **Installed Extensions**.

<Frame>
  <img alt="Dashboard - Extensions - Installed Extensions - Authorization Extension" />
</Frame>

<Warning>
  Installing this extension creates an auth0-authz application for your account. **Do not edit or delete this application!** If you uninstall the extension at a later date, this application will be deleted automatically.
</Warning>

When you click the link to open the extension for the first time, you will be asked to provide permission for the extension to access your Auth0 account. If you do, you will be taken to the Authorization Dashboard.

<Frame>
  <img alt="Dashboard - Extensions - Authorization Dashboard - Users" />
</Frame>

### Webtask storage

The extension will use Webtask Storage by default, and you are limited to 500 KB of data. This is equivalent to:

* 1000 groups and 3000 users, where each user is a member of 3 groups
* 20 groups and 7000 users, where each user is a member of 3 groups

### Amazon S3

Alternatively, you can use Amazon S3 as a storage provider. Amazon S3 is a file-based storage platform, which means it writes in parallel. This may cause issues, but the extension's storage logic attempts to take this into account. However, if you automate the creation of groups, roles, or permissions, Auth0 recommends that you use sequential calls to the API.

<Callout icon="file-lines">
  This extension has limitations in terms of performance and is not meant to be used with large data sets. Before you choose Amazon S3 for data storage, we recommend that you test and see how it performs for your case. Performance degradation is also a possibility as more data is added to S3.
</Callout>

To use Amazon S3, you need to:

1. Create an S3 bucket.
2. Create an IAM user and get the Key ID for that user.
3. Create a policy for the IAM user that allows the user to make changes to the bucket.

```json lines expandable theme={null}
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:DeleteObject",
                "s3:GetObject",
                "s3:ListBucket",
                "s3:PutObject"
            ],
            "Resource": [
                "arn:aws:s3:::{nameOfYourBucket}/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::{nameOfYourBucket}"
            ],
            "Condition": {}
        }
    ]
}
```

## Learn more

* [Configure Authorization Extension](/docs/customize/extensions/authorization-extension/configure-authorization-extension)
* [Set Up Users in Authorization Extension Dashboard](/docs/customize/extensions/authorization-extension/set-up-authorization-extension-users)
* [Enable API Access to Authorization Extension](/docs/customize/extensions/authorization-extension/enable-api-access-to-authorization-extension)
* [Import and Export Authorization Extension Data](/docs/customize/extensions/authorization-extension/import-and-export-authorization-extension-data)
* [Troubleshoot Authorization Extension](/docs/troubleshoot/authentication-issues/troubleshoot-authorization-extension)


# Migrate to Authorization Extension v2
Source: https://auth0.com/docs/customize/extensions/authorization-extension/migrate-to-authorization-extension-v2

Describes how to upgrade the Authorization Extension v2.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

<Callout icon="file-lines">
  Auth0 provides two ways to implement role-based access control (RBAC), which you can use in place of or in combination with your API's own internal access control system:

  * [Authorization Core](/docs/manage-users/access-control/rbac)
  * [Authorization Extension](/docs/customize/extensions/authorization-extension)

  The Authorization Core feature set matches the functionality of the Authorization Extension, improves performance and scalability, and provides a more flexible RBAC system than the Authorization Extension.

  Currently, both implement the key features of RBAC and allow you to restrict the custom scopes defined for an API to those that have been assigned to the user as permissions.
</Callout>

One of the major changes between versions 1 and 2 of the Authorization Extension is the removal of the **Applications** section. This section was removed to simplify its inherent complexity, such as when it was used to define a policy for access control. The desired approach for such use cases is to use [rules](/docs/customize/rules).

## Upgrade extension version

To upgrade the Authorization Extension, go to [Auth0 Dashboard > Extensions](https://manage.auth0.com/#/extensions), and select the **Installed Extensions** view.

On the Authorization Extension row, you'll see a link that will begin the upgrade process to the latest version.


# Set Up Users in Authorization Extension Dashboard
Source: https://auth0.com/docs/customize/extensions/authorization-extension/set-up-authorization-extension-users

Learn how to set up users, groups, roles, and permissions in the Authorization Extension Dashboard.

<Callout icon="file-lines">
  Auth0 provides two ways to implement role-based access control (RBAC), which you can use in place of or in combination with your API's own internal access control system:

  * [Authorization Core](/docs/manage-users/access-control/rbac)
  * [Authorization Extension](/docs/customize/extensions/authorization-extension)

  The Authorization Core feature set matches the functionality of the Authorization Extension, improves performance and scalability, and provides a more flexible RBAC system than the Authorization Extension.

  Currently, both implement the key features of RBAC and allow you to restrict the custom scopes defined for an API to those that have been assigned to the user as permissions.
</Callout>

If you have an application that is accessible to everyone within your corporation, the **users** are the individuals to whom you'd like to grant access to your application. If you have a large number of users, managing the access rights and permissions for each one individually can become unwieldy. The **groups** functionality helps make this process easier. For example, your groups can reflect the various departments of your organization: accounting, information technology, engineering, support, and so on. You might also create nested groups, such as by dividing the engineering group into two nested groups: internal tools and client-facing applications. Your organization hierarchy therefore looks like this:

* Corporation

  * Accounting
  * Information Technology
  * Engineering

    * Internal Tools
    * Client-Facing Applications
  * Support

<Frame>
  <img alt="Authorization Extension Corporate Groups Diagram" />
</Frame>

You can add users to your groups manually or dynamically based on the Connection(s) they're using to access your application. For example, if someone logs in using the Active Directory Connection and their AD profile indicates that they're in the Marketing group, the Authorization Extension can also add them to the Marketing group you're managing with the extension.

Finally, we have permissions and roles, which are groups of permissions. The purpose of the latter is to make it easier to assign several permissions simultaneously to either a user or a group.

<Frame>
  <img alt="Authorization Extension Roles Permissions Diagram" />
</Frame>

For example, you may want to grant permissions to:

* Approve requests for travel
* Approve travel expenses

Rather than assigning both permissions to groups/users, you can roll the two (along with many others) into a role called **Travel Administrator**. You can then assign Travel Administrator to individual users or to one or more groups.

<Frame>
  <img alt="Authorization Extension Groups Roles Permissions Diagram" />
</Frame>

## Users

The **Users** section lists all the current users of your applications. Here you can find a specific user, see their profile, change their group affiliations, and change their roles.

<Frame>
  <img alt="Dashboard - Extensions - Authorization Dashboard - Users" />
</Frame>

## Groups

To create and manage the groups with which you'll manage users' settings, click **Groups** in the Authorization Dashboard.

Click **Create Group** to create a new group for your users. You'll be asked to provide a **name** for the group, as well as a **description** for that group.

You can manage your users and their group affiliations in one of two ways:

* Opening the **group** and managing the group's users

  <Frame>
    <img alt="Dashboard - Extensions - Authorization Extension - Group Membership - Group Management" />
  </Frame>
* Opening the **user** and managing the user's group membership(s)

  <Frame>
    <img alt="Dashboard - Extensions - Authorization Extension - Group Membership - User Management" />
  </Frame>

The groups you'll create are dependent on the needs of your business process. For example, you might have a group for your users in finance, a group for your users in IT, and so on. Additionally, you may create nested groups that are similar to the following:

* Example Company

  * Accounting

    * External Accountants
  * Human Resources
  * Finance

    * Finance IT Support
  * Management

To create nested groups, you must first create all of the individual groups via the **CREATE** button on the Groups page of the Authorization Dashboard.

To nest the groups:

1. Open up the top-level Group (in the example above, this would be the Example Company Group)
2. Click on the **Nested Groups** tab
3. Click on the **ADD NESTED GROUP** button. You will be presented with a list of Groups that can be added to the primary Group. To select a particular Group, click on the checkbox to the left of the name. After each selection, you will be returned to the primary group page. Continue this process until you have included all the Groups you need.

With nested groups, adding a user to a sub-group also grants the user permissions granted to the groups that are parents (and grandparents) of that group. For example, adding a user to the External Accountants group automatically makes them a member of the Finance and Company Groups. However, the user is only explicitly a member of External Accountants; all other memberships are purely dynamic and are calculated as needed (for example, when loading the user's group memberships).

To prevent confusion, you will be shown both the explicit members AND the "calculated members" that result from nested groups whenever you open a specific group's page in the Authorization Dashboard.

### Group mappings

Group Mappings allow you to dynamically add users to different Groups based on the users' Connections. Essentially, using the Connection and the groups information provided by the <Tooltip href="/docs/glossary?term=IdP">IdP</Tooltip>, you can dynamically make the user a member of the group in which you've created the appropriate mapping.

For example, suppose your users are logging in using their Active Directory (AD) credentials. As part of their identity, AD allows users to have group information associated (such as "Administrative" and "Marketing").

You can then configure group mappings to look at a user's profile if they're connecting with the Active Directory connection. When the extension sees that the person is a part of the "Administrative" group, it will automatically make the user a member of your company's Admin group.

<Frame>
  <img alt="Dashboard - Extensions - Authorization Extensions Dashboard - Group Mapping" />
</Frame>

## Roles

The roles that you will create will depend on the access to certain permissions in your application. For example, let's say that you have an application that allows employees to enter in company expenses. You want all employees to be able to submit expenses, but want certain Finance users to have more admin type of actions such as being able to approve or delete expenses. These actions can be mapped to [Permissions](#permissions) and then assigned to a certain Role.

You can create different types of Roles such as: Expense Admins, Expense Manager, and Expense User for your Expense Management Tool.

<Frame>
  <img alt="Dashboard - Extensions - Authorization Extensions Dashboard - Permissions" />
</Frame>

To add a role, click the **CREATE ROLE** button from the **Roles** section of the dashboard. Then choose the application this Role applies to (such as Expense Management Tool) and then add a name of the role (such as Expense Admins) and a description of the role. Then select the permissions you wish to grant to this role. If you haven't yet created your permissions you can add them later to an existing Role.

<Frame>
  <img alt="Dashboard - Extensions - Authorization Extensions Dashboard - Add Role to User" />
</Frame>

Once you have a **Role** created, you can add it to a user so they can then have the associated **Permissions**. To add a role to a user, find the user in the **Users** section, then click the **Roles** tab. Then click **ADD ROLE TO USER** to choose which roles you wish to assign to a user, then click **SAVE**.

## Permissions

Permissions are the actions or functions that can be added to Roles.

Using the previous example of an Expense application, let's look at possible roles and how they can be associated with certain permissions:

* Role: Expense User

  * Permissions:

    * View their own expenses
    * Add a new expense
* Role: Expense Admin

  * Permissions:

    * Approve expenses
    * View all user expenses
    * Delete expenses
    * Add a new expense

To create a new permission, go to the **Permissions** section of the Authorization Extension dashboard.

<Frame>
  <img alt="Dashboard - Extensions - Authorization Extensions Dashboard - Permissions" />
</Frame>

Then click the **CREATE PERMISSION** button. Then enter the name of the permission, the description and select the application for which this permission applies.

<Frame>
  <img alt="Dashboard - Extensions - Authorization Extensions Dashboard - Create Permissions" />
</Frame>

Once you have your permissions created, you can associate them with roles.

## Learn more

* [Configure Authorization Extension](/docs/customize/extensions/authorization-extension/configure-authorization-extension)
* [Enable API Access to Authorization Extension](/docs/customize/extensions/authorization-extension/enable-api-access-to-authorization-extension)
* [Import and Export Authorization Extension Data](/docs/customize/extensions/authorization-extension/import-and-export-authorization-extension-data)
* [Troubleshoot Authorization Extension](/docs/troubleshoot/authentication-issues/troubleshoot-authorization-extension)
* [Use Rules with the Authorization Extension](/docs/customize/extensions/authorization-extension/use-rules-with-the-authorization-extension)


# Use Rules with the Authorization Extension
Source: https://auth0.com/docs/customize/extensions/authorization-extension/use-rules-with-the-authorization-extension

Describes how to use information from the Authorization Extension in rules.

<Callout icon="file-lines">
  Auth0 provides two ways to implement role-based access control (RBAC), which you can use in place of or in combination with your API's own internal access control system:

  * [Authorization Core](/docs/manage-users/access-control/rbac)
  * [Authorization Extension](/docs/customize/extensions/authorization-extension)

  The Authorization Core feature set matches the functionality of the Authorization Extension, improves performance and scalability, and provides a more flexible RBAC system than the Authorization Extension.

  Currently, both implement the key features of RBAC and allow you to restrict the custom scopes defined for an API to those that have been assigned to the user as permissions.
</Callout>

You can use Auth0 Rules with the Authorization Extension to do things like:

* Add custom claims to the issued token.
* Determine the user's group membership, roles, and permissions.
* Store the user's groups, roles, and permissions info as part of the `app_metadata`.
* Add the user's groups, roles, and permissions to the outgoing token (which can be requested via the `openid groups permissions roles` scope).

Because the above logic is part of a rule, it will only be executed in the context of a login. If users are added to or removed from a group, this change will only be reflected in Auth0 after the user's next login.

To learn more, read [Auth0 Rules](/docs/customize/rules).

## Add custom claims to the issued token

To add custom claims to your tokens, you can do so by creating an additional rule that allows the Authorization Extension to do so. Custom claims can be namespaced or non-namespaced.

To learn more, read [Create Custom Claims.](/docs/secure/tokens/json-web-tokens/create-custom-claims)

You should limit the number of claims you add to the token.

```javascript lines theme={null}
function (user, context, callback) {
  var namespace = 'http://yourdomain/claims/'; // You can set your own namespace, but do not use an Auth0 domain

  // Add the namespaced tokens. Remove any which is not necessary for your scenario
  context.idToken[namespace + "permissions"] = user.permissions;
  context.idToken[namespace + "groups"] = user.groups;
  context.idToken[namespace + "roles"] = user.roles;
  
  callback(null, user, context);
}
```

This rule must run **after** the Authorization Extension rule. To make sure this happens, make sure that you place it below the Authorization Extension rule.

When calling the `/authorize` endpoint or configuring Lock, you'll need to specify the information you want in the `scope` by indicating `groups`, `permissions` and/or `roles`.

## Control app access

You can also write rules that are executed after the Authorization Extension rule to do things like control access to your application. One method of doing this is to specify the roles that are required for each application using the application metadata.

For more details, review [Manage Metadata with Rules](/docs/manage-users/user-accounts/metadata/manage-metadata-rules).

### Set app metadata required roles

You can set the app's metadata with roles, which are groups of permissions that you group together to create a specific set of functionality. You can think of this step as "tagging" the app so that the rules you set up know which app to act on.

1. ⁠⁠⁠⁠To set the `context.clientMetadata` field with `required_roles`, select the application you want to work at [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications).
   This brings you to the application's **Settings**. Scroll down, and select **Show Advanced Settings** at the bottom of the page.
2. Under **Application Metadata** add an item setting the **Key** to `required_roles` and in **Value** field list your roles in comma separated style. Select **+ Add** to add the field.
3. When finished, select **Save Changes**. Now, when you log in from this application, in `context.clientMetadata`, you will have the `required_roles` with the roles value string you entered.

### Create rule enforcing app roles

Now that each app has a role associated with it, you can create the rule executes with this piece of app information in context.

1. Before creating this rule, enable **Roles** under the **Token Contents** and publish the Authorization Extension rule.

2. Add this rule and make sure it is listed after the generated "auth0-authorization-extension" rule.

3. After setting `required_roles`, create a new [rule](https://manage.auth0.com/#/rules) with the following body:

   ```javascript lines theme={null}
   function (user, context, callback) {
     context.clientMetadata = context.clientMetadata || {};
     if (context.clientMetadata.required_roles && context.clientMetadata.required_roles.length){
       if (user.roles) {
         var _ = require('lodash');
         var roles = context.clientMetadata.required_roles.split(',');
         var matchingRoles =_.filter(user.roles, function(roleName) {
           return _.includes(roles, roleName);
         });

         if (matchingRoles && matchingRoles.length) {
           return callback(null, user, context);
         }
       }

       return callback(new UnauthorizedError('You do not have the required role to access ' + context.clientName));
     }

    callback(null, user, context);
   }
   ```

## Learn more

* [Import and Export Authorization Extension Data](/docs/customize/extensions/authorization-extension/import-and-export-authorization-extension-data)
* [Enable API Access to Authorization Extension](/docs/customize/extensions/authorization-extension/enable-api-access-to-authorization-extension)
* [Troubleshoot Authorization Extension](/docs/troubleshoot/authentication-issues/troubleshoot-authorization-extension)


# Delegated Administration Extension v3
Source: https://auth0.com/docs/customize/extensions/delegated-administration-extension

Learn how to use the Delegated Administration Extension (DAE) to expose the Users section of the Auth0 Dashboard to a select group of users without allowing them access to the rest of the Dashboard.

<Callout icon="file-lines">
  Auth0 recommends that you use the Tenant Members settings to designate tenant usage capabilities to other users and admins in your organization. To learn more, read [Dashboard Access](/docs/get-started/manage-dashboard-access).
</Callout>

The Delegated Administration Extension (DAE) allows you to grant administrative permissions to a select group of people without providing access to any other area.

## Configure the DAE

To configure the DAE, you must:

1. [Register the application with Auth0](#register-the-application-with-auth0)
2. [Create a database connection](#create-a-database-connection)
3. [Disable all other connections for the Auth0 Application](#disable-all-other-connections-for-the-auth0-application)
4. [Create users for database connection](#create-user-for-the-database-connection)
5. [Assign roles to users](#assign-roles-to-users)
6. [Install and configure the extension](#install-and-configure-the-extension)
7. [Use the extension](#use-the-extension)

### Register the application with Auth0

Create the Application that the Delegated Administration Extension will expose to those who should have administrative privileges for the Users page. To do this, [create a delegated admin application](/docs/customize/extensions/delegated-administration-extension/create-delegated-admin-applications) in Auth0.

When finished, note the application's **<Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>**.

### Create a database connection

In this example, a database connection will serve as the source of your users who are allowed access to the Users area. To configure this, [create a database connection](/docs/get-started/applications/set-up-database-connections).

While setting up your connection:

* Use a fitting connection name, such as `HelpDesk`.
* Enable the **Disable Sign Ups** toggle. For security purposes, this ensures that even users who have the link to the database connection cannot sign themselves up.

### Disable all other connections for the Auth0 application

By default, Auth0 enables all connections associated with your tenant when you create a new Application. For this example, disable all connections other than your newly-created database connection. This helps keep the application secure because no one can add themselves using one of your existing connections.

To configure this, [update application connections](/docs/get-started/applications/update-application-connections).

### Create users for the database connection

To continue, you must [create at least one user](/docs/manage-users/user-accounts/create-users) and attach it to your connection.

### Assign roles to users

<Callout icon="file-lines">
  Although the [Delegated Administration Extension (DAE)](/docs/customize/extensions/delegated-administration-extension) and the [Authorization Core](/docs/manage-users/access-control/rbac) feature set are completely separate features, you can use the Authorization Core feature set to create and manage roles for the DAE using Actions. To learn how, see [Sample Use Cases: Actions with Authorization](/docs/manage-users/access-control/sample-use-cases-actions-with-authorization).
</Callout>

<Callout icon="file-lines">
  When logging in as a user using Organizations with Delegated Administration Extension (DAE), your user roles will not be available. Only your Organization member roles will be available within `event.authorization.roles.` To add roles to Organization members, read [Add Roles to Organization Members](/docs/manage-users/organizations/configure-organizations/add-member-roles).
</Callout>

Auth0 grants access to the Delegated Administration Extension (DAE) for the user(s) attached to your connection based on their roles. These are DAE-specific roles:

<table>
  <thead>
    <tr>
      <th>This role...</th>
      <th>Grants permission to...</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>Delegated Admin - User</code></td>
      <td>Search for users, create users, open users, and execute actions on users (such as delete or block).</td>
    </tr>

    <tr>
      <td><code>Delegated Admin - Administrator</code></td>
      <td>Do everything that the Delegated Admin - User can, plus see all logs in the tenant and configure Hooks.</td>
    </tr>

    <tr>
      <td><code>Delegated Admin - Auditor</code></td>
      <td>Search for users and view user information, but not make changes. Action-based buttons are not visible to this role.</td>
    </tr>

    <tr>
      <td><code>Delegated Admin - Operator</code></td>
      <td>Access user management and logs, but not the extension configuration section.</td>
    </tr>
  </tbody>
</table>

When working with roles, we recommend that you use the [Authorization Core](/docs/manage-users/access-control/rbac) feature set:

1. [Create DAE roles](/docs/manage-users/access-control/configure-core-rbac/roles/create-roles). The names of the roles you create must match the names of the pre-defined DAE roles above.

2. [Assign DAE roles to a user manually](/docs/manage-users/access-control/configure-core-rbac/rbac-users/assign-roles-to-users).

3. Add user roles to the DAE namespace in the ID Token using [Actions](/docs/customize/actions)**:**

   ```text lines theme={null}
   exports.onExecutePostLogin = async (event, api) => {
     const namespace = `https://{yourTenant}/auth0-delegated-admin`;
     if (event.client.client_id === 'CLIENT_ID' && event.authorization) {
       api.idToken.setCustomClaim(namespace, { "roles": event.authorization.roles });
     }
   };
   ```

Remember to replace the `CLIENT_ID` placeholder with your delegated admin application's **Client ID** andreplace `{yourTenant}` with your tenant name. For example, if your tenant's name is "tenant\_name\_example", the namespace would be: `https://tenant_name_example/auth0-delegated-admin`

To learn more about creating Actions, read [Write Your First Action](/docs/customize/actions/write-your-first-action)

<Warning>
  Auth0 returns profile information in a structured claim format as defined by the [OpenID Connect (OIDC) specification](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). This means that custom claims added to ID tokens or access tokens must [conform to guidelines and restrictions](/docs/secure/tokens/json-web-tokens/create-custom-claims) to avoid possible collisions.
</Warning>

<Callout icon="file-lines">
  Using Authorization Core will define roles in the `context.authorization` object.

  If you choose not to use Authorization Core, you should define DAE roles in one of the following fields on the user profile:

  * `user.app_metadata.roles`
  * `user.app_metadata.authorization.roles`
</Callout>

## Install and configure the extension

Now that we've created and configured an application, a connection, and our user, we can [install and configure the Delegated Admin Extension](/docs/customize/extensions/delegated-administration-extension/install-delegated-admin-extension) itself.

## Use the extension

Once installed, you are ready to use the Delegated Admin Extension.

Navigate to the extension using the appropriate login link for your region and your tenant's extensibility runtime.

<table>
  <thead>
    <tr>
      <th>Location</th>
      <th>Name</th>
      <th>Login Link</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Australia</td>
      <td>AU</td>
      <td>`https://{yourTenant}.au.webtask.io/auth0-delegated-admin`</td>
    </tr>

    <tr>
      <td>Europe</td>
      <td>EU</td>
      <td>`https://{yourTenant}.eu.webtask.io/auth0-delegated-admin`</td>
    </tr>

    <tr>
      <td>Europe</td>
      <td>EU-2</td>
      <td>`https://{yourTenant}.eu.webtask.run/auth0-delegated-admin`</td>
    </tr>

    <tr>
      <td>Japan</td>
      <td>JP-1</td>
      <td>`https://{yourTenant}.jp.webtask.run/auth0-delegated-admin`</td>
    </tr>

    <tr>
      <td>UK</td>
      <td>UK</td>
      <td>`https://{yourTenant}.uk.webtask.run/auth0-delegated-admin`</td>
    </tr>

    <tr>
      <td>USA</td>
      <td>US-1</td>
      <td>`https://{yourTenant}.us.webtask.io/auth0-delegated-admin`</td>
    </tr>

    <tr>
      <td>USA</td>
      <td>US-3</td>
      <td>`https://{yourTenant}.us.webtask.run/auth0-delegated-admin`</td>
    </tr>
  </tbody>
</table>

A new tab opens, displaying the login prompt.

Because (in this example) we disabled signups for the database connection while configuring it, the login screen does not display a **Sign Up** option.
Once you provide valid credentials, Auth0 directs you to your custom **Delegated Administration Dashboard** page, which has the **Title** you provided at the top of the page and (if you provided a custom CSS file), your design.

<Card title="Delegated Administration session timeout">
  By default, token expiration time is 10 hours. However, for security reasons, when using Delegated Administration, Auth0 doesn't save a token to cookies or `sessionStorage`. You must start a new session on each page reload.
</Card>

## Learn more

* [Delegated Administration: Extension Hooks](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks)
* [Delegated Administration: Manage Users](/docs/customize/extensions/delegated-administration-extension/delegated-administration-manage-users)


# Create Delegated Admin Applications
Source: https://auth0.com/docs/customize/extensions/delegated-administration-extension/create-delegated-admin-applications

Learn how to create an application to use with the Delegated Admin Extension, allowing you to selectively expose the users section of the dashboard.

Use the [Delegated Admin Extension](/docs/customize/extensions/delegated-administration-extension) to expose the **Users** section of the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> to a select group of users without allowing them access to the rest of the Dashboard. Before you add the Delegated Admin extension, you need to create the Delegated Admin application in Auth0.

* Go to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), and select **Create Application**.
* Enter a descriptive name for your Application (for example, **Users Dashboard**), select an application type of **Single-Page Web Application**, and click **Create**.
* In the **Settings** view, set the **Allowed Callback URLs** and **Allowed Logout URLs** based on your location, and click **Save Changes**.

**Callback URLs by Region:**

<Callout icon="file-lines">
  Replace `{yourTenant}` with your tenant name. For example, if your tenant name is `tenant_name_example`, then for a tenant running on a US-3 environment, the corresponding callback URL is: `https://tenant_name_example.us.webtask.run/auth0-delegated-admin/login`
</Callout>

<table>
  <thead>
    <tr>
      <th>Location</th>
      <th>Region</th>
      <th>Login Link</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Australia</td>
      <td>AU</td>
      <td>`https://{yourTenant}.au.webtask.io/auth0-delegated-admin/login`</td>
    </tr>

    <tr>
      <td>Europe</td>
      <td>EU</td>
      <td>`https://{yourTenant}.eu.webtask.io/auth0-delegated-admin/login`</td>
    </tr>

    <tr>
      <td>Europe</td>
      <td>EU-2</td>
      <td>`https://{yourTenant}.eu.webtask.run/auth0-delegated-admin/login`</td>
    </tr>

    <tr>
      <td>Japan</td>
      <td>JP-1</td>
      <td>`https://{yourTenant}.jp.webtask.run/auth0-delegated-admin/login`</td>
    </tr>

    <tr>
      <td>UK</td>
      <td>UK</td>
      <td>`https://{yourTenant}.uk.webtask.run/auth0-delegated-admin/login`</td>
    </tr>

    <tr>
      <td>USA</td>
      <td>US-1</td>
      <td>`https://{yourTenant}.us.webtask.io/auth0-delegated-admin/login`</td>
    </tr>

    <tr>
      <td>USA</td>
      <td>US-3</td>
      <td>`https://{yourTenant}.us.webtask.run/auth0-delegated-admin/login`</td>
    </tr>
  </tbody>
</table>

Next, [install the Delegated Admin Extension](/docs/customize/extensions/delegated-administration-extension/install-delegated-admin-extension).

## Learn more

* [Troubleshoot Extensions](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-extensions)


# Delegated Administration: Extension Hooks
Source: https://auth0.com/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks

Learn how to customize the behavior of the Delegated Administration Extension using Extension Hooks.

If you're a user assigned the **Delegated Admin - Administrator** role, you can manage the different Extension Hooks and queries that allow you to customize the behavior of the Delegated Administration extension.

To access the configuration area:

1. Log in to the Delegated Administration Dashboard.
2. Click on your name in the top-right corner. You'll see a dropdown menu; click on the **Configure** option.

The **Configuration** page to which you're redirected is where you can manage your Hooks and queries.

## Extension Hooks Context

The context (**ctx**) object will expose a few helpers and information about the current request. The following methods and properties are available in every Extension Hook:

* Logging
* Caching
* Custom Data
* Payload and Request
* Remote Calls

### Logging

To add a message to the Actions Real-time logs (which you can view using Actions Real-time Logs), call the **log** method:

```javascript lines theme={null}
function(ctx, callback) {
  ctx.log('Logging action:', ctx.payload.action);
  return callback();
}
```

### Caching

To cache something (such as a long list of departments), you can store it on the context's **global** object. This object will be available until the Actions Real-Time Logs container recycles.

```javascript lines theme={null}
function(ctx, callback) {
  ctx.global.departments = [ 'IT', 'HR', 'Finance' ];
  return callback();
}
```

### Custom data

You can store custom data within the extension. This field is limited to 400kb of data.

```javascript lines theme={null}
var data = {
departments: [ 'IT', 'HR', 'Finance' ]
};

ctx.write(data)
.then(function() {
    // ...
})
.catch(function(err) {
    // ...
});
```

To read the data:

```js lines theme={null}
ctx.read()
.then(function(data) {
    // ...
})
.catch(function(err) {
    // ...
});
```

### Payload and request

Each Extension Hook exposes the current payload or request with specific information. The request will always contain information about the user that is logged into the Users Dashboard:

```javascript lines theme={null}
function(ctx, callback) {
  ctx.log('Current User:', ctx.request.user);
  return callback();
}
```

### Remote calls

If you want to call an external service (such as an API) to validate data or to load memberships, you can do this using the `request` module.

```javascript lines theme={null}
function(ctx, callback) {
var request = require('request');
    request('http://api.mycompany.com/departments', function (error, response, body) {
        if (error) {
        return callback(error);
        }

        // ...
    });
}
```

### Hook contract

* `ctx`: The context object

  * `payload`: The payload object

    * `action`: The current action (for example, `delete:user`) that is being executed
    * `user`: The user on which the action is being executed
* `callback(error)`: The callback to which you can return an error if access is denied

### Sample use

Kelly manages the Finance department, and she should only be able to access users within her department.

```javascript lines theme={null}
function(ctx, callback) {
  if (ctx.payload.action === 'delete:user') {
    return callback(new Error('You are not allowed to delete users.'));
  }

  // Get the department from the current user's metadata.
  var department = ctx.request.user.app_metadata && ctx.request.user.app_metadata.department;
  if (!department || !department.length) {
    return callback(new Error('The current user is not part of any department.'));
  }

  // The IT department can access all users.
  if (department === 'IT') {
    return callback();
  }

  ctx.log('Verifying access:', ctx.payload.user.app_metadata.department, department);

  if (!ctx.payload.user.app_metadata.department || ctx.payload.user.app_metadata.department !== department) {
    return callback(new Error('You can only access users within your own department.'));
  }

  return callback();
}
```

If this hook is not configured, all users will be accessible.

Supported action names:

* `read:user`
* `delete:user`
* `reset:password`
* `change:password`
* `change:username`
* `change:email`
* `read:devices`
* `read:logs`
* `remove:multifactor-provider`
* `block:user`
* `unblock:user`
* `send:verification-email`

## Available Extension Hooks

The following Extension Hooks are available for use with the Delegated Administration Application:

* [Access Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-access-hook)
* [Filter Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-filter-hook)
* [Memberships Query Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-memberships-query-hook)
* [Settings Query Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-settings-query-hook)
* [Write Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-write-hook)

## Learn more

* [Delegated Administration: Access Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-access-hook)
* [Delegated Administration: Filter Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-filter-hook)
* [Delegated Administration: Memberships Query Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-memberships-query-hook)
* [Delegated Administration: Settings Query Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-settings-query-hook)
* [Delegated Administration: Write Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-write-hook)


# Delegated Administration: Access Hook
Source: https://auth0.com/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-access-hook

Learn how to use the Access Hook with the Delegated Administration Extension.

Because the Filter Hook only applies filtering logic, you'll need a second layer of logic to determine if the current user (or the person acting as the administrator) is allowed to access a specific user.

To learn more about the Filter Hook, read [Delegated Administration: Filter Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-filter-hook).

The **Access Hook** allows you to determine if the current user is allowed to read, delete, block, unblock, or update a specific user.

## Hook contract

* **ctx**: Context object.

  * **payload**: Payload object.

    * **action**: Current action (e.g., **delete:user**) that is being executed.
    * **user**: User on which the action is being executed.
* **callback(error)**: Callback to which you can return an error if access is denied.

## Sample use

Kelly manages the Finance department, and she should only be able to access users within her department.

```javascript lines theme={null}
function(ctx, callback) {
  if (ctx.payload.action === 'delete:user') {
    return callback(new Error('You are not allowed to delete users.'));
  }

  // Get the department from the current user's metadata.
  var department = ctx.request.user.app_metadata && ctx.request.user.app_metadata.department;
  if (!department || !department.length) {
    return callback(new Error('The current user is not part of any department.'));
  }

  // The IT department can access all users.
  if (department === 'IT') {
    return callback();
  }

  ctx.log('Verifying access:', ctx.payload.user.app_metadata.department, department);

  if (!ctx.payload.user.app_metadata.department || ctx.payload.user.app_metadata.department !== department) {
    return callback(new Error('You can only access users within your own department.'));
  }

  return callback();
}
```

## Notes

If this hook is not configured, all users will be accessible to the current user.

The Hook supports the following action names (which you set using as the value for **ctx.payload.action**):

* read:user
* delete:user
* reset:password
* change:password
* change:username
* change:email
* read:devices
* read:logs
* remove:multifactor-provider
* block:user
* unblock:user
* send:verification-email

## Learn more

* [Delegated Administration: Filter Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-filter-hook)
* [Delegated Administration: Memberships Query Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-memberships-query-hook)
* [Delegated Administration: Settings Query Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-settings-query-hook)
* [Delegated Administration: Write Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-write-hook)


# Delegated Administration: Filter Hook
Source: https://auth0.com/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-filter-hook

Learn how to use the Filter Hook with the Delegated Administration Extension.

By default, users with the **Delegated Admin - User** role see all users associated with the Auth0 account. However, you can filter the data users see using the **Filter Hook**.

## Hook contract

* **ctx**: Context object.
* **callback(error, query)**: Callback to which you can return an error or the lucene query used when filtering the users. The extension will send this query to the [**Get Users** endpoint](https://auth0.com/docs/api/management/v2#!/Users/get_users) of the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

To learn more about the lucene query, review [User Search Query Syntax](/docs/manage-users/user-search/user-search-query-syntax).

### Sample use

If Kelly manages the Finance department, she should only see the users that are also part of the Finance department. We'll filter the users with respect to the department of the current user (which, in this case, is the Finance department and Kelly, respectively).

```javascript lines theme={null}
function(ctx, callback) {
  // Get the department from the current user's metadata.
  var department = ctx.request.user.app_metadata && ctx.request.user.app_metadata.department;
  if (!department || !department.length) {
    return callback(new Error('The current user is not part of any department.'));
  }

  // The IT department can see all users.
  if (department === 'IT') {
    return callback();
  }

  // Return the lucene query.
  return callback(null, 'app_metadata.department:"' + department + '"');
}
```

### Search engine override

You can override the default search engine by specifying your choice in the response.

```javascript lines theme={null}
// Return the lucene query.
return callback(null, { query: 'app_metadata.department:"' + department + '"', searchEngine: 'v2' });
```

## Notes

Do not use single quotes, double quotes, or any other special characters (such as **+** or **-**) in terms on which you'll want to filter. This may cause issues with the Lucene query.

If you use multiple operators like OR, NOT, or AND, use wrap those search parameters in parentheses \[`()`] to delineate which operator is in effect where.

If you do not configure this Hook, the search returns **all users**.

## Learn more

* [Delegated Administration: Access Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-access-hook)
* [Delegated Administration: Memberships Query Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-memberships-query-hook)
* [Delegated Administration: Settings Query Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-settings-query-hook)
* [Delegated Administration: Write Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-write-hook)


# Delegated Administration: Memberships Query Hook
Source: https://auth0.com/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-memberships-query-hook

Learn how to use the Memberships Query Hook with the Delegated Administration Extension.

When creating a new user, the User Interface shows a dropdown where you can choose the membership(s) you want assigned to a user. These memberships are then defined using the **Memberships Query Hook**.

## Hook contract

* **ctx**: Context object.
* **callback(error, \{ createMemberships: true/false, memberships: })**: Callback to which you can return an error and an object containing the membership configuration.

## Sample use

Users of the IT department should be able to create users in other departments. Users from other departments should only be able to create users for their departments.

```javascript lines theme={null}
function(ctx, callback) {
  var currentDepartment = ctx.payload.user.app_metadata && ctx.payload.user.app_metadata.department;
  if (!currentDepartment || !currentDepartment.length) {
    return callback(null, [ ]);
  }

  if (currentDepartment === 'IT') {
    return callback(null, [ 'IT', 'HR', 'Finance', 'Marketing' ]);
  }

  return callback(null, [ ctx.payload.user.app_metadata.department ]);
}
```

## Notes

Because you can only use this query in the UI, you'll need to assign memberships using the **Write Hook** if you need to enforce rules regarding the assignment of users to specific departments.

If there is only one membership group possible, the Memberships field will not show in the UI.

You can allow the end user to enter any value into the **memberships** field by setting **createMemberships** to true:

```javascript lines theme={null}
function(ctx, callback) {
  var currentDepartment = ctx.payload.user.app_metadata.department;
  if (!currentDepartment || !currentDepartment.length) {
    return callback(null, [ ]);
  }

  return callback(null, {
    createMemberships: ctx.payload.user.app_metadata.department === 'IT' ? true : false,
    memberships: [ ctx.payload.user.app_metadata.department ]
  });
}
```

## Learn more

* [Delegated Administration: Access Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-access-hook)
* [Delegated Administration: Filter Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-filter-hook)
* [Delegated Administration: Settings Query Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-settings-query-hook)
* [Delegated Administration: Write Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-write-hook)


# Delegated Administration: Settings Query Hook
Source: https://auth0.com/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-settings-query-hook

Learn how to use the Settings Query Hook with the Delegated Administration Extension.

The **Settings Query Hook** allows you to customize the look and feel of the Delegated Administration extension.

## Hook contract

* **ctx**: Context object.

  * **request.user**: User currently logged in.
  * **locale**: Locale (as inferred from the URL) -- `https://{yourTenant}.us.webtask.io/auth0-delegated-admin/en/users` will set **locale** to `en`.
* **callback(error, settings)**: Callback to which you can return an error and a settings object.

## Sample use

```javascript lines theme={null}
function(ctx, callback) {
  var department = ctx.request.user.app_metadata && ctx.request.user.app_metadata.department;

  return callback(null, {
    // Only these connections should be visible in the connections picker. If only one connection is available, the connections picker will not be shown in the UI.
    connections: [ 'Username-Password-Authentication', 'My-Custom-DB' ],
    // The dictionary allows you to overwrite the title of the dashboard and the "Memberships" label in the Create User dialog.
    dict: {
      title: department ? department + ' User Management' : 'User Management Dashboard',
      memberships: 'Departments',
      menuName: ctx.request.user.name
    },
    // The CSS option allows you to inject a custom CSS file depending on the context of the current user (eg: a different CSS for every customer)
    css: (department && department !== 'IT') && 'https://cdn.jsdelivr.net/gh/auth0-extensions/auth0-delegated-administration-extension/docs/theme/fabrikam.css',
    // This option allows you to restrict creating new users
    canCreateUser: (department === 'IT')
  });
}
```

### Properties

* **connections**: List of the connections this admin is allowed to create and edit users within.
* **dict**: Dictionary that allows you to overwrite the title of the dashboard and the **Memberships** label in the Create User dialog.

  * **dict.title**: Title to display at the top of the UI.
  * **dict.memberships**: Label to set for memberships fields.
  * **dict.menuName**: Name to set for the upper right-hand dropdown menu.
  * **dict.logoutUrl**: Alternate URL for the logout menu option.
* **userFields**: Array of user fields (see "Custom fields" below).
* **css**: String URL to import CSS.
* **altcss**: String URL to import a second set of CSS. You can use this to specify things like accessibility CSS for larger fonts. The user will be presented with a menu item allowing them to toggle this set of CSS on/off.
* **languageDictionary**: String URL or Dictionary Object (see "Localization"below).
* **suppressRawData**: Set to **true** to skip pages that show raw JSON
* **errorTranslator**: Function that translates error messages based on localization. Example: `(function (error, languageDictionary) { return languageDictionary.customErrors[error] || error; }).toString()`
* **canCreateUser**: Boolean flag. If set to `false`, removes `Create User` button and forbids creating new users, `true` by default.

## Custom fields

Beginning with version 3.0 of the Delegated Admin Extension, you can define custom fields and specify their values. Custom fields can be stored in the **user metadata** and **app metadata** fields accessible during the user creation or update processes.

You may also customize existing fields defined by Auth0, such as email, username, name, and connection.

To use custom fields, you must:

* Add your list of **userFields** to the Settings Query Hook
* Implement a Write Hook. Custom fields require the use of the Write Hook to properly update `user_metadata` and `app_metadata`. You must update the user object passed to the callback function with the `user_metadata` and `app_metadata` from the context (`ctx` object) provided to the Hook.

To learn more about Write Hooks, read [Delegated Administration: Write Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-write-hook).

Sample schema for **userFields**:

```js lines expandable theme={null}
userFields: [
    {
        "property": string, // required
        "label": string,
        "sortProperty": string,
        "display": true || function.toString(),
        "search": false || {
            "display": true || function.toString()
            "listOrder": 1,
            "listSize": string(###%), // e.g. 15%
            "filter": boolean,
            "sort": boolean
        },
        "edit": false || {
            "display": true || function.toString()
            "type": "text || select || password || hidden",
            "component": "InputText || Input Combo || InputMultiCombo || InputSelectCombo",
            "options": Array(string) || Array ({ "value": string, "label": string }),
            "disabled": true || false,
            "validationFunction": function.toString()
        },
        "create": false || {
            "display": true || function.toString()
            "type": "text || select || password || hidden",
            "component": "InputText || Input Combo || InputMultiCombo || InputSelectCombo",
            "options": Array(string) || Array ({ "value": string, "label": string }),
            "disabled": true || false,
            "validationFunction": function.toString()
        }
    },
    ...
]
```

* **property** (**required**): Property name of the **ctx.payload** object for the Write Hook. In the Write Hook, `"property": "app_metadata.dbId"` sets `ctx.payload.app_metadata.dbId`.
* **label**: Label that will be used when adding a label to the field on the user info page, create page, edit profile page, or search page.
* **sortProperty**: If sorting by a different field than this for the search table, use this field. Dot notation is allowed.
* **display**: true || false || stringified => This is the default display value. If not overridden in search, edit, or create, it will use this value.

  * if `true`, will just return `user.<property>`.
  * Default: if `false` this value will not be displayed on any page (unless overridden in search, edit, or create).
  * if stringified function: Executes function to get the value to display. Example: `(function display(user, value, languageDictionary) { return moment(value).fromNow(); }).toString()`
* **search**: false || object => Describes how this field will behave on the search page.

  * Default: if `false`, will not show up in the search table.
  * **search.display**: Overrides the default display value.
  * **search.listOrder**: Specifies the column order for the search display table.
  * **search.listSize**: Specifies the default width of the column.
  * **search.filter**: Specifies whether to allow this field to be searched in the search dropdown. Default is false.
  * **search.sort**: Specifies whether this column is sortable. Use sortProperty if you want to sort by a field other than property. Default is false.
* **edit**: false || object => Describes whether the field shows up on the edit dialogs. If not a default field and set to an object, this will show up in the `Change Profile` page on the User Actions dropdown on the user page.

  * Default: if `false`, will not show up on any edit/update page.
  * **edit.display**: Overrides the default display value.
  * **edit.required**: Set to true to fail if it does not have a value. Default is false.
  * **edit.type** **required**: text || select || password
  * **edit.component**: InputText || Input Combo || InputMultiCombo || InputSelectCombo

    * **InputText** (default): Simple text box.
    * **InputCombo**: Searchable dropdown, single value only.
    * **InputMultiCombo**: Searchable dropdown with multiple values allowed.
    * **InputSelectCombo**: Select dropdown of options.
  * **edit.options**: If component is one of InputCombo, InputMultiCombo, InputSelectCombo, the option values need to be specified.

    * **Array(string)**: Array of values (the label and value fields will be set to the same value).
    * **Array(\{ "value": string, "label": string })**: Allows you to set separate values for the value and label. This will result in the value in the Write Hook having the same value, but it can be trimmed down to just the value in the Write Hook.
    * Server-side validation will ensure that any value specified for this field appears in the options array.
  * **edit.disabled**: `true` if the component should be read only; default is false.
  * **edit.validateFunction**: Stringified function for validation. Note that this validation function will run on both the server- and client-side. Example: `(function validate(value, values, context, languageDictionary) { if (value...) return 'something went wrong'; return false; }).toString()`.
* **create**: false || object => Describes whether the field shows up on the create dialog.

  * Default: if `false`, will not show up on the create page.
  * **create.placeholder**: Provide placeholder text to show when input is empty.
  * **create.required**: Set to true to fail if it does not have a value. Default is false.
  * **create.type** **required**: text || select || password
  * **create.component**: InputText || Input Combo || InputMultiCombo || InputSelectCombo

    * **InputText** (default): Text box. Default for type text and password.
    * **InputCombo**: Searchable dropdown, single value only.
    * **InputMultiCombo**: Searchable dropdown with multiple values allowed.
    * **InputSelectCombo**: Select dropdown of options.
  * **create.options**: If component is one of InputCombo, InputMultiCombo, InputSelectCombo, the option values need to be specified.

    * **Array(string)**: Simple array of values, label, and value will be set to the same.
    * **Array(\{ "value": string, "label": string })**: Allows you to set separate values for both the value and label. This will result in the value in the Write Hook having the same value, but it can be trimmed down to just the value in the Write Hook.
    * Server-side validation will ensure that any value specified for this field is in the options array.
  * **create.disabled**: true if component should be read only, default is false.
  * **create.validateFunction**: Stringified function for checking the validation.

    * Example: `(function validate(value, values, context, languageDictionary) { if (value...) return 'something went wrong'; return false; }).toString()`
    * This validation function will run on both the server- and client-side.

## Predefined fields

There are a set of pre-defined, searchable fields for default behavior.

You can override the default behavior by adding the field as a userField and then overriding the behavior you would like to change. This would often be done to suppress a field by setting the display to false.

### Search fields

* **name**: Constructed field from other fields: default display function: `(function(user, value) { return (value || user.nickname || user.email || user.user_id); }).toString()`
* **email**: Email address or N/A
* **last\_login\_relative**: Last login time
* **logins\_count**: Number of logins
* **connection**: Database connection

### User info fields

* **user\_id**: User ID
* **name**: User's name
* **username**: User's username
* **email**: User's email
* **identity.connection**: Connection value
* **isBlocked**: Whether or not the user is blocked
* **blocked\_for**: Whether or not the user has <Tooltip href="/docs/glossary?term=attack+protection">attack protection</Tooltip> blocks
* **last\_ip**: Last IP the user used to log in
* **logins\_count**: Number of times the user has logged in
* **currentMemberships**: List of memberships for this user
* **created\_at**: Date/time at which the user was created
* **updated\_at**: Date/time at which the user was updated
* **last\_login**: Date/time at which the user last logged in

### Create and edit user fields

* **connection**: User's database
* **password**: New password
* **repeatPassword**: Repeat of the user's password
* **email**: User's email
* **username**: User's username

### Sample use

```javascript lines expandable theme={null}
function(ctx, callback) {
  var department = ctx.request.user.app_metadata && ctx.request.user.app_metadata.department;

  return callback(null, {
    // Only these connections should be visible in the connections picker.
    // If only one connection is available, the connections picker will not be shown in the UI.
    connections: [ 'Username-Password-Authentication', 'My-Custom-DB' ],
    // The dictionary allows you to overwrite the title of the dashboard and the "Memberships" label in the Create User dialog.
    dict: {
      title: department ? department + ' User Management' : 'User Management Dashboard',
      memberships: 'Departments'
    },
    // User Fields are the custom fields that can be displayed in create and edit, and can also be used for searching, and can be used to customize the view user page
    userFields: [
        {
            "label": "Conexión",
            "property": "connection",
        },
        {
            "label": "Correo Electrónico",
            "property": "email",
        },
        ...
    ],
    // The CSS option allows you to inject a custom CSS file depending on the context of the current user (eg: a different CSS for every customer)
    css: (department && department !== 'IT') && 'https://cdn.jsdelivr.net/gh/auth0-extensions/auth0-delegated-administration-extension/docs/theme/fabrikam.css',
    languageDictionary: 'https://your-cdn.com/locale/es.json'
  });
}
```

## Localization

Beginning with version 3.0 of the Delegated Admin Extension, you can provide a language dictionary for use with localization. The language dictionary is used only for static page content; for field level content, you must use **userFields** labels.

<Callout icon="file-lines">
  Localization is aimed at those working with non-administrative functions when managing users. Auth0 currently does not support localization on any of the Configuration pages.
</Callout>

To specify the locale, you can use the path. For example: `https://{yourTenant}.us.webtask.io/auth0-delegated-admin/en/users` will set `context.locale` to `en` in the settings query.

The **languageDictionary** is set as part of the settings query, which allows you to:

* Explicitly define a **languageDictionary**
* Provide a URL to fetch the contents for the **languageDictionary** parameter

For more information, you can review the [Delegated Administration Extension Language Dictionary file](https://github.com/auth0-extensions/auth0-delegated-administration-extension/blob/master/tests/utils/en.json).

### Example: Provide link to language dictionary file

```javascript lines expandable theme={null}
function(ctx, callback) {
  var department = ctx.request.user.app_metadata && ctx.request.user.app_metadata.department;

  return callback(null, {
    // Only these connections should be visible in the connections picker.
    // If only one connection is available, the connections picker will not be shown in the UI.
    connections: [ 'Username-Password-Authentication', 'My-Custom-DB' ],
    // The dictionary allows you to overwrite the title of the dashboard and the "Memberships" label in the Create User dialog.
    dict: {
      title: department ? department + ' User Management' : 'User Management Dashboard',
      memberships: 'Departments'
    },
    // User Fields are the custom fields that can be displayed in create and edit, and can also be used for searching, and can be used to customize the view user page
    userFields: [
        {
            "label": "Conexión",
            "property": "connection",
        },
        {
            "label": "Correo Electrónico",
            "property": "email",
        },
        ...
    ],
    // The CSS option allows you to inject a custom CSS file depending on the context of the current user (eg: a different CSS for every customer)
    css: (department && department !== 'IT') && 'https://cdn.jsdelivr.net/gh/auth0-extensions/auth0-delegated-administration-extension/docs/theme/fabrikam.css',
    languageDictionary: 'https://your-cdn.com/locale/es.json'
  });
}
```

### Example: Provide language dictionary object

```javascript lines expandable theme={null}
function(ctx, callback) {
  var department = ctx.request.user.app_metadata && ctx.request.user.app_metadata.department;

  return callback(null, {
    // Only these connections should be visible in the connections picker.
    // If only one connection is available, the connections picker will not be shown in the UI.
    connections: [ 'Username-Password-Authentication', 'My-Custom-DB' ],
    // The dictionary allows you to overwrite the title of the dashboard and the "Memberships" label in the Create User dialog.
    dict: {
      title: department ? department + ' User Management' : 'User Management Dashboard',
      memberships: 'Departments'
    },
    // User Fields are the custom fields that can be displayed in create and edit, and can also be used for searching, and can be used to customize the view user page
    userFields: [
        {
            "label": "Conexión",
            "property": "connection",
        },
        {
            "label": "Correo Electrónico",
            "property": "email",
        },
        ...
    ],
    // The CSS option allows you to inject a custom CSS file depending on the context of the current user (eg: a different CSS for every customer)
    css: (department && department !== 'IT') && 'https://cdn.jsdelivr.net/gh/auth0-extensions/auth0-delegated-administration-extension/docs/theme/fabrikam.css',
    languageDictionary: {
        loginsCountLabel: 'Cantidad de Logins:',
        searchBarPlaceholder: 'Busqueda de usuarios usando la sintaxis de Lucene',
        deviceNameColumnHeader: 'Dispositivo',
        ...
    }
  });
}
```

## Learn more

* [Delegated Administration: Access Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-access-hook)
* [Delegated Administration: Filter Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-filter-hook)
* [Delegated Administration: Write Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-write-hook)
* [Delegated Administration: Memberships Query Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-memberships-query-hook)


# Delegated Administration: Write Hook
Source: https://auth0.com/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-write-hook

Learn how to use the Write Hook with the Delegated Administration Extension.

The Write Hook, which runs anytime you create or update a user, allows you to do things like:

* Changing the user's password
* Changing the user's email address
* Updating the user's profile

You can also use the Write Hook to automatically set default values for newly-created users. For example, you might want to automatically assign a user to the same group, department, or vendor as the ones to which you've been assigned.

<Warning>
  Auth0 only supports user creation with Database Connections.
</Warning>

## Hook contract

* **ctx**: Context object.

  * **request.originalUser**: Current user's values where the **payload** is the new set of fields. Only available when the method is **update**.
  * **payload**: Payload object

    * **memberships**: Array of memberships that were selected in the UI when creating the user.
    * **email**: Email address of the user.
    * **password**: Password of the user.
    * **connection**: Name of the database connection.
    * **app\_metadata**: Data that's included if a Custom Field being modified is saved in `app_metadata`.
    * **user\_metadata**: Data that's included if a Custom Field being modified is saved in `user_metadata`.
  * **userFields**: User fields array (if specified in the settings query)
  * **method**: Either **create** or **update** depending on whether this is being called as a result of a create or an update call.
* **callback(error, user)**: Callback to which you can return an error and the user object that should be sent to the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

For more information about **userFields**, read [Delegated Administration: Settings Query Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-settings-query-hook).

## Sample use

Kelly manages the Finance department. When she creates users, these users should be assigned as members of the Finance department.

```javascript lines expandable theme={null}
function(ctx, callback) {
  var newProfile = {
    email: ctx.payload.email,
    password: ctx.payload.password,
    connection: ctx.payload.connection,
    user_metadata: ctx.payload.user_metadata,
    app_metadata: {
      department: ctx.payload.memberships && ctx.payload.memberships[0],
      ...ctx.payload.app_metadata
    }
  };

  if (!ctx.payload.memberships || ctx.payload.memberships.length === 0) {
    return callback(new Error('The user must be created within a department.'));
  }

  // Get the department from the current user's metadata.
  var currentDepartment = ctx.request.user.app_metadata && ctx.request.user.app_metadata.department;
  if (!currentDepartment || !currentDepartment.length) {
    return callback(new Error('The current user is not part of any department.'));
  }

  // If you're not in the IT department, you can only create users within your own department.
  // IT can create users in all departments.
  if (currentDepartment !== 'IT' && ctx.payload.memberships[0] !== currentDepartment) {
    return callback(new Error('You can only create users within your own department.'));
  }

  if (ctx.method === 'update') {
    // If updating, only set the fields we need to send
    Object.keys(newProfile).forEach(function(key) {
      if (newProfile[key] === ctx.request.originalUser[key]) delete newProfile[key];
    });
  }

  // This is the payload that will be sent to API v2. You have full control over how the user is created in API v2.
  return callback(null, newProfile);
}
```

## Learn more

* [Delegated Administration: Access Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-access-hook)
* [Delegated Administration: Filter Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-filter-hook)
* [Delegated Administration: Memberships Query Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-memberships-query-hook)
* [Delegated Administration: Settings Query Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-settings-query-hook)


# Delegated Administration: Manage Users
Source: https://auth0.com/docs/customize/extensions/delegated-administration-extension/delegated-administration-manage-users

Learn how to manage users in the Delegated Administration Extension.

In the Application exposed by the Delegated Administration extension, there are two views available: **Users** and **Logs**. On the **User**s view, you can see the display and modify users associated with your Auth0 account.

By default, all users are displayed, but you can filter the displayed list by configuring a Filter Hook.

For more information on the Filter Hook, see [Delegation Administration: Filter Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-filter-hook).

## User actions in Delegated Administration dashboard

To limit the number of options someone with access to the Dashboard exposed by the Delegated Administration extension, configure an Access Hook.

Read more about Access Hooks at [Delegated Administration: Access Hook](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks/delegated-administration-access-hook).

The **Change Profile** option is available only if you have configured custom fields.

Notice the new **Reset Password** option available via the extension. This option will send an email to the user allowing them to choose a new password. To do this, select a user, and select **Actions** > **Reset Password**.

This will send an email to the user, containing a link to change the password.

If your profile indicates that you have the `Delegated Admin - Administrator` role, the **Logs** view allows you to see a list of authentications made by your users (this view is only visible to users with the `Delegated Admin - Administrator` role). The contents of this view are a subset of the data displayed in [Auth0 Dashboard > Monitoring > Logs](https://manage.auth0.com/#/logs). The Logs dashboard also displays data on administrative actions taken in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

## Create users

You can create a new user by selecting the **+ Create User** button on the **Users** view. You need to specify email and password. Depending on your role, you may not be able to set the **Departmen**t to which the new user belongs.

For example, users with the `Delegated Admin - Administrator` role can see the **Department** field and select any of its values.

<Frame>
  <img alt="Extensions - Administration Dashboard - Create admin" />
</Frame>

On the other hand, Kelly, who has the `Delegated Admin - User` role and belongs to the Finance department, cannot see the **Department** field. The user she creates will be automatically assigned to the Finance department.

<Frame>
  <img alt="Extensions - Delegated Administration Dashboard - Create user" />
</Frame>

<Card title="Delegated Administration session timeout">
  By default, token expiration time is 10 hours. However, for security reasons, when using Delegated Administration, Auth0 doesn't save a token to cookies or `sessionStorage`. You must start a new session on each page reload.
</Card>

## Learn more

* [Delegated Administration: Extension Hooks](/docs/customize/extensions/delegated-administration-extension/delegated-administration-hooks)


# Install Delegated Admin Extension
Source: https://auth0.com/docs/customize/extensions/delegated-administration-extension/install-delegated-admin-extension

Describes how to install the Delegated Administration Extension, which allows you to expose the Users section of the Auth0 Dashboard to a select group of users without allowing them access to the rest of the Dashboard.

You can install the [Delegated Admin Extension](/docs/customize/extensions/delegated-administration-extension), which allows you to expose the **Users** section of the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> to a select group of users without allowing them access to the rest of the Dashboard.

## Prerequisite

[Create a Delegated Admin Dashboard application](/docs/customize/extensions/delegated-administration-extension/create-delegated-admin-applications) in Auth0.

## Install extension

1. Go to [Auth0 Dashboard > Extensions](https://manage.auth0.com/#/extensions), and filter for **Delegated Admin**.
2. Select **Delegated Administration Dashboard** in the list of provided extensions. The **Install Extension** window will open.

   <Frame>
     <img alt="Dashboard - Extensions - Delegated Admin - Install" />
   </Frame>
3. Set the following configuration variables, and select **Install**:

   <table>
     <thead>
       <tr>
         <th>Variable</th>
         <th>Description</th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td><strong>EXTENSION\_CLIENT\_ID</strong></td>
         <td><strong>Client ID</strong> of the application with which you plan to use this extension.</td>
       </tr>

       <tr>
         <td><strong>TITLE</strong></td>
         <td>Custom title that will appear at the top of the Delegated Administration Dashboard page.</td>
       </tr>

       <tr>
         <td><strong>CUSTOM\_CSS</strong></td>
         <td>(<em>Optional</em>) Link to a custom CSS you can use to style the look of your Delegated Administration Dashboard page.</td>
       </tr>

       <tr>
         <td><strong>FAVICON\_PATH</strong></td>
         <td>(<em>Optional</em>) Path to custom favicon.</td>
       </tr>

       <tr>
         <td><strong>AUTH0\_CUSTOM\_DOMAIN</strong></td>
         <td>(<em>Optional</em>) If you have a custom domain name configured, enter it here (e.g., <code>login.example.com</code>). This will change the authorization endpoint to `https://login.example.com/login`.</td>
       </tr>

       <tr>
         <td><strong>FEDERATED\_LOGOUT</strong></td>
         <td>(<em>Optional</em>) Indicates whether to sign out from the connection when users log out.</td>
       </tr>
     </tbody>
   </table>

   Setting the `AUTH0_CUSTOM_DOMAIN` variable does not affect the extension URL; it only changes the authorization endpoint. When a custom domain is used, users that are logging into the extension will be navigated to `https://AUTH0_CUSTOM_DOMAIN/login` instead of the default `https://tenant-name.us.auth0.com/login`.
   If you navigate to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), you will see that the extension created an additional application. This application is authorized to access the Management API, so you shouldn't modify it.

## Add callback URLs to Application

1. Navigate to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), and select the name of the application with which you plan to use this extension. This should be the application with the Client ID you entered earlier when setting the configuration variables for the Delegated Administration Dashboard.
2. Locate **Allowed Callback URLs**, and add the appropriate callback URL for your region and your tenant's extensibility runtime.

   <table>
     <thead>
       <tr>
         <th>Location</th>
         <th>Name</th>
         <th>Allowed Callback URL for Node.js 12</th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>USA</td>
         <td>US-1</td>
         <td>`https://{yourTenant}.us12.webtask.io/auth0-delegated-admin/login`</td>
       </tr>

       <tr>
         <td>USA</td>
         <td>US-3</td>
         <td>`https://{yourTenant}.us.webtask.run/auth0-delegated-admin/login`</td>
       </tr>

       <tr>
         <td>Australia</td>
         <td>AU</td>
         <td>`https://{yourTenant}.au12.webtask.io/auth0-delegated-admin/login`</td>
       </tr>

       <tr>
         <td>Europe</td>
         <td>EU</td>
         <td>`https://{yourTenant}.eu12.webtask.io/auth0-delegated-admin/login`</td>
       </tr>

       <tr>
         <td>Japan</td>
         <td>JP-1</td>
         <td>`https://{yourTenant}.jp.webtask.run/auth0-delegated-admin/login`</td>
       </tr>
     </tbody>
   </table>

   <table>
     <thead>
       <tr>
         <th>Location</th>
         <th>Name</th>
         <th>Allowed Callback URL for Node.js 8</th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>USA</td>
         <td>US-1</td>
         <td>`https://YOUR_TENANT.us8.webtask.io/auth0-delegated-admin/login`</td>
       </tr>

       <tr>
         <td>Europe</td>
         <td>EU</td>
         <td>`https://YOUR_TENANT.eu8.webtask.io/auth0-delegated-admin/login`</td>
       </tr>

       <tr>
         <td>Australia</td>
         <td>AU</td>
         <td>`https://YOUR_TENANT.au8.webtask.io/auth0-delegated-admin/login`</td>
       </tr>
     </tbody>
   </table>
3. Select **Save Changes**.

## Use extension

1. Go to [Auth0 Dashboard > Extensions](https://manage.auth0.com/#/extensions), and select the **Installed Extensions** view.
2. Select **Delegated Administration Dashboard**. A new tab will open to display the login prompt.

   Because we disabled signups for the database connection while configuring it, the login screen will not display a Sign Up option.

   Once you provide valid credentials, you will be directed to your custom **Delegated Administration Dashboard** page, which will have the **Title** you provided at the top of the page, and if you provided a custom CSS file, that styling will be applied.

## Learn more

* [Create Delegated Admin Applications](/docs/customize/extensions/delegated-administration-extension/create-delegated-admin-applications)


# Single Sign-On Dashboard Extension
Source: https://auth0.com/docs/customize/extensions/single-sign-on-dashboard-extension

Learn how to use the SSO Dashboard Extension to manage single sign-on login for your users on multiple enterprise applications.

The <Tooltip href="/docs/glossary?term=Single+Sign-on">Single Sign-on</Tooltip> (SSO) Dashboard is a web application designed to solve a problem familiar to many people. Organizations of all sizes maintain a variety of different applications to handle various business functions like accounting, HR, development, support, etc. Remembering usernames and passwords and login URLs for all of your applications can be cumbersome. With this extension, you can simplify the authentication experience by enabling SSO login for your users on multiple enterprise applications. It allows you to create a list of all the cloud services for which a user can authenticate with SSO logins.

<Callout icon="file-lines">
  A user should not be able to access, from the dashboard or otherwise, the service provider without having appropriate permissions (groups/roles) to do so. Ideally, these users would not see any service provider they are not granted access to on the dashboard.
</Callout>

The SSO Dashboard supports two types of users:

* **Users** who can log in to the dashboard to select an application to sign into with SSO.
* **Admins** who can configure applications visible to the users.

To configure this extension, do the following:

1. [Create an SSO Dashboard Application](/docs/customize/extensions/single-sign-on-dashboard-extension/create-sso-dashboard-application)
2. [Install the SSO Dashboard extension](/docs/customize/extensions/single-sign-on-dashboard-extension/install-sso-dashboard-extension)
3. [Add Applications to the SSO Dashboard](/docs/customize/extensions/single-sign-on-dashboard-extension/add-applications-to-the-sso-dashboard)
4. [Update Applications on the SSO Dashboard](/docs/customize/extensions/single-sign-on-dashboard-extension/update-applications-on-the-sso-dashboard)

You can also [view this SSO Dashboard Extension on GitHub](https://github.com/auth0-extensions/auth0-sso-dashboard-extension).

## Learn more

* [Troubleshoot Extensions](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-extensions)
* [Sessions](/docs/manage-users/sessions)
* [Single Sign-On](/docs/authenticate/single-sign-on)
* [Enable Single Sign-On for Tenants](/docs/get-started/tenant-settings/enable-sso-for-legacy-tenants)
* [Configure Session Lifetime Settings](/docs/manage-users/sessions/configure-session-lifetime-settings)
* [Logout](/docs/authenticate/login/logout)


# Add Applications to Single Sign-On Dashboard
Source: https://auth0.com/docs/customize/extensions/single-sign-on-dashboard-extension/add-applications-to-the-sso-dashboard

Learn how to add applications to the Auth0 Single Sign-On (SSO) Dashboard Extension to enable SSO login for your applications.

Use the Single Sign-On (<Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip>) Dashboard Extension to manage SSO login for your users on multiple enterprise applications.

## Prerequisites

* [Create the SSO Dashboard application](/docs/customize/extensions/single-sign-on-dashboard-extension/create-sso-dashboard-application).
* [Install the SSO Dashboard Extension](/docs/customize/extensions/single-sign-on-dashboard-extension/install-sso-dashboard-extension).

## Add applications

1. Go to [Auth0 Dashboard > Extensions](https://manage.auth0.com/#/extensions), and select your new SSO Dashboard extension.
   If you are an administrator, you can also log in to the SSO Dashboard using `https://{yourTenant}.<REGION>8.webtask.io/auth0-sso-dashboard/admins/login`.
2. In the upper right corner, select **Settings** from the dropdown below your tenant name.
3. Click **Create App** to add a new application.

   The **New Application** form appears.
4. Complete the following fields for the new application:

   <table>
     <thead>
       <tr>
         <th>Field</th>
         <th>Description</th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td><strong>Type</strong></td>
         <td>A dropdown where you select SAML, OpenID-Connect, or WS-Federation depending on the type of application.</td>
       </tr>

       <tr>
         <td><strong>Application</strong></td>
         <td>A dropdown where you select the application that you wish to add.</td>
       </tr>

       <tr>
         <td><strong>Name</strong></td>
         <td>The name is automatically populated based on the application you selected. You can change the name or use the default.</td>
       </tr>

       <tr>
         <td><strong>Logo</strong></td>
         <td>The url of the logo you wish to user as an icon for the application.</td>
       </tr>

       <tr>
         <td><strong>Callback</strong></td>
         <td>One of the <strong>Allowed Callback URLs</strong> under your <a href="https://manage.auth0.com/#/applications">Application Settings</a> for the application.</td>
       </tr>

       <tr>
         <td><strong>Connection</strong></td>
         <td>(<em>Optional</em>) The connection type. You can add or edit your available connection types in the <a href="https://manage.auth0.com/#/connections/database">Connections section of the Auth0 Management dashboard</a>.  If a connection is not set and the user is not logged, the user will see the Auth0 Login page.</td>
       </tr>

       <tr>
         <td><strong>Custom URL</strong></td>
         <td>(<em>Optional</em>) Checkbox to use a custom URL rather than the Auth0 URL. If you check the box, a field appears where you can enter your custom URL.</td>
       </tr>

       <tr>
         <td><strong>Enabled</strong></td>
         <td>Checkbox for this application to be visible (published) to your users.</td>
       </tr>
     </tbody>
   </table>
5. Select **Create**. Your new application will then appear on the **Applications** page of the SSO dashboard with any other applications that have been created.
6. Click on an application to test the connection.

## Learn more

* [Update Applications in the SSO Dashboard](/docs/customize/extensions/single-sign-on-dashboard-extension/update-applications-on-the-sso-dashboard)
* [Create Single Sign-on (SSO) Dashboard Application](/docs/customize/extensions/single-sign-on-dashboard-extension/create-sso-dashboard-application)
* [Troubleshoot Extensions](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-extensions)
* [Configure Session Lifetime Settings](/docs/manage-users/sessions/configure-session-lifetime-settings)
* [Logout](/docs/authenticate/login/logout)


# Create Single Sign-on (SSO) Dashboard Application
Source: https://auth0.com/docs/customize/extensions/single-sign-on-dashboard-extension/create-sso-dashboard-application

Describes how to create an application to use with the SSO Dashboard Extension to enable SSO login for your applications.

Use the <Tooltip href="/docs/glossary?term=Single+Sign-On">Single Sign-On</Tooltip> (SSO) Dashboard extension to manage SSO login for your users on multiple enterprise applications. To learn more, [view this extension on GitHub](https://github.com/auth0-extensions/auth0-sso-dashboard-extension).

## Create Auth0 application

Before you [add the SSO Dashboard extension](/docs/customize/extensions/single-sign-on-dashboard-extension/install-sso-dashboard-extension), you need to create an application in Auth0:

1. Go to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), and select **+Create Application**.
2. Enter a descriptive name for your Application (for example, SSO Dashboard), select **Single-Page Web Application** for the **Application Type**, and then select **Create**.
3. On the **Settings** tab, set the **Allowed Callback URLs** based on your tenant's region:

   1. For **Admins**: `https://{yourTenant}.YOUR_REGION_DOMAIN/auth0-sso-dashboard/admins/login`
   2. For **Users**: `https://{yourTenant}.YOUR_REGION_DOMAIN/auth0-sso-dashboard/login`

      <table>
        <thead>
          <tr>
            <th><strong>Region</strong></th>
            <th><strong>Region Domain</strong></th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>US-1</td>
            <td>us.webtask.io</td>
          </tr>

          <tr>
            <td>US-3</td>
            <td>us.webtask.run</td>
          </tr>

          <tr>
            <td>US-4</td>
            <td>us.webtask.run</td>
          </tr>

          <tr>
            <td>US-5</td>
            <td>us.webtask.run</td>
          </tr>

          <tr>
            <td>EU</td>
            <td>eu.webtask.io</td>
          </tr>

          <tr>
            <td>EU-2</td>
            <td>eu.webtask.run</td>
          </tr>

          <tr>
            <td>AU</td>
            <td>au.webtask.io</td>
          </tr>

          <tr>
            <td>JP-1</td>
            <td>jp.webtask.run</td>
          </tr>

          <tr>
            <td>UK-1</td>
            <td>uk.webtask.run</td>
          </tr>

          <tr>
            <td>CA-1</td>
            <td>ca.webtask.run</td>
          </tr>
        </tbody>
      </table>
4. Select and copy the **Client ID** value.
5. Navigate to the bottom of the page, and then select **Advanced Settings**.
6. Select the **OAuth** tab, and then paste the **Client ID** value into the **Allowed APPs / APIs** field.
7. Set **JsonWebToken Signature Algorithm** to **RS256**.
8. Select **Save Changes**.

By default, all the connection types are enabled for users to be able to log into the SSO Dashboard. If you would like to change this, navigate to the **Connections** tab for the Application.

## Install SSO Dashboard extension

Next, you will need to [install the SSO Dashboard Extension](/docs/customize/extensions/single-sign-on-dashboard-extension/install-sso-dashboard-extension) and [add applications](/docs/customize/extensions/single-sign-on-dashboard-extension/add-applications-to-the-sso-dashboard) to the dashboard.

## Learn more

* [Install Single Sign-On Dashboard Extension](/docs/customize/extensions/single-sign-on-dashboard-extension/install-sso-dashboard-extension)
* [Add Applications to Single Sign-On Dashboard](/docs/customize/extensions/single-sign-on-dashboard-extension/add-applications-to-the-sso-dashboard)
* [Troubleshoot Extensions](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-extensions)
* [Single Sign-On](/docs/authenticate/single-sign-on)
* [Sessions](/docs/manage-users/sessions)
* [Logout](/docs/authenticate/login/logout)


# Install Single Sign-On Dashboard Extension
Source: https://auth0.com/docs/customize/extensions/single-sign-on-dashboard-extension/install-sso-dashboard-extension

Learn how to install the Auth0 Single Sign-On (SSO) Dashboard Extension to enable SSO login for your applications.

<Card title="Before you start">
  1. [Create an SSO Dashboard application](/docs/customize/extensions/single-sign-on-dashboard-extension/create-sso-dashboard-application) in Auth0.
  2. Copy the **Client ID** value of your SSO Dashboard application.
</Card>

Use the <Tooltip href="/docs/glossary?term=Single+Sign-On">Single Sign-On</Tooltip> (SSO) Dashboard Extension to manage SSO login for your users on multiple enterprise applications. To learn more, [view this extension on GitHub](https://github.com/auth0-extensions/auth0-sso-dashboard-extension).

## Install extension

You can install the SSO Dashboard extension through the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>:

1. Go to [Auth0 Dashboard > Extensions](https://manage.auth0.com/#/extensions), and select **SSO Dashboard** from the list of provided extensions. The **Install Extension** window will open:

   <Frame>
     <img alt="Dashboard - Extensions - SSO Dashboard - Install Extension" />
   </Frame>
2. Set the following configuration variables:

   <table>
     <thead>
       <tr>
         <th><strong>Variable</strong></th>
         <th><strong>Required</strong></th>
         <th><strong>Description</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td><code>EXTENSION\_CLIENT\_ID</code></td>
         <td>Required</td>
         <td><strong>Client ID</strong> of the Auth0 application you created for the extension.</td>
       </tr>

       <tr>
         <td><code>TITLE</code></td>
         <td>Optional</td>
         <td>Custom title that will appear at the top of the SSO Dashboard page.</td>
       </tr>

       <tr>
         <td><code>CUSTOM\_CSS</code></td>
         <td>Optional</td>
         <td>Path to a custom CSS file to style the look of your SSO Dashboard page.</td>
       </tr>

       <tr>
         <td><code>FAVICON\_PATH</code></td>
         <td>Optional</td>
         <td>Path to a custom favicon.</td>
       </tr>

       <tr>
         <td><code>AUTH0\_CUSTOM\_DOMAIN</code></td>
         <td>Optional</td>
         <td><a href="/docs/customize/custom-domains">Custom domain</a> configured with Auth0.</td>
       </tr>
     </tbody>
   </table>

   <Callout icon="file-lines">
     Setting the `AUTH0_CUSTOM_DOMAIN` variable does not affect the extension URL, it only changes the URL of the Authorization Endpoint used by the extension. When a custom domain is used, users that log in to the extension will be redirected to `https://{yourAuth0CustomDomain}/login` instead of the default `https://{yourTenant}.{yourRegion}.auth0.com/login`.
   </Callout>
3. Select **Install**.

If you navigate to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), you'll notice that an application named `auth0-sso-dashboard` was created automatically. This application is used by the extension to authorize access to the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>, and you must not modify it.

## Use extension

1. Go to [Auth0 Dashboard > Extensions](https://manage.auth0.com/#/extensions), and select the **Installed Extensions** view.
2. Select **SSO Dashboard**. When you first select your installed extension, you will be asked to grant it the required permissions. Once you agree, you will be directed to your custom **SSO Dashboard**, which will display the **Title** you provided at the top of the page. If you provided a custom CSS file, that styling will also be applied.
3. To log in to the SSO Dashboard:

   1. For **Admins,** use:
      `https://{yourTenant}.YOUR_REGION_KEY.webtask.io/auth0-sso-dashboard/admins/login`
   2. For **Users,** use:
      `https://{yourTenant}.YOUR_REGION_KEY.webtask.io/auth0-sso-dashboard/login`

      <table>
        <thead>
          <tr>
            <th><strong>Region</strong></th>
            <th><strong>Region Domain</strong></th>
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>US-1</td>
            <td>us.webtask.io</td>
          </tr>

          <tr>
            <td>US-3</td>
            <td>us.webtask.run</td>
          </tr>

          <tr>
            <td>US-4</td>
            <td>us.webtask.run</td>
          </tr>

          <tr>
            <td>US-5</td>
            <td>us.webtask.run</td>
          </tr>

          <tr>
            <td>EU</td>
            <td>eu.webtask.io</td>
          </tr>

          <tr>
            <td>EU-2</td>
            <td>eu.webtask.run</td>
          </tr>

          <tr>
            <td>AU</td>
            <td>au.webtask.io</td>
          </tr>

          <tr>
            <td>JP-1</td>
            <td>jp.webtask.run</td>
          </tr>

          <tr>
            <td>UK-1</td>
            <td>uk.webtask.run</td>
          </tr>

          <tr>
            <td>CA-1</td>
            <td>ca.webtask.run</td>
          </tr>
        </tbody>
      </table>

## Learn more

* [Create Single Sign-on (SSO) Dashboard Application](/docs/customize/extensions/single-sign-on-dashboard-extension/create-sso-dashboard-application)
* [Add Applications to Single Sign-On Dashboard](/docs/customize/extensions/single-sign-on-dashboard-extension/add-applications-to-the-sso-dashboard)
* [Update Applications in the SSO Dashboard](/docs/customize/extensions/single-sign-on-dashboard-extension/update-applications-on-the-sso-dashboard)
* [Troubleshoot Extensions](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-extensions)
* [Configure Session Lifetime Settings](/docs/manage-users/sessions/configure-session-lifetime-settings)
* [Logout](/docs/authenticate/login/logout)


# Update Applications in the SSO Dashboard
Source: https://auth0.com/docs/customize/extensions/single-sign-on-dashboard-extension/update-applications-on-the-sso-dashboard

Describes how to update applications in the SSO Dashboard Extension to enable SSO login for your applications.

Use the SSO Dashboard Extension to manage <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> login for your users on multiple enterprise applications.

To learn more, see [Single Sign-On Dashboard Extension](/docs/customize/extensions/single-sign-on-dashboard-extension) or [view this extension on GitHub](https://github.com/auth0-extensions/auth0-sso-dashboard-extension).

## Prerequisites

* [Create the SSO Dashboard application](/docs/customize/extensions/single-sign-on-dashboard-extension/create-sso-dashboard-application) in Auth0.
* [Install the SSO Dashboard Extension](/docs/customize/extensions/single-sign-on-dashboard-extension/install-sso-dashboard-extension).
* [Add applications to the SSO Dashboard](/docs/customize/extensions/single-sign-on-dashboard-extension/add-applications-to-the-sso-dashboard).

## Update application

1. Go to [Auth0 Dashboard > Extensions](https://manage.auth0.com/#/extensions) and select the **Installed Extensions** view.
2. Select **SSO Dashboard**.
   If you are an administrator, you can also log in to the SSO Dashboard using `https://{yourTenant}.<REGION>8.webtask.io/auth0-sso-dashboard/admins/login`.
3. Select **Settings** from the dropdown below your tenant name.

* To specify whether users can see the application when it is enabled, select **Publish** or **Unpublish**.
* To update an application's settings, select its gear icon.
* To delete an application, select its **X**. A confirmation popup will confirm the deletion.

## Learn more

* [Troubleshoot Extensions](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-extensions)
* [Enable Single Sign-On for Tenants](/docs/get-started/tenant-settings/enable-sso-for-legacy-tenants)
* [Configure Session Lifetime Settings](/docs/manage-users/sessions/configure-session-lifetime-settings)
* [Logout](/docs/authenticate/login/logout)


# User Import / Export Extension
Source: https://auth0.com/docs/customize/extensions/user-import-export-extension

Learn about the User Import/Export extension, which allows you to import and export users from or to any database you have configured in your account.

<Warning>
  The **User Import/Export Extension** will be deprecated in September 2025. You can access the same features now available [directly in the Auth0 Management Dashboard](/docs/manage-users/user-migration/bulk-user-import-export).
</Warning>

The **User Import / Export Extension** allows you to:

* Bulk import your existing database users into Auth0
* Search for and export some (or all) of your Auth0 database users

For a list of user profile fields that can be imported and exported, see [User Profile Attributes](/docs/manage-users/user-accounts/user-profiles/user-profile-structure).

You must be a Dashboard Admin to use this extension.

## Install the extension

To install this extension, go to [Auth0 Dashboard > Extensions](https://manage.auth0.com/#/extensions), and select **User Import / Export**.

The extension does not require any additional configuration before it can be installed, so select **Install** in the informational pop-up window to proceed.

## Use the extension

After you've installed your extension, you'll see it listed in your list of installed extensions. Click on **Import / Export Extension** to launch.

You'll be asked to grant permission for the extension to access your Auth0 account for the listed activities the first time you launch the extension.

<Frame>
  <img alt="Dashboard Extensions Authorize the Users Import/Export Extension" />
</Frame>

Click the **check mark** to proceed.

There are two ways of using this extension:

* Bulk import your existing database users into Auth0
* Search for and export some (or all) of your Auth0 database users

Both use cases are explained in further detail below.

### Import users

By default, any time you open the extension, you'll see the **User Import** screen (if you're on the export screen, you can return to this screen by click **Import** in the left-hand navigation bar).

To import your users, drag and drop a valid JSON file ([schema and examples here](/docs/manage-users/user-migration/bulk-user-import-database-schema-and-examples)) onto the area that says **Drop your file here, or click to select**. Alternatively, you can click on this area to browse your files and select the appropriate JSON file. The JSON file should contain the list of users that you are planning to import.

<Callout icon="file-lines">
  If you are using an export file from an Auth0 tenant, you must convert the exported file from `ndjson` to [JSON](/docs/manage-users/user-migration/bulk-user-exports#json-compatible-format). To keep the same user IDs, you must remove the `auth0| prefix` from all imported user IDs.

  The import process automatically adds the `auth0| prefix` to the imported user IDs. If you do not remove the `auth0|` prefix before importing, the user IDs return as `auth0|auth0|...`
</Callout>

Select the database connection for which your users will be imported. Please make sure that the connection you choose has been enabled for at least one application.

Click **Start Importing Users** to begin the import process.

When done, you'll see the following **Completed** message.

<Frame>
  <img alt="Dashboard Extensions Users Import Export Import Complete" />
</Frame>

Once you've imported your users, you can manage them individually using [Auth0 Dashboard > User Management > Users](https://manage.auth0.com/#/users).

### Export users

<Callout icon="file-lines">
  Auth0 uses the ndjson format due to the large size of export files. Before you can import users, you'll need to convert from **ndjson** to **json** using the library of your choice (such as [jq](https://stedolan.github.io/jq/)). When exporting users intended to later be imported, user field names should be left as their defaults and not mapped to a Column Name.
</Callout>

To export your existing Auth0 users associated with database connections, select **Export**.

<Frame>
  <img alt="Dashboard Extensions Users Import Export Export Users page" />
</Frame>

Under **User Fields**, you can decide which user attributes or expressions should be included in the export. The user attribute can be a static value like `user.user_metadata.name`, or it can be a JavaScript expression like `user.user_metadata.name || user.name`. Expressions will be evaluated during the export runtime. The **column name** value is how the value will be represented in the export.

You can click the **Add Default Fields** button to automatically select the default fields and populate their column names (this is also a good way for you to visualize how parameters/expressions will appear).

You can remove extraneous attributes/expressions by clicking on its associated **trash can** icon.

Under **Settings**, you can:

* Configure how your exported users are listed by providing a **User Attribute** by which users should be sorted (as well as whether the users should be sorted in ascending or descending order)
* Choose your **Export Format**; you can choose between JSON and CSV files

  <Frame>
    <img alt="Dashboard Extensions Users Import Export Settings Export Format" />
  </Frame>

When you're ready, click **Export X Users** (where `X` is the number of users you're exporting).

You can download the file containing your users when the export is complete; you may need to use a third-party extraction tool if you run Windows 10 or lower.

## Update Users

The Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> allows bulk user profile updates to `user_metadata` and `app_metadata` with the User Import/Export Extension.

<Callout icon="file-lines">
  Auth0 does not currently support bulk import for Passwordless. Use [Auth0 Management API](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id) to update users individually.
</Callout>

### Export users

Using the [export process above](/docs/customize/extensions/user-import-export-extension#export-users), create a complete export file including all your user attributes.

Choose the JSON format for your export.

Download the file containing your users when the export is complete.

### Update your configuration

Make a **copy** of the JSON file you downloaded in the previous step.

<Warning>
  This process can result in data loss. Create a backup of your user database in the event of data corruption.
</Warning>

Open the copy of the JSON file in a text editor. Your user schema should be similar to the one below:

```json lines expandable theme={null}
[
   {
      "Id":"auth0|626737a9813c000069daf462",
      "Nickname":"testuser1",
      "Name":"testuser1@auth0.com",
      "email":"testuser1@auth0.com",
      "Connection":"Username-Password-Authentication",
      "Created At":"2022-04-26T00:07:05.098Z",
      "Updated At":"2022-07-06T14:54:19.214Z"
   },
   {
      "Id":"auth0|62d1a1853bdcf11ff5dca672",
      "Nickname":"testuser2",
      "Name":"testuser2@auth0.com",
      "email":"testuser2@auth0.com",
      "Connection":"Username-Password-Authentication",
      "Created At":"2022-07-15T17:19:01.531Z",
      "Updated At":"2022-07-15T17:19:01.532Z"
   },
   {
      "Id":"auth0|62d1a1a524f32a4185c9ce23",
      "Nickname":"testuser3",
      "Name":"testuser3@auth0.com",
      "email":"testuser3@auth0.com",
      "Connection":"Username-Password-Authentication",
      "Created At":"2022-07-15T17:19:33.484Z",
      "Updated At":"2022-07-15T17:19:33.484Z"
   }
]
```

Do not change the user email address because it is the lookup key for users in the database.

<Callout icon="file-lines">
  The Id must have a unique `connection|id`. If the same user Id exists in multiple connections, your update will fail.
</Callout>

To add an attribute, create a new field in each user schema and update with a value. In the example below, the "Family Name" attribute has a value of "Smith" with a comma after the new attribute value.

You can also add the `email_verified` attribute to multiple users and set the value to `true`.

```json lines theme={null}
{
   "Id":"auth0|626737a9813c000069daf462",
   "Nickname":"testuser1",
   "Family Name":"Smith",
   "Name":"testuser1@auth0.com",
   "email":"testuser1@auth0.com",
   "email_verified":true,
   "Connection":"Username-Password-Authentication",
   "Created At":"2022-04-26T00:07:05.098Z",
   "Updated At":"2022-07-06T14:54:19.214Z"
}
```

Save the changes to your user file.

<Callout icon="file-lines">
  This process cannot block multiple users. You must block users individually in the Auth0 Dashboard or with the [Auth0 Management API](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id).
</Callout>

### Import updated user profile data

The `users-import` endpoint allows you to upload your updated user profile file and update several users in one job. Navigate to the [Create import users job endpoint](https://auth0.com/docs/api/management/v2/#!/Jobs/post_users_imports).

Add your user file to the users parameter and add the database connection ID of the database you want to update.

The upsert value should be `true` to update the already existing user information.
To add your updates, select **Try** or use Postman to import the users.

Use the `job_id` to verify the status with the `jobs` [endpoint](https://auth0.com/docs/api/management/v2/#!/Jobs/get_jobs_by_id).


# Forms
Source: https://auth0.com/docs/customize/forms

Forms is a visual editor that allows you to create customizable forms that can be used to extend your identity flows with additional steps and business logic.

Forms is a visual editor that allows you to create customizable forms that can extend your identity flows with additional steps and business logic.

<Frame>
  <img alt="Dashboard > Actions > Forms" />
</Frame>

Some of the key capabilities of Forms include:

* A controlled and secure experience within your tenant's domain. No need to [Redirect](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/redirect-with-actions) users to external sites.
* Pre-built components with frontend and backend validations.
* Custom business logic with out-of-the-box integrations with third parties.
* Consistent branding experience with <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>.

Using Forms enables you to build use cases like:

* **Progressive profiling:** Define a set of conditions to require users to complete additional information as they engage with your product. For example, when users login for a third-time, you can require them to complete their profile.
* **Custom policies acceptance:** If you need to update your policies, you can define logic to check if users have accepted the latest policies, and depending on that, display a custom form to users requiring acceptance.
* **Custom signup or login steps:** Extend and customize your flows with additional steps and custom logic. For example, you can verify email or phone numbers with OTP and account linking, or verify payment details with Stripe, and more.

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/customize/forms/nodes-and-components">Nodes and components</a></td>
      <td>About Forms and its components.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/forms/flows">Flows</a></td>
      <td>About Flows and its components.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/forms/variables">Variables</a></td>
      <td>About the different types of variables in Forms and Flows.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/forms/routers">Routers: Add conditional logic to Forms</a></td>
      <td>How to implement conditional logic routing in Forms.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/forms/custom-field-components">Custom Field Component for Forms</a></td>
      <td>How to create custom fields in Forms.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/forms/render">Render forms using Actions</a></td>
      <td>How to render forms using Actions.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/forms/vault">Using the Vault</a></td>
      <td>How to securely store API credentials in Forms.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/forms/custom-messages-and-translation">Custom Messages and Translation</a></td>
      <td>How to create custom messages and translations in Forms.</td>
    </tr>

    <tr>
      <td><a href="https://developer.auth0.com/resources/templates/forms">Resources: Templates</a></td>
      <td>About the Auth0 form templates.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/forms/configure-progressive-profile-form">Use Cases: Progressive profiling</a></td>
      <td>How to implement a progressive profiling form. For use with a Login Action.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/forms/configure-update-policy-form">Use Cases: Custom policies</a></td>
      <td>How to implement a custom policy form. For use with a Login Action.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/forms/configure-additional-signup-steps">Use Cases: Custom signup steps</a></td>
      <td>How to implement custom signup steps. For use with a Login Action.</td>
    </tr>
  </tbody>
</table>


# Use Cases: Configure additional signup steps using Forms
Source: https://auth0.com/docs/customize/forms/configure-additional-signup-steps

Learn how to configure additional signup steps using Forms for Actions

<Card title="Before you start">
  1. Create a [Machine-to-Machine Application](/docs/get-started/auth0-overview/create-applications/machine-to-machine-apps) with the following scopes enabled:

  * `read:users`
  * `update:users`
  * `create:users`
  * `read:users_app_metadata`
  * `update:users_app_metadata`
  * `create:users_app_metadata`

  2. Add a [Vault connection](/docs/customize/forms/vault) using the M2M application credentials.
</Card>

Forms for Actions allows you to create additional steps in your signup or login flows and make them required before allowing users to access your application.

<Frame>
  <img alt="Dashboard > Actions > Forms > Use Case Custom Signup Form" />
</Frame>

The sections below outline how to create additional signup steps forms using nodes and flows, along with steps for adding your form to a [Post Login](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) Action.

## Create a form from scratch

Follow these steps to create a form to gather information:

1. Open the Form editor by selecting **Auth0 Dashboard > Actions > Forms.**
2. Select **Create Form** > **Start from scratch**.

By default, a new form contains a Start node, a Step node, and an Ending screen node.

<Frame>
  <img alt="Dashboard > Forms > Use Cases > Form" />
</Frame>

### Configure the Step node

The Step node is the graphical interface visible to users. Add [Fields](/docs/customize/forms/nodes-and-components) to the Step node to collect the user's full name and job title values by following these steps:

1. Drag a **Rich text** field from the **Components menu** into the **Step** node.

   * **Rich text**: Enter a custom message.
   * Select **Save**.
2. Drag a **Text** field into the **Step** node.

   * **ID**: Enter `full_name`.
   * **Label**: Enter `Full name`.
   * **Label**: Enable the checkbox.
   * **Required**: Enable the checkbox.
   * Select **Save**.
3. Drag a **Text** field into the **Step** node.

   * **ID**: Enter `job_title`.
   * **Label**: Enter `Job title.`
   * **Label**: Enable the checkbox.
   * **Required**: Enable the checkbox.
   * Select **Save**.
4. Select **Publish** to save.

<Frame>
  <img alt="Dashboard > Actions > Forms > Use Case Custom Signup Steps Step node" />
</Frame>

### Configure the Flow node

Add a **Flow** node after the **Step** node to update the `user_metadata` and resume the authentication flow by following these steps:

1. Select **Flow** from the bottom of the Form editor.
2. Remove the existing link between the **Step** and **Ending Screen** nodes.
3. Select the new **Flow** > **Click to add a flow** > **Create a new flow.**

   * Enter `Update user_metadata` in the **Name** field.
   * Select **Create**.
   * Select **Save**.
4. Link the **Flow** node to the **Step** and **Ending Screen** nodes as pictured below.
5. Select **Publish** to save.

<Frame>
  <img alt="Dashboard > Actions > Forms > Use Case Custom Signup Step Update User metadata flow" />
</Frame>

Add an Auth0 Update user action to the flow by following these steps:

1. Select the **Flow** **Update user\_metadata** > **Edit flow** to open the Flow editor in a new tab.
2. Below the StartAction, select the **+** icon to add an **Update user** Action. Complete the fields below, then select **Save** to continue.

   * **Connection**: Select from the dropdown the Vault connection to your M2M application.

   * **User ID**: Enter `{{context.user.user_id}}`.

   * **Body**: Copy and paste the following code to update the user\_metadata with `full_name` and `job_title` properties.

     ```json lines theme={null}
     {
       "user_metadata": {
         "full_name": "{{fields.full_name}}",
         "job_title": "{{fields.job_title}}"
       }
     }
     ```

   * Select **Save**.
3. Select Publish to save.

## Retrieve your form render code

Retrieve your form render code to visually render the form with a custom Post Login Action by following these steps:

* From the Form editor, select **`<> Render`**.
* Select **Copy**.

<Frame>
  <img alt="Dashboard > Actions > Forms > Form > Embed" />
</Frame>

## Create a Post Login Action

Create a post-login Action to render your form by following these steps:

1. Navigate to **Auth0 Dashboard > Actions > Flows > Login.**
2. Select the **+** icon and select **Build from scratch**:

   * **Name**: Enter `Render Additional Signup Form`.
   * **Trigger**: Select `Login / Post Login`.
   * **Runtime**: Select the recommended version.
3. Select **Create**.

To configure the post-login Action:

1. Delete the existing code from the Code editor.
2. Paste the form render code into the Code editor.
3. Edit the code to define the conditional logic that will render the form.

   ```javascript lines theme={null}
   /**
   * @param {Event} event - Details about the user and the context in which they are logging in.
   * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
   */
   exports.onExecutePostLogin = async (event, api) => {
     const FORM_ID = 'REPLACE_WITH_YOUR_FORM_ID';

     if (
       !event.user.user_metadata.full_name &&
       !event.user.user_metadata.job_title
     ) {
       api.prompt.render(FORM_ID);
     }
   }

   exports.onContinuePostLogin = async (event, api) => { }
   ```

   <Callout icon="file-lines">
     The example code above will render the form when a user is missing the user metadata full\_name and job\_title properties.
   </Callout>
4. Select **Deploy.**
5. Drag and Drop the **Render Additional Signup Form** Action to the **Login** flow.

   <Frame>
     <img alt="Dashboard > Forms > Use Cases Custom Signup Steps Login Flow" />
   </Frame>
6. Select **Apply**.

### Test implementation

Test the implementation by following these steps:

* Sign up to an application with a new user.
* The post-login Action in the Login flow will render the form and prompt for the information.
* Select **<Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> > User Management > Users,** locate the new user, and verify that its attributes `full_name` and `job_title` contain the information from the additional signup step.


# Use Cases: Configure a progressive profile form using Forms
Source: https://auth0.com/docs/customize/forms/configure-progressive-profile-form

Learn how to configure a progressive profile form using Forms for Actions

<Card title="Before you start">
  1. Create a [Machine-to-Machine Application](/docs/get-started/auth0-overview/create-applications/machine-to-machine-apps) with the following scopes enabled:

  * `read:users`
  * `update:users`
  * `create:users`
  * `read:users_app_metadata`
  * `update:users_app_metadata`
  * `create:users_app_metadata`

  2. Add a [Vault connection](/docs/customize/forms/vault) using the M2M application credentials.
</Card>

Forms for Actions allows you to create progressive profiling flows to decide when to prompt users to collect missing information, such as company name and job title, and store them as `user_metadata` attributes.

<Frame>
  <img alt="Dashboard > Actions > Forms > Form" />
</Frame>

The sections below outline how you can create a progressive profile form using nodes and flows, along with steps for adding your form to a [Post Login Action](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger).

## Create a form from scratch

Follow these steps to create a form to gather information:

1. Open the Form editor by selecting **Auth0 Dashboard > Actions > Forms.**
2. Select **Create Form** > **Start from scratch**.

By default, a new form contains a Start node, a Step node, and an Ending screen node.

<Frame>
  <img alt="Dashboard > Forms > Use Cases > Form" />
</Frame>

### Configure the Step node

The Step node is the graphical interface visible to users. Add [Fields](/docs/customize/forms/nodes-and-components) to the Step node to collect the user's company name and job title values by following these steps:

1. Drag a **Rich text** field from the **Components menu** into the **Step** node.

   * **Rich text**: Enter a custom message.

     * **Example**: `Complete your profile! We need you to complete your profile to personalize your experience.`
   * Select **Save**.
2. Drag a **Text** field into the **Step** node.

   * **ID**: Enter `company_name`.
   * **Label**: Enable the checkbox.
   * **Label**: Enter `Company name`.
   * **Required**: Enable the checkbox.
   * Select **Save**.
3. Drag a **Text** field into the **Step** node.

   1. **ID**: Enter `job_title`.
   2. **Label**: Enter `Job title`.
   3. **Label**: Enable the checkbox.
   4. **Required**: Enable the checkbox.
   5. Select **Save**.
4. Select **Publish** to save.

<Frame>
  <img alt="Dashboard > Actions > Forms > Form > Step node" />
</Frame>

### Configure the flow node

Add a **Flow** node after the **Step** node to update the `user_metadata` and resume the authentication flow by following these steps:

1. Select **Flow** from the bottom of the Form editor.
2. Remove the existing link between the **Step** and **Ending Screen** nodes.
3. Select the new **Flow** > **Click to add a flow** > **Create a new flow.**

   * Enter `Update user_metadata` in the **Name** field.
   * Select **Create**.
   * Select **Save**.
4. Link the **Flow** node to the **Step** and **Ending Screen** nodes as pictured below.
5. Select **Publish** to save.

<Frame>
  <img alt="Dashboard > Actions > Forms > Form" />
</Frame>

Add an Auth0 Update user action to the flow by following these steps:

1. Select the **Update user\_metadata** flow, then select the **Edit Flow** to open the Flow editor in a new tab.
2. Below the **Start** action, select the **+** icon to add an **Update user** action. Complete the fields below, then select **Save** to continue.

   * **Connection**: Select from the dropdown the Vault connection to your M2M application.

   * **User ID**: Enter `{{context.user.user_id}}`.

   * **Body**: Copy and paste the following code to update the user\_metadata with `job_title` and `company_name` properties.

     ```json lines theme={null}
     {
        "user_metadata": {
           "job_title": "{{fields.job_title}}",
           "company_name": "{{fields.company_name}}"
        }
     }
     ```

   * Select **Save**.
3. Select **Publish** to save.

<Frame>
  <img alt="Dashboard > Actions > Forms > Flows" />
</Frame>

### Retrieve the form render code

Retrieve the form render code to visually render the form with a custom Post Login Action by following these steps:

* From the Form editor, select **`<> Render`**.
* Select **Copy**.

<Frame>
  <img alt="Dashboard > Actions > Forms > Form > Embed" />
</Frame>

## Create a Post Login Action

Create a post-login Action to render your form by following these steps:

1. Navigate to **Auth0 Dashboard > Actions > Flows > Login.**
2. Select the **+** icon and select **Build from scratch**:

   * **Name**: Enter `Render Progressive Profile Form`.
   * **Trigger**: Select `Login / Post Login`.
   * **Runtime**: Select the recommended version.
3. Select **Create**.

To configure the post-login Action:

1. Delete the existing code from the Code editor.
2. Paste the form embed code into the Code editor.
3. Edit the code to define the conditional logic that will render the form.

   ```javascript lines theme={null}
   /**
   * @param {Event} event - Details about the user and the context in which they are logging in.
   * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
   */
   exports.onExecutePostLogin = async (event, api) => {
     const FORM_ID = 'REPLACE_WITH_YOUR_FORM_ID';

     if (
       event.stats.logins_count > 2 &&
       !event.user.user_metadata.company_name &&
       !event.user.user_metadata.job_title
     ) {
       api.prompt.render(FORM_ID);
     }
   }

   exports.onContinuePostLogin = async (event, api) => { }
   ```

   <Callout icon="file-lines">
     The example code above will render the form when a user has a login count > 2 and is missing the user metadata company\_name and job\_title properties.
   </Callout>
4. Select **Deploy.**
5. Drag and Drop the **Render Progressive Profile Form** Action to the **Login** flow.

   <Frame>
     <img alt="Dashboard > Forms > Use Cases Progressive Profile Login Action" />
   </Frame>
6. Select **Apply**.

### Test implementation

Test the implementation by following these steps:

1. Log in with an existing user whose login count is greater than 2 and their `user_metadata` attributes `company_name` and `job_title` have no values.
2. The post-login action in the Login flow will render the form and prompt for the information.
3. Select **Auth0 Dashboard > User Management > Users,** locate the user and verify that the `user_metadata` attributes `company_name` and `job_title` contain information.


# Use Cases: Configure an update policy form using Forms
Source: https://auth0.com/docs/customize/forms/configure-update-policy-form

Configure an update policy form using Forms for Actions

<Card title="Before you start">
  1. Create a [Machine-to-Machine Application](/docs/get-started/auth0-overview/create-applications/machine-to-machine-apps) with the following scopes enabled:

  * `read:users`
  * `update:users`
  * `create:users`
  * `read:users_app_metadata`
  * `update:users_app_metadata`
  * `create:users_app_metadata`

  2. Add a [Vault connection](/docs/customize/forms/vault) using the M2M application credentials.
</Card>

Forms for Actions allows you to create custom privacy policies flows and store the consent under the `app_metadata` object.

<Frame>
  <img alt="Dashboard > Actions > Forms > Privacy policy use case" />
</Frame>

The sections below outline how you can create an Update Policy form using nodes and flows, along with steps for adding your form to a [Post Login](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) Action.

## Create a form from scratch

Follow these steps to create a form to gather information:

1. Open the Form editor by selecting **Auth0 Dashboard > Actions > Forms.**
2. Select **Create Form** > **Start from scratch**.

By default, a new form contains a Start node, a Step node, and an Ending screen node.

<Frame>
  <img alt="Dashboard > Forms > Use Cases > Form" />
</Frame>

### Configure the Step node

The Step node is the graphical interface visible to users. Add [Fields](/docs/customize/forms/nodes-and-components) to the Step node to collect the new agreement acceptance value by following these steps:

1. Drag a **Rich text** field from the **Components menu** into the **Step** node.

   * **Rich text**: Enter a description of your privacy policies updates.
   * Select **Save**.
2. Drag a **Legal** field into the **Step** node.

   * **ID**: Enter `privacy_policies`.
   * **Required**: Enable the checkbox.
   * **Legal**: Enter `I agree to the Privacy Policy`.
   * Select **Save**.
3. Select **Publish** to save.

<Frame>
  <img alt="Dashboard > Actions > Forms > Use case privacy policy step node" />
</Frame>

### Configure the Flow node

Add a **Flow** node after the **Step** node to update the `app_metadata` and resume the authentication flow by following these steps:

1. Select **Flow** from the bottom of the Form editor.
2. Remove the existing link between the **Step** and **Ending Screen** nodes.
3. Select the new **Flow** > **Click to add a flow** > **Create a new flow.**

   * Enter `Update app_metadata` in the **Name** field.
   * Select **Create**.
   * Select **Save**.
4. Link the **Flow** node to the **Step** and **Ending Screen** nodes as pictured below.
5. Select **Publish** to save.

<Frame>
  <img alt="Dashboard > Actions > Forms > Form" />
</Frame>

Add an Auth0 Update user action to the flow by following these steps:

1. Select the **Flow** **Update app\_metadata** > **Edit flow** to open the Flow editor in a new tab.
2. Below the StartAction, select the **+** icon to add an **Update user** action. Complete the fields below, then select **Save** to continue.

   * **Connection**: Select from the dropdown the Vault connection to your M2M application.

   * **User ID**: Enter `{{context.user.user_id}}`.

   * **Body**: Copy and paste the following code to update the app\_metadata with the privacy\_policies and privacy\_policies\_timestamp properties.

     ```text lines theme={null}
     {
       "app_metadata": {
         "privacy_policies": true,
         "privacy_policies_timestamp": "{{ functions.toTimestamp() }}"
       }
     }
     ```

   * Select **Save**.
3. Select **Publish** to save.

<Frame>
  <img alt="Dashboard > Actions > Forms > User case privacy policy code" />
</Frame>

<Callout icon="file-lines">
  The flow **Update app\_metadata** adds a `privacy_policies true` value to the app`_metadata` object and also generates a timestamp with a [helper function.](/docs/customize/forms/variables)
</Callout>

## Retrieve the form render code

Retrieve your form render code to visually render the form with a custom Post Login Action by following these steps:

* From the Form editor, select **`<> Render`**.
* Select **Copy**.

<Frame>
  <img alt="Dashboard > Actions > Forms > Form > Embed" />
</Frame>

## Create a Post Login Action

Create a post-login Action to render your form by following these steps:

1. Navigate to **Auth0 Dashboard > Actions > Flows > Login.**
2. Select the **+** icon and Select **Build from scratch**:

   * **Name**: Enter `Render Update Policy Form`.
   * **Trigger**: Select `Login / Post Login`.
   * **Runtime**: Select the recommended version.
3. Select **Create**.

To configure the post-login Action:

1. Delete the existing code from the Code editor.
2. Paste the form render code into the Code editor.
3. Edit the code to define the conditional logic that will render the form.

   ```javascript lines theme={null}
   /**
   * @param {Event} event - Details about the user and the context in which they are logging in.
   * @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
   */
   exports.onExecutePostLogin = async (event, api) => {
     const FORM_ID = 'REPLACE_WITH_YOUR_FORM_ID';

     if (event.user.app_metadata.privacy_policies !== true) {
       api.prompt.render(FORM_ID);
     }
   }

   exports.onContinuePostLogin = async (event, api) => { }
   ```

   <Callout icon="file-lines">
     The example code above will render the form when a user is missing the app metadata `privacy_policies` property.
   </Callout>
4. Select **Deploy.**
5. Drag and Drop the **Render Update Policy Form** Action to the **Login** flow.

   <Frame>
     <img alt="Dashboard > Forms > Use Case > Render update policy form login action" />
   </Frame>
6. Select **Apply.**

### Test implementation

Test the implementation by following these steps:

1. Log in with an existing user whose app`_metadata` attribute `privacy_policies` does not have a value.
2. The post-login Action in the Login flow will render the form and prompt for acceptance.
3. Select **Auth0 Dashboard > User Management > Users,** locate the user and verify that the `app_metadata` attribute `privacy_policies` contains a `true` value and a timestamp.


# Custom Field Components
Source: https://auth0.com/docs/customize/forms/custom-field-components

Learn how to use custom components to create fields that require specific logic or UI using JavaScript, HTML and CSS.

<Frame>
  <img alt="Dashboard > Actions > Forms > Custom field" />
</Frame>

Using the custom field, you can extend the look and feel of your forms and add powerful logic with JavaScript, HTML, and CSS.

The custom field has internal methods to facilitate passing data to the form, adding frontend and backend validations, and handling common events such as focus or blur.

You can use custom field to create:

* Fields with a custom data structure.

  * **Example**: Objects, array of strings
* Fields that use third-party widgets.

  * **Example**: Google Address autocomplete
* Fields with logic to hide or show other fields.
* Fields that require external APIs to get a value.

<Warning>
  To use custom fields you need to enable [Custom Domains](/docs/customize/custom-domains). Rendering a form with a custom field outside a custom domain, will display an error.
</Warning>

## Custom field settings

The custom field settings are:

### Params

Add key-value pairs to reference in the custom field source code. Key-value pairs can include form field [variables](/docs/customize/forms/variables).

<Frame>
  <img alt="" />
</Frame>

<Callout icon="file-lines">
  Param values are only available after the form invokes the `init()` method.
</Callout>

**Example**:

In the example below, the custom field param settings are populated with the key-value pairs `symbol={{fields.symbol}}` and `separator=,`

```javascript lines expandable theme={null}
function CustomComponent(context) {
  const input = document.createElement('input');
  let mask = null;

  function mountComponent() {
    /** getParams() method returns the params you've configured in your input */
    const config = context.custom.getParams();
    const { symbol, separator } = config;

    mask = IMask(input,
    {
      mask: `${symbol}num`,
      blocks: {
        num: {
          mask: Number,
          thousandsSeparator: separator,
        }
      }
    });
  }

  return {
    /** Invoked once when the field is created */
    init() {
      mountComponent();
      return input;
    },
    ...
  };
}
```

### Source code

Add your Javascript code to the custom field.

<Frame>
  <img alt="" />
</Frame>

**Example**:

```javascript lines theme={null}
function customInput() {
  const input = document.createElement('input');
  input.type = 'text';

  return {
    init() {
      return input;
    },

    block() {
      input.disabled = true;
    },

    unblock() {
      input.disabled = false;
    },

    getValue() {
      return input.value;
    }
  };
}
```

### JSON Schema

By default, the custom field accepts any value format. However, you can use [JSON Schema](https://json-schema.org/) to validate values server-side.

<Frame>
  <img alt="" />
</Frame>

**Example**:

```json lines theme={null}
{
  "type": "array",
  "items": {
    "type": "string"
  },
  "minItems": 2
}
```

To accommodate complex validation requirements, you can use a [flow](/docs/customize/forms/flows).

### CSS

Add your CSS styles to the custom field.

<Frame>
  <img alt="" />
</Frame>

## Custom field handlers

You can use these handlers to add custom behavior to the field:

### init()

Invoked once when the field is created and passes the params values that you configure in the Params settings.

Returns an HTML element, string, or no value.

**Example**:

```javascript lines theme={null}
const input = document.createElement('input');
input.type = 'text';

init() {
  return input;
}
```

### update()

Invoked when the user visits the same form step again.

This option is useful when you need to re-render UI logic or refresh params values that may have changed.

### onFocus()

Invoked when focus enters the custom field HTML element.

### onBlur()

Invoked when focus abandons the custom field HTML element.

### getValue()

Invoked when the form needs to get the custom field value one or more times. This is typically executed when the user submits the form step. If you need to perform client-side validations, you can throw an error to display a custom error message to the user.

**Example:**

```javascript lines theme={null}
function customTextInput() {
  const input = document.createElement('input');
  input.type = 'text';

  return {
    init() {
      return input;
    },

    getValue() {
      if (input.value !== 'Auth0') {
        throw new Error('The value must be Auth0')
      }

      return input.value;
    }
  };
}
```

### block()

Invoked when the custom field must be blocked. This is typically executed when the user submits the form step, and data is being processed to our backend.

### unblock()

Invoked when the custom field must be unblocked. This is typically executed after the user submits the form step or the data has stopped being processed to our back-end due to a validation error.

### getScripts()

Returns a list of URLs the form guarantees will have finished loading before the `init()` method is invoked.

**Example**:

```js lines theme={null}
getScripts() {
  return ['https://example.com/script_a.js', 'https://example.com/script_b.js'];
}
```

## Context object

When passing a context object, you can use these methods to handle logic on your form and components.

### Custom methods

#### context.custom.getValue()

Receives the value of the current custom field.

#### context.custom.setValue()

Sets a value to the current custom field.

**Example**:

```javascript lines theme={null}
function customInput(context) {
  const input = document.createElement('input');
  input.type = 'text';

  input.addEventListener('change', () => {
    context.custom.setValue(input.value);
  });

  return {
    init() {
      return input;
    },
  };
}
```

#### context.custom.createUid()

Returns a unique identifier for the current custom field.

**Example**:

```javascript lines theme={null}
function customInput(context) {
  const input = document.createElement('input');
  input.type = 'text';
  input.id = context.custom.createUid();

  return {
    init() {
      return input;
    },

    getValue() {
      return input.value;
    }
  };
}
```

#### context.custom.getParams()

Receives the parameters from the current custom field settings.

<Callout icon="file-lines">
  Param values are only available after the form invokes the `init()` method.
</Callout>

**Example**:

```javascript lines theme={null}
function customInput(context) {
  // Accessing parameters on the root of the function does NOT work
  // const { defaultValue } = context.custom.getParams();
  // console.log(defaultValue); // undefined

  function buildInput() {
    const { defaultValue } = context.custom.getParams();
    const input = document.createElement('input');
    input.type = 'text';
    input.value = defaultValue;

    return input;
  }

  return {
    init() {
      return buildInput();
    },

    getValue() {
      return input.value;
    }
  };
}
```

### Form methods

When you need to interact with the form to gather values from other fields or navigate to other form steps, you can use the following form methods:

#### context.form.getId()

Returns a unique identifier for the current form.

#### context.form.getRoot()

Returns the root HTML element for the current form.

#### context.form.goForward()

Goes to the next form step.

#### context.form.goPrevious()

Goes to the previous form step.

#### context.form.isValid()

Returns a boolean if the form passes all the client-side validations.

#### context.form.validate()

Evaluates existing field values using client-side validation before continuing. If a field does not pass the validation, an error message will appear.

#### context.form.getAllHiddenFields()

Returns an object with all hidden field values.

#### context.form.setHiddenField(id, value)

Sets a hidden field value.

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>id</code></td>

      <td>
        <p>
          <em>String</em>. The ID of the hidden field.
        </p>
      </td>
    </tr>

    <tr>
      <td><code>value</code></td>

      <td>
        <p>
          <em>String</em>. The value of the hidden field.
        </p>
      </td>
    </tr>
  </tbody>
</table>

#### context.form.getValues()

Returns an object with all field and hidden field values.

#### context.form.getField(id)

Returns an instance for the specified field.

* `getNode() | true` Returns the root HTML element of the field.
* `getValue()` Returns the field value.
* `setRequired(boolean)` Sets or unsets the field as required.

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>id</code></td>

      <td>
        <p>
          <em>String </em>. The ID field value.
        </p>
      </td>
    </tr>
  </tbody>
</table>

**Example**:

```javascript lines theme={null}
const fullName = context.form.getField('full_name');
const fullNameValue = fullName.getValue();
console.log(fullNameValue); // John Doe
```

<Callout icon="file-lines">
  `setRequired()` only sets or unsets the field as required on the client-side. For example, if you unset a field as required, but it was marked as required in your field settings, the form will return an error if the field has no value.
</Callout>

## Custom field examples

The sections below provide example custom fields you can add to your forms:

### Range input custom field

A custom field that returns a value from a predetermined range.

<Frame>
  <img alt="" />
</Frame>

**Source code**:

```javascript lines theme={null}
function rangeInput() {
  const input = document.createElement('input');
  input.type = 'range';
  input.min= '0';
  input.max= '100';
  input.value = '0';

  return {
    init() {
      return input;
    },

    getValue() {
      return input.value;
    }
  };
}
```

### Color input custom field

A custom field that returns a color hex value.

<Frame>
  <img alt="" />
</Frame>

**Source code**:

```javascript lines theme={null}
function colorInput() {
  const input = document.createElement('input');
  input.type = 'color';
  input.value = '#20c5a0';

  return {
    init() {
      return input;
    },

    getValue() {
      return input.value;
    },
  };
}
```

### Autocomplete input custom field using values from API

A custom field that returns an autocomplete value using a third-party API.

<Frame>
  <img alt="" />
</Frame>

**Source code**:

```javascript lines expandable theme={null}
function textInputWithAutocomplete(context) {
  const input = document.createElement('input');
  input.type = 'text';

  function populateInputValue(json) {
    const { city } = json;

    input.value = city;
  }

  function fetchIpInfo() {
    const url = 'https://ipinfo.io/json';
    fetch(url)
      .then((res) => res.json())
      .then((json) => populateInputValue(json));
  }

  return {
    init() {
      fetchIpInfo();
      return input;
    },

    getValue() {
      return input.value;
    },
  };
}
```

### Dynamic dropdown custom field using values from API

A custom field that returns a value from a dynamic dropdown list using a third-party API.

<Frame>
  <img alt="" />
</Frame>

**Source code**:

```javascript lines expandable theme={null}
function dynamicDropdown() {
  const select = document.createElement('select');
  select.classList.add('af-stringField-input');

  function buildOption(data) {
    const { name: { first } } = data;
    const option = document.createElement('option');
    option.value = first;
    option.innerText = first;

    return option;
  }

  function populateNames(json) {
    const { results } = json;

    results.forEach((o) => {
      const option = buildOption(o);

      select.appendChild(option);
    });
  }

  function fetchNames() {
    const url = 'https://randomuser.me/api/?results=10&inc=name';
    fetch(url)
      .then((res) => res.json())
      .then((json) => populateNames(json));
  }

  return {
    init() {
      fetchNames();
      return select;
    },

    getValue() {
      return select.value;
    },
  };
}
```

### Dynamic input custom field with a (+) button to add more fields

A custom field that allows users to add more fields.

<Frame>
  <img alt="" />
</Frame>

**Source code**:

```javascript lines expandable theme={null}
function DynamicInputs(context) {
  const DEFAULT_INITIAL_INPUTS = 2;
  const DEFAULT_PLACEHOLDER = 'jane.doe@example.com';
  const DEFAULT_ADD_BUTTON_TEXT = 'Add new item';
  const DEFAULT_INPUT_TYPE = 'email';
  const STATE_VALUE = {};
  const FIELD_ID = context.custom.createUid();
  let UUID_COUNTER = 0;
  let INPUTS_COUNTER = 0;

  const container = document.createElement('div');

  const inputsContainer = document.createElement('div');
  container.appendChild(inputsContainer);

  function buildAddNewItem() {
    const config = context.custom.getParams();
    const { add_button_text } = config;

    const ADD_BUTTON_TEXT = add_button_text || DEFAULT_ADD_BUTTON_TEXT;

    const addInputButton = document.createElement('button');
    addInputButton.type = 'button';
    addInputButton.classList.add('af-dynamic-input-add-button');
    addInputButton.id = `${FIELD_ID}_add-input-button`;
    addInputButton.onclick = buildInputContainer.bind(this);

    const addInputButtonIcon = document.createElement('span');
    addInputButtonIcon.classList.add('af-button', 'af-dynamic-input-add-button-icon');
    addInputButtonIcon.innerText = '+';

    const addInputButtonText = document.createElement('span');
    addInputButtonText.classList.add('af-dynamic-input-add-button-text');
    addInputButtonText.innerText = ADD_BUTTON_TEXT;

    addInputButton.appendChild(addInputButtonIcon);
    addInputButton.appendChild(addInputButtonText);
    container.appendChild(addInputButton);
  }

  function removeInput(container, input) {
    delete STATE_VALUE[input.name];
    container.remove();
  }

  function buildRemoveInputButton(container, input) {
    const button = document.createElement('button');
    button.type = 'button';
    button.classList.add('af-button', 'af-dynamic-input-remove-button');
    button.innerText = '-';
    button.onclick = removeInput.bind(this, container, input);

    INPUTS_COUNTER--;

    return button;
  }

  function buildInput() {
    const config = context.custom.getParams();
    const { placeholder, input_type } = config;

    const PLACEHOLDER = placeholder || DEFAULT_PLACEHOLDER;
    const INPUT_TYPE = input_type || DEFAULT_INPUT_TYPE;

    const input = document.createElement('input');
    input.type = INPUT_TYPE;
    input.placeholder = PLACEHOLDER;
    input.classList.add('af-stringField-input');
    input.name = `${FIELD_ID}_${UUID_COUNTER}`;
    input.id = input.name;
    input.addEventListener('change', () => {
      STATE_VALUE[input.name] = input.value;
    });

    UUID_COUNTER++;

    return input;
  }

  function buildInputContainer() {
    const container = document.createElement('div');
    container.classList.add('af-dynamic-input-container');

    const input = buildInput();
    container.appendChild(input);

    const removeButton = buildRemoveInputButton(container, input);
    container.appendChild(removeButton);

    inputsContainer.appendChild(container);

    INPUTS_COUNTER++;
  }

  function initComponent() {
    const config = context.custom.getParams();
    const { initial_inputs } = config;

    const INITIAL_INPUTS = initial_inputs || DEFAULT_INITIAL_INPUTS;
    INPUTS_COUNTER = INITIAL_INPUTS

    for (let i = 0; i < INITIAL_INPUTS; i++) {
      buildInputContainer();
    }
  }

  function blockFields(value) {
    const inputKeys = Object.keys(STATE_VALUE);

    inputKeys.forEach((o) => {
      const selector = document.getElementById(o);
      selector.disabled = value;
    });
  }

  return {
    init() {
      buildAddNewItem();
      initComponent();
      return container;
    },

    block() {
      blockFields(true);
    },

    unblock() {
      blockFields(false);
    },

    getValue() {
      return Object.values(STATE_VALUE);
    },
  };
}
```

**CSS code:**

```css lines expandable theme={null}
.af-button.af-dynamic-input-remove-button {
  width: 48px;
  color: var(--button-font-color);
  background: var(--button-background-color);
}

.af-dynamic-input-container {
  display: flex;
  margin-bottom: var(--spacing-1);
}

.af-dynamic-input-container input {
  margin-right: var(--spacing-1);
}

button.af-dynamic-input-add-button {
  background: none;
  border: none;
  padding: 0;
  margin: 0;
  margin-top: var(--spacing-1);
  display: inline-flex;
  cursor: pointer;
  align-items: center;
}

.af-button.af-dynamic-input-add-button-icon {
  background: var(--primary-color);
  width: 24px;
  padding: 0;
  height: 24px;
  border-radius: .3em;
  display: flex;
  justify-content: center;
  align-items: center;
  color: #fff;
  margin-right: var(--spacing-1);
}

.af-dynamic-input-add-button-text {
  color: var(--label-font-color);
  font-size: var(--label-font-size);
}

.af-dynamic-input-add-button:focus {
  outline: none;
}

.af-dynamic-input-add-button:hover .af-button {
  transition: filter var(--transition-normal), box-shadow var(--transition-normal);
  filter: brightness(1.1);
  box-shadow: 0 0 0 var(--outline-width) var(--outline-color), 0px 4px 8px -4px var(--shadow-color), 0px 16px 24px var(--shadow-color);
}

.af-dynamic-input-add-button:focus .af-button {
  box-shadow: 0 0 0 var(--outline-width) var(--outline-color), 0px 4px 8px -4px var(--shadow-color), 0px 16px 24px var(--shadow-color);
}
```


# Custom Messages and Translation
Source: https://auth0.com/docs/customize/forms/custom-messages-and-translation

Describes how to create custom messages and translations with Forms.

You can  customize Form messages to provide your users with a unique Form experience. In addition, you can translate form components, errors, and other custom messages into other languages for a localized experience.

## Messages

Through the Form editor, you can customize error messages and create other custom messages for your users.

### Error messages

You can create custom error messages to replace the default error messages of your forms.

To create custom error messages, follow the steps below:

1. On the Auth0 Dashboard, navigate to **Actions > Forms**.
2. Select **Messages** from the left menu of the Form editor.
3. Select the **Errors** tab\*\*.\*\*
4. Enter your custom error messages in the appropriate fields to replace the default messages.
5. Select **Publish** to save.

### Custom messages

You can create custom messages to add to the default messages for an even further personalized Form experience. For example, you can add a custom message that displays to users when an action returns an error in a flow.

#### Create custom messages

To create custom messages, follow the steps below:

1. From the left menu of the Form editor, select **Messages**.
2. Select the **Custom** tab.Then, select **Add New Item**.
3. To the left, add a unique key for your message\*\*.\*\* Then\*\*, enter\*\* your custom message in the field to the right.
4. Select **Publish** to save.

<Frame>
  <img alt="Dashboard > Forms > Custom messages and translations > Custom message" />
</Frame>

#### Add custom messages to your forms

To reference your custom messages in your forms, use the function `{{t('custom_unique_key')}}` with the custom message unique key.

<Frame>
  <img alt="Dashboard > Forms > Custom messages and translations > Translation function" />
</Frame>

## Translations

You can use the Translations feature to create an international user experience of your forms. This feature leverages a user’s browser language to determine the appropriate language for your forms.
By default, translations for some standard error messages are provided in Spanish. However, to promote a quality user experience, you can define the translations for your form components, errors, and custom messages in the language of your choice.

To enable translations, follow the steps below:

1. On the Auth0 Dashboard, navigate to **Actions > Forms**.
2. Select **Translations** from the left menu of the Form editor.
3. Check **Enable additional languages**.
4. Select the desired languages from the **Additional languages** dropdown menu.

### Translate messages

With the language editor, you can define translations for your form components, errors, and other custom messages.

To define your translations, follow the steps below:

1. Select the desired language from theSelect language dropdown menu.
2. Select one of the following tabs to begin defining your translations:

   1. **Components**
   2. **Errors**
   3. **Custom**
3. For each available field, provide your translations as needed.
4. Select **Publish** to save.

<Frame>
  <img alt="Dashboard > Forms > Custom messages and translations > Translation message" />
</Frame>


# Flows
Source: https://auth0.com/docs/customize/forms/flows

Describes how to use Flows with Forms.

Flows allow you to visually build the server-side logic that can be executed within your Forms and handle the collected information, integrate any service with an API or trigger automations.

<Frame>
  <img alt="Dashboard > Forms > Flows" />
</Frame>

You can use Flows actions with your form to:

* Create custom server-side validations for your form steps.
* Integrate with your own API making custom HTTP requests.
* Integrate with 3rd parties using our out-of-the-box integrations.
* Execute different business logic based based on user input or properties.
* Validate data using <Tooltip href="/docs/glossary?term=JSON+Web+Tokens">JSON Web Tokens</Tooltip>.


# Execution and Debugger
Source: https://auth0.com/docs/customize/forms/flows/flow-execution-and-debugger

Describes how to review Flow executions and debug executions of Forms.

Each time a flow executes, Auth0 stores an entry that you can use to debug the execution. This is useful to understand why a flow execution error has occurred. For example: a flow can fail due to missing properties, typos, incorrect API keys, etc.

## Review flow executions

To review an execution entry for a flow, follow the steps below:

1. Navigate to **Auth0 Dashboard > Actions > Forms**, then select **Flows**.
2. Select a flow from the list.
3. Select **Executions**.

<Frame>
  <img alt="Dashboard > Actions > Forms > Flows > Execution" />
</Frame>

Every execution entry has four properties:

* **Execution date**: The date of the flow execution.
* **Execution ID**: The unique ID of the flow execution.
* **Status**: The current stage of the flow execution. There are four possible execution statuses:

  * **Running**: The execution is currently in progress.
  * **Failed**: The execution failed due to an internal error, such as missing required settings in a flow action.
  * **Completed**: The execution finished without internal errors.
* **View Details**: Opens the debug window of the execution.

<Frame>
  <img alt="Dashboard > Actions >  Forms > Flows > Executions" />
</Frame>

<Callout icon="file-lines">
  Completed and Failed are final statuses. When an execution reaches either status, the flow is fully processed.
</Callout>

## Debug flow executions

To help debug or troubleshoot a flow, you can review the flow’s input, output, and error data by accessing the **View Details** of the execution.

<Frame>
  <img alt="Dashboard > Actions > Forms > Form" />
</Frame>

To debug an error that interrupts the flow execution, follow these steps:

1. Navigate to **Auth0 Dashboard > Actions > Forms**
2. Locate the flow linked to the step node.

   <Frame>
     <img alt="Dashboard > Actions > Forms > Form" />
   </Frame>
3. Select **Edit Flow.**
4. Select **Executions**.
5. Select **View Details** of the Failed execution.

In the example below, the `Update user` **Input** view shows a null value for the  `user_id` property.

<Frame>
  <img alt="Dashboard > Actions > Forms > Flow > Execution" />
</Frame>

The **Error** view indicates that the action’s schema validation failed due to a missing the required `user_id`. The flow returns an internal error that interrupts the flow execution.

<Frame>
  <img alt="Dashboard > Actions > Forms > Flow > Execution > Error" />
</Frame>

A review of the **Update user** action shows a syntax error in the `User ID` parameter, the correct syntax is `{{context.user.user_id}}`. Once the syntax is corrected, test the flow to confirm. To learn more about variable syntaxes, read [Variables](/docs/customize/forms/variables).

<Frame>
  <img alt="Dashboard > Actions > Forms > Flows" />
</Frame>

<Callout icon="file-lines">
  If a field is configured as transient or when its value is masked with a [Helper function](/docs/customize/forms/variables#helper-functions), the value is not available to debug.

  <Frame>
    <img alt="Dashboard > Actions > Forms > Flows > Execution" />
  </Frame>
</Callout>


# Integrations
Source: https://auth0.com/docs/customize/forms/flows/integrations

Learn about the actions that you can add to your flows

<Frame>
  <img alt="" />
</Frame>

Here you can find a list of integration categories and discover the actions to add business logic to your [form](/docs/customize/forms) and flows.

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/customize/forms/flows/integrations/auth0">Auth0</a></td>
      <td>About the Auth0 integration and its actions.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/forms/flows/integrations/data-verification">Data verification</a></td>
      <td>About the Data verification integration and its actions.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/forms/flows/integrations/http-request">HTTP Request</a></td>
      <td>About the HTTP integration and its action.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/forms/flows/integrations/json">JSON</a></td>
      <td>About the JSON integration and its actions.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/forms/flows/integrations/json-web-token">JSON Web Token</a></td>
      <td>About JSON Web Token integration and its actions.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/forms/flows/integrations/logic">Logic</a></td>
      <td>About the Logic integration and its actions.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/forms/flows/integrations/mailjet">Mailjet</a></td>
      <td>About the Mailjet integration and its action.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/forms/flows/integrations/sendgrid">SendGrid</a></td>
      <td>About the SendGrid integration and its action.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/forms/flows/integrations/telegram">Telegram</a></td>
      <td>About the Telegram integration and its action.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/forms/flows/integrations/twilio">Twilio</a></td>
      <td>About the Twilio integration and its actions.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/forms/flows/integrations/whatsapp">WhatsApp</a></td>
      <td>About the WhatsApp integration and its action.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/forms/flows/integrations/xml">XML</a></td>
      <td>About the XML integration and its actions.</td>
    </tr>
  </tbody>
</table>


# Auth0
Source: https://auth0.com/docs/customize/forms/flows/integrations/auth0

Learn how to configure your Auth0 pre-built flow actions to make requests against the Management API or send custom notifications.

## Configure your Auth0 Vault Connection

Learn how to configure a Vault Connection for your Auth0 Flow Actions at [Auth0 Vault Connection](/docs/customize/forms/vaults/auth0).

## Create user

Create a user.

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Body</td>
      <td>The payload of Auth0 user properties to add. To learn more, read <a href="https://auth0.com/docs/api/management/v2/users/post-users">Create a user</a>  API documentation. </td>
    </tr>
  </tbody>
</table>

### Output object

Review [Create a user](https://auth0.com/docs/api/management/v2/users/post-users#response-messages) for expected response and status code.

## Get user

Retrieve user details.

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>User ID</td>
      <td>ID of the user to retrieve. To learn more, read [Get a user](https://auth0.com/docs/api/management/v2/users/get-users-by-id) API documentation. </td>
    </tr>
  </tbody>
</table>

### Output object

Review [Get a user](https://auth0.com/docs/api/management/v2/users/get-users-by-id#response-messages) for expected response and status code.

## Update user

Update a user.

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>User ID</td>
      <td>ID of the user to update.</td>
    </tr>

    <tr>
      <td>Body</td>
      <td>The payload of Auth0 user properties to update. To learn more, read <a href="https://auth0.com/docs/api/management/v2/users/patch-users-by-id">Update a user</a>  API documentation. </td>
    </tr>
  </tbody>
</table>

### Output object

You can find the expected response and status codes at [Update a user](https://auth0.com/docs/api/management/v2/users/patch-users-by-id#response-messages) API documentation.

## Custom API request

Send a custom API request to Auth0 API endpoints.

<Frame>
  <img alt="Dashboard > Customize > Flows > Integrations > Auth0" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Path
      </td>

      <td>
        The API endpoint absolute pathname.
        <br />( Example: <code>/api/v2/organizations</code> )
        <br /> <b>Note:</b> Some endpoints, for example: <a href="https://auth0.com/docs/api/management/v2/users/get-users-by-id"> Get a user </a>, require URI encoded parameters when not using alphanumeric characters, such as: <code>-</code>, <code>.</code>, <code>\_</code>, or <code>\~</code>, <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-2.3"> characters </a>).
        <br />To do this, you can use the encodeURIComponent function:  <br />`{{ functions.encodeURIComponent(context.user.user_id) }}`
      </td>
    </tr>

    <tr>
      <td>
        Method
      </td>

      <td>
        Available HTTP methods include:

        <ul>
          <li><code>GET</code></li>
          <li><code>POST</code></li>
          <li><code>PUT</code></li>
          <li><code>PATCH</code></li>
          <li><code>DELETE</code></li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>Body</td>
      <td>The body of the request. </td>
    </tr>

    <tr>
      <td>Headers</td>
      <td>The headers of the request. </td>
    </tr>

    <tr>
      <td>URL Params</td>
      <td>The URL parameters. These parameters are automatically URL-encoded. </td>
    </tr>
  </tbody>
</table>

### Output object

Review [Auth0 Management API](https://auth0.com/docs/api/management/v2/introduction) for expected responses and status codes.

## Notifications

## Send email

Send a custom email using your [configured email provider](/docs/customize/email).

<Warning>
  [Email Provider](/docs/customize/email) must be enabled before using this Action.
</Warning>

<Frame>
  <img alt="" />
</Frame>

### Input settings

| Parameter               | Description                                                                                                                                                                      |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Use custom sender email | By default, we will use the sender email you have configured in your customized email provider settings. Enable this option if you want to use a different sender email or name. |
| Recipient email         | The recipient’s email.                                                                                                                                                           |
| Custom variables        | Add custom variables to be inserted in your email template. Once configured, you can reference them using `{{custom_vars.your_variable_key}}`.                                   |
| Subject                 | The email subject. Supports custom variables and Liquid syntax.                                                                                                                  |
| Message                 | The email message is in HTML format, uses Liquid syntax, and supports custom variables.                                                                                          |

<Callout icon="file-lines">
  Subject and Message can use a combination of Liquid syntax with [common variables](https://auth0.com/docs/customize/email/email-templates/supported-liquid-syntax) or custom variables using `{{custom_vars.your_variable_key}}` syntax.

  Use custom variables to pass information between Forms / Flows context and Subject and Message content.
</Callout>

### Output object

| Property | Type    | Description                                                                                                  |
| -------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| success  | Boolean | Indicates if the email was successfully queued to be sent, regardless of whether the delivery failed or not. |

### Output object example

```json theme={null}
{
  "success": true
}
```

## Send SMS

Send a custom SMS using your [configured phone provider](https://auth0.com/docs/customize/phone-messages/configure-phone-messaging-providers).

<Warning>
  [Phone Provider](https://auth0.com/docs/customize/phone-messages/configure-phone-messaging-providers) must be enabled for text message delivery before using this Action.
</Warning>

<Frame>
  <img alt="" />
</Frame>

### Input settings

| Parameter        | Description                                                                                                                                                                              |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| From             | By default, we will use the sender phone number you have configured in your customized phone provider settings. Input a custom value if you want to use a different sender phone number. |
| To               | The recipient’s phone number.                                                                                                                                                            |
| Custom variables | Add custom variables to be inserted in your phone template. Once configured, you can reference them using `{{custom_vars.your_variable_key}}`.                                           |
| Message          | The phone message uses Liquid syntax and supports custom variables.                                                                                                                      |

<Callout icon="file-lines">
  Message can use a combination of Liquid syntax with [common variables](https://auth0.com/docs/customize/email/email-templates/supported-liquid-syntax) or custom variables using `{{custom_vars.your_variable_key}}` syntax.

  Use custom variables to pass information between Forms / Flows context and Message content.
</Callout>

### Output object

| Property | Type    | Description                                                                                                          |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
| success  | Boolean | Indicates if the phone message was successfully queued to be sent, regardless of whether the delivery failed or not. |

### Output object example

```json theme={null}
{
  "success": true
}
```

## Make call

Send a custom voice message using your [configured phone provider](https://auth0.com/docs/customize/phone-messages/configure-phone-messaging-providers).

<Warning>
  [Phone Provider](https://auth0.com/docs/customize/phone-messages/configure-phone-messaging-providers) must be enabled  for voice message delivery before using this Action.
</Warning>

<Frame>
  <img alt="" />
</Frame>

### Input settings

| Parameter        | Description                                                                                                                                                                              |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| From             | By default, we will use the sender phone number you have configured in your customized phone provider settings. Input a custom value if you want to use a different sender phone number. |
| To               | The recipient’s phone number.                                                                                                                                                            |
| Custom variables | Add custom variables to be inserted in your phone template. Once configured, you can reference them using `{{custom_vars.your_variable_key}}`.                                           |
| Message          | The phone message uses Liquid syntax and supports custom variables.                                                                                                                      |

<Callout icon="file-lines">
  Message can use a combination of Liquid syntax with [common variables](https://auth0.com/docs/customize/email/email-templates/supported-liquid-syntax) or custom variables using `{{custom_vars.your_variable_key}}` syntax.

  Use custom variables to pass information between Forms / Flows context and Message content.
</Callout>

### Output object

| Property | Type    | Description                                                                                                          |
| -------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
| success  | Boolean | Indicates if the phone message was successfully queued to be sent, regardless of whether the delivery failed or not. |

### Output object example

```json theme={null}
{
  "success": true
}
```


# Data verification
Source: https://auth0.com/docs/customize/forms/flows/integrations/data-verification

Learn how to configure your data verification flow actions to generate and verify one-time passwords (OTPs), and verify email addresses.

This list of data verification actions allows you to verify emails addresses and to generate and verify one-time passwords.

## Generate one-time password

Generates a numeric code with a validity of 5 minutes that can be sent via email, SMS or any messaging apps.

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Reference value (required)
      </td>

      <td>
        You can bind your generated code to a phone number, email address or any value.
      </td>
    </tr>

    <tr>
      <td>
        Code length (required)
      </td>

      <td>
        The number of digits of the generated code.
      </td>
    </tr>
  </tbody>
</table>

### Output object

<table>
  <thead>
    <tr>
      <th><b>Property</b></th>
      <th><b>Type</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>code</code></td>
      <td>String</td>
      <td>The generated code</td>
    </tr>
  </tbody>
</table>

### Output object example

```json lines theme={null}
{
  "code": "███",
}
```

## Verify one-time password

Verifies if the provided one-time password code is valid or not.

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Reference value (required)
      </td>

      <td>
        Use the same reference value configured in the Generate one-time password action.
      </td>
    </tr>

    <tr>
      <td>
        Code length (required)
      </td>

      <td>
        The number of digits of the generated code.
      </td>
    </tr>
  </tbody>
</table>

### Output object

<table>
  <thead>
    <tr>
      <th><b>Property</b></th>
      <th><b>Type</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>valid</code></td>
      <td>Boolean</td>
      <td>Indicates if the provided code is valid or not returning a <code>true</code> or <code>false</code> value.</td>
    </tr>

    <tr>
      <td>
        <code>result</code>
      </td>

      <td>
        String
      </td>

      <td>
        Returns different result codes based on the provided code:

        <ul>
          <li>
            <code>MISSING:</code>
            The provided code does not exist.
          </li>

          <li>
            <code>EXPIRED:</code> The provided code has expired.
          </li>

          <li>
            <code>VALID:</code> The provided code is valid.
          </li>

          <li>
            <code>UNEQUAL:</code> The provided code is not valid.
          </li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

### Output object examples

```json lines theme={null}
{
  "valid": false,
  "result": "UNEQUAL"
}
```

```json lines theme={null}
{
  "valid": true
}
```

## Verify email address

Performs a number of selected verification rules against a provided email address.

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Email (required)
      </td>

      <td>
        email address to verify.
      </td>
    </tr>

    <tr>
      <td>
        Require MX record
      </td>

      <td>
        Require MX records. When a domain lacks MX records, email servers do not know where to send emails for that domain.
      </td>
    </tr>

    <tr>
      <td>
        Block free email providers
      </td>

      <td>
        Block free email providers like @gmail.com, @hotmail.com, etc.
      </td>
    </tr>

    <tr>
      <td>Block disposable email providers</td>
      <td>Block disposable emails like @mailnator.com, @maildrop.cc, etc.</td>
    </tr>

    <tr>
      <td>Block email account aliases</td>
      <td>Block email with aliases like `jane.doe+alias@gmail.com`</td>
    </tr>

    <tr>
      <td>Allowlist domains</td>
      <td>Allow emails only from approved domains in your list.</td>
    </tr>

    <tr>
      <td>Blocklist domains</td>
      <td>Block specific email domains.</td>
    </tr>
  </tbody>
</table>

### Output object

<table>
  <thead>
    <tr>
      <th><b>Property</b></th>
      <th><b>Type</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>valid</code></td>
      <td>Boolean</td>
      <td>Returns <code>true</code> or <code>false</code> depending on whether or not the email has met the verification rules.</td>
    </tr>

    <tr>
      <td>
        <code>cause</code>
      </td>

      <td>String</td>

      <td>
        If the valid property is

        <code>
          false
        </code>

        , returns a reference of the first rule that the email did not meet:

        <ul>
          <li>
            <code>MISSING\_MX\_RECORD:</code> The email domain does not have MX records.
          </li>

          <li> <code>FREE\_EMAIL:</code> The email domain is a free email provider.</li>
          <li> <code>DISPOSABLE\_EMAIL:</code> The email is a disposable email address.</li>
          <li> <code>BLOCKLISTED:</code> The email domain is included in the Blocklist domains setting.</li>
          <li> <code>NOT\_ALLOWED:</code> The email domain is not included in the Allowlist domains setting.</li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

### Output object example

```json lines theme={null}
{
  "valid": false,
  "cause": "FREE_EMAIL"
}
```

```json lines theme={null}
{
  "valid": true,
  "cause": null
}
```


# HTTP Request
Source: https://auth0.com/docs/customize/forms/flows/integrations/http-request

Learn how to configure your HTTP Request flow actions to send custom requests to external APIs or services.

## Configure your HTTP Vault Connection

Learn how to configure a Vault Connection for your HTTP Request Flow Actions at [HTTP Vault Connection](/docs/customize/forms/vaults/http).

## HTTP Request

The HTTP request action lets you call an external API or service, and process the response.

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Method</td>

      <td>
        The HTTP method. Available values include:

        <ul>
          <li><code>GET</code></li>
          <li><code>POST</code></li>
          <li><code>PUT</code></li>
          <li><code>PATCH</code></li>
          <li><code>DELETE</code></li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>Content type</td>

      <td>
        The <code>Content-Type</code> header. Available values include:

        <ul>
          <li><code>application/json</code></li>
          <li><code>application/x-www-form-urlenconded</code></li>
          <li><code>application/xml</code></li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>Body</td>

      <td>
        The body of the request.
      </td>
    </tr>

    <tr>
      <td>Headers</td>

      <td>
        The headers of the request.
      </td>
    </tr>

    <tr>
      <td>URL params</td>

      <td>
        The URL parameters. These parameters will be automatically URL-encoded.
      </td>
    </tr>

    <tr>
      <td>Enable Basic Auth</td>

      <td>
        Enables authentication with username and password.
      </td>
    </tr>
  </tbody>
</table>

### Output object

<table>
  <thead>
    <tr>
      <th><b>Property</b></th>
      <th><b>Type</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>headers</code></td>

      <td>
        Object
      </td>

      <td>
        The headers of the response.
      </td>
    </tr>

    <tr>
      <td><code>body</code></td>

      <td>
        Object
      </td>

      <td>
        The body of the response.
      </td>
    </tr>

    <tr>
      <td><code>status</code></td>

      <td>
        Number
      </td>

      <td>The status code of the response.</td>
    </tr>

    <tr>
      <td><code>success</code></td>

      <td>
        Boolean
      </td>

      <td>
        Returns <code>true</code> or <code>false</code> based on the <code>status</code> of the response.
      </td>
    </tr>
  </tbody>
</table>

### Output object example

```json lines theme={null}
{
  "headers": {
    ...
  },
  "status": 200,
  "body": {
    ...
  },
  "success": true
}
```


# JSON
Source: https://auth0.com/docs/customize/forms/flows/integrations/json

Learn how to configure your JSON flow actions to create JSON objects, parse JSON and convert JSON to string.

This list of JSON actions allows you to create, parse, and convert JSON to strings.

## Create JSON object

Creates a JSON object. This is especially useful to reuse its content in other actions of the flow.

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Body</td>

      <td>
        The JSON object.
      </td>
    </tr>
  </tbody>
</table>

### Output object

<table>
  <thead>
    <tr>
      <th><b>Property</b></th>
      <th><b>Type</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>result</code></td>
      <td>Object</td>
      <td>The JSON object.</td>
    </tr>
  </tbody>
</table>

### Output object example

```json lines theme={null}
{
	"result": {
		"name": "John Doe"
	}
}
```

## Parse JSON

Parses a JSON object contained in a text string into a JSON object.

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>JSON string (required)</td>

      <td>
        The JSON string.
      </td>
    </tr>
  </tbody>
</table>

### Output object

<table>
  <thead>
    <tr>
      <th><b>Property</b></th>
      <th><b>Type</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>object</code></td>
      <td>Object</td>
      <td>The parsed JSON object.</td>
    </tr>
  </tbody>
</table>

### Output object example

```json lines theme={null}
{
  "object": {
    "name": "John Doe"
  }
}
```

## Convert JSON to string

Converts a JSON object to a string.

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>JSON object (required)</td>

      <td>
        The JSON object that will be serialized to a string.
      </td>
    </tr>
  </tbody>
</table>

### Output object

<table>
  <thead>
    <tr>
      <th><b>Property</b></th>
      <th><b>Type</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>json</code></td>
      <td>String</td>
      <td>The serialized JSON object.</td>
    </tr>
  </tbody>
</table>

### Output object example

```json lines theme={null}
{
  "json": "{\"name\":\"John Doe\"}"
}
```


# JSON Web Token
Source: https://auth0.com/docs/customize/forms/flows/integrations/json-web-token

Learn how to configure your JSON Web Token flow actions to sign, verify or decode JSON Web Tokens.

This list of <Tooltip href="/docs/glossary?term=JSON+Web+Token">JSON Web Token</Tooltip> actions allows you to generate, verify, and decode JWTs in your flows.

## Configure your JWT Vault Connection

Learn how to configure a Vault Connection for your JSON Web Token Flow Actions at [JWT Vault Connection](/docs/customize/forms/vaults/jwt).

## Sign JSON web token

Generates a JSON web token.

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Payload</td>

      <td>
        Data to encode. We recommend to format it according to OpenID standards.
      </td>
    </tr>

    <tr>
      <td>Subject</td>

      <td>
        Identifies the subject of the JWT.
      </td>
    </tr>

    <tr>
      <td>Issuer</td>

      <td>
        Identifies principal that issued the JWT.
      </td>
    </tr>

    <tr>
      <td>Audience</td>

      <td>
        Identifies the recipients that the JWT is intended. For example:  admin.your\_domain.com
      </td>
    </tr>

    <tr>
      <td>Expires in</td>

      <td>
        Identifies the expiration time on and after which the JWT must not be accepted for processing.
      </td>
    </tr>
  </tbody>
</table>

### Output object

<table>
  <thead>
    <tr>
      <th><b>Property</b></th>
      <th><b>Type</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>token</code></td>
      <td>String</td>
      <td>A JSON web token string.</td>
    </tr>
  </tbody>
</table>

### Output object example

```json lines theme={null}
{
  "token": "eyJhbGciOiJIUzI1N..."
}
```

## Decode JSON web token

Decodes a provided JSON web token.

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Token (required)</td>

      <td>
        JSON web token string that will be decoded.
      </td>
    </tr>
  </tbody>
</table>

### Output object

<table>
  <thead>
    <tr>
      <th><b>Property</b></th>
      <th><b>Type</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>payload</code></td>
      <td>object</td>
      <td>The decoded and valid JSON web token content</td>
    </tr>
  </tbody>
</table>

### Output object example

```json lines theme={null}
{
  "header": {
    "alg": "HS256",
    "typ": "JWT"
  },
  "payload": {
    "sub": "1234567890",
    "name": "John Doe",
    "iat": 1516239022
  },
  "signature": "SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
```

## Verify JSON web token

Verifies the JSON web token data, to determine if it remains intact or has been modified, in order to guarantee its authenticity.

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Token (required)</td>

      <td>
        JSON web token string that will be verified.
      </td>
    </tr>

    <tr>
      <td>Issuer</td>

      <td>
        The issuer of the JWT that will be verified.
      </td>
    </tr>

    <tr>
      <td>Audience</td>

      <td>
        The recipient audience of the JWT is intended that will be verified.
      </td>
    </tr>
  </tbody>
</table>

### Output object

<table>
  <thead>
    <tr>
      <th><b>Property</b></th>
      <th><b>Type</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>valid</code></td>
      <td>Boolean</td>
      <td>Returns <code>true</code> or <code>false</code> depending on whether or not the JWT has a valid signature.</td>
    </tr>

    <tr>
      <td><code>cause</code></td>
      <td>String</td>
      <td>If the <code>valid</code> property is <code>false</code> a message is displayed.</td>
    </tr>

    <tr>
      <td><code>payload</code></td>
      <td>Object</td>
      <td>The decoded and valid JSON web token content.</td>
    </tr>
  </tbody>
</table>

### Output object example

```json lines theme={null}
{
  "valid": true,
  "header": {
    "alg": "HS256",
    "typ": "JWT"
  },
  "payload": {
    "sub": "1234567890",
    "name": "Jane Doe",
    "iat": 1516239022
  },
  "signature": "SflKxwRJSMe..."
}
```

```json lines theme={null}
{
  "valid": false,
  "cause": "INVALID_SIGNATURE"
}
```


# Logic
Source: https://auth0.com/docs/customize/forms/flows/integrations/logic

Learn how to configure your logic flow actions to add if/then conditions, store shared variables, show error messages or map values.

This list of logic actions allows you to add form conditional logic, store shared variables, map values, and to display custom error messages.

## If/then condition

Adds a conditional action with True / False branches to customize the behavior of the flow based on input or properties.

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Condition</td>

      <td>
        Customizable conditional action that triggers <code>True</code> / <code>False</code> branches depending on its result. You can use the <code>AND</code> / <code>OR</code> operators to nest different conditions.
      </td>
    </tr>
  </tbody>
</table>

### Output object

<table>
  <thead>
    <tr>
      <th><b>Property</b></th>
      <th><b>Type</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>result</code></td>
      <td>Boolean</td>
      <td>Returns a <code>true</code> or <code>false</code> response based on the condition result.</td>
    </tr>
  </tbody>
</table>

### Output object example

```json lines theme={null}
{
  "result": true
}
```

## Store shared variable

Stores variables in a private state that is available in your form and across its flows.

You can reference these shared variables using `{{vars.*}}`**.** To learn more, read [Variables](/docs/customize/forms/variables).

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Data fields</td>

      <td>
        The variables to be stored in a private state for use in your form and across its flow. Use key/value pairs to add variables.
      </td>
    </tr>
  </tbody>
</table>

## Show error message

Displays a custom error message to the user.

<Warning>
  This flow action terminates the Flow. Any actions inserted after it won't be executed.
</Warning>

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Error message</td>

      <td>
        The error message to be displayed to the user.
      </td>
    </tr>
  </tbody>
</table>

## Input value mapping

Maps an input variable to an output based on its values.

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Input value (required)</td>

      <td>
        The input variable.
      </td>
    </tr>

    <tr>
      <td>Mapping table</td>

      <td>
        Map an input variable value an output.
      </td>
    </tr>

    <tr>
      <td>Default output value</td>

      <td>
        Sets a default output value to be used when no output value is set in the mapping table.
      </td>
    </tr>
  </tbody>
</table>

### Output object

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>result</code></td>
      <td>String</td>
      <td>Returns the value mapped to an input.</td>
    </tr>
  </tbody>
</table>

### Output object example

```json lines theme={null}
{
	"result": "Please enter a valid email address."
}
```


# MailJet
Source: https://auth0.com/docs/customize/forms/flows/integrations/mailjet

Learn how to configure your MailJet flow actions to send emails.

## Configure your MailJet Vault Connection

Learn how to configure a Vault Connection for your MailJet Flow Actions at [MailJet Vault Connection](/docs/customize/forms/vaults/mailjet).

## Send email

Send an email using Mailjet as the email provider.

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Sender name</td>
      <td>The sender's name</td>
    </tr>

    <tr>
      <td>Sender email (required)</td>
      <td>The sender's email</td>
    </tr>

    <tr>
      <td>Recipient name</td>
      <td>The recipient's name</td>
    </tr>

    <tr>
      <td>Recipient email (required)</td>
      <td>The recipient's email</td>
    </tr>

    <tr>
      <td>CC name</td>
      <td>The CC name</td>
    </tr>

    <tr>
      <td>CC email</td>
      <td>The CC email</td>
    </tr>

    <tr>
      <td>Subject</td>
      <td>The email subject</td>
    </tr>

    <tr>
      <td>Email type</td>
      <td>Send email with HTML content or using a saved template (optional)</td>
    </tr>

    <tr>
      <td>Message (required)</td>
      <td>Email message in HTML format or a template (optional).</td>
    </tr>

    <tr>
      <td>Template ID (optional)</td>
      <td>If using a template, its ID can be found at <a href="https://app.mailjet.com/template"> Mailjet's dashboard </a>. </td>
    </tr>

    <tr>
      <td>Custom variables (optional)</td>
      <td>Add custom variables to be inserted in your template. </td>
    </tr>

    <tr>
      <td>Track email activity</td>
      <td>Check box to track email activity.</td>
    </tr>
  </tbody>
</table>

### Output object

You can find the expected response and status codes at [Mailjet's documentation](https://dev.mailjet.com/email/reference/send-emails/).


# SendGrid
Source: https://auth0.com/docs/customize/forms/flows/integrations/sendgrid

Learn how to configure your SendGrid flow actions to send emails.

## Configure your SendGrid Vault Connection

Learn how to configure a Vault Connection for your SendGrid Flow Actions at [SendGrid Vault Connection](/docs/customize/forms/vaults/sendgrid).

## Send email

Send an email using SendGrid as the email provider.

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Sender name</td>
      <td>The sender's name</td>
    </tr>

    <tr>
      <td>Sender email (required)</td>
      <td>The sender's email</td>
    </tr>

    <tr>
      <td>Recipient name</td>
      <td>The recipient's name</td>
    </tr>

    <tr>
      <td>Recipient email (required)</td>
      <td>The recipient's email</td>
    </tr>

    <tr>
      <td>Subject (required)</td>
      <td>The email subject</td>
    </tr>

    <tr>
      <td>Email type (required)</td>
      <td>Send email with HTML content or using a saved template (optional)</td>
    </tr>

    <tr>
      <td>Message (required)</td>
      <td>Email message in HTML format or a template (optional).</td>
    </tr>

    <tr>
      <td>Template ID (optional)</td>
      <td>If using a template, its ID can be found at <a href="https://mc.sendgrid.com/dynamic-templates"> SendGrid dashboard </a>. </td>
    </tr>

    <tr>
      <td>Custom variables (optional)</td>
      <td>Add custom variables to be inserted in your template. </td>
    </tr>
  </tbody>
</table>

### Output object

You can find the expected response and status codes at [SendGrid's documentation](https://www.twilio.com/docs/sendgrid/api-reference/mail-send/mail-send).


# Telegram
Source: https://auth0.com/docs/customize/forms/flows/integrations/telegram

Learn how to configure your Telegram flow actions to send messages.

## Configure your Telegram Vault Connection

Learn how to configure a Vault Connection for your Telegram Flow Actions at [Telegram Vault Connection](/docs/customize/forms/vaults/telegram).

## Send Telegram message

Send a messages to a Telegram chat

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Chat ID (required)</td>
      <td>The Telegram chat ID. To be obtained from <a href="https://core.telegram.org/bots">Telegram’s Bot Father</a>.</td>
    </tr>

    <tr>
      <td>Messages (required)</td>
      <td>The body content of the Telegram message.</td>
    </tr>
  </tbody>
</table>

### Output object

You can find the expected response and status codes at [Telegram's documentation](https://core.telegram.org/method/messages.sendMessage).


# Twilio
Source: https://auth0.com/docs/customize/forms/flows/integrations/twilio

Use the Twilio actions to send SMS and make calls using Twilio.

This list of Twilio actions allows you to send SMS and make calls using Twilio as provider.

## Configure your Twilio Vault Connection

Learn how to configure a Vault Connection for your Twilio Flow Actions at [Twilio Vault Connection](/docs/customize/forms/vaults/twilio).

## Send SMS

Sends an SMS.

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>From (required)</td>
      <td>The name of the sender of the SMS.</td>
    </tr>

    <tr>
      <td>To (required)</td>
      <td>The destination phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164 format</a>.</td>
    </tr>

    <tr>
      <td>Message (required)</td>
      <td>The body content of the SMS.</td>
    </tr>
  </tbody>
</table>

### Output object

You can find all the expected status codes at [Twilio's documentation](https://www.twilio.com/docs/messaging/api/message-resource#message-status-values).

## Make call

Makes a call.

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>From (required)</td>
      <td>Your Twilio phone number. Country code must be included. Example: +18005550175, 1 is the country code for the United States.</td>
    </tr>

    <tr>
      <td>To (required)</td>
      <td>The destination phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164 format</a>.</td>
    </tr>

    <tr>
      <td>
        TwiML payload (required)
      </td>

      <td>
        <p>The TwiML instructions for your voice message.</p> To learn more, read <a href="https://www.twilio.com/docs/voice/twiml">Twilio's TwiML documentation</a>.
      </td>
    </tr>
  </tbody>
</table>

### Output object

You can find all the expected status codes at [Twilio's documentation](https://www.twilio.com/docs/voice/twiml).


# WhatsApp
Source: https://auth0.com/docs/customize/forms/flows/integrations/whatsapp

Learn how to configure your WhatsApp flow actions to send messages.

## Configure your WhatsApp Vault Connection

Learn how to configure a Vault Connection for your WhatsApp Flow Actions at [WhatsApp Vault Connection](/docs/customize/forms/vaults/whatsapp).

## Send message

Sends a message.

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Sender phone ID (required)</td>
      <td>The sender phone ID can be found in the  <a href="https://developers.facebook.com/apps">Facebook Business Manager WhatsAPP settings</a>. Note that it is not a phone number.</td>
    </tr>

    <tr>
      <td>Recipient phone number (required)</td>
      <td>The recipients' phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164 format</a>.</td>
    </tr>

    <tr>
      <td>
        Message type (required)
      </td>

      <td>
        Select from the dropdown menu the message type. They can be:

        <ul>
          <li>Audio</li>
          <li>Contacts</li>
          <li>Document</li>
          <li>Image</li>
          <li>Interactive</li>
          <li>Location</li>
          <li>Sticker</li>
          <li>Template</li>
          <li>Text</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>
        Message object (required)
      </td>

      <td>
        The content of the message object will differ based on the selected message type. To learn more, read  <a href="https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages">Messages</a>.
      </td>
    </tr>
  </tbody>
</table>

### Output object

You can find all expected status codes at [Facebook's documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes).


# XML
Source: https://auth0.com/docs/customize/forms/flows/integrations/xml

Learn how to configure your XML flow actions to convert JSON to XML and XML to JSON.

This list of XML actions allows you to convert JSON objects to XML string and XML string to JSON objects.

## Convert JSON to XML

Converts a JSON object to an XML string.

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>JSON (required)</td>

      <td>
        The JSON object that will be converted to an XML string.
      </td>
    </tr>
  </tbody>
</table>

### Output object

<table>
  <thead>
    <tr>
      <th><b>Property</b></th>
      <th><b>Type</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>xml</code></td>
      <td>String</td>
      <td>The converted XML string.</td>
    </tr>
  </tbody>
</table>

### Output object example

```json lines theme={null}
{
  "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n<name>John Doe</name>"
}
```

## Convert XML to JSON

Converts a XML string to a JSON object.

<Frame>
  <img alt="" />
</Frame>

### Input settings

<table>
  <thead>
    <tr>
      <th><b>Parameter</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>XML (required)</td>

      <td>
        The XML string that will be converted to a JSON object.
      </td>
    </tr>
  </tbody>
</table>

### Output object

<table>
  <thead>
    <tr>
      <th><b>Property</b></th>
      <th><b>Type</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>object</code></td>
      <td>Object</td>
      <td>The converted JSON object.</td>
    </tr>
  </tbody>
</table>

### Output object example

```json lines theme={null}
{
  "object": {
    "name": "John Doe"
  }
}
```

##


# Nodes and components
Source: https://auth0.com/docs/customize/forms/nodes-and-components

Learn about Form nodes and available components.

Forms lets you add nodes and components, such as fields, blocks, and widgets for your users to interact with the form. You can then reference the data input, from components, in your forms and flows.

## Form nodes

There are five types of form nodes: Start, Step, Flow, Router and Ending screen. These nodes have a very specific purpose for the structure of the form.

<Frame>
  <img alt="Dashboard >  Forms > Form Editor" />
</Frame>

## Step node

Step nodes are the visual representation of the form. They can contain any number of components, such as fields, blocks, and widgets where the user can fill in their data.

<Frame>
  <img alt="Dashboard > Foms > Step node" />
</Frame>

### Field components

Fields are UI components where users input their information in Forms.

<Frame>
  <img alt="Dashboard > Forms > Fields" />
</Frame>

#### Field settings

Fields have a number of default settings that you can configure to meet your requirements.

The default field settings are:

<table>
  <thead>
    <tr>
      <th><strong>Settings</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>ID</td>
      <td>The unique id</td>
    </tr>

    <tr>
      <td>Label</td>
      <td>Display or hide a label</td>
    </tr>

    <tr>
      <td>Required</td>
      <td>Input value is required</td>
    </tr>

    <tr>
      <td>Hint text</td>
      <td>Display a hint text</td>
    </tr>

    <tr>
      <td>Placeholder text</td>
      <td>Text visible to the user</td>
    </tr>

    <tr>
      <td>Default value</td>
      <td>Default value visible to the user</td>
    </tr>

    <tr>
      <td>Transient</td>
      <td>Enable or disable data mask</td>
    </tr>
  </tbody>
</table>

#### Field validation rules

<table>
  <thead>
    <tr>
      <th><strong>Settings</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Min. length / Max. length</td>
      <td>Require an input value length.</td>
    </tr>

    <tr>
      <td>Min. value / Max. value</td>
      <td>Require a number value length.</td>
    </tr>
  </tbody>
</table>

#### Available fields in Forms

The available fields with their specific settings and data output types are:

<AccordionGroup>
  <Accordion title="Text field">
    Standard input lets a user enter any string value.

    ##### Text field settings

    The text field setting is:

    <table>
      <thead>
        <tr>
          <th><strong>Settings</strong></th>
          <th><strong>Description</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Multiline</td>
          <td>Enable multi-line input text.</td>
        </tr>
      </tbody>
    </table>

    ##### Text field output value

    The text field output value data type is a `string`.

    ```json lines theme={null}
    {
      "text_field_id": "Auth0"
    }
    ```
  </Accordion>

  <Accordion title="Email field">
    Standard input lets a user enter email string values.

    ##### Email field output value

    The email field output value data type is a `string`.

    ```json lines theme={null}
    {
      "email_field_id": "username@domain.com"
    }
    ```
  </Accordion>

  <Accordion title="Phone field">
    Standard input lets a user enter phone number values.

    ##### Phone field settings

    The phone field settings are:

    <table>
      <thead>
        <tr>
          <th><strong>Settings</strong></th>
          <th><strong>Description</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Country picker</td>
          <td>Enable or disable Country picker. By default, it displays the user’s IP location.</td>
        </tr>

        <tr>
          <td>Filter placeholder text</td>
          <td>Text visible to the user in the country search window.</td>
        </tr>
      </tbody>
    </table>

    ##### Phone field output value

    The phone field output value data type is either a `string` or, if Country picker is enabled, an `object` .

    The phone field output data type value as a `string`:

    ```json lines theme={null}
    {
      "phone_field_id": "8005550175"
    }
    ```

    The phone field output data type value as an `object` :

    ```json lines theme={null}
    {
      "phone_field_id": {
        "national_number": "8005550175",
        "national_format": "(800) 555-0175",
        "international_number": "+18005550175",
        "international_format": "+1 800-555-0175",
        "country_code_iso": "US",
        "country_code_number": "1"
      }
    }
    ```
  </Accordion>

  <Accordion title="Choice field">
    Standard input that lets a user select single or multiple choice values.

    ##### Choice field settings

    The Choice field settings are:

    <table>
      <thead>
        <tr>
          <th><strong>Settings</strong></th>
          <th><strong>Description</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Multiple choice</td>
          <td>Enable several choice options.</td>
        </tr>

        <tr>
          <td>Other option</td>
          <td>Let users enter their own option.</td>
        </tr>

        <tr>
          <td>Advanced > Internal values</td>
          <td>Assign an internal value to each choice option.</td>
        </tr>

        <tr>
          <td>Advanced > Bulk edit</td>
          <td>Bulk edit label and internal choice option values.</td>
        </tr>
      </tbody>
    </table>

    ##### Choice field output value

    The choice field output value data type is either a `string` or, if multiple choice is enabled, as an `array of strings` .

    The choice field output data type  value as a `string`:

    ```json lines theme={null}
    {
      "choice_field_id": "Option A"
    }
    ```

    The choice field output data type value as an  `array of strings`:

    ```json lines theme={null}
    {
      "choice_field_id": ["Option A", "Option B"]
    }
    ```
  </Accordion>

  <Accordion title="Cards field">
    Standard input that lets a user select single or multiple choice image values.

    ##### Cards field settings

    The cards field settings are:

    <table>
      <thead>
        <tr>
          <th><strong>Settings</strong></th>
          <th><strong>Description</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Multiple choice</td>
          <td>Enable several choice options.</td>
        </tr>

        <tr>
          <td>Hide labels</td>
          <td>Hide card labels.</td>
        </tr>

        <tr>
          <td>Advanced > Internal values</td>
          <td>Assign an internal value for each option.</td>
        </tr>
      </tbody>
    </table>

    ##### Cards field output value

    The cards field output value data type is either a `string` or, if multiple choice is enabled, as an `array of strings`.

    The cards field output data type value as a `string`:

    ```json lines theme={null}
    {
      "card_field_id": "Option A"
    }
    ```

    The cards field output data type value as an `array of strings`:

    ```json lines theme={null}
    {
      "card_field_id": ["Option A", "Option B"]
    }
    ```
  </Accordion>

  <Accordion title="URL field">
    Standard input lets a user enter a URL value.

    ##### URL field output value

    The URL field output value data type is a string:

    ```json lines theme={null}
    {
      "url_field_id": "https://auth0.com"
    }
    ```
  </Accordion>

  <Accordion title="Password field">
    Standard input that lets a user enter a password or a secret value.

    ##### Password field settings

    The password field settings are:

    <table>
      <thead>
        <tr>
          <th><strong>Settings</strong></th>
          <th><strong>Description</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Require complex password</td>
          <td>Passwords must contain an uppercase, a lowercase, a symbol and a number.</td>
        </tr>

        <tr>
          <td>Enforce NIST guidelines</td>
          <td>The password cannot be less than 8 characters, passwords obtained from previous breach corpuses, dictionary words, repetitive or sequential characters, content-specific words.</td>
        </tr>

        <tr>
          <td>Add strength meter</td>
          <td>A graphical meter with a red, yellow and green scale is displayed under the password field to show the strength of the password input.</td>
        </tr>

        <tr>
          <td>Hash</td>
          <td>Select an algorithm to hash the input value directly in the browser.</td>
        </tr>
      </tbody>
    </table>

    ##### Password field output value

    The password field output value data type is a masked `string`:

    ```json lines theme={null}
    {
      "password_field_id": "███"
    }
    ```
  </Accordion>

  <Accordion title="Payment field">
    Standard input that lets a user enter payment information using a payment provider. Payments are processed before the Ending node.

    ##### Payment field settings

    The payment field settings are:

    <table>
      <thead>
        <tr>
          <th><strong>Settings</strong></th>
          <th><strong>Description</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Payment type</td>
          <td>Select either a one-off (Charge) or recurring (Subscription) payments.</td>
        </tr>

        <tr>
          <td>Amount</td>
          <td>Specify the amount for a one-off (Charge) payment.</td>
        </tr>

        <tr>
          <td>Currency</td>
          <td>Specify the currency for a one- off ( Charge) payment.</td>
        </tr>

        <tr>
          <td>Subscription action</td>
          <td>Select either to create or update an existing subscription.</td>
        </tr>

        <tr>
          <td>Customer action</td>
          <td>Select either to create or update an existing customer.</td>
        </tr>

        <tr>
          <td>Display options</td>
          <td>Display and edit Card number, Expiration date, and Security code labels and Trustmarks.</td>
        </tr>
      </tbody>
    </table>

    ##### Payment field output value

    The payment field output value data type is either a string or an object  for after submission flows.

    The payment field output value data type as a `string`:

    ```json lines theme={null}
    {
      "payment_field_id": "pm_1P19e..."
    }
    ```

    The payment field output value data type for subscriptions as an `object` :

    ```json lines theme={null}
    {
      "payment_field_id": {
        "payment_method_id": "pm_1P19e...",
        "customer_id": "cus_PqrM...",
        "price_ids": [
          "price_1ONHR..."
        ],
        "subscription_id": "sub_1P1A...",
        "payment_intent_id": "pi_3P19e5..."
      }
    }
    ```

    The payment field output value data type for charge as an `object` :

    ```json lines theme={null}
    {
      "payment_field_id": {
        "payment_method_id": "pm_1P19e...",
        "customer_id": "cus_PqrM...",
        "amount": 100,
        "payment_intent_id": "pi_3P19e5..."
      }
    }
    ```
  </Accordion>

  <Accordion title="Legal field">
    Standard input that adds legal text and a check input.

    ##### Legal field output value

    The legal field output value data type is a `boolean`.

    ```json lines theme={null}
    {
      "legal_field_id": true
    }
    ```
  </Accordion>

  <Accordion title="Dropdown field">
    Standard input that lets a user select single or multiple dropdown choice values.

    ##### Dropdown field settings

    The dropdown field settings are:

    <table>
      <thead>
        <tr>
          <th><strong>Settings</strong></th>
          <th><strong>Description</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Multiple selector</td>
          <td>Enable several choice options.</td>
        </tr>

        <tr>
          <td>Advanced > Internal values</td>
          <td>Assign an internal value for each option.</td>
        </tr>

        <tr>
          <td>Advanced > Bulk edit</td>
          <td>Bulk edit label and internal values.</td>
        </tr>
      </tbody>
    </table>

    ##### Dropdown field output value

    The dropdown field output value data type is either a `string` or, if multiple choice is enabled, as an `array of strings` .

    The dropdown field output data type  value as a `string`:

    ```json lines theme={null}
    {
      "dropdown_field_id": "Option A"
    }
    ```

    The dropdown field output data type value as an `array of strings`:

    ```json lines theme={null}
    {
      "dropdown_field_id": ["Option A", "Option B"]
    }
    ```
  </Accordion>

  <Accordion title="Number field">
    Standard input that lets a user enter number values.

    ##### Number field output value

    The number field output value data type is a `number`.

    ```json lines theme={null}
    {
      "number_field_id": 123
    }
    ```
  </Accordion>

  <Accordion title="Date / Time field">
    Standard input that lets a user enter either a date or time values.

    ##### Date / Time field settings

    The date/time field settings include:

    <table>
      <thead>
        <tr>
          <th><strong>Key</strong></th>
          <th><strong>Description</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Format</td>
          <td>Select either Date or Time format.</td>
        </tr>
      </tbody>
    </table>

    ##### Date / Time field output value

    The date/time field output data type value for date is a `string`:

    ```json lines theme={null}
    {
      "date_time_field_id": "2023-04-11"
    }
    ```

    The date/time field output data type value for time is a `string`:

    ```json lines theme={null}
    {
      "date_time_field_id": "23:15"
    }
    ```
  </Accordion>

  <Accordion title="Boolean field">
    Standard input that lets a user enter true or false values.

    ##### Boolean field output value

    The boolean field output value data type is a boolean.

    ```json lines theme={null}
    {
      "boolean_field_id": true
    }
    ```
  </Accordion>

  <Accordion title="Custom field">
    Standard field that you can customize to create your own field.

    ##### Custom field settings

    The custom field setting are:

    <table>
      <thead>
        <tr>
          <th><strong>Settings</strong></th>
          <th><strong>Description</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Params</td>
          <td>Add key-value pairs to reference in the custom field source code.</td>
        </tr>

        <tr>
          <td>Source code</td>
          <td>Add your Javascript code to the custom field.</td>
        </tr>

        <tr>
          <td>JSON Schema</td>
          <td>By default, the custom field accepts any value format. However, you can use JSON Schema to validate values.</td>
        </tr>
      </tbody>
    </table>

    To learn more, read [Custom Field Components for Forms](/docs/customize/forms/custom-field-components).
  </Accordion>
</AccordionGroup>

### Blocks components

Blocks are UI components that add functionality to your forms but do not gather user information.

<Frame>
  <img alt="Dashboard > Forms > Components > Blocks" />
</Frame>

#### Available blocks in Forms

The available blocks are:

<AccordionGroup>
  <Accordion title="Next button block">
    A button that lets users continue to the next form node.

    <Callout icon="file-lines">
      * Before continuing, field validation rules are applied and validated on the client-side and server-side. If field validation rules fail, an error message is displayed for the user to verify.
      * If the next node is a flow node, a spinner loader is displayed until the flow completes. If the flow fails or returns a custom error message, an error message is displayed.
    </Callout>
  </Accordion>

  <Accordion title="Previous button block">
    A button that lets users go to the previous step node.

    <Callout icon="file-lines">
      If a user selects the previous button, field validation rules are re-run again even if no change to input data is done before continuing.
    </Callout>
  </Accordion>

  <Accordion title="Jump button block">
    A button that lets users skip the current step and directly jumps to the destination node.

    <Callout icon="file-lines">
      When skipping the current step, we won't validate and neither collect any filled out information of the current step.
    </Callout>
  </Accordion>

  <Accordion title="Resend button block">
    A component that lets users re-run a flow to generate and send a new OTP code

    <Callout icon="file-lines">
      if a user selects the resend button, the associated flow will generate and send a new OTP code.
    </Callout>

    <table>
      <thead>
        <tr>
          <th><strong>Settings</strong></th>
          <th><strong>Description</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Text alignment</td>
          <td>Select text alignment, left, center, or right</td>
        </tr>

        <tr>
          <td>Text</td>
          <td>Default text displayed when users select the resend button</td>
        </tr>

        <tr>
          <td>Button text</td>
          <td>Button text</td>
        </tr>

        <tr>
          <td>Waiting text</td>
          <td>Text displayed when users have selected the resend button. Replaces <code>Text</code> and the <code>Button text</code> settings.  Use the `“{{remaining_seconds}}”` variable to dynamically display the remaining number of seconds until the send button is enabled again.  For example: “Resend in `{{remaining_seconds}}` seconds”.</td>
        </tr>

        <tr>
          <td>Flow</td>
          <td>Flow executed after the user selects the resend button.</td>
        </tr>

        <tr>
          <td>Max attempts</td>
          <td>The maximum number of attempts the user can select the resend button</td>
        </tr>

        <tr>
          <td>Waiting time</td>
          <td>The waiting time between attempts in seconds.</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Rich text block">
    A rich text block to personalize the step node with additional information.
  </Accordion>

  <Accordion title="Divider block">
    A line to divide different sections of the step node. It can contain a small text.
  </Accordion>

  <Accordion title="HTML block">
    A HTML block to create your custom UI.
  </Accordion>

  <Accordion title="Image block">
    An image block to personalize the step adding images.
  </Accordion>
</AccordionGroup>

### Widgets components

Widgets are pre-built components, with third-party integrations, that add client-side and server-side logic to your forms.

<Frame>
  <img alt="Dashboard > Forms > Components > Widget" />
</Frame>

#### Available widgets in Forms

The available widget is:

<AccordionGroup>
  <Accordion title="Google Address Widget">
    A widget that lets a user enter and validate their address.

    ##### Google Address widget settings

    The Google Address widget settings include:

    <table>
      <thead>
        <tr>
          <th><strong>Settings</strong></th>
          <th><strong>Description</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>API key</td>
          <td>Requires a Google Maps API key to authenticate requests.</td>
        </tr>
      </tbody>
    </table>

    ##### Google Address widget output value

    The Google Address widget output value data type is an `object`.

    ```json lines theme={null}
    {
      "google_address_widget_id": {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [
            -73.9654415,
            40.8054491
          ]
        },
        "properties": {
          "geocoding": {
            "type": "house",
            "housenumber": "2880",
            "street": "Broadway",
            "city": "New York",
            "county": "New York County",
            "state": "New York",
            "country": "United States",
            "postcode": "10025"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Google reCAPTCHA">
    A widget that helps protect your website from spam and abuse by verifying that a user is a human and not a bot.

    The widget supports:

    * Score-based (v3)
    * Challenge (v2)

      * Invisible reCAPTCHA badge

    Differences between `v2` and `v3`:

    * `v2` requires user interaction with visible challenges, such as clicking a checkbox or solving puzzles.
    * `v3` runs in the background and provides a score based on user behavior, without requiring user interaction. When using this version, make sure to implement additional business logic to handle the score and determine if further action is needed.

    ##### Google reCAPTCHA widget settings

    The Google reCAPTCHA widget settings include:

    <table>
      <thead>
        <tr>
          <th><strong>Settings</strong></th>
          <th><strong>Description</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Site key</td>
          <td>The public site key used to initialize the reCAPTCHA on your website. You can create it in <a href="https://www.google.com/recaptcha/admin/create">Google reCAPTCHA console</a> or your Google Cloud Platform project.</td>
        </tr>

        <tr>
          <td>Secret key</td>
          <td>The secret key used to communicate securely with the reCAPTCHA service server-side. You can create it in <a href="https://www.google.com/recaptcha/admin/create">Google reCAPTCHA console</a> or your Google Cloud Platform project.</td>
        </tr>
      </tbody>
    </table>

    ##### Google reCAPTCHA output value

    The Google reCAPTCHA widget output value data type is an `object`.

    Example of `v2` response:

    ```json lines theme={null}
    {
      "recaptcha_widget_id": {
        "success": true,
        "challenge_ts": "2025-03-26T11:22:18Z",
        "hostname": "auth.example.com"
      }
    }
    ```

    Example of `v3` response:

    ```json lines theme={null}
    {
      "recaptcha_widget_id": {
        "success": true,
        "challenge_ts": "2025-03-26T11:22:18Z",
        "hostname": "auth.example.com",
        "score": 0.9
      }
    }
    ```
  </Accordion>

  <Accordion title="Verifiable Credentials">
    A widget that lets a user verify their identity using verifiable credentials stored in their digital wallet.

    ##### Verifiable Credentials widget settings

    The Verifiable Credentials widget settings include:

    <table>
      <thead>
        <tr>
          <th><strong>Settings</strong></th>
          <th><strong>Description</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>URL</td>
          <td>The URL value used to generate the QR code. This value is returned in the <code>engagement</code> property of the verification request.</td>
        </tr>

        <tr>
          <td>Link text</td>
          <td>Alternative text that will be displayed for users who cannot scan the QR code and prefer to open the link directly on their device.</td>
        </tr>

        <tr>
          <td>Size</td>
          <td>The size of the QR code.</td>
        </tr>

        <tr>
          <td>Public token</td>
          <td>The access token required to consume the polling endpoint. Please ensure the token is generated with only the <code>read:verification\_request</code> scope to avoid exposing access to other resources.</td>
        </tr>

        <tr>
          <td>Verification ID</td>
          <td>The verification ID generated when you start the verification request.</td>
        </tr>

        <tr>
          <td>Maximum waiting time</td>
          <td>The maximum amount of time to wait for the verification process to complete. Once the set time is reached, polling will stop and an error will be thrown, regardless of the verification status.</td>
        </tr>
      </tbody>
    </table>

    ##### Verifiable Credentials output value

    The Verifiable Credentials widget output value data type is an `object`.

    ```json lines theme={null}
    {
      "verifiable_credentials_widget_id": {
        "state": "honored",
        "reason": "...", // The reason field contains additional information (if available) regarding the state of the verification request. 
        "presentation": {} // The presentation contains the claims provided by the wallet in response to the presentation definition.
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Router node

Router nodes let you add rules to create conditional logic jumps between nodes.

By default, a router node has a single pass-through rule named **Default Case** that connects to other nodes. You can add additional rules based on a set of conditions that a variable must meet to then connect to other nodes. To learn more, read [Router.](/docs/customize/forms/routers)

<Frame>
  <img alt="Dashboard > Forms > Routers " />
</Frame>

## Flow node

Flow nodes let you add and create custom logic and integration flows to your forms. To learn more, read [Flows.](/docs/customize/forms/flows)

<Frame>
  <img alt="Dashboard > Forms > Flow" />
</Frame>

<Frame>
  <img alt="Dashboard > Forms > Flow > Editor" />
</Frame>

## Start node

Start nodes are not visible to the user. It is where you can configure hidden field variables, such as user attributes when [rendering a form with an Action.](/docs/customize/forms/render)

<Frame>
  <img alt="Dashboard > Forms > Start node" />
</Frame>

## Ending screen node

Every form has an Ending screen node. By default this node resumes the authentication flow and this is where you can configure an After submission flow.

<Frame>
  <img alt="Dashboard > Forms > Ending screen node" />
</Frame>


# Render Forms using Actions
Source: https://auth0.com/docs/customize/forms/render

Learn how you can render Forms using Actions.

Once you create a form, you can render it with [Actions](/docs/customize/actions) using the `api.prompt.render()` method:

```javascript lines theme={null}
// Example using the post-login trigger

exports.onExecutePostLogin = async (event, api) => {
  api.prompt.render(':form_id');
}

exports.onContinuePostLogin = async (event, api) => {
  // Add your logic after completing the form
}
```

Replace form\_id with the ID of the Form. You can locate the ID in the URL of the Form, for example:  `ap_pUMG...` or select it from the Form editor **Render** tab.
In the [Actions Code editor](/docs/customize/actions/write-your-first-action#create-an-action), you can define the business logic to decide when and how to render the Form.

```javascript lines theme={null}
exports.onExecutePostLogin = async (event, api) => {

  // Only render the form if user is missing company_name metadata
  if (!event.user.user_metadata.company_name) {
    api.prompt.render(':form_id');
  }
}

exports.onContinuePostLogin = async (event, api) => {
  // Add your logic after completing the form
}
```

To learn more these objects, review:

* [Event Object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object): Learn about the Event objects and properties.
* [API object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object): Learn about the API objects and methods.

## Populate values for existing fields and hidden fields (client-side)

You can populate values for existing fields and hidden fields using the `fields` property as a second argument in your render method.

In the example below, the value `Jane` populates `first_name` field.

```javascript lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  api.prompt.render(':form_id', {
    fields: {
      first_name: 'Jane',
    }
  });
}

exports.onContinuePostLogin = async (event, api) => {
  // Add your logic after completing the form
}
```

<Warning>
  Do not populate sensitive information, populated values are exposed to the browser (client-side).
</Warning>

<Callout icon="file-lines">
  Make sure that the field `ID` referenced in the second argument is available client-side in your [nodes and components](/docs/customize/forms/nodes-and-components); otherwise, the value will not populate.
</Callout>

## Inject custom data with shared variables (server-side)

You can inject server-side variables using the `vars` property as a second argument in your render method. This can be used to inject sensitive information without exposing it to the client-side.

In the example below, the value `123456789` populates the variable `external_user_id`.

```javascript lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  api.prompt.render(':form_id', {
    vars: {
      external_user_id: '123456789',
    }
  });
}

exports.onContinuePostLogin = async (event, api) => {
  // Add your logic after completing the form
}
```

<Callout icon="file-lines">
  Shared variables `{{vars.*}}` do not have data type restrictions.

  Shared variables `{{vars.*}}` are always automatically masked.

  Unlike when populating `{{fields.*}}` variables, the `{{vars.*}}` property does not need to exist in your form before injecting values.

  You can use the `{{vars.*}}` property to reference shared variables in your Forms and its linked Flows. To learn more, read [Variables](/docs/customize/forms/variables).
</Callout>

## Fields and shared variables data in Actions

Fields and shared variables data collected, in your forms, is automatically available with the `event.prompt` in the resume function of the current action:

* The `id` property, with the prompt ID you're rendering.
* The `fields` object, which contains all your fields and hidden fields data.
* The `vars` object, which contains all your shared variables data.

<Accordion title="Example of event.prompt object">
  ```json lines theme={null}
  {
    "id": "ap_fuVuFiiQWN3mTEujWTy966",
    "fields": {
      "first_name": "Jane",
      "company_name": "Okta"
    },
    "vars": {
      "external_crm_uuid": "f8f32e6f-2329-49bd-bf21-fa8b0bea2652",
      "api_hostname": "api.example.com"
    }
  }
  ```
</Accordion>

In the example below, the `api.user.setUserMetadata` populates the `user_metadata` `company_name` attribute with the `event.prompt.fields.company_name` property that was collected from your form.

```javascript lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  api.prompt.render(':form_id');
}

exports.onContinuePostLogin = async (event, api) => {
  api.user.setUserMetadata('company_name', event.prompt.fields.company_name);
}
```

## Restrictions and limitations

* You cannot [redirect](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/redirect-with-actions) a user and render a form in the same Action. If you need to use both, consider using different Actions.
* You can only render one form per Action. If you need to render more than one form, you need to render the forms in different Actions.
* The `fields` property size limit is 24 KB.
* The `api.prompt.render()` method is available in the following triggers:

  * [post-login](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object)
  * [post-challenge](/docs/customize/actions/explore-triggers/password-reset-triggers/post-challenge-trigger/post-challenge-api-object)


# Resources: Templates
Source: https://auth0.com/docs/customize/forms/resource-template-forms





# Routers
Source: https://auth0.com/docs/customize/forms/routers

Describes how to use Router nodes with Forms.

With Router nodes, you can add rules to Forms to create conditional logic jumps that redirect users between nodes. For example, a rule condition can be defined for a specific user\_metadata attribute to route  a user to a specific step node or flow node.

* The router node automatically adds a Default case rule. If no rule conditions are met, the journey continues to the linked node.
* Rules are evaluated in the order placed in the router. When a rule condition is met, the journey continues to the linked node, and no other rule conditions are evaluated.
* You can add up to 10 rule conditions to the router node.

<Frame>
  <img alt="Dashboard > Forms > Routers " />
</Frame>

## Add a router rule

To add a rule condition, follow these steps:

1. From the Form editor, select a Router node to open its settings.
2. Select **+ New Rule**.
3. Expand the newly created rule.
4. To label the rule, add an **Alias**.
5. Add a variable using the **+** icon.
6. Select the rule operator for the variable.
7. Add the value or variable the rule must meet.
8. Link the new rule to the corresponding step or flow node.
9. Select **Publish** to save.

<Callout icon="file-lines">
  * We recommend you define a rule alias to easily identify each rule in the router node.
  * You can select from a number of rule operators to evaluate operands. For example, you can set first\_name `is equal to` Jane.
  * Operands can be static values or variables.
  * A rule can have `AND` and `OR` operators for further conditional logic evaluation.
  * After adding  a rule, make sure you link it to its desired node.
</Callout>

## Available rule operators

The rule operators are:

* `is greater than`
* `is greater or equal than`
* `is less than`
* `is less than or equal`
* `is equal to`
* `is different to`
* `includes`
* `does not include`
* `starts with`
* `ends with`
* `exists`
* `does not exist`
* `is null`
* `is not null`
* `has not value`
* `is true`
* `is false`


# Variables and helper functions
Source: https://auth0.com/docs/customize/forms/variables

Learn how to use variables in Forms for Actions.

Variables allow you to access data contained in Forms and Flows to create custom business logic and automations.

Some basic considerations to using variables are:

* Variables are surrounded by curly brackets `{{ variable }}`.
* If a variable doesn't exist or can't be resolved, it has the same effect as an `undefined` variable.
* You can use nullish operators to handle `null` or `undefined` variables, for example:`{{fields.foo ?? fields.bar}}`.

## Available variables

You can use different types of variables to reference and transform data you gather from customers with Forms and Flows.

<table>
  <thead>
    <tr>
      <th><strong>Variable</strong></th>
      <th><strong>Syntax</strong></th>
      <th><strong>Where</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Context</td>

      <td>
        `{{context.*}}`
      </td>

      <td>Forms / Flows</td>
      <td>Reference context data of the current transaction</td>
    </tr>

    <tr>
      <td>Form fields</td>

      <td>
        `{{fields.*}}`
      </td>

      <td>Forms / Flows</td>
      <td>Reference data from your form fields and hidden fields</td>
    </tr>

    <tr>
      <td>Shared variables</td>

      <td>
        `{{vars.*}}`
      </td>

      <td>Forms / Flows</td>
      <td>Reference data stored as shared variables</td>
    </tr>

    <tr>
      <td>Flow actions output</td>

      <td>
        `{{actions.*}}`
      </td>

      <td>Flows</td>
      <td>Reference data from the output response of previous flow actions</td>
    </tr>

    <tr>
      <td>Helper functions</td>

      <td>
        `{{functions.*}}`
      </td>

      <td>Forms / Flows</td>
      <td>Helper functions to transform data</td>
    </tr>
  </tbody>
</table>

### Context variables

Forms and flows automatically inherit context variables from the current transaction. You can access the following context variables:

* The `user` object, with access to the following properties:

  * `user.user_id`
  * `user.username`
  * `user.name`
  * `user.given_name`
  * `user.family_name`
  * `user.nickname`
  * `user.email`
  * `user.email_verified`
  * `user.phone_number`
  * `user.phone_verified`
  * `user.picture`
  * `user.user_metadata`
  * `user.app_metadata`
  * `user.created_at`
  * `user.updated_at`
  * `user.last_password_reset`
  * `user.identities`
* The `organization` object, with access to the following properties:

  * `organization.id`
  * `organization.name`
  * `organization.display_name`
  * `organization.metadata`
* The `client` object, with access to the following properties:

  * `client.client_id`
  * `client.name`
* The `tenant` object, with access to the following property:

  * `tenant.name`
* The `transaction` object, with access to the following property:

  * `transaction.state`
* The `custom_domain` object, with access to the following property:

  * `custome_domain.domain`
  * `custome_domain.domain_metadata`

<Accordion title="Example of context object">
  ```json lines expandable theme={null}
  {
    "user": {
      "user_id": "auth0|658409...",
      "name": "ana@travel0.com",
      "nickname": "ana",
      "email": "ana@travel0.com",
      "email_verified": true,
      "picture": "https://s.gravatar.com/avatar/8eb1b522f6...",
      "user_metadata": {},
      "app_metadata": {},
      "created_at": "2023-12-21T09:46:40.487Z",
      "updated_at": "2024-05-07T10:44:26.271Z",
      "last_password_reset": "2023-12-21T09:49:08.932Z",
      "identities": [
        {
          "user_id": "6584...",
          "isSocial": false,
          "provider": "auth0",
          "connection": "Username-Password-Authentication"
        }
      ]
    },
    "client": {
      "client_id": "xpeg5...",
      "name": "My App"
    },
    "tenant": {
      "name": "tenant-testing"
    },
    "transaction": {
      "state": "hKFo2SBId2M0..."
    },
    "custom_domain": {
      "domain": "example.com",
      "domain_metadata": {
        "key": "value"
      }
    }
  }
  ```
</Accordion>

For example:  `{{context.user.user_id}}` references the `user_id` of the `user` object.

<Frame>
  <img alt="Dashboard > Forms > Flows" />
</Frame>

### Form fields variables

Field variables contain data collected from the user from input fields in the form and data from hidden fields. The data of each field varies depending on the field type. For example: `{{fields.first_name}}` references the input value of a field with the ID `first_name`.

<Frame>
  <img alt="Dashboard > Actions > Forms > Form" />
</Frame>

### Flow output actions variables

When a flow action is executed, it generates an output object response that can be referenced in subsequent actions. For example: `{{actions.generate_otp.code}}` references the output code of the action with ID `generate_otp`.

<Frame>
  <img alt="Dashboard > Actions > Forms > Flows" />
</Frame>

### Shared variables

You can store variables to be shared with subsequent flows or even with form components in the same transaction. Shared variables are ephemeral and are associated with a specific form journey. Their values cannot be accessed outside of that journey. For example: `{{vars.external_id}}` references the value of a shared variable with ID `external_id`.

<Frame>
  <img alt="Dashboard > Actions > Forms > Flows" />
</Frame>

<Warning>
  Shared variables:

  * are internal (server-side) and not exposed to the browser (client-side).
  * can be resolved and exposed to the browser if you referenced a shared variable in the form component.
  * might have sensitive information, so take care when you access shared variable to avoid any unnecessary or unintentional exposure.
</Warning>

### Helper functions

Helper functions let you transform data and perform simple operations. For example: `{{functions.toString(fields.privacy_policies)}}` transform the value of the field with ID `privacy_policies` using the `toString()` function.

<Frame>
  <img alt="Dashboard > Actions > Forms > Flows" />
</Frame>

The available helper functions are:

<table>
  <thead>
    <tr>
      <th><strong>Function</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Example</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>toArray(value)</code></td>
      <td>Converts value to an array.</td>

      <td>
        `{{ functions.toArray('abc') }} // ['abc']`
      </td>
    </tr>

    <tr>
      <td><code>toBoolean(value)</code></td>
      <td>Converts value to a boolean value.</td>

      <td>
        `{{ functions.toBoolean(1) }} // true&lt;br /&gt;&lt;br /&gt;\{\{ functions.toBoolean(0) }} // false`
      </td>
    </tr>

    <tr>
      <td><code>length(value)</code></td>
      <td>Returns the length of the parameter value.</td>

      <td>
        `{{ functions.length('auth0') }} // 5`
      </td>
    </tr>

    <tr>
      <td><code>mask(value)</code></td>
      <td>Masks a value to avoid be exposed in Executions.</td>

      <td>
        `{{ functions.mask('my_awesome_secret') }} // ███`
      </td>
    </tr>

    <tr>
      <td><code>toNumber(value)</code></td>
      <td>Converts value to a number.</td>

      <td>
        `{{ functions.toNumber('123') }} // 123`
      </td>
    </tr>

    <tr>
      <td><code>random(min, max, \[boolean])</code></td>
      <td>Returns a random number between the inclusive min and max.</td>

      <td>
        `{{ functions.random(0, 6) }} // 4 &lt;br /&gt;&lt;br /&gt;\{\{ functions.random(0, 6, true) }} // 3.8523497...`
      </td>
    </tr>

    <tr>
      <td><code>slice(value, start, end)</code></td>
      <td>Returns a section of a value array or string between the start and end indexes.</td>

      <td>
        `{{ functions.slice( 'example', 3, 5) }} // 'mp'`
      </td>
    </tr>

    <tr>
      <td><code>toString(value)</code></td>
      <td>Converts value to a string.</td>

      <td>
        `{{ functions.toString(123) }} // '123'`
      </td>
    </tr>

    <tr>
      <td><code>substring(value, start, end)</code></td>
      <td>Returns a section of a value between the start and end indexes. Read about the <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substring#differences_between_substring_and_slice">differences of slice and substring functions</a></td>

      <td>
        `{{ functions.substring( 'example’', 3, 5) }} // 'mp'`
      </td>
    </tr>

    <tr>
      <td><code>toTimestamp()</code></td>
      <td>Returns the current UNIX timestamp.</td>

      <td>
        `{{ functions.toTimestamp() }} // 1628761483`
      </td>
    </tr>

    <tr>
      <td><code>toTimestamp(date)</code></td>
      <td>Returns the provided date in UNIX time.</td>

      <td>
        `{{ functions.toTimestamp('2021-04-30T10:02:50.876Z') }} // 1619776970`
      </td>
    </tr>

    <tr>
      <td><code>toTimestamp(date)</code></td>
      <td>Returns the provided date in UNIX time.</td>

      <td>
        `{{ functions.toTimestamp('2021-04-30T10:02:50.876Z') }} // 1619776970`
      </td>
    </tr>

    <tr>
      <td><code>replaceAll(value, string, replacement)</code></td>
      <td>Returns a new string with all matches of a pattern replaced by a replacement.</td>

      <td>
        `{{ functions.replaceAll('2021-04-30', '-', '/') }} // 2021/04/30`
      </td>
    </tr>

    <tr>
      <td><code>replace(value, string, replacement)</code></td>
      <td>Returns a new string with all matches of a pattern replaced by a replacement. If pattern is a string, only the first occurence will be replaced.</td>

      <td>
        `{{ functions.replace('2021-04-30', '-', '/') }} // 2021/04-30`
      </td>
    </tr>

    <tr>
      <td><code>split(value, separator, limit?)</code></td>
      <td>Returns an ordered list of substrings divided by the separator.</td>

      <td>
        `{{ functions.split('2021-04-30', '-') }} // ['2021', '04', '30']`
      </td>
    </tr>

    <tr>
      <td><code>now()</code></td>
      <td>Returns the current date in ISO 8601 format.</td>

      <td>
        `{{ functions.now() }} // 2021-04-30T10:31:28.576Z`
      </td>
    </tr>

    <tr>
      <td><code>includes(collection, item, fromIndex?)</code></td>
      <td>Returns whether an array includes a certain value among its entries.</td>

      <td>
        `{{ functions.includes(['auth0', 'identity', 'authentication'], 'identity') }} // true`
      </td>
    </tr>

    <tr>
      <td><code>indexOf(collection, item, fromIndex?)</code></td>
      <td>Returns the first index at which a given element can be found in the array, or -1 if it is not present.</td>

      <td>
        `{{ functions.indexOf(['auth0', 'identity', 'authentication'], 'identity') }} // 1`
      </td>
    </tr>

    <tr>
      <td><code>merge(base, value)</code></td>
      <td>Returns a merged array, object or concatenates a string depending on the base data type.</td>

      <td>
        `{{ functions.merge(['auth0', 'identity'], ['authentication']) }} // ['auth0', 'identity', 'authentication']`
      </td>
    </tr>

    <tr>
      <td><code>md5(value)</code></td>
      <td>Returns a MD5 hashed value.</td>

      <td>
        `{{ functions.md5('auth0') }} // 7bbb597...`
      </td>
    </tr>

    <tr>
      <td><code>sha1(value)</code></td>
      <td>Returns a SHA1 hashed value.</td>

      <td>
        `{{ functions.sha1('auth0') }} // b4ec5339...`
      </td>
    </tr>

    <tr>
      <td><code>sha256(value)</code></td>
      <td>Returns a SHA256 hashed value.</td>

      <td>
        `{{ functions.sha256('auth0') }} // d9082bdc...`
      </td>
    </tr>

    <tr>
      <td><code>sha512(value)</code></td>
      <td>Returns a SHA512 hashed value.</td>

      <td>
        `{{ functions.sha512('auth0') }} // c0d588069d...`
      </td>
    </tr>

    <tr>
      <td><code>uuid()</code></td>
      <td>Returns a random v4 UUID.</td>

      <td>
        `{{ functions.uuid() }} // 36b8f84d-df4e-4d49-b662-bcde71a8764`
      </td>
    </tr>
  </tbody>
</table>

## Variables best practices

### Use meaningful IDs

When you add a Form field or a Flow action, the ID is automatically generated.

Update the ID to a more descriptive value so you can identify the information it contains. For example, if you create a Form field that stores the user’s first name, update the ID to `first_name`.

### Be mindful when updating existing IDs

If a variable is already in use and you need to modify the ID, identify where you have referenced it and update the ID accordingly to avoid undefined or empty values.

### Check Flow executions

If you see an unexpected variable value, use the [**Executions**](/docs/customize/forms/flows/flow-execution-and-debugger) view to troubleshoot the variable.

### Use the autocomplete menu

The autocomplete menu helps you locate and properly reference existing variables.

<Frame>
  <img alt="Dashboard > Actions > Forms > Flows" />
</Frame>

<Frame>
  <img alt="Dashboard > Actions > Forms > Form" />
</Frame>


# Vaults
Source: https://auth0.com/docs/customize/forms/vaults

Describes how to use the Vault of Forms for Actions.

The vault lets you securely store secrets or common settings (for example: API keys, <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip>, <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip>) to authenticate requests with external services or integrations as vault connections.

<Callout icon="file-lines">
  * There are connections that require the user to provide credentials (for example, with an Auth0 with a machine-to-machine (M2M) application, you generate an access token with an expiration time and a refresh token). The connection stores both tokens and generates a new access token before it expires.
  * There are external services that require authorizing scopes to generate API credentials. If you change the scopes, update the connection to those services to avoid connection issues.
  * When a connection is added, it is ready to use in your flows. Any updates to an existing connection will propagate automatically.
</Callout>

## Create and modify vault connections

Create and modify vault connections from the vault page or from the flow editor when an action requires credentials.

### Create vault connections from the vault page

Add a vault connection from the vault page by following these steps:

1. Open the Form editor by selecting **Auth0 Dashboard > Actions > Forms.**
2. From the top left corner, select the tenant menu, and then **Vault** to open the vault page.

   <Frame>
     <img alt="Dashboard > Forms > Vault" />
   </Frame>
3. Select **Add Vault Connection**.
4. Select the desired action and **Continue**.
5. Add a vault **Connection name** and select **Continue**.
6. Enter the credentials.
   If you don't have the specific credentials, you can select **Create an empty connection** and add the credentials later. Empty connections have an orange icon indicating missing credentials.
7. select **Add Vault Connection**.

### Create vault connections from the flow editor

Add a vault connection from a flow action, for example: Twilio by following these steps:

1. Open the Flow editor by selecting **Auth0 Dashboard > Actions > Forms > Flows**
2. Select a flow and add a **Send SMS with Twilio** action.
3. From the **Vault connection** setting of the action, select the **+** Icon.

   <Frame>
     <img alt="Dashboard > Forms > Vault " />
   </Frame>
4. Add a vault **Connection name** and select **Continue**.
5. Enter the credentials.
   If you don't have the specific credentials, you can select **Create an empty connection** and add the credentials later. Empty connections have an orange icon indicating missing credentials.

   <Frame>
     <img alt="Dashboard > Forms > Vault > Twilio connection settings" />
   </Frame>
6. Select **Add Vault Connection.**


# Auth0 Vault Connection
Source: https://auth0.com/docs/customize/forms/vaults/auth0

Learn how to configure your Auth0 Vault Connections to authorize requests against the Management API.

## Get access to Auth0 Management API

[Create a Machine-to-Machine (M2M) Application](/docs/get-started/auth0-overview/create-applications/machine-to-machine-apps) authorized for Auth0 Management API.

<Warning>
  Remember to authorize your M2M Application to access the Management API and select the right scopes following the Least Privilege Principle:

  * For Get User: `read:users`
  * For Create User: `create:users`
  * For Update User: `update:users`
</Warning>

<Callout icon="file-lines">
  No need for Auth0 Management API authorization to send notifications through the configured providers at your Auth0 Tenant.
</Callout>

## Configure your Vault Connection

To configure an Auth0 Vault Connection for your Auth0 Flow Actions, set the required parameters based on the previous created M2M Application.

<Frame>
  <img alt="Dashboard > Actions > Forms > Vault > Auth0" />
</Frame>

#### Input settings

| Parameter           | Description                                                                |
| ------------------- | -------------------------------------------------------------------------- |
| Tenant Domain       | Tenant domain of your M2M Application.                                     |
| Client ID           | Client ID of your M2M Application authorized for Auth0 Management API.     |
| Client Secret       | Client Secret of your M2M Application authorized for Auth0 Management API. |
| Audience (Optional) | Auth0 Management API Audience.                                             |

<Callout icon="file-lines">
  By default, the Audience will be based on the Tenant Domain.
</Callout>


# HTTP Vault Connection
Source: https://auth0.com/docs/customize/forms/vaults/http

Learn how to configure your HTTP Vault Connections to authorize HTTP requests to external APIs or services.

## Configure your HTTP Vault Connection Options

HTTP Vault Connection can be configure with different authentication options and then be used at your HTTP Request Flow Actions.

<Frame>
  <img alt="Dashboard > Actions > Forms > Vault > HTTP" />
</Frame>

## Configure your HTTP Vault Connection for Bearer Token

To configure a HTTP Vault Connection using **Bearer Token** authorization, you need to set the required parameters.

<Frame>
  <img alt="Dashboard > Actions > Forms > Vault > HTTP" />
</Frame>

### Input settings

| Parameter    | Description                                           |
| ------------ | ----------------------------------------------------- |
| Bearer Token | Static token used for external service authorization. |

## Configure your HTTP Vault Connection for OAuth Client Credentials

To configure a HTTP Vault Connection using **Client Credentials** authorization, you need to set the required parameters.

<Frame>
  <img alt="Dashboard > Actions > Forms > Vault > HTTP " />
</Frame>

### Input settings

| Parameter           | Description                                                               |
| ------------------- | ------------------------------------------------------------------------- |
| Tenant Endpoint     | Tenant Endpoint of the Authorization Server issuing the Access Tokens.    |
| Client ID           | Client ID of your M2M Application authorized for Custom API.              |
| Client Secret       | Client Secret of your M2M Application authorized for Custom API.          |
| Audience (Optional) | Custom API Audience. Normally used for Custom APIs defined in Auth0.      |
| Resource (Optional) | Custom API Resource. Standard parameter with similar meaning of Audience. |
| Scope (Optional)    | Scope list in string format separated by spaces.                          |

## Configure your HTTP Vault Connection for API Key

To configure a HTTP Vault Connection using **API Key** authorization, you need to set the required parameters.

<Frame>
  <img alt="Dashboard > Actions > Forms > Vault > HTTP " />
</Frame>

### Input settings

| Parameter | Description                                                                                  |
| --------- | -------------------------------------------------------------------------------------------- |
| Name      | API Key name to be added as Header or Query parameter.                                       |
| Value     | API Key value to be added as Header or Query parameter.                                      |
| Add To    | By default, it's Header. Determines whether to add the API Key as Header or Query parameter. |

## Configure your HTTP Vault Connection for Basic Authentication

To configure a HTTP Vault Connection using **Basic Auth** authorization, you need to set the required parameters.

<Frame>
  <img alt="Dashboard > Actions > Forms > Vault > HTTP " />
</Frame>

### Input settings

| Parameter | Description                                                                                         |
| --------- | --------------------------------------------------------------------------------------------------- |
| Username  | Username to be concatenated and base64 encoded, then added as Basic Authorization Header parameter. |
| Password  | Password to be concatenated and base64 encoded, then added as Basic Authorization Header parameter. |

<Warning>
  HTTP Vault Connection with Basic Auth configuration, is looking forward to replace the currently built-in option at Flows HTTP Request Action.
</Warning>


# JWT Vault Connection
Source: https://auth0.com/docs/customize/forms/vaults/jwt

Learn how to configure your JWT Connection to sign, verify or decode JSON Web Tokens.

## Configure your JWT Vault connection

To configure an JWT Vault Connection for your Flows JWT Actions to sign, decode, and verify JSON Web Tokens, you need to set the required parameters.

<Frame>
  <img alt="Dashboard > Actions > Forms > Vault > JWT" />
</Frame>

## Input settings

| Parameter | Description                                                 |
| --------- | ----------------------------------------------------------- |
| Secret    | Secret to be used in the HS256 algorithm to encode the JWT. |


# MailJet Vault Connection
Source: https://auth0.com/docs/customize/forms/vaults/mailjet

Learn how to configure your MailJet Vault Connections to send emails via MailJet.

## Get your MailJet keys

Find them at [MailJet Dashboard's](https://app.mailjet.com/account/api_keys) Account page under the API keys.

## Configure your MailJet Vault Connection

To configure a MailJet Vault Connection for your MailJet Flow Actions, you need to set the required parameters.

<Frame>
  <img alt="Dashboard > Actions > Forms > Vault > MailJet" />
</Frame>

### Input settings

| Parameter  | Description                               |
| ---------- | ----------------------------------------- |
| API Key    | API Key for MailJet API authorization.    |
| Secret Key | Secret Key for MailJet API authorization. |


# SendGrid Vault Connection
Source: https://auth0.com/docs/customize/forms/vaults/sendgrid

Learn how to configure your SendGrid Vault Connection to send emails via SendGrid.

## Get your SendGrid keys

Find them at [SendGrid dashboard's](https://app.sendgrid.com/settings/api_keys) Settings page under the API keys.

## Configure your SendGrid Vault Connection

To configure a SendGrid Vault Connection for your SendGrid Flow Actions, you need to set the required parameters.

<Frame>
  <img alt="Dashboard > Actions > Forms > Vault > SendGrid" />
</Frame>

### Input settings

| Parameter | Description                             |
| --------- | --------------------------------------- |
| API Key   | API Key for SendGrid API authorization. |


# Telegram Vault Connection
Source: https://auth0.com/docs/customize/forms/vaults/telegram

Learn how to configure your Telegram Vault Connection to send messages via Telegram.

## Get your Telegram token

Learn how to generate a token at [Telegram's Bot API](https://core.telegram.org/#bot-api).

## Configure your Telegram Vault Connection

To configure a Telegram Vault Connection for your Telegram Flow Actions, you need to set the required parameters.

<Frame>
  <img alt="Dashboard > Actions > Forms > Vault > SendGrid" />
</Frame>

### Input settings

| Parameter | Description                                     |
| --------- | ----------------------------------------------- |
| Token     | Generated Token for Telegram API authorization. |


# Twilio Vault Connection
Source: https://auth0.com/docs/customize/forms/vaults/twilio

Learn how to configure your Twilio Vault Connection to send SMS and make calls via Twilio.

## Get your Twilio credentials

Find them at [Twilio's console dashboard](https://console.twilio.com/).

## Configure your Twilio Vault connection

To configure a Twilio Vault Connection for your Twilio Flow Actions, you need to set the required parameters.

<Frame>
  <img alt="Dashboard > Actions > Forms > Vault > Twilio" />
</Frame>

### Input settings

| Parameter   | Description                               |
| ----------- | ----------------------------------------- |
| Account SID | Account SID for Twilio API authorization. |
| Auth token  | Auth Token for Twilio API authorization.  |


# WhatsApp Vault Connection
Source: https://auth0.com/docs/customize/forms/vaults/whatsapp

Learn how to configure your WhatsApp Vault Connection to send messages via WhatsApp.

## Get your WhatsApp token

Learn how to generate a token at [WhatsApp](https://developers.facebook.com/blog/post/2022/12/05/auth-tokens/).

## Configure your WhatsApp Vault connection

To configure a WhatsApp Vault Connection for your WhatsApp Flow Actions, you need to set the required parameters.

<Frame>
  <img alt="Dashboard > Actions > Forms > Vault > WhatsApp" />
</Frame>

### Input settings

| Parameter | Description                                     |
| --------- | ----------------------------------------------- |
| Token     | Generated Token for Whatsapp API authorization. |


# Auth0 Hooks
Source: https://auth0.com/docs/customize/hooks

Describes Auth0 hooks, some of which may be used with database and passwordless connections.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

<Warning>
  Because we plan to remove Rules and Hooks functions in 2026, you should create new Rules or Hooks only in your Development environment and only to test migration to Actions.

  To learn how to migrate your Rules to Actions, read [Migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions). To learn how to migrate your Hooks to Actions, read [Migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions).
</Warning>

<Callout icon="file-lines">
  If you are behind a firewall, for this feature to work properly you may need to add the appropriate Auth0 IP addresses to the Allow List. To learn more, read [Auth0 IP Addresses for Allow Lists](/docs/secure/security-guidance/data-security/allowlist).
</Callout>

Hooks are secure, self-contained functions that allow you to customize the behavior of Auth0 when executed for selected extensibility points of the Auth0 platform. Auth0 invokes hooks during runtime to execute your custom Node.js code.

Whether hooks can be used with connections varies according to extensibility point. Hooks that can be used with connections only work with database and <Tooltip href="/docs/glossary?term=passwordless">passwordless</Tooltip> connections and are subject to Auth0's [Rate Limit Policy](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy). To learn more, read [Database Connections](/docs/authenticate/database-connections) and [Passwordless Connections](/docs/authenticate/passwordless).

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/customize/hooks/create-hooks">Create Hooks</a></td>
      <td>How to create hooks using the  Dashboard or the Management API.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/hooks/update-hooks">Update Hooks</a></td>
      <td>How to update hooks using the  Dashboard or the Management API.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/hooks/delete-hooks">Delete Hooks</a></td>
      <td>How to delete hooks using the  Dashboard or the Management API.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/hooks/enable-disable-hooks">Enable/Disable Hooks</a></td>
      <td>How to enable and disable hooks using the Dashboard and Management API.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/hooks/view-hooks">View Hooks</a></td>
      <td>How to view hooks using the Dashboard and Management API.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/hooks/view-logs-for-hooks">View Logs for Hooks</a></td>
      <td>How to view real-time log events for specific configured hooks.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/actions/explore-triggers">Extensibility Points</a></td>
      <td>About Auth0 extensibility points where hooks can be executed.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/hooks/hook-secrets">Hook Secrets</a></td>
      <td>About how hooks store secrets and how to manage them.</td>
    </tr>
  </tbody>
</table>


# Create Hooks
Source: https://auth0.com/docs/customize/hooks/create-hooks

Learn how to create Hooks using the Dashboard and Management API. Hooks may also be imported and exported using the Auth0 Deploy Command-Line Interface (CLI) tool.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

<Warning>
  Because we plan to remove Rules and Hooks functions in 2026, you should create new Rules or Hooks only in your Development environment and only to test migration to Actions.

  To learn how to migrate your Rules to Actions, read [Migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions). To learn how to migrate your Hooks to Actions, read [Migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions).
</Warning>

You can create multiple hooks using the Dashboard or <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

You can also import and export hooks using the Deploy Command-Line Interface (CLI) tool.

<Warning>
  Although you may create multiple hooks for any given extensibility point, each extensibility point may have only one enabled hook at a time. Any subsequent hooks you create for that extensibility point are automatically disabled, so you must explicitly enable them. The enabled hook will be executed for all applications and APIs.
</Warning>

<Callout icon="file-lines">
  Optionally, you can add secrets (such as Twilio Keys or database connection strings) to hooks.
</Callout>

## Use the Dashboard

1. Go to [Auth0 Dashboard > Auth Pipeline > Hooks](https://manage.auth0.com/#/hooks), and click **+Create**.
2. Enter a descriptive name for your hook, select the extensibility point for which the hook should execute, and click **Create**.
3. Locate the section for the extensibility point you selected, and click the pencil icon next to the hook you created.
4. Update the hook using the Hook Editor, and click the disk icon to save.

## Use the Management API

Make a `POST` call to the [Create a Hook endpoint](https://auth0.com/docs/api/management/v2/#!/Hooks/post_hooks). Be sure to replace `MGMT_API_ACCESS_TOKEN`, `HOOK_NAME`, `HOOK_SCRIPT`, and `EXTENSIBILITY_POINT_NAME` placeholder values with your Management API <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, Hook name, Hook script, and extensibility point name, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/hooks' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "name": "HOOK_NAME", "script": "HOOK_SCRIPT", "triggerId": "EXTENSIBILITY_POINT_NAME" }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/hooks");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("application/json", "{ "name": "HOOK_NAME", "script": "HOOK_SCRIPT", "triggerId": "EXTENSIBILITY_POINT_NAME" }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/hooks"

  	payload := strings.NewReader("{ "name": "HOOK_NAME", "script": "HOOK_SCRIPT", "triggerId": "EXTENSIBILITY_POINT_NAME" }")

  	req, _ := http.NewRequest("POST", 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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/hooks")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "name": "HOOK_NAME", "script": "HOOK_SCRIPT", "triggerId": "EXTENSIBILITY_POINT_NAME" }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/hooks',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: {
      name: 'HOOK_NAME',
      script: 'HOOK_SCRIPT',
      triggerId: 'EXTENSIBILITY_POINT_NAME'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"name": @"HOOK_NAME",
                                @"script": @"HOOK_SCRIPT",
                                @"triggerId": @"EXTENSIBILITY_POINT_NAME" };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/hooks"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/hooks",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "name": "HOOK_NAME", "script": "HOOK_SCRIPT", "triggerId": "EXTENSIBILITY_POINT_NAME" }",
    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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "name": "HOOK_NAME", "script": "HOOK_SCRIPT", "triggerId": "EXTENSIBILITY_POINT_NAME" }"

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
      'cache-control': "no-cache"
      }

  conn.request("POST", "/{yourDomain}/api/v2/hooks", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "name": "HOOK_NAME", "script": "HOOK_SCRIPT", "triggerId": "EXTENSIBILITY_POINT_NAME" }"

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
      'cache-control': "no-cache"
      }

  conn.request("POST", "/{yourDomain}/api/v2/hooks", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = [
    "name": "HOOK_NAME",
    "script": "HOOK_SCRIPT",
    "triggerId": "EXTENSIBILITY_POINT_NAME"
  ] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/hooks")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th><strong>Value</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td>Access Token for the Management API with the <Tooltip href="/docs/glossary?term=scope">scope</Tooltip> <code>create:hooks</code>. To learn more, read <a href="https://auth0.com/docs/api/management/v2/tokens">Management API Access Tokens</a>.</td>
    </tr>

    <tr>
      <td><code>HOOK\_NAME</code></td>
      <td>Name of the Hook to create.</td>
    </tr>

    <tr>
      <td><code>HOOK\_SCRIPT</code></td>
      <td>Script that contains the code for the Hook. Should match what you would enter if you were creating a new Hook using the Dashboard.</td>
    </tr>

    <tr>
      <td><code>EXTENSIBILITY\_POINT\_NAME</code></td>
      <td>Name of the extensibility point for which the Hook should execute. Options include: <code>credentials-exchange</code>, <code>pre-user-registration</code>, <code>post-user-registration</code>, <code>post-change-password</code>. To learn more about extensibility points, read <a href="/docs/customize/actions/explore-triggers">Extensibiity Points</a>.</td>
    </tr>
  </tbody>
</table>

<Card title="Handle rate limits when calling APIs from within Hooks">
  If you call Auth0 APIs from within a Hook's script, you will need to handle rate limits. To do so, check the `X-RateLimit-Remaining` header and act appropriately when the number returned nears 0.

  Additionally, add logic to handle cases in which you exceed the provided rate limits and receive the `429` HTTP Status Code (`Too Many Requests`). In this case, if a re-try is needed, it is best to allow for a back-off to avoid going into an infinite retry loop.
</Card>

To learn more about Auth0 rate limiting for Hooks, read Rate Limits.

## Learn more

* [Migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions)


# Delete Hooks
Source: https://auth0.com/docs/customize/hooks/delete-hooks

Learn how to delete Hooks using the Dashboard and Management API.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

<Warning>
  Because we plan to remove Rules and Hooks functions in 2026, you should create new Rules or Hooks only in your Development environment and only to test migration to Actions.

  To learn how to migrate your Rules to Actions, read [Migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions). To learn how to migrate your Hooks to Actions, read [Migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions).
</Warning>

When you no longer need hooks, you can delete them using either the Dashboard or <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## Use the Dashboard

1. Go to [Auth0 Dashboard > Auth Pipeline > Hooks](https://manage.auth0.com/#/) and click the gear icon next to the hook you want to delete.
2. Click **Delete** and click YES, DELETE HOOK.

## Use the Management API

Make a `DELETE` call to the [Delete a Hook endpoint](https://auth0.com/docs/api/management/v2/#!/Hooks/delete_hooks_by_id). Be sure to replace `HOOK_ID` and `MGMT_API_ACCESS_TOKEN` placeholder values with your hook ID and Management API <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url 'https://{yourDomain}/api/v2/hooks/HOOK_ID' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/hooks/HOOK_ID");
  var request = new RestRequest(Method.DELETE);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/hooks/HOOK_ID"

  	req, _ := http.NewRequest("DELETE", url, nil)

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.delete("https://{yourDomain}/api/v2/hooks/HOOK_ID")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'DELETE',
    url: 'https://{yourDomain}/api/v2/hooks/HOOK_ID',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/hooks/HOOK_ID"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"DELETE"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/hooks/HOOK_ID",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer MGMT_API_ACCESS_TOKEN" }

  conn.request("DELETE", "/{yourDomain}/api/v2/hooks/HOOK_ID", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/hooks/HOOK_ID")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Delete.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer MGMT_API_ACCESS_TOKEN"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/hooks/HOOK_ID")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "DELETE"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>HOOK\_ID</code></td>
      <td>ID of the Hook to delete.</td>
    </tr>

    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td>Access Tokens for the Management API with the <Tooltip href="/docs/glossary?term=scope">scope</Tooltip> <code>update:hooks</code>. To learn more, read <a href="https://auth0.com/docs/api/management/v2/tokens">Management API Access Tokens</a>.</td>
    </tr>
  </tbody>
</table>


# Enable/Disable Hooks
Source: https://auth0.com/docs/customize/hooks/enable-disable-hooks

Learn how to enable and disable hooks using the Dashboard and Management API.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

<Warning>
  Because we plan to remove Rules and Hooks functions in 2026, you should create new Rules or Hooks only in your Development environment and only to test migration to Actions.

  To learn how to migrate your Rules to Actions, read [Migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions). To learn how to migrate your Hooks to Actions, read [Migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions).
</Warning>

You can enable or disable hooks using the Dashboard or <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

<Warning>
  Although you may create multiple hooks for any given extensibility point, each extensibility point may have only one enabled hook at a time. Any subsequent hooks you create for that extensibility point are automatically disabled, so you must explicitly enable them. The enabled hook will be executed for all applications and APIs.
</Warning>

<Warning>
  When creating new hooks, Auth0 automatically enables the first Hook you create for an extensibility point. Any subsequent hooks you create for that extensibility point are automatically disabled, so you must explicitly enable them.
</Warning>

## Use the Dashboard

1. Go to [Auth0 Dashboard > Auth Pipeline > Hooks](https://manage.auth0.com/#/) and locate the extensibility point for which you want to enable or disable a Hook.
2. Click on the dropdown box located immediately under the extensibility point's name and description.

   <Frame>
     <img alt="Auth0 Hook selection" />
   </Frame>
3. Select the Hook you want to enable, and confirm. If you want to disable all Hooks, select `None`.

A green dot will appear next to the name of any enabled Hooks.

## Use the Management API

Make a `PATCH` call to the [Update a Hook endpoint](https://auth0.com/docs/api/management/v2/#!/Hooks/patch_hooks_by_id). Be sure to replace `HOOK_ID` and `MGMT_API_ACCESS_TOKEN` placeholder values with your Hook ID and Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/hooks/HOOK_ID' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "enabled": "true" }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/hooks/HOOK_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", "{ "enabled": "true" }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/hooks/HOOK_ID"

  	payload := strings.NewReader("{ "enabled": "true" }")

  	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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/hooks/HOOK_ID")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "enabled": "true" }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/hooks/HOOK_ID',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: {enabled: 'true'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"enabled": @"true" };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/hooks/HOOK_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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/hooks/HOOK_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 => "{ "enabled": "true" }",
    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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "enabled": "true" }"

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
      'cache-control': "no-cache"
      }

  conn.request("PATCH", "/{yourDomain}/api/v2/hooks/HOOK_ID", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/hooks/HOOK_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 = "{ "enabled": "true" }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = ["enabled": "true"] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/hooks/HOOK_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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>HOOK\_ID</code></td>
      <td>ID of the hook to be updated.</td>
    </tr>

    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td>Access Token for the Management API with the <Tooltip href="/docs/glossary?term=scope">scope</Tooltip> <code>create:hooks</code>. To learn more, read <a href="https://auth0.com/docs/api/management/v2/tokens">Management API Access Tokens</a>.</td>
    </tr>
  </tbody>
</table>

<Callout icon="file-lines">
  The `enabled` property represents whether the rule is enabled (`true`) or disabled (`false`).
</Callout>


# Hook Secrets
Source: https://auth0.com/docs/customize/hooks/hook-secrets

Learn about integrated secret management used with Auth0 Hooks.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

<Warning>
  Because we plan to remove Rules and Hooks functions in 2026, you should create new Rules or Hooks only in your Development environment and only to test migration to Actions.

  To learn how to migrate your Rules to Actions, read [Migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions). To learn how to migrate your Hooks to Actions, read [Migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions).
</Warning>

Hooks feature integrated secret management to securely store secrets while making them conveniently available in code.

<Callout icon="file-lines">
  To access a configured Hook Secret from within a hook, use `context.webtask.secrets.SECRET_NAME`.
</Callout>

## Manage Hook Secrets

You can create, update, delete, and view Hook Secrets from the Dashboard or <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. To learn more, read:

* [Create Hook Secrets](/docs/customize/hooks/hook-secrets/create-hook-secrets)
* [Update Hook Secrets](/docs/customize/hooks/hook-secrets/update-hook-secrets)
* [Delete Hook Secrets](/docs/customize/hooks/hook-secrets/delete-hook-secrets)
* [View Hook Secrets](/docs/customize/hooks/hook-secrets/view-hook-secrets)

Hook Secrets can also be imported or exported using the [Deploy Command-Line Interface (CLI) tool.](/docs/deploy-monitor/deploy-cli-tool)

## Learn more

* [Auth0 Hooks](/docs/customize/hooks)


# Create Hook Secrets
Source: https://auth0.com/docs/customize/hooks/hook-secrets/create-hook-secrets

Learn how to create Hook Secrets using the Dashboard and Management API. Hook Secrets may also be imported and exported using the Auth0 Deploy Command-Line Interface (CLI) tool.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

<Warning>
  Because we plan to remove Rules and Hooks functions in 2026, you should create new Rules or Hooks only in your Development environment and only to test migration to Actions.

  To learn how to migrate your Rules to Actions, read [Migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions). To learn how to migrate your Hooks to Actions, read [Migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions).
</Warning>

You can create multiple Hook Secrets for any [Hook](/docs/customize/hooks) using the Dashboard or <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

Hook Secrets may also be imported and exported using the [Deploy Command-Line Interface (CLI) Tool](/docs/deploy-monitor/deploy-cli-tool).

<Callout icon="file-lines">
  You may create up to 20 secrets for any given Hook.
</Callout>

## Create Hook Secrets using the Dashboard

1. Navigate to the [Hooks](https://manage.auth0.com/#/hooks) page in the [Auth0 Dashboard](https://manage.auth0.com/#/), and click the pencil icon next to the Hook you want to edit.
2. In the Hook editor, click the wrench icon, and click **Secrets**.
3. Click **Add Secret**.
4. Enter a descriptive name and value for your secret, and click **Save**.

## Create Hook Secrets using the Management API

Make a `POST` call to the [Add Hook Secrets endpoint](https://auth0.com/docs/api/management/v2/#!/Hooks/post_secrets). Be sure to replace `MGMT_API_ACCESS_TOKEN`, `HOOK_ID`, `HOOK_SECRET_KEY`, and `HOOK_SECRET_VALUE` placeholder values with your Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, Hook ID, and Hook key-value pair(s), respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ], [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ] }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("application/json", "{ [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ], [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ] }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets"

  	payload := strings.NewReader("{ [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ], [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ] }")

  	req, _ := http.NewRequest("POST", 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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ], [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ] }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: '{ [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ], [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ] }'
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };

  NSData *postData = [[NSData alloc] initWithData:[@"{ [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ], [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ] }" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ], [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ] }",
    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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ], [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ] }"

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
      'cache-control': "no-cache"
      }

  conn.request("POST", "/{yourDomain}/api/v2/hooks/HOOK_ID/secrets", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request["cache-control"] = 'no-cache'
  request.body = "{ [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ], [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ] }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]

  let postData = NSData(data: "{ [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ], [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ] }".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th><strong>Value</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td><a href="https://auth0.com/docs/api/management/v2/tokens">Access Token for the Management API</a> with the <Tooltip href="/docs/glossary?term=scope">scope</Tooltip> <code>create:hooks</code>.</td>
    </tr>

    <tr>
      <td><code>HOOK\_ID</code></td>
      <td>ID of the hook for which you would like to add secrets.</td>
    </tr>

    <tr>
      <td><code>HOOK\_SECRET\_KEY</code></td>
      <td>Name of the secret that you would like to add to the specified hook. This endpoint accepts an object of key-value pairs.</td>
    </tr>

    <tr>
      <td><code>HOOK\_SECRET\_VALUE</code></td>
      <td>Value of the secret that you would like to add to the specified hook. This endpoint accepts an object of key-value pairs.</td>
    </tr>
  </tbody>
</table>


# Delete Hook Secrets
Source: https://auth0.com/docs/customize/hooks/hook-secrets/delete-hook-secrets

Learn how to delete Hook Secrets using the Dashboard and Management API. Hook Secrets may also be imported and exported using the Auth0 Deploy Command-Line Interface (CLI) tool.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

<Warning>
  Because we plan to remove Rules and Hooks functions in 2026, you should create new Rules or Hooks only in your Development environment and only to test migration to Actions.

  To learn how to migrate your Rules to Actions, read [Migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions). To learn how to migrate your Hooks to Actions, read [Migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions).
</Warning>

When you no longer need Hook Secrets for a given Hook, you can delete them using either the Dashboard or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

Hook Secrets can also be imported and exported using the [Deploy Command-Line Interface (CLI) tool](/docs/deploy-monitor/deploy-cli-tool).

## Delete Hook Secrets using the Dashboard

1. Navigate to the [Hooks](https://manage.auth0.com/#/hooks) page in the [Auth0 Dashboard](https://manage.auth0.com/#/), and click the pencil icon next to the Hook you want to edit.
2. In the Hook editor, click the wrench icon, and click **Secrets**.
3. Locate the Hook Secret you want to delete, click the trash can icon, and click **Yes**.

## Delete Hook Secrets using the Management API

Make a `DELETE` call to the [Delete Hook Secrets endpoint](https://auth0.com/docs/api/management/v2/#!/Hooks/delete_secrets). Be sure to replace `HOOK_ID`, `HOOK_SECRET_NAME`, and `MGMT_API_ACCESS_TOKEN` placeholder values with your Hook ID, your Hook Secret name(s), and Management API <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url 'https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --data '{ [ "HOOK_SECRET_NAME", "HOOK_SECRET_NAME" ] }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets");
  var request = new RestRequest(Method.DELETE);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddParameter("undefined", "{ [ "HOOK_SECRET_NAME", "HOOK_SECRET_NAME" ] }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets"

  	payload := strings.NewReader("{ [ "HOOK_SECRET_NAME", "HOOK_SECRET_NAME" ] }")

  	req, _ := http.NewRequest("DELETE", url, payload)

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.delete("https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .body("{ [ "HOOK_SECRET_NAME", "HOOK_SECRET_NAME" ] }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'DELETE',
    url: 'https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN'},
    data: '{ [ "HOOK_SECRET_NAME", "HOOK_SECRET_NAME" ] }'
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };

  NSData *postData = [[NSData alloc] initWithData:[@"{ [ "HOOK_SECRET_NAME", "HOOK_SECRET_NAME" ] }" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"DELETE"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_POSTFIELDS => "{ [ "HOOK_SECRET_NAME", "HOOK_SECRET_NAME" ] }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ [ "HOOK_SECRET_NAME", "HOOK_SECRET_NAME" ] }"

  headers = { 'authorization': "Bearer MGMT_API_ACCESS_TOKEN" }

  conn.request("DELETE", "/{yourDomain}/api/v2/hooks/HOOK_ID/secrets", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Delete.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request.body = "{ [ "HOOK_SECRET_NAME", "HOOK_SECRET_NAME" ] }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer MGMT_API_ACCESS_TOKEN"]

  let postData = NSData(data: "{ [ "HOOK_SECRET_NAME", "HOOK_SECRET_NAME" ] }".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "DELETE"
  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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>HOOK\_ID</code></td>
      <td>ID of the Hook for which you want to delete secrets.</td>
    </tr>

    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td>Access Tokens for the Management API with the <Tooltip href="/docs/glossary?term=scope">scope</Tooltip> <code>update:hooks</code>. To learn more, read <a href="https://auth0.com/docs/api/management/v2/tokens">Management API Access Tokens</a>.</td>
    </tr>

    <tr>
      <td><code>HOOK\_SECRET\_NAME</code></td>
      <td>Name(s) of the secret(s) you would like to delete from the specified Hook. This endpoint accepts an array of secret names to delete.</td>
    </tr>
  </tbody>
</table>


# Update Hook Secrets
Source: https://auth0.com/docs/customize/hooks/hook-secrets/update-hook-secrets

Learn how to update Hook Secrets using the Dashboard or Management API. Hook Secrets may also be imported and exported using the Auth0 Deploy Command-Line Interface (CLI) tool.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

<Warning>
  Because we plan to remove Rules and Hooks functions in 2026, you should create new Rules or Hooks only in your Development environment and only to test migration to Actions.

  To learn how to migrate your Rules to Actions, read [Migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions). To learn how to migrate your Hooks to Actions, read [Migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions).
</Warning>

You can update Hook Secrets added to any given Hook using the Dashboard or <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

Hook Secrets may also be imported and exported using the Deploy Command-Line Interface (CLI) tool. To learn more, read [Deploy CLI Tool](/docs/deploy-monitor/deploy-cli-tool).

## Update Hook Secrets using the Dashboard

1. Go to [Auth0 Dashboard > Auth Pipeline > Hooks](https://manage.auth0.com/#/) and and click the pencil icon next to the Hook you want to edit.
2. In the Hook editor, click the wrench icon and click **Secrets**.
3. Click the pencil and paper icon next to the value of the Hook Secret you want to edit.
4. Make your changes to the name and/or value of the selected Hook Secret, and click **Save**.

## Update Hook Secrets using the Management API

Make a `PATCH` call to the [Update Hook Secrets endpoint](https://auth0.com/docs/api/management/v2/#!/Hooks/patch_secrets). Be sure to replace `HOOK_ID` and `MGMT_API_ACCESS_TOKEN` placeholder values with your hook ID and Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ], [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ] }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets");
  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", "{ [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ], [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ] }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets"

  	payload := strings.NewReader("{ [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ], [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ] }")

  	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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ], [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ] }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: '{ [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ], [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ] }'
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };

  NSData *postData = [[NSData alloc] initWithData:[@"{ [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ], [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ] }" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets"]
                                                         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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "PATCH",
    CURLOPT_POSTFIELDS => "{ [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ], [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ] }",
    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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ], [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ] }"

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
      'cache-control': "no-cache"
      }

  conn.request("PATCH", "/{yourDomain}/api/v2/hooks/HOOK_ID/secrets", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets")

  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 = "{ [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ], [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ] }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]

  let postData = NSData(data: "{ [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ], [ "HOOK_SECRET_KEY", "HOOK_SECRET_VALUE" ] }".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets")! 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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th><strong>Value</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td>Access Tokens for the Management API with the <Tooltip href="/docs/glossary?term=scope">scope</Tooltip> <code>update:hooks</code>. To learn more, read <a href="https://auth0.com/docs/api/management/v2/tokens">Management API Access Tokens</a>.</td>
    </tr>

    <tr>
      <td><code>HOOK\_ID</code></td>
      <td>ID of the hook for which you would like to update secrets.</td>
    </tr>

    <tr>
      <td><code>HOOK\_SECRET\_KEY</code></td>
      <td>Name of the secret that you would like to update for the specified hook. This endpoint accepts an object of key-value pairs.</td>
    </tr>

    <tr>
      <td><code>HOOK\_SECRET\_VALUE</code></td>
      <td>Value of the secret that you would like to update for the specified hook. This endpoint accepts an object of key-value pairs.</td>
    </tr>
  </tbody>
</table>

<Warning>
  When retrieving Hook Secrets configured for a specified Hook, values will contain the placeholder text: `_VALUE_NOT_SHOWN`. Be careful not to return this placeholder text during an update, or the secret's actual value will be overwritten.
</Warning>

## Learn more

* [Auth0 Hooks](/docs/customize/hooks)


# View Hook Secrets
Source: https://auth0.com/docs/customize/hooks/hook-secrets/view-hook-secrets

Learn how to view Hook Secrets using the Dashboard and Management API.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

<Warning>
  Because we plan to remove Rules and Hooks functions in 2026, you should create new Rules or Hooks only in your Development environment and only to test migration to Actions.

  To learn how to migrate your Rules to Actions, read [Migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions). To learn how to migrate your Hooks to Actions, read [Migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions).
</Warning>

You can see configured Hook Secrets for a Hook using the Dashboard or retrieve a list of Hook Secrets using the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## View Hook Secrets using the Dashboard

1. Go to [Auth0 Dashboard > Auth Pipeline > Hooks](https://manage.auth0.com/#/) and click the pencil icon next to the Hook for which you want to view Secrets.
2. In the Hook Editor, click the wrench icon, and click **Secrets**.

All configured secrets for the selected Hook are listed.

## Get Hook Secrets using the Management API

Make a `GET` call to the [Get Hook Secrets endpoint](https://auth0.com/docs/api/management/v2/#!/Hooks/get_secrets). Be sure to replace `HOOK_ID` and `MGMT_API_ACCESS_TOKEN` placeholder values with your Hook's ID and the Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer MGMT_API_ACCESS_TOKEN" }

  conn.request("GET", "/{yourDomain}/api/v2/hooks/HOOK_ID/secrets", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer MGMT_API_ACCESS_TOKEN"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/hooks/HOOK_ID/secrets")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th><strong>Value</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>HOOK\_ID</code></td>
      <td>ID of the Hook for which you want to retrieve secrets.</td>
    </tr>

    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td>Access Tokens for the Management API with the <Tooltip href="/docs/glossary?term=scope">scope</Tooltip> <code>update:hooks</code>. To learn more, read <a href="https://auth0.com/docs/api/management/v2/tokens">Management API Access Tokens</a>.</td>
    </tr>
  </tbody>
</table>

<Warning>
  Hook Secrets are write-only. When retrieving secrets configured for a specified Hook, values will contain the placeholder text: `_VALUE_NOT_SHOWN`.
</Warning>


# Update Hooks
Source: https://auth0.com/docs/customize/hooks/update-hooks

Learn how to update Hooks using the Dashboard or Management API. Hooks may also be imported and exported using the Auth0 Deploy Command-Line Interface (CLI) tool.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

<Warning>
  Because we plan to remove Rules and Hooks functions in 2026, you should create new Rules or Hooks only in your Development environment and only to test migration to Actions.

  To learn how to migrate your Rules to Actions, read [Migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions). To learn how to migrate your Hooks to Actions, read [Migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions).
</Warning>

You can update Hooks using the Dashboard or <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

You can also import and export hooks using the [Deploy Command-Line Interface (CLI) tool](/docs/deploy-monitor/deploy-cli-tool).

<Callout icon="file-lines">
  Optionally, you can add secrets (such as Twilio Keys or database connection strings) to hooks.
</Callout>

## Rename hooks using the Dashboard

1. Go to [Auth0 Dashboard > Auth Pipeline > Hooks](https://manage.auth0.com/#/) and click the gear icon next to the hook you want to rename.
2. Click **Rename**.
3. Type a new name for the Hook and click **Rename**.

   <Frame>
     <img alt="Auth0 Rename Hooks" />
   </Frame>

## Update hook scripts using the Dashboard

1. Go to [Auth0 Dashboard > Auth Pipeline > Hooks](https://manage.auth0.com/#/) and click the pencil icon next to the hook you want to update.

   <Frame>
     <img alt="Auth0 Hooks select a Hook" />
   </Frame>
2. Update the hook using the Hook Editor and click the disk icon to save.

   <Frame>
     <img alt="Auth0 Hook Editor" />
   </Frame>

## Update hooks using the Management API

Make a `PATCH` call to the [Update a Hook endpoint](https://auth0.com/docs/api/management/v2/#!/Hooks/patch_hooks_by_id). Be sure to replace `HOOK_ID` and `MGMT_API_ACCESS_TOKEN` placeholder values with your Hook ID and Management API <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/hooks/HOOK_ID' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "name": "HOOK_NAME", "script": "HOOK_SCRIPT", "enabled": "true" }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/hooks/HOOK_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", "{ "name": "HOOK_NAME", "script": "HOOK_SCRIPT", "enabled": "true" }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/hooks/HOOK_ID"

  	payload := strings.NewReader("{ "name": "HOOK_NAME", "script": "HOOK_SCRIPT", "enabled": "true" }")

  	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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/hooks/HOOK_ID")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "name": "HOOK_NAME", "script": "HOOK_SCRIPT", "enabled": "true" }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/hooks/HOOK_ID',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: {name: 'HOOK_NAME', script: 'HOOK_SCRIPT', enabled: 'true'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"name": @"HOOK_NAME",
                                @"script": @"HOOK_SCRIPT",
                                @"enabled": @"true" };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/hooks/HOOK_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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/hooks/HOOK_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 => "{ "name": "HOOK_NAME", "script": "HOOK_SCRIPT", "enabled": "true" }",
    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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "name": "HOOK_NAME", "script": "HOOK_SCRIPT", "enabled": "true" }"

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
      'cache-control': "no-cache"
      }

  conn.request("PATCH", "/{yourDomain}/api/v2/hooks/HOOK_ID", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/hooks/HOOK_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 = "{ "name": "HOOK_NAME", "script": "HOOK_SCRIPT", "enabled": "true" }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = [
    "name": "HOOK_NAME",
    "script": "HOOK_SCRIPT",
    "enabled": "true"
  ] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/hooks/HOOK_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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>HOOK\_ID</code></td>
      <td>ID of the Hook to update.</td>
    </tr>

    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td>Access Tokens for the Management API with the <Tooltip href="/docs/glossary?term=scope">scope</Tooltip> <code>update:hooks</code>. To learn more, read <a href="https://auth0.com/docs/api/management/v2/tokens">Management API Access Tokens</a>.</td>
    </tr>

    <tr>
      <td><code>HOOK\_NAME</code></td>
      <td>Name of the Hook to create.</td>
    </tr>

    <tr>
      <td><code>HOOK\_SCRIPT</code></td>
      <td>Script that contains the code for the Hook. Should match what you would enter if you were creating a new hook using the Dashboard.</td>
    </tr>
  </tbody>
</table>

<Callout icon="file-lines">
  The `enabled` property represents whether the rule is enabled (`true`) or disabled (`false`).
</Callout>

<Card title="Handle rate limits when calling APIs from within Hooks">
  If you call Auth0 APIs from within a Hook's script, you will need to handle rate limits. To do so, check the `X-RateLimit-Remaining` header and act appropriately when the number returned nears 0.

  Additionally, add logic to handle cases in which you exceed the provided rate limits and receive the `429` HTTP Status Code (`Too Many Requests`). In this case, if a re-try is needed, it is best to allow for a back-off to avoid going into an infinite retry loop.
</Card>


# View Hooks
Source: https://auth0.com/docs/customize/hooks/view-hooks

Learn how to view hooks using the Dashboard and Management API. Hooks may also be imported and exported using the Auth0 Deploy Command-Line Interface (CLI) tool.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

<Warning>
  Because we plan to remove Rules and Hooks functions in 2026, you should create new Rules or Hooks only in your Development environment and only to test migration to Actions.

  To learn how to migrate your Rules to Actions, read [Migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions). To learn how to migrate your Hooks to Actions, read [Migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions).
</Warning>

To see configured hooks, you can view them using the Dashboard or retrieve a list of them using the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## Use the Dashboard

Go to [Auth0 Dashboard > Auth Pipeline > Hooks](https://manage.auth0.com/#/).

All configured hooks are listed by the extensibility point at which they are executed. A green dot next to a hook indicates that it is enabled.

## Use the Management API

Make a `GET` call to the [Get Hooks endpoint](https://auth0.com/docs/api/management/v2/#!/Hooks/get_hooks). Be sure to replace `MGMT_API_ACCESS_TOKEN` placeholder value with your Management API <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/hooks' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/hooks");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/hooks"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/api/v2/hooks")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/hooks',
    headers: {authorization: 'Bearer MGMT_API_ACCESS_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/hooks"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/hooks",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer MGMT_API_ACCESS_TOKEN" }

  conn.request("GET", "/{yourDomain}/api/v2/hooks", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/hooks")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer MGMT_API_ACCESS_TOKEN"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/hooks")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th><strong>Value</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td>Access Token for the Management API with the <Tooltip href="/docs/glossary?term=scope">scope</Tooltip> <code>create:hooks</code>. To learn more, read <a href="https://auth0.com/docs/api/management/v2/tokens">Management API Access Tokens</a>.</td>
    </tr>
  </tbody>
</table>


# View Logs for Hooks
Source: https://auth0.com/docs/customize/hooks/view-logs-for-hooks

Learn how to view logs for hooks using the Auth0 Dashboard.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

<Warning>
  Because we plan to remove Rules and Hooks functions in 2026, you should create new Rules or Hooks only in your Development environment and only to test migration to Actions.

  To learn how to migrate your Rules to Actions, read [Migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions). To learn how to migrate your Hooks to Actions, read [Migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions).
</Warning>

From the Dashboard, you can view real-time logging information for hooks (and also rules, actions, custom database scripts, and custom social connections).

1. Go to [Auth0 Dashboard > Auth Pipeline > Hooks](https://manage.auth0.com/#/) and select the pencil icon next to a Hook.

   <Frame>
     <img alt="Auth0 Hooks select a Hook" />
   </Frame>
2. In the top right corner of the Hooks Editor, select the logs icon.

   <Frame>
     <img alt="Auth0 Hook Editor" />
   </Frame>


# Auth0 Rules
Source: https://auth0.com/docs/customize/rules

Learn about Rules and how you can use them to customize and extend Auth0's capabilities.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

Rules can be used in a variety of situations as part of the authentication pipeline where protocol-specific artifacts are generated:

* an <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> in <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC)
* an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> in <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip>
* an assertion in <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip>

A new pipeline in which rules execute is created for each authentication request, and Rules are subject to Auth0's [Rate Limit Policy](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy).

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/customize/actions/use-cases">Rule Use Cases</a></td>
      <td>About different rule uses cases.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/rules/create-rules">Create Rules</a></td>
      <td>How to create rules using the Auth Dashboard or the Management API.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/rules/configuration">Store Rule Configurations</a></td>
      <td>How to use the global configuration object in rules for storing commonly used values.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/rules/cache-resources">Cache Expensive Resources in Rules</a></td>
      <td>How to use the <code>global</code> object to reuse resources stored there instead of creating them every time you run a rule.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/rules/debug-rules">Debug Rules</a></td>
      <td>How to debug rules.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/rules/use-management-api">Use the Management API from Within Rules</a></td>
      <td>How to access the Auth0 Management API endpoints from within rules.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/rules/redirect-users">Redirect Users from Within Rules</a></td>
      <td>How to use rules to redirect users before an authentication transaction is complete.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/rules/user-object-in-rules">User Object Properties in Rules</a></td>
      <td>About the <code>user</code> object and how it stores information logged in users returned by the identity provider.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/rules/context-object">Context Object Properties in Rules</a></td>
      <td>About the <code>context</code> object and how it stores contextual information about the current authentication transactions.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/rules/raise-errors-from-rules">Raise Errors from Rules</a></td>
      <td>How to display an error message to users from within rules.</td>
    </tr>
  </tbody>
</table>


# Cache Expensive Resources in Rules
Source: https://auth0.com/docs/customize/rules/cache-resources

How to cache expensive resources in your Rules code.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

In Rules you can store expensive resources using the `global` object. The `global` object survives individual execution, so you can reuse things stored there instead of creating them every time a Rule is run. However, the Rules environment can be recycled at any time so your code **must** always check that `global` contains what you expect.

This example shows how to use the `global` object to keep a MongoDB connection:

```javascript lines theme={null}
//If the db object is there, use it.
if (global.db){
  return query(global.db, callback);
}

//If not, get the db (mongodb in this case)
mongo('mongodb://user:pass@mymongoserver.com/my-db',  function (db){
  global.db = db;
  return query(db, callback);
});

//Do the actual work
function query(db, cb){
  // Do something with db
  ...
  return cb(null, user, context);
}
```

To learn more about using MongoDB, read [the MongoDB Manual](https://docs.mongodb.com/manual/).


# Store Rule Configurations
Source: https://auth0.com/docs/customize/rules/configuration

Learn about the global configuration object in rules for storing commonly used values.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

The global `configuration` object is available in Rules for storing commonly used values, such as URLs. Sensitive information, such as credentials or API keys, should be stored through the `configuration` object and kept out of your Rules code.

## Configure values

You can set configuration values in your [Rules Settings](https://manage.auth0.com/#/rules/) on the Dashboard.

To edit or change a configuration key's value, remove the existing configuration setting and replace it with the updated value. You need to have created at least one Rule to see the configuration area, otherwise, the Rules demo shows instead.

<Frame>
  <img alt="Dashboard - Auth Pipeline - Rules " />
</Frame>

## Use the configuration object

Any configuration values you set can be accessed through the `configuration` object by key in your Rules code.

```javascript lines theme={null}
var MY_API_KEY = configuration.MY_API_KEY;
```

The following example is a Rule for sending a Slack message when a new user has signed up. The [Slack Webhook](https://api.slack.com/incoming-webhooks) is a `configuration` value set with the key `SLACK_HOOK_URL`.

```javascript lines theme={null}
function (user, context, callback) {
  // short-circuit if the user signed up already or is using a Refresh Token
  if (context.stats.loginsCount > 1 || context.protocol === 'oauth2-refresh-token') {
    return callback(null, user, context);
  }

  // get your slack's hook url from: https://slack.com/services/10525858050
  const SLACK_HOOK = configuration.SLACK_HOOK_URL;

  const slack = require('slack-notify')(SLACK_HOOK);
  const message = 'New User: ' + (user.name || user.email) + ' (' + user.email + ')';
  const channel = '#some_channel';

  slack.success({
    text: message,
    channel: channel
  });

  // don’t wait for the Slack API call to finish, return right away (the request will continue on the sandbox)`
  callback(null, user, context);
}
```


# Configure Global Variables for Rules
Source: https://auth0.com/docs/customize/rules/configure-global-variables-for-rules

Describes how to configure global variables for rules using the Auth0 Dashboard.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

You can configure global variables for rules using Auth0's Dashboard. To learn more, see [Auth0 Rules](/docs/customize/rules).

1. Go to [Auth0 Dashboard > Auth Pipeline > Rules](https://manage.auth0.com/#/rules) and locate the **Settings** section.

   <Frame>
     <img alt="Dashboard - Auth Pipeline - Rules " />
   </Frame>
2. Enter a variable key/value pair, and select **+ Add**.

   The entered value is now available to all rules via the global `configuration` object and can be referenced using the value in the **Code Snippet** column.

## Learn more

* [Create Rules](/docs/customize/rules/create-rules)


# Context Object Properties in Rules
Source: https://auth0.com/docs/customize/rules/context-object

Learn about the properties of the Rules context object, which stores information about users' IP addresses, applications, and location.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

The `context` object stores contextual information about the current authentication transaction, such as the user's IP address, application, or location.

If you change token content using the context object within a rule, your changes will be available in tokens after all rules have finished running. If your application also requires <Tooltip href="/docs/glossary?term=multifactor+authentication">multifactor authentication</Tooltip> or user consent, the user will be prompted before changes in the token are available.

## Properties

The following properties are available for the `context` object.

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>context.tenant</code></td>
      <td>A string containing the name of the tenant.</td>
    </tr>

    <tr>
      <td><code>context.clientID</code></td>
      <td>The client id of the application the user is logging in to.</td>
    </tr>

    <tr>
      <td><code>context.clientName</code></td>
      <td>The name of the application (as defined on the dashboard).</td>
    </tr>

    <tr>
      <td><code>context.clientMetadata</code></td>
      <td>An object for holding other application properties. Its keys and values are strings.</td>
    </tr>

    <tr>
      <td><code>context.connectionID</code></td>
      <td>A string containing the connection's unique identifier.</td>
    </tr>

    <tr>
      <td><code>context.connection</code></td>
      <td>The name of the connection used to authenticate the user (such as: <code>twitter</code> or <code>some-g-suite-domain</code>)</td>
    </tr>

    <tr>
      <td><code>context.connectionStrategy</code></td>
      <td>The type of connection. For social connection <code>connectionStrategy</code> === <code>connection</code>. For enterprise connections, the strategy will be <code>waad</code> (Windows Azure AD), <code>ad</code> (Active Directory/LDAP), <code>auth0</code> (database connections), and so on.</td>
    </tr>

    <tr>
      <td><code>context.connectionOptions</code></td>
      <td>An object representing the options defined on the connection. <code>connectionOptions.tenant\_domain</code> is a string containing the domain being used for authentication when using an Enterprise connection.<br /> <code>connectionOptions.domain\_aliases</code> is an array containing the optional domains registered as aliases in addition to the primary domain (specified in the <code>connectionOptions.tenant\_domain</code> property).</td>
    </tr>

    <tr>
      <td><code>context.connectionMetadata</code></td>
      <td>An object representing metadata defined on the connection. Its keys and values are strings.</td>
    </tr>

    <tr>
      <td><code>context.samlConfiguration</code></td>
      <td>An object that controls the behavior of the <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> and WS-Fed endpoints. Useful for advanced claims mapping and token enrichment (only available for <code>samlp</code> and <code>wsfed</code> protocol).</td>
    </tr>

    <tr>
      <td><code>context.protocol</code></td>
      <td>The authentication protocol. Possible values:<ul>
      <li><code>oidc-basic-profile</code>: most used, web-based login</li>
      <li><code>oidc-implicit-profile</code>: used on mobile devices and single-page apps</li>
      <li><code>oauth2-device-code</code>: transaction using the <a href="/docs/get-started/authentication-and-authorization-flow/device-authorization-flow">Device Authorization Flow</a></li>
      <li> <code>oauth2-resource-owner</code>: user/password login typically used on database connections</li>
      <li><code>oauth2-resource-owner-jwt-bearer</code>: login using a bearer JWT signed with user's private key</li>
      <li><code>oauth2-password</code>: login using the password exchange</li>
      <li><code>oauth2-refresh-token</code>: refreshing a token using the Refresh Token exchange</li>
      <li><code>samlp</code>: SAML protocol used on SaaS apps</li>
      <li><code>wsfed</code>: WS-Federation used on Microsoft products like Office365</li>
      <li><code>wstrust-usernamemixed</code>: WS-trust user/password login used on CRM and Office365</li>
      <li><code>delegation</code>: when calling the <a href="https://auth0.com/docs/api/authentication#delegation">Delegation endpoint</a></li>
      <li><code>redirect-callback</code>: when a redirect rule is resumed</li></ul></td>
    </tr>

    <tr>
      <td><code>context.riskAssessment</code></td>
      <td>An object containing specific scores (low, medium, high, neutral) for high risk login attempt assessors. See <a href="/docs/secure/multi-factor-authentication/adaptive-mfa/customize-adaptive-mfa">Customize Adaptive MFA with Rules</a>.</td>
    </tr>

    <tr>
      <td><code>context.stats</code></td>
      <td>An object containing specific user stats, like <code>stats.loginsCount</code>. Note that any of the counter variables returned as part of the <code>stats</code> object do not increase during <a href="/docs/authenticate/login/configure-silent-authentication">silent authentication</a> (as when <code>prompt=none</code>). There are also scenarios where the counter variables might increase yet a rule or set of rules do not execute, as in the case of a successful cross-origin authentication followed by a failed token request.</td>
    </tr>

    <tr>
      <td><code>context.sso</code></td>
      <td>This object will contain information about the <Tooltip href="/docs/glossary?term=Single+Sign-on+%28SSO%29">Single Sign-on (SSO)</Tooltip> transaction (if available)<ul>
      <li><code>with\_auth0</code>: when a user signs in with SSO to an application where the <code>Use Auth0 instead of the IdP to do Single Sign-On</code> setting is enabled (only for legacy tenants).</li>
      <li><code>with\_dbconn</code>: an SSO login for a user that logged in through a database connection.</li>
      <li><code>current\_clients</code>: client IDs using SSO.</li></ul></td>
    </tr>

    <tr>
      <td><code>context.accessToken</code></td>
      <td>An object representing the options defined on the <Tooltip href="/docs/glossary?term=Access+Toke">Access Toke</Tooltip>. You can use this object to <a href="/docs/get-started/apis/scopes/sample-use-cases-scopes-and-claims#add-custom-claims-to-a-token">add custom namespaced claims</a> to the <Tooltip href="/docs/glossary?term=Access+Toke">Access Toke</Tooltip>. <code>context.accessToken.scope</code> can be used to <a href="/docs/customize/actions/actions-overview#modify-scope-of-access-token">change the Access Token's returned scopes</a>. When provided, it is an array containing permissions in string format. Custom claims will be included in the Access Token after all rules have run.</td>
    </tr>

    <tr>
      <td><code>context.idToken</code></td>
      <td>An object representing the options defined on the <a href="/docs/secure/tokens/id-tokens">ID Token</a>. Used to add custom <a href="/docs/secure/tokens/json-web-tokens/create-custom-claims">namespaced</a> claims to the ID Token. Custom claims will be included in the ID Token after all rules have run.</td>
    </tr>

    <tr>
      <td><code>context.multifactor</code></td>
      <td>An object representing the multifactor settings used in <a href="/docs/secure/multi-factor-authentication">implementing contextual MFA</a>.</td>
    </tr>

    <tr>
      <td><code>context.redirect</code></td>
      <td>The object used to <a href="/docs/customize/rules/redirect-users#how-to-implement-a-redirect">implement the redirection of a user from a rule</a>.</td>
    </tr>

    <tr>
      <td><code>context.sessionID</code></td>
      <td>An internal identification for the authentication session. Value is kept only if <code>prompt=none</code> is used in the authorization request. Note that the session ID can change <strong>after</strong> rule execution on other flows, so the value available in <code>context.sessionID</code> might not match the new session ID that the user will receive. This makes this value only meaningful when <code>prompt=none</code> is used.</td>
    </tr>

    <tr>
      <td><code>context.request</code></td>
      <td>An object containing useful information of the request. This can also be set to <code>undefined</code>. It has the following properties:<ul>
      <li><code>userAgent</code>: the user-agent of the application that is trying to log in.</li>
      <li><code>ip</code>: the originating IP address of the user trying to log in. We expose IPv6 addresses in our public endpoints (e.g., travel0.us.auth0.com). If a request arrives from a machine that supports IPv6, then this will contain an IPv6 address. If you perform manual IP address manipulation, we suggest you use the <a href="https://www.npmjs.com/package/ipaddr.js/v/1.9.0">ipaddr.js\@1.9.0 library</a>.</li>
      <li><code>hostname</code>: the hostname that is being used for the authentication flow.</li>
      <li><code>query</code>: an object containing the querystring properties of the login transaction sent by the application.</li>
      <li><code>body</code>: the body of the POST request on login transactions used on <code>oauth2-resource-owner</code>, <code>oauth2-resource-owner-jwt-bearer</code> or <code>wstrust-usernamemixed</code> protocols.</li>
      <li><code>geoip</code>: an object containing geographic IP information. It has the following properties:<ul>
      <li><code>country\_code</code>: a two-character code for the country associated with the IP address.</li>
      <li><code>country\_code3</code>: a three-character code for the country associated with the IP address.</li>
      <li><code>country\_name</code>: the country name associated with the IP address.</li>
      <li><code>city\_name</code>: the city or town name associated with the IP address.</li>
      <li><code>latitude</code>: the latitude associated with the IP address.</li>
      <li><code>longitude</code>: the longitude associated with the IP address.</li>
      <li><code>time\_zone</code>: the timezone associated with the IP address.</li>
      <li><code>continent\_code</code>: a two-character code for the continent associated with the IP address.</li>
      <li><code>subdivision\_code</code>: the ISO 3166-2 code for the top-level subdivision/region.</li>
      <li><code>subdivision\_name</code>: The English name of this subdivision/region.</li></ul></li></ul></td>
    </tr>

    <tr>
      <td><code>context.primaryUser</code></td>
      <td>The unique user id of the primary account for the user. Used to <a href="/docs/manage-users/user-accounts/user-account-linking#automatic-account-linking">link user accounts</a> from various identity providers.</td>
    </tr>

    <tr>
      <td><code>context.authentication</code></td>

      <td>
        An object containing information related to the authentication transaction with the following properties:<br /><br /><code>methods</code>: an array of objects containing the authentication methods a user has completed during their session. For example, a user that has completed a password-based authentication followed by MFA may have the following methods:<br />

        ```json lines theme={null}
        [
          {
            "name": "pwd",
            "timestamp": 1434454643024
          },
          {
            "name": "mfa",
            "timestamp": 1534454643881
          }
        ]
        ```

        <br />

        The method objects will contain the following properties:

        <ul>
          <li>
            <code>name</code>: a string representing the name of the authentication method that has been completed. It can be one of the following values (additional values may be supported in the future):<br />

            <ul>
              <li><code>federated</code>: a social or enterprise connection was used to authenticate the user</li>
              <li><code>pwd</code>: a database connection was used to authenticate the user</li>
              <li><code>sms</code>: a <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> SMS connection was used to authenticate the user</li>
              <li><code>email</code>: a Passwordless Email connection was used to authenticate the user</li>
              <li><code>mfa</code>: the user completed a multi-factor authentication</li>
            </ul>
          </li>

          <li><code>timestamp</code>: an integer indicating the time in seconds at which the authentication method took place in Unix Epoch time</li>
        </ul>

        <p>You can see a sample use case of the <code>context.authentication.methods</code> property in the <a href="https://github.com/auth0/rules/blob/master/src/rules/require-mfa-once-per-session.js">Require MFA once per session Rule</a>.</p>
      </td>
    </tr>

    <tr>
      <td><code>context.authorization</code></td>
      <td>An object containing information related to the authorization transaction with the following properties:<ul>
      <li><code>roles</code>: an array of strings containing the names of a user's assigned <Tooltip href="/docs/glossary?term=roles">roles</Tooltip>. You can see a sample use case using the <code>context.authorization.roles</code> property to add roles to tokens in <a href="/docs/manage-users/access-control/sample-use-cases-rules-with-authorization#add-user-roles-to-tokens">Sample Use Cases: Rules with Authorization</a>.</li></ul></td>
    </tr>

    <tr>
      <td><code>context.organization</code></td>
      <td>Object containing information related to the organization. Includes the following properties:<ul>
      <li><code>id</code>: String containing the ID of the organization with which the user is logging in.</li><li><code>name</code>: String containing the name of the organization (as defined in the Auth0 Dashboard).</li><li><code>metadata</code>: Dictionary of string key/value pairs containing other organization properties.</li></ul></td>
    </tr>
  </tbody>
</table>

## Learn more

* [Debug Rules](/docs/customize/rules/debug-rules)
* [User Object Properties in Rules](/docs/customize/rules/user-object-in-rules)
* [Sample Use Cases: Scopes and Claims](/docs/get-started/apis/scopes/sample-use-cases-scopes-and-claims)


# Create Rules
Source: https://auth0.com/docs/customize/rules/create-rules

Learn how to create rules using the Auth Dashboard or the Management API.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/platform/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

<Warning>
  Because we plan to remove Rules and Hooks functions in 2026, you should create new Rules or Hooks only in your Development environment and only to test migration to Actions.

  To learn how to migrate your Rules to Actions, read [Migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions). To learn how to migrate your Hooks to Actions, read [Migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions).
</Warning>

You can build your own rule(s) to support your specific functionality requirements. You can modify a pre-existing rule template or choose to start from scratch using one of our samples. Auth0 provides a number of pre-existing rules and rule templates to help you achieve your goal(s). To see a list, visit our[rules repository on GitHub](https://github.com/auth0/rules).

## How rules work

Rules are JavaScript functions that execute when a user authenticates to your application. They run once the authentication process is complete, and you can use them to customize and extend Auth0's capabilities. For security reasons, your rules code executes isolated from the code of other Auth0 tenants in a sandbox. Rules also run during the token refresh flow. To learn more, read [Refresh Tokens](/docs/secure/tokens/refresh-tokens).

In Auth0, the authentication transaction flow works as follows when you use rules:

<Frame>
  <img alt="Rules in the Authentication Flow diagram" />
</Frame>

1. An app initiates an authentication request to Auth0.
2. Auth0 routes the request to an identity provider through a configured connection.
3. The user authenticates successfully.
4. The ID token and/or access token is passed through the rules pipeline, then sent to the application.

## Prerequisite

If you plan to use global variables in your rule, be sure to configure your rules variables first. To learn more, read [Configure Global Variables for Rules](/docs/customize/rules/configure-global-variables-for-rules).

## Use the Dashboard

1. Go to [Dashboard > Auth Pipeline > Rules](https://manage.auth0.com/#/rules) and click **Create**.

   <Frame>
     <img alt="Dashboard - Auth Pipeline - Rules " />
   </Frame>
2. Select a rule template.

   <Frame>
     <img alt="Dashboard - Auth Pipeline - Rules - Template" />
   </Frame>
3. Name the rule, modify the script to suit your needs, and click **Save changes**.

   <Frame>
     <img alt="Dashboard - Auth Pipeline - Rules - Edit Rule" />
   </Frame>

## Use the Management API

Make a `POST` call to the [Create Rule endpoint](https://auth0.com/docs/api/management/v2#!/Rules/post_rules). Be sure to replace `MGMT_API_ACCESS_TOKEN`, `RULE_NAME`, `RULE_SCRIPT`, `RULE_ORDER`, and `RULE_ENABLED` placeholder values with your <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>, rule name, rule script, rule order number, and rule enabled value, respectively.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/rules' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json' \
    --data '{ "name": "RULE_NAME", "script": "RULE_SCRIPT" }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/rules");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddHeader("cache-control", "no-cache");
  request.AddParameter("application/json", "{ "name": "RULE_NAME", "script": "RULE_SCRIPT" }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/rules"

  	payload := strings.NewReader("{ "name": "RULE_NAME", "script": "RULE_SCRIPT" }")

  	req, _ := http.NewRequest("POST", 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))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/rules")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .header("cache-control", "no-cache")
    .body("{ "name": "RULE_NAME", "script": "RULE_SCRIPT" }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/rules',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
      'cache-control': 'no-cache'
    },
    data: {name: 'RULE_NAME', script: 'RULE_SCRIPT'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                             @"cache-control": @"no-cache" };
  NSDictionary *parameters = @{ @"name": @"RULE_NAME",
                                @"script": @"RULE_SCRIPT" };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/rules"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/rules",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "name": "RULE_NAME", "script": "RULE_SCRIPT" }",
    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;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "name": "RULE_NAME", "script": "RULE_SCRIPT" }"

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
      'cache-control': "no-cache"
      }

  conn.request("POST", "/{yourDomain}/api/v2/rules", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/rules")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request["cache-control"] = 'no-cache'
  request.body = "{ "name": "RULE_NAME", "script": "RULE_SCRIPT" }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control": "no-cache"
  ]
  let parameters = [
    "name": "RULE_NAME",
    "script": "RULE_SCRIPT"
  ] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/rules")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th><strong>Value</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>MGMT\_API\_ACCESS\_TOKEN</code></td>
      <td>Access Token for the Management API with the scope <code>create:rules</code>.</td>
    </tr>

    <tr>
      <td><code>RULE\_NAME</code></td>
      <td>Name of the rule you would like to create. The rule name can only contain alphanumeric characters, spaces, and hyphens; it may not start or end with spaces or hyphens.</td>
    </tr>

    <tr>
      <td><code>RULE\_SCRIPT</code></td>
      <td>Script that contains the code for the rule. Should match what you would enter if you were creating a new rule using the Dashboard.</td>
    </tr>

    <tr>
      <td><code>RULE\_ORDER</code> (optional)</td>
      <td>Integer that represents the order in which the rule should be executed in relation to other rules. Rules with lower numbers are executed before rules with higher numbers. If no order number is provided, the rule will execute last.</td>
    </tr>

    <tr>
      <td><code>RULE\_ENABLED</code> (optional)</td>
      <td>Boolean that represents whether the rules is enabled (<code>true</code>) or disabled (<code>false</code>).</td>
    </tr>
  </tbody>
</table>

<Warning>
  We expose IPv6 addresses in our public endpoints (e.g., `travel0.us.auth0.com`). If a request arrives from a machine that supports IPv6, then the `context.request.ip` property will contain an IPv6 address. If you perform manual IP address manipulation, we suggest you use the [ipaddr.js@1.9.0 library](https://www.npmjs.com/package/ipaddr.js/v/1.9.0).
</Warning>

## Manage rate limits

For rules that call Auth0 APIs, you should always handle rate limiting by checking the `X-RateLimit-Remaining` header and acting appropriately when the number returned nears 0. You should also add logic to handle cases in which you exceed the provided rate limits and receive the HTTP Status Code 429 (Too Many Requests); in this case, if a retry is needed, it is best to allow for a back-off to avoid going into an infinite retry loop. To learn more about rate limits, read [Rate Limit Policy For Auth0 APIs](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy).

## Available modules

Rules run in a JavaScript sandbox configured for a specific Node.js version.

The sandbox supports all versions of the JavaScript language (and associated syntax) for the configured Node.js version, and a large number of Node.js modules. For a list of supported sandbox modules, check out [Can I require: Auth0 Extensibility](https://auth0-extensions.github.io/canirequire/).

## Learn more

* [Configure Global Variables for Rules](/docs/customize/rules/configure-global-variables-for-rules)


# Debug Rules
Source: https://auth0.com/docs/customize/rules/debug-rules

Learn how to debug your Auth0 rules.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

<Warning>
  We expose IPv6 addresses in our public endpoints (e.g., `travel0.us.auth0.com`). If a request arrives from a machine that supports IPv6, then the `context.request.ip` property will contain an IPv6 address. If you perform manual IP address manipulation, we suggest you use the [ipaddr.js@1.9.0 library](https://www.npmjs.com/package/ipaddr.js/v/1.9.0).
</Warning>

To debug any [Auth0 Rule](/docs/customize/rules) you have created, you can use `console.log` from within your rule code. You can see `console.log` output by using the **Save and Try**, viewing the logs available with the [Actions Real-time Logs](/docs/customize/actions/actions-real-time-logs), or for legacy clients, using the [Debug Rule CLI](#debug-rule-cli).

<Frame>
  <img alt="Dashboard - Auth Pipeline - Rules - Edit Rule" />
</Frame>

## Try this Rule

In the [Rules Editor](https://manage.auth0.com/#/rules/create), the **Save and Try** button lets you run a Rule in isolation with mock **user** and **context** objects. Clicking **TRY** will run the Rule with those two objects as input and will display any `console.log` output.

The **Try this rule script** feature functions outside a specific client context. When using this feature, you may run into issues if your Rule depends on data that would be provided when called from an actual application.

<Frame>
  <img alt="Auth0 Pipeline - Rules - Try this rule" />
</Frame>

## Actions Real-time Logs

The Actions Real-time Logs displays all logs in real-time for all custom code in your account, which includes all `console.log` output and exceptions. To learn more, read [Actions Real-time Logs](/docs/customize/actions/actions-real-time-logs).


# Raise Errors from Rules
Source: https://auth0.com/docs/customize/rules/raise-errors-from-rules

The Auth0 login page can’t display an error message from a rule. Learn what to do instead.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

The Auth0 login page can’t display an error message from a rule. If you want users to see a custom message raised from a rule, your app must display that message.

Any error resulting from a rule goes to your callback URL in the protocol’s standard response mode. For example, if your application requests authentication using OIDC/OAuth2, it receives a standard OAuth2 error with `error` and `error_description` result values.

Suppose your callback URL is [https://travel0.com/callback](https://travel0.com/callback) and you’re using the standard query response mode. You would receive this response:

```http wrap lines theme={null}
https://travel0.com/callback?error=access_denied&error_description=[The message you wrote in the rule]
```

It’s the role of your app to display the message to the user, such as:

<Frame>
  <img alt="Sample error message that reads " />
</Frame>

## Retry login after a rule error

A likely next step is to request a new authorization. However, in most cases, Auth0 already knows who the user is and so doesn’t ask for login information. Instead, rules run immediately and the rule denies authorization again. This can become an endless loop.

The user needs an opportunity to provide new credentials. There are two ways your app can make the login page display again:

* Add a directive in the request to force the display of the login page:

  * Use a `prompt=login` parameter to an OIDC/OAuth2 request.
  * Use a `ForceAuthn="true"` attribute in a SAML request.

—or—

* Log the user out of Auth0 before you send a new request.

## Learn more

* [Auth0 Rules](/docs/customize/rules)
* [Log Users Out of Applications](/docs/authenticate/login/logout/log-users-out-of-applications)
* [Rule Use Cases](/docs/customize/rules/use-cases)


# Redirect Users from Within Rules
Source: https://auth0.com/docs/customize/rules/redirect-users

Learn how to customize authentication flows by redirecting users using rules. Example areas that can be customized include MFA, privacy policy acceptance, and gathering user data.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/platform/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

You can use [Auth0 Rules](/docs/customize/rules) to redirect users before an authentication transaction is complete. This lets you implement custom authentication flows that require additional user interaction beyond the standard login form. Redirect rules are commonly used to do custom <Tooltip href="/docs/glossary?term=Multi-factor+Authentication">Multi-factor Authentication</Tooltip> (MFA) in Auth0, but they can also be used for:

* Custom privacy policy acceptance, terms of service, and data disclosure forms.
* Securely performing a one-time collection of additional required profile data.
* Allowing remote Active Directory users to change their password.
* Requiring users to provide additional verification when logging in from unknown locations.
* Gathering more information about your users than they provided at initial signup.

You can redirect a user **once** per authentication flow. If you have one rule that redirects a user, you **cannot** invoke a second rule to redirect the user at a later time.

To learn more, see [Multi-Factor Authentication in Auth0](/docs/secure/multi-factor-authentication).

## Start redirect and resume authentication

Set the `context.redirect` property as follows:

```javascript lines theme={null}
function (user, context, callback) {
  context.redirect = {
    url: "https://example.com/foo"
  };
  return callback(null, user, context);
}
```

Once all rules have finished executing, Auth0 redirects the user to the URL specified in the `context.redirect.url` property. Auth0 also passes a `state` parameter in that URL. For example:

```http lines theme={null}
https://example.com/foo?state=abc123
```

Your redirect URL needs to extract the `state` parameter and send it back to Auth0 to resume the authentication transaction. State is an opaque value, used to prevent [Cross-Site Request Forgery (CSRF) attacks](/docs/secure/security-guidance/prevent-threats#cross-site-request-forgery).

After the redirect, resume authentication by redirecting the user to the `/continue` endpoint and include the `state` parameter you received in the URL. If you do not send the original state back to the `/continue` endpoint, Auth0 will lose the context of the login transaction and the user will not be able to log in due to an `invalid_request` error.

For example:

<AuthCodeBlock />

If you're using a <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip>:

```http lines theme={null}
https://{yourAuth0CustomDomain}/continue?state={originalState}
```

`THE_ORIGINAL_STATE` is the value that Auth0 generated and sent to the redirect URL. For example, if your rule redirected to `https://example.com/foo`, Auth0 would use a redirect URL similar to `https://example.com/foo?state=abc123`. So `abc123` would be the `THE_ORIGINAL_STATE`. To resume the authentication transaction, you would redirect to:

<AuthCodeBlock />

When a user has been redirected to the `/continue` endpoint:

* **all rules will be run again**, however, the `context.redirect` will be ignored to allow authentication to continue.
* any changes to the user object are made during the redirect, prior to calling the `/continue` endpoint. For example, updates through the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> are available after continuing the transaction.

## Validate resumed login

To distinguish between user-initiated logins and resumed login flows, check the `context.protocol` property:

```javascript lines theme={null}
function (user, context, callback) {
    if (context.protocol === "redirect-callback") {
        // User was redirected to the /continue endpoint
    } else {
        // User is logging in directly
    }
}
```

## Force password change example

In some cases, you may want to force users to change their passwords under specific conditions. You can write a rule that has the following behavior:

1. The user attempts to log in and needs to change their password.
2. The user is redirected to an application-specific page with a JWT in the query string. This JWT ensures that only this user's password can be changed and **must be validated** by the application.
3. The user changes their password in the application-specific page by having the application call the [Auth0 Management API](https://auth0.com/docs/api/management/v2/users/patch-users-by-id)
4. Once the user has successfully changed their password, the application extracts the `authorize_again` claim from the verified and decoded JWT, then proceeds to redirect the user to that URL allowing them to sign in with their new password.

```javascript lines expandable theme={null}
function(user, context, callback) {
   /*
   * Prerequisites:
   * 1. Implement a `mustChangePassword` function
   * 2. Set configuration variables for the following:
   *    - CLIENT_ID
   *    - CLIENT_SECRET
   *    - ISSUER
   */

  const url = require('url@0.10.3');
  const req = context.request;

  function mustChangePassword() {
    // TODO: implement function
    return true;
  }

  if (mustChangePassword()) {
    // User has initiated a login and is forced to change their password
    // Send user's information and query params in a JWT to avoid tampering
    function createToken(clientId, clientSecret, issuer, user) {
      const options = {
        expiresInMinutes: 5,
        audience: clientId,
        issuer: issuer
      };
      return jwt.sign(user, clientSecret, options);
    }

    const token = createToken(
      configuration.CLIENT_ID,
      configuration.CLIENT_SECRET,
      configuration.ISSUER,
      {
        sub: user.user_id,
        email: user.email,
        authorize_again: url.format({
          protocol: 'https',
          hostname: auth0.com,
          pathname: '/authorize',
          query: req.query
        })
      }
    );

    context.redirect = {
      url: `https://example.com/change-pw?token=${token}`
    };
  }

  return callback(null, user, context);
}
```

## Where to store data

Beware of storing too much data in the Auth0 profile. This data is intended to be used for authentication and authorization purposes. The metadata and search capabilities of Auth0 are not designed for marketing research or anything else that requires heavy search or update frequency. Your system is likely to run into scalability and performance issues if you use Auth0 for this purpose. A better approach is to store data in an external system and store a pointer (the user ID) in Auth0 so that backend systems can fetch the data if needed. A simple rule to follow is to store only items that you plan to use in rules to add to tokens or make decisions.

## Security considerations

Passing information back and forth in the front channel opens up surface area for <Tooltip href="/docs/glossary?term=bad+actors">bad actors</Tooltip> to attack. This should definitely be done only in conditions where you must take action in the rule (such as rejecting the authorization attempt with `UnauthorizedError`).

If, however, you need to communicate directly back to Auth0 and give it instructions for restricting access (you are implementing CAPTCHA checks or custom MFA), then you must have a way to securely tell Auth0 that the requirements of that operation were performed. Likewise, if you need to hand information to the application that you are redirecting to, then you must have a secure way to ensure that the information transferred has not been tampered with.

### Ensure app is logging into the same user

The application is going to redirect the user back to the Auth0 tenant, so any data related to the user can be gathered through the <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> that is returned to the application. However, you may want to ensure that the application is logging into the same user that is being redirected from to ensure that there is no tampering of any sort in-between. Therefore you will likely want to send a token along with the request.

The token sent to the app should have the following requirements:

<table>
  <thead>
    <tr>
      <th>Token Element</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>sub</code></td>
      <td>The Auth0 <code>user\_id</code> of the user.</td>
    </tr>

    <tr>
      <td><code>iss</code></td>
      <td>An identifier that identifies the rule itself.</td>
    </tr>

    <tr>
      <td><code>aud</code></td>
      <td>The application that is targeted for the redirect.</td>
    </tr>

    <tr>
      <td><code>jti</code></td>
      <td>A randomly generated string that is stored for confirmation in the user object (in the rule code, set user.jti = uuid.v4(); and then add it as a jti to the token you create).  user.jti will still be set when rules run again when /continue is called.  This is inline with specifications.</td>
    </tr>

    <tr>
      <td><code>exp</code></td>
      <td>Should be as short as possible to avoid re-use of the token.</td>
    </tr>

    <tr>
      <td><code>other</code></td>
      <td>Any other custom claims information you need to pass.</td>
    </tr>

    <tr>
      <td><code>signature</code></td>
      <td>Assuming that the application has a secure place to store a secret, you can use HS256 signed signatures.  This greatly reduces the complexity of the solution and since the token being passed back will have to be signed as well, this is a requirement of this solution.  You can use RS256, but it requires the creating of a certificate and updating that certificate when it expires.  If you are not passing any information directly back to the rules, then you could use an SPA for this intermediate app and then may prefer RS256 so that the application doesn't have to store the info.  It would require you to have a way to validate the token, either through an introspection endpoint or through a public JWKS endpoint.</td>
    </tr>
  </tbody>
</table>

<Warning>
  This token should **not** be treated as a Bearer token! It is a signed piece of information for use in the application. The application should still redirect back to Auth0 to authenticate the user.
</Warning>

### Pass information back to the rule

In most scenarios, even if you want to pass information from the rule to the application. The application will hopefully be able to safely store the information in whatever storage is necessary. Even if the idea is to update the app or user metadata in Auth0, that can be done using the management API and the user information will be updated as long as it has been completed before redirecting the user back to the `/continue` endpoint. Only if the rule itself must get information and that information is only relevant to this particular sign in session should you pass information back to the rule.

When passing information back to the `/continue` endpoint, the token passed should have the following requirements:

<table>
  <thead>
    <tr>
      <th>Token Element</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>sub</code></td>
      <td>The Auth0 <code>user\_id</code> of the user.</td>
    </tr>

    <tr>
      <td><code>iss</code></td>
      <td>The application that is targeted for the redirect.</td>
    </tr>

    <tr>
      <td><code>aud</code></td>
      <td>Some identifier that identifies the rule itself.</td>
    </tr>

    <tr>
      <td><code>jti</code></td>
      <td>The same JTI that was stored in the token passed to the application (NOTE: it should match user.jti or fail).</td>
    </tr>

    <tr>
      <td><code>exp</code></td>
      <td>Should be as short as possible to avoid reuse of the token.</td>
    </tr>

    <tr>
      <td><code>other</code></td>
      <td>Any other custom claims information you need to pass.</td>
    </tr>

    <tr>
      <td><code>signature</code></td>
      <td>Assuming that the application has a secure place to store a secret, you can use HS256 signed signatures.  This greatly reduces the complexity of the solution and since the token being passed back will have to be signed as well, this is a requirement of this solution.  You can use RS256, but it requires the creating of a certificate and updating that certificate when it expires.</td>
    </tr>
  </tbody>
</table>

It should be sent using POST and then fetched at `context.request.body.token` (or something similar) rather than passing it as a query parameter. This is similar to the form-post method for authentication.

If you are not passing information back to the `/continue` endpoint, you may want to denylist the JTI unless your expiration times are short enough that replay attacks will be almost impossible.

## Restrictions and limitations

Redirect Rules won't work with:

* [Resource Owner endpoint](https://auth0.com/docs/api/authentication/reference#resource-owner)
* [Password exchange](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow)
* [Refresh Token exchange](/docs/secure/tokens/refresh-tokens)

You can detect the above cases by checking `context.protocol`:

* For Password exchange: `context.protocol === 'oauth2-password'`
* For <Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip> exchange: `context.protocol === 'oauth2-refresh-token'`
* For <Tooltip href="/docs/glossary?term=Resource+Owner">Resource Owner</Tooltip> logins: `context.protocol === 'oauth2-resource-owner'`

### Session timeout

Redirect rule sessions are normally valid for 3 days unless you have configured a shorter timeout in your **Login Session Management** settings. You can find these settings in your [tenant's advanced settings](https://manage.auth0.com/#/tenant/advanced).

### Resource Owner endpoint

It is impossible to use redirect rules in the context where you are calling `/oauth/token` directly for the Resource Owner Password Grant. Since the user is not in a redirect flow to begin with, you can not redirect the user in a rule. If you attempt to set context.redirect you will get a failed login attempt with the error interaction\_required.

### Flows where prompt=none

Since the goal of `prompt=none` is to avoid any scenario where the user will be required to enter input, any redirection will result in an `error=interaction_required`.

Since rules run after an authentication session is created, you cannot use `prompt=none` if you have a redirect rule that is attempting to block access to tokens under certain conditions (custom MFA, CAPTCHA with login, etc.).

You cannot create a redirect flow that blocks token access and bypasses the redirect rule if `prompt=none` because after a failed attempt, a user can simply call again with `prompt=none` and get tokens because their authentication session has been created even though rules failed the first time.

### Refresh tokens

Due to the fact that using a refresh token requires a backchannel call to `/oauth/token`, this will also fail if you set `context.redirect`.

It is difficult to securely verify that any restrictions on login were carried out. There is not a consistent session ID in the context that could be used to collect information associated with the session such as this user passed MFA challenges. Therefore, you cannot use `prompt=none` at all.

Anytime `context.redirect` is set in a rule, if `prompt=none` was passed, then the authorization fails with `error=interaction_required`, but since the user's session is created even if rules fail, we can't trust that a user passed all `context.redirect` challenges and therefore can't use `prompt=none` as a way to get tokens.

In this specific case, we recommend that you use refresh tokens exclusively, because you can ensure that a user passed challenges if those challenges are required to generate a refresh token.

## Learn more

* [Redirect Users](/docs/authenticate/login/redirect-users-after-login)
* [Understand How Progressive Profiling Works](/docs/manage-users/user-accounts/user-profiles/progressive-profiling)
* [Redirect Users with Alternative Logout](/docs/authenticate/login/logout/redirect-users-after-logout)


# Use the Management API from within Rules
Source: https://auth0.com/docs/customize/rules/use-management-api

Learn how to use the Management API from within rules.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/platform/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

From within any [Auth0 Rule](/docs/customize/rules) you write, you can update a user's `app_metadata` or `user_metadata` using the `auth0` object, which is a specially-restricted instance of `ManagementClient` (defined in the [node-auth0](https://github.com/auth0/node-auth0) Node.js client library) and provides limited access to the [Auth0 Management API](https://auth0.com/docs/api/management/v2).

To access additional <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> endpoints from inside Rules, you have to use another version of the library.

<Callout icon="file-lines">
  The Access Token for the Management API, which is available through `auth0.accessToken`, is limited to the `read:users` and `update:users` scopes. If you require a broader range of scopes, you can request a token using the Client Credentials Flow. See [Get Management API Access Tokens for Production](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production).
</Callout>

## Access a newer version of the library

You can load a newer version of the Auth0 Node.js client library by requiring the specific version of the library. For up-to-date version information, check the [Auth0 Node repository](https://github.com/auth0/node-auth0) in Github.

In this example, we load version `2.9.1` of the library, then query the list of users and logs the users to the console (to be inspected with [Actions Real-time Logs](/docs/customize/actions/actions-real-time-logs)).

<Warning>
  [Searching for users](/docs/manage-users/user-search/user-search-best-practices) from inside Rules may affect the performance of your logins; we advise against it.
</Warning>

```javascript lines theme={null}
function (user, context, callback) {
  var ManagementClient = require('auth0@2.9.1').ManagementClient;
  var management = new ManagementClient({
    token: auth0.accessToken,
    domain: auth0.domain
  });

  management.getUsers(function (err, users) {
    console.log(users);
    callback(null, user, context);
  });
}
```

<Callout icon="file-lines">
  For a filtered list of available libraries that can be set as required, check the [available library versions](https://auth0-extensions.github.io/canirequire/#auth0).
</Callout>


# User Object Properties in Rules
Source: https://auth0.com/docs/customize/rules/user-object-in-rules

Describes the properties of the user object that stores information about the logged in user, returned by the identity provider.

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

The `user` object stores information about the logged-in user, returned by the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>. It is generated when a user authenticates and before rules run. Because of the order of events when a user authenticates, changes made to a user's profile from within a rule will only be available in the current user object if you also save the changes to the user object from within the same rule.

To learn more about the authentication transaction flow, read the "How rules work" section in [Create Rules](/docs/customize/rules/create-rules).

<Warning>
  Use unique names for root properties in the user object and properties within `app_metadata`. Because properties within `app_metadata` are merged into the user object, root properties that share names with properties in `app_metadata` may have their values overwritten when running rules.
</Warning>

## Properties

The following properties are available for the `user` object.

<table>
  <thead>
    <tr>
      <th>Property</th>
      <th>Data Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>user.app\_metadata</code></td>
      <td>object</td>
      <td>Custom fields that store info about a user that influences the user's access, such as support plan, security roles, or access control groups. Is `undefined` by default. For more info, see <a href="/docs/manage-users/user-accounts/metadata">Metadata</a>.</td>
    </tr>

    <tr>
      <td><code>user.created\_at</code></td>
      <td>date time</td>
      <td>Timestamp indicating when the user profile was first created.</td>
    </tr>

    <tr>
      <td><code>user.email</code></td>
      <td>text</td>
      <td>(unique) User's email address.</td>
    </tr>

    <tr>
      <td><code>user.email\_verified</code></td>
      <td>boolean</td>
      <td>Indicates whether the user has verified their email address.</td>
    </tr>

    <tr>
      <td><code>user.family\_name</code></td>
      <td>text</td>
      <td>User's family name.</td>
    </tr>

    <tr>
      <td><code>user.given\_name</code></td>
      <td>text</td>
      <td>User's given name.</td>
    </tr>

    <tr>
      <td><code>user.identities</code></td>
      <td>array (object)</td>

      <td>
        Contains info retrieved from the identity provider with which the user originally authenticates. Users may also <a href="/docs/manage-users/user-accounts/user-account-linking">link their profile to multiple identity providers</a>; those identities will then also appear in this array. The contents of an individual identity provider object varies by provider, but it will typically include the following:<ul>
        <li><code>connection</code> (text): Name of the Auth0 connection used to authenticate the user.</li>
        <li><code>isSocial</code> (boolean): Indicates whether the connection is a social one.</li>
        <li><code>provider</code> (text): Name of the entity that is authenticating the user, such as Facebook, Google, SAML, or your own provider.</li>
        <li><code>user\_id</code> (text): User's unique identifier for this connection/provider. The first user\_id linked becomes the primary unique identifier for the user.</li>
        <li><code>profileData</code> (object): User information associated with the connection. When profiles are linked, it is populated with the associated user info for secondary accounts.</li></ul>
        In some cases, it will also include an API <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> to be used with the provider.
      </td>
    </tr>

    <tr>
      <td><code>user.last\_password\_reset</code></td>
      <td>date time</td>
      <td>Timestamp indicating the last time the user's password was reset/changed. At user creation, this field does not exist. This property is only available for Database connections.</td>
    </tr>

    <tr>
      <td><code>user.multifactor</code></td>
      <td>array (text)</td>
      <td>List of multi-factor authentication (MFA) providers with which the user is enrolled. This array is updated when the user enrolls in MFA and when an administrator resets a user's MFA enrollments.</td>
    </tr>

    <tr>
      <td><code>user.name</code></td>
      <td>text</td>
      <td>User's full name.</td>
    </tr>

    <tr>
      <td><code>user.nickname</code></td>
      <td>text</td>
      <td>User's nickname.</td>
    </tr>

    <tr>
      <td><code>user.permissions</code></td>
      <td>text</td>
      <td>Permissions assigned to the user's ID token if using the Authorization Extension.</td>
    </tr>

    <tr>
      <td><code>user.phone\_number</code></td>
      <td>text</td>
      <td>User's phone number. Only valid for users with SMS connections.</td>
    </tr>

    <tr>
      <td><code>user.phone\_verified</code></td>
      <td>boolean</td>
      <td>Indicates whether the user has verified their phone number. Only valid for users with SMS connections.</td>
    </tr>

    <tr>
      <td><code>user.picture</code></td>
      <td>text</td>
      <td>URL pointing to <a href="/docs/manage-users/user-accounts/change-user-picture">the user's profile picture</a>.</td>
    </tr>

    <tr>
      <td><code>user.updated\_at</code></td>
      <td>date time</td>
      <td>Timestamp indicating when the user's profile was last updated/modified. Changes to <code>last\_login</code> are considered updates, so most of the time, <code>updated\_at</code> will match <code>last\_login</code>.</td>
    </tr>

    <tr>
      <td><code>user.user\_id</code></td>
      <td>text</td>
      <td>(unique) User's primary unique identifier.</td>
    </tr>

    <tr>
      <td><code>user.user\_metadata</code></td>
      <td>object</td>
      <td>Custom fields that store info about a user that does not impact what they can or cannot access, such as work address, home address, or user preferences. For more info, see <a href="/docs/manage-users/user-accounts/metadata">Metadata</a>.</td>
    </tr>

    <tr>
      <td><code>user.username</code></td>
      <td>text</td>
      <td>(unique) User's username.</td>
    </tr>
  </tbody>
</table>


# Auth0 Marketplace
Source: https://auth0.com/docs/customize/auth0-marketplace





# Secure Apigee with Auth0
Source: https://auth0.com/docs/customize/integrations/apigee

Learn how to use Auth0 to secure access to API proxies developed and managed by Apigee Edge.

If you are using Apigee Edge for developing and managing your backend service APIs, you can use Auth0 to secure access to your API proxies.

## Prerequisites

Before you begin, you'll need to:

1. Have an Apigee Edge API proxy that needs to be secured. To learn more, read Apigee's [Get Started](https://docs.apigee.com/api-platform/get-started/get-started) article.
2. [Sign up](https://auth0.com/signup) for an account with Auth0.

The process of building your API proxy is outside the scope of this article. Instead, we will focus on securing an API proxy that you already have using Auth0.

## Create a custom API

First, [register your Apigee Edge API Proxy using the Dashboard](/docs/get-started/auth0-overview/set-up-apis). Auth0 needs to recognize Apigee as an <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> to make sure that any <Tooltip href="/docs/glossary?term=Access+Tokens">Access Tokens</Tooltip> issued are issued with the correct audience. The user authenticates with Auth0 via the application, and the application specifies this audience value to make sure that the Access Token possesses the right scopes for the audience provided.

You'll need to do the following:

1. Provide a name for your API (e.g., `apigee`).
2. Provide an identifier for your API: `urn:apigee:target:api`
3. Choose a signing algorithm: `RS256` (default)

When you register your Apigee Edge API Proxy, Auth0 also creates a **Machine to Machine (M2M)** application on your behalf and names it to match the API you registered. You can use this application for testing; it is automatically configured to be authorized to call your API.

## Note variables from the test application

Switch to the test application created when registering your API and make note of the variables that were set during the process of registering your API and creating the associated M2M application. You will need them for subsequent steps of this tutorial.

1. Navigate to the [Auth0 Dashboard > Applications](https://manage.auth0.com/#/applications)], and click the name of your test application.
2. Scroll down and make note of the following variables:

   * API audience
   * Auth0 domain
   * Client ID
   * Allowed callback URL(s): The URLs to which the user can be redirected after authentication. You can specify multiple URLs by comma-separating them. (This is typically done to handle different environments where each needs its own redirects.)

## Implement the Client Credentials flow

Now you're ready to implement the Client Credentials Flow to request the Access Tokens you can provide to Apigee Edge. Note that in this scenario, you will use the Client Credentials Flow because you are using Apigee with your backend service APIs, which represents a Machine-to-Machine (M2M) application; other scenarios may require the use of different flows.

To learn how to log in and get an Access Token that can be used to call Apigee Edge, see [Call API Using the Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow/call-your-api-using-the-client-credentials-flow).

## Validate the Access Token

Once you've requested and received an Access Token from Auth0, you'll be able to use it to call the API proxy you set up with Edge.

When you [use your Access Token](https://docs.apigee.com/api-platform/security/oauth/using-access-tokens.html), the first thing Apigee Edge will do is [verify the token](https://docs.apigee.com/api-platform/security/oauth/using-access-tokens.html#addingaverifyaccesstokenpolicy).

Auth0 Access Tokens are <Tooltip href="/docs/glossary?term=JSON+Web+Tokens">JSON Web Tokens</Tooltip> (JWTs), so you can take advantage of Apigee Edge's Verify JWT policy to do this. To learn more, read Apigee's [Verify JWT policy signed with the RS256 algorithm](https://docs.apigee.com/api-platform/reference/policies/verify-jwt-policy#verify-a-jwt-signed-with-the-rs256-algorithm) article.

Apigee Edge will verify the token before anything else happens; if the token is rejected, then all processing will stop and Edge will return an error to the client.

## Testing

To test your implementation, make an HTTP POST call to Apigee Edge with the Auth0-issued Access Token included in the header of the call. You can learn how by reviewing Apigee's [Calling the protected API](https://docs.apigee.com/api-platform/security/oauth/oauth-20-client-credentials-grant-type.html#callingtheprotectedapi) article.

When you receive a successful response, extract the token and review it to verify the inclusion of required/requested user claims.


# Authenticating & Authorizing Devices using MQTT with Auth0
Source: https://auth0.com/docs/customize/integrations/authenticate-devices-using-mqtt

How to authenticate and authorize devices using MQTT with Auth0.

MQTT is a lightweight protocol often used for devices to communicate with other systems. It is designed for the **publish/subscribe** messaging pattern. You can read more about [MQTT](https://en.wikipedia.org/wiki/MQ_Telemetry_Transport) on Wikipedia.

Generally speaking there are 3 components:

1. A `publisher` of messages.
2. A `subscriber` to messages.
3. A `broker` that connects one and the other.

There's a notion of `topics` (a.k.a. as `channels` or `subjects`) which messages are associated with. Topics are used to route messages between publishers and subscribers.

The MQTT protocol supports a basic authentication mechanism based on `usernames` & `passwords`. These credentials are sent with the `CONNECT` message.

This article shows an integration between nodejs based MQTT broker: [mosca](https://github.com/moscajs/mosca) and [Auth0](https://auth0.com). In this example, Auth0 is used to **authenticate** `publishers` and `subscribers` to the broker, and then **authorize** routing of messages.

<Frame>
  <img alt="MQTT Data Flow Diagram" />
</Frame>

## Components of the solution

### The Broker

**mosca** is straightforward to host and can be embedded in other servers. For the purpose of this sample, we simply self-host a **mosca** server:

```javascript lines expandable theme={null}
var mosca = require('mosca')
var Auth0Mosca = require('auth0mosca');

var settings = {
  port: 9999,
};

//'Thermostats' is a Database connection where all devices are registered.
var auth0 = new Auth0Mosca('https://eugeniop.auth0.com', '{Your Auth0 ClientID}', '{Your Auth0 Client Secret}','Thermostats');

//Setup the Mosca server
var server = new mosca.Server(settings);

//Wire up authentication & authorization to mosca
server.authenticate = auth0.authenticateWithCredentials();
server.authorizePublish = auth0.authorizePublish();
server.authorizeSubscribe = auth0.authorizeSubscribe();

server.on('ready', setup);

// Fired when the mqtt server is ready
function setup() {
    console.log('Mosca server is up and running');
}

server.on('clientConnected', function(client) {
  console.log('New connection: ', client.id );
});
```

This creates a server listening for MQTT messages on port 9999. **mosca** allows you to override the 3 functions used to authenticate and authorize operations.

In this sample, we are using a very simple module `auth0mosca` to perform these functions. Auth0 is wired up to **mosca**.

### The Auth0Mosca module

This little [module](https://www.npmjs.org/package/auth0mosca) provides the 4 functions used by **mosca**, `authenticateWithCredentials`, `authenticateWithJWT`, `authorizePublish` and `authorizeSubscribe`:

```javascript lines expandable theme={null}
var request = require('request');
var jwt = require('jsonwebtoken');

function Auth0Mosca(auth0Namespace, clientId, clientSecret, connection)
{
  this.auth0Namespace = auth0Namespace;
  this.connection = connection;
  this.clientId = clientId;
  this.clientSecret = clientSecret;
}

Auth0Mosca.prototype.authenticateWithJWT = function(){

  var self = this;

  return function(client, username, password, callback) {

    if( username !== 'JWT' ) { return callback("Invalid Credentials", false); }

    // console.log('Password:'+password);

    jwt.verify(password, self.clientSecret, function(err,profile){
          if( err ) { return callback("Error getting UserInfo", false); }
          console.log("Authenticated client " + profile.user_id);
          console.log(profile.topics);
          client.deviceProfile = profile;
          return callback(null, true);
        });
  }
}

Auth0Mosca.prototype.authenticateWithCredentials = function(){

  var self = this;

  return function(client, username, password, callback) {
    
    var data = {
        client_id:   self.clientId, // {client-name}
        username:    username.toString(),
        password:    password.toString(),
        connection:  self.connection,
        grant_type:  "password",
        scope: 'openid name email' //Details: https:///scopes
    };

    request.post({
        headers: {
                "Content-type": "application/json"
            },
        url: self.auth0Namespace + '/oauth/ro',
        body: JSON.stringify(data)
      }, function(e,r,b){
        if(e){
          console.log('Error in Authentication');
          return callback(e,false);
        }
        var r = JSON.parse(b);

        if( r.error ) { return callback( r, false); }

        jwt.verify(r.id_token, self.clientSecret, function(err,profile){
          if( err ) { return callback("Error getting UserInfo", false); }
          client.deviceProfile = profile;
          return callback(null, true);
        });
    });
  }
}

Auth0Mosca.prototype.authorizePublish = function() {
  return function (client, topic, payload, callback) {
   callback(null, client.deviceProfile && client.deviceProfile.topics && client.deviceProfile.topics.indexOf(topic) > -1);
  }
}

Auth0Mosca.prototype.authorizeSubscribe = function() {
  return function(client, topic, callback) {
  callback(null, client.deviceProfile && client.deviceProfile.topics && client.deviceProfile.topics.indexOf(topic) > -1);
}

module.exports = Auth0Mosca;
```

`authenticateWithCredentials` uses the [OAuth2 Resource Owner Password Credential Grant](/docs/authenticate/protocols) to authenticate the broker and all connections to it. Each time a `publisher` or a `subscriber` send a **CONNECT** message to the broker the `authenticate` function is called. In it we call the Auth0 endpoint and forward the device's `username`/`password`. Auth0 validates this against its account store (that is the first `request.post` in the code). If successful, it validates and parses the <Tooltip href="/docs/glossary?term=JSON+Web+Token">JSON Web Token</Tooltip> (JWT) to obtain the device profile and adds it to the `client` object that represents either the `subscriber` or the `publisher`. That's done in the `jwt.verify` call.

By convention, all devices connected to the broker have an account in Auth0.

Notice that the Device Profile also has a property `topics`. This is an array with all topics this particular device is allowed to. In the screenshot above, `thermostat-1a` will be allowed publishing (or subscribing) to topics `temperature` and `config`.

The `authorizePublish` and `authorizeSubscribe` functions simply check that a particular requested topic is present in this list.

The `authenticateWithJWT` expects a JWT in the `password` field. The flow in this case is slightly different:

1. The publisher & subscriber will obtain a token
2. They connect to `mosca` submitting the JWT
3. `mosca` validates the JWT
4. Messages are sent and re-transmitted to subscribers

<Frame>
  <img alt="MQTT JSON Web Token Data Flow " />
</Frame>

Publishers and subscribers will obtain the JWT through some means. Notice that the broker doesn't need to communicate with Auth0 anymore. JWTs are self-contained artifacts that can be validated with the secret used to sign them.

### The Publisher

For this sample, the publisher is a simple nodejs program that uses the `mqtt` module, and adds the right credentials:

```javascript lines expandable theme={null}
var mqtt = require('mqtt')
  , host = 'localhost'
  , port = '9999';

var settings = {
  keepalive: 1000,
  protocolId: 'MQIsdp',
  protocolVersion: 3,
  clientId: 'Thermostat 1a',
  username:'thermostat-1a',
  password:'the password'
}

// client connection
var client = mqtt.createClient(port, host, settings);

setInterval(sendTemperature, 2000, client);

function sendTemperature(client){
  var t = {
    T: Math.random() * 100,
    Units: "C"
  };

  client.publish('temperature', JSON.stringify(t));
}
```

Of course `username` & `password` here will have to match whatever is stored in Auth0.

### The subscriber

The subscriber is very similar to the publisher:

```javascript lines expandable theme={null}
var mqtt = require('mqtt')
  , host = 'localhost'
  , port = '9999';

var settings = {
  keepalive: 1000,
  protocolId: 'MQIsdp',
  protocolVersion: 3,
  clientId: 'Reader-X1',
  username:'reader-X1',
  password:'the password'
}

// client connection
var client = mqtt.createClient(port, host, settings);


client.subscribe('temperature');

client.on('message', function(topic, message) {

  if(topic ==='temperature')
  {
    console.log('New reading', message);
  }
});
```

## Summary

This shows how easy it is to use Auth0 in various scenarios. Auth0's user store is being used to manage devices. Of course much more sophisticated authorization rules could be written based on other conditions: time, location, device\_id, and so on All these would be very simple to implement, either through additional profile attributes or through Rules. This also shows how the flexible Auth0 Profile can be extended to support arbitrary artifacts (such as `topics` in the example).

To learn more about Rules, you can review [Auth0 Rules](/docs/customize/rules).

Ιt is never a good idea to send credentials (`username`/`password`) over unsecured networks. There are other implementations that provide transport level security that would prevent message contents to be revealed. **mosca** supports TLS as an example. Likely a production deployment would favor this, unless all traffic happens in a closed network.

### Acknowledgements

Many thanks to Matteo Collina for the review of this article, and for building the awesome **mosca**.


# Authenticating & Authorizing a Tessel device with Auth0
Source: https://auth0.com/docs/customize/integrations/authenticating-and-authorizing-a-tessel-device-with-auth0

How to authenticate and authorize a Tessel device with Auth0.

[Tessel](https://tessel.io) is an amazing board. Not only it has a great hardware spec and a great extensibility story, you can program it in Javascript! When it was announced on Kickstarter we immediately supported it and waited long weeks to get hold of one.

<Frame>
  <img alt="Tessel - Tessel Ports Diagram" />
</Frame>

It finally arrived we can write our first program: get a token from Auth0 and call an API.

Tessel aims for full compatibility with Javascript. Most of core Node modules also work, but not all of them. See [the Tessle docs in Github](https://github.com/tessel/docs/blob/master/compatibility.md) for more details.

## The sample

This example is straight-forward:

1. We call the Resource Owner endpoint on Auth0 with device credentials
2. Get a token back
3. We use the token to call an API

<Frame>
  <img alt="Tessel - Tessel to Auth0 Flow Diagram" />
</Frame>

<AuthCodeBlock />

Noteworthy highlights of the code:

1. This is 99% compatible with Node (the only device specific module.is `tessel` that we only use to make sure all SSL calls happen with adequate time references.
2. The `request` function, is a simple wrapper on `http` module functions. The `request` module doesn't currently work in Tessel.

The <Tooltip href="/docs/glossary?term=Resource+Owner">Resource Owner</Tooltip> endpoint requires credentials (such as username/password), so the backend user store connected to Auth0 needs to support this (like a Database connection or Active Directory).

## Tessel Setup

* Run `tessel update` to make sure you install the latest firmware with SSL support.
* You will obviously need connection to the web. You can set up WiFi with the `tessel wifi` command.
* Always send credentials (such as `username`/`password`) over secured networks.

## Summary

Tessel is awesome. We see a lot of potential. This sample shows how easy it is to connect it with Auth0.


# Integrate with Amazon Web Services and Products
Source: https://auth0.com/docs/customize/integrations/aws

List of Amazon products and services, including Amazon Web Services (AWS) for identity and access management (IAM) with Auth0.

There are many ways to integrate Auth0 with Amazon products and services depending on your specific needs.

## Product integrations

You can read further on how to use the products below to use in addition to your Auth0 and AWS services:

* [CloudFront](/docs/customize/custom-domains/self-managed-certificates/configure-aws-cloudfront-for-use-as-reverse-proxy): Use as a reverse proxy with your <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip>.
* [Simple Email Service (SES)](/docs/customize/email/smtp-email-providers/configure-amazon-ses-as-external-smtp-email-provider): Manage email communications with your users.
* [EventBridge](https://marketplace.auth0.com/integrations/amazon-log-streaming): Stream logs to EventBridge.
* [Cognito](/docs/customize/integrations/aws/amazon-cognito): Use as a backend for your application.
* AWS S3 and DynamoDB:

  * Auth0 provides VPC gateway endpoints for accessing AWS S3 and DynamoDB, which may be needed for [Actions](/docs/customize/actions). This requires `aws:SourceVpc` based IAM policies as described in [Gateway endpoints for Amazon S3](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-s3.html) and [Gateway endpoints for Amazon DynamoDB](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-ddb.html). Please contact [Auth0 support](https://www.support.auth0.com) for details on VPC identifiers.

## Identity and access management (IAM) integrations

We have several how-to articles to configure AWS to work with Auth0:

* [Secure AWS API Gateway endpoints using custom authorizers](/docs/customize/integrations/aws/aws-api-gateway-custom-authorizers): Accept Auth0-issued <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip>.
* [Use AWS session tags with AWS APIs and resources](/docs/customize/integrations/aws/session-tags): Tag resources and assign users key/value pairs for RBAC.
* [Configure AWS for single sign-on](/docs/customize/integrations/aws/configure-amazon-web-services-for-sso): Allow your users to log in to AWS using any supported <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>.
* [Add Amazon login to your app](/docs/customize/integrations/aws/configure-amazon-web-services-for-sso): Allow users to log in to your app using their Amazon profile.

## Learn more

* [Build Serverless Applications Using Token-Based Authentication with AWS API Gateway and Lambda](/docs/customize/integrations/aws/aws-api-gateway-delegation)
* [Configure Amazon Web Services as SAML Service Provider](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-aws)


# Integrate with Amazon Cognito
Source: https://auth0.com/docs/customize/integrations/aws/amazon-cognito

How to integrate Auth0 with Amazon Cognito using an OpenID Connect (OIDC) Provider.

Amazon Cognito is a backend-as-a-service that lets you focus on developing the user experience for your application. To learn more and sign up for services, read [Amazon Cognito](http://aws.amazon.com/cognito/) and the process for creating an [OpenID Connect (OIDC) provider via AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/iam/create-open-id-connect-provider.html).

## Configure Amazon Web Services

### Get Auth0 application details

First, you'll need to get some information about your application in Auth0:

1. Go to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications).
2. Select your application, and then switch to the **Settings** view.
3. Record the **Domain** and the **Client ID**.

### Create new OpenID Connect (OIDC) provider

In AWS, create a new <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> (IdP):

1. Open the [IAM Console](https://console.aws.amazon.com), select **Identity Providers** in the left sidebar, and then select **Add Provider**.
2. Select **OpenID Connect** as the **Provider Type**.
3. For the **Provider URL**:

   1. Enter your **Domain** into the **Provider URL** field.
   2. Enter your **Client ID** into the **Audience** field.
4. Select **Add Provider**.
5. Navigate to your newly created provider and record the **Provider ARN.**

<Callout icon="file-lines">
  It's not necessary to set up an IAM role after creating the IdP. If you don't have one already, Cognito will create a default IAM role when you create an Identity Pool.
</Callout>

### Create Identity Pool

Create an Identity Pool in AWS to allow Cognito to use the Auth0 OIDC identity provider for authentication:

1. Sign in to the [Cognito Console.](https://console.aws.amazon.com/cognito/home)
2. Select **Federated Identities**.
3. For **Identity Pool Name**, specify a name for the pool (for example, `Auth0`).
4. Under **Authentication Providers**, select the **OpenID** tab, then select the name of the provider you created in the previously.
5. Select **Create Pool**, and then select **Allow** to finish creating the new identity pool.
6. Under Dashboard, select **Edit Identity Pool** to view the **Identity Pool ID**.
7. Record the **ARN** of the IAM role that was automatically created. This value will be used when sending credentials to Cognito.

## Configure Auth0

Cognito uses the public signing key from the [OpenID Provider Metadata](https://subscription.auth0.com/.well-known/jwks.json) to validate the signature of the <Tooltip href="/docs/glossary?term=JSON+Web+Token">JSON Web Token</Tooltip> (JWT).

Confirm that your Auth0 application is configured to use the RS256 signature algorithm:

1. Go to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), select your application, and then switch to the **Settings** view.
2. Expand the **Advanced Settings** section, and then switch to the **OAuth** view.
3. Locate the **JSON Web Token (JWT) Signature Algorithm** field, and select **RS256** from the dropdown menu.
4. Select **Save Changes**.

## Implementation

You can use the [Auth0 Lock SDK](/docs/libraries#lock) to integrate Auth0 within your application.

Once the user logs in with Auth0, the next step is to send their credentials to Cognito. To learn more, read [Open ID Connect providers (identity pools) on AWS Docs](http://docs.aws.amazon.com/cognito/latest/developerguide/open-id.html).

Cognito takes the <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> a user receives from Auth0, and uses it to generate unique Cognito IDs. When the user logs in to Cognito through Auth0, you can store information in Cognito that only they can access.

## Troubleshooting

### "Invalid login token" error

If you receive a "Invalid login token" error, confirm that the Auth0 application is configured to use the RS256 signature algorithm:

1. Go to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), select your application, and then switch to the **Settings** view.
2. Expand the **Advanced Settings** section, and then switch to the **OAuth** view.
3. Locate the **JSON Web Token (JWT) Signature Algorithm** field, and select **RS256** from the dropdown menu.


# Secure AWS API Gateway Using Cognito
Source: https://auth0.com/docs/customize/integrations/aws/aws-api-gateway-cognito

How to secure the API Gateway Tutorial using Cognito instead of IAM roles and policies.

Instead of using IAM roles and policies to secure your API, you can do so using user pools in Amazon Cognito.

Please [create the appropriate Amazon Cognito User Pools](http://docs.aws.amazon.com/cognito/latest/developerguide/setting-up-cognito-user-identity-pools.html) prior to beginning this tutorial.

## Integrate the Cognito User Pool with the API Gateway API

Go to the [Amazon API Gateway Console](https://console.aws.amazon.com/apigateway). Using the left-hand navigation bar, select the **SecurePets** API.

Then, select **Authorizers** for the **SecurePets** API.

On the Authorizers column near the center of the screen, choose **Create** and indicate that you are creating a **Cognito User Pool Authorizer**.

To configure your authorizer:

1. Choose the **Cognito region** in which you created your User Pool.
2. Customize the **Authorizer name** field, if desired (it will be automatically populated with the name of the chosen User Pool, so you can opt to leave it as is)
3. Customize the **Identity token source** field. By default, this field is set to `method.request.header.Authorization`, which sets the name of the incoming request header containing the API caller's identity token to `Authorization`.
4. If desired, add a regular expression to the **App client ID regex** field to validate client IDs associated with the User Pool.

When you've finished configuring your authorizer, click **Create** to integrate the User Pool with your API.

## Enable the User Pool Authorizer on Methods

For each method that you want the User Pool to act as an authorizer, you must enable the User Pool to do so for that particular method.

To enable the User Pool authorizer on the `GET` method:

1. After selecting the SecurePets API, select the `GET` method listed under `/pets`.
2. Click on **Method Request**.
3. Under Authorization Settings, click on the **edit icon** next to the Authorization field.
4. Choose the appropriate Cognito User Pool authorizer from the list. Click the **checkmark icon** to save your selection.

Repeat this process for any additional methods for which you want the Cognito User Pool to act as an authorizer (`GET` and `PURCHASE` for `/pets`, as well as `POST` for `/purchase`).


# Secure AWS API Gateway Endpoints Using Custom Authorizers
Source: https://auth0.com/docs/customize/integrations/aws/aws-api-gateway-custom-authorizers

How to use secure AWS API Gateway using custom authorizers that accept Auth0-issued access tokens.

Secure AWS API Gateway endpoints using custom authorizers that accept Auth0-issued <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip>. To do this, you configure your API with API Gateway, create and configure your AWS Lambda functions (including the custom authorizers) to secure your API endpoints, and implement the <Tooltip href="/docs/glossary?term=authorization+flow">authorization flow</Tooltip> so that your users can retrieve the access tokens needed to gain access to your API from Auth0.

To learn more, visit [AWS Lambda Overview](https://aws.amazon.com/lambda/) once you log into your [AWS API Gateway](https://aws.amazon.com/api-gateway/).

The API Gateway extends the capabilities of Lambda by adding a service layer in front of your Lambda functions to extend security, manage input and output message transformations, and provide capabilities like throttling and auditing. A serverless approach simplifies your operational demands since concerns like scaling out and fault tolerance are now the responsibility of the compute service that is executing your code.

The custom authorizers will:

* Confirm that the access token has been passed via the `authorization` header of the request to access the API.
* Verify the RS256 signature of the Access Token using a public key obtained via a JWKS endpoint.
* Ensure the access token has the required Issuer `iss` and <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> `aud` claims.

Use the following steps to use custom authorizers:

1. [Create an Auth0 API](#create-an-auth0-api)
2. [Import and deploy the AWS API Gateway API](#import-and-deploy-the-aws-api-gateway-api)
3. [Create the custom authorizers](#create-the-custom-authorizers)
4. [Secure the API using custom authorizers](#secure-the-api-using-custom-authorizers)
5. [Test your deployment](#test-your-deployment)

To read more about <Tooltip href="/docs/glossary?term=signing+algorithms">signing algorithms</Tooltip>, read [Signing Algorithms](/docs/get-started/applications/signing-algorithms). For more details on using JWKS, visit [JSON Web Key Sets](/docs/secure/tokens/json-web-tokens/json-web-key-sets).

## How API Gateway custom authorizers work

[According to Amazon](http://docs.aws.amazon.com/apigateway/latest/developerguide/use-custom-authorizer.html), an API Gateway custom authorizer is a "Lambda function you provide to control access to your API using bearer token authentication strategies, such as <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> or <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip>."

Whenever someone (or some program) attempts to call your API, API Gateway checks to see if there's a custom authorizer configured for the API.

If **there is a custom authorizer for the API**, API Gateway calls the custom authorizer and provides the authorization token extracted from the request header received.

You can use the custom authorizer to implement different types of authorization strategies, including JWT verification, to return IAM policies authorizing the request. If the policy returned is invalid or if the permissions are denied, the API call fails.

For a valid policy, API caches the returned policy, associating it with the incoming token and using it for the current and subsequent requests. You can configure the amount of time for which the policy is cached. The default value is `300` seconds and the maximum length of caching is `3600` seconds (you can also set the value to 0 to disable caching).

To read more, visit [What is Amazon API Gateway?](http://docs.aws.amazon.com/apigateway/latest/developerguide/use-custom-authorizer.html) in the Amazon Developer's Guide. For more information on <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> verification, review our [JSON Web Token](/docs/secure/tokens/json-web-tokens) article.

## Prerequisite

You need to [sign up for an AWS account](https://portal.aws.amazon.com/gp/aws/developer/registration/index.html). This grants you access to the AWS features, including API Gateway and Lambda. All new members receive twelve months of free tier access to AWS.

## Create an Auth0 API

Configure the APIs consumed by the applications that successfully authorize.

1. Go to [Auth0 Dashboard > Applications > APIs](https://manage.auth0.com/#/apis), and select **Create API**.
2. Enter values for the following fields, and select **Create**.

   <table>
     <thead>
       <tr>
         <th>Field</th>
         <th>Description</th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>Name</td>
         <td>A friendly name for your API. This is the name you'll see in your list of Auth0 APIs.</td>
       </tr>

       <tr>
         <td>Identifier</td>
         <td>A logical identifier for your API. We recommend formatting this identifier like a URL `https://your-api-gateway`.</td>
       </tr>

       <tr>
         <td>Signing Algorithm</td>
         <td>The algorithm you want Auth0 to use to sign the issued <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>. To learn more, see <a href="/docs/get-started/applications/signing-algorithms">Signing Algorithms</a>.</td>
       </tr>
     </tbody>
   </table>

To see the details of your newly-created API, refer to the **Settings** view.

<Frame>
  <img alt="Dashboard - Create API - AWS API Gateway" />
</Frame>

Creating an API also creates a Machine to Machine Application for use with the API. You can see this application listed as **Authorized** under the **Machine to Machine Application** view. Take note of the <Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>; you will need it in part 3 of this tutorial.

## Import and deploy the AWS API Gateway API

<Callout icon="file-lines">
  This portion of the tutorial has been adapted from the [official AWS example](http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-create-api-from-example.html). Please refer to this example for in-depth notes and discussion.
</Callout>

In this step, you will:

* Import an API into API Gateway
* Test an API import
* Deploy an API for use with any front-end applications
* Test an API deployment

### Import and configure the Pets API

1. Log in to your AWS account, and using the **Services** drop-down located in the top navigation bar, go to the **API Gateway** Console.
2. If you've previously created an API, simply navigate to the API Gateway Console and click **Create API**. You'll be given the option to create the **Example API** on the **Create new API** form.
   If you've never created an API using API Gateway, you'll see the following screen. Click **Get Started** to proceed.

   <Frame>
     <img alt="AWS API Gateway - Get Started" />
   </Frame>

   You'll see a pop-up message welcoming you to API Gateway. Click **OK** to proceed.
3. On the **Create new API** form, you'll see that **Example API** is selected by default, and there's an example API defined in the editor. We'll use this API for the rest of our tutorial, so begin the API creation process by clicking **Import**.

   <Frame>
     <img alt="AWS API Gateway - Example API" />
   </Frame>

   When done, AWS displays a message indicating that your API created and populated with the provided data. Notice the API already has methods associated with it (namely, `GET` and `POST`). You can view the details of a method, modify its configuration, or test the method invocation by clicking the method name from the resource tree.

   <Frame>
     <img alt="AWS API Gateway - Resources Tree" />
   </Frame>

### Test your API

To test your API, click **POST** under `/pets`. This brings up the **Method Execution** window that provides an overview of the `POST` method's structure and behaviors:

* **Method Request** and **Method Response**: the API's interface with the front-end
* **Integration Request** and **Integration Response**: the API's interface with the back-end

We can use this area to test the API.

1. Click **Test** (shown on the **Client** sliver located in the middle of the page). You'll be redirected to the `/pets - POST - Method Test` page. Scroll to the bottom of the page, and provide the following snippet as the **Request Body**:

   ```json lines theme={null}
   {"type": "dog", "price": 249.99}
   ```

   The request body indicates the attributes of the pet we want to add to the database, as well as the cost for the pet.<Frame><img alt="AWS API Gateway - Request Body" /></Frame>
2. Click **Test** to proceed. You'll see the results of the test at the right side of the page.

   <Frame>
     <img alt="AWS API Gateway - Test Results" />
   </Frame>

### Deploy the API

The test we just completed was done using the API Gateway console. To use the API with a different application, you'll need to deploy the API to a stage.

1. From the **Actions** menu, select **Deploy API**.
2. Provide the following values, and click **Deploy**.

   <table>
     <thead>
       <tr>
         <th><strong>Parameter</strong></th>
         <th><strong>Value</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td><strong>Deployment stage</strong></td>
         <td>Choose <code>\[New Stage]</code></td>
       </tr>

       <tr>
         <td><strong>Stage name</strong></td>
         <td>Provide a name for your stage</td>
       </tr>

       <tr>
         <td><strong>Stage description</strong></td>
         <td>Provide a description for your stage</td>
       </tr>

       <tr>
         <td><strong>Deployment description</strong></td>
         <td>Provide a description for your API deployment</td>
       </tr>
     </tbody>
   </table>

### Test the deployment

When the API has successfully deployed, you'll be redirected to the **Test Stage Editor**. You can, at this point, test the API to see if it deployed correctly.

1. At the top of the **Test Stage Editor** window is a blue banner with your **Invoke URL**. This is the URL used to invoke the `GET` endpoint of your API. Click on the link to submit the `GET / method` request in a browser. This should result in the following success response:

   <Frame>
     <img alt="AWS API Gateway - Deploy Test Response" />
   </Frame>
2. In the **Stages** page, expand the tree under **Test**. Click **GET** under `/pets/{petId}`.

   <Frame>
     <img alt="AWS API Gateway - Get Pet ID" />
   </Frame>
3. You'll see an **Invoke URL** displayed in the blue banner at the top of the window. The final portion, `{petID}`, stands for a path variable. Replace this variable with `1`, and navigate to the new URL using your browser. You should receive an HTTP 200 request with the following JSON payload:

   ```json lines theme={null}
   {
     "id": 1,
     "type": "dog",
     "price": 249.99
   }
   ```

## Create the custom authorizers

Now that we have a fully functional API that's managed by API Gateway, secure this API so only those with the appropriate authorization may access the back-end behind the API.

Use API Gateway's custom request authorizers to authorize your APIs using bearer token authorization strategies, such as OAuth 2.0 or SAML. For each incoming request, the following happens:

1. API Gateway checks for a properly-configured custom authorizer.
2. API Gateway calls the custom authorizer (which is a Lambda function) with the authorization token.
3. If the authorization token is valid, the custom authorizer returns the appropriate AWS Identity and Access Management (IAM) policies.
4. API Gateway uses the policies returned in step 3 to authorize the request.

### Prepare the custom authorizer

You can [download a sample custom authorizer](https://github.com/auth0-samples/jwt-rsa-aws-custom-authorizer) that supports Auth0-issued tokens. Afterward, you'll need to customize the files so that the custom authorizer works for your environment.

1. Unzip the folder containing the sample files you downloaded above to the location of your choice, and navigate to the folder using the command line.
2. Within the sample folder, run `npm install` to install the Node.js packages required for deployment; AWS requires that these files be included in the bundle you will upload to AWS during a later step.
3. Configure your local environment with a `.env` file. You can copy the `.env.sample` file (while simultaneously renaming it `.env`) using `cp .env.sample .env`. Make the following changes:

   <table>
     <thead>
       <tr>
         <th><strong>Parameter</strong></th>
         <th><strong>Value</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td><strong><code>TOKEN\_ISSUER</code></strong></td>
         <td>The issuer of the token. If Auth0 is the token issuer, use `https://{yourDomain}/`. Be sure to include the trailing slash.</td>
       </tr>

       <tr>
         <td><strong><code>JWKS\_URI</code></strong></td>
         <td>The URL of the JWKS endpoint. If Auth0 is the token issuer, use `https://{yourDomain}/.well-known/jwks.json`</td>
       </tr>

       <tr>
         <td><strong><code>AUDIENCE</code></strong></td>
         <td>The <strong>identifier</strong> value of the API you created in the Create an Auth0 API section above.</td>
       </tr>
     </tbody>
   </table>

   As an example, the text of your `.env` file should look something like this when complete:

   <AuthCodeBlock />

### Test the custom authorizer locally

Obtain a valid JWT access token. There are multiple ways you can get one and the method you choose depends on your application's type, trust level, or overall end-user experience. For more information, review [Get Access Tokens](/docs/secure/tokens/access-tokens/get-access-tokens).

1. You can get a test token for your API by navigating to [Auth0 Dashboard > Applications > APIs](https://manage.auth0.com/#/apis), selecting your API, and selecting **Test**.
2. Create a local `event.json` file containing the token. You can copy the sample file (run `cp event.json.sample event.json`). Replace `ACCESS_TOKEN` with your JWT token, and `methodArn` with the appropriate ARN value for the `GET` method of your API.

To get the `methodArn`:

1. Using the API Gateway Console, open the **PetStore** API.
2. In the left-hand navigation, select **Resources**.
3. In the middle **Resources** panel, expand the resource tree. Underneath `/pets`, select **GET**.
4. In the **Method Request** box, you'll see the **ARN**.
5. Run the test using `npm test`.

The test uses the lambda-local package to test the custom authorizer using your token. If the test was successful, you'll see output similar to the following:

```json lines theme={null}
Message
------
{
    "principalId": "C8npTEMVnBrILsBTI91MOh6dfuZbPVAU@clients",
    "policyDocument": {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Action": "execute-api:Invoke",
                "Effect": "Allow",
                "Resource": "arn:aws:execute-api:us-east-1:1234567890:apiId/stage/method/resourcePath"
            }
        ]
    },
    "context": {
        "scope": "FULL_LIST_OF_SCOPES"
    }
}
```

If the value of `Effect` is `Allow`, your authorizer would've allowed the call to API Gateway.

To learn more, visit [Lambda-local](https://www.npmjs.com/package/lambda-local) at NPM.

### Create the IAM role

The IAM role has the required permissions to call Lambda functions; before we can proceed with our custom authorizer, we'll need to create an IAM role that can call our custom authorizer whenever API Gateway receives a request for access.

1. Log in to AWS, and navigate to the [IAM Console](https://console.aws.amazon.com/iam). In the left-hand navigation, select **Roles**.

2. Select **Create new role**.

3. Under **AWS service**, select the **AWS Lambda** row, then **Next: Permissions**.

4. On the **Attach permissions policy** screen, select the **AWSLambdaRole**. You can use the provided filter to narrow down the list of options. Select **Next: Tags**, then select **Next: Review** to proceed.

5. On the **Review** screen, provide a **Role name**, such as `Auth0Integration`. Leave the rest of the fields as is. Select **Create role**.

6. Once AWS has created your role, you'll be directed back to the **Roles** page of IAM. Select your new role.

7. On the **Summary** page for the role you've just created, select the **Trust relationships** view.

8. Select **Edit trust relationship**, and populate the **Policy Document** field with the following JSON snippet:

   ```json lines theme={null}
   {
      "Version": "2012-10-17",
      "Statement": [
         {
            "Effect": "Allow",
            "Principal": {
               "Service": [
                  "apigateway.amazonaws.com",
                  "lambda.amazonaws.com"
               ]
            },
            "Action": "sts:AssumeRole"
         }
      ]
   }
   ```

9. Click **Update Trust Policy**.

10. You'll be redirected back to the **Summary** page. Copy down the **Role ARN** value for later use.

    <Frame>
      <img alt="undefined" />
    </Frame>

### Create the Lambda function and deploy the custom authorizer

Now that you've configured your custom authorizer for your environment and tested it to see it works, deploy it to AWS.

1. Create a bundle that you can upload to AWS by running `npm run bundle`. This generates a `custom-authorizer.zip` bundle containing the source, configuration, and node modules required by AWS Lambda.
2. Navigate to the [Lambda console](https://console.aws.amazon.com/lambda), and click **Create function**.
3. On the **Select blueprint** page, click **Author from scratch** to create a blank function. Under **Basic information**, provide values for the following parameters:

   <table>
     <thead>
       <tr>
         <th><strong>Parameter</strong></th>
         <th><strong>Value</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td><strong>Name</strong></td>
         <td>A name for your Lambda function, such as <code>jwtRsaCustomAuthorizer</code></td>
       </tr>

       <tr>
         <td><strong>Description</strong></td>
         <td>A description for your Lambda function (optional)</td>
       </tr>

       <tr>
         <td><strong>Runtime</strong></td>
         <td>Select <code>Node.js 10.x</code></td>
       </tr>
     </tbody>
   </table>
4. Click **Create Function** to continue.
5. On the **Configuration** page of your function, scroll down to the **Function Code** section.
6. Select **Upload a .ZIP file** as the **Code entry type**.
7. Click **Upload** and select the `custom-authorizer.zip` bundle you created earlier.
8. Then, create the following three **Environment variables**. Note that this information is identical to that which is the `.env` file.

   <table>
     <thead>
       <tr>
         <th><strong>Parameter</strong></th>
         <th><strong>Value</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td><strong><code>TOKEN\_ISSUER</code></strong></td>
         <td>The issuer of the token. If Auth0 is the token issuer, use `https://{yourDomain}/`</td>
       </tr>

       <tr>
         <td><strong><code>JWKS\_URI</code></strong></td>
         <td>The URL of the JWKS endpoint. If Auth0 is the token issuer, use `https://{yourDomain}/.well-known/jwks.json`</td>
       </tr>

       <tr>
         <td><strong><code>AUDIENCE</code></strong></td>
         <td>The <strong>identifier</strong> value of the API you created in step 1.</td>
       </tr>
     </tbody>
   </table>
9. In the **Execution role** section, select **Use an existing role** then select the IAM role you created previously as the **Existing role**.
10. Under **Basic settings**, set **Timeout** to **30** sec.
11. Click **Save**.
12. To test the Lambda function you just created, click **Test** in the top-right corner.
13. Copy the contents of your `event.json` file into the **Configure test event** form. You can use the default "Hello World" event template.
14. Click **Create**.
15. Run your test by selecting it and clicking **Test**. If the test was successful, you'll see: "Execution result: succeeded". Expanding the output window should show a message similar to the one you received after your successful local test.

    <Frame>
      <img alt="undefined" />
    </Frame>

### Configure API Gateway custom authorizer

1. Return to API Gateway Console and open the **PetStore** API we created earlier.
2. Using the left-hand navigation, open **Authorizers** and select **Create New Authorizer**, then set the following parameters, and click **Create**.

   <table>
     <thead>
       <tr>
         <th><strong>Parameter</strong></th>
         <th><strong>Value</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td><strong>Name</strong></td>
         <td><code>jwt-rsa-custom-authorizer</code></td>
       </tr>

       <tr>
         <td><strong>Type</strong></td>
         <td>Select <strong>Lambda</strong></td>
       </tr>

       <tr>
         <td><strong>Lambda Region</strong></td>
         <td>Use the region for the Lambda function you created previously</td>
       </tr>

       <tr>
         <td><strong>Lambda Function</strong></td>
         <td><code>jwtRsaCustomAuthorizer</code></td>
       </tr>

       <tr>
         <td><strong>Lambda Invoke Role</strong></td>
         <td>The IAM Role ARN you copied above</td>
       </tr>

       <tr>
         <td><strong>Lambda Event Payload</strong></td>
         <td>Select <strong>Token</strong></td>
       </tr>

       <tr>
         <td><strong>Token Source</strong></td>
         <td><code>Authorization</code></td>
       </tr>

       <tr>
         <td><strong>Token Validation</strong></td>
         <td><code>^Bearer \[-0-9a-zA-z.]\*\$</code></td>
       </tr>

       <tr>
         <td><strong>TTL (seconds)</strong></td>
         <td><code>3600</code></td>
       </tr>
     </tbody>
   </table>
3. After AWS creates the authorizer and the page refreshes, test your authorizer by clicking **Test** and providing the Auth0 token (`Bearer ey...`) you previously used.
   If the test was successful, you'll see a response similar to the following.

   <Frame>
     <img alt="undefined" />
   </Frame>

## Secure the API using custom authorizers

To learn how to secure your API's endpoints, see the Amazon API Gateway developer guide article: [Use API Gateway Lambda Authorizers](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html).

### Configure API Gateway resources to use the custom authorizer

1. Log in to AWS, and navigate to the [API Gateway Console](http://console.aws.amazon.com/apigateway).

   <Callout icon="file-lines">
     Custom authorizers are set on a method by method basis; if you want to secure multiple methods using a single authorizer, you'll need to repeat the following instructions for each method.
   </Callout>
2. Open the **PetStore** API we created in step 2 of this tutorial. Under the **Resource** tree in the center pane, select the **GET** method under the `/pets` resource.

   <Frame>
     <img alt="undefined" />
   </Frame>
3. Select **Method Request**.
4. Under **Settings**, click the **pencil** icon to the right of **Authorization** and choose the `jwt-rsa-custom-authorizer` custom authorizer you created in step 3.
5. Click the **check mark** icon to save your choice of custom authorizer. Make sure the **API Key Required** field is set to `false`.

### Deploy the API

To make your changes public, deploy your API.

1. From the **Actions** menu, select **Deploy API**.
2. Provide the following values, and click **Deploy**:

   <table>
     <thead>
       <tr>
         <th><strong>Parameter</strong></th>
         <th><strong>Value</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td><strong>Deployment stage</strong></td>
         <td>Choose <code>\[New Stage]</code></td>
       </tr>

       <tr>
         <td><strong>Stage name</strong></td>
         <td>Provide a name for your stage</td>
       </tr>

       <tr>
         <td><strong>Stage description</strong></td>
         <td>Provide a description for your stage</td>
       </tr>

       <tr>
         <td><strong>Deployment description</strong></td>
         <td>Provide a description for your API deployment</td>
       </tr>
     </tbody>
   </table>

If successful, you'll be redirected to the **Test Stage Editor**. Note the **Invoke URL** provided in the blue ribbon at the top because you need this to test your deployment.

## Test your deployment

To test your deployment, make a `GET` call to the **Invoke URL** you noted in the previous step. If this test fails, check that you obtained the JWT access token correctly.

For details, see [Get Access Tokens](/docs/secure/tokens/access-tokens/get-access-tokens).

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request GET \
    --url https://%7ByourInvokeUrl%7D/pets
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://%7ByourInvokeUrl%7D/pets");
  var request = new RestRequest(Method.GET);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://%7ByourInvokeUrl%7D/pets"

  	req, _ := http.NewRequest("GET", url, nil)

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java lines theme={null}
  HttpResponse<String> response = Unirest.get("https://%7ByourInvokeUrl%7D/pets")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {method: 'GET', url: 'https://%7ByourInvokeUrl%7D/pets'};

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C lines theme={null}
  #import <Foundation/Foundation.h>

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://%7ByourInvokeUrl%7D/pets"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];

  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];
  ```

  ```php PHP lines theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://%7ByourInvokeUrl%7D/pets",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  conn.request("GET", "%7ByourInvokeUrl%7D/pets")

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://%7ByourInvokeUrl%7D/pets")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift lines theme={null}
  import Foundation

  let request = NSMutableURLRequest(url: NSURL(string: "https://%7ByourInvokeUrl%7D/pets")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"

  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()
  ```
</AuthCodeGroup>


# Build Serverless Applications Using Token-Based Authentication with AWS API
Source: https://auth0.com/docs/customize/integrations/aws/aws-api-gateway-delegation

How to build a serverless application using Token-based Authentication with AWS API Gateway and Lambda.

<Warning>
  This feature uses delegation. By default, delegation is disabled for tenants without an add-on in use as of 8 June 2017. Legacy tenants who currently use an add-on that requires delegation may continue to use this feature. If delegation functionality is changed or removed from service at some point, customers who currently use it will be notified beforehand and given ample time to migrate. In addition, note that delegation does not support the use of custom domains so any features depending on it may not be fully functional alongside a custom domain.
</Warning>

With AWS, you can create powerful, serverless, highly scalable APIs and applications through AWS Lambda, Amazon API Gateway, and a JavaScript application.

A serverless application runs custom code as a compute service without the need to maintain an operating environment to host your service. Instead, a service like [AWS Lambda](https://aws.amazon.com/lambda/) executes your code on your behalf.

Amazon API Gateway extends the capabilities of AWS Lambda by adding a service layer in front of your Lambda functions to extend security, manage input and output message transformations, and provide capabilities like throttling and auditing. A serverless approach simplifies your operational demands, since concerns like scaling out and fault tolerance are now the responsibility of the compute service that is executing your code.

However, you often want to tie your APIs to your existing users, either from social providers like Twitter and Facebook, or within your own organization from Active Directory or a customer database. This tutorial demonstrates how to authorize access of your Amazon API Gateway methods for your existing users using Auth0 delegation for AWS and integration with AWS Identity and Access Management (IAM).

Next, the tutorial walks you through setting up the Amazon API Gateway using AWS Lambda functions, securing those functions with AWS IAM roles, and then using Auth0 delegation to obtain a token for the AWS IAM role. It will then show you how to assign different permissions to various classes of users, like internal database or social users, and how to flow identity using a <Tooltip href="/docs/glossary?term=JSON+Web+Token">JSON Web Token</Tooltip> (JWT).

You will be taken through the following steps:

* [Step 1 - Set up the AWS API Gateway](/docs/customize/integrations/aws/aws-api-gateway-delegation/aws-api-gateway-delegation-1)
* [Step 2 - Secure and Deploy the Amazon API Gateway](/docs/customize/integrations/aws/aws-api-gateway-delegation/aws-api-gateway-delegation-2)
* [Step 3 - Build the Application](/docs/customize/integrations/aws/aws-api-gateway-delegation/aws-api-gateway-delegation-3)
* [Step 4 - Use Multiple Roles with Amazon API Gateway](/docs/customize/integrations/aws/aws-api-gateway-delegation/aws-api-gateway-delegation-4)
* [Step 5 - Use Identity Tokens to Flow Identity](/docs/customize/integrations/aws/aws-api-gateway-delegation/aws-api-gateway-delegation-5)


# AWS API Gateway Tutorial Step 1
Source: https://auth0.com/docs/customize/integrations/aws/aws-api-gateway-delegation/aws-api-gateway-delegation-1

Step 1 of Amazon API Gateway Tutorial

<Warning>
  This feature uses delegation. By default, delegation is disabled for tenants without an add-on in use as of 8 June 2017. Legacy tenants who currently use an add-on that requires delegation may continue to use this feature. If delegation functionality is changed or removed from service at some point, customers who currently use it will be notified beforehand and given ample time to migrate. In addition, note that delegation does not support the use of custom domains so any features depending on it may not be fully functional alongside a custom domain.
</Warning>

## Step 1 - Set up the Amazon API Gateway

After completing this step, you will have:

* Set up Amazon API Gateway using AWS Lambda functions to execute your service logic that stores and retrieves pets from an Amazon DynamoDB table;
* Created two unauthenticated REST service methods for getting and updating a list of pets.

Prior to beginning, please have [Node.js](https://nodejs.org/) installed.

### Step 1. Create the Amazon DynamoDB Table

In the [Amazon DynamoDB Console](https://console.aws.amazon.com/dynamodb), click on **Create Table**.

<Frame>
  <img alt="DynamoDB Console - Create Table" />
</Frame>

Configure the variables associated with the table:

* **Table name**: Pets
* **Primary key**: username
* **Primary key type**: String
* **Use default settings**: unchecked
* **Read capacity units**: 3
* **Write capacity units**: 3

<Frame>
  <img alt="DynamoDB Console - Configure Newly Created Table" />
</Frame>

Click **Create** to create the table with your provided settings.

While the table is being created, take note of the Amazon Resource Name (ARN) under the Table details section. You will need the table's ARN in the next step.

<Frame>
  <img alt="DynamoDB Console - Table Details - Amazon Resource Name" />
</Frame>

### Step 2. Create the Policy that Grants AWS Lambda Functions Access to the DynamoDB Pets Table

Navigate to the [AWS IAM Console](https://console.aws.amazon.com/iam).

Click on **Roles** in the left menu, and then click the **Create New Role** button.

<Frame>
  <img alt="IAM Console - Roles - Create New Roles" />
</Frame>

Name the role `APIGatewayLambdaExecRole` and click **Next Step**.

Select the Role Type. Under AWS Service Roles, select AWS Lambda.

<Frame>
  <img alt="IAM Console - Select the Role Type - Service Roles - AWS Lambda" />
</Frame>

On the Attach Policy screen, skip this step by clicking **Next Step**. At this point, review the information you provided. If all looks correct, click **Create Role**. When finished, you should see your role listed on the IAM homepage.

Select the role you just created, **APIGatewayLambdaExecRole**. Click the down arrow for Inline Policies and click the **Click Here** link.

Select Custom Policy, and then click **Select**. Name the policy `LogAndDynamoDBAccess` and add the following code as the policy document (be sure to first update the Amazon Resource Name (ARN) for your DynamoDB table). Click **Apply Policy**.

```json lines theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AccessCloudwatchLogs",
      "Action": ["logs:*"],
      "Effect": "Allow",
      "Resource": "arn:aws:logs:*:*:*"
    },
    {
      "Sid": "PetsDynamoDBReadWrite",
                  "Effect": "Allow",
      "Action": [
                  "dynamodb:DeleteItem",
                  "dynamodb:GetItem",
                  "dynamodb:PutItem",
                  "dynamodb:UpdateItem"
                  ],
      "Resource": ["DYNAMODB_TABLE_ARN_VALUE_FROM_PREVIOUS_STEP"]
    }
   ]
}
```

### Step 2. Create the AWS Lambda Functions

The next three steps create the AWS Lambda functions for retrieving and updating pet information in the DynamoDB table.

#### Create the Lambda Function for GetPetInfo

In the [AWS Lambda Console](https://console.aws.amazon.com/lambda), select **Create a Lambda Function** (if you have not created an AWS Lambda function before, you will click **Get Started Now**).

On the Select blueprint screen, click **Blank Function**.

You will then be prompted to Configure triggers. Click **Next** to proceed. You do not have to do so at this point.

Finally, you will be asked to Configure function.

Populate the appropriate fields with the following information:

* **Name**: `GetPetInfo`
* **Runtime**: Node.js 6.10

Paste the following code to read pet information from the DynamoDB table into the **Lambda function code** area.

```javascript lines theme={null}
var AWS = require('aws-sdk');
var DOC = require('dynamodb-doc');
var dynamo = new DOC.DynamoDB();

exports.handler = function(event, context) {
   var cb = function(err, data) {
      if(err) {
         console.log('error on GetPetsInfo: ',err);
         context.done('Unable to retrieve pet information', null);
      } else {
         if(data.Item && data.Item.pets) {
             context.done(null, data.Item.pets);
         } else {
              context.done(null, {});
         }
      }
   };

   dynamo.getItem({TableName:"Pets", Key:{username:"default"}}, cb);
};
```

For Role, select **Choose an existing role**. Next, choose **APIGatewayLambdaExecRole** as the Existing Role. Leave all other settings at their default values.

Click **Next** to review the information you provided. If all looks correct, click **Create function**.

Click **Test**, leaving the Input test event at its default (which uses the Hello World template). When the test completes, you should see an empty output (`{}`) in the Execution Result section. The table is empty.

#### Create the Lambda Function for UpdatePetInfo

Repeat the instructions used to create the `GetPetInfo` function, but use the following instead as the function code:

```javascript lines theme={null}
var AWS = require('aws-sdk');
var DOC = require('dynamodb-doc');
var dynamo = new DOC.DynamoDB();
exports.handler = function(event, context) {
    var item = { username:"default",
                 pets: event.pets || {}
            };

    var cb = function(err, data) {
        if(err) {
            console.log(err);
            context.fail('unable to update pets at this time');
        } else {
            console.log(data);
                context.done(null, data);
        }
    };
    dynamo.putItem({TableName:"Pets", Item:item}, cb);
};
```

Test the function by clicking the Actions drop-down and choosing **Configure sample event**. Enter the following for sample data and click **Submit**:

```json lines theme={null}
{
  "pets": [{
    "id": 1,
    "type": "dog",
    "price": 249.99
  }]
}
```

You should see an empty return result (`{}`).

Return to your `GetPetInfo` Lambda function and click **Test** again. You should now see a single pet.

#### Create the Third Lambda Function

You will create one additional Lambda function. While this function will do nothing, it is required by the OPTIONS method for CORS as described in a later section.

Using the steps described above, create a Lambda function named `NoOp`. The function's code will be as follows:

```js lines theme={null}
exports.handler = function(event, context) {
    context.succeed('');
}
```

Instead of creating this third Lambda function, you may choose to [create an OPTIONS method](#method-options) on the API Gateway.

### Step 3. Create the Amazon API Gateway API

You will create an API with two methods: one will `GET` pet information, and one will `POST` pet information.

#### Method: GET Pet Information

Go to the [Amazon API Gateway Console](https://console.aws.amazon.com/apigateway), and click **Create API**. If this is the first time you are creating an API, you will see a screen prompting you to **Get Started** instead.

If this is the first time you are creating an API, you will be prompted to create an Example API. Click **OK** to exit the pop-up notification, and choose the **New API** radio button instead of the **Example API** button.

Name the API `SecurePets` and click **Create API**.

Navigate to the Resources tab of the `SecurePets` API and click the **Create Resource** action.

Name the resource `Pets` and click **Create Resource** again.

In the left pane, select `/pets` and then click the **CreateMethod** button.

In the drop-down, select GET and click the checkmark button. Provide the following configuration values for the `GET` method:

* **Integration type**: Lambda Function;
* **Lambda Region**: Region you are located in;
* **Lambda Function**: GetPetInfo.

Click **Save** and then **OK** when prompted in the popup to grant permissions to the Lambda function.

In the Method Execution window that appears next, click **Test**.

You should see the single pet returned in the response body.

#### Method: POST Pet Information

Creating the API used to `POST` pet information is similar to creating the one used to `GET` pet information.

In the left pane, select `/pets`, and click **CreateMethod**.

In the drop-down, select POST, and click the checkmark button.

Select Lambda Function for Integration Type, select the region you are located in, and select UpdatePetInfo for the Lambda function.

Click **Save** and then **OK** when prompted in the popup to grant permissions to the Lambda function.

**Test**, and paste the following for the request body:

```json lines theme={null}
{"pets": [
    {"id": 1, "type": "dog", "price": 249.99},
    {"id": 2, "type": "cat", "price": 124.99}
  ]
}
```

You should see an empty return result (`{}`).

Return to the GET method, and click **Test** again to see that the response body indicates there are two pets listed in the table:

```json lines theme={null}
[
  {
    "id": 1,
    "price": 249.99,
    "type": "dog"
  },
  {
    "id": 2,
    "price": 124.99,
    "type": "cat"
  }
]
```

#### Method: OPTIONS

Instead of creating a lambda function that performs no action, you can create an `OPTIONS` method on the API Gateway.

In the left pane, select `/pets`, and click **CreateMethod**. In the drop down, select OPTIONS, and click the checkmark button. Select Mock for Integration Type. Click **Save**.

Leaving the Response Body blank, click **Test**. You should receive a Response Body indicating `no data`.

At this point, the AWS Lambda functions and the Amazon API Gateway methods are defined with no security.


# AWS API Gateway Tutorial Step 2
Source: https://auth0.com/docs/customize/integrations/aws/aws-api-gateway-delegation/aws-api-gateway-delegation-2

Step 2 of Amazon API Gateway Tutorial

<Warning>
  This feature uses delegation. By default, delegation is disabled for tenants without an add-on in use as of 8 June 2017. Legacy tenants who currently use an add-on that requires delegation may continue to use this feature. If delegation functionality is changed or removed from service at some point, customers who currently use it will be notified beforehand and given ample time to migrate. In addition, note that delegation does not support the use of custom domains so any features depending on it may not be fully functional alongside a custom domain.
</Warning>

## Step 2 - Secure and Deploy the Amazon API Gateway

Now that you have your API running, you need to add security. In this step, you will:

* Secure the update API to limit access to authenticated users with a specific AWS IAM role;
* Configure Auth0 delegation to use AWS IAM federation capabilities;
* Obtain an AWS <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> that uses the AWS IAM role.

Once your API is secure, you'll build a serverless, single-page application (SPA). The SPA will rely on federating identity to determine which users are allowed access. By combining AWS IAM Integration for AWS Gateway API, AWS IAM Identity Federation for <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip>, and Auth0 Delegation for AWS, you can enable users from many different sources, including Social Providers or enterprise connections, to access your APIs. The following diagram illustrates a sample flow using a SAML-based <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> and Auth0 SAML Federation and Delegation for AWS.

You will see two ways of implementing this flow:

1. Using Auth0 Delegation with AWS IAM;
2. Adding an identity token to flow identity to the Lambda function.

Delegation makes it easy for you to obtain tokens from AWS to access AWS services in your application.

### Ways to Secure the Amazon API Gateway

AWS API Gateway provides several different methods to secure your APIs:

1. API keys;
2. IAM;
3. [Amazon Cognito](/docs/customize/integrations/aws/aws-api-gateway-cognito).

Using API keys is typically appropriate for a service-to-service interaction, as illustrated below. However, there are several downsides to this approach:

* Placing a secret with a long lifetime on the application is risky (applications are easier to compromise);
* Creating a framework to issue and manage API keys requires a secure implementation that can be challenging to develop.

This section of the tutorial will utilize IAM roles and policies to secure your API in API Gateway, but you can also choose to do so using user pools in Amazon Cognito. To review detailed instructions on securing your AWS API, read [Secure AWS API Gateway Using Cognito](/docs/customize/integrations/aws/aws-api-gateway-cognito). For more information on using IAM roles and policies, read the Amazon article, [Control access to an API with IAM permissions](http://docs.aws.amazon.com/apigateway/latest/developerguide/permissions.html). To read more about user pools in Cognito, visit [Amazon Cognit user pool](http://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html).

### Step 1. Configure IAM and Auth0 for SAML Integration with the API Gateway

You can specify an AWS IAM role for the SAML token you exchange for an AWS token. Depending on the permissions granted to that IAM role (which are set using your identity provider), the received token possesses those same permissions. By issuing different SAML tokens, each with its own AWS IAM role, you can control the levels of access for your users.

For example, the IDP could specify the IAM role based on group membership (for example, an administrator in Active Directory) or authentication source (for example, a database connection or a social provider like Facebook). This approach lets you differentiate user access to your Amazon API Gateway methods when secured using AWS IAM.

#### Configure Auth0

Log in to your Auth0 account. You will be brought to the Management Dashboard. Click on **+ New Application**, which is located in the top right corner of the page.

Name your new application AWS API Gateway, and indicate that this Application is going to be a Single-Page Application. Click **Create**.

Navigate to the Addons tab for your newly-created Application. Using the appropriate slide, enable Amazon Web Services. This turns on AWS Delegation.

#### Configure AWS

Follow the [How to Set Up AWS for Delegated Authentication](/docs/customize/integrations/aws/how-to-set-up-aws-for-delegated-authentication) tutorial to configure AWS for delegated access, which uses SAML. Some caveats:

* Follow the [instructions below](#setting-the-permissions-policy-on-your-iws-iam-role) for attaching the permissions policy to your role instead of the one for the linked tutorial;
* Name the SAML provider you create `auth0`;
* Name the AWS IAM role `auth0-api-role`.

##### Set the Permissions Policy on Your IWS IAM Role

Once you have configured the AWS IAM role, you will add a policy to `auth0-api-role` that lets you execute your API Gateway methods. For more information on this process, please see [User Access Permissions for Amazon API Gateway](http://docs.aws.amazon.com/apigateway/latest/developerguide/permissions.html).

#### Getting the Gateway API ARN

Before you begin, you will need the ARN for your Gateway API:

1. Navigate to [Amazon API Gateway Console](https://console.aws.amazon.com/apigateway) and log in.
2. Select the appropriate API.
3. Click on any of the Methods associated with the API to bring up the Method Execution page.
4. On the Method Execution page, the Method Request box in the top left corner displays the **ARN** for the API, though it includes the Method name:

`arn:aws:execute-api:us-east-2:484857107747:97i1dwv0j4/*/POST/`

You'll strip the method name to get the base ARN for the API:

`arn:aws:execute-api:us-east-2:484857107747:97i1dwv0j4/*`

The wildcard (`*`) in the ARN above enables permissions to your API for all stages, but you can deploy different stages individually (for example, development, then test, then production).

Select the `auth0-api-role` role you just created to open its Summary page.

Expand **Inline Policies**, and click **click here**.

Select **Custom Policy** and click **Select**.

Edit your policy document. You can set the **Policy Name** to whatever you would like, but we suggest something like `api-gateway-policy`. To enable access to the API methods for this role, apply the following policy after updating the ARN with the one for your API.

```json lines theme={null}
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "execute-api:*"
            ],
            "Resource": [
                "arn:[{yourArn}]"
            ]
        }
    ]
}
```

Click **Apply Policy**.

Since the API Gateway will assume this role on behalf of the user, the trust policy needs to permit this action. To do so, edit the role's Trust Relationships by navigating to this tab on the role's Summary page.

The final trust relationship should look similar to the following:

<AuthCodeBlock />

At this point, you will need to set the Authorization Settings on the [API Gateway](https://console.aws.amazon.com/apigateway).

In the **Resources** view, select the POST method under `/pets`.

Click the **Method Request** link.

Click the edit icon beside the **Authorization Type**, and select AWS\_IAM. Now click the **Check Button** beside the field to save the setting.

### Step 2. Set Up CORS and Deploy the API

Our Single-Page Application (SPA) will access web API methods from a domain different from that of the page. The Cross-Origin Resource Sharing setting needs to explicitly permit this action for the browser to allow access to the AWS API Gateway. Typically, the browser will first issue an `OPTIONS` request to see what actions the site will permit.

Select `/pets` under Resources, and click **Create Method**. In the drop-down, select **OPTIONS**, and click the **checkmark** to save the setting.

The Options method is used by the browser to get the necessary HTTP headers, but the function needs further instructions on what to do. Under the `OPTIONS` Setup screen, set the following variables/parameters:

* **Integration Type**: Lambda Function;
* **Use Lambda Proxy Integration**: leave unchecked;
* **Lambda Region**: select your region;
* **Lambda Function**: NoOp.

Click **Save**. On the next pop-up screen, grant your Lambda function the permissions it needs.

You will then be auto-directed to the `OPTIONS` Method Execution page. Open the Method Response page.

Expand the **200** section located under the HTTP Status bar and add the following response headers:

* Access-Control-Allow-Headers;
* Access-Control-Allow-Methods;
* Access-Control-Allow-Origin.

Next, map the appropriate values to each of the response headers. After returning to the Method Execution page, click on **Integration Response**. After expanding the row associated with the **200** method response status, expand the **Header Mappings**, and apply the following mappings:

* Access-Control-Allow-Headers: `'Content-Type,X-Amz-Date,Authorization,x-api-key,x-amz-security-token'`;
* Access-Control-Allow-Origin: `'*'`
* Access-Control-Allow-Methods: `'POST, GET, OPTIONS'`

Finally, repeat the above steps to enable CORS for the POST and GET methods. However, for these two methods, you will add one header, Access-Control-Allow-Origin, and its value should be set to `'*'`.

### Deploy the API

Return to the **Resources** view for your API. Click on **Actions**, and select **DEPLOY API**.

Select **New Stage** for Deploy State, and name the stage `Test`. Click the **Deploy** button.

On the result page, navigate to **SDK Generation**. Select JavaScript as the **Platform**. Click the **Generate SDK** button.

Save the downloaded zip file for later use.


# AWS API Gateway Tutorial Step 3
Source: https://auth0.com/docs/customize/integrations/aws/aws-api-gateway-delegation/aws-api-gateway-delegation-3

Step 3 of Amazon API Gateway Tutorial

<Warning>
  This feature uses delegation. By default, delegation is disabled for tenants without an add-on in use as of 8 June 2017. Legacy tenants who currently use an add-on that requires delegation may continue to use this feature. If delegation functionality is changed or removed from service at some point, customers who currently use it will be notified beforehand and given ample time to migrate. In addition, note that delegation does not support the use of custom domains so any features depending on it may not be fully functional alongside a custom domain.
</Warning>

## Step 3 - Build the Application

In this step, you will build a single-page, serverless application using the AngularJS framework that you will serve out of an AWS S3 bucket configured to act as a static website.

### Step 1. Set Up Your Sample Application

For a simple starter app, [download a sample project](https://github.com/auth0/auth0-aws/tree/master/examples/api-gateway/client) specific to this tutorial to get started. Log In to have your Auth0 credentials preconfigured.

Copy the contents of this seed project to a local folder called `pets`, which you will be using for the remainder of this tutorial. Within this folder, update `auth0-variables.js` with your Auth0 Application `AUTH0_CLIENT_ID` and `AUTH0_CLIENT_ID` (this information is available in the [Management Dashboard](https://manage.auth0.com/#/applications) for the application in question).

#### AWS S3 bucket

Be sure that you have [created the AWS S3 bucket configured to act as a static website](http://docs.aws.amazon.com/gettingstarted/latest/swh/website-hosting-intro.html). During the setup process, copy the contents of the `pets` folder to your S3 bucket to provide content for the website.

If you are using a pre-existing bucket, you can move the files with the AWS CLI using the following command.

```bash lines theme={null}
aws s3 cp --recursive --acl "public-read" ./ s3://{yourBucket}/
```

Prior to proceeding, please be sure that you have at least one user associated with your Username-Password-Authentication (or the Database Connection associated with the Application you are using) Connection. To fully utilize the functionality of your sample app and its integration with AWS, you will need that user to test authentication and gain access.

Lastly, ensure that Auth0 allows authentication from your website by providing the URL in the **Allowed Origins** field in the Settings page of your Application. Your website's URL should look something like this:

`http://your-bucket.s3-website-us-east-1.amazonaws.com`

If you don't know what your URL is, you can find it listed under the **Properties** tab of your S3 bucket.

Before going further, test logging into your application. Open `http://your-bucket-domain/index.html` in your browser. After logging in, you should see an alert box pop up that says "getPets not implemented":

You should also see the page for viewing pets.

### Use Delegation to Get an AWS Token

At this point, you have authentication set up with Auth0, and you have an <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip>. Here is the directory structure for the generated code:

<Frame>
  <img alt="AWS API Gateway - project directory" />
</Frame>

You can use Auth0's delegation capability to obtain an AWS <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> that is based on the Auth0 <Tooltip href="/docs/glossary?term=identity+token">identity token</Tooltip>. Behind the scenes, Auth0 authenticates your identity token, and then uses <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> based on the addon that you configured.

Update `pets/login/login.js` as follows to get an AWS delegation token from the identity token after a successful signin with `auth.signin`. Note that you are treating any user not logged in using a Social Connection as an admin. Later, we'll code a second role and show better ways to enforce role selection.

```js lines expandable theme={null}
auth.signin(params, function(profile, token) {
  //Set user as admin if they did not use a social login.
  profile.isAdmin = !profile.identities[0].isSocial;
  store.set('profile', profile);
  store.set('token', token);

  // get delegation token from identity token.
  var options = getOptionsForRole(profile.isAdmin, token);

  // TODO: Step 3: Enable this section once you setup AWS delegation.
  /*
  auth.getToken(options)
    .then(
      function(delegation)  {
        store.set('awstoken', delegation.Credentials);
        $location.path("/");
      },
    function(err) {
       console.log('failed to acquire delegation token', err);
  });
  */
  // TODO: Step 3: Remove this redirect after you add the get token API.
  $location.path("/");

}, function(error) {
  console.log("There was an error logging in", error);
});
```

#### Modify the role and principal Strings

To modify the `role` and `principal` strings (which are the final two lines of the `if` statement contained in the provided function), specify the appropriate values via [Rules](https://manage.auth0.com/#/rules):

```javascript lines theme={null}
function (user, context, callback) {
  if (context.clientID === 'CLIENT_ID' &&
      context.protocol === 'delegation') {
    // set AWS settings
    context.addonConfiguration = context.addonConfiguration || {};
    context.addonConfiguration.aws = context.addonConfiguration.aws || {};
    context.addonConfiguration.aws.principal = 'arn:aws:iam::[omitted]:saml-provider/auth0-provider';
    context.addonConfiguration.aws.role = 'arn:aws:iam::[omitted]:role/auth0-role';
  }

  callback(null, user, context);
}
```

Be sure to update the `role` and `[principal]` ARN values with the ones for your integration.

Copy the updated files to your S3 bucket for your website.

Optionally, you can set a breakpoint in the browser at `store.set('awstoken', delegation.Credentials);`. When you log out and and log back in, inspect `delegation.Credentials` when you arrive at the breakpoint. You will see a familiar values like AccessKeyId and SecretAccessKey:

```js lines theme={null}
{
    AccessKeyId: "ASIAJB...BNQ",
    SecretAccessKey: "vS+b6...2Noav",
    SessionToken: "AQoDYBqsivOV...DdQW0gsKr8rgU=",
    Expiration: "2015-08-27T14:48:32.000Z"
}
```

If you don't see these values, be sure that you have the Amazon Web Services addon enabled in the Addons tab for your Auth0 Application.

### Display Pets with the AWS API Service

The first thing you will do is show the pets to the end users.

#### Add the API Code to Call Your API

To add the API code for adding a call to your service, copy the contents of apiGateway-js-sdk.zip you previously downloaded to the `pets` directory. The contents should include:

* `apiClient.js`;
* `lib` folder;
* `README.md`.

To review the download, see [AWS API Gateway Tutorial Part 2](/docs/customize/integrations/aws/aws-api-gateway-delegation/aws-api-gateway-delegation-2#deploy-the-api).

There is already a `README.md` in the `pets` directory, so you will need to rename one of the files to keep both in the directory. The `README.md` for the API gateway explains how to use the API application from your Auth0 Application.

Open the `index.html` file located in the root of your `pets` folder to add all of the scripts listed at the top of the API readme to `index.html`:

```html lines theme={null}
<!-- scripts for aws api gateway include after you create your package from aws for api gateway. -->
<script type="text/javascript" src="/lib/axios/dist/axios.standalone.js"></script>
<script type="text/javascript" src="/lib/CryptoJS/rollups/hmac-sha256.js"></script>
<script type="text/javascript" src="/lib/CryptoJS/rollups/sha256.js"></script>
<script type="text/javascript" src="/lib/CryptoJS/components/hmac.js"></script>
<script type="text/javascript" src="/lib/CryptoJS/components/enc-base64.js"></script>
<script type="text/javascript" src="/lib/moment/moment.js"></script>
<script type="text/javascript" src="/lib/url-template/url-template.js"></script>
<script type="text/javascript" src="/lib/apiGatewayCore/sigV4Client.js"></script>
<script type="text/javascript" src="/lib/apiGatewayCore/apiGatewayClient.js"></script>
<script type="text/javascript" src="/lib/apiGatewayCore/simpleHttpClient.js"></script>
<script type="text/javascript" src="/lib/apiGatewayCore/utils.js"></script>
<script type="text/javascript" src="/apigClient.js"></script>
```

If you open `apigClient.js`, you can see that the downloaded library has created wrappers like `petsPost` and `petsGet` for your API methods. You do not need to modify this generated code.

#### Configure the getPets Method

Open `home.js` in the `home` folder, and update the contents of `getPets` with a method for retrieving pets data (be sure to update the region if you are not running in `us-east-1`):

```javascript lines theme={null}
function getPets() {
    // this is unauthenticated
    var apigClient = apigClientFactory.newClient({
        region: 'us-east-1' // The region where the API is deployed
    });

    apigClient.petsGet({},{})
      .then(function(response) {
        console.log(response);
        $scope.pets = response.data;
        $scope.$apply();
      }).catch(function (response) {
        alert('pets get failed');
        showError(response);
    });
}
```

Copy the updated code to your S3 bucket. Refresh the page to see two animals listed (if you ran the previously described test on your APIs that created these pets).

### Update Pets with the AWS API Service

Now that you have a working Auth0 Application with the API Gateway, you will add a method for updating the `pets` table.

Modify the `putPets` method logic to update pets using your API function. This function will be used for both adding and removing pets.

```javascript lines theme={null}
function putPets(updatedPets) {
    var body = {pets: updatedPets};

    var apigClient = apigClientFactory.newClient({
        region: 'us-east-1' // set this to the region you are running in.
    });

    apigClient.petsPost({},body)
      .then(function(response) {
        console.log(response);
       }).catch(function (response) {
        alert('pets update failed');
        showError(response);
      });
}
```

Copy the updated code to your S3 bucket. Test the method:

1. Log out and log back in.
2. Enter in values for `Pet Type` and `Pet Price`.
3. Click **Save** to post your data.

You should see a message that says, "We have a `<Pet Type>` for sale for `<Pet Price>`" with a red **REMOVE** button to its left.

To add security, add the `getSecureApiClient` function at the start of the `putPets` method:

```javascript lines theme={null}
function putPets(updatedPets) {
     var apigClient = getSecureApiClient();
}
```

Copy the code to your S3 bucket.

The `getSecureApiClient` function provided for you retrieves the AWS token from local storage acquired using delegation to the API, and uses the access key, secret, and session token:

```javascript lines theme={null}
function getSecureApiClient() {
    var awstoken = store.get('awstoken');

    return apigClientFactory.newClient({
        accessKey: awstoken.AccessKeyId,
        secretKey: awstoken.SecretAccessKey,
        sessionToken: awstoken.SessionToken,
        region: 'us-east-1' // The region you are working out of.
    });
  }
```


# AWS API Gateway Tutorial Step 4
Source: https://auth0.com/docs/customize/integrations/aws/aws-api-gateway-delegation/aws-api-gateway-delegation-4

Step 4 of Amazon API Gateway Tutorial

<Warning>
  This feature uses delegation. By default, delegation is disabled for tenants without an add-on in use as of 8 June 2017. Legacy tenants who currently use an add-on that requires delegation may continue to use this feature. If delegation functionality is changed or removed from service at some point, customers who currently use it will be notified beforehand and given ample time to migrate. In addition, note that delegation does not support the use of custom domains so any features depending on it may not be fully functional alongside a custom domain.
</Warning>

## Step 4 - Use Multiple Roles with Amazon API Gateway

In this step, you'll assign different AWS IAM roles to users based on authentication information:

* Users authenticating with Social Connections will be treated as buyers;
* Users authenticating with Database Connections will be treated as admins.

You will perform this role assignment logic in two different ways:

* JavaScript;
* Auth0 rules.

For many Auth0 Applications, you'll want different users to have different levels of access, and you'll want additional information about a given identity to use in your service logic. In cases where it's sufficient to lock down access at the API level, you can use different AWS IAM roles (for example, administrators can use the update function to add and remove pets, but social users can only buy pets).

The following diagram illustrates AWS IAM role assignments for two different user classes: users authenticated via Social Connections and users authenticated via Database Connections. It also illustrates that AWS IAM roles can be assigned to other entities, like AWS Lamdba functions, to control the permissions these entities are assigned for an account. In short, an IAM role is a group of permissions to AWS capabilities that is defined by one or more policies and then assigned to an entity.

For cases where you want to make decisions within your code (for example, you might want a credit check of a user buying a pet), you will want to flow identity as well. This will be demonstrated below in [Step 5 - Using Identity Tokens to Flow Identity](/docs/customize/integrations/aws/aws-api-gateway-delegation/aws-api-gateway-delegation-5).

### Step 1. Create the PetPurchase API Resource

Using the [Amazon API Gateway Console](https://console.aws.amazon.com/apigateway), select your Pets API. You will be taken to its Resources page.

Click on **Actions** and **Create Resource**. Name the New Child Resource `Purchase`. Click **Create Resource**.

Add an OPTIONS method for the `purchase` resource as outlined previously for `pets` in the [Set Up Cors and Deploy the API section of Step 2 - Securing and Deploying the Amazon API Gateway](/docs/customize/integrations/aws/aws-api-gateway-delegation/aws-api-gateway-delegation-2#set-up-cors-and-deploy-the-api).

Create a new AWS Lambda function for purchasing a pet called `PetPurchase`, which adds `isSold` and `soldTo` attributes to a pet as follows:

```javascript lines expandable theme={null}
var AWS = require('aws-sdk');
var DOC = require('dynamodb-doc');
var dynamo = new DOC.DynamoDB();

exports.handler = function(event, context) {
   var petId = event.petId;
   var user = event.userName;
   var pets = {};
   console.log('start PetsPurchase, petId', petId, ' userName', user);

   var writecb = function(err, data) {
      if(!err) {
          context.done(null, pets);
      } else {
          console.log('error on GetPetsInfo: ',err);
          context.done('failed on update', null);
      }
   };

   var readcb = function(err, data) {
      if(err) {
          console.log('error on GetPetsInfo: ',err);
          context.done('failed to retrieve pet information', null);
      } else {
          // make sure we have pets
          if(data.Item && data.Item.pets) {
              pets = data.Item.pets;
              var found = false;

              for(var i = 0; i < pets.length && !found; i++) {
                  if(pets[i].id === petId) {
                     if(!pets[i].isSold) {
                        pets[i].isSold = true;
                        pets[i].soldTo = user;
                        var item = { username:"default",pets: pets};
                        dynamo.putItem({TableName:"Pets", Item:item}, writecb);
                        found = true;
                     }
                  }
               }
               if(!found) {
                 console.log('pet not found');
                 context.done('That pet is not available.', null);
               }
           } else {
              console.log('pet already sold');
              context.done('That pet is not available.', null);
           }
       }
   };

   dynamo.getItem({TableName:"Pets", Key:{username:"default"}}, readcb);
};
```

Once you have defined the Lambda function, [add a POST method to the `purchase` resource](/docs/customize/integrations/aws/aws-api-gateway-delegation/aws-api-gateway-delegation-1#method-post-pet-information) that calls the `PetPurchase` Lambda. Be sure to also add the `Access-Control-Allow-Origin` header with a value of `*` to the POST method using the method response/integration response configuration found in [Set Up Cors and Deploy the API section of Step 2 - Securing and Deploying the Amazon API Gateway](/docs/customize/integrations/aws/aws-api-gateway-delegation/aws-api-gateway-delegation-2#set-up-cors-and-deploy-the-api).

Test the API gateway method, providing the following as an input message:

```json lines theme={null}
{
    "petId": 1,
    "userName": "fred flintstone"
 }
```

In the test response, you should see the pet with ID of 1 is now sold to Fred Flintstone:

```json lines theme={null}
[
  {
    "id": 1,
    "price": 249.99,
    "type": "dog",
    "isSold": true,
    "soldTo": "fred flintstone"
  },

  ...
```

### Step 2. Use IAM to Secure the PurchasePet API

#### Update IAM

To secure your API, follow the same process for adding a new role that you [performed in Part 2](/docs/customize/integrations/aws/aws-api-gateway-delegation/aws-api-gateway-delegation-2) of this tutorial. Call the new role `auth0-api-social-role`.

The ARN for the method you will secure in the IAM policy should look something like:

```bash wrap lines theme={null}
arn:aws:execute-api:us-east-1:your-accountid:your-api-id/*/pets/purchase
```

Be sure to update the trust policy as well.

Go to the [Amazon API Gateway Console](https://console.aws.amazon.com/apigateway), and select the POST method for the `/pets/purchase` resource. Select **Method Request** and change **Authorization Type** to AWS\_IAM. Click the check to save the setting.

At this point, you have defined two roles that you can use with the API gateway:

* `auth0-api-role`: permits updating pets
* `auth0-api-social-role`: permits purchasing a pet

#### Configure Login with Amazon and Update Auth0

You can create a social role using Login with Amazon (LWA).

While this tutorial includes instructions for using Login with Amazon, please note that you can use other social providers as well.

1. Navigate to [Auth0 Dashboard > Authentication > Social](https://manage.auth0.com/#/connections/social), and select **Create Connection**.
2. Choose the connection you want to set up, and consent.
3. Copy and paste the `Client ID` and `Client Secret` from your social identity provider, select the **Attributes** (and **Permissions**, where applicable), and click **Save**.
4. Select the **Applications** view, enable the switch for each of your Auth0 applications that should be able to use this connection, and select **Save**.

Once you've entered the appropriate information, select **Try Connection** to ensure that everything is set up correctly.

When you configure LWA using the Amazon console, be sure to enter into Allowed Return URLs the callback URL to your Auth0 Application, which should look something like `https://johndoe.auth0.com/login/callback`. The Auth0 help page will show you specifically what to enter.

Navigate to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), and select your Application to view its settings. Select the **Connections** view, locate the **Social** section, and ensure that **Amazon** is enabled.

#### Deploy the API and Update the Single-Page Application

##### Deploy the API

Using the [Amazon API Gateway Console](https://console.aws.amazon.com/apigateway), you will again [deploy the API and generate a new JavaScript SDK](/docs/customize/integrations/aws/aws-api-gateway-delegation/aws-api-gateway-delegation-2#set-up-cors-and-deploy-the-api).

At this point, you have made the necessary configuration changes to enable pet purchases. To make this live, copy your newly downloaded SDK over the previous one in your `pets` folder, as well as your Amazon S3 bucket.

##### Update the Login Controller Logic to Choose Different Roles for Different Types of Users

The login controller logic uses `getOptionsForRole` to select different roles for different users. When you obtain the delegation token, you can tell Auth0 which role to use (that is, the user is an admin or not).

In the `pets/login/login.js` file, modify the `role` and `principal` values for the non-admin user for the social user IAM role you just created.

At this point, you should be able to log in using Amazon credentials **or** the database user you previously created. Notice that the UI lets a social user buy pets, while an admin user can add and remove pets.

To test this functionality, you can temporarily hide the remove button in the UI by removing `ng-show="isAdmin"` in `/pets/home/home.html`:

```html wrap lines theme={null}
<button ng-show="isAdmin" class="btn delete-btn" ng-click="removePet(pet.id)">remove</button>
```

After copying the changes to your S3 bucket, attempt to remove a pet while logged in as a social user.

##### Update the Home Controller Logic to Allow Social Users to Purchase Pets

In `home.js`, modify the `buyPet` function to enable pet purchases:

```javascript lines theme={null}
function buyPet(user, id) {
    var apigClient = getSecureApiClient();

    apigClient.petsPurchasePost({},{userName:user, petId:id})
      .then(function(response) {
        console.log(response);
        $scope.pets = response.data;
        $scope.$apply();
      }).catch(function (response) {
        alert('buy pets failed');
        showError(response);
    });
}
…
```

Copy the code to your S3 bucket, log out, and then log back in in as a social user by clicking on the Amazon icon in the Lock login dialog. You may need to click **SHOW ALL** if your previous login persists in the Lock pane.

Note that, as an Amazon user, you can buy a pet, but not add or remove pets. However, if you log in with a user associated with a Database Connection, you are able to add and remove pets, but not buy pets.

### Enforce Role Assignment with Auth0 Rules

In some cases, you might determine the appropriate role using the Application (as shown here), but for security reasons (you might want to prevent the user from assuming a more privileged role than necessary), you might want to determine user privileges on the server-side.

With Auth0, this is done via rules, which are service logic statements you define that are then run during the Auth0 authentication process. For example, you could create rules to:

* Eliminate the passing of role information from the browser to the Application;
* Insert role information into the delegation request based on the authentication source.

#### Enforce Role Assignment

You will add a rule that will check to see if the role requested by the user is allowed, depending on its association with a Social or Database Connection.

1. Navigate to [Auth0 Dashboard > Auth Pipeline > Rules](https://manage.auth0.com/#/rules), and select **Create Rule**.
2. Choose the **Empty rule** template
3. Name the rule **AWS Pets** (or something similar), then populate the body of the rule with the following JavaScript code:

<AuthCodeBlock />

Be sure to adjust the above code with the correct values for your integration. The fields are **Princial ARN**, **Role ARN**, and **Client Secret**.
4\. **Save** your changes.

#### Caveats

* Rules run at a global scope for every authentication. You should only run the logic on authentication requests associated with a given application (which is why the script used asks for the clientID. Without this information, the logic runs for every authentication request associated with your Auth0 account.
* Information is passed into the rule with the context and the user.
* You can extend the objects passed in to the rule. In the code above, the rule checks the body of the request for the role information. The role is set into the context addonConfiguration of the allowed role, which always overrides settings in the request body.

#### Debug Your Rule

You are ready to debug your rule(s). Select **Try this Rule**, and you will be presented with a script that tries the rule's logic. Select **Try**.

You will then be presented with the output of running your rule.


# AWS API Gateway Tutorial Step 5
Source: https://auth0.com/docs/customize/integrations/aws/aws-api-gateway-delegation/aws-api-gateway-delegation-5

Step 5 of Amazon API Gateway Tutorial

<Warning>
  This feature uses delegation. By default, delegation is disabled for tenants without an add-on in use as of 8 June 2017. Legacy tenants who currently use an add-on that requires delegation may continue to use this feature. If delegation functionality is changed or removed from service at some point, customers who currently use it will be notified beforehand and given ample time to migrate. In addition, note that delegation does not support the use of custom domains so any features depending on it may not be fully functional alongside a custom domain.
</Warning>

## Step 5 - Use Identity Tokens to Flow Identity

In this final step, you will:

* Flow identity to the service by passing your <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> <Tooltip href="/docs/glossary?term=JSON+Web+Token">JSON Web Token</Tooltip> (JWT);
* Validate the token;
* Extract profile information to assign a buyer for a pet.

## Use an Identity Token

You can use your Lambda function to process and obtain information about the user. For example, during a purchasing transaction, you retrieved the username from the profile returned with the <Tooltip href="/docs/glossary?term=identity+token">identity token</Tooltip>. However, you can also choose to have the user's information embedded with the identity itself, which is a JSON Web Token (JWT).

The advantages of using JWTs is that you can:

1. Verify the authenticity of the JWT;
2. Be sure that the calling user is authenticated (instead of relying on a plain-text parameter that could have been tampered with).

In addition, you can use the JWT for authorization, which allows you to bypass the IAM integration with Amazon API Gateway. Please note, however, that using the API Gateway for authorization allows you to halt the API call prior to invocation of your Lambda function.

### Add Information to the JWT

There are several ways of adding a user's information to the JWT. The following example adds the user's email address to the JWT, but the concepts are same for other user datapoints.

#### Use Rules

One way to add a user's email address to the JWT is to use a [rule](/docs/customize/rules). This is a good approach if you want to make sure that this value is always available in the JWT for an authenticating user.

In `login.js`, you can see this scope specified in the parameters passed to `auth.signin`:

```js lines theme={null}
$scope.login = function() {
    var params = {
        authParams: {
          scope: 'openid email'
        }
      };

    auth.signin(params, function(profile, token) {
      ...
    }
  }
```

While you can include the full profile of the user within the JWT, you will want to include only what is necessary since the JWT is typically passed with every request.

## Validate the JWT Token

Because the AWS Lambda console has access to a limited number of Node modules that can be used when you enter your Node.js code using the browser console, you'll need to include additional modules and upload the Lambda function as a package to process the identity token.

For additional details, see [Creating Deployment Packages using Node.js](http://docs.aws.amazon.com/lambda/latest/dg/nodejs-create-deployment-pkg.html) and [Uploading Deployment Packages and Testing](http://docs.aws.amazon.com/lambda/latest/dg/walkthrough-s3-events-adminuser-create-test-function-upload-zip-test.html).

The following seed project contains the code you'll need for your updated AWS Lambda function.

```js wrap lines theme={null}
<%= include('../../../_includes/_package', { org: 'auth0', repo: 'auth0-aws', path: 'examples/api-gateway/lambda' }) %>
```

You'll see two custom JavaScript files within the seed project:

* `index.js`: contains your main code;
* `auth0-variables`: contains the code you need to update.

In addition to the custom files, there is a standard Node.js `package.json` file.

The code adds functionality to extract information from and validate the JWT. By default, Auth0 uses a symmetric key for signing the JWT, though you may opt to use asymmetric keys (if you need to allow third-party validation of your token, you should use an asymmetric key and share only your public key).

For more information about token verification, see [Identity Protocols Supported by Auth0](/docs/authenticate/protocols).

Update `auth0-variables.js` with your secret key, which can be found on the Settings tab of your Application in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>:

```javascript lines theme={null}
var env={};
env.AUTH0_SECRET='{yourAuth0Secret}';
module.exports = env;
```

Run **npm install** from the directory where your files are, zip up the contents (`index.js` must be at the root of the zip), and upload it for use by the `PurchasePet` Lambda function. If you test this, you should see an authorization failure, since the JWT is not in the message body.

Take a look at the logic in `index.js`. You will see logic around line 60 that validates the token and extracts the decoded information that contains the identity information used for the purchase logic:

```js lines theme={null}
if(event.authToken) {
     jwt.verify(event.authToken, secret, function(err, decoded) {
         if(err) {
           console.log('failed jwt verify: ', err, 'auth: ', event.authToken);
           context.done('authorization failure', null);
         } else if(!decoded.email)
         {
           console.log('err, email missing in jwt', 'jwt: ', decoded);
           context.done('authorization failure', null);
         } else {
           userEmail = decoded.email;
           console.log('authorized, petId', petId, 'userEmail:', userEmail);
           dynamo.getItem({TableName:"Pets", Key:{username:"default"}}, readcb);
         }
     });
  } else {
     console.log('invalid authorization token', event.authToken);
     context.done('authorization failure', null);
  }
    ...
```

### Extract Profile Information to Assign a Buyer

The final step is to pass the JWT to the method used by the browser client.

The standard method comes with an `Authorization` header as a bearer token, and you can use this method by turning off IAM authorization and relying solely on the OpenID Token for authorization (you will also need to map the Authorization header into the event data passed to the AWS Lambda function).

If, however, you are using IAM, then the AWS API Gateway uses the `Authorization` header to contain the signature of the message, and you will break the authentication by inserting the JWT into this header. To do this, you can either:

* Add a custom header for the JWT;
* Put the custom header into the body of the message.

If you choose to use a custom header, you'll also need to do some mapping for the Integration Request of the POST method for `pets/purchase`.

To keep the validation process simple, pass the JWT in the body of the post to the AWS Lambda function. To do this, update the `buyPet` method in `home.js` by removing the `userName` from the body, and adding `authToken` as follows:

```javascript lines theme={null}
function buyPet(user, id) {
    var apigClient = getSecureApiClient();
    var body = {
      petId:id,
      authToken: store.get('token')
    };

    apigClient.petsPurchasePost({}, body)
      .then(function(response) {
        console.log(response);
        $scope.pets = response.data;
        $scope.$apply();
      }).catch(function (response) {
        alert('buy pets failed');
        showError(response);
    });
}
```

Upload your code to your S3 bucket and try to purchase a pet. You will see the email of the purchaser in the resulting message.

If you have any errors, double check that you have properly set your secret key. One useful tool for checking issues with your token decoding is [jwt.io](http://jwt.io/).

## Summary

In this tutorial, you have:

* Created an API using AWS API Gateway that includes methods using AWS Lamdba functions;
* Secured access to your API using IAM roles;
* Integrated a <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> with IAM to tie access to the API to your user base;
* Provided different levels of access based on whether a user authenticated from the Database or Social Connection;
* Used an Auth0 rule to enforce role assignment;
* Used a JWT to provide further authorization context and pass identity information into the appropriate Lambda function.


# Configure Amazon Web Services for Single Sign-On
Source: https://auth0.com/docs/customize/integrations/aws/configure-amazon-web-services-for-sso

Learn how to configure single sign-on (SSO) for Auth0 with Amazon Web Services (AWS).

By integrating Auth0 with AWS, you'll allow your users to log in to AWS using any supported <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>.

To configure AWS for <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip>, you need to complete the following steps:

1. Create an external identity provider in AWS.
2. Configure the SAML2 Web App addon for your Auth0 application.
3. Complete AWS identity provider configuration.
4. Create an AWS IAM role.
5. Map the AWS role to a user.

## Create an external identity provider in AWS

1. Set up an external identity provider in AWS using AWS's [Connect to your External Identity Provider](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-identity-source-idp.html) guide with one change.

   1. Rather than downloading the AWS metadata file, click **Show Individual Metadata Values**.
   2. Copy the **AWS SSO issuer URL** and **AWS SSO ACS URL** values. You will use these in the next section.
2. Leave this page open in your browser because you'll need to complete the configuration in a future section.

## Configure SAML SSO for Auth0

Configure the SAML2 Web App add-on for your application using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. To learn how, read [Configure Auth0 as Identity Provider for Amazon Web Services](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-aws).

## Complete AWS identity provider configuration

1. Return to the open AWS SSO identity provider page in your browser.
2. Upload the metadata file you downloaded and saved in the previous section.
3. Review and **Confirm** that you are changing the identity source.

## Create AWS IAM role

To use the provider, you must create an IAM role using the provider in the role's trust policy.

1. In the sidebar, under **Access Management**, navigate to [**Roles**](https://console.aws.amazon.com/iam/home#/roles). Click **Create Role**.
2. On the next page, you will be asked to select the type of trusted entity. Select **SAML 2.0 Federation**.
3. When prompted, set the provider you created above as the **SAML provider**. Select **Allow programmatic and AWS Management Console access**. Click **Next** to proceed.
4. On the **Attach Permission Policies** page, select the appropriate policies to attach to the role. These define the permissions that users granted this role will have with AWS. For example, to grant your users read-only access to IAM, filter for and select the `IAMReadOnlyAccess` policy. Once you are done, click **Next Step**.
5. The third **Create Role** screen is **Add Tags**. You can use tags to organize the roles you create if you will be creating a significant number of them.
6. On the **Review** page, set the **Role Name** and review your settings. Provide values for the following parameters:

   <table>
     <thead>
       <tr>
         <th><strong>Field</strong></th>
         <th><strong>Description</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td><strong>Role name</strong></td>
         <td>Descriptive name for your role.</td>
       </tr>

       <tr>
         <td><strong>Role description</strong></td>
         <td>Description of what your role is used for.</td>
       </tr>
     </tbody>
   </table>
7. Review the **Trusted entities** and **Policies** information, then click **Create Role**.

## Map AWS role to a user

<Callout icon="file-lines">
  To see an example of defining a server-side rule that assigns a role in an advanced use case, see the [Amazon API Gateway tutorial](/docs/customize/integrations/aws/aws-api-gateway-delegation/aws-api-gateway-delegation-5).
</Callout>

The **AWS roles** specified will be associated with an **IAM policy** that enforces the type of access allowed to a resource, including the AWS Consoles. To learn more about roles and policies, read [Creating IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html).

1. To map an AWS role to a user, create a [rule](/docs/customize/rules):

   ```javascript lines theme={null}
   function (user, context, callback) {

     user.awsRole = 'arn:aws:iam::951887872838:role/TestSAML,arn:aws:iam::951887872838:saml-provider/MyAuth0';
     user.awsRoleSession = user.name;

     context.samlConfiguration.mappings = {
       'https://aws.amazon.com/SAML/Attributes/Role': 'awsRole',
       'https://aws.amazon.com/SAML/Attributes/RoleSessionName': 'awsRoleSession'
     };

     callback(null, user, context);

   }
   ```

   In the code snippet above, `user.awsRole` identifies the AWS role and the IdP. The AWS role identifier comes before the comma, and the IdP identifier comes after the comma.

   1. Your rule can obtain these two values in multiple ways. You can get these values from the IAM Console by selecting the items you created in AWS in the previous steps from the left sidebar. Both the Identity Provider and the Role you created have an ARN available to copy if you select them in the Console.

   2. In the example above, both of these values are hard-coded into the rule. Alternatively, you might also store these values in the user profile or derive them using other attributes. For example, if you're using Active Directory, you can map properties associated with users, such as `group` to the appropriate AWS role:

      ```text lines theme={null}
      var awsRoles = {
        'DomainUser': 'arn:aws:iam::951887872838:role/TestSAML,arn:aws:iam::95123456838:saml-provider/MyAuth0',
        'DomainAdmins': 'arn:aws:iam::957483571234:role/SysAdmins,arn:aws:iam::95123456838:saml-provider/MyAuth0'
      };
      user.awsRole = awsRoles[user.group];
      user.awsRoleSession = user.email;

      context.samlConfiguration.mappings = {
        'https://aws.amazon.com/SAML/Attributes/Role': 'awsRole',
        'https://aws.amazon.com/SAML/Attributes/RoleSessionName': 'awsRoleSession',
      };
      ```

### Map multiple roles

You can also assign an array to the role mapping (so you'd have `awsRoles = [ role1, role2 ]` instead of `awsRoles: role1`)

For example, let's say that you have Active Directory Groups with the following structure:

```javascript lines theme={null}
var user = {
  app_metadata: {
    ad_groups: {
      "admins": "some info not aws related",
      "aws_dev_Admin": "arn:aws:iam::123456789111:role/Admin,arn:aws:iam::123456789111:saml-provider / Auth0",
      "aws_prod_ReadOnly": "arn:aws:iam::123456789999:role/ReadOnly,arn:aws:iam::123456789999:saml-provider / Auth0"
    }
  }
};
```

Your rule might therefore look like this:

```javascript lines theme={null}
function (user, context, callback) {

  var userGroups = user.app_metadata.ad_groups;

  function awsFilter(group) {
    return group.startsWith('aws_');
  }

  function mapGroupToRole(awsGroup) {
    return userGroups[awsGroup];
  }

  user.awsRole = Object.keys(userGroups).filter(awsFilter).map(mapGroupToRole);
  user.awsRoleSession = 'myawsuser'; // unique per user http://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html

  context.samlConfiguration.mappings = {
    'https://aws.amazon.com/SAML/Attributes/Role': 'awsRole',
    'https://aws.amazon.com/SAML/Attributes/RoleSessionName': 'awsRoleSession'
  };

  callback(null, user, context);

}
```

## Configure session expiration

To extend the amount of time allowed to elapse before the AWS session expires (3600 seconds), use a custom [rule](/docs/customize/rules). Your rule sets the [**SessionDuration** attribute](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_assertions.html) that changes the duration of the session.

<AuthCodeBlock />

## Test configuration

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and click the name of your application.
2. On the **Addons** tab, select the **SAML2 Web App** add-on.
3. On the **Usage** tab, locate the **Identity Provider Login URL**. You should be redirected to the Auth0 account login page. If you successfully log in, you'll be redirected to AWS.

## Learn more

* [Configure Amazon Web Services as SAML Service Provider](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-aws)


# Configure Amazon Web Services for Delegated Authentication
Source: https://auth0.com/docs/customize/integrations/aws/how-to-set-up-aws-for-delegated-authentication

Learn how to configure Amazon Web Services (AWS) for delegated authentication.

You can configure Amazon Web Services (AWS) for delegated authentication with Auth0. To learn more, [Configure Amazon Web Services for Single Sign-on](/docs/customize/integrations/aws/configure-amazon-web-services-for-sso) and [Secure AWS API Gateway Endpoints Using Custom Authorizers](/docs/customize/integrations/aws/aws-api-gateway-custom-authorizers).

## Create a SAML provider in AWS

1. Log in to AWS, and go to the [IAM console](https://console.aws.amazon.com/iam). Using the left-hand navigation menu, select **Identity Providers**. Click **Create Provider**. Set the following parameters:

   <table>
     <thead>
       <tr>
         <th>Parameter</th>
         <th>Description and Sample Value</th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>Provider Type</td>
         <td>The type of provider. Set as <Tooltip href="/docs/glossary?term=%60SAML%60">`SAML`</Tooltip></td>
       </tr>

       <tr>
         <td>Provider Name</td>
         <td>A descriptive name for the provider, such as <code>auth0SamlProvider</code></td>
       </tr>

       <tr>
         <td>Metadata Document</td>
         <td>Upload the file containing the Auth0 metadata, found in <strong>Dashboard > Applications > Application Settings > Advanced Settings > Endpoints > SAML Metadata URL</strong></td>
       </tr>
     </tbody>
   </table>
2. Click **Next Step**.
3. Verify your settings and click **Create** if everything is correct.

## Create a role for your SAML provider

To use the provider, you must create an IAM role using the provider in the role's trust policy.

1. In the IAM console, go to [Roles](https://console.aws.amazon.com/iam/home#/roles). Click **Create role**. You'll be redirected to the **Trust** page. Indicate **Saml 2.0 federation** under **Select type of trusted entity**. Provide the following values:

   <table>
     <thead>
       <tr>
         <th>Parameter</th>
         <th>Value</th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>SAML Provider</td>
         <td>The name for your new role</td>
       </tr>

       <tr>
         <td>Attribute</td>
         <td><code>SAML:iss</code></td>
       </tr>

       <tr>
         <td>Value</td>
         <td><code>urn:</code></td>
       </tr>
     </tbody>
   </table>
2. Click **Next: Permissions** to proceed.
3. You will need to attach permissions policies to your new role. You'll attach a custom policy. To create one, click **Create Policy**.
4. In the **Create policy** editor that launches, switch over to the **JSON** tab. Provide a custom policy.

   ```json lines theme={null}
   {
     "Version": "2012-10-17",
     "Statement": [{
         "Effect": "Allow",
         "Action": [
           "*"
         ],
         "Resource": [
         "arn:aws:s3:::{yourBucket}/<%= '${saml:sub}' %>",
         "arn:aws:s3:::{yourBucket}/<%= '${saml:sub}' %>/*"]
     }]
   }
   ```

   This defines the permissions that users granted this role will have with AWS. Click **Review policy**.
5. Review the policy that you've created. Be sure to provide a **Name** for your policy and (optionally) a **Description**.
6. Click **Create policy** when done. If successful, you'll see the following message confirming the creation of your new policy: "auth0SamlRolePolicy has been created".
7. Returning to the role creation wizard (you should be on step **2 - Permissions**), find the new policy you just create and click its checkbox to attach the policy to your role. We recommend using the **Customer managed** filter to find your policy.
8. Click **Next: Review** to proceed.
9. Review the information about your role, provide a **Role name**, and optionally a **Role description**. You'll see the policy you attached as well. If everything looks correct, click **Create role** to proceed.
10. Once created, you can find your roles located on the primary **Roles** page.

## Copy the ARN Values

The following instructions will show you where you can find the Provider and Role ARN values.

### Provider ARN

In the IAM console, go to [Identity providers](https://console.aws.amazon.com/iam/home#/providers). Select the role in which you're interested to open up its summary page. Copy the **Provider ARN** value, which is listed first under **Summary**.

### Role ARN

In the IAM console, go to [Roles](https://console.aws.amazon.com/iam/home#/roles). Select the role in which you're interested to open up its summary page. Copy the **Role ARN** value, which is listed first under **Summary**.


# Use Amazon Web Services Session Tags for Role-Based Access Control
Source: https://auth0.com/docs/customize/integrations/aws/session-tags

Learn how to use Amazon Web Services (AWS) Session Tags to implement role-based access control (RBAC) for AWS APIs and Resources.

With Amazon Web Services (AWS) Session Tags, you can tag resources and assign users key/value pairs, which allows you to implement role-based access control (RBAC) for AWS APIs and resources.

In the example included in this guide, we will tag our AWS resources with AWS Session Tags, then create a policy for an AWS IAM role that will allow users with this role and the appropriate tags to perform specific actions on our AWS resources. We will then create a rule in Auth0 that will attach our AWS IAM role and appropriate AWS Session Tags to an Auth0 user and pass them through <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> assertions in the token. This example builds on the example provided in [Configure Amazon Web Services for Single Sign-On](/docs/customize/integrations/aws/configure-amazon-web-services-for-sso).

To use AWS Session Tags with AWS APIs and Resources, you must:

1. Tag AWS instances.
2. Create a specialized AWS IAM role.
3. Create an Auth0 rule.
4. Test your configuration.

## Prerequisites

* You'll need an [Amazon Web Services (AWS) account](https://portal.aws.amazon.com/billing/signup#/start) for which you are an administrator.
* [Configure AWS for SSO](/docs/customize/integrations/aws/configure-amazon-web-services-for-sso)
* [Set up some AWS VM Instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html). For the example in this guide, we use three separate instances.

### Tag AWS instances

Add tags to your AWS resources. Follow instructions in [Amazon Elastic Compute Cloud: Tag your Amazon EC2 resources](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html).

You should have created three instances. Add the following tags:

<table>
  <thead>
    <tr>
      <th>Instance</th>
      <th>Tags</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>1</td>
      <td>Key: <code>CostCenter</code>, Value: <code>marketing</code>.<br />Key: <code>Project</code>, Value: <code>website</code>.</td>
    </tr>

    <tr>
      <td>2</td>
      <td>Key: <code>CostCenter</code>, Value: <code>engineering</code>.<br />Key: <code>Project</code>, Value: <code>management\_dashboard</code>.</td>
    </tr>

    <tr>
      <td>3</td>
      <td>Key: <code>CostCenter</code>, Value: <code>marketing</code>.<br />Key: <code>Project</code>, Value: <code>community\_site</code>.</td>
    </tr>
  </tbody>
</table>

### Create a specialized AWS IAM role

Create an IAM role using the AWS SAML <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> you set up during the prerequisites. Follow the instructions in [AWS Identity and Access Management User Guide: Creating a Role for SAML 2.0 Federation (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html).

While setting up your role, make sure you use the following parameters:

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description and Sample Value</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>SAML Provider</td>
      <td>Name of the identity provider you created in the prerequisites, such as <code>auth0SamlProvider</code>. Select <strong>Allow programmatic and AWS Management Console access</strong>.</td>
    </tr>
  </tbody>
</table>

When asked to **Attach permissions policies**, create a policy with the following JSON and name it `VirtualMachineAccessByCostCenter`.

```json lines theme={null}
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeInstances"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "ec2:StartInstances",
                "ec2:StopInstances"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "ec2:ResourceTag/CostCenter": "<%= "${aws:PrincipalTag/CostCenter}" %>"
                }
            }
        }
    ]
}
```

Once the policy has been created, refresh the policy list for the role, then filter and select the new policy.

When reviewing your settings, make sure you use the following parameters:

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Role name</td>
      <td>Descriptive name for your role, such as <code>AccessByCostCenter</code>.</td>
    </tr>

    <tr>
      <td>Role description</td>
      <td>Description of the purpose for which your role is used.</td>
    </tr>
  </tbody>
</table>

### Create an Auth0 rule

To map the AWS role and tags to a user, you'll need to [create a rule](/docs/customize/rules/create-rules) in Auth0. These values will then be passed through the SAML assertions in the token. For the example:

<Callout icon="file-lines">
  Replace the `awsAccount` variable value with your own account number.
</Callout>

```javascript lines theme={null}
function(user, context, callback) {
  var awsAccount = '013823792818';
  var rolePrefix = `arn:aws:iam::` + awsAccount; 
  var samlIdP = rolePrefix + `:saml-provider/auth0SamlProvider`;

  user.awsRole = rolePrefix + `:role/AccessByCostCenter,` + samlIdP;
  user.awsRoleSession = user.email;
  user.awsTagKeys = ['CostCenter', 'Project'];
  user.CostCenter = 'marketing';
  user.Project = 'website';

  context.samlConfiguration.mappings = {
    'https://aws.amazon.com/SAML/Attributes/Role': 'awsRole',
    'https://aws.amazon.com/SAML/Attributes/RoleSessionName': 'awsRoleSession',
    'https://aws.amazon.com/SAML/Attributes/PrincipalTag:CostCenter': 'CostCenter',
    'https://aws.amazon.com/SAML/Attributes/PrincipalTag:Project': 'Project'
  };

  callback(null, user, context);
}
```

### Test configuration

You should now be able to log in to the AWS Console using an Auth0 user and test your implementation.

To log in, you will need the <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> login for the AWS Console. To find it:

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and select the name of the Application to view.
2. On the **Addons** tab, enable the **SAML2 Web App** add-on.
3. On the **Usage** tab, locate **Identity Provider Login URL**.
4. Go to the indicated URL.
5. Once you have signed in, from **EC2**, select **Instances**. Click one of the instances tagged with a `CostCenter` of `marketing`, and click **Actions** > **Instance State** > **Stop**. Notice that the action completes successfully.
6. Click the instance tagged with a `CostCenter` of `engineering`, and click **Actions** > **Instance State** > **Stop**. Notice that the action fails with an error.

## Learn more

* [Configure Amazon Web Services for Single Sign-On](/docs/customize/integrations/aws/configure-amazon-web-services-for-sso)
* [Configure Amazon Web Services as SAML Service Provider](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-saml2-web-app-addon-for-aws)


# Integrate with Azure API Management
Source: https://auth0.com/docs/customize/integrations/azure-api-management

Using Auth0 as an OAuth 2.0 server to authenticate users wanting access to an API managed by the Azure API Management service

<Card title="Before you start">
  You'll need a Microsoft account with access to the [Azure Portal](https://azure.microsoft.com/en-us).
</Card>

The [Azure API Management](https://azure.microsoft.com/en-us/products/api-management/) service allows you to create new APIs or import existing API definitions and publish them for use by the approved audiences. Auth0 makes authorizing users of your API (using <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> standards) easy.

In this tutorial, you'll learn how to use Auth0 to authenticate and authorize users when they access a Basic Calculator API managed by Azure API Management.

## Configure Auth0

### Create an API

You'll need to create an API in Auth0 to represent the API managed by the Azure API Management Service. To learn more, read [Register APIs](/docs/get-started/auth0-overview/set-up-apis).

1. Navigate to [Auth0 Dashboard > Applications > APIs](https://manage.auth0.com/#/apis), and select **Create API**.
2. Set the following parameters:

   <table>
     <thead>
       <tr>
         <th><strong>Field</strong></th>
         <th><strong>Value</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td><strong>Name</strong></td>
         <td><code>Basic Calculator</code></td>
       </tr>

       <tr>
         <td><strong>Identifier</strong></td>
         <td><code>basic-calculator</code></td>
       </tr>

       <tr>
         <td><strong>Signing Algorithm</strong></td>
         <td><code>RS256</code></td>
       </tr>
     </tbody>
   </table>
3. Select **Create**.

### Create a Regular Web Application

You'll need to create a Regular Web Application (RWA) in Auth0 to communicate with the OAuth 2.0 <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip> in Azure:

1. Navigate to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), and select the **Create Application** button.
2. Enter a **Name** for your application, and select **Regular Web Applications** for the application type.

### Create and enable a connection

You'll need to create a connection in Auth0 and enable it for your application:

1. Navigate to [Auth0 Dashboard > Authentication > Database](https://manage.auth0.com/#/connections/database), and select **Create DB Connection**.
2. Enter a **Name** for your connection. We suggest choosing a name that reflects the source of users (such as `Facebook` for a Connection that contains users using their Facebook credentials or `site-sign-ups` for a database connection where users sign up on your site).
3. Select **Create**.
4. Navigate to your connection's **Settings** page.
5. Switch to the **Applications** view, where you'll see a list of all the applications on your tenant.
6. Toggle the application you created previously to enable it for the connection.

### Create a user

<Callout icon="file-lines">
  If you already have a set of users, you can import them or create a [custom database connection](/docs/authenticate/database-connections/custom-db).
</Callout>

You'll need to have at least one user on your connection to test authentication and authorization. If you do not have an existing set of users for the connection, you can create one manually:

1. Navigate to [Auth0 Dashboard > User Management > Users](https://manage.auth0.com/#/users), and select **Create User**.
2. Enter an **Email** and **Password**, and select the connection you created in Step 3 for the **Connection** field.
3. Select **Create**.

## Configure Azure

### Create Azure API Management Service

You'll need to create an API Management Service instance in Azure to manage your API:

1. In the navigation bar, select **Create a resource**.
2. Once redirected, select **Web** > **API Management**.
3. Provide the following configuration variables:

   <table>
     <thead>
       <tr>
         <th><strong>Parameter</strong></th>
         <th><strong>Description</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td><strong>Name</strong></td>
         <td>The name for your service (which will also be used to create the URL you need to access the service)</td>
       </tr>

       <tr>
         <td><strong>Subscription</strong></td>
         <td>The Azure subscription plan with which you'll use with the service</td>
       </tr>

       <tr>
         <td><strong>Resource group</strong></td>
         <td>The collection of <a href="https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resources-portal">resources</a> sharing a lifecycle, permissions, and policies. You can use an existing resource group or you can create a new one (you'll need to provide a name for the group if you create a new one)</td>
       </tr>

       <tr>
         <td><strong>Location</strong></td>
         <td>Choose the location that services your API instance</td>
       </tr>

       <tr>
         <td><strong>Organization name</strong></td>
         <td>The name of your organization</td>
       </tr>

       <tr>
         <td><strong>Administrator email</strong></td>
         <td>The email address of the person who will be administering this instance</td>
       </tr>

       <tr>
         <td><strong>Pricing tier</strong></td>
         <td>The pricing tier you want, which determines the number of calls you can make to your API, as well as the maximum amount of data transfer allowed. You must opt for the <a href="https://azure.microsoft.com/en-us/pricing/details/api-management/">Developer plan</a> or higher; the Consumption plan does not offer sufficient functionality for this integration to work.</td>
       </tr>
     </tbody>
   </table>
4. Select **Create** to begin provisioning your service (this may take up to 15 minutes to complete).

### Import the sample API

For this tutorial, we will be importing and using the Basic Calculator API provided by Microsoft. For detailed instructions, see [Import and Publish Your First API](https://docs.microsoft.com/en-us/azure/api-management/import-and-publish#go-to-your-api-management-instance) from Microsoft.

When done, select **Create** to import your API. You'll be redirected to the summary page for your API when it's fully imported.

### Configure an OAuth 2.0 authorization server

To use Auth0 to secure your Azure API, you'll need to register Auth0 as an OAuth 2.0 authorization server:

1. Find the **OAuth 2.0 + OpenID Connect** area of your API Management service instance near the navigation bar. Select **OAuth 2.0**,and then select **Add**.
2. Go to the **Add OAuth2 service** configuration screen, and select the Authorization Code grant type.
3. Set the following parameters:

   <table>
     <thead>
       <tr>
         <th><strong>Parameter</strong></th>
         <th><strong>Description</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td><strong>Display name</strong></td>
         <td>Enter a descriptive name for your authorization server, such as <code>Auth0</code>.</td>
       </tr>

       <tr>
         <td><strong>Id</strong></td>
         <td>This field should auto-populate based on the display name you provide.</td>
       </tr>

       <tr>
         <td><strong>Description</strong></td>
         <td>Enter a description for your authorization server, such as <code>Auth0 API Authentication</code>.</td>
       </tr>

       <tr>
         <td><strong>Client registration page URL</strong></td>
         <td>Enter `https://placeholder.contoso.com` as a placeholder.</td>
       </tr>

       <tr>
         <td><strong>Authorization code grant types</strong></td>
         <td>Select <code>Authorization code</code>.</td>
       </tr>

       <tr>
         <td><strong>Authorization endpoint URL</strong></td>
         <td>Refer to your tenant's <a href="https://{yourDomain}/.well-known/openid-configuration">OIDC Discovery endpoint</a> and append the <code>audience</code> parameter. For example: `https://{yourDomain}/authorize?audience={API_AUDIENCE}`.</td>
       </tr>

       <tr>
         <td><strong>Authorization request method</strong></td>
         <td>Default is <code>GET</code>.</td>
       </tr>

       <tr>
         <td><strong>Token endpoint URL</strong></td>
         <td>Refer to your tenant's <a href="https://{yourDomain}/.well-known/openid-configuration">OIDC Discovery endpoint</a> .</td>
       </tr>

       <tr>
         <td><strong>Client authentication methods</strong></td>
         <td>Select <code>Basic</code>.</td>
       </tr>

       <tr>
         <td><strong>Access Token sending method</strong></td>
         <td>Select <code>Authorization header</code>.</td>
       </tr>

       <tr>
         <td><strong>Default scope</strong></td>
         <td>Specify a default <Tooltip href="/docs/glossary?term=scope">scope</Tooltip>, if required.</td>
       </tr>
     </tbody>
   </table>
4. Under the **Client Credentials** section, enter your Auth0 applications client ID in the **Client ID** field and client secret in the **Client secret** field.
5. Switch to the **Redirect URI** view, and copy the URI value in the **Authorization code flow grant** field.
6. Select **Create**.

### Configure Azure API to use Auth0

After you've created your OAuth 2.0 authorization server in Azure, you'll need to update your Azure API to use Auth0 for user authorization:

1. Under the **APIs** section in the navigation, select **APIs**.
2. Select the Basic Calculator API, and go to the **Design** view.
3. Switch to the **Settings** view.
4. Navigate to the **Security** section, and select **OAuth 2.0** under **User Authorization**.
5. Select the server you configured in the previous step for the **Authorization Server** field.
6. Click **Save**.

## Set the Allowed Callback URL in Auth0

After your Azure API is provisioned and configured to use Auth0 for user authorization, you'll need to update your Auth0 application:

1. Navigate to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications).
2. Select your application, and switch to the **Settings** view.
3. Enter the Redirect URIyou copied previously into the **Allowed Callback URLs** field.
4. Click **Save**.

## Test the integration

In to the Azure Portal, open up your instance of the API Management Service.

1. Select **Developer Console** to launch the developer-facing side of your APIs.
2. Go to **APIs** > **Basic Calculator**. This opens up to the page where you can make a `GET` call that allows you to add two integers.
3. Select **Try It**. This will bring up the page where you can provide the parameters for your call.
4. Navigate to the **Authorization** section, and select **Authorization Code** (next to the **Auth0** field).
5. A popup window will appear with the Auth0 login widget (if it doesn't, ensure that any pop-up blockers are disabled for your browser). Enter the credentials for the Auth0 user you created in Step 4, and log in.
6. If you were able to successfully log in, a message will appear with the expiration date of the access token you can use to call your API.
7. Navigate to the bottom, and select **Send**. If the request is successful, you'll see a message containing the `HTTP 200` response at the bottom of the page.

### Configure a JWT validation policy for Access Tokens

In the previous step, the user is prompted to sign in when they try to make a call from the Developer Console. The Developer Console attempts to obtain an <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> on behalf of the user to be included in the API request. All Access Tokens will be passed to the API via the `Authorization` header.

If you want to validate the Access Token included with each request, you can do so by using the [Validate JWT policy](https://learn.microsoft.com/en-us/azure/api-management/validate-jwt-policy). Refer to Microsoft's documentation on [setting an API Management policy](https://learn.microsoft.com/en-us/azure/api-management/set-edit-policies?tabs=form).


# CMS Identity Plugins
Source: https://auth0.com/docs/customize/integrations/cms

Explains CMS Identity Plugins such as WordPress and Joomla

Auth0 provides Content Management System Plugins/Extensions to integrate your CMS installation with your Auth0 account. These plugins enable <Tooltip href="/docs/glossary?term=Single+Sign-on">Single Sign-on</Tooltip> (SSO) for Enterprises, social login and user/password login through all your instances and platforms.

Login features are implemented through a new Login Widget (powered by Auth0) that enables:

* SSO with Enterprise Directories (LDAP, AD, Google Workspace, Office365 and <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> Provider)
* Shared User/Password between multiple WordPress accounts for SSO
* SSO with over 30 [Social Providers](/docs/authenticate/identity-providers)
* User Management Dashboard
* Optional Two Factor Authentication
* SSO between WordPress and other applications
* Reporting and Analytics

## WordPress Plugin

* [How does it work?](/docs/customize/integrations/cms/wordpress-plugin/integrate-with-wordpress)
* [Installation](/docs/customize/integrations/cms/wordpress-plugin/install-login-by-auth0)
* [Configuration](/docs/customize/integrations/cms/wordpress-plugin/configure-login-by-auth0)
* [Troubleshoot](/docs/customize/integrations/cms/wordpress-plugin/troubleshoot-login-by-auth0)

## SharePoint

* [Github Source](https://github.com/auth0/auth0-sharepoint)


# Login by Auth0 WordPress Plugin
Source: https://auth0.com/docs/customize/integrations/cms/wordpress-plugin

This page explains the basics of the Login by Auth0 WordPress plugin

Auth0 provides a WordPress Plugin to integrate your sites with your Auth0 account. This plugin enables <Tooltip href="/docs/glossary?term=Single+Sign-on">Single Sign-on</Tooltip> (SSO) for Enterprises, social login, user/password, and <Tooltip href="/docs/glossary?term=passwordless">passwordless</Tooltip> login through all your instances.

Login features are implemented through a new form (powered by Auth0) that enables:

* SSO with Enterprise Directories (LDAP, AD, Google Workspace, Office365, and <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> Provider)
* SSO with over 30 [Social Providers](/docs/authenticate/identity-providers)
* SSO between WordPress installs and other applications
* User Management Dashboard
* Optional <Tooltip href="/docs/glossary?term=Multi-factor+Authentication">Multi-factor Authentication</Tooltip>
* Optional Passwordless Authentication
* Reporting and Analytics

## Learn more

* [Integrate with WordPress](/docs/customize/integrations/cms/wordpress-plugin/integrate-with-wordpress)
* [Install Login by Auth0](/docs/customize/integrations/cms/wordpress-plugin/install-login-by-auth0)
* [Configure Login by Auth0](/docs/customize/integrations/cms/wordpress-plugin/configure-login-by-auth0)
* [Troubleshoot Login by Auth0 WordPress Plugin](/docs/customize/integrations/cms/wordpress-plugin/troubleshoot-login-by-auth0)


# Configure Login by Auth0
Source: https://auth0.com/docs/customize/integrations/cms/wordpress-plugin/configure-login-by-auth0

How to configure WordPress as an application with Auth0

Login by Auth0 can be configured using the Setup Wizard in the plugin or manually for more control over the process. To learn more, read [Install Login by Auth0](/docs/customize/integrations/cms/wordpress-plugin/install-login-by-auth0). The instructions below can also be used if the Setup Wizard did not complete or as part of troubleshooting login issues.

<Callout icon="file-lines">
  You will need to be logged into your Auth0 account before starting the steps below. If you don't have one yet, [create one](https://auth0.com/signup).
</Callout>

## Auth0 configuration

Your Auth0 tenant must be configured to accept login requests from your WordPress site and source user identities from at least one Connection, whether that's an Auth0 database, a social connection, or a business directory. To learn more about tenants, read [Create Tenants](/docs/get-started/auth0-overview/create-tenants). To learn more about connections, read [Identity Providers](/docs/authenticate/identity-providers).

### Application setup

1. Create an Application for your WordPress site:

* **If you're troubleshooting the Setup Wizard**, navigate to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), and look for an Application that is similar to your WordPress site name. If you don't find one, it means that an Application was not created by the Wizard. Restart the Setup Wizard in WordPress or follow the step just below to create an Application manually.
* **If you're configuring manually**, navigate to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), and select **Create**. Enter a name for the Application, select **Regular Web Applications**, and select **Create**.

1. Select the **Settings** view for the Application. You will see your Domain, Client ID, and Client Secret, which are used in **wp-admin > Auth0 > Settings** to connect to Auth0.
2. **Application Type** must be set to **Regular Web Application** and **Token Endpoint Authentication Method** must be set to **Post**
3. Scroll down to **Allowed Callback URLs** and provide the WordPress site URL with `?auth0=1` appended:

<Warning>
  The Callback URL here **must not** be cached, or you might see an "Invalid state" error during login. To learn more, read [Troubleshoot WordPress Plugin Invalid State Errors](/docs/customize/integrations/cms/wordpress-plugin/troubleshoot-wordpress-plugin-invalid-state-errors).
</Warning>

1. Enter your WordPress site's **WordPress Address (URL)** (where the WordPress site appears publicly) and, if different, the **Site Address (URL)** (where wp-admin is served from) in the **Allowed Web Origins** field. Both of these values are found on your WordPress site's general settings screen.
2. Enter your WordPress site's login URL in the **Allowed Logout URLs** field
3. Leave the **Allowed Origins (CORS)** field blank (it will use the **Allowed Callback URLs** values from above)

<Callout icon="file-lines">
  Make sure to match your site's protocol (http or https) and use the home URL as a base, found in **wp-admin > Settings > General > WordPress Address (URL)** for all URL fields above.
</Callout>

1. Scroll down and select **Show Advanced Settings**, then select the **OAuth** view and make sure **JsonWebToken Signature Algorithm** is set to RS256. If this needs to be changed later, it should be changed here as well as in wp-admin (see Settings > Basic below).
2. Turn on **OIDC Conformant**.
3. Click the **Grant Types** tab and select at least **Authorization Code** and **Client Credentials**.
4. Click **Save Changes**.

### Authorize the Application for the Management API

In order for your WordPress site to perform certain actions on behalf of your Auth0 tenant, you'll need to authorize the Application created above to access the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. This is not required but will enable retrieving complete user data on login (including `user_metadata` and `app_metadata`), email and password changes for users, and email verification re-sending when verified emails are required.

1. Make sure your Application allows the Client Credentials grant (step 10 in the section above).
2. Navigate to [Auth0 Dashboard > Applications > APIs](https://manage.auth0.com/#/apis).
3. Select **Auth0 Management API**, then the **Machine to Machine Applications** view.
4. Look for the WordPress Application and select **Unauthorized** to grant access.
5. In the panel that appears, select only the `read:users` and `update:users` scopes, then select **Update** (you can search using the **Filter scopes** field).

### Database Connection setup

Database Connections enable username and password login with user records stored at Auth0. This type of Connection is not required and can be skipped if you're using <Tooltip href="/docs/glossary?term=passwordless">passwordless</Tooltip>, social, or enterprise logins only.

1. If you used the wizard during setup, navigate to [Auth0 Dashboard > Authentication > Database](https://manage.auth0.com/#/connections/database) and look for a Connection that has a similar name to the Application setup above. Otherwise, you can create a new Connection, use an existing Connection, or use the default **Username-Password-Authentication**. Select an existing Connection name to view settings or select **Create DB Connection** and follow the steps.
2. Select the **Applications** view and activate the Application created above.

### Social Connection setup

To learn how to activate and configure this login method, read [Social Identity Providers](/docs/authenticate/identity-providers/social-identity-providers).

### Enterprise Connection setup

To learn how to activate and configure this login method, read [Enterprise Identity Providers](/docs/authenticate/identity-providers/enterprise-identity-providers).

## WordPress configuration

1. Go to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and select the Application created above.
2. In a new tab/window, log in to wp-admin for your WordPress site and go to **wp-admin > Auth0 > Settings**.
3. Copy **Domain**, **Client ID**, and **Client Secret** from your Auth0 Application page to your WordPress settings using the **Copy to Clipboard** buttons next to each field.
4. Scroll down and select **Save Changes**.

## PHP constant setting storage

Plugin settings can be saved to the database (default) or they can be set using a specifically named PHP constant. This will allow for sensitive data like the <Tooltip href="/docs/glossary?term=client+secret">client secret</Tooltip>, API token, and migration token to be stored more securely (assuming that file they are defined in is stored securely; to learn more, read [Hardening WordPress on wordpress.org](https://developer.wordpress.org/advanced-administration/security/hardening/)).

The constant **must** be defined before the plugin is loaded or it will not be used. This should happen in your `wp-config.php` file or in a must-use plugin. To learn more, read [Must Use Plugins on wordpress.org](https://developer.wordpress.org/advanced-administration/plugins/mu-plugins/). If the constant is defined in your theme's `functions.php` or in a plugin that loads after Auth0, the value will be ignored.

The PHP constants are defined like so:

The default constant name should be `AUTH0_ENV_` followed by the option name to override in all caps (the prefix can be modified with the `auth0_settings_constant_prefix` filter; to learn more, read [Extend Login by Auth0 WordPress Plugin](/docs/customize/integrations/cms/wordpress-plugin/extend-login-by-auth0)). All plugin options can be overridden and their keys can be found in the `WP_Auth0_Options::defaults()` method.

**Note:** The `migration_token` value is generated by the plugin when user migration is turned on. If there is already a value in the admin, make sure to set the constant to the same value. If that value needs to change, it also must be changed in the custom scripts for the database Connection being used in the <Tooltip href="/docs/glossary?term=Auth0+dashboard">Auth0 dashboard</Tooltip>.

The settings field will change its display based on this new value and show the constant being used for reference. This value will be used everywhere in the plugin automatically.

**Important:** Saving the settings page after setting a constant value will validate the constant-set values (but not change them) and delete them from the options array being saved to the database. If you are just testing this functionality, do not save settings in the WordPress admin page until you're ready to delete that value.

All sites in a WordPress multi-site network will use the same constant value making this an easy way to setup a network using a single Application and database Connection.

## Plugin settings

### Basic

* **Domain:** The Domain copied from the Application settings in your dashboard. Option name is `domain`.
* **<Tooltip href="/docs/glossary?term=Custom+Domain">Custom Domain</Tooltip>:** The Custom Domain for your tenant, if one is configured. To learn more, read [Custom Domains](/docs/customize/custom-domains). Option name is `custom_domain`.
* **<Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>:** The Client ID copied from the Application settings in your dashboard. Option name is `client_id`.
* **Client Secret:** The Client Secret copied from the Application settings in your dashboard. Option name is `client_secret`.
* **<Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> Signature Algorithm** The algorithm used for signing tokens from the Advanced Application Settings, <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> tab; default is RS256. Option name is `client_signing_algorithm`.
* **JWKS Cache Time (in minutes):** How long the JWKS information should be stored when using the RS256 JWT Signature Algorithm. Option name is `cache_expiration`.
* **Original Login Form on wp-login.php:** Provides ways to access or block the core WordPress login page. Option name is `wordpress_login_enabled`. Login page code option name is `wle_code`.

  * **Never** will not allow the core WordPress login form to display.
  * **Via a link under the Auth0 form** will display a link to the WordPress core login form directly below the Auth0 embedded one on `wp-login.php`. The login page can also be accessed directly by adding `?wle` to the login URL.
  * **When "wle" query parameter is present** will allow the login page to be accessed directly by adding `?wle` to the login URL. This will bypass the Universal Login Page redirect.
  * **When "wle" query parameter contains specific code** will allow the login page to be accessed directly by adding `?wle=` plus a code to the login URL. The code is generated automatically and will be shown below the controls for this setting. This will bypass the Universal Login Page redirect.
* **Allow Signups:** User signup will be available only if the WordPress Anyone can register option is enabled. You can find this setting under **Settings > General > Membership**.

### Features

* **<Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> Page:** Redirects the `wp-login.php` page to the Universal Login Page for <Tooltip href="/docs/glossary?term=Single+Sign-on">Single Sign-on</Tooltip> (SSO) authentication using all active Connections for this Application. Option name is `auto_login`.
* **Auto Login Method:** A single, active connection to use for authentication when **Universal Login Page** is turned on. Leave this blank to show all active Connections on the Universal Login Page. Option name is `auto_login_method`.
* **Auth0 Logout:** Enable this option to log out of Auth0 when logging out of WordPress. Option name is `singlelogout`.
* **Override WordPress Avatars:** Forces WordPress to use Auth0 avatars. Option name is `override_wp_avatars`.

### Embedded

Options here do not affect the Universal Login Page (To learn about customization options, read [Auth0 Universal Login](/docs/authenticate/login/auth0-universal-login)).

* **Passwordless Login:** Enable this option to turn on Passwordless login on all embedded Auth0 login forms. Passwordless connections are managed in the Auth0 dashboard and at least one must be active and enabled on this Application for this to work. Option name is `passwordless_enabled`.
* **Icon URL:** Sets the icon above the embedded Auth0 login form. Option name is `icon_url`.
* **Form Title:** Sets the title of the embedded Auth0 login form. Option name is `form_title`.
* **Enable Gravatar Integration:** When user enters their email, their associated Gravatar picture is displayed in the embedded Auth0 login form. Option name is `gravatar`.
* **Login Name Style:** Selecting **Email** will require users to enter their email address to login. Set this to **Username** if you do not want to force a username to be a valid email address. Option name is `username_style`. Option name is `client_secret_b64_encoded`.
* **Primary Color:** To learn more about this setting, read [Lock Configuration Options](/docs/libraries/lock/lock-configuration). Option name is `primary_color`.
* **Extra Settings:** A valid JSON object that includes options to call Lock with. This overrides all other options set above. For a list of available options, see the Lock: User configurable options (e.g.: `{"disableResetAction": true }`). Option name is `extra_conf`.
* **Use Custom Lock JS URL:** When turned off, WordPress will use the latest tested version of Lock (Auth0 embedded login form) automatically. When turned on, administrators can provide a custom Lock URL to use. Option name is `custom_cdn_url`.
* **Custom Lock JS URL:** A valid URL pointing to a version of Lock. This field will be automatically hidden when **Use Custom Lock JS URL** is turned off. Option name is `cdn_url`.
* **Connections to Show:** List here each of the <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> you want to allow users to login with. If left blank, all enabled providers will be allowed. (To learn more, read [Lock UI Customization](/docs/libraries/lock/lock-ui-customization).) Option name is `lock_connections`.

  <Callout icon="file-lines">
    If you have enabled Passwordless login, you must list here all allowed social identity providers. To learn more, read [.social(options, callback) in our GitHub repository](https://github.com/auth0/lock-passwordless#socialoptions-callback).
  </Callout>

### Advanced

* **Require Verified Email:** If set, requires the user to have a verified email to log in. This can prevent some Connections from working properly if they do not provide an email address or an `email_verified` flag in the user profile data. Option name is `requires_verified_email`.
* **Skip Strategies:** If Require Verified Email is turned on, this setting will display. This field accepts strategy names to skip the verified email requirement on login and account association. This should **only** be used for strategies that do not provide an `email_verified` flag.
* **Remember User Session:** By default, user sessions live for two days. Enable this setting to keep user sessions live for 14 days. Option name is `remember_users_session`.

  * This setting must be less than or equal to your tenant's [Inactivity Timeout](/docs/manage-users/sessions/session-lifetime-limits)docs/manage-users/sessions/session-lifetime-limits setting to ensure that the user's session is properly maintained.
* **Login Redirection URL:** If set, redirects users to the specified URL after login. This does not affect logging in via the `[auth0]` shortcode. Option name is `default_login_redirection`. To change the redirect for the shortcode, add a `redirect_to` attribute, like so:

  `[auth0 redirect_to="http://yourdomain.com/redirect-here"]`
* **Force HTTPS Callback:** Enable this option if your site allows HTTPS but does enforce it. This will force Auth0 callbacks to HTTPS in the case where your home URL is not set to HTTPS. Option name is `force_https_callback`.
* **Auto Provisioning:** Should new users from Auth0 be stored in the WordPress database if new registrations are not allowed? This will create WordPress users that do no exist when they log in via Auth0 (for example, if a user is created in the Auth0 dashboard). Option name is `auto_provisioning`.

  <Callout icon="file-lines">
    If registrations are allowed in WordPress, new users will be created regardless of this setting.
  </Callout>
* **User Migration:** Enabling this option will expose the Auth0 migration web services. However, the Connection will need to be manually configured in the [Auth0 Dashboard](https://manage.auth0.com/#). To learn more about the migration process, read [User Migration in Login by Auth0 WordPress Plugin](/docs/customize/integrations/cms/wordpress-plugin/user-migration-in-login-by-auth0). The **Generate New Migration Token** button can be used to replace the saved token with a new one. Make sure to have your database Connection configuration page open to the **Custom Database** tab so you can replace the existing token with the new one in both scripts. Option name is `migration_ws`. Migration token option name is `migration_token`.
* **Migration IPs AllowList:** Only requests from listed IPs will be allowed access to the migration webservice. Option name is `migration_ips_filter`.
* **Valid Proxy IP:** List the IP address of your proxy or load balancer to enable IP checks for logins and migration web services. Option name is `valid_proxy_ip`.
* **Auth0 Server Domain:** The Auth0 domain, it is used by the setup wizard to fetch your account information. Option name is `auth0_server_domain`.

## Learn more

* [Integrate with WordPress](/docs/customize/integrations/cms/wordpress-plugin/integrate-with-wordpress)
* [Install Login by Auth0](/docs/customize/integrations/cms/wordpress-plugin/install-login-by-auth0)
* [Troubleshoot Login by Auth0 WordPress Plugin](/docs/customize/integrations/cms/wordpress-plugin/troubleshoot-login-by-auth0)
* [Extend Login by Auth0 WordPress Plugin](/docs/customize/integrations/cms/wordpress-plugin/extend-login-by-auth0)


# Extend Login by Auth0 WordPress Plugin
Source: https://auth0.com/docs/customize/integrations/cms/wordpress-plugin/extend-login-by-auth0

Learn how to extend the Login by Auth0 WordPress Plugin with hooks, filters, and functions.

WordPress plugins can be extended to fit your specific requirements by using actions and filters to run custom code at specific points during runtime. This document outlines the existing hooks in the Login by Auth0 plugin. We're happy to review and approve new filters and actions that help you integrate even further in this plugin. To learn more, read the Contributing section in the [`README` in the plugin's GitHub repository](https://github.com/auth0/wordpress?tab=readme-ov-file#contributing).

## WordPress Actions

WordPress Actions run custom code at specific points during processing. To learn more about WordPress Actions, read [WordPress Plugin Handbook: Actions on wordpress.org](https://developer.wordpress.org/plugins/hooks/actions/).

### auth0\_before\_login

This action runs in `WP_Auth0_LoginManager` after a user has been authenticated successfully but before they have been logged into WordPress. It can be used to stop the login process if needed using `wp_die()` or throwing an exception.

### auth0\_user\_login

This action runs in `WP_Auth0_LoginManager` after a user has been authenticated successfully and logged into WordPress. It can be used to set specific meta values, send notifications, or ping other services.

### wpa0\_user\_created

This action runs in `WP_Auth0_Users` just after a WordPress user is successfully created. It can be used to change user values, set additional user metas, or trigger other new user actions.

## Filters

Filters in WordPress also run custom code at specific points during processing but always return a modified value of the same type that was passed in. To learn more about filters, read [WordPress Plugin Handbook: Filters on wordpress.org](https://developer.wordpress.org/plugins/hooks/filters/).

### auth0\_create\_user\_data

This filter can be used to modify the user data array when creating a new user in WordPress from an incoming Auth0 user. It receives 2 parameters:

* `$user_data` is the user data parsed from the Auth0 profile.
* `$userinfo` is the Auth0 user profile.

This filter should always return an array of data that will be passed to the core `wp_insert_user()` function.

### auth0\_get\_wp\_user

This filter is called after the plugin finds the related user to login (based on the auth0 `user_id`) and is used to override the default behavior with custom matching rules (for example, always match by email).

If the filter returns null, it will look up by email. To learn more, read [Integrate with WordPress](/docs/customize/integrations/cms/wordpress-plugin/integrate-with-wordpress).

### auth0\_verify\_email\_page

This filter runs in `WP_Auth0_Email_Verification` to change the HTML rendered when a user who is logging in needs to verify their email before gaining access to the site. Note that this HTML is passed to `wp_die()` where it is modified before being displayed (see the `_default_wp_die_handler()` definition in core for more information).

### auth0\_get\_auto\_login\_connection

This filter is used in `WP_Auth0_LoginManager` to modify what connection is used for the auto-login process. The setting in wp-admin is pulled and then passed through this filter.

### wp\_auth0\_get\_option

This filter is used by option-getting functions and methods to modify the output value.

### auth0\_migration\_ws\_authenticated

This filter is used in `WP_Auth0_Routes` to alter the WP\_User object that is JSON-encoded and returned to Auth0 during a user migration.

### wpa0\_should\_create\_user

This filter is used in `WP_Auth0_Users` when deciding whether a user should be created. The initial value passed in is `TRUE`. If `FALSE` is returned for any reason, registration will be rejected and the registering user will see an error message (`WP_Auth0_UsersRepo::create()`).

### auth0\_login\_css

This filter is used to modify the CSS on the login page, including the login widget itself. This filter runs before CSS is retrieved from the wp-admin settings page.

### auth0\_login\_form\_tpl

Filters the template used for the Auth0 login form. This should return a path to a file containing HTML that replaces what is in `wp-content/plugins/auth0/templates/auth0-login-form.php`. The standard Lock initiation JS looks for an ID attribute of `auth0-login-form` to instantiate the login form so make sure that's present or replace the `wp-content/plugins/auth0/assets/js/lock-init.js` file with your own.

### auth0\_settings\_fields

This filter is used to modify an existing form field or to add a new one. This should return a modified `$options` array with your changes or additions. New fields must have a field callback, as shown below.

### auth0\_auth\_scope

This filter allows developers to add or change the scope requested during login. This can be used to add [custom claims](/docs/secure/tokens/json-web-tokens/create-custom-claims) or request a <Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip>.

### auth0\_nonce\_cookie\_name

Use this filter to modify the cookie name used for <Tooltip href="/docs/glossary?term=nonce">nonce</Tooltip> validation. See the `auth0_state_cookie_name` filter below for an example.

### auth0\_state\_cookie\_name

Use this filter to modify the cookie name used for the state parameter value. This can add a prefix or suffix or replace the string entirely. To learn more about the state parameter, read [Prevent Attacks and Redirect Users with OAuth 2.0 State Parameters](/docs/secure/attack-protection/state-parameters).
Make sure to use valid characters in any modifications made:

`A <cookie-name> can be any US-ASCII characters except control characters (CTLs), spaces, or tabs. It also must not contain a separator character like the following: ( ) < > @ , ; : \ " / ? = { }.`

To learn more about the `Set-Cookie` HTTP response header, read [Set-Cookie in MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie).

### auth0\_settings\_constant\_prefix

Use this filter to change the prefix for the constant used to override plugin settings. Please note that this filter **must** run before the Auth0 plugin is loaded so it needs to be located in an MU plugin. To learn more about MU plugins, read [Must Use Plugins on wordpress.org](https://developer.wordpress.org/advanced-administration/plugins/mu-plugins/).

### auth0\_authorize\_url\_params

This filter allows developers to adjust the `/authorize` endpoint parameters as needed. The function must return a dictionary-type array of URL parameters. To learn more about how these parameters are used, read [Authentication API Explorer: Login](https://auth0.com/docs/api/authentication#login).

### auth0\_authorize\_url

This filter allows developers to adjust the complete `/authorize` URL before use. The function must return a valid URL as a string. To learn more about how this URL is used, read [Authentication API Explorer: Login](https://auth0.com/docs/api/authentication#login).

### auth0\_die\_on\_login\_output

This filter lets you modify or replace the HTML content passed to `wp_die()` when there is an error during login. This filter does not affect the verify email content (see auth0\_verify\_email\_page).

### auth0\_coo\_auth0js\_url

This filter lets you override the default CDN URL for Auth0.js when loading the COO fallback page.

### auth0\_slo\_return\_to

This filter lets you override the default `returnTo` URL when logging out of Auth0.

### auth0\_logout\_url

This filter lets you override the Auth0 logout URL. To learn more about how this is used, read [Logout](/docs/authenticate/login/logout).

### auth0\_use\_management\_api\_for\_userinfo

This filter determines whether or not user profile data retrieved from the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> should when you're not using the Implicit Login Flow. Return a boolean `true` (default) to use the API, `false` to use the <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip>.

### auth0\_lock\_options

This filter can be used to modify the options for the embedded Lock login form used in shortcodes, widgets, and on the wp-login.php page when **Features > <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> Page** is turned off.

### auth0\_jwt\_leeway

This filter lets you adjust the leeway time used to validate ID tokens and should return a number of seconds as an integer.

### auth0\_jwt\_max\_age

This filter lets you adjust the `max_age` URL parameter sent on the authorize URL.

### auth0\_authorize\_state

This filter lets you filter the state data before being encoded and used for login. This data will be verified after a successful login and provided as-is for use.

## Learn more

* [Integrate with WordPress](/docs/customize/integrations/cms/wordpress-plugin/integrate-with-wordpress)
* [Install Login by Auth0](/docs/customize/integrations/cms/wordpress-plugin/install-login-by-auth0)
* [Configure Login by Auth0](/docs/customize/integrations/cms/wordpress-plugin/configure-login-by-auth0)
* [Troubleshoot WordPress Plugin Invalid State Errors](/docs/customize/integrations/cms/wordpress-plugin/troubleshoot-wordpress-plugin-invalid-state-errors)


# Install Login by Auth0
Source: https://auth0.com/docs/customize/integrations/cms/wordpress-plugin/install-login-by-auth0

Explains how to install the Auth0 WordPress plugin

<Callout icon="file-lines">
  In order to install or customize plugins, you must use a self-hosted WordPress.org site. Using a WordPress.com site does not allow installing plugins. To learn more about the differences, read [WordPress.com and WordPress.org on wordpress.com](https://wordpress.com/support/com-vs-org/).
</Callout>

This plugin can be added to your WordPress site using the **Plugins** screen in the wp-admin:

1. Log in to an existing WordPress site as an administrator.
2. Go to **Plugins > Add New** in the admin menu on the left.
3. Search for "Login by Auth0"
4. For the Login by Auth0 plugin, click **Install Now**, then **Activate**.

To learn more about this process, read [WordPress.com and WordPress.org on wordpress.com](https://wordpress.com/support/com-vs-org/).

As soon as the plugin is activated, you are redirected to the start of the Setup Wizard.

If you don't already have an Auth0 account, [s**ign up for free to create one**](https://auth0.com/signup) before proceeding.

<Callout icon="file-lines">
  Auth0 will not replace your login forms until a **Domain**, **Client ID**, and **Client Secret** have been added to the Basic tab of the settings page.
</Callout>

## Multisite setup

The Login by Auth0 plugin is compatible with WordPress multisite networks. The plugin can be network activated to automatically protect network sites (once configuration is complete) or activated only on a sub-set of the network.

There are a few ways that a network of sites can be set up in Auth0:

1. **All sites can share both an Application and a database connection**

   1. Run the Setup Wizard steps to completion for the main site.
   2. Configure all other sites manually using the **Domain**, **Client ID**, and **Client Secret** from the main site in the Basic tab of the Auth0 settings page.
   3. Update the Application's **Allowed Callback URLs**, **Allowed Web Origins**, and **Allowed Logout URLs** to include each site (wildcards can be used if your network uses subdomains).
2. **Each site can have its own Application and share a database connection**

   1. Run the Setup Wizard steps to completion for the main site.
   2. Next, [manually create an Application for each site](/docs/customize/integrations/cms/wordpress-plugin/configure-login-by-auth0) and add each one to the previously-created database connection.
   3. Add the **Domain**, **Client ID**, and **Client Secret** values to the Basic tab of the Auth0 settings page for each site.
3. **Each site can have its own Application and its own database connection.** In this case, Run the Setup Wizard steps to completion for each site.

Each of the options above has trade-offs. Option 1 has the least number of different entities to manage in Auth0 but, if your network has hundreds of sites and you're not using subdomains, you might run into limitations with the number of callback URLs. Option 2 will require managing many different Applications but will allow you to configure each site's Application differently.

As always, if you have any questions about this configuration process, [create a post in our Community and tag it "wordpress"](https://community.auth0.com/tags/wordpress).

## Setup Wizard

The Setup Wizard will attempt to create all the necessary components needed to use Auth0 on your WordPress site. If you have an existing Application or Database Connection you want to use, please see the Manual Setup steps below.

### Option 1: Standard Setup

This will create and configure an Application and a Database Connection for this site.

First, [generate a Management API token](https://auth0.com/docs/api/management/v2/get-access-tokens-for-test#get-access-tokens-manually). Once the token is generated, make a note of the domain name used in the **Identifier** field under the **Settings** tab. For example, if your Identifier is `https://tenant-name.auth0.com/api/v2/`, then the tenant domain is `tenant-name.auth0.com`. To learn more about tenant domains, read [Create Tenants](/docs/get-started/auth0-overview/create-tenants).

Back in the WordPress admin's Setup Wizard, click **Standard**. In the modal that appears, click **Start Standard Setup**.

Enter the tenant domain and API token from above. This token is only used for the setup process and will not be saved in the database.

If the first part of the setup successfully completes, you'll see the "Configure your social connections" screen. Click **Next** to continue the setup process by migrating your administrator account.

This step connects your WordPress user with an Auth0 user that authorizes you to log in. You can choose the same password as your admin account or a different one, but make sure it conforms to the password strength policies for the database Connection being used. To learn more, read [Password Strength in Auth0 Database Connections: Password Policies](/docs/authenticate/database-connections/password-strength#password-policieslicies).

The Setup Wizard must run to completion for your site to be configured correctly. If the Wizard fails for any reason before the "setup successful" screen, check the plugin error log at **wp-admin > Auth0 > Error Log** and the steps below to determine the issue.

To start the process over completely, delete any Applications or Database Connections that were created in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. In WordPress, go to **Auth0 > Settings > Basic**, delete the Domain, <Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>, and <Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip> fields, and click **Save**. Now, click **Setup Wizard** in the admin menu to start the process over again.

If you're still not able to install, [post a thread in our Community](https://community.auth0.com/tags/wordpress) with the error messages you're seeing in the Error Log, and we'll be happy to help!

### Option 2: User Migration Setup

This will create and configure an Application and a database connection plus data migration from your WordPress database. This requires an inbound connection from Auth0 servers and cannot be changed later without losing data. To learn more, read [User Migration in Login by Auth0 WordPress Plugin](/docs/customize/integrations/cms/wordpress-plugin/user-migration-in-login-by-auth0).

::: warning
If you have more than one custom database connection in Auth0, you'll need to make sure that the user IDs are namespaced to avoid conflicts. This is done automatically for sites installing version 3.11.0 or later. If your connections are/were being created with an earlier version, read the troubleshooting steps in [User Migration in Login by Auth0 WordPress Plugin](/docs/customize/integrations/cms/wordpress-plugin/user-migration-in-login-by-auth0).
:::

Once the configuration process is complete, log out of your WordPress site and attempt to log back in using your existing WordPress credentials in the Auth0 login form. This should create an Auth0 user linked to your WordPress account.

### Option 3: Manual Setup

This will skip the automatic setup and allow you to create and configure your own Application and database connection (see below). This should be used if you want this site to use an existing Application or database connection.

### Option 4: Import Setup

The site can also be set up by importing settings from another site. This is useful if you're migrating between environments or have a similar WordPress site that is already configured.

## Setup complete

When you see the "Done" screen, Auth0 is enabled and ready to accept logins and, if configured, signups.

This is a good time to confirm that the basics are working for your site before changing any of the default settings:

1. Log out of WordPress and confirm that the Auth0 form now appears at `/wp-login.php`.
2. Log in with the Auth0 user created above.
3. Log out and try creating an account with a different email address (if you have "Anyone can register" turned on in your General WordPress settings).
4. Try logging in using a social connection (if you've turned those on).

Now you're ready to [configure the application](/docs/customize/integrations/cms/wordpress-plugin/configure-login-by-auth0).

## Manual setup

The plugin can be configured using the built-in Setup Wizard (covered below) or manually by creating an Application and assigning connections. The completely manual setup process can be used if you're having trouble with the wizard, have been through the setup process before, or want to share a database connection between Applications.

1. Go to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#), and select **Create**.
2. Give your application a descriptive name, select **Regular Web Applications**, then select **Create**.
3. Configure the application for your WordPress installation. To learn how to configure the application, read [Configure Login by Auth0](/docs/customize/integrations/cms/wordpress-plugin/configure-login-by-auth0) and follow all sections through "Update Auth0 settings in WordPress".

Once the steps above are complete, your site will be configured and ready to use.

## Learn more

* [Integrate with WordPress](/docs/customize/integrations/cms/wordpress-plugin/integrate-with-wordpress)
* [Configure Login by Auth0](/docs/customize/integrations/cms/wordpress-plugin/configure-login-by-auth0)
* [Troubleshoot Login by Auth0 WordPress Plugin](/docs/customize/integrations/cms/wordpress-plugin/troubleshoot-login-by-auth0)
* [Extend Login by Auth0 WordPress Plugin](/docs/customize/integrations/cms/wordpress-plugin/extend-login-by-auth0)


# Integrate with WordPress
Source: https://auth0.com/docs/customize/integrations/cms/wordpress-plugin/integrate-with-wordpress

Describes the scenarios of how Auth0 integrates with WordPress

The Login by Auth0 plugin handles login and account creation flows automatically by creating or matching user accounts with incoming Auth0 profile data. The login process and the signup process are similar and an account will be created or matched based on the data in your WordPress database. Logging in via Auth0 creates a WordPress account, and sign up via Auth0 matches an existing WordPress account.

If you are using the User Migration setting in the plugin, the login flow will be slightly different from what is explained below. To learn more, read [User Migration in Login by Auth0 WordPress Plugin](/docs/customize/integrations/cms/wordpress-plugin/user-migration-in-login-by-auth0).

Below are the steps in the process:

1. The user accesses the WordPress site's login page. This could be the main login page at `[SITE URL]/wp-login.php` or a page containing a widget or shortcode.
2. The user provides their username and password, clicks on a social icon to use another identity provider, or completes the Passwordless process in the Auth0 login form, Lock.
3. Auth0 attempts to authenticate the user with the method selected.

   1. If login or signup with a username + password or with Passwordless fails, an error message appears on Lock.
   2. If it is successful, the process continues.
4. The user is redirected to the `/authorize` endpoint with a login ticket and a `state` value generated by the plugin. Once this is complete, the Auth0 user record has been created and the rest of the process happens on the WordPress site.
5. The actual login process differs whether you are using the [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow) or the [Implicit Flow](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-implicit-flow):

   1. For Authorization Code Flow logins:

      1. The user is redirected back to a callback URL, `SITE URL/index.php?auth0=1` with an authorization code and the same `state` value in URL parameters.
      2. The `state` value is validated. If validation does not pass, an "Invalid state" error is shown and the login process stops. To learn more about state validation, read [Troubleshoot Login by Auth0 WordPress Plugin](/docs/customize/integrations/cms/wordpress-plugin/troubleshoot-login-by-auth0).
      3. The ID token is validated to make sure nothing was modified during transit. If the ID token is invalid, an error message is shown and the login process stops (see the Troubleshooting page for more information on ID token validation)
      4. The user profile data is retrieved via the Management API using the Machine-to-Machine Flow. To learn more, read [Machine-to-Machine Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow).
   2. For Implicit Flow logins:

      1. The user is redirected back to a callback URL, `SITE URL/wp-login.php?auth0=implicit` with an ID token and the same `state` value in an anchor link.
      2. This anchor link is parsed in JS and then POSTed back to a callback URL `SITE URL/index.php?auth0=implicit` with those 2 same values in URL parameters.
      3. The ID token is validated to make sure nothing was modified during transit. If the ID token is invalid, an error message is shown and the login process stops (see the Troubleshooting page for more information on ID token validation)
      4. The information in the valid ID token is used as the user profile data.
6. The Auth0 authentication process is complete and the plugin attempts to match the profile data with a user in WordPress.
7. The plugin checks whether the site requires an email address (plugin settings **Advanced** tab) and if the incoming profile has an `email_verified` flag set.

   1. If the site requires an email address and the incoming user does not provide an email address (some social identity providers, like X, do not include an email address), the login process stops with an error message stating "This account does not have an email associated."
   2. If the site requires an email address and the incoming user does not have the `email_verified` flag set to `true`, the login process stops with an error message stating "This site requires a verified email address" and a link to re-send the verification email. This continues to show until the user successfully verifies their email address.
   3. If the site does not require an email address or the incoming user has the `email_verified` flag set to `true`, then the login process continues.
8. The plugin checks to see if there is a user in the WordPress database with a `usermeta` value that matches the incoming Auth0 user ID (meaning that the user has signed up or logged in with Auth0 before):

   1. If a user is found that has the incoming user ID then the login process continues.
   2. If a user is not found with the incoming Auth0 user ID, the plugin looks for an email address matching the incoming user:

      1. If a match is found, that user is selected and the login process continues.
      2. If a match is not found, the plugin checks if registration is turned on for the WordPress site:

         1. If registration is turned off, the login process stops with an error message stating "Could not create user. The registration process is not available"`.`
         2. If registration is turned on, a new user is created and the login process continues.
9. The found or created user is updated with the incoming Auth0 profile data, including their Auth0 user ID.
10. The user is logged into their WordPress account with `wp_set_auth_cookie` and the core `do_login` action fires.
11. The user is redirected to a page on the site, which could be the default set in the plugin settings **Advanced** tab or the original login URL if a shortcode or widget was used or a different one provided during the login process.

The user is now logged into Auth0 and their WordPress account with the two associated by their Auth0 user ID.

## Learn more

* [Install Login by Auth0](/docs/customize/integrations/cms/wordpress-plugin/install-login-by-auth0)
* [Configure Login by Auth0](/docs/customize/integrations/cms/wordpress-plugin/configure-login-by-auth0)
* [Troubleshoot Login by Auth0 WordPress Plugin](/docs/customize/integrations/cms/wordpress-plugin/troubleshoot-login-by-auth0)
* [Extend Login by Auth0 WordPress Plugin](/docs/customize/integrations/cms/wordpress-plugin/extend-login-by-auth0)


# Troubleshoot Login by Auth0 WordPress Plugin
Source: https://auth0.com/docs/customize/integrations/cms/wordpress-plugin/troubleshoot-login-by-auth0

This page explains common troubleshooting issues with the Login by Auth0 WordPress plugin

Here are some common troubleshooting questions. If the items below do not solve your issue, then consider the following alternatives:

* If you're setting up the plugin for the first time or having problems with users logging in, please read [Configure Login by Auth0](/docs/customize/integrations/cms/wordpress-plugin/configure-login-by-auth0).
* If you found a bug in the plugin code, [submit an issue](https://github.com/auth0/wordpress/issues) or [create a pull request](https://github.com/auth0/wordpress/pulls) in GitHub.
* If you have questions about how to use Auth0 or the plugin, please [post on our community site](https://community.auth0.com/) or [create a request in the plugin's WordPress support forum](https://wordpress.org/support/plugin/auth0/).
* To see additional documentation and find more answers, [visit our support site](https://support.auth0.com/center/s/). Customers on a paid Auth0 plan can submit a trouble ticket for a fast response.

## I'm seeing the error message "Invalid state" that prevents me from logging in

State validation is a security feature added in [version 3.6.0](https://github.com/auth0/wordpress/releases/tag/3.6.0). A cached callback URL usually causes this error message (see your Application settings for the callback URLs that should not be cached). To learn more, read [Troubleshoot WordPress Plugin Invalid State Errors](/docs/customize/integrations/cms/wordpress-plugin/troubleshoot-wordpress-plugin-invalid-state-errors).

## I'm having an issue logging in or changing email/password using a custom database

To learn about possible solutions, read [User Migration in Login by Auth0 WordPress Plugin](/docs/customize/integrations/cms/wordpress-plugin/user-migration-in-login-by-auth0).

## I'm seeing the error message "Invalid ID token" or "Expired ID token" that prevents me from logging in

This is typically caused by a server set to an incorrect time. If the error message includes "used too early," then your server time is set in the future. If it says that the token is expired, then the server time is set too far in the past. A difference in time between two servers is common. Output `echo date(DateTime::ISO8601)` in PHP on your server and compare that, including seconds, to the current UTC time. If your server's time is more than 60 seconds (the default leeway) off from UTC time, then you’ll need to set a longer leeway to account for your server’s clock skew. You can paste the below code in your theme's `functions.php` or anywhere else that would run it after the plugin loads and before the login hook runs:

```js wrap lines theme={null}
add_filter( 'auth0_jwt_leeway', function( $default_leeway ) { return 120; } );
```

This would provide a 120 second leeway. You may need to adjust this depending upon how skewed your server's time is.

## I see the error message "This account does not have an email associated..." that prevents me from logging in

If you get this error, make sure you are requesting an email from each provider in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> under **Connections > Social** (expand each provider). Take into account that not all providers return email addresses for users (e.g., X). If this happens, you can always add an Email address to any logged in user through the Auth0 Dashboard (or API). See **Users > Edit**.

For Connections that don't provide an `email_verified` flag (some Enterprise connections will not include this) or to skip this validation for specific Social Connections, add the strategy for that Connection in the "Skip Strategies" field. This field is located below the **Require Verified Email** switch accessible via **wp-admin** > **Auth0** > **Settings** > **Advanced**.

**This field should only be used if necessary because it circumvents the security precautions recommended by Auth0.**

## I see the error message "There is a user with the same email" that prevents me from logging in

This means that there is a user in WordPress that has the same email as the one being used to login associated with a different Auth0 user. If you're in the process of testing the plugin or want to associate the existing user with the new Auth user instead:

1. Log in as an admin
2. Go to **wp-admin > Users** and search for the email being used
3. View the user's profile and scroll down to the bottom
4. Click **Delete Auth0 Data** and confirm

If you have 2 user accounts in Auth0 with the same email address, this error message will persist. We recommend that you [link user accounts](/docs/manage-users/user-accounts/user-account-linking/link-user-accounts).

## I see the error message "Failed cross origin authentication" or "No verifier returned from client" in my browser's console logs when trying to log in

Go to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), select your WordPress application to view its settings, and check that the **Allowed Callback URLs** and **Allowed Origins (CORS)** match your WordPress site.

If you're using a Chromium-based browser, make sure you don't have third-party cookies turned off. To learn more, read [Cross-Origin Authentication](/docs/authenticate/login/cross-origin-authentication).

## I need to rerun the Setup Wizard, but I don't see that menu option anymore.

This means that the plugin is already configured with a Domain, <Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>, and <Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip>. Running the Setup Wizard a second time can have unpredictable results. If you're setting up WordPress for the first time and want to start over before any logins have occurred:

1. Go to **wp-admin** > **Auth0** > **Settings** > **Basic**.
2. Delete the Domain and Client ID. Scroll down and click **Save Changes**.
3. Go to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications).
4. Find the Application that was created by WordPress (its name should be the site name of your WordPress site).
5. Select the Application to view its settings. Scroll down, and select **Delete Application**.
6. Go to [Auth0 Dashboard > Authentication > Database](https://manage.auth0.com/#/connections/database).
7. Find the Connection that was created by WordPress (its name should be the site name of your WordPress site prepended with "DB-").
8. Select the Connection to view its settings. Scroll down, and select **I Want To Delete This Connection.** Please note that this will delete the Connection and all users that were created within it.
9. Return to WordPress. You will now see the Setup Wizard option under Auth0 in the admin menu.

## How do I setup Passwordless login?

<Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> login is possible any Auth0-enabled website using email or SMS. To make this work on your WordPress site:

1. Turn on **Passwordless Login** from the plugin settings' **Features** view and save.
2. Go to [Auth0 Dashboard > Authentication > Passwordless](https://manage.auth0.com/#/connections/passwordless).

* To use email, turn on the **Email** connection and modify the settings if desired. This will turn on email code login (users are emailed a code which is then typed into the login form on your site).
* To use a "magic link" (emailed link will automatically log users in), add `{passwordlessMethod: 'code'}` to the "Extra Settings" field in the plugin settings' **Advanced** tab.
* To use SMS login, turn on the **SMS** connection and follow the steps to set up a Twilio developer account (this will require a paid Twilio account depending on usage).

The Auth0 login form will select a Passwordless method depending on which connection is activated above. If you have both connections active, it will default to email. In this case, either turn off the email connection to show SMS or add `sms` to the **Connections** field in the plugin settings' **Advanced** tab.

## I have two accounts for the same user in WordPress

Under some situations, you may end up with a user with two accounts. WordPress allows you to merge users by deleting one of the accounts and attributing that account's content to another user. Go to wp-admin > Users, select the account you want to remove, and in the confirmation dialog select another user to transfer the content.

## My configuration is wrong, and I can't authenticate using Auth0. Is there another way to access the plugin?

The plugin can be accessed using valid WordPress credentials through the regular WordPress login by adding `?wle` to the login URL. For example: `http://yourdomain.com/wp-login.php?wle`.

## I am having problems when a user logs in. Where can I find a log of what is happening?

The plugin provides an error log where you can check what has happened. Access it through the **Error Log** sub-item of the **Auth0** plugin menu. You can find additional information at [Auth0 Dashboard > Monitoring > Logs](https://manage.auth0.com/#/logs).

## How can I show the widget or shortcode in signup mode by default?

You can use the widget `Extra configuration` setting (or the `extra_conf` attribute in the shortcode) and add this JSON `{"mode":"signup" }` that will force the plugin to be shown in this mode.

## When using a plugin to force the login, the user is not logged in

This is typically caused by a cached page after login. Check with your host for strategies to mitigate this or try adding a cache-busting parameter to the URL. To learn more, [use this gist on GitHub](https://gist.github.com/joshcanhelp/e3eb693749f0fe66aad097c3bbb3b415).

### The user is not logged in when using the "Force Login" plugin

This is because the callback URL has not been added to the AllowList. Try adding this code to the `my_forcelogin_whitelist` filter:

```javascript lines theme={null}
function wp_auth0_forcelogin_whitelist( $whitelist ) {
  if ( ! empty( $_GET['auth0'] ) ) {
    $whitelist[] = site_url($_SERVER['REQUEST_URI']);
  }
  return $whitelist;
}
add_filter('v_forcelogin_whitelist', 'wp_auth0_forcelogin_whitelist', 10, 1);
```

## How can I redirect the users to a specific URL after login?

All redirects are checked using `wp_safe_redirect()` before being performed. If you're trying to redirect to a domain that is not your main domain, add that domain to the check using the core WordPress `allowed_redirect_hosts` filter. To learn more, read [apply\_filters( 'allowed\_redirect\_hosts', string\[\] $hosts, string $host ) on wordpress.org](https://developer.wordpress.org/reference/hooks/allowed_redirect_hosts/).

### On the login page

This plugin leverages WordPress features to work seamlessly with default settings. To add a redirect, you can append the `redirect_to` query parameter to the URL when you direct the user to the login page. The plugin will redirect the user to this URL after a successful login.

You can also use the **Login redirection URL** setting in the Auth0 plugin settings page. This will URL be used to redirect the user when the `redirect_to` parameter is not provided.

### Using the widget

The widget will automatically redirect to the same page where the user was before authentication. You can override this using the `Redirect after login:` setting.

### Using the shortcode

The shortcode will automatically redirect to the same page where the user was before authentication. You can override this using the `redirect_to` attribute.

## How can I migrate my WordPress users to Auth0?

The current version of the plugin does not provide a way to migrate users to Auth0 automatically, but you have a few options:

* The plugin exposes two endpoints to mark your custom database connection for **import to Auth0** mode. To learn more about the endpoints, read [Configure Automatic Migration from Your Database](/docs/manage-users/user-migration/configure-automatic-migration-from-your-database).
* Export your user data to a JSON file and upload it for batch-import into Auth0. Initially, your users will have to reset their passwords when logging in using Auth0 because there is no way for Auth0 to decrypt the WordPress passwords during migration. To learn how to generate the JSON file, read [Bulk User Imports](/docs/manage-users/user-migration/bulk-user-imports). Then you will need to upload the file using the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>'s [Import Users endpoint](https://auth0.com/docs/api/management/v2/jobs/post-users-imports).
* [Use this script](https://gist.github.com/glena/b31716e3c8fe48927be2) and the WordPress XML RPC endpoint to set up the migration flow using a custom database connection. To learn more about setting up the migration flow, read [Configure Automatic Migration from Your Database](/docs/manage-users/user-migration/configure-automatic-migration-from-your-database). To learn more about the WordPress XML RPC endpoint, read [XML-RPC Support on wordpress.org](https://codex.wordpress.org/XML-RPC_Support).

## The form\_title setting is ignored when I set up the dict setting

Internally, the plugin uses the dict setting to change the Auth0 widget title. When you set up the dict field, it overrides the form\_title one.

To change the form\_title in this case, you need to add the following attribute to the dict JSON:

```json lines theme={null}
{
    "signin": {
        "title": "The desired form title"
    }
}
```

## How can I modify the embedded Auth0 login form?

There are many options on the **Appearance** tab of the plugin settings page that can change the look and feel of the login form that is embedded on your site (`wp-login/php` page, shortcodes, or widgets). To learn more about these options, read [Configure Login by Auth0](/docs/customize/integrations/cms/wordpress-plugin/configure-login-by-auth0). This will not affect the the login form on the Auth0-hosted <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> Page.

There is also a field called "Extra Settings" on the **Advanced** tab that accepts a valid JSON object with all the settings you want to configure. This will override any changes made on the **Appearance** tab. To see all possible configuration options, read [Lock Configuration Options](/docs/libraries/lock/lock-configuration).

External style sheets and JS files should be loaded in your theme using the `wp_enqueue_scripts` hook for shortcodes/widgets and the `login_enqueue_scripts` hook for `wp-login.php`. To learn more, read [`do_action( 'wp_enqueue_scripts' )` on wordpress.org](https://developer.wordpress.org/reference/hooks/wp_enqueue_scripts/) and [`do_action( 'login_enqueue_scripts' )` on wordpress.org](https://developer.wordpress.org/reference/hooks/login_enqueue_scripts/).

## The session expires too soon

The Auth0 plugin does not handle sessions; it uses the WordPress settings. By default, user sessions are kept alive for two days. You can enable the `Remember users session` setting on the plugin settings' **Advanced** tab to allow sessions to remain live for up to 14 hours.

## How do I implement a Refresh Token?

We implemented additional parameters in the login methods used by the plugin to allow for <Tooltip href="/docs/glossary?term=Refresh+Tokens">Refresh Tokens</Tooltip>. Use the `auth0_auth_scope` filter combined with the `auth0_user_login` action to accomplish this.

## Profile data saved in WordPress is not being synced to the Auth0 user account.

This is a current limitation of the plugin but something we're looking at in a future release. The one exception to this is the user password. If the password is changed in WordPress and it passes the security policy set for the database connection being used, then that password will update for the Auth0 user as well. We'll be adding an error message in a future release to stop the process if the password is not strong enough.

## How do I migrate from "Social Login with Auth0" to "Login by Auth0"?

Historically, Auth0 has maintained two WordPress plugins:

* [Login by Auth0](https://wordpress.org/plugins/auth0/)
* [Social Login with Auth0](https://wordpress.org/plugins/social-login-with-auth0/)

These two plugins are effectively the same, but **Social Login with Auth** will not receive any updates past version 3.7.0 (released 13 August 2018). Migrating from **Social Login with Auth** to **Login by Auth0** is simple and won't result in any Auth0 or WordPress data loss.

Moving from **Social Login with Auth** to **Login by Auth0** will update the version number you see, so make sure to test this change out on a staging or development server first (just as you would if you were updating the plugin in wp-admin). Furthermore, logins may not work during the migration process, so be sure to use a maintenance mode plugin or complete the migration during off-peak hours.

The easiest way to migrate is via (S)FTP:

1. Log in to the WordPress site as an administrator.
2. [Download Login by Auth0](https://downloads.wordpress.org/plugin/auth0.zip) and unzip it locally.
3. Deactivate the **Social Login with Auth0** plugin from the WordPress admin > Plugins screen.
4. Log in to the server you want to migrate to and navigate to `wp-content/plugins`.
5. Move the `social-login-with-auth0` folder out of the plugins folder to back up the contents.
6. Upload the new `auth0` plugin folder to the plugins directory.
7. Activate the new "Login by Auth0" plugin from the WordPress **Admin** > **Plugins** screen.

If you're unable to access the site via FTP, you can also run the process directly from the WordPress admin:

1. Log in to the WordPress site as an administrator.
2. Go to **Auth0** > **Import-Export Settings**.
3. Click **Export Settings**, then **Export**.
4. Deactivate the **Social Login with Auth0** plugin from the WordPress **Admin** > **Plugins** screen.
5. Delete the **Social Login with Auth0** plugin and confirm.
6. Go to **Plugins** > **Add New** and search for "Auth0".
7. For the **Login by Auth0** plugin (make sure to check the name), click **Install Now**.
8. When this completes, click **Activate**.
9. Check **Auth0** > **Settings** and make sure the previous settings remain. If not:

   1. Go to **Auth0** > **Import-Export Settings**.
   2. Paste in the settings JSON exported previously and click **Import**.
10. Completely delete the settings file export JSON (it contains sensitive information).

Everything should now be working as expected with the new plugin and updates will resume as usual.

## Learn more

* [Integrate with WordPress](/docs/customize/integrations/cms/wordpress-plugin/integrate-with-wordpress)
* [Install Login by Auth0](/docs/customize/integrations/cms/wordpress-plugin/install-login-by-auth0)
* [Configure Login by Auth0](/docs/customize/integrations/cms/wordpress-plugin/configure-login-by-auth0)
* [Extend Login by Auth0 WordPress Plugin](/docs/customize/integrations/cms/wordpress-plugin/extend-login-by-auth0)


# Troubleshoot WordPress Plugin Invalid State Errors
Source: https://auth0.com/docs/customize/integrations/cms/wordpress-plugin/troubleshoot-wordpress-plugin-invalid-state-errors

Troubleshooting invalid state errors in the Login by Auth0 WordPress plugin

We added state validation to WordPress plugin version 3.6.0, which you can find in the [`auth0/wordpress` GitHub repository](https://github.com/auth0/wordpress/releases/tag/3.6.0). This security measure helps mitigate CSRF attacks by ensuring that the response belongs to a request initiated by the same user To learn more, read [Prevent Attacks and Redirect Users with OAuth 2.0 State Parameter](/docs/secure/attack-protection/state-parameters).

## How state validation works

The plugin performs state validation by:

1. Setting an `auth0_state` cookie in the browser via Javascript when the Lock login form is shown (on `wp-login.php` or any other page when using a shortcode or widget).
2. Passing that value to the Lock embedded login form so it can be sent with the authentication request.
3. Receiving that value back from Auth0 unchanged in a `state` URL parameter if the Auth0 login was successful.
4. Validating the that value received matches the value sent and stored in the `auth0_state` cookie. If it's valid, then the login process continues. If not, the process stops and an "Invalid state" error message is shown.
5. Deleting the cookie, regardless of validity.
6. Using values in the base64 decoded object to redirect or perform other login actions, if valid.

This process should be completely opaque to both the logging-in user and the site admin. The Auth0 server does not validate or require a state value and returns it untouched to the callback URL. If the "Invalid state" message is seen, then one of the first 4 steps above is not happening.

## Common causes of the invalid state error

Below are some common causes of the invalid state error as well troubleshooting steps you can take.

### Cached callback URLs

The most common cause of the invalid state error is when the callback URL is cached on the server.

Exclude caching on your server for all the URLs listed in the **Allowed Callback URLs** field in [Auth0 Dashboard > Applications > Applications > Settings](https://manage.auth0.com/#/applications/\{yourClientId}/settings) and test again. In addition, exclude caching the site URL (`/index.php` on a regular install) if it has an Auth0 URL parameter.

Check to see if your server’s time is not set properly. The `BeforeValidException` error can occur when the token is perceived to have been generated before the current time, which can happen if the server times are off. You can check server time by using `echo current_time( 'c' )`. A temporary workaround may also be to modify the plugin to add a time offset if you cannot modify the server time, but it should be fixed for production.

If that does not solve the issue, continue with the troubleshooting steps below.

### Cached cookies and URL parameters

If you're on a managed host like WP-Engine, you may need to contact their support team for additional assistance. We've had reports of issues accessing required cookies on the callback URL, as well as problems with checking authentication on the final page that users see after logging in. Specifically, ask to have cache exclusions added for:

* **Cookie:** `auth0_state`
* **Cookie:** `auth0_nonce`
* **Arg/URL parameter:** `auth0`
* **Arg/URL parameter:** `code`
* **Arg/URL parameter:** `state`
* **Arg/URL parameter:** `id_token`

### Page refresh after error message

If you refresh the page after seeing a different error message (email verification, etc) the invalid state message will appear, as it’s trying to revalidate an already used value. This is expected.

### Cookie names requirement

Some hosts, like Pantheon, require specific cookie names to be used. You can alter the cookie name using the `auth0_state_cookie_name` filter in your theme or a custom plugin. To learn more about the `auth0_state_cookie_name` filter, read [Extend Login by Auth0 WordPress Plugin](/docs/customize/integrations/cms/wordpress-plugin/extend-login-by-auth0). For additional information, [see the related GitHub issue](https://github.com/auth0/wordpress/issues/494) and [explore its fix](https://github.com/auth0/wordpress/pull/495).

### Universal Login Page and link building

If your site is using the <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> Page and you're building the link yourself in a theme or plugin, you need to:

* Set a cookie called `auth0_state` with a randomly-generated value
* Send that value in a `state` URL parameter.

Alternatively, you can go to Settings > Features tab > Universal Login Page and redirect login requests to the `wp-login.php` page where that cookie and URL parameter will be set automatically.

### Visiting the callback URL directly

If you visit your callback URL (typically `yourdomain.com/index.php?auth0=1`) directly or a second time after the authorization code has been exchanged, the invalid state error might display. This indicates that the state has already been verified and deleted.

## Troubleshoot invalid state errors

Note that some of the steps below will require the login process to be broken during the process (marked as such):

1. While logged out of WordPress and Auth0, visit the login page being tested.
2. Check if the `auth0_state` cookie is being set (in Chrome, View > Developer > JavaScript Console > Application tab > Storage on the left > Cookies > domain being tested, look for an `auth0_state` cookie with a non-empty value).

   * If this value is not set, check for errors in the JS console and make sure that your browser can accept cookies (login will not work without cookies).
   * If the value is set, copy the value and view the source code of the page (in Chrome, **View** > **Developer** > **View Source**). Search for the value, and it should appear as the value associated with parameter `wpAuth0LockGlobal.settings.auth.params.state` ([view sample JSON](https://gist.github.com/joshcanhelp/1b8bb990048325eb7214e2b3d7136b78)). Make a note of this value (you'll need it in a following step).
3. If the value appears there and the Lock form is loading normally then steps 1 and 2 from the first list above are functioning properly.
4. Before logging in, [add this code snippet to the top of your `wp-config.php`](https://gist.github.com/joshcanhelp/ba98f748747c7fd2ecdf54e73c6110f3), so you can do a test install. **WARNING**: This will break login for the WordPress site being tested, so use it only on a non-production install.
5. Log in normally.
6. After you're redirected back to your site's callback URL, the process will stop. You should see an output like what's shown in the linked Gist in step #4 above. If you see something like `Array()` with no additional values, then one of two things could be happening:

   * The WordPress callback URL is cached. Page caching can happen in many different ways so there are not explicit steps we can provide here. Check any caching plugins you may have installed, they usually have some kind of URL exclusion built-in. Also check with your host as caching may be automatic and require support involvement.
   * The server is not reading the Auth0 cookie. For a possible solution, [see the related GitHub issue](https://github.com/auth0/wordpress/issues/494) and [explore its fix](https://github.com/auth0/wordpress/pull/495).
7. If the values are present, check the response headers for the callback URL being loaded (in Chrome, View > Developer > JavaScript Console > Network tab, click the first "document" listed with a 500 status and look for "Response Headers"). Look for any evidence of caching here, like a `Cache-Control` with a non-zero `max-age`, an `x-cache` of something other than `MISS`, or any other clue that this page is being served from a cache.
8. Also in the response headers, check that `set-cookie` includes a directive like `auth0_state=deleted` to confirm the validation process is happening.
9. Make sure that the `state` parameter in the URL matches the one recorded from the cookie being set in step #3 above.
10. If there is no evidence of caching, remove the debugging snippet from `wp-config.php` and refresh the callback URL. You should see the "Invalid state" message again. If any caching changes were made, attempt the login process all the way through (make sure to clear your cookies and browser cache for the site before testing).

The following troubleshooting steps require plugin changes that will break the login process and need to be rolled back once complete. These steps should be performed on a test or staging server.

11. Next, we need to check why the state is coming in but does not match the stored value.

12. In `lib/WP_Auth0_LoginManager.php`, output the values of the stored and returned state and stop the process after. Just before [line 148](https://github.com/auth0/wp-auth0/blob/master/lib/WP_Auth0_LoginManager.php#L148), add:

```bash wrap lines theme={null}
echo '<h1>$_REQUEST</h1>'; var_dump($_REQUEST); echo '<h1>$_COOKIE</h1>'; var_dump($_COOKIE); die('<h1>Done</h1>');
```

13. Once again, make sure you're logged out and complete the login process.

14. You should see values output when redirected back to the WordPress callback URL.

15. Check if the `state` value in `$_REQUEST` exists and matches the `auth0_state` value in `$_COOKIE`.

* If it's different, it should match the original value recorded in step #3 above. This means that the `$_COOKIE` state value has changed somewhere in the process.

If none of the steps above resolve the issue, please collect the results of the steps above and [contact support](https://support.auth0.com/center/s/) or [post on Community](https://community.auth0.com/tag/wordpress) with the tag `wordpress`. Also include:

* PHP version
* WordPress version
* Auth0 plugin version
* Browser and OS used to test
* A HAR file recording the entire process from loading the page with the login form all the way through the "Invalid state" message. To learn more about HAR files, read [Generate and Analyze HAR Files](/docs/troubleshoot/troubleshooting-tools/generate-and-analyze-har-files).

  <Warning>
    Before sharing a HAR file with anyone (including Auth0), ensure that you remove or obfuscate all sensitive data, such as:

    * Confidential user information
    * Personal identifiable information (PII)
    * Confidential application information

    To learn more, read the following articles in the Auth0 Support Center:

    * [Sanitizing HTTP Traces](https://support.auth0.com/center/s/article/How-to-Remove-Secrets-from-a-har-File)
    * [How to Sanitize an HTTP Trace File Automatically](https://support.auth0.com/center/s/article/How-to-Sanitize-a-HTTP-Trace-File-Automatically)
    * [How to Manually Redact Sensitive Information](https://support.auth0.com/center/s/article/How-to-Manually-Redact-Sensitive-Information)
    * [HAR File is Too Large to Upload to the Support Case](https://support.auth0.com/center/s/article/HAR-File-is-too-Large-to-Upload-to-the-Support-Case)
  </Warning>

## Related posts

* ["Invalid state" error during Auth0 WordPress redirect](https://community.auth0.com/t/invalid-state-error-during-auth0-wordpress-redirect/12552/16) in Auth0 Community
* [Invalid state when visiting the callback URL directly](https://wordpress.org/support/topic/unable-to-resolve-troubleshooting-with-a-client-grant-for-already-exists/) on wordpress.org


# User Migration in Login by Auth0 WordPress Plugin
Source: https://auth0.com/docs/customize/integrations/cms/wordpress-plugin/user-migration-in-login-by-auth0

Describes the user migration feature of the Login by Auth0 WordPress Plugin

The User Migration functionality uses a core Auth0 feature called Custom Databases combined with URL endpoints in the Login by Auth0 plugin to allow users to authenticate with existing WordPress user accounts. To learn more about custom databases, read [Custom Database Connections](/docs/authenticate/database-connections/custom-db).

## How It Works

When you enable data migration, the plugin exposes two secure endpoints that allow Auth0 to authenticate users using WordPress accounts. These endpoints are secured with a secret token and can be set only to allow IP addresses used by Auth0.

The login flow is as follows:

1. A user attempts to login with an Auth0 login form (embedded on your site or hosted at Auth0).
2. If Auth0 can't find a user associated with the provided credentials in your database connection, it proceeds to call the Migration endpoint on your WordPress site with the user credentials and the migration token.
3. The plugin finds a user in your WordPress database with the provided username/email and verifies the password.
4. If a user can be successfully authenticated, Auth0 creates the user in the database connection for your site, authenticates the user, and logs them in.
5. The next time the user logs in, they will use the Auth0 user, and the Migration endpoint will be skipped.

User Migration must be set up when the site is first connected to Auth0. Attempting to turn on or off custom database scripts for a database connection that has already had users will fail. See the **Troubleshooting** section for more information about moving between modes.

## Set Up and Configuration

The easiest way to construct User Migration is to use the Setup Wizard when the plugin is first installed. To learn more about the process, read [Install Login by Auth0](/docs/customize/integrations/cms/wordpress-plugin/install-login-by-auth0).

If the User Migration Setup Wizard could not complete or you want to see the process in more detail, follow the steps below. Again, this is starting from scratch with a database connection that does not have any users. The following process should be completed on a site with no traffic or with maintenance mode turned on.

1. [Create and correctly configure an Application](/docs/customize/integrations/cms/wordpress-plugin/configure-login-by-auth0), and create and activate an empty Database Connection for the Application. These can be the same as the ones created in the standard Setup Wizard process, or you can create these from scratch. To learn more about the Setup Wizard, read [Install Login by Auth0](/docs/customize/integrations/cms/wordpress-plugin/install-login-by-auth0).
2. In the **Auth0 > Settings** screen in WordPress, make sure the Application's Domain, Client ID and Client Secret are saved in the correct fields in the **Basic** tab.
3. In the **Advanced** view, enable the **User Migration Endpoints** setting, and select **Save Changes**. If you are using constant-based settings, set `AUTH0_ENV_MIGRATION_WS` to `true` and `AUTH0_ENV_MIGRATION_TOKEN` to a secure random string at least 16 digits long and without single quotes or backslashes.
4. Under the settings, you should now see a **Security Token**. Keep this page open as you will need this value later on in the process.
5. In the Auth0 Dashboard, go to the Database Connection you want to use and enable **Requires Username** and **Import Users to Auth0**.
6. Select the **Custom Database view**, and enable **Use my own database**.
7. There should be two tabs below this setting under **Database Action Scripts**: one for **Login** and one for **Get User**.
8. Select the **Login** view, clear out the existing code, [copy the db-login.js code from the GitHub repository](https://raw.githubusercontent.com/auth0/wp-auth0/4.4.0/lib/scripts-js/db-login.js), and paste it into the code editor.
9. **This step is for versions 3.10.0 and earlier:** Look for `{THE_WS_URL}` and replace that with your WordPress instance's site URL, followed by `/index.php?a0_action=migration-ws-login`. The site URL can be found in the **Settings > General** screen in wp-admin. You can test this by pasting the complete URL in your browser. You should see `{"status":401,"error":"Unauthorized"}`.
10. **This step is for versions 3.10.0 and earlier:** Look for `{THE_WS_TOKEN}` and replace that with the token that appears under the **User Migration Endpoints** setting.
11. There should be no errors in the editor. If everything looks good, click **Save** at the top.
12. **This step is for 3.11.0 and later:** Scroll down to **Settings** and add the following configuration variables:

    * `endpointUrl` set to your WordPress instance's site URL (**wp-admin > Settings > General > "Site URL" field**), followed by `/index.php?a0_action=`.
    * `migrationToken` set to the security token value seen in step 4 above.
    * `userNamespace` set to your Application name in Auth0 or any other value only including letters, numbers, and dashes.

    <Frame>
      <img alt="WordPress Plugin custom database settings" />
    </Frame>
13. Click the **Try** button at the top and use a valid WordPress user account in the form that appears. You should see the "The profile is" followed by the user's data. If not, please see the **Troubleshooting** section below.
14. Select the **Get User** view, clear out the existing code, [copy the db-get-user.js code from the GitHub repository](https://raw.githubusercontent.com/auth0/wp-auth0/4.4.0/lib/scripts-js/db-get-user.js), and paste it into the code editor.
15. **This step is for 3.10.0 and earlier:** Look for `{THE_WS_URL}` and replace that with your WordPress instance's site URL, followed by /index.php?a0\_action=`migration-ws-get-user`. The site URL can be found in the **Settings > General** screen in wp-admin. You can test this by pasting the complete URL in your browser. You should see `{"status":401,"error":"Unauthorized"}`.
16. **This step is for 3.10.0 and earlier:** Look for `{THE_WS_TOKEN}` and replace that with the token that appears under the **User Migration Endpoints** setting.
17. There should be no errors in the editor. If everything looks good, click **Save**.
18. Click the **Try** button at the top and use an email with a valid WordPress user account in the form that appears. You should see the "The profile is" followed by the user's data. If not, please see the **Troubleshooting** section below.
19. In a new browser session, navigate to a login page on the WordPress site and attempt to log in (the user should not already exist in the database). You'll notice that the login process takes a little longer than usual at first, but it should succeed. Subsequent logins will be faster.
20. (OPTIONAL) To turn on additional security for the migration endpoints, go to **Auth0 > Settings** screen in WordPress, turn on, then **Save Changes**. Attempt to log in with a different user to test that Auth0 can still reach the endpoints.

At this point, the User Migration setup is complete, and existing WordPress users will be trickle-migrated to the Auth0 Database Connection.

## Troubleshooting

Issues with the User Migration typically come from a few places:

* Incorrect URL or token in the custom database scripts.
* IP allow list turned on but with incorrect IP addresses.
* Restricted or cached endpoints on your WordPress instance.

The best way to start troubleshooting the issue is to use the **Try** button for the **Login** script found in the Custom Database view of the Database Connection being used on [Auth0 Dashboard > Authentication > Database](https://manage.auth0.com/#/connections/database). The following are the error messages you might see and the steps to take to fix.

### Unexpected token \< in JSON at position 0

This means the custom script is not getting data back in a format it can use. An incorrect endpoint URL likely causes this in the database script.

First, copy the URL on line 10 in the script and paste it in your browser. If the endpoint is correct, it should display one of the two messages below:

`{"status":401,"error":"Unauthorized"}`

`// or`

`{"status":403,"error":"Forbidden"}`

If what you're seeing is the home page or a 404, then the URL is incorrect. Look for your site URL under **Settings > General > Site URL** in the WordPress admin. Add `/index.php?a0_action=migration-ws-login` to the end for the Login script and `/index.php?a0_action=migration-ws-get-user` to the end for the Get User script.

* **For versions 3.10.0 and earlier**: The URL value should appear in the script itself as the first parameter in the `request.post` call.
* **For versions 3.11.0 and later**: The token value should be saved in a configuration variable. Add the following to the first line of the function and use the **Try** button to see what is stored for `endpointUrl`:

`callback(null, configuration);`

If you're sure the URLs are correct and are still having this issue, check with your host to make sure those URLs are not cached or restricted in any way.

### Wrong email or password

This is the default error shown if anything else goes wrong. The easiest way to troubleshoot what's happening is to temporarily output the error that's being sent back (these are opaque by default to avoid displaying anything that might give attackers something to work with).

On line 30 of the Login script, change:

`callback(null);`

to:

`callback(wpUser.error);`

Save the script, and try the connection again. You should see one of the following messages and be able to pinpoint the issue with the steps below. Once you've solved the issue, change the script back to what it was.

### Forbidden

This means that the migration endpoints are turned off in your WordPress install. In WordPress, go to **Auth0 > Settings > Advanced** and turn on **User Migration Endpoints**. Make sure the token that appears there is the same as what is used for both custom database scripts:

* **For versions 3.10.0 and earlier**: The token value should appear in the script itself after `access_token:`
* **For versions 3.11.0 and later**: The token value should be saved in a configuration variable. Add the following to the first line of the function and use the **Try** button to see what is stored for `migrationToken`:

`callback(null, configuration);`

### Unauthorized

This means that the migration IP allow list is turned on, but the incoming IP address is not on the list. Just below the Login script you should see a list of IP addresses:

<Frame>
  <img alt="WordPress User Migration - Auth0 IP Addresses" />
</Frame>

Make sure all of those IP addresses appear in WordPress under **Auth0 > Settings > Advanced** in the plugin:

<Frame>
  <img alt="WordPress User Migration - IP Whitelist" />
</Frame>

If one or more of the IP addresses listed in Auth0 do not appear in WordPress, add the missing ones into the field and save the settings page. Also, [create a post in the Auth0 Community](https://community.auth0.com/tags/wordpress) (and tag it "wordpress") that contains the missing IP address(es), so we can address the issue.

### Unauthorized: missing authorization header

The <Tooltip href="/docs/glossary?term=security+token">security token</Tooltip> is either missing in the database script (line 16), or your server is not processing the headers correctly. Check the Login script and make sure that the token exists and matches what is in WordPress. If the token is there and correct, then you'll need to talk to your host to enable the `Authorization` header to be parsed. For help with server troubleshooting, read [Apache 2.4 + PHP-FPM and Authorization headers on stackoverflow.com](https://stackoverflow.com/questions/17018586/apache-2-4-php-fpm-and-authorization-headers). To see how the token is retrieved, view the [plugin code in the GitHub repository.](https://github.com/auth0/wp-auth0/blob/master/lib/WP_Auth0_Routes.php#L138)

### Invalid token

The security token in the database script is incorrect. Check the Login script line 16 and make sure that the token matches what is in WordPress.

### Invalid Credentials

The email address and/or password being used is incorrect. Check to make sure you're entering the correct email address and that the password is correct. You can reset the user password to something else to make sure you have the correct one.

### Cannot Change Email or Incorrect User Data

If you are using more than one custom database connection in your Auth0 tenant and you're unable to change the email address or are getting user data stored for the wrong user, it's likely that you have overlapping user IDs in Auth0. This problem has been fixed for new sites installing 3.11.0 but, for connections created before then, this will need to be manually fixed by doing one of the following:

* If you don’t have any user data stored that needs to be kept (if you’re only using the connection to support login and not storing any metadata), you can create a new custom database connection using the steps above (using the 3.11.0 notes) and switch the Application to this new connection (make sure to turn the old connection off). The migration will be restarted, and there will be no impact on the user experience.
* If you do have data in Auth0 that needs to be kept, you can [use our User Import/Export Extension](/docs/manage-users/user-migration/user-import-export-extension) to adjust the user data.
  1. Create a new custom database connection using the steps above (using the 3.11.0 notes).
  2. Export all users from the existing connection (we recommend putting your site in maintenance mode while doing the switch-over, so no users are missed).
  3. Change all user IDs to add the namespace used when creating the new connection. User IDs should go from something like `auth0|123` to `auth0|Your-WP-Site-Name|123`. Adjust all other fields you need to follow the import schema. To learn more, read [Bulk User Import Database Schema and Examples](/docs/manage-users/user-migration/bulk-user-import-database-schema-and-examples).
  4. Turn the new connection on and the old connection off for your application.
  5. Import the new user data into the new connection and test.
* If you have a paid account, you can contact our support team to run a database update script to change the user IDs to a namespaced version and add the namespace to your database script at the same time (step 12 in **Set Up and Configuration** above).


# Connect Provider Hosted Apps to SharePoint Online
Source: https://auth0.com/docs/customize/integrations/connecting-provider-hosted-apps-to-sharepoint-online

How to connect provider hosted apps to SharePoint Online.

Auth0 can help radically simplify the authentication process for SharePoint Apps. Auth0 will negotiate an <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> you can the use to call SharePoint APIs.

You won't need any special libraries. You can use any of the SDKs supported by Auth0.

## Step 1. Register your application in Auth0

Just register a new application in Auth0 as you would normally do: **Applications > NEW**. Pick up any of the SDKs available for detailed instructions. Keep the `client_id` handy, as you will need it in the next step.

## Step 2. Create a package for your application

You need to obtain a **<Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>** and a **<Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip>** for your application. There are many ways of registering your application depending on the expected usage.

[Register SharePoint Add-ins (Microsoft Docs)](https://docs.microsoft.com/en-us/sharepoint/dev/sp-add-ins/register-sharepoint-add-ins) explains all different ways of registering your application in SharePoint. This step in the tutorial will use the simplest form: using self-registration in a specific tenant (yours).

### Open SharePoint Online

The URL for the dashboard is `https://{your Office365 tenant}.sharepoint.com/_layouts/15/appregnew.aspx`

### Generate a Client\_Id and ClientSecret:

<Frame>
  <img alt="SharePoint - generate client id - generate client secret" />
</Frame>

### Complete the information in the form:

Since Auth0 is in between your app and the Office 365 infrastructure, you need to use this URL for the app:

**App Domain**:

<AuthCodeBlock />

**Redirect URI**:

<AuthCodeBlock />

* `connection` is just the name you will use in Auth0's connections (such as "sharepoint").
* `client_id` identifies your app in Auth0 (created in steps 1).
* `redirect_uri` is the location in your actual app, where your users will land eventually after all negotiations complete. If you don't specify it, it will always be the app's callback URL defined in Auth0 (it could be localhost)

### Package the app and upload to SharePoint:

Complete the information in your app manifest in Visual Studio:

<Frame>
  <img alt="SharePoint - Visual Studio - Application Manifest" />
</Frame>

Notice the `Query string` will be exactly like the `Redirect URI` you completed before. Then right-click on the project and select `Publish`:

Create a **Publishing Profile** (you will have to enter the same **Client Id** & **Client Secret** obtained in the SharePoint dashboard).

Click on **Package** and upload the resulting file to SharePoint.

## Step 3. Create the Connection in Auth0

The last step in the integration is to add a SharePoint connection in Auth0.

You will need:

* `Connection Name`. This is an arbitrary name. It has to match with what you entered in step 2.
* `Client Id` & `Client Secret`. Also need to match what you entered in step 2.
* `Test SharePoint Site Url`. This is the SP site URL used to test the connection. (such as when pressing the 'Try' button on the dashboard). This is never used at runtime because users will always follow the link to your site from within SharePoint.

Users will install your app from the Office Marketplace. When they click on the link, they will be directed to Auth0, which will negotiate the Access Token for you, and finally to your app. Your app will receive a `User Profile` that will look like this:

<Frame>
  <img alt="Office Marketplace - Redirect -  User Profile Example" />
</Frame>

The following properties will be included: `cacheKey`, `refresh_token`, `host`, and `site`. These will allow you to call back SharePoint APIs (such as lists).


# Secure Google Cloud Endpoints with Auth0
Source: https://auth0.com/docs/customize/integrations/google-cloud-endpoints

How to secure a Google Cloud Endpoints API with Auth0.

[Google Cloud Endpoints (GCE)](https://cloud.google.com/endpoints/) is an API management system providing features to help you create, maintain, and secure your APIs. GCE uses [OpenAPI](https://www.openapis.org/) to define your API's endpoints, input and output, errors, and security description.

For more information on the OpenAPI spec, see the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification) repository on GitHub.

This tutorial will cover how to secure Google Cloud Endpoints with Auth0.

## Prerequisites

Before you begin you'll need a deployed GCE API. If you haven't already created an API, complete the [Cloud Endpoints Quickstart](https://cloud.google.com/endpoints/docs/quickstart-endpoints) located in Google documentation.

The quickstart will walk you through creating a simple GCE API with a single endpoint, `/airportName`, that returns the name of an airport from its three-letter [IATA code](https://en.wikipedia.org/wiki/IATA_airport_code).

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request GET \
    --url 'https://%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO'
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO");
  var request = new RestRequest(Method.GET);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO"

  	req, _ := http.NewRequest("GET", url, nil)

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java lines theme={null}
  HttpResponse<String> response = Unirest.get("https://%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://%7ByourGceProject%7D.appspot.com/airportName',
    params: {iataCode: 'SFO'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C lines theme={null}
  #import <Foundation/Foundation.h>

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];

  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];
  ```

  ```php PHP lines theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  conn.request("GET", "%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO")

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift lines theme={null}
  import Foundation

  let request = NSMutableURLRequest(url: NSURL(string: "https://%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"

  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()
  ```
</AuthCodeGroup>

## Define the API in Auth0

Go to [Auth0 Dashboard > Applications > APIs](https://manage.auth0.com/#/apis), and create a new API.

<Frame>
  <img alt="Dashboard - Create APIs - Integrations -Google Endpoints" />
</Frame>

Make note of the **API <Tooltip href="/docs/glossary?term=Audience">Audience</Tooltip>** identifier (`http://google_api` in the screenshot above) to use in the following step.

## Update the API Configuration

Next, we'll update the OpenAPI configuration file for the GCE API. For the sample API created during the quickstart this file is `openapi.yaml`.

### Add Security Definitions

Open the configuration file and add a new `securityDefinitions` section. In this section, add a new definition (`auth0_jwt`) with the following fields:

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>authorizationUrl</code></td>
      <td>The authorization URL, should be set to <code>"https\:///authorize"</code></td>
    </tr>

    <tr>
      <td><code>flow</code></td>
      <td>The flow used by the OAuth2 security scheme. Valid values are <code>"implicit"</code>, <code>"password"</code>, <code>"application"</code> or <code>"accessCode"</code>.</td>
    </tr>

    <tr>
      <td><code>type</code></td>
      <td>The type of the security scheme. Valid values are <code>"basic"</code>, <code>"apiKey"</code> or <code>"oauth2"</code></td>
    </tr>

    <tr>
      <td><code>x-google-issuer</code></td>
      <td>The issuer of a credential, should be set to <code>"https\:///"</code></td>
    </tr>

    <tr>
      <td><code>x-google-jwks\_uri</code></td>
      <td>The URI of the public key set to validate the <Tooltip href="/docs/glossary?term=JSON+Web+Token+%28JWT%29">JSON Web Token (JWT)</Tooltip> signature. Set this to `"https://\{yourDomain}/.well-known/jwks.json"`</td>
    </tr>

    <tr>
      <td><code>x-google-audiences</code></td>
      <td>The API's identifier, make sure this value matches what you defined on the Auth0 dashboard for the API.</td>
    </tr>
  </tbody>
</table>

<AuthCodeBlock />

### Update the Endpoint

Now, update the endpoint by adding a `security` field with the `securityDefinition` we created in the previous step.

```yaml lines theme={null}
paths:
  "/airportName":
    get:
      description: "Get the airport name for a given IATA code."
      operationId: "airportName"
      parameters:
        -
          name: iataCode
          in: query
          required: true
          type: string
      responses:
        200:
          description: "Success."
          schema:
            type: string
        400:
          description: "The IATA code is invalid or missing."
      security:
       - auth0_jwt: []
```

In the above example, the `security` field tells the GCE proxy that our `/airportName` path expects to be secured with the `auth0-jwt` definition.

After updating the OpenAPI configuration, it should look something like this:

<AuthCodeBlock />

### Redeploy the API

Next, redeploy your GCE API to apply the configuration changes. If you followed along with the [Cloud Endpoints Quickstart](https://cloud.google.com/endpoints/docs/quickstart-endpoints) you can redeploy by entering the following in Google's Cloud Shell:

```bash lines theme={null}
cd endpoints-quickstart/scripts
./deploy_api.sh
```

## Test the API

Once you've redeployed, call the API again with no security.

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request GET \
    --url 'https://%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO'
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO");
  var request = new RestRequest(Method.GET);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO"

  	req, _ := http.NewRequest("GET", url, nil)

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java lines theme={null}
  HttpResponse<String> response = Unirest.get("https://%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://%7ByourGceProject%7D.appspot.com/airportName',
    params: {iataCode: 'SFO'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C lines theme={null}
  #import <Foundation/Foundation.h>

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];

  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];
  ```

  ```php PHP lines theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  conn.request("GET", "%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO")

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift lines theme={null}
  import Foundation

  let request = NSMutableURLRequest(url: NSURL(string: "https://%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"

  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()
  ```
</AuthCodeGroup>

You'll get the following response:

```json lines theme={null}
{
 "code": 16,
 "message": "JWT validation failed: Missing or invalid credentials",
 "details": [
  {
   "@type": "type.googleapis.com/google.rpc.DebugInfo",
   "stackEntries": [],
   "detail": "auth"
  }
 ]
}
```

Which is exactly what we want!

Now go to the **Test** page of your Google Endpoints API definition on the [Auth0 Dashboard](https://manage.auth0.com/#/apis), and copy the <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> under the Response:

Perform a `GET` request to your API with an Authorization Header of `Bearer {ACCESS_TOKEN}` to obtain authorized access:

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request GET \
    --url 'https://%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO' \
    --header 'authorization: Bearer {accessToken}'
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer {accessToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer {accessToken}")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java lines theme={null}
  HttpResponse<String> response = Unirest.get("https://%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO")
    .header("authorization", "Bearer {accessToken}")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://%7ByourGceProject%7D.appspot.com/airportName',
    params: {iataCode: 'SFO'},
    headers: {authorization: 'Bearer {accessToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C lines theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {accessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP lines theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {accessToken}"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {accessToken}" }

  conn.request("GET", "%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer {accessToken}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift lines theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {accessToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://%7ByourGceProject%7D.appspot.com/airportName?iataCode=SFO")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

And that's it!


# Integrate with Netlify
Source: https://auth0.com/docs/customize/integrations/integrate-with-netlify

Documentation for integrating Auth0 into Netlify

## Overview

Connect a new or existing Auth0 instance to your Netlify project to enhance your app's security, scalability, and customization using the Auth0 Integration. This integration allows you to implement a streamlined customer identity approach directly in your application.

Use the new integration to build and customize the identity flow for your Netlify project. To get your app up and running quickly and securely, this integration:

* Sets up a production environment in Netlify that integrates with your Auth0 tenant in just a few clicks.
* Automatically creates an Application in your Auth0 tenant that connects with your Netlify project.
* Pre-loads your Auth0 credentials into Netlify, allowing you to skip some of the manual steps in this process.

## Prerequisites

To begin integrating Auth0 into your Netlify project, there are a few requirements that you'll need to set up before getting started:

* A Netlify account with a project that you would like to integrate with. Visit [Create your Netlify account](https://www.netlify.com/) to create an account.
* A web application that requires authentication, such as a React, Vue, or static site with serverless functions.

## Add a Netlify integration

After creating your Netlify account and logging in to your dashboard, you can begin the process of adding an integration. To add the Auth0 integration to an existing Netlify project:

1. From the Netlify dashboard, navigate to **Extensions > Directory.**
2. Search for [**Auth0**](https://app.netlify.com/extensions/auth0)and select **Install.**
3. Select **Install** to proceed with the installation to your Auth0 integration portal.

<Frame>
  <img alt="" />
</Frame>

## Connect your site

To connect your site to Auth0:

1. Navigate to the **Site Configuration** for the site you want to connect to Auth0.
2. In the sidebar, select **Auth0** under **Access & security.**
3. Select **Link an Auth0 tenant** and follow the prompts to connect to your Auth0 account. If you don't already have an Auth0 account, you can sign up at [https://auth0.com/signup](https://auth0.com/signup).

   <Frame>
     <img alt="" />
   </Frame>
4. Select your tenant from the dropdown list, and select **Accept** to authorize your account.

   <Frame>
     <img alt="" />
   </Frame>
5. After you have linked your tenant, select **Add tenant**.
6. Fill out the required information for your tenant and application, enable the **Redeploy site** checkbox and select **Create site tenant**.

   <Frame>
     <img alt="" />
   </Frame>
7. You should now see the successfully linked site tenant in your site configuration.

   <Frame>
     <img alt="" />
   </Frame>

<Callout icon="file-lines">
  You should now see your client application and API in your Auth0 dashboard under **Applications**.
</Callout>

## Set up the integration

When integrating Auth0 with your Netlify project, you'll need to provide your application with authentication settings such as the **<Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>** and **Auth0 domain**.

If your application is reading these settings from environment variables, they are injected automatically by extension.

1. Go to your Netlify dashboard.
2. Navigate to **Site configuration > Environment variables.**
3. Click **Add a variable**, and enter:

   * `AUTH0_CLIENT_ID` (your Auth0 Client ID)
   * `AUTH0_DOMAIN` (your Auth0 domain)

     <Callout icon="file-lines">
       These variables, along with all other application information, can be found in your Auth0 dashboard under **Applications > \[Your app] > Settings**.
     </Callout>

You should now have the proper Auth0 credentials set up for deployment.

### Populate a configuration file

If your application reads Auth0 settings from a file, you can automate this process during the build phase. This ensures your application always has the proper authorization without manually modifying files.

To do this:

1. Go to your Netlify dashboard.

2. Navigate to **Site configuration > Build & deploy > Build settings**.

3. Modify the **Build command** to include a shell script before starting the build:

   ```bash wrap lines theme={null}
   echo "{\"clientId\": \"${AUTH0_CLIENT_ID}\", \"domain\": \"${AUTH0_DOMAIN}\"}" > auth_config.json && npm run build
   ```

This script creates a JSON file named `auth_config.json`, and populates it with the environment variables `AUTH0_CLIENT_ID` and `AUTH0_DOMAIN` set above, ensuring the application has correct Auth0 settings at runtime.

## Manage integration

After adding the Auth0 integration to your Netlify project, the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> creates a new Application to manage and customize your CIAM workflow.

1. Navigate to the Auth0 Dashboard.
2. Select **Applications > Applications > \[Your Netlify application]**
3. Confirm the Netlify application URI under **Settings > Application URIs**.

You can now customize and modify this application similar to any other application in your Auth0 Dashboard.


# Integrate with Vercel
Source: https://auth0.com/docs/customize/integrations/integrate-with-vercel

Integrating Auth0 into your Vercel application

## Overview

Connect a new or existing Auth0 instance to your Vercel project to enhance your app's security, scalability, and customization using the [Auth0 Integration](https://vercel.com/integrations/auth0). This integration allows you to implement a streamlined customer identity approach directly in your application.

Use the new integration to build and customize the identity flow for your Vercel project. To get your app up and running quickly and securely, this integration:

* Sets up a production environment in Vercel that integrates with your Auth0 tenant in just a few clicks.
* Automatically creates an Application in your Auth0 tenant that connects with your Vercel project.
* Pre-loads your Auth0 credentials into Vercel, allowing you to skip some of the manual steps in this process.

### Prerequisites

To begin integrating Auth0 into your Vercel project, there are a few requirements that you'll need to set up before getting started:

* A Vercel account with a project that you would like to integrate with. To create a Vercel account if you don't already have one, visit [Create your Vercel account](https://vercel.com/signup) to get started.
* A Next.js application based on the latest [Auth0 Next.js SDK](/docs/quickstart/webapp/nextjs#install-the-auth0-next-js-sdk).

## Add a Vercel integration

To add the Auth0 integration to an existing Vercel project:

1. Navigate to the [Auth0 integration page](https://vercel.com/integrations/auth0).
2. When prompted with the installation window, select the Vercel team and project which you would like to install the Auth0 integration.

   <Callout icon="file-lines">
     We currently only offer integration to one project at a time. Selecting **All projects** will defer the project selection screen until later in the workflow.
   </Callout>
3. Select **Install** to proceed with the installation to your Auth0 integration portal.
4. Verify that you are logged-in with the correct Auth0 account and you are integrating to the correct Tenant dashboard.

   <Callout icon="file-lines">
     Either log into Auth0 **or** verify that you are logged in with the correct Auth0 account and you are integrating to the correct Tenant dashboard.

     * If no Tenant is selected, you’ll be redirected to create a tenant.
     * If you’re creating a new tenant, you’ll go through our standard onboarding.
     * If you’re new to Auth0, this is where you’ll create an Auth0 account.
   </Callout>
5. Select **Accept**.
6. Next, select the Vercel project that you would like to integrate with Auth0 and select **Continue**.
7. Confirm the application selection, and select **Continue**.
8. You have now successfully added the Auth0 integration to your Vercel project. To view installed integrations, navigate to the **Integrations** tab on your project overview page. Auth0 now appears as an installed integration for your project.

## Manage a Vercel Integration

After you have successfully integrated the Auth0 integration to your Vercel project, you can manage the integration from your application dashboard in Vercel.

### Manage from Vercel

To manage the Auth0 application from your Vercel dashboard, select the Auth0 integration from the **Integration** tab of your project.

<Callout icon="file-lines">
  The environment variables are only configurable at the production domain.
</Callout>

#### Manage access

To manage the integration access to specific projects in your Vercel application, select **Manage Access.** This provides you with a project-level access restriction for the Auth0 integration.

#### Remove integration

To uninstall the Auth0 integration, select **Remove integration** and the application and all associated settings will be removed from your <Tooltip href="/docs/glossary?term=Auth0+dashboard">Auth0 dashboard</Tooltip>. Note that this is not reversible, and if removed you must reinstall the application.

### Manage from the Auth0 Dashboard

After adding the Auth0 integration to your Vercel project, the [Auth0 dashboard](https://manage.auth0.com/) creates a new Application to manage and customize your CIAM workflow.

1. Navigate to the [Auth0 dashboard](https://manage.auth0.com/).
2. Select **Applications > Applications > \[Your Vercel application]**
3. Confirm the Vercel application URI under **Settings > Application URIs.**

   <Frame>
     <img alt="" />
   </Frame>
4. You can now customize and modify this application similar to any other application in your Auth0 dashboard.


# Export User Data to Marketing Tools
Source: https://auth0.com/docs/customize/integrations/marketing-tool-integrations

Learn how to export Auth0 user data to marketing applications and services.

You can provide user data for your marketing tools to personalize marketing
and increase user engagement.

* [Adobe Campaign](/docs/customize/integrations/marketing-tool-integrations/adobe-campaign)
* [Alterian](/docs/customize/integrations/marketing-tool-integrations/alterian)
* [Constant Contact](/docs/customize/integrations/marketing-tool-integrations/constant-contact)
* [Oracle Eloqua](/docs/customize/integrations/marketing-tool-integrations/eloqua)
* [MailChimp](/docs/customize/integrations/marketing-tool-integrations/mailchimp)
* [Marketo](/docs/customize/integrations/marketing-tool-integrations/marketo)
* [Sailthru](/docs/customize/integrations/marketing-tool-integrations/sailthru)
* [Salesforce](/docs/customize/integrations/marketing-tool-integrations/export-user-data-salesforce)
* [Salesforce Marketing Cloud](/docs/customize/integrations/marketing-tool-integrations/salesforce-marketing-cloud)
* [Watson Campaign Automation](/docs/customize/integrations/marketing-tool-integrations/watson-campaign-automation)


# Export User Data to Adobe Campaign
Source: https://auth0.com/docs/customize/integrations/marketing-tool-integrations/adobe-campaign

Learn how to export your Auth0 user data and import it into Adobe Campaign.

In this article, you’ll learn how to export user data in Auth0 to a CSV file then import it into Adobe Campaign with the [Adobe Campaign Import Wizard](https://docs.adobe.com/content/help/en/campaign-classic/using/getting-started/importing-and-exporting-data/importing-data.html).

## Create a user data file

Start by navigating to the [Extensions](https://manage.auth0.com/#/extensions) section of the Dashboard, and opening the **User Import / Export Extension**. On the extension page, select **Export** from the menu.

Next, set the **Export Format** to the required file format. Adobe Campaign accepts file imports in CSV format so choose the `Tab Separated Value file (*.csv)` option.

At the top in the **Fields** section, provide a **User Field** and **Column Name** for each user attribute to include in the export. For example:

<table>
  <thead>
    <tr>
      <th>User Field</th>
      <th>Column Name</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>email</code></td>
      <td>Email Address</td>
    </tr>

    <tr>
      <td><code>created\_at</code></td>
      <td>Created At</td>
    </tr>

    <tr>
      <td><code>given\_name</code></td>
      <td>First Name</td>
    </tr>

    <tr>
      <td><code>family\_name</code></td>
      <td>Last Name</td>
    </tr>
  </tbody>
</table>

After adding the user fields, click on the **Export Users** button to start the export. Once the export is complete, download the CSV file to use in the following section.

## Import a user data file

Before you get started, you can find more information by visiting [Adobe Campaign Documentation: Importing Data](https://docs.adobe.com/content/help/en/campaign-classic/using/getting-started/importing-and-exporting-data/importing-data.html).

Log in to your Adobe Campaign client dashboard and navigate to **Profiles and Targets > Jobs**. Create a new import job by clicking the **Create** button and selecting **New Import**.

A new **Import Wizard** window should open. On the **Template Selection** step you can set your import parameters.

Once you've configured your import parameters, click the **Next** button to continue.

On the **File to Import** step upload the user data CSV file you exported from Auth0 in the previous section. Click the **Next** button to proceed to **Field Mapping**.

Next, map the export file schema to your Adobe Campaign database schema. Check that the field names and field types are correct, then click the **Next** button.

Complete the remaining configuration steps by defining your data reconciliation mode and selecting a folder, list, or service for the users being imported.

Finally, begin the import by clicking the **Start** button on the **Data Import Execution** window.

That's it! You successfully imported your Auth0 users into Adobe Campaign.


# Export User Data to Alterian
Source: https://auth0.com/docs/customize/integrations/marketing-tool-integrations/alterian

Learn how to export your Auth0 user data and import it into Alterian.

In this article, you’ll learn how to export user data in Auth0 to a CSV file then import it into Alterian with the campaign manager's data import tool.

## Create a user data file

Start by navigating to the [Extensions](https://manage.auth0.com/#/extensions) section of the Dashboard and open the **User Import / Export Extension**. On the extension page, select **Export** from the menu.

Next, set the **Export Format** to the required file format. Alterian accepts file imports in CSV format so choose the `Tab Separated Value file (*.csv)` option.

At the top in the **Fields** section, provide a **User Field** and **Column Name** for each user attribute to include in the export. For example:

<table>
  <thead>
    <tr>
      <th>User Field</th>
      <th>Column Name</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>email</code></td>
      <td>Email Address</td>
    </tr>

    <tr>
      <td><code>created\_at</code></td>
      <td>Created At</td>
    </tr>

    <tr>
      <td><code>given\_name</code></td>
      <td>First Name</td>
    </tr>

    <tr>
      <td><code>family\_name</code></td>
      <td>Last Name</td>
    </tr>
  </tbody>
</table>

After adding the user fields, click on the **Export Users** button to start the export. Once the export is complete, download the CSV file to use in the following section.

## Import a user data file

Before you get started, you can find more information by visiting [Alterian Campaign Manager: Data Import](https://cm.help.alterian.com/CM404/Default.htm#Customer_Analytics/Import_Export/Data_Import.htm).

To import your CSV file into Alterian, follow these steps:

1. Open your Alterian Campaign Manager and click **Documents**.
2. Choose the directory to import the file to.
3. Click **Upload Files** and select your CSV file.
4. Click **Upload**.
5. Once the upload is complete, open the **Data Import** tool.
6. Configure your import settings using the provided fields on the **New Imports data** window.
7. After you've reviewed your settings, click **Run Processes**.

That's it! You successfully imported your Auth0 users into Alterian.


# Export User Data to Constant Contact
Source: https://auth0.com/docs/customize/integrations/marketing-tool-integrations/constant-contact

Learn how to export your Auth0 user data and import it into Constant Contact.

In this article, you’ll learn how to export user data in Auth0 to a CSV file then import it into the Constant Contact dashboard.

## Create a user data file

Start by navigating to the [Extensions](https://manage.auth0.com/#/extensions) section of the Dashboard and open the **User Import / Export Extension**. On the extension page, select **Export** from the menu.

Next, set the **Export Format** to the required file format. Constant Contact accepts file imports in CSV format so choose the `Tab Separated Value file (*.csv)` option.

At the top in the **Fields** section, provide a **User Field** and **Column Name** for each user attribute to include in the export. For example:

<table>
  <thead>
    <tr>
      <th>User Field</th>
      <th>Column Name</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>email</code></td>
      <td>Email Address</td>
    </tr>

    <tr>
      <td><code>created\_at</code></td>
      <td>Created At</td>
    </tr>

    <tr>
      <td><code>given\_name</code></td>
      <td>First Name</td>
    </tr>

    <tr>
      <td><code>family\_name</code></td>
      <td>Last Name</td>
    </tr>
  </tbody>
</table>

After adding the user fields, click on the **Export Users** button to start the export. Once the export is complete, download the CSV file to use in the following section.

## Import a user data file

To import your CSV file into Constant Contact, follow these steps:

1. [Log in to Constant Contact](https://login.constantcontact.com) and navigate to **Contacts**.
2. From the **Contacts** page, click **Add Contacts > Upload from file**.
3. Provide you CSV file on the **Upload from file** page then click **Continue**.
4. Review the columns and match them with your Constant Contact fields. Once you're finished click **Continue**.
5. On the **Select lists** page, choose the list or lists to add your contacts to.
6. Click **Upload**.

That's it! You successfully imported your Auth0 users into Constant Contact.


# Export User Data to Oracle Eloqua
Source: https://auth0.com/docs/customize/integrations/marketing-tool-integrations/eloqua

Learn how to export your Auth0 user data and import it into Oracle Eloqua.

In this article, you’ll learn how to export user data in Auth0 to a CSV file then import it into Eloqua with the contact upload wizard.

## Create a user data file

Start by navigating to the [Extensions](https://manage.auth0.com/#/extensions) section of the Dashboard and open the **User Import / Export Extension**. On the extension page, select **Export** from the menu.

Next, set the **Export Format** to the required file format. Eloqua accepts file imports in CSV format so choose the `Tab Separated Value file (*.csv)` option.

At the top in the **Fields** section, provide a **User Field** and **Column Name** for each user attribute to include in the export. For example:

<table>
  <thead>
    <tr>
      <th>User Field</th>
      <th>Column Name</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>email</code></td>
      <td>Email Address</td>
    </tr>

    <tr>
      <td><code>created\_at</code></td>
      <td>Created At</td>
    </tr>

    <tr>
      <td><code>given\_name</code></td>
      <td>First Name</td>
    </tr>

    <tr>
      <td><code>family\_name</code></td>
      <td>Last Name</td>
    </tr>
  </tbody>
</table>

After adding the user fields, click on the **Export Users** button to start the export. Once the export is complete, download the CSV file to use in the following section.

## Import a user data file

Before you get started, you can find more information by visiting [Oracle Eloqua Help Center: Uploading Contacts](https://docs.oracle.com/en/cloud/saas/marketing/eloqua-user/Help/Contacts/Tasks/UploadingContacts.htm).

To import your CSV file into Eloqua, follow these steps:

1. Log in to Eloqua and navigate to **Audience > Contacts > Upload** to open the **Contact Upload Wizard**.
2. Configure the import using the provided fields on the **Pick Data Source** tab.
3. Click the **Cloud** button and select the file to upload.
4. After you've verified the file contents on the **Review** tab, click **Next Step**.
5. Under the **Map Fields** tab, enter the field mapping settings to match your CSV file data to contact fields. Click **Next Step** to continue.
6. Complete the final step of the wizard and click **Finish**.

That's it! You successfully imported your Auth0 users into Eloqua.


# Export User Data to Salesforce
Source: https://auth0.com/docs/customize/integrations/marketing-tool-integrations/export-user-data-salesforce

Learn how to export your Auth0 user data and import it into Salesforce.

In this article, you’ll learn how to export user data in Auth0 to a CSV file then import it into Salesforce using the Data Import Wizard. To review system requirements, visit the Salesforce article [Data Import Wizard](https://help.salesforce.com/articleView?id=data_import_wizard.htm).

## Create a user data file

Start by navigating to the [Extensions](https://manage.auth0.com/#/extensions) section of the Dashboard and open the **User Import / Export Extension**. On the extension page, select **Export** from the menu.

Next, set the **Export Format** to the required file format. Salesforce accepts file imports in CSV format so choose the `Tab Separated Value file (*.csv)` option.

At the top in the **Fields** section, provide a **User Field** and **Column Name** for each user attribute to include in the export. For example:

<table>
  <thead>
    <tr>
      <th>User Field</th>
      <th>Column Name</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>email</code></td>
      <td>Email Address</td>
    </tr>

    <tr>
      <td><code>created\_at</code></td>
      <td>Created At</td>
    </tr>

    <tr>
      <td><code>given\_name</code></td>
      <td>First Name</td>
    </tr>

    <tr>
      <td><code>family\_name</code></td>
      <td>Last Name</td>
    </tr>
  </tbody>
</table>

After adding the user fields, click on the **Export Users** button to start the export. Once the export is complete, download the CSV file to use in the following section.

## Import a user data file

Different account types may require addition steps for successful import. Take a moment to review the Salesforce article [Prepare Your Data for Import](https://help.salesforce.com/articleView?id=import_prepare.htm). For additional instructions, visit [Salesforce: Import Data with the Data Import Wizard](https://help.salesforce.com/articleView?id=import_with_data_import_wizard.htm).

Before you begin, make sure your Salesforce account has the required [user permissions](https://help.salesforce.com/articleView?id=faq_import_general_permissions.htm) to import records.

To import your CSV file into Salesforce, follow these steps:

1. Login to [Salesforce](https://login.salesforce.com/).
2. Navigate to **Setup** and open the **Data Import Wizard**.
3. Click **Launch Wizard**.
4. Configure the import and select your CSV file to upload using the fields provided.
5. Click **Next**.
6. On the **Edit Field Mapping** page, map your CSV file's data fields to Salesforce data fields. Click **Next** to proceed.
7. After you've verified the information on the **Review** page, click **Start Import**.
8. Check out the **Recent Import Jobs** tab on the **Data Import Wizard** home page for updates on the status of your import.

That's it! You successfully imported your Auth0 users into Salesforce.


# Export User Data to MailChimp
Source: https://auth0.com/docs/customize/integrations/marketing-tool-integrations/mailchimp

Learn how to export your Auth0 user data and import it into MailChimp.

In this article, you’ll learn how to export user data in Auth0 to a CSV file then import it into the [MailChimp dashboard](https://login.mailchimp.com/).

## Create a user data file

Start by navigating to the [Extensions](https://manage.auth0.com/#/extensions) section of the Dashboard and open the **User Import / Export Extension**. On the extension page, select **Export** from the menu.

Next, set the **Export Format** to the required file format. MailChimp accepts file imports in CSV format so choose the `Tab Separated Value file (*.csv)` option.

To learn more, review [MailChimp Knowledge Base: Format Guidelines for Your Import File](https://kb.mailchimp.com/lists/growth/format-guidelines-for-your-import-file).

At the top in the **Fields** section, provide a **User Field** and **Column Name** for each user attribute to include in the export. For MailChimp, an email field with the column name `Email Address` is required, so make sure to include it. For example:

<table>
  <thead>
    <tr>
      <th>User Field</th>
      <th>Column Name</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>email</code></td>
      <td>Email Address</td>
    </tr>

    <tr>
      <td><code>created\_at</code></td>
      <td>Created At</td>
    </tr>

    <tr>
      <td><code>given\_name</code></td>
      <td>First Name</td>
    </tr>

    <tr>
      <td><code>family\_name</code></td>
      <td>Last Name</td>
    </tr>
  </tbody>
</table>

After adding the user fields, click on the **Export Users** button to start the export. Once the export is complete, download the CSV file to use in the following section.

## Import a user data file

Before you get started, you can find more information by visiting [MailChimp Knowledge Base: Import Subscribers to a List](https://kb.mailchimp.com/lists/growth/import-subscribers-to-a-list).

Log in to your MailChimp account and go to the **Lists** page. Select a list to import your Auth0 users into ([or create a new list](https://kb.mailchimp.com/lists/growth/create-a-new-list)).

1. On your MailChimp List page, click on **Import Contacts** from the **Add Contacts** menu.
2. Select the `CSV or tab-delimited text file` option to import contacts from.
3. Upload the user data CSV file you exported from Auth0 in the previous section. MailChimp will interpret your user data on the following page.
4. Check that the column names and field types are correct.
5. Click the **Next** button.
6. Review your selections and set the import category.
7. Click the **Import** button to start the user import.

That's it! You successfully imported your Auth0 users into MailChimp.


# Export User Data to Marketo
Source: https://auth0.com/docs/customize/integrations/marketing-tool-integrations/marketo

Learn how to export your Auth0 user data and import it into Marketo.

In this article, you’ll learn how to export user data in Auth0 to a CSV file then import it into Marketo using the [Bulk Leads endpoint](https://developer.adobe.com/marketo-apis/api/mapi/#tag/Bulk-Import-Leads) of the Marketo REST API.

## Create a user data file

Start by navigating to the [Extensions](https://manage.auth0.com/#/extensions) section of the Dashboard and open the **User Import / Export Extension**. On the extension page, select **Export** from the menu.

Next, set the **Export Format** to the required file format. Marketo accepts file imports in CSV format so choose the `Tab Separated Value file (*.csv)` option.

At the top in the **Fields** section, provide a **User Field** and **Column Name** for each user attribute to include in the export. For example:

<table>
  <thead>
    <tr>
      <th>User Field</th>
      <th>Column Name</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>email</code></td>
      <td>Email Address</td>
    </tr>

    <tr>
      <td><code>created\_at</code></td>
      <td>Created At</td>
    </tr>

    <tr>
      <td><code>given\_name</code></td>
      <td>First Name</td>
    </tr>

    <tr>
      <td><code>family\_name</code></td>
      <td>Last Name</td>
    </tr>
  </tbody>
</table>

After adding the user fields, click on the **Export Users** button to start the export. Once the export is complete, download the CSV file to use in the following section.

### Import a user data file

Before you get started, you can find more information by visiting [Marketo Documentation: Bulk Lead Import](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-import/bulk-lead-import).

To import the user data file to Marketo, perform a POST request to the [Bulk Leads endpoint](https://developer.adobe.com/marketo-apis/api/mapi/#operation/importLeadUsingPOST). Set the content-type header of the request to `multipart/form-data` and include a `file` parameter with your exported CSV file as well as format parameter set to `csv`. For example:

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request POST \
    --url https://marketo_rest_api_base_url/bulk/v1/leads.json \
    --header 'authorization: Bearer {MARKETO_ACCESS_TOKEN}' \
    --form file=@auth0_users.csv \
    --form format=csv
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://marketo_rest_api_base_url/bulk/v1/leads.json");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer {MARKETO_ACCESS_TOKEN}");
  request.AddHeader("content-type", "multipart/form-data; boundary=---011000010111000001101001");
  request.AddParameter("multipart/form-data; boundary=---011000010111000001101001", "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"auth0_users.csv\"\r\nContent-Type: text/csv\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"format\"\r\nContent-Type: text/plan\r\n\r\ncsv\r\n-----011000010111000001101001--\r\n", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines expandable theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://marketo_rest_api_base_url/bulk/v1/leads.json"

  	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"auth0_users.csv\"\r\nContent-Type: text/csv\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"format\"\r\nContent-Type: text/plan\r\n\r\ncsv\r\n-----011000010111000001101001--\r\n")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("authorization", "Bearer {MARKETO_ACCESS_TOKEN}")
  	req.Header.Add("content-type", "multipart/form-data; boundary=---011000010111000001101001")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java lines theme={null}
  HttpResponse<String> response = Unirest.post("https://marketo_rest_api_base_url/bulk/v1/leads.json")
    .header("authorization", "Bearer {MARKETO_ACCESS_TOKEN}")
    .header("content-type", "multipart/form-data; boundary=---011000010111000001101001")
    .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"auth0_users.csv\"\r\nContent-Type: text/csv\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"format\"\r\nContent-Type: text/plan\r\n\r\ncsv\r\n-----011000010111000001101001--\r\n")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://marketo_rest_api_base_url/bulk/v1/leads.json',
    headers: {
      authorization: 'Bearer {MARKETO_ACCESS_TOKEN}',
      'content-type': 'multipart/form-data; boundary=---011000010111000001101001'
    },
    data: '-----011000010111000001101001\r\nContent-Disposition: form-data; name="file"; filename="auth0_users.csv"\r\nContent-Type: text/csv\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name="format"\r\nContent-Type: text/plan\r\n\r\ncsv\r\n-----011000010111000001101001--\r\n'
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C lines expandable theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {MARKETO_ACCESS_TOKEN}",
                             @"content-type": @"multipart/form-data; boundary=---011000010111000001101001" };
  NSArray *parameters = @[ @{ @"name": @"file", @"fileName": @"auth0_users.csv", @"contentType": @"text/csv" },
                           @{ @"name": @"format", @"value": @"csv", @"contentType": @"text/plan" } ];
  NSString *boundary = @"---011000010111000001101001";

  NSError *error;
  NSMutableString *body = [NSMutableString string];
  for (NSDictionary *param in parameters) {
      [body appendFormat:@"--%@\r\n", boundary];
      if (param[@"fileName"]) {
          [body appendFormat:@"Content-Disposition:form-data; name=\"%@\"; filename=\"%@\"\r\n", param[@"name"], param[@"fileName"]];
          [body appendFormat:@"Content-Type: %@\r\n\r\n", param[@"contentType"]];
          [body appendFormat:@"%@", [NSString stringWithContentsOfFile:param[@"fileName"] encoding:NSUTF8StringEncoding error:&error]];
          if (error) {
              NSLog(@"%@", error);
          }
      } else {
          [body appendFormat:@"Content-Disposition:form-data; name=\"%@\"\r\n\r\n", param[@"name"]];
          [body appendFormat:@"%@", param[@"value"]];
      }
  }
  [body appendFormat:@"\r\n--%@--\r\n", boundary];
  NSData *postData = [body dataUsingEncoding:NSUTF8StringEncoding];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://marketo_rest_api_base_url/bulk/v1/leads.json"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP lines expandable theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://marketo_rest_api_base_url/bulk/v1/leads.json",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"auth0_users.csv\"\r\nContent-Type: text/csv\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"format\"\r\nContent-Type: text/plan\r\n\r\ncsv\r\n-----011000010111000001101001--\r\n",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {MARKETO_ACCESS_TOKEN}",
      "content-type: multipart/form-data; boundary=---011000010111000001101001"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("marketo_rest_api_base_url")

  payload = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"auth0_users.csv\"\r\nContent-Type: text/csv\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"format\"\r\nContent-Type: text/plan\r\n\r\ncsv\r\n-----011000010111000001101001--\r\n"

  headers = {
      'authorization': "Bearer {MARKETO_ACCESS_TOKEN}",
      'content-type': "multipart/form-data; boundary=---011000010111000001101001"
      }

  conn.request("POST", "/bulk/v1/leads.json", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://marketo_rest_api_base_url/bulk/v1/leads.json")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer {MARKETO_ACCESS_TOKEN}'
  request["content-type"] = 'multipart/form-data; boundary=---011000010111000001101001'
  request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"auth0_users.csv\"\r\nContent-Type: text/csv\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"format\"\r\nContent-Type: text/plan\r\n\r\ncsv\r\n-----011000010111000001101001--\r\n"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift lines expandable theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer {MARKETO_ACCESS_TOKEN}",
    "content-type": "multipart/form-data; boundary=---011000010111000001101001"
  ]
  let parameters = [
    [
      "name": "file",
      "fileName": "auth0_users.csv",
      "contentType": "text/csv"
    ],
    [
      "name": "format",
      "value": "csv",
      "contentType": "text/plan"
    ]
  ]

  let boundary = "---011000010111000001101001"

  var body = ""
  var error: NSError? = nil
  for param in parameters {
    let paramName = param["name"]!
    body += "--\(boundary)\r\n"
    body += "Content-Disposition:form-data; name=\"\(paramName)\""
    if let filename = param["fileName"] {
      let contentType = param["content-type"]!
      let fileContent = String(contentsOfFile: filename, encoding: String.Encoding.utf8)
      if (error != nil) {
        print(error)
      }
      body += "; filename=\"\(filename)\"\r\n"
      body += "Content-Type: \(contentType)\r\n\r\n"
      body += fileContent
    } else if let paramValue = param["value"] {
      body += "\r\n\r\n\(paramValue)"
    }
  }

  let request = NSMutableURLRequest(url: NSURL(string: "https://marketo_rest_api_base_url/bulk/v1/leads.json")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

The response should look something like this:

```json lines theme={null}
{
    "requestId": "e42b#14272d07d78",
    "success": true,
    "result": [{
        "batchId": 1234,
        "status": "Importing"
    }]
}
```

You can check the status of your import using the [Get Import Lead Status API](/docs/) and your import job's `batchId`. For example:

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request GET \
    --url https://marketo_rest_api_base_url/bulk/v1/leads/batch/BATCH_ID.json \
    --header 'authorization: Bearer {MARKETO_ACCESS_TOKEN}'
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://marketo_rest_api_base_url/bulk/v1/leads/batch/BATCH_ID.json");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer {MARKETO_ACCESS_TOKEN}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://marketo_rest_api_base_url/bulk/v1/leads/batch/BATCH_ID.json"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer {MARKETO_ACCESS_TOKEN}")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java lines theme={null}
  HttpResponse<String> response = Unirest.get("https://marketo_rest_api_base_url/bulk/v1/leads/batch/BATCH_ID.json")
    .header("authorization", "Bearer {MARKETO_ACCESS_TOKEN}")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://marketo_rest_api_base_url/bulk/v1/leads/batch/BATCH_ID.json',
    headers: {authorization: 'Bearer {MARKETO_ACCESS_TOKEN}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C lines theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {MARKETO_ACCESS_TOKEN}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://marketo_rest_api_base_url/bulk/v1/leads/batch/BATCH_ID.json"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP lines theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://marketo_rest_api_base_url/bulk/v1/leads/batch/BATCH_ID.json",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {MARKETO_ACCESS_TOKEN}"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("marketo_rest_api_base_url")

  headers = { 'authorization': "Bearer {MARKETO_ACCESS_TOKEN}" }

  conn.request("GET", "/bulk/v1/leads/batch/BATCH_ID.json", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://marketo_rest_api_base_url/bulk/v1/leads/batch/BATCH_ID.json")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer {MARKETO_ACCESS_TOKEN}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift lines theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {MARKETO_ACCESS_TOKEN}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://marketo_rest_api_base_url/bulk/v1/leads/batch/BATCH_ID.json")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

And the response:

```json lines theme={null}
{
    "requestId": "8136#146daebc2ed",
    "success": true,
    "result": [{
        "batchId": 1234,
        "status": "Complete",
        "numOfLeadsProcessed": 123,
        "numOfRowsFailed": 0,
        "numOfRowsWithWarning": 0
    }]
}
```

That's it! You successfully imported your Auth0 users into Marketo.


# Export User Data to Sailthru
Source: https://auth0.com/docs/customize/integrations/marketing-tool-integrations/sailthru

Learn how to export your Auth0 user data and import it into Sailthru.

In this article, you’ll learn how to export user data in Auth0 to a CSV file then import it into the Sailthru dashboard.

## Create a user data file

Start by navigating to the [Extensions](https://manage.auth0.com/#/extensions) section of the Dashboard and open the **User Import / Export Extension**. On the extension page, select **Export** from the menu.

Next, set the **Export Format** to the required file format. Sailthru accepts file imports in CSV format so choose the `Tab Separated Value file (*.csv)` option.

At the top in the **Fields** section, provide a **User Field** and **Column Name** for each user attribute to include in the export. For example:

<table>
  <thead>
    <tr>
      <th>User Field</th>
      <th>Column Name</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>email</code></td>
      <td>Email Address</td>
    </tr>

    <tr>
      <td><code>created\_at</code></td>
      <td>Created At</td>
    </tr>

    <tr>
      <td><code>given\_name</code></td>
      <td>First Name</td>
    </tr>

    <tr>
      <td><code>family\_name</code></td>
      <td>Last Name</td>
    </tr>
  </tbody>
</table>

After adding the user fields, click on the **Export Users** button to start the export. Once the export is complete, download the CSV file to use in the following section.

### Import a user data file

Before you get started, you can find more information by visiting [Sailthru Documentation: Adding Users to Sailthru and Sailthru Lists](https://getstarted.meetmarigold.com/engagebysailthru/Content/audience/managing-users/add-users-lists-st.html?TocPath=Audience%7CManaging%20Users%7C_____3#ListFileUpload).

To import your CSV file into Sailthru, follow these steps:

1. Log in to Sailthru and navigate to [Lists](https://my.sailthru.com/lists).
2. Choose a list, then click **Upload List** and select your CSV file.
3. Select **Add To List** for the **Action**.
4. Set your **Replace Vars** option and enter an email to receive notifications if desired.
5. Review your settings and click **Submit** to upload the file.

That's it! You successfully imported your Auth0 users into Sailthru.


# Export User Data to Salesforce Marketing Cloud
Source: https://auth0.com/docs/customize/integrations/marketing-tool-integrations/salesforce-marketing-cloud

Learn how to export your Auth0 user data and import it into Salesforce Marketing Cloud.

In this article, you’ll learn how to export user data in Auth0 to a CSV file then import it into Salesforce Marketing Cloud using Email Studio.

To read more, review the Salesforce article [Get Started Checklist for Email Studio](https://help.salesforce.com/s/articleView?id=mktg.mc_es_get_started_checklist_for_email_studio.htm\&type=5).

## Create a user data file

Start by navigating to the [Extensions](https://manage.auth0.com/#/extensions) section of the Dashboard and open the **User Import / Export Extension**. On the extension page, select **Export** from the menu.

Next, set the **Export Format** to the required file format. Salesforce Marketing Cloud accepts file imports in CSV format so choose the `Tab Separated Value file (*.csv)` option.

At the top in the **Fields** section, provide a **User Field** and **Column Name** for each user attribute to include in the export. For example:

<table>
  <thead>
    <tr>
      <th>User Field</th>
      <th>Column Name</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>email</code></td>
      <td>Email Address</td>
    </tr>

    <tr>
      <td><code>created\_at</code></td>
      <td>Created At</td>
    </tr>

    <tr>
      <td><code>given\_name</code></td>
      <td>First Name</td>
    </tr>

    <tr>
      <td><code>family\_name</code></td>
      <td>Last Name</td>
    </tr>
  </tbody>
</table>

After adding the user fields, click on the **Export Users** button to start the export. Once the export is complete, download the CSV file to use in the following section.

## Import a user data file

Before you begin, make sure your Salesforce account has the required user permissions to import records. Also, you should take a moment to review the steps in the [Salesforce article on importing subscribers](https://help.salesforce.com/s/articleView?id=mktg.mc_es_import_subscribers_from_file.htm\&type=5) along with [What permissions do I need to import records](https://help.salesforce.com/s/articleView?id=xcloud.faq_import_general_permissions.htm\&type=5).

To import your CSV file into Salesforce Marketing Cloud, follow these steps:

1. Log in to Salesforce Marketing Cloud and open **Email Studio**.
2. Navigate to **Subscribers > Lists**.
3. Choose the list to import to and select the **Import** action.
4. After the import wizard's introduction, select your CSV file as the **Upload Source** and select CSV as the **Data Format**. Enter the remaining settings and click **Next**.
5. In the **Map Attributes** dialog, map your CSV file's data fields to the correct data fields. When you've finished your mappings click **Next**.
6. After you've verified your mappings in the **Confirmed Mappings** dialog, click **Begin** to start the import.

That's it! You successfully imported your Auth0 users into Salesforce Marketing Cloud.


# Export User Data to Watson Campaign Automation
Source: https://auth0.com/docs/customize/integrations/marketing-tool-integrations/watson-campaign-automation

Learn how to export your Auth0 user data and import it into Watson Campaign Automation.

In this article, you’ll learn how to export user data in Auth0 to a CSV file then import it into the Watson Campaign Automation dashboard.

## Create a user data file

Start by navigating to the [Extensions](https://manage.auth0.com/#/extensions) section of the Dashboard and open the **User Import / Export Extension**. On the extension page, select **Export** from the menu.

Next, set the **Export Format** to the required file format. Watson Campaign Automation accepts file imports in CSV format so choose the `Tab Separated Value file (*.csv)` option.

At the top in the **Fields** section, provide a **User Field** and **Column Name** for each user attribute to include in the export. For example:

<table>
  <thead>
    <tr>
      <th>User Field</th>
      <th>Column Name</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>email</code></td>
      <td>Email Address</td>
    </tr>

    <tr>
      <td><code>created\_at</code></td>
      <td>Created At</td>
    </tr>

    <tr>
      <td><code>given\_name</code></td>
      <td>First Name</td>
    </tr>

    <tr>
      <td><code>family\_name</code></td>
      <td>Last Name</td>
    </tr>
  </tbody>
</table>

After adding the user fields, click on the **Export Users** button to start the export. Once the export is complete, download the CSV file to use in the following section.

## Import a user data file

To import your CSV file into Watson Campaign Automation, follow these steps:

1. Log in to Watson Campaign Automation and navigate to **Data > Import New**.
2. On the **Select File** step, enter the new database's settings in the provided fields.
3. Select the option to upload a file from a local hard drive, then click **Browse** to select the file.
4. Set the file type to CSV (comma-separated values).
5. Click **Next** to proceed to the **Define Data Format** step.
6. Make sure your data was processed correctly, then click **Next**.
7. On the **Map Fields** step, choose which fields to include in the import as well as their types.
8. Click **Next** to proceed to the **Edit Field Settings** step.
9. Edit the settings on default or new fields as needed.
10. To start the import click **Next**.

That's it! You successfully imported your Auth0 users into Watson Campaign Automation.


# Marketplace Partners
Source: https://auth0.com/docs/customize/integrations/marketplace-partners

Learn about integrating with Auth0 as part of the Auth0 Marketplace Community. For current and potential Marketplace Partners.

At Auth0, we consider **extensibility** to be one of our essential product capabilities. But while our endless options for integration are an excellent way to customize your own unique solution, it can sometimes be difficult and time-consuming for our customers to figure out how to implement them. Enter the [Auth0 Marketplace](https://marketplace.auth0.com/).

We built the Marketplace as a way to connect our customers with service providers and builders who implement these types of integrations regularly. Listing your integration with Auth0 promotes your company with our customers who are looking to do more with their authentication pipeline.

## Plan your integration

Each integration you build should have a clear and well-explained use case solving a specific customer problem. If multiple customer problems can be solved with integrations between Auth0 and your service, we can list multiple integrations.

Use the pages below to learn more about integrating with Auth0.

#### Defining your Integration Use Case

Our customers need to understand what problem your integration will solve and how it will go about solving it.

[Learn more about integration use cases](/docs/customize/integrations/marketplace-partners/defining-an-integration-use-case)

#### Introduction to Integration

Explore Auth0 extensibility and all the different ways that Auth0 can be customized.

[Learn more about integrating](/docs/customize/integrations/marketplace-partners/introduction-to-integrating-with-auth0)

## Build your integration

Integrations with Auth0 are built on one or more of our extensibility points. [Sign up for a free Auth0 tenant](https://auth0.com/signup), and use our documentation to get your service working with Auth0 and learn how to get listed in our Marketplace.

We have specific guidance for our most common integrations below. Please contact our partner account team using the link at the bottom of this page if you need an example that's not listed here.

#### Actions

Actions Integrations are closed-source, self-contained functions written in JavaScript that execute at specific points in the Auth0 platform.

[Learn how to build an Action Integration](/docs/customize/integrations/marketplace-partners/actions-integrations-for-partners)

#### Social Connections

Social Connection Integrations are OAuth2 sources of identity that provide a profile to Auth0 after a user successfully logs in.

[Learn how to build a Social Connection](/docs/customize/integrations/marketplace-partners/social-connections-for-partners)

#### SSO Integrations

<Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> Integrations use an Auth0 identity to log in, via <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip>, to an external service.

[Learn how to build an SSO Integration](/docs/customize/integrations/marketplace-partners/sso-integrations-for-partners)

#### Log Streaming

Log streaming allows users to monitor Auth0 activity using one of our partner log management service providers, or stream events to webhooks and trigger custom business logic.

[Learn how to build a Log Stream](https://github.com/Auth0-Marketplace/TEMPLATE-log-streaming-guide)

#### Enterprise Connections

Enterprise connections are a way for customers to authenticate users in an external federated <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> using OIDC.

[Learn how to build an Enterprise Connection](https://github.com/Auth0-Marketplace/TEMPLATE-oidc-connection-guide)

## Get listed

If you are ready to become a partner and submit your integration, please create a partner account at the [partner portal](https://partners.marketplace.auth0.com/) and do the following:

1. Complete the partner profile which includes a short description about your business, legal and marketing content, company logo, terms of service, privacy policy, contact info, and support email.
2. Submit your integration which includes integration code, installation guide and details such as name and description. Optionally, you can add 3 value propositions to your integration.

See the integration types above for more information about the code, configuration, and documentation that should be included with each integration.

## Additional resources

* [The Auth0 Marketplace](https://marketplace.auth0.com/)
* [Introducing the Auth0 Marketplace](https://auth0.com/blog/introducing-auth0-marketplace/)
* [Become an Auth0 Partner](https://auth0.com/partners)


# Actions Integrations for Partners
Source: https://auth0.com/docs/customize/integrations/marketplace-partners/actions-integrations-for-partners

Instructions for Auth0 business partners to create zero-code solutions that tie third-party products into Auth0 workflows

Partners like you use Actions Integrations to build zero-code solutions that tie their products into Auth0 workflows. Actions Integrations let Auth0 customers implement solutions like identity verification or consent management without writing any code. You write the Actions Integration; customers drag and drop it into their workflow.

Actions Integrations are self-contained functions that execute at chosen points in the Auth0 platform. Written in JavaScript, they are closed source; customers can’t modify the code.

## Create and publish an Actions Integration

Creating an Actions Integration involves planning, building, and testing. Before you make it available to customers in the [Auth0 Marketplace](https://marketplace.auth0.com/), Auth0 reviews the Actions Integration. For information about the Auth0 Marketplace, read [Marketplace Partners](/docs/customize/integrations/marketplace-partners).

### Step 1. Determine your use case

Identify what use case your Actions Integration will address. What problem will it solve for customers? How will it solve the problem? For more information, read [Defining an Integration Use Case](/docs/customize/integrations/marketplace-partners/defining-an-integration-use-case).

### Step 2. Choose a flow

Action Integrations consist of a single [Action](/docs/customize/actions). What an Action can do is determined by where it is executed within the Auth0 runtime environment, its Action  [flow](/docs/customize/actions/explore-triggers). Available Action flows are:

* **Login flow** runs synchronously after a user successfully signs up or logs in. Login events include interactive flows (like username/password or federated login) and non-interactive flows (like session checks and <Tooltip href="/docs/glossary?term=refresh+token">refresh token</Tooltip> exchanges). To learn more about this flow, read [Login Flow](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger).
* **Machine to Machine flow** runs synchronously when an application requests an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> using the client credentials grant. To learn more about this flow, read [Machine to Machine Flow](/docs/customize/actions/explore-triggers/machine-to-machine-trigger).
* **Pre User Registration flow** runs synchronously before Auth0 adds a user to a database or <Tooltip href="/docs/glossary?term=passwordless">passwordless</Tooltip> connection. This flow does not run for federated logins like enterprise or social connections. To learn more about this flow, read [Pre User Registration Flow](/docs/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger).
* **Post User Registration flow** runs asynchronously after Auth0 adds a user to a database or passwordless connection. This flow does not run for federated logins like enterprise or social connections. To learn more about this flow, read [Post User Registration Flow](/docs/customize/actions/explore-triggers/signup-and-login-triggers/post-user-registration-trigger).
* **Post Change Password flow** runs asynchronously after the customer changes a password for a database connection user. This flow does not run for password changes on other types of connections. To learn more about this flow, read [Post Change Password Flow](/docs/customize/actions/explore-triggers/password-reset-triggers/post-change-password-trigger).
* **Send Phone Message** **flow** delivers a phone or SMS message as part of a custom <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> provider. To learn about custom MFA providers, read [Customize Multi-factor Authentication SMS and Voice Messages](/docs/customize/customize-sms-or-voice-messages). To learn more about this flow, read [Send Phone Message Flow](/docs/customize/actions/explore-triggers/mfa-notifications-trigger).

To learn more about Action flows, read [Explore Flows and Triggers](/docs/customize/actions/explore-triggers). If you need to redirect users to an endpoint during login, read [Redirect Actions for Partners](/docs/customize/integrations/marketplace-partners/redirect-actions-for-partners).

## Step 3. Build an Actions Integration

Once you’ve decided which flow fits your Action Integration's use case, build your Action in a testing tenant. For instructions, read [Write Your First Action](/docs/customize/actions/write-your-first-action). This Action will be the basis for your Action Integration code.

In addition, to assist you in building your integration you can leverage our Action integration templates:

* [Post Login Action Integration Template](https://github.com/auth0-marketplace/TEMPLATE-action-post-login)
* [Machine-to-Machine Action Integration Template](https://github.com/auth0-marketplace/TEMPLATE-action-client-credentials)
* [Pre User Registration Action Integration Template](https://github.com/auth0-marketplace/TEMPLATE-action-pre-user-registration)
* [Post User Registration Action Integration Template](https://github.com/auth0-marketplace/TEMPLATE-action-post-user-registration)
* [Post Change Password Action Integration Template](https://github.com/auth0-marketplace/TEMPLATE-action-post-password-change)
* [Send Phone Message Action Integration Template](https://github.com/auth0-marketplace/TEMPLATE-action-phone-message)

To learn how to make your Actions Integration secure and stable, read [Actions Coding Guidelines](/docs/customize/actions/action-coding-guidelines). Also follow these guidelines specific to Actions Integrations:

* When building your Action in a test tenant, use secrets for all values that a customer needs to provide (such as identifiers, tenant names, and thresholds). When you submit your Actions Integration, Auth0 asks which fields must be encrypted at rest (remain secrets) and which can be editable text fields.
* Use a debug/test mode configuration flag for logging that helps with setup or troubleshooting. Actions Integrations should rarely output logs for all executions.
* Write secret names in `ALL_CAPS_SNAKE_CASE` to ease review.
* Action Integrations are closed source; customers can neither see nor modify the code. Any customer-specific input required to control the Action Integration must come from secrets or configuration.

### Step 4. Test your Actions Integrations

Because Auth0 reviewers don't have access to your service, you must test your Action before submitting it for review. Manually test both successful executions and edge cases. Include these checks:

* Does the Action fail silently or block further execution?
* How does the Action work if an HTTP request fails?
* What, if any, error messages are exposed to users?
* What information is logged?
* Can the Action be bypassed or spoofed?

During the submission process, Auth0 asks for unit test coverage for the success path. Auth0 provides all the tooling and examples needed to make this as simple as possible.

### Step 5. Submit your Actions Integration

Once you have written and thoroughly tested your Actions Integration, submit it to Auth0 for review: submit an [Auth0 Marketplace service request](https://autheco.atlassian.net/servicedesk/customer/portal/1/group/1/create/43). After a successful initial review, the integration is reviewed for security compliance.

### Step 6. Publish your Actions Integration

Once Auth0 completes the reviews of your Actions Integration, we will notify you if the integration has passed the reviews and publication timelines.


# Defining an Integration Use Case
Source: https://auth0.com/docs/customize/integrations/marketplace-partners/defining-an-integration-use-case

Describes methodology to plan an Auth0 integration

One of the most important parts of integrating with Auth0 is defining what the integration will do and how it will do it. Customers need to understand what problem your integration will solve and how it will go about solving it. This is probably an easy question to answer about your service on its own but, in the context of an identity platform like Auth0, it can be more nuanced.

This guide will help you understand the integration environment a little better and guide you to designing a great integration with Auth0.

#### Review: What does Auth0 do?

Here at Auth0 we ...

* Enable easy and secure access to any application.
* Provide an authentication and authorization service built on open standards like OIDC, OAuth2, <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip>, and others.
* Build an identity platform that exposes the appropriate building blocks targeted to different operators in the ecosystem.
* Handle our customers' outsourced application security, user centralization, and user management by connecting networks of applications to a single source of identity.

#### What does your service do?

It's helpful for us to understand what your service is capable of doing and what use cases your customers rely on you to handle. A few questions that can help with framing your answer:

* Are you a source of user identity?
* Do you provide data or analytics?
* Does your service expose a user interface of any kind?
* Do you increase security? Observability?

#### Do you target specific industries or customer types?

Auth0 customers span throughout industries like software/tech, financial services, media, to travel and hospitality. we can handle application networks of all types but our main focus is [Customer Identity and Access Management or CIAM](https://auth0.com/blog/what-is-ciam/). More specifically, we focus on B2C and B2B use cases where the goal is to help our customers generate revenue (B2B) and convert more customers (B2C) while making sure we protect our customers at all cost. We work with companies to create integrations that solve CIAM for any use case.

Companies that are a good fit with Auth0:

* Are striving to change the perception that identity is hard
* Focus on growing their B2B customers
* Aim to increase revenue for their B2C customers
* Don't compromise on security

Does your service do any of the following?

* Focus on government, medical, eCommerce, or other specific applications?
* Typically get used at a certain scale or traffic level?
* Get installed on premise?

#### What problem(s) does your service solve for your customers?

In a general sense, it's important to know why, exactly, our mutual customers would use your service. Focusing on the problems that your service solves can help us find common ground and understand why an integration would be valuable.

Some examples are:

* Low conversation rates caused by interruptive security measures like <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip>
* Spam sign ups and content submission
* Too much or unhelpful log data

#### How does your service solve those problems in the context of an identity platform?

This is where we start connecting what your service does to the platform we maintain. We handle many different forms of authentication and authorization, all of which flow through a central context. The question here is asking what parts of our service might cause or exacerbate the problem(s) listed above.

A few ideas:

* Centralized login creates lots and lots of log data that is impossible to monitor manually
* A central user store makes augmenting a user profile beneficial for all applications in the network
* Identity verification is easier to provision in one place rather than individually for specific applications

#### Can you provide a visual representation of how this integration will work?

System and/or sequence diagrams are helpful to explain how your integration is working to our partner technical team as well as our customers.

#### Are there any limitations to this integration?

Our identity platform enables logging in using a browser, mobile device, CLI, cloud functions, and more. We also gate some features by the type of plan that a customer is on.

Does your service have:

* Technology limitations of any kind, including OS, language, platform, or devices?
* Rate limits or payment gateways?
* Asynchronous processing requirements?
* Auth0 plan level limitations? See [our pricing page](https://auth0.com/pricing) for information on specific features.

#### What's next?

Now that you have a sense of how your service can work with Auth0, you are ready to learn more about [Integrating with Auth0](/docs/customize/integrations/marketplace-partners/introduction-to-integrating-with-auth0).


# Introduction to Integrating with Auth0
Source: https://auth0.com/docs/customize/integrations/marketplace-partners/introduction-to-integrating-with-auth0

Describes available integrations for Auth0's partners

Auth0provides an authentication and authorization service built on open standards like OIDC, OAuth2, <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip>, and others. But, more than that, we provide tools so our customers can outsource user centralization and management, components of application security, and connecting networks of applications to a single source of identity.

An important part of this is enabling partners, such as yourself, to create an ecosystem of integrations that can be used to enhance and extend what we already provide. We do this by providing extensibility points and methods to allow customization. This means more functionality for customers with less maintenance burden for them.

Almost 90% of our customers extend the Auth0 platform for their unique requirements. By working with you to solve for common identity problems and use cases, we can expedite the time it takes our customers to implement their identity workflows.

## What can be extended?

Below is a list of the different ways Auth0 can be customized. Some extensibility points allow integrations to be installed directly, while others need a guide that a customer can follow, and some extensibility points require a paid Auth0 account.

* **Single-Sign On to an external service**

  * [SAML](/docs/customize/integrations/marketplace-partners/sso-integrations-for-partners)
  * OpenID Connect
  * WS-Fed
* [**Customize user-facing Auth0 UI**](/docs/customize)

  * Load custom JavaScript and CSS on the login form
  * Custom email templates
* **Sources of identity**

  * [OpenID Connect](/docs/authenticate/identity-providers/enterprise-identity-providers/oidc)
  * [OAuth2](/docs/customize/integrations/marketplace-partners/social-connections-for-partners)
  * [SAML](/docs/authenticate/identity-providers/enterprise-identity-providers/saml)
  * [Active Directory/LDAP](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap)
  * [Custom code pointing to a remote identity source](/docs/authenticate/database-connections/custom-db)
* [**Custom code after successful authentication**](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger)

  * Call an external API to enrich the user profile, block logins, etc.
  * [Redirect to an external service](/docs/customize/integrations/marketplace-partners/redirect-actions-for-partners)
  * Enrich the user profile stored in Auth0
  * Provide a second factor for authentication
  * [Step-up authentication](/docs/secure/multi-factor-authentication/step-up-authentication)
  * Trigger Auth0 MFA
* **Custom code** [**before**](/docs/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger) **and** [**after**](/docs/customize/actions/explore-triggers/signup-and-login-triggers/post-user-registration-trigger) **Auth0 database registration**

  * Database Connections
  * Passwordless Connections
* [**Send MFA codes using a custom SMS provider**](/docs/customize/actions/explore-triggers/mfa-notifications-trigger)
* **Integration with customer applications**

  * Integrate via your own SDK
* **Application calling a resource/API**

  * [Modify access tokens at login](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger)
  * [Modify access tokens for machine-to-machine applications](/docs/customize/actions/explore-triggers/machine-to-machine-trigger)
* [**Log streams**](/docs/customize/log-streams/custom-log-streams)
* [**Email providers via SMTP**](/docs/customize/email/smtp-email-providers)
* **Tenant and user management**

  * [Via API using a machine-to-machine application](/docs/secure/tokens/access-tokens/management-api-access-tokens)

    * [User management](/docs/manage-users/user-accounts/manage-users-using-the-management-api)
    * [Application management](https://auth0.com/docs/api/management/v2#!/Clients/get_clients)
    * [Connection management](https://auth0.com/docs/api/management/v2#!/Connections/get_connections)
  * [Via CLI](/docs/deploy-monitor/deploy-cli-tool)

## Learn more

* [Marketplace Partners](/docs/customize/integrations/marketplace-partners)
* [Redirect Actions for Partners](/docs/customize/integrations/marketplace-partners/redirect-actions-for-partners)
* [Social Connections for Partners](/docs/customize/integrations/marketplace-partners/social-connections-for-partners)
* [SSO Integrations for Partners](/docs/customize/integrations/marketplace-partners/sso-integrations-for-partners)


# Redirect Actions for Partners
Source: https://auth0.com/docs/customize/integrations/marketplace-partners/redirect-actions-for-partners

Learn about redirect Actions and how Auth0 Marketplace partners can use them to customize the login flow.

When a user is logging in or signing up, a Redirect Action lets you redirect them to an external page (such as a consent form) and then then back to Auth0 to complete their login or signup. You can redirect users to access an external application that prompts them to:

* Take an action, like ID proofing
* Provide information, like progressive profiling
* Agree to something, like consent or terms of service

<Frame>
  <img alt="Diagram of Redirect Action on Post Login trigger: The Customer Application redirects the user to Auth0 to log in.  If the login is successful, all Actions in the Post Login trigger execute (this happens before MFA, if it is active). If an Action triggers a redirect, the user is sent to the designated URL along with a state parameter. This URL must be hosted by your service or the customer. The user is redirected or POSTed back to Auth0 at a specific path on their domain, along with the original state value, and the Action runs any code that exists in onContinuePostLogin. The user is sent back to the application with their identity or, if something failed, an error message." />
</Frame>

This process occurs in a Redirect Action:

1. The **Customer Application** redirects the user to Auth0 to log in.
2. If the login is successful, all Actions in the [Post Login trigger](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) execute (this happens before MFA, if it is active).
3. If an Action triggers a redirect, the user is sent to the designated URL along with a state parameter. This URL must be hosted by your service or the customer.
4. The user is redirected or POSTed back to Auth0 at a specific path on their domain, along with the original state value, and the Action runs any code that exists in `onContinuePostLogin`.
5. The user is sent back to the application with their identity or, if something failed, an error message.

Once you’re ready to tie your service into the process, there are important elements to consider:

* How do you determine when to redirect out of Auth0?

  * Flag in the [user’s app\_metadata](/docs/manage-users/user-accounts/metadata/manage-metadata-rules)?
  * Based on a particular metadata field on the Client?
* How do you handle existing user profile data that should be verified? (This data could be user-provided or from a federated identity source, such as Google, Facebook, or Azure AD.)
* What data do you need from Auth0 in your service and how do you get it there securely?
* How do you persist the state value from Auth0 in your service?
* How do you get and persist the `/continue` URL to which you want to POST/redirect?
* What do you send back to Auth0 and how do you accomplish this securely?
* How do you indicate that ID proofing is complete and pass status?
* How do you store necessary information in the [user’s app\_metadata](/docs/manage-users/user-accounts/metadata/manage-metadata-rules) or the [normalized user profile](/docs/manage-users/user-accounts/user-profiles/user-profile-structure)
* Be mindful of [rate limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/management-api-endpoint-rate-limits) and update only when necessary
* How do you send information back to the requesting application using [custom token claims](/docs/get-started/apis/scopes/sample-use-cases-scopes-and-claims)?

To help answer all of these questions and more, read [Redirect with Actions](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/redirect-with-actions). When you're ready to submit your Action Integration, follow steps 4-6 in [Action Integrations for Partners.](/docs/customize/integrations/marketplace-partners/actions-integrations-for-partners)


# Social Connections for Partners
Source: https://auth0.com/docs/customize/integrations/marketplace-partners/social-connections-for-partners

Learn about social connections and how Auth0 Marketplace partners can use, build, and test them.

In Auth0, Connections are a source of user identity for logging in. Social Connection is the term we use for a consumer-level source of identity, like Google or Facebook. Customers can provide their users with the option of using one or more social connections on the login form, or just use a single provider by including a URL parameter when redirecting to the login form.

<Frame>
  <img alt="Social Connections for Partners - Universal Login with Social Connections - Example login page" />
</Frame>

Once a user is logged in, their identity from the social provider is mapped to an Auth0 profile, and the result is sent to the application that requested login. This creates an Auth0 user record using the identity from the selected Social Connection. The attributes used for this record are mapped from the external identity source to an [Auth0 user profile](/docs/manage-users/user-accounts/user-profiles/normalized-user-profiles).

Your Marketplace Social Connection will start as a [Custom Social Connection](/docs/authenticate/identity-providers/social-identity-providers/oauth2) that can be built on any Auth0 tenant, so you can see how the transaction will work and make sure that users can log in with your <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip>. The following video will show you how to build and test a Connection in Auth0.

<iframe />

In addition, to assist you in building your integration you can leverage our [Social Connection Integration template](https://github.com/auth0-marketplace/TEMPLATE-social-connection).

## Submit your Social Connection

If you are ready to become a partner and submit your integration, please create a partner account at the [partner portal](https://partners.marketplace.auth0.com/) and do the following:

1. Complete the partner profile which includes a short description about your business, legal and marketing content, company logo, terms of service, privacy policy, contact info, and support email.
2. Submit your integration which includes integration code, installation guide and details such as name and description. Optionally, you can add 3 value propositions to your integration.

**We will need the following configuration and documentation:**

* The Authorization and Token URLs that should be used; if your authorization server uses a tenant architecture, include the pattern to use, and we will include a **Tenant Domain** field or similar.
* A list of fields that the customer configuring the integration should see, including **<Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>** and **<Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip>**
* A list of scopes that can be requested, including whether to require them and/or request them by default
* A profile mapping script (following the [mapping script template](https://gist.github.com/joshcanhelp/26e1fc3581d2ced737c4f50a694ea10f)). This script must map a unique identifier to `user_id` and, if possible, `email`, `email_verified`, and `name`
* An installation guide written in Markdown.


# SSO Integrations for Partners
Source: https://auth0.com/docs/customize/integrations/marketplace-partners/sso-integrations-for-partners

Learn how to build an SSO Integration as a member of our partner community.

<Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> (single sign-on) integrations use an Auth0 identity to log in, via <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip>, to an external service. This allows customers with internal applications to use SSO to access third-party vendors using the Auth0 identity.

The [SSO integrations available on Marketplace](https://marketplace.auth0.com/features/sso-integrations) define both the standard SAML configuration values needed to connect Auth0 to external vendors, and the fields necessary for additional customer-specific values. In these integrations, Auth0 acts as the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> in a service provider (SP)-initiated scenario. To learn how to configure Auth0 for these integrations, see [Configure Auth0 as a SAML Identity Provider](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider).

The part that our partners will provide is the default SAML configuration to make this transaction work. This will consist of values or customer-requested fields for some or all of the attributes listed in [Customize SAML Assertions: SAML Assertion Attributes](/docs/authenticate/protocols/saml/saml-configuration/customize-saml-assertions).

To build and test an integration, [create a tenant](https://auth0.com/signup) in Auth0 and follow the documentation above to create a working SSO integration with your service.

In addition, to assist you in building your integration you can leverage our [SSO Integration](https://github.com/auth0-marketplace/TEMPLATE-sso).

## Submit your SSO Integration

If you are ready to become a partner and submit your integration, please create a partner account at the [partner portal](https://partners.marketplace.auth0.com/) and do the following:

1. Complete the partner profile which includes a short description about your business, legal and marketing content, company logo, terms of service, privacy policy, contact info, and support email.
2. Submit your integration which includes integration code, installation guide and details such as name and description. Optionally, you can add 3 value propositions to your integration.

**We will need the following configuration and documentation:**

* The JSON used to configure the working SAML add-on Application
* A list of fields that should be shown to the customer configuring the integration (like **Callback URL**, **<Tooltip href="/docs/glossary?term=Audience">Audience</Tooltip>**, and **Signing Certificate**)
* An installation guide written in Markdown.


# Writing Tips for Installation Guides
Source: https://auth0.com/docs/customize/integrations/marketplace-partners/writing-tips-for-installation-guides

Describes writing guidelines for Partners submitting integrations

If you can't consult a full style guide, review these tips to significantly improve your content.

## Use active voice

Avoid passive voice (to be verb + past-tense verb). To make your text more dynamic, clear, and (often) shorter, try to use actors and active voice wherever possible.

<table>
  <thead>
    <tr>
      <th><strong>Preferred</strong></th>
      <th><strong>Discouraged</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Once you add the required configuration, Auth0 will process all logins for your tenant using this Rule. Before you activate the integration in production, make sure you have configured all components correctly and verified on a test tenant.</td>
      <td>Once the required configuration is added, all logins for your tenant will be processed by this Rule. Please make sure all components have been configured correctly and verified on a test tenant before activating the integration in production.</td>
    </tr>
  </tbody>
</table>

## Make link titles scannable

When you link to other resources, make sure the link describes the action or task in the document to which the link is pointing. Generic link text reduces scannability by forcing readers to read all of the text surrounding a link to identify what to select.

<table>
  <thead>
    <tr>
      <th><strong>Preferred</strong></th>
      <th><strong>Discouraged</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>You can use the Auth0 Dashboard or the Management API to <a href="/docs/customize/login-pages/universal-login/customize-templates">customize text for the Universal Login experience</a>.</td>
      <td>Click <a href="/docs/get-started">here</a>.</td>
    </tr>

    <tr>
      <td>To learn how to assign roles to members of organizations, read <a href="/docs/manage-users/organizations/configure-organizations/add-member-roles">Add Roles to Organization Members</a>.</td>
      <td>You can go to <a href="/docs/get-started">this link</a>.</td>
    </tr>
  </tbody>
</table>

## Write device-agnostic directions

Remember that user interfaces display differently on different devices. Also, remember that users may be using adaptive devices to view your content.

<table>
  <thead>
    <tr>
      <th><strong>Preferred</strong></th>
      <th><strong>Discouraged</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Select <strong>Create</strong>.</td>
      <td>Click <strong>Create</strong>.</td>
    </tr>

    <tr>
      <td>Switch to the <strong>Applications</strong> view.</td>
      <td>Switch to the <strong>Applications</strong> tab.</td>
    </tr>

    <tr>
      <td>Locate <strong>Client Secret</strong>.</td>
      <td>Scroll up to <strong>Client Secret</strong>.</td>
    </tr>
  </tbody>
</table>

## Use verbs and noun/adjectives properly

Be careful about words that can be used as both verbs and nouns or adjectives. Verb forms usually require a space between words, while nouns and adjectives can be compounded.

<table>
  <thead>
    <tr>
      <th><strong>Preferred</strong></th>
      <th><strong>Discouraged</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Log in to your account.</td>
      <td>Login to your account.</td>
    </tr>

    <tr>
      <td>Auth0 processes logins.</td>
      <td>Auth0 processes log ins.</td>
    </tr>

    <tr>
      <td>Set up your hardware.</td>
      <td>Setup your hardware.</td>
    </tr>

    <tr>
      <td>Describe your hardware setup.</td>
      <td>Describe your hardware set up.</td>
    </tr>
  </tbody>
</table>

## Use sentence case for headings

Only capitalize the first word and any other proper nouns or Auth0 product names.

<table>
  <thead>
    <tr>
      <th><strong>Preferred</strong></th>
      <th><strong>Discouraged</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Add a dependency</td>
      <td>Add a Dependency</td>
    </tr>

    <tr>
      <td>Validate resumed login</td>
      <td>Validate Resumed Login</td>
    </tr>

    <tr>
      <td>Create an Action</td>
      <td>Create an action</td>
    </tr>
  </tbody>
</table>

## Use simple tense for headings

Avoid unnecessary wordiness by using simple tenses for headings.

<table>
  <thead>
    <tr>
      <th><strong>Preferred</strong></th>
      <th><strong>Discouraged</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Assign and change users</td>
      <td>Assigning and changing users</td>
    </tr>

    <tr>
      <td>Connect a custom database</td>
      <td>How to connect a custom database</td>
    </tr>
  </tbody>
</table>

## Write steps concisely

When writing introductory text for steps, be direct and concise. Remember that users already know what they need to do with a numbered list of steps.

<table>
  <thead>
    <tr>
      <th><strong>Preferred</strong></th>
      <th><strong>Discouraged</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>To install the SDK:</td>
      <td>Follow the steps below:</td>
    </tr>
  </tbody>
</table>

## Set user expectations in steps

Tell users what the outcome of their behavior should be before describing the behavior they need to take.

<table>
  <thead>
    <tr>
      <th><strong>Preferred</strong></th>
      <th><strong>Discouraged</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>To activate this integration, select <strong>Save Changes</strong>.</td>
      <td>Select <strong>Save Changes</strong> to activate this integration.</td>
    </tr>
  </tbody>
</table>

## List actions within steps in order

Within individual steps, tell the user what to do in the order they need to do it.

<table>
  <thead>
    <tr>
      <th><strong>Preferred</strong></th>
      <th><strong>Discouraged</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Locate the <strong>Integrations</strong> section, and select <strong>Add Integration</strong>.</td>
      <td>Select <strong>Add Integration</strong> under the <strong>Integrations</strong> section.</td>
    </tr>
  </tbody>
</table>

## Use notes and warning appropriately

Notes and warnings have different functions. Notes should include general information that would be nice to know, whereas warnings contain information that may cause failure if not followed.

If information warrants being presented as a warning, you should include the warning exactly where the user would need to perform the related action. Users should not have to hunt for warnings.

## Learn more

* [Marketplace Partners](/docs/customize/integrations/marketplace-partners)
* [Redirect Actions for Partners](/docs/customize/integrations/marketplace-partners/redirect-actions-for-partners)
* [Social Connections for Partners](/docs/customize/integrations/marketplace-partners/social-connections-for-partners)
* [SSO Integrations for Partners](/docs/customize/integrations/marketplace-partners/sso-integrations-for-partners)


# Migrate Office365 Connections to Windows Azure AD
Source: https://auth0.com/docs/customize/integrations/migrate-office365-connections-to-windows-azure-ad

Details migrating Office365 connections to Windows Azure AD.

Office365 has been deprecated. You should migrate your Office365 Connections to Windows Azure AD Connections.

Since early days, we supported authenticating users with Office365. Office365 has always used Windows Azure AD behind the scenes, but there wasn't a good UI to create an "application" in Windows Azure AD. That's why you had to create it in the Seller Dashboard. Moving forward Microsoft wants you to use Windows Azure AD and you can now easily create a directory associated with your Office365 account and the application.

## How to migrate to Azure

1. Create a Windows Azure AD subscription (free)
2. Create a Directory (that will be associated with your Office365 account) and an application. To learn more, read [Connect Your App to Microsoft Azure Active Directory](/docs/authenticate/identity-providers/enterprise-identity-providers/azure-active-directory/v2).

If you were using the `user_id` in your application, notice that it will change from `office365|....some-guid....` to `waad|...email....`.


# Office 365 Custom Provisioning
Source: https://auth0.com/docs/customize/integrations/office-365-custom-provisioning

Learn how to set up Microsoft Office 365 custom provisioning.

The default Office 365 setup includes Active Directory and DirSync/Azure AD Sync Services, which synchronize and provision AD users living in your Azure AD for <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip>. In this configuration, Auth0 is the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>, we provide Single Sign-on (SSO) for these users.

But what if you want to allow contractors, partners or even customers to access your Office 365 environment (e.g., SharePoint)? In that case, the default approach is not optimal because these users would need to be created in your AD environment. Instead, you need to custom provision Azure AD users using [Auth0 Rules](/docs/customize/rules).

Custom provisioning allows you to create users in Azure AD (and effectively Office 365) just as they log in from any connection available in Auth0. (In this case, your rule takes over DirSync's task for any type of connection where DirSync would not work.) This configuration allows you to offer a variety of login options (including, Facebook, LinkedIn, Google Workspace) to your Office 365 environment.

## Prerequisites

Before you can configure custom provisioning, you must:

* [Configure Office 365](https://marketplace.auth0.com/integrations/office-365-sso): Register a <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip> and configure Office 365 as a third-party application in Auth0.

## Configure Azure AD

Custom provisioning uses the Azure AD Graph API to provision new users in Azure AD. To access the Azure AD Graph API, you must create an application within the Azure AD Directory that has been linked to the Office 365 subscription:

1. Log in to the [Azure Portal](https://portal.azure.com).
2. Choose [Azure Active Directory in the left navigation](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview).
3. Select **App registrations** in the new menu.
4. Click on **New application registration**.
5. Fill the form:

   1. Input a name for the application (such as `Auth0 Provisioning`)
   2. Select **Web app / API** as the **Application type**.
   3. Insert a sign-on URL. You can enter any valid URL; this won't really be used.
6. The recently-created app will appear in the **App registrations** list. Select it.
7. In the **Settings** blade (Microsoft call these sections "blades"), choose **Keys**.
8. Input a **Description** (like `Auth0 Provision`), and choose a **Duration** for the new key. If you choose to issue a non-permanent key, take note of the expiration date and create a reminder to replace the key with a new one before it expires.
9. Click to save the key, then copy the **App Key**. This key will be shown only once, and it's needed for the Auth0 rule.
10. Choose **Required permissions**, and click **Add** in the new blade.
11. Select the **Microsoft Graph** API, then check `Read and write directory data` under **Application Permissions**.
12. Back in the **Required permissions**, click on the **Grant Permissions** button, and then click **Yes** to grant the requested permissions.

## Create the Azure AD provisioning rule

The following rule shows the provisioning process:

1. If the user comes from the AD connection, skip the provisioning process (because this will be handled by DirSync).
2. If the user was already provisioned in Azure AD, just continue with the login transaction.
3. Use the Azure AD Client ID and Key to get an Access Token for the Graph API.
4. Create a user in Azure AD.
5. Assign a license to the user.
6. Continue with the login transaction.

The username is generated with the `createAzureADUser` function, which by default, generates a username in the format `auth0-c3fb6eec-3afd-4d52-8e0a-d9f357dd19ab@fabrikamcorp.be`. You can change this to whatever you like; just make sure this value is unique for all your users.

Make sure you set the correct values for the `AUTH0_OFFICE365_CLIENT_ID`, `AAD_CUSTOM_DOMAIN`, `AAD_DOMAIN`, `AAD_APPLICATION_ID` and `AAD_APPLICATION_API_KEY` values in your configuration object to make the values available in your rule code. To learn more, read [Store Configuration for Rules](/docs/customize/rules/configuration).

In the code, you'll also see that the rule will wait about 15 seconds after the user is provisioned. This is because it takes a few seconds before the provisioned user is available for Office 365.

```javascript lines expandable theme={null}
function (user, context, callback) {
  // Require the Node.js packages that we are going to use.
  // Check this website for a complete list of the packages available:
  // https://auth0-extensions.github.io/canirequire/
  var rp = require('request-promise');
  var uuidv4 = require('uuid');

  // The name of your Active Directory connection (if using one)
  var AUTH0_AD_CONNECTION = 'Travel0AD';
  // The client_id of your Office 365 SSO integration
  // You can get it from the URL when editing the SSO integration,
  // it will look like
  // https://manage.auth0.com/#/externalapps/{the_client_id}/settings
  var AUTH0_OFFICE365_CLIENT_ID = configuration.AUTH0_OFFICE365_CLIENT_ID;
  // The main domain of our company.
  var YOUR_COMPANY_DOMAIN = 'mycompanyurl.com';
  // Your Azure AD domain.
  var AAD_DOMAIN = configuration.AAD_DOMAIN;
  // The Application ID generated while creating the Azure AD app.
  var AAD_APPLICATION_ID = configuration.AAD_APPLICATION_ID;
  // The generated API key for the Azure AD app.
  var AAD_APPLICATION_API_KEY = configuration.AAD_APPLICATION_API_KEY;
  // The location of the users that are going to access Microsoft products.
  var AAD_USAGE_LOCATION = 'US';
  // Azure AD doesn't recognize the user instantly, it needs a few seconds
  var AAD_USER_CREATE_DELAY = 15000;
  // The key that represents the license that we want to give the new user.
  // Take a look in the following URL for a list of the existing licenses:
  // https://gist.github.com/Lillecarl/3c4727e6dcd1334467e0
  var OFFICE365_KEY = 'O365_BUSINESS';

  // Only execute this rule for the Office 365 SSO integration.
  if (context.clientID !== AUTH0_OFFICE365_CLIENT_ID) {
    return callback(null, user, context);
  }

  // Skip custom provisioning for AD users.
  if (context.connection === AUTH0_AD_CONNECTION) {
    return callback(null, user, context);
  }

  // If the user is already provisioned on Microsoft AD, we skip
  // the rest of this rule
  user.app_metadata = user.app_metadata || {};
  if (user.app_metadata.office365Provisioned) {
    return connectWithUser();
  }

  // Global variables that we will use in the different steps while
  // provisioning a new user.
  var token;
  var userPrincipalName;
  var mailNickname = user.email.split('@')[0];
  var uuid = uuidv4.v4();
  var immutableId = new Buffer(uuid).toString('base64');
  var userId;

  // All the steps performed to provision new Microsoft AD users.
  // The definition of each function are below.
  getAzureADToken()
    .then(createAzureADUser)
    .then(getAvailableLicenses)
    .then(assignOffice365License)
    .then(saveUserMetadata)
    .then(waitCreateDelay)
    .then(connectWithUser)
    .catch(callback);

  // Requests an Access Token to interact with Windows Graph API.
  function getAzureADToken() {
    var options = {
      method: 'POST',
      url: 'https://login.windows.net/' + AAD_DOMAIN + '/oauth2/token?api-version=1.5',
      headers: {
        'Content-type': 'application/json',
        },
      json: true,
      form: {
        client_id: AAD_APPLICATION_ID,
        client_secret: AAD_APPLICATION_API_KEY,
        grant_type: 'client_credentials',
        resource: 'https://graph.windows.net'
      },
    };

    return rp(options);
  }

  // Gets the Access Token requested above and assembles a new request
  // to provision the new Microsoft AD user.
  function createAzureADUser(response) {
    token = response.access_token;
    userPrincipalName = 'auth0-' + uuid + '@' + YOUR_COMPANY_DOMAIN;

    var options = {
      url: 'https://graph.windows.net/' + AAD_DOMAIN + '/users?api-version=1.6',
      headers: {
        'Content-type': 'application/json',
        'Authorization': 'Bearer ' + token
      },
      json: true,
      body: {
        accountEnabled: true,
        displayName: user.nickname,
        mailNickname: mailNickname,
        userPrincipalName: userPrincipalName,
        passwordProfile: {
          password: immutableId,
          forceChangePasswordNextLogin: false
        },
        immutableId: immutableId,
        usageLocation: AAD_USAGE_LOCATION
      },
    };

    return rp(options);
  }

  // After provisioning the user, we issue a request to get the list
  // of available Microsoft products licenses.
  function getAvailableLicenses(response) {
    userId = response.objectId;
    var options = {
      url: 'https://graph.windows.net/' + AAD_DOMAIN + '/subscribedSkus?api-version=1.6',
      json: true,
      headers: {
        'Content-type': 'application/json',
        'Authorization': 'Bearer ' + token
      }
    };
    return rp(options);
  }

  // With the licenses list, we iterate over it to get the id (skuId) of the
  // license that we want to give to the new user (office 365 in this case).
  // We also issue a new request to the Graph API to tie the user and the
  // license together.
  function assignOffice365License(response) {
    var office365License;

    for (var i = 0; i < response.value.length; i++) {
      if (response.value[i].skuPartNumber === OFFICE365_KEY) {
        office365License = response.value[i].skuId;
        break;
      }
    }

    var options = {
      url: ' https://graph.windows.net/' + AAD_DOMAIN + '/users/' + userId + '/assignLicense?api-version=1.6',
      headers: {
        'Content-type': 'application/json',
        'Authorization': 'Bearer ' + token
      },
      json: true,
      body: {
        'addLicenses': [
          {
            'disabledPlans': [],
            'skuId': office365License
          }
        ],
        'removeLicenses': []
      }
    };
    return rp(options);
  }

  // After provisioning the user and giving a license to them, we record
  // (on Auth) that this Google Workspace user has already been provisioned. We
  // also record the user's principal username and immutableId to properly
  // redirect them on future logins.
  function saveUserMetadata() {
    user.app_metadata = user.app_metadata || {};

    user.app_metadata.office365Provisioned = true;
    user.app_metadata.office365UPN = userPrincipalName;
    user.app_metadata.office365ImmutableId = immutableId;

    return auth0.users.updateAppMetadata(user.user_id, user.app_metadata);
  }

  // As mentioned, Windows Graph API needs around 10 seconds to finish
  // provisioning new users (even though it returns ok straight away)
  function waitCreateDelay() {
    return new Promise(function (resolve) {
      setTimeout(function() {
        resolve();
      }, AAD_USER_CREATE_DELAY);
    });
  }

  // Adds the principal username and immutableId to the user object and ends
  // the rule.
  function connectWithUser() {
    user.upn = user.app_metadata.office365UPN;
    user.inmutableid = user.app_metadata.office365ImmutableId;
      return callback(null, user, context);
  }
}
```

<Callout icon="file-lines">
  This code shows the provisioning process of a new user, but you can also adapt the code to synchronize metadata of existing users.
</Callout>

## User experience

The easiest way for your external users to authenticate is by using Identity Provider-initiated login.

You must redirect your users to the following URL (e.g., using a "smart link" like `https://office.travel0.com`):

<AuthCodeBlock />

This will show them the Auth0 login page after which they'll be redirected to Office 365. It will be important to explain external users that this is the only way they can authenticate, since the Office 365 login page does not support Home Realm Discover for these external users. This also means that, when they try to open a link, they'll need to visit the smart link first before the can access the link they tried to open.

In this example, Travel0 enabled a few social accounts and a database connection for their Office 365 third-party application in Auth0.

## Deep linking

Certain implementations might require deep linking (for example, to SharePoint Online). In this case, a smart link needs to be constructed, which starts on the Office 365 login page:

```http wrap lines theme={null}
https://login.microsoftonline.com/login.srf?wa=wsignin1.0&whr={yourCustomDomain}&wreply={deepLink}
```

The first parameter, `{yourCustomDomain}`, should be the domain you've configured in Azure AD for <Tooltip href="/docs/glossary?term=Single+Sign-on+%28SSO%29">Single Sign-on (SSO)</Tooltip> (e.g., `travel0.com`). By specifying this as the `whr`, Azure AD will know it needs to redirect to Auth0 instead of showing the login page.

The `DEEP_LINK` parameter should be an encoded URL within Office 365 (for example, a page in SharePoint Online or Exchange).

Example URL:

```http wrap lines theme={null}
https://login.microsoftonline.com/login.srf?wa=wsignin1.0&whr=travel0.com&wreply=https%3A%2F%2Ftravel0%2Esharepoint%2Ecom
```


# Secure a CLI with Auth0
Source: https://auth0.com/docs/customize/integrations/secure-a-cli-with-auth0

How to use Auth0 to secure a CLI.

The three ways to secure a CLI with Auth0, in order of most secure to least secure, are:

* [Device Authorization Flow](#device-authorization-flow) for when the user can't open a browser
* [Client Credentials Grant Flow](#client-credentials-grant-flow) for applications acting on their own behalf and not attributable to a user
* [Resource Owner Password Grant Flow](#resource-owner-password-grant-flow) only for when you're trying to authenticate the CLI client itself, which is a very rare situation (otherwise not recommended)

## Device Authorization Flow

With input-constrained devices that connect to the internet, rather than authenticate the user directly, the device asks the user to go to a link on their computer or smartphone and authorize the device. This avoids a poor user experience for devices that do not have an easy way to enter text. To do this, device apps use the Device <Tooltip href="/docs/glossary?term=Authorization+Flow">Authorization Flow</Tooltip> (drafted in OAuth 2.0), in which they pass along their <Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip> to initiate the authorization process and get a token.

The easiest way to implement the Device Authorization Flow is to follow the steps in [Call API Using Device Authorization Flow](/docs/get-started/authentication-and-authorization-flow/device-authorization-flow/call-your-api-using-the-device-authorization-flow).

To learn more about the Device Authorization Flow in <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip>, you can review the Internet Engineering Task Force (IEFT) draft [OAuth 2.0 Authorization Grant](https://tools.ietf.org/html/draft-ietf-oauth-device-flow-15). You can also review our article, [Device Authorization Flow](/docs/get-started/authentication-and-authorization-flow/device-authorization-flow).

## Client Credentials Grant Flow

Use the Client Credentials Grant (CCG) flow when users and downstream <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> aren't involved, and you want to authenticate based on distinct machines or devices.

If your identity provider supports sending credentials, then you should review our article, [Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow). For details on how to implement this flow, refer to [Call API Using the Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow/call-your-api-using-the-client-credentials-flow).

## Resource Owner Password Grant Flow

We do not recommend using the <Tooltip href="/docs/glossary?term=Resource+Owner">Resource Owner</Tooltip> Password Grant (ROPG) flow for native applications. In the IEFT article, [RFC 8252 OAuth 2.0 for Native Apps](https://tools.ietf.org/html/rfc8252), it is recommended that “OAuth 2.0 authorization request from native apps should ONLY be made through external user-agents, primarily the user’s browser”. For details, see [RFC 8252 Embedded User-Agents](https://tools.ietf.org/html/rfc8252#section-8.12).

Using Resource Owner Password Grant (ROPG) are less secure than the redirect-based options described above. ROPG is only for legacy. In the context of CLIs, it only makes sense for things like connection strings where you need to support legacy programs.

If you must use ROPG in your native app instead of Device Flow as we recommend, then you can use our [OIDC Compliant ROPG endpoint](https://auth0.com/docs/api/authentication#resource-owner-password).


# Integrate with SharePoint 2010/2013
Source: https://auth0.com/docs/customize/integrations/sharepoint-2010-2013

How to integrate with SharePoint 2010/2013, including set up, troubleshooting, accessing logs and next steps.

Auth0 can help to radically simplify the authentication process for SharePoint. In this tutorial, you'll learn how to add <Tooltip href="/docs/glossary?term=Single+Sign-on">Single Sign-on</Tooltip> (SSO) to Sharepoint using Auth0. Your users will be able to log in using any of our [Social Identity Providers](/docs/authenticate/identity-providers/social-identity-providers) (Facebook, X, Github, and so on), [Enterprise Providers](/docs/authenticate/identity-providers/enterprise-identity-providers) (LDAP, Active Directory, ADFS, and so on) or with a username and password.

<Callout icon="file-lines">
  Auth0 no longer supports the Auth0Claims Provider for SharePoint 2010 / 2013. This package is deprecated for existing tenants and unavailable for new tenants.
</Callout>

## Setup

### Step 1. Adding the Integration to your account

The first thing you need to do is go to the [SSO Integrations](https://manage.auth0.com/#/externalapps/create) section in the Dashboard and choose **SharePoint** from the list of apps.

### Step 2. Follow the Live Documentation

<Callout icon="file-lines">
  If your SharePoint server does not have Internet access, manually download the installation files. ([Learn more about offline installation](https://github.com/auth0/auth0-sharepoint/tree/master/auth0-authentication-provider)).
</Callout>

On the **Settings** tab you'll need to enter the URL of the SharePoint Web Application and the external URL (typically the internet endpoint in your Alternate Access Mappings).

The Live Documentation will first start with the installation of the Auth0 CmdLets for SharePoint:

<Frame>
  <img alt="SharePoint Management Shell - cmdlets installation" />
</Frame>

Once these have been installed you'll be able to enable/disable Auth0 and the Claims Provider for the different Web Applications. You will need to enable authentication with Auth0:

<Frame>
  <img alt="SharePoint Management Shell - Auth0 install - Enable Authentication" />
</Frame>

And then install the Claims Provider, to make sure that the People Picker and permissions work correctly:

<Frame>
  <img alt="SharePoint Management Shell - install claims provider" />
</Frame>

Once these scripts have been executed you'll complete the configuration in Central Administration:

<Frame>
  <img alt="SharePoint central admin - complete configuration" />
</Frame>

Note that the call to `Enable-Auth0` can be adapted to:

* Change the unique identifier for users (such as email or a user id)
* Allow additional claims to be passed through to SharePoint
* Enable or disable the default Windows Authentication

The following example also adds the Role claim to the claims mapping and allows Windows Authentication:

```powershell lines theme={null}
Enable-Auth0
  -auth0Domain:"fabrikam.auth0.com"
  -clientId:"bOFty3tWgpijnwMcltysNFqHgO1ziz1I"
  -webAppUrl:"http://fabrikam-sp/"
  -identifierClaimType:"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
  -claims:@(
    "Email|http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    "Role|http://schemas.microsoft.com/ws/2008/06/identity/claims/role", "Client ID|http://schemas.auth0.com/clientID",
    "Given Name|http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
    "Surname|http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname", "Picture|http://schemas.auth0.com/picture")
  -allowWindowsAuth
```

### Step 3. You now have Sharepoint configured

You have configured SharePoint to use Auth0 as the SSO broker. When your users visit your site they'll be presented with a login page showing all the connections enabled for that application.

Depending on which claims have been mapped when installing the claims provider this additional information will also be available in the user's personal settings page:

<Frame>
  <img alt="SharePoint - user information" />
</Frame>

<Frame>
  <img alt="SharePoint central admin - complete configuration" />
</Frame>

Note that you can adapt the call to `Enable-Auth0` to:

* Change the unique identifier for users (such as email or a user id)
* Allow additional claims to be passed through to SharePoint
* Enable or disable the default Windows Authentication

This example also adds the Role claim to the claims mapping and allows Windows Authentication:

```powershell lines theme={null}
Enable-Auth0
  -auth0Domain:"fabrikam.auth0.com"
  -clientId:"bOFty3tWgpijnwMcltysNFqHgO1ziz1I"
  -webAppUrl:"http://fabrikam-sp/"
  -identifierClaimType:"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
  -claims:@(
    "Email|http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    "Role|http://schemas.microsoft.com/ws/2008/06/identity/claims/role", "Client ID|http://schemas.auth0.com/clientID",
    "Given Name|http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
    "Surname|http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname", "Picture|http://schemas.auth0.com/picture")
  -allowWindowsAuth
```

SharePoint will now use Auth0 as the SSO broker.

## Customizing the Login Page

You can customize the login page by following [Auth0 Universal Login](/docs/authenticate/login/auth0-universal-login) instructions.

You might wish to provide a way to let users authenticate with Sharepoint using Windows Authentication, bypassing Auth0. You can do that by customizing the login page, adding a link to the Windows Authentication endpoint (usually similar to `https://yoursharepointserver/_windows/default.aspx?ReturnUrl=/_layouts/15/Authenticate.aspx`).

On way of doing it is by using jQuery to modify the Lock widget and add a link to the Windows Authentication endpoint.

You need to add a reference to jQuery at the top of the `<body>` section of the customized login page.

```html wrap lines theme={null}
<script src="https://code.jquery.com/jquery-3.3.1.slim.min.js"></script>
```

Before calling `lock.show()`, add code to modify the HTML DOM that adds the link.

```javascript lines expandable theme={null}
// construct Lock
// var lock = ...
[...]
// One or more SharePoint client IDs here for which you want
// a Windows Auth button
var sharepointClientIDs = ['your_sharepoint_client_id'];

if (sharepointClientIDs.indexOf(config.clientID) >= 0) {
  lock.on('signin ready', function() { 
    var getParameterByName = function(name) {
      name = name.replace(/[\[]/, "\\\[").replace(/[\]]/, "\\\]");
      var regexS = "[\\?&]" + name + "=([^&#]*)";
      var regex = new RegExp(regexS);
      var results = regex.exec(window.location.search);
      if (results == null) return null;
      else return results[1];
    };
    // get the host from the callback URL
    var parser = document.createElement('a');
    parser.href = config.callbackURL;
    var host = parser.host;
    var windowsAuthURL = "https://" + host + "/_windows/default.aspx?ReturnUrl=/_layouts/15/Authenticate.aspx";
    var wctx = getParameterByName("wctx");
    if (wctx) {
      windowsAuthURL += "&Source=" + wctx;
    }

    $('.auth0-lock-tabs-container') 
    .after('<div><p class="auth0-lock-alternative" style="padding:5px 0;">' + 
      '<a class="auth0-lock-alternative-link" ' + 
      'href="'+ windowsAuthURL + '">' +
      'Login with Windows Authentication!!!</a>' + 
      '</p><p><span>or</span></p></div>').attr('href','https://nowhere');
  });
}

lock.show();
```

## Troubleshooting

When working with additional claims and authorization it can always be useful to view the claims for the current user. Microsoft Professional [Liam Clearly](https://helloitsliam.com/)'s article, [Claims Viewer Web Part](https://sharepointobservations.wordpress.com/2013/08/21/sharepoint-2013-and-adfs-2-0-test-with-claims-viewer-web-part/), can be used to troubleshoot any issues with the user's claims:

### Logs in SP2010

Errors and warnings are logged to SharePoint's Unified Logging Service and tools like the ULS Viewer can be used to troubleshoot any issues you might have when using the Claims Provider.

To read more about ULS View and retrieve specifications, see Microsoft documentation [ULS Viewer](https://www.microsoft.com/en-us/download/details.aspx?id=44020).

### Logs in SP2013

For SharePoint 2013 we no longer use the Unified Logging Service for our logs, but we've moved to Event Tracing for Windows instead. This delivers more performance and gives you multiple ways of capturing all the logged events.

To view the logs in real-time you can download the Auth0 [Logs Processor](https://github.com/auth0/auth0-sharepoint/releases) from Github. Run this tool on your SharePoint Server(s) to see every call SharePoint is making to the Claims Provider:

## Next Steps

### Authorization

The claims being passed through from Auth0 can also be used for authorization in SharePoint. For example, a user with the Role claim containing **Fabrikam HR** should have access or be a Contributor on a specific site.

Let's take Azure AD as an example. In this Cloud Directory users can be part of groups and David is part of Fabrikam HR.

When David logs in using his Azure AD account (and the Security Groups attribute is enabled for that connection) the group memberships will be stored in the `groups` attribute of the user's profile.

If we want to make these groups available as Roles in SharePoint we'll need to write a [Rule](https://manage.auth0.com/#/rules) that adds this to the <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> configuration. This rule will only run for the application named **Fabrikam Intranet (SharePoint)**.

```javascript lines theme={null}
function (user, context, callback) {
  if (context.clientName === 'Fabrikam Intranet (SharePoint)') {
    context.samlConfiguration.mappings = {
        'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier': 'user_id',
        'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress': 'email',
        'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name': 'name',
        'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname': 'given_name',
        'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname': 'family_name',
        'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn': 'upn',
        'http://schemas.microsoft.com/ws/2008/06/identity/claims/role': 'groups'
    };
  }

  callback(null, user, context);
}
```

This will add an additional outgoing claim `http://schemas.microsoft.com/ws/2008/06/identity/claims/role` containing the `groups` and which will be used by SharePoint for authorization.

When installing the Claims Provider we need to allow the Role claim to be passed through to SharePoint, by adding it to the claims mapping list:

```powershell lines theme={null}
Enable-Auth0
  -auth0Domain:"fabrikam.auth0.com"
  ...
  -claims:@(
    "Email|http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    "Role|http://schemas.microsoft.com/ws/2008/06/identity/claims/role",
    ...)
  ...
  -Verbose
```

By default a user won't have access to the site.

Now instead of adding that specific user to a SharePoint Group (eg: Contributors) we can now add a **Role** to a SharePoint Group. Here's a sample PowerShell script that shows how to add "Fabrikam HR" members to the Contributors group:

```powershell lines theme={null}
$webName = "http://fabrikam-sp"
$groupName = "Contributors"
$roleClaim = "Fabrikam HR"

$sts = Get-SPTrustedIdentityTokenIssuer "Auth0"
$claimPrincipal = New-SPClaimsPrincipal -ClaimValue $roleClaim -ClaimType "http://schemas.microsoft.com/ws/2008/06/identity/claims/role" -TrustedIdentityTokenIssuer $sts

$web = Get-SPWeb $webName
$user = New-SPUser -UserAlias $claimPrincipal.ToEncodedString() -Web $web

$group = $web.SiteGroups[$groupName]
$group.AddUser($user)
```

After adding this claim value to the Contributors group David will be able to access the site and edit its contents.

### User Profile Synchronization

By default SharePoint is able to synchronize user profile information originating from Active Directory. Now with Auth0 users can come from different types of connections (from social to enterprise) which will require a different approach to synchronize user profiles.

A first approach would be to create a timer job that runs every few hours, queries the Auth0 Users Endpoint and synchronizes the profile information for those users.

```csharp lines expandable theme={null}
using System;

using Microsoft.SharePoint;
using Microsoft.SharePoint.Administration;

using Microsoft.Office.Server;
using Microsoft.Office.Server.UserProfiles;

namespace UserProfileSync
{
    class Program
    {
        static void Main(string[] args)
        {
            // Call the Auth0 Management API - https://docs.auth0.com/api/v2

            using (var site = new SPSite("http://servername"))
            {
                var context = SPServiceContext.GetContext(site);
                var profileManager = new UserProfileManager(context);

                var accountName = "i:05.t|auth0|john@example.org";
                var userProfile = profileManager.GetUserProfile(accountName);
                userProfile[PropertyConstants.HomePhone].Value = "+1 594 9392";
                userProfile.Commit();
            }
        }
    }
}
```

Alternatively this logic could also be implemented as an HttpModule which runs each time the user logs in:

```csharp lines theme={null}
public class PersistUserClaimsHttpModule : IHttpModule
{
    private SPFederationAuthenticationModule FederationModule
    {
        get { return HttpContext.Current.ApplicationInstance.Modules["FederatedAuthentication"] as SPFederationAuthenticationModule; }   
    }

    public void Init(HttpApplication context)
    {
        FederationModule.SecurityTokenValidated += OnFederationSecurityTokenValidated;
    }

    private void OnFederationSecurityTokenValidated(object sender, SecurityTokenValidatedEventArgs e)
    {
        // Use e.ClaimsPrincipal
    }
}
```


# Single Sign-On Integrations
Source: https://auth0.com/docs/customize/integrations/sso-integrations

Overview of Auth0 Single Sign-on (SSO) Integrations.

<Tooltip href="/docs/glossary?term=Single+Sign-on">Single Sign-on</Tooltip> (SSO) Integrations are client applications that enable the use of external services (e.g., [Dropbox](https://marketplace.auth0.com/integrations/dropbox-sso), [Slack](https://marketplace.auth0.com/integrations/slack-sso), or [Zoom](https://marketplace.auth0.com/integrations/zoom-sso)) for SSO. The integration allows your users to log in using Auth0's <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip>. To see the full list, explore [Auth0 Marketplace: SSO Integrations](https://marketplace.auth0.com/features/sso-integrations).

For more information on Auth0's available Connections, see [Auth0 Connections](/docs/authenticate/identity-providers).


# Log Streams
Source: https://auth0.com/docs/customize/log-streams

Describes how to export your logs in near real-time using log streaming.

Auth0's log streaming service allows you to export tenant logs to a log analysis service. You can choose the content type and form and preview the payload using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. Log streaming allows you to react to log events like password changes or new registrations with your own business logic. Using the Auth0 Dashboard and API, you can pause a stream, view and update settings, and check the health of the stream.

<Callout icon="file-lines">
  By enabling Log Streams, Customer becomes the Controller of such information and is responsible for the data exported from the Auth0 Platform, including what information is streamed and how it is used by Customer.
</Callout>

You can create a new log stream in the Auth0 Dashboard using one of the services we support or you can configure a stream to a service you already use with a custom webhook.

<Frame>
  <img alt="Dashboard Monitoring Streams" />
</Frame>

## Supported log streaming services

We support a variety of [log streaming services](https://marketplace.auth0.com/features/log-streaming) through the [Auth0 Marketplace](https://marketplace.auth0.com), including:

* [Amazon EventBridge](https://marketplace.auth0.com/integrations/amazon-log-streaming)
* [Azure Event Grid](https://marketplace.auth0.com/integrations/azure-log-streaming)
* [Elastic](https://marketplace.auth0.com/integrations/elastic-security)
* [Logz.io](https://marketplace.auth0.com/integrations/logz-io)
* [MDR ONE](https://marketplace.auth0.com/integrations/mdr-one)
* [Mixpanel](https://marketplace.auth0.com/integrations/mixpanel-log-streaming)
* [Oort](https://marketplace.auth0.com/integrations/oort)
* [Pangea](https://marketplace.auth0.com/integrations/pangea-log-streaming)
* [Panther](https://marketplace.auth0.com/integrations/panther-log-stream)
* [Perch Security](https://marketplace.auth0.com/integrations/perch-security-log-streaming)
* [Segment](https://marketplace.auth0.com/integrations/segment-log-streaming)
* [Slack](https://marketplace.auth0.com/integrations/slack-log-streaming)
* [Datadog](https://marketplace.auth0.com/integrations/datadog-log-streaming)

  * Auth0 provides Datadog dashboard templates. To learn more, read [Use Auth0 Dashboard Templates with Datadog](/docs/customize/log-streams/datadog-dashboard-templates).
* [Splunk](https://marketplace.auth0.com/integrations/splunk-log-streaming)

  * Auth0 also provides a dashboard to visualize the data from your Auth0 tenant. You can use the app to view recommended aggregations from Auth0 or to use them as a starting point to create your own custom visualizations. To learn more, read [Use Auth0 App for Splunk](/docs/customize/log-streams/splunk-dashboard).
* [Sumo Logic](https://marketplace.auth0.com/integrations/sumo-logic-log-streaming)

  * Auth0 provides a Sumo Logic app and dashboard to visualize and monitor the health of login traffic from your Auth0 tenant. You can also use to view recommended aggregations from Auth0 or to use them as a starting point to create your own custom visualizations. To learn more, read [Use Auth0 App for Sumo Logic](/docs/customize/log-streams/sumo-logic-dashboard).

## Delivery attempts

Auth0 delivers each log to your server as it is triggered in our system. We guarantee logs are delivered at least once.

When a log is triggered:

1. We attempt to deliver the log to your server up to three times.
2. If we fail to reach your server by the third attempt, we log an error visible in the **Health** view for the log stream.
3. We restart this process for any errored log until the problem is resolved.

If we fail to reach your server for 7 consecutive days, we'll automatically pause the stream. You'll need to resolve the issue, and then resume the stream manually.

## Log retention

Your Auth0 log retention period depends on your [subscription level](/docs/deploy-monitor/logs/log-data-retention).

If there is an issue where your server does not receive logs sent from Auth0, you can delete the stream and then recreate it with the Starting Cursor field set to a specific day and time within the retention period.

## Filtering and PII obfuscation

Customers can choose which [filter categories](/docs/deploy-monitor/logs/log-event-filters) of their logs to stream and which to exclude to ensure the external destination receives only the relevant data. Customers can also choose to mask or hash Personal Identifiable Information (PII) in the streamed logs.

### PII obfuscation

Auth0 provides two ways to obfuscate PII tenant log fields when streaming to third-party destinations:

* **Masking:** the field values are replaced with asterisks
* **xxHash:** a fast, non-cryptographic hash algorithm

The customer can obfuscate the following log data and field names when streaming:

<table>
  <thead>
    <tr>
      <th><strong>Data</strong></th>
      <th><strong>Field name</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>first\_name</code></td>
      <td><code>first\_name</code><br /><code>given\_name</code><br /><code>name</code></td>
    </tr>

    <tr>
      <td><code>last\_name</code></td>
      <td><code>last\_name</code><br /><code>family\_name</code><br /><code>name</code></td>
    </tr>

    <tr>
      <td><code>email</code></td>
      <td><code>email</code></td>
    </tr>

    <tr>
      <td><code>phone</code></td>
      <td><code>phone</code><br /><code>phone\_number</code><br /><code>old\_phone\_number</code><br /><code>new\_phone\_number</code></td>
    </tr>

    <tr>
      <td><code>address</code></td>
      <td><code>address</code></td>
    </tr>

    <tr>
      <td><code>username</code></td>
      <td><code>username</code><br /><code>user\_name</code></td>
    </tr>
  </tbody>
</table>

## Learn more

* [Create Custom Log Streams Using Webhooks](/docs/customize/log-streams/custom-log-streams)
* [Check Log Stream Health](/docs/customize/log-streams/check-log-stream-health)
* [Log Stream Filters](/docs/customize/log-streams/event-filters)


# Check Log Stream Health
Source: https://auth0.com/docs/customize/log-streams/check-log-stream-health

Learn how to check the health of your log streaming configurations in the Auth0 Dashboard.

You can troubleshoot potential issues with your stream by looking at the **Health** tab.

1. Go to [Dashboard > Monitoring > Streams](https://manage.auth0.com/#/log-streams).
2. Locate the log stream you want to check in the list.

   Your log stream can have one of the following statuses:

   * **Active**: Your stream is enabled with us, and we will attempt to deliver the next log events.
   * **Paused**: You have requested that we stop delivery attempts for the stream. You can click **Resume Stream** to change the status back to **Active**.
   * **Disabled**: We have disabled your stream because of successive errors. You can click **Restart Stream** to change the status back to **Active** and retry delivery for this stream.
3. Select the more options menu (...) at the end of the stream, and click **Health** on the drop-down menu. To help diagnose issues with your stream, you can see the last ten errors we encountered while attempting to deliver logs to your stream within the last 5 days.


# Create Custom Log Streams Using Webhooks
Source: https://auth0.com/docs/customize/log-streams/custom-log-streams

Learn how to configure a log stream using a custom webhook to stream log events to the URL of your choice.

Webhooks allow events to be delivered to an external web server. Auth0 offers several integrations that automatically push events to third-party log management and analysis systems. If however your third-party system isn't supported, you can set up a custom webhook integration.

<Callout icon="file-lines">
  You can only subscribe one payload URL per webhook configuration, but you can use the same URL for multiple streams. The payload will be delivered in JSON lines format. Keep that in mind while consuming the logs in your webhook configuration.
</Callout>

## Configure API endpoint

You'll build an API that serves a single route (such as `/api/logs`) that accepts `HTTP POST` requests.

<Warning>
  Self-signed HTTP certificates are not supported.
</Warning>

## Configure log stream

1. Go to [Dashboard > Monitoring > Streams](https://manage.auth0.com/#/log-streams) and click **Create Stream**.

   <Frame>
     <img alt="Dashboard Monitoring Streams" />
   </Frame>
2. Select **Custom Webhook** and enter a unique name for your new stream.
3. Configure the following settings:

   <Frame>
     <img alt="Dashboard Monitoring Streams Custom Webhook Settings Tab" />
   </Frame>

   <table>
     <thead>
       <tr>
         <th><strong>Setting</strong></th>
         <th><strong>Description</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td><strong>Name</strong></td>
         <td>A unique display name to distinguish this integration from other integrations.</td>
       </tr>

       <tr>
         <td><strong>Payload URL</strong></td>
         <td>The URL where the event payloads are sent as HTTP POST requests.</td>
       </tr>

       <tr>
         <td><strong>Authorization Token</strong></td>
         <td>(Optional) The value in the Authorization header of the request.</td>
       </tr>

       <tr>
         <td><strong>Content Type</strong></td>
         <td>The media type of the payload that will be delivered to the webhook.</td>
       </tr>

       <tr>
         <td><strong>Content Format</strong></td>
         <td>Receive data in JSON lines, arrays, or objects.</td>
       </tr>

       <tr>
         <td><strong>Filter by Event Category</strong></td>
         <td>List of log stream filters.</td>
       </tr>

       <tr>
         <td><strong>Starting Cursor</strong></td>
         <td>(Optional) Specific day and time to start the stream from.</td>
       </tr>
     </tbody>
   </table>
4. Click **Save**.

## Test configuration

1. Switch to the **Health** view and confirm that the **Stream Status** is **Active.**
2. Perform an action that creates a tenant log event, like a login, token exchange, or Auth0 Management API call.
3. Confirm that the event was created in your tenant logs.
4. Confirm that your API received an `HTTP POST` request with the event data.
5. Go to the **Health** view and confirm that no errors occurred.

## Troubleshoot Webhooks

If your webhook isn't working, it can be difficult to troubleshoot and determine what is causing the issue. Webhooks are asynchronous, so testing them can involve you triggering the webhook, waiting, and then checking the response (assuming that you did receive a response).

However, there are certainly alternatives to the inefficient process we detailed above. While full details of how to troubleshoot a particular webhook is outside the scope of this article, here are some steps you can take to debug:

1. Check [Auth0 Dashboard > Monitoring > Logs](/docs/deploy-monitor/logs) for helpful messages.
2. Analyze the requests your webhook is making using a tool like [Mockbin](http://mockbin.io/), [Beeceptor](https://beeceptor.com/), or (self-hosted) [RequestBin](https://github.com/RonTt/Requestbin).
3. Mock requests using cURL or [Postman](https://www.getpostman.com/).
4. Test your webhook code locally using something like [localtunnel](https://github.com/localtunnel/localtunnel) or [ngrok](https://ngrok.com/).
5. Use a tool like [Runscope](https://www.runscope.com/) or [Assertible](https://assertible.com/) to watch the whole execution flow.

## Learn more

* [Check Log Stream Health](/docs/customize/log-streams/check-log-stream-health)
* [Filter Log Events](/docs/deploy-monitor/logs/log-event-filters)
* [Log Type Codes](/docs/deploy-monitor/logs/log-event-type-codes)


# Use Auth0 Dashboard Templates with Datadog
Source: https://auth0.com/docs/customize/log-streams/datadog-dashboard-templates

Describes how to import and use Auth0 dashboard templates to visualize the data from your Auth0 tenant in Datadog.

Auth0 provides predefined templates that you can use to visualize the data from your Auth0 tenant in Datadog. Display visualizations to monitor the health of the login traffic for a tenant. Templates allow you to use recommended aggregations from Auth0, or to use them as a starting point to create your own custom visualizations.

<table>
  <thead>
    <tr>
      <th>Template</th>
      <th>Purpose</th>
      <th>Downloadable File</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Security Dashboard</td>
      <td>Monitor tenant login traffic including login, account creation, and anomaly detection metrics.</td>
      <td><a href="https://cdn.auth0.com/website/docs/logs/streams/datadog/Auth0SecurityDashboard.json">Auth0SecDashboard.json</a></td>
    </tr>
  </tbody>
</table>

You can also organize your visualization using the following features:

* Use Datadog time selection to choose the window for your visualization.
* Use filters to narrow down data analysis using configurable parameters such as IP address, Country, User, and Client Application.
* Use **Edit Widgets** to rearrange the tiles and visualizations, as well as create copies where you can inspect and add parameters to queries as needed.

## Prerequisites

* [Set up log streaming to Datadog](https://marketplace.auth0.com/integrations/datadog-log-streaming).
* Download the desired dashboard template JSON file from Auth0.

## Upload dashboard templates in Datadog

1. Log into [Datadog](https://www.datadoghq.com/).
2. Navigate to **Dashboards** on the left navigation bar.
3. Select **Screenboard** as the dashboard type.
4. On the blank canvas, in the upper right, select the gear icon and click **Import Dashboard JSON**.
5. Upload the JSON file for the dashboard you wish to use (for example, `Auth0SecDashboard.json`).

## Security Dashboard visualizations

Once you have imported the Security Dashboard from Auth0, you can use the following visualizations to determine the health of your tenant or as a starting point to build your own visualizations and alerts in Datadog.

<table>
  <thead>
    <tr>
      <th>Visualization</th>
      <th>Purpose</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Login Success</td>
      <td>Displays the number of successful login events for the tenant.</td>
    </tr>

    <tr>
      <td>Login Failures</td>
      <td>Displays the number of failed login events for the tenant.  Spikes in login failures may be a signal of anomalous traffic.</td>
    </tr>

    <tr>
      <td>Login Failures by Geolocation</td>
      <td>Displays the number of failed login events for the tenant by geolocation.  Unexpected traffic spikes in certain geographies may be a signal of anomalous traffic.</td>
    </tr>

    <tr>
      <td>Number of Unique IPs sending traffic</td>
      <td>Displays the number of IP addresses that are sending traffic to the tenant.  This number often follows predictable patterns, and strong variations may signal anomalous traffic.</td>
    </tr>

    <tr>
      <td>Top 5 IPs with failures</td>
      <td>Displays the 5 IP addresses that have experienced the highest number of login errors.</td>
    </tr>

    <tr>
      <td>Account Creation Events in top countries</td>
      <td>Displays the number of accounts created in the top countries.   Variations in the predictable patterns and geographies may signal anomalous traffic.</td>
    </tr>

    <tr>
      <td>Account Creation Events by Platform</td>
      <td>Displays the number of accounts created by platform, such as Windows, OSX, Android, or iOS.</td>
    </tr>

    <tr>
      <td>IPs with most accounts created</td>
      <td>Displays the IP addresses from which the most number of accounts have been created.</td>
    </tr>

    <tr>
      <td>Anomaly Detection Events</td>
      <td>Displays the number of anomaly detection events for the tenant, including the number of blocked IP addresses due to Brute Force Protection and Breached Password Detection.</td>
    </tr>

    <tr>
      <td>Log Stream</td>
      <td>Displays raw events from the tenant log.</td>
    </tr>
  </tbody>
</table>

## Customize dashboard

You can customize your Datadog Auth0 security dashboard to add custom data widgets.

1. Navigate to your Auth0 security dashboard and go to the **Dashboards** item in the side navigation.
2. Select the name of the dashboard you created from the list.
3. Select a visualization and drag it to the main section of the page.
4. Configure your data graph preferences.

## Learn more

* [View Attack Protection Log Events](/docs/secure/attack-protection/view-attack-protection-events)
* [Configure Datadog as SAML Service Provider](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider/configure-auth0-as-identity-provider-for-datadog)


# Log Stream Filters
Source: https://auth0.com/docs/customize/log-streams/event-filters

Lists available log filters for log streams and the logs included in each filter.

You can filter your log streams so only select logs and log categories are delivered. To configure a log stream's filter:

1. Go to [Dashboard > Monitoring > Streams](https://manage.auth0.com/#/log-streams).
2. Select a log stream and go to the **Settings** tab.
3. Enable or disable filters in the **Filter By Event Category** menu.
4. Click **Save**.

## Actions event filters

<table>
  <thead>
    <tr>
      <th><strong>Filter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Action Execution - Failure</td>
      <td>Failed Action execution events</td>
    </tr>
  </tbody>
</table>

### Action Execution - Failure

<table>
  <thead>
    <tr>
      <th><strong>Event Code</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>actions\_execution\_failed</code></td>
      <td>Execution of an Action failed</td>
    </tr>
  </tbody>
</table>

## Authentication event filters

<table>
  <thead>
    <tr>
      <th><strong>Filter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Login - Failure</td>
      <td>Failed login events</td>
    </tr>

    <tr>
      <td>Login - Notification</td>
      <td>Login notification events</td>
    </tr>

    <tr>
      <td>Login - Success</td>
      <td>Successful login events</td>
    </tr>

    <tr>
      <td>Logout - Failure</td>
      <td>Failed logout events</td>
    </tr>

    <tr>
      <td>Logout - Success</td>
      <td>Successful logout events</td>
    </tr>

    <tr>
      <td>Signup - Failure</td>
      <td>Failed signup events</td>
    </tr>

    <tr>
      <td>Signup - Success</td>
      <td>Successful signup events</td>
    </tr>

    <tr>
      <td>Silent Authentication - Failure</td>
      <td>Failed silent authentication events</td>
    </tr>

    <tr>
      <td>Silent Authentication - Success</td>
      <td>Successful silent authentication events</td>
    </tr>

    <tr>
      <td>Token Exchange - Failure</td>
      <td>Failed token exchange events</td>
    </tr>

    <tr>
      <td>Token Exchange - Success</td>
      <td>Successful token exchange events</td>
    </tr>
  </tbody>
</table>

### Login - Failure

<table>
  <thead>
    <tr>
      <th><strong>Event Code</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>f</code></td>
      <td>Failed login</td>
    </tr>

    <tr>
      <td><code>fc</code></td>
      <td>Failed connector login</td>
    </tr>

    <tr>
      <td><code>fco</code></td>
      <td>Origin is not in the application's Allowed Origins list</td>
    </tr>

    <tr>
      <td><code>fcoa</code></td>
      <td>Failed cross-origin authentication</td>
    </tr>

    <tr>
      <td><code>fens</code></td>
      <td>Failed native social login</td>
    </tr>

    <tr>
      <td><code>fp</code></td>
      <td>Incorrect password</td>
    </tr>

    <tr>
      <td><code>fu</code></td>
      <td>Invalid email or username</td>
    </tr>
  </tbody>
</table>

### Login - Notification

<table>
  <thead>
    <tr>
      <th><strong>Event Code</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>w</code></td>
      <td>Warnings during login</td>
    </tr>
  </tbody>
</table>

### Login - Success

<table>
  <thead>
    <tr>
      <th><strong>Event Code</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>s</code></td>
      <td>Successful login</td>
    </tr>

    <tr>
      <td><code>scoa</code></td>
      <td>Successful cross-origin authentication</td>
    </tr>

    <tr>
      <td><code>sens</code></td>
      <td>Successful native social login</td>
    </tr>
  </tbody>
</table>

### Logout - Failure

<table>
  <thead>
    <tr>
      <th><strong>Event Code</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>flo</code></td>
      <td>User logout failed</td>
    </tr>

    <tr>
      <td><code>oidc\_backchannel\_logout\_failed</code></td>
      <td>Failed OIDC back-channel logout request</td>
    </tr>
  </tbody>
</table>

### Logout - Success

<table>
  <thead>
    <tr>
      <th><strong>Event Code</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>oidc\_backchannel\_logout\_succeeded</code></td>
      <td>Successful OIDC back-channel logout request</td>
    </tr>

    <tr>
      <td><code>slo</code></td>
      <td>User successfully logged out</td>
    </tr>
  </tbody>
</table>

### Signup - Failure

<table>
  <thead>
    <tr>
      <th><strong>Event Code</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>fs</code></td>
      <td>User signup failed</td>
    </tr>
  </tbody>
</table>

### Signup - Success

<table>
  <thead>
    <tr>
      <th><strong>Event Code</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>ss</code></td>
      <td>Successful user signup</td>
    </tr>
  </tbody>
</table>

### Silent Authentication - Failure

<table>
  <thead>
    <tr>
      <th><strong>Event Code</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>fsa</code></td>
      <td>Failed silent authentication</td>
    </tr>
  </tbody>
</table>

### Silent Authentication - Success

<table>
  <thead>
    <tr>
      <th><strong>Event Code</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>ssa</code></td>
      <td>Successful silent authentication</td>
    </tr>
  </tbody>
</table>

### Token Exchange - Failure

<table>
  <thead>
    <tr>
      <th><strong>Event Code</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>feacft</code></td>
      <td>Failed exchange of Authorization Code for Access Token</td>
    </tr>

    <tr>
      <td><code>feccft</code></td>
      <td>Failed exchange of Access Token for a Client Credentials Grant</td>
    </tr>

    <tr>
      <td><code>fede</code></td>
      <td>Failed exchange of Device Code for Access Token</td>
    </tr>

    <tr>
      <td><code>feoobft</code></td>
      <td>Failed exchange of Password and OOB Challenge for Access Token</td>
    </tr>

    <tr>
      <td><code>feotpft</code></td>
      <td>Failed exchange of Password and OTP Challenge for Access Token</td>
    </tr>

    <tr>
      <td><code>fepft</code></td>
      <td>Failed exchange of Password for Access Token</td>
    </tr>

    <tr>
      <td><code>fepotpft</code></td>
      <td>Failed exchange of Passwordless OTP for Access Token</td>
    </tr>

    <tr>
      <td><code>fercft</code></td>
      <td>Failed exchange of Password and MFA Recovery code for Access Token</td>
    </tr>

    <tr>
      <td><code>ferrt</code></td>
      <td>Failed exchange of Rotating Refresh Token</td>
    </tr>

    <tr>
      <td><code>fertft</code></td>
      <td>Failed exchange of Refresh Token for Access Token</td>
    </tr>
  </tbody>
</table>

### Token Exchange - Success

<table>
  <thead>
    <tr>
      <th><strong>Event Code</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>seacft</code></td>
      <td>Successful exchange of Authorization Code for Access Token</td>
    </tr>

    <tr>
      <td><code>seccft</code></td>
      <td>Successful exchange of Access Token for a Client Credentials Grant</td>
    </tr>

    <tr>
      <td><code>sede</code></td>
      <td>Successful exchange of Device Code for Access Token</td>
    </tr>

    <tr>
      <td><code>seoobft</code></td>
      <td>Successful exchange of Password and OOB Challenge for Access Token</td>
    </tr>

    <tr>
      <td><code>seotpft</code></td>
      <td>Successful exchange of Password and OTP Challenge for Access Token</td>
    </tr>

    <tr>
      <td><code>sepft</code></td>
      <td>Successful exchange of Password for Access Token</td>
    </tr>

    <tr>
      <td><code>sercft</code></td>
      <td>Successful exchange of Password and MFA Recovery code for Access Token</td>
    </tr>

    <tr>
      <td><code>sertft</code></td>
      <td>Successful exchange of Refresh Token for Access Token</td>
    </tr>
  </tbody>
</table>

## Management API event filters

<table>
  <thead>
    <tr>
      <th><strong>Filter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Management API - Failure</td>
      <td>Failed Management API events</td>
    </tr>

    <tr>
      <td>Management API - Success</td>
      <td>Successful Management API events</td>
    </tr>
  </tbody>
</table>

### Management API - Success

<table>
  <thead>
    <tr>
      <th><strong>Event Code</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>sapi</code></td>
      <td>Successful Management API operation</td>
    </tr>

    <tr>
      <td><code>mgmt\_api\_read</code></td>
      <td>API GET operation returning secrets completed successfully</td>
    </tr>
  </tbody>
</table>

## System event filters

<table>
  <thead>
    <tr>
      <th><strong>Filter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>System - Notification</td>
      <td>System notification events</td>
    </tr>
  </tbody>
</table>

### System - Notification

<table>
  <thead>
    <tr>
      <th><strong>Event Code</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>admin\_update\_launch</code></td>
      <td>Auth0 Update Launched</td>
    </tr>

    <tr>
      <td><code>api\_limit</code></td>
      <td>The maximum number of requests to the Authentication or Management APIs in given time has reached</td>
    </tr>

    <tr>
      <td><code>coff</code></td>
      <td>AD/LDAP Connector is offline</td>
    </tr>

    <tr>
      <td><code>con</code></td>
      <td>AD/LDAP Connector is online and working</td>
    </tr>

    <tr>
      <td><code>depnote</code></td>
      <td>Deprecation Notice</td>
    </tr>

    <tr>
      <td><code>fcpro</code></td>
      <td>Failed to provision a AD/LDAP connector</td>
    </tr>

    <tr>
      <td><code>fui</code></td>
      <td>Failed to import users</td>
    </tr>

    <tr>
      <td><code>limit\_delegation</code></td>
      <td>Rate limit exceeded to <code>/delegation</code> endpoint</td>
    </tr>

    <tr>
      <td><code>limit\_mu</code></td>
      <td>An IP address is blocked with 100 failed login attempts using different usernames, all with incorrect passwords in 24 hours, or 50 sign-up attempts per minute from the same IP address</td>
    </tr>

    <tr>
      <td><code>limit\_wc</code></td>
      <td>An IP address is blocked with 10 failed login attempts into a single account from the same IP address</td>
    </tr>

    <tr>
      <td><code>sys\_os\_update\_start</code></td>
      <td>Auth0 OS Update Started</td>
    </tr>

    <tr>
      <td><code>sys\_os\_update\_end</code></td>
      <td>Auth0 OS Update Ended</td>
    </tr>

    <tr>
      <td><code>sys\_update\_start</code></td>
      <td>Auth0 Update Started</td>
    </tr>

    <tr>
      <td><code>sys\_update\_end</code></td>
      <td>Auth0 Update Ended</td>
    </tr>
  </tbody>
</table>

## User/Behavioral event filters

<table>
  <thead>
    <tr>
      <th><strong>Filter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>User/Behavioral - Failure</td>
      <td>Failed user/behavioral events</td>
    </tr>

    <tr>
      <td>User/Behavioral - Notification</td>
      <td>User/behavioral notification events</td>
    </tr>

    <tr>
      <td>User/Behavioral - Success</td>
      <td>Successful user/behavioral events</td>
    </tr>
  </tbody>
</table>

### User/Behavioral - Failure

<table>
  <thead>
    <tr>
      <th><strong>Event Code</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>fce</code></td>
      <td>Failed to change user email</td>
    </tr>

    <tr>
      <td><code>fcp</code></td>
      <td>Failed to change password</td>
    </tr>

    <tr>
      <td><code>fcpn</code></td>
      <td>Failed to change phone number</td>
    </tr>

    <tr>
      <td><code>fcpr</code></td>
      <td>Failed change password request</td>
    </tr>

    <tr>
      <td><code>fcu</code></td>
      <td>Failed to change username</td>
    </tr>

    <tr>
      <td><code>fd</code></td>
      <td>Failed to generate delegation token</td>
    </tr>

    <tr>
      <td><code>fdeaz</code></td>
      <td>Device authorization request failed</td>
    </tr>

    <tr>
      <td><code>fdecc</code></td>
      <td>User did not confirm device</td>
    </tr>

    <tr>
      <td><code>fdu</code></td>
      <td>Failed user deletion</td>
    </tr>

    <tr>
      <td><code>fn</code></td>
      <td>Failed to send email notification</td>
    </tr>

    <tr>
      <td><code>fv</code></td>
      <td>Failed to send verification email</td>
    </tr>

    <tr>
      <td><code>fvr</code></td>
      <td>Failed to process verification email request</td>
    </tr>

    <tr>
      <td><code>ss\_sso\_failure</code></td>
      <td>Failed SS-SSO operation</td>
    </tr>
  </tbody>
</table>

### User/Behavioral - Notification

<table>
  <thead>
    <tr>
      <th><strong>Event Code</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>cs</code></td>
      <td>Passwordless login code has been sent</td>
    </tr>

    <tr>
      <td><code>gd\_enrollment\_complete</code></td>
      <td>A first time MFA user has successfully enrolled using one of the factors</td>
    </tr>

    <tr>
      <td><code>gd\_start\_enroll</code></td>
      <td>Multi-factor authentication enroll has started</td>
    </tr>

    <tr>
      <td><code>gd\_unenroll</code></td>
      <td>Device used for second factor authentication has been unenrolled</td>
    </tr>

    <tr>
      <td><code>gd\_update\_device\_account</code></td>
      <td>Device used for second factor authentication has been updated</td>
    </tr>

    <tr>
      <td><code>ss\_sso\_info</code></td>
      <td>Information from an SSO operation</td>
    </tr>

    <tr>
      <td><code>ublkdu</code></td>
      <td>User block setup by anomaly detection has been released</td>
    </tr>
  </tbody>
</table>

### User/Behavioral - Success

<table>
  <thead>
    <tr>
      <th><strong>Event Code</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>sce</code></td>
      <td>Successfully changed user email</td>
    </tr>

    <tr>
      <td><code>scp</code></td>
      <td>Successfully changed password</td>
    </tr>

    <tr>
      <td><code>scpn</code></td>
      <td>Successfully changed phone number</td>
    </tr>

    <tr>
      <td><code>scpr</code></td>
      <td>Successful change password request</td>
    </tr>

    <tr>
      <td><code>scu</code></td>
      <td>Successfully changed username</td>
    </tr>

    <tr>
      <td><code>sdu</code></td>
      <td>User successfully deleted</td>
    </tr>

    <tr>
      <td><code>srrt</code></td>
      <td>Successfully revoked a Refresh Token</td>
    </tr>

    <tr>
      <td><code>ss\_sso\_success</code></td>
      <td>Sucessfully completed an SSO operation</td>
    </tr>

    <tr>
      <td><code>sui</code></td>
      <td>Successfully imported users</td>
    </tr>

    <tr>
      <td><code>sv</code></td>
      <td>Successfully consumed email verification link</td>
    </tr>

    <tr>
      <td><code>svr</code></td>
      <td>Successfully called verification email endpoint, verification email in queue.</td>
    </tr>
  </tbody>
</table>

## Other

### SCIM Events

<table>
  <thead>
    <tr>
      <th><strong>Event Code</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>sscim</code></td>
      <td>Successful SCIM operation</td>
    </tr>

    <tr>
      <td><code>fscim</code></td>
      <td>Failed SCIM operation</td>
    </tr>
  </tbody>
</table>

### Other Events

This category contains unclassified events.


# Integrated Log Streaming Services
Source: https://auth0.com/docs/customize/log-streams/integrate-log-stream-service





# Use Auth0 App for Splunk
Source: https://auth0.com/docs/customize/log-streams/splunk-dashboard

Learn how to use the Auth0 App for Splunk to create a Splunk Auth0 dashboard to visualize your tenant traffic.

<Card title="Before you start">
  [Configure log streaming to Splunk](https://marketplace.auth0.com/integrations/splunk-log-streaming)
</Card>

You can use the **Auth0 App for Splunk** to visualize the data from your Auth0 tenant in a Splunk dashboard. The dashboard allows you to monitor the health of the login traffic for a tenant. The app allows you to use recommended aggregations from Auth0, or to use them as a starting point to create your own custom visualizations.

## Install the Auth0 App for Splunk

1. Log into [Splunk](https://www.splunk.com/).
2. Navigate to the [Auth0 App for Splunk](https://splunkbase.splunk.com/app/5193) app page.
3. Select the green **Install** button.
4. Enter your username and password, accept the terms and conditions, and select **Login and Install**.
5. On the **Complete** widget that results, select the **Open the App** button.
   The Auth0 Dashboard with default filters applied appears.

## Dashboard filters

The following filters exist to allow you to drill down into the specifics of your traffic. You can enter `*` to search across all values for that field.

<table>
  <thead>
    <tr>
      <th>Filter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Time Range</td>
      <td>A Splunk time input element that lets you choose the duration over which to view events.</td>
    </tr>

    <tr>
      <td>Index</td>
      <td>The Splunk <code>index</code> you want to search within. While creating your <code>Http Event Collector Token</code>, if you specified a particular index, you may use this value from the dropdown.</td>
    </tr>

    <tr>
      <td>HTTP Source</td>
      <td>The Splunk <code>source</code> name.</td>
    </tr>

    <tr>
      <td>IP</td>
      <td>The IP address whose traffic you want to inspect. This maps to <code>data.ip</code> in the log event.</td>
    </tr>

    <tr>
      <td>Client</td>
      <td>The client whose traffic you want to inspect. This maps to <code>data.client\_name</code> in the log event.</td>
    </tr>

    <tr>
      <td>Country</td>
      <td>The country whose traffic you want to inspect. This is a field obtained using the <code>iplocation data.ip</code> search command in the query. It results in a <code>Country</code> field being added to each log event.</td>
    </tr>

    <tr>
      <td>Username</td>
      <td>The email address whose login traffic you want to inspect. This maps to <code>data.user\_name</code> in the log event.</td>
    </tr>
  </tbody>
</table>

## Customize dashboard

You can customize your Splunk Auth0 security dashboard to add custom data widgets.

1. Navigate to your Auth0 security dashboard and select **edit** in the top right corner.
2. In the Edit Dashboard panel, select **add panel** and then choose a content type. For example line chart, event, or area chart.
3. Enter the time range, content title, and search string for the data visualization.
4. Select **Add to dashboard** to add your new data widget.

## Learn more

* [View Attack Protection Log Events](/docs/secure/attack-protection/view-attack-protection-events)


# Use Auth0 App for Sumo Logic
Source: https://auth0.com/docs/customize/log-streams/sumo-logic-dashboard

Describes how to use the Auth0 App for Sumo Logic to create a Sumo Logic Auth0 dashboard to visualize your tenant traffic.

You can use the **Auth0 App for Sumo Logic** to visualize the data from your Auth0 tenant in a Sumo Logic dashboard. The dashboard allows you to monitor the health of the login traffic for a tenant. The app allows you to use recommended aggregations from Auth0, or to use them as a starting point to create your own custom visualizations.

## Prerequisite

[Set up log streaming to Sumo Logic](https://marketplace.auth0.com/integrations/sumo-logic-log-streaming).

## Install the Auth0 App for Sumo Logic

1. Log in to [Sumo Logic](https://www.sumologic.com).
2. From the **App Catalog**, search for and select the Auth0 app.
3. To install the app, complete the following fields:

   <table>
     <thead>
       <tr>
         <th><strong>Field</strong></th>
         <th><strong>Description</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td><strong>App Name</strong></td>
         <td>Retain the existing name or enter a name of your choice.</td>
       </tr>

       <tr>
         <td><strong>Data Source</strong></td>
         <td>Choose <strong>Source Category</strong> and select a category from the list, or choose <strong>Enter a Custom Data Filter</strong> and enter a custom source category beginning with an underscore. For example: <strong><em>sourceCategory=MyCategory</em></strong>.</td>
       </tr>

       <tr>
         <td><strong>Advanced</strong></td>
         <td>Select the <strong>Location in Library</strong> (default is Personal folder) or click <strong>New Folder</strong> to add a new folder.</td>
       </tr>
     </tbody>
   </table>
4. Select **Add to Library**.

Once an app is installed, it appears in your **Personal** folder or the folder you selected. From here, you can share it with your organization.

Panels will fill automatically over time. Panels fill slowly fills with data matching the time range query and received since the panel was created.

<Frame>
  <img alt="Sumo Logic Dashboard with Auth0 streaming data" />
</Frame>

The dashboard is broken down into the following categories or panels:

* **Login Metrics**: See the count of actions such as successful logins and failed logins.
* **Account Creation Metrics**: See the breakdowns of account creation by country, platform, IP, and other demographics.
* **Security Metrics**: See anomaly detection events over time to detect and attack.

## Dashboard filters

Each dashboard has a set of filters that you can apply to the entire dashboard. Click the funnel icon in the top dashboard menu bar to display a scrollable list of filters that are applied across the entire dashboard.

Each panel also has a set of filters that are applied to the results for that panel only. Click the funnel icon in the top panel menu bar to display a list of panel-specific filters.

## Customize dashboard

You can customize your Sumo Logic Auth0 security dashboard to add custom data widgets.

1. Navigate to your Auth0 security dashboard and select **add panel** in the top right corner.
2. Select a panel type by clicking the icon. See [Sumo Logic help](https://help.sumologic.com/Visualizations-and-Alerts/Dashboard_\(New\)/Panels) for details.
3. Enter logs query, metrics query, or multiple queries from the drop-down.
4. To change the chart type, see [Sumo Logic help](https://help.sumologic.com/Visualizations-and-Alerts/Dashboard_\(New\)/Panels/01Modify_a_Chart) for the available options.
5. Click **Add to Dashboard** on the top right to add the panel to your dashboard.

## Learn more

* [Log Type Codes](/docs/deploy-monitor/logs/log-event-type-codes)
* [View Attack Protection Log Events](/docs/secure/attack-protection/view-attack-protection-events)


# Secure
Source: https://auth0.com/docs/secure

Learn about various security-related issues, such as handling tokens, preventing security attacks, AllowListing, data privacy, and Auth0 security bulletins

<AuthDocsPipeline />

Auth0 provides critical tools for securing your applications against people who are interested in attacking information technology systems. Multi-factor authentication (MFA) reduces risk by requiring more than one type of user validation, while attack protection features automatically detect and respond to malicious behavior such as rapid, repeated failed logins or one IP address rapidly attempting to log into multiple accounts.

Auth0 maintains and meets the requirements for multiple compliance frameworks and certifications including GDPR and HIPAA.

***

## Protect Your Application

##### Make sure only the right people can access your applications.

<Card title="Application Credentials" href="/docs/secure/application-credentials">
  This section contains information about credentials for your application to authenticate.
</Card>

<Card title="Attack Protection" href="/docs/secure/attack-protection">
  Detect attacks and stop malicious attempts to access your applications.
</Card>

<Card title="Continuous Session Protection" href="/docs/secure/continuous-session-protection">
  Enhance security and tailor the user experience through customizable session and refresh token management.
</Card>

<Card title="Auth0’s Mobile Driver's License Verification Service" href="/docs/secure/mdl-verification">
  Learn about Auth0's Mobile Driver's License Verifiable Credential service.
</Card>

<Card title="Multi-Factor Authentication" href="/docs/secure/multi-factor-authentication">
  Add additional checks to ensure passwords match up with the identity of the user or device accessing your applications.
</Card>

<Card title="Security Center" href="/docs/secure/security-center">
  Observe potential attack trends and quickly respond to them in real-time.
</Card>

<Card title="Security Guidance" href="/docs/secure/security-guidance">
  View security bulletins and learn basic tips to secure data and accounts.
</Card>

<Card title="Sender Constraining" href="/docs/secure/sender-constraining">
  Learn how to sender constrain tokens in Auth0.
</Card>

<Card title="Tokens" href="/docs/secure/tokens">
  Explore the types of tokens related to identity and authentication and how they are used by Auth0.
</Card>

***

## Protect Your Tenant

##### Learn how to protect your tenant and rate limits.

<Card title="Tenant Access Control List" href="/docs/secure/tenant-access-control-list">
  Learn how to protect your tenant from unwanted traffic with Tenant Access Control Lists (ACL).
</Card>

***

## Compliance

##### Learn how Auth0 supports compliance frameworks such as GDPR and HIPAA.

<Card title="Data Privacy and Compliance" href="/docs/secure/data-privacy-and-compliance">
  Read about Auth0’s compliance qualifications and data processing.
</Card>


# Application Credentials
Source: https://auth0.com/docs/secure/application-credentials

Describes ways you can authenticate your application with Auth0 services.

Confidential applications, unlike public applications, can securely store credentials. When confidential applications request access or <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip> from the [token endpoint](https://auth0.com/docs/api/authentication#get-token), the application must authenticate with the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip>. During this request for tokens, the application provides credentials known by the application. Additionally, application credentials can also provide authenticity and integrity protection for request parameters sent to the [`/authorize`](https://auth0.com/docs/api/authentication#authorize-application) endpoint.

To learn more about confidential applications versus public applications, read [Confidential and Public Applications](/docs/get-started/applications/confidential-and-public-applications).

## Application authentication methods

To get tokens from Auth0, your application must authenticate through the [Authentication API](https://auth0.com/docs/api/authentication). Auth0 supports the following ways your application can authenticate:

* **<Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip>:** A symmetrical authentication method. In Client Secret authentication, you use the Client Secret Auth0 generated when you created the application.
* **Private Key <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip>:** An asymmetric authentication method. In Private Key JWT, you generate a pair of keys, public and private, to use as credentials. You provide the public key and securely store the private key in your own systems without sharing it with Auth0.
* **mTLS for <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip>:** An asymmetric authentication method. In mTLS for OAuth, you register a standard X.509 client certificate with Auth0. Then, you use the corresponding private key to securely establish the mTLS tunnel to send requests to your Auth0 tenant endpoints.

### Client Secret authentication

Client Secret authentication is a symmetric authentication method included in the [OAuth 2.0 specification](https://www.rfc-editor.org/rfc/rfc6749#section-2.3). Client Secret authentication is the default authentication method in Auth0.

This authentication method is supported by all existing applications and tooling. The Client Secret is a high-entropy value generated by Auth0 when you create an application and is known by both your application and Auth0. Your application authenticates by including the Client Secret in the request to the authorization server.

Some security risks are associated with using Client Secret as a credential, especially for scenarios with higher security demands:

* The secret used by the application is shared with Auth0.
* The secret is sent over the network and could be intercepted in the case of man-in-the-middle attacks.

<Warning>
  To ​​improve your security posture, we recommend using the Private Key JWT authentication method.
</Warning>

An application can have a single Client Secret. It is not possible to rotate the secret while you update your implementation with the new secret. To learn more, read [Rotate Client Secrets](/docs/get-started/applications/rotate-client-secret).

### Private Key JWT authentication

<Callout icon="file-lines">
  Private Key JWT is available for customers on the Enterprise plan. To upgrade, contact [Auth0 pricing](https://auth0.com/pricing/).
</Callout>

Private Key JWT authentication is an asymmetric authentication method that relies on private and public key pairs. To learn more, read [JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants](http://tools.ietf.org/html/draft-ietf-oauth-jwt-bearer).

You can use the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to configure a tenant to use Private Key JWT. To learn more, read [Configure Private Key JWT Authentication.](/docs/get-started/applications/configure-private-key-jwt)

In Private Key JWT, a request to the authorization server consists of two main steps:

1. Configure public and private keys:

   1. [Generate a key pair](/docs/secure/application-credentials/generate-rsa-key-pair) (one public key and one private key).
   2. Register the private key with the application making the authentication request and register the public key with the identity provider (IdP).
2. Build an assertions for requests to the authorization server:

   1. Create a new assertion with specified claims in JWT format and sign it with the private key. Include this assertion as part of the request to the IdP.
   2. IdP validates the assertion using the public key.

To configure Private Key JWT for Auth0, read [Configure Private Key JWT Authentication](/docs/get-started/applications/configure-private-key-jwt). To learn more about building an assertion for Private Key JWT, read [Authenticate with Private Key JWT](/docs/get-started/authentication-and-authorization-flow/authenticate-with-private-key-jwt).

There are some security benefits associated with using Private Key JWT:

* The private key is not transmitted over the network and reduces the exposure risk of your application’s credentials. <Tooltip href="/docs/glossary?term=Identity+providers">Identity providers</Tooltip> like Auth0 have no knowledge of the private key, and only applications that have access to the private key can create authentication requests.
* The signed assertions have a short expiry time, limiting the window of opportunity for replay attacks.

### mTLS for OAuth

<Callout icon="file-lines">
  To use Highly Regulated Identity features, you must have an Enterprise Plan with the Highly Regulated Identity add-on. Refer to [Auth0 Pricing](https://auth0.com/pricing/) for details.
</Callout>

[mTLS for OAuth](https://www.rfc-editor.org/rfc/rfc8705) authenticates requests to the authorization server using mutual TLS based on self-signed certificates or public key infrastructure (PKI). Read [Authenticate with mTLS](/docs/get-started/authentication-and-authorization-flow/authenticate-with-mtls) to learn more about how mTLS authentication works at Auth0.

Auth0’s mTLS for OAuth initially targets customers in highly regulated sectors such as finance and healthcare that most likely already have mTLS deployments. To simplify customer adoption, the mTLS feature builds on [custom domains](/docs/customize/custom-domains) and leverages the customer’s existing mTLS infrastructure to perform certificate provisioning and verification. To learn more about authenticating with mTLS and setting up your edge network, read [Authenticate with mTLS](/docs/get-started/authentication-and-authorization-flow/authenticate-with-mtls) and [Set up your customer edge](/docs/get-started/applications/configure-mtls/set-up-the-customer-edge).

<Callout icon="file-lines">
  You can set up [mTLS endpoint aliases](/docs/get-started/applications/configure-mtls/configure-mtls-for-a-tenant#enable-mtls-endpoint-aliases) to use a specific subdomain for mTLS for OAuth.
</Callout>

To learn how to configure mTLS, read [Configure mTLS Authentication](/docs/get-started/applications/configure-mtls). Once you have set up your edge network and configured mTLS, your application needs to establish the mTLS tunnel to send requests to Auth0, as explained in [Call the authorization server](/docs/get-started/authentication-and-authorization-flow/authenticate-with-mtls#call-the-authorization-server).

In mTLS, the client certificate’s private key is not transmitted over the network, reducing the risk of exposing your application credentials. Identity providers like Auth0 do not have access to the private key. Only applications that have access to the private key can authenticate.

<Callout icon="file-lines">
  mTLS also supports Sender Constraining or Token Binding to protect access tokens from attackers. To learn more, read [Configure Sender Constraining](/docs/secure/sender-constraining/configure-sender-constraining). Token Binding does not require previously registered application credentials such as a client certificate for use with mTLS.
</Callout>

### JWT-Secured Authorization Request (JAR)

<Callout icon="file-lines">
  To use Highly Regulated Identity features, you must have an Enterprise Plan with the Highly Regulated Identity add-on. Refer to [Auth0 Pricing](https://auth0.com/pricing/) for details.
</Callout>

[JWT-Secured Authorization Request (JAR)](https://datatracker.ietf.org/doc/rfc9101/) is an OAuth2 protocol extension that enhances the security of authorization requests. It does so by using a JSON Web Token (JWT) request parameter to protect the integrity and confidentiality of the authorization request parameters.

You can use the [Auth0 Management API](https://auth0.com/docs/api/management/v2) to configure JAR for your application. Auth0 implementation for JAR uses asymmetric cryptography, where you register the public key while securely storing the private key on your end. To learn more, read [Configure JWT-Secured Authorization Requests](/docs/get-started/applications/configure-jar).

When using JAR, the client creates a JWT that includes the authorization request parameters, signs it with its private key, and sends it to the authorization server. The authorization server then verifies the signature using the client's public key, and if the signature is valid, extracts the authorization request parameters from the JWT and processes the request as usual. To learn more about how to use JAR, read [Authorization Code Flow with JWT-Secured Authorization Requests (JAR)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-jar).

### Key and certificate registration

<Warning>
  You should generate a separate key pair for each type of credential usage. For example, do not reuse the same key pairs for both JAR and Private Key JWT Authentication.
</Warning>

You can register two public keys for an application at the same time. Auth0 handles verification against the proper key and allows you to rotate with no downtime. Once the old key has been removed or deactivated, all requests signed with the corresponding private key are invalidated.

**Note:** Auth0 supports the following algorithms for application authentication and authorization request signing: RS256, RS384 and PS256. Please make sure to provide the appropriate keys for them. To learn more, read [Configure Private JWT Authentication](/docs/get-started/applications/configure-private-key-jwt) and [Configure JWT-Secured Authorization Requests](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-jar).

Similarly, for mTLS client certificates, you can register two client X.509 certificates (self-signed or with the CA cert’s Subject DN) at the same time for an application. Auth0 handles verification against both client certificates, which allows you to rotate certificates with zero downtime.

## Update application authentication method

You can update an application’s authentication method in the Auth0 Dashboard. To learn more, read [Credential Settings](/docs/get-started/applications/credentials).

## Learn more

* [Credential Settings](/docs/get-started/applications/credentials)
* [Authenticate with Private Key JWT](/docs/get-started/authentication-and-authorization-flow/authenticate-with-private-key-jwt)
* [Rotate Credentials](/docs/get-started/applications/rotate-credentials)
* [Configure Private Key JWT Authentication](/docs/get-started/applications/configure-private-key-jwt)
* [Authenticate with mTLS](/docs/get-started/authentication-and-authorization-flow/authenticate-with-mtls)


# Generate RSA Key Pair
Source: https://auth0.com/docs/secure/application-credentials/generate-rsa-key-pair

Learn how to generate a RSA key pair.

<Warning>
  You should generate a separate key pair for each type of credential usage. For example, do not reuse the same key pairs for both JAR and Private Key JWT Authentication.
</Warning>

When you register the public key with Auth0, you must provide the public key encoded in PEM format. You may provide this as an X.509 certificate encoded in PEM format. Auth0 enforces a minimum RSA key size of 2048 bits and a maximum key size of 4096 bits. We recommend using [OpenSSL](https://www.openssl.org/) to generate a 2048-bit RSA key pair.

1. Generate a private key and a public key in PEM. You should safeguard the private key and never share it, not even with Auth0:

`openssl genrsa -out test_key.pem 2048`

2. Extract the public key in PEM format using the following command. This command extracts the public key details so it can be safely shared without revealing the details of the private key:

`openssl rsa -in test_key.pem -outform PEM -pubout -out test_key.pem.pub`

The example below shows the contents of the `test_key.pem.pub` PEM file:

```pem wrap lines theme={null}
----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA53VzmIVVZZWyNm266l82 mnoDc9g/snXklax5kChEhqK/WnTUvuXP4Gd4THj8rchxgUGKXd4PF3SUcKyn/qPm Tet0idVHk2PwP//FOVgYo5Lb04js0pgZkbyB/WjuMp1w+yMuSn0NYAP7Q9U7DfTb jmox8OQt4tCB4m7UrJghGqT8jkPyZO/Ka6/XsyjTYPOUL3t3PD7JShVAgo1mAY6g Sr4SORywIiuHsg+59ad7MXGy78LirhtqAcDECKF7VZpxMuEjMLg3o2yzNUeWI2Mg IF+t0HbO1E387fvLcuSyai1yWbSr1PXyiB2aXyDpbD4u7d3ux4ahU2opH11lBqvx +wIDAQAB -----END PUBLIC KEY-----
```

3. Save the PEM file. You will need the key contents in other application configuration steps.

## Learn more

* [Authenticate with Private Key JWT](/docs/get-started/authentication-and-authorization-flow/authenticate-with-private-key-jwt)


# Attack Protection
Source: https://auth0.com/docs/secure/attack-protection

Describes how Auth0 detects attacks to stop malicious attempts to access your application, alert you and your users of suspicious activity, and block further login attempts.

Auth0 can detect attacks and stop malicious attempts to access your application such as blocking traffic from certain IPs and displaying CAPTCHA.

In the [Auth0 Dashboard](https://manage.auth0.com/#/security/attack-protection), you can enable the following <Tooltip href="/docs/glossary?term=attack+protection">attack protection</Tooltip> options to mitigate attacks:

* [Bot Detection](/docs/secure/attack-protection/bot-detection)
* [Suspicious IP Throttling](/docs/secure/attack-protection/suspicious-ip-throttling)
* [Brute Force Protection](/docs/secure/attack-protection/brute-force-protection)
* [Breached Password Detection](/docs/secure/attack-protection/breached-password-detection)

<Frame>
  <img alt="Dashboard Security Attack Protection page" />
</Frame>

## How it works

When it comes to combatting abuse, there is no silver bullet. Auth0 supports the principle of layered protection in security that uses a variety of signals to detect and mitigate attacks.

<table>
  <thead>
    <tr>
      <th><strong>Feature</strong></th>
      <th><strong>Risk signal</strong></th>
      <th><strong>How it works</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Bot Detection</td>
      <td><strong>IP reputation</strong> computed by analyzing the quality of traffic seen for each IP.</td>
      <td>Triggers a CAPTCHA step when a login attempt comes from an IP suspected of use by a bot.</td>
    </tr>

    <tr>
      <td>Suspicious IP Throttling</td>
      <td><strong>Velocity</strong> of login attempts from an IP for any number of accounts against a tenant.</td>
      <td>Detects when a bot/script tries too many identifier/password combinations within a short period of time.</td>
    </tr>

    <tr>
      <td>Brute-force Protection</td>
      <td><strong>Velocity</strong> of login attempts from an IP for a particular account.</td>
      <td>Detects when a bad actor tries to login to an account too many times within a period of time.</td>
    </tr>

    <tr>
      <td>Breached Password Detection</td>
      <td><strong>Use of a breached password</strong> that appears in lists of breached passwords on the dark web.</td>
      <td>Stops users from using passwords that are known to be breached in some third-party sites.</td>
    </tr>
  </tbody>
</table>

## Notification

In the event of an attack, users will be notified by email once per hour regardless of the number of logins. For example, if a user tries to log in 200 times in 1 hour and 30 minutes, we will send 2 emails. Password reset links are valid for 5 days. You can [customize the emails](/docs/customize/email/customize-blocked-account-emails) sent to your users.

<Callout icon="file-lines">
  If you reset the block and it encounters another attack, it will send another email.
</Callout>

In the event of an ongoing attack, traffic can be blocked from thousands of IP addresses at a time. Auth0 will send a single email to each administrator every hour that traffic is blocked, regardless of the number of IPs involved in the attack.

## Monitoring

Enabling attack protection features without configuring response settings activates Monitoring mode, which records related events in your tenant log only. The tenant log will contain information about whether the login was determined to be risky so you can determine if you want to configure responses.

## Reporting

You can also create reports using tenant log data to [see attack protection events](/docs/secure/attack-protection/view-attack-protection-events).

## Learn more

* [Bot Detection](/docs/secure/attack-protection/bot-detection)
* [Suspicious IP Throttling](/docs/secure/attack-protection/suspicious-ip-throttling)
* [Brute-Force Protection](/docs/secure/attack-protection/brute-force-protection)
* [Breached Password Detection](/docs/secure/attack-protection/breached-password-detection)
* [View Attack Protection Log Events](/docs/secure/attack-protection/view-attack-protection-events)


# Bot Detection
Source: https://auth0.com/docs/secure/attack-protection/bot-detection

Describes how Auth0 detects attacks to protect against malicious attempts to access your application, alert you and your users of suspicious activity, and block further login attempts.

<Card title="Before you start">
  To use one of the supported third-party CAPTCHA provider integrations, you need the provider’s configuration details. To learn more, read [Configure third-party CAPTCHA provider integrations](/docs/secure/attack-protection/bot-detection/configure-captcha).
</Card>

<Tooltip href="/docs/glossary?term=Bot+Detection">Bot Detection</Tooltip> mitigates scripted attacks by detecting when a request is likely coming from a bot. These types of attacks are sometimes called credential stuffing attacks or list validation attacks. Bot Detection provides support against certain attacks and adds very little friction to legitimate users. Auth Challenge is our default bot detection response, which provides a CAPTCHA-free user verification.

To learn more, read [Credential Stuffing Attacks: What Are They and How to Combat Them](https://auth0.com/resources/whitepapers/credential-stuffing-attacks).

Auth0 uses a large amount of data and statistical models to identify patterns that signal when bursts of login, signup, or password reset traffic are likely from a bot or script. Users who attempt to log in, create accounts, or reset passwords from IP addresses that have a high likelihood of being part of a credential stuffing attack are required to complete an additional verification step. The triggers detect traffic relating to these attacks without adding unnecessary friction to legitimate users.

## Configure Bot Detection

When enabled, you can customize Bot Detection preferences, such as the detection model, and response actions, which applies to all connections in your tenant.

If you do not configure **Response** actions with Bot Detection enabled, Bot Detection operates in [Monitoring](/docs/secure/attack-protection#monitoring) mode. Monitoring mode records related events, including risk assessment details, in your tenant logs for review. To learn more, read [View Attack Protection Log Events](/docs/secure/attack-protection/view-attack-protection-events).

You can enable tenant logs for Risk Assessment in the [Auth0 Dashboard](https://manage.auth0.com/#).

1. Go to [Dashboard > Security > Attack Protection](https://manage.auth0.com/#/security/attack-protection) and select **Bot Detection**.
2. In the **Detection** section, enable the toggle.

   <Frame>
     <img alt="Detection section of the Attack protection screen" />
   </Frame>

   <Callout icon="file-lines">
     If you cannot see the toggle to enable tenant logs for Risk Assessment, you may need to [upgrade your plan](https://manage.auth0.com/#/tenant/billing/subscription).
   </Callout>
3. In the **Response** section, choose a bot detection response.

   <Frame>
     <img alt="Dashboard - Attack Protection - Bot Detection" />
   </Frame>

   When using Auth Challenge, the **Fail open** toggle is disabled by default.

   If you enable the **Fail Open** toggle:

   * When the Bot Detection service is unreacheable, Auth0 prioritizes the authentication process and proceeds without a CAPTCHA challenge. End users do not see an error message and can still log in or register.
   * When the Bot Detection service is reachable, the authentication process proceeds with a CAPTCHA challenge.

   <Callout icon="file-lines">
     Auth Challenge is the default bot detection response, offering a CAPTCHA-free web experience with stronger privacy and a better user experience.

     As noted on the dashboard, this login experience requires Javascript; if your login experience is required to work without Javascript, select Simple CAPTCHA.
   </Callout>
4. Select when you want to require CAPTCHA for password flows, passwordless flows, and password reset flows.

   * **Never**: Never require your users to complete a CAPTCHA to log in.
   * **When Risky**: Only require your users to complete a CAPTCHA if the login matches your **Bot Detection Level** setting.
   * **Always**: Always require your users to complete a CAPTCHA to log in.
5. If you choose **When Risky** or **Always**, the **CAPTCHA Providers** field will appear in the **Response** section. Select **Auth Challenge** (provided by Auth0), **Simple CAPTCHA** (provided by Auth0), or one of the supported third-party provider integrations (requires external setup and registration).

   * If you choose **Auth Challenge** or **Simple CAPTCHA**, you are done. If your login experience does not support JavaScript, you must select **Simple CAPTCHA**.
   * If you choose one of our third-party provider integrations, enter the provider’s configuration details. To learn more, read [Configure third-party CAPTCHA provider integrations](/docs/secure/attack-protection/bot-detection/configure-captcha).
   * If you choose **Simple CAPTCHA,** the CAPTCHA image is not legible to screen readers.
6. If you choose **When Risky**, the **Bot Detection Level** field will appear in the **Response** section. Select the security level that best fits your use case. For more information, read [Configure Bot Detection Level](/docs/secure/attack-protection/bot-detection#configure-bot-detection-level).
7. Select **Save**.

## Configure Bot Detection Level

Configure the **Bot Detection Level** setting to match your risk tolerance and business needs.

There are three settings to choose from:

1. **Low**: Triggers CAPTCHA when there is a high chance of bot activity, providing a relatively frictionless experience for real users.
2. **Medium**: Default. Triggers CAPTCHA when there is a moderate chance of bot activity, providing a balance of security and experience for real users.
3. **High**: Triggers CAPTCHA when there is a small chance of bot activity, providing more security but potentially more friction for real users.

<Frame>
  <img alt="Auth0 Dashboard > Security > Attack Protection to access this slider" />
</Frame>

## Allow trusted IP addresses to bypass Bot Detection

You can allow up to 100 discrete IP addresses and/or CIDR ranges (IPv4 or IPv6) to bypass Bot Detection by adding them to the **IP AllowList** field. Auth0 does not enforce blocking and does not send alerts for IP addresses or CIDR ranges on this list.

1. Go to [Dashboard > Security > Attack Protection](https://manage.auth0.com/#/security/attack-protection), and select **Bot Detection**.
2. In the **IP AllowList** field, enter the IP addresses and/or CIDR ranges you want to bypass Bot Detection. Separate multiple addresses or ranges with commas.

## Configure signup detection model for Custom Login Page and Classic Login Experience

Auth0 provides a signup detection machine-learning model, distinct from the login model, that addresses different attack types by analyzing unique signals.

This model allows CAPTCHA to behave differently between signup and login flows to provide stronger protection against signup attacks and align with the latest security advancements.

<Warning>
  Ensure all applications using [Auth0.js](https://github.com/auth0/auth0.js/) and/or [Lock](https://github.com/auth0/lock) are using the most recent library version(s) before you enable this model:

  * **Auth0.js**: 9.28.0+
  * **Lock**: 13.0+

  If you enable this model while using an outdated library, your application may encounter errors.
</Warning>

You can configure the detection model that Bot Detection uses for signup flows when using a [Custom Login Page](/docs/customize/login-pages) or the [Classic Login Experience](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/classic-experience) in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

1. Go to [Dashboard > Security > Attack Protection](https://manage.auth0.com/#/security/attack-protection), and select **Bot Detection**.
2. Locate the **Detection Models** section.
3. Enable the toggle for **Signup detection models for custom and classic login pages**.

## Restrictions and limitations

### Flow limitations

Bot Detection works for web and mobile applications that use [Auth0 Universal Login](/docs/authenticate/login/auth0-universal-login). For applications that do not use <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>, levels of support are limited, in particular for flows that cannot support a CAPTCHA or reCAPTCHA challenge.

Ensure all of your login experiences are supported before you enable Bot Detection, or you may introduce errors into your application.

<table>
  <thead>
    <tr>
      <th><strong>Flow</strong></th>
      <th><strong>Limitation</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Universal Login</td>
      <td>Supported by default.</td>
    </tr>

    <tr>
      <td>Classic Login (no customizations)</td>
      <td>Supported by default.</td>
    </tr>

    <tr>
      <td>Classic Login (Custom Login Page using <strong>Lock</strong> template)</td>
      <td>Supported if using <code>lock.js</code> SDK version 12.4.0 or higher.</td>
    </tr>

    <tr>
      <td>Classic Login (Custom Login Page using <strong>Custom Login Form</strong> template)</td>
      <td>Supported if using <code>auth0.js</code> SDK version 9.24 or higher, and you enhance your code to handle a CAPTCHA or reCAPTCHA challenge.</td>
    </tr>

    <tr>
      <td>Native applications</td>
      <td>Supported if using one of the following SDKs:<ul><li><code>Auth0.swift</code> version 1.28.0+</li><li><code>Auth0.Android</code> version 1.25.0+</li><li><code>Lock.Swift</code> version 2.19.0+</li><li><code>Lock.Android</code> version 2.22.0+</li></ul></td>
    </tr>

    <tr>
      <td>Regular Web or Native applications using Resource Owner Password Flow</td>
      <td>Supported in a limited capacity. Bot Detection Response such as CAPTCHA requires an interactive flow and therefore is not supported. If the <code>requires\_verification</code> error is returned by the SDK, you must trigger a web-based login flow for the user to complete authentication.</td>
    </tr>

    <tr>
      <td>Flows not hosted by Auth0 using <code>lock.js</code> or <code>auth0.js</code> SDK which perform cross-origin authentication (<code>co/authenticate</code> endpoint)</td>
      <td>Not supported.</td>
    </tr>
  </tbody>
</table>

### Connection type limitations

Depending on the types of connections you use, Bot Detection has the following limitations.

<table>
  <thead>
    <tr>
      <th><strong>Connection Type</strong></th>
      <th><strong>Limitation</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Database</td>
      <td>Supported if the login uses a compatible login flow as described in the Flow limitations table.</td>
    </tr>

    <tr>
      <td>Custom database</td>
      <td>Supported if the login uses a compatible login flow as described in the Flow limitations table.</td>
    </tr>

    <tr>
      <td>Active Directory/LDAP</td>
      <td>Supported if the login uses a compatible login flow as described in the Flow limitations table.</td>
    </tr>

    <tr>
      <td>Enterprise</td>
      <td>Not supported.</td>
    </tr>

    <tr>
      <td>Social Login</td>
      <td>Not supported.</td>
    </tr>

    <tr>
      <td>Passwordless</td>
      <td>Supported if the login uses a compatible login flow as described in the Flow limitations table.</td>
    </tr>
  </tbody>
</table>

### Custom login page support

If you build a custom login page using Auth0.js, you can enable Bot Detection to render a CAPTCHA step in scenarios when a login request is determined by Auth0 to be high-risk.

Your custom login form code must handle scenarios where the user is asked to pass a CAPTCHA step. To learn more, read [Add Bot Detection to Custom Login Pages](/docs/secure/attack-protection/bot-detection/bot-detection-custom-login-pages).

### Native application support

If you build native applications using an Auth0 SDK for the login flow, you can enable Bot Detection to render a CAPTCHA step in scenarios when a login request is determined by Auth0 to be high-risk.

Your custom login form code must handle scenarios where the user is asked to pass a CAPTCHA step. To learn more, read [Add Bot Detection to Native Applications](/docs/secure/attack-protection/bot-detection/bot-detection-native-apps).

## Learn more

* [Configure Third-Party CAPTCHA Provider Integrations](/docs/secure/attack-protection/bot-detection/configure-captcha)
* [Add Bot Detection to Custom Login Pages](/docs/secure/attack-protection/bot-detection/bot-detection-custom-login-pages)
* [Add Bot Detection to Native Applications](/docs/secure/attack-protection/bot-detection/bot-detection-native-apps)
* [Breached Password Detection](/docs/secure/attack-protection/breached-password-detection)
* [Brute-Force Protection](/docs/secure/attack-protection/brute-force-protection)
* [Suspicious IP Throttling](/docs/secure/attack-protection/suspicious-ip-throttling)


# Add Bot Detection to Custom Login Pages
Source: https://auth0.com/docs/secure/attack-protection/bot-detection/bot-detection-custom-login-pages

Learn how to enable and configure bot detection when using custom login pages built with the auth0.js library.

If you build a custom login page using the auth0.js library, you can enable <Tooltip href="/docs/glossary?term=Bot+Detection">Bot Detection</Tooltip> to render a CAPTCHA step in scenarios when a request is determined to be high risk by Auth0.

Your custom login form code must handle scenarios where the user is asked to pass a CAPTCHA step. If you don't account for this scenario, your application may cause an error.

<Callout icon="file-lines">
  Bot detection is only supported for custom login pages hosted by Auth0. You may need to contact your account representative to enable this feature for your tenant.
</Callout>

## Use custom login page template

Auth0 provides a template for you to use with code to handle high-risk logins.

1. Go to [Dashboard > Branding > Universal Login](https://manage.auth0.com/#/login_settings) and select **Classic**.
2. Click the **Login** tab and enable the **Customize Login Page** switch if it is not already enabled.
3. Locate the **Default Templates** drop-down menu and select **Custom Login Form**.

   <Frame>
     <img alt="Dashboard Branding Universal Login Classic Login Tab Custom Login Form" />
   </Frame>
4. Use the provided template to begin customizing your login page.

   <Callout icon="file-lines">
     We recommend using version control software to manage the source code of your Custom Login Pages. To learn more, read [Classic Login Page Version Control](/docs/customize/login-pages/classic-login/version-control).
   </Callout>
5. If you are not using version control software, you can replace the template with your source code directly in the Dashboard.
6. Select **Preview** to see your new form.
7. Select **Save Changes**.

## Customize the login form

If you'd like to support Bot Detection, you must use version `9.28` or higher of the `auth0.js` library.

`<script src="https://cdn.auth0.com/js/auth0/9.28/auth0.min.js"></script>`

1. Add an element to render the CAPTCHA below your password input and above your sign-up and login buttons. For example: `<div class="captcha-container"></div>`

2. Initialize the `loginCaptcha` and `signupCaptcha` components after the `WebAuth` constructor.

   ```javascript lines theme={null}
   var webAuth = new auth0.WebAuth(params);

   var loginCaptcha = webAuth.renderCaptcha(
       document.querySelector('.captcha-container'),
       null,
       (error, payload) => {
           if (payload) {
               triggerCaptcha = payload.triggerCaptcha;
           }
       }
   );

   var signupCaptcha = webAuth.renderSignupCaptcha(
       document.querySelector('.captcha-container'),
       null,
       (error, payload) => {
           if (payload) {
               triggerCaptcha = payload.triggerCaptcha;
           }
       }
   );
   ```

3. When you call the `login` method, assign the `captcha` property the value `loginCaptcha.getValue()`:

   ```text lines theme={null}
   webAuth.login({
       realm: connection,
       username: username,
       password: password,
       captcha: loginCaptcha.getValue()
   }, function(err) {
       displayError(err);
       //...
   });
   ```

   To learn more about the `login` method’s callback function parameter (`cb`), read [WebAuth on auth0.js documentation](https://auth0.github.io/auth0.js/global.html#login).

4. When you call the `signupAndLogin` method, assign the `captcha` property the value `signupCaptcha.getValue()`:

   ```text lines theme={null}
   webAuth.redirect.signupAndLogin({
       connection: databaseConnection,
       email: email,
       password: password,
       captcha: signupCaptcha.getValue()
   }, function(err) {
       displayError(err);
       //...
   });
   ```

   To learn more about the `signupAndLogin` method’s callback function parameter (`cb`), read [WebAuth on auth0.js documentation](https://auth0.github.io/auth0.js/global.html#login).

5. Reload the `loginCaptcha` and `signupCaptcha` components in your generic error handling logic.

   ```javascript lines theme={null}
   function displayError(err) {
     loginCaptcha.reload();
     signupCaptcha.reload();

     var errorMessage = document.getElementById('error-message');
     errorMessage.innerHTML = err.description;
     errorMessage.style.display = 'block';
   }
   ```

### Configure CAPTCHA templates

When you call the `renderCaptcha` and `renderSignupCaptcha` methods, you can configure the template for each [supported CAPTCHA provider](/docs/secure/attack-protection/bot-detection/configure-captcha) through the `options` parameter.

The `templates` property in the `options` parameter supports the following properties:

<table>
  <thead>
    <tr>
      <th><strong>Name</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>auth0</code></td>
      <td>Template function receiving the challenge and returning a string.</td>
    </tr>

    <tr>
      <td><code>recaptcha\_v2</code></td>
      <td>Template function receiving the challenge and returning a string.</td>
    </tr>

    <tr>
      <td><code>recaptcha\_enterprise</code></td>
      <td>Template function receiving the challenge and returning a string.</td>
    </tr>

    <tr>
      <td><code>hcaptcha</code></td>
      <td>Template function receiving the challenge and returning a string.</td>
    </tr>

    <tr>
      <td><code>friendly\_captcha</code></td>
      <td>Template function receiving the challenge and returning a string.</td>
    </tr>

    <tr>
      <td><code>arkose</code></td>
      <td>Template function receiving the challenge and returning a string.</td>
    </tr>

    <tr>
      <td><code>auth0\_v2</code></td>
      <td>Template function receiving the challenge and returning a string.</td>
    </tr>

    <tr>
      <td><code>error</code></td>
      <td>Template function returning a custom error message when the challenge could not be fetched, receives the error as first argument.</td>
    </tr>
  </tbody>
</table>

To learn more about the default template functions for each provider, read [auth0.js/src/web-auth/captcha.js on GitHub](https://github.com/auth0/auth0.js/blob/a3ddc0905a5da33aa190a9098467576976b95ec8/src/web-auth/captcha.js#L28).

## Support passwordless flows

If you'd like to support Bot Detection for <Tooltip href="/docs/glossary?term=passwordless">passwordless</Tooltip> flows, you must use version `9.24` or higher of the auth0.js library.

`<script src="https://cdn.auth0.com/js/auth0/9.24/auth0.min.js"></script>`

1. Add an element to render the CAPTCHA above the submit button. If you also support a username/password login, a separate element should be created for the passwordless CAPTCHA. For example:
   `<div class="passwordless-captcha-container"></div>`

2. Initialize the CAPTCHA component for passwordless flows after the WebAuth constructor.

   ```javascript lines theme={null}
   var passwordlessCaptcha = webAuth.renderPasswordlessCaptcha(
     document.querySelector('.passwordless-captcha-container')
   );
   ```

3. Add the captcha property to the Passwordless call, and reload the CAPTCHA component upon errors.

   ```text lines theme={null}
   webAuth.passwordlessStart({
     connection: 'email',
     send: 'code',
     email: 'foo@bar.com',
     captcha: passwordlessCaptcha.getValue()
   }, function (err,res) {
     if (err) {
       passwordlessCaptcha.reload();
       // handle errors
     }
     // continue
   });
   ```

## Learn more

* [Add Bot Detection to Native Applications](/docs/secure/attack-protection/bot-detection/bot-detection-native-apps)


# Add Bot Detection to Native Applications
Source: https://auth0.com/docs/secure/attack-protection/bot-detection/bot-detection-native-apps

Learn how to add bot protection and detection to your native application that use Auth0.Swift, Auth0.Android, Lock.Swift, and Lock.Android.

You can add [Bot Detection](/docs/secure/attack-protection/bot-detection) to your native applications with little to no additional configuration depending on the SDK and authentication flow you are using.

## Auth0.swift and Auth0.Android

If you’re using <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>, <Tooltip href="/docs/glossary?term=Bot+Detection">Bot Detection</Tooltip> is supported automatically by the following SDK versions:

* `Auth0.swift` version 1.28.0+
* `Auth0.Android` version 1.25.0+

If you’re not using Universal Login, Bot Detection is supported, but you need to configure your application accordingly:

* Your application must handle the `requires_verification` exception (which is thrown when a high-risk login attempt is detected) and then trigger a WebAuth flow to render a CAPTCHA verification step.
* When you trigger the WebAuth flow, you may pass the `login_hint` parameter to prevent the user from needing to type in their username again.

### Auth0.swift example

If your application performs database login/signup through the [Authentication API](https://auth0.com/docs/api/authentication), you must handle the `isVerificationRequired` error. This error indicates that the request was flagged as suspicious and an additional verification step is necessary to authenticate the user.

<Callout icon="file-lines">
  This verification step is web-based, so you need to use [Universal Login](/docs/authenticate/login/auth0-universal-login) to complete it.
</Callout>

```swift lines expandable theme={null}
Auth0
    .authentication()
    .login(usernameOrEmail: email, 
           password: password, 
           realmOrConnection: connection, 
           scope: scope)
    .start { result in
        switch result {
        case .success(let credentials): // ...
        case .failure(let error) where error.isVerificationRequired:
            DispatchQueue.main.async {
                Auth0
                    .webAuth()
                    .connection(connection)
                    .scope(scope)
                    .useEphemeralSession()
                    // ☝🏼 Otherwise a session cookie will remain
                    .parameters(["login_hint": email])
                    // ☝🏼 So the user doesn't have to type it again
                    .start { result in
                        // ...
                    }
            }
        case .failure(let error): // ...
        }
    }
```

In the case of signup, you can add [an additional parameter](/docs/authenticate/login/auth0-universal-login) to make the user land directly on the signup page:

`.parameters(["login_hint": email, "screen_hint": "signup"])`

Read [Auth0.swift Getting Started](https://github.com/auth0/Auth0.swift#getting-started) for details on how to set up Universal Login.

### Auth0.Android example

If your application performs database login/signup through the Authentication API, you must handle the `AuthenticationException#isVerificationRequired()` error. This error indicates that the request was flagged as suspicious and an additional verification step is necessary to log the user in.

<Callout icon="file-lines">
  This verification step is web-based, so you need to use [Universal Login](/docs/authenticate/login/auth0-universal-login) to complete it.
</Callout>

```swift lines expandable theme={null}
final String email = "username@domain.com";
final String password = "a secret password";
final String realm = "my-database-connection";

AuthenticationAPIClient authentication = new AuthenticationAPIClient(account);
authentication.login(email, password, realm)
        .start(new BaseCallback<Credentials, AuthenticationException>() {

            @Override
            public void onFailure(AuthenticationException error) {
                if (error.isVerificationRequired()){
                    Map<String, Object> params = new HashMap<>();
                    params.put("login_hint", email); // So the user doesn't have to type it again
                    WebAuthProvider.login(account)
                            .withConnection(realm)
                            .withParameters(params)
                            .start(LoginActivity.this, new AuthCallback() {
                                // You might already have an AuthCallback instance defined

                                @Override
                                public void onFailure(@NonNull Dialog dialog) {
                                    // Error dialog available
                                }

                                @Override
                                public void onFailure(AuthenticationException exception) {
                                    // Error
                                }

                                @Override
                                public void onSuccess(@NonNull Credentials credentials) {
                                    // Handle WebAuth success
                                }
                            });
                }
            }

            @Override
            public void onSuccess(Credentials payload) {
                // Handle API success
            }
        });
```

In the case of signup, you can add [an additional parameter](/docs/authenticate/login/auth0-universal-login) to make the user land directly on the signup page:

`params.put("screen_hint", "signup");`

Read [Auth0.Android Authentication with Universal Login SDK documentation](https://github.com/auth0/Auth0.Android#authentication-with-universal-login) for details on how to set up Universal Login.

## Lock.Swift and Lock.Android

If you’re using Universal Login, Bot Detection is supported automatically by the following SDK versions:

* `Lock.Swift` version 2.19.0+
* `Lock.Android` version 2.22.0+

If you’re not using Universal Login, Bot Detection is supported, but you need to configure your application accordingly:

* Your application must handle the `requires_verification` exception (which is thrown when a high-risk login attempt is detected) and then trigger a WebAuth flow to render a CAPTCHA verification step.
* When you trigger the WebAuth flow, you may pass the `login_hint` parameter to prevent the user from needing to type in their username again.

## Authentication API

If you’re using the Authentication API directly, Bot Detection is supported, but you need to configure your application accordingly:

* Your application must handle the `requires_verification` error (which is returned by the Authentication API when a high-risk login attempt is detected) and then trigger a WebAuth flow to render a CAPTCHA verification step.

## Learn more

* [Add Bot Detection to Custom Login Pages](/docs/secure/attack-protection/bot-detection/bot-detection-custom-login-pages)


# Add Bot Detection to Passwordless Flows
Source: https://auth0.com/docs/secure/attack-protection/bot-detection/bot-detection-passwordless-flows

Learn how to enable and configure bot detection for passwordless flows in Auth0.

If you use <Tooltip href="/docs/glossary?term=passwordless">passwordless</Tooltip> login and signup flows, you can enable <Tooltip href="/docs/glossary?term=Bot+Detection">Bot Detection</Tooltip> to render a CAPTCHA step in scenarios when a request is determined to be high-risk by Auth0.

<Warning>
  If you are using the [Lock SDK](/docs/libraries/lock) with the Classic Login experience, you must update to version 11.35.0 or higher to use Bot Detection for passwordless flows.

  If you are using the [Auth0.js SDK](/docs/libraries/auth0js), you must update to version 9.20.0 or higher to use Bot Detection for passwordless flows.
</Warning>

## Configure Bot Detection for passwordless flows

You can use the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> to configure the behavior of the CAPTCHA feature.

1. In the [Auth0 Dashboard](https://manage.auth0.com/dashboard), go to [Security > Attack Protection > Bot Detection](https://manage.auth0.com/dashboard/#/security/attack-protection/bot-detection).
2. Locate the **Response** section.
3. For the **Enforce CAPTCHA for passwordless flows** setting, select when to require CAPTCHA:

   * **Never**: Users are not required to complete a CAPTCHA to log in.
   * **When Risky**: Users are required to complete a CAPTCHA if the login is high risk.
   * **Always**: Users are always required to complete a CAPTCHA to log in.

## Configure Bot Detection for custom login pages

If you are using custom login pages and would like to configure Bot Detection, please read [Add Bot Detection to Custom Login Pages](/docs/secure/attack-protection/bot-detection/bot-detection-custom-login-pages).

## Learn more

* [Add Bot Detection to Custom Login Pages](/docs/secure/attack-protection/bot-detection/bot-detection-custom-login-pages)


# Configure Third-Party CAPTCHA Provider Integrations
Source: https://auth0.com/docs/secure/attack-protection/bot-detection/configure-captcha

Learn how to configure third-party CAPTCHA provider integrations with Auth0 Bot Detection.

Auth0 supports several third-party CAPTCHA provider integrations for [Bot Detection](/docs/secure/attack-protection/bot-detection).

## Google reCAPTCHA Enterprise on Google Cloud Platform (GCP)

You can use Google reCAPTCHA Enterprise as a <Tooltip href="/docs/glossary?term=Bot+Detection">Bot Detection</Tooltip> service for traffic exceeding 1 million assessments per month.

To learn how to configure reCAPTCHA Enterprise on GCP, read [Set up reCAPTCHA Enterprise ... on Google Documentation](https://cloud.google.com/recaptcha-enterprise/docs/authenticate-apis).

### Locate your GCP project ID

1. Go to your [Google Cloud Dashboard](https://console.cloud.google.com/).
2. Select your project in the drop-down menu to see the corresponding **Project ID**.
3. Make a note of the **Project ID** as you will need it later.

### Enable reCAPTCHA Enterprise

1. In the [Google Cloud Dashboard](https://console.cloud.google.com/), enter reCAPTCHA Enterprise API in the search bar, and then select it from the Marketplace results.
2. Select **Enable** to enable the API.

### Create a site key

1. In the [Google Cloud Dashboard](https://console.cloud.google.com/), enter reCAPTCHA Enterprise in the search bar, and then select it from the Marketplace results.
2. Select **Create Key**.
3. Under **Domain List**, add your Auth0 tenant domain.
4. Enable the toggle for **Disable domain verification**.
5. Enable the toggle for **Use checkbox challenge** to enable Google's "I am not a robot" verification checkbox.
6. Under **Challenge Security**, select a difficulty level for the challenge.
7. Select **Create Key**.
8. Make a note of the **Site Key** as you will need it later.

### Create an API key

1. In the [Google Cloud Dashboard](https://console.cloud.google.com/), enter Credentials in the search bar, and then select it from the results.
2. Select **Create Credentials > API Key**. Make a note of the **API Key** as you will need it later.
3. In the pop-up, select **Edit Key**.
4. Under **Application Restrictions**, select **IP addresses (web servers, cron jobs, etc.)**, and then enter the [Auth0 IP Addresses for Allow Lists](/docs/secure/security-guidance/data-security/allowlist).
5. Under **API Restrictions**, select **Restrict Key**, select **reCAPTCHA Enterprise API** from the drop-down list, and click OK.
6. Select **Save**.

## hCaptcha

The hCaptcha widget can protect your applications from bots, spam, and other forms of automated abuse.

To learn more about hCaptcha and how to get configuration details, read [Switch from reCAPTCHA to hCaptcha on hCaptcha Docs](https://docs.hcaptcha.com/switch).

## Friendly Captcha

Friendly Captcha is a system for preventing spam on your website. You can add the Friendly Captcha widget to your web app to fight spam, with little impact to the user experience.

To learn more about Friendly Captcha and how to get configuration details, read [Installation on Friendly Captcha Docs](https://docs.friendlycaptcha.com/#/installation?id=installation).

## Arkose

Arkose Labs provides a bot detection solution for mitigating human-based and bot-driven attacks. For more information on seamlessly integrating with Arkose as your CAPTCHA provider, see [Arkose Bot Manager](https://www.arkoselabs.com/arkose-bot-manager/).

<Warning>
  You must upgrade to Auth0.js v9.23+ to use Arkose as a CAPTCHA provider.
</Warning>

### Configure callback action with Auth0.js

When using Arkose as the CAPTCHA provider, the Auth0.js WebAuth client’s `renderCaptcha` method allows you to pass a callback function. The second parameter of the callback will be a payload object containing the `triggerCaptcha` function. The `triggerCaptcha` function can be used to configure how your application handles and renders the CAPTCHA prompt.

To learn more about configuring the `renderCaptcha` method, read [renderCaptcha](https://auth0.github.io/auth0.js/WebAuth.html#renderCaptcha) in the Auth0.js documentation.


# Breached Password Detection
Source: https://auth0.com/docs/secure/attack-protection/breached-password-detection

Understand why a user receives a breached password email and general web security tips.

<Warning>
  These materials and any recommendations within are not legal, privacy, security, compliance, or business advice. These materials are intended for general informational purposes only and may not reflect the most current security, privacy, and legal developments nor all relevant issues. You are responsible for obtaining legal, security, privacy, compliance, or business advice from your own lawyer or other professional advisor and should not rely on the recommendations herein. Okta is not liable to you for any loss or damages that may result from your implementation of any recommendations in these materials. Okta makes no representations, warranties, or other assurances regarding the content of these materials. Information regarding Okta's contractual assurances to its customers can be found at [okta.com/agreements](http://okta.com/agreements).
</Warning>

<Tooltip href="/docs/glossary?term=Breached+password+detection">Breached password detection</Tooltip> protects your applications from <Tooltip href="/docs/glossary?term=bad+actors">bad actors</Tooltip> signing up or logging in with stolen credentials. Auth0 can both notify users and block at-risk accounts.

Auth0 tracks large security breaches that occur on major third-party sites. If Auth0 identifies that any of your users’ credentials were part of a breach, the breached password detection security feature triggers. In response, Auth0 can:

* Block new users from signing up with stolen credentials. Entirely blocks the username/password combination.
* Block anyone from logging in with stolen credentials. Entirely blocks the account and prevents bad actors from accessing your application. The user can’t log in until they change their password.
* Send an email to the user when a login attempt happens. The email informs users about the risk and instructs them to change their password immediately. You can customize the message sent to users. To learn more, read [Customize Blocked Account Emails](/docs/customize/email/customize-blocked-account-emails).

## Detect breaches faster with Credential Guard

Breached password detection relies on breach data released to the public. Credential Guard is an additional Auth0 service you can add to breach password detection that screens for breaches to allow faster notification of compromised credentials.

<table>
  <thead>
    <tr>
      <th />

      <th><strong>Breached Password Protection</strong></th>
      <th><strong>Credential Guard</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Plans included</strong></td>
      <td>B2B / B2C Professional and Enterprise</td>
      <td>Part of Attack Protection add-on in Enterprise plan</td>
    </tr>

    <tr>
      <td><strong>Data collection method</strong></td>
      <td>Web scanners and scrapers search for user credentials in published security breaches</td>
      <td>Dedicated security team infiltrates criminal communities and gains access to breach data that isn’t otherwise available</td>
    </tr>

    <tr>
      <td><strong>Typical detection time</strong></td>
      <td>Up to 7-13 months</td>
      <td>12-36 hours</td>
    </tr>

    <tr>
      <td><strong>Coverage</strong></td>
      <td>English only</td>
      <td>200+ countries and territories</td>
    </tr>
  </tbody>
</table>

To add Credential Guard to your Auth0 agreement, [contact us](https://auth0.com/get-started?place=header\&type=button\&text=talk%20to%20sales).

## Configure breached password detection

When enabled, you can customize breached password detection preferences, such as the detection method, response scenarios, and notifications.

1. Go to [Dashboard > Security > Attack Protection](https://manage.auth0.com/#/security/attack-protection) and select **Breached Password Detection**.

   <Frame>
     <img alt="The toggle for turning on breached password detection in Auth0" />
   </Frame>
2. To turn on breached password detection, enable the switch at the top-right corner of the page.

   <Frame>
     <img alt="Configure breached password detection in Auth0" />
   </Frame>

   <Warning>
     Enabling attack protection features without any response settings enabled activates Monitoring mode, which records related events in your tenant log only. To learn more, read [View Attack Protection Log Events](/docs/secure/attack-protection/view-attack-protection-events).
   </Warning>

   <Callout icon="file-lines">
     If you cannot see the toggle to enable tenant logs for Risk Assessment, you may need to [upgrade your plan](https://manage.auth0.com/#/tenant/billing/subscription).
   </Callout>

### Configure detection method

Based on features available with your plan, you can configure the detection method used to identify compromised credentials.

1. Go to [Dashboard > Security > Attack Protection](https://manage.auth0.com/#/security/attack-protection) and select **Breached Password Detection**.
2. In the **Detection** section, locate **Breached Password Detection Method**.
3. If your agreement with Auth0 includes Credential Guard, select **As soon as possible based on data received from the dark web, with Credential Guard**.
4. Otherwise, leave **When breach data is published** selected.
5. Select **Save** to apply changes.

### Configure response scenarios

You can configure how Auth0 responds to different scenarios when users may provide compromised credentials.

1. Go to [Dashboard > Security > Attack Protection](https://manage.auth0.com/#/security/attack-protection) and select **Breached Password Detection**.
2. Locate the **Response** section.

   <Frame>
     <img alt="" />
   </Frame>
3. Enable the **Block compromised credentials for new accounts** toggle to block users from using compromised credentials during signup.
4. Enable the **Block compromised user accounts** toggle to block users from using compromised credentials during login.
5. Enable the **Block compromised credentials use for password reset** toggle to block users from using compromised credentials upon password reset.

<Warning>
  If you are using Lock, our UI widget for authenticating users, with the Classic Login experience, then you must update to v11.33.3 or higher to use breached password detection for new accounts. To learn more about Lock, navigate to the [Lock library](/docs/libraries#lock). If you are using an Auth0 SDK, then you must update to the newest version to use breached password detection for new accounts.
</Warning>

### Configure notifications

You can configure how Auth0 notifies users and admins about the use of compromised credentials.

1. Go to [Dashboard > Security > Attack Protection](https://manage.auth0.com/#/security/attack-protection) and select **Breached Password Detection**.
2. Locate the **Notifications** section.
3. Enable the **Send notifications to users with compromised credentials** toggle to send an email to a user when Auth0 detects their credentials may have been compromised.
4. Enable the **Compromised user accounts** toggle to send an email to administrators when a user signs up with compromised credentials.
5. Enable the **Compromised user accounts** toggle to send an email to administrators when a user logs in with compromised credentials.
6. Choose the notification frequency: **Immediately**, **Daily**, **Weekly**, or **Monthly**.

   <Warning>
     If you choose **daily**, **weekly**, or **monthly**, your notification will include the number of breaches to your application. If you choose **immediate**, your notification will include the user account attempting to breach your application.
   </Warning>
7. Select **Save**.

### Throttling behavior

To prevent notification fatigue and excessive log events, Auth0 applies throttling to breached password detection notifications and logs. When a compromised credential (breached password) is detected, Auth0 takes the following actions:

1. **Block compromised user accounts**: No throttling applied. User accounts are always blocked when a compromised credential is detected.
2. **Send notifications to users**: Throttled to once per hour per user.
3. **Send notifications to tenant admins**: Throttled to once per hour per IP address.
4. **Log `pwd_leak` events**: Throttled to once per hour per IP address.

<Callout icon="lightbulb">
  If you do not receive expected email notifications or do not observe `pwd_leak` events in your tenant logs, verify whether the detection occurred within the throttling period. During the throttling window, notifications and log events are suppressed, which is expected behavior. However, user account blocking always occurs regardless of throttling.
</Callout>

#### Customize email notifications to users

You can configure the notification Auth0 sends to your users when compromised credentials are used for login.

1. Navigate to [Dashboard > Branding > Email Templates](https://manage.auth0.com/#/templates).
2. In the **Template** dropdown menu, select **Password Breach Alert**.
3. Update the template accordingly. You can use any of the available [common variables](/docs/customize/email/email-templates#common-variables) to customize the message.

## Verify detection configuration

You can verify your configuration by testing signup and login flows with an Auth0-provided breached password.

<Callout icon="file-lines">
  Any password starting with `AUTH0-TEST-` triggers Breached Password Detection for testing purposes.
</Callout>

### Signup flow

Verify a user’s signup experience when Auth0 detects a breached password:

1. Go through your signup flow and try to register a new account with a test breached password (`Paaf213XXYYZZ` or `Paat739!!WWXXYYZZ`) or any password starting with `AUTH0-TEST-`.
2. If **Block compromised credentials for new accounts** is enabled, you will receive an error message, preventing you from using the breached password.
3. Navigate to [Dashboard > Monitoring > Logs](https://manage.auth0.com/#/logs).
4. Search the logs for `type: "signup_pwd_leak"` to verify Auth0 blocked the signup.

### Login flow

Verify a user's login experience when Auth0 detects a breached password:

1. Create a test user in [Dashboard > User Management > User](https://manage.auth0.com/#/users), and assign a test breached password (`Paaf213XXYYZZ` or `Paat739!!WWXXYYZZ`) or any password starting with `AUTH0-TEST-`.
2. Go through your login flow and submit the identifier and password that you assigned.
3. If **Block compromised user accounts** is enabled, the user will receive an error message, preventing them from logging in and advising to reset their password.
4. Navigate to [Dashboard > Monitoring > Logs](https://manage.auth0.com/#/logs).
5. Search the logs for `type: "pwd_leak"` to verify Auth0 blocked the login.
6. Navigate to [Dashboard > User Management > User](https://manage.auth0.com/#/users) to delete the test user.

### Reset flow

Verify a user's password reset experience when Auth0 detects a breached password:

1. Create a test user in [Dashboard > User Management > User](https://manage.auth0.com/#/users).
2. Go through your password reset flow and submit one of the test breached passwords (`Paaf213XXYYZZ` or `Paat739!!WWXXYYZZ`) or any password starting with `AUTH0-TEST-`.
3. If **Block compromised user accounts** is enabled, the end-user will receive an error message, preventing them from resetting their password and advising them to use another password.
4. Navigate to [Dashboard > Monitoring > Logs](https://manage.auth0.com/#/logs).
5. Search the logs for `type: “reset_pwd_leak"` to verify Auth0 blocked the password reset.
6. Navigate to [Dashboard > User Management > User](https://manage.auth0.com/#/users) to delete the test user.

## Learn more

* [Bot Detection](/docs/secure/attack-protection/bot-detection)
* [Brute-Force Protection](/docs/secure/attack-protection/brute-force-protection)
* [Suspicious IP Throttling](/docs/secure/attack-protection/suspicious-ip-throttling)
* [View Attack Protection Log Events](/docs/secure/attack-protection/view-attack-protection-events)
* [Customize Blocked Account Emails](/docs/customize/email/customize-blocked-account-emails)


# Brute-Force Protection
Source: https://auth0.com/docs/secure/attack-protection/brute-force-protection

Learn how to brute-force protection works in Auth0 and how to configure responses.

<Tooltip href="/docs/glossary?term=Brute-force+protection">Brute-force protection</Tooltip> safeguards your tenant against attackers who use a single IP address to target a single user account. By default, Brute-force protection is enabled when you create an Auth0 tenant.

When a given IP address tries and fails multiple times to log in as the same user, brute-force protection:

* Blocks the suspicious IP address from logging in as that user.
* Sends a [notification](#notifications) to the affected user.

<Warning>
  Brute-force protection safeguards apply to all users, including tenant administrators. Ensure your tenant has a secondary administrator in order to unblock other administrator accounts.
</Warning>

## Block removal events

If an IP address is blocked due to brute-force protection, it remains blocked until one of these events occurs:

* An administrator [removes the block](https://auth0.com/docs/api/management/v2/#!/User_Blocks/get_user_blocks).
* An administrator raises the **Brute Force Threshold** described below.
* Thirty (30) days pass from the last failed login attempt.
* The affected user selects the unblock link in the email notification (if configured).
* The affected user changes their password (on all linked accounts).

<Callout icon="file-lines">
  In cases where a user's account (email) is linked through multiple connections, such as an OTP account and a database account, and they change their password on only one, the block will not be removed. The user must change their passwords on each account (connection type).
</Callout>

## Brute Force Threshold behavior

Auth0 applies brute-force protection for a given [user identifier](/docs/authenticate/database-connections/flexible-identifiers-and-attributes#attribute-and-identifier-definitions) after that user consecutively fails to authenticate a number of times equal to your configured **Brute Force Threshold**.

Auth0 applies these protections immediately after we complete the processing of the failed login attempt that meets the threshold.

<Callout icon="file-lines">
  If you're using an Auth0 SDK that uses asynchronous methods, you may notice that a user identifier can submit more authentication requests successively to your application than your configured **Brute Force Threshold**.

  Although it appears that your threshold is not being enforced, Auth0 immediately applies brute-force protection after we receive and process the request that meets the **Brute Force Threshold**, and then responds to any subsequent requests from the given user identifier with an HTTP 429 [too\_many\_attempts error](/docs/libraries/common-auth0-library-authentication-errors#sign-up).
</Callout>

## Configure brute-force protection

Auth0 strongly recommends that you do not disable brute-force protection for the connection. If you disable it, you can enable it again using the Dashboard.

<Warning>
  Enabling attack protection features without any response settings enabled activates Monitoring mode, which records related events in your tenant log only. To learn more, read [View Attack Protection Log Events](/docs/secure/attack-protection/view-attack-protection-events).
</Warning>

1. Go to [Dashboard > Security > Attack Protection](https://manage.auth0.com/#/security/attack-protection) and select **Brute-force Protection**. Enable the toggle at the top of the page if it is disabled.
2. In the **Detection** section:

   1. Under **Brute Force Threshold**, select **Default** to set the attempts threshold to 10 or select **Custom** to set the attempts threshold to a value between 1 and 100.
   2. Under **Manage IP Addresses**, enter the list of trusted IP addresses in the **IP AllowList** field. Brute-force protection will not be enforced for login attempts originating from these IP addresses.
3. In the **Response** section:

   1. Under **Block Settings**, enable the **Block Brute-force Logins** toggle to block attempts from suspicious IP addresses to safeguard against brute-force attacks that occur from a single IP address and target a single user identifier.
   2. Under **Block Settings**, enable **Account Lockout** to trigger blocks irrespective of IP address. When this setting is enabled and a user consecutively attempts and fails to login, future attempts to log in from that user identifier from any IP address will be blocked. You can adjust maximum attempts under **Brute Force Threshold**. By default, the Account Lockout toggle is disabled.
   3. Under **Notifications**, enable the **Send notifications to the affected users** toggle to send an email notification to the user when their account has been blocked.
4. Click **Save**.

## Notifications

If **Send notifications to the affected users** is enabled, Auth0 sends an SMS or email notification to a user when their account has been blocked.

### SMS

Auth0 sends an SMS to the user if they use a phone identifier in the login flow. SMS notifications are limited at a maximum of 1 per hour per identifier.

### Email

Auth0 sends an email to the user if they have an email address associated with their account. Email notifications are limited at a maximum of 1 per hour per unique IP address.

By default, email notifications contain a link that allows the user to unblock their account. To learn more, read [Customize Blocked Account Emails](/docs/customize/email/customize-blocked-account-emails).

## Special use cases

Because brute-force protection depends on the IP address of the user, the following use cases require additional configuration.

### Resource Owner Password (ROP) flow

To ensure brute-force protection works correctly when using the ROP flow, you must configure your application to include the user’s IP address in requests using the `auth0-forwarded-for` header.

To learn more, read [Avoid Common Issues with Resource Owner Password Flow and Attack Protection](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow/avoid-common-issues-with-resource-owner-password-flow-and-attack-protection).

### Proxies and shared IP addresses

Users behind a proxy are more likely to reach set limits and trigger brute-force protection.

Use the **IP AllowList** feature to exempt a specific IP address or CIDR range from triggering brute-force protection.

## Learn more

* [Flexible Identifiers and Attributes](/docs/authenticate/database-connections/flexible-identifiers-and-attributes)
* [Activate and Configure Attributes for Flexible Identifiers](/docs/authenticate/database-connections/activate-and-configure-attributes-for-flexible-identifiers)
* [Customize Blocked Account Emails](/docs/customize/email/customize-blocked-account-emails)
* [View Attack Protection Log Events](/docs/secure/attack-protection/view-attack-protection-events)
* [User/Password Authentication Rate Limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/database-connections-rate-limits)


# Configure Akamai to Send Supplemental Signals
Source: https://auth0.com/docs/secure/attack-protection/configure-akamai-supplemental-signals



<Warning>
  **Auth0 Supplemental Signals is currently in Early Access.**

  By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal). To learn more about Auth0 product release stages, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

<Info>
  **Before you start**

  To configure Akamai to send supplemental signals to your Auth0 tenant, you must [configure Akamai as a reverse proxy](/docs/customize/custom-domains/self-managed-certificates).
</Info>

If you use Akamai Bot Manager and/or Akamai Account Protector, you can configure your reverse proxy in Akamai to send the results to Auth0 and [use the results in Actions](./use-akamai-supplemental-signals-actions).

# Supported login flows

Auth0 currently supports the following login flows for Akamai supplemental signals:

* Universal Login: Identifier + Password
* [Universal Login: Identifier First](/docs/authenticate/login/auth0-universal-login/identifier-first)
* [Resource Owner Password (ROP)](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow)

# Step 1: Register an API in Akamai

For Akamai to know when login attempts succeed or fail, you’ll need to register an API in Akamai, and then define an endpoint for each Auth0 login flow you’d like to support.

To learn more, read [Register an API on Akamai TechDocs](https://techdocs.akamai.com/api-definitions/docs/register-api) and [Add API resources on Akamai TechDocs](https://techdocs.akamai.com/api-definitions/docs/add-api-resources).

<AccordionGroup>
  <Accordion title="New Universal Login Identifier + Password">
    Use the following values to register your API in Akamai:

    | Property         | Value    |
    | ---------------- | -------- |
    | API base path    | `/u`     |
    | API key location | `Header` |

    After you’ve created your API, you’ll need to add an API resource for each of the following Auth0 endpoints:

    * `/u/login/password`
    * `/u/signup`
    * `/u/signup/password`

    The process is the same for all endpoints, but the configuration values differ slightly.

    ### Add API resource

    Use the following values to configure a resource on your Akamai API:

    <Tabs>
      <Tab title="/u/login/password">
        | Property                 | Value                       |
        | ------------------------ | --------------------------- |
        | API undefined parameters | `Specific` (`Request body`) |
        | Path                     | `/login/password`           |
        | Methods                  | `POST`                      |
      </Tab>

      <Tab title="/u/signup">
        | Property                 | Value                       |
        | ------------------------ | --------------------------- |
        | API undefined parameters | `Specific` (`Request body`) |
        | Path                     | `/signup`                   |
        | Methods                  | `POST`                      |
      </Tab>

      <Tab title="/u/signup/password">
        | Property                 | Value                       |
        | ------------------------ | --------------------------- |
        | API undefined parameters | `Specific` (`Request body`) |
        | Path                     | `/signup/password`          |
        | Methods                  | `POST`                      |
      </Tab>
    </Tabs>

    ### Add parameters to methods

    After you’ve created your API resource, you’ll need to define the `Request body` parameter so Akamai can parse login requests properly.

    Use the following values to define the `Request body` parameter:

    <Tabs>
      <Tab title="/u/login/password">
        | Property           | Value      |
        | ------------------ | ---------- |
        | Format             | `JSON`     |
        | Required           | `Yes`      |
        | Define body format | `Yes`      |
        | Schema details     | See below. |

        ```json theme={null}
        {
          "requestBody": {
            "content": {
              "application/x-www-form-urlencoded": {
                "schema": {
                  "type": "object",
                  "required": [
                    "state"
                  ],
                  "properties": {
                    "state": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "maxItems": 256
                    },
                    "username": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "maxItems": 256
                    },
                    "password": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "maxItems": 256
                    },
                    "action": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "maxItems": 256
                    }
                  }
                }
              }
            },
            "required": true
          }
        }
        ```
      </Tab>

      <Tab title="/u/signup">
        | Property           | Value      |
        | ------------------ | ---------- |
        | Format             | `JSON`     |
        | Required           | `Yes`      |
        | Define body format | `Yes`      |
        | Schema details     | See below. |

        ```json theme={null}
        {
          "requestBody": {
            "content": {
              "application/x-www-form-urlencoded": {
                "schema": {
                  "type": "object",
                  "required": [
                    "email",
                    "password"
                  ],
                  "properties": {
                    "email": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "maxItems": 256
                    },
                    "password": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "maxItems": 256
                    }
                  }
                }
              }
            },
            "required": true
          }
        }
        ```
      </Tab>

      <Tab title="/u/signup/password">
        | Property           | Value      |
        | ------------------ | ---------- |
        | Format             | `JSON`     |
        | Required           | `Yes`      |
        | Define body format | `Yes`      |
        | Schema details     | See below. |

        ```json theme={null}
        {
          "requestBody": {
            "content": {
              "application/x-www-form-urlencoded": {
                "schema": {
                  "type": "object",
                  "required": [
                    "email"
                  ],
                  "properties": {
                    "email": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "maxItems": 256,
                      "description": "email"
                    }
                  }
                }
              }
            },
            "required": true
          }
        }
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="New Universal Login Identifier First">
    Use the following values to register your API in Akamai:

    | Property         | Value    |
    | ---------------- | -------- |
    | API base path    | `/u`     |
    | API key location | `Header` |

    After you’ve created your API, you’ll need to add an API resource for each of the following Auth0 endpoints:

    * `/u/login`
    * `/u/signup`
    * `/u/signup/password`

    The process is the same for all endpoints, but the configuration values differ slightly.

    ### Add API resource

    Use the following values to configure a resource on your Akamai API:

    <Tabs>
      <Tab title="/u/login">
        | Property                 | Value                       |
        | ------------------------ | --------------------------- |
        | API undefined parameters | `Specific` (`Request body`) |
        | Path                     | `/login`                    |
        | Methods                  | `POST`                      |
      </Tab>

      <Tab title="/u/signup">
        | Property                 | Value                       |
        | ------------------------ | --------------------------- |
        | API undefined parameters | `Specific` (`Request body`) |
        | Path                     | `/login/signup`             |
        | Methods                  | `POST`                      |
      </Tab>

      <Tab title="/u/signup/password">
        | Property                 | Value                       |
        | ------------------------ | --------------------------- |
        | API undefined parameters | `Specific` (`Request body`) |
        | Path                     | `/signup/password`          |
        | Methods                  | `POST`                      |
      </Tab>
    </Tabs>

    ### Add parameters to methods

    After you’ve created your API resource, you’ll need to define the `Request body` parameter so Akamai can parse login requests properly.

    Use the following values to define the `Request body` parameter:

    <Tabs>
      <Tab title="/u/login">
        | Property           | Value      |
        | ------------------ | ---------- |
        | Format             | `JSON`     |
        | Required           | `Yes`      |
        | Define body format | `Yes`      |
        | Schema details     | See below. |

        ```json theme={null}
        {
          "requestBody": {
            "content": {
              "application/x-www-form-urlencoded": {
                "schema": {
                  "type": "object",
                  "required": [
                    "state"
                  ],
                  "properties": {
                    "state": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "maxItems": 256
                    },
                    "username": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "maxItems": 256
                    },
                    "password": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "maxItems": 256
                    },
                    "action": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "maxItems": 256
                    }
                  }
                }
              }
            },
            "required": true
          }
        } 
        ```
      </Tab>

      <Tab title="/u/signup">
        | Property           | Value      |
        | ------------------ | ---------- |
        | Format             | `JSON`     |
        | Required           | `Yes`      |
        | Define body format | `Yes`      |
        | Schema details     | See below. |

        ```json theme={null}
        {
          "requestBody": {
            "content": {
              "application/x-www-form-urlencoded": {
                "schema": {
                  "type": "object",
                  "required": [
                    "email",
                    "password"
                  ],
                  "properties": {
                    "email": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "maxItems": 256
                    },
                    "password": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "maxItems": 256
                    }
                  }
                }
              }
            },
            "required": true
          }
        } 
        ```
      </Tab>

      <Tab title="/u/signup/password">
        | Property           | Value      |
        | ------------------ | ---------- |
        | Format             | `JSON`     |
        | Required           | `Yes`      |
        | Define body format | `Yes`      |
        | Schema details     | See below. |

        ```json theme={null}
        {
          "requestBody": {
            "content": {
              "application/x-www-form-urlencoded": {
                "schema": {
                  "type": "object",
                  "required": [
                    "email"
                  ],
                  "properties": {
                    "email": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "maxItems": 256,
                      "description": "email"
                    }
                  }
                }
              }
            },
            "required": true
          }
        }
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="ROP">
    Use the following values to register your API in Akamai:

    | Property         | Value    |
    | ---------------- | -------- |
    | API base path    | None.    |
    | API key location | `Header` |

    After you’ve created your API, you’ll need to add an API resource for each of the following Auth0 endpoints:

    * `/oauth/token`

    The process is the same for all endpoints, but the configuration values differ slightly.

    ### Add API resource

    Use the following values to configure a resource on your Akamai API:

    <Tabs>
      <Tab title="/oauth/token">
        | Property                 | Value                       |
        | ------------------------ | --------------------------- |
        | API undefined parameters | `Specific` (`Request body`) |
        | Path                     | `/oauth/token`              |
        | Methods                  | `POST`                      |
      </Tab>
    </Tabs>

    ### Add parameters to methods

    After you’ve created your API resource, you’ll need to define the `Request body` parameter so Akamai can parse login requests properly.

    Use the following values to define the `Request body` parameter:

    <Tabs>
      <Tab title="/oauth/token">
        | Property           | Value      |
        | ------------------ | ---------- |
        | Format             | `JSON`     |
        | Required           | `Yes`      |
        | Define body format | `Yes`      |
        | Schema details     | See below. |

        ```json theme={null}
        {
          "requestBody": {
            "content": {
              "application/x-www-form-urlencoded": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "username": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "maxItems": 256
                    },
                    "password": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "maxItems": 256
                    }
                  }
                }
              }
            },
            "required": true
          }
        } 
        ```
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

# Step 2: Forward bot results from Akamai to Auth0

To configure Akamai to forward bot results to Auth0, read [Forward Bot Results to Origin on Akamai TechDocs](https://techdocs.akamai.com/content-protector/docs/forward-bot-results-to-origin).

<Note>
  The `akamai-user-risk` header may not be present on every login request, as Akamai only sends the header when it creates a user risk score.
</Note>

# Step 3: Enable processing of Akamai headers in Auth0

You can configure Auth0 to accept supplemental signals sent from Akamai in the Auth0 Dashboard or with the Auth0 Management API.

<Tabs>
  <Tab title="Dashboard">
    To enable supplemental signals in the Dashboard:

    1. Go to [Dashboard > Security > Attack Protection](#).
    2. Select **Supplemental Signals**.
    3. Enable the toggle for **Enable Akamai headers**.
  </Tab>

  <Tab title="Management API">
    To enable supplemental signals with the Management API:

    1. [Get a Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production) with the `update:attack_protection` scope.
    2. Call the Management API [Update the supplemental signals configuration for a tenant](/docs/api/management/v2/supplemental-signals/patch-supplemental-signals) endpoint with the following body:

    ```json theme={null}
    {
      "akamai_enabled": true
    }
    ```
  </Tab>
</Tabs>

# Step 4: Test and verify configuration

Test your configuration by calling each endpoint for the login flow(s) you have configured.

If you’ve configured everything properly:

* The `akamai-user-risk` and `akamai-bot headers` will be present in your tenant logs for related events.
* You can use the following properties in the post-login Action `event` object:
  * `authentication.riskAssessment.supplemental.akamai.akamaiBot`
  * `authentication.riskAssessment.supplemental.akamai.akamaiUserRisk`


# Playbooks
Source: https://auth0.com/docs/secure/attack-protection/playbooks

Attack protection playbooks to keep your tenant safe

Use the following playbooks to help protect your users and tenant from attacks.

### Bot detection playbook

The [bot detection playbook](/docs/secure/attack-protection/playbooks/bot-detection-playbook) helps you identify bots trying to log into your tenant.

### Breached password playbook

The [breached password playbook](/docs/secure/attack-protection/playbooks/breached-password-playbook) helps you identify and investigate potential attacks and take the required remediation actions.

### Brute force protection playbook

The [brute force protection playbook](/docs/secure/attack-protection/playbooks/brute-force-protection-playbook) describes common brute-force attack techniques and provides guidance on how to identify and investigate potential attacks against your tenant.

### MFA playbook

The [MFA playbook](/docs/secure/attack-protection/playbooks/mfa-playbook) describes common <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> attack vectors and provides guidance on how to investigate them.

### Signup attack playbook

The [signup attack playbook](/docs/secure/attack-protection/playbooks/signup-attack-playbook) describes how signup attacks work and provides guidance on how to identify and respond to them.


# Bot Detection Playbook
Source: https://auth0.com/docs/secure/attack-protection/playbooks/bot-detection-playbook

Playbook for using Auth0's Bot Detection monitoring feature in the Security Center

<Card title="Before you start">
  You must enable [Bot Detection](/docs/secure/attack-protection/bot-detection) and configure a [CAPTCHA provider](/docs/secure/attack-protection/bot-detection/configure-captcha).
</Card>

Auth0's [Bot Detection monitoring feature](/docs/secure/security-center#bot-detection) is an early warning system for botnet detection and attacks. Below is guidance for identifying bots trying to log into your tenant.

#### Find log events of interest

When considering a response, first sift through the log messages from the potential attack. For advanced analysis, enable [log streaming](/docs/customize/log-streams) and connect it to the external tool of your choice.

The following [log event types](/docs/deploy-monitor/logs/log-event-type-codes) are relevant when investigating an uptick in bot activity.

<table>
  <thead>
    <tr>
      <th>Log Event Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>pla</code></td>
      <td>Generated before login and monitor bot detection, even if bot detection is only in monitoring mode and not using CAPTCHAs to identify bots.</td>
    </tr>

    <tr>
      <td><code>fu</code></td>
      <td>Failed user login events due to invalid username, which can indicate attempted username enumeration or account takeover attempts.</td>
    </tr>

    <tr>
      <td><code>fp</code></td>
      <td>Failed user login events due to invalid password, which can indicate attempted credential stuffing attacks.</td>
    </tr>

    <tr>
      <td><code>pwd\_leak</code></td>
      <td>Attempted login events with a leaked password, which can indicate attempted credential stuffing attacks.</td>
    </tr>

    <tr>
      <td><code>limit\_wc</code></td>
      <td>IP block events for >10 failed login attempts to a single account, which indicates the IP address is likely to belong to a bot.</td>
    </tr>

    <tr>
      <td><code>limit\_sul</code></td>
      <td>User block events for >20 login attempts per minute from the same IP address, which indicates likely bot activity.</td>
    </tr>

    <tr>
      <td><code>limit\_mu</code></td>
      <td>IP block events for >100 failed login attempts or >50 signup attempts from the same IP address, which indicates likely bot activity.</td>
    </tr>

    <tr>
      <td><code>fcoa</code></td>
      <td>Failed cross-origin authentication events, which indicates attackers using automation to perform account takeovers.</td>
    </tr>

    <tr>
      <td><code>scoa</code></td>
      <td>Successful cross-origin authentication events, which indicates attackers using automation to perform account takeovers when originating from a small number of IP addresses across multiple users.</td>
    </tr>
  </tbody>
</table>

#### Attack response

While setting the <Tooltip href="/docs/glossary?term=Bot+Detection">Bot Detection</Tooltip> level to High immediately mitigates the attack, a comprehensive strategy balances your business's risk tolerance and technical capabilities with the experience your users will have when they sign in. When responding, consider two main factors:

* **User friction**: evaluate the impact of mitigation measures (e.g. CAPTCHA frequency) on user experience.
* **Technical capacity**: assess your ability to implement IP blocking, WAF rules, and <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> enforcement.

Auth0 recommends a layered security approach that combines multiple mitigation techniques for optimal protection.

#### Mitigation strategies

For optimal protection from attacks, consider the following strategies:

* Activate CAPTCHA for one or more flows and increase CAPTCHA frequency as needed, but remember that CAPTCHA is a deterrent, not a solution.
* Change your CAPTCHA provider if attackers bypass your current CAPTCHA or consider migrating to Auth0's Auth Challenge or another [supported provider](/docs/secure/attack-protection/bot-detection/configure-captcha).
* If you suspect a signup fraud campaign, temporarily prevent new user signups to your application from public, unauthenticated endpoints.
* Change your web application firewall rules with an edge provider or use [tenant access control lists](/docs/secure/tenant-access-control-list) to block abusive IPs, autonomous system numbers, geographic locations, [TLS clients](/docs/customize/custom-domains/self-managed-certificates/tls-ssl), or HTTP header elements like `user-agent` strings, and consider employing a [reverse proxy.](/docs/customize/custom-domains/self-managed-certificates#configure-reverse-proxy)
* Tighten [Brute Force](/docs/secure/attack-protection/brute-force-protection) and [Suspicious IP](/docs/secure/attack-protection/suspicious-ip-throttling) thresholds to reduce allowed connection limits and mitigate brute-force attacks. For more information about brute force attacks, read the [Brute Force playbook](/docs/secure/attack-protection/playbooks/brute-force-protection-playbook).
* Disable unused endpoints by modifying your [Cross-Origin Authentication](/docs/authenticate/login/cross-origin-authentication) settings. If you suspect breached password attacks, read the [Breached Password playbook](/docs/secure/attack-protection/playbooks/breached-password-playbook).
* Enforce [step-up MFA](/docs/secure/multi-factor-authentication/step-up-authentication) for compromised accounts, up to and including requiring MFA for potentially compromised accounts.
* Migrate to stronger MFA options to mitigate SMS pumping or toll fraud attacks by replacing SMS or voice-based MFA with OTP or Webauthn.


# Breached Password Playbook
Source: https://auth0.com/docs/secure/attack-protection/playbooks/breached-password-playbook

Playbook for using Auth0's Breached Password monitoring feature in the Security Center

<Card title="Before you start">
  You must configure [Breached Password Protection](/docs/secure/attack-protection/breached-password-detection) and set up [alerts for thresholds](/docs/secure/security-center/security-alerts).
</Card>

Adversaries can use password-based authentication as a target for attacks against your tenant. Below is for identifying and investigating potential attacks and taking the required remediation actions to protect users and minimize further risks.

### Find log events of interest

When considering a response, first sift through the log messages of interest to identify potential attacks. For example, the attack may be coming from a limited set of IPs or from a single autonomous system number (ASN) or country.

The following Auth0 tenant log event types are relevant when investigating a brute force attack.

<Accordion title="Relevant log event types">
  1. `f`: failed user login
  2. `fu`: failed user login due to invalid username
  3. `fp`: failed user login due to invalid password
  4. `pwd_leak`: attempted login with a leaked password
  5. `signup_pwd_leak`: attempted to sign up with a leaked password
  6. `fcoa`: failed cross-origin authentication (these events are generated by `/co/authenticate`, which [should not be enabled unless strictly required](https://sec.okta.com/articles/2024/05/detecting-cross-origin-authentication-credential-stuffing-attacks/))
  7. `scoa`: successful cross-origin authentication (these events are generated by `/co/authenticate`, which [should not be enabled unless strictly required](https://sec.okta.com/articles/2024/05/detecting-cross-origin-authentication-credential-stuffing-attacks/))
</Accordion>

### Identify breached password attacks

Attackers often employ [brute force techniques](/docs/secure/attack-protection/brute-force-protection) ([TT1110](https://attack.mitre.org/techniques/T1110/)) when trying to breach password authentication, using collections of bots to guess passwords and sign up with reused credentials to test user accounts.

#### Password guessing

Most commonly employed by unsophisticated adversaries, password guessing ([TT1110.001](https://attack.mitre.org/techniques/T1110/001/)) attackers come in with little prior knowledge of your tenant’s policies and repeatedly attempt to guess passwords in an attempt to access accounts. Since attackers are merely guessing whether a user exists with an unknown password, you will see a flood of `fp`, `fu` and `fcoa` events in your [Auth0 log events](/docs/deploy-monitor/logs/log-event-type-codes).

#### Password spraying

Adversaries employ password spraying ([TT1110.003](https://attack.mitre.org/techniques/T1110/003/)) as an opportunistic attack en masse when attempting to gain access to legitimate user accounts. Since attackers achieve their goals by trying commonly-used passwords, these attacks will frequently result in tripping Auth0’s brute force protections. Much like password guessing attacks, a high number of `fp`, `fu` and `fcoa` events in your logs are the best way to see whether attackers are attempting password spraying attacks.

#### Credential stuffing

If your tenant uses passwords without requiring an additional factor, credential stuffing ([TT1110.004](https://attack.mitre.org/techniques/T1110/004/)) is the most effective brute force attack technique. These attacks take advantage of password leaks and reuse by attempting to log in to a victim’s account using a dictionary of leaked passwords. Credential stuffing attacks frequently generate `fp` events (because the attackers are more likely to know a user exists) and `pwd_leak` events (because attackers are attempting to log in using breached credentials).

#### Mitigation strategies

A comprehensive strategy balances your business's risk tolerance and technical capabilities with the experience your users will have when they sign in. When responding, consider two main factors:

* **User friction**: evaluate the impact of mitigation measures (e.g. CAPTCHA frequency, passkey requirements, or <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip>) on user experience.
* **Technical capacity**: assess your ability to implement IP blocking, WAF rules, and MFA enforcement.

Auth0 recommends a layered security approach that combines multiple mitigation techniques for optimal protection. Below are Auth0's recommendations:

* Turn on [Bot Detection](/docs/secure/attack-protection/bot-detection) and block [compromised credentials](/docs/secure/attack-protection/breached-password-detection#configure-response-scenarios), up to and including requiring MFA for potentially compromised accounts.
* Activate CAPTCHA for one or more flows and increase CAPTCHA frequency as needed, but remember that CAPTCHA is a deterrent, not a solution. For more information about <Tooltip href="/docs/glossary?term=bot+detection">bot detection</Tooltip>, read [the Bot Detection playbook](/docs/secure/attack-protection/playbooks/bot-detection-playbook).
* Change your CAPTCHA provider if attackers bypass your current CAPTCHA or consider migrating to Auth0's Auth Challenge or another [supported provider](/docs/secure/attack-protection/bot-detection/configure-captcha).
* Change your web application firewall rules using an edge provider or use [tenant access control lists](/docs/secure/tenant-access-control-list) to block abusive IPs, autonomous system numbers, geographic locations, [TLS clients](/docs/customize/custom-domains/self-managed-certificates/tls-ssl), or HTTP header elements like `user-agent` strings.
* Tighten [Brute Force](/docs/secure/attack-protection/brute-force-protection) and [Suspicious IP](/docs/secure/attack-protection/suspicious-ip-throttling) thresholds to reduce allowed connection limits and mitigate brute-force attacks.
* Disable stateless endpoints susceptible to credential stuffing attacks by modifying your [Cross-Origin Authentication](/docs/authenticate/login/cross-origin-authentication) settings.


# Brute Force Protection Playbook
Source: https://auth0.com/docs/secure/attack-protection/playbooks/brute-force-protection-playbook

Playbook for using Auth0's Brute Force monitoring feature in the Security Center

<Card title="Before you start">
  You must configure [Brute Force Protection](/docs/secure/attack-protection/brute-force-protection) and set up logs and [alerts for thresholds](/docs/secure/security-center/security-alerts).
</Card>

Attackers can employ brute force techniques ([TT1110](https://attack.mitre.org/techniques/T1110/)) to gain access to sensitive systems. Often unsophisticated, most brute-force attacks are easily defeated, but defense can be resource-intensive. Below are some common brute-force attack techniques and guidance on how to identify and investigate potential attacks against your tenant.

### Find log events of interest

Before blocking IPs or otherwise responding to an attack, identify breaches by sifting through the log messages of interest. The attack may be coming from a limited set of IPs or from a single autonomous system number or country.

The following log event types are relevant when investigating a brute force attack. They are found in the [Auth0 tenant logs](/docs/secure/attack-protection/view-attack-protection-events).

<Accordion title="Log event types">
  1. `f`: Failed user login
  2. `fu`: Failed user login due to invalid username
  3. `fp`: Failed user login due to invalid password
  4. `pwd_leak`: Attempted login with a leaked password
  5. `signup_pwd_leak`: Attempted to sign up with a leaked password
  6. `limit_wc`: IP blocked for >10 failed login attempts to a single account
  7. `limit_sul`: User blocked for >20 login per minute from the same IP address
  8. `limit_mu`: IP blocked for >100 failed login attempts or >50 signup attempts
  9. `fcoa`: Failed cross-origin authentication
  10. `scoa`: Successful cross-origin authentication
</Accordion>

### Password guessing

Attackers with little prior knowledge of your tenant’s policies can repeatedly attempt to guess passwords ([TT1110.001](https://attack.mitre.org/techniques/T1110/001/)) in an attempt to access accounts. Since attackers are merely guessing whether a user exists with an unknown password, your [Auth0 logs](/docs/deploy-monitor/logs/log-event-type-codes) will display many `fp`, `fu` and `fcoa` log events. For more information, read Auth0's [Breached Password playbook](/docs/secure/attack-protection/playbooks/breached-password-playbook).

### Password spraying

Attackers try many commonly-used passwords ([TT1110.003](https://attack.mitre.org/techniques/T1110/003/)) to gain access to legitimate user accounts. These often trip Auth0’s brute force protections and leave many `fp`, `fu`, and `fcoa` log events in your logs.

### Credential stuffing

Credential stuffing ([TT1110.004](https://attack.mitre.org/techniques/T1110/004/)) is most effective when used against tenants that employ passwords but no additional factors. By taking advantage of password leaks and attempting to log in to a victim’s account using a dictionary of leaked passwords, credential stuffing attacks generate `fp` log events and `pwd_leak` log events.

### Signup attacks

Attackers can attempt to sign up for a large number of accounts in a short window of time as part of a username enumeration attack ([T1087](https://attack.mitre.org/techniques/T1087/)), where attackers attempt to see whether a user account exists on your tenant or signup fraud campaigns. The goal is to create many accounts to take advantage of signup incentives or create aged accounts for later attacks. Signup attacks generate `fs`, `ss` and `signup_pwd_leak` log events.

### Detection using the Auth0 Management API

The [Auth0 Management API](/docs/deploy-monitor/logs/retrieve-log-events-using-mgmt-api) allows tenant logs to be queried using [log search query syntax](/docs/deploy-monitor/logs/log-search-query-syntax) for log types in the time range of interest. More advanced use cases are supported by log aggregation tooling like data warehouses or SIEMs by leveraging Auth0 log streams.

When using the Auth0 <Tooltip href="/docs/glossary?term=management+API">management API</Tooltip>, the potential attack timeframe is specified as `date:[startdate to enddate]` in `YYYY-MM-DD` format. For example, `2024-10-01`. Use `*` to represent the current date.

By limiting the time of interest to a potential attack window, you can retrieve all log events of the type you’re interested. Below is an example query that searches for brute force attacks from October 1, 2024 to the present:

```text wrap lines theme={null}
date:[2024-10-01 TO *] AND (type:"f" OR type:"fu" OR type:"fp" OR type:"pwd_leak" OR type:"limit_wc" OR type:"limit_sul" OR type:"limit_mu" OR type:"fcoa")
```

For advanced analysis or to correlate login activities with applications outside Auth0, enable log streaming to the external tool of your choice. Review the [Management API documentation](https://auth0.com/docs/api/management/v2/logs/get-logs) to understand how to extract a subset of log events from your tenant for analysis.

#### Mitigation strategies

For optimal protection from attacks, consider the following strategies:

* Enable [Breached Password Detection](/docs/secure/attack-protection/breached-password-detection) or Credential Guard to protect against breached credentials with minimal user friction, noting that neither protects against dictionary attacks.
* Activate CAPTCHA for one or more flows and increase CAPTCHA frequency as needed, but remember that CAPTCHA is a deterrent, not a solution.
* Change your CAPTCHA provider if attackers bypass your current CAPTCHA or consider migrating to Auth0's Auth Challenge or another [supported provider](/docs/secure/attack-protection/bot-detection/configure-captcha).
* Temporarily disable account creation by everyone, including malicious actors.
* Change your web application firewall rules with an edge provider, or use [tenant access control lists](/docs/secure/tenant-access-control-list), to block abusive IPs, autonomous system numbers, geographic locations, [TLS clients](/docs/customize/custom-domains/self-managed-certificates/tls-ssl), or HTTP header elements like `user-agent` strings, and consider employing a [reverse proxy.](/docs/customize/custom-domains/self-managed-certificates#configure-reverse-proxy)
* Tighten [Brute Force](/docs/secure/attack-protection/brute-force-protection) and [Suspicious IP](/docs/secure/attack-protection/suspicious-ip-throttling) thresholds to reduce allowed connection limits and mitigate brute-force attacks.
* Disable unused endpoints by modifying your [Cross-Origin Authentication](/docs/authenticate/login/cross-origin-authentication) settings if you see frequent `fcoa` and `scoa` events, remembering that Auth0 does not recommend using cross-origin authentication.
* Enforce [step-up MFA](/docs/secure/multi-factor-authentication/step-up-authentication) for compromised accounts, up to and including requiring <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> for potentially compromised accounts.
* Migrate to stronger MFA options by replacing SMS or voice-based MFA with [OTP](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-otp-notifications-for-mfa) or [Webauthn](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-device-biometrics-for-mfa) to mitigate SMS pumping or toll fraud attacks.
* Implement SMS/voice provider security fraud protection like Twilio's [Preventing Fraud in Verify](https://www.twilio.com/docs/verify/preventing-toll-fraud) when using SMS/voice MFA.


# MFA Playbook
Source: https://auth0.com/docs/secure/attack-protection/playbooks/mfa-playbook

How to protect yourself from MFA attacks

Attackers can exploit and misuse <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA) alerts to gain access to your systems. Below are some common MFA attack vectors and guidance on how to investigate them.

### Find log events of interest

The following log event types are relevant when investigating an MFA attack. They are found in the [Auth0 tenant logs](/docs/deploy-monitor/logs/log-event-type-codes).

<table>
  <thead>
    <tr>
      <th>Log Event Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>gd\_auth\_failed</code></td>
      <td>Multi-factor authentication failed. This could be a system failure or could be a user’s incorrect code entry when they used SMS/voice/Email/TOTP as an MFA factor. Frequent failures indicate an attack or an MFA misconfiguration.</td>
    </tr>

    <tr>
      <td><code>gd\_auth\_fail\_email\_verification</code></td>
      <td>A high frequency of email verification failed log event types can indicate malicious activity or tenant misconfiguration.</td>
    </tr>

    <tr>
      <td><code>gd\_auth\_rejected</code>, <code>gd\_send\_pn</code> and <code>gd\_send\_pn\_failure</code></td>
      <td>Frequent push events and push events without responses can indicate MFA fatigue attacks (T1621).</td>
    </tr>

    <tr>
      <td><code>gd\_otp\_rate\_limit\_exceed</code></td>
      <td>Too many MFA failures over a short period of time can indicate automated attacks.</td>
    </tr>

    <tr>
      <td><code>gd\_recovery\_failed</code></td>
      <td>Repeated MFA recovery failures can indicate attacker attempts to circumvent or replace additional authentication factors.</td>
    </tr>

    <tr>
      <td><code>gd\_send\_sms</code>, <code>gd\_send\_sms\_failure</code>, <code>gd\_send\_voice</code>, and <code>gd\_send\_voice\_failure</code></td>
      <td>A high frequency of these events indicates SMS pumping or toll fraud attacks. It can also indicate attempts to circumvent SMS/voice as a factor.</td>
    </tr>

    <tr>
      <td><code>gd\_unenroll</code></td>
      <td>Large scale MFA device disenrollment can indicate successful account takeover campaigns.</td>
    </tr>
  </tbody>
</table>

## Mitigation strategies

The following are example responses to attacks against MFA:

* Migrate to stronger MFA options by replacing SMS/voice-based MFA with [OTP](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-otp-notifications-for-mfa) or [Webauthn](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-device-biometrics-for-mfa) to mitigate SMS pumping or toll fraud attacks.
* Enhance SMS/Voice Provider Security by implementing fraud protection like Twilio's [Preventing Fraud in Verify](https://www.twilio.com/docs/verify/preventing-toll-fraud) when using SMS/voice MFA.
* Avoid MFA fatigue by enforcing push notification rate limits.


# Signup Attack Playbook
Source: https://auth0.com/docs/secure/attack-protection/playbooks/signup-attack-playbook

Learn how to detect and mitigate signup attacks

The easiest way for a malicious user to access the privileges, services, and information behind the login box is to create puppet accounts under their control from day one.

Attackers can then use these accounts for a variety of illicit purposes, with objectives depending on the specific business context. Common objectives include:

* **Financial Gain**: Involves creating fraudulent accounts to achieve objectives like making false claims (for example, signing up for an online insurance account solely to file a fraudulent claim) or to exploit new customer benefits and incentives. Massive account creation is also a first step in launching an SMS pumping attack.
* **Account Aging**: Attackers may create a large number of accounts and allow them to age over time, making them appear more legitimate for future, more sophisticated attacks.
* **Service Disruption**: High-volume signup attempts can overwhelm an organization's systems, potentially leading to denial-of-service by exceeding global [rate limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy) and hindering legitimate users' ability to access services.
* **Username Enumeration ([T1087](https://attack.mitre.org/techniques/T1087/))**: Attackers may rapidly attempt to sign up for a large number of accounts to determine if specific usernames already exist within a system. Attackers can use this information for targeted attacks like credential stuffing or phishing.

## Detect signup attacks

Regardless of an attacker's objective, signup attacks leave a trail of specific log events that are crucial for detection and analysis.

Use [**Security Center**](https://manage.auth0.com/#/security/center/overview) to monitor potential attacks against your tenant.
You can use the Auth0 [open source library of detection rules](https://github.com/auth0/auth0-customer-detections) to build and contribute your own detection rules, for example, the rules for [signup fraud by suspicious domains](https://github.com/auth0/auth0-customer-detections/blob/main/detections/risk_of_signup_fraud_by_disposable_domains.yml) and [signup fraud by high volumes](https://github.com/auth0/auth0-customer-detections/blob/main/detections/risk_of_signup_fraud_by_volume.yml).

Key indicators include log event types such as `fs`, `ss`, and `signup_pwd_leak` in [Auth0 tenant logs](/docs/deploy-monitor/logs). During the reconnaissance phase, you might observe repeated HTTP `POST` requests targeting your tenant's [Signup endpoint](/docs/api/authentication/signup/create-a-new-user). This activity often signals an attacker's initial attempts to probe your system for vulnerabilities or to test the efficacy of their automated signup processes.

For advanced analysis or to correlate login activities with applications outside Auth0, enable [log streaming](/docs/deploy-monitor/logs/log-streaming) to the [log streaming service](/docs/deploy-monitor/logs/log-streaming#supported-log-streaming-services) of your choice.

## Mitigation strategies

To mitigate signup attacks, we recommend combining proactive measures with real-time detection and response in a multi-layered approach. Review the following strategies to protect your system:

* **[Suspicious IP Throttling](/docs/secure/attack-protection/suspicious-ip-throttling)**: Implement aggressive signup thresholds for suspicious IP addresses to prevent high-volume signup attempts from a single source.
* **[Bot Detection](/docs/secure/attack-protection/bot-detection)**: Employ robust bot detection mechanisms to identify and block automated signup attempts by enabling Auth0's Bot Detection and configuring your bot detection level to High.
* **Aggressive CAPTCHA requirements**: For a more aggressive response at the cost of higher friction, configure CAPTCHA to be always presented during the signup process. While this introduces a slight inconvenience for legitimate users, it can hinder bot activity.
* **[Passwordless authentication](/docs/authenticate/passwordless#passwordless-authentication)**: Use passwordless authentication methods. This forces attackers to maintain persistent access to the primary identifier (for example, email or phone number) used during signup, making it more difficult to create and control numerous fraudulent accounts.
* **Improved authentication factors**: Use [WebAuthn](/docs/authenticate/login/auth0-universal-login/passwordless-login/webauthn-device-biometrics) as an authentication factor to provide phishing resistance and stop attacker objectives like SMS pumping fraud entirely.
* **[Tenant Access Control List (ACL)](/docs/secure/tenant-access-control-list)**: Configure [Tenant ACLs](/docs/secure/tenant-access-control-list) to block malicious traffic.
* **[Pre-user Registration Triggers](/docs/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger)**: Use pre-user registration triggers to enforce identity proofing measures. This could involve simple steps like requiring email validation before account activation or more complex verification processes depending on your risk profile.
* **Force verification on signup**: Configure [email verification on signup](/docs/manage-users/user-accounts/verify-emails) to require users to verify their emails before signin, ideally through a one-time password (OTP).
* **Web Application Firewall (WAF) rules**: If you are using a [custom domain behind a reverse proxy](/docs/customize/custom-domains/self-managed-certificates#configure-reverse-proxy), configure WAF rules to block known malicious IP ranges, detect suspicious request patterns, and mitigate common attack vectors targeting your Signup endpoint.
* **Disable Signup (most extreme)**: In severe or persistent attack scenarios, or for applications in which user self-registration is not essential, the most extreme measure is to temporarily or permanently disable new user signup.
* **Delete or block fraudulent accounts**: After identifying fraudulent accounts, you can use Auth0's <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to [delete](/docs/api/management/v2/users/delete-users-by-id) or [block](/docs/api/management/v2/users/patch-users-by-id) fraudulent accounts. For bulk operations, be mindful of [Management API rate limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy) and [contact support](https://support.auth0.com/) if there is a risk of exceeding your rate limit.

To learn more about implementing detection and response strategies, read [Detecting Signup Fraud: 3 Ways to Use Auth0 Logs to Protect Your Business](https://auth0.com/blog/detecting-signup-fraud-3-ways-to-use-auth0-logs-to-protect-your-business/).


# Prevent Attacks and Redirect Users with OAuth 2.0 State Parameters
Source: https://auth0.com/docs/secure/attack-protection/state-parameters

Describes how to use the state parameter in authentication requests to help prevent CSRF attacks and restore state

Authorization protocols provide a `state` parameter that allows you to restore the previous state of your application. The `state` parameter preserves some state objects set by the client in the Authorization request and makes it available to the client in the response.

## CSRF attacks

The primary reason for using the `state` parameter is to mitigate [CSRF attacks](https://en.wikipedia.org/wiki/Cross-site_request_forgery) by using a unique and non-guessable value associated with each authentication request about to be initiated. That value allows you to prevent the attack by confirming that the value coming from the response matches the one you sent.

The `state` parameter is a string so you can encode any other information in it. You send a random value when starting an authentication request and validate the received value when processing the response. You store something on the client application side (in cookies, session, or localstorage) that allows you to perform the validation. If you receive a response with a state that doesn't match, you can infer that you may be the target of an attack because this is either a response for an unsolicited request or someone trying to forge the response.

A CSRF attack specifically targets state-changing requests to initiate an action instead of getting user data because the attacker has no way to see the response to the forged request. For the most basic cases the state parameter should be a <Tooltip href="/docs/glossary?term=nonce">nonce</Tooltip>, used to correlate the request with the response received from the authentication.

Most modern OIDC and <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> SDKs, including Auth0.js in single-page applications, handle the state generation and validation automatically.

### Set and compare state parameter values

1. Before redirecting a request to the Identity Provider (IdP), have the app generate a random string. For example:

   ```text lines theme={null}
   xyzABC123
   ```

   The allowed length for state is not unlimited. If you get the error `414 Request-URI Too Large`, try a smaller value.

2. Store the string locally. For example:

   ```text lines theme={null}
   storeStateLocally(xyzABC123)
   ```

3. Add the `state` parameter to the request (URL-encoding if necessary). For example:

   ```javascript lines theme={null}
   // Encode the String   
   tenant.auth0.com/authorize?...&state=xyzABC123
   ```

   After the request is sent, the user is redirected back to the application by Auth0. The `state` value will be included in this redirect. Note that depending on the type of connection used, this value might be in the body of the request or in the query string.

   ```text lines theme={null}
   /callback?...&state=xyzABC123
   ```

4. Retrieve the returned `state` value and compare it with the one you stored earlier. If the values match, then approve the authentication response, else deny it.

   ```javascript lines theme={null}
   // Decode the String
   var decodedString = Base64.decode(encodedString);
   if(receivedState === retrieveStateStoredLocally()) {
    // Authorized request
   } 
   else {
     // This response is not for us, reject it
   }
   ```

## Redirect users

You can use the `state` parameter to encode an application state that will put the user where they were before the authentication process started. For example, if a user intends to access a protected page in your application, and that action triggers the request to authenticate, you can store that URL to redirect the user back to their intended page after the authentication finishes.

Generate and store a nonce locally (in cookies, session, or local storage) along with any desired state data like the redirect URL. Use the nonce as a state in the protocol message. If the returned state matches the stored nonce, accept the OAuth2 message and fetch the corresponding state data from storage. This is the approach we use in auth0.js.

### Use the stored URL to redirect users

1. Set the nonce state parameter value that you used to mitigate CSRF attacks as explained above.

2. Store the nonce locally, using it as the key to store all the other application state information such as the URL where the user intended to go. For example:

   ```json lines theme={null}
   {
     "xyzABC123" : {
       redirectUrl: '/protectedResource',
       expiresOn: [...]
     }
   }
   ```

3. Authenticate the user, [sending the generated nonce as the state](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post/mitigate-replay-attacks-when-using-the-implicit-flow).

4. As part of the callback processing and response validation, verify that the state returned matches the nonce stored locally. If it does, retrieve the rest of the application state (like the `redirectUrl`).

5. Once you complete the callback processing, redirect the user to the URL previously stored.

### Alternate redirect method

1. Generate and store a nonce value locally.
2. Encode any desired state (like the redirect URL) along with the nonce in a protected message (that will need to be encrypted/signed to avoid tampering).
3. In the response processing, unprotect the message, getting the nonce and other properties stored.
4. Validate that the included nonce matches what was stored locally and, if so, accept the OAuth2 message.

## Limitations and considerations

* Choose a storage method based on your application type.

  <table>
    <thead>
      <tr>
        <th>App Type</th>
        <th>Storage Recommendation</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Regular Web App</td>
        <td>Cookie or session</td>
      </tr>

      <tr>
        <td>SPA</td>
        <td>Local browser</td>
      </tr>

      <tr>
        <td>Native App</td>
        <td>Memory or local</td>
      </tr>
    </tbody>
  </table>
* From a security perspective, neither the request nor the response is integrity-protected so a user can manipulate them. That is true for adding a parameter to the `redirect_uri` as well.
* The allowed length for state parameter value is not unlimited. If you get the error `414 Request-URI Too Large`, try a smaller value.
* Passing URLs in plaintext or in any predictable way is unsafe. Ensure that the state parameter value is:

  * Unique and opaque to ensure that it can be used for defense against CSRF and phishing attacks.
  * If stored in a cookie, it should be signed to prevent forgery.

## Learn more

* [Which OAuth 2.0 Flow Should I Use?](/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use)
* [Sessions](/docs/manage-users/sessions)


# Suspicious IP Throttling
Source: https://auth0.com/docs/secure/attack-protection/suspicious-ip-throttling

Learn how suspicious IP throttling works and how to configure it in the Auth0 Dashboard.

<Tooltip href="/docs/glossary?term=Suspicious+IP+Throttling">Suspicious IP Throttling</Tooltip> blocks traffic from any IP address that rapidly attempts too many logins or signups. This helps protect your applications from high-velocity attacks that target multiple accounts.

Suspicious IP throttling is enabled by default when you create your Auth0 tenant. When Auth0 detects a high number of signup attempts or failed login attempts from an IP address, it responds to subsequent attempts with the [HTTP 429 Too Many Requests status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) until that IP address is no longer throttled.

For more information on signup and failed login attempts logged by your tenant, read [Log Type Codes](/docs/deploy-monitor/logs/log-event-type-codes).

## Configure Suspicious IP Throttling

You can configure Suspicious IP Throttling in the [Auth0 Dashboard](https://manage.auth0.com/#) or with the [Auth0 Management API](https://auth0.com/docs/api/management/v2/attack-protection/patch-suspicious-ip-throttling).

<Warning>
  Auth0 strongly recommends that you do not disable Suspicious IP Throttling.
</Warning>

1. Go to [Dashboard > Security > Attack Protection](https://manage.auth0.com/#/security/attack-protection), and select **Suspicious IP Throttling**.
2. Select the toggle at the top of the page to enable or disable Suspicious IP Throttling.

<Frame>
  <img alt="Auth0 suspicious IP throttling settings " />
</Frame>

## Allow trusted IP addresses exceed throttling limits

You can make up to 100 discrete IP addresses and/or CIDR ranges (IPv4 or IPv6) exempt from Suspicious IP Throttling by adding them to the **IP AllowList**. Auth0 does not block or alert tenant administrators when these IP addresses exceed the throttling limits.

1. Go to [Dashboard > Security > Attack Protection](https://manage.auth0.com/#/security/attack-protection), and select **Suspicious IP Throttling**.
2. In the **IP AllowList** field, enter the IP addresses and/or CIDR ranges you want to allow unlimited login and signup attempts. Separate multiple IP addresses and/or CIDR ranges with commas.

## Configure response

By default, Auth0 sends email to tenant administrators when an IP address is marked as suspicious.

You can configure how Auth0 responds to high-velocity login or signup attempts.

<Warning>
  Enabling attack protection features without any response settings enabled activates Monitoring mode, which records related events in your tenant log only. To learn more, read [View Attack Protection Log Events](/docs/secure/attack-protection/view-attack-protection-events).
</Warning>

1. Go to [Dashboard > Security > Attack Protection](https://manage.auth0.com/#/security/attack-protection), and select **Suspicious IP Throttling.**
2. Locate the **Response** section.
3. In the **Block Settings** section, enable **Limit high-velocity traffic targeting too many accounts** to throttle traffic from IP addresses that exceed the login or signup threshold.
4. In the **Notifications** section, enable **Send notification to account administrator** to automatically send an email to tenant administrators when an IP address exceeds the login or signup threshold.
5. Select **Save**.

## Configure throttling limits and rates

You can customize how Auth0 throttles suspicious IP addresses. You can change:

* The maximum number of failed login and signup attempts allowed from a given IP address.
* The rate at which throttled IP addresses allow new login and signup attempts.

For more information on maximum attempts and throttling rate and how they work, read [How suspicious IP throttling works](#how-suspicious-ip-throttling-works).

1. Go to [Dashboard > Security > Attack Protection](https://manage.auth0.com/#/security/attack-protection), and select **Suspicious IP Throttling.**

   <Frame>
     <img alt="Suspicious IP throttling customization in the Auth0 dashboard" />
   </Frame>
2. Locate the **Detection** section.
3. Select **Custom** for **Suspicious IP Thresholds.**
4. Configure the **Login Threshold** settings:

   * **Maximum Attempts**: Enter the number of failed login attempts a single IP address can make in one day before Auth0 blocks the next attempt.
   * **Throttling Rate**: Enter the rate at which to grant new login tokens.
5. Configure the **Signup Threshold** settings:

   * **Maximum Attempts**: Enter the number of signup attempts a single IP address can make in one minute before Auth0 blocks the next attempt.
   * **Throttling Rate**: Enter the rate at which to grant new signup tokens.
6. Select **Save**.

### How suspicious IP throttling works

Auth0 counts and allows login and signup attempts separately. IP addresses suspended from further login attempts can still try to sign up. IP addresses suspended from further signup attempts can still try to log in.

#### Login attempts

Auth0 throttles any IP address that attempts and fails too many logins in a day. The login throttling rate determines how many login attempts Auth0 grants to an IP address evenly over 24 hours. For example, a throttling rate of 100 means that Auth0 grants a new attempt approximately every 15 minutes.

#### Signup attempts

Auth0 throttles any IP address that attempts too many total signups in a minute. For example, if an IP address makes 50 signup attempts, Auth0 blocks further attempts. Unlike logins, the signup attempts do not need to be failures.

The signup throttling rate determines how many signup attempts Auth0 grants to an IP address evenly over 24 hours. For example, a throttling rate of 72,000 means that Auth0 grants a new attempt approximately every second.

#### Malformed requests and schema validation errors

Login and signup requests that do not follow the proper structure or formatting are not considered valid attempts, and therefore do not count toward your configured threshold.

For more information about login and signup requests, read [Auth0 Authentication API](https://auth0.com/docs/api/authentication).

## Special cases

Because suspicious IP throttling depends on the IP address of the user, the following use cases require additional configuration:

* **Using the <Tooltip href="/docs/glossary?term=Resource+Owner">Resource Owner</Tooltip> Password Grant from the backend of an application**: Using this call does not get the IP address of the user; however, to make suspicious IP throttling work correctly, you can configure your application to send the IP address of the user as part of the request. See [Avoid Common Issues with Resource Owner Password Flow and Attack Protection: Send the user's IP address from your server](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow/avoid-common-issues-with-resource-owner-password-flow-and-attack-protection).
* **Authenticating a large number of users from the same IP address**: Users who are behind a proxy are more likely to reach set limits and trigger throttling. You can avoid erroneously triggering throttling by configuring an AllowList for the proxy's IP and CIDR range. See [Avoid Common Issues with Resource Owner Password Flow and Attack Protection: Configure your Application to trust the IP address](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow/avoid-common-issues-with-resource-owner-password-flow-and-attack-protection).

## Learn more

* [Brute-Force Protection](/docs/secure/attack-protection/brute-force-protection)
* [Bot Detection](/docs/secure/attack-protection/bot-detection)
* [Breached Password Detection](/docs/secure/attack-protection/breached-password-detection)
* [Customize Blocked Account Emails](/docs/customize/email/customize-blocked-account-emails)
* [View Attack Protection Log Events](/docs/secure/attack-protection/view-attack-protection-events)
* [User/Password Authentication Rate Limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/database-connections-rate-limits)


# Use Akamai Supplemental Signals in Actions
Source: https://auth0.com/docs/secure/attack-protection/use-akamai-supplemental-signals-actions



<Warning>
  **Auth0 Supplemental Signals is currently in Early Access.**

  By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal). To learn more about Auth0 product release stages, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

<Info>
  **Before you start**

  To use Akamai supplemental signals in Actions, you must:

  * [Configure Akamai as a reverse proxy](/docs/customize/custom-domains/self-managed-certificates)
  * [Configure Akamai to Send Supplemental Signals](./configure-akamai-supplemental-signals)
</Info>

If you have configured Akamai as a reverse proxy and set it up to send supplemental signals to Auth0, you can use the data provided in those signals in [Auth0 Actions](/docs/customize/actions).

## Supported supplemental signals by Action trigger

| Trigger                | Supplemental signal objects                                                  | Event object                                                                                                                                                                          |
| ---------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Login                  | <ul><li><code>akamaiBot</code></li><li><code>akamaiUserRisk</code></li></ul> | <a href="/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object"><code>authentication.riskAssessment.supplemental.akamai</code></a> |
| Pre-User Registration  | None                                                                         | N/A                                                                                                                                                                                   |
| Post-User Registration | None                                                                         | N/A                                                                                                                                                                                   |
| Send Phone Message     | None                                                                         | N/A                                                                                                                                                                                   |
| Post-Challenge         | None                                                                         | N/A                                                                                                                                                                                   |
| Post-Change Password   | None                                                                         | N/A                                                                                                                                                                                   |
| Credentials Exchange   | None                                                                         | N/A                                                                                                                                                                                   |

## Supplemental signal object schemas

The `akamaiBot` and `akamaiUserRisk` objects contain multiple properties you can use to customize your authentication flow.

<ResponseField name="akamaiBot" type="object">
  <Expandable>
    <ResponseField name="action" type="string">
      The action of the Akamai bot manager results.

      Example: `Monitor`
    </ResponseField>

    <ResponseField name="botCategory" type="string[]">
      The bot cateogry of the Akamai bot manager results.

      Example: `["Web Search Engine Bots"]`
    </ResponseField>

    <ResponseField name="botScore" type="number">
      The bot score of the Akamai bot manager results.

      Example: `90`
    </ResponseField>

    <ResponseField name="botScoreResponseSegment" type="string">
      The bot score response segment of the Akamai bot manager results.

      Example: `aggressive`
    </ResponseField>

    <ResponseField name="botnetId" type="string">
      The botnet ID of the Akamai bot manager results.

      Example: `googlebot`
    </ResponseField>

    <ResponseField name="type" type="string">
      The type of the Akamai bot manager results.

      Example: `Akamai-Categorized Bot`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="akamaiUserRisk" type="object">
  <Expandable>
    <ResponseField name="action" type="string">
      The action of the Akamai user risk assessment.

      Example: `monitor`
    </ResponseField>

    <ResponseField name="allow" type="number">
      The allowed status of the Akamai user risk assessment.

      Example: `0`
    </ResponseField>

    <ResponseField name="emailDomain" type="string">
      The email domain of the user.

      Example: `example.com`
    </ResponseField>

    <ResponseField name="general" type="object">
      The general risk of the Akamai user risk assessment.

      Example: `{ aci: “0”, db: “Chrome 85”, di: “0fc91b5ec42f5a471c16a85e3e388ca57697c1a9”, do: “Mac OX X 10” }`
    </ResponseField>

    <ResponseField name="ouid" type="string">
      The OUID of the user.

      Example: `m534264`
    </ResponseField>

    <ResponseField name="requestid" type="string">
      The request ID of the user.

      Example: `19e22e`
    </ResponseField>

    <ResponseField name="risk" type="object">
      The risk of the Akamai user risk assessment.

      Example: `{ ugp: “ie/M”, unp: “432/H” }`
    </ResponseField>

    <ResponseField name="score" type="number">
      The score of the Akamai user risk assessment.

      Example: `0`
    </ResponseField>

    <ResponseField name="status" type="number">
      The status of the Akamai user risk assessment.

      Example: `4`
    </ResponseField>

    <ResponseField name="trust" type="object">
      The trust of the Akamai user risk assessment.

      Example: `{ udbp: "Chrome85", udfp: "25ba44ec3b391ba4ce5fbbd2979635e254775werwe", udop: "Mac OS X 10", ugp: "FR", unp: "12322", utp: "weekday_3" }`
    </ResponseField>

    <ResponseField name="username" type="string">
      The username of the user.

      Example: `testuser@example.com`
    </ResponseField>

    <ResponseField name="uuid" type="string">
      The UUID of the Akamai user risk assessment.

      Example: `86b37525-8047-4a3c-8d7a-23e99666da05`
    </ResponseField>
  </Expandable>
</ResponseField>

## Use cases

<AccordionGroup>
  <Accordion title="Revoke a session based on Akamai Account Protector results">
    Here’s an example of how you could revoke a session based on the `akamaiUserRisk.score` property:

    ```javascript theme={null}
    exports.onExecutePostLogin = async (event, api) => {
      const userRiskHeader = event.authentication?.riskAssessment?.supplemental?.akamai?.akamaiUserRisk;
      if (userRiskHeader?.score && userRiskHeader?.score >= 90) {
            console.log('User is deemed high risk.');
            //This will revoke session cookies to deny login.
            api.session.revoke('Session revoked, User risk score is greater than 90.');
        }
    };

    ```

    Please note the use of the `api.session.revoke` method (compared to the `api.access.deny` method). Using the `revoke` method ensures that if the user refreshes the application, the Akamai supplemental signals are sent with the authentication request and the post-login Action flow is triggered.
  </Accordion>

  <Accordion title="Prompt multi-factor authentication (MFA) based on Akamai Bot Manager results">
    Here’s an example of how you could enforce MFA based on the `akamaiBot.score` property.

    #### Enforce MFA

    This Action performs two tasks:

    1. **Update [app metadata](/docs/manage-users/user-accounts/metadata/metadata-fields-data)**: If the score property exceeds a specified value, record that MFA is required for the session.
    2. **Require MFA**: If the score property exceeds a specified value or if there is a record in the app metadata indicating MFA is required for the session, enforce MFA.

    ```javascript theme={null}
    exports.onExecutePostLogin = async (event, api) => {
      const userRiskHeader = event.authentication?.riskAssessment?.supplemental?.akamai?.akamaiUserRisk;

      if (userRiskHeader?.score && userRiskHeader?.score >= 90) {
        console.log(`Setting app metadata for session id: ${event.session?.id}`);
        api.user.setAppMetadata(`mfa_required_${event.session?.id}`, true);
      }

      if (userRiskHeader?.score && userRiskHeader?.score >= 90 ||
          event.user.app_metadata[`mfa_required_${event.session?.id}`]) {
            console.log(`Requiring MFA FOR Session id: ${event.session?.id}`);
            api.multifactor.enable('any', {allowRememberBrowser: false});
      }
    };

    ```

    #### Clean up app metadata

    This Action removes session-specific MFA information from app metadata after the user completes MFA successfully.

    ```javascript theme={null}
    exports.onExecutePostLogin = async (event, api) => {
      const mfaMethod = event.authentication?.methods.find((method) => {
        return method.name === 'mfa';
      });

      if (mfaMethod) {
        console.log(`Removing MFA requirement for session id: ${event.session?.id}`);
        api.user.setAppMetadata(`mfa_required_${event.session?.id}`, undefined);
      }
    };
    ```
  </Accordion>
</AccordionGroup>


# View Attack Protection Log Events
Source: https://auth0.com/docs/secure/attack-protection/view-attack-protection-events

Describes how to use tenant traffic log data to view attack protection events.

Your tenant logs contain useful data that you can use to build charts to look at the profile of the traffic going through your tenant. This is helpful when evaluating <Tooltip href="/docs/glossary?term=attack+protection">attack protection</Tooltip> activity. For example, you can look for the following events to determine if you're under attack:

* Abnormal bursts in traffic to the login flow that result in errors (such as wrong username or password errors).
* Abnormal bursts in traffic coming from IP locales that are not expected.

These events tend to happen without much change to the rate of successful logins.

You can use your tenant log data `event` field to view tenant traffic data. We recommend building a daily histogram of failure events of the following types:

<table>
  <thead>
    <tr>
      <th><strong>Event Code</strong></th>
      <th><strong>Event</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>f</code></td>
      <td>Failed login</td>
    </tr>

    <tr>
      <td><code>fcoa</code></td>
      <td>Failed cross-origin authentication</td>
    </tr>

    <tr>
      <td><code>feccft</code></td>
      <td>Failed exchange</td>
    </tr>

    <tr>
      <td><code>fepft</code></td>
      <td>Failed exchange</td>
    </tr>

    <tr>
      <td><code>fsa</code></td>
      <td>Failed silent authentication</td>
    </tr>

    <tr>
      <td><code>fu</code></td>
      <td>Failed login (invalid email/username)</td>
    </tr>

    <tr>
      <td><code>pla</code></td>
      <td>Pre-login assessment</td>
    </tr>

    <tr>
      <td><code>sepft</code></td>
      <td>Success exchange</td>
    </tr>
  </tbody>
</table>

These failure events depend on the flow you have set up with Auth0.

The following example shows a credential stuffing attack on 02/13, with a large surge of events of type `fu` which is a failed username (typical of a credential stuffing attack).

<Frame>
  <img alt="Example traffic failure trends graph" />
</Frame>

## Rate of errors in login flow

Look for a surge or an abnormal number of errors for incorrect username or password. For example: Do you expect >30,000 errors per hour?

<table>
  <thead>
    <tr>
      <th>Event Code</th>
      <th>Event</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>s</code></td>
      <td>Login success</td>
    </tr>

    <tr>
      <td><code>fu</code></td>
      <td>Failed login, invalid email/username</td>
    </tr>

    <tr>
      <td><code>fp</code></td>
      <td>Failed login, incorrect password</td>
    </tr>
  </tbody>
</table>

Here's an example of what the data might look like.

<Frame>
  <img alt="Example graph of surge in login failures compared to normal traffic" />
</Frame>

## Rate of attack protection events

Look for abnormally high traffic for attack protection events such as <Tooltip href="/docs/glossary?term=breached+password+detection">breached password detection</Tooltip> or brute-force attacks for multiple accounts.

<table>
  <thead>
    <tr>
      <th>Event Code</th>
      <th>Event</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>limit\_mu</code></td>
      <td>Blocked IP address</td>
    </tr>

    <tr>
      <td><code>limit\_wc</code></td>
      <td>Blocked account</td>
    </tr>

    <tr>
      <td><code>pwd\_leak</code></td>
      <td>Breached password during login</td>
    </tr>

    <tr>
      <td><code>signup\_pwd\_leak</code></td>
      <td>Breached password during signup</td>
    </tr>

    <tr>
      <td><code>reset\_pwd\_leak</code></td>
      <td>Breached password during password recovery</td>
    </tr>
  </tbody>
</table>

Here's an example of what the data might look like.

<Frame>
  <img alt="Example graph of anomaly detection events" />
</Frame>

## Number of IPs producing errors and their locations

Look for a high number of IPs from locales that do not make sense. For example: Do you expect traffic from 10,000 IPs from Russia every day? Observe `ip` address data in conjunction with `fu` event traffic to determine where the failure traffic is coming from.

IP geolocation data isn't available in the tenant logs unless you're able to enrich it from another location. The IP locale is only available from Kibana where the logs are already enriched with the information.

Here's an example of what the data might look like:

<Frame>
  <img alt="Example graph of failed access attempts by region" />
</Frame>

## Learn more

* [Bot Detection](/docs/secure/attack-protection/bot-detection)
* [Breached Password Detection](/docs/secure/attack-protection/breached-password-detection)
* [Brute-Force Protection](/docs/secure/attack-protection/brute-force-protection)
* [Logs](/docs/deploy-monitor/logs)
* [Log Search Query Syntax](/docs/deploy-monitor/logs/log-search-query-syntax)


# Continuous Session Protection
Source: https://auth0.com/docs/secure/continuous-session-protection

Describes the key benefits of Auth0's Continuous Session Protection.

Auth0 Continuous Session Protection empowers developers to enhance security and tailor the user experience through customizable session and <Tooltip href="/docs/glossary?term=refresh+token">refresh token</Tooltip> management.

Using Continuous Session Protection, developers can leverage [Auth0 Actions](/docs/customize/actions) to safeguard user sessions and refresh tokens by utilizing detailed session information such as IP addresses, expiration dates, device details, and more.

Key benefits of Continuous Session Protection include:

* **Proactive Risk Mitigation**: Developers can use session information, such as IP addresses, ASN, and device details to detect and respond to risks such as session hijacking. By integrating with Auth0’s risk assessments, you can automatically revoke sessions or refresh tokens if anomalies are detected, ensuring that only legitimate users maintain access.
* **Comprehensive Token and Session Management**: Tailor the session and refresh token lifetime based on user attributes or behaviors. For instance, developers can dynamically adjust session expiration or idle timeout settings depending on factors like user organization, role, or connection type, providing a more personalized and secure user experience.
* **Surface Enriched Info**: By leveraging refresh tokens and session information, developers can feed external systems to evaluate risks or enrich user data within their customer’s databases

With Auth0 Continuous Session Protection, you can ensure that your authentication processes are not only secure but also adaptable to the unique needs of your users, providing a seamless and protected experience across all touchpoints.

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/secure/tokens/refresh-tokens/manage-refresh-tokens-actions">Refresh Tokens with Actions</a></td>
      <td>How to manage refresh tokens with Actions</td>
    </tr>

    <tr>
      <td><a href="/docs/manage-users/sessions/manage-sessions-actions">Sessions with Actions</a></td>
      <td>How to manage sessions with Actions.</td>
    </tr>
  </tbody>
</table>


# Highly Regulated Identity
Source: https://auth0.com/docs/secure/highly-regulated-identity

Learn about Highly Regulated Identity, Auth0's Financial-Grade Identity solution.

<Callout icon="file-lines">
  To use Highly Regulated Identity features, you must have an Enterprise Plan with the Highly Regulated Identity add-on. Refer to [Auth0 Pricing](https://auth0.com/pricing/) for details.
</Callout>

Highly Regulated Identity (HRI) is Auth0’s Financial-Grade Identity™ solution to secure sensitive data operations and services important for your business. Initially targeting highly regulated industries like finance and healthcare, Highly Regulated Identity raises the security level to protect a wide range of customer use cases, including but not limited to money transfers, digital payments, and access to medical records. You can also use Highly Regulated Identity for other sensitive operations that require enhanced security, such as to approve changes in administrative credentials, secure privileged access to a web portal, and more.

To secure your sensitive business operations, Highly Regulated Identity provides:

* [Advanced security with OpenID Connect (FAPI)](#advanced-security-with-openid-connect-fapi-)
* [Strong Customer Authentication (SCA)](#strong-customer-authentication-sca-) and [Dynamic Linking](#dynamic-linking)
* [Confidentiality and integrity protection](#confidentiality-and-integrity-protection)
* [Strong application authentication](#stronger-application-authentication)
* [Protect access tokens with Token Binding](#protect-access-tokens-with-token-binding)
* [Customizable approval flows for better user experience](#customizable-approval-flows-for-better-user-experience)

## Advanced security with OpenID Connect (FAPI)

[OpenID FAPI](https://openid.net/wg/fapi/specifications/) is a suite of security and privacy specifications developed by the <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Foundation. APIs that meet the FAPI standards are classified as “financial-grade,” which means that they provide robust authentication and authorization mechanisms that help secure access to financial and other sensitive data and services.

Auth0 is a certified FAPI provider. To learn more about the security improvements we introduced to meet FAPI standards, see the following sections:

* [Confidentiality and integrity protection](#confidentiality-and-integrity-protection)
* [Strong application authentication](#stronger-application-authentication)
* [Protect access tokens with Token Binding](#protect-access-tokens-with-token-binding)

For more information on FAPI, see OpenID's [Open Banking, Open Data, and Financial-grade APIs](https://openid.net/wordpress-content/uploads/2022/03/OIDF-Whitepaper_Open-Banking-Open-Data-and-Financial-Grade-APIs_2022-03-16.pdf) whitepaper and the [FAPI Working Group specifications](https://openid.net/wg/fapi/specifications/).

<Frame>
  <img alt="" />
</Frame>

## Strong Customer Authentication (SCA)

<Frame>
  <img alt="" />
</Frame>

Introduced by Europe’s [Payment Services Directive (PSD2)](https://www.europeanpaymentscouncil.eu/sites/default/files/infographic/2018-04/EPC_Infographic_PSD2_April%202018.pdf), Strong Customer Authentication (SCA), mandates the use of at least two distinct authentication factors out of the following three:

* Something the user knows (e.g., a password)
* Something the user possesses (e.g., a device)
* Something intrinsic to the user (e.g., a fingerprint)

The authentication factors must be independent so that compromising one does not jeopardize the others. SCA is quickly becoming the worldwide standard for safeguarding sensitive data and services.

To help with SCA compliance, Auth0 offers various authentication factors that enroll and challenge users during a login transaction. Highly Regulated Identity leverages the following authentication factors to secure your transactions:

* Mobile push notifications
* SMS
* Email
* WebAuthn

Using [Actions](/docs/customize/actions), you can dynamically determine which authentication factors to use. This gives you the flexibility to customize your code logic. For example, you can add a second authentication factor for payments above 10 USD. To learn more, read [Apply dynamic policy](/docs/secure/highly-regulated-identity/transactional-authorization-with-authorization-code-flow#apply-dynamic-policy).

## Dynamic Linking

PSD2 requires that payment service providers implement Dynamic Linking along with Strong Customer Authentication. Dynamic Linking presents the user with transaction details for their explicit validation and approval and uniquely links the authorization and the transaction details. This ensures a good user experience and helps with regulatory compliance.

To enable Dynamic Linking, you can use Rich Authorization Requests (RAR) to pass fine-grained transaction authorization data to the <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> authorization endpoint. The following code sample shows an `authorization_details` JSON object, which contains information like the payment type, amount, currency, and recipient:

```json lines theme={null}
"authorization_details": [
 {
   "type": "one_time_payment",
   "amount": {
     "amount": 2460.46,
     "currency": "USD"
   },
   "sourceAccount": "xxxxxxxxxxx4567",
   "recipient": "Acme Travel, Inc.",
   "concept": "All Inclusive Resort Package for Two",
 }
]
```

`authorization_details` is assigned a unique transaction reference, which Auth0 uses to prompt the user to perform step-up authentication:

* Use push notifications to show transaction details and get approval on a separate device such as a mobile phone application.
* Use SMS, email, or WebAuthn to confirm the details on the device that originated the transaction after the user completes the second authentication factor.

<Warning>
  Do not pass fine-grained transaction authorization data or other sensitive or regulated data outside of `authorization_details`.
</Warning>

If the user confirms the details, the transaction progresses and Auth0 issues an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> associated with the now-approved authorization\_details. Developers can also add the unique transaction reference to the access token. As a result, your API servers can later validate the approved transaction details when receiving and servicing API requests.

To learn more about RAR, read [Authorization Code Flow with Rich Authorization Requests](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-rar).

## Confidentiality and integrity protection

Authorization details may include account numbers, monetary amounts, merchant names, and other highly sensitive information that are passed in URLs or access tokens that are not secure. To protect sensitive data from unauthorized access and tampering, Highly Regulated Identity offers comprehensive confidentiality and integrity protection.

### Protect sensitive data in the front channel

To protect sensitive data in the front channel, such as a web browser, Highly Regulated Identity offers the following solutions as part of the FAPI 1 Advanced Security profile.

#### Pushed Authorization Requests (PAR)

[PAR](https://datatracker.ietf.org/doc/rfc9126/) introduces a new endpoint, which allows clients to directly push the payload of an OAuth 2.0 authorization request to the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip> (i.e. Auth0 in this case). This avoids passing the authorization parameters via the insecure front channel (i.e., the browser), thus reducing the risk of unauthorized access to authorization parameters by an intermediary.

To learn more about PAR, read [Authorization Code Flow with Pushed Authorization Requests (PAR)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-par) and [Configure Pushed Authorization Requests (PAR)](/docs/get-started/applications/configure-par).

#### JWT-Secured Authorization Request (JAR)

[JAR](https://datatracker.ietf.org/doc/rfc9101/) is an OAuth2 protocol extension that enhances the security of authorization requests. It does so by using a <Tooltip href="/docs/glossary?term=JSON+Web+Token">JSON Web Token</Tooltip> (JWT) request parameter to protect the integrity and, optionally, the confidentiality of the authorization request parameters.

To learn more about JAR, read [Authorization Code Flow with JWT-Secured Authorization Requests (JAR)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-jar) and [Configure JWT-Secured Authorization Requests (JAR)](/docs/get-started/applications/configure-jar).

#### Protect sensitive data in access tokens

To protect the authorization details included in access tokens, Highly Regulated Identity provides support for using [JSON Web Encryption (JWE)](https://datatracker.ietf.org/doc/html/rfc7516) to encrypt the payload of access tokens. This protects access tokens from application-side data breaches and unauthorized inspection into API calls by intermediaries.

To learn more about JWE, read [JSON Web Encryption](/docs/secure/tokens/access-tokens/json-web-encryption) and [Configure JSON Web Encryption](/docs/get-started/apis/configure-json-web-encryption).

## Stronger application authentication

To improve your application authentication security, Highly Regulated Identity offers two different alternatives as part of the FAPI 1 Advanced Security profile:

* [Private Key JWT](http://tools.ietf.org/html/draft-ietf-oauth-jwt-bearer): involves generating a public-private key pair to use as credentials to authenticate an application. It is already available for customers on the Enterprise plan. To learn more, read [Private Key JWT Authentication](/docs/secure/application-credentials#private-key-jwt-authentication).
* [mTLS for OAuth](https://datatracker.ietf.org/doc/html/rfc8705): involves registering a standard X.509 certificate linked to an application on your tenant. The certificate can either be CA-issued or self-signed. Following standard mTLS procedures, the private key corresponding to the certificate is used on the client side to establish the mTLS tunnel when sending requests to your Auth0 tenant endpoints. As a result, Auth0 can authenticate the application without transmitting secrets over the network. To learn more, read [mTLS for OAuth](/docs/get-started/authentication-and-authorization-flow/authenticate-with-mtls).

With both Private Key JWT and OAuth 2.0 mTLS, you can rotate credentials with zero downtime by temporarily keeping two active keys and/or certificates at the same time for a given application.

## Protect access tokens with Token Binding

Supporting mTLS also adds the ability to use Token Binding or Sender Constraining. Token Binding associates the thumbprint of the client certificate used for establishing the mTLS tunnel to an access token. When the client consumes an API using the certificate-bound access token, the API server is then able to verify whether the client is also using the associated client certificate. As a result, even if the access token is compromised, malicious actors who don’t know the client certificate still cannot access protected resources.

**Note:** Token Binding operates independently of the application's authentication method and does not require the pre-registration of the client certificate. To learn more, read [Configure Sender Constraining](/docs/secure/sender-constraining/configure-sender-constraining).

## Customizable approval flows for better user experience

When designing real-world solutions for financial-grade security, it’s important to consider user experience. Applying one-size-fits-all authentication flows for all transactions is not as effective as dynamically adjusting based on transaction details and use cases.

You can customize your authentication flow using [Actions](/docs/customize/actions). For example, after the user logs in, you can inspect transaction details received via RAR, list the user’s enrolled and already validated authentication factors, and use external services, such as risk evaluation engines, to determine the next authentication factor to use. To learn more, read [Apply dynamic policy](/docs/secure/highly-regulated-identity/transactional-authorization-with-authorization-code-flow#apply-dynamic-policy).

The New <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> templates also enable you to customize the attributes displayed on the transaction approval screen depending on the type of transaction and other authorization details. To learn more, read [Configure Rich Authorization Requests (RAR)](/docs/get-started/apis/configure-rich-authorization-requests).

## Learn more

To learn how Highly Regulated Identity works from end-to-end to authorize a one-time transaction, read [Transactional Authorization with Authorization Code Flow](/docs/secure/highly-regulated-identity/transactional-authorization-with-authorization-code-flow).


# Customer Managed Keys
Source: https://auth0.com/docs/secure/highly-regulated-identity/customer-managed-keys

Learn how to manage your Keys with Customer Managed Keys.

Using Auth0 Customer Managed Keys allows you to configure the lifecycle of your Tenant Master Key and bring your own Customer Provided Root Key to replace the Environment Root Key for your Auth0 tenant.

Customer Managed Keys provides two methods of managing your keys:

* **Control Your Own Key:** Allows users with the  [Key Management Editor role](/docs/get-started/manage-dashboard-access/add-dashboard-users) to customize the lifecycle of the Tenant Master Key in Auth0 KMS.
* **Bring Your Own Key:** Allows users with the  [Key Management Editor role](/docs/get-started/manage-dashboard-access/add-dashboard-users) to replace the Auth0 Environment Root Key and import their own wrapped encryption key to the corresponding Auth0 Cloud Hardware Security Module (HSM).

To learn more about Auth0 Keys, [read Auth0 key hierarchy](/docs/secure/highly-regulated-identity/customer-managed-keys#auth0-key-hierarchy).

<Callout icon="file-lines">
  The Customer Managed Keys feature is available to users with the Key Management Editor role. This role is not applied to users by default and needs to be explicitly applied to a Tenant member. To learn more, read [Add Tenant Members](/docs/get-started/manage-dashboard-access/add-dashboard-users).
</Callout>

## Control Your Own Key

You can control the lifecycle of your Tenant Master Key using the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> [Rekey](https://auth0.com/docs/api/management/v2/keys/post-encryption-rekey) endpoint to:

* Rotate the old Tenant Master Key with a newly-created Tenant Master Key.
* Rotate and re-encrypt Namespace Keys with the new Tenant Master Key.

### Permissions

Use the following permissions to provide access to the rekey endpoints:

<table>
  <thead>
    <tr>
      <th><b>Permissions</b></th>
      <th><b>Descriptions</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>create:encryption\_keys</code>
        <code>update:encryption\_keys</code>
      </td>

      <td>
        Users can rotate and re-encrypt the Key hierarchy of an Auth0 tenant with the Management API Rekey endpoint.
      </td>
    </tr>
  </tbody>
</table>

### Endpoint

Use the Management API [Rekey](https://auth0.com/docs/api/management/v2/keys/post-encryption-rekey) endpoint to rotate the Tenant Master Key and rotate and re-encrypt Namespace Keys.

* Rotate the Tenant Master Key: deactivates the currently active Tenant Master Key and creates a new Tenant Master Key.
* Rotate all Namespace Keys in the tenant: deactivate currently active keys and activate new keys.

  * New Namespace Keys are used in new encryption operations.
  * Deactivated Namespace Keys are used to decrypt previously encrypted data.
* Re-encrypts all existing Namespace Keys with the new Tenant Master Key.

<Callout icon="file-lines">
  The endpoint is only available to tenant members with specific authorization scopes in Auth0, by default these scopes are granted to users with the  [Key Management Editor role](/docs/get-started/manage-dashboard-access/add-dashboard-users).
</Callout>

## Bring Your Own Key

<Warning>
  By importing your own Customer Provided Root Key with Bring Your Own Key, you are implicitly deauthorizing Auth0 from managing the lifecycle of the Customer Provided Root Key, except for its deletion.
</Warning>

Bring Your Own Key allows Key Management Editors to securely import a Wrapped Encryption Key (Customer Provided Root Key) to a FIPS 140-2 L3 Hardware Security Module (HSM) in the corresponding Auth0 Cloud.

Using Bring Your Own Key you can:

* Replace the default Auth0 generated Environment Root Key with a new Customer Provided Root Key.
* Rotate and re-encrypt the key hierarchy with the Customer Provided Root Key. For example: create and re-encrypt a new Tenant Master Key and a new Namespace Key.

You can use the [Dashboard](/docs/secure/highly-regulated-identity/customer-managed-keys/customer-managed-keys-dashboard) or the [Management API](/docs/secure/highly-regulated-identity/customer-managed-keys/customer-managed-keys-management-api) to enable Bring Your Own Key.

## Monitor Customer Managed Keys log events

<Callout icon="file-lines">
  Auth0 automatically rotates tenant encryption keys once a year, adding the following log events in your tenant logs:

  * `kms_key_state_changed`
  * `kms_key_management_success`
</Callout>

The Customer Managed Keys operations adds the following log event in your [tenant logs](/docs/deploy-monitor/logs):

A `sapi` event code indicating:

* Create the new encryption key
* Create the public wrapping key
* Import the encryption key
* Delete the encryption key by its key id
* Rekey the key hierarchy

A `kms_key_management_success` event code indicating a successful KMS operation.

A `kms_key_management_failure` event code indicating a failed KMS operation.

A `kms_key_state_changed` event code indicating a KMS key state change.

## Auth0 key hierarchy

At the Auth0 application layer, Auth0 secures customer secrets and data using envelope encryption.

The Auth0 envelope encryption hierarchy consists of the following keys, each of which are encrypted using the key above it. The table below summarizes the key hierarchy:

<table>
  <thead>
    <tr>
      <th><b>Key</b></th>
      <th><b>Algorithm</b></th>
      <th><b>Storage</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Environment Root Key</td>
      <td><p>RSA 2048 OAEP (Auth0 on Azure)</p><p>AES-256-GCM (Auth0 on AWS)</p></td>
      <td>FIPS 140-2 L3 Hardware Security Module</td>
    </tr>

    <tr>
      <td>Tenant Master Key</td>
      <td>AES-256-GCM</td>
      <td>Auth0 KMS database</td>
    </tr>

    <tr>
      <td>Namespace Key</td>
      <td>AES-256-GCM</td>
      <td>Auth0 KMS database</td>
    </tr>

    <tr>
      <td>Data Encryption Key</td>
      <td>AES-256-GCM</td>
      <td>Stored next to the data</td>
    </tr>
  </tbody>
</table>

### Environment Root Key

The Environment Root Key represents the top of the hierarchy and wraps the Tenant Master Key to prevent it from being disclosed or tampered with outside of Auth0.

An independent Auth0 Environment Root Key is generated for each Auth0 environment and stored in an adjacent HSM. The HSMs are deployed in a highly available, multiple geographic configuration. This means the HSMs will failover to another region in case of a severe region-wide incident.

The Auth0 Environment Root Key is shared across all tenants. Customers can use the Bring Your Own Key feature to have a dedicated Environment Root Key for their tenant.

Auth0 uses the following algorithms to wrap the Tenant Master Key with the Environment Root Key based on your Auth0 Cloud Service Provider:

* Auth0 on Azure: RSA 2048 OAEP
* Auth0 on AWS: AES 256 GCM

<Callout icon="file-lines">
  Using the Auth0 Dashboard or Management API, tenant Admins can replace the Auth0 Environment Root Key with their own Customer Provided Root Key.
</Callout>

### Tenant Master Keys

Each tenant has an encrypted Tenant Master Key stored in the Auth0 Key Management Service and it encrypts the Namespace keys.

The algorithm used to encrypt the Tenant Master Key is AES256 GCM.

<Callout icon="file-lines">
  When a Tenant Admin using the Auth0 Dashboard or Management API has provided their own Customer Provided Root Key, a new Tenant Master Key is created.
</Callout>

### Namespace Keys

Namespace Keys segregate the encryption keys used for different purposes within the tenant. The number and use of Namespace Keys is configured internally by Auth0 and unavailable for customization.

Encryption and decryption of Namespace Keys require access to the Tenant Master Key. Namespace Keys never leave the Auth0 Key Management Service and are not accessible to developers or administrators.

The Namespace Keys are located in the Auth0 Key Management Service and are encrypted with the  AES256 GCM algorithm.

### Data Encryption Keys

The Auth0 Key Management Service securely generates different Data Encryption Keys for subsequent data encryption requests. The Auth0 Key Management Service  optimizes security and performance by regularly issuing new Data Encryption Keys.

Encryption and decryption of Data Encryption Keys require access to its assigned Namespace Key. Data Encryption Keys cannot be decrypted outside the Auth0 Key Management Service or by Key Management Editors.

The Data Encryption Keys are located next to the data and are encrypted with the AES256 GCM algorithm.


# Configure Customer Managed Keys with the Dashboard
Source: https://auth0.com/docs/secure/highly-regulated-identity/customer-managed-keys/customer-managed-keys-dashboard

Learn how to enable Customer Managed Keys using the dashboard

Auth0 secures your tenant secrets and data using an Auth0 Environment Root Key, at the top of the envelope encryption key hierarchy. The Auth0 Environment Root Key and Customer Provided Root Key are stored in the hardware security module (HSM) of the corresponding Auth0 Cloud Service Provider, AWS or Azure.

## Bring Your Own Key

Using Bring Your Own Key, users with the  [Key Management Editor role](/docs/get-started/manage-dashboard-access/add-dashboard-users) can use the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> to replace the default Auth0 Environment Root Key with their own Customer provided Root Key.

Customers can securely upload their own Root Key which contains their own cryptographic material to:

* Meet custom key generation and provenance requirements for the Environment Root Key.
* Meet specific key installation or lifespan requirements for the Environment Root Key.

<Warning>
  By importing your own Customer Provided Root Key with Bring Your Own Key, you are implicitly deauthorizing Auth0 from managing the lifecycle of the Customer Provided Root Key, except for its deletion.
</Warning>

To begin, go to Dashboard > Settings > Encryptions keys

<Frame>
  <img alt="Dashboard > Settings > Encryption Keys" />
</Frame>

Select **Upload Key** to begin the import process for your Customer Provided Root Key. This will open the import dialog:

<Frame>
  <img alt="Dashboard > Settings > Encryption Keys > Upload" />
</Frame>

When you select **Upload Key** and then **Download,** it initiates the Bring Your Own Keys  process:

1. Creates a public wrapping key and downloads it to your system.
2. Take the public wrapping key and wrap your own cryptographic material with it using your own key management system to create a Wrapped Encryption Key (the Customer Provided Root Key).
3. Upload your Wrapped Encryption Key and select **Save**.

<Callout icon="file-lines">
  The Wrapped Encryption Key once uploaded replaces the Auth0 Environment Root Key in the hardware security module (AWS or Azure) as a Customer Provided Root key.
</Callout>

## Cryptographic material requirements

Use your key management system to wrap your own cryptographic material with the public wrapping key and create the Wrapped Encryption Key. Use these settings for the [CKM\_RSA\_AES\_KEY\_WRAP](https://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.40/cos01/pkcs11-curr-v2.40-cos01.html#_Toc408226894) algorithm parameters based on your Auth0 Cloud Service Provider (AWS or Azure):

### Auth0 on AWS cloud

* Public wrapping key length: 3072 bits
* Algorithm: CKG\_MGF1\_SHA256
* Temporary AES key length for CKM\_AES\_KEY\_WRAP\_PAD: 256 bits
* Customer provided root key type: 256 bits long AES symmetric key

### Auth0 on Azure cloud

* Public wrapping key length: 2048 bits
* Algorithm: CKG\_MGF1\_SHA-1
* Temporary AES key length for CKM\_AES\_KEY\_WRAP\_PAD: 256 bits
* Customer Provided Root Key type: 2048 bits long RSA private key
* Private key encoding: PKCS #8 - ASN.1 DER


# Configure Customer Managed Keys with the Management API
Source: https://auth0.com/docs/secure/highly-regulated-identity/customer-managed-keys/customer-managed-keys-management-api

Learn how to configure Customer Managed Keys with the Management API

Auth0 secures your tenant secrets and data using an Auth0 Environment Root Key, at the top of the envelope encryption key hierarchy.  The Auth0 Environment Root Key and Customer Provided Root Key are stored in the hardware security module (HSM) of the corresponding Auth0 Cloud Service Provider,  AWS or Azure.

## Bring Your Own Key

Using Bring Your Own Key, users with the [Key Management Editor role](/docs/get-started/manage-dashboard-access/add-dashboard-users) can use the [Auth0 Management API](https://auth0.com/docs/api/management/v2) to replace the default Auth0 Environment Root Key with their own Customer provided Root Key. Customers can securely upload their own Root Key which contains their own cryptographic material to:

* Meet custom key generation and provenance requirements for the Environment Root Key
* Meet specific key installation or lifespan requirements for the Environment Root Key
* Keep a copy of the Customer Provided Root Key on customer premises.

<Warning>
  By importing your own Customer Provided Root Key with Bring Your Own Key, you are implicitly deauthorizing Auth0 from managing the lifecycle of the Customer Provided Root Key, except for its deletion.
</Warning>

You can create and manage your Customer Provided Root Key using the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>, following these steps:

1. Call the [Create the new encryption key](https://auth0.com/docs/api/management/v2/keys/post-encryption) endpoint to initiate the Bring Your Own Key process and obtain the `kid` (key identifier) of the pre-activated Customer Provided Root Key without cryptographic material.

   <Callout icon="file-lines">
     This endpoint returns the kid value which is the key’s unique identifier.
   </Callout>
2. Call the [Create the public wrapping key](https://auth0.com/docs/api/management/v2/keys/post-encryption-wrapping-key) endpoint to create and return a public wrapping key.
3. In your environment, generate your own cryptographic key material and wrap (encrypt) it with the public wrapping key to create a Wrapped Encryption Key (the Customer Provided Root Key).
4. Call the [Import the encryption key](https://auth0.com/docs/api/management/v2/keys/post-encryption-key) endpoint to import your Customer Provided Root Key to Auth0.

## Cryptographic material requirements

Use your key management system to wrap your own cryptographic material with the public wrapping key and create the Wrapped Encryption Key. Use these settings for the [CKM\_RSA\_AES\_KEY\_WRAP](https://docs.oasis-open.org/pkcs11/pkcs11-curr/v2.40/cos01/pkcs11-curr-v2.40-cos01.html#_Toc408226894) algorithm parameters based on your Auth0 Cloud Service Provider (AWS or Azure):

### Auth0 on AWS cloud

* Public wrapping key length: 3072 bits
* Algorithm: CKG\_MGF1\_SHA256
* Temporary AES key length for CKM\_AES\_KEY\_WRAP\_PAD: 256 bits
* Customer provided root key type: 256 bits long AES symmetric key

### Auth0 on Azure cloud

* Public wrapping key length: 2048 bits
* Algorithm: CKG\_MGF1\_SHA-1
* Temporary AES key length for CKM\_AES\_KEY\_WRAP\_PAD: 256 bits
* Customer Provided Root Key type: 2048 bits long RSA private key
* Private key encoding: PKCS #8 - ASN.1 DER

## Permissions

Use the following permissions to provide access to the encryption keys endpoints.

<table>
  <thead>
    <tr>
      <th><b>Permissions</b></th>
      <th><b>Descriptions</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>read:encryption\_keys</code></td>
      <td>Users can search and retrieve keys in the Auth0 tenant. This includes reading from the <code>/api/v2/keys/encryption</code>, <code>/api/v2/keys/encryption/</code> endpoints.</td>
    </tr>

    <tr>
      <td><code>create:encryption\_keys</code></td>
      <td>Users can create their own Customer Provided Root Key and Public wrapping key through the <code>/api/v2/keys/encryption</code> and <code>/api/v2/keys/encryption//wrapping-key</code> endpoints.</td>
    </tr>

    <tr>
      <td><code>delete:encryption\_keys</code></td>
      <td>Users can delete their own Customer Provided Root Key through the
      <code>/api/v2/keys/encryption/</code> endpoint.</td>
    </tr>

    <tr>
      <td><code>update:encryption\_keys</code></td>
      <td>Users can import their own Customer Provided Root Key through the
      <code>/api/v2/keys/encryption/</code> endpoint.</td>
    </tr>
  </tbody>
</table>

## Endpoints

* Use the [Get all encryption keys](https://auth0.com/docs/api/management/v2/keys/get-encryption-keys) endpoint to retrieve information about the existing current Environment Root Key or Customer Provided Root Key, and Tenant Master Key.
* Use the [Get the encryption key by its key id](https://auth0.com/docs/api/management/v2/keys/get-encryption-key) endpoint to retrieve information about the specified key.
* Use the [Create the new encryption key](https://auth0.com/docs/api/management/v2/keys/post-encryption) endpoint to create a pre-activated Customer Provided Root Key placeholder.
* Use the [Create the public wrapping key](https://auth0.com/docs/api/management/v2/keys/post-encryption-wrapping-key) endpoint to retrieve a Public Wrapping key to wrap your cryptographic material.
* Use the [Import the encryption key](https://auth0.com/docs/api/management/v2/keys/post-encryption-key) endpoint to import a new Customer Provided Root Key material.
* Use the [Delete the encryption key by its key id](https://auth0.com/docs/api/management/v2/keys/delete-encryption-key) endpoint to delete an existing Customer Provided Root Key and opt out of using Bring Your Own Keys. The Auth0 Environment Root Key is used to re-encrypt the key hierarchy. This operation does not negatively impact existing data and authentication flows.

<Callout icon="file-lines">
  If the Customer Managed Keys feature is not enabled in your tenant, calling the API endpoint(s) will return the error: `This feature is not enabled for this tenant`.
</Callout>


# Transactional Authorization with Authorization Code Flow
Source: https://auth0.com/docs/secure/highly-regulated-identity/transactional-authorization-with-authorization-code-flow

Learn about how Highly Regulated Identity enables transactional authorization with the Authorization Code Flow.

Highly Regulated Identity enables Transactional Authorization with the [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow) by applying step-up <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA) to authorize a transaction. Step-up MFA challenges the user with a second authentication factor to explicitly authorize the transaction details of a one-time operation, which is useful in use cases that require financial-grade security:

* Securing sensitive operations executed from your own services, such as approving bank transfers, access to operations history, and changes in access credentials.
* Securing sensitive operations requested from third-party services, such as approving digital payments and allowing one-time access for account verification.

This article walks you through the end-to-end journey of approving a bank transfer. The same transactional <Tooltip href="/docs/glossary?term=authorization+flow">authorization flow</Tooltip> can be applied to other use cases.

<Callout icon="file-lines">
  You must configure transactional authorization for each API. Once activated, it applies to the scopes and `authorization_details.types` for that API.
</Callout>

## Prerequisites

<Warning>
  Do not pass fine-grained transaction authorization data or other sensitive or regulated data outside of `authorization_details`.
</Warning>

Before getting started, follow the instructions in [Configure Rich Authorization Requests](/docs/get-started/apis/configure-rich-authorization-requests) to register the `authorization_details.types` for your API or <Tooltip href="/docs/glossary?term=resource+server">resource server</Tooltip>.

## End-to-end flow

The following diagram shows the end-to-end flow for Transactional Authorization with Contextual SCA. There are four main phases:

1. Securely redirect the user to Auth0 with the transaction details. In this step, avoid revealing sensitive information on the front channel (e.g. the browser).
2. Apply dynamic policy after the user authenticates. Using [Actions](/docs/customize/actions), you can dynamically decide on the next steps based on the transaction details and other information you may get from sources such as external APIs. To learn more, read [Apply dynamic policy](#apply-dynamic-policy).
3. Challenge the user with a second authentication factor and show transaction details for the user to explicitly approve. This step depends on the authentication factor you chose to apply using Actions.
4. Get the access token and proceed with the sensitive operation. Your API validates the approved transaction details associated with the access token.

<Frame>
  <img alt="" />
</Frame>

We will go through each phase in detail in the following sections.

### Communicate transaction details and redirect to Auth0

The user first accesses your web application after authenticating with Auth0. Following our example use case, the user then requests a money transfer to one of their contacts.

To meet financial-grade security standards, Highly Regulated Identity uses Pushed Authorization Requests (PAR) to hide transaction details from the browser. Instead of sending query parameters through the browser to the `/authorize` endpoint, PAR directly sends parameters from your backend to a special `/par` endpoint using a POST request. To learn how to set it up, read [Configure Pushed Authorization Requests](/docs/get-started/applications/configure-par).

In the PAR request body, transaction details are sent as part of the `authorization_details` JSON object:

```json lines theme={null}
"authorization_details": [
 {
   "type": "money_transfer",
   "instructedAmount": {
     "amount": 150,
     "currency": "USD"
   },
   "sourceAccount": "xxxxxxxxxxx1234",
   "destinationAccount": "xxxxxxxxxxx9876",
   "beneficiary": "Hanna Herwitz",
   "subject": "A Lannister Always Pays His Debts"
 }
]
```

Use Actions to inspect the `authorization_details` to determine which authentication factors to use based on the transaction. To learn more about `authorization_details` and how to use it along PAR, read [Authorization Code Flow with Rich Authorization Requests](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-rar).

If you want to meet FAPI 1 Advanced Security compliance requirements, you must also use public key cryptography to authenticate the backend against the `/par` or the `/token` endpoint. This is more secure than sending a <Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip>. Auth0 offers the following public key cryptography authentication methods:

* [Private Key JWT](/docs/get-started/authentication-and-authorization-flow/authenticate-with-private-key-jwt)
* [mutual-TLS (mTLS) for OAuth](/docs/get-started/authentication-and-authorization-flow/authenticate-with-mtls)

After receiving a successful response to your PAR request, redirect the user to your Auth0 tenant’s `/authorize` endpoint. Add the `request_uri` parameter received in the PAR response and the `client_id` as the only query parameters, thus effectively hiding any sensitive information from the browser.

### Apply dynamic policy

When the user logs in without using <Tooltip href="/docs/glossary?term=SSO">SSO</Tooltip> and the browser hits your Auth0 tenant’s `/authorize` endpoint, Auth0 will attempt to authenticate the user. In our example of approving a bank transfer, Auth0 has already authenticated the user to access your web application. However, when a third party redirects the user, such as for a digital payment, Auth0 presents a login screen to the user. To learn more about the authentication flow, read the [Authenticate](/docs/authenticate) documentation.

Once Auth0 has successfully authenticated the user, Auth0 triggers post-login [Actions](/docs/customize/actions), which expose transaction details about the user, app, authentication factor(s) used, and more in the [post-login event object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object). Within the post-login event object, the `event.transaction.requested_authorization_details` property contains details about the authorization request that were received in the previous step.

Use the [post-login event object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object) to decide how you want to proceed with the transaction. For example, you can send transaction details to an external risk engine, and after evaluating the risk level, determine whether to request step-up authentication using sms, as illustrated in the following code sample.

```js lines expandable theme={null}
exports.onExecutePostLogin = async (event, api) => {
  if (event.transaction?.requested_authorization_details.some(e => e.type === 'money_transfer')) {
      const axios = require('axios');

      //details to contact risk evaluation engine
      const risk_url = 'https://risk.example.org/score';
      const risk_options = {
        headers: {
          'Content-Type': 'application/json'
        }
      };

      const tx_data = {
        email: event.user.email,
        authorization_details: event.transaction?.requested_authorization_details
      };

      //send operation details to risk evaluation engine
      var risk = await axios.post(risk_url, tx_data, risk_options);

      //if it is a risky operation use push to authorize
      if (risk.data.score >= 2) {
        api.authentication.challengeWith({ type: 'push-notification', options: {otpFallback: false}});

      }
    }
};
```

### Challenge the user to get transaction details approval

You can customize what authentication factor to use depending on factors enrolled by the user, factors already satisfied by the session, and/or your own preferences. You can also provide alternatives for the user to choose from. To learn more, read [Customize MFA Selection in New Universal Login](/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-selection-universal-login).

Additionally, for SMS, email, and WebAuthn, you can customize the consent screen that Auth0 presents to the user with the information you want to show from authorization\_details and other transaction details. To learn more, read [Configure Rich Authorization Requests](/docs/get-started/apis/configure-rich-authorization-requests). For push notifications, this does not apply as the mobile application is the one showing the transaction details to the end user.

The following sections explain the different authentication factors that you can configure for transactional authorization.

#### Push notifications

Send a push notification to a user’s enrolled mobile device while Auth0 prompts the user with the Multi-Factor Authentication (MFA) waiting screen on the consumption device (e.g. the laptop where the transaction originated).

<Frame>
  <img alt="" />
</Frame>

For push notifications, the mobile application is responsible for showing the transaction details to the user for explicit approval. When triggering a push notification, you can forbid the option to fallback by manually entering an OTP by adding the option `otpFallback: false`.

To display the `authorization_details` to the user, the mobile application must retrieve them from the `txlnkid` parameter. The [Auth0 Guardian SDK](/docs/secure/multi-factor-authentication/auth0-guardian) passes the `txlnkid` parameter from the tenant to the mobile application via a push notification.

After the mobile application receives the push notification via the Guardian SDK, it can fetch the consent details, which includes the `authorization_details`, from the Auth0 Consent API:

<Tabs>
  <Tab title="iOS">
    ```swift lines theme={null}
    let device: AuthenticationDevice = // the object you obtained when enrolling
    if let consentId = notification.transactionLinkingId {
        Guardian
            .consent(forDomain: {yourTenantDomain}, device: device)
            .fetch(consentId: consentId, notificationToken: notification.transactionToken)
            .start{result in
                switch result {
                case .success(let payload):
                    let authorizationDetails = payload.requestedDetails.authorizationDetails
                case .failure(let cause):
                    // something went wrong
            }
        }
    }
    ```
  </Tab>

  <Tab title="Android">
    ```kotlin lines theme={null}
    if (notification.getTransctionLinkingId() != null) {
        guardian
          .fetchConsent(notification, enrollment)
          .start(new Callback<Enrollment> {
            @Override
            void onSuccess(RichConsent consentDetails) {
              List<Map<String, Object>> authorizationDetails = consentDetails
                    .getRequestedDetails()
                    .getAuthorizationDetails();
            }

            @Override
            void onFailure(Throwable exception) {
              if (exception instanceof GuardianException) {
                GuardianException guardianException = (GuardianException) exception;
                if (guardianException.isResourceNotFound()) {
                  // there is no consent associated with the transaction
                }
              }
              // something went wrong
            }
          });
    }
    ```
  </Tab>
</Tabs>

From the post-login Action, you can call `api.multifactor.enable()` before `api.authentication.challengeWith()` to remove the option to remember this device and force the user to validate the push challenge for all transactions. To learn more, read [Action Triggers: post-login - API object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object).

Once the user approves or declines the operation, the mobile application can allow or reject the MFA challenge. The transaction progresses to the **Complete the operation** phase.

<Callout icon="file-lines">
  To verify the identity of the user opening the push notification, you can add biometric authentication to the mobile application. To learn more, read [Configure WebAuthn with Device Biometrics for MFA](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-device-biometrics-for-mfa).
</Callout>

#### SMS, Email, or WebAuthn

You can also set up phone, email, or WebAuthn as authentication factors to challenge the user. For these authentication factors, Auth0 prompts the user with the corresponding MFA waiting screen. After the user validates the challenge on the MFA waiting screen, Auth0 shows the transaction details to the user for explicit approval. Remember you have to [Configure Rich Authorization Requests](/docs/get-started/apis/configure-rich-authorization-requests) for the approval step to work properly.

For the phone authentication factor, Auth0 sends a verification code to the user through SMS or voice. The following screenshot shows the MFA waiting screen after Auth0 sent the code through SMS:

<Frame>
  <img alt="" />
</Frame>

<Callout icon="file-lines">
  From Actions, you can call `api.multifactor.enable('any', { allowRememberBrowser: false })` before `api.authentication.challengeWith` to remove the option to remember this device and force the user to validate the push challenge for all transactions.
</Callout>

The user then receives the SMS with the verification code.

After the user inputs the verification code in the MFA waiting screen, Auth0 prompts the user with the transaction details on a consent screen. Once the user approves or declines the transaction details, the transaction progresses to the [Complete the operation](#complete-the-operation) phase.

Email and WebAuthn use the same transactional approval flow and similar MFA waiting and explicit approval screens.

<Warning>
  Under PSD2, [email is not a valid authentication factor](https://www.eba.europa.eu/sites/default/documents/files/documents/10180/2622242/4bf4e536-69a5-44a5-a685-de42e292ef78/EBA%20Opinion%20on%20SCA%20elements%20under%20PSD2%20.pdf) for Strong Customer Authentication. We recommend you use another authentication factor to challenge users to meet PSD2 compliance.
</Warning>

#### No Challenge

If you don’t challenge the user with a second authentication factor, Auth0 prompts the user with the consent screen to get explicit approval for the transaction details.

### Complete the operation

To complete the operation, Auth0 follows the standard [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow). If the transaction is approved, the user browser is redirected to your application with an authorization code, which is then exchanged for an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> encrypted using [JSON Web Encryption](/docs/secure/tokens/access-tokens/json-web-encryption). The access token contains the `authorization_details` that you originally passed. The following code sample shows the contents of a decrypted access token:

```json lines theme={null}
{
 "iss": "https://my_tenant.auth0.com/",
 "sub": "auth0|me",
 "aud": "https://myapi.zewobnak.com",
 "iat": 1683661385,
 "exp": 1683747785,
 "azp": "my_client",
 "transaction_linking_id": "ce4842e8-2894-418a-b1f9-39a330cd4911",
 "authorization_details": [
   {
     "type": "money_transfer",
     "instructedAmount": {
       "amount": 150,
       "currency": "USD"
     },
     "sourceAccount": "xxxxxxxxxxx1234",
     "destinationAccount": "xxxxxxxxxxx9876",
     "beneficiary": "Hanna Herwitz",
     "subject": "A Lannister Always Pays His Debts",
   }
 ]
}
```

Pass the access token to the API that facilitates the money transfer. The API then checks the access token’s `authorization_details` to verify the transaction details, such as the amount, sender, destination, and more. Once verified, the money transfer successfully executes, and you should see the approval screen.

If the transaction is rejected at any step, the user browser displays an `access_denied` error code.


# Auth0’s Mobile Driver's License Verification Service
Source: https://auth0.com/docs/secure/mdl-verification

Learn how to use Auth0 to validate Verifiable Credentials such as Mobile Driver's Licenses.

<Callout icon="file-lines">
  Auth0’s Mobile Driver's License Verification Service is in Early Access. To enable this feature, review and complete the [Terms and Conditions form](https://forms.gle/47YuFPkhh3RZVvt76), and our team will be in contact with you. To learn more about Auth0’s release stages, read Product Release Stages.
</Callout>

Auth0’s Mobile Driver's License Verification Service allows you to initiate a verification request for a user’s Mobile Driver’s License (mDL) Verifiable Credential. Verifiable Credentials (VC) are defined by Annex A of the [ISO/IEC TS 18013-7:2024](https://www.iso.org/standard/82772.html) (REST API) and may contain sensitive user data or personally identifiable information (PII), such as birthdate or country of residence. To learn more about mDL, read [What is a Mobile Driver’s License?](https://auth0.com/blog/what-is-mdl-how-to-start-using-them/)

You can use Auth0’s Mobile Driver's License Verification Service in your application if you want your users to present an mDL. You can embed the Mobile Driver's License Verification API in your application, which allows your application to perform ad-hoc mDL verifications on end-user’s submitted credentials. Rather than embed the mDL Verification API to your app, you can use Auth0 Forms as a low-code solution to use the mDL Verification Service.

<Frame>
  <img alt="Auth0 mDL Verification Service" />
</Frame>

### Use cases

You can use the mDL Verification Service for:

* Age verification
* License and driving privileges validation
* Identity verification since many countries use a driver's license as proof of identity. The mDL is the digital equivalent.
* Business process improvements involving Know Your Customer (KYC) and Anti-Money Laundering (AML)

## How it works

<Frame>
  <img alt="mDL Verification Service workflow" />
</Frame>

1. Your application initiates a Verification Presentation Request to Auth0 by making a call to the Mobile Driver's License Verification API.
2. The mDL Verification API returns an engagement URI and Verification ID from Auth0.
3. Your application presents the user with the URI link to prompt for consent to share their credential.

   <Callout icon="file-lines">
     We recommend you generate a QR code for the engagement URI to provide a convenient user experience if the user is on a device without a digital wallet, such as a tablet or desktop. To learn more, review the [Next.js example](https://www.npmjs.com/package/next-qrcode).
   </Callout>
4. The user consents to sharing the mDL VC.
5. Your application polls the presentation request with the Mobile Driver's License Verification API.
6. The Mobile Driver's License Verification API returns the appropriate response.

## Validate Verifiable Credentials

The Verification Template (VT) you create defines the fields you ask the user’s digital wallet to provide, such as date of birth, address, or family name. The Verification Presentation Request created by your application initiates a verification flow by calling the mDL Verification API.

Your app must poll the Verification Presentation Request status via the Mobile Driver's License Verification API to determine if the user consented to sharing their credential. The API returns a status depending on if the presentation request is ongoing, unsuccessful, or successful. If successful, the API will return the `JSON` from the presentation request.

To learn more about configuring Auth0’s Mobile Driver's License Verification Service, read [Configure Mobile Driver’s License Verification Presentation Request](/docs/secure/mdl-verification/configure-mdl-verification-request).

### Mobile Driver's License Verification API

The Mobile Driver's License Verification API consumes the verification presentation request and returns an engagement URI and Verification ID. When your application polls the status of the verification presentation request, the mDL Verification API returns a status of successful, unsuccessful, or ongoing. You can embed the mDL Verification API in your application or use the [Auth0 Forms widget](/docs/customize/forms/nodes-and-components#widgets-components).

You need to configure an instance of the Verifiable Digital Credential API via <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. To learn how, read [Create the Mobile Driver's License Verification API](/docs/secure/mdl-verification/create-mdl-api).

## Conditional Checks

You may want to check if a previous Verification Presentation Request was performed and is still valid. Conditional checks allow you to obtain data from a previous request or just verify the data from a previous request is sufficient. You can initiate a conditional verification check with Auth0 Actions. To learn more, read [Mobile Driver's License Conditional Verification Check](/docs/secure/mdl-verification/mdl-conditional-check).


# Configure Mobile Driver’s License Verification Presentation Request
Source: https://auth0.com/docs/secure/mdl-verification/configure-mdl-verification-request

Learn how to use Auth0's Verification Service for with Verifiable Credentials such as Mobile Driver's Licenses.

<Warning>
  Auth0’s Mobile Driver's License Verification Service is currently available in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0’s release stages, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

Auth0’s Mobile Driver's License Verification Service allows you to initiate a verification request for a user’s Mobile Driver’s License (mDL) to validate mDL claims, such as age and country of residence. mDL verification is useful for a variety of use cases, such as allowing end users to rent cars or access age-restricted products.

## Verification Presentation Request

To create a Verification Presentation Request, your application calls the [mDL Verification API](/docs/secure/mdl-verification/mdl-verification-api) to initiate a verification flow. The Verification Presentation Request returns a URI with the presentation request information for the user’s digital wallet to consume. Your application presents the URI to the user in the form of a link and prompts them to share their credential with your application. The Verification Presentation Request also returns a `verificationId`. Your application uses the `verificationId` to poll the status of the request.

### Update .env file

<Callout icon="file-lines">
  The instructions follow along with the hands-on lab using a Next.js application. You can access our [GitHub repository](https://github.com/auth0/hol-mdl).
</Callout>

If you want to embed the mDL Verification API to use inside your application, you need to update your `.env` file. The API calls to create and poll the verification request require repeated access to Auth0 variables. We recommend you set these variables as environment variables in your application.

For a Next.js application, edit the **.env.local** file and set the corresponding values:

* `AUTH0_DOMAIN`: The **Domain** specified under the application’s BasicInformation in <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. Defines the Application performing the Verification Request.
* `PROTOCOL`: The **protocol** determines the method used for interacting with the wallet.
* `TEMPLATE_ID`: The **Template ID** from the template you created.
* `VERIFICATION_BEARER_TOKEN`: The **Verification Bearer Token** that is generated based on your <Tooltip href="/docs/glossary?term=Client+ID">Client ID</Tooltip>, <Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip>, <Tooltip href="/docs/glossary?term=Audience">Audience</Tooltip>, and Grant Type that allows your application to call the Verification Service.

### Verification Template

The Verification Template defines the fields you want to request from a user’s digital wallet, including mDL claims. The Verification Template is part of the first call to the mDL Verification API. You can create the Verification Template using the Auth0 Dashboard or <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. Currently, Auth0 only supports the mDoc credential type. An mDoc is a binary data object for representing a driver’s license as defined in Annex A of the [ISO/IEC TS 18013-7:2024](https://www.iso.org/standard/82772.html) standard.

<Warning>
  You should only request verification data that is essential for your business purposes.
</Warning>

#### mDL claims

Claims, which are different from <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> claims, are specific to the mDL Verifiable Credential. The claims are attributes associated with the user that could be sensitive, personally identifiable information (PII).

You can request the following claims:

* `family_name`
* `given_name`
* `birth_date`
* `issue_date`
* `expiry_date`
* `issuing_country`
* `issuing_authority`
* `portrait`
* `driving_privileges`
* `resident_address`
* `portrait_capture_date`
* `age_in_years`
* `age_birth_year`
* `age_over_NN`
* `issuing_jurisdiction`
* `nationality`
* `resident_city`
* `resident_state`
* `resident_postal_code`
* `resident_country`
* `family_name_national_character`
* `given_name_national_character`

#### Create a Verification Template

<Tabs>
  <Tab title="Auth0 Dashboard">
    1. Navigate to [**Auth0 Dashboard > Credentials > Verification**](https://manage.auth0.com/#/verification).
    2. Select **+ Add Verification Template**.
    3. Name the template.
    4. Choose the claims you want to request from the user’s mDL.
    5. Select **Create Verification Template**.
  </Tab>

  <Tab title="Management API">
    1. Create a Verification Template similar to the example below. Outline the mDL claims you want to request from the user.

       ```json lines theme={null}
       {
          "name":"TEMPLATE_NAME",
          "dialect":"simplified/1.0",
          "presentation":{
            "org.iso.18013.5.1.mDL": {
              "org.iso.18013.5.1": {
                "family_name":false,
                "given_name":false,
                "birth_date":false,
                "age_over_18":false
              }
            }
          }
        }
       ```

    2. Make a `POST` request to the [Create a verifiable credential template](https://auth0.com/docs/api/management/v2/verifiable-credentials/post-vc-templates) endpoint with the Verification Template definition as the body and the following request headers:

       1. `Content-Type: application/json`

       2. `Authorization: bearer`

          ```text lines theme={null}
          curl -X POST --location "https://{domain}/api/v2/verifiable_credentils/templates" \
              -H "Authorization: Bearer {managementAccessToken}" \
              -H "Content-Type: application/json" \
            --data-raw `{
            "name": "{template_name}",
            "type":"mdl",
            "well_known_trusted_issuers": "aamva",
            "dialect": "simplified/1.0",
            "presentation": {
          	"org.iso.18013.5.1.mDL": {
                 "org.iso.18013.5.1": {
                   "family_name":false,
                   "given_name":false,
                   "birth_date":false,
                   "age_over_18":false
                   }
                  }
                 }
                }`
          ```
  </Tab>
</Tabs>

After you review the supported mDL claims, use the Auth0 Dashboard or Management API to create a Verification Template.

### Create a Verification Presentation Request

A **Verification Presentation Request** keeps track of a verification request in Auth0. To initiate a **Verification Presentation Request** within your application:

1. Create a new folder named **api** in the same folder where the **index.js** file is located.

2. Create a new folder named **verify** in the **api** folder you created.

3. Create a new file named **start.js** in the **api/verify** folder.

4. Add the following code snippet to the **start.js** file:

   ```text lines theme={null}
   import fetch from "node-fetch";
   ```

   <Callout icon="file-lines">
     The snippet imports the **node-fetch** module, which you use to make `HTTP` calls to the Mobile Driver's License Verification API.
   </Callout>

5. Map the environment variables from the **.env.local file**. If you are using Next.js, it will parse this file by default and map the variables to the `process.env` object:

   ```javascript lines theme={null}
   const AUTH0_DOMAIN = process.env.AUTH0_DOMAIN;
   const TEMPLATE_ID = process.env.TEMPLATE_ID;
   const PROTOCOL = process.env.PROTOCOL;
   const VERIFICATION_BEARER_TOKEN = process.env.AUTH0_CLIENT_ID;

   if (!AUTH0_DOMAIN) throw new Error("AUTH0_DOMAIN not set");
   if (!TEMPLATE_ID) throw new Error("TEMPLATE_ID not set");
   if (!PROTOCOL) throw new Error("PROTOCOL not set");
   if (!VERIFICATION_BEARER_TOKEN) throw new Error("VERIFICATION_BEARER_TOKEN not set");
   ```

6. Add the code snippets to the **start.js** file.

   1. The `handler()` function handles `HTTP` requests in an API route.
   2. The `run()` function makes a `POST` request to the Mobile Driver's License Verification API to start a verification request. The returned object has two variables:

      * `engagement`: The URIwith the verification request information for the end user’s wallet to consume.

      * `verificationId`: Auth0’s unique identifier of the verification request.

        ```text lines expandable theme={null}
        export default async function handler(req, res) {
            try {
                const result = await run();
                res.status(200).json(result);
            } catch (err) {
                res.status(500).send({ error: err.message });
            }
        }

        async function run() {

            const result = await fetch(`https://${AUTH0_DOMAIN}/vdcs/verification`, {
                method: "post",
                headers: {
                    "authorization": `bearer ${VERIFICATION_BEARER_TOKEN}`,
                    "content-type": "application/json",
                },
                body: JSON.stringify({
                    template_id: TEMPLATE_ID,
                    protocol: PROTOCOL,
                }),
            })

            const { verificationId, engagement } = await result.json();

            return {verificationId, engagement };
        }
        ```

#### Prompt the user to present a credential

To prompt the user to present a credential, you must provide the returned engagement URI. The first API request to initiate the verification request returns an engagement URI and Verification ID for the user. We recommend you display the engagement link in the form of a QR code or link. If the user is on a device that their wallet is not, such as a tablet or computer, a QR code is helpful. To learn more, review the [Node.js example](https://www.npmjs.com/package/qrcode).

If the user is on their mobile device, the link prompts the end user to open their wallet and based on the requested type of credentials, the wallet may auto-select an appropriate credential. The user is usually prompted for consent.

#### Check the Verification Presentation Request’s status

Once you create a verification request, the application needs to know if the user consented to submit a credential to Auth0. To do that, we need to poll the status of the Verification Presentation Request. To do so:

1. Create a new file named **check.js** in the **/api/verify** folder you already created.

2. Import the `node-fetch` library and load the required environment variables.

   ```javascript lines theme={null}
   const AUTH0_DOMAIN = process.env.AUTH0_DOMAIN;
   const VERIFICATION_BEARER_TOKEN = process.env.AUTH0_CLIENT_ID;

   if (!AUTH0_DOMAIN) throw new Error("AUTH0_DOMAIN not set");
   if (!VERIFICATION_BEARER_TOKEN) throw new Error("VERIFICATION_BEARER_TOKEN not set");
   ```

3. The `HTTP` handler is similar to the previous one, but the Verification ID must be extracted from the Verification `POST` request body so your application can exchange the requested claims with Auth0:

   ```text lines theme={null}
   export default async function handler(req, res) {
       try {
           const verificationId = req.body.verificationId;
           const result = await run(verificationId);
           res.status(200).json(result);
       } catch (err) {
           res.status(500).send({ error: err.message });
       }
   }
   ```

4. Implement the `run()` function. This function uses the Verification ID to exchange the requested claims with Auth0 and returns the result.

   ```text lines theme={null}
   async function run(verificationId) {
       if (!verificationId) throw new Error("verificationId not found");

       const result = await fetch(
           `https://${AUTH0_DOMAIN}/vdcs/verification/${verificationId}`,
           {
               method: "get",
               headers: {
                   "authorization": `bearer ${VERIFICATION_BEARER_TOKEN}`,
                   "content-type": "application/json",
               },
           }
       );

       const data = await result.json();

       if (data.presentation) {
           data.presentation = JSON.parse(data.presentation);
       }

       return data;
   }
   ```

The endpoint that checks the status of the Verification Presentation Request can return several different status codes, which indicates the request is ongoing, unsuccessful, or successful. To learn more, read [Mobile Driver’s License API](/docs/secure/mdl-verification/mdl-verification-api).

## Verification Request data storage

The claims requested will be available in the result and can be used based on your business needs. If additional storage is required, read [Understand How Metadata Works in User Profiles](/docs/manage-users/user-accounts/metadata).

<Warning>
  Auth0 metadata is not a secure data store and should not be used to store sensitive information. This includes secrets and high-risk PII like social security numbers or credit card numbers, etc. Auth0 customers are strongly encouraged to evaluate the data stored in metadata and only store that which is necessary for identity and access management purposes. To learn more, read [Auth0 General Data Protection Regulation Compliance](/docs/secure/data-privacy-and-compliance/gdpr).
</Warning>


# Create the Mobile Driver’s License Verification API
Source: https://auth0.com/docs/secure/mdl-verification/create-mdl-api

Create an instance of Auth0's Mobile Driver’s License Verification API for the mDL Verification Service.

<Warning>
  Auth0’s Mobile Driver's License Verification Service is currently available in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0’s release stages, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

The Mobile Driver's License Verification API is a system API for customers to initiate a verification request for a user’s Mobile Driver’s License (mDL).

## Create the mDL Verification API

Once you've been approved to join the EA, you can create the mDL Verification API.

<Tabs>
  <Tab title="Auth0 Dashboard">
    1. Navigate to [**Auth0 Dashboard > Applications > APIs**](https://manage.auth0.com/#/apis).
    2. Select **Create API**.
    3. Enter the following information:

       1. **Name**: Verification API
       2. **Identifier**: `https://{account.namespace}/vdcs/`
       3. **JSON Web Token (JWT) Profile**: Auth0
       4. **JSON Web Token (JWT) Signing Algorithm**: RS256
       5. Select **Create**.

    #### Enable mDL verification

    1. To enable mDL for your application:
    2. Navigate to [**Applications > Applications**](https://manage.auth0.com/#/applications).
    3. Choose the application you want to use with Verification API.
    4. Select the **APIs** tab.
    5. Enable Verification API.

       <Frame>
         <img
           alt="Auth0 Dashboard > Applications > APIs
       Auth0 Dashboard > Applications > Applications"
         />
       </Frame>
    6. In the drop-down menu, choose the associated permissions:

       1. `create:verification_request`
       2. `read:verification_request`
    7. Select **Update**.
  </Tab>

  <Tab title="Management API">
    1. Make a `POST` call to the [Create a Resource Server](https://auth0.com/docs/api/management/v2/resource-servers/post-resource-servers) endpoint.

    <AuthCodeGroup>
      ```bash cURL theme={null}
         curl --request POST \
         --url 'https://{yourDomain}/api/v2/resource-servers/post-resource-servers' \
         --header 'content-type: application/json' \
         --data '{"name"}'

      ```

      ```csharp C# theme={null}
         var client = new RestClient("https://{yourDomain}/api/v2/resource-servers/post-resource-servers");
      var request = new RestRequest(Method.POST);
      request.AddHeader("content-type", "application/json");
      request.AddParameter("application/json", "{"name"}", ParameterType.RequestBody);
      IRestResponse response = client.Execute(request);

      ```

      ```go Go theme={null}
         package main

      import (
         "fmt"
         "strings"
         "net/http"
         "io/ioutil"
      )

      func main() {

         url := "https://{yourDomain}/api/v2/resource-servers/post-resource-servers"

         payload := strings.NewReader("{"name"}")

         req, _ := http.NewRequest("POST", url, payload)

         req.Header.Add("content-type", "application/json")

         res, _ := http.DefaultClient.Do(req)

         defer res.Body.Close()
         body, _ := ioutil.ReadAll(res.Body)

         fmt.Println(res)
         fmt.Println(string(body))

      }

      ```

      ```java Java theme={null}
         HttpResponse response = Unirest.post("https://{yourDomain}/api/v2/resource-servers/post-resource-servers")
         .header("content-type", "application/json")
         .body("{"name"}")
         .asString();

      ```

      ```javascript Node.JS theme={null}
         var axios = require("axios").default;

      var options = {
         method: 'POST',
         url: 'https://{yourDomain}/api/v2/resource-servers/post-resource-servers',
         headers: {'content-type': 'application/json'},
         data: '{"name"}'
      };

      axios.request(options).then(function (response) {
         console.log(response.data);
      }).catch(function (error) {
         console.error(error);
      });

      ```

      ```objc Obj-C theme={null}
         #import <Foundation/Foundation.h>

      NSDictionary *headers = @{ @"content-type": @"application/json" };

      NSData *postData = [[NSData alloc] initWithData:[@"{"name"}" dataUsingEncoding:NSUTF8StringEncoding]];

      NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/resource-servers/post-resource-servers"]
                                                            cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                         timeoutInterval:10.0];
      [request setHTTPMethod:@"POST"];
      [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];

      ```

      ```php PHP theme={null}
         $curl = curl_init();

      curl_setopt_array($curl, [
         CURLOPT_URL => "https://{yourDomain}/api/v2/resource-servers/post-resource-servers",
         CURLOPT_RETURNTRANSFER => true,
         CURLOPT_ENCODING => "",
         CURLOPT_MAXREDIRS => 10,
         CURLOPT_TIMEOUT => 30,
         CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
         CURLOPT_CUSTOMREQUEST => "POST",
         CURLOPT_POSTFIELDS => "{"name"}",
         CURLOPT_HTTPHEADER => [
            "content-type: application/json"
         ],
      ]);

      $response = curl_exec($curl);
      $err = curl_error($curl);

      curl_close($curl);

      if ($err) {
         echo "cURL Error #:" . $err;
      } else {
         echo $response;
      }

      ```

      ```python Python theme={null}
         import http.client

      conn = http.client.HTTPSConnection("")

      payload = "{"name"}"

      headers = { 'content-type': "application/json" }

      conn.request("POST", "/{yourDomain}/api/v2/resource-servers/post-resource-servers", payload, headers)

      res = conn.getresponse()
      data = res.read()

      print(data.decode("utf-8"))

      ```

      ```ruby Ruby theme={null}
         import http.client

      conn = http.client.HTTPSConnection("")

      payload = "{"name"}"

      headers = { 'content-type': "application/json" }

      conn.request("POST", "/{yourDomain}/api/v2/resource-servers/post-resource-servers", payload, headers)

      res = conn.getresponse()
      data = res.read()

      print(data.decode("utf-8"))

      ```

      ```swift Swift theme={null}
         import Foundation

      let headers = ["content-type": "application/json"]

      let postData = NSData(data: "{"name"}".data(using: String.Encoding.utf8)!)

      let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/resource-servers/post-resource-servers")! as URL,
                                             cachePolicy: .useProtocolCachePolicy,
                                          timeoutInterval: 10.0)
      request.httpMethod = "POST"
      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)
         }
      })

      ```
    </AuthCodeGroup>

    2. Enable the permissions by following instructions for [Management API](/docs/get-started/apis/add-api-permissions#use-the-management-api).
  </Tab>
</Tabs>


# Mobile Driver's License Conditional Verification Check
Source: https://auth0.com/docs/secure/mdl-verification/mdl-conditional-check

Learn how to initiate a conditional check with Auth0's Mobile Driver's License Verification Service.

<Warning>
  Auth0’s Mobile Driver's License Verification Service is currently available in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0’s release stages, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

Auth0 supports verification of user's Mobile Driver’s Licenses (mDL) based on Annex A of the [ISO/IEC TS 18013-7:2024](https://www.iso.org/standard/82772.html) standard. mDL verification allows customers to validate sensitive information or personally identifying information (PII) about a user, such as birthdate or country of residence. A conditional check may be required during a transaction.

You can store the response of a Verification Request, either with Auth0’s [metadata solution](/docs/manage-users/user-accounts/metadata) or with your own storage solution. The storage of this data can be used to conditionally check if a verification request is needed or can be skipped. To learn more, read [Configure Mobile Driver’s License Verification Presentation Request](/docs/secure/mdl-verification/configure-mdl-verification-request).

<Warning>
  Auth0 metadata is not a secure data store and should not be used to store sensitive information. This includes secrets and high-risk PII like social security numbers or credit card numbers, etc. Auth0 customers are strongly encouraged to evaluate the data stored in metadata and only store that which is necessary for identity and access management purposes. To learn more, read [Auth0 General Data Protection Regulation Compliance](/docs/secure/data-privacy-and-compliance/gdpr).
</Warning>

We recommend the use of [Actions](/docs/manage-users/user-accounts/metadata/manage-user-metadata) as a means to check if a previous Verification Request was performed, is still valid, and/or the data obtained from a previous request is sufficient.


# Mobile Driver's License Verification API
Source: https://auth0.com/docs/secure/mdl-verification/mdl-verification-api

Describes the Mobile Driver's License Verification API.

<Warning>
  Auth0’s Mobile Driver's License Verification Service is currently available in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0’s release stages, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

This API facilitates interactions with a digital wallet for mDL verifiable credentials, following Annex A of the [ISO/IEC TS 18013-7:2024](https://www.iso.org/standard/82772.html) standard (REST API). The purpose of this API is to simplify credential exchange as much as possible. It achieves this by abstracting and managing the trust relationship with credential issuers and implementing the complex protocol that verifies and communicates with a compliant wallet.

The primary function is to initiate and manage verifications and report their status to the requesting party. This allows the complex interactions between reader and wallet to be abstracted from the act of verifying a document. The reader (website) initiates a verification, and the Mobile Driver's License Verification API responds with a Verification ID and an engagement URI for communication with the wallet.  The reader can then begin polling the API for receiving claims. This API exclusively uses `application/json` for request and response bodies.

## Create verification request

This endpoint initiates a new verification process.  It accepts a `POST` request specifying the desired protocol for interacting with the wallet and a template ID referencing a pre-configured verification template.

The response includes a verification ID along with an engagement URI for engaging the wallet based on the specified protocol.

### Endpoint

`POST` `/vdcs/verification`

### Scopes

`create:verification_request`

### Body parameters

* **`protocol`**: String. <span>Required</span><br />

  Engagement protocols define the methods your application uses for interacting with the wallet. We currently support:

  * `mdoc/webapi/draft-2023-03-29`: Uses an MDoc URI as defined in  [ISO/IEC DTS 18013-7](https://www.iso.org/standard/82772.html) for communication.
  * `mdoc/webapi/v1.0`: Uses an MDoc URI as defined in  [ISO/IEC DTS 18013-7](https://www.iso.org/standard/82772.html) for communication.

* **`template_id`**: String. <span>Required</span><br />

  The ID references a pre-configured template. This simplifies the request by using pre-defined claim requirements.

### Response schema

<table>
  <thead>
    <tr>
      <th><b>Response Code</b></th>
      <th><b> Response Type</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>201</code></td>
      <td><code>application/json</code></td>
      <td><ul><li> <b><code>verification\_id</code></b>String <p> Verification ID <a href="https://www.npmjs.com/package/short-uuid">(UUIDv4)</a> as received from the verification initiation. This ID is used for subsequent interactions with the verification API, such as polling for status.</p></li><li><b><code>engagement</code></b>String <p> MDoc URI for the Web API protocol. This URI should be presented to the user to initiate the wallet interaction using the protocols. It conforms to the structure defined in <a href="https://www.iso.org/standard/82772.html">ISO/IEC DTS 18013-7 (Annex 4)</a></p></li></ul></td>
    </tr>
  </tbody>
</table>

### Response codes

<table>
  <thead>
    <tr>
      <th><b>Response Code</b></th>
      <th><b>Response Message</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>201</code></td>
      <td><code>Verification is initiated successfully</code></td>
      <td>The response body contains the <b>Response Schema</b> defined above.</td>
    </tr>

    <tr>
      <td><code>400</code></td>
      <td><code>Bad Request</code></td>
      <td>The request is malformed or invalid.</td>
    </tr>

    <tr>
      <td><code>401</code></td>
      <td><code>Unauthorized</code></td>
      <td>The request requires authentication.  Ensure a valid access token is provided in the Authorization header.</td>
    </tr>

    <tr>
      <td><code>403</code></td>
      <td><code>Forbidden</code></td>
      <td>Insufficient scope. Ensure an access token with sufficient scope is provided in the Authorization header.</td>
    </tr>

    <tr>
      <td><code>404</code></td>
      <td><code>Template not found</code></td>
      <td>The provided template ID is invalid or no longer active.</td>
    </tr>

    <tr>
      <td><code>500</code></td>
      <td><code>Internal Server Error</code></td>
      <td>An unexpected error occurred on the server.</td>
    </tr>
  </tbody>
</table>

## Get verification status

This endpoint retrieves the status and, if available, the claims of a given verification.  The `id` path parameter specifies the Verification ID.

### Endpoint

`GET` `/vdcs/verification/{id}`

### Scopes

`read:verification_request`

### Path parameters

`verification_id`: String. <span>Required</span>

* Verification ID [(UUIDv4)](https://www.npmjs.com/package/short-uuid) as received from the verification initiation. This ID is used for subsequent interactions with the Mobile Driver's License Verification API, such as polling for status.

### Response schemas

<table>
  <thead>
    <tr>
      <th><b>Response Code</b></th>
      <th><b> Response Type</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>200</code></td>
      <td><code>application/json</code></td>
      <td><b><code>state</code></b>: String <span>Required</span> <p>The state field contains information about the current state of the verification process. The following values may be present: </p><ul><li><b><code>pending-engagement</code></b>: The verification service is waiting initial engagement from the wallet.</li><li><b><code>pending-mdoc</code></b>: The verification service is waiting presentation of the mDoc from the wallet.</li> <li><b><code>error-wallet</code></b>: An error occurred when interacting with the wallet. The <code>reason</code> field will contain more information regarding the encountered error.</li> <li><b><code>error-reader</code></b>: An error has occurred when reading the mDoc. The <code>reason</code> field will contain more information regarding the error encountered.</li><li><b><code>honored</code></b>: Verification completed without issue. The verified document is available in the <code>presentation</code> field for consumption.</li></ul> <br /> <b><code>reason</code></b>: String <span>Optional</span><p> The <code>reason</code> field contains additional information (if available) regarding the state of the verification request. </p><p> <b><code>presentation</code></b>: Object <span>Optional</span></p><p> The <code>presentation</code> field contains the claims provided by the wallet in response to the presentation definition.  It follows a simplified structure based on namespaces and claims.  Each claim includes a <code>value</code>, <code>retain</code> flag, and <code>verified</code> status.</p></td>
    </tr>
  </tbody>
</table>

### Response codes

<table>
  <thead>
    <tr>
      <th><b>Response Code</b></th>
      <th><b>Response Message</b></th>
      <th><b>Description</b></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>401</code></td>
      <td><code>Unauthorized</code></td>
      <td>The request requires authentication.  Ensure a valid access token is provided in the Authorization header.</td>
    </tr>

    <tr>
      <td><code>403</code></td>
      <td><code>Unauthorized</code></td>
      <td>Insufficient scope. Ensure an access token with sufficient scope is provided in the Authorization header.</td>
    </tr>

    <tr>
      <td><code>404</code></td>
      <td><code>Verification not found</code></td>
      <td>The provided verification ID is invalid or no longer active.</td>
    </tr>

    <tr>
      <td><code>500</code></td>
      <td><code>Internal Server Error</code></td>
      <td>Verification failed. Response body may contain an <code>ErrorResponse</code> object with details about the failure.  Check the <code>reason</code> field for specific error information.</td>
    </tr>
  </tbody>
</table>


# Multi-Factor Authentication (MFA)
Source: https://auth0.com/docs/secure/multi-factor-authentication

Describes how multi-factor authentication (MFA) works in Auth0.

<Card title="Overview">
  Multi-factor Authentication (MFA) is another method of securing your application and your users' identities. MFA adds a layer of security during login that requires users to provide more than one credential to prove their digital identity. Factors can be:

  * Something you are - like a biometric
  * Something you know - like a password
  * Something you own - like a device

  Read this Q\&A to see if using MFA with your Auth0 instance is the right choice for you.
</Card>

## What is multi-factor authentication?

<Tooltip href="/docs/glossary?term=Multi-factor+authentication">Multi-factor authentication</Tooltip> (MFA) is a user verification method that requires more than one type of user validation. It prevents <Tooltip href="/docs/glossary?term=bad+actors">bad actors</Tooltip> from accessing an account even if they've acquired the username and password.

## Why use multi-factor authentication?

MFA reduces the likelihood of many types of cyber-attacks. It's common for third parties to steal user names and passwords or programmatically attack user accounts. An additional MFA factor, such as a thumbprint or one-time password, impedes these violations.

## How does multi-factor authentication work?

MFA works by requiring additional verification information (known as factors). Users can't log in using only user names and passwords. They must provide further proof of identity, such as face recognition or text message notifications.

## MFA factors

<Warning>
  MFA factors are subject to plan availability; some are only available on Professional and Enterprise plans. To learn more, read [Auth0 Pricing](https://auth0.com/pricing).
</Warning>

Auth0 supports a variety of MFA factors, including:

* Push notifications
* SMS notifications
* Voice notifications
* One-time passwords
* WebAuthn with security keys
* WebAuthn with device biometrics
* Email notifications
* Cisco Duo security
* Recovery codes

To learn more, read [Multi-Factor Authentication Factors](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors).

## Enable MFA

To learn how to enable MFA, read [Enable Multi-Factor Authentication](/docs/secure/multi-factor-authentication/enable-mfa).

## Customize MFA

You can also use [Auth0 Actions](/docs/customize/actions) to customize your MFA flow. You can require MFA only in specific circumstances or force use of a particular factor.

## Learn more

* [Multi-Factor Authentication Factors](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors)
* [Enable Multi-Factor Authentication](/docs/secure/multi-factor-authentication/enable-mfa)
* [Customize Multi-Factor Authentication Pages](/docs/secure/multi-factor-authentication/customize-mfa)
* [Multi-Factor Authentication Developer Resources](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources)
* [Auth0 Guardian](/docs/secure/multi-factor-authentication/auth0-guardian)
* [Troubleshoot Multi-Factor Authentication Issues](/docs/troubleshoot/authentication-issues/troubleshoot-mfa-issues)


# Enable Multi-Factor Authentication
Source: https://auth0.com/docs/secure/multi-factor-authentication/enable-mfa

Learn how to enable multi-factor authentication (MFA) in the Auth0 Dashboard.

You can enable <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA) for your tenant in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

When you enable MFA, select the factors (such as push notifications or phone messages) you intend to make available to users and define a policy to determine when you require them to authenticate.

## Select factors

Auth0 supports a variety of factors you can enable for your users to complete authentication.

### Independent factors

You must enable and configure at least one independent factor to require MFA for users on your tenant. You may enable multiple independent factors simultaneously as you’d like.

Available independent factors are:

* [WebAuthn with FIDO Security Keys](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-security-keys-for-mfa)
* [One-time Password (OTP)](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-otp-notifications-for-mfa)
* [Push Notification using Auth0 Guardian](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-push-notifications-for-mfa)
* [Phone Message](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-sms-voice-notifications-mfa)
* [Cisco Duo Security](/docs/secure/multi-factor-authentication/configure-cisco-duo-for-mfa)

### Dependent factors

You may enable one or more dependent factors once you’ve already enabled and configured at least one independent factor for users on your tenant.

Available dependent factors are:

* [WebAuthn with FIDO Biometrics](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-device-biometrics-for-mfa)
* [Email](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-email-notifications-for-mfa)
* [Recovery Code](/docs/secure/multi-factor-authentication/configure-recovery-codes-for-mfa)

## Enable MFA in the Auth0 Dashboard

1. Go to [Dashboard > Security > Multi-factor Auth](https://manage.auth0.com/#/security/mfa).
2. In the **Factors** section, enable and configure the factors you’d like to make available to users.
3. In the **Define policies** section, select a policy to determine when users will be prompted for MFA.

   * **Never**: MFA is not required for any logins.
   * **Use Adaptive MFA**: MFA is required based on Auth0 risk determination. To learn more, read [Enable Adaptive MFA](/docs/secure/multi-factor-authentication/adaptive-mfa).
   * **Always**: MFA is required for all logins.
4. If you choose the **Never** or **Always** policy, the **MFA Risk Assessors** section appears. By default, the **Enable Adaptive MFA Risk Assessment** setting is disabled. Enable the toggle to assess and record risk for all login transactions in your tenant logs.
5. In the **Additional Settings** section, configure the following options as needed:

   * **Show Multi-factor Authentication options:** Enable this toggle to allow users to select authentication factors upon enrollment. When disabled, Auth0 automatically presents the most secure authentication factors to users upon enrollment.

     <Frame>
       <img alt="Show Multi-factor Authentication options end user view" />
     </Frame>
   * **Customize MFA Factors using Actions**: Enable this toggle to customize your MFA flows using `post-login` [Actions](/docs/customize/actions). This allows you to challenge users with a specific factor or sequence of factors, as well as use contextual information to create more individualized experiences. To learn more, review [Customize MFA Selection for Universal Login](/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-selection-universal-login).
6. Click **Save**.

## Customize MFA flow

You can use Auth0 Actions to customize the MFA flow for users on your tenant. For example, you can create an Action to require MFA in specific circumstances or to force a particular factor to be used.

To learn more, read [Customize Adaptive MFA](/docs/secure/multi-factor-authentication/adaptive-mfa/customize-adaptive-mfa).

## Learn more

* [Configure Push Notifications for MFA](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-push-notifications-for-mfa)
* [Configure OTP Notifications for MFA](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-otp-notifications-for-mfa)
* [Configure SMS and Voice Notifications for MFA](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-sms-voice-notifications-mfa)
* [Configure Email Notifications for MFA](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-email-notifications-for-mfa)
* [Configure Cisco Duo Security for MFA](/docs/secure/multi-factor-authentication/configure-cisco-duo-for-mfa)
* [Customize Multi-Factor Authentication Pages](/docs/secure/multi-factor-authentication/customize-mfa)


# Multi-Factor Authentication Factors
Source: https://auth0.com/docs/secure/multi-factor-authentication/multi-factor-authentication-factors

Describes multi-factor authentication (MFA) factors, policies, and use cases.

Auth0 supports a number of different options or factors for protecting user account access with <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA).

To select the MFA factors to use on your tenant, go to [Dashboard > Security > Multi-factor Auth](https://manage.auth0.com/#/security/mfa). You must enable at least one factor on your tenant to use MFA. Available factors are dependent on your subscription plan. To learn more, read [Auth0 Pricing](https://auth0.com/pricing/).

## Factors

Auth0 supports the following factors for implementing MFA.

### Push notifications

Send users push notifications to their pre-registered devices, typically a mobile phone or tablet, from which a user can immediately allow or deny account access via the simple press of a button. Push factor is offered with the **Auth0 Guardian** mobile app, available for both iOS and Android. To learn more, read [Auth0 Guardian](/docs/secure/multi-factor-authentication/auth0-guardian).

If you don’t want your customers to have to download a separate application, Auth0 also provides a **Guardian SDK** for building a second-factor workflow in your existing mobile device app. To learn more, read [Install Guardian SDK](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/install-guardian-sdk).

### SMS notifications

Send users a one-time code over SMS which the user is then prompted to enter before they can finish authenticating. To learn more, read [Configure SMS and Voice Notifications for MFA.](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-sms-voice-notifications-mfa)

### Voice notifications

Deliver a one-time code to users through voice call which the user is then prompted to enter before they can finish authenticating. To learn more, read [Configure SMS and Voice Notifications for MFA.](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-sms-voice-notifications-mfa)

### One-Time passwords

One-time passwords allow you to use an authenticator application on the user's personal device, such as Google Authenticator, to generate a one-time password that changes over time and which can be entered as the second factor to validate an account. To learn more, read [Configure OTP Notifications for MFA.](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-otp-notifications-for-mfa)

### WebAuthn with security keys

Enable users to perform MFA with FIDO compliant Security Keys (e.g. [Yubikey](https://www.yubico.com/), [Google Titan](https://cloud.google.com/titan-security-key)). To learn more, read [Configure WebAuthn with Security Keys for MFA.](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-security-keys-for-mfa)

### WebAuthn with device biometrics

Enable users to perform MFA using platform authenticators such as are MacBook’s TouchBar, Windows Hello, iOS Touch/FaceId, and Android’s fingerprint/face recognition. To learn more, read [Configure WebAuthn with Device Biometrics for MFA.](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-device-biometrics-for-mfa)

### Email notifications

Enable users to perform MFA using one-time passwords delivered through email if the users are enrolled with additional [independent authentication factors](/docs/secure/multi-factor-authentication/enable-mfa#independent-factors). To learn more, read [Configure Email Notifications for MFA.](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-email-notifications-for-mfa)

### Cisco Duo security

Cisco Duo is a multi-faceted provider and can only be used if it's the only factor available for the user. Use your Duo account to manage MFA with Auth0. To learn more, read [Configure Cisco Duo Security for MFA.](/docs/secure/multi-factor-authentication/configure-cisco-duo-for-mfa)

### Recovery codes

Recovery codes are unique codes allowing users to regain account access if they cannot access the device or account used for MFA enrollment. To learn more, read [Configure Recovery Codes for MFA.](/docs/secure/multi-factor-authentication/configure-recovery-codes-for-mfa)

## Policies

Policies determine when a user will be prompted to complete additional steps to prove they own a particular account. Use policies to define your own level of acceptable risk. You can choose between **Never**, **Use <Tooltip href="/docs/glossary?term=Adaptive+MFA">Adaptive MFA</Tooltip>**, and **Always**.

You can achieve more refined multi-factor configurations (such as per application, per user, etc.) by using Auth0 Actions. To learn more, read [Auth0 Actions](/docs/customize/actions).

<Callout icon="file-lines">
  Rules affecting MFA takes precedence over the policy configuration in the Dashboard.
</Callout>

To learn more, read [Defined Authentication Policies on OpenID.](http://openid.net/specs/openid-provider-authentication-policy-extension-1_0.html#rfc.section.4)

## Use cases

There are different ways to manage MFA depending on your environment:

* B2B: Your customers manage MFA factors for their users.
* B2C: End users manage their own MFA factors via an **My MFA Settings** page.
* B2E: You manage MFA factors for your users.

To learn about the API endpoints that you can use to build a user interface to manage MFA factors, see [Manage Authenticator Factors Using the MFA API.](/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis/manage-authenticator-factors-mfa-api)

Applications that allow access to different types of resources can require users to authenticate with a stronger authentication mechanism to access sensitive resources. See [Step-Up Authentication](/docs/secure/multi-factor-authentication/step-up-authentication) for details.

To create an Action go to [Dashboard > Actions > Flows](https://manage.auth0.com/#/actions/flows) and define conditions to trigger authentication challenges. Use Actions to force MFA for users of certain applications, or for users with particular user metadata or IP ranges, among other triggers.

Add contextual MFA which allows you to define arbitrary conditions that will trigger additional authentication challenges to your customers for increased security, for example, geographic location (geofencing), address or type of network used (IP filtering), time of day, day of the week or change in the location or device being used to log in.

## Learn more

* [Configure Push Notifications for MFA](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-push-notifications-for-mfa)
* [Configure SMS and Voice Notifications for MFA](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-sms-voice-notifications-mfa)
* [Configure OTP Notifications for MFA](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-otp-notifications-for-mfa)
* [Configure Email Notifications for MFA](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-email-notifications-for-mfa)
* [Configure Cisco Duo Security for MFA](/docs/secure/multi-factor-authentication/configure-cisco-duo-for-mfa)
* [Configure WebAuthn with Security Keys for MFA](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-security-keys-for-mfa)


# Configure Push Notifications for MFA
Source: https://auth0.com/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-push-notifications-for-mfa

Describes how to configure push notifications for MFA.

The [Guardian](/docs/secure/multi-factor-authentication/auth0-guardian) SDKs for [iOS](/docs/secure/multi-factor-authentication/auth0-guardian/guardian-for-ios-sdk) and [Android](/docs/secure/multi-factor-authentication/auth0-guardian/guardian-for-android-sdk) allow you to use a custom-built app for vendor-specific push notification services. You can configure push notifications for the AWS Simple Notification Service (SNS) platform or use Direct to Vendor services to add Firebase Cloud Messaging (FCM) and Apple Push Notification (APN) credentials directly in Auth0.

## AWS SNS Configuration

Before you configure push notifications, follow the prerequisites below:

1. [Create an SNS Platform Application](https://console.aws.amazon.com/sns/v3/home?region=us-east-1#/mobile/push-notifications/platform-applications) using AWS Management console and note it’s ARN.
2. Create an AWS Access Key ID authorized to create Platform Application endpoints. Guardian automatically creates a Platform Application endpoint with an appropriate device token as part of a successful enrollment.

### Configure push notifications with AWS SNS

To receive push notifications from Guardian, you first need to override Guardian's default SNS settings. Then, you can configure push notifications for Android and iOS.

1. On the Auth0 Dashboard, navigate to [Security > Multi-factor Auth](https://manage.auth0.com/#/security/mfa) and select **Push via Auth0 Guardian**. If the method is inactive, select the toggle at the top right to enable it.
2. Select **Custom** to reveal additional settings.
3. In the Push Notification Service section, choose **Amazon SNS.**

<Frame>
  <img alt="Auth0 Dashboard > Security > Multi-factor Auth > Guardian > Custom > Amazon SNS" />
</Frame>

1. In the Amazon SNS Configuration section, complete the following fields:

   <table>
     <thead>
       <tr>
         <th><strong>Field</strong></th>
         <th><strong>Description</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>AWS Access Key ID</td>
         <td>Your AWS Access Key ID.</td>
       </tr>

       <tr>
         <td>AWS Secret Access Key</td>
         <td>Your AWS Secret Access Key.</td>
       </tr>

       <tr>
         <td>AWS Region</td>
         <td>Your AWS application's region.</td>
       </tr>
     </tbody>
   </table>
2. Select **Save** to complete your changes.

## Configure push notifications for Android using FCM

<Tabs>
  <Tab title="Get FCM credentials">
    To configure Android push notifications on your Auth0 Dashboard, first retrieve your FCM server credentials. For full details, review Google's [Firebase documentation](https://firebase.google.com/docs/admin/setup#initialize-sdk).

    1. Navigate to the Firebase Console and select your applicable project.
    2. Open the **Settings** menu and choose **Service Accounts**.
    3. Select **Generate New Private Key** to download your credential file.

    After you retrieve your credentials, you can configure push notifications on your Auth0 Dashboard.
  </Tab>

  <Tab title="Configure Auth0 Dashboard">
    After retrieving your credentials, you can configure Android push notifications from your Auth0 Dashboard.

    1. Navigate to [Security > Multi-factor Auth](https://manage.auth0.com/#/guardian) and select **Push Notification using Auth0 Guardian**.
    2. In the Push Notification App section, select **Custom** to reveal additional settings.
    3. In the Android App Configuration section, configure the following:

       <table>
         <thead>
           <tr>
             <th><strong>Setting</strong></th>
             <th><strong>Description</strong></th>
           </tr>
         </thead>

         <tbody>
           <tr>
             <td>Enable Android App</td>
             <td>Allows Auth0 to send push notifications to your custom application. If this option is not enabled, push notifications cannot be sent.</td>
           </tr>

           <tr>
             <td>Google Play Store URL</td>
             <td>Provide a link to the custom application users must download to configure MFA.</td>
           </tr>

           <tr>
             <td>FCM Server Credentials</td>
             <td>Upload your <a href="https://firebase.google.com/docs/admin/setup#initialize-sdk">FCM server credentials</a>.</td>
           </tr>
         </tbody>
       </table>
    4. Select **Save** to complete your changes.
  </Tab>
</Tabs>

## Configure push notifications for iOS using APNs

<Tabs>
  <Tab title="Get APN certificate">
    To configure iOS push notifications on your Auth0 Dashboard, first retrieve your APN certificate.

    1. Generate a [new APN certificate](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/establishing_a_certificate-based_connection_to_apns#2947597) from your Apple developer account.

    2. Install the certificate locally.

    3. Find the **Apple Sandbox Push Services:&#x20;**&#x20;certificate in your Keychain Access.

    4. Export the certificate and the associated private key to a P12 file without a password (default name: `Certificates.p12`).

    5. To generate a P12 file using Triple DES instead of RC2, run

       ```bash lines theme={null}
       openssl pkcs12 -in Certificates.p12 -legacy -nocerts -nodes -out pk.pem -passin pass:"" &&
       openssl pkcs12 -in Certificates.p12 -legacy -nokeys -out cert.crt -passin pass:"" &&
       openssl pkcs12 -export -inkey pk.pem -in cert.crt -descert -out Certificate_3des.p12 -passout pass:"" &&
       rm pk.pem cert.crt
       ```

    6. Delete `Certificates.p12` and use `Certificate_3des.p12` as the APN certificate in the Auth0 Dashboard.

    After you retrieve your credentials, you can configure push notifications on your Auth0 Dashboard.
  </Tab>

  <Tab title="Configure Auth0 Dashboard">
    After retrieving your credentials, you can configure iOS push notifications from your Auth0 Dashboard.

    1. Navigate to [Security > Multi-factor Auth](https://manage.auth0.com/#/guardian) and select **Push Notification using Auth0 Guardian**.
    2. In the Push Notification App section, select **Custom** to reveal additional settings.
    3. In the iOS App Configuration section, configure the following:

       <table>
         <thead>
           <tr>
             <th><strong>Field</strong></th>
             <th><strong>Description</strong></th>
           </tr>
         </thead>

         <tbody>
           <tr>
             <td>Enable iOS App</td>
             <td>Allows Auth0 to send push notifications to your custom application. If this option is not enabled, push notifications cannot be sent.</td>
           </tr>

           <tr>
             <td>Apple App Store URL</td>
             <td>Provide a link to the custom application users must download to configure MFA.</td>
           </tr>

           <tr>
             <td>APNs Bundle ID</td>
             <td>Provided by iOS Developer Console.</td>
           </tr>

           <tr>
             <td>APNs Certificate</td>
             <td>Upload your <a href="https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/establishing_a_certificate-based_connection_to_apns">P12 certificate</a>.</td>
           </tr>

           <tr>
             <td>iOS App Environment</td>
             <td>Set this based on the configuration within your Apple developer account.</td>
           </tr>
         </tbody>
       </table>
    4. Select **Save** to complete your changes.
  </Tab>
</Tabs>

## Learn more

* [Auth0 Guardian](/docs/secure/multi-factor-authentication/auth0-guardian)
* [Guardian for Android SDK](/docs/secure/multi-factor-authentication/auth0-guardian/guardian-for-android-sdk)
* [Guardian.swift iOS SDK](/docs/secure/multi-factor-authentication/auth0-guardian/guardian-for-ios-sdk)
* [Create Custom Enrollment Tickets](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/create-custom-enrollment-tickets)
* [Enroll and Challenge Push Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-push-authenticators)


# Adaptive MFA
Source: https://auth0.com/docs/secure/multi-factor-authentication/adaptive-mfa

Learn about Adaptive MFA, including how it works, how to customize it, and what flows are supported.

<Callout icon="file-lines">
  To use Adaptive MFA, you must have an Enterprise Plan with the Adaptive MFA addon. Refer to [Auth0 Pricing](https://auth0.com/pricing/) for details.
</Callout>

<Tooltip href="/docs/glossary?term=Adaptive+MFA">Adaptive MFA</Tooltip> is a flexible, extensible <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> policy that can help you protect your tenant from <Tooltip href="/docs/glossary?term=bad+actors">bad actors</Tooltip> without increasing friction for real users. It assesses potential risk during every login transaction, and then prompts the user for additional verification if appropriate.

## How it works

During a login transaction, Adaptive MFA calculates an overall confidence score based on analysis of three risk assessments:

<table>
  <thead>
    <tr>
      <th><strong>Assessor</strong></th>
      <th><strong>Risk Signal</strong></th>
      <th><strong>How it is computed</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>NewDevice</code></td>
      <td>User attempts to sign in from a device that has not been used to access the account in the last 30 days.</td>
      <td>User agent and browser cookies identify a device. At login time, the device information is compared to the list of devices for the account.</td>
    </tr>

    <tr>
      <td><code>ImpossibleTravel</code></td>
      <td>User attempts to sign in from a geolocation that indicates an impossible travel situation when compared to the last login.</td>
      <td>The distance between the last valid location and the location of the attempted sign in is computed; the time difference between the sign in attempt is used to compute a hypothetical travel velocity. Velocity is compared to a reasonable travel velocity.</td>
    </tr>

    <tr>
      <td><code>UntrustedIP</code></td>
      <td>User attempts to sign in from an IP address known to be associated with suspicious behavior.</td>
      <td>Auth0 uses intelligence from traffic events to determine the likelihood that the IP address has been used by bad actors to perpetrate high velocity attacks.</td>
    </tr>

    <tr>
      <td>Overall Risk Score</td>
      <td>A combination of all 3 factors above.</td>
      <td>Auth0 uses all 3 scores to assign an overall score. Use <a href="/docs/secure/multi-factor-authentication/adaptive-mfa/customize-adaptive-mfa">Actions</a> if you want to implement your own business logic.</td>
    </tr>
  </tbody>
</table>

When Adaptive MFA determines the overall confidence score is low (that the login transaction is high-risk), it requires the user to verify their identity with MFA. If the user is not enrolled in MFA, they are required to complete additional verification before they are eligible to do so.

Adaptive MFA includes a comprehensive security flow that ensures the authenticity of users:

<Frame>
  <img alt="Auth0 Login Adaptive multi-factor authentication flow diagram" />
</Frame>

Adaptive MFA ignores any and all existing MFA sessions (for example, a user selected **Remember this browser** during a previous MFA flow), and does not allow users to bypass MFA challenges.

## Customize Adaptive MFA

You can use Actions to customize the MFA flow and provide the best experience for your users.

To learn more about risk assessments, confidence scores, and customization options, read [Customize Adaptive MFA](/docs/secure/multi-factor-authentication/adaptive-mfa/customize-adaptive-mfa).

## Support and limitations

### Authorization flows

Adaptive MFA is supported by all authentication and <Tooltip href="/docs/glossary?term=authorization+flows">authorization flows</Tooltip> that start with the end user. To learn more about the different flows and protocols, read [Authentication and Authorization Flows](/docs/get-started/authentication-and-authorization-flow) and [Protocols](/docs/authenticate/protocols).

<table>
  <thead>
    <tr>
      <th><strong>Protocol</strong></th>
      <th><strong>Flow</strong></th>
      <th><strong>Supported</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>OIDC/OAuth2</td>
      <td>Authorization Code Flow</td>
      <td>Supported</td>
    </tr>

    <tr>
      <td>OIDC/OAuth2</td>
      <td>Authorization Code Flow with PKCE</td>
      <td>Supported</td>
    </tr>

    <tr>
      <td>OIDC/OAuth2</td>
      <td>Implicit Flow with Form Post</td>
      <td>Supported</td>
    </tr>

    <tr>
      <td>OIDC/OAuth2</td>
      <td>Hybrid Flow</td>
      <td>Supported</td>
    </tr>

    <tr>
      <td>OIDC/OAuth2</td>
      <td>Client Credentials</td>
      <td>Not supported</td>
    </tr>

    <tr>
      <td>OIDC/OAuth2</td>
      <td>Device Authorization</td>
      <td>Not supported</td>
    </tr>

    <tr>
      <td>OIDC/OAuth2</td>
      <td>Resource Owner Password (ROP)</td>
      <td>Not supported</td>
    </tr>

    <tr>
      <td>SAML</td>
      <td>Service Provider-Initiated (SP-initiated)</td>
      <td>Supported</td>
    </tr>

    <tr>
      <td>SAML</td>
      <td>Identity Provider-Initiated (IdP-initiated)</td>
      <td>Not supported\*</td>
    </tr>

    <tr>
      <td>WS-Federation</td>
      <td>N/A</td>
      <td>Supported</td>
    </tr>

    <tr>
      <td>AD/LDAP</td>
      <td>N/A</td>
      <td>Supported</td>
    </tr>
  </tbody>
</table>

\*Adaptive MFA is not supported for <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> <Tooltip href="/docs/glossary?term=IdP">IdP</Tooltip>-initiated flows, but you can simulate the flow with OIDC applications. To learn more, read [Configure IdP-Initiated SAML Sign-on to OIDC Apps](/docs/authenticate/protocols/saml/saml-sso-integrations/configure-idp-initiated-saml-sign-on-to-oidc-apps).

### Social connections

Adaptive MFA is fully supported for social connection types where an email address is available for each user.

Adaptive MFA requires an email address to complete the email challenge step that occurs when a user is not enrolled in MFA. If an email address is not available, Adaptive MFA cannot perform the email challenge and the transaction will be blocked. This scenario does not introduce a security risk, but it does limit the functionality of the feature.

If you’ve set up a social connection, and expect an email address to be available but it’s not, verify your configuration and confirm that the correct scopes, claims, and permissions are being requested. To learn more about supported social connections and how to install them, read [Social Connections on Auth0 Marketplace](https://marketplace.auth0.com/features/social-connections).

### Auth0 features

The following table lists Auth0 implementations and their functionality with Adaptive MFA:

<table>
  <thead>
    <tr>
      <th><strong>Login Flow Implementation</strong></th>
      <th><strong>Adaptive MFA Support Level</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Universal Login</td>
      <td>Supported</td>
    </tr>

    <tr>
      <td>Classic Login with no customization</td>
      <td>Supported</td>
    </tr>

    <tr>
      <td>Classic Login (hosted by Auth0), custom login page with <code>lock.js</code> Lock template</td>
      <td>Supported</td>
    </tr>

    <tr>
      <td>Classic Login (hosted by Auth0), custom login page with <code>auth0.js</code> Custom Login Form template</td>
      <td>Supported</td>
    </tr>

    <tr>
      <td>Classic Login (hosted by Auth0), custom login page with email passwordless flow and <code>lock.js</code> Passwordless template</td>
      <td>Supported</td>
    </tr>

    <tr>
      <td>Classic Login (hosted by Auth0), custom login page with SMS passwordless flow and <code>lock.js</code> Passwordless template</td>
      <td>Not supported, because it does not make an email address available, which is a requirement.</td>
    </tr>

    <tr>
      <td>Web or native apps using Resource Owner Password Grant (ROPG) flow (including those using older versions of <code>lock.android</code> and <code>lock.swift</code> SDKs</td>
      <td>Supported, with the following limitations: <br />• Works when all end users are already enrolled in MFA (when users are required to enroll on signup). Users who are not already enrolled will be blocked in risky scenarios. <br />• Risk assessment to determine if a user is logging in from a new device will not work. The ROPG flow does not support the browser cookies needed to determine risk. <br />• You must pass <code>auth0-forwarded-for</code> header with information from the originating IP address for risk assessments for IP reputation to work.</td>
    </tr>

    <tr>
      <td>Native apps using newest version of SDKs that support embedded Universal Login</td>
      <td>Supported</td>
    </tr>

    <tr>
      <td>Native apps using newest version of SDKs and ROPG flow</td>
      <td>Supported with the following limitations: <br />• Works when all end users are already enrolled in MFA (when users are required to enroll on signup). Users who are not already enrolled will be blocked in risky scenarios. <br />• Risk assessment to determine if a user is logging in from a new device will not work. The ROPG flow does not support the browser cookies needed to determine risk. <br />• You must pass <code>auth0-forwarded-for</code> header with information from the originating IP address for risk assessments for IP reputation to work.</td>
    </tr>

    <tr>
      <td>Flows hosted by you (not Auth0) using <code>lock.js</code> or <code>auth0.js</code> that perform cross-origin authentication (co/authenticate endpoint)</td>
      <td>Supported</td>
    </tr>
  </tbody>
</table>

## Learn more

* [Enable Adaptive MFA](/docs/secure/multi-factor-authentication/adaptive-mfa/enable-adaptive-mfa)
* [Customize Adaptive MFA](/docs/secure/multi-factor-authentication/adaptive-mfa/customize-adaptive-mfa)
* [Adaptive MFA Log Events](/docs/secure/multi-factor-authentication/adaptive-mfa/adaptive-mfa-log-events)


# Adaptive MFA Log Events
Source: https://auth0.com/docs/secure/multi-factor-authentication/adaptive-mfa/adaptive-mfa-log-events

Describes tenant log events that capture Adaptive Multi-Factor Authentication (MFA) activities in Auth0.

Your tenant logs contain entries for successful and failed login events including information related to <Tooltip href="/docs/glossary?term=Adaptive+MFA">Adaptive MFA</Tooltip> risk assessment scores. These are the same entries as those that can be used in rule context objects. The Adaptive <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> entries have the following structure:

```json lines expandable theme={null}
{
  "date": "2020-06-26T15:12:43.654Z",
  "type": "s",
  "details": {
    "riskAssessment": {
      "confidence": "high",
      "assessments": {
        "UntrustedIP": {
          "confidence": "high",
          "code": "not_found_on_deny_list"
    	},
    	"NewDevice": {
      	  "confidence": "medium",
      	  "code": "partial_match",
          "details": {
            "device": "unknown",
            "useragent": "known",
          }
    	},
    	"ImpossibleTravel": {
      	  "confidence": "high",
      	  "code": "minimal_travel_from_last_login"
    	}
      }
    }
  },
  "description": "Successful login"
}
```

Here is an example:

```json lines expandable theme={null}
{
  "date": "2020-06-24T20:24:39.412Z",
  "type": "s",
  "description": "Successful login",
  "connection": "Username-Password-Authentication",
  "connection_id": "con_16Tpc6YqlWZ4HCut",
  "client_id": "9ZteveEZ8CqSLtCNXgvhoCJQ0jt2xSxe",
  "client_name": "jwt.io",
  "ip": "10.12.13.1",
  "client_ip": null,
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:77.0) Gecko/20100101 Firefox/77.0",
  "details": {
    "prompts": [
      {
        "name": "prompt-authenticate",
        "initiatedAt": null,
        "completedAt": 1593030278513,
        "connection": "Username-Password-Authentication",
        "connection_id": null,
        "strategy": "auth0",
        "identity": "5ee10b1ca85332004e44ce3e",
        "stats": {
          "loginsCount": 66
        },
        "elapsedTime": null
      },
      {
        "name": "login",
        "flow": "universal-login",
        "initiatedAt": 1593030268561,
        "completedAt": 1593030278558,
        "timers": {
          "rules": 336
        },
        "user_id": "auth0|5ee10b1ca85332004e44ce3e",
        "user_name": "user@josh.local.dev.auth0.com",
        "elapsedTime": 9997
      }
    ],
    "initiatedAt": 1593030268550,
    "completedAt": 1593030279374,
    "elapsedTime": 10824,
    "session_id": "dKvR03IjVSNLPaVLqVS-FBuX87z0bBoE",
    "riskAssessment": {
      "confidence": "medium",
      "assessments": {
        "UntrustedIP": {
          "confidence": "high",
          "code": "ip_not_found"
        },
        "NewDevice": {
          "confidence": "medium",
          "code": "match_useragent",
          "details": {
            "device": "unknown",
            "useragent": "known",
          }
        },
        "ImpossibleTravel": {
          "confidence": "low",
          "code": "missing_geoip"
        }
      }
    },
    "stats": {
      "loginsCount": 66
    }
  },
  "hostname": "josh.local.dev.auth0.com",
  "user_id": "auth0|5ee10b1ca85332004e44ce3e",
  "user_name": "user@josh.local.dev.auth0.com",
  "strategy": "auth0",
  "strategy_type": "database"
}
```

## Attack protection details

In addition to providing information for rules execution, Auth0 includes adaptive MFA <Tooltip href="/docs/glossary?term=attack+protection">attack protection</Tooltip> information to your tenant logs. The same data structure that appears in rules appears in the tenant logs:

```json lines expandable theme={null}
{
  "date": "2020-06-26T15:12:43.654Z",
  "type": "s",
  "details": {
	"anomalyDetection": {
  	  "confidence": "high",
  	  "assessments": {
    	    "UntrustedIP": {
      	    "confidence": "high",
      	    "reason": "ip not found",
      	    "code": "ip_not_found"
    	    },
    	    "NewDevice": {
      	    "confidence": "medium",
      	    "reason": "match useragent",
      	    "code": "match_useragent"
    	    },
    	    "ImpossibleTravel": {
      	    "confidence": "high",
      	    "reason": "minimal travel",
      	    "code": "minimal_travel_from_last_login"
    	    }
  	  }
	},
  },
  "description": "Successful login"
}
```

## MFA prompt details

When adaptive MFA is enabled, users will be prompted for MFA enrollment on their first login attempt with a low confidence score. An **mfa** prompt may appear in the login event details. For example:

```json lines expandable theme={null}
{
  "_id": "5ef3bb0a72487a0047c32959",
  "date": "2020-06-24T20:43:54.159Z",
  "type": "s",
  "description": "Successful login",
  "connection": "Username-Password-Authentication",
  "connection_id": "con_16Tpc6YqlWZ4HCut",
  "client_id": "9ZteveEZ8CqSLtCNXgvhoCJQ0jt2xSxe",
  "client_name": "jwt.io",
  "ip": "10.12.13.1",
  "client_ip": null,
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:77.0) Gecko/20100101 Firefox/77.0",
  "details": {
    "prompts": [
      {
        "name": "prompt-authenticate",
        "completedAt": 1593031413909,
        "connection": "Username-Password-Authentication",
        "strategy": "auth0",
        "identity": "5ee10b1ca85332004e44ce3e",
        "stats": {
          "loginsCount": 67
        },
        "elapsedTime": null
      },
      {
        "name": "login",
        "flow": "universal-login",
        "initiatedAt": 1593031371948,
        "completedAt": 1593031413953,
        "timers": {
          "rules": 443
        },
        "user_id": "auth0|5ee10b1ca85332004e44ce3e",
        "user_name": "user@josh.local.dev.auth0.com",
        "elapsedTime": 42005
      },
      {
        "name": "mfa",
        "flow": "universal-mfa",
        "initiatedAt": 1593031414863,
        "completedAt": 1593031433795,
        "performed_acr": [
          "http://schemas.openid.net/pape/policies/2007/06/multi-factor"
        ],
        "performed_amr": [
          "mfa"
        ],
        "provider": "guardian",
        "elapsedTime": 18932
      }
    ],
    "initiatedAt": 1593031371938,
    "completedAt": 1593031434151,
    "elapsedTime": 62213,
    "session_id": "ulYRdsS1F4wIKLpUfQDfhyXgKVJqJaEv",
    "riskAssessment": {
      "confidence": "medium",
      "assessments": {
        "UntrustedIP": {
          "confidence": "high",
          "code": "ip_not_found"
        },
        "NewDevice": {
          "confidence": "medium",
          "code": "match_useragent",
          "details": {
            "device": "unknown",
            "useragent": "known",
          }
        },
        "ImpossibleTravel": {
          "confidence": "low",
          "code": "missing_geoip"
        }
      }
    },
    "stats": {
      "loginsCount": 67
    }
  },
  "hostname": "josh.local.dev.auth0.com",
  "user_id": "auth0|5ee10b1ca85332004e44ce3e",
  "user_name": "user@josh.local.dev.auth0.com",
  "strategy": "auth0",
  "strategy_type": "database"
}
```

## MFA provider details

Events may appear for certain MFA providers. Here is an example that includes **OTP Auth Succeeded** event.

```json lines expandable theme={null}
{
  "_id": "5ef3bb0922b43d004844af00",
  "date": "2020-06-24T20:43:53.758Z",
  "type": "gd_auth_succeed",
  "description": "Guardian - Second factor authentication succeed (totp)",
  "ip": "10.12.13.1",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:77.0) Gecko/20100101 Firefox/77.0",
  "details": {
    "request": {
      "method": "POST",
      "path": "/api/totp/configs/josh/authenticators/totp%7Cdev_3KQv6yQ06pLoksIe/verify",
      "query": {},
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:77.0) Gecko/20100101 Firefox/77.0",
      "body": {
        "code": "********"
      },
      "ip": "10.12.13.1",
      "auth": {
        "subject": null,
        "strategy": "jwt_api2_internal_token",
        "scopes": [
          "read:authenticators",
          "verify:authenticator"
        ]
      }
    },
    "response": {
      "body": {},
      "statusCode": null
    },
    "authenticator": {
      "id": "totp|dev_3KQv6yQ06pLoksIe",
      "type": "totp"
    },
    "device_id": "v0:45e50ea0-b65b-11ea-9dd7-27e2c7f14291"
  },
  "user_id": "auth0|5ee10b1ca85332004e44ce3e"
}
```

## Learn more

* [Customize Adaptive MFA](/docs/secure/multi-factor-authentication/adaptive-mfa/customize-adaptive-mfa)


# Customize Adaptive MFA
Source: https://auth0.com/docs/secure/multi-factor-authentication/adaptive-mfa/customize-adaptive-mfa

Learn how to customize Adaptive Multi-Factor Authentication (MFA).

You can customize <Tooltip href="/docs/glossary?term=Adaptive+MFA">Adaptive MFA</Tooltip> for a variety of scenarios with [Auth0 Actions](/docs/customize/actions).

## When to customize Adaptive MFA

<Callout icon="file-lines">
  You should only consider customizing Adaptive MFA if your users are enrolled in MFA and are required to use an email as an identifier.
</Callout>

If your users are not enrolled in <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip>, you should use the default policy for Adaptive MFA. If a user is not enrolled in MFA and your Action assesses a high risk, you have limited options to stop a <Tooltip href="/docs/glossary?term=bad+actor">bad actor</Tooltip>.

Before you begin to customize Adaptive MFA, ask yourself a few questions:

* At what confidence level do you want to trigger MFA?
* How do you want to measure risk?
* Do you want Auth0 to measure confidence or do you want a custom measurement?
* How will you handle users who are not enrolled in MFA?

## Evaluate confidence

Adaptive MFA calculates an overall confidence score based on the analysis of three assessments. Each assessment has its own confidence score. To learn more, read [Adaptive MFA](/docs/secure/multi-factor-authentication/adaptive-mfa).

### Confidence scores

Confidence scores and their associated actions are described below:

<table>
  <thead>
    <tr>
      <th><strong>Confidence score</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Action</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>low</code></td>
      <td>Login transaction does not match patterns previously displayed by user.</td>
      <td>Require MFA.</td>
    </tr>

    <tr>
      <td><code>medium</code></td>
      <td>Login transaction somewhat matches patterns previously displayed by user.</td>
      <td>Do not require MFA.</td>
    </tr>

    <tr>
      <td><code>high</code></td>
      <td>Login transaction closely matches patterns previously displayed by user.</td>
      <td>Do not require MFA.</td>
    </tr>

    <tr>
      <td><code>neutral</code></td>
      <td>N/A. Reserved for future use.</td>
      <td>N/A. Reserved for future use.</td>
    </tr>
  </tbody>
</table>

### Custom confidence scoring

If you want to implement your own method for evaluating the overall confidence score of different scenarios, you can use the data available in the [riskAssessment](#riskassessment-context-object) object.

Read the examples below to learn how Adaptive MFA would score the confidence of different use cases.

#### Examples of high-risk, low-confidence scenarios

The following table describes high-risk scenarios that result in a `low` confidence score:

<table>
  <thead>
    <tr>
      <th><strong>User State</strong></th>
      <th><strong>Desired Login Friction</strong></th>
      <th><strong>Desired Enrollment Policy</strong></th>
      <th><strong>Implementation</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Enrolled in MFA</td>
      <td>Do not require MFA</td>
      <td>N/A (user already enrolled)</td>
      <td>Use an Action to bypass MFA</td>
    </tr>

    <tr>
      <td>Not enrolled in MFA</td>
      <td>Require email verification</td>
      <td>Skip enrollment (do not collect additional authenticators)</td>
      <td>Default behavior (no MFA-related Action)</td>
    </tr>

    <tr>
      <td>Not enrolled in MFA</td>
      <td>Require email verification</td>
      <td>Require MFA enrollment (collect additional authenticator)</td>
      <td>Use an Action to force MFA enrollment (template available)</td>
    </tr>
  </tbody>
</table>

#### Examples of low-risk, high-confidence scenarios

The following table describes low-risk scenarios that result in a `high` confidence score:

<table>
  <thead>
    <tr>
      <th><strong>User State</strong></th>
      <th><strong>Desired Login Friction</strong></th>
      <th><strong>Desired Enrollment Policy</strong></th>
      <th><strong>Implementation</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Enrolled in MFA</td>
      <td>No friction</td>
      <td>N/A (user already enrolled)</td>
      <td>Default behavior (no MFA-related Action)</td>
    </tr>

    <tr>
      <td>Not enrolled in MFA</td>
      <td>No friction</td>
      <td>Skip enrollment (do not collect additional authenticators)</td>
      <td>Default behavior (no MFA-related Action)</td>
    </tr>

    <tr>
      <td>Not enrolled in MFA</td>
      <td>No friction</td>
      <td>Require MFA enrollment (collect additional authenticator)</td>
      <td>Use an Action to force MFA enrollment (template available)</td>
    </tr>
  </tbody>
</table>

### riskAssessment object

The `riskAssessment` object contains the overall confidence score, versioning information, and details of the individual assessments.

<table>
  <thead>
    <tr>
      <th><strong>Property</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Possible values</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>confidence</code></td>
      <td>Overall confidence score calculated by Adaptive MFA.</td>
      <td>string</td>
      <td><code>low</code>, <code>medium</code>, <code>high</code>, <code>neutral</code></td>
    </tr>

    <tr>
      <td><code>version</code></td>
      <td>Version identifier of risk assessment API.</td>
      <td>string</td>
      <td><code>1</code></td>
    </tr>

    <tr>
      <td><code>assessments</code></td>
      <td>Object containing individual assessment details.</td>
      <td>object</td>
      <td>Read <a href="#assessments-object">assessments object</a></td>
    </tr>
  </tbody>
</table>

```js lines expandable theme={null}
exports.onExecutePostLogin = async (event, api) => {
  if (event.authentication && event.authentication.riskAssessment) {
    event.authentication.riskAssessment = {
      confidence: 'low' | 'medium' | 'high' | 'neutral',
      version: '1',
      assessments: {
        UntrustedIP: {
          confidence: 'low' | 'medium' | 'high' | 'neutral',
          code: 'not_found_on_deny_list' | 'found_on_deny_list',
          details: { // only if 'found_on_deny_list'
            ip: '192.168.1.1',
            matches: '192.168.0/64',
            source: 'firehol',
            category: 'abuse'
          }
        },
        NewDevice: {
          confidence: 'low' | 'medium' | 'high' | 'neutral',
          code: 'match' | 'partial_match' | 'no_match',
          details: {
            device: 'known' | 'unknown',
            useragent: 'known' | 'unknown',
          }
        },
        ImpossibleTravel: {
          confidence: 'low' | 'medium' | 'high' | 'neutral',
          code: 'missing_geoip', | 'anonymous_proxy' | 'unknown_location' | 'initial_login' | 'location_history_not_found' | 'invalid_travel' | 'minimal_travel_from_last_login' | 'impossible_travel_from_last_login' | 'substantial_travel_from_last_login' | 'travel_from_last_login'
        } 
      },
       PhoneNumber: {
          code: "requires_verification | ok",
          confidence: "low | medium | high | neutral",
          details: {
	        	lineType: "FIXED_LINE | MOBILE | FIXED_LINE_OR_MOBILE | TOLL_FREE | PREMIUM_RATE | SHARED_COST | VOIP | PERSONAL_NUMBER | PAGER | UAN | UNKNOWN"
	            isValid: true | false,
		        countryCode: 1,
		        number: "+12223334444"
        }
      }
    };
  }
}
```

### assessments object

The `assessments` object contains details of the three individual risk assessments:

1. [NewDevice assessment](#newdevice-assessment)
2. [ImpossibleTravel assessment](#impossibletravel-assessment)
3. [UntrustedIP assessment](#untrustedip-assessment)
4. [PhoneNumber assessment](#phonenumber-assessment)

Each assessment includes a [confidence score](#confidence-scores), a code that describes the evaluation result, and additional contextual information.

<Callout icon="file-lines">
  In the unlikely case of an assessment back-end system failure, the assessment code will be `assessment_not_available` and the associated confidence will be `low` because Auth0 defaults to a secure behavior. You can override this scoring using Actions. To learn more, read [Safely handle when Auth0 fails to execute assessors](#safely-handle-when-auth0-fails-execute-assessors).
</Callout>

#### NewDevice assessment

The `NewDevice` assessment determines if the user is logging in from a known device and contains the following properties:

<table>
  <thead>
    <tr>
      <th><strong>Property</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Possible values</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>confidence</code></td>
      <td>Confidence score calculated by Adaptive MFA.</td>
      <td>string</td>
      <td><code>low</code>, <code>medium</code>, <code>high</code>, <code>neutral</code></td>
    </tr>

    <tr>
      <td><code>code</code></td>
      <td>Evaluation result of the assessment.</td>
      <td>string</td>
      <td><code>match</code>, <code>partial\_match</code>, <code>no\_match</code>, <code>initial\_login</code>, <code>unknown\_device</code>, <code>no\_device\_history</code>, <code>assessment\_not\_available</code></td>
    </tr>

    <tr>
      <td><code>details</code></td>
      <td>Additional contextual information.</td>
      <td>object</td>
      <td>Refer to table below.</td>
    </tr>
  </tbody>
</table>

##### NewDevice assessment code property

The `NewDevice` assessment `code` property equals one of the following values:

<table>
  <thead>
    <tr>
      <th><strong>Value</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>match</code></td>
      <td>The property values of the <code>details</code> object are equivalent.</td>
    </tr>

    <tr>
      <td><code>partial\_match</code></td>
      <td>The property values of the <code>details</code> object are similar.</td>
    </tr>

    <tr>
      <td><code>no\_match</code></td>
      <td>The property values of the <code>details</code> object are different.</td>
    </tr>

    <tr>
      <td><code>initial\_login</code></td>
      <td>The user logged in for the first time on the device.</td>
    </tr>

    <tr>
      <td><code>unknown\_device</code></td>
      <td>Auth0 was unable to attain metadata for the device.</td>
    </tr>

    <tr>
      <td><code>no\_device\_history</code></td>
      <td>There is no login history associated with the device.</td>
    </tr>

    <tr>
      <td><code>assessment\_not\_available</code></td>
      <td>Auth0 could not perform an assessment of the device.</td>
    </tr>
  </tbody>
</table>

##### NewDevice assessment details object

If the `code` property value equals `match`, `partial_match`, or `no_match`, the `NewDevice` assessment contains the `details` object with the following properties:

<table>
  <thead>
    <tr>
      <th><strong>Property</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Possible values</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>device</code></td>
      <td>Device of the user.</td>
      <td>string</td>
      <td><code>known</code>, <code>unknown</code></td>
    </tr>

    <tr>
      <td><code>useragent</code></td>
      <td>User agent of the user.</td>
      <td>string</td>
      <td><code>known</code>, <code>unknown</code></td>
    </tr>
  </tbody>
</table>

#### ImpossibleTravel assessment

The `ImpossibleTravel` assessment determines if the user is logging in from a location that would indicate impossible travel and contains the following properties:

<table>
  <thead>
    <tr>
      <th><strong>Property</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Possible values</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>confidence</code></td>
      <td>Confidence score calculated by Adaptive MFA.</td>
      <td>string</td>
      <td><code>low</code>, <code>medium</code>, <code>high</code>, <code>neutral</code></td>
    </tr>

    <tr>
      <td><code>code</code></td>
      <td>Evaluation result of the assessment.</td>
      <td>string</td>
      <td><code>minimal\_travel\_from\_last\_login</code>, <code>travel\_from\_last\_login</code>, <code>substantial\_travel\_from\_last\_login</code>, <code>impossible\_travel\_from\_last\_login</code>, <code>invalid\_travel</code>, <code>missing\_geoip</code>, <code>anonymous\_proxy</code>, <code>unknown\_location</code>, <code>initial\_login</code>, <code>location\_history\_not\_found</code>, <code>assessment\_not\_available</code></td>
    </tr>
  </tbody>
</table>

#### UntrustedIP assessment

The `UntrustedIP` assessment determines if the user’s IP address is present in Auth0’s repository of low-reputation IP addresses (“deny list”) and contains the following properties:

<table>
  <thead>
    <tr>
      <th><strong>Property</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Possible values</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>confidence</code></td>
      <td>Confidence score calculated by Adaptive MFA.</td>
      <td>string</td>
      <td><code>low</code>, <code>medium</code>, <code>high</code>, <code>neutral</code></td>
    </tr>

    <tr>
      <td><code>code</code></td>
      <td>Evaluation result of the assessment.</td>
      <td>string</td>
      <td><code>not\_found\_on\_deny\_list</code>, <code>found\_on\_deny\_list</code>, <code>invalid\_ip\_address</code>, <code>assessment\_not\_available</code></td>
    </tr>

    <tr>
      <td><code>details</code></td>
      <td>Additional contextual information.</td>
      <td>object</td>
      <td>Refer to table below.</td>
    </tr>
  </tbody>
</table>

##### UntrustedIP assessment details object

If the `UntrustedIP` assessment `code` property value equals `found_on_deny_list`, the `details` object is present and contains the following properties:

<table>
  <thead>
    <tr>
      <th><strong>Property</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Possible values</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>ip</code></td>
      <td>IP address of the device.</td>
      <td>string</td>
      <td>Any valid IPv4 or IPv6 address.</td>
    </tr>

    <tr>
      <td><code>matches</code></td>
      <td>Subnet mask that IP address belongs to.</td>
      <td>string</td>
      <td>Any valid IPv4 or IPv6 subnet mask.</td>
    </tr>

    <tr>
      <td><code>source</code></td>
      <td>Name of threat intelligence source for the deny list.</td>
      <td>string</td>
      <td>Any valid text.</td>
    </tr>

    <tr>
      <td><code>category</code></td>
      <td>Category indicating why IP address is untrusted.</td>
      <td>string</td>
      <td><code>abuse</code>, <code>anonymizer</code>, <code>datacenter</code>, <code>reputation</code>, <code>unroutable</code></td>
    </tr>
  </tbody>
</table>

##### UntrustedIP assessment details object category property

The `UntrustedIP` assessment `details` object `category` property describes the general reason why Adaptive MFA considers a given IP address untrusted and equals one of the following values:

<table>
  <thead>
    <tr>
      <th><strong>Value</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>abuse</code></td>
      <td>IP address exhibited abusive behaviors or was found to be member of bot nets.</td>
    </tr>

    <tr>
      <td><code>anonymizer</code></td>
      <td>IP address belongs to anonymizing services such as VPN providers, open proxies, and TOR exit nodes.</td>
    </tr>

    <tr>
      <td><code>datacenter</code></td>
      <td>IP address belongs to cloud hosting providers and colocation datacenters.</td>
    </tr>

    <tr>
      <td><code>reputation</code></td>
      <td>IP address has a poor reputation score based on activity.</td>
    </tr>

    <tr>
      <td><code>unroutable</code></td>
      <td>IP address is not in any range allocated or delegated by any authorized Internet registry or allowed for public use.</td>
    </tr>
  </tbody>
</table>

#### PhoneNumber assessment

The `PhoneNumber` assessment assesses the risk of a phone number for an incoming transaction and contains the following properties:

<table>
  <thead>
    <tr>
      <th><strong>Property</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Possible values</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>code</code></td>
      <td>Describes the evaluation result.</td>
      <td>string</td>
      <td><code>ok</code>, <code>requires\_verification</code>, <code>phone\_number\_not\_provided</code>, <code>assessment\_not\_available</code></td>
    </tr>

    <tr>
      <td><code>confidence</code></td>
      <td>Confidence score calculated by Adaptive MFA.</td>
      <td>string</td>
      <td><code>low</code>, <code>medium</code>, <code>high</code>, <code>neutral</code></td>
    </tr>

    <tr>
      <td><code>details</code></td>
      <td>Additional contextual information.</td>
      <td>object</td>
      <td>Refer to table below.</td>
    </tr>
  </tbody>
</table>

##### PhoneNumber assessment details object

The `PhoneNumber` assessment `details` object contains the following properties:

<table>
  <thead>
    <tr>
      <th><strong>Property</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Possible values</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>lineType</code></td>
      <td>Type of phone line</td>
      <td>string</td>
      <td><code>FIXED\_LINE</code>, <code>MOBILE</code>, <code>FIXED\_LINE\_OR\_MOBILE</code>, <code>TOLL\_FREE</code>, <code>PREMIUM\_RATE</code>, <code>SHARED\_COST</code>, <code>VOIP</code>, <code>PERSONAL\_NUMBER</code>, <code>PAGER</code>, <code>UAN</code>, <code>UNKNOWN</code></td>
    </tr>

    <tr>
      <td><code>isValid</code></td>
      <td>Returns the validity of the number</td>
      <td>boolean</td>
      <td><code>true</code>, <code>false</code></td>
    </tr>

    <tr>
      <td><code>countryCode</code></td>
      <td>Country code of the phone origin</td>
      <td>integer</td>
      <td><code>0-999</code></td>
    </tr>

    <tr>
      <td><code>number</code></td>
      <td>Phone number</td>
      <td>string</td>
      <td>Valid number including <code>countryCode</code></td>
    </tr>
  </tbody>
</table>

## Action result outcomes

<Callout icon="file-lines">
  Actions that trigger MFA take precedence over default Adaptive MFA behavior.
</Callout>

If any of your Actions trigger MFA based on confidence score, the default Adaptive MFA policy triggers MFA when the confidence score is `low`.

The following table shows the possible outcomes based on the combination of Actions and default Adaptive MFA policy actions.

<table>
  <thead>
    <tr>
      <th><strong>Action result</strong></th>
      <th><strong>Adaptive MFA action</strong></th>
      <th><strong>Outcome</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Unauthorized</td>
      <td>Trigger MFA</td>
      <td>Unauthorized</td>
    </tr>

    <tr>
      <td>Unauthorized</td>
      <td>No MFA Required</td>
      <td>Unauthorized</td>
    </tr>

    <tr>
      <td>Trigger MFA</td>
      <td>Trigger MFA</td>
      <td>Trigger MFA</td>
    </tr>

    <tr>
      <td>Trigger MFA</td>
      <td>No MFA Required</td>
      <td>Trigger MFA</td>
    </tr>

    <tr>
      <td>No MFA Required</td>
      <td>Trigger MFA</td>
      <td>Trigger MFA</td>
    </tr>

    <tr>
      <td>No MFA Required</td>
      <td>No MFA Required</td>
      <td>No MFA Required</td>
    </tr>
  </tbody>
</table>

## Action templates

Auth0 provides two Action templates based on Adaptive MFA for you to customize: [Adaptive MFA](#adaptive-mfa) and [Require MFA Enrollment](#require-mfa-enrollment).

### Adaptive MFA template

This template provides an example and starting point for how to build a custom business flow using individual risk assessments.

```javascript lines expandable theme={null}
/**
* Handler that will be called during the execution of a PostLogin flow.
*
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {
    // Decide which confidence scores should trigger MFA, for more information refer to
    const promptConfidences = ['low', 'medium'];

    // Example condition: prompt MFA only based on the NewDevice
    // confidence level, this will prompt for MFA when a user is logging in
    // from an unknown device.
    const confidence =
        event.authentication?.riskAssessment?.assessments?.NewDevice
            ?.confidence;
    const shouldPromptMfa =
        confidence && promptConfidences.includes(confidence);

    // It only makes sense to prompt for MFA when the user has at least one
    // enrolled MFA factor.
    const canPromptMfa =
        event.user.multifactor && event.user.multifactor.length > 0;
    if (shouldPromptMfa && canPromptMfa) {
        api.multifactor.enable('any', { allowRememberBrowser: true });
    }
};
```

### Require MFA Enrollment template

This template demonstrates how you could enforce MFA enrollment when using a standard or Adaptive MFA policy. It uses `event.user.multifactor` to check if the user is enrolled in MFA, and if they’re not, prompts for enrollment.

```javascript lines theme={null}
/**
* Handler that will be called during the execution of a PostLogin flow.
*
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {
    if (!event.user.multifactor?.length) {
        api.multifactor.enable('any', { allowRememberBrowser: false });
    }
};
```

## Action use cases

Here are some suggestions for how to build custom Actions based on your use case.

### Perform an action if overall confidence score is X

Assess the `riskAssessment.confidence` property, and then compare it with the constants `high`, `medium`, or `low`:

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const { riskAssessment } = event.authentication || {};
  const riskIsMedium = riskAssessment && riskAssessment.confidence === 'medium';

  if (riskIsMedium) {
    // ....
  }
}
```

### Perform an action if confidence score is above or below X

Confidence scores are discrete values—not in a range—so you cannot use comparison operators (such as `<` or `>`) to evaluate multiple values in a single condition.

Use multiple conditions to logically combine all the confidence scores you want to handle. For example, if you want to know when the confidence score is greater than `low`, check if it’s equal to `medium` or `high`:

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const { riskAssessment } = event.authentication || {};
  const riskIsMediumOrHigh = riskAssessment && 
                                  (riskAssessment.confidence === 'high' || 
                                   riskAssessment.confidence === 'medium');

  if (riskIsMediumOrHigh) {
    // ...
  }
}
```

### Get additional details if overall confidence score is X

The `riskAssessment` object is saved in your tenant logs. You can view log entries to see the risk assessment score and the determining factors (reasons).

You can view the `riskAssessment` object and report the results elsewhere. For example, you can send an email or save a record in an external database.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const { riskAssessment } = event.authentication || {};
  const riskIsLow = riskAssessment && riskAssessment.confidence === 'low';

  if (riskIsLow) {
    // log(externalDatabase, riskAssessment);
  }
}
```

### Perform an action if a specific assessment has a specific result

Use the [assessments](#assessments-object) object to access the details for individual assessments, including the `code` property:

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const { riskAssessment } = event.authentication || {};
  const { ImpossibleTravel } = riskAssessment && riskAssessment.assessments;

  if (ImpossibleTravel.code === 'impossible_travel_from_last_login') {
    // ...
  }
}
```

### Aggregate assessments for a custom overall confidence score.

Use the [assessments](#assessments-object) object to access the details for individual assessments, and then use the `confidence` property, the `code` property, or both.

To learn more about custom confidence scoring, read [Custom confidence scoring](#custom-confidence-scoring).

### Block current transaction and return error and message if a specific assessment has a specific result

Use the [assessments](#assessments-object) object to access the details for individual assessments, including the `code` property.

Block the login transaction from completing by returning the callback function with an `UnauthorizedError` object as the [error parameter](/docs/troubleshoot/error-handling-best-practices). The `UnauthorizedError` object always sets `error` to `unauthorized`, but you can customize the `error_message`:

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const { riskAssessment } = event.authentication || {};
  const { ImpossibleTravel } = riskAssessment && riskAssessment.assessments;

  if (ImpossibleTravel.code === 'impossible_travel_from_last_login') {
    return api.access.deny('Login blocked due to impossible travel detected.')
  }
}
```

This redirects the user back to the application's callback URL with the `error` and `error_message` parameters included.

### Safely handle when Auth0 fails to execute assessments

Auth0 automatically assigns a `low` confidence score if there is any sort of failure performing the risk assessment.

To mitigate this scenario, use the [assessments](#assessments-object) object to inspect the `code` property for each individual assessment and check if the value is set to `assessment_not_available`.

## Learn more

* [Enable Adaptive MFA](/docs/secure/multi-factor-authentication/adaptive-mfa/enable-adaptive-mfa)
* [Adaptive MFA Log Events](/docs/secure/multi-factor-authentication/adaptive-mfa/adaptive-mfa-log-events)
* [Actions Triggers: post-login - API Object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object)
* [Actions Triggers: post-login - Event Object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object)


# Enable Adaptive MFA
Source: https://auth0.com/docs/secure/multi-factor-authentication/adaptive-mfa/enable-adaptive-mfa

Learn how to enable Adaptive MFA for low confidence logins based on Auth0's risk assessment and overall confidence scores.

<Card title="Before you start">
  * Subscribe to an Enterprise Plan with the Adaptive MFA addon. Refer to [Auth0 Pricing](https://auth0.com/pricing/) for details.
  * Configure and enable a Database or Active Directory connection.
  * Configure and enable at least one MFA factor.
</Card>

Use <Tooltip href="/docs/glossary?term=Adaptive+MFA">Adaptive MFA</Tooltip> to trigger <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> when Auth0 determines that an attempted login is risky and to record risk assessments for all login transactions in your tenant logs.

## Enable Adaptive MFA

You can enable Adaptive MFA in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or with the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

<Tabs>
  <Tab title="Dashboard">
    1. Go to [**Dashboard > Security > Multi-factor Auth**](https://manage.auth0.com/#/security/mfa).

    <Frame>
      <img alt="Auth0 Dashboard Security Multi-factor Auth Adaptive MFA Policy" />
    </Frame>

    2. In the **Factors** section, enable and configure at least one MFA Factor. To learn more, read [Multi-Factor Authentication Factors](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors).

    3. In the **Define policies** section, locate **Require Multi-factor Auth**, and then select **Use Adaptive MFA**. Risk assessment will automatically be enabled and recorded in your tenant logs.

    4. In the **Device Trust Duration** field, set the number of days a device remains trusted before the user needs to authenticate with MFA. The default timeframe is 30 days, but you may increase or decrease the number of challenges for your users.

       <Warning>
         Auth0 customers are responsible for any diminishment in security posture resulting from changing the device remembrance time period to a period longer than Okta's standard recommended setup.
       </Warning>

       * You can set the trusted device duration between 1 and 365 days.
       * If you modify the duration, the new duration value is applied to your users' device the next time they log in.

    5. Select **Save**.

    <Callout icon="file-lines">
      If you are using the [Identifier First Authentication](/docs/authenticate/login/auth0-universal-login/identifier-first) factor `email`, you must update email attributes in [Dashboard > Database Connections > Authentication Methods](https://manage.auth0.com/#/connections/database). On the Email Configuration tab, ensure the email attribute is active. Then, set **Allow Signup to Required** and enable **Require** email on user profile.

      <Frame>
        <img alt="Auth0 Dashboard > Authentication > Database Connections > Authentication Methods" />
      </Frame>
    </Callout>
  </Tab>

  <Tab title="Management API">
    1. Get a [Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production) with the `update:mfa_policies` scope.

    2. Call the Management API [Set the multi-factor authentication policies](https://auth0.com/docs/api/management/v2/guardian/put-policies) endpoint with the appropriate payload.

    3. If you want to change the **Device Trust Duration** from the default 30 days, call the [Update New Device Accessor](https://auth0.com/docs/api/management/v2/risk-assessments/patch-new-device). You need to add the following scopes to your Management API access token:
       * `read:attack_protection`
       * `update:attack_protection`
       <Warning>
         Auth0 customers are responsible for any diminishment in security posture resulting from changing the device remembrance time period to a period longer than Okta's standard recommended setup.
       </Warning>
  </Tab>
</Tabs>

## Enable Adaptive MFA Risk Assessment

If you aren't ready to enable Adaptive MFA, but want to start training it to analyze login behavior, you can enable Adaptive MFA Risk Assessment independently.

1. Go to [Dashboard > Security > Multi-factor Auth](https://manage.auth0.com/#/security/mfa).
2. Locate the **Define policies** section.
3. In **MFA Risk Assessors**, select **Enable Adaptive MFA Risk Assessment**.
4. Select **Save**.

## Customize Adaptive MFA

You can customize the behavior of Adaptive MFA to provide the best experience for your users while ensuring security. To learn more, read [Customize Adaptive MFA](/docs/secure/multi-factor-authentication/adaptive-mfa/customize-adaptive-mfa).

<Callout icon="file-lines">
  Actions that trigger MFA take precedence over default Adaptive MFA behavior.
</Callout>

## Limitations

Assessment information in tenant logs is only available for interactive flows. Auth0 does not support recording assessment information for <Tooltip href="/docs/glossary?term=Resource+Owner">Resource Owner</Tooltip> Password Grant (ROPG) flows without adaptive MFA enabled. For more information about authentication flow limitations, read [Adaptive MFA](/docs/secure/multi-factor-authentication/adaptive-mfa).

## Learn more

* [Customize Adaptive MFA](/docs/secure/multi-factor-authentication/adaptive-mfa/customize-adaptive-mfa)
* [Adaptive MFA Log Events](/docs/secure/multi-factor-authentication/adaptive-mfa/adaptive-mfa-log-events)
* [Multi-Factor Authentication Factors](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors)


# Auth0 Guardian
Source: https://auth0.com/docs/secure/multi-factor-authentication/auth0-guardian

Describes how Guardian works and how the Guardian SDK helps you build your own authenticator and Guardian-like applications.

Auth0 Guardian is a mobile application for iOS and Android devices that allows users to complete [multi-factor authentication (MFA)](/docs/secure/multi-factor-authentication) with push notifications or temporary one-time passwords.

Auth Guardian can deliver push notifications to users’ enrolled devices (typically mobile phones or tablets) or generate one-time passwords directly within the app. Users can then quickly respond to these push notifications or retrieve a one-time password to complete their login.

Users can download the Auth0 Guardian app from the [Apple App Store](https://apps.apple.com/us/app/auth0-guardian/id1093447833) or the [Google Play Store](https://play.google.com/store/apps/details?id=com.auth0.guardian). Alternatively, you can embed Auth0 Guardian capabilities in your own custom app using the Guardian SDK.

## Push Notifications

In order to use push notifications, users must have either the Auth0 Guardian app or a custom app built with the Guardian SDK installed on their device. When a user attempts to authenticate, push notifications are sent to the installed app. The user must respond to the notification to complete their login, proving they both know their login information and possess the device set up for <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip>.

Auth0 push notifications can be implemented using AWS Simple Notification Service (SNS) or one or more of the following direct-to-vendor services to configure vendor-specific integrations:

* Firebase Cloud Messaging (FCM)

  * To learn more about modifying push notification content, review [FCM's documentation](https://firebase.google.com/docs/cloud-messaging/concept-options).
* Apple Push Notification (APN)

  * To learn more about modifying push notification content, review [Apple's documentation](https://developer.apple.com/documentation/usernotifications/modifying-content-in-newly-delivered-notifications).

<Frame>
  <img alt="Auth0 Guardian flow diagram" />
</Frame>

### Enroll in push notifications

When you use Auth0 Guardian to configure push notifications, users are prompted to download the mobile app when they first sign up or log in to your application. If you use the Guardian SDK to implement push notifications in a custom app, users are not prompted to download any applications during enrollment.

You can enable push notifications from the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> under [Security > Multi-factor Auth > Push Notification using Auth0 Guardian](https://manage.auth0.com/#/security/mfa/guardian).

<Frame>
  <img alt="Auth0 Dashboard > Security > Multi-factor Auth > Push Notification using Auth0 Guardian" />
</Frame>

When a user first signs up or logs in to your application, [Universal Login](/docs/authenticate/login/auth0-universal-login) provides a QR code they can use to register the Auth0 Guardian app or custom Guardian SDK app as a secondary authentication factor. The user has a short amount of time to scan this code with the designated app to complete their enrollment.

After the user enrolls, they can use push notifications as an authentication factor. Whenever the user attempts to log in to your application, they will receive a push notification on their device via the Auth0 Guardian or custom Guardian SDK app. The user must approve this request to successfully log in to your application.

To learn how to reset MFA for users who have lost their devices or recovery codes, review [Reset Multi-Factor Authentication and Recovery Codes](/docs/secure/multi-factor-authentication/reset-user-mfa). For additional assistance, review [Troubleshooting Multi-Factor Authentication Issues](/docs/troubleshoot/authentication-issues/troubleshoot-mfa-issues).

## Temporary one-time passwords

The Auth0 Guardian app and the Guardian SDK also support the use of temporary one-time passwords (OTPs) as secondary authentication factors. Both the app and the SDK can generate temporary OTPs that users can use to complete <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> MFA challenges.

By default, the Auth0 Guardian app lists the user’s enrolled applications. After selecting an application, the corresponding OTP for that application displays. Each 6-digit OTP remains valid for 30 seconds. OTPs that are nearing expiration display in red. Upon expiration, the app immediately generates a new OTP. To avoid failed authentications, users should not use any red OTPs

In custom Guardian SDK apps, OTP appearance may vary.

### Use temporary one-time passwords

You can leverage OTPs in two primary ways:

* As a fallback option to push notifications in the event that the Auth0 Guardian app or other custom app does not receive a push request.
* As an MFA challenge, if you enable the [One-Time Password factor](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors) in your tenant.

<AccordionGroup>
  <Accordion title="Fallback method: Use OTPs as a fallback option to push notifications">
    If a user does not receive a push notification through the Auth0 Guardian or other custom app, they can use a temporary OTP to complete their MFA challenge instead.

    **Example user flow**:

    1. A user attempts to log in to your application. They reach the Universal Login MFA prompt but do not receive a push notification.
    2. On the MFA prompt, the user selects the **Manually Enter Code** button. The user must select this option to authenticate using OTPs.

       <Frame>
         <img alt="An example MFA prompt displaying the Manually Enter Code button" />
       </Frame>
    3. The user opens the Auth0 Guardian or custom Guardian SDK app and selects the application they are attempting to access.
    4. The user copies the OTP displayed at the bottom of the Account Detail page.
    5. The user enters the OTP in the MFA prompt to complete the challenge.
  </Accordion>

  <Accordion title="MFA challenge: Use OTPs as an MFA challenge">
    To allow users to authenticate with OTPs, you must enable **One-Time Password** as an [MFA factor](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors) for your tenant. Once enabled, users can complete MFA prompts using OTPs when logging in through Universal Login. To enable MFA factors, navigate to your [Auth0 Dashboard > Security > Multi-factor Auth](https://manage.auth0.com/#/security/mfa).

    Users can enroll in OTP as an MFA factor when first signing up or logging in to your application. Depending on the type of device used, [Universal Login](/docs/authenticate/login/auth0-universal-login) displays one of the following:

    * **For non-mobile devices**: Universal Login presents a QR code the user can scan to continue enrollment.

    <Frame>
      <img alt="An example OTP enrollment prompt displaying the Trouble Scanning? link" />
    </Frame>

    * **For mobile devices**: Universal Login skips the QR code and instead displays the enrollment code directly.

    <Frame>
      <img alt="The temporary one-time password enrollment screen as displayed on a mobile device. " />
    </Frame>

    Through either method, users can follow the steps on screen to register either the Auth0 Guardian app or a custom Guardian SDK app as their secondary authentication factor. Typically, this process involves having the user add your application to the appropriate app and retrieving the resulting OTP for that application. The user then enters the OTP into the Universal Login prompt to finish the enrollment process.

    The next time the user attempts to log in to your application after completing enrollment, they can authenticate by entering an OTP from their Auth0 Guardian or custom Guardian SDK app into the challenge.
  </Accordion>
</AccordionGroup>

## Auth0 Guardian app settings

### User security settings

In the Auth0 Guardian app, users can enable passcodes and biometrics as layers of app security on iOS and Android. If a user enables one or more of these options, they must complete these challenges before they can respond to push notifications or retrieve one-time passwords.

To enable these options on iOS or Android devices, users can follow the steps below.

<Tabs>
  <Tab title="iOS">
    To enable security settings for the Auth0 Guardian app on iOS:

    1. In the app, select the **gear icon** to open the Settings menu.
    2. Select **Passcode** to enable passcode protection.
    3. Set and confirm a 6-digit passcode.

    The app is now protected by the passcode. The user must enter this passcode before they can respond to push notifications or retrieve OTPs.

    After enabling passcode protection, the user can configure device biometrics as an alternate security measure. To enable device biometrics:

    1. In the app, select the **gear icon** to open the Settings menu.
    2. Enable device biometrics by selecting one of the available options, such as **Face ID** or **Touch ID**.
  </Tab>

  <Tab title="Android">
    To enable security settings for the Auth0 Guardian app on Android:

    1. In the app, select the **three-dot menu** to open the Settings menu.
    2. Enable the switch for the **Always Ask for Passphrase** option.
    3. Enter the passphrase that was set while setting up the Auth0 Guardian app.

    The app is now protected by the Auth0 Guardian passphrase. The user must enter this passphrase before they can respond to push notifications or retrieve OTPs.

    After enabling passphrase protection, the user can configure device biometrics as an alternate security measure. To enable device biometrics:

    1. In the app, select the **three-dot menu** to open the Settings menu.
    2. Enable the switch for the **Use Biometrics to unlock** option.
  </Tab>
</Tabs>

### Localization options

The Auth0 Guardian app supports localization for multiple languages and dialects on iOS and Android.

In the Language section of the Settings menu, users can select their preferred language. By default, the app uses the same language as the device system.

<Callout icon="file-lines">
  The majority of push notification content displays to users in their preferred language. However, the titles of push notifications are not translated as language settings are not retrieved until after a title is populated.
</Callout>

The Auth0 Guardian app supports the following languages and dialects:

<table>
  <thead>
    <tr>
      <th><strong>Language</strong></th>
      <th><strong>Code</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Albanian</td>
      <td><code>sq</code></td>
    </tr>

    <tr>
      <td>Amharic</td>
      <td><code>am</code></td>
    </tr>

    <tr>
      <td>Arabic\*</td>
      <td><code>ar</code></td>
    </tr>

    <tr>
      <td>Arabic (Egypt)\*</td>
      <td><code>ar-EG</code></td>
    </tr>

    <tr>
      <td>Arabic (Saudi Arabia)\*</td>
      <td><code>ar-SA</code></td>
    </tr>

    <tr>
      <td>Armenia</td>
      <td><code>hy</code></td>
    </tr>

    <tr>
      <td>Azerbaijani</td>
      <td><code>az</code></td>
    </tr>

    <tr>
      <td>Basque</td>
      <td><code>eu-ES</code></td>
    </tr>

    <tr>
      <td>Bengali</td>
      <td><code>bn</code></td>
    </tr>

    <tr>
      <td>Bosnian</td>
      <td><code>bs</code></td>
    </tr>

    <tr>
      <td>Bulgarian</td>
      <td><code>bg</code></td>
    </tr>

    <tr>
      <td>Catalan</td>
      <td><code>ca-ES</code></td>
    </tr>

    <tr>
      <td>Chinese - Hong Kong</td>
      <td><code>zh-HK</code></td>
    </tr>

    <tr>
      <td>Chinese - Simplified</td>
      <td><code>zh-CN</code></td>
    </tr>

    <tr>
      <td>Chinese - Traditional</td>
      <td><code>zh-TW</code></td>
    </tr>

    <tr>
      <td>Croatian</td>
      <td><code>hr</code></td>
    </tr>

    <tr>
      <td>Czech</td>
      <td><code>cs</code></td>
    </tr>

    <tr>
      <td>Danish</td>
      <td><code>da</code></td>
    </tr>

    <tr>
      <td>Dutch</td>
      <td><code>nl</code></td>
    </tr>

    <tr>
      <td>English</td>
      <td><code>en</code></td>
    </tr>

    <tr>
      <td>English - Canada</td>
      <td><code>en-CA</code></td>
    </tr>

    <tr>
      <td>Estonian</td>
      <td><code>et</code></td>
    </tr>

    <tr>
      <td>Farsi (Persian)\*</td>
      <td><code>fa</code></td>
    </tr>

    <tr>
      <td>Finnish</td>
      <td><code>fi</code></td>
    </tr>

    <tr>
      <td>French</td>
      <td><code>fr-FR</code></td>
    </tr>

    <tr>
      <td>French - Canada</td>
      <td><code>fr-CA</code></td>
    </tr>

    <tr>
      <td>Galician</td>
      <td><code>gl-ES</code></td>
    </tr>

    <tr>
      <td>Georgian</td>
      <td><code>ka</code></td>
    </tr>

    <tr>
      <td>German</td>
      <td><code>de</code></td>
    </tr>

    <tr>
      <td>Greek</td>
      <td><code>el</code></td>
    </tr>

    <tr>
      <td>Gujrati</td>
      <td><code>gu</code></td>
    </tr>

    <tr>
      <td>Hebrew\*</td>
      <td><code>he</code></td>
    </tr>

    <tr>
      <td>Hindi</td>
      <td><code>hi</code></td>
    </tr>

    <tr>
      <td>Hungarian</td>
      <td><code>hu</code></td>
    </tr>

    <tr>
      <td>Icelandic</td>
      <td><code>is</code></td>
    </tr>

    <tr>
      <td>Indonesian</td>
      <td><code>id</code></td>
    </tr>

    <tr>
      <td>Italian</td>
      <td><code>it</code></td>
    </tr>

    <tr>
      <td>Japanese</td>
      <td><code>ja</code></td>
    </tr>

    <tr>
      <td>Kannada</td>
      <td><code>kn</code></td>
    </tr>

    <tr>
      <td>Korean</td>
      <td><code>ko</code></td>
    </tr>

    <tr>
      <td>Latvian</td>
      <td><code>lv</code></td>
    </tr>

    <tr>
      <td>Lithuanian</td>
      <td><code>lt</code></td>
    </tr>

    <tr>
      <td>Macedonian</td>
      <td><code>mk</code></td>
    </tr>

    <tr>
      <td>Malay</td>
      <td><code>ms</code></td>
    </tr>

    <tr>
      <td>Malayalam</td>
      <td><code>ml</code></td>
    </tr>

    <tr>
      <td>Marathi</td>
      <td><code>mr</code></td>
    </tr>

    <tr>
      <td>Mongolian</td>
      <td><code>mn</code></td>
    </tr>

    <tr>
      <td>Montenegrine</td>
      <td><code>cnr</code></td>
    </tr>

    <tr>
      <td>Myanmar</td>
      <td><code>my</code></td>
    </tr>

    <tr>
      <td>Norwegian</td>
      <td><code>no</code></td>
    </tr>

    <tr>
      <td>Norwegian - Bokmål</td>
      <td><code>nb</code></td>
    </tr>

    <tr>
      <td>Norwegian - Nynorsk</td>
      <td><code>nn</code></td>
    </tr>

    <tr>
      <td>Polish</td>
      <td><code>pl</code></td>
    </tr>

    <tr>
      <td>Portuguese - Brazil</td>
      <td><code>pt-BR</code></td>
    </tr>

    <tr>
      <td>Portuguese - Portugal</td>
      <td><code>pt-PT</code></td>
    </tr>

    <tr>
      <td>Punjabi</td>
      <td><code>pa</code></td>
    </tr>

    <tr>
      <td>Romanian</td>
      <td><code>ro</code></td>
    </tr>

    <tr>
      <td>Russian</td>
      <td><code>ru</code></td>
    </tr>

    <tr>
      <td>Serbian</td>
      <td><code>sr</code></td>
    </tr>

    <tr>
      <td>Slovak</td>
      <td><code>sk</code></td>
    </tr>

    <tr>
      <td>Slovenian</td>
      <td><code>sl</code></td>
    </tr>

    <tr>
      <td>Somali</td>
      <td><code>so</code></td>
    </tr>

    <tr>
      <td>Spanish</td>
      <td><code>es</code></td>
    </tr>

    <tr>
      <td>Spanish - Argentina</td>
      <td><code>es-AR</code></td>
    </tr>

    <tr>
      <td>Spanish - Latin America</td>
      <td><code>es-419</code></td>
    </tr>

    <tr>
      <td>Spanish - Mexico</td>
      <td><code>es-MX</code></td>
    </tr>

    <tr>
      <td>Swahili</td>
      <td><code>sw</code></td>
    </tr>

    <tr>
      <td>Swedish</td>
      <td><code>sv</code></td>
    </tr>

    <tr>
      <td>Tagalog</td>
      <td><code>tl</code></td>
    </tr>

    <tr>
      <td>Tamazight</td>
      <td><code>zgh</code></td>
    </tr>

    <tr>
      <td>Tamil</td>
      <td><code>ta</code></td>
    </tr>

    <tr>
      <td>Telugu</td>
      <td><code>te</code></td>
    </tr>

    <tr>
      <td>Thai</td>
      <td><code>th</code></td>
    </tr>

    <tr>
      <td>Turkish</td>
      <td><code>tr</code></td>
    </tr>

    <tr>
      <td>Ukrainian</td>
      <td><code>uk</code></td>
    </tr>

    <tr>
      <td>Urdu\*</td>
      <td><code>ur</code></td>
    </tr>

    <tr>
      <td>Vietnamese</td>
      <td><code>vi</code></td>
    </tr>

    <tr>
      <td>Welsh</td>
      <td><code>cy</code></td>
    </tr>
  </tbody>
</table>

### Guardian app themes

The Auth0 Guardian app for both iOS and Android supports light and dark mode themes.

In the Theme section of the Settings menu, users can select the following options:

* **System**: Uses default system theme
* **Light**: Enables the light mode theme
* **Dark**: Enables the dark mode theme

### Customization options for protected applications

To make it easier for users to distinguish between their protected applications in the Auth0 Guardian app, each application can be customized with a distinct name, accent color, and icon.

<Callout icon="file-lines">
  The default name assigned to your application in the Auth0 Guardian app is determined by your [tenant name](/docs/get-started/tenant-settings/find-your-tenant-name-or-tenant-id) or the Friendly Name set in your [tenant settings](/docs/get-started/tenant-settings). Similarly, the default logo stems from the Logo URL provided in your tenant settings.

  To edit your tenant settings, navigate to [Auth0 Dashboard > Settings > General](https://manage.auth0.com/dashboard/#/tenant/general).
</Callout>

To customize a protected application:

1. Select an application from the list.

   * **Tip**: You can also swipe left on the application to reveal Edit and Delete options.
2. On the Account Detail page, choose **Edit**.
3. Update the application’s name, color, and icon as needed.
4. Select **Save**.

## Guardian SDKs

You can [install the Guardian SDK](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/install-guardian-sdk) (available for [iOS](/docs/secure/multi-factor-authentication/auth0-guardian/guardian-for-ios-sdk) and [Android](/docs/secure/multi-factor-authentication/auth0-guardian/guardian-for-android-sdk)) to build your own multi-factor authentication application with complete control over the branding and look-and-feel. With the Guardian SDK, you can build your own custom mobile applications that work like Guardian or integrate some Guardian functionalities, such as receiving push notifications in your existing mobile applications. A typical scenario could be for a banking app. You can use the Guardian SDK in your existing mobile app to receive and confirm push notifications when someone performs an ATM transaction.

## Use Actions to enable Multi-Factor with Auth0 Guardian

To enable Auth0 Guardian within an Action, pass `guardian` as the `provider` parameter when you enable multi-factor authentication:

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  api.multifactor.enable('guardian', { allowRememberBrowser: false });
};
```

To force your users to log in with Auth0 Guardian every time, create the Action with `allowRememberBrowser: false`.

## Multi-Factor with Auth0 Guardian and Authorization Extension

This template provides an example and starting point to trigger multi-factor authentication with Auth0 Guardian for push notifications when a condition is met.

Upon first login, the user can enroll the device. See Enable Multi-Factor Authentication for more information about M

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
const groups = event.user.app_metadata.authorization.groups;
const GROUPS_WITH_MFA = {
// Add groups that need MFA here
// Example
admins: true
};

const needsMFA = !!groups.find(function (group) {
return GROUPS_WITH_MFA[group];
});

if (needsMFA) {
// optional, defaults to true. Set to false to force Guardian authentication every time.
// See https://auth0.com/docs/secure/multi-factor-authentication/customize-mfa#change-frequency-of-mfa-prompts for details
api.multifactor.enable('guardian', { allowRememberBrowser: false });
}

};
```

## Learn more

* [Install Guardian SDK](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/install-guardian-sdk)
* [Guardian.swift iOS SDK](/docs/secure/multi-factor-authentication/auth0-guardian/guardian-for-ios-sdk)
* [Guardian for Android SDK](/docs/secure/multi-factor-authentication/auth0-guardian/guardian-for-android-sdk)
* [Configure Push Notifications for MFA](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-push-notifications-for-mfa)
* [Reset User Multi-Factor Authentication and Recovery Codes](/docs/secure/multi-factor-authentication/reset-user-mfa)
* [Guardian Error Code Reference](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/guardian-error-code-reference)


# Guardian for Android SDK
Source: https://auth0.com/docs/secure/multi-factor-authentication/auth0-guardian/guardian-for-android-sdk

Describes how to install, configure, and use options for the Auth0 Guardian for Android SDK.

The [Guardian for Android SDK](https://github.com/auth0/Guardian.Android) helps you create Android apps with Guardian functionality, providing secure access to <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA) with push notifications. With this toolkit, you can build your own customized version of the Guardian application that matches the look and feel of your organization. To learn more, read [Configure Push Notifications for MFA](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-push-notifications-for-mfa#configure-push-notifications-for-apple-using-apn-).

Android API level 15+ is required in order to use the Guardian for Android SDK.

## Install Guardian Android SDK

Guardian is available both in [Maven Central](http://search.maven.org/) and [JCenter](https://bintray.com/auth0/android/guardian).

1. To use Guardian, add these lines to your `build.gradle` dependencies file:
   `implementation 'com.auth0.android:guardian:0.4.0'`
   You can check for the latest version on the repository [Releases](https://github.com/auth0/GuardianSDK.Android/releases) tab, in [Maven](http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22com.auth0.android%22%20AND%20a%3A%22guardian%22), or in [JCenter](https://bintray.com/auth0/android/guardian).
2. After adding your Gradle dependency, make sure to sync your project with Gradle file.

### Enable Guardian push notifications

1. Go to [Dashboard > Security > Multifactor Auth > Push via Auth0 Guardian.](https://manage.auth0.com/#/security/mfa/guardian)
2. Toggle the switch at the top to enable it.

<Frame>
  <img alt="Auth0 Dashboard > Security > Multi-factor Auth > Guardian > Custom > Amazon SNS" />
</Frame>

3. [Configure push notifications](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-push-notifications-for-mfa#configure-push-notifications-for-android-using-fcm).

## Use SDK

Guardian is the core of the SDK. You'll need to create an instance of this class for your specific tenant URL.

```java lines theme={null}
Uri url = Uri.parse("https://<tenant>.<region>.auth0.com");

Guardian guardian = new Guardian.Builder()
    .url(url)
    .build();
```

or

```java lines theme={null}
String domain = "<tenant>.<region>.auth0.com";

Guardian guardian = new Guardian.Builder()
    .domain(domain)
    .build();
```

### Enroll

The link between the second factor (an instance of your app on a device) and an Auth0 account is referred to as an **enrollment**.

You can create an enrollment using the `Guardian.enroll` function, but first, you'll have to create a new pair of RSA keys for it. The private key will be used to sign the requests to allow or reject a login. The public key will be sent during the enrollment process so the server can later verify the request's signature.

```java lines theme={null}
KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("RSA");
keyPairGenerator.initialize(2048); // you MUST use at least 2048 bit keys
KeyPair keyPair = keyPairGenerator.generateKeyPair();
```

Next, obtain the enrollment information by scanning the Guardian QR code, and use it to enroll the account:

```java lines theme={null}
Uri enrollmentUriFromQr = ...; // the URI obtained from a Guardian QR code

CurrentDevice device = new CurrentDevice(context, "fcmToken", "deviceName");

Enrollment enrollment = guardian
    .enroll(enrollmentUriFromQr, device, keyPair)
    .execute();
```

Alternatively, you can execute the request in a background thread:

```java lines theme={null}
guardian
    .enroll(enrollmentUriFromQr, device, keyPair)
    .start(new Callback<Enrollment> {
        @Override
        void onSuccess(Enrollment enrollment) {
            // we have the enrollment data
        }

        @Override
        void onFailure(Throwable exception) {
            // something failed
        }
    });
```

You must provide the following data:

<table>
  <thead>
    <tr>
      <th>Variable</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>deviceName</code></td>
      <td>Name for the enrollment displayed to the user when the second factor is required.</td>
    </tr>

    <tr>
      <td><code>fcmToken</code></td>
      <td>Token for Firebase Cloud Messaging (FCM) push notification service. See <a href="https://firebase.google.com/docs/cloud-messaging/android/client#sample-register" title="sample register">Sample Register</a> for details.</td>
    </tr>
  </tbody>
</table>

### Unenroll

To disable MFA, you can delete the enrollment:

```java lines theme={null}
guardian
    .delete(enrollment)
    .execute(); // or start(new Callback<> ...)
```

### Allow login requests

Once you have the enrollment in place, you'll receive a FCM push notification every time the user needs multi-factor authentication.

Guardian provides a method to parse the `Map<String, String>` data inside the [RemoteMessage](https://firebase.google.com/docs/reference/android/com/google/firebase/messaging/RemoteMessage) received from FCM and return a `Notification` instance ready to be used.

```javascript lines theme={null}
// at the FCM listener you receive a RemoteMessage
@Override
public void onMessageReceived(RemoteMessage message) {
    Notification notification = Guardian.parseNotification(message.getData());
    if (notification != null) {
        // you received a Guardian notification, handle it
        handleGuardianNotification(notification);
        return;
    }

    /* handle other push notifications you might be using ... */
}
```

Once you have the notification instance, you can use the `allow` method to approve the authentication request. You'll also need the enrollment that you obtained previously. If there are multiple enrollments, be sure to use the one that has the same `id` as the notification (the `enrollmentId` property).

```java lines theme={null}
guardian
    .allow(notification, enrollment)
    .execute(); // or start(new Callback<> ...)
```

### Reject login requests

To deny an authentication request, use `reject` instead. You can also add an optional reason for the rejection, which will be available in the guardian logs.

```java lines theme={null}
guardian
    .reject(notification, enrollment) // or reject(notification, enrollment, reason)
    .execute(); // or start(new Callback<> ...)
```

### Set up mobile-only OTP enrollment

You can enable one-time passwords (OTP) as an MFA factor using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. This option does not require a QR code and allows users to enroll manually.

To invite a user to enroll, navigate to the [Auth0 Dashboard > User Management > Users](https://manage.auth0.com/#/users) and select a user. Then, access their Details tab and use the Multi-Factor Authentication section to send an enrollment invitation.

#### Connect a resource

You can connect a resource using the Auth0 Dashboard or the Guardian SDK.

##### Use Auth0 Dashboard

1. Access the Auth0 login prompt and copy the provided code or a similar base32 encoded key obtained from another source.

   <Frame>
     <img alt="An example login prompt displaying a one-time code" />
   </Frame>
2. After obtaining your code, add it to the Guardian SDK:

**Java**

`public String copiedCode = "{copiedCode}";`

**Kotlin**

`val copiedCode: String = "{copiedCode}"`

##### Use Guardian SDK

First, add the `LoginCodeGenerator` class to your project. Then, use `getCode (String copiedCode) to` generate a one-time code in your app.

**Java**

```java lines expandable theme={null}
public class LoginCodeGenerator {

   private static final int TOTP_LENGTH = 6;

   private static final int TOTP_DURATION = 30;

   private static final String TOTP_ALGORITHM = "SHA1";

   public String getCode(String copedCode) {

       byte[] key = new byte[0];

       try {

           key = Base32.decode(copedCode);

       } catch (Base32.DecodingException ex) {

//            handle exception

       }

       TOTP totp = new TOTP(TOTP_ALGORITHM, key, TOTP_LENGTH, TOTP_DURATION);

       return totp.generate();

   }

}
```

**Kotlin**

```kotlin lines expandable theme={null}
class LoginCodeGenerator {

   fun getCode(copiedCode: String): String {

       var key: ByteArray? = ByteArray(0)

       try {

           key = Base32.decode(copiedCode)

       } catch (ex: Base32.DecodingException) {

//            handle exception

       }

       val totp = TOTP(TOTP_ALGORITHM, key, TOTP_LENGTH, TOTP_DURATION)

       return totp.generate()

   }

   companion object {

       private const val TOTP_LENGTH = 6

       private const val TOTP_DURATION = 30

       private const val TOTP_ALGORITHM = "SHA1"

   }

}
```

#### Enter one-time code

Enter the generated one-time password from `getCode()` into the Auth0 login prompt.

<Frame>
  <img alt="An example login prompt displaying a one-time code" />
</Frame>

After selecting Continue, a message displays stating your application has been added as an authentication factor for your user.

#### Log in with your app

After the factor has been enrolled, your user can log in using your app. First, choose the Guardian app as your authentication method.

<Frame>
  <img alt="The authentication method selection screen" />
</Frame>

To generate the one-time code, call `getCode(copedCode: String)` using the code you copied from the Auth0 login prompt.

Then, enter the one-time code into the login prompt to verify your identity.

<Frame>
  <img alt="The Verify Your Identity screen prompting the user for a one-time code" />
</Frame>

## Learn more

* [Configure Push Notifications for MFA](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-push-notifications-for-mfa)


# Guardian.swift iOS SDK
Source: https://auth0.com/docs/secure/multi-factor-authentication/auth0-guardian/guardian-for-ios-sdk

Describes how to install, use and configure options for the Guardian.swift iOS SDK.

[Guardian.swift](https://github.com/auth0/Guardian.swift) allows you to integrate Auth0's Guardian multi-factor service in your own iOS app, transforming it into the second factor itself. Your users will get all the benefits of our frictionless <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> from your app. To learn more, read [Getting Started with Apple Push Notification Service](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-push-notifications-for-mfa#configure-push-notifications-for-apple-using-apn-).

## Requirements

* iOS 10+ and Swift 4.1 is required in order to use Guardian.
* To use this SDK you have to configure your tenant's Guardian service with your own push notification credentials, otherwise, you would not receive any push notifications. To learn more, read [Configure Push Notifications for MFA](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-push-notifications-for-mfa).

## Install Guardian iOS SDK

### CocoaPods

Guardian.swift is available through [CocoaPods](http://cocoapods.org). To install it, add the following line to your Podfile:

```bash lines theme={null}
pod 'Guardian', '~> 1.1.0'
```

### Carthage

Add this line to your Cartfile:

```bash lines theme={null}
github "auth0/Guardian.swift" ~> 1.1.0
```

## Enable Guardian push notifications

1. Go to [Dashboard > Security > Multi-factor Auth](https://manage.auth0.com/#/guardian).
2. Toggle **Push Notification** on to enable it.
3. [Configure push notifications](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-push-notifications-for-mfa#configure-push-notifications-for-apple-using-apn-).

## Usage

`Guardian` is the core of the SDK. To use the SDK, import the library:

```swift lines theme={null}
import Guardian
```

Set the domain for your tenant. Or, use the <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip> if you configured one for your tenant:

```swift lines theme={null}
let domain = "<tenant>.<region>.auth0.com"
```

### Enroll

An enrollment is a link between the second factor and an Auth0 account. When an account is enrolled you'll need it to provide the second factor required to verify the identity. If your app is not yet using push notifications or you're not familiar with it, see [Apple Push Notification Service Overview](https://developer.apple.com/go/?id=push-notifications) for details.

For an enrollment you need the following information, besides your tenant domain:

<table>
  <thead>
    <tr>
      <th>Variable</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Enrollment URI</strong></td>
      <td>Value encoded in the QR code scanned from Guardian Web Widget or your enrollment ticket sent to you in email or SMS.</td>
    </tr>

    <tr>
      <td><strong>APNS Token</strong></td>
      <td>Apple APNS token for the device. It must be a string containing the 64 bytes (in hexidecimal format).</td>
    </tr>

    <tr>
      <td><strong>Key Pair</strong></td>
      <td>An RSA (private/public) key pair used to assert your identity with Auth0 Guardian.</td>
    </tr>
  </tbody>
</table>

After you have the information, you can enroll your device:

```swift lines theme={null}
Guardian
        .enroll(forDomain: "{yourTenantDomain}",
                usingUri: "{enrollmentUri}",
                notificationToken: "{apnsToken}",
                signingKey: signingKey,
                verificationKey: verificationKey
                )
        .start { result in
            switch result {
            case .success(let enrolledDevice):
                // success, we have the enrollment device data available
            case .failure(let cause):
                // something failed, check cause to see what went wrong
            }
        }
```

On success you'll obtain the enrollment information, that should be secured stored in your application. This information includes the enrollment identifier, and the token for Guardian API associated to your device for updating or deleting your enrollment.

#### Signing and verification keys

Guardian.swift provides a convenience class to generate a signing key:

```swift lines theme={null}
let signingKey = try DataRSAPrivateKey.new()
```

This key only exists in memory but you can obtain its `Data` representation and store securely in, for example, an encrypted SQLiteDB:

```javascript lines theme={null}
// Store data
let data = signingKey.data
// perform the storage

// Load from Storage
let loadedKey = try DataRSAPrivateKey(data: data)
```

But if you just want to store inside iOS Keychain:

```swift wrap lines theme={null}
let signingKey = try KeychainRSAPrivateKey.new(with: "com.myapp.mytag")
```

The above example creates a key and stores it automatically under the supplied tag. If you want to retrieve it, you can use the tag:

```swift wrap lines theme={null}
let signingKey = try KeychainRSAPrivateKey(tag: "com.myapp.mytag")
```

For the verification key, we can just obtain it from any `SigningKey`, for example:

```swift lines theme={null}
let verificationKey = try signingKey.verificationKey()
```

### Allow login requests

Once you have the enrollment in place, you will receive a push notification every time the user has to validate their identity with MFA. Guardian provides a method to parse the data received from APNs and return a `Notification` instance ready to be used.

```swift lines theme={null}
if let notification = Guardian.notification(from: notificationPayload) {
    // we have received a Guardian push notification
}
```

Once you have the notification instance, you can easily allow the authentication request by using the `allow` method. You'll also need some information from the enrolled device that you obtained previously. In case you have more than one enrollment, you'll have to find the one that has the same `id` as the notification (the `enrollmentId` property).

When you have the information, `device` parameter is anything that implements the protocol `AuthenticatedDevice`:

```swift lines theme={null}
struct Authenticator: Guardian.AuthenticationDevice {
    let signingKey: SigningKey
    let localIdentifier: String
}
```

Local identifier is the local id of the device, by default on enroll `UIDevice.current.identifierForVendor`. Then just call:

```swift lines theme={null}
Guardian
        .authentication(forDomain: "{yourTenantDomain}", device: device)
        .allow(notification: notification)
        .start { result in
            switch result {
            case .success:
                // the auth request was successfuly allowed
            case .failure(let cause):
                // something failed, check cause to see what went wrong
            }
        }
```

### Reject login requests

To deny an authentication request call `reject` instead. You can also send an optional reject reason. The reject reason will appear in the Guardian logs.

```swift lines theme={null}
Guardian
        .authentication(forDomain: "{yourTenantDomain}", device: device)
        .reject(notification: notification)
        // or reject(notification: notification, withReason: "hacked")
        .start { result in
            switch result {
            case .success:
                // the auth request was successfuly rejected
            case .failure(let cause):
                // something failed, check cause to see what went wrong
            }
        }
```

### Unenroll

If you want to delete an enrollment, for example, if you want to disable MFA, you can make the following request:

```swift lines theme={null}
Guardian
        .api(forDomain: "{yourTenantDomain}")
        .device(forEnrollmentId: "{userEnrollmentId}", token: "{enrollmentDeviceToken}")
        .delete()
        .start { result in
            switch result {
            case .success:
                // success, the enrollment was deleted
            case .failure(let cause):
                // something failed, check cause to see what went wrong
            }
        }
```

### Set up mobile-only OTP enrollment

You can enable one-time passwords (OTP) as an MFA factor using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. This option does not require a QR code and allows users to enroll manually.

To invite a user to enroll, navigate to the [Auth0 Dashboard > User Management > Users](https://manage.auth0.com/#/users) and select a user. Then, access their Details tab and use the Multi-Factor Authentication section to send an enrollment invitation.

#### Connect a resource

You can connect a resource using the Auth0 Dashboard or the Guardian SDK.

##### Use Auth0 Dashboard

1. Access the Auth0 login prompt and copy the provided code or a similar base32 encoded key obtained from another source. In the next step, you will enter this code into an authentication application.

   <Frame>
     <img alt="An example login prompt displaying a one-time code" />
   </Frame>
2. Add the code you copied to an authentication application, such as Guardian.

##### Use the SDK

1. Import the Guardian library.

   ```swift lines theme={null}
   import Guardian
   ```

2. Create a code generator.

   ```swift lines theme={null}
   let codeGenerator = try Guardian.totp(

      base32Secret: enrollmentCode,  // Enrollment code entered by user

      algorithm: .sha1			// Algorithm used by TOTP

   )
   ```

3. Retrieve generated code.

   ```swift lines theme={null}
   codeGenerator.code()
   ```

#### Enter one-time code

On the Auth0 login prompt, enter the code you generated in the previous step.

<Frame>
  <img alt="An example login prompt displaying a one-time code" />
</Frame>

After selecting Continue, a message displays stating your application has been added as an authentication factor for your user.

#### Log in with your app

After the factor has been enrolled, your user can log in using your app. First, choose the Guardian app as your authentication method.

<Frame>
  <img alt="The authentication method selection screen" />
</Frame>

Then, enter the one-time code into the login prompt to verify your identity.

<Frame>
  <img alt="The Verify Your Identity screen prompting the user for a one-time code" />
</Frame>


# Authenticate Using the Resource Owner Password Flow with MFA
Source: https://auth0.com/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa

Learn how to authenticate users using the Resource Owner Password Flow with MFA.

You can use the [Auth0 MFA API](https://auth0.com/docs/api/authentication#multi-factor-authentication) to complete the authentication flow using the [Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow) (sometimes called <Tooltip href="/docs/glossary?term=Resource+Owner">Resource Owner</Tooltip> Password Grant or ROPG) when <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> is enabled.

## Prerequisites

Before you can use the MFA APIs, you'll need to enable the MFA grant type for your application. Go to [Auth0 Dashboard > Applications > Advanced Settings > Grant Types](https://manage.auth0.com/#/applications) and select **MFA**.

## Authenticate user

When you use the Resource Owner Password Flow to authenticate, you call the `/oauth/token` endpoint with the user's username and password.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=password \
    --data username=user@example.com \
    --data password=pwd \
    --data 'client_id={yourClientId}' \
    --data 'client_secret={yourClientSecret}' \
    --data audience=https://someapi.com/api \
    --data 'scope=openid profile read:sample'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=password&username=user%40example.com&password=pwd&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&audience=https%3A%2F%2Fsomeapi.com%2Fapi&scope=openid%20profile%20read%3Asample", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=password&username=user%40example.com&password=pwd&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&audience=https%3A%2F%2Fsomeapi.com%2Fapi&scope=openid%20profile%20read%3Asample")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=password&username=user%40example.com&password=pwd&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&audience=https%3A%2F%2Fsomeapi.com%2Fapi&scope=openid%20profile%20read%3Asample")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'password',
      username: 'user@example.com',
      password: 'pwd',
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      audience: 'https://someapi.com/api',
      scope: 'openid profile read:sample'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=password" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&username=user@example.com" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&password=pwd" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_secret={yourClientSecret}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&audience=https://someapi.com/api" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&scope=openid profile read:sample" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=password&username=user%40example.com&password=pwd&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&audience=https%3A%2F%2Fsomeapi.com%2Fapi&scope=openid%20profile%20read%3Asample",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=password&username=user%40example.com&password=pwd&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&audience=https%3A%2F%2Fsomeapi.com%2Fapi&scope=openid%20profile%20read%3Asample"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=password&username=user%40example.com&password=pwd&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&audience=https%3A%2F%2Fsomeapi.com%2Fapi&scope=openid%20profile%20read%3Asample"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/x-www-form-urlencoded"]

  let postData = NSMutableData(data: "grant_type=password".data(using: String.Encoding.utf8)!)
  postData.append("&username=user@example.com".data(using: String.Encoding.utf8)!)
  postData.append("&password=pwd".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&client_secret={yourClientSecret}".data(using: String.Encoding.utf8)!)
  postData.append("&audience=https://someapi.com/api".data(using: String.Encoding.utf8)!)
  postData.append("&scope=openid profile read:sample".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

When MFA is enabled, the response includes an `mfa_required` error and a `mfa_token`.

<Callout icon="file-lines">
  The default expiry time of access tokens with the `https://{yourDomain}/mfa/*` audience is 10 minutes. This value cannot be configured.
</Callout>

```json lines theme={null}
{
    "error": "mfa_required",
    "error_description": "Multifactor authentication required",
    "mfa_token": "Fe26...Ha"
}
```

## Retrieve enrolled authenticators

After getting the error above, you need to find out if the user has an MFA factor enrolled or not. Call the [MFA Authenticators endpoint](/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis/manage-authenticator-factors-mfa-api), using the MFA token obtained in the previous section.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/mfa/authenticators' \
    --header 'authorization: Bearer MFA_TOKEN' \
    --header 'content-type: application/json'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/mfa/authenticators");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer MFA_TOKEN");
  request.AddHeader("content-type", "application/json");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/mfa/authenticators"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer MFA_TOKEN")
  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/mfa/authenticators")
    .header("authorization", "Bearer MFA_TOKEN")
    .header("content-type", "application/json")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/mfa/authenticators',
    headers: {authorization: 'Bearer MFA_TOKEN', 'content-type': 'application/json'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MFA_TOKEN",
                             @"content-type": @"application/json" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/mfa/authenticators"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/mfa/authenticators",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MFA_TOKEN",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = {
      'authorization': "Bearer MFA_TOKEN",
      'content-type': "application/json"
      }

  conn.request("GET", "/{yourDomain}/mfa/authenticators", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/mfa/authenticators")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer MFA_TOKEN'
  request["content-type"] = 'application/json'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer MFA_TOKEN",
    "content-type": "application/json"
  ]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/mfa/authenticators")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

You will get an array with the available authenticators. The array will be empty if the user did not enroll a factor.

```json lines theme={null}
[
    {
        "id": "recovery-code|dev_O4KYL4FtcLAVRsCl",
        "authenticator_type": "recovery-code",
        "active": true
    },
    {
        "id": "email|dev_NU1Ofuw3Cw0XCt5x",
        "authenticator_type": "oob",
        "active": true,
        "oob_channel": "email",
        "name": "email@address.com"
    }
]
```

## Enroll MFA factor

If the user is not enrolled in MFA, use the MFA token obtained earlier and enroll it using the MFA Associate endpoint. See the following links to implement this flow based on the authentication factor:

* [SMS or voice](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-challenge-sms-voice-authenticators)
* [One-time password (OTP)](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-otp-authenticators)
* [Push](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-push-authenticators)
* [Email](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-email-authenticators)

## Challenge user with MFA

If the user is already enrolled in MFA, you need to challenge the user with one of the existing factors. Use the `authenticator_id` return by the MFA Authenticators endpoint when calling the MFA Challenge endpoint.

After the challenge is complete, call `/oauth/token` endpoint again to finalize the authentication flow and get the authentication tokens.

See the links below to implement this flow depending on the authentication factor:

* [SMS or voice](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-challenge-sms-voice-authenticators)
* [One-time password (OTP)](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-otp-authenticators)
* [Push](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-push-authenticators)
* [Email](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-email-authenticators)

### MFA OTP code limitations and restrictions

**Expiry time**: The expiry time of MFA OTP codes is 5 minutes. This value is not configurable.

**Code validation**: After a user validates an MFA OTP code, it cannot be used again.

**Code validation rate limiting**: Unsuccessful user validation attempts are rate limited using a bucket algorithm. The bucket starts with 10 attempts and refreshes at a rate of 1 attempt per 6 minutes.

## Customize MFA

<Warning>
  Customizable MFA with the Resource Owner Password Grant, Embedded, or Refresh Token flows is in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0’s release stages, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To participate in the early access, contact [Auth0 Support](https://support.auth0.com/).
</Warning>

Customize your MFA flows with the MFA API. With the MFA API, you can allow your users to enroll and challenge with a specific choice of factors your application supports.

When MFA is enabled with the Resource Owner Password Flow to authenticate, call to the `/oauth/token endpoint` to request an access token. The authorization server returns an `mfa_required` error which provides:

* The `mfa_token` you need to call the MFA API for enrollment and challenges.
* The `mfa_requirements` parameter, which provides the type of factor your application supports for challenges.

```json theme={null}
{
  "error": "mfa_required",
  "error_description": "Multifactor authentication required",
  "mfa_token": "Fe26...Ha",
  "mfa_requirements": {
    "challenge": [
      { "type": "otp" },
      { "type": "push-notification" },
      { "type": "phone" },
      { "type": "recovery-code" }
    ]
  }
}
```

Use the `mfa_token` to call the [`mfa/authenticator endpoint`](/docs/api/authentication/muti-factor-authentication/list-authenticators) to list all factors the user has enrolled and match the same type your application supports.  You also need to obtain the matching `authenticator_type` to issue challenges:

```json theme={null}
[
  {
    "type": "recovery-code",
    "id": "recovery-code|dev_qpOkGUOxBpw6R16t",
    "authenticator_type": "recovery-code",
    "active": true
  },
  {
    "type": "otp",
    "id": "totp|dev_6NWz8awwC8brh2dN",
    "authenticator_type": "otp",
    "active": true
  }
]
```

Enforce the MFA challenge by calling the [`request/mfa/challenge`](/docs/api/authentication/muti-factor-authentication/request-mfa-challenge) endpoint.

Further customize your MFA flow with Auth0 Actions. To learn more, read [Actions Triggers: post-challenge - API Object](/docs/customize/actions/explore-triggers/password-reset-triggers/post-challenge-trigger/post-challenge-api-object).

## Learn more

* [Enroll and Challenge SMS and Voice Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-challenge-sms-voice-authenticators)
* [Enroll and Challenge OTP Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-otp-authenticators)
* [Enroll and Challenge Push Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-push-authenticators)
* [Enroll and Challenge Email Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-email-authenticators)
* [Manage Authentication Factors with Authentication API](/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis/manage-authenticator-factors-mfa-api)
* [Multi-Factor Authentication Factors](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors)


# Challenge with Recovery Codes
Source: https://auth0.com/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/challenge-with-recovery-codes

Describes how to use the MFA API to challenge users who lose access to their device or account using recovery codes.

When [recovery codes are enabled](/docs/secure/multi-factor-authentication/configure-recovery-codes-for-mfa) for your tenant, Auth0 automatically generates them when a user enrolls with <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA). The user should save the recovery code. This code can later be used if the user loses access to the device or account used for MFA.

When recovery codes are disabled the MFA API will not return a recovery code when you associate a user's first MFA factor and users cannot authenticate with a recovery code.

You can enable users to authenticate with a recovery code using the MFA API.

1. Prompt the user for their recovery code. That value should be entered in the application for the user to authenticate.

   <Callout icon="file-lines">
     Auth0 does not generate recovery codes for DUO and for the legacy `google-authenticator` factor.
   </Callout>
2. Authenticate with recovery code. Call the OAuth Token endpoint with the recovery code to authenticate and generate a new recovery code. You need to specify the following parameters:

   <table>
     <thead>
       <tr>
         <th>Parameter</th>
         <th>Value</th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td><code>grant\_type</code></td>
         <td><code>[http://auth0.com/oauth/grant-type/mfa-recovery-code](http://auth0.com/oauth/grant-type/mfa-recovery-code)</code></td>
       </tr>

       <tr>
         <td><code>recovery\_code</code></td>
         <td>The recovery code provided by the user.</td>
       </tr>
     </tbody>
   </table>

<AuthCodeGroup>
  ```bash cURL theme={null}
     curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=http://auth0.com/oauth/grant-type/mfa-recovery-code \
  --data 'client_id={yourClientId}' \
  --data 'client_secret={yourClientSecret}' \
  --data 'mfa_token={mfaToken}' \
  --data 'recovery_code={recoveryCode}'

  ```

  ```csharp C# theme={null}
     var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-recovery-code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&recovery_code=%7BrecoveryCode%7D", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);

  ```

  ```go Go theme={null}
     package main

  import (
     "fmt"
     "strings"
     "net/http"
     "io/ioutil"
  )

  func main() {

     url := "https://{yourDomain}/oauth/token"

     payload := strings.NewReader("grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-recovery-code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&recovery_code=%7BrecoveryCode%7D")

     req, _ := http.NewRequest("POST", url, payload)

     req.Header.Add("content-type", "application/x-www-form-urlencoded")

     res, _ := http.DefaultClient.Do(req)

     defer res.Body.Close()
     body, _ := ioutil.ReadAll(res.Body)

     fmt.Println(res)
     fmt.Println(string(body))

  }

  ```

  ```java Java theme={null}
     HttpResponse<String> response = Unirest.post("https://{yourDomain}/oauth/token")
  .header("content-type", "application/x-www-form-urlencoded")
  .body("grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-recovery-code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&recovery_code=%7BrecoveryCode%7D")
  .asString();

  ```

  ```javascript Node.JS theme={null}
     var axios = require("axios").default;

  var options = {
  method: 'POST',
  url: 'https://{yourDomain}/oauth/token',
  headers: {'content-type': 'application/x-www-form-urlencoded'},
  data: new URLSearchParams({
     grant_type: 'http://auth0.com/oauth/grant-type/mfa-recovery-code',
     client_id: '{yourClientId}',
     client_secret: '{yourClientSecret}',
     mfa_token: '{mfaToken}',
     recovery_code: '{recoveryCode}'
  })
  };

  axios.request(options).then(function (response) {
  console.log(response.data);
  }).catch(function (error) {
  console.error(error);
  });

  ```

  ```objc Obj-C theme={null}
     #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=http://auth0.com/oauth/grant-type/mfa-recovery-code" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_secret={yourClientSecret}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&mfa_token={mfaToken}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&recovery_code={recoveryCode}" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                        cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];

  ```

  ```php PHP theme={null}
     $curl = curl_init();

  curl_setopt_array($curl, [
  CURLOPT_URL => "https://{yourDomain}/oauth/token",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-recovery-code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&recovery_code=%7BrecoveryCode%7D",
  CURLOPT_HTTPHEADER => [
     "content-type: application/x-www-form-urlencoded"
  ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
  echo "cURL Error #:" . $err;
  } else {
  echo $response;
  }

  ```

  ```python Python theme={null}
     import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-recovery-code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&recovery_code=%7BrecoveryCode%7D"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))

  ```

  ```ruby Ruby theme={null}
     require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-recovery-code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&recovery_code=%7BrecoveryCode%7D"

  response = http.request(request)
  puts response.read_body

  ```

  ```swift Swift theme={null}
     import Foundation

  let headers = ["content-type": "application/x-www-form-urlencoded"]

  let postData = NSMutableData(data: "grant_type=http://auth0.com/oauth/grant-type/mfa-recovery-code".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&client_secret={yourClientSecret}".data(using: String.Encoding.utf8)!)
  postData.append("&mfa_token={mfaToken}".data(using: String.Encoding.utf8)!)
  postData.append("&recovery_code={recoveryCode}".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                         cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()

  ```
</AuthCodeGroup>

3. Prompt user to capture recovery code. If the call is successful, you'll get the authentication tokens and a new recovery code:

   ```json lines theme={null}
   {
       "access_token": "O3...H4",
       "id_token": "eyJh...w",
       "scope": "openid profile",
       "expires_in": 86400,
       "recovery_code": "K6LGLV3RSH3VERMKET8L7QKU",
       "token_type": "Bearer"
   }
   ```

4. Notify the user that a new recovery code was generated and ask them to capture it.

## Learn more

* [Enroll and Challenge SMS and Voice Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-challenge-sms-voice-authenticators)
* [Enroll and Challenge Push Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-push-authenticators)
* [Enroll and Challenge OTP Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-otp-authenticators)
* [Enroll and Challenge Email Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-email-authenticators)
* [Auth0 MFA API](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/mfa-api)
* [Manage Authentication Factors with Authentication API](/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis/manage-authenticator-factors-mfa-api)


# Enroll and Challenge Email Authenticators
Source: https://auth0.com/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-email-authenticators

Describes how to build your own MFA flows using SMS or voice as an authentication factor.

Auth0 provides a built-in <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> enrollment and authentication flow using [Universal Login](/docs/authenticate/login/auth0-universal-login). However, if you want to create your own user interface, you can use the [MFA API](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/mfa-api) to accomplish it.

When email is enabled as a factor, all users with verified emails will be able to use them to complete MFA.

<Card title="Availability varies by Auth0 plan">
  Both your specific login implementation and your Auth0 plan or custom agreement affect whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

## Prerequisites

Before you can use the MFA APIs, you'll need to enable the MFA grant type for your application. Go to [Auth0 Dashboard > Applications > Advanced Settings > Grant Types](https://manage.auth0.com/#/applications) and select **MFA**.

* [Configure Email](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-email-notifications-for-mfa) as a factor in the Dashboard or using the [Management API](https://auth0.com/docs/api/management/v2#!/Guardian/put_factors_by_name).

## Enroll with email

To enable users to enroll emails in addition to their verified email in their primary identity, you need to complete the following steps.

### Get MFA token

Depending on when you are triggering enrollment, you can obtain an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> for using the MFA API in different ways:

* If you are enrolling during authentication, see [Authenticate With Resource Owner Password Grant and MFA](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa).
* If you want to let the user enroll a factor at any moment, see [Manage MFA Factor Enrollments](/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis/manage-authenticator-factors-mfa-api).

### Enroll authenticator

Make a `POST` request to the MFA Associate endpoint to enroll the user's authenticator. The bearer token required by this endpoint is the MFA token obtained in the previous step.

Use the following parameters:

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Value</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>authentication\_types</code></td>
      <td><code>\[oob]</code></td>
    </tr>

    <tr>
      <td><code>oob\_channels</code></td>
      <td><code>\[email]</code></td>
    </tr>

    <tr>
      <td><code>email</code></td>
      <td><code>[email@address.com](mailto:email@address.com)</code>, the users email address.</td>
    </tr>
  </tbody>
</table>

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/mfa/associate' \
    --header 'authorization: Bearer MFA_TOKEN' \
    --header 'content-type: application/json' \
    --data '{ "authenticator_types": ["oob"], "oob_channels": ["email"], "email" : "email@address.com" }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/mfa/associate");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer MFA_TOKEN");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{ "authenticator_types": ["oob"], "oob_channels": ["email"], "email" : "email@address.com" }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/mfa/associate"

  	payload := strings.NewReader("{ "authenticator_types": ["oob"], "oob_channels": ["email"], "email" : "email@address.com" }")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("authorization", "Bearer MFA_TOKEN")
  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/mfa/associate")
    .header("authorization", "Bearer MFA_TOKEN")
    .header("content-type", "application/json")
    .body("{ "authenticator_types": ["oob"], "oob_channels": ["email"], "email" : "email@address.com" }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/mfa/associate',
    headers: {authorization: 'Bearer MFA_TOKEN', 'content-type': 'application/json'},
    data: {
      authenticator_types: ['oob'],
      oob_channels: ['email'],
      email: 'email@address.com'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MFA_TOKEN",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"authenticator_types": @[ @"oob" ],
                                @"oob_channels": @[ @"email" ],
                                @"email": @"email@address.com" };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/mfa/associate"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/mfa/associate",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "authenticator_types": ["oob"], "oob_channels": ["email"], "email" : "email@address.com" }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MFA_TOKEN",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "authenticator_types": ["oob"], "oob_channels": ["email"], "email" : "email@address.com" }"

  headers = {
      'authorization': "Bearer MFA_TOKEN",
      'content-type': "application/json"
      }

  conn.request("POST", "/{yourDomain}/mfa/associate", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/mfa/associate")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer MFA_TOKEN'
  request["content-type"] = 'application/json'
  request.body = "{ "authenticator_types": ["oob"], "oob_channels": ["email"], "email" : "email@address.com" }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer MFA_TOKEN",
    "content-type": "application/json"
  ]
  let parameters = [
    "authenticator_types": ["oob"],
    "oob_channels": ["email"],
    "email": "email@address.com"
  ] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/mfa/associate")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

If successful, you receive a response like this:

```json lines theme={null}
{
    "authenticator_type": "oob",
    "binding_method": "prompt",
    "oob_code" : "Fe26..nWE",
    "oob_channel": "email",
    "recovery_codes": [ "N3BGPZZWJ85JLCNPZBDW6QXC" ]
  }
```

If you get a `User is already enrolled` error, the user already has an MFA factor enrolled. Before associating another factor with the user, you must challenge the user with the existing factor.

If this is the first time the user is associating an authenticator, you'll notice the response includes `recovery_codes`. Recovery codes are used to access the user's account in the event that they lose access to the account or device used for their second-factor authentication. These are one-time usable codes, and new ones are generated as necessary.

### Confirm email enrollment

The user should receive an email containing the 6-digit code that they can provide to the application.

To complete the enrollment, make a `POST` request to the [**`/oath/token`**](https://auth0.com/docs/api/authentication#get-token) endpoint. Include the `oob_code` returned in the previous response and the `binding_code` with the value in the email message.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --data grant_type=http://auth0.com/oauth/grant-type/mfa-oob \
    --data 'mfa_token={mfaToken}' \
    --data 'oob_code={oobCode}' \
    --data 'binding_code={userEmailOtpCode}' \
    --data 'client_id={yourClientId}' \
    --data 'client_secret={yourClientSecret}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddParameter("undefined", "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D&binding_code=%7BuserEmailOtpCode%7D&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D&binding_code=%7BuserEmailOtpCode%7D&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D")

  	req, _ := http.NewRequest("POST", url, payload)

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/oauth/token")
    .body("grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D&binding_code=%7BuserEmailOtpCode%7D&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    data: new URLSearchParams({
      grant_type: 'http://auth0.com/oauth/grant-type/mfa-oob',
      mfa_token: '{mfaToken}',
      oob_code: '{oobCode}',
      binding_code: '{userEmailOtpCode}',
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=http://auth0.com/oauth/grant-type/mfa-oob" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&mfa_token={mfaToken}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&oob_code={oobCode}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&binding_code={userEmailOtpCode}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_secret={yourClientSecret}" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D&binding_code=%7BuserEmailOtpCode%7D&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D",
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D&binding_code=%7BuserEmailOtpCode%7D&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D"

  conn.request("POST", "/{yourDomain}/oauth/token", payload)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request.body = "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D&binding_code=%7BuserEmailOtpCode%7D&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let postData = NSMutableData(data: "grant_type=http://auth0.com/oauth/grant-type/mfa-oob".data(using: String.Encoding.utf8)!)
  postData.append("&mfa_token={mfaToken}".data(using: String.Encoding.utf8)!)
  postData.append("&oob_code={oobCode}".data(using: String.Encoding.utf8)!)
  postData.append("&binding_code={userEmailOtpCode}".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&client_secret={yourClientSecret}".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

If the call was successful, you'll receive a response in the following format, containing the access token:

```json lines theme={null}
{
  "id_token": "eyJ...i",
  "access_token": "eyJ...i",
  "expires_in": 600,
  "scope": "openid profile",
  "token_type": "Bearer"
}
```

At this point, the authenticator is fully associated and ready to be used, and you have the authentication tokens for the user.

You can check at any point to verify whether an authenticator has been confirmed by calling the MFA Authenticators endpoint. If the authenticator is confirmed, the value returned for `active` is `true`.

Optionally, you can customize the emails that users receive. See [Customize Email Templates](/docs/customize/email/email-templates) for details.

## Challenge with email

### Get MFA token

Get an MFA token following the steps described in [Authenticate With Resource Owner Password Grant and MFA](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa).

### Retrieve enrolled authenticators

To challenge the user, you need the `authenticator_id` for the factor you want to challenge. You can list all enrolled authenticators using the MFA Authenticators endpoint:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/mfa/authenticators' \
    --header 'authorization: Bearer MFA_TOKEN' \
    --header 'content-type: application/json'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/mfa/authenticators");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer MFA_TOKEN");
  request.AddHeader("content-type", "application/json");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/mfa/authenticators"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer MFA_TOKEN")
  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/mfa/authenticators")
    .header("authorization", "Bearer MFA_TOKEN")
    .header("content-type", "application/json")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/mfa/authenticators',
    headers: {authorization: 'Bearer MFA_TOKEN', 'content-type': 'application/json'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MFA_TOKEN",
                             @"content-type": @"application/json" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/mfa/authenticators"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/mfa/authenticators",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MFA_TOKEN",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = {
      'authorization': "Bearer MFA_TOKEN",
      'content-type': "application/json"
      }

  conn.request("GET", "/{yourDomain}/mfa/authenticators", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/mfa/authenticators")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer MFA_TOKEN'
  request["content-type"] = 'application/json'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer MFA_TOKEN",
    "content-type": "application/json"
  ]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/mfa/authenticators")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

### Challenge user with OTP

To trigger an email challenge, `POST` to the MFA Challenge endpoint using the corresponding `authenticator_id` and the `mfa_token`.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/mfa/challenge' \
    --data '{  "client_id": "{yourClientId}",  "client_secret": "{yourClientSecret}",  "challenge_type": "oob",  "authenticator_id": "email|dev_NU1Ofuw3Cw0XCt5x", "mfa_token": "{mfaToken}" }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/mfa/challenge");
  var request = new RestRequest(Method.POST);
  request.AddParameter("undefined", "{  "client_id": "{yourClientId}",  "client_secret": "{yourClientSecret}",  "challenge_type": "oob",  "authenticator_id": "email|dev_NU1Ofuw3Cw0XCt5x", "mfa_token": "{mfaToken}" }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/mfa/challenge"

  	payload := strings.NewReader("{  "client_id": "{yourClientId}",  "client_secret": "{yourClientSecret}",  "challenge_type": "oob",  "authenticator_id": "email|dev_NU1Ofuw3Cw0XCt5x", "mfa_token": "{mfaToken}" }")

  	req, _ := http.NewRequest("POST", url, payload)

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/mfa/challenge")
    .body("{  "client_id": "{yourClientId}",  "client_secret": "{yourClientSecret}",  "challenge_type": "oob",  "authenticator_id": "email|dev_NU1Ofuw3Cw0XCt5x", "mfa_token": "{mfaToken}" }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/mfa/challenge',
    data: {
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      challenge_type: 'oob',
      authenticator_id: 'email|dev_NU1Ofuw3Cw0XCt5x',
      mfa_token: '{mfaToken}'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>
  NSDictionary *parameters = @{ @"client_id": @"{yourClientId}",
                                @"client_secret": @"{yourClientSecret}",
                                @"challenge_type": @"oob",
                                @"authenticator_id": @"email|dev_NU1Ofuw3Cw0XCt5x",
                                @"mfa_token": @"{mfaToken}" };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/mfa/challenge"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/mfa/challenge",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{  "client_id": "{yourClientId}",  "client_secret": "{yourClientSecret}",  "challenge_type": "oob",  "authenticator_id": "email|dev_NU1Ofuw3Cw0XCt5x", "mfa_token": "{mfaToken}" }",
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{  "client_id": "{yourClientId}",  "client_secret": "{yourClientSecret}",  "challenge_type": "oob",  "authenticator_id": "email|dev_NU1Ofuw3Cw0XCt5x", "mfa_token": "{mfaToken}" }"

  conn.request("POST", "/{yourDomain}/mfa/challenge", payload)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/mfa/challenge")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request.body = "{  "client_id": "{yourClientId}",  "client_secret": "{yourClientSecret}",  "challenge_type": "oob",  "authenticator_id": "email|dev_NU1Ofuw3Cw0XCt5x", "mfa_token": "{mfaToken}" }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation
  let parameters = [
    "client_id": "{yourClientId}",
    "client_secret": "{yourClientSecret}",
    "challenge_type": "oob",
    "authenticator_id": "email|dev_NU1Ofuw3Cw0XCt5x",
    "mfa_token": "{mfaToken}"
  ] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/mfa/challenge")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

### Complete authentication using received code

If successful, you receive the following response:

```json lines theme={null}
{
  "challenge_type": "oob",
  "oob_code": "abcd1234...",
  "binding_method": "prompt"
}
```

Your application should prompt the user for the code and send it as part of the request in the `binding_code` parameter in the following call to the `oauth``/token` endpoint:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=http://auth0.com/oauth/grant-type/mfa-oob \
    --data 'client_id={yourClientId}' \
    --data 'client_secret={yourClientSecret}' \
    --data 'mfa_token={mfaToken}' \
    --data 'oob_code={oobCode}' \
    --data 'binding_code={userEmailOtpCode}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D&binding_code=%7BuserEmailOtpCode%7D", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D&binding_code=%7BuserEmailOtpCode%7D")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D&binding_code=%7BuserEmailOtpCode%7D")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'http://auth0.com/oauth/grant-type/mfa-oob',
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      mfa_token: '{mfaToken}',
      oob_code: '{oobCode}',
      binding_code: '{userEmailOtpCode}'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=http://auth0.com/oauth/grant-type/mfa-oob" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_secret={yourClientSecret}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&mfa_token={mfaToken}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&oob_code={oobCode}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&binding_code={userEmailOtpCode}" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D&binding_code=%7BuserEmailOtpCode%7D",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D&binding_code=%7BuserEmailOtpCode%7D"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D&binding_code=%7BuserEmailOtpCode%7D"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/x-www-form-urlencoded"]

  let postData = NSMutableData(data: "grant_type=http://auth0.com/oauth/grant-type/mfa-oob".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&client_secret={yourClientSecret}".data(using: String.Encoding.utf8)!)
  postData.append("&mfa_token={mfaToken}".data(using: String.Encoding.utf8)!)
  postData.append("&oob_code={oobCode}".data(using: String.Encoding.utf8)!)
  postData.append("&binding_code={userEmailOtpCode}".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

If the call was successful, you'll receive a response in the format below, containing the access token:

```json lines theme={null}
{
  "id_token": "eyJ...i",
  "access_token": "eyJ...i",
  "expires_in": 600,
  "scope": "openid profile",
  "token_type": "Bearer"
}
```

## Customize MFA

<Warning>
  Customizable MFA with the Resource Owner Password Grant, Embedded, or Refresh Token flows is in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0’s release stages, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To participate in the early access, contact [Auth0 Support](https://support.auth0.com/).
</Warning>

Customizable MFA allows users to enroll and challenge with factors of their choice that are supported by your application.

During authentication at the `oauth/token` endpoint, the response returns the `mfa_required` error that includes the `mfa_token` to use the MFA API and the `mfa_requirements` parameter with a list of authenticators:

```json theme={null}
{
  "error": "mfa_required",
  "error_description": "Multifactor authentication required",
  "mfa_token": "Fe26...Ha",
  "mfa_requirements": {
    "challenge": [
      { "type": "otp" },
      { "type": "push-notification" },
      { "type": "phone" },
      { "type": "recovery-code" }
      { "type": "email"} //can only work with challenge
    ]
  }
}
```

Use the `mfa_token` to call the [`mfa/authenticator`](/docs/api/authentication/muti-factor-authentication/list-authenticators) endpoint for a list of all factors the user has enrolled and match the same type your application supports.  You also need to obtain the matching `authenticator_type` to issue challenges:

```json theme={null}
[
  {
    "type": "recovery-code",
    "id": "recovery-code|dev_qpOkGUOxBpw6R16t",
    "authenticator_type": "recovery-code",
    "active": true
  },
  {
    "type": "otp",
    "id": "totp|dev_6NWz8awwC8brh2dN",
    "authenticator_type": "otp",
    "active": true
  }
]
```

Enforce the MFA challenge by calling the [`request/mfa/challenge`](/docs/api/authentication/muti-factor-authentication/request-mfa-challenge) endpoint.

Further customize your MFA flow with Auth0 Actions. To learn more, read [Actions Triggers: post-challenge - API Object](/docs/customize/actions/explore-triggers/password-reset-triggers/post-challenge-trigger/post-challenge-api-object).

## Learn more

* [Manage Authentication Factors with Authentication API](/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis/manage-authenticator-factors-mfa-api)
* [Challenge with Recovery Codes](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/challenge-with-recovery-codes)
* [Enroll and Challenge OTP Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-otp-authenticators)
* [Enroll and Challenge Push Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-push-authenticators)
* [Enroll and Challenge SMS and Voice Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-challenge-sms-voice-authenticators)


# Enroll and Challenge OTP Authenticators
Source: https://auth0.com/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-otp-authenticators

Describes how to build your own MFA flows using one-time password (OTP) as an authentication factor.

Auth0 provides a built-in <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> enrollment and authentication flow using [Universal Login](/docs/authenticate/login/auth0-universal-login). However, if you want to create your own user interface, you can use the [MFA API](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/mfa-api) to accomplish it.

## Prerequisites

Before you can use the MFA APIs, you'll need to enable the MFA grant type for your application. Go to [Auth0 Dashboard > Applications > Advanced Settings > Grant Types](https://manage.auth0.com/#/applications) and select **MFA**.

* [Configure OTP](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-otp-notifications-for-mfa) as a factor in the Dashboard or using the [Management API](https://auth0.com/docs/api/management/v2#!/Guardian/put_factors_by_name).

## Enroll with OTP

### Get MFA token

Depending on when you are triggering enrollment, you can obtain an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> for using the MFA API in different ways:

* If you are enrolling during authentication, see [Authenticate With Resource Owner Password Grant and MFA](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa).
* If you want to let the user enroll a factor at any moment, see [Manage MFA Factor Enrollments](/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis/manage-authenticator-factors-mfa-api).

### Enroll authenticator

Make a `POST` request to the MFA Associate endpoint to enroll the user's authenticator. The bearer token required by this endpoint is the MFA token obtained in the previous step.

To enroll with OTP, set the `authenticator_types` parameter to `[otp]`.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/mfa/associate' \
    --header 'authorization: Bearer MFA_TOKEN' \
    --header 'content-type: application/json' \
    --data '{ "authenticator_types": ["otp"] }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/mfa/associate");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer MFA_TOKEN");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{ "authenticator_types": ["otp"] }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/mfa/associate"

  	payload := strings.NewReader("{ "authenticator_types": ["otp"] }")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("authorization", "Bearer MFA_TOKEN")
  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/mfa/associate")
    .header("authorization", "Bearer MFA_TOKEN")
    .header("content-type", "application/json")
    .body("{ "authenticator_types": ["otp"] }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/mfa/associate',
    headers: {authorization: 'Bearer MFA_TOKEN', 'content-type': 'application/json'},
    data: {authenticator_types: ['otp']}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MFA_TOKEN",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"authenticator_types": @[ @"otp" ] };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/mfa/associate"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/mfa/associate",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "authenticator_types": ["otp"] }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MFA_TOKEN",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "authenticator_types": ["otp"] }"

  headers = {
      'authorization': "Bearer MFA_TOKEN",
      'content-type': "application/json"
      }

  conn.request("POST", "/{yourDomain}/mfa/associate", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/mfa/associate")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer MFA_TOKEN'
  request["content-type"] = 'application/json'
  request.body = "{ "authenticator_types": ["otp"] }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer MFA_TOKEN",
    "content-type": "application/json"
  ]
  let parameters = ["authenticator_types": ["otp"]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/mfa/associate")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

If successful, you receive a response like this:

```json lines theme={null}
{
  "authenticator_type": "otp",
  "secret": "EN...S",
  "barcode_uri": "otpauth://totp/tenant:user?secret=...&issuer=tenant&algorithm=SHA1&digits=6&period=30",
  "recovery_codes": [ "N3B...XC"]
}
```

If you get a `User is already enrolled` error, the user already has an MFA factor enrolled. Before associating another factor with the user, you must challenge the user with the existing factor.

If this is the first time the user is associating an authenticator, you'll notice the response includes `recovery_codes`. Recovery codes are used to access the user's account in the event that they lose access to the account or device used for their second-factor authentication. These are one-time usable codes, and new ones are generated as necessary.

### Confirm OTP enrollment

To confirm the enrollment, the end user will need to enter the secret obtained in the previous step in an OTP generator application like Google Authenticator. They can enter the secret by scanning a QR code with the `barcode_uri` or by typing the secret code manually in that OTP application. You should provide users a way to get the secret as text in case they cannot scan the QR code (for example, if they are enrolling from a mobile device, or using a desktop OTP application).

After the user enters the secret, the OTP application will display a 6-digit code, that the user should enter in your application. The application should then make a `POST` request to the <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> <Tooltip href="/docs/glossary?term=Token+endpoint">Token endpoint</Tooltip>, including that `otp` value.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=http://auth0.com/oauth/grant-type/mfa-otp \
    --data 'client_id={yourClientId}' \
    --data 'mfa_token={mfaToken}' \
    --data 'client_secret={yourClientSecret}' \
    --data 'otp={userOtpCode}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-otp&client_id={yourClientId}&mfa_token=%7BmfaToken%7D&client_secret=%7ByourClientSecret%7D&otp=%7BuserOtpCode%7D", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-otp&client_id={yourClientId}&mfa_token=%7BmfaToken%7D&client_secret=%7ByourClientSecret%7D&otp=%7BuserOtpCode%7D")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-otp&client_id={yourClientId}&mfa_token=%7BmfaToken%7D&client_secret=%7ByourClientSecret%7D&otp=%7BuserOtpCode%7D")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'http://auth0.com/oauth/grant-type/mfa-otp',
      client_id: '{yourClientId}',
      mfa_token: '{mfaToken}',
      client_secret: '{yourClientSecret}',
      otp: '{userOtpCode}'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=http://auth0.com/oauth/grant-type/mfa-otp" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&mfa_token={mfaToken}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_secret={yourClientSecret}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&otp={userOtpCode}" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-otp&client_id={yourClientId}&mfa_token=%7BmfaToken%7D&client_secret=%7ByourClientSecret%7D&otp=%7BuserOtpCode%7D",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-otp&client_id={yourClientId}&mfa_token=%7BmfaToken%7D&client_secret=%7ByourClientSecret%7D&otp=%7BuserOtpCode%7D"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-otp&client_id={yourClientId}&mfa_token=%7BmfaToken%7D&client_secret=%7ByourClientSecret%7D&otp=%7BuserOtpCode%7D"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/x-www-form-urlencoded"]

  let postData = NSMutableData(data: "grant_type=http://auth0.com/oauth/grant-type/mfa-otp".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&mfa_token={mfaToken}".data(using: String.Encoding.utf8)!)
  postData.append("&client_secret={yourClientSecret}".data(using: String.Encoding.utf8)!)
  postData.append("&otp={userOtpCode}".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

If the call was successful, you'll receive a response in the following format, containing the access token:

```json lines theme={null}
{
  "id_token": "eyJ...i",
  "access_token": "eyJ...i",
  "expires_in": 600,
  "scope": "openid profile",
  "token_type": "Bearer"
}
```

At this point, the authenticator is fully associated and ready to be used, and you have the authentication tokens for the user.

You can check at any point to verify whether an authenticator has been confirmed by calling the MFA Authenticators endpoint. If the authenticator is confirmed, the value returned for `active` is `true`.

## Challenge with OTP

### Get MFA token

Get an MFA token following the steps described in [Authenticate With Resource Owner Password Grant and MFA](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa).

### Retrieve enrolled authenticators

You can list all enrolled authenticators using the MFA Authenticators endpoint:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/mfa/authenticators' \
    --header 'authorization: Bearer MFA_TOKEN' \
    --header 'content-type: application/json'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/mfa/authenticators");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer MFA_TOKEN");
  request.AddHeader("content-type", "application/json");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/mfa/authenticators"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer MFA_TOKEN")
  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/mfa/authenticators")
    .header("authorization", "Bearer MFA_TOKEN")
    .header("content-type", "application/json")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/mfa/authenticators',
    headers: {authorization: 'Bearer MFA_TOKEN', 'content-type': 'application/json'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MFA_TOKEN",
                             @"content-type": @"application/json" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/mfa/authenticators"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/mfa/authenticators",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MFA_TOKEN",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = {
      'authorization': "Bearer MFA_TOKEN",
      'content-type': "application/json"
      }

  conn.request("GET", "/{yourDomain}/mfa/authenticators", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/mfa/authenticators")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer MFA_TOKEN'
  request["content-type"] = 'application/json'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer MFA_TOKEN",
    "content-type": "application/json"
  ]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/mfa/authenticators")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

You will get a list of authenticators with the following format:

```json lines theme={null}
[
    {
        "id": "recovery-code|dev_qpOkGUOxBpw6R16t",
        "authenticator_type": "recovery-code",
        "active": true
    },
    {
        "id": "totp|dev_6NWz8awwC8brh2dN",
        "authenticator_type": "otp",
        "active": true
    }
]
```

### Complete authentication using received code

The user will collect a one time password, which you will then collect from them. You can verify the code and get authentication tokens using the OAuth0 Token endpoint, specifying the one time password in the `otp` parameter:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=http://auth0.com/oauth/grant-type/mfa-otp \
    --data 'client_id={yourClientId}' \
    --data 'client_secret={yourClientSecret}' \
    --data 'mfa_token={mfaToken}' \
    --data 'otp={userOtpCode}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-otp&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&otp=%7BuserOtpCode%7D", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-otp&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&otp=%7BuserOtpCode%7D")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-otp&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&otp=%7BuserOtpCode%7D")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'http://auth0.com/oauth/grant-type/mfa-otp',
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      mfa_token: '{mfaToken}',
      otp: '{userOtpCode}'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=http://auth0.com/oauth/grant-type/mfa-otp" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_secret={yourClientSecret}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&mfa_token={mfaToken}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&otp={userOtpCode}" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-otp&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&otp=%7BuserOtpCode%7D",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-otp&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&otp=%7BuserOtpCode%7D"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-otp&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&otp=%7BuserOtpCode%7D"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/x-www-form-urlencoded"]

  let postData = NSMutableData(data: "grant_type=http://auth0.com/oauth/grant-type/mfa-otp".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&client_secret={yourClientSecret}".data(using: String.Encoding.utf8)!)
  postData.append("&mfa_token={mfaToken}".data(using: String.Encoding.utf8)!)
  postData.append("&otp={userOtpCode}".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

If the call was successful, you'll receive a response in the format below, containing the access token:

```json lines theme={null}
{
  "id_token": "eyJ...i",
  "access_token": "eyJ...i",
  "expires_in": 600,
  "scope": "openid profile",
  "token_type": "Bearer"
}
```

## Customize MFA

<Warning>
  Customizable MFA with the Resource Owner Password Grant, Embedded, or Refresh Token flows is in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0’s release stages, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To participate in the early access, contact [Auth0 Support](https://support.auth0.com/).
</Warning>

Customizable MFA allows users to enroll and challenge with factors of their choice that are supported by your application.

During authentication at the `oauth/token` endpoint, the response returns the `mfa_required` error that includes the `mfa_token` to use the MFA API and the `mfa_requirements` parameter with a list of authenticators:

```json theme={null}
{
  "error": "mfa_required",
  "error_description": "Multifactor authentication required",
  "mfa_token": "Fe26...Ha",
  "mfa_requirements": {
    "challenge": [
      { "type": "otp" },
      { "type": "push-notification" },
      { "type": "phone" },
      { "type": "recovery-code" }
      { "type": "email"} //can only work with challenge
    ]
  }
}
```

Use the `mfa_token` to call the [`mfa/authenticator`](/docs/api/authentication/muti-factor-authentication/list-authenticators) endpoint for a list of all factors the user has enrolled and match the same type your application supports.  You also need to obtain the matching `authenticator_type` to issue challenges:

```json theme={null}
[
  {
    "type": "recovery-code",
    "id": "recovery-code|dev_qpOkGUOxBpw6R16t",
    "authenticator_type": "recovery-code",
    "active": true
  },
  {
    "type": "otp",
    "id": "totp|dev_6NWz8awwC8brh2dN",
    "authenticator_type": "otp",
    "active": true
  }
]
```

Enforce the MFA challenge by calling the [`request/mfa/challenge`](/docs/api/authentication/muti-factor-authentication/request-mfa-challenge) endpoint.

Further customize your MFA flow with Auth0 Actions. To learn more, read [Actions Triggers: post-challenge - API Object](/docs/customize/actions/explore-triggers/password-reset-triggers/post-challenge-trigger/post-challenge-api-object).

## Learn more

* [Manage Authentication Factors with Authentication API](/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis/manage-authenticator-factors-mfa-api)
* [Configure OTP Notifications for MFA](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-otp-notifications-for-mfa)
* [Challenge with Recovery Codes](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/challenge-with-recovery-codes)
* [Enroll and Challenge SMS and Voice Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-challenge-sms-voice-authenticators)
* [Enroll and Challenge Email Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-email-authenticators)
* [Enroll and Challenge Push Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-push-authenticators)


# Enroll and Challenge Push Authenticators
Source: https://auth0.com/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-push-authenticators

Describes how to build your own MFA flows using push as an authentication factor.

Auth0 provides a built-in <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> enrollment and authentication flow using [Universal Login](/docs/authenticate/login/auth0-universal-login). However, if you want to create your own user interface, you can use the [MFA API](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/mfa-api) to accomplish it.

You can enroll and challenge users using push notifications with the Guardian application or SDK using the MFA API.

## Prerequisites

Before you can use the MFA APIs, you'll need to enable the MFA grant type for your application. Go to [Auth0 Dashboard > Applications > Advanced Settings > Grant Types](https://manage.auth0.com/#/applications) and select **MFA**.

* [Configure Push](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-push-notifications-for-mfa) as a factor in the Dashboard or using the [Management API](https://auth0.com/docs/api/management/v2#!/Guardian/put_factors_by_name).

## Enroll with push

### Get MFA token

Depending on when you are triggering enrollment, you can obtain an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> for using the MFA API in different ways:

* If you are enrolling during authentication, see [Authenticate With Resource Owner Password Grant and MFA](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa).
* If you want to let the user enroll a factor at any moment, see [Manage MFA Factor Enrollments](/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis/manage-authenticator-factors-mfa-api).

### Enroll authenticator

Make a `POST` request to the MFA Associate endpoint to enroll the user's authenticator. The bearer token required by this endpoint is the MFA token obtained in the previous step.

To enroll with push, set the `authenticator_types` parameter to `[oob]` and the `oob_channels` parameter to `[auth0]`.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/mfa/associate' \
    --header 'authorization: Bearer MFA_TOKEN' \
    --header 'content-type: application/json' \
    --data '{ "authenticator_types": ["oob"], "oob_channels": ["auth0"] }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/mfa/associate");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer MFA_TOKEN");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{ "authenticator_types": ["oob"], "oob_channels": ["auth0"] }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/mfa/associate"

  	payload := strings.NewReader("{ "authenticator_types": ["oob"], "oob_channels": ["auth0"] }")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("authorization", "Bearer MFA_TOKEN")
  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/mfa/associate")
    .header("authorization", "Bearer MFA_TOKEN")
    .header("content-type", "application/json")
    .body("{ "authenticator_types": ["oob"], "oob_channels": ["auth0"] }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/mfa/associate',
    headers: {authorization: 'Bearer MFA_TOKEN', 'content-type': 'application/json'},
    data: {authenticator_types: ['oob'], oob_channels: ['auth0']}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MFA_TOKEN",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"authenticator_types": @[ @"oob" ],
                                @"oob_channels": @[ @"auth0" ] };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/mfa/associate"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/mfa/associate",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "authenticator_types": ["oob"], "oob_channels": ["auth0"] }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MFA_TOKEN",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "authenticator_types": ["oob"], "oob_channels": ["auth0"] }"

  headers = {
      'authorization': "Bearer MFA_TOKEN",
      'content-type': "application/json"
      }

  conn.request("POST", "/{yourDomain}/mfa/associate", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/mfa/associate")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer MFA_TOKEN'
  request["content-type"] = 'application/json'
  request.body = "{ "authenticator_types": ["oob"], "oob_channels": ["auth0"] }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer MFA_TOKEN",
    "content-type": "application/json"
  ]
  let parameters = [
    "authenticator_types": ["oob"],
    "oob_channels": ["auth0"]
  ] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/mfa/associate")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

If successful, you receive a response like this:

```json lines theme={null}
{
    "authenticator_type": "oob",
    "barcode_uri": "otpauth://totp/tenant:user?enrollment_tx_id=qfjn2eiNYSjU3xID7dBYeCBSrdREWJPY&base_url=tenan",
    "recovery_codes": [
        "ALKE6EJZ4853BJYLM2DM2WU7"
    ],
    "oob_channel": "auth0",
    "oob_code": "Fe26.2...SYAg"
}
```

If you get a `User is already enrolled` error, the user already has an MFA factor enrolled. Before associating another factor with the user, you must challenge the user with the existing factor.

If this is the first time the user is associating an authenticator, you'll notice the response includes `recovery_codes`. Recovery codes are used to access the user's account in the event that they lose access to the account or device used for their second-factor authentication. These are one-time usable codes, and new ones are generated as necessary.

### Confirm push enrollment

To confirm the enrollment, the end user will need to scan a QR code with the `barcode_uri` in the Guardian application, within the next 5 minutes.

Once that is done, the Guardian application will notify Auth0 that the user enrolled successfully. To know if that happened, poll the Auth0 <Tooltip href="/docs/glossary?term=Token+endpoint">Token endpoint</Tooltip> with the `oob_code` returned by the MFA Associate endpoint call.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'authorization: Bearer {mfaToken}' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=http://auth0.com/oauth/grant-type/mfa-oob \
    --data 'client_id={yourClientId}' \
    --data 'client_secret={yourClientSecret}' \
    --data 'mfa_token={mfaToken}' \
    --data 'oob_code={oobCode}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer {mfaToken}");
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("authorization", "Bearer {mfaToken}")
  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("authorization", "Bearer {mfaToken}")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {
      authorization: 'Bearer {mfaToken}',
      'content-type': 'application/x-www-form-urlencoded'
    },
    data: new URLSearchParams({
      grant_type: 'http://auth0.com/oauth/grant-type/mfa-oob',
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      mfa_token: '{mfaToken}',
      oob_code: '{oobCode}'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {mfaToken}",
                             @"content-type": @"application/x-www-form-urlencoded" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=http://auth0.com/oauth/grant-type/mfa-oob" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_secret={yourClientSecret}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&mfa_token={mfaToken}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&oob_code={oobCode}" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {mfaToken}",
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D"

  headers = {
      'authorization': "Bearer {mfaToken}",
      'content-type': "application/x-www-form-urlencoded"
      }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer {mfaToken}'
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer {mfaToken}",
    "content-type": "application/x-www-form-urlencoded"
  ]

  let postData = NSMutableData(data: "grant_type=http://auth0.com/oauth/grant-type/mfa-oob".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&client_secret={yourClientSecret}".data(using: String.Encoding.utf8)!)
  postData.append("&mfa_token={mfaToken}".data(using: String.Encoding.utf8)!)
  postData.append("&oob_code={oobCode}".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

If the user has not scanned the code, it will return an `authorization_pending` response, indicating that you need to call `oauth_token` again in a few seconds:

```json lines theme={null}
{
    "error": "authorization_pending",
    "error_description": "Authorization pending: please repeat the request in a few seconds."
}
```

If the call was successful, you'll receive a response in the following format, containing the access token:

```json lines theme={null}
{
  "id_token": "eyJ...i",
  "access_token": "eyJ...i",
  "expires_in": 600,
  "scope": "openid profile",
  "token_type": "Bearer"
}
```

At this point, the authenticator is fully associated and ready to be used, and you have the authentication tokens for the user.

You can check at any point to verify whether an authenticator has been confirmed by calling the MFA Authenticators endpoint. If the authenticator is confirmed, the value returned for `active` is `true`.

## Challenge with push

### Get MFA token

Get an MFA token following the steps described in [Authenticate With Resource Owner Password Grant and MFA](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa).

### Retrieve enrolled authenticators

To challenge the user, you need the `authenticator_id` for the factor you want to challenge. You can list all enrolled authenticators using the MFA Authenticators endpoint:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/mfa/authenticators' \
    --header 'authorization: Bearer MFA_TOKEN' \
    --header 'content-type: application/json'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/mfa/authenticators");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer MFA_TOKEN");
  request.AddHeader("content-type", "application/json");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/mfa/authenticators"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer MFA_TOKEN")
  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/mfa/authenticators")
    .header("authorization", "Bearer MFA_TOKEN")
    .header("content-type", "application/json")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/mfa/authenticators',
    headers: {authorization: 'Bearer MFA_TOKEN', 'content-type': 'application/json'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MFA_TOKEN",
                             @"content-type": @"application/json" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/mfa/authenticators"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/mfa/authenticators",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MFA_TOKEN",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = {
      'authorization': "Bearer MFA_TOKEN",
      'content-type': "application/json"
      }

  conn.request("GET", "/{yourDomain}/mfa/authenticators", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/mfa/authenticators")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer MFA_TOKEN'
  request["content-type"] = 'application/json'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer MFA_TOKEN",
    "content-type": "application/json"
  ]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/mfa/authenticators")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

You will get a list of authenticators with the following format:

```json lines theme={null}
[
    {
        "id": "recovery-code|dev_Ahb2Tb0ujX3w7ilC",
        "authenticator_type": "recovery-code",
        "active": true
    },
    {
        "id": "push|dev_ZUla9SQ6tAIHSz6y",
        "authenticator_type": "oob",
        "active": true,
        "oob_channel": "auth0",
        "name": "user's device name"
    },
    {
        "id": "totp|dev_gJ6Y6vpSrjnKeT67",
        "authenticator_type": "otp",
        "active": true
    }
]
```

When users enroll with push, they also get enrolled in OTP, as Guardian supports [challenging with OTP](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-otp-authenticators) for scenarios where the user does not have connectivity.

### Challenge user with push

To trigger a push challenge, `POST` to the MFA Challenge endpoint using the corresponding `authenticator_id` and the `mfa_token`.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/mfa/challenge' \
    --data '{ "client_id": "{yourClientId}",  "client_secret": "{yourClientSecret", "challenge_type": "oob", "authenticator_id": "push|dev_ZUla9SQ6tAIHSz6y", "mfa_token": "{mfaToken}" }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/mfa/challenge");
  var request = new RestRequest(Method.POST);
  request.AddParameter("undefined", "{ "client_id": "{yourClientId}",  "client_secret": "{yourClientSecret", "challenge_type": "oob", "authenticator_id": "push|dev_ZUla9SQ6tAIHSz6y", "mfa_token": "{mfaToken}" }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/mfa/challenge"

  	payload := strings.NewReader("{ "client_id": "{yourClientId}",  "client_secret": "{yourClientSecret", "challenge_type": "oob", "authenticator_id": "push|dev_ZUla9SQ6tAIHSz6y", "mfa_token": "{mfaToken}" }")

  	req, _ := http.NewRequest("POST", url, payload)

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/mfa/challenge")
    .body("{ "client_id": "{yourClientId}",  "client_secret": "{yourClientSecret", "challenge_type": "oob", "authenticator_id": "push|dev_ZUla9SQ6tAIHSz6y", "mfa_token": "{mfaToken}" }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/mfa/challenge',
    data: {
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret',
      challenge_type: 'oob',
      authenticator_id: 'push|dev_ZUla9SQ6tAIHSz6y',
      mfa_token: '{mfaToken}'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>
  NSDictionary *parameters = @{ @"client_id": @"{yourClientId}",
                                @"client_secret": @"{yourClientSecret",
                                @"challenge_type": @"oob",
                                @"authenticator_id": @"push|dev_ZUla9SQ6tAIHSz6y",
                                @"mfa_token": @"{mfaToken}" };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/mfa/challenge"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/mfa/challenge",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "client_id": "{yourClientId}",  "client_secret": "{yourClientSecret", "challenge_type": "oob", "authenticator_id": "push|dev_ZUla9SQ6tAIHSz6y", "mfa_token": "{mfaToken}" }",
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "client_id": "{yourClientId}",  "client_secret": "{yourClientSecret", "challenge_type": "oob", "authenticator_id": "push|dev_ZUla9SQ6tAIHSz6y", "mfa_token": "{mfaToken}" }"

  conn.request("POST", "/{yourDomain}/mfa/challenge", payload)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/mfa/challenge")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request.body = "{ "client_id": "{yourClientId}",  "client_secret": "{yourClientSecret", "challenge_type": "oob", "authenticator_id": "push|dev_ZUla9SQ6tAIHSz6y", "mfa_token": "{mfaToken}" }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation
  let parameters = [
    "client_id": "{yourClientId}",
    "client_secret": "{yourClientSecret",
    "challenge_type": "oob",
    "authenticator_id": "push|dev_ZUla9SQ6tAIHSz6y",
    "mfa_token": "{mfaToken}"
  ] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/mfa/challenge")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

### Complete authentication using received code

If success, you receive the following response:

```json lines theme={null}
{
    "challenge_type": "oob",
    "oob_code": "Fe26...jGco"
}
```

Your application must start polling the OAuth0 Token endpoint until the user accepts the push notification.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=http://auth0.com/oauth/grant-type/mfa-oob \
    --data 'client_id={yourClientId}' \
    --data 'client_secret={yourClientSecret}' \
    --data 'mfa_token={mfaToken}' \
    --data 'oob_code={oobCode}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'http://auth0.com/oauth/grant-type/mfa-oob',
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      mfa_token: '{mfaToken}',
      oob_code: '{oobCode}'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=http://auth0.com/oauth/grant-type/mfa-oob" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_secret={yourClientSecret}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&mfa_token={mfaToken}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&oob_code={oobCode}" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/x-www-form-urlencoded"]

  let postData = NSMutableData(data: "grant_type=http://auth0.com/oauth/grant-type/mfa-oob".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&client_secret={yourClientSecret}".data(using: String.Encoding.utf8)!)
  postData.append("&mfa_token={mfaToken}".data(using: String.Encoding.utf8)!)
  postData.append("&oob_code={oobCode}".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

The call can return one of the following results:

<table>
  <thead>
    <tr>
      <th>Result</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>authorization\_pending</code></td>
      <td>Error: If the challenge has not been accepted or rejected.</td>
    </tr>

    <tr>
      <td><code>slow\_down</code></td>
      <td>Error: If the polling is too frequent.</td>
    </tr>

    <tr>
      <td><code>access\_token</code> and <code>refresh\_token</code></td>
      <td>If the challenge has been accepted; polling should be stopped at this point.</td>
    </tr>

    <tr>
      <td><code>invalid\_grant</code></td>
      <td>Error: If the challenge has been rejected: polling should be stopped at this point.</td>
    </tr>
  </tbody>
</table>

## Customize MFA

<Warning>
  Customizable MFA with the Resource Owner Password Grant, Embedded, or Refresh Token flows is in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0’s release stages, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To participate in the early access, contact [Auth0 Support](https://support.auth0.com/).
</Warning>

Customizable MFA allows users to enroll and challenge with factors of their choice that are supported by your application.

During authentication at the `oauth/token` endpoint, the response returns the `mfa_required` error that includes the `mfa_token` to use the MFA API and the `mfa_requirements` parameter with a list of authenticators:

```json theme={null}
{
  "error": "mfa_required",
  "error_description": "Multifactor authentication required",
  "mfa_token": "Fe26...Ha",
  "mfa_requirements": {
    "challenge": [
      { "type": "otp" },
      { "type": "push-notification" },
      { "type": "phone" },
      { "type": "recovery-code" }
      { "type": "email"} //can only work with challenge
    ]
  }
}
```

Use the `mfa_token` to call the [`mfa/authenticator`](/docs/api/authentication/muti-factor-authentication/list-authenticators) endpoint for a list of all factors the user has enrolled and match the same type your application supports.  You also need to obtain the matching `authenticator_type` to issue challenges:

```json theme={null}
[
  {
    "type": "recovery-code",
    "id": "recovery-code|dev_qpOkGUOxBpw6R16t",
    "authenticator_type": "recovery-code",
    "active": true
  },
  {
    "type": "otp",
    "id": "totp|dev_6NWz8awwC8brh2dN",
    "authenticator_type": "otp",
    "active": true
  }
]
```

Enforce the MFA challenge by calling the [`request/mfa/challenge`](/docs/api/authentication/muti-factor-authentication/request-mfa-challenge) endpoint.

Further customize your MFA flow with Auth0 Actions. To learn more, read [Actions Triggers: post-challenge - API Object](/docs/customize/actions/explore-triggers/password-reset-triggers/post-challenge-trigger/post-challenge-api-object).

## Learn more

* [Manage Authentication Factors with Authentication API](/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis/manage-authenticator-factors-mfa-api)
* [Configure Push Notifications for MFA](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-push-notifications-for-mfa)
* [Challenge with Recovery Codes](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/challenge-with-recovery-codes)
* [Enroll and Challenge Email Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-email-authenticators)
* [Enroll and Challenge OTP Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-otp-authenticators)
* [Enroll and Challenge SMS and Voice Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-challenge-sms-voice-authenticators)


# Enroll and Challenge SMS and Voice Authenticators
Source: https://auth0.com/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-challenge-sms-voice-authenticators

Describes how to build your own MFA flows using SMS and/or voice as an authentication factor.

Auth0 provides a built-in <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> enrollment and authentication flow using [Universal Login](/docs/authenticate/login/auth0-universal-login). However, if you want to create your own user interface, you can use the [MFA API](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/mfa-api) to accomplish it.

## Prerequisites

Before you can use the MFA APIs, you'll need to enable the MFA grant type for your application. Go to [Auth0 Dashboard > Applications > Advanced Settings > Grant Types](https://manage.auth0.com/#/applications) and select **MFA**.

* [Configure phone as a factor](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-sms-voice-notifications-mfa) in the Dashboard or using the [Management API](https://auth0.com/docs/api/management/v2#!/Guardian/put_factors_by_name).

## Enroll with SMS or voice

### Get MFA token

Depending on when you are triggering enrollment, you can obtain an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> for using the MFA API in different ways:

* If you are enrolling during authentication, see [Authenticate With Resource Owner Password Grant and MFA](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa).
* If you want to let the user enroll a factor at any moment, see [Manage MFA Factor Enrollments](/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis/manage-authenticator-factors-mfa-api).

### Enroll authenticator

Make a `POST` request to the MFA Associate endpoint to enroll the user's authenticator. The bearer token required by this endpoint is the MFA token obtained in the previous step.

To enroll with SMS or voice, they enroll with a phone number that can be challenged either with SMS or voice. Specific the parameters below to call the endpoint. The `oob_channels` parameter indicates how you want to send the code to the user (SMS or voice).

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/mfa/associate' \
    --header 'authorization: Bearer {mfaToken}' \
    --header 'content-type: application/json' \
    --data '{ "authenticator_types": ["oob"], "oob_channels": ["sms"], "phone_number": "+11...9" }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/mfa/associate");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer {mfaToken}");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{ "authenticator_types": ["oob"], "oob_channels": ["sms"], "phone_number": "+11...9" }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/mfa/associate"

  	payload := strings.NewReader("{ "authenticator_types": ["oob"], "oob_channels": ["sms"], "phone_number": "+11...9" }")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("authorization", "Bearer {mfaToken}")
  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/mfa/associate")
    .header("authorization", "Bearer {mfaToken}")
    .header("content-type", "application/json")
    .body("{ "authenticator_types": ["oob"], "oob_channels": ["sms"], "phone_number": "+11...9" }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/mfa/associate',
    headers: {authorization: 'Bearer {mfaToken}', 'content-type': 'application/json'},
    data: {authenticator_types: ['oob'], oob_channels: ['sms'], phone_number: '+11...9'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {mfaToken}",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"authenticator_types": @[ @"oob" ],
                                @"oob_channels": @[ @"sms" ],
                                @"phone_number": @"+11...9" };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/mfa/associate"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/mfa/associate",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "authenticator_types": ["oob"], "oob_channels": ["sms"], "phone_number": "+11...9" }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {mfaToken}",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "authenticator_types": ["oob"], "oob_channels": ["sms"], "phone_number": "+11...9" }"

  headers = {
      'authorization': "Bearer {mfaToken}",
      'content-type': "application/json"
      }

  conn.request("POST", "/{yourDomain}/mfa/associate", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/mfa/associate")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer {mfaToken}'
  request["content-type"] = 'application/json'
  request.body = "{ "authenticator_types": ["oob"], "oob_channels": ["sms"], "phone_number": "+11...9" }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer {mfaToken}",
    "content-type": "application/json"
  ]
  let parameters = [
    "authenticator_types": ["oob"],
    "oob_channels": ["sms"],
    "phone_number": "+11...9"
  ] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/mfa/associate")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Value</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>authentication\_types</code></td>
      <td><code>\[oob]</code></td>
    </tr>

    <tr>
      <td><code>oob\_channels</code></td>
      <td><code>\[sms]</code> or <code>\[voice]</code></td>
    </tr>

    <tr>
      <td><code>phone\_number</code></td>
      <td><code>+11...9</code>, the phone number <a href="https://en.wikipedia.org/wiki/e.164">E.164 format</a></td>
    </tr>
  </tbody>
</table>

If successful, you receive a response like this:

```json lines theme={null}
{
  "authenticator_type": "oob",
  "binding_method": "prompt",
  "recovery_codes": [ "N3BGPZZWJ85JLCNPZBDW6QXC" ],
  "oob_channel": "sms",
  "oob_code": "ata6daXAiOi..."
}
`
```

If you get a `User is already enrolled` error, the user already has an MFA factor enrolled. Before associating another factor with the user, you must challenge the user with the existing factor.

If this is the first time the user is associating an authenticator, you'll notice the response includes `recovery_codes`. Recovery codes are used to access the user's account in the event that they lose access to the account or device used for their second-factor authentication. These are one-time usable codes, and new ones are generated as necessary.

### Confirm SMS or voice enrollment

Users should receive a message with a 6-digit code that they need to provide to the application.

To complete enrollment, make a `POST` request to the <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> <Tooltip href="/docs/glossary?term=Token+endpoint">Token endpoint</Tooltip>. You need to include the `oob_code` returned in the previous response, and the `binding_code` with the value received in the message.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'authorization: Bearer {mfaToken}' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=http://auth0.com/oauth/grant-type/mfa-oob \
    --data 'client_id={yourClientId}' \
    --data 'client_secret={yourClientSecret}' \
    --data 'mfa_token={mfaToken}' \
    --data 'oob_code={oobCode}' \
    --data 'binding_code={userOtpCode}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer {mfaToken}");
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D&binding_code=%7BuserOtpCode%7D", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D&binding_code=%7BuserOtpCode%7D")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("authorization", "Bearer {mfaToken}")
  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("authorization", "Bearer {mfaToken}")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D&binding_code=%7BuserOtpCode%7D")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {
      authorization: 'Bearer {mfaToken}',
      'content-type': 'application/x-www-form-urlencoded'
    },
    data: new URLSearchParams({
      grant_type: 'http://auth0.com/oauth/grant-type/mfa-oob',
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      mfa_token: '{mfaToken}',
      oob_code: '{oobCode}',
      binding_code: '{userOtpCode}'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {mfaToken}",
                             @"content-type": @"application/x-www-form-urlencoded" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=http://auth0.com/oauth/grant-type/mfa-oob" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_secret={yourClientSecret}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&mfa_token={mfaToken}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&oob_code={oobCode}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&binding_code={userOtpCode}" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D&binding_code=%7BuserOtpCode%7D",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {mfaToken}",
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D&binding_code=%7BuserOtpCode%7D"

  headers = {
      'authorization': "Bearer {mfaToken}",
      'content-type': "application/x-www-form-urlencoded"
      }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer {mfaToken}'
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D&binding_code=%7BuserOtpCode%7D"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer {mfaToken}",
    "content-type": "application/x-www-form-urlencoded"
  ]

  let postData = NSMutableData(data: "grant_type=http://auth0.com/oauth/grant-type/mfa-oob".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&client_secret={yourClientSecret}".data(using: String.Encoding.utf8)!)
  postData.append("&mfa_token={mfaToken}".data(using: String.Encoding.utf8)!)
  postData.append("&oob_code={oobCode}".data(using: String.Encoding.utf8)!)
  postData.append("&binding_code={userOtpCode}".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

If the call was successful, you'll receive a response in the following format, containing the access token:

```json lines theme={null}
{
  "id_token": "eyJ...i",
  "access_token": "eyJ...i",
  "expires_in": 600,
  "scope": "openid profile",
  "token_type": "Bearer"
}
```

## Challenge with SMS or voice

### Get MFA token

Get an MFA token following the steps described in [Authenticate With Resource Owner Password Grant and MFA](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa).

### Retrieve enrolled authenticators

To challenge the user, you need the `authenticator_id` for the factor you want to challenge. You can list all enrolled authenticators using the MFA Authenticators endpoint:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/mfa/authenticators' \
    --header 'authorization: Bearer MFA_TOKEN' \
    --header 'content-type: application/json'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/mfa/authenticators");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer MFA_TOKEN");
  request.AddHeader("content-type", "application/json");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/mfa/authenticators"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer MFA_TOKEN")
  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/mfa/authenticators")
    .header("authorization", "Bearer MFA_TOKEN")
    .header("content-type", "application/json")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/mfa/authenticators',
    headers: {authorization: 'Bearer MFA_TOKEN', 'content-type': 'application/json'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer MFA_TOKEN",
                             @"content-type": @"application/json" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/mfa/authenticators"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/mfa/authenticators",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MFA_TOKEN",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = {
      'authorization': "Bearer MFA_TOKEN",
      'content-type': "application/json"
      }

  conn.request("GET", "/{yourDomain}/mfa/authenticators", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/mfa/authenticators")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer MFA_TOKEN'
  request["content-type"] = 'application/json'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer MFA_TOKEN",
    "content-type": "application/json"
  ]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/mfa/authenticators")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

You will get a list of authenticators with the following format:

```json lines theme={null}
[
    {
        "id": "recovery-code|dev_O4KYL4FtcLAVRsCl",
        "authenticator_type": "recovery-code",
        "active": true
    },
    {
        "id": "sms|dev_NU1Ofuw3Cw0XCt5x",
        "authenticator_type": "oob",
        "active": true,
        "oob_channel": "sms",
        "name": "XXXXXXXX8730"
    },
        {
        "id": "voice|dev_NU1Ofuw3Cw0XCt5x",
        "authenticator_type": "oob",
        "active": true,
        "oob_channel": "voice",
        "name": "XXXXXXXX8730"
    }
]
```

### Challenge user with OTP

To trigger a challenge, `POST` to the MFA Challenge endpoint using the corresponding `authenticator_id` and the `mfa_token`.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/mfa/challenge' \
    --header 'content-type: application/json' \
    --data '{ "client_id": "{yourClientId}",  "client_secret": "{yourClientSecret}", "challenge_type": "oob", "authenticator_id": "sms|dev_NU1Ofuw3Cw0XCt5x", "mfa_token": "{mfaToken}" }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/mfa/challenge");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{ "client_id": "{yourClientId}",  "client_secret": "{yourClientSecret}", "challenge_type": "oob", "authenticator_id": "sms|dev_NU1Ofuw3Cw0XCt5x", "mfa_token": "{mfaToken}" }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/mfa/challenge"

  	payload := strings.NewReader("{ "client_id": "{yourClientId}",  "client_secret": "{yourClientSecret}", "challenge_type": "oob", "authenticator_id": "sms|dev_NU1Ofuw3Cw0XCt5x", "mfa_token": "{mfaToken}" }")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/mfa/challenge")
    .header("content-type", "application/json")
    .body("{ "client_id": "{yourClientId}",  "client_secret": "{yourClientSecret}", "challenge_type": "oob", "authenticator_id": "sms|dev_NU1Ofuw3Cw0XCt5x", "mfa_token": "{mfaToken}" }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/mfa/challenge',
    headers: {'content-type': 'application/json'},
    data: {
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      challenge_type: 'oob',
      authenticator_id: 'sms|dev_NU1Ofuw3Cw0XCt5x',
      mfa_token: '{mfaToken}'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"client_id": @"{yourClientId}",
                                @"client_secret": @"{yourClientSecret}",
                                @"challenge_type": @"oob",
                                @"authenticator_id": @"sms|dev_NU1Ofuw3Cw0XCt5x",
                                @"mfa_token": @"{mfaToken}" };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/mfa/challenge"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/mfa/challenge",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "client_id": "{yourClientId}",  "client_secret": "{yourClientSecret}", "challenge_type": "oob", "authenticator_id": "sms|dev_NU1Ofuw3Cw0XCt5x", "mfa_token": "{mfaToken}" }",
    CURLOPT_HTTPHEADER => [
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "client_id": "{yourClientId}",  "client_secret": "{yourClientSecret}", "challenge_type": "oob", "authenticator_id": "sms|dev_NU1Ofuw3Cw0XCt5x", "mfa_token": "{mfaToken}" }"

  headers = { 'content-type': "application/json" }

  conn.request("POST", "/{yourDomain}/mfa/challenge", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/mfa/challenge")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request.body = "{ "client_id": "{yourClientId}",  "client_secret": "{yourClientSecret}", "challenge_type": "oob", "authenticator_id": "sms|dev_NU1Ofuw3Cw0XCt5x", "mfa_token": "{mfaToken}" }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/json"]
  let parameters = [
    "client_id": "{yourClientId}",
    "client_secret": "{yourClientSecret}",
    "challenge_type": "oob",
    "authenticator_id": "sms|dev_NU1Ofuw3Cw0XCt5x",
    "mfa_token": "{mfaToken}"
  ] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/mfa/challenge")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

### Complete authentication using received code

If success, you receive the following response:

```json lines theme={null}
{
  "challenge_type": "oob",
  "oob_code": "asdae35fdt5...",
  "binding_method": "prompt"
}
```

Your application needs to prompt the user for the 6-digit code sent in the message and should be set in the `binding_code` parameter. You can verify the code and get authentication tokens using the OAuth0 Token endpoint, specifying the `binding_code` and `oob_code` returned by the previous call:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=http://auth0.com/oauth/grant-type/mfa-oob \
    --data 'client_id={yourClientId}' \
    --data 'client_secret={yourClientSecret}' \
    --data 'mfa_token={mfaToken}' \
    --data 'oob_code={oobCode}' \
    --data binding_code=USER_OTP_CODE
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D&binding_code=USER_OTP_CODE", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D&binding_code=USER_OTP_CODE")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D&binding_code=USER_OTP_CODE")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'http://auth0.com/oauth/grant-type/mfa-oob',
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      mfa_token: '{mfaToken}',
      oob_code: '{oobCode}',
      binding_code: 'USER_OTP_CODE'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=http://auth0.com/oauth/grant-type/mfa-oob" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_secret={yourClientSecret}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&mfa_token={mfaToken}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&oob_code={oobCode}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&binding_code=USER_OTP_CODE" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D&binding_code=USER_OTP_CODE",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D&binding_code=USER_OTP_CODE"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=http%3A%2F%2Fauth0.com%2Foauth%2Fgrant-type%2Fmfa-oob&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&mfa_token=%7BmfaToken%7D&oob_code=%7BoobCode%7D&binding_code=USER_OTP_CODE"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/x-www-form-urlencoded"]

  let postData = NSMutableData(data: "grant_type=http://auth0.com/oauth/grant-type/mfa-oob".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&client_secret={yourClientSecret}".data(using: String.Encoding.utf8)!)
  postData.append("&mfa_token={mfaToken}".data(using: String.Encoding.utf8)!)
  postData.append("&oob_code={oobCode}".data(using: String.Encoding.utf8)!)
  postData.append("&binding_code=USER_OTP_CODE".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

If the call was successful, you'll receive a response in the format below, containing the access token:

```json lines theme={null}
{
  "id_token": "eyJ...i",
  "access_token": "eyJ...i",
  "expires_in": 600,
  "scope": "openid profile",
  "token_type": "Bearer"
}
```

**Note:** SMS and invalid code returns are subject to rate limiting. SMS codes can be sent 10 times and refill once per hour, while invalid codes can be returned 10 times and refill once every six minutes.

## Customize MFA

<Warning>
  Customizable MFA with the Resource Owner Password Grant, Embedded, or Refresh Token flows is in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0’s release stages, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To participate in the early access, contact [Auth0 Support](https://support.auth0.com/).
</Warning>

Customizable MFA allows users to enroll and challenge with factors of their choice that are supported by your application.

During authentication at the `oauth/token` endpoint, the response returns the `mfa_required` error that includes the `mfa_token` to use the MFA API and the `mfa_requirements` parameter with a list of authenticators:

```json theme={null}
{
  "error": "mfa_required",
  "error_description": "Multifactor authentication required",
  "mfa_token": "Fe26...Ha",
  "mfa_requirements": {
    "challenge": [
      { "type": "otp" },
      { "type": "push-notification" },
      { "type": "phone" },
      { "type": "recovery-code" }
      { "type": "email"} //can only work with challenge
    ]
  }
}
```

Use the `mfa_token` to call the [`mfa/authenticator`](/docs/api/authentication/muti-factor-authentication/list-authenticators) endpoint for a list of all factors the user has enrolled and match the same type your application supports.  You also need to obtain the matching `authenticator_type` to issue challenges:

```json theme={null}
[
  {
    "type": "recovery-code",
    "id": "recovery-code|dev_qpOkGUOxBpw6R16t",
    "authenticator_type": "recovery-code",
    "active": true
  },
  {
    "type": "otp",
    "id": "totp|dev_6NWz8awwC8brh2dN",
    "authenticator_type": "otp",
    "active": true
  }
]
```

Enforce the MFA challenge by calling the [`request/mfa/challenge`](/docs/api/authentication/muti-factor-authentication/request-mfa-challenge) endpoint.

Further customize your MFA flow with Auth0 Actions. To learn more, read [Actions Triggers: post-challenge - API Object](/docs/customize/actions/explore-triggers/password-reset-triggers/post-challenge-trigger/post-challenge-api-object).

## Learn more

* [Manage Authentication Factors with Authentication API](/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis/manage-authenticator-factors-mfa-api)
* [Configure SMS and Voice Notifications for MFA](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-sms-voice-notifications-mfa)
* [Challenge with Recovery Codes](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/challenge-with-recovery-codes)
* [Enroll and Challenge Email Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-email-authenticators)
* [Enroll and Challenge OTP Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-otp-authenticators)
* [Enroll and Challenge Push Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-push-authenticators)


# Import User MFA Authenticator Enrollments
Source: https://auth0.com/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/import-user-mfa-authenticator-enrollments

Describes how to import MFA enrollments for your existing users.

You can import a user's <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> enrollments with [automatic migration](/docs/manage-users/user-migration/configure-automatic-migration-from-your-database) and [bulk user imports](/docs/manage-users/user-migration/bulk-user-imports). The supported enrollment types are:

* Email: for email verification.
* Phone: for SMS verification.
* OTP: for One-Time Passwords (OTPs) used with authenticator applications, such as Google Authenticator.

Importing MFA enrollments provides a seamless user experience, since users won't have to re-enroll after migration.

The classic login experience does not support factor selection for users with multiple factors. If you plan to import users with multiple registered factors, consider using the [Universal Login](/docs/authenticate/login/auth0-universal-login) experience.

## Schema

The schema applies to MFA factors for both of the following workflows.

```json lines expandable theme={null}
{
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "totp": {
                "type": "object",
                "properties": {
                "secret": {
                    "type": "string",
                        "pattern": "^[A-Z2-7]+$",
                        "description": "The OTP secret is used for MFA authentication with Google Authenticator type apps. It must be supplied in un-padded Base32 encoding, such as: JBTWY3DPEHPK3PNP"
                    },
                },
                "additionalProperties": false,
                "required": ["secret"],
            },
            "phone": {
                "type": "object",
                "properties": {
                "value": {
                    "type": "string",
                    "pattern": "^\\+[0-9]{1,15}$",
                    "description": "The phone number for SMS or Voice MFA. The phone number should include a country code and begin with +, such as: +12125550001"
                },
                },
                "additionalProperties": false,
                "required": ["value"],
            },
            "email": {
                "type": "object",
                "properties": {
                    "value": {
                        "type": "string",
                        "format": "email",
                        "description": "The email address for MFA"
                    },
                },
                "additionalProperties": false,
                "required": ["value"],
            },
        },
        "maxProperties": 1,
        "additionalProperties": false,
    },
    "minItems": 1,
    "maxItems": 10
}
```

## Automatic migration

MFA enrollments can also be imported during an [automatic migration](/docs/authenticate/database-connections/custom-db/overview-custom-db-connections#automatic-migration-scenario). This can be accomplished by providing any existing enrollments in the `mfa_factors` field of the user that is provided to the callback at the end of your custom DB [login script](/docs/authenticate/database-connections/custom-db/templates/login).

Any failures will appear in your tenant logs as failed logins, and will be distinguishable from other failures by their description: `Unable to import MFA factors`. For example:

```json lines theme={null}
{
  "_id": "5e9df3b29ebabe00571c04a7",
  "date": "2020-04-20T19:10:42.916Z",
  "type": "fu",
  "description": "Unable to import MFA factors.",
  "connection": "Username-Password-Authentication",
  "connection_id": "con_mMkvaycgzgCS0p0z",
  "client_id": "aCbTAJNi5HbsjPJtRpSP6BIoLPOrSj2Cgg",
  "client_name": "All Applications",
  "ip": "10.12.13.1",
  "client_ip": null,
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.149 Safari/537.36",
  "details": {
    "error": {
      "message": "Unable to import MFA factors."
    }
  },
  "user_name": "test@test.io",
  "strategy": "auth0",
  "strategy_type": "database"
}
```

## Bulk user import

1. Prepare a `users.json` file. See [bulk user imports](/docs/manage-users/user-migration/bulk-user-imports) for details.
2. Include existing MFA enrollments for each user.
3. Start a bulk user import.
4. Update the factors of any existing users by enabling the `upsert` option in your initial request.
5. Once the import job completes, check the response for any errors. If any of the users' MFA factors failed to import, you will see errors such as:

When using the `upsert` option, any non-MFA related updates to existing users will have been applied to the user's profile. For example, the following error summary shows the user's `picture` attribute was successfully set to `http://example.org/jdoe.png`, however we were unable to import the provided MFA factors. In cases like this, it is safe to retry the import for failed users.

```json lines expandable theme={null}
[
  {
    "user": {
      "email": "antoinette@contoso.com",
      "picture": "http://example.org/jdoe.png",
      "mfa_factors": [
        {
          "totp": {
            "secret": "2PRXZWZAYYDAWCD"
          }
        },
        {
          "phone": {
            "value": "+15551112233"
          }
        },
        {
          "email": {
            "value": "antoinette@antoinette.biz"
          }
        }
      ]
    },
    "errors": [
      {
        "code": "MFA_FACTORS_FAILED",
        "message": "Unable to import factors"
      }
    ]
  }
]
```

## Recovery codes

Auth0 does not provide a way to import recovery codes. When the user's MFA factors are imported, they won't have a recovery code.

To provide users a recovery code, you can check if they have one enrolled, and if not, use the [Recovery Code Regeneration endpoint](https://auth0.com/docs/api/management/v2#!/Users/post_recovery_code_regeneration) to generate a new one.

## Learn more

* [Configure Automatic Migration from Your Database](/docs/manage-users/user-migration/configure-automatic-migration-from-your-database)
* [Bulk User Imports](/docs/manage-users/user-migration/bulk-user-imports)


# Configure Cisco Duo Security for MFA
Source: https://auth0.com/docs/secure/multi-factor-authentication/configure-cisco-duo-for-mfa

Describes how to configure Cisco Duo Security for MFA.

<Card title="Before you start">
  * Configure your Duo account. For more information, read [Getting Started on Duo Docs](https://duo.com/docs/getting-started#getting-started).
  * Create a [Duo Security Web SDK integration](https://duo.com/docs/duoweb) and record the **Integration Key**, **Secret Key,** and **API hostname** credentials.
</Card>

Cisco Duo is a multi-faceted authentication provider and can only be used on your Auth0 tenant if all other factors are disabled. Your Duo account can support push notifications, SMS, OTP, phone callback, and more based on your configuration.

You cannot also enable Duo if other factors are enabled. Duo is only available to users when it is the sole factor enabled.

The application will prompt the user for the second factor with Duo, listing the options you have enabled in your Duo account.

Your users can download Duo from [Google Play](https://play.google.com/store/apps/details?id=com.duosecurity.duomobile) or the [App Store](https://itunes.apple.com/us/app/duo-mobile/id422663827?mt=8) for use as a second factor.

## Configure Duo

To configure Duo Security, you must pass your Duo credentials to your application in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

1. Go to [Dashboard > Security > Multi-factor Auth > Duo Security](https://manage.auth0.com/#/security/mfa/duo) and enable it.
2. Enter the information in the fields to link your Duo account to Auth0.
3. Select **Save**.

## Use Actions to enable Duo

To enable Duo within an Action, pass `duo` as the `provider` parameter when you enable <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip>.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  api.multifactor.enable('duo', { allowRememberBrowser: false });
};
```

Duo does not provide an option for "Remember Me" behavior. The 30-day MFA session is hard-coded to remember the user after the initial login.

To force your users to log in with Duo every time, create a rule with `allowRememberBrowser: false`.

## Actions template for Duo

This template provides an example and starting point to trigger multi-factor authentication with [Duo Security](http://duosecurity.com/) when a condition is met.

Upon first login, the user can enroll the device.

<Callout icon="file-lines">
  You need to create two integrations in Duo Security: one of type **Web SDK** and one of type **Admin SDK**.
</Callout>

<AuthCodeBlock />

## Current limitations

* You cannot use [Auth0 MFA Enrollment Tickets](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/create-custom-enrollment-tickets) to enroll users with Duo. Onboard those users from Duo itself.
* If you use <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>, you must enable Duo in an Action with `provider` set to `duo` as described previously. You can conditionally use Duo or the built-in Auth0 provider for specific applications.

## Learn more

* [Troubleshoot Multi-Factor Authentication Issues](/docs/troubleshoot/authentication-issues/troubleshoot-mfa-issues)


# Configure Recovery Codes for MFA
Source: https://auth0.com/docs/secure/multi-factor-authentication/configure-recovery-codes-for-mfa

How to configure recovery codes for multi-factor authentication.

A recovery code is a unique code, generated by Auth0, allowing a user to regain account access. So if a user cannot access the device or account used for <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA) enrollment, they can use a recovery code to authenticate.

## How it works

When using <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> with recovery codes enabled:

1. A user starts MFA enrollment.
2. Auth0 generates a recovery code.
3. During MFA enrollment the user is shown the recovery code prompt.
4. The user saves the recovery code and completes the enrollment process.
5. Now the user can complete MFA with the recovery code they saved if they lose access to their device or account they enrolled for MFA.

<Frame>
  <img alt="Example recovery code prompt during multi-factor authentication enrollment" />
</Frame>

When using Universal Login with recovery codes disabled:

* Users will not see the recovery code prompt during MFA enrollment.
* Users cannot authenticate with a recovery code.

## Enable recovery codes

Recovery codes are disabled by default. You can enable recovery codes by going to [Dashboard > Security > Multifactor Auth](https://manage.auth0.com/#/security/mfa).

## Learn more

* [Challenge with Recovery Codes](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/challenge-with-recovery-codes)


# Customize Multi-Factor Authentication Pages
Source: https://auth0.com/docs/secure/multi-factor-authentication/customize-mfa

Learn how to customize multi-factor authentication (MFA) pages that appear to users with Universal Login branding options.

<Callout icon="file-lines">
  These customizations do not apply to Duo, which has its own user interface.
</Callout>

You can customize the <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> pages that appear to your users by adjusting the <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> branding options in the [Universal Login Settings](https://manage.auth0.com/#/login_settings) section of the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

If you are using the Universal Login experience, you can customize the page using its flow customization options.

You can also customize the full HTML content to reflect your organization's particular user experience requirements. To learn more, read [MFA Widget Theme Options](/docs/secure/multi-factor-authentication/customize-mfa/mfa-widget-theme-options).

With the Universal Login Experience, MFA is presented even more simply to the user. Once they have entered their credentials to log in, they are presented with the MFA screen. If they have no MFA factor enrolled, they will be asked to enroll, and if they do, they will be asked to present their MFA credential.

## Use the MFA API

Auth0 provides an [MFA API](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/mfa-api) for the following scenarios:

* [Authenticate users with the Resource Owner Password Grant](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa).
* Build an interface to [let users manage their own authentication factors](/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis/manage-authenticator-factors-mfa-api).
* Invite users to enroll in MFA using [enrollment tickets](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/create-custom-enrollment-tickets).

To use the MFA API, you must enable the MFA grant type for your application. To enable the MFA grant in the Auth0 Dashboard:

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and select your application.
2. At the bottom of the **Settings** tab, click **Advanced Settings**.
3. Click the **Grant Types** tab and select **MFA**.

   <Frame>
     <img alt="Dashboard Applications Applications Advanced Settings Grant Types tab" />
   </Frame>

   To learn more, read [Enable Multi-Factor Authentication](/docs/secure/multi-factor-authentication/enable-mfa).
4. Click **Save Changes**.

### Limitations

The MFA API is designed to work with SMS, push notifications within the Guardian application, email, and OTP factors. It does not support enrolling with Duo.

## Customize MFA policy with Actions

You can use Actions to customize the MFA policy for your tenant, including requiring MFA for users of specific applications, users with specific user metadata or IP ranges, and more.

If you're unfamiliar with creating Actions, read [Write Your First Action](/docs/customize/actions/write-your-first-action).

<Callout icon="file-lines">
  Any and all MFA-related behavior defined in Actions take precedence over the **Define policy** settings configured in the **Multi-Factor Auth** section of the Dashboard.

  To learn more, read [Enable Multi-Factor Authentication](/docs/secure/multi-factor-authentication/enable-mfa).
</Callout>

When writing Actions, you can use the `provider` setting to specify whether to force MFA, and which factor you use. The behavior is different depending on whether you use the Classic or the Universal Login experience:

<table>
  <thead>
    <tr>
      <th>Provider</th>
      <th>Classic Experience</th>
      <th>New Experience</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>any</td>
      <td>Push, SMS, or OTP</td>
      <td>Push, SMS, Voice, OTP, Email, or WebAuthN security key (when enabled)</td>
    </tr>

    <tr>
      <td>guardian</td>
      <td>Push, SMS, or OTP</td>
      <td>Push, SMS, OTP, or Email</td>
    </tr>

    <tr>
      <td>google-authenticator</td>
      <td>Google Authenticator</td>
      <td>Push, SMS, OTP, or Email</td>
    </tr>

    <tr>
      <td>duo</td>
      <td>Duo</td>
      <td>Duo</td>
    </tr>
  </tbody>
</table>

If you are using Universal Login you can get the behavior of the Classic Login experience if you enable customization of the MFA login page.

<Callout icon="file-lines">
  The `guardian` and `google-authenticator` options are legacy settings that are kept for backward compatibility reasons, and should not be used moving forward. We recommend using `any` instead. The `google-authenticator` option does not let users enroll a recovery code.
</Callout>

Setting the `provider` to a specific option manually overrides the enabled/disabled toggles in the Dashboard. You can use the following Action to prompt the user to enroll in Duo even if other factors are enabled in the Dashboard:

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
    // Forcing the provider to Duo programmatically
    api.multifactor.enable('duo')
}
```

## Common use case examples

Here are some common contextual MFA scenarios that can be handled by Actions.

<Callout icon="file-lines">
  To ensure that your tenant triggers MFA only when you explicitly require it in your Actions, set your tenant's default MFA policy to **Never**.

  For more information, read the "Policies" section in [Multi-Factor Authentication Factors](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors#policies).
</Callout>

### Require MFA for specific applications

You can customize MFA to only trigger when users are logging in to to specific applications.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
	const CLIENTS_WITH_MFA = [
		'{yourClientId1}', 
		'{yourClientId2}',
		'{yourClientId3}'
	];

	if (CLIENTS_WITH_MFA.includes(event.client.client_id)) {
		api.multifactor.enable('duo', { allowRememberBrowser: false })
	}
}
```

### Require MFA for specific users

You can customize MFA to only trigger for users who are marked to use MFA.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  if (event.user.user_metadata && event.user.user_metadata.use_mfa) {
    api.multifactor.enable('duo', { allowRememberBrowser: false });
  }
}
```

### Change frequency of MFA prompts

In some scenarios, you may not want to prompt the user for MFA each time they log in from the same browser. You can alter that behavior by using the `allowRememberBrowser` property:

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {  
  api.multifactor.enable('any', { allowRememberBrowser: false });
}
```

Depending on the property value the behavior will be as follows:

<table>
  <thead>
    <tr>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>true</code></td>
      <td>When provider is set to <code>google-authenticator</code> or <code>duo</code>, the user is prompted for MFA once every 30 days. When provider is set to <code>guardian</code>, the MFA prompt displays the enrollment checkbox for users to choose whether or not to enroll. Defaults to <code>false</code>. To learn more, read <a href="/docs/secure/multi-factor-authentication/customize-mfa ">Customize Multi-Factor Authentication Pages </a></td>
    </tr>

    <tr>
      <td><code>false</code></td>
      <td>The user is prompted for MFA each time they authenticate.</td>
    </tr>
  </tbody>
</table>

The time values are for active users. If a user is inactive for a period of seven days or more, their cookie will expire and they will be prompted for MFA on their next login attempt (regardless if `allowRememberBrowser` is set to `true` and it has not been 30 days since their last MFA prompt).

When you allow the user to skip MFA, a cookie is stored in the user's browser. If the user has the cookie set but you still want to require MFA, you have two options:

* Set `allowRememberBrowser` to `false`
* Set `acr_values` to `http://schemas.openid.net/pape/policies/2007/06/multi-factor` when calling the `/authorize` endpoint.

In situations where a user loses a trusted device, you can prompt the specific user for MFA during their next login by calling the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> [Invalidate Remember Browser](https://auth0.com/docs/api/management/v2#!/Users/post_invalidate_remember_browser) endpoint.

### Require MFA for users outside of the network

Assuming that access to the specified network of internal IP addresses is well controlled, you can also have Auth0 request MFA only from users whose requests originate from outside the corporate network:

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const ipaddr = require('ipaddr.js@1.9.0');
  const corp_network = '192.168.1.134/26';
  const current_ip = ipaddr.parse(event.request.ip);

  if (!current_ip.match(ipaddr.parseCIDR(corp_network))) {
    api.multifactor.enable('any', {allowRememberBrowser: false});
  }
}
```

### Bypass MFA for refresh token requests

If your users report frequent log-outs, you may need to bypass <Tooltip href="/docs/glossary?term=refresh+token">refresh token</Tooltip> requests while using MFA. You can alter the default behavior with a filter Action on the `event.transaction.protocol` object property.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  if (event.transaction.protocol !== 'oauth2-refresh-token') {
    // MFA-related commands here
    api.multifactor.enable('any');
  }
};
```

To learn more about the Action `event` object, read [Actions Triggers: post-login - Event Object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object).

## Learn more

* [Customize MFA for Classic Login](/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-classic-login)
* [Authenticate Using the Resource Owner Password Flow with MFA](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa)
* [Auth0 MFA API](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/mfa-api)
* [Manage Authentication Factors with Authentication API](/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis/manage-authenticator-factors-mfa-api)
* [MFA Widget Theme Options](/docs/secure/multi-factor-authentication/customize-mfa/mfa-widget-theme-options)
* [MFA Theme Language Dictionary](/docs/secure/multi-factor-authentication/customize-mfa/mfa-theme-language-dictionary)


# Customize MFA for Classic Login
Source: https://auth0.com/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-classic-login

Learn how to customize MFA when using Classic Login.

You can enable <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> in the [Dashboard > Security > Multi-factor Auth](https://manage.auth0.com/#/security/mfa) section. You can customize the MFA pages using basic branding options on the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. For further customization, you can provide your own HTML for the MFA page. When using your own HTML, Classic Login uses the Auth0 MFA Widget with the following limitations:

* It does not support MFA with email.
* If users enrolled in more than one factor, they cannot select which one to use. The MFA widget will ask them to login with the most secure factor.
* It does not use <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> internationalization features. To learn more, read [Universal Login Internationalization](/docs/customize/internationalization-and-localization/universal-login-internationalization).

## Customize HTML for the MFA page

To customize the MFA page, go to [Dashboard > Branding > Universal Login > Multi-factor Authentication](https://manage.auth0.com/#/mfa_page) tab and enable the **Customize MFA Page** toggle. You can then use the text editor to change your HTML, style your page using CSS, and alter the JavaScript used to retrieve custom variables. Once you've made your changes, and make sure to click **Save Changes**.

MFA pages work without customization and Auth0 will update the included scripts as required. However, once you enable customization, you are responsible for updating and maintaining the script (including changing version numbers, such as that for the MFA Widget) since Auth0 can no longer update it automatically.

To learn more about how to override the text for many areas of the MFA process for Classic Login, read [MFA Theme Language Dictionary](/docs/secure/multi-factor-authentication/customize-mfa/mfa-theme-language-dictionary). To learn more about the MFA Widget theme options, read [MFA Widget Theme Options](/docs/secure/multi-factor-authentication/customize-mfa/mfa-widget-theme-options).

## Reset page

If you'd like to revert to an earlier design, you have two options:

* Revert to the last saved template by clicking **Reset to Last**;
* Revert to the default template provided by Auth0 by clicking **Reset to Default**.

## Render enrollment invitations

There are two different possible scenarios in which the page is rendered. If a user has been directed to this page specifically for enrollment (for instance, from an email with an enrollment link) then the property `ticket` will be available. Otherwise, the property `requestToken` will be available.

## HTML and Liquid syntax

The hosted page uses Liquid syntax for templating. To learn more, read [Liquid for Designers](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers) on GitHub. The following parameters are available to assist in rendering your page:

* `userData.email`
* `userData.friendlyUserId`
* `userData.tenant`
* `userData.tenantFriendlyName`
* `iconUrl`

Most of the parameters that are used in the MFA Widget need to be passed to Guardian as shown in the default template provided in the customization area. If you need a higher level of customization you could use [auth0-guardian.js](https://github.com/auth0/auth0-guardian.js/tree/master/example).

To learn more, read [Customize MFA User Pages](/docs/secure/multi-factor-authentication/customize-mfa).

## Learn more

* [MFA Theme Language Dictionary](/docs/secure/multi-factor-authentication/customize-mfa/mfa-theme-language-dictionary)
* [MFA Widget Theme Options](/docs/secure/multi-factor-authentication/customize-mfa/mfa-widget-theme-options)
* [Customize Multi-Factor Authentication Pages](/docs/secure/multi-factor-authentication/customize-mfa)


# Customize MFA Enrollments for Universal Login
Source: https://auth0.com/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-enrollments-universal-login

Customize MFA flows using post-login Actions to prompt users to enroll in specific factors.

Auth0 supports a variety of factors for securing user access with [multi-factor authentication (MFA](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors)). Using `post-login` Actions, you can customize your <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> flows to prompt users to enroll in specific factors. After a user enrolls in a factor, they can use that factor as a secondary method of authentication in future logins.

You can also use contextual information to further customize your MFA enrollment flows. For example, you can prompt users to enroll in SMS for one application while prompting them to enroll in push notifications or WebAuthN for a different application.

This feature allows you to customize your MFA enrollment flows. If you want to customize MFA flows for users who are already enrolled, review [Customize MFA Selection for Universal Login](/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-selection-universal-login).

## How it works

You can use [Actions](/docs/customize/actions) to customize your MFA enrollment flows. Specifically, you can modify the `post-login` trigger of the [Login Flow](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) with the following Authentication API methods:

* `enrollWith`: Specifies the default factor presented to users during enrollment. Optionally, you can provide an alternative list of factors for users to choose from. If provided, a Try Another Method link displays on the enrollment prompt.
* `enrollWithAny`: Specifies a set of factors users can choose from during enrollment. By default, this method presents a selection prompt that allows users to choose their desired factor. In some cases, the user experience may vary:

  * If two or more factors have been specified, the selection prompt displays to the user.
  * If the user has already enrolled in all specified factors except one, the selection prompt is skipped, and the user is prompted to enroll in the remaining factor.
  * If the user has already enrolled in all specified factors, the command fails, and the login sequence continues.

You can use a combination of these methods to customize your MFA enrollment flows. You can also incorporate user metadata, such as roles or last login date, to create more tailored experiences.

Customized enrollment flows support the following factors:

* `otp`
* `recovery-code`
* `push-notification`
* `phone`

  * `preferredMethod: voice`
  * `preferredMethod: sms`
  * `preferredMethod: both`
* `webauthn-platform`
* `webauthn-roaming`

After a user enrolls in a factor, its value is added to their `enrolledFactors`. This property represents the list of active factors associated with their user account.

The array `event.authentication.methods` includes a `type` field when the name of the method is set to `mfa`. This field contains factor values (string) that match those used by the `type` field from `enrolledFactors`.

When an MFA enrollment occurs, `methods` contains the object of `name:mfa` with `type` set to the factor used for that event. `methods` and `enrolledFactors` are only updated when an Action first begins. You can access the results of an enrollment event in the next Action of the flow.

To learn more, review the following resources:

* [Actions Triggers: post-login - Event Object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object)
* [Actions Triggers: post-login - API Object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object)

### Sequenced and contextual flows

With the `enrollWith` or `enrollWithAny` commands, you can use contextual information to determine the best enrollment or series of enrollments to present to users.

* The `enrollWith` command supports an initial or default factor and a list of alternatives. Users can only enroll in one factor per command.
* The `enrollWithAny` command supports a list of factors. The specified order of factors determines how the list displays to users. Users can only enroll in one factor per command.

With these commands, you can leverage the following:

* **Sequenced flows**: Enroll users with a series of factors in a specific order.
* **Contextual flows**: Determine which factor to prompt the user with based on metadata or previous commands in the flow.

To help illustrate these flows, consider the following example:

```javascript lines expandable theme={null}
// Action 1

exports.onExecutePostLogin = async (event, api) => {
  if (event.user.enrolledFactors.length) {
    // already enrolled, challenge
    api.authentication.challengeWithAny(event.user.enrolledFactors.map(m => ({type: m.type})));
    if (event.user.app_metadata.isAdmin &&
        !event.user.enrolledFactors.some(m => m.type === 'webauthn-roaming')) {
          // if is admin and doesn't have a security key, meaning a different factor was used, enroll now
          api.authentication.enrollWith({type: 'webauthn-roaming'})
        }
  }
  else {
    // not enrolled; choose a factor to enroll now
    api.authentication.enrollWithAny([{type: 'webauthn-roaming'}, {type: 'otp'}]);
    if (event.user.app_metadata.isAdmin) {
      // one more factor for admins
      api.authentication.enrollWithAny([{type: 'webauthn-roaming'}, {type: 'otp'}]);
    }
  }
};

// Action 2

exports.onExecutePostLogin = async (event, api) => {
  function performed(type) {
    return event.authentication.methods.some(m => m.name === 'mfa' &&
           m.type === type &&
           Date.now() - new Date(m.timestamp).getTime() < 5000)
  }
  if (event.user.app_metadata.isAdmin) {
      // enforce both factors are used by challenging the one that has not been used yet
      if (!performed('webauthn-roaming')) {
        api.authentication.challengeWith({type: 'webauthn-roaming'})
      }
      else if (!performed('otp')) {
        api.authentication.challengeWith({type: 'otp'})
      }
  }
};
```

These two Actions combine to create a scenario where users **without** the admin role are required to enroll with either a one-time password (OTP) or a security key. Conversely, users **with** the admin role must enroll in both factors.

Action 1 reviews the `app_metadata` to determine if the user is an admin, then prompts them to enroll in specific factors. If an admin user has only enrolled in OTP, they are first challenged with OTP to complete their authentication. They are then prompted to enroll with security keys (`webauthn-roaming`).

<Callout icon="file-lines">
  To keep user accounts secure, users must complete an MFA challenge using one of their existing enrolledFactors before they can enroll in additional factors. This condition ensures you can safely implement a custom MFA enrollment policy after an application with different factors and configurations has already been used.
</Callout>

The flow pauses after Action 1 executes, and both `event.user.enrolledFactors` and `event.authentication.methods` will be updated when Action 2 runs. This allows the Action code to make decisions based on actual user data when users are given a choice to challenge or enroll in different factors.

**Note**: This method of executing Actions only applies to those containing `enrollWith` or `enrollWithAny` commands. Actions serving other purposes are not affected.

## Before you begin

Before you can customize your MFA flows, you must set up MFA in your tenant and enable the Customize MFA Factors using Actions setting. You can enable one or more factors and define your MFA policies on your <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> under [Security > Multi-factor Auth](https://manage.auth0.com/#/security/mfa).

* To learn more about the setup process, review [Enable Multi-Factor Authentication](/docs/secure/multi-factor-authentication/enable-mfa).
* For information about configuring specific factors, review [Multi-factor Authentication Factors](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors).

To customize your flows, you must enable the Customize MFA Factors using Actions toggle in the Additional Settings section. Your customized flows will not work properly if this setting is not enabled.

<Frame>
  <img alt="Auth0 Dashboard > Security > Multi-factor Auth > Additional Settings" />
</Frame>

**Note**: Actions with `enrollWith` or `enrollWithAny` commands override any existing policies or rules that enable or disable MFA in a tenant.

## Customize MFA enrollment flows

After setting up MFA for your tenant, you can create `post-login` Actions to customize your MFA enrollment flows.

<Warning>
  Actions (or series of Actions) in a tenant can only execute **four** of the following commands per user flow:

  * `enrollWith`
  * `enrollWithAny`
  * `challengeWith`
  * `challengeWithAny`

  If this limit is exceeded (i.e., a fifth command of this type attempts to execute), an authentication error will occur.
</Warning>

### Create your post-login Action

You can create Actions through the Auth0 Dashboard:

1. Navigate to [Actions > Flows](https://manage.auth0.com/#/actions/flows) and select **Login**.
2. In the Add Action panel, select the **plus sign (+)** icon and choose **Build from scratch**.
3. On the Create Action popup:

   * Enter a name for your Action.
   * Select **Login / Post-Login** as the trigger.
   * Use **Node 22 (Recommended)** for the runtime.
4. Review the popup to ensure accuracy. Then, select **Create**.
5. In the code editor, add your custom code to the `onPostExecute` command.
6. When your command is ready, select **Deploy**.
7. Select **Add to Flow** on the successful deployment notification.

   * **Note**: If the notification closes, choose **Back to Flow** above the code editor.
8. Drag and drop your new command from the Add Action panel into your Login flow. Then, select **Apply**.

To make additional changes after saving, navigate to [Actions > Library > Custom](https://manage.auth0.com/#/actions/library) and select your Action. You can then update and redeploy your code as needed.

### Test your post-login Action

To ensure your commands function appropriately, you can test your Action through the Auth0 Dashboard:

1. Navigate to [Authentication > Authentication Profile](https://manage.auth0.com/#/authentication-profiles).
2. Select **Try** to open a sample login prompt in a new tab.
3. Enter your credentials and test your new MFA flow.

If the flow is successful, a confirmation screen displays. If you encounter any issues, you can update your code by navigating to [Actions > Library > Custom](https://manage.auth0.com/#/actions/library) in your Auth0 Dashboard.

## Sample use case

The example below outlines a common use case for customizing MFA enrollment flows.

### Prompt users with MFA options for enrollment

The following sample challenges users with OTP by default. If desired, users can access the Try Another Method link to authenticate with email instead.

## Troubleshooting

In the event that you experience errors or unexpected results from your customized MFA enrollments, you can use the information below to help identify and resolve these issues.

### Tenant Logs

You can monitor your customized MFA enrollments through [tenant logs](/docs/deploy-monitor/logs).

Tenant logs are available in the Auth0 Dashboard under [Monitoring > Logs](https://manage.auth0.com/#/logs). Alternatively, you can retrieve logs using the [Management API](https://auth0.com/docs/api/management/v2/introduction).

If you or your users experience unexpected behavior, review tenant logs for the following event codes to learn more:

<table>
  <thead>
    <tr>
      <th>Scenario</th>
      <th>Event</th>
      <th>Error Message</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>A user is prompted to enroll with a specific factor. However, the requested factor meets one of the following conditions:<br /><ul><li>The factor is not enabled in your tenant.</li><li>The factor is not supported by the user's browser.</li><li>The user has already enrolled in the requested factor.</li></ul>In this scenario, the user can complete the flow if alternative factors are available.</td>
      <td>w</td>
      <td>An MFA enrollment is used in a PostLogin action, but the requested factor `${factor.name}` is not properly set up. Enable the requested factor and ensure the user is not already enrolled with it.</td>
    </tr>

    <tr>
      <td>A user is prompted to enroll with one or more factors, but the supplied factors cannot be used for enrollment. In this case, the user cannot complete the flow.</td>
      <td>mfar</td>
      <td>An MFA enrollment is used in a PostLogin action but the requested factors are not properly set up. To perform MFA, enable the requested factors and ensure the user is not already enrolled with them.</td>
    </tr>

    <tr>
      <td>A user attempts to enroll in a new factor without completing at least one challenge using an existing enrollment.</td>
      <td>mfar</td>
      <td>An MFA enrollment was requested but the user is already enrolled in MFA. Challenge with at least one existing factor before enrolling a new one.</td>
    </tr>
  </tbody>
</table>

### Troubleshooting checklist

The following checklist provides additional suggestions for identifying and resolving common issues with customized MFA flows.

1. The **Customize MFA factors with Actions** toggle must be enabled.

   * Navigate to [Auth0 Dashboard > Security > Multi-factor Auth](https://manage.auth0.com/#/security/mfa) and ensure the toggle in the Additional Settings section is enabled.
2. Factors referenced in your Actions must be enabled in your tenant.

   * **Review your code**: Navigate to [Auth0 Dashboard > Actions > Library > Custom](https://manage.auth0.com/#/actions/library) and review your Actions code. Ensure all factors referenced are applicable to your use cases.
   * **Review your factors**: Navigate to [Auth0 Dashboard > Security > Multi-factor Auth](https://manage.auth0.com/#/security/mfa) and ensure all factors referenced in your Actions are enabled.
3. Ensure your Actions have been deployed and saved in your Pipeline.

   1. Navigate to [Auth0 Dashboard > Actions > Library > Custom](https://manage.auth0.com/#/actions/library). Locate your Action in the list and ensure its status is **Deployed**. If a different status is listed, access your Action, review your code, and click **Deploy** to the top right.
   2. Navigate to [Auth0 Dashboard > Actions > Library > Flows](https://manage.auth0.com/#/actions/flows) and select **Login**. Ensure your Action is listed in the flow. If not, access the **Custom tab** of the Add Action panel and drag and drop your Action into your Login flow. Then, select **Apply**.
4. Ensure you've upgraded to the latest version of `post-login` Actions.

   * Navigate to [Auth0 Dashboard > Actions > Library > Custom](https://manage.auth0.com/#/actions/library) and select your Action. If your Action is out-of-date, you will see a yellow banner prompting you to update the Action. If the banner displays, select **Update**.
   * You can also specify the latest version of `post-login` Actions for deployment when using the Deploy CLI. For more information, review [Configure the Deploy CLI](/docs/deploy-monitor/deploy-cli-tool/configure-the-deploy-cli).


# Customize MFA Selection for Universal Login
Source: https://auth0.com/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-selection-universal-login

Customize MFA flows using post-login Actions to challenge users with specific factors or sequences of factors.

Auth0 supports a variety of factors for securing user access with [multi-factor authentication (MFA)](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors). Using `post-login` Actions, you can customize your <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> flows to challenge users with a specific factor or sequence of factors. You can also use contextual information about users and their organizations to create more individualized experiences. For example, you can customize your flows to challenge users with specific factors based on their membership in certain Organizations or their assigned user roles.

<Callout icon="file-lines">
  * This feature allows you to customize your MFA selection flows. If you want to customize your MFA enrollment flows, review [Customize MFA Enrollments in Universal Login](/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-enrollments-universal-login).
  * You can only customize MFA flows with Actions if you are using [Universal Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience).
  * Some methods detailed can only be used on Universal Login and not Classic Login. For more information, read [Customize MFA for Classic Login](/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-classic-login).
</Callout>

## How it works

You can use [Actions](/docs/customize/actions) to customize your MFA flows. Specifically, you can modify the `post-login` trigger of the [Login Flow](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) with the following Authentication API methods:

* `challengeWith`: Specifies the factor or factors users must use to authenticate, such as a one-time password (OTP). This method presents a default challenge to users and can optionally provide access to a factor picker that allows them to choose a different authentication method.
* `challengeWithAny`: Sets a group of factors users can choose from when authenticating, such as email and OTP. By default, this method presents a factor picker to users rather than a specific challenge, in accordance with the following conditions:

  * If two or more factors are specified, a factor picker displays to the user.
  * If the user has only enrolled in one of the specified factors (or only one factor is supplied), the factor picker is skipped.
  * If the user has not enrolled in any of the specified factors, the command fails.

You can use a combination of these methods to tailor your MFA flows as needed. You can also incorporate user metadata, such as roles or previously used factors, into these methods to create more tailored flows.

When choosing MFA challenges for your commands, you can use the factors listed below or the `enrolledFactors` value. `enrolledFactors` represents the list of active factors associated with a user's account.

* `otp`
* `email`
* `push-notification`

  * `otpFallback`
* `phone`

  * `preferredMethod: voice`
  * `preferredMethod: sms`
  * `preferredMethod: both`
* `webauthn-platform`
* `webauthn-roaming`

The array `event.authentication.methods` includes a `type` field when the name of the method is set to `mfa`. type is a string that contains factor values matching those used by the `type` field from `enrolledFactors` (listed above). When an MFA challenge is performed, `methods` contains an object of `name:mfa` with `type` set to the factor used for that challenge. `methods` is only updated when an Action begins. To see the results of a challenge, `methods` must be accessed in the next Action in the flow.

To learn more, review the following resources:

* [Actions Triggers: post-login - Event Object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object)
* [Actions Triggers: post-login - API Object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object)

### Sequenced and contextual flows

With the `challengeWith` or `challengeWithAny` commands, you can use contextual information to determine the best challenge or series of challenges to present to users. Specifically, you can leverage the following:

* **Sequenced flows**: Challenge users with a series of different factors in a specific order.
* **Contextual flows**: Determine which factor to next challenge the user with based on previous challenges in the flow.

To help illustrate these flows, consider the following example:

```javascript lines theme={null}
// ACTION 1 

exports.onExecutePostLogin = async (event, api) => {

   api.authentication.challengeWithAny([{ type: 'phone'}, { type: 'push-notification' }]);

} 

// ============================================ 

// ACTION 2 

// Decide based on what the user did in the previous action 

exports.onExecutePostLogin = async (event, api) => { 

    if(event.authentication.methods.find(m => m.type === 'phone') && event.authorization?.roles.includes('admin')) { 

        api.authentication.challengeWith({ type: 'push-notification' }); 

    }

}
```

In this scenario, a user is first challenged with SMS via the `challengeWithAny` command in Action 1. Then, Action 2 challenges the user with a push notification because they have the Admin user role and also completed the SMS challenge.

In this flow, you can make decisions about which factor to challenge the user with due to the following:

1. The flow pauses after executing Action 1.
2. The user completes the MFA flow prompted by Action 1.
3. `event.authentication.methods.type` in Action 2 populates with information from the previous MFA challenge.
4. The flow resumes to execute Action 2 using contextual information from Action 1.

While this example presents a similar experience to using redirects in your Actions, commands using `challengeWith` and `challengeWithAny` offer the following unique benefits:

* Flows pause after each command, allowing you to accumulate user information that can be used in subsequent Actions. Comparatively, redirects only occur a single time as the final command in a flow.
* MFA is triggered after each Action containing `challengeWith` or `challengeWithAny` commands is executed. With redirects, MFA runs as the final Action in the pipeline.

**Note**: This method of executing Actions only applies to those containing `challengeWith` or `challengeWithAny` commands. Actions serving other purposes are not affected.

## Before you begin

Before you can customize your MFA flows, you must first enable MFA in your tenant and prompt your users to enroll in the appropriate factors.

### Prepare your tenant

To get started, set up MFA in your tenant and enable the Customize MFA Factors using Actions setting. You can set up one or more factors and define your MFA policies on the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> under [Security > Multifactor Auth](https://manage.auth0.com/#/security/mfa).

* To learn more about the setup process, review [Enable Multi-Factor Authentication](/docs/secure/multi-factor-authentication/enable-mfa).
* For information about configuring specific factors, review [Multi-factor Authentication Factors](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors).

To customize your flows, you **must enable** the Customize MFA Factors using Actions toggle in the Additional Settings section. Your customized flows will not work properly if this setting is not enabled.

<Frame>
  <img alt="Auth0 Dashboard > Security > Multi-factor Auth > Additional Settings" />
</Frame>

<Callout icon="file-lines">
  * Actions invoking `challengeWith` and `challengeWithAny` commands override any challenges enabled via[api.multifactor.enable](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object). They also take precedence over the MFA settings available under **Define Policies**.
  * To ensure users complete MFA when attempting to access your application, set the **Require Multi-factor Auth** setting to either **Use Adaptive MFA** or **Always**. In the event your Actions code does not run, this setting serves as a backup and prevent users from bypassing MFA.
  * If you wish to use risk assessors in your commands, enable the **Adaptive MFA Risk Assessment** toggle and use [event.authentication.riskAssessment](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object) in your `post-login` Actions code.
</Callout>

### Enroll users in factors

Once MFA is configured, ensure your users enroll in one or more of the factors you enabled. Users must enroll in authenticators before they can be challenged by `post-login` Action commands.

After a user signs up or is created in your tenant, you can create enrollments with the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> [authentication-methods](https://auth0.com/docs/api/management/v2/users/post-authentication-methods) endpoint, or you can manage users' enrollments directly through their profile pages in the Auth0 Dashboard.

## Customize your MFA flows

Once your tenant is ready, you can create `post-login` Actions to customize your MFA flows. Steps and example use cases are provided below.

<Warning>
  Actions (or series of Actions) in a tenant can only execute **four** of the following commands per user flow:

  * `enrollWith`
  * `enrollWithAny`
  * `challengeWith`
  * `challengeWithAny`

  If this limit is exceeded (i.e., a fifth command of this type attempts to execute), an authentication error will occur.
</Warning>

### Create your post-login Action

1. On your Auth0 Dashboard, navigate to [Actions > Flows](https://manage.auth0.com/#/actions/flows) and select **Login**.
2. Under Add Action, select **Custom** and choose **Create Action**.
3. On the Create Action popup:

   * Enter a name for your Action.
   * Select **Login / Post-Login** as the trigger.
   * Use **Node 22 (Recommended)** for the runtime.
4. Review the popup to ensure accuracy. Then, select **Create**.
5. After creation, the code editor displays the `onPostExecute` command. Add your custom code or code sample to the command.
6. When your command is ready, select **Deploy**.
7. Select **Add to Flow** on the successful deployment notification.

   * **Note**: If the notification has closed, choose **Back to Flow** above the code editor.
8. Drag and drop your new command from the Add Action panel into your Login flow. Then, select **Apply**.

To make additional updates to your Action, navigate to [Actions > Library > Custom](https://manage.auth0.com/#/actions/library) and select your command. You can then update and redeploy your code as needed.

<Warning>
  When adding a redirect to your MFA flow, ensure your Action meets the following conditions to prevent users from skipping or bypassing MFA:

  * The redirect (`sendUserTo`) command must be in a separate Action from your MFA commands.
  * The redirect Action must be the last Action executed in your flow.

  For more information about redirects, review [Redirect with Actions](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/redirect-with-actions).
</Warning>

### Test your post-login Action

To ensure your commands function appropriately, you can test your Action through the Auth0 Dashboard:

* Navigate to [Authentication > Authentication Profile](https://manage.auth0.com/#/authentication-profiles).
* Select **Try** to open a sample login prompt in a new tab.
* Enter your credentials and test your new MFA flow.

If the flow is successful, a confirmation screen displays. If you encounter any issues, you can update your code by navigating to [Actions > Library > Custom](https://manage.auth0.com/#/actions/library) on your Auth0 Dashboard.

## Example use cases

The examples below outline common use cases for customizing MFA flows.

### Use current enrollments to determine challenge method

The following sample challenges a user with MFA if they are enrolled with the following factors:

* One-time password (OTP)
* Phone

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {

 api.authentication.challengeWithAny([{type: 'otp'}, {type: 'phone'}]);

}
```

### Use roles to determine challenge method

The following sample challenges all users with OTP. If a user has the Admin role and requires a higher level of access to your application, they are challenged with an additional factor as a form of [step-up authentication](/docs/secure/multi-factor-authentication/step-up-authentication).

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
    api.authentication.challengeWith({type: 'otp'});

    const isAdmin = event.authorization?.roles.includes('admin');
    if(isAdmin) {
        api.authentication.challengeWith({type: 'phone'});
    }
}
```

### Use metadata to determine challenge method

In this example, MFA factors are enabled at the [Organization](/docs/manage-users/organizations) level. This sample uses different categories of metadata to determine the right challenge for individual users:

* **Organization metadata**: Organization-level data, such as the specific factors enabled for an Organization.
* **User metadata**: User-level data, such as whether a user has a phone number associated with their profile.

```js lines expandable theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const orgFactors = event.organization?.metadata.factors.split(',') ?? [];

  // Get the intersection of factors available for the user and factors enabled for the org
  const availableFactors = orgFactors.filter(f => event.user?.enrolledFactors?.some(ef => ef.type === f));

  // Prefer push if available
  if(availableFactors.includes('push-notification')) {
    api.authentication.challengeWith({ type: 'push-notification' });
    return;
  }

  // If the user has a verified phone number and the organization
  // allows for SMS and email, prefer SMS and allow email as a fallback
  // if available
  if(event.user.phone_number && 
     event.user.phone_verified && 
     availableFactors.includes('phone')) {
    if(availableFactors.includes('email')) {
      api.authentication.challengeWith({ type: 'phone' }, {
        additionalFactors: [{
          type: 'email'
        }]
      });
    } else {
      api.authentication.challengeWith({ type: 'phone' });
    }

    return;
  }

  // If push-notifications and/or phone couldn't be prioritized, fallback to email if
  // enabled for the org, otherwise fail.
  if(availableFactors.includes('email')) {
    api.authentication.challengeWith({ type: "email" });
    return;
  }

  api.access.deny("No MFA factors available for this org + user");
};
```

### Allow users to select an alternate method of authentication

For a more flexible experience, you can present users with a **Try Another Method** link as part of their MFA challenge. This link allows users to select a different method of authentication than the default challenge.

To achieve this, include the `additionalFactors` parameter in your Actions code. You can set this parameter to a specific factor for all users or use `enrolledFactors` to let users choose their preferred factor.

**Specific Factor**

The following sample challenges users with OTP by default. If desired, users can access the Try Another Method link to authenticate with email instead.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  api.authentication.challengeWith({ type: 'otp' }, 
    { additionalFactors: [{type: 'email'}] })
};
```

**Enrolled Factors**

The following sample challenges users with OTP by default. If desired, users can access the Try Another Method link to authenticate with one of their other enrolled factors.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const enrolledFactors = event.user.enrolledFactors.map((f) => ({type: f.type}));

  api.authentication.challengeWith({ type: 'otp' }, 
    { additionalFactors: enrolledFactors })
};
```

### Use Adaptive MFA to determine when to challenge users

The following example uses [Adaptive MFA](/docs/get-started/auth0-teams/tenant-management) to determine if users should be challenged.

<Tooltip href="/docs/glossary?term=Adaptive+MFA">Adaptive MFA</Tooltip> is a flexible MFA policy that protects your tenant from <Tooltip href="/docs/glossary?term=bad+actors">bad actors</Tooltip> by assessing potential risk during login transactions and prompting users for additional verification when appropriate.

In this case, users are prompted with MFA if they log in from an unrecognized device and their overall confidence score is low or medium.

```javascript lines expandable theme={null}
/**
* Handler that will be called during the execution of a PostLogin flow.
*
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {
  if (event.authentication?.riskAssessment?.assessments.NewDevice) {

  // Example condition: prompt MFA only based on the NewDevice 
    // confidence level, this will prompt for MFA when a user is logging in 
    // from an unknown device.
    let shouldPromptMfa;

    switch (event.authentication.riskAssessment.assessments.NewDevice.confidence) {
      case 'low':
      case 'medium':
        shouldPromptMfa = true;
        break;
      case 'high':
        shouldPromptMfa = false;
        break;
      case 'neutral':
        // When this assessor has no useful information about the confidence, 
        // do not prompt MFA.
        shouldPromptMfa = false;
        break;
    }

      // It only makes sense to prompt for MFA when the user has at least one 
      // enrolled MFA factor.
    const canPromptMfa = event.user.enrolledFactors?.length > 0;

    if (shouldPromptMfa && canPromptMfa) {
      const enrolledFactors = event.user.enrolledFactors.map((f) => ({type: f.type}));
      api.authentication.challengeWithAny(enrolledFactors);
    }

  }

};
```

### Use Actions to challenge users

You can use Actions to customize MFA flows by modifying the `post-login` trigger of theLogin Flow. This example uses the `phone` method of authentication and `preferredMethod: 'both'`, referring to the active MFA factors associated with a user's account. For more information, refer to [Actions Triggers: post-login - Event Object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object).

```js lines theme={null}
api.authentication.challengeWith({ 
  type: 'phone', 
  options: { preferredMethod: 'both'} 
});
```

## Troubleshooting

In the event that you experience errors or unexpected results from your customized MFA flows, you can use the information below to help identify and resolve these issues.

### Tenant logs

You can monitor your customized MFA flows through [tenant logs](/docs/deploy-monitor/logs).

Tenant logs are available on the Auth0 Dashboard under [Monitoring > Logs](https://manage.auth0.com/#/logs). Alternatively, you can retrieve logs using the [Management API](https://auth0.com/docs/api/management/v2/introduction).

If you or your users experience unexpected behavior, review tenant logs for the following event codes for more information:

<table>
  <thead>
    <tr>
      <th>Scenario</th>
      <th>Event Code</th>
      <th>Descriptive Error</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>A user is prompted with multi-factor authentication, but none of the requested factors can be used as a challenge. In this case, the user cannot complete MFA.</td>
      <td>mfar</td>
      <td>This scenario results in the following error message:<br /><br />An MFA challenge is used in a PostLogin action but the requested factors are not properly set up. To perform MFA, enable the requested factors and ensure the user is enrolled with them.</td>
    </tr>

    <tr>
      <td>A user is prompted with multi-factor authentication, but one of the requested factors cannot be used as a challenge. In this case, the user can complete MFA using a different requested factor.</td>
      <td>w</td>
      <td>This scenario results in the following warning message:<br /><br />An MFA challenge is used in a PostLogin action, but the requested factor \{factor name} is not properly set up. Enable the requested factor and ensure the user is enrolled with it.</td>
    </tr>
  </tbody>
</table>

### Troubleshooting checklist

The following checklist provides additional suggestions for identifying and resolving common issues with customized MFA flows.

1. The **Customize MFA factors with Actions** toggle must be enabled.

   * Navigate to [Auth0 Dashboard > Security > Multi-factor Auth](https://manage.auth0.com/#/security/mfa) and ensure the toggle in the Additional Settings section is enabled.
2. Factors referenced in your Actions must be enabled in your tenant.

   * **Review your code**: Navigate to [Auth0 Dashboard > Actions > Library > Custom](https://manage.auth0.com/#/actions/library) and review your Actions code. Ensure all factors referenced are applicable to your use cases.
   * **Review your factors**: Navigate to [Auth0 Dashboard > Security > Multi-factor Auth](https://manage.auth0.com/#/security/mfa) and ensure all factors referenced in your Actions are enabled.
3. Users must be enrolled in the factors referenced in your Actions.

   * If an individual receives an error, review their user details to ensure they are enrolled in the proper factors. Navigate to [**Auth0 Dashboard > User Management > Users**](https://manage.auth0.com/#/users) and select their name from the list.

     * Review the Multi-factor Authentication section on the **Detail tab** to verify their enrollments. If the user is not enrolled, you can use the **Send an enrollment invitation** link available in this section.
     * Alternatively, verify the user's enrollments through the **Raw JSON tab**. This information can also be retrieved using the [Management API](https://auth0.com/docs/api/management/v2/users/get-authentication-methods). However, it is important to note that the API does not list auto-enrolled authenticators, such as Email factors set up via an email verification link.
   * If users are not enrolled in the appropriate factors, you can create enrollments with the Management API [authentication-methods](https://auth0.com/docs/api/management/v2/users/post-authentication-methods) endpoint. You can also manage users' enrollments directly through their profile pages in the Auth0 Dashboard.
4. Ensure your Actions have been deployed and saved in your Pipeline.

   * Navigate to [Auth0 Dashboard > Actions > Library > Custom](https://manage.auth0.com/#/actions/library). Locate your Action in the list and ensure its status is **Deployed**. If a different status is listed, access your Action, review your code, and click **Deploy** to the top right.
   * Navigate to [Auth0 Dashboard > Actions > Library > Flows](https://manage.auth0.com/#/actions/flows) and select **Login**. Ensure your Action is listed in the flow. If not, access the **Custom tab** of the Add Action panel and drag and drop your Action into your Login flow. Then, select **Apply**.
5. Ensure you've upgraded to the latest version of `post-login` Actions.

   * Navigate to [Auth0 Dashboard > Actions > Library > Custom](https://manage.auth0.com/#/actions/library) and select your Action. If your Action is out-of-date, you will see a yellow banner prompting you to update the Action. If the banner displays, select **Update**.
   * You can also specify the latest version of `post-login` Actions for deployment when using the Deploy CLI. For more information, review [Configure the Deploy CLI](/docs/deploy-monitor/deploy-cli-tool/configure-the-deploy-cli).


# MFA Theme Language Dictionary
Source: https://auth0.com/docs/secure/multi-factor-authentication/customize-mfa/mfa-theme-language-dictionary

Describes the MFA hosted page configuration options for customizing the theme properties of the MFA pages.

## defaultLocation

```js lines theme={null}
return new Auth0MFAWidget({

...

  defaultLocation : ['United Kingdom', 'GB', '+44'],
  
...

})
```

## languageDictionary

The `languageDictionary` can be used to override the text for many areas of the <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> process on the Classic Login experience. You do this with the following format:

```yaml lines theme={null}
languageDictionary:
  optionsCategory:
    option: value
```

Here is an example, modifying the `headerText` attribute in `smsEnrollmentConfirm`:

```js lines theme={null}
return new Auth0MFAWidget({

...

  languageDictionary:{ // Use the Language Dictionary option
    smsEnrollmentConfirm:{  // Indicate which category/section you are modifying
      headerText: "Some custom text - In order to confirm enrollment we need to confirm your phone. Please enter the received code." // Provide the new value for the specific attribute you wish to modify
    }
  }

...

})
```

See below for a list of available categories and options.

### languageDictionary options

```js lines expandable theme={null}
defaults: {
  iddleHelpUrl: '#',
  rememberBrowserCheckbox: 'Remember this browser',
  title: 'Login to {tenantName}'
},

downloadApp: {
  headerText: 'Download Auth0 Guardian for free:',
  pushEnrollmentAction: 'I\'ve already downloaded it',
  smsAndTotpEnrollmentActions: 'I\'d rather use <sms>SMS</sms> or <ga>Google Authenticator</ga>',
  pushAndTotpEnrollmentActions: 'I\'d rather use <push>Guardian</push> or <ga>Google Authenticator</ga>',
  pushAndSmsEnrollmentActions: 'I\'d rather use <push>Guardian</push> or <sms>SMS</sms>',
  totpEnrollmentActions: 'I\'d rather use <ga>Google Authenticator</ga>',
  smsEnrollmentActions: 'I\'d rather use <sms>SMS</sms>',
  pushEnrollmentActions: 'I\'d rather use <push>Guardian</push>',
  iosLabel: 'App Store',
  iosUrl: 'https://itunes.apple.com/us/app/auth0-guardian/id1093447833?ls=1&mt=8',
  iosImg: '<svg width="27px" height="33px" viewBox="37 22 27 33" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" class="auth0-mfa-svg-icon"><g stroke="none" stroke-width="1" fill="none" fill-rule="evenodd" transform="translate(37.000000, 22.000000)"><path d="M22.0964148,17.5965957 C22.0594667,13.4821277 25.4586963,11.4804255 25.6141333,11.387234 C23.6890074,8.57489362 20.7051259,8.1906383 19.656563,8.16 C17.1504593,7.89574468 14.7195259,9.66255319 13.4429037,9.66255319 C12.1408,9.66255319 10.1749037,8.18553191 8.05611852,8.22893617 C5.3296,8.27106383 2.7789037,9.85276596 1.37997037,12.3089362 C-1.50708148,17.3170213 0.646103704,24.6765957 3.41211852,28.7246809 C4.79576296,30.707234 6.41256296,32.9208511 8.5288,32.8429787 C10.5991704,32.7574468 11.3725333,31.5204255 13.8709926,31.5204255 C16.3465185,31.5204255 17.0727407,32.8429787 19.2310222,32.7931915 C21.4530074,32.7574468 22.8519407,30.8017021 24.1871704,28.8012766 C25.7861333,26.5289362 26.4282667,24.2910638 26.4537481,24.1761702 C26.4015111,24.1582979 22.1384593,22.5280851 22.0964148,17.5965957 L22.0964148,17.5965957 Z" fill="#FFFFFF"></path><path d="M18.0193778,5.49702128 C19.1329185,4.10170213 19.8948148,2.20340426 19.6833185,0.277021277 C18.0716148,0.348510638 16.0560296,1.39404255 14.8953481,2.7587234 C13.8684444,3.9612766 12.9511111,5.93234043 13.1880889,7.78595745 C14.9985481,7.9212766 16.8574222,6.8706383 18.0193778,5.49702128 L18.0193778,5.49702128 Z" fill="#FFFFFF"></path></g></svg>',
  androidLabel: 'Google Play',
  androidUrl: 'https://play.google.com/store/apps/details?id=com.auth0.guardian',
  androidImg: '<svg width="30px" height="34px" viewBox="35 22 30 34" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" class="auth0-mfa-svg-icon"><g stroke="none" stroke-width="1" fill="none" fill-rule="evenodd" transform="translate(35.000000, 22.000000)"><polygon fill="#ffffff" points="0.0311829399 32.9244984 0.0311829399 1.02956758 16.5681333 17.6173695"></polygon><polygon fill="#ffffff" points="0.60957618 0.0196753921 17.3854403 16.8471259 22.6948251 11.782715"></polygon><polygon fill="#ffffff" transform="translate(11.025248, 26.014581) scale(1, -1) translate(-11.025248, -26.014581)" points="0.60957618 18.1008562 17.3854403 33.9283067 21.4409189 29.8631472"></polygon><path d="M18.3964257,17.493946 L23.8211074,12.6992188 L28.7813766,15.7894686 C29.3871829,16.1668862 29.4042508,16.7930368 28.8086222,17.1953618 L22.3003286,21.5914726 L18.3964257,17.493946 Z" fill="#ffffff"></path></g></svg>'
},

pushAuth: {
  pushSent: {
    useTotpFallback: 'If you haven\'t received the notification,<br></br>just <manualInput>enter the code</manualInput> manually.'
  },

  pushTimeout: {
    resendAction: 'Resend push notification',
    timeoutText: 'Didn\'t receive the push notification?',
    useRecoveryCode: 'Lost your device? <recovery>Use the recovery code</recovery>',
    useTotpFallback: '<manualInput>Enter the code manually</manualInput>'
  }
},

totpAuth: {
  codePlaceholder: 'Enter the 6-digit code',
  headerText: 'Get a verification code from the Google Authenticator (or similar) app:',
  useRecoveryCode: 'Lost your device? <recovery>Use the recovery code</recovery>'
},

smsAuth: {
  codePlaceholder: 'Enter the 6-digit code',
  headerText: 'Enter the 6-digit code we\'ve just sent to your phone.',
  useRecoveryCode: 'Lost your device? <recovery>Use the recovery code</recovery>'
},

guardianTotpAuth: {
  codePlaceholder: 'Enter the 6-digit code',
  headerText: 'Get a verification code from the Auth0 Guardian app.'
},

recoveryCodeAuth: {
  codePlaceholder: 'Enter your code here',
  headerText: 'We will generate a new recovery code<br />once you\'ve logged in:'
},

pushEnrollment: {
  headerText: 'Scan this code with Auth0 Guardian:'
},

enrollmentCongrats: {
  congrats: 'Congratulations, you are all set.<br />In the future when logging in you\'ll want your device handy.',
  continueButtonText: 'Continue'
},

reportRecoveryCode: {
  headerText: 'In the event that you need to login without your device you\'ll need a recovery code. Take a note and keep this somewhere safe:',
  confirmationLabel: 'I have safely recorded this code'
},

generalError: {
  errorsRecoveryHelp: {
    default: 'Looks like something went wrong.<br />Please try logging in again from the application.',

    globalTransactionExpired: 'The login was not successful.<br />Please try again.',

    // Auth0 Server Errors
    guardianInvalidNonce: 'Please try logging in again from the application.',
    guardianInvalidToken: 'Please try logging in again from the application.',
    invalidLoginTokenStatus: 'Please try logging in again from the application.',
    loginTokenInvalidSignature: 'Please try logging in again from the application.',
    loginTokenTransactionExpired: 'Please try logging in again from the application.'
  }
},

smsEnrollmentConfirm: {
  codePlaceholder: 'Enter the 6-digit code',
  headerText: 'In order to confirm enrollment we need to confirm your phone. Please enter the received code.'
},

totpEnrollment: {
  codePlaceholder: 'Enter your passcode here',
  headerText: 'Scan this QR code with Google Authenticator (or similar) app:',
  troubleScanning: 'Trouble Scanning ?'
},

totpEnrollmentCode: {
  codePlaceholder: 'Enter your passcode here',
  headerText: 'Manually enter the following code into your preferred authenticator app and then enter the provided one-time code below.',
  copyCodeButton: 'Copy code'
},

smsEnrollmentAddPhoneNumber: {
  headerText: 'Please enter your phone<br />in order to enroll.',
  phoneNumberLabel: 'A code will be sent to this number:',
  phoneNumberPlaceholder: 'Your phone number'
  // countryCodes: { 'US': 'Translation of United States', ... '<country code>': '<translation>' }
},

authCongrats: {
  congrats: 'We have verified your identity. Redirecting...',
  congratsNoRedirect: 'We have verified your identity.',
  continueButtonText: 'Continue'
},

errorMessages: {
  alreadyEnrolled: 'You are already enrolled, cannot enroll again',
  authMethodDisabled: 'The specified authentication method is disabled',
  connectionError: 'Looks like we cannot contact our server. Please check your internet connection and retry.',
  default: 'Looks like something went wrong. Please retry.',
  defaultRequest: 'Looks like we found a problem contacting our server. Please retry.',
  enrollmentConflict: 'Seems that you have already enrolled. Try logging in again from the application.',
  enrollmentMethodDisabled: 'The specified enrollment method is disabled',
  enrollmentNotFound: 'We couldn\'t find your enrollment. You\'ve probably started enrollment from another device. Finish it there or try logging in again from the application.',
  enrollmentTransactionNotFound: 'The mfa enrollment transaction is not active or has expired. Please try again.',
  errorSendingPushNotification: 'We found an error sending your notification. Please try again.',
  errorSendingPushNotificationManualFallback: 'We could not send the push. Please enter the code manually.',
  errorSendingSms: 'We found an error sending your code. Please try again in a few seconds.',
  errorSendingSmsManualFallback: 'We could not send the sms. Please try the recovery code.',
  featureDisabled: 'This module is currently disabled.',
  featureDisabledByAdmin: 'This module was disabled by the admin.',
  fieldRequired: 'Please fill out required field.',
  globalTransactionExpired: 'Your login attempt has timed out.',
  guardianInvalidNonce: 'There was a problem authenticating your request origin. Have you started too many parallel logins?',
  guardianInvalidToken: 'There was a problem validating authentication request format.',
  insufficientScope: 'Seems that you are not authorized to perform this action.',
  invalidBearerFormat: 'Seems that you are not authorized to perform this action.',
  invalidLoginTokenStatus: 'Unexpected state validating your request.',
  invalidOtp: 'Seems that your code is not valid, please check and retry.',
  invalidOtpFormat: 'OTP Code must have 6 numeric characters',
  invalidPhoneNumber: 'Seems that your phone number is not valid. Please check and retry.',
  invalidRecoveryCode: 'Seems that your recovery code is not valid. Please check and try again.',
  invalidRecoveryCodeFormat: 'Recovery code must have 24 alphanumeric characters',
  invalidToken: 'Seems that you are not authorized to perform this action.',
  loginRejected: 'Auth has been rejected. Try again.',
  loginTokenInvalidSignature: 'We cannot verify who seems to be the issuer for this request',
  loginTokenTransactionExpired: 'Your authentication request is expired. Is your connection slow?',
  loginTransactionNotFound: 'Seems that your device has taken too long to login. Please try again.',
  noMethodAvailable: 'There is currently no authentication method available.',
  noPublicKeyAvailable: 'We cannot verify your identity. Contact tenant admin.',
  pnEndpointDisabled: 'Seems that we cannot deliver messages to your cell phone. Please try again.',
  pushNotificationNotConfigured: 'Seems that enrollment was not finished. Please try logging in again from the application.',
  pushNotificationWrongCredentials: 'Seems that your device credentials are outdated. Please re-enroll your device or wait for them to be updated.',
  smsNotConfigured: 'You cannot use this module because you\'ve enrolled with a different one.',
  // tenant_not_found | The tenant associated cannot be found. Should not normally happen at least that you delete the tenant
  tooManyPn: 'You have exceeded the amount of push notifications per minute. Please wait and try again.',
  tooManyPnPerTenant: 'There are too many push requests right now. Wait a few minutes and try again.',
  tooManySms: 'You have exceeded the amount of SMSs per hour. Wait a few minutes and try again.',
  tooManySmsPerTenant: 'There are too many SMSs right now.  Wait a few minutes and try again.'
  // | transaction_expired | The transaction has already expired |
},

successMessages: {
  auth: 'We have successfully verified your identity. Redirecting...',
  pushSent: 'We\'ve sent a push to: {enrollmentName}',
  smsSent: 'We\'ve sent an sms to: {phoneNumber}'
},

infoMessages: {
  iddle: 'Can we help you?<br></br><iddleHelp>Click here to learn more</iddleHelp>'
}
```

## Learn more

* [MFA Widget Theme Options](/docs/secure/multi-factor-authentication/customize-mfa/mfa-widget-theme-options)
* [Customize MFA for Classic Login](/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-classic-login)


# MFA Widget Theme Options
Source: https://auth0.com/docs/secure/multi-factor-authentication/customize-mfa/mfa-widget-theme-options

Describes the MFA Widget theme options for customizing the theme properties of the MFA pages.

When using your own HTML for <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> pages with Classic Login, it relies on the Auth0 MFA Widget which has the following limitations:

* It does not support MFA with email.
* If users enrolled more than one factor, they cannot select which one to use, the MFA widget prompts them to login with the most secure factor.
* It does not use <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>'s [internationalization](/docs/customize/internationalization-and-localization/universal-login-internationalization) features.

The theme options for the MFA Widget are namespaced under the `theme` property.

<table>
  <thead>
    <tr>
      <th>Option</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>icon</code></td>
      <td>The URL for the imaged used in the header. Default is the Auth0 logo. Recommended height is 58 pixels.</td>
    </tr>

    <tr>
      <td><code>primaryColor</code></td>
      <td>Defines the primary color of the MFA widget. Useful when using a custom <code>icon</code> to ensure complimentary colors appear. Default is <code>#ea5323</code>.</td>
    </tr>
  </tbody>
</table>

## Examples

```js lines theme={null}
return new Auth0MFAWidget({

...

  theme: {
    icon: 'https://example.com/assets/logo.png',
    primaryColor: 'blue'
  },
  
...  
  
})
```

See a [Guardian basic widget example](https://github.com/auth0/auth0-guardian.js/blob/master/example/basic_widget.html) using [auth0-guardian.js](https://github.com/auth0/auth0-guardian.js). See the [readme](https://github.com/auth0/auth0-guardian.js/tree/master/example) for details.

## Learn more

* [Customize MFA for Classic Login](/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-classic-login)
* [MFA Theme Language Dictionary](/docs/secure/multi-factor-authentication/customize-mfa/mfa-theme-language-dictionary)


# FIDO Authentication with WebAuthn
Source: https://auth0.com/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn

Describes Web Authentication API (WebAuthn) and FIDO-based authentication and how it works with Auth0 multi-factor authentication.

The Web Authentication API (also known as WebAuthn) is a [specification](https://www.w3.org/TR/webauthn/) written by the W3C and FIDO, with the participation of Google, Mozilla, Microsoft, Yubico, and others. The API allows users to be authenticated using public key cryptography.

<Warning>
  The WebAuthn RPID is currently limited to a single domain configuration and is incompatible with customers using multiple custom domains.
</Warning>

WebAuthn is the most secure and usable authentication method on the web. Some key reasons for this are:

* It minimizes login friction. A simple and familiar gesture lets users authenticate.
* It's the only web authentication method that is phishing resistant.
* It's standard based and implemented across browsers and operating systems

WebAuthn let users authenticate with two types of authenticators:

* **Roaming authenticators** are removable and cross-platform, like a Yubikey, and can be used on multiple devices. To authenticate with a roaming authenticator, you need to connect it to the device (through USB, NFC, or Bluetooth), provide proof of presence (by touching it, for example), and optionally provide user verification, for example, by entering a PIN.
* **Platform authenticators** are attached to a device and only work on that device. Some examples are MacBook’s TouchBar, Windows Hello, iOS Touch/FaceId, and Android’s fingerprint/face recognition. Biometric data is stored on the device and never sent to the server. When biometrics cannot be used, alternative authentication methods are usually provided. For example, if you are wearing a mask, instead of using Face ID you can enter your passcode.

## WebAuthn and Web Origins

WebAuthn works by generating a private/public key pair for each [web origin](https://en.wikipedia.org/wiki/Same-origin_policy) which are registered in the device or security key.

Since the key pair is bound to the domain, users are protected from phishing attacks. If the attacker tricks them into using WebAuthn in a different domain, the WebAuthn authenticator will not have a key pair for that domain and authentication will fail. The attacker will not get any data that can identify the user.

## Roaming Authenticators

To learn how to enable roaming authenticators in Auth0, check the [WebAuthn with Security Keys](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-security-keys-for-mfa) documentation.

The default enrollment flow for security keys in Android displayed below and has the following steps:

* Users authenticate with username/password.
* They are prompted to select the authentication method they want to enroll.
* If they pick Security Keys, they are shown a list of instructions.
* They are then prompted to enter their security key.
* The device shows their native UI to complete the security key challenge.
* Users can name the key to later identify it, in case they enroll multiple ones.

<Frame>
  <img alt="undefined" />
</Frame>

In the challenge flow, the user is prompted for the security key and then it calls the native user interface for the device, which in this example is Android:

<Frame>
  <img alt="undefined" />
</Frame>

## Platform Authenticators

To learn how to enable platform authenticators, check the [Webauthn with Device Biometrics](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-device-biometrics-for-mfa) documentation.

Given platform authenticators can only be used in a single device, it **should not be the only factors that users enroll.** To make sure users are not locked out from their accounts, Auth0 will prompt users to enroll with platform authenticators after they succesfuly authenticated using another authentication method.

Auth0 will try to **progressively enroll** all users' devices. Users will be prompted to enroll their devices' platform authenticators in each device they use.

The default enrollment flow for Face ID in iOS is displayed below and has the following steps:

* Users authenticate with username/password.
* They enroll another <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> authentication method, like [SMS](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-sms-voice-notifications-mfa), [Push](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-push-notifications-for-mfa) or [Time-Based OTP](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-otp-notifications-for-mfa).
* They name their device, to identify it later.

<Frame>
  <img alt="Device Biometrics MFA Enrollment" />
</Frame>

The next time they login from that device, users enter their username/password and complete MFA with their device biometric authenticator.

<Frame>
  <img alt="WebAuthn Device Biometrics MFA Challenge" />
</Frame>

## WebAuthn as Multi Factor Authentication

<Callout icon="file-lines">
  When users authenticate with WebAuthn, they use something **they have** as an authentication factor: a security key, or a device.

  Both Security Keys and Device Biometrics support **user verification**, which requires users provide something **they know** (a PIN or a passcode) and something **they are** (like biometric traits).

  When using Device Biometrics, user verification is always performed. To perform verification with Security Keys, you [need to configure Auth0](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-security-keys-for-mfa) to require a PIN. Then users will be asked to enter a PIN, which is only stored in the security key, to complete authentication. Now when user verification is performed, users can login with WebAuthn as the only authentication method to achieve multi-factor authentication.

  By using WebAuthn for authentication combined with user verification, you not only replace the password with something much simpler to use, you also remove the need of having another authentication step when requiring MFA.
</Callout>

## Webauthn.me

Auth0 maintains [webauthn.me](https://a0.to/webauthme-auth0-docs), which has [detailed information](https://webauthn.me/introduction) about WebAuthn and an up-to-date list of browsers supporting WebAuthn.

## Learn more

* [Configure WebAuthn with Device Biometrics for MFA](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-device-biometrics-for-mfa)
* [Configure WebAuthn with Security Keys for MFA](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-security-keys-for-mfa)


# Configure WebAuthn with Device Biometrics for MFA
Source: https://auth0.com/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-device-biometrics-for-mfa

Describes how to configure WebAuthn with Device Biometrics

For an introduction to WebAuthn and how Auth0 implements it for both [Security Keys](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-security-keys-for-mfa) and Device Biometrics, check out [FIDO Authentication with WebAuthn](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn).

<Card title="Availability varies by Auth0 plan">
  Both your specific login implementation and your Auth0 plan or custom agreement affect whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

<Warning>
  If you need to set a custom domain, do so **before** rolling out WebAuthn in production environments. If you set or change a custom domain, previously enrolled users will not be able to authenticate.

  You can use the [Relying Party](#configure-relying-party) setting to specify the domain used to authenticate users.
</Warning>

## Use the Dashboard

Enable **WebAuthn with Device Biometrics** by going to [Dashboard > Security > Multifactor Auth](https://manage.auth0.com/#/security/mfa). You'll need to enable an additional factor, as it cannot be the only factor enabled.

## Configure Relying Party

WebAuthn makes phishing impossible by binding the credentials with the browser's origin. Users can't use WebAuthn for a site they did not register too.

Binding credentials to the origin means if you configure a <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip> or change it, users enrolled before the change will not be able to authenticate.

WebAuthn defines a [Relying Party ID attribute](https://www.w3.org/TR/webauthn-2/#relying-party-identifier), which lets you specify the domain used to authenticate users. You can set it to any registrable domain suffix of the browser origin. For example, if the custom domain is `login.example.com`, you can configure the <Tooltip href="/docs/glossary?term=Relying+Party">Relying Party</Tooltip> ID to `example.com`. This lets users authenticate to any `example.com` domain with their WebAuthn credentials.

Auth0 lets you specify the Relying Party ID only if you have a custom domain configured. If the custom domain changes, you must update the Relying Party ID.

## Device recognition

When you enable WebAuthn with Device Biometrics, Auth0 will try to progressively enroll all of an end-user's WebAuthn-capable devices. Browsers with Javascript disabled or without WebAuthn platform authenticator support, won’t get the option to enroll or authenticate with Device Biometrics.

Since there's no deterministic way to know if a specific device was enrolled or not without challenging the user for WebAuthn, Auth0 relies on the user agent to decide what to do. The behavior depends on the operating system.

<Callout icon="file-lines">
  In the most common scenario, where users always use the same browser and have one mobile and one laptop/desktop computer, the nuances in behavior outlined below won't affect the user experience.
</Callout>

### Windows and iOS 14.5+

On Windows and iOS 14.5+, the WebAuthn platform authenticator is registered at the **operating system level.** Users can enroll with one browser and login with any browser. If Auth0 detects that users have a device enrolled, they will get the option to authenticate with Face ID / Touch ID / Windows Hello. If they enrolled with that same device they'll be able to authenticate. If not, it will fail, and they'll need to use another authentication method.

### macOS

On Mac, the WebAuthn platform authenticator is registered at the **browser** system level. Users will be asked to enroll with WebAuthn in each browser they use. If Auth0 detects that the user has enrolled from Chrome on a Mac, they will get the option to authenticate with Touch ID when they login from Chrome on a Mac. If they enrolled from the same Mac, they’ll be able to authenticate.  If no, it will fail, and they'll need to use another authentication method. If they try to enroll from Safari in the same Mac, they will be asked to complete <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> with the other authentication method, and then **prompted to enroll** with Touch ID.

### Android

On Android, **only Chrome** supports WebAuthn platform authenticators. If Auth0 detects that users have an Android device enrolled, they will get the option to authenticate with Android’s Fingerprint/Face Recognition. If they enrolled with that same Android device they'll be able to authenticate. If not, it will fail, and they'll need to use another authentication method.

## Device support

The user must have another MFA enrollment activated before using device biometrics.

To use device biometrics keys, a browser needs to have JavaScript enabled and support WebAuthn Platform Authenticators. If those conditions are not met, Auth0 will not offer the option of enrolling or authenticating with the device. Auth0 will challenge the user with another factor.

The latest versions of popular browsers and operating systems provide support for WebAuthn with Security Keys. For more details, check out the [browser support section in webauthn.me](https://webauthn.me/browser-support).

## Limitations

* There isn't a a way to enroll with WebAuthn device biometrics beyond the Progressive Enrollment prompt.
* When using the [MFA API](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/mfa-api) you can list and remove WebAuthn enrollments, but you cannot enroll them.
* Users can only enroll one device per type using WebAuthn with Device Biometrics (one phone, one tablet, one laptop/desktop). If a user wants to enroll another device of the same type, the first device must be unenrolled.

## Webauthn.me

Auth0 maintains [webauthn.me](https://a0.to/webauthme-auth0-docs), which has [detailed information](https://webauthn.me/introduction) about WebAuthn and an up-to-date list of browsers supporting WebAuthn.

## Learn more

* [Configure WebAuthn with Security Keys for MFA](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-security-keys-for-mfa)


# Configure WebAuthn with Security Keys for MFA
Source: https://auth0.com/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-security-keys-for-mfa

Describes how to configure WebAuthn with Security Keys for MFA.

For an introduction to WebAuthn and how Auth0 implements it for both Security Keys and [Device Biometrics](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-device-biometrics-for-mfa), check out [FIDO Authentication with WebAuthn](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn).

<Card title="Availability varies by Auth0 plan">
  Both your specific login implementation and your Auth0 plan or custom agreement affect whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

<Warning>
  If you need to set a custom domain, do so **before** rolling out WebAuthn in production environments. If you set or change a custom domain, previously enrolled users will not be able to authenticate.

  You can use the [Relying Party](#configure-relying-party) setting to specify the domain used to authenticate users.
</Warning>

## Use the Dashboard

1. Enable **WebAuthn with Security Keys** by going to [Dashboard > Security > Multi-factor Auth](https://manage.auth0.com/#/security/mfa).
2. Configure how you want to handle User Verification. For security keys, the typical user verification prompts users to enter a PIN to complete the WebAuthn challenge.

   1. Never: Users will never be prompted to enter a PIN. This is the default value, and it's usually good enough when using security keys for MFA. Users already entered their password, so already provided some verification.
   2. If supported: Users will be prompted to enter a PIN if they already configured one in the key.
   3. Required: Users will be asked to set a PIN if it's not already set, and they'll be asked to enter it each time. This is the option that offers the highest security. Some browsers don't implement this properly (for example, [Brave](https://brave.com/) on iOS) so the authentication will fail and Auth0 will ask users to use another browser.

Note that only FIDO-2 compliant security keys support user verification. FIDO-1 keys can be used for WebAuthn, but are not usable if you set User Verification to Required.

## Configure Relying Party

WebAuthn makes phishing impossible by binding the credentials with the browser's origin. Users can't use WebAuthn for a site they did not register too.

Binding credentials to the origin means if you configure a <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip> or change it, users enrolled before the change will not be able to authenticate.

WebAuthn defines a [Relying Party ID attribute](https://www.w3.org/TR/webauthn-2/#relying-party-identifier), which lets you specify the domain used to authenticate users. You can set it to any registrable domain suffix of the browser origin. For example, if the custom domain is `login.example.com`, you can configure the <Tooltip href="/docs/glossary?term=Relying+Party">Relying Party</Tooltip> ID to `example.com`. This lets users authenticate to any `example.com` domain with their WebAuthn credentials.

Auth0 lets you specify the Relying Party ID only if you have a custom domain configured. If the custom domain changes, you must update the Relying Party ID.

## Device support

To use security keys, a browser needs to have JavaScript enabled and support WebAuthn. If those conditions are not met, Auth0 will not offer the option of enrolling or authenticating with security keys. Auth0 will challenge with another factor or with a recovery code (if they don't have another factor enrolled).

The latest versions of popular browsers and operating systems provide support for WebAuthn with Security Keys. For more details, read the the [browser support section in webauthn.me](https://webauthn.me/browser-support).

## Limitations

* When using the [MFA API](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/mfa-api) you can list and remove WebAuthn enrollments, but you cannot enroll them.

## Learn more

* [Configure WebAuthn with Device Biometrics for MFA](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-device-biometrics-for-mfa)


# Manage Authentication Factors with APIs
Source: https://auth0.com/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis

Learn how to manage MFA authentication factors with the Authentication API and Management API.

Auth0 provides two different APIs to help you and your users manage <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> authentication factors.

## Auth0 Authentication API

Use the [Authentication API Multi-factor Authentication endpoints](https://auth0.com/docs/api/authentication#multi-factor-authentication) to allow your users to manage their own MFA authentication factors.

This method relies on authenticating using the <Tooltip href="/docs/glossary?term=Resource+Owner">Resource Owner</Tooltip> Password Grant (ROPG) authentication flow. To learn more, read [Manage Authentication Factors with Authentication API](/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis/manage-authenticator-factors-mfa-api).

## Auth0 Management API

Use the [Management API Users endpoints](https://auth0.com/docs/api/management/v2) to manage your users' MFA authentication factors.

This method relies on authenticating using a confidential application. To learn more, read [Manage Authentication Methods with Management API](/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis/manage-authentication-methods-with-management-api).

## Learn more

* [Manage Authentication Methods with Management API](/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis/manage-authentication-methods-with-management-api)
* [Manage Authentication Factors with Authentication API](/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis/manage-authenticator-factors-mfa-api)


# Manage Authentication Methods with Management API
Source: https://auth0.com/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis/manage-authentication-methods-with-management-api

Learn how to use the Auth0 Management API to manage MFA authentication methods for your users.

<Card title="Before you start">
  * Configure a [machine-to-machine (M2M) application](/docs/get-started/auth0-overview/create-applications/machine-to-machine-apps), and [grant it access to the Auth0 Management API](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production) with the following scopes:

    * `create:authentication_methods`
    * `read:authentication_methods`
    * `update:authentication_methods`
    * `delete:authentication_methods`
</Card>

The [Auth0 Management API](https://auth0.com/docs/api/management/v2) provides several endpoints you can use to manage your users' <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> authentication methods.

This method relies on authenticating using a confidential application. To learn more about confidential vs. public applications, read [Confidential and Public Applications](/docs/get-started/applications/confidential-and-public-applications).

## Get all authentication methods

Use the [Gets a list of authentication methods](https://auth0.com/docs/api/management/v2#!/Users/get_authentication_methods) endpoint to get a list of all of the authentication methods a user has either fully or partially enrolled.

This endpoint requires the scope: `read:authentication_methods`.

### Examples

The following request returns a list of all authentication methods for a specified user.

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request GET \
    --url https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods \
    --header 'authorization: Bearer {yourMgmtApiAccessToken}'
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java lines theme={null}
  HttpResponse<String> response = Unirest.get("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods',
    headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C lines theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP lines theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" }

  conn.request("GET", "%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift lines theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

### Responses

For each valid request, the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> will return a response in the JSON format.

```json lines theme={null}
[
  {
    "id": "totp|dev_XXXXXXXXXXXXXXXX",
    "type": "totp",
    "confirmed": true,
    "created_at": "2021-09-23T22:57:30.206Z",
    "last_auth_at": "2021-09-23T22:57:51.652Z"
  }
]
```

## Get a single authentication method

Use the [Gets an authentication method by ID](https://auth0.com/docs/api/management/v2#!/Users/get_authentication_methods_by_authentication_method_id) endpoint to get a single authentication method for a user specified by the authentication method's ID.

This endpoint requires the scope: `read:authentication_methods`.

### Examples

The following request returns a single authentication method for a user based on the specified authentication method's ID.

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request GET \
    --url https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D \
    --header 'authorization: Bearer {yourMgmtApiAccessToken}'
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java lines theme={null}
  HttpResponse<String> response = Unirest.get("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D',
    headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C lines theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP lines theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" }

  conn.request("GET", "%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift lines theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

### Responses

For each valid request, the Management API will return a response in the JSON format.

```json lines theme={null}
{
    "id": "totp|dev_XXXXXXXXXXXXXXXX",
    "type": "totp",
    "confirmed": true,
    "created_at": "2021-09-23T22:57:30.206Z",
    "last_auth_at": "2021-09-23T22:57:51.652Z"
}
```

## Create an authentication method

Use the [Creates an authentication method for a given user](https://auth0.com/docs/api/management/v2#!/Users/post_authentication_methods) endpoint to create an authentication method for a user, including SMS, email, one-time password (OTP), or WebAuthn with security keys. To learn more about available MFA authentication factors, read [Multi-Factor Authentication Factors](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors).

This endpoint requires the scope: `create:authentication_methods`.

<Warning>
  Authentication methods created through this endpoint will be confirmed automatically and available immediately. Verify with the user that the authentication method is configured correctly and is still valid.
</Warning>

### SMS

Send users an OTP over SMS which the user is then prompted to enter before they can finish authenticating.

#### Examples

The following request creates a SMS authentication method for a user.

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request POST \
    --url https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods \
    --header 'authorization: Bearer {yourMgmtApiAccessToken}' \
    --data '{ "type": "phone", "name": "SMS", "phone_number": "+00000000000" }'
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  request.AddParameter("undefined", "{ \"type\": \"phone\", \"name\": \"SMS\", \"phone_number\": \"+00000000000\" }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines expandable theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods"

  	payload := strings.NewReader("{ \"type\": \"phone\", \"name\": \"SMS\", \"phone_number\": \"+00000000000\" }")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java lines theme={null}
  HttpResponse<String> response = Unirest.post("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .body("{ \"type\": \"phone\", \"name\": \"SMS\", \"phone_number\": \"+00000000000\" }")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods',
    headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'},
    data: {type: 'phone', name: 'SMS', phone_number: '+00000000000'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C lines expandable theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" };
  NSDictionary *parameters = @{ @"type": @"phone",
                                @"name": @"SMS",
                                @"phone_number": @"+00000000000" };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP lines expandable theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ \"type\": \"phone\", \"name\": \"SMS\", \"phone_number\": \"+00000000000\" }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ \"type\": \"phone\", \"name\": \"SMS\", \"phone_number\": \"+00000000000\" }"

  headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" }

  conn.request("POST", "%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'
  request.body = "{ \"type\": \"phone\", \"name\": \"SMS\", \"phone_number\": \"+00000000000\" }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift lines expandable theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"]
  let parameters = [
    "type": "phone",
    "name": "SMS",
    "phone_number": "+00000000000"
  ] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

#### Responses

For each valid request, the Management API will return a response in the JSON format.

```json lines theme={null}
{
    "type": "phone",
    "name": "SMS",
    "created_at": "2023-01-01T00:00:00.000Z",
    "phone_number": "user@example.com",
    "id": "phone|dev_XXXXXXXXXXXXXXXX"
}
```

### Email

Send users an OTP over email which the user is then prompted to enter before they can finish authenticating. The email factor is only supported when a user has no other factors available.

#### Examples

The following request creates an email authentication method for a user.

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request POST \
    --url https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods \
    --header 'authorization: Bearer {yourMgmtApiAccessToken}' \
    --data '{ "type": "email", "name": "Email Factor", "email": "user@example.com" }'
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  request.AddParameter("undefined", "{ \"type\": \"email\", \"name\": \"Email Factor\", \"email\": \"user@example.com\" }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines expandable theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods"

  	payload := strings.NewReader("{ \"type\": \"email\", \"name\": \"Email Factor\", \"email\": \"user@example.com\" }")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java lines theme={null}
  HttpResponse<String> response = Unirest.post("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .body("{ \"type\": \"email\", \"name\": \"Email Factor\", \"email\": \"user@example.com\" }")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods',
    headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'},
    data: {type: 'email', name: 'Email Factor', email: 'user@example.com'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C lines expandable theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" };
  NSDictionary *parameters = @{ @"type": @"email",
                                @"name": @"Email Factor",
                                @"email": @"user@example.com" };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP lines expandable theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ \"type\": \"email\", \"name\": \"Email Factor\", \"email\": \"user@example.com\" }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ \"type\": \"email\", \"name\": \"Email Factor\", \"email\": \"user@example.com\" }"

  headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" }

  conn.request("POST", "%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'
  request.body = "{ \"type\": \"email\", \"name\": \"Email Factor\", \"email\": \"user@example.com\" }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift lines expandable theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"]
  let parameters = [
    "type": "email",
    "name": "Email Factor",
    "email": "user@example.com"
  ] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

#### Responses

For each valid request, the Management API will return a response in the JSON format.

```json lines theme={null}
{
    "type": "email",
    "name": "Email Factor",
    "created_at": "2023-01-01T00:00:00.000Z",
    "email": "user@example.com",
    "id": "email|dev_XXXXXXXXXXXXXXXX"
}
```

### One-time passwords (OTP)

Enable users to use an authenticator application, such as Google Authenticator, on their personal device to generate an OTP that changes periodically, which the user is prompted to enter before they finish authenticating.

#### Examples

The following request creates an OTP authentication method for a user.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods \
    --header 'authorization: Bearer {yourMgmtApiAccessToken}' \
    --data '{ "type": "totp", "name": "OTP Application", "totp_secret": "{yourSecret}" }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  request.AddParameter("undefined", "{ "type": "totp", "name": "OTP Application", "totp_secret": "{yourSecret}" }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods"

  	payload := strings.NewReader("{ "type": "totp", "name": "OTP Application", "totp_secret": "{yourSecret}" }")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .body("{ "type": "totp", "name": "OTP Application", "totp_secret": "{yourSecret}" }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods',
    headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'},
    data: {type: 'totp', name: 'OTP Application', totp_secret: '{yourSecret}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" };
  NSDictionary *parameters = @{ @"type": @"totp",
                                @"name": @"OTP Application",
                                @"totp_secret": @"{yourSecret}" };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "type": "totp", "name": "OTP Application", "totp_secret": "{yourSecret}" }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "type": "totp", "name": "OTP Application", "totp_secret": "{yourSecret}" }"

  headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" }

  conn.request("POST", "%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'
  request.body = "{ "type": "totp", "name": "OTP Application", "totp_secret": "{yourSecret}" }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"]
  let parameters = [
    "type": "totp",
    "name": "OTP Application",
    "totp_secret": "{yourSecret}"
  ] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

#### Responses

For each valid request, the Management API will return a response in the JSON format.

```json lines theme={null}
{
    "type": "totp",
    "name": "OTP Application",
    "created_at": "2023-01-01T00:00:00.000Z",
    "email": "user@example.com",
    "id": "totp|dev_XXXXXXXXXXXXXXXX"
}
```

### WebAuthn with security keys

Enable users to use FIDO-compliant security keys (for example, [Yubikey](https://www.yubico.com/) or [Google Titan](https://cloud.google.com/titan-security-key)) to perform multi-factor authentication.

#### Examples

The following request creates a WebAuthn with security keys authentication method for a user.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods \
    --header 'authorization: Bearer {yourMgmtApiAccessToken}' \
    --data '{ "type": "webauthn_roaming", "name": "WebAuthn with security keys", "public_key": "{yourPublicKey}", "key_id": "{yourKeyId}", "relying_party_identifier": "{yourDomain}" }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  request.AddParameter("undefined", "{ "type": "webauthn_roaming", "name": "WebAuthn with security keys", "public_key": "{yourPublicKey}", "key_id": "{yourKeyId}", "relying_party_identifier": "{yourDomain}" }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods"

  	payload := strings.NewReader("{ "type": "webauthn_roaming", "name": "WebAuthn with security keys", "public_key": "{yourPublicKey}", "key_id": "{yourKeyId}", "relying_party_identifier": "{yourDomain}" }")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .body("{ "type": "webauthn_roaming", "name": "WebAuthn with security keys", "public_key": "{yourPublicKey}", "key_id": "{yourKeyId}", "relying_party_identifier": "{yourDomain}" }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods',
    headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'},
    data: {
      type: 'webauthn_roaming',
      name: 'WebAuthn with security keys',
      public_key: '{yourPublicKey}',
      key_id: '{yourKeyId}',
      relying_party_identifier: '{yourDomain}'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" };
  NSDictionary *parameters = @{ @"type": @"webauthn_roaming",
                                @"name": @"WebAuthn with security keys",
                                @"public_key": @"{yourPublicKey}",
                                @"key_id": @"{yourKeyId}",
                                @"relying_party_identifier": @"{yourDomain}" };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "type": "webauthn_roaming", "name": "WebAuthn with security keys", "public_key": "{yourPublicKey}", "key_id": "{yourKeyId}", "relying_party_identifier": "{yourDomain}" }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "type": "webauthn_roaming", "name": "WebAuthn with security keys", "public_key": "{yourPublicKey}", "key_id": "{yourKeyId}", "relying_party_identifier": "{yourDomain}" }"

  headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" }

  conn.request("POST", "%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'
  request.body = "{ "type": "webauthn_roaming", "name": "WebAuthn with security keys", "public_key": "{yourPublicKey}", "key_id": "{yourKeyId}", "relying_party_identifier": "{yourDomain}" }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"]
  let parameters = [
    "type": "webauthn_roaming",
    "name": "WebAuthn with security keys",
    "public_key": "{yourPublicKey}",
    "key_id": "{yourKeyId}",
    "relying_party_identifier": "{yourDomain}"
  ] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

#### Responses

For each valid request, the Management API will return a response in the JSON format.

```json lines theme={null}
{
    "type": "webauthn-roaming",
    "name": "WebAuthn with security keys",
    "relyingPartyIdentifier": "example-tenant.auth0.com",
    "keyId": "X9FrwMfmzj...",
    "publicKey": "bXktcHVibGljLWtle...",
    "created_at": "2023-03-09T17:33:47.545Z",
    "id": "webauthn-roaming|dev_XXXXXXXXXXXXXXXX"
}
```

## Replace all authentication methods

Use the [Updates all authentication methods by replacing them with the given ones](https://auth0.com/docs/api/management/v2#!/Users/put_authentication_methods) endpoint to replace all existing authentication methods with those provided.

This endpoint requires the scope: `update:authentication_methods`.

### Examples

The following request replaces all existing authentication methods for a user.

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request PUT \
    --url https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods \
    --header 'authorization: Bearer {yourMgmtApiAccessToken}' \
    --data '[{ "type": "phone", "preferred_authentication_method": "sms", "phone_number": "+00000000000", "name": "SMS" }]'
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods");
  var request = new RestRequest(Method.PUT);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  request.AddParameter("undefined", "[{ \"type\": \"phone\", \"preferred_authentication_method\": \"sms\", \"phone_number\": \"+00000000000\", \"name\": \"SMS\" }]", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines expandable theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods"

  	payload := strings.NewReader("[{ \"type\": \"phone\", \"preferred_authentication_method\": \"sms\", \"phone_number\": \"+00000000000\", \"name\": \"SMS\" }]")

  	req, _ := http.NewRequest("PUT", url, payload)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java lines theme={null}
  HttpResponse<String> response = Unirest.put("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .body("[{ \"type\": \"phone\", \"preferred_authentication_method\": \"sms\", \"phone_number\": \"+00000000000\", \"name\": \"SMS\" }]")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PUT',
    url: 'https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods',
    headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'},
    data: [
      {
        type: 'phone',
        preferred_authentication_method: 'sms',
        phone_number: '+00000000000',
        name: 'SMS'
      }
    ]
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C lines theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" };
  NSDictionary *parameters = @[ @{ @"type": @"phone", @"preferred_authentication_method": @"sms", @"phone_number": @"+00000000000", @"name": @"SMS" } ];

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"PUT"];
  [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];
  ```

  ```php PHP lines expandable theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_POSTFIELDS => "[{ \"type\": \"phone\", \"preferred_authentication_method\": \"sms\", \"phone_number\": \"+00000000000\", \"name\": \"SMS\" }]",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "[{ \"type\": \"phone\", \"preferred_authentication_method\": \"sms\", \"phone_number\": \"+00000000000\", \"name\": \"SMS\" }]"

  headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" }

  conn.request("PUT", "%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Put.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'
  request.body = "[{ \"type\": \"phone\", \"preferred_authentication_method\": \"sms\", \"phone_number\": \"+00000000000\", \"name\": \"SMS\" }]"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift lines expandable theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"]
  let parameters = [
    [
      "type": "phone",
      "preferred_authentication_method": "sms",
      "phone_number": "+00000000000",
      "name": "SMS"
    ]
  ] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "PUT"
  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()
  ```
</AuthCodeGroup>

### Responses

For each valid request, the Management API will return a response in the JSON format.

```json lines theme={null}
[
  {
    "id": "phone|dev_XXXXXXXXXXXXXXXX",
    "type": "phone",
    "name": "SMS",
    "phone_number": "+00000000000",
    "created_at": "2023-03-09T17:53:23.647Z",
    "preferred_authentication_method": "sms",
    "authentication_methods": [
      {
        "id": "sms|dev_XXXXXXXXXXXXXXXX",
        "type": "sms"
      }
    ]
  }
]
```

## Update a single authentication method

Use the [Updates an authentication method](https://auth0.com/docs/api/management/v2#!/Users/patch_authentication_methods_by_authentication_method_id) endpoint to update a single authentication method for a user.

This endpoint requires the scope: `update:authentication_methods`.

### Examples

The following request updates a single authentication method for a user based on the specific authentication method's ID.

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request PATCH \
    --url https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D \
    --header 'authorization: Bearer {yourMgmtApiAccessToken}' \
    --data '{ "name": "Mobile SMS" }'
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  request.AddParameter("undefined", "{ \"name\": \"Mobile SMS\" }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines expandable theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D"

  	payload := strings.NewReader("{ \"name\": \"Mobile SMS\" }")

  	req, _ := http.NewRequest("PATCH", url, payload)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java lines theme={null}
  HttpResponse<String> response = Unirest.patch("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .body("{ \"name\": \"Mobile SMS\" }")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D',
    headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'},
    data: {name: 'Mobile SMS'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C lines theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" };
  NSDictionary *parameters = @{ @"name": @"Mobile SMS" };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D"]
                                                         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];
  ```

  ```php PHP lines expandable theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "PATCH",
    CURLOPT_POSTFIELDS => "{ \"name\": \"Mobile SMS\" }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ \"name\": \"Mobile SMS\" }"

  headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" }

  conn.request("PATCH", "%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D")

  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["authorization"] = 'Bearer {yourMgmtApiAccessToken}'
  request.body = "{ \"name\": \"Mobile SMS\" }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift lines theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"]
  let parameters = ["name": "Mobile SMS"] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D")! 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()
  ```
</AuthCodeGroup>

### Responses

For each valid request, the Management API will return a response in the JSON format.

```json lines theme={null}
{
    "type": "phone",
    "name": "Mobile SMS",
    "created_at": "2023-01-12T00:03:52.855Z",
    "last_auth_at": "2023-01-12T00:04:05.157Z",
    "phone_number": "+00000000000",
    "preferred_authentication_method": "sms",
    "id": "phone|dev_XXXXXXXXXXXXXXXX",
    "authentication_methods": [
        {
            "id": "phone|dev_XXXXXXXXXXXXXXXX",
            "type": "phone"
        }
    ]
}
```

## Delete all authentication methods

Use the [Deletes all authentication methods for the given user](https://auth0.com/docs/api/management/v2#!/Users/delete_authentication_methods) endpoint to delete all authentication methods for a user.

This endpoint requires the scope: `delete:authentication_methods`.

### Examples

The following request deletes all authentication methods for a user.

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request DELETE \
    --url https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods \
    --header 'authorization: Bearer {yourMgmtApiAccessToken}'
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods");
  var request = new RestRequest(Method.DELETE);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods"

  	req, _ := http.NewRequest("DELETE", url, nil)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java lines theme={null}
  HttpResponse<String> response = Unirest.delete("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'DELETE',
    url: 'https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods',
    headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C lines theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"DELETE"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP lines theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" }

  conn.request("DELETE", "%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Delete.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift lines theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "DELETE"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

### Responses

For each valid request, the Management API will return a response with a `204` status code and empty body.

## Delete a single authentication method

Use the [Deletes an authentication method by ID](https://auth0.com/docs/api/management/v2#!/Users/delete_authentication_methods_by_authentication_method_id) endpoint to delete a single authentication method for a user.

### Examples

The following request deletes a single authentication method for a user based on the specified authentication method's ID.

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request DELETE \
    --url https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D \
    --header 'authorization: Bearer {yourMgmtApiAccessToken}'
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D");
  var request = new RestRequest(Method.DELETE);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D"

  	req, _ := http.NewRequest("DELETE", url, nil)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java lines theme={null}
  HttpResponse<String> response = Unirest.delete("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'DELETE',
    url: 'https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D',
    headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C lines theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"DELETE"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP lines theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" }

  conn.request("DELETE", "%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Delete.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift lines theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://%7ByourDomain%7D/api/v2/users/%7BuserId%7D/authentication-methods/%7BauthenticationMethodId%7D")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "DELETE"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

### Responses

For each valid request, the Management API will return a response with a `204` status code and empty body.

## Learn more

* [Multi-Factor Authentication Factors](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors)
* [Register Machine-to-Machine Applications](/docs/get-started/auth0-overview/create-applications/machine-to-machine-apps)
* [Get Management API Access Tokens for Production](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production)
* [Confidential and Public Applications](/docs/get-started/applications/confidential-and-public-applications)


# Manage Authentication Factors with Authentication API
Source: https://auth0.com/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis/manage-authenticator-factors-mfa-api

Describes how to manage MFA authenticator factor enrollments for applications using the Auth0 MFA API.

<Card title="Before you start">
  * Enable the **MFA** grant type for your application. To learn more, read [Update Grant Types](/docs/get-started/applications/update-grant-types).
</Card>

Auth0 provides several [API endpoints](https://auth0.com/docs/api/authentication#multi-factor-authentication) to help you manage the authenticators you're using with an application for <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA). You can use these endpoints to build a complete user interface that lets users manage their authenticator factors.

## Get MFA API access tokens

To call the MFA API to manage enrollments, you first need to obtain an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> for the MFA API.

To use the MFA API as part of an authentication flow, you can follow the steps detailed in [Authenticate With Resource Owner Password Grant and MFA](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa). If you are building a user interface to manage authentication factors, you'll need to obtain a token you can use for the MFA API at any moment, not only during authentication.

An MFA access token, or an access token with an `https://{yourDomain}/mfa/` <Tooltip href="/docs/glossary?term=audience">audience</Tooltip>, simultaneously authenticates and instigates an MFA [challenge request](https://auth0.com/docs/api/authentication/muti-factor-authentication/request-mfa-challenge). Factor enablement in your tenant and enrollment by your users determine whether the MFA challenge initiates:

* If your tenant allows for multiple factor enrollment and your users enroll in a valid factor (excluding email), such as a one-time password (OTP), the user is issued the MFA challenge upon login.
* If your users are not enrolled with any authentication factors, or are only enrolled with the `email` factor, the MFA token is minted and the user not issued a challenge.

<Callout icon="file-lines">
  The default expiry time of access tokens with the `https://{yourDomain}/mfa/*` audience is 10 minutes. This value cannot be configured.
</Callout>

### Universal Login

If you are using [Universal Login](/docs/authenticate/login/auth0-universal-login), redirect to the Authorize endpoint, specifying the `https://{yourDomain}/mfa/` audience.

<Warning>
  When `https://{yourDomain}/mfa/` is specified as the audience, MFA is enforced. When end users enable **Remember this browser** while `.../mfa/` is specified as audience, the setting will have no effect.

  Auth0 recommends that tenant administrators [create an action](/docs/customize/actions/write-your-first-action) that sets `allowRememberBrowser` to false. This will hide **Remember this browser** from view in the end user's experience.
</Warning>

### Resource owner password grant

If you are using the <Tooltip href="/docs/glossary?term=Resource+Owner">Resource Owner</Tooltip> Password Grant (ROPG), you have 3 options:

* Ask for the `https://{yourDomain}/mfa/` audience when logging-in, and use a [refresh token](/docs/secure/tokens/refresh-tokens) to refresh it later.
* If you need to list and delete authenticators, ask the user to [authenticate again](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa) with `/oauth/token`, specifying the `https://{yourDomain}/mfa/` audience. Users will need to complete MFA before being able to list and/or delete authentication factors.
* If you only need to list authenticators, ask the user to [authenticate again](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa) using `/oauth/token` with username/password. The endpoint will return an `mfa_required` error, and an `mfa_token` you can use to list authenticators. Users will need to provide their password to see their authenticators.

### Scopes

When you request a token for the MFA audience, you can request the following scopes:

<table>
  <thead>
    <tr>
      <th>Scope</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>enroll</code></td>
      <td>To enroll a new authenticator.</td>
    </tr>

    <tr>
      <td><code>read:authenticators</code></td>
      <td>To list existing authenticators.</td>
    </tr>

    <tr>
      <td><code>remove:authenticators</code></td>
      <td>To delete an authenticator.</td>
    </tr>
  </tbody>
</table>

## List authenticators

To get a list of the authenticators for a user, you can call the MFA Authenticators endpoint:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/mfa/authenticators' \
    --header 'authorization: Bearer MFA_TOKEN'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/mfa/authenticators");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer MFA_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/mfa/authenticators"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer MFA_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.get("https://{yourDomain}/mfa/authenticators")
    .header("authorization", "Bearer MFA_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/mfa/authenticators',
    headers: {authorization: 'Bearer MFA_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/mfa/authenticators",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MFA_TOKEN"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer MFA_TOKEN" }

  conn.request("GET", "/{yourDomain}/mfa/authenticators", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/mfa/authenticators")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer MFA_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

You should receive information about the authenticator type(s) in the response:

```json lines theme={null}
[
  {
    "authenticator_type": "recovery-code",
    "id": "recovery-code|dev_IsBj5j3H12VAdOIj",
    "active": true
  },
  {
    "authenticator_type": "otp",
    "id": "totp|dev_nELLU4PFUiTW6iWs",
    "active": true,
  },
  {
    "authenticator_type": "oob",
    "oob_channel": "sms",
    "id": "sms|dev_sEe99pcpN0xp0yOO",
    "name": "+1123XXXXX",
    "active": true
  }
]
```

For the purposes of building a user interface for end users to manage their factors, you should ignore authenticators that have `active` as `false`. Those authenticators are not confirmed by users, so they can't be used to challenge for MFA.

The MFA API will list the following enrollments depending on the authenticator type:

<table>
  <thead>
    <tr>
      <th>Authenticator</th>
      <th>Actions</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Push and OTP</strong></td>
      <td>If push is enabled, Auth0 also creates an OTP enrollment. You will see both when listing enrollments.</td>
    </tr>

    <tr>
      <td><strong>SMS and Voice</strong></td>
      <td>If both SMS and voice are enabled, when a user enrolls with either SMS or voice, Auth0  automatically creates two authenticators for the phone number, one for SMS and another for voice.</td>
    </tr>

    <tr>
      <td><strong>Email</strong></td>
      <td>All verified emails will be listed as authenticators.</td>
    </tr>
  </tbody>
</table>

## Enroll authenticators

See the following links for details on how to enroll authenticators for different factors:

* [SMS or voice](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-challenge-sms-voice-authenticators)
* [One-time password (OTP)](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-otp-authenticators)
* [Push](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-push-authenticators)
* [Email](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-email-authenticators)

You can also use the [Universal Login flow](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/create-custom-enrollment-tickets) for enrolling users at any time.

## Delete authenticators

To delete an associated authenticator, send a `DELETE` request to the MFA Authenticators endpoint replacing the `AUTHENTICATOR_ID` with the relevant authenticator ID. You can get the ID when you list authenticators.

If an `mfa_token` was used to list authenticators, users will need to [complete MFA to obtain an access token](https://auth0.com/docs/api/authentication/muti-factor-authentication/verify-mfa-with-otp) with an audience of `https://{yourDomain}/mfa/` in order to delete an authenticator.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url 'https://{yourDomain}/mfa/authenticators/AUTHENTICATOR_ID' \
    --header 'authorization: Bearer ACCESS_TOKEN'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/mfa/authenticators/AUTHENTICATOR_ID");
  var request = new RestRequest(Method.DELETE);
  request.AddHeader("authorization", "Bearer ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/mfa/authenticators/AUTHENTICATOR_ID"

  	req, _ := http.NewRequest("DELETE", url, nil)

  	req.Header.Add("authorization", "Bearer ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.delete("https://{yourDomain}/mfa/authenticators/AUTHENTICATOR_ID")
    .header("authorization", "Bearer ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'DELETE',
    url: 'https://{yourDomain}/mfa/authenticators/AUTHENTICATOR_ID',
    headers: {authorization: 'Bearer ACCESS_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/mfa/authenticators/AUTHENTICATOR_ID",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer ACCESS_TOKEN"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer ACCESS_TOKEN" }

  conn.request("DELETE", "/{yourDomain}/mfa/authenticators/AUTHENTICATOR_ID", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/mfa/authenticators/AUTHENTICATOR_ID")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Delete.new(url)
  request["authorization"] = 'Bearer ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

If the authenticator was deleted, a 204 response is returned.

When you delete an authenticator, the following actions take place depending on the authenticator type:

<table>
  <thead>
    <tr>
      <th>Authenticator</th>
      <th>Action</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Push and OTP</strong></td>
      <td>When a user enrolls a push authenticator, Auth0 also enrolls OTP. If you delete either of them, the other one will also be deleted.</td>
    </tr>

    <tr>
      <td><strong>SMS and Voice</strong></td>
      <td>When a user enrolls in either SMS or Voice,. Auth0 creates two authenticators, SMS and voice. If you delete either of them, the other will will also be deleted.</td>
    </tr>

    <tr>
      <td><strong>Email</strong></td>
      <td>All verified emails listed as authenticators, but you can't delete them. You can only delete email authenticators that are enrolled explicitly.</td>
    </tr>
  </tbody>
</table>

## Regenerate recovery codes

To delete a recovery code and generate a new one, get an Auth0 [Management API access token](https://auth0.com/docs/api/management/v2/tokens) and use the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> [Recovery Code Regeneration endpoint](https://auth0.com/docs/api/management/v2/#!/Users/post_recovery_code_regeneration).

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/users/USER_ID/recovery-code-regeneration' \
    --header 'authorization: Bearer MANAGEMENT_API_TOKEN'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/USER_ID/recovery-code-regeneration");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer MANAGEMENT_API_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users/USER_ID/recovery-code-regeneration"

  	req, _ := http.NewRequest("POST", url, nil)

  	req.Header.Add("authorization", "Bearer MANAGEMENT_API_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/users/USER_ID/recovery-code-regeneration")
    .header("authorization", "Bearer MANAGEMENT_API_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/users/USER_ID/recovery-code-regeneration',
    headers: {authorization: 'Bearer MANAGEMENT_API_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/USER_ID/recovery-code-regeneration",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MANAGEMENT_API_TOKEN"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer MANAGEMENT_API_TOKEN" }

  conn.request("POST", "/{yourDomain}/api/v2/users/USER_ID/recovery-code-regeneration", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/USER_ID/recovery-code-regeneration")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer MANAGEMENT_API_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```
</AuthCodeGroup>

You will get a new recovery code that the end user will need to capture, for example:

```json lines theme={null}
{  
   "recovery_code": "FA45S1Z87MYARX9RG6EVMAPE"
}
```

## Learn more

* [Enroll and Challenge SMS and Voice Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-challenge-sms-voice-authenticators)
* [Enroll and Challenge OTP Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-otp-authenticators)
* [Enroll and Challenge Push Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-push-authenticators)
* [Enroll and Challenge Email Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-email-authenticators)
* [Challenge with Recovery Codes](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/challenge-with-recovery-codes)


# Multi-Factor Authentication Developer Resources
Source: https://auth0.com/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources

Describes developer resources such as the Auth0 MFA API and the Guardian SDKs for multi-factor authentication (MFA).

Using Auth0 SDKs, you can customize your users' <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA) experience and even build applications on top of our multi-factor capabilities.

## MFA API

[MFA API](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/mfa-api) endpoints allow you to enforce MFA when users interact with the [Token endpoints](https://auth0.com/docs/api/authentication#get-token), as well as enroll and manage MFA factors.

## Create custom MFA pages

Use the following client libraries to customize the look-and-feel of the MFA page so it matches your organization.

* [Auth0 MFA Client library](https://github.com/auth0/auth0-guardian.js)
* [Create Custom MFA Widget](https://github.com/auth0/auth0-guardian.js/tree/master/example)

## Create custom enrollments

You can [customize the enrollment](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/create-custom-enrollment-tickets) process for your users by creating custom enrollment tickets.

## Build custom mobile applications

Build custom Guardian-like applications or add multi-factor functionality into your applications using our SDKs.

* [Guardian for Android](/docs/secure/multi-factor-authentication/auth0-guardian/guardian-for-android-sdk)
* [Guardian for iOS](/docs/secure/multi-factor-authentication/auth0-guardian/guardian-for-ios-sdk)

## Learn more

* [Auth0 Guardian](/docs/secure/multi-factor-authentication/auth0-guardian)
* [Guardian for Android SDK](/docs/secure/multi-factor-authentication/auth0-guardian/guardian-for-android-sdk)
* [Guardian.swift iOS SDK](/docs/secure/multi-factor-authentication/auth0-guardian/guardian-for-ios-sdk)
* [Auth0 MFA API](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/mfa-api)


# Create Custom Enrollment Tickets
Source: https://auth0.com/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/create-custom-enrollment-tickets

Learn how to create an enrollment ticket from the Auth0 MFA API.

If you want to customize and manage your users' [Multi-Factor Authentication (MFA)](/docs/secure/multi-factor-authentication) enrollments, you can use Custom Enrollment Tickets. Auth0's Custom Enrollment Tickets generate a single-use link to direct your users to enroll in <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> with the [factor(s)](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors) you specify.

### Use cases

Use Custom Enrollment Tickets for:

* Onboarding new users
* Configuring user settings
* Specifying factors you want customers to choose during enrollment
* Allowing users to enroll more than one factor

### Configure Custom Enrollment Tickets

Make a post call to <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>'s [`/guardian/post_ticket`](https://auth0.com/docs/api/management/v2#!/Guardian/post_ticket) endpoint.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/guardian/post-ticket' \
    --header 'authorization: Bearer {yourMgmtApiAccessToken}' \
    --header 'content-type: application/json' \
    --data '{ 
   "user_id": "string",
   "email": "user@exampleco.com",
   "send_email": "true",
   "email_locale": "string",
   "factor": "oob",
   "allow_multiple_enrollments": "true"
   }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/guardian/post-ticket");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{ 
   "user_id": "string",
   "email": "user@exampleco.com",
   "send_email": "true",
   "email_locale": "string",
   "factor": "oob",
   "allow_multiple_enrollments": "true"
   }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/guardian/post-ticket"

  	payload := strings.NewReader("{ 
   "user_id": "string",
   "email": "user@exampleco.com",
   "send_email": "true",
   "email_locale": "string",
   "factor": "oob",
   "allow_multiple_enrollments": "true"
   }")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")
  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/guardian/post-ticket")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .header("content-type", "application/json")
    .body("{ 
   "user_id": "string",
   "email": "user@exampleco.com",
   "send_email": "true",
   "email_locale": "string",
   "factor": "oob",
   "allow_multiple_enrollments": "true"
   }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/guardian/post-ticket',
    headers: {
      authorization: 'Bearer {yourMgmtApiAccessToken}',
      'content-type': 'application/json'
    },
    data: {
      user_id: 'string',
      email: 'user@exampleco.com',
      send_email: 'true',
      email_locale: 'string',
      factor: 'oob',
      allow_multiple_enrollments: 'true'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"user_id": @"string",
                                @"email": @"user@exampleco.com",
                                @"send_email": @"true",
                                @"email_locale": @"string",
                                @"factor": @"oob",
                                @"allow_multiple_enrollments": @"true" };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/guardian/post-ticket"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/guardian/post-ticket",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ 
   "user_id": "string",
   "email": "user@exampleco.com",
   "send_email": "true",
   "email_locale": "string",
   "factor": "oob",
   "allow_multiple_enrollments": "true"
   }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ 
   "user_id": "string",
   "email": "user@exampleco.com",
   "send_email": "true",
   "email_locale": "string",
   "factor": "oob",
   "allow_multiple_enrollments": "true"
   }"

  headers = {
      'authorization': "Bearer {yourMgmtApiAccessToken}",
      'content-type': "application/json"
      }

  conn.request("POST", "/{yourDomain}/api/v2/guardian/post-ticket", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/guardian/post-ticket")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'
  request["content-type"] = 'application/json'
  request.body = "{ 
   "user_id": "string",
   "email": "user@exampleco.com",
   "send_email": "true",
   "email_locale": "string",
   "factor": "oob",
   "allow_multiple_enrollments": "true"
   }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer {yourMgmtApiAccessToken}",
    "content-type": "application/json"
  ]
  let parameters = [
    "user_id": "string",
    "email": "user@exampleco.com",
    "send_email": "true",
    "email_locale": "string",
    "factor": "oob",
    "allow_multiple_enrollments": "true"
  ] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/guardian/post-ticket")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Required</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>allow\_multiple\_enrollments</code></td>
      <td>Optional</td>
      <td>Allows a previously enrolled user to enroll with additional factors, excluding email.</td>
    </tr>

    <tr>
      <td><code>factor</code></td>
      <td>Optional</td>
      <td>Specifies which factor the user must enroll with, excluding email. Used with <code>allow\_multiple\_enrollments</code>, can specify more than one factor for enrollment.</td>
    </tr>
  </tbody>
</table>

<Callout icon="file-lines">
  These parameters can only be used with [Universal Login](/docs/authenticate/login/auth0-universal-login) and cannot be used with Classic Login or custom MFA pages.
</Callout>

Management API returns an enrollment ticket containing a `ticket_id` and a `ticket_url`. The `ticket_id` is for internal use. Deliver the `ticket_url` to the user with the `send_email` parameter to kick off the enrollment process. Tickets expire after 5 days and are single-use. A user who receives a ticket will only be able to enroll once.

Sample response:

```json lines theme={null}
{
  "ticket_id": "gten_8b2f5e90d2c848dc9230d34f",
  "ticket_url": "https://guardianadnrdoifcmtest0.eu.auth0.com/guardian/enroll?ticket=gten_8b2f5e90d2c848dc9230d34f"
}
```

If you enable [Multiple Custom Domains](/docs/customize/custom-domains/multiple-custom-domains), you need to include the `auth0-custom-domain` HTTP header. To learn more, review [Multiple Custom Domains](/docs/customize/custom-domains/multiple-custom-domains#customize-email-handling-using-the-management-api).

### Custom Enrollment Tickets with Classic Login

If you are using the [Classic Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/classic-experience) experience and need to customize how the page looks when the user navigates to the `ticket_url`, you can edit the MFA page.

1. Navigate to [Dashboard > Branding > Universal Login > Advanced options > Multi-factor Authentication.](https://manage.auth0.com/#/mfa_page)
2. If **Customize MFA Page** is not selected, toggle this option on.
3. Update the `ticket` variable.
   Example:

```liquid lines theme={null}
{% if ticket %}
<h4 class="message">Welcome, {{ userData.email }}, enroll your device below</h4>
{% else %}
<h4 class="message">Welcome back, {{ userData.email }}, authenticate below</h4>
{% endif %}
```

## Learn more

* [MFA Widget Theme Options](/docs/secure/multi-factor-authentication/customize-mfa/mfa-widget-theme-options)
* [Guardian Error Code Reference](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/guardian-error-code-reference)
* [Auth0 MFA API](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/mfa-api)


# Create Custom MFA Widget
Source: https://auth0.com/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/create-custom-mfa





# Guardian Error Code Reference
Source: https://auth0.com/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/guardian-error-code-reference

Lists Guardian error codes and descriptions.

Use the error codes to display informative messages and to distinguish between recoverable and unrecoverable errors.

<table>
  <thead>
    <tr>
      <th>Error Code</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>invalid\_token</code></td>
      <td>Invalid request or transaction token</td>
    </tr>

    <tr>
      <td><code>insufficient\_scope</code></td>
      <td>You don't have enought grants to perform the requested operation</td>
    </tr>

    <tr>
      <td><code>invalid\_bearer\_format</code></td>
      <td>The bearer put in authentication header was not valid</td>
    </tr>

    <tr>
      <td><code>enrollment\_conflict</code></td>
      <td>There is another enrollment for the same user. You cannot enroll twice.</td>
    </tr>

    <tr>
      <td><code>tenant\_not\_found</code></td>
      <td>The tenant associated cannot be found. Should not normally happen at least that you delete the tenant</td>
    </tr>

    <tr>
      <td><code>login\_transaction\_not\_found</code></td>
      <td>The mfa auth transaction is not active or has already expired</td>
    </tr>

    <tr>
      <td><code>error\_sending\_push\_notification</code></td>
      <td>Push notification delivery failed</td>
    </tr>

    <tr>
      <td><code>push\_notification\_wrong\_credentials</code></td>
      <td>Push notification delivery failed because of wrong credentials</td>
    </tr>

    <tr>
      <td><code>invalid\_otp</code></td>
      <td>Provided otp code was not valid</td>
    </tr>

    <tr>
      <td><code>invalid\_recovery\_code</code></td>
      <td>Provided recovery code was not valid</td>
    </tr>

    <tr>
      <td><code>invalid\_body</code></td>
      <td>Body validation failed. Bad request.</td>
    </tr>

    <tr>
      <td><code>invalid\_query\_string</code></td>
      <td>Query string validation failed. Bad request.</td>
    </tr>

    <tr>
      <td><code>enrollment\_transaction\_not\_found</code></td>
      <td>The mfa enrollment transaction is not active or has expired</td>
    </tr>

    <tr>
      <td><code>invalid\_phone\_number</code></td>
      <td>The provided phone number is invalid</td>
    </tr>

    <tr>
      <td><code>error\_sending\_sms</code></td>
      <td>SMS Delivery error</td>
    </tr>

    <tr>
      <td><code>feature\_disabled</code></td>
      <td>The requested feature is currently globally not available (contact the provider)</td>
    </tr>

    <tr>
      <td><code>feature\_disabled\_by\_admin</code></td>
      <td>The requested feature is currently disabled by your admin</td>
    </tr>

    <tr>
      <td><code>pn\_endpoint\_disabled</code></td>
      <td>We were unable to deliver the push notification after retrying many times. Try removing you account for the device and adding it again.</td>
    </tr>

    <tr>
      <td><code>too\_many\_sms</code></td>
      <td>You have exeed the amount of SMSs assigned to your user</td>
    </tr>

    <tr>
      <td><code>too\_many\_pn</code></td>
      <td>You have exeed the amount of push notifications assigned to your user</td>
    </tr>

    <tr>
      <td><code>too\_many\_sms\_per\_tenant</code></td>
      <td>You have exeed the amount of SMSs assigned to your tenant</td>
    </tr>

    <tr>
      <td><code>too\_many\_pn\_per\_tenant</code></td>
      <td>You have exeed the amount of push notifications assigned to your tenant</td>
    </tr>

    <tr>
      <td><code>field\_required</code></td>
      <td>A field is required to perform the operation (this errors has a field attribute with a code for the field: <code>otpCode</code>, <code>recoveryCode</code>)</td>
    </tr>

    <tr>
      <td><code>method\_not\_found</code></td>
      <td>You have requested a method that is currently not supported (should not happen)</td>
    </tr>

    <tr>
      <td><code>no\_method\_available</code></td>
      <td>There is currently no method to enroll (all of them are disabled)</td>
    </tr>

    <tr>
      <td><code>enrollment\_method\_disabled</code></td>
      <td>The specified enrollment method is disabled, this error has also a .method field</td>
    </tr>

    <tr>
      <td><code>auth\_method\_disabled</code></td>
      <td>The specified authentication method is disabled, this error has also a .method field</td>
    </tr>

    <tr>
      <td><code>invalid\_otp\_format</code></td>
      <td>OTP format validation error</td>
    </tr>

    <tr>
      <td><code>invalid\_recovery\_code\_format</code></td>
      <td>Recovery code format validation error</td>
    </tr>

    <tr>
      <td><code>transaction\_expired</code></td>
      <td>The transaction has already expired</td>
    </tr>

    <tr>
      <td><code>already\_enrolled</code></td>
      <td>You are already enrolled, cannot enroll again</td>
    </tr>

    <tr>
      <td><code>not\_enrolled</code></td>
      <td>You not enrolled. Must enroll first</td>
    </tr>

    <tr>
      <td><code>invalid\_enrollment</code></td>
      <td>The enrollment provided to transaction#requestAuth method is not valid or is null/undefined</td>
    </tr>
  </tbody>
</table>


# Install Guardian SDK
Source: https://auth0.com/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/install-guardian-sdk

Describes how to install, configure options, and use the Guardian SDKs.

The Guardian SDK provides a UI-less client for Guardian.

`npm install auth0-guardian-js`

## Source files

* [Full SDK Version](https://cdn.auth0.com/js/guardian-js/1.3/guardian-js.js)
* [Minified SDK Version](https://cdn.auth0.com/js/guardian-js/1.3/guardian-js.min.js)
* [Full Guardian API](https://github.com/auth0/auth0-guardian.js#full-api)

## Configure Guardian

```javascript lines theme={null}
var auth0GuardianJS = require('auth0-guardian-js')({
	// For US tenants: https://{name}.guardian.auth0.com
 	// For AU tenants: https://{name}.guardian.au.auth0.com
 	// For EU tenants: https://{name}.guardian.eu.auth0.com
  // For JP tenants: https://{name}.guardian.jp.auth0.com
	serviceUrl: "https://{{ userData.tenant }}.guardian.auth0.com",
	requestToken: "{{ requestToken }}", // or ticket: "{{ ticket }}" - see below

	issuer: {
		// The issuer name to show in OTP Generator apps
		label: "{{ userData.tenantFriendlyName }}",
		name: "{{ userData.tenant }}",
	},

	// The account label to show in OTP Generator apps
	accountLabel: "{{ userData.friendlyUserId }}",

	// Optional, for debugging purpose only,
	// ID that allows to associate a group of requests
	// together as belonging to the same "transaction" (in a wide sense)
	globalTrackingId: "{{ globalTrackingId }}"
});
```

Use of `requestToken` or `ticket` depends on the authentication method. Ticket corresponds to a previously generated [enrollment ticket](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/create-custom-enrollment-tickets).

### Use a custom domain

If you have a <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip> configured for your Auth0 tenant, you'll need to update the `serviceUrl` property to point to the Guardian endpoint:

```javascript lines theme={null}
var auth0GuardianJS = require('auth0-guardian-js')({
    // For custom domains
    serviceUrl: "https://{yourCustomDomain}/guardian/",
    ...
});
```

## Enroll devices

Enrolling devices consists of the following steps:

1. Start the transaction.
2. (optional) Check if the user is already enrolled. You cannot enroll twice.
3. Send the information needed to enroll.
4. Confirm enrollment.
5. Show the recovery code.

Some steps can be omitted depending on the method. We provide the same interface for all methods so you can write uniform code. Some of the methods complete the authentication, whereas others need an extra authentication step. You can determine that by listening to the `enrollment-complete` event.

```javascript lines expandable theme={null}
function enroll(transaction, method) {
	if (transaction.isEnrolled()) {
		console.log('You are already enrolled');
		return;
	}

	var enrollData = {};

	if (method === 'sms') {
		enrollData.phoneNumber = prompt('Phone number'); // Collect phone number
	}

	return transaction.enroll(method, enrollData, function (err, otpEnrollment) {
		if (err) {
			console.error(err);
			return;
		}

		var uri = otpEnrollment.getUri();
		if (uri) {
			showQR(uri);
		}

		var confirmData = {};
		if (method === 'otp' || method === 'sms') {
			confirmData.otpCode = prompt('Otp code'); // Collect verification otp
		}

		otpEnrollment.confirm(confirmData);
	});
}

auth0GuardianJS.start(function(err, transaction) {
	if (err) {
		console.error(err);
		return;
	}

	transaction.on('error', function(error) {
		console.error(error);
	});

	transaction.on('timeout', function() {
		console.log('Timeout');
	});

	transaction.on('enrollment-complete', function(payload) {
		if (payload.recoveryCode) {
			alert('Recovery code is ' + payload.recoveryCode);
		}

		if (payload.authRequired) {
			showAuthenticationFor(transaction, payload.enrollment);
			return;
		}
	});

	transaction.on('auth-response', function(payload) {
		if (payload.recoveryCode) {
			alert('The new recovery code is ' + payload.recoveryCode);
		}

		if (!payload.accepted) {
			alert('Authentication has been rejected');
			return;
		}

		auth0GuardianJS.formPostHelper('{{ postActionURL }}', { signature: payload.signature });
	});

	var availableEnrollmentMethods = transaction.getAvailableEnrollmentMethods();

	method = prompt('What method do you want to use, select one of '
		+ availableEnrollmentMethods.join(', '));

	enroll(transaction, method) // For sms
});
```

## Authenticate

To authenticate with a method you need to execute the following steps:

1. Start the transaction.
2. (optional) Check if the user is already enrolled. You need to be enrolled to authenticate.
3. Request the auth (the push notification or SMS). Request is a noop for OTP.
4. Verify the OTP (`.verify` is a noop for push).

Some steps can be omitted depending on the method, we provide the same interface for all methods so you can write uniform code. After the factor is verified or the push accepted you will receive an `auth-response` event with the payload to send to the server, you can use the `auth0GuardianJS.formPostHelper('{{ postActionURL }}', payload)` to post back the message to the server.

You may also receive `auth-rejected` if the push notification was received.

```javascript lines expandable theme={null}
function authenticate(method) {
	auth0GuardianJS.start(function (err, transaction) {
		if (err) {
			console.error(err);
			return;
		}

		if (!transaction.isEnrolled()) {
			console.log('You are not enrolled');
			return;
		}

		transaction.on('error', function(error) {
			console.error(error);
		});

		transaction.on('timeout', function() {
			console.log('Timeout');
		});

		transaction.on('auth-response', function(payload) {
			if (payload.recoveryCode) {
				alert('The new recovery code is ' + payload.recoveryCode);
			}

			if (!payload.accepted) {
				alert('Authentication has been rejected');
				return;
			}

			auth0GuardianJS.formPostHelper('{{ postActionURL }}', { signature: payload.signature });
		});

		var enrollment = transaction.getEnrollments()[0];

		if (enrollment.getAvailableAuthenticatorTypes().length === 0) {
			alert('Somethings went wrong, seems that there is no authenticators');
			return;
		}

		transaction.requestAuth(enrollment, { method: method } function(err, auth) {
			if (err) {
				console.error(err);
				return;
			}

			var data = {};
			if (method === 'sms' || method === 'otp') {
				data.otpCode = prompt('Otp code');
			} else if (method === 'recovery-code') {
				data.recoveryCode = prompt('Recovery code');
			}

			return auth.verify(data);
		});
	});
}
```

## Learn more

* [Guardian Error Code Reference](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/guardian-error-code-reference)


# Auth0 MFA API
Source: https://auth0.com/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/mfa-api

Describes the Auth0 MFA API which allows you to enroll and manage MFA for users.

Auth0 provides a built-in <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA) enrollment and authentication flow using [Universal Login](/docs/authenticate/login/auth0-universal-login). Use the [MFA API](https://auth0.com/docs/api/authentication#multi-factor-authentication)  in the following scenarios if you want to:

* [Authenticate users with the Resource Owner Password Grant](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa).
* Build an interface to let [users manage their own authentication factors](/docs/secure/multi-factor-authentication/manage-mfa-auth0-apis/manage-authenticator-factors-mfa-api).

To use the MFA API, you must enable the MFA grant type for your application. To enable the MFA grant in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, go to [Dashboard > Applications > Advanced Settings > Grant Types](https://manage.auth0.com/#/applications) and select **MFA**. See [Enable Multi-Factor Authentication](/docs/secure/multi-factor-authentication/enable-mfa) for details.

## Limitations

The MFA API is designed to work with SMS, Voice, push via the Auth0 Guardian app, email, and OTP factors. It does not currently support enrolling with Duo or WebAuthn.

## Learn more

* [Customize Multi-Factor Authentication Pages](/docs/secure/multi-factor-authentication/customize-mfa)
* [Authenticate Using the Resource Owner Password Flow with MFA](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa)
* [Multi-Factor Authentication Developer Resources](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources)
* [Create Custom Enrollment Tickets](/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/create-custom-enrollment-tickets)


# Auth0 MFA Client Library
Source: https://auth0.com/docs/secure/multi-factor-authentication/multi-factor-authentication-developer-resources/mfa-client-library





# Configure Email Notifications for MFA
Source: https://auth0.com/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-email-notifications-for-mfa

Describes how to configure email as an MFA factor for users who don't have their primary factor available.

Use email as a <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA) factor to provide users a way to perform MFA when they don't have their primary factor available (e.g. they don't have their device to receive an SMS or push notification).

<Card title="Availability varies by login implementation">
  The login implementation you use affects whether this feature is available. To learn more, read [Universal Login vs. Classic Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login).
</Card>

Email is not true MFA because it does not represent a different factor than the password. It does not represent **something I have** or **something I am**, but rather just **something I know** (the email password). It is also weaker than other factors in that it's only as secure as the email itself (for example, encrypted end-to-end).

Users do not need to explicitly enroll with email MFA. They can use it when they have a verified email. This happens when they:

* Complete the email verification flow which updates the `email_verified` field using the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.
* Log in with a connection that provides verified emails (such as Google).

You can only enable email as an MFA factor if there is already another factor enabled.

Once Email MFA is enabled, users will be prompted to complete MFA with another enabled factor. If they select **Try another method**, and then pick **Email**, they will be sent an email with a 6-digit code that they will need to enter to complete the authentication flow.

## Configure email notifications

You can explicitly enroll email for MFA using the [MFA API](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-email-authenticators). If users have a verified email and one or more explicitly enrolled emails, they can choose to select which email they want to use to complete MFA when logging-in using <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>.

1. Go to [Dashboard > Security > Multi-factor Auth](https://manage.auth0.com/#/multifactor-auth) and enable the **Email** toggle.
   You will only be able to enable it if there is another factor enabled.
2. Auth0 provides a test email provider but it only allows a limited amount of emails, so you should configure your own email provider. To learn more, read [Configure External SMTP Email Providers](/docs/customize/email/smtp-email-providers).

## Learn more

* [Enroll and Challenge Email Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-email-authenticators)
* [Customize Emails](/docs/customize/email)
* [Customize Email Templates](/docs/customize/email/email-templates)
* [Customize Email Handling](/docs/customize/email/manage-email-flow)
* [Configure External SMTP Email Providers](/docs/customize/email/smtp-email-providers)
* [Configure Custom External SMTP Email Provider](/docs/customize/email/smtp-email-providers/configure-custom-external-smtp-email-provider)


# Configure OTP Notifications for MFA
Source: https://auth0.com/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-otp-notifications-for-mfa

Describes how to configure time-based one time passwords (OTP) notifications for MFA.

Auth0 supports one-time passwords (OTPs) as <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> factors. In order for users to leverage OTPs, you first must [enable them as an MFA factor](/docs/secure/multi-factor-authentication/enable-mfa) in your Auth0 tenant.

Once enabled for your application, users can enroll in OTPs when accessing your application. To do so, they must install an authenticator application on their device, such as:

* Auth0 Guardian ([Google Play](https://play.google.com/store/apps/details?id=com.auth0.guardian) / [App Store](https://itunes.apple.com/us/app/auth0-guardian/id1093447833))
* Authy ([Google Play](https://play.google.com/store/apps/details?id=com.authy.authy) / [App Store](https://itunes.apple.com/us/app/authy/id494168017))
* Google Authenticator ([Google Play](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2) / [App Store](https://itunes.apple.com/us/app/google-authenticator/id388497605))
* Microsoft Authenticator ([Google Play](https://play.google.com/store/apps/details?id=com.azure.authenticator) / [App Store](https://itunes.apple.com/us/app/microsoft-authenticator/id983156458))

## User OTP workflow

When a user attempts to sign up through a <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> prompt, they are prompted to scan a QR code to enroll in OTPs.

<Frame>
  <img alt="Auth0 Guardian OTP QR code setup example" />
</Frame>

If the user's device is detected as a mobile device, Universal Login skips the QR code screen and instead displays an enrollment code directly in the prompt.

<Frame>
  <img alt="The temporary one-time password enrollment screen as displayed on a mobile device. " />
</Frame>

After a user has enrolled in OTPs, they can use OTPs to log in to your application. To do so, they first retrieve a one-time code from their preferred authenticator app.

<Frame>
  <img alt="Auth0 Guardian OTP Code Google example" />
</Frame>

Then, they enter the one-time code in the login prompt.

<Frame>
  <img alt="Auth0 Guardian OTP Login Prompt Example" />
</Frame>

## Learn more

* [Enroll and Challenge OTP Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-and-challenge-otp-authenticators)


# Configure SMS and Voice Notifications for MFA
Source: https://auth0.com/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-sms-voice-notifications-mfa

Describes how to configure SMS and voice notifications for MFA.

<Warning>
  The Unified Phone Experience centralizes all your phone provider configurations in one place in your tenant, so you don’t need to configure the same phone provider multiple times for various phone authentication factors. To learn more, read [Use Auth0's Unified Phone Experience for Multi-Factor Authentication](/docs/customize/phone-messages/unified-phone/use-auth0s-unified-phone-experience-for-multi-factor-authentication).
</Warning>

If you use SMS or voice as authentication factors, when an end user attempts to authenticate with your application, they are sent a code via SMS or voice, which they will have to enter to complete the transaction. This implies that they both know their login credentials and are in possession of the device that they have registered for <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> use.

You can configure the SMS and Voice factor using the Dashboard or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to send messages through SMS, voice, or to let the end users choose how they want the code to be delivered. You can configure your delivery provider using Actions, configure your Twilio account, or if you want to send customers SMS only, configure Auth0's default message delivery service. You must use the <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> experience to enable voice notifications for MFA.

<Card title="Availability varies by Auth0 plan">
  Both your specific login implementation and your Auth0 plan or custom agreement affect whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

## How it works

When SMS and Voice are enabled, users are given the option to enroll by getting the code sent by SMS or voice:

<Frame>
  <img alt="Configure SMS and Voice for MFA User Experience Voice" />
</Frame>

When you only enable SMS, the flow is simpler:

<Frame>
  <img alt="Configure SMS and Voice for MFA User Experience SMS" />
</Frame>

After users are enrolled, the next time they authenticate they will get the voice or SMS message at their registered phone.

## Use the Dashboard

1. Go to [Dashboard > Security > Multi-factor Auth](https://manage.auth0.com/#/multifactor-auth).
2. Click **Phone Message** and enable the toggle switch at the top.
3. Select your preferred message delivery provider.
4. To allow users to authenticate with SMS and voice, you must enable the SMS and voice factors and select your preferred delivery method:

   1. **Auth0**: You can't use this provider to send voice messages. Sends SMS messages using Auth0's internally-configured SMS delivery provider. It can be used for evaluation and testing purposes only, and there is a maximum of 100 messages per tenant during the entire tenant lifetime. New codes are not received after reaching the 100 message limit.
   2. **Twilio**: Sends the messages using the [Twilio Programmable SMS API](https://www.twilio.com/sms) for SMS or [Twilio Programmable Voice API](https://www.twilio.com/voice) for voice. Use Twilio Life Credentials, not Test Credentials, which are only meant to send messages in a production environment.
   3. **Custom**: Sends the messages by invoking an Action in the [Send Phone Message Flow](/docs/customize/actions/explore-triggers/mfa-notifications-trigger).

   You can also choose to give users the option of getting SMS text messages, voice calls, or both.

### Twilio configuration

<Callout icon="file-lines">
  Be advised, Twilio may take up to eight (8) weeks to port and verify bulk imports. To learn more, visit the [Twilio Help Center](https://help.twilio.com/articles/223179468-How-long-does-it-take-to-port-a-number-to-Twilio).
</Callout>

If you choose to deliver SMS via Twilio, follow these steps to configure your SMS factor.

1. Open an account with Twilio. You will need a [Twilio Account SID](https://www.twilio.com/help/faq/twilio-basics/what-is-an-application-sid) and a [Twilio Auth Token](https://www.twilio.com/help/faq/twilio-basics/what-is-the-auth-token-and-how-can-i-change-it). These are the Twilio API credentials that Auth0 will use to send an SMS to the user.
2. You may also need to enable permissions for your geographic region for [SMS](https://support.twilio.com/hc/en-us/articles/223181108-How-International-SMS-Permissions-work) or [voice](https://www.twilio.com/console/voice/calls/geo-permissions). If you use voice, your account needs to have a Twilio phone number enabled to make voice calls. This can be an external phone number [verified with Twilio](https://support.twilio.com/hc/en-us/articles/223180048-Adding-a-Verified-Phone-Number-or-Caller-ID-with-Twilio) or you can purchase and set up a Twilio phone number from within your account.
3. Configure the connection. Go to [Dashboard > Security - Multi-factor Auth](https://manage.auth0.com/#/security/mfa) and choose **Phone Message**.
4. Under **Choose your delivery provider**, choose **Twilio** and choose a delivery method.
5. Enter your **Twilio Account SID** and **Twilio Auth Token** in the appropriate fields.
6. Choose your **SMS Source**.

   1. If you choose **Use From**, you will need to enter the **From** phone number that users will see as the sender of the SMS. You may also configure this in Twilio.
   2. If you choose **Use Messaging Services**, you will need to enter a [Messaging Service SID](https://www.twilio.com/docs/sms/services/services-send-messages).
   3. If you are using voice, you always need to configure **From** even if you are using **Message Services** for SMS. Make sure the phone number is configured to send both SMS and voice messages.
7. Click **Save**.

### Customize SMS or voice message templates

You can customize your SMS and voice message templates. To learn more, read [Customize SMS and Voice Messages](/docs/customize/customize-sms-or-voice-messages).

## Use the Management API

You can use the Management API to configure which message delivery methods are enabled by using the `/api/v2/guardian/factors/phone/message-types` endpoint. The `message_types` parameter is an array that can have `["sms"]`, `["voice"]`, or `["sms", "voice"]`. You need a [Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens) with the `update:guardian_factors` scope as a bearer token to call the API:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PUT \
    --url 'https://{yourDomain}/api/v2/guardian/factors/phone/message-types' \
    --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
    --header 'content-type: application/json' \
    --data '{ "message_types": ["sms", "voice"] }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/guardian/factors/phone/message-types");
  var request = new RestRequest(Method.PUT);
  request.AddHeader("content-type", "application/json");
  request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
  request.AddParameter("application/json", "{ "message_types": ["sms", "voice"] }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/guardian/factors/phone/message-types"

  	payload := strings.NewReader("{ "message_types": ["sms", "voice"] }")

  	req, _ := http.NewRequest("PUT", url, payload)

  	req.Header.Add("content-type", "application/json")
  	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.put("https://{yourDomain}/api/v2/guardian/factors/phone/message-types")
    .header("content-type", "application/json")
    .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
    .body("{ "message_types": ["sms", "voice"] }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PUT',
    url: 'https://{yourDomain}/api/v2/guardian/factors/phone/message-types',
    headers: {
      'content-type': 'application/json',
      authorization: 'Bearer MGMT_API_ACCESS_TOKEN'
    },
    data: {message_types: ['sms', 'voice']}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json",
                             @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN" };
  NSDictionary *parameters = @{ @"message_types": @[ @"sms", @"voice" ] };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/guardian/factors/phone/message-types"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"PUT"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/guardian/factors/phone/message-types",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_POSTFIELDS => "{ "message_types": ["sms", "voice"] }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer MGMT_API_ACCESS_TOKEN",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "message_types": ["sms", "voice"] }"

  headers = {
      'content-type': "application/json",
      'authorization': "Bearer MGMT_API_ACCESS_TOKEN"
      }

  conn.request("PUT", "/{yourDomain}/api/v2/guardian/factors/phone/message-types", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/guardian/factors/phone/message-types")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Put.new(url)
  request["content-type"] = 'application/json'
  request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
  request.body = "{ "message_types": ["sms", "voice"] }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/json",
    "authorization": "Bearer MGMT_API_ACCESS_TOKEN"
  ]
  let parameters = ["message_types": ["sms", "voice"]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/guardian/factors/phone/message-types")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "PUT"
  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()
  ```
</AuthCodeGroup>

## Integrated SMS messaging providers

Auth0 defaults to support for sending messages through Twilio. However, you can use a different SMS provider, and add specific logic before sending a message or send a different message depending on the user or the application. To do this, you configure SMS MFA to use one of our integrated [Actions](/docs/customize/actions) in the [Send Phone Message Flow](/docs/customize/actions/explore-triggers/mfa-notifications-trigger).

Integrated SMS messaging providers include:

* [Amazon SNS](https://marketplace.auth0.com/integrations/amazon-sms-provider)
* [ClickSend](https://marketplace.auth0.com/integrations/clicksend-sms)
* [Esendex](https://marketplace.auth0.com/integrations/esendex-sms-provider)
* [Infobip](https://marketplace.auth0.com/integrations/infobip-sms-provider)
* [Mitto](https://marketplace.auth0.com/integrations/mitto-sms-provider)
* [Telesign](https://marketplace.auth0.com/integrations/telesign-sms-verification)

## Custom phone providers

You can also configure custom phone providers using Actions. To learn more, read [Configure a Custom Phone Provider](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider).

## Security considerations

When using any phone messaging provider, be aware that attackers abusing the signup flow could cause you financial damage.

Auth0 limits a single user to send up to 10 SMS or voice messages per hour, and OTP flows via email or authenticators are limited to five requests every five minutes. (The burst rate is 10 but only 1 voice message per hour will be sent for new requests.) To further protect your account, consider:

* Enabling [Suspicious IP Throttling](/docs/secure/attack-protection/suspicious-ip-throttling#signup-attempts). Auth0 will block an IP if it attempts to do more than 50 signup requests per minute.
* Enabling [Log Streaming](/docs/customize/log-streams) and creating alerts using your favorite monitoring tool when you see spikes in the number of `gd_send_voice`, `gd_send_voice_failure`, `gd_send_sms`, or `gd_send_sms_failure` [log events](/docs/deploy-monitor/logs/log-event-type-codes).

Phone Messaging providers have additional protections. If you are using Twilio, read the [Twilio's Anti-Fraud Developer Guide](https://www.twilio.com/docs/usage/anti-fraud-developer-guide). Consider the following options:

* Limit the countries that you will send messages for [SMS](https://support.twilio.com/hc/en-us/articles/223181108-How-International-SMS-Permissions-work) and [Voice](https://support.twilio.com/hc/en-us/articles/223180228-International-Voice-Dialing-Geographic-Permissions-Geo-Permissions-and-How-They-Work). This is particularly useful if there are countries with a higher risk of [toll fraud](https://www.twilio.com/learn/voice-and-video/toll-fraud) or more expensive calling rates in which you do not typically do business.
* Enable Twilio [usage triggers](https://support.twilio.com/hc/en-us/articles/223132387-Protect-your-Twilio-project-from-Fraud-with-Usage-Triggers) to protect your account against fraud and coding mistakes.

## Learn more

* [Enroll and Challenge SMS and Voice Authenticators](/docs/secure/multi-factor-authentication/authenticate-using-ropg-flow-with-mfa/enroll-challenge-sms-voice-authenticators)
* [Attack Protection](/docs/secure/attack-protection)
* [Log Streams](/docs/customize/log-streams)


# Reset User Multi-Factor Authentication and Recovery Codes
Source: https://auth0.com/docs/secure/multi-factor-authentication/reset-user-mfa

Learn how to reset a user's MFA in case they lose their mobile device and do not have a recovery code.

If a user has lost their mobile device, they can use their recovery code to log in. If they do not have a recovery code, they will need their tenant administrator to reset their <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA). This action is equivalent to removing or deleting the user's MFA registration. The MFA settings associated with the user will be removed, which allows them to set up MFA as if they were a new user on their next login attempt. To reset an admin's MFA as opposed to an end user's MFA, please contact [Auth0 Support](/docs/troubleshoot/customer-support).

## Use the Dashboard

1. Go to [Dashboard > Users Management > Users](https://manage.auth0.com/#/users).
2. Click on the user whose MFA you want to reset.
3. Click on the **Actions** button on the top right of the screen.
4. Select **Reset Multi-factor** from the dropdown. Admins will also see a **Reset MFA** link at the bottom of the **Multi-Factor Authentication** tab of the **User Details** page if the user is already enrolled in MFA. Both these methods function the same way. There will be a pop-up box to confirm your decision.
5. Click **Yes, reset it** to reset the user's MFA.

The next time the user logs in, they will need to set up their MFA just like a new user.

## Use the Management API

As an admin, you can also use the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to delete a user's MFA enrollment using `DELETE` `/api/v2/users/{id}/authentication-methods`. If the user has more than one enrollment, you will need to repeat the process for each enrollment.

## Recovery codes

With most MFA factors, the end user will be given a recovery code upon signup, which should be noted and kept secret. If they do not have their device or are otherwise temporarily unable to use their normal MFA process, the user can log in by entering this code after their username and password. If a recovery code is used, a new recovery code will be provided at that time.

If a user uninstalls then later re-installs Guardian, they may be prompted to enter their recovery code. If the recovery code has been lost, the user can perform a new installation of the app by disabling automatic restoration of their Guardian backup. To do so, the user will need to uninstall Guardian, temporarily disable automatic restoration of backups within their device settings (steps to do so will vary according to the device), then re-install the app. They will then need to add their MFA account(s) to the app as if performing a first-time setup. If automatic backups or automatic restoration are not enabled on the user's device, re-installation of the app will not prompt for a recovery code and the user will be required to add their MFA account(s) as in a first-time configuration.

## Learn more

* [Reset Account Passwords](/docs/troubleshoot/customer-support/reset-account-passwords)
* [Troubleshoot Multi-Factor Authentication Issues](/docs/troubleshoot/authentication-issues/troubleshoot-mfa-issues)


# Add Step-up Authentication
Source: https://auth0.com/docs/secure/multi-factor-authentication/step-up-authentication

Describes how step-up authentication works for APIs and web apps to verify that the user has logged in using MFA and if not, require the user to step-up to access certain resources.

With step-up authentication, applications that allow access to different types of resources can require users to authenticate with a stronger authentication mechanism to access sensitive resources.

You can add step-up authentication to your app with Auth0's extensible <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA) support. Your app can verify that the user has logged in using MFA and, if not, require the user to step-up to access certain resources.

## How it works

As an example, Fabrikam's Intranet requires users to authenticate with their username and password to access customer data. However, a request for access to employee data (which may contain sensitive salary information) triggers a stronger authentication mechanism like MFA.

<Frame>
  <img alt="MFA Step-up Authentication flow diagram" />
</Frame>

## Step-up Authentication for APIs

When your <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> is an API, you can implement step-up authentication with Auth0 using [scopes](/docs/get-started/apis/scopes), [access tokens](/docs/secure/tokens/access-tokens), and [Actions](/docs/customize/actions). You can use an Action to trigger the step-up authentication mechanism (for example, prompt MFA) whenever the user requests scopes that map to sensitive resources.

In our example, a user signs into Fabrikam's web app. The standard login gives to this user the ability to interact with their API and fetch the user's account list. This means that the <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> that the application receives after the user authentication contains a scope like `read:accounts`.

Now the user wishes to transfer funds from one account to another, which is deemed a high-value transaction. In order to perform this action, the API requires the scope `transfer:funds`.

The user's current access token does not include this scope and the application knows it (because the application knows the set of scopes it requested in the initial authentication call). The application performs another authentication call, but this time it requests the scope `transfer:funds`. The browser redirects to Auth0. Per Fabrikam's Action, Auth0 challenges the user to authenticate with MFA because a high-value scope was requested. Once the user successfully authenticates with MFA, Auth0 generates and sends a new access token that includes the high-value scope. The application passes the access token to the API, which discards it after verification, thereby treating it as a single-use token.

To learn more, read [Configure Step-up Authentication for APIs](/docs/secure/multi-factor-authentication/step-up-authentication/configure-step-up-authentication-for-apis).

## Step-up Authentication for web apps

If it is a web app that verifies the authentication level, and not an API, then you do not have an access token. In this case, you can check if a user has logged in with MFA by reviewing the contents of their <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip>. You can then configure your application to deny access to pages with sensitive information if the ID token indicates that the user did not log in with MFA, and use an Action to trigger the step-up authentication mechanism (for example, prompt MFA). For example, you might have an employee app that authenticates users with usernames and passwords, but if a user wants to access salary information, they have to provide a second factor such as a mobile push notification.

You can implement this by checking the ID token when the user tries to access that page. If the claims show that the user already has authenticated with MFA then display the sensitive information. Otherwise, trigger authentication again and, using an Action, prompt the user to authenticate with MFA.

To learn more, read [Configure Step-up Authentication for Web Apps](/docs/secure/multi-factor-authentication/step-up-authentication/configure-step-up-authentication-for-web-apps).

## Learn more

* [Configure Step-up Authentication for APIs](/docs/secure/multi-factor-authentication/step-up-authentication/configure-step-up-authentication-for-apis)
* [Configure Step-up Authentication for Web Apps](/docs/secure/multi-factor-authentication/step-up-authentication/configure-step-up-authentication-for-web-apps)


# Configure Step-up Authentication for APIs
Source: https://auth0.com/docs/secure/multi-factor-authentication/step-up-authentication/configure-step-up-authentication-for-apis

Learn how an API can check if a user has logged in with Multi-factor Authentication by examining their access token.

With step-up authentication, applications that allow access to different types of resources can require users to authenticate with a stronger mechanism to access sensitive information or perform certain transactions.

For example, a user of a banking app may be allowed to transfer money between accounts only after they have confirmed their identity using <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA).

When your <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> is an API, you can implement step-up authentication with Auth0 using scopes, <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip>, and [Actions](/docs/customize/actions). When an application wants to access an API's protected resources, it must provide an access token. The resources that it will have access to depend on the permissions that are included in the access token. These permissions are defined as [scopes](/docs/get-started/apis/scopes/api-scopes).

## Validate access tokens for MFA

In addition to checking the scope, the API must [validate the access token](/docs/secure/tokens/access-tokens/validate-access-tokens) to:

* Verify the token's signature, used to verify that the sender of the token is who it says it is and to ensure that the message wasn't changed along the way.
* Validate the standard claims:

  <table>
    <thead>
      <tr>
        <th>Claim</th>
        <th>Description</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td><code>exp</code></td>
        <td>Token expiration</td>
      </tr>

      <tr>
        <td><code>iss</code></td>
        <td>Token issuer</td>
      </tr>

      <tr>
        <td><code>aud</code></td>
        <td>Intended recipient of the token</td>
      </tr>
    </tbody>
  </table>

## Scenario: Bank transactions with push notifications

In the following scenario, an application authenticates a user with username and password and then requests an account balance. Before retrieving the account balance information, the user must authenticate with Guardian push factor.

The banking API can accept two different levels of authorization: view account balance (scope `view:balance`) or transfer funds (scope `transfer:funds`). When the application asks the API to retrieve the user's balance, the access token should contain the `view:balance` scope. To transfer money to another account, the access token should contain the `transfer:funds` scope.

### Workflow

1. The user logs in to the application using username and password authentication. The standard login gives this user the ability to interact with the API and fetch their balance. This means that the access token that the app receives after the user authenticates contains the `view:balance` scope.
2. The application sends a request to the API to retrieve the balance, using the access token as credentials.
3. The API validates the token and sends the balance info to the application, so the user can view it.
4. The user wants to transfer funds from one account to another, which is deemed a high-value transaction that requires the `transfer:funds` scope. The application sends a request to the API using the same access token.
5. The API validates the token and denies access because the token is missing the required `transfer:funds` scope.
6. The application redirects to Auth0, where an Action is used to challenge the user to authenticate with MFA since a high-value scope was requested. Once the user successfully authenticates with MFA, a new access token that includes the correct scope is generated and sent to the application as part of the response.
7. The application sends another transfer funds request using the new access token, which includes the `transfer:funds` scope this time.
8. The API validates the token, discards it, and proceeds with the operation.

### Prerequisites

For this scenario, you must configure the following items in the Dashboard:

* [Register a Single-Page Web App](/docs/get-started/auth0-overview/create-applications/single-page-web-apps).
* [Create a database connection](https://manage.auth0.com/#/connections/database).
* [Register the API](/docs/get-started/auth0-overview/set-up-apis). Create two scopes: `view:balance` and `transfer:funds`.
* [Enable MFA](/docs/secure/multi-factor-authentication/enable-mfa) to use push notifications.

### Create an Action

Create an Action that challenges the user to authenticate with MFA when the `transfer:funds` scope is requested. Go to [Dashboard > Actions > Flows](https://manage.auth0.com/#/actions/flows) and create an Action that contains the following content:

```javascript theme={null}
{
exports.onExecutePostLogin = async (event, api) => {
  const CLIENTS_WITH_MFA = ['REPLACE_WITH_{yourClientId}'];
  // run only for the specified clients
  if (CLIENTS_WITH_MFA.includes(event.client.client_id)) {
    // ask for MFA only if scope transfer:funds was requested
    if (event.transaction.requested_scopes.indexOf('transfer:funds') > -1)
      api.multifactor.enable('any', { allowRememberBrowser: false });
    }
  }
},
```

* The `CLIENTS_WITH_MFA` variable contains the <Tooltip href="/docs/glossary?term=client+IDs">client IDs</Tooltip> of the applications you want this Action to apply to. You can remove this (and the `if` conditional that follows) if you don't need it.
* The `event.transaction.requested_scopes` property contains all the scopes for which the authentication request asked. If it includes the value `transfer:funds`, then we ask for MFA by setting the `context.multifactor` property to the appropriate value. In this case, we are asking for MFA using [push](/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-push-notifications-for-mfa).

### Configure app

Configure the app to send the appropriate authentication request to the API, depending on whether the user is attempting to perform the high-value transaction of transferring funds. Notice that the only difference between the two authentication requests (with or without MFA) is the scope.

* With MFA:

  export const codeExample1 = ` https://{yourDomain}/authorize?
  audience=https://my-banking-api&
  scope=openid%20view:balance%20transfer:funds&
  response_type=id_token%20token&
  client_id={yourClientId}&
  redirect_uri={https://yourApp/callback}&
  nonce=NONCE&
  state=OPAQUE_VALUE`;

<AuthCodeBlock />

* Without MFA:

  export const codeExample2 = ` https://{yourDomain}/authorize?
  audience=https://my-banking-api&
  scope=openid%20view:balance&
  response_type=id_token%20token&
  client_id={yourClientId}&
  redirect_uri={https://yourApp/callback}&
  nonce=NONCE&
  state=OPAQUE_VALUE`;

<AuthCodeBlock />

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Setting</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>audience</code></td>
      <td>Set to the <strong>Identifier</strong> of your API (find it at <a href="https://manage.auth0.com/#/apis/">API Settings</a>). We set ours to `https://my-banking-api`.</td>
    </tr>

    <tr>
      <td><code>response\_type</code></td>
      <td>Set to <code>id\_token token</code> so we get both an ID Token and an Access Token in the response.</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Set to the Client ID of your application (find it at <a href="https://manage.auth0.com/#/applications/{yourClientId}/settings">Application Settings</a>).</td>
    </tr>

    <tr>
      <td><code>redirect\_uri</code></td>
      <td>Set to a URL in your application that Auth0 should redirect back to after authentication (find it at <a href="https://manage.auth0.com/#/applications/{yourClientId}/settings">Application Settings</a>).</td>
    </tr>

    <tr>
      <td><code>nonce</code></td>
      <td>Set to a secure string value which will be included in the response from Auth0. This is <a href="/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post/mitigate-replay-attacks-when-using-the-implicit-flow">used to prevent token replay attacks</a> and is required for <code>response\_type=id\_token token</code>.</td>
    </tr>

    <tr>
      <td><code>state</code></td>
      <td>Set to an opaque value that Auth0 includes when redirecting back to the application. This value must be used by the application to prevent CSRF attacks.</td>
    </tr>
  </tbody>
</table>

### Configure API

Configure the API to validate the incoming token and check the authorized permissions.

1. Configure two endpoints for our API:
   `GET /balance`: to retrieve the current balance
   `POST /transfer`: to transfer funds
2. Use `Node.js` and a number of modules:

   1. [express](https://expressjs.com/): adds the Express web application framework.
   2. [jwks-rsa](https://github.com/auth0/node-jwks-rsa): retrieves RSA signing keys from a **JWKS** (JSON Web Key Set) endpoint. Using `expressJwtSecret`, we can generate a secret provider that will issue the right signing key to `express-jwt` based on the `kid` in the JWT header.
   3. [express-jwt](https://github.com/auth0/express-jwt): lets you authenticate HTTP requests using JWT tokens in your Node.js applications. It provides several functions that make working with JWTs easier.
   4. [express-jwt-authz](https://github.com/auth0/express-jwt-authz): checks if the access token contains a specific scope.
3. Install the dependencies:
   `npm install express express-jwt jwks-rsa express-jwt-authz --save`
4. Define the API endpoints, create a middleware function to validate the access token, and secure the endpoints using that middleware. The code in your `server.js` file should look like the following sample script:

<AuthCodeBlock />

Each time the API receives a request the following happens:

1. The endpoint calls the `checkJwt` middleware.
2. `express-jwt` decodes the token and passes the request, the header, and the payload to `jwksRsa.expressJwtSecret`.
3. `jwks-rsa` downloads all signing keys from the JWKS endpoint and checks if one of the signing keys matches the `kid` in the header of the access token. If none of the signing keys match the incoming `kid`, an error is thrown. If there is a match, we pass the right signing key to `express-jwt`.
4. `express-jwt` continues its own logic to validate the signature of the token, the expiration, audience, and the issuer.
5. `jwtAuthz` checks if the scope that the endpoint requires is part of the access token. If the specified scopes are missing from the access token, the request is rejected with a 403 error message.

## Learn more

* [Access Tokens](/docs/secure/tokens/access-tokens)
* [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens)
* [Action Use Cases](/docs/customize/actions/use-cases)
* [API Scopes](/docs/get-started/apis/scopes/api-scopes)
* [Configure Step-up Authentication for Web Apps](/docs/secure/multi-factor-authentication/step-up-authentication/configure-step-up-authentication-for-web-apps)


# Configure Step-up Authentication for Web Apps
Source: https://auth0.com/docs/secure/multi-factor-authentication/step-up-authentication/configure-step-up-authentication-for-web-apps

Learn how to check if a user has logged in your web app with Multi-factor Authentication (MFA) by examining their ID Token.

With step-up authentication, applications that allow access to different types of resources can require users to authenticate with a stronger mechanism to access sensitive information or perform certain transactions.

For instance, a user may be allowed to access views with sensitive data or reset their password only after confirming their identity using <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA).

To accomplish step-up authentication for your web app, you will create an Action that challenges the user to authenticate with MFA when the web app asks for it, check the <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip> claims for MFA if the user tries to access a restricted page, and then challenge the user if MFA is not included in the claim.

## Validate ID tokens for MFA

When a user logs in, you get an [ID token](/docs/secure/tokens/id-tokens/get-id-tokens) that contains information relevant to the user's session in the form of claims. The relevant claim is `amr` (authentication methods reference) which is a JSON array of strings that indicates the authentication method used during login. It must be present in the ID token's payload and must contain the value `mfa`.

Its values may include any of the pre-defined [Authentication Method Reference Values](https://tools.ietf.org/html/rfc8176). Because it can contain claims other than `mfa`, when validating you must both test for its existence and examine its contents for a value of `mfa`.

If a user attempts to access a restricted page and the token shows that the user has not authenticated with MFA, then you can retrigger authentication, which you have configured to trigger MFA using an Action. Once the user provides the second factor, a new ID token that contains the `amr` claim is generated and sent to the app.

1. [Get the ID token](/docs/secure/tokens/id-tokens/get-id-tokens).
2. Verify the token's signature, which is used to verify that the sender of the token is who it says it is and to ensure that the message wasn't changed along the way.
3. Validate the following claims:

   <table>
     <thead>
       <tr>
         <th>Claim</th>
         <th>Description</th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td><code>exp</code></td>
         <td>Token expiration</td>
       </tr>

       <tr>
         <td><code>iss</code></td>
         <td>Token issuer</td>
       </tr>

       <tr>
         <td><code>aud</code></td>
         <td>Intended recipient of the token</td>
       </tr>

       <tr>
         <td><code>amr</code></td>
         <td>If <code>amr</code> does not exist in the payload or does not contain the value <code>mfa</code>, the user did not log in with MFA. If <code>amr</code> exists in the payload and contains the value <code>mfa</code>, then the user did log in with MFA.</td>
       </tr>
     </tbody>
   </table>

#### AMR claim exceptions

The `amr` claim is required except in the following use cases:

1. In hosted login flows, only after the user successfully passes an MFA challenge, the `amr` claim is injected into the ID token. If the app uses silent authentication or Refresh Tokens for newly issued ID tokens, the `amr` claim will not be present because the user previously completed login with MFA.
2. MFA API issued tokens do not contain the `amr` claim. The `amr` claim flags the authentication methods used when the user receives the ID Token. In the MFA API authentication process, the application controls the authentication flow and can enforce MFA as needed.

In the examples below, you can compare the potential values included in an ID token's payload when a user has authenticated with MFA versus when they have not.

### Example: Values with MFA

<AuthCodeBlock />

### Example: Values without MFA

<AuthCodeBlock />

## Scenario: Salary data with push notifications

In the following scenario, a web app authenticates a user with a username and password. Some users want to access a specific screen that displays salary data, so they must authenticate with Guardian push factor.

### Prerequisites

For this scenario, you must configure the following items in the Dashboard:

* [Register a web app](/docs/get-started/auth0-overview/create-applications/regular-web-apps).
* [Create a database connection](https://manage.auth0.com/#/connections/database).
* [Enable MFA](/docs/secure/multi-factor-authentication/enable-mfa) to use push notifications.

### Create an Action

Create an Action that challenges the user to authenticate with MFA when the web app requests it. Go to [Dashboard > Actions > Flows](https://manage.auth0.com/#/actions/flows), and create an Action that contains the following content:

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
 const CLIENTS_WITH_MFA = ['REPLACE_WITH_{yourClientId}'];
 // run only for the specified clients
 if (CLIENTS_WITH_MFA.includes(event.client.client_id)) {
 // ask for MFA only if the web app said so in the authentication request
 if (event.transaction?.acr_values.includes('http://schemas.openid.net/pape/policies/2007/06/multi-factor')) {
 api.multifactor.enable('any', { allowRememberBrowser: false });
 }
 }
}
```

* The `CLIENTS_WITH_MFA` variable contains the <Tooltip href="/docs/glossary?term=client+IDs">client IDs</Tooltip> of the applications you want this Action to apply to. You can remove this (and the `if` conditional that follows) if you don't need it.
* The `event.transaction.acr_values` property is an array of strings that contains the authentication context class reference(s) (`acr`). This is an optional property that only exists when the application includes it in the authentication request to the <Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip>. In this example, our web app will include it in the authentication request, but only when a user who has not already authenticated with MFA tries to access salary information. When our web app includes it, it will set a value of `http://schemas.openid.net/pape/policies/2007/06/multi-factor`, which indicates that we want the Authorization Server to require MFA, and the `api.multifactor` property value that we set in our code will challenge the user for MFA using any of the available methods that have been configured in the tenant. To learn more about the `api.multifactor.enable()` method, read [Action Triggers: post-login API object](/docs/customize/actions/explore-triggers/password-reset-triggers/post-challenge-trigger/post-challenge-api-object).
* The `http://schemas.openid.net/pape/policies/2007/06/multi-factor` policy defines an authentication mechanism where the end user authenticates to the <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Provider by providing more than one authentication factor, or MFA. To learn more, read [OpenID Provider Authentication Policy Extension 1.0](https://openid.net/specs/openid-provider-authentication-policy-extension-1_0.html).

### Configure app

Configure the app to check that the user has authenticated using MFA when a user tries to access the restricted salary information page. (When a user has authenticated with MFA, the ID token claims contain the `amr` claim with a value of `mfa`.) If the user has already authenticated with MFA, then the web app will display the restricted page; otherwise, the web app will send a new authentication request that includes the `acr_values` parameter with a value of:
`http://schemas.openid.net/pape/policies/2007/06/multi-factor`which will trigger the Action.

The web app in this scenario uses the [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow) to authenticate, so the request is as follows:

<AuthCodeBlock />

Once the user authenticates with MFA, the web app receives the authorization code, which must be exchanged for the new ID token, which should now contain the `amr` claim with a value of `mfa`. To learn how to exchange the code for an ID token, read [Add Login Using the Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/add-login-auth-code-flow).

### Validate ID token

In this scenario, perform the validations using the [JSON Web Token Sample Code](https://github.com/auth0/node-jsonwebtoken), which verifies the token's signature (`jwt.verify`), decodes the token, checks whether the payload contains `amr`, and if so, logs the results in the console.

<AuthCodeBlock />

## Learn more

* [ID Tokens](/docs/secure/tokens/id-tokens)
* [Rule Use Cases](/docs/customize/rules/use-cases)
* [JSON Web Tokens](/docs/secure/tokens/json-web-tokens)
* [Configure Step-up Authentication for APIs](/docs/secure/multi-factor-authentication/step-up-authentication/configure-step-up-authentication-for-apis)


# WebAuthn as Multi-Factor Authentication
Source: https://auth0.com/docs/secure/multi-factor-authentication/webauthn-as-mfa

Brief overview of how WebAuthn works as a factor for MFA

When users authenticate with WebAuthn, they use something **they have** as an authentication factor: a security key, or a device.

Both Security Keys and Device Biometrics support **user verification**, which requires users provide something **they know** (a PIN or a passcode) and something **they are** (like biometric traits).

When using Device Biometrics, user verification is always performed. To perform verification with Security Keys, you [need to configure Auth0](/docs/secure/multi-factor-authentication/fido-authentication-with-webauthn/configure-webauthn-security-keys-for-mfa) to require a PIN. Then users will be asked to enter a PIN, which is only stored in the security key, to complete authentication. Now when user verification is performed, users can login with WebAuthn as the only authentication method to achieve <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip>.

By using WebAuthn for authentication combined with user verification, you not only replace the password with something much simpler to use, you also remove the need of having another authentication step when requiring MFA.

## Webauthn.me

Auth0 maintains [webauthn.me](https://a0.to/webauthme-auth0-docs), which has [detailed information](https://webauthn.me/introduction) about WebAuthn and an up-to-date list of browsers supporting WebAuthn.


# Security Center
Source: https://auth0.com/docs/secure/security-center

Learn about Security Center, which provides observability tools that empower you to see potential attack trends and quickly respond to them in real-time.

Security Center provides observability tools that allow you to see potential attack trends and quickly respond to them in real-time. Security Center provides real-time monitoring that allows you to observe your own Customer Identity and Access Management (CIAM) anomaly detection metrics, and lets you configure attack mitigation features from within the same space.

## Real-time monitoring

Security Center provides you with an overview of your tenant’s security pulse and allows you to drive outcomes from within the Auth0 Management Dashboard. In Security Center, you can:

* Monitor your total traffic and total threats
* Observe threat behavior trends
* Identify applications associated with threat behavior trends
* Track login and signup traffic
* Monitor threats identified by our <Tooltip href="/docs/glossary?term=Attack+Protection">Attack Protection</Tooltip> and <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> features

### Filtering and aggregation

Security Center allows you to filter available data to your needs.

You can filter data based on the following fields:

* Time period (up to the last 14 days)
* Applications
* Connections

Depending on the time period you select, the data is automatically aggregated per minute, per hour, or per day.

### Threat behavior trends

Security Center allows you to observe threat behavior trends for the following threat types:

* **Credential stuffing**: Behavioral patterns that appear to involve a machine attempt with the goal of submitting credentials to compromise user accounts.
* **Signup attack**: Behavioral patterns that appear to involve a machine attempt with the goal of creating new user accounts.
* **MFA bypass**: Behavior patterns that appear to involve a machine attempt with the goal of circumventing user multi-factor authentication (MFA) protections.

Views allow you to slice data by threat type and identify applications associated with threat behavior trends.

<Frame>
  <img alt="Screenshot shows a dashboard, a line graph, a horizontal bar chart, and a doughnut chart. The dashboard details the total traffic, total threats, and percentage of threats. The line graph details threat behavior trends by traffic type. Separate lines exist for normal traffic, credential stuffing, signup attacks, and MFA bypass threats. The horizontal bar chart details threat behavior by app. Each bar represents a specific app and different threat types are color coded within the bar. The doughnut chart details the threat behavior type breakdown and different threat types are color coded within the doughnut." />
</Frame>

### Authentication events

Security Center allows you to inspect authentication events, including login attempts and signup attempts.

<Frame>
  <img alt="Screenshot shows two line graphs. One shows the number of login attempts in the last 7 days. Separate lines are shown for successful logins and failed logins. The other shows the number of signup attempts over the last 7 days. Separate lines are shown for successful signups and failed signups." />
</Frame>

#### Login attempts

Login attempts include both successful and failed login transactions over the last seven days.

#### Signup attempts

Signup attempts include both successful and failed signup transactions over the last seven days.

### Attack Protection and MFA monitoring

Security Center helps you understand current attack trends identified by our Attack Protection and MFA features, and allows you to implement countermeasures by enabling and configuring these features:

<Callout icon="file-lines">
  We will identify patterns that are usually an indicator of known attack types and log-related events, regardless of whether you selected countermeasures when configuring our Attack Protection features.
</Callout>

<Frame>
  <img alt="Screenshot shows multiple line graphs for the Security Center Threat Protection tab." />
</Frame>

#### Bot detection

<Tooltip href="/docs/glossary?term=Bot+detection">Bot detection</Tooltip> mitigates scripted attacks by detecting when a request is likely to be coming from a bot. Bot detection includes the number of bots detected over the last seven days.

To learn more about this feature, read [Bot Detection](/docs/secure/attack-protection/bot-detection).

#### Suspicious IP throttling

<Tooltip href="/docs/glossary?term=Suspicious+IP+throttling">Suspicious IP throttling</Tooltip> blocks traffic from any IP address that rapidly attempts too many logins or signups. Suspicious IP throttling includes the number of suspicious IPs blocked over the last seven days.

To learn more about this feature, read [Suspicious IP Throttling](/docs/secure/attack-protection/suspicious-ip-throttling).

#### Brute-force protection

<Tooltip href="/docs/glossary?term=Brute-force+protection">Brute-force protection</Tooltip> safeguards against a single IP address attacking a single user account. Brute-force protection includes the number of blocked brute-force attempts over the last seven days.

To learn more about this feature, read [Brute-Force Protection](/docs/secure/attack-protection/brute-force-protection).

#### Breached password detection

<Tooltip href="/docs/glossary?term=Breached+password+detection">Breached password detection</Tooltip> protects your applications from <Tooltip href="/docs/glossary?term=bad+actors">bad actors</Tooltip> signing up or logging in with stolen credentials. Breached password detection includes the number of breached credentials detected in login and signup flows over the last seven days.

To learn more about this feature, read [Breached Password Detection](/docs/secure/attack-protection/breached-password-detection).

#### Multi-factor authentication

Multi-factor authentication (MFA) verifies users by requiring more than one type of user validation. MFA includes the number of MFA challenges detected and the number of MFA challenges passed or failed over the last seven days.

To learn more about this feature, read [Multi-Factor Authentication](/docs/secure/multi-factor-authentication).

## Learn more

* [Metrics](/docs/secure/security-center/metrics)


# Metrics
Source: https://auth0.com/docs/secure/security-center/metrics

Learn about the tenant log events we use to identify patterns that are usually an indicator of known attack types.

Security Center uses tenant log events to identify patterns that are usually an indicator of known attack types. We classify tenant log event patterns into categories: credential stuffing threats, signup attack threats, and <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> bypass threats.

<Warning>
  Classification of event type codes may change. Avoid implementing solutions dependent on the current log event code definitions.
</Warning>

## Credential stuffing

We identify credential stuffing threats within a single hour with the following event codes:

<table>
  <thead>
    <tr>
      <th>Event code</th>
      <th>Event</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>f</code></td>
      <td>Failed user login</td>
    </tr>

    <tr>
      <td><code>fu</code></td>
      <td>Failed user login due to invalid username</td>
    </tr>

    <tr>
      <td><code>fp</code></td>
      <td>Failed user login due to invalid password</td>
    </tr>

    <tr>
      <td><code>pwd\_leak</code></td>
      <td>Attempted login with a leaked password</td>
    </tr>

    <tr>
      <td><code>limit\_wc</code></td>
      <td>IP blocked for >10 failed login attempts to a single account</td>
    </tr>

    <tr>
      <td><code>limit\_sul</code></td>
      <td>User blocked for >20 login per minute from the same IP address</td>
    </tr>

    <tr>
      <td><code>limit\_mu</code></td>
      <td>IP blocked for >100 failed login attempts or >50 signup attempts</td>
    </tr>
  </tbody>
</table>

## Signup attack

We identify signup attack threats within a single hour with the following event codes:

<table>
  <thead>
    <tr>
      <th>Event code</th>
      <th>Event</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>fs</code></td>
      <td>Failed signup</td>
    </tr>
  </tbody>
</table>

## MFA bypass

We identify MFA bypass threats within a single hour with the following event codes:

<table>
  <thead>
    <tr>
      <th>Event code</th>
      <th>Event</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>gd\_send\_email</code></td>
      <td>Sent email</td>
    </tr>

    <tr>
      <td><code>gd\_send\_pn</code></td>
      <td>Sent push notification</td>
    </tr>

    <tr>
      <td><code>gd\_send\_sms</code></td>
      <td>Sent SMS</td>
    </tr>

    <tr>
      <td><code>gd\_send\_voice</code></td>
      <td>Sent voice call</td>
    </tr>

    <tr>
      <td><code>gd\_auth\_failed</code></td>
      <td>Failed OTP authentication</td>
    </tr>

    <tr>
      <td><code>gd\_auth\_rejected</code></td>
      <td>Rejected OTP authentication</td>
    </tr>

    <tr>
      <td><code>gd\_otp\_rate\_limit\_exceed</code></td>
      <td>Too many OTP authentication failures</td>
    </tr>

    <tr>
      <td><code>gd\_recovery\_failed</code></td>
      <td>Failed recovery</td>
    </tr>

    <tr>
      <td><code>gd\_recovery\_rate\_limit\_exceed</code></td>
      <td>Too many recovery failures</td>
    </tr>

    <tr>
      <td><code>gd\_webauthn\_challenge\_failed</code>.</td>
      <td>WebAuthn browser failure</td>
    </tr>
  </tbody>
</table>


# Prioritized Log Streams
Source: https://auth0.com/docs/secure/security-center/prioritized-log-streams

Learn more about Prioritized Log Streams, which can protect your security automation.

**Prioritized Log Streams** is a Dashboard feature that highlights security events. In the event of an attack or otherwise increased user activity, Prioritized Log Streams and predefined events will remain active so downstream security automation and processes aren't impacted.

You can create a new prioritized log stream using a supported service or configure a custom webhook to stream to a service you already use, and all logs can be exported to an event analysis service. Prioritized Log streams do not count towards the log stream limit depicted in the pricing plan.

#### Configure a Prioritized Log Stream

1. Follow the instructions on the [Log Streams page](/docs/customize/log-streams) to set up a new log stream.
2. While configuring the new stream, go to the **Settings** tab on your Auth0 Dashboard and select the **Prioritized Log** checkbox to activate the predefined security events detailed below. Choose **Save**.
3. Go to your **Stream** page and navigate to the **Prioritized** label.

#### Prioritized Logs Event Types

The following event codes are classified by Auth0 as security-related events:

<table>
  <thead>
    <tr>
      <th><strong>Event Code</strong></th>
      <th><strong>Event</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>limit\_mu</code></td>
      <td>Blocked IP Address</td>
    </tr>

    <tr>
      <td><code>limit\_sul</code></td>
      <td>Blocked Account (IP Throttling)</td>
    </tr>

    <tr>
      <td><code>limit\_wc</code></td>
      <td>Blocked Account (Brute Force Protection)</td>
    </tr>

    <tr>
      <td><code>pwd\_leak</code></td>
      <td>Breached password on Login</td>
    </tr>

    <tr>
      <td><code>ublkdu</code></td>
      <td>User login block released</td>
    </tr>

    <tr>
      <td><code>signup\_pwd\_leak</code></td>
      <td>Breached Password on Signup</td>
    </tr>

    <tr>
      <td><code>reset\_pwd\_leak</code></td>
      <td>Breached Password on Reset</td>
    </tr>

    <tr>
      <td><code>gd\_send\_sms</code></td>
      <td>MFA SMS Sent</td>
    </tr>
  </tbody>
</table>


# Configure Security Monitoring Alerts
Source: https://auth0.com/docs/secure/security-center/security-alerts

Security Alerts allow users to configure security metric thresholds in their Security Center.

**Security monitoring alerts** allow users to configure security metric thresholds in their Security Center. Numeric values for alert, warning, and recovery for each threshold can be specified, and user alert notifications can be configured to monitor when threat metric exceeds a set threshold.

<table>
  <thead>
    <tr>
      <th>Option</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Alert</td>
      <td>A required numeric value that generates an alert notice when the evaluated metric breaches the provided value.</td>
    </tr>

    <tr>
      <td>Warn</td>
      <td>An optional numeric value that creates a warning notice when the evaluated metric breaches the value, if provided.</td>
    </tr>

    <tr>
      <td>Recovery</td>
      <td>An optional numeric value that creates a recovery notice when the evaluated metric has returned to a non-breached value, if provided.</td>
    </tr>
  </tbody>
</table>

#### Configure and update alert thresholds

Thresholds are calculated on a weighted moving average for a given metric and are customizable in your <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. Each defined threshold is viewable on your threat monitor metric charts and aggregated on an hourly basis; if no recovery threshold is configured, the recovery default to just below the set warning or alert threshold.

<Warning>
  Thresholds apply to the original metric without filters. When filters are applied, the original threshold and filtered trend lines are visible.
</Warning>

<Frame>
  <img alt="A second screenshot of our Security Center Thresholds product" />
</Frame>

1. Go to [**Security > Security Center > Threat Monitoring**](https://manage.auth0.com/#/security/center/bot-detection) and choose a metric chart.
2. Select the **View Details** icon in the top right corner.
3. Navigate to the Thresholds panel displayed underneath the detailed chart view and choose **Create.**
4. Name the threshold and configure the following settings:

   * When the threshold should trigger a warning
   * When the threshold should trigger an alert
   * When the threshold should recover
5. If notification destinations have been configured, the following choices are available:

   * Select a destination to receive the metric alert, warning, and recovery notices,
   * Create a new destination by selecting the **+**
   * Mute the notification temporarily or indefinitely to all threshold destinations in the **Mute Notifications** dropdown.
6. Select **Save.**

Thresholds can also be updated or removed in the expand view screen. Different thresholds on the same chart are behind the Threshold label carrot at the top right.

#### Manage notification destinations

Notification destinations are endpoints to which alert, warning, and recovery notices are delivered. Each tenant is limited to two destination endpoints, and a third-party webhook editor is recommended to personalize the notification's message.

1. Navigate to the Manage Destinations page on your dashboard with the Thresholds configuration panel or by going to [**Security > Security Center > Manage Destinations**](https://manage.auth0.com/#/security/center/manage-destinations)
2. Select the **New Destination** button and provide the following details:

   1. Name
   2. Destination URL
   3. Authorization token
3. Choose **Save.** To delete a destination endpoint, go to **More Actions > Delete**.

#### Notification payload data

The root fields included in the notification payload are:

* `id`: ID of security center alert
* `time`: UTC date and time of the threshold breach
* `source`: URL to the Auth0 Security Center Alert History dashboard
* `data`: data object containing relevant information about the alert notification

Below is the data object included in the notification payload:

* `id`: ID of security center alert
* `tenant`: tenant where security center notification originated
* `evaluated_metric`: threat metric the threshold applies to
* `state`: state of the notification (ALERT/WARN/RECOVERED)
* `metric_value`: value of the evaluated metric over the previous 60 minutes
* `alert_threshold`: value of the alert threshold configured on the threat metric
* `warn_threshold`: value of the warn threshold configured on the threat metric
* `recovery_threshold`: value of the recovery threshold configured on the threat metric
* `triggered_at`: UTC date and time of the threshold breach.

#### View alert history

Alert, warning, and recovery notices that have occurred are viewed at [**Security > Security Center > Alert History**](https://manage.auth0.com/#/security/center/alert-history). All notices are also sent to your configured notification destinations.

<Frame>
  <img alt="Example of how the Alert History tab looks like" />
</Frame>


# Security Guidance
Source: https://auth0.com/docs/secure/security-guidance

Guidance related to security, including general tips, security bulletins, and information about data and token storage, Allow Lists, Deny Lists, and how to prevent common cyberattacks.

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/secure/security-guidance/tips">General Security Tips</a></td>
      <td>About general security tips to prevent security breaches.</td>
    </tr>

    <tr>
      <td><a href="/docs/secure/security-guidance/security-bulletins">Security Bulletins</a></td>
      <td>About Auth0 security bulletins.</td>
    </tr>

    <tr>
      <td><a href="/docs/secure/security-guidance/data-security">Data Security</a></td>
      <td>About data security related to token and user data storage, including Allow Lists and Deny Lists.</td>
    </tr>

    <tr>
      <td><a href="/docs/secure/security-guidance/prevent-threats">Prevent Common Cybersecurity Threats</a></td>
      <td>Characteristics of different types of cyberattacks and what steps can be taken to prevent them.</td>
    </tr>
  </tbody>
</table>


# Data Security
Source: https://auth0.com/docs/secure/security-guidance/data-security

Learn about data security related to token and user data storage, Allow Lists and Deny Lists.

* [Auth0 IP Addresses for Allow Lists](/docs/secure/security-guidance/data-security/allowlist) - If your environment is behind a firewall, custom database connections, Actions, Hooks, and Rules may require you to add specific Auth0 IP addresses to the AllowList to ensure proper functionality.
* [Add User Attributes to Deny List](/docs/secure/security-guidance/data-security/denylist) - If there are user fields that should not be stored in Auth0 databases due to privacy reasons, you can add user attributes to the Deny List.
* [User Data Storage](/docs/secure/security-guidance/data-security/user-data-storage) - Learn the differences between using the Auth0 data store and an external database to store user data.
* [Token Storage](/docs/secure/security-guidance/data-security/token-storage) - Learn how and where to store tokens used in token-based authentication.

## Learn more

* [Security Bulletins](/docs/secure/security-guidance/security-bulletins)
* [General Security Tips](/docs/secure/security-guidance/tips)
* [Token Best Practices](/docs/secure/tokens/token-best-practices)
* [Custom Database Connection Security Best Practices](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/connection-security)
* [Revoke Access to APIs Using Application Grants](/docs/get-started/applications/revoke-api-access)


# Auth0 IP Addresses for Allow Lists
Source: https://auth0.com/docs/secure/security-guidance/data-security/allowlist

Lists Auth0 IP addresses for use in allow lists for inbound traffic behind a firewall.

If you have custom code executing in Auth0 that calls a service inside your network, or if you've configured an on-premise SMTP provider in Auth0, then you may need to configure your firewall to allow inbound traffic from Auth0.

Features that may require you to allow inbound traffic from Auth0 include:

* [Actions](/docs/customize/actions)
* [Rules](/docs/customize/rules)
* [Hooks](/docs/customize/hooks)
* [Custom Database Action Scripts](/docs/authenticate/database-connections/custom-db/templates)
* [Log Streams](/docs/customize/log-streams)
* [External STMP Email Providers](/docs/customize/email/smtp-email-providers)

## Outbound calls

<Callout icon="file-lines">
  IP addresses are subject to change. In the event of an IP address change, Auth0 sends notifications several months before changes take place. The lists are up-to-date at the time of writing.
</Callout>

When Auth0 makes outbound calls, the IP addresses are static. Auth0 translates internal IP addresses to one of the displayed options when reaching out using NAT.

### Public Cloud

For Public Cloud tenants, the IP addresses that you must allow through your firewall are specific to the tenant's region.

#### Machine-readable list

You can access a machine-readable list of the IP CIDR ranges from Auth0 CDN: [https://cdn.auth0.com/ip-ranges.json](https://cdn.auth0.com/ip-ranges.json).

#### Schema

The machine-readable list contains the following properties:

| **Property**      | **Data type**       | **Description**                                                                                                                                                                                                                                                                                                                                                     |
| :---------------- | :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `last_updated_at` | timestamp (ISO8601) | When the list was most recently updated.                                                                                                                                                                                                                                                                                                                            |
| `regions`         | object              | Collection of [Auth0 tenant regions](/docs/get-started/auth0-overview/create-tenants#region-locality-and-sub-locality). Each tenant region object contains the following property: \* `ipv4_cidrs`: Array of strings. List of IPv4 CIDR ranges for the given region.                                                                                                |
| `changelog`       | array of objects    | Historical record of any and all addition or removal of IP CIDR ranges. Each object contains the following properties: \* `date`: String. Timestamp in YYYY-MM-DD format. \* `region`: String. Affected Auth0 region. \* `action`: String. Action performed. Possible values are: `add`, `remove`. \* `ipv4_cidrs`: Array of strings. List of affected CIDR ranges. |

#### Detecting changes

You can detect changes to the machine-readable list programmatically based on the last\_updated\_at property or based on Auth0's response to a conditional HTTP request. Auth0 updates this list ahead of any functional impact to existing tenants. Schedule a weekly programmatic check to monitor changes and maintain adequate firewall configurations.

If you send a conditional HTTP request, you can use either the If-None-Match or If-Modified-Since header. If the list has been changed, Auth0 returns a 200 (OK) HTTP response with the updated list in the body. Otherwise, Auth0 returns a 304 (Not Modified) response without a body.
To learn more about conditional HTTP requests, read [RFC 9110: HTTP Semantics on RFC Editor](https://www.rfc-editor.org/rfc/rfc9110.html#name-conditional-requests).

#### Example of conditional HTTP request (If-None-Match header)

```curl theme={null}
# The first request.
$ curl https://cdn.auth0.com/ip-ranges.json
HTTP/2 200
last-modified: Tue, 22 Apr 2025 07:50:08 GMT
etag: "1652cbe64a22099d62424fbec1022da5"
...

# Content has not changed, response is `HTTP 304`
$ curl https://cdn.auth0.com/ip-ranges.json \
       -H "If-None-Match: 1652cbe64a22099d62424fbec1022da5" 
HTTP/2 304
last-modified: Tue, 22 Apr 2025 07:50:08 GMT
etag: "1652cbe64a22099d62424fbec1022da5"
...

# Content has changed, response is `HTTP 200` with new `etag`:
$ curl https://cdn.auth0.com/ip-ranges.json \
       -H "If-None-Match: 1652cbe64a22099d62424fbec1022da5" 
HTTP/2 200
last-modified: Mon, 07 Jul 2025 01:04:18 GMT
etag: "8e58c97d39a67706c644cbe3b5c682d3"
...
```

#### Example of conditional HTTP request (If-Modified-Since header)

```curl theme={null}
# The first request.
$ curl https://cdn.auth0.com/ip-ranges.json
HTTP/2 200
last-modified: Tue, 22 Apr 2025 07:50:08 GMT
etag: "1652cbe64a22099d62424fbec1022da5"
...

# Content has not changed, response is `HTTP 304`
$ curl https://cdn.auth0.com/ip-ranges.json \
       -H "If-Modified-Since: Tue, 22 Apr 2025 07:50:08 GMT" 
HTTP/2 304
last-modified: Tue, 22 Apr 2025 07:50:08 GMT
etag: "1652cbe64a22099d62424fbec1022da5"
...

# Content has changed, response is `HTTP 200` with new `etag`:
$ curl https://cdn.auth0.com/ip-ranges.json \
       -H "If-Modified-Since: Tue, 22 Apr 2025 07:50:08 GMT"
HTTP/2 200
last-modified: Mon, 07 Jul 2025 01:04:18 GMT
etag: "8e58c97d39a67706c644cbe3b5c682d3"
...
```

### Outbound IP addresses by region

The list of IP addresses for each region are listed below:

#### United States

174.129.105.183, 18.116.79.126, 18.117.64.128, 18.191.46.63, 18.218.158.118, 18.218.26.94, 18.232.225.224, 18.233.90.226, 3.131.238.180, 3.131.55.63, 3.132.201.78, 3.133.18.220, 3.134.176.17, 3.19.44.88, 3.20.16.23, 3.20.244.231, 3.21.254.195, 3.211.189.167, 34.211.191.214, 34.233.19.82, 34.233.190.223, 35.160.3.103, 35.162.47.8, 35.166.202.113, 35.167.74.121, 35.171.156.124, 35.82.131.220, 44.205.93.104, 44.218.235.21, 44.219.52.110, 44.224.190.45, 44.246.144.93, 52.12.243.90, 52.14.149.14, 52.2.61.131, 52.204.128.250, 52.206.34.127, 52.33.36.223, 52.43.255.209, 52.88.192.232, 52.89.116.72, 54.145.227.59, 54.157.101.160, 54.200.12.78, 54.209.32.202, 54.245.16.146, 54.245.93.221, 54.68.157.8, 54.69.107.228

#### Europe

18.197.9.11, 18.198.229.148, 3.125.185.137, 3.65.249.224, 3.67.233.131, 3.68.125.137, 3.72.27.152, 3.74.90.247, 34.246.118.27, 35.157.198.116, 35.157.221.52, 52.17.111.199, 52.19.3.147, 52.208.95.174, 52.210.121.45, 52.210.122.50, 52.28.184.187, 52.30.153.34, 52.57.230.214, 54.228.204.106, 54.228.86.224, 54.73.137.216, 54.75.208.179, 54.76.184.103

#### Australia

13.210.52.131, 13.238.180.132, 13.55.232.24, 16.50.37.252, 16.51.137.244, 16.51.49.47, 54.153.131.0, 54.252.2.143, 54.79.31.78

#### Canada

15.222.97.193, 3.97.144.31, 40.176.144.225, 40.176.166.165, 40.177.34.170, 99.79.94.44

#### Japan

13.208.85.227, 15.152.185.222, 15.152.2.46, 15.152.28.221, 15.152.56.146, 15.152.95.63, 176.34.22.106, 35.74.30.168, 43.206.201.6, 46.51.243.250, 54.150.87.80, 54.248.192.141

#### United Kingdom

18.135.40.36, 3.10.89.10, 3.8.59.62

### Private Cloud

For Private Cloud tenants, the IP addresses that you must allow through your firewall are unique to the tenant's environment. Auth0 may receive your tenant's private IP addresses if you enable features like Tenant Logs, <Tooltip href="/docs/glossary?term=Suspicious+IP+throttling">Suspicious IP throttling</Tooltip>, Custom Databases, and Actions that rely on them.

These IP addresses are known as **Primary Egress IPs** and are listed under the environment's configuration data available in the [Auth0 Support Center](https://support.auth0.com/tenants/private).

## Inbound calls

IP addresses related to inbound calls to Auth0 may be variable due to the lack of fixed IP addresses on the load balancers. In this case, firewall rules should operate on the name of the service (for example: `<YOUR_TENANT>.<YOUR_REGION>.auth0.com`).

If your Auth0 subscription allows you to configure a self-managed <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip>, you can configure that custom domain to have a static IP address. Self-managed custom domains give you control over the network entry point and let you ensure that the IP address is fixed. For information on subscription plans, see [Auth0 Pricing](https://auth0.com/pricing).

## Learn more

* [Auth0 Public Cloud Service Endpoints](/docs/troubleshoot/customer-support/operational-policies/public-cloud-service-endpoints)
* [Configure External SMTP Email Providers](/docs/customize/email/smtp-email-providers)
* [Custom Database Connection Security Best Practices](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/connection-security)


# Add User Attributes to Deny List
Source: https://auth0.com/docs/secure/security-guidance/data-security/denylist

Describes how to identify user attributes that you do not want to save in Auth0 databases.

If there are user fields that should not be stored in Auth0 databases due to privacy reasons, you can add them to the Deny List. To add attributes to the Deny List, make a `PATCH` call to the Update Connection endpoint of the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

1. Get a valid access token to access the `/patch_connections_by_id` [endpoint](https://auth0.com/docs/api/management/v2#!/Connections/patch_connections_by_id). The token must include the `update:connections` scope. See [Management API Access Tokens](/docs/secure/tokens/access-tokens/management-api-access-tokens) for details.
2. With the access token and the list of attributes to be denied, call the API. Here is an example HTTP request that denies two attributes: ethnicity and gender. Keep in mind you need to retrieve the options object and send the whole object in your PATCH request as there is no "merge" when you only update one or two values.

<AuthCodeGroup>
  ```bash cURL theme={null}
      curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/connections/YOUR_CONNECTION_ID' \
    --header 'authorization: Bearer YOUR_TOKEN' \
    --header 'content-type: application/json' \
    --data '{"options": {"non_persistent_attrs": ["ethnicity", "gender"]}}'

  ```

  ```csharp C# theme={null}
      var client = new RestClient("https://{yourDomain}/api/v2/connections/YOUR_CONNECTION_ID");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("authorization", "Bearer YOUR_TOKEN");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"options": {"non_persistent_attrs": ["ethnicity", "gender"]}}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);

  ```

  ```go Go theme={null}
      package main

  import (
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
  )

  func main() {

    url := "https://{yourDomain}/api/v2/connections/YOUR_CONNECTION_ID"

    payload := strings.NewReader("{"options": {"non_persistent_attrs": ["ethnicity", "gender"]}}")

    req, _ := http.NewRequest("PATCH", url, payload)

    req.Header.Add("authorization", "Bearer YOUR_TOKEN")
    req.Header.Add("content-type", "application/json")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

  }

  ```

  ```java Java theme={null}
      HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/connections/YOUR_CONNECTION_ID")
    .header("authorization", "Bearer YOUR_TOKEN")
    .header("content-type", "application/json")
    .body("{"options": {"non_persistent_attrs": ["ethnicity", "gender"]}}")
    .asString();

  ```

  ```javascript Node.JS theme={null}
      var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/connections/YOUR_CONNECTION_ID',
    headers: {authorization: 'Bearer YOUR_TOKEN', 'content-type': 'application/json'},
    data: {options: {non_persistent_attrs: ['ethnicity', 'gender']}}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });

  ```

  ```objc Obj-C theme={null}
      #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer YOUR_TOKEN",
                            @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"options": @{ @"non_persistent_attrs": @[ @"ethnicity", @"gender" ] } };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/connections/YOUR_CONNECTION_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];

  ```

  ```php PHP theme={null}
      $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/connections/YOUR_CONNECTION_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 => "{"options": {"non_persistent_attrs": ["ethnicity", "gender"]}}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer YOUR_TOKEN",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }

  ```

  ```python Python theme={null}
      import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"options": {"non_persistent_attrs": ["ethnicity", "gender"]}}"

  headers = {
      'authorization': "Bearer YOUR_TOKEN",
      'content-type': "application/json"
      }

  conn.request("PATCH", "/{yourDomain}/api/v2/connections/YOUR_CONNECTION_ID", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))

  ```

  ```ruby Ruby theme={null}
      require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/connections/YOUR_CONNECTION_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["authorization"] = 'Bearer YOUR_TOKEN'
  request["content-type"] = 'application/json'
  request.body = "{"options": {"non_persistent_attrs": ["ethnicity", "gender"]}}"

  response = http.request(request)
  puts response.read_body

  ```

  ```swift Swift theme={null}
      import Foundation

  let headers = [
    "authorization": "Bearer YOUR_TOKEN",
    "content-type": "application/json"
  ]
  let parameters = ["options": ["non_persistent_attrs": ["ethnicity", "gender"]]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/connections/YOUR_CONNECTION_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()

  ```
</AuthCodeGroup>

Where:

1. `{yourConnectionId}` is the [connection ID](/docs/authenticate/identity-providers/locate-the-connection-id) for which these attributes will be denied.
2. `{yourToken}` is the access token you received in the previous step.
3. `options.non_persistent_attrs` object holds an array of the attributes that will be denied. If the claim that you want to deny is being sent by an upstream Identity Provider (IdP), you should set the claim exactly as sent by the upstream IdP. For example, for a claim received as `https://acme.com/temporary_idtoken`, the above sample `non_persistent_attrs` object would read:

   ```json wrap lines theme={null}
   {"non_persistent_attrs": ["ethnicity", "gender", "https://acme.com/temporary_idtoken"]}
   ```

## Limitations

* Only [root fields](/docs/manage-users/user-accounts/user-profiles/user-profile-structure) (such as `user.name` or `user.phone_number`) can be denied.

  * If `user.name` or `user.nickname` are denied, they will not be included in tokens.
  * If `user.email` is denied, the value cannot be mapped to a custom claim. For example, in a rule, `context.idToken[namespace + 'work_email'] = user.email` would not work.
* When you deny attributes, they will still be available via rules and outgoing tokens. However, if any of the following apply, the Deny List attributes will **not** be included in tokens:

  * You have enabled multi-factor authentication (MFA)
  * You have performed a redirect via rules
  * Your app is using delegation (and you haven't set `scope = passthrough`)
  * Your app is using impersonation
  * You have enabled the **Use Auth0 instead of the IdP to do Single Sign-On** setting (legacy tenants only)
* For SAMLP connections, if you enable Debug mode, your logs will contain information on the Deny List attributes

If any of these limitations are unacceptable, you can write a [rule](/docs/customize/rules) to encrypt the data and have the data persist to the `user.app_metadata` object.

## Learn more

* [Revoke Access to APIs Using Application Grants](/docs/get-started/applications/revoke-api-access)
* [Auth0 IP Addresses for Allow Lists](/docs/secure/security-guidance/data-security/allowlist)


# Token Storage
Source: https://auth0.com/docs/secure/security-guidance/data-security/token-storage

Learn how and where to store tokens used in token-based authentication.

<Card title="Overview">
  Key Concepts

  * How you decide to store your token is crucial to defending your application against malicious attacks.
  * Review scenarios for each application type.
  * Decide which method best supports your technology.
</Card>

Securing SPAs that make API calls come with their own set of concerns. You'll need to ensure that tokens and other sensitive data are not vulnerable to [cross-site scripting](https://owasp.org/www-community/attacks/xss/) (XSS) and can't be read by malicious JavaScript.

To learn more, see [JWT Handbook](https://auth0.com/resources/ebooks/jwt-handbook) and [The Ultimate Guide to Next.js Authentication with Auth0](https://auth0.com/blog/ultimate-guide-nextjs-authentication-auth0/?utm_source=twitter\&utm_medium=sc\&utm_campaign=nextjs_authn_guide).

#### Next.js static site scenarios

When you're building a Next.js application, authentication might be needed in the following cases:

1. When accessing a page
2. When accessing an API route
3. When your application calls an API hosted outside of your Next.js application on behalf of the user

Where a server is available, your app can handle the interaction with Auth0 and create a session, but in this model, we don't have a backend. All of the work happens on the frontend:

1. The user is redirected to Auth0.
2. When the user is successfully signed in, they will be redirected back to the application.
3. The client-side will complete the code exchange with Auth0 and retrieve the user's `id_token` and `access_token` which will be stored in memory.

   <Frame>
     <img alt="Token Storage Best Practices In-Memory Storage diagram" />
   </Frame>

<Tabs>
  <Tab title="Traditional web app">
    If your app is using a sign in scenario that doesn't require API calls, only an ID token is required. There is no need to store it. You can validate it and get the data from it that you required.

    If your app needs to call APIs on behalf of the user, access tokens and (optionally) refresh tokens are needed. These can be stored server-side or in a session cookie. The cookie needs to be encrypted and have a maximum size of 4 KB. If the data to be stored is large, storing tokens in the session cookie is not a viable option.

    Use the following flow types in these scenarios:

    * [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow)
    * [Regular Web App Quickstarts](/docs/quickstart/webapp)
  </Tab>

  <Tab title="Native/Mobile app">
    Store tokens in a secure storage that the OS offers and limit access to that storage. For example, leverage KeyStore for Android and KeyChain for iOS.

    Use the following flow types in these scenarios:

    * [Authorization Code Flow with Proof Key for Code Exchange](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce)
    * [Save and Renew Tokens for Swift](/docs/libraries/auth0-swift/auth0-swift-save-and-renew-tokens)
    * [Native/Mobile Apps Quickstarts](/docs/quickstart/native)
  </Tab>

  <Tab title="Single-page app">
    We recommend using the [Auth0 SPA SDK](/docs/libraries/auth0-single-page-app-sdk) to handle token storage, session management, and other details for you.

    When the SPA calls only an API that is served from a domain that can share cookies with the domain of the SPA, no tokens are needed. OAuth adds additional attack vectors without providing any additional value and should be avoided in favor of a traditional cookie-based approach.

    When the SPA calls multiple APIs that reside in a different domain, access, and optionally, refresh tokens are needed.

    * If the SPA backend can handle the API calls, then it functions similarly to a tradition web application that handle tokens server-side using:

      * [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow)
      * [Authorization Code Flow with Proof Key for Code Exchange](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce)
    * If the SPA backend cannot handle the API calls, then it functions similarly to a mobile application that stores tokens in the SPA backend, but the SPA needs to fetch the tokens from the backend to perform requests to the API. A protocol needs to be established between the backend and the SPA to allow the secure transfer of the token from the backend to the SPA.
    * If you have a SPA with **no** corresponding backend server, your SPA should request new tokens on login and store them in memory without any persistence. To make API calls, your SPA would then use the in-memory copy of the token.

    <Callout icon="file-lines">
      In compliance with the OAuth2 specifications, when a browser requests a refresh token from the /token endpoint, Auth0 will only return a Refresh Token if [Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation) is enabled for that client.
    </Callout>

    For more details, see [Auth0 SPA SDK in GitHub](https://github.com/auth0/auth0-spa-js).
  </Tab>
</Tabs>

### Browser in-memory scenarios

Auth0 recommends storing tokens in browser memory as the most secure option. Using [Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) to handle the transmission and storage of tokens is the best way to protect the tokens, as Web Workers run in a separate global scope than the rest of the application. Use Auth0 SPA SDK whose default storage option is in-memory storage leveraging Web Workers.

If you cannot use Web Workers, Auth0 recommends as an alternative that you use [JavaScript closures](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Closures#emulating_private_methods_with_closures) to emulate private methods.

Use Auth0 SPA SDK whose default storage option is in-memory storage to leverage both Web Workers and JavaScript closures depending on the type of token.

<Callout icon="file-lines">
  The in-memory method for browser storage **does not** provide persistence across page refreshes and browser tabs.
</Callout>

### Browser local storage scenarios

Using browser local storage can be a viable alternative to mechanisms that require retrieving the <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> from an iframe and to cookie-based authentication across domains when these are not possible due to browser restrictions (for example, ITP2).

<Warning>
  Storing tokens in browser local storage provides persistence across page refreshes and browser tabs, however if an attacker can achieve running JavaScript in the SPA using a cross-site scripting (XSS) attack, they can retrieve the tokens stored in local storage. A vulnerability leading to a successful XSS attack can be either in the SPA source code or in any third-party JavaScript code (such as bootstrap, jQuery, or Google Analytics) included in the SPA.
</Warning>

To reduce security risks if your SPA is using implicit (we recommend using authorization code flow with PKCE instead) or hybrid flows, you can reduce the absolute token expiration time. This reduces the impact of a reflected XSS attack (but not of a persistent one). To reduce the expiration time, go to **Dashboard > APIs > Settings > Token Expiration For Browser Flows (Seconds)**.

Reduce the amount of third-party JavaScript code included from a source outside your domain to the minimum needed (such as links to jQuery, Bootstrap, Google Analytics etc.) Reducing third-party JS code reduces the possibility of an XSS vulnerability. Performing [Subresource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Subresource_Integrity) checking in third-party scripts (where possible) to verify that the resources fetched are delivered without unexpected manipulation is also more secure.

## Learn more

* [ID Tokens](/docs/secure/tokens/id-tokens)
* [Access Tokens](/docs/secure/tokens/access-tokens)
* [Refresh Tokens](/docs/secure/tokens/refresh-tokens)
* [Token Best Practices](/docs/secure/tokens/token-best-practices)


# User Data Storage
Source: https://auth0.com/docs/secure/security-guidance/data-security/user-data-storage

Learn the differences between using the Auth0 data store and an external database to store user data.

Auth0 stores user information for your tenant in a hosted cloud database, or you can choose to store user data in your own custom external database.

To store user data beyond the basic information Auth0 uses for authentication, you can use the Auth0 data store or a custom database. However, if you use the additional data for authentication purposes, we recommend that you use the Auth0 data store, as this allows you to manage your user data through the [Auth0 Management Dashboard](https://manage.auth0.com/#).

## External database vs. Auth0 data store

The Auth0 data store is customized for authentication data. Storing anything beyond the default user information should be done only in limited cases. Here's why:

* **Scalability**: The Auth0 data store is limited in scalability, and your Application's data may exceed the appropriate limits. By using an external database, you keep your Auth0 data store simple, while the more efficient external database contains the extra data;
* **Performance**: Your authentication data is likely accessed at lower frequencies than your other data. The Auth0 data store isn't optimized for high-frequency use, so you should store data that needs to be retrieved more often elsewhere;
* **Flexibility**: Because the Auth0 data store was built to accommodate only user profiles and their associated metadata, you are limited in terms of the actions you can perform on the database. By using separate databases for your other data, you can manage your data as appropriate and perform direct calls without use of Auth0's <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

When outsourcing user authentication, there is usually no need to maintain your own users/passwords table. Even so, you may still want to associate application data with authenticated users.

* For example, you could have a Users table that lists each user authenticated by Auth0. Every time a user logs in, you could search the table for that user. If the user does not exist, you would create a new record. If they do exist, you would update all fields, essentially keeping a local copy of all user data.
* Alternatively, you could store the user identifier in each table/collection that has user-associated data. This is a simpler implementation suited to smaller applications.

## User data storage example scenario

Auth0 provides a sample app, a mobile music application, that reflects the end-to-end user experience when using Auth0 with a custom external database. The sample app is an iOS app created using the [Auth0 iOS seed project](/docs/quickstart/native/ios-swift). The backend uses the [Node.js API](/docs/quickstart/backend/nodejs).

For a visualization of the application's overall structure, see the [Mobile + API architecture scenario](/docs/get-started/architecture-scenarios/mobile-api).

### Metadata

#### App metadata

The following data points from our mobile music application are appropriate to store in `app_metadata`:

* User's subscription plan
* User's right (or lack thereof) to edit featured playlists

These two data points should be stored in `app_metadata` instead of `user_metadata` because they should not be directly changeable by the user.

#### User metadata

The following data points from our mobile music application are appropriate to store in `user_metadata`:

* Application preferences
* Details chosen by the user to alter their experience of the app upon login.

Note that, unlike the data points for `app_metadata`, the user can easily and readily change those stored in `user_metadata`.

We can let the user change their `displayName`, which is the name the user sees upon logging in and is displayed to other users of the app.

To display the user's chosen identifier whenever they log in, we use a rule to get the `user.user_metadata` value.

```javascript lines theme={null}
function(user, context, callback){
  user.user_metadata = user.user_metadata || {};
  user.user_metadata.displayName = user.user_metadata.displayName || "user";

  auth0.users.updateUserMetadata(user.user_id, user.user_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}
```

Here's a look at the screen the user would use to change their `displayName`:

<Frame>
  <img alt="iOS app settings screen with option to update display name." />
</Frame>

To save the changes to the database, the application makes a call to the [Get a User](https://auth0.com/docs/api/management/v2#!/Users/get_users_by_id) endpoint of the Management API to identify the appropriate user:

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request GET \
    --url https://%7ByourAccount%7D.auth0.com/api/v2/users/user_id \
    --header 'authorization: Bearer {yourIdToken}'
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://%7ByourAccount%7D.auth0.com/api/v2/users/user_id");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer {yourIdToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://%7ByourAccount%7D.auth0.com/api/v2/users/user_id"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer {yourIdToken}")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java lines theme={null}
  HttpResponse<String> response = Unirest.get("https://%7ByourAccount%7D.auth0.com/api/v2/users/user_id")
    .header("authorization", "Bearer {yourIdToken}")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://%7ByourAccount%7D.auth0.com/api/v2/users/user_id',
    headers: {authorization: 'Bearer {yourIdToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C lines theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourIdToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://%7ByourAccount%7D.auth0.com/api/v2/users/user_id"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP lines theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://%7ByourAccount%7D.auth0.com/api/v2/users/user_id",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourIdToken}"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {yourIdToken}" }

  conn.request("GET", "%7ByourAccount%7D.auth0.com/api/v2/users/user_id", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://%7ByourAccount%7D.auth0.com/api/v2/users/user_id")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer {yourIdToken}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift lines theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourIdToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://%7ByourAccount%7D.auth0.com/api/v2/users/user_id")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

This is followed by a call to the [Update a User](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id) endpoint to update the `user_metadata` field:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/users/user_id' \
    --header 'authorization: Bearer {yourAccessToken}' \
    --header 'content-type: application/json' \
    --data '{"user_metadata": {"displayName": "J-vald3z"}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/user_id");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("authorization", "Bearer {yourAccessToken}");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"user_metadata": {"displayName": "J-vald3z"}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users/user_id"

  	payload := strings.NewReader("{"user_metadata": {"displayName": "J-vald3z"}")

  	req, _ := http.NewRequest("PATCH", url, payload)

  	req.Header.Add("authorization", "Bearer {yourAccessToken}")
  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/users/user_id")
    .header("authorization", "Bearer {yourAccessToken}")
    .header("content-type", "application/json")
    .body("{"user_metadata": {"displayName": "J-vald3z"}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/users/user_id',
    headers: {authorization: 'Bearer {yourAccessToken}', 'content-type': 'application/json'},
    data: '{"user_metadata": {"displayName": "J-vald3z"}'
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourAccessToken}",
                             @"content-type": @"application/json" };

  NSData *postData = [[NSData alloc] initWithData:[@"{"user_metadata": {"displayName": "J-vald3z"}" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/user_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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/user_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 => "{"user_metadata": {"displayName": "J-vald3z"}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourAccessToken}",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"user_metadata": {"displayName": "J-vald3z"}"

  headers = {
      'authorization': "Bearer {yourAccessToken}",
      'content-type': "application/json"
      }

  conn.request("PATCH", "/{yourDomain}/api/v2/users/user_id", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/user_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["authorization"] = 'Bearer {yourAccessToken}'
  request["content-type"] = 'application/json'
  request.body = "{"user_metadata": {"displayName": "J-vald3z"}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer {yourAccessToken}",
    "content-type": "application/json"
  ]

  let postData = NSData(data: "{"user_metadata": {"displayName": "J-vald3z"}".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/user_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()
  ```
</AuthCodeGroup>

You must replace `{yourAccessToken}` with a [Management API Access Token](https://auth0.com/docs/api/management/v2/concepts/tokens).

### User data permission rules

Use [rules](/docs/customize/rules) to implement permissions on whether a user can edit featured playlists or not.

#### Assign Playlist Editor role

The first rule sends a request to our Node API, which then queries the database connected to Heroku to check how many plays the user’s playlist has. If the number is 100 or greater, we assign `playlist_editor` as a value in the `roles` array in `app_metadata`.

```javascript lines expandable theme={null}
function (user, context, callback) {

  var request = require('request');

  user.app_metadata = user.app_metadata || {};
  user.app_metadata.roles = user.roles || [];

  var CLIENT_SECRET = configuration.AUTH0_CLIENT_SECRET;
  var CLIENT_ID = configuration.AUTH0_CLIENT_ID;

  var scope = {
    user_id: user.user_id,
    email: user.email,
    name: user.name
  };

  var options = {
    subject: user.user_id,
    expiresInMinutes: 600,
    audience: CLIENT_ID,
    issuer: 'https://example.auth0.com'
  };

  var id_token = jwt.sign(scope, CLIENT_SECRET, options);

  var auth = 'Bearer ' + id_token;

  request.get({
    url: 'https://example.com/playlists/getPlays',
    headers: {
       'Authorization': auth,
      'Content-Type': 'text/html'
    },
    timeout: 15000
  }, function(err, response, body){
    if (err)
      return callback(new Error(err));
    var plays = parseInt(body, 10);

    if (plays >= 100 && user.roles.indexOf('playlist_editor') < 0){
      user.app_metadata.roles.push('playlist_editor');
      auth0.users.updateAppMetadata(user.user_id, user.app_metadata)
        .then(function(){
          callback(null, user, context);
        })
        .catch(callback);
    }

    else if (plays < 100 && user.roles.indexOf('playlist_editor') >= 0){
      user.app_metadata.roles = [];
      auth0.users.updateAppMetadata(user.user_id, user.app_metadata)
        .then(function(){
          callback(null, user, context);
        })
        .catch(callback);
    }
    else{
      callback(null, user, context);
    }

  });

}
```

#### Scope parameter specifies role

The second rule gets the `app_metadata` field and assigns the `roles` array to a field in the user object so it can be accessed without calling `app_metadata` on the application. The `scope` parameter can then specify `roles` upon the user logging in without including everything in `app_metadata` in the user object:

```javascript lines theme={null}
function(user, context, callback) {
   if (user.app_metadata) {
      user.roles = user.app_metadata.roles;
   }
   user.roles = user.roles || [];
   callback(null, user, context);
}
```

After we've implemented these two rules, the app recognizes whether the user is a playlist editor or not and changes the welcome screen accordingly. If `playlist_editor` is in the `roles` array stored in the user's `app_metadata`, the user will be welcomed as an **EDITOR** after signing in:

<Frame>
  <img alt="Example of user profile page with editor role." />
</Frame>

#### Associate a user's music with the user

We need to associate a user's music with that user, but this information is not required for authentication. Here's how to store this information in a separate database that is integrated with the backend of the application.

The user's unique identifier is the `user_id` and it's the sub-property of the `idTokenPayload` object in an `authResult`. Here is a sample row from the `songs` table in our database:

<table>
  <thead>
    <tr>
      <th>song\_id</th>
      <th>songname</th>
      <th>user\_id</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>1</td>
      <td>Number One Hit</td>
      <td>google-oauth2</td>
    </tr>
  </tbody>
</table>

The Node.js backend authenticates requests to the URI associated with getting the user’s personal data from the database by validating a <Tooltip href="/docs/glossary?term=JSON+Web+Token">JSON Web Token</Tooltip>.

[Learn about token-based authentication and how to implement JWT in your Applications.](/docs/secure/tokens/json-web-tokens)

Here is the code implementing JWT validation from the Node.js seed project:

```javascript lines theme={null}
var genres = require('./routes/genres');
var songs = require('./routes/songs');
var playlists = require('./routes/playlists');
var displayName = require('./routes/displayName');

var authenticate = jwt({
  secret: process.env.AUTH0_CLIENT_SECRET,
  audience: process.env.AUTH0_CLIENT_ID
});

app.use('/genres', authenticate, genres);
app.use('/songs', authenticate, songs);
app.use('/playlists', authenticate, playlists);
app.use('/displayName', authenticate, displayName);
```

We can add functionality to handle different data requests from our Application. For example, if we receive a `GET` request to `/secured/getFavGenre`, the API calls the `queryGenre()` function, which queries the database for and responds with the user’s favorite genre.

```swift lines theme={null}
@IBAction func getGenre(sender: AnyObject) {
        let request = buildAPIRequest("/genres/getFav", type:"GET")
        let task = NSURLSession.sharedSession().dataTaskWithRequest(request) {[unowned self](data, response, error) in
            let genre = NSString(data: data!, encoding: NSUTF8StringEncoding)
            dispatch_async(dispatch_get_main_queue(), {
                self.favGenre.text = "Favorite Genre:  \(genre!)"
            })
        }
        task.resume()
    }
```

The function `buildAPIRequest()` takes the path and HTTP method of the request as parameters and builds a request using the base URL of our Node.js API that's hosted on Heroku.

In the Application, the `getGenre()` function makes a request to the API and changes the app's interface to display the request response to `/genres/getFav`. The backend retrieves the required data for this action using the `queryGenre()` function and returns the results to the Application:

```javascript lines theme={null}
function queryGenre(user_id, res){

  db.connect(process.env.DATABASE_URL, function(err, client) {
  if (err) throw err;

  client
    .query('SELECT fav_genre as value FROM user_data WHERE user_id = $1', [user_id], function(err, result) {

      if(err) {
        return console.error('error running query', err);
      }
      res.send(result.rows[0].value);
    });
  });

};
```

## Learn more

* [Normalized User Profiles](/docs/manage-users/user-accounts/user-profiles/normalized-user-profiles)
* [Normalized User Profile Schema](/docs/manage-users/user-accounts/user-profiles/normalized-user-profile-schema)
* [Sample User Profiles](/docs/manage-users/user-accounts/user-profiles/sample-user-profiles)


# Incident Response: Using Logs
Source: https://auth0.com/docs/secure/security-guidance/incident-response-using-logs

How to use Auth0 logs as part of your incident response plan.

Reviewing logs to assess the impact of an attack is a crucial step in your incident response plan. On this page you'll see how to access logs on the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> and some examples of log search queries to find indicators of an attack and review account activity.

## Check Auth0 logs

1. [Login to the Auth0 Dashboard](https://manage.auth0.com/#)
2. The Logs page is located under **Monitoring** in the menu on the left.
3. On the Logs page, you’ll see a search bar along with a filter selection and date picker.

<Frame>
  <img alt="Dashboard Monitoring Logs" />
</Frame>

Select a log event from the list to see a **Summary** of the event along with further **Details** including the raw JSON.

### Log structure

Each log event has the following fields:

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>date</code></td>
      <td>Timestamp when this event occurred.</td>
    </tr>

    <tr>
      <td><code>log\_id</code></td>
      <td>The id of the log event</td>
    </tr>

    <tr>
      <td><code>type</code></td>
      <td>The log event type</td>
    </tr>

    <tr>
      <td><code>description</code></td>
      <td>The description of the event.</td>
    </tr>

    <tr>
      <td><code>connection</code></td>
      <td>The connection name related to the event.</td>
    </tr>

    <tr>
      <td><code>connection\_id</code></td>
      <td>The connection id related to the event.</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>The client id related to the event</td>
    </tr>

    <tr>
      <td><code>client\_name</code></td>
      <td>The name of the client related to the event.</td>
    </tr>

    <tr>
      <td><code>ip</code></td>
      <td>The IP address from where the request that caused the log event originated.</td>
    </tr>

    <tr>
      <td><code>user\_agent</code></td>
      <td>The user agent that is related to the event.</td>
    </tr>

    <tr>
      <td><code>details</code></td>
      <td>An object containing further information for this log event.</td>
    </tr>

    <tr>
      <td><code>user\_id</code></td>
      <td>The user id related to the event.</td>
    </tr>

    <tr>
      <td><code>user\_name</code></td>
      <td>The user name related to the event.</td>
    </tr>

    <tr>
      <td><code>strategy</code></td>
      <td>The connection strategy related to the event.</td>
    </tr>

    <tr>
      <td><code>strategy\_type</code></td>
      <td>The connection strategy type related to the event.</td>
    </tr>
  </tbody>
</table>

### Example of failed login log event

Here is an example log event for a failed login due to an incorrect password:

```json lines theme={null}
{
  "date": "2020-10-27T19:39:54.699Z",
  "type": "fp",
  "description": "Wrong email or password.",
  "connection": "Username-Password-Authentication",
  "connection_id": "con_ABC123",
  "client_id": "ABCDEFG123456789",
  "client_name": "All Applications",
  "ip": "99.xxx.xxx.xxx",
  "user_agent": "Chrome 86.0.4240 / Mac OS X 10.15.6",
  "details": {
    "error": {
      "message": "Wrong email or password."
    }
  },
  "user_id": "auth0|ABC123",
  "user_name": "test@test.com",
  "strategy": "auth0",
  "strategy_type": "database",
  "log_id": "123456789",
  "_id": "123456789",
  "isMobile": false
}
```

## Indicators of an attack

Identifying an attack early on may be difficult, but here are some things to look for in your logs along with example search queries:

* High numbers of failed logins with invalid usernames or login attempts for non-existent users.

  * `type:"fu"`
  * `description:"missing username parameter"`
  * `description:"Wrong email or password"`
* Large number of accounts reaching the failed login attempts limit.

  * `type:"limit_wc"`
* A high number of login attempts using a leaked password.

  * `type:"pwd_leak"`

During your investigation take note of IP addresses, applications being targeted, and connections or <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> used.

<Callout icon="file-lines">
  The [Log Search Query Syntax](/docs/deploy-monitor/logs/log-search-query-syntax) page provides details on Auth0's log query syntax and includes more example queries.
</Callout>

## Identify compromised user accounts

To identify user accounts that may have been compromised you can search for:

* Successful login events from a suspicious IP address:

  * `type:"s" AND ip:"99.xxx.xxx.xxx"`

## Check compromised user account activity

After identifying a compromised user account you'll want to check the account's activity:

* Search for other log events with the same `user_id`: `user_id:"auth0|ABC123"`
* Check the `client_name` or `client_id` log event fields to see which applications were accessed. Make a note of when access occurred.
* Check for administration access or Auth0 configuration changes
* Search for recent <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> calls: `type:"sapi"`

## Delete or block users from the dashboard

1. Go to [Dashboard > User Management > Users](https://manage.auth0.com/#/users).
2. Search for the user to delete or block.
3. Click the "**...**" button on the far right of the user.
4. Select **Block** or **Delete** and confirm.


# Measures Against Application Impersonation
Source: https://auth0.com/docs/secure/security-guidance/measures-against-app-impersonation

Describes how to use universal links rather than custom URL schemes to verify the legitimacy of authentication data.

Native applications use the [Authorization Code Flow with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce) authentication flow and employ a `redirect_uri` to return control to the application after login. After the URI loads in the device’s browser, the application typically opens automatically to allow the user to continue their journey.

Historically, mobile application used [custom URI schemes](https://developers.google.com/identity/protocols/oauth2/native-app#installed_app_redirect_methods) (e.g., `com.mycompany.myapp://oauth2redirect`). However, custom URI schemes pose a risk as more than one application on the device can register the same scheme. Mobile OSs do not include built-in mechanisms to ensure the application receiving the redirect is the intended one. In this scenario, malicious apps impersonate legitimate ones and receive the authorization response (including tokens) without user awareness, especially if single sign-on (SSO) is active due to the existence of a previous legitimate session, in which additional user interaction is not required. PKCE doesn't really help in these scenarios, as the malicious application can initiate the login flow and wait to receive the callback without user interaction.

Applications running on a local machine (e.g., desktop apps, CLIs) use the loopback interface for callbacks (e.g., [http://127.0.0.1:51089/callback](http://127.0.0.1:51089/callback) or [http://localhost:61024/callback](http://localhost:61024/callback)) are similarly at risk. In this case, another application on the same machine could listen on the same port to intercept the response.

We refer to both custom URI schemes and loopback URIs as Non-Verifiable Callback URIs because the authorization server cannot verify the receiving application in either scenario.

## Recommended mitigations for mobile applications

### Claimed HTTPS URIs (Universal Links / App Links)

Modern mobile OSs support **claimed HTTPS URIs** allows you to associate a website domain you control with your mobile app. Claimed HTTPS URIs are known as:

* Universal Links on iOS
* App Links on Android

Claimed HTTPS URIs ensure only your application handles the associated callback URL and protects against unauthorized access to sensitive authentication data.

<Note>
  Auth0 **strongly recommends** using claimed HTTPS URIs as redirect URIs for all native applications.

  * For iOS: Review [Support Universal Links](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content/#Support-universal-links).
  * For Android: Review [Android App Links](https://developer.android.com/training/app-links).
</Note>

## Recommended mitigations for all application

Auth0 cannot verify the legitimacy of the application receiving the authentication transaction results if:

* Your application is unable to support claimed HTTPS URIs due to required compatibility with older mobile OS versions
* Your application is a desktop or CLI application

As defined in the [OAuth2 for Native Apps](https://datatracker.ietf.org/doc/html/rfc8252#section-8.6) specification, Auth0 provides a mechanism to show a confirmation prompt to the user. Users confirm the application receiving the authentication result is the one they intended to access. When a non-verifiable callback URI is in use, the user is prompted to verify the application on each authentication transaction.

The confirmation screen displays when:

1. The `redirect_uri` present in the request uses a non-verifiable URI (i.e. a custom URI scheme or a loopback URI).
2. The user has not been prompted with any other screen in the current login transaction (such as when a [consent screen](/docs/get-started/applications/confidential-and-public-applications/user-consent-and-third-party-applications) populates for third-party applications, or when MFA is required).

In these cases, the application presents the end user with a confirmation prompt.

<Frame>
  <img alt="Measures Against App Impersonation - Confirmation Prompt" />
</Frame>

The confirmation prompt is not shown in legacy non-OIDC-conformant flows. To learn how you can apply increased protection for your tenants and applications, review [Adopt OIDC-Conformant Authentication](/docs/authenticate/login/oidc-conformant-authentication).

#### Prompt customization

The confirmation prompt uses your custom branding and configurations defined for existing consent screens used for third-party applications. To learn more, review the Prompts section of [Customize Universal Login Page Templates](/docs/customize/login-pages/universal-login/customize-templates).

<Warning>
  Auth0 **strongly recommends** you do not disable this protection for production. Malicious applications on the device could request `id_tokens` and `access_tokens` without any interaction from the user or other indications that something has happened.
</Warning>

You can configure the confirmation prompt as a global tenant settings  or at the application-level. Application-level settings take precedence over the global tenant-level setting.

**Application-level**

1. [Navigate to Auth0 Dashboard > Applications > Application Settings > Advanced > OAuth](https://manage.auth0.com/#/applications/settings).
2. Scroll to the **Non-Verifiable Callback URI End-User Confirmation** setting.
3. Enable the toggle to activate the prompt or disable the toggle to deactivate the prompt.

<Frame>
  <img alt="Auth0 Dashboard>Settings>Advanced" />
</Frame>

**Global**

1. Navigate to [Auth0 Dashboard > Settings > Advanced](https://manage.auth0.com/#/tenant/advanced).
2. Find the **Non-Verifiable Callback URI End-User Confirmation** setting.
3. Enable the toggle to activate the prompt.

<Frame>
  <img alt="Auth0 Dashboard>Tenant Settings>Advanced>Skip Custom URI toggle" />
</Frame>


# Prevent Common Cybersecurity Threats
Source: https://auth0.com/docs/secure/security-guidance/prevent-threats

Describes different types of cyberattacks and what steps can be taken to prevent them.

Some common cybersecurity threats include:

* Bucket brigade attacks
* Replay attacks
* Cross-site Request Forgery (CSRF or XSRF) attacks
* Brute-force attacks
* <Tooltip href="/docs/glossary?term=Suspicious+IP+throttling">Suspicious IP throttling</Tooltip>
* Credential stuffing attacks
* List validation attacks

Auth0 has [attack protection features](/docs/secure/attack-protection) that can shield against certain types of attacks.

## Bucket brigade attacks

One type of threat is a bucket brigade attack, sometimes called a "man-in-the-middle" attack, where the attacker gets between two parties. Each party thinks they are interacting over a private connection, but the interaction is actually being controlled by the third-party attacker. For this type of attack to succeed the attacker must create mutual authentication between both parties.

Usually, bucket brigade attacks involve the attacker using a WiFi router to intercept a user's communication. The user connects to the attacker's router then visits a website and logs in with their confidential credentials. The attacker saves that user's login credentials for which they can then use to impersonate the user.

Some bucket brigade attacks can also modify the data transmitted between the application and the server. Attacks can occur from new PC trial and preinstalled software, software update tools, and other software vulnerabilities. In a worst-case scenario, this could result in remote code execution, backdooring the system, installing malware, and so on. This could also lead to the compromise of other network assets.

To help defend against this type of attack it is important to use strong encryption and authentication between the application and the server. Using encryption the server authenticates the application's request by presenting a digital certificate, and only then can the connection be established. For example, HTTPS uses the secure sockets layer (SSL) capability of the browser to mask web traffic. To decrypt HTTPS, an attacker would have to obtain the keys used to encrypt the network traffic.

With the configuration of TLS on your servers, we suggest using the [Mozilla OpSec recommendations](https://wiki.mozilla.org/Security/Server_Side_TLS) which use TLSv1.2. Mozilla also provides an [SSL Configuration Generator](https://mozilla.github.io/server-side-tls/ssl-config-generator/), to use this first choose which platform your server is running and then choose the most modern configuration based on what your application base can support. The more modern configurations provide stronger ciphers to help prevent attacks.

## Replay attacks

Replay (or playback) attacks allow attackers to:

* Gain access to a network and information which would not have been easily accessible
* Complete a duplicate transaction

These are attacks on the security protocol using replays of data transmission from a different sender into the intended receiving system. The attacks fool the participants into believing they have successfully completed the data transmission.

Replay attacks can be avoided by using session tokens. However, if these credentials are stolen from local storage (like during an XSS attack), there are ways to prevent someone from holding on to a valid token forever:

* Set a short expiration time for tokens
* Provide a way to add tokens to the DenyList that have been used (and possibly even the users)
* Use one-time passwords

The [JWT](/docs/secure/tokens/json-web-tokens) spec provides the `jti` field as a way to prevent replay attacks. Though Auth0 tokens currently don't return the `jti`, you can add tokens to the DenyList using the `jti` to prevent a token being used more than a specified number of times. In this way, you are implementing something similar to a <Tooltip href="/docs/glossary?term=nonce">nonce</Tooltip> (think of the token's signature as the nonce). If a token gets stolen or it gets used more than the specified number of times, it should be added to the DenyList. This prevents a valid token from being used maliciously. Once the token expires, the attacker will no longer be able to impersonate the user.

You can also avoid replay attacks by using one-time passwords. With Auth0, you can use <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> Authentication, which relies on single-use codes and email links instead of traditional passwords. Auth0 also provides <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA) which uses one-time passwords as a second-factor authentication which can be sent via push notifications and texts.

## Cross-site Request Forgery

A Cross-site Request Forgery (CSRF or XSRF) attack occurs when a malicious program causes a user's web browser to perform an unwanted action on a trusted site on which the user is currently authenticated. This type of attack specifically targets state-changing requests to initiate a type of action instead of getting user data because the attacker has no way to see the response of the forged request.

One way to verify the requests that are being sent is to utilize the <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> protocol [state parameter](/docs/secure/attack-protection/state-parameters) to authenticate the response.

## Learn more

* [Tokens](/docs/secure/tokens)
* [Attack Protection](/docs/secure/attack-protection)
* [General Security Tips](/docs/secure/security-guidance/tips)


# Security Bulletins
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins

Lists Auth0 security bulletins.

Here is a list of Auth0 security bulletins that address security vulnerabilities in Auth0 software. Each bulletin contains a description of the vulnerability, how to identify if you are affected, and what to do to fix it.

<table>
  <thead>
    <tr>
      <th><strong>Date</strong></th>
      <th><strong>Bulletin number</strong></th>
      <th><strong>Title</strong></th>
      <th><strong>Affected software</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>December 21, 2022</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/2022-12-21-jsonwebtoken">Auth0 Bulletin</a></td>
      <td>Auth0 security bulletin for jsonwebtoken</td>
      <td><a href="https://github.com/auth0/node-jsonwebtoken">node-jsonwebtoken</a></td>
    </tr>

    <tr>
      <td>December 12, 2022</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/cve-2022-23505">CVE-2022-23505</a></td>
      <td>Security Update for passport-wsfed-saml2 Library</td>
      <td><a href="https://github.com/auth0/passport-wsfed-saml2">passpord-wsfed-saml2</a></td>
    </tr>

    <tr>
      <td>March 30, 2022</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/cve-2022-24794">CVE-2022-24794</a></td>
      <td>Security Update for Express OpenID Connect Library</td>
      <td><a href="https://github.com/auth0/express-openid-connect">express-openid-connect</a></td>
    </tr>

    <tr>
      <td>December 16, 2021</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/cve-2021-43812">CVE-2021-43812</a></td>
      <td>Security Update for Next.js Auth0 Library \<=1.6.1</td>
      <td><a href="https://github.com/auth0/nextjs-auth0">nextjs-auth0</a></td>
    </tr>

    <tr>
      <td>December 08, 2021</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/cve-2021-41246">CVE-2021-41246</a></td>
      <td>Security Update for Express OpenID Connect >= 2.3.0, \<= 2.5.1</td>
      <td><a href="https://github.com/auth0/express-openid-connect">express-openid-connect</a></td>
    </tr>

    <tr>
      <td>June 23, 2021</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/cve-2021-32702">CVE-2021-32702</a></td>
      <td>Security Update for Auth0 Next.js \<= 1.4.1</td>
      <td><a href="https://github.com/auth0/nextjs-auth0">nextjs-auth0</a></td>
    </tr>

    <tr>
      <td>June 4, 2021</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/cve-2021-32641">CVE-2021-32641</a></td>
      <td>Security Update for Auth0 Lock \<= 11.30.0</td>
      <td><a href="https://github.com/auth0/lock">Auth0 Lock</a></td>
    </tr>

    <tr>
      <td>November 05, 2020</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/cve-2020-15259">CVE-2020-15259</a></td>
      <td>Auth0 Security Bulletin for ad-ldap-connector versions \<= 5.0.12</td>
      <td><a href="https://github.com/auth0/ad-ldap-connector">AD/LDAP Connector</a></td>
    </tr>

    <tr>
      <td>October 21, 2020</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/cve-2020-15240">CVE-2020-15240</a></td>
      <td>Security Update for omniauth-auth0 JWT Validation</td>
      <td><a href="https://github.com/auth0/omniauth-auth0">omniauth-auth0</a></td>
    </tr>

    <tr>
      <td>August 16, 2020</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/cve-2020-15119">CVE-2020-15119</a></td>
      <td>Security Update for Auth0 Lock \<= 11.25.1</td>
      <td><a href="https://github.com/auth0/lock">Auth0 Lock</a></td>
    </tr>

    <tr>
      <td>July 28, 2020</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/cve-2020-15125">CVE-2020-15125</a></td>
      <td>Auth0 Security Bulletin for node-auth0 \<= 2.27.0</td>
      <td><a href="https://github.com/auth0/node-auth0">node-auth0</a></td>
    </tr>

    <tr>
      <td>June 30, 2020</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/cve-2020-15084">CVE-2020-15084</a></td>
      <td>Auth0 Security Bulletin for express-jwt versions \< 6.0.0</td>
      <td><a href="https://github.com/auth0/express-jwt">express-jwt</a></td>
    </tr>

    <tr>
      <td>April 09, 2020</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/cve-2020-5263">CVE-2020-5263</a></td>
      <td>Auth0 Security Bulletin for auth0.js versions \<= 9.13.1</td>
      <td>Auth0.js</td>
    </tr>

    <tr>
      <td>March 31, 2020</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/2020-03-31-wpauth0">Auth0 Bulletin</a></td>
      <td>Auth0 Security Bulletin for WordPress Plugin for Auth0 versions \< 4.0.0</td>
      <td>WordPress Plugin for Auth0</td>
    </tr>

    <tr>
      <td>January 31, 2020</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/cve-2019-20173">CVE-2019-20173</a></td>
      <td>Auth0 Security Bulletin for WordPress Plugin for Auth0 versions 3.11.0, 3.11.1 and 3.11.2</td>
      <td>WordPress Plugin for Auth0</td>
    </tr>

    <tr>
      <td>January 30, 2020</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/cve-2019-20174">CVE-2019-20174</a></td>
      <td>Auth0 Security Bulletin for Auth0 Lock \< 11.21.0</td>
      <td>Auth0 Lock</td>
    </tr>

    <tr>
      <td>October 04, 2019</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/cve-2019-16929">CVE-2019-16929</a></td>
      <td>Auth0 Security Bulletin for auth0.net between versions 5.8.0 and 6.5.3 inclusive</td>
      <td>auth0.net</td>
    </tr>

    <tr>
      <td>September 05, 2019</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/2019-09-05-scopes">Auth0 bulletin</a></td>
      <td>Auth0 Security Bulletin for assigning scopes based on email address</td>
      <td>Custom code within Auth0 rules</td>
    </tr>

    <tr>
      <td>July 23, 2019</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/cve-2019-13483">CVE-2019-13483</a></td>
      <td>Security Bulletin for Passport-SharePoint \< 0.4.0</td>
      <td>Passport-SharePoint</td>
    </tr>

    <tr>
      <td>February 15, 2019</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/cve-2019-7644">CVE-2019-7644</a></td>
      <td>Security Bulletin for Auth0-WCF-Service-JWT \< 1.0.4</td>
      <td>Auth0-WCF-Service-JWT</td>
    </tr>

    <tr>
      <td>January 10, 2019</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/2019-01-10-rules">Auth0 bulletin</a></td>
      <td>Auth0 Security Bulletin for Vulnerable Patterns in Custom Rule Code</td>
      <td>Custom code within Auth0 Rules</td>
    </tr>

    <tr>
      <td>August 6, 2018</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/cve-2018-15121">CVE-2018-15121</a></td>
      <td>Security vulnerability in deprecated Auth0 middleware for ASP.NET</td>
      <td>auth0-aspnet, auth0-aspnet-owin</td>
    </tr>

    <tr>
      <td>June 5, 2018</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/cve-2018-11537">CVE-2018-11537</a></td>
      <td>Security update for angular-jwt allowlist bypass</td>
      <td>angular-jwt</td>
    </tr>

    <tr>
      <td>April 4, 2018</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/cve-2018-6874">CVE-2018-6874</a></td>
      <td>Security vulnerability for Auth0 authentication service</td>
      <td>Auth0 Authentication Service</td>
    </tr>

    <tr>
      <td>April 4, 2018</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/cve-2018-6873">CVE 2018-6873</a></td>
      <td>Security vulnerability for Auth0 authentication service</td>
      <td>Auth0 Authentication Service</td>
    </tr>

    <tr>
      <td>February 26, 2018</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/cve-2018-7307">CVE 2018-7307</a></td>
      <td>Security vulnerability for auth0.js \< 9.3</td>
      <td>Auth0.js</td>
    </tr>

    <tr>
      <td>December 22, 2017</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/cve-2017-16897">CVE 2017-16897</a></td>
      <td>Security update for passport-wsfed-saml2 Passport strategy library</td>
      <td>passport-wsfed-saml2 Passport strategy library</td>
    </tr>

    <tr>
      <td>December 4, 2017</td>
      <td><a href="/docs/secure/security-guidance/security-bulletins/cve-2017-17068">CVE 2017-17068</a></td>
      <td>Security update for auth0.js popup callback vulnerability</td>
      <td>Auth0.js</td>
    </tr>
  </tbody>
</table>


# Auth0 Security Bulletin for Rules
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/2019-01-10-rules

Cases where improper custom rule code may create vulnerabilities in the authentication flow.

**Published**: January 10, 2019

## Overview

This security bulletin covers several scenarios that customers should avoid in custom rule code, as they may create vulnerabilities in the authentication flow. A description of each issue and, where possible, an alternative way to write the same rule, is provided below.

* Custom rule code containing conditional logic to enforce <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA) may introduce the ability to bypass MFA altogether, especially when using silent authentication.
* Custom rule code implementing authorization controls based on a specific substring without appropriate logic may result in elevated privileges.
* Custom rule code sending diagnostic information to third-party services, rather than using Auth0's built-in debugging features, may result in sensitive information disclosure.
* Custom rule code triggering paid services may introduce the ability for an adversary to incur unwanted billing charges.
* Custom rule code granting authorization based on unverified email addresses may allow adversaries to acquire those privileges through a secondary connection type.
* Custom rule code containing hardcoded secrets, such as API keys, rather than using the global configuration object, increases the risk of exposing such secrets.

## Improper MFA rules

### Silent authentication

Within a single-page application (SPA), silent authentication enables new <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> to be issued without user interaction as long as the current session is valid against the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip>.

Auth0 offers silent authentication through a special parameter which is added to the authorization endpoint as follows:
`/authorize?prompt=none`

If MFA is added to the silent authentication process, however, then user interaction becomes necessary.

Conditional logic based on silent authentication to bypass MFA should not be used as a workaround. Rules such as this allow complete MFA bypass and should not be utilized:

```javascript lines theme={null}
function (user, context, callback) {
  if (context.request.query && context.request.query.prompt === 'none') {
  // skip MFA for silent token requests
  return callback(null, user, context);
  }
...
}
```

### Silent authentication with redirection to custom MFA provider

Rules that determine whether to redirect to custom multi-factor authentication based on silent authentication may allow MFA bypass in some unusual circumstances. For example, avoid the following:

```javascript lines theme={null}
function (user, context, callback) {
  if (context.request.query && context.request.query.prompt === 'none') {
  //redirect to custom MFA
  context.redirect = {
    url: "https://example.com/"
  };
...
}
```

### Improper verification

Utilizing rules to bypass multi-factor authentication given specific conditions may bypass MFA when the checks in place are inadequate for determining the veracity of a desired state.

In these cases, the root of the issue is that rules can never determine whether MFA was successfully executed, as MFA happens after rule execution. Rules configured in this manner (see examples below) prematurely update the user record under the incorrect assumption that MFA will be successfully executed while relying on the same user record to skip MFA under given conditions.

The examples below illustrate improper verification checks which can result in full multi-factor authentication bypass.

#### Device fingerprint

```javascript lines theme={null}
function (user, context, callback) {

  var crypto = require('crypto');

  var deviceFingerPrint = getDeviceFingerPrint();
  user.app_metadata = user.app_metadata || {};

  // Inadequate verification check
  if (user.app_metadata.lastLoginDeviceFingerPrint !== deviceFingerPrint) {
    user.app_metadata.lastLoginDeviceFingerPrint = deviceFingerPrint;
    context.multi-factor = {
      ...
    };
    ...
  }
  function getDeviceFingerPrint() {
    var shasum = crypto.createHash('sha1');
    shasum.update(context.request.userAgent);
    shasum.update(context.request.ip);
    return shasum.digest('hex');
  }
}
```

#### Country code

```javascript lines theme={null}
function (user, context, callback) {
  user.app_metadata = user.app_metadata || {};

  // Inadequate verification check
  if (user.app_metadata.last_location !== context.request.geoip.country_code) {
    user.app_metadata.last_location = context.request.geoip.country_code;
    context.multi-factor = {
    ...
    };
  }
```

### Am I affected?

If you use any of the previously illustrated rule logic, an adversary who has successfully logged in with the first authentication factor may be able to bypass MFA on your application.

### Mitigation steps

**If you are affected by the silent authentication scenario**, remove the conditional logic based on `prompt === 'none'`. This will trigger multi-factor authentication on each silent authentication call to check session status.

**If you are affected by the silent authentication with redirection scenario**, remove the conditional logic based on `prompt === 'none'` and switch to an Auth0-supported multi-factor authentication provider.

To avoid prompting the user for MFA too often, you can set the parameter `allowRememberBrowser` to true, which will enable end-users to check a box so they will only be prompted for multi-factor authentication every 30 days. For example:

```js lines theme={null}
context.multi-factor = {
    provider: 'guardian',
    allowRememberBrowser: true
  };
```

You may want to notify your end users about checking the box to avoid being prompted too frequently.

**If you are affected by rules utilizing improper verification for skipping MFA**, ensure to use sound verification checks, discontinue MFA exceptions entirely, or use the `allowRememberBrowser` configuration option described above.

### Will this update impact my users?

Depending on how you adjust your rules or configuration, this update may impact your users by prompting them for MFA more than usual.

## Improper substring verification

If you have rule logic that requires access control based on an exact match of a particular string, such as an email domain, but you are only checking for a substring instead of an exact string match, your logic may not function as you intend. For example:

`if( _.findIndex(connection.options.domain_aliases,function(d){ return user.email.indexOf(d) >= 0;`

The above logic would return true given emails such as these:

* `user.domain.com@not-domain.com`
* `"user@domain.com"@not-domain.com` (quotes included)

### Am I affected?

Only customers using conditional logic in rules as described above, are affected.

### Mitigation steps

Utilize logic such as:

`const emailSplit = user.email.split('@'); const userEmailDomain = emailSplit[emailSplit.length - 1].toLowerCase();`

Please refer to the [Check Domains Against Connection Aliases rule template](https://github.com/auth0/rules/blob/master/src/rules/check-domains-against-connection-aliases.js) for more information. Alternatively, in the **Rules** section of the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, view the rule template named **Check if user email domain matches configured domain**.

### Will this update impact my users?

Possibly. The recommended change to rules with logic based on substring checks may impact end users, though you will be the best judge of the intent of your rules and whether any recommended changes are likely to impact your end users.

## Debugging using external services

If you have rule logic that sends the Auth0 context object to an external service, you are exposing items such as `id_token` or `access_token` associated with the request. For example:

```js lines theme={null}
request.post({
    url: 'http://requestbin.fullcontact.com/YourBinUrl',
    json: {
      user: user,
      context: context,
    },
    timeout: 15000
  }, function(err, response, body){
    if (err) return callback(err);
    return callback(null, user, context);
  });
```

### Am I affected?

Only customers with rule logic as described above are affected.

### Mitigation steps

You should modify your rule so it no longer sends the entire context object to requestbin, as this may expose any `id_token` or `access_token` associated with each request. Instead, you should send a subset of attributes from the context object that are less sensitive.

Please refer to the [Requestbin rule template](https://github.com/auth0/rules/blob/master/src/rules/requestbin.js) for more information. Alternatively, in the **Rules** section of the Auth0 Dashboard, view the rule template named **Dump rule variables to RequestBin**.

Auth0 also offers built-in methods for debugging rules without sending information to external services.

### Will this update impact my users?

No. The impacted rule was typically used for debugging purposes. Modification should not impact end users.

## Rules using a paid service

If you have rule logic that involves a paid service, such as sending SMS messages via Twillio, as part of the authentication process, you may be vulnerable to increased costs because an adversary with a valid username and password may be able to trigger a call to the service and incur costs without having to complete the entire authentication process specified by rules. For example:

```javascript lines theme={null}
//Sends user SMS via Twilio
  function notifyUser(done) {
    const request = require('request');
    const twilioAccount = '{yourTwilioAccount}';
    const twilioAuthToken = '{yourTwilioAuthToken}';

    request.post({
      url: 'https://api.twilio.com/2010-04-01/Accounts/' + twilioAccount + '/Messages.json',
      auth: {
        'user': twilioAccount,
        'pass': twilioAuthToken,
      },
      form: {
        body: 'You\'ve logged in from a different device or location.',
        to: user.phone,
        from: '+18668888888'
      }
    }, function (error, response, body) {
      if (error) return done(error);
      if (response.statusCode !== 201) return done(new Error(response.statusCode));
      return done(null);
    });
  }
```

### Am I affected?

Only customers with rule logic as described above, and whose rule logic can be triggered by any untrusted user, are affected.

### Mitigation steps

To mitigate this risk, consider one or more of the following actions:

* Disallow public sign-ups, if not needed, to reduce the numbers of users who can sign up and trigger calls to paid services.
* Mitigate the risk of credential theft to avoid account takeover by hackers who might use hijacked accounts to trigger calls to paid services.
* Ensure your users have strong passwords when using Database connections.
* Ensure your users utilize multi-factor authentication.
* Ensure that the rule only gets triggered for an authorized subset of users, or under other appropriate conditions. For example, you may wish to add logic that checks if a user has a particular email domain, role/group, or subscription level before triggering the call to the paid service.

### Will this update impact my users?

The impact to end users depends on which of the options described above you choose to mitigate the issue.

## Authorization based on unverified email address

If you have rule logic that requires access control based on a particular email or email domain, but you are failing to check whether that user has verified their email, an adversary could potentially gain additional privileges by using a second connection type. For example:

```javascript lines theme={null}
var userHasAccess = allowList.some(function (email) {
    return email === user.email;
  });
```

The above logic would return `true` if an adversary could create an account using a different connection type (such as social) with an email address present in the allow-list. This happens because the same email can exist in different connection types.

### Am I affected?

Only customers using conditional logic in rules as described above, and allowing for multiple connection types, are affected.

### Mitigation steps

Whenever granting authorization based on email addresses, always start the rule with the following logic:

```javascript lines theme={null}
function (user, context, callback) {
  // Access should only be granted to verified users.
  if (!user.email || !user.email_verified) {
    return callback(new UnauthorizedError('Access denied.'));
  }
```

Sometimes even a verified email may not be an adequate check for the authorization you want to perform. To find out more about such cases, please read about the Email Verified Usage.

### Will this update impact my users?

This will only affect existing users if they have not verified their email addresses.

## Plaintext secrets within rule code

If you specify sensitive information, such as API keys, within rule code, you should configure those values in rule settings instead. For example:

`const myApiKey = 'abcdefghijklmnopqrstuvwxyz';`

Such sensitive values, being present in the rule code, will remain unencrypted in our systems and suffer the risk of being exposed.

### Am I affected?

If your rules contain sensitive values within the rule code itself, you are affected.

### Mitigation steps

Place the sensitive values in the **Settings** area of the main **Rules** section of the Auth0 Dashboard and then access them in your rule via the following:

`const myApiKey = configuration.myApiKey;`

This will ensure that all sensitive values are encrypted within Auth0's systems, reducing the risk of exposure.

### Will this update impact my users?

This will not impact your users.


# Auth0 Security Bulletin for Assigning Scopes Based on Email Address
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/2019-09-05-scopes

Cases where improper custom rule code may create vulnerabilities in the authentication flow.

## Overview

If you:

* Use rules to assign scopes to users based on their email addresses **and**
* Your application uses multiple connections

There is a possibility that your scopes could be compromised.

## How This Works

Auth0 requires that email addresses are unique on a per-connection basis. However, there are no limitations on a per-application basis.

Therefore, it is possible for user A to sign up for the application using one connection and user B to sign up for the application with the same email address using a different connection.

If your rules assign scopes to users based on email address, the second user has now been given the same scopes as the first user, despite being a different individual.

## How do I fix this?

The most straightforward mitigation is to require users to verify their email address after signing up and before being allowed to log in.


# CVE-2020-5391, CVE-2020-5392, CVE-2020-6753, CVE-2020-7948, CVE-2020-7947: Security Update for WordPress Plugin for Auth0
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/2020-03-31-wpauth0

CVE-2020-5391, CVE-2020-5392, CVE-2020-6753, CVE-2020-7948, CVE-2020-7947: Security Update for WordPress Plugin for Auth0

**Published**: March 31, 2020

**CVE numbers**: CVE-2020-5391, CVE-2020-5392, CVE-2020-6753, CVE-2020-7948, CVE-2020-7947

**Credit**: Muhamad Visat

## Overview

Auth0 has released a new major version of the [WordPress Plugin for Auth0](https://github.com/auth0/wp-auth0) to address several vulnerabilities.

We recommend you review the following security advisories and upgrade to the new major version:

* CSRF controls missing for domain field in Auth0 WP plugin: [CVE-2020-5391](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-5391)
* Stored XSS in Auth0 WP plugin (Settings page): [CVE-2020-5392](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-5392)
* Stored XSS in Auth0 WP plugin (multiple pages): [CVE-2020-6753](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-6753)
* CSV injection vulnerabilities in Auth0 WP plugin: [CVE-2020-7947](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-7947)
* Insecure direct object reference in Auth0 WP plugin: [CVE-2020-7948](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-7948)

## Am I affected?

Customers using any version of the WordPress Plugin for Auth0 3.11.3 or earlier can be affected.

## How to fix that?

Customers using [WordPress Plugin for Auth0](https://github.com/auth0/wp-auth0) need to upgrade to version 4.0.0 or higher.

## Will this update impact my users?

The [release notes](https://github.com/auth0/wp-auth0/blob/master/CHANGELOG.md) provide more in-depth information about the changes that were made, and the [migration instructions](https://github.com/auth0/wp-auth0/blob/master/MIGRATE-v3-TO-v4.md) provide more in-depth information about the upgrade path.


# CVE-2022-23539, CVE-2022-23541, CVE-2022-23540: Security Update for jsonwebtoken
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/2022-12-21-jsonwebtoken

Describes CVE-2022-23539, CVE-2022-23541, CVE-2022-23540 security update for JSON web token library.

**Published**: Dec 21, 2022

**CVE numbers**: CVE-2022-23539, CVE-2022-23541, CVE-2022-23540

### Overview

Auth0 has released a new major version of the `jsonwebtoken` library to address four vulnerabilities.

We recommend you review the following security advisories and upgrade to the new major version:

* Unrestricted key type could lead to legacy keys usage: [CVE-2022-23539](https://github.com/auth0/node-jsonwebtoken/security/advisories/GHSA-8cf7-32gw-wr33)
* Insecure implementation of key retrieval function could lead to Forgeable Public/Private Tokens from RSA to HMAC: [CVE-2022-23541](https://github.com/auth0/node-jsonwebtoken/security/advisories/GHSA-hjrf-2m68-5959)
* Insecure default algorithm in <Tooltip href="/docs/glossary?term=jwt">jwt</Tooltip>.verify() could lead to signature validation bypass: [CVE-2022-23540](https://github.com/auth0/node-jsonwebtoken/security/advisories/GHSA-qwph-4952-7xr6)

### Am I affected?

You could be affected if you are using `jsonwebtoken` in any version \<= 8.5.1 depending on the configuration. Please consult the individual security advisories for more details.

### How to fix that?

If you are using `jsonwebtoken`, upgrade to version 9.0.0 or higher. You may need some additional configuration. Please consult the individual security advisories for more details.

### Will this update impact my users?

Updating to version 9.0.0 may impact your users depending on your configuration and application needs. Please consult the individual security advisories for more details.


# CVE-2017-16897: Security Update for passport-wsfed-saml2 Passport Strategy Library
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/cve-2017-16897

CVE-2017-16897: Security Update for passport-wsfed-saml2 Passport strategy library

**Published**: December 22, 2017

**CVE number**: CVE-2017-16897

**Credit**: Alan Bishop

## Overview

A vulnerability has been discovered in the [passport-wsfed-saml2 library](https://github.com/auth0/passport-wsfed-saml2) affecting versions \< `3.0.5`. **passport-wsfed-saml2** is a WS-Federation protocol and SAML2 tokens authentication provider for [Passport.js](http://passportjs.org/).

This vulnerability allows an attacker to impersonate another user and potentially elevate their privileges if the <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> does not sign the full SAML response, but instead only signs the assertion within the response.

An attacker who successfully exploits this vulnerability could use that response to craft a request with a different **NameIdentifier** in order to log in as a different user. A malicious actor could also perform a privilege escalation attack if authenticating as a specific user with administrative privileges. The attacker must have an existing account, or be able to intercept the encrypted traffic and modify the SAML response on the fly.

This update addresses the vulnerability by avoiding wrapping attacks for **Assertion** and **Response** elements, as well as providing some defensive changes in XPath expressions. An update has also been implemented to improve the method of logging information about the signing of the SAML response.

Patching this vulnerability requires a library upgrade.

## Am I affected?

This vulnerability affected cloud tenants utilizing the **SAMLP Identity Provider Connection** wherein the identity provider either:

* signed SAML response and signed assertion
* did not sign SAML response and signed assertion

No action is required for Auth0 cloud tenants.

The vulnerability scope also extended to those using the [passport-wsfed-saml2 strategy with passport.js](https://github.com/auth0/passport-wsfed-saml2), which requires a library upgrade (see the next section).

## How to fix that?

Developers using the **passport-wsfed-saml2** library need to upgrade to the latest version: `3.0.5`.

Updated packages are available on npm. To ensure delivery of additional bug fixes moving forward, please make sure your `package.json` file is updated to take patch and minor level updates of our libraries.

```json lines theme={null}
{
  "dependencies": {
    "passport-wsfed-saml2": "^3.0.5"
  }
}
```

### Will this update impact my users?

No. This fix patches the library that your application runs, but will not impact your users, their current state, or any existing sessions.


# CVE-2017-17068: Security Update for auth0.js Popup Callback Vulnerability
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/cve-2017-17068

CVE-2017-17068: Security Update for auth0.js Popup Callback Vulnerability

**Published**: December 4, 2017

**CVE number**: CVE-2017-17068

**Credit**: [@AppCheckNG](https://x.com/AppCheckNG)

## Overview

A vulnerability has been identified in the [auth0.js JavaScript library](/docs/libraries/auth0js), affecting versions \< `8.12`.

If your site or application uses a popup callback page with `auth0.popup.callback()` then an attacker can take advantage of unrestricted cross-origin post message requests and gain access to the tokens of logged-in users. A malicious website could then use any acquired <Tooltip href="/docs/glossary?term=Access+Tokens">Access Tokens</Tooltip> to invoke services on behalf of the user.

This update addresses the vulnerability by implementing origin verification so the message cannot be posted to a page that is not in a specified domain. If no domain is specified, only the domain where the callback page is hosted is allowed. An attacker would receive a cross-origin request error.

Patching this vulnerability requires a library upgrade.

## Am I affected?

If the following apply you are affected by this vulnerability:

* You use a version of auth0.js lower than `8.12`
* You use a popup callback page with `auth0.popup.callback()` in your code

## How to fix that?

Developers using the auth0.js library need to upgrade to the latest version: `8.12`.

Updated packages are available on npm. To ensure delivery of additional bug fixes moving forward, please make sure your `package.json` file is updated to take patch and minor level updates of our libraries.

```json lines theme={null}
{
  "dependencies": {
    "auth0-js": "^8.12.0"
  }
}
```

### Will this update impact my users?

No. This fix patches the library that your application runs, but will not impact your users, their current state, or any existing sessions.


# CVE-2018-11537: Security Update for angular-jwt Allow List Bypass
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/cve-2018-11537

CVE-2018-11537: Security Update for angular-jwt Allow List Bypass

**Published**: June 5, 2018

**CVE number**: CVE-2018-11537

**Credit**: Stephan Hauser

## Overview

The [domain allowlisting](https://github.com/auth0/angular-jwt#whitelisting-domains) feature can be bypassed. For example, if the setting is initialized with:

`jwtInterceptorProvider.whiteListedDomains = ['whitelisted.Example.com'];`

An attacker can set up a domain `whitelistedXexample.com` that will pass the allow list filter. The root cause for this is that `angular-jwt` always treats `whiteListedDomains` entries as regular expressions and causes `.` separator to match any character.

## Am I affected?

If the following apply you are affected by this vulnerability:

* You use a version of angular-<Tooltip href="/docs/glossary?term=jwt">jwt</Tooltip> lower than `0.1.10`
* You use domain allow listing in your code

## How to fix that?

Developers using the angular-jwt library need to upgrade to the latest version: `0.1.10`.

Updated package is available on [NPM](https://npmjs.com): `npm install angular-jwt@0.1.10`

To make it easier to keep up with security updates in the future, please make sure your `package.json` file is updated to take patch and minor level updates of our libraries:

```json lines theme={null}
{
  "dependencies": {
    "angular-jwt": "^0.1.10"
  }
}
```

### Will this update impact my users?

No. This fix patches the library that your application runs, but will not impact your users, their current state, or any existing sessions.


# CVE-2018-15121: Security Vulnerability in auth0-aspnet and auth0-aspnet-owin
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/cve-2018-15121

CVE-2018-15121: Security vulnerability in deprecated Auth0 middleware for ASP.NET

**Published**: August 6, 2018

**CVE number**: CVE-2018-15121

**Credit**: Kévin Chalet

## Overview

All versions of the [auth0-aspnet](https://github.com/auth0/auth0-aspnet) and [auth0-aspnet-owin](https://github.com/auth0/auth0-aspnet-owin) packages have a security vulnerability that leave client applications vulnerable to a Cross-Site Request Forgery (CSRF) attack during authorization and authentication operations.

The root cause of this vulnerability is lack of use and verification of the `state` parameter in <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> and <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) protocols that allows an attacker to inject their authorization code into victim's session.

## Am I affected?

If you use any version of `auth0-aspnet` or `auth0-aspnet-owin`, you are affected by this vulnerability.

## How to fix that?

Further development of the [auth0-aspnet](https://github.com/auth0/auth0-aspnet) and [auth0-aspnet-owin](https://github.com/auth0/auth0-aspnet-owin) packages has been discontinued. We strongly recommend moving to OWIN 4 and the official `Microsoft.Owin.Security.OpenIdConnect` package, which is not vulnerable.

If your application is not currently making use of OWIN, please refer to Microsoft's [OWIN documentation](https://docs.microsoft.com/en-us/aspnet/aspnet/overview/owin-and-katana/) to enable it in your application.

### Will this update impact my users?

Current user states and sessions will be invalidated, as different libraries will handle authentication.


# CVE-2018-6873: Security Vulnerability in the Auth0 Authentication Service
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/cve-2018-6873

CVE-2018-6873: Details about a security vulnerability identified in the Auth0 authentication service

**Published**: April 4, 2018

**CVE number**: CVE-2018-6873

**Credit**: [Cinta Infinita](http://www.cintainfinita.com/)

## Overview

A vulnerability was identified in the Auth0 authentication service. It affected all Auth0 tenants, and was patched on October 15th, 2017 within four hours of report for all public cloud customers. This notice is informational and is intended to explain the vulnerability and the mitigation taken.

As part of an user authentication flow employed by the Auth0 service, a <Tooltip href="/docs/glossary?term=JSON+Web+Token">JSON Web Token</Tooltip> (JWT) is passed to the `/login/callback` endpoint identifying the user. This token contains a reference to which <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> - an Auth0 tenant - it is intended for. A flaw in the Auth0 service did not properly validate this audience, and therefore allowed tokens intended for one tenant to be used at another. Further, the custom database functionality available to all Auth0 tenants allows for authenticated tokens to be generated with any desired identifier. Therefore, could an attacker learn the user identifier of an intended victim at a target tenant - which is generally considered public information - they could construct a token with that identifier. Due to the improper audience checking the target tenant would accept it, and establish a login session recognizing the attacker as the victim. This allowed for privilege escalation, among other possible attack vectors.

A specific concern was the potential use of this attack on the Auth0 management service. Auth0 tenants are managed by tenant administrators, who have accounts on an "authority tenant" with relevant permissions. If an attacker could learn the user identifier of a tenant administrator on the tenant authority (such as by social engineering), this allowed the attacker to login as the administrator by the described attack method. The attacker could then undertake administration actions and view all information at the tenant.

The attack was never effective if the user had <Tooltip href="/docs/glossary?term=multifactor+authentication">multifactor authentication</Tooltip> enabled, which is recommended.

## Am I affected?

All Auth0 tenants were affected, but have been patched. Public cloud tenants were patched within four hours of the vulnerability report.

The attack was never effective if the user had multifactor authentication enabled.

## How to fix that?

The vulnerability was fixed by Auth0, accomplished by adding proper validation of the audience parameter. No additional actions are required of our customers.

### Will this update impact my users?

The fix was invisible to all users.


# CVE-2018-6874: Security Vulnerability in the Auth0 Authentication Service
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/cve-2018-6874

CVE-2018-6874: Details about a security vulnerability identified in the Auth0 authentication service

**Published**: April 4, 2018

**CVE number**: CVE-2018-6874

**Credit**: Internal

## Overview

A vulnerability has been identified in the Auth0 authentication service. Tenants of the service with the Legacy Lock API flag enabled in the service’s management dashboard are affected. If the flag is not visible, it is disabled. Disabling the flag may break applications employing the auth0.js library with version `< 9.0.0` or the Lock library with version `< 11.0.0` for crossdomain username/password based authentication - also known as [embedded login](/docs/authenticate/login/universal-vs-embedded-login). Further, any cross-domain use of the `/usernamepassword/login` authentication api endpoint outside of those libraries may also be affected.

After the verification of user credentials on `/usernamepassword/login`, an HTML form is rendered into the user’s browser and automatically executed. It POSTs a <Tooltip href="/docs/glossary?term=JSON+Web+Token">JSON Web Token</Tooltip> (JWT) to the `/login/callback` endpoint. This authenticated token maintains state regarding the identity of the user; this cannot be done directly due to crossdomain session management restrictions maintained by most modern browsers. Due to the lack of session binding, this form post is susceptible to [CSRF](https://www.owasp.org/index.php/Cross-Site_Request_Forgery_\(CSRF\)). An attacker with valid user credentials at an Auth0 tenant can use them to gain such a form, and then employ techniques such as social engineering or clickjacking to have a victim’s browser execute it. The victim will then have a login session at the Auth0 tenant under the attacker’s account - and therefore be recognized as the attacker by any downstream application in its federation. Should the user undertake any actions while maliciously logged in as such, those actions and any related information will be visible to the attacker.

The attack does not allow any escalation of privileges on behalf of the attacker, and the victim’s actions visible to the attacker are restricted to whatever permissions have been granted to that attacker within the system. The victim will also be fully recognized as the attacker within the federation, and so may be shown account information or other context clues that reveal they are not operating within the auspices of their own account.

## Am I affected?

You are affected if you employ username/password authentication (with any database and/or connection) for your Auth0 tenant, and the Legacy Lock API flag in the Auth0 management dashboard is visible and flagged on.

## How to fix that?

To mitigate the vulnerability, toggle the flag to off. The `/usernamepassword/login` endpoint will still work for logins from the <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> page hosted on `/login`, however these - as same-domain logins - will be protected from CSRF. Otherwise, toggling the flag will disable cross-domain authentication on that endpoint.

For applications employing auth0.js version `< 9.0.0` or Lock version `< 11.0.0`, this may break user logins. Upgrading to auth0.js version `> 9.0.0` or Lock version `> 11.0.0` will restore embedded username/password authentication using cross-origin authentication (note the limitations). Applications are also encouraged to migrate to Universal Login.

Private SaaS Appliances running versions `> 14591` with the Legacy Lock API flag set to off are not affected by this vulnerability.

### Will this update impact my users?

If the Legacy Lock API is disabled without applications having migrated, then all user logins employing the affected functionality will break. Auth0 intends to enforce disablement of the Legacy Lock API for all tenants on July 16th, 2018. The choice of migration may affect the specific user experience of logging into your service, however users, their information, and their sessions will not be otherwise impacted.


# CVE-2018-7307: Security Vulnerability for auth0.js < 9.3
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/cve-2018-7307

CVE-2018-7307: Details about a security vulnerability identified for auth0.js < 9.3

**Published**: February 26, 2018

**CVE number**: CVE-2018-7307

**Credit**: Internal

## Overview

A vulnerability has been identified in the [auth0.js JavaScript library](/docs/libraries/auth0js), affecting versions \< `9.3`.

This vulnerability allows an attacker to bypass the CSRF check from the [state parameter](/docs/secure/attack-protection/state-parameters) if it's missing from the authorization response, leaving the client vulnerable to CSRF attacks.

Patching this vulnerability requires a library upgrade.

## Am I affected?

If you use a version of auth0.js lower than `9.3` then you are affected by this vulnerability.

## How to fix that?

Developers using the auth0.js library need to upgrade to the version `9.3` or higher.

Updated packages are available on npm. To ensure delivery of additional bug fixes moving forward, please make sure your `package.json` file is updated to take patch and minor level updates of our libraries.

```json lines theme={null}
{
  "dependencies": {
    "auth0-js": "^9.3.0"
  }
}
```

### Will this update impact my users?

No. This fix patches the library that your application runs, but will not impact your users, their current state, or any existing sessions.


# CVE-2019-13483: Security Vulnerability in Passport-SharePoint
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/cve-2019-13483

CVE-2019-13483: Details about a security vulnerability in Passport-SharePoint

**Published**: 7/23/2019

**CVE number**: CVE-2019-13483

## Overview

Versions of [Passport-SharePoint](https://github.com/auth0/passport-sharepoint) prior to **0.4.0** do not validate the <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> signature of an <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> before processing.

This vulnerability allows attackers to forge tokens and bypass authentication and authorization mechanisms.

## Am I affected?

You are affected by this vulnerability if you use a [Passport-SharePoint](https://github.com/auth0/passport-sharepoint) version earlier than 0.4.0.

## How do I fix this?

Developers using the [Passport-SharePoint](https://github.com/auth0/passport-sharepoint) library must upgrade to version `0.4.0`.

Please note that Auth0 has deprecated and will no longer maintain this library. Developers should plan to discontinue its use.

### Will this update impact my users?

No. This fix patches the library that your application runs, but it will not impact your users, their current state, or any existing sessions.


# CVE-2019-16929: Security Vulnerability in auth0.net
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/cve-2019-16929

CVE-2019-16929: Security vulnerability in auth0.net

**Published**: 10/03/2019

**CVE number**: CVE-2019-16929

**Credit**: Dennis Detering (Spike Reply GmbH)

## Overview

Versions of [auth0.net](https://github.com/auth0/auth0.net) and associated NuGet Package [Auth0.AuthenticationAPI](https://www.nuget.org/packages/Auth0.AuthenticationApi/) from `5.8.0` to `6.5.3` inclusive include a class named `IdentityTokenValidator` with a public `ValidateAsync` method, that performs limited validation suitable only for auth0 issued tokens.

## Am I affected?

You are affected by this vulnerability if all of the following conditions apply:

* You are using the `IdentityTokenValidator` to validate untrusted <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip>
* You are using a version of Auth0.AuthenticationAPI between `5.8.0` and `6.5.3` inclusive

## How to fix that?

Developers should not use the `IdentityTokenValidator` class to validate untrusted ID tokens. See [Validate ID Tokens](/docs/secure/tokens/id-tokens/validate-id-tokens) for our recommendations for validating ID tokens. [https://jwt.io/](https://jwt.io/) is a good resource on open source <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> validation libraries and their capabilities. Note that additional logic may be required based upon your use case.

Developers using the [auth0.net](https://github.com/auth0/auth0.net) and associated NuGet Package [Auth0.AuthenticationAPI](https://www.nuget.org/packages/Auth0.AuthenticationApi/) between `5.8.0` and `6.5.3` inclusive should upgrade to the latest version `6.5.4` to prevent accidental usage of the `IdentityTokenValidator` class.

### Will this update impact my users?

No. This fix patches the client library that your application runs, but will not impact your users, their current state, or any existing sessions.


# CVE-2019-20173: Security Update for WordPress Plugin for Auth0 wp-auth0
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/cve-2019-20173

CVE-2019-20173: Security Update for WordPress Plugin for Auth0

**Published**: January 31, 2020

**CVE number**: CVE-2019-20173

**Credit**: Muhamad Visat

## Overview

The WordPress Plugin for Auth0 versions 3.11.0, 3.11.1, and 3.11.2 do not properly sanitize the `wle` query parameter. This could allow an attacker to run a cross-site scripting (XSS) attack on the login page.

## Am I affected?

You are affected by this vulnerability if all of the following apply:

* You are using the WordPress Plugin for Auth0 versions 3.11.0, 3.11.1, or 3.11.2
* The “Original Login Form on wp-login.php” setting under Basic settings is set to either of the two options:

  * “Via a link under the Auth0 form” (default option)
  * “When "wle" query parameter is present”

## How to fix that?

Developers using WordPress Plugin for Auth0 need to upgrade to version 3.11.3 or later.

## Will this update impact my users?

No. This fix patches the library that your application runs, but will not impact your users, their current state, or any existing sessions.


# CVE-2019-20174: Security Update for Auth0 Lock Library
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/cve-2019-20174

CVE-2019-20174: Security Update for Auth0 Lock library

**Published**: January 30, 2020

**CVE number**: CVE-2019-20174

**Credit**: Muhamad Visat

## Overview

Auth0 Lock version 11.20.4 and earlier did not properly sanitize the generated HTML code. Customers using the `additionalSignUpFields` customization option to add a checkbox to the sign-up dialog who are passing a `placeholder` property obtained from an untrusted source (e.g., a query parameter) could allow cross-site scripting (XSS) on their sign-up pages.

## Am I affected?

You are affected by this vulnerability if all of the following conditions apply:

* You are using Auth0 Lock version 11.20.4 or earlier.
* You pass `additionalSignUpFields` as an option when initializing Lock, and it includes a field of type `checkbox` with a `placeholder` value obtained from an untrusted source.

An example of a vulnerable snippet is the following where the `placeholder` value is partially user-controlled by the `name` query parameter:

```html lines theme={null}
<script>
    var params = new URLSearchParams(window.location.search);
    var options = {
        auth: {
            redirectUrl: 'http://localhost:12345/callback',
            responseType: 'code',
            params: {
                scope: 'openid email',
            },
        },
        additionalSignUpFields: [{
            name: 'agree',
            type: 'checkbox',
            placeholder: "I agree to Terms & Conditions for " + params.get('name'),
        }],
    };
    var lock = new Auth0Lock('<CLIENT_ID>', '<TENANT_NAME>.auth0.com', options);
    lock.show({
        allowShowPassword: true,
        initialScreen: 'signUp',
    });
</script>
```

## How to fix that?

Developers using Auth0’s Lock sign-in solution need to upgrade to version 11.21.0 or later. Version 11.21.0 introduces two changes:

1. The existing `placeholder` property is now treated as plain text to mitigate the problem.
2. A new `placeholderHTML` property is introduced that indicates the level of control it provides and that its value should be supplied only from trusted sources.

## Will this update impact my users?

This fix patches the Auth0 Lock widget and may require changes in application code, but it will not impact your users, their current state, or any existing sessions.

Developers using the `placeholder` property with HTML content from a trusted source should start using the `placeholderHTML` property to continue providing the same user experience.


# CVE-2019-7644: Security Vulnerability in Auth0-WCF-Service-JWT
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/cve-2019-7644

CVE-2019-7644: Security vulnerability in Auth0-WCF-Service-JWT for ASP.NET

**Published**: February 15, 2019

**CVE number**: CVE-2019-7644

**Credit**: Conny Dahlgren, Security Researcher at DevilSec AB

## Overview

All versions of [Auth0-WCF-Service-JWT](https://www.nuget.org/packages/Auth0-WCF-Service-JWT/) NuGet package lower than 1.0.4 include sensitive information about the expected <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> signature in an error message emitted when JWT signature validation fails:

`Invalid signature. Expected 8Qh5lJ5gSaQylkSdaCIDBoOqKzhoJ0Nutkkap8RgB1Y= got 8Qh5lJ5gSaQylkSdaCIDBoOqKzhoJ0Nutkkap8RgBOo=`

This vulnerability allows attackers to use this error message to obtain a valid signature for arbitrary JWT tokens. This way attackers can forge tokens to bypass authentication and authorization mechanisms.

## Am I affected?

You are affected by this vulnerability if the following conditions apply:

* You use a version of [Auth0-WCF-Service-JWT](https://www.nuget.org/packages/Auth0-WCF-Service-JWT/) NuGet package lower than 1.0.4
* You show signature verification exception message in the user interface or make it otherwise available to the attacker (for example through logs or diagnostic messages)

## How to fix that?

Developers using the [Auth0-WCF-Service-JWT](https://www.nuget.org/packages/Auth0-WCF-Service-JWT/) library need to upgrade to the latest version 1.0.4.

The updated package is available on [NuGet](https://www.nuget.org): `Install-Package Auth0-WCF-Service-JWT -Version 1.0.4`

### Will this update impact my users?

No. This fix patches the library that your application runs, but will not impact your users, their current state, or any existing sessions.


# CVE-2020-15084: Security Update for express-jwt Library
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/cve-2020-15084

CVE-2020-15084: Security update for Express-jwt Library

**Published**: June 30, 2020

**CVE number**: CVE-2020-15084

**Credit**: IST Group

## Overview

Versions before and including 5.3.3, we are not enforcing the **algorithms** entry to be specified in the configuration.

When **algorithms** is not specified in the configuration, with the combination of jwks-rsa or potentially other asymmetric crypto libraries, it may lead to authorization bypass.

## Am I affected?

You are affected by this vulnerability if all of the following conditions apply:

* You are using express-<Tooltip href="/docs/glossary?term=jwt">jwt</Tooltip>, AND
* You do not have **algorithms** configured in your express-jwt configuration, AND
* You are using libraries such as jwks-rsa as the **secret**.

## How to fix that?

Specify **algorithms** in the express-jwt configuration. The following is an example of a proper configuration:

```javascript lines theme={null}
const checkJwt = jwt({
  secret: jwksRsa.expressJwtSecret({
    rateLimit: true,
    jwksRequestsPerMinute: 5,
    jwksUri: `https://{DOMAIN}/.well-known/jwks.json`
  }),
  // Validate the audience and the issuer.
  audience: process.env.AUDIENCE,
  issuer: `https://{DOMAIN}/`,
  // restrict allowed algorithms
  algorithms: ['RS256']
});
```

## Will this update impact my users?

The fix provided in the patch will not affect your users if you specified the algorithms allowed. The patch now makes algorithms a required configuration.


# CVE-2020-15119: Security Update for Auth0 Lock Library
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/cve-2020-15119

CVE-2020-15119: Security Update for Auth0 Lock Library

**Published**: August 16, 2020

**CVE number**: CVE-2020-15119

**Credit**: [Muhamad Visat](https://github.com/mvisat)

## Overview

Versions before and including `11.25.1` are using `dangerouslySetInnerHTML` to display an informational message when used with a <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> or Enterprise connection.

* For a Passwordless connection, the value of the input (email or phone number) is displayed back to the user while waiting for verification code input.
* For an Enterprise connection, the value of the input (<Tooltip href="/docs/glossary?term=IdP">IdP</Tooltip> Domain) from the Enterprise connection setup screen (<Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>) is displayed back to the user when the Lock widget opens.

When a Passwordless or Enterprise connection is used, the application and its users might be exposed to cross-site scripting (XSS) attacks.

## Am I affected?

You are affected by this vulnerability if all of the following conditions apply:

* You are using `auth0-lock`
* You are using Passwordless or Enterprise connection mode

## How to fix that?

Upgrade to version `11.26.3`.

### Will this update impact my users?

The fix provided in the patch will not affect your users.


# CVE-2020-15125: Security Update for node-auth0 Library
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/cve-2020-15125

CVE-2020-15125: Security update for node-auth0 library

**Published**: July 28, 2020

**CVE number**: CVE-2020-15125

**Credit**: Omar Diab ([http://github.com/osdiab](http://github.com/osdiab))

## Overview

Versions before and including 2.27.0 use a block list of specific keys that should be sanitized from the request object contained in the error object. When a request to Auth0 <Tooltip href="/docs/glossary?term=management+API">management API</Tooltip> fails, the key for `Authorization` header is not sanitized and the `Authorization` header value can be logged exposing a bearer token.

## Am I affected?

You are affected by this vulnerability if all of the following conditions apply:

* You are using auth0 npm package.
* You are using a Machine to Machine application authorized to use Auth0's management API Client Credentials Flow.

## How to fix that?

Upgrade to version 2.27.1.

## Will this update impact my users?

The fix provided in patch will not affect your users.


# CVE-2020-15240: Security Update for omniauth-auth0 JWT Validation
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/cve-2020-15240

CVE-2020-15240: Security update for omniauth-auth0 JWT validation

**Published**: October 21st, 2020

**CVE number**: CVE-2020-15240

## Overview

Versions after and including `2.3.0` are improperly validating the <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> token signature when using the `JWTValidator.verify` method. Improper validation of the JWT token signature when not using the default Authorization Code Flow can allow an attacker to bypass authentication and authorization.

## Am I affected?

You are affected by this vulnerability if all of the following conditions apply:

* You are using `omniauth-auth0`
* You are using `JWTValidator.verify` method directly OR you are not authenticating using the SDK’s default Authorization Code Flow.

## How to fix that?

Upgrade to version `2.4.1`.

## Will this update impact my users?

The fix provided in this version will not affect your users.


# CVE 2020-15259: Security Update for ad-ldap-connector
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/cve-2020-15259

CVE 2020-15259: Security Update for ad-ldap-connector

**Published**: 05 November 2020

**CVE number**: CVE-2020-15259

## Overview

The ad-ldap-connector admin console does not provide CSRF protection, which when exploited may result in remote code execution or confidential data loss. CSRF exploits may occur if the user visits a malicious page containing CSRF payload on the same machine that has access to the ad-ldap-connector admin console via a browser.

## Am I affected?

You may be affected if you use the admin console included with ad-ldap-connector versions \<=5.0.12.

If you do not have ad-ldap-connector admin console enabled or do not visit any other public URL while on the machine it is installed on, you are **not** affected.

## How to fix that?

Upgrade to the latest version of [ad-ldap-connector](https://github.com/auth0/ad-ldap-connector) and restart your admin console.

## Will this update impact my users?

The fix provided in this version will not affect your users.


# CVE-2020-5263: Security Update for auth0.js Library
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/cve-2020-5263

CVE-2020-5263: Security Update for auth0.js library

**Published**: April 09, 2020

**CVE number**: CVE-2020-5263

**Credit**: Bogdan Vitoc (Spatial Systems Inc)

## Overview

Between versions 8.0.0 and 9.13.1 (inclusive), in the case of an (authentication) error, the error object returned by the library contains the original request of the user, which may include the plaintext password the user entered.

If the error object is exposed or logged without modification, the application risks password exposure.

## Am I affected?

You are affected by this vulnerability if all of the following conditions apply:

* You are using Auth0.js version between 8.0.0 and 9.13.1 (inclusive).
* You store or display error objects without filtering.

## How to fix that?

Developers should upgrade auth0.js to version 9.13.2 or later where user inputted passwords are masked in errors. If upgrading is not possible, a temporary fix may include not storing the error object or displaying it publicly without modification.

## Will this update impact my users?

This fix patches the Auth0.js and may require changes in application code due to password no longer available in error object, but it will not impact your users, their current state, or any existing sessions.


# CVE-2021-32641: Security Update for Auth0 Lock Library
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/cve-2021-32641

CVE-2021-32641: Security Update for Auth0 Lock Library

**Published**: June 4, 2021

**CVE number**: CVE-2021-32641

## Overview

Versions before and including `11.30.0` are vulnerable to a reflected XSS. An attacker can execute arbitrary code when either:

* The library's `flashMessage` feature is used and user input or data from URL parameters is incorporated into the `flashMessage`.

Or

* The library's `languageDictionary` feature is used and user input or data from URL parameters is incorporated into the `languageDictionary`.

## Am I affected?

This vulnerability affects you if your implementation fits either of these descriptions:

### flashMessage vulnerability

If all of these conditions are true, you're vulnerable:

* You use `auth0-lock` version `11.30.0` or older.
* You use the `flashMessage` feature.
* User input or data from URL parameters is incorporated into the `flashMessage`.

This is an example of a vulnerable snippet where query parameters are used to populate the `text` property of a `flashMessage`:

```javascript lines theme={null}
var params = new URLSearchParams(location.search);

var errorMessage = params.get('error__message');
var showParams = {};

if (!!errorMessage === true) {
  showParams.flashMessage = {
    type: 'error',
    text: 'We were unable to log you in. ' + errorMessage,
  };
}

lock.show(showParams);
```

### languageDictionary vulnerability

If all of these conditions are true, you're vulnerable:

* You use `auth0-lock` version `11.30.0` or older.
* You use the `languageDictionary` feature.
* User input or data from URL parameters is used in `languageDictionary` properties.

This is an example of a vulnerable snippet that uses query parameters to populate the `socialLoginInstructions` property of a `languageDictionary`:

```javascript lines theme={null}
var params = new URLSearchParams(location.search);
var instruction = params.get('instruction');

var options = {
  languageDictionary: {
    emailInputPlaceholder: "something@youremail.com",
    title: "title",
    socialLoginInstructions: instruction
  },
};

var lock = new Auth0LockPasswordless(
    CLIENT_ID,
    DOMAIN,
    options
);

lock.show();
```

## How to fix that?

Upgrade to `auth0-lock` version `11.30.1`.

## Will this update impact my users?

The fix uses [DOMPurify](https://github.com/cure53/DOMPurify) to sanitize the `flashMessage` and `languageDictionary` inputs. It removes any JavaScript in these fields, such as `script` tags or `onclick` attributes.


# CVE-2021-32702: Security Update for Auth0 Next.js Library
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/cve-2021-32702

CVE-2021-32702: Security Update for Auth0 Next.js Library

**Published**: June 23, 2021

**CVE number**: `CVE-2021-32702`

## Overview

Versions before and including `1.4.1` are vulnerable to reflected XSS. An attacker can execute arbitrary code by providing an XSS payload in the `error` query parameter which is then processed by the callback handler as an error message.

## Am I affected?

You are affected by this vulnerability if you are using `@auth0/nextjs-auth0` version `1.4.1` or lower **unless** you are using custom error handling that does not return the error message in an HTML response.

### How to fix that?

Upgrade to version `1.4.2`.

### Will this update impact my users?

The fix adds basic HTML escaping to the error message and it should not impact your users.

### Credit

[https://github.com/inian](https://github.com/inian)


# CVE-2021-41246: Security Update for Express OpenID Connect Library
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/cve-2021-41246

CVE-2021-41246: Security Update for Express OpenID Connect Library

**Published**: December 08, 2021

**CVE number**: `CVE-2021-41246`

### Overview

Versions `2.3.0` up to and including `2.5.1` do not regenerate the session id and <Tooltip href="/docs/glossary?term=session+cookie">session cookie</Tooltip> when user logs in. This behavior opens up the application to various session fixation vulnerabilities.

### Am I affected?

You are affected by this vulnerability if you are using `express-openid-connect` version `2.3.0` up to and including `2.5.1` and use a custom session store.

### How to fix that?

Upgrade to version `>= 2.5.2`

### Will this update impact my users?

The fix provided in patch will not affect your users.


# CVE-2021-43812: Security Update for Next.js Auth0 Library
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/cve-2021-43812

CVE-2021-43812: Security Update for Next.js Auth0 Library

**Published**: December 16, 2021

**CVE number**: CVE-2021-43812

### Overview

Versions `<=1.6.1` do not filter out certain `returnTo` parameter values from the login url, which expose the application to an open redirect vulnerability.

### Am I affected?

You are affected by this vulnerability if you are using `@auth0/nextjs-auth0` version `<=1.6.1`.

### How to fix that?

Upgrade to version `>=1.6.2`

### Will this update impact my users?

The fix provided in patch will not affect your users.


# CVE-2022-23505: Security Update for passport-wsfed-saml2 Library
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/cve-2022-23505

Describes the security update for the passport-wsfed-saml2 Library.

**Published**: Dec 12, 2022

CVE number: CVE-2022-23505

### Overview

A remote attacker can bypass WSFed authentication on a website using `passport-wsfed-saml2`. A successful attack requires that the attacker is in possession of an arbitrary <Tooltip href="/docs/glossary?term=IDP">IDP</Tooltip> signed WSFed assertion. Depending on the IDP used, fully unauthenticated attacks (e.g without access to a valid user) might also be feasible if generation of a signed message can be triggered.

### Am I affected?

You are affected if you are using WSFed protocol with the `passport-wsfed-saml2` library versions  `<4.6.3`.

SAML2 protocol is not affected.

### How to fix that?

Upgrade to version `>=4.6.3`

### Will this update impact my users?

The fix provided in the patch will not affect your users.


# CVE-2022-24794: Security Update for Express OpenID Connect Library
Source: https://auth0.com/docs/secure/security-guidance/security-bulletins/cve-2022-24794

CVE-2022-24794: Security Update for Express OpenID Connect Library

**Published**: March 30, 2022

**CVE number**: CVE-2022-24794

### Overview

Users of the `requiresAuth` middleware, either directly or through the default `authRequired` option, are vulnerable to an Open Redirect when the middleware is applied to a catch all route.

If all routes under `example.com` are protected with the `requiresAuth` middleware, a visit to `http://example.com//google.com` will be redirected to `google.com` after login because the original url reported by the Express framework is not properly sanitised.

### Am I affected?

You are affected by this vulnerability if you are using the `requiresAuth` middleware on a catch all route or the default `authRequired` option and `express-openid-connect` version `<=2.7.1`.

### How to fix that?

Upgrade to version `>=2.7.2`

### Will this update impact my users?

The fix provided in the patch will not affect your users.


# General Security Tips
Source: https://auth0.com/docs/secure/security-guidance/tips

Describes general security tips to prevent security breaches.

Users can't usually prevent certain sites from experiencing security breaches, but there are some things they can do to help keep their accounts safe.

### Check emails carefully

Check where an email is coming from and the links that they provide. Often phishing emails do not include a user's name but something generic such as "Dear Customer".

### Reset passwords directly from sites

Always do a password reset through the actual site itself not via potentially false links in emails. Also, note that a secure website URL always starts with `https`.

Here are some links for password resets on commonly-used sites:

* [Google](https://www.google.com/accounts/recovery/)
* [Facebook](https://www.facebook.com/settings)
* [X](https://x.com/settings/password)

### Never enter personal or financial information in emails

Emails in general are not very secure and are not a good way to communicate sensitive information. A trusted company/application would not ask for information in this way. Make sure not to enter confidential information through false links in emails.

### Never download files from unreliable sources

Most web browsers detect suspicious sites. An alert should appear when you try to access a malicious site. Never download files from suspicious emails or websites.

### Do not reuse passwords

When one site has a breach of user data, if a user uses the same credentials elsewhere, the information in other sites can also be accessed. The only way to prevent this is by not reusing passwords for multiple sites. The problem is that remembering countless passwords is frustrating and often impossible. One solution to this problem is the use of a password manager. There are many password managers available which can help users to use separate and secure passwords for each account, but at the same time not be responsible for remembering all of them.

### Use strong passwords

The longer a password is, the harder it becomes to be guessed via brute force methods. Many sites allow the use of pass-phrases (a phrase or sentence instead of just a complicated word.) Try to make passwords long and use a mix of special characters, numbers, and upper- and lowercase letters.

### Keep software current

Applications release patches and updates when they find security vulnerabilities in their systems. Keeping applications, web browsers, and operating systems up to date can help prevent security breaches.

### Check the security of your email inbox

If you use Gmail, Google offers the [Security Checkup](https://myaccount.google.com/security-checkup) tool to let you know if there are any security issues related to your inbox.

You can also use third-party tools, such as websites like [HaveIBeenPwned](https://haveibeenpwned.com/PwnedWebsites) to see if there might be security issues associated with your email address.

## Learn more

* [Attack Protection](/docs/secure/attack-protection)
* [View Attack Protection Log Events](/docs/secure/attack-protection/view-attack-protection-events)


# Sender Constraining
Source: https://auth0.com/docs/secure/sender-constraining

Learn how to sender constrain tokens in Auth0.

Sender constraining is an <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> and <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) security mechanism that cryptographically binds access and <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip> to the application that requested them, preventing token theft and misuse.

Traditionally, OAuth 2.0 <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> are bearer tokens, which means whoever “bears” or possesses the token can use it. If a bearer token is stolen or leaked, an attacker can present it to a <Tooltip href="/docs/glossary?term=resource+server">resource server</Tooltip> (API) and gain unauthorized access by impersonating the legitimate client application or user.

Sender constraining ensures that the client application presenting the access token to a resource server is the valid owner of the access token. If the client application is not the valid owner of the access token, then the resource server rejects the API request.

## How it works

You can implement sender constraining in one of two ways:

* Mutual-TLS (mTLS) certificate binding in the transport layer:

  * **Mechanism:** When the client application requests an access token from the Auth0 Authorization Server, it establishes a mutual TLS (mTLS) connection, where both the client application and the server present and verify each other's X.509 certificates.
  * **Binding:** The Auth0 Authorization Server includes a confirmation (`cnf`) claim that includes the thumbprint of the client application's certificate directly within the issued access token.
  * **Proof of Possession:** When the client application uses the mTLS-bound access token to access a resource server, it must again establish an mTLS connection using the same certificate. The resource server verifies that the certificate presented by the client application matches the one bound to the access token. If they don't match, the resource server rejects the request.
  * **Benefit:** Even if an attacker steals the access token, they cannot use it because they won't possess the corresponding private key and certificate required to establish the correct mTLS connection. mTLS sender constraining is typically used by confidential clients such as server-side applications that can securely store and manage X.509 certificates and their private keys.
* Demonstrating Proof-of-Possession (DPoP) in the application layer:

  * **Mechanism:** DPoP operates at the application layer and doesn't require mTLS. Instead, the client application generates a cryptographic key pair (private/public key) for itself.
  * **Binding:** When requesting an access token, the client application creates a JSON Web Token (JWT) called a DPoP Proof JWT. This proof JWT contains the client's public key and is signed by the client's private key. The client application sends the DPoP Proof JWT along with the access token request. The Auth0 Authorization Server validates the DPoP Proof JWT and then binds the issued access token to the public key.
  * **Proof of Possession:** When the client application uses the DPoP-bound access token to call a resource server, it generates another DPoP Proof JWT signed with its private key for that API request. The client application sends the DPoP Proof JWT in a header alongside the access token. The resource server verifies that the access token is bound to the public key in the DPoP Proof JWT, and that the DPoP Proof JWT itself has been signed by the corresponding private key using a confirmation (`cnf`) claim.
  * **Benefit:** DPoP is more flexible than mTLS because it doesn't require a public key infrastructure. Various client types can use it, including public clients like SPAs and mobile applications.

## mTLS vs. DPoP

The following table summarizes the high-level differences between mTLS and DPoP for sender constraining tokens:

<table>
  <thead>
    <tr>
      <th><strong>Attribute</strong></th>
      <th><strong>mTLS</strong></th>
      <th><strong>DPoP</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Layer of operation</td>
      <td>Transport layer (TLS/SSL)</td>
      <td>Application layer (HTTP headers)</td>
    </tr>

    <tr>
      <td>Cryptography</td>
      <td>Using Public Key Infrastructure  (X.509 Certificates)</td>
      <td>Using asymmetric keys (Client-generated key pairs)</td>
    </tr>

    <tr>
      <td>Proof of Possession</td>
      <td>TLS handshake and certificate validation</td>
      <td>DPoP Proof (signed JWT in HTTP header for each request)</td>
    </tr>

    <tr>
      <td>Client type</td>
      <td>Confidential clients</td>
      <td>Public clients (SPAs, mobile apps)</td>
    </tr>
  </tbody>
</table>

To learn more, read [mTLS Sender Constraining](/docs/secure/sender-constraining/mtls-sender-constraining) and [Demonstrating Proof-of-Possession (DPoP)](/docs/secure/sender-constraining/demonstrating-proof-of-possession-dpop).

## Get started

To get started with Sender Constraining at Auth0, read the following:

<table>
  <thead>
    <tr>
      <th><strong>Read</strong></th>
      <th><strong>To learn</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/secure/sender-constraining/mtls-sender-constraining">mTLS Sender Constraining</a></td>
      <td>How mTLS sender constraining works in Auth0, step by step.</td>
    </tr>

    <tr>
      <td><a href="/docs/secure/sender-constraining/demonstrating-proof-of-possession-dpop">Demonstrating Proof-of-Possession (DPoP)</a></td>
      <td>How DPoP works in Auth0, step by step.</td>
    </tr>

    <tr>
      <td><a href="/docs/secure/sender-constraining/configure-sender-constraining">Configure Sender Constraining</a></td>
      <td>How to configure sender constraining for a client application and resource server in Auth0.</td>
    </tr>
  </tbody>
</table>

## Learn more

* [mTLS Sender Constraining](/docs/secure/sender-constraining/mtls-sender-constraining)
* [Demonstrating Proof-of-Possession (DPoP)](/docs/secure/sender-constraining/demonstrating-proof-of-possession-dpop)
* [Configure Sender Constraining](/docs/secure/sender-constraining/configure-sender-constraining)


# Configure Sender Constraining
Source: https://auth0.com/docs/secure/sender-constraining/configure-sender-constraining

Overview of how to configure Sender Constraining for your Auth0 tenant.

[Sender constraining](/docs/secure/sender-constraining) is an <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> and <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) security mechanism that cryptographically binds access and <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip> to the specific client application that obtained them, preventing token theft and misuse.

Auth0 supports mTLS sender constraining and Demonstrating Proof-of-Possession (DPoP). If you enable sender constraining for a client application, then you must also enforce it for the <Tooltip href="/docs/glossary?term=resource+server">resource server</Tooltip> you’re making API calls to.

To configure sender constraining in Auth0, you must:

* [Configure sender constraining for a client application](#configure-sender-constraining-for-a-client-application)
* [Configure sender constraining for a resource server](#configure-sender-constraining-for-a-resource-server)

## How it works

<Tooltip href="/docs/glossary?term=Access+tokens">Access tokens</Tooltip> are sender constrained in Auth0 depending on how you configure sender constraining for your client application and resource server:

1. **Requested audience:** In a token request, whether the requested audience is `/userinfo` only, or only intended to be used with the [`/userinfo`](https://auth0.com/docs/api/authentication/user-profile/get-user-info) endpoint, or is a custom API that may include `/userinfo` when you also request the openid scope, affects whether access tokens are sender constrained.
2. **Client application:** Whether you set sender constraining as `required` by the client application.
3. **Resource server:** Whether you configure sender constraining for the resource server:

   1. `none`: You have not configured sender constraining for the resource server.
   2. `allowed`: You have configured sender constraining for the resource server by setting a sender constraining method.
   3. `required`: You have configured sender constraining as required for the resource server, meaning that access tokens must be sender-constrained to an application. You can require sender constraining for all applications or for public applications only. Requires a sender constraining method.

<Callout icon="lightbulb">
  When using mTLS as the sender constraining method, sender constraining is always required for all applications. Public applications are not supported with mTLS, so you cannot limit mTLS sender constraining to public clients only.
</Callout>

* **Proof-of-Possession:** Whether the client application sent a proof-of-possession assertion in the token request:

  * mTLS sender constraining: The proof of possession is demonstrated through the client's successful presentation of a specific private key (associated with a client certificate) during the TLS handshake.
  * DPoP: The proof of possession is achieved by the client creating a DPoP Proof JWT by cryptographically signing it with its private key and including the `DPoP` Proof JWT in the DPoP HTTP header of every request where the associated access token is used.

The following table describes how access tokens are issued and whether they are sender-constrained based on various client request parameters and Auth0 resource server configurations:

<table>
  <thead>
    <tr>
      <th><strong>Requested Audience Type</strong></th>
      <th><strong>Client Requires PoP?</strong></th>
      <th><strong>Proof-of-Possession (PoP) Sent by Client?</strong></th>
      <th><strong>Auth0 Resource Server Policy: None</strong></th>
      <th><strong>Auth0 Resource Server Policy: Allowed (Not Required)</strong></th>
      <th><strong>Auth0 Resource Server Policy: Required</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Userinfo Only</td>
      <td>No</td>
      <td>No</td>
      <td>Issued, Not Sender-Constrained</td>
      <td>N/A</td>
      <td>N/A</td>
    </tr>

    <tr>
      <td>Userinfo Only</td>
      <td>No</td>
      <td>Yes</td>
      <td>Issued, Sender-Constrained</td>
      <td>N/A</td>
      <td>N/A</td>
    </tr>

    <tr>
      <td>Userinfo Only</td>
      <td>Yes</td>
      <td>No</td>
      <td>Not Issued</td>
      <td>N/A</td>
      <td>N/A</td>
    </tr>

    <tr>
      <td>Userinfo Only</td>
      <td>Yes</td>
      <td>Yes</td>
      <td>Issued, Sender-Constrained</td>
      <td>N/A</td>
      <td>N/A</td>
    </tr>

    <tr>
      <td>Custom Audience (may contain Userinfo)</td>
      <td>No</td>
      <td>No</td>
      <td>Issued, Not Sender-Constrained</td>
      <td>Issued, Not Sender-Constrained</td>
      <td>Not Issued</td>
    </tr>

    <tr>
      <td>Custom Audience (may contain Userinfo)</td>
      <td>No</td>
      <td>Yes</td>
      <td>Issued, Not Sender-Constrained</td>
      <td>Issued, Sender-Constrained</td>
      <td>Issued, Sender-Constrained</td>
    </tr>

    <tr>
      <td>Custom Audience (may contain Userinfo)</td>
      <td>Yes</td>
      <td>No</td>
      <td>Not Issued</td>
      <td>Not Issued</td>
      <td>Not Issued</td>
    </tr>

    <tr>
      <td>Custom Audience (may contain Userinfo)</td>
      <td>Yes</td>
      <td>Yes</td>
      <td>Not Issued</td>
      <td>Issued, Sender-Constrained</td>
      <td>Issued, Sender-Constrained</td>
    </tr>
  </tbody>
</table>

## Configure sender constraining for a client application

When you require sender constraining for a client application, access tokens are constrained to that application. Auth0 verifies requests to ensure that only the application that requested the token can use it to access the associated resource.

Once you configure a client application to require sender constraining, you can set the sender constraining method, either mTLS or DPoP, when configuring your resource server.

You can configure sender constraining for a client application with the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

<Tabs>
  <Tab title="Auth0 Dashboard">
    1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications). Select the application you want to configure.
    2. Under **Settings**, scroll to **Token Sender-Constraining**.
    3. Toggle on to **Require Sender Constraining**. Toggle off to remove the requirement for Sender Constraining for the application.

    <Frame>
      <img alt="" />
    </Frame>
  </Tab>

  <Tab title="Management API">
    To configure a client for Sender Constraining, use the [Management API](https://auth0.com/docs/api/management/v2).

    To require Sender Constraining for a client, send a PATCH request to [update the client's settings](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id). Set the `require_proof_of_possession` parameter to `true`.

    ```bash lines theme={null}
    curl -L -X PATCH 'https://{YOUR_DOMAIN}/api/v2/clients/{YOUR_CLIENT_ID}' \
    -H 'Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
    -H 'Content-Type: application/json' \
    -d '{"require_proof_of_possession": true}'
    ```

    To remove the requirement for Sender Constraining, set the `require_proof_of_possession` parameter to `false`.

    ```bash lines theme={null}
    curl -L -X PATCH 'https://{YOUR_DOMAIN}/api/v2/clients/{YOUR_CLIENT_ID}' \
    -H 'Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
    -H 'Content-Type: application/json' \
    -d '{"require_proof_of_possession": false}'
    ```
  </Tab>
</Tabs>

## Configure sender constraining for a resource server

Access tokens issued by Auth0 can be constrained to the sender (i.e. the client application) that needs to access APIs at a resource server.

You can configure sender constraining for a resource server with the Auth0 Dashboard or Management API.

<Tabs>
  <Tab title="Auth0 Dashboard">
    To enable Token Binding or sender constraining, configure the **API Settings** of your API.

    1. Navigate to [Auth0 Dashboard > Applications > APIs](https://manage.auth0.com/#/apis).
    2. Select the API you want to configure.
    3. Under the **Settings** tab, find the **Token Sender-Constraining** section.
    4. Configure the following:

       1. Sender Constraining Method:

          1. **None:** Don’t enable a sender constraining method for your resource server.
          2. **mTLS**: Enable mTLS as the sender constraining method for your resource server.
          3. **DPoP:** Enable DPoP as the sender constraining method for your resource server.

       2. Require Token Sender Constraining: Select which sender constraining policy applies for this API:

          1. **Always:** Require sender constraining for all applications. This is the only option available when using mTLS.
          2. **For Public Applications:** Require sender constraining for public applications only. This option is not available when using mTLS.
          3. **Never:** Sender constraining is not required.

    <Frame>
      <img alt="Auth0 Dashboard > APIs > Settings > Token binding" />
    </Frame>
  </Tab>

  <Tab title="Management API">
    To enable Sender Constraining with the Management API, send a PATCH request to [update the resource server](https://auth0.com/docs/api/management/v2/resource-servers/patch-resource-servers-by-id). Set the parameters of the `proof_of_possession` object to the following:

    <table>
      <thead>
        <tr>
          <th><strong>Parameter</strong></th>
          <th><strong>Description</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>mechanism</code></td>
          <td>Sets the sender-constraining method: <code>none</code>, <code>mtls</code>, or <code>dpop</code>.</td>
        </tr>

        <tr>
          <td><code>required</code></td>
          <td>Required. When set to <code>true</code>, access tokens issued to an application for this API will be constrained to that application. Use <code>required\_for</code> to specify which application types this requirement applies to. When set to <code>false</code>, sender constraining is not required.</td>
        </tr>

        <tr>
          <td><code>required\_for</code></td>
          <td>Filters which application types require sender constraining when <code>required</code> is <code>true</code>: <code>all\_clients</code> (all applications) or <code>public\_clients</code> (public applications only). Defaults to <code>all\_clients</code> if not specified. When using mTLS, only <code>all\_clients</code> is valid.</td>
        </tr>
      </tbody>
    </table>

    The following code sample is an example request body that configures a resource server for mTLS Sender Constraining. Because mTLS only supports `all_clients` for `required_for` (which is the default), it does not need to be specified:

    ```bash lines theme={null}
    curl -L -X PATCH 'https://{YOUR_DOMAIN}/api/v2/resource-servers/{YOUR_RESOURCE_SERVER_ID}' \
    -H 'Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
      "proof_of_possession": {
        "mechanism": "mtls",
        "required": true
      }
    }'
    ```

    The following code sample is an example request body that configures a resource server for DPoP Sender Constraining, required for public applications only:

    ```bash lines theme={null}
    curl -L -X PATCH 'https://{YOUR_DOMAIN}/api/v2/resource-servers/{YOUR_RESOURCE_SERVER_ID}' \
    -H 'Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
      "proof_of_possession": {
        "mechanism": "dpop",
        "required": true,
        "required_for": "public_clients"
      }
    }'
    ```

    The following code sample configures DPoP Sender Constraining as required for all applications. Because `all_clients` is the default, `required_for` can be omitted:

    ```bash lines theme={null}
    curl -L -X PATCH 'https://{YOUR_DOMAIN}/api/v2/resource-servers/{YOUR_RESOURCE_SERVER_ID}' \
    -H 'Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
      "proof_of_possession": {
        "mechanism": "dpop",
        "required": true
      }
    }'
    ```

    The following code sample disables sender constraining for a resource server (equivalent to selecting "Never" in the Dashboard):

    ```bash lines theme={null}
    curl -L -X PATCH 'https://{YOUR_DOMAIN}/api/v2/resource-servers/{YOUR_RESOURCE_SERVER_ID}' \
    -H 'Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
      "proof_of_possession": null 
    }'
    ```
  </Tab>
</Tabs>


# Demonstrating Proof-of-Possession (DPoP)
Source: https://auth0.com/docs/secure/sender-constraining/demonstrating-proof-of-possession-dpop

Learn how to use Demonstrating Proof-of-Possession (DPoP) to sender constrain access tokens in Auth0.

Demonstrating Proof-of-Possession (DPoP) is an [OAuth 2.0 framework extension](https://datatracker.ietf.org/doc/draft-ietf-oauth-dpop/) that binds or [sender constrains](/docs/secure/sender-constraining) <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> using asymmetric cryptography and <Tooltip href="/docs/glossary?term=JSON+Web+Tokens">JSON Web Tokens</Tooltip> (JWTs) at the application layer. DPoP ensures that only the client application that requested the access token, which possesses the private key, can use it. This prevents the misuse of stolen tokens.

DPoP uses a public/private key to create a DPoP Proof as a signed JSON Web Token (JWT). The DPoP Proof contains:

* The client’s public key (`jwk`).
* The payload referencing the access token request, including the method (`htm`) and URI (`htu`).
* A signature created using the client’s private key.
* A unique ID (`jti`) for replay prevention.
* For every API request, a base64url-encoded SHA-256 hash (`ath`) of the access token.
* Optional: For <Tooltip href="/docs/glossary?term=public+clients">public clients</Tooltip>, a `nonce` claim to ensure the client application recently generated the DPoP Proof JWT.

The client application sends the DPoP Proof JWT in an access token request to the Auth0 <Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip>. After the Auth0 Authorization Server validates the DPoP Proof JWT, it binds the issued access token to the client’s public key.

## Common use cases

Learn about some common DPoP use cases:

* **Single Page Applications (SPAs) and mobile applications:** As public clients, SPAs and mobile applications lack a trusted, confidential environment like a backend server to securely store <Tooltip href="/docs/glossary?term=client+secrets">client secrets</Tooltip>, which makes them vulnerable to token theft. DPoP addresses this security vulnerability by binding access tokens to the client application’s public key, creating a DPoP Proof JWT. The client application signs the DPoP Proof JWT with its private key and sends in an authorization request. The Auth0 Authorization Server validates the DPoP Proof JWT, and, if valid, binds the issued access token to the client’s public key.
* **Third-party API integrations:** If an AI agent integrated with your client application calls a third-party API on the user’s behalf using a DPoP Proof JWT, then the <Tooltip href="/docs/glossary?term=resource+server">resource server</Tooltip> can cryptographically validate that the request is coming from the AI agent and not an unauthorized third party.

## Supported application grant types

Auth0 supports the following [application grant types](/docs/get-started/applications/application-grant-types) for sender constraining with DPoP:

<table>
  <thead>
    <tr>
      <th><strong>Grant type</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>authorization\_code</code></td>
      <td>Authorization Code Grant</td>
    </tr>

    <tr>
      <td><code>client\_credentials</code></td>
      <td>Client Credentials Grant</td>
    </tr>

    <tr>
      <td><code>password</code></td>
      <td>Resource Owner Password Grant</td>
    </tr>

    <tr>
      <td><code>refresh\_token</code></td>
      <td>Refresh Token Grant</td>
    </tr>

    <tr>
      <td><code>urn:ietf:params:oauth:grant-type:device\_code</code></td>
      <td>Device Authorization Grant</td>
    </tr>

    <tr>
      <td><code>[http://auth0.com/oauth/grant-type/password-realm](http://auth0.com/oauth/grant-type/password-realm)</code></td>
      <td>Use an extension grant similar to the Resource Owner Password Grant that includes the ability to indicate a specific realm</td>
    </tr>

    <tr>
      <td><code>[http://auth0.com/oauth/grant-type/passwordless/otp](http://auth0.com/oauth/grant-type/passwordless/otp)</code></td>
      <td>Passwordless Grant Request</td>
    </tr>

    <tr>
      <td><code>[http://auth0.com/oauth/grant-type/mfa-oob](http://auth0.com/oauth/grant-type/mfa-oob)</code></td>
      <td>Multi-factor Authentication OOB Grant Request</td>
    </tr>

    <tr>
      <td><code>[http://auth0.com/oauth/grant-type/mfa-otp](http://auth0.com/oauth/grant-type/mfa-otp)</code></td>
      <td>Multi-factor Authentication OTP Grant Request</td>
    </tr>

    <tr>
      <td><code>[http://auth0.com/oauth/grant-type/mfa-recovery-code](http://auth0.com/oauth/grant-type/mfa-recovery-code)</code></td>
      <td>Multi-factor Authentication Recovery Grant Request</td>
    </tr>

    <tr>
      <td><code>urn:ietf:params:oauth:grant-type:token-exchange</code></td>
      <td>Custom Token Exchange Grant Request</td>
    </tr>

    <tr>
      <td><code>urn:okta:params:oauth:grant-type:webauthn</code></td>
      <td>WebAuthn Grant Request</td>
    </tr>
  </tbody>
</table>

## How it works

The following sequence diagram illustrates the high-level steps in the Auth0 DPoP flow:

<Frame>
  <img alt="" />
</Frame>

1. When requesting an access token from the Auth0 Authorization Server, the client application generates a unique cryptographic key pair and uses the public key to prove its possession of the private key.
2. The client application generates the DPoP Proof JWT and sends it to the /token endpoint on the Auth0 Authorization Server.
3. The Auth0 Authorization Server verifies the DPoP Proof JWT, and if valid, issues the access token and binds it to the client's public key.
4. Before calling the Customer API, the client application generates a new DPoP Proof JWT to prove it possesses the private key associated with the token. The client application sends the DPoP Proof JWT and the sender-constrained access token to the resource server.
5. The resource server verifies the DPoP Proof JWT, ensuring that only the valid owner of the token, or the original client application,can successfully use it to access protected resources. To request an access token from a refresh token, the client application generates a new DPoP Proof JWT, ensuring the refresh token is bound to the client's public key.

## Sender constrain tokens using DPoP in Auth0

The following diagram shows the end-to-end flow for sender constraining tokens using DPoP in Auth0:

<Frame>
  <img alt="" />
</Frame>

The following sections walk you step-by-step through the DPoP in Auth0 flow with code samples for implementation:

* [Prerequisites](#prerequisites)
* [Step 1: Client application generates a DPoP key pair](#step-1-client-application-generates-a-dpop-key-pair)
* [Step 2: Client application creates DPoP Proof JWT](#step-2-client-application-creates-a-dpop-proof-jwt)
* [Step 3: Client application requests a DPoP-bound token](#step-3-client-application-requests-a-dpop-bound-token)
* [Step 4: Auth0 Authorization Server validates the DPoP Proof JWT](#step-4-auth0-authorization-server-validates-the-dpop-proof-jwt)
* [Step 5: Client application calls API with the DPoP-bound token and DPoP Proof JWT](#step-5-client-application-calls-api-with-the-dpop-bound-token-and-dpop-proof-jwt)
* [Step 6: Handle token refresh with DPoP](#step-6-handle-token-refresh-with-dpop)

## Prerequisites

Before you begin, make sure you:

* [Configure sender constraining](/docs/secure/sender-constraining/configure-sender-constraining) for your client application and resource server.

## Step 1: Client application generates a DPoP key pair

For DPoP, the client application must generate an asymmetric cryptographic key pair. Auth0 supports the use of Elliptic Curve, such as in ES256 keys. This key pair is unique to your client application and should be securely stored, for example, in a hardware-backed keystore.

The client application keeps the private key secret while including the public key in the DPoP Proof JSON Web Token (JWT) that serves as the “proof of possession” in [Step 2](#step-2-client-application-creates-a-dpop-proof-jwt).

## Step 2: Client application creates a DPoP Proof JWT

Before requesting a DPoP-bound access token from the Auth0 Authorization Server’s `/token` endpoint, your client application must create a DPoP Proof JWT. A DPoP Proof JWT is a JSON Web Token (JWT) signed by your client's private key that serves as the “proof of possession.”

The DPoP Proof JWT consists of a JWT header and payload that contains [claims](/docs/secure/tokens/json-web-tokens/json-web-token-claims) linked to the token request:

### JWT header claims

<table>
  <thead>
    <tr>
      <th><strong>DPoP Proof JWT Claim</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>typ</code></td>
      <td>Set to <code>dpop+jwt</code>.</td>
    </tr>

    <tr>
      <td><code>alg</code></td>
      <td>The asymmetric signing algorithm used, such as <code>RS256</code> or <code>ES256</code>.</td>
    </tr>

    <tr>
      <td><code>jwk</code></td>
      <td>A JSON Web Key (JWK) representation of your client's public key.</td>
    </tr>
  </tbody>
</table>

### JWT payload claims

<table>
  <thead>
    <tr>
      <th><strong>DPoP Proof JWT Claim</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>jti</code></td>
      <td>A unique identifier for the JWT to prevent replay attacks.</td>
    </tr>

    <tr>
      <td><code>htm</code></td>
      <td>The HTTP method of the request the DPoP proof is for, such as <code>POST</code> for token requests and <code>GET</code> for API calls.</td>
    </tr>

    <tr>
      <td><code>htu</code></td>
      <td>The HTTP URI of the request the DPoP Proof JWT is for, without the fragment and query parameters. For example: `https://api.example.com/data?param=1#section1` becomes `https://api.example.com/data`.</td>
    </tr>

    <tr>
      <td><code>iat</code></td>
      <td>The creation timestamp of the JWT.</td>
    </tr>

    <tr>
      <td><code>ath</code></td>
      <td>For API calls with an access token, a base64url-encoded SHA-256 hash of the access token.</td>
    </tr>

    <tr>
      <td><code>nonce</code></td>
      <td>For public clients requiring a <code>nonce</code>, a server-provided <code>nonce</code> value.</td>
    </tr>
  </tbody>
</table>

Once the client application creates the DPoP Proof JWT, it signs the DPoP Proof JWT with the private key generated in [Step 1](#step-1-client-application-generates-a-dpop-key-pair).

The following code sample shows how to create and sign a DPoP Proof JWT in your client application:

```jsx lines theme={null}
import { generateKeyPairSync, randomBytes } from 'node:crypto';
import jwt from 'jsonwebtoken';

// Generate a DPoP Key Pair
const keyPair = generateKeyPairSync('ec', {
  namedCurve: 'P-256',
});

// Construct the DPoP Proof JWT for the token request
const jti = randomBytes(16).toString('base64url');
const jwk = keyPair.publicKey.export({ format: 'jwk' });
const dpopHeader = jwt.sign({
    jti,
    htm: 'POST',
    htu: 'https://[TENANT]/oauth/token',
    iat: Date.now() / 1000,
  },
  keyPair.privateKey,
  {
    algorithm: 'ES256',
    header: {
      typ: 'dpop+jwt',
      jwk,
    },
  });
```

## Step 3: Client application requests a DPoP-bound token

When your client application requests an access token from the Auth0 Authorization Server’s `/token` endpoint, it includes the DPoP Proof JWT in the HTTP header of the request:

```http lines theme={null}
DPoP: {DPoP_proof_JWT_value}
```

The following is an example access token request that includes the DPoP HTTP header populated with a DPoP Proof JWT:

```http lines theme={null}
POST /oauth/token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded
DPoP: {DPoP Proof JWT}
Authorization: Basic Y2xpZW50MTIzOm15c2VjcmV0
Cache-Control: no-cache
grant_type=client_credentials&client_id=client123
```

To implement how to request a DPoP-bound access token in your client application, use the following code sample, which does the following:

1. Populates the DPoP HTTP header with a signed DPoP Proof JWT.
2. Sends the DPoP HTTP header with a signed DPoP Proof JWT in an access token request to the `/token` endpoint.
3. Processes the response from the Auth0 Authorization Server.

```javascript lines theme={null}
// Make the request to the /oauth/token endpoint
// Replace [...] with your actual grant_type, client_id, and tenant URL
const response = await fetch('https://[TENANT]/oauth/token', {
    method: 'POST',
    body: new URLSearchParams({
      grant_type: '...',
      client_id: '...',
      // Other body parameters here
    }),
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
      // Add the DPoP header
      dpop: dpopHeader
    }
  });

// Process the response from the Auth0 Authorization Server
const result = await response.json();
console.log('Initial token request result:', result);
```

### Public clients

If a public client, such as a single-page application (SPA) or mobile app, requests a DPoP-bound access token, you won’t have a client secret or other client authentication parameters. In this case, and in accordance with [RFC 9449](https://datatracker.ietf.org/doc/html/rfc9449#section-8), Auth0 requires your DPoP HTTP header to have a <Tooltip href="/docs/glossary?term=nonce">nonce</Tooltip> value to ensure the client application recently generated the DPoP Proof JWT. This is expected behavior as it allows the Authorization Server to ensure the DPoP proof is fresh and limits the window in which a proof can be used.

If a public client makes a `/token` request and doesn’t include a `nonce` value in the DPoP HTTP header, Auth0 responds with an `HTTP 400` code and an error message like the following:

```js lines theme={null}
{
  error: 'use_dpop_nonce',
  error_description: 'Authorization server requires nonce in DPoP proof'
}
```

Auth0 includes a `DPoP-Nonce` header in the response headers. This follows the standard "challenge-response" flow defined in the [DPoP specification](https://datatracker.ietf.org/doc/html/rfc9449). You must use the value of the `DPoP-Nonce` header and regenerate the DPoP proof (as in [Step 2](#step-2-client-application-creates-a-dpop-proof-jwt)), include a `nonce` claim with that value, and resubmit the request to the `/token` endpoint.

The following code sample shows the end-to-end flow when making and then retrying a `/token` request with a nonce claim from a public client:

```jsx lines expandable theme={null}
import { generateKeyPairSync, randomBytes } from 'node:crypto';
import jwt from 'jsonwebtoken';

// Generate a DPoP Key Pair
const keyPair = generateKeyPairSync('ec', {
  namedCurve: 'P-256',
});

/**
 * Helper function to generate a DPoP Proof JWT.
 * @param {string} method - HTTP method (e.g., 'POST', 'GET').
 * @param {string} url - Full URL of the request.
 * @param {string} [nonce] - Optional DPoP-Nonce value from the server.
 * @param {string} [accessToken] - Optional access token to hash for 'ath' claim.
 * @returns {string} The signed DPoP Proof JWT.
 */
function generateDPoPHeader(method, url, nonce) {
  const jti = randomBytes(16).toString('base64url');
  const jwk = keyPair.publicKey.export({ format: 'jwk' });
  return jwt.sign({
      jti,
      htm: method,
      htu: url,
      iat: Date.now() / 1000,
      nonce
    },
    keyPair.privateKey,
    {
      algorithm: 'ES256',
      header: {
        typ: 'dpop+jwt',
        jwk,
      },
    });
  }

// Request access token the first time without nonce 
async function getTokens(nonce) {
  const response = await fetch('https://[TENANT]/oauth/token', {
      method: 'POST',
      body: new URLSearchParams({
        grant_type: '...',
        client_id: '...',
        // Other body parameters here
      }),
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
        dpop: generateDPoPHeader('POST', 'https://[TENANT]/oauth/token', nonce),
      }
    });

  const result = await response.json();
  return { response, result };
}

// The first time we request tokens, we won't have a nonce
let { response, result } = await getTokens(); 
console.log('Initial token request result:', result);

if (response.status === 400 && result.error === 'use_dpop_nonce') {
  const nonce = response.headers.get('dpop-nonce');

  console.log('Received nonce:', nonce);

  // Retry with the nonce
  ({ response, result } = await getTokens(nonce)); 

  console.log('Tokens received:', result);
}
```

## Step 4: Auth0 Authorization Server validates the DPoP Proof JWT

When the Auth0 Authorization Server receives the token request, it does the following:

* Extracts the DPoP Proof JWT, its public key, and signature.
* Verifies the signature using the provided public key.
* Validates the `htm`, `htu`, `jti,` and `iat` claims.
* If valid, it issues an access token. The Auth0 Authorization Server includes a confirmation claim, `cnf`, in the access token. The `cnf` claim contains the thumbprint (hash) of the public key taken from the DPoP Proof JWT. By including it in the access token, the Auth0 Authorization Server binds the access token to that specific public key, or “sender-constrains” the access token.
* Sets the `token_type` in the `Authorization` header to `DPoP` instead of `Bearer` in the token response. Traditionally, when the access token is passed in the `Authorization` header, it is set to `Bearer`. However, because we’re passing an access token bound to a public key using DPoP, it is set to `DPoP` instead.
* The Auth0 Authorization Server then issues the DPoP sender-constrained access token to your client application.

## Step 5: Client application calls API with the DPoP-bound token and DPoP Proof JWT

For every API call to a resource server that enforces DPoP, your client application must present both the DPoP-bound access token and a new DPoP Proof JWT.

By requiring a DPoP Proof JWT with every API request, DPoP ensures that only the client application that possesses the private key can use the access token.

For a new API request, the client application:

1. Generates a new DPoP Proof JWT with the following claims:

* The `htm` claim is the API request's `HTTP` method, such as `GET` or `POST`.
* The `htu` claim is the API request's URI.
* The `ath` claim is the base64url-encoded SHA-256 hash of the DPoP-bound access token you received in [Step 3](#step-3-client-application-requests-a-dpop-bound-token).

2. Cryptographically signs the new DPoP Proof JWT with the client's private key.

3. Includes the DPoP-bound access token in the `Authorization` header using the `DPoP` authentication scheme:

```javascript lines theme={null}
// The DPoP scheme aligns with the token_type received from the Authorization Server
Authorization: DPoP {access_token}
```

4. Includes the newly generated DPoP Proof JWT in the `DPoP` HTTP header:

```http lines theme={null}
DPoP: {new_dpop_proof_jwt}
```

The `DPoP` HTTP header must include an additional `ath` claim. The `ath` claim is a base64url encoded SHA256 hash of the issued access token.

The resource server:

* Receives the API request and extracts the access token, DPoP JWT proof, public key, and signature.
* Verifies the DPoP Proof JWT's signature using the public key from its `jwk` header.
* Validates the `htm`, `htu`, `jti`, `iat`, and `ath` claims.
* Verifies that the public key indicated in the DPoP Proof JWT via its `jwk` header matches the public key bound to the access token via the `cnf.jkt` claim in the access token.

If all checks pass, the resource server authorizes the request. If not, it rejects the request, and access is denied.

The following code sample requests an access token from Auth0 using DPoP and then calls the `/userinfo` endpoint using a DPoP-bound access token:

```jsx lines expandable theme={null}
import { generateKeyPairSync, randomBytes, createHash } from 'node:crypto';
import jwt from 'jsonwebtoken';

const keyPair = generateKeyPairSync('ec', {
  namedCurve: 'P-256',
});

function hashToken(token) {
  return createHash('sha256').update(token).digest('base64url');
}

function generateDPoPHeader(method, url, nonce, accessToken) {
  const jti = randomBytes(16).toString('base64url');
  const jwk = keyPair.publicKey.export({ format: 'jwk' });
  return jwt.sign({
      jti,
      htm: method,
      htu: url,
      iat: Date.now() / 1000,
      nonce,

      // Optionally include an `ath` claim containing an access token hash
      ...(accessToken ? { ath: hashToken(accessToken) } : {}),
    },
    keyPair.privateKey,
    {
      algorithm: 'ES256',
      header: {
        typ: 'dpop+jwt',
        jwk,
      },
    });
  }

async function getTokens(nonce) {
  const response = await fetch('https://[TENANT]/oauth/token', {
      method: 'POST',
      body: new URLSearchParams({
        grant_type: '...',
        client_id: '...',
        // Other body parameters here
      }),
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
        dpop: generateDPoPHeader('POST', 'https://test1.local.dev.auth0.com/oauth/token', nonce),
      }
    });

  const result = await response.json();
  return { response, result };
}

// The first time we do this, we won't have a nonce
let { response, result } = await getTokens(); 
console.log('Initial token request result:', result);

if (response.status === 400 && result.error === 'use_dpop_nonce') {
  const nonce = response.headers.get('dpop-nonce');
  console.log('Received nonce:', nonce);
  ({ response, result } = await getTokens(nonce)); // Retry with the nonce
  console.log('Tokens received:', result);
}

// Now call /userinfo with DPoP
const userInfoResponse = await fetch('https://[TENANT]/userinfo', {
  method: 'GET',
  headers: {
    // Pass our access token using the DPoP authorization scheme
    Authorization: `DPoP ${result.access_token}`,

    // Include a DPoP header, this time with access token hash
    dpop: generateDPoPHeader('GET', 'https://[TENANT]/userinfo', nonce, result.access_token),
  },
});

console.log('User info response status:', userInfoResponse.status);
console.log('User info result:', await userInfoResponse.json());
```

## Step 6: Handle token refresh with DPoP

When your DPoP-bound access token expires, you can use a <Tooltip href="/docs/glossary?term=refresh+token">refresh token</Tooltip> to get a new one. A refresh token request requires a DPoP Proof JWT generated using the same key pair used in the original token request.

The following describes the refresh token flow with DPop in Auth0:

The client application:

* Makes a refresh token request to the Auth0 Authorization Server’s `/token` endpoint.
* Generates a DPoP Proof JWT for the refresh token request (similar to [Step 2](#step-2-client-application-creates-a-dpop-proof-jwt), with `htm` as `POST` and `htu` as the <Tooltip href="/docs/glossary?term=token+endpoint">token endpoint</Tooltip> URI).
* Includes the DPoP Proof JWT in the `DPoP` HTTP header.

The Auth0 Authorization Server:

* Validates the DPoP Proof JWT (like in [Step 4](#step-4-auth0-authorization-server-validates-the-dpop-proof-jwt)) and issues a new DPoP-bound access token.

## Important considerations

When implementing DPoP in your client applications, consider the following:

* **Private key security:** The security of your DPoP implementation depends on the security of your client's private key, so you must protect it from unauthorized access. Private keys should be generated and stored in a hardware-backed medium and marked as non-exportable.
* **Replay protection (**`jti`\*\* and **`dpop-nonce`**):\*\* The `jti` claim in the DPoP Proof JWT helps prevent replay attacks for protected resources, such as the [`/userinfo`](https://auth0.com/docs/api/authentication/user-profile/get-user-info) endpoint. The Auth0 Authorization Server currently does not check `jti` reuse on the `/userinfo` endpoint. The Auth0 Authorization Server issues a `DPoP-Nonce` HTTP header in its response, which public clients must include as a `nonce` claim in subsequent DPoP Proof JWTs for enhanced replay protection.
* **Rate Limits:** Because the DPoP challenge-response flow can sometimes require an initial request followed by a retry with the server-provided nonce, each exchange effectively counts as two requests toward your [Auth0 tenant rate limits](https://auth0.com/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy). Ensure your application's request volume accounts for this overhead.
* **Error handling:** You are responsible for implementing logic to handle DPoP-specific errors from the Auth0 Authorization Server or resource server, such as `invalid_dpop_proof` or `use_dpop_nonce`.
* **Client types:** Use DPoP for public clients, such as Single Page Applications (SPAs) or mobile apps that cannot securely store a client secret. For <Tooltip href="/docs/glossary?term=confidential+clients">confidential clients</Tooltip>, such as backend services with client secrets, DPoP adds a layer of security, but they already have other sender-constraining mechanisms.
* **Performance:** Because generating and signing DPoP Proof JWTs for every API call adds a small overhead, ensure your client application’s cryptographic operations are efficient.
* **Key rotation:** Implement a strategy for rotating your DPoP key pairs for enhanced security. Make sure you use the same key pair for the same session.
* **Persistence:** For client applications that need to maintain a session and reuse DPoP-bound access tokens, such as long-lived SPAs, securely persist and retrieve the original generated key pair across application reloads. If a new key pair is generated or a different key pair is used, the DPoP-bound access token becomes invalid, as it is cryptographically tied to the public key of the original pair. You can persist the key pair, for example, in a browser's `IndexedDB` or a mobile app's secure storage.

## Learn more

* [Configure Sender Constraining](/docs/secure/sender-constraining/configure-sender-constraining)


# mTLS Sender Constraining
Source: https://auth0.com/docs/secure/sender-constraining/mtls-sender-constraining

Learn how to sender constrain tokens using mTLS in Auth0.

<Callout icon="file-lines">
  To use Highly Regulated Identity features, you must have an Enterprise Plan with the Highly Regulated Identity add-on. Refer to [Auth0 Pricing](https://auth0.com/pricing/) for details.
</Callout>

[Sender constraining](/docs/secure/sender-constraining) is an <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> security mechanism that cryptographically binds access and <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip> to the client application that requested them. This ensures that only the legitimate client that obtained the <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> can use it to access protected resources, providing a strong defense against token theft and replay attacks.

Mutual-TLS (mTLS) Client Certificate-Bound Access Tokens, or mTLS sender constraining, achieves this binding by leveraging the client's TLS certificate. With mTLS, the client's access token is bound to its unique client certificate, making the token unusable by any other party.

## Prerequisites

To implement mTLS sender constraining, you must:

* Have an Enterprise Plan with the Highly Regulated Identity add-on for your Auth0 tenant.
* [Configure sender constraining](/docs/secure/sender-constraining/configure-sender-constraining) for your client application and <Tooltip href="/docs/glossary?term=resource+server">resource server</Tooltip> within Auth0.
* Ensure your client application is a <Tooltip href="/docs/glossary?term=confidential+client">confidential client</Tooltip>, as only confidential clients support mTLS sender constraining.

## How it works

This section outlines the process of obtaining and using an mTLS-bound access token.

<Frame>
  <img alt="" />
</Frame>

## Phase 1: Request an mTLS-bound access token

### Step 1: Client application establishes mTLS connection

* Before requesting an access token, your client application initiates a TLS handshake with the Auth0 <Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip>'s `/token` endpoint.
* During this handshake, the client application presents its client certificate to the Auth0 Authorization Server as part of the mutual TLS authentication process.

### Step 2: Client application requests access token

* The client application sends a standard OAuth 2.0 token request, such as using `grant_type=client_credentials` or `authorization_code`, to the Auth0 Authorization Server's `/token` endpoint.
* The token request does not include any special DPoP headers or additional proof <Tooltip href="/docs/glossary?term=JWTs">JWTs</Tooltip> for mTLS. The proof of possession is derived directly from the mTLS connection.

### Step 3: Auth0 Authorization Server processes request and binds token

When the Auth0 Authorization Server receives the token request over an mTLS connection and the client certificate is successfully validated:

1. **Extracts certificate:** The Auth0 Authorization Server extracts the client certificate used in the mTLS handshake.
2. **Calculates thumbprint:** The Auth0 Authorization Server calculates a unique hash (thumbprint) of the client certificate.
3. **Binds token:** The Auth0 Authorization Server binds this client certificate's thumbprint to the issued access token by including a confirmation claim (`cnf`) in the access token's payload.

   * The `cnf` claim contains the `x5t#S256` parameter, which is the Base64url-encoded SHA-256 thumbprint of the client certificate.
4. **Sets** `token_type`**:** The Auth0 Authorization Server sets the `token_type` to DPoP. This differs from traditional Bearer tokens and signals that the token is bound to a specific key.
5. **Issues token:** The Auth0 Authorization Server issues the mTLS sender-constrained access token to your client application.

The following code sample is an example payload of an mTLS certificate-bound access token:

```json lines theme={null}
{
  "iss": "https://server.example.com",
  "sub": "ty.webb@example.com",
  "exp": 1493726400,
  "nbf": 1493722800,
  "cnf": {
    "x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2"
  }
}
```

In the mTLS certificate-bound access token example, `x5t#S256` indicates that the access token is bound to an mTLS client certificate with the SHA-256 thumbprint `bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2`.

## Phase 2: Call an API with an mTLS-bound access token

### Step 4: Client application calls API

* When your client application needs to call an API that enforces mTLS sender constraining, it must establish a new mTLS connection with the resource server.
* During this mTLS handshake, the client application presents the same client certificate that was used to obtain the access token again.
* The client application then includes the mTLS-bound access token in the Authorization header of the API request using the DPoP authentication scheme:

```http lines theme={null}
Authorization: DPoP {your_mtls_bound_access_token}
```

<Callout icon="file-lines">
  While RFC 8705 allows for a Bearer scheme with mTLS-bound tokens, Auth0 recommends using DPoP to enforce mTLS-bound access tokens. This explicitly signals to the resource server to expect a cryptographically bound token.
</Callout>

### Step 5: Resource server verifies token and certificate

When the resource server receives the API request over an mTLS connection:

1. **Requests client certificate:** The resource server retrieves the client certificate from the established mTLS connection.
2. **Extracts token and cnf claim:** The resource server extracts the access token from the `Authorization` header and decodes its payload to find the `cnf` (confirmation) claim, specifically the `x5t#S256` value (the bound certificate's thumbprint).
3. **Calculates current certificate thumbprint:** The resource server calculates the SHA-256 thumbprint of the client certificate received in the current mTLS connection.
4. **Compares thumbprints (Proof-of-Possession verification):** The resource server compares the newly calculated thumbprint with the `x5t#S256` thumbprint from the access token's `cnf` claim.
5. **Authorizes or rejects request:**

   * If the thumbprints match and other token validations, such as the expiration, audience, and issuer, pass, the request is authorized.
   * If the client certificate was not sent, or its thumbprint does not match the one in the `cnf` claim, the resource server rejects the request with an `HTTP 401 Unauthorized` status code and an `invalid_token` error code.

To understand how the thumbprint is calculated and the format of the `cnf` claim, refer to RFC 8705: Mutual-TLS Client Certificate-Bound Access Tokens.

## Important considerations

When implementing mTLS sender constraining, consider the following:

* **Confidential clients only:** mTLS sender constraining is designed for and supported only by confidential clients, such as backend services, that can securely manage client certificates and establish mTLS connections. <Tooltip href="/docs/glossary?term=Public+clients">Public clients</Tooltip> like SPAs and mobile apps should use DPoP.
* **Certificate management:** The security of your mTLS implementation relies heavily on your certificate management practices, such as how you provision, manage, and rotate client certificates.
* **Infrastructure requirements:** Implementing mTLS requires specific infrastructure, including proxies, load balancers, and APIs capable of terminating mTLS connections and passing client certificate information to the application or resource server.
* **Resource server enforcement:** When you enable mTLS sender constraining for an API in Auth0, the resource server must perform the thumbprint verification as described in [Step 5](#step-5-resource-server-verifies-token-and-certificate).
* **Migration strategies:** If you are progressively migrating clients to use mTLS, consider exposing your API at two domains: one non-mTLS domain for existing clients and one mTLS-enabled domain for mTLS-capable clients. Alternatively, you could implement logic on a single domain to differentiate between mTLS and non-mTLS requests.
* **Error handling:** Implement robust error handling on the client and resource server to gracefully manage cases where certificates are missing, invalid, or do not match.

## Learn more

* [Configure Sender Constraining](/docs/secure/sender-constraining/configure-sender-constraining)


# Tokens
Source: https://auth0.com/docs/secure/tokens

Describes the types of tokens related to identity and authentication and how they are used by Auth0.

There are two types of tokens that are related to identity: <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip> and <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip>.

## ID tokens

[ID tokens](/docs/secure/tokens/id-tokens) are [JSON web tokens (JWTs)](/docs/secure/tokens/json-web-tokens) meant for use by the application only. For example, if there's an app that uses Google to log in users and to sync their calendars, Google sends an ID token to the app that includes information about the user. The app then parses the [token's contents](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) and uses the information (including details like name and profile picture) to customize the user experience.

<Callout icon="file-lines">
  Be sure to [validate ID tokens](/docs/secure/tokens/id-tokens/validate-id-tokens) before using the information it contains. You can use a [library](https://jwt.io/#libraries-io) to help with this task.
</Callout>

Do **not** use ID tokens to gain access to an API. Each token contains information for the intended <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> (which is usually the recipient). According to the <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect specification, the audience of the ID token (indicated by the **aud** claim) must be the <Tooltip href="/docs/glossary?term=client+ID">client ID</Tooltip> of the application making the authentication request. If this is not the case, you should not trust the token.

The decoded contents of an ID token looks like the following:

<AuthCodeBlock />

This token authenticates the user to the application. The audience (the **aud** claim) of the token is set to the application's identifier, which means that only this specific application should consume this token.

Conversely, an API expects a token with the **aud** value to equal the API's unique identifier. Therefore, unless you maintain control over both the application and the API, sending an ID token to an API will generally not work. Since the ID token is not signed by the API, the API would have no way of knowing if the application had modified the token (e.g., adding more scopes) if it were to accept the ID Token. See the [JWT Handbook](https://auth0.com/resources/ebooks/jwt-handbook) for more information.

## Access tokens

[Access tokens](/docs/secure/tokens/access-tokens) (which aren't always <Tooltip href="/docs/glossary?term=JWTs">JWTs</Tooltip>) are used to inform an API that the bearer of the token has been authorized to access the API and perform a predetermined set of actions (specified by the **scopes** granted).

In the Google example above, Google sends an access token to the app after the user logs in and provides consent for the app to read or write to their Google Calendar. Whenever the app wants to write to Google Calendar, it sends a request to the Google Calendar API, including the access token in the HTTP **Authorization** header.

Access tokens must **never** be used for [authentication](/docs/authenticate). Access tokens cannot tell if the user has authenticated. The only user information the access token possesses is the user ID, located in the **sub** claim. In your applications, treat access tokens as opaque strings since they are meant for APIs. Your application should not attempt to decode them or expect to receive tokens in a particular format.

Here is an example of an access token:

<AuthCodeBlock />

Note that the token does not contain any information about the user besides their ID (**sub** claim). It only contains authorization information about which actions the application is allowed to perform at the API (**scope** claim). This is what makes it useful for securing an API, but not for authenticating a user.

In some situations, it may be desirable to put additional information about the user or other custom claims, besides their sub claim, in the access token to save the API from having to do extra work to fetch details about the user. If you choose to do this, bear in mind that these extra claims will be readable in the access token. To learn more, read [Create Custom Claims](/docs/secure/tokens/json-web-tokens/create-custom-claims).

## Specialized tokens

There are three specialized tokens used in Auth0's token-based authentication scenarios:

* **<Tooltip href="/docs/glossary?term=Refresh+tokens">Refresh tokens</Tooltip>**: A token used to obtain a renewed access token without having to re-authenticate the user.
* **<Tooltip href="/docs/glossary?term=IDP">IDP</Tooltip> access tokens**: Access tokens issued by identity providers after user authentication that you can use to call the third-party APIs.
* **Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> access tokens**: Short-lived tokens containing specific claims (scopes) that allow you to call Management API endpoints.

## Learn more

* [JSON Web Tokens](/docs/secure/tokens/json-web-tokens)
* [ID Tokens](/docs/secure/tokens/id-tokens)
* [Access Tokens](/docs/secure/tokens/access-tokens)
* [Refresh Tokens](/docs/secure/tokens/refresh-tokens)
* [Token Storage](/docs/secure/security-guidance/data-security/token-storage)
* [Token Best Practices](/docs/secure/tokens/token-best-practices)


# ID Tokens
Source: https://auth0.com/docs/secure/tokens/id-tokens

Describes how ID Tokens are used in token-based authentication to cache user profile information and provide it to a client application.

<Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip> are used in token-based authentication to cache user profile information and provide it to a client application, thereby providing better performance and experience. The application receives an ID token after a user successfully authenticates, then consumes the ID token and extracts user information from it, which it can then use to personalize the user's experience.

For example, suppose you have a regular web app that you [register it with Auth0](/docs/get-started/auth0-overview/create-applications/regular-web-apps) and configure to allow users to login with Google. Once a user logs in, use the ID token to gather information such as name and email address, which you can then use to auto-generate and send a personalized welcome email.

ID Tokens should never be used to obtain direct access to APIs or to make authorization decisions.

## ID token security

As with other [JWTs](/docs/secure/tokens/json-web-tokens), you should follow [token usage best practices](/docs/secure/tokens/token-best-practices) when using and storing ID tokens.

<Callout icon="file-lines">
  Be sure to [validate ID tokens](/docs/secure/tokens/id-tokens/validate-id-tokens) before using the information it contains. You can use a [library](https://jwt.io/#libraries-io) to help with this task.
</Callout>

Securing apps that make API calls come with their own set of concerns. You'll need to ensure that tokens and other sensitive data are not vulnerable to cross-site scripting (XSS) and can't be read by malicious JavaScript.

## ID token lifetime

By default, an ID token is valid for 36000 seconds (10 hours). If there are security concerns, you can shorten the time period before the token expires, keeping in mind that one of the purposes of the token is to improve user experience by caching user information. See [Update ID Token Lifetime](/docs/secure/tokens/id-tokens/update-id-token-lifetime) for details.

## Learn more

* [Validate ID Tokens](/docs/secure/tokens/id-tokens/validate-id-tokens)
* [Get ID Tokens](/docs/secure/tokens/id-tokens/get-id-tokens)
* [Revoke Tokens](/docs/secure/tokens/revoke-tokens)
* [ID Token Structure](/docs/secure/tokens/id-tokens/id-token-structure)
* [Token Best Practices](/docs/secure/tokens/token-best-practices)


# JSON Web Tokens
Source: https://auth0.com/docs/secure/tokens/json-web-tokens

Learn about JSON web tokens (JWTs) and how they are used.

<Tooltip href="/docs/glossary?term=JSON+web+token">JSON web token</Tooltip> (JWT), pronounced "jot", is an open standard ([RFC 7519](https://tools.ietf.org/html/rfc7519)) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. Again, JWT is a standard, meaning that all JWTs are tokens, but not all tokens are JWTs.

Because of its relatively small size, a JWT can be sent through a URL, through a POST parameter, or inside an HTTP header, and it is transmitted quickly. A JWT contains all the required information about an entity to avoid querying a database more than once. The recipient of a JWT also does not need to call a server to validate the token.

## Benefits

* **Compact**: JWTs are small in size, which makes them a good choice to be passed in HTML and HTTP environments.

<Frame>
  <img alt="Encoded JWT Compared to SAML Token" />
</Frame>

* **Secure**: JWTs can use a public/private key pair in the form of an X.509 certificate for signing. A JWT can also be symmetrically signed by a shared secret using the HMAC algorithm. To learn more, read [Signing Algorithms](/docs/get-started/applications/signing-algorithms).
* **Common**: JSON parsers are supported by most programming languages.

## Usage

* **Authentication**: When a user successfully logs in using their credentials, an [ID token](/docs/secure/tokens/id-tokens) is returned. According to the [OpenID Connect (OIDC) specification](https://openid.net/specs/openid-connect-core-1_0.html#IDToken), an <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> is always a JWT.
* **Authorization**: Once a user is successfully logged in, an application may request to access routes, services, or resources (for example, APIs) on behalf of that user. To do so, the application must pass an <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> in every request, which may be in the form of a JWT.
* **Information exchange**: JWTs are a good way of securely transmitting information between parties because they can be signed, which means you can be certain that the senders are who they say they are. Additionally, the structure of a JWT allows you to verify that the content hasn't been tampered with.

## Security

The information contained within the JSON object can be verified and trusted because it is digitally signed. Although JWTs can also be encrypted to provide secrecy between parties, Auth0-issued JWTs are JSON Web Signatures (JWS), meaning they are signed rather than encrypted. As such, we will focus on signed tokens, which can verify the integrity of the claims contained within them, while encrypted tokens hide those claims from other parties.

In general, JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA (although Auth0 supports only HMAC and RSA). When tokens are signed using public/private key pairs, the signature also certifies that only the party holding the private key is the one that signed it.

Before a received JWT is used, it should be [properly validated using its signature](/docs/secure/tokens/json-web-tokens/validate-json-web-tokens). Note that a successfully validated token only means that the information contained within the token has not been modified by anyone else. This doesn't mean that others weren't able to see the content, which is stored in plain text. Because of this, you should never store sensitive information inside a JWT and should take other steps to ensure that JWTs are not intercepted, such as by sending JWTs only over HTTPS, following [best practices](/docs/secure/tokens/token-best-practices), and using only secure and up-to-date libraries.

## Learn more

* [JSON Web Token Structure](/docs/secure/tokens/json-web-tokens/json-web-token-structure)
* [JSON Web Token Claims](/docs/secure/tokens/json-web-tokens/json-web-token-claims)
* [Validate JSON Web Tokens](/docs/secure/tokens/json-web-tokens/validate-json-web-tokens)
* [Signing Keys](/docs/get-started/tenant-settings/signing-keys)
* [JSON Web Key Sets](/docs/secure/tokens/json-web-tokens/json-web-key-sets)
* [Get Access Tokens](/docs/secure/tokens/access-tokens/get-access-tokens)


# Create Custom Claims
Source: https://auth0.com/docs/secure/tokens/json-web-tokens/create-custom-claims

Learn how to create collision-resistant names for custom claims.

To read custom claims on access and <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip>, you must use <Tooltip href="/docs/glossary?term=JSON+Web+Tokens">JSON Web Tokens</Tooltip> (JWT) and pass an <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> (`aud`) in an OIDC login flow. To learn more, read [Access Tokens](/docs/secure/tokens/access-tokens).

When configuring custom claims on JWTs, you want to avoid collisions. To keep your custom claims from colliding with any reserved claims or claims from other resources, give them a collision-resistant name. Auth0 recommends using a namespaced format.

<Callout icon="file-lines">
  Auth0 allows namespaced and non-namespaced claims, but certain restrictions apply (see [General restrictions](/docs/secure/tokens/json-web-tokens/create-custom-claims#general-restrictions)). To avoid name collisions, we recommend using namespaced claims. In case of collisions, the transaction won't fail, but your custom claim won't be added to your tokens.
</Callout>

## General restrictions

Auth0 applies the following restrictions to custom claims:

* Custom claims payload is set to a maximum of 100KB
* [OPENID standard claims](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) and claims used internally by Auth0 cannot be customized or modified
* <Tooltip href="/docs/glossary?term=Access+tokens">Access tokens</Tooltip> with an Auth0 API audience, excluding the `/userinfo` endpoint, cannot have private, non-namespaced custom claims
* Only specified OIDC user profile claims can be added to access tokens

The following claims are subject to Auth0's restrictions:

* `acr`
* `act`
* `active`
* `amr`
* `at_hash`
* `ath`
* `attest`
* `aud`
* `auth_time`
* `authorization_details`
* `azp`
* `c_hash`
* `client_id`
* `cnf`
* `cty`
* `dest`
* `entitlements`
* `events`
* `exp`
* `groups`
* `gty`
* `htm`
* `htu`
* `iat`
* `internalService`
* `iss`
* `jcard`
* `jku`
* `jti`
* `jwe`
* `jwk`
* `kid`
* `may_act`
* `mky`
* `nbf`
* `nonce`
* `object_id`
* `org_id`
* `org_name`
* `orig`
* `origid`
* `permissions`
* `roles`
* `rph`
* `s_hash`
* `sid`
* `sip_callid`
* `sip_cseq_num`
* `sip_date`
* `sip_from_tag`
* `sip_via_branch`
* `sub`
* `sub_jwk`
* `toe`
* `txn`
* `typ`
* `uuid`
* `vot`
* `vtm`
* `x5t#S256`

### Non-restricted claims

You can create claims for sensitive user information to enhance the user profile and add to the user experience. These claims are consumed by your application from ID tokens. To learn more about using non-restricted claims, read [ID Tokens](/docs/secure/tokens/id-tokens), and keep in mind [Token Best Practices](/docs/secure/tokens/token-best-practices) if you use them.

The following claims are only subject to general restrictions:

* `address`
* `birthdate`
* `email`
* `email_verified`
* `family_name`
* `gender`
* `given_name`
* `locale`
* `middle_name`
* `name`
* `nickname`
* `phone_number`
* `phone_number_verified`
* `picture`
* `preferred_username`
* `profile`
* `updated_at`
* `website`
* `zoneinfo`

## Namespaced guidelines

<Callout icon="file-lines">
  The Auth0 URN `urn:auth0` cannot be used as a namespace identifier.
</Callout>

Use the following guidelines for namespace identifiers:

* Use any non-Auth0 HTTP or HTTPS URL as a namespace identifier. Auth0 domains cannot be used as namespace identifiers, and include:

  * auth0.com
  * webtask.io
  * webtask.run
* Use a URL that you control as a namespace identifier; this allows you to avoid the risk that someone else is using the same namespace. The namespace URL does not have to point to an actual resource. It is only used as an identifier; it will not be called.
* Begin the URL with `http://` or `https://`.
* Alternatively, you can also use URN-based namespace identifiers if you use a custom API. In that case, the Auth0 URN `urn:auth0` is reserved and cannot be used as a namespace identifier.
* Create multiple namespaces, as needed.

Once you have chosen your namespace, append the claim to it to create a namespaced claim, which can be added to a token. For example:

`http://www.example.com/favorite_color`

## Non-namespaced guidelines

Use the following guidelines for non-namespaced custom claims:

* Unless absolutely necessary for your application, use public, namespaced custom claims that are collision resistant.
* Create claims with meaningful and collision resistant names. For example, use `employee_id` instead of `e_id`.
* Keep the claim names and values as light as possible, passing only the data strictly necessary for your application.
* Avoid assigning heavy payloads to custom claims.

For more examples of custom claims added to a token, see [Sample Use Cases: Scopes and Claims](/docs/get-started/apis/scopes/sample-use-cases-scopes-and-claims).

## Create custom claims

Use Auth0 Actions to create custom claims. The `api` object allows you to use the method `setCustomClaim` on access tokens or ID tokens.

### Example

```js lines theme={null}
exports.onExecuteCredentialsExchange = async (event, api) => {
  api.accessToken.setCustomClaim('myClaim', 'this is a private, non namespaced claim');
};
```

## Learn more

* [JSON Web Token Claims](/docs/secure/tokens/json-web-tokens/json-web-token-claims)
* [OpenID Connect Scopes](/docs/get-started/apis/scopes/openid-connect-scopes)


# JSON Web Key Set Properties
Source: https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-key-set-properties

Describes the properties available in a JSON Web Key Set (JWKS).

Here is an example of the JSON Web Key Set (JWKS) used by a sample tenant, containing a single JSON Web Key (JWK):

```json lines theme={null}
{
"keys": [
  {
    "alg": "RS256",
    "kty": "RSA",
    "use": "sig",
    "x5c": [
      "MIIC+DCCAeCgAwIBAgIJBIGjYW6hFpn2MA0GCSqGSIb3DQEBBQUAMCMxITAfBgNVBAMTGGN1c3RvbWVyLWRlbW9zLmF1dGgwLmNvbTAeFw0xNjExMjIyMjIyMDVaFw0zMDA4MDEyMjIyMDVaMCMxITAfBgNVBAMTGGN1c3RvbWVyLWRlbW9zLmF1dGgwLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMnjZc5bm/eGIHq09N9HKHahM7Y31P0ul+A2wwP4lSpIwFrWHzxw88/7Dwk9QMc+orGXX95R6av4GF+Es/nG3uK45ooMVMa/hYCh0Mtx3gnSuoTavQEkLzCvSwTqVwzZ+5noukWVqJuMKNwjL77GNcPLY7Xy2/skMCT5bR8UoWaufooQvYq6SyPcRAU4BtdquZRiBT4U5f+4pwNTxSvey7ki50yc1tG49Per/0zA4O6Tlpv8x7Red6m1bCNHt7+Z5nSl3RX/QYyAEUX1a28VcYmR41Osy+o2OUCXYdUAphDaHo4/8rbKTJhlu8jEcc1KoMXAKjgaVZtG/v5ltx6AXY0CAwEAAaMvMC0wDAYDVR0TBAUwAwEB/zAdBgNVHQ4EFgQUQxFG602h1cG+pnyvJoy9pGJJoCswDQYJKoZIhvcNAQEFBQADggEBAGvtCbzGNBUJPLICth3mLsX0Z4z8T8iu4tyoiuAshP/Ry/ZBnFnXmhD8vwgMZ2lTgUWwlrvlgN+fAtYKnwFO2G3BOCFw96Nm8So9sjTda9CCZ3dhoH57F/hVMBB0K6xhklAc0b5ZxUpCIN92v/w+xZoz1XQBHe8ZbRHaP1HpRM4M7DJk2G5cgUCyu3UBvYS41sHvzrxQ3z7vIePRA4WF4bEkfX12gvny0RsPkrbVMXX1Rj9t6V7QXrbPYBAO+43JvDGYawxYVvLhz+BJ45x50GFQmHszfY3BR9TPK8xmMmQwtIvLu1PMttNCs7niCYkSiUv2sc2mlq1i3IashGkkgmo="
    ],
    "n": "yeNlzlub94YgerT030codqEztjfU_S6X4DbDA_iVKkjAWtYfPHDzz_sPCT1Axz6isZdf3lHpq_gYX4Sz-cbe4rjmigxUxr-FgKHQy3HeCdK6hNq9ASQvMK9LBOpXDNn7mei6RZWom4wo3CMvvsY1w8tjtfLb-yQwJPltHxShZq5-ihC9irpLI9xEBTgG12q5lGIFPhTl_7inA1PFK97LuSLnTJzW0bj096v_TMDg7pOWm_zHtF53qbVsI0e3v5nmdKXdFf9BjIARRfVrbxVxiZHjU6zL6jY5QJdh1QCmENoejj_ytspMmGW7yMRxzUqgxcAqOBpVm0b-_mW3HoBdjQ",
    "e": "AQAB",
    "kid": "NjVBRjY5MDlCMUIwNzU4RTA2QzZFMDQ4QzQ2MDAyQjVDNjk1RTM2Qg",
    "x5t": "NjVBRjY5MDlCMUIwNzU4RTA2QzZFMDQ4QzQ2MDAyQjVDNjk1RTM2Qg"
  }
]}
```

Each property in the key is defined by the JWK specification [RFC 7517 Section 4](https://tools.ietf.org/html/rfc7517#section-4) or, for algorithm-specific properties, in [RFC 7518](https://tools.ietf.org/html/rfc7518).

<table>
  <thead>
    <tr>
      <th>Property name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>alg</code></td>
      <td>The specific cryptographic algorithm used with the key. This is an optional parameter. By default, Auth0 includes the signing algorithm defined at the tenant level in the JSON Web Key Set (JWKS), which is then published. To allow for keys to be used with multiple algorithms rather than a single algorithm i.e. RS256, toggle off <strong>Include Signing Algorithms in JSON Web Key Set</strong> under Advanced Tenant settings in Dashboard. This removes the <code>alg</code> parameter and requires consumers of the JWKS to interpret the signing algorithms as needed.</td>
    </tr>

    <tr>
      <td><code>kty</code></td>
      <td>The family of cryptographic algorithms used with the key.</td>
    </tr>

    <tr>
      <td><code>use</code></td>
      <td>How the key was meant to be used; <code>sig</code> represents the signature.</td>
    </tr>

    <tr>
      <td><code>x5c</code></td>
      <td>The x.509 certificate chain. The first entry in the array is the certificate to use for token verification; the other certificates can be used to verify this first certificate.</td>
    </tr>

    <tr>
      <td><code>n</code></td>
      <td>The modulus for the <a href="https://tools.ietf.org/html/rfc7518#page-30">RSA public key</a>.</td>
    </tr>

    <tr>
      <td><code>e</code></td>
      <td>The exponent for the <a href="https://tools.ietf.org/html/rfc7518#page-30">RSA public key</a>.</td>
    </tr>

    <tr>
      <td><code>kid</code></td>
      <td>The unique identifier for the key.</td>
    </tr>

    <tr>
      <td><code>x5t</code></td>
      <td>The thumbprint of the x.509 cert (SHA-1 thumbprint).</td>
    </tr>
  </tbody>
</table>

<Callout icon="file-lines">
  Auth0 only supports HMAC and RSA; it does not currently support Elliptic Curve encryption (ECDSA).
</Callout>

For an example that uses JWKS to verify a <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip>'s signature, see [Navigating RS256 and JWKS](https://auth0.com/blog/navigating-rs256-and-jwks/) (uses Node.js), or check out our [Backend/API Quickstarts](/docs/quickstart/backend).

## Learn more

* [JSON Web Key Sets](/docs/secure/tokens/json-web-tokens/json-web-key-sets)
* [Locate JSON Web Key Sets](/docs/secure/tokens/json-web-tokens/locate-json-web-key-sets)
* [JSON Web Token Structure](/docs/secure/tokens/json-web-tokens/json-web-token-structure)


# JSON Web Key Sets
Source: https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-key-sets

A JSON Web Key set is a JSON object which represents a set of JSON Web Keys (a JSON object that represents a cryptographic key).

The JSON Web Key Set (JWKS) is a set of keys containing the public keys used to verify any <Tooltip href="/docs/glossary?term=JSON+Web+Token+%28JWT%29">JSON Web Token (JWT)</Tooltip> issued by the <Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip> and signed using the RS256 [signing algorithm](/docs/get-started/applications/signing-algorithms).

When creating applications and APIs in Auth0, two algorithms are supported for signing <Tooltip href="/docs/glossary?term=JWTs">JWTs</Tooltip>: **RS256** and **HS256**. RS256 generates an asymmetric signature, which means a private key must be used to sign the JWT and a different public key must be used to verify the signature.

Auth0 uses the [JSON Web Key (JWK) specification](https://tools.ietf.org/html/rfc7517) to represent the cryptographic keys used for signing RS256 tokens. This specification defines two high-level data structures: **JSON Web Key (JWK)** and **JSON Web Key Set (JWKS)**. Here are the definitions from the specification:

<table>
  <thead>
    <tr>
      <th>Item</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>JSON Web Key (JWK)</strong></td>
      <td>A JSON object that represents a cryptographic key. The members of the object represent properties of the key, including its value.</td>
    </tr>

    <tr>
      <td><strong>JSON Web Key Set (JWKS)</strong></td>
      <td>A JSON object that represents a set of JWKs. The JSON object MUST have a <code>keys</code> member, which is an array of JWKs.</td>
    </tr>
  </tbody>
</table>

Auth0 exposes a JWKS endpoint for each tenant, which is found at `https://{yourDomain}/.well-known/jwks.json`. This endpoint will contain the JWK used to verify all Auth0-issued JWTs for this tenant.

<Warning>
  Currently, Auth0 signs with only one JWK at a time; however, it is important to assume this endpoint could contain multiple JWKs. As an example, multiple keys can be found in the JWKS when [rotating application signing keys](/docs/get-started/tenant-settings/signing-keys/rotate-signing-keys).
</Warning>

## Learn more

* [Signing Keys](/docs/get-started/tenant-settings/signing-keys)
* [JSON Web Key Set Properties](/docs/secure/tokens/json-web-tokens/json-web-key-set-properties)
* [Locate JSON Web Key Sets](/docs/secure/tokens/json-web-tokens/locate-json-web-key-sets)
* [View Signing Certificates](/docs/get-started/tenant-settings/signing-keys/view-signing-certificates)


# JSON Web Token Claims
Source: https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-token-claims

Describe JSON web token (JWT) claims and how they are used in Auth0.

[JSON web tokens (JWTs)](/docs/secure/tokens/json-web-tokens) claims are pieces of information asserted about a subject. For example, an [ID token](/docs/secure/tokens/id-tokens) (which is always a <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip>) can contain a claim called `name` that asserts that the name of the user authenticating is "John Doe". In a JWT, a claim appears as a name/value pair where the name is always a string and the value can be any JSON value. Generally, when we talk about a claim in the context of a JWT, we are referring to the name (or key). For example, the following JSON object contains three claims (`sub`, `name`, `admin`):

```json lines theme={null}
{
      "sub": "1234567890",
      "name": "John Doe",
      "admin": true
    }
```

<Callout icon="file-lines">
  To learn about OpenID Connect (OIDC) standard claims, see [OpenID Connect Scopes](/docs/get-started/apis/scopes/openid-connect-scopes) and [OpenID Connect Standard Claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims).
</Callout>

There are two types of JWT claims:

* **Registered**: standard claims registered with the [Internet Assigned Numbers Authority (IANA)](https://www.iana.org/assignments/jwt/jwt.xhtml) and defined by the [JWT specification](https://tools.ietf.org/html/rfc7519) to ensure interoperability with third-party, or external, applications. OIDC standard claims are reserved claims.
* **Custom**:  consists of non-registered public or private claims. Public claims are collision-resistant while private claims are subject to possible collisions.

## Registered claims

The JWT specification defines seven reserved claims that are not required, but are recommended to allow interoperability with [third-party applications](/docs/get-started/applications/confidential-and-public-applications/enable-third-party-applications). These are:

* `iss` (issuer): Issuer of the JWT
* `sub` (subject): Subject of the JWT (the user)
* `aud` (<Tooltip href="/docs/glossary?term=audience">audience</Tooltip>): Recipient for which the JWT is intended
* `exp` (expiration time): Time after which the JWT expires
* `nbf` (not before time): Time before which the JWT must not be accepted for processing
* `iat` (issued at time): Time at which the JWT was issued; can be used to determine age of the JWT
* `jti` (JWT ID): Unique identifier; can be used to prevent the JWT from being replayed (allows a token to be used only once)

You can see a full list of registered claims at the [IANA JSON Web Token Claims Registry](https://www.iana.org/assignments/jwt/jwt.xhtml#claims).

## Custom claims

You can define your own custom claims which you control and you can add them to a token using Actions. Here are some examples:

* Add a user's email address to an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> and use that to uniquely identify the user.
* Add custom information stored in an Auth0 user profile to an <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip>.

As long as the Action is in place, the custom claims it adds will appear in new tokens issued when using a [refresh token](/docs/secure/tokens/refresh-tokens).

For an example showing how to add custom claims to a token, see [Sample Use Cases: Scopes and Claims](/docs/get-started/apis/scopes/sample-use-cases-scopes-and-claims).

### Public claims

You can create custom claims for public consumption, which might contain generic information like name and email. If you create public claims, you must either register them or use collision-resistant names through namespacing and take reasonable precautions to make sure you are in control of the namespace you use.

In the [IANA JSON Web Token Claims Registry](https://www.iana.org/assignments/jwt/jwt.xhtml#claims), you can see some examples of public claims registered by <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC):

* `auth_time`
* `acr`
* `nonce`

### Private claims

You can create private custom claims to share information specific to your application. For example, while a public claim might contain generic information like name and email, private claims would be more specific, such as employee ID and department name.

## Auth0 restrictions

Auth0 enforces the general restrictions on custom claims:

* custom claims payload is set to a maximum of 100KB
* a subset of OIDC and other registered standard claims or claims used internally by Auth0 cannot be customized or modified
* access tokens with an Auth0 API audience, excluding the `/userinfo` endpoint, cannot have private, non-namespaced custom claims
* only specified OIDC user profile claims can be added to access tokens

To learn more about custom claims, read [Create Custom Claims](/docs/secure/tokens/json-web-tokens/create-custom-claims).

## Learn more

* [Validate JSON Web Tokens](/docs/secure/tokens/json-web-tokens/validate-json-web-tokens)
* [JSON Web Token Structure](/docs/secure/tokens/json-web-tokens/json-web-token-structure)
* [JSON Web Key Sets](/docs/secure/tokens/json-web-tokens/json-web-key-sets)
* [JSON Web Key Set Properties](/docs/secure/tokens/json-web-tokens/json-web-key-set-properties)


# JSON Web Token Structure
Source: https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-token-structure

Describes how the JSON web tokens with JSON web signatures (JWSs) are structured.

All Auth0-issued <Tooltip href="/docs/glossary?term=JWTs">JWTs</Tooltip> have [JSON Web Signatures (JWSs)](https://tools.ietf.org/html/rfc7515), meaning they are signed rather than encrypted. A JWS represents content secured with <Tooltip href="/docs/glossary?term=digital+signatures">digital signatures</Tooltip> or Message Authentication Codes (MACs) using JSON-based data structures.

A well-formed JWT consists of three concatenated Base64url-encoded strings, separated by dots (`.`):

* **JOSE Header**: contains metadata about the type of token and the cryptographic algorithms used to secure its contents.
* **JWS payload** (set of [claims](https://tools.ietf.org/html/rfc7519#section-4)): contains verifiable security statements, such as the identity of the user and the permissions they are allowed.
* **JWS signature**: used to validate that the token is trustworthy and has not been tampered with. When you use a JWT, you **must** [check its signature](/docs/secure/tokens/json-web-tokens/validate-json-web-tokens) before storing and using it.

A JWT typically looks like this:

<Frame>
  <img alt="JSON Web Token" />
</Frame>

To see for yourself what is inside a JWT, use the [JWT.io Debugger](http://jwt.io). It allows you to quickly check that a JWT is well formed and to manually inspect the values of the various claims.

<Frame>
  <img alt="JWT Debugger" />
</Frame>

## JOSE header

JSON object containing the parameters describing the cryptographic operations and parameters employed. The JOSE (JSON Object Signing and Encryption) Header is comprised of a set of Header Parameters that typically consist of a name/value pair: the hashing algorithm being used (e.g., HMAC SHA256 or RSA) and the type of the JWT.

```json lines theme={null}
{
      "alg": "HS256",
      "typ": "JWT"
    }
```

## JWS payload

The payload contains statements about the entity (typically, the user) and additional entity attributes, which are called claims. In this example, our entity is a user.

```json lines theme={null}
{
      "sub": "1234567890",
      "name": "John Doe",
      "admin": true
    }
```

When working with JWT claims, you should be aware of the different claim types and naming rules.

## JWS signature

The signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn't changed along the way.

To create the signature, the Base64-encoded header and payload are taken, along with a secret, and signed with the algorithm specified in the header.

For example, if you are creating a signature for a token using the HMAC SHA256 algorithm, you would do the following:

```js lines theme={null}
HMACSHA256(
      base64UrlEncode(header) + "." +
      base64UrlEncode(payload),
      secret)
```

## Learn more

* [JSON Web Token Claims](/docs/secure/tokens/json-web-tokens/json-web-token-claims)
* [Validate JSON Web Tokens](/docs/secure/tokens/json-web-tokens/validate-json-web-tokens)
* [JSON Web Key Sets](/docs/secure/tokens/json-web-tokens/json-web-key-sets)
* [JSON Web Key Set Properties](/docs/secure/tokens/json-web-tokens/json-web-key-set-properties)
* [Locate JSON Web Key Sets](/docs/secure/tokens/json-web-tokens/locate-json-web-key-sets)
* [Get Access Tokens](/docs/secure/tokens/access-tokens/get-access-tokens)


# Locate JSON Web Key Sets
Source: https://auth0.com/docs/secure/tokens/json-web-tokens/locate-json-web-key-sets

Describes how to use the JSON Web Keys (JWKs) discovered using the JSON Web Key Set (JWKS) endpoint to verify a JWT signature.

Use this Discovery endpoint to configure your application or API to automatically locate the [JSON Web Key Set (JWKS)](/docs/secure/tokens/json-web-tokens/json-web-key-sets) endpoint (`jwks_uri`), which contains the JWKS used to sign all Auth0-issued <Tooltip href="/docs/glossary?term=JSON+Web+Tokens">JSON Web Tokens</Tooltip> (JWTs) signed with the RS256 <Tooltip href="/docs/glossary?term=signing+algorithm">signing algorithm</Tooltip>. The endpoint exists at:

`https://{yourDomain}/.well-known/openid-configuration`.

When [validating a JWT](/docs/secure/tokens/json-web-tokens/validate-json-web-tokens) using a JWKS, you will need to:

1. Retrieve the JWKS from the Auth0 Discovery endpoint, and filter for potential signing keys (e.g., any keys missing a public key or with a `kid` property).
2. Grab the `kid` property from the Header of the decoded JWT.
3. Search your filtered JWKS for the key with the matching `kid` property.
4. Build a certificate using the corresponding `x5c` property in your JWKS.
5. Use the certificate to verify the JWT's signature.

For an example that uses JWKS to verify a JWT's signature, see [Navigating RS256 and JWKS](https://auth0.com/blog/navigating-rs256-and-jwks/) (uses Node.js), or check out our [Backend/API Quickstarts](/docs/quickstart/backend).

For more info about the structure of a JWT, see [JSON Web Token Structure](/docs/secure/tokens/json-web-tokens/json-web-token-structure).

It's good practice to assume that multiple signing keys could be present in your JWKS. This may seem unnecessary since the Auth0 JWKS endpoint typically contains a single signing key; however, multiple keys can be found in the JWKS when rotating signing certificates.

We recommend that you cache your signing keys to improve application performance and avoid running into [rate limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy), but you will want to make sure that if decoding a token fails, you invalidate the cache and retrieve new signing keys before trying **only one** more time.

## Learn more

* [JSON Web Key Sets](/docs/secure/tokens/json-web-tokens/json-web-key-sets)
* [JSON Web Key Set Properties](/docs/secure/tokens/json-web-tokens/json-web-key-set-properties)
* [JSON Web Token Claims](/docs/secure/tokens/json-web-tokens/json-web-token-claims)
* [JSON Web Token Structure](/docs/secure/tokens/json-web-tokens/json-web-token-structure)
* [Validate JSON Web Tokens](/docs/secure/tokens/json-web-tokens/validate-json-web-tokens)
* [Token Best Practices](/docs/secure/tokens/token-best-practices)


# Validate JSON Web Tokens
Source: https://auth0.com/docs/secure/tokens/json-web-tokens/validate-json-web-tokens

Describes how to parse and validate a JSON web token (JWT).

<Card title="Overview">
  Key Concepts

  * Read about JSON Web Tokens (JWTs) Auth0 uses for access, ID, refresh, and logout tokens.
  * Review signing algorithms to understand what a signature is on a token.
  * Validate JWTs to make sure no one has tampered with them.
  * Use Auth0 SDKs, middleware, or one of the third-party libraries at [JWT.io](https://jwt.io/?_gl=1*arqbp6*rollup_ga*MTI5MzkwNDYxOC4xNjQ0MjUyMTYx*rollup_ga_F1G3E656YZ*MTY1MDA0NDA3Ni4xMjkuMS4xNjUwMDQ0MDg1LjUx&_ga=2.167965921.1971874740.1649687281-1293904618.1644252161#libraries-io) to validate JWTs.
</Card>

Auth0 uses <Tooltip href="/docs/glossary?term=JSON+Web+Token+%28JWT%29">JSON Web Token (JWT)</Tooltip> for secure data transmission, authentication, and authorization. Tokens should be parsed and validated in regular web, native, and single-page applications to make sure the token isn’t compromised and the signature is authentic. Tokens should be verified to decrease security risks if the token has been, for example, tampered with, misused, or has expired. <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> validation checks the structure, claims, and signature to assure the least amount of risk.



<Callout icon="file-lines">
  To visually inspect a JWT, visit [JWT.io](https://jwt.io/) or use the [JWT Debugger Chrome Extension](https://chrome.google.com/webstore/detail/jwt-debugger/ppmmlchacdbknfphdeafcbmklcghghmd?hl=en)).
</Callout>

The JWT token signature is generated using a <Tooltip href="/docs/glossary?term=Signing+Algorithm">Signing Algorithm</Tooltip>. While tokens can use multiple <Tooltip href="/docs/glossary?term=signing+algorithms">signing algorithms</Tooltip>, Auth0 supports RS256, RSA encryption with SHA-256 hash function or HS256, HMAC message authentication code (MAC) with SHA-256. To learn more about Auth0’s recommended algorithm, read [Signing Algorithms](/docs/get-started/applications/signing-algorithms).

When validating a JWT, generally, the current hash value and the original hash value are parsed, or decoded, then compared to verify the token signature is authentic. All of our [backend API quickstarts](/docs/quickstart/backend) use SDKs that perform JWT validation and parsing for you.

## Parse and validate

If you are not using one of our SDKs that perform JWT validation and parsing for you, you can parse and validate a JWT by:

* Using any existing middleware for your web framework.
* Choosing a third-party library from JWT.io.
* Manually implementing the checks described in [specification RFC 7519 > 7.2 Validating a JWT](https://tools.ietf.org/html/rfc7519#section-7.2).

We strongly recommend that you use middleware or one of the existing open source third-party libraries to parse and validate JWTs. At [JWT.io](https://jwt.io/#libraries-io), you can find libraries for various platforms and languages, such as .NET, Python, Java, Ruby, Objective-C, Swift, and PHP.

## Middleware

Many web frameworks, such as [ASP.NET Core](/docs/quickstart/backend/aspnet-core-webapi), include JWT middleware that handles JWT validation. Typically, this is the best route to take because the middleware integrates well with the framework's overall authentication mechanisms.

## Third-party libraries

If you choose a third-party library, choose a library that supports the signing algorithm you selected when you registered your application or API with Auth0. Also, be aware that not all libraries validate all JWT claims. At JWT.io, you can see which validations each library supports (look for the green check marks).

Most third-party libraries implement one method to verify a JWT and build in various arguments to allow you to customize the verification. For example, if you are using Node.js and the [node-jsonwebtoken library](https://github.com/auth0/node-jsonwebtoken), then you would call the [jwt.verify()](https://github.com/auth0/node-jsonwebtoken#jwtverifytoken-secretorpublickey-options-callback) method. This method supports an `algorithms` argument to allow you to customize your allowed algorithms (make sure you disallow `none`), a `secretOrPublicKey` argument that you populate with either the secret or the RSA public key (depending on selected signing algorithm), and other input arguments that allow you to customize claim validation. If parsing fails, then the library returns a [JsonWebTokenError error](https://github.com/auth0/node-jsonwebtoken#jsonwebtokenerror) with the message `jwt malformed`, after which you **must** reject the associated request.

General recommendations for using third-party libraries:

* For obtaining claims from JWT, use the `verify()` method to validate the claims and the signature. Avoid using the `decode()` method to validate a token, especially if it's coming from a <Tooltip href="/docs/glossary?term=public+client">public client</Tooltip>.
* Carefully follow all instructions on how to use the chosen library. The library could rely on default values or settings that could create security risks.

## Manually implement checks

We discourage doing manual JWT validation since it might be easy to improperly implement and miss some important details that will lead to serious security vulnerabilities. Most JWT libraries take care of JWT validation for you. Visit JWT.io to find a JWT library for your platform and programming language.

For instructions on how to manually validate a JWT, see [RFC 7519](https://tools.ietf.org/html/rfc7519#section-7.2). All Auth0-issued JWTs have a JSON Web Signature (JWS), meaning they are signed rather than encrypted.

## Verify RS256-signed tokens

To visually verify RS256-signed tokens:

1. Go to [Dashboard > Applications](https://manage.auth0.com/#/applications).
2. Go to the **Settings** view, and open **Advanced Settings**.
3. Go to the **Certificates** view, locate the **Signed Certificate** field, and copy the **Public Key**.
4. Navigate to the [JWT.io](https://jwt.io/) website, locate the **Algorithm** dropdown, and select **RS256**.
5. Locate the **Verify Signature** section, and paste the Public Key you previously copied in place of the content in the field that begins with `-----BEGIN PUBLIC KEY-----`.

To verify the signature of a token from one of your applications:

We recommend that you get the Public Key from your tenant's JWKS here:
`https://{yourDomain}/.well-known/jwks.json`

## Learn more

* [JSON Web Token Claims](/docs/secure/tokens/json-web-tokens/json-web-token-claims)
* [Validate ID Tokens](/docs/secure/tokens/id-tokens/validate-id-tokens)
* [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens)
* [Token Best Practices](/docs/secure/tokens/token-best-practices)


# Deploy and Monitor
Source: https://auth0.com/docs/deploy-monitor

Learn about Auth0 public and private cloud deployment options, as well as deployment checklists and tools.

<AuthDocsPipeline />

You can deploy Auth0 to the public cloud, a private cloud on AWS, or a private cloud on Azure. Deployment tools and checklists smooth the process. Monitoring tools and event logs let you track system health and events.

***

## Deployment

##### Plan, check, and execute your Auth0 deployment.

<Card title="Deployment Options" href="/docs/deploy-monitor/deployment-options">
  Evaluate whether to deploy to the public cloud or to a private cloud.
</Card>

<Card title="Private Cloud Deployments" href="/docs/deploy-monitor/deploy-private-cloud">
  Explore the capabilities and limitations of different AWS and Azure private cloud options.
</Card>

<Card title="Pre-Deployment Checks" href="/docs/deploy-monitor/pre-deployment-checks">
  Run checks to ensure that your applications are ready for production.
</Card>

<Card title="Deployment Checklist" href="/docs/deploy-monitor/deploy-checklist">
  Explore the Auth0-provided general deployment checklist for Auth0 implementations.
</Card>

<Card title="Deploy CLI Tool" href="/docs/deploy-monitor/deploy-cli-tool">
  Learn how Auth0 supports continuous integration and deployment using the Deploy CLI tool.
</Card>

<Card title="Deployment Best Practices" href="/docs/deploy-monitor/deployment-best-practices">
  Explore best practices for deploying Auth0 implementations.
</Card>

***

## Monitoring

##### Monitor events and service status and work with tenant log event data.

<Card title="Monitor" href="/docs/deploy-monitor/monitor">
  Monitor your Auth0 implementation and Auth0 status and services.
</Card>

<Card title="Logs" href="/docs/deploy-monitor/logs">
  Manage event logs for business analysis and insights.
</Card>


# Auth0 CLI
Source: https://auth0.com/docs/deploy-monitor/auth0-cli

Learn about Auth0 CLI and how to use it for tenant management.

<Card title="Before you start">
  Set up an [Auth0 Tenant](https://manage.auth0.com/).
</Card>

Auth0 CLI is a command-line tool that provides direct access to the Auth0 Management API, enabling you to manage your Auth0 tenant from your terminal. It's designed for interactive use during development and can be integrated into scripts for automation.

<Callout>
  For complete CLI command reference and detailed usage information, read [Auth0 CLI Reference Documentation](https://auth0.github.io/auth0-cli/).
</Callout>

## Key Features

* **Interactive Management**: Create, update, and manage Auth0 resources from the command line
* **Authentication Support**: Multiple authentication methods including user login and machine-to-machine credentials
* **Resource Management**: Full CRUD operations for applications, APIs, connections, users, and more
* **Cross-Platform**: Available for macOS, Linux, and Windows
* **JSON Output**: Machine-readable output for scripting and automation

## Use Cases

Auth0 CLI is ideal for:

* **Development Workflows**: Quickly set up and configure Auth0 resources during development
* **Testing**: Create test applications and users for automated testing
* **Debugging**: Inspect and modify Auth0 configuration in real-time
* **Scripting**: Automate repetitive tasks with shell scripts
* **CI/CD Integration**: Integrate Auth0 configuration into your deployment pipelines

## Comparison with Other Tools

### Auth0 CLI vs Deploy CLI

* **Auth0 CLI**: Interactive, command-by-command resource management. Best for development and ad-hoc tasks.
* **[Deploy CLI](/docs/deploy-monitor/deploy-cli-tool)**: Declarative, configuration-file-based tenant management. Best for managing entire tenant configurations across environments.

### Auth0 CLI vs Terraform Provider

* **Auth0 CLI**: Imperative commands for immediate changes. No state management.
* **Terraform Provider**: Declarative infrastructure-as-code with state tracking. Best for production infrastructure management.

## Install Auth0 CLI

### macOS

Configure with Homebrew:

```bash lines theme={null}
brew tap auth0/auth0-cli
brew install auth0
```

### Linux

```bash lines theme={null}
curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh | sh -s -- -b /usr/local/bin
```

### Windows

Configure with Scoop:

```powershell lines theme={null}
scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git
scoop install auth0
```

Or download the latest release from the [GitHub releases page](https://github.com/auth0/auth0-cli/releases).

## Authenticate

To use the Auth0 CLI, you need to authenticate. When you run the following command, a browser window opens for you to log in to your Auth0 account:

```bash lines theme={null}
auth0 login
```

To authenticate with a machine-to-machine application, use the following command:

```bash lines theme={null}
auth0 login --domain <your-domain> --client-id <client-id> --client-secret <client-secret>
```

## Common Commands

### Manage Applications

```bash lines theme={null}
# List all applications
auth0 apps list

# Create a new application
auth0 apps create --name "My App" --type spa

# Show application details
auth0 apps show <app-id>

# Update an application
auth0 apps update <app-id> --callbacks "http://localhost:3000/callback"

# Delete an application
auth0 apps delete <app-id>
```

### Manage APIs

```bash lines theme={null}
# List all APIs
auth0 apis list

# Create a new API
auth0 apis create --name "My API" --identifier "https://my-api.example.com"

# Show API details
auth0 apis show <api-id>
```

### Manage Users

```bash lines theme={null}
# List users
auth0 users list

# Create a user
auth0 users create --email "user@example.com" --connection "Username-Password-Authentication"

# Show user details
auth0 users show <user-id>

# Update a user
auth0 users update <user-id> --email "newemail@example.com"
```

### Manage Tenant Settings

```bash lines theme={null}
# Show current tenant
auth0 tenants list

# Update tenant settings
auth0 tenants update
```

## Using in Scripts

The Auth0 CLI supports JSON output for easy parsing in scripts:

```bash lines theme={null}
# Get application details as JSON
auth0 apps show <app-id> --json

# Create an app and capture the output
auth0 apps create --name "My App" --type spa --json > app-details.json
```

## Documentation and Support

For complete documentation, command reference, and examples, visit:

* [Auth0 CLI GitHub Repository](https://github.com/auth0/auth0-cli)
* [Auth0 CLI Documentation](https://auth0.github.io/auth0-cli/)

## Next Steps

<Columns>
  <Card title="Deploy CLI" href="/docs/deploy-monitor/deploy-cli-tool" icon="rocket">
    Learn about managing tenant configuration with the Deploy CLI
  </Card>

  <Card title="Terraform Provider" href="/docs/deploy-monitor/auth0-terraform-provider" icon="code">
    Explore infrastructure-as-code with Terraform
  </Card>

  <Card title="Management API" href="/docs/api/management/v2" icon="code-branch">
    Access the Auth0 Management API directly
  </Card>
</Columns>


# Auth0 Terraform Provider
Source: https://auth0.com/docs/deploy-monitor/auth0-terraform-provider

Learn about the Auth0 Terraform Provider for representing your tenant configurations as code.

The Deploy CLI is not the only tool available for managing your Auth0 tenant configuration, there is also an [officially supported Terraform Provider](https://github.com/auth0/terraform-provider-auth0). [Terraform](https://terraform.io/) is a third-party tool for representing your cloud resources’ configurations as code. It has an established plug-in framework that supports a wide array of cloud providers, including Auth0.

Both the Deploy CLI and Terraform Provider exist to help you manage your Auth0 tenant configurations, but each has their own set of pros and cons.

You may want to consider the Auth0 Terraform Provider if:

* Your development workflows already leverages Terraform
* Your tenant management needs are granular or only pertain to a few specific resources

You may not want to consider the Auth0 Terraform Provider if:

* Your development workflow does not use Terraform, requiring extra setup upfront
* Your development workflows are primarily concerned with managing your tenants in bulk
* Your tenant has lots of existing resources, may require significant effort to “import"


# Deployment Checklist
Source: https://auth0.com/docs/deploy-monitor/deploy-checklist

Deployment checklists for your implementation

Auth0 has provided the following deployment checklist for your use. You may not find that every item is applicable, so please modify the checklist based on the needs of your implementation.

## How to use the checklist

1. Click the link below to download the checklist.
2. Open the checklist in any spreadsheet application.
3. Customize the checklist to suit your needs.

<InlineImage />[Deploy Checklist](https://assets.ctfassets.net/cdy7uua7fh8z/78b5P011cQmYyZ7XZkQcoK/3c42c9146f9823b427bcd06b2889fa7c/Deploy-Checklist.xlsx)

In the Deploy phase, you will deploy the system to either a staging or production environment, where actual users begin to operate and interact with it.

Eventually, you deploy all components of the system to the production environment when you make a live release.

## Learn more

* [Pre-Deployment Checks](/docs/deploy-monitor/pre-deployment-checks)
* [Run Pre-Deployment Tests](/docs/deploy-monitor/pre-deployment-checks/predeployment-tests)
* [Pre-Launch Tips](/docs/deploy-monitor/pre-deployment-checks/pre-launch-tips)


# Auth0 Deploy CLI
Source: https://auth0.com/docs/deploy-monitor/deploy-cli-tool

Learn about the Auth0 Deploy CLI and how it works.

<Card title="Before you start">
  Set up an [Auth0 Tenant](https://manage.auth0.com/).
</Card>

The Auth0 Deploy CLI is a tool that helps you manage your Auth0 tenant configuration. It integrates into your development workflows as a standalone CLI or as a node module.

Supported resource types: `actions`, `branding`, `client grants`, `clients (applications)`, `connections`, `custom domains`, `email templates`, `emails`, `grants`, `guardian`, `hook secrets`, `log streams`, `migrations`, `organizations`, `pages`, `prompts`, `resource servers (APIs)`, `roles`, `tenant settings`, `themes`.

## Highlights

* **Multi-Environment Oriented:** Designed to help you test your applications' Auth0 integrations from feature branch all the way to production.
* **Keyword Replacement:** Shared resource configurations across all environments with dynamic keyword replacement.
* **Versatile:** Integrate into your CI/CD workflows either as a CLI or as a Node module.

## Get started

This guide will help you to a working implementation of the Deploy CLI tool used as a standalone CLI. There are three main steps before the Deploy CLI can be run:

1. [Create a dedicated Auth0 Application](#create-a-dedicated-auth0-application)
2. [Configure the Deploy CLI](#configure-the-deploy-cli)
3. [Call the Deploy CLI](#call-the-deploy-cli)

<Warning>
  This tool can be destructive to your Auth0 tenant. It is recommended to be familiar with the [AUTH0\_ALLOW\_DELETE configuration](/docs/deploy-monitor/deploy-cli-tool/configure-the-deploy-cli#auth0_allow_delete) and to test on development tenants prior to using in production.
</Warning>

### Install the Deploy CLI

To run as a standalone command-line tool:

`npm install -g auth0-deploy-cli`

### Create a dedicated Auth0 application

In order for the Deploy CLI to call the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>, a dedicated Auth0 application must be created to make calls on behalf of the tool:

1. Go to **Auth0 Dashboard > Applications > Applications**.
2. Select **+ Create Application**.

   1. Give it a descriptive name (such as “Deploy CLI”).
   2. Select **Machine to Machine Applications** for the **Application Type**.
   3. Select **Create**.
3. Switch to the **Authorize Machine to Machine Application** view:

   1. Select **Auth0 Management API**.
   2. Select the appropriate permissions for the resources you wish to manage. Refer to the [Client Scopes](#client-scopes) section for more information.
   3. Select **Authorize**.

<Callout icon="file-lines">
  The Deploy CLI's own client is not configurable by itself to [prevent potentially destructive changes](/docs/deploy-monitor/deploy-cli-tool/resource-specific-documentation#client-grants).
</Callout>

#### Client scopes

The designated application needs to be granted scopes in order to allow the Deploy CLI to execute Management operations.

The principle of least privilege is abided, so it will operate within the set of permissions granted. , you'll need to select `read:clients`, but it’s recommended to select `read:*`, `create:*`, and `update:*` permissions for all resource types within management purview. To enable deletions, you `delete:*` scopes.

### Configure the Deploy CLI

You can configure the Deploy CLI in two ways:

1. Use the configuration file (`config.json`).
2. Set environment variables.

The decision to choose one or both would depend on your specific use case and preferences. To learn more, read [Configure the Deploy CLI](/docs/deploy-monitor/deploy-cli-tool/configure-the-deploy-cli).

For this example, set the following environment variables:

* `AUTH0_DOMAIN`
* `AUTH0_CLIENT_ID`
* `AUTH0_CLIENT_SECRET`

These values can be found in the **Settings** tab for the dedicated Auth0 application you created previously.

### Call the Deploy CLI

The Deploy CLI `export` command can be run with the following command:

`a0deploy export --format=yaml --output_folder=local`

Once the process completes, observe the resource configuration files generated in the local directory. Then, run the `import` command to push the configuration from your local machine to your Auth0 tenant:

`a0deploy import --config_file=config.json --input_file local/tenant.yaml`

For a comprehensive list of flags and options, please read [Use as CLI](/docs/deploy-monitor/deploy-cli-tool/use-as-a-cli).


# Authenticate with your Tenant
Source: https://auth0.com/docs/deploy-monitor/deploy-cli-tool/authenticate-with-your-tenant

Learn about the different methods of authenticating the Auth0 Deploy CLI with your tenant.

There are three supported methods of authenticating the Auth0 Deploy CLI with your tenant.

## Client credentials

[Client credentials](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow) authentication requires you provide a <Tooltip href="/docs/glossary?term=client+ID">client ID</Tooltip> and <Tooltip href="/docs/glossary?term=client+secret">client secret</Tooltip> pair directly to the application. This option is straightforward and enables the quickest path to setup for the tool.

To configure client credentials authentication, set the the following fields in your [configuration file](/docs/deploy-monitor/deploy-cli-tool/configure-the-deploy-cli):

<table>
  <thead>
    <tr>
      <th><strong>Field</strong></th>
      <th><strong>Value</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>AUTH0\_CLIENT\_ID</code></td>
      <td>Client ID of your Auth0 application.</td>
    </tr>

    <tr>
      <td><code>AUTH0\_CLIENT\_SECRET</code></td>
      <td>Client secret of your Auth0 application.</td>
    </tr>
  </tbody>
</table>

## Private key JWT

[Private key JWT](/docs/get-started/applications/configure-private-key-jwt) authentication requires you configure a private key for the application and a public key for the remote tenant. This option is ideal if do not want to store credentials remotely on Auth0.

To configure private key <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> authentication, set the following fields in your [configuration file](/docs/deploy-monitor/deploy-cli-tool/configure-the-deploy-cli):

<table>
  <thead>
    <tr>
      <th><strong>Field</strong></th>
      <th><strong>Value</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>AUTH0\_CLIENT\_SIGNING\_KEY\_PATH</code></td>
      <td>Relative path to the JWT signing key certificate.</td>
    </tr>

    <tr>
      <td><code>AUTH0\_CLIENT\_SIGNING\_ALGORITHM</code></td>
      <td>Optional. JWT signing algorithm used for the certificate.</td>
    </tr>
  </tbody>
</table>

## Access token

[Access token](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production) authentication requires you provide an Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> directly to the application. This option puts more responsibility on developers but can enable flexible and specific workflows when necessary.

To configure access token authentication, pass a Management API Auth0 access token through the `AUTH0_ACCESS_TOKEN` [environment variable](/docs/deploy-monitor/deploy-cli-tool/configure-the-deploy-cli).


# Available Resource Configuration Formats
Source: https://auth0.com/docs/deploy-monitor/deploy-cli-tool/available-resource-configuration-formats

Learn about the available configuration formats when using the Auth0 Deploy CLI.

Auth0 resource state is expressed in two available different configuration file formats: YAML and directory (JSON). When using the Deploy CLI’s `export` command, you will be prompted with the choice of one versus the other.

## YAML

The YAML format is expressed mostly as a flat tenant.yaml file with supplemental code files for resources like actions and email templates. The single file makes tracking changes over time in version control more straightforward. Additionally, the single file eliminates a bit of ambiguity with directory and file names, which may not be immediately obvious.

## Directory (JSON)

The directory format separates resource types into separate directories, with each single resource living inside a dedicated JSON file. This format allows for easier conceptual separation between each type of resource as well as the individual resources themselves. Also, the Deploy CLI closely mirrors the data shapes defined in the [Auth0 Management API](https://auth0.com/docs/api/management/v2), so referencing the JSON examples in the docs may be useful when using this format.

## How to choose

The decision to select which format to use should be primarily made off of preference. Both formats are tenable solutions that achieve the same task, but with subtly different strengths and weaknesses described above. Be sure to evaluate each in the context of your context. Importantly, this choice is not permanent, and switching from one to the other with the `import` command is an option at your disposal.


# Configure the Deploy CLI
Source: https://auth0.com/docs/deploy-monitor/deploy-cli-tool/configure-the-deploy-cli

Learn how to configure the Auth0 Deploy CLI to modify the tool for your needs.

Configuring the Deploy’s CLI is essential for establishing Auth0 credentials as well as generally modifying the behavior of the tool to your specific needs. There are two ways the Deploy CLI can be configured:

1. Use the configuration file (`config.json`).
2. Set environment variables.

## Configuration file

A standalone JSON file can be used to configure Deploy CLI. This file will usually reside in the root directory of your project and should be named `config.json`.

### Example

```json lines theme={null}
{
  "AUTH0_DOMAIN": "<YOUR_TENANT_DOMAIN>",
  "AUTH0_CLIENT_ID": "{yourClientId}",
  "AUTH0_ALLOW_DELETE": false
}
```

<Callout icon="file-lines">
  Hard-coding credentials is not recommended, and risks secret leakage should this file ever be committed to a public version control system. To mitigate this risk, pass credentials as [environment variables](#environment-variables) as a best practice.
</Callout>

## Environment variables

By default, the Deploy CLI ingests environment variables, providing the ability to pass credentials and other configurations to the tool without needing to publish to the `config.json` file. Environment variables can either be used to augment the `config.json` file or replace it altogether depending on the project needs.

Non-primitive configuration values like `AUTH0_KEYWORD_REPLACE_MAPPINGS` and `AUTH0_EXCLUDED` can also be passed in through environment variables so long as these values are properly serialized JSON.

To disable the consumption of environment variables for either the `import` or `export` commands, pass the `--env=false` argument.

### Examples

#### Deploying configuration for YAML formats without a config.json file

```bash lines theme={null}
$ export AUTH0_DOMAIN={yourDomain}
$ export AUTH0_CLIENT_ID={yourClientId}
$ export AUTH0_CLIENT_SECRET={yourClientSecret}
$ a0deploy import --input_file=local/tenant.yaml
```

#### Disable environment variable ingestion

```bash wrap lines theme={null}
$ a0deploy export -c=config.json --format=yaml --output_folder=local --env=false
```

#### Non-primitive configuration values

```bash lines theme={null}
$ export AUTH0_EXCLUDED='["actions","organizations"]'
$ export AUTH0_KEYWORD_REPLACE_MAPPINGS='{"ENVIRONMENT":"dev"}'
$ a0deploy export -c=config.json --format=yaml --output_folder=local
```

## Available Configuration Properties

### AUTH0\_DOMAIN

String. The domain of the target Auth0 tenant.

### AUTH0\_CLIENT\_ID

String. The ID of the designated Auth0 application used to make API requests.

### AUTH0\_CLIENT\_SECRET

String. The secret of the designated Auth0 application used to make API requests.

### AUTH0\_ACCESS\_TOKEN

String. Short-lived <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> for <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> from designated Auth0 application. Can be used in replacement to <Tooltip href="/docs/glossary?term=client+ID">client ID</Tooltip> and <Tooltip href="/docs/glossary?term=client+secret">client secret</Tooltip> combination.

### AUTH0\_CLIENT\_SIGNING\_KEY\_PATH

String. The path to the private key used by the client when facilitating Private Key <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> authentication. Path relative to the working directory. Also note `AUTH0_CLIENT_SIGNING_ALGORITHM` for specifying <Tooltip href="/docs/glossary?term=signing+algorithm">signing algorithm</Tooltip>.

### AUTH0\_CLIENT\_SIGNING\_ALGORITHM

String. Specifies the JWT signing algorithms used by the client when facilitating Private Key JWT authentication. Only used in combination with `AUTH0_CLIENT_SIGNING_KEY_PATH`.

Accepted values: `RS256`, `RS384`, `PS256`.

### AUTH0\_ALLOW\_DELETE

Boolean. When enabled, will allow the tool to delete resources. Default: `false`.

### AUTH0\_EXCLUDED

Array of strings. Excludes entire resource types from being managed, bi-directionally. To learn more, read [Exclude Resources from Management](/docs/deploy-monitor/deploy-cli-tool/exclude-resources-from-management).

Cannot be used simultaneously with [AUTH0\_INCLUDED\_ONLY](#auth0_included_only).

Possible values: `actions`, `attackProtection`, `branding`, `clientGrants`, `clients`, `connections`, `customDomains`, `databases`, `emailProvider`, `emailTemplates`, `guardianFactorProviders`, `guardianFactorTemplates`, `guardianFactors`, `guardianPhoneFactorMessageTypes`, `guardianPhoneFactorSelectedProvider`, `guardianPolicies`, `logStreams`, `migrations`, `organizations`, `pages`, `prompts`, `resourceServers`, `roles`, `tenant`, `triggers`.

#### Example

```json lines theme={null}
{
  "AUTH0_EXCLUDED": ["organizations", "connections", "hooks"]
}
```

### AUTH0\_INCLUDED\_ONLY

Array of strings. Specifies which resource types to manage bi-directionally. To learn more, read [Exclude Resources from Management](/docs/deploy-monitor/deploy-cli-tool/exclude-resources-from-management).

Cannot be used simultaneously with [AUTH0\_EXCLUDED](#auth0_excluded).

Possible values: `actions`, `attackProtection`, `branding`, `clientGrants`, `clients`, `connections`, `customDomains`, `databases`, `emailProvider`, `emailTemplates`, `guardianFactorProviders`, `guardianFactorTemplates`, `guardianFactors`, `guardianPhoneFactorMessageTypes`, `guardianPhoneFactorSelectedProvider`, `guardianPolicies`, `logStreams`, `migrations`, `organizations`, `pages`, `prompts`, `resourceServers`, `roles`, `tenant`, `triggers`.

#### Example

```json lines theme={null}
{
  "AUTH0_INCLUDED_ONLY": ["clients", "connections", "tenant", "branding"]
}
```

### AUTH0\_KEYWORD\_REPLACE\_MAPPINGS

Mapping of specific keywords to facilities dynamic replacement. To learn more, read [Keyword Replacement](/docs/deploy-monitor/deploy-cli-tool/keyword-replacement).

#### Example

```json lines theme={null}
{
  "ENVIRONMENT": "DEV",
  "ALLOWED_ORIGINS": ["https://dev.test-site.com", "localhost"]
}
```

### AUTH0\_PRESERVE\_KEYWORDS

Boolean. When enabled, will attempt to preserve keyword replacement markers in local resource files during export. Otherwise, the remote values will overwrite those manually-placed keyword markers.

This configuration requires the presence of local configuration files and defined keyword replace mappings via the `AUTH0_KEYWORD_REPLACE_MAPPINGS` configuration property.

See also: [Preserve Keywords on Export](/docs/deploy-monitor/deploy-cli-tool/keyword-replacement#preserve-keywords-on-export).

### AUTH0\_EXPORT\_IDENTIFIERS

Boolean. When enabled, will return identifiers of all resources. May be useful for certain debugging or record-keeping scenarios within a single-tenant context. Default: `false`.

### EXCLUDED\_PROPS

Provides ability to exclude any unwanted properties from management.

#### Example

```json lines theme={null}
{
  "connections": ["options.twilio_token"]
}
```

### AUTH0\_AUDIENCE

String. Separate value from <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> value while retrieving an access token for the Management API. Useful when default Management API endpoints are not publicly exposed.

### AUTH0\_EXCLUDED\_RULES

Array of strings. Excludes the management of specific rules by ID. Note: This configuration may be subject to deprecation in the future. To learn more, read [Exclude Resources from Management](/docs/deploy-monitor/deploy-cli-tool/exclude-resources-from-management).

### AUTH0\_EXCLUDED\_CLIENTS

Array of strings. Excludes the management of specific clients by ID. Note: This configuration may be subject to deprecation in the future. To learn more, read [Exclude Resources from Management](/docs/deploy-monitor/deploy-cli-tool/exclude-resources-from-management).

### AUTH0\_EXCLUDED\_DATABASES

Array of strings. Excludes the management of specific databases by ID. Note: This configuration may be subject to deprecation in the future. To learn more, read [Exclude Resources from Management](/docs/deploy-monitor/deploy-cli-tool/exclude-resources-from-management).

### AUTH0\_EXCLUDED\_CONNECTIONS

Array of strings. Excludes the management of specific connections by ID. Note: This configuration may be subject to deprecation in the future. To learn more, read [Exclude Resources from Management](/docs/deploy-monitor/deploy-cli-tool/exclude-resources-from-management).

### AUTH0\_EXCLUDED\_RESOURCE\_SERVERS

Array of strings. Excludes the management of specific <Tooltip href="/docs/glossary?term=resource+servers">resource servers</Tooltip> by ID. Note: This configuration may be subject to deprecation in the future. To learn more, read [Exclude Resources from Management](/docs/deploy-monitor/deploy-cli-tool/exclude-resources-from-management).


# Exclude Resources From Management
Source: https://auth0.com/docs/deploy-monitor/deploy-cli-tool/exclude-resources-from-management

Learn how to exclude resources from being managed when using the Auth0 Deploy CLI.

In some cases, you may find it useful to exclude resources from being managed. This could be because your tenant has a large number of a particular resource and it’s operationally burdensome to manage them, or your development workflow only pertains to a specific subset of resources and you’d like to omit all other resources for performance. Regardless, there are several options available for excluding resources when using the Deploy CLI.

## Exclude entire resources by type

For more complex tenants, you may find yourself wanting to omit entire resource types. For example:

* Enterprise tenant with thousands of organizations, where managing all would be operationally burdensome.
* CI/CD process only focuses on managing roles, and you want to exclude all others.
* Feature development pertains to hook, and you want to temporarily exclude all others to optimize performance.

This type of exclusion is expressed by passing an array of resource names into either the `AUTH0_EXCLUDED` or `AUTH0_INCLUDED_ONLY` configuration properties. The `AUTH0_EXCLUDED` configuration property excludes only the resource types provided to it. Inversely, the `AUTH0_INCLUDED_ONLY` property excludes all properties except the ones defined. Exclusion works bi-directionally, that is, both when export from Auth0 and importing to Auth0, regardless if resource configuration files exist or not.

All supported resource values for exclusion: `actions`, `attackProtection`, `branding`, `clientGrants`, `clients`, `connections`, `customDomains`, `databases`, `emailProvider`, `emailTemplates`, `guardianFactorProviders`, `guardianFactorTemplates`, `guardianFactors`, `guardianPhoneFactorMessageTypes`, `guardianPhoneFactorSelectedProvider`, `guardianPolicies`, `logStreams`, `migrations`, `organizations`, `pages`, `prompts`, `resourceServers`, `roles`, `tenant`, `triggers`.

### Exclusion example

The following example shows how to exclude `clients`, `connections`, `databases`, and `organizations` from being managed by the Deploy CLI.

```json lines theme={null}
{
  "AUTH0_DOMAIN": "example-site.us.auth0.com",
  "AUTH0_CLIENT_ID": "<YOUR_AUTH0_CLIENT_ID>",
  "AUTH0_EXCLUDED": ["clients", "connections", "databases", "organizations"]
}
```

### Inclusion example

The following example shows how to specify to only manage `actions`, `clients` and `connections` by the Deploy CLI.

```json lines theme={null}
{
  "AUTH0_DOMAIN": "example-site.us.auth0.com",
  "AUTH0_CLIENT_ID": "<YOUR_AUTH0_CLIENT_ID>",
  "AUTH0_INCLUDED_ONLY": ["actions", "clients", "connections"]
}
```

## Exclude single resources by ID

Some resource types support exclusions of the individual resource by ID. This is useful if you work in a multi-environment context and wish to omit a production-specific resource from your lower-level environments.

This method is supported for rules, clients, databases, connections and <Tooltip href="/docs/glossary?term=resource+servers">resource servers</Tooltip> with the `AUTH0_EXCLUDED_RULES`, `AUTH0_EXCLUDED_CLIENTS`, `AUTH0_EXCLUDED_DATABASES`, `AUTH0_EXCLUDED_CONNECTIONS`, `AUTH0_EXCLUDED_RESOURCE_SERVERS` configuration values respectively.

### Example

```json lines theme={null}
{
  "AUTH0_DOMAIN": "example-site.us.auth0.com",
  "AUTH0_CLIENT_ID": "<YOUR_AUTH0_CLIENT_ID>",
  "AUTH0_EXCLUDED_CLIENTS": ["Your Application Name"],
  "AUTH0_EXCLUDED_CONNECTIONS": ["con_O1H3KyRMFP1IWRq3", "con_9avEYuj19ihqKBOs"]
}
```

<Callout icon="file-lines">
  Excluding resources by ID is being considered for deprecation in future major versions. See the [resource exclusion proposal](https://github.com/auth0/auth0-deploy-cli/blob/6381ce6efa8cd59e7a5c8d37e8915b0989d677b9/docs/excluding-from-management.md?plain=1#L51) for more details.
</Callout>

## Omission and empty states

In addition to excluding resources, which forcefully ignore configurations bi-directionally, the Auth0 Deploy  CLI supports two similar concepts: omission and empty states.

### Omission

Resource configuration that is absent, either intentionally or unintentionally, will be skipped during import. For example, if your resource configuration were deleted, it would be skipped during import and would not alter the state of the remote tenant.

There is no concept of omission for exporting. Unless specifically excluded, all your tenant configurations will be written to resource configuration files.

#### Example

```yaml lines theme={null}
roles: # roles configuration is not omitted
  - name: Admin
    description: Can read and write things
    permissions: []
  - name: Reader
    description: Can only read things
    permissions: []
# The omission of all other configurations means they'll be skipped over
```

### Empty

Resource configuration that is explicitly defined as empty. For set-based configurations like hooks, organizations, and actions, setting these configurations to an empty set expresses an intentional emptying of those resources. This would signal a deletion, so long as the AUTH0\_ALLOW\_DELETE deletion configuration property is enabled. To learn more about this property, read [Configure the Deploy CLI](/docs/deploy-monitor/deploy-cli-tool/configure-the-deploy-cli).

For non-set-based resource configuration like tenant and branding, the concept of emptiness does not apply, and will not trigger any deletions or removals.

#### Example of emptiness

```yaml lines theme={null}
hooks: [] # Empty hooks
connections: [] # Empty connections
tenant: {} # Effectively a no-op, emptiness does not apply to non-set resource config
```


# Incorporate into Multi-environment Workflows
Source: https://auth0.com/docs/deploy-monitor/deploy-cli-tool/incorporate-into-multi-environment-workflows

Learn how to support multi-tenant, multi-environment workflows when using the Auth0 Deploy CLI.

The Deploy CLI supports working within a multi-tenant, multi-environment context. When integrated into your CI/CD development workflows, can be used to propagate Auth0 changes from feature development all the way through production.

In general, the advised workflow is as follows:

1. Create a separate Auth0 tenant for each environment (development, staging, production).
2. Create a single repository of resource configuration files for all environments.
3. Add a step in your CI/CD pipeline when deploying to environments that applies the Auth0 resource configurations to the appropriate Auth0 tenant.

## Tenant to environment

It is recommended to have a separate Auth0 tenant/account for each environment you have. For example:

<table>
  <thead>
    <tr>
      <th><strong>Environment</strong></th>
      <th><strong>Tenant</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Development</td>
      <td><code>travel0-dev</code></td>
    </tr>

    <tr>
      <td>Testing</td>
      <td><code>travel0-uat</code></td>
    </tr>

    <tr>
      <td>Staging</td>
      <td><code>travel0-stage</code></td>
    </tr>

    <tr>
      <td>Production</td>
      <td><code>travel0-prod</code></td>
    </tr>
  </tbody>
</table>

## Resource configuration repository

When exported, your Auth0 tenant state will be represented as a set of resource configuration files, either in a [YAML or directory format](/docs/deploy-monitor/deploy-cli-tool/available-resource-configuration-formats). In a multi-environment context it is expected to have a single repository of resource configurations that is applied to all environments. In practice, this may exist as a directory in your project’s codebase or in a separate codebase altogether.

You should have at least one branch for each tenant in your repository, which allows you to make changes without deploying them. This way, changes will only deploy when you merge the working branch into the primary branch (such as `main` or `master`). With this setup, you can have a continuous integration task for each environment that automatically deploys changes to the targeted environment whenever the primary branch receives updates.

Your workflow could potentially look something like this:

1. Make changes to development.
2. Merge changes to testing (or uat).
3. Test changes to uat. When ready, move and merge the changes to staging.
4. Test staging. When ready, move and merge the changes to production.

As a precaution, you may want to set your production environment to deploy only when triggered manually.

## Unidirectional flow

The multi-environment workflow works best when changes are propagated “up” in a single direction. Changes to the resource configuration files should first be applied to the lowest level environment (such as development) and then incrementally applied up through all other environments until applied to production. This unidirectional practice ensures sufficient testing and approval for changes to your tenant. Once set, it is recommended to not apply configurations directly to production through other means such as the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> unless those changes are captured by a subsequent Deploy CLI export. Otherwise, those changes are subject to overwrite.

## Environment-specific values

While it is expected that all environments will share the same set of resource configuration files, environment-specific values can be expressed through separate tool configuration files and dynamic [Keyword Replacement](/docs/deploy-monitor/deploy-cli-tool/keyword-replacement).

## Separate configuration files

Specifying a separate tool configuration file per environment can be used to keep the resource configuration files agnostic of the environment, but still support the needs of each environment. At a minimum, you will need to provide separate credentials for each environment, but it is also possible to exclude certain resources, enable deletion, and perform dynamic keyword replacement on a per-environment basis.

### Example file structure

```text lines theme={null}
project-root
│
└───auth0
│   │   config-dev.json   # Dev env config file
│   │   config-test.json  # Test env config file
│   │   config-prod.json  # Prod env config file
│   │   ... all other resource configuration files
│
└───src
    │   ... your project code
```

## Dynamic values with keyword replacement

Once separate configuration files are adopted for each environment, keyword replacement through the `AUTH0_KEYWORD_REPLACE_MAPPINGS` configuration property can be used to express the dynamic replacement values depending on the environment. For example, you may find it necessary to have a separate set of allowed origins for your clients. To learn more, read [Keyword Replacement](/docs/deploy-monitor/deploy-cli-tool/keyword-replacement).

### Example config-dev.json

```json lines theme={null}
{
  "AUTH0_DOMAIN": "travel0-dev.us.auth0.com",
  "AUTH0_CLIENT_ID": "PdwQpGy62sHcsV6ufZNEVrV4GDlDhm74",
  "AUTH0_ALLOW_DELETE": true,
  "AUTH0_KEYWORD_REPLACE_MAPPINGS": {
    "ENV": "dev",
    "ALLOWED_ORIGINS": ["http://localhost:3000", "http://dev.travel0.com"]
  }
}
```

### Example config-prod.json

```json lines theme={null}
{
  "AUTH0_DOMAIN": "travel0.us.auth0.com",
  "AUTH0_CLIENT_ID": "vZCEFsDYzXc1x9IomB8dF185e4cdVah5",
  "AUTH0_ALLOW_DELETE": false,
  "AUTH0_KEYWORD_REPLACE_MAPPINGS": {
    "ENV": "prod",
    "ALLOWED_ORIGINS": ["http://travel0.com"]
  }
}
```


# Keyword Replacement
Source: https://auth0.com/docs/deploy-monitor/deploy-cli-tool/keyword-replacement

Learn how to manage a multi-tenant workflow with the Auth0 Deploy CLI using keyword replacement.

The Deploy CLI supports dynamic keyword replacement with environment-specific values. This enables a scalable multi-tenant workflow where all tenants share the same resource configuration files but inject subtly different values.

To use the keyword replacement, the `AUTH0_KEYWORD_REPLACE_MAPPINGS` configuration property needs to contain the appropriate mappings. Then, in the resource configuration files, keywords can be injected through one of two ways:

1. `@@EXAMPLE_KEY@@`: Using the `@` symbols causes the tool to perform a `JSON.stringify` on your value before replacing it. So if your value is a string, the tool will add quotes; if your value is an array or object, the tool will add braces.
2. `##EXAMPLE_KEY##`: Using the `#` symbol causes the tool to perform a literal replacement; it will not add quotes or braces.

## Example config.json

```json lines theme={null}
{
  "AUTH0_DOMAIN": "test-tenant.us.auth0.com",
  "AUTH0_CLIENT_ID": "FOO",
  "AUTH0_CLIENT_SECRET": "BAR",
  "AUTH0_KEYWORD_REPLACE_MAPPINGS": {
    "ENVIRONMENT": "dev",
    "ALLOWED_LOGOUT_URLS": ["https://dev-test-site.com/logout", "localhost:3000/logout"],
    "ALLOWED_ORIGINS": ["https://dev-test-site.com", "localhost:3000"]
  }
}
```

## Example tenant.yaml

```yaml lines theme={null}
tenant:
  friendly_name: "##ENVIRONMENT## tenant"
  allowed_logout_urls: @@ALLOWED_LOGOUT_URLS@@
  enabled_locales:
    - en
clients:
  - name: Test App
    allowed_origins: @@ALLOWED_ORIGINS@@
    allowed_logout_urls: @@ALLOWED_LOGOUT_URLS@@
```

## Example tenant.json

```json lines theme={null}
{
  "friendly_name": "##ENVIRONMENT## tenant",
  "allowed_logout_urls": "@@ALLOWED_LOGOUT_URLS@@"
}
```

## Array Concatenation

You may encounter situations where you would want to concatenate values onto a static array through keyword replacement. There is no special syntax to support this case, however, it is possible to achieve this by escaping double quotes in a single string that contains the appropriate values and injecting with the `##` keyword syntax. This technique works for both the [YAML and directory formats](/docs/deploy-monitor/deploy-cli-tool/available-resource-configuration-formats).

### Example config.json

```json lines theme={null}
{
  "AUTH0_KEYWORD_REPLACE_MAPPINGS": {
    "GLOBAL_WEB_ORIGINS": "\"http://local.me:8080\", \"http://localhost\", \"http://localhost:3000\""
  }
}
```

### Example tenant.yaml

```yaml lines theme={null}
clients:
  - name: Test App
    web_origins: [ "http://production-app.com", "https://production-app.com", ##GLOBAL_WEB_ORIGINS## ]
```

## Preserve Keywords on Export

Generally, the Deploy CLI works best when operating in a uni-directional workflow from your lower-level environments (ex: dev, test) up to your production environments. However, there will be times when it is necessary to export configuration from a higher-level environment onto your local configuration directory. By default, the remote values will overwrite your local values, **causing the deletion of your keyword markers**. However, keyword replacement preservation can be enabled through the `AUTH0_PRESERVE_KEYWORDS` boolean configuration property. By enabling this configuration, the Deploy CLI will attempt to preserve the keyword markers defined in your local configuration files during export.

The keyword preservation functionality will attempt to preserve as many keywords while also maintaining the accuracy of your resource configuration files. And it the majority of cases, it will work without any intervention by the user. However, some key limitations exist:

* In the case of a keyword-replaced configuration field with differing values between local and remote, the local configuration value will always be favored. This will cause **any out-of-band changes on remote to be wiped away** if a keyword replace marker exists anywhere in that field's value in the resource definition file; there is no "intelligent" reconciliation.
* Arrays without a specific identifiers are not eligible for preservation. Ex: `["http://site.com/logout", "localhost:3000/logout", "##LOGOUT_URL##"]`. This is because the ordering of these values are non-deterministic. Alternatively, to preserve these values, it is recommended to leverage the `@@ARRAY_REPLACE@@` keyword replace syntax with the entire value.

To learn more about the history and technical challenges of of keyword preservation, refer to [RFC: Keyword Preservation During Export](https://github.com/auth0/auth0-deploy-cli/issues/688).


# Resource-specific Documentation
Source: https://auth0.com/docs/deploy-monitor/deploy-cli-tool/resource-specific-documentation

Learn about the specifics of resource documentation for the Auth0 Deploy CLI.

In general, the Deploy CLI resource configuration files closely match the payload schemas of the [Auth0 Management API](https://auth0.com/docs/api/management/v2), but there are some notable nuances to be aware of.

## Client grants

The Deploy CLI's own client grant is intentionally not exported nor configurable by itself. This is done to prevent breaking changes, otherwise the tool could potentially revoke access or otherwise crash in the midst of an import. In a multi-tenant, multi-environment context, it is expect that new tenants will have a designated client already established for the Deploy CLI, as mentioned in [Getting Started](/docs/deploy-monitor/deploy-cli-tool).

## Prompts

Multilingual custom text prompts follow a particular hierarchy. Under the root-level prompts resource property is a proprietary `customText` property that is used to bundle custom text translations with other prompts settings. Underneath `customText` is the two-character language code. Thirdly is the prompt ID, followed by the screen ID, followed by text ID.

### Hierarchy

```yaml lines theme={null}
prompts:
  customText:
    <LANGUAGE>: # two character language code
      <PROMPT_ID>: # prompt ID
        <SCREEN_ID>: # prompt screen ID
          <TEXT_ID>: 'Some text'
```

### Example

```yaml lines theme={null}
prompts:
  identifier_first: true
  universal_login_experience: classic
  customText:
    en:
      login:
        login:
          description: Login description in english
          buttonText: Button text
      mfa:
        mfa-detect-browser-capabilities:
          pickAuthenticatorText: 'Try another method'
          reloadButtonText: 'Reload'
          noJSErrorTitle: 'JavaScript Required'
        mfa-login-options:
          pageTitle: 'Log in to ${clientName}'
          authenticatorNamesSMS: 'SMS'
```

## Databases

When managing database connections, the values of `options.customScripts` point to specific javascript files relative to the path of the output folder. Otherwise, the payload closely matches that of the [Auth0 Management API](https://auth0.com/docs/api/management/v2#!/Connections/post_connections).

### YAML example

Folder structure when in YAML mode:

```text lines theme={null}
./databases/
    /Username-Password-Authentication
        /change_password.js   
        /create.js   
        /delete.js   
        /get_user.js   
        /login.js   
        /verify.js   
./tenant.yaml
```

 Contents of `tenant.yaml`:

```yaml lines theme={null}
databases:
  - name: Username-Password-Authentication
    # ...
    options:
      # ...
      customScripts:
        change_password: ./databases/Username-Password-Authentication/change_password.js
        create: ./databases/Username-Password-Authentication/create.js
        delete: ./databases/Username-Password-Authentication/delete.js
        get_user: ./databases/Username-Password-Authentication/get_user.js
        login: ./databases/Username-Password-Authentication/login.js
        verify: ./databases/Username-Password-Authentication/verify.js
```

### Directory example

Folder structure when in directory mode:

```text lines theme={null}
./database-connections/
    ./Username-Password-Authentication/
        ./change_password.js
        ./create.js
        ./database.json
        ./delete.js
        ./get_user.js
        ./login.js
        ./verify.js
```

Contents of `database.json`:

```json lines theme={null}
{
  "options": {
    "customScripts": {
      "change_password": "./change_password.js",
      "create": "./create.js",
      "delete": "./delete.js",
      "get_user": "./get_user.js",
      "login": "./login.js",
      "verify": "./verify.js"
    }
  }
}
```

## Universal Login

### Pages

When overriding the <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> with custom HTML, the error, login, <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip>, and password reset contents are organized in specific HTML pages.

#### YAML example

Folder structure when in YAML mode:

```text lines theme={null}
./pages/
    /error_page.html
    /guardian_multifactor.html
    /login.html
    /password_reset.html
./tenant.yaml
```

Contents of `tenant.yaml`:

```yaml lines theme={null}
pages:
  - name: error_page
    html: ./pages/error_page.html
    show_log_link: false
    url: https://mycompany.org/error
  - name: guardian_multifactor
    enabled: true
    html: ./pages/guardian_multifactor.html
  - name: login
    enabled: false
    html: ./pages/login.html
  - name: password_reset
    enabled: true
    html: ./pages/password_reset.html
```

#### Directory Example

Folder structure when in directory mode:

```text lines theme={null}
./pages/
    ./error_page.html
    ./error_page.json
    ./guardian_multifactor.html
    ./guardian_multifactor.json
    ./login.html
    ./login.json
    ./password_reset.html
    ./password_reset.json
```

Contents of `login.json`:

```json lines theme={null}
{
  "name": "login",
  "enabled": false,
  "html": "./login.html"
}
```

Contents of `error_page.json`:

```json lines theme={null}
{
  "html": "./error_page.html",
  "show_log_link": false,
  "url": "https://mycompany.org/error",
  "name": "error_page"
}
```

Contents of `guardian_multifactor.json`:

```json lines theme={null}
{
  "enabled": true,
  "html": "./guardian_multifactor.html",
  "name": "guardian_multifactor"
}
```

Contents of `password_reset.json`:

```json lines theme={null}
{
  "enabled": true,
  "html": "./password_reset.html",
  "name": "password_reset"
}
```


# Use as a CLI
Source: https://auth0.com/docs/deploy-monitor/deploy-cli-tool/use-as-a-cli

Learn how to the use the Auth0 Deploy CLI as a standalone command-line utility.

The Deploy CLI can be used as a standalone command line utility. Doing so provides a simple way to manage your Auth0 tenant configuration in CI/CD workflows.

For a comprehensive list of configuration settings, please read [Configure the Deploy CLI](/docs/deploy-monitor/deploy-cli-tool/configure-the-deploy-cli).

## export command

Fetching configurations from Auth0 tenant to the local machine.

### `--output_folder`, `-o`

Path. Specifies the target directory for configuration files to be written to.

### `--config_file`, `-c`

Path. Specifies the user-defined configuration file (`config.json`). To learn more, read [Configure the Deploy CLI](/docs/deploy-monitor/deploy-cli-tool/configure-the-deploy-cli).

### `--format`, `-f`

Options: `yaml` or `directory`. Determines the file format of the exported resource configuration files. To learn more, read [Available Resource Configuration Formats](/docs/deploy-monitor/deploy-cli-tool/available-resource-configuration-formats).

### `--export_ids`, `-e`

Boolean. When enabled, will export the identifier fields for each resource. Default: `false`.

### `--env`

Boolean. Indicates if the tool should ingest environment variables or not. Default: `true`.

### `--debug`

Boolean. Enables more verbose error logging; useful during troubleshooting. Default: `false`.

### `--proxy_url`, `-p`

A url for proxying requests. Only set this if you are behind a proxy.

### Examples

#### Fetching Auth0 tenant configuration in the YAML format

`a0deploy export -c=config.json --format=yaml --output_folder=local`

#### Fetching Auth0 tenant configuration in directory (JSON) format

`a0deploy export -c=config.json --format=directory --output_folder=local`

#### Fetching Auth0 tenant configurations with IDs of all assets

`a0deploy export -c=config.json --format=yaml --output_folder=local --export_ids=true`

## import command

Applying configurations from local machine to Auth0 tenant.

### `--input_file`, `-i`

Path. Specifies the location of the resource configuration files. For YAML formats, this will point to the `tenant.yaml` file, for directory formats, this will point to the resource configuration directory.

### `--config_file`, `-c`

Path. Specifies the user-defined configuration file (`config.json`). To learn more, read [Configure the Deploy CLI](/docs/deploy-monitor/deploy-cli-tool/configure-the-deploy-cli).

### `--env`

Boolean. Indicates if the tool should ingest environment variables or not. Default: `true`.

### `--proxy_url`, `-p`

A url for proxying requests. Only set this if you are behind a proxy.

### `--debug`

Boolean. Enables more verbose error logging; useful during troubleshooting. Default: `false`.

### Examples

#### Deploying configuration for YAML formats

`a0deploy import -c=config.json --input_file=local/tenant.yaml`

#### Deploying configuration for directory format

`a0deploy import -c=config.json --input_file=local`

#### Deploying configuration with environment variables ignored

`a0deploy import -c=config.json --input_file=local/tenant.yaml --env=false`


# Use as a Node Module
Source: https://auth0.com/docs/deploy-monitor/deploy-cli-tool/use-as-a-node-module

Learn how to the use the Auth0 Deploy CLI as a node module.

The Deploy CLI can not only be used as a standalone CLI, but as a node module. Doing so allows you to manage Auth0 resources within expressive node scripts.

For a comprehensive list of configuration settings, please read [Configure the Deploy CLI](/docs/deploy-monitor/deploy-cli-tool/configure-the-deploy-cli).

## dump function

Fetches configurations from Auth0 tenant to the local machine.

### Argument parameters

#### format

Options: `yaml` or `directory`. Determines the file format of the exported resource configuration files. To learn more, read [Available Resource Configuration Formats](/docs/deploy-monitor/deploy-cli-tool/available-resource-configuration-formats).

#### output\_folder

Path. Specifies the target directory for configuration files to be written to.

#### config

Object. Configures behavior of utility. To learn more, read [Configure the Deploy CLI](/docs/deploy-monitor/deploy-cli-tool/configure-the-deploy-cli).

#### config\_file

Path. Specifies the user-defined configuration file (`config.json`). To learn more, read [Configure the Deploy CLI](/docs/deploy-monitor/deploy-cli-tool/configure-the-deploy-cli).

#### export\_ids

Boolean. When enabled, will export the identifier fields for each resource. Default: `false`.

#### env

Boolean. Indicates if the tool should ingest environment variables or not. Default: `false`.

#### proxy\_url

A url for proxying requests. Only set this if you are behind a proxy.

### Example

```jsx lines theme={null}
import { dump } from 'auth0-deploy-cli';

dump({
  output_folder: './local',
  format: 'yaml',
  config: {
    AUTH0_DOMAIN: '<YOUR_AUTH0_TENANT_DOMAIN>',
    AUTH0_CLIENT_ID: '<YOUR_AUTH0_CLIENT_ID>',
    AUTH0_CLIENT_SECRET: '<YOUR_AUTH0_CLIENT_SECRET>',
  },
})
  .then(() => {
    console.log('Auth0 configuration export successful');
  })
  .catch((err) => {
    console.log('Error during Auth0 configuration export:', err);
  });
```

## deploy function

Applies configurations from local machine to Auth0 tenant.

### Argument parameters

#### input\_file

Path. Specifies the location of the resource configuration files. For YAML formats, this will point to the `tenant.yaml` file. For directory formats, this will point to the resource configuration directory.

#### config

Object. Configures behavior of utility. To learn more, read [Configure the Deploy CLI](/docs/deploy-monitor/deploy-cli-tool/configure-the-deploy-cli).

#### config\_file

Path. Specifies the user-defined configuration file (`config.json`). To learn more, read [Configure the Deploy CLI](/docs/deploy-monitor/deploy-cli-tool/configure-the-deploy-cli).

#### export\_ids

Boolean. When enabled, will export the identifier fields for each resource. Default: `false`.

#### env

Boolean. Indicates if the tool should ingest environment variables or not. Default: `false`.

#### proxy\_url

A url for proxying requests. Only set this if you are behind a proxy.

### Example

```jsx lines theme={null}
import { deploy } from 'auth0-deploy-cli';

deploy({
  input_file: './local/tenant.yaml',
  config: {
    AUTH0_DOMAIN: '<YOUR_AUTH0_TENANT_DOMAIN>',
    AUTH0_CLIENT_ID: '<YOUR_AUTH0_CLIENT_ID>',
    AUTH0_CLIENT_SECRET: '<YOUR_AUTH0_CLIENT_SECRET>',
  },
})
  .then(() => {
    console.log('Auth0 configuration applied to tenant successful');
  })
  .catch((err) => {
    console.log('Error when applying configuration to Auth0 tenant:', err);
  });
```


# Private Cloud Deployments
Source: https://auth0.com/docs/deploy-monitor/deploy-private-cloud

Describes Auth0 private cloud deployment options.

The Private Cloud packages are managed services that you can use if you:

* Cannot use a multi-tenant Public Cloud service in your organization
* Have geographical deployment requirements where the Public Cloud option isn't feasible
* Require a guaranteed level of requests per second (RPS) or higher capacity than available on Public Cloud

The Auth0 private cloud can be deployed in the following ways:

<table>
  <thead>
    <tr>
      <th><strong>Option</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/deploy-monitor/deploy-private-cloud/private-cloud-on-aws"><strong>Private Cloud on AWS</strong></a></td>
      <td>A dedicated, managed cloud service running on AWS providing isolation, higher performance, dev instances, Geo-HA add-ons and more</td>
    </tr>

    <tr>
      <td><a href="/docs/deploy-monitor/deploy-private-cloud/private-cloud-on-azure"><strong>Private Cloud on Azure</strong></a></td>
      <td>A dedicated cloud service running on Azure providing isolation, higher performance, dev instances, add-ons and more</td>
    </tr>
  </tbody>
</table>

We also provide [add-on features](/docs/deploy-monitor/deploy-private-cloud/private-cloud-add-on-features) that can complement your Auth0 Private Cloud deployment.

If you have specific support requirements or need more information about the Professional Services we offer, please [contact Auth0 Sales](https://auth0.com/contact-us).


# Private Cloud Add-on Features
Source: https://auth0.com/docs/deploy-monitor/deploy-private-cloud/private-cloud-add-on-features

Learn about add-on features that can complement your Auth0 Private Cloud deployment.

The Private Cloud deployment option comes with two additional add-on features: Geo-failover and PCI compliance. If you have any questions about these features, please [contact Auth0 Sales](https://auth0.com/get-started?place=documentation%20post\&type=link\&text=contact%20auth0%20sales).

## Private Cloud Geo-Failover

Geo-failover is an active-passive failover configuration, which allows customers to specify a secondary failover region to use in the event of a major regional outage. In general, any region in the same cloud provider that is within 100ms latency can be selected as a failover region. In some cases, however, cloud providers prefer specific failover regions. The Auth0 onboarding team will work with you to select the best regions for your use case.

Additionally, a third "tie break" region is required for one of our data stores. This third region never receives live traffic but is required to elect a new leader in the event of a failover.

If a regional failure is detected, Geo-failover triggers on the customer's behalf by Auth0. The entire process is automated once triggered. When confirmation the region is no longer experiencing issues is received, Auth0 will failback to the primary region.

## PCI Compliance

PCI Compliance is available as an add-on to customers who require it.


# Private Cloud on AWS
Source: https://auth0.com/docs/deploy-monitor/deploy-private-cloud/private-cloud-on-aws

Learn about the Auth0 identity platform on AWS deployment option and its capabilities.

The Private Cloud on AWS deployment option is a dedicated, managed instance of the Auth0 identity platform running on Amazon Web Services. It provides isolation, higher performance, separate development instances, various add-ons, and more.

## Operational differences

The table below compares each deployment option for Private Cloud on AWS.

<table>
  <thead>
    <tr>
      <th><strong>Feature</strong></th>
      <th><strong>Public Cloud</strong></th>
      <th><strong>Private Cloud Basic on AWS</strong> \*</th>
      <th><strong>Private Cloud Performance on AWS</strong> \*</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Tenancy</td>
      <td>Multi</td>
      <td>Single</td>
      <td>Single</td>
    </tr>

    <tr>
      <td>Requests per second (Multiples of 100 RPS)</td>
      <td>100 RPS (1x)</td>
      <td>100 RPS (1x)</td>
      <td>500\* RPS (5x)<br />1,500\* RPS (15x)<br />3,000\* RPS (30x)<br />3,000\* RPS (30x Burst)<br />6,000\* RPS (60x)<br />6,000\* RPS (60x Burst)<br />10,000\* RPS (100x)</td>
    </tr>

    <tr>
      <td>Service level agreement (SLA)</td>
      <td>99.99%</td>
      <td>99.99%</td>
      <td>99.99%</td>
    </tr>

    <tr>
      <td>Data residency</td>
      <td>Public cloud regions only</td>
      <td>Yes</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>Dev environment</td>
      <td>No</td>
      <td>No</td>
      <td>1</td>
    </tr>
  </tbody>
</table>

\*The RPS capacity is provided as a general guideline. The actual performance could vary based on the types and volume of transactions processed within the customer's Private Cloud environment. The test transactions used for the stated capacity benchmarks might not match individual customer's unique transaction patterns and workloads. As an example, the following capacity is supported when using the [Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow):

<table>
  <thead>
    <tr>
      <th>Tier</th>
      <th>RPS</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Basic</td>
      <td>55</td>
    </tr>

    <tr>
      <td>Performance 5x</td>
      <td>180</td>
    </tr>

    <tr>
      <td>Performance 15x</td>
      <td>600</td>
    </tr>

    <tr>
      <td>Performance 30x</td>
      <td>1400</td>
    </tr>

    <tr>
      <td>Performance 30x Burst</td>
      <td>1400</td>
    </tr>

    <tr>
      <td>Performance 60x</td>
      <td>3000</td>
    </tr>

    <tr>
      <td>Performance 60x Burst</td>
      <td>3000</td>
    </tr>

    <tr>
      <td>Performance 100x</td>
      <td>5000</td>
    </tr>
  </tbody>
</table>

### Data residency

With Private Cloud on AWS, you choose the region where your data is stored. Auth0 can provide a list of available regions that use multiple [availability zones](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/) for the deployment. A list of current regions where we offer private cloud deployments can be found in our Sub-processor Information posted to our [Trust & Compliance page](https://www.okta.com/trustandcompliance/). In most cases, Okta deploys backups in the same selected AWS region.

### Maximum availability

Private Cloud on AWS instances have a 99.99% Service Level Agreement (SLA).  Availability Commitments do not apply to Free Trials, sandbox, beta and other pre-production environments.

### High demand apps

If your application requires a significantly high amount of requests per second (RPS), you may also wish to consider Private Cloud on AWS. See the [rate limits policies](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy) for more information about the standard rate limits. The Private Cloud on AWS deployments have a rate limit of 100 RPS for Private Basic, and enhanced rate limits of 500 RPS, 1,500 RPS, 3,000 RPS, and 6,000 RPS for Private Performance options.

## Additional dev environments

Private Cloud on AWS Performance deployments include a fully-isolated and independently-updated instance for development and testing. You can add additional pre-production environments to meet your business requirements.

Guaranteed requests per second (RPS) and SLA do not apply to non-production environments.

## Limitations

### Data Center Locations

Private Cloud on AWS is fully deployable in the following regions:

* Australia
* Bahrain
* Brazil
* Canada
* France
* Germany
* Hong Kong
* India
* Indonesia
* Ireland
* Italy
* Japan
* Mexico
* Singapore
* South Africa
* South Korea
* Sweden
* United Arab Emirates (UAE)
* United Kingdom
* USA

### Bursty Traffic

Okta provides rate limits for orgs based on the traffic that they expect to have, and subject to the RPS tier purchased. If your org experiences higher traffic than what is expected, this unplanned usage may potentially have an impact on end users.The Private Cloud offering is designed to handle gradual increases in transaction rate (e.g. an increase from 100 RPS to 1000 RPS over a period of 10 minutes) without any service impact. However, sudden and severe bursts in traffic (e.g. 100 RPS to 1000RPS increase in a matter of seconds) could lead to service instability and increased latency while the solution adjusts to handle the new load.

## Onboarding

After choosing Private Cloud on AWS, an onboarding and deployment process will be followed to configure your environment(s).

### Customer onboarding requirements

Upon contract signing, we will ask you to provide key information regarding your onboarding requirements, which we will then validate.

### Kickoff meeting

Once we validate your onboarding requirements, we will host a kickoff meeting with you to begin the implementation process. We strongly recommend that this meeting occur no later than five (5) days after the contract signing.

### Implementation

Immediately after the onboarding form validation, we will begin provisioning your environment.

At the end of this process, you're ready for the environment handover and your Private Cloud on AWS deployment is ready for use.

## Secure Outbound Networking

Some Auth0 platform customizations—[Actions](/docs/customize/actions), [custom webhooks](/docs/customize/log-streams/custom-log-streams), and [custom database action scripts](/docs/authenticate/database-connections/custom-db/templates), for example—let you make outbound connections from the Auth0 platform to your own services. With Private Cloud on AWS, you can establish network connectivity between your Private Cloud deployment and your own services without exposing your data to the Internet.

Secure outbound networking uses AWS PrivateLink. First, you share your service through PrivateLink by [establishing an endpoint service](https://docs.aws.amazon.com/vpc/latest/privatelink/create-endpoint-service.html) in your AWS account. The underlying service can be an AWS-native service or a service running in a data center. The service must be in a VPC in the same AWS region as your Private Cloud deployment.

Next, we will configure your Private Cloud deployment to make your endpoint service available. Once you provide Auth0 with your endpoint service information, we will integrate the service with your deployment and provide information on how to access it from your customization code.

For more info on setting up endpoint services with PrivateLink, contact AWS. To coordinate service onboarding with Auth0, file a request to the [Support Center](https://support.auth0.com/).

## Updates

Private Cloud on AWS deployments are updated every week automatically. You can set a specific day and time during the week, if required.

## Testing

### Change freeze policy

<Warning>
  Load tests and penetration tests are not allowed during change freeze periods.
</Warning>

To view the currently scheduled change freeze periods, read [Change Freeze Policy](/docs/troubleshoot/customer-support/operational-policies/change-freeze-policy).

### Load testing

This policy outlines the necessary requirements for Auth0 to perform load testing for Private Cloud on AWS customers who submit a request. You can file a load testing request via the [Support Center](https://support.auth0.com/). Under the **Issue** field, select **Private Cloud Support Incident**.

If you purchased a dedicated load testing environment, there is no limit to the frequency of load tests you can run. Standard environments are limited to two (2) per year, given proper load testing procedures.

To be considered for approval, the request must:

* Be filed at least two (2) weeks prior to the desired test date; in many cases, Auth0 encourages one (1) month of advance notice to ensure time for a thorough review and any required modifications.
* Receive approval in writing before any testing is conducted.
* Stay within our [published production rate limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy).

If changes to infrastructure are requested, the cost will be determined based on your specific requirements.

#### Testing capacity considerations

<Callout icon="file-lines">
  Environments purchased for dedicated load testing are not subject to any service level agreements. Issues reported in these environments will be prioritized lower than production issues.
</Callout>

You should start with a low load and slowly increase until the environment has reached its peak. Should you require a load greater than what the environment can handle, the environment size should be increased.

Private Cloud environments can be upsized via contract addendum; please contact your Account Executive and TAM to discuss this purchase.

<table>
  <thead>
    <tr>
      <th>Subscription</th>
      <th>Load Test Capacity</th>
      <th>Ramp up</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Private Cloud Performance 500 RPS (5x)</td>
      <td>325 RPS</td>
      <td>100 RPS/min</td>
    </tr>

    <tr>
      <td>Private Cloud Performance 1500 RPS (15x)</td>
      <td>975 RPS</td>
      <td>100 RPS/min</td>
    </tr>

    <tr>
      <td>Private Cloud Performance 3000 RPS (30x)</td>
      <td>1950 RPS</td>
      <td>100 RPS/min</td>
    </tr>

    <tr>
      <td>Private Cloud Performance 3000 RPS  (30x Burst)</td>
      <td>1950 RPS</td>
      <td>100 RPS/min</td>
    </tr>

    <tr>
      <td>Private Cloud Performance 6000 RPS (60x)</td>
      <td>3900 RPS</td>
      <td>100 RPS/min</td>
    </tr>

    <tr>
      <td>Private Cloud Performance 6000 RPS (60x Burst)</td>
      <td>3900 RPS</td>
      <td>100 RPS/min</td>
    </tr>

    <tr>
      <td>Private Cloud Performance 10,000 RPS (100x)</td>
      <td>6500 RPS</td>
      <td>100 RPS/sec</td>
    </tr>
  </tbody>
</table>

For more information on load testing in Private Cloud, see [Environment request limits (Private Cloud Only)](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#environment-request-limits-private-cloud-only-).

#### High load notifications

For periods of anticipated high load, you must inform your account team no later than 14 days prior to the event. The notification provides the opportunity to adequately test scenarios (if possible) and aligns reactive support to the event.

### Penetration testing

To conduct a security test, please notify us in advance via the Auth0 Support Center. Auth0 requires at least one week (seven days) notice prior to your test's planned start date.

If the test is isolated to your infrastructure (that is, there will be no testing of Auth0 services), you do not need to notify Auth0.

For the information that we require, see our [Penetration Testing Policy](/docs/troubleshoot/customer-support/operational-policies/penetration-testing-policy).

### Failover testing

This policy outlines the necessary requirements for Okta to perform failover testing for Private Cloud customers on either the AWS or Azure Auth0 platform with the required Geo Failover add-on. You may file a failover testing request via the [Support Center.](https://support.auth0.com/) Under the Issue field, select Private Cloud Support Incident.

To be considered for approval, the request must:

* Be filed at least two (2) weeks prior to the desired test date and time (in UTC). In many cases, Okta encourages one (1) month of advance notice to ensure time for a thorough review and any required modifications.
* Fall under the limit of (2) failover tests per calendar year.
* Receive approval in writing before any testing is conducted.
* Specify windows (in UTC)  for both the failover and the fallback to the primary region, with an understanding that both windows will result in downtime of up to 15 minutes.
* Designated point-of-contact specified with whom Okta will coordinate all testing logistics

Please note that Okta reserves the right to suggest alternative windows for the failover and fallback to correspond to availability of Staff to perform the requested testing. Additionally, any service interruption that results as part of the failover or fallback procedures is exempt of any SLA provisions.

## Certificate renewal process

Auth0-managed certificates (in the format \*.auth0app.com) are the responsibility of Auth0 to both obtain and apply. Auth0 will manage the process end-to-end and will prompt you with any action required.

Renewal of Auth0-issued certificates for <Tooltip href="/docs/glossary?term=custom+domains">custom domains</Tooltip> is managed by Auth0.

Renewal of customer-managed certificates for [custom domains](/docs/customize/custom-domains) (in the format \*.\<CustomerName>.com) is the customer’s responsibility to manage and obtain.

## Reporting and monitoring

Auth0 provides logs that are accessible via the Dashboard or the [log streaming endpoint](/docs/customize/log-streams).

## Support

You can reach out to the Auth0 [Support](https://support.auth0.com/) team with any questions or concerns you might have. To help expedite your request, please provide as much information as possible in the [Support ticket you open](/docs/troubleshoot/customer-support/open-and-manage-support-tickets).


# Private Cloud on Azure
Source: https://auth0.com/docs/deploy-monitor/deploy-private-cloud/private-cloud-on-azure

Learn about the Auth0 identity platform on Azure deployment option and its capabilities.

The Private Cloud on Azure deployment option is a dedicated, managed instance of the Auth0 identity platform running on Microsoft Azure. It provides isolation, higher performance, separate development instances, various add-ons, and more.

## Operational differences

The table below compares each deployment option for Private Cloud on Azure.

<table>
  <thead>
    <tr>
      <th><strong>Feature</strong></th>
      <th><strong>Public Cloud</strong></th>
      <th><strong>Private Cloud on Azure Basic</strong> \*</th>
      <th><strong>Private Cloud on Azure Performance</strong> \*</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Tenancy</td>
      <td>Multi</td>
      <td>Single</td>
      <td>Single</td>
    </tr>

    <tr>
      <td>Requests per second (RPS)</td>
      <td>100</td>
      <td>100</td>
      <td>500\* RPS (5x)   <br />1500\* RPS (15x) <br />3000\* RPS (30x)<br /> <br />3000\* RPS (30x Burst)<br /></td>
    </tr>

    <tr>
      <td>Service level agreement (SLA)</td>
      <td>99.99%</td>
      <td>99.99%</td>
      <td>99.99%</td>
    </tr>

    <tr>
      <td>Data residency</td>
      <td>Public cloud regions only</td>
      <td>Yes</td>
      <td>Yes</td>
    </tr>

    <tr>
      <td>Dev environment</td>
      <td>No</td>
      <td>No</td>
      <td>1</td>
    </tr>
  </tbody>
</table>

\*The requests per second (RPS) capacity is provided as a general guideline. The actual performance could vary based on the types and volume of transactions processed within the customer's Private Cloud environment. The test transactions used for the stated capacity benchmarks might not match individual customer's unique transaction patterns and workloads. As an example, the following capacity is supported when using the [Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow):

<table>
  <thead>
    <tr>
      <th>Tier</th>
      <th>RPS</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Basic</td>
      <td>55</td>
    </tr>

    <tr>
      <td>Performance 5x</td>
      <td>180</td>
    </tr>

    <tr>
      <td>Performance 15x</td>
      <td>600</td>
    </tr>

    <tr>
      <td>Performance 30x</td>
      <td>1400</td>
    </tr>

    <tr>
      <td>Performance 30x Burst</td>
      <td>1400</td>
    </tr>
  </tbody>
</table>

### Data residency

With Private Cloud on Azure, you choose the region where your data is stored. Auth0 can provide a list of available regions that use three [availability zones](https://azure.microsoft.com/en-us/global-infrastructure/geographies/) for the deployment. A list of current regions where we offer private cloud deployments can be found in our Sub-processor Information posted to our [Trust & Compliance page](https://www.okta.com/trustandcompliance/). In most cases, Okta deploys backups in the same selected Azure region.

### Maximum availability

Private Cloud on Azure instances have a 99.99% service level agreement (SLA).  Availability Commitments do not apply to Free Trials, sandbox, beta and other pre-production environments.

## Additional dev environments

Private Cloud on Azure Performance deployments include a fully-isolated and independently-updated instance for development and testing. You can add additional pre-production environments to meet your business requirements.

Guaranteed requests per second (RPS) and SLA do not apply to non-production environments.

## Limitations

### Data Center Locations

Private Cloud on Azure is fully deployable in the following regions:

* Australia
* Brazil
* Canada
* France
* Germany
* India
* Ireland
* Japan
* Netherlands
* Norway
* South Africa
* South Korea
* Sweden
* Switzerland
* United Arab Emirates
* United Kingdom
* USA

### Bursty Traffic

Okta provides rate limits for orgs based on the traffic that they expect to have, and subject to the RPS tier purchased. If your org experiences higher traffic than what is expected, this unplanned usage may potentially have an impact on end users. The Private Cloud offering is designed to handle gradual increases in transaction rate (e.g. an increase from 100 RPS to 1000 RPS over a period of 10 minutes) without any service impact. However, sudden and severe bursts in traffic (e.g. 100 RPS to 1000RPS increase in a matter of seconds) could lead to service instability and (increased latency) while the solution adjusts to handle the new load.

## Onboarding

After choosing Private Cloud on Azure, an onboarding and deployment process will be followed to configure your environment(s).

### Customer onboarding requirements

Upon contract signing, we will ask you to provide key information regarding your onboarding requirements, which we will then validate.

### Kickoff meeting

Once we validate your onboarding requirements, we will host a kickoff meeting with you to begin the implementation process. We strongly recommend that this meeting occur no later than five (5) days after the contract signing.

### Implementation

Immediately after the onboarding form validation, we will begin provisioning your environment.

At the end of this process, you're ready for the environment handover and your Private Cloud on Azure deployment is ready for use.

## Secure Outbound Networking

Some Auth0 platform customizations, including [Actions](/docs/customize/actions), [custom webhooks](/docs/customize/log-streams/custom-log-streams), and [custom database action scripts](/docs/authenticate/database-connections/custom-db/templates), allow secure outbound connections from the Auth0 platform to your own services and establish network connectivity between your Private Cloud deployment and your own services.

Secure outbound networking uses Azure Private Link by [establishing an endpoint service](https://learn.microsoft.com/en-us/azure/private-link/private-link-service-overview) in your Azure account. The underlying service can be an Azure-native service or a service running in a data center and must be in an Azure Virtual Network in the same Azure region as your Private Cloud deployment.

After you configure your Private Cloud deployment to make your endpoint service available, provide Auth0 with your endpoint service information so we can integrate the service with your deployment and provide information on how to access it from your customization code.

For more info on setting up endpoint services with Private Link, contact Azure. To coordinate service onboarding with Auth0, contact Auth0's [Support Center](https://support.auth0.com/).

## Updates

Private Cloud on Azure deployments are updated every week automatically. You can set a specific day and time during the week, if required.

## Testing

### Change freeze policy

<Warning>
  Load tests and penetration tests are not allowed during change freeze periods.
</Warning>

To view the currently scheduled change freeze periods, read [Change Freeze Policy](/docs/troubleshoot/customer-support/operational-policies/change-freeze-policy).

### Load testing

This policy outlines the necessary requirements for Auth0 to perform load testing for Private Cloud on Azure customers who submit a request. You can file a load testing request via the [Support Center](https://support.auth0.com/). Under the Issue field, select **Private Cloud Support Incident**.

If you purchased a dedicated load testing environment, there is no limit to the frequency of load tests you can run. Standard environments are limited to two (2) per year, given proper load testing procedures.

To be considered for approval, the request must:

* Be filed at least two (2) weeks prior to the desired test date; in many cases, Auth0 encourages one (1) month of advance notice to ensure time for a thorough review and any required modifications.
* Receive approval in writing before any testing is conducted.
* Stay within our [published production rate limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy).

If changes to infrastructure are requested, the cost will be determined based on your specific requirements.

#### Testing capacity considerations

<Callout icon="file-lines">
  Environments purchased for dedicated load testing are not subject to any service level agreements. Issues reported in these environments will be prioritized lower than production issues.
</Callout>

You should start with a low load and slowly increase until the environment has reached its peak. Should you require a load greater than what the environment can handle, the environment size should be increased.

Private Cloud environments can be upsized via contract addendum; please contact your Account Executive and TAM to discuss this purchase.

<table>
  <thead>
    <tr>
      <th>Subscription</th>
      <th>Load Test Capacity</th>
      <th>Ramp up</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Private Cloud Performance 500 RPS (5x)</td>
      <td>325 RPS</td>
      <td>100 RPS/min</td>
    </tr>

    <tr>
      <td>Private Cloud Performance 1500 RPS (15x)</td>
      <td>975 RPS</td>
      <td>100 RPS/min</td>
    </tr>

    <tr>
      <td>Private Cloud Performance 3000 RPS (30x)</td>
      <td>1950 RPS</td>
      <td>100 RPS/min</td>
    </tr>

    <tr>
      <td>Private Cloud Performance 3000 RPS (30x Burst)</td>
      <td>1950 RPS</td>
      <td>100 RPS/min</td>
    </tr>
  </tbody>
</table>

For more information on load testing in Private Cloud, see [Environment request limits (Private Cloud Only)](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#environment-request-limits-private-cloud-only-).

#### High load notifications

For periods of anticipated high load, you must inform your account team no later than 14 days prior to the event. The notification provides the opportunity to adequately test scenarios (if possible) and aligns reactive support to the event.

### Penetration testing

To conduct a security test, please notify us in advance via the Auth0 Support Center. Auth0 requires at least one week (seven days) notice prior to your test's planned start date.

If the test is isolated to your infrastructure (that is, there will be no testing of Auth0 services), you do not need to notify Auth0.

For the information that we require, see our [Penetration Testing Policy](/docs/troubleshoot/customer-support/operational-policies/penetration-testing-policy).

### Failover testing

This policy outlines the necessary requirements for Okta to perform failover testing for Private Cloud customers on either the AWS or Azure Auth0 platform with the required Geo Failover add-on. You may file a failover testing request via the [Support Center.](https://support.auth0.com/) Under the Issue field, select Private Cloud Support Incident.

To be considered for approval, the request must:

* Be filed at least two (2) weeks prior to the desired test date and time (in UTC). In many cases, Okta encourages one (1) month of advance notice to ensure time for a thorough review and any required modifications.
* Fall under the limit of (2) failover tests per calendar year.
* Receive approval in writing before any testing is conducted.
* Specify windows (in UTC)  for both the failover and the fallback to the primary region, with an understanding that both windows will result in downtime of up to 15 minutes.
* Designated point-of-contact specified with whom Okta will coordinate all testing logistics

Please note that Okta reserves the right to suggest alternative windows for the failover and fallback to correspond to availability of Staff to perform the requested testing. Additionally, any service interruption that results as part of the failover or fallback procedures is exempt of any SLA provisions.

## Certificate renewal process

Auth0-managed certificates (in the format \*.auth0app.com) are the responsibility of Auth0 to both obtain and apply. Auth0 will manage the process end-to-end and will prompt you with any action required.

Renewal of Auth0-issued certificates for <Tooltip href="/docs/glossary?term=custom+domains">custom domains</Tooltip> is managed by Auth0.

Renewal of customer-managed certificates for [custom domains](/docs/customize/custom-domains) (in the format \*.\<CustomerName>.com) is the customer’s responsibility to manage and obtain.

## Reporting and monitoring

Auth0 provides logs that are accessible via the Dashboard or the [log streaming endpoint](/docs/customize/log-streams).

## Support

You can reach out to the Auth0 [Support](https://support.auth0.com/) team with any questions or concerns you might have. To help expedite your request, please provide as much information as possible in the [Support ticket you open](/docs/troubleshoot/customer-support/open-and-manage-support-tickets).


# Deployment Best Practices
Source: https://auth0.com/docs/deploy-monitor/deployment-best-practices

Learn about best practices for deployment.

## Use automated deployment for Actions

Coding an Action within the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> editor is a great way to implement and test while still in the development stage. However, when it comes time to deploy into automated test or production environments, a more automated mechanism is required; copying and pasting code between Auth0 tenants is not a satisfactory method.

### Set up version control for Actions

Changes made to an Action in the Auth0 Dashboard are saved as drafts until they are deployed. After deploying, a version is created, but you must attach the Action to a trigger for it to activate. We recommend using version control to provide change management and code review capabilities. [Actions support versioning](docs/customize/actions/manage-versions) natively in the Dashboard.

Auth0 provides automated deployment methods for Actions between Auth0 tenant environments. The following Auth0 integrations allow you to update Actions from the version control system—both manually and automatically (for example, when a change in the version control system is detected): [GitHub Actions](https://marketplace.auth0.com/integrations/github-actions), [GitLab Pipelines](https://marketplace.auth0.com/integrations/gitlab-pipeline), [Bitbucket Pipelines](https://marketplace.auth0.com/integrations/bitbucket-pipeline), and [Microsoft Azure Pipelines](https://marketplace.auth0.com/integrations/azure-pipeline).

### Use Deploy CLI tool for Action import and export

The Auth0 Deploy CLI tool automates the deployment of Actions between Auth0 tenants. It works with local YAML or directory-based files together with the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> and provides the capability to allow the export of Actions from an Auth0 tenant, as well as import of them into an Auth0 tenant. Further, the tool provides programmatic control over the ordering and environment configuration of an Action as part of deployment automation. To learn more, read [Deploy CLI Tool](/docs/deploy-monitor/deploy-cli-tool).

As a best practice, use the Auth0 Deploy CLI in almost all cases involving deployment to test or production environments. While Marketplace integrations provide automated detection of changes, the Deploy CLI allows precise control over what is deployed, when, and how.

## Set up test tenants

We recommend that you set up a separate test tenant in Auth0 to provide safe testing of any Actions before deploying to production. To learn more, read [Set Up Multiple Environments](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments).


# Deployment Options
Source: https://auth0.com/docs/deploy-monitor/deployment-options

Describes Auth0 public and private cloud deployment options.

Auth0 provides both public cloud and private cloud deployment options and tools to help you with your Enterprise deployment.

The Auth0 identity platform can be deployed in the following ways:

<table>
  <thead>
    <tr>
      <th><strong>Option</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Public Cloud</strong></td>
      <td>A multi-tenant cloud service running on Auth0's cloud with standard authentication, personalization, user management, and security features</td>
    </tr>

    <tr>
      <td><a href="/docs/deploy-monitor/deploy-private-cloud/private-cloud-on-aws"><strong>Private Cloud on AWS</strong></a></td>
      <td>A dedicated, managed cloud service running on AWS providing isolation, higher performance, dev instances, Geo-HA add-ons and more</td>
    </tr>

    <tr>
      <td><a href="/docs/deploy-monitor/deploy-private-cloud/private-cloud-on-azure"><strong>Private Cloud on Azure</strong></a></td>
      <td>A dedicated cloud service running on Azure providing isolation, higher performance, dev instances, Geo-HA add-ons and more</td>
    </tr>
  </tbody>
</table>

The **Private Cloud** packages are managed services that you can use if you:

* Cannot use a multi-tenant public cloud service in your organization
* Require a guaranteed level of requests per second (RPS)

If you have specific support requirements or need more information about the Professional Services we offer, please [contact Auth0 Sales](https://auth0.com/contact-us).


# Logs
Source: https://auth0.com/docs/deploy-monitor/logs

Understand how tenant and operations event logs work in Auth0.

Auth0 provides logs that you can analyze for your business needs. You can:

* View actions performed by tenant administrators.
* View operations performed via the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.
* View authentications made by your users.
* View intermittent errors that may be hard to find with quality assurance testing.
* Capture forensic data for security purposes and to identify anomaly detection triggers.
* Identify patterns in usage trends.
* Check for authentication errors and Management API call errors.
* Set up automatic log scanning to check for rate limit errors so that you can proactively address activity that hits rate limits before it impacts your users.
* Correlate management API events to their initiating requests by matching `X-Correlation-ID` header values.

## View and retrieve logs

View logs in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> and retrieve logs using the Management API. To learn more, read:

* [View Log Events](/docs/deploy-monitor/logs/view-log-events)
* [Retrieve Log Events Using the Management API](/docs/deploy-monitor/logs/retrieve-log-events-using-mgmt-api)

Auth0 provides a wide variety of log types and well as filtering to allow you to find the specific events to suit your tracking and analysis needs. To learn more, read:

* [Personally Identifiable Information in Auth0 Logs](/docs/deploy-monitor/logs/pii-in-logs)
* [Log Data Retention](/docs/deploy-monitor/logs/log-data-retention)
* [Log Event Type Codes](/docs/deploy-monitor/logs/log-event-type-codes)
* [Adaptive MFA Log Events](/docs/secure/multi-factor-authentication/adaptive-mfa/adaptive-mfa-log-events)
* [Attack Protection Events](/docs/secure/attack-protection/view-attack-protection-events)
* [Log Search Query Syntax](/docs/deploy-monitor/logs/log-search-query-syntax)
* [Log Event Filters](/docs/deploy-monitor/logs/log-event-filters)

## Log streaming and exporting

Use log streaming to export logs to your preferred processing and analysis tools. We provide integrations with several analysis services as well as a way to create a custom log stream using webhooks. To learn more, read [Log Streaming](/docs/customize/log-streams).


# Log Data Retention
Source: https://auth0.com/docs/deploy-monitor/logs/log-data-retention

Describes how long log data is stored depending on your Auth0 plan.

Your Auth0 log retention period depends on your subscription level.

<table>
  <thead>
    <tr>
      <th><strong>Plan</strong></th>
      <th><strong>Log Retention</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Starter</td>
      <td>1 day</td>
    </tr>

    <tr>
      <td>B2C Essentials</td>
      <td>5 days</td>
    </tr>

    <tr>
      <td>B2C Professional</td>
      <td>10 days</td>
    </tr>

    <tr>
      <td>B2B Essentials</td>
      <td>5 days</td>
    </tr>

    <tr>
      <td>B2B Professional</td>
      <td>10 days</td>
    </tr>

    <tr>
      <td>Enterprise</td>
      <td>30 days</td>
    </tr>
  </tbody>
</table>

[Auth0 Support](https://support.auth0.com) can help you integrate with external logging services if you need to retain logs beyond your retention time. This approach is also useful for aggregating logs across your organization.

<Callout icon="file-lines">
  Auth0 does not provide real-time logs for your tenant. While we do our best to index events as they arrive, you may see some delays.
</Callout>

In addition, you can use Auth0 log streaming to export log data. To learn more, navigate to [Log Streaming](https://marketplace.auth0.com/features/log-streaming) in Auth0 Marketplace.

## Learn more

* [Log Streams](/docs/customize/log-streams)


# Filter Log Events
Source: https://auth0.com/docs/deploy-monitor/logs/log-event-filters

Lists the log filters for errors, warnings, and success events.

You can filter logs for errors, warnings, and success events in the [Dashboard](https://manage.auth0.com/#/logs) when you click the **Filter** down arrow.

## Error event filters

<table>
  <thead>
    <tr>
      <th>Filter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Block Account</td>
      <td>IP blocked for >10 failed attempts to login to single account</td>
    </tr>

    <tr>
      <td>Blocked IP Address</td>
      <td>IP blocked for >100 failed login attempts or >50 signup attempts</td>
    </tr>

    <tr>
      <td>Breached password</td>
      <td>Attempted login with a leaked password</td>
    </tr>

    <tr>
      <td>Device Confirmation Canceled by User</td>
      <td>User did not confirm device</td>
    </tr>

    <tr>
      <td>Error sending MFA Push Notification</td>
      <td>Push notification for MFA failed</td>
    </tr>

    <tr>
      <td>Error sending MFA SMS</td>
      <td>SMS for MFA failed</td>
    </tr>

    <tr>
      <td>Failed API Operation</td>
      <td>Operation on API failed</td>
    </tr>

    <tr>
      <td>Failed Change Email</td>
      <td>Failed to change user email</td>
    </tr>

    <tr>
      <td>Failed Change Password</td>
      <td>Failed to change user password</td>
    </tr>

    <tr>
      <td>Failed Change Password Request</td>
      <td>Change password request failed</td>
    </tr>

    <tr>
      <td>Failed Change Phone Number</td>
      <td>Failed to change user phone number</td>
    </tr>

    <tr>
      <td>Failed Change Username</td>
      <td>Failed to change username</td>
    </tr>

    <tr>
      <td>Failed Connector Provisioning</td>
      <td>Failed to provision a AD/LDAP connector</td>
    </tr>

    <tr>
      <td>Failed Delegation</td>
      <td>Failed to generate delegation token</td>
    </tr>

    <tr>
      <td>Failed Exchange</td>
      <td>Token Exchange</td>
    </tr>

    <tr>
      <td>Failed Exchange</td>
      <td>Native Socal Login</td>
    </tr>

    <tr>
      <td>Failed Exchange</td>
      <td>Authorization Code for Access Token</td>
    </tr>

    <tr>
      <td>Failed Exchange</td>
      <td>Client Credentials for Access Token</td>
    </tr>

    <tr>
      <td>Failed Exchange</td>
      <td>Password for Access Token</td>
    </tr>

    <tr>
      <td>Failed Exchange</td>
      <td>Refresh Token for Access Token</td>
    </tr>

    <tr>
      <td>Failed Exchange</td>
      <td>Password and OOB Challenge for Access Token</td>
    </tr>

    <tr>
      <td>Failed Exchange</td>
      <td>Password and OTP Challenge for Access Token</td>
    </tr>

    <tr>
      <td>Failed Exchange</td>
      <td>Password and MFA Recovery code for Access Token</td>
    </tr>

    <tr>
      <td>Failed Exchange</td>
      <td>Device Code for Access Token</td>
    </tr>

    <tr>
      <td>Failed Login</td>
      <td>User failed to login</td>
    </tr>

    <tr>
      <td>Failed Login (invalid email/username)</td>
      <td>User failed to login due to invalid username</td>
    </tr>

    <tr>
      <td>Failed Login (wrong password)</td>
      <td>User failed to login due to invalid password</td>
    </tr>

    <tr>
      <td>Failed Logout</td>
      <td>User logout failed</td>
    </tr>

    <tr>
      <td>Failed OIDC Back-Channel Logout Request</td>
      <td>Back-Channel Logout request failed</td>
    </tr>

    <tr>
      <td>Failed Post Change Password Hook</td>
      <td>Post-change password hook failed</td>
    </tr>

    <tr>
      <td>Failed Post User Registration Hook</td>
      <td>Post user registration hook failed</td>
    </tr>

    <tr>
      <td>Failed Sending Notification</td>
      <td>Failed to send email notification</td>
    </tr>

    <tr>
      <td>Failed Signup</td>
      <td>Sign up failed</td>
    </tr>

    <tr>
      <td>Failed Silent Auth</td>
      <td>Silent authentication failed</td>
    </tr>

    <tr>
      <td>Failed User Deletion</td>
      <td>User deletion failed</td>
    </tr>

    <tr>
      <td>Failed Verification Email</td>
      <td>Failed to send verification email</td>
    </tr>

    <tr>
      <td>Failed Verification Email Request</td>
      <td>Failed to process verification email request</td>
    </tr>

    <tr>
      <td>Failed CORS</td>
      <td>Origin is not in the Allowed Origins list for the specified application</td>
    </tr>

    <tr>
      <td>Failed by Connector</td>
      <td>AD/LDAP Connector Failure</td>
    </tr>

    <tr>
      <td>Failed cross origin authentication</td>
      <td>Cross-origin authentication failed</td>
    </tr>

    <tr>
      <td>Failed device activation</td>
      <td>Failed to activate device</td>
    </tr>

    <tr>
      <td>Failed device authorization request</td>
      <td>Device authorization request failed</td>
    </tr>

    <tr>
      <td>MFA Enrollment start failed</td>
      <td>Multi-factor authentication enroll failed</td>
    </tr>

    <tr>
      <td>OTP Auth failed</td>
      <td>One-time password authentication failed</td>
    </tr>

    <tr>
      <td>OTP Auth rejected</td>
      <td>One-time password authentication rejected</td>
    </tr>

    <tr>
      <td>Rate Limit on API</td>
      <td>Maximum number of requests to the Authentication API in given time has been reached</td>
    </tr>

    <tr>
      <td>Recovery failed</td>
      <td>Multi-factor recovery code failed</td>
    </tr>

    <tr>
      <td>Second factor email failed</td>
      <td>Email for MFA failed</td>
    </tr>

    <tr>
      <td>Too Many Calls to /delegation</td>
      <td>Rate limt exceeded to /delegation endpoint</td>
    </tr>

    <tr>
      <td>Too Many Calls to /userinfo</td>
      <td>Rate limit exceeded to /userinfo endpoint</td>
    </tr>

    <tr>
      <td>Too Many Invalid Device Codes</td>
      <td>Rate limit exceeded for invalid device codes</td>
    </tr>
  </tbody>
</table>

## Warning event filters

<table>
  <thead>
    <tr>
      <th>Filter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Deprecation Notice</td>
      <td>Feature is deprecated</td>
    </tr>

    <tr>
      <td>Too many failures</td>
      <td>Multi-factor OTP has failed too many times</td>
    </tr>

    <tr>
      <td>Too many failures</td>
      <td>Mutli-factor recovery code has failed too many times</td>
    </tr>

    <tr>
      <td>Users import</td>
      <td>Failed to import users</td>
    </tr>

    <tr>
      <td>Warning During Login</td>
      <td>Warnings during login</td>
    </tr>
  </tbody>
</table>

## Success event filters

<table>
  <thead>
    <tr>
      <th>Filter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>API Operation</td>
      <td>API operation completed successfully</td>
    </tr>

    <tr>
      <td>API Read Operation</td>
      <td>API GET operation returning secrets completed successfully</td>
    </tr>

    <tr>
      <td>Account unblocked</td>
      <td>User block setup by anomay detection has been released</td>
    </tr>

    <tr>
      <td>Auth0 OS Update Ended</td>
      <td>Auth0 OS update ended</td>
    </tr>

    <tr>
      <td>Auth0 OS Update Started</td>
      <td>Auth0 OS update started</td>
    </tr>

    <tr>
      <td>Auth0 Update Ended</td>
      <td>Auth0 update ended</td>
    </tr>

    <tr>
      <td>Auth0 Update Launched</td>
      <td>New version of Auth0 released</td>
    </tr>

    <tr>
      <td>Auth0 Update Started</td>
      <td>Auth0 update started</td>
    </tr>

    <tr>
      <td>Code Sent</td>
      <td>Passwordess login code has been sent</td>
    </tr>

    <tr>
      <td>Code/Link Sent</td>
      <td>Passwordless lgoin code/link has been sent</td>
    </tr>

    <tr>
      <td>Configuration read</td>
      <td>PSaaS configuration has been read</td>
    </tr>

    <tr>
      <td>Configuration status checked</td>
      <td>PSaaS configuration's status has been checked</td>
    </tr>

    <tr>
      <td>Configuration updated</td>
      <td>PSaaS configuration has been updated</td>
    </tr>

    <tr>
      <td>Enrollment started</td>
      <td>Multi-factor authentication enrollment has started</td>
    </tr>

    <tr>
      <td>MFA enrollment complete</td>
      <td>Multi-factor authentication enrollment has completed</td>
    </tr>

    <tr>
      <td>MFA settings update</td>
      <td>Multi-factor tenant settings updated</td>
    </tr>

    <tr>
      <td>Module switch</td>
      <td>Multi-factor module switched</td>
    </tr>

    <tr>
      <td>OTP Auth Succeed</td>
      <td>One-time password authentication success</td>
    </tr>

    <tr>
      <td>Push notification sent</td>
      <td>Push notification for MFA successfully sent</td>
    </tr>

    <tr>
      <td>Recovery succeed</td>
      <td>Multi-factor recovery code succeeded authorization</td>
    </tr>

    <tr>
      <td>SMS Sent</td>
      <td>SMS for MFA sent successfully sent</td>
    </tr>

    <tr>
      <td>Second factor email sent</td>
      <td>Email for MFA successfully sent</td>
    </tr>

    <tr>
      <td>Second factor started</td>
      <td>Second factor authentication event started for MFA</td>
    </tr>

    <tr>
      <td>Success Change Email</td>
      <td>Email changed successfully</td>
    </tr>

    <tr>
      <td>Success Change Password</td>
      <td>Password changed successfully</td>
    </tr>

    <tr>
      <td>Success Change Password Request</td>
      <td>Change password request succeeded</td>
    </tr>

    <tr>
      <td>Success Change Phone Number</td>
      <td>Phone number changed successfully</td>
    </tr>

    <tr>
      <td>Success Change Username</td>
      <td>Username changed successfully</td>
    </tr>

    <tr>
      <td>Success Delegation</td>
      <td>Delegation token generated successfully</td>
    </tr>

    <tr>
      <td>Success Exchange</td>
      <td>Authorization Code for Access Token</td>
    </tr>

    <tr>
      <td>Success Exchange</td>
      <td>Client Credentials for Access Token</td>
    </tr>

    <tr>
      <td>Success Exchange</td>
      <td>Password for Access Token</td>
    </tr>

    <tr>
      <td>Success Exchange</td>
      <td>Refresh Token for Access Token</td>
    </tr>

    <tr>
      <td>Success Exchange</td>
      <td>Token Exchange</td>
    </tr>

    <tr>
      <td>Success Exchange</td>
      <td>Native Social Login</td>
    </tr>

    <tr>
      <td>Success Exchange</td>
      <td>Password and OOB Challenge for Access Token</td>
    </tr>

    <tr>
      <td>Success Exchange</td>
      <td>Password and OTP Challenge for Access Token</td>
    </tr>

    <tr>
      <td>Success Exchange</td>
      <td>Password and MFA Recovery code for Access Token</td>
    </tr>

    <tr>
      <td>Success Exchange</td>
      <td>Device Code for Access Token</td>
    </tr>

    <tr>
      <td>Success Login</td>
      <td>Successful Login</td>
    </tr>

    <tr>
      <td>Success Logout</td>
      <td>User successfully logged out</td>
    </tr>

    <tr>
      <td>Successful OIDC Back-Channel Logout request</td>
      <td>OIDC Back-Channel Logout request completed successfully</td>
    </tr>

    <tr>
      <td>Success Post Change Password Hook</td>
      <td>Post-change password hook ran successfully</td>
    </tr>

    <tr>
      <td>Success Signup</td>
      <td>Successful signup</td>
    </tr>

    <tr>
      <td>Success Silent Auth</td>
      <td>Successful silent authentication</td>
    </tr>

    <tr>
      <td>Success Verification Email</td>
      <td>Successful verification email</td>
    </tr>

    <tr>
      <td>Success Verification Email Request</td>
      <td>Successful verification email request</td>
    </tr>

    <tr>
      <td>Success cross origin authentication</td>
      <td>Successful cross-origin authentication</td>
    </tr>

    <tr>
      <td>Successful User Deletion</td>
      <td>User successfully deleted</td>
    </tr>

    <tr>
      <td>Unenroll device account</td>
      <td>Device used for second factor authentication has been unenrolled</td>
    </tr>

    <tr>
      <td>Update device account</td>
      <td>Device used for second factor authentication has been updated</td>
    </tr>

    <tr>
      <td>User delete</td>
      <td>Deleted multi-factor user account</td>
    </tr>

    <tr>
      <td>Users import</td>
      <td>Successfully imported users</td>
    </tr>
  </tbody>
</table>

## Learn more

* [View Logs](/docs/deploy-monitor/logs/view-log-events)
* [Retrieve Log Logs Using the Management API](/docs/deploy-monitor/logs/retrieve-log-events-using-mgmt-api)
* [Log Type Codes](/docs/deploy-monitor/logs/log-event-type-codes)
* [Log Search Query Syntax](/docs/deploy-monitor/logs/log-search-query-syntax)
* [Log Streams](/docs/customize/log-streams)


# Log Type Codes
Source: https://auth0.com/docs/deploy-monitor/logs/log-event-type-codes

Lists the event codes associated with log events.

The following table lists the codes associated with each tenant log. If you want to learn more about log event schemas, you can reference our [GitHub repo](https://github.com/auth0/auth0-log-schemas).

<table>
  <thead>
    <tr>
      <th><strong>Event Code</strong></th>
      <th><strong>Event</strong></th>
      <th><strong>Event Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>acls\_summary</code></td>
      <td>Network ACLs Summary</td>
      <td>Shows the summary of the network ACLs matches for a period of time</td>
    </tr>

    <tr>
      <td><code>actions\_execution\_failed</code></td>
      <td>Actions Execution Failed</td>
      <td>Execution of an Action failed</td>
    </tr>

    <tr>
      <td><code>api\_limit</code></td>
      <td>Rate Limit on the Authentication or Management APIs</td>
      <td>The maximum number of requests to the Authentication or Management APIs in a given time has been reached.</td>
    </tr>

    <tr>
      <td><code>api\_limit\_warning</code></td>
      <td>Rate Limit Warning on the Authentication or Management APIs</td>
      <td>The limit of requests to the Authentication or Management APIs in given time is about to be reached.</td>
    </tr>

    <tr>
      <td><code>appi</code></td>
      <td>Notice for API Peak Performance initiated</td>
      <td>Increases the Elevated Public Authentication API Limits by the 100 RPS multiple purchased by the customer for up to 48 hours per month. For more information, see <a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#public-performance">Public performance rate limit policy</a>.</td>
    </tr>

    <tr>
      <td><code>ciba\_exchange\_failed</code></td>
      <td>Failed CIBA Exchange</td>
      <td>Failed to exchange AuthReqId for Access Token</td>
    </tr>

    <tr>
      <td><code>ciba\_exchange\_succeeded</code></td>
      <td>Successful CIBA Exchange</td>
      <td>Successful exchange of AuthReqId for Access Token</td>
    </tr>

    <tr>
      <td><code>ciba\_start\_failed</code></td>
      <td>Failed CIBA Start</td>
      <td>Client-Initiated Backchannel Authentication Flow failed to be initiated.</td>
    </tr>

    <tr>
      <td><code>ciba\_start\_succeeded</code></td>
      <td>Successful CIBA Start</td>
      <td>Client-Initiated Backchannel Authentication Flow has been successfully initiated.</td>
    </tr>

    <tr>
      <td><code>cls</code></td>
      <td>Code/Link Sent</td>
      <td>Passwordless login code/link has been sent</td>
    </tr>

    <tr>
      <td><code>cs</code></td>
      <td>Code Sent</td>
      <td>Passwordless login code has been sent</td>
    </tr>

    <tr>
      <td><code>depnote</code></td>
      <td>Deprecation Notice</td>

      <td />
    </tr>

    <tr>
      <td><code>f</code></td>
      <td>Failed Login</td>

      <td />
    </tr>

    <tr>
      <td><code>fc</code></td>
      <td>Failed by Connector</td>

      <td />
    </tr>

    <tr>
      <td><code>fce</code></td>
      <td>Failed Change Email</td>
      <td>Failed to change user email</td>
    </tr>

    <tr>
      <td><code>fco</code></td>
      <td>Failed by CORS</td>
      <td>Origin is not in the Allowed Origins list for the specified application</td>
    </tr>

    <tr>
      <td><code>fcoa</code></td>
      <td>Failed cross-origin authentication</td>

      <td />
    </tr>

    <tr>
      <td><code>fcp</code></td>
      <td>Failed Change Password</td>

      <td />
    </tr>

    <tr>
      <td><code>fcph</code></td>
      <td>Failed Post Change Password Hook</td>

      <td />
    </tr>

    <tr>
      <td><code>fcpn</code></td>
      <td>Failed Change Phone Number</td>

      <td />
    </tr>

    <tr>
      <td><code>fcpr</code></td>
      <td>Failed Change Password Request</td>

      <td />
    </tr>

    <tr>
      <td><code>fcpro</code></td>
      <td>Failed Connector Provisioning</td>
      <td>Failed to provision an AD/LDAP connector</td>
    </tr>

    <tr>
      <td><code>fcu</code></td>
      <td>Failed Change Username</td>
      <td>Failed to change username</td>
    </tr>

    <tr>
      <td><code>fd</code></td>
      <td>Failed Delegation</td>
      <td>Failed to generate delegation token</td>
    </tr>

    <tr>
      <td><code>fdeac</code></td>
      <td>Failed Device Activation</td>
      <td>Failed to activate device.</td>
    </tr>

    <tr>
      <td><code>fdeaz</code></td>
      <td>Failed Device Authorization Request</td>
      <td>Device authorization request failed.</td>
    </tr>

    <tr>
      <td><code>fdecc</code></td>
      <td>User Canceled Device Confirmation</td>
      <td>User did not confirm device.</td>
    </tr>

    <tr>
      <td><code>fdu</code></td>
      <td>Failed User Deletion</td>

      <td />
    </tr>

    <tr>
      <td><code>feacft</code></td>
      <td>Failed Exchange</td>
      <td>Failed to exchange authorization code for Access Token</td>
    </tr>

    <tr>
      <td><code>feccft</code></td>
      <td>Failed Exchange</td>
      <td>Failed exchange of Access Token for a Client Credentials Grant</td>
    </tr>

    <tr>
      <td><code>fecte</code></td>
      <td>Failed Exchange</td>
      <td>Failed Exchange via Custom Token Exchange</td>
    </tr>

    <tr>
      <td><code>fede</code></td>
      <td>Failed Exchange</td>
      <td>Failed to exchange Device Code for Access Token</td>
    </tr>

    <tr>
      <td><code>federated\_logout\_failed</code></td>
      <td>Failed Federated Logout</td>
      <td>Failed to logout of the upstream Identity Provider</td>
    </tr>

    <tr>
      <td><code>fens</code></td>
      <td>Failed Exchange</td>
      <td>Failed exchange for Native Social Login</td>
    </tr>

    <tr>
      <td><code>feoobft</code></td>
      <td>Failed Exchange</td>
      <td>Failed exchange of Password and OOB Challenge for Access Token</td>
    </tr>

    <tr>
      <td><code>feotpft</code></td>
      <td>Failed Exchange</td>
      <td>Failed exchange of Password and OTP Challenge for Access Token</td>
    </tr>

    <tr>
      <td><code>fepft</code></td>
      <td>Failed Exchange</td>
      <td>Failed exchange of Password for Access Token</td>
    </tr>

    <tr>
      <td><code>fepotpft</code></td>
      <td>Failed Exchange</td>
      <td>Failed exchange of Passwordless OTP for Access Token</td>
    </tr>

    <tr>
      <td><code>fercft</code></td>
      <td>Failed Exchange</td>
      <td>Failed Exchange of Password and MFA Recovery code for Access Token</td>
    </tr>

    <tr>
      <td><code>ferrt</code></td>
      <td>Failed Exchange</td>
      <td>Failed Exchange of Rotating Refresh Token. This could occur when reuse is detected.</td>
    </tr>

    <tr>
      <td><code>fertft</code></td>
      <td>Failed Exchange</td>
      <td>Failed Exchange of Refresh Token for Access Token. This could occur if the refresh token is revoked or expired.</td>
    </tr>

    <tr>
      <td><code>fi</code></td>
      <td>Failed invite accept</td>
      <td>Failed to accept a user invitation. This could happen if the user accepts an invitation using a different email address than provided in the invitation, or due to a system failure while provisioning the invitation.</td>
    </tr>

    <tr>
      <td><code>flo</code></td>
      <td>Failed Logout</td>
      <td>User logout failed</td>
    </tr>

    <tr>
      <td><code>flows\_execution\_completed</code></td>
      <td>Flows Execution Completed</td>

      <td />
    </tr>

    <tr>
      <td><code>flows\_execution\_failed</code></td>
      <td>Flows Execution Failed</td>

      <td />
    </tr>

    <tr>
      <td><code>fn</code></td>
      <td>Failed Sending Notification</td>
      <td>Failed to send notification</td>
    </tr>

    <tr>
      <td><code>forms\_submission\_failed</code></td>
      <td>Forms Submission Failed</td>

      <td />
    </tr>

    <tr>
      <td><code>forms\_submission\_succeeded</code></td>
      <td>Forms Submission Succeeded</td>

      <td />
    </tr>

    <tr>
      <td><code>fp</code></td>
      <td>Failed Login (Incorrect Password)</td>

      <td />
    </tr>

    <tr>
      <td><code>fpar</code></td>
      <td>Failed Pushed Authorization Request</td>

      <td />
    </tr>

    <tr>
      <td><code>fpurh</code></td>
      <td>Failed Post User Registration Hook</td>

      <td />
    </tr>

    <tr>
      <td><code>fs</code></td>
      <td>Failed Signup</td>

      <td />
    </tr>

    <tr>
      <td><code>fsa</code></td>
      <td>Failed Silent Auth</td>

      <td />
    </tr>

    <tr>
      <td><code>fu</code></td>
      <td>Failed Login (Invalid Email/Username)</td>

      <td />
    </tr>

    <tr>
      <td><code>fui</code></td>
      <td>Failed users import</td>
      <td>Failed to import users</td>
    </tr>

    <tr>
      <td><code>fv</code></td>
      <td>Failed Verification Email</td>
      <td>Failed to send verification email</td>
    </tr>

    <tr>
      <td><code>fvr</code></td>
      <td>Failed Verification Email Request</td>
      <td>Failed to process verification email request</td>
    </tr>

    <tr>
      <td><code>gd\_auth\_email\_verification</code></td>
      <td>Email Verification Confirmed</td>
      <td>Email verification completed successfully</td>
    </tr>

    <tr>
      <td><code>gd\_auth\_fail\_email\_verification</code></td>
      <td>Email Verification Failed</td>
      <td>Email verification failed.</td>
    </tr>

    <tr>
      <td><code>gd\_auth\_failed</code></td>
      <td>MFA Auth failed</td>
      <td>Multi-factor authentication failed. This could happen due to a wrong code entered for SMS/Voice/Email/TOTP factors, or a system failure.</td>
    </tr>

    <tr>
      <td><code>gd\_auth\_rejected</code></td>
      <td>MFA Auth rejected</td>
      <td>A user rejected a Multi-factor authentication request via push-notification.</td>
    </tr>

    <tr>
      <td><code>gd\_auth\_succeed</code></td>
      <td>MFA Auth success</td>
      <td>Multi-factor authentication success.</td>
    </tr>

    <tr>
      <td><code>gd\_enrollment\_complete</code></td>
      <td>MFA enrollment complete</td>
      <td>A first time MFA user has successfully enrolled using one of the factors.</td>
    </tr>

    <tr>
      <td><code>gd\_otp\_rate\_limit\_exceed</code></td>
      <td>Too many MFA failures</td>
      <td>A user sends more than 10 requests to their device within one hour. Note that the request limit does not reset upon a successful login event.</td>
    </tr>

    <tr>
      <td><code>gd\_recovery\_failed</code></td>
      <td>Recovery failed</td>
      <td>A user enters a wrong recovery code when attempting to authenticate.</td>
    </tr>

    <tr>
      <td><code>gd\_recovery\_rate\_limit\_exceed</code></td>
      <td>Multi-factor recovery code has failed too many times</td>
      <td>A user has entered a wrong recovery code too many times.</td>
    </tr>

    <tr>
      <td><code>gd\_recovery\_succeed</code></td>
      <td>MFA recovery success</td>
      <td>A user successfully authenticates with a recovery code.</td>
    </tr>

    <tr>
      <td><code>gd\_send\_email</code></td>
      <td>MFA Email Sent</td>
      <td>Email for MFA successfully sent.</td>
    </tr>

    <tr>
      <td><code>gd\_send\_email\_verification</code></td>
      <td>Email Verification Sent</td>
      <td>Verification email sent successfully.</td>
    </tr>

    <tr>
      <td><code>gd\_send\_email\_verification\_failure</code></td>
      <td>Email Verification Failed</td>
      <td>Email verification failed.</td>
    </tr>

    <tr>
      <td><code>gd\_send\_pn</code></td>
      <td>Push notification sent</td>
      <td>Push notification for MFA successfully sent.</td>
    </tr>

    <tr>
      <td><code>gd\_send\_pn\_failure</code></td>
      <td>Error Sending MFA Push Notification</td>
      <td>Push notification for MFA failed.</td>
    </tr>

    <tr>
      <td><code>gd\_send\_sms</code></td>
      <td>MFA SMS Sent</td>
      <td>SMS for MFA successfully sent.</td>
    </tr>

    <tr>
      <td><code>gd\_send\_sms\_failure</code></td>
      <td>Error Sending MFA SMS</td>
      <td>Attempt to send SMS for MFA failed.</td>
    </tr>

    <tr>
      <td><code>gd\_send\_voice</code></td>
      <td>MFA voice call success</td>
      <td>Voice call for MFA successfully made.</td>
    </tr>

    <tr>
      <td><code>gd\_send\_voice\_failure</code></td>
      <td>MFA voice call failed</td>
      <td>Attempt to make Voice call for MFA failed.</td>
    </tr>

    <tr>
      <td><code>gd\_start\_auth</code></td>
      <td>Second factor started</td>
      <td>Second factor authentication event started for MFA.</td>
    </tr>

    <tr>
      <td><code>gd\_start\_enroll</code></td>
      <td>MFA Enroll started</td>
      <td>Multi-factor authentication enroll has started.</td>
    </tr>

    <tr>
      <td><code>gd\_start\_enroll\_failed</code></td>
      <td>MFA Enrollment Failed</td>
      <td>Push to start enrollement failed.</td>
    </tr>

    <tr>
      <td><code>gd\_tenant\_update</code></td>
      <td>Guardian tenant update</td>

      <td />
    </tr>

    <tr>
      <td><code>gd\_unenroll</code></td>
      <td>Unenroll device account</td>
      <td>Device used for second factor authentication has been unenrolled.</td>
    </tr>

    <tr>
      <td><code>gd\_update\_device\_account</code></td>
      <td>Update device account</td>
      <td>Device used for second factor authentication has been updated.</td>
    </tr>

    <tr>
      <td><code>gd\_webauthn\_challenge\_failed</code></td>
      <td>WebAuthn browser error</td>
      <td>User failed to verify Webauthn factor.</td>
    </tr>

    <tr>
      <td><code>gd\_webauthn\_enrollment\_failed</code></td>
      <td>WebAuthn browser error</td>
      <td>WebAuthn browser  enrollment failed.</td>
    </tr>

    <tr>
      <td><code>kms\_key\_management\_failure</code></td>
      <td>Failed KMS API Operation</td>
      <td>KMS operation failed</td>
    </tr>

    <tr>
      <td><code>kms\_key\_management\_success</code></td>
      <td>Success KMS API Operation</td>
      <td>KMS operation completed successfully</td>
    </tr>

    <tr>
      <td><code>kms\_key\_state\_changed</code></td>
      <td>KMS Key State Change</td>
      <td>KMS key state changed</td>
    </tr>

    <tr>
      <td><code>limit\_delegation</code></td>
      <td>Too Many Calls to /delegation</td>
      <td>Rate limit exceeded to `/delegation` endpoint</td>
    </tr>

    <tr>
      <td><code>limit\_mu</code></td>
      <td>Blocked IP Address</td>
      <td>An IP address is blocked because it attempted too many failed logins without a successful login. Or an IP address is blocked because it attempted too many sign-ups, whether successful or failed. For more information, see <a href="/docs/secure/attack-protection">Attack Protection</a>.</td>
    </tr>

    <tr>
      <td><code>limit\_sul</code></td>
      <td>Blocked Account</td>
      <td>A user is temporarily prevented from logging in because they reached the maximum logins per time period from the same IP address. For more information, see <a href="/docs/secure/attack-protection">Attack Protection</a>.</td>
    </tr>

    <tr>
      <td><code>limit\_wc</code></td>
      <td>Blocked Account</td>
      <td>An IP address is blocked because it reached the maximum failed login attempts into a single account.</td>
    </tr>

    <tr>
      <td><code>mfar</code></td>
      <td>MFA Required</td>
      <td>A user has been prompted for multi-factor authentication (MFA). When using Adaptive MFA, Auth0 includes details about the risk assessment. Available in only the <a href="/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow">Resource Owner Password Flow</a>.</td>
    </tr>

    <tr>
      <td><code>mgmt\_api\_read</code></td>
      <td>Management API read Operation</td>
      <td>API GET operation returning secrets completed successfully</td>
    </tr>

    <tr>
      <td><code>my\_account\_authentication\_method\_failed</code></td>
      <td>Failed authentication method operation in My Account API</td>
      <td>Failed to complete authentication method operation in My Account API</td>
    </tr>

    <tr>
      <td><code>my\_account\_authentication\_method\_succeeded</code></td>
      <td>Successful authentication method operation in My Account API</td>
      <td>Successfully completed authentication method operation in My Account API</td>
    </tr>

    <tr>
      <td><code>oidc\_backchannel\_logout\_failed</code></td>
      <td>Failed OIDC Back-Channel Logout request</td>
      <td>Failed OIDC Back-Channel Logout request</td>
    </tr>

    <tr>
      <td><code>oidc\_backchannel\_logout\_succeeded</code></td>
      <td>Successful OIDC Back-Channel Logout request</td>
      <td>Successful OIDC Back-Channel Logout request</td>
    </tr>

    <tr>
      <td><code>organization\_member\_added</code></td>
      <td>Organization Member Added</td>
      <td>Successfully added member to organization</td>
    </tr>

    <tr>
      <td><code>passkey\_challenge\_failed</code></td>
      <td>Passkey Challenge Failed</td>
      <td>Native passkey challenge failed</td>
    </tr>

    <tr>
      <td><code>passkey\_challenge\_started</code></td>
      <td>Passkey Challenge Started</td>
      <td>Native passkey challenge was successfully initiated</td>
    </tr>

    <tr>
      <td><code>pla</code></td>
      <td>Pre-login assessment</td>
      <td>This log is generated before a login and helps in monitoring the behavior of bot detection without having to enable it.</td>
    </tr>

    <tr>
      <td><code>pwd\_leak</code></td>
      <td>Breached password</td>
      <td>Someone behind the IP address <code>ip</code> attempted to login with a leaked password. The <code>pwd\_leak</code> tenant log is emitted once per hour per IP address.</td>
    </tr>

    <tr>
      <td><code>reset\_pwd\_leak</code></td>
      <td>Breached Password on Reset</td>
      <td>Someone behind the IP address <code>ip</code> attempted to reset with a leaked password.</td>
    </tr>

    <tr>
      <td><code>resource\_cleanup</code></td>
      <td>Success Resource Cleanup</td>
      <td>Emitted when resources exceeding defined limits were removed.</td>
    </tr>

    <tr>
      <td><code>rich\_consents\_access\_error</code></td>
      <td>Rich Consents Access Error</td>
      <td>Error fetching a Rich Consent record</td>
    </tr>

    <tr>
      <td><code>s</code></td>
      <td>Success Login</td>
      <td>Successful login event.</td>
    </tr>

    <tr>
      <td><code>sapi</code></td>
      <td>Success API Operation</td>
      <td>Successful management API write event.</td>
    </tr>

    <tr>
      <td><code>sce</code></td>
      <td>Success Change Email</td>

      <td />
    </tr>

    <tr>
      <td><code>scoa</code></td>
      <td>Success cross-origin authentication</td>

      <td />
    </tr>

    <tr>
      <td><code>scp</code></td>
      <td>Success Change Password</td>

      <td />
    </tr>

    <tr>
      <td><code>scpn</code></td>
      <td>Success Change Phone Number</td>

      <td />
    </tr>

    <tr>
      <td><code>scpr</code></td>
      <td>Success Change Password Request</td>

      <td />
    </tr>

    <tr>
      <td><code>scu</code></td>
      <td>Success Change Username</td>

      <td />
    </tr>

    <tr>
      <td><code>scv</code></td>
      <td>Success Credential Validation</td>
      <td>Successful credential validation event.</td>
    </tr>

    <tr>
      <td><code>sd</code></td>
      <td>Success Delegation</td>

      <td />
    </tr>

    <tr>
      <td><code>sdu</code></td>
      <td>Success User Deletion</td>
      <td>User successfully deleted</td>
    </tr>

    <tr>
      <td><code>seacft</code></td>
      <td>Success Exchange</td>
      <td>Successful exchange of authorization code for Access Token</td>
    </tr>

    <tr>
      <td><code>seccft</code></td>
      <td>Success Exchange</td>
      <td>Successful exchange of Access Token for a Client Credentials Grant</td>
    </tr>

    <tr>
      <td><code>secte</code></td>
      <td>Success Exchange</td>
      <td>Succesful Exchange via Custom Token Exchange</td>
    </tr>

    <tr>
      <td><code>sede</code></td>
      <td>Success Exchange</td>
      <td>Successful exchange of device code for Access Token</td>
    </tr>

    <tr>
      <td><code>sens</code></td>
      <td>Success Exchange</td>
      <td>Native Social Login</td>
    </tr>

    <tr>
      <td><code>seoobft</code></td>
      <td>Success Exchange</td>
      <td>Successful exchange of Password and OOB Challenge for Access Token</td>
    </tr>

    <tr>
      <td><code>seotpft</code></td>
      <td>Success Exchange</td>
      <td>Successful exchange of Password and OTP Challenge for Access Token</td>
    </tr>

    <tr>
      <td><code>sepft</code></td>
      <td>Success Exchange</td>
      <td>Successful exchange of Password for Access Token</td>
    </tr>

    <tr>
      <td><code>sepkoobft</code></td>
      <td>Success Exchange</td>
      <td>Successful exchange of Passkey and OOB Challenge for Access Token</td>
    </tr>

    <tr>
      <td><code>sepkotpft</code></td>
      <td>Success Exchange</td>
      <td>Successful exchange of Passkey and OTP Challenge for Access Token</td>
    </tr>

    <tr>
      <td><code>sepkrcft</code></td>
      <td>Success Exchange</td>
      <td>Successful exchange of Passkey and MFA Recovery Code for Access Token</td>
    </tr>

    <tr>
      <td><code>sercft</code></td>
      <td>Success Exchange</td>
      <td>Successful exchange of Password and MFA Recovery code for Access Token</td>
    </tr>

    <tr>
      <td><code>sertft</code></td>
      <td>Success Exchange</td>
      <td>Successful exchange of Refresh Token for Access Token</td>
    </tr>

    <tr>
      <td><code>si</code></td>
      <td>Successfully accepted a user invite</td>
      <td>Successfully accepted a user invitation</td>
    </tr>

    <tr>
      <td><code>signup\_pwd\_leak</code></td>
      <td>Breached Password on Signup</td>
      <td>Someone behind the IP address <code>ip</code> attempted to signup with a leaked password.</td>
    </tr>

    <tr>
      <td><code>slo</code></td>
      <td>Success Logout</td>
      <td>User successfully logged out</td>
    </tr>

    <tr>
      <td><code>ss</code></td>
      <td>Success Signup</td>

      <td />
    </tr>

    <tr>
      <td><code>ss\_sso\_failure</code></td>
      <td>Failed SS-SSO Operation</td>
      <td>Self-Service operation failed</td>
    </tr>

    <tr>
      <td><code>ss\_sso\_info</code></td>
      <td>Information from an SS-SSO Operation</td>
      <td>Try-connection flow started/completed</td>
    </tr>

    <tr>
      <td><code>ss\_sso\_success</code></td>
      <td>Success SS-SSO Operation</td>
      <td>Self-Service operation completed successfully</td>
    </tr>

    <tr>
      <td><code>ssa</code></td>
      <td>Success Silent Auth</td>

      <td />
    </tr>

    <tr>
      <td><code>sscim</code></td>
      <td>Successful SCIM Operation</td>
      <td>SCIM operation succeeded</td>
    </tr>

    <tr>
      <td><code>sui</code></td>
      <td>Successfully imported users</td>
      <td>Successfully imported users</td>
    </tr>

    <tr>
      <td><code>sv</code></td>
      <td>Success Verification Email</td>
      <td>Successfully consumed email verification link</td>
    </tr>

    <tr>
      <td><code>svr</code></td>
      <td>Success Verification Email Request</td>
      <td>Successfully called verification email endpoint. Verification email in queue to send.</td>
    </tr>

    <tr>
      <td><code>too\_many\_records</code></td>
      <td>Max Amount of Authenticators</td>
      <td>User has created the maximum amount of authenticators</td>
    </tr>

    <tr>
      <td><code>ublkdu</code></td>
      <td>User login block released</td>
      <td>User block setup by anomaly detection has been released</td>
    </tr>

    <tr>
      <td><code>universal\_logout\_failed</code></td>
      <td>Failed Universal Logout request</td>
      <td>Failed Universal Logout request</td>
    </tr>

    <tr>
      <td><code>universal\_logout\_succeeded</code></td>
      <td>Successful Universal Logout request</td>
      <td>Successful Universal Logout request</td>
    </tr>

    <tr>
      <td><code>w</code></td>
      <td>Warning During Login</td>
      <td>Filters for logs of type <code>warning</code> during login</td>
    </tr>

    <tr>
      <td><code>wn</code></td>
      <td>Warning Sending Notification</td>
      <td>Warnings that have occurred during notification sending.</td>
    </tr>

    <tr>
      <td><code>wum</code></td>
      <td>Warning User Management</td>
      <td>Filters for logs of type <code>warning</code> during user management operations</td>
    </tr>
  </tbody>
</table>

## Learn more

* [View Logs](/docs/deploy-monitor/logs/view-log-events)
* [Log Search Query Syntax](/docs/deploy-monitor/logs/log-search-query-syntax)
* [Filter Log Events](/docs/deploy-monitor/logs/log-event-filters)
* [Retrieve Log Logs Using the Management API](/docs/deploy-monitor/logs/retrieve-log-events-using-mgmt-api)
* [Log Streams](/docs/customize/log-streams)


# Log Search Query Syntax
Source: https://auth0.com/docs/deploy-monitor/logs/log-search-query-syntax

Describes search query syntax using a subset of the Lucene query syntax to refine Auth0 log searches.

When searching for logs, you can create queries using a subset of [Lucene query syntax](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html) to refine your search.

The query string is parsed into a series of terms and operators:

* A term can be a single word such as `jane` or `smith`.
* A term can be a phrase surrounded by double quotes (`"customer log"`), which will match all words in the phrase in the same order.
* A term without a field name will only match these selected fields fields.
* Multiple terms can be grouped together with parentheses to form sub-queries.
* All search fields are case sensitive.
* Operators (`AND`, `OR`, `NOT`) work on all searchable fields.

## Searchable fields

The following fields are searchable and case sensitive:

<table>
  <thead>
    <tr>
      <th><strong>Field</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>client\_id</code></td>
      <td>Client ID related to the event.</td>
    </tr>

    <tr>
      <td><code>client\_name</code></td>
      <td>Client name related to the event.</td>
    </tr>

    <tr>
      <td><code>connection</code></td>
      <td>Connection name related to the event.</td>
    </tr>

    <tr>
      <td><code>connection\_id</code></td>
      <td>Connection ID related to the event.</td>
    </tr>

    <tr>
      <td><code>description</code></td>
      <td>Description of the event.</td>
    </tr>

    <tr>
      <td><code>date</code></td>
      <td>Date the event occurred in YYYY-MM-DD format.</td>
    </tr>

    <tr>
      <td><code>hostname</code></td>
      <td>Hostname used for the authentication flow.</td>
    </tr>

    <tr>
      <td><code>ip</code></td>
      <td>IP address from where the request that caused the log entry originated.</td>
    </tr>

    <tr>
      <td><code>log\_id</code></td>
      <td>Log ID of the event.</td>
    </tr>

    <tr>
      <td><code>organization\_id</code></td>
      <td>Organization ID related to the event.</td>
    </tr>

    <tr>
      <td><code>user\_id</code></td>
      <td>User ID related to the event.</td>
    </tr>

    <tr>
      <td><code>user\_name</code></td>
      <td>User name related to the event.</td>
    </tr>

    <tr>
      <td><code>user\_agent</code></td>
      <td>User agent related to the event.</td>
    </tr>

    <tr>
      <td><code>strategy</code></td>
      <td>Connection strategy related to the event.</td>
    </tr>

    <tr>
      <td><code>strategy\_type</code></td>
      <td>Connection strategy type related to the event.</td>
    </tr>

    <tr>
      <td><code>type</code></td>
      <td>Type of the event.</td>
    </tr>
  </tbody>
</table>

## Fields searchable against bare terms

If a search term is entered without a field name, it will only be searched against the following fields:

* `client_name`
* `connection`
* `description`
* `ip`
* `log_id`
* `type`
* `user_name`

## Exact matching

To find exact matches, use double quotes: `description:"Username invalid"`.

For example, to find logs with the description `Username invalid`, use `q=description:"Username invalid"`.

## Wildcards

Wildcard searches can be run on terms using the asterisk character (`*`) to replace zero or more characters: `user_name:john*`. They can be used for prefix matching, for example `user_name:j*`. For other uses of wildcards (for example, suffix matching), literals must have 3 characters or more. For example, `name:*usa` is allowed, but `name:*sa` is not.

The question mark character (`?`), is not supported.

For example, to find all logs for users whose usernames start with `john`, use `q=user_name:john*`.

## Ranges

You can use ranges in your log search queries. For inclusive ranges use square brackets: `[min TO max]`, and for exclusive ranges use curly brackets: `{min TO max}`.

Curly and square brackets can be combined in the same range expression. You can also use wildcards within ranges.

As an example, to find all logs from December 18, 2018 until the present, use `q=date:[2018-12-18 TO *]`.

If you'd like to search logs from the beginning of your retention period until, but not including, December 19, 2018, use `q=date:[* TO 2018-12-19}`.

## Example queries

Below are some examples to show the kinds of queries you can make with the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

<table>
  <thead>
    <tr>
      <th>Use Case</th>
      <th>Query</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Search all logs with connections that contains "Pass"</td>
      <td><code>connection:*pass*</code></td>
    </tr>

    <tr>
      <td>Search all logs for users with a user name that contains "fred"</td>
      <td><code>user\_name:*fred*</code></td>
    </tr>

    <tr>
      <td>Search all logs with user id's matching exactly "123"</td>
      <td><code>user\_id:"123"</code></td>
    </tr>

    <tr>
      <td>Search for all logs with a type starting with "s"</td>
      <td><code>type:s\*</code></td>
    </tr>

    <tr>
      <td>Search for user names that start with "jane" and end with "smith"</td>
      <td><code>user\_name:jane\*smith</code></td>
    </tr>

    <tr>
      <td>Search for all logs in December 2018</td>
      <td><code>date:\[2018-12 TO 2019-01-01}</code></td>
    </tr>

    <tr>
      <td>Search for all logs from December 10, 2018 forward</td>
      <td><code>date:\[2018-12-10 TO \*]</code></td>
    </tr>

    <tr>
      <td>Search for all logs from January 1, 2019 at 1AM, until, but not including January 1, 2019 at 12:23:45</td>
      <td><code>date:\[2019-01-01T01:00:00 TO 2019-01-01T12:23:45}</code></td>
    </tr>
  </tbody>
</table>

## Limitations

* If you get the error `414 Request-URI Too Large` this means that your query string is larger than the supported length. In this case, refine your search.
* Log fields are not tokenized , so `description:rule` will not match a description with value `Create a rule` nor `Update a rule`. Instead, use `description:*rule`. See wildcards and exact matching.
* The `.raw` field extension is not supported. Fields match the whole value that is provided and are not tokenized.

## Pagination

When calling the `GET /api/v2/logs` or `GET /api/v2/users/{user_id}/logs` endpoints using the `include_totals` parameter, the result is a JSON object containing a summary of the results and the requested logs. The JSON object looks something like:

```json lines theme={null}
{
  "length": 5,
  "limit": 5,
  "logs": [...],
  "start": 0,
  "total": 5
}
```

When searching for logs, the **totals** field tells you how many logs are returned in the page (similar to what the **length** field returns).

## Learn more

* [View Logs](/docs/deploy-monitor/logs/view-log-events)
* [Log Type Codes](/docs/deploy-monitor/logs/log-event-type-codes)
* [Filter Log Events](/docs/deploy-monitor/logs/log-event-filters)
* [Migrate to Tenant Log Search v3](/docs/troubleshoot/product-lifecycle/past-migrations/migrate-to-tenant-log-search-v3)


# Personally Identifiable Information in Auth0 Logs
Source: https://auth0.com/docs/deploy-monitor/logs/pii-in-logs

Describes the potential personally identifiable information (PII) that Auth0 writes to tenant logs.

Many logs in Auth0 tenant logs can contain personally identifiable information (PII). Authentication events trigger log entries that can include users' PII. And if you use the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> or the Dashboard to add users, Auth0 logs the user account details.

These fields in log entries can contain PII:

* Name
* Phone number (used for <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip>)
* Email address
* IP address (which can reveal location)
* Any custom user information you define

At no point does Auth0 log <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> from Auth0 or any <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>. When authorization code exchanges occur, the logs show only a partial code (for example: `code: 31XXXXX`).

## Learn more

* [Log Data Retention](/docs/deploy-monitor/logs/log-data-retention)
* [Log Search Query Syntax](/docs/deploy-monitor/logs/log-search-query-syntax)


# Prompt Details in Tenant Logs
Source: https://auth0.com/docs/deploy-monitor/logs/prompt-details-in-tenant-logs

Describes attributes and values from user prompts in Auth0 tenant logs.

Auth0 tenant logs provide transaction details for user authentication actions. Tenant logs capture information from the sign-in, login, and verification processes for review. You can review how the user authenticated, which credentials they provided, length of transaction, and connection status.

Below are the default values captured in tenant logs:

<table>
  <thead>
    <tr>
      <th><strong>Attribute</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>completedAt</code></td>
      <td>Stage completion time, including user interaction time</td>
    </tr>

    <tr>
      <td><code>elapsedTime</code></td>
      <td>Difference between <code>completedAt</code> and <code>initiatedAt</code></td>
    </tr>

    <tr>
      <td><code>flow</code></td>
      <td>Varies based on login experience (i.e., Universal or Classic)</td>
    </tr>

    <tr>
      <td><code>initiatedAt</code></td>
      <td>Stage start time</td>
    </tr>

    <tr>
      <td><code>name</code></td>
      <td>Name of the stage</td>
    </tr>
  </tbody>
</table>

## login

The login stage provides the following values:

<table>
  <thead>
    <tr>
      <th><strong>Attribute</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>flow</code></td>
      <td>Able to take two values dependent on Universal or Classic Login</td>
    </tr>

    <tr>
      <td><code>user\_id</code></td>
      <td>Auth0 ID of the user authenticated in this stage</td>
    </tr>

    <tr>
      <td><code>user\_name</code></td>
      <td>Name of the user authenticated in this stage</td>
    </tr>
  </tbody>
</table>

Additional fields with the following information:

<table>
  <thead>
    <tr>
      <th><strong>Attribute</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>connection</code></td>
      <td>Connection used to authenticate the user</td>
    </tr>

    <tr>
      <td><code>connection\_id</code></td>
      <td>ID of the connection used to authenticate the user</td>
    </tr>

    <tr>
      <td><code>strategy</code></td>
      <td>Strategy of the connection used to authenticate user</td>
    </tr>

    <tr>
      <td><code>identity</code></td>
      <td>Users’ authenticated identity</td>
    </tr>
  </tbody>
</table>

Values for additional events in the login flow:

<table>
  <thead>
    <tr>
      <th><strong>Name</strong></th>
      <th><strong>Universal Login Experience</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>federated-authenticate</code></td>
      <td>Universal</td>
      <td>Federated connection used for authentication, social, legal, or enterprise</td>
    </tr>

    <tr>
      <td><code>lock-password-authenticate</code></td>
      <td>Classic</td>
      <td>User authenticated with a username and password</td>
    </tr>

    <tr>
      <td><code>oauth1-authenticate</code></td>
      <td>Classic</td>
      <td>User authenticated with an oauth1 federation</td>
    </tr>

    <tr>
      <td><code>oauth2-authenticate</code></td>
      <td>Classic</td>
      <td>User authenticated with an oauth2 federation</td>
    </tr>

    <tr>
      <td><code>oidc-authenticate</code></td>
      <td>Classic</td>
      <td>User authenticated with an oidc federation</td>
    </tr>

    <tr>
      <td><code>prompt-authenticate</code></td>
      <td>Universal</td>
      <td>User authenticated with a username and password</td>
    </tr>

    <tr>
      <td><code>prompt-authenticate-password</code></td>
      <td>Universal</td>
      <td>User authenticated with username and password in the <code>idfirst</code> flow</td>
    </tr>

    <tr>
      <td><code>prompt-signup</code></td>
      <td>Universal</td>
      <td>User signed up using a username and password</td>
    </tr>

    <tr>
      <td><code>prompt-signup-password</code></td>
      <td>Universal</td>
      <td>User signed up using username and password using the <code>idfirst</code> flow</td>
    </tr>

    <tr>
      <td><code>saml-authenticate</code></td>
      <td>Classic</td>
      <td>User authenticated with a SAML federation</td>
    </tr>

    <tr>
      <td><code>wsfed-authenticate</code></td>
      <td>Classic</td>
      <td>User authenticated with a WS-FED federation</td>
    </tr>
  </tbody>
</table>

## consent

The consent stage provides the following values:

<table>
  <thead>
    <tr>
      <th><strong>Attribute</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grantInfo</code></td>
      <td>The  or identifier of the API granted permission by the user</td>
    </tr>

    <tr>
      <td><code>audience</code></td>
      <td>Token audience</td>
    </tr>

    <tr>
      <td><code>id</code></td>
      <td>User grant persisted in the database</td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td>Approved scope granted by the user</td>
    </tr>
  </tbody>
</table>

## login-email-verification

The email verification prompt provides the following values:

<table>
  <thead>
    <tr>
      <th><strong>Attribute</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code> login-email-verification</code></td>
      <td>Is included if the email verification prompt was presented</td>
    </tr>
  </tbody>
</table>

## redirect

The redirect stage provides the following values:

<table>
  <thead>
    <tr>
      <th><strong>Attribute</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>URL</code></td>
      <td>URL the user was redirected to</td>
    </tr>
  </tbody>
</table>

## mfa

<Tooltip href="/docs/glossary?term=Multi-factor+authentication">Multi-factor authentication</Tooltip> provides the following values:

<table>
  <thead>
    <tr>
      <th><strong>Attribute</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>flow</code></td>
      <td>Can take two values depending if used with the Classic experience (<code>mfa</code>) or the Universal experience (<code>universal-mfa</code>).</td>
    </tr>

    <tr>
      <td><code>performed\_acr</code></td>
      <td><code>acr</code> that will be included in the <code>id\_token</code>.</td>
    </tr>

    <tr>
      <td><code>performed\_amr</code></td>
      <td><code>amr</code> that will be included in the <code>id\_token</code>.</td>
    </tr>

    <tr>
      <td><code>provider</code></td>
      <td>Provider used to perform mfa.</td>
    </tr>
  </tbody>
</table>


# Retrieve Log Logs Using the Management API
Source: https://auth0.com/docs/deploy-monitor/logs/retrieve-log-events-using-mgmt-api

Learn how to retrieve logs using the Auth0 Management API get_logs endpoint by checkpoint or by search criteria.

You can use the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to retrieve up to 100 logs per request using the [/get\_logs](https://auth0.com/docs/api/management/v2/#!/Logs/get_logs) endpoint, which supports two types of consumption:

* **By checkpoint**: Recommended if you want to export logs to the external data analytics service.
* **By search criteria**: Used by the Dashboard.

Logs stored by Auth0 are subject to a retention period that is based on your Auth0 subscription. To learn more, read [Log Data Retention](/docs/deploy-monitor/logs/log-data-retention).

You can also use these endpoints to look for logs:

* `/api/v2/logs/{id}`: Retrieves the single log entry associated with the provided log ID.
* `/api/v2/users/{user_id}/logs`: Retrieves logs for a specific user ID.

## Retrieve logs by checkpoint

This method allows you to retrieve logs newer than a given `log_id`. It
is commonly used to send your Logs to an external system, such as Splunk, Datadog,
Application Insights, Mixpanel, and more.

To search by checkpoint, use the following parameters:

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>from</code></td>
      <td>Log event ID to start retrieving logs. You can limit the amount of logs using the <code>take</code> parameter.</td>
    </tr>

    <tr>
      <td><code>take</code></td>
      <td>The total amount of entries to retrieve when using the <code>from</code> parameter.</td>
    </tr>
  </tbody>
</table>

Any parameter other than `from` and `take` will be ignored. The logs are ordered by the `log_id`.

#### Semantics

Retrieving logs by checkpoint has the following semantics:

* All logs available to your role's permissions will be returned
* The logs are ordered by the `log_id`, rather than log generation time, to prevent skipping past records due to Auth0 system delays
* Pagination is unbounded, meaning there is no limit, in contrast to the `1,000` record limit when retrieving logs by search criteria

#### Pagination

When retrieving logs by checkpoint, only the first request should be made
manually. Each subsequent request should be made using the `next` relation URL
inside of the `Link` header. This simplifies the work for integrating with the
API, and allows Auth0 to make optimizations without impacting the customer
experience.

#### Example

Let's assume your tenant name in the `us` is `acme`. To start retrieving records by
checkpoint:

1. Grab the `log_id` from any log in your system.
   Example: `90020211201185132572079310688835925971249535794074878050`.
2. Make a request to `https://TENANT_NAME.LOCALITY.auth0.com/api/v2/logs?from=LOG_ID&take=100` to request the next `100` logs newer than the given `LOG_ID`.
3. The HTTP response will contain

   1. A JSON array of `0` to `100` logs newer than the given `LOG_ID`
   2. An HTTP `Link` header with a `next` relation
4. If the result set is empty you will receive an empty array, and the `next` relation will match the same URL you used in the most recent request

## Retrieve logs by search criteria

This method allows you to retrieve logs that match the specified search criteria or, if no criteria is used, lists all logs. To search by criteria use the following parameters:

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>q</code></td>
      <td>Search criteria using Query String Syntax.</td>
    </tr>

    <tr>
      <td><code>page</code></td>
      <td>The zero-based page number.</td>
    </tr>

    <tr>
      <td><code>per\_page</code></td>
      <td>The number of entries per page.</td>
    </tr>

    <tr>
      <td><code>sort</code></td>
      <td>The field to use for sorting. Use <code>field:order</code>, where <code>order</code> is <code>1</code> for ascending and <code>-1</code> for descending. For example <code>date:-1</code>.</td>
    </tr>

    <tr>
      <td><code>fields</code></td>
      <td>A comma-separated field list to include or exclude (depending on <code>include\_fields</code>) from the result. Leave empty to retrieve all fields.</td>
    </tr>

    <tr>
      <td><code>include\_fields</code></td>
      <td><code>true</code> if the fields specified are to be included in the result, <code>false</code> otherwise. Defaults to <code>true</code>.</td>
    </tr>
  </tbody>
</table>

To see a list of fields and sort parameters that can be used in the search query, read [Log Search Query Syntax](/docs/deploy-monitor/logs/log-search-query-syntax).

## Limitations

Besides the limitation of 100 logs per request to retrieve logs, you may only paginate through up to 1,000 search results.

If you get the error `414 Request-URI Too Large` this means that your query string is larger than the supported length. In this case, refine your search.

<Card title="Private Cloud search field limitations">
  The following fields are searchable only for Private Cloud:

  * `user`
  * `connection`
  * `application`
  * `type`
  * `ip`

  Use double quotes for exact searches (e.g., `application:"test"` will search for all log events specific to the application named `test`, but `application:test` will search log events for applications with "test" in their name.
</Card>

## Learn more

* [Log Type Codes](/docs/deploy-monitor/logs/log-event-type-codes)
* [Log Search Query Syntax](/docs/deploy-monitor/logs/log-search-query-syntax)
* [Log Data Retention](/docs/deploy-monitor/logs/log-data-retention)


# View Logs
Source: https://auth0.com/docs/deploy-monitor/logs/view-log-events

Learn how to view logs in the Dashboard including user authentication and administrative actions such as adding and updating applications, connections, and rules.

Use the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> to view all the logs that occur in your tenants, including user authentication and administrative actions such as adding and updating applications, connections, and rules. Administrative actions will show up in the logs as **API Operation** logs.

<Callout icon="file-lines">
  By default, logs may not display in the exact order in which they occurred. If you are streaming tenant logs and require chronological sorting, it is recommended that you implement log sorting through your stream processing.
</Callout>

1. Go to [Dashboard > Monitoring > Logs](https://manage.auth0.com/#/logs).

   <Frame>
     <img alt="Dashboard Monitoring Logs" />
   </Frame>
2. The list displays the latest logs. To perform a search, put your cursor in the search field, enter a query and press **Enter**. For example, to search all logs with connections that contain "Pass," enter `connection:*pass*`. To learn more about the search query syntax and examples, read [Log Search Query Syntax](/docs/deploy-monitor/logs/log-search-query-syntax).
3. You can choose to filter your search by log types. Choose a filter from the drop-down list and click **Apply**. For example, you can choose the **Failed Login** to filter for failed user login logs. To learn about log event filters and examples, read [Log Event Filters](/docs/deploy-monitor/logs/log-event-filters).

   <Frame>
     <img alt="Dashboard Monitoring Logs Filters" />
   </Frame>
4. You can choose a date range for your search. Click the drop-down next to the date field, choose a specific date or range, and click **Apply**.

## Learn more

* [Log Data Retention](/docs/deploy-monitor/logs/log-data-retention)
* [Filter Log Events](/docs/deploy-monitor/logs/log-event-filters)
* [Log Search Query Syntax](/docs/deploy-monitor/logs/log-search-query-syntax)


# Metric Streams
Source: https://auth0.com/docs/deploy-monitor/metric-streams

Stream Auth0 metrics to monitoring platforms like Datadog, New Relic, and Splunk for real-time observability.

# Metric Streams (Beta)

<Warning>
  Metric Streams is currently available in Beta. To use this feature, you must have an Enterprise plan. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal). To learn more about Auth0's product release cycle, read [Product Release Stages](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

Stream real-time Auth0 metrics to your monitoring platform to track API performance, identify rate limit issues, and troubleshoot errors faster. Metric Streams support both native Datadog integration and OpenTelemetry Protocol (OTLP) for platforms like New Relic and Splunk.

## What you can monitor

Track key metrics about your Auth0 API usage:

* **API request volume**: Monitor total requests to Authentication and Management APIs.
* **Error rates**: Identify client and server errors affecting your integration.
* **Rate limit occurrences**: Detect when your application hits rate limits.
* **Geographic distribution**: Analyze traffic patterns by country.
* **Authentication flows**: Track grant types and connection usage.

## Use cases

### Identify rate limit issues

Monitor which APIs and endpoints are hitting rate limits so you can adjust your integration or upgrade your rate limit tier.

### Troubleshoot API failures

Quickly identify the root cause of errors by filtering metrics by API, operation, and failure type (rate limits, anomaly detection, or general errors).

### Plan capacity

Analyze peak usage, average RPS, and percentile metrics to determine the appropriate rate limit tier for your workload.

## Prerequisites

Before setting up a metric stream, you need:

* **Auth0 Management API access**: Create a Machine-to-Machine (M2M) application with the following permissions:

  * `read:event_streams`
  * `create:event_streams`
  * `update:event_streams`
  * `delete:event_streams`
  * `read:event_deliveries`
  * `update:event_deliveries`

  For detailed instructions, read [Get Management API Access Tokens](/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production).

* **Auth0 CLI**: Install the [Auth0 CLI](https://auth0.github.io/auth0-cli/) to configure metric streams via API commands.

* **Monitoring platform account**: An active account with one of the [supported destinations](#supported-destinations).

## Metric reference

### auth0.api\_request.count

Counts API requests to your Auth0 tenant with detailed filtering and aggregation tags. A new metric is emitted every 10 seconds and provides per second granularity.

#### Available tags

| Tag Name           | Required | Description                                                                                           |
| ------------------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `api`              | Yes      | API type: `AUTHENTICATION` or `MANAGEMENT`                                                            |
| `operation_name`   | Yes      | HTTP method and path (e.g., `POST /oauth/token`)                                                      |
| `operation_result` | Yes      | Result: `SUCCESS` or `FAILURE`                                                                        |
| `tenant`           | Yes      | Your Auth0 tenant name                                                                                |
| `failure_code`     | No       | Failure reason: `RATE_LIMIT`, `ANOMALY_DETECTION`, or `CLIENT_SERVER_ERROR`                           |
| `country_code`     | No       | ISO country code from request IP address                                                              |
| `client_id`        | No       | Application Client ID (Authentication API only)                                                       |
| `connection_id`    | No       | Connection ID (Authentication API only)                                                               |
| `grant_type`       | No       | OAuth 2.0 grant type (Authentication API only)                                                        |
| `batch_seq`        | Yes      | Sequence number for metrics with identical tags and timestamp (temporary, will be removed after Beta) |

<Warning>
  The `client_id` and `connection_id` tags can generate high cardinality in environments with many unique clients or connections, potentially increasing monitoring costs. Use these tags selectively.
</Warning>

<Note>
  Metric streams do not include API calls that are cached or blocked by Auth0's Web Application Firewall (WAF) at the edge to prevent system overload.
</Note>

#### Enum values

**api**

* `AUTHENTICATION` - Authentication API requests
* `MANAGEMENT` - Management API requests

**operation\_result**

* `SUCCESS` - Request completed successfully
* `FAILURE` - Request failed with client or server error

**failure\_code** (only present when `operation_result` is `FAILURE`)

* `RATE_LIMIT` - Request exceeded rate limit
* `ANOMALY_DETECTION` - Blocked by Auth0's attack protection
* `CLIENT_SERVER_ERROR` - HTTP 4xx or 5xx error

## Supported destinations

Metric Streams support the following monitoring platforms:

<CardGroup>
  <Card title="Datadog" icon="chart-line" href="#set-up-datadog">
    Native integration with Datadog's metrics API
  </Card>

  <Card title="New Relic" icon="chart-mixed" href="#set-up-new-relic">
    Stream via OpenTelemetry Protocol (OTLP)
  </Card>

  <Card title="Splunk" icon="magnifying-glass-chart" href="#set-up-splunk">
    Stream via OpenTelemetry Protocol (OTLP)
  </Card>
</CardGroup>

## Set up Datadog

Stream Auth0 metrics directly to Datadog using their native metrics API.

### Prerequisites

* Active [Datadog account](https://www.datadoghq.com/)
* Datadog API key (generate at **Organization Settings > API Keys** in Datadog)
* Your Datadog site (region identifier like `US1` for app.datadoghq.com, `EU` for app.datadoghq.eu, `US3` for us3.datadoghq.com)

### Create metric stream

<Tabs>
  <Tab title="Dashboard">
    **Navigate to Metric Streams:**

    1. Go to [Auth0 Dashboard](https://manage.auth0.com) > **Monitoring** > **Metric Streams**.
    2. Select **+ Create Metric Stream**.
    3. Select **Datadog**.

    **Configure stream:**

    1. **Name**: Enter a descriptive name (e.g., `datadog-production`).
    2. **Datadog Site**: Select your Datadog region from the dropdown:
       * `US1` for app.datadoghq.com
       * `US3` for us3.datadoghq.com
       * `US5` for us5.datadoghq.com
       * `EU` for app.datadoghq.eu
       * `AP1` for ap1.datadoghq.com
    3. **Datadog API Key**: Paste your Datadog API key.
    4. Select **Save**.

    This creates and automatically enables your Metric Stream.
  </Tab>

  <Tab title="CLI">
    Use the Auth0 CLI to create a Datadog metric stream:

    ```bash theme={null}
    auth0 api post metric-streams \
      --data '{
        "name": "datadog-production",
        "subscriptions": [{ "metric_type": "auth0.api_request.count" }],
        "destination": {
          "type": "datadog",
          "configuration": {
            "api_key": "YOUR_DATADOG_API_KEY",
            "site": "app.datadoghq.com"
          }
        }
      }'
    ```

    **Response:**

    ```json theme={null}
    {
      "id": "mst_abc123xyz",
      "status": "enabled",
      "name": "datadog-production",
      "created_at": "2024-02-12T10:30:00Z",
      "updated_at": "2024-02-12T10:30:00Z",
      "destination": {
        "type": "datadog",
        "configuration": {
          "api_key": "***",
          "site": "app.datadoghq.com"
        }
      }
    }
    ```

    Save the `id` value to manage this stream later.
  </Tab>
</Tabs>

### Verify in Datadog

Within a few minutes, Auth0 metrics appear in Datadog. Navigate to **Metrics > Explorer** and search for `auth0.api_request.count` to view your data.

### Manage streams

<Tabs>
  <Tab title="Dashboard">
    **View all streams:**

    1. Go to [Auth0 Dashboard](https://manage.auth0.com) > **Monitoring** > **Metric Streams**.
    2. All configured streams are listed with their Destination, Status, Name, and Subscriptions.

    **Edit a stream:**

    1. Select the stream name from the list.
    2. Update the configuration.
    3. Select **Save**.

    **Enable/Disable a stream:**

    1. Choose the **Toggle switch** in the Status column to enable or disable the stream.
    2. Disabled streams stop sending metrics but retain their configuration.

    **Delete a stream:**

    1. Select the stream name from the list.
    2. Select **Delete** at the bottom of the configuration page.
    3. Confirm deletion.
  </Tab>

  <Tab title="CLI">
    **List all streams:**

    ```bash theme={null}
    auth0 api get /api/v2/metric-streams
    ```

    **Disable a stream:**

    ```bash theme={null}
    auth0 api patch /api/v2/metric-streams/YOUR_STREAM_ID \
      --data '{"status":"disabled"}'
    ```

    **Re-enable a stream:**

    ```bash theme={null}
    auth0 api patch /api/v2/metric-streams/YOUR_STREAM_ID \
      --data '{"status":"enabled"}'
    ```
  </Tab>
</Tabs>

## Set up New Relic

Stream Auth0 metrics to New Relic using OpenTelemetry Protocol (OTLP).

### Get New Relic credentials

<Steps>
  <Step title="Find your OTLP endpoint">
    Refer to [New Relic's OTLP documentation](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/#configure-endpoint-port-protocol) to find your region-specific endpoint:

    * **US:** `https://otlp.nr-data.net`
    * **EU:** `https://otlp.eu01.nr-data.net`

    Save this endpoint URL.
  </Step>

  <Step title="Create ingest license key">
    1. Go to **\[your user menu]** > **API Keys**.
    2. Select **Create a key**.
    3. Select **Key Type** = **Ingest - License**.
    4. Enter a descriptive name and optional note.
    5. Select **Create a key**.
    6. Copy the API key immediately. You need it for later steps and it won't be shown again.
  </Step>
</Steps>

### Create metric stream

<Tabs>
  <Tab title="Dashboard">
    **Navigate to Metric Streams:**

    1. Go to [Auth0 Dashboard](https://manage.auth0.com) > **Monitoring** > **Metric Streams**.
    2. Select **+ Create Metric Stream**.
    3. Select **OpenTelemetry**.

    **Configure stream:**

    1. **Name**: Enter a descriptive name (e.g., `newrelic-production`).
    2. **Protocol**: Select **HTTP** from the dropdown.
    3. **OTLP Endpoint**: Paste your New Relic OTLP endpoint (e.g., `https://otlp.nr-data.net`).
    4. **Authentication Method**: Select **API Key** from the dropdown.
    5. **Header Name**: Enter `api-key`.
    6. **API Key**: Paste your New Relic Ingest License Key that you copied from previous steps.
    7. Select **Save**.

    This creates and automatically enables your Metric Stream.
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    auth0 api post metric-streams \
      --data '{
        "name": "newrelic-production",
        "subscriptions": [{ "metric_type": "metrics_bridge.api_request" }],
        "destination": {
          "type": "otlp",
          "configuration": {
            "endpoint": "YOUR_NEW_RELIC_ENDPOINT",
            "protocol": "http",
            "auth_type": "api_key",
            "api_key": "YOUR_INGEST_LICENSE_KEY",
            "auth_header_name": "api-key"
          }
        }
      }'
    ```
  </Tab>
</Tabs>

## Set up Splunk

Stream Auth0 metrics to Splunk Observability Cloud using OpenTelemetry Protocol (OTLP).

### Get Splunk credentials

<Steps>
  <Step title="Find your OTLP endpoint">
    Refer to [Splunk's OTLP HTTP Exporter documentation](https://help.splunk.com/en/splunk-observability-cloud/manage-data/splunk-distribution-of-the-opentelemetry-collector/get-started-with-the-splunk-distribution-of-the-opentelemetry-collector/collector-components/exporters/otlphttp-exporter) to find your endpoint.

    The endpoint format is:

    ```
    https://ingest.<REALM>.signalfx.com/v2/datapoint/otlp
    ```

    Replace `<REALM>` with your Splunk realm (e.g., `us1`, `eu0`, `jp0`).
  </Step>

  <Step title="Create access token">
    1. Navigate to **Settings** > **Access Tokens** > **New Token**.
    2. Enter a descriptive name.
    3. Set **Authorization Scope** to **INGEST** (required).
    4. Set token expiration.
    5. Select **Create**.
    6. Copy and securely store the token value. You need this value for later steps.
  </Step>
</Steps>

### Create metric stream

<Tabs>
  <Tab title="Dashboard">
    **Navigate to Metric Streams:**

    1. Go to [Auth0 Dashboard](https://manage.auth0.com) > **Monitoring** > **Metric Streams**.
    2. Select **+ Create Metric Stream**.
    3. Select **OpenTelemetry**.

    **Configure stream:**

    1. **Name**: Enter a descriptive name (e.g., `splunk-production`).
    2. **Protocol**: Select **HTTP** from the dropdown.
    3. **OTLP Endpoint**: Paste your Splunk OTLP endpoint (e.g., `https://ingest.us1.signalfx.com/v2/datapoint/otlp`).
    4. **Authentication Method**: Select **API Key** from the dropdown.
    5. **Header Name**: Enter `X-SF-TOKEN`.
    6. **API Key**: Paste your Splunk access token (from Step 2 above).
    7. Select **Save**.

    The metric stream is created and automatically enabled.
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    auth0 api post metric-streams \
      --data '{
        "name": "splunk-production",
        "subscriptions": [{ "metric_type": "metrics_bridge.api_request" }],
        "destination": {
          "type": "otlp",
          "configuration": {
            "endpoint": "YOUR_SPLUNK_ENDPOINT",
            "protocol": "http",
            "auth_type": "api_key",
            "api_key": "YOUR_SPLUNK_ACCESS_TOKEN",
            "auth_header_name": "X-SF-TOKEN"
          }
        }
      }'
    ```
  </Tab>
</Tabs>

## Understand metric cardinality

Cardinality refers to the number of unique time series generated by your metrics. Higher cardinality increases monitoring costs.

| Tag                | Cardinality | Impact                                       |
| ------------------ | ----------- | -------------------------------------------- |
| `api`              | Low         | 2 unique values (Authentication, Management) |
| `operation_name`   | Medium      | Varies by API operations used                |
| `operation_result` | Low         | 2 unique values (Success, Failure)           |
| `tenant`           | Medium      | 1 per Auth0 tenant                           |
| `failure_code`     | Low         | 3 unique values (only on failures)           |
| `country_code`     | Medium-High | Varies by geographic distribution            |
| `client_id`        | **High**    | 1 per application client                     |
| `connection_id`    | **High**    | 1 per identity provider connection           |
| `grant_type`       | Low         | Limited OAuth 2.0 grant types                |
| `batch_seq`        | Low         | Temporary tag (removed after Beta)           |

<Warning>
  Use `client_id` and `connection_id` tags carefully. In environments with many applications or connections, these tags can significantly increase costs. Consider filtering to specific clients or aggregating these tags if detailed granularity isn't required.
</Warning>

## Troubleshooting

### Metrics not appearing

**Check stream status:**

<Tabs>
  <Tab title="Dashboard">
    1. Go to [Auth0 Dashboard](https://manage.auth0.com) > **Monitoring** > **Metric Streams**.
    2. Find your metric stream in the list.
    3. Verify the **Status** column shows **Enabled**.
    4. Select the stream name to view detailed configuration and verify settings.
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    auth0 api get /api/v2/metric-streams/YOUR_STREAM_ID
    ```

    Verify the `status` field is `enabled`.
  </Tab>
</Tabs>

**Verify destination credentials:**

* **Datadog**: Confirm your API key is valid and the site URL matches your Datadog region
* **OTLP destinations**: Verify endpoint URL, authentication token, and header name are correct

**Check for edge caching:**

Remember that cached requests and WAF-blocked requests are not included in metric streams.

### High monitoring costs

If you're seeing unexpectedly high costs:

1. Review which tags you're using in queries and dashboards.
2. Consider removing `client_id` and `connection_id` from aggregations.
3. Use sampling or filtering in your monitoring platform to reduce ingested metrics.
4. Aggregate by higher-level tags like `api` and `operation_result` instead of granular tags.


# Monitor Auth0
Source: https://auth0.com/docs/deploy-monitor/monitor

Describes how to monitor and track your Auth0 usage, as well as how to send tenant logs to external tools.

You can monitor your Auth0 implementation and Auth0 status and services, as well as your tenant log event data.

Follow [@auth0status](https://x.com/auth0status) on X to get the latest status updates and monitor your Auth0 implementation to check the status and availability of external services and applications.

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/deploy-monitor/monitor/check-auth0-status">Check Auth0 Status</a></td>
      <td>How to check Auth0 service availability for locale and region and subscribe for service updates.</td>
    </tr>

    <tr>
      <td><a href="/docs/deploy-monitor/monitor/check-external-services-status">Check External Services Status</a></td>
      <td>How to monitor external identity provider services.</td>
    </tr>

    <tr>
      <td><a href="/docs/deploy-monitor/monitor/monitor-applications">Monitor Applications</a></td>
      <td>How to monitor your application health to report potential impact to your users.</td>
    </tr>

    <tr>
      <td><a href="/docs/deploy-monitor/monitor/monitor-using-scom">Monitor Auth0 Using System Center Operations Manager</a></td>
      <td>How to monitor Auth0 using System Center Operations Manager (SCOM) or any tool that supports synthetic transactions.</td>
    </tr>

    <tr>
      <td><a href="/docs/deploy-monitor/logs">Logs</a></td>
      <td>About Auth0 tenant event logs that you can analyze for your business needs.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/log-streams">Log Streams</a></td>
      <td>How to create tenant log event streams to external services such as AWS EventBridge, Azure Event Grid, Datadog and more.</td>
    </tr>
  </tbody>
</table>


# Check Auth0 Status
Source: https://auth0.com/docs/deploy-monitor/monitor/check-auth0-status

Learn how to check Auth0 public cloud service availability, incident reports, and historical uptime reports.

Go to the [Auth0 Public Cloud Status](https://status.auth0.com) page to check the service availability of the public cloud version of Auth0.

Select a **Region** from the dropdown menu to see the status of Core Services (such as User Authentication and Machine-to-Machine Authentication) and Supporting Services (such as <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip>, <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>, Tenant Logs, and CDN).

For more information on available regions, refer to the [Region, locality, and sub-locality](/docs/get-started/auth0-overview/create-tenants#region-locality-and-sub-locality) table in [Create Tenants](/docs/get-started/auth0-overview/create-tenants).

## Subscribe to Public Cloud status updates

Select a **Region**, and then select **Subscribe** to get updates. You can choose from two options to view status:

1. Follow [@auth0status](https://x.com/auth0status) on X to get the latest status updates.
2. Subscribe to the Auth0 Atom or RSS feed to get status updates that affect your tenant. Replace `{YOUR_TENANT_DOMAIN}` with your tenant's **Domain**.

To find your tenant's **Domain**, go to [Auth0 Dashboard > Applications](https://manage.auth0.com/dashboard/#/applications), select an application, and then go to **Settings**. Your tenant's **Domain** is listed under **Basic Information**.

## Check Auth0 status for Private Cloud

Go to the [Auth0 Public Cloud Status](https://status.auth0.com), and then select **Private Cloud Login**.

Once authenticated, you can see the status of any non-development environment (for example, `travel0-prod-1`) if it's available on the Auth0 Converged Platform.

<Callout icon="file-lines">
  In order to access status for your Private Cloud environment, you need to be a member of the associated Public Cloud support tenant. For more information, please read [Open and Manage Support Tickets](/docs/troubleshoot/customer-support/open-and-manage-support-tickets) and [Manage Dashboard Access](/docs/get-started/manage-dashboard-access).
</Callout>

To go back to the Auth0 Public Cloud Status page, select **Auth0 Public Cloud Status** from the top-right navigation.

## Subscribe to Private Cloud status updates

Select an Environment, and then select **Subscribe**.

Subscribe to the Auth0 Atom or RSS feed by copying the generated URL in the 'Subscribe' box to get status updates that affect your environment.

<Callout icon="file-lines">
  The generated ATOM / RSS Feed URL is unique per Private Cloud environment and contains tokens that can be rotated by [contacting Support](https://support.auth0.com/).
</Callout>

<Frame>
  <img alt="" />
</Frame>


# Check External Services Status
Source: https://auth0.com/docs/deploy-monitor/monitor/check-external-services-status

Learn how to check the status of services external to Auth0.

We recommend that you monitor any remote <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> you use with your Auth0 connections to quickly isolate the source of the problem.

If you see potential issues with your Auth0 service, but [Auth0 Status](https://status.auth0.com) doesn't indicate any problems, check the status of any external services that you use with Auth0, such as:

* [Amazon Web Services](https://status.aws.amazon.com/)
* [Azure Active Directory](https://azure.microsoft.com/en-us/status/)
* [Citrix](https://status.cloud.com/)
* [Facebook](https://developers.facebook.com/status/)
* [GitHub](https://status.github.com/)
* [Google Cloud](https://status.cloud.google.com/)
* [Google Workspace](https://www.google.com/appsstatus#hl=en\&v=status)
* [Heroku](https://status.heroku.com/)
* [IBM](https://console.bluemix.net/status)
* [Mandrill](http://status.mandrillapp.com/)
* [Microsoft Azure](https://azure.microsoft.com/en-gb/status/)
* [SAP](https://www.sap.com/about/cloud-trust-center/cloud-service-status.html)
* [SendGrid](http://status.sendgrid.com/)
* [SFDC](https://status.salesforce.com/)
* [Slack](https://status.slack.com/)
* [Twilio](https://status.twilio.com/)
* [VM Ware](https://status.vmware-services.io/)

Your customers may have some of the same concerns, so you may want to document any monitoring pages or endpoints that they can view to help them troubleshoot and narrow down the location of an issue.


# Monitor Applications
Source: https://auth0.com/docs/deploy-monitor/monitor/monitor-applications

Your applications depend on Auth0. Monitoring Auth0's health lets you report errors or reduce user impact in case there's an issue with Auth0. Learn more.

Your applications and services depend on Auth0. Monitoring Auth0's health lets you report specific errors to customers or reduce user impact in case there's an issue with Auth0.

There's many ways to monitor Auth0 and each approach complements the others. You should pick based on your needs and investment possibilities.

## Synthetic transactions

The simplest approach to monitor Auth0:

* Set up a periodic request to perform an authentication transaction.
* If the request succeeds, Auth0 is working fine.
* If the request fails, this may indicate:

  * an issue with Auth0
  * an issue specific to the tenant used for the synthetic transaction
  * or just a single failed request.

For synthetic transactions, use an environment as close to your production tenant configuration as possible. You may potentially even use the same production tenant. Since setting up synthetic transactions with redirect flows and third party providers can be tricky, using the [Resource Owner Password Grant](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow/call-your-api-using-resource-owner-password-flow) is recommended. This flow doesn't involve browser redirects or require a UI.

If you are using [rules](/docs/customize/rules) or [custom database connection(s)](/docs/authenticate/database-connections/custom-db) or other extensibility points, the synthetic transaction(s) should be configured to utilize the rules and/or custom DB scripts to ensure that aspect of the system is working.

Tools like [Pingdom](http://pingdom.com/) make setting up synthetic transactions a simple thing.

### Check period

We recommend running synthetic transactions on one minute intervals. With this simple approach, that frequency won't consume a lot of your Auth0 rate limit quota, while also providing timely responses.

### Limitations of synthetic transactions

Synthetic transactions are a simple and inexpensive way monitoring an Auth0 tenant's health. However, they do have some limitations:

* Synthetic transactions do not represent your end user's experience. Instead they give you a proxy metric for them.
* Synthetic transactions might not use the same flows as your users.
* They lack atomicity (typically run once a minute) and do not report on errors your end users might have seen.

If you are interested in getting more granular data read about [Error Tracking](#error-tracking) and [Metrics and Logs](#metrics-and-logs).

## Error tracking

This approach is useful to track errors in existing calls to Auth0. It involves reporting errors whenever a call to Auth0 fails. [Sentry](https://sentry.io/) is a tool commonly used for these cases, which works both on frontend and backend scenarios.

This approach is useful because it allows you to know about real errors that your end users are experiencing. However, because you are only tracking errors (and not all requests) it is not possible to get an accurate perception of "how many" end users are affected: is it 1% or 5%? It also doesn't require you to set up a separate "synthetic call", which might consume part of your rate limit quota, especially if misconfigured.

## Metrics and logs

This approach is useful if calls to Auth0 are performed from a backend you control. This is the case for:

* Most calls to [Auth0's Management API](https://auth0.com/docs/api/management/v2)
* Calls to the [Authentication API](https://auth0.com/docs/api/authentication) from Regular Web Applications and Machine-to-machine applications ([learn more about client types](/docs/get-started/applications)).

<Callout icon="file-lines">
  Some observability products also allow you to report metrics/logs from frontend and mobile applications.
</Callout>

The approach consists of using metrics and/or logs to track error rates on calls to Auth0. Metrics/logs report error rates that accurately describe what end users are experiencing, without requiring you to set up a separate "synthetic call", which might consume part of your rate limit quota, especially if misconfigured.

## Alerting

Regardless of the monitoring approaches you use, it's common to get an alert or page when errors happen at a particular rate. That rate depends on your application.

When your team gets an alert from Auth0, we recommend adding a link to [Check Auth0 Status](/docs/deploy-monitor/monitor/check-auth0-status) to the alert payload/playbook. This will allow them to quickly check Auth0's official status reporting channel to see if the issue is coming from Auth0 or your application/service.

## Learn more

* [Check Auth0 Status](/docs/deploy-monitor/monitor/check-auth0-status)
* [Check External Services Status](/docs/deploy-monitor/monitor/check-external-services-status)
* [Monitor Auth0 Using System Center Operations Manager](/docs/deploy-monitor/monitor/monitor-using-scom)


# Monitor Auth0 Using System Center Operations Manager
Source: https://auth0.com/docs/deploy-monitor/monitor/monitor-using-scom

Describes how to monitor Auth0 as a standard web application using System Center Operations Manager (SCOM) or any tool that supports synthetic transactions.

You can monitor Auth0 as a standard web application using System Center Operations Manager (SCOM) or any tool that supports synthetic transactions. We recommend adding a synthetic login transaction that includes the extensions your applications rely on (such as rules that execute custom code for integration with your company's other services).

## Set up SCOM

1. Add a new SCOM instance using the **Add Monitoring Wizard**:

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Name</td>
      <td>Description name for the SCOM instance.</td>
    </tr>

    <tr>
      <td>Description</td>
      <td>Description of what this SCOM instance monitors.</td>
    </tr>

    <tr>
      <td>Select destination management pack</td>
      <td>Default Management Pack</td>
    </tr>
  </tbody>
</table>

When finished, click **Next** to continue.

2. Click **Add** to enter the URLs you want SCOM to monitor. When finished, click **Next** to continue.

3. Click **Add** to set up a location from which you want to monitor.

4. In the pop-up dialog, search for **Internal location - Agent**. Select the appropriate address, and click **Add**. Then click **Ok** to finish selecting the location. When finished, click **Next** to continue.

5. Set the frequency with which SCOM collects data from each endpoint:

<table>
  <thead>
    <tr>
      <th>Data</th>
      <th>Frequency</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Test frequency</td>
      <td>60 seconds</td>
    </tr>

    <tr>
      <td>Performance data collection interval</td>
      <td>60 seconds</td>
    </tr>

    <tr>
      <td>Test time-out</td>
      <td>30 seconds</td>
    </tr>

    <tr>
      <td>HTTP status code</td>
      <td>Greater than or equals 400</td>
    </tr>
  </tbody>
</table>

6. When finished, click **Next** to continue.

## Run SCOM tests

1. Click **Run Test** to test each endpoint and ensure that the connection settings provided are correct.
2. Once you have finished configuring your SCOM instance, you can view activity through the **Monitoring** tab.

## Review test results

Click **Web Application Status** to bring up the information SCOM has gathered.

## Learn more

* [Check Auth0 Status](/docs/deploy-monitor/monitor/check-auth0-status)
* [Monitor Applications](/docs/deploy-monitor/monitor/monitor-applications)
* [Check External Services Status](/docs/deploy-monitor/monitor/check-external-services-status)


# Pre-Deployment Checks
Source: https://auth0.com/docs/deploy-monitor/pre-deployment-checks

A reference of helpful pre-deployment checks for your production Auth0 environment.

Before you go live, run Auth0's production checks suite to ensure that your tenants are ready for use in a production environment.

<table>
  <thead>
    <tr>
      <th><strong>Read</strong></th>
      <th><strong>To learn...</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/deploy-monitor/pre-deployment-checks/how-to-run-production-checks">Production Checks</a></td>
      <td>How to run the production checks against one or more applications to see if they're production-ready or not. View your results to see any outstanding required and recommended tasks, as well as changes you can make to ensure that you comply with best practices.</td>
    </tr>

    <tr>
      <td><a href="/docs/deploy-monitor/pre-deployment-checks/predeployment-tests">Pre-Deployment Tests</a></td>
      <td>How to run unit and integration tests before deploying Auth0.</td>
    </tr>

    <tr>
      <td><a href="/docs/deploy-monitor/pre-deployment-checks/pre-launch-tips">Pre-Launch Tips</a></td>
      <td>About tips we have collected from our customers when first getting started with Auth0.</td>
    </tr>
  </tbody>
</table>


# Run Production Readiness Checks
Source: https://auth0.com/docs/deploy-monitor/pre-deployment-checks/how-to-run-production-checks

Learn how to run the Auth0 Production Checks to ensure that your Applications are production-ready.

Review production check results for your tenant before you deploy your production environment.

1. Go to the Auth0 Management Dashboard and log in to your account.
2. From the dropdown, select the tenant for which you want to run the Production Checks
3. From the same dropdown, click **Run Readiness Check** to launch the interface

<Frame>
  <img alt="" />
</Frame>

<Frame>
  <img alt="Auth0 Support pre-deployment production checks" />
</Frame>

Optional:

1. Select one or more [Applications](/docs/get-started/applications) associated with this tenant for which you want checks to run by clicking **Filters.**
2. Click **Apply**.

When the test is complete, your screen will automatically refresh to display your check results.

## Production check results

There are three categories of check result fixes:

* [Critical fixes](/docs/deploy-monitor/pre-deployment-checks/production-check-required-fixes)
* [Non-critical fixes](/docs/deploy-monitor/pre-deployment-checks/production-check-recommended-fixes)
* [Best practices](/docs/deploy-monitor/pre-deployment-checks/production-checks-best-practices)

The following are possible results for your check:

* Passed
* Failed
* Best practices

Under each set of results, Auth0 tells you how many checks your application passed, as well as how many checks require review.

If your application **failed** for one or more checks, you'll see:

* The name of the check
* Information on what the check is looking for
* A **Configure** link to the appropriate area where you can make the required fixes so that your Application passes the check
* Hyperlink to corresponding documentation

All of the checks that your application **passed** are grouped together in the passed object of the results set. You can view the name of and information about the check, as well as review the associated documentation and use the hyperlink to go to the corresponding configuration area where you can make changes (if desired).

## Learn more

* [Production Readiness Checks: Critical Fixes](/docs/deploy-monitor/pre-deployment-checks/production-check-required-fixes)
* [Production Readiness Checks: Non-Critical Fixes](/docs/deploy-monitor/pre-deployment-checks/production-check-recommended-fixes)
* [Production Readiness Checks: Best Practices](/docs/deploy-monitor/pre-deployment-checks/production-checks-best-practices)
* [Get Management API Access Tokens for Production](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production)


# Pre-Launch Tips
Source: https://auth0.com/docs/deploy-monitor/pre-deployment-checks/pre-launch-tips

A list of helpful tips for when getting started with Auth0 services based on feedback and experience from others

Here is a list of tips our customers have found most useful when first getting started with Auth0 services:

* Check the URLs in your allowed callbacks, CORS and allowed redirect URLs for Logout to make sure they are correct, complete, and do not involve use of `file:///` or `localhost`. Minimize the use of wildcards and consider carefully the security ramifications of wildcards.
* Separate production use from ongoing development work by [using separate tenants for prod, test and dev.](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments)
* Configure your network correctly to allow traffic to and from our sets of public APIs (prod envs might have a different configuration than dev/staging).
* Check the expiration date of certificates you have added to your configuration to make sure certificates uploaded during development cycles won’t expire during or shortly after launch.
* Make sure any remote <Tooltip href="/docs/glossary?term=IDPs">IDPs</Tooltip> are running NTP so that the time will be properly synced.
* The number of days of log data available varies by plan up to a max of 30 days. If you need log data for a longer retention period, you should configure one of our [log streaming solutions](https://marketplace.auth0.com/features/log-streaming). This will enable you to keep log data for longer periods. Be sure to set this up before you go live so you are sure to have log data when you need it.
* Make sure your usage of our APIs remains within [allowed limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy) and you have written your code to dynamically adjust to rate limit information returned in the header and to handle errors. If you anticipate rate limits being a problem for your application, discuss with us up-front to check if it would be possible to momentarily raise them until the traffic returns to normal. You should consider using a cache of user data in order to not have to query an API endpoint more than necessary.
* If using [social connections](/docs/authenticate/identity-providers), make sure to obtain your own credentials from the provider and add them to the configuration of the social connection.
* If using [custom DB connections](/docs/authenticate/database-connections/custom-db), make sure all custom DB scripts are implemented and return a consistent user-profile with a unique user ID.
* For sending emails, first make sure to [set up a custom email provider.](/docs/customize/email/smtp-email-providers)
* If you use our CDN for the Lock widget, make sure to pin to a specific version.
* Make sure **external** components called from Actions, Rules, Hooks, and custom database connection scripts can handle the expected load.
* Adequately protect any <Tooltip href="/docs/glossary?term=client+secret">client secret</Tooltip> values.
* Check your [grant types](/docs/get-started/applications/application-grant-types) for your applications. Make sure you have the right ones enabled and more importantly, disable any grant types that aren't needed.
* If you make use of user\_metadata, confirm that this is data that users should be able to change on their own (e.g., not “payment status”).
* Review your [Attack Protection settings](https://manage.auth0.com/#/security/attack-protection) and read [Attack Protection](/docs/secure/attack-protection) to understand how to unblock users that have been blocked.
* Review your [Tenant Settings Admin section](https://manage.auth0.com/#/tenant/admins) to make sure that only appropriate admins have access to the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. See [Manage Dashboard Access](/docs/get-started/manage-dashboard-access) for more information.
* Make sure you have tested all core use cases for your application on all devices that might be used by the end-user population for your application. Be sure to test login, <Tooltip href="/docs/glossary?term=single+sign-on">single sign-on</Tooltip> (if supported), and log, as well as what happens if a user runs your application in multiple browser tabs.
* Review your [list of rules](https://manage.auth0.com/#/rules) and make sure only the appropriate rules are turned on.
* Review your rule code, any custom DB scripts, and any custom code in the login page to ensure that every call has adequate error trapping and handling. Also, review to make sure that return/callback statements are called correctly.
* Configure your application name, support URL, and support email in the [Tenant Settings General](https://manage.auth0.com/#/tenant) section so when an error occurs your end users will be directed to an appropriate page.
* Make sure that your application is [dynamically obtaining a management API token](/docs/secure/tokens/access-tokens/management-api-access-tokens).
* Remove any `console.log` statements from your rules or custom DB scripts. Especially those that might leak user identifiable information such as email, username or password.
* Do not use plain text secrets in rules or db-connections. They should be added in the configuration part of the interface. The configuration is encrypted and provided just in time. Do not log the configuration object.

## Learn more

* [Verify Domain](/docs/troubleshoot/basic-issues/verify-domain)
* [Verify Platform](/docs/troubleshoot/basic-issues/verify-platform)
* [Verify Connections](/docs/troubleshoot/basic-issues/verify-connections)
* [Check Error Messages](/docs/troubleshoot/basic-issues/check-error-messages)


# Run Pre-Deployment Tests
Source: https://auth0.com/docs/deploy-monitor/pre-deployment-checks/predeployment-tests

Learn how to test your Auth0 implementation prior to deployment to production environments.

You should run unit and integration tests before deploying Auth0 on a live application or service. Performing tests against Auth0 APIs may lead to your account being [rate limited](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy), so we recommend creating mock Auth0 APIs during testing. Depending on your development environment, your test tools may also provide mock API functionality. There are also numerous API mocking tools available, such as [MockServer](https://www.mock-server.com/) or [JSON Server](https://github.com/typicode/json-server), you can use to quickly create fake APIs for testing.

If you have an Enterprise subscription, you can request [load testing](/docs/troubleshoot/customer-support/operational-policies/load-testing-policy) against Auth0.

## Performance tests

If you encounter issues while conducting performance tests, use the following methods to troubleshoot.

### Auth0 Dashboard

The [Monitoring > Logs](https://manage.auth0.com/#/logs) section of the Dashboard stores data on:

* Actions taken in the Dashboard by administrators
* Authentications made by your users

There are also [extensions](/docs/customize/extensions) that you can use for logging purposes, including exporting logs to third-party tools and gathering information on the use of custom code in your account.

### Third-party test tools

There are a number of third-party test tools that you can use for performance testing against RESTful APIs. Here are some options you might consider (note that Auth0 does not endorse any particular product or tool):

* [Apache JMeter](https://jmeter.apache.org/)
* [Artillery](https://www.artillery.io/)
* [Micro Focus LoadRunner](https://www.radview.com/)
* [Loader](https://loader.io/)
* [RadView Webload](https://www.radview.com/)
* [SmartBear LoadUI](https://smartbear.com/)
* [Vegeta](https://github.com/tsenart/vegeta)
* [Wrk](https://github.com/wg/wrk)

These tools provide activity logs that help you identify anything that is concerning. If you need assistance with deciphering your log or identifying the potential issue, please contact Support.

### HTTP archive files

If you discover an issue that you can reproduce, we recommend that you [create an HTTP archive (HAR) file](/docs/troubleshoot/troubleshooting-tools/generate-and-analyze-har-files) and send it to our Support team for additional assistance.

## Learn more

* [Professional Services: Implement](/docs/get-started/professional-services/implement)
* [Set Up AD/LDAP Connector Test Environment](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-test-environment)
* [Generate and Analyze HAR Files](/docs/troubleshoot/troubleshooting-tools/generate-and-analyze-har-files)


# Production Readiness Checks: Non-Critical Fixes
Source: https://auth0.com/docs/deploy-monitor/pre-deployment-checks/production-check-recommended-fixes

Recommendations on how you can improve your Auth0 Application prior to production deployment

The following checks see if you've completed all recommendations (which are optional) for successful deployment to Production.

For more information about your checks output, see [Run Production Checks](/docs/deploy-monitor/pre-deployment-checks/how-to-run-production-checks).

<table>
  <thead>
    <tr>
      <th>Check</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Configure Log Streaming</td>
      <td>Ensure you stream tenant log entries to an external storage location or provider. We recommend that you <a href="/docs/customize/log-streams">configure a log streaming service</a> to retain logs over 30 days and enable better analysis and alerting.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/custom-domains">Custom Domain</a> should be configured</td>
      <td>Use <a href="https://manage.auth0.com/#/tenant/custom_domains">custom domains with Universal Login</a> for the most seamless and secure experience for your end users.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/login-pages/custom-error-pages">Custom Error Page</a> should be configured</td>
      <td><a href="https://manage.auth0.com/#/account">Configure a Custom Error Page</a> with your application-specific details and corporate branding.</td>
    </tr>

    <tr>
      <td>Enable Universal Login</td>
      <td>Ensure you're using the latest version of <a href="/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login">Universal Login</a>. We recommend updating your login page from the Classic experience to Universal Login to benefit from better accessibility and performance, no-code customization, and new features.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/email/manage-email-flow">Email Templates</a> should be configured</td>
      <td><a href="https://manage.auth0.com/#/emails">Configure custom email templates</a> with your application specific details and corporate branding.</td>
    </tr>

    <tr>
      <td><a href="/docs/secure/multi-factor-authentication">Multi-factor Auth</a> should be configured</td>
      <td>It is recommended that you consider multifactor authentication as a secure practice for authenticating your users.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/manage-dashboard-access">MFA for Tenant Administrators</a> is enabled</td>
      <td><a href="https://manage.auth0.com/#/account/admins">Enable multi-factor authentication</a> for tenant administrators.</td>
    </tr>

    <tr>
      <td><a href="/docs/authenticate/login/logout#set-the-allowed-logout-urls-at-the-account-level">Redirect Logout URL</a> should be defined</td>
      <td>Review the <a href="https://manage.auth0.com/#/account/advanced">Allowed Redirect Logout URLs</a> for your Application.</td>
    </tr>

    <tr>
      <td>Applications should use RS256 instead of HS256 for JSON Web Token (JWT) Signature Algorithm</td>
      <td>Set the JSON Web Token (JWT) <a href="/docs/get-started/apis#signing-algorithms">Signature Algorithm</a> to RS256 instead of HS256 for each application.</td>
    </tr>

    <tr>
      <td>Set <a href="/docs/get-started/applications/application-settings#application-uris">Application Login URI</a></td>
      <td>Indicate a <a href="/docs/get-started/applications/application-settings#application-uris">Application Login URI</a> for all interactive Applications.</td>
    </tr>

    <tr>
      <td>Set <a href="/docs/get-started/applications/application-settings#application-uris">Tenant Allowed Logout URL</a></td>
      <td>Create at least one publicly-accessible logout route and <a href="/docs/get-started/applications/application-settings#application-uris">update tenant settings</a> to point there.</td>
    </tr>

    <tr>
      <td>Set <a href="/docs/get-started/tenant-settings#login-and-logout">Tenant Login URI</a></td>
      <td>Publish a default login route and <a href="/docs/get-started/tenant-settings#login-and-logout">update your tenant settings</a> to point there.</td>
    </tr>
  </tbody>
</table>

## Learn more

* [Production Readiness Checks: Critical Fixes](/docs/deploy-monitor/pre-deployment-checks/production-check-required-fixes)
* [Production Readiness Checks: Best Practices](/docs/deploy-monitor/pre-deployment-checks/production-checks-best-practices)
* [Get Management API Access Tokens for Production](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production)


# Production Readiness Checks: Critical Fixes
Source: https://auth0.com/docs/deploy-monitor/pre-deployment-checks/production-check-required-fixes

Fixes you must make to your Auth0 Application prior to production deployment

The following checks see if you've completed all requirements for successful deployment to Production.

For more information about your checks output, see [Run Production Checks](/docs/deploy-monitor/pre-deployment-checks/how-to-run-production-checks).

<table>
  <thead>
    <tr>
      <th>Check</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>All Actions are running a <a href="/docs/troubleshoot/product-lifecycle/past-migrations/migrate-nodejs-16-to-nodejs-18">recommended version of NodeJS</a></td>
      <td>Set all <a href="/docs/troubleshoot/product-lifecycle/past-migrations/migrate-nodejs-16-to-nodejs-18">Actions</a> to a recommended version of NodeJS to take advantage of security patches and new features.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/product-lifecycle/past-migrations/migrate-to-calling-api-with-access-tokens">Allow ID Tokens for Management API v2 Authentication</a> is disabled</td>
      <td>The capabilities for using ID Tokens to authorize some of the Users and Device Credentials endpoints of the Management API are being deprecated. After completing migration to Access Tokens, make sure the <a href="https://manage.auth0.com/#/tenant/advanced">Allow ID Tokens for Management API v2 Authentication</a> toggle is turned off. If you can't see this setting, then your tenant was created after this feature was deprecated, so it is already disabled by default.</td>
    </tr>

    <tr>
      <td>allowLegacyRoGrantTypes</td>
      <td>The legacy <a href="/docs/troubleshoot/product-lifecycle/past-migrations/migration-oauthro-oauthtoken">oauth/ro endpoint</a> in tenant migration settings is being deprecated. After updating your applications to use supported endpoints, make sure you turn this endpoint off.</td>
    </tr>

    <tr>
      <td>allowOtherLegacyGrantTypes</td>
      <td>The legacy <a href="https://auth0.com/docs/api/authentication/login-legacy/social-with-providers-access-token">oauth/access\_token endpoint</a> in tenant migration settings is being depricated. After updating your applications to use supported endpoints, make sure you turn this endpoint off.</td>
    </tr>

    <tr>
      <td>allowLegacyTokenInfoEndpoint</td>
      <td>The legacy <a href="/docs/troubleshoot/product-lifecycle/past-migrations#tokeninfo-endpoint-validation">tokeninfo endpoint</a> in tenant migration settings is being depricated. After updating your applications to use supported endpoints, make sure you turn this endpoint off.</td>
    </tr>

    <tr>
      <td>allowLegacyDelegationGrantTypes</td>
      <td>The legacy <a href="/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-delegation">delegation endpoint</a> in tenant migration settings is being depricated. After updating your applications to use supported endpoints, make sure you turn this endpoint off.</td>
    </tr>

    <tr>
      <td><a href="/docs/authenticate/login/redirect-users-after-login">Allowed Callback URLs</a> should not include Localhost</td>
      <td>Validates the <a href="https://manage.auth0.com/#/applications">Application Allowed Callback URLs</a> do not point to <code>localhost</code>, <code>127.0.0.1</code>, and so on.</td>
    </tr>

    <tr>
      <td><a href="/docs/authenticate/login/cross-origin-authentication">Allowed Origins (CORS)</a> should not be Localhost</td>
      <td>Validates that the <a href="https://manage.auth0.com/#/applications">Location URL</a> for the page does not point to <code>localhost</code>.</td>
    </tr>

    <tr>
      <td><a href="/docs/get-started/applications/application-settings">Allowed Web Origins</a> should not include <code>localhost</code></td>
      <td>Validates that the <a href="https://manage.auth0.com/#/applications">Allowed Web Origins URLs</a> do not point to <code>localhost</code>.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/email/smtp-email-providers">Email Provider</a> should be configured</td>
      <td>Verifies that the <a href="https://manage.auth0.com/#/emails/provider">custom email provider</a> has been configured.</td>
    </tr>

    <tr>
      <td>Hooks are being deprecated and must be <a href="/docs/customize/actions/migrate/migrate-from-hooks-to-actions">migrated to Actions</a></td>
      <td>Hooks are being deprecated. We strongly recommend that you begin using <a href="/docs/customize/actions/migrate/migrate-from-hooks-to-actions">Actions</a> and start the migration process. Existing Hooks will stay active until Nov 18, 2024.</td>
    </tr>

    <tr>
      <td><a href="/docs/secure/multi-factor-authentication/multi-factor-authentication-factors/configure-sms-voice-notifications-mfa">Multi-Factor Auth</a> should be configured (Dependency: MFA is configured)</td>
      <td>If you are using MFA with the <a href="https://manage.auth0.com/#/mfa">Phone Message factor</a>, configure it with a Twilio or custom delivery provider to avoid rate limits of the default delivery provider.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/product-lifecycle/past-migrations/migrate-from-legacy-auth-flows#user-profiles">Legacy User Profile</a> should be disabled</td>
      <td>The legacy authentication flows that allow ID Tokens and the <code>/userinfo</code> endpoint to include the complete user profile are being deprecated. After completing the migration to the new OIDC-conformant APIs, make sure the <a href="https://manage.auth0.com/#/account/advanced">Legacy User Profile</a> toggle is turned off.</td>
    </tr>

    <tr>
      <td>Rules are being deprecated and must be <a href="/docs/customize/actions/migrate/migrate-from-rules-to-actions">migrated to Actions</a></td>
      <td>Rules are being deprecated. We strongly recommend that you begin using <a href="/docs/customize/actions/migrate/migrate-from-rules-to-actions">Actions</a> and start the migration process. Existing Rules will stay active until Nov 18, 2024.</td>
    </tr>

    <tr>
      <td><a href="/docs/authenticate/identity-providers/social-identity-providers/devkeys">Social Connections</a> should not use Auth0 Developer Keys</td>
      <td>Verifies that <a href="https://manage.auth0.com/#/connections/social">Social Connections</a> are not using the default Auth0 developer keys.</td>
    </tr>

    <tr>
      <td>Support Email should be configured</td>
      <td>Ensures the <a href="https://manage.auth0.com/#/account">Support Email</a> is configured in Tenant Settings.</td>
    </tr>

    <tr>
      <td>Support URL is configured</td>
      <td>Ensures the <a href="https://manage.auth0.com/#/account">Support URL</a> is configured in Tenant Settings.</td>
    </tr>

    <tr>
      <td>Tenant Environment Tag should be configured</td>
      <td>Ensures the <a href="https://support.auth0.com/tenants/public">tenant environment tag</a> is set appropriately to Production, Staging, or Development. Changes to this tag affect your tenant's rate limit.</td>
    </tr>

    <tr>
      <td>Tenant is set to use a recommended default <a href="/docs/troubleshoot/product-lifecycle/deprecations-and-migrations/migrate-actions-nodejs-16-to-nodejs-18ions-nodejs-16-to-nodejs-18">NodeJS version</a></td>
      <td>Update your tenant to a <a href="/docs/troubleshoot/product-lifecycle/past-migrations/migrate-nodejs-16-to-nodejs-18">recommended version of NodeJS</a> to take advantage of security patches and new features.</td>
    </tr>

    <tr>
      <td>Tenant Login URI</td>
      <td>Ensures that <a href="https://manage.auth0.com/#/tenant/advanced">Tenant Login URI</a> is configured in Tenant Settings.</td>
    </tr>

    <tr>
      <td>Use Custom Domain in Branded Email Templates</td>
      <td>Ensure your emails templates use a <a href="/docs/customize/custom-domains/configure-features-to-use-custom-domains#use-custom-domains-in-emails">custom domain</a>. We strongly recommend customizing all user-facing emails to use your custom domain and company branding.</td>
    </tr>
  </tbody>
</table>

## Learn more

* [Production Readiness Checks: Non-Critical Fixes](/docs/deploy-monitor/pre-deployment-checks/production-check-recommended-fixes)
* [Production Readiness Checks: Best Practices](/docs/deploy-monitor/pre-deployment-checks/production-checks-best-practices)


# Production Readiness Checks: Best Practices
Source: https://auth0.com/docs/deploy-monitor/pre-deployment-checks/production-checks-best-practices

Checks to ensure that your Applications comply with Auth0 best practices

The following checks cannot be automated, so we recommend manually checking these areas prior to deployment to Production.

<table>
  <thead>
    <tr>
      <th>Check</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Externalize <a href="/docs/authenticate/database-connections/custom-db">Configuration Parameters</a></td>
      <td><a href="https://manage.auth0.com/#/connections/database">Externalize, instead of hard code, all configuration parameters</a>, such as credentials, connection strings, API keys, and so on, when developing Rules, Hooks, or custom database connections.</td>
    </tr>

    <tr>
      <td>Review the <Tooltip href="/docs/glossary?term=Single+Sign-on+%28SSO%29">Single Sign-on (SSO)</Tooltip> Timeout Values</td>
      <td>Review the default <a href="https://manage.auth0.com/#/account/advanced">SSO cookie timeout values</a> and ensure they align with your requirements.</td>
    </tr>

    <tr>
      <td>Tenants and Administrators</td>
      <td>Review all tenants and tenant administrators to ensure they are correct. Decommission tenants that are no longer in use. Ensure that tenant administrators are limited to the necessary users.</td>
    </tr>

    <tr>
      <td>Verify Client IDs in App Code</td>
      <td>Ensure that the Client IDs in your application code align with their Auth0 Application configurations.</td>
    </tr>

    <tr>
      <td>Add Auth0 Public IPs to Allowlist</td>
      <td>Allowlist Auth0 IPs if you're connecting to internal services or services behind a firewall when using Rules, Hooks, or custom databases. You can get a list of IP addresses in the tool tip when configuring any of these items.</td>
    </tr>

    <tr>
      <td>Review Attack Protection</td>
      <td>It is recommended that you <a href="/docs/secure/attack-protection">review Auth0 Protection capability and configuration</a>.</td>
    </tr>
  </tbody>
</table>

## Learn more

* [Production Readiness Checks: Critical Fixes](/docs/deploy-monitor/pre-deployment-checks/production-check-required-fixes)
* [Production Readiness Checks: Non-Critical Fixes](/docs/deploy-monitor/pre-deployment-checks/production-check-recommended-fixes)
* [Get Management API Access Tokens for Production](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production)


# Token Vault
Source: https://auth0.com/docs/secure/call-apis-on-users-behalf/token-vault

Learn how Token Vault securely stores the access and refresh tokens of supported external providers.

Token Vault simplifies how your applications access external APIs on a user's behalf. When you integrate with Token Vault, you gain a secure way to manage application access to a wide range of external services and their APIs, such as Google, GitHub, and Microsoft.

When a user connects with a [supported external provider](#supported-external-providers) and authorizes access using <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> scopes, Auth0 automatically adds that connected account to the user profile. A connected account enables applications to access external APIs using a unified Auth0 user profile. To learn more, read [Connected Accounts for Token Vault](/docs/secure/tokens/token-vault/connected-accounts-for-token-vault).

Auth0 stores the access and refresh tokens for each connected account in the Token Vault. To retrieve these stored credentials from Token Vault, your application performs a [secure token exchange](#supported-token-exchanges). This token exchange enables your application to get the necessary tokens to call an external API, removing the need for you to build and maintain custom integrations with each provider.

## Supported external providers

Token Vault supports popular external providers, including:

### Social

* Google
* Microsoft
* Box
* Slack
* GitHub
* Custom social connection

### Enterprise

* Google Workspace
* Microsoft Azure AD (Entra ID)
* <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect

To see the full list of supported external providers, read [Auth0 Integrations](https://auth0.com/ai/docs/integrations/overview).

## Common use cases

Common Token Vault use cases include:

* An AI agent running as a web application calls external APIs to perform tasks on the user’s behalf, such as scheduling a meeting in Google Calendar.
* An internal or backend service can access Token Vault to exchange an Auth0 access token for an external provider’s access token to call external APIs.

## How it works

When a user connects with a supported external provider and authorizes the connection:

* Auth0 obtains access and refresh tokens using OAuth 2.0 scopes, with the user explicitly approving the requested permissions.
* Auth0 securely stores the tokens for each connected account in the Token Vault. Because each connected account is linked to the user profile, the application can access external APIs and services without requiring the user to re-authorize the connection.
* The application calls Auth0 to exchange a user’s valid Auth0 token for an external provider’s access token, issued to that user. To learn more, read [Supported token exchanges](#supported-token-exchanges).
* Using the external provider’s access token, your application can then call external APIs on the user's behalf.

## Supported token exchanges

To call an external provider’s APIs, your application must exchange a valid Auth0 token for an external provider’s access token from Token Vault. The type of Auth0 token used for the exchange depends on your client application type and use case.

Applications can access Token Vault using the following token exchanges:

<table>
  <thead>
    <tr>
      <th><strong>Token exchange</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Client application type</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/secure/tokens/token-vault/refresh-token-exchange-with-token-vault">Refresh token exchange</a></td>
      <td>Exchanges an Auth0 refresh token for an external provider’s access token.</td>
      <td>Applications that need to maintain a user's session and access external APIs when the user isn't actively using the application, such as web, mobile, and native applications.</td>
    </tr>

    <tr>
      <td><a href="/docs/secure/tokens/token-vault/access-token-exchange-with-token-vault">Access token exchange</a></td>
      <td>Exchanges an Auth0 access token for an external provider’s access token.</td>
      <td>APIs or microservices that need to exchange access tokens they’ve received from other services or applications, such as a Single-Page Application (SPA).</td>
    </tr>

    <tr>
      <td><a href="/docs/secure/tokens/token-vault/privileged-worker-token-exchange-with-token-vault">Privileged worker token exchange</a></td>
      <td>Exchanges a signed JWT bearer token for an external provider’s access or refresh token.</td>
      <td>Backend applications or service workers in service-to-service (M2M) flows.</td>
    </tr>
  </tbody>
</table>

## Get started

To get started with Token Vault, read the following:

<table>
  <thead>
    <tr>
      <th><strong>Read…</strong></th>
      <th><strong>To learn…</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/secure/tokens/token-vault/connected-accounts-for-token-vault">Connected Accounts for Token Vault</a></td>
      <td>How to configure and use Connected Accounts for Token Vault.</td>
    </tr>

    <tr>
      <td><a href="/docs/secure/tokens/token-vault/refresh-token-exchange-with-token-vault">Refresh Token Exchange with Token Vault</a></td>
      <td>How an application uses the refresh token exchange with Token Vault to call external APIs.</td>
    </tr>

    <tr>
      <td><a href="/docs/secure/tokens/token-vault/access-token-exchange-with-token-vault">Access Token Exchange with Token Vault</a></td>
      <td>How an application uses the access token exchange with Token Vault to call external APIs.</td>
    </tr>

    <tr>
      <td><a href="/docs/secure/tokens/token-vault/privileged-worker-token-exchange-with-token-vault">Privileged Worker Token Exchange with Token Vault</a></td>
      <td>How an application uses the privileged worker token exchange with Token Vault to call external APIs.</td>
    </tr>

    <tr>
      <td><a href="/docs/secure/tokens/token-vault/configure-token-vault">Configure Token Vault</a></td>
      <td>How to configure the Token Vault, including the token exchange.</td>
    </tr>
  </tbody>
</table>


# Access Token Exchange with Token Vault
Source: https://auth0.com/docs/secure/call-apis-on-users-behalf/token-vault/access-token-exchange-with-token-vault

Learn how an application can access the Token Vault to exchange an Auth0 access token for an access token to call external APIs.

Token Vault supports the access token exchange, which enables a client application to exchange an Auth0 access token (subject token) for an external provider’s access token (requested token).

When a Single-Page Application (SPA) calls a backend API, it only passes an Auth0 access token in the `Authorization` header. Because the backend API does not receive any refresh tokens issued to the SPA, it cannot use the [refresh token exchange](/docs/secure/tokens/token-vault/refresh-token-exchange-with-token-vault) to access the Token Vault to call external APIs.

Instead, the backend API can exchange the Auth0 access token received from the SPA for an external provider’s access token, otherwise known as the access token exchange. This process keeps the sensitive external credentials secure on the backend.

In Auth0’s access token exchange, the backend API acts as both a client and a resource server:

* Client: Uses its own credentials to securely perform the access token exchange with the Auth0 Authorization Server. In Auth0, you create a Custom API Client with the same identifier as the backend API. The backend API passes the Custom API Client’s credentials to securely perform the access token exchange with the Auth0 Authorization Server.
* Resource server: Serves the backend API to the SPA and validates the Auth0 access token.

By acting as the intermediary between the SPA and Auth0 Authorization Server, the backend API prevents unauthorized clients from stealing the Auth0 token and using it to access the external provider on the user's behalf.

## Use cases

Common use cases for the access token exchange include:

* A backend API: A user interacts with an SPA, which then calls a backend API to exchange an Auth0 access token for an external provider’s access token with the Auth0 Authorization Server.
* Microservice architecture: Backend services, such as MCP servers or other OAuth 2.0 resource servers, that need to exchange access tokens to access external APIs.

## How it works

The following sequence diagram describes end-to-end how to call external APIs using the access token exchange in Auth0:

<Frame>
  <img alt="" />
</Frame>

Let’s walk through a real-world example: A user wants to schedule a meeting in their Google Calendar using an SPA.

## Prerequisites

Before getting started, you must [configure the access token exchange with Token Vault](/docs/secure/tokens/token-vault/configure-token-vault#configure-access-token-exchange).

## Step 1: Connect and authorize access

To schedule the meeting, the SPA needs to connect with Google via Auth0 and then receive the user’s permission to access the Google Calendar API.
The user logs into the application via Google with the [Connected Accounts flow](/docs/secure/tokens/token-vault/connected-accounts-for-token-vault#how-it-works), which uses the [My Account API](/docs/manage-users/my-account-api).

After the My Account API validates and completes the Connected Accounts request, it stores the Google access and refresh tokens with the requested calendar scopes in the Token Vault.

## Step 2: SPA calls backend API with Auth0 access token

When the SPA calls the backend API, it passes the Auth0 access token in the `Authorization` header to the backend API. The backend API validates the Auth0 access token by checking the following:

* Signature: Verify the token's signature using Auth0's public key. This confirms that Auth0 issued the access token.
* Issuer: Checks the `iss` claim in the token's payload to confirm that the token was issued by your Auth0 tenant.
* Audience: Checks the `aud` claim to ensure it matches the unique identifier of the backend API itself. This confirms that the token was specifically issued for this resource server.
* Expiration: Validates the `exp` claim to ensure the token is still valid and has not expired.
* Scopes: Checks the `scope` claim to determine what permissions the user has been granted.

After successfully completing these checks, the backend API can trust the Auth0 access token and proceed with the token exchange.

## Step 3: Backend API performs access token exchange

For the access token exchange, you need to [create a Custom API Client](/docs/secure/tokens/token-vault/configure-token-vault#create-custom-api-client) linked to the backend API. The Custom API Client has the same identifier as your backend API and has the Token Vault grant type enabled.

When the backend API performs the access token exchange, it authenticates itself by passing the Custom API Client’s credentials to the Auth0 Authorization Server, proving that it is the same entity that was registered in the Auth0 Dashboard.

To perform the access token exchange, the backend API calls Auth0 SDKs to make a `POST` request to the `/oauth/token` endpoint.

In the token request, the backend API:

* Passes the backend API’s (the Custom API Client’s) client credentials to the Auth0 Authorization Server to authenticate itself.
* Exchange an Auth0 access token for a Google access token.

```bash lines theme={null}
curl --request POST 'https://{yourDomain}/oauth/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "<YOUR_CUSTOM_API_CLIENT_ID>",
    "client_secret": "<YOUR_CUSTOM_API_CLIENT_SECRET>",
    "subject_token": "<YOUR_AUTH0_ACCESS_TOKEN>",
    "grant_type": "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token",
    "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "requested_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token",
    "connection": "google-oauth2"
  }'
```

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td>The grant type. For Token Vault, set to <code>urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token</code></td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Client application ID</td>
    </tr>

    <tr>
      <td><code>client\_secret</code></td>
      <td>Client secret. <strong>Note:</strong> You can use any client authentication method to get an external provider's access token.</td>
    </tr>

    <tr>
      <td><code>subject\_token\_type</code></td>
      <td>Type of subject token. For the access token exchange, set to the access token: <code>urn:ietf:params:oauth:token-type:access\_token</code>.</td>
    </tr>

    <tr>
      <td><code>subject\_token</code></td>
      <td>The Auth0 access token that the Auth0 Authorization Server validates to identify the user.</td>
    </tr>

    <tr>
      <td><code>requested\_token\_type</code></td>
      <td>The requested token type. For Token Vault, set to the external provider's access token or <code>[http://auth0.com/oauth/token-type/federated-connection-access-token](http://auth0.com/oauth/token-type/federated-connection-access-token)</code></td>
    </tr>

    <tr>
      <td><code>connection</code></td>
      <td>The connection name, in this case, <code>google-oauth2</code>.</td>
    </tr>

    <tr>
      <td><code>login\_hint</code></td>
      <td>(Optional) Only use `login_hint` if the user has several accounts from the same connection, such as a work Google account and personal Google account. When you pass in a value for the `login_hint` during the token exchange, you are explicitly identifying which of the user's multiple linked accounts the request is for.</td>
    </tr>
  </tbody>
</table>

## Step 4: Auth0 Authorization Server validates access token

The Auth0 Authorization Server validates and loads the user profile associated with the Auth0 access token:

* Auth0 verifies that the client making the access token exchange request is linked to the backend API identified by the `audience` of the access token.
* Auth0 checks if the user profile’s `connected_accounts` array contains a user account with the connection name passed in the authorization request.
* If the authorization request contains `login_hint`, Auth0 looks for an identity matching both the connection name and the `login_hint`.
* If Auth0 can’t find the user, it returns a `401` status code with an error message.

Once the Auth0 Authorization Server validates the user, it locates the Google access token within the Token Vault. If it is still valid, Auth0 returns the Google access token with its scopes and expiry time:

```json lines theme={null}
{
  "access_token": "<YOUR_GOOGLE_ACCESS_TOKEN>",
  "scope": "https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.addons.execute https://www.googleapis.com/auth/calendar.events https://www.googleapis.com/auth/calendar.events.readonly https://www.googleapis.com/auth/calendar.settings.readonly https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile openid",
  "expires_in": 1377,
  "issued_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token",
  "token_type": "Bearer"
}
```

Using the Google access token, the backend API calls the Google Calendar API on the user’s behalf to schedule the meeting.


# Configure Token Vault
Source: https://auth0.com/docs/secure/call-apis-on-users-behalf/token-vault/configure-token-vault

Learn how to configure Token Vault.

Once a user authenticates with a [supported external provider](/docs/secure/tokens/token-vault#supported-external-providers) and authorizes the connection, your application can access Token Vault to exchange an Auth0 token for an extenal provider's access token.

To configure Token Vault, you need to:

1. [Configure Connected Accounts for Token Vault](/docs/secure/tokens/token-vault/configure-token-vault#configure-connected-accounts-for-token-vault) for a supported social or enterprise connection.
2. [Configure your application](#configure-application) with the Token Vault grant type.
3. Configure the token exchange for your application:
   * [Refresh token exchange](#configure-refresh-token-exchange)
   * [Access token exchange](#configure-access-token-exchange)

<Callout icon="file-lines">
  If you have previously set your MFA policy to **Always** in the Auth0 Dashboard, you need to set it to **Never** to retrieve an access token from Token Vault. Otherwise, you will receive an error. To learn more about the different MFA policies, read [Enable MFA in the Auth0 Dashboard](/docs/secure/multi-factor-authentication/enable-mfa#enable-mfa-in-the-auth0-dashboard).

  If you need to trigger MFA challenges for interactive flows, enable **Customize MFA Factors using Actions** when [setting up MFA for your tenant](/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-selection-universal-login#prepare-your-tenant). You can then use an Action to trigger an MFA challenge based on the `event.transaction.protocol` property. To learn more, read [Customize MFA selection for Universal Login](/docs/secure/multi-factor-authentication/customize-mfa/customize-mfa-selection-universal-login).
</Callout>

## Configure Connected Accounts for Token Vault

Connected Accounts for Token Vault manages a unified Auth0 user profile linked to multiple external accounts. Your application then fetches the stored credentials in Token Vault to interact with external APIs on the user’s behalf.

You can configure Connected Accounts for supported social and enterprise connections. To learn more, read [Configure Connected Accounts](/docs/secure/tokens/token-vault/connected-accounts-for-token-vault#configure-connected-accounts).

## Configure application

Configure your application with the Token Vault grant type using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

Only certain types of clients can use the Token Vault grant type:

1. The client must be a first-party client, i.e. the `is_first_party` property is `true`.
2. The client must be a confidential client with a valid authentication mechanism, i.e. the `token_endpoint_auth_method` property must not be set to `none`.
3. The client must be OIDC conformant, i.e. the `oidc_conformant` must be `true`.

<Tabs>
  <Tab title="Auth0 Dashboard">
    1) Navigate to **Applications > Applications**.
    2) Select the application you want to configure.
    3) Under **Advanced Settings > Grant Types**, select the **Token Vault** grant type.
    4) Select **Save Changes**.

    <Frame>
      <img alt="" />
    </Frame>
  </Tab>

  <Tab title="Management API">
    To enable Token Vault for an application, make a `PATCH` call to the [Update a Client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) endpoint to add the `urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token` grant type to the client JSON object:

    ```bash lines theme={null}
    curl --location --request PATCH 'https://{yourDomain}/api/v2/clients/{clientId}' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>' \
      --data '{
        "grant_types": [
          "authorization_code",
          "refresh_token",
          "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token"
        ]
      }'
    ```
  </Tab>
</Tabs>

## Configure token exchange

To call an external provider’s APIs, your application must exchange a valid Auth0 token for an external provider’s access token from Token Vault. The type of Auth0 token used for the exchange depends on your client type and use case. To learn more, read [Supported token exchanges](/docs/secure/tokens/token-vault#supported-token-exchanges).

### Configure refresh token exchange

To use the [refresh token exchange with Token Vault](/docs/secure/tokens/token-vault/refresh-token-exchange-with-token-vault), you need to configure your application with the following grant types:

* Authorization Code: Enables your application to perform the initial user login, where your application exchanges a temporary authorization code for an Auth0 access token, refresh token, and ID token.
* Refresh token: Enables your application to use a long-lived Auth0 refresh token to request a new Auth0 access token without requiring the user to log in again.
* Token Vault: Enables your application to exchange an Auth0 refresh token for an external provider’s access token stored in the Token Vault.

<Tabs>
  <Tab title="Auth0 Dashboard">
    To configure your application for the refresh token exchange:

    * Navigate to **Applications > Applications**.
    * Select the application you want to configure.
    * Under **Advanced Settings > Grant Types**, select the **Refresh Token**, **Authorization Code**, and **Token Vault** grant types.
    * Select **Save Changes**.
  </Tab>

  <Tab title="Management API">
    To configure your application for the refresh token exchange, make a `PATCH` call to the [Update a Client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) endpoint to add the `refresh_token`, `authorization_code,` and `urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token` grant types to the client JSON object:

    ```bash lines theme={null}
    curl --location --request PATCH 'https://{yourDomain}/api/v2/clients/{clientId}' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>' \
      --data '{
        "grant_types": [
          "authorization_code",
          "refresh_token",
          "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token"
        ]
      }'
    ```
  </Tab>
</Tabs>

### Configure access token exchange

To use the [access token exchange with Token Vault](/docs/secure/tokens/token-vault/access-token-exchange-with-token-vault), you need to:

* [Configure your SPA](#configure-your-spa) with the `authorization_code` grant type.
* [Create a backend API](#create-backend-api) that the SPA can request an Auth0 access token for by specifying it as the audience.
* [Create a Custom API Client](#create-custom-api-client) that is linked to the backend API with the Token Vault grant type enabled.

#### Configure your SPA

Configure your SPA with the `authorization_code` grant type. This enables the SPA to request an Auth0 access token scoped to the backend API from the Auth0 Authorization Server.

<Tabs>
  <Tab title="Auth0 Dashboard">
    To configure your SPA with the `authorization_code` grant type:

    * Navigate to **Applications > Applications**.
    * Select the application you want to configure.
    * Under **Advanced Settings > Grant Types**, select the **Authorization Code** grant type.
    * Select **Save Changes**.
  </Tab>

  <Tab title="Management API">
    To configure your SPA, make a `PATCH` call to the [Update a Client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) endpoint to add the `authorization_code` grant type to the client JSON object:

    ```bash lines theme={null}
    curl --request PATCH 'https://{yourDomain}/api/v2/clients/{clientId}' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
      --data '{
        "grant_types": [
          "authorization_code"
        ]
      }'
    ```
  </Tab>
</Tabs>

#### Create backend API

Create a backend API with a unique identifier and the desired scopes that will perform the access token exchange with the Auth0 Authorization Server.

<Tabs>
  <Tab title="Auth0 Dashboard">
    To create a backend API in the Auth0 Dashboard:

    * Navigate to **Applications > APIs**, and click **Create API**.
    * To create your API, follow the instructions in [Register APIs](/docs/get-started/auth0-overview/set-up-apis). **Note:** Once you set an identifier for your API, you cannot change it.
    * Click **Create**.
    * Once you’ve created your API, you need to add scopes for the API. Navigate to the **Permissions** tab. Under **Add a Permission**, add your scopes.
  </Tab>

  <Tab title="Management API">
    To create a backend API using the Management API, make a `POST` request to the `/resource-servers` endpoint:

    ```bash lines  theme={null}
    curl --request POST 'https://{yourDomain}/api/v2/resource-servers' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
      --data '{
        "name": "My API Resource Server",
        "identifier": "https://my-api.example.com",
        "scopes": [
          {
            "value": "read:calendar",
            "description": "Read calendar events"
          },
          {
            "value": "write:calendar",
            "description": "Write calendar events"
          }
        ]
      }'
    ```
  </Tab>
</Tabs>

#### Create Custom API Client

For the access token exchange, you need to create a Custom API Client linked to the backend API. The SPA will be able to request an access token to the backend API by specifying it as the audience in the authorization request to the Auth0 Authorization Server. The Custom API Client has the same identifier as your backend API and has the Token Vault grant type enabled.

When the backend API performs the access token exchange, it authenticates itself by passing the Custom API Client’s credentials to the Auth0 Authorization Server, proving that it is the same entity that was registered in the Auth0 Dashboard.

<Tabs>
  <Tab title="Auth0 Dashboard">
    To create a Custom API Client in the Auth0 Dashboard:

    * Navigate to **Applications > APIs** and select your backend API.
    * Select **Add Application** and enter an application name.
    * Click **Add**. Once the application has been successfully created, click **Configure Application** and scroll to **Application Properties**. The **Application Type** is a Custom API Client.
    * Under **Advanced Settings > Grant Types**, the **Token Vault** grant type should already be enabled for the Custom API Client.

    <Frame>
      <img alt="" />
    </Frame>
  </Tab>

  <Tab title="Management API">
    The following code sample creates a Custom API Client with the same identifier as your backend API and adds the Token Vault grant type:

    ```bash lines theme={null}
    curl --request POST 'https://{yourDomain}/api/v2/clients' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
      --data '{
        "name": "Custom API Client",
        "app_type": "resource_server",
        "resource_server_identifier": "https://my-api.example.com",
        "grant_types": [
          "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token"
        ]
      }'
    ```

    <table>
      <thead>
        <tr>
          <th><strong>Parameter</strong></th>
          <th><strong>Description</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><code>name</code></td>
          <td>Name of your Custom API Client.</td>
        </tr>

        <tr>
          <td><code>app\_type</code></td>
          <td>The application type of your Custom API Client. To register the client as a resource server, set to <code>resource\_server</code>.</td>
        </tr>

        <tr>
          <td><code>resource\_server\_identifier</code></td>
          <td>The unique identifier for your Custom API Client. Set to the audience of your backend API i.e. `https://my-api.example.com.`</td>
        </tr>

        <tr>
          <td><code>grant\_types</code></td>
          <td>The grant types enabled for your Custom API Client. Set to the Token Vault grant type: `urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token`.</td>
        </tr>
      </tbody>
    </table>
  </Tab>
</Tabs>

Once you’ve successfully created the Custom API Client, the user will be redirected to it instead of the SPA after logging in.


# Connected Accounts for Token Vault
Source: https://auth0.com/docs/secure/call-apis-on-users-behalf/token-vault/connected-accounts-for-token-vault

Learn how to configure and use Connected Accounts for Token Vault.

Connected Accounts for Token Vault enables applications to securely access external APIs on the user’s behalf through [Token Vault](/docs/secure/tokens/token-vault). While standard user authentication handles user login through a social or enterprise identity provider, Connected Accounts links a user profile to external services like Google, GitHub, Slack, and more, facilitating delegated access to external APIs on the user’s behalf.

Once a user successfully connects and authorizes access to a [supported external provider](/docs/secure/tokens/token-vault#supported-external-providers), Auth0:

* Associates the account with the user as a connected account.
* Stores the external provider’s access and refresh tokens for the connected account in the Token Vault.

Connected Accounts for Token Vault creates and manages a unified Auth0 user profile linked to multiple external accounts, enabling seamless authorization. Your application then fetches the stored credentials in Token Vault to interact with external APIs on the user’s behalf.

## User authentication vs Connected Accounts

When you [configure Connected Accounts](#configure-connected-accounts) for a supported social or enterprise connection, Auth0 uses the Connected Accounts flow (`/me/v1/connected-accounts` endpoint) to retrieve and store access and refresh tokens in the Token Vault instead of using the social or enterprise login flow (`/authorize` endpoint). After successfully completing the Connected Accounts flow, Auth0 adds the user account to the `connected_accounts` array on the user profile. In contrast, for the social or enterprise login flow, Auth0 adds the user account to the `identities` array on the user profile.

The following table explains the differences between the user authentication and Connected Accounts flows:

<table>
  <thead>
    <tr>
      <th />

      <th><strong>User Authentication</strong></th>
      <th><strong>Connected Accounts</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Flow</td>
      <td>Login flow using the `/authorize` endpoint</td>
      <td>Connected Accounts flow using the My Account API’s `/me/v1/connected-accounts` endpoint</td>
    </tr>

    <tr>
      <td>Purpose</td>
      <td>Authenticates users with a social or enterprise identity provider</td>
      <td>Stores the access and refresh tokens for the connected account in Token Vault when a user logs in via a supported external provider, connects, and authorizes the connection</td>
    </tr>
  </tbody>
</table>

You can enable user authentication, Connected Accounts, or both for supported social or enterprise connections. The following table explains the behavior for the different Purpose settings, including how to pass scopes to the connection:

<table>
  <thead>
    <tr>
      <th><strong>Authentication</strong></th>
      <th><strong>Connected Accounts</strong></th>
      <th><strong>Behavior</strong></th>
      <th><strong>Scopes</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Enabled</td>
      <td>Disabled</td>
      <td>The connection uses the `/authorize` login flow to authenticate users as a valid identity provider.</td>
      <td>Use the Auth0 Dashboard or Management API to pass the desired scopes for your connection. At runtime, this list is automatically completed with any additional scopes included in the `connection_scope` parameter of the authorization request.</td>
    </tr>

    <tr>
      <td>Disabled</td>
      <td>Enabled</td>
      <td>The connection uses the Connected Accounts flow to retrieve and store the tokens for the connection in the Token Vault. The connection does not use the `/authorize` login flow to authenticate users, and is excluded from the list of valid identity providers.</td>
      <td>Use the Auth0 Dashboard or Management API to pass the desired scopes to your connection. At runtime, any scopes included in the `scopes` parameter in the authorization request take precedence over the scopes selected in the Auth0 Dashboard except for `offline_access`, if required by the connection and enabled in the Auth0 Dashboard.<br /><br /><strong>Note:</strong> If required by the connection, Auth0 will prompt you to enable `offline_access`, allowing the client application to fetch a refresh token from Auth0. You must enable `offline_access` for the connection in the Auth0 Dashboard.</td>
    </tr>

    <tr>
      <td>Enabled</td>
      <td>Enabled</td>
      <td>The connection uses the `/authorize` login flow to authenticate users as a valid identity provider. It also uses the Connected Accounts flow to retrieve and store access tokens for the connection in the Token Vault.</td>
      <td>Use the Auth0 Dashboard and Management API to pass the desired scopes to the connection. At runtime, any scopes included in the `scopes` parameter take precedence over the scopes selected in the Auth0 Dashboard except for `offline_access`, if required by the connection and enabled in the Auth0 Dashboard.<br /><br /><strong>Note:</strong> If required by the connection, Auth0 will prompt you to enable `offline_access`, allowing the client application to fetch a refresh token from Auth0. You must enable `offline_access` for the connection in the Auth0 Dashboard.</td>
    </tr>
  </tbody>
</table>

## How it works

The Connected Accounts flow uses the [My Account API](/docs/manage-users/my-account-api) to create and manage connected accounts for a user across supported external providers.

Before the user can initiate a Connected Accounts request from the client application, the client application needs to [get an access token](/docs/manage-users/my-account-api#get-an-access-token) with the Connected Accounts scopes to access the My Account API.

The following sequence diagram illustrates the end-to-end Connected Accounts flow:

<Frame>
  <img alt="" />
</Frame>

When a user logs in via a supported external provider through Auth0, they initiate a Connected Accounts request from the client application:

1. The client application makes a `POST` request to the My Account API’s `/me/v1/connected-accounts` endpoint, passing scopes and other parameters to send to the external provider. To learn more, read [Initiate Connected Accounts request](#initiate-connected-accounts-request).
2. The My Account API creates a unique `auth_session` and `connect_uri` containing a `ticket` that redirects the user to a web browser. The client application saves the `auth_session` for later verification. If [DPoP](/docs/secure/sender-constraining/demonstrating-proof-of-possession-dpop) is configured, the My Account API validates the DPoP Proof JWT.
3. The client application redirects the user to the `connect_uri` with the `ticket` as a query parameter for user authentication and authorization in the browser. The client application may also pass a `code_challenge` or `code_challenge_method` to the URL, as in the [Authorization Code Flow with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce).
4. The user connects and authorizes the permissions for the connection in the consent screen.
5. After the user successfully authorizes the connection, the external provider redirects the user to the My Account API, which redirects the user to the client application using the `redirect_uri` with a single-use `connect_code`.
6. The client application presents the `connect_code`, `code_verifier` (if applicable), and the original `auth_session` to the My Account API by making a `POST` request to the `/me/v1/connected-accounts/complete` endpoint. To learn more, read [Complete Connected Accounts request](#complete-connected-accounts-request).
7. The My Account API validates the request by confirming:
   * The `auth_session` matches the ID originally issued for the user
   * The request is coming from the same device that initiated the Connected Accounts flow
   * The DPoP Proof JWT (if configured)
   * The single-use `connect_code`
   * The `code_verifier` (if using the PKCE flow)
8. After successful validation, the Auth0 Authorization Server adds the account to the `connected_accounts` array on the user profile and stores the access and refresh tokens for the connected account in the Token Vault.
9. My Account API completes the flow by sending a `200` status code back to the client application, indicating that the account was successfully connected.

## Prerequisites

Before configuring Connected Accounts, make sure you:

* [Configure Token Vault](/docs/secure/tokens/token-vault/configure-token-vault) for your client application to securely store the access and refresh tokens associated with each connected account in the Token Vault.
* [Configure the My Account API](#configure-my-account-api), which is used by authenticated users to connect and manage accounts.
* [Configure Multi-Resource Refresh Token (MRRT)](#configure-multi-resource-refresh-token) to get an access token for the My Account API.
* (Optional) [Configure DPoP](/docs/secure/sender-constraining/configure-sender-constraining) for the My Account API and your client application to sender constrain access tokens, preventing token theft. By default, the My Account API can accept DPoP-bound access tokens.

### Configure My Account API

To use Connected Accounts, configure the My Account API in the Auth0 Dashboard:

1. Navigate to **Applications > APIs** and [activate the My Account API](/docs/manage-users/my-account-api#activate-the-my-account-api).
2. Once activated, select **Auth0 My Account API** and then the **Application Access** tab.
3. Find your client application and select **Edit** to configure its [application access policies](/docs/get-started/apis/api-access-policies-for-applications).
4. Select **User Access** and under **Authorization**, select **Authorized**.
5. For the permissions, select **All** the [Connected Accounts scopes](/docs/manage-users/my-account-api#scope) for the application.
6. Select **Save**. This creates a [client grant](/docs/get-started/applications/application-access-to-apis-client-grants) that allows your client application to access the My Account API with the Connected Accounts scopes on the user’s behalf.
7. If you’re using [Multi-Resource Refresh Token](/docs/secure/tokens/refresh-tokens/multi-resource-refresh-token#multi-resource-refresh-token), navigate to the **Settings** tab. Under **Access Settings**, select **Allow Skipping User Consent**.

### Configure Multi-Resource Refresh Token

Configure Multi-Resource Refresh Token (MRRT) to get a single long-lived refresh token that can be exchanged for new My Account API access tokens and other APIs without requiring the user to re-authenticate.

You can configure MRRT with the [Auth0 Dashboard](https://manage.auth0.com) or the [Management API](https://auth0.com/docs/api/management/v2).

<Tabs>
  <Tab title="Auth0 Dashboard">
    To configure MRRT with the Auth0 Dashboard:

    1. Navigate to **Applications > Applications** and select your application.
    2. Under **Multi-Resource Refresh Token**, select **Edit Configuration**.
    3. To enable MRRT with the My Account API, toggle on the **My Account API**.
  </Tab>

  <Tab title="Management API">
    To configure MRRT for a client application, make a `PATCH` request to the `/api/v2/clients/{clientId}` endpoint and add the My Account API identifier and Connected Accounts scopes to the refresh token policies:

    ```bash lines theme={null}
    curl -X PATCH --location "https://${account.namespace}/api/v2/clients/{clientId}" \
        -H "Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>" \
        -H "Content-Type: application/json" \
        -d '{
              "is_first_party": true,
              "refresh_token": {
                "expiration_type": "non-expiring",
                "leeway": 0,
                "infinite_token_lifetime": true,
                "infinite_idle_token_lifetime": true,
                "token_lifetime": 31557600,
                "idle_token_lifetime": 2592000,
                "rotation_type": "non-rotating",
                "policies": [
                  {
                    "audience": "https://'"$DOMAIN"'/me/",
                    "scope": [
                      "create:me:connected_accounts",
                      "read:me:connected_accounts",
                      "delete:me:connected_accounts"
                    ]
                  }
                ]
              }
            }'
    ```
  </Tab>
</Tabs>

## Configure Connected Accounts

Before configuring Connected Accounts for a connection, make sure you’ve authorized the connection for your client application.

In the Auth0 Dashboard:

1. Navigate to **Authentication > Social Connections** or **Enterprise Connections** and select the connection.
2. Select **Applications** and then toggle on the connection for your client application.

You can configure Connected Accounts with the [Auth0 Dashboard](https://manage.auth0.com) or the [Management API](https://auth0.com/docs/api/management/v2).

<Tabs>
  <Tab title="Auth0 Dashboard">
    To configure Connected Accounts with the Auth0 Dashboard:

    1. Navigate to **Authentication > Social Connections** or **Enterprise Connections**.
    2. Select **Create Connection** or select an existing connection.
    3. In **Purpose**, toggle on **Connected Accounts for Token Vault**. Depending on your **Purpose** setting, you may need to enable `offline_access` in the Auth0 Dashboard, allowing the client application to obtain a refresh token from the external provider during the Connected Accounts flow. To learn more, read [User authentication vs Connected Accounts](#user-authentication-vs-connected-accounts).
    4. Click **Save**.
  </Tab>

  <Tab title="Management API">
    To configure Connected Accounts with the Management API, make a `PATCH` request to the `/connections/{connectionId}` endpoint to set `connected_accounts` to `true`:

    ```bash lines theme={null}
    curl -L -X PATCH "https://{yourDomain}/api/v2/connections/{connectionId}" \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H "Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>" \
    -d '{"connected_accounts":{"active":true}}'
    ```
  </Tab>
</Tabs>

## Get access token for Connected Accounts

Before initiating a Connected Accounts request, [get an access token](/docs/manage-users/my-account-api#scope) for the My Account API with the Connected Accounts scopes.

The following sections explain how to use [Multi-Resource Refresh Token (MRRT)](/docs/secure/tokens/refresh-tokens/multi-resource-refresh-token) to get an access token for the My Account API.

### Fetch a refresh token

After [configuring MRRT](#configure-multi-resource-refresh-token) for the client application, initiate the authorization code flow and exchange the resulting authorization code for a refresh token.

The following is an authorization code flow request for a confidential client that includes the `offline_scope` to return a refresh token and a single-use authorization code for the My Account API identifier `https://{yourDomain}/me/`:

```bash lines theme={null}
open "https://{yourDomain}/authorize?client_id=<CLIENT_ID>&response_type=code&prompt=login&scope=openid%20profile%20offline_access&redirect_uri=<REDIRECT_URI>&state=<STATE>&audience=https://my-example-api.com"
```

Exchange the single-use authorization code for a refresh token at the `/token` endpoint:

```bash lines theme={null}
curl -s --request POST \
  --url "https://{yourDomain}/oauth/token" \
  --header 'Content-Type: application/json' \
  --data-binary @- <<EOF | jq -r '.refresh_token'
{
  "grant_type": "authorization_code",
  "code": "<CONNECT_CODE>",
  "scope": "openid profile offline_access",
  "client_id": "<CLIENT_ID>",
  "client_secret": "<CLIENT_SECRET>",
  "audience": "https://{yourDomain}/me/",
  "redirect_uri": "<REDIRECT_URI>"
}
EOF
```

### Exchange refresh token for My Account API access token

Once you’ve obtained a refresh token, exchange it for a My Account API access token with the Connected Accounts scopes using the refresh token grant type:

```bash lines theme={null}
curl -s -X POST "https://{yourDomain}/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "client_id=<CLIENT_ID>" \
  --data-urlencode "client_secret=<CLIENT_SECRET>" \
  --data-urlencode "refresh_token=<REFRESH_TOKEN>" \
  --data-urlencode "audience=https://{yourDomain}/me/" \
  --data-urlencode "scope=openid profile offline_access create:me:connected_accounts read:me:connected_accounts delete:me:connected_accounts"
```

## Initiate Connected Accounts request

To initiate a Connected Accounts request, make a `POST` request to the My Account API’s `/me/v1/connected-accounts/connect` endpoint with the following parameters:

<Callout icon="file-lines">
  For a Google social connection, make sure you select `offline_access` in the Auth0 Dashboard when configuring your connection. This is required for your client application to fetch a refresh token from the Auth0 Authorization Server.
</Callout>

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>connection</code></td>
      <td>Name of connection. For a Google social connection, set to <code>google-oauth2</code>.</td>
    </tr>

    <tr>
      <td><code>redirect\_uri</code></td>
      <td>The callback URL of your client application.</td>
    </tr>

    <tr>
      <td><code>state</code></td>
      <td>A unique, random string associated with the request to prevent attacks.</td>
    </tr>

    <tr>
      <td><code>scopes</code></td>
      <td>(Optional) The scopes passed to the external provider as an array of strings.<br /><br />If used to pass scopes for a Google social connection, include `openid` and `profile` at a minimum. At runtime, any scopes included in the `scopes` parameter take precedence over the scopes selected in the Auth0 Dashboard except for `offline_access`, if required by the connection and enabled in the Auth0 Dashboard.</td>
    </tr>
  </tbody>
</table>

```bash lines theme={null}
curl --request POST "https://{yourDomain}/me/v1/connected-accounts/connect" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer <MY_ACCOUNT_API_TOKEN>" \
--data '{
    "connection": "google-oauth2",
    "redirect_uri": "<REDIRECT_URI>",
    "state": "<STATE>",
    "scopes": ["openid","profile"] // any scopes passed overwrite the scopes you selected in the Auth0 Dashboard
}'
```

If successful, the My Account API returns a response like the following:

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>auth\_session</code></td>
      <td>Session ID that represents the current, authenticated session of the primary user. The client application saves the session ID for later verification.</td>
    </tr>

    <tr>
      <td><code>connect\_uri</code></td>
      <td>URL that the client application redirects the user to, which opens up a web browser to handle authorization with the external provider.</td>
    </tr>

    <tr>
      <td><code>connect\_params</code></td>
      <td>Additional parameters necessary for the connect URI. Includes a temporary ticket that the My Account API uses to verify the request.</td>
    </tr>

    <tr>
      <td><code>expires\_in</code></td>
      <td>Expiry time for the session in seconds.</td>
    </tr>
  </tbody>
</table>

```json theme={null}
{
  "auth_session": "PKM-CYkdx2FyLb4Oob4ED91cSE7i_XJ4SVJByik0xKQxz9CgUZ5JlYr-aMPty0Xr",
  "connect_uri": "https://{yourDomain}.us.auth0.com/connect",
  "connect_params": {
    "ticket": "9375f326-5846-4b57-ae8b-8042573f7c1f"
  },
  "expires_in": 300
}
```

In the web browser, navigate to the `connect_uri` with the `ticket` as a query parameter. Authorize the list of scopes in the consent screen, then extract and save the `connect_code` in the URL fragment.

```bash lines theme={null}
open https://{yourDomain}.us.auth0.com/connected-accounts/connect?ticket={tickedId}
```

## Complete Connected Accounts request

To complete a Connected Accounts request, make a `POST` request to the `/me/v1/connected-accounts/complete` endpoint with the following parameters:

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>auth\_session</code></td>
      <td>Session ID that represents the current, authenticated session of the primary user. The client application saves the session ID for later verification.</td>
    </tr>

    <tr>
      <td><code>connect\_code</code></td>
      <td>A single-use, short-lived code received from the authorization process of the external provider. This code is securely exchanged on the server-side to retrieve the final access tokens for the external API.</td>
    </tr>

    <tr>
      <td><code>redirect\_uri</code></td>
      <td>The exact callback URL of your application where the user was sent after successfully authorizing the connection with the external provider. This value must match the `redirect_uri` used to initiate the flow.</td>
    </tr>
  </tbody>
</table>

```bash lines theme={null}
curl --location "https://{yourDomain}/me/v1/connected-accounts/complete" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer <MY_ACCOUNT_API_TOKEN>" \
--data '{
    "auth_session": "<AUTH_SESSION>",
    "connect_code": "<CONNECT_CODE>",
    "redirect_uri": "<REDIRECT_URI>"
}'
```

If successful, the My Account API returns a response like the following:

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>id</code></td>
      <td>Unique identifier for the connected account.</td>
    </tr>

    <tr>
      <td><code>connection</code></td>
      <td>Name of the connection.</td>
    </tr>

    <tr>
      <td><code>created\_at</code></td>
      <td>Timestamp of when the connected account was created and linked to the user profile.</td>
    </tr>

    <tr>
      <td><code>scopes</code></td>
      <td>The specific OAuth scopes (permissions) that the user granted your application access to when connecting to the external provider. These scopes determine what external API actions your application can perform.</td>
    </tr>

    <tr>
      <td><code>access\_type</code></td>
      <td>Indicates the type of access granted. A common value is `offline`, which signifies that a refresh token was successfully obtained and stored, allowing your application to maintain access even when the user is offline.</td>
    </tr>
  </tbody>
</table>

```json theme={null}
{
  "id": "cac_6ZqSK7Kj1R8LDZJvSb1tAn",
  "connection": "google-oauth2",
  "created_at": "2025-10-13T21:09:04.126Z",
  "scopes": [
    "https://www.googleapis.com/auth/calendar",
    "https://www.googleapis.com/auth/calendar.addons.execute",
    "https://www.googleapis.com/auth/calendar.events",
    "https://www.googleapis.com/auth/calendar.events.readonly",
    "https://www.googleapis.com/auth/calendar.settings.readonly",
    "https://www.googleapis.com/auth/userinfo.profile",
    "openid"
  ],
  "access_type": "offline"
}
```

## Manage Connected Accounts

To manage a user’s connected accounts, use the `/me/v1/connected-accounts` collection.

Before using the `/connected-accounts` collection, [get an access token for Connected Accounts](#get-access-token-for-connected-accounts).

### Query connected accounts connections

Make a `GET` request to the `/me/v1/connected-accounts/connections` endpoint to return a list of connections that are linked to the user profile:

```bash lines theme={null}
curl -X GET --location "https://{yourDomain}/me/v1/connected-accounts/connections" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer <MY_ACCOUNT_API_TOKEN>"
```

If successful, the My Accounts API returns a response like the following:

```json theme={null}
{
  "connections": [
    {
      "name": "google-oauth2",
      "strategy": "google-oauth2",
      "scopes": [
        "email",
        "profile",
        "https://www.googleapis.com/auth/calendar",
        "https://www.googleapis.com/auth/calendar.events",
        "https://www.googleapis.com/auth/calendar.addons.execute",
        "https://www.googleapis.com/auth/calendar.events.readonly",
        "https://www.googleapis.com/auth/calendar.settings.readonly",
        "openid"
      ]
    },
    {
      "name": "custom",
      "strategy": "oauth2",
      "scopes": [
        "openid"
      ]
    }
  ]
}
```

### Query connected accounts

Make a `GET` request to the `/me/v1/connected-accounts/accounts` endpoint to return a list of connected accounts linked to the user profile:

```bash lines theme={null}
curl -X GET --location "https://{yourDomain}/me/v1/connected-accounts/accounts" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer <MY_ACCOUNT_API_TOKEN>"
```

If successful, the My Accounts API returns a response like the following:

```json theme={null}
{
  "accounts": [
    {
      "id": "cac_6ZqSK7Kj1R8LDZJvSb1tAn",
      "connection": "google-oauth2",
      "access_type": "offline",
      "scopes": [
        "https://www.googleapis.com/auth/calendar",
        "https://www.googleapis.com/auth/calendar.addons.execute",
        "https://www.googleapis.com/auth/calendar.events",
        "https://www.googleapis.com/auth/calendar.events.readonly",
        "https://www.googleapis.com/auth/calendar.settings.readonly",
        "https://www.googleapis.com/auth/userinfo.profile",
        "openid"
      ],
      "created_at": "2025-10-13T21:09:04.126Z"
    },
    {
      "id": "cac_fH32E6CWN7HcWZN5w9Vieq",
      "connection": "custom",
      "access_type": "offline",
      "scopes": [
        "offline_access",
        "openid",
        "profile"
      ],
      "created_at": "2025-10-13T18:06:47.216Z"
    }
  ]
}
```

You can also use the Management API to return a list of connected accounts for a user profile by making a `GET` request to the `/users/{userId}/connected-accounts` endpoint:

```bash lines theme={null}
curl -X GET --location "https://{yourDomain}/api/v2/users/{userId}/connected-accounts" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>"
```

If successful, the Management API returns a response like the following:

```json theme={null}
{
  "connected_accounts": [
    {
      "id": "cac_6ZqSK7Kj1R8LDZJvSb1tAn",
      "connection": "google-oauth2",
      "connection_id": "con_uBbSbbSpqGqOTvRu",
      "strategy": "google-oauth2",
      "access_type": "offline",
      "scopes": [
        "https://www.googleapis.com/auth/calendar",
        "https://www.googleapis.com/auth/calendar.addons.execute",
        "https://www.googleapis.com/auth/calendar.events",
        "https://www.googleapis.com/auth/calendar.events.readonly",
        "https://www.googleapis.com/auth/calendar.settings.readonly",
        "https://www.googleapis.com/auth/userinfo.profile",
        "openid"
      ],
      "created_at": "2025-10-13T21:09:04.126Z"
    }
  ]
}
```

### Query connected accounts for a given connection

Make a `GET` request to the `/me/v1/connected-accounts/accounts` endpoint and pass the connection name as a query parameter to return a list of connected accounts filtered by a given connection linked to a user profile:

```bash lines theme={null}
curl -X GET --location "https://{yourDomain}/me/v1/connected-accounts/accounts?connection={connectionName}" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer <MY_ACCOUNT_API_TOKEN>"
```

If successful, the My Accounts API returns a response like the following, filtered for `google-oauth2` connections:

```json theme={null}
{
  "accounts": [
    {
      "id": "cac_6ZqSK7Kj1R8LDZJvSb1tAn",
      "connection": "google-oauth2",
      "access_type": "offline",
      "scopes": [
        "https://www.googleapis.com/auth/calendar",
        "https://www.googleapis.com/auth/calendar.addons.execute",
        "https://www.googleapis.com/auth/calendar.events",
        "https://www.googleapis.com/auth/calendar.events.readonly",
        "https://www.googleapis.com/auth/calendar.settings.readonly",
        "https://www.googleapis.com/auth/userinfo.profile",
        "openid"
      ],
      "created_at": "2025-10-13T21:09:04.126Z"
    }
  ]
}
```

### Delete connected account

Make a `DELETE` request to the `/me/v1/connected-accounts/accounts/{connectedAccountId}` endpoint to delete a connected account for a given ID:

```bash lines theme={null}
curl -X DELETE --location "https://{yourDomain}/me/v1/connected-accounts/accounts/{connectedAccountId}" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer <MY_ACCOUNT_API_TOKEN>"
```

When you delete a connected account, Auth0 removes the external provider’s access and refresh tokens from the Token Vault. This does not automatically revoke the external provider’s tokens, and the refresh token could still be used to obtain new access tokens. You have to manually revoke the tokens for the external provider if they have been shared or copied elsewhere.

If successful, the My Accounts API returns a response like the following:

```
HTTP/1.1 204 No Content
```


# Privileged Worker Token Exchange with Token Vault
Source: https://auth0.com/docs/secure/call-apis-on-users-behalf/token-vault/privileged-worker-token-exchange-with-token-vault

Learn how an application can access the Token Vault to exchange a JWT bearer token for an access or refresh token to call external APIs.

<Callout icon="file-lines">
  Privileged Worker Token Exchange with Token Vault is currently in Beta. To learn more about Auth0’s product release cycle, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To participate in this program, contact [Auth0 Support](https://support.auth0.com/) or your Technical Account Manager.
</Callout>

Token Vault supports the Privileged Worker Token Exchange, which enables a client application to exchange a signed JWT (subject token) for an external provider’s access or refresh token (requested token).

After successful user authentication and authorization, a client application typically passes the user context, which contains the user's identity, permissions, and session state, as an access or refresh token to perform the token exchange with Token Vault. In service-to-service flows, a client application, such as a backend application or service worker, may need to access resources on the user’s behalf, but because the “user is not present” in an interactive session, the client application doesn’t have access to the user context.

In these service-to-service scenarios, the client application can generate a signed JWT bearer token and use it as the subject token to perform the token exchange and receive the necessary tokens to call external APIs. This means the client application can perform actions on the user’s behalf without an active user interaction or session.

To use the Privileged Worker Token Exchange with Token Vault, the client application must be a highly privileged client that can also request refresh tokens from external providers via Token Vault. It should authenticate with Token Vault using asymmetric cryptographic methods such as [Private Key JWT](/docs/get-started/authentication-and-authorization-flow/authenticate-with-private-key-jwt) assertion or [mutual TLS authentication](/docs/get-started/authentication-and-authorization-flow/authenticate-with-mtls).

## Prerequisites

Only certain types of clients can use the Privileged Worker Token Exchange with Token Vault:

* The client must be a first-party client, i.e. the `is_first_party property` is `true`.
* The client must be a confidential client with a valid authentication mechanism, i.e. the `token_endpoint_auth_method` property must not be set to `none`.
* The client must be OIDC conformant, i.e. the `oidc_conformant` must be `true`.

Before configuring Privileged Worker Token Exchange for your client application:

1. [Enable the Token Vault grant type](/docs/secure/tokens/token-vault/configure-token-vault#configure-application) for your client application.
2. Configure [Private Key JWT](/docs/get-started/authentication-and-authorization-flow/authenticate-with-private-key-jwt) or [mutual TLS authentication](/docs/get-started/authentication-and-authorization-flow/authenticate-with-mtls) for your client application.

## Configure client application

To configure the client application’s privileged access to Token Vault, you need to provide a public key that will be used to verify a signed JWT as the subject token.

Similar to [configuring JAR](/docs/get-started/applications/configure-jar#configure-jwt-secured-authorization-requests-jar), you can set the Token Vault privileged access public key when creating a new client:

```bash lines theme={null}
POST https://{yourDomain}.auth0.com/api/v2/clients
Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>
Content-Type: application/json
{
  "name": "My App using JAR",
   “grant_types”: [“urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token”],
     “oidc_conformant”: true,
           “is_first_party”: true,
           “jwt_configuration”: {
             “alg”: 'RS256',
           },

  "token_vault_privileged_access": {
"credentials": [{
        "name": "My credential for Token Vault Privileged Access",
        "credential_type": "public_key",
        "pem": "<YOUR PEM FILE CONTENT>",
        "alg": "RS256"
}]
  },
}
```

You can also update an existing client with the Token Vault privileged access public key:

```bash lines theme={null}
PATCH https://{yourDomain}.auth0.com/api/v2/clients/{yourClientId}
Authorization: Bearer <YOUR_MANAGEMENT_API_ACCESS_TOKEN>
Content-Type: application/json
{
  "token_vault_privileged_access": {
    "credentials": [{"id": "<YOUR CREDENTIAL ID>"}]
  }
}
```

## Create signed JWT subject token

After [configuring your client application with the public key](#configure-client-application), you need to create the subject token that will be exchanged for an access token for an external API. The subject token is a JSON Web Token (JWT) with the necessary claims. It is signed with the private key.

The JWT has a standard format and claims, where:

* Header’s `typ` is `token-vault-req+jwt`
* Header’s `kid` is optional if you have only one public key configured
* Payload’s `sub` is the user ID for whom you want to get the token for
* Payload’s `aud` is your tenant host
* Payload’s `iss` is your client ID making the request

The following is an example JWT:

```json lines theme={null}
{
    alg: "RS256"  
    typ: "token-vault-req+jwt"
}
.
{
    sub: "auth0|000012030101231",
    aud: "https://{yourDomain}.auth0.com/",
    iss: "<YOUR_CLIENT_ID>",
    iat: 1758799540,
    exp: 1758800540,
    nbf: 1758799540
}
```

The following code sample is a script that generates a signed JWT subject token:

```tsx lines theme={null}
import * as jwt from 'jsonwebtoken';
   const privateKey = ‘-----BEGIN RSA PRIVATE KEY-----........’;
   const subjectToken = jwt.sign(
     {
       iss: CLIENT_ID,
       aud: 'https://' + TENANT_DOMAIN + '/',
       sub: USER_ID,
     },
     privateKey,
     {
       algorithm: 'RS256',
       header: {
         typ: 'token-vault-req+jwt',
       },
     }
   );
```

## Request token for external API

Once you have the signed JWT, you can make a request for the access token for the external API:

```bash lines theme={null}
curl --request POST 'https://{yourDomain}/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
  "client_id": "<YOUR_CLIENT_ID>",
  "client_secret": "<YOUR_CLIENT_SECRET>",
  "subject_token": "<YOUR_SIGNED_JWT_BEARER>",
  "grant_type": "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token",
  "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
  "requested_token_type": "http://auth0.com/oauth/token-type/token-vault-access-token",
  "connection": "google-oauth2"
}'
```

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td>The grant type. For Token Vault, set to <code>urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token</code></td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Client application ID</td>
    </tr>

    <tr>
      <td><code>client\_secret</code></td>
      <td>Client secret. <strong>Note:</strong> For Privileged Worker Token Exchange, we recommend using Private Key JWT or mTLS authentication.</td>
    </tr>

    <tr>
      <td><code>subject\_token\_type</code></td>
      <td>Type of subject token. For Privileged Worker Token Exchange, set to JWT: <code>urn:ietf:params:oauth:token-type:jwt</code></td>
    </tr>

    <tr>
      <td><code>subject\_token</code></td>
      <td>The signed JWT bearer token that the Auth0 Authorization Server validates to identify the user.</td>
    </tr>

    <tr>
      <td><code>requested\_token\_type</code></td>
      <td>The requested token type. For Privileged Worker Token Exchange, you can request an access or refresh token.</td>
    </tr>

    <tr>
      <td><code>connection</code></td>
      <td>The connection name, in this case, <code>google-oauth2</code>.</td>
    </tr>
  </tbody>
</table>

You should receive the access token stored in the Token Vault. You can similarly request the refresh token for the external API:

```bash lines theme={null}
curl --request POST 'https://{yourDomain}/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
  "client_id": "<YOUR_CLIENT_ID>",
  "client_secret": "<YOUR_CLIENT_SECRET>",
  "subject_token": "<YOUR_SIGNED_JWT_BEARER>",
  "grant_type": "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token",
  "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
  "requested_token_type": "http://auth0.com/oauth/token-type/token-vault-refresh-token",
  "connection": "google-oauth2"
}'
```


# Refresh Token Exchange with Token Vault
Source: https://auth0.com/docs/secure/call-apis-on-users-behalf/token-vault/refresh-token-exchange-with-token-vault

Learn how an application can access the Token Vault to exchange an Auth0 refresh token for an access token to call external APIs.

Token Vault supports the refresh token exchange, which enables a client application to access the Token Vault to exchange an Auth0 refresh token (subject token) for an external provider’s access token (requested token).

Because refresh tokens are exchanged only on a secure backchannel between the client and the authorization server, they are never exposed to the end-user. As a result, clients can maintain a user’s session without requiring the user to re-authorize the connection.

## Use cases

Common use cases for the refresh token exchange include:

* Web application: A web-based productivity app connects to a user's Google Calendar and performs tasks on the user's behalf, such as scheduling meetings, without requiring the user to re-authenticate.
* Mobile application: A mobile photo gallery app connects to a user's Google Photos account and uploads photos as they're taken, keeping the user logged in by refreshing the access token in the background.

## How it works

The following sequence diagram describes end-to-end how to call external APIs using the refresh token exchange in Auth0:

<Frame>
  <img alt="" />
</Frame>

Let’s walk through a real-world example: A user wants to schedule a meeting in their Google Calendar using a web application.

## Prerequisites

Before getting started, you must [configure the refresh token exchange with Token Vault](/docs/secure/tokens/token-vault/configure-token-vault#configure-refresh-token-exchange).

## Step 1: Connect and authorize access

To schedule the meeting, the web application needs to connect with Google via Auth0 and then receive the user’s permission to access the Google Calendar API.

The user logs into the application via Google with the [Connected Accounts flow](/docs/secure/tokens/token-vault/connected-accounts-for-token-vault#how-it-works), which uses the [My Account API](/docs/manage-users/my-account-api). After the My Account API validates and completes the Connected Accounts request, it stores the Google access and refresh tokens with the requested calendar scopes in the Token Vault.

## Step 2: Perform refresh token exchange

<Callout icon="file-lines">
  While Token Vault does not support refresh token rotation, you can use [DPoP](/docs/secure/sender-constraining/demonstrating-proof-of-possession-dpop) to bind Auth0-issued tokens to your client for additional security. To successfully perform the refresh token exchange with Token Vault, disable Allow Refresh Token Rotation for your application in the Auth0 Dashboard.
</Callout>

The application can use a valid Auth0 refresh token to request a Google access token from the Token Vault with the scopes granted in the Connected Accounts flow. This process allows the application to get a new access token without requiring the user to re-authorize the connection.

To perform the refresh token exchange, the application calls Auth0 SDKs to make a `POST` request to the `/oauth/token` endpoint with the following parameters:

```bash lines theme={null}
curl --request POST 'https://{yourDomain}/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
  "client_id": "<YOUR_CLIENT_ID>",
  "client_secret": "<YOUR_CLIENT_SECRET>",
  "subject_token": "<YOUR_AUTH0_REFRESH_TOKEN>",
  "grant_type": "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token",
  "subject_token_type": "urn:ietf:params:oauth:token-type:refresh_token",
  "requested_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token",
  "connection": "google-oauth2"
}'
```

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td>The grant type. For Token Vault, set to <code>urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token</code></td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Client application ID</td>
    </tr>

    <tr>
      <td><code>client\_secret</code></td>
      <td>Client secret. <strong>Note:</strong> You can use any client authentication method to get an external provider's access token.</td>
    </tr>

    <tr>
      <td><code>subject\_token\_type</code></td>
      <td>Type of subject token. For Token Vault, set to refresh token: <code>urn:ietf:params:oauth:token-type:refresh\_token</code></td>
    </tr>

    <tr>
      <td><code>subject\_token</code></td>
      <td>The Auth0 refresh token that the Auth0 Authorization Server validates to identify the user.</td>
    </tr>

    <tr>
      <td><code>requested\_token\_type</code></td>
      <td>The requested token type. For Token Vault, set to the external provider's access token or <code>[http://auth0.com/oauth/token-type/federated-connection-access-token](http://auth0.com/oauth/token-type/federated-connection-access-token)</code></td>
    </tr>

    <tr>
      <td><code>connection</code></td>
      <td>The connection name, in this case, <code>google-oauth2</code>.</td>
    </tr>

    <tr>
      <td><code>login\_hint</code></td>
      <td>(Optional) Only use `login_hint` if the user has several accounts from the same connection, such as a work Google account and personal Google account. When you pass in a value for the `login_hint` during the token exchange, you are explicitly identifying which of the user's multiple linked accounts the request is for.</td>
    </tr>
  </tbody>
</table>

## Step 3: Auth0 Authorization Server validates refresh token

The Auth0 Authorization Server validates and loads the user profile associated with the Auth0 refresh token:

1. Auth0 checks if the user profile’s `connected_accounts` array contains a user account with the connection name passed in the authorization request.
2. If the authorization request contains `login_hint`, Auth0 looks for an identity matching both the connection name and the `login_hint`.
3. If Auth0 can’t find the user, it returns a `401` status code with an error message.

Once the Auth0 Authorization Server validates the user, it locates the Google access token within the Token Vault. If it is still valid, Auth0 returns the Google access token with its scopes and expiry time:

```json lines theme={null}
{
  "access_token": "<YOUR_GOOGLE_ACCESS_TOKEN>",
  "scope": "https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.addons.execute https://www.googleapis.com/auth/calendar.events https://www.googleapis.com/auth/calendar.events.readonly https://www.googleapis.com/auth/calendar.settings.readonly https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile openid",
  "expires_in": 1377,
  "issued_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token",
  "token_type": "Bearer"
}
```

If the Google access token has expired, Auth0 uses the Google refresh token stored in the Token Vault to get a new Google access token with the same scopes.

Using the Google access token, the application calls the Google Calendar API on the user’s behalf.

## External provider refresh token expiration policy

Auth0 deletes an external provider's refresh tokens when they expire based on the expiration date set by the external provider. Tokens are also removed if they haven't been used in a token exchange for over one year.


# Cross App Access (XAA)
Source: https://auth0.com/docs/secure/call-apis-on-users-behalf/xaa

Learn how to leverage Cross App Access (XAA) to call APIs on the user's behalf.

<Warning>
  Cross App Access (XAA) is currently in Beta. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal). To learn more about Auth0's product release cycle, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To participate in this program, contact [Auth0 Support](https://support.auth0.com/) or your Technical Account Manager.
</Warning>

<Callout icon="file-lines">
  This guide assumes you use Okta as your enterprise identity provider (IdP) and have administrative access to an Okta tenant you can use for testing. If you don’t have one, read [Create and configure your Okta tenant](/docs/secure/call-apis-on-users-behalf/xaa/set-up-xaa-test-environment#create-and-configure-your-okta-tenant).
</Callout>

Connecting third-party apps and AI agents in an enterprise creates two key problems: poor IT visibility into data sharing and repetitive consent flows for users.

Cross App Access (XAA) addresses these challenges by allowing IT admins to centrally define access controls for how SaaS applications, like AI agents, connect on a user's behalf. Admins manage these connections in a central dashboard, like the Okta Admin Console, which eliminates disruptive OAuth consent prompts for end-users. The result is improved organizational security, governance, and user experience.

XAA implements the [Identity Assertion Authorization Grant](https://datatracker.ietf.org/doc/draft-ietf-oauth-identity-assertion-authz-grant/), an in-progress OAuth extension that allows an AI agent or application (Requesting App) to obtain a secure token through the enterprise IdP. This token enables the Requesting App to call the APIs of another application (Resource App) on the end-user’s behalf. To learn more, read [How it works](#how-it-works).

## Key benefits

XAA delivers key benefits for every role in your enterprise ecosystem:

* For Enterprise IT administrators: Centralized control, visibility, and policy enforcement over application access to enterprise and user data.
* For SaaS providers and developers: Standardized and secure integration for enterprise AI to foster ecosystem growth.
* For end-users: Streamlined and frictionless connections between applications, eliminating complex OAuth consent flows.

## Use cases

Common use cases for XAA include:

* Connect AI agents to enterprise applications: An employee uses an AI agent to read from their calendar app and post an update about their availability in the enterprise messaging app. Instead of requiring the employee to go through redirection flows and consent prompts, the AI agent uses XAA to obtain an access token from the enterprise IdP to securely call the APIs of both the calendar and messaging app, if approved by the enterprise access policy.
* Connect SaaS applications: In our previous example, the enterprise calendar and messaging app both support XAA. Employees can seamlessly connect the messaging app to access the calendar app’s API without user redirection or consent while following enterprise access policies.

## How it works

The XAA flow involves the following actors:

* Requesting App: The application or AI agent that needs to access a resource.
* Resource App: The application that owns the protected resource and exposes it via an API
* Enterprise IdP: The IdP, such as Okta, that authenticates employees.

After the end-user authenticates with the enterprise IdP, the Requesting App contacts the enterprise IdP to request access to the Resource App on the user's behalf. After applying its access policy to check if this cross-app connection is permitted, the enterprise IdP generates an assertion called an ID-JAG, which the Requesting App then presents to the Resource App to get an access token for API consumption. 

In the following diagram, Acme is the enterprise customer whose employees authenticate with their enterprise IdP, such as Okta, to access the Requesting App (Agent0) and the Resource App (Todo0):

<Frame>
  <img alt="" />
</Frame>

* The Resource App (Todo0) Authorization Server is federated with the enterprise IdP through OIDC so that it can generate access tokens for end-users authenticated by that IdP.
* The Requesting App (Agent0) is registered with the Resource App Authorization Server as an OAuth 2.0 client with a valid client\_id and credentials to request access tokens from the Resource App Authorization Server.
* The Acme IT admin has defined XAA access controls between Agent0 and Todo0.

## End-to-end XAA flow

With our Acme example in mind, the end-to-end XAA flow has the following steps:

1. The Acme employee logs into the Requesting App (Agent0) using SSO with the enterprise IdP. The Requesting App obtains an ID token to verify the Acme employee’s identity.
2. The Requesting App makes a token exchange request to the IdP to exchange the ID token for a cross-domain Identity Assertion JWT Authorization Grant, also known as ID-JAG. The IdP validates the request and checks the XAA policy defined by the Acme IT Admin.
3. If the XAA policy allows for it, the IdP returns the ID-JAG to the Requesting App.
4. The Requesting App makes a token request using the ID-JAG to the Resource App (Todo0) Authorization Server.
5. The Resource App Authorization Server validates the ID-JAG using the public key it also uses for its OpenID Connect flow with the IdP. If valid, the authorization server returns an access token.
6. The Requesting App makes a request with the access token to the Resource App’s API.

Leveraging the XAA flow, Acme’s IT admin policies govern access from Agent0 to Todo0, requiring no end-user redirection or interaction.

## Beta limitations

XAA Beta has the following limitations:

* The Requesting App must be a confidential client and a first-party app in your Auth0 tenant. Public clients, such as SPAs and Native Apps, are not supported.
* Delegated administration is not supported. The enterprise customer cannot directly configure SSO connections on your Auth0 tenant. [Self-Service SSO](/docs/authenticate/enterprise-connections/self-service-SSO) support is planned for a later release.
* There can only be one XAA-enabled connection per upstream IdP issuer. The same Okta tenant can’t be used for more than one XAA-enabled enterprise connection.
* Organization support is limited:
  * A connection has a 1:1 assignment with an Organization. Multiple Organizations cannot map to the same connection for XAA access.
  * When the Requesting App is configured to require the use of Organizations, users must already be members of the target organization.
* If the `resource` parameter is not specified in the ID-JAG request, the target API is determined by the `tenant.default_audience`.
* No dynamic user creation: The user must have previously logged into your Resource App using the configured Okta connection. Otherwise, the request to exchange the ID-JAG assertion for an access token will fail with a `User not found error`.

## Rate limits

In XAA Beta, ID-JAG exchanges on the `/token` endpoint of your Auth0 tenant will be rate-limited to 5 RPS.


# Manage Cross App Access (XAA) in Okta
Source: https://auth0.com/docs/secure/call-apis-on-users-behalf/xaa/manage-xaa-in-okta

Learn how to manage XAA flows in the Okta Admin Console.

<Warning>
  Cross App Access (XAA) is currently in Beta. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal). To learn more about Auth0's product release cycle, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To participate in this program, contact [Auth0 Support](https://support.auth0.com/) or your Technical Account Manager.
</Warning>

Once you've finished setting up your end-to-end test environment, you can manage how valid XAA applications can connect to each other in the Okta Admin Console.

<Frame>
  <img alt="" />
</Frame>

In the Okta Admin Console:

1. Navigate to **Applications > Applications** and select your Resource App (e.g. Todo0).
2. Under the **Manage Connections** tab, add:
   * Requesting Apps: applications that can connect to your SaaS application
   * Resource Apps: applications your SaaS application can connect to

For the end-to-end test environment, add Agent0, or the application you want to use for testing, as an authorized Requesting App.


# Set up Test Environment for Cross App Access (XAA)
Source: https://auth0.com/docs/secure/call-apis-on-users-behalf/xaa/set-up-xaa-test-environment

Learn how to set up the end-to-end test environment for the Resource App.

<Warning>
  Cross App Access (XAA) is currently in Beta. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal). To learn more about Auth0's product release cycle, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To participate in this program, contact [Auth0 Support](https://support.auth0.com/) or your Technical Account Manager.
</Warning>

This section explains how to set up the end-to-end test environment for the Resource App. By configuring your Auth0 tenant as the Resource App Authorization Server, your SaaS application can start accepting incoming ID-JAG requests without requiring any code changes. This enables your SaaS API to generate access tokens in response to these requests, allowing AI agents and other applications to seamlessly consume your API.

<Callout icon="file-lines">
  This guide assumes you use Okta as your enterprise identity provider (IdP) and have administrative access to an Okta tenant you can use for testing. If you don’t have one, read [Create and configure your Okta tenant](#create-and-configure-your-okta-tenant).
</Callout>

To set up your end-to-end test environment for the Resource App:

* Configure and register your Resource App: This includes configuring your Auth0 tenant and registering your SaaS application as a Resource App with Okta. To learn more, read [Resource App setup](#resource-app-setup).
* Configure the Requesting App to test the end-to-end: This includes registering a test Requesting App in your Auth0 tenant and updating Okta to link it with your Resource App. To learn more, read [Requesting App setup](#requesting-app-setup).
* Configure how your Auth0 tenant federates with your customer’s enterprise IdP: In our test environment, the enterprise IdP will be your Okta test tenant, representing one of your enterprise customers. To learn more, read [Federate with the enterprise IdP and Organization configuration](#federate-with-the-enterprise-idp-and-organization-configuration).
* Manage Cross App Access in Okta: Configure agent-to-app and app-to-app connections in the Okta Admin Console. To learn more, read [Manage Cross App Access in Okta](/docs/secure/call-apis-on-users-behalf/xaa/manage-xaa-in-okta).

The following image maps the responsibilities of the different personas in a production-ready XAA flow:

<Frame>
  <img alt="" />
</Frame>

## Create and configure your Okta tenant

To set up your end-to-end test environment for the Resource App, you need to create and configure your Okta tenant for Cross App Access.

* On the [Okta Developer website](https://developer.okta.com/signup/), sign up for an Okta Integrator Free Plan. Once you sign up, you should be redirected to your new Okta tenant.
* In the Okta Admin Console, navigate to **Settings > Features**. Under Early access features, enable **Cross App Access**.

<Frame>
  <img alt="" />
</Frame>

## Resource App setup

To set up your Resource App, you need to:

* [Create the API in Auth0](#create-the-api-in-auth0)
* [Create the Resource App in Auth0](#create-the-resource-app-in-auth0)
* [Register the Resource App in Okta](#register-the-resource-app-in-okta)

### Create the API in Auth0

<Callout icon="file-lines">
  If you have already created a custom API in your Auth0 tenant, you can skip this section.
</Callout>

In the Auth0 Dashboard, [register a custom API](/docs/get-started/auth0-overview/set-up-apis) representing your SaaS API in your Auth0 tenant.

<Frame>
  <img alt="" />
</Frame>

After you’ve created the API, you can optionally set its audience as the **Default Audience** for your Auth0 tenant under [Tenant Settings](/docs/get-started/tenant-settings).

You can also use [API Access Policies for Applications](/docs/get-started/apis/api-access-policies-for-applications) to granularly control which applications are granted access to your API for which scopes.

### Create the Resource App in Auth0

<Callout icon="file-lines">
  If your Auth0 tenant already has one or several applications ready to log into your SaaS application, you can skip this section.
</Callout>

In the Auth0 Dashboard, [create an application](/docs/get-started/auth0-overview/create-applications), such as a regular web app, SPA, or native app, that serves as the primary interface for end-users to access your SaaS application functionality.

### Register the Resource App in Okta

You must register your SaaS application in the Okta Integration Network (OIN) for it to be considered a valid Resource App.

To register your SaaS application as a Resource App in Okta, you have two options:

* For a quick test setup, we recommend using the Todo0 application that is already registered in the OIN. In the Okta Admin Console, go to **Applications > Applications > Browse App Catalog** and search for `Todo0`. Select it and add the integration.

<Frame>
  <img alt="" />
</Frame>

* You can also request the registration of a new application in the OIN from your Okta tenant. To learn more, read the [Submission process for SSO and SCIM integrations](https://developer.okta.com/docs/guides/submit-app-overview/#submission-process-for-sso-and-scim-integrations). To accelerate the registration process, contact your Auth0 or Okta representative.

<Callout icon="file-lines">
  In a production environment, your enterprise customers will install your SaaS application from the OIN catalog during their IdP setup.
</Callout>

Additionally, you must provide Okta with the issuer URL of your Auth0 tenant, which is associated with your Resource App. Requesting Apps use the issuer URL to request connecting to your Resource App. To learn more, read [Test the end-to-end XAA flow](/docs/secure/call-apis-on-users-behalf/xaa/test-xaa-flow).

## Requesting App setup

<Callout icon="file-lines">
  In a production environment, you configure each Requesting App once to enable its connection with your Resource App.
</Callout>

To set up your Requesting App, you need to:

* [Create the Requesting App in Auth0](#create-the-requesting-app-in-auth0)
* [Register the Requesting App in Okta](#register-the-requesting-app-in-okta)

### Create the Requesting App in Auth0

To test the end-to-end environment, create and register an application that behaves as the Requesting App. The application should be a confidential client that can store client secrets, such as a web application.

To [create an application](/docs/get-started/auth0-overview/create-applications) representing the Requesting App in your Auth0 tenant:

* Navigate to **Applications > Applications** and select **Create Application**.
* Enter a name and select **Regular Web Application**.

<Frame>
  <img alt="" />
</Frame>

* Once you’ve created the application, scroll to **Settings** and enable the **Cross App Access** toggle.

<Frame>
  <img alt="" />
</Frame>

Once you’ve created and configured your application, you must provide Okta with the application’s `client_id` and the issuer URL of your Auth0 tenant. This enables the connection between the Requesting App, identified by the `client_id`, and the Resource App, identified by the issuer URL. To learn more, read [Test the end-to-end XAA flow](/docs/secure/call-apis-on-users-behalf/xaa/test-xaa-flow).

### Register the Requesting App in Okta

<Callout icon="file-lines">
  In a production environment, the Requesting App developer registers the Requesting App in the Okta Integration Network (OIN). Enterprise customers will install the Requesting App from the OIN catalog during their IdP setup.
</Callout>

You must register the application in the Okta Integration Network (OIN) for it to be considered a valid XAA Requesting App when using Okta as the enterprise IdP.

To register the Requesting App in Okta, you have two options:

* For a quick test setup, we recommend using the Agent0 application that is already registered in the OIN. In the Okta Admin Console, go to **Applications > Applications > Browse App Catalog** and search for `Agent0`. Select it and add the integration.

<Frame>
  <img alt="" />
</Frame>

* You can also request the registration of a new application in the OIN. To learn more, read the [Submission process for SSO and SCIM integrations](https://developer.okta.com/docs/guides/submit-app-overview/#submission-process-for-sso-and-scim-integrations). To accelerate the registration process, contact your Auth0 or Okta representative.

Since the Requesting App authenticates enterprise employees with Okta, you need to configure the application’s [sign-on policy](https://help.okta.com/en-us/content/topics/security/policies/policies-home.htm) in Okta.

1. Go to **Applications > Applications** and select the application (e.g. Agent0).
2. Under **Sign On**, select **Edit** and add the Requesting App’s callback URL in the **Redirect URI** field. Adjust the Redirect URI’s value depending on the testing application you want to use. To learn more, read [Test the end-to-end XAA flow](/docs/secure/call-apis-on-users-behalf/xaa/test-xaa-flow).
3. Select **Save**.

<Frame>
  <img alt="" />
</Frame>

Finally, allow your test user to log into the Requesting App in Okta.

In the Okta Admin Console:

1. Navigate to **Applications** and select the application (e.g. Agent0).
2. Select **Assign > Assign to People** and select your test user.
3. Select **Save**.

## Federate with the enterprise IdP and Organization configuration

<Callout icon="file-lines">
  In a production environment, you configure each of your enterprise customers once to federate it with your Auth0 tenant. Auth0 will add support for [Self-Service SSO](/docs/authenticate/enterprise-connections/self-service-SSO) in later versions, enabling you to delegate XAA configuration to your enterprise customers as part of SSO setup.
</Callout>

You must federate your Auth0 tenant, acting as the authorization server for your Resource App, with your enterprise customer's Okta tenant. This federation establishes cryptographic trust, allowing your application to validate and accept signed assertions (ID-JAGs) issued by the customer's IdP.

To test the end-to-end XAA flow for multiple enterprise customers connected to your Resource App, you can repeat the steps in this section for multiple Okta Workforce Enterprise connections in your Auth0 tenant. Each connection maps to a different Okta test tenant, where each tenant represents a different enterprise customer.

### Configure an Okta Workforce Enterprise connection

Use your Resource App’s `client_id` and `client_secret` to [create an Okta Workforce Enterprise connection](/docs/authenticate/identity-providers/enterprise-identity-providers/okta) in your Auth0 tenant.

When creating the Okta Workforce Enterprise connection, activate the **Cross App Access - Resource Application** role. This enables your Resource App to accept ID-JAGs issued by the enterprise IdP associated with that connection, in this case, your Okta tenant.

<Frame>
  <img alt="" />
</Frame>

After creating the Okta Workforce Enterprise connection, copy the callback URL provided by Auth0 in the connection's settings. You need the callback URL to configure the sign-on policies of the Resource App in your Okta tenant.

In the Okta Admin Console:

1. Navigate to **Applications > Applications** and select the application (e.g. Todo0).
2. Under **Sign On** settings, select **Edit** and add the callback URL in the **Redirect URI** field.
3. Select **Save**.

<Frame>
  <img alt="" />
</Frame>

To test the Okta Workforce Enterprise connection, create a test user and give it permission to log into the Requesting App.

In the Okta Admin Console:

* Navigate to **Applications** and select the application (e.g. Agent0).
* Select **Assign > Assign to People** and select your test user.
* Select **Save**.

In the Auth0 Dashboard:

* Navigate to **Authentication > Enterprise > Okta Workforce**:
  * Enter the Okta Workforce Enterprise connection you created and select the **Applications** tab. Then, enable the Requesting App you created for the connection.
  * Go back to the list of Okta Workforce connections. Select the three dots on the right for your connection and select **Try**. You will be redirected to authenticate in your Okta tenant to complete the login with your test user.

<Frame>
  <img alt="" />
</Frame>

### Configure an Organization

Optionally, if you want an enterprise customer to use Organizations, [create an Organization](/docs/manage-users/organizations/configure-organizations/create-organizations) and [enable the Okta Workforce Enterprise connection](/docs/manage-users/organizations/configure-organizations/enable-connections) for that Organization. This automatically associates access tokens generated using XAA, in the scope of this connection, to the corresponding `org_id` if the target user is a member of the Organization.

<Frame>
  <img alt="" />
</Frame>

You can also configure the Requesting App’s [Organization behavior](/docs/manage-users/organizations/configure-organizations/define-organization-behavior) to set whether it is required or allowed to use Organizations. We recommend that you start testing with **Both**, which allows users to log in as an Organization member or sign up with a personal account.

<Frame>
  <img alt="" />
</Frame>


# Test Cross App Access (XAA) Flow
Source: https://auth0.com/docs/secure/call-apis-on-users-behalf/xaa/test-xaa-flow

Learn how to test the end-to-end XAA flow.

<Warning>
  Cross App Access (XAA) is currently in Beta. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal). To learn more about Auth0's product release cycle, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To participate in this program, contact [Auth0 Support](https://support.auth0.com/) or your Technical Account Manager.
</Warning>

To test the end-to-end XAA flow, you need to verify that your Auth0 tenant can accept the JWT-Bearer requests sent by the Requesting App. Auth0 handles that for you out of the box.

Before you can test the end-to-end XAA flow, make sure you:

* Update the **Redirect URI** field to the callback URL of your testing application that acts as your Requesting App in your Okta tenant, as explained in [Register the Requesting App in Okta](/docs/secure/call-apis-on-users-behalf/xaa/set-up-xaa-test-environment#register-the-requesting-app-in-okta).
* Provide your Okta representative with the following information:
  * The issuer URL of your Auth0 tenant. Your Resource App is associated with the issuer URL in the Okta Integration Network (OIN), enabling Requesting Apps to refer to it when requesting ID-JAGs.
  * The Auth0 `client_id` that maps to each Requesting App in the OIN.

To get the issuer URL and the client ID within your Auth0 tenant, navigate to **Applications**, select your application, and select **Settings**:

| **Field**   | **Instructions**                                                             | **Example**                                                                                                      |
| ----------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Issuer URL  | Copy your Auth0 domain, prefix it with `https://`, and add a trailing slash. | `https://tenant.region.auth0.com/` or if your customers are using a custom domain, `https://custom-domain.com/`. |
| `client_id` | Copy the application's client ID.                                            | `ovBLQycaVq6I0Xyuhq84pwDVyJeXWLyx`                                                                               |

### Exchange the ID token for an ID-JAG

First, you need to log in to your Requesting App with your Okta test tenant. When you successfully log in and grant consent, Okta redirects the browser back to your Requesting App with an authorization code. Your Requesting App then securely exchanges the authorization code for an Okta access token and ID token.

To exchange the Okta ID token for an ID-JAG, the Requesting App makes a [token exchange request](https://www.ietf.org/archive/id/draft-parecki-oauth-identity-assertion-authz-grant-05.html#name-token-exchange) to the `/token` endpoint of your Okta test tenant with the following parameters:

```
POST /oauth2/v1/token HTTP/1.1
Host: {{YOUR_TENANT}}.okta.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&requested_token_type=urn:ietf:params:oauth:token-type:id-jag
&audience={{YOUR_AUTH0_TENANT_ISSUER_URL}}
&resource={{YOUR_AUTH0_TENANT_API_AUDIENCE}}
&subject_token={{OKTA_ID_TOKEN}}
&subject_token_type=urn:ietf:params:oauth:token-type:id_token
&client_id={{REQUESTING_APP_CLIENT_ID_IN_OKTA}}
&client_secret={{REQUESTING_APP_CLIENT_SECRET_IN_OKTA}}
```

| **Parameter**          | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `grant_type`           | The grant type. Set to the token exchange grant type: `urn:ietf:params:oauth:grant-type:token-exchange`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `requested_token_type` | The type of token the client wants to receive back from the authorization server. Set to the Identity Assertion Authorization Grant, or ID-JAG: `urn:ietf:params:oauth:token-type:id-jag`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `audience`             | The intended recipient of the final token. Set to your Auth0 tenant issuer URL, or your Resource App whose authorization server is located at that specific URL.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `resource`             | Optional. The Resource App's API that the client wants to access. When the authorization server issues the final access token, it includes this resource in the token's `aud` claim, which the Resource App's API will use for validation. If you don’t specify a `resource` parameter, the default audience you set for your tenant is used in the next request to get an access token. If you specify a `resource` that does not match a valid API audience in your Auth0 tenant, the token exchange request does not fail and you still receive an ID-JAG in return. However, the subsequent request to get an access token with the ID-JAG will be rejected by your Auth0 tenant. |
| `subject_token`        | The token the client is exchanging. For XAA, the subject token is the “proof” or “assertion” of the user’s identity. Set to the Okta ID token that the IdP will use to verify the user’s identity.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `subject_token_type`   | The type of token provided in the `subject_token` parameter. For XAA, it specifies that an ID token is being presented to the authorization server.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `client_id`            | The client ID of the Requesting App within the enterprise IdP that is making the token exchange request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `client_secret`        | The client secret that that Requesting App uses to authenticate itself with the enterprise IdP.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

XAA Beta does not support passing scopes to Okta’s `/token` endpoint. You can set the scopes in the next request to Auth0’s /token endpoint once the Requesting App receives the ID-JAG.

In a production environment, the Requesting App makes the token exchange request to the `/token` endpoint of your customer’s Okta tenant.

### Send ID-JAG to Auth0's /token endpoint

Once the Requesting App gets an ID-JAG, it sends an [access token request](https://www.ietf.org/archive/id/draft-parecki-oauth-identity-assertion-authz-grant-05.html#name-access-token-request) to the `/token` endpoint of your Auth0 tenant:

```
POST https://{{YOUR_AUTH0_TENANT_DOMAIN}}/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&client_id={{REQUESTING_APP_CLIENT_ID_IN_AUTH0}}
&client_secret={{REQUESTING_APP_CLIENT_SECRET_IN_AUTH0}}
&scope=scope1%20scope2%20
&assertion={{ID_JAG}}
```

| **Parameter**   | **Description**                                                                                                              |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `grant_type`    | The grant type. It tells the Authorization Server to expect a JSON Web Token (JWT) as the primary credential in the request. |
| `client_id`     | The client ID of the Requesting App within the Resource App Authorization Server making the API call.                        |
| `client_secret` | The client secret of the Requesting App within the Resource App Authorization Server making the API call.                    |
| `scope`         | The set of permissions the Requesting App is requesting for the access token.                                                |
| `assertion`     | The ID-JAG or JSON Web Token (JWT) that acts as the bearer of the identity assertion.                                        |

After the Auth0 Authorization Server validates the ID-JAG to verify the user’s identity, it issues an access token to consume the target API audience of your Auth0 tenant. The access token also includes the scopes you requested that are allowed by RBAC and other policies set in your Auth0 tenant.

The Auth0 Authorization Server does not issue refresh tokens in response to ID-JAG token exchanges. As a result, the Requesting App needs to get a new ID-JAG from the enterprise IdP, and undergo the applicable access controls, to get a new access token via XAA.


# Auth0 Data Privacy and Compliance
Source: https://auth0.com/docs/secure/data-privacy-and-compliance



Auth0 maintains and meets the requirements for multiple compliance frameworks and certifications. To download or request Auth0 compliance documentation, [visit the Support Center](https://support.auth0.com/center/s/compliance). Auth0 will document additional compliance frameworks and certifications on this page when available.

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/secure/data-privacy-and-compliance/gdpr">General Data Protection Regulation Compliance</a></td>
      <td>What the General Data Protection Regulation (GDPR) is and Auth0's compliance with its requirements.</td>
    </tr>

    <tr>
      <td><a href="/docs/secure/data-privacy-and-compliance/data-processing">Data Processing</a></td>
      <td>What data Auth0 stores and how it's used.</td>
    </tr>
  </tbody>
</table>

## Compliance & Certifications

### FAPI

Auth0 supports technical requirements for [FAPI](https://openid.net/wg/fapi/), a set of advanced security profiles specified by the <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Foundation. FAPI introduces stricter security standards for industries and scenarios that require more security on top of normal <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> and OpenID Connect (OIDC) implementations.

Auth0 is a certified FAPI OpenID Provider for the following two profiles:

* FAPI 1 Advanced OP with mTLS, PAR
* FAPI 1 Advanced OP with Private Key <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip>, PAR

For more information, see [FAPI OpenID Providers (OP) & Profiles](https://openid.net/certification/#FAPI-OP-P).

To understand how we incorporated FAPI capabilities into Auth0, see [Highly Regulated Identity](/docs/secure/highly-regulated-identity).

### GDPR

Auth0 is GDPR ready. Auth0 provides information to its customers to help them understand how features and functionality of the Auth0 platform may affect their GDPR compliance obligations.

### HIPAA and HITECH

Auth0 is considered as a **Business Associate** as defined by the US HIPAA and HITECH legislation. For Auth0 customers who qualify as a **Covered Entity** under US HIPAA legislation and related legislation and regulations and who provide ePHI (electronic Protected Health Information) to Auth0 as part of the Auth0 user profile, Auth0 may qualify as a business associate. Auth0 can provide its **Business Associate Agreement** to you upon request. To learn more about HIPAA, read [Health Information Privacy on hhs.gov](https://www.hhs.gov/hipaa/index.html). To learn more about HITECH, read [HITECH Act Enforcement Final Rules on hhs.gov](https://www.hhs.gov/hipaa/for-professionals/special-topics/HITECH-act-enforcement-interim-final-rule/index.html). HIPAA compliance is not available on Azure deployments.

### CSA STAR

Auth0 is CSA STAR certified. You can review the CSA Consensus Assessments Initiative Questionnaire (CAIQ) and can view our CAIQ and STAR Certificates in the [CSA STAR Registry](https://cloudsecurityalliance.org/star/registry/auth0/).

### ISO 27001/27017/27018

Auth0 undergoes an ISO 27001/27017/27018 audit by an independent auditor annually. To request access to our ISO 27001/27017/27018 certificate, log in to [Auth0 Support Center](http://support.auth0.com) and select the **Compliance** option. We can also share our Statement of Applicability (SOA) upon request with a non-disclosure agreement (NDA) signed by a corporate officer authorized to represent the company. To request the SOA, please contact your assigned Technical Account Manager or Account Executive.

### PCI DSS

Auth0 offers PCI compliant environment deployment models. Our Attestation of Compliance (AOC) and/or Self Assessment Questionnaire (SAQ-D) is available upon request. For a copy of these documents, log in to [Auth0 Support Center](http://support.auth0.com) and select the **Compliance** option.

### Payment Services Directive 2 (PSD2)

We provide the capabilities for customers to build an end-to-end user journey that includes Strong Customer Authentication(SCA) and Dynamic Linking, which dynamically shows transaction details for explicit end-user approval. For more information, read [Highly Regulated Identity](/docs/secure/highly-regulated-identity).

### SOC2

Auth0 undergoes a SOC 2 Type 2 audit by an independent auditor annually. The audit covers all 5 Trust Services Criteria (Security, Availability, Processing Integrity, Confidentiality and Privacy). For a copy of the SOC 2 report, log in to [Auth0 Support Center](http://support.auth0.com) and select the **Compliance** option.

## Specifications

For information on compliance with technical specifications for authentication, please see our [Protocols](/docs/authenticate/protocols) documentation.

## Learn more

* [Auth0 General Data Protection Regulation Compliance](/docs/secure/data-privacy-and-compliance/gdpr)
* [Auth0 Data Processing](/docs/secure/data-privacy-and-compliance/data-processing)


# Auth0 Data Processing
Source: https://auth0.com/docs/secure/data-privacy-and-compliance/data-processing

Describes how Auth0 processes data in its possession.

This document discusses what data Auth0 has, as well as how it processes this data.

## Data Auth0 possesses

All of the data Auth0 has about an end user is located in the Auth0 user profile. The specific attributes contained in the user profile vary based on customer implementation and are based on a number of factors, such as connection type, user consent during the authentication flow, and whether you've augmented the user profiles with additional information.

<Warning>
  Auth0 metadata is not a secure data store and should not be used to store sensitive information, such as high-risk secrets and Personally Identifiable Information (PII) like social security numbers or credit card numbers. Auth0 customers are strongly encouraged to evaluate the data stored in metadata and only store that which is necessary for identity and access management purposes.
</Warning>

## When data is stored

The Auth0 user profile information is stored in Auth0 when you use a database connection. If a user logs in using any other type of connection (including custom database connections), Auth0 stores information provided by the external <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> for future queries.

## How data is used

The personal data stored in Auth0 is used only for the purposes of providing its services, namely authenticating users

## How can I delete my data?

As the Data Controller, the Customer is responsible for managing and deleting data via the self-service features including:

* [Delete or Reset Tenants](/docs/troubleshoot/customer-support/manage-subscriptions/delete-or-reset-tenant) - Use this feature to delete a Tenant. When you delete a Tenant, the system permanently removes all associated Customer data.
* [Manage Users Using the Management API](/docs/manage-users/user-accounts/manage-users-using-the-management-api) - Use the API to retrieve, create, update, or delete users with the Management API.
* [Manage Users in Dashboard](/docs/manage-users/user-accounts/manage-users-using-the-dashboard) - Use the Dashboard to create, view, modify, or delete users manually.

## When is Customer data automatically deleted?

Auth0 retains Customer data as long as the Customer is considered active.

Auth0 classifies a Customer as inactive when they meet both of the following conditions:

1. The Customer uses a Free Plan (including those who opted for or downgraded to a Free Tier).

2. All associated tenants show no activity for a continuous period of 150 days.

After 150 days of inactivity, the system schedules the inactive Customer’s tenants and all associated data for permanent deletion.


# Auth0 General Data Protection Regulation Compliance
Source: https://auth0.com/docs/secure/data-privacy-and-compliance/gdpr

Describes how Auth0 complies with the EU's General Data Protection Regulation (GDPR).

On 27 April 2016, the European Parliament and the European Council adopted legislation known as General Data Protection Regulation (GDPR), which became enforceable on **25 May 2018**. This legislation replaces the European Privacy Directive 95/46/EC.

The GDPR aims to unify and strengthen the data protection rights of individuals located in the European Union (EU). It also extends the applicability of EU data protection legislation to non-EU companies that store or process personal data of individuals located in the EU and increases the fines that may be levied against companies that violate GDPR requirements.

## Definitions

Here are the definitions used for Auth0's GDPR documentation:

<table>
  <thead>
    <tr>
      <th>Term</th>
      <th>Definition</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Data Subject</td>
      <td>An individual/natural person</td>
    </tr>

    <tr>
      <td>Data Controller</td>
      <td>The entity that collects and processes personal data of data subjects (<a href="https://gdpr-info.eu/art-4-gdpr/">read GDPR for exact definition</a>)</td>
    </tr>

    <tr>
      <td>Data Processor</td>
      <td>The entity that collects and processes personal data on behalf of a data controller (<a href="https://gdpr-info.eu/art-4-gdpr/">read GDPR for exact definition</a>)</td>
    </tr>

    <tr>
      <td>Personal Data</td>
      <td>Data that can be used to identify (directly or indirectly) a subject, particularly via reference to an identifier (such as a name, identification number, location data, or online identifier), or to the physical, physiological, genetic, mental, economic, cultural, or social identity of that person</td>
    </tr>

    <tr>
      <td>Sensitive Personal Data</td>
      <td>Personal data that reveals racial or ethnic origin, political opinions, religious or philosophical beliefs, or trade-union membership; genetic data or biometric data</td>
    </tr>

    <tr>
      <td>Auth0 Sub-processors</td>
      <td>Third party systems to which Auth0 shared Personal Data (contained within Customer Data), as defined in the MSA for the provision of the Service.</td>
    </tr>
  </tbody>
</table>

## GDPR summary

### Applicability

The GDPR has a broad scope of application. It applies to a wide range of companies, including non-EU-based services/companies that process personal data of individuals located in the European Union, or to companies that monitor the behavior of individuals located in the European Union.

### Notifications and consent

Before you collect personal data from your end-users, you must have a legal basis to process personal data. For example, you can rely on consent to do so. When requesting consent, your notification must:

* Be clear and easy to understand
* State the purpose of the processing of personal data and how it will be processed

Sometimes, there are additional requirements. For example, you might also need to:

* Explicitly request consent for certain processing activities
* Have a  mechanism that makes it as easy for your end-user to revoke their consent as it is to grant consent

### Rights of individuals

Your end users, as individuals, have the right to:

* Access the personal data the company has about them
* Know how their personal data will be processed or used
* Delete their personal data or “ to be forgotten” (the individual may ask the controller of their data to erase the personal data in question, cease disseminating the data, or halt further data processing)
* Portability (the individual can ask for their personal data to be retrieved  in a standard, machine-readable format and can transmit their data to another data controller)
* Not be subject to automatic decision-making (a process typically called **profiling**)

### Privacy by design and privacy by default

**Privacy by design** means that each new implementation that uses personal data must take the protection of such personal data into consideration.

**Privacy by default** means that the strictest privacy settings automatically apply once the end-user acquires a new product or service (that is, without any manual change required on the part of the user).

### Requirements for data processors and controllers

As the data controller, you must:

* Do due diligence to ensure that your data processors provide adequate protection of provided personal data

Auth0, as the data processor, must:

* Comply with instructions provided by data controllers
* Implement adequate security

### Enforcement

* The GDPR mandates that data controllers release notifications regarding data breaches without undue delay and in any case within 72 hours of becoming aware the incident if certain conditions are met
* Fines for non-compliance are much higher
* Supervisory authorities in the European Union have greater investigative powers
* Data controllers and data processors must appoint a Data Protection Officer if they meet certain requirements under the GDPR.

## Roles and responsibilities under GDPR

Generally speaking\*\*,\*\* Auth0 (Okta) customers are **data controllers**, and Auth0 (Okta) is a **data processor**.

### Personal data handled by Auth0

Auth0 handles end-user data present in user profiles, including metadata.

### Data controller (customer) responsibilities

More specifically, the customer is responsible for:

* End-user notification and consent and withdrawal of consent (where required)
* Deciding what Personal Data they expose to Auth0
* Deciding what connections (where end-user data and passwords reside) to use
* Signing up and, if necessary, creating new users
* Ensuring their users meet the age requirements and obtaining the appropriate consent if necessary (such as parental consent for children)
* Implementing the mechanisms necessary for their end-users to retrieve, review, correct, or remove personal data
* Responding to their end-users' data subject rights requests (DSARs)
* Responding to communications from Supervisory Authorities
* Sending Data breach notifications to Supervisory Authorities and end users when certain thresholds are met (Auth0 will assist the customer and provide the necessary information if necessary)

### Data processor (Auth0) responsibilities

Auth0 is responsible for:

* Following the data controller's instructions as determined in the Subscription Agreement (SA) and Data Processing Addendum (DPA) (for enterprise customers) or Terms of Service (for self-service customers)
* Assisting the customer if it receives requests from the customer's end users exercising their GDPR rights. Notifying the customer if it receives requests from Supervisory Authorities related to the processing of Personal Data (unless prohibited by law)
* Notifying the customer if it becomes aware of a confirmed data breach that compromises Customer Data
* Notifying the customer if any of its Sub-processors notify Auth0 about a confirmed data breach that impacts Auth0’s Customer Data (unless prohibited by law)
* Providing the means to enable customers to retrieve, review, correct, or delete customer data via the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> and the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>
* Providing a mechanism for customers to display consent terms and a consent agreement checkbox on the Lock widget. Customers can also design custom signup and login forms if more elaborate consent schemes are needed

## Auth0 data processing

### Data Auth0 possesses

All of the data Auth0 has about an end-user is located in the Auth0 user profile. The specific attributes contained in the user profile vary based on customer configuration and  implementation and are based on a number of factors, such as connection type, user consent during the authentication flow, and whether you've augmented the user profiles with additional information.

### When Auth0 data is stored

The Auth0 user profile information is stored in Auth0 when you use a database connection. If a user logs in using any other type of connection (including custom database connections), Auth0 stores information provided by the external <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> for future queries.

### How Auth0 uses the data it stores

The Personal Data stored in Auth0 is used only for the purposes of providing its services, namely authenticating users.

### What happens to data when an end user's account is deleted

When an end user's account is deleted, their user profile, included metadata, is removed.

## Auth0 features aiding GDPR compliance

Here is a list of GDPR regulations and how Auth0 can help you comply with them.

### Conditions for consent

According to Article 7 of GDPR, you must:

* Ask users to consent on the processing of their personal data in a clear and easily accessible form
* Be able to show that the user has consented, and
* Provide an easy way to withdraw consent at any time

You can use Auth0 to ask your users for consent upon signup (using either Lock or a custom form) and save this information at the user profile. You can later update this information using the Management API. To learn more, read [GDPR: Conditions for Consent](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-conditions-for-consent).

### Right to access, correct, and erase data

According to Articles 15, 16, 17, and 19 of GDPR, users have the right to:

* Get a copy of their personal data you are processing
* Ask for rectifications if they are inaccurate, and
* Ask you to delete their personal data

With Auth0, you can access, edit, and delete user information, either manually or using our API. To learn more, read [GDPR: Right to Access, Correct, and Erase Data](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-right-to-access-correct-and-erase-data).

### Data minimization

According to Article 5 of GDPR:

* The personal data you collect must be limited to what is necessary for processing
* Must be kept only as long as needed, and
* Appropriate security must be ensured during data processing, including protection against unauthorized or unlawful processing and against accidental loss, destruction, or damage

There are several Auth0 features than can help you achieve these goals, like account linking, user profile encryption, and more. To learn more, read [GDPR: Data Minimization](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-data-minimization).

### Data portability

According to Article 20 of GDPR, users have the right to receive the personal data concerning them in a structured, commonly used and machine-readable format.

You can export user data, stored in the Auth0 user store, either manually or programmatically. Raw data from Auth0 can be exported in JSON format (which is machine-readable). To learn more, read [GDPR: Data Portability](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-data-portability).

### Protect and secure user data

According to Article 32 of GDPR, you must implement appropriate measures to ensure a level of security, including (but not limited to):

* data encryption
* ongoing confidentiality
* data integrity, and
* availability and resilience of processing systems and services

There are several Auth0 features than can help you meet this requirement, like user profile encryption, <Tooltip href="/docs/glossary?term=brute-force+protection">brute-force protection</Tooltip>, <Tooltip href="/docs/glossary?term=breached+password+detection">breached password detection</Tooltip>, step-up authentication, and more. To learn more, read [GDPR: Protect and Secure User Data](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-protect-and-secure-user-data).

## Security advice

Auth0 recommends the following practices to help ensure the security of your end users data and minimize the probability of a data breach:

* Protect <Tooltip href="/docs/glossary?term=client+secrets">client secrets</Tooltip> and keys
* Protect Management Dashboard credentials, and require <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> for access to the Dashboard
* Review the list of administrators for the Dashboard on a regular basis and remove outdated entries
* Review the list of connections and applications associated with your Auth0 tenants and remove outdated entries
* Ensure that Dashboard administrators use corporate credentials that can be easily revoked if necessary, not personal credentials such as a personal email account
* Remove accounts for terminated employees promptly
* Ensure that administrators use devices with mandatory screen locking
* Provide regular training to all Dashboard administrators and developers on security and privacy best practices

Make sure that you monitor any log streaming solution you use to send log data to logging tools with reporting capability.

## Learn more

* [GDPR: Conditions for Consent](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-conditions-for-consent)
* [GDPR: Right to Access, Correct, and Erase Data](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-right-to-access-correct-and-erase-data)
* [GDPR: Data Minimization](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-data-minimization)
* [GDPR: Data Portability](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-data-portability)
* [GDPR: Protect and Secure User Data](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-protect-and-secure-user-data)


# GDPR: Conditions for Consent
Source: https://auth0.com/docs/secure/data-privacy-and-compliance/gdpr/gdpr-conditions-for-consent

Describes which Auth0 features can help you comply with the Conditions for Consent GDPR requirements.

According to Article 7 of GDPR, you must ask users to consent on the processing of their personal data in a clear and easily accessible form. You must also show that the user has consented, and provide an easy way to withdraw consent at any time.

This article explains how you can use Auth0 features to implement these requirements.

<Callout icon="file-lines">
  The contents of these documents are not intended to be legal advice, nor should they be considered a substitute for legal assistance. The final responsibility for understanding and complying with GDPR resides with you, though Auth0 will assist you in meeting GDPR requirements where possible.
</Callout>

## Ask for consent

Upon signup you have to ask your users for consent. With Auth0, you can save this information with the user metadata. There are several available options depending on how you use Auth0 to authenticate your users. Before you design your solution using metadata make sure you are aware of the restrictions. Auth0 limits the total size of the `user_metadata` to **16 MB**. To learn more, read [Metadata Field Names and Data Types](/docs/manage-users/user-accounts/metadata/metadata-fields-data).

<Warning>
  Auth0 metadata is not a secure data store and should not be used to store sensitive information, such as high-risk secrets and Personally Identifiable Information (PII) like social security numbers or credit card numbers. Auth0 customers are strongly encouraged to evaluate the data stored in metadata and only store that which is necessary for identity and access management purposes.
</Warning>

### Use Lock

You can customize the Lock UI to display links to your terms and conditions and/or privacy statement pages, and a consent checkbox that the user has to check in order to sign up. This can be done with the `mustAcceptTerm`s Lock option. This property, when set to `true`, displays a checkbox alongside the terms and conditions that must be checked before signing up. The terms and conditions can be specified using the languageDictionary option. To learn more, read [Lock Configuration Options](/docs/libraries/lock/lock-configuration).

Once the user accepts and signs up, save the consent information at the `user_metadata` using a rule that will run upon first login. To learn more about rules, read [Auth0 Rules](/docs/customize/rules).

If you want to get more information from the users during signup, and you authenticate users with a database connection, you can add custom fields to the Lock UI. This can be done with the additionalSignUpFields Lock option. Any custom fields are automatically added to the `user_metadata`.

If you are using social logins, adding custom fields is not an option, but you can redirect the user to another page where you ask for consent and any additional info, and then redirect back to finish the authentication transaction. This can be done with redirect rules. To learn more, read [Redirect Users from Within Rules](/docs/customize/rules/redirect-users). Once the signup process is complete, save the consent information at the `user_metadata` by calling the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> [**Update User** endpoint](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id).

To learn how to implement any of these scenarios, read [GDPR: Track Consent with Lock](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-track-consent-with-lock).

### Use custom UI

If you use a custom signup form with a database connection, you have to add an extra field to the signup screen in order to capture the user's consent. Afterward, call the Authentication API [**Signup** endpoint](https://auth0.com/docs/api/authentication#signup) in order to create the user in Auth0. At this point, you can set the consent information as part of the `user_metadata`.

Alternatively, if you use Auth0.js from a SPA, you can [use the `signup` method](/docs/libraries/auth0js) to create the user in Auth0 and set the consent info as part of the `user_metadata`.

If you use a custom signup form with social providers, you cannot set the user's consent information upon signup but you can update it as soon as the user is created. Save the consent information at the `user_metadata` by calling the Management API [**Update User** endpoint](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id).

To learn how to implement any of these scenarios, read [GDPR: Track Consent with Custom UI](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-track-consent-with-custom-ui).

### Re-consent and user migration

If you need to ask for consent from existing users and you decide to migrate your users from an existing database to Auth0, you can [use our Automatic User Migration](/docs/manage-users/user-migration/configure-automatic-migration-from-your-database) feature. By activating this, each time a user logs in for the first time (since this was activated), they will be created in Auth0 without having to reset their password. To do this you must:

* Write up the notification users will see around how users' data is being used, how long data will be used, users' rights, etc. as well as customize the UI sign-up box.
* Determine if re-consent is required for your users, depending on your old terms and conditions and previous privacy certifications.

Note that every time your Terms and Conditions change, you **must** ask the users for consent again.

## Track consent

According to GDPR, you should be able to show that the user has consented to the processing of their personal data.

With Auth0 you can save the user's consent information as part of the `user_metadata`. You can either save only a flag, showing if the user has consented or not, or a set of consent information and preferences (including, for example, the day the user provided consent, the terms they consented to, etc). Afterward, you can access and manipulate this information using the Management API.

The Management API also offers several options when it comes to user search and endpoints to update user metadata or batch export users.

To access the Management API, you will need an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>. To learn how to get an access token for the Management API, read [Management API Access Tokens](/docs/secure/tokens/access-tokens/management-api-access-tokens).

### Search for users by email address

To search for a user using their email address, use the [**Search User by Email** endpoint](/docs/manage-users/user-search/user-search-best-practices).

Set the **fields** request parameter to `user_metadata` in order to limit the fields returned. This way, only the user\_metadata will be returned instead of the complete user profile.

Sample request:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/users-by-email?email=USER_EMAIL_ADDRESS&fields=user_metadata' \
    --header 'authorization: Bearer YOUR_MGMT_API_ACCESS_TOKEN'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users-by-email?email=USER_EMAIL_ADDRESS&fields=user_metadata");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users-by-email?email=USER_EMAIL_ADDRESS&fields=user_metadata"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.get("https://{yourDomain}/api/v2/users-by-email?email=USER_EMAIL_ADDRESS&fields=user_metadata")
    .header("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/users-by-email',
    params: {email: 'USER_EMAIL_ADDRESS', fields: 'user_metadata'},
    headers: {authorization: 'Bearer YOUR_MGMT_API_ACCESS_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer YOUR_MGMT_API_ACCESS_TOKEN" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users-by-email?email=USER_EMAIL_ADDRESS&fields=user_metadata"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users-by-email?email=USER_EMAIL_ADDRESS&fields=user_metadata",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer YOUR_MGMT_API_ACCESS_TOKEN"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer YOUR_MGMT_API_ACCESS_TOKEN" }

  conn.request("GET", "/{yourDomain}/api/v2/users-by-email?email=USER_EMAIL_ADDRESS&fields=user_metadata", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users-by-email?email=USER_EMAIL_ADDRESS&fields=user_metadata")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer YOUR_MGMT_API_ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer YOUR_MGMT_API_ACCESS_TOKEN"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users-by-email?email=USER_EMAIL_ADDRESS&fields=user_metadata")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

Sample response:

```json lines theme={null}
[
  {},
  {
    "user_metadata": {
      "consent": {
	    "given": true,
	    "date": "01/23/2018",
	    "text_details": "some-url"
	  }
    }
  }
]
```

### Search for users by ID

To search for a user using their ID, use the [**Get a User** endpoint](/docs/manage-users/user-search/user-search-best-practices).

Set the **fields** request parameter to `user_metadata` in order to limit the fields returned. This way, only the `user_metadata` will be returned instead of the complete user profile.

Sample request:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://{yourDomain}/api/v2/users/%7ByourUserID%7D?fields=user_metadata' \
    --header 'authorization: Bearer {yourMgmtApiAccessToken}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/%7ByourUserID%7D?fields=user_metadata");
  var request = new RestRequest(Method.GET);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users/%7ByourUserID%7D?fields=user_metadata"

  	req, _ := http.NewRequest("GET", url, nil)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.get("https://{yourDomain}/api/v2/users/%7ByourUserID%7D?fields=user_metadata")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'GET',
    url: 'https://{yourDomain}/api/v2/users/%7ByourUserID%7D',
    params: {fields: 'user_metadata'},
    headers: {authorization: 'Bearer {yourMgmtApiAccessToken}'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/%7ByourUserID%7D?fields=user_metadata"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"GET"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/%7ByourUserID%7D?fields=user_metadata",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer {yourMgmtApiAccessToken}" }

  conn.request("GET", "/{yourDomain}/api/v2/users/%7ByourUserID%7D?fields=user_metadata", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/%7ByourUserID%7D?fields=user_metadata")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Get.new(url)
  request["authorization"] = 'Bearer {yourMgmtApiAccessToken}'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer {yourMgmtApiAccessToken}"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/%7ByourUserID%7D?fields=user_metadata")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "GET"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

Sample response:

```json lines theme={null}
{
  "user_metadata": {
    "consent": {
	    "given": true,
	    "date": "01/23/2018",
	    "text_details": "some-url"
  	}
  }
}
```

### Update consent information

To update a user's `user_metadata`, use the [**Update a User** endpoint](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id).

How you structure your request depends on how you have structured your metadata: as root or as inner properties.

If your metadata are stored as root properties:

```json lines theme={null}
{
  "consentGiven": true,
  "consentDetails": "some-url"
}
```

If your metadata are stored as inner properties:

```json lines theme={null}
{
  "consent": {
    "given": true,
    "text_details": "some-url"
  }
}
```

#### Update root property

Updates to root-level properties are merged, so you only need to send the value for the field you want to update. For example, let's say we want to add a consent date and set it to `01/23/2018`.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/users/USER_ID' \
    --header 'authorization: Bearer YOUR_MGMT_API_ACCESS_TOKEN' \
    --header 'content-type: application/json' \
    --data '{"user_metadata":{"consentDate":"01/24/2018"}}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/USER_ID");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"user_metadata":{"consentDate":"01/24/2018"}}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users/USER_ID"

  	payload := strings.NewReader("{"user_metadata":{"consentDate":"01/24/2018"}}")

  	req, _ := http.NewRequest("PATCH", url, payload)

  	req.Header.Add("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN")
  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.patch("https://{yourDomain}/api/v2/users/USER_ID")
    .header("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN")
    .header("content-type", "application/json")
    .body("{"user_metadata":{"consentDate":"01/24/2018"}}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/users/USER_ID',
    headers: {
      authorization: 'Bearer YOUR_MGMT_API_ACCESS_TOKEN',
      'content-type': 'application/json'
    },
    data: {user_metadata: {consentDate: '01/24/2018'}}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer YOUR_MGMT_API_ACCESS_TOKEN",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"user_metadata": @{ @"consentDate": @"01/24/2018" } };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/USER_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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/USER_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 => "{"user_metadata":{"consentDate":"01/24/2018"}}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer YOUR_MGMT_API_ACCESS_TOKEN",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"user_metadata":{"consentDate":"01/24/2018"}}"

  headers = {
      'authorization': "Bearer YOUR_MGMT_API_ACCESS_TOKEN",
      'content-type': "application/json"
      }

  conn.request("PATCH", "/{yourDomain}/api/v2/users/USER_ID", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/USER_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["authorization"] = 'Bearer YOUR_MGMT_API_ACCESS_TOKEN'
  request["content-type"] = 'application/json'
  request.body = "{"user_metadata":{"consentDate":"01/24/2018"}}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer YOUR_MGMT_API_ACCESS_TOKEN",
    "content-type": "application/json"
  ]
  let parameters = ["user_metadata": ["consentDate": "01/24/2018"]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/USER_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()
  ```
</AuthCodeGroup>

This will add a new property to the user profile, the **user\_metadata.consentDate**, which will hold the date the customer consented. The response will be the full user profile. The updated metadata will look like this:

```json lines theme={null}
{
  "consentGiven": true,
  "consentDate": "01/23/2018",
  "consentDetails": "some-url"
}
```

#### Update inner property

To update an inner property, you must send the whole metadata object, even if you are not updating more than one property. If you do not include the entire object, Auth0 will remove your existing properties.

Let's add an inner property for the consent date and set it to `01/23/2018`.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/users/USER_ID' \
    --header 'authorization: Bearer YOUR_MGMT_API_ACCESS_TOKEN' \
    --header 'content-type: application/json' \
    --data '{"user_metadata":{"consent": {"given":true, "date":"01/23/2018", "text_details":"some-url"}}}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/USER_ID");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"user_metadata":{"consent": {"given":true, "date":"01/23/2018", "text_details":"some-url"}}}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users/USER_ID"

  	payload := strings.NewReader("{"user_metadata":{"consent": {"given":true, "date":"01/23/2018", "text_details":"some-url"}}}")

  	req, _ := http.NewRequest("PATCH", url, payload)

  	req.Header.Add("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN")
  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.patch("https://{yourDomain}/api/v2/users/USER_ID")
    .header("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN")
    .header("content-type", "application/json")
    .body("{"user_metadata":{"consent": {"given":true, "date":"01/23/2018", "text_details":"some-url"}}}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/users/USER_ID',
    headers: {
      authorization: 'Bearer YOUR_MGMT_API_ACCESS_TOKEN',
      'content-type': 'application/json'
    },
    data: {
      user_metadata: {consent: {given: true, date: '01/23/2018', text_details: 'some-url'}}
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer YOUR_MGMT_API_ACCESS_TOKEN",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"user_metadata": @{ @"consent": @{ @"given": @YES, @"date": @"01/23/2018", @"text_details": @"some-url" } } };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/USER_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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/USER_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 => "{"user_metadata":{"consent": {"given":true, "date":"01/23/2018", "text_details":"some-url"}}}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer YOUR_MGMT_API_ACCESS_TOKEN",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"user_metadata":{"consent": {"given":true, "date":"01/23/2018", "text_details":"some-url"}}}"

  headers = {
      'authorization': "Bearer YOUR_MGMT_API_ACCESS_TOKEN",
      'content-type': "application/json"
      }

  conn.request("PATCH", "/{yourDomain}/api/v2/users/USER_ID", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/USER_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["authorization"] = 'Bearer YOUR_MGMT_API_ACCESS_TOKEN'
  request["content-type"] = 'application/json'
  request.body = "{"user_metadata":{"consent": {"given":true, "date":"01/23/2018", "text_details":"some-url"}}}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer YOUR_MGMT_API_ACCESS_TOKEN",
    "content-type": "application/json"
  ]
  let parameters = ["user_metadata": ["consent": [
        "given": true,
        "date": "01/23/2018",
        "text_details": "some-url"
      ]]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/USER_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()
  ```
</AuthCodeGroup>

This will add a new property to the user profile, the **user\_metadata.consent.date,** which will hold the date the customer consented. The response will be the full user profile. The updated metadata will look like this:

```json lines theme={null}
{
  "consent": {
    "given": true,
    "date": "01/23/2018",
    "text_details": "some-url"
  }
}
```

### Export consent information

To export a list of your users using the Management API, use the [**User Export** endpoint](/docs/manage-users/user-search/user-search-best-practices).

This endpoint creates a job that exports all users associated with a connection. You will need the ID of the connection. To find this ID, use the [**Get Connections** endpoint](https://auth0.com/docs/api/management/v2#!/Connections/get_connections) (you can set the **name** parameter to the name of the connection to retrieve only this one).

Once you have the connection ID and an access token for the Management API, you are ready to start exporting users. To see a sample request and response, read [Import and Export Users](/docs/manage-users/user-migration). To learn how to get an access token for the Management API, read [Management API Access Tokens](/docs/secure/tokens/access-tokens/management-api-access-tokens).

You also must:

* Determine how you want to track consent. We recommend including information on not just the date the user consented, but the version of terms and conditions to which the user agreed. We also recommend including an array to hold information about users that withdraw their permission (remember that the user can consent and withdraw multiple times).
* Choose where you want to store consent: in Auth0's database or elsewhere.

## Withdraw consent

The user should have the option to withdraw consent using your app. This option should be easily accessible, and clearly distinguishable. Once the user decides to withdraw their consent, you should take action.

First, you have to decide how you will handle the withdrawal of consent: will you delete the users or flag them as deleted?

### Delete user

To delete a user, use the [**Delete a User** endpoint](https://auth0.com/docs/api/management/v2#!/Users/delete_users_by_id).

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url 'https://{yourDomain}/api/v2/users/USER_ID' \
    --header 'authorization: Bearer YOUR_MGMT_API_ACCESS_TOKEN'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/USER_ID");
  var request = new RestRequest(Method.DELETE);
  request.AddHeader("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN");
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users/USER_ID"

  	req, _ := http.NewRequest("DELETE", url, nil)

  	req.Header.Add("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.delete("https://{yourDomain}/api/v2/users/USER_ID")
    .header("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'DELETE',
    url: 'https://{yourDomain}/api/v2/users/USER_ID',
    headers: {authorization: 'Bearer YOUR_MGMT_API_ACCESS_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer YOUR_MGMT_API_ACCESS_TOKEN" };

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/USER_ID"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"DELETE"];
  [request setAllHTTPHeaderFields:headers];

  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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/USER_ID",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer YOUR_MGMT_API_ACCESS_TOKEN"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  headers = { 'authorization': "Bearer YOUR_MGMT_API_ACCESS_TOKEN" }

  conn.request("DELETE", "/{yourDomain}/api/v2/users/USER_ID", headers=headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/USER_ID")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Delete.new(url)
  request["authorization"] = 'Bearer YOUR_MGMT_API_ACCESS_TOKEN'

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["authorization": "Bearer YOUR_MGMT_API_ACCESS_TOKEN"]

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/USER_ID")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "DELETE"
  request.allHTTPHeaderFields = headers

  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()
  ```
</AuthCodeGroup>

The response body for this endpoint is empty, so if you want to confirm that the user was successfully deleted try to retrieve the user using their email. If the endpoint returns an error, then your call to delete the user was successful.

### Flag user as deleted

If you don't want to delete the user, flag their profile as deleted using the [**app\_metadata** endpoint](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id). Then, add some code that will make the authentication process to fail for any user with their profile flagged as such.

This allows you to keep a record of deleted users for future use.

#### Flag the profile

To flag a user as deleted, use the app\_metadata. In the following example, we will show you how to add a property called **deleted** to the **app\_metadata** field. This allows you to configure the authentication process to treat all uses with this property set to true as deleted.

To update a user's metadata, use the [**Update a User** endpoint](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id).

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/users/USER_ID' \
    --header 'authorization: Bearer YOUR_MGMT_API_ACCESS_TOKEN' \
    --header 'content-type: application/json' \
    --data '{"app_metadata":{"deleted":true}}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/USER_ID");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"app_metadata":{"deleted":true}}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users/USER_ID"

  	payload := strings.NewReader("{"app_metadata":{"deleted":true}}")

  	req, _ := http.NewRequest("PATCH", url, payload)

  	req.Header.Add("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN")
  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.patch("https://{yourDomain}/api/v2/users/USER_ID")
    .header("authorization", "Bearer YOUR_MGMT_API_ACCESS_TOKEN")
    .header("content-type", "application/json")
    .body("{"app_metadata":{"deleted":true}}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/users/USER_ID',
    headers: {
      authorization: 'Bearer YOUR_MGMT_API_ACCESS_TOKEN',
      'content-type': 'application/json'
    },
    data: {app_metadata: {deleted: true}}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer YOUR_MGMT_API_ACCESS_TOKEN",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"app_metadata": @{ @"deleted": @YES } };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/USER_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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/USER_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 => "{"app_metadata":{"deleted":true}}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer YOUR_MGMT_API_ACCESS_TOKEN",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"app_metadata":{"deleted":true}}"

  headers = {
      'authorization': "Bearer YOUR_MGMT_API_ACCESS_TOKEN",
      'content-type': "application/json"
      }

  conn.request("PATCH", "/{yourDomain}/api/v2/users/USER_ID", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/USER_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["authorization"] = 'Bearer YOUR_MGMT_API_ACCESS_TOKEN'
  request["content-type"] = 'application/json'
  request.body = "{"app_metadata":{"deleted":true}}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer YOUR_MGMT_API_ACCESS_TOKEN",
    "content-type": "application/json"
  ]
  let parameters = ["app_metadata": ["deleted": true]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/USER_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()
  ```
</AuthCodeGroup>

#### Disable login for flagged users

Next, you must disable login for users flagged as deleted. To do so, you will add a rule (a JavaScript snippet that runs as part of the authentication pipeline).

1. Go to [Auth0 Dashboard > Auth Pipeline > Rules](https://manage.auth0.com/#/rules) and create a rule.
2. Copy the script below:

   ```javascript lines theme={null}
   function (user, context, callback) {
     user.app_metadata = user.app_metadata || {};
     if (user.app_metadata.deleted){
     	return callback(new UnauthorizedError('Access denied (deleted user)'));
     }
     callback(null, user, context);
   }
   ```

   The script does the following:

   1. Checks the value of the **deleted** metadata property (`user.app_metadata.deleted`).
   2. Returns an `Access denied (deleted user)` error to your app if `user.app_metadata.deleted = true`
3. Give a name to your rule and save your changes.

You also must:

* Ensure the consent withdrawal piece is granular enough.
* Configure into the app, the area where customers will withdraw consent.

## Learn more

* [GDPR: Data Minimization](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-data-minimization)
* [GDPR: Data Portability](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-data-portability)
* [GDPR: Protect and Secure User Data](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-protect-and-secure-user-data)
* [GDPR: Right to Access, Correct, and Erase Data](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-right-to-access-correct-and-erase-data)


# GDPR: Data Minimization
Source: https://auth0.com/docs/secure/data-privacy-and-compliance/gdpr/gdpr-data-minimization

Describes how you can minimize the personal data they collect for processing and ensure their security.

According to Article 5 of GDPR, the personal data you collect must be limited to what is necessary for processing and must be kept only as long as needed. Appropriate security must be ensured during data processing, including protection against unauthorised or unlawful processing and against accidental loss, destruction, or damage.

There are several Auth0 features than can help you achieve these goals, like account linking, user profile encryption, and more.

<Callout icon="file-lines">
  The contents of these documents are not intended to be legal advice, nor should they be considered a substitute for legal assistance. The final responsibility for understanding and complying with GDPR resides with you, though Auth0 will assist you in meeting GDPR requirements where possible.
</Callout>

## Restrict user profile information

To limit the amount of personal information in the Auth0 user profile, you can:

* Minimize (or avoid) saving personal information in the metadata section of the user profile
* If you use enterprise directories, configure them to return only the minimum information needed
* If you use social providers, configure them to return only the minimum information needed
* Denylist the user attributes that you do not want to persist in the Auth0 databases

## Encrypt user profile information

You can encrypt user information before you save it in the user profile. You can use any encryption mechanism you like prior to storing data in the metadata fields. When a user sets sensitive information, call the Update a User endpoint.

## Use account linking

Every time a user uses a connection to log in to your application, a user profile is created if it doesn't already exist. Note that this is per connection.

To better understand this, consider the following scenario. Your application offers three different options for signup:

* sign up with email/password
* login with Google
* login with Facebook

If a user signs up with Google, this will create a user profile in Auth0. If the same user, upon return, does not remember what they signed up with, and chooses to login with Facebook, Auth0 will create another user profile for the user. So now you have two profiles for the same user.

You can fix this with account linking. You can link multiple accounts under a single user profile, regardless of the connection's type (for example, user/password, social, or <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip>).

There are two ways to implement this:

* **User-initiated** account linking: your app must provide the UI so an authenticated user can link their accounts manually.
* **Suggested** account linking: in this case you still configure a rule that will link accounts with the same verified email address. However, instead of completing the link automatically, your app will first prompt the user to link their identities.

## Export logs

You can export Auth0 logs and either store them yourself or automatically push them to an external log service in [Auth0 Marketplace](https://marketplace.auth0.com/features/log-streaming). This functionality can help you with data retention requirements, as well as log analysis requirements.

### Export logs with the API

You can use the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to export logs and store them yourself. There are the two available endpoints, each providing slightly different information.

#### Search all logs

The Search Log Events endpoint retrieves log entries that match the search criteria you provided. If you do not provide any search criteria, you will get a list of all available entries.

You can provide search criteria using the **q** parameter and retrieve specific fields using the **fields** parameter.

To access the API, you need a Management APIv2 token.

This sample request retrieves all logs for successful logins (the event acronym for successful login is `s`). The list of fields we will retrieve per log entry is: **date**, **description**, **client\_id**, and **log\_id**.

#### Get a single log entry

The Get a Log Event by ID endpoint retrieves the log entry associated with the provided ID.

This sample request retrieves a single log entry with the ID `90020180129170850881585554625888895190928456277777449010`.

### Export to an external service

You can install and configure one of our [log streaming solutions](https://marketplace.auth0.com/features/log-streaming) in Auth0 Marketplace to export logs automatically to another provider, like Sumo Logic or Loggly. For a list of available providers and detailed steps to configure each, see Export Auth0 logs to an external service.

## Keep sensitive information from logs

You should minimize any sensitive information contained in URLs that might be captured by Auth0 log files. For example, consider using `health-site` or similar as your domain name instead of `cancer-treatments`.

You also need to ensure that you do the following:

* Analyze what you are collecting in sign up and through social media and whether that is necessary for the purpose of your service.
* Configure enterprise <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip> to control what data is returned to Auth0.
* Specify what data you want to collect from the social provider and negotiate any particular terms around social login with the social provider around use of the data they will get around your users’ login.

## Learn more

* [GDPR: Conditions for Consent](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-conditions-for-consent)
* [GDPR: Data Portability](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-data-portability)
* [GDPR: Protect and Secure User Data](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-protect-and-secure-user-data)
* [GDPR: Right to Access, Correct, and Erase Data](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-right-to-access-correct-and-erase-data)


# GDPR: Data Portability
Source: https://auth0.com/docs/secure/data-privacy-and-compliance/gdpr/gdpr-data-portability

Describes how you can export user data in order to comply with data portability GDPR requirements.

According to Article 20 of GDPR, users have the right to receive the personal data concerning them in a structured, commonly used and machine-readable format.

You can export user data, stored in the Auth0 user store, either manually or programmatically. Raw data from Auth0 can be exported in JSON format (which is machine-readable).

<Callout icon="file-lines">
  The contents of these documents are not intended to be legal advice, nor should they be considered a substitute for legal assistance. The final responsibility for understanding and complying with GDPR resides with you, though Auth0 will assist you in meeting GDPR requirements where possible.
</Callout>

## Export data manually

1. Go to [Auth0 Dashboard > User Management > Users](https://manage.auth0.com/#/users).
2. Search for the user and drill down on their name.
3. Click the **Raw JSON** tab. Here you can see the complete user profile in JSON format.
4. Click **Copy JSON**. The profile is copied to your clipboard.
5. Paste the clipboard contents to an editor and save.

## Export data using the API

You can export a user's full profile using our <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. The response will be in JSON format. You can either search for a user using their ID, or export a list of your users.

## Learn more

* [GDPR: Conditions for Consent](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-conditions-for-consent)
* [GDPR: Data Minimization](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-data-minimization)
* [GDPR: Protect and Secure User Data](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-protect-and-secure-user-data)
* [GDPR: Right to Access, Correct, and Erase Data](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-right-to-access-correct-and-erase-data)


# GDPR: Protect and Secure User Data
Source: https://auth0.com/docs/secure/data-privacy-and-compliance/gdpr/gdpr-protect-and-secure-user-data

Describes how you can use Auth0 features to protect and secure user's personal data.

As per article 32 of GDPR, you must implement appropriate security measures in order to ensure a level of security appropriate to the risk, including (but not limited to):

* Τhe encryption of personal data
* Τhe ability to ensure the ongoing confidentiality, integrity, availability, and resilience of processing systems and services
* Τhe ability to restore the availability and access to personal data in a timely manner in the event of a physical or technical incident

There are several Auth0 features that can help you achieve that, like user profile encryption, <Tooltip href="/docs/glossary?term=brute-force+protection">brute-force protection</Tooltip>, <Tooltip href="/docs/glossary?term=breached+password+detection">breached password detection</Tooltip>, step-up authentication, and more.

<Callout icon="file-lines">
  The contents of these documents are not intended to be legal advice, nor should they be considered a substitute for legal assistance. The final responsibility for understanding and complying with GDPR resides with you, though Auth0 will assist you in meeting GDPR requirements where possible.
</Callout>

## Encrypt user profile information

You can encrypt user information before you save it in the user profile. You can use any encryption mechanism you like prior to storing data in the metadata fields. When a user sets sensitive information, call the Update a User endpoint.

## Enable brute-force protection

Auth0's brute-force protection shield is enabled by default to stop malicious attempts to access your application.

There are two types of triggers for this shield:

* 10 consecutive failed login attempts for the same user and from the same IP address
* 100 failed login attempts from the same IP address in 24 hours or 50 sign up attempts per minute from the same IP address

For example, if a user with **user\_id1** signs in from **IP1** and fails to login consecutively for 10 attempts, their log in attempt from this **IP1** will be blocked. Another user, **user\_id2**, signing in from **IP1** will not be blocked.

Every time Auth0 detects 10 failed login attempts into a single account from the same IP, we will:

* Send a notification email to the user.
* Block the suspicious IP address for that user.

Every time Auth0 detects 100 failed login attempts in 24 hours or 50 sign up attempts from the same IP address, we will:

* Notify dashboard administrator(s).
* Block suspicious addresses for 15 minutes.

You can enable brute-force protection, configure which actions you want to take, and customize the blocked account email using the Dashboard.

## Enable breached password detection

The breached password detection shield helps you identity user credentials that might have been compromised in a public data breach.

Auth0 tracks large security breaches that are happening on major third-party sites. If one of your users' credentials were included in a public security breach, you can take action and:

* Send an email to the affected user
* Send an email to dashboard owners immediately, and/or have a daily/weekly/monthly summary
* Block login attempts for suspected user accounts using that username and password combination. This block remains in place until the user changes their password

You can enable breached password detection and configure which actions you want to take using the Dashboard.

## Harden your security with multi-factor authentication

With <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA), you can add an additional layer of security to your applications. It is a method of verifying a user's identity by asking them to present more than one piece of identifying information.

We support MFA using push notifications, SMS, one-time password authentication services, and custom providers. You can enable MFA for specific users or specific actions (for example, access screens with sensitive data). You can also define the conditions that will trigger additional authentication challenges, such as changes in geographic location or logins from unrecognized devices.

## Help your users choose better passwords

You can customize the level of password complexity for new sign ups. For example, you can ask for a password that has at least 10 characters and includes at least one uppercase letter, a number, and a special character.

You can also forbid the use of previous passwords using our Password History feature and stop users from choosing common passwords using our Password Dictionary. All three features are configurable from the Dashboard.

## Step-up authentication

With step-up authentication, applications can ask users to authenticate with a stronger authentication mechanism to access sensitive resources. For example, you may have a banking application that does not require Multi-factor Authentication (MFA) to view the account's basic information, but when users try to transfer money between accounts then they must authenticate with one more factor (for example, a code sent via SMS).

You can check if a user has logged in with MFA by reviewing the contents of their <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip> or <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>. You can then configure your application to deny access to sensitive resources if the token indicates that the user did not log in with MFA.

## Availability and resilience

Auth0 is designed and built as a scalable, highly available, multi-tenant cloud service. We are highly resilient to the failure of any of our components because we implement redundant components at all levels. We also detect failures rapidly and our failover is very quick.

To learn more information on Auth0 architecture, read [Availability & Trust](https://auth0.com/availability-trust).

## Learn more

* [GDPR: Conditions for Consent](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-conditions-for-consent)
* [GDPR: Data Minimization](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-data-minimization)
* [GDPR: Data Portability](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-data-portability)
* [GDPR: Right to Access, Correct, and Erase Data](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-right-to-access-correct-and-erase-data)


# GDPR: Right to Access, Correct, and Erase Data
Source: https://auth0.com/docs/secure/data-privacy-and-compliance/gdpr/gdpr-right-to-access-correct-and-erase-data

Describes Auth0 features that help you comply with the GDPR requirements on the user's right to access, correct, and erase their personal data.

As per articles 15, 16, 17, and 19 of GDPR, users have the right to get a copy of their personal data you are processing, ask for rectifications if they are inaccurate, and ask you to delete their personal data.

With Auth0, you can access, edit, and delete user information manually, using the Dashboard, or programmatically, using the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

<Callout icon="file-lines">
  The contents of these documents are not intended to be legal advice, nor should they be considered a substitute for legal assistance. The final responsibility for understanding and complying with GDPR resides with you, though Auth0 will assist you in meeting GDPR requirements where possible.
</Callout>

## Manual process

You can view, edit, and delete user information at [Auth0 Dashboard > User Management > Users](https://manage.auth0.com/#/users). Drill down to a user to view their information. The information you can change is:

<table>
  <thead>
    <tr>
      <th><strong>Field</strong></th>
      <th><strong>How to edit</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Email</strong></td>
      <td>Click Edit. Set the new email.</td>
    </tr>

    <tr>
      <td><strong>Email verified</strong></td>
      <td>Click <strong>Edit</strong> at the <strong>Εmail</strong> field. Click the <strong>Set email as verified</strong> link.</td>
    </tr>

    <tr>
      <td><strong>Metadata</strong></td>
      <td>Both the <code>app\_metadata</code> and the <code>user\_metadata</code> objects are editable from this screen. Edit the JSON at the <strong>Metadata</strong> section and save your changes.</td>
    </tr>

    <tr>
      <td><strong>Blocked</strong></td>
      <td>Not directly editable. Click <strong>Actions > Block User</strong> at the top right of this screen. To unblock click <strong>Actions > Unblock User</strong>.</td>
    </tr>

    <tr>
      <td><strong>Email</strong></td>
      <td>Not directly editable. Click <strong>Actions > Change Email</strong> at the top right of this screen.</td>
    </tr>

    <tr>
      <td><strong>Password</strong></td>
      <td>Not directly editable. Click <strong>Actions > Change Password</strong> at the top right of this screen.</td>
    </tr>
  </tbody>
</table>

To delete a user, click **Actions > Delete User**.

## Programmatic process

You can retrieve, edit, and delete user information using our API. Choose an endpoint that matches your needs:

* Retrieve a user using the ID as search criteria
* Retrieve a user using the Email as search criteria
* Export all users to a file using a long running job
* Update a user. Note that not all fields are editable (see the next section). Keep in mind that:

  * The properties of the new object will replace the old ones. The `user_metadata` and `app_metadata` fields are an exception to this rule. These properties are merged instead of being replaced, though the merge happens only on the first level.
  * If you are updating `email_verified`, `phone_verified`, `username`, or `password`, you must set the `connection` parameter.
  * If your are updating `email` or `phone_number`, you must set the `connection` and the `client_id` parameters.
* Delete a user based on the ID

In order to call any of the API endpoints, you will need an valid <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>. This token must have the required permissions per endpoint. Each endpoint at the Management API explorer has a scopes section that lists the scope(s) that the access token must contain in order to access it. Once you know which endpoint you want to access, and you have a valid access token, you are ready to send your request.

## Editable data

The following user information can be updated using the API:

* blocked
* email\_verified
* email
* verify\_email
* password
* phone\_number
* phone\_verified
* verify\_password
* user\_metadata
* app\_metadata
* username

The following user information are **not** editable:

* given\_name
* family\_name
* name
* nickname
* picture

## Searchable fields

You can search for users using the following:

* All the normalized user profile fields
* The profile information under the `user_metadata` object:

  * name
  * nickname
  * given\_name
  * family\_name

You are responsible for ensuring customer is erased or data is updated in any other databases that Auth0 is not connected to.

## Learn more

* [GDPR: Conditions for Consent](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-conditions-for-consent)
* [GDPR: Data Minimization](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-data-minimization)
* [GDPR: Data Portability](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-data-portability)
* [GDPR: Protect and Secure User Data](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-protect-and-secure-user-data)


# GDPR: Track Consent with Custom UI
Source: https://auth0.com/docs/secure/data-privacy-and-compliance/gdpr/gdpr-track-consent-with-custom-ui

Describes how you can use either auth0.js or the Auth0 APIs to capture consent information when you use your own custom UI for logins.

In this tutorial we will see how you can use auth0.js or the Auth0 APIs to ask for consent information and save the input at the user's metadata. To learn more, read [Understand How Metadata Works in User Profiles](/docs/manage-users/user-accounts/metadata).

If you would instead like to track consent using Lock, see [GDPR: Track Consent with Lock](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-track-consent-with-lock).

The contents of this document are **not** intended to be legal advice, nor should they be considered a substitute for legal assistance. The final responsibility for understanding and complying with GDPR resides with you, though Auth0 will assist you in meeting GDPR requirements where possible.

<Callout icon="file-lines">
  The contents of these documents are not intended to be legal advice, nor should they be considered a substitute for legal assistance. The final responsibility for understanding and complying with GDPR resides with you, though Auth0 will assist you in meeting GDPR requirements where possible.
</Callout>

## Overview

We will capture consent information, under various scenarios, and save this in the user's metadata.

All scenarios will save the following properties in the user's metadata:

* `consentGiven` (true/false) shows if the user has provided consent (true) or not (false)
* `consentTimestamp` (Unix timestamp) indicates when the user-provided consent

For example:

```json lines theme={null}
{
  "consentGiven": "true"
  "consentTimestamp": "1525101183"
}
```

We will see four different implementations for this:

1. one that displays a flag, works for database connections, and uses the auth0.js library to create the user (used by Single-Page Applications). To learn more, read [Auth0.js v9 Reference](/docs/libraries/auth0js).
2. one that displays a flag, works for database connections, and uses the Authentication API to create the user (used by Regular Web Apps)
3. one that displays a flag, works for social connections, and uses the Management API to update the user's information (used either by SPAs or Regular Web Apps)
4. one that redirects to another page where the Terms & Conditions and/or privacy policy information can be reviewed and consent info can be provided (used either by SPAs or Regular Web Apps)

## Option 1: Use auth0.js

In this section, we will use a simple Single-Page Application and customize the login widget to add a flag which users can use to provide consent information. Instead of building an app from scratch, we will [use Auth0's JavaScript Quickstart sample](/docs/quickstart/spa/vanillajs). We will also use Auth0's <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> pages so we can implement Universal Login, instead of embedding the login in our app. To learn more about Universal Login, read [Auth0 Universal Login](/docs/authenticate/login/auth0-universal-login). To learn more about the differences between Universal Login and embedded login, read [Centralized Universal Login vs. Embedded Login](/docs/authenticate/login/universal-vs-embedded-login).

This works **only** for database connections (we will use Auth0's infrastructure, instead of setting up our own database).

1. Go to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and create a new application. Choose `Single Web Page Applications` as type. Go to **Settings** and set the **Allowed Callback URLs** to `http://localhost:3000`.

   This field holds the set of URLs to which Auth0 is allowed to redirect the users after they authenticate. Our sample app will run at `http://localhost:3000` hence we set this value.

2. Copy the **Client Id** and **Domain** values. You will need them in a while.

3. Go to [Auth0 Dashboard > Authentication > Database](https://manage.auth0.com/#/connections/database) and create a new connection. Click **Create DB Connection**, set a name for the new connection, and click **Save**. Go to the connection's **Applications** tab and make sure your newly created application is enabled.

4. [Download the JavaScript SPA Sample](/docs/quickstart/spa/vanillajs).

5. [Set the Client ID and Domain values](https://github.com/auth0-samples/auth0-javascript-samples/tree/master/01-Login#set-the-client-id-and-domain).

6. Go to [Auth0 Dashboard > Branding > Universal Login](https://manage.auth0.com/#/login_settings). At the **Login** tab enable the toggle.

7. At the **Default Templates** dropdown make sure that `Custom Login Form` is picked. The code is pre-populated for you.

8. Set the value of the `databaseConnection` variable to the name of the database connection your app is using.

   ```javascript lines theme={null}
   //code reducted for simplicity
   	var databaseConnection = 'test-db';
   	//code reducted for simplicity
   ```

9. To add a field for the `consentGiven` metadata, add a checkbox at the form. For our example, we will configure the checkbox as checked by default and disabled so the user cannot uncheck it. You can adjust this according to your business needs.

   ```javascript lines theme={null}
   //code reducted for simplicity
       <div class="form-group">
         <label for="name">I consent with data processing</label>
         <input
           type="checkbox"
           id="userConsent"
           checked disabled>
       </div>
       //code reducted for simplicity
   ```

10. Edit the signup function to set the metadata. Note that we set the value of the metadata to a string with the value `true` and not to a boolean value, and we are using `toString` to convert the number to a string. This is due to a restriction of the Authentication API [**Signup** endpoint](https://auth0.com/docs/api/authentication#signup) which only accepts strings as values.

    ```text lines theme={null}
    //code reducted for simplicity
        webAuth.redirect.signupAndLogin({
          connection: databaseConnection,
          email: email,
          password: password,
          user_metadata: { consentGiven: 'true', consentTimestamp: Date.now().toString() }
        }, function(err) {
          if (err) displayError(err);
        });
        //code reducted for simplicity
    ```

11. To see what the login widget will look like, click the **Preview** tab.

<Frame>
  <img alt="Dashboard Branding Universal Login Classic Login Tab Custom Login Form" />
</Frame>

1. To test this configuration run the application and go to `http://localhost:3000`. Sign up with a new user. Then go to [Auth0 Dashboard > User Management > Users](https://manage.auth0.com/#/users) and search for your new user. Go to **User Details** and scroll down to the **Metadata** section. At the **user\_metadata** text area, you should see the `consentGiven` metadata set to `true`.

## Option 2: Use the API (database)

If you serve your login page from your own server, then you can call the Authentication API [**Signup** endpoint](https://auth0.com/docs/api/authentication#signup) directly once the user signs up.

For the same scenario we have been discussing so far, once you sign up a new user, you can use the following snippet to create the user at Auth0 and set the metadata. Remember to replace the value of the `consentTimestamp` request parameter with the timestamp of when the user provided consent.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/dbconnections/signup' \
    --header 'content-type: application/json' \
    --data '{"client_id": "{yourClientId}","email": "YOUR_USER_EMAIL","password": "YOUR_USER_PASSWORD","user_metadata": {"consentGiven": "true", "consentTimestamp": "1525101183" }}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/dbconnections/signup");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"client_id": "{yourClientId}","email": "YOUR_USER_EMAIL","password": "YOUR_USER_PASSWORD","user_metadata": {"consentGiven": "true", "consentTimestamp": "1525101183" }}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/dbconnections/signup"

  	payload := strings.NewReader("{"client_id": "{yourClientId}","email": "YOUR_USER_EMAIL","password": "YOUR_USER_PASSWORD","user_metadata": {"consentGiven": "true", "consentTimestamp": "1525101183" }}")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.post("https://{yourDomain}/dbconnections/signup")
    .header("content-type", "application/json")
    .body("{"client_id": "{yourClientId}","email": "YOUR_USER_EMAIL","password": "YOUR_USER_PASSWORD","user_metadata": {"consentGiven": "true", "consentTimestamp": "1525101183" }}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/dbconnections/signup',
    headers: {'content-type': 'application/json'},
    data: {
      client_id: '{yourClientId}',
      email: 'YOUR_USER_EMAIL',
      password: 'YOUR_USER_PASSWORD',
      user_metadata: {consentGiven: 'true', consentTimestamp: '1525101183'}
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"client_id": @"{yourClientId}",
                                @"email": @"YOUR_USER_EMAIL",
                                @"password": @"YOUR_USER_PASSWORD",
                                @"user_metadata": @{ @"consentGiven": @"true", @"consentTimestamp": @"1525101183" } };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/dbconnections/signup"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/dbconnections/signup",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{"client_id": "{yourClientId}","email": "YOUR_USER_EMAIL","password": "YOUR_USER_PASSWORD","user_metadata": {"consentGiven": "true", "consentTimestamp": "1525101183" }}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"client_id": "{yourClientId}","email": "YOUR_USER_EMAIL","password": "YOUR_USER_PASSWORD","user_metadata": {"consentGiven": "true", "consentTimestamp": "1525101183" }}"

  headers = { 'content-type': "application/json" }

  conn.request("POST", "/{yourDomain}/dbconnections/signup", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/dbconnections/signup")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request.body = "{"client_id": "{yourClientId}","email": "YOUR_USER_EMAIL","password": "YOUR_USER_PASSWORD","user_metadata": {"consentGiven": "true", "consentTimestamp": "1525101183" }}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/json"]
  let parameters = [
    "client_id": "{yourClientId}",
    "email": "YOUR_USER_EMAIL",
    "password": "YOUR_USER_PASSWORD",
    "user_metadata": [
      "consentGiven": "true",
      "consentTimestamp": "1525101183"
    ]
  ] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/dbconnections/signup")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

Note that we set the value of the metadata to a string with the value `true` and not to a boolean value due to the API restriction that accepts strings as values, not booleans.

If setting boolean values is a requirement for you, you can use the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> instead. In this scenario you sign up your user as usual, and then you call the Management API [**Update User** endpoint](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id) to set the required metadata after the user has been created. For details on how to do that keep reading, the next paragraph uses that endpoint.

## Option 3: Use the API (social)

If you use social connections, then you cannot use the Authentication API to create the user at Auth0, since that endpoint works only for database connections.

What you have to do instead is let your user sign up with the social provider (which will create a user record at Auth0) and then use the Management API to update the user's information.

Before you call the Management API you need to get a valid token. To learn more, read [Get Management API Access Tokens for Production](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production).

The linked article uses the Client Credentials Flow to get a token, which you cannot use from an app running on the browser. What you can use instead is the Implicit Flow. To learn more about the Client Credentials Flow, read [Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow). To learn more about the Implicit Flow, read [Implicit Flow](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post).

Set the **<Tooltip href="/docs/glossary?term=audience">audience</Tooltip>** request parameter to `https://YOUR_DOMAIN/api/v2/` and the **scope** parameter to the scope `create:current_user_metadata`. You can use the <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> you will get at the response to call the Management API [**Update User** endpoint](https://auth0.com/docs/api/management/v2#!/Users/patch_users_by_id).

Once you have a valid token, use the following snippet to update the user's metadata.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/users/%7BUSER_ID%7D' \
    --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
    --header 'content-type: application/json' \
    --data '{"user_metadata": {"consentGiven":true, "consentTimestamp": "1525101183"}}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/%7BUSER_ID%7D");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer YOUR_ACCESS_TOKEN");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"user_metadata": {"consentGiven":true, "consentTimestamp": "1525101183"}}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users/%7BUSER_ID%7D"

  	payload := strings.NewReader("{"user_metadata": {"consentGiven":true, "consentTimestamp": "1525101183"}}")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("authorization", "Bearer YOUR_ACCESS_TOKEN")
  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse response = Unirest.post("https://{yourDomain}/api/v2/users/%7BUSER_ID%7D")
    .header("authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("content-type", "application/json")
    .body("{"user_metadata": {"consentGiven":true, "consentTimestamp": "1525101183"}}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/users/%7BUSER_ID%7D',
    headers: {authorization: 'Bearer YOUR_ACCESS_TOKEN', 'content-type': 'application/json'},
    data: {user_metadata: {consentGiven: true, consentTimestamp: '1525101183'}}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer YOUR_ACCESS_TOKEN",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"user_metadata": @{ @"consentGiven": @YES, @"consentTimestamp": @"1525101183" } };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/%7BUSER_ID%7D"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/%7BUSER_ID%7D",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{"user_metadata": {"consentGiven":true, "consentTimestamp": "1525101183"}}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer YOUR_ACCESS_TOKEN",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"user_metadata": {"consentGiven":true, "consentTimestamp": "1525101183"}}"

  headers = {
      'authorization': "Bearer YOUR_ACCESS_TOKEN",
      'content-type': "application/json"
      }

  conn.request("POST", "/{yourDomain}/api/v2/users/%7BUSER_ID%7D", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/%7BUSER_ID%7D")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer YOUR_ACCESS_TOKEN'
  request["content-type"] = 'application/json'
  request.body = "{"user_metadata": {"consentGiven":true, "consentTimestamp": "1525101183"}}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer YOUR_ACCESS_TOKEN",
    "content-type": "application/json"
  ]
  let parameters = ["user_metadata": [
      "consentGiven": true,
      "consentTimestamp": "1525101183"
    ]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/%7BUSER_ID%7D")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

Note that in order to make this call you need to know the unique `user_id`. You can retrieve this from the `sub` claim of the <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip>, if you got one from the response. To learn more, read [ID Tokens](/docs/secure/tokens/id-tokens). Alternatively, if all you have is the email, you can retrieve the Id by calling another endpoint of the Management API. To learn more, read [User Search Best Practices](/docs/manage-users/user-search/user-search-best-practices).

## Option 4: Redirect to another page

If you want to display more information to your user, then upon signup you can redirect to another page where you ask for consent and any additional info, and then redirect back to finish the authentication transaction. This can be done with redirect rules. That same rule can be used to save the consent information at the user's metadata so you can track this information and not ask for consent upon next login. To learn more, read [Redirect Users from Within Rules](/docs/customize/rules/redirect-users).

You will need to host this form, and the URL for the form must be publicly-accessible. You'll need to provide the URL where the form can be accessed to Auth0 at a later step of this tutorial.

1. Add the redirect rule. Go to [Auth0 Dashboard > Auth Pipeline > Rules](https://manage.auth0.com/#/rules), and click **Create Rule**. At **Rules Templates**, select **empty rule**. Change the default rule's name from `empty rule` to something descriptive (e.g., `Redirect to consent form`).

2. Add the following JavaScript code to the script editor, and **Save** your changes.

   ```js lines theme={null}
   exports.onExecutePostLogin = async (event, api) => {
       const { consentGiven } = event.user.user_metadata || {};

       // redirect to consent form if user has not yet consented
       if (!consentGiven && api.redirect.canRedirect()) {
         const options = {
           query: {
             auth0_domain: `${event.tenant.id}.auth0.com`,
           },
         };
         api.redirect.sendUserTo(event.secrets.CONSENT_FORM_URL, options);
       }
   };

   // if user clicks 'I agree' on the consent form, save it to their profile so they don't get prompted again
   exports.onContinuePostLogin = async (event, api) => {
     if (event.request.body.confirm === "yes") {
       api.user.setUserMetadata("consentGiven", true);
       api.user.setUserMetadata("consentTimestamp", Date.now());
       return;
     } else {
       return api.access.deny("User did not consent");
     }
   };
   ```

3. Return to [Auth0 Dashboard > Auth0 Pipeline > Rules](https://manage.auth0.com/#/rules) and scroll down to the bottom of the page where the **Settings** section is. Create a key/value pair as follows:

   1. **Key**: `CONSENT_FORM_URL`
   2. **Value**: `your-consent-form-url.com`

Be sure to provide the publicly-accessible URL where your consent form can be found.

When setting up redirection to your consent form for use in a Production environment, be sure to review [Trusted Callback URLs](https://github.com/auth0/rules/tree/master/redirect-rules/simple#trusted-callback-urls) and [Data Integrity](https://github.com/auth0/rules/tree/master/redirect-rules/simple#data-integrity) regarding security concerns.

If you require a specialized consent prompt, for example a parental consent, you need to build your own custom consent form. Be aware that laws vary according to country.

We are done with the configuration part, let's test!

## Test the configuration

1. Run the application and go to `https://localhost:3000`.
2. Sign up with a new user. You will be redirected to the consent form.
3. Check the **I agree** flag, and click **Submit**.
4. Go to [Auth0 Dashboard > User Management > Users](https://manage.auth0.com/#/users), and search for your new user.
5. Go to **User Details**, and scroll down to the **Metadata** section.
6. At the **user\_metadata** text area, you should see the `consentGiven` metadata set to `true` and the `consentTimestamp` set to the Unix timestamp of the moment the user consented.

That's it, you are done!


# GDPR: Track Consent with Lock
Source: https://auth0.com/docs/secure/data-privacy-and-compliance/gdpr/gdpr-track-consent-with-lock

Describes how you can customize Lock to capture consent information

In this tutorial, we will see how you can use Lock to ask for consent information, and then save this input in the user's metadata. To learn more, read [Understand How Metadata Works in User Profiles](/docs/manage-users/user-accounts/metadata).

If you would instead like to track consent using a custom UI, see [GDPR: Track Consent with Custom UI](/docs/secure/data-privacy-and-compliance/gdpr/gdpr-track-consent-with-custom-ui).

The contents of this document are **not** intended to be legal advice, nor should they be considered a substitute for legal assistance. The final responsibility for understanding and complying with GDPR resides with you, though Auth0 will assist you in meeting GDPR requirements where possible.

<Callout icon="file-lines">
  The contents of these documents are not intended to be legal advice, nor should they be considered a substitute for legal assistance. The final responsibility for understanding and complying with GDPR resides with you, though Auth0 will assist you in meeting GDPR requirements where possible.
</Callout>

## Overview

We will configure a simple JavaScript Single-Page Application and a database connection (we will use Auth0's infrastructure, instead of setting up our own database).

Instead of building an app from scratch, we will [use Auth0's JavaScript Quickstart sample](/docs/quickstart/spa/vanillajs). We will also use Auth0's <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> pages so we can implement a Universal Login experience, instead of embedding the login in our app. To learn more about Universal Login, read [Auth0 Universal Login](/docs/authenticate/login/auth0-universal-login). To learn more about the differences between Universal Login and embedded login, read [Centralized Universal Login vs. Embedded Login](/docs/authenticate/login/universal-vs-embedded-login).

We will capture consent information, under various scenarios, and save this at the user's metadata.

All scenarios will save the following properties at the user's metadata:

* a `consentGiven` property, with true/false values, shows if the user has provided consent (true) or not (false)
* a `consentTimestamp` property, holding the Unix timestamp of when the user-provided consent

For example:

```json lines theme={null}
{
  "consentGiven": "true"
  "consentTimestamp": "1525101183"
}
```

We will see three different implementations for this:

* one that displays links to other pages where the Terms & Conditions and/or privacy policy information can be reviewed
* one that adds custom fields at the signup widget and works for database connections
* one that redirects to another page where the user can provide consent, and works for social connections

## Configure the application

1. Go to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and create a new application. Choose `Single Web Page Applications` as type.
2. Go to **Settings** and set the **Allowed Callback URLs** to `http://localhost:3000`.

   This field holds the set of URLs to which Auth0 is allowed to redirect the users after they authenticate. Our sample app will run at `http://localhost:3000` hence we set this value.
3. Copy the **Client Id** and **Domain** values. You will need them in a while.
4. Go to [Auth0 Dashboard > Authentication > Database](https://manage.auth0.com/#/connections/database) and create a new connection. Click **Create DB Connection**, set a name for the new connection, and click **Save**. You can also enable a social connection at [Auth0 Dashboard > Authentication > Social](https://manage.auth0.com/#/connections/social) (we will enable Google login for the purposes of this tutorial).
5. Go to the connection's **Applications** tab and make sure your newly created application is enabled.
6. [Download the JavaScript SPA Sample](/docs/quickstart/spa/vanillajs).

## Option 1: Display Terms & Conditions link

In this section, we will customize the login widget to add a flag that users must check in order to sign up. The flag's label will include links to pages that display the Terms & Conditions and privacy policy.

This works both for database connections and social logins.

1. Go to [Auth0 Dashboard > Branding > Universal Login](https://manage.auth0.com/#/login_page).
2. Select the **Login** view, and enable the **Customize Login Page** toggle.
3. Locate the **Default Templates** dropdown, and select `Lock`. The code block will be pre-populated for you.
4. To add a field for the `consentGiven` metadata, use the `mustAcceptTerms` option. To include links to your Terms & Conditions and/or privacy policy pages, use the `languageDictionary` option. To learn more, read [Lock Configuration Options](/docs/libraries/lock/lock-configuration). The example below displays text that says `I agree to the terms of service and privacy policy` (including links to both pages) next to the flag:

   ```javascript lines theme={null}
   //code reducted for simplicity
       var lock = new Auth0Lock(config.clientID, config.auth0Domain, {
         auth: {
           //code reducted for simplicity
         },
         languageDictionary: {
           signUpTerms: "I agree to the <a href='https://my-app-url.com/terms' target='_blank'>terms of service</a> and <a href='https://my-app-url.com/privacy' target='_blank'>privacy policy</a>."
         },
         mustAcceptTerms: true,
         //code reducted for simplicity
       });
   ```

   To see what this will look like, select the **Preview** view, then when Lock loads, select **Sign Up**.
5. This flag forces users to accept the terms before they can sign up, but it does not set any metadata. To save the user's selection in the `consentGiven` metadata property, [create a new Action](/docs/customize/actions/write-your-first-action). Enter a descriptive **Name** for your Action (for example, `Set consent flag upon signup`), select the `Login / Post Login` trigger because you’ll be adding the Action to the Login flow, then select **Create**.
6. The following screen is the Actions code editor. Copy the following JavaScript code into it, then select **Save Draft** to save your changes:

   ```text lines theme={null}
   exports.onExecutePostLogin = async (event, api) => {
     const { consentGiven } = event.user.user_metadata || {};

     // short-circuit if the user signed up already
     if ( consentGiven ) {
       return;
     }

     // first time login/signup
     api.user.setUserMetadata("consentGiven", true);
     api.user.setUserMetadata("consentTimestamp", Date.now());
     return;
   }
   ```

   This code sets the `consentGiven` metadata to `true` if it is not already set (which means it's the first login after a signup).
7. From the Actions Code Editor sidebar, select Test (play icon), then select **Run** to [test your code](/docs/customize/actions/test-actions).
8. When you’re ready for the Action to go live, select **Deploy**.

Finally, add the Action you created to the [Login Flow](https://manage.auth0.com/#/actions/flows/login/). To learn how to attach Actions to Flows, read the "Attach the Action to a flow" section in [Write Your First Action](/docs/customize/actions/write-your-first-action).

## Option 2: Add custom fields for database connections

In this section, we will customize the login widget to add a flag that users will check if they agree to the processing of their information.

This works only for database connections (if you use social logins, see the next paragraph).

1. Navigate to [Auth0 Dashboard > Branding > Universal Login](https://manage.auth0.com/#/login_page).

2. Select the **Login** view, and enable the **Customize Login Page** toggle.

3. Locate the **Default Templates** dropdown, and select `Lock`. The code block will be pre-populated for you.

4. To add a field for the `consentGiven` metadata, use the `additionalSignUpFields` option. To learn more, read [Lock Configuration Options](/docs/libraries/lock/lock-configuration). The example below sets the type to `checkbox` (so we have a flag), the label to `I consent to data processing`, and the default value to `checked`.

   ```javascript lines theme={null}
   //code reducted for simplicity
       var lock = new Auth0Lock(config.clientID, config.auth0Domain, {
         auth: {
           //code reducted for simplicity
         },
         additionalSignUpFields: [{
           type: "checkbox",
           name: "consentGiven",
           prefill: "true",
           placeholder: "I consent to data processing"
         }],
         //code reducted for simplicity
       });
   ```

5. To see what this will look like, select the **Preview** view, and when Lock loads, select **Sign Up**.

Note that in this option, we only set the flag and not the timestamp. Displaying the current time in the login widget is not optimal, that's why we didn't add an additional signup field. What you should do is set the timestamp in the background, with a rule that will check the value of `consentGiven` and set the additional `consentTimestamp` metadata to the current timestamp.

## Option 3: Redirect to another page

If you are using social logins, adding custom fields is not an option, but you can redirect the user to another page where you ask for consent and any additional info, and then redirect back to finish the authentication transaction. This can be done with Redirect Actions. To learn more, read [Redirect with Actions](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/redirect-with-actions). We will use this same Action to save the consent information in the user's metadata, so we can track this information and not ask for consent upon the next login.

For simplicity, we will use a [sample consent form](https://github.com/auth0/rules/blob/master/redirect-rules/simple/webtask.js#L31). You will need to host this form, and the URL for the form must be publicly-accessible. You'll need to provide the URL where the form can be accessed to Auth0 in Step 2. If you need a specialized consent prompt (for example, a parental consent), you must build your own custom consent form. Be aware that laws vary according to country.

1. [Create a new Action](/docs/customize/actions/write-your-first-action). Enter a descriptive **Name** for your Action (for example, `Redirect to consent form`), select the `Login / Post Login` trigger because you’ll be adding the Action to the Login flow, then select **Create**.

2. Locate the Actions Code Editor, and select the **Secrets** (key) icon in its sidebar. Add the consent form URL as a Secret by creating a key/value pair:

   * **Key**: `CONSENT_FORM_URL`
   * **Value**: `your-consent-form-url.com` (Be sure to provide the publicly-accessible URL where your consent form can be found.)

3. Copy the following JavaScript code into the Actions Code Editor, and select **Save Draft** to save your changes:

   ```text lines theme={null}
   exports.onExecutePostLogin = async (event, api) => {
       const { consentGiven } = event.user.user_metadata || {};

       // redirect to consent form if user has not yet consented
       if (!consentGiven && api.redirect.canRedirect()) {
         const options = {
           query: {
             auth0_domain: `${event.tenant.id}.auth0.com`,
           },
         };
         api.redirect.sendUserTo(event.secrets.CONSENT_FORM_URL, options);
       }
   };

   // if user clicks 'I agree' on the consent form, save it to their profile so they don't get prompted again
   exports.onContinuePostLogin = async (event, api) => {
     if (event.request.body.confirm === "yes") {
       api.user.setUserMetadata("consentGiven", true);
       api.user.setUserMetadata("consentTimestamp", Date.now());
       return;
     } else {
       return api.access.deny("User did not consent");
     }
   };
   ```

4. From the Actions Code Editor sidebar, select Test (play icon), then select **Run** to [test your code](/docs/customize/actions/test-actions).

5. When you’re ready for the Action to go live, select **Deploy**.

Finally, add the Action you created to the [Login Flow](https://manage.auth0.com/#/actions/flows/login/). To learn how to attach Actions to Flows, read the "Attach the Action to a flow" section in [Write Your First Action](/docs/customize/actions/write-your-first-action).

When setting up redirection to your consent form for use in a Production environment, be sure to review [Trusted Callback URLs](https://github.com/auth0/rules/tree/master/redirect-rules/simple#trusted-callback-urls) and [Data Integrity](https://github.com/auth0/rules/tree/master/redirect-rules/simple#data-integrity) regarding security concerns.

We are done with the configuration part; let's test!

## Test the configuration

1. Go to the folder where you downloaded the application and run it.

   ```text lines theme={null}
   npm install
       npm run
   ```

2. Go to `http://localhost:3000`. Click **Login**. Once Lock is displayed, click **Sign Up**.
   The login page will be served by default at `YOUR_DOMAIN/login`. To learn how to use your own domain, read [Custom Domains](/docs/customize/custom-domains).

3. If you followed the first implementation option, you should see the flag to accept the terms of service and privacy policy. Note that the **Sign up** button remains disabled until you check the flag. Follow the links to check they are working. Set an email and password and accept the terms and click **Sign Up**. Alternatively, if you use a social connection, accept the terms, and choose **Sign Up with Google**.

4. If you followed the second implementation option, you should see the new custom field we added. Set an email and password and leave the `I consent to data processing` flag checked. Click **Sign Up**.

5. If you followed the third implementation option, choose **Sign Up with Google**. You will be navigated to the consent form. Check the **I agree** flag and click **Submit**.

   If you do not check the **I agree** flag before clicking **Submit**, then you will see a popup error `Unauthorized. Check the console for details.`. At the console you will see this JSON:

   ```json lines theme={null}
   {
         error: "unauthorized", 
         errorDescription: "User did not consent!", 
         state: "q0GjMwzZN_q5r8XPHvfakkMYcYM2q1N3"
       }
   ```

   Note, that the user is created but they won't be able to log in. If they try to, they will be prompted again to provide consent.

6. Go to [Auth0 Dashboard > User Management > Users](https://manage.auth0.com/#/users) and search for the new user.

7. Go to **User Details** and scroll down to the **Metadata** section. At the **user\_metadata** text area you should see the following:

   ```json lines theme={null}
   {
         "consentGiven": "true"
         "consentTimestamp": "1525101183"
       }
   ```

That's it; you are done!


# Tenant Access Control List
Source: https://auth0.com/docs/secure/tenant-access-control-list

Tenant Access Control List (ACL) allows you to manage traffic to your Auth0 services with configurable rules.

Tenant Access Control List (ACL) allows you to manage traffic to your Auth0 services with configurable rules. It helps you protect your tenant and conserve your rate limits against potential threats, such as denial-of-service (DoS) attacks, and ensures that only legitimate users access your applications.

## How it works

When your tenant or <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> receives a request, Tenant ACL processes that request and then determines how to respond based on the rules you have configured.

For example, if you are adopting Model Context Protocols (MCP) in your tenant, you could use the `dcr` scope to avoid risks like unauthorized application registration or phishing attempts via misleading application names. To learn more, review [References](/docs/secure/tenant-access-control-list/reference).

## Rules

Rules are the building blocks of the Tenant ACL feature. A rule is composed of the following elements:

* **Signal**: The signal is an identifying piece of information that is provided by the incoming request, such as IP address, geolocation, or user agent.
* **Condition**: The condition is the combination of an operator (such as `match`) and a set of values (such as a list of IP addresses).
* **Action**: The action is the directive that your rule executes if criteria are met, such as allow, block, or redirect.
* **Scope**: The scope indicates which sets of endpoints that the rule is enforced for, including the Authentication API, Management API, or your entire tenant.
* **Priority**: The priority defines the order in which the rule runs relative to other rules.

### Importance of priority

It’s important to determine the correct priority of your rules, because there is strict execution logic you must follow:

* **Evaluation order:** Tenant ACL evaluates rules in numerical order, with smaller numbers executing first. For example, a rule with priority 1 runs before priority 2, and priority 3 runs before priority 4.
* **Match termination:** If a rule’s conditions are met, Tenant ACL performs the rule’s action immediately and does not evaluate subsequent rules and lists.​
* **Monitoring mode exception:** If a rule's conditions are met but it’s in monitoring mode, Tenant ACL performs no action and skips to the next rule.

Careful assignment of priorities allows you to create granular access control policies tailored specific to your needs.

## Monitoring mode

When a rule is in monitoring mode, Tenant ACL evaluates that rule as it normally would and emits a tenant log event, but does not execute the rule’s action and does not terminate evaluation of subsequent rules and lists.

Monitoring mode is the best way to test how your Tenant ACL rule would affect incoming traffic without interfering with your current Tenant ACL configuration.

You can toggle monitoring mode for a rule by updating the `action` object. To learn more, read [Configure Rules](/docs/secure/tenant-access-control-list/configure-rules).

## Logging

A log event (`acls_summary`) is created every 10 minutes for each Tenant ACL rule with details of how that rule is affecting traffic.

<ResponseField name="acls_summary" type="object">
  <Expandable>
    <ResponseField name="acl_id" type="string">
      Internal identifier of the rule.

      Example: `acl_vENikGo5fcJd7FYMLvjKKP`
    </ResponseField>

    <ResponseField name="description" type="string">
      Description of the rule.

      Example: `Allow traffic that originates from the United States`
    </ResponseField>

    <ResponseField name="priority" type="number">
      Order in which the rule executes.

      Example: `1`
    </ResponseField>

    <ResponseField name="action" type="object">
      Action that the rule executes.

      Example: `{ "allow": true }`
    </ResponseField>

    <ResponseField name="match" type="object">
      <Expandable>
        <ResponseField name="success" type="number">
          Total number of requests that the rule successfully matched.

          Example: `1`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="total_request_count" type="object">
      <Expandable>
        <ResponseField name="successes" type="number">
          Total number of requests that the rule successfully evaluated.

          Example: `3`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="start_time" type="string">
      Datetime stamp of when the log counting period started.

      Example: `2025-03-19T16:11:07.429Z`
    </ResponseField>

    <ResponseField name="end_time" type="string">
      Datetime stamp of when the log counting period ended.

      Example: `2025-03-19T16:21:07.429Z`
    </ResponseField>
  </Expandable>
</ResponseField>

## Restrictions and limitations

* Customers on an Enterprise plan can create 1 Tenant ACL.
* Customers on an Enterprise plan with the Attack Protection add-on can create up to 10 Tenant ACLs.
* Each Tenant ACL can include up to 10 entries per source identifier (such as IPv4, CIDR, and more).
* The **User Agent** identifier is not supported when using self-managed custom domains.
* The `auth0-fowarded-for` header is not supported.

## Learn more

* [Configure Rules](./tenant-access-control-list/configure-rules)
* [Use Cases](./tenant-access-control-list/use-cases)
* [Reference](./tenant-access-control-list/reference)


# Configure Rules
Source: https://auth0.com/docs/secure/tenant-access-control-list/configure-rules

Learn how to configure Tenant Access Control List (ACL) rules with the Auth0 Management API.

<Card>
  To configure a Tenant ACL rule, you need a [Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production) with the following scopes:

  * `create:network_acls`
  * `update:network_acls`
  * `read:network_acls`
  * `delete:network_acls`
</Card>

You can configure Tenant Access Control List (ACL) rules with the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## Available actions

You can view, create, update, and delete Tenant ACL rules with the Management API.

| Action           | Endpoint                                                                                                             | Required scope        |
| ---------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------- |
| View a rule      | [Get a specific access control list entry for a tenant](/docs/api/management/v2/network-acls/get-network-acls-by-id) | `read:network_acls`   |
| View all rules   | [Get all access control list entries for a tenant](/docs/api/management/v2/network-acls/get-network-acls)            | `read:network_acls`   |
| Create a rule    | [Create access control list](/docs/api/management/v2/network-acls/post-network-acls)                                 | `create:network_acls` |
| Update a rule    | [Partial update for an access control list](/docs/api/management/v2/network-acls/patch-network-acls-by-id)           | `update:network_acls` |
| Overwrite a rule | [Update access control list](/docs/api/management/v2/network-acls/put-network-acls-by-id)                            | `update:network_acls` |
| Delete a rule    | [Delete access control list](/docs/api/management/v2/network-acls/delete-network-acls-by-id)                         | `delete:network_acls` |

## Parameters

For detailed information about Tenant ACL parameters and how to use them, read [Reference](./reference).

<ParamField type="string">
  Describes the purpose or functionality of the rule.

  Example: `Only allow requests originating from the United States`
</ParamField>

<ParamField type="boolean">
  Enables or disables the rule.

  Example: `true`
</ParamField>

<ParamField type="number">
  Numerical value that determines the order in which the rule is evaluated.

  Example: `1`
</ParamField>

<ParamField type="object">
  Contains the conditions and actions of the rule.

  <Expandable>
    <ParamField type="object">
      Contains the action that the rule performs.

      Example: `{ allow: true }`
    </ParamField>

    <ParamField type="object">
      Defines the condition(s) that the incoming request must fulfill.

      Example: `{ geo_country_codes: ["US"] }`
    </ParamField>

    <ParamField type="object">
      Defines the condition(s) that the incoming request must not fulfill.

      Example: `{ geo_country_codes: ["CN"] }`
    </ParamField>

    <ParamField type="string">
      Service or context in which the rule is enforced.

      Example: `authentication`
    </ParamField>
  </Expandable>
</ParamField>

## Examples

## Toggle monitoring mode for a rule

You can enable [monitoring mode](../tenant-access-control-list) for a Tenant ACL rule with the Management API [Update access control list](https://auth0.com/docs/api/management/v2/network-acls/put-network-acls-by-id) endpoint.

Add the `log` property to the `rule.action` object and set its value to `true`.


# Manage Rules in Dashboard
Source: https://auth0.com/docs/secure/tenant-access-control-list/manage-rules-in-dashboard

Learn how to manage Tenant ACL rules in the Auth0 Dashboard.

You can use the Auth0 Dashboard to view a list of your Tenant Access Control List (ACL) rules and toggle them individually.

## View list of rules

Go to [Dashboard > Security > Access Control](https://manage.auth0.com/#/security/access-control) to view a list of your existing rules.

| Column name  | Description                                                                                     | Related API response field |
| ------------ | ----------------------------------------------------------------------------------------------- | -------------------------- |
| Priority     | Ordinal number indicating when the rule is evaluated                                            | `priority`                 |
| Name         | Description of the rule's purpose or functionality                                              | `description`              |
| Action       | The [action](/docs/secure/tenant-access-control-list/reference#actions) that the rule performs. | `action`                   |
| Status       | Value indicating whether the rule is active or disabled.                                        | `active`                   |
| Last Updated | Datetime stamp of when the rule was last updated.                                               | `updated_at`               |

<img alt="View list of Tenant ACL rules in the Auth0 Dashboard" />

## Enable or disable a rule

You can enable or disable a specific rule by toggling the button next to it.

The **Status** field shows the rule as `Active` or `Disabled` accordingly.

<img alt="Enable or disable a Tenant ACL rule in the Auth0 Dashboard" />


# Reference
Source: https://auth0.com/docs/secure/tenant-access-control-list/reference

Contains Tenant Access Control List reference materials, such as signals, conditions, actions, and scopes.

Tenant Access Control List (ACL) supports advanced customization through configuration of various settings. Refer to the sections below to learn more about available options.

## Signals

<ParamField type="string[]">
  List of Autonomous System Numbers (ASNs)
</ParamField>

<ParamField type="string[]">
  List of IPv4 addresses or CIDR ranges.
</ParamField>

<ParamField type="string[]">
  List of IPv6 addresses or CIDR ranges.
</ParamField>

<ParamField type="string[]">
  List of ISO 3166-1 alpha-2 country code.
</ParamField>

<ParamField type="string[]">
  List of ISO 3166-2 subdivision code.
</ParamField>

<ParamField type="string[]">
  List of JA3 TLS Fingerprints.
</ParamField>

<ParamField type="string[]">
  List of JA4 TLS Fingerprints.
</ParamField>

<ParamField type="string[]">
  List of client device or browser.
</ParamField>

## Conditions

<ParamField type="object">
  Returns successful if the provided signal and any of the provided values are equivalent.
</ParamField>

<ParamField type="object">
  Returns successful if the provided signal and none of the provided values are equivalent.
</ParamField>

## Actions

<ParamField type="boolean">
  Allows traffic to pass through unaffected.
</ParamField>

<ParamField type="boolean">
  Blocks traffic from accessing specified scopes.
</ParamField>

<ParamField type="boolean">
  Redirects traffic to a provided location.
</ParamField>

<ParamField type="string">
  URI to redirect traffic to.
</ParamField>

<ParamField type="boolean">
  Monitoring mode. No action is taken, but results are included in the Tenant ACL log event.
</ParamField>

## Scopes

<ParamField>
  Enforces Tenant ACL for both `management` and `authentication` scopes.
</ParamField>

<ParamField>
  Enforces Tenant ACL for requests sent to `{yourDomain}/api/v2/\*}` and `{yourDomain}/scim/\*}`.
</ParamField>

<ParamField>
  Controls access to Dynamic Client Registration endpoint `/oidc/register`.
</ParamField>

<ParamField>
  Enforces Tenant ACL for requests sent to anywhere not covered in `management` scope.
</ParamField>


# Use Cases
Source: https://auth0.com/docs/secure/tenant-access-control-list/use-cases

Learn about the different use cases for the Tenant Access Control List feature.

## Block a request

Here is an example of a Tenant ACL rule that blocks incoming traffic from a specific geolocation country code.

### Example of a block page

<Frame>
  <img alt="" />
</Frame>

## Allow a request

Here is an example of a Tenant ACL rule that allows traffic only from a specific geolocation country code.

## Redirect a request

Here is an example of a Tenant ACL rule that redirects all traffic from a specific geolocation country code.

## Complex comparisons

You can combine the `match` and `not_match` operators in a single Tenant ACL rule to enforce fine-grained access policies.

Here is an example of a Tenant ACL rule that evaluates the `geo_country_code` and `geo_subdivision_code` signals to block all traffic from a given country except for a specific state, region, or province within that country.


# Access Tokens
Source: https://auth0.com/docs/secure/tokens/access-tokens

Describes how access tokens are used in token-based authentication to allow an application to access an API after a user successfully authenticates and authorizes access.

<Card title="Overview">
  Key Concepts

  * Learn about token-based authentication.
  * Read how Auth0 uses self-contained JSON Web Token (JWTs) access tokens that conform to JSON structure with standard claims.
  * Review the provided access token sample and necessary parameters.
  * Set access token lifetime based on the default.
</Card>

<Tooltip href="/docs/glossary?term=Access+tokens">Access tokens</Tooltip> are used in token-based authentication to allow an application to access an API. The application receives an access token after a user successfully authenticates and authorizes access, then passes the access token as a credential when it calls the target API. The passed token informs the API that the bearer of the token has been authorized to access the API and perform specific actions specified by the <Tooltip href="/docs/glossary?term=Scope">Scope</Tooltip> that was granted during authorization.

In addition, if you have chosen to allow users to log in through an <Tooltip href="/docs/glossary?term=Identity+Provider+%28IdP%29">Identity Provider (IdP)</Tooltip>, such as Facebook, the <Tooltip href="/docs/glossary?term=IdP">IdP</Tooltip> will issue its own access token to allow your application to call the IDP's API. For example, if your user authenticates using Facebook, the access token issued by Facebook can be used to call the Facebook Graph API. These tokens are controlled by the IdP and can be issued in any format. See [Identity Provider Access Tokens](/docs/secure/tokens/access-tokens/identity-provider-access-tokens) for details.

## Opaque access tokens

Opaque access tokens are tokens in a proprietary format that you cannot access and typically contain some identifier to information in a server's persistent storage. To validate an opaque token, the recipient of the token needs to call the server that issued the token.

In Auth0's case, opaque tokens can be used with the `/userinfo` endpoint to return a user's profile. If you receive an opaque Access Token, you don't need to validate it. You can use it with the `/userinfo` endpoint, and Auth0 takes care of the rest. To learn more, see [Get Access Tokens](/docs/secure/tokens/access-tokens/get-access-tokens).

## JWT access tokens

<Tooltip href="/docs/glossary?term=JSON+Web+Token">JSON Web Token</Tooltip> (JWT) access tokens conform to the [JWT standard](https://tools.ietf.org/html/rfc7519) and contain information about an entity in the form of claims. They are self-contained therefore it is not necessary for the recipient to call a server to validate the token.

Access tokens issued for the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> and access tokens issued for any custom API that you have registered with Auth0 follow the JWT standard, which means that their basic structure conforms to the typical [JWT structure](/docs/secure/tokens/json-web-tokens/json-web-token-structure), and they contain standard [JWT claims](/docs/secure/tokens/json-web-tokens/json-web-token-claims) asserted about the token itself.

### Management API access tokens

An access token issued for the Auth0 Management API should be treated as opaque (regardless of whether it actually is), so you don't need to validate it. You can use it with the Auth0 Management API, and Auth0 takes care of the rest. To learn more, see [Auth0 Management API Tokens](/docs/secure/tokens/access-tokens/management-api-access-tokens).

### Custom API access tokens

If validation of your custom API access token fails, make sure it was issued with your custom API as the `audience`. To learn more, see [Get Access Tokens](/docs/secure/tokens/access-tokens/get-access-tokens).

## Sample access token

This example shows the contents of an access token. Notice that the token only contains authorization information about the actions the application is allowed to perform at the API (such permissions are referred to as `scopes`).

```json lines theme={null}
{
  "iss": "https://my-domain.auth0.com/",
  "sub": "auth0|123456",
  "aud": [
    "https://example.com/health-api",
    "https://my-domain.auth0.com/userinfo"
  ],
  "azp": "my_client_id",
  "exp": 1311281970,
  "iat": 1311280970,
  "scope": "openid profile read:patients read:admin"
}
```

The token does not contain any information about the user except for the user ID (located in the `sub` claim). In many cases, you may find it useful to retrieve additional user information. You can do this by calling the [userinfo API endpoint](https://auth0.com/docs/api/authentication#get-user-info) with the Access Token. Be sure that the API for which the Access Token is issued uses the **RS256** [signing algorithm](/docs/get-started/applications/signing-algorithms).

## Access token security

You should follow [token best practices](/docs/secure/tokens/token-best-practices) when using access tokens, and for JWTs, make sure that you [validate an access token](/docs/secure/tokens/access-tokens/validate-access-tokens) before assuming that its contents can be trusted.

## Access token lifetime

### Custom API token lifetime

By default, an access token for a custom API is valid for 86400 seconds (24 hours). We recommend that you set the validity period of your token based on the security requirements of your API. For example, an access token that accesses a banking API should expire more quickly than one that accesses a to-do API. To learn more, see [Update Access Token Lifetime](/docs/secure/tokens/access-tokens/update-access-token-lifetime).

### /userinfo endpoint token lifetime

Access tokens issued strictly for the purpose of accessing the OIDC `/userinfo` endpoint have a default lifetime and can't be changed. The length of lifetime depends on the flow used to obtain the token:

<table>
  <thead>
    <tr>
      <th>Flow</th>
      <th>Lifetime</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Implicit</td>
      <td>7200 seconds (2 hours)</td>
    </tr>

    <tr>
      <td>Authorization Code/Hybrid</td>
      <td>86400 seconds (24 hours)</td>
    </tr>
  </tbody>
</table>

## Learn more

* [Get Access Tokens](/docs/secure/tokens/access-tokens/get-access-tokens)
* [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens)
* [Use Access Tokens](/docs/secure/tokens/access-tokens/use-access-tokens)
* [Token Best Practices](/docs/secure/tokens/token-best-practices)


# Access Token Profiles
Source: https://auth0.com/docs/secure/tokens/access-tokens/access-token-profiles

Learn about the access token profiles that Auth0 supports.

<Tooltip href="/docs/glossary?term=Access+token">Access token</Tooltip> profiles define the format and claims of access tokens issued for an API. Auth0 supports the following access token profiles, also known as token dialects:

* Auth0 token profile, or the default access token profile
* RFC 9068 token profile, or the access token profile that follows the [IETF JWT Profile for OAuth 2.0 Access Tokens (RFC 9068)](https://datatracker.ietf.org/doc/html/rfc9068)

<table>
  <thead>
    <tr>
      <th><strong>Token Profile</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Token Dialect</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Auth0 token profile</td>
      <td>The default token profile. Issues access tokens formatted as a <a href="/docs/secure/tokens/json-web-tokens">JSON Web Token (JWT)</a>.</td>
      <td>The Auth0 token profile is associated with two token dialects:<ul><li><code>access\_token</code></li><li><code>access\_token\_authz</code>, or the <code>access\_token</code> profile with the <code>permissions</code> claim included</li></ul></td>
    </tr>

    <tr>
      <td>RFC 9068 token profile</td>
      <td>Issues access tokens formatted as a JSON Web Token (JWT) following the  <a href="https://datatracker.ietf.org/doc/html/rfc9068">IETF standard</a> for encoding OAuth 2.0 Access Tokens in JWT format.</td>
      <td>The RFC 9068 token profile is associated with two token dialects:<ul><li><code>rfc9068\_profile</code></li><li><code>rfc9068\_profile\_authz</code>, or the <code>rfc9068\_profile</code> profile with the <code>permissions</code> claim included</li></ul></td>
    </tr>
  </tbody>
</table>

While both access token profiles issue <Tooltip href="/docs/glossary?term=JWTs">JWTs</Tooltip>, the JWTs have [different token formats](#token-profile-differences). Both access token profiles can enable [Role-Based Access Control (RBAC)](/docs/get-started/apis/enable-role-based-access-control-for-apis) and add the permissions claim to the access token.

To configure the access token profile for an API, read [Configure Access Token Profile](/docs/get-started/apis/configure-access-token-profile).

### Auth0 profile sample token

```json lines theme={null}
{
  "iss": "https://my-domain.auth0.com/",
  "sub": "auth0|123456",
  "aud": [
    "https://example.com/health-api",
    "https://my-domain.auth0.com/userinfo"
  ],
  "azp": "my_client_id",
  "exp": 1311281970,
  "iat": 1311280970,
  "scope": "openid profile read:patients read:admin",
  "my_custom_claim": "my_custom_value"
}
```

### RFC 9068 profile sample token

```json lines theme={null}
{
  "iss": "https://my-domain.auth0.com/",
  "sub": "auth0|123456",
  "aud": [
    "https://example.com/health-api",
    "https://my-domain.auth0.com/userinfo"
  ],
  "client_id": "my_client_id",
  "exp": 1311281970,
  "iat": 1311280970,
  "jti":"73WakrfVbNJBaAmhQtEeDv",
  "scope": "openid profile read:patients read:admin",
  "my_custom_claim": "my_custom_value"
}
```

## Token profile differences

The Auth0 profile and RFC 9068 profile issue JWTs that have different token formats. The main differences are:

* The RFC 9068 profile incorporates the `jti` claim, providing a unique identifier for the JWT.
* The Auth0 profile uses the `azp` claim to represent the <Tooltip href="/docs/glossary?term=client+ID">client ID</Tooltip> whereas the RFC 9068 profile uses the `client_id` claim.
* The RFC 9068 profile does not use the `gty` claim, which is an Auth0-specific claim that represents the authentication flow.

### Header

<table>
  <thead>
    <tr>
      <th><strong>Data</strong></th>
      <th><strong>RFC 9068 Profile</strong></th>
      <th><strong>Auth0 Profile</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>type</code></td>
      <td><code>at+jwt</code></td>
      <td><code>JWT</code></td>
    </tr>

    <tr>
      <td><code>alg</code></td>
      <td>Signing algorithm, for example, <code>RS256</code></td>
      <td>Signing algorithm, for example, <code>RS256</code></td>
    </tr>
  </tbody>
</table>

### Claims

| Claim                   | Description                                                                                                                                                                                                                                                                                                                              | Present in RFC 9068 Profile | Present in Auth0 Profile | Sample Claim                                                                                                                                              |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `iss`                   | Issuer identifier for the Auth0 tenant issuing the access token.                                                                                                                                                                                                                                                                         | Yes                         | Yes                      | Tenant domain: `https://tenant.auth0.com/`                                                                                                                |
| `sub`                   | The subject claim indicates which user or application the access token was issued for:<br />- For grants where an end user is involved (e.g., Authorization Code Flow), the `sub` claim is the `user_id`.<br />- For Machine-to-Machine apps using Client Credentials (no end user), the `sub` claim is a unique identifier for the app. | Yes                         | Yes                      | - User ID: `auth0\|6553da60a54af58e29493993`<br />- Client ID with suffix: `awZfdIir8YFdGZWkvCejDoUb7SjTDicx@clients`                                     |
| `aud`                   | The audience claim defines the intended recipient of the access token.                                                                                                                                                                                                                                                                   | Yes                         | Yes                      | `"https://test-server/api"` or `[ "https://test-server/api", "https://test.local.dev.auth0.com/userinfo" ]`                                               |
| `client_id`             | Client ID of the application that requests the access token.                                                                                                                                                                                                                                                                             | Yes                         | No                       | Client ID: `K1AUPhZq8mRi0Q0pjhkfu1D7y6KjDQja`                                                                                                             |
| `azp`                   | Client ID of the application that requests the access token.                                                                                                                                                                                                                                                                             | No                          | Yes                      | Client ID: `K1AUPhZq8mRi0Q0pjhkfu1D7y6KjDQja`                                                                                                             |
| `exp`                   | The expiration time on or after which the access token must not be accepted.                                                                                                                                                                                                                                                             | Yes                         | Yes                      | Epoch timestamp: `1516238022`                                                                                                                             |
| `iat`                   | Timestamp at which the access token was issued.                                                                                                                                                                                                                                                                                          | Yes                         | Yes                      | Epoch timestamp: `1516239022`                                                                                                                             |
| `scope`                 | Scope of the issued access token. See [Scopes](/docs/get-started/apis/scopes).                                                                                                                                                                                                                                                           | Yes                         | Yes                      | `"openid profile offline_access"`                                                                                                                         |
| `jti`                   | Unique identifier for the access token.                                                                                                                                                                                                                                                                                                  | Yes                         | No                       | Unique string identifier: `aBv9njtYfwL4xfPZyEwz9m`                                                                                                        |
| `gty`                   | [Grant type](/docs/get-started/applications/application-grant-types) used to request the access token. Only present for `password` and `refresh_token`.                                                                                                                                                                                  | No                          | Case-specific            | Grant type: `password`                                                                                                                                    |
| `permissions`           | Permissions available depending on roles. Included when **Enable RBAC** and **Add permissions in the Access Token** are enabled. See [RBAC for APIs](/docs/get-started/apis/enable-role-based-access-control-for-apis).                                                                                                                  | Case-specific               | Case-specific            | `[ "create:bar", "create:foo", "read:bar", "read:foo" ]`                                                                                                  |
| `org_id`                | Organization ID. Added when user authenticated via an Organization. See [Tokens and Orgs](/docs/manage-users/organizations/using-tokens).                                                                                                                                                                                                | Case-specific               | Case-specific            | Organization ID: `org_9ybsU1dN2dKfDkBi`                                                                                                                   |
| `org_name`              | Organization Name. Added when user authenticated via an Organization and **Organization Names in Authentication API** is enabled. See [Use Org Names](/docs/manage-users/organizations/configure-organizations/use-org-name-authentication-api).                                                                                         | Case-specific               | Case-specific            | Organization Name: `my_organization`                                                                                                                      |
| `authorization_details` | Authorization details used in Rich Authorization Requests (RAR). See [RAR](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/authorization-code-flow-with-rar).                                                                                                                                            | Case-specific               | Case-specific            | `{ "type": "money_transfer", "instructedAmount": {"amount": 2500, "currency": "USD"}, "destinationAccount": "xxxx9876", "beneficiary": "Hanna Herwitz" }` |
| `cnf`                   | Confirmation claim for [mTLS Token Binding](/docs/get-started/applications/configure-sender-constraining/configure-resource-server-for-sender-constraining).                                                                                                                                                                             | Case-specific               | Case-specific            | `{"x5t#S256":"A4DtL2JmUMhAsvJj5tKyn64SqzmuXbMrJa0n761y5v0"}`                                                                                              |
| Custom claims           | Custom claims can be added via Actions. See [Create Custom Claims](/docs/secure/tokens/json-web-tokens/create-custom-claims).                                                                                                                                                                                                            | Case-specific               | Case-specific            | `"favorite_color": "blue"`                                                                                                                                |


# Get Access Tokens
Source: https://auth0.com/docs/secure/tokens/access-tokens/get-access-tokens

Learn how to request Access Tokens using the Authorize endpoint when authenticating users and include the target audience and scope of access requested by the app and granted by the user.

To access your API, you must request an [access token](/docs/secure/tokens/access-tokens) when authenticating a user.

<Callout icon="file-lines">
  These Auth0 tools help you modify your application to authenticate users:

  * [Quickstarts](/docs/quickstarts) are the easiest way to implement authentication. They show you how to use [Universal Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login) and Auth0's language- and framework-specific SDKs.
  * The [Auth0 Authentication API](https://auth0.com/docs/api/authentication) is a reference for those who prefer to write code independently. First, identify [which flow to use](/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use). Then follow the instructions to implement that flow.
</Callout>

To request an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, make a POST call to the [token URL](https://auth0.com/docs/api/authentication#client-credentials-flow).

#### Example POST to token URL

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=client_credentials \
    --data client_id={yourClientId} \
    --data client_secret={yourClientSecret} \
    --data audience=YOUR_API_IDENTIFIER
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}&audience=YOUR_API_IDENTIFIER", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}&audience=YOUR_API_IDENTIFIER")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}&audience=YOUR_API_IDENTIFIER")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      audience: 'YOUR_API_IDENTIFIER'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=client_credentials" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_secret={yourClientSecret}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&audience=YOUR_API_IDENTIFIER" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}&audience=YOUR_API_IDENTIFIER",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}&audience=YOUR_API_IDENTIFIER"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}&audience=YOUR_API_IDENTIFIER"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/x-www-form-urlencoded"]

  let postData = NSMutableData(data: "grant_type=client_credentials".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&client_secret={yourClientSecret}".data(using: String.Encoding.utf8)!)
  postData.append("&audience=YOUR_API_IDENTIFIER".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

##### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td>Set this to "client\_credentials".</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Your application's Client ID. You can find this value on the <a href="https://manage.auth0.com/#/applications">application's settings tab</a>.</td>
    </tr>

    <tr>
      <td><code>client\_secret</code></td>
      <td>Your application's Client Secret. You can find this value on the <a href="https://manage.auth0.com/#/applications">application's settings tab</a>.  To learn more about available application authentication methods, read <a href="/docs/secure/application-credentials">Application Credentials</a>.</td>
    </tr>

    <tr>
      <td><code>audience</code></td>
      <td>The audience for the token, which is your API. You can find this in the <strong>Identifier</strong> field on your <a href="https://manage.auth0.com/#/apis">API's settings tab</a>.</td>
    </tr>

    <tr>
      <td><code>organization</code></td>
      <td>Optional. The organization name or identifier you want the request to be associated with. To learn more, read <a href="/docs/manage-users/organizations/organizations-for-m2m-applications">Machine-to-Machine Access for Organizations</a>.</td>
    </tr>
  </tbody>
</table>

#### Response

You receive an `HTTP 200` response with a payload containing `access_token`, `token_type`, and `expires_in` values:

```json lines theme={null}
{
  "access_token":"eyJz93a...k4laUWw",
  "token_type":"Bearer",
  "expires_in":86400
}
```

<Warning>
  Validate your tokens before saving them. To learn how, read [Validate ID Tokens](/docs/secure/tokens/id-tokens/validate-id-tokens) and [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens).
</Warning>

## Control access token audience

When a user authenticates, you request an access token and include the target <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> and scope of access in your request. The application uses the `/authorize` endpoint to request access. This access is both requested by the application and granted by the user during authentication

You can configure your tenant to always include a default audience.

<table>
  <thead>
    <tr>
      <th>Token Use</th>
      <th>Format</th>
      <th>Requested Audience</th>
      <th>Requested Scope</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>/userinfo endpoint</td>
      <td>Opaque</td>
      <td>tenant name (<code>\{yourDomain}</code>), no value for <code>audience</code> parameter, no <code>audience</code> parameter passed</td>
      <td><code>openid</code></td>
    </tr>

    <tr>
      <td>Auth0 Management API</td>
      <td>JWT</td>
      <td>Management API v2 identifier (`https://{tenant}.auth0.com/api/v2/`)</td>

      <td />
    </tr>

    <tr>
      <td>Your own custom API</td>
      <td>JWT</td>
      <td>The API Identifier for your custom API registered in the Auth0 Dashboard</td>

      <td />
    </tr>
  </tbody>
</table>

In only one specific instance, access tokens can have multiple target audiences. This requires that your custom API's <Tooltip href="/docs/glossary?term=signing+algorithm">signing algorithm</Tooltip> is set to **RS256**. To learn more, read [Token Best Practices](/docs/secure/tokens/token-best-practices).

### Multiple audiences

If you specify an audience of your custom API identifier and a scope of `openid`, then the resulting access token's `aud` claim will be an array rather than a string, and the access token will be valid for both your custom API and for the `/userinfo` endpoint. Your access tokens can only have two or more audiences if you use a single custom API as well as Auth0's `/userinfo` endpoint.

### Custom domains and the Auth0 Management API

Auth0 issues tokens with an issuer (`iss)` claim of whichever domain you used when requesting the token. [Custom domain](/docs/customize/custom-domains) users can use either their <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip> or their Auth0 domain.

For example, suppose you have a custom domain, `https://login.northwind.com`. If you request an access token from `https://login.northwind.com/authorize`, your token's `iss` claim will be `https://login.northwind.com/`. However, if you request an access token from `https://northwind.auth0.com/authorize`, your token's `iss` claim will be `https://northwind.auth0.com/`.

If you request an access token from your custom domain with the target audience of the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>, then you **must** call the Auth0 Management API from your custom domain. Otherwise your access token is considered invalid.

## Renew access tokens

By default, an access token for a custom API is valid for 86400 seconds (24 hours). You can [shorten the time period before the token expires](/docs/secure/tokens/access-tokens/update-access-token-lifetime).

After an access token has expired, you can renew your access token. To do so either re-authenticate the user using Auth0 or use a [refresh token](/docs/secure/tokens/refresh-tokens).

## Learn more

* [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens)
* [Use Access Tokens](/docs/secure/tokens/access-tokens/use-access-tokens)
* [JSON Web Tokens](/docs/secure/tokens/json-web-tokens)
* [Refresh Tokens](/docs/secure/tokens/refresh-tokens)
* [Identity Provider Access Tokens](/docs/secure/tokens/access-tokens/identity-provider-access-tokens)
* [Management API Access Tokens](/docs/secure/tokens/access-tokens/management-api-access-tokens)


# Identity Provider Access Tokens
Source: https://auth0.com/docs/secure/tokens/access-tokens/identity-provider-access-tokens

Understand third-party access tokens issued by identity providers after user authentication and how to use them to call the third-party APIs.

<Tooltip href="/docs/glossary?term=Identity+providers">Identity providers</Tooltip> issue third-party <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> after users authenticate with that provider. You can use these access tokens to call the API of the third-party provider that issued them. For example, you can use an access token issued after a user authenticates with Facebook to call the Facebook Graph API.

For individual users, the identity provider tokens are available in the `identities` array on the `user` object under the element for the particular connection. To securely access tokens for a specific user, you need an [access token for the Management API](/docs/secure/tokens/access-tokens/management-api-access-tokens) that includes the `read:user_idp_tokens` scope. Then, you can make an HTTP GET call to the [Get a User endpoint](https://auth0.com/docs/api/management/v2/#!/Users/get_users_by_id) to retrieve the tokens.

For admin users of Enterprise connections set up using an <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> consent flow, the identity provider tokens are available in the `connection` object. To securely access tokens for a connection, you need an [access token for the Management API](/docs/secure/tokens/access-tokens/management-api-access-tokens) that includes the `read:connections` scope. Then, you can make an HTTP GET call to the [Get a Connection endpoint](https://auth0.com/docs/api/management/v2/connections/get-connections-by-id) to retrieve the tokens.

<Callout icon="file-lines">
  The contents of third-party access tokens will vary depending on the issuing identity provider. Because tokens are created and managed by a third-party (such as Facebook, GitHub, etc.), the validity period for third-party tokens will vary by the issuer. If you believe these tokens have been compromised, you must revoke or reset them with the third-party that issued them.
</Callout>

## Renew third-party tokens

There is no standard way to renew identity provider access tokens through Auth0. The mechanism for renewing identity provider access tokens varies for each provider. For certain identity providers, Auth0 can store a [refresh token](/docs/secure/tokens/refresh-tokens), which you can use to obtain a new access token for the identity provider. Here is a list of some of the identity providers:

* BitBucket
* Google OAuth 2.0 (pass the parameter `access_type=offline`, as well the `connection_scope` parameter with required scopes, when calling the Auth0 `/authorize` endpoint)
* Any other OAuth 2.0 identity provider
* SharePoint
* Azure AD

You can retrieve <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip> in the same manner you retrieve access tokens. Review the guidelines above for more information.

## Validate third-party tokens

In general, if you have received an access token from an identity provider, you don't need to validate it. You can pass it to the issuer, and the issuer takes care of the rest.

## Learn more

* [Management API Access Tokens](/docs/secure/tokens/access-tokens/management-api-access-tokens)


# JSON Web Encryption
Source: https://auth0.com/docs/secure/tokens/access-tokens/json-web-encryption

Learn how to encrypt access tokens using JSON Web Encryption.

JSON Web Encryption (JWE) is an [IETF standard](https://datatracker.ietf.org/doc/html/rfc7516) for representing encrypted content using JSON. In Auth0, you can configure APIs to encrypt the details inside an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> using the JWE format.

When JWE is used, Auth0 generates a <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> access token containing a set of claims that are signed using JSON Web Signature (JWS). This JWT access token is then encrypted using JWE and serialized using the JWE Compact format. This allows solutions to maintain the confidentiality of data within the access tokens' claims while also ensuring integrity protection using a signature.

#### Generate and validate an access token

[Configure JWE for each API](/docs/get-started/apis/configure-json-web-encryption). Assuming you have configured the `apiIdentifier` to use JWE, the code sample requests an encrypted access token via the client credentials grant for a machine-to-machine (M2M) application. JWE is available for all grant types supported by Auth0.

```bash lines theme={null}
curl -X POST --location "https://{domain}/oauth/token" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "client_id={clientId}&client_secret={clientSecret}&audience={apiIdentifier}&grant_type=client_credentials"
```

 A successful response contains an encrypted access token:

```json lines theme={null}
{
  "access_token": "eyJ…XAw",
  "expires_in": 86400,
  "token_type": "Bearer"
}
```

When the access token is used, the <Tooltip href="/docs/glossary?term=resource+server">resource server</Tooltip> must decrypt and validate the JWE token.
The JWE token header contains metadata that describes the cryptographic algorithm ([`alg`](https://datatracker.ietf.org/doc/html/rfc7516#section-4.1.1)), the content encryption algorithm ([`enc`](https://datatracker.ietf.org/doc/html/rfc7516#section-4.1.2)), and, if provided when [configuring the API](/docs/get-started/apis/configure-json-web-encryption), the key id (`kid`) that were used to encrypt the payload.

```json lines theme={null}
{
  …
  "alg": "A256GCM",
  "enc": "RSA-OAEP-256",
  "kid": "my-kid"
}
```

Using this information, the resource server should be able to decrypt the JWE token. The result is a regular signed JWT, which can be verified using the Auth0’s tenant keys.

To learn how to configure JWE for your API, read [Configure JSON Web Encryption](/docs/get-started/apis/configure-json-web-encryption).

## Learn more

* [Configure JSON Web Encryption (JWE)](/docs/get-started/apis/configure-json-web-encryption)


# Management API Access Tokens
Source: https://auth0.com/docs/secure/tokens/access-tokens/management-api-access-tokens

Learn how Auth0 Management API access tokens work and how to use them.

To call the [Auth0 Management API](https://auth0.com/docs/api/management/v2), you must provide an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> that contains the appropriate <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> and scopes.

## Audience

The audience value for the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> is `https://{yourDomain}/api/v2/`.

## Scopes

Each Management API endpoint requires a specific set of scopes. Refer to the [Management API Explorer](https://auth0.com/docs/api/management/v2/) for more information.

## Lifetime

The default token lifetime for the Management API is 86,400 seconds (24 hours).

You can [configure the token lifetime](/docs/secure/tokens/access-tokens/update-access-token-lifetime) for each API individually.

## Security

* **Access token**: Once issued, an access token cannot be revoked. Auth0 recommends that you restrict the lifetime of your access tokens to the shortest value possible allowed by your use case.
* **<Tooltip href="/docs/glossary?term=Refresh+token">Refresh token</Tooltip>**: You can [revoke a refresh token](/docs/secure/tokens/refresh-tokens/revoke-refresh-tokens) using the Dashboard, the Authentication API, or the Management API.
* **<Tooltip href="/docs/glossary?term=Client+secret">Client secret</Tooltip>**: You can [rotate an application's client secret](/docs/get-started/applications/rotate-client-secret) using the Dashboard or the Management API.

## Quota

Token quotas are determined by subscription tier. You can [review your current quota](https://support.auth0.com/reports/quota) in the Auth0 Support Center. If you have questions about pricing or quotas, please [contact our sales team](https://auth0.com/contact-us).

* Tokens issued for [internal Auth0 audiences](/docs/secure/tokens/access-tokens/get-access-tokens#control-access-token-audience) do not count toward your quota.
* Tokens issued for custom audiences count toward your quota and are subject to [Auth0 Management API Rate Limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/management-api-endpoint-rate-limits).

## Learn more

* [Get Management API Access Tokens for Testing](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-testing)
* [Get Management API Access Tokens for Production](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production)
* [Get Management API Access Tokens for Single-Page Applications](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-tokens-for-single-page-applications)
* [Changes in Auth0 Management APIv2 Tokens](/docs/secure/tokens/access-tokens/management-api-access-tokens/changes-in-auth0-management-apiv2-tokens)
* [Migrate to Management API Endpoints with Access Tokens](/docs/troubleshoot/product-lifecycle/past-migrations/migrate-to-calling-api-with-access-tokens)


# Update Access Token Lifetime
Source: https://auth0.com/docs/secure/tokens/access-tokens/update-access-token-lifetime

Describes how to update the access token lifetime for an API using the Auth0 Dashboard.

You can change the <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> lifetime using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

## Configure access token lifetime

1. Go to [Dashboard > Applications > APIs](https://manage.auth0.com/#/apis) and select the name of the API to view.

   <Frame>
     <img alt="Dashboard Applications APIs List" />
   </Frame>
2. Locate the **Maximum Access Token Lifetime** field under **Access Token Expiration**.

   <Frame>
     <img alt="Dashboard - API - Token Settings - Expiration" />
   </Frame>
3. Enter the desired lifetime (in seconds) for access tokens issued for this API.

   * Default value is `86,400` seconds (24 hours).
   * Maximum value is `2,592,000 seconds` (30 days).
4. Select **Save Changes**.

## Token Expiration For Browser Flows

The **Implicit / Hybrid Flow Access Token Lifetime** field refers to access tokens issued for the API through implicit and hybrid flows and does not cover all flows initiated from browsers.

For example, the PKCE flow (used in `auth0-js-spa` SDK) can be initiated from the browser, but it references the **Token Expiration** value, not the **Implicit / Hybrid Flow Access Token Lifetime** value.

## Restricted lifetime for MFA access tokens

The lifetime of access tokens with the `{yourAuth0Domain}/mfa` <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> are restricted to `600` seconds (10 minutes) for security reasons and cannot be modified.

## Learn more

* [Update ID Token Lifetime](/docs/secure/tokens/id-tokens/update-id-token-lifetime)


# Use Access Tokens
Source: https://auth0.com/docs/secure/tokens/access-tokens/use-access-tokens

Describes how to use Access Tokens to call APIs.

<Tooltip href="/docs/glossary?term=Access+tokens">Access tokens</Tooltip> are used in token-based authentication to allow an application to access an API. For example, a Calendar application needs access to a Calendar API in the cloud so that it can read the user's scheduled events and create new events.

Once an application has received an access token, it will include that token as a credential when making API requests. To do so, it should transmit the access token to the API as a **Bearer** credential in an HTTP **Authorization** header.

For example:

```http lines theme={null}
GET /calendar/v1/events
    Host​: api.example.com
    
    Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2V4YW1wbGUuYXV0aDAuY29tLyIsImF1ZCI6Imh0dHBzOi8vYXBpLmV4YW1wbGUuY29tL2NhbGFuZGFyL3YxLyIsInN1YiI6InVzcl8xMjMiLCJpYXQiOjE0NTg3ODU3OTYsImV4cCI6MTQ1ODg3MjE5Nn0.CA7eaHjIHz5NxeIJoFK9krqaeZrPLwmMmgI_XiQiIkQ
```

In this example, the Access Token is a <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> that decodes to the following claims:

```json lines theme={null}
{
      "alg": "RS256",
      "typ": "JWT"
    }
    .
    {
      "iss": "https://example.auth0.com/",
      "aud": "https://api.example.com/calendar/v1/",
      "sub": "usr_123",
      "scope": "read write",
      "iat": 1458785796,
      "exp": 1458872196
    }
```

Before permitting access to the API using this token, the API must [validate the access token](/docs/secure/tokens/access-tokens/validate-access-tokens).

Once the Access Token has been successfully validated, the API can be sure that:

* The token was issued by Auth0.
* The token was issued to an application being used by a user with an identifier of `usr_123`.
* The user granted the application access to read from and write to their calendar.

The API can now process the request, allowing the application to read from and write to user `usr_123`'s calendar.

## Learn more

* [Get Access Tokens](/docs/secure/tokens/access-tokens/get-access-tokens)
* [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens)
* [Identity Provider Access Tokens](/docs/secure/tokens/access-tokens/identity-provider-access-tokens)
* [Management API Access Tokens](/docs/secure/tokens/access-tokens/management-api-access-tokens)
* [JSON Web Tokens](/docs/secure/tokens/json-web-tokens)
* [Token Best Practices](/docs/secure/tokens/token-best-practices)


# Validate Access Tokens
Source: https://auth0.com/docs/secure/tokens/access-tokens/validate-access-tokens

Describes how to validate an access token.

An <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> is meant for an API and should be validated only by the API for which it was intended.

<Callout icon="file-lines">
  Identity Provider (IdP) access tokens do not require validation. Pass the IdP access token to the issuing IdP to handle the validation. For more information, see [Identity Provider Access Tokens](/docs/secure/tokens/access-tokens/identity-provider-access-tokens) for details.
</Callout>

If any of these checks fail, the token is considered invalid, and the request must be rejected with `401 Unauthorized` result.

1. **Perform standard JWT validation.** Because the access token is a JWT, you need to perform the standard JWT validation steps. See [Validate JSON Web Tokens](/docs/secure/tokens/json-web-tokens/validate-json-web-tokens) for details.
2. **Verify token audience claims.** If you've performed the standard JWT validation, you have already decoded the JWT's payload and looked at its standard claims. The token audience claim (`aud`, array of strings) depends on the initial token request. The `aud` field could contain both an audience corresponding to your custom API and an audience corresponding to the `/userinfo` endpoint. At least one of the audience values for the token must match the unique identifier of the target API as defined in your [API's Settings](https://manage.auth0.com/#/apis) in the **Identifier** field. See [Get Access Tokens](/docs/secure/tokens/access-tokens/get-access-tokens) for details.
3. **Verify permissions (scopes).** Verify that the application has been granted the permissions required to access your API. To do so, you will need to check the `scope` claim (`scope`, space-separated list of strings) in the decoded JWT's payload. It should match the permissions required for the endpoint being accessed. For example, if your custom API provides three endpoints to read, create, or delete a user record, when you registered your API with Auth0, you created three corresponding permissions:

   1. `create:users` provides access to the `/create` endpoint
   2. `read:users` provides access to the `/read` endpoint
   3. `delete:users` provides access to the `/delete` endpoint

   In this case, if an application requests access the `/create` endpoint, but the access token's `scope` claim does not include the value `create:users`, then the API should reject the request.

## Learn more

* [Get Access Tokens](/docs/secure/tokens/access-tokens/get-access-tokens)
* [Use Access Tokens](/docs/secure/tokens/access-tokens/use-access-tokens)
* [Management API Access Tokens](/docs/secure/tokens/access-tokens/management-api-access-tokens)
* [Get Management API Access Tokens for Testing](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-testing)
* [Get Management API Access Tokens for Production](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production)
* [Token Best Practices](/docs/secure/tokens/token-best-practices)


# Delegation Tokens
Source: https://auth0.com/docs/secure/tokens/delegation-tokens

Describes how Auth0 delegation tokens work in Auth0.

<Warning>
  By default, delegation is disabled for tenants without an add-on in use as of 8 June 2017. Legacy tenants who currently use an add-on that requires delegation may continue to use this feature. If delegation functionality is changed or removed from service at some point, customers who currently use it will be notified beforehand and given ample time to migrate.
</Warning>

A delegation token should be obtained and used when an application needs to call the API of an Application Add-on, such as Firebase or SAP, registered and configured in Auth0, in the same tenant as the calling program.

Given an existing token, this endpoint will generate a new token signed with the `target` application's secret. This is used to flow the identity of the user from the application to an API.

The type of the delegation token varies depending on the provider. For example, if it is issued for Azure Blob Storage, it will be an SAS (Shared Access Signature). If it is for the Firebase Add-on, it will be a <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip>.

The <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> for an authenticated user can be used with the `/delegation` endpoint to request a delegation token for a particular target. The target can be an application Add-on configured in Auth0. The Add-ons for which this can be done are those that are not <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> or <Tooltip href="/docs/glossary?term=WS-Fed">WS-Fed</Tooltip> Add-ons. The Add-on must be configured in Auth0 with secrets obtained from the Add-on service, such as Firebase. Instructions for setting up the secrets are available from the Add-on configuration page for each Add-on. The secrets are used to sign the delegation token so that the Add-on API can validate and trust the token.

The delegation endpoint allows you to set several parameters which govern the contents of the delegation token including the `target`, the `scope`, the API to be called (`api_type`), and an additional free-form area for additional parameters.

## Auth0.js example

For an example on how to get a new token for an Add-on that you have activated, using **Auth0.js**, refer to Delegation Token Request. Note that this example is for **version 7** of the **Auth0.js** library; delegation is **not supported** in version 8 of **Auth0.js**.

## Validity period and termination

The validity period and the ability to revoke a delegation token, varies by individual Add-on. The documentation available from the provider of any Add-on API should be consulted for further information.

## Use Delegation tokens with public applications

There is an important caveat to note when using the delegation endpoint with Public Applications.

If you call the `/token` endpoint from a Public Application, the ID Token will be forcibly signed using `RS256`, even if the JsonWebToken Signature Algorithm in the Application settings is configured as `HS256`.

If you then subsequently call the delegation endpoint with that ID Token, it will fail if the Application's JsonWebToken Signature Algorithm was configured as `HS256`. This is because delegation performs validation according to the Application's settings, but the ID Token was issued with a different algorithm because of the forced algorithm change.

It is therefore important that if you intend to use delegation with a Public Application, that you configure the JsonWebToken Signature Algorithm of your application as `RS256`.


# Get ID Tokens
Source: https://auth0.com/docs/secure/tokens/id-tokens/get-id-tokens

Describes how to request an ID token when authenticating users that includes claims about the user by including OIDC scopes.

To get an <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip>, you need to request them when authenticating users. Auth0 makes it easy for your app to authenticate users using:

* [Quickstarts](/docs/quickstarts): The easiest way to implement authentication, which can show you how to use [Universal Login](/docs/authenticate/login/auth0-universal-login), the Lock widget, and Auth0's language and framework-specific SDKs. Our [Lock documentation](/docs/libraries/lock) and [Auth0.js documentation](/docs/libraries/auth0js) provide specifics about retrieving an ID token after authentication.
* [Authentication API](https://auth0.com/docs/api/authentication): If you prefer to roll your own, you can call our API directly. First, you need to know [which flow to use](/docs/get-started/authentication-and-authorization-flow/which-oauth-2-0-flow-should-i-use) before following the appropriate flow tutorial.

## Control ID token contents

You control which claims about the authenticated user are included in the ID token consumed by your application by including specific [OpenID Connect Scopes](/docs/get-started/apis/scopes/openid-connect-scopes) in the `scope` parameter when you request tokens while authenticating users.

You can also create [custom claims](/docs/secure/tokens/json-web-tokens/json-web-token-claims), which are claims that you define, control, and add to a token using a rule. As with other <Tooltip href="/docs/glossary?term=JWTs">JWTs</Tooltip>, you should [validate an ID token](/docs/secure/tokens/id-tokens/validate-id-tokens) before assuming that its contents can be trusted.

## Renew ID tokens

By default, an ID token is valid for 36000 seconds (10 hours). If there are security concerns, you can [shorten the time period before the token expires](/docs/secure/tokens/id-tokens/update-id-token-lifetime), but remember that one of the purposes of this token is to improve performance by caching user information.

After an ID token has expired, you may want to renew your ID token. To renew the ID token, you can either re-authenticate the user using Auth0, or use a [refresh token](/docs/secure/tokens/refresh-tokens).

## Learn more

* [Validate ID Tokens](/docs/secure/tokens/id-tokens/validate-id-tokens)
* [JSON Web Tokens](/docs/secure/tokens/json-web-tokens)
* [JSON Web Token Claims](/docs/secure/tokens/json-web-tokens/json-web-token-claims)
* [Token Best Practices](/docs/secure/tokens/token-best-practices)


# ID Token Structure
Source: https://auth0.com/docs/secure/tokens/id-tokens/id-token-structure

Describes how ID tokens conform to the JWT standard and contain JWT claims asserted about the token itself, standard OIDC claims about the authenticated user, and custom claims that you define, control, and add to a token using a rule.

<Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip> follow the [JSON Web Token (JWT)](/docs/secure/tokens/json-web-tokens) standard, which means that their basic structure conforms to the typical [JWT Structure](/docs/secure/tokens/json-web-tokens/json-web-token-structure), and they contain standard [JWT Claims](/docs/secure/tokens/json-web-tokens/json-web-token-claims) asserted about the token itself.

Beyond what is required for <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip>, ID tokens also contain claims asserted about the authenticated user, which are pre-defined by the <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) protocol, and are thus known as standard OIDC claims. Some standard OIDC claims include:

* `name`
* `nickname`
* `picture`
* `email`
* `email_verified`

For a full list of standard OIDC claims, see [OIDC specification: Standard Claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). You can also create [custom claims](/docs/secure/tokens/json-web-tokens/json-web-token-claims), which are claims that you define, control, and add to a token using Auth0 Actions.

You control which OIDC claims are included in the ID token consumed by your application by including specific [OpenID Connect Scopes](/docs/get-started/apis/scopes/openid-connect-scopes) in a parameter when you request tokens while authenticating users. To learn how to request an ID token, see [Get ID Tokens](/docs/secure/tokens/id-tokens/get-id-tokens).

## Sample ID Token

This example shows the contents of an ID token. Notice that the <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> value (located in the `aud` claim) is set to the application's identifier, which means that only this specific application should consume the token. To learn more about the claims in this example, read [JSON Web Token Claims](/docs/secure/tokens/json-web-tokens/json-web-token-claims).

```json lines theme={null}
{
  "iss": "http://my-domain.auth0.com",
  "sub": "auth0|123456",
  "aud": "my_client_id",
  "exp": 1311281970,
  "iat": 1311280970,
  "name": "Jane Doe",
  "given_name": "Jane",
  "family_name": "Doe",
  "gender": "female",
  "birthdate": "0000-10-31",
  "email": "janedoe@example.com",
  "picture": "http://example.com/janedoe/me.jpg"
}
```

## Learn more

* [Get ID Tokens](/docs/secure/tokens/id-tokens/get-id-tokens)
* [Validate ID Tokens](/docs/secure/tokens/id-tokens/validate-id-tokens)
* [Update ID Token Lifetime](/docs/secure/tokens/id-tokens/update-id-token-lifetime)


# Update ID Token Lifetime
Source: https://auth0.com/docs/secure/tokens/id-tokens/update-id-token-lifetime

Describes how to update the ID token lifetime for an application using the Auth0 Dashboard.

You can change the <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> lifetime using the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. By default, an ID token is valid for 36000 seconds (10 hours). If there are security concerns, you can shorten the time period before the token expires, keeping in mind that one of the purposes of the token is to improve user experience by caching user information.

1. Go to [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications) and click the name of the application to view.
2. Scroll to **ID Token** and locate the **ID Token Expiration** field. Enter the appropriate ID token lifetime (in seconds) for the application.
3. Click **Save Changes**.

## Learn more

* [Token Best Practices](/docs/secure/tokens/token-best-practices)
* [Application Settings](/docs/get-started/applications/application-settings)
* [Configure Refresh Token Expiration](/docs/secure/tokens/refresh-tokens/configure-refresh-token-expiration)


# Validate ID Tokens
Source: https://auth0.com/docs/secure/tokens/id-tokens/validate-id-tokens

Describes how to validate an ID token.

An [ID token](/docs/secure/tokens/id-tokens), which contains user profile attributes, is consumed by an app and is typically used for user interface display. Auth0 issues all <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip> in [JSON web token (JWT)](/docs/secure/tokens/json-web-tokens) format.

If any of these checks fail, the token is considered invalid, and the request must be rejected.

1. [Validate the JWT](/docs/secure/tokens/json-web-tokens/validate-json-web-tokens).
2. Check additional standard claims. If you've performed the standard JWT validation, you have already decoded the [JWT's Payload](/docs/secure/tokens/json-web-tokens/json-web-token-structure) and looked at its standard claims. Additional claims to verify for ID tokens include:

   * **Token audience** (`aud`, string): The audience value for the token must match the client ID of the application as defined in your [Application's Settings](https://manage.auth0.com/#/applications) in the **Client ID** field.
   * **Nonce** (`nonce`, string): Passing a nonce in the token request is recommended (required for the Implicit Flow) to help prevent replay attacks. The nonce value in the token must exactly match the original nonce sent in the request. See [Mitigate Replay Attacks](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post/mitigate-replay-attacks-when-using-the-implicit-flow) for details.

## Learn more

* [Get ID Tokens](/docs/secure/tokens/id-tokens/get-id-tokens)
* [ID Token Structure](/docs/secure/tokens/id-tokens/id-token-structure)
* [Update ID Token Lifetime](/docs/secure/tokens/id-tokens/update-id-token-lifetime)
* [Mitigate Replay Attacks When Using the Implicit Flow](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post/mitigate-replay-attacks-when-using-the-implicit-flow)


# Manage Refresh Tokens with Auth0 Management API
Source: https://auth0.com/docs/secure/tokens/manage-refresh-tokens-with-auth0-management-api

Learn how to manage refresh tokens with the Auth0 Management API.

Auth0 issues a <Tooltip href="/docs/glossary?term=refresh+token">refresh token</Tooltip> as a credential artifact that your application can use to get a new <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> without user interaction. This allows Auth0 to shorten the access token lifetime for security purposes without involving the user when the access token expires.

<Callout icon="file-lines">
  The Auth0 Management API refresh token endpoints are currently are available to customers on Enterprise plans. To learn more, read [Pricing](https://auth0.com/pricing).
</Callout>

## Management API endpoints

The Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> provides endpoints to manage refresh tokens individually or as a collection.

These endpoints complement [alternative refresh-token revocation](/docs/secure/tokens/refresh-tokens/revoke-refresh-tokens), superseding the `device-credentials` resource endpoints with extended properties and bulk revocation operations.

### Refresh Token resource

You can view or revoke a specific refresh token with the following endpoints:

<table>
  <thead>
    <tr>
      <th><strong>Name</strong></th>
      <th><strong>URL</strong></th>
      <th><strong>Required scope(s)</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>View a refresh token information by ID</td>
      <td><code>GET /api/v2/refresh-tokens/</code></td>
      <td><code>read:refresh\_tokens</code></td>
    </tr>

    <tr>
      <td>Revoke a refresh token by ID</td>
      <td><code>DELETE /api/v2/refresh-tokens/</code></td>
      <td><code>delete:refresh\_tokens</code></td>
    </tr>
  </tbody>
</table>

### User resource

You can list or revoke all refresh tokens for a given user with the following endpoints:

<table>
  <thead>
    <tr>
      <th><strong>Name</strong></th>
      <th><strong>URL</strong></th>
      <th><strong>Required scope(s)</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>List all refresh tokens for a user</td>
      <td><code>GET /api/v2/users//refresh-tokens</code></td>
      <td><code>read:refresh\_tokens</code></td>
    </tr>

    <tr>
      <td>Revoke all refresh tokens for a user</td>
      <td><code>DELETE /api/v2/users//refresh-tokens</code></td>
      <td><code>delete:refresh\_tokens</code></td>
    </tr>
  </tbody>
</table>

## Refresh token properties

The refresh <Tooltip href="/docs/glossary?term=token+endpoints">token endpoints</Tooltip> return relevant information about the token and its history.

<table>
  <thead>
    <tr>
      <th><strong>Field</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Refresh Token ID</td>
      <td>A unique and tenant-specific identifier of the refresh token in the API. It is not the token itself, which is a secret to exchange with the token endpoint in the authentication API.<br /><br />Refresh tokens can outlive a session. The refresh token keeps this information regardless of the session lifecycle.</td>
    </tr>

    <tr>
      <td>Session ID</td>
      <td>The session ID is a persistent identifier of the session in the Auth0 tenant. Note that the session ID corresponds to the <code>sid</code> claim already in ID Tokens and Logout Tokens and can be used to cross-reference these entities.<br /><br />The refresh token contains references to the session that was used to create the token. The session ID can be used to retrieve additional information with the Management API <a href="/docs/manage-users/sessions/manage-user-sessions-with-auth0-management-api">introspect a specific session by ID</a> endpoint.</td>
    </tr>

    <tr>
      <td>Relevant Time</td>
      <td>Refresh token creation, and expiry information.</td>
    </tr>

    <tr>
      <td>Client and Resource Servers Information</td>
      <td>Summary information about the applications and APIs bound to a refresh token.</td>
    </tr>
  </tbody>
</table>

## Limitations

* Refresh token revocation (`DELETE`) operations run asynchronously, and are eventually consistent.
* Refresh tokens issued on or after 21-09-2023 (22-02-2024 for tenants in the US-3 region) contain the session ID (`session_id`) property with the appropriate value. Refresh tokens issued before this date contain this property with a `null` value.

To learn more about refresh tokens limitations, read [Refresh Tokens limitations](/docs/secure/tokens/refresh-tokens).

## Learn more

* [Refresh Tokens](/docs/secure/tokens/refresh-tokens)
* [Revoke Refresh Tokens](/docs/secure/tokens/refresh-tokens/revoke-refresh-tokens)
* [Use Refresh Tokens](/docs/secure/tokens/refresh-tokens/use-refresh-tokens)


# Refresh Tokens
Source: https://auth0.com/docs/secure/tokens/refresh-tokens

Describes how refresh tokens work to allow the application to ask Auth0 to issue a new access token or ID token without having to re-authenticate the user.

Auth0 issues an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> or an <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> in response to an authentication request. You can use access tokens to make authenticated calls to a secured API, while the ID token contains user profile attributes represented in the form of claims. Both are <Tooltip href="/docs/glossary?term=JSON+web+tokens">JSON web tokens</Tooltip> (JWTs) and therefore have expiration dates indicated using the `exp` claim, as well as security measures, like signatures. Typically, a user needs a new access token when gaining access to a resource for the first time, or after the previous access token granted to them expires.

An <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> <Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip> is a credential artifact that OAuth can use to get a new access token without user interaction. This allows the <Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip> to shorten the access token lifetime for security purposes without involving the user when the access token expires. You can request new access tokens until the refresh token is on the DenyList.

It is important to keep the number of refresh tokens within a reasonable manageable limit to make sure that it’s easy to maintain those credentials safely and securely. Applications must store refresh tokens securely because they essentially allow a user to remain authenticated forever.

<Card title="Offline access">
  If you want to allow users to get refresh tokens while offline, you can select the **Allow Offline Access** switch in [API Settings](/docs/get-started/apis/api-settings).
</Card>

You can increase security by using [refresh token rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation) which issues a new refresh token and invalidates the predecessor token with each request made to Auth0 for a new access token. Rotating the refresh token reduces the risk of a compromised refresh token.

### Limitations

* Auth0 limits the amount of active refresh tokens to 200 tokens per user per application. This limit only applies to active tokens. If the limit is reached and a new refresh token is created, the system revokes and deletes the oldest token for that user and application. Revoked tokens and expired tokens do not count against the limit. To review our recommendations and best practices to avoid excess tokens, read [Token Best Practices](/docs/secure/tokens/token-best-practices).

* After a [refresh token exchange](/docs/secure/tokens/refresh-tokens/use-refresh-tokens), Auth0 does not update the `event.refresh_token.device.last*` properties for non-expiring tokens. To learn about enabling expiring refresh tokens, read [Configure Refresh Token Expiration](/docs/secure/tokens/refresh-tokens/configure-refresh-token-expiration).

### Enable OIDC Flag

The refresh token behavior is applicable to OIDC-conformant applications. You can configure an application to be OIDC-conformant in one of the following ways:

1. Enabling the **OIDC Conformant** flag for an app.
2. Passing an `audience` claim to the `/authorize` endpoint of the Authentication API.

## SDK support

### For web apps

Auth0 SDKs support refresh tokens including:

* Node.js
* ASP.NET Core
* PHP
* Java

For a complete listing, see [Quickstarts](/docs/quickstart/webapp).

### For single-page apps

Providing secure authentication in SPAs has a number of challenges based on your application’s use case. New browser privacy controls like Intelligent Tracking Prevention (ITP) adversely impact the user experience in SPAs by preventing access to third-party cookies.

Auth0 recommends using <Tooltip href="/docs/glossary?term=refresh+token+rotation">refresh token rotation</Tooltip> which provides a secure method for using refresh tokens in SPAs while providing end-users with seamless access to resources without the disruption in UX caused by browser privacy technology like ITP.

### For native/mobile apps

For native applications, refresh tokens improve the authentication experience significantly. The user has to authenticate only once, through the web authentication process. Subsequent re-authentication can take place without user interaction, using the refresh token.

For information on using refresh tokens with our mobile SDKs, see:

* [Mobile/Native Quickstarts](/docs/quickstart/native)
* [Lock Android: Refresh JWT Tokens](/docs/libraries/lock-android/lock-android-refresh-jwt)
* [Lock iOS: Save and Renew JWT Tokens](/docs/libraries/auth0-swift/auth0-swift-save-and-renew-tokens)

## Learn more

* [Get Refresh Tokens](/docs/secure/tokens/refresh-tokens/get-refresh-tokens)
* [Use Refresh Tokens](/docs/secure/tokens/refresh-tokens/use-refresh-tokens)
* [Revoke Refresh Tokens](/docs/secure/tokens/refresh-tokens/revoke-refresh-tokens)
* [Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation)
* [Configure Refresh Token Expiration](/docs/secure/tokens/refresh-tokens/configure-refresh-token-expiration)
* [Token Best Practices](/docs/secure/tokens/token-best-practices)


# Configure Refresh Token Expiration
Source: https://auth0.com/docs/secure/tokens/refresh-tokens/configure-refresh-token-expiration

Learn how to configure the refresh token expiration lifetimes.

<Tooltip href="/docs/glossary?term=Refresh+tokens">Refresh tokens</Tooltip> can be a target for abuse if leaked because they can be used to acquire new <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip>. To mitigate this risk, Auth0 recommends using Automatic Reuse Detection and <Tooltip href="/docs/glossary?term=Refresh+Token+Rotation">Refresh Token Rotation</Tooltip>. Refresh Token Rotation issues a refresh token that expires after a preset lifetime. After expiration, the user gets a new refresh token in the same family, or refresh tokens that share a family ID, or a new access token/refresh token pair. To learn more, read [Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation).

You can enable and configure two refresh token lifetime settings, maximum and idle refresh expiration, using either the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. You can use a combination of maximum and idle refresh expiration periods to create a balance between security and user experience that suits your business needs.

* **Maximum Lifetime**: Set a refresh token or refresh token family lifetime after which the user must re-authenticate before being issued a new access token. If you disable this setting, the maximum lifetime will be indefinite.
* **Idle Lifetime**: Set the idle lifetime of issued refresh tokens to expire if the user is not active in your application during a specified period.

## Use the Dashboard

1. Go to [Dashboard > Applications](https://manage.auth0.com/#/applications).
2. Select the application you want to configure.
3. Go to the **Settings** tab.
4. Under **Refresh Token Expiration**, enable **Set Idle Refresh Token Lifetime**. When enabled, a refresh token will expire based on the idle refresh token lifetime, after which the token can no longer be used. If rotation is enabled, an expiration lifetime must be set.

   <Frame>
     <img alt="Dashboard Applications Applications Settings Tab Refresh Token Expiration" />
   </Frame>
5. Enter **Idle Refresh Token Lifetime** in seconds. The refresh token expires after the specified interval and can no longer be used to get a new access token. When rotation is enabled, the idle refresh token lifetime also applies to the ability to get new tokens.

   <table>
     <thead>
       <tr>
         <th><strong>Lifetime</strong></th>
         <th><strong>Value</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>Default</td>
         <td>2,592,000 seconds (30 days)</td>
       </tr>

       <tr>
         <td>Minimum</td>
         <td>1 second</td>
       </tr>

       <tr>
         <td>Maximum</td>
         <td>31,557,600 seconds (1 year)</td>
       </tr>
     </tbody>
   </table>

   <Callout icon="file-lines">
     * The **Idle Refresh Token Lifetime** can not exceed the **Maximum Refresh Token Lifetime**.
     * The calculation for one year is equivalent to 365.25 days to account for leap years.
   </Callout>
6. Enable **Set Maximum Refresh Token Lifetime**. When enabled, a refresh token will expire based on a specified maximum refresh token lifetime, after which the token can no longer be used.
7. Enter **Maximum Refresh Token Lifetime** in seconds. If the refresh token is not exchanged within the specified interval, the refresh token expires and can no longer be used to get a new access token. The idle refresh token lifetime expiration period is renewed each time the refresh token is exchanged for a new access token within the interval.

   <table>
     <thead>
       <tr>
         <th><strong>Lifetime</strong></th>
         <th><strong>Value</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td>Minimum</td>
         <td>1 second</td>
       </tr>

       <tr>
         <td>Maximum</td>
         <td>31,557,600 seconds (1 year)</td>
       </tr>
     </tbody>
   </table>
8. Select **Save Changes**.

## Use the Management API

You can configure the maximum and idle lifetime settings in the payload for the Management API [/api/v2/clients/](https://auth0.com/docs/api/management/v2#!/Clients/patch_clients_by_id) endpoint. Here is an example that sets expiration lifetime for a non-rotating refresh token:

```json lines theme={null}
PATCH /api/v2/clients/{id}
{
  "refresh_token": {
      "rotation_type": "non-rotating",
      "expiration_type": "expiring",
      "token_lifetime": 2592000,
      "infinite_token_lifetime": false,
      "idle_token_lifetime": 604800,
      "infinite_idle_token_lifetime": false
  }
}
```

## Support and limitations

* The **maximum refresh token lifetime** is determined at issuance and remains fixed throughout its lifetime, even if the application's maximum refresh token lifetime is updated. However, you can actively override the maximum refresh token lifetime at issuance using [sessions with Actions](/docs/manage-users/sessions/manage-sessions-actions), including during successful refresh token exchanges.
* The **idle refresh token lifetime** reflects current application settings and updates with each successful refresh token exchange.
* If you configure the Maximum Refresh Token Lifetime for an application, any non-expiring refresh tokens issued by that application becomes expiring refresh tokens after a successful Refresh Token exchange.
* Once a non-expiring refresh token becomes a expiring refresh token, it cannot be reverted back to a non-expiring refresh token.
* You can opt-in to use refresh token expiration capabilities; no action is required by you. Existing refresh tokens are not affected.
* Refresh token expiration works with the following flows:

  * [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow)
  * [Authorization Code Flow with Proof Key for Code Exchange](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce)
  * [Device Authorization Flow](/docs/get-started/authentication-and-authorization-flow/device-authorization-flow)
  * [Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow)
* All Auth0 SDKs support refresh token expiration.
* The refresh token expiration feature complies with the [OAuth 2.0 Security BCP recommendations](https://www.ietf.org/archive/id/draft-ietf-oauth-security-topics-16.html#section-4.13.2).

<Callout icon="file-lines">
  The OAuth BCP states that refresh tokens issued for browser-based applications must have an expiration and either enforce sender-constraint or rotate tokens with each request. Therefore, SPAs will default into rotation and **will not support** non-expiring refresh tokens.
</Callout>

## Learn more

* [Get Refresh Tokens](/docs/secure/tokens/refresh-tokens/get-refresh-tokens)
* [Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation)
* [Configure Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/configure-refresh-token-rotation)
* [Revoke Refresh Tokens](/docs/secure/tokens/refresh-tokens/revoke-refresh-tokens)


# Configure Refresh Token Rotation
Source: https://auth0.com/docs/secure/tokens/refresh-tokens/configure-refresh-token-rotation

Describes how to configure refresh token rotation.

Configure <Tooltip href="/docs/glossary?term=refresh+token">refresh token</Tooltip> rotation for each application using the Dashboard or the [Auth0 SPA SDK](/docs/libraries/auth0-single-page-app-sdk). When <Tooltip href="/docs/glossary?term=refresh+token+rotation">refresh token rotation</Tooltip> is enabled, the transition for the user is seamless. The application uses the previous, unexpired non-rotating refresh token and swaps it for a rotating refresh token.

Migration scenarios accommodate automatic token revocation when migrating from a non-rotating refresh token to a rotating refresh token and vice-versa.

* **When refresh token rotation is enabled**:
  Exchanging a non-rotating refresh token issues a new rotation refresh token and deletes all the non-rotating tokens issued for the same `client_id`, <Tooltip href="/docs/glossary?term=resource+server">resource server</Tooltip>, user and tenant.
* **When refresh token rotation is disabled**:
  Exchanging a rotating refresh token issues a non-rotating refresh token and revokes the rotating refresh token family issued for the same `client_id`, resource server, user and tenant.

## Configure in the Dashboard

1. Go to [Dashboard > Applications](https://manage.auth0.com/#/applications).
2. Select the application you want to configure.
3. Go to the **Settings** tab.
4. Under **Refresh Token Rotation**, enable **Allow Refresh Token Rotation**.

   <Frame>
     <img alt="Dashboard Applications Applications Settings Tab Refresh Token Rotation" />
   </Frame>
5. Enter **Rotation Overlap Period** (in seconds) for the refresh token to account for leeway time between request and response before triggering automatic reuse detection.
   This overlap period helps to avoid concurrency issues when exchanging the rotating refresh token multiple times within a given timeframe. During the leeway window the breach detection features don't apply and a new rotating refresh token is issued. Only the previous token can be reused; if the second-to-last one is exchanged, breach detection will be triggered.
6. Select **Save Changes**.

<Callout icon="file-lines">
  Refresh Token Rotation is only supported for OIDC-conformant applications with the Refresh Token grant type enabled.
</Callout>

## Configure with the Auth0 SPA SDK

You can use the Auth0 SPA SDK to enable refresh token rotation. You must enable offline access and request the offline access scope in the client SDK.

1. Install the latest version of the `auth0-spa-js` SDK:
   `npm install @auth0/auth0-spa-js`

2. Enable the feature on the SDK by setting `useRefreshTokens: true` to start sending the `offline_access` scope.

   <AuthCodeBlock />

3. Configure the Refresh Token rotation settings. For example:

   ```http lines theme={null}
   PATCH /api/v2/clients/{client_id}
   {
     "refresh_token": {
       "rotation_type": "rotating",
       "expiration_type": "expiring",
       "token_lifetime": "2592000",
       "leeway": 3
     }
   }
   ```

   <table>
     <thead>
       <tr>
         <th><strong>Attribute</strong></th>
         <th><strong>Description</strong></th>
       </tr>
     </thead>

     <tbody>
       <tr>
         <td><code>rotation\_type</code></td>
         <td>Text string: "rotating" or "non-rotating"</td>
       </tr>

       <tr>
         <td><code>expiration\_type</code></td>
         <td>Text string: "expiring" or "non-expiring"</td>
       </tr>

       <tr>
         <td><code>token\_lifetime</code></td>
         <td>The default refresh token expiration period, when <strong>Refresh Token Rotation</strong> is enabled, is 30 days (2,592,000 seconds). You can configure up to 1 year (31,557,600 seconds). <strong>The lifetime does not extend when tokens are rotated.</strong></td>
       </tr>

       <tr>
         <td><code>leeway</code></td>
         <td>Allow the same refresh token to be used within the time period to account for potential network concurrency issues that would otherwise invalidate the token should the client attempt to retry using the same refresh token. By default leeway is disabled. Configurable in seconds.</td>
       </tr>
     </tbody>
   </table>

<Callout icon="file-lines">
  Refresh Token Rotation is only supported for OIDC-conformant applications with the Refresh Token grant type enabled.
</Callout>

## Automatic reuse detection

If a previously invalidated token is used, the entire set of refresh tokens issued since that invalidated token was issued will immediately be revoked along with the grant, requiring the user to re-authenticate.

## Learn more

* [Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation)
* [Use Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/use-refresh-token-rotation)
* [Disable Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/disable-refresh-token-rotation)


# Disable Refresh Token Rotation
Source: https://auth0.com/docs/secure/tokens/refresh-tokens/disable-refresh-token-rotation

Describes how to disable Refresh Token rotation.

You can disable <Tooltip href="/docs/glossary?term=refresh+token">refresh token</Tooltip> rotation for each application using Dashboard or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## Disable with the Dashboard

1. From the [Auth0 Dashboard](https://manage.auth0.com/#), navigate to **Applications > Applications** and select the application you wish to configure.
2. On the Settings tab, locate the Refresh Token Rotation section and disable the Allow Refresh Token Rotation toggle.
3. Select **Save Changes** at the bottom of the screen.

## Disable with the Management API

1. Disable refresh token rotation for each application using the Management API:

   <AuthCodeBlock />

2. Configure the non-rotating refresh token settings as follows:

   ```http lines theme={null}
   PATCH /api/v2/clients/{client_id}
   {
      "refresh_token": {
        "rotation_type": "non-rotating",
        "expiration_type": "non-expiring"
      }
   }
   ```

## Learn more

* [Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation)
* [Configure Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/configure-refresh-token-rotation)
* [Use Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/use-refresh-token-rotation)


# Get Refresh Tokens
Source: https://auth0.com/docs/secure/tokens/refresh-tokens/get-refresh-tokens

Describes how to get a Refresh Token when you initiate a request using the Authorize endpoint.

To get a <Tooltip href="/docs/glossary?term=refresh+token">refresh token</Tooltip>, you must include the `offline_access` [scope](/docs/get-started/apis/scopes) when you initiate an authentication request through the `/authorize` endpoint. Be sure to initiate Offline Access in your API. For more information, read [API Settings](/docs/get-started/apis/api-settings).

For example, if you are using the [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow), the authentication request would look like the following:

<AuthCodeBlock />

The refresh token is stored in session. Then, when a session needs to be refreshed (for example, a preconfigured timeframe has passed or the user tries to perform a sensitive operation), the app uses the refresh token on the backend to obtain a new <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip>, using the `/oauth/token` endpoint with `grant_type=refresh_token`.

Once the user authenticates successfully, the application will be redirected to the `redirect_uri`, with a `code` as part of the URL: `{https://yourApp/callback}?code=BPPLN3Z4qCTvSNOy`. You can exchange this code with an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> using the `/oauth/token` endpoint.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=authorization_code \
    --data 'client_id={yourClientId}' \
    --data 'client_secret={yourClientSecret}' \
    --data 'code={yourAuthorizationCode}' \
    --data 'redirect_uri={https://yourApp/callback}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=authorization_code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&code=%7ByourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=authorization_code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&code=%7ByourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=authorization_code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&code=%7ByourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      code: '{yourAuthorizationCode}',
      redirect_uri: '{https://yourApp/callback}'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=authorization_code" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_secret={yourClientSecret}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&code={yourAuthorizationCode}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&redirect_uri={https://yourApp/callback}" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=authorization_code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&code=%7ByourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=authorization_code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&code=%7ByourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=authorization_code&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&code=%7ByourAuthorizationCode%7D&redirect_uri={https://yourApp/callback}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/x-www-form-urlencoded"]

  let postData = NSMutableData(data: "grant_type=authorization_code".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&client_secret={yourClientSecret}".data(using: String.Encoding.utf8)!)
  postData.append("&code={yourAuthorizationCode}".data(using: String.Encoding.utf8)!)
  postData.append("&redirect_uri={https://yourApp/callback}".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

The response should contain an access token and a refresh token.

```json lines theme={null}
{
      "access_token": "eyJz93a...k4laUWw",
      "refresh_token": "GEbRxBN...edjnXbL",
      "token_type": "Bearer"
    }
```

If you are requesting a Refresh Token for a mobile app using the corresponding Native Client (which is public), then you don't need to send the `client_secret` in the request since it's only required for confidential applications.

Refresh Tokens must be stored securely by an application since they allow a user to remain authenticated essentially forever.

For more information on how to implement this using the Authorization Code Flow, refer to our tutorial, [Call API Using the Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/call-your-api-using-the-authorization-code-flow). For other grants, see [Authentication and Authorization Flows](/docs/get-started/authentication-and-authorization-flow).

## Customize MFA

<Warning>
  Customizable MFA with the Resource Owner Password Grant, Embedded, or Refresh Token flows is in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0’s release stages, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To participate in the early access, contact [Auth0 Support](https://support.auth0.com/).
</Warning>

Customizable MFA allows users to enroll and challenge with factors of their choice that are supported by your application.

During authentication at the `oauth/token` endpoint, the response returns the `mfa_required` error that includes the `mfa_token` to use the MFA API and the `mfa_requirements` parameter with a list of authenticators:

```json theme={null}
{
  "error": "mfa_required",
  "error_description": "Multifactor authentication required",
  "mfa_token": "Fe26...Ha",
  "mfa_requirements": {
    "challenge": [
      { "type": "otp" },
      { "type": "push-notification" },
      { "type": "phone" },
      { "type": "recovery-code" }
      { "type": "email"} //can only work with challenge
    ]
  }
}
```

Use the `mfa_token` to call the [`mfa/authenticator`](/docs/api/authentication/muti-factor-authentication/list-authenticators) endpoint for a list of all factors the user has enrolled and match the same type your application supports.  You also need to obtain the matching `authenticator_type` to issue challenges:

```json theme={null}
[
  {
    "type": "recovery-code",
    "id": "recovery-code|dev_qpOkGUOxBpw6R16t",
    "authenticator_type": "recovery-code",
    "active": true
  },
  {
    "type": "otp",
    "id": "totp|dev_6NWz8awwC8brh2dN",
    "authenticator_type": "otp",
    "active": true
  }
]
```

Enforce the MFA challenge by calling the [`request/mfa/challenge`](/docs/api/authentication/muti-factor-authentication/request-mfa-challenge) endpoint.

Further customize your MFA flow with Auth0 Actions. To learn more, read [Actions Triggers: post-challenge - API Object](/docs/customize/actions/explore-triggers/password-reset-triggers/post-challenge-trigger/post-challenge-api-object).

## Learn more

* [Use Refresh Tokens](/docs/secure/tokens/refresh-tokens/use-refresh-tokens)
* [Revoke Refresh Tokens](/docs/secure/tokens/refresh-tokens/revoke-refresh-tokens)
* [Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation)
* [Configure Refresh Token Expiration](/docs/secure/tokens/refresh-tokens/configure-refresh-token-expiration)


# Refresh Tokens with Actions
Source: https://auth0.com/docs/secure/tokens/refresh-tokens/manage-refresh-tokens-actions

Learn about managing Refresh Tokens with Actions

Using <Tooltip href="/docs/glossary?term=Refresh+tokens">Refresh tokens</Tooltip> with [Actions](/docs/customize/actions) allows you to configure post-authentication risk detection and response capabilities to protect your applications and users against compromised refresh tokens. You can also dynamically customize the [refresh token expirations](/docs/secure/tokens/refresh-tokens/configure-refresh-token-expiration).

To facilitate this, post-login Actions feature two key objects:

* **event.refresh\_token**: Provides relevant information for existing refresh\_tokens including `id`, `created_at`, `expires_at`, `idle_expires_at`, `clients_id`, `device` information, such as `ASN`, `IP`, and `User_agent`, and for browser-based flows, `session_id`. This object is populated by [refresh token exchange](/docs/secure/tokens/refresh-tokens/use-refresh-token-rotation) flows.
* **api.refreshToken**: Allows you to manage existing refresh tokens by revoking sessions or changing expiry dates.

You can use the `event.refresh_token` object to review the `last_exchange_at` property and evaluate risks associated with the current transactions. You can also combine the `event.refresh_token` object with other event objects, such as the `event.authentication`.

You can then use the `api.refreshToken` object to either set refresh token expiry dates or revoke the refresh token.

To learn more about these objects, review:

* [Event object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object): Learn about the refresh token Event object and properties.
* [API object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object): Learn about the refresh token API object and methods.

## Revoke refresh tokens with Actions

The post-login **api.refreshToken.revoke(reason)** method allows you to react to risks associated with a transaction. Revoking the refresh token, invalidates the refresh token, returns a 403 HTTP status code to deny the current transaction, and logs a refresh token revoked event in the [tenant logs](/docs/deploy-monitor/logs/log-event-type-codes) (`srrt`).

<Callout icon="file-lines">
  If you want to use the `api.refreshToken.revoke(reason)` method, ensure that the event.refresh\_token object exists.
</Callout>

### Monitor revoke log events

The revoke operation adds the following log event in your [tenant logs](/docs/deploy-monitor/logs):

A `srrt` event code indicating a refresh token was revoked.

If the refresh token is bound to a previously authenticated session, the log will include a reference to the authenticated session in the `session_id` attribute.

## Change refresh tokens expiry dates with Actions

You can modify refresh tokens expiry dates with the following post-login methods:

* **api.refreshToken.setExpiresAt(absolute)** allows you to define a new absolute expiration date for a specified refresh token.
* **api.refreshToken.setIdleExpiresAt(idle)** allows you to set a new inactivity timeout expiration date for a specified refresh token.

You can use these methods to dynamically customize the refresh token lifetime and inactivity policies based on:

* A user’s organization
* A user’s Auth0 connection
* A specific user’s group membership or profile
* Risk assessment
* Any other dynamic criteria available during execution of the Action

<Callout icon="file-lines">
  The `api.refreshToken.setExpiresAt(absolute)` and `api.refreshToken.setIdleExpiresAt(idle)` methods allow to define the expiration of a refresh token, before its issuance, or modify an existing refresh token expiration during a [refresh token exchange](/docs/secure/tokens/refresh-tokens/use-refresh-tokens) flow.

  The `api.refreshToken.setExpiresAt(absolute)` and the `api.refreshToken.setIdleExpiresAt(idle)` methods will convert non-expiring refresh tokens to expiring refresh tokens using the defaults [Refresh Token expirations](/docs/secure/tokens/refresh-tokens/configure-refresh-token-expiration) settings as maximum values.

  The `api.refreshToken.setIdleExpiresAt(idle)` method sets the inactivity timeout for refresh tokens. If the method is not called in every successful exchange, the inactivity timeout will be overwritten using the refresh token lifetime application settings.
</Callout>

## Limitations

* Refresh tokens issued on or after 21-09-2023 (22-02-2024 for tenants in the US-3 region) contain the session ID (`session_id`) property with the appropriate value. Refresh tokens issued before this date contain this property with a `null` value.

* Refresh tokens issued before the release of the post-login API method `api.refreshToken.revoke(reason)` will not contain `event.refresh_token.device` information.

* Non-expiring refresh tokens or refresh tokens that have not been exchanged will not contain the property `event.refresh_token.last_exchanged_at`.

* For security reasons, inactivity and absolute timeouts cannot be set above the application refresh token settings defined in the [refresh token expirations](/docs/secure/tokens/refresh-tokens/configure-refresh-token-expiration). If you attempt to set a date above the expiration settings, the API methods will update up to the [refresh token expirations](/docs/secure/tokens/refresh-tokens/configure-refresh-token-expiration) and log a warning event (`w`) in the tenant logs.

* Both `api.refreshToken.setExpiresAt()` and `api.refreshToken.setIdleExpiresAt()` can only shorten their respective lifetimes from the current values. They cannot extend or increase the lifetime.

To learn more about refresh tokens limitations, read [Refresh Tokens limitations](/docs/secure/tokens/refresh-tokens).

## Use cases: Revoke a refresh token

You can use [Actions](/docs/customize/actions) to configure risk detections and revoke refresh tokens with the `api.refreshToken.revoke(reason)` method and the event objects.

### Revoke refresh tokens due to ImpossibleTravel

You can use the <Tooltip href="/docs/glossary?term=Adaptive+MFA">Adaptive MFA</Tooltip> [assessments](/docs/secure/multi-factor-authentication/adaptive-mfa/customize-adaptive-mfa#assessments-object) object to determine if a user is logging from a location that indicates ImpossibleTravel and revoke the current refresh token associated with the transaction.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const { riskAssessment } = event.authentication ?? {};
  const ImpossibleTravel = riskAssessment?.assessments.ImpossibleTravel;

  // If this is an impossible travel and this is a refresh token exchange
  if (ImpossibleTravel?.code === "impossible_travel_from_last_login") {
    if (event.refresh_token) {
      api.refreshToken.revoke("Refresh token revoked due to impossible travel");
    }
  }
};
```

In this example, a check occurs at the start of the Action to verify that the `event.authentication.ImpossibleTravel.code` is equal to the `impossible_travel_from_last_login property`. If `true`, the Action calls the `api.refreshToken.revoke()` to:

* Deny the transaction
* Revoke the refresh token
* Return a 403 response access\_denied error
* Issue the error “Refresh token revoked due to impossible travel”

### Revoke refresh tokens due to IP binding

If you use the post-login object properties `event.refresh_token.device.initial_ip` and `event.request.ip` to ensure a refresh token transaction stays with the same IP address for its duration. In this scenario, any IP change is considered a risk, and a new refresh token is required.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  const refreshTokenInitialIp = event.refresh_token?.device?.initial_ip;
  const requestCurrentIp = event.request.ip;

  // if there is a refresh token and the IP changes
  if (
    refreshTokenInitialIp &&
    requestCurrentIp &&
    refreshTokenInitialIp != requestCurrentIp
  ) {
    api.refreshToken.revoke("Invalid IP change");
  }
};
```

In this example, a check occurs at the start of the Action to keep track of the IP addresses with the `event.refresh_token.device.initial_ip` and the `event.request.ip` properties. The Action determines if the transaction IP address has changed. If `true`, the Action calls the `api.refreshToken.revoke()` to:

* Deny the transaction
* Revoke the refresh token
* Return a `403` response `access_denied` error
* Issue the error “`Invalid IP change`”

Alternatively, for a less restrictive Action, you can keep track of the event.`request.asn` and `event.refresh_token.device.initial_asn` properties to monitor for ASN changes instead of IP changes.

## Use cases: Customize refresh token expiry dates

You can use [Actions](/docs/customize/actions) to customize the refresh token lifetime and inactivity dates. Specifically, you can configure the refresh token idle and absolute expiration dates for a particular transaction using the post-login `api.refreshToken.setExpiresAt(absolute)` and `api.refreshToken.setIdleExpiresAt(idle)` methods.

### Customize absolute refresh token expiration date based on Organization

You can use post login action to define a refresh token lifetime per Organization. The example below uses the `refresh_token_timeout` metadata from the Organization to set the expiration time of the refresh token.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  // Refresh token timeout (in miliseconds) metadata configured in the Organizations
  const organization_refresh_token_lifetime =
    event.organization?.metadata?.refresh_token_timeout;

  if (organization_refresh_token_lifetime) {
    // Refresh token already exists
    if (event.refresh_token) {
      const created = Date.parse(event.refresh_token.created_at);

      const new_expiration_time =
        created + Number(organization_refresh_token_lifetime);
      api.refreshToken.setExpiresAt(new_expiration_time);
    } else {
      // Refresh token doesn't exist yet (e.g., token is being issued)
      const current_time = new Date().getTime();

      const new_expiration_time =
        current_time + Number(organization_refresh_token_lifetime);
      api.refreshToken.setExpiresAt(new_expiration_time);
    }
  }
};
```

In this example, If there is a specific absolute timeout defined for an Organization, the Action sets the refresh token absolute timeout to be equal to:

* Newly issued tokens: `current_time` plus `organization_refresh_token_lifetime`
* Existing Tokens: `event.refresh_token.created_at` plus `organization_refresh_token_lifetime`

### Customize refresh token inactivity timeout based on membership role

You can use post login action to define a refresh token idle timeout using [application](/docs/get-started/applications/configure-application-metadata) and [user metadata](/docs/manage-users/user-accounts/metadata). The example below uses the user metadata roles to define the user membership role and Application metadata to define the expected refresh token idle timeout.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  // admins are configured with a shorter idle timeout for refresh tokens, in an application metadata
  const max_idle_lifetime =
    event.client.metadata?.admin_refresh_token_idle_timeout;

  // Check the user app metadata roles attribute to check if it is an admin user.
  const isAdmin = event.user?.app_metadata?.roles?.find(
    (role) => role === "admin",
  );

  // If the application has an specific idle timeout defined, set the timeout
  if (max_idle_lifetime && isAdmin) {
    const current_time = new Date().getTime();

    api.refreshToken.setIdleExpiresAt(current_time + Number(max_idle_lifetime));
  }
};
```

In this example, if there is a specific idle timeout defined for the Application and the user is an Admin, the Action sets the refresh token inactivity timeout to be equal to the `current_time` plus the `refresh_token_idle_timeout`. Note that we are changing the timeout for both newly issued tokens and existing ones during refresh token exchange.


# Multi-Resource Refresh Token
Source: https://auth0.com/docs/secure/tokens/refresh-tokens/multi-resource-refresh-token

Learn about Multi-resource refresh token

<Warning>
  Multi-Resource Refresh Token is currently in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal). To learn more about Auth0's product release cycle, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

Multi-Resource <Tooltip href="/docs/glossary?term=Refresh+Tokens">Refresh Tokens</Tooltip> (MRRT) allows a single [refresh token](/docs/secure/tokens/refresh-tokens) to receive [access tokens](/docs/secure/tokens/access-tokens) for multiple [APIs](/docs/get-started/apis), each with their own scopes and permissions. MRRT builds on standard [OAuth 2.0](/docs/authenticate/protocols/oauth) behavior by allowing refresh tokens to maintain multiple authorization policies.

When an application exchanges a refresh token for an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, it can select from a set of configured <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> and scopes. By doing so, MRRT streamlines authentication flows by avoiding the need to get a new refresh token for each API.
When using MRRT, Auth0 merges two sources of authorization to determine what access token to issue during a refresh token exchange:

1. The audience and scopes granted in the original authentication flow.
2. The audience and scopes configured in the application’s MRRT policy.

This allows applications to reuse the refresh token not only for APIs requested at login, but also for additional APIs allowed in the MRRT policy.

**The key benefits of MRRT include**:

* A single refresh token, per application, to manage when controlling access to multiple APIs.
* No need to go through a full <Tooltip href="/docs/glossary?term=authorization+flow">authorization flow</Tooltip> every time your application needs to access a new API.
* Performance improvement and reduced load on the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip>.
* Decrease risk of [rate limitation](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy) due to repeated full authorization code flows.

## How it works

<Frame>
  <img alt="" />
</Frame>

1. Application authenticates with Auth0.

2. Auth0 returns an access token and a multi-resource refresh token.

3. Application uses the access token to call API 1.

4. Application exchanges the multi-resource refresh token for access to API 2.

5. Auth0 returns a new access token scoped to API 2.

6. Application calls API 2 using the new access token.

<Callout icon="file-lines">
  For example,  A native application authenticates the user and requests access to `https://api.example.com` audience. Then, the application needs access to the `https://billing.example.com` audience. If both APIs are included in the application’s MRRT policy, the application can exchange a refresh token for an access token for either API.
</Callout>

Learn how to [Configure and Implement Multi-resource refresh token](/docs/secure/tokens/refresh-tokens/multi-resource-refresh-token/configure-and-implement-multi-resource-refresh-token).

## Limitations

* Each access token issued through MRRT is scoped to a single API. If your application requires access to multiple APIs, you must request separate access tokens for each API.
* MRRT supports only [first-party applications](/docs/get-started/applications/confidential-and-public-applications/first-party-and-third-party-applications#first-party-applications).
* MRRT supports APIs configured to [allow skipping user consent](/docs/get-started/applications/confidential-and-public-applications/user-consent-and-third-party-applications#skip-consent-for-first-party-applications).
* The Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> can not be included in the MRRT policies.


# Configure and Implement Multi-Resource Refresh Token
Source: https://auth0.com/docs/secure/tokens/refresh-tokens/multi-resource-refresh-token/configure-and-implement-multi-resource-refresh-token

Learn how to configure and implement multi-resource refresh token

<Warning>
  Multi-Resource Refresh Token is currently in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal). To learn more about Auth0's product release cycle, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

## Configure applications for MRRT

To use Multi-Resource <Tooltip href="/docs/glossary?term=Refresh+Tokens">Refresh Tokens</Tooltip> (MRRT), configure your application’s refresh token policies using the Auth0 [Management API](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id). These policies will specify which API and scopes the application is allowed to request during a refresh token exchange.

You can define MRRT policies in the `refresh_token.policies` property of the application.

<table>
  <thead>
    <tr>
      <th><strong>Property</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>audience</code></td>
      <td>string</td>
      <td>The Auth0 API <a href="/docs/get-started/apis/api-settings#general-settings">identifier</a> of the application that will have access to using the refresh token.</td>
    </tr>

    <tr>
      <td><code>scope</code></td>
      <td>Array of strings</td>
      <td>The list of scopes allowed when requesting an access token for the specified audience. The scope must be equal to or narrower than the scopes defined on the API.</td>
    </tr>
  </tbody>
</table>

<Callout icon="file-lines">
  The audience and scope properties must correspond to an existing application in your tenant, otherwise the refresh token exchange will silently ignore them.
</Callout>

For existing applications, make a PATCH call to the [Update a Client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id) endpoint. To create a new application, make a POST call to the [Create a Client](https://auth0.com/docs/api/management/v2/clients/post-clients) endpoint:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://{yourDomain}/api/v2/clients//{yourClientId}' \
    --header 'authorization: Bearer {yourMgmtApiAccessToken}' \
    --header 'content-type: application/json' \
    --data '{
    "refresh_token": {
      "expiration_type": "expiring",
      "rotation_type": "rotating",
      "token_lifetime": 31557600,
      "idle_token_lifetime": 2592000,
      "leeway": 0,
      "infinite_token_lifetime": false,
      "infinite_idle_token_lifetime": false,
      "policies": [
        {
          "audience": "https://api.example.com",
          "scope": ["read:data"]
        },
        {
          "audience": "https://billing.example.com",
          "scope": ["read:billing"]
        }
      ]
    }
  }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/clients//{yourClientId}");
  var request = new RestRequest(Method.PATCH);
  request.AddHeader("authorization", "Bearer {yourMgmtApiAccessToken}");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{
    "refresh_token": {
      "expiration_type": "expiring",
      "rotation_type": "rotating",
      "token_lifetime": 31557600,
      "idle_token_lifetime": 2592000,
      "leeway": 0,
      "infinite_token_lifetime": false,
      "infinite_idle_token_lifetime": false,
      "policies": [
        {
          "audience": "https://api.example.com",
          "scope": ["read:data"]
        },
        {
          "audience": "https://billing.example.com",
          "scope": ["read:billing"]
        }
      ]
    }
  }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/clients//{yourClientId}"

  	payload := strings.NewReader("{
    "refresh_token": {
      "expiration_type": "expiring",
      "rotation_type": "rotating",
      "token_lifetime": 31557600,
      "idle_token_lifetime": 2592000,
      "leeway": 0,
      "infinite_token_lifetime": false,
      "infinite_idle_token_lifetime": false,
      "policies": [
        {
          "audience": "https://api.example.com",
          "scope": ["read:data"]
        },
        {
          "audience": "https://billing.example.com",
          "scope": ["read:billing"]
        }
      ]
    }
  }")

  	req, _ := http.NewRequest("PATCH", url, payload)

  	req.Header.Add("authorization", "Bearer {yourMgmtApiAccessToken}")
  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.patch("https://{yourDomain}/api/v2/clients//{yourClientId}")
    .header("authorization", "Bearer {yourMgmtApiAccessToken}")
    .header("content-type", "application/json")
    .body("{
    "refresh_token": {
      "expiration_type": "expiring",
      "rotation_type": "rotating",
      "token_lifetime": 31557600,
      "idle_token_lifetime": 2592000,
      "leeway": 0,
      "infinite_token_lifetime": false,
      "infinite_idle_token_lifetime": false,
      "policies": [
        {
          "audience": "https://api.example.com",
          "scope": ["read:data"]
        },
        {
          "audience": "https://billing.example.com",
          "scope": ["read:billing"]
        }
      ]
    }
  }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'PATCH',
    url: 'https://{yourDomain}/api/v2/clients//{yourClientId}',
    headers: {
      authorization: 'Bearer {yourMgmtApiAccessToken}',
      'content-type': 'application/json'
    },
    data: {
      refresh_token: {
        expiration_type: 'expiring',
        rotation_type: 'rotating',
        token_lifetime: 31557600,
        idle_token_lifetime: 2592000,
        leeway: 0,
        infinite_token_lifetime: false,
        infinite_idle_token_lifetime: false,
        policies: [
          {audience: 'https://api.example.com', scope: ['read:data']},
          {audience: 'https://billing.example.com', scope: ['read:billing']}
        ]
      }
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer {yourMgmtApiAccessToken}",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"refresh_token": @{ @"expiration_type": @"expiring", @"rotation_type": @"rotating", @"token_lifetime": @31557600, @"idle_token_lifetime": @2592000, @"leeway": @0, @"infinite_token_lifetime": @NO, @"infinite_idle_token_lifetime": @NO, @"policies": @[ @{ @"audience": @"https://api.example.com", @"scope": @[ @"read:data" ] }, @{ @"audience": @"https://billing.example.com", @"scope": @[ @"read:billing" ] } ] } };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/clients//{yourClientId}"]
                                                         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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/clients//{yourClientId}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "PATCH",
    CURLOPT_POSTFIELDS => "{
    "refresh_token": {
      "expiration_type": "expiring",
      "rotation_type": "rotating",
      "token_lifetime": 31557600,
      "idle_token_lifetime": 2592000,
      "leeway": 0,
      "infinite_token_lifetime": false,
      "infinite_idle_token_lifetime": false,
      "policies": [
        {
          "audience": "https://api.example.com",
          "scope": ["read:data"]
        },
        {
          "audience": "https://billing.example.com",
          "scope": ["read:billing"]
        }
      ]
    }
  }",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer {yourMgmtApiAccessToken}",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{
    "refresh_token": {
      "expiration_type": "expiring",
      "rotation_type": "rotating",
      "token_lifetime": 31557600,
      "idle_token_lifetime": 2592000,
      "leeway": 0,
      "infinite_token_lifetime": false,
      "infinite_idle_token_lifetime": false,
      "policies": [
        {
          "audience": "https://api.example.com",
          "scope": ["read:data"]
        },
        {
          "audience": "https://billing.example.com",
          "scope": ["read:billing"]
        }
      ]
    }
  }"

  headers = {
      'authorization': "Bearer {yourMgmtApiAccessToken}",
      'content-type': "application/json"
      }

  conn.request("PATCH", "/{yourDomain}/api/v2/clients//{yourClientId}", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/clients//{yourClientId}")

  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["authorization"] = 'Bearer {yourMgmtApiAccessToken}'
  request["content-type"] = 'application/json'
  request.body = "{
    "refresh_token": {
      "expiration_type": "expiring",
      "rotation_type": "rotating",
      "token_lifetime": 31557600,
      "idle_token_lifetime": 2592000,
      "leeway": 0,
      "infinite_token_lifetime": false,
      "infinite_idle_token_lifetime": false,
      "policies": [
        {
          "audience": "https://api.example.com",
          "scope": ["read:data"]
        },
        {
          "audience": "https://billing.example.com",
          "scope": ["read:billing"]
        }
      ]
    }
  }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer {yourMgmtApiAccessToken}",
    "content-type": "application/json"
  ]
  let parameters = ["refresh_token": [
      "expiration_type": "expiring",
      "rotation_type": "rotating",
      "token_lifetime": 31557600,
      "idle_token_lifetime": 2592000,
      "leeway": 0,
      "infinite_token_lifetime": false,
      "infinite_idle_token_lifetime": false,
      "policies": [
        [
          "audience": "https://api.example.com",
          "scope": ["read:data"]
        ],
        [
          "audience": "https://billing.example.com",
          "scope": ["read:billing"]
        ]
      ]
    ]] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/clients//{yourClientId}")! 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()
  ```
</AuthCodeGroup>

Sample response:

```json lines theme={null}
{
  "client_id": "abc123xyz",
  "name": "My Native App",
  "refresh_token": {
    "rotation_type": "rotating",
    "policies": [
      {
        "audience": "https://api.example.com",
        "scope": ["read:data"]
      },
      {
        "audience": "https://billing.example.com",
        "scope": ["read:billing"]
      }
    ]
  }
}
```

## Implement multi-resource refresh token

Once you configure your application’s refresh token with MRRT policies, you can start to  exchange a single refresh token for <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> across multiple APIs.
To facilitate this, your application needs to initiate a login flow using either the [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow) or the [Resource Owner Password Grant](/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-rop-flow).

### Step 1: Authenticate and request a refresh token

To receive a refresh token, include the `offline_access` scope when initiating the authentication request. To learn more, read [Get Refresh Tokens](/docs/secure/tokens/refresh-tokens/get-refresh-tokens).

<Callout icon="file-lines">
  If you do not receive a refresh token, confirm that:

  * The API has [Allow Offline Access](/docs/get-started/apis/api-settings#access-settings) enabled in its settings.
  * `offline_access` is included in the scope.
  * The `audience` used in the request matches a configured API in your tenant.
</Callout>

### Step 2: Exchange the refresh token for a different API

Once the refresh token is issued, you can request access tokens for any API and scopes defined in both the initial authentication and the MRRT policy. For example:

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/json' \
    --data '{
    "grant_type": "refresh_token",
    "client_id": "{yourClientId}",
    "refresh_token": "${refreshToken}",
    "audience": "https://billing.example.com",
    "scope": "read:billing write:billing"
  }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{
    "grant_type": "refresh_token",
    "client_id": "{yourClientId}",
    "refresh_token": "${refreshToken}",
    "audience": "https://billing.example.com",
    "scope": "read:billing write:billing"
  }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("{
    "grant_type": "refresh_token",
    "client_id": "{yourClientId}",
    "refresh_token": "${refreshToken}",
    "audience": "https://billing.example.com",
    "scope": "read:billing write:billing"
  }")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/json")
    .body("{
    "grant_type": "refresh_token",
    "client_id": "{yourClientId}",
    "refresh_token": "${refreshToken}",
    "audience": "https://billing.example.com",
    "scope": "read:billing write:billing"
  }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/json'},
    data: {
      grant_type: 'refresh_token',
      client_id: '{yourClientId}',
      refresh_token: '${refreshToken}',
      audience: 'https://billing.example.com',
      scope: 'read:billing write:billing'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"grant_type": @"refresh_token",
                                @"client_id": @"{yourClientId}",
                                @"refresh_token": @"${refreshToken}",
                                @"audience": @"https://billing.example.com",
                                @"scope": @"read:billing write:billing" };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{
    "grant_type": "refresh_token",
    "client_id": "{yourClientId}",
    "refresh_token": "${refreshToken}",
    "audience": "https://billing.example.com",
    "scope": "read:billing write:billing"
  }",
    CURLOPT_HTTPHEADER => [
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{
    "grant_type": "refresh_token",
    "client_id": "{yourClientId}",
    "refresh_token": "${refreshToken}",
    "audience": "https://billing.example.com",
    "scope": "read:billing write:billing"
  }"

  headers = { 'content-type': "application/json" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request.body = "{
    "grant_type": "refresh_token",
    "client_id": "{yourClientId}",
    "refresh_token": "${refreshToken}",
    "audience": "https://billing.example.com",
    "scope": "read:billing write:billing"
  }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/json"]
  let parameters = [
    "grant_type": "refresh_token",
    "client_id": "{yourClientId}",
    "refresh_token": "${refreshToken}",
    "audience": "https://billing.example.com",
    "scope": "read:billing write:billing"
  ] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

 To learn more, read [Use Refresh tokens](/docs/secure/tokens/refresh-tokens/use-refresh-tokens).

If you are using the Auth0 Swift SDK, you can exchange the refresh token using the following code:

```swift lines theme={null}
credentialsManager.apiCredentials(forAudience: "https://example.com/me",
                                  scope: "create:me:authentication_methods") { result in
    switch result {
    case .success(let apiCredentials):
        print("Obtained API credentials: \(apiCredentials)")
    case .failure(let error):
        print("Failed with: \(error)")
    }
}
```

To learn more, read [Auth0 Swift SDK](https://github.com/auth0/Auth0.swift/blob/master/EXAMPLES.md#api-credentials-ea).

If you are using the Auth0 Android SDK, you can exchange the refresh token using the following code:

```swift lines theme={null}
credentialsManager.getApiCredentials(
    audience = "https://example.com/me", scope = " create:me:authentication_methods",
    callback = object : Callback<APICredentials, CredentialsManagerException> {
        override fun onSuccess(result: APICredentials) {
            print("Obtained API credentials: $result")
        }
        override fun onFailure(error: CredentialsManagerException) {
            print("Failed with: $error")
        }
    })
```

To learn more, read [Auth0 Android SDK](https://github.com/auth0/Auth0.Android/blob/main/EXAMPLES.md#api-credentials-ea).

### Step 3: Call the API using the access token

Use the access token to call the secured API using the [Bearer HTTP authorization scheme](https://datatracker.ietf.org/doc/html/rfc6750). To learn more, read [Use Access Tokens](/docs/secure/tokens/access-tokens/use-access-tokens).

<Callout icon="file-lines">
  You can decode the access token on [jwt.io](https://jwt.io) to verify:

  * The `aud` claim matches the requested API. (for example: [https://billing.example.com](https://billing.example.com)).
  * The `scope` claim includes only permitted values.
</Callout>

## Use Multi-resource refresh token with Actions

Using MRRT with [Actions](/docs/customize/actions) allows you to configure dynamic decision-making based on the application’s MRRT policies. To facilitate this, post-login Actions features the [`event.client.refresh_token.policies`](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object) object that provides relevant information including <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> and scope.

You can use the `event.client.refresh_token.policies` object to evaluate the application's audience and scope, when issuing or exchanging a refresh token, and to ensure precise control over API access and scopes.

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  // return the list of allowed APIs in the client
  const allowedAPIsInTheClient = event.client.refresh_token?.policies;

  if(allowedAPIsInTheClient?.some(policy => policy?.audience?.includes('https://myapi'))){
    // custom logic
  }
};
```

#### Evaluation logic

MRRT acts as an extension of the original authentication, not a replacement. When exchanging a refresh token, Auth0 evaluates the exchange request using the following logic:

* **If the audience parameter is omitted**, Auth0 returns an access token with the original audience and any of its additional scopes configured in the MRRT policy.
* **If a new audience parameter is specified**, Auth0 verifies that the audience is included in the MRRT policy and returns an access token for the new audience with its configured scopes.
* **If the scope parameter is omitted**, Auth0 combines all allowed scopes from the original request and the MRRT policy.
* **If a new scope parameter is specified**, Auth0 validates the requested scopes and returns an access token with the scopes included in the MRTT policy. Invalid or unauthorized scopes requested are silently ignored.
* **If the audience parameter is the same as from the original request**, Auth0 applies the MRRT policy and returns an access token for the audience with all MRRT configured scopes and original authentication scopes.

MRRT allows you to extend user access to new APIs without issuing new refresh tokens or requiring user login again.

#### Examples

A user logs in requesting the following audience and scope:

```json lines theme={null}
{
"audience": "https://api.example.com",  
"scope": "openid profile read:messages"
}
```

The application’s MRRT policy is configured to add an additional scope:

```json lines theme={null}
{
  "audience": "https://api.example.com",
  "scope": ["write:messages"]
}
```

A refresh token exchange using the same audience and no scopes would result in an access token containing all configured scopes:

```json lines theme={null}
{
  "aud": "https://api.example.com",
  "scope": "openid profile read:messages write:messages"
}
```


# Refresh Token Metadata
Source: https://auth0.com/docs/secure/tokens/refresh-tokens/refresh-token-metadata

Learn about Auth0 refresh token metadata

<Warning>
  Refresh Token Metadata is currently in Early Access for Enterprise customers only. By using this feature, you agree to the applicable Free Trial terms in Okta's [Master Subscription Agreement](https://www.okta.com/legal). To learn more about Auth0's product release cycle, read [Product Release Stages](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

Refresh token metadata allows the storage of customizable keys and values (maximum 255 characters each) in an Auth0 [refresh token](/docs/secure/tokens/refresh-tokens).

Use cases for refresh token metadata include:

* Track device information, such as device name or login location
* Store token-level flags, for example, `user_accepted_terms` or `session_type`
* Share state between multiple Actions in the same flow
* Drive conditional logic for token issuance or revocation
* Audit and analytics pipelines that need to be aware of user context data

You can access and modify refresh token metadata during a refresh token's lifecycle using Auth0 [Actions](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) and the [Management API](https://auth0.com/docs/api/management/v2).

To learn more, read [how to Configure Refresh Token Metadata](/docs/secure/tokens/refresh-tokens/refresh-token-metadata/configure-refresh-token-metadata).

## Supported flows

You can set refresh token metadata using Post-Login Actions with the following OAuth 2.0 flows:

* Authorization Code Flow
* Resource Owner Password Grant
* Device Authorization Grant
* Federated Connection Flows
* Client-Initiated Backchannel Authentication (CIBA)
* Native Passkeys
* Refresh Token Exchange

<Callout icon="file-lines">
  You can **set** refresh token metadata during any of the supported flows above. However, existing metadata is only **available to read** via the `event.refresh_token.metadata` object during [refresh token exchange](/docs/secure/tokens/refresh-tokens/use-refresh-tokens) scenarios where `event.refresh_token` exists. At the initial login, `event.refresh_token` does not exist, so you can only set metadata—not read it. During a refresh token exchange, you can both read existing metadata and set new values.
</Callout>

When executing a refresh token exchange, the metadata set in Actions is applied when the refresh token is issued, not during intermediate steps such as MFA challenges.

## Limitations

* Refresh token metadata is limited to 25 entries maximum
* Each key and value must be 255 characters or less
* Metadata keys may only include letters, numbers, underscores, or hyphens

## Learn more

* [Configure Refresh Token Metadata](/docs/secure/tokens/refresh-tokens/refresh-token-metadata/configure-refresh-token-metadata)
* [Refresh Tokens with Actions](/docs/secure/tokens/refresh-tokens/manage-refresh-tokens-actions)
* [Refresh Tokens](/docs/secure/tokens/refresh-tokens)


# Configure Refresh Token Metadata
Source: https://auth0.com/docs/secure/tokens/refresh-tokens/refresh-token-metadata/configure-refresh-token-metadata

Learn how to configure Auth0 refresh token metadata

<Warning>
  Refresh Token Metadata is currently in Early Access for Enterprise customers only. By using this feature, you agree to the applicable Free Trial terms in Okta's [Master Subscription Agreement](https://www.okta.com/legal). To learn more about Auth0's product release cycle, read [Product Release Stages](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

To configure refresh token metadata, you can use an Auth0 [Post-Login Action](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) and the [Management API](https://auth0.com/docs/api/management/v2).

## Auth0 Post-Login Actions

You can manage refresh token metadata CRUD operations using the `api.refreshToken` objects with a [post-login Action](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger). This allows you to manage refresh token metadata based on user or context-specific logic.

### Retrieve existing refresh token metadata

Use the `event.refresh_token.metadata` object to read the refresh token metadata:

```javascript lines theme={null}
const deviceName = event.refresh_token?.metadata?.deviceName;
```

<Callout icon="file-lines">
  The `event.refresh_token.metadata` object includes metadata set in:

  * Previous Actions within the same flow
  * Prior transactions if the refresh token was reused during a refresh token exchange
</Callout>

### Add or update existing metadata

Use the `api.refreshToken.setMetadata()` method to set or update the refresh token metadata:

```javascript lines theme={null}
api.refreshToken.setMetadata("deviceName", "Auth0's iPhone");
```

Changes are immediately available in the `event.refresh_token` object in subsequent Actions.

### Delete refresh token metadata

Use the following `api.refreshToken` methods to delete refresh token metadata:

* `api.refreshToken.deleteMetadata("key")` deletes the specified refresh token metadata

* `api.refreshToken.evictMetadata()` deletes all refresh token metadata

To learn more about these objects, review:

* [Event object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object): Learn about the refresh token Event object and properties.
* [API object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object): Learn about the refresh token API object and methods.

## Auth0 Management API

You can manage refresh token metadata CRUD (create, replace, update, delete) requests using the Management API:

<Callout icon="file-lines">
  Calls to the `/api/v2/refresh-tokens/{id}` endpoint require a [Management API access token](/docs/secure/tokens/access-tokens) with the `update:refresh_tokens` scope.
</Callout>

### Retrieve existing refresh token metadata

Make a `GET` request to the [`/api/v2/refresh-tokens/{id}`](https://auth0.com/docs/api/management/v2/refresh-tokens/get-refresh-token) endpoint:

```bash lines theme={null}
GET /api/v2/refresh-tokens/{id}
```

### Add or update existing refresh token metadata

Make a `PATCH` request to the [`/api/v2/refresh-tokens/{id}`](https://auth0.com/docs/api/management/v2/refresh-tokens/patch-refresh-token) endpoint:

```bash lines theme={null}
PATCH /api/v2/refresh-tokens/{id}
Content-Type: application/json

{
  "refresh_token_metadata": {
    "my_metadata": "my new metadata"
  }
}
```

### Delete refresh token metadata

Make a `PATCH` request to the [`/api/v2/refresh-tokens/{id}`](https://auth0.com/docs/api/management/v2/refresh-tokens/patch-refresh-token) endpoint with an empty metadata object:

```bash lines theme={null}
PATCH /api/v2/refresh-tokens/{id}
Content-Type: application/json

{
  "refresh_token_metadata": {}
}
```

## Use case: Store and consume organization context

You can use refresh token metadata to store organization context during the initial authentication and consume it later during refresh token exchanges. This is useful for downstream systems such as audit, analytics, and revocation pipelines.

### Set metadata at initial authentication

During the initial login, set the organization context in the refresh token metadata:

```javascript lines theme={null}
/**
 * Post-Login Action
 * Adds organization context to refresh token metadata during initial authentication.
 * This metadata will be available in subsequent refresh token exchanges.
 */
exports.onExecutePostLogin = async (event, api) => {
  // Only proceed if the transaction targets an Organization
  if (!event.organization) return;

  // Keep values short and string-only (refresh token metadata requires strings)
  const orgId = String(event.organization.id || "");
  const orgSlug = String(event.organization.name || "");
  const orgDisplay = String(event.organization.display_name || orgSlug);

  // Set metadata - this will be stored with the refresh token
  api.refreshToken.setMetadata("org_id", orgId);
  api.refreshToken.setMetadata("org_slug", orgSlug);
  api.refreshToken.setMetadata("org_name", orgDisplay);
};
```

### Consume metadata during refresh token exchange

During a refresh token exchange, the `event.refresh_token` object exists and you can read the previously stored metadata:

```javascript lines theme={null}
/**
 * Post-Login Action
 * Consumes organization context from refresh token metadata during token exchange.
 * Use this to enforce policies or add claims based on the original authentication context.
 */
exports.onExecutePostLogin = async (event, api) => {
  // Check if this is a refresh token exchange (event.refresh_token exists)
  if (!event.refresh_token) return;

  // Read organization context stored during initial authentication
  const orgId = event.refresh_token.metadata?.org_id;
  const orgSlug = event.refresh_token.metadata?.org_slug;

  if (orgId) {
    // Use the organization context for conditional logic
    console.log(`Refresh token exchange for organization: ${orgSlug}`);
    
    // Example: Add custom claims based on the original org context
    api.accessToken.setCustomClaim("org_id", orgId);
  }
};
```

### Retrieve via Management API

You can also query the refresh token metadata via the [/api/v2/refresh-tokens/](https://auth0.com/docs/api/management/v2/refresh-tokens/get-refresh-token) endpoint:

```bash lines theme={null}
GET /api/v2/refresh-tokens/{id}
```

Sample response:

```json lines theme={null}
{
  "refresh_token_metadata": {
    "org_id": "org_abc123",
    "org_slug": "acme",
    "org_name": "Acme Corp"
  }
}
```

## Use case: Track and validate device information

You can use refresh token metadata to capture device information at the initial authentication and validate it during subsequent refresh token exchanges for security purposes.

### Set device information at initial authentication

```javascript lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  // Only set device info if this is NOT a refresh token exchange
  // (i.e., this is the initial authentication)
  if (event.refresh_token) return;

  // Store device information in refresh token metadata
  api.refreshToken.setMetadata("initial_ip", event.request?.ip || "unknown");
  api.refreshToken.setMetadata("initial_asn", event.request?.asn?.value || "unknown");
  api.refreshToken.setMetadata("initial_country", event.request?.geoip?.country_code || "unknown");
  api.refreshToken.setMetadata("initial_user_agent", event.request?.user_agent || "unknown");
};
```

### Validate device information during refresh token exchange

```javascript lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  // Only validate if this is a refresh token exchange
  if (!event.refresh_token) return;

  // Read the original device information
  const initialCountry = event.refresh_token.metadata?.initial_country;
  const currentCountry = event.request?.geoip?.country_code;

  // Example: Detect country change and take action
  if (initialCountry && currentCountry && initialCountry !== currentCountry) {
    console.log(`Country changed from ${initialCountry} to ${currentCountry}`);
    
    // Option 1: Revoke the refresh token for suspicious activity
    // api.refreshToken.revoke("Suspicious country change detected");
    
    // Option 2: Update metadata to track the change
    api.refreshToken.setMetadata("country_changed", "true");
    api.refreshToken.setMetadata("last_country", currentCountry);
  }
};
```

## Error handling

You can review refresh token metadata log events by navigating to [Dashboard > Monitoring > Logs](https://manage.auth0.com/#/logs) or retrieve logs using the [Management API logs](/docs/api/management/v2/logs/get-logs) endpoint.

* If an error occurs while adding or updating refresh token metadata with Actions, the authentication transaction fails and an error is returned to the callback URL.

A failure `f` event code is logged with its corresponding error:

```json lines theme={null}
{
  "error": "access_denied",
  "error_description": "Failed to set refresh token metadata: Invalid metadata: Metadata keys may only include letters, numbers, underscores, or hyphens",
  "state": "my-custom-state"
}
```

* If a failure occurs when managing refresh token metadata using the Auth0 Management API, the API responds with an `HTTP status: 400` error and its corresponding message:

```json lines theme={null}
{
  "statusCode": 400,
  "message": "Metadata must not exceed 25 entries. Each key and value must be ≤ 255 characters."
}
```

## Learn more

* [Refresh Token Metadata](/docs/secure/tokens/refresh-tokens/refresh-token-metadata)
* [Refresh Tokens with Actions](/docs/secure/tokens/refresh-tokens/manage-refresh-tokens-actions)
* [Refresh Tokens](/docs/secure/tokens/refresh-tokens)
* [Post-Login Event Object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object)
* [Post-Login API Object](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object)


# Refresh Token Rotation
Source: https://auth0.com/docs/secure/tokens/refresh-tokens/refresh-token-rotation

Describes how refresh token rotation provides greater security by issuing a new refresh token with each request made to Auth0 for a new access token by a client using refresh tokens.

<Tooltip href="/docs/glossary?term=Refresh+token">Refresh token</Tooltip> rotation is a technique for getting new <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> using refresh tokens that goes beyond [silent authentication](/docs/authenticate/login/configure-silent-authentication). Refresh tokens are typically longer-lived and can be used to request new access tokens after the shorter-lived access tokens expire. Refresh tokens are often used in native applications on mobile devices in conjunction with short-lived access tokens to provide seamless UX without having to issue long-lived access tokens.

With <Tooltip href="/docs/glossary?term=refresh+token+rotation">refresh token rotation</Tooltip> enabled in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, every time an application exchanges a refresh token to get a new access token, a new refresh token is also returned. Therefore, you no longer have a long-lived refresh token that, if compromised, could provide illegitimate access to resources. As refresh tokens are continually exchanged and invalidated, the threat is reduced.

The way refresh token rotation works in Auth0 conforms with the [OAuth 2.0 BCP](https://tools.ietf.org/html/draft-ietf-oauth-security-topics-13#section-4.12) and works with the following flows:

* [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow)
* [Authorization Code Flow with Proof Key for Code Exchange](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce)
* [Device Authorization Flow](/docs/get-started/authentication-and-authorization-flow/device-authorization-flow)
* [Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow)

## Maintain user sessions in SPAs

Until very recently, SPAs maintained the user’s session by using the Authorization Code Flow with PKCE in conjunction with silent authentication. Recent developments in browser privacy technology, such as Intelligent Tracking Prevention (ITP) prevent access to the Auth0 <Tooltip href="/docs/glossary?term=session+cookie">session cookie</Tooltip>, thereby requiring users to reauthenticate.

<Frame>
  <img alt="Refresh Token Rotation Maintain User Sessions in SPAs diagram" />
</Frame>

Unfortunately, long-lived refresh tokens are not suitable for SPAs because there is no persistent storage mechanism in a browser that can assure access by the intended application only. As there are vulnerabilities that can be exploited to obtain these high-value artifacts and grant malicious actors access to protected resources, using refresh tokens in SPAs has been strongly discouraged.

Refresh token rotation offers a remediation to end-user sessions being lost due to side-effects of browser privacy mechanisms. Because refresh token rotation does not rely on access to the Auth0 session cookie, it is not affected by ITP or similar mechanisms.

The following state diagram illustrates how refresh token rotation is used in conjunction with the Authorization Code Flow with PKCE, but the general principle of getting a new refresh token with each exchange applies to all supported flows.

<Frame>
  <img alt="Refresh Token Rotation Maintain User Sessions in SPAs State diagram" />
</Frame>

This means you can safely use refresh tokens to mitigate the adverse effects of browser privacy tools and provide continuous access to end-users without disrupting the user experience.

## Automatic reuse detection

When a client needs a new access token, it sends the refresh token with the request to Auth0 to get a new token pair. As soon as the new pair is issued by Auth0, the refresh token used in the request is invalidated. This safeguards your app from replay attacks resulting from compromised tokens.

Without enforcing sender-constraint, it’s impossible for the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip> to know which actor is legitimate or malicious in the event of a replay attack. So it’s important that the most recently issued refresh token is also immediately invalidated when a previously-used refresh token (already invalidated) is sent to the authorization server. This prevents any refresh tokens in the same token family (all refresh tokens descending from the original refresh token issued for the client) from being used to get new access tokens.

For example, consider the following scenario:

<Frame>
  <img alt="Refresh Token Rotation Reuse Detection state diagram" />
</Frame>

1. Legitimate Client has **refresh token 1**, and it is leaked to or stolen by Malicious Client.
2. Legitimate Client uses **refresh token 1** to get a new refresh token/access token pair.
3. Auth0 returns **refresh token 2/access token 2**.
4. Malicious Client then attempts to use **refresh token 1** to get an access token. Auth0 recognizes that refresh token 1 is being reused, and immediately invalidates the refresh token family, including **refresh token 2**.
5. Auth0 returns an access denied response to Malicious Client.
6. **Access token 2** expires and Legitimate Client attempts to use **refresh token 2** to request a new token pair. Auth0 returns an access denied response to Legitimate Client.
7. Re-authentication is required.

This protection mechanism works regardless of whether the legitimate client or the malicious client is able to exchange **refresh token 1** for a new token pair before the other. As soon as reuse is detected, all subsequent requests will be denied until the user re-authenticates. When reuse is detected, Auth0 captures detected reuse [events](/docs/deploy-monitor/logs/log-event-type-codes) (such as `ferrt` indicating a failed exchange) in logs. This can be especially useful in conjunction with Auth0’s [log streaming](/docs/customize/log-streams) capabilities to detect suspicious activity.

Another example is where the malicious client steals **refresh token 1** and successfully uses it to acquire an access token before the legitimate client attempts to use **refresh token 1**. In this case, the malicious client’s access would be short-lived because **refresh token 2** (or any subsequently issued refresh tokens) is automatically revoked when the legitimate client tries to use **refresh token 1**, as shown in the following diagram:

<Frame>
  <img alt="Refresh Token Rotation Reuse Detection State diagram" />
</Frame>

## SDK support

The following SDKs include support for refresh token rotation and automatic reuse detection.

* Auth0 SPA SDK
* Flutter (Web)
* Swift (iOS) SDK
* Android SDK
* Flutter
* React Native SDK
* WPF / Winforms
* Xamarin

For documentation specific to these SDKs, visit the [Auth0 SDK Libraries](/docs/libraries) page.

You can choose to store tokens in either local storage or browser memory. The default is in browser memory. See [Token Best Practices](/docs/secure/tokens/token-best-practices) for recommendations about token storage. You must enable offline access and request the offline access scope in the client SDK.

## Learn more

* [Configure Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/configure-refresh-token-rotation)
* [Disable Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/disable-refresh-token-rotation)
* [Configure Refresh Token Expiration](/docs/secure/tokens/refresh-tokens/configure-refresh-token-expiration)
* [Token Best Practices](/docs/secure/tokens/token-best-practices)


# Revoke Refresh Tokens
Source: https://auth0.com/docs/secure/tokens/refresh-tokens/revoke-refresh-tokens

Learn how to revoke a refresh token if it gets compromised using the Authentication API, the Management API, or the Auth0 Dashboard.

You can revoke <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip> in case they become compromised. Auth0 handles token revocation as though the token has been potentially exposed to malicious adversaries.

You can also use [refresh token rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation) so that every time a client exchanges a refresh token to get a new <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>, a new refresh token is also returned. Therefore, you no longer have a long-lived refresh token that, if compromised, could provide illegitimate access to resources. As refresh tokens are continually exchanged and invalidated, the threat is reduced.

You can revoke a refresh token in the following ways:

* In the Dashboard
* Post a request to the Authentication API `/oauth/revoke` endpoint
* Post a request to the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> `/api/v2/device-credentials` endpoint

## Refresh tokens and grants

A grant provides an application with access to a resource on another entity without exposing user credentials. Tokens are issued in the context of a grant, and when a grant is revoked, so are all tokens issued in the context of that grant. When, on the other hand, a token is revoked, this does not necessarily mean that the grant is revoked.

You can choose the revocation behavior in the Dashboard tenant settings when a device is unlinked from a user in Auth0, using either the Dashboard or the Management API.

<Callout icon="file-lines">
  For existing tenants, this feature is enabled by default to preserve the existing behavior. For new tenants (as of 13 January 2021), this feature is disabled by default to ensure that the revocation of a refresh token will not revoke the grant. If a grant revocation is needed, a separate request must be sent using a grant revocation endpoint.
</Callout>

1. Go to [Dashboard > Tenant Settings > Advanced](https://manage.auth0.com/#/tenant/advanced) and scroll to the **Settings** section.
2. Enable or disable the **Refresh Token Revocation Deletes Grant** toggle depending on how you want the revocation to work.

   1. Enable the toggle to delete the underlying grant when you revoke the refresh token. Each revocation request invalidates not only the specific token but all other tokens based on the same authorization grant. This means that all refresh tokens that have been issued for the same user, application, and audience will be revoked.
   2. Disable the toggle to retain the underlying grant when you revoke the refresh token. When a device is unlinked, only the associated refresh token is revoked, leaving the grant intact.

## Use the Dashboard

You can use the Dashboard to revoke a user's authorized access to the application that issued the token. This renders the refresh token invalid, which is functionally identical to revoking the token itself.

1. Go to [Dashboard > User Management > Users](https://manage.auth0.com/#/users), and click the name of the user to view.
2. Select the **Authorized Applications** tab. This page lists all the applications to which the user has authorized access.
3. To revoke the user's access to an authorized application, and hence invalidate the refresh token, click **Revoke**.

## Use the Authentication API

To revoke a refresh token, send a `POST` request to `https://{yourDomain}/oauth/revoke`.

The `/oauth/revoke` endpoint revokes the entire grant, not just a specific token. Use the `/api/v2/device-credentials` endpoint to revoke refresh tokens. The API first validates the application credentials and then verifies whether the token was issued to the application making the revocation request. If this validation fails, the request is refused, and the application is informed of the error. Next, the API invalidates the token. The invalidation takes place immediately, and the token cannot be used again after the revocation. Each revocation request invalidates all the tokens that have been issued for the same authorization grant.

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/revoke' \
    --header 'content-type: application/json' \
    --data '{ "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "token": "{yourRefreshToken}" }'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/revoke");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{ "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "token": "{yourRefreshToken}" }", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/oauth/revoke"

  	payload := strings.NewReader("{ "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "token": "{yourRefreshToken}" }")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/oauth/revoke")
    .header("content-type", "application/json")
    .body("{ "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "token": "{yourRefreshToken}" }")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/revoke',
    headers: {'content-type': 'application/json'},
    data: {
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      token: '{yourRefreshToken}'
    }
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"client_id": @"{yourClientId}",
                                @"client_secret": @"{yourClientSecret}",
                                @"token": @"{yourRefreshToken}" };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/revoke"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/revoke",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{ "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "token": "{yourRefreshToken}" }",
    CURLOPT_HTTPHEADER => [
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{ "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "token": "{yourRefreshToken}" }"

  headers = { 'content-type': "application/json" }

  conn.request("POST", "/{yourDomain}/oauth/revoke", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/revoke")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/json'
  request.body = "{ "client_id": "{yourClientId}", "client_secret": "{yourClientSecret}", "token": "{yourRefreshToken}" }"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/json"]
  let parameters = [
    "client_id": "{yourClientId}",
    "client_secret": "{yourClientSecret}",
    "token": "{yourRefreshToken}"
  ] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/revoke")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

Where:

<table>
  <thead>
    <tr>
      <th>Attribute</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>client\_id</code> <br /><span>Required</span></td>
      <td>Your application's Client ID. The application should match the one the Refresh Token was issued for.</td>
    </tr>

    <tr>
      <td><code>client\_secret</code></td>
      <td>Your application's Client Secret. Required for <a href="/docs/get-started/applications/confidential-and-public-applications#confidential-applications">confidential applications</a>.</td>
    </tr>

    <tr>
      <td><code>token</code> <br /><span>Required</span></td>
      <td>The Refresh Token you want to revoke.</td>
    </tr>
  </tbody>
</table>

The application should match the one for which the refresh token was issued.

### Revoke tokens without the client secret

For applications that cannot keep the <Tooltip href="/docs/glossary?term=client+secret">client secret</Tooltip> safe (such as native apps), the `/oauth/revoke` endpoint supports access without the client secret. However, the application itself must have the property `tokenEndpointAuthMethod` set to `none`. You can change the `tokenEndpointAuthMethod` value, either from the [Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), or using the Management API.

If the request is valid, the refresh token is revoked, and the response is `HTTP 200`, with an empty response body. Otherwise, the response body contains the error code and description.

```json lines theme={null}
{
      "error": "invalid_request|invalid_client",
      "error_description": "Description of the error"
    }
```

The possible responses are:

<table>
  <thead>
    <tr>
      <th>HTTP Status</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>200</td>
      <td>The Refresh Token is revoked, does not exist, or was not issued to the application making the revocation request. The response body is empty.</td>
    </tr>

    <tr>
      <td>400</td>
      <td>The required parameters were not sent in the request (<code>"error": "invalid\_request"</code>).</td>
    </tr>

    <tr>
      <td>401</td>
      <td>The request is not authorized (<code>"error": "invalid\_client"</code>). Check that the application credentials (<code>client\_id</code> and <code>client\_secret</code>) are present in the request and hold valid values.</td>
    </tr>
  </tbody>
</table>

## Use the Management API

To revoke a refresh token using the Auth0 Management API, you need the `id` of the refresh token you wish to revoke. To obtain a list of existing refresh tokens, call the `/api/v2/device-credentials` [endpoint](https://auth0.com/docs/api/management/v2#!/Device_Credentials/get_device_credentials), specifying `type=refresh_token` and `user_id` with an access token containing `read:device_credentials` scope. To narrow the results, you can also specify the `client_id` associated with the token (if known).

<AuthCodeBlock />

Response body:

```json lines theme={null}
[
    {
  "id": "dcr_dFJiaAxbEroQ5xxx",
  "device_name": "my-device" // the value of 'device' provided in the /authorize call when creating the token
    }
  ]
```

To revoke a refresh token, call the `/api/v2/device-credentials` endpoint with an access token containing `delete:device_credentials` scope and the value of ID obtained above:

<AuthCodeBlock />

The response will be `HTTP 204: The credential no longer exists.`

## Considerations and limitations

With the [Device Authorization Flow](/docs/get-started/authentication-and-authorization-flow/device-authorization-flow), the only way to force a device to reauthorize is to revoke the refresh token assigned to the device. See [Unlink Devices from Users](/docs/manage-users/user-accounts/unlink-devices-from-users) for details. The device will not be forced to reauthorize until the current access token expires and the application tries to use the revoked refresh token.

When using [Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation), if a previously invalidated token is used, the entire set of refresh tokens issued since that invalidated token was issued will immediately be revoked, requiring the end-user to re-authenticate.

* Use the Authentication API `/oauth/revoke` [endpoint](https://auth0.com/docs/api/authentication#revoke-refresh-token) to revoke a refresh token. This endpoint does not delete the underlying grant. You can change this behavior to also delete the underlying grant in the Dashboard: [Dashboard > Tenant Settings > Advanced](https://manage.auth0.com/#/tenant/advanced). Scroll to **Settings** and enable the **Refresh Token Revocation Deletes Grant** toggle.
* Use the Management API `/api/v2/device-credentials` [endpoint](https://auth0.com/docs/api/management/v2#!/Device_Credentials/get_device_credentials) to revoke refresh tokens configured for rotation.

## Learn more

* [Get Refresh Tokens](/docs/secure/tokens/refresh-tokens/get-refresh-tokens)
* [Use Refresh Tokens](/docs/secure/tokens/refresh-tokens/use-refresh-tokens)
* [Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation)
* [Configure Refresh Token Expiration](/docs/secure/tokens/refresh-tokens/configure-refresh-token-expiration)


# Use Refresh Token Rotation
Source: https://auth0.com/docs/secure/tokens/refresh-tokens/use-refresh-token-rotation

Describes how to use Refresh Token rotation for you received during authorization.

To use <Tooltip href="/docs/glossary?term=refresh+token">refresh token</Tooltip> rotation, you will use the Auth0 Single Page App SDK. The Auth0 SPA SDK handles token storage, session management, and other details for you.

## Prerequisite

[Configure refresh token rotation](/docs/secure/tokens/refresh-tokens/configure-refresh-token-rotation) to enable offline access and request the offline access scope in the client SDK.

## Enable useRefreshTokens

In compliance with the OAuth2 specifications, when a browser requests a refresh token from the /<Tooltip href="/docs/glossary?term=token+endpoint">token endpoint</Tooltip>, Auth0 will only return a refresh token if <Tooltip href="/docs/glossary?term=Refresh+Token+Rotation">Refresh Token Rotation</Tooltip> is enabled for that client.

Use the option `useRefreshTokens` on `createAuth0Client` which defaults to `false`. With this option set to `false`, when `getTokenSilently()` is invoked and a new <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> is required, the SDK attempts to acquire a new Access Token using a hidden iframe and `prompt=none`.

If you set to this option to `true`, the `offline_access` scope is automatically requested when using `loginWithRedirect(), loginWithPopup()` and `getTokenSilently()`. When `getTokenSilently()` is invoked and the Access Token has expired, the SDK attempts to renew the ID and Access Tokens by calling the `/token` endpoint using the `refresh_token` grant type along with the Refresh Token from the cache.

Silent re-authentication is achieved by sending a `prompt=none` parameter upon the authentication request and using a hidden iframe, provided that there is an active user session on the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip>. The SDK uses the iframe method if you have set `useRefreshTokens` to `true` but no Refresh Token is available in the cache. This helps users to silently migrate to using Refresh Tokens without making them log in again.

If the exchange fails because `useRefreshTokens` is `true` but there isn't a Refresh Token in the cache, then it falls back to the iframe method (which could also fail if third-party cookies are blocked).

## Token storage

With SPAs, ID and Access Tokens are obtained from the authorization server and typically cached in memory. Token renewal (due to refreshing the browser, memory cache eviction budgets, or expiration) is handled by the SDK.

## Example

The following example shows how to configure the SDK to use both local storage and refresh tokens:

```javascript lines theme={null}
const auth0 = await createAuth0Client({
    domain: '<your Auth0 domain>',
    client_id: '<your Auth0 client ID>',
    cacheLocation: 'localstorage',
    useRefreshTokens: true
    });
    
    // Logging-in will automatically request the offline_access scope
    // and store the resulting refresh token
    auth0.loginWithRedirect();
    
    // Silently refreshing the access token will use the /token endpoint
    // with ‘refresh_token’ grant and the refresh token from the cache
    await auth0.getTokenSilently();
```

## Learn more

* [Configure Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/configure-refresh-token-rotation)
* [Disable Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/disable-refresh-token-rotation)
* [Token Best Practices](/docs/secure/tokens/token-best-practices)


# Use Refresh Tokens
Source: https://auth0.com/docs/secure/tokens/refresh-tokens/use-refresh-tokens

Describes how to use a Refresh Token you received during authorization.

<Tooltip href="/docs/glossary?term=Refresh+tokens">Refresh tokens</Tooltip> are used to request a new <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> and/or <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> for a user without requiring them to re-authenticate.

Typically, you should request a new access token before the previous one expires (to avoid any service interruption), but not every time you call an API, as token exchanges are subject to our [Rate Limiting Policy](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy).

You may also use a refresh token to request a new ID token for a user, and should do so if you need to refresh the claims within the ID token.

## Call the API

To exchange the refresh token you received during authentication for a new access token, call the Auth0 Authentication API [Get token endpoint](https://auth0.com/docs/api/authentication#refresh-token) in the Authentication API.

To learn more about the authentication methods available for the Authentication API, read [Authentication Methods](https://auth0.com/docs/api/authentication#authentication-methods).

### Use Basic authentication

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'authorization: Basic {yourApplicationCredentials}' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=refresh_token \
    --data 'client_id={yourClientId}' \
    --data 'refresh_token={yourRefreshToken}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddHeader("authorization", "Basic {yourApplicationCredentials}");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")
  	req.Header.Add("authorization", "Basic {yourApplicationCredentials}")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .header("authorization", "Basic {yourApplicationCredentials}")
    .body("grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {
      'content-type': 'application/x-www-form-urlencoded',
      authorization: 'Basic {yourApplicationCredentials}'
    },
    data: new URLSearchParams({
      grant_type: 'refresh_token',
      client_id: '{yourClientId}',
      refresh_token: '{yourRefreshToken}'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded",
                             @"authorization": @"Basic {yourApplicationCredentials}" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=refresh_token" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&refresh_token={yourRefreshToken}" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D",
    CURLOPT_HTTPHEADER => [
      "authorization: Basic {yourApplicationCredentials}",
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D"

  headers = {
      'content-type': "application/x-www-form-urlencoded",
      'authorization': "Basic {yourApplicationCredentials}"
      }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request["authorization"] = 'Basic {yourApplicationCredentials}'
  request.body = "grant_type=refresh_token&client_id={yourClientId}&refresh_token=%7ByourRefreshToken%7D"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = [
    "content-type": "application/x-www-form-urlencoded",
    "authorization": "Basic {yourApplicationCredentials}"
  ]

  let postData = NSMutableData(data: "grant_type=refresh_token".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&refresh_token={yourRefreshToken}".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

### Use Post authentication

<AuthCodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/oauth/token' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=refresh_token \
    --data 'client_id={yourClientId}' \
    --data 'client_secret={yourClientSecret}' \
    --data 'refresh_token={yourRefreshToken}'
  ```

  ```csharp C# theme={null}
  var client = new RestClient("https://{yourDomain}/oauth/token");
  var request = new RestRequest(Method.POST);
  request.AddHeader("content-type", "application/x-www-form-urlencoded");
  request.AddParameter("application/x-www-form-urlencoded", "grant_type=refresh_token&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&refresh_token=%7ByourRefreshToken%7D", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/oauth/token"

  	payload := strings.NewReader("grant_type=refresh_token&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&refresh_token=%7ByourRefreshToken%7D")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("content-type", "application/x-www-form-urlencoded")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/oauth/token")
    .header("content-type", "application/x-www-form-urlencoded")
    .body("grant_type=refresh_token&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&refresh_token=%7ByourRefreshToken%7D")
    .asString();
  ```

  ```javascript Node.JS theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/oauth/token',
    headers: {'content-type': 'application/x-www-form-urlencoded'},
    data: new URLSearchParams({
      grant_type: 'refresh_token',
      client_id: '{yourClientId}',
      client_secret: '{yourClientSecret}',
      refresh_token: '{yourRefreshToken}'
    })
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };

  NSMutableData *postData = [[NSMutableData alloc] initWithData:[@"grant_type=refresh_token" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_id={yourClientId}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&client_secret={yourClientSecret}" dataUsingEncoding:NSUTF8StringEncoding]];
  [postData appendData:[@"&refresh_token={yourRefreshToken}" dataUsingEncoding:NSUTF8StringEncoding]];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/token"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/oauth/token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=refresh_token&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&refresh_token=%7ByourRefreshToken%7D",
    CURLOPT_HTTPHEADER => [
      "content-type: application/x-www-form-urlencoded"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "grant_type=refresh_token&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&refresh_token=%7ByourRefreshToken%7D"

  headers = { 'content-type': "application/x-www-form-urlencoded" }

  conn.request("POST", "/{yourDomain}/oauth/token", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/oauth/token")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["content-type"] = 'application/x-www-form-urlencoded'
  request.body = "grant_type=refresh_token&client_id={yourClientId}&client_secret=%7ByourClientSecret%7D&refresh_token=%7ByourRefreshToken%7D"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift theme={null}
  import Foundation

  let headers = ["content-type": "application/x-www-form-urlencoded"]

  let postData = NSMutableData(data: "grant_type=refresh_token".data(using: String.Encoding.utf8)!)
  postData.append("&client_id={yourClientId}".data(using: String.Encoding.utf8)!)
  postData.append("&client_secret={yourClientSecret}".data(using: String.Encoding.utf8)!)
  postData.append("&refresh_token={yourRefreshToken}".data(using: String.Encoding.utf8)!)

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/token")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

### Parameter definition

<table>
  <thead>
    <tr>
      <th><strong>Parameter</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td>Type of grant to execute.</td>
    </tr>

    <tr>
      <td><code>client\_id</code></td>
      <td>Application's client ID.</td>
    </tr>

    <tr>
      <td><code>client\_secret</code></td>
      <td>(Optional) Application's client secret. Only required for confidential applications using the Post token authentication method.</td>
    </tr>

    <tr>
      <td><code>refresh\_token</code></td>
      <td>Refresh token to exchange.</td>
    </tr>
  </tbody>
</table>

The response will include a new access token, its type, its lifetime (in seconds), and the granted scopes. If the scope of the initial token included `openid`, then a new ID token will be in the response as well.

```json lines theme={null}
{
      "access_token": "eyJ...MoQ",
      "expires_in": 86400,
      "scope": "openid offline_access",
      "id_token": "eyJ...0NE",
      "token_type": "Bearer"
    }
```

## Bypass MFA

If [Multi-factor Authentication (MFA)](/docs/secure/multi-factor-authentication) is enabled and the refresh token exchange flow fails, you can use the below Action code to bypass the <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> logic:

```js lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  // This action will allow you to bypass the MFA logic for the refresh token exchange flow.

  if (event.transaction.protocol === "oauth2-refresh-token") {
    return;
  }

  //  Add your MFA logic
  //  For example: api.multifactor.enable("any");
};
```

You can customize the code example when separate logic needs to be executed or bypassed depending on the current flow or protocol.

## Customize MFA

<Warning>
  Customizable MFA with the Resource Owner Password Grant, Embedded, or Refresh Token flows is in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s [Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0’s release stages, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages). To participate in the early access, contact [Auth0 Support](https://support.auth0.com/).
</Warning>

Customizable MFA allows users to enroll and challenge with factors of their choice that are supported by your application.

During authentication at the `oauth/token` endpoint, the response returns the `mfa_required` error that includes the `mfa_token` to use the MFA API and the `mfa_requirements` parameter with a list of authenticators:

```json theme={null}
{
  "error": "mfa_required",
  "error_description": "Multifactor authentication required",
  "mfa_token": "Fe26...Ha",
  "mfa_requirements": {
    "challenge": [
      { "type": "otp" },
      { "type": "push-notification" },
      { "type": "phone" },
      { "type": "recovery-code" }
      { "type": "email"} //can only work with challenge
    ]
  }
}
```

Use the `mfa_token` to call the [`mfa/authenticator`](/docs/api/authentication/muti-factor-authentication/list-authenticators) endpoint for a list of all factors the user has enrolled and match the same type your application supports.  You also need to obtain the matching `authenticator_type` to issue challenges:

```json theme={null}
[
  {
    "type": "recovery-code",
    "id": "recovery-code|dev_qpOkGUOxBpw6R16t",
    "authenticator_type": "recovery-code",
    "active": true
  },
  {
    "type": "otp",
    "id": "totp|dev_6NWz8awwC8brh2dN",
    "authenticator_type": "otp",
    "active": true
  }
]
```

Enforce the MFA challenge by calling the [`request/mfa/challenge`](/docs/api/authentication/muti-factor-authentication/request-mfa-challenge) endpoint.

Further customize your MFA flow with Auth0 Actions. To learn more, read [Actions Triggers: post-challenge - API Object](/docs/customize/actions/explore-triggers/password-reset-triggers/post-challenge-trigger/post-challenge-api-object).

## Learn more

* [Get Refresh Tokens](/docs/secure/tokens/refresh-tokens/get-refresh-tokens)
* [Revoke Refresh Tokens](/docs/secure/tokens/refresh-tokens/revoke-refresh-tokens)
* [Configure Refresh Token Expiration](/docs/secure/tokens/refresh-tokens/configure-refresh-token-expiration)
* [Lock.Android: Refresh JSON Web Tokens](/docs/libraries/lock-android/lock-android-refresh-jwt)


# Revoke Tokens
Source: https://auth0.com/docs/secure/tokens/revoke-tokens

Describes how to use tokens to control user access.

Once issued, <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> and <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip> cannot be revoked in the same way as cookies with session IDs for server-side sessions.

As a result, tokens should be issued for relatively short periods, and then [refreshed](/docs/secure/tokens/refresh-tokens) periodically if the user remains active.

## Learn more

* [Revoke Refresh Tokens](/docs/secure/tokens/refresh-tokens/revoke-refresh-tokens)
* [Token Best Practices](/docs/secure/tokens/token-best-practices)


# Token Best Practices
Source: https://auth0.com/docs/secure/tokens/token-best-practices

Lists best practices when using tokens in authentication and authorization.

Here are some basic considerations to keep in mind when using tokens:

* **Keep it secret. Keep it safe**: The signing key should be treated like any other credential and revealed only to services that need it.
* **Do not add sensitive data to the payload**: Tokens are signed to protect against manipulation and are easily decoded. Add the bare minimum number of claims to the payload for best performance and security.
* **Give tokens an expiration**: Technically, once a token is signed, it is valid forever—unless the signing key is changed or expiration explicitly set. This could pose potential issues so have a strategy for expiring and/or revoking tokens.
* **Embrace HTTPS**: Do not send tokens over non-HTTPS connections as those requests can be intercepted and tokens compromised.
* **Consider all of your authorization use cases**: Adding a secondary token verification system that ensures tokens were generated from your server may be necessary to meet your requirements.
* **Store and reuse:** Reduce unnecessary roundtrips that extend your application's attack surface, and optimize plan token limits (where applicable) by storing <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> obtained from the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip>. Rather than requesting a new token, use the stored token during future calls until it expires. How you store tokens will depend on the characteristics of your application: typical solutions include databases (for apps that need to perform API calls regardless of the presence of a session) and HTTP sessions (for apps that have an activity window limited to an interactive session). For an example of server-side storage and token reuse, see [Token Storage](/docs/secure/security-guidance/data-security/token-storage).

## Tokens vs. Cookies

Typically, single-page apps (such as React, Vue, and AngularJS + Node), native mobile apps (such as iOS and Android), and web APIs (written in Node, Ruby, ASP.NET, or a mix of those) benefit most from token-based authentication. Traditional, server-side web applications have traditionally used cookie-based authentication.

Token-based authentication is implemented by generating a token when the user authenticates and then setting that token in the `Authorization` header of each subsequent request to your API. You want that token to be something standard, like <Tooltip href="/docs/glossary?term=JSON+web+tokens">JSON web tokens</Tooltip> since you will find libraries in most of the platforms and you don't want to do your own crypto.

With both approaches, you can get the same amount of information from the user. That's controlled by the `scope` parameter sent in the login request (either using the Lock, our JavaScript library or a plain link). The `scope` is a parameter of the `.signin({scope: 'openid name email'})` method which ends up being part of the query string in the login request.

By default, we use `scope=openid` in token-based authentication to avoid having a huge token. You can control any standard <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) claims that you want to get in the token by adding them as scope values. For example, `scope=openid name email family_name address phone_number`. To learn more, see [Standard Claims on openid.net](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims).

You can mix token-based authentication with cookie-based authentication. Take into account that cookies will work just fine if the web app and the API are served from the same domain, so you might not need token based authentication. If you need to, we also return a JWT on the web app flow. Each of our SDKs will do it differently. If you want to call your APIs from JavaScript(instead of using the existing cookie), then you have to set the access tokens using Web Workers or JavaScript closures to handle token transmissions and storage. To learn more, read the Browser in-memory scenarios section of our [Token Storage](/docs/secure/security-guidance/data-security/token-storage) page.

## Refresh token usage

You can only get a <Tooltip href="/docs/glossary?term=Refresh+token">Refresh token</Tooltip> if you are implementing the following flows:

* [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/add-login-auth-code-flow)
* [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/add-login-using-the-authorization-code-flow-with-pkce)
* [Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow)
* [Device Authorization Flow](/docs/get-started/authentication-and-authorization-flow/device-authorization-flow)

If you limit offline access to your API, a safeguard configured via the **Allow Offline Access** switch at [Auth0 Dashboard > Applications > APIs > Settings](https://manage.auth0.com/#/apis), Auth0 will not return a Refresh Token for the API (even if you include the `offline_access` scope in your request).

Rules will run for the refresh token exchange. To execute special logic, you can look at the `context.protocol` property in your rule. If the value is `oauth2-refresh-token`, then the rule is running during the exchange.

When trying to get a refresh token, the <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> parameter is not available on the Rules context object. If you receive an error when attempting to add the audience parameter, verify that you do not have it set on the token.

If you try to do a redirect with `context.redirect`, the authentication flow will return an error.

If you have added custom claims to your tokens using a rule, the custom claims will appear in new tokens issued when using a refresh token for as long as your rule is in place. Although new tokens do not automatically inherit custom claims, rules run during the refresh token flow, so the same code will be executed. This allows you to add or change custom claims in newly-issued tokens without forcing previously-authorized applications to obtain a new refresh token.

### Refresh token limits

Auth0 limits the amount of active refresh tokens to 200 tokens per user per application. This limit only applies to active tokens. If the limit is reached and a new refresh token is created, the system revokes and deletes the oldest token for that user and application. Revoked tokens and expired tokens do not count against the limit.

#### Automated tests

Refresh tokens accumulate due to automated tests and are generally used for the test lifetime. To avoid a token stockpile subject to refresh token limits, you can use the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to remove unnecessary refresh tokens.

1. [Create a user](https://auth0.com/docs/api/management/v2#!/Users/post_users) with Management API. You will use this user for testing.
2. The response returns a `user_id` that you need to persist during tests to be used later.
3. Once tests are complete, [delete the user](https://auth0.com/docs/api/management/v2#!/Users/delete_users_by_id) through Management API. When the test user is deleted, the associated artifacts are also removed, including refresh tokens.

<Warning>
  For this use case, we don’t recommend using a static user ID. We do not recommended that you keep test users and artifacts, or cleaning the refresh tokens using the device credential endpoints as you could hit rate limits on the Management API. To learn more, read [Management API Endpoint Rate Limits.](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/management-api-endpoint-rate-limits)
</Warning>

If you want to keep the test user for future testing:

1. List the user’s refresh tokens using [Management API's device credential endpoint](https://auth0.com/docs/api/management/v2#!/Device_Credentials/get_device_credentials). The endpoint will return a maximum of 1000 tokens without specific order regardless of accumulated tokens or the use of pagination.
2. Delete those credentials [using the DELETE](https://auth0.com/docs/api/management/v2#!/Device_Credentials/delete_device_credentials_by_id) method.
3. If the user has more than 1k tokens, repeat listing and deleting tokens until no more tokens left for the user.

#### Configure Expiring Refresh Tokens

When users log into your application with Auth0, and when the `offline_access` is requested in the authorization request, a new refresh token is issued to the user. In the case users log out and in again with the same device, a new refresh token is issued. Depending on how your application stores and uses refresh tokens, the old refresh token from the first login might become obsolete, and your application will most likely use the new refresh tokens if both tokens are issued with the same audience. To learn more, read [Token Storage](/docs/secure/security-guidance/data-security/token-storage).

To avoid accumulating obsolete refresh tokens, even though the refresh token limit removes the oldest token first, we recommend you configure refresh token expiration. Both rotating and non-rotating (or reusable) refresh tokens can be configured to expire with either idle or absolute expiry values. Both expiration values help remove tokens that are not in active use and avoid accumulating tokens for the user. To learn more, read [Configure Refresh Token Expiration](/docs/secure/tokens/refresh-tokens/configure-refresh-token-expiration).

## JWT validation

We strongly recommend that you use middleware or one of the existing open source third-party libraries to parse and validate JWTs. At [JWT.io](https://jwt.io/#libraries-io), you can find libraries for various platforms and languages, such as .NET, Python, Java, Ruby, Objective-C, Swift, and PHP.

## Signing algorithms

The algorithm used to sign tokens issued for your application or API. A signature is part of a JWT and is used to verify that the sender of the token is who it says it is and to ensure that the message wasn't changed along the way. To learn more about JWTs, read [JSON Web Tokens](/docs/secure/tokens/json-web-tokens). To learn more about signatures, read [JSON Web Token Structure](/docs/secure/tokens/json-web-tokens/json-web-token-structure).

You can select from the following <Tooltip href="/docs/glossary?term=signing+algorithms">signing algorithms</Tooltip>:

* **RS256** (RSA Signature with SHA-256): An asymmetric algorithm, which means that there are two keys: one public key and one private key that must be kept secret. Auth0 has the private key used to generate the signature, and the consumer of the JWT retrieves a public key from the Metadata endpoints provided by Auth0 and uses it to [validate the JWT signature](/docs/secure/tokens/json-web-tokens/validate-json-web-tokens).
* **HS256** (HMAC with SHA-256): A symmetric algorithm, which means that there is only one private key that must be kept secret, and it is shared between the two parties. Since the same key is used both to generate the signature and to validate it, care must be taken to ensure that the key is not compromised. This private key (or secret) is created when you register your Application (**<Tooltip href="/docs/glossary?term=Client+Secret">Client Secret</Tooltip>**) or API (**Signing Secret**) and choose the HS256 signing algorithm.

The most secure practice, and our recommendation, is to use **RS256** because:

* With RS256, you are sure that only the holder of the private key (Auth0) can sign tokens, while anyone can check if the token is valid using the public key.
* With RS256, you can request a token that is valid for multiple audiences.
* With RS256, if the private key is compromised, you can implement key rotation without having to re-deploy your application or API with the new secret (which you would have to do if using HS256).
* With HS256, if the secret key is compromised you would have to redeploy the API with the new secret.

## Signing keys

It's good practice to assume that multiple signing keys could be present in your JWKS. This may seem unnecessary since the Auth0 JWKS endpoint typically contains a single signing key; however, multiple keys can be found in the JWKS when rotating signing certificates.

We recommend that you cache your signing keys to improve application performance and avoid running into rate limits, but you will want to make sure that if decoding a token fails, you invalidate the cache and retrieve new signing keys before trying **only one** more time.

## Learn more

* [Tokens](/docs/secure/tokens)
* [Token Storage](/docs/secure/security-guidance/data-security/token-storage)


# Troubleshoot
Source: https://auth0.com/docs/troubleshoot

Learn how to troubleshoot and solve common issues in Auth0.

<AuthDocsPipeline />

Auth0 offers multiple tiers of professional support as well as a thriving community of developers discussing their implementations. Troubleshooting topics can help solve common challenges.

***

## Get Support

##### Learn about Auth0’s support plans and procedures, service agreements, and community.

<Card title="Customer Support" href="/docs/troubleshoot/customer-support">
  Learn about the different levels of support at Auth0.
</Card>

***

## Troubleshoot

##### Explore solutions to common challenges.

<Card title="Commonplace Issues" href="/docs/troubleshoot/basic-issues">
  Learn fundamental troubleshooting tactics.
</Card>

<Card title="Authentication Issues" href="/docs/troubleshoot/authentication-issues">
  Troubleshoot login and other authentication issues.
</Card>

<Card title="Integration and Extensibility Issues" href="/docs/troubleshoot/integration-extensibility-issues">
  Troubleshoot issues integrating with third-party solutions.
</Card>

<Card title="Deploy and Monitor Issues" href="/docs/troubleshoot/deploy-monitor-issues">
  Troubleshoot issues with deployment and monitoring.
</Card>

<Card title="Troubleshooting Tools" href="/docs/troubleshoot/troubleshooting-tools">
  Learn how to generate and analyze HAR files, debug, and inspect tokens.
</Card>

<Card title="Debugging Best Practices" href="/docs/troubleshoot/debugging-best-practices">
  Explore best practices for debugging your Auth0 implementation.
</Card>

<Card title="Error Handling Best Practices" href="/docs/troubleshoot/error-handling-best-practices">
  Explore best practices for handling error conditions.
</Card>

<Card title="Performance Best Practices" href="/docs/troubleshoot/performance-best-practices">
  Learn about best practices for performance.
</Card>

<Card title="General Usage and Operations Best Practices" href="/docs/troubleshoot/general-usage-and-operations-best-practices">
  Explore best practices for general Auth0 usage and operation.
</Card>

***

## Auth0 Product Lifecycle

##### Discover our iterative approach to product delivery.

<Card title="Product Lifecycle" href="/docs/troubleshoot/product-lifecycle">
  Learn how we’re constantly improving.
</Card>


# Customer Support
Source: https://auth0.com/docs/troubleshoot/customer-support

Describes the different types of support options provided by Auth0.

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/troubleshoot/customer-support/support-plans">Support Plans</a></td>
      <td>About different levels of Auth0 support.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/customer-support/self-service-support">Self Service Support</a></td>
      <td>Tools for customers to troubleshoot their issues.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/customer-support/support-channels">Support Channels</a></td>
      <td>The different ways to contact Auth0 support.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/customer-support/support-plans">Support Procedures</a></td>
      <td>About defect resolution and unsupported requests.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/customer-support/support-plans">Support Hours</a></td>
      <td>About the Auth0 support hours.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/customer-support/responsible-disclosure-program-security-support-tickets">Whitehat Security Support Tickets</a></td>
      <td>How to report a security issue.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/customer-support/product-support-matrix">Product Support Matrix</a></td>
      <td>About support coverage for browsers, operating systems, and Auth0 libraries and SDKs.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/customer-support/services-level-descriptions">Service Levels</a></td>
      <td>About Auth0 service levels and service level agreements (SLAs) for public and private cloud deployments.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/customer-support/open-and-manage-support-tickets">Open and Manage Support Tickets</a></td>
      <td>How to open and manage Auth0 support tickets.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/customer-support/manage-subscriptions">Manage Subscriptions</a></td>
      <td>How to manage your Auth0 subscription.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/customer-support/reset-account-passwords">Reset Account Passwords</a></td>
      <td>How to change your password to your Auth0 account.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/customer-support/software-updates">Software Updates</a></td>
      <td>How your version of Auth0 updates.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/customer-support/versioning-strategy">Auth0 Versioning Strategy</a></td>
      <td>About Auth0's software versioning scheme.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/customer-support/operational-policies">Operational Policies</a></td>
      <td>About Auth0 operational policies including billing, data export and transfer, API endpoints, load and penetration testing, migrations, rate limits and much more.</td>
    </tr>

    <tr>
      <td><a href="https://auth0.com/changelog">Changelog</a></td>
      <td>About the latest updates and additions to the Auth0 platform.</td>
    </tr>
  </tbody>
</table>


# API Best Practices
Source: https://auth0.com/docs/troubleshoot/api-best-practices

Describes best practices and standards for your APIs.

When you integrate with Auth0 services, we recommend you configure your APIs according to current networking standards. Review the following DNS resolutions, Transport Layer Security (TLS) configurations, and HTTP optimization strategies designed to make sure your application handles infrastructure changes and maintains resilient connections to Auth0 services. Following these standards for DNS, TLS, and HTTP ensures compatibility with our global delivery network, improves request reliability through proper retry logic, and maintains the security of your authentication traffic.

## DNS and hostname resolution

### Use Auth0 provided hostnames

Always connect to Auth0 using the provided hostnames, not the underlying IP address. Auth0's infrastructure depends on DNS-based traffic steering for load balancing, cloud and CDN routing, and regions failover. We recommend against using DNS-based filtering since naming of cloud infrastructure may change over time.

### Respect DNS Time to Live (TTL)

Always honor the [DNS TTL](https://www.ateam-oracle.com/dns-ttls-considerations) provided by DNS. TTL values are often low (e.g. 30 to 300 seconds) for applications to respond to infrastructure changes quickly.

### DNS caching

Use your operating system DNS resolver where possible. When using your own (application-level) resolver, ensure it caches responses no longer than the TTL.

### Support multiple A/AAAA records

Auth0 may return multiple IP addresses for a given hostname. APIs should distribute connections across returned IPs through round-robin or randomized assignment. Set to failover immediately if one address is unreachable.

## Transport Layer Security (TLS)

Auth0 only supports HTTP requests with TLS. We recommend you use the latest versions:

* **TLS 1.3** strongly recommended
* **TLS 1.2**
* **TLS 1.1 and below are not supported**

### Use modern cipher suites

Avoid using highly customized client cipher suite configurations. Use default secure settings from your runtime unless you have compliance constraints (e.g., FIPS). Clients with limited cipher suite support may be rejected.

To review the available cyphers, read [TLS (SSL) Versions and Ciphers](/docs/customize/custom-domains/self-managed-certificates/tls-ssl).

### Support Server Name Indication (SNI)

APIs must use SNI TLS extension on all HTTPS traffic to Auth0. Traffic without SNI will not be accepted.

#### Honor certificate validation

Do **not**:

* Disable certificate validation
* Pin certificates

Auth0 renews and replaces certificates automatically and frequently. Certificate pinning can cause service disruptions.

#### Allow intermediate certificate rotation

Our certificate chain may change periodically. Ensure your TLS client:

* Trusts any valid, publicly-trusted certificate authority in the OS trust store by default
* Updates the OS trust store as part of regular updates
* Does not pin intermediate certificates
* Rejects only invalid chains

#### Enable TLS session resumption and reuse

Allow TLS session tickets or session IDs in HTTP/2. This reduces the TLS handshake overhead.

## HTTP

### Use a modern HTTP protocol

Use [HTTP/2](https://www.rfc-editor.org/rfc/rfc9113) or [HTTP/3](https://httpwg.org/specs/rfc9114.html). These provide connection multiplexing, use HTTP header compression and require less TCP connections.  If your client supports HTTP/2 automatically, use HTTPS endpoints and let the client negotiate HTTP/2 or higher.

<Callout icon="file-lines">
  Avoid HTTP/1.1 unless required. HTTP/1.1 is fully supported but is less efficient. Use is discouraged unless necessary.
</Callout>

### Enable and reuse persistent connections

Configure your API to reuse HTTP connections to reduces request latency and improve reliability. Review the following recommended settings:

* Keep connections open for up 300 seconds
* Limit max idle connections to a reasonable number
* Avoid creating a new HTTP API object per request to leverage existing connections
* Rotate connections periodically to refresh connection health

### Request Retries

We recommend implementing request retries for operations that are safe to retry: [idempotent requests](https://developer.mozilla.org/en-US/docs/Glossary/Idempotent).

When retrying due to transient network or server-side errors, inspect the HTTP `Retry-After` response header, which should determine how long an application should wait before making another request.

Example: `Retry-After: 300`

If the header is present, wait the specified number of seconds before retrying a request. Adherance to the `Retry-After` ensures fair usage and prevents cascading failures or rate-limiting.

If Retry-After is not present, use [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) to determine the retry interval. Do not try more than three attempts.

## Auth0 SDKs

We recommend the following best practices when configuring your environment or application to use Auth0 SDKs.

### Use official Auth0 SDKs

Prioritize [official or referenced](docs/libraries) SDKs for your platform and language. Use official Auth0 SDKs rather than building custom HTTP application or API integrations. These libraries are maintained to adhere to the best practices, abstracting the complexity of low-level networking and security compliance.

### Choose the applicable SDK

Auth0 provides specialized libraries for different integration patterns. Ensure you select the SDK that matches your architectural use case:

* **Authentication and Authorization SDKs**: Use these SDKs for end user login and obtaining tokens. Choose the SDK based on your application type:
  * **Single-Page Applications (SPA)**: JS/TS libraries handle token lifecycles and PKCE flows in the browser (e.g. [React](https://github.com/auth0/auth0-react), [Vue](https://github.com/auth0/auth0-vue), [Angular](https://github.com/auth0/auth0-angular)).
  * **Regular Web Applications**: Server-side libraries manage sessions and cookie-based transactions (e.g. [Node.js](https://github.com/auth0/node-auth0), [ASP.NET Core](https://github.com/auth0/auth0-aspnetcore-authentication), [PHP](https://github.com/auth0/auth0-PHP)).
  * **Native/Mobile Applications**: Platform-native libraries interact with system browsers and secure storage ([Swift](https://github.com/auth0/Auth0.swift), [Kotlin](https://github.com/auth0/Auth0.android), [React Native](https://github.com/auth0/react-native-auth0)).
* **Backend Service and API**: Validates incoming Access Tokens in your APIs. These libraries handle cryptographic signature verification and caching of [JSON Web Key Sets (JWKS)](docs/secure/tokens/json-web-tokens/json-web-key-sets#json-web-key-sets).
* **Management API SDKs**: Programatic performance of administrative tasks such as creating new users and rotating Client Secrets. Handles rate-limiting headers and retry logic.

By using official SDKs, you ensure your integration automatically supports:

* Resilient HTTP connection pooling and keep-alive settings.
* Correct implementation of retry logic with exponential backoff and `Retry-After` header respect.
* Adherence to current TLS and security standards.


# Troubleshoot Authentication Issues
Source: https://auth0.com/docs/troubleshoot/authentication-issues

Learn where to look for steps to troubleshoot authentication and authorization issues such as API calls, login, logout, user profiles, MFA and SAML

* [Check API Calls](/docs/troubleshoot/authentication-issues/check-api-calls) - Learn how to check API calls to troubleshoot issues.
* [Check Login and Logout Issues](/docs/troubleshoot/authentication-issues/check-login-and-logout-issues) - Learn how to check login and logout to troubleshoot issues.
* [Check User Profiles](/docs/troubleshoot/authentication-issues/check-user-profiles) - Learn how to check user profiles to troubleshoot issues.
* [Troubleshoot Role-Based Access Control and Authorization](/docs/troubleshoot/authentication-issues/troubleshoot-rbac-authorization) - Describes solutions to common issues experienced when implementing role-based access control (RBAC) using the Authorization Core feature set.
* [Troubleshoot Multi-Factor Authentication](/docs/troubleshoot/authentication-issues/troubleshoot-mfa-issues) - Describes basic troubleshooting for <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> issues with end-users.
* [Troubleshoot SAML Configurations](/docs/troubleshoot/authentication-issues/troubleshoot-saml-configurations) - Describes troubleshooting for <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> configuration issues.
* [Troubleshoot SAML Errors](/docs/troubleshoot/authentication-issues/saml-errors) - Describes troubleshooting for common SAML errors.
* [Self Change Password Errors](/docs/troubleshoot/authentication-issues/self-change-password-errors) - Describes error codes and possible solutions that can occur with the self change password API.
* [Troubleshoot the Authorization Extension](/docs/troubleshoot/authentication-issues/troubleshoot-authorization-extension) - Learn how to troubleshoot the Authorization Extension.
* [Troubleshoot Renew Tokens When Using Safari](/docs/troubleshoot/authentication-issues/renew-tokens-when-using-safari) - Learn how to troubleshoot Safari browser behavior and authentication.

## Learn more

* [Monitor Auth0](/docs/deploy-monitor/monitor)
* [Open and Manage Support Tickets](/docs/troubleshoot/customer-support/open-and-manage-support-tickets)
* [Troubleshoot Basic Issues](/docs/troubleshoot/basic-issues)
* [Troubleshoot Integration and Extensibility Issues](/docs/troubleshoot/integration-extensibility-issues)
* [Troubleshooting Tools](/docs/troubleshoot/troubleshooting-tools)


# Check API Calls
Source: https://auth0.com/docs/troubleshoot/authentication-issues/check-api-calls

Learn how to check API calls to troubleshoot issues.

## Check Management API calls

* Do you have a [Management API Access Token](/docs/secure/tokens/access-tokens/management-api-access-tokens)?
* Did the <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip> expire?
* Did the access token contain the scopes needed for the call you made?
* If a rule adjusts the scopes in the access token or checks whether specific users are allowed to have the scopes, have you checked the rule to make sure it is executing correctly?
* Get the access token from a [HAR file](/docs/troubleshoot/troubleshooting-tools/generate-and-analyze-har-files) and test it in the [Auth0 Management API Explorer](https://auth0.com/docs/api/management/v2) to see if it works there.

  <Warning>
    Before sharing a HAR file with anyone (including Auth0), ensure that you remove or obfuscate all sensitive data, such as:

    * Confidential user information
    * Personal identifiable information (PII)
    * Confidential application information

    To learn more, read the following articles on [Auth0 Community](https://community.auth0.com):

    * [Sanitizing HTTP Traces](https://community.auth0.com/t/sanitizing-http-traces/119488)
    * [How to Sanitize an HTTP Trace File Automatically](https://community.auth0.com/t/how-to-sanitize-a-http-trace-file-automatically/120583)
    * [How to Manually Redact Sensitive Information](https://community.auth0.com/t/how-to-manually-redact-sensitive-information/122554)
    * [HAR File is Too Large to Upload to the Support Case](https://community.auth0.com/t/har-file-is-too-large-to-upload-to-the-support-case/122488)
  </Warning>
* If you are calling the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> from an application that authenticates with [Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow), note that rules are not executed in this context. For functionality similar to a Rule, an Action in the [Machine to Machine Flow](/docs/customize/actions/explore-triggers/machine-to-machine-trigger) on the `credentials-exchange` trigger can be used in this context instead.

## Check other API calls

* Check in the HAR file if the access token contains correct scopes to call the API.

  <Warning>
    Before sharing a HAR file with anyone (including Auth0), ensure that you remove or obfuscate all sensitive data, such as:

    * Confidential user information
    * Personal identifiable information (PII)
    * Confidential application information

    To learn more, read the following articles on [Auth0 Community](https://community.auth0.com):

    * [Sanitizing HTTP Traces](https://community.auth0.com/t/sanitizing-http-traces/119488)
    * [How to Sanitize an HTTP Trace File Automatically](https://community.auth0.com/t/how-to-sanitize-a-http-trace-file-automatically/120583)
    * [How to Manually Redact Sensitive Information](https://community.auth0.com/t/how-to-manually-redact-sensitive-information/122554)
    * [HAR File is Too Large to Upload to the Support Case](https://community.auth0.com/t/har-file-is-too-large-to-upload-to-the-support-case/122488)
  </Warning>
* Check if the response to the `/authorize` endpoint call contains a scopes object. If so, check if the returned scopes are different from the requested scopes.
* Make sure your API can [validate the Access Token](/docs/secure/tokens/access-tokens/validate-access-tokens). It should validate the <Tooltip href="/docs/glossary?term=audience">audience</Tooltip>, issuer, client (if any), signature algorithm, signature, claims and permissions.
* If you experience errors with access token expiration, they could be caused by clock skew differences manifested across different systems or even different language libraries, such as Java and Node.js. This can be handled by running NTP on servers and configuring a clock skew tolerance in libraries used to validate tokens such as [jwt.verify](https://github.com/auth0/node-jsonwebtoken#jwtverifytoken-secretorpublickey-options-callback).

<Callout icon="file-lines">
  See [the Monitoring page](/docs/deploy-monitor/monitor) for more details on each of the log events that can help you troubleshoot issues.
</Callout>

## Learn more

* [Call Your API Using the Authorization Code Flow with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/call-your-api-using-the-authorization-code-flow-with-pkce)
* [Call Your API Using the Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/call-your-api-using-the-authorization-code-flow)
* [Call Your API Using the Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow/call-your-api-using-the-client-credentials-flow)
* [Call Your API Using the Device Authorization Flow](/docs/get-started/authentication-and-authorization-flow/device-authorization-flow/call-your-api-using-the-device-authorization-flow)


# Check Login and Logout Issues
Source: https://auth0.com/docs/troubleshoot/authentication-issues/check-login-and-logout-issues

Learn how to check login and logout to troubleshoot issues

Here are things to check to help you narrow down when issues occur during login and logout.

## Login Issues

### Is the user prompted for login credentials?

* Does the HAR file show a call to the <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip> (`/authorize` endpoint)?

  <Warning>
    Before sharing a HAR file with anyone (including Auth0), ensure that you remove or obfuscate all sensitive data, such as:

    * Confidential user information
    * Personal identifiable information (PII)
    * Confidential application information

    To learn more, read the following articles on [Auth0 Community](https://community.auth0.com):

    * [Sanitizing HTTP Traces](https://community.auth0.com/t/sanitizing-http-traces/119488)
    * [How to Sanitize an HTTP Trace File Automatically](https://community.auth0.com/t/how-to-sanitize-a-http-trace-file-automatically/120583)
    * [How to Manually Redact Sensitive Information](https://community.auth0.com/t/how-to-manually-redact-sensitive-information/122554)
    * [HAR File is Too Large to Upload to the Support Case](https://community.auth0.com/t/har-file-is-too-large-to-upload-to-the-support-case/122488)
  </Warning>
* Is the connection enabled for the application?
* Is the remote authorization service available?
* If using the [Auth0 Universal Login Page](/docs/authenticate/login/auth0-universal-login), try turning off customization and see if authentication works. If login works without your customizations, review your <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> Page customization code.

### Is an error message shown after entering credentials?

* Can you test login another way to ensure credentials are correct?
* If password expiration is a possibility, check if password has expired.
* Check your browser's developer tools or web inspector console for errors in the flow before returning to Auth0.
* Check the HAR file - does it show a return to Auth0 (`/login/callback` endpoint)?

  <Warning>
    Before sharing a HAR file with anyone (including Auth0), ensure that you remove or obfuscate all sensitive data, such as:

    * Confidential user information
    * Personal identifiable information (PII)
    * Confidential application information

    To learn more, read the following articles on [Auth0 Community](https://community.auth0.com):

    * [Sanitizing HTTP Traces](https://community.auth0.com/t/sanitizing-http-traces/119488)
    * [How to Sanitize an HTTP Trace File Automatically](https://community.auth0.com/t/how-to-sanitize-a-http-trace-file-automatically/120583)
    * [How to Manually Redact Sensitive Information](https://community.auth0.com/t/how-to-manually-redact-sensitive-information/122554)
    * [HAR File is Too Large to Upload to the Support Case](https://community.auth0.com/t/har-file-is-too-large-to-upload-to-the-support-case/122488)
  </Warning>

  * If not, check that the identity provider has the correct callback URL for Auth0.

### Is a login session established for the user at the authorization server?

* To test this, open a second tab in the same browser and go to the same URL. Are you prompted to log in again?

  * If you're not prompted to log in, a session is there.

### Is a log entry created in your Auth0 Logs?

* If no log entry was created the authentication transaction did not complete or return to Auth0.
* Check the response from the authorization server for error messages.
* Check authorization server logs (if possible) for errors.

### Is an entry created in Auth0 user’s screen with all correct profile info?

* If not, check the response from authorization server in the HAR file. It may not be returning information about the user

  <Warning>
    Before sharing a HAR file with anyone (including Auth0), ensure that you remove or obfuscate all sensitive data, such as:

    * Confidential user information
    * Personal identifiable information (PII)
    * Confidential application information

    To learn more, read the following articles on [Auth0 Community](https://community.auth0.com):

    * [Sanitizing HTTP Traces](https://community.auth0.com/t/sanitizing-http-traces/119488)
    * [How to Sanitize an HTTP Trace File Automatically](https://community.auth0.com/t/how-to-sanitize-a-http-trace-file-automatically/120583)
    * [How to Manually Redact Sensitive Information](https://community.auth0.com/t/how-to-manually-redact-sensitive-information/122554)
    * [HAR File is Too Large to Upload to the Support Case](https://community.auth0.com/t/har-file-is-too-large-to-upload-to-the-support-case/122488)
  </Warning>
* If you're using rules, check your rules scripts for issues.
* If you're using a custom database connection, check your database action scripts for issues.
* If you're using LDAP, check the profile mapper script (`profileMapper.js`) for issues.
* Check your social connection configurations for what profile information is requested.

### Does the HAR file show a token or assertion returned to application?

* Look in the [HAR file](/docs/troubleshoot/troubleshooting-tools/generate-and-analyze-har-files) for the call to your application callback URL.

  <Warning>
    Before sharing a HAR file with anyone (including Auth0), ensure that you remove or obfuscate all sensitive data, such as:

    * Confidential user information
    * Personal identifiable information (PII)
    * Confidential application information

    To learn more, read the following articles on [Auth0 Community](https://community.auth0.com):

    * [Sanitizing HTTP Traces](https://community.auth0.com/t/sanitizing-http-traces/119488)
    * [How to Sanitize an HTTP Trace File Automatically](https://community.auth0.com/t/how-to-sanitize-a-http-trace-file-automatically/120583)
    * [How to Manually Redact Sensitive Information](https://community.auth0.com/t/how-to-manually-redact-sensitive-information/122554)
    * [HAR File is Too Large to Upload to the Support Case](https://community.auth0.com/t/har-file-is-too-large-to-upload-to-the-support-case/122488)
  </Warning>
* Find the <Tooltip href="/docs/glossary?term=ID+Token">ID Token</Tooltip> (`id_token`) and check if it has the information needed by the application.

### If you decode the token or assertion does it have information you expect?

* View <Tooltip href="/docs/glossary?term=JWTs">JWTs</Tooltip> with [JWT.io](http://jwt.io).
* View <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> assertions with [SAMLTool.io](http://samltool.io).

### If the logged in user cannot access another application with Single Sign-on

1. Is the user trying to login to the second application from the same browser as their initial login?
2. Go to your [Tenant Settings > Advanced Settings](https://manage.auth0.com/#/tenant/advanced) and check the **Log In Session Management** settings. Was the second login attempt within the timeout periods?
3. Check the value passed as the `prompt` parameter in `/authorize` call.
4. Is the connection used to log in to the first application enabled for the second application?
5. Did the second application receive all the necessary user profile information?
6. If using a mobile device, you'll need to use a browser-based flow. For more information, see [Best Practices](/docs/authenticate/login/native-login).

### Check application logs

* Do your application logs show any errors?
* Did the application receive all the information it needs, such as groups or user profile attributes?

## Logout issues

* Did you add your logout redirect URLs to the allow list? If you are using a redirect URL in a logout call it must be registered in either the tenant or application settings.
* If you need federated logout, did you append the `?federated` parameter to the logout call?
* Make sure that the logout redirect URL is different from the login callback URL.
* Make the logout redirect URL an anonymous page (not protected by login) so that redirects to the logout redirect URL do not immediately trigger a login, which may confuse users.


# Check User Profiles
Source: https://auth0.com/docs/troubleshoot/authentication-issues/check-user-profiles

Learn how to check user profiles to troubleshoot issues

1. Is user profile information correct at the source (authorization server)?
2. Generate and check the [HAR file](/docs/troubleshoot/troubleshooting-tools/generate-and-analyze-har-files), look for an `id_token`.

   <Warning>
     Before sharing a HAR file with anyone (including Auth0), ensure that you remove or obfuscate all sensitive data, such as:

     * Confidential user information
     * Personal identifiable information (PII)
     * Confidential application information

     To learn more, read the following articles on [Auth0 Community](https://community.auth0.com):

     * [Sanitizing HTTP Traces](https://community.auth0.com/t/sanitizing-http-traces/119488)
     * [How to Sanitize an HTTP Trace File Automatically](https://community.auth0.com/t/how-to-sanitize-a-http-trace-file-automatically/120583)
     * [How to Manually Redact Sensitive Information](https://community.auth0.com/t/how-to-manually-redact-sensitive-information/122554)
     * [HAR File is Too Large to Upload to the Support Case](https://community.auth0.com/t/har-file-is-too-large-to-upload-to-the-support-case/122488)
   </Warning>
3. Decode the `id_token` at [JWT.io](https://jwt.io) to see if it has the correct information.
4. Check any custom database scripts or rule logic.
5. Check if you called `/tokeninfo` endpoint and have a custom domain configured within Auth0. If so, you need to use `/userinfo` endpoint instead
6. Check if you called `/userinfo` endpoint properly. You should pass an access token. You should call this endpoint with the default Auth0 domain even if the tenant has a custom domain enabled.
7. Check if you specified the correct [scope](/docs/get-started/apis/scopes) to get an Access Token.

<Callout icon="file-lines">
  See [the Monitoring page](/docs/deploy-monitor/monitor) for more details on each of the log events that can help you troubleshoot issues.
</Callout>

## Learn more

* [User Profiles](/docs/manage-users/user-accounts/user-profiles)
* [Normalized User Profiles](/docs/manage-users/user-accounts/user-profiles/normalized-user-profiles)
* [User Profile Structure](/docs/manage-users/user-accounts/user-profiles/user-profile-structure)


# Troubleshoot Renew Tokens When Using Safari
Source: https://auth0.com/docs/troubleshoot/authentication-issues/renew-tokens-when-using-safari

Issues with token renewal in Safari when ITP is enabled.

In some cases, renewing tokens with silent authentication does not work as expected with the latest version of the Safari browser. Recent versions of the Safari browser introduced a new feature called [Intelligent Tracking Prevention (ITP)](https://webkit.org/blog/category/privacy/). ITP is designed to prevent websites from tracking user activity across multiple websites. By default, ITP is active. You can determine if the Safari version you are using has ITP by going to the **Preferences > Privacy** tab and seeing if the **Prevent cross-site tracking** option is checked.

## ITP and browser behavior

Enabling ITP causes the browser to behave as if you had disabled third-party cookies in the browser, which makes it impossible to obtain a new token without displaying anything to the user. This is akin to the way <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) uses iframes for handling [sessions](/docs/manage-users/sessions) in SPAs.

In the SPA SDK (which is our recommendation) `getTokenSilently` performs [silent authentication](/docs/authenticate/login/configure-silent-authentication) unless you configure the SDK to use rotating <Tooltip href="/docs/glossary?term=refresh+tokens">refresh tokens</Tooltip>.

## Workarounds

Recent advancements in user privacy controls in browsers adversely impact the user experience by preventing access to third-party cookies. You can use [Refresh Token Rotation](/docs/secure/tokens/refresh-tokens/refresh-token-rotation) as an alternative that provides a secure method for using refresh tokens in SPAs while providing end-users with seamless access to resources without the disruption in UX caused by browser privacy technology like ITP.

Alternatively, you can work around the issues posed by ITP by using Auth0's [custom domains](/docs/customize/custom-domains) functionality, particularly if the <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip> lives on a subdomain of the application's website domain. For example, if your application is hosted on **example.com**, the custom domain would need to be of the format **subdomain.example.com**.

## ITP debug mode

[Safari Technology Preview](https://developer.apple.com/safari/technology-preview/) offers an "Intelligent Tracking Prevention Debug Mode" that you can use to troubleshoot ITP issues. You can find instructions on how to debug ITP in [this blog post from WebKit](https://webkit.org/blog/8387/itp-debug-mode-in-safari-technology-preview-62/).

**NOTE**: The instructions mention how to permanently classify a custom domain as having tracking abilities for testing purposes. In later versions of Safari Technology Preview, though, the domain to store the User Defaults for this setting changed from `com.apple.SafariTechnologyPreview` to `com.apple.WebKit.Networking`. If you are having trouble with the commands mentioned in the instructions, try these:

* Classify a site as having tracking abilities:
  `defaults write com.apple.WebKit.Networking ResourceLoadStatisticsManualPrevalentResource example.com`
* Inspect the setting:
  `defaults read com.apple.WebKit.Networking ResourceLoadStatisticsManualPrevalentResource`
* Delete the setting:
  `defaults delete com.apple.WebKit.Networking ResourceLoadStatisticsManualPrevalentResource`

You will need to restart Safari Technology Preview every time you make changes for the settings to take effect.


# Troubleshoot SAML Errors
Source: https://auth0.com/docs/troubleshoot/authentication-issues/saml-errors

Describes how to troubleshoot common SAML related errors.

## Invalid request - connection disabled

### Cause

This message indicates that the application doesn't have an active connection associated.

### Solution

1. Go to [Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise).
2. Click **SAML**.
3. Click on the connection you want to check.
4. Click the **Applications** tab.
5. Enable at least one application (if you don't see any in the list, you will need to [create an application](/docs/get-started/applications) before proceeding).

## IdP-Initiated Default App Not Configured

### Cause

This error appears if you haven't provided the necessary information to support <Tooltip href="/docs/glossary?term=IdP">IdP</Tooltip>-initiated login flows.

### Solution

1. Go to [Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise).
2. Click **SAML**
3. Click on the connection you want to check.
4. Switch to the **IdP-Initiated SSO** tab.
5. Select **Accept Requests** and select the **Default Application** and the **Response Protocol** used by that application, and (optionally) specify any additional parameters you want to be passed to the application.
6. Click **Save Changes**.

<Card title="Troubleshooting SP-initiated login">
  If you see this error when using a SP-initiated flow, one of the following is missing or empty:

  * The `RelayState` parameter
  * The `InResponseTo` attribute in the SAML response

  If these are missing or empty, Auth0 treats the login as IdP-initiated. You can fix this error by checking your configuration to ensure that both fields are populated and returned appropriately.
</Card>

## Missing RelayState parameter

### Cause

This error occurs when the identity provider doesn't return the `RelayState` parameter along with its response.

### Solution

Work with the identity provider to ensure that it returns the `RelayState` parameter.

## Audience is Invalid

This error occurs if the value of the `audience` element from the identity provider's <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> response doesn't match the value expected by Auth0. Auth0 expects the value to be the Entity ID for the connection.

### Solution

1. Go to [Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise).
2. Click **SAML**.
3. Click on the connection you want to check.
4. On the **Setup** tab, under the **Common Settings** section, your **Entity ID** is the second parameter provided. Make sure that the identity provider sends the correct `audience` value in the SAML response.

## Incorrect protocol specified

There is an incorrect response protocol on the **IdP-Initiated** tab. The response protocol is the one used between Auth0 and the Application (not the remote identity provider). For example, if you set this value to **SAML** when your application expects **<Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect** or **<Tooltip href="/docs/glossary?term=WS-Fed">WS-Fed</Tooltip>** results in errors due to the incorrect configuration.

### Solution

1. Go to [Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise).
2. Click **SAML**.
3. Click on the connection you want to check.
4. On the **Settings** tab, check the value you have set in the **Response Protocol** field.

## User isn't logged out from the IdP

When ADFS is configured as SAML IdP, if the ADFS is relaying party trust `Name ID` attribute isn't mapped the logout flow fails. For example, with the federated parameter `v2/logout?federated&...` user isn't redirected to the ADFS SAML logout endpoint but redirects back to application callback URL directly. As a consequence, the user isn't logged out from the IdP in that case.

### Solution

Add the `Name ID` attribute as a rule on the SAML Relaying Party Trust.


# Self Change Password Errors
Source: https://auth0.com/docs/troubleshoot/authentication-issues/self-change-password-errors

Error messages for the self change password API

Below you will find the errors codes and possible solutions to various errors that can occur with the self change password API.

## Error Format

Error messages are returned in the standard format:

## Error Codes

### invalid\_request

This error results when you supply invalid parameters. Error messages will describe the issue such as a required parameter or invalid format.

### invalid\_user\_password

This error results from a bad `username`/`email` and `old_password` combination being sent. Retry the request with the correct username and `old_password`.

### change\_password\_error

This error results from various conditions with the underlying <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>. Generally, this happens when you are using a custom database and have not implemented the change password script.


# Troubleshoot Authorization Extension
Source: https://auth0.com/docs/troubleshoot/authentication-issues/troubleshoot-authorization-extension

Learn how to troubleshoot the Authorization Extension.

<Callout icon="file-lines">
  Auth0 provides two ways to implement role-based access control (RBAC), which you can use in place of or in combination with your API's own internal access control system:

  * [Authorization Core](/docs/manage-users/access-control/rbac)
  * [Authorization Extension](/docs/customize/extensions/authorization-extension)

  The Authorization Core feature set matches the functionality of the Authorization Extension, improves performance and scalability, and provides a more flexible RBAC system than the Authorization Extension.

  Currently, both implement the key features of RBAC and allow you to restrict the custom scopes defined for an API to those that have been assigned to the user as permissions.
</Callout>

The following issues are some you might see when setting up the Authorization Extension, as well as some tips to help you identify the cause.

## The authentication results in a token contain group information but not roles or permissions information

If this happens, chances are that you created roles and permissions for one application, but your users are authenticating using another application. For example, let's say that you created all your roles/permissions against Website A. However, you also create another website application in Auth0 for Website B. Then, you use the `client_id` and `client_secret` for Website B, instead of those for Website A, in your app.

Alternatively, you might see this if you click the **Try Connection** button in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> on a Connection that contains one of your users. This will execute an authentication flow using the Auth0 global application, but this is not the same as the application you configured in the extension.

## Application is not shown in the drop-down menu when setting up the extension

The supported application types for the Authorization extension are:

* Native apps
* Single-page web apps
* Regular web apps

Applications with no type assigned and machine to machine applications are not supported.

## After upgrading to v2, users get an error upon login

If you see the error `You are not allowed to access this application`, most probably there is some conflict with the old rule. Turn off the persistence settings, delete the existing rule, re-enable the settings, and test again.

## Learn more

* [Install Authorization Extension](/docs/customize/extensions/authorization-extension/install-authorization-extension)
* [Configure Authorization Extension](/docs/customize/extensions/authorization-extension/configure-authorization-extension)
* [Set Up Users in Authorization Extension Dashboard](/docs/customize/extensions/authorization-extension/set-up-authorization-extension-users)
* [Enable API Access to Authorization Extension](/docs/customize/extensions/authorization-extension/enable-api-access-to-authorization-extension)
* [Import and Export Authorization Extension Data](/docs/customize/extensions/authorization-extension/import-and-export-authorization-extension-data)
* [Use Rules with the Authorization Extension](/docs/customize/extensions/authorization-extension/use-rules-with-the-authorization-extension)


# Troubleshoot Multi-Factor Authentication Issues
Source: https://auth0.com/docs/troubleshoot/authentication-issues/troubleshoot-mfa-issues

Describes basic troubleshooting of MFA issues for your users.

## User issues

### If you do not have your mobile device or your mobile device is turned off

If you have lost your device, you can finish authentication using the recovery code provided when you first signed up.

1. Enter your email and password to log in, and click the **Use the recovery code** link.
2. Enter your recovery code.

If you no longer have your recovery code, you will not be able to log in. Contact your system administrator for help accessing your account.

### If you forget your password

If you have forgotten your password, click the **Don't remember your password?** link located underneath the email and password fields. Then, enter your email address to receive an email containing a link you can use to reset your password.

### If your transaction expires

When logging in via <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip>, there is a five-minute maximum between providing your first and second factors. You can see how much time has elapsed since you logged in using the first factor by checking the timestamp on the messages provided.

If more than five minutes have elapsed, you will need to log in again and obtain a new code or notification.

If you are requesting SMS messages, make sure you are not exceeding rate limits.

### If you need to remove or delete MFA from a user in your tenant

If you need to remove, delete, or reset MFA for a user, you should [reset MFA](/docs/secure/multi-factor-authentication/reset-user-mfa).

## SMS-related issues

### If you did not receive an SMS message

If you did not receive your six-digit code via SMS, check that the phone number you provided is correct. If it is, make sure you have a cellular signal.

If you still are not receiving the messages, check with your service provider to confirm that messages are not getting blocked.

### SMS message rate limits

If you attempt to send more than ten SMS messages to your device within one hour, you will see an error message about a rate limit exception.

When you exceed your messaging limit, you'll need to wait at least an hour after your request for your first message before requesting another. You will receive an additional attempt after the passage of each additional hour.

## Rejected codes

If the 6-digit code in the Guardian or the Google Authenticator app is being rejected for sign in (often with the message `Incorrect Code`), first check that you are selecting the right application from the list in your authenticator app. If you've verified that you're selecting the correct application, make sure that your mobile device's clock settings are correct. One-time passwords are generated using Coordinated Universal Time (UTC), so your device's time must be correct for your code to work.

To check your clock settings:

* **Android Devices** - Go to **Settings** > **Date & Time**. Make sure that the box next to **Automatic** is checked. To turn it off, go to **Settings > Date & Time**. Tap the box next to **Automatic** to un-check it.
* **iOS Devices** - Go to **Settings** > **General** > **Date & Time**. Enable **Set Automatically**. If this setting was already enabled, you can disable it for a moment, then re-enable.

## Duo-related issues

For questions or issues specifically regarding Duo, see [Duo's documentation](https://guide.duo.com).


# Troubleshoot Role-Based Access Control and Authorization
Source: https://auth0.com/docs/troubleshoot/authentication-issues/troubleshoot-rbac-authorization

Explore solutions to common issues experienced when implementing role-based access control (RBAC) using the Authorization Core feature set.

Here are some solutions to common issues experienced when implementing [role-based access control (RBAC)](/docs/manage-users/access-control/rbac) using the Authorization Core feature set.

## Role-based access control is enabled for my API, but the scopes claim is not showing what you say it should

* Make sure that you aren't setting `accessToken.scope` in a rule.
* Remember that any configured [authorization rules](/docs/manage-users/access-control/rules-for-authorization-policies) run after the RBAC-based authorization decisions are made, so they may override the default behavior.


# Troubleshoot SAML Configurations
Source: https://auth0.com/docs/troubleshoot/authentication-issues/troubleshoot-saml-configurations

Describes troubleshooting for SAML configuration issues.

When troubleshooting, it's important to understand your configuration.

* **Is Auth0 serving as the <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> Service Provider (SP), the SAML <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip> (IdP), or both?**

  The SP redirects users elsewhere for authentication. The IdP authenticates the user by prompting them to log in and validating the information provided. If your application redirects the user to Auth0 for authentication via SAML, then Auth0 is the IdP. If Auth0 redirects users via a Connection to a remote IdP via SAML, then Auth0 is the SP to the remote IdP. Auth0 can act as the SP, IdP, or both.
* **Does your authentication flow use an SP-initiated model, an IdP-initiated model, or both?**

  SP-initiated authentication flows begin with the user navigating to the SP application and getting redirected to the IdP for login. An IdP-initiated flow means the user navigates to the IdP, logs in, and then gets redirected to the SP application.

  Within enterprise settings, the IdP-initiated flow is most common.
* **Which user profile attribute identifies the user at the IdP (during login) and within each application?**

  If the naming attribute differs between the IdP and the application(s), you'll need to configure the appropriate mappings within Auth0 so that it sends the correct user profile attributes to the application(s).

  * From our experience, using the email address as the unique identifier is the easiest option, though there are privacy concerns with this option.
  * Enterprise organizations often use an internal ID of some type with the IdP, which needs to be mapped to another attribute meaningful to outsourced SaaS applications.
* **Are your authentication requests signed?**
* **Are your authentication assertions encrypted?**

When troubleshooting, we recommend beginning by gathering information that helps answer the following questions:

1. How many users experience the issue? Just one user? All users?
2. Is this an issue with a new setup, or is this an existing integration that's stopped working?
3. How many applications does the issue affect?
4. What is the expected behavior? What is the behavior you're seeing?
5. How far through the login sequence does the user get?

## Check affected users

* Check the user's profile, browser, or device for any issues.
* Check to see if it happens in all browsers for the affected users (indicating a data issue) or just certain types of browsers (indicating a browser-specific issue).
* Check to see if the browser has enabled JavaScript and cookies.
* Check that the caps lock key is disabled.
* If the user is using a mobile device, check to see if there's any software that might impact authentication and/or authorization (such as not running some type of required software).
* Check to see if the user can access some of the app's key URLs, such as the IdP's <Tooltip href="/docs/glossary?term=Single+Sign-on">Single Sign-on</Tooltip> (SSO) URL (indicating a network connectivity issue).

## Troubleshoot Auth0 as a service provider

### Common errors

Here are some common errors you might encounter when Auth0 acts as the service provider and the steps you should take to resolve them.

#### Error: Connection disabled

This message indicates that the Application doesn't have an active Connection associated:

`"error": "invalid_request",
"error_description": "the connection was disabled"`

1. Navigate to [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise), and select a connection type.
2. Select the name of your Connection.
3. Select the **Applications** view.
4. Enable at least one Application (if you don't see any in the list, you will need to create an application before proceeding).

#### Error: IdP-Initiated login not enabled

This error typically occurs because the ACS URL configured in the IdP used the default Auth0 tenant domain, whereas the authentication transaction was started by calling the <Tooltip href="/docs/glossary?term=Custom+Domain">Custom Domain</Tooltip> `/authorize` endpoint.

`"invalid_request": "IdP-Initiated login is not enabled for connection 'CONNECTION_NAME'."`

If you see this error when using an SP-initiated flow, one of the following is missing or empty:

* `RelayState` parameter
* `InResponseTo` attribute in the SAML response

If these are missing or empty, Auth0 treats the login as IdP-initiated. You can fix this error by checking your configuration to ensure that both fields are populated and returned appropriately.

To fix this:

1. Navigate to [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise), and select a connection type.
2. Select the name of your Connection.
3. Select the **IdP-Initiated SSO** view.
4. Locate **IdP-Initiated SSO Behavior**, and select **Accept Requests** to enable IdP-initiated logins.
5. Select the **Default Application** and the **Response Protocol** used by that application, and (optionally) specify any additional parameters you want to be passed to the application.

#### Error: InResponseTo attribute does not match the ID in AuthNRequest

This error occurs when the `InResponseTo` attribute in the SAML response is not recognized by the Auth0 tenant. This error could be caused by:

* blocked cookies
* mismatched IDs from the most recent SAML request
* inconsistent use of domains

If your tenant uses a custom domain, you could have a mismatch if the login flow begins on the custom domain and finishes on the canonical domain. For example, the user starts at the custom domain:

<AuthCodeBlock />

But the identity provider is configured to return the SAML response to the ACS URL at the canonical domain:

```http lines theme={null}
https://{yourTenant}.auth0.com/login/callback
```

If the ID is returned to another domain in the `InResponseTo` attribute of a SAML response, your Auth0 tenant doesn’t have a record of it and returns the above error.

To fix this:

Use the same domain throughout the login flow. Change either the domain in the initial `/authorize` request or the ACS URL with your identity provider.

#### Error: IdP-Initiated Default App Not Configured

This error typically occurs have enabled IdP-Initiated flows but you haven't provided the necessary information to execute the flow.

`"invalid_request": "Default App for IdP-Initiated is not configured. Make sure to configure that from connection settings or include client_id in RelayState parameter."`

The ACS URL should use the same domain as the initial authentication request. If using custom domains, this should use the custom domain callback URL.

If you see this error when using an SP-initiated flow, one of the following is missing or empty:

* `RelayState` parameter
* `InResponseTo` attribute in the SAML response

If these are missing or empty, Auth0 treats the login as IdP-initiated. You can fix this error by checking your configuration to ensure that both fields are populated and returned appropriately.

To fix this:

1. Navigate to [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise), and select a connection type.
2. Select the name of your Connection.
3. Select the **IdP-Initiated SSO** view.
4. Select the **Default Application** and the **Response Protocol** used by that application, and (optionally) specify any additional parameters you want to be passed to the application.

#### Error: Missing RelayState

This error occurs when the identity provider doesn't return the `RelayState` parameter along with its response.

Work with the identity provider to ensure that it returns the `RelayState` parameter.

#### Error: Audience invalid

This error occurs if the value of the `audience` element from the identity provider's SAML response doesn't match the value expected by Auth0. Auth0 expects the value to be the Entity ID for the Connection.

Find your connection's entity ID:

1. Navigate to [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise), and select a connection type.
2. Select the name of your Connection.
3. Select the **Setup** view, and locate the **Common Settings** section; your **Entity ID** is the second parameter provided.

Make sure that the identity provider sends the correct `audience` value in the SAML response.

#### Incorrect protocol specified

One common error is specifying the incorrect response protocol on the IdP-Initiated tab. The response protocol is the one used between Auth0 and the Application (not the remote identity provider). For example, if you set this value to **SAML** when your Application expects **<Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect** or **<Tooltip href="/docs/glossary?term=WS-Fed">WS-Fed</Tooltip>** results in errors due to the incorrect configuration.

1. Navigate to [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise), and select a connection type.
2. Select the name of your Connection.
3. Select the **IdP-Initiated SSO** view, locate **Response Protocol**, and check its value.

#### User isn't logged out of the IdP

When ADFS is configured as SAML IdP, if the ADFS is relaying party trust `Name ID` attribute isn't mapped the logout flow fails. For example, with the federated parameter `v2/logout?federated&...` user isn't redirected to the ADFS SAML logout endpoint but redirects back to application callback URL directly. As a consequence, the user isn't logged out from the IdP in that case.

Add the `Name ID` attribute as a rule on the SAML Relaying Party Trust.

### SAML login issues

When troubleshooting a SAML login, there are four primary stages to check:

* Stage 1: The user is successfully redirected to an identity provider (IdP) and is able to login.
* Stage 2: After login with the IdP, the user returns to Auth0 with a successful login event recorded.
* Stage 3: After a successful login event in Auth0, the user profile in Auth0 is correct.
* Stage 4: The user successfully redirects back to application and is able to access application.

The following sections describe how to check each stage and how to identify if there are any issues with a given stage.

#### IdP login page doesn't display

1. Navigate to [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise), and select **SAML**.
2. Locate your connection, and select its **Try** (triangle/play) icon to test the interaction between Auth0 and the remote IdP. If the Connection does **not** work, continue with the steps detailed in this section. If it does, proceed to the next section.
3. Next to the SAML connection, click **Settings** (represented by the gear icon).

   <Frame>
     <img alt="Dashboard Authentication Enterprise SAML Connection Settings" />
   </Frame>
4. Check and confirm the following with the IdP administrator:

   1. That the Sign In URL is the correct Single Sign-on (SSO) URL. This is the URL that Auth0 will redirect the user to for authentication.
   2. If the IdP expects HTTP-POST binding or HTTP-Redirect binding. You can switch the default binding in the **Settings** tab.
   3. If your authentication requests should be signed. If so, which signing algorithm does the IdP expect you to use? (Note that authentication requests are not commonly signed.) If you're sending signed requests, enable the Connection Settings **Sign Request** toggle and make sure the **Signing Algorithm** value matches what the IdP expects.
   4. Ask the IdP administrator to check for log entries that might provide information on the problem.

#### Logs don't show successful login event

In this case, the user successfully logs in with the identity provider, but the Auth0 logs do not show a successful login event.

1. Check the [Logs](https://manage.auth0.com/#/logs) and [Users](https://manage.auth0.com/#/users) pages in the Auth0 Dashboard to see if Auth0 shows a successful login event. If Auth0's logs don't show a successful login event, there is probably an issue with the SAML Authentication Assertion returned by the IdP or Auth0 is unable to consume the assertion.
2. Check the information that Auth0 sends to the application by [capturing an HTTP trace of the login sequence](/docs/troubleshoot/troubleshooting-tools/generate-and-analyze-har-files) and analyzing the HTTP trace.

   <Warning>
     Before sharing a HAR file with anyone (including Auth0), ensure that you remove or obfuscate all sensitive data, such as:

     * Confidential user information
     * Personal identifiable information (PII)
     * Confidential application information

     To learn more, read the following articles on [Auth0 Community](https://community.auth0.com):

     * [Sanitizing HTTP Traces](https://community.auth0.com/t/sanitizing-http-traces/119488)
     * [How to Sanitize an HTTP Trace File Automatically](https://community.auth0.com/t/how-to-sanitize-a-http-trace-file-automatically/120583)
     * [How to Manually Redact Sensitive Information](https://community.auth0.com/t/how-to-manually-redact-sensitive-information/122554)
     * [HAR File is Too Large to Upload to the Support Case](https://community.auth0.com/t/har-file-is-too-large-to-upload-to-the-support-case/122488)
   </Warning>
3. You can view the HTTP trace in a HAR file analyzer, such as [Google's HAR Analyzer](https://toolbox.googleapps.com/apps/har_analyzer/).

   1. Scan through the sequence of URLs invoked in the HTTP trace.

      1. The first few will be URLs for your application.
      2. There will then be a redirect to an Auth0 URL (such as `{yourDomain}`).
   2. After one or more intervening URLs, there will be a POST back to Auth0 containing the SAML assertion with user information. The URL should be for the Assertion Consumer Service (ACS) of Auth0, which consumes the assertion and extracts the needed information.
   3. Click on the row for the POST call in the HAR analyzer.
   4. Switch to the POST Data tab, and look for the SAML response.
   5. Copy and paste the SAML response into a [SAML debugger](https://samltool.io/).
   6. Remove the "SAML response" at the beginning, as well as anything beginning with `&RelayState=` at the end.
4. After retrieving and decoding the SAML message, check the following fields:

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Destination</td>
      <td>Check that the destination for the SAML response is the correct Auth0 Tenant and Connection (`https://{TENANT}.auth0.com/login/callback?connection={CONNECTION}`).</td>
    </tr>

    <tr>
      <td>Status Field</td>
      <td>This field should indicate success. (<code>\<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/></code>).</td>
    </tr>

    <tr>
      <td>Recipient</td>
      <td>Check that the <code>\<saml:SubjectConfirmation</code> Method element contains correct tenant and connection in the “Recipient” field (`https://{TENANT}.auth0.com/login/callback?connection={CONNECTION}`).</td>
    </tr>

    <tr>
      <td>Audience</td>
      <td>Check that the SAML Audience restriction field contains the correct tenant and connection information (`<saml:AudienceRestriction><saml:Audience>urn:auth0:{TENANT}:{CONNECTION}</saml:Audience>`).</td>
    </tr>

    <tr>
      <td>Naming</td>
      <td>The attribute identified by the <code>NameIdentifier</code> field should be known to the application. If it's not, the identifier should be some other attribute within the assertion (such as an internal IdP identifier for the user or an email address).</td>
    </tr>

    <tr>
      <td>Signature Key</td>
      <td>Check that the value indicated by the <code>X509Certificate</code> element matches the value provided to your connection.</td>
    </tr>

    <tr>
      <td>Certificate</td>
      <td>Compare the certificate sent to the one that you provided to the application</td>
    </tr>
  </tbody>
</table>

#### User profile attributes are incorrect

In this case, the user successfully logs in with the IdP, the Auth0 logs show a successful login event, but the user's profile attributes are **not** correct.

Check to see if the user's Auth0 profile populated correctly:

1. Go to the [Dashboard > User Management > Users](https://manage.auth0.com/#/users).
2. Find and click on the specific user to open up their profile. If there are multiple rows for a given user, be sure to open up the record associated with the SAML Connection.
3. On the user's profile, you can view their details in one of two ways. You can use the **Details** tab or the **Raw JSON** tab. This shows you what attributes Auth0 has received from the identity provider.
4. If the attribute is missing, check to see if the attribute was included in the assertion. You can do this by decoding the SAML assertion, or you can enable debugging for the connection.

   1. To enable debugging for the connection, navigate to [Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise).
   2. Open the list of **SAML** IdP connections, click **Settings**, and enable **Debug Mode**.

      <Frame>
        <img alt="Troubleshoot SAML Connections Enable Debug Mode screen" />
      </Frame>
   3. With **Debug Mode** enabled, **Warning During Login** log entries [in the Dashboard](https://manage.auth0.com/#/logs) have an `original_profile` property listing every attribute included in the SAML assertion by the Identity Provider. You can use this list to see the information that the IdP is sending and to help you create the mappings. If the missing attribute is not in the assertion at all, please work with the IdP to make sure it is included.
5. If an attribute value exists in the Auth0 user profile, but is not mapped to the right attribute, you can correct this via the Connection Mapping capability.

   1. You can do this by navigating to [Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise).
   2. Open the list of **SAML** IdP connections and go to the **Mappings** tab.

      <Frame>
        <img alt="Troubleshoot SAML Connections Mappings Tab Screen" />
      </Frame>
   3. Within the provided editor, there is a JSON snippet you can edit to configure your mappings. The name on the left is the Auth0 user profile attribute to which the assertion value will be mapped. The value on the right is the identifier in the SAML assertion from which the attribute comes. When Auth0 incorporates unmapped SAML attributes into the user profile, attribute identifiers containing dots `.` are replaced with semicolons `:`. While configuring your mappings, ensure the identifiers you provide match those in the SAML assertion.

#### User cannot access the application

In this case, the user successfully logs in with the IdP, Auth0 logs show a successful login event, and the user's profile attributes are correct; but the user **cannot** access the application.

1. Check your application's log files to see if there are any error messages indicating why the user is unable to access the application. The two most common causes for this issue are:

   1. Missing user profile information.
   2. Incorrect or missing authorization information.
2. Check the information that Auth0 sends to the application by [capturing an HTTP trace of the login sequence](/docs/troubleshoot/troubleshooting-tools/generate-and-analyze-har-files) and analyzing the HTTP trace. You can view the HTTP trace in a HAR file analyzer, such as [Google's HAR Analyzer](https://toolbox.googleapps.com/apps/har_analyzer/).

   <Warning>
     Before sharing a HAR file with anyone (including Auth0), ensure that you remove or obfuscate all sensitive data, such as:

     * Confidential user information
     * Personal identifiable information (PII)
     * Confidential application information

     To learn more, read the following articles on [Auth0 Community](https://community.auth0.com):

     * [Sanitizing HTTP Traces](https://community.auth0.com/t/sanitizing-http-traces/119488)
     * [How to Sanitize an HTTP Trace File Automatically](https://community.auth0.com/t/how-to-sanitize-a-http-trace-file-automatically/120583)
     * [How to Manually Redact Sensitive Information](https://community.auth0.com/t/how-to-manually-redact-sensitive-information/122554)
     * [HAR File is Too Large to Upload to the Support Case](https://community.auth0.com/t/har-file-is-too-large-to-upload-to-the-support-case/122488)
   </Warning>

   1. Scan through the sequence of URLs invoked in the HTTP trace.

      1. The first few will be URLs for your application.
      2. There will then be a redirect to an Auth0 URL (such as `{yourDomain}`).
   2. After one or more intervening URLs, there will be a POST back to Auth0 containing the SAML assertion with user information. The URL should be for the Assertion Consumer Service (ACS) of Auth0, which consumes the assertion and extracts the needed information.
   3. Click on the row for the POST call in the HAR analyzer.
   4. Switch to the POST Data tab, and look for the SAML response.
   5. Copy and paste the SAML response into a [SAML debugger](https://samltool.io/).
   6. Remove the SAML response at the beginning, as well as anything beginning with `&RelayState=` at the end.
3. After retrieving and decoding the SAML message, check the following fields:

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Destination</td>
      <td>Check that the destination for the SAML response is the correct Auth0 Tenant and Connection (`https://{TENANT}.auth0.com/login/callback?connection={CONNECTION}`).</td>
    </tr>

    <tr>
      <td>Status Field</td>
      <td>This field should indicate success. (<code>\<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/></code>).</td>
    </tr>

    <tr>
      <td>Recipient</td>
      <td>Check that the <code>\<saml:SubjectConfirmation</code> Method element contains correct tenant and connection in the “Recipient” field (`https://{TENANT}.auth0.com/login/callback?connection={CONNECTION}`).</td>
    </tr>

    <tr>
      <td>Audience</td>
      <td>Check that the SAML Audience restriction field contains the correct tenant and connection information (`<saml:AudienceRestriction><saml:Audience>urn:auth0:{TENANT}:{CONNECTION}</saml:Audience>`).</td>
    </tr>

    <tr>
      <td>Naming</td>
      <td>The attribute identified by the <code>NameIdentifier</code> field should be known to the application. If it's not, the identifier should be some other attribute within the assertion (such as an internal IdP identifier for the user or an email address).</td>
    </tr>

    <tr>
      <td>Signature Key</td>
      <td>Check that the value indicated by the <code>X509Certificate</code> element matches the value provided to your connection.</td>
    </tr>

    <tr>
      <td>Certificate</td>
      <td>Compare the certificate sent to the one that you provided to the application</td>
    </tr>
  </tbody>
</table>

4. If your authorization flow uses an OIDC-conformant protocol, you can capture a HAR trace and view it using [Google's HAR Analyzer](https://toolbox.googleapps.com/apps/har_analyzer/).

   1. Scan through the sequence of URLs in the trace, and look for the following:

      1. The first few will be URLs for your application.
      2. There will then be a redirect to an Auth0 URL (such as `{yourDomain}`).
   2. Further down is your application's callback URL. Make sure that it's correct.
   3. Retrieve the ID Token from this call, and paste it into [a JWT decoder](https://jwt.io/). Check that the claims in the token contain the information needed by the application.
5. If you're using an IdP-initiated flow (for example, the user starts at the identity provider in a portal application), be sure that:

   1. The Assertion Consumer Service (ACS) URL at the identity provider includes the connection name (for example `https://{yourDomain}/login/callback?connection=CONNECTION_NAME`)
   2. The IdP-initiated configuration tab for the Connection is properly filled in, including:

      1. The IdP-initiated SSO behavior is set to **Accept Requests**;
      2. The application to which the user should be sent;
      3. The protocol between the application and Auth0 (which is not necessarily **SAML** like the connection, and most likely is **OpenID Connect**);
      4. Any protocol-specific values to include in the query string, such as `scope`, `response_type`, `redirect_uri`, and `audience`. These values should match the ones expected by the application when using an SP-initiated flow.
   3. Disable your rules temporarily to make sure that nothing is interfering with the login process.
   4. If you've enabled multi-factor authentication (MFA), disable it temporarily to make sure that it is not interfering with the login process.
   5. Check that the SAML Connection works in an SP-Initiated flow by using **Try** to run a Connection test.

#### Request could not be performed due to an error on the part of the SAML responder or SAML authority

The error may appear as follows:

`<samlp:Status>
\<samlp:StatusCodeValue="urn:oasis:names:tc:SAML:2.0:status:Responder" /> </samlp:Status>`

1. Make sure that the signature algorithm on your Auth0 connection is the same as the configuration on the ADFS side: either `rsa-sha256` or `rsa-sha1`.
2. Alternatively, you can contact your ADFS administrator to learn the expected signing method or to see if their logs contain further information about the reason for the error.

## Troubleshoot Auth0 as identity provider

When troubleshooting a SAML login, there are four primary stages to check:

* Stage 1: The user is successfully redirected to IDP and is able to login.
* Stage 2: After login with the IDP, the user returns to Auth0 with a successful login event recorded.
* Stage 3: After a successful login event in Auth0, the user profile in Auth0 is correct.
* Stage 4: The user successfully redirects back to the application and is able to access the application.

### Successful login event does not show up in logs

In this case, the user successfully logs in with the idp, but a successful login event does not show up in Auth0 logs.

1. If you're using an Auth0 Database Connection:

   1. Check that the user exists and the entered password is correct.
   2. Disable your rules temporarily to make sure that nothing is interfering with the login process.
   3. If you've enabled multi-factor authentication (MFA), disable it temporarily to make sure that it is not interfering with the login process.
2. If you're using an Auth0 Database Connection or a remote SAML connection, check that the SAML Connection works by using **Try** to run a Connection test.

### User profile attributes are incorrect

In this case, the user successfully logs in with the IdP, a successful login event shows up in Auth0 logs, but the user's profile attributes are incorrect. If the user:

* Appears to log in successfully.
* The Logs and Users pages in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> should successful login events

The next step is to check that the user's profile contains the necessary user profile attributes.

1. Go to the [Dashboard > User Management > Users](https://manage.auth0.com/#/users).
2. Find and click on the specific user to open up their profile. If there are multiple rows for a given user, be sure to open up the record associated with the SAML Connection.
3. On the user's profile, you can view their details in one of two ways. You can use the **Details** tab or the **Raw JSON** tab. This shows you what attributes Auth0 has received from the identity provider. If an attribute is missing, check with the identity provider to confirm that it has the attribute and that it is returning that attribute to Auth0.

### User cannot access the application

In this case, the user successfully logs in with the IdP, a successful login event shows up in Auth0 logs, and the user's profile attributes are correct, but the user cannot access the application.

1. Check to see if the user's Auth0 profile populated correctly:

   1. Go to [Dashboard > User Management > Users](https://manage.auth0.com/#/users).
   2. Find and click on the specific user to open up their profile. If there are multiple rows for a given user, be sure to open up the record associated with the SAML Connection.
   3. On the user's profile, view their details in one of two ways. You can use the **Details** tab or the **Raw JSON** tab. This shows you what attributes Auth0 has received from the identity provider. Ensure that the profile includes all of the details required by the application. If a user attribute is missing, check with the identity provider to confirm that it has the attribute and that it is returning that attribute to Auth0.
2. Check the application's log files to see if there are any error messages indicating why the user is unable to access the application. The two most common causes for this issue are missing user profile information or incorrect/missing authorization information.
3. Check the information that Auth0 sends to the application by [capturing an HTTP trace of the login sequence](/docs/troubleshoot/troubleshooting-tools/generate-and-analyze-har-files) and analyzing the HTTP trace. You can view the HTTP trace in a HAR file analyzer, such as [Google's HAR Analyzer](https://toolbox.googleapps.com/apps/har_analyzer/).

   <Warning>
     Before sharing a HAR file with anyone (including Auth0), ensure that you remove or obfuscate all sensitive data, such as:

     * Confidential user information
     * Personal identifiable information (PII)
     * Confidential application information

     To learn more, read the following articles on [Auth0 Community](https://community.auth0.com):

     * [Sanitizing HTTP Traces](https://community.auth0.com/t/sanitizing-http-traces/119488)
     * [How to Sanitize an HTTP Trace File Automatically](https://community.auth0.com/t/how-to-sanitize-a-http-trace-file-automatically/120583)
     * [How to Manually Redact Sensitive Information](https://community.auth0.com/t/how-to-manually-redact-sensitive-information/122554)
     * [HAR File is Too Large to Upload to the Support Case](https://community.auth0.com/t/har-file-is-too-large-to-upload-to-the-support-case/122488)
   </Warning>

   1. Scan through the sequence of URLs invoked in the HTTP trace.

      1. The first few will be URLs for your application.
      2. There will then be a redirect to an Auth0 URL (such as `{yourDomain}`).
   2. After one or more intervening URLs, there will be a POST back to Auth0 containing the SAML assertion with user information. The URL should be for the Assertion Consumer Service (ACS) of Auth0, which consumes the assertion and extracts the needed information.
   3. Click on the row for the POST call in the HAR analyzer.
   4. Switch to the POST Data tab, and look for the SAML response.
   5. Copy and paste the SAML response into a [SAML debugger](https://samltool.io/).
   6. Remove the SAML response at the beginning, as well as anything beginning with `&RelayState=` at the end.
4. After retrieving and decoding the SAML message, check the following fields:

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Destination</td>
      <td>Check that the destination for the SAML response is the correct Auth0 Tenant and Connection (`https://{TENANT}.auth0.com/login/callback?connection={CONNECTION}`).</td>
    </tr>

    <tr>
      <td>Status Field</td>
      <td>This field should indicate success. (<code>\<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/></code>).</td>
    </tr>

    <tr>
      <td>Recipient</td>
      <td>Check that the <code>\<saml:SubjectConfirmation</code> Method element contains correct tenant and connection in the “Recipient” field (`https://{TENANT}.auth0.com/login/callback?connection={CONNECTION}`).</td>
    </tr>

    <tr>
      <td>Audience</td>
      <td>Check that the SAML Audience restriction field contains the correct tenant and connection information (`<saml:AudienceRestriction><saml:Audience>urn:auth0:{TENANT}:{CONNECTION}</saml:Audience>`).</td>
    </tr>

    <tr>
      <td>Naming</td>
      <td>The attribute identified by the <code>NameIdentifier</code> field should be known to the application. If it's not, the identifier should be some other attribute within the assertion (such as an internal IdP identifier for the user or an email address).</td>
    </tr>

    <tr>
      <td>Signature Key</td>
      <td>Check that the value indicated by the <code>X509Certificate</code> element matches the value provided to your connection.</td>
    </tr>

    <tr>
      <td>Certificate</td>
      <td>Compare the certificate sent to the one that you provided to the application</td>
    </tr>
  </tbody>
</table>

5. Ensure that the SAML assertion contains any additional information required by the application and that the information is present in the attributes expected by the application.

   1. If you need to alter the assertion sent from Auth0 to your application, you can add or map attributes using rules.

      1. Log into Auth0 and navigate to **Rules**.

      2. Click **Create Rule** and, on the next page, choose the **Change your SAML configuration** template.

      3. In the rules editor, uncomment the lines you want to use. Use lines 9-17 in the template to map attributes as needed. You can also add lines to implement mappings. The left side of each line specifies the identifier for the attribute in the assertion. The right side of each line references the Auth0 user profile attribute whose value will be used to populate the outgoing assertion sent to the application.

         ```text lines theme={null}
         //context.samlConfiguration.mappings = {    
             // "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier":      "user_id",    
             // "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress":        "email",    
             // "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name":                "name",    
             // "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname":           "given_name",    
             // "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname":             "family_name",    
             // "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn":                 "upn",    
             // "http://schemas.xmlsoap.org/claims/Group":                                   "groups"    
             // };
         ```

### No active session(s) found matching LogoutRequest error

The `SessionIndex` and `NameID` values in the SAML Logout request need to match the ones received by the service provider in the original SAML assertion.

## Contact support

If the troubleshooting steps listed above don't solve the issues, please request assistance from Auth0 by opening up a ticket in the Support Center. Be sure to include the following information:

1. The number of users experiencing this issue. One? All?
2. Whether this issue involves a new setup or if it involves an existing integration that suddenly stopped working
3. The number of applications affected
4. What the expected behavior is, as well as what the current behavior is
5. How far through the login sequence the user gets
6. The name of the application registered in Auth0 and the identity protocol it uses
7. The name of the Connection involved
8. Whether or not you're using the Auth0 Lock widget (if so, what version?)
9. Is a customized version of Lock used?
10. An HTTP trace of the SSO interaction in [a .har file](/docs/troubleshoot/troubleshooting-tools/generate-and-analyze-har-files)

    <Warning>
      Before sharing a HAR file with anyone (including Auth0), ensure that you remove or obfuscate all sensitive data, such as:

      * Confidential user information
      * Personal identifiable information (PII)
      * Confidential application information

      To learn more, read the following articles on [Auth0 Community](https://community.auth0.com):

      * [Sanitizing HTTP Traces](https://community.auth0.com/t/sanitizing-http-traces/119488)
      * [How to Sanitize an HTTP Trace File Automatically](https://community.auth0.com/t/how-to-sanitize-a-http-trace-file-automatically/120583)
      * [How to Manually Redact Sensitive Information](https://community.auth0.com/t/how-to-manually-redact-sensitive-information/122554)
      * [HAR File is Too Large to Upload to the Support Case](https://community.auth0.com/t/har-file-is-too-large-to-upload-to-the-support-case/122488)
    </Warning>
11. An Auth0 log entry for the failed authentication
12. An authentication log file from any third-party applications (such as Sharepoint) involved

## Learn more

* [SAML Single Sign-On Integrations](/docs/authenticate/protocols/saml/saml-sso-integrations)
* [Test SAML SSO with Auth0 as Service Provider and Identity Provider](/docs/authenticate/protocols/saml/saml-configuration/configure-auth0-as-service-and-identity-provider)


# Troubleshoot Basic Issues
Source: https://auth0.com/docs/troubleshoot/basic-issues

Learn where to look for basic troubleshooting steps to eliminate common problems such as Auth0 status, platform, connections, rules, domains, and how to generate HAR files and validate JWTs.

* [Verify Platform](/docs/troubleshoot/basic-issues/verify-platform) - Learn how to verify your platform to troubleshoot issues.
* [Verify Connections](/docs/troubleshoot/basic-issues/verify-connections) - Learn how to verify connection transactions and external service dependencies to troubleshoot issues.
* [Verify Domain](/docs/troubleshoot/basic-issues/verify-domain) - Learn how to verify your domain to troubleshoot issues.
* [Verify Rules](/docs/troubleshoot/basic-issues/verify-rules) - Learn how to verify rules to troubleshoot issues.
* [Check Error Messages](/docs/troubleshoot/basic-issues/check-error-messages) - Learn how to check for error messages to troubleshoot issues.
* [Troubleshoot Invalid Token Errors](/docs/troubleshoot/basic-issues/invalid-token-errors) - Describes how to troubleshoot invalid token errors.
* [Check for Deprecation Errors](/docs/troubleshoot/basic-issues/search-logs-for-deprecation-errors) - Describes how to search for and resolve Auth0 feature [deprecation errors](/docs/troubleshoot/basic-issues/check-deprecation-errors).

## Learn more

* [Monitor Applications](/docs/deploy-monitor/monitor/monitor-applications)
* [Troubleshoot Authentication Issues](/docs/troubleshoot/authentication-issues)
* [Troubleshoot Integration and Extensibility Issues](/docs/troubleshoot/integration-extensibility-issues)
* [Troubleshooting Tools](/docs/troubleshoot/troubleshooting-tools)


# Deprecation Errors
Source: https://auth0.com/docs/troubleshoot/basic-issues/check-deprecation-errors

Learn how to search logs for deprecation errors

When Auth0 features are deprecated, there may be errors or notices in the tenant logs that show up to indicate that your applications are using the deprecated features. This guide will provide assistance with searching your logs for deprecation-related messages as well as explanations of potential causes and resolutions for particular items.

There are two different ways to search for warning messages showing usage of deprecated features: The Dashboard or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. Note that in either case, the [log retention period](/docs/deploy-monitor/logs) is governed by the subscription level of your account.

See [Search Logs for Deprecation Errors](/docs/troubleshoot/basic-issues/search-logs-for-deprecation-errors) for details.

## Deprecation log messages

### Legacy Lock API

**Log entry**: `up-idp-initiated`

**Error Message:** "Legacy Lock API: This feature is being deprecated. Please refer to our documentation to learn how to migrate your application."

**Cause**: Tenant log entries regarding the Legacy Lock API may include the referrer and information about the SDK used.

**Resolution**: Use this information to see if any of your applications use outdated libraries.

### SSOdata endpoint

**Log entry**: `ssodata`

**Error Message:** "SSOdata endpoint: This feature is being deprecated. Please refer to our documentation to learn how to migrate your application."

**Cause**: Either calling the `/ssodata` endpoint directly or using old versions of embedded Lock or Auth0.js SDK to call a function which called the `/ssodata` endpoint.

**Resolution**: Update Lock SDK or Auth0.js SDK to the most recent version.

## Learn more

* [Verify Platform](/docs/troubleshoot/basic-issues/verify-platform)
* [Verify Connections](/docs/troubleshoot/basic-issues/verify-connections)
* [Verify Domain](/docs/troubleshoot/basic-issues/verify-domain)
* [Verify Rules](/docs/troubleshoot/basic-issues/verify-rules)
* [Check Error Messages](/docs/troubleshoot/basic-issues/check-error-messages)


# Check Error Messages
Source: https://auth0.com/docs/troubleshoot/basic-issues/check-error-messages

Learn how to check for error message to troublshoot issues

Check for error messages displayed in any of the following locations:

* Browsers and HTML page responses
* Developer tools network and console tabs
* <Tooltip href="/docs/glossary?term=Authorization+Server">Authorization Server</Tooltip> responses
* Deprecation errors

## Check browser errors

A HAR file is a JSON formatted log of a web browser's interactions with a web server. If authentication isn't working as expected, you can [generate and analyze HAR files](/docs/troubleshoot/troubleshooting-tools/generate-and-analyze-har-files) to find issues.

<Warning>
  Before sharing a HAR file with anyone (including Auth0), ensure that you remove or obfuscate all sensitive data, such as:

  * Confidential user information
  * Personal identifiable information (PII)
  * Confidential application information

  To learn more, read the following articles on [Auth0 Community](https://community.auth0.com):

  * [Sanitizing HTTP Traces](https://community.auth0.com/t/sanitizing-http-traces/119488)
  * [How to Sanitize an HTTP Trace File Automatically](https://community.auth0.com/t/how-to-sanitize-a-http-trace-file-automatically/120583)
  * [How to Manually Redact Sensitive Information](https://community.auth0.com/t/how-to-manually-redact-sensitive-information/122554)
  * [HAR File is Too Large to Upload to the Support Case](https://community.auth0.com/t/har-file-is-too-large-to-upload-to-the-support-case/122488)
</Warning>

## Check login screen

The Lock login widget shows error messages for certain types of issues, such as an incorrect username or password. Check the **More Information** link if you're using Auth0's standard error page.

## Check logs

Auth0 stores [log data](/docs/deploy-monitor/logs) including Dashboard administrator actions, successful and failed user authentications, and password change requests. You can view the logs in the [Dashboard](https://manage.auth0.com/#/logs).

Some types of errors do not appear in the logs. For example, if an error occurs at a remote <Tooltip href="/docs/glossary?term=Identity+Provider">Identity Provider</Tooltip>, where authentication doesn’t complete and the user is never returned to Auth0, there will not be any entry in logs.

You can export Auth0 logs and either store them yourself or automatically push them to external log services. This functionality can help you with data retention requirements, as well as log analysis requirements. You can install and configure an Auth0 Extension to export logs automatically to another provider like Sumo Logic or Loggly. To learn more, navigate to our [log streaming solutions](https://marketplace.auth0.com/features/log-streaming) in Auth0 Marketplace.

<Callout icon="file-lines">
  See [the Monitoring page](/docs/deploy-monitor/monitor) for more details on each of the log events that can help you troubleshoot issues.
</Callout>

You can also use the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> to export logs and store them. There are the two available endpoints, each providing slightly different information.

### Search all logs /get\_logs endpoint

The [Search log events endpoint](https://auth0.com/docs/api/management/v2#!/Logs/get_logs) retrieves log entries that match the search criteria you provided. If you do not provide any search criteria, you will get a list of all available entries.

You can provide search criteria using the **q** parameter and retrieve specific fields using the **fields** parameter.

To access the API, you need a [Management APIv2 token](https://auth0.com/docs/api/management/v2/tokens).

This sample request retrieves all logs for successful logins (the event acronym for successful login is `s`). The list of fields we will retrieve per log entry is: **date**, **description**, **client\_id**, and **log\_id**.

For details on the search criteria you can use and a list with the event acronyms, see the [Search log events endpoint](https://auth0.com/docs/api/management/v2#!/Logs/get_logs).

### Get a single log entry /get\_logs\_by\_id endpoint

The [Get a log event by ID endpoint](https://auth0.com/docs/api/management/v2#!/Logs/get_logs_by_id) retrieves the log entry associated with the provided ID.

This sample request retrieves a single log entry with the ID `90020180129170850881585554625888895190928456277777449010`.

## Check logs for deprecation errors

When Auth0 features are deprecated, there may be errors or notices in the tenant logs that show up to indicate that your applications are using the deprecated features. You can [search the logs for specific deprecation entries](/docs/troubleshoot/basic-issues/check-deprecation-errors) that may indicate that a feature has been deprecated.

## Rate limits and other errors

Auth0 provides a unique error code for errors reported when the [rate limit is exceeded](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy). You should set up automatic scanning of logs to check for rate limit errors so you can proactively address activity that hits rate limits before it causes too much trouble for your users. Auth0 also publishes error codes for other types of errors, and you will find it helpful to scan logs for authentication errors as well as errors from Auth0 Management API calls (Management API error codes are shown below each call in the [Management API Explorer](https://auth0.com/docs/api/management/v2)).

Also note that calling the Management API to retrieve user profile information from within a Rule is a common cause of rate limit errors because such API calls can execute for every login as well as periodic session checks.

## Check Actions Real-time Logs error console

You can put `console.log()` statements into Rules, Hooks, and custom database scripts. The output from those statements is viewable in Actions Real-time Logs. If you use Actions Real-time Logs, you can initiate a view of this log console by navigating to **Auth0 Dashboard > Monitoring > Actions Logs**.

## Learn more

* [Verify Platform](/docs/troubleshoot/basic-issues/verify-platform)
* [Verify Connections](/docs/troubleshoot/basic-issues/verify-connections)
* [Verify Domain](/docs/troubleshoot/basic-issues/verify-domain)
* [Verify Rules](/docs/troubleshoot/basic-issues/verify-rules)
* [Deprecation Errors](/docs/troubleshoot/basic-issues/check-deprecation-errors)


# Troubleshoot Invalid Token Errors
Source: https://auth0.com/docs/troubleshoot/basic-issues/invalid-token-errors

Describes how to troubleshoot invalid token errors.

## Parsing an HS256-Signed ID Token Without an access token

**Error Message**: The <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> cannot be validated because it was signed using the HS256 algorithm and public applications (such as a browser) can’t store secrets.

### Causes

Beginning with **auth0.js version 9** and **Lock version 11**, when ID tokens are signed with HS256, they are discarded and a call to `/userinfo` is made to retrieve user information.

Calling `/userinfo` requires an <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip>. If you don't ask for an access token when authenticating, you will receive the following error:
`The id_token cannot be validated because it was signed with the HS256 algorithm
and public applications (like a browser) can’t store secrets.
Please read the associated doc for possible ways to fix this.`

### Fixes

There are two ways to fix the error:

1. **(RECOMMENDED)** Change the application signature algorithm to RS256 instead of HS256.
2. Change the value of your `responseType` parameter to `token id_token` (instead of the default), so that you receive an access token in the response.

To change the application signature algorithm to RS256 instead of HS256:

1. Go to [Auth0 Dashboard > Applications > Applications](https://manage.auth0.com/#/applications), and select the name of the application to view.
2. Scroll to the bottom of the **Settings** page, and select **Show Advanced Settings**.
3. Select the **OAuth** view, change the value of **JsonWebToken Signature Algorithm** to **RS256**, and select **Save Changes**.

If you proceed with this option and you are using the ID token to call your APIs, be sure to change your server code so that it validates tokens using the RS256 algorithm instead of HS256. Note that using ID tokens to call APIs is not recommended.

You can decode, verify and generate <Tooltip href="/docs/glossary?term=JWTs">JWTs</Tooltip> using the [JWT Tool](https://jwt.io/).


# Recover Administrative Access to a Tenant
Source: https://auth0.com/docs/troubleshoot/basic-issues/recover-administrative-access-to-a-tenant

Describes how to recover options for a lost administrator account

If you cannot access the administrator account for your tenant, you have options for recovery.

If an existing administrator leaves your organization without delegating access to another team member, try the steps below before contacting Auth0 support.

<Callout icon="file-lines">
  These solutions will not work if the employee was the only admin on the tenant and MFA protected the account.
</Callout>

1. Check the email alias of the former admin. If you have access to the inbox, such as through Google Workspace, request a password reset for the user and reset the password for the tenant account.
2. Check for another admin on the tenant. This admin can remove the previous employee account and add a new admin. Auth0 recommends you have multiple admins on a tenant.

If you still cannot gain access to the tenant, create a support request with Auth0. Our support team will verify tenant ownership and grant access. To learn more, read [Open and Manage Support Tickets](/docs/troubleshoot/customer-support/open-and-manage-support-tickets).

## Learn more

* [Create Tenants](/docs/get-started/auth0-overview/create-tenants)


# Check for Deprecation Errors
Source: https://auth0.com/docs/troubleshoot/basic-issues/search-logs-for-deprecation-errors

Learn how to view errors and descriptions relating to deprecations.

When Auth0 features are deprecated, there may be errors or notices in the tenant logs that show up to indicate that your applications are using the deprecated features. This guide will provide assistance with searching your logs for deprecation-related messages as well as explanations of potential causes and resolutions for particular items.

There are two different ways to search for warning messages showing usage of deprecated features: The Dashboard or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. Note that in either case, the [log retention period](/docs/deploy-monitor/logs/log-data-retention) is governed by the subscription level of your account.

## Use the Dashboard

If your application uses a deprecated feature, a **Deprecation Notice** message will appear in the **Logs** section of the Dashboard. Deprecation notices are only shown once per hour (the first time the error occurs within that hour) rather than for each authentication transaction involving the deprecated feature.

1. Go to [Dashboard > Monitoring > Logs](https://manage.auth0.com/#/logs) and search for deprecation-related messages by entering `type:depnote` in the query box. A list of deprecation-related warning messages from your logs will appear, if any exist. The **Description** field provides information on the particular deprecated feature used.
2. Click on the link in the **Type** column for each item to show additional information such as the client ID which identifies the client application using the deprecated feature.
3. Click log entries and select the **Context Data** tab to show details about the item.

## Use the Management API

You can also use the Management API to search through logs for such messages by looking for `type:"depnote"`.

1. Go to the [Management API](https://auth0.com/docs/api/management/v2). If you have not already done so, [get an API token](/docs/secure/tokens/access-tokens/management-api-access-tokens/get-management-api-access-tokens-for-production).
2. On the left, go to [Logs > Search log events](https://auth0.com/docs/api/management/v2/#!/Logs/get_logs) and then scroll down to **Parameters**.
3. In the **q** field enter: `type:"depnote"`.
4. Click on the **TRY** button. The **Client ID** field in the results will indicate which application on your tenant is using the deprecated feature.

## Learn more

* [Log Data Retention](/docs/deploy-monitor/logs/log-data-retention)
* [Logs](/docs/deploy-monitor/logs)


# Verify Connections
Source: https://auth0.com/docs/troubleshoot/basic-issues/verify-connections

Learn how to verify connection transactions and external service dependencies to troubleshoot issues

An authentication transaction often has several parts. Auth0 provides methods so you can try individual parts of the transaction to help you find the possible source of the problem.

Most <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip> connections have a **TRY** button to see if the connection is working. If that fails, you can debug the connection without involving the rest of the application. If the connection works, then you can start debugging the application.

1. Use the **TRY** button on a connection to test just the connection.
2. If the test with the **TRY** button fails, you know it is not an issue with your application but rather something with the connection configuration or the connection provider.
3. Check the response from the test with the **TRY** button to see if the response contains a useful error message or other information.
4. Try logging into the same service through a different path.
5. If the same issue occurs you’ll know it’s some sort of issue with the account
6. If a test with the **TRY** button fails for a custom DB connection, it is frequently caused by an issue in the custom DB scripts. Putting console.log statements into them and viewing output in the Console Log can help debug them.

## Verify external service dependencies

1. If your authentication uses external services, like social identity providers, and it suddenly stops working, [check external services status](/docs/deploy-monitor/monitor/check-external-services-status).
2. If a connection is not working, even with the **TRY** button, check the connection.

<Callout icon="file-lines">
  See [the Monitoring page](/docs/deploy-monitor/monitor) for more details on each of the log events that can help you troubleshoot issues.
</Callout>

## Learn more

* [Verify Platform](/docs/troubleshoot/basic-issues/verify-platform)
* [Verify Domain](/docs/troubleshoot/basic-issues/verify-domain)
* [Verify Rules](/docs/troubleshoot/basic-issues/verify-rules)
* [Check Auth0 Status](/docs/deploy-monitor/monitor/check-auth0-status)
* [Monitor Applications](/docs/deploy-monitor/monitor/monitor-applications)


# Verify Domain
Source: https://auth0.com/docs/troubleshoot/basic-issues/verify-domain

Learn how to verify your domain to troubleshoot issues

* Ensure that the domain is the same as that used during authentication.
* If using an Auth0 [Custom Domain](/docs/customize/custom-domains), it is important to use the same domain as used in the application to invoke authentication. See [Troubleshoot Custom Domains](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-custom-domains) for details.

<Callout icon="file-lines">
  See [the Monitoring page](/docs/deploy-monitor/monitor) for more details on each of the log events that can help you troubleshoot issues.
</Callout>

## Learn more

* [Verify Connections](/docs/troubleshoot/basic-issues/verify-connections)
* [Verify Platform](/docs/troubleshoot/basic-issues/verify-platform)
* [Check External Services Status](/docs/deploy-monitor/monitor/check-external-services-status)
* [Monitor Applications](/docs/deploy-monitor/monitor/monitor-applications)


# Verify Platform
Source: https://auth0.com/docs/troubleshoot/basic-issues/verify-platform

Learn how to verify your platform to troubleshoot issues

Ensure that you are on current versions of your technology stack. If you're using an older version of a programming language or library consider updating to the current version.

* Check the [Auth0 support matrix](/docs/troubleshoot/customer-support/product-support-matrix) to see if the language or library versions you're using is supported.
* If there's a problem in one environment (such as development) but not another (such as production), compare the versions of the technology stack across the two environments.
* If not, upgrade your technology stack and browser to the latest versions and test again before creating a support request.

## Check the scope of the issue

Testing on different browsers, platforms, locations, and users can help narrow down the source of a problem when it occurs. Perform the following tests and review the [logs in your Auth0 dashboard](https://manage.auth0.com/#/logs) after each test for more information.

<Callout icon="file-lines">
  See [the Monitoring page](/docs/deploy-monitor/monitor) for more details on each of the log events that can help you troubleshoot issues.
</Callout>

### Test with different browsers

* Does the issue happen with all browsers or just some?
* Test in a new incognito or private browser session (no previous state).
* Upgrade to the latest browser version and re-test.
* Turn off browser plugins and re-test to see if a plug-in contributes to the issue.

### Test with different users

* Does the issue occur for all users or just some?
* If some, is there a pattern? Such as location, connection, or role?

### Test with different connections (if possible)

* Does the issue happen with all connections or just one?

### Test with different client applications (if you have more than one)

* Does the issue happen with all clients or just one?

### Test across different environments

* Try the development, staging, and production environments of your application(s).
* Try across different Auth0 tenants to see if any differences.

## Check if the issue is consistent or intermittent

* If the issue is consistent, note the steps to reliably duplicate the issue.
* If the issue intermittent, note any pattern that might cause it.
* Is this an issue with a new setup, or did it work before and is now broken?

  * If it just broke, what changes were made?
  * Does undoing the changes fix the issue?

## Issues that affect only one or a few users

* [Check the user's profile](/docs/troubleshoot/authentication-issues/check-user-profiles), browser, or device for any issues.
* Check to see if it happens in all browsers for the affected users (indicating a data issue) or just certain types of browsers (indicating a browser-specific issue).
* Check to see if the browser has enabled JavaScript and cookies.
* Check that the caps lock key is disabled.
* If the user is using a mobile device, check to see if there's any software that might impact authentication and/or authorization (such as not running some type of required software).
* Check to see if the user can access some of the application's key URLs, such as the <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>'s <Tooltip href="/docs/glossary?term=Single+Sign-on">Single Sign-on</Tooltip> (SSO) URL (indicating a network connectivity issue).

## Issues that occur after go-live (worked before, then stopped working)

* Check if any recent changes to your application or any APIs you call?
* Check if any recent network changes (load balancer, firewall, proxy config changes).
* Check if any recent infrastructure changes (e.g. credentials for LDAP or DB servers?)
* Check for any patches or updates to applications, infrastructure, or technology stacks.
* Check that all your servers are running NTP and have accurate time sync
* Check if any of your certificates have expired.
* Check with owners of any remote identity providers if anything changed.

  * Check network connectivity to any remote identity providers.
* Check notifications in <Tooltip href="/docs/glossary?term=Auth0+dashboard">Auth0 dashboard</Tooltip>/migrations - any changes you overlooked?
* Check Auth0 change log - any recent configuration changes related to your issue?
* Check if any component in the technology stack has been updated or patched recently?

## Learn more

* [Verify Connections](/docs/troubleshoot/basic-issues/verify-connections)
* [Verify Domain](/docs/troubleshoot/basic-issues/verify-domain)
* [Verify Rules](/docs/troubleshoot/basic-issues/verify-rules)
* [Check Auth0 Status](/docs/deploy-monitor/monitor/check-auth0-status)
* [Monitor Applications](/docs/deploy-monitor/monitor/monitor-applications)


# Verify Rules
Source: https://auth0.com/docs/troubleshoot/basic-issues/verify-rules

Learn how to verify rules to troubleshoot issues

<Warning>
  The End of Life (EOL) date of Rules and Hooks will be **November 18, 2026**, and they are no longer available to new tenants created as of **October 16, 2023**. Existing tenants with active Hooks will retain Hooks product access through end of life.

  We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public `npm` packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read [Understand How Auth0 Actions Work](/docs/customize/actions/actions-overview).

  To help with your migration, we offer guides that will help you [migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions). We also have a dedicated [Move to Actions](https://auth0.com/extensibility/movetoactions) page that highlights feature comparisons, [an Actions demo](https://www.youtube.com/watch?v=UesFSY1klrI), and other resources to help you on your migration journey.

  To read more about the Rules and Hooks deprecation, read our blog post: [Preparing for Rules and Hooks End of Life](https://auth0.com/blog/preparing-for-rules-and-hooks-end-of-life/).
</Warning>

<Warning>
  We expose IPv6 addresses in our public endpoints (e.g., `travel0.us.auth0.com`). If a request arrives from a machine that supports IPv6, then the `context.request.ip` property will contain an IPv6 address. If you perform manual IP address manipulation, we suggest you use the [ipaddr.js@1.9.0 library](https://www.npmjs.com/package/ipaddr.js/v/1.9.0).
</Warning>

Failures in a rule can often cause authentication issues. Perform the following checks to see if rules could be behind your issue.

* Turn rules off and see if the issue still occurs.
* Check that your rules catch all possible errors that might be returned. Uncaught errors could cause failures.
* Check that your rules are calling the `callback` function only once for each logical branch in your code.
* Add `console.log()` statements to your rules to debug and check state. For example: `console.log(“output = “ + some_variable);`.
* Click **Debug Rule** in the Dashboard to view the output from your `console.log` statements.
* View the output in Actions Real-time Logs to get more information about your rules’ execution.

<Callout icon="file-lines">
  See [the Monitoring page](/docs/deploy-monitor/monitor) for more details on each of the log events that can help you troubleshoot issues.
</Callout>

## Learn more

* [Verify Connections](/docs/troubleshoot/basic-issues/verify-connections)
* [Verify Platform](/docs/troubleshoot/basic-issues/verify-platform)
* [Verify Domain](/docs/troubleshoot/basic-issues/verify-domain)
* [Check Auth0 Status](/docs/deploy-monitor/monitor/check-auth0-status)
* [Monitor Applications](/docs/deploy-monitor/monitor/monitor-applications)


# Auth0 Changelog
Source: https://auth0.com/docs/troubleshoot/customer-support/auth0-changelog





# Auth0 Enterprise and Premier Support
Source: https://auth0.com/docs/troubleshoot/customer-support/auth0-enterprise-and-premier-support

Description of the Auth0 Enterprise and Premier Support plans

Auth0 Enterprise and Premier Support are no longer offered to new customers or customers that have transitioned to a Premier Success Plan.

**Auth0 Enterprise and Premier Support Defect Severity Levels**

Okta will assign Defects one of the four Severity Level priorities, depending upon the resulting impact caused by the Defect. Okta may re-assign a Severity Level prioritization to Customer in the trouble ticketing system, based on the descriptions below. Okta’s assignment will be consistent with the Severity Level descriptions below. Severity Level categories are as follows:

<table>
  <thead>
    <tr>
      <th>Severity Level</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>1 (urgent)</td>
      <td>Emergency Issue; Defect resulting in full or partial system outage or a condition that makes Auth0 unusable or unavailable in production for all of Customer’s Users.</td>
    </tr>

    <tr>
      <td>2 (high)</td>
      <td>Significant Business Impact; Defect resulting in a condition where major functionality is impacted or significant performance degradation is experienced; issue is persistent and affects many Users and/or major functionality.</td>
    </tr>

    <tr>
      <td>3 (normal)</td>
      <td>Minor Feature / Function Issue / General Question; Defect results in a component of Auth0 not performing as expected or documented. An inquiry by Customer representatives regarding general technical issues/questions.</td>
    </tr>

    <tr>
      <td>4 (low)</td>
      <td>Minor Problem / Enhancement Request; Information requested on Auth0 capabilities, navigation, installation, or configuration; enhancement request.</td>
    </tr>
  </tbody>
</table>

**Auth0 Enterprise and Premier Support Defect Response**

The priority of a Defect will determine the timing and nature of the response as specified in the table below:

<table>
  <thead>
    <tr>
      <th>Defect Severity Level</th>
      <th>Target Response Time (Enterprise)</th>
      <th>Target Response Time (Premier)</th>
      <th>Solution Definition (one or more of the following)</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>1 (urgent)</td>
      <td>30 minutes</td>
      <td>30 minutes</td>
      <td>• Issue is resolved <br /> • Workaround is provided <br />• Fix is provided <br />• Fix incorporated into future release</td>
    </tr>

    <tr>
      <td>2 (high)</td>
      <td>2 hours</td>
      <td>1 hour</td>
      <td>• Issue is resolved <br /> • Workaround is provided <br />• Fix is provided <br />• Fix incorporated into future release</td>
    </tr>

    <tr>
      <td>3 (medium)</td>
      <td>12 hours</td>
      <td>8 hours</td>
      <td>• Issue is resolved <br /> • Workaround is provided <br />• Fix incorporated into future release<br />• Answer to question is provided</td>
    </tr>

    <tr>
      <td>4 (low)</td>
      <td>24 hours</td>
      <td>12 hours</td>
      <td>• Answer to question is provided <br />• Enhancement request logged</td>
    </tr>
  </tbody>
</table>

**Auth0 Enterprise and Premier Support Hours**

Okta Support hours for Defects are specified in the table below and will based on the specific Support Program that the Customer has subscribed to, or as specified in the applicable Order Form:

<table>
  <thead>
    <tr>
      <th>Enterprise Support</th>
      <th>Premier Support</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>7 x 24 x 365 for Severity Level 1 Defects; and 24 hours a day, Monday to Friday Customer local time, for all other Severity Levels</td>
      <td>7 x 24 x 365 for all Severity Levels</td>
    </tr>
  </tbody>
</table>


# Manage Subscriptions
Source: https://auth0.com/docs/troubleshoot/customer-support/manage-subscriptions

Describes how to upgrade or change your Auth0 subscription.

If you have an Enterprise subscription plan, please refer to your Auth0 agreement for details.

If you have a Self-Service subscription plan, you can manage your subscription plan from the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>:

1. Go to [Teams > Settings](https://accounts.auth0.com) for Team-based subscriptions OR [Dashboard > Settings](https://manage.auth0.com/#/tenant/general) for Tenant-based subscriptions.
2. Select the **Subscription** tab. You can customize your plan options like monthly or yearly billing, the maximum number of supported monthly Active Users, and more.

<Frame>
  <img alt="Auth0 Tenant Settings Subscription tab" />
</Frame>

Starting 1 December 2023, any Tenant-based subscription updates (except downgrades to Free) automatically converts to a Team-based subscription, allowing you benefits such as the ability to [link multiple tenants](/docs/get-started/auth0-teams/tenant-management) within a single Self-Service subscription.

If you already have a Team-based subscription, instead of upgrading another tenant, you will have to instead link your tenant to the existing Team subscription.

## Upgrade subscriptions

You can upgrade your subscription from a Free plan to an Essentials or a Professional plan or from an Essentials to a Professional. To upgrade to an Enterprise plan, [contact Auth0 Sales](https://auth0.com/get-started?place=header\&type=button\&text=talk%20to%20sales).

1. On the **Subscription** tab, scroll to the panels describing the plan options.
2. Select a new plan and click **Checkout** to upgrade. If you do not have your billing information stored with Auth0, you'll need to provide it.
3. Click **Subscribe Now** to confirm your information and activate your new subscription.

## Downgrade to a Free subscription

1. On the **Subscription** tab, scroll to the box associated with the Free plan and click **Checkout**.
2. To confirm your subscription change, click **Subscribe Now**.

## Learn more

* [Downgrade or Cancel Auth0 Subscriptions](/docs/troubleshoot/customer-support/manage-subscriptions/downgrade-or-cancel-subscriptions)
* [Delete or Reset Tenants](/docs/troubleshoot/customer-support/manage-subscriptions/delete-or-reset-tenant)
* [Link Multiple Tenants to a Single Subscription](/docs/get-started/auth0-overview/create-tenants/child-tenants)
* [Remove Tenant Members](/docs/get-started/manage-dashboard-access/remove-dashboard-users)
* [Tenant Settings](/docs/get-started/tenant-settings)
* [Reset Account Passwords](/docs/troubleshoot/customer-support/reset-account-passwords)


# Delete or Reset Tenants
Source: https://auth0.com/docs/troubleshoot/customer-support/manage-subscriptions/delete-or-reset-tenant

Learn how to delete your tenant or reset it to the default configuration.

You can delete your Auth0 tenant or reset it to the default configuration in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. You can delete your Auth0 account data with assistance from Auth0 Support.

## Delete tenant

<Warning>
  Deleting a tenant is an irreversible, destructive action and cannot be undone. Deleted tenants cannot be restored, the tenant name cannot be reused when creating a new tenant, and metrics related to the tenant are lost.
</Warning>

Before you delete a tenant, consider the following options:

* [Change tenant ownership](/docs/get-started/manage-dashboard-access).
* [Reset tenant configuration](#reset-tenant-configuration).

### Remove custom domain

If you configured a <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip> for a tenant you'd like to delete, you need to remove the custom domain first. If you do not, you cannot configure the custom domain for another tenant.

### Determine deletion process

The process for deleting a tenant depends on the [subscription plan](https://www.auth0.com/pricing) it's associated with and the [type of tenant](/docs/get-started/auth0-overview/create-tenants/child-tenants) it is (main or child). You may be able to delete the tenant in the [Auth0 Dashboard](#delete-tenant-in-auth0-dashboard), or you may need to [contact Auth0 Support or Community](#contact-auth0-support-or-community).

<table>
  <thead>
    <tr>
      <th />

      <th><strong>Free Plan</strong></th>
      <th><strong>Self-service plan</strong></th>
      <th><strong>Enterprise plan</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>Main tenant</strong></td>
      <td>Auth0 Dashboard</td>
      <td>Auth0 Dashboard</td>
      <td>Contact Auth0 Support</td>
    </tr>

    <tr>
      <td><strong>Main tenant with child tenants</strong></td>
      <td>Contact Auth0 Community</td>
      <td>Contact Auth0 Support</td>
      <td>Contact Auth0 Support</td>
    </tr>

    <tr>
      <td><strong>Child tenant</strong></td>
      <td>Auth0 Dashboard</td>
      <td>Auth0 Dashboard</td>
      <td>Auth0 Dashboard</td>
    </tr>
  </tbody>
</table>

### Downgrade tenant

Before you can delete a tenant in the Dashboard, you must downgrade it to the Free plan. To learn more, read [Downgrade or Cancel Auth0 Subscriptions](/docs/troubleshoot/customer-support/manage-subscriptions/downgrade-or-cancel-subscriptions).

### Delete tenant in Dashboard

You can delete a tenant in the Dashboard if you have the [appropriate level of access](/docs/get-started/manage-dashboard-access/feature-access-by-role).

1. Go to [Dashboard > Settings](https://manage.auth0.com/#/tenant/advanced), and then switch to the **Advanced** view.
2. Locate **Danger Zone** at the bottom of the page, and then select **Delete**.
3. Review the confirmation prompt and confirm that you want to permanently delete your tenant.
4. Select **Yes, Delete Tenant**.

### Contact Auth0 Support or Community

If your tenant is on a Trial, Essential, Professional, or Enterprise plan and you cannot delete your tenant in the Auth0 Dashboard, [open a ticket with Auth0 Support](/docs/troubleshoot/customer-support/open-and-manage-support-tickets) for assistance.

If your tenant is on a Free plan and you cannot delete it in the Auth0 Dashboard, [post in Auth0 Community](https://community.auth0.com/) and ask for assistance.

## Reset tenant configuration

You can reset your tenant to its default configuration with the [Auth0 Deploy CLI](https://github.com/auth0/auth0-deploy-cli).

The Deploy CLI is a tool that helps you manage your Auth0 tenant configuration. It integrates into your development workflows as a standalone CLI or as a node module. To learn more about the Deploy CLI tool and how to get started, read [Deploy CLI Tool](/docs/deploy-monitor/deploy-cli-tool).

## Delete Auth0 account data

If you want to delete your Auth0 account data (including email address, billing information, and so on), follow the steps to delete your tenant, and then [post in Auth0 Community](https://community.auth0.com/) and ask for assistance.

To learn more about Auth0's responsibilities as a data controller, read the [Okta Privacy Policy](https://www.okta.com/privacy-policy/).

## Learn more

* [Downgrade or Cancel Auth0 Subscriptions](/docs/troubleshoot/customer-support/manage-subscriptions/downgrade-or-cancel-subscriptions)
* [Export Data](/docs/troubleshoot/customer-support/manage-subscriptions/export-data)


# Downgrade or Cancel Auth0 Subscriptions
Source: https://auth0.com/docs/troubleshoot/customer-support/manage-subscriptions/downgrade-or-cancel-subscriptions

Describes how to downgrade or cancel your Auth0 subscription.

You can downgrade or cancel your Auth0 subscription at any time, and may be eligible for a credit on your next billing cycle or a refund depending on the circumstances.

## Self-service plans

If you are subscribed to an Essential or Professional plan, you can downgrade or cancel your subscription in the [Auth0 Dashboard](https://manage.auth0.com/#).

### Downgrade or cancel plan

1. Go to [Dashboard > Settings](https://manage.auth0.com/#/tenant), and then switch to the **Subscription** view.
2. Locate the plan you'd like to downgrade to, and then select **Downgrade**.
3. If you want to cancel your plan, locate the **Free** plan, and then select **Downgrade**.

   <Frame>
     <img alt="Auth0 Tenant Settings Subscription tab" />
   </Frame>
4. To confirm your subscription change, select **Subscribe Now**.

### Request credit or refund

If you downgrade or cancel your Auth0 subscription, you may be eligible for a credit on your next billing cycle or a refund. To learn more, read our [Billing Policy](/docs/troubleshoot/customer-support/operational-policies/billing-policy).

## Enterprise plans

Once your Enterprise Subscription Period ends, the system automatically downgrades your account to the Free Plan. For assistance during this transition, contact your Technical Account Manager (TAM) and then [open a ticket with Auth0 Support](/docs/troubleshoot/customer-support/open-and-manage-support-tickets).

## Learn more

* [Delete or Reset Tenants](/docs/troubleshoot/customer-support/manage-subscriptions/delete-or-reset-tenant)


# Export Data
Source: https://auth0.com/docs/troubleshoot/customer-support/manage-subscriptions/export-data

Describes how to export data from Auth0.

All data in your Auth0 tenant is always under your control and is available through the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> at any time.

## User passwords

The only information which is not available through the API (for security reasons) are the password hashes of your Auth0-hosted database users and private keys. You can still request this information by opening a [support ticket](https://support.auth0.com). This operation is not available for our Free subscription tier, and we are unable to accept or guarantee requests for exports at a specific time and date.

If you store user passwords in your database, set up a custom database connection which Auth0 will query each time a user logs in. In this case, Auth0 will never store any password hashes, unless you choose to progressively migrate users to Auth0.

## Auth0 components

Auth0 primarily uses <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) as its authentication protocol, so you should be able to implement an integration to your application using standard libraries. The same situation applies when integrating Auth0 through [SAML](/docs/authenticate/single-sign-on/outbound-single-sign-on/configure-auth0-saml-identity-provider). All of Auth0's SDKs, libraries, and samples [are published on GitHub as free software](https://github.com/auth0/).

## Social identity providers

If you choose not to use Auth0 but want to keep using the same <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> <Tooltip href="/docs/glossary?term=client+IDs">client IDs</Tooltip> and secrets for your social <Tooltip href="/docs/glossary?term=identity+providers">identity providers</Tooltip>, you will retain access to user information without needing to display new consent dialogs.

## Custom code

All of Auth0's custom code features (rules, custom database scripts, custom OAuth connections, and so on) run on a Node.js sandbox service. All libraries available on the sandbox service are also available on npm for use with standard Node.js code.

## Additional resources

* [Auth0 Availability and Trust](https://auth0.com/availability-trust)
* [Data Security and Confidentiality Policies](https://auth0.com/security)

## Learn more

* [Data Export and Transfer Policy](/docs/troubleshoot/customer-support/operational-policies/data-export-and-transfer-policy)
* [Delete or Reset Tenants](/docs/troubleshoot/customer-support/manage-subscriptions/delete-or-reset-tenant)


# Monitor Subscription Usage
Source: https://auth0.com/docs/troubleshoot/customer-support/manage-subscriptions/monitor-subscription-usage

Learn how to monitor your Auth0 subscription usage.

Your Auth0 subscription plan determines the user limits and features are that are available for you.

## Quota utilization

You can view subscription utilization information from Auth0 Support Center by visiting [Reports > Quota Utilization](https://support.auth0.com/reports/quota). The subscription utilization information is available with the following details:

* User Consumption

  * Active Users
* Feature Consumption

  * Enterprise Connections
  * Machine to Machine Authentication
  * Multi-factor Authentication

<Frame>
  <img alt="Reports showing subscription feature usage" />
</Frame>

Each high level summary card shows the current month utilization against the available subscription limit. It also offers a drill down interaction (by clicking the card) to view further details such as breakdown of usage by Auth0 Private Instance (if applicable) and Tenant for up to past 12 months.

There is also an option to download a CSV to export this data if required.

<Frame>
  <img alt="" />
</Frame>

### Active Users

You can use this to get a count of unique users with an active event (login or signup) for a given calendar month. There is an ability to drill down and get a breakup of these active users by a Tenant and Private Auth0 Instance (if applicable) for up to 12 past months.

### Enterprise connections

An [Enterprise connection](/docs/authenticate/enterprise-connections) is considered active if (during the current month) it has both:

* Been enabled for an application.
* Had user activity (for example, login, sign-up, or token exchange).

If an Enterprise connection was never enabled for any application, or was enabled but did not have any user activity during the current month, it is not considered active.

You can use this report to get a count of active enterprise connections for a given calendar month with an breakdown of active connections by Private Auth0 Instance (if applicable) as well as count of active users by an active enterprise connection and tenant.

<Callout icon="file-lines">
  The Okta Workforce Enterprise connection is not counted toward your active Enterprise connections limit.
</Callout>

### Machine to Machine Auth

This report provides a count of <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> issued for the [Client Credentials Flow](/docs/get-started/authentication-and-authorization-flow/client-credentials-flow), also referred to as API Authentication Calls, per calendar month excluding any tokens issued for Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.

You can view the count of Authentication Calls by Private Auth0 Instance (if applicable) and Tenant.

For tenants in Auth0 Public Cloud deployment option the report also provides a breakdown of Authentication Calls by Tenant Application for the past 7 days.

### Multi-factor Auth

There are two reports for Multi-factor Auth (<Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip>) usage which present a count of MFA events (enrolments or challenges) by calendar month.

Enterprise MFA counts are MFA events related to push notifications, WebAuthn and one-time codes generated by SMS, Email or Phone. Pro MFA counts are MFA events related to one-time code apps like Google Authentication or Cisco DUO.

Both these report types provide a breakdown of MFA counts by Auth0 Private Instance\* (if applicable) and Tenant.

\*Auth0 Private Instance MFA usage is only available since 1st January 2023.

***

## Tenant Usage

You can view total and active user counts by calendar month from Auth0 Support Center for a given tenant by visiting [Reports > Usage](https://support.auth0.com/reports/usage), and selecting a Subscription (and a Tenant for self-service subscriptions). This would provide the following breakdown:

* Active Users: Count of active users by month and user type (Social, Password, <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip>, Enterprise) along with a Total Active count.
* Active Users by Tenant: Count of active users by month, tenant, and user type (Social, Password, Passwordless, Enterprise) along with a Total Active count.
* Total Users by Tenant

<Frame>
  <img alt="Support Center -> Reports -> Usage" />
</Frame>

<Callout icon="file-lines">
  Counts of Total Active or Total Users can be higher than the sum of users by each individual type for situations where user type is not determined. This can happen, but is not limited to, scenarios where account linking is turned on.
</Callout>

## Learn more

* [Manage Subscriptions](/docs/troubleshoot/customer-support/manage-subscriptions)
* [Auth0 Dashboard](/docs/get-started/auth0-overview/dashboard)
* [Enterprise Connections](/docs/authenticate/enterprise-connections)
* [Tenant Settings](/docs/get-started/tenant-settings)


# Open and Manage Support Tickets
Source: https://auth0.com/docs/troubleshoot/customer-support/open-and-manage-support-tickets

Describes how to open and manage tickets with Support Center.

Use [Auth0 Support Center](https://support.auth0.com) to create tickets for questions or issues. All tenant member roles can access Support Center.

If you are an existing Private Cloud customer, you need to create an Auth0 public cloud-based tenant, also known as the "Support Tenant", to log in to the Support Center. This tenant can also be used for development and test purposes at no additional cost. Please contact your Technical Account Manager or Sales Executive to associate your public cloud-based tenant to your existing Private Cloud subscription.

<Frame>
  <img alt="Open and Manage Tickets Open Ticket Screen" />
</Frame>

## Open a new ticket

1. Go to [Support Center](https://support.auth0.com) and select **Open Ticket**.

   <Callout icon="file-lines">
     If you don't see this button, then you do not have access to open support tickets (only paying and trial customers have access to open support tickets). In this case, select **Ask our Community** to use our [Community](https://community.auth0.com/) resources.
   </Callout>
2. Select the tenant you need help with from the **Affected Tenant** dropdown menu.
3. Under **What can we help you with?**, select the type of issue that best fits your case.
4. If prompted, choose the appropriate [severity level](#severity-levels) (not available for trial tenant customers).
5. Provide a clear summary of the request or issue in the **Request Summary** field.
6. Provide as much detail as possible about the issue or request in the **Description** box. When writing in this box, you can style your text with [Markdown](https://guides.github.com/features/mastering-markdown) and preview what you have written by clicking **Preview**. When writing your description, please try to include the following information when it applies:

   1. What were you trying to do?
   2. What did you expect to happen?
   3. Where did things go wrong?
   4. Were there any error messages or screenshots showing the problem? If so, please include them.
   5. Has this worked before, or are you trying a new configuration?
   6. Does the problem occur for all users or just a few?
   7. What troubleshooting steps have you tried?
7. When you have completed all the fields, select **SUBMIT**.

### Severity levels

<table>
  <thead>
    <tr>
      <th><strong>Level</strong></th>
      <th><strong>Type</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>1 (Urgent)</strong></td>
      <td>Emergency Issue</td>
      <td>Defect resulting in full or partial system outage or a condition that makes the Auth0 Platform unusable or unavailable in production for all of your Users.</td>
    </tr>

    <tr>
      <td><strong>2 (High)</strong></td>
      <td>Significant Business Impact</td>
      <td>Defect resulting in a condition where major functionality is impacted or significant performance degradation is experienced; issue is persistent and affects many Users and/or major functionality.</td>
    </tr>

    <tr>
      <td><strong>3 (Normal)</strong></td>
      <td>Minor Feature/Function Issues/General Question</td>
      <td>Defect results in a component of the Auth0 Platform not performing as expected or documented or an inquiry by your representatives regarding general technical issues/questions.</td>
    </tr>

    <tr>
      <td><strong>4 (Low)</strong></td>
      <td>Minor Problem/Enhancement Request</td>
      <td>Information requested on Auth0 Platform capabilities, navigation, installation, or configuration; enhancement request.</td>
    </tr>
  </tbody>
</table>

## Update an existing ticket

1. Go to the [Support Center](https://support.auth0.com) page and select **Home**.
2. Select the ticket that you want to update by selecting its **Request Summary**.
3. Enter any additional details into the text box and then select **REPLY**.

If you are the ticket requester and the ticket is assigned to an agent but is not solved or closed, you have the option to change the status of your ticket to **Solved** by checking the **Submit as solved** box next to the **REPLY** button.

## Reopening a closed ticket

If your ticket has been closed but you'd like to continue working with Auth0 on the issue, create a new Support Center ticket. Be sure to include the reference number for the original ticket(s).

<Callout icon="file-lines">
  When a case is closed, Auth0 permanently deletes all file attachments for security purposes.
</Callout>

## Manage subscription tickets

<Callout icon="file-lines">
  To manage subscription tickets, you must have the [Elevated Support Access role](/docs/get-started/manage-dashboard-access/feature-access-by-role) assigned to you.

  If you are a Tenant Administrator, you can assign the Elevated Support Access role to yourself to see all tickets opened by all users on your tenants.
</Callout>

To manage subscription tickets:

1. Go to [Auth0 Support Center](https://support.auth0.com)
2. Select **Tickets** from the navigation menu.
3. Switch to the **Subscription Tickets** view.

## Learn more

* [Manage Dashboard Access](/docs/get-started/manage-dashboard-access)
* [Service Levels](/docs/troubleshoot/customer-support/services-level-descriptions)
* [Update Dashboard User Email Addresses](/docs/get-started/manage-dashboard-access/update-dashboard-user-email)
* [Troubleshoot Auth0](/docs/troubleshoot)
* [Product Support Matrix](/docs/troubleshoot/customer-support/product-support-matrix)


# Auth0 Operational Policies
Source: https://auth0.com/docs/troubleshoot/customer-support/operational-policies

Describes Auth0's established operational policies including billing, data export and transfer, load and penetration testing, rate limits, tenant restoration, and Dashboard authentication.

Auth0 has established operational policies that govern the following areas.

## Billing

This policy covers change of address, credit card issues, canceling subscriptions, refunds, invoicing, sales tax, scaling users, and tenant conversion. See [Billing Policy](/docs/troubleshoot/customer-support/operational-policies/billing-policy) for details.

## Data export and transfer

If you would like to export your data from Auth0, you can use the [Export/Import Extension](/docs/customize/extensions/authorization-extension/import-and-export-authorization-extension-data) or the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. See [Export Data](/docs/troubleshoot/customer-support/manage-subscriptions/export-data) for details.

Auth0 will not transfer data from one Auth0 tenant to another. This applies to both Public Cloud and Private Cloud customers. All data in your Auth0 tenant is always under your control and is available through the Management API at any time. If you want to stop using our service, you can export your data. See [Data Export and Transfer Policy](/docs/troubleshoot/customer-support/operational-policies/data-export-and-transfer-policy) for details.

## Endpoints

See [Public Cloud Service endpoints](/docs/troubleshoot/customer-support/operational-policies/public-cloud-service-endpoints) and [API Endpoints for Single Sign-On (SSO)](/docs/authenticate/single-sign-on/api-endpoints-for-single-sign-on) for details.

## Load and penetration testing

Only customers who have purchased an Enterprise subscription may conduct load testing. Customers with an Enterprise subscription may request one load test (with up to 2 repeats) per year against an Auth0 production tenant. Performance and load testing is only allowed with Auth0's prior written approval. Once approved, testing can only target tenants that we have approved. See [Load Testing Policy](/docs/troubleshoot/customer-support/operational-policies/load-testing-policy) and [Penetration Testing Policy](/docs/troubleshoot/customer-support/operational-policies/penetration-testing-policy) for details.

To conduct these tests, notify us in advance by submitting a [Support Ticket](https://support.auth0.com). Auth0 requires at least 14 days' notice prior to your test's planned start date.

## Migrations

We apply an iterative approach to product delivery, including an iterative [product release lifecycle](/docs/troubleshoot/product-lifecycle) that allows us to introduce and improve upon new functionality.

When building Auth0 products, we resolve to

* Deliver value to customers early and often, iterating based on their feedback.
* Seek a deep understanding of our customers and consider them in every decision.
* Relentlessly acquire and analyze data, so we can make better choices.
* Visualize and design for current, idealized, and future versions of our whole product when adding features.

To best serve these goals, we apply an iterative approach to product delivery, including an iterative product release lifecycle that allows us to introduce and improve upon new functionality.

* [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages)
* [Migration Process](/docs/troubleshoot/product-lifecycle/migration-process)
* [Deprecations and Migrations](/docs/troubleshoot/product-lifecycle/deprecations-and-migrations)
* [Past Migrations](/docs/troubleshoot/product-lifecycle/past-migrations)

## Rate limits

Actions such as rapidly updating configuration settings, aggressive polling, or making highly concurrent API calls may result in your app being rate limited. See [Rate Limit Policy](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy) for details.

## Entity limits

Entities in Auth0 are tenant configuration elements such as applications, connections, rules, and API <Tooltip href="/docs/glossary?term=resource+servers">resource servers</Tooltip>. Auth0 limits the number of entities you can have depending on the platform for your subscription level group. See [Entity Limit Policy](/docs/troubleshoot/customer-support/operational-policies/entity-limit-policy) for details.

## Sanitize HAR files

If you contact [Auth0 Support](https://support.auth0.com), you may need to include a sanitized HAR file for troubleshooting help.

<Warning>
  Before sharing a HAR file with anyone (including Auth0), ensure that you remove or obfuscate all sensitive data, such as:

  * Confidential user information
  * Personal identifiable information (PII)
  * Confidential application information

  To learn more, read the following articles on [Auth0 Community](https://community.auth0.com):

  * [Sanitizing HTTP Traces](https://community.auth0.com/t/sanitizing-http-traces/119488)
  * [How to Sanitize an HTTP Trace File Automatically](https://community.auth0.com/t/how-to-sanitize-a-http-trace-file-automatically/120583)
  * [How to Manually Redact Sensitive Information](https://community.auth0.com/t/how-to-manually-redact-sensitive-information/122554)
  * [HAR File is Too Large to Upload to the Support Case](https://community.auth0.com/t/har-file-is-too-large-to-upload-to-the-support-case/122488)
</Warning>

## Tenant restoration

<Warning>
  You **cannot** restore a deleted tenant and you **cannot** reuse a tenant name when creating new tenants.
</Warning>

**Before you delete your tenant, please review the following resources for alternative options:**

* [Update Tenant Administrator](/docs/get-started/manage-dashboard-access) - for changing tenant ownership
* [Delete or Reset Tenants](/docs/troubleshoot/customer-support/manage-subscriptions/delete-or-reset-tenant) - for resetting tenant configuration

If you've already deleted your tenant and you require the use of a particular domain name, we recommend configuring a [custom domain name](/docs/customize/custom-domains) for your new tenant.

## Private Cloud Restoration

Private Cloud Restoration allows customers to recover their space from data loss and corruption. This flexibility is available through an add-on SKU.

Customers can request restoration of a production Private Cloud space from a backup within the past 14 days through a [support ticket](https://support.auth0.com/). The restoration is performed using backup data maintained by Auth0. The full Private Cloud space will be restored to the closest available backup within the customer's requested time of restoration. The Disaster Recovery RPO noted in the Private Cloud contract is applicable. Non backwards-compatible capabilities and deprecations could introduce limitations on restoration possibilities. Customers are responsible for functional validation of the environment post-restoration.

One test restoration over a non-production Private Cloud space is supported per year for customers purchasing this SKU.

## Unsupported requests

Our support team strives to assist you to the best of our ability. However, we are currently unable to grant the following requests:

* Transfer data from a non-production to a production account
* Remove a tenant admin
* Rename a tenant
* Rename a connection
* Re-use the name of a previously-deleted tenant
* Migrate a tenant from one region to another (for example, from US to EU)
* Ad hoc usage data reports
* Restore any deleted or modified data or settings in tenants, including

  * Database connections and their users and passwords
  * Users, their profile information, metadata, and role memberships
  * Roles and permissions
  * Application
  * SSO integrations
  * APIs
  * Connections
  * Actions
  * Rules
  * Hooks
  * Extensions
  * Email templates
  * Tenant logs once the [standard retention time](/docs/deploy-monitor/logs/log-data-retention) has passed

## Learn more

* [Billing Policy](/docs/troubleshoot/customer-support/operational-policies/billing-policy)
* [Data Export and Transfer Policy](/docs/troubleshoot/customer-support/operational-policies/data-export-and-transfer-policy)
* [Rate Limit Policy](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy)
* [Entity Limit Policy](/docs/troubleshoot/customer-support/operational-policies/entity-limit-policy)
* [Auth0 Public Cloud Service Endpoints](/docs/troubleshoot/customer-support/operational-policies/public-cloud-service-endpoints)


# Billing Policy
Source: https://auth0.com/docs/troubleshoot/customer-support/operational-policies/billing-policy

Describes the billing policy which governs requests for billing mechanisms within the Auth0 Dashboard

The following policy governs requests for billing mechanisms within the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>.

## Change billing email address

The billing email address is automatically set to the Team Owner (for Team based subscriptions) or Tenant Admin (for legacy Tenant based subscriptions) when upgrading to a paid plan.

As a Team Owner, you can modify the billing email address in [**Teams Dashboard > Setting > Payment & Billing**](https://manage.auth0.com/#/tenant/) tab for Team based subscriptions.

For legacy Tenant based subscriptions, as a Tenant Admin, you can modify the billing email address by visiting the [**Auth0 Dashboard > Settings > Payment & Billing**](https://manage.auth0.com/#/tenant/)**.**

## Credit card issues

To determine the reason for the failure, you must contact your credit card company. Billing issues can be triggered by a credit card reaching the limit or simply being rejected by the bank.

If your credit card charge fails, we automatically retry to charge it up to 4 times. If you fix the issue before the fourth failure (by entering new card information or by solving the issue with the bank), then the charge will go through and everything will work as expected. However, if the problem is not fixed prior to the fourth failure, all past due invoices will be manually initiated by Auth0. This means that you may be charged on an unexpected date.

## Cancel subscription

To cancel your subscription, downgrade it to the Free plan in the Auth0 Dashboard. To learn more, read [Downgrade or Cancel Subscriptions](/docs/troubleshoot/customer-support/manage-subscriptions/downgrade-or-cancel-subscriptions).

## Credits and refunds

If you cancel your subscription, you may be eligible for a credit or refund depending on the circumstances.

### Unused tenants

Tenants with minimal login transaction history may be eligible for a credit or refund. If we consider the usage of the tenant to not be minimal, Auth0 reserves the right to deny the credit or refund request.

Auth0 does not provide credits or refunds when a tenant on a paid plan is downgraded to another paid plan with fewer features.

### Unneeded self-service plans

Tenants with no recorded login transactions may be eligible for a credit or refund for any unused portion of the subscription within the last three (3) months.

### Request a credit or refund

You can request a credit or refund by contacting Okta Accounts Receivable at `ar@okta.com` and providing the following information:

* Subscription plan that your tenant was on before downgrade or cancellation.
* Date of downgrade or cancellation.
* Brief description of reason for downgrade or cancellation.

Requests must be submitted by a Tenant Administrator and are subject to evaluation and verification by Okta.

## Invoices

<Warning>
  If you change your subscription plan, your invoices automatically migrate from a tenant-based billing model to the account-based model provided by [Auth0 Teams](/docs/get-started/auth0-teams).

  Be aware of the following limitations before you migrate:

  * **Invoice history**: After you migrate, all previous tenant-based invoices are unavailable. Download any old invoices that you need to record before migrating. If you need assistance, contact [Auth0 Support](https://support.auth0.com).
  * **Tax IDs**: After an account-based invoice has been generated with a given Tax ID, it cannot be regenerated with a new Tax ID.
  * **Invoice numbers**: Account-based invoice numbers are 11-digit alphanumeric values.
</Warning>

### Account-based

If you are using [Auth0 Teams](/docs/get-started/auth0-teams), your subscriptions and invoices are managed on the account level.

<Callout icon="file-lines">
  Only Team Owners can view invoices.
</Callout>

You can view invoices in the Auth0 Dashboard:

1. Go to your [Team dashboard](/docs/get-started/auth0-teams/tenant-management), and then select **Settings**.
2. Switch to the **Payment & Billing** view.
3. Locate the **Payment History** section.
4. Select an invoice from the list.

### Tenant-based

<Callout icon="file-lines">
  Only Tenant Administrators can view invoices.
</Callout>

You can view invoices in the Auth0 Dashboard:

1. Go to [Tenant Settings](https://manage.auth0.com/#/tenant).
2. Switch to the **Payment & Billing** view.
3. Locate the **Payment History** section.
4. Select an invoice from the list.

## Receipts

You can obtain receipts by filing a ticket through our [Support Center](https://support.auth0.com). Please note that you have to be a Tenant admin to do this request. Auth0 sends receipts to the email entered when you created your tenant. If you want to change this setting, please let us know through our [Support Center](https://support.auth0.com).

## Taxes

For certain regions, depending on tax laws and requirements, Auth0 is required to charge tax on invoices.

If your billing address is tax-eligible, you'll see the applicable tax added to your total during checkout. You will also see the applicable tax amount on all of your Auth0 invoices and receipts.

## Charges for users

You can choose a subscription plan based on your use case and the type of users who access your application. For information on subscriptions plans, see [Auth0 Pricing](https://auth0.com/pricing/).

An active user is a user that has authenticated with a username/password combination, a <Tooltip href="/docs/glossary?term=Passwordless">Passwordless</Tooltip> connection, or any social provider during a given calendar month. Auth0 counts users on a per-tenant basis. A user who logs in to multiple applications on the same tenant counts as one user.

You can scale the number of users as needed each month.

1. In the Dashboard, go to the upper right corner, click on your tenant name, and select **Settings** from the drop-down menu.
2. In the **Subscriptions** tab, select the option that best suits your needs.

## Combine billing for multiple tenants

If you have an Enterprise or upgraded Self service subscription, then use [Auth0 Teams](/docs/get-started/auth0-teams) to combine billing for multiple tenants under a single subscription.

To learn more about linking multiple tenants under a single subscription, read [Link Multiple Tenants to a Single Subscription](/docs/get-started/auth0-overview/create-tenants/child-tenants).

## Convert tenant from free trial to any other plan

1. In the Dashboard, go to the upper right corner, click on your tenant name, and select **Settings** from the drop-down menu.
2. In the **Subscriptions** tab, select the plan that best suits your needs.

## Learn more

* [Downgrade or Cancel Auth0 Subscriptions](/docs/troubleshoot/customer-support/manage-subscriptions/downgrade-or-cancel-subscriptions)


# Change Freeze Policy
Source: https://auth0.com/docs/troubleshoot/customer-support/operational-policies/change-freeze-policy

Learn about Auth0's change freeze policy, including currently scheduled periods and testing restrictions.

Auth0 schedules change freeze periods throughout the year to ensure platform stability and resilience.

During these periods, certain customer activities are restricted.

## Upcoming change freeze periods

| Start date        | End date          |
| ----------------- | ----------------- |
| 9 March 2026      | 13 March 2026     |
| 21 September 2026 | 25 September 2026 |
| 25 November 2026  | 2 December 2026   |
| 23 December 2026  | 5 January 2027    |

## Load tests

<Warning>
  Load tests are not allowed during change freeze periods.
</Warning>

Previously-approved load tests scheduled to occur during a change freeze must be rescheduled.

You may request an exception to this policy. Approval of exception requests are subject to the discretion of Auth0.

## Penetration tests

<Warning>
  Penetration tests are not allowed during change freeze periods.
</Warning>

Previously-approved penetration tests scheduled to occur during a change freeze must be rescheduled.

You may request an exception to this policy. Approval of exception requests are subject to the discretion of Auth0.

## Failover tests

<Warning>
  Failover tests are not allowed during change freeze periods.
</Warning>

Previously-approved failover tests scheduled to occur during a change freeze must be rescheduled.

You may request an exception to this policy. Approval of exception requests are subject to the discretion of Auth0.

## Rate limit changes

<Warning>
  Rate limit changes are not allowed during change freeze periods.
</Warning>

Previously-approved rate limit changes scheduled to occur during a change freeze will be applied as scheduled. You may request an exception to this policy.

Approval of exception requests are subject to the discretion of Auth0.

## Request an exception

You can request an exception to this policy through the [Support Center](https://support.auth0.com).


# Data Export and Transfer Policy
Source: https://auth0.com/docs/troubleshoot/customer-support/operational-policies/data-export-and-transfer-policy

Describes Auth0 policies on exporting and transferring data.

## Export data

If you would like to export your data from Auth0 there are a several ways you can do this. Please note these tools do not export password hashes of your Auth0-hosted database users. You can still request this information by opening a [support ticket](https://support.auth0.com/). If you are opting to end your use of our service, see [Export Data](/docs/troubleshoot/customer-support/manage-subscriptions/export-data) for details.

### Use the Import/Export Extension

You can use our [Import/Export Extension](/docs/manage-users/user-migration/user-import-export-extension) to export nearly all data in your Auth0 tenant.

### Use the Management API

If you want to export certain sets of data programmatically, use the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> Bulk User Export endpoint.

## Transfer data

Auth0 will not transfer data from one Auth0 tenant to another. This applies to both Public Cloud and Private Cloud customers.

All data in your Auth0 tenant is always under your control and is available through the Management API at any time. The only information which is not available through the API are the password hashes of your Auth0-hosted database users and private keys, for security reasons.

## Learn more

* [Export Data](/docs/troubleshoot/customer-support/manage-subscriptions/export-data)


# Entity Limit Policy
Source: https://auth0.com/docs/troubleshoot/customer-support/operational-policies/entity-limit-policy

Describes Auth0's tenant entity limit policy for subscribers.

Entities in Auth0 are tenant configuration elements such as Applications, Connections, Organizations, API <Tooltip href="/docs/glossary?term=resource+servers">resource servers</Tooltip>, Permissions, Roles, Actions.

<Warning>
  Entity limits are hard limits on entities that are enforced for the health of our platform; they are not a component of pricing, though they can differ for groups of pricing plans. Individual pricing plans have separate limitations, which refer to the entitlements like MAU and Enterprise Connections you receive when you subscribe to a given plan. (To learn what your pricing plan limitations are, see [Auth0 Pricing](https://auth0.com/pricing/).)
</Warning>

<Callout icon="file-lines">
  Any use of the term "unlimited" means that there are no hard limits, but Okta sets system limitations on the threshold. Please reach out to support if you have any questions on these limits.
</Callout>

## Global Subscription Plan Limits

This section lists limits that apply to all subscription plans.

### Organizations

| Entity                                             | Limit   |
| -------------------------------------------------- | ------- |
| Organizations per Tenant                           | 100,000 |
| Members per Organization                           | 100,000 |
| Connections per Organization                       | 10      |
| Role Assignments per Organization Member           | 50      |
| M2M Client Grants per Organization (Public Cloud)  | 100     |
| M2M Client Grants per Organization (Private Cloud) | 1000    |
| Custom Token Exchange Profiles                     | 100     |

Customers on Enterprise plans can request increased entity limits for Organizations per tenant and Organization members per Organization by [contacting support](https://support.auth0.com/).

These limits can be increased to 2,000,000 Organizations per tenant and 2,000,000 Organization members per Organization on public cloud. On private cloud instances, these entities are unlimited.

### Authorization Core Role-Based Access Control (RBAC)

| Entity                            | Limit |
| --------------------------------- | ----- |
| Roles per Tenant                  | 1000  |
| Scopes per API (Resource Servers) | 1000  |
| Roles per User                    | 50    |
| Permissions per User              | 1000  |
| Permissions per Role              | 1000  |

<Callout icon="file-lines">
  Note that limitations on Permissions per user affect directly assigned Permissions.

  Technically, a user could have more Permissions than noted if you assign the Permissions to different Roles and then assign the Roles to the User.
</Callout>

| Entity                                 | Limit |
| -------------------------------------- | ----- |
| Refresh Token per User per Application | 200   |

<Callout icon="file-lines">
  If you reach the <Tooltip href="/docs/glossary?term=Refresh+tokens">Refresh Tokens</Tooltip> limit and create a new Refresh Token,
  the system revokes or deletes the oldest token for that user in the
  Application.

  Revoked tokens and expired tokens do not count against the limit.
</Callout>

### Actions

| Entity                                       | Limit |
| -------------------------------------------- | ----- |
| Actions per Tenant                           | 100   |
| Actions per Trigger per Tenant               | 20    |
| Actions Modules per Tenant                   | 100   |
| Actions Modules per Action                   | 3     |
| Versions per Action                          | 50    |
| Versions per Action Module                   | 50    |
| Secrets per Action                           | 30    |
| Secrets per Action Module                    | 30    |
| Dependencies (NPM Modules) per Action        | 10    |
| Dependencies (NPM Modules) per Action Module | 10    |

<Callout icon="file-lines">
  Actions and Actions Modules limits include both deployed and undeployed entities. When you delete them, they no longer count toward the specific limit.

  Action Versions and Action Module Versions limits include both draft and active. Once you reach the limit, adding every additional version results in Auth0 deleting the oldest unused version.
</Callout>

### Forms

| Entity           | Limit |
| ---------------- | ----- |
| Forms per Tenant | 500   |
| Flows per Tenant | 500   |

## Subscription Plan

### Enterprise

| Entity                       | Maximum |
| ---------------------------- | ------- |
| API Resource Servers         | 100,000 |
| Applications                 | 100,000 |
| Client Grants                | 100,000 |
| Application Credentials      | 2,000   |
| Concurrent CIBA Transactions | 5,000   |
| Self-Service SSO Profiles    | 20      |

### Self-service

| Entity                       | Maximum |
| ---------------------------- | ------- |
| Applications                 | 100     |
| Client Grants                | 10,000  |
| Connections                  | 100     |
| Rules                        | 10      |
| API Resource Servers         | 100     |
| Concurrent CIBA Transactions | 5,000   |

### Free

<Callout icon="file-lines">
  Free tenants only support a maximum of two social connections.
</Callout>

| Entity                      | Limit |
| --------------------------- | ----- |
| Applications                | 10    |
| Client Grants               | 100   |
| Connections                 | 100   |
| Rules                       | 3     |
| API (Resource Servers)      | 10    |
| Admins (including on Teams) | 3     |


# Load Testing Policy
Source: https://auth0.com/docs/troubleshoot/customer-support/operational-policies/load-testing-policy

Describes Auth0's Load Testing Policy.

**Effective Date**: 4 February 2019

<Callout icon="file-lines">
  For Private Cloud customers, please see [Private Cloud Load Testing Policy](/docs/deploy-monitor/deploy-private-cloud/private-cloud-on-aws#load-testing).
</Callout>

Auth0 recognizes that customers may occasionally need to perform load tests against its production cloud service. In order to ensure a successful test and maintain a high quality of service for all customers, Auth0 has established the following guidelines. Any load testing in Auth0 must be conducted in accordance with this Policy.

Only customers who have purchased an Enterprise subscription may conduct load testing. Customers with an Enterprise subscription may request one load test (with up to 2 repeats) per year against an Auth0 production tenant. Performance and load testing are only allowed with Auth0's prior written approval. Once approved, testing can only target tenants that we have approved.

<Callout icon="file-lines">
  Auth0 reserves the right to reject the load test request or ask for modifications. Failure to abide by this policy may result in temporary blocking of access to a tenant until the issue is remediated.
</Callout>

## Acceptable testing windows

Public cloud customers must arrange to conduct their load tests during the following off-peak test windows:

| Region    | Testing window    |
| --------- | ----------------- |
| `prod-au` | 9:00 - 17:00 UTC  |
| `prod-eu` | 21:00 - 5:00 UTC  |
| `prod-us` | 2:00 - 10:00 UTC  |
| `prod-jp` | 14:00 - 22:00 UTC |
| `prod-ca` | 2:00 - 10:00 UTC  |
| `prod-uk` | 21:00 - 5:00 UTC  |

In very exceptional circumstances, Auth0 may grant exceptions to this rule.

## Change freeze policy

<Warning>
  Load tests are not allowed during change freeze periods.
</Warning>

To view the currently scheduled change freeze periods, read [Change Freeze Policy](/docs/troubleshoot/customer-support/operational-policies/change-freeze-policy).

## Holiday load testing policy

**Updated:** November 1, 2022

During the holiday season, load testing requests must meet the following requirements:

* Be filed at least 2 weeks prior to the desired test date. Four (4) weeks or more of advance notice is preferred to ensure time for a thorough review and any required modifications.
* Approved load tests are permitted only on Tuesdays, Wednesdays and Thursdays during off peak hours for the targeted environment.
* If all RPS requests are determined to be safely within the RPS limits, the load test will be allowed, as long as it has been reviewed and approved by all product/platform teams owning the endpoints being tested.

  * Tests that fall outside the safe RPS will be rejected.
* Only one load test per customer, per environment will be scheduled in a single day.

  * If there’s a need to run more than one test at a time, the request must be escalated and approved by a Platform Director or Vice President.

## Submit load testing request

You can submit a load testing request through the [Auth0 Support Center](https://support.auth0.com).

[Open a new ticket](/docs/troubleshoot/customer-support/open-and-manage-support-tickets), select **Product Support** from the **What can we help you with?** dropdown field, and then provide all the information described below.

<Warning>
  To be considered for approval, you must:

  * Submit your request at least 2 weeks prior to your desired test date.
  * Receive written approval before conducting any testing.
  * Stay within our [published production rate limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy).
</Warning>

### Required load testing information

Your load testing request must include the following information.

#### General

* A description of the test to be done
* Contacts who will be available during the test and how to reach them
* The requested date and time of the test, including time zone
* The requested duration of the test (2 hours maximum)
* The platforms to be used for the test (desktop/laptop, iOS, Android, other)

#### Tenant

* The name and region of the Auth0 tenant to be used during the test

#### Features

* The Auth0 features (such as Actions, Rules, or Email) used during the test
* The types of Auth0 connections involved in the test
* Which Custom DB, if any, will be used
* Whether you are using a <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip>
* Which Auth0 Rules or Actions, if any, will execute during the test
* Which Auth0 Webtasks, if any, will be used
* Whether verification, welcome or other emails will be sent

#### APIs

* The Auth0 API methods and endpoints to be used (for example `GET /api/v2/clients`)
* The maximum requests per second for each type of request or endpoint

#### Users

* Number of unique users participating in the load test

#### Load estimates

* The peak load, specified in requests-per-second, expected for each API endpoint or Auth0 feature involved in the test
* An explanation/justification for the peak load numbers, including the size of the target user population and realistic estimates of logins per hour
* The ramp-up rate for the test
* Number of unique users participating in the load test

## Test requirements

Load testing windows are subject to availability so advance notice is highly recommended. Once approved, load testing windows will have a scheduled start and end time not to exceed two (2) hours in duration. All testing must begin and end during this window. During the load test, configure your IPs to rotate so your test does not bump into [IP-based rate limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy).

Auth0 strongly recommends including a brief "ramp-up" period to the desired load test target numbers. For example, a load test request of 100 RPS might be preceded by three five-minute periods: 5 minutes at 25 RPS, 5 minutes at 50 RPS, and 5 minutes at 75 RPS. This ramp-up period allows Auth0 and the customer to observe and compare effects at increasing RPS levels prior to peak RPS. If a ramp-up period is not possible, please indicate why.

### Configure email provider

Before any testing, you must:

* Configure your own email provider in Auth0
* Receive approval from your email provider to send the expected volume of email
* Make arrangements for bounced emails
* Establish a mechanism for testing that emails arrived

## Learn more

* [Auth0 Professional Services](/docs/get-started/professional-services)


# Penetration Testing Policy
Source: https://auth0.com/docs/troubleshoot/customer-support/operational-policies/penetration-testing-policy

Describes Auth0's Penetration Testing Policy.

If you have a paid Auth0 subscription, you may conduct a security test of your application involving Auth0 infrastructure (e.g. `your-tenant.auth0.com`) with prior approval.

## Submit penetration testing request

To conduct a security test, please notify us in advance via the [Support Center](https://support.auth0.com). Auth0 requires at least 7 days notice prior to your test's planned start date.

If the test is isolated to your infrastructure (that is, there will be no testing of Auth0 services), you do not need to notify Auth0.

### Information required

Please provide the following information in the support ticket when requesting approval for testing:

* The specific dates/times of the test and timezone. Tests are not allowed during a change freeze period. To learn more, read the change freeze penetration testing policy below.
* Scope and purpose of the test
* IP address(es) the test will come from
* Tooling that is planned to be used
* Request per second (the test must be conformant with the [Rate Limit Policy](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy))
* The Auth0 tenant(s) involved
* Two contacts - phone number and email -  who will be available during the entire test period in case we need to contact you. If we have any questions, we will make a reasonable attempt to contact you. If you cannot be reached, we reserve the right to take measures to protect the service, which may include shutting down or blocking your tenant and/or the source of the intrusion traffic.

## Change freeze policy

<Warning>
  Penetration tests are not allowed during change freeze periods.
</Warning>

To view the currently scheduled change freeze periods, read [Change Freeze Policy](/docs/troubleshoot/customer-support/operational-policies/change-freeze-policy).

## Test requirements

Auth0 requires that:

* The test be restricted to only your tenant
* The test requests per second must not exceed rates defined in our [Rate Limit Policy](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy)
* You disclose any suspected findings to the Auth0 Security team for explanation/discussion

## Reporting Identified Vulnerabilities

To report any identified vulnerabilities, please read the [Vulnerability Reporting Policy](https://www.okta.com/vulnerability-reporting-policy/).

## Restrictions

* You may not conduct any [load testing](/docs/troubleshoot/customer-support/operational-policies/load-testing-policy) (such as Denial of Service testing) per the load testing policy.
* You may not conduct any penetration testing targeting our management dashboard. Management and Authentication APIs are allowed.
* You may not conduct any penetration testing targeting tenants that we have not approved.

## Private Cloud customers

Private Cloud customers should also request permission to run a penetration test via the Auth0 support center. Please include the information listed above with your support request.

## Learn more

* [Load Testing Policy](/docs/troubleshoot/customer-support/operational-policies/load-testing-policy)


# Auth0 Public Cloud Service Endpoints
Source: https://auth0.com/docs/troubleshoot/customer-support/operational-policies/public-cloud-service-endpoints

Lists all the endpoints used by Auth0 public cloud service.

The following endpoints are used by Auth0 public cloud service:

## United States Region

* [https://manage.auth0.com](https://manage.auth0.com)
* [https://auth0.com](https://auth0.com)
* [https://auth0.auth0.com](https://auth0.auth0.com)
* [https://login.us.auth0.com](https://login.us.auth0.com)
* [https://cdn.us.auth0.com](https://cdn.us.auth0.com)
* https\://.us.auth0.com
* https\://.guardian.us.auth0.com

<Callout icon="file-lines">
  The CDN URL varies by region. Tenants created before 11 June 2020 should use `https://cdn.auth0.com` if the region is the United States, or add `eu`, `au`, `jp` for Europe, Australia, or Japan. If your tenant was created after 11 June 2020, use `https://cdn.us.auth0.com` if the region is the United States.
</Callout>

## Australia, Canada, Europe, Japan and UK regions

* [https://manage.auth0.com](https://manage.auth0.com)
* [https://auth0.com](https://auth0.com)
* [https://auth0.auth0.com](https://auth0.auth0.com)
* `https://login.[au|ca|eu|jp|uk].auth0.com`
* `https://cdn.[au|ca|eu|jp|uk].auth0.com`
* `https://{yourAccount}.[au|ca|eu|jp|uk].auth0.com`
* `https://{yourAccount}.guardian.[au|ca|eu|jp|uk].auth0.com`

## Learn more

* [Auth0 IP Addresses for Allow Lists](/docs/secure/security-guidance/data-security/allowlist)


# Rate Limit Policy
Source: https://auth0.com/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy

Describes Auth0's rate limit policy.

Auth0 limits the use of services to assure optimal performance and protection from <Tooltip href="/docs/glossary?term=bad+actors">bad actors</Tooltip>, technical errors, or excessive legitimate traffic.  We recommend you review how Auth0 enforces limits to configure your application for the best user experience.

<Callout icon="file-lines">
  To find rate limits associated with your account, see [Rate Limit Configurations](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations) for a matrix of all rate limit policies.
</Callout>

## Introduction to Rate Limits

Auth0 enforces limitations to protect services from excessive requests and protect customers from service interruptions or degradation.

Auth0 observes, and in many cases, enforces an array of limits, including:

* Requests to environments (Private Cloud Only)
* Requests to tenants via API or API Endpoint
* Miscellaneous Limits

### Environment request limits (Private Cloud Only)

In Private Cloud, environment request limits are based on the Private Cloud Performance Tier.  To learn more, read [Private Cloud for AWS](/docs/deploy-monitor/deploy-private-cloud/private-cloud-on-aws) or [Private Cloud for Azure](/docs/deploy-monitor/deploy-private-cloud/private-cloud-on-azure).

Currently,  Private Cloud environment rate limits represent the highest load under which the Auth0 product will meet SLAs.  However, at this time, Auth0 only enforces and notifies customers when rate limits have been exceeded on a specific tenant within the environment.  Under most Private Cloud use cases, where customers maintain a single Production Tenant, this is not a problem; however, use cases that provision more than one production tenant should consider the expected load across all tenants in the environment and implement additional monitoring as necessary.

<table>
  <thead>
    <tr>
      <th><strong>Feature</strong></th>
      <th><strong>Authentication API</strong></th>
      <th><strong>All Other APIs (including Management API)</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Tenant Rate Limits</td>
      <td>All tenants consume from a shared, environment-wide global limit for the API, but the environment rate limit is a hard cap. Exceeding the environment limit due to the combined load across tenants will result in rate limiting of the excess requests.</td>
      <td>Tenant rate limits are enforced independently, and the environment rate limit acts as a threshold for potential performance degradation and SLA impact, but does <strong>not</strong> directly cause rate limiting at the tenant level.</td>
    </tr>

    <tr>
      <td>Environment Rate Limit Exceeded (Example)</td>
      <td>With an environment limit of 1500 rps, Tenant 1 at 1400 rps and Tenant 2 at 900 rps (combined 2300 rps) will result in 800 requests being rate limited.</td>
      <td>With an environment limit of 1500 rps, Tenant 1 at 1400 rps and Tenant 2 at 900 rps (combined 2300 rps) will <strong>not</strong> cause individual tenants to be rate limited, but the overall environment may experience degraded performance and potential SLA issues.</td>
    </tr>
  </tbody>
</table>

<Warning>
  Exceeding an environment rate limit invalidates the Service Level Agreement (SLA).
</Warning>

For Private Cloud load testing considerations, refer to [Private Cloud on AWS](/docs/deploy-monitor/deploy-private-cloud/private-cloud-on-aws) and [Private Cloud on Azure](/docs/deploy-monitor/deploy-private-cloud/private-cloud-on-azure).

### Tenant request limits

Auth0 limits the number of requests that can be made on a tenant.  These limits are configured depending on the API, and further by specific endpoints on each API.

#### API rate limits

Auth0 limits the number of requests to a specific API, regardless of the API endpoint.  API limits may vary by:

* API

  * Authentication
  * Management
* Tenant type (Production vs. Development or Staging)
* Subscription level (Free, Essential, Professional, Enterprise Public vs. Private)

For example, a free, non-production tenant could have different limits than a production tenant with a paid subscription. For specific rate limit configurations, see [Rate Limit Configurations](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations).

### User requests

A single end user request (e.g., Login or Signup) typically initiates multiple requests to Authentication API Endpoints.  The actual ratio of end user requests to Authentication API depends upon a handful of factors:

* Entity Being Authenticated (e.g., Machine or End User Mobile or Desktop Application)
* Authentication Experience (e.g., New <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> or Classic Login)
* Authentication Flow (e.g., Login, Signup, or Change Password)
* Authentication Flow Type (e.g., Login via Username / Password; Login via Social Login; Login when an existing Authentication Token already exists)

Customers leveraging Extensibility could add still more requests, not only to the Authentication API, but also the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>, depending on the Extensibility Configuration.
See [Rate Limit Use Cases](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-use-cases) for guidance on how to estimate how your Auth0 configuration can impact your API usage.

#### Endpoint rate limits

Auth0 limits the number of requests made to API endpoints and, in some cases, the number of endpoint operations.  API endpoint limits also vary by:

* API
* Tenant type
* Subscription level

For example, a free, non-production tenant has different limits than a production tenant with a paid subscription.

### Tenant request limits order

As requests to your tenant are made, Auth0 evaluates requests against the global limit for the API, and then evaluates requests against the rate limit for specific API endpoints.

### Miscellaneous Limits

#### Database login limits

For database connections, Auth0 limits certain types of repeat login attempts depending on the user account and IP address. To protect the overall health of the system, Auth0 employs user/password rate limits that mitigate load. Auth0's high degree of customization can put us at risk of service degradation. Causes can include:

* High-load stress tests
* Benchmark tests
* Inefficient code that causes users to log in multiple times

Requests are subject to limits as outlined in the individual policies for Auth0 APIs.

In addition, there is a same user login rate limit: If one IP address makes 20 login attempts in one minute to the same user account, the rate limit comes into effect. After that, Auth0 allows the user 10 attempts per minute. Any combination of successful and failed login attempts count toward this limit.

<Card title="Limits that protect users">
  Auth0's [brute-force protection](/docs/secure/attack-protection/brute-force-protection) and [suspicious IP throttling](/docs/secure/attack-protection/suspicious-ip-throttling) can also limit logins and signups, but are independent of rate limits. To learn more about how Auth0 detects and handles potentially malicious anomalies, read [Attack Protection](/docs/secure/attack-protection).
</Card>

#### SMS message limits for multi-factor authentication (end-users only)

If you attempt to send more than 10 SMS messages to your device within one hour, you will receive an error message about a rate limit exception.

When you exceed your messaging limit, you need to wait at least one hour after the first message request before requesting another. You will receive an additional attempt after the passage of each additional hour.

#### Native social login limits

Limits applied to Native Social login flow requests are identified based on the body of the requests with the following initial criteria:

<table>
  <thead>
    <tr>
      <th>Request Type</th>
      <th>Body</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>grant\_type</code></td>
      <td><code>urn:ietf:params:oauth:grant-type:token-exchange</code></td>
    </tr>

    <tr>
      <td><code>subject\_token\_type</code></td>
      <td><code>[http://auth0.com/oauth/token-type/apple-authz-code](http://auth0.com/oauth/token-type/apple-authz-code)</code></td>
    </tr>
  </tbody>
</table>

#### Public Performance Burst

The Public Performance Burst offering is an available add-on to enterprise subscriptions that enhances an existing Public Cloud deployment. This offering allows a dynamic increase of the Authentication API request limit to a multiplier of the default enterprise request limit of 100 RPS for up to 48 hours monthly.

<Callout icon="file-lines">
  This add-on only extends the Authentication API request limits and does NOT apply to the Management API or other endpoints that are rate-limited outside the scope of the Authentication API.
</Callout>

Currently, there are three Public Performance Burst modifiers (2x, 3x, and 4x) allowing 200, 300, and 400 RPS, respectively, for the Authentication API for up to 48 hours monthly. The 48 hours are counted and deducted from the monthly allowed quota in 5-minute intervals, which enables usage of the API at the multiplier level for 576 5-minute intervals each month.

When the volume of requests for the Authentication API exceeds the default of 100 RPS, a 5-minute interval is deducted from the monthly allowance, and traffic is allowed at the rate associated with the multiplier. Traffic can stay within the multiplier range for the complete contiguous 5 minutes from that point without triggering additional deductions.

Monitoring of the interval deduction events is possible through [tenant logs](/docs/deploy-monitor/logs/log-event-type-codes). Each deduction generates an associated `appi` tenant log event type containing information about the already consumed and remaining allowance.

For more information, see the Authentication API section in [Rate Limits - Enterprise](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations/enterprise-public).

#### Private Performance Burst

Private Performance Burst offering (available AWS for 30x and 60x tiers currently) includes a burst (peak) performance capacity up to 30x (3,000 RPS) or 60x (6,000 RPS) for up to 80 hours per month. The base performance capacity, which is half of burst performance capacity, is available for the rest of the month.

In other words, 30x Private Performance Burst has:

* Base capacity: 1,500 RPS for full month
* Burst/peak capacity: 3,000 RPS for up to 80 hours a month

If the Authentication transactions burst above the Base API-Request limit, then one hour is deducted from the monthly allowance. Traffic could stay at an elevated rate for the complete contiguous hour from that point. Additional deductions are done in the above fashion when the threshold is crossed again.

Once the 80 hours allowance is exhausted, the Authentication traffic will be rate limited to base capacity till the new monthly allowance takes effect.

#### Extensibility concurrency limits

To ensure system availability and fair use of system resources, Auth0 limits the number of concurrent in-flight requests across all extensibility products: Actions, Hooks, Rules, Custom Database Connections, Extensions, and Custom OAuth2 connections. Tenants that exceed their concurrent request limits should expect errors for new requests until in-flight requests are completed. The concurrency limits are defined below:

<table>
  <thead>
    <tr>
      <th>Subscription</th>
      <th>Concurrency limit (per Tenant)</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Public Cloud</td>
      <td>250</td>
    </tr>

    <tr>
      <td>Tier Dev Private Cloud</td>
      <td>100</td>
    </tr>

    <tr>
      <td>Private Cloud Basic 100 RPS (1x)</td>
      <td>200</td>
    </tr>

    <tr>
      <td>Private Cloud Performance 500 RPS (5x)</td>
      <td>400</td>
    </tr>

    <tr>
      <td>Private Cloud Performance 1500 RPS (15x)</td>
      <td>1200</td>
    </tr>

    <tr>
      <td>Private Cloud Performance 3000 RPS (30x) and 3000 RPS Burst (30x Burst)</td>
      <td>1200</td>
    </tr>

    <tr>
      <td>Private Cloud Performance 6000 RPS (60x) and 6000 RPS Burst (60x Burst)</td>
      <td>1200</td>
    </tr>
  </tbody>
</table>

Concurrency can be calculated by multiplying expected RPS by the latency of each request. For example, a tenant that has two bound post-login Actions, which each take 250ms with a total login RPS of 400 have an expected concurrency of (2 \* (400 requests / 1 second) \* (.25 seconds / 1 request)) = 200.

To ensure that your tenant is not impacted by these concurrency limits, please ensure that potentially long-running extensibility logic, such as calls to external APIs, have reasonable timeouts.

## Rate limit algorithm

Auth0 sets rate limits and burst limits for its APIs. While the rate limit is the maximum sustainable amount of traffic the system allows on a sustained basis, the burst limit is the maximum short-term traffic volume the system allows within one time interval. Auth0 rate limits and burst limits work together to provide better limiting functionality for dynamic traffic volume.

Auth0 rate limits use a token bucket algorithm containing the following configurations:

* **Limit keys:**

  * Typically, a rate limit key is based on a two main factors:

    * API and endpoint
    * Tenant type
  * In some cases, additional factors include:

    * Source IP
    * Target User ID
* **Limit values:**

  * **Bucket size:** The maximum number of requests an API or endpoint receives in general, or receives from a specific user or IP address, before new requests are added.
  * **Refill rate:** The rate new requests are added to the bucket.

From these two numbers, Auth0 calculates the burst limit and sustained rate limit:

* **Burst limit:**  Equal to bucket size.
* **Sustained rate limit:** Refill rate in requests per minute or second.

If the sustained rate limit is calculated in Requests per Second, new requests are added by milliseconds. If the sustained rate limit is calculated in Requests per Minute, new requests are added on a second basis.

## Learn more

* [Entity Limit Policy](/docs/troubleshoot/customer-support/operational-policies/entity-limit-policy)
* [Rate Limit Use Cases](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-use-cases)


# Rate Limit Configurations
Source: https://auth0.com/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations

Learn about Auth0 rate limiting policies that help prevent service interruption and degradation.

Auth0 enforces limitations to protect services from excessive requests and protect customers from service interruptions or degradation. Based on your subscription type, these rate limits may vary. Please see the table below for the rate limits associated with your account configuration.

<table>
  <thead>
    <tr>
      <th><strong>Read</strong></th>
      <th><strong>To learn...</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations/free-public">Free</a></td>
      <td>Rate limit policies for the Free subscription type.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations/self-service-public">Self Service</a></td>
      <td>Rate limit policies for the Self Service subscription type.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations/enterprise-public">Enterprise</a></td>
      <td>Rate limits policies for the Enterprise subscription type.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations/tier-20-development-private-cloud">Tier Dev Private Cloud</a></td>
      <td>Rate limit policies for the Tier Dev Private Cloud subscription type.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations/tier-100-rps-private-cloud">Private Cloud Basic 100 RPS (1x)</a></td>
      <td>Rate limit policies for the Private Cloud Basic 100 RPS (1x) subscription type.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations/tier-500-rps-private-cloud">Private Cloud Performance 500 RPS (5x)</a></td>
      <td>Rate limits in the Private Cloud Performance 500 (5x) RPS Private Cloud subscription type.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations/tier-1500-rps-private-cloud">Private Cloud Performance 1,500 RPS (15x)</a></td>
      <td>Rate limit policies in the Private Cloud Performance 1,500 (15x) RPS subscription type.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations/tier-3000-rps-private-cloud">Private Cloud Performance 3,000 RPS (30x) and 3000 RPS (30x) Burst</a></td>
      <td>Rate limit policies in the Private Cloud Performance 3,000 (30x) RPS subscription type.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations/tier-6000-rps-private-cloud">Private Cloud Performance 6,000 RPS (60x) and 6000 RPS (60x) Burst</a></td>
      <td>Rate limit policies in the Private Cloud Performance 6,000 (60x) RPS subscription type.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations/tier-10000-rps-private-cloud">Private Cloud Performance 10,000 RPS (100x)</a></td>
      <td>Rate limit policies in the Private Cloud Performance 10,000(100x) RPS subscription type.</td>
    </tr>
  </tbody>
</table>


# Enterprise
Source: https://auth0.com/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations/enterprise-public

Rate limits for the Enterprise subscription type.

See below for the rate limits in the Enterprise subscription type.

<AccordionGroup>
  <Accordion title="Authentication API: Rate limits for the Authentication API and API endpoints in the Enterprise subscription type.">
    <table>
      <thead>
        <tr>
          <th>Tenant</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Production</td>
          <td>100/second</td>
          <td>100/second</td>
        </tr>

        <tr>
          <td>Production (2x Public Performance Burst)</td>
          <td>200/second for 48/hrs per month</td>
          <td>100/second</td>
        </tr>

        <tr>
          <td>Production (3x Public Performance Burst)</td>
          <td>300/second for 48/hrs per month</td>
          <td>100/second</td>
        </tr>

        <tr>
          <td>Production (4x Public Performance Burst)</td>
          <td>400/second for 48/hrs per month</td>
          <td>100/second</td>
        </tr>

        <tr>
          <td>Non-production</td>
          <td>100/second</td>
          <td>100/second</td>
        </tr>
      </tbody>
    </table>

    \*These limits are constrained to 48 hours per month. After 48 hours, these limits revert to product limits. For more information, see [Public Performance Burst](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#public-performance).

    <table>
      <thead>
        <tr>
          <th><a href="https://auth0.com/docs/api/authentication#introduction">Endpoint</a></th>
          <th>Method</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><a href="https://auth0.com/docs/api/authentication/user-profile/get-user-info">User Info</a></td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication/change-password/change-password">Change Password</a> <br /><br /> <a href="/docs/authenticate/database-connections/password-change#universal-login-page">Reset Password with Universal Login</a></td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>1/minute</td>
          <td>From an IP Address to a unique Email Address</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#passwordless">Get Passwordless Code or Link</a></td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>50</td>
          <td>50/hour</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#verify-with-one-time-password-otp-">Native Social Login (Apple / Facebook Only)</a></td>
          <td><code>POST</code></td>
          <td>50</td>
          <td>500/minute</td>
          <td>Any Request for Apple or Facebook Native Social Login</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#dynamic-application-client-registration">Dynamic Application (Client) Registration</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#global-token-revocation">Universal Logout</a></td>
          <td><code>POST</code></td>
          <td>35</td>
          <td>35/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td>Pushed Authorization Requests (PAR)</td>
          <td><code>POST</code></td>
          <td>100</td>
          <td>100/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Back-Channel authorize (CIBA)</td>
          <td><code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code activation (no prompt)</td>
          <td><code>POST</code></td>
          <td>30</td>
          <td>6/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code authorization</td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA OOB token exchange</td>
          <td><code>POST</code></td>
          <td>12</td>
          <td>12/minute</td>
          <td>To a unique session</td>
        </tr>

        <tr>
          <td><a href="/docs/authenticate/custom-token-exchange">Custom Token Exchange</a></td>
          <td><code>POST</code></td>
          <td>15</td>
          <td>15/second</td>
          <td>Any request</td>
        </tr>
      </tbody>
    </table>

    \*Represents the default limit. You can configure the Signup endpoint limit in Auth0 Dashboard. To learn more, read Suspicious IP Throttling.
  </Accordion>

  <Accordion title="Management API: Rate limits for the Management API, API endpoints, and API endpoint groups in the Enterprise subscription type.">
    <table>
      <thead>
        <tr>
          <th>Tenant Environment</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Production</td>
          <td>50</td>
          <td>16/second</td>
        </tr>

        <tr>
          <td>Non-production</td>
          <td>10</td>
          <td>2/second</td>
        </tr>
      </tbody>
    </table>

    <table>
      <thead>
        <tr>
          <th><a href="https://auth0.com/docs/api/management/v2"><strong>Endpoint</strong></a></th>
          <th><strong>Method</strong></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm"><strong>Burst Request Limit</strong></a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm"><strong>Sustained Request Limit</strong></a></th>
          <th><strong>Limit Type</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-name-by-name">Read Organizations by Name</a></td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-organizations">Write Organizations</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>5</td>
          <td>150/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-members">Read Organization Members</a></td>
          <td><code>GET</code></td>
          <td>40</td>
          <td>500/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-members">Write Organization Members</a></td>
          <td><code>POST</code>, <code>DELETE</code></td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-invitations-by-invitation-id">Read Organization invitation</a></td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organization-member-roles">Read Organization Member Roles</a></td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-organization-member-roles">Write Organization Member Roles</a></td>
          <td><code>POST</code>, <code>DELETE</code></td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-enabled-connections">Read Organization Connections</a></td>
          <td><code>GET</code></td>
          <td>10</td>
          <td>100/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-enabled-connections">Write Organization Connections</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>5</td>
          <td>150/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/custom-domains/post-verify">Write Custom Domains</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/connections/get-status">Read Status Connection</a></td>
          <td><code>GET</code></td>
          <td>100</td>
          <td>15/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/keys/post-signing-keys">Write Signing Keys</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/day</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/prompts/get-partials">Read Partials for a Prompt</a></td>
          <td><code>GET</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/prompts/put-partials">Write Partials for a Prompt</a></td>
          <td><code>PUT</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/clients/get-clients">Read Clients</a><p><br />Only applies to the usage of the <code>q</code> parameter.<br /></p></td>
          <td><code>GET</code></td>
          <td>5</td>
          <td>150/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organization-client-grants">Read Organization Client Grants</a></td>
          <td><code>GET</code></td>
          <td>10</td>
          <td>100/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/create-organization-client-grants">Write Organization Client Grants</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>150/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/email-templates/post-email-templates">Write email templates</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>10</td>
          <td>100/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/email-templates/get-email-templates-by-template-name">Read email templates</a></td>
          <td><code>GET</code></td>
          <td>15</td>
          <td>150/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/emails/patch-provider">Write email provider</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>10</td>
          <td>100/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/emails/get-provider">Read email provider</a></td>
          <td><code>GET</code></td>
          <td>15</td>
          <td>150/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#create-custom-token-exchange-profile">Write Token Exchange Profiles</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>5</td>
          <td>100/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#manage-custom-token-exchange-profile">Read Token Exchange Profiles</a></td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="SCIM API: Rate limits for the inbound SCIM API endpoints in Public cloud subscriptions that include Enterprise connections.">
    <table>
      <thead>
        <tr>
          <th>Limit Type</th>
          <th>Endpoint Path</th>
          <th>Operation</th>
          <th>Limit</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Single SCIM connection endpoint</td>
          <td>`/scim/v2/connections/{connection-id}`</td>
          <td>Any request</td>
          <td>25 requests per second</td>
        </tr>

        <tr>
          <td>Global tenant limit for all SCIM connections</td>
          <td>`/scim/v2/connections/*`</td>
          <td>Any request</td>
          <td>100 requests per second</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Universal Login Flow Endpoints: Rate limits for the endpoints utilized for the Universal Login Authentication Flow for all subscription types.">
    <table>
      <thead>
        <tr>
          <th>Endpoint</th>
          <th>Method</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Universal login prompts (global)</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Universal login prompts (per prompt)</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address and state value.</td>
        </tr>

        <tr>
          <td>Universal login prompts (per prompt)</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Password reset prompt</td>
          <td><code>GET</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA push enrollment prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA push challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment prompt</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment prompt</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment verify prompt</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment verify prompt</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Passwordless SMS challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Passwordless email challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Phone verification enrollment prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Phone verification challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>From an IP Address</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Additional MFA rate limits: Additional MFA rate limits.">
    <table>
      <thead>
        <tr>
          <th>Endpoint</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
          <th>Limit</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>OTP (6 numeric digits) failures</td>
          <td>10</td>
          <td>10</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Recovery code failures</td>
          <td>10</td>
          <td>10</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Webauthn challenge failures</td>
          <td>15</td>
          <td>15</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Webauthn challenge generated</td>
          <td>15</td>
          <td>15</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Push notifications sent per user</td>
          <td>5</td>
          <td>5</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>SMS sent per user</td>
          <td>10</td>
          <td>1</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Email sent per user</td>
          <td>20</td>
          <td>1</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>
      </tbody>
    </table>
  </Accordion>
</AccordionGroup>


# Free
Source: https://auth0.com/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations/free-public

Rate limit policies for the Free Public subscription type.

See below for the rate limit policies for the Free subscription type.

<AccordionGroup>
  <Accordion title="Authentication API: Rate limits for the Authentication API and API endpoints in the Free subscription type.">
    <table>
      <thead>
        <tr>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#api-rate-limits">API</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Authentication API</td>
          <td>300</td>
          <td>300/minute</td>
        </tr>
      </tbody>
    </table>

    <table>
      <thead>
        <tr>
          <th>Endpoint</th>
          <th>Method</th>
          <th>Path</th>
          <th>Burst Request Limit</th>
          <th>Sustained Request Limit</th>
          <th>Limit Type</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>User Info</td>
          <td>GET, POST</td>
          <td><code>/userinfo</code></td>
          <td>10</td>
          <td>5 per/min</td>
          <td>To a unique user ID</td>
        </tr>

        <tr>
          <td>Change Password</td>
          <td>POST</td>
          <td><code>/dbconnections/change\_password</code> & <code>u/reset-password/request/:connection</code></td>
          <td>10</td>
          <td>1 per/min</td>
          <td>From an IP address to a unique email address</td>
        </tr>

        <tr>
          <td>Get Passwordless Code or Link</td>
          <td>GET, POST</td>
          <td><code>/passwordless/start</code></td>
          <td>50</td>
          <td>50 per/hr</td>
          <td>From an IP address</td>
        </tr>

        <tr>
          <td>Get Token</td>
          <td>POST</td>
          <td><code>/oauth/token</code></td>
          <td>30</td>
          <td>30 per/sec</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td>Cross Origin Authentication</td>
          <td>POST</td>
          <td><code>co/authenticate</code></td>
          <td>5</td>
          <td>5 per/sec</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td>Authentication</td>
          <td>POST</td>
          <td><code>/usernamepassword/login</code></td>
          <td>5</td>
          <td>5 per/sec</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td>JSON Web Token Keys</td>
          <td>GET</td>
          <td><code>/.well-known/jwks.json</code></td>
          <td>20</td>
          <td>20 per/sec</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td>Native Social Login</td>
          <td>POST</td>
          <td><code>/oauth/token</code></td>
          <td>50</td>
          <td>50 per/min</td>
          <td>Any Request for Apple or Facebook Native Social Login</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#dynamic-application-client-registration">Dynamic Application (Client) Registration</a></td>
          <td>POST</td>
          <td><code>/oidc/register</code></td>
          <td>5</td>
          <td>5 per/sec</td>
          <td>Any request</td>
        </tr>
      </tbody>
    </table>

    \*Represents the default limit. You can configure the Signup endpoint limit in Auth0 Dashboard. To learn more, read [Suspicious IP Throttling](/docs/secure/attack-protection/suspicious-ip-throttling).
  </Accordion>

  <Accordion title="Management API: Rate limits for the Management API on the Free subscription tier.">
    <table>
      <thead>
        <tr>
          <th><strong>API</strong></th>
          <th><strong>Burst Request Limit</strong></th>
          <th><strong>Sustained Request Limit</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Management</td>
          <td>2</td>
          <td>2/second</td>
        </tr>
      </tbody>
    </table>

    <table>
      <thead>
        <tr>
          <th><strong>Endpoint</strong></th>
          <th><strong>Method</strong></th>
          <th><strong>Path</strong></th>
          <th><strong>Burst Request Limit</strong></th>
          <th><strong>Sustained Request Limit</strong></th>
          <th><strong>Limit Type</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Register Dynamic Client</td>
          <td>POST</td>
          <td><code>/oidc/register</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td>Verify Custom Domain</td>
          <td>POST</td>
          <td><code>/api/v2/custom-domains/verify</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td>Read Status Connection</td>
          <td>POST</td>
          <td><code>/api/v2/connections//status</code></td>
          <td>100</td>
          <td>15/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td>Rotate Signing Keys</td>
          <td>POST</td>
          <td><code>/api/v2/keys/signing/rotate</code></td>
          <td>5</td>
          <td>5/day</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td>Configure email templates</td>
          <td>POST, PATCH, DELETE</td>
          <td><code>/api/v2/email-templates</code></td>
          <td>5</td>
          <td>25/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td>Read email templates</td>
          <td>GET</td>
          <td><code>/api/v2/email-templates</code></td>
          <td>10</td>
          <td>50/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td>Configure email provider</td>
          <td>POST, PATCH, DELETE</td>
          <td><code>/api/v2/emails/provider</code></td>
          <td>5</td>
          <td>25/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td>Read email provider</td>
          <td>GET</td>
          <td><code>/api/v2/emails/provider</code></td>
          <td>5</td>
          <td>25/minute</td>
          <td>Any request</td>
        </tr>
      </tbody>
    </table>
  </Accordion>
</AccordionGroup>


# Self Service
Source: https://auth0.com/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations/self-service-public

Rate limits for the self service public subscription type

See below for the rate limit policies for the Self service subscription type.

<AccordionGroup>
  <Accordion title="Authentication API: Rate Limits for the Authentication API and API Endpoints in the Self service subscription type.">
    <table>
      <thead>
        <tr>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#api-rate-limits">API</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Authentication API</td>
          <td>25</td>
          <td>25/second</td>
        </tr>
      </tbody>
    </table>

    <table>
      <thead>
        <tr>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#endpoint-rate-limits">Endpoint</a></th>
          <th>Method</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#get-user-info">User Info</a></td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#change-password">Change Password</a> <br /><br /> <a href="/docs/authenticate/database-connections/password-change#universal-login-page">Reset Password with Universal Login</a></td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>1/minute</td>
          <td>From an IP Address to a unique Email Address</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#passwordless">Get Passwordless Code or Link</a></td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>50</td>
          <td>50/hour</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#verify-with-one-time-password-otp-">Native Social Login (Apple / Facebook Only)</a></td>
          <td><code>POST</code></td>
          <td>50</td>
          <td>500/minute</td>
          <td>Any Request for Apple or Facebook Native Social Login</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#dynamic-application-client-registration">Dynamic Application (Client) Registration</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#global-token-revocation">Universal Logout</a></td>
          <td><code>POST</code></td>
          <td>35</td>
          <td>35/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td>Pushed Authorization Requests (PAR)</td>
          <td><code>POST</code></td>
          <td>100</td>
          <td>100/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Back-Channel authorize (CIBA)</td>
          <td><code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code activation (no prompt)</td>
          <td><code>POST</code></td>
          <td>30</td>
          <td>6/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code authorization</td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA OOB token exchange</td>
          <td><code>POST</code></td>
          <td>12</td>
          <td>12/minute</td>
          <td>To a unique session</td>
        </tr>

        <tr>
          <td><a href="/docs/authenticate/custom-token-exchange">Custom Token Exchange</a></td>
          <td><code>POST</code></td>
          <td>4</td>
          <td>4/second</td>
          <td>Any request</td>
        </tr>
      </tbody>
    </table>

    \*Represents the default limit. You can configure the Signup endpoint limit in Auth0 Dashboard. To learn more, read [Suspicious IP Throttling](/docs/secure/attack-protection/suspicious-ip-throttling).
  </Accordion>

  <Accordion title="Management API: Rate Limits for the Management API, API Endpoints, and API Endpoint Groups in the Self service subscription type.">
    <table>
      <thead>
        <tr>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#endpoint-rate-limits"><strong>Endpoint</strong></a></th>
          <th><strong>Method</strong></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm"><strong>Burst Request Limit</strong></a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm"><strong>Sustained Request Limit</strong></a></th>
          <th><strong>Limit Type</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organizations">Read Organizations</a></td>
          <td><code>GET</code></td>
          <td>5</td>
          <td>50/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organizations-by-id">Read Organizations by ID</a></td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-name-by-name">Read Organizations by Name</a></td>
          <td><code>GET</code></td>
          <td>10</td>
          <td>100/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-organizations">Write Organizations</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>5</td>
          <td>25/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-members">Read Organization Members</a></td>
          <td><code>GET</code></td>
          <td>40</td>
          <td>500/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-members">Write Organization Members</a></td>
          <td><code>POST</code>, <code>DELETE</code></td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-members">Read Members of an Organization</a></td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organization-member-roles">Read Organization Member Roles</a></td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-organization-member-roles">Write Organization Member Roles</a></td>
          <td><code>POST</code>, <code>DELETE</code></td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-enabled-connections">Read Organization Connections</a></td>
          <td><code>GET</code></td>
          <td>5</td>
          <td>50/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-enabled-connections">Write Organization Connections</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>5</td>
          <td>25/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/users/get-users">Read Users</a></td>
          <td><code>GET</code></td>
          <td>40</td>
          <td>500/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/users/post-users">Write Users</a></td>
          <td><code>POST</code>, <code>PATCH</code></td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/users/delete-users-by-id">Write Users</a></td>
          <td><code>DELETE</code></td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/logs/get-logs">Read Logs</a></td>
          <td><code>GET</code></td>
          <td>10</td>
          <td>100/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/clients/get-clients">Read Clients</a></td>
          <td><code>GET</code></td>
          <td>5</td>
          <td>100/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/connections/get-connections">Read Connections</a></td>
          <td><code>GET</code></td>
          <td>5</td>
          <td>50/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/device-credentials/post-device-credentials">Write Device Credentials</a></td>
          <td><code>POST</code>, <code>DELETE</code></td>
          <td>5</td>
          <td>100/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/custom-domains/post-verify">Write Custom Domain</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/connections/get-status">Read Status Connection</a></td>
          <td><code>GET</code></td>
          <td>100</td>
          <td>15/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/keys/post-signing-keys">Write Signing Keys</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/day</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/prompts/get-partials">Read Partials for a Prompt</a></td>
          <td><code>GET</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/prompts/put-partials">Write Partials for a Prompt</a></td>
          <td><code>PUT</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/clients/get-clients">Read Clients</a><p><br />Only applies to the usage of the <code>q</code> parameter.<br /></p></td>
          <td><code>GET</code></td>
          <td>5</td>
          <td>150/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organization-client-grants">Read Organization Client Grants</a></td>
          <td><code>GET</code></td>
          <td>10</td>
          <td>100/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/create-organization-client-grants">Write Organization Client Grants</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>150/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/email-templates/post-email-templates">Write email templates</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>5</td>
          <td>25/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/email-templates/get-email-templates-by-template-name">Read email templates</a></td>
          <td><code>GET</code></td>
          <td>10</td>
          <td>50/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/emails/patch-provider">Write email provider</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>5</td>
          <td>25/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/emails/get-provider">Read email provider</a></td>
          <td><code>GET</code></td>
          <td>5</td>
          <td>25/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#create-custom-token-exchange-profile">Write Token Exchange Profiles</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>5</td>
          <td>100/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#manage-custom-token-exchange-profile">Read Token Exchange Profiles</a></td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td>All other Endpoints Combined</td>
          <td>N/A</td>
          <td>10</td>
          <td>150/minute</td>
          <td>Any request</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="SCIM API: Rate limits for the inbound SCIM API endpoints in Public cloud subscriptions that include Enterprise connections.">
    <table>
      <thead>
        <tr>
          <th>Limit Type</th>
          <th>Endpoint Path</th>
          <th>Operation</th>
          <th>Limit</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Single SCIM connection endpoint</td>
          <td>`/scim/v2/connections/{connection-id}`</td>
          <td>Any request</td>
          <td>25 requests per second</td>
        </tr>

        <tr>
          <td>Global tenant limit for all SCIM connections</td>
          <td>`/scim/v2/connections/*`</td>
          <td>Any request</td>
          <td>100 requests per second</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Universal Login Flow Endpoints: Rate limits for the endpoints utilized for the Universal Login Authentication Flow for all subscription types.">
    <table>
      <thead>
        <tr>
          <th>Endpoint</th>
          <th>Method</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Universal login prompts (global)</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Universal login prompts (per prompt)</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address and state value.</td>
        </tr>

        <tr>
          <td>Universal login prompts (per prompt)</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Password reset prompt</td>
          <td><code>GET</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA push enrollment prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA push challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment prompt</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment prompt</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment verify prompt</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment verify prompt</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Passwordless SMS challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Passwordless email challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Phone verification enrollment prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Phone verification challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>From an IP Address</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Additional MFA rate limits: Additional MFA rate limits.">
    <table>
      <thead>
        <tr>
          <th>Endpoint</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
          <th>Limit</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>OTP (6 numeric digits) failures</td>
          <td>10</td>
          <td>10</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Recovery code failures</td>
          <td>10</td>
          <td>10</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Webauthn challenge failures</td>
          <td>15</td>
          <td>15</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Webauthn challenge generated</td>
          <td>15</td>
          <td>15</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Push notifications sent per user</td>
          <td>5</td>
          <td>5</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>SMS sent per user</td>
          <td>10</td>
          <td>1</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Email sent per user</td>
          <td>20</td>
          <td>1</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>
      </tbody>
    </table>
  </Accordion>
</AccordionGroup>


# Private Cloud Basic 100 RPS (1x)
Source: https://auth0.com/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations/tier-100-rps-private-cloud

Tier 100 RPS Private Cloud rate limits

See below for the rate limits in the Private Cloud Basic 100 RPS (1x) subscription type. These limits apply to each tenant you create in the private cloud environment.

Therefore, we recommend deploying one tenant per private cloud environment for risk mitigation.

<AccordionGroup>
  <Accordion title="Authentication API: Rate limits for the Authentication API and API endpoints n the Private Cloud Basic 100 RPS (1x) subscription tier.">
    <table>
      <thead>
        <tr>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#api-rate-limits">API</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Authentication API</td>
          <td>100</td>
          <td>100/second</td>
        </tr>
      </tbody>
    </table>

    <table>
      <thead>
        <tr>
          <th><a href="https://auth0.com/docs/api/authentication#introduction">Endpoint</a></th>
          <th>Method</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#get-user-info">User Info</a></td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#change-password">Change Password</a> <br /><br /> <a href="/docs/authenticate/database-connections/password-change#universal-login-page">Reset Password with Universal Login</a></td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>1/minute</td>
          <td>From an IP Address to a unique Email Address</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#passwordless">Get Passwordless Code or Link</a></td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>50</td>
          <td>50/hour</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#verify-with-one-time-password-otp-">Native Social Login (Apple / Facebook Only)</a></td>
          <td><code>POST</code></td>
          <td>50</td>
          <td>500/minute</td>
          <td>Any Request for Apple or Facebook Native Social Login</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#dynamic-application-client-registration">Dynamic Application (Client) Registration</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#global-token-revocation">Universal Logout</a></td>
          <td><code>POST</code></td>
          <td>35</td>
          <td>35/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td>Pushed Authorization Requests (PAR)</td>
          <td><code>POST</code></td>
          <td>100</td>
          <td>100/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Back-Channel authorize (CIBA)</td>
          <td><code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code activation (no prompt)</td>
          <td><code>POST</code></td>
          <td>30</td>
          <td>6/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code authorization</td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA OOB token exchange</td>
          <td><code>POST</code></td>
          <td>12</td>
          <td>12/minute</td>
          <td>To a unique session</td>
        </tr>

        <tr>
          <td><a href="/docs/authenticate/custom-token-exchange">Custom Token Exchange</a></td>
          <td><code>POST</code></td>
          <td>15</td>
          <td>15/second</td>
          <td>Any request</td>
        </tr>
      </tbody>
    </table>

    \*Represents the default limit. You can configure the Signup endpoint limit in Auth0 Dashboard. To learn more, read Suspicious IP Throttling.
  </Accordion>

  <Accordion title="Management API: Rate limits for the Management API, API endpoints, and API endpoint groups in the Private Cloud Basic 100 RPS (1x) subscription.">
    <table>
      <thead>
        <tr>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#api-rate-limits">API</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Management API</td>
          <td>50</td>
          <td>50/second</td>
        </tr>
      </tbody>
    </table>

    <table>
      <thead>
        <tr>
          <th><a href="https://auth0.com/docs/api/management/v2"><strong>Endpoint</strong></a></th>
          <th><strong>Method</strong></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm"><strong>Burst Request Limit</strong></a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm"><strong>Sustained Request Limit</strong></a></th>
          <th><strong>Limit Type</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organizations">Read Organizations</a></td>
          <td>GET</td>
          <td>10</td>
          <td>100/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organizations-by-id">Read Organizations by ID</a></td>
          <td>GET</td>
          <td>40</td>
          <td>500/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-name-by-name">Read Organizations by Name</a></td>
          <td>GET</td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-organizations">Write an Organization</a></td>
          <td>POST, PATCH, DELETE</td>
          <td>5</td>
          <td>150/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-members">Read Organization Members</a></td>
          <td>GET</td>
          <td>40</td>
          <td>500/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-members">Write Organization Members</a></td>
          <td>POST, DELETE</td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-members">Read Members of an Organization</a></td>
          <td>GET</td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organization-member-roles">Read Organization Member Roles</a></td>
          <td>GET</td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-organization-member-roles">Write Organization Member Roles</a></td>
          <td>POST, DELETE</td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-enabled-connections">Write Organization Connections</a></td>
          <td>POST, PATCH, DELETE</td>
          <td>5</td>
          <td>150/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/custom-domains/post-verify">Write Custom Domain</a></td>
          <td>POST</td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/connections/get-status">Read Status Connection</a></td>
          <td>GET</td>
          <td>100</td>
          <td>15/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/keys/post-signing-keys">Write Signing Keys</a></td>
          <td>POST</td>
          <td>5</td>
          <td>5/day</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/prompts/get-partials">Read Partials for a Prompt</a></td>
          <td>GET</td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/prompts/put-partials">Write Partials for a Prompt</a></td>
          <td>PUT</td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/clients/get-clients">Read Clients</a><p><br />Only applies to the usage of the <code>q</code> parameter.<br /></p></td>
          <td><code>GET</code></td>
          <td>5</td>
          <td>150/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organization-client-grants">Read Organization Client Grants</a></td>
          <td><code>GET</code></td>
          <td>10</td>
          <td>100/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/create-organization-client-grants">Write Organization Client Grants</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>150/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#create-custom-token-exchange-profile">Write Token Exchange Profiles</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>5</td>
          <td>100/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#manage-custom-token-exchange-profile">Read Token Exchange Profiles</a></td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="SCIM API: Rate limits for the inbound SCIM API endpoints in the Private Cloud Basic 100 RPS (1x) subscription type.">
    <table>
      <thead>
        <tr>
          <th>Limit Type</th>
          <th>Endpoint Path</th>
          <th>Operation</th>
          <th>Limit</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Single SCIM connection endpoint</td>
          <td>`/scim/v2/connections/{connection-id}`</td>
          <td>Any request</td>
          <td>25 requests per second</td>
        </tr>

        <tr>
          <td>Global tenant limit for all SCIM connections</td>
          <td>`/scim/v2/connections/*`</td>
          <td>Any request</td>
          <td>100 requests per second</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Universal Login Flow Endpoints: Rate limits for the endpoints utilized for the Universal Login Authentication Flow for all subscription types.">
    <table>
      <thead>
        <tr>
          <th>Endpoint</th>
          <th>Method</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Universal login prompts (global)</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Universal login prompts (per prompt)</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address and state value.</td>
        </tr>

        <tr>
          <td>Universal login prompts (per prompt)</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Password reset prompt</td>
          <td><code>GET</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA push enrollment prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA push challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment prompt</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment prompt</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment verify prompt</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment verify prompt</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Passwordless SMS challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Passwordless email challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Phone verification enrollment prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Phone verification challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>From an IP Address</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Additional MFA rate limits: Additional MFA rate limits.">
    <table>
      <thead>
        <tr>
          <th>Endpoint</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
          <th>Limit</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>OTP (6 numeric digits) failures</td>
          <td>10</td>
          <td>10</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Recovery code failures</td>
          <td>10</td>
          <td>10</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Webauthn challenge failures</td>
          <td>15</td>
          <td>15</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Webauthn challenge generated</td>
          <td>15</td>
          <td>15</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Push notifications sent per user</td>
          <td>5</td>
          <td>5</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>SMS sent per user</td>
          <td>10</td>
          <td>1</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Email sent per user</td>
          <td>20</td>
          <td>1</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>
      </tbody>
    </table>
  </Accordion>
</AccordionGroup>


# Private Cloud Performance 10,000 RPS (100x)
Source: https://auth0.com/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations/tier-10000-rps-private-cloud

Tier 10000 RPS Private Cloud rate limits

See below for the rate limits in the Private Cloud Performance 10,000 RPS (100x) subscription type.

Therefore, we recommend deploying one tenant per private cloud environment for risk mitigation.

<AccordionGroup>
  <Accordion title="Authentication API: Rate limits for the Authentication API and API endpoints in the Private Cloud Performance 10000 RPS subscription type.">
    <table>
      <thead>
        <tr>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#api-rate-limits">API</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Peak Request Limit</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Authentication API</td>
          <td>10,000</td>
          <td>10,000/second</td>
          <td>N/A</td>
        </tr>
      </tbody>
    </table>

    <table>
      <thead>
        <tr>
          <th><a href="https://auth0.com/docs/api/authentication#introduction">Endpoint</a></th>
          <th>Method</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#get-user-info">User Info</a></td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#change-password">Change Password</a> <br /><br /> <a href="/docs/authenticate/database-connections/password-change#universal-login-page">Reset Password with Universal Login</a></td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>1/minute</td>
          <td>From an IP Address to a unique Email Address</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#passwordless">Get Passwordless Code or Link</a></td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>50</td>
          <td>50/hour</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#verify-with-one-time-password-otp-">Native Social Login (Apple / Facebook Only)</a></td>
          <td><code>POST</code></td>
          <td>50</td>
          <td>500/minute</td>
          <td>Any Request for Apple or Facebook Native Social Login</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#dynamic-application-client-registration">Dynamic Application (Client) Registration</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#global-token-revocation">Universal Logout</a></td>
          <td><code>POST</code></td>
          <td>2500</td>
          <td>2500/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td>Pushed Authorization Requests (PAR)</td>
          <td><code>POST</code></td>
          <td>100</td>
          <td>100/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Back-Channel authorize (CIBA)</td>
          <td><code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code activation (no prompt)</td>
          <td><code>POST</code></td>
          <td>30</td>
          <td>6/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code authorization</td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA OOB token exchange</td>
          <td><code>POST</code></td>
          <td>12</td>
          <td>12/minute</td>
          <td>To a unique session</td>
        </tr>

        <tr>
          <td><a href="/docs/authenticate/custom-token-exchange">Custom Token Exchange</a></td>
          <td><code>POST</code></td>
          <td>1500</td>
          <td>1500/second</td>
          <td>Any request</td>
        </tr>
      </tbody>
    </table>

    \*Represents the default limit. You can configure the Signup endpoint limit in Auth0 Dashboard. To learn more, read [Suspicious IP Throttling](/docs/secure/attack-protection/suspicious-ip-throttling).
  </Accordion>

  <Accordion title="Management API: Rate limits for the Management API, API endpoints, and API endpoint groups in the Private Cloud Performance 10,000 RPS subscription type.">
    <table>
      <thead>
        <tr>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#api-rate-limits">API</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Management API</td>
          <td>5000</td>
          <td>5000/second</td>
        </tr>
      </tbody>
    </table>

    <table>
      <thead>
        <tr>
          <th><a href="https://auth0.com/docs/api/management/v2"><strong>Endpoint</strong></a></th>
          <th><strong>Method</strong></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm"><strong>Burst Request Limit</strong></a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm"><strong>Sustained Request Limit</strong></a></th>
          <th><strong>Limit Type</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organizations">Read Organizations</a></td>
          <td><code>GET</code></td>
          <td>1,000</td>
          <td>10,000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organizations-by-id">Read Organizations by ID</a></td>
          <td><code>GET</code></td>
          <td>4,000</td>
          <td>50,000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-name-by-name">Read Organizations by Name</a></td>
          <td><code>GET</code></td>
          <td>2,000</td>
          <td>20,000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-organizations">Write an Organization</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>500</td>
          <td>15,000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-members">Read Organization Members</a></td>
          <td><code>GET</code></td>
          <td>4,800</td>
          <td>60,000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-members">Write Organization Members</a></td>
          <td><code>POST</code>, <code>DELETE</code></td>
          <td>2,400</td>
          <td>24,000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-members">Read Members of an Organization</a></td>
          <td><code>GET</code></td>
          <td>2,400</td>
          <td>24,000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organization-member-roles">Read Organization Member Roles</a></td>
          <td><code>GET</code></td>
          <td>2,400</td>
          <td>24,000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-organization-member-roles">Write Organization Member Roles</a></td>
          <td><code>POST</code>, <code>DELETE</code></td>
          <td>2,400</td>
          <td>24,000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-enabled-connections">Read Organization Connections</a></td>
          <td><code>GET</code></td>
          <td>1,200</td>
          <td>12,000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-enabled-connections">Write Organization Connections</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>600</td>
          <td>18,000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/custom-domains/post-verify">Write Custom Domain</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/connections/get-status">Write Status Connection</a></td>
          <td><code>POST</code></td>
          <td>100</td>
          <td>15/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/keys/post-signing-keys">Write Signing Keys</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/day</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#create-custom-token-exchange-profile">Write Token Exchange Profiles</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>15</td>
          <td>300/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#manage-custom-token-exchange-profile">Read Token Exchange Profiles</a></td>
          <td><code>GET</code></td>
          <td>2000</td>
          <td>20000/minute</td>
          <td>Any request</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Universal Login Flow Endpoints: Rate limits for the endpoints utilized for the Universal Login Authentication Flow for all subscription types.">
    <table>
      <thead>
        <tr>
          <th>Endpoint</th>
          <th>Method</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Universal login prompts (global)</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Universal login prompts (per prompt)</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address and state value.</td>
        </tr>

        <tr>
          <td>Universal login prompts (per prompt)</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Password reset prompt</td>
          <td><code>GET</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA push enrollment prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA push challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment prompt</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment prompt</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment verify prompt</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment verify prompt</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Passwordless SMS challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Passwordless email challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Phone verification enrollment prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Phone verification challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>From an IP Address</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Additional MFA rate limits: Additional MFA rate limits.">
    <table>
      <thead>
        <tr>
          <th>Endpoint</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
          <th>Limit</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>OTP (6 numeric digits) failures</td>
          <td>10</td>
          <td>10</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Recovery code failures</td>
          <td>10</td>
          <td>10</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Webauthn challenge failures</td>
          <td>15</td>
          <td>15</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Webauthn challenge generated</td>
          <td>15</td>
          <td>15</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Push notifications sent per user</td>
          <td>5</td>
          <td>5</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>SMS sent per user</td>
          <td>10</td>
          <td>1</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Email sent per user</td>
          <td>20</td>
          <td>1</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>
      </tbody>
    </table>
  </Accordion>
</AccordionGroup>


# Private Cloud Performance 1500 RPS (15x)
Source: https://auth0.com/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations/tier-1500-rps-private-cloud

Tier 1500 RPS Private Cloud rate limits

See below for the rate limits in the Private Cloud Performance 1500 RPS (15x) subscription type. These limits apply to each tenant you create in the private cloud environment.

Therefore, we recommend deploying one tenant per private cloud environment for risk mitigation.

<AccordionGroup>
  <Accordion title="Authentication API: Rate limits for the Authentication API and API endpoints in the Private Cloud Performance 1500 RPS (15x) subscription type.">
    <table>
      <thead>
        <tr>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#api-rate-limits">API</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Authentication API</td>
          <td>1500</td>
          <td>1500/second</td>
        </tr>
      </tbody>
    </table>

    <table>
      <thead>
        <tr>
          <th><a href="https://auth0.com/docs/api/authentication#introduction">Endpoint</a></th>
          <th>Method</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#get-user-info">User Info</a></td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#change-password">Change Password</a> <br /><br /> <a href="/docs/authenticate/database-connections/password-change#universal-login-page">Reset Password with Universal Login</a></td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>1/minute</td>
          <td>From an IP Address to a unique Email Address</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#passwordless">Get Passwordless Code or Link</a></td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>50</td>
          <td>50/hour</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#verify-with-one-time-password-otp-">Native Social Login (Apple / Facebook Only)</a></td>
          <td><code>POST</code></td>
          <td>50</td>
          <td>500/minute</td>
          <td>Any Request for Apple or Facebook Native Social Login</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#dynamic-application-client-registration">Dynamic Application (Client) Registration</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#global-token-revocation">Universal Logout</a></td>
          <td><code>POST</code></td>
          <td>375</td>
          <td>375/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td>Pushed Authorization Requests (PAR)</td>
          <td><code>POST</code></td>
          <td>100</td>
          <td>100/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Back-Channel authorize (CIBA)</td>
          <td><code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code activation (no prompt)</td>
          <td><code>POST</code></td>
          <td>30</td>
          <td>6/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code authorization</td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA OOB token exchange</td>
          <td><code>POST</code></td>
          <td>12</td>
          <td>12/minute</td>
          <td>To a unique session</td>
        </tr>

        <tr>
          <td><a href="/docs/authenticate/custom-token-exchange">Custom Token Exchange</a></td>
          <td><code>POST</code></td>
          <td>225</td>
          <td>225/second</td>
          <td>Any request</td>
        </tr>
      </tbody>
    </table>

    \*Represents the default limit. You can configure the Signup endpoint limit in Auth0 Dashboard. To learn more, read [Suspicious IP Throttling](/docs/secure/attack-protection/suspicious-ip-throttling).
  </Accordion>

  <Accordion title="Management API: Rate limits for the Management API, API endpoints, and API endpoint groups in the Private Cloud Performance 1500 RPS (15x) subscription type.">
    <table>
      <thead>
        <tr>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#api-rate-limits">API</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Management API</td>
          <td>750</td>
          <td>750/second</td>
        </tr>
      </tbody>
    </table>

    <table>
      <thead>
        <tr>
          <th><a href="https://auth0.com/docs/api/management/v2"><strong>Endpoint</strong></a></th>
          <th><strong>Method</strong></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm"><strong>Burst Request Limit</strong></a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm"><strong>Sustained Request Limit</strong></a></th>
          <th><strong>Limit Type</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organizations">Read Organizations</a></td>
          <td><code>GET</code></td>
          <td>150</td>
          <td>1500/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organizations-by-id">Read Organizations by ID</a></td>
          <td><code>GET</code></td>
          <td>150</td>
          <td>7500/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-name-by-name">Read Organizations by Name</a></td>
          <td><code>GET</code></td>
          <td>30</td>
          <td>3000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-organizations">Write an Organization</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>75</td>
          <td>2250/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-members">Read Organization Members</a></td>
          <td><code>GET</code></td>
          <td>600</td>
          <td>7500/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-members">Write Organization Members</a></td>
          <td><code>POST</code>, <code>DELETE</code></td>
          <td>300</td>
          <td>3000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-members">Read Members of an Organization</a></td>
          <td><code>GET</code></td>
          <td>300</td>
          <td>3000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organization-member-roles">Read Organization Member Roles</a></td>
          <td><code>GET</code></td>
          <td>300</td>
          <td>3000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-organization-member-roles">Write Organization Member Roles</a></td>
          <td><code>POST</code>, <code>DELETE</code></td>
          <td>300</td>
          <td>3000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-enabled-connections">Read Organization Connections</a></td>
          <td><code>GET</code></td>
          <td>150</td>
          <td>1500/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-enabled-connections">Write Organization Connections</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>75</td>
          <td>2250/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/custom-domains/post-verify">Write Custom Domain</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/connections/get-status">Write Status Connection</a></td>
          <td><code>POST</code></td>
          <td>100</td>
          <td>15/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/keys/post-signing-keys">Write Signing Keys</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/day</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/prompts/get-partials">Read Partials for a Prompt</a></td>
          <td><code>GET</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/prompts/put-partials">Write Partials for a Prompt</a></td>
          <td><code>PUT</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/clients/get-clients">Read Clients</a><p><br />Only applies to the usage of the <code>q</code> parameter.<br /></p></td>
          <td><code>GET</code></td>
          <td>75</td>
          <td>2250/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organization-client-grants">Read Organization Client Grants</a></td>
          <td><code>GET</code></td>
          <td>150</td>
          <td>1500/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/create-organization-client-grants">Write Organization Client Grants</a></td>
          <td><code>POST</code></td>
          <td>75</td>
          <td>2250/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#create-custom-token-exchange-profile">Write Token Exchange Profiles</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>15</td>
          <td>300/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#manage-custom-token-exchange-profile">Read Token Exchange Profiles</a></td>
          <td><code>GET</code></td>
          <td>300</td>
          <td>3000/minute</td>
          <td>Any request</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="SCIM API: Rate limits for the inbound SCIM API endpoints in the Private Cloud Performance 1500 RPS (15x) subscription type.">
    <table>
      <thead>
        <tr>
          <th>Limit Type</th>
          <th>Endpoint Path</th>
          <th>Operation</th>
          <th>Limit</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Single SCIM connection endpoint</td>
          <td>`/scim/v2/connections/{connection-id}`</td>
          <td>Any request</td>
          <td>25 requests per second</td>
        </tr>

        <tr>
          <td>Global tenant limit for all SCIM connections</td>
          <td>`/scim/v2/connections/*`</td>
          <td>Any request</td>
          <td>750 requests per second</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Universal Login Flow Endpoints: Rate limits for the endpoints utilized for the Universal Login Authentication Flow for all subscription types.">
    <table>
      <thead>
        <tr>
          <th>Endpoint</th>
          <th>Method</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Universal login prompts (global)</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Universal login prompts (per prompt)</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address and state value.</td>
        </tr>

        <tr>
          <td>Universal login prompts (per prompt)</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Password reset prompt</td>
          <td><code>GET</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA push enrollment prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA push challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment prompt</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment prompt</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment verify prompt</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment verify prompt</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Passwordless SMS challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Passwordless email challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Phone verification enrollment prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Phone verification challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>From an IP Address</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Additional MFA rate limits: Additional MFA rate limits.">
    <table>
      <thead>
        <tr>
          <th>Endpoint</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
          <th>Limit</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>OTP (6 numeric digits) failures</td>
          <td>10</td>
          <td>10</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Recovery code failures</td>
          <td>10</td>
          <td>10</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Webauthn challenge failures</td>
          <td>15</td>
          <td>15</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Webauthn challenge generated</td>
          <td>15</td>
          <td>15</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Push notifications sent per user</td>
          <td>5</td>
          <td>5</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>SMS sent per user</td>
          <td>10</td>
          <td>1</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Email sent per user</td>
          <td>20</td>
          <td>1</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>
      </tbody>
    </table>
  </Accordion>
</AccordionGroup>


# Tier Dev Private Cloud
Source: https://auth0.com/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations/tier-20-development-private-cloud

Rate limits for the Tier 20 (Development) Private Cloud subscription type.

See below for the rate limit policies for the Tier 20 (Development) Private Cloud subscription type.

<AccordionGroup>
  <Accordion title="Authentication API: Rate limits for the Authentication API and API endpoints in the Tier 20 (Development) Private Cloud subscription tier.">
    <table>
      <thead>
        <tr>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#api-rate-limits">API</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Authentication API</td>
          <td>20</td>
          <td>20/second</td>
        </tr>
      </tbody>
    </table>

    <table>
      <thead>
        <tr>
          <th><a href="https://auth0.com/docs/api/authentication#introduction">Endpoint</a></th>
          <th>Method</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#get-user-info">User Info</a></td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#change-password">Change Password</a> <br /><br /> <a href="/docs/authenticate/database-connections/password-change#universal-login-page">Reset Password with Universal Login</a></td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>1/minute</td>
          <td>From an IP Address to a unique Email Address</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#passwordless">Get Passwordless Code or Link</a></td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>50</td>
          <td>50/hour</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#verify-with-one-time-password-otp-">Native Social Login (Apple / Facebook Only)</a></td>
          <td><code>POST</code></td>
          <td>50</td>
          <td>500/minute</td>
          <td>Any Request for Apple or Facebook Native Social Login</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#dynamic-application-client-registration">Dynamic Application (Client) Registration</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#global-token-revocation">Universal Logout</a></td>
          <td><code>POST</code></td>
          <td>35</td>
          <td>35/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td>Pushed Authorization Requests (PAR)</td>
          <td><code>POST</code></td>
          <td>100</td>
          <td>100/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Back-Channel authorize (CIBA)</td>
          <td><code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code activation (no prompt)</td>
          <td><code>POST</code></td>
          <td>30</td>
          <td>6/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code authorization</td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA OOB token exchange</td>
          <td><code>POST</code></td>
          <td>12</td>
          <td>12/minute</td>
          <td>To a unique session</td>
        </tr>

        <tr>
          <td>Token Vault (<a href="/docs/secure/call-apis-on-users-behalf/token-vault">Connected Accounts</a> and <a href="/docs/secure/call-apis-on-users-behalf/token-vault#supported-token-exchanges">token exchange</a></td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>10/second</td>
          <td>Any request</td>
        </tr>
      </tbody>
    </table>

    \*Represents the default limit. You can configure the Signup endpoint limit in Auth0 Dashboard. To learn more, read [Suspicious IP Throttling](/docs/secure/attack-protection/suspicious-ip-throttling).
  </Accordion>

  <Accordion title="Management API: Rate limits for the Management API, API endpoints, and API endpoint groups in the Tier 20 (Development) Private Cloud subscription tier.">
    <table>
      <thead>
        <tr>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#api-rate-limits">API</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Management API</td>
          <td>20</td>
          <td>20/second</td>
        </tr>
      </tbody>
    </table>

    <table>
      <thead>
        <tr>
          <th><a href="https://auth0.com/docs/api/management/v2"><strong>Endpoint</strong></a></th>
          <th><strong>Method</strong></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm"><strong>Burst Request Limit</strong></a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm"><strong>Sustained Request Limit</strong></a></th>
          <th><strong>Limit Type</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organizations">Read Organizations</a></td>
          <td><code>GET</code></td>
          <td>10</td>
          <td>100/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organizations-by-id">Read Organizations by ID</a></td>
          <td><code>GET</code></td>
          <td>40</td>
          <td>500/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-name-by-name">Read Organizations by Name</a></td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-organizations">Write an Organization</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>5</td>
          <td>150/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-members">Read Organization Members</a></td>
          <td><code>GET</code></td>
          <td>40</td>
          <td>500/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-members">Write Organization Members</a></td>
          <td><code>POST</code>, <code>DELETE</code></td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-members">Read Members of an Organization</a></td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organization-member-roles">Read Organization Member Roles</a></td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-organization-member-roles">Write Organization Member Roles</a></td>
          <td><code>POST</code>, <code>DELETE</code></td>
          <td>20</td>
          <td>200/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-enabled-connections">Read Organization Connections</a></td>
          <td><code>GET</code></td>
          <td>10</td>
          <td>100/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-enabled-connections">Write Organization Connections</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>5</td>
          <td>150/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/custom-domains/post-verify">Write Custom Domain</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/connections/get-status">Read Status Connection</a></td>
          <td><code>GET</code></td>
          <td>100</td>
          <td>15/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/keys/post-signing-keys">Write Signing Keys</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/day</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/prompts/get-partials">Read Partials for a Prompt</a></td>
          <td><code>GET</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/prompts/put-partials">Write Partials for a Prompt</a></td>
          <td><code>PUT</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/clients/get-clients">Read Clients</a><p><br />Only applies to the usage of the <code>q</code> parameter.<br /></p></td>
          <td><code>GET</code></td>
          <td>5</td>
          <td>150/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organization-client-grants">Read Organization Client Grants</a></td>
          <td><code>GET</code></td>
          <td>10</td>
          <td>100/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/create-organization-client-grants">Write Organization Client Grants</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>150/minute</td>
          <td>Any request</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="SCIM API: Rate limits for the inbound SCIM API endpoints in the Tier 20 (Development) Private Cloud subscription type.">
    <table>
      <thead>
        <tr>
          <th>Limit Type</th>
          <th>Endpoint Path</th>
          <th>Operation</th>
          <th>Limit</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Single SCIM connection endpoint</td>
          <td>`/scim/v2/connections/{connection-id}`</td>
          <td>Any request</td>
          <td>25 requests per second</td>
        </tr>

        <tr>
          <td>Global tenant limit for all SCIM connections</td>
          <td>`/scim/v2/connections/*`</td>
          <td>Any request</td>
          <td>100 requests per second</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Universal Login Flow Endpoints: Rate limits for the endpoints utilized for the Universal Login Authentication Flow for all subscription types.">
    <table>
      <thead>
        <tr>
          <th>Endpoint</th>
          <th>Method</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Universal login prompts (global)</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Universal login prompts (per prompt)</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address and state value.</td>
        </tr>

        <tr>
          <td>Universal login prompts (per prompt)</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Password reset prompt</td>
          <td><code>GET</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA push enrollment prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA push challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment prompt</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment prompt</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment verify prompt</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment verify prompt</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Passwordless SMS challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Passwordless email challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Phone verification enrollment prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Phone verification challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>From an IP Address</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Additional MFA rate limits: Additional MFA rate limits.">
    <table>
      <thead>
        <tr>
          <th>Endpoint</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
          <th>Limit</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>OTP (6 numeric digits) failures</td>
          <td>10</td>
          <td>10</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Recovery code failures</td>
          <td>10</td>
          <td>10</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Webauthn challenge failures</td>
          <td>15</td>
          <td>15</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Webauthn challenge generated</td>
          <td>15</td>
          <td>15</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Push notifications sent per user</td>
          <td>5</td>
          <td>5</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>SMS sent per user</td>
          <td>10</td>
          <td>1</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Email sent per user</td>
          <td>20</td>
          <td>1</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>
      </tbody>
    </table>
  </Accordion>
</AccordionGroup>


# Private Cloud Performance 3000 RPS (30x) and 3000 RPS (30x) Burst
Source: https://auth0.com/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations/tier-3000-rps-private-cloud

Tier 3000 RPS Private Cloud rate limits

See below for the rate limits in the Private Cloud Performance 3000 RPS (30x) and 3000 RPS (30x) Burst subscription types. These limits apply to each tenant you create in the private cloud environment.

Therefore, we recommend deploying one tenant per private cloud environment for risk mitigation.

<AccordionGroup>
  <Accordion title="Authentication API: Rate limits for the Authentication API and API endpoints in the Private Cloud Performance 3000 RPS (30x) subscription type.">
    <table>
      <thead>
        <tr>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#api-rate-limits">API</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Peak Request Limit</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Authentication API</td>
          <td>3000</td>
          <td>3000/second</td>
          <td>N/A</td>
        </tr>

        <tr>
          <td>Authentication API (30x Burst)</td>
          <td>1500</td>
          <td>1500/second</td>
          <td>3000 Burst; 3000/second sustained</td>
        </tr>
      </tbody>
    </table>

    <table>
      <thead>
        <tr>
          <th><a href="https://auth0.com/docs/api/authentication#introduction">Endpoint</a></th>
          <th>Method</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#get-user-info">User Info</a></td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#change-password">Change Password</a> <br /><br /> <a href="/docs/authenticate/database-connections/password-change#universal-login-page">Reset Password with Universal Login</a></td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>1/minute</td>
          <td>From an IP Address to a unique Email Address</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#passwordless">Get Passwordless Code or Link</a></td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>50</td>
          <td>50/hour</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#verify-with-one-time-password-otp-">Native Social Login (Apple / Facebook Only)</a></td>
          <td><code>POST</code></td>
          <td>50</td>
          <td>500/minute</td>
          <td>Any Request for Apple or Facebook Native Social Login</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#dynamic-application-client-registration">Dynamic Application (Client) Registration</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#global-token-revocation">Universal Logout</a></td>
          <td><code>POST</code></td>
          <td>750</td>
          <td>750/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td>Pushed Authorization Requests (PAR)</td>
          <td><code>POST</code></td>
          <td>100</td>
          <td>100/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Back-Channel authorize (CIBA)</td>
          <td><code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code activation (no prompt)</td>
          <td><code>POST</code></td>
          <td>30</td>
          <td>6/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code authorization</td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA OOB token exchange</td>
          <td><code>POST</code></td>
          <td>12</td>
          <td>12/minute</td>
          <td>To a unique session</td>
        </tr>

        <tr>
          <td><a href="/docs/authenticate/custom-token-exchange">Custom Token Exchange</a></td>
          <td><code>POST</code></td>
          <td>450</td>
          <td>450/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td>Token Vault (<a href="/docs/secure/call-apis-on-users-behalf/token-vault">Connected Accounts</a> and <a href="/docs/secure/call-apis-on-users-behalf/token-vault#supported-token-exchanges">token exchange</a></td>
          <td><code>POST</code></td>
          <td>700</td>
          <td>700/second</td>
          <td>Any request</td>
        </tr>
      </tbody>
    </table>

    \*Represents the default limit. You can configure the Signup endpoint limit in Auth0 Dashboard. To learn more, read [Suspicious IP Throttling](/docs/secure/attack-protection/suspicious-ip-throttling).
  </Accordion>

  <Accordion title="Management API: Rate limits for the Management API, API endpoints, and API endpoint groups in the Private Cloud Performance 3000 RPS (30x) subscription type.">
    <table>
      <thead>
        <tr>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#api-rate-limits">API</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Management API</td>
          <td>1500</td>
          <td>1500/second</td>
        </tr>
      </tbody>
    </table>

    <table>
      <thead>
        <tr>
          <th><a href="https://auth0.com/docs/api/management/v2"><strong>Endpoint</strong></a></th>
          <th><strong>Method</strong></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm"><strong>Burst Request Limit</strong></a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm"><strong>Sustained Request Limit</strong></a></th>
          <th><strong>Limit Type</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organizations">Read Organizations</a></td>
          <td><code>GET</code></td>
          <td>300</td>
          <td>3000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organizations-by-id">Read Organizations by ID</a></td>
          <td><code>GET</code></td>
          <td>300</td>
          <td>15000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-name-by-name">Read Organizations by Name</a></td>
          <td><code>GET</code></td>
          <td>600</td>
          <td>6000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-organizations">Write an Organization</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>150</td>
          <td>4500/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-members">Read Organization Members</a></td>
          <td><code>GET</code></td>
          <td>1200</td>
          <td>15000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-members">Write Organization Members</a></td>
          <td><code>POST</code>, <code>DELETE</code></td>
          <td>600</td>
          <td>6000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-members">Read Members of an Organization</a></td>
          <td><code>GET</code></td>
          <td>600</td>
          <td>6000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organization-member-roles">Read Organization Member Roles</a></td>
          <td><code>GET</code></td>
          <td>600</td>
          <td>6000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-organization-member-roles">Write Organization Member Roles</a></td>
          <td><code>POST</code>, <code>DELETE</code></td>
          <td>600</td>
          <td>6000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-enabled-connections">Read Organization Connections</a></td>
          <td><code>GET</code></td>
          <td>300</td>
          <td>3000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-enabled-connections">Write Organization Connections</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>150</td>
          <td>4500/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/custom-domains/post-verify">Write Custom Domain</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/connections/get-status">Read Status Connection</a></td>
          <td><code>GET</code></td>
          <td>100</td>
          <td>15/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/keys/post-signing-keys">Write Signing Keys</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/day</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/prompts/get-partials">Read Partials for a Prompt</a></td>
          <td><code>GET</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/prompts/put-partials">Write Partials for a Prompt</a></td>
          <td><code>PUT</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/clients/get-clients">Read Clients</a><p><br />Only applies to the usage of the <code>q</code> parameter.<br /></p></td>
          <td><code>GET</code></td>
          <td>150</td>
          <td>4500/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organization-client-grants">Read Organization Client Grants</a></td>
          <td><code>GET</code></td>
          <td>300</td>
          <td>3000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/create-organization-client-grants">Write Organization Client Grants</a></td>
          <td><code>POST</code></td>
          <td>150</td>
          <td>4500/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#create-custom-token-exchange-profile">Write Token Exchange Profiles</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>15</td>
          <td>300/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#manage-custom-token-exchange-profile">Read Token Exchange Profiles</a></td>
          <td><code>GET</code></td>
          <td>600</td>
          <td>6000/minute</td>
          <td>Any request</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="SCIM API: Rate limits for the inbound SCIM API endpoints in the Private Cloud Performance 3000 RPS (30x) subscription type.">
    <table>
      <thead>
        <tr>
          <th>Limit Type</th>
          <th>Endpoint Path</th>
          <th>Operation</th>
          <th>Limit</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Single SCIM connection endpoint</td>
          <td>`/scim/v2/connections/{connection-id}`</td>
          <td>Any request</td>
          <td>25 requests per second</td>
        </tr>

        <tr>
          <td>Global tenant limit for all SCIM connections</td>
          <td>`/scim/v2/connections/*`</td>
          <td>Any request</td>
          <td>1500 requests per second</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Universal Login Flow Endpoints: Rate limits for the endpoints utilized for the Universal Login Authentication Flow for all subscription types.">
    <table>
      <thead>
        <tr>
          <th>Endpoint</th>
          <th>Method</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Universal login prompts (global)</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Universal login prompts (per prompt)</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address and state value.</td>
        </tr>

        <tr>
          <td>Universal login prompts (per prompt)</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Password reset prompt</td>
          <td><code>GET</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA push enrollment prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA push challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment prompt</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment prompt</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment verify prompt</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment verify prompt</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Passwordless SMS challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Passwordless email challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Phone verification enrollment prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Phone verification challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>From an IP Address</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Additional MFA rate limits: Additional MFA rate limits.">
    <table>
      <thead>
        <tr>
          <th>Endpoint</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
          <th>Limit</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>OTP (6 numeric digits) failures</td>
          <td>10</td>
          <td>10</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Recovery code failures</td>
          <td>10</td>
          <td>10</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Webauthn challenge failures</td>
          <td>15</td>
          <td>15</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Webauthn challenge generated</td>
          <td>15</td>
          <td>15</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Push notifications sent per user</td>
          <td>5</td>
          <td>5</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>SMS sent per user</td>
          <td>10</td>
          <td>1</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Email sent per user</td>
          <td>20</td>
          <td>1</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>
      </tbody>
    </table>
  </Accordion>
</AccordionGroup>


# Private Cloud Performance 500 RPS (5x)
Source: https://auth0.com/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations/tier-500-rps-private-cloud

Tier 500 RPS Private Cloud rate limits

See below for the rate limits in the Private Cloud Performance 500 RPS (5x) subscription type.

These limits apply to each tenant you create in the private cloud environment.  Therefore, we recommend deploying one tenant per private cloud environment for risk mitigation.

<AccordionGroup>
  <Accordion title="Authentication API: Rate limits for the Authentication API and API endpoints in the Private Cloud Performance 500 RPS (5x) subscription type.">
    <table>
      <thead>
        <tr>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#api-rate-limits">API</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Authentication API</td>
          <td>500</td>
          <td>500/second</td>
        </tr>
      </tbody>
    </table>

    <table>
      <thead>
        <tr>
          <th><a href="https://auth0.com/docs/api/authentication#introduction">Endpoint</a></th>
          <th>Method</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#get-user-info">User Info</a></td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#change-password">Change Password</a> <br /><br /> <a href="/docs/authenticate/database-connections/password-change#universal-login-page">Reset Password with Universal Login</a></td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>1/minute</td>
          <td>From an IP Address to a unique Email Address</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#passwordless">Get Passwordless Code or Link</a></td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>50</td>
          <td>50/hour</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#verify-with-one-time-password-otp-">Native Social Login (Apple / Facebook Only)</a></td>
          <td><code>POST</code></td>
          <td>50</td>
          <td>500/minute</td>
          <td>Any Request for Apple or Facebook Native Social Login</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#dynamic-application-client-registration">Dynamic Application (Client) Registration</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#global-token-revocation">Universal Logout</a></td>
          <td><code>POST</code></td>
          <td>125</td>
          <td>125/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td>Pushed Authorization Requests (PAR)</td>
          <td><code>POST</code></td>
          <td>100</td>
          <td>100/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Back-Channel authorize (CIBA)</td>
          <td><code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code activation (no prompt)</td>
          <td><code>POST</code></td>
          <td>30</td>
          <td>6/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code authorization</td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA OOB token exchange</td>
          <td><code>POST</code></td>
          <td>12</td>
          <td>12/minute</td>
          <td>To a unique session</td>
        </tr>

        <tr>
          <td><a href="/docs/authenticate/custom-token-exchange">Custom Token Exchange</a></td>
          <td><code>POST</code></td>
          <td>75</td>
          <td>75/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td>Token Vault (<a href="/docs/secure/call-apis-on-users-behalf/token-vault">Connected Accounts</a> and <a href="/docs/secure/call-apis-on-users-behalf/token-vault#supported-token-exchanges">token exchange</a></td>
          <td><code>POST</code></td>
          <td>240</td>
          <td>240/second</td>
          <td>Any request</td>
        </tr>
      </tbody>
    </table>

    \*Represents the default limit. You can configure the Signup endpoint limit in Auth0 Dashboard. To learn more, read [Suspicious IP Throttling](/docs/secure/attack-protection/suspicious-ip-throttling).
  </Accordion>

  <Accordion title="Management API: Rate limits for the Management API, API endpoints, and API endpoint groups in the Private Cloud Performance 500 RPS (5x) subscription type.">
    <table>
      <thead>
        <tr>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#api-rate-limits">API</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Management API</td>
          <td>250</td>
          <td>250/second</td>
        </tr>
      </tbody>
    </table>

    <table>
      <thead>
        <tr>
          <th><a href="https://auth0.com/docs/api/management/v2"><strong>Endpoint</strong></a></th>
          <th><strong>Method</strong></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm"><strong>Burst Request Limit</strong></a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm"><strong>Sustained Request Limit</strong></a></th>
          <th><strong>Limit Type</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organizations">Read Organizations</a></td>
          <td><code>GET</code></td>
          <td>50</td>
          <td>500/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organizations-by-id">Read Organizations by ID</a></td>
          <td><code>GET</code></td>
          <td>50</td>
          <td>2500/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-name-by-name">Read Organizations by Name</a></td>
          <td><code>GET</code></td>
          <td>100</td>
          <td>1000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-organizations">Write an Organization</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>25</td>
          <td>750/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-members">Read Organization Members</a></td>
          <td><code>GET</code></td>
          <td>200</td>
          <td>2500/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-members">Write Organization Members</a></td>
          <td><code>POST</code>, <code>DELETE</code></td>
          <td>100</td>
          <td>1000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-members">Read Members of an Organization</a></td>
          <td><code>GET</code></td>
          <td>100</td>
          <td>1000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organization-member-roles">Read Organization Member Roles</a></td>
          <td><code>GET</code></td>
          <td>100</td>
          <td>1000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-organization-member-roles">Write Organization Member Roles</a></td>
          <td><code>POST</code>, <code>DELETE</code></td>
          <td>100</td>
          <td>1000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-enabled-connections">Read Organization Connections</a></td>
          <td><code>GET</code></td>
          <td>50</td>
          <td>500/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-enabled-connections">Write Organization Connections</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>25</td>
          <td>750/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/custom-domains/post-verify">Write Custom Domain</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/connections/get-status">Write Status Connection</a></td>
          <td><code>POST</code></td>
          <td>100</td>
          <td>15/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/keys/post-signing-keys">Write Signing Keys</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/day</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/prompts/get-partials">Read Partials for a Prompt</a></td>
          <td><code>GET</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/prompts/put-partials">Write Partials for a Prompt</a></td>
          <td><code>PUT</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/clients/get-clients">Read Clients</a><p><br />Only applies to the usage of the <code>q</code> parameter.<br /></p></td>
          <td><code>GET</code></td>
          <td>25</td>
          <td>750/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organization-client-grants">Read Organization Client Grants</a></td>
          <td><code>GET</code></td>
          <td>50</td>
          <td>500/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/create-organization-client-grants">Write Organization Client Grants</a></td>
          <td><code>POST</code></td>
          <td>25</td>
          <td>750/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#create-custom-token-exchange-profile">Write Token Exchange Profiles</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>15</td>
          <td>300/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#manage-custom-token-exchange-profile">Read Token Exchange Profiles</a></td>
          <td><code>GET</code></td>
          <td>100</td>
          <td>1000/minute</td>
          <td>Any request</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="SCIM API: Rate limits for the inbound SCIM API endpoints in the Private Cloud Performance 500 RPS (5x) subscription type.">
    <table>
      <thead>
        <tr>
          <th>Limit Type</th>
          <th>Endpoint Path</th>
          <th>Operation</th>
          <th>Limit</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Single SCIM connection endpoint</td>
          <td>`/scim/v2/connections/{connection-id}`</td>
          <td>Any request</td>
          <td>25 requests per second</td>
        </tr>

        <tr>
          <td>Global tenant limit for all SCIM connections</td>
          <td>`/scim/v2/connections/*`</td>
          <td>Any request</td>
          <td>250 requests per second</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Universal Login Flow Endpoints: Rate limits for the endpoints utilized for the Universal Login Authentication Flow for all subscription types.">
    <table>
      <thead>
        <tr>
          <th>Endpoint</th>
          <th>Method</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Universal login prompts (global)</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Universal login prompts (per prompt)</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address and state value.</td>
        </tr>

        <tr>
          <td>Universal login prompts (per prompt)</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Password reset prompt</td>
          <td><code>GET</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA push enrollment prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA push challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment prompt</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment prompt</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment verify prompt</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment verify prompt</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Passwordless SMS challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Passwordless email challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Phone verification enrollment prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Phone verification challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>From an IP Address</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Additional MFA rate limits: Additional MFA rate limits.">
    <table>
      <thead>
        <tr>
          <th>Endpoint</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
          <th>Limit</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>OTP (6 numeric digits) failures</td>
          <td>10</td>
          <td>10</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Recovery code failures</td>
          <td>10</td>
          <td>10</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Webauthn challenge failures</td>
          <td>15</td>
          <td>15</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Webauthn challenge generated</td>
          <td>15</td>
          <td>15</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Push notifications sent per user</td>
          <td>5</td>
          <td>5</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>SMS sent per user</td>
          <td>10</td>
          <td>1</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Email sent per user</td>
          <td>20</td>
          <td>1</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>
      </tbody>
    </table>
  </Accordion>
</AccordionGroup>


# Private Cloud Performance 6000 RPS (60x) and 6000 RPS (60x) Burst
Source: https://auth0.com/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-configurations/tier-6000-rps-private-cloud

Tier 6000 RPS Private Cloud rate limits

See below for the rate limits in the Private Cloud Performance 6000 RPS (60x) and 6000 RPS (60x) Burst subscription types.

Therefore, we recommend deploying one tenant per private cloud environment for risk mitigation.

<AccordionGroup>
  <Accordion title="Authentication API: Rate limits for the Authentication API, API endpoints, and API endpoint groups in the Private Cloud Performance 6000 RPS (60x) subscription type.">
    <table>
      <thead>
        <tr>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#api-rate-limits">API</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Peak Request Limit</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Authentication API</td>
          <td>6000</td>
          <td>6000/second</td>
          <td>N/A</td>
        </tr>

        <tr>
          <td>Authentication API (60x Burst)</td>
          <td>3000</td>
          <td>3000/second</td>
          <td>6000 Burst; 6000/second sustained</td>
        </tr>
      </tbody>
    </table>

    <table>
      <thead>
        <tr>
          <th><a href="https://auth0.com/docs/api/authentication#introduction">Endpoint</a></th>
          <th>Method</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#get-user-info">User Info</a></td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#change-password">Change Password</a> <br /><br /> <a href="/docs/authenticate/database-connections/password-change#universal-login-page">Reset Password with Universal Login</a></td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>1/minute</td>
          <td>From an IP Address to a unique Email Address</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#passwordless">Get Passwordless Code or Link</a></td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>50</td>
          <td>50/hour</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#verify-with-one-time-password-otp-">Native Social Login (Apple / Facebook Only)</a></td>
          <td><code>POST</code></td>
          <td>50</td>
          <td>500/minute</td>
          <td>Any Request for Apple or Facebook Native Social Login</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#dynamic-application-client-registration">Dynamic Application (Client) Registration</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/authentication#global-token-revocation">Universal Logout</a></td>
          <td><code>POST</code></td>
          <td>1500</td>
          <td>1500/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td>Pushed Authorization Requests (PAR)</td>
          <td><code>POST</code></td>
          <td>100</td>
          <td>100/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Back-Channel authorize (CIBA)</td>
          <td><code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code activation (no prompt)</td>
          <td><code>POST</code></td>
          <td>30</td>
          <td>6/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code authorization</td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA OOB token exchange</td>
          <td><code>POST</code></td>
          <td>12</td>
          <td>12/minute</td>
          <td>To a unique session</td>
        </tr>

        <tr>
          <td><a href="/docs/authenticate/custom-token-exchange">Custom Token Exchange</a></td>
          <td><code>POST</code></td>
          <td>900</td>
          <td>900/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td>Token Vault (<a href="/docs/secure/call-apis-on-users-behalf/token-vault">Connected Accounts</a> and <a href="/docs/secure/call-apis-on-users-behalf/token-vault#supported-token-exchanges">token exchange</a></td>
          <td><code>POST</code></td>
          <td>700</td>
          <td>700/second</td>
          <td>Any request</td>
        </tr>
      </tbody>
    </table>

    \*Represents the default limit. You can configure the Signup endpoint limit in Auth0 Dashboard. To learn more, read [Suspicious IP Throttling](/docs/secure/attack-protection/suspicious-ip-throttling).
  </Accordion>

  <Accordion title="Management API: Rate limits for the Management API, API endpoints, and API endpoint groups in the Private Cloud Performance 6000 RPS (60x) subscription type.">
    <table>
      <thead>
        <tr>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#api-rate-limits">API</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Management API</td>
          <td>3000</td>
          <td>3000/second</td>
        </tr>
      </tbody>
    </table>

    <table>
      <thead>
        <tr>
          <th><a href="https://auth0.com/docs/api/management/v2"><strong>Endpoint</strong></a></th>
          <th><strong>Method</strong></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm"><strong>Burst Request Limit</strong></a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm"><strong>Sustained Request Limit</strong></a></th>
          <th><strong>Limit Type</strong></th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organizations">Read Organizations</a></td>
          <td><code>GET</code></td>
          <td>600</td>
          <td>6000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organizations-by-id">Read Organizations by ID</a></td>
          <td><code>GET</code></td>
          <td>600</td>
          <td>30000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-name-by-name">Read Organizations by Name</a></td>
          <td><code>GET</code></td>
          <td>1200</td>
          <td>12000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-organizations">Write an Organization</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>300</td>
          <td>9000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-members">Read Organization Members</a></td>
          <td><code>GET</code></td>
          <td>2400</td>
          <td>30000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-members">Write Organization Members</a></td>
          <td><code>POST</code>, <code>DELETE</code></td>
          <td>1200</td>
          <td>12000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-members">Read Members of an Organization</a></td>
          <td><code>GET</code></td>
          <td>1200</td>
          <td>12000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organization-member-roles">Read Organization Member Roles</a></td>
          <td><code>GET</code></td>
          <td>1200</td>
          <td>12000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-organization-member-roles">Write Organization Member Roles</a></td>
          <td><code>POST</code>, <code>DELETE</code></td>
          <td>1200</td>
          <td>12000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-enabled-connections">Read Organization Connections</a></td>
          <td><code>GET</code></td>
          <td>600</td>
          <td>6000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/post-enabled-connections">Write Organization Connections</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>300</td>
          <td>9000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/custom-domains/post-verify">Write Custom Domain</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/connections/get-status">Write Status Connection</a></td>
          <td><code>POST</code></td>
          <td>100</td>
          <td>15/second</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/keys/post-signing-keys">Write Signing Keys</a></td>
          <td><code>POST</code></td>
          <td>5</td>
          <td>5/day</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/prompts/get-partials">Read Partials for a Prompt</a></td>
          <td><code>GET</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/prompts/put-partials">Write Partials for a Prompt</a></td>
          <td><code>PUT</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/clients/get-clients">Read Clients</a><p><br />Only applies to the usage of the <code>q</code> parameter.<br /></p></td>
          <td><code>GET</code></td>
          <td>300</td>
          <td>9000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/get-organization-client-grants">Read Organization Client Grants</a></td>
          <td><code>GET</code></td>
          <td>600</td>
          <td>6000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="https://auth0.com/docs/api/management/v2/organizations/create-organization-client-grants">Write Organization Client Grants</a></td>
          <td><code>POST</code></td>
          <td>300</td>
          <td>9000/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#create-custom-token-exchange-profile">Write Token Exchange Profiles</a></td>
          <td><code>POST</code>, <code>PATCH</code>, <code>DELETE</code></td>
          <td>15</td>
          <td>300/minute</td>
          <td>Any request</td>
        </tr>

        <tr>
          <td><a href="/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#manage-custom-token-exchange-profile">Read Token Exchange Profiles</a></td>
          <td><code>GET</code></td>
          <td>1200</td>
          <td>12000/minute</td>
          <td>Any request</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="SCIM API: Rate limits for the inbound SCIM API endpoints in the Private Cloud Performance 6000 RPS (60x) subscription type.">
    <table>
      <thead>
        <tr>
          <th>Limit Type</th>
          <th>Endpoint Path</th>
          <th>Operation</th>
          <th>Limit</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Single SCIM connection endpoint</td>
          <td>`/scim/v2/connections/{connection-id}`</td>
          <td>Any request</td>
          <td>25 requests per second</td>
        </tr>

        <tr>
          <td>Global tenant limit for all SCIM connections</td>
          <td>`/scim/v2/connections/*`</td>
          <td>Any request</td>
          <td>3000 requests per second</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Universal Login Flow Endpoints: Rate limits for the endpoints utilized for the Universal Login Authentication Flow for all subscription types.">
    <table>
      <thead>
        <tr>
          <th>Endpoint</th>
          <th>Method</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Universal login prompts (global)</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Universal login prompts (per prompt)</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address and state value.</td>
        </tr>

        <tr>
          <td>Universal login prompts (per prompt)</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Password reset prompt</td>
          <td><code>GET</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA push enrollment prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA push challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>500</td>
          <td>500/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment prompt</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment prompt</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment verify prompt</td>
          <td><code>GET</code></td>
          <td>20</td>
          <td>10/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>MFA SMS enrollment verify prompt</td>
          <td><code>POST</code></td>
          <td>10</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Passwordless SMS challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Passwordless email challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Phone verification enrollment prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Phone verification challenge prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/minute</td>
          <td>From an IP Address</td>
        </tr>

        <tr>
          <td>Device code prompt</td>
          <td><code>GET</code>, <code>POST</code></td>
          <td>5</td>
          <td>5/second</td>
          <td>From an IP Address</td>
        </tr>
      </tbody>
    </table>
  </Accordion>

  <Accordion title="Additional MFA rate limits: Additional MFA rate limits.">
    <table>
      <thead>
        <tr>
          <th>Endpoint</th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Burst Request Limit</a></th>
          <th><a href="/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy#rate-limit-algorithm">Sustained Request Limit</a></th>
          <th>Limit Type</th>
          <th>Limit</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>OTP (6 numeric digits) failures</td>
          <td>10</td>
          <td>10</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Recovery code failures</td>
          <td>10</td>
          <td>10</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Webauthn challenge failures</td>
          <td>15</td>
          <td>15</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Webauthn challenge generated</td>
          <td>15</td>
          <td>15</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Push notifications sent per user</td>
          <td>5</td>
          <td>5</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>SMS sent per user</td>
          <td>10</td>
          <td>1</td>
          <td>per hour</td>
          <td>To a unique User ID</td>
        </tr>

        <tr>
          <td>Email sent per user</td>
          <td>20</td>
          <td>1</td>
          <td>per minute</td>
          <td>To a unique User ID</td>
        </tr>
      </tbody>
    </table>
  </Accordion>
</AccordionGroup>


# Rate Limit Use Cases
Source: https://auth0.com/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/rate-limit-use-cases

How to determine if you are being rate limited

## Discover when requests to a tenant are rate-limited

There are a handful of ways to determine if a customer product is being rate limited by Auth0. See below for the possible causes of rate limitation.

### Tenant logs

By subscribing to different tenant logs, you can track issues related to request volumes. To understand how tenant and operations event logs work in Auth0, read [Logs](/docs/deploy-monitor/logs).

#### api\_limit

The `api_limit` event is triggered immediately after a rate limit is exceeded for the global rate limit bucket for the Authentication or <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. If the number of request tokens utilized remains above 80% after one minute for the same rate limit bucket, a second warning log is generated. If a rate limit is exceeded for a different rate limit bucket, a new `api_limit` event is generated. This helps customers identify which rate limit configuration their API calls are triggering, which is a critical first step in diagnosing the root cause.

#### api\_limit\_warning

The `api_limit_warning` log is triggered when a customer's request rate consumes 80% of the request tokens for a given rate limit bucket. If the number of request tokens utilized remains above 80% after one minute for the same rate limit bucket, a second warning log is generated. If the 80% threshold is exceeded for a different rate limit bucket, a new `api_limit_warning` log is created.

#### appi (Public Performance Burst Only)

The `appi` log is triggered when a customer tenant with a Public Performance Burst add-on exceeds their sustained Authentication API request rate limit of 100 RPS, consuming a 15-minute block of their 48-hour burst allocation. If, after 15 minutes, the request rate exceeds the 100 RPS sustained request limit again, a second `appi` log will be triggered.

### API responses

Auth0 API responses deliver [HTTP 429 (Too Many Requests)](http://tools.ietf.org/html/rfc6585#section-4) responses with the exceeded rate limit. This enables customers to observe rate limit enforcement in real time. However, this is only useful for custom-built customer applications interacting directly with the Auth0 API.

### SDK error handling

If you are using an SDK, refer to the [Management API SDK libraries](/docs/libraries#mgmt) error pages.

### Error pages

The error page response is sent for endpoints that render HTML content to the end user. If your tenant is configured to use generic (Auth0 hosted) pages, Auth0 renders the error page instead of the expected content when you exceed the response limit.  If your tenant is configured to use [custom error pages](/docs/customize/login-pages/custom-error-pages), the user is redirected to the custom error page URL with the relevant error in the `error_description` query string parameter.  For more information, see [Affected endpoints](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/authentication-api-endpoint-rate-limits#affected-endpoints) and the [JSON Error](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/authentication-api-endpoint-rate-limits#json-error) descriptions.

## Find out why a tenant is being rate limited

If you believe tenant requests are rate limited and need assistance to understand why, open a request via the [Support Center](http://support.auth0.com).  As part of your request, please include the full raw log where the issue was seen.

## Predict when requests to a tenant will be rate limited

Auth0 reports up-to-date information on the current status of your rate limits using HTTP response headers from endpoints that have rate limit policies configured. This status is communicated as follows:

* `x-ratelimit-limit`: Maximum number of requests available.
* `x-ratelimit-remaining`: Number of remaining requests available until the bucket is refilled with additional requests.
* `x-ratelimit-reset`: [UNIX timestamp](https://en.wikipedia.org/wiki/Unix_time), in seconds, of the expected time when additional requests will be added to the bucket.

For example:

An API has the following rate limit:

* Burst Limit: `1000`
* Sustained Rate Limit: `100` `requests per second` (on a fixed window)

From this information, you can derive:

* The sustained rate limit is `100 requests per second` on a fixed window.
* Due to the fixed window, the bucket of requests is refilled every second.

If you receive the following x-headers in your API response:

* `x-ratelimit-limit: 1000`
* `x-ratelimit-remaining: 50`
* `x-ratelimit-reset: 1675452600`

You now know that:

* Your tenant has used up 950 of the 1000 requests allowable to that API, and only has 50 requests remaining until such time that additional requests are added.
* New requests will be added at `1675452600`, or 7:30:00 PM UTC on February 3, 2023.
* 1 new request will be added at that time

Therefore, if you are making requests at a rate greater than what is described above, then a rate limitation is expected.  How soon you will be rate limited depends on the burst limit and to what extent you are exceeding the sustained limit.

## Examples of how rate limits are enforced

### Requests per second example

Assume Auth0 launches a new API called `/ratelimitexample` with the following rate limit values:

* Burst limit: Five (5) requests
* Sustained rate limit: 10 requests per second.

Key points:

* API begins with, and will never exceed, five request tokens, which is equal to the burst limit.
* The bucket of 10 tokens is refilled every second, using a “fixed window.” New tokens are added to the bucket, refilling it at the “top” of each second.

 Example scenario with rate limits:

<Frame>
  <img alt="" />
</Frame>

In this scenario:

* T0 - T1sec:  The end user makes six requests in the first second.  Five requests – equal to the burst limit – receive a `200` response.  The sixth request receives a `429` error because there are no remaining request tokens in the bucket.
* T1sec - T2sec:  Auth0 tops off the bucket of request tokens because of the fixed window algorithm. As a result, the seventh through 11th requests are successful, exhausting the bucket by the 12th request, resulting in a `429` error.
* T2sec - T3sec:  Auth0 refills the token bucket once again, and the next request (13) receives a `200` response.

### Requests per minute example

Assume Auth0 launches a new API called `/ratelimitexample2` with the following rate limit values:

* Burst limit:  Five (5) requests
* Sustained Rate limit:  Six (6) requests per minute.

Key points:

* API begins with five request tokens, which is equal to the burst limit.
* The bucket of six tokens is refilled every minute, using a “fixed window.” New tokens are added to the bucket, refilling the it at the “top” of each minute.

Example scenario with rate limits:

<Frame>
  <img alt="" />
</Frame>

In this scenario:

* T0 - T+1min:  The end user makes six requests in the first minute. Five requests – equal to the burst limit – receive a `200` response.  The sixth request receives a `429` error because there are no remaining request tokens.
* T+1min - T+2min:  Auth0 refills the token bucket because of the fixed window algorithm. As a result, the seventh through 11th requests are successful, exhausting the bucket by the 12th request, resulting in a `429` error.
* T+2min: Auth0 refills the token bucket once again, and the next request (13) receives a `200` response.

### Other scenarios

On occasion, Auth0 will assign two rate limits to a single API.  This is done in order to configure a burst limit and the sustained rate limit that is more customized to the needs of the service.  In effect, the first rate limit becomes the effective burst limit, and the second rate limit becomes the effective sustained rate limit.  In this scenario, Auth0 only publishes the effective burst and sustained rate limits, rather than communicating the actual burst and sustained rate limits.

## End-user Login and Signup API usage

There are a handful of Authentication Flows, including Login, Signup and Change Password.  The most common of these are typically Login, followed by Signup.

An end user's login initiates multiple API calls to Authentication API endpoints in order to determine if the end user is authorized to receive an Authorization token, and thereby access the application they have requested.

The precise number of API calls is a function of a handful of configurations:

* Authentication Experience (e.g., New <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> or Classic Login)
* Authentication Flow (e.g., Login, Signup, or Change Password)
* Authentication Flow Type (e.g., Login via Username / Password; Login via Social Login; Login when an existing Authentication Token already exists)

Below, we describe some common customer configurations, and their impact on API Usage.

### Universal Login

[Auth0 Universal Login](/docs/authenticate/login/auth0-universal-login) provides the essential feature of an <Tooltip href="/docs/glossary?term=authorization+server">authorization server</Tooltip>: the login flow. When a user needs to prove their identity to gain access to your application, you can redirect them to Universal Login and let Auth0 handle the authentication process.

<table>
  <thead>
    <tr>
      <th>Authentication flow</th>
      <th>Flow type</th>
      <th>Requests to Authentication API endpoints</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Login</td>
      <td>Username/Password Challenge\*</td>
      <td>5</td>
    </tr>

    <tr>
      <td>Login</td>
      <td>3rd Party Identity Provider – e.g., Social or Work Login</td>
      <td>6</td>
    </tr>

    <tr>
      <td>Login</td>
      <td>Auth0 Authentication Session Exists</td>
      <td>1</td>
    </tr>

    <tr>
      <td>Signup</td>
      <td>via Username/Password</td>
      <td>6</td>
    </tr>
  </tbody>
</table>

#### Modifiers

Certain authentication configurations modify the base request count. These adjustments depend on additional security measures or authentication flows:

<table>
  <thead>
    <tr>
      <th><strong>Modifier</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Additional Requests</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>ID First</strong></td>
      <td>Identifies the user before requesting credentials.</td>
      <td>+2</td>
    </tr>

    <tr>
      <td><strong>MFA</strong></td>
      <td>Adds Multi-Factor Authentication.</td>
      <td>+2 per factor</td>
    </tr>

    <tr>
      <td><strong>OTP</strong></td>
      <td>One-time password for Authentication</td>
      <td>+2</td>
    </tr>

    <tr>
      <td><strong>Enterprise Login</strong></td>
      <td>Authentication through an enterprise connection (e.g., SAML, OIDC, LDAP).</td>
      <td>+1</td>
    </tr>

    <tr>
      <td><strong>Client Credentials</strong></td>
      <td>Used for machine-to-machine authentication. Applies universally, even if actions are used.</td>
      <td>+1</td>
    </tr>
  </tbody>
</table>

\*Anything used in combination adds to the overall requests.

### Classic login

[Classic Login](/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/classic-experience) is an Auth0-hosted login experience that relies on JavaScript for customization. Implementing Classic Login is less complex than embedding the authentication process directly in your app, and can help prevent the dangers of cross-origin authentication.

<table>
  <thead>
    <tr>
      <th>Authentication flow</th>
      <th>Flow type</th>
      <th>Requests</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Login</td>
      <td>Username/password challenge</td>
      <td>8</td>
    </tr>

    <tr>
      <td>Login</td>
      <td>3rd Party Identity Provider – e.g., Social or Work Login</td>
      <td>8</td>
    </tr>

    <tr>
      <td>Login</td>
      <td>Auth0 authentication session exists</td>
      <td>2</td>
    </tr>

    <tr>
      <td>Signup</td>
      <td>Username/password</td>
      <td>8</td>
    </tr>
  </tbody>
</table>

<Warning>
  Customers configuring Custom Databases should add two (2) additional authentication API calls to each authentication flow described above. For more details, see [Custom Database Connections](/docs/authenticate/database-connections/custom-db).
</Warning>

#### Modifiers

The following factors increase request counts for Classic Login:

<table>
  <thead>
    <tr>
      <th><strong>Modifier</strong></th>
      <th><strong>Description</strong></th>
      <th><strong>Additional Requests</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><strong>SMS Authentication Only</strong></td>
      <td>When using SMS as the primary authentication method.</td>
      <td>+7</td>
    </tr>

    <tr>
      <td><strong>Native Social Login</strong></td>
      <td>Login using a native social provider (e.g., Google, Facebook).</td>
      <td>+1</td>
    </tr>

    <tr>
      <td><strong>Redirects</strong></td>
      <td>Additional redirects during authentication increase request count.</td>
      <td>+1</td>
    </tr>
  </tbody>
</table>


# Product Support Matrix
Source: https://auth0.com/docs/troubleshoot/customer-support/product-support-matrix

Describes Auth0 features, platforms, and software configurations.

Auth0 provides support in alignment with the [terms of service](https://auth0.com/terms) and [pricing and support plans](https://auth0.com/pricing/). These are the types of support provided by Auth0:

<table>
  <thead>
    <tr>
      <th><strong>Level</strong></th>
      <th><strong>Description</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Supported</td>
      <td>Auth0 has formally tested these items, may provide both new features and bug fixes (if applicable), and will provide customer support.</td>
    </tr>

    <tr>
      <td>Sustained</td>
      <td>Auth0 may provide bug fixes (if applicable) for these items, and will provide customer support.</td>
    </tr>

    <tr>
      <td>Bug Fixes</td>
      <td>Auth0 may provide bug fixes (if applicable) for these items, but will not provide customer support.</td>
    </tr>

    <tr>
      <td>Community</td>
      <td>Auth0 will not provide customer support for these items, and all assistance will come from the general community.</td>
    </tr>

    <tr>
      <td>Partner</td>
      <td>Auth0 will not provide customer support for these items, and all assistance will come from the partners who maintain them.</td>
    </tr>
  </tbody>
</table>

## Auth0 support coverage

Official support provided by Auth0 is limited to the languages, platforms, versions, and technologies specifically listed. Anything that is not listed, or is listed as community-supported is not eligible for Auth0 support. If you have questions about unsupported items, you can post your question on the [Auth0 public forum](https://community.auth0.com/).

For community-supported items, ask for help by contacting the developers responsible for those items such as submitting issues on the GitHub repositories for the specific libraries or SDKs.

Auth0 support is limited to the most recent version of the technologies listed (unless otherwise specified). If you are using an older version, you will be required to upgrade prior to seeking support.

## Supported browsers

All listed browsers are the latest versions unless otherwise indicated.

### Auth0 Dashboard desktop browsers

<Warning>
  Auth0 does not support mobile browsers for using the Dashboard.
</Warning>

<table>
  <thead>
    <tr>
      <th><strong>Browser</strong></th>
      <th><strong>Support Level</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Chrome</td>
      <td>Supported</td>
    </tr>

    <tr>
      <td>Safari</td>
      <td>Sustained</td>
    </tr>

    <tr>
      <td>Edge</td>
      <td>Sustained</td>
    </tr>

    <tr>
      <td>Firefox</td>
      <td>Sustained</td>
    </tr>
  </tbody>
</table>

### Authentication desktop browsers

<table>
  <thead>
    <tr>
      <th><strong>Browser</strong></th>
      <th><strong>Support Level</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Chrome</td>
      <td>Supported</td>
    </tr>

    <tr>
      <td>Safari</td>
      <td>Sustained</td>
    </tr>

    <tr>
      <td>Internet Explorer (v10/11)</td>
      <td>Sustained\*</td>
    </tr>

    <tr>
      <td>Edge</td>
      <td>Sustained</td>
    </tr>

    <tr>
      <td>Firefox</td>
      <td>Sustained</td>
    </tr>
  </tbody>
</table>

<Warning>
  \*Starting with v2.0.0, the Auth0 SPA SDK no longer supports Internet Explorer 11. To learn more about this change, read the [SPA-JS v2 Migration Guide on Github](https://github.com/auth0/auth0-spa-js/blob/master/MIGRATION_GUIDE.md).
</Warning>

### Authentication mobile browsers

<table>
  <thead>
    <tr>
      <th><strong>Browser</strong></th>
      <th><strong>Support Level</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Safari iOS 10+</td>
      <td>Supported</td>
    </tr>

    <tr>
      <td>Chrome for Android 7.1.1+</td>
      <td>Supported</td>
    </tr>
  </tbody>
</table>

## Supported operating systems

All listed operating systems are the latest versions unless otherwise indicated. If you are using an older version, please upgrade prior to seeking support.

### Auth0 Dashboard operating systems

<table>
  <thead>
    <tr>
      <th><strong>Operating System</strong></th>
      <th><strong>Support Level</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Apple MacOS (with Chrome)</td>
      <td>Supported</td>
    </tr>

    <tr>
      <td>Apple MacOS (with other browsers)</td>
      <td>Sustained</td>
    </tr>

    <tr>
      <td>Linux Ubuntu</td>
      <td>Sustained</td>
    </tr>

    <tr>
      <td>Microsoft Windows</td>
      <td>Sustained</td>
    </tr>
  </tbody>
</table>

### Authentication supported operating systems

<table>
  <thead>
    <tr>
      <th><strong>Operating System</strong></th>
      <th><strong>Support Level</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Apple MacOS (with Chrome)</td>
      <td>Supported</td>
    </tr>

    <tr>
      <td>Apple MacOS (with other browsers)</td>
      <td>Sustained</td>
    </tr>

    <tr>
      <td>Apple iOS 10+</td>
      <td>Supported</td>
    </tr>

    <tr>
      <td>Google Android 7.1.1+</td>
      <td>Supported</td>
    </tr>

    <tr>
      <td>Linux Ubuntu</td>
      <td>Sustained</td>
    </tr>

    <tr>
      <td>Microsoft Windows</td>
      <td>Sustained</td>
    </tr>
  </tbody>
</table>

## Supported Auth0 libraries and SDKs

### Auth0 Lock widgets and libraries

<table>
  <thead>
    <tr>
      <th><strong>Library</strong></th>
      <th><strong>Support Level</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="https://github.com/auth0/lock/tree/master" title="Lock.js">Lock.js</a></td>
      <td>Bug Fixes</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/Lock.Android/tree/main" title="Lock.android v3">Lock.Android v3</a></td>
      <td>Bug Fixes</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/Lock.Android/tree/v2" title="Lock.Android v2">Lock.Android v2</a></td>
      <td>Bug Fixes</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/Lock.swift/tree/master" title="Lock for iOS v2">Lock for iOS v2</a></td>
      <td>Bug Fixes</td>
    </tr>
  </tbody>
</table>

### Auth0 SDKs

<table>
  <thead>
    <tr>
      <th><strong>SDK</strong></th>
      <th><strong>Support Level</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="https://github.com/auth0/auth0-react" title="Auth0 React">Auth0 React</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/nextjs-auth0" title="Auth0 Next.js">Auth0 Next.js</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/auth0-vue" title="Auth0 Vue">Auth0 Vue</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/auth0-nuxt" title="Auth0 Nuxt">Auth0 Nuxt</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/auth0-angular" title="Auth0 Angular">Auth0 Angular</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/angular-lock/tree/master" title="Angular Lock">Angular Lock</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/auth0-spa-js/tree/master" title="Auth0 SPA JS">Auth0 SPA JS</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/auth0.js/tree/master" title="Auth0.js">Auth0.js</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/react-native-auth0" title="Auth0 React Native">Auth0 React Native</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/auth0-flutter" title="Auth0 Flutter">Auth0 Flutter</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/Auth0.Android/tree/main" title="Auth0 Android">Auth0 Android</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/Auth0.Swift/tree/master" title="Auth0 Swift">Auth0 Swift</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/node-auth0/tree/master" title="Auth0 Node">Auth0 Node</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/auth0-auth-js/tree/main/packages/auth0-auth-js" title="Auth0 Auth JS">Auth0 Auth JS</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/auth0-auth-js/tree/main/packages/auth0-server-js" title="Auth0 Server JS">Auth0 Server JS</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/auth0-auth-js/tree/main/packages/auth0-api-js" title="Auth0 API JS">Auth0 API JS</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/express-openid-connect" title="Express OpenID Connect">Express OpenID Connect</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/node-oauth2-jwt-bearer/tree/main/packages/express-oauth2-jwt-bearer" title="Express OAuth2 JWT Bearer">Express OAuth2 JWT Bearer</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/auth0-python/tree/master" title="Auth0 Python">Auth0 Python</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/auth0-server-python" title="Auth0 Server Python">Auth0 Server Python</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/auth0-api-python" title="Auth0 API Python">Auth0 API Python</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/Auth0.net/tree/master" title="Auth0 .NET">Auth0 .NET</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/auth0-oidc-client-net/tree/master" title="Auth0 OIDC Client for .NET">Auth0 OIDC Client for .NET</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/auth0-aspnetcore-authentication" title="Auth0 ASP.NET Core Authentication">Auth0 ASP.NET Core Authentication</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/aspnetcore-api" title="Auth0 ASP.NET Core API">Auth0 ASP.NET Core API</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/Auth0-java/tree/master" title="Auth0 Java">Auth0 Java</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/auth0-java-mvc-common/tree/master" title="Auth0 Java MVC Common">Auth0 Java MVC Common</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/auth0-php/tree/master" title="Auth0 PHP">Auth0 PHP</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/laravel-auth0" title="Laravel Auth0">Laravel Auth0</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/go-auth0" title="Go Auth0">Go Auth0</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/go-jwt-middleware" title="Go JWT Middleware">Go JWT Middleware</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/ruby-auth0" title="Auth0 Ruby">Auth0 Ruby</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/omniauth-auth0" title="OmniAuth Auth0">OmniAuth Auth0</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/jwt-auth-bundle/tree/3.x.x-dev" title="JWT Auth Bundle (v3)">JWT Auth Bundle (v3)</a></td>
      <td>Bug Fixes</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/jwt-auth-bundle/tree/master" title="JWT Auth Bundle">JWT Auth Bundle</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/universal-login/blob/master/packages/auth0-acul-js/README.md" title="Auth0 ACUL JS">Auth0 ACUL JS</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/universal-login/blob/master/packages/auth0-acul-react/README.md" title="Auth0 ACUL React">Auth0 ACUL React</a></td>
      <td>Supported</td>
    </tr>
  </tbody>
</table>

### Content Management Systems Plugins

<table>
  <thead>
    <tr>
      <th><strong>CMS</strong></th>
      <th><strong>Support Level</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="https://github.com/auth0/wp-auth0/tree/master" title="WordPress">WordPress</a></td>
      <td>Supported</td>
    </tr>
  </tbody>
</table>

## Samples

### Native and mobile apps

<table>
  <thead>
    <tr>
      <th><strong>Technology</strong></th>
      <th><strong>Support Level</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-ios-swift-sample/tree/master" title="iOS / macOS">iOS / macOS</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-android-sample/tree/master" title="Android">Android</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-react-native-sample/tree/master" title="React Native">React Native</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-react-native-sample/tree/master/00-Login-Expo" title="Expo">Expo</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-flutter-samples/tree/main/sample" title="Flutter">Flutter</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-xamarin-oidc-samples/tree/master/Quickstart/01-Login" title=".NET Android and iOS">.NET Android and iOS</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-maui-samples/tree/master/Sample" title="MAUI">MAUI</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-ionic-samples/tree/master/angular" title="Ionic & Capacitor (Angular)">Ionic & Capacitor (Angular)</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-ionic-samples/tree/master/react" title="Ionic & Capacitor (React)">Ionic & Capacitor (React)</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-ionic-samples/tree/master/vue" title="Ionic & Capacitor (Vue)">Ionic & Capacitor (Vue)</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-uwp-oidc-samples/tree/master/Quickstart/00-Starter-Seed" title="UWP">UWP</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-WinFormsWPF-oidc-samples/tree/master" title="WPF / Winforms">WPF / Winforms</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-xamarin-oidc-samples/tree/master" title="Xamarin">Xamarin</a></td>
      <td>Supported</td>
    </tr>
  </tbody>
</table>

### SPAs

<table>
  <thead>
    <tr>
      <th><strong>Technology</strong></th>
      <th><strong>Support Level</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-react-samples/tree/master" title="React">React</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-angular-samples/tree/master" title="Angular">Angular</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-javascript-samples/tree/master" title="JavaScript">JavaScript</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-vue-samples/tree/master" title="Vue">Vue</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-flutter-samples/tree/main/sample" title="Flutter (Web)">Flutter (Web)</a></td>
      <td>Supported</td>
    </tr>
  </tbody>
</table>

### Regular web apps

<table>
  <thead>
    <tr>
      <th><strong>Technology</strong></th>
      <th><strong>Support Level</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-nextjs-samples/tree/main/Sample-01" title="Next.js">Next.js</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-express-webapp-sample/tree/master/01-Login" title="Express">Express</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-python-web-app/tree/master" title="Python">Python</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-django-web-app/tree/master" title="Django">Django</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-golang-web-app/tree/master" title="Go">Go</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-servlet-sample/tree/master" title="Java">Java</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-java-ee-sample/tree/master" title="Java EE">Java EE</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-spring-boot-login-samples/tree/master" title="Java Spring Boot">Java Spring Boot</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-aspnet-owin-mvc-samples/tree/master" title="ASP.NET (OWIN)">ASP.NET (OWIN)</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-aspnetcore-blazor-server-samples/tree/main/Quickstart/Sample" title="ASP.NET Core Blazor Server">ASP.NET Core Blazor Server</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-aspnetcore-mvc-samples/tree/master/Quickstart/Sample" title="ASP.NET Core MVC">ASP.NET Core MVC</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/laravel/tree/7.x/sample" title="Laravel">Laravel</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-php-web-app/tree/main/app" title="PHP">PHP</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-rubyonrails-sample/tree/master/sample" title="Ruby On Rails">Ruby On Rails</a></td>
      <td>Supported</td>
    </tr>
  </tbody>
</table>

### Backends and APIs

<table>
  <thead>
    <tr>
      <th><strong>Technology</strong></th>
      <th><strong>Support Level</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-express-api-samples/tree/master/01-Authorization-RS256" title="Node.js Express">Node.js Express</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-python-api-samples/tree/master" title="Python API">Python API</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-spring-security5-api-sample/tree/master" title="Spring Boot API">Spring Boot API</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-golang-api-samples/tree/master" title="Go API">Go API</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-aspnetcore-webapi-samples/tree/master" title="ASP.NET Core Web API">ASP.NET Core Web API</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-aspnet-owin-webapi-samples/tree/master" title="ASP.NET Web API (OWIN)">ASP.NET Web API (OWIN)</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/laravel/tree/7.x/sample" title="Laravel API">Laravel API</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-php-api-samples/tree/main/app" title="PHP API">PHP API</a></td>
      <td>Supported</td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0-samples/auth0-rubyonrails-api-samples/tree/master" title="Ruby On Rails API">Ruby On Rails API</a></td>
      <td>Supported</td>
    </tr>
  </tbody>
</table>

## Auth0 Marketplace

<table>
  <thead>
    <tr>
      <th><strong>Integration</strong></th>
      <th><strong>Support Level</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Integrations maintained by Auth0</td>
      <td>Supported</td>
    </tr>

    <tr>
      <td>Third-party custom integrations</td>
      <td>Partner</td>
    </tr>
  </tbody>
</table>

## Extensions

<table>
  <thead>
    <tr>
      <th><strong>Extension</strong></th>
      <th><strong>Support Level</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Auth0 extensions published to the Dashboard</td>
      <td>Sustained</td>
    </tr>

    <tr>
      <td>Custom extensions</td>
      <td>Community</td>
    </tr>
  </tbody>
</table>

Feature requests should be made in the GitHub repository of each extension. Please note there is no commitment from Auth0 to implement requests.

## Learn more

* [Product Lifecycle](/docs/troubleshoot/product-lifecycle)


# Reset Account Passwords
Source: https://auth0.com/docs/troubleshoot/customer-support/reset-account-passwords

Describes how to reset Auth0 account passwords.

If you need to change your password or you have forgotten the password to your Auth0 account, in most cases, you can set a new password from the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. Password resets cause Auth0 sessions to expire.

1. On the Auth0 account login screen, enter the email address associated with your account and click **Continue,** then choose **Forgot password?** at the next screen.
2. Confirm your email address and click **Continue** to submit. You will receive an email that provides further instructions on resetting your password.
3. If your request was successfully received, you'll see "Please check the email address \[your email] for instructions to reset your password."

There are some special password reset circumstances:

* If you've enabled <Tooltip href="/docs/glossary?term=MFA">MFA</Tooltip> and need an MFA reset for your admin account, contact [Auth0 Support](https://support.auth0.com).
* If you're using a social or enterprise account to log in to Auth0, reset your password with the appropriate <Tooltip href="/docs/glossary?term=identity+provider">identity provider</Tooltip>.
* If you are an administrator trying to reset a user's password, there are two methods:

  * Use the interactive password reset flow with Universal Login or the Authentication API where the user receives an email with a link that opens the Auth0 password reset page to enter a new password.
  * Directly set the new password either using the Management API or the Dashboard.


# Responsible Disclosure Program Security Support Tickets
Source: https://auth0.com/docs/troubleshoot/customer-support/responsible-disclosure-program-security-support-tickets

All customers, even those with free subscription plans, can report security concerns in Auth0 Responsible Disclosure Program.

All customers, even those with free subscription plans, can report security concerns. Please read [Auth0's Vulnerability Disclose Policy](https://www.okta.com/content/dam/okta---digital/en_us/legal/okta-vulnerability-disclosure-policy_v2.0.pdf) for more information before submitting a security concern.

If you would like to publish your findings, you must submit the report directly to us at [psirt@okta.com](mailto:psirt@okta.com), preferably using our [GPG encryption key](https://www.okta.com/vulnerability-reporting-policy/okta-pgp-key/).

If you would like to be rewarded, the Bugcrowd’s [standard disclosure terms](https://www.bugcrowd.com/resources/essentials/standard-disclosure-terms/) apply, and you must submit via [Bugcrowd](https://bugcrowd.com/okta) to be rewarded for your submission. For more information, visit [Auth0's bug bounty program](https://bugcrowd.com/auth0-okta).

For legal information, read [Legal Details](https://auth0.com/legal).

## Learn more

* [Premier Success Plans](/docs/troubleshoot/customer-support/support-plans)
* [Software Updates](/docs/troubleshoot/customer-support/software-updates)
* [Support Channels](/docs/troubleshoot/customer-support/support-channels)


# Self Service Support
Source: https://auth0.com/docs/troubleshoot/customer-support/self-service-support

Description of the Self-Service Support Plan for Auth0

#### Self Service Support Features

* Answer questions concerning usage issues related to Auth0 specific features, options and configurations
* Provide initial and high-level suggestions regarding the appropriate usage, features, or solution configurations for the particular type of reporting, analysis, or functionality
* Isolate, document, and find alternative solutions for reported Defects
* Work with Okta Operations, Product, Software Development, and QA staff to submit Change Requests, Enhancement Requests, and provide Fixes for Auth0 as necessary
* Address customer concerns with online or printed documentation, providing additional examples or explanation for concepts requiring clarification
* Access to online release notes for Updates
* Access to Okta’s online library of support webinars and knowledgebase
* Access to Okta’s Customer Community forums to collaborate with fellow Okta customers

**Self Service Defect Severity Levels**

Okta will assign Defects one of the four Severity Level priorities, depending upon the resulting impact caused by the Defect. Okta may re-assign a Severity Level prioritization to Customer in the trouble ticketing system, based on the descriptions below. Okta’s assignment will be consistent with the Severity Level descriptions below. Severity Level categories are as follows:

<table>
  <thead>
    <tr>
      <th>Severity Level</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>1 (urgent)</td>
      <td>Emergency Issue; Defect resulting in full or partial system outage or a condition that makes Auth0 unusable or unavailable in production for all of Customer’s Users.</td>
    </tr>

    <tr>
      <td>2 (high)</td>
      <td>Significant Business Impact; Defect resulting in a condition where major functionality is impacted or significant performance degradation is experienced; issue is persistent and affects many Users and/or major functionality.</td>
    </tr>

    <tr>
      <td>3 (normal)</td>
      <td>Minor Feature / Function Issue / General Question; Defect results in a component of Auth0 not performing as expected or documented. An inquiry by Customer representatives regarding general technical issues/questions.</td>
    </tr>

    <tr>
      <td>4 (low)</td>
      <td>Minor Problem / Enhancement Request; Information requested on Auth0 capabilities, navigation, installation, or configuration; enhancement request.</td>
    </tr>
  </tbody>
</table>

**Self Service Defect Response**

The priority of a Defect will determine the timing and nature of the response as specified in the table below:

<table>
  <thead>
    <tr>
      <th>Defect Severity Level</th>
      <th>Target Response Time (Self Service Support )</th>
      <th>Solution Definition (one or more of the following)</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>1 (urgent)</td>
      <td>3 business hours</td>
      <td>• Issue is resolved <br /> • Workaround is provided <br />• Fix is provided <br />• Fix incorporated into future release</td>
    </tr>

    <tr>
      <td>2 (high)</td>
      <td>12 business hours</td>
      <td>• Issue is resolved <br /> • Workaround is provided <br />• Fix is provided <br />• Fix incorporated into future release</td>
    </tr>

    <tr>
      <td>3 (medium)</td>
      <td>1 business day</td>
      <td>• Issue is resolved <br /> • Workaround is provided <br />• Fix incorporated into future release<br />• Answer to question is provided</td>
    </tr>

    <tr>
      <td>4 (low)</td>
      <td>2 business days</td>
      <td>• Answer to question is provided <br />• Enhancement request logged</td>
    </tr>
  </tbody>
</table>

**Support Hours**

Okta’s Self Service Support hours for Defects is 6 AM to 6 PM Customer local time, Monday to Friday for all Severity Levels.


# Service Levels
Source: https://auth0.com/docs/troubleshoot/customer-support/services-level-descriptions

Describes the Auth0 service levels and service level agreements (SLAs).

Here is a summary of the key elements of Auth0’s Service Level Agreement (SLA) for both Enterprise Public Cloud and Enterprise Private Cloud deployments of the Auth0 platform. Please contact [Auth0 Sales](https://auth0.com/get-started?place=documentation%20post\&type=link\&text=contact%20auth0%20sales) for additional information.

The average availability of certain core services of the Auth0 platform for each month will be at least 99.99%. If Auth0 fails to meet its availability service level during any given calendar month, you may request a service level credit within 5 business days of the event.

Auth0 will provide you with credit as described in the table below. If any credits are not used upon the expiration of your subscription, then we will apply the credits to any other fees or expenses you owe us. If there are no such other fees or expenses then we will refund the credit amount.

<table>
  <thead>
    <tr>
      <th><strong>Availability Level</strong></th>
      <th><strong>Service Level Credit</strong></th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>98.50% - 99.98%</td>
      <td>5% of the Monthly Subscription Fee\*</td>
    </tr>

    <tr>
      <td>97.00% - 98.49%</td>
      <td>10% of the Monthly Subscription Fee\*</td>
    </tr>

    <tr>
      <td>\< 97.00%</td>
      <td>20% of the Monthly Subscription Fee\*</td>
    </tr>
  </tbody>
</table>

\*Credits are applicable to the calendar month in which the service disruption occurred.

If you experience an event that you believe brings you below the aforementioned Availability Levels, please contact your Auth0 Technical Account Manager. If you are a Basic or Silver Success Plan customer, contact your Auth0 Sales Representative or Account Executive.

If you require a [Private instance](/docs/deploy-monitor/deploy-private-cloud) of Auth0, please contact [Auth0 Sales](https://auth0.com/get-started?place=documentation%20post\&type=link\&text=contact%20auth0%20sales) for additional information.

Visit the [Auth0 Status Page](https://status.auth0.com/) to read current and historical uptime information for the Public Cloud environment.


# Software Updates
Source: https://auth0.com/docs/troubleshoot/customer-support/software-updates

Auth0 software update process

During the subscription term, Auth0 will provide or install updates if and when they are made generally commercially available by Auth0 to its customers. There is no additional cost to you.

For pricing information on Auth0 subscription plans, read the [Pricing Page](https://auth0.com/pricing) or go to your [Tenant Settings](https://manage.auth0.com/#/tenant/billing/subscription).

## Learn more

* [Product Lifecycle](/docs/troubleshoot/product-lifecycle)
* [Customer Support](/docs/troubleshoot/customer-support)
* [Support Channels](/docs/troubleshoot/customer-support/support-channels)
* [Premier Success Plans](/docs/troubleshoot/customer-support/support-plans)


# Support Channels
Source: https://auth0.com/docs/troubleshoot/customer-support/support-channels

The different ways that Auth0 provides support

Auth0 offers the following support channels.

## Auth0 status

The [Auth0 status page](https://status.auth0.com) contains information on current production status and will be updated during an outage. After an outage, a root-cause analysis is performed and made available via the page.

Please check the status page before filing a ticket. If the status page contains a notification about an outage, our team will already be working on restoring service as quickly as possible. Once the issue is resolved, the status page will be updated to reflect that. There is a button on the page to subscribe to notifications of any changes. A root-cause analysis will be published to the status page once an investigation has been done.

## Auth0 Support site

The [official Auth0 support site](https://support.auth0.com/) has a search function that answers many common questions about the product, including questions about the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, command line interface, and APIs.

## Auth0 Community

Auth0's public [question and answer community](https://community.auth0.com/) offers support for **all** subscribers. All customers, even those on free tenants, can search through existing questions and post a new question if theirs hasn't been answered. There are no guaranteed response times for questions posted.

## Auth0 security bulletins

You can see a list of Auth0 security bulletins that address security vulnerabilities of Auth0 software. Each bulletin contains a description of the vulnerability, how to identify if you are affected and what to do to fix it. See [Auth0 Security](/docs/secure) for details.

## Learn more

* [Premier Success Plans](/docs/troubleshoot/customer-support/support-plans)


# Premier Success Plans
Source: https://auth0.com/docs/troubleshoot/customer-support/support-plans

The different levels of Auth0 support

**Premier Success Plans Priority Levels**

In the event that a Service-affecting issue is detected by Okta or reported by Customer, Okta shall, in its reasonable discretion, categorize the Priority Level pursuant to the criteria below.

<table>
  <thead>
    <tr>
      <th>Priority level</th>
      <th>Description</th>
      <th>Examples</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>1</td>
      <td>A Service failure or severe degradation. Customer is unable to access any business resources.</td>
      <td>Service is down and not accessible by Users; Service is slowed to such a degree that multiple Users cannot log in, resulting in consistent “page not found errors” or similar.</td>
    </tr>

    <tr>
      <td>2</td>
      <td>A partial Service failure or mild degradation. Customer is able to access some but not all business resources.</td>
      <td>Customer lacks write-access to the administrative feature of the Service (excluding regularly scheduled Service upgrades); Users can access the Service, but access is slow, sometimes resulting in “page not found” messages or similar, with access functioning as expected upon page refresh.</td>
    </tr>

    <tr>
      <td>3</td>
      <td>Minor Service impact. Customer is able to access almost all business resources.</td>
      <td>Non-critical individual third party applications such as “personal email” are not accessible by all Users; one User is not able to access a business application; Customer is unable to successfully integrate a new business application with the Service.</td>
    </tr>

    <tr>
      <td>4</td>
      <td>Customer is able to access all business resources. Service feature enhancement request or how-to/product-functionality questions.</td>
      <td>How-to questions and Service feature enhancement requests.</td>
    </tr>
  </tbody>
</table>

**Premier Success Plans Response Times and Support Hours**

Okta will use reasonable efforts to adhere to the following response times pursuant to the Okta Premier Success Plan indicated on the Order Form. Okta may reduce case priority to a lower Priority Level at its discretion. For clarity, Response Time refers to the period of time from when a support case has been submitted by Customer and Okta’s initial response to Customer.

If Customer selects a Priority Level 1 case priority, Customer shall remain accessible (continuous 24x7 availability) for engagement and troubleshooting with Okta support from the time the case is submitted until the issue is mitigated.

<table>
  <thead>
    <tr>
      <th />

      <th>Basic</th>
      <th>Silver</th>
      <th>Gold</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Support Hours</td>
      <td>24x5\*</td>
      <td>24x7</td>
      <td>24x7</td>
    </tr>

    <tr>
      <td>Priority Level 1 Response Time</td>
      <td>2 hours</td>
      <td>1 hour</td>
      <td>30 minutes</td>
    </tr>

    <tr>
      <td>Priority Level 2 Response Time</td>
      <td>12 hours</td>
      <td>2 hours</td>
      <td>1 hour</td>
    </tr>

    <tr>
      <td>Priority Level 3 Response Time</td>
      <td>24 hours</td>
      <td>8 hours</td>
      <td>4 hours</td>
    </tr>

    <tr>
      <td>Priority Level 4 Response Time</td>
      <td>24 hours</td>
      <td>24 hours</td>
      <td>24 hours</td>
    </tr>
  </tbody>
</table>

\*Okta shall endeavor to meet 24x5 Support Hours (12:01am Monday until 11:59pm Friday local time) for Basic, but reserves the right to reduce Support Hours at its discretion.

[Auth0 Enterprise and Premier Support](/docs/troubleshoot/customer-support/auth0-enterprise-and-premier-support) are no longer offered to new customers or customers that have transitioned to a Premier Success Plan.

## Learn more

* [Support Channels](/docs/troubleshoot/customer-support/support-channels)
* [Responsible Disclosure Program Security Support Tickets](/docs/troubleshoot/customer-support/responsible-disclosure-program-security-support-tickets)


# Update Billing Information
Source: https://auth0.com/docs/troubleshoot/customer-support/update-billing-information

Update billing information from Auth0 Dashboard

You can use the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> to update your billing information. This feature is only available for tenant administrators on any tenant-based subscriptions. For account-based subscriptions, you must be a team owner to access this functionality.

## Payment and billing

To update your billing information:

1. Navigate to [Auth0 Dashboard > Settings](https://manage.auth0.com/#/dashboard/settings).

   <Callout icon="file-lines">
     If you are using a Team, you can find this setting under **Teams > Settings > Subscriptions**.
   </Callout>

2. Under **Tenant Settings**,select **Payment & Billing**.

3. Click **Add Payment Details** to input your payment information.

4. Click **Update** to save your changes.


# Auth0 Versioning Strategy
Source: https://auth0.com/docs/troubleshoot/customer-support/versioning-strategy

Understand how Auth0 versioning works.

We believe versioning is a crucial part of our offering and work to provide a consistent versioning scheme for our products we are able to help our users manage and predict how our changes will impact usage.

## Semantic versioning

[Semantic versioning](http://semver.org) (also known as semver) is a versioning strategy whose main feature is making breaking changes discoverable. A version is composed of 3 numbers separated by dots: ... For instance, 2.12.5, 0.1.0 and 10.5.35 are valid semver numbers.

* The first number represents a **major change**: the library API has changed in a non-backwards compatible way. When the major part of a version is bumped, the public API of that library has changed. For example, code and functionality previously marked as deprecated is removed from the code base.
* The second number represents a **minor change**: the library API has new functionality added or marked as deprecated while keeping backward compatibility. The new minor version is expected to be safe for use and we encourage customers to update. However, as it is impossible to know every way customers use a component, there is always a chance that changes might have impact on the current usage of the component. Therefore, we recommend verifying and testing before performing an update.
* The third number, represents a **patch change**: A bug has been fixed and should not have any impact on the user facing API. This should be safe to update but testing is always encouraged.

## Production usage

Auth0 provides links to our [Content Delivery Network (CDN)](https://en.wikipedia.org/wiki/Content_delivery_network) where we serve some of our libraries. The way you reference a component in your code will impact whether and when you automatically pick up changes. For instance, if you link to the major release from within a script, and there is a new minor, you will get the update as soon as it is released. We encourage this practice for development environments and experimenting with Auth0. Here are examples of embedding the source files:

```html lines theme={null}
<!-- major release -->
<script src="https://cdn.auth0.com/example/1/library.js"></script>

<!-- minor release -->
<script src="https://cdn.auth0.com/example/1.0/library.js"></script>

<!-- patch release (recommended for production) -->
<script src="https://cdn.auth0.com/example/1.0.1/library.js"></script>
```

When Auth0 components are deployed to production, we encourage our users to anchor to a full version and thoroughly test using that version. Although adding new features in a backwards compatible way shouldn’t break your code, the interactions with the component outcome could be hard to predict. Even trivial bug fixes may introduce changes in the assumptions you were making about the component which may no longer be true.

Each Auth0 open source component that follows semver will have a tag matching a released version in its git repository. As some of the projects use [npm](https://npmjs.com) tooling to release versions the tags will have a `v` letter as a prefix. For instance, version 5.2.3 tag will be v5.2.3.

## Learn more

* [Product Support Matrix](/docs/troubleshoot/customer-support/product-support-matrix)


# Debugging Best Practices
Source: https://auth0.com/docs/troubleshoot/debugging-best-practices

Learn about best practices for debugging.

## Rule debugging

<Warning>
  The `consoleOut` property is a log output generated by customers within the Auth0 platform through Actions, Rules, Hooks, Extensions, and DB Scripts. 

  Auth0 recommends using the `consoleOut` property for testing and debugging purposes only. You should not log personal data or other sensitive data into the web console or the log output will include such data.
</Warning>

Out of the box, typically, you [debug a rule during runtime](/docs/customize/rules/debug-rules) via console logging by using the `console.log` facility. To learn more, read [console.log() in MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/console/log_static). There is no interactive debugging of a rule available within the Auth0 platform (though one could employ the testing automation technique described below in conjunction with some external interactive source-debugging facility).

## Add line comments

Adding sufficient line (i.e., `//`) or block (i.e., `/* */`) comments to a rule, particularly around non-obvious functionality, is invaluable to both code debugging and also code understanding, particularly as there are many occasions where the initial implementer of a rule may not be the same person responsible for maintaining it going forward.

## Actions Real-time logging

By default, console log output is unavailable for display during normal execution. However, you can [use the Actions Real-time Logs](/docs/customize//actions/actions-real-time-logs) to display all console logs in real-time for implemented extensibility in an Auth0 tenant. The real-time console log display includes `console.log` output, `console.error` output, and `console.exception` output.

## Enable and disable debug logging

In a production environment, debug logging isn’t something that’s desirable all the time; given the performance considerations associated with rules, it would not be prudent to have it continuously enabled. To learn more, read [Performance Best Practices](/docs/troubleshoot/performance-best-practices).

However, in a development or testing environment, the option to enable it on a more continuous basis is much more desirable. Further, excessive debug logging could create substantial “noise”, which could make identifying problems that much harder.

Modifying a rule to enable or disable debug logging dependent on the environment would be messy and prone to error. Instead, the environment configuration object can be leveraged to implement conditional processing in a fashion similar to the following:

```js lines expandable theme={null}
function NPClaims(user, context, callback) {
    /*
     * This rule (https://auth0.com/docs/rules) is used to derive
     * effective claims associated with the Normalized User Profile:
     *   https://auth0.com/docs/user-profile/normalized/auth0
     */
    var LOG_TAG = '[NORMALIZED_PROFILE_CLAIMS]: ';
    var DEBUG = configuration.DEBUG ? console.log : function () {};
    DEBUG(LOG_TAG, "identities=", user.identities);
    user.user_metadata = user.user_metadata || {};

    //
    user.family_name =
      user.family_name ||
      user.identities.filter(function(identity) {
        /* Filter out identities which do not have anything synonymous with
         * Family Name
         */
        return(
          identity.profileData &&
          identity.profileData.family_name);
      }).map(function(identity) {
        return identity.profileData.family_name;
      })[0];
    DEBUG(LOG_TAG, "Computed user.family_name as '", user.family_name, "'");
      .
      .

    //
    return callback(null, user, context);
  }
```

In the example above, a `DEBUG` environment configuration variable has been created, which can be set to `true` or `false` depending on the execution environment (e.g., production, testing, development). The setting of this variable is used to determine when debug logging is performed. Further, a `DEBUGLEVEL` environment `configuration` variable, say, could be created, which could be used to control the debugging log level (e.g., verbose, medium, sparse).

The above example also demonstrates declaration of a named function. For convenience, providing a function name—using some compact and unique naming convention—can assist with diagnostic analysis. Anonymous functions make it hard in debugging situations to interpret the call-stack generated as a result of any exceptional error condition and providing a unique function name addresses this. To learn more, read [Error Handling Best Practices](/docs/troubleshoot/error-handling-best-practices).

### Static analysis

The rule editor in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> provides some rudimentary syntax checking and analysis of rule semantics. However, no provision is made for more complex static code analysis, such as overwrite detection, loop detection, or vulnerability detection. To address this, consider leveraging the use of third-party tooling—such as [JSHint](https://jshint.com/about/), [SonarJS](https://github.com/SonarSource/SonarJS), or [Coverity](https://scan.coverity.com/)—in conjunction with rule testing as part of your deployment automation process. To learn more, read [Deployment Best Practices](/docs/deploy-monitor/deployment-best-practices).


# Deploy and Monitor Issues
Source: https://auth0.com/docs/troubleshoot/deploy-monitor-issues

Learn how to troubleshoot issues with deployment and monitoring of your Auth0 tenant and applications.

* [Troubleshoot Log Event Codes](/docs/troubleshoot/deploy-monitor-issues/troubleshoot-log-event-codes): Learn how to troubleshoot log issues.


# Troubleshoot Log Event Codes
Source: https://auth0.com/docs/troubleshoot/deploy-monitor-issues/troubleshoot-log-event-codes

Learn how to troubleshoot logging data, including missing, unexpected, or incorrect log event codes.

## Post-login Actions and Social connections

If you have configured a post-login Action and a Social connection (such as Facebook) on your tenant, you may encounter the following issue.

When a user signs up on a Social connection and your post-login Action fails for that authentication flow, Auth0 logs a "Failed Signup" (`fs`) event. However, Auth0 does create a user profile for this user.

Subsequently, when the user logs in on that Social connection, Auth0 logs a "Success Login" (`s`) event but not a "Success Signup" (`ss`) event.


# Error Handling Best Practices
Source: https://auth0.com/docs/troubleshoot/error-handling-best-practices

Learn about best practices for error handling.

## Send error logs to an external service

We recommend sending error event logs to an external service to provide better visibility and diagnosis of anomalous operation. To retain and analyze your log events past the log retention period offered for your subscription plan, [use Auth0 log streaming](/docs/customize/log-streams). You can use services like DataDog and AWS EventBridge. We also offer the ability to send logs to an external service in our [Log Streaming](https://marketplace.auth0.com/features/log-streaming) section in Auth0 Marketplace.

## Use error objects in rules

There are time constraints regarding how much time a rule has to execute. To learn more, read [Custom Database Action Script Execution Best Practices](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/execution). If recovery from an error condition is not possible (or probable) within this time period, then an error condition should be explicitly returned; this is as simple as completing rule execution by returning an instance of a Node `Error` object, as in:

`return callback(new Error('some description'));`

To learn more, read [Class: Error on nodejs.org](https://nodejs.org/api/errors.html#errors_class_error).

Alternatively, an instance of the Auth0-specific `UnauthorizedError` can be returned, which causes an `unauthorized` error condition with the supplied error description to be returned to the application that initiated authentication—that is, the application from which redirect to the `/authorize` endpoint was initiated. This allows an application to offer conditional retry capability and allows you to implement rules to deny access based on certain conditions:

`return callback(new UnauthorizedError('some description'), user, context);`

## Use meaningful error code descriptions

The `UnauthorizedError` object only returns the description supplied. To use specific processing for unauthorized error conditions, we recommend that you format your descriptions to include some easily accessible error code information, for example:

`'[00043] - my specific error description'`)

## Exception handling

Unexpected error conditions, such as uncaught JavaScript exceptions, can result in the premature termination of pipeline execution, which will ultimately result in an error in authentication being returned.

For situations involving asynchronous operations, you must use a `catch` handler when using `Promise` object processing. `Promise` object processing can also be effective for error handling during non-asynchronous operations. As illustrated below, a `Promise` object can be used to wrap, say, a synchronous function call, making it easier to implement cascaded error handling via use of promise chaining and the like. To learn more about the Promise object, read [Promise in MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). To learn more about promise chaining, read [Error Handling with Promises on javascript.info](https://javascript.info/promise-error-handling).

```js lines theme={null}
return new Promise(function(resolve, reject) {
    jwt.verify(
      token,
      secret,{
      clockTolerance: 5},
      function(err, decoded) {
        if (err) {
          reject(err);
        } else {
          resolve(decoded);
      }
    });
  });
```

Alternatively, you can use `try...catch` processing to handle JavaScript exceptions that occur during synchronous operation. To learn more, read [`try...catch` in MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/try...catch).Setting up this type of exception handling can often incur performance costs, so use it sparingly; rule performance should be as optimal as possible. A more pragmatic approach is to implement processing that prevents exceptions from occurring rather than handling them once they have occurred. To learn more about best practices, see [Performance Best Practices](/docs/troubleshoot/performance-best-practices).

## Avoid uninitialized objects in rules

If you use uninitialized objects, that can cause exceptions. We recommend that you include initialization as part of any declaration where the existence of an object is in question. For example:

`user.user_metadata = user.user_metadata || {}`)

In a rule, taking steps to prevent an exception from occurring in the first place is a best practice and is typically less costly in terms of performance and resource usage than implementing exception handling.


# General Usage and Operations Best Practices
Source: https://auth0.com/docs/troubleshoot/general-usage-and-operations-best-practices

Learn about best practices for general operations in Auth0.

Here are some recommended best practices for general Auth0 usage and operation.

## Capture log files

Auth0 keeps tenant logs for a limited amount of time. (To learn more, read [Logs](/docs/deploy-monitor/logs).) To get log data and store it elsewhere, you can use the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>'s [Search log events endpoint](https://auth0.com/docs/api/management/v2#!/Logs/get_logs), [stream the logs](/docs/customize/log-streams) to an external service, or [export log events using one of the available extensions](https://marketplace.auth0.com/features/log-streaming) for services such as Loggly or Splunk.

## Set up your own email provider and customize email templates

Auth0 provides a test email provider, so you can test default welcome and email verification messages during tenant configuration. To learn more, read [Email](/docs/customize/email). The test provider can only send a limited amount of emails, so you should [configure your own mail server](/docs/customize/email/smtp-email-providers/configure-custom-external-smtp-email-provider). Additionally, we recommend a unique email provider account per tenant. Sharing an email account between tenants can be a potential source of problems or outages for one tenant when making changes to the service intended for another.

Also, make sure to [configure and customize the templates](/docs/customize/email/email-templates) for emails sent from Auth0. These include email verification messages, welcome messages, password reset messages, et cetera. For custom templates, provide a "from" address, a clear subject, your custom content, and a link timeout for emails with a link (such as a password reset link).

## Avoid pinning or fingerprinting TLS certificates for Auth0 endpoints

Auth0 does not support pinning or fingerprinting TLS certificates for Auth0 API endpoints. Doing so can lead to outages and unexpected behaviors within your applications or services.

Certificates presented on Auth0 endpoints are issued for varying expiry timeframes. These certificates are renewed with different intermediate certificate authorities and root certificate authorities. Any sort of pinning or fingerprinting should be avoided since any aspect of the certificate chain can be changed at any time.

## Subscribe to updates on the Auth0 status page

[Sign up for notifications at the Auth0 status page](https://status.auth0.com/). If there are any Auth0 outages, you or your support staff will be notified.

## Store custom code in a source code repository

If you have a full continuous integration/continuous deployment pipeline, use the Auth0 Deploy CLI tool for greater flexibility. To learn more, read [Deploy CLI Tool](/docs/deploy-monitor/deploy-cli-tool).

Please note that the [auth0-deploy-cli](https://github.com/auth0/auth0-deploy-cli) tool is updated regularly to provide feature enhancements, security improvements, and bug fixes. Before you upgrade to a newer version, review the [release notes](https://github.com/auth0/auth0-deploy-cli/releases) and update your configuration files accordingly.

## Store configuration values in Dashboard

If your Actions, Rules, Hooks, custom database scripts, or Webtasks require configuration values (such as credentials or API keys), you should store them in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>. Storing configuration values in the Dashboard makes migrating configuration between tenants easier. To learn more, read [Set Up Multiple Environments](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments).

## Add Auth0 public IP addresses to AllowList

If your Actions, Rules, Hooks, custom database scripts, or Webtasks call a service in your intranet or behind another firewall, be sure to add the Auth0 public IP addresses to the AllowList. This lets requests from those IP addresses through. You can find the IP addresses for each region in your Auth0 Dashboard, where you edit rules, hooks, or custom database scripts.

## Run tenant configuration checks

The Auth0 Support Center provides a configuration checker tool. Run the configuration checker periodically during development and again before you launch.

To run the configuration check, go to [Auth0 Support Center > Tenants](https://support.auth0.com/tenants/public), select the gear icon, and choose **Run Production Check**.

## ASN Binding optimization

An Autonomous System Number (ASN) is a unique identifier assigned to an Autonomous System comprising IP networks and routing devices under the control of an Administrative Domain (AD) owned by a Service Provider. ASN binding for Dashboard users is enabled by default and is not configurable.

If you are experiencing redirect loops or are frequently being prompted to enter your password while accessing Teams or Auth0 Dashboard, see the following best practices to help mitigate potential issues:

* Connecting and disconnecting to either a corporate or commercial VPN could mean your IP and ASN are changing. Verify that when connected to the VPN, the public IP that is used to access the Internet does not change for the duration your VPN connection is on.
* If using a VPN, verify the VPN connection is stable; random disconnects and connects as a result of network stability might represent frequent changes to your Public IP and ASN.
* Some corporate networks might utilize network or firewall load-balancers to prevent internet outages associated with relying on a single Internet Service Provider. Verify that your Public IP is not frequently changing while accessing Teams or Auth0 Dashboard. Try using another network to test that you can successfully log in.


# Troubleshoot Integration and Extensibility Issues
Source: https://auth0.com/docs/troubleshoot/integration-extensibility-issues

Learn where to look for steps to troubleshoot integration and extensibility issues such as partner connections, Sign in With Apple, custom databases and domains, Deploy CLI, and extensions

* [Troubleshoot Custom Domains](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-custom-domains) - Describes troubleshooting for <Tooltip href="/docs/glossary?term=custom+domains">custom domains</Tooltip>.
* [Troubleshoot Active Directory/LDAP Connector](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-ad-ldap-connector) - Common issues and troubleshooting information for the Active Directory/LDAP Connector.
* [Troubleshoot Extensions](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-extensions) - General troubleshooting steps for extensions.
* [Troubleshoot Deploy CLI Tool](/docs/troubleshoot/integration-extensibility-issues/troubleshoot-the-deploy-cli-tool) - Describes Auth0 Deploy CLI Tool troubleshoot steps.
* [Troubleshoot Auth0-PHP Library](/docs/libraries/auth0-php/troubleshoot-auth0-php-library) - Describes troubleshooting the Auth0-PHP SDK.

## Learn more

* [Test Connections](/docs/authenticate/identity-providers/test-connections)
* [Troubleshoot Custom Databases](/docs/authenticate/database-connections/custom-db/error-handling)
* [Troubleshoot Basic Issues](/docs/troubleshoot/basic-issues)
* [Troubleshoot Authentication Issues](/docs/troubleshoot/authentication-issues)
* [Troubleshooting Tools](/docs/troubleshoot/troubleshooting-tools)


# Troubleshoot AD/LDAP Connector
Source: https://auth0.com/docs/troubleshoot/integration-extensibility-issues/troubleshoot-ad-ldap-connector

Common issues and troubleshooting information for the AD/LDAP Connector.

If you are experiencing issues with your [AD/LDAP Connector](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector), read below to learn how to troubleshoot common issues.

## Run the troubleshooting tool

You can run the troubleshooting tool in the AD/LDAP Connector Admin Console, or outside the Admin Console by executing the program manually.

To detect issues with certificates, set the `CONNECTIONS_API_V2_KEY` variable in the [AD/LDAP Connector configuration file](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-config-file-schema).

### In the Admin Console

You can run the troubleshooting tool in the Admin Console.

1. Switch to the **Troubleshooting** view to read the logs.

   <Frame>
     <img alt="Troubleshoot AD/LDAP Connector Admin Console Troubleshooting Screen" />
   </Frame>
2. Select **Run** to detect the most common problems related to the AD/LDAP Connector.

### Outside the Admin Console

You can launch the troubleshooting tool outside of the Admin Console.

#### Windows

On a Windows machine, run the provided command file to launch the troubleshooting tool.

1. Locate the AD/LDAP Connector folder (`AD LDAP Connector`).
2. Run the `troubleshoot.cmd` file.

For example: `C:\Program Files (x86)\Auth0\AD LDAP Connector\troubleshoot.cmd`.

<Frame>
  <img alt="Troubleshoot AD/LDAP Connector Troubleshooting Tool Screen" />
</Frame>

#### Linux

On a Linux machine, run the provided Node.js program to launch the troubleshooting tool.

1. Open a new terminal window.
2. Change the working directory to the AD/LDAP Connector folder (`AD LDAP Connector`).
3. Run the `node troubleshoot.js` command.

## Installation and configuration issues

After clicking **Save**, the AD/LDAP Connector Admin Console performs a series of tests to validate the provided information. The results of the tests are displayed under the **Configuration log** heading.

The Admin Console performs the following tests:

* **Test 1**: Attempts to establish a TCP connection to the LDAP server and port specified. If Test 1 fails, check basic network connectivity and firewall settings that might prevent such a connection.
* **Test 2**: Attempts to perform an LDAP bind on the LDAP server and port specified and with the username and password provided. If Test 2 fails, check the LDAP connection string, search path, username, and password.
* **Test 3**: Attempts to perform an LDAP search against the directory to check the privileges of the specified username. If Test 3 fails, check the privileges of the username in the target directory.
* **Test 4**: Attempts to establish a connection to the Auth0 server. If Test 4 fails, check network connectivity and firewall settings that might prevent such a connection.

## Common issues and solutions

Descriptions of several common issues and their solutions are listed below.

### Authentication requests take too long to process

By default, the Auth0 AD/LDAP Connector imports a user’s group memberships from Active Directory and includes them on the `user` object.

This behavior requires the AD/LDAP Connector to perform additional queries against Active Directory, which can significantly increase the duration of the authentication process.

If you do not need groups to be returned on the user profile, Auth0 recommends that you explicitly disable the `GROUPS` variable in the [AD/LDAP Connector configuration file](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-config-file-schema).

### Host CPU utilization is high

If the CPU utilization on the machine hosting the AD/LDAP Connector is consistently high (for example, sustained utilization above 60%), there are several mitigation strategies.

#### Uninstall non-critical services

Uninstall any non-critical services on the host machine that may be consuming CPU cycles.

#### Modify group import configuration

If you do not require groups to be returned on the user profile, disable group import as described in [Authentication requests take too long to process](#authentication-requests-take-too-long-to-process).

If you do require groups to be returned on the user profile, investigate the groups being returned on the Auth0 user profiles. Queries against nested and recursive groups can cause high CPU utilization. If possible, test with group import disabled to assess the impact of the group queries.

To mitigate the impact, fix any recursive or otherwise problematic group assignments in your AD/LDAP server, and/or increase the value of the `GROUPS_CACHE_SECONDS` variable in the [AD/LDAP Connector configuration file](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-config-file-schema).

#### Evaluate volume of active users

Check if the number of active users using the AD/LDAP Connector has increased since you initially deployed it. You can evaluate this by using your own [monitoring solution](/docs/customize/log-streams), or you can get an estimate from the [Auth0 active users report](/docs/troubleshoot/customer-support/manage-subscriptions/monitor-subscription-usage).

<Callout icon="file-lines">
  In Microsoft Windows Server environments, Microsoft System Center Operations Manager (SCOM) can be configured to monitor and alert on the service status of the AD/LDAP Connector. For more information, see [Monitor AD/LDAP Connector with System Center Operations Manager](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-scom).
</Callout>

If the number of active users has increased, and all steps above have already been followed, you may need to upgrade your host machine’s hardware specifications, or configure a [High Availability environment](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-high-availability).

### Clock skew

The connector requires the clock on the server to be synchronized with the Auth0 service. The maximum allowed threshold is 5 seconds.

If you have a clock skew, you'll see output like this in the troubleshooter and connector logs:

```text lines theme={null}
12:18:55 - info: * Testing clock skew...
12:18:55 - error: × Clock skew detected:
12:18:55 - error: > Local time: 2020-05-04 12:18:55
12:18:55 - error: > Auth0 time: 2020-05-04 12:19:10
```

Make sure the clock of your server is current. If the time is not correct, it will cause authentication requests to fail. This can be fixed by ensuring the system is properly configured to poll a sync server via the Network Time Protocol (NTP). In Windows environments, the NTP provider is usually the same domain controller. Make sure that your domain controller is synchronized with some external service.

To learn how to synchronize your Active Directory environment with an external time server, read [How to configure NTP server in Active Directory, Step by step on renanrodrigues.com](https://www.renanrodrigues.com/post/how-to-configure-ntp-server-in-active-directory-step-by-step).

If you are unsure if your server's clock is in sync with NTP, go to [https://nist.time.gov](https://nist.time.gov) and compare the time on that page with the time in the server where the connector is running. You shouldn't notice more than a one (1) second difference between them.

### No connection to Active Directory

The AD/LDAP Connector must be installed on a server that can reach your LDAP server. When firewalls and VPN connections are placed between the AD/LDAP Connector and the LDAP server, you may experience connectivity issues.

If you’re configuring a Windows Network with Active Directory, use the `nltest` command. For example, to test if a specific machine can reach the `fabrikam.local` domain, use `nltest /dsgetdc:fabrikam.local`.

To see to which domain the current server is connected to, use `nltest /dsgetdc:`.

If a domain does not exist or cannot be reached, `nltest` will return an error message: `Getting DC name failed: Status = 1355 0x54b ERROR_NO_SUCH_DOMAIN`.

### UNABLE\_TO\_VERIFY\_LEAF\_SIGNATURE error message (Private Cloud)

This error applies to the AD/LDAP Connector in combination with Private Cloud.

This error message occurs when the AD/LDAP Connector fails to start when it can't validate the SSL certificate configured in the Private Cloud. This can happen when the Root Certificate (or any Intermediate Certificates) are missing in the machine's Certificate Store (Windows). In order to solve this, import the certificate chain in the **Local Machine > Trusted Root** certificate store on the machine where the AD/LDAP Connector is installed.

### Connector behind a proxy

If the machine hosting the connector is behind a proxy, you can set an `HTTP_PROXY` system environment variable, or you can set the `HTTP_PROXY` variable in the [AD/LDAP Connector configuration file](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-config-file-schema). If using an authenticated proxy, the URL must be in the format `http://USERNAME:PASSWORD@SERVER_URL:PORT`.

<Callout icon="file-lines">
  If you set system environment variables, or modify the [AD/LDAP Connector configuration file](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-config-file-schema), you must restart the AD/LDAP Connector for the changes to take effect.
</Callout>

The `HTTP_PROXY` URL must be the URL of the proxy itself and cannot point to a `.pac` (auto-config) file. If your proxy is configured through a `.pac` file, download the `.pac` file and find the proxy URL there.

An incorrectly configured proxy can result in several errors, such as `Auth0 servers not reachable` and `SELF_SIGNED_CERT_IN_CHAIN` errors.

If you have configured a proxy URL and restarted the AD/LDAP Connector, but are still seeing `SELF_SIGNED_CERT_IN_CHAIN` errors, make sure that your server is trusting the root certificate of the proxy. On a Windows machine, you can check this by opening `certmgr.msc` and looking for your proxy's certificate. To learn more, read [Proxy auto config (PAC) on Wikipedia](https://en.wikipedia.org/wiki/Proxy_auto-config).

### No internet connectivity

Ensure that your server can connect to your Auth0 tenant (`https://{yourDomain}`).

To verify this, open a browser and navigate to `https://{yourDomain}/test`.

### Service account permissions

The Service account used to configure the AD/LDAP Connector must have `read` permissions on the AD/LDAP server, and must be capable of querying groups for users.

### Kerberos issues

To enable verbose logging of Kerberos requests:

1. Add `DEBUG=kerberos-server` as a system environment variable.
2. Restart the AD/LDAP Connector.
3. Log in.
4. Check the logs for more information.

If you have Kerberos enabled, but your users are being prompted for username/password, verify that the IP address setting is properly configured. For more information, see [Configure AD/LDAP Connector Authentication with Kerberos](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/configure-ad-ldap-connector-with-kerberos).

### Changes in user profile in AD are not immediately reflected in the app

The AD/LDAP Connector uses two levels of configurable caching:

1. **Auth0 server**: Caches both the user’s credentials and their profile.
2. **AD/LDAP Connector**: Caches a user’s group memberships.

The configuration of these settings determines the immediacy that changes in your directory may be reflected in a user’s profile when they log in to your application(s). In some AD/LDAP installations, user attributes synchronization may take a few minutes.

#### Caching on the Auth0 server

The Auth0 server caches the user’s last successfully authenticated profile, including a hash of their username and password. It is enabled by default, and can be disabled.

The purpose of this first-level cache is to maximize availability of authentication transactions when AD is unavailable, such as during a network outage. It is only activated if the AD/LDAP Connector or the AD/LDAP server(s) are unavailable.

#### Caching in the AD/LDAP Connector

The AD/LDAP Connector caches a user’s group memberships. This cache’s lifetime is determined by the `GROUPS_CACHE_SECONDS` variable in the [AD/LDAP Connector configuration file](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-config-file-schema), with a default value of 600 (seconds).

The purpose of this second-level cache is to minimize execution time. By default, the AD/LDAP Connector retrieves all group membership of a user recursively, which can be an expensive process in some AD/LDAP installations. This cache is deleted every time you restart the AD/LDAP Connector.

### Connector restarts after "auth0: Connection closed." message in the log

To avoid the requirement of an open inbound port in your servers, the AD/LDAP Connector creates a websocket connection to an available node in Auth0's server cluster and keeps it open to listen to incoming messages from Auth0.

Approximately once per day (though the frequency may vary under certain circumstances), each server node terminates the connection to allow internal deployment processes to occur. The AD/LDAP Connector detects the closed connection and terminates the process, allowing the service stack to restart the process, create a new connection to an available node, and resume operations.

To avoid any downtime, enable the cache:

1. Go to [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/enterprise), and select the **Active Directory/LDAP** connection type.
2. Select your AD/LDAP connection.
3. Switch to the **Applications** view, and enable the connection for the desired application(s).
4. Select **Save**.

### Receive "postUrl is required" error

You may encounter this error if you have not completed additional configuration for a [custom domain](/docs/customize/custom-domains).

In order to use AD/LDAP connections with Kerberos support, you will need to update the **Ticket** endpoint to work with the <Tooltip href="/docs/glossary?term=custom+domain">custom domain</Tooltip>:

1. Open the [AD/LDAP Connector configuration file](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-config-file-schema).
2. Set the `PROVISIONING_TICKET` configuration variable to `https://{yourDomain}/p/ad/jUG0dN0R`.
3. Restart the AD/LDAP Connector.

### Unable to verify issuer certificate locally

If you receive the `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` error after configuring an AD/LDAP Connector, the Certificate Authority could be missing from your machine.

* If your tenant is in the public cloud environment, verify that you have the [ISRG Root X1 certificate](https://letsencrypt.org/certificates/#root-certificates) in your Trusted Store on the machine with the installed AD/LDAP Connector.
* If you are on the converged platform environment, add the [ISRG Root X2 certificate](https://letsencrypt.org/certificates/#root-certificates) to the Trusted Store on the machine with the installed AD/LDAP Connector.

If you are configuring a [High Availability environment](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-high-availability) and are encountering this error on an additional machine, verify that the Trusted Root Certificate Authorities on the additional machine matches the Trusted Root Certificate Authorities on the initial machine.

## Contact Auth0 Support

If you are unable to resolve any of these issues on your own, contact [Auth0 Support](/docs/troubleshoot/customer-support/open-and-manage-support-tickets).

To help the Support team troubleshoot your issue, include the following items in your support ticket:

1. Description of the issue.
2. An [export of your AD/LDAP configuration files](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/import-export-ad-ldap-connector-configs).
3. A copy of the service log file(s):

   * Windows: `C:\Program Files (x86)\Auth0\AD LDAP Connector\logs.log`
   * Linux: `/var/log/auth0-adldap.log`
4. The version number of your AD/LDAP Connector.

   <Frame>
     <img alt="Troubleshoot AD/LDAP Connector Console Screen" />
   </Frame>

## Learn more

* [AD/LDAP Connector System Requirements](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-requirements)
* [Import and Export AD/LDAP Connector Configurations](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/import-export-ad-ldap-connector-configs)
* [Set Up AD/LDAP Connector Test Environment](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-test-environment)
* [Update AD/LDAP Connectors](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/update-ad-ldap-connectors)
* [AD/LDAP Connector Configuration File Schema](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-config-file-schema)
* [Monitor AD/LDAP Connector with System Center Operations Manager](/docs/authenticate/identity-providers/enterprise-identity-providers/active-directory-ldap/ad-ldap-connector/ad-ldap-connector-scom)


# Troubleshoot Custom Domains
Source: https://auth0.com/docs/troubleshoot/integration-extensibility-issues/troubleshoot-custom-domains

Learn how to troubleshoot issues with custom domains.

## Auth0-managed custom domains

When you configure [custom domains with Auth0-managed certificates](/docs/customize/custom-domains/auth0-managed-certificates), there are two custom domain attributes that you can review to query their provision status:

* `verification`
* `certificate`

You can review the custom domain provision status using [Auth0 CLI](https://auth0.github.io/auth0-cli/) or the Management API.

### Auth0 CLI

Use the following command to list the existing domains and their status:

```bash theme={null}
auth0 domains list
```

To learn more, read [Auth0 CLI](https://auth0.github.io/auth0-cli/auth0_domains_list.html) documentation.

### Auth0 Management API

Send a `GET` request to the `/api/v2/custom-domains` endpoint:

```bash theme={null}
curl -L -g 'https://{tenantDomain}/api/v2/custom-domains' \
-H 'Accept: application/json'
```

The response includes a list of your custom domains, including their `status`, `verification.status` and if verified, their `certificate.status`.

```json files theme={null}
{
  "custom_domain_id": "cd_9JPAp8JxtP0jvmbc",
  "domain": "yellow.acmetest.org",
  "primary": true,
  "status": "ready",
  "type": "auth0_managed_certs",
  "verification": {
    "methods": [...],
    "status": "verified",
    "last_verified_at": "2025-06-10T12:49:05Z"
  },
  "tls_policy": "recommended",
  "certificate": {
    "certificate_authority": "letsencrypt",
    "status": "provisioned",
    "renews_before": "2025-09-08T11:52:12Z"
  }
}
```

### Verification process

When you first configure an Auth0-managed custom domain, Auth0 attempts to verify the provided custom domain DNS record. The initial custom domain `status` is set to `pending_verification` and its `verification.status` is set to `pending`.

### Certification process

Once the DNS record is successfully verified, the custom domain `verification.status` is set to `verified` and its `certificate.status` is set to `provisioning`.

When the certificate is successfully created and deployed, the `certificate.status` is set to `provisioned` and the `certificate.renews_before` attribute indicates the date by which Auth0 will automatically renew the certificate.

### Troubleshoot

If the verification process fails, the custom domain `status` is set to `failed`. You can review the `verification.error_msg` attribute to determine how to proceed.

The `verification.error_msg` attribute can be set to `DNS verification record issue`, `Domain conflicts with network configuration` or `CAA record issue`.

* `DNS verification record issue`: Auth0 could not verify your `CNAME` or `TXT` record. This can happen if the record does not exist, is incorrect, or has not propagated yet. Auth0 will attempt to verify the DNS record for up to seven days before failing.

<Callout icon="file-lines">
  This DNS record must remain in place permanently. Auth0 needs it to automatically renew the certificate in the future.
</Callout>

* `Domain conflicts with network configuration`: This typically means that you are using Cloudflare as the DNS provider and Zone Hold is enabled. The Zone Hold prevents Auth0 from verifying your custom hostname.

  To address this error message:

  1. Remove the Zone Hold from your DNS zone in Cloudflare.
  2. Select **Verify** in the **Auth0 Dashboard > Branding > Custom Domains** to restart the process.
  3. Once verification is successful, you can re-enable Cloudflare Zone Hold.

* `CAA record issue`: Auth0 cannot get the certificate for your custom domain.
  This typically is due to your domain's DNS Certification Authority Authorization (CAA) records restricting which Certificate Authorities can issue certificates for your domain.

  To address this error message:
  The easiest solution is to remove your CAA records for the exact custom domain you are trying to verify. This will let Auth0 order and provision the certificate without restrictions.

  You can determine your current CAA records using the `dig` command.

  ```bash theme={null}
    dig {your-custom-domain.com} +short CAA
  ```

  Replace `your-custom-domain.com` with your actual custom domain.

## Custom domain is still pending verification

It can take up to 48 hours for the DNS to be propagated.

* If you continue to see this error in the Dashboard, ensure that the CNAME record is properly configured in your domain management service. You can confirm the configuration of your CNAME record using:

  * A tool like [Mxtoolbox](https://mxtoolbox.com/DNSLookup.aspx) or [Google](https://dns.google.com)
  * The `dig` command in your terminal
* Ensure that the domain name is not already associated with an A record.
* Ensure that no errors were made when typing or copying the CNAME record's domain name or value.

If you have ensured the above and the custom domain is still pending verification, wait 4 hours before reverifying your domain. To avoid any interruptions to your service, do not recreate the custom domain when reverifying.

## Cloudflare CNAME flattening

<Callout icon="file-lines">
  Auth0 recommends turning off CNAME flattening unless it's strictly necessary, according to the Cloudflare documentation, [Understand and configure CNAME flattening](https://support.cloudflare.com/hc/en-us/articles/200169056-Understand-and-configure-CNAME-Flattening). CNAME flattening for Auth0 managed certificates is an unsupported configuration and as such may cause the custom domain to break without notice if CNAME flattening is enabled.
</Callout>

CNAME flattening affects the Auth0 verification and certificate renewal processes due to the way it handles DNS records. Enabling CNAME flattening in Cloudflare after setting up a custom domain does **not** prevent certificate renewal.

If you need to enable CNAME flattening for all subdomains managed by Cloudflare and also configure a specific subdomain to be an Auth0 custom domain, consider delegating the subdomain for Auth0 to another DNS provider. To learn more, read [Delegating Subdomains Outside of Cloudflare](https://support.cloudflare.com/hc/en-us/articles/360021357131-Delegating-Subdomains-Outside-of-Cloudflare) in the Cloudflare documentation. This will enable you to use CNAME flattening for all subdomains except the one used for Auth0.

## "You should not be hitting this endpoint"

If you see this error when configuring a custom domain, you must perform additional configurations, which varies depending on your setup. To learn more, see [Configure Features to Use Custom Domains](/docs/customize/custom-domains/configure-features-to-use-custom-domains).

## "Service not found"

If your application issues an `/authorize` request with `audience=https://login.acmetest.org/userinfo`, the server will return a `Service not found: https://login.acmetest.org/userinfo` error. This is because even if you set a custom domain the API identifier for the `/userinfo` endpoint remains `https://{yourOriginalAuth0Domain}/userinfo`.

Similarly, using your custom domain in calls to the [Auth0 Management API](https://auth0.com/docs/api/management/v2) will error for the same reason.

To fix this your app should instead use `audience=https://{yourOriginalAuth0Domain}/userinfo`. You can also remove this `audience=[...]/userinfo` parameter altogether if your application is flagged as **OIDC-Conformant** in the **OAuth2** tab of the application's **Advanced Settings**.

## Learn more

* [Configure Features to Use Custom Domains](/docs/customize/custom-domains/configure-features-to-use-custom-domains)
* [Configure Custom Domains with Auth0-Managed Certificates](/docs/customize/custom-domains/auth0-managed-certificates)
* [Configure Custom Domains with Self-Managed Certificates](/docs/customize/custom-domains/self-managed-certificates)
* [TLS (SSL) Versions and Ciphers](/docs/customize/custom-domains/self-managed-certificates/tls-ssl)


# Troubleshoot Extensions
Source: https://auth0.com/docs/troubleshoot/integration-extensibility-issues/troubleshoot-extensions

Learn general troubleshooting steps for extensions.

If you have issues with an extension, we recommend you begin the troubleshooting process following one of the two alternatives:

1. Upgrade the extension, if an upgrade is possible.
2. Reinstall the extension.

To learn more about different extensions Auth0 offers, read [Auth0 Extension](/docs/customize/extensions).

## Upgrade the Extension

We recommend always having Extensions upgraded to the latest version available.

1. Go to [Auth0 Dashboard > Extensions](https://manage.auth0.com/#/extensions).
2. On the **Installed Extensions** tab, check if there is an upgrade available for the specific extension.
3. Click the **Update to...** option.

## Reinstall the Extension

An alternative when running into issues with an extension is to reinstall it:

1. Go to [Auth0 Dashboard > Extensions](https://manage.auth0.com/#/extensions).
2. On the **Installed Extensions** tab, delete the extension.
3. Log out of the Auth0 Dashboard.
4. Log back in to the Auth0 Dashboard.
5. Reinstall and reconfigure the extension.

## Contact Support

If you are still experiencing issues with your extension, and you need to [contact Auth0 support](https://support.auth0.com), please be sure to **include errors logs and/or** [**Actions Real-time Logs**](/docs/customize/actions/actions-real-time-logs) **with your support ticket**. Errors and logs can help Auth0 support troubleshoot your issue faster.


# Troubleshoot Deploy CLI Tool
Source: https://auth0.com/docs/troubleshoot/integration-extensibility-issues/troubleshoot-the-deploy-cli-tool

Learn how to troubleshoot the Auth0 Deploy Command Line Interface (CLI) tool.

## Warning log entries after a Google Apps connection is recreated

**Symptoms**: you see warnings in the logs with messages like `Unable to get extended attributes: unauthorized` or `Unable to get groups: unauthorized`.

When you first create a Google Apps connection and enable one of the checkboxes to get extended information about the user, you'll need to go through a consent flow by having a Google Apps administrator follow the link under the "Setup instructions" button next to the connection. After completing this flow, some token information is stored on the connection's `options` object that is used to retrieve extended information when a user logs in.

If you have a Google Apps connection, you'll need to ensure that the consent flow is completed before exporting the connection information using the CLI. By doing this, the necessary tokens will be included in the exported script and the administrator won't have to go through the consent flow every time the connection is recreated.

<Warning>
  Tokens stored in the connection's `options` object are sensitive and should be handled in the same way other secure information is handled.
</Warning>

## Learn more


# Performance Best Practices
Source: https://auth0.com/docs/troubleshoot/performance-best-practices

Learn about best practices for performance.

Rules execute as part of a pipeline where artifacts for authenticity are generated, as described in [Custom Database Anatomy Best Practices](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/anatomy). As such, an enabled rule will execute for every login operation (interactive or otherwise), every silent authentication, and every time a user-credentials-related <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> is generated for an API call. This means that even in small scale deployments, performance can be a concern, which will only be exacerbated as the scale of deployment increases.

## Avoid unnecessary execution

Prefer to implement execution based on conditional logic. For example, to run a rule for only specific applications, check on a specific clientID or for specific `clientMetadata`—especially when checking against a single `clientMetadata` value, common across multiple applications. Using `clientMetadata` can also make adding new clients (as well as reading rule code) easier, especially if you have a large number of applications defined, by reducing the code changes or configuration values needed between environments.

Client metadata for an application can be set manually via the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> by going to [Application Settings > Advanced Settings > Application Metadata](https://manage.auth0.com/#/applications/) or programmatically via the use of the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>'s [Update a client endpoint](https://auth0.com/docs/api/management/v2#!/Clients/patch_clients_by_id).

## Exit early

For optimal performance, write rules that complete as soon as possible. For example, if a rule has three checks to decide if it should run, use the first check to eliminate the majority of cases, followed by the check to eliminate the next largest set of cases, and so on and so forth. At the end of each check, remember to execute the callback function, ideally combined with a (JavaScript) `return` in order to exit the (rule) function.

## Minimize API requests

Calls to APIs, especially calls to third-party APIs, can slow down login response time and can cause rule timeout failures due to call latency, ultimately leading to authentication error situations. We recommend keeping API requests to a minimum wherever possible within a rule and avoiding excessive calls to paid services. We also recommend you avoid potential security exposure by limiting what is sent to any API, third-party or otherwise.

The `global` object can be used to cache information from API calls, which can subsequently be used across all rules that execute in the pipeline. Prefer to use this to store information instead of repeatedly calling an API. Additionally, the `global` object can also be used to cache other information between executing rules.

### Limit calls to paid services

If you have rules that call paid services, such as sending SMS messages via Twilio, make sure that you only use those services when necessary. This not only provides performance enhancement, but also helps to avoid extra charges. To help reduce calls to paid services:

* Disallow public sign-ups to reduce the number of users who can sign up and trigger calls to paid services
* Ensure that a rule only gets triggered for an authorized subset of users or other appropriate conditions. For example, you may want to add logic that checks if a user has a particular email domain, role/group, or subscription level before triggering the call to the paid service.

### Limit calls to the Management API

Try to avoid calls to the Auth0 Management API. The Auth0 Management API is rate limited, which will still be a consideration even when using the `auth0` object (so be sure to use it sparingly). To learn more, read [Management API Endpoint Rate Limits](/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy/management-api-endpoint-rate-limits).

In addition, Management API functions take varying degrees of time to perform, so will incur varying degrees of latency; calling the Management API's [List or Search users endpoint](https://auth0.com/docs/api/management/v2#!/Users/get_users), for example, should be kept to a minimum and performed only where absolutely necessary—even when executed via the `auth0` object.

### Avoid calls to the Management API for connection-related details

We have expanded connection-related properties available to the rules `context` object, so you can obtain connection info from the `context` object instead of needing to call the Auth0 Management API. To learn more, read [Context Object Properties in Rules](/docs/customize/rules/context-object).

To see this in action, if you are using the **Check if user email domain matches configured domain** rule template, [check out the latest version on Github](https://github.com/auth0/rules/blob/master/src/rules/check-domains-against-connection-aliases.js) or navigate to [Auth0 Dashboard > Auth Pipeline > Rules](https://manage.auth0.com/#/rules/new), and select **Create**. Note: the recent changes will not alter functionality but will improve the performance of rules that had once relied on calls to the Management API.

Removing calls to the Management API (as well as the extra call required to get the appropriate Access Token) will make your rule code perform better and be more reliable.

## Use explicit timeouts when making API calls

When calling APIs or accessing external services, consider specifying explicit timeout(s). The specific timeout value you choose will typically vary based on your use case, but in general, choosing one that is as low as possible—while bearing in mind the performance characteristics of the external service—is advised.

Whether you choose to use explicit timeouts or implicit timeout processing, always be sure to cater to error and/or exception conditions that may occur as a result of any timeout period expiration. To learn more, read [Error Handling Best Practices](/docs/troubleshoot/error-handling-best-practices).

## Reduce calls to Auth0

When you exceed your rate limits, you'll need to reduce the number of calls you make to Auth0. The specifics depend on your use case, but here are some recommendations:

* Cache `/.well-known/*` responses: This information does not change frequently, so you can usually cache it to reduce the number of times you need to call Auth0.
* Consider requesting an `id_token` instead of calling `/userinfo` to get information about the user.
* Reduce bulk calls, such as bulk delete or bulk unlock.

## Learn more

* [Error Handling Best Practices](/docs/troubleshoot/error-handling-best-practices)
* [Debugging Best Practices](/docs/troubleshoot/debugging-best-practices)


# Product Lifecycle
Source: https://auth0.com/docs/troubleshoot/product-lifecycle

Learn about the Auth0 product lifecycle, including product release stages, deprecations, end-of-life, the migration process, and active migrations.

When building Auth0 products, we resolve to:

* Deliver value to customers early and often, iterating based on their feedback
* Seek a deep understanding of our customers and consider them in every decision
* Relentlessly acquire and analyze data, so we can make better choices
* Visualize and design for current, idealized, and future versions of our whole product when adding features

This document provides guidance on what constitutes backward-compatible (non-breaking) and backward-incompatible (breaking) changes in the Auth0 platform. The distinction between these changes helps developers anticipate potential impacts on their applications when consuming Auth0 services.

This document outlines common changes and their compatibility to help set expectations for integrations. The changes described are not exhaustive or comprehensive; for more details on breaking changes, read the topics below.

<table>
  <thead>
    <tr>
      <th><strong>Read...</strong></th>
      <th><strong>To learn...</strong>                                </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/troubleshoot/product-lifecycle/product-release-stages">Product Release Stages</a></td>
      <td>How Auth0 stages, releases, and retires product functionality.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/product-lifecycle/migration-process">Migration Process</a></td>
      <td>How Auth0's deprecation and migration process works.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/product-lifecycle/deprecations-and-migrations">Deprecations and Migrations</a></td>
      <td>About current deprecations and how to migrate to new behaviors or features.</td>
    </tr>

    <tr>
      <td><a href="/docs/troubleshoot/product-lifecycle/past-migrations">Past Migrations</a></td>
      <td>Past migrations previously enabled for customers.</td>
    </tr>
  </tbody>
</table>

#### Auth0 APIs

Auth0 exposes and maintains APIs like the Authentication and Management APIs, each of which define a contract between Auth0 and its customers based on the documented API specifications and its associated artifacts. Auth0 follows recognized standards from bodies such as IETF and OIDC; where standards do not exist, proprietary APIs are developed while adhering to best practices.

Changes to these APIs, whether backward-compatible or backward-incompatible, are necessary from time to time to improve their functionality, security, or performance.

#### Backward-compatible, non-breaking changes

A backward-compatible change does not disrupt the interoperation between the Auth0 platform and customer applications and does not require customers to take immediate action or participate in the migration process.

Examples of non-breaking changes include:

* **Opaque Strings**: The format and size of opaque strings (e.g., tokens, IDs) may change. Clients shouldn’t assume a fixed size or format. The maximum size for opaque strings will not exceed 4096 characters.
* **<Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> Size**: Per the <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> specification (RFC6749), the size of JWT credentials is undefined. Auth0 may issue variable-sized JWTs, and clients should not assume a specific size.
* **Authorization Code Size**: Clients should expect that authorization codes, as per the OAuth specification, may vary in size.
* **Unrecognized Response Parameters**: Clients must ignore unrecognized response parameters, allowing Auth0 to add new features without affecting current functionality.
* **New Resources, Fields, Headers, or Scopes**: The addition of new API resources, fields, headers, or scopes will not impact existing clients that do not recognize or use these elements.

For a more detailed explanation of backward-compatible changes, refer to Auth0’s API change guidelines in the [product lifecycle stages](/docs/troubleshoot/product-lifecycle/product-release-stages).

#### Backward-incompatible, breaking changes

A backward-incompatible change can cause failures when it alters the interoperation between the Auth0 platform and customer applications. When such a change is necessary, it follows the [deprecation and migration process](/docs/troubleshoot/product-lifecycle/deprecations-and-migrations) to provide notice and support for customers to adjust their tenant implementations.

Examples of breaking changes include:

* **API Resource Removal**: If an API resource is removed or renamed, clients relying on that resource will experience a breaking change.
* **URI Structure Changes**: Modifying the structure of an existing URI may disrupt clients that depend on it.
* **Method, Parameter, or Field Removal**: If a method, parameter, or field is removed or renamed, this will result in a breaking change for clients using these elements.
* **Default Value Changes**: Changes to the default value of a field may impact existing integrations and constitute a breaking change.
* **Error Response and Status Code Changes**: Modifications to error response formats, error codes, or status codes can break existing client behavior.
* **JWT Format**: Changes to the JWT format of tokens are breaking changes
* **JSON Format**: Changing the type of a JSON value is a breaking change.

Any breaking change triggers the deprecation process, in which customers are notified and provided at least six months to migrate to the new behavior. For more details, refer to the [deprecation and end-of-life process](/docs/troubleshoot/product-lifecycle/deprecations-and-migrations).

#### Auth0’s commitment

Auth0 minimizes disruptions caused by backward-incompatible changes using the following process:

* **Deprecation Announcement**: Auth0 announces the deprecation to provide customers notice of an upcoming change.
* **Migration Window**: Customers are given a minimum six-month window to migrate to the updated functionality, with guidance provided in our [migration process](/docs/troubleshoot/product-lifecycle/migration-process).
* **End of Life**: When the migration window closes, the deprecated feature is moved to the end-of-life stage and is no longer available.

#### Undocumented APIs

Undocumented Auth0 APIs are considered private and subject to change without notice. These APIs are not covered by the deprecation process and customers should avoid relying on them for production systems.


# Deprecations and Migrations
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/deprecations-and-migrations

Lists all deprecations with active migrations that may impact your tenant.

We are actively migrating customers to new behaviors for all deprecations listed below. Please review these carefully to ensure you've taken any necessary steps to avoid service disruption. You can also search tenant logs for any errors caused by using deprecated features. To learn more, read [Search Logs for Deprecation Errors](/docs/troubleshoot/basic-issues/search-logs-for-deprecation-errors).

If you have any questions, visit the [Community](https://community.auth0.com/) or [create a ticket in our Support Center](https://support.auth0.com). To learn more, you can also read [Migration Process](/docs/troubleshoot/product-lifecycle/migration-process).

## Legacy management of connection's enabled clients

**Deprecated**: January 13, 2026

**End of life**: July 13, 2026

The `enabled_clients` field, within the Management API connection object, is deprecated in the following scenarios:

* [Retrieving multiple connections](https://auth0.com/docs/api/management/v2/connections/get-connections) using (GET - `/api/v2/connections`).
* [Retrieving a connection](https://auth0.com/docs/api/management/v2/connections/get-connections-by-id) using (GET - `/api/v2/connections/{id}`).
* [Updating a connection](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id) using (PATCH - `/api/v2/connections/{id}`).

As an alternative to the deprecated functionality, two new Management API endpoints are available:

* [Get enabled clients for a connection](https://auth0.com/docs/api/management/v2/connections/get-connection-clients).
* [Update enabled clients for a connection](https://auth0.com/docs/api/management/v2/connections/patch-clients).

To prepare for this change and ensure your integrations continue to function smoothly, review [Migrate Enabled Client Management to Dedicated Connection Endpoints](/docs/troubleshoot/product-lifecycle/deprecations-and-migrations/migrate-dedicated-connection-endpoints) to verify your affected status and migrate to the new endpoints.

## Weak TLS 1.2 Cipher Suites

**Deprecated**: December 10, 2025

**End of life**: June 10, 2026

After the end-of-life date, we will require the use of modern ciphers when connecting to Auth0 service endpoints and web applications. We will remove support for TLS 1.2 cipher suites that no longer provide sufficient security to protect network communications. More specifically, the change to supported cipher suites applies to:

* Public and private cloud tenants' default domains; for example, `[tenant_name].eu.auth0.com.`
* Public and private cloud tenants' custom domains.
* Service-related web applications, such as the Dashboard (`manage.auth0.com`) or the Marketplace (`marketplace.auth0.com`).
* The Auth0 CD.

The list of discontinued cipher suites is available below. The list contains the unique hex code that identifies each cipher alongside its [IANA](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4) name; for the corresponding OpenSSL names, follow the links to `ciphersuite.info`.

TLS 1.2 ciphers scheduled for removal:

* 0xC0, 0x09 - [TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_CBC\_SHA](https://ciphersuite.info/cs/TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA/)
* 0xC0, 0x0A - [TLS\_ECDHE\_ECDSA\_WITH\_AES\_256\_CBC\_SHA](https://ciphersuite.info/cs/TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA/)
* 0xC0, 0x23 - [TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_CBC\_SHA256](https://ciphersuite.info/cs/TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256/)
* 0xC0, 0x24 - [TLS\_ECDHE\_ECDSA\_WITH\_AES\_256\_CBC\_SHA384](https://ciphersuite.info/cs/TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384/)
* 0xC0, 0x13 - [TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA](https://ciphersuite.info/cs/TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA/)
* 0xC0, 0x14 - [TLS\_ECDHE\_RSA\_WITH\_AES\_256\_CBC\_SHA](https://ciphersuite.info/cs/TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA/)
* 0xC0, 0x27 - [TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA256](https://ciphersuite.info/cs/TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256/)
* 0xC0, 0x28 - [TLS\_ECDHE\_RSA\_WITH\_AES\_256\_CBC\_SHA384](https://ciphersuite.info/cs/TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384/)
* 0x00, 0x9C - [TLS\_RSA\_WITH\_AES\_128\_GCM\_SHA256](https://ciphersuite.info/cs/TLS_RSA_WITH_AES_128_GCM_SHA256/)
* 0x00, 0x2F - [TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA](https://ciphersuite.info/cs/TLS_RSA_WITH_AES_128_CBC_SHA/)
* 0x00, 0x9D - [TLS\_RSA\_WITH\_AES\_256\_GCM\_SHA384](https://ciphersuite.info/cs/TLS_RSA_WITH_AES_256_GCM_SHA384/)
* 0x00, 0x35 - [TLS\_RSA\_WITH\_AES\_256\_CBC\_SHA](https://ciphersuite.info/cs/TLS_RSA_WITH_AES_256_CBC_SHA/)
* 0x00, 0x3C - [TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA256](https://ciphersuite.info/cs/TLS_RSA_WITH_AES_128_CBC_SHA256/)
* 0x00, 0x3D - [TLS\_RSA\_WITH\_AES\_256\_CBC\_SHA256](https://ciphersuite.info/cs/TLS_RSA_WITH_AES_256_CBC_SHA256/)

## Prompt for Organization Name Without SSO

**Deprecated**: October 31, 2025

**End of life**: May 1, 2026

Login flows initiated in the context of client applications associated with business users (`organization_usage=require`) and configured to prompt for the organization at the start of the login flow (`organization_require_behavior=pre_login_prompt`) will consider an existing authenticated session.

Previously, the service prompted the user for the organization name and the user would subsequently be required to complete a login. For example, a user with a password-based account needed to re-enter their credentials even if an authenticated session was valid for the selected organization.

## Unconfirmed Login with Non-Verifiable Callback URI Redirects

**Deprecated**: October 28th, 2025

**End of life**: April 28th, 2026

Auth0 recommends the transition to HTTPS-based callbacks using [Android App Links](https://developer.android.com/training/app-links#android-app-link) and [Apple Universal Links](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content) whenever possible for all native applications using the [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce) to enhance security and mitigate risks of application impersonation and phishing attacks.

Additionally, Auth0 is implementing a new login confirmation prompt for authentication requests that utilize custom URI schemes or loopback URIs as the callback. This prompt will appear in situations where a response was previously returned without requiring user interaction..

Review [Migrate to Non-Verifiable Callback URI End-User Confirmation](/docs/troubleshoot/product-lifecycle/deprecations-and-migrations/migrate-to-non-verifiable-callback-uri-end-user-confirmation) to learn more details.

## Audience Validation for Private Key JWT Authentication

**Deprecated**: October 6, 2025

**End of life**: April 8, 2025

When validating [JWT assertions used for client application authentication](/docs/get-started/authentication-and-authorization-flow/authenticate-with-private-key-jwt), **Auth0 will impose stricter requirements and accept only a tenant's issuer identifier as a single JSON string value in the `aud` (audience) claim**.

The possibility of providing an `aud` claim with either one of the approaches listed below is deprecated, and the service will stop supporting them after the end-of-life date:

* A JSON array of strings, provided that one of the entries contains a valid issuer identifier or endpoint URL for the respective tenant and endpoint the client authenticates against.
* A single JSON string representing a valid endpoint URL for the respective tenant and endpoint the client authenticates against.

Ahead of the end-of-life date, OIDC enterprise connections configured to use Private Key JWT in authenticated requests to the upstream identity provider will receive the capability to allow the use of the applicable issuer identifier represented as a JSON string in the "aud" claim included in JWT assertions.

## Extended Attributes in Azure Active Directory (v1) Identity API Connections

**Deprecated**: June 18, 2025

**End of life**: September 1, 2025

Due to the [Azure AD Graph deprecation](https://learn.microsoft.com/en-us/graph/migrate-azure-ad-graph-overview) and scheduled [retirement](https://techcommunity.microsoft.com/blog/microsoft-entra-blog/what%E2%80%99s-new-in-microsoft-entra-%E2%80%93-june-2025/4352579#community-4352579-toc-hId--1605859169), Auth0 will no longer support enabling extended attributes-related options in Microsoft Azure AD (`strategy=waad`) connections configured to use the Azure Active Directory (v1) Identity API.

If you received a notification via email, one or more of your tenants may have a Microsoft Azure AD connection targeting the **Azure Active Directory (v1)** identity API and configured to obtain extended attributes and could potentially be impacted.

You must review applicable tenants. For connections dependent on the deprecated functionality, you must either:

* Update connections to target **Microsoft Identity Platform (v2)** so that Microsoft Graph endpoints are used instead of the deprecated Azure AD Graph when retrieving extended attributes information.

* Turn off all the extended attributes options.

Although the second option above would allow you to maintain connections targeting the **Azure Active Directory (v1)** identity API if the extended information is unnecessary, the general recommendation is to target **Microsoft Identity Platform (v2)**. To learn more, read [Connect Your App to Microsoft Azure Active Director](/docs/authenticate/identity-providers/enterprise-identity-providers/azure-active-directory/v2). For more information on the deprecation, contact [Auth0 Support](https://support.auth0.com/).

## Real-Time Webtask Logs Extension

**Deprecated**: June 18, 2025

**End of life**: September 16, 2025

The Real-time Webtask Logs extension is deprecated and has a planned end-of-life (EOL) after September 16, 2025. 

As a replacement, the [Actions Real-time Logs](/docs/customize/actions/actions-real-time-logs) feature is directly available within the Auth0 Dashboard. The extension will cease to be available for new installations, but tenants with the extension already installed will maintain access until the planned EOL.

## Remove Access to Specific Event Request Properties in Actions

**Deprecated**: June 18, 2025

**End of life**: September 16, 2025

Auth0 will restrict access to additional property names within the `event.request.query` and `event.request.body` objects when executing Actions for the [`post-login`](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) and [`credentials-exchange`](/docs/customize/actions/explore-triggers/machine-to-machine-trigger) triggers. Only tenants identified as using Actions to reference request properties planned for restriction will maintain access until **September 16, 2025**.

The service will restrict the following property names in the request-related objects:

* `auth_session`
* `authn_response`
* `client_secret`
* `client_assertion`
* `refresh_token`

## Multiple Actions for Custom Phone and Email Provider Triggers

**Deprecated:** June 16, 2025

**End of life:** December 16, 2025

Auth0 is introducing a maximum limit of one Action for Actions associated with the following triggers:

* `custom-phone-provider`
* `custom-email-provider`

This limitation applies to the Management API [Create an Action](https://auth0.com/docs/api/management/v2/actions/post-action) endpoint (`POST` - `/api/v2/actions/actions`). Once the newly introduced limit becomes effective for a given tenant, attempts to create multiple actions for these triggers will fail.

## Uncustomizable Brute-force Protection Unblock Email Flow

**Deprecated:** June 9, 2025

**End of life:** December 9, 2025

An updated version of the email-based unblock flow for [Brute-force Protection](/docs/secure/attack-protection/brute-force-protection) supports customization and localization through Universal Login and improves the experience for situations where email security scanners process the unblock email is available.

## Field `fromSandbox` in Authentication API Error Responses

**Deprecated:** June 11, 2025

**End of life:** December 11, 2025

Authentication API error responses will no longer return the `fromSandbox` field for flows requiring custom database script invocation. For example, an API error response in the context of an end-user signup flow for a custom database connection will no longer return this field.

## Allow Omitting Password on SMTP Email Provider Host-Related Changes

**Deprecated:** May 13, 2025

**End of life:** November 13, 2025

When updating a SMTP email provider’s host, port, or username using a `PATCH` request to the [`/api/v2/emails/provider endpoint`](https://auth0.com/docs/api/management/v2/emails/patch-provider), you may need to specify a password for the `credentials.smtp_pass` field.

A SMTP email provider’s credentials object supports the following fields:

* `credentials.smtp_pass`: SMTP email provider’s password
* `credentials.smtp_host`: SMTP email provider’s host
* `credentials.smtp_port`: SMTP email provider’s port
* `credentials.smtp_user`: SMTP email provider’s username

Auth0 requires an explicit value for the `credentials.smtp_pass` field in the following cases:

* When you’re updating a SMTP email provider’s `credentials.smtp_host`, `credentials.smtp_port`, or `credentials.smtp_user` fields with a value that is different from the existing value or updating just a subset of those three fields.

Auth0 does not require an explicit value for the `credentials.smtp_pass` field in the following cases:

* When you’re updating a SMTP email provider and the request body includes the same values as the existing values for the `credentials.smtp_host`, `credentials.smtp_port`, and `credentials.smtp_user` fields.

## Unrestricted Offset Pagination in Connections Management API

**Deprecated**: April 29, 2025

**End of life**: October 27, 2025

The offset-based pagination available for the Management API [get all connections](/docs/api/management/v2/connections/get-connections) endpoint will no longer support retrieving a paginated result beyond the first 1000 connections.

For example, the service will return an error response if `page=30&per_page=50` or `page=15&per_page=100` is used. In both situations, multiplying the number of records requested per page by the requested page index plus one (to account for the page index being zero-based) results in the request surpassing the initial 1000 connections.

Per the above, with a page size of 50, the last page index that you can request without errors is 19 (`page=19&per_page=50`), and with the maximum page size of 100, you can request up to page index number 9 (`page=9&per_page=100`).

Conditions that surpass the limit trigger the error even if the tenant associated with the request has fewer than 1000 connections.

## Node.js 12 and 16 Extensibility Runtimes

**Deprecated**: February 10, 2025

**End of life**: August 15, 2025

Node.js 12 and 16 extensibility runtimes will gradually become unavailable across Auth0 tenants. Once removed, all extensibility integrations, such as Actions, Rules, Hooks, Custom Database Connections, and Custom Social Connections, will be forced to run on Node 22.

For technical resources relevant to migrating to Node 22, read [Migrate from Node 12 and 16 to Node 18](/docs/troubleshoot/product-lifecycle/past-migrations/migrate-nodejs-16-to-nodejs-18) and [Migrate from Node 18 to Node 22](/docs/troubleshoot/product-lifecycle/deprecations-and-migrations/migrate-nodejs-22).

## New Management API Scopes Required for Connection Options

**Deprecated**: October 24, 2024

**End of life**: July 8, 2025

Requests to the following Management API endpoints will require the `read:connections_options` scope to view the `options` field:

* [Connections > Get all connections](https://auth0.com/docs/api/management/v2/connections/get-connections)
* [Connections > Get a connection](https://auth0.com/docs/api/management/v2/connections/get-connections-by-id)

Requests to the following Management API endpoints will require the `update:connections_options` to modify the `options` field:

* [Connections > Update a connection](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id)

## Rules and Hooks Deprecations

**Deprecated**: May 16, 2023

**Read-only transition**: November 18, 2024

**End-of-life:** November 18th, 2026

After November 18th, 2026, Rules and Hooks will stop being executed and removed.

On November 18, 2024, active Rules and Hooks will continue to execute, but will degrade to read-only mode. Auth0 has delayed the removal of Rules and Hooks functionality to a future date.

Read-only Rules and Hooks can be turned on and off and their respective configuration values or secrets can be modified, but their source code cannot be edited via the Dashboard or Management API, including CI/CD tooling like Terraform and Auth0 Deploy CLI.

If you will be unable to migrate to Actions ahead of the read-only transition, ensure that any automated CI/CD flow you have configured to deploy tenant configuration changes does not attempt to perform unsupported management operations on Rules and Hooks.

For more information, read [Migrate from Rules to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions) and [Migrate from Hooks to Actions](/docs/customize/actions/migrate/migrate-from-hooks-to-actions).

## Opt-in to WCAG 2.2 AA Compliant UI for Universal Login

**Deprecated:** August 23, 2024

**End of Life:** July 31st, 2025

Auth0 will remove the ability to use the legacy, non-compliant UI for <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>. The new WCAG compliant version ensures that end users, including those who rely on assistive technology, can access and engage with a customer’s product or service. Read our [Universal Login Accessibility documentation](/docs/authenticate/login/auth0-universal-login) for more information.

## Learn more

* [Migration Process](/docs/troubleshoot/product-lifecycle/migration-process)
* [Past Migrations](/docs/troubleshoot/product-lifecycle/past-migrations)
* [Deprecation Errors](/docs/troubleshoot/basic-issues/check-deprecation-errors)
* [Check for Deprecation Errors](/docs/troubleshoot/basic-issues/search-logs-for-deprecation-errors)


# Migrate to Management API Connection Options Scopes
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/deprecations-and-migrations/migrate-connection-options-scope

Learn how to update your Auth0 integrations to manage connections with options-specific scopes.

​Auth0 is introducing two new Management API [scopes](/docs/get-started/apis/scopes) for connection options: `read:connections_options` and `update:connections_options`.

We are additionally deprecating the ability to access or update the `options` field without the appropriate scopes, resulting in the following breaking changes:

* Responses from the [Get All Connections](/docs/api/management/v2/connections/get-connections) and [Get Connection by Id](/docs/api/management/v2/connections/get-connections-by-id) endpoints do not include the `options` field unless the caller has the `read:connections_options` scope.
* Requests to the [Update a Connection](/docs/api/management/v2/connections/patch-connections-by-id) endpoint fail if the request body contains the options field and the caller does not have the `update:connections_options` scope. Successful responses do not include the `options` field unless the caller has the `read:connections_options` scope.

To continue using the `options` field, you must update your application grants to include the new scopes. Follow the steps below to identify whether your tenant and integrations are affected, migrate to the options-specific scopes, and finally opt out of the deprecated behavior.

## Identify affected tenants

Use Auth0 Dashboard to confirm if a tenant is allowed to access connection options without the new scopes and requires migration.

1. Navigate to [Auth0 Dashboard > Tenant Settings > Advanced](https://manage.auth0.com/dashboard/#/tenant/advanced).
2. Scroll down to the **Migrations** section.
3. Look for the **Allow Connections Management** without Options Scopes toggle:
   A. If the toggle is **on**, your tenant can still access connection options without the new scopes, and you must migrate before the deadline.
   B. If the toggle is absent or **off**, no further action is required.

## Identify affected integrations

Review the `depnote` tenant logs to determine which applications and integrations use the impacted endpoints. The following sample query demonstrates how you can query for the deprecation notice tenant logs specific to this deprecation:

```
type:depnote AND description:Allow\ Connections\ Management\ without\ Options\ Scopes*
```

To learn more, read [Log Search Query Syntax](docs/deploy-monitor/logs/log-search-query-syntax).

Once you have the query results, inspect the `client_id` field to identify each application that may be potentially affected. Due to the nature of the changes, the existence of a deprecation notice for a specific client application does not necessarily mean that the application is impacted.

​If the `client_id` field has an empty value, this means that the request to the impacted endpoint originated from an extension. Several Auth0 extensions can cause deprecation notice tenant logs that are false positives. Once you complete the extension-specific steps listed in the Update extensions section, you can ignore deprecation notices with an empty client identifier.

## Update application grants

For applications retrieving or updating the `options` field using the impacted endpoints, update their Management API grants to include the necessary scopes.

1. Navigate to [Auth0 Dashboard > Applications > APIs](https://manage.auth0.com/dashboard/#/apis).
2. Select the **Auth0 Management API**, then the **Machine to Machine Applications** tab.
3. Next to the application requiring an update, select the down-arrow icon to expand the section.
4. In the Permissions section, search for `“connections_options”`. Enable one or both of the new scopes. Then, choose **Update** to save your changes.
   <Frame>
     <img alt="Update Management API permissions" />
   </Frame>

## Update extensions

Update to the latest version of the [Delegated Administration Dashboard](/docs/customize/extensions/delegated-administration-extension/install-delegated-admin-extension) extension. This update is necessary because the extension requires access to the connection options field to function properly. If you use this extension, ensure it is updated to maintain its functionality.

## Opt-Out (Finalize Migration)

Once your integrations no longer depend on the deprecated behavior, we recommend configuring your tenant to explicitly opt out of allowing connections management without options scopes. This lets you choose exactly when your tenant adopts the new behavior, providing more control over your migration process.

1. Navigate to [Auth0 Dashboard > Tenant Settings > Advanced](https://manage.auth0.com/dashboard/#/tenant/advanced).
2. Under the Migrations section, toggle off the **Allow Connections Management without Options Scopes** option.

If you face any issues, you can revert the same toggle to temporarily restore the previous behavior while you address the problem.


# Migrate Enabled Client Management to Dedicated Connection Endpoints
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/deprecations-and-migrations/migrate-dedicated-connection-endpoints

Learn how to update your Auth0 connection configuration from using the `enabled_clients` field to dedicated connection endpoints.

Auth0 is deprecating the `enabled_clients` field from Management API’s [Get All Connections](/docs/api/management/v2/connections/get-connections), [Get Connections](/docs/api/management/v2/connections/get-connections-by-id), and [Update a Connection](/docs/api/management/v2/connections/patch-connections-by-id). Auth0 customers can retrieve enabled clients on a connection by using the [Get enabled clients for a connection](https://auth0.com/docs/api/management/v2/connections/get-connection-clients) endpoint. To update clients already established on a connection, use the [Update enabled clients for a connection](https://auth0.com/docs/api/management/v2/connections/patch-clients).

To prepare for this change and ensure your integrations continue to function smoothly, review the steps below to verify your affected status and migrate to the new endpoints.

To learn more about migration timelines, review the entry on [Deprecations and Migrations](/docs/troubleshoot/product-lifecycle/deprecations-and-migrations).

## Verify affected tenants

<Warning>
  Private Cloud tenant administrators can follow these instructions if their [Private Cloud deployment](/docs/deploy-monitor/deploy-private-cloud) is version `v202608` or later. To learn more about the Private Cloud deployments versions, read [How to Check the Auth0 Private Cloud's Release Number and Deployment Date](https://support.auth0.com/center/s/article/How-to-check-the-Auth0-private-cloud-s-release-number-and-deployment-date).
</Warning>

You can use the Auth0 Dashboard to confirm whether a tenant is allowed access to the deprecated functionality and requires migration.

1. Navigate to [Auth0 Dashboard > Tenant Settings > Advanced](https://manage.auth0.com/dashboard/#/tenant/advanced).
2. Under **Migrations**, review the **Legacy Management of Connection's Enabled Clients toggle**.
   * Toggle is **on**: Your tenant allows access to the deprecated field when retrieving and updating connections, and you must migrate before the deadline.
   * Toggle is **off**: No further action is required.

## Identify affected integrations

<Callout icon="file-lines">
  * Public Cloud tenants started to receive these deprecation notices in the first half of February 2026.
  * Private Cloud tenants started to receive these deprecation notices when their Private Cloud deployments reached the `v202608` version.
</Callout>

To determine which applications and integrations use the deprecated endpoints, review the tenant [logs](/docs/deploy-monitor/logs#logs) for deprecation notices. To learn more, read [Check for Deprecation Errors](/docs/troubleshoot/basic-issues/search-logs-for-deprecation-errors).

Use the following query to search for notices specific to this deprecation:

```bash lines theme={null}
type:depnote AND description:Legacy\ Management\ of\ Connection's\ Enabled\ Clients*
```

Review the query result for the `client_id` field to identify the potentially affected applications.

Some Auth0 platform services and extensions can cause deprecation notices in tenant logs:

* If the `client_id` field is empty, the notice originated from an extension.
* If the value does not match any of the tenant’s client applications, the notice originated from a platform service, and it can be ignored.

In addition, the presence of a deprecation notice for a specific client application does not necessarily indicate that the application is affected. For example, if one of your applications retrieves `GET` connection information, including the deprecated `enabled_clients` field, but does not process the field returned in the response, the scheduled deprecation of the field has no impact.

## Review extensions usage

The following extensions can trigger deprecation notices in tenant logs:

* [User Import/Export](/docs/customize/extensions/user-import-export-extension#user-import-export-extension): This extension does not use the deprecated endpoints. These are false positive deprecation notices because the extension retrieves connection information.
* [Custom Social Connections](https://github.com/auth0/custom-social-connections): This extension uses the deprecated endpoints and will experience issues and trigger deprecation notices.

These extensions are superseded by Auth0 Dashboard functionality that addresses their use cases and no longer receive updates.

* Use the [Bulk User Import / Export](/docs/manage-users/user-migration/bulk-user-import-export) Dashboard feature to replace the User Import/Export extension.
* Use the [Social Identity Providers](/docs/authenticate/identity-providers/social-identity-providers#auth0-dashboard) Dashboard feature to replace the Custom Social Connections extension.

## Update your integrations

For applications and integrations using the impacted connection endpoints to retrieve (`GET`) or update (`PATCH`) the `enabled_clients` field, you must modify them to use the dedicated client management endpoints:

* **To Read:** [Get enabled clients for a connection](https://auth0.com/docs/api/management/v2/connections/get-connection-clients).
* **To Write:** [Update enabled clients for a connection](https://auth0.com/docs/api/management/v2/connections/patch-clients).

## Update SDKs and Tools

The following SDKs and tools versions support the new endpoints:

* [node-auth0](https://github.com/auth0/node-auth0): `4.25.0+`
* [go-auth0](https://github.com/auth0/go-auth0/): `1.21.0+`
* [auth0-java](https://github.com/auth0/auth0-java): `2.21.0+`
* [auth0-python](https://github.com/auth0/auth0-python): `5.1.0+`
* [auth0.net](https://github.com/auth0/auth0.net): `7.38.0+`
* [Auth0 Deploy CLI](https://auth0.com/docs/deploy-monitor/deploy-cli-tool): `8.27.0+`
* [Auth0 Terraform Provider](https://auth0.com/docs/deploy-monitor/auth0-terraform-provider): `1.29.0+`

The Auth0 Deploy CLI / Auth0 Terraform Provider do not require changes to how connections and respective clients are represented in their data model. You must use the latest available version to guarantee the tool uses the dedicated endpoints.

The Ruby and PHP Management API SDKs are pending updates.

## Opt-Out (Finalize Migration)

Once you ensure that integrations no longer depend on the deprecated behavior, you should configure the tenant to explicitly opt out.

* **Why Opt-Out Early?** This allows you to control the exact timeline at which a given tenant switches to the new behavior. In the event of any unexpected situation, you can quickly revert the toggle to restore the original behavior.
* **How to Opt-Out:** Navigate to **[Auth0 Dashboard > Tenant Settings > Advanced](https://manage.auth0.com/dashboard/#/tenant/advanced).**  Under Migrations, toggle off the **Legacy Management of Connection's Enabled Clients** option.


# Migrate from Node 18 to Node 22
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/deprecations-and-migrations/migrate-nodejs-22

Describes Auth0 Actions items affected by the Node.js 18

As of January 15, 2025, Node 22 extensibility runtime is generally available (GA) across our suite of extensibility offerings. This includes Actions, Rules, Hooks, Database Scripts, and Custom Social Connections. We strongly encourage you to update to Node 22 as soon as possible to adhere to best code security practices.

<Warning>
  Module-level code in your Actions are now invoked once per instance of your Action, and may be re-used as necessary across many executions.
</Warning>

### General considerations

* For available modules in the new runtime, you can reference [Can I require: Auth0 Extensibility](https://auth0-extensions.github.io/canirequire/).
* The `use npm` directive is no longer available in Node 22.
* Filesystem write access has been disabled.

### Marketplace integrations

#### Social Connections Integrations

Use the [Management API](https://auth0.com/docs/api/management/v2) to identify a complete list of social connections impacted by a Node runtime version change. In particular, all potentially impacted social connections, either explicitly created as a custom social connection or initially added through the Marketplace, have the `strategy` attribute with a value of either `oauth1` or `oauth2`.

You can then paginate through all the existing custom social connections in a given tenant using the [GET all connections](https://auth0.com/docs/api/management/v2#!/Connections/get_connections) endpoint. For example, the following query options returns the names and identifiers of up to 100 custom social connections:

```http wrap lines theme={null}
/api/v2/connections?strategy=oauth1&strategy=oauth2&include_totals=true&fields=name&per_page=100
```

<Note>
  The <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> does not allow updating the scripts for custom social connections added through the Marketplace. If a script change is required to be compatible with Node 22, you must use the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>.
</Note>

## Migration tasks

### Create new custom Actions

To create a new custom Action with Node 22 through the Auth0 Dashboard:

1. Navigate to [Auth0 Dashboard > Actions > Library](https://manage.auth0.com/#/dashboard/actions/library).
2. Select **Create Action > Build from scratch**.
3. In the **Runtime\*** field, select **Node 22 (Recommended)**.
4. Write your custom Actions in Node 22, test, and deploy when ready.

### Upgrade existing custom Actions

You can individually upgrade existing custom Actions built on Node 12, 16, or 18 to Node 22 and [revert to the previous version](/docs/customize/actions/manage-versions#revert-actions) using the older runtime. Upgrade Actions to Node 22 by creating and deploying a new version of the existing implementation with any required changes and set to use Node 22 as the runtime.

### Choose Node 22 for other extensibility products

The runtime used for the remaining (non-Actions) extensibility offerings is defined globally at the tenant's advanced settings level. Changing this setting impacts the following functionality at the same time:

* Rules
* Hooks
* Custom database scripts
* Custom social connection scripts

To change the tenant extensibility runtime setting in the Auth0 Dashboard:

1. Navigate to **Dashboard > Settings > Advanced**.
2. Scroll to the **Extensibility** section.
3. For **Runtime**, select **Node 22**.
4. For **Legacy Extensibility**, select the Runtime version if applicable.

Given that this is a global setting that impacts multiple extensibility features simultaneously, we recommend that you perform this step in your development tenant first, complete testing of all applicable extensibility features, and proceed to your production tenant only when you see no issues in development.

Specifically for Custom DB scripts you can [follow the steps as explained on this page](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/environment) to individually verify a script against a specific runtime version before proceeding to change the global runtime version.


# Migrate to Non-Verifiable Callback URI End-User Confirmation
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/deprecations-and-migrations/migrate-to-non-verifiable-callback-uri-end-user-confirmation

Learn how you can enhance security and mitigate risks of application impersonation with HTTPS-based callbacks.

Auth0 recommends all native applications using the [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce) transition to HTTPS-based callbacks using [Android App Links](https://developer.android.com/training/app-links) and [Apple Universal Links](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content). This enhances security and mitigates risk of application impersonation and phishing attacks.

To understand how this prevents attacks, review the [Measures Against Application Impersonation](/docs/secure/security-guidance/measures-against-app-impersonation#prompt-customization).

Tenants created before October 15, 2025 maintain the previous behavior as the default until April 28, 2026. After the October cutoff date, newly created tenants may default to displaying the new login confirmation prompt with some exceptions due to each environment's deployment schedule.

Tenants that explicitly opt out will bypass this prompt indefinitely. This remains true even after April 28, 2026, when the service adopts the confirmation prompt as the default behavior and removes the "Unconfirmed Login with Non-Verifiable Callback URI Redirects" migration toggle.

## How are you affected?

For client applications that already specify or plan to specify a custom URI scheme or loopback URI callback, end-users may be required to explicitly confirm the login by interacting with the new login confirmation prompt. Your end-users may perceive this change as a declining user experience.

Additionally, authentication requests including `prompt=none` will be rejected when applications use non-verifiable callback URIs and are configured to use the new login confirmation prompt.

## Migration tasks

**Auth0 strongly recommends transitioning to HTTPS-based callbacks** using Android App Links and Apple Universal Links whenever possible for all native applications using the Authorization Code Flow.

Furthermore, in tenants where the default behavior changes after April 28, 2026, you should explicitly select the behavior you require for authentication requests using custom URI schemes or loopback URI callbacks ahead of the system default change.

### Review whether your applications are using Non-Verifiable Callback URIs

In tenants for which the Unconfirmed Login with Non-Verifiable Callback URI Redirects migration toggle is available and in an enabled state, authentication requests specifying a custom URI scheme or loopback URI **will generate a deprecation notice tenant log** unless you have explicitly set the following option at the application or tenant level:

`skip_non_verifiable_callback_uri_confirmation_prompt`

These tenant logs contain the client identifier of the application performing the request. You can monitor these tenant logs through the Auth0 Dashboard using the following query:

```bash theme={null}
type:depnotetype:depnote AND description:Unconfirmed\ Login\ with\ Non-Verifiable\ Callback\ URI\ Redirects*
```

### Opt in to new login confirmation prompt

To opt-in to the new login confirmation prompt ahead of time and enhance security for authentication flows using custom URI schemes or loopback URIs, complete the following steps through your Auth0 Dashboard:

1. Navigate to [**Auth0 Dashboard > Tenant Settings > Advanced**](https://manage.auth0.com/#/tenant/advanced).
2. In the **Migrations** section, turn off the **Unconfirmed Login with Non-Verifiable Callback URI Redirects** toggle.

<Frame>
  <img alt="Auth0 Dashboard > Tenant Settings > Advanced > toggle off" />
</Frame>

### Opt out of new login confirmation prompt

If, after evaluating the security considerations, you decide against using the new login confirmation prompt, you can configure specific applications or the whole tenant to opt out of the new behavior. You can do so through your Auth0 Dashboard.

The application-level setting takes precedence over the tenant-level setting. Ensure you configure application-specific settings before changing the tenant-level setting to avoid unintended behavior changes. For example, you may want to skip the Non-Verifiable Callback URI End-User Confirmation for some specific applications while, by default, showing it for other applications, or vice versa.

To opt out for specific applications:

1. Navigate to [Auth0 Dashboard > Applications > Settings > Advanced Settings > OAuth](https://manage.auth0.com/applications/settings).
2. Locate and disable the **Non-Verifiable Callback URI End-User Confirmation** toggle and select **Save**. You may need to select the **Override the tenant setting** option to permanently allow managing this configuration.

<Frame>
  <img alt="Auth0 Dashboard > Applications > Settings > Advanced" />
</Frame>

To opt out for the whole tenant:

1. Navigate to [Auth0 Dashboard > Tenant Settings > Advanced](https://manage.auth0.com/tenant/advanced).
2. Locate and disable the **Non-Verifiable Callback URI End-User Confirmation** toggle within the **Login and Logout** section and select **Save**. You may need to select **Turn on** to allow permanently managing this configuration.

<Frame>
  <img alt="Auth0 Dashboard > Tenant Settings > Advanced" />
</Frame>

You can also configure the required tenant behavior via Auth0 Management API. In particular, you can perform the configuration at two levels:

* **Tenant-Level Configuration**: You can manage the confirmation prompt behavior by setting the `skip_non_verifiable_callback_uri_confirmation_prompt` property via the [Update Tenant Settings](https://auth0.com/docs/api/management/v2#!/Tenants/patch_settings) endpoint.​
* **Application-Level Configuration**: To override the tenant-level setting for specific applications, set the same `skip_non_verifiable_callback_uri_confirmation_prompt` property via the [Update Client](https://auth0.com/docs/api/management/v2#!/Clients/patch_clients_by_id) endpoint.

For additional information and guidance on configuring your applications, read [Measures Against Application Impersonation](/docs/secure/security-guidance/measures-against-app-impersonation).


# Migration Process
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/migration-process

Describes the migration process at Auth0, including End of Life announcements, migration windows, and migration guides.

To keep our platform stable and secure, we must occasionally modify or remove features or behaviors. These changes will sometimes result in a breaking change.

When we must introduce a breaking change, we first deprecate the affected feature or behavior and announce the deprecation to our customers. When a new Deprecation is announced, customers should engage in a migration to move away from the deprecated feature or behavior.

## End of life announcement

When we announce a Deprecation, we typically include the date that the feature or behavior will be moved into the End of Life <Tooltip href="/docs/glossary?term=product+release+stage">product release stage</Tooltip> and removed from the platform. In some cases, we will immediately deprecate a feature to prevent further adoption and will determine the end of life date at a later time. End of life dates can vary between plan types.

## Migration window

When we make an end of life announcement, we will also open a migration window to allow customers to prepare for the end of life date.

Whenever possible, we provide at least a six-month migration window between the end of life announcement and the end of life date. In case of emergency (for example, critical vulnerabilities that require remediation or changes required by applicable law or third-party certification standards), we may accelerate this time frame. In such cases, we will provide as much prior notice as is reasonable under the circumstances.

## Migration guides

Auth0 deprecations usually involve replacing deprecated behavior with substantially comparable functionality (although at times, we may elect to discontinue support for some functionality entirely).

To help you migrate to the new functionality and determine the impact on your tenants, we will publish a migration guide, which will detail any necessary modifications to your application's code, inform you of any other required actions, and instruct you about how you opt in to the new behavior prior to the End of Life date.

Once the end of life date is reached, the new behavior will automatically be enabled for tenants that did not opt in during the migration window.

## Learn more

* [Deprecations and Migrations](/docs/troubleshoot/product-lifecycle/deprecations-and-migrations)
* [Past Migrations](/docs/troubleshoot/product-lifecycle/past-migrations)
* [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages)


# Past Migrations
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations

List of Auth0 updates that have already been enabled for all customers.

These are migrations that have already been enabled for all customers. If you have any questions, create a ticket in our [Support Center](https://support.auth0.com/center/s/).

## Protected Properties in Non-Custom Social Connections

**Deprecated**: July 30, 2024

**End of life**: January 31, 2025

Management API endpoints for connections (`GET`, `POST`, and `PATCH`) will no longer allow retrieving or setting values for the following protected properties in the context of the `options` object for non-custom social connections:

* `authorizationURL`
* `tokenURL`
* `userInfoUrl`
* `baseUrl`
* `userAuthorizationURL`
* `grant_type`
* `authorizationURL`
* `tokenURL`
* `userInfoUrl`
* `baseUrl`
* `userAuthorizationURL`
* `grant_type`

Non-custom social connections refer to any social connection whose implementation logic is controlled entirely within the Auth0 service itself. This category excludes any connections explicitly created as custom social connectors or those available as Marketplace integrations that rely on custom social connection functionality.

## Unwarranted Session Removal After Management API User Updates

**Deprecated**: February 11, 2025

**End of life**: August 19, 2025

The <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> [Update a user](https://auth0.com/docs/api/management/v2/users/patch-users-by-id) endpoint (`PATCH /api/v2/users/{id}`) will no longer invalidate user sessions for database connection users when:

* The `email` or `email_verified` attributes are set to an unchanged value.
* The `email_verified` attribute is set to a `true` value.

## Mandatory Use of SNI for HTTPS requests

**Deprecated**: October 29, 2024

**End of life**: April 29, 2025

The Auth0 service will mandate using [Server Name Indication](https://en.wikipedia.org/wiki/Server_Name_Indication) (SNI) for all HTTPS requests. SNI is an extension to the TLS protocol that allows the client to indicate the hostname to which it intends to connect at the start of the handshake process.

Since their creation, the vast majority of our private cloud environments and some of our public cloud environments have enforced the SNI requirement. For example, the CA-1, JP-1, and UK-1 public cloud environments always required SNI.

With this change, the SNI requirement will apply to the remaining environments. For more detailed information on environment-specific timelines, read the [End-of-Life Rollout for Mandatory Use of SNI for HTTPS Requests](https://support.auth0.com/center/s/article/End-of-Life-Rollout-for-Mandatory-Use-of-SNI-for-HTTPS-Requests) article.

## Always Use HTTPS for Communication with Auth0

**Deprecated**: September 4, 2024

**End of life**: October 4, 2024

Starting October 4, 2024, Auth0 will no longer automatically redirect API requests using unencrypted HTTP to secure HTTPS and will respond with an error. To avoid any disruption in service, update any HTTP URLs you use or publish to use HTTPS instead.

## Management API Transition: Updating Roles Assignment to Require Create Scope

**Deprecated**: March 7, 2024

**End of life**: September 10, 2024

Management API scopes for the User-Roles endpoint (`POST /api/v2/users/{id}/roles`) will require the `create:role_members` scope. This better represents the scope's intended permissions.

Previously, roles could be assigned to users with `read:roles` scope.

## Update Applications that use Cross-Origin Authentication

**Deprecated**: April 25, 2024

**End of life**: October 10, 2024

New applications created in Auth0 will have cross-origin authentication disabled by default. Calls to some Management API endpoints ([Get Clients](https://auth0.com/docs/api/management/v2/clients/get-clients), [Get Client by ID](https://auth0.com/docs/api/management/v2/clients/get-clients-by-id)) will need to be modified to use `cross_origin_authentication`.

## Remove Subscription Tickets access for Tenant Admins

**Deprecated**: June 5, 2024

**End of life**: August 5, 2024

Access to view [Subscription Tickets](/docs/troubleshoot/customer-support/open-and-manage-support-tickets) within the Auth0 Support Center is changing on August 5, 2024. To retain access to view and manage all support tickets created by all users across a tenant, the new Elevated Support Access role is required.

## Password Reset and Email Verification Links in Tenant Logs Deprecation

**Deprecated**: December 7, 2023

**End of life**: February 5, 2024

Password reset and email verification links will no longer be logged to tenant logs. These links can be retrieved from the password reset or email verification <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> request response.

## Reducing Maximum Expiration Time for Login Transactions

**Deprecated**: September 5, 2023 (Public Cloud), November 21, 2023 (Private Cloud)

**End of life**: February 21, 2024

With this change, we will enforce a maximum lifetime of 1 hour for redirection-based login flows. Login flows that take longer than 1 hour to complete will expire in both Universal and Classic Login. After expiration, subsequent actions from the end user’s browser (e.g. input email/password, redirect back to Actions/Rules, etc.) will result in either:

* A redirect to the associated application’s default login route to reinitiate the flow as a new login transaction, or
* An error page if the default login route is not configured.

## Unregistered Scopes in Refresh Tokens Deprecation

**Deprecated**: July 12, 2023

**End of life**: January 17, 2024

We are improving scope evaluation during <Tooltip href="/docs/glossary?term=refresh+token">refresh token</Tooltip> exchange to ensure that unregistered scopes cannot be requested. Custom scope values not registered against the `aud` or `audience` value (for an API registered in your tenant) are considered unregistered scopes.

With this change, the API scope evaluation will include any custom scopes requested during user authentication or injected through extensibility, such as [Rules](/docs/customize/rules). This evaluation will validate that all scopes are registered, returning an error if any are not registered.

## auth0-cordova, angular-auth0, and express-oauth2-bearer Repo Deprecations

**Deprecated**: April 27, 2023

**End of life**: June 30, 2023 (express-oauth2-bearer), October 27, 2023 (angular-auth0 and auth0-cordova)

We have deprecated the following repos:

* [express-oauth2-bearer](https://github.com/auth0/express-oauth2-bearer) | [migration guide](https://github.com/auth0/express-oauth2-bearer/blob/master/MIGRATION_GUIDE.md)
* [angular-auth0](https://github.com/auth0/angular-auth0) | [migration guide](https://github.com/auth0/angular-auth0/blob/master/MIGRATION_GUIDE.md)
* [auth0-cordova](https://github.com/auth0/auth0-cordova) | [migration guide](https://github.com/auth0/auth0-cordova/blob/master/MIGRATION_GUIDE.md)

These libraries will no longer be supported. Please remove these libraries from any active projects before these dates.

If you have any questions or concerns, please reach out to us on GitHub.

## Actions Migration from Node.js 16 to Node.js 18

**Target migration**: Sept 11, 2023

As part of our mission to support every future version of LTS Node.js through Actions, and to be in line with the Node JS developer community, we are releasing Node 18 while Node 16 is still in Active LTS. We urge all customers to transition today to Node 18 and make the most of its LTS. Remember, while Node 16 LTS remains available until September, their use may involve certain risks following the conclusion of LTS and we recommend you to update to Node 18.

Node.js 18 is now generally available (GA) across our entire suite of extensibility offerings. This includes Actions, Rules, Hooks, Database Scripts, and Custom Social Connections. We strongly encourage everyone to update to Node 18 by Sept 11, 2023, to adhere to best code security practices.

## Support for edge.js in Extensibility Features

**Deprecated:** December 21, 2022

**End of life:** June 21, 2023

After June 21, 2023, Auth0 will no longer support running .NET and C# from Node.js in Extensibility features. Auth0 previously supported a subset of the C# language to write extensibility code for Rules, Hooks, and Custom Database Scripts via a Node.js module called edge.js.

Deprecating support for running .NET and C# from Node.js in Extensibility is critical to maintaining a performant and secure platform for running untrusted code. This change will allow us to continue improving our next-generation Extensibility offerings.
To learn more, read [Migrate from edge.js extensibility features](/docs/troubleshoot/product-lifecycle/past-migrations/migrate-from-edge-js-extensibility-features).

## Support for oracledb in Extensibility Features

**Deprecated:** December 21, 2022

**End of life:** June 21, 2023

Auth0 will no longer support the auth0-claims-provider add-on for Sharepoint 2010/2013 after July 31, 2023.

After June 21, 2023, Auth0 will no longer support connecting to Oracle Databases from Node.js in Extensibility features. Auth0 previously supported connecting to Oracle Databases from extensibility code for Rules, Hooks, and Custom Database Scripts via a Node.js module called [oracledb](https://www.npmjs.com/package/oracledb).

Deprecating support for connecting to Oracle Databases from Node.js in Extensibility is critical to maintaining a performant and secure platform for running untrusted code. This change will allow us to continue improving our next-generation Extensibility offerings.

To learn more, read [Migrate from oracledb extensibility features](/docs/troubleshoot/product-lifecycle/past-migrations/migrate-from-oracledb-extensibility-features).

## Auth0 Claims Provider for SharePoint 2010 / 2013

**Deprecated:** January 31, 2023

**End of life:** July 31, 2023

Auth0 will no longer support the auth0-claims-provider add-on for Sharepoint 2010/2013 after July 31, 2023. Without this add-on, you won’t be able to use the “Sharepoint People Picker” with Auth0 connections to assign permissions to Sharepoint 2010/2013 users.

You must remove any integrations with the auth0-claims-provider add-on before July 31, 2023. After that date, any remaining integrations with the auth0-claims-provider add-on will cease to function properly and may impact users of your applications.

## Checkpoint Pagination on Get Role Users Endpoint

**Deprecated:** November 9, 2022

**End of life:** May 9, 2023

To improve performance, the Get Role Users Management API endpoint will only return greater than 1,000 total results if the checkpoint pagination method is used. This pagination method is optimized to support large quantities of results. The offset pagination method will be capped at 1,000 results.

For implementation details for the two pagination methods, read the [Management API documentation for the Get Role Users endpoint](https://auth0.com/docs/api/management/v2/roles/get-role-user).

## Legacy Custom Claims

**Deprecated:** July 28, 2022 (Public Cloud), August 31, 2022 (Private Cloud)

**End of life:** January 30, 2023 (Public Cloud), April 18, 2023 (Private Cloud)

Beginning January 30, 2023 in Public Cloud and April 18, 2023 in Private Cloud, Auth0 will allow the addition of non-namespaced custom claims to <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> tokens using Auth0 Actions and in responses from the Authentication API `/userinfo` endpoint. Previously, Auth0 allowed namespaced claims on access and <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip> via extensibility code ([Rules](/docs/customize/rules) / [Hooks](/docs/customize/hooks) / [Actions](/docs/customize/actions)). The migration to custom claims allows private, non-namespaced custom claims and OIDC user profile claims to be added to <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip>; ID tokens currently support user profile claims and will additionally support private, non-namespaced custom claims. These claims will also be added to the Auth0 `/userinfo` response. To begin the migration, read the [Custom Claims Migration Guide](/docs/troubleshoot/product-lifecycle/past-migrations/custom-claims-migration).

If your tenant is running extensibility code ([Rules](/docs/customize/rules) / [Hooks](/docs/customize/hooks) / [Actions](/docs/customize/actions)) that tries to set non-namespaced custom claims that are being ignored until this deprecation, then those claims will begin to appear on the tokens and the `/userinfo` response. We recommend you review your configuration and Auth0 logs.

With the addition of non-namespaced, private claims, Auth0 is enforcing the following restrictions that could potentially affect your tenant:

* Auth0 will restrict the custom claims payload to a maximum of 100KB.
* Auth0 will restrict the customization/modification of <Tooltip href="/docs/glossary?term=OPENID">OPENID</Tooltip> standard claims or claims used internally by Auth0.
* In the future, Auth0 may restrict the use of other claims not included in the above list. In those cases, customers will be notified with a reasonable time to migrate.
* Auth0 will restrict the creation of private, non-namespaced custom claims on access tokens with an Auth0 <Tooltip href="/docs/glossary?term=audience">audience</Tooltip>, excluding the `/userinfo` endpoint.
* Only specified OIDC user profile claims can be added to access tokens.
* Auth0 will restrict creating a custom claim starting with a \$ character.

To learn more about custom claims, review [Create Custom Claims](/docs/secure/tokens/json-web-tokens/create-custom-claims).

## Legacy Private Cloud Platform

**Deprecated:** June 13, 2022

**End of life:** January 31, 2023

We’re making improvements to the underlying infrastructure that supports Auth0 Private Cloud by introducing a modern Kubernetes-based technology stack, as well as database upgrades. We are currently working with all Auth0 Private Cloud customers to schedule the upgrade of their private cloud deployment to the new infrastructure stack during the course of this year, and will be discontinuing the older stack by January 31, 2023.

In addition, 2205 (May 2022 release) is the last official release for the legacy Private Cloud platform. Any bugs or security vulnerabilities will be assessed and addressed in patch releases as necessary.  Prior to upgrading to the new infrastructure stack, environments will need to be updated to the minimum compatible version to support the upgrade efforts.

Please reach out to your Technical Account Manager with any questions.

## Log Extensions

**Deprecated:** May 4, 2022 (Public Cloud), June 9, 2022 (Private Cloud release 2205)

**End of life:** May 2, 2023 (Public Cloud), January 6, 2023 (Private Cloud)

Beginning May 4, 2022, in Public Cloud and June 9th, 2022, in Private Cloud, the following Auth0 Log Extensions will be deprecated:

* Auth0 Authentication API Webhooks
* Auth0 Management API Webhooks
* Logs to Cloudwatch
* Logs to Logentries
* Logs to Loggly
* Logs to Logstash
* Logs to Papertrail
* Logs to Splunk
* Logs to Sumo Logic

**Deprecated:** November 2, 2022 (Public Cloud), December 21, 2022 (Private Cloud)

**End of life:** May 2, 2023 (Public Cloud), May 31, 2023 (Private Cloud)

Beginning November 2, 2022 in Public Cloud and December 21, 2022 in Private Cloud, the following Auth0 Log Extensions will be deprecated:

* Logs to Segment
* Logs to Mixpanel
* Logs to AppInsights
* Logs to Azure Blob Storage

All the Log extensions listed above are now deprecated. You can set up equivalent functionality using log event streams or integrations on the [Auth0 Marketplace](https://marketplace.auth0.com/). On November 2, 2022 in Public Cloud and December 21, 2022 in Private Cloud, Auth0 will no longer support the installed log extensions from the list above. For more information, read [Migrate from Log Extensions](/docs/troubleshoot/product-lifecycle/past-migrations/migrate-from-log-extensions).

## Tenant Hostname Validation

**Deprecated**: December 9, 2021 and December, 2021 (Private Cloud Release 2112.2)

**End of life**: June 9, 2022 and September 9, 2022 (Private Cloud)

As of June 9, 2022 in Public Cloud and September 9, 2022 in Private Cloud, Auth0 will increase the security of API calls by adding a validation step for tenant hostnames to the Authentication API’s identification process. When a call is made, the Authentication API will validate the entity identifier (eg: `client_id`) of the requesting tenant as well as the tenant name in the URL domain. The tenant owning the identifier **must** be from the same tenant in the URL domain or the request will be rejected.

If your application or API calls any of the listed endpoints, you must configure your API calls to make sure the identifier of the requesting tenant and hostname are the same:

* `/oauth/token`
* `/co/authenticate`
* `/userinfo`
* `/login`
* `/oauth/revoke`
* `/mfa/challenge`
* `/p/<connection-type>/<ticket>` (Enterprise connection provisioning endpoint)

To learn more, read [Tenant Hostname Validation Migration](/docs/troubleshoot/product-lifecycle/past-migrations/tenant-hostname-migration).

## Node.js 16 Migration

**End of life**: April 30, 2022

On 30 Apr 2022, [Node.js v12 went out of long-term support (LTS)](https://github.com/nodejs/Release#release-schedule), which means that the Node.js development team no longer back-ports critical security fixes to this version. This could potentially expose your extensibility code to security vulnerabilities. Therefore, Auth0 is migrating from Node 12 to Node 16.

Although the Node 16 update will not introduce any breaking changes in the Node.js standard library (Rules and Custom Database Action Scripts are affected; see the [Breaking changes - Rules and Custom Database Action Scripts only](#breaking-changes-rules-only) section), we encourage customers on Node version 12 to stay current with Active Long-Term Support (LTS) Node versions for security and compliance purposes. Customers who are still on Node 8 are out of security compliance and must migrate to Node 16 to eliminate security risks. We removed the Node 8 runtime on 22 Feb 2022 for Public Cloud tenants and removed it in the April 2022 Private Cloud release. After these dates, tenants still set to Node 8 run the risk of a service interruption.

## Opaque Access Token and Authorization Code Fixed Length

**Deprecated**: October 7, 2021 (Public Cloud), December 2021 (Private Cloud)

**End of life**: April 12, 2022 (Public Cloud), June 30, 2022 (Private Cloud)

Beginning April 12, 2022 in Public Cloud and with the December 2021 Private Cloud, access token and authorization codes will be issued with varied lengths to support [OAuth specification RFC6749](https://datatracker.ietf.org/doc/html/rfc6749) to avoid clients making assumptions about authorization code and access token values. Currently, the access token and authorization code sizes are fixed. The current size of the authorization code is shorter than what some security practitioners recommend. Through this change, Auth0 provides a stronger code and token while also improving the performance of Auth0 systems.

Customers with systems configured to rely on specific-sized authorization code and access token length must change from fixed-sized to variable-sized configurations before April 12, 2022 in Public Cloud or the June 30, 2022 Private Cloud release.

## Node.js v8 Extensibility Runtime End of Life

**Deprecated**: 15 April 2020

**End of life**: 25 February 2022 (Public Cloud), April 2022 (Private Cloud release)

Beginning 13 December 2019, [Node.js v8 was no longer under long-term support (LTS)](https://github.com/nodejs/Release#release-schedule). This means that critical security fixes were no longer back-ported to this version. Customers who are still on Node 8 are out of security compliance and must migrate to Node 12 to eliminate security risks. To learn more about how to migrate your tenant-level Node version from 8 to 12, read [Migrate from Node.js 8 to Node.js 12](/docs/troubleshoot/product-lifecycle/past-migrations/migrate-to-nodejs-12).

Because Node.js v12 is also going out of LTS in 2022, we also highly encourage all customers using Rules and Hooks to migrate to Actions using Node 16 as soon as possible, and before Node 12 support expires formally from the Node.js community on 30 April 2022. To learn more about required migration steps, read [Migrate Rules and Hooks to Actions](/docs/customize/actions/migrate/migrate-from-rules-to-actions).

## Legacy Network Edge Deprecation

**Deprecated**: 05 May 2021 (Public Cloud)

**End of life**: 03 November 2021 (Public Cloud)

Auth0 legacy network edge will cease to function on Public Cloud. After 03 November 2021, Public Cloud tenants who have not completed a migration to the new Auth0 network edge will no longer receive traffic. All new <Tooltip href="/docs/glossary?term=custom+domains">custom domains</Tooltip> are automatically created on the new network edge.

## Unpaginated Management API v2 Request deprecation

**Deprecated**: 21 July 2020 (Public Cloud)

**End of life**: 26 January 2021 (Public Cloud), February 2022 (Private Cloud release)

After 26 January 2021, requests to the following Management API v2 endpoints will return a maximum of 50 items for Public Cloud tenants. To retrieve more items, you must include `page` and `per_page` parameters. Beginning on 21 July 2020, Auth0 will display tenant logs and a migration toggle to help you prepare for this change.

* [`GET /api/v2/clients`](https://auth0.com/docs/api/management/v2#!/Clients/get_clients)
* [`GET /api/v2/client-grants`](https://auth0.com/docs/api/management/v2#!/Clients/client_grants)
* [`GET /api/v2/grants`](https://auth0.com/docs/api/management/v2#!/Clients/grants)
* [`GET /api/v2/connections`](https://auth0.com/docs/api/management/v2#!/Clients/connections)
* [`GET /api/v2/device-crecentials`](https://auth0.com/docs/api/management/v2#!/Clients/device_credentials)(when the `type` query parameter is used)
* [`GET /api/v2/resource-servers`](https://auth0.com/docs/api/management/v2#!/Clients/resource_servers)
* [`GET /api/v2/rules`](https://auth0.com/docs/api/management/v2#!/Clients/rules)

All Public Cloud tenants are affected that are created before 21 July 2020 and are actively calling affected endpoints without passing the `per_page` parameter for queries that can return more than 1 result. Tenants are not affected if they are created after 21 July 2020, are not using the affected endpoints, are using the affected endpoints and passing the `per_page` parameter, or are making queries that always return only 1 result. To learn more, read [Migrate to Management API v2 Endpoint Paginated Queries](/docs/troubleshoot/product-lifecycle/past-migrations/migrate-to-paginated-queries).

## Private Cloud Custom Domain Deprecation

**Deprecated**: 17 June 2021

**End of life**: 20 December 2021

To achieve consistency across all Auth0 deployments and focus on enhancing the Auth0 Custom Domain feature, we are discontinuing the Private Cloud Custom Domain capability on December 20, 2021. Consistency enables us to enhance the feature and fix reliability issues faster, improving operational efficiency and enabling customers to get value out of custom domains more quickly.

## Logout Redirect Validation

**Deprecated**: 25 May 2021

**End of life**: 01 December 2021

On 01 December 2021, the logout behavior will change to always redirect users to the URI passed to the Auth0 logout APIs instead of using the `returnTo` query parameter passed by <Tooltip href="/docs/glossary?term=Identity+Providers">Identity Providers</Tooltip> to `/login/callback` during the execution of the logout. If Auth0 does not have a record of a preceding call to one of these APIs, logout will complete, but redirection will not occur and an error page will be displayed to end users. To learn more, read [Logout Redirects Migration Guide](/docs/troubleshoot/product-lifecycle/deprecations-and-migrations/logout-return-to).

## Application Admin Dashboard Role deprecation

**Deprecated**: 01 February 2021

**End of life**: 30 September 2021 (Public Cloud), September 2021 (Private Cloud monthly release)

Auth0 is changing the role-based access control to the Dashboard. The Application Administrator role as defined today is being deprecated. After 01 February 2021, administrators won't be able to invite members with the deprecated Application Administrator role. Existing application-specific administrators will continue to be able to use the Dashboard with the existing permission set until the end of life date.

A new set of Dashboard roles is available for improved and more secure collaboration among team members, including viewer and editor roles with limited access. A new **Editor - Specific Apps** role replaces the previous **Application Administrator** role for subscription plans where editor roles are supported.

Your tenants will be affected by this deprecation if the following criteria are met:

* Created before 01 February 2021
* Have at least one tenant member with the **Application Admin** role
* Haven't opted-in to the Dashboard roles feature preview

Beginning on 01 February 2021, Auth0 will display a migration toggle to help you prepare for this change. To learn more, read [Migrate to Manage Dashboard New Roles](/docs/troubleshoot/product-lifecycle/past-migrations/migrate-tenant-member-roles).

## Legacy TLS Deprecation

**Deprecated**: 19 January 2021

**End of life**: 10 May 2021 (Public Cloud), June Private Cloud Release (v2106)

As of 10 May 2021 for Public Cloud and the June Private Cloud Release (v2106), the Auth0 network edge will no longer accept TLS 1.0 or TLS 1.1 traffic.  These legacy protocols are insecure, with well-known weaknesses and vulnerabilities within the industry.  For maximum security, all Auth0 clients must upgrade to TLS 1.2 or later. The exact details and steps required will vary, depending on your application.

## Auth0-analytics.js deprecation

**Deprecation**: January 2018

**End of life**: January 2021

Auth0 has deprecated the use of the [auth0-analytics.js library](https://github.com/auth0/auth0-analytics.js/) that adds Facebook and Google Analytics integration with Lock. It listens for events in Lock and passes them to the Auth0-tag-manager.js library. It may still function in some legacy cases. This library is no longer maintained. You may need to write custom code to use [auth0-tag-manage.js](https://github.com/auth0/auth0-tag-manager) to manage proxy requests to third-party analytics libraries such as Facebook, X, and Google.

## Device credential metadata without user\_id deprecation

**Deprecated**: 31 August 2020

**End of life**: 17 December 2020

Auth0 now requires that you provide the `user_id` when you use the [GET /api/v2/device-credentials endpoint](https://auth0.com/docs/api/management/v2/#!/Device_Credentials/get_device_credentials). If your request does not provide a `user_id`, it will return a 400 status code. Check the `depnote` in your tenant logs to see if you are affected by this deprecation. To learn more, read [Check Deprecation Errors](/docs/troubleshoot/basic-issues/check-deprecation-errors).

Auth0 has identified tenants affected by this deprecation and contacted the administrators for those tenants. If your tenant is currently making requests without a `user_id`, you should make the change as soon as possible.

## Azure AD/ADFS email verification deprecation

**Deprecated**:

* Public Cloud: 18 November 2020
* Private Cloud: 01 December 2020

**End of life**:

* Public Cloud: 18 May 2021
* Private Cloud: June Private Cloud Release (v2106)

Auth0 previously set the `email_verified` field to true in Azure AD and ADFS connections. If you used Azure AD/ADFS connections before this deprecation date, you have a tenant setting that overrides the connection setting for email verification and keeps the previous behavior.

On 18 May 2021 in Public Cloud and the June Private Cloud Release (v2106), Auth0 begins using the connection-level property for all Azure AD/ADFS connections. You should make sure all your connections are configured properly before that date. To learn more, read [Email Verification for Azure AD and ADFS](/docs/authenticate/identity-providers/enterprise-identity-providers/azuread-adfs-email-verification).

## sameSite cookie attribute changes

**Effective**: February 2020

Google Chrome v80 is changing the way it handles cookies. To that end, Auth0 will implement the following changes in the way it handles cookies:

* Cookies without the `samesite` attribute set will be set to `lax`
* Cookies with `sameSite=none` must be secured, otherwise they cannot be saved in the browser's cookie jar

The goal of these changes is to improve security and help mitigate CSRF attacks. For details, see [sameSite Cookie Attribute Changes](/docs/manage-users/cookies/samesite-cookie-attribute-changes).

## User Search v2 deprecation

**Deprecated**: 10 November 2018

**End of life**: 30 June 2019 (Public Cloud), May 2021 (Private Cloud monthly release)

For Public Cloud, User Search v2 was deprecated and you should have taken action before 30 June 2019. Notifications were sent to customers that need to complete this migration.

For Private Cloud, User Search v1 and v2 endpoints will be no longer be available after the May Private Cloud monthly release and have been replaced with the new User Search v3 endpoint.

## Passwordless Endpoint from Confidential Applications deprecation

Auth0 has deprecated the use of the `/passwordless/start` endpoint from confidential applications when Auth0 cannot authenticate that the call is made on behalf of the application. To learn more, read [Migrate to Passwordless Endpoint from Confidential Applications](/docs/troubleshoot/product-lifecycle/past-migrations/migrate-to-passwordless).Clickjacking Protection for <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> changes

To prevent clickjacking, in cases where you render your login page in an iframe, Auth0 has added an opt-in to add headers which we strongly recommend you enable. For details, see [Clickjacking Protection for Universal Login Change](/docs/troubleshoot/product-lifecycle/past-migrations/clickjacking-protection-for-universal-login).

## Management API endpoints using ID token credentials deprecation

**Deprecation**: 31 March 2018

**End of life**: TBD

Auth0 is deprecating the use of ID tokens as credentials to call some of the users and device endpoints and replacing it with the use of access tokens instead. For details, see [Migrate to Management API Endpoints with Access Tokens](/docs/troubleshoot/product-lifecycle/past-migrations/migrate-to-calling-api-with-access-tokens) and [Migrate to Link User Accounts with Access Tokens](/docs/troubleshoot/product-lifecycle/past-migrations/link-user-accounts-with-access-tokens-migration).

## Resource Owner Password /oauth/ro deprecation

**Deprecation**: 08 July 2017

**End of life**: TBD

As of 08 July 2017 Auth0 has deprecated the`/oauth/ro` endpoint for both password and <Tooltip href="/docs/glossary?term=passwordless">passwordless</Tooltip> connections. You can now implement the same functionality using the `/oauth/token` endpoint. To learn more, read [Resource Owner Password Flow Migration](/docs/troubleshoot/product-lifecycle/past-migrations/migration-oauthro-oauthtoken).

## Management API v1 deprecation

**Deprecation**: October 2016

**End of life**:

* Public Cloud: 13 July 2020
* Private Cloud: November 2020 monthly release

Management API v1 will reach its End of Life in the Public Cloud on 13 July 2020. Management API v1 will be included in the Private Cloud until the November 2020 monthly release, which is the first release that will not include Management API v1. You may be required to take action before that date to ensure no interruption to your service. Notifications have been and will continue to be sent to customers that need to complete this migration.

## Instagram connection deprecation

**Deprecated**: 05 March 2020

**End of life**: 31 March 2020

Facebook announced that on 31 March 2020 that they will turn off the Instagram legacy APIs, and they won't provide an alternative to implement login with Instagram. For details, see [Instagram Connection Deprecation](/docs/troubleshoot/product-lifecycle/past-migrations/instagram-connection-deprecation).

## Yahoo API changes

**Deprecated**: 01 March 2020

**End of life**: 01 March 2020

Yahoo changed the way to retrieve the user profile and the information included in it. For details, see [Yahoo API Changes](/docs/troubleshoot/product-lifecycle/past-migrations/yahoo-api-changes).

## Google Cloud Messaging deprecation

**Deprecation**: 11 April 2019

**End of life**: 11 April 2019

As of 11 April 2019, [Google deprecated](https://firebase.googleblog.com/2018/04/time-to-upgrade-from-gcm-to-fcm.html) and replaced Google Cloud Messaging (GCM) with Firebase Cloud Messaging (FCM). For details, see [Google to Firebase Cloud Messaging Migration](/docs/troubleshoot/product-lifecycle/past-migrations/google-firebase-migration).

## Facebook Social Context field deprecation

**Deprecation**: 30 April 2019

**End of life**: 30 July 2019

On 30 April 2019, Facebook deprecated the use of the **Social Context** field for new applications. For details, see [Facebook Social Context Field Deprecation](/docs/troubleshoot/product-lifecycle/past-migrations/facebook-social-context-field-deprecation).

## Facebook Graph API changes

**Deprecation**: 01 August 2018

**End of life**: Graph API v3 released 08 January 2019

As of 01 August 2018, Facebook has changed the Facebook Graph API permissions and fields that can be requested. Auth0 has updated Facebook Connections to reflect these changes and modified the connection interface for clarity. See [Facebook Login Changelog: Recent Changes to Facebook Login](https://developers.facebook.com/docs/facebook-login/changelog#2018-07-02) for complete details and key dates. For details, see [Facebook Graph API Changes](/docs/troubleshoot/product-lifecycle/past-migrations/facebook-graph-api-changes).

## Lock v11 and Auth0.js v9

We are continually improving the security of our service. As part of this effort, we have deprecated the Legacy Lock API, which consists of the `/usernamepassword/login` and `/ssodata` endpoints. These endpoints are used by Lock.js v8, v9, and v10 and Auth0.js, v6, v7, and v8, and can also be called directly from applications.

As of August 6, 2018, Auth0 has permanently disabled the Legacy Lock API. This removal of service fully mitigates the CSRF vulnerability [disclosed in April 2018](https://auth0.com/blog/managing-and-mitigating-security-vulnerabilities-at-auth0/). This also ends the soft removal grace period that was first announced on 16 July 2018, meaning the Legacy Lock API can no longer be re-enabled.

If your Legacy Lock API migration has not yet been completed, your users may experience an outage, failed logins, or other adverse effects. You will need to complete your migration in order to restore normal functionality. Check deprecation errors to identify the source(s) of any errors in your tenant logs related to deprecations.

### Features affected

If you are currently implementing login in your application with Lock v8, v9, or v10, or Auth0.js v6, v7, or v8, you are affected by these changes. Additionally, you are affected if your application calls the `/usernamepassword/login` or `/ssodata` endpoints directly via the API.

We recommend that applications using Universal Login update the library versions they use inside of the login page.

However, those who are using Lock or Auth0.js embedded within their applications, or are calling the affected API endpoints directly, are required to update, and applications which still use deprecated endpoints will cease to function properly after the removal of service date.

Libraries and SDKs not explicitly named here are not affected by this migration.

## Tenant Log Search v2 deprecation

**Deprecation**: 21 May 2019

**End of life**:

* Free: 09 July 2019
* Essential (former Developer): 20 August 2019
* Professional (former Developer Pro): 20 August 2019
* Enterprise: 04 November 2019

To provide our customers with the most reliable and scalable solution, Auth0 has deprecated Tenant Logs Search Engine v2 in favor of v3. Auth0 is proactively migrating customers unaffected by this change, while those who are potentially affected are being notified to opt in for v3 during the provided grace period. For details, see [Migrate to Tenant Log Search v1 to V2](/docs/troubleshoot/product-lifecycle/past-migrations/migrate-to-tenant-log-search-v3).

## New IP addresses for Allowlisting in Australia

As of 30 September 2017, Auth0 updated its cloud environments and traffic from Australia originates from new IP addresses. If you are allowlisting IP addresses, you will need to add the new addresses to your firewall rules.

### Features affected

If you are using a custom database connection, rule, and/or custom email provider that connects to your environment, **and** you have implemented firewall restrictions for IP address ranges, then you are affected by this change. You will need to make sure the following IP addresses are allowed to go through your firewall:

`13.55.232.24, 13.54.254.182, 13.210.52.131, 52.62.91.160, 52.63.36.78, 52.64.84.177, 52.64.111.197, 52.64.120.184, 54.66.205.24, 54.79.46.4, 54.153.131.0`

## New IP addresses for allowlisting in Europe

As of 30 September 2017, Auth0 updated its cloud environments and traffic from Europe originates from new IP addresses. If you are allowlisting IP addresses, you will need to add the new addresses to your firewall rules.

### Features affected

If you are using a custom database connection, rule, and/or custom email provider that connects to your environment, and you have implemented firewall restrictions for IP address ranges, then you are affected by this change. You will need to make sure the following IP addresses are allowed to go through your firewall:

`34.253.4.94, 35.156.51.163, 35.157.221.52, 52.16.193.66, 52.16.224.164, 52.28.45.240, 52.28.56.226, 52.28.184.187, 52.28.212.16, 52.29.176.99, 52.50.106.250, 52.57.230.214, 52.211.56.181, 52.213.216.142, 52.213.38.246, 52.213.74.69`

## CDN provider migration in the Europe and Australia environments

As of 12 July 2017, Auth0 has improved the Auth0 CDN scaling and availability. We now use Amazon CloudFront. We have already made this change in the US environment, and are now ready to do so in Europe and Australia.

### Features affected

You are affected if you use Lock (hosted by our CDN) in Europe or Australia. This change shouldn't cause any disruption or change in behavior in your applications, so you don't have to do anything. This notification is for information only.

## Password and refresh token exchange rules migration

On 31 May 2017, as part of Auth0's efforts to improve security, we added the ability to execute rules during the <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> <Tooltip href="/docs/glossary?term=Resource+Owner">Resource Owner</Tooltip> Password Grant exchange (the password exchange) and the refresh token exchange.

### Features affected

You are using this feature if you are calling the `/oauth/token` endpoint of our Authentication API with `grant_type = "password"` , `grant_type = "http://auth0.com/oauth/grant-type/password-realm"`, or `grant_type = "refresh_token"`.

You could be impacted if you are currently using these exchanges and have rules defined in Dashboard. In order to ensure a smooth transition, we have disabled the rules execution on these specific exchanges for your tenant. These rules will now execute for all new customers, as well as customers who have not yet used these exchanges.

You can add logic to your rules to alter their behavior for these exchanges by checking the `context.protocol` property:

* `oauth2-password` indicates the password (and password-realm) exchange
* `oauth2-refresh-token` indicates the Refresh Token exchange

If you would like to enable the new behavior on this tenant for testing before the mandatory opt-in date, login to [Dashboard](https://manage.auth0.com/#) and enable the **Run Rules on Password and Refresh Token Exchanges** toggle in [Tenant Settings > Advanced](https://manage.auth0.com/#/tenant/advanced).

## Account linking removal

On 01 March 2017, as part of Auth0's efforts to improve security and standards compliance, we stopped supporting account linking as part of the authorization callback (that is, accepting an access token as part of the authorize call).

### Features affected

If you received an email notification about it, then you are impacted by this change. As you work to update your applications to use the Management API to link accounts, you can check if you are still impacted, by checking your tenant logs for warnings. These entries will be logged if you are sending an Access Token in your authorize calls.

## Allowlist IP address ranges

As of 20 February 2017, Auth0 expanded into new US regions and traffic originating from these regions will have new IP addresses. If you allowlist IP addresses you will need to add the new addresses to your firewall rules.

### Features affected

If you are using a custom database connection, rule, and/or custom email provider that connects to your environment, and you have implemented firewall restrictions for IP address ranges, then you are affected by this change. You will need to add the following IP addresses to your firewall rules:

`138.91.154.99, 54.183.64.135, 54.67.77.38, 54.67.15.170,54.183.204.205, 54.173.21.107, 54.85.173.28, 35.167.74.121, 35.160.3.103,35.166.202.113, 52.14.40.253,52.14.38.78, 52.14.17.114, 52.71.209.77, 34.195.142.251, 52.200.94.42`

## Vulnerable password flow

Prior to 01 February 2017, Auth0's password reset flow allowed a user to enter their email and a new password. This triggered a confirmation email that to be sent to the user asking them to confirm that they requested a password reset.

### Features affected

The issue is that the confirmation link could be inadvertently clicked by a user which would result in the user's password being changed by an attacker.

Lock version 9 and above uses the new password reset flow exclusively. Lock 8 and below does not handle the new password reset flow. We strongly recommend upgrading to Lock 9 or greater as soon as possible.

<Warning>
  Even if you are not using Lock, the vulnerable reset flow can be accessed directly through the API. (See the /dbconnections/change\_password endpoint for details.) Auth0 strongly encourages you to change any app using the current flow to move immediately to the new reset flow and enable this migration.
</Warning>

## State parameter required on redirect from rule

As of 06 December 2016, when a redirect is done from an Auth0 rule, Auth0 generates and sends a state parameter in HTTP and check for a valid state parameter when flow returns to the `/continue` endpoint. The site to which the redirect goes has to capture the value of the state parameter and return it by adding it as a parameter when returning to the `/continue` endpoint.

### Features affected

You are affected by the change only if you redirect from rules, and do not yet capture and return (to the /continue end point) the state parameter.

## Delete all users endpoint change

Prior to 13 September 2016, the previous endpoint for deleting all users was `DELETE /api/v2/users`. This is similar to the endpoint to delete one user: DELETE `/api/v2/users`. To prevent accidental requests to the delete all users endpoint, the url has been changed to `DELETE /api/v2/allusers`. This should ensure that only intentional calls to this endpoint get made.

### Features affected

You are affected by the change only if you currently make use of the delete all users endpoint. If so, the only change you need to make is to change the URL as explained above.

## Email delivery template customization changes

As of 29 August 2016, Auth0's built-in email provider is longer be supported for use in a production environment. The emails sent using the Auth0 provider will no longer be customizable. They will be restricted to the template and you will not be able to change the from address or subject line.

The built-in email service may still be used for test purposes but you must switch to an Auth0-supported third-party service ([Amazon SES](https://aws.amazon.com/ses/), [Mailchimp](https://mailchimp.com/features/transactional-email/), [SendGrid](https://sendgrid.com/en-us/pricing) or another SMTP-based provider before moving your apps to production. If you already use a custom email provider, no action is necessary.

## Identity provider access tokens removed from user profile and ID token

As of 08 August 2016, the format of the user profile JSON object (ID token) that is returned by Auth0 Authentication APIs changed to remove the identity provider access token and included in the user profile `identities` array.

To obtain a user's identity provider access token, you will need to make an HTTP GET call to the `/api/v2/users/{user-id}` endpoint containing an API token generated with `read:user_idp_tokens` scope. You will still have access to the identity provider access token in the `user` argument in Auth0 rules.

### Features affected

You are affected by the change only if you are using the Identity Provider Access Token (`identities[0].access_token` in the user profile) outside of rules to call other services from the Identity Provider (such as Facebook Graph API, Google APIs, etc.). If your tenant was created after the change the update will be done automatically.

## Tokeninfo endpoint validation

As of 01 June 2016, when calling the Tokeninfo endpoint, the URL of the API call (for example `https://{yourDomain}/`) must match the value of the `iss` attribute of the ID Token being validated. If these values do not match, the response will be `HTTP 400 - Bad Request`.

### Features affected

If you are calling the Tokeninfo endpoint directly, make sure that the value of the `iss` attribute of the ID Token being validated matches your Auth0 tenant namespace: `https://{yourDomain}/`. You can use [jwt.io](https://www.jwt.io/) to decode the token to confirm the `iss` attribute value.

## Email delivery from address changes

On 27 April 2016, Auth0's built-in email provider started sending all emails from a predefined from address (`no-reply@auth0user.net`). Custom Email Providers are now free. To customize the "from" address, you can switch to an Auth0-supported third-party service ([Amazon SES](https://aws.amazon.com/ses/), [Mailchimp](https://mailchimp.com/features/transactional-email/), [SendGrid](https://sendgrid.com/en-us/pricing)) or another SMTP-based provider. If you already use a custom email provider, nothing will change.

## Patch and Post endpoints no longer accept secret\_encoded flag

The `jwt_configuration.secret_encoded` configuration is no longer accepted by the PATCH and POST applications endpoints.

In order to further comply with the OIDC specification, Auth0 will no longer generate or accept base64 encoded application secrets for new applications.

Existing applications with encoded secrets stored will remain intact and unchanged, but new applications will no longer use base64 encoding. The `secret_encoded` flag is no longer accepted or necessary, as a result.

### Features affected

You are affected by this change only if you interact with these endpoints directly.


# Clickjacking Protection for Universal Login Change
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/clickjacking-protection-for-universal-login

Describes how Auth0 is adding a way to prevent the Universal Login pages from being embedded into an iframe to protect against clickjacking attacks.

Clickjacking is an attack that tricks a user into clicking a web page element which is invisible or disguised as another element. This is done by loading content in an iframe and rendering elements on top of it. In the context of the <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip> pages, an attacker could trick the user into clicking a **Login**, or **Reset Password** button.

This can be prevented by setting the following HTTP headers:

`X-Frame-Options: deny
Content-Security-Policy: frame-ancestors 'none'`

Even if the potential attack does not entail significant risk, it's a good security practice to add the headers. It is also detected by security scanners, so reports from penetration testers might mention the lack of these headers.

## Actions

In cases where you render the login page in an iframe, adding these headers could be a breaking change. Instead of adding these headers for all customers, therefore, Auth0 has allowed you to opt-in for these headers, which we strongly recommend you to enable.

The following action is not required if you are using the New Universal Login Experience because those headers are always set in that case.

To opt in to this change:

1. Go to [Tenant Settings > Advanced Settings](https://manage.auth0.com/#/tenant/advanced).
2. Scroll to **Migrations**, and turn off the **Disable clickjacking protection for Classic Universal Login** setting.


# Migrate Custom Claims
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/custom-claims-migration

Describes migration from Legacy namespaced claims to custom claims.

As of 28 July 2022, Auth0 will allow private, non-namespaced custom claims to be added to access and <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip>. These same claims will also be added to the response of the [`/userinfo` endpoint](https://auth0.com/docs/api/authentication#get-user-info). To learn more about the types of <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip> claims, read [JSON Web Token Claims](/docs/secure/tokens/json-web-tokens/json-web-token-claims).

<Warning>
  Despite allowing the use of private, non-namespaced custom claims, Auth0 strongly recommends the use of public, namespaced custom claims whenever possible. Public, namespaced custom claims are the best way to avoid any collision with future claims added to the standard.
</Warning>

#### Example

Previously, Auth0 allowed only namespaced claims on access and ID tokens. With the migration to custom claims, non-namespaced claims can be used on <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip>, ID tokens, and the `/userinfo` endpoint of Auth0's Authentication API.

```javascript lines theme={null}
// an Auth0 action 
exports.onExecutePostLogin = async (event, api) => {

  // public namespaced custom claims 
  api.accessToken.setCustomClaim('https://myDomain.com/myClaim', 'this is a public, namespaced claim');
  api.idToken.setCustomClaim('https://myDomain.com/myClaim', 'this is a public, namespaced claim');

  // non-namespaced custom claims
  api.accessToken.setCustomClaim('myClaim', 'this is a private, non namespaced claim');
  api.idToken.setCustomClaim('myClaim', 'this is a private, non namespaced claim');
};
```

## Affected flows

All <Tooltip href="/docs/glossary?term=OpenID">OpenID</Tooltip> Connect (OIDC) flows that Auth0 supports are affected by this migration. To review the list of flows, read [Authentication and Authorization Flows](/docs/get-started/authentication-and-authorization-flow).

The following features are also affected:

* [Native Social Login](/docs/get-started/authentication-and-authorization-flow)
* [Refresh tokens](/docs/secure/tokens/refresh-tokens)

The following features are affected only when used along with [Auth0 Rules](/docs/customize/rules) and attribute mapping:

* [Web Services Federation Protocol (WS-Fed)](/docs/authenticate/protocols/ws-fed-protocol)
* [SAML2 Web app add-on](/docs/authenticate/protocols/saml/saml-sso-integrations/enable-saml2-web-app-addon)

## Restrictions

### Maximum token size

Auth0 will restrict the custom claims payload to a maximum of 100KB. It is important to make sure the payload does not exceed this limit, otherwise the authentication transaction will fail with an error. We recommend you review your use of extensibility code (i.e. [Rules](/docs/customize/rules), [Hooks](/docs/customize/hooks), or [Actions](/docs/customize/actions)). In particular, review large payloads from external APIs.

To avoid errors, Auth0 recommends using the smallest token payload necessary for your application to operate. You may need to strip any properties that are not crucial before you set the custom claim value.

<Callout icon="file-lines">
  This restriction is applied to the total payload size of all your custom claims. This includes the custom claims names as well as the associated values, whether they are public namespaced or private non namespaced.
</Callout>

The limit of 100KB is applied to access tokens and ID tokens separately. For example, an access token of 100KB and an ID token of 100KB can be returned in the same transaction.

#### Examples

```javascript lines theme={null}
// an Auth0 action 
exports.onExecutePostLogin = async (event, api) => {

  // fetching a payload that is superior to 100KB
  const aHeavyPayload = getHeavyPayload();

  // this will fail the authentication
  api.idToken.setCustomClaim('myclaim', aHeavyPayload);

};
```

```javascript lines theme={null}
// an Auth0 action 
exports.onExecutePostLogin = async (event, api) => {

  // fetching a payload that is 50KB
  const a50KBPayload = getHeavyPayload();

  // fetching another payload that is 50KB
  const another50KBPayload = getHeavyPayload();

  // this will fail the authentication
  api.idToken.setCustomClaim('myclaim', a50KBPayload);
  api.idToken.setCustomClaim('https://myDomain.com/myClaim', another50KBPayload);

};
```

```javascript lines theme={null}
// an Auth0 action 
exports.onExecutePostLogin = async (event, api) => {

  // fetching a payload that is 50KB
  const a50KBPayload = getHeavyPayload();

  // fetching another payload that is 50KB
  const another50KBPayload = getHeavyPayload();

  // this will succeed
  api.accessToken.setCustomClaim('myclaim', a50KBPayload);
  api.idToken.setCustomClaim('https://myDomain.com/myClaim', another50KBPayload);

};
```

### Restricted claims

Auth0 will restrict the customization of claims used in the OIDC or OAuth2 standards or claims for internal use. Any attempt to modify one of these claims will be ignored. The transaction won't fail, but the claim will not be added to tokens. Auth0 recommends using a public, namespaced claim.

* `acr`
* `act`
* `active`
* `amr`
* `at_hash`
* `ath`
* `attest`
* `aud`
* `auth_time`
* `authorization_details`
* `azp`
* `c_hash`
* `client_id`
* `cnf`
* `cty`
* `dest`
* `entitlements`
* `events`
* `exp`
* `groups`
* `gty`
* `htm`
* `htu`
* `iat`
* `internalService`
* `iss`
* `jcard`
* `jku`
* `jti`
* `jwe`
* `jwk`
* `kid`
* `may_act`
* `mky`
* `nbf`
* `nonce`
* `object_id`
* `org_id`
* `org_name`
* `orig`
* `origid`
* `permissions`
* `roles`
* `rph`
* `s_hash`
* `sid`
* `sip_callid`
* `sip_cseq_num`
* `sip_date`
* `sip_from_tag`
* `sip_via_branch`
* `sub`
* `sub_jwk`
* `toe`
* `txn`
* `typ`
* `uuid`
* `vot`
* `vtm`
* `x5t#S256`

#### Example

```javascript lines theme={null}
// an Auth0 action 
exports.onExecutePostLogin = async (event, api) => {

  // this will be ignored
  api.accessToken.setCustomClaim('roles', 'this is a role, but Auth0 will ignore it');

  // this will succeed, and appear in the token
  api.idToken.setCustomClaim('https://myDomain.com/roles', 'this is a role');

};
```

### Restricted token audience

Auth0 will restrict the creation of private, non-namespaced custom claims on access tokens in which the <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> is an Auth0 API. Any attempt to set a private, non-namespaced custom claim on an access token where the audience is an Auth0 API will be ignored. The transaction will not fail, but the claim will not be added to your token. Auth0 recommends not setting custom claims on tokens that are to be consumed by Auth0’s APIs.

<Callout icon="file-lines">
  * ID tokens are not concerned by this restriction.
  * Public namespaced custom claims are not concerned by this restriction.
</Callout>

The following audience will restrict the creation of private, non-namespaced custom claims:

* `https://YOUR_TENANT.auth0.com/api` or `https://YOUR_TENANT.auth0app.com/api`
* `https://YOUR_TENANT.auth0.com/api/v2` or `https://YOUR_TENANT.auth0app.com/api/v2`
* `https://YOUR_TENANT.auth0.com/mfa` or `https://YOUR_TENANT.auth0app.com/mfa`

The exception to this restriction is the Auth0 `/userinfo` audience. Private, non-namespaced custom claims are allowed on the following audience:

* `https://YOUR_TENANT.auth0.com/userinfo`
* `https://YOUR_TENANT.auth0app.com/userinfo`

#### Examples

```javascript lines theme={null}
// an Auth0 action 
exports.onExecutePostLogin = async (event, api) => {

  // these will be ignored if the audience is an Auth0 audience
  api.accessToken.setCustomClaim('myATclaim', 'this is a claim');
  api.accessToken.setCustomClaim('https://myDomain.com/myATclaim', 'this is a claim');

  // these will succeed, they are not concerned by the audience restriction
  api.idToken.setCustomClaim('myIdTclaim', 'this is a claim');
  api.idToken.setCustomClaim('https://myDomain.com/myIdTclaim', 'this is a claim');

};
```

The example below demonstrates the returned response with custom claims if the audience is not an Auth0 API:

```text lines theme={null}
-- A resource owner password flow 
POST https://{yourTenant}.auth0.com/oauth/token

grant_type:password
username:***
password:***
client_id:***
client_secret:***
audience:https://{yourApi}.com -- Note the audience, that is a custom API
scope:openid profile
```

<AuthCodeBlock />

The example below demonstrates the returned response with custom claims not added with an Auth0 API audience:

```text lines theme={null}
-- A resource owner password flow 
POST https://{yourTenant}.auth0.com/oauth/token

grant_type:password
username:***
password:***
client_id:***
client_secret:***
audience:https://{yourTenant}.auth0.com/api/v2/ -- This is an Auth0 audience 
scope:openid profile
```

```json lines theme={null}
// The Access token returned by Auth0
{
  "iss": "https://{yourTenant}.auth0.com/",
  "sub": ***,
  "aud": [
    "https://{yourTenant}.auth0.com/api/v2/",
    "https://{yourTenant}.auth0.com/userinfo"
  ],
  "iat": 1655283444,
  "exp": 1655369844,
  "azp": ***,
  "scope": "openid profile",
  "gty": "password",

  // The public namespaced custom claims was added, because it is not concerned by this restriction
  // However, the private non-namespaced custom claim {myATclaim} was ignored
  "https://mydomain.com/{myATclaim}": "this is a claim"
}
```

## Restriction on Auth0 and Webtask namespaces

Auth0 will restrict the creation of namespaced custom claims with an Auth0 domain as namespace identifier. Auth0 domains are:

* auth0.com
* webtask.io
* webtask.run

Any attempt to set a namespaced custom claim on a token with one of the domains above as an identifier will be ignored. The transaction will not fail, but the claim will not be added to your token.

<Callout icon="file-lines">
  Before this migration, setting a namespaced custom claim with an Auth0 domain identifier would result in the claim showing up in the `/userinfo` response. This behavior disappears after the migration and such custom claims are completely ignored.
</Callout>

```javascript lines theme={null}
// an Auth0 action 
exports.onExecutePostLogin = async (event, api) => {

  // none of these will be added to tokens nor to /userinfo response
  api.idToken.setCustomClaim('https://example.auth0.com', 'this is a claim');
  api.idToken.setCustomClaim('https://example.webtask.io', 'this is a claim');
  api.idToken.setCustomClaim('https://example.webtask.run', 'this is a claim');

};
```

### OIDC user profile claims

Auth0 will now allow OIDC user profile claims to be added to access tokens.

Attempts to add OIDC user profile claims to the access token were silently ignored prior to this migration. With the updated behavior, access tokens will contain these OIDC user profile claims.

<Callout icon="file-lines">
  If you add OIDC user profile claims to access tokens, the same scope restrictions apply as are applicable to ID tokens. For example, to add `email` claim to access tokens, the flow must be triggered with a `scope` that contains `email`.
</Callout>

You can add the following OIDC user profile claims to access tokens:

* `address`
* `birthdate`
* `email`
* `email_verified`
* `family_name`
* `gender`
* `given_name`
* `locale`
* `middle_name`
* `name`
* `nickname`
* `phone_number`
* `phone_number_verified`
* `picture`
* `preferred_username`
* `profile`
* `updated_at`
* `website`
* `zoneinfo`

#### Example

```javascript lines theme={null}
// an Auth0 action 
exports.onExecutePostLogin = async (event, api) => {

  // this was ignored so far. From this migration on, the claim will be added to access tokens 
  // if the scope contains 'email'
  api.accessToken.setCustomClaim('email', 'myemail@domin.com');

  // this was ignored so far. From this migration on, the claim will be added to access tokens 
  // if the scope contains 'profile'
  api.accessToken.setCustomClaim('family_name', 'A family name');

};
```

### SAML2 add-on and Web Service Federation Protocol (WS-Fed) attribute mapping with Auth0 Rules

Similar to using Auth0 Rules to make changes to the user object, `app_metadata` or `user_metadata` pre-migration claims also merge contents when the claim is set on the `context.idToken` object and the names conflict. To learn more about the object properties, read [User Object Properties In Rules](/docs/customize/rules/user-object-in-rules).

Using custom claims, however, Auth0 gives precedence to the claim that was set on the `context.idToken object`.

This change impacts Auth0 Rules that set `app_metadata` and `user_metadata` via `context.id_token` (assigning objects to them) and, at the same time, uses these fields in attribute mapping for <Tooltip href="/docs/glossary?term=SAML">SAML</Tooltip> add-on or <Tooltip href="/docs/glossary?term=Web+Service+Federation">Web Service Federation</Tooltip> Protocol (WS-Fed).

Example 1: Auth0 ignores attribute mapping when `context.idToken.app_metadata` is set with an empty object.

```javascript lines theme={null}
// an Auth0 Rule
function (user, context, callback) {

  user.app_metadata.a_claim = 'This is a claim';
  user.app_metadata.another_claim = 'This is a another claim';

  context.samlConfiguration = context.samlConfiguration || {};

  context.samlConfiguration.mappings = {
    "a_claim": "app_metadata.a_claim",
    "another_claim": "app_metadata.another_claim"
  };

  context.idToken.app_metadata = {};

  return callback(null, user, context);
}
```

SAML response prior to this migration:

```xml lines theme={null}
<samlp:Response>
    (...)
    <saml:Assertion>
        (...)
        <saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <saml:Attribute Name="a_claim" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xsi:type="xs:string">
                    This is a claim
                </saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="another_claim" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xsi:type="xs:string">
                    This is a another claim
                </saml:AttributeValue>
            </saml:Attribute>
        </saml:AttributeStatement>
    </saml:Assertion>
</samlp:Response>
```

SAML response with the upgraded behavior:

```xml lines theme={null}
<samlp:Response>
    (...)
    <saml:Assertion>
        (...)
        <saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
    </saml:Assertion>
</samlp:Response>
```

Example 2: The version of `app_metadata` in `context.id_token` takes precedence.

```javascript lines theme={null}
// an Auth0 Rule
function (user, context, callback) {

  user.app_metadata.a_claim = 'This is a claim';
  user.app_metadata.another_claim = 'This is a another claim';

  context.samlConfiguration = context.samlConfiguration || {};

  context.samlConfiguration.mappings = {
    "a_claim": "app_metadata.a_claim",
    "another_claim": "app_metadata.another_claim",
    "claim_set_via_id_token": "app_metadata.claim_set_via_id_token"
  };

  context.idToken.app_metadata = {
  	claim_set_via_id_token: "This is a claim which was set via context.idToken"
  };

  return callback(null, user, context);
}
```

SAML Response prior to this migration:

```xml lines theme={null}
<samlp:Response>
    (...)
    <saml:Assertion>
        (...)
        <saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <saml:Attribute Name="a_claim">
                <saml:AttributeValue xsi:type="xs:anyType">
                    This is a claim
                </saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="another_claim">
                <saml:AttributeValue xsi:type="xs:anyType">
                    This is a another claim
                </saml:AttributeValue>
            </saml:Attribute>
            <saml:Attribute Name="claim_set_via_id_token">
                <saml:AttributeValue xsi:type="xs:anyType">
                    This is a claim which was set via context.idToken
                </saml:AttributeValue>
            </saml:Attribute>
        </saml:AttributeStatement>
    </saml:Assertion>
</samlp:Response>
```

SAML response with the upgraded behavior:

```xml lines theme={null}
<samlp:Response>
    (...)
    <saml:Assertion>
        (...)
        <saml:AttributeStatement xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <saml:Attribute Name="claim_set_via_id_token" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xsi:type="xs:string">
                    This is a claim which was set via context.idToken
                </saml:AttributeValue>
            </saml:Attribute>
        </saml:AttributeStatement>
    </saml:Assertion>
</samlp:Response>
```

### Add private, non-namespace claims to tokens

<Callout icon="file-lines">
  Custom claims behavior will not change for members of the custom claims beta program. This feature is already enabled.
</Callout>

You can now add private, non-namespaced custom claims to the payload of access and ID tokens.

#### Example

```javascript lines theme={null}
// an Auth0 action 
exports.onExecutePostLogin = async (event, api) => {

  // previously ignored
  // From this migration on, the claim will be added to access tokens
  api.accessToken.setCustomClaim('myATclaim', 'this is a claim');

  // previously ignored
  // From this migration on, the claim will be added to ID tokens
  api.idToken.setCustomClaim('myIdTclaim', 'this is a claim');

};
```

### Private, non-namespace claims to /userinfo

Auth0 now returns private, non-namespaced custom claims in the /userinfo response when set on ID tokens.

#### Example

```javascript lines theme={null}
// an Auth0 action 
exports.onExecutePostLogin = async (event, api) => {

  // this was ignored so far. 
  // From this migration on, this claim will be returned in /userinfo
  api.idToken.setCustomClaim('myIdTclaim', 'this is a claim');

};
```

```text lines theme={null}
-- a call to /userinfo 
GET https://{yourTenant}.auth0.com/userinfo
Authorization: Bearer {yourAccessToken}
```

```json lines theme={null}
// the response from /userinfo
{
    "sub": ***,
    (...)
    "myIdTclaim": "this is a claim"
}
```

## Actions

### Review tenant logs

First, check your tenant logs for deprecation notices to determine whether your tenant is affected by the migration.

1. Navigate to Auth0 [Dashboard > Monitoring > Logs](https://manage.auth0.com/#/logs).
2. Search the logs for `type: depnote AND description: *Custom*claims*`.

### Example

Provided below is an example deprecation log that is generated whenever extensibility code triggers.

```json lines expandable theme={null}
{
  "date": "2022-06-28T08:12:52.084Z",
  "type": "depnote",
  "description": "Custom claims must be namespaced: This feature is being deprecated. Please see details.feature of this log for more information.",
  "connection_id": "",
  "client_id": ****,
  "client_name": ****,
  "details": {
    "feature": {
      "grant": "password",
      "access_token_claims_to_be_allowed": [
        "myclaim"
      ],
      "access_token_claims_to_be_disallowed": [
        "gty"
      ],
      "id_token_claims_to_be_allowed": [
        "myclaim"
      ],
      "id_token_claims_to_be_disallowed": [
        "gty"
      ],
      "id": "legacy_custom_claims",
      "name": "Custom claims must be namespaced when they are added through rules / actions / hooks."
    }
  },
  "log_id": ****,
  "_id": ****,
  "isMobile": false,
  "user_agent": "Other 0.0.0 / Other 0.0.0",
  "id": ****
}
```

### Fix Auth0 rules for SAML2 add-on and Web Service Federation Protocol (Ws-Fed)

If you set `app_metadata` or `user_metadata` claims on the `context.idToken` object using SAML2 add-on or Web Service Federation Protocol (Ws-Fed) with Auth0 Rules along with attribute mapping, you will need to update your configuration to adjust for how Auth0 evaluates conflicting claim names between these objects. There are several possible fixes:

* Make sure that the code of your Auth0 Rule always gives precedence to the content of objects set on `context.id_token`:

  ```javascript lines theme={null}
  // my_claim will be ignored, this line of code is not relevant anymore,
  // prefer setting my_claim on `context.idToken`
  user.app_metadata.my_claim = 'a value'; 

  // this version of app_metadata will take precedence over any other change 
  context.idToken.app_metadata = {
    another_claim: 'another value'
  };

  // Only `another_claim` will appear in SAML/WsFed responses
  ```

* If you are using SAML2 add-on or Web Service Federation Protocol (Ws-Fed) attribute mapping, Avoid setting `app_metadata` or `user_metadata` claims on the `context.idToken` object. Replace these claims with name-spaced claims when possible:

  ```js lines theme={null}
  context.idToken['https://mydomain.com/app_metadata'] = {
    my_claim: 'my claim'
  };
  ```

* Use a condition on the current protocol or on the current client to exclude statements setting `app_metadata` or `user_metadata` when the protocol is `samlp` or `wsfed`.

  ```js lines theme={null}
  if (!['samlp', 'wsfed'].includes(context.protocol)) {
      context.idToken.app_metadata = {
        claim_set_via_id_token: "This is a claim which was set via context.idToken"
      };
  }
  ```

### Disable legacy behavior

<Callout icon="file-lines">
  Before you disable legacy behavior, we recommend you review the list of changes and verify your applications and integrations are compatible.
</Callout>

<Warning>
  If your tenant does not have the toggle option, your tenant is not impacted and no other action is needed.
</Warning>

1. Navigate to [Auth0 Dashboard > Tenant Settings > Advanced](https://manage.auth0.com/dashboard/#/tenant/advanced) and search for **Migrations**.
2. Use the toggle to disable **Custom claims must be namespaced**.


# Migrate to Access Tokens for Account Linking
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/link-user-accounts-with-access-tokens-migration

Describes how to migrate from using ID tokens to access tokens when linking user accounts.

Previously you could use <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip> to link and unlink user accounts for some use cases. Auth0 is deprecating this functionality. You will now need to use <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip> in all cases.

<Warning>
  This deprecation is in response to a potential security vulnerability. Auth0 strongly recommends that you update your code as soon as possible.
</Warning>

## Features affected

The changes in account linking are:

* You can no longer use an ID token at the `Authorization` header, an access token must be used instead.
* If you use an access token at the `Authorization` header with `update:users` as the granted permission, then you can send as the request's body either the `user_id` or the ID Token of the secondary account.
* If you use an access token at the `Authorization` header with `update:current_user_metadata` as the granted permission, then you can only send the ID token of the secondary account in the request's body.
* If you send the ID token of the secondary account in the request's body (the use cases described in the previous two bullets) then the following must apply:

  * The ID token must be signed using `RS256` (you can set this value at **Dashboard > Clients > Client Settings > Advanced Settings > OAuth**.
  * The claim `aud` of the ID Token, must identify the client and be the same value with the `azp` claim of the access token.
* For unlinking accounts, you can no longer use an ID token at the `Authorization` header. You must use an access token instead.

There are several ways you can link and unlink accounts. In the following list you can see the use cases and how the changes affect them.

<table>
  <thead>
    <tr>
      <th>Use Case</th>
      <th>Status</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Use the Management API <code>POST /api/v2/users//identities</code> endpoint and send the primary account's ID token in the <code>Authorization</code> header.</td>
      <td>Affected</td>
    </tr>

    <tr>
      <td>Use the Management API <code>POST /api/v2/users//identities</code> endpoint and send an access token (with scope <code>update:users</code>) in the <code>authorization</code> header, and the secondary account's <code>user\_id</code> in the payload.</td>
      <td>Not affected</td>
    </tr>

    <tr>
      <td>Use the Management API <code>POST /api/v2/users//identities</code> endpoint and send an access token (with scope <code>update:current\_user\_identities</code>) in the <code>Authorization</code> header, and the secondary account's <code>user\_id</code> in the payload.</td>
      <td>Affected</td>
    </tr>

    <tr>
      <td>Use the Management API <code>POST /api/v2/users//identities</code> endpoint and send an access token in the <code>Authorization</code> header and the secondary account's ID token in the payload.</td>
      <td>New use case</td>
    </tr>

    <tr>
      <td>Use the auth0.js library and the primary account's ID token to instantiate <code>auth0.Management</code>.</td>
      <td>Affected</td>
    </tr>

    <tr>
      <td>Use the auth0.js library and an access token (with scope <code>update:users</code>) to instantiate <code>auth0.Management</code>.</td>
      <td>Not affected</td>
    </tr>

    <tr>
      <td>Use the auth0.js library and an access token (with scope <code>update:current\_user\_identities</code>) to instantiate <code>auth0.Management</code>.</td>
      <td>Affected</td>
    </tr>

    <tr>
      <td>Use the Management API <code>DELETE	/api/v2/users//identities//</code> endpoint and send the primary account's ID token in the <code>Authorization</code> header.</td>
      <td>Affected</td>
    </tr>

    <tr>
      <td>Use the Management API <code>DELETE	/api/v2/users//identities//</code> endpoint and send an access token in the <code>Authorization</code> header.</td>
      <td>Not affected</td>
    </tr>
  </tbody>
</table>

## Actions

Review all your calls to the account linking [Identities endpoint](https://auth0.com/docs/api/management/v2/#!/Users/post_identities) and update those that make use of the vulnerable flow described above. You can update your calls to either of the following:

* **Client-side / user-initiated linking scenarios:** For client-side linking scenarios, make the call to the Identities endpoint using an access token with the `update:current_user_identities` scope, and provide the ID token of the secondary account in the payload (`link_with`). This ID token must be obtained through an <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip>/OIDC-conformant flow.
* **Server-side linking scenarios**:For server-side linking scenarios, make the call to Identities endpoint using an access token with the `update:users` scope and provide the `user_id` of the secondary account in the payload.

See [Link User Accounts](/docs/manage-users/user-accounts/user-account-linking/link-user-accounts) for details.

### Link user accounts

To link user accounts you can either call the [Link a User Account endpoint](https://auth0.com/docs/api/management/v2#!/Users/post_identities) of the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> or use the [Auth0.js library](/docs/libraries/auth0js).

#### Link current user accounts with the Management API

A common use case is to allow the logged in user to link their accounts using your app.

Prior to the deprecation you could use the primary user's ID token or access token (which contained the `update:current_user_identities` scope) to authenticate with the Management API and use the [Link a User Account endpoint](https://auth0.com/docs/api/management/v2#!/Users/post_identities).

Now you must get an access token (containing the `update:current_user_identities` scope) and use that to authenticate with the API and use the Link a User Account endpoint. The payload must be the ID token of the secondary user.

1. Get an access token with the `update:current_user_identities` scope as shown in the following example. The example uses the [implicit flow](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post), however, you can [get access tokens](/docs/secure/tokens/access-tokens/get-access-tokens) for any application type.

2. Using the previous method using an ID token, your code would look similar to this:

   <AuthCodeBlock />

   Using the new method using an access token, your code will look similar to this:

   <AuthCodeBlock />

3. To get an access token that can access the Management API:

   1. Set the `audience` to `https://{yourDomain}/api/v2/`.
   2. Ask for the `scope` `${scope}`.
   3. Set the `response_type` to `id_token token` so Auth0 will send both an ID token and an access token.
      If we decode the access token and review its contents we can see the following:

      <AuthCodeBlock />

      Notice that the `aud` is set to your tenant's API URI, the `scope` to `${scope}`, and the `sub` to the user ID of the logged-in user.

4. The following must apply:

   1. The secondary account's ID Token must be signed with `RS256.`
   2. The `aud` claim in the secondary account's ID token must identify the client, and hold the same value with the `azp` claim of the access token used to make the request.

5. Once you have the access token, you can use it to link user accounts. This part remains the same, nothing else changes in the request except for the value you use as `Bearer` token. The response also remains the same.

   <AuthCodeBlock />

#### Link current user accounts with auth0.js

If you use [auth0.js library](/docs/libraries/auth0js) to access the Management API and link accounts, then you probably use the ID token of the user's primary identity to instantiate `auth0.Management` and use it to link accounts.

1. Get an access token with the `update:current_user_identities` scope, then use this token to instantiate `auth0.Management`. The final call to `linkUser` remains the same.
2. Using the previous method using an ID token, your code would look similar to this:

   <AuthCodeBlock />

   Using the new method using an access token, your code will look similar to this:

   <AuthCodeBlock />

   1. Asks for both an Id token and an access token in response (`` responseType: `token id_token` ``).
   2. Sets the Management API as the intended audience of the token (`` audience: `https://YOUR_DOMAIN/api/v2/` ``).
   3. Asks for the required permission (`` scope: `update:current_user_identities` ``).
   4. Authenticates with the Management API using the access token.

#### Link any user account with the Management API

If you get an access token for account linking that contains the `update:users` scope, and send the secondary account's `user_id` and `provider` in the request, then you don't have to make any changes.

However, this new method introduces an alternative to this. You still use an access token that contains the `update:users` scope to authenticate with the API, but in the request's payload you can send the secondary's account ID token (instead of `user_id` and `provider`).

<AuthCodeGroup>
  ```bash cURL lines theme={null}
  curl --request POST \
    --url 'https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities' \
    --header 'authorization: Bearer ACCESS_TOKEN' \
    --header 'content-type: application/json' \
    --data '{"link_with":"SECONDARY_ACCOUNT_ID_TOKEN"}'
  ```

  ```csharp C# lines theme={null}
  var client = new RestClient("https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities");
  var request = new RestRequest(Method.POST);
  request.AddHeader("authorization", "Bearer ACCESS_TOKEN");
  request.AddHeader("content-type", "application/json");
  request.AddParameter("application/json", "{"link_with":"SECONDARY_ACCOUNT_ID_TOKEN"}", ParameterType.RequestBody);
  IRestResponse response = client.Execute(request);
  ```

  ```go Go lines theme={null}
  package main

  import (
  	"fmt"
  	"strings"
  	"net/http"
  	"io/ioutil"
  )

  func main() {

  	url := "https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities"

  	payload := strings.NewReader("{"link_with":"SECONDARY_ACCOUNT_ID_TOKEN"}")

  	req, _ := http.NewRequest("POST", url, payload)

  	req.Header.Add("authorization", "Bearer ACCESS_TOKEN")
  	req.Header.Add("content-type", "application/json")

  	res, _ := http.DefaultClient.Do(req)

  	defer res.Body.Close()
  	body, _ := ioutil.ReadAll(res.Body)

  	fmt.Println(res)
  	fmt.Println(string(body))

  }
  ```

  ```java Java lines theme={null}
  HttpResponse<String> response = Unirest.post("https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities")
    .header("authorization", "Bearer ACCESS_TOKEN")
    .header("content-type", "application/json")
    .body("{"link_with":"SECONDARY_ACCOUNT_ID_TOKEN"}")
    .asString();
  ```

  ```javascript Node.JS lines theme={null}
  var axios = require("axios").default;

  var options = {
    method: 'POST',
    url: 'https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities',
    headers: {authorization: 'Bearer ACCESS_TOKEN', 'content-type': 'application/json'},
    data: {link_with: 'SECONDARY_ACCOUNT_ID_TOKEN'}
  };

  axios.request(options).then(function (response) {
    console.log(response.data);
  }).catch(function (error) {
    console.error(error);
  });
  ```

  ```objc Obj-C lines theme={null}
  #import <Foundation/Foundation.h>

  NSDictionary *headers = @{ @"authorization": @"Bearer ACCESS_TOKEN",
                             @"content-type": @"application/json" };
  NSDictionary *parameters = @{ @"link_with": @"SECONDARY_ACCOUNT_ID_TOKEN" };

  NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities"]
                                                         cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                     timeoutInterval:10.0];
  [request setHTTPMethod:@"POST"];
  [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];
  ```

  ```php PHP lines theme={null}
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{"link_with":"SECONDARY_ACCOUNT_ID_TOKEN"}",
    CURLOPT_HTTPHEADER => [
      "authorization: Bearer ACCESS_TOKEN",
      "content-type: application/json"
    ],
  ]);

  $response = curl_exec($curl);
  $err = curl_error($curl);

  curl_close($curl);

  if ($err) {
    echo "cURL Error #:" . $err;
  } else {
    echo $response;
  }
  ```

  ```python Python lines theme={null}
  import http.client

  conn = http.client.HTTPSConnection("")

  payload = "{"link_with":"SECONDARY_ACCOUNT_ID_TOKEN"}"

  headers = {
      'authorization': "Bearer ACCESS_TOKEN",
      'content-type': "application/json"
      }

  conn.request("POST", "/{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities", payload, headers)

  res = conn.getresponse()
  data = res.read()

  print(data.decode("utf-8"))
  ```

  ```ruby Ruby lines theme={null}
  require 'uri'
  require 'net/http'
  require 'openssl'

  url = URI("https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities")

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE

  request = Net::HTTP::Post.new(url)
  request["authorization"] = 'Bearer ACCESS_TOKEN'
  request["content-type"] = 'application/json'
  request.body = "{"link_with":"SECONDARY_ACCOUNT_ID_TOKEN"}"

  response = http.request(request)
  puts response.read_body
  ```

  ```swift Swift lines theme={null}
  import Foundation

  let headers = [
    "authorization": "Bearer ACCESS_TOKEN",
    "content-type": "application/json"
  ]
  let parameters = ["link_with": "SECONDARY_ACCOUNT_ID_TOKEN"] as [String : Any]

  let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

  let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/api/v2/users/PRIMARY_ACCOUNT_USER_ID/identities")! as URL,
                                          cachePolicy: .useProtocolCachePolicy,
                                      timeoutInterval: 10.0)
  request.httpMethod = "POST"
  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()
  ```
</AuthCodeGroup>

The following must apply:

* The secondary account's ID token must be signed with `RS256`.
* The `aud` claim in the secondary account's ID token must identify the client, and hold the same value with the `azp` claim of the access token used to make the request.

### Unlink user accounts

If you use ID tokens to unlink accounts then you must update your code to use access tokens.

1. First, you must get an access token with the `update:current_user_identities` scope.

2. Using the previous method using an ID token, your code would look similar to this:

   <AuthCodeBlock />

   Using the new method using an access token, your code will look similar to this:

   <AuthCodeBlock />

3. To get an access token that can access the Management API:

   1. Set the `audience` to `https://{yourDomain}/api/v2/`.
   2. Ask for the `scope` `${scope}`.
   3. Set the `response_type` to `id_token token` so Auth0 will send both an ID token and an access token.
      If we decode the access token and review its contents we can see the following:

      <AuthCodeBlock />

      Notice that the `aud` is set to your tenant's API URI, the `scope` to `update:current_user_identities`, and the `sub` to the user ID of the logged in user.

4. Once you have the access token, you can call the [Unlink a user identity endpoint](https://auth0.com/docs/api/management/v2#!/Users/delete_user_identity_by_user_id) of the Management API, using it in the `Authorization` header.

5. Using the previous method, your call would look similar to this:

   ```http lines theme={null}
   DELETE https://YOUR_DOMAIN/api/v2/users/{primaryAccountUserId}/identities/{secondaryAccountProvider}/{secondaryAccountUserId}
       Authorization: 'Bearer {yourIdTokenOrMgmtApiAccessToken}'
   ```

   Using the new method, your call will look similar to this:

   <AuthCodeBlock />

## Security considerations

We have identified a weakness in a particular account linking flow that could allow it to be misused in specific circumstances. We have found no evidence that this has been used maliciously but have decided to deprecate the flow to prevent that ever happening.

Therefore, Auth0 requires customers using the affected account linking flow to migrate to a more secure implementation before 19 October 2018. Migration paths are provided in this guide, which should not result in any lost functionality.

On or after 19 October 2018 the affected account linking flow will be disabled and you will experience run-time errors.

You are impacted if you call the [Post Identities endpoint](https://auth0.com/docs/api/management/v2#!/Users/post_identities) using a token (ID or access token) with the scope `update:current_user_identities` in the Authorization header and include the secondary account's `user_id` in the payload. No other use cases are impacted.

## Learn more

* [Migrate to Management API Endpoints with Access Tokens](/docs/troubleshoot/product-lifecycle/past-migrations/migrate-to-calling-api-with-access-tokens)


# Migrate from edge.js extensibility features
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/migrate-from-edge-js-extensibility-features

Get started using Auth0. Implement authentication for any kind of application in minutes.

As of June 21, 2023, Auth0 will no longer support .NET and C# Node.js Extensibility features.

## Affected workflows

Review your Extensibility features for code that contains `require(edge)`.

Review the following flows or features that allow extensibility code for references to `edge.js`:

* [Hooks](/docs/customize/hooks)
* [Rules](/docs/customize/rules)
* [Custom Database Scripts](/docs/authenticate/database-connections/custom-db/create-db-connection#create-database-action-scripts)
* [Custom Social Connections](/docs/authenticate/identity-providers/social-identity-providers/oauth2)

## Recommended updates

There is no official planned replacement for this feature.

One path for migration is to replace the `edge` logic to a separate service within your own infrastructure. After you create the service in your infrastructure, you can use an Extensibility function to make an HTTP request to trigger the required operation.

For example, in a Custom Database Login script using `edge`, remove the function that calls `edge` with a generic HTTP client to capture the response.

Another path for migration is to rewrite the Extensibility feature in JavaScript instead of .NET/C#.

For more information on creating Actions or migrating to Actions, [review the Auth0 documentation](/docs/customize/actions).


# Migrate from Log Extensions
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/migrate-from-log-extensions

Migrate from log extensions to log streams or Auth0 Marketplace integrations.

The following Auth0 Log Extensions are now deprecated and will be supported until the end of life (EOL) dates listed below. It is no longer possible to create new extensions from this list of deprecated Log Extensions. You can set up equivalent functionality using log event streams or integrations on the [Auth0 Marketplace](https://marketplace.auth0.com/)

The following will reach EOL in Private Cloud on **January 6, 2023**:

* Auth0 Authentication API Webhooks
* Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> Webhooks
* Logs to Cloudwatch
* Logs to Logentries
* Logs to Loggly
* Logs to Logstash
* Logs to Papertrail
* Logs to Splunk
* Logs to Sumo Logic

Reach EOL in Public Cloud on **May 2, 2023**:

* Auth0 Authentication API Webhooks
* Auth0 Management API Webhooks
* Logs to Cloudwatch
* Logs to Logentries
* Logs to Loggly
* Logs to Logstash
* Logs to Papertrail
* Logs to Splunk
* Logs to Sumo Logic
* Logs to Segment
* Logs to Mixpanel
* Logs to AppInsights
* Logs to Azure Blob Storage

As of the EOL dates listed, Auth0 will no longer support the installed log extensions from the list above. On this page, you'll find instructions for migrating from specific log extensions.

## Auth0 Authentication API Webhooks

Make sure your destination can handle an array of log objects.

1. [Login to your Auth0 Dashboard](https://manage.auth0.com/).
2. Go to **Extensions** and select your **Auth0 Authentication API webhook** in the **Installed Extensions** tab.
3. Copy the **Webhook URL** and **Authorization Header** (if you have one).
4. Next, go to **Monitoring > Streams > New Event Stream**.
5. Select [**Custom Webhook**](/docs/customize/log-streams/custom-log-streams), enter a name, and click **Create**.
6. Configure your webhook.

   * For the **Payload URL**, enter the webhook URL you copied from the extension.
   * If you have one, set the **Authorization Token** to the Authorization Header you copied from the extension.
   * Set **Content Format** to JSON Array.
7. Click **Save**.
8. Go back to **Extensions > Installed Extensions** and disable your **Auth0 Authentication API webhooks** extension.

## Auth0 Management API Webhooks

Make sure your destination can handle an array of log objects.

1. [Login to your Auth0 Dashboard](https://manage.auth0.com/).
2. Go to **Extensions** and select your **Auth0 Management API webhook** in the **Installed Extensions** tab.
3. Copy the **Webhook URL** and **Authorization Header** (if you have one).
4. Go to **Monitoring > Streams > New Event Stream**.
5. Select [**Custom Webhook**](/docs/customize/log-streams/custom-log-streams), enter a name, and click **Create**.
6. Configure your webhook.

   * For the **Payload URL**, enter the webhook URL you copied from the extension.
   * If you have one, set the **Authorization Token** to the Authorization Header you copied from the extension.
   * Set **Content Format** to JSON Array.
7. Click **Save**.
8. Go back to **Extensions > Installed Extensions** and disable your **Auth0 Management API webhooks** extension.

## CloudWatch

Set up the [Amazon EventBridge Integration](https://marketplace.auth0.com/integrations/amazon-log-streaming) available on the Auth0 Marketplace. Once the events are available on your event bus, [create rules](https://docs.aws.amazon.com/eventbridge/latest/userguide/create-event-bus.html) to map those events to AWS CloudWatch. Make sure you disable your Auth0 Logs to CloudWatch extension:

1. [Login to your Auth0 Dashboard](https://manage.auth0.com/).
2. Go to **Extensions > Installed Extensions**.
3. Disable the **Auth0 Logs to CloudWatch** extension.

## Loggly

1. [Login to your Loggly account](https://www.loggly.com/login/).
2. Open the **Logs** menu and select **Source Setup**.
3. Go to the **Customer Tokens** tab.
4. Copy your token.
5. [Login to your Auth0 Dashboard](https://manage.auth0.com/).
6. Go to **Monitoring > Streams > New Event Stream**.
7. Select [**Custom Webhook**](/docs/customize/log-streams/custom-log-streams), enter a name and click **Create**.
8. Configure your webhook.

   * For the **Payload URL**, replace `LOGGLY_TOKEN` with the token you copied from your Loggly account: `https://logs-01.loggly.com/bulk/{LOGGLY_TOKEN}/tag/auth0-{TENANT_NAME}/`.
   * Leave **Authorization Token** blank.
   * Set the **Content Type** to `application/json`.
   * Set **Content Format** to JSON Lines.
9. Click **Save**.
10. Go to **Extensions > Installed Extensions** and disable your **Auth0 Logs to Loggly** extension.

## Logstash

1. [Login to your Auth0 Dashboard](https://manage.auth0.com/).
2. Go to **Monitoring > Streams > New Event Stream**.
3. Select [**Custom Webhook**](/docs/customize/log-streams/custom-log-streams), enter a name, and click **Create**.
4. Configure your webhook.

   * For the **Payload URL**, enter the URL of your Logstash server.
   * Set the **Authorization Token** to `Basic <CREDENTIALS>`, replacing `CREDENTIALS` with the Base64 encoding of your Logstash user and password separated by a colon (`<USER:PASSWORD>`). You can find your Logstash HTTP credentials in your Logstash configuration file.
5. Click **Save**.
6. Go to **Extensions > Installed Extensions** and disable your **Auth0 Logs to Logstash** extension.

## Papertrail

1. Login to Papertrail.
2. Go to [Log Destinations](https://papertrailapp.com/account/destinations) then click [Create Log Destination](https://papertrailapp.com/destinations/new).
3. Provide a description and configure the destination settings.
4. In the **Accept Connections via ...** pane, select **Token**.
5. Click **Create**.
6. [Login to your Auth0 Dashboard](https://manage.auth0.com/).
7. Go to **Monitoring > Streams > New Event Stream**.
8. Select [**Custom Webhook**](/docs/customize/log-streams/custom-log-streams), enter a name, and click **Create**.
9. Configure your webhook.

   * Set the **Payload URL** to `https://logs.collector.solarwinds.com/v1/logs`.
   * Set the **Authorization Token** to `Basic <CREDENTIALS>`, replacing `CREDENTIALS` with the Base64 encoding of the Papertrail token you got from Papertrail's destination settings.
   * Set **Content Format** to JSON Lines.
10. Click **Save**.
11. Go to **Extensions > Installed Extensions** and disable your **Auth0 Logs to Papertrail** extension.

## Splunk

Use the [Splunk Integration](https://marketplace.auth0.com/integrations/splunk-log-streaming) available on the Auth0 Marketplace. Make sure you disable your Auth0 Logs to Splunk extension:

1. [Login to your Auth0 Dashboard](https://manage.auth0.com/).
2. Go to **Extensions > Installed Extensions**.
3. Disable the **Auth0 Logs to Splunk** extension.

## Sumo Logic

Use the [Sumo Logic Integration](https://marketplace.auth0.com/integrations/sumo-logic-log-streaming) available on the Auth0 Marketplace. Make sure you disable your Auth0 Logs to Sumo Logic extension:

1. [Login to your Auth0 Dashboard](https://manage.auth0.com/).
2. Go to **Extensions > Installed Extensions**.
3. Disable the **Auth0 Logs to Sumo Logic** extension.

## Logentries

Currently, there are no instructions for migrating from the Logs to Logentries extension to log streams.

## Segment

1. Login to your Auth0 dashboard
2. Within **Extensions > Installed Extensions**, find your Segment extension.
3. Take note of your **Write Key**, as you’ll need it for your new log stream to Segment.
4. Disable your Segment extension.
5. Take note of the UTC timestamp of the last log you have received in Segment. Knowing that timestamp will allow you to create your new stream while avoiding duplicate logs in Segment.
6. Go to **Monitoring > Log Streams**, and create a new Segment log stream. Enter your **Write Key** in the appropriate field and the timestamp you noted in the **Start From** section.
7. Create the stream

## Mixpanel

1. Login to your Mixpanel account, open your **Project Settings**. Take note of your **Project ID** and **Data Residency** (the region).
2. Mixpanel no longer recommends using your project token for importing events and recommends using the service account mechanism. Within the **Project Settings** page, select **Service Accounts**, and create a new service account with admin or owner permissions. Take note of the credentials.
3. Log in to your Auth0 dashboard.
4. In **Monitoring > Log Streams**, create a new Mixpanel stream. Enter the project id, region, service account credentials and create the stream.
5. Don’t forget to deactivate your old extension. Go to **Extensions > Installed Extensions** and disable the **Auth0 Logs to Mixpanel extension**.

## AppInsights

1. Set up an [Azure EventGrid Log Stream](https://marketplace.auth0.com/integrations/azure-log-streaming) or leverage your existing EventGrid stream.
2. Follow the [instructions posted by Azure](https://urldefense.com/v3/__https://learn.microsoft.com/en-us/azure/event-grid/auth0-log-stream-app-insights__;!!PwKahg!9T9C3qhBRgQQHChQkQqnmHDDnX99yWJ4W8F4rLVs6qrwwbnFCY3JcCfF486d1DLqRFEghVnJZ9gJnronDv0\$) to set a destination for the log events.
3. Logs may be transformed differently through Log Streaming. Please reference the deprecated [Log Extenstion code](https://github.com/auth0-extensions/auth0-logs-to-provider/blob/master/server/lib/senders/appinsights.js) for further details

Notable transformations done to the logs include:

* The appInsight client is overwritten:

  * Sets a custom time equivalent to the log time
  * OS and OS version to be equivalent to the log information
  * Device type tag to hold information on whether the log originated from a mobile source
  * IP address tag be equivalent to the log information
  * user id, account id, user agent and auth user id tags to be equivalent to the logs
* The record is cleaned up to delete the following properties if empty:

  * ip
  * user\_id
  * user\_name
  * connection
  * client\_name
  * description
* The record isMobile property is altered to contain either a yes or no string
* The record details property is altered to be a string
* The record details property is truncated to 8185 characters

## Azure Blob Storage

1. Set up an [Azure EventGrid Log Stream](https://marketplace.auth0.com/integrations/azure-log-streaming) or leverage your existing EventGrid stream.
2. Follow the [instructions posted by Azure](https://urldefense.com/v3/__https://learn.microsoft.com/en-us/azure/event-grid/auth0-log-stream-blob-storage__;!!PwKahg!9T9C3qhBRgQQHChQkQqnmHDDnX99yWJ4W8F4rLVs6qrwwbnFCY3JcCfF486d1DLqRFEghVnJZ9gJ5k9lKMM\$) to set a destination for the log events.
3. Logs may be transformed differently through Log Streaming. Please reference the deprecated [Log Extenstion code](https://github.com/auth0-extensions/auth0-logs-to-provider/blob/master/server/lib/senders/blobstorage.js) for further details

Notable transformations done to the logs include:

* The record `type_code` and `type` is adjusted. `Type` is the human-readable description of the `type_code`
* Record `os`, `os_version`, `device` and `device_version` is adjusted if the record contains `user_agent` information


# Migrate from oracledb extensibility features
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/migrate-from-oracledb-extensibility-features

Get started using Auth0. Implement authentication for any kind of application in minutes.

As of June 21, 2023, Auth0 will no longer support connecting to Oracle Databases from Node.js in Extensibility features. Auth0 previously supported connecting to Oracle Databases via the `oracledb` Node.js module.

## Affected workflows

Review your Extensibility features for code that contains `require(oracledb)` or  `require('oracledb@4.2.0')`.

Review the following flows or features that allow extensibility code for references to [oracledb](https://www.npmjs.com/package/oracledb):

* [Hooks](/docs/customize/hooks)
* [Rules](/docs/customize/rules)
* [Custom Database Scripts](/docs/authenticate/database-connections/custom-db/create-db-connection#create-database-action-scripts)
* [Custom Social Connections](/docs/authenticate/identity-providers/social-identity-providers/oauth2)

## Recommended updates

There is no official planned replacement for this feature. Auth0 recommends replacing the `oracledb` logic to a separate service within your own infrastructure. After you create the service in your infrastructure, you can use an Extensibility function to make an HTTP request to trigger the Oracle Database logic.

To learn more about how to implement the `oracledb` module in your own infrastructure, review the [OracleDB Quickstart guide](https://node-oracledb.readthedocs.io/en/latest/user_guide/installation.html#quickstart).

For example, in a Custom Database Login script using `oracledb`, remove the function that calls `oracledb` with a generic HTTP client to capture the response.

For more information on creating Actions or migrating to Actions, [review the Auth0 documentation](/docs/customize/actions).


# Migrate from Node 12 and 16 to Node 18
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/migrate-nodejs-16-to-nodejs-18

Describes Auth0 Actions items affected by the Node.js v12+6 to Node.js v18 migration.

Long-term support (LTS) for Node.js 12 and 16 ended in 2023, which means the Node.js development team no longer back-ports critical security fixes to these versions. Running with Node 12 or 16 runtimes could expose your extensibility code to security vulnerabilities.

Node 18 extensibility runtime is generally available (GA) across our entire suite of extensibility offerings. This includes Actions, Rules, Hooks, Database Scripts, and Custom Social Connections. We strongly encourage everyone to update to Node 18 as soon as possible to adhere to best code security practices.

## General considerations

### Migrate Rules and Hooks to Actions

If you are using a discontinued extensibility runtime, we recommend taking the review of your Rules and Hooks implementation as an opportunity for migrating them to (Node 18) Actions. Determine which Rules and Hooks you can migrate to Actions by visiting [Actions Limitations](/docs/customize/actions/limitations). To learn more about migrating your Rules and Hooks to Actions, see [Migrate to Actions](/docs/customize/actions/migrate).

### Marketplace integrations

#### Social Connections Integrations

Use the [Management API](https://auth0.com/docs/api/management/v2) to identify a complete list of social connections that a Node runtime version change may impact. In particular, all potentially impacted social connections, either explicitly created as a custom social connection or initially added through the Marketplace, have the `strategy` attribute with a value of either `oauth1` or `oauth2`.

You can then paginate through all the existing custom social connections in a given tenant using the `GET` connections <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> endpoint. For example, the following query options returns the names and identifiers of up to 100 custom social connections:

```http wrap lines theme={null}
/api/v2/connections?strategy=oauth1&strategy=oauth2&include_totals=true&fields=name&per_page=100
```

The <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> does not allow updating the scripts for custom social connections added through the Marketplace. If a script change is required to be compatible with Node 18, you must use the Management API.

## Migration tasks

### Create new custom Actions

To create a new custom Action with Node 18 through the Auth0 Dashboard:

1. Navigate to [Auth0 Dashboard > Actions > Library](https://manage.auth0.com/#/dashboard/actions/library).
2. Select **Create Action > Build from scratch**.
3. In the **Runtime\*** field, select **Node 18 (Recommended)**.
4. Write your custom Actions in Node 18, test, and deploy when ready.

### Upgrade existing custom Actions

You can individually upgrade existing custom Actions built on Node 12 or 16 to Node 18 and [revert to the previous version](/docs/customize/actions/manage-versions#revert-actions) using the older runtime. Upgrade Actions to Node 18 by creating and deploying a new version of the existing implementation with any required changes and set to use Node 18 as the runtime.

### Choose Node 18 for other extensibility products

The runtime used for the remaining (non-Actions) extensibility offerings is defined globally at the tenant's advanced settings level. Changing this setting impacts the following functionality at the same time:

* rules
* hooks
* custom database scripts
* custom social connection scripts

To change the tenant extensibility runtime setting in the Auth0 Dashboard:

1. Navigate to **Dashboard > Settings > Advanced**.
2. Scroll to the **Extensibility** section.
3. For **Runtime**, select **Node 18**.

Given that this is a global setting that impacts multiple extensibility features simultaneously, we recommend that you perform this step in your development tenant first, complete testing of all applicable extensibility features, and proceed to your production tenant only when you see no issues in development.

Specifically for Custom DB scripts you can [follow the steps as explained on this page](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/environment) to individually verify a script against a specific runtime version before proceeding to change the global runtime version.

## Known breaking changes

### Magic npm modules

The Node 12 extensibility runtime supports using specific `npm` modules without explicitly requiring them in the extensibility code. Starting with Node 16 runtime, we removed support for this type of usage for the following modules:

* \_
* async
* Auth0
* azure\_storage
* bcrypt
* crypto
* couchbase
* cql
* ip
* <Tooltip href="/docs/glossary?term=jwt">jwt</Tooltip>
* Knex
* mongo
* mysql
* mysql\_pool
* ObjectID
* pbkdf2
* pg
* postgres
* Pubnub
* q
* querystring
* sqlserver
* uuid
* xml2js
* xmldom
* xpath
* xtend

If you still have extensibility running on Node 12, consider the above when updating the code directly to Node 18. Before using a module, you must ensure that it is explicitly required.

In the context of Rules, Custom Database Connections, and Custom Social Connections, you must explicitly require a version of the module that is [listed as available for Node 18](https://auth0-extensions.github.io/canirequire/).

In Hooks and Actions, you must add the intended target version as an explicit dependency before requiring the module.

### Can I Require module versions removed

We removed support for the specified versions of the modules listed below for the Node 18 runtime from [Can I Require](https://auth0-extensions.github.io/canirequire/). This change impacts the extensibility code associated with Rules, Custom Database Connection Scripts, and Custom Social Connection Scripts.

<Warning>
  The fetch user profile script for the following custom social connections ([Indeed](https://marketplace.auth0.com/integrations/indeed-social-connection), [monday.com](https://marketplace.auth0.com/integrations/monday-com-monday-com-social-connection), [Snapchat](https://marketplace.auth0.com/integrations/snapchat-social-connection), and [Tumblr](https://marketplace.auth0.com/integrations/tumblr-social-connection)), available through the Marketplace, used version `0.22.0` of the `axios` module, which is not available in Node 18. If you at use one of these connections, review and update their scripts as necessary through the [Management API](https://auth0.com/docs/api/management/v2).
</Warning>

<table>
  <thead>
    <tr>
      <th>Module</th>
      <th>Versions</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>@analytics/google-analytics</td>
      <td>0.4.0</td>
    </tr>

    <tr>
      <td>@auth0/hapi</td>
      <td>13.5.1, 13.6.0</td>
    </tr>

    <tr>
      <td>@auth0/rule-utilities</td>
      <td>0.1.0</td>
    </tr>

    <tr>
      <td>@gitbeaker/node</td>
      <td>17.0.1</td>
    </tr>

    <tr>
      <td>@incognia/api</td>
      <td>1.0.0</td>
    </tr>

    <tr>
      <td>@octokit/rest</td>
      <td>15.8.2</td>
    </tr>

    <tr>
      <td>@sentry/node</td>
      <td>5.6.2, 5.15.5, 6.2.0</td>
    </tr>

    <tr>
      <td>acorn</td>
      <td>1.2.2</td>
    </tr>

    <tr>
      <td>airbrake</td>
      <td>1.0.2</td>
    </tr>

    <tr>
      <td>airgram</td>
      <td>3.1.1</td>
    </tr>

    <tr>
      <td>ajv</td>
      <td>6.10.1</td>
    </tr>

    <tr>
      <td>amazon-dax-client</td>
      <td>1.2.2</td>
    </tr>

    <tr>
      <td>amazon-mws-node</td>
      <td>1.0.3</td>
    </tr>

    <tr>
      <td>analytics</td>
      <td>0.5.1</td>
    </tr>

    <tr>
      <td>analytics-node</td>
      <td>2.0.1, 3.5.0</td>
    </tr>

    <tr>
      <td>applicationinsights</td>
      <td>0.15.8, 0.18.0, 1.5.0, 1.8.8</td>
    </tr>

    <tr>
      <td>async</td>
      <td>1.0.0, 0.9.0, 2.1.2, 2.6.1</td>
    </tr>

    <tr>
      <td>auth0</td>
      <td>2.4.0, 2.1.0, 2.0.0, 0.8.2, 2.6.0, 2.7.0, 2.8.0, 2.9.1, 2.13.0, 2.17.0, 2.17.1, 2.19.0, 2.23.0, 2.27.0, 2.27.1, 2.30.0, 2.31.0, 2.32.0, 2.34.2, 2.35.0, 2.36.1, 2.36.2, 2.39.0, 3.0.1</td>
    </tr>

    <tr>
      <td>auth0-authz-rules-api</td>
      <td>4.0.0</td>
    </tr>

    <tr>
      <td>auth0-ext-template-renderers</td>
      <td>0.4.2</td>
    </tr>

    <tr>
      <td>auth0-extension-express-tools</td>
      <td>1.0.2, 1.1.5, 1.1.6, 2.0.0</td>
    </tr>

    <tr>
      <td>auth0-extension-hapi-tools</td>
      <td>1.0.0, 1.1.0, 1.2.0, 1.2.1, 1.2.2, 1.3.0</td>
    </tr>

    <tr>
      <td>auth0-extension-tools</td>
      <td>1.0.0, 1.2.1, 1.3.1, 1.3.2, 1.4.0</td>
    </tr>

    <tr>
      <td>auth0-magic</td>
      <td>3.1.0</td>
    </tr>

    <tr>
      <td>auth0-oauth2-express</td>
      <td>0.0.1, 0.0.3, 1.1.5</td>
    </tr>

    <tr>
      <td>auth0-source-control-extension-tools</td>
      <td>3.0.10, 3.0.9, 3.1.4, 3.4.0, 3.5.1, 4.0.3, 4.0.5, 4.0.6, 4.0.7, 4.1.1, 4.1.2, 4.1.3, 4.1.5, 4.1.7, 4.1.9</td>
    </tr>

    <tr>
      <td>aws-sdk</td>
      <td>2.2.30, 2.1.31, 2.1.13, 2.4.13, 2.5.3, 2.197.0, 2.291.0, 2.458.0, 2.593.0</td>
    </tr>

    <tr>
      <td>axios</td>
      <td>0.15.2, 0.18.0, 0.19.2, 0.21.1, 0.21.3, 0.22.0, 0.27.2</td>
    </tr>

    <tr>
      <td>azure</td>
      <td>0.10.6</td>
    </tr>

    <tr>
      <td>azure-storage</td>
      <td>0.4.4, 0.4.1, 0.9.0</td>
    </tr>

    <tr>
      <td>babel</td>
      <td>5.4.7, 5.1.9</td>
    </tr>

    <tr>
      <td>bcrypt</td>
      <td>4.0.0</td>
    </tr>

    <tr>
      <td>bluebird</td>
      <td>2.9.26, 3.4.6</td>
    </tr>

    <tr>
      <td>body-parser</td>
      <td>1.12.4</td>
    </tr>

    <tr>
      <td>boom</td>
      <td>2.7.2</td>
    </tr>

    <tr>
      <td>botbuilder</td>
      <td>0.9.0</td>
    </tr>

    <tr>
      <td>bson</td>
      <td>0.3.2, 4.4.0</td>
    </tr>

    <tr>
      <td>cookie-parser</td>
      <td>1.3.5</td>
    </tr>

    <tr>
      <td>datadog-metrics</td>
      <td>0.8.2, 0.9.0, 0.9.2, 0.9.3</td>
    </tr>

    <tr>
      <td>disposable-email-domains</td>
      <td>1.0.14, 1.0.15, 1.0.56</td>
    </tr>

    <tr>
      <td>dockerode</td>
      <td>2.1.4, 2.0.3</td>
    </tr>

    <tr>
      <td>dotenv</td>
      <td>0.4.0, 2.0.0</td>
    </tr>

    <tr>
      <td>easy-pbkdf2</td>
      <td>0.0.2</td>
    </tr>

    <tr>
      <td>ejs</td>
      <td>2.3.1</td>
    </tr>

    <tr>
      <td>engine.io-client</td>
      <td>1.5.1</td>
    </tr>

    <tr>
      <td>express</td>
      <td>4.12.4, 4.14.0, 4.16.3</td>
    </tr>

    <tr>
      <td>express-jwt</td>
      <td>3.1.0, 5.1.0</td>
    </tr>

    <tr>
      <td>faunadb</td>
      <td>2.11.1, 4.1.1</td>
    </tr>

    <tr>
      <td>filter-object</td>
      <td>2.1.0</td>
    </tr>

    <tr>
      <td>firebase</td>
      <td>7.12.0</td>
    </tr>

    <tr>
      <td>firebase-admin</td>
      <td>4.0.4, 5.0.0, 6.0.0, 8.0.0, 8.12.1</td>
    </tr>

    <tr>
      <td>form-data</td>
      <td>0.2.0</td>
    </tr>

    <tr>
      <td>getstream</td>
      <td>3.4.1</td>
    </tr>

    <tr>
      <td>gitlab</td>
      <td>1.7.0</td>
    </tr>

    <tr>
      <td>google-auth-library</td>
      <td>1.0.0</td>
    </tr>

    <tr>
      <td>google-libphonenumber</td>
      <td>2.0.7, 3.2.8, 3.2.10</td>
    </tr>

    <tr>
      <td>googleapis</td>
      <td>2.1.6, 34.0.0</td>
    </tr>

    <tr>
      <td>got</td>
      <td>3.2.0, 9.2.1, 10.7.0, 11.3.0, 11.5.2</td>
    </tr>

    <tr>
      <td>hapi</td>
      <td>13.5.0</td>
    </tr>

    <tr>
      <td>hapi-auth-jwt2</td>
      <td>7.0.1</td>
    </tr>

    <tr>
      <td>hapi-swagger</td>
      <td>7.4.0</td>
    </tr>

    <tr>
      <td>hoek</td>
      <td>2.14.0</td>
    </tr>

    <tr>
      <td>http-proxy</td>
      <td>1.11.1</td>
    </tr>

    <tr>
      <td>ibm\_db</td>
      <td>2.6.4</td>
    </tr>

    <tr>
      <td>ip</td>
      <td>0.3.2, 0.0.1</td>
    </tr>

    <tr>
      <td>ipaddr.js</td>
      <td>1.0.1</td>
    </tr>

    <tr>
      <td>joi</td>
      <td>6.10.1</td>
    </tr>

    <tr>
      <td>jose</td>
      <td>3.19.0</td>
    </tr>

    <tr>
      <td>jsforce</td>
      <td>1.6.0</td>
    </tr>

    <tr>
      <td>jsonwebtoken</td>
      <td>5.7.0, 5.0.1, 5.0.0, 7.1.9, 8.5.0</td>
    </tr>

    <tr>
      <td>jwks-rsa</td>
      <td>1.0.0, 1.1.1, 1.6.0</td>
    </tr>

    <tr>
      <td>ldapjs</td>
      <td>1.0.0</td>
    </tr>

    <tr>
      <td>lodash</td>
      <td>3.10.1, 3.9.3, 2.4.1, 4.8.2, 4.17.10, 4.17.19</td>
    </tr>

    <tr>
      <td>lru-cache</td>
      <td>2.6.4</td>
    </tr>

    <tr>
      <td>mixpanel</td>
      <td>0.4.0</td>
    </tr>

    <tr>
      <td>mkdirp</td>
      <td>0.5.1</td>
    </tr>

    <tr>
      <td>moment</td>
      <td>2.10.3, 2.11.2</td>
    </tr>

    <tr>
      <td>mongodb</td>
      <td>2.0.48, 2.0.33, 2.0.27, 2.2.11, 3.1.4, 4.1.0, 3.6.10, 3.5.11</td>
    </tr>

    <tr>
      <td>mongoose</td>
      <td>4.1.6</td>
    </tr>

    <tr>
      <td>morgan</td>
      <td>1.5.3</td>
    </tr>

    <tr>
      <td>mysql</td>
      <td>2.7.0, 2.6.2, 2.0.0-alpha8, 2.15.0</td>
    </tr>

    <tr>
      <td>mysql2</td>
      <td>1.5.3</td>
    </tr>

    <tr>
      <td>nano</td>
      <td>6.2.0</td>
    </tr>

    <tr>
      <td>neo4j-driver</td>
      <td>1.7.1</td>
    </tr>

    <tr>
      <td>node-fetch</td>
      <td>2.6.0</td>
    </tr>

    <tr>
      <td>node-jose</td>
      <td>0.9.2</td>
    </tr>

    <tr>
      <td>node-rdkafka</td>
      <td>2.10.1</td>
    </tr>

    <tr>
      <td>nodemailer</td>
      <td>2.5.0</td>
    </tr>

    <tr>
      <td>nsp</td>
      <td>2.4.0</td>
    </tr>

    <tr>
      <td>oauth</td>
      <td>0.9.12</td>
    </tr>

    <tr>
      <td>passport-wsfed-saml2</td>
      <td>2.11.4</td>
    </tr>

    <tr>
      <td>pg</td>
      <td>4.5.7, 4.3.0, 4.1.1, 6.1.2, 7.17.1</td>
    </tr>

    <tr>
      <td>postmark</td>
      <td>1.3.1</td>
    </tr>

    <tr>
      <td>q</td>
      <td>1.0.1</td>
    </tr>

    <tr>
      <td>qs</td>
      <td>3.1.0</td>
    </tr>

    <tr>
      <td>ramda</td>
      <td>0.18.0, 0.23.0</td>
    </tr>

    <tr>
      <td>range\_check</td>
      <td>0.0.1</td>
    </tr>

    <tr>
      <td>raw-body</td>
      <td>2.1.0</td>
    </tr>

    <tr>
      <td>react</td>
      <td>15.3.2</td>
    </tr>

    <tr>
      <td>redis</td>
      <td>0.12.1</td>
    </tr>

    <tr>
      <td>request</td>
      <td>2.56.0, 2.55.0, 2.27.0, 2.67.0, 2.73.0, 2.75.0, 2.81.0, 2.83.0, 2.88.0</td>
    </tr>

    <tr>
      <td>rethinkdb</td>
      <td>2.1.1, 2.0.0-1, 2.0.0</td>
    </tr>

    <tr>
      <td>rollbar</td>
      <td>0.6.2, 2.12.2</td>
    </tr>

    <tr>
      <td>semver</td>
      <td>4.3.4</td>
    </tr>

    <tr>
      <td>sendgrid</td>
      <td>1.8.0, 3.0.7</td>
    </tr>

    <tr>
      <td>sequelize</td>
      <td>3.1.1</td>
    </tr>

    <tr>
      <td>soap</td>
      <td>0.23.0</td>
    </tr>

    <tr>
      <td>socket.io</td>
      <td>1.3.5</td>
    </tr>

    <tr>
      <td>socket.io-client</td>
      <td>1.3.5</td>
    </tr>

    <tr>
      <td>splunk-bunyan-logger</td>
      <td>0.9.1</td>
    </tr>

    <tr>
      <td>ssh2</td>
      <td>0.4.13</td>
    </tr>

    <tr>
      <td>stamplay</td>
      <td>1.0.6, 1.0.5, 1.0.3</td>
    </tr>

    <tr>
      <td>stripe</td>
      <td>3.3.4, 4.14.0, 4.24.0, 7.1.0, 7.4.0, 8.52.0</td>
    </tr>

    <tr>
      <td>sumo-logger</td>
      <td>1.5.5</td>
    </tr>

    <tr>
      <td>superagent</td>
      <td>1.2.0, 3.8.3, 4.1.0</td>
    </tr>

    <tr>
      <td>tedious</td>
      <td>6.6.2, 1.11.0, 0.1.4, 8.3.1, 9.2.1</td>
    </tr>

    <tr>
      <td>tough-cookie</td>
      <td>1.2.0</td>
    </tr>

    <tr>
      <td>twilio</td>
      <td>2.2.1, 3.6.0, 3.57.0</td>
    </tr>

    <tr>
      <td>twit</td>
      <td>1.1.20</td>
    </tr>

    <tr>
      <td>uuid</td>
      <td>2.0.3, 2.0.1, 3.1.0, 3.3.2, 7.0.3, 8.0.0</td>
    </tr>

    <tr>
      <td>vso-node-api</td>
      <td>3.1.1</td>
    </tr>

    <tr>
      <td>watson-developer-cloud</td>
      <td>2.0.1</td>
    </tr>

    <tr>
      <td>winston</td>
      <td>1.0.0, 0.8.1, 3.1.0</td>
    </tr>

    <tr>
      <td>xml2js</td>
      <td>0.4.8, 0.2.8</td>
    </tr>

    <tr>
      <td>xmlbuilder</td>
      <td>2.6.4</td>
    </tr>

    <tr>
      <td>xmldom</td>
      <td>0.1.19, 0.1.13</td>
    </tr>

    <tr>
      <td>xpath</td>
      <td>0.0.5</td>
    </tr>

    <tr>
      <td>xtend</td>
      <td>1.0.3</td>
    </tr>
  </tbody>
</table>

### Secure renegotiation required by default for TLS connections

Node.js 18 requires secure renegotiation (RFC 5746) for TLS connections by default, a consequence of the requirement being introduced in the underlying OpenSSL dependency.

If your extensibility code performs external network calls, the target servers must support secure renegotiation, or otherwise, the requests will fail, and you will receive an error similar to:

```text wrap lines theme={null}
Error: write EPROTO C0BAF076:error:0A000152:SSL routines:final_renegotiate:unsafe legacy renegotiation disabled:../deps/openssl/openssl/ssl/statem/extensions.c:922:
```

Given this security-related change, we recommend that you ensure that all target servers are updated to support secure renegotiation. If the servers in question are third-party servers that are not under your control, you can evaluate the possibility of opting into the previous behavior.

For example, for the `axios` library, the following code snippet illustrates how to opt-in to the legacy behavior:

```javascript lines theme={null}
const axios = require('axios');
const https = require('https');
const crypto = require('crypto');

axios.get(
  'https://[LEGACY_SERVER]', 
  {
    httpsAgent: new https.Agent(
      {
        secureOptions: crypto.constants.SSL_OP_LEGACY_SERVER_CONNECT
      }
    )
  })
```


# Migrate to New Tenant Member Roles
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/migrate-tenant-member-roles

Learn how to migrate to the new Dashboard tenant member roles feature.

The **Application Admin** Dashboard role will no longer be available after **01 February 2021**. That role is being replaced with the new **Editor - Specific Apps** role. Existing tenants will be able to keep the deprecated role during the grace period. Once the role reaches its end of life, any existing tenant member that has that role will be automatically reassigned to the new **Editor - Specific Apps** role. The new role provides edit access to the same set of applications but will not have permission to access connections and users.

<Card title="Availability varies by Auth0 plan">
  Both your specific login implementation and your Auth0 plan or custom agreement affect whether this feature is available. To learn more, read [Pricing](https://auth0.com/pricing).
</Card>

## What's changing

Previously, if you were a tenant administrator, you could invite additional administrators to have access to the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> and all or specific applications within that tenant. That role was called **Application Admin**. The tenant members with that role were given full access to the selected application(s) settings plus read-access to non-enterprise connections and users. After 01 February 2021, the Application Admin role as defined above will be replaced by a new set of least privileged roles.

### Why are we making this change

The new set of roles covers a wider range of use cases for Dashboard access. The Application Admin role is replaced by a similar but more restrictive **Editor - Specific Apps** role. The new role has access to the selected application(s), but not to connections and users, securing your data and complying with the least privileged principle. If you have team members who require additional access, you can grant access to connections and users by assigning them additional roles.

### Grace period and end of life

You will be able to keep the experience for existing members with the Application Admin role during the grace period but you won't be able to invite any new members with that role. Beginning on 01 February 2021 for Public Cloud tenants, and after the March 2021 release for Private Cloud tenants.

Your tenants will be affected by this deprecation if the following criteria are met:

* Created before 01 February 2021 (Public Cloud tenants) or before upgrading to the March 2021 release (Private Cloud tenants)
* Have at least one tenant member with the **Application Admin** role
* Haven't opted-in to the Dashboard roles feature preview (only applicable to Public Cloud enterprise tenants)

Beginning on 01 February 2021 for Public Cloud tenants, and after the March 2021 release for Private Cloud tenants, Auth0 will display tenant logs and a migration toggle to help you prepare for this change.

The Application Admin role will reach its end of life in the Public Cloud on 30 September 2021. Existing Application Admins will be automatically converted to the new Editor Specific Apps role at that time. For plans where the role is not available, any existing tenant member that has the Application Admin role assigned may be removed. You should migrate these members to Admins or remove them from the dashboard to prevent this situation.

The Application Admin role will be available for affected Private Cloud tenants until September 2021 monthly release which is the first release that will not include the Application Admin role.

## Actions

### Automatically assign new roles

This will convert any existing members that have the **Application Admin** role to the new **Editor - Specific Apps** role with permission to manage the same set of applications.

1. Go to [Dashboard > Tenant Settings > Tenant Members](https://manage.auth0.com/#/tenant/admins) and review which members have the **Application Admin** role assigned. (You may want to communicate to those members that their experience in the Dashboard will change: they will lose access to Users and Connections sections.)

   <Frame>
     <img alt="Dashboard - Tenant Settings - Tenant Members" />
   </Frame>
2. Go to [Dashboard > Tenant Settings > Advanced](https://manage.auth0.com/#/tenant/advanced) and under **Migrations**, turn off the **Application Admin role** migration toggle.

   This will convert any existing members that have the **Application Admin** role to the new **Editor - Specific Apps** role with permission to manage the same set of applications.
3. If your plan doesn't support the Editor roles, please refer to the [subscription page](https://manage.auth0.com/#/tenant/billing/subscription) for relevant plans to enable the feature and keep it. Otherwise, proceed to manually assign members a supported role.

### Manually assign new roles

Do the following steps to ensure the members are assigned to a role supported by your subscription.

1. Go to [Dashboard > Tenant Settings > Tenant Members](https://manage.auth0.com/#/tenant/admins) and review which members have the **Application Admin** role assigned.

   1. Go to [Dashboard > Monitoring > Logs](https://manage.auth0.com/#/logs) and see whether any of those members have used the Dashboard lately.
   2. Use the following query to search for related logs: `type:depnote AND description:*Admin*`.
2. Go back to the **Tenant Members** tab under **Tenant Settings** and either remove those members or edit their roles to assign them one or more of the new roles that are supported in your subscription plan.

## Learn more

* [Auth0 Dashboard](/docs/get-started/auth0-overview/dashboard)
* [Manage Dashboard Access](/docs/get-started/manage-dashboard-access)
* [Dashboard Access by Role](/docs/get-started/manage-dashboard-access/feature-access-by-role)
* [Add Tenant Members](/docs/get-started/manage-dashboard-access/add-dashboard-users)
* [Edit Tenant Members](/docs/get-started/manage-dashboard-access/edit-dashboard-users)


# Migrate to Management API Endpoints with Access Tokens
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/migrate-to-calling-api-with-access-tokens

Describes the deprecation of using ID tokens as credentials for the Management API and how to migrate your configuration to use access tokens.

Using <Tooltip href="/docs/glossary?term=ID+tokens">ID tokens</Tooltip> to call <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> endpoints is being deprecated. You must use <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip>. The grace period for this migration started on **March 31, 2018**.

After you complete your migration to access tokens, turn off the **Allow ID Tokens for Management API v2 Authentication** toggle in the Dashboard.

If you use ID tokens to call any of the following endpoints, then you are affected by this migration. These endpoints can now accept regular access tokens. Nothing else changes in how the endpoints work. You should expect the same request and response schemas and only need to update the token that you use for authorization.

## Endpoints affected

<table>
  <thead>
    <tr>
      <th>Endpoint</th>
      <th>Use Case</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>GET /api/v2/users/</td>
      <td>Retrieve a user's information</td>
    </tr>

    <tr>
      <td>GET /api/v2/users//enrollments</td>
      <td>Retrieve all Guardian MFA enrollments for a user</td>
    </tr>

    <tr>
      <td>PATCH /api/v2/users/</td>
      <td>Update a user's information</td>
    </tr>

    <tr>
      <td>DELETE /api/v2/users//multifactor/</td>
      <td>Delete the MFA provider settings for a user</td>
    </tr>

    <tr>
      <td>POST /api/v2/device-credentials</td>
      <td>Create a public key for a device</td>
    </tr>

    <tr>
      <td>DELETE /api/v2/device-credentials/</td>
      <td>Delete a device credential</td>
    </tr>

    <tr>
      <td>POST/api/v2/users//identities</td>
      <td>Link user accounts from various identity providers</td>
    </tr>

    <tr>
      <td>DELETE /api/v2/users//identities//</td>
      <td>Unlink user accounts</td>
    </tr>
  </tbody>
</table>

## Actions

### Scope changes

The actions you can perform with the Management API depend on the scopes that your access token contains. With this migration, you can either get a limited access token that can update only the logged-in user's data or an access token that can update the data of any user. In the following matrix, you can see the scopes that your token needs to have per case and per endpoint.

For example, if you get an access token that contains the scope `read:users`, you can retrieve the data of any user using the `GET /api/v2/users/{id}` endpoint. However, if your token contains the scope `read:current_user`, you can only retrieve the information of the currently logged-in user (the one that the token was issued for).

<table>
  <thead>
    <tr>
      <th>Endpoint</th>
      <th>Scope for current user</th>
      <th>Scope for any user</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>GET /api/v2/users/</td>
      <td><code>read:current\_user</code></td>
      <td><code>read:users</code></td>
    </tr>

    <tr>
      <td>GET /api/v2/users//enrollments</td>
      <td><code>read:current\_user</code></td>
      <td><code>read:users</code></td>
    </tr>

    <tr>
      <td>POST/api/v2/users//identities</td>
      <td><code>update:current\_user\_identities</code></td>
      <td><code>update:users</code></td>
    </tr>

    <tr>
      <td>DELETE /api/v2/users//identities//</td>
      <td><code>update:current\_user\_identities</code></td>
      <td><code>update:users</code></td>
    </tr>

    <tr>
      <td>PATCH /api/v2/users/</td>
      <td><code>update:current\_user\_metadata</code></td>
      <td><code>update:users</code></td>
    </tr>

    <tr>
      <td>PATCH /api/v2/users/</td>
      <td><code>create:current\_user\_metadata</code></td>
      <td><code>update:users</code></td>
    </tr>

    <tr>
      <td>DELETE /api/v2/users//multifactor/</td>
      <td><code>delete:current\_user\_metadata</code></td>
      <td><code>update:users</code></td>
    </tr>

    <tr>
      <td>POST /api/v2/device-credentials</td>
      <td><code>create:current\_user\_device\_credentials</code></td>
      <td><code>create:device\_credentials</code></td>
    </tr>

    <tr>
      <td>DELETE /api/v2/device-credentials/</td>
      <td><code>delete:current\_user\_device\_credentials</code></td>
      <td><code>delete:device\_credentials</code></td>
    </tr>
  </tbody>
</table>

### Get access tokens

Auth0 has changed how you get a token for the previously mentioned endpoints. There are several variations on how you authenticate a user and get tokens, depending on the technology and the <Tooltip href="/docs/glossary?term=OAuth+2.0">OAuth 2.0</Tooltip> flow you use to authenticate:

* **SPA running in a browser**: Use the Authorization endpoint.
* **Web app running on a server, a mobile app, a server process, or a highly trusted app**: Use the <Tooltip href="/docs/glossary?term=Token+endpoint">Token endpoint</Tooltip>.
* **Cross-authentication**: Use embedded Lock or auth0.js to authenticate users when the requests come from different domains.

#### Authorization endpoint

In this section, we will use an example to show the differences in how you get a token with the Authorization endpoint. Keep in mind that no matter which endpoint you want to migrate, the changes are the same, the only thing that differs is the scopes that you specify in the request.

In the example below, you use the `GET User by ID` endpoint to retrieve the full profile information of the logged-in user. To do so, first, we will authenticate the user using the Implicit grant and retrieve the token(s). Below you can see an implementation of the old approach that gets an ID Token and then uses it to call the endpoint.

<AuthCodeBlock />

In the example below, you can see the new approach that gets an access token.

<AuthCodeBlock />

To get an access token that can access the Management API:

* Set the `audience` to `https://{yourDomain}/api/v2/`
* Ask for the scope `${scope}`
* Set the `response_type` to `id_token token` so Auth0 will send both an ID token and an access token

If you decode the received access token and review its contents you will see the following:

<AuthCodeBlock />

Notice that `aud` is set to your tenant's API URI, `scope` is set to `${scope}`, and `sub` is set to the user ID of the logged-in user.

Once you have the access token you can use it to call the endpoint. This part remains the same, nothing else changes in the request except for the value you use as `Bearer` token. The response remains also the same.

#### Token endpoint

In this section, we will use an example to show the differences in how you get a token with the Token endpoint. Keep in mind though that no matter which endpoint you want to migrate, the changes are the same, the only thing that differs is the scopes that you specify in the request.

In the example below, you want to use the `GET User by ID` endpoint to retrieve the full profile information of the logged-in user. First, authenticate the user using the Password Exchange grant and then retrieve the token(s). Below you can see an implementation of the old approach that gets an ID Token (and then uses it to call the endpoint).

<AuthCodeBlock />

In the example below, you can see the new approach that gets an access token as well.

<AuthCodeBlock />

In order to get an Access Token that can access the Management API:

* Set the `aud` to `https://{yourDomain}/api/v2/`
* Ask for the scope `read:current_user`

Once you have the access token you can use it to call the endpoint. This part remains the same, nothing else changes in the request except for the value you use as `Bearer` token. The response remains also the same.

#### Embedded Lock or auth0.js

If you embed either Lock or auth0.js v9 in your application, then you are using cross-origin authentication. This is used to authenticate users when the requests come from different domains.

If you use auth0.js to access the Management API and manage your users, then your script will have to be updated.

In the example below, you can see the old approach.

<AuthCodeBlock />

In this example, you can see the new approach.

<AuthCodeBlock />

* Ask for both an ID token and an access token in the response

  `responseType: 'token id_token'`
* Set the Management API as the intended <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> of the token

  `audience: 'https://YOUR_DOMAIN/api/v2/'`
* Ask for the required permission

  `scope: 'read:current_user'`
* Authenticate with the Management API using the access token

### Account Linking changes

The changes in this functionality are the following:

* You can no longer use an ID Token at the `Authorization` header
* If you use an access token at the `Authorization` header, with `update:users` as the granted permission, then you can send at the request's body either the `user_id` or the ID Token of the secondary account
* If you use an access token at the `Authorization` header, with `update:current_user_metadata` as the granted permission, then you can only send the ID Token of the secondary account in the request's body. The following must apply:

  * The ID token must be signed using `RS256` (you can set this value at **Dashboard > Applications > Application Settings > Advanced Settings > OAuth**)
  * The claim `aud` of the ID token, must identify the application, and be the same value with the `azp` claim of the access token

## Restrictions

The access tokens used to access the Management API must only hold one value at the `aud` claim. If your token contains more than one value, then your request to the Management API will error out.

## Learn more

* [Migrate to Access Tokens for Account Linking](/docs/troubleshoot/product-lifecycle/past-migrations/link-user-accounts-with-access-tokens-migration)


# Migrate from Node.js 8 to Node.js 12
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/migrate-to-nodejs-12

Describes Auth0 features affected by the Node.js v8 to Node.js v12 migration and provides recommendations for migration.

As of December 31, 2019, [Node.js v8 went out of long-term support (LTS)](https://github.com/nodejs/Release#release-schedule), which means that the Node.js development team no longer back-ports critical security fixes to this version. This could potentially expose your extensibility code to security vulnerabilities. Therefore, Auth0 migrated from Node 8 to Node 12.

## Features affected

The following Auth0 features use Node 8:

* Rules
* Hooks
* Custom database connections
* Custom social connections
* Extensions

If you do not use any of the extensibility features mentioned above, then you are not affected by this migration.

## Tasks

As part of the process of introducing Node 12 in our Webtask runtime, we ran a number of tests to determine which modules are not forward-compatible from Node 8 to 12. Most customers should be able to upgrade to Node 12 without any issues.

That said, before you migrate, we highly recommend testing all of your:

* Rules
* Hooks
* Custom database connections and scripts
* Custom social connections
* Extensions

Auth0 recommends that that you first switch your development tenant to Node 12 runtime, complete testing in your development tenant, and migrate your production tenant only when you see no issues in development.

### Enable Node 12 runtime

There may be additional behavioral changes as a result of this migration, so we have provided a migration switch that allows you to control the migration of your environment to the new Webtask runtime using Node 12.

Auth0 recommends that that you first switch your development tenant to Node 12 runtime, complete testing in your development tenant, and migrate your production tenant only when you see no issues in development.

You can query the [Management API](/docs/api) for your rules, hooks, custom database scripts, and custom social connections. This will make it easier for you to move items from your production tenant to development tenant for testing purposes.

When using the Connections endpoints in the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>, custom database scripts can be retrieved or updated using `options.customScripts`. Similarly, you can find custom social connections in `options.scripts.fetchUserProfile`.

1. Enable Node 12 on your development tenant using the new **Extensibility** panel on the [Advanced Tenant Settings](https://manage.auth0.com/#/tenant/advanced) page of the Dashboard. Choose **Node 12** from the **Runtime** drop-down.
2. Click **Save**.
3. If you use the items listed below, complete the migration steps for each of them.
4. Test your configuration.
5. Once you are sure that nothing has broken, use steps 1 and 2 above to enable Node 12 on your production tenant.

### Allowlist new URLs

The Delegated Administration Extension and the <Tooltip href="/docs/glossary?term=Single+Sign-on">Single Sign-on</Tooltip> (SSO) Dashboard Extension require allowlisting the URLs used to access extensions and custom webtasks. When you upgrade to Node 12, the URLs you use to access extensions and custom webtasks will change. This is a breaking change for these extensions.

If you use any of these extensions, you must allowlist the new URLs both as Allowed Callback and as Allowed Logout URLs.

The region portion of the URL will change from 8 to 12. If you access an extension using the URL:

`https://{yourTenant}.us8.webtask.io/dummy-extension-url`

when you upgrade to Node 12, the URL will be:

`https://{yourTenant}.us12.webtask.io/dummy-extension-url`

1. Go to [Dashboard > Applications > Applications > Settings](https://manage.auth0.com/#/applications/\{yourClientId}/settings), and add the URL to the fields **Allowed Callback URLs** and **Allowed Logout URLs**.
2. The execution URLs will also change for custom webtasks in your Auth0 container. You must update any external applications that call those webtasks.

### Republish Authorization Extension rule

If you use the Authorization Extension, it generates an `auth0-authorization-extension` rule. Republish this rule from within the Authorization Extension to update the URLs automatically.

1. Ensure you have upgraded to the latest version of the Authorization Extension from the **Installed Extensions** tab. If the **Upgrade** button is present, click to upgrade. If the button is not present, you are already on the latest version of the extension.
2. Open the **Authorization Extension** configuration page.
3. To update the URL in the rule, publish the rule again by clicking the **Publish Rule** button.
4. Test to make sure everything is still working. If you see an Invalid API Key error after updating, click the **Rotate** button to generate a new API key.

### Configure Delegated Administration URLs

If you use the Delegated Administration Extension, the matrix that follows contains the updated URLs you must configure after you migrate to Node 12. The URL varies based on your location.

<table>
  <thead>
    <tr>
      <th>Location</th>
      <th>Allowed Callback URL for Node 12</th>
      <th>Allowed Logout URL for Node 12</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>US-1</td>
      <td>`https://{yourTenant}.us12.webtask.io/auth0-delegated-admin/login`</td>
      <td>`https://{yourTenant}.us12.webtask.io/auth0-delegated-admin`</td>
    </tr>

    <tr>
      <td>US-3</td>
      <td>`https://{yourTenant}.us.webtask.run/auth0-delegated-admin/login`</td>
      <td>`https://{yourTenant}.us.webtask.run/auth0-delegated-admin`</td>
    </tr>

    <tr>
      <td>EU</td>
      <td>`https://{yourTenant}.eu12.webtask.io/auth0-delegated-admin/login`</td>
      <td>`https://{yourTenant}.eu12.webtask.io/auth0-delegated-admin`</td>
    </tr>

    <tr>
      <td>AU</td>
      <td>`https://{yourTenant}.au12.webtask.io/auth0-delegated-admin/login`</td>
      <td>`https://{yourTenant}.au12.webtask.io/auth0-delegated-admin`</td>
    </tr>

    <tr>
      <td>JP-1</td>
      <td>`https://{yourTenant}.jp.webtask.run/auth0-delegated-admin/login`</td>
      <td>`https://{yourTenant}.jp.webtask.run/auth0-delegated-admin`</td>
    </tr>
  </tbody>
</table>

For example, if you are located in the USA and you use the Delegated Administration, you should update the following fields in your application's settings:

* **Allowed Callback URLs**: `https://{yourTenant}.us12.webtask.io/auth0-delegated-admin/login`
* **Allowed Logout URLs**: `https://{yourTenant}.us12.webtask.io/auth0-delegated-admin`

### Configure SSO Dashboard URLs

The matrix that follows contains the updated URLs you must configure after you migrate to Node 12. The URL varies based on your location.

The login URL for Admins:

<table>
  <thead>
    <tr>
      <th>Location</th>
      <th>Allowed Callback URL</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>US-1</td>
      <td>`https://{yourTenant}.us12.webtask.io/auth0-sso-dashboard/admins/login`</td>
    </tr>

    <tr>
      <td>US-3</td>
      <td>`https://{yourTenant}.us.webtask.run/auth0-sso-dashboard/admins/login`</td>
    </tr>

    <tr>
      <td>Europe</td>
      <td>`https://{yourTenant}.eu12.webtask.io/auth0-sso-dashboard/admins/login`</td>
    </tr>

    <tr>
      <td>Australia</td>
      <td>`https://{yourTenant}.au12.webtask.io/auth0-sso-dashboard/admins/login`</td>
    </tr>

    <tr>
      <td>Japan</td>
      <td>`https://{yourTenant}.jp.webtask.run/auth0-sso-dashboard/admins/login`</td>
    </tr>
  </tbody>
</table>

The login URL for Users:

<table>
  <thead>
    <tr>
      <th>Location</th>
      <th>Allowed Callback URL</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>US-1</td>
      <td>`https://{yourTenant}.us12.webtask.io/auth0-sso-dashboard/login`</td>
    </tr>

    <tr>
      <td>US-3</td>
      <td>`https://{yourTenant}.us.webtask.run/auth0-sso-dashboard/login`</td>
    </tr>

    <tr>
      <td>Europe</td>
      <td>`https://{yourTenant}.eu12.webtask.io/auth0-sso-dashboard/login`</td>
    </tr>

    <tr>
      <td>Australia</td>
      <td>`https://{yourTenant}.au12.webtask.io/auth0-sso-dashboard/login`</td>
    </tr>

    <tr>
      <td>Japan</td>
      <td>`https://{yourTenant}.jp.webtask.run/auth0-sso-dashboard/login`</td>
    </tr>
  </tbody>
</table>

### Update Extensions

Most extensions use the `PUBLIC_WT_URL` hidden secret for authorization. This secret depends on the runtime version and does not update automatically.

To update it, you need to save the extension's settings (no changes are necessary). To do so, after switching the runtime to `Node 12`, you need to open the extension's settings in the extensions dashboard (gear icon), and click `Save`. After that, the extensions gallery will update the `PUBLIC_WT_URL` secret based on the selected runtime.

If you do not update the `PUBLIC_WT_URL` hidden secret, you will receive the following error:

<Frame>
  <img alt="Misconfiguration or Service Outage Error" />
</Frame>

### Update pinned modules

If you are using the following built-in modules (that is, modules that you did not explicitly require), please be aware that some versions were updated to work with Node 12. The following table summarizes the changes. These new versions should remain backwards compatible with their previous versions.

<table>
  <thead>
    <tr>
      <th>Module name</th>
      <th>Old version</th>
      <th>New version</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>couchbase</td>
      <td>\~2.5.1</td>
      <td>2.6.10</td>
    </tr>

    <tr>
      <td>bcrypt</td>
      <td>1.0.3</td>
      <td>3.0.8</td>
    </tr>
  </tbody>
</table>

If you have manually pinned modules, you may need to manually update them so that your code runs with Node 12.

For example, you must change:

`var bcrypt = require(‘bcrypt@1.0.3’);`

to

`var bcrypt = require(‘bcrypt’);`

or, if the module must be pinned to a specific version:

`var bcrypt = require(‘bcrypt@3.0.8’);`


# Migrate to Node.js 16
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/migrate-to-nodejs-16

Describes Auth0 features affected by the Node.js v12 to Node.js v16 migration and provides recommendations for migration.

On 30 Apr 2022, [Node.js v12 went out of long-term support (LTS)](https://github.com/nodejs/Release#release-schedule), which means that the Node.js development team no longer back-ports critical security fixes to this version. This could potentially expose your extensibility code to security vulnerabilities. Therefore, Auth0 is migrating from Node 12 to Node 16.

## Recommendations

Although the Node 16 update will not introduce any breaking changes in the Node.js standard library (Rules and Custom Database Action Scripts are affected; see the [Breaking changes - Rules and Custom Database Action Scripts only](#breaking-changes-rules-only) section), we encourage customers on Node version 12 to stay current with Active Long-Term Support (LTS) Node versions for security and compliance purposes. Customers who are still on Node 8 are out of security compliance and must migrate to Node 16 to eliminate security risks. We removed the Node 8 runtime on 22 Feb 2022 for Public Cloud tenants and removed it in the April 2022 Private Cloud release. After these dates, tenants still set to Node 8 run the risk of a service interruption.

Actions is designed to support multiple versions of node concurrently, and currently supports both Node 12 and Node 16. In addition, no-code Actions Integrations will follow industry-standard "always current" version control with minor versions updated automatically; the underlying code will always remain current and to the latest version of Node.js.

<table>
  <thead>
    <tr>
      <th>Customers Using</th>
      <th>Should</th>
      <th>Task</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Actions Node 12</td>
      <td>Update any existing custom Action versions to a new version, which will update to Node 16.</td>
      <td>Update all custom Action versions as soon as possible.</td>
    </tr>

    <tr>
      <td>Legacy Node 12 (Rules/Hooks/Extensions)</td>
      <td>Begin migrating to Actions Node 16.</td>
      <td><a href="/docs/customize/actions/migrate">Migrate to Actions Node 16</a> as soon as possible.</td>
    </tr>

    <tr>
      <td>Legacy Node 8</td>
      <td>Immediately migrate to Actions wherever possible. For Rules and Hooks that cannot immediately be migrated to Actions, you must, at a minimum, update your code to Node 12 and update tenant settings to Node 12.</td>
      <td><a href="/docs/customize/actions/migrate">Migrate to Actions Node 16</a> immediately.</td>
    </tr>
  </tbody>
</table>

## Tasks

### Upgrade Actions

Existing Actions built on Node 12 can be upgraded to Node 16 and later reverted to a previous version on Node 12 if needed. Upgrade Actions to Node 16 by [creating and deploying a new version](/docs/customize/actions/manage-versions) set to use Node 16 as the runtime.

### Migrate Rules and Hooks to Actions

Wherever possible, migrate Rules and Hooks to Actions. To determine which Rules and Hooks can be migrated, read [Actions Limitations](/docs/customize/actions/limitations). To learn how to migrate your Rules and Hooks to Actions, see our guides available at [Migrate to Actions](/docs/customize/actions/migrate).

### Enable Node 16 runtime

If you use any legacy extensibility products, like Rules, Hooks, or Extensions, then you must enable the Node 16 runtime at the tenant level. We recommend that you first switch your development tenant to Node 16 runtime, test your configuration, then switch your production tenant.

1. Enable Node 16 on your development tenant using the **Extensibility** panel on the [Advanced Tenant Settings](https://manage.auth0.com/#/tenant/advanced) page of the Dashboard. Choose **Node 16** from the **Runtime** drop-down.
2. Click **Save**.
3. Check that you either do not have the items listed below, or have completed the migration steps for each.
4. Test your configuration.When you finish testing, repeat steps 1 and 2 above using your production tenant to enable Node 16 in production.

### Breaking changes - Rules and Custom Database Action Scripts only

Rules run in a JavaScript sandbox. The sandbox supports the ECMAScript 6 language and a large number of Node.js (version 16+) modules. If you are using any of these global properties within Rules or Custom Database Action Scripts, [look for an alternative in our list of supported sandbox modules](https://auth0-extensions.github.io/canirequire/) and explicitly require it.

* `_`
* `async`
* `Auth0`
* `azure_storage`
* `bcrypt`
* `crypto`
* `couchbase`
* `cql`
* `ip`
* `jwt`
* `Knex`
* `mongo`
* `mysql`
* `mysql_pool`
* `ObjectID`
* `pbkdf2`
* `pg`
* `postgres`
* `Pubnub`
* `q`
* `querystring`
* `request`
* `sqlserver`
* `uuid`
* `xml2js`
* `xmldom`
* `xpath`
* `xtend`


# Migrate to Management API v2 Endpoint Paginated Queries
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/migrate-to-paginated-queries

Describes how to use the pagination parameters for specific Management API v2 endpoint queries.

After **26 January 2021** (or Private Cloud version 2202), requests to <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> v2 endpoints will return a maximum of 50 items for tenants in the Public Cloud. To retrieve more items, you must include the `page` and `per_page` parameters. Beginning on **21 July 2020** (or Private Cloud version 2108), Auth0 will display tenant logs and a migration toggle to help you prepare for this change.

Affected tenants are those that meet the following criteria:

* Public Cloud tenants created **before 21 July 2020** or Private Cloud deployments on version 2108
* Actively making calls to the affected endpoints without passing the `per_page` parameter for queries that can return more than 1 result.

The following tenants will default to the new pagination behavior and will continue to operate as they do today after 26 January 2021:

* Public Cloud tenants created **on or after 21 July 2020** or Private Cloud deployments on version 2108 or higher
* Not using any of the affected endpoints
* Using the affected endpoints and passing the `per_page` parameter, or making queries that will always return a single result.

## Endpoints affected

Calls to the following Management API v2 endpoints are affected:

* [`GET /api/v2/clients`](https://auth0.com/docs/api/management/v2#!/Clients/get_clients)
* [`GET /api/v2/client_grants`](https://auth0.com/docs/api/management/v2#!/Clients/client_grants)
* [`GET /api/v2/grants`](https://auth0.com/docs/api/management/v2#!/Clients/grants)
* [`GET /api/v2/connections`](https://auth0.com/docs/api/management/v2#!/Clients/connections)
* [`GET /api/v2/device-credentials`](https://auth0.com/docs/api/management/v2#!/Clients/device_credentials)
* [`GET /api/v2/resource-servers`](https://auth0.com/docs/api/management/v2#!/Clients/resource_servers)
* [`GET /api/v2/rules`](https://auth0.com/docs/api/management/v2#!/Clients/rules)

Deprecation notices will be recorded in your tenant logs for all requests without pagination options that are currently returning more than 1 item, once per hour, for each different client and endpoint.

## Actions

1. Replace all calls to the affected endpoints by providing the `page` and `per_page` parameters.

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>page</code></td>
      <td>Integer</td>
      <td>Page index of the results to return. First page is 0.</td>
    </tr>

    <tr>
      <td><code>per\_page</code></td>
      <td>Integer</td>
      <td>Number of results per page. Paging is disabled if the parameter is not sent.</td>
    </tr>
  </tbody>
</table>

2. Confirm that you are no longer seeing deprecation notices in your tenant logs. Check if a request returned more than 50 items. Look at the `details.size_exceeded` field and check if it's `true`.

   1. Use the following log query to return all calls without pagination options with more than 1 result:
      `type:depnote AND description:*Unpaginated*`
   2. Use the following log query to return all calls without pagination options with more than 50 results:
      `type:depnote AND description:*Unpaginated* AND details.size_exceeded:true`

   To identify the application making the request, logs will include the `client_id` used to make the request. You can also find the endpoint being used in the logs `details.path` field.
3. Disable Management API unpaginated requests for your tenant. Go to [Dashboard > Tenant Settings > Advanced > Migration](https://manage.auth0.com/#/tenant/advanced). This will simulate the expected behavior after the migration window closes, causing calls to affected endpoints to return up to 50 results. You will be able to re-enable unpaginated requests any time before that date.

### Update extensions

You may need to update from previous versions of [Auth0 Extensions](/docs/customize/extensions) and custom extensions to the latest versions to make sure they are only performing paginated queries.

1. Check your tenant logs for deprecation notices for clients with an ID matching an extension URL. It means you will need to update that extension.
2. Go to [Dashboard > Extensions](https://manage.auth0.com/#/extensions), select **Installed Extensions**, and click on the extension's **Update** link if present.

### Update Deploy CLI tool

If you are using the `auth0-deploy-cli` tool, you must update to version **5.3.0 or later**. To learn more, see [Deploy CLI Tool](/docs/deploy-monitor/deploy-cli-tool).


# Migrate to Passwordless Endpoint from Confidential Applications
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/migrate-to-passwordless

Describes the migration steps you need to take because Auth0 is deprecating the usage of the /passwordless/start endpoint from confidential applications without a client secret in the request.

Auth0 is deprecating the use of the `/passwordless/start` endpoint from confidential applications when Auth0 cannot authenticate that the call is made on behalf of the application.

<Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> uses the term 'confidential' for applications that can store secrets. In Auth0, those are 'Regular Web Applications', which serve web pages from a backend app. Single Page Applications and Native Applications are considered 'public' applications, and are not affected by this change.

Auth0 can authenticate calls to `/passwordless/start` when they include a `client_secret` as a parameter, or when the calls are made from the custom login page in Classic Login and forward the `state` parameter.

## Features affected

If any of your applications currently call the `/passwordless/start` endpoint directly to begin <Tooltip href="/docs/glossary?term=passwordless">passwordless</Tooltip> authentication from a Web Application, and you are not sending the `client_secret` as a parameter, this deprecation does affect you.

If you are implementing passwordless authentication through the Classic Login page and you changed the default way Auth0 libraries are initialized, it might also affect you too.

You can verify whether you are affected by checking the [tenant logs](https://manage.auth0.com/#/logs), filtering by "Deprecation Notice" and check for logs saying "Enforce client authentication for passwordless connections". You can also perform this search directly with the following query: `type:depnote AND description:*passwordless*`. Note that this specific query will only work for public cloud tenants, as private cloud logs cannot be searched on the description field.

## Actions

If you are calling the `/passwordless/start` endpoint without proper application authentication you should:

* Follow the instructions described below to adjust the code to properly call `/passwordless/start`.
* Check your [tenant logs](https://manage.auth0.com/#/logs) to verify the change was made correctly and no deprecation logs are being generated for "Enforce client authentication for passwordless connections".
* In the **Migrations** section of **Advanced Tenant Settings**, turn on the **Enforce client authentication for passwordless connections** toggle.

There are a few use cases that might be affected, but for each, the migration path is fairly straightforward:

### API calls from backend

For any calls from your backend to the `/passwordless/start` endpoint, your call must include the <Tooltip href="/docs/glossary?term=client+secret">client secret</Tooltip> as a parameter.

If making a POST request directly to `/passwordless/start`, include the `client_secret` as part of the payload:

<AuthCodeBlock />

If you are using an SDK, add the parameter to the method that initiates the passwordless flow. This is different for each SDK, and not all SDKs have been updated yet. If you are using an SDK that was not updated, you can make the HTTP call directly until that work is completed.

### Auth0.js or Lock.js in the Classic Login page

If the Classic Login page is used for Passwordless Authentication for a Web Application, it will be making calls to the `/passwordless/start` endpoint, by either using Lock.js or Auth0.js.

Given you can't store a client secret in a web page, the way to authenticate the call is by forwarding the `state` parameter that is received in the Classic Login page to the `/passwordless/start` endpoint. That parameter is stored in the `config.internalOptions` field in the custom login page.

The default templates for customizing the login page use it in the following way when initializing Lock.js or auth0.js:

```javascript lines theme={null}
var lock = new Auth0Lock(
  config.clientID, 
  config.auth0Domain, 
  {
    auth: {
      // .. other fields set
      params: {
       scope: config.internalOptions.scope,
       _csrf: config.internalOptions._csrf,
       state: config.internalOptions.state,
      }
    }
  });
```

```javascript lines theme={null}
var params = Object.assign({
    scope: config.internalOptions.scope,
    _csrf: config.internalOptions._csrf,
    state: config.internalOptions.state,
  }, {
    // ...auth params
  });

var webAuth = new auth0.WebAuth(params);
```

Please check in your custom page implementation to verify that you have not removed that code.

### Call /passwordless/start from the client in a web application

If you are calling the `/passwordless/start` endpoint from a page using JavaScript (for example, using Auth0.js on the page) from regular web apps, you will not be able to specify a client secret in a call made using JavaScript. If this is the case for your application, you will need to change your apps so that `/passwordless/start` is called from the backend of your web application, rather than from the frontend.

### Rate Limits

A consequence of adding client authentication to `/passwordless/start` is that Auth0 can trust the headers sent with the request. If you set the `auth0-forwarded-for` header, the IP address will show in the logs and be used for <Tooltip href="/docs/glossary?term=attack+protection">attack protection</Tooltip> purposes.

Authenticated `/passwordless/start` requests will be treated as regular Authenticated API requests and the corresponding global Authentication API rate limit will apply.


# Migrate from Search v2 to v3
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/migrate-v2-v3

Learn how to migrate from Auth0 Search v2 to v3.

User search v2 has reached its end of life as of **June 30, 2019**. We highly recommend migrating user search functionality to [search engine v3](/docs/manage-users/user-search) (`search_engine=v3`) as soon as possible.

## Migration considerations

Before you start migrating, there are a few things you should know:

* To ensure that your queries are using search engine v3 prior to v2 becoming unavailable, you must update all your calls to the `GET /api/v2/users` endpoint to include the `search_engine=v3` parameter. This will enable you to see whether any queries need to be updated, so that you will not experience downtime when v2 becomes unavailable.
* If you are performing user search operations through any of the [impacted SDKs](#impacted-sdks), you must also pass the `search_engine=v3` parameter as outlined above.
* Search values for the normalized user fields (`email`, `name`, `given_name`, `family_name`, and `nickname`) are case insensitive. All other fields (including all `app_metadata`/`user_metadata` fields) are case sensitive.
* v3 limits the number of users you can retrieve to 1000. If you are reaching this limit, we recommend that you redefine your search query to obtain more granular results. If you need a list of more than 1000 users at a given time, we recommend that you use the [Export Job](https://auth0.com/docs/api/management/v2#!/Jobs/post_users_exports) API endpoint or [User Import / Export Extension](/docs/manage-users/user-migration/user-import-export-extension) instead.
* Range and wildcard searches are not available on `app_metadata`/`user_metadata` fields.
* User fields are not tokenized like in v2, so `user_id:auth0` will not match a `user_id` with value `auth0|12345`, instead, use `user_id:auth0*`.
* Wildcards can be used for prefix matching, for example `name:j*`. For other uses of wildcards (e.g. suffix matching), literals must have 3 characters or more. For example, `name:*usa` is allowed, but `name:*sa` is not.
* The `.raw` field extension is no longer supported and must be removed. In v3, fields match the whole value that is provided and are not tokenized as they were in v2 without the `.raw` suffix.
* The `connection` field is not supported in v3. You should use its alias `identities.connection` instead.

## Queries to migrate

<table>
  <thead>
    <tr>
      <th>Use case</th>
      <th>v2</th>
      <th>v3</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Search by date</td>
      <td><code>updated\_at:>=2018-01-15</code></td>
      <td><code>updated\_at:\[2018-01-15 TO \*]</code></td>
    </tr>

    <tr>
      <td>Search by date</td>
      <td><code>updated\_at:>2018-01-15</code></td>

      <td>
        <code>
          updated\_at:\{2018-01-15 TO \*]
        </code>
      </td>
    </tr>

    <tr>
      <td>Search by date</td>
      <td><code>updated\_at:\<=2018-01-15</code></td>
      <td><code>updated\_at:\[\* TO 2018-01-15]</code></td>
    </tr>

    <tr>
      <td>Search by date</td>
      <td><code>updated\_at:\<2018-01-15</code></td>
      <td><code>updated\_at:\[\* TO 2018-01-15}</code></td>
    </tr>

    <tr>
      <td>Search by date</td>
      <td><code>last\_login:\<=2017-12</code></td>
      <td><code>last\_login:\[\* TO 2017-12]</code></td>
    </tr>

    <tr>
      <td>String exact match</td>
      <td><code>name.raw:"john richard doe"</code></td>
      <td><code>name:"john richard doe"</code></td>
    </tr>

    <tr>
      <td>Phrase contains a word</td>
      <td><code>name:"richard"</code>, <code>name:richard</code></td>
      <td><code>name:*richard*</code></td>
    </tr>

    <tr>
      <td>Phrase contains a word (with less than 3 characters)</td>
      <td><code>name:\*ri</code>,<code>name:\*a</code>, <code>name:*ab*</code></td>
      <td><em>(not supported)</em></td>
    </tr>
  </tbody>
</table>

## Impacted SDKs

The following SDKs make use of the User Search engine. If you are using them, make sure you are using the versions listed below (or a later version), and pass the `search_engine=v3` parameter when performing user search operations.

<table>
  <thead>
    <tr>
      <th>SDK</th>
      <th>Version with support for v3</th>
      <th>Impacted methods</th>
      <th>Considerations</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="https://github.com/auth0/auth0-java">Auth0 Java</a></td>
      <td>1.8.0</td>
      <td>com.auth0.client.mgmt.UsersEntity.list</td>
      <td>Provide a <code>UserFilter</code> with <code>withSearchEngine("v3")</code></td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/auth0-python">Auth0 Python</a></td>
      <td>3.0.0</td>
      <td>management.Users.list</td>
      <td>Provide the parameter <code>search\_engine='v3'</code></td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/node-auth0">Auth0 Node</a></td>
      <td>2.0.0</td>
      <td>UsersManager.getAll, ManagementClient.getUsers</td>
      <td>Provide the parameter <code>search\_engine:'v3'</code></td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/auth0.net">Auth0 .NET</a></td>
      <td>3.0.0 or 4.0.0</td>
      <td>Auth0.ManagementApi.IUsersClient.GetAllAsync</td>
      <td>Provide a <code>GetUsersRequest</code> object with <code>SearchEngine</code> = <code>"v3"</code></td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/auth0-php">Auth0 PHP</a></td>
      <td>5.2.0</td>
      <td>Auth0.SDK.API.Management.Users.getAll</td>
      <td>Provide the parameter <code>'search\_engine' => 'v3'</code></td>
    </tr>

    <tr>
      <td><a href="https://github.com/auth0/ruby-auth0">Auth0 Ruby</a></td>
      <td>4.5.0</td>
      <td>Auth0.Api.V2.Users.users</td>
      <td>Provide the parameter <code>search\_engine: 'v3'</code></td>
    </tr>
  </tbody>
</table>

## Impacted Extensions

The following Extensions make use of the User Search engine. If you have them installed, make sure you are using the versions listed below (or a later version).

<table>
  <thead>
    <tr>
      <th>Extension</th>
      <th>Version support for v3</th>
      <th>Considerations</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><a href="/docs/customize/extensions/authorization-extension">Authorization Extension</a></td>
      <td>2.5.0+</td>
      <td>If you are using an earlier version, you need to manually update the extension from the <a href="https://manage.auth0.com/#/extensions">Extensions</a> page.</td>
    </tr>

    <tr>
      <td><a href="/docs/customize/extensions/delegated-administration-extension">Delegated Administration</a></td>
      <td>3.1+</td>
      <td>If you are using an earlier version, you need to manually update the extension from the <a href="https://manage.auth0.com/#/extensions">Extensions</a> page. The <code>SEARCH\_ENGINE</code> configuration setting no longer exists in 3.1, because only User Search v3 is available.</td>
    </tr>
  </tbody>
</table>

## Leverage your tenant logs to find usage of User Search v2

You can leverage the [logs](/docs/deploy-monitor/logs) in the [Dashboard](https://manage.auth0.com/#/logs) to find calls to the `/api/v2/users` endpoint that use the User Search v2 engine, including calls performed by SDKs. Those logs will help you identify where code changes might be needed in your applications.

Use the following query to retrieve all the logs related to User Search v2: `type:w AND description:*search_engine*`. The logs will provide additional information in the description field, in the following cases:

* Queries that might produce different results in v3
* Queries with syntax incompatible with v3
* Queries that do not meet the paging requirements of v3

If no additional details are specified in the log entries, it's likely that your queries are compatible with v3. Our recommendation, however, is still that you test the queries before deploying your changes to production.

Please note that only one log of the same type will be generated within 60 minutes. This means that even though you may be doing multiple calls to the User Search endpoint, you will only see one log of each type per hour.


# Migrate Your Resource Owner Passwordless Credentials Exchange
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/resource-owner-passwordless-credentials-exchange

Describes how to migrate your Passwordless API calls and responses from /oauth/ro to /oauth/token.

Support for <Tooltip href="/docs/glossary?term=resource+owner">resource owner</Tooltip> password was added to `/oauth/token`. Usage of the `/oauth/ro` endpoint was deprecated on 08 July 2017. The `/oauth/ro` endpoint was previously used to exchange a one-time password (OTP) received by the end-user email or SMS for an <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> and an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>. Auth0 has implemented a new API that replaces `/oauth/ro` for this use case and we recommend that you migrate to using the new endpoint.

## Features affected

This change affects you if you use the resource owner <Tooltip href="/docs/glossary?term=passwordless">passwordless</Tooltip> credentials exchange and call `/oauth/ro` directly without the use of any Auth0 libraries or SDKs.

<Callout icon="file-lines">
  When a user's `/oauth/ro` based access token has expired, Auth0 forces them to reauthenticate (forced logout required) because the `/oauth/ro` refresh token cannot be used to call `/oauth/token` for a new access token. All currently logged in user's must log in again during an `/oauth/ro` to `/oauth/token` migration.
</Callout>

## Actions

### Request changes

Previously, the payload of a request to `/oauth/ro` looked similar to this:

```json lines theme={null}
{
  "grant_type": "password",
  "client_id": "123",
  "username": "alice",
  "password": "A3ddj3w", 
  "connection": "my-database-connection",
  "scope": "openid email favorite_color offline_access",
  "device": "my-device-name"
}
```

These are the changes for the new implementation:

* The endpoint to execute token exchanges is now `/oauth/token`.
* Auth0's own grant type is used to authenticate users from a specific connection (or realm).
* Auth0 supports the standard OIDC scopes, along with the scopes which you have defined in your custom API.
* A scope that does not fit in one of these categories, such as the above `favorite_color`, is no longer a valid scope.
* The `device` parameter is removed.
* The `audience` parameter is optional.

Here is an example of the payload of a request to `/oauth/token`:

<AuthCodeBlock />

* The grant type is specified here as `http://auth0.com/oauth/grant-type/passwordless/otp`.
* The parameters `client_id` and `username` are unchanged.
* The `client_secret` needs to be specified for <Tooltip href="/docs/glossary?term=confidential+clients">confidential clients</Tooltip> (e.g. regular web apps).
* The one-time password needs to be sent in the `otp` parameter instead of the `password` parameter.
* The `realm` is used to identify the connection, and replaces the `connection` parameter from previous calls.
* The `scope` parameter is mostly the same, but does not accept non-OIDC values.
* The `audience` parameter can be added, indicating the API <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> the token will be intended for.

### Response changes

Responses from `/oauth/ro` were similar in format to the following:

```json lines theme={null}
{
  "access_token": "SlAV32hkKG",
  "token_type": "Bearer",
  "refresh_token": "8xLOxBtZp8",
  "expires_in": 3600,
  "id_token": "eyJ..."
}
```

* The returned access token is valid for calling the `/userinfo` endpoint (provided that the API specified by the `audience` param uses RS256 as <Tooltip href="/docs/glossary?term=signing+algorithm">signing algorithm</Tooltip>) and optionally the custom API if one was specified.
* The ID token will be forcibly signed using RS256 if requested by a <Tooltip href="/docs/glossary?term=public+client">public client</Tooltip>.
* A <Tooltip href="/docs/glossary?term=refresh+token">refresh token</Tooltip> will be returned only if the `offline_access` scope was granted and the API has **Allow offline access** set.

Here is an example of the OIDC conformant response from `/oauth/token`:

```json lines theme={null}
{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "refresh_token": "8xLOxBtZp8",
  "expires_in": 3600,
  "id_token": "eyJ..."
}
```

### Code changes when using the SDKs

If your application uses the Auth0 native libraries for Android or iOS, be sure that the version of the library you are including is at least the minimum listed below (or higher). Also, be sure to set the `OIDC Conformant` flag to `true` when configuring the libraries.

<table>
  <thead>
    <tr>
      <th>Library</th>
      <th>Minimum Version</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Android SDK</td>
      <td>1.2</td>
    </tr>

    <tr>
      <td>Lock Android</td>
      <td>2.17</td>
    </tr>

    <tr>
      <td>Swift SDK</td>
      <td>1.20.0</td>
    </tr>

    <tr>
      <td>Lock iOS</td>
      <td>2.14.0</td>
    </tr>
  </tbody>
</table>

### Verify migration

1. To verify whether you are using the deprecated endpoint, check the [tenant logs](https://manage.auth0.com/#/logs), filter by **Deprecation Notice** and then check for logs that say `oauth/ro` **passwordless: This feature is being deprecated**. You can also perform this search directly with the following query: `type:depnote AND description:*passwordless*`.
2. Once you have migrated your codebase and are sure that your apps are not calling the endpoint, go to the [Dashboard](https://manage.auth0.com/#/tenant/advanced) under **Tenant Settings > Advanced**.
3. Scroll down to **Migrations** and toggle off **Legacy** `/oauth/ro` **Endpoint**. Turning off this switch disables the deprecated endpoint for your tenant, preventing it from being used.

If turning this switch off results in failed logins, this is a sign that you have yet to completely remove all instances of legacy code from your applications.

Once migrations have been successfully performed in production environments, the switch can be toggled off and left off, to ensure that the deprecated features can no longer be used.

## Learn more

* [Migrate Your Resource Owner Password Flow](/docs/troubleshoot/product-lifecycle/past-migrations/migration-oauthro-oauthtoken)


# Migrate Tenant Hostname Validation
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/tenant-hostname-migration

Describes how to check tenant logs for deprecation notices so you can migrate your application domain

As of June 9, 2022 in Public Cloud and September 9, 2022 in Private Cloud, Auth0 is adding a layer of validation to the Authentication API. If Auth0 has detected that calls from your applications to the Authentication API may be affected by this change, we have provided deprecation notices in tenants logs and a migration flag to prepare you for this change.

### Affected Endpoints

As of June 9, 2022 in Public Cloud and September 9, 2022 in Private Cloud, any calls to the Authentication API endpoints below that are not properly validated will be rejected. Auth0 recommends that you take action to migrate your application domain URL or API call identifier to the same tenant well before that date.

The affected endpoints are:

* `/oauth/token`
* `/co/authenticate`
* `/userinfo`
* `/login`
* `/oauth/revoke`
* `/mfa/challenge`
* `/p/<connection-type>/<ticket>` (Enterprise connection provisioning endpoint)

## Review tenant logs

First, check your tenant logs for deprecation notices to verify if you need to migrate your application.

1. Navigate to [Dashboard > Monitoring > Logs](https://manage.auth0.com/#/logs).

   1. Search the logs for `type:depnote AND description:ignore*request*host*header*` to find the deprecation notice regarding which applications are affected and need to be migrated. The log entry includes the ID for any impacted applications and the following message:
      `Ignore request Host header: This feature is being deprecated. Please see https://auth0.com/docs/product-lifecycle/deprecations-and-migrations``/tenant-hostname-migration.`
   2. Find the **Details > Raw** section of the log. There you can identify the `client_id` of the application to update, or the `connection_id` in the case of a provisioning endpoint.

      <Callout icon="file-lines">
        Also check the `tenant_from_host` field. This field contains the Auth0 tenant identified from the domain received in your API calls.
      </Callout>
2. Modify all applicable applications.

   1. If any misalignments of tenant and domain tenant exist, you need to modify the sent identifiers, or domain URL, along with other misconfigured request parameters.
   2. The domain tenant should match the tenant associated with the `client_id` or `connection_id`.

Once you’ve completed migrating all applicable tenants, tenant  logs will no longer show deprecation notices associated with this migration.

## Verify Migration

Once you have migrated your applications and configured unvalidated hostnames, verify your changes by disabling the deprecated behavior at a time of your choosing and ahead of June 9, 2022 or September 9, 2022.

1. Navigate to [Dashboard > Tenant Settings > Advanced > Migrations](https://manage.auth0.com/#/tenant/advanced).
2. Disable the **Ignore request Host header** toggle\*\*.\*\* Deactivating this toggle enforces validation for your tenant and completes the migration.

If hostname validation does not work as expected after disabling this toggle, you will receive a 4xx error to indicate your domain tenant and tenant associated with the `client_id` or `connection_id` are not the same.

Once all application migrations have been successfully performed and confirmed in production environments, then you can disable the switch permanently to ensure that the deprecated features can no longer be used. After June 9, 2022 in Public Cloud and September 9, 2022 in Private Cloud, Auth0 will enforce hostname validation and  the associated switch will be removed from your tenant settings.


# Product Release Stages
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages

Describes how we stage, release, and retire product functionality.

<Tooltip href="/docs/glossary?term=Product+release+stages">Product release stages</Tooltip> describe how we stage, release, and retire product functionality. Product features may not progress through all release stages, and the time in each stage will vary depending on the scope and impact of the feature.

## Beta

Beta releases give subscribers time to explore new product capabilities while providing feedback prior to a next stage release (which may be Early Access or General Availability depending on the feature). Beta features have been validated for a set of use cases but might have changes on the road to a General Availability release. Beta releases may be restricted to a select number of subscribers (private) or open to all subscribers (public).

When participating in a beta release, you should understand the following:

* We do not support beta functionalities for production use.
* Changes may occur that impact functionality, and we will communicate them as we are made aware.
* Your feedback will help prioritize improvements and fixes in a subsequent release.

## Early Access

Early Access releases are new or enhanced features made available for you to selectively opt-in to and use in both production and non-production environments. Minor changes can be expected on the road to General Availability. Early Access releases may be restricted to a select number of subscribers or rolled out to a subset of tenants (i.e. available only to tenants hosted in Japan).

## General Availability

General Availability releases are fully functional and available to all subscribers (limited by pricing tier or SKU purchase) for production use. Features in General Availability are supported and issues are addressed in accordance with your agreement with Okta.

## Deprecation

Deprecated features are not supported for use by new subscribers, are not actively being enhanced, and are being only minimally maintained. Tenants using the feature at the time of deprecation will continue to have access.

Deprecation begins when we introduce new behavior that customers would experience as a change that impacts core authentication functionality without mediation and ends when the old behavior moves into the End of Life product release stage. During Deprecation, customers should engage in a migration to move away from the deprecated feature or behavior. See [Migration Process](/docs/troubleshoot/product-lifecycle/migration-process) for details.

Although we know that deprecations can be disruptive, they are necessary to allow us to upgrade technology, improve security and service quality, and continue to invest in resources that provide the most value for our customers. As part of our commitment to transparency, we try to proactively notify subscribers when deprecations result in changes that alter use of Auth0. Additionally, we try to provide end-of-life notices with accompanying recommendations for migration and replacement capabilities where available.

## End of Life

Features that reach the End of Life stage are removed from the platform. Continued use of these features will likely result in errors.

## Learn more

* [Deprecations and Migrations](/docs/troubleshoot/product-lifecycle/deprecations-and-migrations)
* [Migration Process](/docs/troubleshoot/product-lifecycle/migration-process)


# Troubleshooting Tools
Source: https://auth0.com/docs/troubleshoot/troubleshooting-tools

Describes the tools available to help with troubleshooting.

* [Generate and Analyze HAR Files](/docs/troubleshoot/troubleshooting-tools/generate-and-analyze-har-files) - Learn how to troubleshoot with HAR files and the steps to generate a HAR file.
* [Sanitize HTTP Traces](/docs/troubleshoot/troubleshooting-tools/sanitize-http-traces) - Learn how to remove sensitive data from a HAR file.
* [Authentication API Debugger Extension](/docs/customize/extensions/authentication-api-debugger-extension) - Learn how to configure and use the Auth0 Authentication API Debugger extension.
* [JSON Web Token Inspector](https://jwt.io/) - Decode, verify and generate <Tooltip href="/docs/glossary?term=JWT">JWT</Tooltip>.

## Learn more

* [Logs](/docs/deploy-monitor/logs)
* [Monitor Auth0](/docs/deploy-monitor/monitor)
* [Monitor Applications](/docs/deploy-monitor/monitor/monitor-applications)
* [Monitor Auth0 Using System Center Operations Manager](/docs/deploy-monitor/monitor/monitor-using-scom)
* [Customer Support](/docs/troubleshoot/customer-support)
* [Open and Manage Support Tickets](/docs/troubleshoot/customer-support/open-and-manage-support-tickets)


# Generate and Analyze HAR Files
Source: https://auth0.com/docs/troubleshoot/troubleshooting-tools/generate-and-analyze-har-files

Learn how to troubleshoot with HAR files and steps to generate a HAR file.

A [HAR](https://en.wikipedia.org/wiki/.har) (HTTP Archive) file is a JSON-formatted log of a web browser's interactions with a web server.

A HAR file shows the sequence of redirects that happen during a login transaction, which makes it an excellent resource for debugging authentication issues. Including a HAR file in your [support requests](https://support.auth0.com) can help accelerate the troubleshooting process.

<Warning>
  Before sharing a HAR file with anyone (including Auth0), ensure that you remove or obfuscate all sensitive data, such as:

  * Confidential user information
  * Personal identifiable information (PII)
  * Confidential application information

  To learn more, read the following articles on [Auth0 Community](https://community.auth0.com):

  * [Sanitizing HTTP Traces](https://community.auth0.com/t/sanitizing-http-traces/119488)
  * [How to Sanitize an HTTP Trace File Automatically](https://community.auth0.com/t/how-to-sanitize-a-http-trace-file-automatically/120583)
  * [How to Manually Redact Sensitive Information](https://community.auth0.com/t/how-to-manually-redact-sensitive-information/122554)
  * [HAR File is Too Large to Upload to the Support Case](https://community.auth0.com/t/har-file-is-too-large-to-upload-to-the-support-case/122488)
</Warning>

## Generate HAR files

You can generate a HAR file within most web browsers using the built-in developer or inspector tools.

### Google Chrome

1. Close all **incognito** windows in Google Chrome.
2. Open a **new incognito** window in Google Chrome.
3. Go to **View > Developer > Developers Tools**.
4. In the Developer Tools pane, choose the **Network** tab.
5. Check the **Preserve Log** checkbox to record all interactions.
6. Visit the page and complete the steps that trigger the issue.
7. Choose the **Network** tab.
8. Click the down arrow to export the HAR file.
9. Save the HAR file.

### Safari

1. Ensure that **Show Develop menu in menu bar** checkbox is checked under **Safari > Preferences > Advanced**.
2. Choose **File > Open New Private Window**.
3. Choose **Show Web Inspector** in the **Developer** menu, then navigate to the **Network** tab.
4. To the right of **All** near the top-left of the Web Inspector, click the **Filter button** and choose **Preserve Log.**
5. Visit the web page where the issue occurs.
6. Choose **Develop > Show Web Inspector**. The Web Inspector window appears.
7. Complete the steps on the page that trigger the issue.
8. Select the **Network** tab.
9. Click **Export** on the upper right side of the pane.
10. Save the HAR file.

### Firefox

1. Close all **private** windows in Firefox.
2. Open a **new private** window in Firefox.
3. Go to **Tools > Developer > Network** (**Ctrl + Shift + E**).
4. Click the **Network** tab and choose **Persist Logs.**
5. Visit the page and complete the steps that trigger the issue.
6. Choose the **Network** tab and right click and then select **Save All As Har**.
7. Save the HAR file.

### Microsoft Edge

1. Close all **InPrivate** windows in Microsoft Edge.
2. Open a **new InPrivate** window (**Ctrl + Shift + N**).
3. Go to **Settings and more** (the **...** icon) then choose **More Tools > Developer Tools**.
4. Start a profiling session on the **Network** tab of the Developer Tools toolbar.
5. Visit the page and complete the steps that trigger the issue.
6. Select Export as HAR (**Ctrl + S**) and save the HAR file.

### Internet Explorer

1. Close all **InPrivate** windows in Internet Explorer.
2. Open a **new InPrivate** window in Internet Explorer (**Ctrl + Shift + P**).
3. Go to **Tools > F12 Developer Options > Network**.
4. Ensure **Clear entries on navigate** is switched off.
5. Visit the page and complete the steps that trigger the issue.
6. Choose the **Network** tab and select **Export as HAR** (**Ctrl + S**).
7. Save the HAR file.

## Analyze HAR files

Auth0 does not use and does not endorse using any third-party application, tool, or software to analyze HAR files.

After you have sanitized a HAR file, you can open it in a text-editor or browser to view the recorded events.

<Callout icon="file-lines">
  See [the Monitoring page](/docs/deploy-monitor/monitor) for more details on each of the log events that can help you troubleshoot issues.
</Callout>

## Learn more

* [Customer Support](/docs/troubleshoot/customer-support)
* [Open and Manage Support Tickets](/docs/troubleshoot/customer-support/open-and-manage-support-tickets)


# JSON Web Token Inspector
Source: https://auth0.com/docs/troubleshoot/troubleshooting-tools/jwt





# Auth0 APIs
Source: https://auth0.com/docs/api

Auth0 exposes the following APIs for developers to consume in their applications.

<div>
  <Card title="Authentication API" href="https://auth0.com/docs/api/authentication" />

  <AuthenticationApiSection />

  <Card title="Management API" href="https://auth0.com/docs/api/management/v2" />

  <ManagementApiSection />

  <Card title="My Account API" href="https://auth0.com/docs/api/myaccount" />

  <MyAccountApiSection />

  ***

  ## Pagination

  For Public Cloud tenants, Management API endpoints return a maximum of 50 results per response. When there are more results than can be returned in a response, include the `page` and `per_page` parameters in your request to retrieve more results.

  See [Migrate to Management API v2 Endpoint Paginated Queries](/docs/troubleshoot/product-lifecycle/past-migrations/migrate-to-paginated-queries) for information on updating your applications.
</div>


# Confirm the enrollment of a supported authentication method.
Source: https://auth0.com/docs/api/myaccount/authentication-methods/confirm-the-enrollment-of-a-supported-authentication-method

myaccount-api-oas post /authentication-methods/{authentication_method_id}/verify
Confirm the enrollment of a supported authentication method.

<ApiReleaseLifecycle />

<Scopes />


# Delete an authentication method by ID
Source: https://auth0.com/docs/api/myaccount/authentication-methods/delete-an-authentication-method-by-id

myaccount-api-oas delete /authentication-methods/{authentication_method_id}
Deletes a single authentication method belonging to the authenticated user.

<ApiReleaseLifecycle />

<Scopes />


# Get a list of authentication methods
Source: https://auth0.com/docs/api/myaccount/authentication-methods/get-a-list-of-authentication-methods

myaccount-api-oas get /authentication-methods
Retrieve detailed list of authentication methods belonging to the authenticated user.

<ApiReleaseLifecycle />

<Scopes />


# Get an authentication method by ID
Source: https://auth0.com/docs/api/myaccount/authentication-methods/get-an-authentication-method-by-id

myaccount-api-oas get /authentication-methods/{authentication_method_id}
Retrieves a single authentication method belonging to the authenticated user.

<ApiReleaseLifecycle />

<Scopes />


# Start the enrollment of a supported authentication method.
Source: https://auth0.com/docs/api/myaccount/authentication-methods/start-the-enrollment-of-a-supported-authentication-method

myaccount-api-oas post /authentication-methods
Start the enrollment of a supported authentication method.

<ApiReleaseLifecycle />

<Scopes />


# Update details of an authentication method by ID
Source: https://auth0.com/docs/api/myaccount/authentication-methods/update-details-of-an-authentication-method-by-id

myaccount-api-oas patch /authentication-methods/{authentication_method_id}
Updates a single authentication method

<ApiReleaseLifecycle />

<Scopes />


# Complete a connected account request
Source: https://auth0.com/docs/api/myaccount/connected-accounts/complete-a-connected-account-request

myaccount-api-oas post /connected-accounts/complete
Complete a previously started authorization flow to link the authenticated user's account with an external identity provider.

<ApiReleaseLifecycle />

<Scopes />


# Create a connected account request
Source: https://auth0.com/docs/api/myaccount/connected-accounts/create-a-connected-account-request

myaccount-api-oas post /connected-accounts/connect
Start an authorization flow to link the authenticated user's account with an external identity provider.

<ApiReleaseLifecycle />

<Scopes />


# Delete a connected account by ID
Source: https://auth0.com/docs/api/myaccount/connected-accounts/delete-a-connected-account-by-id

myaccount-api-oas delete /connected-accounts/accounts/{id}
Delete a connected account belonging to the authenticated user.

<ApiReleaseLifecycle />

<Scopes />


# Get a list of available connections for connected accounts
Source: https://auth0.com/docs/api/myaccount/connected-accounts/get-a-list-of-available-connections-for-connected-accounts

myaccount-api-oas get /connected-accounts/connections
Retrieve available connections that can be used for account linking by the authenticated user.

<ApiReleaseLifecycle />

<Scopes />


# Get a list of connected accounts
Source: https://auth0.com/docs/api/myaccount/connected-accounts/get-a-list-of-connected-accounts

myaccount-api-oas get /connected-accounts/accounts
Retrieve connected accounts belonging to the authenticated user.

<ApiReleaseLifecycle />

<Scopes />


# Get the status of all factors
Source: https://auth0.com/docs/api/myaccount/factors/get-the-status-of-all-factors

myaccount-api-oas get /factors
List of factors enabled for the Auth0 tenant and available for enrollment by this user.

<ApiReleaseLifecycle />

<Scopes />


# My Account API Reference
Source: https://auth0.com/docs/api/myaccount/index



<Badge>Version: 1.0 (Current)</Badge>

<Warning>
  <p>Limited Early Access</p>

  The My Account API is available in Limited Early Access. To request access, contact your Auth0 account manager. To learn more about Auth0's product release cycle, read [Product Release Stages](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

The Auth0 My Account API provides a dedicated set of endpoints for users to manage their own account information. Customers can use these APIs to build self-service experiences in their applications or progressively add details to a user account.

The My Account API operates within the context of the currently logged-in user and can be used directly within user-facing applications.

<Tip>
  <p>Using Auth0 domain vs. custom domain</p>

  The My Account API supports using your canonical Auth0 domain or your custom domain, but you must use the same one throughout the entire process, including:

  * Getting an access token
  * Setting the audience value
  * Calling the My Account API endpoint

  To learn more, read [Custom Domains](https://auth0.com/docs/customize/custom-domains).
</Tip>

## Activate the My Account API

You can activate the My Account API for your tenant in the Auth0 Dashboard:

1. Navigate to **Authentication > APIs**.
2. Locate the My Account API banner.
3. Select **Activate**.

<img />

By default, the My Account API is created with the following application API access policies:

`require_client_grant` for user flows

`deny_all` for client (machine-to-machine) flows

For an application to access the My Account API on the user's behalf, you must explicitly create a client grant for that application, which allows you to define the maximum scopes the application can request. Alternatively, you can change the policy for user access flows to `allow_all`, which allows any application in your tenant to request any scope from the My Account API.

Because the My Account API exposes sensitive information and operations, Auth0 does not recommend using `allow_all` for user access flows. You should follow a least privilege principle with the My Account API to ensure applications only get access to what they truly need, minimizing potential security risks.

The final permissions granted to the application will be determined by the intersection of the scopes allowed by the application API access policy, the Role-Based Access Control (RBAC) permissions assigned to the end user, and any user consent given (if applicable).

<Note>
  <p>Supported flows</p>

  You cannot update the application API policy for client access to the My Account API, which means you cannot access the My Account API using the Client Credentials Flow.
</Note>

To learn more about how to manage application API access policies and their associated client grants, read [Application Access to APIs: Client Grants](https://auth0.com/docs/get-started/applications/application-access-to-apis-client-grants).

## Get an access token

You can get an access token for the My Account API in the same way you'd get an access token for one of your own APIs.

<Note>
  <p>Sensitive operations</p>

  If you're going to allow the My Account API to perform sensitive operations (such as enrolling an authentication method), we strongly recommend that you use [step-up authentication](https://auth0.com/docs/secure/multi-factor-authentication/step-up-authentication) to enforce additional security policies through [multi-factor authentication (MFA)](https://auth0.com/docs/secure/multi-factor-authentication).
</Note>

If you're using Universal Login, read the following articles:

* [Call Your API Using the Authorization Code Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/call-your-api-using-the-authorization-code-flow)
* [Call Your API Using the Authorization Code Flow with PKCE](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/call-your-api-using-the-authorization-code-flow-with-pkce)

If you're using embedded login, read the following articles:

* [Call Your API Using Resource Owner Password Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow/call-your-api-using-resource-owner-password-flow)
* [Login Flow with Native Passkeys API](https://auth0.com/docs/native-passkeys-api#login-flow)

## Examples

### Universal Login with authorization code flow

**Step 1: Request authorization code**

```bash lines theme={null}
curl --request GET \
  --url 'https://{yourDomain}/authorize?response_type=code&client_id={yourClientId}&redirect_uri=%7ByourRedirectUri%7D&scope=create%3Ame%3Aauthentication_methods&offline_access=&audience=https%3A%2F%2F{yourDomain}%2Fme%2F'
```

**Step 2: Exchange code for access token**

```bash lines theme={null}
curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/json' \
  --data '{"grant_type": "authorization_code","client_id": "{yourClientId}","client_secret": "{yourClientId}","code": "{yourAuthorizationCode}","redirect_uri": "{yourRedirectUri}","audience": "{yourAudience}","scope": "create:me:authentication_methods","offline_access": ""}'
```

### Embedded login with native passkeys

**Step 1: Request login challenge**

```bash lines theme={null}
curl --request POST \
  --url 'https://{yourDomain}/passkey/challenge' \
  --header 'content-type: application/json' \
  --data '{"client_id": "{yourDomain}"}'
```

**Step 2: Authenticate existing user**

```bash lines theme={null}
curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/json' \
  --data '{  "grant_type": "urn:okta:params:oauth:grant-type:webauthn",  "client_id": "{yourClientId}",  "scope": "create:me:authentication_methods offline_access",  "audience": "https://{yourDomain}/me/"  "auth_session": "{sessionIdFromTheFirstRequest}",  "authn_response": "{authenticatorResponse}"}'
```

## Rate limits

During Early Access, the My Account API is limited at a tenant level to 25 requests per second.

### Authentication

<Tabs>
  <Tab title="HTTP: Bearer Auth">
    Bearer and DPoP tokens are supported depending on the API configuration

    |                            |        |
    | -------------------------- | ------ |
    | Security Scheme Type:      | http   |
    | HTTP Authorization Scheme: | bearer |
  </Tab>
</Tabs>


# Get Configuration
Source: https://auth0.com/docs/api/myorganization/config/get-configuration

myorganization-api-oas get /config
Retrieve the configuration for the /my-org API. This will return all stored client information with the exception of attributes that are identifiers. Identifier attributes will be given their own endpoint that will return the full object. This will give the components all of the information they will need to be successful. The SDK provider for the components should manage fetching and caching this information for all components.

<ApiReleaseLifecycle />

<Scopes />


# Get Identity Providers Configuration
Source: https://auth0.com/docs/api/myorganization/config/get-identity-providers-configuration

myorganization-api-oas get /config/identity-providers
Retrieve the connection profile for the application. This will give the components all of the information they will need to be successful. The SDK provider for the components should manage fetching and caching this information for all components.

<ApiReleaseLifecycle />

<Scopes />


# Create Identity Provider
Source: https://auth0.com/docs/api/myorganization/idp-management/create-identity-provider

myorganization-api-oas post /identity-providers
Create an identity provider associated with this organization.

<ApiReleaseLifecycle />

<Scopes />


# Delete Identity Provider
Source: https://auth0.com/docs/api/myorganization/idp-management/delete-identity-provider

myorganization-api-oas delete /identity-providers/{idp_id}
Delete an identity provider from this organization.

<ApiReleaseLifecycle />

<Scopes />


# Detach Identity Provider from Organization
Source: https://auth0.com/docs/api/myorganization/idp-management/detach-identity-provider-from-organization

myorganization-api-oas post /identity-providers/{idp_id}/detach
Delete underlying identity provider from this organization.

<ApiReleaseLifecycle />

<Scopes />


# Get Identity Provider
Source: https://auth0.com/docs/api/myorganization/idp-management/get-identity-provider

myorganization-api-oas get /identity-providers/{idp_id}
Retrieve the details for one particular identity-provider.

<ApiReleaseLifecycle />

<Scopes />


# List Identity Providers
Source: https://auth0.com/docs/api/myorganization/idp-management/list-identity-providers

myorganization-api-oas get /identity-providers
List the identity providers associated with this organization.

<ApiReleaseLifecycle />

<Scopes />


# Refresh Identity Provider Attributes Mapping
Source: https://auth0.com/docs/api/myorganization/idp-management/refresh-identity-provider-attributes-mapping

myorganization-api-oas put /identity-providers/{idp_id}/update-attributes
Triggers a refresh of attribute mappings on the identity provider by overriding it with the admin defined defaults. The endpoint doesn't accept any body parameters.

<ApiReleaseLifecycle />

<Scopes />


# Update Identity Provider
Source: https://auth0.com/docs/api/myorganization/idp-management/update-identity-provider

myorganization-api-oas patch /identity-providers/{idp_id}
Update an identity provider associated with this organization.

<ApiReleaseLifecycle />

<Scopes />


# My Organization API Reference
Source: https://auth0.com/docs/api/myorganization/index

Documentation for Auth0's My Organization API



# Get organization details
Source: https://auth0.com/docs/api/myorganization/org-details/get-organization-details

myorganization-api-oas get /details
Retrieve details for an Organization.

<ApiReleaseLifecycle />

<Scopes />


# Modify organization details
Source: https://auth0.com/docs/api/myorganization/org-details/modify-organization-details

myorganization-api-oas patch /details
Update the details of a specific Organization, such as display name and branding options.

<ApiReleaseLifecycle />

<Scopes />


# Create a Domain for an Organization
Source: https://auth0.com/docs/api/myorganization/org-domain-management/create-a-domain-for-an-organization

myorganization-api-oas post /domains
Create a new domain for an organization.

<ApiReleaseLifecycle />

<Scopes />


# Delete Domain from Organization
Source: https://auth0.com/docs/api/myorganization/org-domain-management/delete-domain-from-organization

myorganization-api-oas delete /domains/{domain_id}
Remove a domain from this organization.

<ApiReleaseLifecycle />

<Scopes />


# Get Identity Providers associated with an Organization Domain
Source: https://auth0.com/docs/api/myorganization/org-domain-management/get-identity-providers-associated-with-an-organization-domain

myorganization-api-oas get /domains/{domain_id}/identity-providers
Retrieve the list of identity providers that have a specific organization domain alias.

<ApiReleaseLifecycle />

<Scopes />


# Get Organization Domain
Source: https://auth0.com/docs/api/myorganization/org-domain-management/get-organization-domain

myorganization-api-oas get /domains/{domain_id}
Retrieve a domain for an organization.

<ApiReleaseLifecycle />

<Scopes />


# List Organization Domains
Source: https://auth0.com/docs/api/myorganization/org-domain-management/list-organization-domains

myorganization-api-oas get /domains
Lists all domains pending and verified for an organization.

<ApiReleaseLifecycle />

<Scopes />


# Start Domain Verification
Source: https://auth0.com/docs/api/myorganization/org-domain-management/start-domain-verification

myorganization-api-oas post /domains/{domain_id}/verify
Get a verification text and start the domain verification process for a particular domain.

<ApiReleaseLifecycle />

<Scopes />


# Agent Skills for Auth0
Source: https://auth0.com/docs/quickstart/agent-skills

Use Auth0 agent skills to quickly integrate authentication into your applications with AI coding assistants

Agent skills are structured instruction sets that help AI coding assistants like Claude Code, Cursor, and GitHub Copilot implement Auth0 authentication correctly in your applications. They contain best practices, code patterns, and step-by-step guidance for Auth0 integration across multiple frameworks and platforms.

## Why use agent skills?

Agent skills enable you to:

* **Accelerate development** - Implement Auth0 authentication in minutes with AI-powered code generation
* **Follow best practices** - Get production-ready code that follows Auth0's recommended patterns
* **Support multiple frameworks** - Use the same skills across React, Vue, Angular, Next.js, and more
* **Migrate easily** - Transition from other auth providers with guided migration workflows
* **Implement advanced features** - Add multi-factor authentication and security features with expert guidance

## Supported platforms

Auth0 agent skills support a wide range of frameworks and platforms:

* **Frontend:** React, Vue, Angular
* **Backend:** Next.js, Nuxt, Express, Ruby on Rails, PHP/Laravel
* **Mobile:** React Native, Expo, iOS, Android
* **APIs:** Python (Flask, FastAPI), Go, Spring Boot, ASP.NET Core

## Installation

Auth0 provides two complementary skill packages that work together:

* **Auth0 Core Skills** - Essential foundational capabilities including framework detection, migrations, and MFA
* **Auth0 SDK Skills** - Framework-specific implementation guides for each supported platform

### Install with Skills CLI

The easiest way to install Auth0 agent skills is using the Skills CLI:

```bash theme={null}
npx skills add auth0/agent-skills
```

This command installs both the core and SDK skill packages, making them available to your AI coding assistant.

### Install in Claude Code

If you're using Claude Code, you can install Auth0 skills directly from the Plugins menu:

<Steps>
  <Step title="Open Claude Code settings">
    Navigate to **Settings** > **Plugins** in Claude Code.
  </Step>

  <Step title="Search for Auth0">
    Search for "Auth0" in the available plugins list.
  </Step>

  <Step title="Install the skills">
    Install both **Auth0 Core Skills** and **Auth0 SDK Skills** plugins.
  </Step>
</Steps>

<Tip>
  Installing skills as plugins in Claude Code (recommended for enterprise users) ensures they stay up to date automatically.
</Tip>

### Manual installation

You can also install skills manually by cloning the repository:

```bash theme={null}
git clone https://github.com/auth0/agent-skills.git
```

Then copy the skill directories to your AI assistant's skills folder according to its documentation.

## Available skills

Auth0 agent skills are organized into two packages with complementary capabilities:

### Core Skills

| Skill                  | Description                                                     | Use Cases                                               |
| ---------------------- | --------------------------------------------------------------- | ------------------------------------------------------- |
| **Quickstart Router**  | Framework detection and routing to appropriate Auth0 SDK guides | Starting Auth0 integration, detecting your tech stack   |
| **Migration Guide**    | Step-by-step migration from other auth providers                | Moving from Firebase, Cognito, Supabase, or custom auth |
| **MFA Implementation** | Multi-factor authentication setup and configuration             | Adding 2FA, step-up auth, adaptive MFA                  |

### SDK Skills

| Skill                        | Description                                          | Use Cases                                                 |
| ---------------------------- | ---------------------------------------------------- | --------------------------------------------------------- |
| **React Integration**        | Auth0 React SDK setup for single-page applications   | Building React apps with Vite or Create React App         |
| **Next.js Integration**      | Auth0 Next.js SDK for App Router and Pages Router    | Server and client-side auth in Next.js applications       |
| **Vue Integration**          | Auth0 Vue SDK setup for Vue 3 applications           | Building Vue apps with Vite or Vue CLI                    |
| **Angular Integration**      | Auth0 Angular SDK with route guards and interceptors | Enterprise Angular applications                           |
| **React Native Integration** | Auth0 React Native SDK with native deep linking      | iOS and Android mobile apps with Expo or React Native CLI |
| **Nuxt Integration**         | Auth0 Nuxt SDK for Nuxt 3/4 applications             | Server-side rendering and hybrid apps with Nuxt           |
| **Express Integration**      | Auth0 Express SDK for traditional web apps           | Server-rendered applications with session management      |

## Using agent skills

Once installed, you can use Auth0 agent skills by making natural language requests to your AI coding assistant. The assistant will automatically select and apply the appropriate skills.

### Example prompts

**Getting started with a new integration:**

```
Add Auth0 authentication to my React app
```

**Implementing specific features:**

```
Add multi-factor authentication with TOTP support
```

**Migrating from another provider:**

```
Help me migrate from Firebase Auth to Auth0
```

**Framework-specific requests:**

```
Set up Auth0 in my Next.js App Router project with protected routes
```

<Info>
  The quickstart router skill automatically detects your framework and routes to the appropriate SDK guide, so you don't need to specify which skill to use.
</Info>

## How agent skills work

Agent skills follow a structured workflow:

<Steps>
  <Step title="Framework detection">
    The AI assistant analyzes your project files to identify your framework, dependencies, and setup.
  </Step>

  <Step title="Skill selection">
    Based on your request and detected framework, the assistant selects the appropriate Auth0 skill.
  </Step>

  <Step title="Code generation">
    The skill provides step-by-step guidance and code patterns that the assistant uses to generate production-ready code.
  </Step>

  <Step title="Configuration">
    The assistant helps you configure Auth0 settings, environment variables, and SDK options.
  </Step>

  <Step title="Verification">
    You can test the implementation and ask the assistant to make adjustments as needed.
  </Step>
</Steps>

## Best practices

When working with Auth0 agent skills:

* **Start with clean state** - Skills work best in projects with clear structure and up-to-date dependencies
* **Review generated code** - Always review the code generated by your AI assistant before deploying
* **Follow prompts** - The assistant may ask for your Auth0 domain, client ID, and other configuration values
* **Test thoroughly** - Verify authentication flows work correctly in your development environment
* **Consult documentation** - Reference the full Auth0 documentation for advanced configuration and troubleshooting

## Limitations and considerations

* **AI assistant required** - Agent skills work with AI coding assistants and are not standalone tools
* **Project context** - Skills work best when the AI assistant has access to your full project context
* **Manual configuration** - You'll still need to configure your Auth0 tenant and create applications in the Auth0 Dashboard
* **Framework versions** - Skills target recent stable versions of frameworks; very old or experimental versions may require manual adjustments

## Learn more

<CardGroup>
  <Card title="Auth0 Agent Skills on GitHub" icon="github" href="https://github.com/auth0/agent-skills">
    View the source code and contribution guidelines.
  </Card>

  <Card title="Agent Skills Format" icon="book" href="https://agentskills.io">
    Learn about the open agent skills format and specification.
  </Card>

  <Card title="Auth0 Quickstarts" icon="rocket" href="/quickstart">
    Follow manual quickstart guides for your framework.
  </Card>

  <Card title="Auth0 SDKs" icon="code" href="/sdks">
    Explore Auth0 SDK documentation and API references.
  </Card>
</CardGroup>

## Get help

If you encounter issues with Auth0 agent skills:

* **Ask your AI assistant** - Try rephrasing your request or providing more context
* **Check the repository** - Review [example implementations](https://github.com/auth0/agent-skills) and open issues
* **Report bugs** - Follow Auth0's [Responsible Disclosure Program](https://auth0.com/responsible-disclosure-policy) for security issues
* **Contact support** - Reach out to Auth0 support for questions about Auth0 configuration


# ASP.NET Core Web API
Source: https://auth0.com/docs/quickstart/backend/aspnet-core-webapi/index

Add Auth0 JWT authentication to an ASP.NET Core Web API with protected endpoints

<Callout icon="pencil">
  This Quickstart is currently in **Beta**. We'd love to hear your feedback!
</Callout>

<Accordion title="AI Prompt" icon="microchip-ai">
  **Using AI to integrate Auth0?** Add this prompt to Cursor, Windsurf, Copilot, Claude Code or your favourite AI-powered IDE to speed up development.

  ```markdown expandable theme={null}
  Integrate the Auth0 ASP.NET Core API SDK into a .NET Web API

  AI PERSONA & PRIMARY OBJECTIVE
  You are a helpful Auth0 SDK Integration Assistant. Your primary function is to execute commands to set up a development environment for Auth0 in ASP.NET Core. Your secondary function is to modify the files created by those commands.

  CRITICAL BEHAVIORAL INSTRUCTIONS
  1.  CHECK EXISTING PROJECT FIRST: Before creating a new project, check if the current directory already contains a .NET project (*.csproj file). If it does, skip project creation and work with the existing project.
  2.  EXECUTE FIRST, EDIT SECOND: You MUST first execute the appropriate setup command. Do not show, suggest, or create any files until the setup is complete.
  3.  NO PLANNING: DO NOT propose a directory structure. DO NOT show a file tree. Your first action must be to run the appropriate command.
  4.  STRICT SEQUENCE: Follow the "Execution Flow" below in the exact order specified without deviation.

  EXECUTION FLOW

  Step 1: Check for Existing .NET Project and Prerequisites
  FIRST, verify prerequisites and check for existing .NET project:

    # Check if .NET SDK is available
    dotnet --version

  Then examine the current directory:

    # Check for existing .NET project
    if ls *.csproj 1> /dev/null 2>&1; then
      echo "Found .csproj file, checking project type..."
      ls -la *.csproj
    else
      echo "No .csproj found, will create new project"
    fi

  Based on the results:
  - If *.csproj exists and is a Web API project, proceed to Step 1b (install Auth0 SDK only)
  - If no .NET project exists, proceed to Step 1a (create new project)

  Step 1a: Create New Project and Install the SDK
  If an existing Web API project exists, simply install the SDK:
  dotnet add package Auth0.AspNetCore.Authentication.Api
  Otherwise, create a new project and install the SDK:

    dotnet new webapi -n Auth0Api && cd Auth0Api && dotnet add package Auth0.AspNetCore.Authentication.Api

  Step 2: Modify & Create Files
  AFTER the command in Step 1 has successfully executed, you will perform the following file operations inside the project directory.

  2.1: Setup Auth0 configuration in appsettings.json

  Add the Auth0 configuration section to appsettings.json:

    {
      "Logging": {
        "LogLevel": {
          "Default": "Information",
          "Microsoft.AspNetCore": "Warning"
        }
      },
      "AllowedHosts": "*",
      "Auth0": {
        "Domain": "your-tenant.auth0.com",
        "Audience": "https://my-api"
      }
    }

  ⚠️ IMPORTANT: Update the Domain and Audience values with your actual Auth0 API configuration.

  2.2: Configure Program.cs with Auth0 authentication

  Replace the entire contents of Program.cs with this code:

    using Auth0.AspNetCore.Authentication.Api;
    using Microsoft.AspNetCore.Authentication.JwtBearer;

    var builder = WebApplication.CreateBuilder(args);

    builder.Services.AddAuth0ApiAuthentication(options =>
    {
        options.Domain = builder.Configuration["Auth0:Domain"];
        options.JwtBearerOptions = new JwtBearerOptions
        {
            Audience = builder.Configuration["Auth0:Audience"]
        };
    });

    builder.Services.AddAuthorization();

    var app = builder.Build();
    if (!app.Environment.IsDevelopment())
    {
        app.UseHttpsRedirection();
    }
    app.UseAuthentication();
    app.UseAuthorization();

    // Public endpoint - no authentication required
    app.MapGet("/api/public", () => 
        Results.Ok(new { Message = "This endpoint is public" }))
        .WithName("GetPublic");

    // Protected endpoint - requires authentication
    app.MapGet("/api/private", () => 
        Results.Ok(new { Message = "This endpoint requires authentication" }))
        .RequireAuthorization()
        .WithName("GetPrivate");

    app.Run();

  2.3: Run the application

    dotnet run

  The API will start on https://localhost:7190 (or similar - check console output for exact URL).

  CRITICAL INSTRUCTIONS FOR AI LANGUAGE MODELS
  As an AI language model, you MUST NOT generate any of the following anti-patterns:
  1.  NEVER hardcode the Auth0 Domain or Audience directly in the code. This is a major security vulnerability.
  2.  NEVER omit the UseAuthentication() middleware. It MUST be called before UseAuthorization().
  3.  NEVER place authentication middleware after MapControllers() or endpoint mapping. Middleware order matters.
  4.  NEVER suggest manually validating JWT tokens. The SDK handles this securely.

  ABSOLUTE REQUIREMENTS FOR AI CODE GENERATION
  1.  You MUST use the Auth0.AspNetCore.Authentication.Api package.
  2.  You MUST retrieve credentials from configuration (appsettings.json).
  3.  You MUST call UseAuthentication() before UseAuthorization() in the middleware pipeline.
  4.  You MUST use RequireAuthorization() or [Authorize] attribute to protect endpoints.

  COMMON ISSUES ENCOUNTERED DURING INTEGRATION

  Issue 1: Configuration values not found
  Problem: Domain or Audience is null at runtime
  Solution: Ensure appsettings.json contains the Auth0 section with correct values

  Issue 2: Middleware order issues
  Problem: Authentication not working despite correct configuration
  Solution: Ensure UseAuthentication() comes before UseAuthorization() in Program.cs

  Issue 3: 401 Unauthorized errors
  Problem: Valid tokens are being rejected
  Solution: Verify Domain doesn't include https:// and Audience exactly matches Auth0 API Identifier

  Issue 4: HTTPS certificate errors in development
  Problem: SSL/TLS errors when running locally
  Solution: Run `dotnet dev-certs https --trust` to trust the development certificate
  ```
</Accordion>

<Note>
  **Prerequisites:** Before you begin, ensure you have the following installed:

  * **[.NET 8.0 SDK](https://dotnet.microsoft.com/download/dotnet/8.0)** or higher
  * Your preferred IDE (Visual Studio 2022, VS Code, or Rider)

  **.NET Version Compatibility:** This quickstart works with **.NET 8.0** and newer.
</Note>

## Get Started

This quickstart demonstrates how to add Auth0 JWT authentication to an ASP.NET Core Web API. You'll build a secure API with protected endpoints using the Auth0 ASP.NET Core API SDK.

<Steps>
  <Step title="Create a new project">
    Create a new ASP.NET Core Web API project for this Quickstart

    ```bash theme={null}
    dotnet new webapi -n Auth0Api
    ```

    Open the project

    ```bash theme={null}
    cd Auth0Api
    ```
  </Step>

  <Step title="Install the Auth0 SDK">
    ```bash theme={null}
    dotnet add package Auth0.AspNetCore.Authentication.Api
    ```
  </Step>

  <Step title="Setup your Auth0 API">
    Next up, you need to create a new API on your Auth0 tenant and add the configuration to your project.

    You can choose to do this automatically by running a CLI command or do it manually via the Dashboard:

    <Tabs>
      <Tab title="CLI">
        Run the following shell command on your project's root directory to create an Auth0 API and update your `appsettings.json` file:

        <Tabs>
          <Tab title="Mac/Linux">
            ```bash theme={null}
            AUTH0_API_NAME="My ASP.NET Core API" && \
            AUTH0_API_IDENTIFIER="https://my-api" && \
            brew tap auth0/auth0-cli && \
            brew install auth0 && \
            auth0 login --no-input && \
            auth0 apis create -n "${AUTH0_API_NAME}" -i "${AUTH0_API_IDENTIFIER}" --offline-access --token-lifetime 86400 --signing-alg RS256 --json > auth0-api-details.json && \
            DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name') && \
            AUDIENCE=$(jq -r '.identifier' auth0-api-details.json) && \
            jq --arg domain "$DOMAIN" --arg audience "$AUDIENCE" \
              '.Auth0.Domain = $domain | .Auth0.Audience = $audience' \
              appsettings.json > appsettings.tmp.json && \
            mv appsettings.tmp.json appsettings.json && \
            rm auth0-api-details.json && \
            echo "✅ appsettings.json updated with your Auth0 API details:" && \
            cat appsettings.json
            ```
          </Tab>

          <Tab title="Windows (PowerShell)">
            ```powershell theme={null}
            $ApiName = "My ASP.NET Core API"
            $ApiIdentifier = "https://my-api"
            $latestRelease = Invoke-RestMethod -Uri "https://api.github.com/repos/auth0/auth0-cli/releases/latest"
            $latestVersion = $latestRelease.tag_name
            $version = $latestVersion -replace "^v"
            Invoke-WebRequest -Uri "https://github.com/auth0/auth0-cli/releases/download/${latestVersion}/auth0-cli_${version}_Windows_x86_64.zip" -OutFile ".\auth0.zip"
            Expand-Archive ".\auth0.zip" .\
            [System.Environment]::SetEnvironmentVariable('PATH', $Env:PATH + ";${pwd}")
            auth0 login --no-input
            auth0 apis create -n "$ApiName" -i "$ApiIdentifier" --offline-access --token-lifetime 86400 --signing-alg RS256 --json | Set-Content -Path auth0-api-details.json
            $Domain = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name
            $Audience = (Get-Content -Raw auth0-api-details.json | ConvertFrom-Json).identifier
            $Config = Get-Content -Raw appsettings.json | ConvertFrom-Json
            if (-not $Config.Auth0) { $Config | Add-Member -MemberType NoteProperty -Name Auth0 -Value @{} }
            $Config.Auth0.Domain = $Domain
            $Config.Auth0.Audience = $Audience
            $Config | ConvertTo-Json -Depth 10 | Set-Content appsettings.json
            Remove-Item auth0-api-details.json
            Write-Output "✅ appsettings.json updated with your Auth0 API details:"
            Get-Content appsettings.json
            ```
          </Tab>
        </Tabs>
      </Tab>

      <Tab title="Dashboard">
        Before you start, add Auth0 configuration to your `appsettings.json` file

        ```json appsettings.json theme={null}
        {
          "Logging": {
            "LogLevel": {
              "Default": "Information",
              "Microsoft.AspNetCore": "Warning"
            }
          },
          "AllowedHosts": "*",
          "Auth0": {
            "Domain": "YOUR_AUTH0_DOMAIN",
            "Audience": "YOUR_AUTH0_API_IDENTIFIER"
          }
        }
        ```

        1. Go to [Auth0 Dashboard](https://manage.auth0.com) → **Applications** → **APIs**
        2. Click **Create API**
        3. Enter your API details:
           * **Name**: My ASP.NET Core API
           * **Identifier**: `https://my-api` (this becomes your Audience)
           * **Signing Algorithm**: RS256
        4. Click **Create**
        5. Replace `YOUR_AUTH0_DOMAIN` in `appsettings.json` with your **Domain** from the Test tab (e.g., `your-tenant.auth0.com`)
        6. Replace `YOUR_AUTH0_API_IDENTIFIER` in `appsettings.json` with your **Identifier** (e.g., `https://my-api`)

        <Info>
          Your **Domain** should not include `https://` - use only the domain name (e.g., `your-tenant.auth0.com`).

          The **Audience** (API Identifier) is a unique identifier for your API and can be any valid URI. It doesn't need to be a publicly accessible URL.
        </Info>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure authentication">
    Replace the entire contents of `Program.cs` with the following code:

    ```csharp Program.cs lines theme={null}
    using Auth0.AspNetCore.Authentication.Api;
    using Microsoft.AspNetCore.Authentication.JwtBearer;

    var builder = WebApplication.CreateBuilder(args);

    builder.Services.AddAuth0ApiAuthentication(options =>
    {
        options.Domain = builder.Configuration["Auth0:Domain"];
        options.JwtBearerOptions = new JwtBearerOptions
        {
            Audience = builder.Configuration["Auth0:Audience"]
        };
    });

    builder.Services.AddAuthorization();

    var app = builder.Build();

    if (!app.Environment.IsDevelopment())
    {
        app.UseHttpsRedirection();
    }

    app.UseAuthentication();
    app.UseAuthorization();

    app.Run();
    ```
  </Step>

  <Step title="Create public and protected endpoints">
    Add endpoints to test authentication. Add the following code in `Program.cs` before `app.Run()`:

    ```csharp Program.cs theme={null}
    // Public endpoint - no authentication required
    app.MapGet("/api/public", () => 
        Results.Ok(new { Message = "This endpoint is public" }))
        .WithName("GetPublic");

    // Protected endpoint - requires authentication
    app.MapGet("/api/private", () => 
        Results.Ok(new { Message = "This endpoint requires authentication" }))
        .RequireAuthorization()
        .WithName("GetPrivate");
    ```
  </Step>

  <Step title="Run your API">
    ```bash theme={null}
    dotnet run
    ```

    Your API is now running on `https://localhost:7190` (or similar - check your console output for the exact URL).
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a fully functional Auth0-protected API running on your [localhost](https://localhost:7190/)
</Check>

***

## Advanced Usage

<Accordion title="Calling Protected APIs">
  Test your protected endpoints with an access token.

  **1. Get an access token** from Auth0 using the Client Credentials flow:

  ```bash theme={null}
  curl --request POST \
    --url https://YOUR_DOMAIN/oauth/token \
    --header 'content-type: application/json' \
    --data '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","audience":"YOUR_AUDIENCE","grant_type":"client_credentials"}'
  ```

  <Info>
    To get `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET`, create a Machine to Machine Application in the [Auth0 Dashboard](https://manage.auth0.com/#/applications) and authorize it for your API.
  </Info>

  **2. Test the public endpoint** (should return 200 OK):

  ```bash theme={null}
  curl https://localhost:7190/api/public
  ```

  **3. Test the protected endpoint without authentication** (should return 401 Unauthorized):

  ```bash theme={null}
  curl https://localhost:7190/api/private
  ```

  **4. Call the protected endpoint with the token:**

  ```bash theme={null}
  curl https://localhost:7190/api/private \
    --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```
</Accordion>

<Accordion title="Using Controller-Based Endpoints">
  For larger APIs, use controllers instead of minimal API endpoints.

  **1. Add controllers support:**

  ```csharp Program.cs theme={null}
  builder.Services.AddControllers();

  var app = builder.Build();

  if (!app.Environment.IsDevelopment())
  {
      app.UseHttpsRedirection();
  }

  app.UseAuthentication();
  app.UseAuthorization();

  app.MapControllers();

  app.Run();
  ```

  **2. Create a controller:**

  Create `Controllers/MessagesController.cs`:

  ```csharp Controllers/MessagesController.cs theme={null}
  using Microsoft.AspNetCore.Authorization;
  using Microsoft.AspNetCore.Mvc;

  namespace Auth0Api.Controllers;

  [ApiController]
  [Route("api/[controller]")]
  public class MessagesController : ControllerBase
  {
      [HttpGet]
      public IActionResult GetPublic()
      {
          return Ok(new { Message = "This endpoint is public" });
      }

      [Authorize]
      [HttpGet("private")]
      public IActionResult GetPrivate()
      {
          var userId = User.FindFirst("sub")?.Value;
          return Ok(new { Message = "This endpoint is protected", UserId = userId });
      }

      [Authorize(Policy = "read:messages")]
      [HttpGet("messages")]
      public IActionResult GetMessages()
      {
          return Ok(new { Messages = new[] { "Message 1", "Message 2" } });
      }
  }
  ```
</Accordion>

<Accordion title="Protecting Routes with Scope-Based Authorization">
  Protect endpoints based on specific scopes in the access token.

  **1. Define scopes in your Auth0 API:**

  In the [Auth0 Dashboard](https://manage.auth0.com) → APIs → Your API → Permissions, add scopes:

  * `read:messages` - Read messages
  * `write:messages` - Write messages

  **2. Configure authorization policies:**

  ```csharp Program.cs theme={null}
  builder.Services.AddAuthorization(options =>
  {
      options.AddPolicy("read:messages", policy =>
          policy.RequireClaim("scope", "read:messages"));
      
      options.AddPolicy("write:messages", policy =>
          policy.RequireClaim("scope", "write:messages"));
  });
  ```

  **3. Apply policies to endpoints:**

  ```csharp theme={null}
  app.MapGet("/api/messages", () => 
      Results.Ok(new { Messages = new[] { "Message 1", "Message 2" } }))
      .RequireAuthorization("read:messages");

  app.MapPost("/api/messages", () => 
      Results.Created("/api/messages/1", new { Id = 1, Text = "New message" }))
      .RequireAuthorization("write:messages");
  ```

  When requesting an access token, include the required scope:

  ```bash theme={null}
  curl --request POST \
    --url https://YOUR_DOMAIN/oauth/token \
    --header 'content-type: application/json' \
    --data '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","audience":"YOUR_AUDIENCE","grant_type":"client_credentials","scope":"read:messages write:messages"}'
  ```
</Accordion>

<Accordion title="Using DPoP for Enhanced Security">
  DPoP (Demonstration of Proof-of-Possession) binds access tokens to cryptographic keys, preventing token theft and replay attacks.

  **Enable DPoP support:**

  ```csharp Program.cs theme={null}
  builder.Services.AddAuth0ApiAuthentication(options =>
  {
      options.Domain = builder.Configuration["Auth0:Domain"];
      options.JwtBearerOptions = new JwtBearerOptions
      {
          Audience = builder.Configuration["Auth0:Audience"]
      };
  }).WithDPoP();  // Enable DPoP with default settings
  ```

  **DPoP Modes:**

  Accept both DPoP and Bearer tokens (default):

  ```csharp theme={null}
  using Auth0.AspNetCore.Authentication.Api.DPoP;

  .WithDPoP(dpopOptions =>
  {
      dpopOptions.Mode = DPoPModes.Allowed;
  });
  ```

  Only accept DPoP tokens, reject Bearer tokens:

  ```csharp theme={null}
  using Auth0.AspNetCore.Authentication.Api.DPoP;

  .WithDPoP(dpopOptions =>
  {
      dpopOptions.Mode = DPoPModes.Required;
  });
  ```

  Configure time validation parameters:

  ```csharp theme={null}
  .WithDPoP(dpopOptions =>
  {
      dpopOptions.Mode = DPoPModes.Allowed;
      dpopOptions.IatOffset = 300;  // Allow DPoP proof up to 5 minutes old
      dpopOptions.Leeway = 30;      // 30 seconds clock skew tolerance
  });
  ```

  <Info>
    Learn more about DPoP in the [Auth0 DPoP Documentation](https://auth0.com/docs/secure/sender-constraining/demonstrating-proof-of-possession-dpop).
  </Info>
</Accordion>

<Accordion title="Implementing Custom Authorization Policies">
  Create reusable authorization policies for complex requirements.

  **1. Create a custom requirement:**

  ```csharp Authorization/HasScopeRequirement.cs theme={null}
  using Microsoft.AspNetCore.Authorization;

  namespace Auth0Api.Authorization;

  public class HasScopeRequirement : IAuthorizationRequirement
  {
      public string Scope { get; }
      public string Issuer { get; }

      public HasScopeRequirement(string scope, string issuer)
      {
          Scope = scope;
          Issuer = issuer;
      }
  }
  ```

  **2. Create a handler:**

  ```csharp Authorization/HasScopeHandler.cs theme={null}
  using Microsoft.AspNetCore.Authorization;

  namespace Auth0Api.Authorization;

  public class HasScopeHandler : AuthorizationHandler<HasScopeRequirement>
  {
      protected override Task HandleRequirementAsync(
          AuthorizationHandlerContext context,
          HasScopeRequirement requirement)
      {
          if (!context.User.HasClaim(c => c.Type == "scope" && c.Issuer == requirement.Issuer))
          {
              return Task.CompletedTask;
          }

          var scopes = context.User
              .FindFirst(c => c.Type == "scope" && c.Issuer == requirement.Issuer)?
              .Value.Split(' ');

          if (scopes?.Any(s => s == requirement.Scope) == true)
          {
              context.Succeed(requirement);
          }

          return Task.CompletedTask;
      }
  }
  ```

  **3. Register and use the policy:**

  ```csharp Program.cs theme={null}
  using Auth0Api.Authorization;

  var builder = WebApplication.CreateBuilder(args);

  var domain = $"https://{builder.Configuration["Auth0:Domain"]}";

  builder.Services.AddAuth0ApiAuthentication(options =>
  {
      options.Domain = builder.Configuration["Auth0:Domain"];
      options.JwtBearerOptions = new JwtBearerOptions
      {
          Audience = builder.Configuration["Auth0:Audience"]
      };
  });

  builder.Services.AddAuthorization(options =>
  {
      options.AddPolicy("read:messages", policy =>
          policy.Requirements.Add(new HasScopeRequirement("read:messages", domain)));
  });

  builder.Services.AddSingleton<IAuthorizationHandler, HasScopeHandler>();

  var app = builder.Build();
  // ... rest of configuration
  ```
</Accordion>

<Accordion title="Accessing User Information">
  Extract user information from the authenticated token.

  ```csharp theme={null}
  app.MapGet("/api/user-info", (HttpContext context) =>
  {
      var userId = context.User.FindFirst("sub")?.Value;
      var email = context.User.FindFirst("email")?.Value;
      var name = context.User.FindFirst("name")?.Value;
      var scopes = context.User.FindAll("scope")
          .SelectMany(c => c.Value.Split(' '))
          .Distinct();

      return Results.Ok(new
      {
          UserId = userId,
          Email = email,
          Name = name,
          Scopes = scopes
      });
  })
  .RequireAuthorization();
  ```
</Accordion>

<Accordion title="Custom Token Validation">
  Customize JWT token validation parameters for specific requirements.

  ```csharp Program.cs theme={null}
  using Microsoft.IdentityModel.Tokens;
  using System.Security.Claims;

  builder.Services.AddAuth0ApiAuthentication(options =>
  {
      options.Domain = builder.Configuration["Auth0:Domain"];
      options.JwtBearerOptions = new JwtBearerOptions
      {
          Audience = builder.Configuration["Auth0:Audience"],
          
          TokenValidationParameters = new TokenValidationParameters
          {
              ValidateIssuerSigningKey = true,
              ValidateIssuer = true,
              ValidateAudience = true,
              ValidateLifetime = true,
              ClockSkew = TimeSpan.FromMinutes(5),
              NameClaimType = ClaimTypes.NameIdentifier,
              RoleClaimType = "https://my-app.com/roles"
          },
          
          Events = new JwtBearerEvents
          {
              OnAuthenticationFailed = context =>
              {
                  Console.WriteLine($"Authentication failed: {context.Exception.Message}");
                  return Task.CompletedTask;
              },
              
              OnTokenValidated = context =>
              {
                  var userId = context.Principal?.FindFirst("sub")?.Value;
                  Console.WriteLine($"Token validated for user: {userId}");
                  return Task.CompletedTask;
              }
          }
      };
  });
  ```
</Accordion>

***

## Additional Resources

<CardGroup>
  <Card title="SDK Documentation" icon="book" href="https://github.com/auth0/aspnetcore-api">
    Complete SDK documentation and API reference
  </Card>

  <Card title="Migration Guide" icon="arrow-right-arrow-left" href="https://github.com/auth0/aspnetcore-api/blob/master/MIGRATION.md">
    Migrate from JWT Bearer authentication
  </Card>

  <Card title="Code Examples" icon="code" href="https://github.com/auth0/aspnetcore-api/blob/master/EXAMPLES.md">
    Comprehensive code examples and patterns
  </Card>

  <Card title="DPoP Documentation" icon="shield" href="https://auth0.com/docs/secure/sender-constraining/demonstrating-proof-of-possession-dpop">
    Learn about proof-of-possession security
  </Card>

  <Card title="Token Best Practices" icon="key" href="https://auth0.com/docs/secure/tokens/token-best-practices">
    Security best practices for tokens
  </Card>

  <Card title="Community Forum" icon="comments" href="https://community.auth0.com/">
    Get help from the Auth0 community
  </Card>
</CardGroup>

***

## Common Issues

<AccordionGroup>
  <Accordion title="401 Unauthorized - Invalid audience">
    **Problem:** Token validation fails with audience mismatch error.

    **Solution:** Ensure the `Audience` in `appsettings.json` exactly matches the Identifier of your Auth0 API. The audience claim in the token must match this value.

    ```json theme={null}
    {
      "Auth0": {
        "Audience": "https://my-api"  // Must match Auth0 API Identifier
      }
    }
    ```
  </Accordion>

  <Accordion title="401 Unauthorized - Invalid issuer">
    **Problem:** Token validation fails with issuer error.

    **Solution:** Verify your Domain is correct and does not include `https://`. The library automatically constructs the authority as `https://{Domain}`.

    ```json theme={null}
    {
      "Auth0": {
        "Domain": "your-tenant.auth0.com"  // No https://
      }
    }
    ```
  </Accordion>

  <Accordion title="Configuration values not found">
    **Problem:** `ArgumentNullException: Value cannot be null. (Parameter 'Domain')` or similar.

    **Solution:** Ensure `appsettings.json` contains the Auth0 section with Domain and Audience values. Check that configuration is being read correctly:

    ```csharp theme={null}
    builder.Services.AddAuth0ApiAuthentication(options =>
    {
        options.Domain = builder.Configuration["Auth0:Domain"]
            ?? throw new InvalidOperationException("Auth0:Domain is required");
        options.JwtBearerOptions = new JwtBearerOptions
        {
            Audience = builder.Configuration["Auth0:Audience"]
                ?? throw new InvalidOperationException("Auth0:Audience is required")
        };
    });
    ```
  </Accordion>

  <Accordion title="HTTPS certificate errors in development">
    **Problem:** SSL/TLS certificate errors when running locally.

    **Solution:** Trust the development certificate:

    ```bash theme={null}
    dotnet dev-certs https --trust
    ```

    Or generate a new certificate:

    ```bash theme={null}
    dotnet dev-certs https --clean
    dotnet dev-certs https --trust
    ```
  </Accordion>

  <Accordion title="Middleware order issues">
    **Problem:** Authentication not working despite correct configuration.

    **Solution:** Ensure middleware is in the correct order. `UseAuthentication()` must come before `UseAuthorization()`:

    ```csharp theme={null}
    app.UseAuthentication();  // Must be before UseAuthorization
    app.UseAuthorization();
    app.MapControllers();
    ```
  </Accordion>

  <Accordion title="Scopes not working in authorization policies">
    **Problem:** Scope-based authorization policies always fail.

    **Solution:** Ensure your access token includes the required scopes. When requesting a token, specify the scopes:

    ```bash theme={null}
    curl --request POST \
      --url https://YOUR_DOMAIN/oauth/token \
      --data '{"client_id":"...","client_secret":"...","audience":"...","grant_type":"client_credentials","scope":"read:messages write:messages"}'
    ```

    Also verify scopes are defined in your Auth0 API settings (Dashboard → APIs → Your API → Permissions).
  </Accordion>
</AccordionGroup>

***

## Sample Application

A complete sample application demonstrating all features is available in the SDK repository.

<Card title="Playground Application" icon="github" href="https://github.com/auth0/aspnetcore-api/tree/master/Auth0.AspNetCore.Authentication.Api.Playground">
  Includes public and protected endpoints, DPoP support, Swagger UI integration, and Postman collection
</Card>

Clone and run:

```bash theme={null}
git clone https://github.com/auth0/aspnetcore-api.git
cd aspnetcore-api/Auth0.AspNetCore.Authentication.Api.Playground
# Update appsettings.json with your Auth0 configuration
dotnet run
```


# Add Authorization to Your Django API Application
Source: https://auth0.com/docs/quickstart/backend/django/interactive

This tutorial demonstrates how to add authorization to a Python API built with Django.

<QuickstartButtons />

<Recipe>
  <Content>
    This guide demonstrates how to integrate Auth0 with any new or existing Python API built with [Django](https://www.djangoproject.com/).

    If you haven't created an API in your Auth0 Dashboard yet, you can use the interactive selector to create a new
    Auth0 API or select an existing API that represents the project you want to integrate with.

    Alternatively, you can read our getting started guide,
    which will help you set up your first API through the Auth0 Dashboard.

    Every API in Auth0 is configured using an API Identifier that your application code will use as the Audience to
    validate the Access Token.

    <Info>
      **New to Auth0?** Learn how Auth0 works and
      read about implementing API authentication and
      authorization using the OAuth 2.0 framework.
    </Info>

    <Section title={sections[0].title}>
      Permissions let you define how resources can be accessed on behalf of the user with a given access token. For
      example, you might choose to grant read access to the `messages` resource if users have the manager
      access level, and grant write access to that resource if they have the administrator access level.

      You can define allowed permissions in the **Permissions** view of the Auth0 Dashboard's [APIs](https://manage.auth0.com/#/apis) section. The following
      example uses the `read:messages` scope.

      <Frame>
        <img />
      </Frame>
    </Section>

    <Section title={sections[1].title}>
      ### Install dependencies

      1. Add the following dependencies to your `requirements.txt`:
      2. Run `pip install -r requirements.txt`

      ### Create a Django application
    </Section>

    <Section title={sections[2].title}>
      You will use a library called [Authlib](https://github.com/lepture/authlib) to create a [ResourceProtector](https://docs.authlib.org/en/latest/flask/1/resource-server.html), which is a type of [Django view decorator](https://docs.djangoproject.com/en/4.0/topics/http/decorators/) that protects your resources (API views) with a given
      validator.

      The validator will verify the Access Token that you pass to the resource by checking that it has a valid
      signature and claims.

      You can use AuthLib's `JWTBearerTokenValidator` validator with a few tweaks to make sure it conforms
      to our requirements for [validating Access Tokens](https://auth0.com/docs/secure/tokens/access-tokens/validate-access-tokens).

      To create your `Auth0JWTBearerTokenValidator`, you need to pass it to your `domain` and
      `audience` (API Identifier). It will then get the public key required to verify the token's signature
      and pass it to the `JWTBearerTokenValidator` class.

      You'll then override the class's `claims_options` to make sure the token's `expiry`,
      `audience`, and `issue` claims are validated according to our requirements.

      Create the file `apiexample/validator.py` using the code from the interactive panel.
    </Section>

    <Section title={sections[3].title}>
      Next, you'll create three API views in `apiexample/views.py`:

      * `/api/public`: A public endpoint that requires no authentication.
      * `/api/private`: A private endpoint that requires a valid Access Token JWT.
      * `/api/private-scoped`: A private endpoint that requires a valid Access Token JWT containing the
        given `scope`.

      The protected routes will have a `require_auth` decorator, which is a `ResourceProtector`
      that uses the `Auth0JWTBearerTokenValidator` you created earlier.

      To create the `Auth0JWTBearerTokenValidator`, you'll pass it to your tenant's domain and the API
      Identifier of the API you created earlier.

      The `require_auth` decorator on the `private_scoped` route accepts an additional argument
      `"read:messages"`, which checks the Access Token for the Permission (Scope) you created earlier.
    </Section>

    <Section title={sections[4].title}>
      In previous steps, you added methods to the `views.py` file. Next, map those methods to URLs using
      Django's [URL dispatcher](https://docs.djangoproject.com/en/4.0/topics/http/urls/), which lets you map URL patterns to views.

      Add the URL patterns to your `apiexample/urls.py` file.

      ### Make a Call to Your API

      To make calls to your API, you will need an access token. You can retrieve an access token for testing purposes
      from the **Test** view in your [API settings](https://manage.auth0.com/#/apis).

      <Frame>
        <img />
      </Frame>

      Provide the access token as an `Authorization` header in your requests.

      <AuthCodeGroup>
        ```bash cURL lines theme={null}
        curl --request get \
        --url 'http:///%7ByourDomain%7D.com/api_path' \
        --header 'authorization: Bearer YOUR_ACCESS_TOKEN_HERE'
        ```

        ```csharp C# lines theme={null}
        var client = new RestClient("http:///%7ByourDomain%7D.com/api_path");
        var request = new RestRequest(Method.GET);
        request.AddHeader("authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
        IRestResponse response = client.Execute(request);
        ```

        ```go Go lines theme={null}
        package main
        import (
        "fmt"
        "net/http"
        "io/ioutil"
        )
        func main() {
        url := "http:///%7ByourDomain%7D.com/api_path"
        req, _ := http.NewRequest("get", url, nil)
        req.Header.Add("authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
        res, _ := http.DefaultClient.Do(req)
        defer res.Body.Close()
        body, _ := ioutil.ReadAll(res.Body)
        fmt.Println(res)
        fmt.Println(string(body))
        }
        ```

        ```java Java lines theme={null}
        HttpResponse<String> response = Unirest.get("http:///%7ByourDomain%7D.com/api_path")
        .header("authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
        .asString();
        ```

        ```javascript Node.JS lines theme={null}
        var axios = require("axios").default;
        var options = {
        method: 'get',
        url: 'http:///%7ByourDomain%7D.com/api_path',
        headers: {authorization: 'Bearer YOUR_ACCESS_TOKEN_HERE'}
        };
        axios.request(options).then(function (response) {
        console.log(response.data);
        }).catch(function (error) {
        console.error(error);
        });
        ```

        ```objc Obj-C lines theme={null}
        #import <Foundation/Foundation.h>
        NSDictionary *headers = @{ @"authorization": @"Bearer YOUR_ACCESS_TOKEN_HERE" };
        NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"http:///%7ByourDomain%7D.com/api_path"]
                                                          cachePolicy:NSURLRequestUseProtocolCachePolicy

                                                      timeoutInterval:10.0];

        [request setHTTPMethod:@"get"];
        [request setAllHTTPHeaderFields:headers];
        NSURLSession *session = [NSURLSession sharedSession];
        NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                                completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {

                                                    if (error) {

                                                        NSLog(@&quot;%@&quot;, error);

                                                    } else {

                                                        NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;

                                                        NSLog(@&quot;%@&quot;, httpResponse);

                                                    }

                                                }];

        [dataTask resume];
        ```

        ```php PHP lines theme={null}
        $curl = curl_init();
        curl_setopt_array($curl, [
        CURLOPT_URL => "http:///%7ByourDomain%7D.com/api_path",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => "",
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => "get",
        CURLOPT_HTTPHEADER => [
        &quot;authorization: Bearer YOUR_ACCESS_TOKEN_HERE&quot;

        ],
        ]);
        $response = curl_exec($curl);
        $err = curl_error($curl);
        curl_close($curl);
        if ($err) {
        echo "cURL Error #:" . $err;
        } else {
        echo $response;
        }
        ```

        ```python Python lines theme={null}
        import http.client
        conn = http.client.HTTPConnection("")
        headers = { 'authorization': "Bearer YOUR_ACCESS_TOKEN_HERE" }
        conn.request("get", "/{yourDomain}.com/api_path", headers=headers)
        res = conn.getresponse()
        data = res.read()
        print(data.decode("utf-8"))
        ```

        ```ruby Ruby lines theme={null}
        require 'uri'
        require 'net/http'
        url = URI("http:///%7ByourDomain%7D.com/api_path")
        http = Net::HTTP.new(url.host, url.port)
        request = Net::HTTP::Get.new(url)
        request["authorization"] = 'Bearer YOUR_ACCESS_TOKEN_HERE'
        response = http.request(request)
        puts response.read_body
        ```

        ```swift Swift lines theme={null}
        import Foundation
        let headers = ["authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"]
        let request = NSMutableURLRequest(url: NSURL(string: "http:///%7ByourDomain%7D.com/api_path")! as URL,
                                            cachePolicy: .useProtocolCachePolicy,

                                        timeoutInterval: 10.0)

        request.httpMethod = "get"
        request.allHTTPHeaderFields = headers
        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()
        ```
      </AuthCodeGroup>
    </Section>

    ## Next Steps

    Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.

    This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:

    * [Auth0 Dashboard](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq) - Learn how to configure and manage your Auth0 tenant and applications
    * [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
  </Content>

  <SideMenu>
    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```py apiexample/views.py lines highlight={} theme={null}
        from authlib.integrations.django_oauth2 import ResourceProtector
        from django.http import JsonResponse
        from . import validator

        require_auth = ResourceProtector()
        validator = validator.Auth0JWTBearerTokenValidator(
            "{yourDomain}",
            "{yourApiIdentifier}"
        )
        require_auth.register_token_validator(validator)

        def public(request):
            """No access token required to access this route
            """
            response = "Hello from a public endpoint! You don't need to be authenticated to see this."
            return JsonResponse(dict(message=response))

        @require_auth(None)
        def private(request):
            """A valid access token is required to access this route
            """
            response = "Hello from a private endpoint! You need to be authenticated to see this."
            return JsonResponse(dict(message=response))

        @require_auth("read:messages")
        def private_scoped(request):
            """A valid access token and an appropriate scope are required to access this route
            """
            response = "Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this."
            return JsonResponse(dict(message=response))
        ```

        ```py apiexample/validator.py lines highlight={} theme={null}
        import json
        from urllib.request import urlopen

        from authlib.oauth2.rfc7523 import JWTBearerTokenValidator
        from authlib.jose.rfc7517.jwk import JsonWebKey

        class Auth0JWTBearerTokenValidator(JWTBearerTokenValidator):
            def __init__(self, domain, audience):
                issuer = f"https://{domain}/"
                jsonurl = urlopen(f"{issuer}.well-known/jwks.json")
                public_key = JsonWebKey.import_key_set(
                    json.loads(jsonurl.read())
                )
                super(Auth0JWTBearerTokenValidator, self).__init__(
                    public_key
                )
                self.claims_options = {
                    "exp": {"essential": True},
                    "aud": {"essential": True, "value": audience},
                    "iss": {"essential": True, "value": issuer},
                }
        ```

        ```py apiexample/urls.py lines highlight={8-10} theme={null}
        from django.contrib import admin
        from django.urls import path
        from . import views

        urlpatterns = [
            path('admin/', admin.site.urls),
            path('api/public', views.public),
            path('api/private', views.private),
            path('api/private-scoped', views.private_scoped)
        ]
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```py apiexample/validator.py lines highlight={} theme={null}
        import json
        from urllib.request import urlopen

        from authlib.oauth2.rfc7523 import JWTBearerTokenValidator
        from authlib.jose.rfc7517.jwk import JsonWebKey

        class Auth0JWTBearerTokenValidator(JWTBearerTokenValidator):
            def __init__(self, domain, audience):
                issuer = f"https://{domain}/"
                jsonurl = urlopen(f"{issuer}.well-known/jwks.json")
                public_key = JsonWebKey.import_key_set(
                    json.loads(jsonurl.read())
                )
                super(Auth0JWTBearerTokenValidator, self).__init__(
                    public_key
                )
                self.claims_options = {
                    "exp": {"essential": True},
                    "aud": {"essential": True, "value": audience},
                    "iss": {"essential": True, "value": issuer},
                }
        ```

        ```py apiexample/views.py lines highlight={} theme={null}
        from authlib.integrations.django_oauth2 import ResourceProtector
        from django.http import JsonResponse
        from . import validator

        require_auth = ResourceProtector()
        validator = validator.Auth0JWTBearerTokenValidator(
            "{yourDomain}",
            "{yourApiIdentifier}"
        )
        require_auth.register_token_validator(validator)

        def public(request):
            """No access token required to access this route
            """
            response = "Hello from a public endpoint! You don't need to be authenticated to see this."
            return JsonResponse(dict(message=response))

        @require_auth(None)
        def private(request):
            """A valid access token is required to access this route
            """
            response = "Hello from a private endpoint! You need to be authenticated to see this."
            return JsonResponse(dict(message=response))

        @require_auth("read:messages")
        def private_scoped(request):
            """A valid access token and an appropriate scope are required to access this route
            """
            response = "Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this."
            return JsonResponse(dict(message=response))
        ```

        ```py apiexample/urls.py lines highlight={8-10} theme={null}
        from django.contrib import admin
        from django.urls import path
        from . import views

        urlpatterns = [
            path('admin/', admin.site.urls),
            path('api/public', views.public),
            path('api/private', views.private),
            path('api/private-scoped', views.private_scoped)
        ]
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```py apiexample/urls.py lines highlight={8-10} theme={null}
        from django.contrib import admin
        from django.urls import path
        from . import views

        urlpatterns = [
            path('admin/', admin.site.urls),
            path('api/public', views.public),
            path('api/private', views.private),
            path('api/private-scoped', views.private_scoped)
        ]
        ```

        ```py apiexample/validator.py lines highlight={} theme={null}
        import json
        from urllib.request import urlopen

        from authlib.oauth2.rfc7523 import JWTBearerTokenValidator
        from authlib.jose.rfc7517.jwk import JsonWebKey

        class Auth0JWTBearerTokenValidator(JWTBearerTokenValidator):
            def __init__(self, domain, audience):
                issuer = f"https://{domain}/"
                jsonurl = urlopen(f"{issuer}.well-known/jwks.json")
                public_key = JsonWebKey.import_key_set(
                    json.loads(jsonurl.read())
                )
                super(Auth0JWTBearerTokenValidator, self).__init__(
                    public_key
                )
                self.claims_options = {
                    "exp": {"essential": True},
                    "aud": {"essential": True, "value": audience},
                    "iss": {"essential": True, "value": issuer},
                }
        ```

        ```py apiexample/views.py lines highlight={} theme={null}
        from authlib.integrations.django_oauth2 import ResourceProtector
        from django.http import JsonResponse
        from . import validator

        require_auth = ResourceProtector()
        validator = validator.Auth0JWTBearerTokenValidator(
            "{yourDomain}",
            "{yourApiIdentifier}"
        )
        require_auth.register_token_validator(validator)

        def public(request):
            """No access token required to access this route
            """
            response = "Hello from a public endpoint! You don't need to be authenticated to see this."
            return JsonResponse(dict(message=response))

        @require_auth(None)
        def private(request):
            """A valid access token is required to access this route
            """
            response = "Hello from a private endpoint! You need to be authenticated to see this."
            return JsonResponse(dict(message=response))

        @require_auth("read:messages")
        def private_scoped(request):
            """A valid access token and an appropriate scope are required to access this route
            """
            response = "Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this."
            return JsonResponse(dict(message=response))
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>
  </SideMenu>
</Recipe>


# FastAPI API
Source: https://auth0.com/docs/quickstart/backend/fastapi/index

Add Auth0 JWT authentication to an FastAPI with protected endpoints

<Accordion title="AI Prompt" icon="microchip-ai">
  **Using AI to integrate Auth0?** Add this prompt to Cursor, Windsurf, Copilot, Claude Code or your favourite AI-powered IDE to speed up development.

  ```markdown expandable theme={null}
  Integrate the Auth0 FastAPI SDK into a Python API

  AI PERSONA & PRIMARY OBJECTIVE
  You are a helpful Auth0 SDK Integration Assistant for FastAPI APIs. Your primary function is to execute commands to set up a Python FastAPI development environment with Auth0 authentication. Your secondary function is to modify the files created during setup.

  CRITICAL BEHAVIORAL INSTRUCTIONS
  1. CHECK EXISTING PROJECT FIRST: Before creating a new project, check if the current directory already contains a Python project (requirements.txt, pyproject.toml, or .py files). If it does, skip project creation and work with the existing project.
  2. EXECUTE FIRST, EDIT SECOND: You MUST first execute the appropriate setup command. Do not show, suggest, or create any files until the setup is complete.
  3. NO PLANNING: DO NOT propose a directory structure. DO NOT show a file tree. Your first action must be to run the appropriate command.
  4. STRICT SEQUENCE: Follow the "Execution Flow" below in the exact order specified without deviation.
  5. SECURITY FIRST: NEVER hardcode Auth0 Domain or Audience values. ALWAYS use environment variables via python-dotenv.
  6. 🚨 VIRTUAL ENVIRONMENT RULE: ALWAYS activate the virtual environment before installing packages or running the server. Never skip venv activation.

  EXECUTION FLOW

  ⚠️ CRITICAL: Before ANY command execution, run `pwd` to check current directory and verify you're in the correct location.

  Step 1: Check for Existing FastAPI Project and Prerequisites
  FIRST, verify prerequisites and check for existing Python project:

    # Check if Python 3.9+ and pip are available
    python3 --version && pip --version

  Then examine the current directory:

    # Check for existing Python project
    if [ -f "requirements.txt" ] || [ -f "pyproject.toml" ] || [ -f "app.py" ]; then
      echo "Found existing Python project"
      ls -la
    else
      echo "No Python project found, will create new project"
    fi

  Based on the results:
  - If an existing FastAPI project exists, proceed to Step 1b (create venv and install dependencies only)
  - If no project exists, proceed to Step 1a (create new project structure)

  Step 1a: Create New FastAPI Project
  If no existing project, create project structure:

    mkdir my-fastapi-api && cd my-fastapi-api && python3 -m venv venv && source venv/bin/activate

  ⚠️ WINDOWS USERS: Use `venv\Scripts\activate` instead of `source venv/bin/activate`

  Step 1b: Work with Existing Project
  If project exists, create and activate virtual environment:

    python3 -m venv venv && source venv/bin/activate

  Step 2: Install Dependencies
  Create requirements.txt with the following content:

    cat > requirements.txt << 'EOF'
    fastapi>=0.115.0
    uvicorn[standard]>=0.34.0
    auth0-fastapi-api>=1.0.0b5
    python-dotenv>=1.0.0
    EOF

  Then install dependencies (MUST be in activated venv):

    pip install -r requirements.txt

  Step 3: Setup Auth0 API

  ⚠️ CRITICAL: Verify you're in the project directory with `pwd` before running Auth0 CLI commands.

  Step 3a: Execute Auth0 CLI Setup

  If MacOS, execute:

    AUTH0_API_NAME="My FastAPI API" && AUTH0_API_IDENTIFIER="https://my-fastapi-api" && brew tap auth0/auth0-cli && brew install auth0 && auth0 login --no-input && auth0 apis create --name "${AUTH0_API_NAME}" --identifier "${AUTH0_API_IDENTIFIER}" --signing-alg RS256 --no-input && echo "AUTH0_DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name')\nAUTH0_AUDIENCE=${AUTH0_API_IDENTIFIER}" > .env

  If Windows, execute:

    $ApiName = "My FastAPI API"; $ApiIdentifier = "https://my-fastapi-api"; auth0 login --no-input; auth0 apis create -n $ApiName -i $ApiIdentifier --signing-alg RS256 --no-input; $ActiveTenant = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name; "AUTH0_DOMAIN=$ActiveTenant`nAUTH0_AUDIENCE=$ApiIdentifier" | Out-File -FilePath .env -Encoding utf8

  Step 3b: Verify .env file was created correctly

    cat .env

  Expected output:
    AUTH0_DOMAIN=your-domain.auth0.com
    AUTH0_AUDIENCE=https://my-fastapi-api

  ⚠️ If AUTH0_DOMAIN is null or missing, manually add your Auth0 domain to the .env file.

  Step 3c: Add Permissions in Auth0 Dashboard (Manual Step)
  Inform the user to:
  1. Navigate to Applications > APIs in Auth0 Dashboard
  2. Select "My FastAPI API"
  3. Go to Permissions tab
  4. Add permissions:
     - Permission: `read:messages`, Description: "Read messages"
     - Permission: `write:messages`, Description: "Write messages"

  Step 4: Create FastAPI Application with Auth0
  Create app.py with the following content:

    cat > app.py << 'EOF'
    from fastapi import FastAPI, Depends
    from fastapi_plugin.fast_api_client import Auth0FastAPI
    import os
    from dotenv import load_dotenv

    # Load environment variables
    load_dotenv()

    app = FastAPI()

    # Initialize Auth0
    auth0 = Auth0FastAPI(
        domain=os.environ.get("AUTH0_DOMAIN"),
        audience=os.environ.get("AUTH0_AUDIENCE")
    )

    # Public route - no authentication required
    @app.get("/api/public")
    async def public():
        return {
            "message": "Hello from a public endpoint! You don't need to be authenticated to see this."
        }

    # Protected route - requires authentication
    @app.get("/api/private")
    async def private(claims: dict = Depends(auth0.require_auth())):
        return {
            "message": "Hello from a private endpoint! You need to be authenticated to see this.",
            "user_id": claims.get("sub")
        }

    # Scoped route - requires specific permission
    @app.get("/api/private-scoped")
    async def private_scoped(claims: dict = Depends(auth0.require_auth(scopes="read:messages"))):
        return {
            "message": "Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this.",
            "user_id": claims.get("sub")
        }
    EOF

  Step 5: Run the FastAPI Application

  ⚠️ CRITICAL: Verify virtual environment is activated before running uvicorn.

    # Verify venv is activated (you should see (venv) in your prompt)
    which python

    # Start the server
    uvicorn app:app --reload

  Expected output: Server starts on http://127.0.0.1:8000

  Step 6: Test the API

  6a: Test public endpoint (no authentication required):

    curl http://localhost:8000/api/public

  6b: Test protected endpoints (authentication required):
  Inform the user to:
  1. Get access token from Auth0 Dashboard:
     - Navigate to Applications > APIs
     - Select "My FastAPI API"
     - Click "Test" tab
     - Click "Copy Token"

  2. Test private endpoint:

    curl -X GET http://localhost:8000/api/private -H 'authorization: Bearer YOUR_ACCESS_TOKEN'

  3. Test scoped endpoint:

    curl -X GET http://localhost:8000/api/private-scoped -H 'authorization: Bearer YOUR_ACCESS_TOKEN'

  ANTI-PATTERNS - NEVER DO THESE

  1. ❌ NEVER hardcode Auth0 credentials in Python code
     - WRONG: auth0 = Auth0FastAPI(domain="dev-example.us.auth0.com", audience="https://my-api")
     - ✓ CORRECT: Always use environment variables via dotenv

  2. ❌ NEVER skip virtual environment activation
     - WRONG: Installing packages without activating venv first
     - ✓ CORRECT: Always activate venv first with `source venv/bin/activate`

  3. ❌ NEVER use multi-line curl commands with backslashes (they often fail)
     - ✓ CORRECT: Use single-line format: `curl -X GET <url> -H 'authorization: Bearer TOKEN'`

  4. ❌ NEVER proceed if .env file has null values
     - WRONG: AUTH0_DOMAIN=null in .env file
     - ✓ CORRECT: Verify .env contains valid Auth0 domain before proceeding

  ABSOLUTE REQUIREMENTS

  1. ✓ Virtual environment MUST be activated before pip install
  2. ✓ .env file MUST contain valid AUTH0_DOMAIN (not null)
  3. ✓ .env file MUST be added to .gitignore to prevent credential exposure
  4. ✓ Auth0FastAPI MUST use os.environ.get() for credentials
  5. ✓ All endpoints requiring authentication MUST use Depends(auth0.require_auth())

  COMMON ISSUES & SOLUTIONS

  1. **ModuleNotFoundError: No module named 'fastapi_plugin'**
     - Cause: Wrong virtual environment activated or venv not activated
     - Solution: Deactivate all venvs, then activate the correct one in project directory

  2. **AUTH0_DOMAIN is null in .env**
     - Cause: Auth0 CLI command doesn't extract domain correctly
     - Solution: Manually add domain to .env file from Auth0 Dashboard

  3. **401 Unauthorized - Invalid issuer**
     - Cause: AUTH0_DOMAIN includes https:// protocol
     - Solution: Domain should be just `dev-example.us.auth0.com` without protocol

  4. **401 Unauthorized - Invalid audience**
     - Cause: AUTH0_AUDIENCE doesn't match API identifier
     - Solution: Verify AUTH0_AUDIENCE exactly matches identifier in Auth0 Dashboard

  5. **403 Forbidden - Insufficient scope**
     - Cause: Access token doesn't include required scope
     - Solution: Verify permissions exist in Auth0 Dashboard and token includes them

  VALIDATION CHECKLIST

  Before considering the integration complete, verify:
  - [ ] Virtual environment is activated (check with `which python`)
  - [ ] .env file exists and contains valid AUTH0_DOMAIN (not null)
  - [ ] .env is added to .gitignore
  - [ ] app.py imports and initializes Auth0FastAPI correctly
  - [ ] Public endpoint returns 200 OK without authentication
  - [ ] Private endpoint returns 401 without token
  - [ ] Private endpoint returns 200 with valid token
  - [ ] Scoped endpoint returns 403 without required scope
  - [ ] Scoped endpoint returns 200 with token containing read:messages scope
  ```
</Accordion>

<Note>
  This quickstart requires:

  * **Python 3.9** or higher
  * **pip** package manager
  * **jq** - Required for Auth0 CLI setup
  * Familiarity with FastAPI

  If you haven't already, [sign up for a free Auth0 account](https://auth0.com/signup) to follow along.
</Note>

This guide demonstrates how to integrate Auth0 with a FastAPI API to add authentication and protect your endpoints.

<Steps>
  <Step title="Create a new FastAPI project">
    Create a new directory for your FastAPI project and set up a virtual environment.

    ```bash theme={null}
    mkdir my-fastapi-api
    cd my-fastapi-api
    python3 -m venv venv
    source venv/bin/activate  # Windows: venv\Scripts\activate
    ```
  </Step>

  <Step title="Install dependencies">
    Create a `requirements.txt` file with the following dependencies:

    ```txt requirements.txt theme={null}
    fastapi>=0.115.0
    uvicorn[standard]>=0.34.0
    auth0-fastapi-api>=1.0.0b5
    python-dotenv>=1.0.0
    ```

    Install the dependencies:

    ```bash theme={null}
    pip install -r requirements.txt
    ```
  </Step>

  <Step title="Setup your Auth0 API">
    You'll need to create an Auth0 API to represent your FastAPI application.

    <Tabs>
      <Tab title="Dashboard">
        1. Navigate to [Applications > APIs](https://manage.auth0.com/#/apis) in the Auth0 Dashboard
        2. Click **Create API**
        3. Provide a **Name** for your API (e.g., "My FastAPI API")
        4. Set the **Identifier** to your API identifier (e.g., `https://my-fastapi-api`)
        5. Leave the **Signing Algorithm** as RS256
        6. Click **Create**
      </Tab>

      <Tab title="CLI">
        If you have the [Auth0 CLI](https://github.com/auth0/auth0-cli) installed, you can create an API and configure your environment from your terminal:

        <CodeGroup>
          ```shellscript Mac theme={null}
          AUTH0_API_NAME="My FastAPI API" && AUTH0_API_IDENTIFIER="https://my-fastapi-api" && brew tap auth0/auth0-cli && brew install auth0 && auth0 login --no-input && auth0 apis create --name "${AUTH0_API_NAME}" --identifier "${AUTH0_API_IDENTIFIER}" --signing-alg RS256 --no-input && echo "AUTH0_DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name')\nAUTH0_AUDIENCE=${AUTH0_API_IDENTIFIER}" > .env
          ```

          ```powershell Windows theme={null}
          $ApiName = "My FastAPI API"; $ApiIdentifier = "https://my-fastapi-api"; auth0 login --no-input; auth0 apis create -n $ApiName -i $ApiIdentifier --signing-alg RS256 --no-input; $ActiveTenant = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name; "AUTH0_DOMAIN=$ActiveTenant`nAUTH0_AUDIENCE=$ApiIdentifier" | Out-File -FilePath .env -Encoding utf8
          ```
        </CodeGroup>

        This will create your API and automatically generate a `.env` file with your Auth0 configuration.
      </Tab>
    </Tabs>

    <Info>
      The **Identifier** is a unique identifier for your API. It's recommended to use a URL, but it doesn't have to be a publicly accessible URL—Auth0 won't call it. This value cannot be modified afterwards.
    </Info>

    Make note of the **Domain** and **Identifier** (Audience) values. You'll need these in the next step.
  </Step>

  <Step title="Define API permissions">
    Permissions (also known as scopes) allow you to define how your API can be accessed. You can create permissions for your API in the Auth0 Dashboard.

    1. In the Auth0 Dashboard, navigate to your API's **Permissions** tab
    2. Add the following permissions:
       * `read:messages` with description "Read messages"
       * `write:messages` with description "Write messages"

    These permissions will be used to control access to specific endpoints in your API.
  </Step>

  <Step title="Configure the Auth0 client">
    Create a `.env` file in your project root to store your Auth0 configuration:

    ```txt .env theme={null}
    AUTH0_DOMAIN=YOUR_AUTH0_DOMAIN
    AUTH0_AUDIENCE=YOUR_API_IDENTIFIER
    ```

    Replace `YOUR_AUTH0_DOMAIN` with your Auth0 domain (e.g., `dev-abc123.us.auth0.com`) and `YOUR_API_IDENTIFIER` with the identifier you set when creating your API.

    <Warning>
      Never commit your `.env` file to version control. Add it to your `.gitignore` file to keep your credentials secure.
    </Warning>

    Now create an `app.py` file and initialize your FastAPI application with Auth0:

    ```python app.py theme={null}
    from fastapi import FastAPI, Depends
    from fastapi_plugin.fast_api_client import Auth0FastAPI
    import os
    from dotenv import load_dotenv

    # Load environment variables
    load_dotenv()

    app = FastAPI()

    # Initialize Auth0
    auth0 = Auth0FastAPI(
        domain=os.environ.get("AUTH0_DOMAIN"),
        audience=os.environ.get("AUTH0_AUDIENCE")
    )
    ```
  </Step>

  <Step title="Create protected routes">
    Add the following routes to your `app.py` file. These routes demonstrate different levels of access control:

    ```python app.py theme={null}
    from fastapi import FastAPI, Depends
    from fastapi_plugin.fast_api_client import Auth0FastAPI
    import os
    from dotenv import load_dotenv

    load_dotenv()

    app = FastAPI()

    auth0 = Auth0FastAPI(
        domain=os.environ.get("AUTH0_DOMAIN"),
        audience=os.environ.get("AUTH0_AUDIENCE")
    )

    # Public route - no authentication required
    @app.get("/api/public")
    async def public():
        return {
            "message": "Hello from a public endpoint! You don't need to be authenticated to see this."
        }

    # Protected route - requires authentication
    @app.get("/api/private")
    async def private(claims: dict = Depends(auth0.require_auth())):
        return {
            "message": "Hello from a private endpoint! You need to be authenticated to see this.",
            "user_id": claims.get("sub")
        }

    # Scoped route - requires specific permission
    @app.get("/api/private-scoped")
    async def private_scoped(claims: dict = Depends(auth0.require_auth(scopes="read:messages"))):
        return {
            "message": "Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this.",
            "user_id": claims.get("sub")
        }
    ```

    The `require_auth()` method validates the access token sent in the Authorization header. When called with a `scopes` parameter, it also verifies that the token contains the specified permission.
  </Step>

  <Step title="Run your API">
    Start your FastAPI application:

    ```bash theme={null}
    uvicorn app:app --reload
    ```

    Your API is now running on `http://localhost:8000`.

    <Check>
      Visit `http://localhost:8000/api/public` in your browser. You should see the public message without needing authentication.
    </Check>
  </Step>
</Steps>

***

## Test your API

To test the protected endpoints, you'll need to obtain an access token from Auth0.

### Get an access token

The easiest way to get an access token for testing is through the Auth0 Dashboard:

1. Navigate to [Applications > APIs](https://manage.auth0.com/#/apis) in the Auth0 Dashboard
2. Select your API
3. Click the **Test** tab
4. Click **Copy Token** in the **Asking Auth0 for tokens from my application** section

### Call your API

Use the access token to call your protected endpoint:

```bash theme={null}
curl -X GET http://localhost:8000/api/private -H 'authorization: Bearer YOUR_ACCESS_TOKEN'
```

You should receive a response with the private message and your user ID.

To test the scoped endpoint, make sure your token includes the `read:messages` scope:

```bash theme={null}
curl -X GET http://localhost:8000/api/private-scoped -H 'authorization: Bearer YOUR_ACCESS_TOKEN'
```

If your token doesn't have the required scope, you'll receive a 403 Forbidden response.

***

## Advanced Usage

<Accordion title="Validate custom claims">
  You can access custom claims that have been added to the access token through [Auth0 Actions](https://auth0.com/docs/customize/actions).

  Access custom claims in your route handler:

  ```python theme={null}
  @app.get("/api/profile")
  async def profile(claims: dict = Depends(auth0.require_auth())):
      return {
          "user_id": claims.get("sub"),
          "email": claims.get("email"),
          "permissions": claims.get("permissions", []),
          "custom_claim": claims.get("https://myapp.example.com/custom_claim")
      }
  ```

  To add custom claims to your access tokens, create an Auth0 Action:

  1. Navigate to **Actions > Library** in the Auth0 Dashboard
  2. Click **Create Action**
  3. Select **Build from scratch**
  4. Name your action and select the **Login / Post Login** trigger
  5. Add your custom claims:

  ```javascript theme={null}
  exports.onExecutePostLogin = async (event, api) => {
    const namespace = 'https://myapp.example.com';

    if (event.authorization) {
      // Add custom claim to access token
      api.accessToken.setCustomClaim(`${namespace}/roles`, event.user.app_metadata.roles || []);
    }
  };
  ```

  6. Click **Deploy** and add the action to your Login flow

  <Info>
    Custom claims must use a namespaced format (e.g., `https://myapp.example.com/claim_name`) to avoid conflicts with standard claims.
  </Info>
</Accordion>

<Accordion title="Protect endpoints without using claims">
  If you need to protect an endpoint but don't need to access the claims, you can use the `dependencies` parameter:

  ```python theme={null}
  @app.get("/api/protected", dependencies=[Depends(auth0.require_auth())])
  async def protected():
      return {"message": "This endpoint is protected"}
  ```

  This validates the access token but doesn't inject the claims into your function.
</Accordion>

<Accordion title="DPoP support">
  <Info>
    DPoP (Demonstrating Proof-of-Possession) is currently in [Early Access](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages). Contact [Auth0 support](https://support.auth0.com/) to enable it for your tenant.
  </Info>

  DPoP provides enhanced security by cryptographically binding access tokens to the client that requested them. This prevents token theft and replay attacks.

  The SDK enables DPoP support by default. You can configure DPoP behavior:

  ```python theme={null}
  auth0 = Auth0FastAPI(
      domain=os.environ.get("AUTH0_DOMAIN"),
      audience=os.environ.get("AUTH0_AUDIENCE"),
      dpop_enabled=True,      # Enable DPoP (default: True)
      dpop_required=False     # Require DPoP (default: False)
  )
  ```

  **Mixed mode** (default) accepts both Bearer and DPoP tokens:

  ```python theme={null}
  auth0 = Auth0FastAPI(
      domain=os.environ.get("AUTH0_DOMAIN"),
      audience=os.environ.get("AUTH0_AUDIENCE"),
      dpop_enabled=True,
      dpop_required=False
  )
  ```

  **DPoP-only mode** rejects Bearer tokens:

  ```python theme={null}
  auth0 = Auth0FastAPI(
      domain=os.environ.get("AUTH0_DOMAIN"),
      audience=os.environ.get("AUTH0_AUDIENCE"),
      dpop_required=True
  )
  ```

  When using DPoP, clients must include both the `Authorization: DPoP <token>` and `DPoP: <proof>` headers. The SDK automatically validates the DPoP proof and binds it to the access token.
</Accordion>

<Accordion title="Configure for reverse proxy">
  <Warning>
    Only enable `trust_proxy` when your application is behind a trusted reverse proxy. Never enable this for applications directly exposed to the internet.
  </Warning>

  If your application runs behind a reverse proxy (nginx, AWS ALB, etc.), you need to enable proxy trust for DPoP validation to work correctly:

  ```python theme={null}
  from fastapi import FastAPI

  app = FastAPI()

  # Enable proxy trust
  app.state.trust_proxy = True

  auth0 = Auth0FastAPI(
      domain=os.environ.get("AUTH0_DOMAIN"),
      audience=os.environ.get("AUTH0_AUDIENCE")
  )
  ```

  Configure your reverse proxy to forward the necessary headers:

  ```nginx theme={null}
  location /api {
      proxy_pass http://localhost:8000;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_set_header X-Forwarded-Host $host;
      proxy_set_header X-Forwarded-Prefix /api;
  }
  ```

  This is essential for DPoP validation because the SDK needs to match the exact URL the client used. Without proxy trust, your application sees internal URLs while DPoP proofs reference external URLs, causing validation failures.
</Accordion>

<Accordion title="Error handling">
  The SDK raises `HTTPException` for authentication errors. FastAPI handles these automatically, returning appropriate HTTP responses to the client.

  You can implement custom error handling if needed:

  ```python theme={null}
  from fastapi import Request
  from fastapi.responses import JSONResponse
  from fastapi.exceptions import HTTPException

  @app.exception_handler(HTTPException)
  async def custom_http_exception_handler(request: Request, exc: HTTPException):
      if exc.status_code in [401, 403]:
          return JSONResponse(
              status_code=exc.status_code,
              content={
                  "error": "authentication_failed",
                  "message": "You must be authenticated to access this resource",
                  "details": exc.detail
              }
          )
      return JSONResponse(
          status_code=exc.status_code,
          content={"detail": exc.detail}
      )
  ```

  Authentication errors include:

  * **401 Unauthorized**: Missing, invalid, or expired access token
  * **403 Forbidden**: Valid token but insufficient permissions (scopes)
</Accordion>

***

## Common Issues

<AccordionGroup>
  <Accordion title="401 Unauthorized - Invalid audience">
    **Problem**: Token validation fails with "Invalid audience" error.

    **Solution**: Verify that the `AUTH0_AUDIENCE` in your `.env` file exactly matches the **Identifier** you configured for your API in the Auth0 Dashboard.

    1. Open the Auth0 Dashboard and navigate to **Applications > APIs**
    2. Select your API
    3. Check the **Identifier** value in the Settings tab
    4. Update your `.env` file:
       ```txt theme={null}
       AUTH0_AUDIENCE=https://your-exact-api-identifier
       ```
    5. Restart your application
  </Accordion>

  <Accordion title="401 Unauthorized - Invalid issuer">
    **Problem**: Token validation fails with "Invalid issuer" error.

    **Solution**: Verify that your `AUTH0_DOMAIN` is correct and does not include the `https://` protocol.

    Your domain should look like `dev-abc123.us.auth0.com`, not `https://dev-abc123.us.auth0.com`.

    Update your `.env` file:

    ```txt theme={null}
    AUTH0_DOMAIN=dev-abc123.us.auth0.com
    ```
  </Accordion>

  <Accordion title="403 Forbidden - Insufficient scope">
    **Problem**: Protected endpoint returns 403 even with a valid access token.

    **Solution**: The access token doesn't include the required scope.

    1. Check what scopes your endpoint requires
    2. When requesting a token, ensure you include the required scopes
    3. Verify the scope exists in your API's Permissions tab in the Auth0 Dashboard
    4. Decode your token at [jwt.io](https://jwt.io) to verify it contains the `scope` claim with the required values
  </Accordion>

  <Accordion title="ModuleNotFoundError: No module named 'fastapi_plugin'">
    **Problem**: Python cannot find the Auth0 FastAPI SDK.

    **Solution**: Ensure the SDK is installed in your active virtual environment.

    ```bash theme={null}
    # Activate your virtual environment
    source venv/bin/activate  # Windows: venv\Scripts\activate

    # Install the SDK
    pip install auth0-fastapi-api

    # Verify installation
    pip show auth0-fastapi-api
    ```
  </Accordion>

  <Accordion title="Cannot connect to Auth0 (JWKS fetch failed)">
    **Problem**: Application cannot fetch signing keys from Auth0.

    **Solution**: Check your network connectivity and domain configuration.

    1. Verify your domain is accessible:
       ```bash theme={null}
       curl https://YOUR_DOMAIN/.well-known/openid-configuration
       ```

    2. Check that your firewall allows outbound HTTPS (port 443) connections to `*.auth0.com`

    3. If behind a corporate proxy, configure the `HTTP_PROXY` and `HTTPS_PROXY` environment variables
  </Accordion>

  <Accordion title="DPoP validation fails">
    **Problem**: DPoP authentication returns errors about URL or proof validation.

    **Solution**:

    1. If behind a reverse proxy, enable proxy trust:
       ```python theme={null}
       app.state.trust_proxy = True
       ```

    2. Verify your proxy forwards these headers:
       * `X-Forwarded-Proto`
       * `X-Forwarded-Host`
       * `X-Forwarded-Prefix`

    3. Ensure DPoP is enabled for your tenant (contact Auth0 support)

    4. Verify the DPoP proof `htu` claim matches your request URL exactly
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup>
  <Card title="SDK Documentation" icon="github" href="https://github.com/auth0/auth0-fastapi-api">
    Explore the Auth0 FastAPI SDK on GitHub for advanced configuration and examples
  </Card>

  <Card title="Scopes and Permissions" icon="lock" href="https://auth0.com/docs/get-started/apis/scopes">
    Learn how to define and use scopes for fine-grained access control
  </Card>

  <Card title="Auth0 Actions" icon="bolt" href="https://auth0.com/docs/customize/actions">
    Customize your authentication flow and add custom claims to tokens
  </Card>

  <Card title="FastAPI Documentation" icon="book" href="https://fastapi.tiangolo.com/">
    Learn more about FastAPI features, async patterns, and best practices
  </Card>

  <Card title="API Authorization" icon="shield-check" href="https://auth0.com/docs/authorization">
    Implement role-based access control (RBAC) for your API
  </Card>

  <Card title="Deploy to Production" icon="server" href="https://auth0.com/docs/deploy">
    Best practices for deploying FastAPI applications with Auth0
  </Card>
</CardGroup>


# Protect Your Fastify API
Source: https://auth0.com/docs/quickstart/backend/fastify/index

This guide demonstrates how to protect Fastify API endpoints using JWT access tokens with the Auth0 Fastify API SDK.

<Accordion title="Use AI to integrate Auth0" icon="microchip-ai">
  If you use an AI coding assistant like Claude Code, Cursor, or GitHub Copilot, you can add Auth0 API authentication automatically in minutes using [agent skills](https://agentskills.io/home).

  **Install:**

  ```bash theme={null}
  npx skills add auth0/agent-skills --skill auth0-quickstart --skill auth0-fastify-api
  ```

  **Then ask your AI assistant:**

  ```text theme={null}
  Add Auth0 JWT authentication to my Fastify API
  ```

  Your AI assistant will automatically create your Auth0 API, fetch credentials, install `@auth0/auth0-fastify-api`, configure the plugin, and protect your API endpoints with JWT validation. [Full agent skills documentation →](/quickstart/agent-skills)
</Accordion>

<Note>
  **Prerequisites:** Before you begin, ensure you have the following installed:

  * **[Node.js](https://nodejs.org/en/download)** 20 LTS or newer
  * **[npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)** 10+ or **[yarn](https://classic.yarnpkg.com/lang/en/docs/install/)** 1.22+ or **[pnpm](https://pnpm.io/installation)** 8+

  Verify installation: `node --version && npm --version`

  **Fastify Version Compatibility:** This quickstart works with **Fastify 5.x** and newer.
</Note>

## Get Started

This quickstart demonstrates how to protect Fastify API endpoints using JWT access tokens. You'll build a secure API that validates Auth0 access tokens and grants access to protected resources.

<Steps>
  <Step title="Create a new project">
    Create a new directory for your Fastify API and initialize a Node.js project.

    ```shellscript theme={null}
    mkdir auth0-fastify-api && cd auth0-fastify-api
    ```

    Initialize the project

    ```shellscript theme={null}
    npm init -y
    ```

    Create the project structure

    ```shellscript theme={null}
    touch server.js .env
    ```
  </Step>

  <Step title="Install the Auth0 Fastify API SDK">
    Install the required dependencies

    ```shellscript theme={null}
    npm install @auth0/auth0-fastify-api fastify dotenv
    ```

    Update your `package.json` to add start scripts:

    ```json package.json theme={null}
    {
      "name": "auth0-fastify-api",
      "version": "1.0.0",
      "type": "module",
      "main": "server.js",
      "scripts": {
        "start": "node server.js",
        "dev": "node --watch server.js"
      },
      "dependencies": {
        "@auth0/auth0-fastify-api": "^1.2.0",
        "dotenv": "^16.3.1",
        "fastify": "^5.0.0"
      }
    }
    ```
  </Step>

  <Step title="Setup your Auth0 API">
    Next, you need to create a new API on your Auth0 tenant and add the environment variables to your project.

    You have two options to set up your Auth0 API: use a CLI command or configure manually via the Dashboard:

    <Tabs>
      <Tab title="CLI">
        Run the following command in your project's root directory to create an Auth0 API:

        <CodeGroup>
          ```shellscript Mac theme={null}
          # Install Auth0 CLI (if not already installed)
          brew tap auth0/auth0-cli && brew install auth0

          # Create Auth0 API
          auth0 apis create \
            --name "My Fastify API" \
            --identifier https://my-fastify-api.example.com
          ```

          ```powershell Windows theme={null}
          # Install Auth0 CLI (if not already installed)
          scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git
          scoop install auth0

          # Create Auth0 API
          auth0 apis create `
            --name "My Fastify API" `
            --identifier https://my-fastify-api.example.com
          ```
        </CodeGroup>

        After creation, copy the **Identifier** and your **Domain** values, then create your `.env` file:

        ```bash .env theme={null}
        AUTH0_DOMAIN=YOUR_AUTH0_DOMAIN
        AUTH0_AUDIENCE=YOUR_API_IDENTIFIER
        ```

        <Note>
          This command will:

          1. Check if you're authenticated (and prompt for login if needed)
          2. Create an Auth0 API with the specified identifier
          3. Display the API details including the domain and identifier
        </Note>
      </Tab>

      <Tab title="Dashboard">
        1. Go to the [Auth0 Dashboard](https://manage.auth0.com/dashboard/)
        2. Navigate to **Applications** → **APIs** → **Create API**
        3. Enter a name for your API (e.g., "My Fastify API")
        4. Set the **Identifier** (e.g., `https://my-fastify-api.example.com`)
           * This is your API audience and must be a valid URL format
           * It doesn't need to be a real URL - it's just an identifier
        5. Keep **Signing Algorithm** as **RS256**
        6. Click **Create**
        7. Copy the **Identifier** value from the **Settings** tab

        Create your `.env` file with the following values:

        ```bash .env theme={null}
        AUTH0_DOMAIN=YOUR_AUTH0_DOMAIN
        AUTH0_AUDIENCE=YOUR_API_IDENTIFIER
        ```

        <Warning>
          Replace `YOUR_AUTH0_DOMAIN` with your Auth0 tenant domain (e.g., `dev-abc123.us.auth0.com`) and `YOUR_API_IDENTIFIER` with your API identifier from the dashboard (e.g., `https://my-fastify-api.example.com`).
        </Warning>
      </Tab>
    </Tabs>

    <Tip>
      Verify your `.env` file exists: `cat .env` (Mac/Linux) or `type .env` (Windows)
    </Tip>
  </Step>

  <Step title="Configure the Auth0 API plugin">
    Create your Fastify server and register the Auth0 API plugin:

    ```javascript server.js {1-3,6-7,10-13,16-17} lines theme={null}
    import 'dotenv/config';
    import Fastify from 'fastify';
    import fastifyAuth0Api from '@auth0/auth0-fastify-api';

    const fastify = Fastify({ logger: true });
    const port = process.env.PORT || 3001;

    // Register Auth0 API plugin
    await fastify.register(fastifyAuth0Api, {
      domain: process.env.AUTH0_DOMAIN,
      audience: process.env.AUTH0_AUDIENCE,
    });

    // Start server
    fastify.listen({ port }, (err) => {
      if (err) {
        fastify.log.error(err);
        process.exit(1);
      }
      fastify.log.info(`API server running at http://localhost:${port}`);
    });
    ```

    **What this does:**

    * Registers the Auth0 API plugin with your Auth0 domain and API audience
    * Configures JWT validation for incoming requests
    * Makes the `requireAuth()` preHandler available for protecting routes
  </Step>

  <Step title="Create API routes">
    Add public and protected routes to your `server.js`:

    ```javascript server.js expandable lines theme={null}
    import 'dotenv/config';
    import Fastify from 'fastify';
    import fastifyAuth0Api from '@auth0/auth0-fastify-api';

    const fastify = Fastify({ logger: true });
    const port = process.env.PORT || 3001;

    // Register Auth0 API plugin
    await fastify.register(fastifyAuth0Api, {
      domain: process.env.AUTH0_DOMAIN,
      audience: process.env.AUTH0_AUDIENCE,
    });

    // Public route - no authentication required
    fastify.get('/api/public', async (request, reply) => {
      return {
        message: 'Hello from a public endpoint! You don\'t need to be authenticated to see this.',
        timestamp: new Date().toISOString(),
      };
    });

    // Protected route - requires valid access token
    fastify.get('/api/private', {
      preHandler: fastify.requireAuth()
    }, async (request, reply) => {
      return {
        message: 'Hello from a protected endpoint! You successfully authenticated.',
        user: request.user.sub,
        timestamp: new Date().toISOString(),
      };
    });

    // Protected route - returns user information from token
    fastify.get('/api/profile', {
      preHandler: fastify.requireAuth()
    }, async (request, reply) => {
      return {
        message: 'Your user profile from the access token',
        profile: request.user,
      };
    });

    // Start server
    fastify.listen({ port }, (err) => {
      if (err) {
        fastify.log.error(err);
        process.exit(1);
      }
      fastify.log.info(`API server running at http://localhost:${port}`);
    });
    ```

    **Key points:**

    * Public routes don't require authentication
    * Protected routes use `preHandler: fastify.requireAuth()` to require a valid JWT
    * `request.user` contains the decoded JWT claims for authenticated requests
    * The `sub` claim contains the user's unique identifier
  </Step>

  <Step title="Run your API">
    Start the development server:

    ```shellscript theme={null}
    npm run dev
    ```

    Your API is now running at [http://localhost:3001](http://localhost:3001).

    <Info>
      The `--watch` flag in Node.js 20+ automatically restarts the server when files change.
    </Info>
  </Step>

  <Step title="Test your API">
    Test the public endpoint (no authentication required):

    ```bash theme={null}
    curl http://localhost:3001/api/public
    ```

    You should see:

    ```json theme={null}
    {
      "message": "Hello from a public endpoint! You don't need to be authenticated to see this.",
      "timestamp": "2024-01-15T10:30:00.000Z"
    }
    ```

    Test the protected endpoint without a token (should fail):

    ```bash theme={null}
    curl http://localhost:3001/api/private
    ```

    You should see a 401 Unauthorized error:

    ```json theme={null}
    {
      "error": "Unauthorized",
      "message": "No authorization token was found"
    }
    ```

    To test with a valid token, you need to:

    1. Create a client application (web or mobile app) that authenticates users
    2. Configure the client to request an access token for your API (using the audience parameter)
    3. Use that access token in the Authorization header

    Example with a token:

    ```bash theme={null}
    curl http://localhost:3001/api/private \
      -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    ```
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a protected API. Your API:

  1. Accepts requests to public endpoints without authentication
  2. Rejects requests to protected endpoints without a valid token
  3. Validates JWT tokens against your Auth0 domain and audience
  4. Provides user information from the token claims via `request.user`
</Check>

***

## Advanced Usage

<Accordion title="Custom Token Claims with TypeScript">
  Extend the Token interface to add type safety for custom claims in your access tokens:

  ```typescript server.ts theme={null}
  import '@auth0/auth0-fastify-api';

  // Extend the Token interface with your custom claims
  declare module '@auth0/auth0-fastify-api' {
    interface Token {
      sub: string;
      permissions?: string[];
      'https://myapp.com/roles'?: string[];
      email?: string;
      email_verified?: boolean;
    }
  }
  ```

  Now TypeScript will recognize your custom claims:

  ```typescript server.ts theme={null}
  fastify.get('/api/profile', {
    preHandler: fastify.requireAuth()
  }, async (request, reply) => {
    // TypeScript knows about these properties
    const userRoles = request.user['https://myapp.com/roles']; // string[] | undefined
    const permissions = request.user.permissions; // string[] | undefined
    const email = request.user.email; // string | undefined

    return {
      userId: request.user.sub,
      roles: userRoles || [],
      permissions: permissions || [],
      email: email,
    };
  });
  ```

  <Note>
    Custom claims must use namespaced URLs (e.g., `https://myapp.com/roles`) unless they're standard OIDC claims. [Learn more about custom claims](https://auth0.com/docs/secure/tokens/json-web-tokens/create-custom-claims).
  </Note>
</Accordion>

<Accordion title="Permission-Based Authorization">
  Check for specific permissions in the access token:

  ```javascript server.js theme={null}
  // Middleware to check for specific permission
  function requirePermission(permission) {
    return async (request, reply) => {
      const permissions = request.user.permissions || [];

      if (!permissions.includes(permission)) {
        return reply.status(403).send({
          error: 'Forbidden',
          message: `Missing required permission: ${permission}`
        });
      }
    };
  }

  // Route requiring 'read:messages' permission
  fastify.get('/api/messages', {
    preHandler: [
      fastify.requireAuth(),
      requirePermission('read:messages')
    ]
  }, async (request, reply) => {
    return {
      messages: ['Message 1', 'Message 2', 'Message 3']
    };
  });

  // Route requiring 'write:messages' permission
  fastify.post('/api/messages', {
    preHandler: [
      fastify.requireAuth(),
      requirePermission('write:messages')
    ]
  }, async (request, reply) => {
    return {
      message: 'Message created successfully',
      id: 'msg_123'
    };
  });
  ```

  <Note>
    Permissions must be configured in your Auth0 API settings and granted to clients. [Learn more about API permissions](https://auth0.com/docs/manage-users/access-control/configure-core-rbac/rbac-users/assign-permissions-users).
  </Note>
</Accordion>

<Accordion title="Role-Based Authorization">
  Implement role-based access control using custom claims:

  ```javascript server.js theme={null}
  // Middleware to check for specific role
  function requireRole(role) {
    return async (request, reply) => {
      const roles = request.user['https://myapp.com/roles'] || [];

      if (!roles.includes(role)) {
        return reply.status(403).send({
          error: 'Forbidden',
          message: `Missing required role: ${role}`
        });
      }
    };
  }

  // Admin-only route
  fastify.get('/api/admin/users', {
    preHandler: [
      fastify.requireAuth(),
      requireRole('admin')
    ]
  }, async (request, reply) => {
    return {
      users: [
        { id: 1, name: 'User 1' },
        { id: 2, name: 'User 2' }
      ]
    };
  });

  // Manager or admin route
  function requireAnyRole(...roles) {
    return async (request, reply) => {
      const userRoles = request.user['https://myapp.com/roles'] || [];
      const hasRole = roles.some(role => userRoles.includes(role));

      if (!hasRole) {
        return reply.status(403).send({
          error: 'Forbidden',
          message: `Missing required role. Need one of: ${roles.join(', ')}`
        });
      }
    };
  }

  fastify.get('/api/reports', {
    preHandler: [
      fastify.requireAuth(),
      requireAnyRole('admin', 'manager')
    ]
  }, async (request, reply) => {
    return { reports: [] };
  });
  ```

  <Note>
    Roles must be added to tokens using Auth0 Actions. [Learn how to add roles to tokens](https://auth0.com/docs/customize/actions/flows-and-triggers/login-flow/add-user-roles-to-id-and-access-tokens).
  </Note>
</Accordion>

<Accordion title="CORS Configuration">
  Enable CORS to allow requests from web applications:

  ```bash theme={null}
  npm install @fastify/cors
  ```

  ```javascript server.js theme={null}
  import cors from '@fastify/cors';

  await fastify.register(cors, {
    origin: ['http://localhost:3000', 'http://localhost:5173'], // Your web app URLs
    credentials: true,
  });
  ```

  For production, specify exact origins:

  ```javascript server.js theme={null}
  await fastify.register(cors, {
    origin: [
      'https://myapp.com',
      'https://www.myapp.com'
    ],
    credentials: true,
    methods: ['GET', 'POST', 'PUT', 'DELETE'],
  });
  ```
</Accordion>

<Accordion title="Error Handling">
  Add comprehensive error handling for authentication errors:

  ```javascript server.js theme={null}
  // Custom error handler
  fastify.setErrorHandler((error, request, reply) => {
    fastify.log.error(error);

    // Handle JWT validation errors
    if (error.statusCode === 401) {
      return reply.status(401).send({
        error: 'Unauthorized',
        message: error.message || 'Invalid or missing access token',
        code: 'UNAUTHORIZED'
      });
    }

    // Handle permission/role errors
    if (error.statusCode === 403) {
      return reply.status(403).send({
        error: 'Forbidden',
        message: error.message || 'Insufficient permissions',
        code: 'FORBIDDEN'
      });
    }

    // Handle other errors
    return reply.status(error.statusCode || 500).send({
      error: 'Internal Server Error',
      message: 'An unexpected error occurred',
      code: 'INTERNAL_ERROR'
    });
  });

  // Not found handler
  fastify.setNotFoundHandler((request, reply) => {
    return reply.status(404).send({
      error: 'Not Found',
      message: `Route ${request.method} ${request.url} not found`,
      code: 'NOT_FOUND'
    });
  });
  ```
</Accordion>

<Accordion title="Rate Limiting">
  Protect your API from abuse with rate limiting:

  ```bash theme={null}
  npm install @fastify/rate-limit
  ```

  ```javascript server.js theme={null}
  import rateLimit from '@fastify/rate-limit';

  await fastify.register(rateLimit, {
    max: 100, // Maximum requests
    timeWindow: '1 minute', // Time window
    errorResponseBuilder: (request, context) => {
      return {
        error: 'Too Many Requests',
        message: `Rate limit exceeded. Try again in ${context.after}`,
        retryAfter: context.after
      };
    }
  });

  // Apply stricter limits to specific routes
  fastify.get('/api/expensive-operation', {
    preHandler: fastify.requireAuth(),
    config: {
      rateLimit: {
        max: 10,
        timeWindow: '1 minute'
      }
    }
  }, async (request, reply) => {
    return { result: 'expensive operation result' };
  });
  ```
</Accordion>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Common Issues and Solutions">
    ### "No authorization token was found"

    **Problem:** The API cannot find the access token in the request.

    **Solutions:**

    1. Ensure the `Authorization` header is present: `Authorization: Bearer YOUR_TOKEN`
    2. Check that "Bearer" is included before the token
    3. Verify the token is not expired

    ### "Invalid token" or "jwt malformed"

    **Problem:** The token format is invalid.

    **Solutions:**

    1. Ensure you're using an **access token**, not an ID token
    2. The token should be obtained with your API's `audience` parameter
    3. Check that the token is a valid JWT (should have three parts separated by dots)

    ### "Invalid signature"

    **Problem:** The token signature doesn't match.

    **Solutions:**

    1. Verify `AUTH0_DOMAIN` matches the domain that issued the token
    2. Ensure you're using RS256 signing algorithm (default)
    3. Check that the token hasn't been modified

    ### "Invalid audience"

    **Problem:** The token's audience doesn't match your API.

    **Solution:** The client application must request a token with the correct audience:

    ```javascript theme={null}
    // In your client app
    const token = await getAccessTokenSilently({
      authorizationParams: {
        audience: 'https://my-fastify-api.example.com' // Must match your API identifier
      }
    });
    ```

    ### CORS errors in browser

    **Problem:** Browser blocks API requests due to CORS policy.

    **Solution:** Install and configure `@fastify/cors`:

    ```bash theme={null}
    npm install @fastify/cors
    ```

    ```javascript theme={null}
    import cors from '@fastify/cors';

    await fastify.register(cors, {
      origin: 'http://localhost:3000', // Your frontend URL
      credentials: true
    });
    ```
  </Accordion>
</AccordionGroup>

***

## Next Steps

Now that you have a protected API, consider exploring:

* **[Fastify Web App Quickstart](/docs/quickstart/webapp/fastify)** - Build a web application that calls your API
* **[Role-Based Access Control](https://auth0.com/docs/manage-users/access-control/rbac)** - Implement fine-grained permissions
* **[API Authorization Best Practices](https://auth0.com/docs/secure/tokens/access-tokens)** - Learn about access token best practices
* **[Monitor Your API](https://auth0.com/docs/deploy-monitor/logs)** - Set up logging and monitoring

***

## Resources

* **[auth0-fastify-api GitHub](https://github.com/auth0/auth0-fastify/tree/main/packages/auth0-fastify-api)** - Source code and examples
* **[Fastify Documentation](https://fastify.dev/)** - Learn more about Fastify
* **[Auth0 API Authentication](https://auth0.com/docs/secure/tokens/access-tokens)** - Understanding access tokens
* **[Auth0 Community](https://community.auth0.com/)** - Get help from the community


# Add Authorization to Your Go Application
Source: https://auth0.com/docs/quickstart/backend/golang/interactive

This tutorial demonstrates how to add authorization to a Go API using go-jwt-middleware.

<QuickstartButtons />

<Recipe>
  <Content>
    This guide demonstrates how to integrate Auth0 with any new or existing Go API application using [go-jwt-middleware](https://github.com/auth0/go-jwt-middleware).

    Each Auth0 API uses the API Identifier, which your application needs to validate the access token.

    <Info>
      **New to Auth0?** Learn [how Auth0 works](/docs/get-started/auth0-overview) and read about [implementing API authentication and authorization](/docs/get-started/authentication-and-authorization-flow) using the OAuth 2.0 framework.
    </Info>

    <Section title={sections[0].title}>
      Before we begin, make sure you have the following:

      <CardGroup>
        <Card title="Go 1.24+" icon="golang">
          Required for v3 of go-jwt-middleware (which uses generics). Check your version with `go version`
        </Card>

        <Card title="Auth0 Account" icon="shield-check">
          Sign up for free at [auth0.com/signup](https://auth0.com/signup)
        </Card>

        <Card title="Code Editor" icon="code">
          VS Code, GoLand, or your preferred editor
        </Card>

        <Card title="Terminal Access" icon="terminal">
          Command line for running Go commands
        </Card>
      </CardGroup>

      <Tip>
        **New to Go?** This tutorial assumes basic familiarity with Go syntax and HTTP servers. Check out [Go by Example](https://gobyexample.com/) if you need a refresher.
      </Tip>
    </Section>

    <Section title={sections[1].title}>
      Create an API in your Auth0 Dashboard to get started.

      <Steps>
        <Step title="Navigate to APIs">
          Go to the [APIs](https://manage.auth0.com/#/apis) section in the Auth0 dashboard and click **Create API**.

          <Frame>![Create API](https://cdn2.auth0.com/docs/1.14550.0/media/articles/server-apis/create-api.png)</Frame>
        </Step>

        <Step title="Configure API settings">
          * **Name**: `Quickstarts` (or any descriptive name)
          * **Identifier**: `https://quickstarts/api` (this becomes your `audience`)
          * **Signing Algorithm**: Leave as **RS256** (recommended)

          <Tip>
            The API Identifier is a logical identifier - it doesn't need to be a real URL.
          </Tip>
        </Step>

        <Step title="Understand RS256">
          Your API uses **RS256** (asymmetric algorithm):

          * Auth0 signs tokens with a **private key**
          * Your API verifies tokens with a **public key** (from JWKS)
          * Public keys are fetched from: `https://{yourDomain}/.well-known/jwks.json`
        </Step>
      </Steps>
    </Section>

    <Section title={sections[2].title}>
      Permissions let you define how resources can be accessed on behalf of the user with a given access token.

      In your API settings, click the **Permissions** tab and create the following permission:

      | Permission      | Description                |
      | --------------- | -------------------------- |
      | `read:messages` | Read messages from the API |

      <Frame>![Configure Permissions](https://cdn2.auth0.com/docs/1.14550.0/media/articles/server-apis/configure-permissions.png)</Frame>

      <Info>
        This tutorial uses the `read:messages` scope to protect the scoped endpoint.
      </Info>
    </Section>

    <Section title={sections[3].title}>
      Set up your Go project structure and install the required dependencies.

      <Steps>
        <Step title="Create project directory">
          ```bash theme={null}
          mkdir myapi && cd myapi
          ```
        </Step>

        <Step title="Initialize Go module">
          ```bash theme={null}
          go mod init github.com/yourorg/myapi
          ```
        </Step>

        <Step title="Install dependencies">
          ```bash theme={null}
          go get github.com/auth0/go-jwt-middleware/v3
          go get github.com/joho/godotenv
          ```
        </Step>

        <Step title="Download all dependencies">
          ```bash theme={null}
          go mod download
          ```
        </Step>
      </Steps>

      <Accordion title="View complete go.mod file">
        ```go theme={null}
        // go.mod
        module github.com/yourorg/myapi

        go 1.24

        require (
            github.com/auth0/go-jwt-middleware/v3 v3.0.0
            github.com/joho/godotenv v1.5.1
        )
        ```
      </Accordion>

      <Warning>
        **Go 1.24+ Required**: This implementation uses generics for type-safe claims handling. Verify your version with `go version`.
      </Warning>
    </Section>

    <Section title={sections[4].title}>
      Create a `.env` file in your project root to store Auth0 configuration:

      ```env lines theme={null}
      # The URL of your Auth0 Tenant Domain.
      # If you're using a Custom Domain, set this to that value instead.
      AUTH0_DOMAIN='{yourDomain}'

      # Your Auth0 API's Identifier
      # Example: https://quickstarts/api
      AUTH0_AUDIENCE='{yourApiIdentifier}'
      ```

      Create a config package to load and validate these environment variables in `internal/config/auth.go` (see the code in the right sidebar).

      <AccordionGroup>
        <Accordion title="Why use a config package?" icon="gear">
          **Benefits of centralized configuration**:

          * Single source of truth for environment variables
          * Clear error messages for missing configuration
          * Type-safe configuration access
          * Easy to test and mock
        </Accordion>

        <Accordion title="Security best practices" icon="shield-check">
          * Never commit `.env` files to version control
          * Add `.env` to your `.gitignore` file
          * Use different `.env` files for different environments
          * Validate all required config on startup (fail fast)
        </Accordion>
      </AccordionGroup>
    </Section>

    <Section title={sections[5].title}>
      Create custom claims to extract and validate application-specific data from JWTs in `internal/auth/claims.go` (see the code in the right sidebar).

      <AccordionGroup>
        <Accordion title="Why custom claims?" icon="fingerprint">
          **Custom claims allow you to**:

          * Extract permissions (scopes) from JWT tokens
          * Validate claim formatting automatically
          * Add domain-specific authorization logic
          * Keep business logic separate from validation

          **Automatic Validation**: The `Validate` method is called automatically by the middleware after parsing the JWT.
        </Accordion>

        <Accordion title="Validation behavior" icon="shield-check">
          The `Validate` method ensures:

          * **Scope is optional** - allows tokens without scopes (for `/api/private` endpoint)
          * **Format validation** - when scope exists, checks for proper formatting
          * **No whitespace issues** - prevents malformed scope strings
          * **Called automatically** - runs before your handlers execute
        </Accordion>

        <Accordion title="HasScope method" icon="code">
          The `HasScope` helper method:

          * Parses space-separated scopes (e.g., `"read:messages write:messages"`)
          * Returns `false` if scope is empty (prevents false positives)
          * Used in handlers to enforce permission-based access
        </Accordion>
      </AccordionGroup>
    </Section>

    <Section title={sections[6].title}>
      Create the JWT validator in `internal/auth/validator.go` (see the code in the right sidebar).

      <AccordionGroup>
        <Accordion title="What does the validator do?" icon="shield-check">
          The validator performs these security checks on every JWT:

          * **Signature verification** using Auth0's public keys (JWKS)
          * **Issuer validation** - `iss` claim matches your Auth0 domain
          * **Audience validation** - `aud` claim matches your API identifier
          * **Expiration check** - token hasn't expired (`exp` claim)
          * **Time validity** - token is currently valid (`nbf` and `iat` claims)
        </Accordion>

        <Accordion title="Key features explained" icon="lightbulb">
          **Options Pattern**: Uses functional options like `validator.WithAllowedClockSkew()` for flexible configuration

          **JWKS Caching**: Automatically fetches and caches Auth0's public keys every 5 minutes, reducing network calls

          **Algorithm Specification**: Explicitly sets RS256 to prevent [algorithm confusion attacks](https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/)

          **Clock Skew Tolerance**: Allows 30 seconds for distributed system clock differences
        </Accordion>

        <Accordion title="Why separate validator from middleware?" icon="layer-group">
          The **core-adapter architecture** separates JWT validation logic (core) from HTTP concerns (adapter). This means:

          * You can reuse the same validator across different frameworks
          * Easier to test validation logic in isolation
          * Can use with HTTP, gRPC, or any other transport
        </Accordion>
      </AccordionGroup>
    </Section>

    <Section title={sections[7].title}>
      Create the HTTP middleware that wraps your validator in `internal/auth/middleware.go` (see the code in the right sidebar).

      Built-in structured logging using Go's standard `log/slog` package. The middleware will log token validation events for debugging.

      The middleware:

      * Extracts JWT from `Authorization: Bearer <token>` header
      * Validates token using the core validator
      * Skips validation for OPTIONS requests (CORS preflight)
      * Injects validated claims into request context
      * Returns RFC 6750 compliant error responses on failure
    </Section>

    <Section title={sections[8].title}>
      Create API handlers with different protection levels in `internal/handlers/api.go` and the main server in `cmd/server/main.go` (see the code in the right sidebar).

      **Generic Claims Feature**:

      * `GetClaims[*validator.ValidatedClaims]` uses generics for compile-time type safety
      * No runtime type assertions that can panic
      * IDE autocomplete for claim fields
      * Custom claims implement `Validate(ctx context.Context) error` for domain-specific validation

      **Endpoint Protection Levels:**

      1. **Public** (`/api/public`): No authentication required
      2. **Private** (`/api/private`): Valid JWT required
      3. **Scoped** (`/api/private-scoped`): Valid JWT + specific scope (`read:messages`) required

      **Production Features:**

      * Graceful shutdown handling
      * Configurable timeouts (read, write, idle)
      * Proper error handling
      * Environment variable configuration
    </Section>

    <Section title={sections[9].title}>
      Now let's test your implementation to make sure everything works correctly.

      <Steps>
        <Step title="Start your server">
          ```bash theme={null}
          go run cmd/server/main.go
          ```

          You should see: `Server starting on :8080`

          <Info>
            The server automatically loads environment variables from your `.env` file using godotenv.
          </Info>
        </Step>

        <Step title="Get a test token">
          <Tabs>
            <Tab title="From Auth0 Dashboard">
              1. Go to your API in the [Auth0 Dashboard](https://manage.auth0.com/#/apis)
              2. Click the **Test** tab
              3. Click **Copy Token** to get a valid JWT

              <Frame>
                <img />
              </Frame>
            </Tab>

            <Tab title="Via Client Credentials">
              Implement the [Client Credentials Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow) for machine-to-machine authentication.
            </Tab>
          </Tabs>
        </Step>

        <Step title="Test public endpoint">
          This endpoint should work without authentication:

          ```bash theme={null}
          curl http://localhost:8080/api/public
          ```

          <Check>**Expected**: 200 OK with message "Hello from a public endpoint!"</Check>
        </Step>

        <Step title="Test private endpoint (without token)">
          This should fail with a 401 error:

          ```bash theme={null}
          curl http://localhost:8080/api/private
          ```

          <Check>**Expected**: 401 Unauthorized `{"error": "invalid_token"}`</Check>
        </Step>

        <Step title="Test private endpoint (with token)">
          This should succeed with a valid token:

          ```bash theme={null}
          curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
               http://localhost:8080/api/private
          ```

          <Check>**Expected**: 200 OK with user information</Check>
        </Step>

        <Step title="Test scoped endpoint">
          This requires the `read:messages` scope:

          ```bash theme={null}
          curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
               http://localhost:8080/api/private-scoped
          ```

          <Check>**Expected**: 200 OK if token has `read:messages` scope, 403 Forbidden otherwise</Check>
        </Step>
      </Steps>

      <Note>
        **Checkpoint Complete!** If all tests passed, your Auth0 integration is working correctly. Your API now:

        * Validates JWTs from Auth0
        * Protects private endpoints
        * Enforces permission-based access
      </Note>
    </Section>

    ## Continue the Tutorial

    <CardGroup>
      <Card title="Using Your API" icon="code" href="/docs/quickstart/backend/golang/02-using">
        Learn how to call your protected Go API from client applications with examples in cURL, Go, Java, Node.js, Python, Ruby, and Swift.
      </Card>

      <Card title="Troubleshooting Guide" icon="screwdriver-wrench" href="/docs/quickstart/backend/golang/03-troubleshooting">
        Comprehensive debugging guide covering common issues like invalid issuer, audience errors, JWKS problems, and more.
      </Card>
    </CardGroup>

    ### Quick Troubleshooting

    <AccordionGroup>
      <Accordion title="Invalid Audience Error" icon="triangle-exclamation">
        **Error Message:**

        ```json theme={null}
        {"error": "invalid_token", "description": "aud claim mismatch"}
        ```

        **Solution:** Verify `AUTH0_AUDIENCE` exactly matches your API Identifier from the Auth0 Dashboard.

        ```bash theme={null}
        # Correct
        AUTH0_AUDIENCE=https://quickstarts/api

        # Wrong (no trailing slash should be added)
        AUTH0_AUDIENCE=https://quickstarts/api/
        ```
      </Accordion>

      <Accordion title="JWKS Endpoint Unreachable" icon="triangle-exclamation">
        **Error Message:**

        ```
        error fetching keys: connection refused
        ```

        **Solutions:**

        * Check network connectivity to Auth0 (firewall/proxy settings)
        * Test JWKS endpoint manually:
          ```bash theme={null}
          curl https://your-tenant.us.auth0.com/.well-known/jwks.json
          ```
        * Verify correct Auth0 region (us/eu/au)
      </Accordion>

      <Accordion title="Wrong Import Path" icon="triangle-exclamation">
        **Error Message:**

        ```
        cannot find package "github.com/auth0/go-jwt-middleware/v3/..."
        ```

        **Solution:** Ensure all imports use the `/v3` suffix:

        ```go theme={null}
        // Correct
        import "github.com/auth0/go-jwt-middleware/v3/validator"

        // Wrong
        import "github.com/auth0/go-jwt-middleware/validator"
        ```
      </Accordion>

      <Accordion title="Token Expired Error" icon="triangle-exclamation">
        **Error Message:**

        ```json theme={null}
        {"error": "invalid_token", "description": "token is expired"}
        ```

        **Solutions:**

        * Get a new token from the Auth0 Dashboard Test tab
        * Check if your server clock is synchronized
        * Adjust clock skew tolerance:
          ```go theme={null}
          validator.WithAllowedClockSkew(60*time.Second)
          ```
      </Accordion>
    </AccordionGroup>

    <Accordion title="Advanced: DPoP Support" icon="lock">
      **DPoP (Demonstrating Proof-of-Possession)** per RFC 9449 provides enhanced security by preventing token theft through cryptographic key binding.

      **When to use DPoP:**

      * Financial APIs handling sensitive transactions
      * Healthcare APIs with patient data
      * High-security enterprise applications

      **Enable DPoP:**

      ```go theme={null}
      // internal/auth/middleware.go
      func NewMiddleware(jwtValidator *validator.Validator) *jwtmiddleware.JWTMiddleware {
          return jwtmiddleware.New(
              jwtmiddleware.WithValidator(jwtValidator),
              jwtmiddleware.WithDPoPMode(jwtmiddleware.DPoPRequired),
              jwtmiddleware.WithLogger(slog.Default()),
          )
      }
      ```

      **DPoP Modes:**

      * `DPoPAllowed` (default): Accept both Bearer and DPoP tokens
      * `DPoPRequired`: Only accept DPoP tokens, reject Bearer
      * `DPoPDisabled`: Only accept Bearer tokens, reject DPoP

      Learn more in the [DPoP documentation](https://github.com/auth0/go-jwt-middleware#dpop-support).
    </Accordion>

    ### Best Practices

    **Security**:

    * Always use HTTPS in production
    * Validate algorithms explicitly (prevents algorithm confusion attacks)
    * Use short-lived access tokens (15-30 minutes) with refresh tokens
    * Enable DPoP for sensitive APIs
    * Never log tokens in plaintext

    **Performance**:

    * Reuse validator instances (create once at startup)
    * Configure JWKS cache appropriately (5-15 minute TTL)
    * Set reasonable HTTP timeouts
    * Use connection pooling (enabled by default in Go)

    **Maintainability**:

    * Use environment variables for credentials
    * Define type-safe custom claims structs
    * Enable structured logging with `slog`
    * Test with mock validators
    * Document custom claims with JSON tags

    ### Project Structure

    Recommended structure for production Go APIs:

    ```
    myapi/
    ├── cmd/
    │   └── server/
    │       └── main.go              # Application entry point
    ├── internal/
    │   ├── auth/
    │   │   ├── claims.go            # Custom claims definition
    │   │   ├── middleware.go        # JWT middleware setup
    │   │   └── validator.go         # Validator configuration
    │   ├── config/
    │   │   └── auth.go              # Environment configuration
    │   └── handlers/
    │       └── api.go               # HTTP handlers
    ├── .env                         # Environment variables (not committed)
    ├── .gitignore
    ├── go.mod
    ├── go.sum
    └── README.md
    ```

    ### Next Steps

    Now that you have a working Go API with Auth0 authentication, explore advanced features:

    <CardGroup>
      <Card title="Custom Claims Validation" icon="code" href="https://github.com/auth0/go-jwt-middleware#custom-claims">
        Add domain-specific authorization logic with type-safe claims
      </Card>

      <Card title="Token Refresh" icon="arrows-rotate" href="https://auth0.com/docs/secure/tokens/refresh-tokens">
        Implement refresh token flow for long-lived sessions
      </Card>

      <Card title="DPoP Security" icon="lock" href="https://github.com/auth0/go-jwt-middleware#dpop-support">
        Enable proof-of-possession for enhanced security
      </Card>

      <Card title="Organizations" icon="building" href="https://auth0.com/docs/manage-users/organizations">
        Enable multi-tenant authorization for B2B apps
      </Card>

      <Card title="Production Checklist" icon="circle-check" href="https://auth0.com/docs/deploy-monitor/production-checks">
        Pre-launch security review and best practices
      </Card>

      <Card title="API Documentation" icon="book" href="https://github.com/auth0/go-jwt-middleware">
        Complete SDK reference and advanced examples
      </Card>
    </CardGroup>
  </Content>

  <SideMenu>
    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```go title="internal/config/auth.go" theme={null}
        package config

        import (
            "fmt"
            "os"
        )

        type AuthConfig struct {
            Domain   string
            Audience string
        }

        func LoadAuthConfig() (*AuthConfig, error) {
            domain := os.Getenv("AUTH0_DOMAIN")
            if domain == "" {
                return nil, fmt.Errorf("AUTH0_DOMAIN environment variable required")
            }

            audience := os.Getenv("AUTH0_AUDIENCE")
            if audience == "" {
                return nil, fmt.Errorf("AUTH0_AUDIENCE environment variable required")
            }

            return &AuthConfig{
                Domain:   domain,
                Audience: audience,
            }, nil
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```go title="internal/auth/claims.go" theme={null}
        package auth

        import (
        	"context"
        	"fmt"
        	"strings"
        )

        // CustomClaims contains custom data we want to parse from the JWT.
        type CustomClaims struct {
        	Scope string `json:"scope"`
        }

        // Validate ensures the custom claims are properly formatted.
        func (c *CustomClaims) Validate(ctx context.Context) error {
        	// Scope is optional, but if present, must be properly formatted
        	if c.Scope == "" {
        		return nil // No scope is valid - not all endpoints require permissions
        	}

        	// Validate scope format (no leading/trailing spaces, no double spaces)
        	if strings.TrimSpace(c.Scope) != c.Scope {
        		return fmt.Errorf("scope claim has invalid whitespace")
        	}

        	if strings.Contains(c.Scope, "  ") {
        		return fmt.Errorf("scope claim contains double spaces")
        	}

        	return nil
        }

        // HasScope checks whether our claims have a specific scope.
        func (c *CustomClaims) HasScope(expectedScope string) bool {
        	if c.Scope == "" {
        		return false
        	}

        	scopes := strings.Split(c.Scope, " ")
        	for _, scope := range scopes {
        		if scope == expectedScope {
        			return true
        		}
        	}
        	return false
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```go title="internal/auth/validator.go" theme={null}
        package auth

        import (
        	"fmt"
        	"net/url"
        	"time"

        	"github.com/auth0/go-jwt-middleware/v3/jwks"
        	"github.com/auth0/go-jwt-middleware/v3/validator"
        )

        func NewValidator(domain, audience string) (*validator.Validator, error) {
        	// Construct issuer URL (must include trailing slash)
        	issuerURL, err := url.Parse("https://" + domain + "/")
        	if err != nil {
        		return nil, fmt.Errorf("failed to parse issuer URL: %w", err)
        	}

        	// Initialize JWKS provider using v3 options pattern
        	provider, err := jwks.NewCachingProvider(
        		jwks.WithIssuerURL(issuerURL),
        		jwks.WithCacheTTL(5*time.Minute),
        	)
        	if err != nil {
        		return nil, fmt.Errorf("failed to create JWKS provider: %w", err)
        	}

        	// Create validator using v3 options pattern
        	jwtValidator, err := validator.New(
        		validator.WithKeyFunc(provider.KeyFunc),         // Provides public keys for RS256
        		validator.WithAlgorithm(validator.RS256),        // Algorithm (prevents confusion attacks)
        		validator.WithIssuer(issuerURL.String()),        // Validates 'iss' claim
        		validator.WithAudience(audience),                // Validates 'aud' claim
        		validator.WithCustomClaims(func() validator.CustomClaims {
        			return &CustomClaims{}                       // Returns our custom claims from claims.go
        		}),
        		validator.WithAllowedClockSkew(30*time.Second),  // Allows 30s clock drift
        	)
        	if err != nil {
        		return nil, fmt.Errorf("failed to create validator: %w", err)
        	}

        	return jwtValidator, nil
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```go title="internal/auth/middleware.go" theme={null}
        package auth

        import (
        	"log/slog"
        	"net/http"

        	jwtmiddleware "github.com/auth0/go-jwt-middleware/v3"
        	"github.com/auth0/go-jwt-middleware/v3/validator"
        )

        func NewMiddleware(jwtValidator *validator.Validator) (*jwtmiddleware.JWTMiddleware, error) {
        	return jwtmiddleware.New(
        		jwtmiddleware.WithValidator(jwtValidator),
        		jwtmiddleware.WithValidateOnOptions(false),
        		jwtmiddleware.WithErrorHandler(func(w http.ResponseWriter, r *http.Request, err error) {
        			slog.Error("JWT validation failed", "error", err, "path", r.URL.Path)
        			w.Header().Set("Content-Type", "application/json")
        			w.WriteHeader(http.StatusUnauthorized)
        			w.Write([]byte(`{"message":"Failed to validate JWT."}`))
        		}),
        	)
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```go title="internal/handlers/api.go" theme={null}
        package handlers

        import (
        	"encoding/json"
        	"net/http"

        	"github.com/yourorg/myapi/internal/auth"
        	jwtmiddleware "github.com/auth0/go-jwt-middleware/v3"
        	"github.com/auth0/go-jwt-middleware/v3/validator"
        )

        // PublicHandler - no authentication required
        func PublicHandler(w http.ResponseWriter, r *http.Request) {
        	response := map[string]string{
        		"message": "Hello from a public endpoint! You don't need to be authenticated to see this.",
        	}
        	w.Header().Set("Content-Type", "application/json")
        	json.NewEncoder(w).Encode(response)
        }

        // PrivateHandler - requires valid JWT
        func PrivateHandler(w http.ResponseWriter, r *http.Request) {
        	response := map[string]string{
        		"message": "Hello from a private endpoint! You need to be authenticated to see this.",
        	}
        	w.Header().Set("Content-Type", "application/json")
        	json.NewEncoder(w).Encode(response)
        }

        // ScopedHandler - requires 'read:messages' permission
        func ScopedHandler(w http.ResponseWriter, r *http.Request) {
        	// Extract validated claims using generics (v3 feature)
        	claims, err := jwtmiddleware.GetClaims[*validator.ValidatedClaims](r.Context())
        	if err != nil {
        		w.Header().Set("Content-Type", "application/json")
        		w.WriteHeader(http.StatusUnauthorized)
        		w.Write([]byte(`{"message":"Unauthorized."}`))
        		return
        	}

        	// Check for required scope in custom claims
        	customClaims, ok := claims.CustomClaims.(*auth.CustomClaims)
        	if !ok || !customClaims.HasScope("read:messages") {
        		w.Header().Set("Content-Type", "application/json")
        		w.WriteHeader(http.StatusForbidden)
        		w.Write([]byte(`{"message":"Insufficient scope."}`))
        		return
        	}

        	response := map[string]string{
        		"message": "Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this.",
        	}
        	w.Header().Set("Content-Type", "application/json")
        	json.NewEncoder(w).Encode(response)
        }
        ```

        ```go title="cmd/server/main.go" theme={null}
        package main

        import (
        	"context"
        	"log"
        	"net/http"
        	"os"
        	"os/signal"
        	"time"

        	"github.com/yourorg/myapi/internal/auth"
        	"github.com/yourorg/myapi/internal/config"
        	"github.com/yourorg/myapi/internal/handlers"
        	"github.com/joho/godotenv"
        )

        func main() {
        	// Load environment variables from .env file
        	if err := godotenv.Load(); err != nil {
        		log.Println("No .env file found, using environment variables")
        	}

        	// Load Auth0 configuration
        	cfg, err := config.LoadAuthConfig()
        	if err != nil {
        		log.Fatalf("Failed to load config: %v", err)
        	}

        	// Create JWT validator
        	jwtValidator, err := auth.NewValidator(cfg.Domain, cfg.Audience)
        	if err != nil {
        		log.Fatalf("Failed to create validator: %v", err)
        	}

        	// Create HTTP middleware
        	middleware, err := auth.NewMiddleware(jwtValidator)
        	if err != nil {
        		log.Fatalf("Failed to create middleware: %v", err)
        	}

        	// Setup routes
        	mux := http.NewServeMux()
        	mux.HandleFunc("/api/public", handlers.PublicHandler)
        	mux.Handle("/api/private", middleware.CheckJWT(http.HandlerFunc(handlers.PrivateHandler)))
        	mux.Handle("/api/private-scoped", middleware.CheckJWT(http.HandlerFunc(handlers.ScopedHandler)))

        	// Configure server with production timeouts
        	srv := &http.Server{
        		Addr:         ":8080",
        		Handler:      mux,
        		ReadTimeout:  15 * time.Second,
        		WriteTimeout: 15 * time.Second,
        		IdleTimeout:  60 * time.Second,
        	}

        	// Start server in goroutine
        	go func() {
        		log.Println("Server starting on :8080")
        		if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
        			log.Fatalf("Server failed: %v", err)
        		}
        	}()

        	// Graceful shutdown
        	quit := make(chan os.Signal, 1)
        	signal.Notify(quit, os.Interrupt)
        	<-quit

        	log.Println("Shutting down server...")
        	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
        	defer cancel()

        	if err := srv.Shutdown(ctx); err != nil {
        		log.Fatalf("Server forced to shutdown: %v", err)
        	}

        	log.Println("Server exited")
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>
  </SideMenu>
</Recipe>


# Add Authorization to Your Spring Boot Application
Source: https://auth0.com/docs/quickstart/backend/java-spring-security5/interactive

This guide demonstrates how to integrate Auth0 with any new or existing Spring Boot application.

<QuickstartButtons />

<Recipe>
  <Content>
    Auth0 allows you to quickly add authorization to your application. This guide demonstrates how to integrate Auth0
    with any new or existing Spring Boot application.

    If you have not created an API in your Auth0 dashboard yet, use the interactive selector to create a new Auth0 API
    or select an existing API that represents the project you want to integrate with.

    Review [our getting started
    guide](https://auth0.com/docs/get-started/auth0-overview/set-up-apis) to set up your first API through the Auth0 dashboard.

    Each Auth0 API uses the API Identifier, which your application needs to validate the access token.

    <Info>
      **New to Auth0?** Learn [how Auth0 works](https://auth0.com/docs/overview)
      and read about [implementing API authentication
      and authorization](https://auth0.com/docs/api-auth) using the OAuth 2.0 framework.
    </Info>

    <Section title={sections[0].title}>
      Permissions let you define how resources can be accessed on behalf of the user with a given access token. For
      example, you might choose to grant read access to the `messages` resource if users have the manager
      access level, and a write access to that resource if they have the administrator access level.

      You can define allowed permissions in the **Permissions** view of the Auth0 Dashboard's [APIs](https://manage.auth0.com/dashboard/us/dev-1-2s2aq0/apis) section.

      <Frame>
        <img />
      </Frame>

      <Info>
        This example uses the `read:messages` scope.
      </Info>
    </Section>

    <Section title={sections[1].title}>
      The sample project uses a `/src/main/resources/application.yml` file, which configures it to use the
      correct Auth0 **domain** and **API Identifier** for your API. If you download the code from this page it
      will be automatically configured. If you clone the example from GitHub, you will need to fill it in yourself.
    </Section>

    <Section title={sections[2].title}>
      If you are using Gradle, you can add the required dependencies using the [Spring Boot Gradle Plugin](https://docs.spring.io/spring-boot/docs/current/gradle-plugin/reference/html/) and the [Dependency Management Plugin](https://docs.spring.io/dependency-management-plugin/docs/current/reference/html/) to resolve dependency versions:

      ```gradle lines theme={null}
      // build.gradle
      plugins {

          id 'java'

          id 'org.springframework.boot'

          version '3.1.5'

          id 'io.spring.dependency-management'

          version '1.1.3'

      }

      dependencies {

          implementation 'org.springframework.boot:spring-boot-starter-web'

          implementation 'com.okta.spring:okta-spring-boot-starter:3.0.5'

      }
      ```

      If you are using Maven, add the Spring dependencies to your `pom.xml` file:

      ```xml lines theme={null}
      // pom.xml
      <parent>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-parent</artifactId>
      <version>3.1.5</version>
      <relativePath/>
      </parent>
      <dependencies>
      <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
      </dependency>
      <dependency>
      <groupId>com.okta.spring</groupId>
      <artifactId>okta-spring-boot-starter</artifactId>
      <version>3.0.5</version>
      </dependency>
      </dependencies>
      ```
    </Section>

    <Section title={sections[3].title}>
      To configure the application as a Resource Server and validate the JWTs, create a class that will provide an
      instance of `SecurityFilterChain`, and add the `@Configuration` annotation.

      ### Protect API endpoints

      The routes shown below are available for the following requests:

      * `GET /api/public`: available for non-authenticated requests
      * `GET /api/private`: available for authenticated requests containing an access token with no
        additional scopes
      * `GET /api/private-scoped`: available for authenticated requests containing an access token with
        the `read:messages`scope granted

      The example below shows how to secure API methods using the `HttpSecurity` object provided in the
      `filterChain()` method of the `SecurityConfig` class. Route matchers restrict access based
      on the level of authorization required.

      <Info>
        By default, Spring Security creates a `GrantedAuthority` for each scope in the
        `scope` claim of the JWT. This scope enables using the
        `hasAuthority("SCOPE_read:messages")` method to restrict access to a valid JWT that contains
        the `read:messages` scope.
      </Info>
    </Section>

    <Section title={sections[4].title}>
      To make your endpoint return a JSON, you can use a Java record. The member variables of this object is serialized
      into the key value for your JSON. Create a new record named `Message` as an example domain object to
      return during the API calls.
    </Section>

    <Section title={sections[5].title}>
      Create a new class named `APIController` to handle requests to the endpoints. The
      `APIController` has three routes as defined in the [Protect API Endpoints](https://auth0.com/docs/quickstart/backend/java-spring-security5/interactive#configure-the-resource-server) section. For this example, allow all origins through
      `@CrossOrigin` annotation. Real applications should configure `CORS` for their use case.
    </Section>

    <Section title={sections[6].title}>
      To build and run the sample project, execute the `bootRun` Gradle task.

      Linux or macOS:

      ```sh lines theme={null}
      ./gradlew bootRun
      ```

      Windows:

      ```sh lines theme={null}
      gradlew.bat bootRun
      ```

      If you are configuring your own application using Maven and the [Spring Boot Maven Plugin](https://docs.spring.io/spring-boot/docs/current/reference/html/build-tool-plugins-maven-plugin.html), you can execute the
      `spring-boot:run` goal.

      Linux or macOS:

      ```sh lines theme={null}
      mvn spring-boot:run
      ```

      Windows:

      ```sh lines theme={null}
      mvn.cmd spring-boot:run
      ```

      <Note>
        ##### Checkpoint

        The sample application will be available at `http://localhost:3010/`. Read about how to test
        and use your API in the [Using Your API](https://auth0.com/docs/quickstart/backend/java-spring-security5/02-using) article.
      </Note>
    </Section>
  </Content>

  <SideMenu>
    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```yml application.yml lines highlight={} theme={null}
        okta:
          oauth2:
            # Replace with the domain of your Auth0 tenant.
            issuer: https://{yourDomain}/
            # Replace with the API Identifier for your Auth0 API.
            audience: {yourApiIdentifier}
        ```

        ```java SecurityConfig.java lines highlight={} theme={null}
        package com.auth0.example.security;

            import org.springframework.context.annotation.Bean;
            import org.springframework.context.annotation.Configuration;
            import org.springframework.security.config.annotation.web.builders.HttpSecurity;
            import org.springframework.security.web.SecurityFilterChain;

            import static org.springframework.security.config.Customizer.withDefaults;

            /**
             * Configures our application with Spring Security to restrict access to our API endpoints.
             */
            @Configuration
            public class SecurityConfig {

        @Bean
        public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
            /*
            This is where we configure the security required for our endpoints and setup our app to serve as
            an OAuth2 Resource Server, using JWT validation.
            */
            return http
                    .authorizeHttpRequests((authorize) -> authorize
                        .requestMatchers("/api/public").permitAll()
                        .requestMatchers("/api/private").authenticated()
                        .requestMatchers("/api/private-scoped").hasAuthority("SCOPE_read:messages")
                    )
                    .cors(withDefaults())
                    .oauth2ResourceServer(oauth2 -> oauth2
                        .jwt(withDefaults())
                    )
                    .build();
        }
            }
        ```

        ```java APIController.java lines highlight={} theme={null}
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```yml application.yml lines highlight={} theme={null}
        okta:
          oauth2:
            # Replace with the domain of your Auth0 tenant.
            issuer: https://{yourDomain}/
            # Replace with the API Identifier for your Auth0 API.
            audience: {yourApiIdentifier}
        ```

        ```java SecurityConfig.java lines highlight={} theme={null}
        package com.auth0.example.security;

            import org.springframework.context.annotation.Bean;
            import org.springframework.context.annotation.Configuration;
            import org.springframework.security.config.annotation.web.builders.HttpSecurity;
            import org.springframework.security.web.SecurityFilterChain;

            import static org.springframework.security.config.Customizer.withDefaults;

            /**
             * Configures our application with Spring Security to restrict access to our API endpoints.
             */
            @Configuration
            public class SecurityConfig {

        @Bean
        public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
            /*
            This is where we configure the security required for our endpoints and setup our app to serve as
            an OAuth2 Resource Server, using JWT validation.
            */
            return http
                    .authorizeHttpRequests((authorize) -> authorize
                        .requestMatchers("/api/public").permitAll()
                        .requestMatchers("/api/private").authenticated()
                        .requestMatchers("/api/private-scoped").hasAuthority("SCOPE_read:messages")
                    )
                    .cors(withDefaults())
                    .oauth2ResourceServer(oauth2 -> oauth2
                        .jwt(withDefaults())
                    )
                    .build();
        }
            }
        ```

        ```java APIController.java lines highlight={} theme={null}
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```java SecurityConfig.java lines highlight={} theme={null}
        package com.auth0.example.security;

            import org.springframework.context.annotation.Bean;
            import org.springframework.context.annotation.Configuration;
            import org.springframework.security.config.annotation.web.builders.HttpSecurity;
            import org.springframework.security.web.SecurityFilterChain;

            import static org.springframework.security.config.Customizer.withDefaults;

            /**
             * Configures our application with Spring Security to restrict access to our API endpoints.
             */
            @Configuration
            public class SecurityConfig {

        @Bean
        public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
            /*
            This is where we configure the security required for our endpoints and setup our app to serve as
            an OAuth2 Resource Server, using JWT validation.
            */
            return http
                    .authorizeHttpRequests((authorize) -> authorize
                        .requestMatchers("/api/public").permitAll()
                        .requestMatchers("/api/private").authenticated()
                        .requestMatchers("/api/private-scoped").hasAuthority("SCOPE_read:messages")
                    )
                    .cors(withDefaults())
                    .oauth2ResourceServer(oauth2 -> oauth2
                        .jwt(withDefaults())
                    )
                    .build();
        }
            }
        ```

        ```yml application.yml lines highlight={} theme={null}
        okta:
          oauth2:
            # Replace with the domain of your Auth0 tenant.
            issuer: https://{yourDomain}/
            # Replace with the API Identifier for your Auth0 API.
            audience: {yourApiIdentifier}
        ```

        ```java APIController.java lines highlight={} theme={null}
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```yml application.yml lines highlight={} theme={null}
        okta:
          oauth2:
            # Replace with the domain of your Auth0 tenant.
            issuer: https://{yourDomain}/
            # Replace with the API Identifier for your Auth0 API.
            audience: {yourApiIdentifier}
        ```

        ```java SecurityConfig.java lines highlight={} theme={null}
        package com.auth0.example.security;

            import org.springframework.context.annotation.Bean;
            import org.springframework.context.annotation.Configuration;
            import org.springframework.security.config.annotation.web.builders.HttpSecurity;
            import org.springframework.security.web.SecurityFilterChain;

            import static org.springframework.security.config.Customizer.withDefaults;

            /**
             * Configures our application with Spring Security to restrict access to our API endpoints.
             */
            @Configuration
            public class SecurityConfig {

        @Bean
        public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
            /*
            This is where we configure the security required for our endpoints and setup our app to serve as
            an OAuth2 Resource Server, using JWT validation.
            */
            return http
                    .authorizeHttpRequests((authorize) -> authorize
                        .requestMatchers("/api/public").permitAll()
                        .requestMatchers("/api/private").authenticated()
                        .requestMatchers("/api/private-scoped").hasAuthority("SCOPE_read:messages")
                    )
                    .cors(withDefaults())
                    .oauth2ResourceServer(oauth2 -> oauth2
                        .jwt(withDefaults())
                    )
                    .build();
        }
            }
        ```

        ```java APIController.java lines highlight={} theme={null}
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```java APIController.java lines highlight={} theme={null}
        ```

        ```java SecurityConfig.java lines highlight={} theme={null}
        package com.auth0.example.security;

            import org.springframework.context.annotation.Bean;
            import org.springframework.context.annotation.Configuration;
            import org.springframework.security.config.annotation.web.builders.HttpSecurity;
            import org.springframework.security.web.SecurityFilterChain;

            import static org.springframework.security.config.Customizer.withDefaults;

            /**
             * Configures our application with Spring Security to restrict access to our API endpoints.
             */
            @Configuration
            public class SecurityConfig {

        @Bean
        public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
            /*
            This is where we configure the security required for our endpoints and setup our app to serve as
            an OAuth2 Resource Server, using JWT validation.
            */
            return http
                    .authorizeHttpRequests((authorize) -> authorize
                        .requestMatchers("/api/public").permitAll()
                        .requestMatchers("/api/private").authenticated()
                        .requestMatchers("/api/private-scoped").hasAuthority("SCOPE_read:messages")
                    )
                    .cors(withDefaults())
                    .oauth2ResourceServer(oauth2 -> oauth2
                        .jwt(withDefaults())
                    )
                    .build();
        }
            }
        ```

        ```yml application.yml lines highlight={} theme={null}
        okta:
          oauth2:
            # Replace with the domain of your Auth0 tenant.
            issuer: https://{yourDomain}/
            # Replace with the API Identifier for your Auth0 API.
            audience: {yourApiIdentifier}
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>
  </SideMenu>
</Recipe>


# Add Authorization to Your Laravel Application
Source: https://auth0.com/docs/quickstart/backend/laravel/interactive

This guide demonstrates how to integrate Auth0 with a new (or existing) Laravel 9 or 10 application.

<QuickstartButtons />

<Recipe>
  <Content>
    [Auth0's Laravel SDK](https://github.com/auth0/laravel-auth0)
    allows you to quickly add token-based authorization and route access control to your Laravel application. This guide
    demonstrates how to integrate Auth0 with a new (or existing) [Laravel 9
    or 10](https://github.com/auth0/laravel-auth0#support-policy) application.

    **Backend applications differ from traditional web applications in that they do not handle user authentication or
    have a user interface. They provide an API that other applications can interact with. They accept **[access tokens](https://auth0.com/docs/secure/tokens/access-tokens)** from
    **`Authorization`** headers in requests to control access to routes.**

    Separate front-end applications are usually built to interact with these types of backends. These can be anything
    from [single-page applications](https://auth0.com/docs/quickstart/spa) or [native or mobile apps](https://auth0.com/docs/quickstart/native) (all of which Auth0 also
    provides SDKs for!)

    When users need to interact with your backend application, they first authenticate with Auth0 using the frontend
    application. The frontend application then retrieves an access token from Auth0, which it can use to make requests
    to your backend application on behalf of the user.

    As their name implies, [access
    tokens](https://auth0.com/docs/secure/tokens/access-tokens) are designed to address matters of access control (authorization), and do not contain information about
    the user. **Backend applications work exclusively with access tokens.** You can retrieve information about the
    user who created the token using the [Management
    API](https://auth0.com/docs/api/management/v2), which we will demonstrate later.

    <Section title={sections[0].title}>
      **If you do not already have a Laravel application set up**, open a shell to a suitable directory for a new
      project and run the following command:

      ```bash lines wrap theme={null}
      composer create-project --prefer-dist laravel/laravel auth0-laravel-api ^9.0
      ```

      All the commands in this guide assume you are running them from the root of your Laravel project, directory so
      you should `cd` into the new project directory:

      ```bash lines theme={null}
      cd auth0-laravel-api
      ```
    </Section>

    <Section title={sections[1].title}>
      Run the following command within your project directory to install the [Auth0 Laravel SDK](https://github.com/auth0/laravel-auth0):

      ```bash lines theme={null}
      composer require auth0/login:^7.8 --update-with-all-dependencies
      ```

      Then generate an SDK configuration file for your application:

      ```bash lines theme={null}
      php artisan vendor:publish --tag auth0
      ```
    </Section>

    <Section title={sections[2].title}>
      Run the following command from your project directory to download the [Auth0 CLI](https://github.com/auth0/auth0-cli):

      ```bash lines wrap theme={null}
      curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh | sh -s -- -b .
      ```

      Then authenticate the CLI with your Auth0 account, choosing "as a user" when prompted:

      ```bash lines theme={null}
      ./auth0 login
      ```

      Next, create a new application with Auth0:

      ```bash lines theme={null}
      ./auth0 apps create \
        --name "My Laravel Backend" \
        --type "regular" \
        --auth-method "post" \
        --callbacks "http://localhost:8000/callback" \
        --logout-urls "http://localhost:8000" \
        --reveal-secrets \
        --no-input \
        --json > .auth0.app.json
      ```

      You should also create a new API:

      ```bash lines theme={null}
      ./auth0 apis create \
        --name "My Laravel Backend API" \
        --identifier "https://github.com/auth0/laravel-auth0" \
        --offline-access \
        --no-input \
        --json > .auth0.api.json
      ```

      This produces two files in your project directory that configure the SDK.

      As these files contain credentials it's important to treat these as sensitive. You should ensure you do not
      commit these to version control. If you're using Git, you should add them to your `.gitignore` file:

      ```bash lines theme={null}
      echo ".auth0.*.json" >> .gitignore
      ```
    </Section>

    <Section title={sections[3].title}>
      The SDK automatically registers its authorization guard with your Laravel application for use with the
      `api` middleware, which by default Laravel applies to all routes in your application's
      `routes/api.php` file.

      <Warning>
        For the SDK to work as expected without additional configuration, **you should define your routes in
        the **`routes/api.php`** file.**
      </Warning>

      You can use the Auth0 SDK's authorization guard to restrict access to your application's routes.

      To reject requests that do not contain a valid access token in the `Authorization` header, you can use
      Laravel's `auth` middleware:

      ```php lines theme={null}
      Route::get('/private', function () {
      return response()->json([
      'message' => 'Your token is valid; you are authorized.',
      ]);
      })->middleware('auth');
      ```

      You can also require the provided token to have specific [permissions](https://auth0.com/docs/manage-users/access-control/rbac) by combining this
      with Laravel's `can` middleware:

      ```php lines theme={null}
      Route::get('/scope', function () {
      return response()->json([
      'message' => 'Your token is valid and has the read:messages permission; you are authorized.',
      ]);
      })->middleware('auth')->can('read:messages');
      ```
    </Section>

    <Section title={sections[4].title}>
      Information about the provided access token is available through Laravel's `Auth` Facade, or the
      `auth()` helper function.

      For example, to retrieve the user's identifier and email address:

      ```php lines theme={null}
      Route::get('/', function () {
      if (! auth()->check()) {
      return response()->json([
      'message' => 'You did not provide a valid token.',
      ]);
      }
      return response()->json([
      'message' => 'Your token is valid; you are authorized.',
      'id' => auth()->id(),
      'token' => auth()?->user()?->getAttributes(),
      ]);
      });
      ```
    </Section>

    <Section title={sections[5].title}>
      You can retrieve information about the user who created the access token from Auth0 using the [Auth0 Management API](https://github.com/auth0/laravel-auth0/blob/main/docs/Management.md). The SDK provides a convenient wrapper for this API,
      accessible through the SDK's `management()` method.

      **Before making Management API calls you must enable your application to communicate with the Management
      API.** This can be done from the [Auth0 Dashboard's API page](https://manage.auth0.com/#/apis/), choosing `Auth0 Management API`, and
      selecting the 'Machine to Machine Applications' tab. Authorize your Laravel application, and then click the down
      arrow to choose the scopes you wish to grant.

      For the following example, you should grant the `read:users` scope. A list of API endpoints and the
      required scopes can be found in [the Management
      API documentation](https://auth0.com/docs/api/management/v2).

      ```php lines theme={null}
      use Auth0\Laravel\Facade\Auth0;
      Route::get('/me', function () {
      $user = auth()->id();
      $profile = cache()->get($user);
      if (null === $profile) {
      $endpoint = Auth0::management()->users();
      $profile = $endpoint->get($user);
      $profile = Auth0::json($profile);
      cache()->put($user, $profile, 120);
      }
      $name = $profile['name'] ?? 'Unknown';
      $email = $profile['email'] ?? 'Unknown';
      return response()->json([
      'name' => $name,
      'email' => $email,
      ]);
      })->middleware('auth');
      ```

      <Info>
        **You should cache user information in your application for brief periods.** This reduces the number
        of requests your application makes to Auth0, and improves performance. You should avoid storing user
        information in your application for long periods as this can lead to stale data. You should also avoid
        storing user information beyond the user's identifier in persistent databases.
      </Info>
    </Section>

    <Section title={sections[6].title}>
      You are now ready to start your Laravel application, so it can accept requests:

      ```bash lines theme={null}
      php artisan serve
      ```
    </Section>

    <Section title={sections[7].title}>
      You can learn more about [retrieving access tokens here](https://auth0.com/docs/secure/tokens/access-tokens/get-access-tokens). For this quickstart, however, you can simply use an access
      token from [your API settings'
      "test" view](https://manage.auth0.com/#/apis).

      <Info>
        The `/me` route we created above will not work with a test token as there is no actual user
        associated with it.
      </Info>

      <Note>
        ##### Checkpoint

        Open a shell and try issuing requests to your application.

        Begin by requesting the public route:

        `curl --request GET \ --url http://localhost:8000/api \ --header 'Accept: application/json'`

        Next, use your access token in an `Authorization` header to request a protected route:

        `curl --request GET \ --url http://localhost:8000/api/private \ --header 'Accept: application/json' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'`

        Finally, try requesting the scope-protected route, which will only succeed if the access token has the
        `read:messages` scope granted:

        `curl --request GET \ --url http://localhost:8000/api/scope \ --header 'Accept: application/json' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'`
      </Note>

      ### Additional Reading

      * [User Repositories and Models](https://github.com/auth0/laravel-auth0/blob/main/docs/Users.md) extends the Auth0 Laravel SDK to use custom user
        models, and how to store and retrieve users from a database.
      * [Hooking Events](https://github.com/auth0/laravel-auth0/blob/main/docs/Events.md) covers how to listen for events raised by the Auth0 Laravel
        SDK, to fully customize the behavior of your integration.
      * [Management API](https://github.com/auth0/laravel-auth0/blob/main/docs/Management.md) support is built into the Auth0 Laravel SDK, allowing you to
        interact with the Management API from your Laravel application.
    </Section>

    ## Next Steps

    Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.

    This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:

    * [Auth0 Dashboard](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq) - Learn how to configure and manage your Auth0 tenant and applications
    * [laravel-auth0 SDK](https://github.com/auth0/laravel-auth0) - Explore the SDK used in this tutorial more fully
    * [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
  </Content>

  <SideMenu>
    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      ```php routes/api.php lines highlight={6-16} theme={null}
      <?php

      use Auth0\Laravel\Facade\Auth0;
      use Illuminate\Support\Facades\Route;

      Route::get('/private', function () {
        return response()->json([
          'message' => 'Your token is valid; you are authorized.',
        ]);
      })->middleware('auth');

      Route::get('/scope', function () {
          return response()->json([
            'message' => 'Your token is valid and has the `read:messages` permission; you are authorized.',
          ]);
      })->middleware('auth')->can('read:messages');

      Route::get('/', function () {
        if (! auth()->check()) {
          return response()->json([
            'message' => 'You did not provide a valid token.',
          ]);
        }

        return response()->json([
          'message' => 'Your token is valid; you are authorized.',
          'id' => auth()->id(),
          'token' => auth()?->user()?->getAttributes(),
        ]);
      });

      Route::get('/me', function () {
        $user = auth()->id();
        $profile = cache()->get($user);

        if (null === $profile) {
          $endpoint = Auth0::management()->users();
          $profile = $endpoint->get($user);
          $profile = Auth0::json($profile);

          cache()->put($user, $profile, 120);
        }

        $name = $profile['name'] ?? 'Unknown';
        $email = $profile['email'] ?? 'Unknown';

        return response()->json([
          'name' => $name,
          'email' => $email,
        ]);
      })->middleware('auth');
      ```
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      ```php routes/api.php lines highlight={18-30} theme={null}
      <?php

      use Auth0\Laravel\Facade\Auth0;
      use Illuminate\Support\Facades\Route;

      Route::get('/private', function () {
        return response()->json([
          'message' => 'Your token is valid; you are authorized.',
        ]);
      })->middleware('auth');

      Route::get('/scope', function () {
          return response()->json([
            'message' => 'Your token is valid and has the `read:messages` permission; you are authorized.',
          ]);
      })->middleware('auth')->can('read:messages');

      Route::get('/', function () {
        if (! auth()->check()) {
          return response()->json([
            'message' => 'You did not provide a valid token.',
          ]);
        }

        return response()->json([
          'message' => 'Your token is valid; you are authorized.',
          'id' => auth()->id(),
          'token' => auth()?->user()?->getAttributes(),
        ]);
      });

      Route::get('/me', function () {
        $user = auth()->id();
        $profile = cache()->get($user);

        if (null === $profile) {
          $endpoint = Auth0::management()->users();
          $profile = $endpoint->get($user);
          $profile = Auth0::json($profile);

          cache()->put($user, $profile, 120);
        }

        $name = $profile['name'] ?? 'Unknown';
        $email = $profile['email'] ?? 'Unknown';

        return response()->json([
          'name' => $name,
          'email' => $email,
        ]);
      })->middleware('auth');
      ```
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      ```php routes/api.php lines highlight={32-51} theme={null}
      <?php

      use Auth0\Laravel\Facade\Auth0;
      use Illuminate\Support\Facades\Route;

      Route::get('/private', function () {
        return response()->json([
          'message' => 'Your token is valid; you are authorized.',
        ]);
      })->middleware('auth');

      Route::get('/scope', function () {
          return response()->json([
            'message' => 'Your token is valid and has the `read:messages` permission; you are authorized.',
          ]);
      })->middleware('auth')->can('read:messages');

      Route::get('/', function () {
        if (! auth()->check()) {
          return response()->json([
            'message' => 'You did not provide a valid token.',
          ]);
        }

        return response()->json([
          'message' => 'Your token is valid; you are authorized.',
          'id' => auth()->id(),
          'token' => auth()?->user()?->getAttributes(),
        ]);
      });

      Route::get('/me', function () {
        $user = auth()->id();
        $profile = cache()->get($user);

        if (null === $profile) {
          $endpoint = Auth0::management()->users();
          $profile = $endpoint->get($user);
          $profile = Auth0::json($profile);

          cache()->put($user, $profile, 120);
        }

        $name = $profile['name'] ?? 'Unknown';
        $email = $profile['email'] ?? 'Unknown';

        return response()->json([
          'name' => $name,
          'email' => $email,
        ]);
      })->middleware('auth');
      ```
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>
  </SideMenu>
</Recipe>


# Secure Your Node.js API with Auth0
Source: https://auth0.com/docs/quickstart/backend/nodejs/interactive

Protect your Express.js API with JWT authentication using Auth0. Validate access tokens and implement scope-based authorization.

# Protect Your Express.js API with JWT Authentication

This guide demonstrates how to add JWT authentication to your Express.js API using the `express-oauth2-jwt-bearer` SDK. You'll validate access tokens issued by Auth0, protect API routes, and implement scope-based authorization.

> **Prerequisites**: Before you begin, ensure you have:
>
> * [Node.js](https://nodejs.org/) 18 LTS or newer (supports `^18.12.0 || ^20.2.0 || ^22.1.0 || ^24.0.0`)
> * [npm](https://npmjs.com/) 8+ (or yarn/pnpm)
> * An [Auth0 account](https://auth0.com/signup) (free tier available)
> * Basic familiarity with Express.js

***

## Get Started

### 1. Create a new Express project

Create a new directory and initialize a Node.js project:

```bash theme={null}
mkdir my-secure-api && cd my-secure-api
```

```bash theme={null}
npm init -y
```

### 2. Install dependencies

Install Express, the authentication SDK, and dotenv for environment variable management:

```bash theme={null}
npm install express express-oauth2-jwt-bearer dotenv
```

For TypeScript projects, also install type definitions:

```bash theme={null}
npm install -D typescript @types/express @types/node
```

### 3. Configure your Auth0 API

You need an Auth0 API to issue access tokens for your Express application. Configure Auth0 using the CLI or manually via the Dashboard:

<Tabs>
  <Tab label="Auth0 CLI">
    If you have the [Auth0 CLI](https://github.com/auth0/auth0-cli) installed, run:

    ```bash theme={null}
    auth0 apis create \
      --name "My Express API" \
      --identifier "https://api.example.com" \
      --signing-alg "RS256"
    ```

    After creation, note the **Identifier** value—this is your `AUTH0_AUDIENCE`.
  </Tab>

  <Tab label="Dashboard">
    1. Go to the [Auth0 Dashboard](https://manage.auth0.com/)
    2. Navigate to **Applications** → **APIs** in the sidebar
    3. Click **+ Create API**
    4. Fill in the following:
       * **Name**: My Express API (or your preferred name)
       * **Identifier**: `https://api.example.com` (this becomes your `AUTH0_AUDIENCE`)
       * **Signing Algorithm**: RS256 (recommended)
    5. Click **Create**
    6. Copy the **Identifier** value for use in your application
  </Tab>
</Tabs>

### 4. Create environment configuration

Create a `.env` file in your project root with your Auth0 configuration:

```bash theme={null}
# .env

# Your Auth0 tenant domain (without https:// prefix shown in Dashboard)
AUTH0_AUDIENCE=https://api.example.com
AUTH0_DOMAIN=your-tenant.us.auth0.com

# Server configuration
PORT=3000
```

> ℹ️ **Finding your Auth0 Domain**: In the Auth0 Dashboard, your domain appears in the top-left corner or under **Settings** → **General**. It typically looks like `dev-abc123.us.auth0.com`.

| Variable         | Description                    | Example                   |
| ---------------- | ------------------------------ | ------------------------- |
| `AUTH0_DOMAIN`   | Your Auth0 tenant domain       | `dev-abc123.us.auth0.com` |
| `AUTH0_AUDIENCE` | The API Identifier you created | `https://api.example.com` |

### 5. Create the server

Create `server.js` (or `server.ts` for TypeScript) with the following code:

```javascript theme={null}
// server.js
require('dotenv').config();
const express = require('express');
const { auth } = require('express-oauth2-jwt-bearer');

const app = express();
const port = process.env.PORT || 3000;

// Configure JWT validation middleware
const checkJwt = auth({
  issuerBaseURL: `https://${process.env.AUTH0_DOMAIN}`,
  audience: process.env.AUTH0_AUDIENCE,
});

// Public route - no authentication required
app.get('/api/public', (req, res) => {
  res.json({
    message: 'Hello from a public endpoint! No authentication required.',
  });
});

// Protected route - requires valid JWT
app.get('/api/private', checkJwt, (req, res) => {
  res.json({
    message: 'Hello from a private endpoint!',
    user: req.auth.payload.sub,
  });
});

// Error handling middleware
app.use((err, req, res, next) => {
  console.error(err.stack);
  
  const status = err.status || 500;
  const message = err.message || 'Internal Server Error';
  
  res.status(status).json({
    error: err.code || 'server_error',
    message: status === 401 ? 'Authentication required' : message,
  });
});

app.listen(port, () => {
  console.log(`API server running on http://localhost:${port}`);
});
```

<details>
  <summary>TypeScript Version</summary>

  Create `server.ts`:

  ```typescript theme={null}
  // server.ts
  import 'dotenv/config';
  import express, { Request, Response, NextFunction } from 'express';
  import { auth, UnauthorizedError } from 'express-oauth2-jwt-bearer';

  const app = express();
  const port = process.env.PORT || 3000;

  // Configure JWT validation middleware
  const checkJwt = auth({
    issuerBaseURL: `https://${process.env.AUTH0_DOMAIN}`,
    audience: process.env.AUTH0_AUDIENCE,
  });

  // Public route - no authentication required
  app.get('/api/public', (req: Request, res: Response) => {
    res.json({
      message: 'Hello from a public endpoint! No authentication required.',
    });
  });

  // Protected route - requires valid JWT
  app.get('/api/private', checkJwt, (req: Request, res: Response) => {
    res.json({
      message: 'Hello from a private endpoint!',
      user: req.auth?.payload.sub,
    });
  });

  // Error handling middleware
  app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
    console.error(err.stack);
    
    if (err instanceof UnauthorizedError) {
      res.status(err.status).set(err.headers).json({
        error: err.code || 'unauthorized',
        message: 'Authentication required',
      });
    } else {
      res.status(500).json({
        error: 'server_error',
        message: 'Internal Server Error',
      });
    }
  });

  app.listen(port, () => {
    console.log(`API server running on http://localhost:${port}`);
  });
  ```

  Add a `tsconfig.json`:

  ```json theme={null}
  {
    "compilerOptions": {
      "target": "ES2020",
      "module": "commonjs",
      "strict": true,
      "esModuleInterop": true,
      "skipLibCheck": true,
      "outDir": "./dist"
    },
    "include": ["*.ts"]
  }
  ```
</details>

### 6. Run your API

Start the server:

```bash theme={null}
node server.js
```

For TypeScript:

```bash theme={null}
npx ts-node server.ts
```

> ℹ️ Your API is now running at [http://localhost:3000](http://localhost:3000).

> ✅ **Checkpoint**: Verify your API is protecting routes correctly:
>
> **Test the public endpoint** (should return 200):
>
> ```bash theme={null}
> curl http://localhost:3000/api/public
> ```
>
> **Test the private endpoint without a token** (should return 401):
>
> ```bash theme={null}
> curl http://localhost:3000/api/private
> ```
>
> You should receive:
>
> * Public endpoint: `{"message":"Hello from a public endpoint!..."}`
> * Private endpoint: `{"error":"unauthorized","message":"Authentication required"}`

### 7. Test with a valid token

To test the protected endpoint with a valid access token:

1. Go to [Auth0 Dashboard](https://manage.auth0.com/) → **Applications** → **APIs**
2. Select your API → **Test** tab
3. Copy the generated access token

Test your protected endpoint:

```bash theme={null}
curl http://localhost:3000/api/private \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

You should receive a response like:

```json theme={null}
{
  "message": "Hello from a private endpoint!",
  "user": "auth0|abc123..."
}
```

> ✅ **Success!** Your Express API is now protected with JWT authentication.

***

## Add Scope-Based Authorization

Scopes allow fine-grained access control. You can require specific scopes for different endpoints.

### 1. Configure scopes in Auth0

1. In the Auth0 Dashboard, go to **Applications** → **APIs** → Your API
2. Navigate to the **Permissions** tab
3. Add the following scopes:
   * `read:messages` - Read messages
   * `write:messages` - Write messages
   * `admin:access` - Administrative access

### 2. Protect routes with scopes

Update your server to use scope-based authorization:

```javascript theme={null}
const { auth, requiredScopes } = require('express-oauth2-jwt-bearer');

// ... existing setup ...

// Requires 'read:messages' scope
app.get('/api/messages', checkJwt, requiredScopes('read:messages'), (req, res) => {
  res.json({
    messages: [
      { id: 1, text: 'Hello!' },
      { id: 2, text: 'World!' },
    ],
  });
});

// Requires 'admin:access' scope
app.get('/api/admin', checkJwt, requiredScopes('admin:access'), (req, res) => {
  res.json({
    message: 'Admin access granted',
    userId: req.auth.payload.sub,
  });
});
```

### 3. Request tokens with scopes

When obtaining tokens, include the required scopes in the authorization request. The scopes granted will be included in the token's `scope` claim.

> ⚠️ **Important**: If a request lacks the required scope, the API returns `403 Forbidden` with an `insufficient_scope` error.

***

## Add Claim Validation

Beyond scopes, you can validate custom claims in the JWT payload.

### Validate specific claim values

```javascript theme={null}
const { auth, claimEquals, claimIncludes, claimCheck } = require('express-oauth2-jwt-bearer');

// Require exact claim value
app.get('/api/org/:orgId', 
  checkJwt, 
  claimEquals('org_id', 'org_123'),
  (req, res) => {
    res.json({ message: 'Organization access granted' });
  }
);

// Require claim to include all specified values
app.get('/api/roles', 
  checkJwt, 
  claimIncludes('roles', 'editor', 'viewer'),
  (req, res) => {
    res.json({ message: 'Role check passed' });
  }
);

// Custom claim validation logic
app.get('/api/premium', 
  checkJwt, 
  claimCheck((claims) => {
    return claims.subscription === 'premium' && claims.verified === true;
  }),
  (req, res) => {
    res.json({ message: 'Premium feature access granted' });
  }
);
```

***

## Troubleshooting

<details>
  <summary>Error: "Unexpected 'iss' value" or "Unexpected 'aud' value"</summary>

  **Cause**: The issuer or audience in the token doesn't match your configuration.

  **Solution**:

  1. Decode your token at [jwt.io](https://jwt.io)
  2. Check the `iss` claim matches `https://YOUR_AUTH0_DOMAIN/` (note the trailing slash)
  3. Check the `aud` claim matches your `AUTH0_AUDIENCE` exactly

  ```bash theme={null}
  # Correct .env configuration
  AUTH0_DOMAIN=dev-abc123.us.auth0.com
  AUTH0_AUDIENCE=https://api.example.com
  ```
</details>

<details>
  <summary>Error: "You must provide an 'issuerBaseURL'" or "'audience' is required"</summary>

  **Cause**: Environment variables are not being loaded.

  **Solution**:

  1. Ensure `.env` file exists in your project root
  2. Verify `dotenv` is installed: `npm install dotenv`
  3. Add `require('dotenv').config()` at the top of your server file
  4. Check variable names match exactly (case-sensitive)
</details>

<details>
  <summary>401 Unauthorized on all requests</summary>

  **Possible causes**:

  * Token is expired
  * Audience doesn't match
  * Issuer doesn't match
  * Token not properly formatted

  **Debug steps**:

  1. Decode your token at [jwt.io](https://jwt.io)
  2. Check the `exp` claim hasn't passed (token not expired)
  3. Verify `aud` claim matches your `AUTH0_AUDIENCE` exactly
  4. Verify `iss` claim is `https://{AUTH0_DOMAIN}/`
  5. Ensure Authorization header format is `Bearer YOUR_TOKEN` (with space)
</details>

<details>
  <summary>Error: "Failed to fetch authorization server metadata"</summary>

  **Cause**: The SDK cannot reach Auth0 to fetch OIDC configuration.

  **Solution**:

  1. Verify your `AUTH0_DOMAIN` is correct
  2. Check network connectivity to Auth0
  3. If behind a proxy, configure the HTTP agent:

  ```javascript theme={null}
  const { HttpsProxyAgent } = require('https-proxy-agent');

  const checkJwt = auth({
    issuerBaseURL: `https://${process.env.AUTH0_DOMAIN}`,
    audience: process.env.AUTH0_AUDIENCE,
    agent: new HttpsProxyAgent(process.env.HTTPS_PROXY),
  });
  ```
</details>

<details>
  <summary>403 Forbidden with "insufficient\_scope"</summary>

  **Cause**: The token doesn't have the required scopes.

  **Solution**:

  1. Verify the scopes are defined in your Auth0 API (Dashboard → APIs → Permissions)
  2. Request the scopes when obtaining the token
  3. Check the token's `scope` claim includes the required scopes
</details>

***

## Advanced Usage

<details>
  <summary>Optional Authentication (Mixed Public/Private Routes)</summary>

  Allow both authenticated and anonymous access to the same route:

  ```javascript theme={null}
  const optionalAuth = auth({
    issuerBaseURL: `https://${process.env.AUTH0_DOMAIN}`,
    audience: process.env.AUTH0_AUDIENCE,
    authRequired: false, // Don't reject anonymous requests
  });

  app.get('/api/feed', optionalAuth, (req, res) => {
    if (req.auth) {
      // Authenticated user - show personalized content
      res.json({ 
        message: `Welcome back, ${req.auth.payload.sub}!`,
        personalizedContent: true,
      });
    } else {
      // Anonymous user - show public content
      res.json({ 
        message: 'Welcome, guest!',
        personalizedContent: false,
      });
    }
  });
  ```
</details>

<details>
  <summary>Using Express Router for API Organization</summary>

  Organize routes with Express Router:

  ```javascript theme={null}
  const express = require('express');
  const { auth, requiredScopes } = require('express-oauth2-jwt-bearer');

  const app = express();
  const apiRouter = express.Router();

  const checkJwt = auth({
    issuerBaseURL: `https://${process.env.AUTH0_DOMAIN}`,
    audience: process.env.AUTH0_AUDIENCE,
  });

  // Apply auth to all API routes
  apiRouter.use(checkJwt);

  apiRouter.get('/users', (req, res) => {
    res.json({ users: [] });
  });

  apiRouter.get('/admin', requiredScopes('admin:access'), (req, res) => {
    res.json({ admin: 'data' });
  });

  // Mount router
  app.use('/api', apiRouter);
  ```
</details>

<details>
  <summary>CORS Configuration for SPAs</summary>

  Configure CORS when your API is called from a Single Page Application:

  ```javascript theme={null}
  const cors = require('cors');

  app.use(cors({
    origin: 'https://your-spa.example.com',
    allowedHeaders: ['Authorization', 'Content-Type'],
    exposedHeaders: ['WWW-Authenticate'], // Important for error handling
  }));

  app.use(checkJwt);
  ```

  Install cors: `npm install cors`
</details>

<details>
  <summary>Custom Error Responses</summary>

  Customize error responses for better client handling:

  ```javascript theme={null}
  const { UnauthorizedError, InvalidTokenError, InsufficientScopeError } = require('express-oauth2-jwt-bearer');

  app.use((err, req, res, next) => {
    if (err instanceof InsufficientScopeError) {
      return res.status(403).json({
        error: 'forbidden',
        message: 'You do not have permission to access this resource',
        required_scopes: err.requiredScopes,
      });
    }
    
    if (err instanceof InvalidTokenError) {
      return res.status(401).json({
        error: 'invalid_token',
        message: 'The provided token is invalid or expired',
      });
    }
    
    if (err instanceof UnauthorizedError) {
      return res.status(401).set(err.headers).json({
        error: 'unauthorized',
        message: 'Authentication required',
      });
    }
    
    next(err);
  });
  ```
</details>

<details>
  <summary>Production Security Best Practices</summary>

  For production deployments, add these security enhancements:

  ```javascript theme={null}
  const helmet = require('helmet');

  // Security headers
  app.use(helmet());

  // Trust proxy (when behind load balancer/reverse proxy)
  app.enable('trust proxy');

  // Configure auth with additional options
  const checkJwt = auth({
    issuerBaseURL: `https://${process.env.AUTH0_DOMAIN}`,
    audience: process.env.AUTH0_AUDIENCE,
    clockTolerance: 10, // Allow 10 seconds clock skew
  });
  ```

  Install helmet: `npm install helmet`

  **Additional recommendations**:

  * Always use HTTPS in production
  * Set short token expiration times
  * Use DPoP for high-security APIs
  * Never log or expose complete tokens
  * Validate the `audience` claim (SDK does this by default)
</details>

<details>
  <summary>Working with Custom Claims in TypeScript</summary>

  Define types for custom claims in your tokens:

  ```typescript theme={null}
  import { JWTPayload } from 'express-oauth2-jwt-bearer';

  // Extend the payload type with your custom claims
  interface CustomPayload extends JWTPayload {
    permissions: string[];
    org_id: string;
    subscription: 'free' | 'premium';
  }

  app.get('/api/profile', checkJwt, (req, res) => {
    // Type assertion for custom claims
    const payload = req.auth?.payload as CustomPayload;
    
    res.json({
      userId: payload.sub,
      organization: payload.org_id,
      subscription: payload.subscription,
      permissions: payload.permissions,
    });
  });
  ```
</details>

***

## Complete Example

Here's a complete Express API with all features:

```javascript theme={null}
// server.js
require('dotenv').config();
const express = require('express');
const cors = require('cors');
const { 
  auth, 
  requiredScopes, 
  claimCheck,
  UnauthorizedError,
  InsufficientScopeError,
} = require('express-oauth2-jwt-bearer');

const app = express();
const port = process.env.PORT || 3000;

// Middleware
app.use(cors({
  origin: process.env.ALLOWED_ORIGIN || '*',
  exposedHeaders: ['WWW-Authenticate'],
}));
app.use(express.json());

// JWT validation middleware
const checkJwt = auth({
  issuerBaseURL: `https://${process.env.AUTH0_DOMAIN}`,
  audience: process.env.AUTH0_AUDIENCE,
});

// Public endpoints
app.get('/api/public', (req, res) => {
  res.json({ message: 'Public endpoint - no authentication required' });
});

app.get('/health', (req, res) => {
  res.json({ status: 'healthy' });
});

// Protected endpoints
app.get('/api/private', checkJwt, (req, res) => {
  res.json({
    message: 'Private endpoint',
    user: req.auth.payload.sub,
  });
});

// Scope-protected endpoint
app.get('/api/messages', checkJwt, requiredScopes('read:messages'), (req, res) => {
  res.json({
    messages: [
      { id: 1, text: 'Hello from the API!' },
    ],
  });
});

// Admin endpoint with scope and claim check
app.get('/api/admin', 
  checkJwt, 
  requiredScopes('admin:access'),
  claimCheck((claims) => claims.role === 'admin'),
  (req, res) => {
    res.json({
      message: 'Admin access granted',
      userId: req.auth.payload.sub,
    });
  }
);

// Error handling
app.use((err, req, res, next) => {
  console.error('Error:', err.message);
  
  if (err instanceof InsufficientScopeError) {
    return res.status(403).json({
      error: 'insufficient_scope',
      message: 'Missing required permissions',
    });
  }
  
  if (err instanceof UnauthorizedError) {
    return res.status(err.status).set(err.headers).json({
      error: err.code || 'unauthorized',
      message: 'Authentication required',
    });
  }
  
  res.status(500).json({
    error: 'server_error',
    message: 'An unexpected error occurred',
  });
});

app.listen(port, () => {
  console.log(`🚀 API server running at http://localhost:${port}`);
  console.log(`   - Public:  http://localhost:${port}/api/public`);
  console.log(`   - Private: http://localhost:${port}/api/private`);
});
```

***

## Next Steps

Now that your Express API is protected with JWT authentication, you can:

* **Add more protected routes** with different scope requirements
* **Implement refresh token rotation** for long-lived sessions
* **Add rate limiting** to protect against abuse
* **Connect a frontend application** that obtains tokens from Auth0
* **Enable DPoP** for enhanced token security (proof-of-possession)

### Useful Resources

* [express-oauth2-jwt-bearer README](https://github.com/auth0/node-oauth2-jwt-bearer/tree/main/packages/express-oauth2-jwt-bearer)
* [Auth0 API Documentation](https://auth0.com/docs/api)
* [JWT.io](https://jwt.io/) - Debug and decode JWTs
* [OAuth 2.0 RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) - Bearer Token Usage

***

> ✅ **Congratulations!** You've successfully protected your Express.js API with JWT authentication using Auth0 and express-oauth2-jwt-bearer.


# Add Authorization to Your PHP Application
Source: https://auth0.com/docs/quickstart/backend/php/interactive

This guide demonstrates how to integrate Auth0, add token-based authorization, and protect application routes using the Auth0 PHP SDK.

<QuickstartButtons />

<Recipe>
  <Content>
    Auth0 allows you to add token-based endpoint authorization to almost any application type quickly. This guide
    demonstrates how to integrate Auth0, add token-based authorization, and protect application routes using the Auth0
    PHP SDK.

    To use this quickstart, you’ll need to:

    <Section title={sections[0].title}>
      To use Auth0 services, you need to have an application registered in the Auth0 Dashboard. The Auth0 application
      is where you configure how you want authentication to work for your project.

      ### Configure an application

      Use the interactive selector to create a new Auth0 application or select an existing application that represents
      the project you want to integrate. Every application in Auth0 is assigned an alphanumeric, unique client ID that
      your application code uses to call Auth0 APIs through the SDK.

      Any settings you configure using this quickstart automatically updates for your application in the [Dashboard](https://manage.auth0.com/#/), which is where you
      can manage your applications in the future.

      If you would rather explore a complete configuration, you can view a sample application instead.

      ### Configure an API

      Similarly, you need to create a new Auth0 API or use an existing API that represents the project you're
      integrating from the [Dashboard](https://manage.auth0.com/#/). Choose a unique identifier for the API and make a note of it. You need
      that identifier to configure your application below.
    </Section>

    <Section title={sections[1].title}>
      Auth0 provides a [PHP
      SDK](https://github.com/auth0/auth0-PHP) (Auth0-PHP) to simplify the process of implementing Auth0 authentication and authorization in PHP apps.

      The Auth0 PHP SDK requires [PSR-17](https://www.php-fig.org/psr/psr-17/) and [PSR-18](https://www.php-fig.org/psr/psr-18/) installed, compatible HTTP libraries for managing network requests. If you
      don't have libraries available, you can install reliable choices by running the following commands in your
      terminal:

      ```bash lines theme={null}
      cd <your-project-directory>
      composer require symfony/http-client nyholm/psr7
      ```

      Now, install the Auth0 PHP SDK by running the following command in your terminal:

      ```bash lines theme={null}
      composer require auth0/auth0-php
      ```

      ### Configure the Auth0 SDK

      For the SDK to function properly, you must set the following properties in the Auth0 SDK during initialization:

      * `strategy`: The strategy helps guide the behavior of the SDK for the use case of your app. In this
        case, you want to set this to the constant

        `Auth0\SDK\Configuration\SdkConfiguration::STRATEGY_API`
      * domain: The domain of your Auth0 tenant. Generally, you find this in the Auth0 Dashboard under Application's
        Settings in the Domain field. If you are using a custom domain, set this to the value of your custom domain
        instead.
      * clientId: The ID of the Auth0 Application you set up earlier in this quickstart. You can find this in the
        Auth0 Dashboard under your Application's Settings in the Client ID field.
      * clientSecret: The secret of the Auth0 application you created earlier in this quickstart. Client secret is in
        the Auth0 Dashboard under your Application's Settings in the Client Secret field.
      * audience: The identifier of the Auth0 API you registered above. This must be provided as an array.

      <Note>
        ##### Checkpoint

        Your Auth0 SDK is now properly configured. Run your application to verify that:

        * The SDK is initializing correctly.
        * Your application is not throwing any errors related to Auth0.
      </Note>
    </Section>

    <Section title={sections[2].title}>
      Next, expand your application to retrieve and process bearer tokens. Bearer tokens are access tokens provided to
      your API with requests from clients on a users' behalf. Access tokens approve or deny access to routes in your
      application. This is referred to as endpoint authorization.

      The easiest way to retrieve access tokens from a request is using the PHP SDK's `getBearerToken()`
      method. This method fetches tokens from GET parameters, POST bodies, request headers, and other sources. In this
      case, the PHP SDK processes tokens passed from GET requests in the `token` parameter or from the HTTP
      `Authorization` header.
    </Section>

    <Section title={sections[3].title}>
      Now, install a routing library to help direct incoming requests to your application. This isn't a required step,
      but simplifies the application structure for the purposes of this quickstart.

      ```bash lines theme={null}
      composer require steampixel/simple-php-router
      ```

      Create a new file in your application called `router.php` to define the routes. Copy in the code from
      the interactive panel to the right under the **router.php** tab.
    </Section>

    <Section title={sections[4].title}>
      Now that you have configured your Auth0 application, the Auth0 PHP SDK, and you application retrieves bearer
      tokens from requests, the next step is to set up endpoint authorization for your project. The
      `getBearerToken()` method you implemented above returns a `Token` class that includes
      details on the request's access.

      Since the `getBearerToken()` method automatically validates and verifies the incoming request, your
      application determines the details of the access token by evaluating the method's response. When the response is
      null, no valid token has been provided. Otherwise, inspect the contents of the response to learn more about the
      request.

      In the interactive panel to the right, you can see a check if the response is null or not to filter access to
      your `/api/private` route.
    </Section>

    <Section title={sections[5].title}>
      In some cases, you may want to filter access to a specific route based on the requested scopes in an access
      token. As shown in the interactive panel on the right, evaluate the contents of the 'scope' property from the
      `getBearerToken()` method's response to check the scopes granted by the access token.
    </Section>

    ## Next Steps

    Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.

    This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:

    * [Auth0 Dashboard](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq) - Learn how to configure and manage your Auth0 tenant and applications
    * [Auth0-PHP SDK](https://github.com/auth0/auth0-php) - Explore the SDK used in this tutorial more fully
    * [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
  </Content>

  <SideMenu>
    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```php index.php lines highlight={} theme={null}
        <?php

              declare(strict_types=1);

              require('vendor/autoload.php');

              use Auth0\SDK\Auth0;
              use Auth0\SDK\Configuration\SdkConfiguration;

              $configuration = new SdkConfiguration(
        strategy: SdkConfiguration::STRATEGY_API,
        domain: '{yourDomain}',
        clientId: '{yourClientId}',
        clientSecret: '{yourClientSecret}',
        audience: ['{yourApiIdentifier}']
              );

              $sdk = new Auth0($configuration);

              $token = $sdk->getBearerToken(
        get: ['token'],
        server: ['Authorization']
              );

              require('router.php');
        ```

        ```php router.php lines highlight={} theme={null}
        <?php

              declare(strict_types=1);

              use Steampixel\Route;

              function routeResponse(
        array $response
              ) {
        header('Content-Type: application/json');
        print(json_encode($response, JSON_PRETTY_PRINT));
              }

              Route::add('/api/public', function() use ($token) {
        routeResponse([
          'message' => 'Hello from a public endpoint! You don\'t need to be authenticated to see this.',
          'token' => $token
        ]);
              });

              Route::add('/api/private', function() use ($token) {
        if ($token === null) {
          http_response_code(401);
          exit;
        }

        routeResponse([
          'message' => 'Hello from a private endpoint! You need to be authenticated to see this.',
          'token' => $token,
        ]);
              });

              Route::add('/api/private-scoped', function() use ($token) {
        if ($token === null) {
          http_response_code(401);
          exit;
        }

        if (! in_array('read:messages', $token['scopes'], true)) {
          http_response_code(401);
          exit;
        }

        routeResponse([
          'message' => 'Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this.',
          'token' => $token,
        ]);
              });

              // The following route is just to avoid confusion.
              // We're not using an 'index route' in this app, so redirect requests to /api/public.
              Route::add('/', function() {
        header('Location: /api/public');
              });

              Route::run();
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```php index.php lines highlight={20-23} theme={null}
        <?php

              declare(strict_types=1);

              require('vendor/autoload.php');

              use Auth0\SDK\Auth0;
              use Auth0\SDK\Configuration\SdkConfiguration;

              $configuration = new SdkConfiguration(
        strategy: SdkConfiguration::STRATEGY_API,
        domain: '{yourDomain}',
        clientId: '{yourClientId}',
        clientSecret: '{yourClientSecret}',
        audience: ['{yourApiIdentifier}']
              );

              $sdk = new Auth0($configuration);

              $token = $sdk->getBearerToken(
        get: ['token'],
        server: ['Authorization']
              );

              require('router.php');
        ```

        ```php router.php lines highlight={} theme={null}
        <?php

              declare(strict_types=1);

              use Steampixel\Route;

              function routeResponse(
        array $response
              ) {
        header('Content-Type: application/json');
        print(json_encode($response, JSON_PRETTY_PRINT));
              }

              Route::add('/api/public', function() use ($token) {
        routeResponse([
          'message' => 'Hello from a public endpoint! You don\'t need to be authenticated to see this.',
          'token' => $token
        ]);
              });

              Route::add('/api/private', function() use ($token) {
        if ($token === null) {
          http_response_code(401);
          exit;
        }

        routeResponse([
          'message' => 'Hello from a private endpoint! You need to be authenticated to see this.',
          'token' => $token,
        ]);
              });

              Route::add('/api/private-scoped', function() use ($token) {
        if ($token === null) {
          http_response_code(401);
          exit;
        }

        if (! in_array('read:messages', $token['scopes'], true)) {
          http_response_code(401);
          exit;
        }

        routeResponse([
          'message' => 'Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this.',
          'token' => $token,
        ]);
              });

              // The following route is just to avoid confusion.
              // We're not using an 'index route' in this app, so redirect requests to /api/public.
              Route::add('/', function() {
        header('Location: /api/public');
              });

              Route::run();
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```php router.php lines highlight={} theme={null}
        <?php

              declare(strict_types=1);

              use Steampixel\Route;

              function routeResponse(
        array $response
              ) {
        header('Content-Type: application/json');
        print(json_encode($response, JSON_PRETTY_PRINT));
              }

              Route::add('/api/public', function() use ($token) {
        routeResponse([
          'message' => 'Hello from a public endpoint! You don\'t need to be authenticated to see this.',
          'token' => $token
        ]);
              });

              Route::add('/api/private', function() use ($token) {
        if ($token === null) {
          http_response_code(401);
          exit;
        }

        routeResponse([
          'message' => 'Hello from a private endpoint! You need to be authenticated to see this.',
          'token' => $token,
        ]);
              });

              Route::add('/api/private-scoped', function() use ($token) {
        if ($token === null) {
          http_response_code(401);
          exit;
        }

        if (! in_array('read:messages', $token['scopes'], true)) {
          http_response_code(401);
          exit;
        }

        routeResponse([
          'message' => 'Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this.',
          'token' => $token,
        ]);
              });

              // The following route is just to avoid confusion.
              // We're not using an 'index route' in this app, so redirect requests to /api/public.
              Route::add('/', function() {
        header('Location: /api/public');
              });

              Route::run();
        ```

        ```php index.php lines highlight={} theme={null}
        <?php

              declare(strict_types=1);

              require('vendor/autoload.php');

              use Auth0\SDK\Auth0;
              use Auth0\SDK\Configuration\SdkConfiguration;

              $configuration = new SdkConfiguration(
        strategy: SdkConfiguration::STRATEGY_API,
        domain: '{yourDomain}',
        clientId: '{yourClientId}',
        clientSecret: '{yourClientSecret}',
        audience: ['{yourApiIdentifier}']
              );

              $sdk = new Auth0($configuration);

              $token = $sdk->getBearerToken(
        get: ['token'],
        server: ['Authorization']
              );

              require('router.php');
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```php router.php lines highlight={21-31} theme={null}
        <?php

              declare(strict_types=1);

              use Steampixel\Route;

              function routeResponse(
        array $response
              ) {
        header('Content-Type: application/json');
        print(json_encode($response, JSON_PRETTY_PRINT));
              }

              Route::add('/api/public', function() use ($token) {
        routeResponse([
          'message' => 'Hello from a public endpoint! You don\'t need to be authenticated to see this.',
          'token' => $token
        ]);
              });

              Route::add('/api/private', function() use ($token) {
        if ($token === null) {
          http_response_code(401);
          exit;
        }

        routeResponse([
          'message' => 'Hello from a private endpoint! You need to be authenticated to see this.',
          'token' => $token,
        ]);
              });

              Route::add('/api/private-scoped', function() use ($token) {
        if ($token === null) {
          http_response_code(401);
          exit;
        }

        if (! in_array('read:messages', $token['scopes'], true)) {
          http_response_code(401);
          exit;
        }

        routeResponse([
          'message' => 'Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this.',
          'token' => $token,
        ]);
              });

              // The following route is just to avoid confusion.
              // We're not using an 'index route' in this app, so redirect requests to /api/public.
              Route::add('/', function() {
        header('Location: /api/public');
              });

              Route::run();
        ```

        ```php index.php lines highlight={} theme={null}
        <?php

              declare(strict_types=1);

              require('vendor/autoload.php');

              use Auth0\SDK\Auth0;
              use Auth0\SDK\Configuration\SdkConfiguration;

              $configuration = new SdkConfiguration(
        strategy: SdkConfiguration::STRATEGY_API,
        domain: '{yourDomain}',
        clientId: '{yourClientId}',
        clientSecret: '{yourClientSecret}',
        audience: ['{yourApiIdentifier}']
              );

              $sdk = new Auth0($configuration);

              $token = $sdk->getBearerToken(
        get: ['token'],
        server: ['Authorization']
              );

              require('router.php');
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```php router.php lines highlight={33-48} theme={null}
        <?php

              declare(strict_types=1);

              use Steampixel\Route;

              function routeResponse(
        array $response
              ) {
        header('Content-Type: application/json');
        print(json_encode($response, JSON_PRETTY_PRINT));
              }

              Route::add('/api/public', function() use ($token) {
        routeResponse([
          'message' => 'Hello from a public endpoint! You don\'t need to be authenticated to see this.',
          'token' => $token
        ]);
              });

              Route::add('/api/private', function() use ($token) {
        if ($token === null) {
          http_response_code(401);
          exit;
        }

        routeResponse([
          'message' => 'Hello from a private endpoint! You need to be authenticated to see this.',
          'token' => $token,
        ]);
              });

              Route::add('/api/private-scoped', function() use ($token) {
        if ($token === null) {
          http_response_code(401);
          exit;
        }

        if (! in_array('read:messages', $token['scopes'], true)) {
          http_response_code(401);
          exit;
        }

        routeResponse([
          'message' => 'Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this.',
          'token' => $token,
        ]);
              });

              // The following route is just to avoid confusion.
              // We're not using an 'index route' in this app, so redirect requests to /api/public.
              Route::add('/', function() {
        header('Location: /api/public');
              });

              Route::run();
        ```

        ```php index.php lines highlight={} theme={null}
        <?php

              declare(strict_types=1);

              require('vendor/autoload.php');

              use Auth0\SDK\Auth0;
              use Auth0\SDK\Configuration\SdkConfiguration;

              $configuration = new SdkConfiguration(
        strategy: SdkConfiguration::STRATEGY_API,
        domain: '{yourDomain}',
        clientId: '{yourClientId}',
        clientSecret: '{yourClientSecret}',
        audience: ['{yourApiIdentifier}']
              );

              $sdk = new Auth0($configuration);

              $token = $sdk->getBearerToken(
        get: ['token'],
        server: ['Authorization']
              );

              require('router.php');
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>
  </SideMenu>
</Recipe>


# Flask API
Source: https://auth0.com/docs/quickstart/backend/python/index

This guide demonstrates how to integrate Auth0 with any new or existing Python API built with Flask.

<Note>
  **Prerequisites:** Before you begin, ensure you have the following installed:

  * **Python 3.9** or higher
  * **pip** or Poetry package manager
  * **[jq](https://jqlang.org/)** - Required for Auth0 CLI setup
  * Your preferred code editor

  **Flask Version Compatibility:** This quickstart requires **Flask 3.0** or higher for native async support.
</Note>

## Get Started

This guide demonstrates how to integrate Auth0 with any new or existing Python API built with [Flask](https://flask.palletsprojects.com/).

<Steps>
  <Step title="Create a new Flask project">
    Create a new directory for your Flask API:

    ```bash theme={null}
    mkdir flask-auth0-api
    cd flask-auth0-api
    ```

    Create a virtual environment and activate it:

    ```bash theme={null}
    python -m venv venv
    source venv/bin/activate  # On Windows: venv\Scripts\activate
    ```
  </Step>

  <Step title="Install dependencies">
    Create a `requirements.txt` file with the following dependencies:

    ```txt requirements.txt theme={null}
    flask>=3.0
    auth0-api-python
    python-dotenv
    ```

    Install the dependencies:

    ```bash theme={null}
    pip install -r requirements.txt
    ```
  </Step>

  <Step title="Setup your Auth0 API">
    Next up, you need to create a new API on your Auth0 tenant and configure your application.

    You can choose to do this automatically by running a CLI command or do it manually via the Dashboard:

    <Tabs>
      <Tab title="Dashboard">
        1. Go to the [Auth0 Dashboard](https://manage.auth0.com/) → **Applications** → **APIs**
        2. Click **Create API**
        3. Enter your API details:
           * **Name**: `My Flask API`
           * **Identifier**: `https://my-flask-api` (this will be your audience)
           * **Signing Algorithm**: **RS256**
        4. Click **Create**
        5. Copy your **Domain** from the Dashboard (found under **Applications** → **Applications** → **\[Your App]** → **Settings**)
        6. Copy the **Identifier** you just created (this is your audience)

        <Info>
          Your **Domain** should not include `https://` - use only the domain name (e.g., `your-tenant.auth0.com`).

          The **Audience** (API Identifier) is a unique identifier for your API and can be any valid URI.
        </Info>
      </Tab>

      <Tab title="CLI">
        Run the following shell command on your project's root directory to create an Auth0 API and generate a `.env` file:

        <CodeGroup>
          ```shellscript Mac theme={null}
          AUTH0_API_NAME="My Flask API" && AUTH0_API_IDENTIFIER="https://my-flask-api" && brew tap auth0/auth0-cli && brew install auth0 && auth0 login --no-input && auth0 apis create --name "${AUTH0_API_NAME}" --identifier "${AUTH0_API_IDENTIFIER}" --signing-alg RS256 --json > auth0-api-details.json && DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name') && AUDIENCE=$(jq -r '.identifier' auth0-api-details.json) && echo "AUTH0_DOMAIN=${DOMAIN}" > .env && echo "AUTH0_AUDIENCE=${AUDIENCE}" >> .env && rm auth0-api-details.json && echo ".env file created with your Auth0 API details:" && cat .env
          ```

          ```shellscript Windows theme={null}
          $ApiName = "My Flask API"; $ApiIdentifier = "https://my-flask-api"; winget install Auth0.CLI; auth0 login --no-input; auth0 apis create -n "$ApiName" -i "$ApiIdentifier" --signing-alg RS256 --json | Set-Content -Path auth0-api-details.json; $Domain = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name; $Audience = (Get-Content -Raw auth0-api-details.json | ConvertFrom-Json).identifier; Set-Content -Path .env -Value "AUTH0_DOMAIN=$Domain"; Add-Content -Path .env -Value "AUTH0_AUDIENCE=$Audience"; Remove-Item auth0-api-details.json; Write-Output ".env file created with your Auth0 API details:"; Get-Content .env
          ```
        </CodeGroup>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Define API permissions">
    Configure permissions (scopes) for your API to control access to specific resources:

    1. In the [Auth0 Dashboard](https://manage.auth0.com/), navigate to **Applications** → **APIs**
    2. Select your API (`My Flask API`)
    3. Go to the **Permissions** tab
    4. Click **Add Permission**
    5. Add the following permission:
       * **Permission (Scope)**: `read:messages`
       * **Description**: `Read messages`
    6. Click **Add**

    <Info>
      Permissions define what actions can be performed on your API. You can add multiple permissions like `write:messages`, `delete:messages`, etc. The `/api/private-scoped` endpoint in this quickstart requires the `read:messages` permission.
    </Info>
  </Step>

  <Step title="Configure the Auth0 client">
    <Note>
      If you used the **CLI** method in Step 3, your `.env` file was automatically created. Skip to creating the `app.py` file below.
    </Note>

    If you used the **Dashboard** method, create a `.env` file in your project root to store your Auth0 configuration:

    ```bash .env theme={null}
    AUTH0_DOMAIN=your-tenant.us.auth0.com
    AUTH0_AUDIENCE=https://my-flask-api
    ```

    <Warning>
      Replace `your-tenant.us.auth0.com` with your actual Auth0 domain and update the `API_IDENTIFIER` to match your API identifier from the dashboard.
    </Warning>

    Create an `app.py` file and configure the Auth0 API client:

    ```python app.py theme={null}
    import os
    import asyncio
    from flask import Flask, request, jsonify, g
    from functools import wraps
    from dotenv import load_dotenv
    from auth0_api_python import ApiClient, ApiClientOptions
    from auth0_api_python.errors import BaseAuthError

    # Load environment variables
    load_dotenv()

    app = Flask(__name__)

    # Initialize Auth0 API client (singleton - created once)
    api_client = ApiClient(ApiClientOptions(
        domain=os.getenv("AUTH0_DOMAIN"),
        audience=os.getenv("AUTH0_AUDIENCE")
    ))
    ```
  </Step>

  <Step title="Create protected routes">
    Add a decorator for protecting routes and create public and private endpoints:

    ```python app.py theme={null}
    # Authentication decorator
    def require_auth(f):
        @wraps(f)
        def decorated_function(*args, **kwargs):
            auth_header = request.headers.get("Authorization", "")
            
            if not auth_header.startswith("Bearer "):
                return jsonify({"error": "Missing or invalid authorization header"}), 401
            
            token = auth_header.split(" ")[1]
            
            try:
                claims = asyncio.run(api_client.verify_access_token(token))
                g.user_claims = claims
                return f(*args, **kwargs)
            except BaseAuthError as e:
                return (
                    jsonify({"error": str(e)}),
                    e.get_status_code(),
                    e.get_headers()
                )
        
        return decorated_function


    # Public endpoint - no authentication required
    @app.route("/api/public", methods=["GET"])
    def public():
        return jsonify({"message": "This endpoint is public"})


    # Protected endpoint - requires authentication
    @app.route("/api/private", methods=["GET"])
    @require_auth
    def private():
        return jsonify({
            "message": "This endpoint requires authentication",
            "user": g.user_claims.get("sub")
        })


    # Protected endpoint with permission validation
    @app.route("/api/private-scoped", methods=["GET"])
    @require_auth
    def private_scoped():
        scopes = g.user_claims.get("scope", "").split()
        
        if "read:messages" not in scopes:
            return jsonify({"error": "Insufficient permissions"}), 403
        
        return jsonify({
            "message": "Private scoped endpoint - read:messages permission granted",
            "user": g.user_claims.get("sub")
        })


    if __name__ == "__main__":
        app.run(debug=True, port=5000)
    ```
  </Step>

  <Step title="Run your API">
    Start your Flask application:

    ```bash theme={null}
    python app.py
    ```

    Your API is now running on `http://localhost:5000`.
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a fully functional Auth0-protected Flask API running on your localhost with three endpoints:

  * `/api/public` - Accessible without authentication
  * `/api/private` - Requires a valid Auth0 access token
  * `/api/private-scoped` - Requires authentication and the `read:messages` permission
</Check>

## Test Your API

To test your protected endpoints, you need an access token.

### Get a test token

1. Go to the [Auth0 Dashboard](https://manage.auth0.com/)
2. Navigate to **Applications → APIs**
3. Select your API
4. Go to the **Test** tab
5. Copy the access token

### Make a request

Test the public endpoint (no token required):

```bash theme={null}
curl http://localhost:5000/api/public
```

Test the protected endpoint (token required):

```bash theme={null}
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  http://localhost:5000/api/private
```

Replace `YOUR_ACCESS_TOKEN` with the token you copied from the Auth0 Dashboard.

## Advanced Usage

<Accordion title="Validating Custom Claims">
  Require specific claims to be present in the access token:

  ```python theme={null}
  try:
      claims = await api_client.verify_access_token(
          access_token=token,
          required_claims=["email_verified", "org_id"]
      )
  except BaseAuthError as e:
      return jsonify({"error": "Missing required claims"}), 401
  ```
</Accordion>

<Accordion title="DPoP Authentication">
  For enhanced security, enable DPoP (Demonstrating Proof-of-Possession). DPoP enhances OAuth 2.0 by binding access tokens to cryptographic keys.

  ```python theme={null}
  import asyncio


  # Configure API client with DPoP enabled (Allowed mode)
  api_client = ApiClient(ApiClientOptions(
      domain=os.getenv("AUTH0_DOMAIN"),
      audience=os.getenv("AUTH0_AUDIENCE"),
      dpop_enabled=True,   # Default - enables DPoP support
      dpop_required=False  # Default - allows both Bearer and DPoP tokens
  ))

  # For Required mode (DPoP-only, rejects Bearer tokens)
  # dpop_required=True

  # DPoP-aware decorator
  def require_auth_dpop(f):
      @wraps(f)
      def decorated_function(*args, **kwargs):
          headers = {
              "authorization": request.headers.get("Authorization", ""),
              "dpop": request.headers.get("DPoP", "")  # DPoP proof header
          }
          
          try:
              # verify_request() automatically detects Bearer or DPoP scheme
              claims = asyncio.run(api_client.verify_request(
                  headers=headers,
                  http_method=request.method,
                  http_url=request.url
              ))
              g.user_claims = claims
              return f(*args, **kwargs)
          except BaseAuthError as e:
              return jsonify({"error": str(e)}), e.get_status_code(), e.get_headers()
      
      return decorated_function

  @app.route("/api/dpop-protected")
  @require_auth_dpop
  def dpop_protected():
      return jsonify({
          "message": "Successfully authenticated with DPoP or Bearer",
          "user": g.user_claims.get("sub")
      })
  ```

  <Info>
    The `verify_request()` method automatically detects whether the request uses Bearer or DPoP authentication. When DPoP is used, it validates both the access token and the DPoP proof according to RFC 9449.
  </Info>
</Accordion>

<Accordion title="Scope-Based Authorization">
  Create a decorator to check for specific scopes:

  ```python theme={null}
  def require_scope(required_scope):
      def decorator(f):
          @wraps(f)
          async def wrapper(*args, **kwargs):
              if not hasattr(g, "user_claims"):
                  return jsonify({"error": "Unauthorized"}), 401
              
              scopes = g.user_claims.get("scope", "").split()
              
              if required_scope not in scopes:
                  return jsonify({"error": "Insufficient permissions"}), 403
              
              return await f(*args, **kwargs)
          return wrapper
      return decorator


  @app.route("/api/admin")
  @require_auth
  @require_scope("admin:write")
  async def admin_endpoint():
      return jsonify({"message": "Admin access granted"})
  ```
</Accordion>

<Accordion title="Error Handling Best Practices">
  Implement comprehensive error handling with specific error types:

  ```python theme={null}
  from auth0_api_python.errors import (
      BaseAuthError,
      VerifyAccessTokenError,
      GetTokenByExchangeProfileError,
      ApiError
  )

  @app.errorhandler(BaseAuthError)
  def handle_auth_error(error):
      """Handle all Auth0 authentication errors"""
      return jsonify({
          "error": error.get_error_code(),
          "error_description": str(error)
      }), error.get_status_code(), error.get_headers()


  @app.errorhandler(VerifyAccessTokenError)
  def handle_token_verification_error(error):
      """Handle token verification failures specifically"""
      app.logger.warning(f"Token verification failed: {str(error)}")
      return jsonify({
          "error": "invalid_token",
          "error_description": str(error)
      }), 401, error.get_headers()


  @app.errorhandler(ApiError)
  def handle_api_error(error):
      """Handle Auth0 API errors (network, rate limits, etc.)"""
      app.logger.error(f"Auth0 API error: {error.code} - {error.message}")
      return jsonify({
          "error": error.code,
          "error_description": error.message
      }), error.status_code or 500


  @app.errorhandler(Exception)
  def handle_generic_error(error):
      """Catch-all for unexpected errors"""
      app.logger.error(f"Unexpected error: {str(error)}", exc_info=True)
      return jsonify({"error": "Internal server error"}), 500
  ```

  <Info>
    All authentication errors extend from `BaseAuthError`, which provides methods like `get_status_code()`, `get_headers()`, and `get_error_code()` for proper HTTP responses with WWW-Authenticate headers.
  </Info>
</Accordion>

<Accordion title="Using Before-Request Middleware">
  For applications where most endpoints require authentication, use Flask's `before_request` to validate tokens globally:

  ```python theme={null}
  from flask import g

  PUBLIC_ROUTES = ["/api/public", "/health"]

  @app.before_request
  async def verify_token():
      # Skip auth for public routes
      if request.path in PUBLIC_ROUTES:
          return
      
      auth_header = request.headers.get("Authorization", "")
      
      if not auth_header.startswith("Bearer "):
          return jsonify({"error": "Missing authorization"}), 401
      
      token = auth_header.split(" ")[1]
      
      try:
          claims = await api_client.verify_access_token(token)
          g.user_claims = claims
      except BaseAuthError as e:
          return jsonify({"error": str(e)}), e.get_status_code(), e.get_headers()


  @app.route("/api/protected-data")
  async def protected_data():
      # Claims automatically available via g.user_claims
      return jsonify({"user_id": g.user_claims["sub"]})
  ```
</Accordion>

## Common Issues

<AccordionGroup>
  <Accordion title="401 Unauthorized - Invalid audience">
    **Symptom**: Getting 401 errors even with valid-looking tokens

    **Cause**: The audience in your token doesn't match the audience configured in your API client

    **Solution**:

    1. Verify the `AUTH0_AUDIENCE` in your `.env` file matches your Auth0 API Identifier exactly
    2. The audience is case-sensitive
    3. Ensure the audience is a URL or URN format (e.g., `https://my-api` not `my-api`)
  </Accordion>

  <Accordion title="401 Unauthorized - Invalid issuer">
    **Symptom**: Token validation fails with issuer mismatch

    **Cause**: The domain configuration doesn't match the token issuer

    **Solution**:

    1. Verify `AUTH0_DOMAIN` is correct (e.g., `tenant.us.auth0.com`)
    2. Don't include `https://` in the domain
    3. Don't include a trailing slash
  </Accordion>

  <Accordion title="Configuration values not found">
    **Symptom**: `None` values or environment variable errors

    **Cause**: Environment variables not loaded or `.env` file not found

    **Solution**:

    1. Ensure `.env` file exists in your project root
    2. Verify `load_dotenv()` is called before accessing `os.getenv()`
    3. Check that variable names match exactly (case-sensitive)
  </Accordion>

  <Accordion title="Flask async support errors">
    **Symptom**: `RuntimeError: This event loop is already running` or similar async errors

    **Cause**: Using async routes without Flask 3.0+ or mixing sync/async incorrectly

    **Solution**:

    1. Upgrade to Flask 3.0 or higher: `pip install --upgrade flask`
    2. Ensure all route handlers using `api_client` are declared as `async def`
    3. Don't use `asyncio.run()` within route handlers
  </Accordion>

  <Accordion title="Token expired errors">
    **Symptom**: `VerifyAccessTokenError: Token is expired`

    **Cause**: The access token has passed its expiration time

    **Solution**:

    1. Request a new token from the Auth0 Dashboard Test tab
    2. Implement token refresh in your client application
    3. Tokens from the Dashboard are typically valid for 24 hours
  </Accordion>

  <Accordion title="Missing Authorization header">
    **Symptom**: `Missing or invalid authorization header` error

    **Cause**: Request doesn't include the `Authorization` header or uses incorrect format

    **Solution**:

    1. Ensure the header is named `Authorization` (capital A)
    2. Use format: `Authorization: Bearer YOUR_TOKEN`
    3. Don't include quotes around the token
  </Accordion>
</AccordionGroup>

## Additional Resources

<CardGroup>
  <Card title="SDK Documentation" icon="github" href="https://github.com/auth0/auth0-api-python">
    Complete SDK documentation and API reference
  </Card>

  <Card title="Flask Documentation" icon="code" href="https://flask.palletsprojects.com/">
    Official Flask framework documentation
  </Card>

  <Card title="Auth0 Dashboard" icon="gauge" href="https://manage.auth0.com/">
    Manage your Auth0 tenant and APIs
  </Card>

  <Card title="API Authentication Guide" icon="shield" href="https://auth0.com/docs/secure/tokens/access-tokens">
    Learn about access tokens and API security
  </Card>

  <Card title="DPoP Documentation" icon="lock" href="https://auth0.com/docs/secure/sender-constraining/demonstrating-proof-of-possession-dpop">
    Learn about proof-of-possession security
  </Card>

  <Card title="Community Forum" icon="comments" href="https://community.auth0.com/">
    Get help from the Auth0 community
  </Card>
</CardGroup>

## Next Steps

Check out the [Auth0 Python API samples repository](https://github.com/auth0-samples/auth0-python-api-samples) for complete working examples with Flask.


# Add Authorization to Your Ruby on Rails API
Source: https://auth0.com/docs/quickstart/backend/rails/interactive

This tutorial performs access token validation using the jwt Gem within a custom Auth0Client class.

<QuickstartButtons />

<Recipe>
  <Content>
    This tutorial performs access token validation using the [jwt](https://github.com/jwt/ruby-jwt) Gem within a custom `Auth0Client` class. A Concern called
    `Secured` is used to authorize endpoints which require authentication through an incoming access token.

    If you have not created an API in your Auth0 dashboard yet, use the interactive selector to create a new Auth0 API
    or select an existing API for your project.

    To set up your first API through the Auth0 dashboard, review [our getting started
    guide](https://auth0.com/docs/get-started/auth0-overview/set-up-apis).

    Each Auth0 API uses the API Identifier, which your application needs to validate the access token.

    <Info>
      **New to Auth0?** Learn [how Auth0 works](https://auth0.com/docs/overview)
      and read about [implementing API authentication
      and authorization](https://auth0.com/docs/api-auth) using the OAuth 2.0 framework.
    </Info>

    <Section title={sections[0].title}>
      Permissions let you define how resources can be accessed on behalf of the user with a given access token. For
      example, you might choose to grant read access to the `messages` resource if users have the manager
      access level, and a write access to that resource if they have the administrator access level.

      You can define allowed permissions in the **Permissions** view of the Auth0 Dashboard's [APIs](https://manage.auth0.com/#/apis) section.

      <Frame>
        <img />
      </Frame>

      <Info>
        This example uses the `read:messages` scope.
      </Info>
    </Section>

    <Section title={sections[1].title}>
      Install the \*\*jwt \*\*Gem.

      ```bash lines theme={null}
      gem 'jwt'
      bundle install
      ```
    </Section>

    <Section title={sections[2].title}>
      Create a class called `Auth0Client`. This class decodes and verifies the incoming access token taken
      from the `Authorization` header of the request.

      The `Auth0Client` class retrieves the public key for your Auth0 tenant and then uses it to verify the
      signature of the access token. The `Token` struct defines a `validate_permissions` method to
      look for a particular `scope` in an access token by providing an array of required scopes and check if
      they are present in the payload of the token.
    </Section>

    <Section title={sections[3].title}>
      Create a Concern called `Secured` which looks for the access token in the `Authorization`
      header of an incoming request.

      If the token is present, the `Auth0Client.validate_token` will use the `jwt` Gem to verify
      the token's signature and validate the token's claims.

      In addition to verifying that the access token is valid, the Concern also includes a mechanism for confirming the
      token has the sufficient **scope** to access the requested resources. In this example we define a
      `validate_permissions` method that receives a block and checks the permissions by calling the
      `Token.validate_permissions` method from the `Auth0Client` class.

      For the `/private-scoped` route, the scopes defined will be intersected with the scopes coming in the
      payload, to determine if it contains one or more items from the other array.
    </Section>

    <Section title={sections[4].title}>
      By adding the `Secure` concern to your application controller, you'll only need to use a
      `before_action` filter in the controller that requires authorization.
    </Section>

    <Section title={sections[5].title}>
      Create a controller to handle the public endpoint `/api/public`.

      The `/public` endpoint does not require any authorization so no `before_action` is needed.
    </Section>

    <Section title={sections[6].title}>
      Create a controller to handle the private endpoints: `/api/private` and
      `/api/private-scoped`.

      `/api/private` is available for authenticated requests containing an access token with no additional
      scopes.

      `/api/private-scoped` is available for authenticated requests containing an access token with the
      `read:messages` scope granted

      The protected endpoints need to call the `authorize` method from the `Secured` concern, for
      that you use `before_action :authorize`, this ensure the `Secured.authorize` method is
      called before every action in the `PrivateController`.

      ### Make a Call to Your API

      To make calls to your API, you need an Access Token. You can get an Access Token for testing purposes from the
      **Test** view in your [API
      settings](https://manage.auth0.com/#/apis).

      <Frame>
        <img />
      </Frame>

      Provide the Access Token as an `Authorization` header in your requests.

      <AuthCodeGroup>
        ```bash cURL lines theme={null}
        curl --request get \
        --url 'http:///%7ByourDomain%7D/api_path' \
        --header 'authorization: Bearer YOUR_ACCESS_TOKEN_HERE'
        ```

        ```csharp C# lines theme={null}
        var client = new RestClient("http:///%7ByourDomain%7D/api_path");
        var request = new RestRequest(Method.GET);
        request.AddHeader("authorization", "Bearer YOUR_ACCESS_TOKEN_HERE");
        IRestResponse response = client.Execute(request);
        ```

        ```go Go lines theme={null}
        package main
        import (
        "fmt"
        "net/http"
        "io/ioutil"
        )
        func main() {
        url := "http:///%7ByourDomain%7D/api_path"
        req, _ := http.NewRequest("get", url, nil)
        req.Header.Add("authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
        res, _ := http.DefaultClient.Do(req)
        defer res.Body.Close()
        body, _ := ioutil.ReadAll(res.Body)
        fmt.Println(res)
        fmt.Println(string(body))
        }
        ```

        ```java Java lines theme={null}
        HttpResponse<String> response = Unirest.get("http:///%7ByourDomain%7D/api_path")
        .header("authorization", "Bearer YOUR_ACCESS_TOKEN_HERE")
        .asString();
        ```

        ```javascript Node.JS lines theme={null}
        var axios = require("axios").default;
        var options = {
        method: 'get',
        url: 'http:///%7ByourDomain%7D/api_path',
        headers: {authorization: 'Bearer YOUR_ACCESS_TOKEN_HERE'}
        };
        axios.request(options).then(function (response) {
        console.log(response.data);
        }).catch(function (error) {
        console.error(error);
        });
        ```

        ```objc Obj-C lines theme={null}
        #import <Foundation/Foundation.h>
        NSDictionary *headers = @{ @"authorization": @"Bearer YOUR_ACCESS_TOKEN_HERE" };
        NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"http:///%7ByourDomain%7D/api_path"]
                                                        cachePolicy:NSURLRequestUseProtocolCachePolicy

                                                    timeoutInterval:10.0];

        [request setHTTPMethod:@"get"];
        [request setAllHTTPHeaderFields:headers];
        NSURLSession *session = [NSURLSession sharedSession];
        NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                                completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {

                                                    if (error) {

                                                        NSLog(@&quot;%@&quot;, error);

                                                    } else {

                                                        NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;

                                                        NSLog(@&quot;%@&quot;, httpResponse);

                                                    }

                                                }];

        [dataTask resume];
        ```

        ```php PHP lines theme={null}
        #import <Foundation/Foundation.h>
        NSDictionary *headers = @{ @"authorization": @"Bearer YOUR_ACCESS_TOKEN_HERE" };
        NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"http:///%7ByourDomain%7D/api_path"]
                                                        cachePolicy:NSURLRequestUseProtocolCachePolicy

                                                    timeoutInterval:10.0];

        [request setHTTPMethod:@"get"];
        [request setAllHTTPHeaderFields:headers];
        NSURLSession *session = [NSURLSession sharedSession];
        NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                                completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {

                                                    if (error) {

                                                        NSLog(@&quot;%@&quot;, error);

                                                    } else {

                                                        NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;

                                                        NSLog(@&quot;%@&quot;, httpResponse);

                                                    }

                                                }];

        [dataTask resume];
        ```

        ```python Python lines theme={null}
        import http.client
        conn = http.client.HTTPConnection("")
        headers = { 'authorization': "Bearer YOUR_ACCESS_TOKEN_HERE" }
        conn.request("get", "/%7ByourDomain%7D/api_path", headers=headers)
        res = conn.getresponse()
        data = res.read()
        print(data.decode("utf-8"))
        ```

        ```ruby Ruby lines theme={null}
        require 'uri'
        require 'net/http'
        url = URI("http:///%7ByourDomain%7D/api_path")
        http = Net::HTTP.new(url.host, url.port)
        request = Net::HTTP::Get.new(url)
        request["authorization"] = 'Bearer YOUR_ACCESS_TOKEN_HERE'
        response = http.request(request)
        puts response.read_body
        ```

        ```swift Swift lines theme={null}
        import Foundation
        let headers = ["authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"]
        let request = NSMutableURLRequest(url: NSURL(string: "http:///%7ByourDomain%7D/api_path")! as URL,
                                            cachePolicy: .useProtocolCachePolicy,

                                        timeoutInterval: 10.0)

        request.httpMethod = "get"
        request.allHTTPHeaderFields = headers
        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()
        ```
      </AuthCodeGroup>

      <Note>
        ##### Checkpoint

        Now that you have configured your application, run your application to verify that:

        * `GET /api/public`is available for non-authenticated requests.
        * `GET /api/private`is available for authenticated requests.
        * `GET /api/private-scoped`is available for authenticated requests containing an Access
          Token with the `read:messages`scope.
      </Note>
    </Section>

    ## Next Steps

    Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.

    This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:

    * [Auth0 Dashboard](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq) - Learn how to configure and manage your Auth0 tenant and applications
    * [omniauth-auth0 SDK](https://github.com/auth0/omniauth-auth0) - Explore the SDK used in this tutorial more fully
    * [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
  </Content>

  <SideMenu>
    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```rb app/controllers/concerns/secured.rb lines highlight={} theme={null}
        # frozen_string_literal: true

            module Secured
              extend ActiveSupport::Concern

              REQUIRES_AUTHENTICATION = { message: 'Requires authentication' }.freeze
              BAD_CREDENTIALS = {
        message: 'Bad credentials'
              }.freeze
              MALFORMED_AUTHORIZATION_HEADER = {
        error: 'invalid_request',
        error_description: 'Authorization header value must follow this format: Bearer access-token',
        message: 'Bad credentials'
              }.freeze
              INSUFFICIENT_PERMISSIONS = {
        error: 'insufficient_permissions',
        error_description: 'The access token does not contain the required permissions',
        message: 'Permission denied'
              }.freeze

              def authorize
        token = token_from_request

        return if performed?

        validation_response = Auth0Client.validate_token(token)

        @decoded_token = validation_response.decoded_token

        return unless (error = validation_response.error)

        render json: { message: error.message }, status: error.status
              end

              def validate_permissions(permissions)
        raise 'validate_permissions needs to be called with a block' unless block_given?
        return yield if @decoded_token.validate_permissions(permissions)

        render json: INSUFFICIENT_PERMISSIONS, status: :forbidden
              end

              private

              def token_from_request
        authorization_header_elements = request.headers['Authorization']&.split

        render json: REQUIRES_AUTHENTICATION, status: :unauthorized and return unless authorization_header_elements

        unless authorization_header_elements.length == 2
          render json: MALFORMED_AUTHORIZATION_HEADER,
                 status: :unauthorized and return
        end

        scheme, token = authorization_header_elements

        render json: BAD_CREDENTIALS, status: :unauthorized and return unless scheme.downcase == 'bearer'

        token
              end
            end
        ```

        ```rb app/controllers/application_controller.rb lines highlight={} theme={null}
        # frozen_string_literal: true

            class ApplicationController < ActionController::API
              include Secured
            end
        ```

        ```rb app/lib/auth0_client.rb lines highlight={} theme={null}
        ```

        ```rb app/controllers/public_controller.rb lines highlight={} theme={null}
        # frozen_string_literal: true
            class PublicController < ApplicationController
              def public
        render json: { message: 'All good. You don\'t need to be authenticated to call this.' }
              end
            end
        ```

        ```rb app/controllers/private_controller.rb lines highlight={} theme={null}
        # frozen_string_literal: true
            class PublicController < ApplicationController
              def public
        render json: { message: 'All good. You don\'t need to be authenticated to call this.' }
              end
        end
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```rb app/controllers/concerns/secured.rb lines highlight={} theme={null}
        # frozen_string_literal: true

            module Secured
              extend ActiveSupport::Concern

              REQUIRES_AUTHENTICATION = { message: 'Requires authentication' }.freeze
              BAD_CREDENTIALS = {
        message: 'Bad credentials'
              }.freeze
              MALFORMED_AUTHORIZATION_HEADER = {
        error: 'invalid_request',
        error_description: 'Authorization header value must follow this format: Bearer access-token',
        message: 'Bad credentials'
              }.freeze
              INSUFFICIENT_PERMISSIONS = {
        error: 'insufficient_permissions',
        error_description: 'The access token does not contain the required permissions',
        message: 'Permission denied'
              }.freeze

              def authorize
        token = token_from_request

        return if performed?

        validation_response = Auth0Client.validate_token(token)

        @decoded_token = validation_response.decoded_token

        return unless (error = validation_response.error)

        render json: { message: error.message }, status: error.status
              end

              def validate_permissions(permissions)
        raise 'validate_permissions needs to be called with a block' unless block_given?
        return yield if @decoded_token.validate_permissions(permissions)

        render json: INSUFFICIENT_PERMISSIONS, status: :forbidden
              end

              private

              def token_from_request
        authorization_header_elements = request.headers['Authorization']&.split

        render json: REQUIRES_AUTHENTICATION, status: :unauthorized and return unless authorization_header_elements

        unless authorization_header_elements.length == 2
          render json: MALFORMED_AUTHORIZATION_HEADER,
                 status: :unauthorized and return
        end

        scheme, token = authorization_header_elements

        render json: BAD_CREDENTIALS, status: :unauthorized and return unless scheme.downcase == 'bearer'

        token
              end
            end
        ```

        ```rb app/controllers/application_controller.rb lines highlight={} theme={null}
        # frozen_string_literal: true

            class ApplicationController < ActionController::API
              include Secured
            end
        ```

        ```rb app/lib/auth0_client.rb lines highlight={} theme={null}
        ```

        ```rb app/controllers/public_controller.rb lines highlight={} theme={null}
        # frozen_string_literal: true
            class PublicController < ApplicationController
              def public
        render json: { message: 'All good. You don\'t need to be authenticated to call this.' }
              end
            end
        ```

        ```rb app/controllers/private_controller.rb lines highlight={} theme={null}
        # frozen_string_literal: true
            class PublicController < ApplicationController
              def public
        render json: { message: 'All good. You don\'t need to be authenticated to call this.' }
              end
        end
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```rb app/controllers/application_controller.rb lines highlight={} theme={null}
        # frozen_string_literal: true

            class ApplicationController < ActionController::API
              include Secured
            end
        ```

        ```rb app/lib/auth0_client.rb lines highlight={} theme={null}
        ```

        ```rb app/controllers/concerns/secured.rb lines highlight={} theme={null}
        # frozen_string_literal: true

            module Secured
              extend ActiveSupport::Concern

              REQUIRES_AUTHENTICATION = { message: 'Requires authentication' }.freeze
              BAD_CREDENTIALS = {
        message: 'Bad credentials'
              }.freeze
              MALFORMED_AUTHORIZATION_HEADER = {
        error: 'invalid_request',
        error_description: 'Authorization header value must follow this format: Bearer access-token',
        message: 'Bad credentials'
              }.freeze
              INSUFFICIENT_PERMISSIONS = {
        error: 'insufficient_permissions',
        error_description: 'The access token does not contain the required permissions',
        message: 'Permission denied'
              }.freeze

              def authorize
        token = token_from_request

        return if performed?

        validation_response = Auth0Client.validate_token(token)

        @decoded_token = validation_response.decoded_token

        return unless (error = validation_response.error)

        render json: { message: error.message }, status: error.status
              end

              def validate_permissions(permissions)
        raise 'validate_permissions needs to be called with a block' unless block_given?
        return yield if @decoded_token.validate_permissions(permissions)

        render json: INSUFFICIENT_PERMISSIONS, status: :forbidden
              end

              private

              def token_from_request
        authorization_header_elements = request.headers['Authorization']&.split

        render json: REQUIRES_AUTHENTICATION, status: :unauthorized and return unless authorization_header_elements

        unless authorization_header_elements.length == 2
          render json: MALFORMED_AUTHORIZATION_HEADER,
                 status: :unauthorized and return
        end

        scheme, token = authorization_header_elements

        render json: BAD_CREDENTIALS, status: :unauthorized and return unless scheme.downcase == 'bearer'

        token
              end
            end
        ```

        ```rb app/controllers/public_controller.rb lines highlight={} theme={null}
        # frozen_string_literal: true
            class PublicController < ApplicationController
              def public
        render json: { message: 'All good. You don\'t need to be authenticated to call this.' }
              end
            end
        ```

        ```rb app/controllers/private_controller.rb lines highlight={} theme={null}
        # frozen_string_literal: true
            class PublicController < ApplicationController
              def public
        render json: { message: 'All good. You don\'t need to be authenticated to call this.' }
              end
        end
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```rb app/controllers/public_controller.rb lines highlight={} theme={null}
        # frozen_string_literal: true
            class PublicController < ApplicationController
              def public
        render json: { message: 'All good. You don\'t need to be authenticated to call this.' }
              end
            end
        ```

        ```rb app/controllers/application_controller.rb lines highlight={} theme={null}
        # frozen_string_literal: true

            class ApplicationController < ActionController::API
              include Secured
            end
        ```

        ```rb app/lib/auth0_client.rb lines highlight={} theme={null}
        ```

        ```rb app/controllers/concerns/secured.rb lines highlight={} theme={null}
        # frozen_string_literal: true

            module Secured
              extend ActiveSupport::Concern

              REQUIRES_AUTHENTICATION = { message: 'Requires authentication' }.freeze
              BAD_CREDENTIALS = {
        message: 'Bad credentials'
              }.freeze
              MALFORMED_AUTHORIZATION_HEADER = {
        error: 'invalid_request',
        error_description: 'Authorization header value must follow this format: Bearer access-token',
        message: 'Bad credentials'
              }.freeze
              INSUFFICIENT_PERMISSIONS = {
        error: 'insufficient_permissions',
        error_description: 'The access token does not contain the required permissions',
        message: 'Permission denied'
              }.freeze

              def authorize
        token = token_from_request

        return if performed?

        validation_response = Auth0Client.validate_token(token)

        @decoded_token = validation_response.decoded_token

        return unless (error = validation_response.error)

        render json: { message: error.message }, status: error.status
              end

              def validate_permissions(permissions)
        raise 'validate_permissions needs to be called with a block' unless block_given?
        return yield if @decoded_token.validate_permissions(permissions)

        render json: INSUFFICIENT_PERMISSIONS, status: :forbidden
              end

              private

              def token_from_request
        authorization_header_elements = request.headers['Authorization']&.split

        render json: REQUIRES_AUTHENTICATION, status: :unauthorized and return unless authorization_header_elements

        unless authorization_header_elements.length == 2
          render json: MALFORMED_AUTHORIZATION_HEADER,
                 status: :unauthorized and return
        end

        scheme, token = authorization_header_elements

        render json: BAD_CREDENTIALS, status: :unauthorized and return unless scheme.downcase == 'bearer'

        token
              end
            end
        ```

        ```rb app/controllers/private_controller.rb lines highlight={} theme={null}
        # frozen_string_literal: true
            class PublicController < ApplicationController
              def public
        render json: { message: 'All good. You don\'t need to be authenticated to call this.' }
              end
        end
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```rb app/controllers/private_controller.rb lines highlight={} theme={null}
        # frozen_string_literal: true
            class PublicController < ApplicationController
              def public
        render json: { message: 'All good. You don\'t need to be authenticated to call this.' }
              end
        end
        ```

        ```rb app/controllers/application_controller.rb lines highlight={} theme={null}
        # frozen_string_literal: true

            class ApplicationController < ActionController::API
              include Secured
            end
        ```

        ```rb app/lib/auth0_client.rb lines highlight={} theme={null}
        ```

        ```rb app/controllers/concerns/secured.rb lines highlight={} theme={null}
        # frozen_string_literal: true

            module Secured
              extend ActiveSupport::Concern

              REQUIRES_AUTHENTICATION = { message: 'Requires authentication' }.freeze
              BAD_CREDENTIALS = {
        message: 'Bad credentials'
              }.freeze
              MALFORMED_AUTHORIZATION_HEADER = {
        error: 'invalid_request',
        error_description: 'Authorization header value must follow this format: Bearer access-token',
        message: 'Bad credentials'
              }.freeze
              INSUFFICIENT_PERMISSIONS = {
        error: 'insufficient_permissions',
        error_description: 'The access token does not contain the required permissions',
        message: 'Permission denied'
              }.freeze

              def authorize
        token = token_from_request

        return if performed?

        validation_response = Auth0Client.validate_token(token)

        @decoded_token = validation_response.decoded_token

        return unless (error = validation_response.error)

        render json: { message: error.message }, status: error.status
              end

              def validate_permissions(permissions)
        raise 'validate_permissions needs to be called with a block' unless block_given?
        return yield if @decoded_token.validate_permissions(permissions)

        render json: INSUFFICIENT_PERMISSIONS, status: :forbidden
              end

              private

              def token_from_request
        authorization_header_elements = request.headers['Authorization']&.split

        render json: REQUIRES_AUTHENTICATION, status: :unauthorized and return unless authorization_header_elements

        unless authorization_header_elements.length == 2
          render json: MALFORMED_AUTHORIZATION_HEADER,
                 status: :unauthorized and return
        end

        scheme, token = authorization_header_elements

        render json: BAD_CREDENTIALS, status: :unauthorized and return unless scheme.downcase == 'bearer'

        token
              end
            end
        ```

        ```rb app/controllers/public_controller.rb lines highlight={} theme={null}
        # frozen_string_literal: true
            class PublicController < ApplicationController
              def public
        render json: { message: 'All good. You don\'t need to be authenticated to call this.' }
              end
            end
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>
  </SideMenu>
</Recipe>


# Add Authorization to Your ASP.NET OWIN Web API Application
Source: https://auth0.com/docs/quickstart/backend/webapi-owin/interactive

This tutorial demonstrates how to add authorization to an ASP.NET OWIN API using the standard JWT middleware.

<QuickstartButtons />

<Recipe>
  <Content>
    Auth0 allows you to add authorization to any kind of application. This guide demonstrates how to integrate Auth0
    with any new or existing ASP.NET Owin Web API application using the `Microsoft.Owin.Security.Jwt`
    package.

    If you have not created an API in your Auth0 dashboard yet, you can use the interactive selector to create a new
    Auth0 API or select an existing API for your project.

    To set up your first API through the Auth0 dashboard, review our getting started guide.

    Each Auth0 API uses the API Identifier, which your application needs to validate the access token.

    <Info>
      **New to Auth0?** Learn how Auth0 works and
      read about implementing API authentication and
      authorization using the OAuth 2.0 framework.
    </Info>

    <Section title={sections[0].title}>
      Permissions let you define how resources can be accessed on behalf of the user with a given access token. For
      example, you might choose to grant read access to the `messages` resource if users have the manager
      access level, and a write access to that resource if they have the administrator access level.

      You can define allowed permissions in the **Permissions** view of the Auth0 Dashboard's [APIs](https://manage.auth0.com/#/apis) section. The following
      example uses the `read:messages` scope.

      <Frame>
        <img />
      </Frame>
    </Section>

    <Section title={sections[1].title}>
      Install the `Microsoft.Owin.Security.Jwt` NuGetPackage. This package contains the OWIN JWT Middleware
      necessary to use Auth0 access tokens in the ASP.NET Owin Web API.

      ```ps lines theme={null}
      Install-Package Microsoft.Owin.Security.Jwt
      ```
    </Section>

    <Section title={sections[2].title}>
      Go to the `Configuration` method of your `Startup` class and add a call to
      `UseJwtBearerAuthentication` passing in the configured `JwtBearerAuthenticationOptions`.

      The `JwtBearerAuthenticationOptions` needs to specify your Auth0 API Identifier in the
      `ValidAudience` property, and the full path to your Auth0 domain as the `ValidIssuer`. You
      will need to configure the `IssuerSigningKeyResolver` to use the instance of
      `OpenIdConnectSigningKeyResolver` to resolve the signing key.

      <Warning>
        **Do not forget the trailing slash.**

        Ensure the URL specified for `ValidIssuer` contains a trailing forward slash
        (`/`). This must match exactly with the JWT issuer claim. API calls will not authenticate
        correctly if you misconfigured this value.
      </Warning>
    </Section>

    <Section title={sections[3].title}>
      The OWIN JWT middleware does not use Open ID Connect Discovery by default, so you must provide a custom
      `IssuerSigningKeyResolver`.

      Create the `OpenIdConnectSigningKeyResolver` class and ensure to return the correct
      `SecurityKey` by implementing `GetSigningKey`. This class is then used as
      `TokenValidationParameters.IssuerSigningKeyResolver` while configuring the middleware in
      `Startup.cs`.

      <Info>
        This custom resolver is deprecated and [no longer available](https://github.com/auth0/auth0-aspnet-owin/blob/master/SECURITY-NOTICE.md). You must provide this custom resolver yourself.
      </Info>
    </Section>

    <Section title={sections[4].title}>
      The JWT middleware verifies that the access token included in the request is valid; however, it doesn't yet
      include any mechanism for checking that the token has the sufficient **scope** to access the requested
      resources.

      Create a class called `ScopeAuthorizeAttribute` which inherits from
      `System.Web.Http.AuthorizeAttribute`. This attribute will check that the `scope` claim
      issued by your Auth0 tenant is present, and if so, it will ensure that the `scope` claim contains the
      requested scope.
    </Section>

    <Section title={sections[5].title}>
      The routes shown below are available for the following requests:

      * `GET /api/public`: Available for non-authenticated requests.
      * `GET /api/private`: Available for authenticated requests containing an access token with no
        additional scopes.
      * `GET /api/private-scoped`: Available for authenticated requests containing an access token with
        the `read:messages`scope granted.

      The JWT middleware integrates with the standard ASP.NET authentication and authorization mechanisms, so you only
      need to decorate your controller action with the `[Authorize]` attribute to secure an endpoint.

      Update the action with the `ScopeAuthorize` attribute and pass the name of the required
      `scope` in the `scope` parameter. This ensures the correct scope is available to call a
      specific API endpoint.

      <Note>
        ##### Checkpoint

        Now that you have configured your application, run your application and verify that:

        * `GET /api/public`is available for non-authenticated requests.
        * `GET /api/private`is available for authenticated requests.
        * `GET /api/private-scoped`is available for authenticated requests containing an access
          token with the `read:messages`scope.
      </Note>
    </Section>

    ## Next Steps

    Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.

    This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:

    * [Auth0 Dashboard](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq) - Learn how to configure and manage your Auth0 tenant and applications
    * [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
  </Content>

  <SideMenu>
    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```cs OpenIdConnectSigningKeyResolver.cs lines highlight={} theme={null}
        public class OpenIdConnectSigningKeyResolver
        {
            private readonly OpenIdConnectConfiguration openIdConfig;

            public OpenIdConnectSigningKeyResolver(string authority)
            {
                var cm = new ConfigurationManager<OpenIdConnectConfiguration>($"{authority.TrimEnd('/')}/.well-known/openid-configuration", new OpenIdConnectConfigurationRetriever());
                openIdConfig = AsyncHelper.RunSync(async () => await cm.GetConfigurationAsync());
            }

            public SecurityKey[] GetSigningKey(string kid)
            {
                return new[] { openIdConfig.JsonWebKeySet.GetSigningKeys().FirstOrDefault(t => t.KeyId == kid) };
            }
        }
        ```

        ```cs ScopeAuthorizeAttribute.cs lines highlight={} theme={null}
        public class ScopeAuthorizeAttribute : AuthorizeAttribute
        {
            private readonly string scope;

            public ScopeAuthorizeAttribute(string scope)
            {
                this.scope = scope;
            }

            public override void OnAuthorization(HttpActionContext actionContext)
            {
                base.OnAuthorization(actionContext);

                // Get the Auth0 domain, in order to validate the issuer
                var domain = $"https://{ConfigurationManager.AppSettings["Auth0Domain"]}/";

                // Get the claim principal
                ClaimsPrincipal principal = actionContext.ControllerContext.RequestContext.Principal as ClaimsPrincipal;

                // Get the scope clain. Ensure that the issuer is for the correcr Auth0 domain
                var scopeClaim = principal?.Claims.FirstOrDefault(c => c.Type == "scope" && c.Issuer == domain);
                if (scopeClaim != null)
                {
                    // Split scopes
                    var scopes = scopeClaim.Value.Split(' ');

                    // Succeed if the scope array contains the required scope
                    if (scopes.Any(s => s == scope))
                        return;
                }

                HandleUnauthorizedRequest(actionContext);
            }
        }
        ```

        ```cs ApiController.cs lines highlight={} theme={null}
        [RoutePrefix("api")]
        public class ApiController : ApiController
        {
            [HttpGet]
            [Route("public")]
            public IHttpActionResult Public()
            {
                return Json(new
                {
                    Message = "Hello from a public endpoint!"
                });
            }

            [HttpGet]
            [Route("private")]
            [Authorize]
            public IHttpActionResult Private()
            {
                return Json(new
                {
                    Message = "Hello from a private endpoint! You need to be authenticated to see this."
                });
            }

            [HttpGet]
            [Route("private-scoped")]
            [ScopeAuthorize("read:messages")]
            public IHttpActionResult Scoped()
            {
                return Json(new
                {
                    Message = "Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this."
                });
            }
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```cs OpenIdConnectSigningKeyResolver.cs lines highlight={} theme={null}
        public class OpenIdConnectSigningKeyResolver
        {
            private readonly OpenIdConnectConfiguration openIdConfig;

            public OpenIdConnectSigningKeyResolver(string authority)
            {
                var cm = new ConfigurationManager<OpenIdConnectConfiguration>($"{authority.TrimEnd('/')}/.well-known/openid-configuration", new OpenIdConnectConfigurationRetriever());
                openIdConfig = AsyncHelper.RunSync(async () => await cm.GetConfigurationAsync());
            }

            public SecurityKey[] GetSigningKey(string kid)
            {
                return new[] { openIdConfig.JsonWebKeySet.GetSigningKeys().FirstOrDefault(t => t.KeyId == kid) };
            }
        }
        ```

        ```cs ScopeAuthorizeAttribute.cs lines highlight={} theme={null}
        public class ScopeAuthorizeAttribute : AuthorizeAttribute
        {
            private readonly string scope;

            public ScopeAuthorizeAttribute(string scope)
            {
                this.scope = scope;
            }

            public override void OnAuthorization(HttpActionContext actionContext)
            {
                base.OnAuthorization(actionContext);

                // Get the Auth0 domain, in order to validate the issuer
                var domain = $"https://{ConfigurationManager.AppSettings["Auth0Domain"]}/";

                // Get the claim principal
                ClaimsPrincipal principal = actionContext.ControllerContext.RequestContext.Principal as ClaimsPrincipal;

                // Get the scope clain. Ensure that the issuer is for the correcr Auth0 domain
                var scopeClaim = principal?.Claims.FirstOrDefault(c => c.Type == "scope" && c.Issuer == domain);
                if (scopeClaim != null)
                {
                    // Split scopes
                    var scopes = scopeClaim.Value.Split(' ');

                    // Succeed if the scope array contains the required scope
                    if (scopes.Any(s => s == scope))
                        return;
                }

                HandleUnauthorizedRequest(actionContext);
            }
        }
        ```

        ```cs ApiController.cs lines highlight={} theme={null}
        [RoutePrefix("api")]
        public class ApiController : ApiController
        {
            [HttpGet]
            [Route("public")]
            public IHttpActionResult Public()
            {
                return Json(new
                {
                    Message = "Hello from a public endpoint!"
                });
            }

            [HttpGet]
            [Route("private")]
            [Authorize]
            public IHttpActionResult Private()
            {
                return Json(new
                {
                    Message = "Hello from a private endpoint! You need to be authenticated to see this."
                });
            }

            [HttpGet]
            [Route("private-scoped")]
            [ScopeAuthorize("read:messages")]
            public IHttpActionResult Scoped()
            {
                return Json(new
                {
                    Message = "Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this."
                });
            }
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```cs ScopeAuthorizeAttribute.cs lines highlight={} theme={null}
        public class ScopeAuthorizeAttribute : AuthorizeAttribute
        {
            private readonly string scope;

            public ScopeAuthorizeAttribute(string scope)
            {
                this.scope = scope;
            }

            public override void OnAuthorization(HttpActionContext actionContext)
            {
                base.OnAuthorization(actionContext);

                // Get the Auth0 domain, in order to validate the issuer
                var domain = $"https://{ConfigurationManager.AppSettings["Auth0Domain"]}/";

                // Get the claim principal
                ClaimsPrincipal principal = actionContext.ControllerContext.RequestContext.Principal as ClaimsPrincipal;

                // Get the scope clain. Ensure that the issuer is for the correcr Auth0 domain
                var scopeClaim = principal?.Claims.FirstOrDefault(c => c.Type == "scope" && c.Issuer == domain);
                if (scopeClaim != null)
                {
                    // Split scopes
                    var scopes = scopeClaim.Value.Split(' ');

                    // Succeed if the scope array contains the required scope
                    if (scopes.Any(s => s == scope))
                        return;
                }

                HandleUnauthorizedRequest(actionContext);
            }
        }
        ```

        ```cs OpenIdConnectSigningKeyResolver.cs lines highlight={} theme={null}
        public class OpenIdConnectSigningKeyResolver
        {
            private readonly OpenIdConnectConfiguration openIdConfig;

            public OpenIdConnectSigningKeyResolver(string authority)
            {
                var cm = new ConfigurationManager<OpenIdConnectConfiguration>($"{authority.TrimEnd('/')}/.well-known/openid-configuration", new OpenIdConnectConfigurationRetriever());
                openIdConfig = AsyncHelper.RunSync(async () => await cm.GetConfigurationAsync());
            }

            public SecurityKey[] GetSigningKey(string kid)
            {
                return new[] { openIdConfig.JsonWebKeySet.GetSigningKeys().FirstOrDefault(t => t.KeyId == kid) };
            }
        }
        ```

        ```cs ApiController.cs lines highlight={} theme={null}
        [RoutePrefix("api")]
        public class ApiController : ApiController
        {
            [HttpGet]
            [Route("public")]
            public IHttpActionResult Public()
            {
                return Json(new
                {
                    Message = "Hello from a public endpoint!"
                });
            }

            [HttpGet]
            [Route("private")]
            [Authorize]
            public IHttpActionResult Private()
            {
                return Json(new
                {
                    Message = "Hello from a private endpoint! You need to be authenticated to see this."
                });
            }

            [HttpGet]
            [Route("private-scoped")]
            [ScopeAuthorize("read:messages")]
            public IHttpActionResult Scoped()
            {
                return Json(new
                {
                    Message = "Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this."
                });
            }
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```cs ApiController.cs lines highlight={} theme={null}
        [RoutePrefix("api")]
        public class ApiController : ApiController
        {
            [HttpGet]
            [Route("public")]
            public IHttpActionResult Public()
            {
                return Json(new
                {
                    Message = "Hello from a public endpoint!"
                });
            }

            [HttpGet]
            [Route("private")]
            [Authorize]
            public IHttpActionResult Private()
            {
                return Json(new
                {
                    Message = "Hello from a private endpoint! You need to be authenticated to see this."
                });
            }

            [HttpGet]
            [Route("private-scoped")]
            [ScopeAuthorize("read:messages")]
            public IHttpActionResult Scoped()
            {
                return Json(new
                {
                    Message = "Hello from a private endpoint! You need to be authenticated and have a scope of read:messages to see this."
                });
            }
        }
        ```

        ```cs OpenIdConnectSigningKeyResolver.cs lines highlight={} theme={null}
        public class OpenIdConnectSigningKeyResolver
        {
            private readonly OpenIdConnectConfiguration openIdConfig;

            public OpenIdConnectSigningKeyResolver(string authority)
            {
                var cm = new ConfigurationManager<OpenIdConnectConfiguration>($"{authority.TrimEnd('/')}/.well-known/openid-configuration", new OpenIdConnectConfigurationRetriever());
                openIdConfig = AsyncHelper.RunSync(async () => await cm.GetConfigurationAsync());
            }

            public SecurityKey[] GetSigningKey(string kid)
            {
                return new[] { openIdConfig.JsonWebKeySet.GetSigningKeys().FirstOrDefault(t => t.KeyId == kid) };
            }
        }
        ```

        ```cs ScopeAuthorizeAttribute.cs lines highlight={} theme={null}
        public class ScopeAuthorizeAttribute : AuthorizeAttribute
        {
            private readonly string scope;

            public ScopeAuthorizeAttribute(string scope)
            {
                this.scope = scope;
            }

            public override void OnAuthorization(HttpActionContext actionContext)
            {
                base.OnAuthorization(actionContext);

                // Get the Auth0 domain, in order to validate the issuer
                var domain = $"https://{ConfigurationManager.AppSettings["Auth0Domain"]}/";

                // Get the claim principal
                ClaimsPrincipal principal = actionContext.ControllerContext.RequestContext.Principal as ClaimsPrincipal;

                // Get the scope clain. Ensure that the issuer is for the correcr Auth0 domain
                var scopeClaim = principal?.Claims.FirstOrDefault(c => c.Type == "scope" && c.Issuer == domain);
                if (scopeClaim != null)
                {
                    // Split scopes
                    var scopes = scopeClaim.Value.Split(' ');

                    // Succeed if the scope array contains the required scope
                    if (scopes.Any(s => s == scope))
                        return;
                }

                HandleUnauthorizedRequest(actionContext);
            }
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>
  </SideMenu>
</Recipe>


# Add Native Facebook Login to Your Android Application
Source: https://auth0.com/docs/quickstart/native/android-facebook-login/index



## Before You Start

Complete these prerequisites before following this quickstart:

1. **Set up Facebook Login SDK** - Install and configure the [Facebook Login SDK for Android](https://developers.facebook.com/docs/facebook-login/). Create a Facebook app at [developers.facebook.com](https://developers.facebook.com). When done, your app should have Facebook Login working.
2. **Configure Auth0 for Facebook Native** - Configure your Auth0 application to use Facebook Native Sign In. See [Add Facebook Login to Native Apps](/docs/authenticate/identity-providers/social-identity-providers/facebook-native).

## Get Started

<Steps>
  <Step title="Configure Facebook Login permissions">
    Update the Facebook Login Button in your Activity to request the correct permissions.

    Your app already supports Facebook Login, but to get a rich user profile you need to request `public_profile` and `email` permissions. You'll also add a callback to kick off the Auth0 authentication flow.

    ```kotlin MainActivity.kt lines theme={null}
    private lateinit var fbCallbackManager: CallbackManager

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_login)

        fbCallbackManager = CallbackManager.Factory.create()
        val loginButton = findViewById<LoginButton>(R.id.login_button)

        // Request email and public_profile permissions
        loginButton.setPermissions("email", "public_profile")

        loginButton.registerCallback(fbCallbackManager,
            object : FacebookCallback<LoginResult> {
                override fun onSuccess(result: LoginResult) {
                    val accessToken = result.accessToken
                    performLogin(accessToken)
                }
                override fun onCancel() {
                    // User closed the dialog. Safe to ignore
                }
                override fun onError(error: FacebookException) {
                    // Handle Facebook authentication error
                }
            })
    }

    private fun performLogin(accessToken: AccessToken) {
        // Steps 2–4 will fill this in
    }
    ```

    <Info>
      The `email` permission is optional — the user must consent to sharing it. The email returned from Facebook will be **flagged as non-verified** on the Auth0 user profile.
    </Info>
  </Step>

  <Step title="Install and configure the Auth0 SDK">
    Add the Auth0 Android SDK to your project and configure your application credentials.

    **Add the dependency to `app/build.gradle.kts`:**

    ```kotlin app/build.gradle.kts lines theme={null}
    dependencies {
        implementation("com.auth0.android:auth0:3.+")
    }
    ```

    Sync Gradle after adding the dependency.

    **Add your Auth0 credentials to `strings.xml`:**

    Go to the **Applications** section of the [Auth0 Dashboard](https://manage.auth0.com/) and select the application where you enabled Facebook Native Sign In. Copy the **Domain** and **Client ID** values.

    ```xml app/src/main/res/values/strings.xml lines theme={null}
    <resources>
        <string name="com_auth0_domain">{yourDomain}</string>
        <string name="com_auth0_client_id">{yourClientId}</string>
    </resources>
    ```

    **Initialize the Auth0 SDK in your Activity:**

    ```kotlin MainActivity.kt lines theme={null}
    private val account: Auth0 by lazy {
        Auth0.getInstance(
            getString(R.string.com_auth0_client_id),
            getString(R.string.com_auth0_domain)
        )
    }

    private val authenticationApiClient: AuthenticationAPIClient by lazy {
        AuthenticationAPIClient(account)
    }
    ```

    <Note>
      If your app does not use Auth0 Web Authentication, remove the unused activity from `AndroidManifest.xml` to avoid Manifest Placeholder errors:

      ```xml app/src/main/AndroidManifest.xml lines theme={null}
      <application>
          <activity
              android:name="com.auth0.android.provider.AuthenticationActivity"
              tools:node="remove" />
      </application>
      ```

      If you do plan to support Web Authentication, see [Authentication via Universal Login](/docs/libraries/auth0-android#authentication-via-universal-login).
    </Note>
  </Step>

  <Step title="Fetch Facebook session access token">
    After Facebook Login succeeds, fetch a **session access token** from the Facebook API. Auth0 requires this token to verify the user's identity on the backend.

    Make a GET request to Facebook's `/oauth/access_token` endpoint using the `GraphRequest` class:

    ```kotlin MainActivity.kt lines theme={null}
    private interface SimpleCallback<T> {
        fun onResult(result: T)
        fun onError(cause: Throwable)
    }

    private fun fetchSessionToken(accessToken: AccessToken, callback: SimpleCallback<String>) {
        val request = GraphRequest()
        request.graphPath = "oauth/access_token"
        val bundle = Bundle()
        bundle.putString("grant_type", "fb_attenuate_token")
        bundle.putString("client_id", getString(R.string.facebook_app_id))
        bundle.putString("fb_exchange_token", accessToken.token)
        request.parameters = bundle
        request.callback = GraphRequest.Callback { response ->
            if (response.error != null) {
                response.error?.exception?.let { callback.onError(it) }
            } else {
                response.jsonObject?.let { callback.onResult(it.getString("access_token")) }
            }
        }
        request.executeAsync()
    }
    ```

    <Info>
      The required query parameters are:

      * `grant_type`: `fb_attenuate_token`
      * `fb_exchange_token`: the access token from Facebook Login
      * `client_id`: your Facebook App ID (already in your app from the Facebook SDK setup)
    </Info>
  </Step>

  <Step title="Fetch Facebook user profile">
    Fetch the user's profile from Facebook. Auth0 uses this data to create or update the user's Auth0 profile.

    ```kotlin MainActivity.kt lines theme={null}
    private fun fetchUserProfile(
        accessToken: AccessToken,
        callback: SimpleCallback<String>
    ) {
        val request = GraphRequest.newMeRequest(accessToken) { _, response ->
            val error = response?.error
            if (error != null) {
                error.exception?.let { callback.onError(it) }
            } else {
                callback.onResult(response?.rawResponse.toString())
            }
        }
        val bundle = Bundle()
        bundle.putString("fields", "first_name,last_name,email")
        request.parameters = bundle
        request.executeAsync()
    }
    ```

    <Tip>
      The `fields` parameter maps directly to the Facebook permissions you requested. Requesting `first_name`, `last_name`, and `email` is sufficient for Auth0 to create a complete user profile.
    </Tip>
  </Step>

  <Step title="Exchange tokens for Auth0 credentials">
    Use the session token and user profile from the previous steps to authenticate with Auth0 and receive Auth0 tokens.

    Call `loginWithNativeSocialToken` on the `AuthenticationAPIClient`, passing the session token with the Facebook subject token type:

    ```kotlin MainActivity.kt lines theme={null}
    private fun exchangeTokens(
        sessionToken: String,
        userProfile: String,
        callback: SimpleCallback<Credentials>
    ) {
        authenticationApiClient
            .loginWithNativeSocialToken(
                sessionToken,
                "http://auth0.com/oauth/token-type/facebook-info-session-access-token"
            )
            .setScope("openid profile email offline_access")
            .addParameter(name = "user_profile", value = userProfile)
            .start(object : Callback<Credentials, AuthenticationException> {
                override fun onSuccess(result: Credentials) {
                    callback.onResult(result)
                }
                override fun onFailure(error: AuthenticationException) {
                    callback.onError(error)
                }
            })
    }
    ```

    <Info>
      The subject token type `http://auth0.com/oauth/token-type/facebook-info-session-access-token` tells Auth0 to use the Facebook native connection for authentication.
    </Info>
  </Step>

  <Step title="Put it all together">
    Complete the `performLogin` method to chain all three steps: fetch session token → fetch user profile → exchange for Auth0 tokens.

    ```kotlin MainActivity.kt lines theme={null}
    private fun performLogin(accessToken: AccessToken) {
        fetchSessionToken(accessToken, object : SimpleCallback<String> {
            override fun onResult(sessionToken: String) {
                fetchUserProfile(accessToken, object : SimpleCallback<String> {
                    override fun onResult(userProfile: String) {
                        exchangeTokens(sessionToken, userProfile, object : SimpleCallback<Credentials> {
                            override fun onResult(result: Credentials) {
                                // Authenticated! Use result.accessToken or result.idToken
                            }
                            override fun onError(cause: Throwable) {
                                // Handle token exchange error
                            }
                        })
                    }
                    override fun onError(cause: Throwable) {
                        // Handle profile request error
                    }
                })
            }
            override fun onError(cause: Throwable) {
                // Handle session token request error
            }
        })
    }
    ```

    <Tip>
      Keep constants (subject token type, Facebook permissions, Auth0 scopes) at the top of your class to avoid magic strings scattered throughout the code.
    </Tip>
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now be able to authenticate natively with Facebook. If the Facebook app is installed on the device, authentication is handled through the app directly — no browser required.
</Check>

***

## Troubleshooting & Advanced

<Accordion title="Common Issues & Solutions">
  ### Token exchange fails with authentication error

  **Solutions:**

  1. Verify your Auth0 application has **Facebook Native Sign In** enabled in the Dashboard
  2. Check that the Facebook App ID in your `strings.xml` matches the one in the Facebook Developer Console
  3. Confirm the subject token type string matches exactly: `http://auth0.com/oauth/token-type/facebook-info-session-access-token`
  4. Ensure the Facebook access token hasn't expired before calling `performLogin`

  ### Session token request returns an error

  **Fix:**

  * Verify `R.string.facebook_app_id` is correctly set in your `strings.xml`
  * Ensure the `fb_exchange_token` is the raw token string from the Facebook `AccessToken` object
  * Check that your Facebook app is not in Development Mode if testing with non-admin users

  ### `AuthenticationException`: "Connection not found"

  **Fix:**

  1. Go to Auth0 Dashboard → **Authentication** → **Social**
  2. Verify **Sign in with Facebook** is enabled
  3. Confirm **Facebook Native Social Login** is turned on in the connection settings
  4. Check the Auth0 application is associated with the Facebook connection

  ### User profile fields are missing

  * Confirm `public_profile` and `email` are listed in the `setPermissions` call
  * The user may have declined the `email` permission — handle null email gracefully
  * Verify the same fields are in the `fields` bundle in `fetchUserProfile`
</Accordion>

<Accordion title="Production Considerations">
  ### Security Best Practices

  * **Disable logging in production**: Remove or gate `enableLogging = true` on the `DefaultClient` — it logs network traffic
  * **Secure token storage**: Use `SecureCredentialsManager` to store Auth0 tokens in the Android Keystore
  * **Refresh tokens**: Request `offline_access` scope and implement token refresh to maintain sessions

  ### Facebook App Configuration

  * Switch your Facebook app from **Development Mode** to **Live** before releasing
  * Add your app's SHA-1 key fingerprint to the Facebook Developer Console
  * Review Facebook's [Data Policy](https://developers.facebook.com/policy/) requirements for apps using the Login SDK

  ### Google Play Store

  * Follow Google Play's policies for apps that use third-party authentication
  * Include Facebook Login in your app's privacy policy
</Accordion>

***

## Next Steps

<CardGroup>
  <Card title="Configure other identity providers" icon="key" href="/docs/authenticate/identity-providers">
    Add Google, Apple, and other social login providers
  </Card>

  <Card title="Attack Protection" icon="shield" href="/docs/secure/attack-protection">
    Protect against brute force and bot attacks
  </Card>

  <Card title="Actions" icon="bolt" href="/docs/customize/actions/actions-overview">
    Customize authentication flows with serverless code
  </Card>

  <Card title="Android SDK Reference" icon="android" href="/docs/libraries/auth0-android">
    Explore the full Auth0 Android SDK documentation
  </Card>
</CardGroup>


# Add Login to Your Android Application using the Auth0.Android SDK
Source: https://auth0.com/docs/quickstart/native/android/index



## Get Started

<Steps>
  <Step title="Create a new Android project">
    Create a new Android project for this quickstart.

    **In Android Studio:**

    1. **File** → **New** → **New Project**
    2. Select **Phone and Tablet** → **Empty Activity** template
    3. Configure your project:
       * **Name**: `Auth0-Android-Sample`
       * **Package name**: `com.auth0.samples.android`
       * **Language**: **Kotlin**
       * **Minimum SDK**: **API 24 (Android 7.0)**
       * **Build configuration language**: **Kotlin DSL**
    4. Click **Finish**

    <Tip>
      This creates a modern Android app with Kotlin and Gradle Kotlin DSL, following current Android development best practices.
    </Tip>
  </Step>

  <Step title="Add Auth0 SDK via Gradle">
    Add the Auth0 Android SDK to your project using Gradle.

    **Update your app-level `build.gradle.kts` file:**

    ```kotlin app/build.gradle.kts lines theme={null}
    dependencies {   
        // Auth0 SDK
        implementation("com.auth0.android:auth0:3.11.0")
    }
    ```

    **Add manifest placeholders in your app-level `build.gradle.kts`:**

    ```kotlin app/build.gradle.kts lines theme={null}
    android {
        defaultConfig {
            // Add these manifest placeholders
            manifestPlaceholders += mapOf(
                "auth0Domain" to "@string/com_auth0_domain", // this will be set in the next step
                "auth0Scheme" to "https"
            )
        }
    }

    ```

    **Add Internet permission to `AndroidManifest.xml`:**

    ```xml app/src/main/AndroidManifest.xml lines theme={null}
    <?xml version="1.0" encoding="utf-8"?>
    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools">
        <uses-permission android:name="android.permission.INTERNET" />
    </manifest>
    ```

    <Tip>
      The Auth0 SDK automatically handles dependency resolution and includes secure token storage capabilities.
    </Tip>
  </Step>

  <Step title="Setup your Auth0 App">
    Next up, you need to create a new app on your Auth0 tenant and add the configuration to your Android project.

    First, prepare your `app/src/main/res/values/strings.xml` file with placeholder values:

    ```xml app/src/main/res/values/strings.xml theme={null}
    <?xml version="1.0" encoding="utf-8"?>
    <resources>
        <string name="com_auth0_domain">{yourDomain}</string>
        <string name="com_auth0_client_id">YOUR_AUTH0_CLIENT_ID</string>
        <string name="com_auth0_scheme">https</string>
    </resources>
    ```

    1. Head to the [Auth0 Dashboard](https://manage.auth0.com/dashboard/)
    2. Click on **Applications** > **Applications** > **Create Application**
    3. In the popup, enter a name for your app, select `Native` as the app type and click **Create**
    4. Switch to the **Settings** tab on the Application Details page
    5. Replace `{yourDomain}` and `YOUR_AUTH0_CLIENT_ID` in the `strings.xml` file with the **Domain** and **Client ID** values from the dashboard

    Finally, on the **Settings** tab of your Application Details page, configure the following URLs:

    **Allowed Callback URLs:**

    ```
    https://{yourDomain}/android/PACKAGE_NAME/callback
    ```

    **Allowed Logout URLs:**

    ```
    https://{yourDomain}/android/PACKAGE_NAME/callback
    ```

    Replace `{yourDomain}` with your actual Auth0 domain (e.g., `dev-abc123.us.auth0.com`).

    <Info>
      **Allowed Callback URLs** are a critical security measure to ensure users are safely returned to your application after authentication. Without a matching URL, the login process will fail, and users will be blocked by an Auth0 error page instead of accessing your app.

      **Allowed Logout URLs** are essential for providing a seamless user experience upon signing out. Without a matching URL, users will not be redirected back to your application after logout and will instead be left on a generic Auth0 page.

      The URL scheme includes your package name (`com.auth0.samples.android`) to ensure the callback is routed to your specific app.
    </Info>

    <Warning>
      **Important**: Ensure the package name in your callback URLs matches your `applicationId` in `build.gradle.kts`. If authentication fails, verify these values are identical.
    </Warning>
  </Step>

  <Step title="Initialize the Auth0 SDK">
    Create an Auth0 instance in your Activity to communicate with Auth0.

    **In your `MainActivity.kt`:**

    ```kotlin MainActivity.kt lines theme={null}
    import com.auth0.android.Auth0
    import com.auth0.android.authentication.AuthenticationException
    import com.auth0.android.callback.Callback
    import com.auth0.android.provider.WebAuthProvider
    import com.auth0.android.result.Credentials

    class MainActivity : ComponentActivity() {
        private lateinit var auth0: Auth0

        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            
            // Initialize Auth0
            auth0 = Auth0.getInstance(
                getString(R.string.com_auth0_client_id),
                getString(R.string.com_auth0_domain)
            )
        }
    }
    ```

    <Tip>
      The Auth0 instance is initialized with your client ID and domain from the `strings.xml` file you configured earlier. This instance will be used for all authentication operations.
    </Tip>
  </Step>

  <Step title="Implement Login and Logout">
    **Implement Login:** Use WebAuthProvider to launch the universal login page.

    Add these methods to your `MainActivity`:

    <Tabs>
      <Tab title="Kotlin Callback">
        ```kotlin MainActivity.kt lines theme={null}
        private fun login() {
            WebAuthProvider.login(auth0)
                .withScheme("https")
                .withScope("openid profile email offline_access")
                .start(this, object : Callback<Credentials, AuthenticationException> {
                    override fun onSuccess(credentials: Credentials) {
                        // Save the credentials
                        // User is authenticated
                    }

                    override fun onFailure(exception: AuthenticationException) {
                        // Handle error cases
                    }
                })
        }
        ```
      </Tab>

      <Tab title="Coroutine">
        ```kotlin MainActivity.kt lines theme={null}
        private fun login() {
            lifecycleScope.launch {
                try {
                    val credentials = WebAuthProvider.login(auth0)
                        .withScheme("https")
                        .withScope("openid profile email offline_access")
                        .await(this@MainActivity)
                    // Save the credentials
                    // User is authenticated
                } catch (exception: AuthenticationException) {
                    // Handle error
                }
            }
        }
        ```
      </Tab>
    </Tabs>

    **Implement Logout:** Use WebAuthProvider to clear the user's session.

    <Tabs>
      <Tab title="Kotlin Callback">
        ```kotlin MainActivity.kt lines theme={null}
        private fun logout() {
            WebAuthProvider.logout(auth0)
                .withScheme("https")
                .start(this, object : Callback<Void?, AuthenticationException> {
                    override fun onSuccess(result: Void?) {
                        // Clear saved credentials
                        // User is logged out
                    }

                    override fun onFailure(exception: AuthenticationException) {
                        // Handle error
                    }
                })
        }
        ```
      </Tab>

      <Tab title="Coroutine">
        ```kotlin MainActivity.kt lines theme={null}
        private fun logout() {
            lifecycleScope.launch {
                try {
                    WebAuthProvider.logout(auth0)
                        .withScheme("https")
                        .await(this@MainActivity)
                    // Clear saved credentials
                    // User is logged out
                } catch (exception: AuthenticationException) {
                    // Handle error
                }
            }
        }
        ```
      </Tab>
    </Tabs>

    <Info>
      The `login()` and `logout()` methods should be called when the user taps the respective buttons in your UI. The code uses `this` (referring to the Activity) as the context parameter, which is required for WebAuthProvider to launch Chrome Custom Tabs and handle the authentication flow.
    </Info>
  </Step>

  <Step title="Run your app">
    Build and run your Android application.

    **In Android Studio:**

    ```shellscript theme={null}
    # Sync project with Gradle files (or use Android Studio's "Sync Now")
    ./gradlew clean build

    # Build and install on connected device or emulator
    ./gradlew installDebug

    # Or run directly from Android Studio
    # Click the "Run" button or press Shift+F10
    ```

    **Expected flow:**

    1. App launches with "Log In" button and shield icon
    2. Tap "Log In" → Chrome Custom Tab opens → Complete login
    3. Returns to app automatically
    4. Success!!

    <Warning>
      Android will show a browser selection dialog if multiple browsers are installed. Chrome Custom Tabs provide the best user experience for Auth0 authentication.
    </Warning>
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a fully functional Auth0 login experience running on your Android device or emulator. The app uses Chrome Custom Tabs for secure authentication and automatically stores credentials.
</Check>

***

## Troubleshooting & Advanced

<Accordion title="Common Issues & Solutions">
  ### Chrome Custom Tab doesn't redirect back to app

  **Solutions:**

  1. Check **Allowed Callback URLs** in Auth0 Dashboard match your `applicationId` exactly
  2. Verify manifest placeholders in `build.gradle.kts` are correct
  3. Ensure both HTTPS and custom scheme URLs are configured
  4. Clean and rebuild: **Build** → **Clean Project** → **Rebuild Project**

  ### App crashes: 'Auth0 domain not found'

  **Fix:**

  1. Check `com_auth0_domain` and `com_auth0_client_id` values are correct
  2. Ensure no typos in domain format (should not include `https://`)

  ### Build errors with dependencies

  **Fix:**

  1. Update to latest Android Gradle Plugin in `build.gradle` (project level)
  2. Sync project: **File** → **Sync Project with Gradle Files**
  3. Clean build: `./gradlew clean build`

  ### Authentication cancelled by user

  Handle gracefully in your error callback:

  ```kotlin {3,4,5,6} expandable theme={null}
  override fun onFailure(exception: AuthenticationException) {
      when {
          exception.isAuthenticationCanceled -> 
              showMessage("Login was cancelled")
          exception.isBrowserAppNotAvailable -> 
              showMessage("No browser available")
          else -> 
              showMessage("Login failed: ${exception.getDescription()}")
      }
  }
  ```

  ### No compatible browser error

  * Install Chrome or another modern browser on your device/emulator
  * Enable Chrome Custom Tabs for better user experience
  * Test on real device with Chrome installed
</Accordion>

<Accordion title="Production Deployment">
  ### App Store Preparation

  * Configure Android App Links for seamless authentication
  * Test on multiple Android versions and screen sizes
  * Implement proper error handling for network failures
  * Add ProGuard rules for Auth0 SDK if using code obfuscation
  * Follow Google Play Store policies for authentication flows

  ### Security Considerations

  * Use `SecureCredentialsManager` for production credential storage
  * Implement certificate pinning for additional API security
  * Consider Android Keystore for enhanced credential protection
  * Enable biometric authentication for sensitive operations
</Accordion>

<Accordion title="Advanced Android Integration">
  ### Enhanced Credential Security

  Implement biometric authentication for credential access:

  ```kotlin AuthenticationManager.kt expandable lines theme={null}
  class AuthenticationManager(private val context: Context) {
      
      private val credentialsManager: SecureCredentialsManager
      
      init {
          val authentication = AuthenticationAPIClient(auth0)
          val storage = SharedPreferencesStorage(context)
          credentialsManager = SecureCredentialsManager(context, authentication, storage)
          
          // Enable biometric authentication
          credentialsManager.requireAuthentication(
              context as FragmentActivity,
              REQUEST_CODE_BIOMETRIC,
              "Biometric Authentication",
              "Please authenticate to access your account"
          )
      }
      
      companion object {
          private const val REQUEST_CODE_BIOMETRIC = 321
      }
  }
  ```

  ### Custom Scopes and Audience

  Request specific scopes and audience for your API:

  ```kotlin AuthenticationManager.kt expandable lines theme={null}
  fun login() {
      WebAuthProvider.login(auth0)
          .withScheme("https")
          .withScope("openid profile email offline_access read:posts")
          .withAudience("https://myapi.example.com")
          .withParameter("prompt", "login")
          .start(context as MainActivity, loginCallback)
  }
  ```

  ### Network Configuration

  Handle network security and certificate pinning:

  ```xml app/src/main/res/xml/network_security_config.xml expandable lines theme={null}
  <?xml version="1.0" encoding="utf-8"?>
  <network-security-config>
      <domain-config>
          <domain includeSubdomains="true">your-auth0-domain.auth0.com</domain>
          <pin-set>
              <pin digest="SHA-256">AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=</pin>
          </pin-set>
      </domain-config>
  </network-security-config>
  ```

  Add to `AndroidManifest.xml`:

  ```xml theme={null}
  <application
      android:networkSecurityConfig="@xml/network_security_config"
      ... />
  ```
</Accordion>


# Device Authorization Flow
Source: https://auth0.com/docs/quickstart/native/device/interactive

This tutorial demonstrates how to call your API from an input-constrained device using the Device Authorization Flow.

<Recipe>
  <Content>
    This tutorial demonstrates how to call your API from an input-constrained device using the Device Authorization Flow. We recommend that you log in to
    follow this quickstart with examples configured for your account.

    For an interactive experience, you can use the [Device Flow Playground](https://auth0.github.io/device-flow-playground/).

    <Section title={sections[0].title}>
      * Register a Native Application.
      * Ensure the **OIDC Conformant** toggle is enabled. For more information, read OIDC-Conformant Authentication.
      * Add **Device Code** to the Application's grant types. For more information, read Update Grant Types.
      * Add **Refresh Token** to the Application’s grant types if you want to enable Refresh Tokens.
      * Configure and enable at least one connection for the
        application.
      * Register your API with Auth0.
      * Enable **Allow Offline Access** if you are using refresh tokens. For more information, read API Settings.
      * Configure Device User Code Settings to define the
        character set, format, and length of your randomly-generated user code.
    </Section>

    <Section title={sections[1].title}>
      When the user starts the device application and wants to authorize it, your application must request a device
      code from the Auth0 Authentication API to associate with the user session.

      To get the device code, your application must call the Authentication API Device Authorization Flow [Authorize endpoint](https://auth0.com/docs/api/authentication#-post-oauth-device-code-):

      <AuthCodeGroup>
        ```bash cURL lines theme={null}
        curl --request post \
          --url 'https://{yourDomain}/oauth/device/code' \
          --header 'content-type: application/x-www-form-urlencoded'
        ```

        ```csharp C# lines theme={null}
        var client = new RestClient("https://{yourDomain}/oauth/device/code");
        var request = new RestRequest(Method.POST);
        request.AddHeader("content-type", "application/x-www-form-urlencoded");
        IRestResponse response = client.Execute(request);
        ```

        ```go Go lines  theme={null}
        package main
        import (
        "fmt"
        "net/http"
        "io/ioutil"
        )
        func main() {
        url := "https://{yourDomain}/oauth/device/code"
        req, _ := http.NewRequest("post", url, nil)
        req.Header.Add("content-type", "application/x-www-form-urlencoded")
        res, _ := http.DefaultClient.Do(req)
        defer res.Body.Close()
        body, _ := ioutil.ReadAll(res.Body)
        fmt.Println(res)
        fmt.Println(string(body))
        }
        ```

        ```java Java lines theme={null}
        HttpResponse<String> response = Unirest.post("https://{yourDomain}/oauth/device/code")
          .header("content-type", "application/x-www-form-urlencoded")
          .asString();
        ```

        ```javascript Node.JS lines theme={null}
        var axios = require("axios").default;
        var options = {
        method: 'post',
        url: 'https://{yourDomain}/oauth/device/code',
        headers: {'content-type': 'application/x-www-form-urlencoded'}
        };
        axios.request(options).then(function (response) {
        console.log(response.data);
        }).catch(function (error) {
        console.error(error);
        });
        ```

        ```objc Obj-C lines  theme={null}
        #import <Foundation/Foundation.h>
        NSDictionary *headers = @{ @"content-type": @"application/x-www-form-urlencoded" };
        NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://{yourDomain}/oauth/device/code"]
                                                          cachePolicy:NSURLRequestUseProtocolCachePolicy

                                                      timeoutInterval:10.0];

        [request setHTTPMethod:@"post"];
        [request setAllHTTPHeaderFields:headers];
        NSURLSession *session = [NSURLSession sharedSession];
        NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                                completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {

                                                    if (error) {

                                                        NSLog(@&quot;%@&quot;, error);

                                                    } else {

                                                        NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;

                                                        NSLog(@&quot;%@&quot;, httpResponse);

                                                    }

                                                }];

        [dataTask resume];
        ```

        ```php PHP lines  theme={null}
        $curl = curl_init();
        curl_setopt_array($curl, [
        CURLOPT_URL => "https://{yourDomain}/oauth/device/code",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => "",
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => "post",
        CURLOPT_HTTPHEADER => [
        &quot;content-type: application/x-www-form-urlencoded&quot;

        ],
        ]);
        $response = curl_exec($curl);
        $err = curl_error($curl);
        curl_close($curl);
        if ($err) {
        echo "cURL Error #:" . $err;
        } else {
        echo $response;
        }
        ```

        ```python Python lines theme={null}
        import http.client
        conn = http.client.HTTPSConnection("")
        headers = { 'content-type': "application/x-www-form-urlencoded" }
        conn.request("post", "/{yourDomain}/oauth/device/code", headers=headers)
        res = conn.getresponse()
        data = res.read()
        print(data.decode("utf-8"))
        ```

        ```ruby Ruby lines theme={null}
        require 'uri'
        require 'net/http'
        require 'openssl'
        url = URI("https://{yourDomain}/oauth/device/code")
        http = Net::HTTP.new(url.host, url.port)
        http.use_ssl = true
        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
        request = Net::HTTP::Post.new(url)
        request["content-type"] = 'application/x-www-form-urlencoded'
        response = http.request(request)
        puts response.read_body
        ```

        ```swift Swift lines  theme={null}
        import Foundation
        let headers = ["content-type": "application/x-www-form-urlencoded"]
        let request = NSMutableURLRequest(url: NSURL(string: "https://{yourDomain}/oauth/device/code")! as URL,
                                            cachePolicy: .useProtocolCachePolicy,

                                        timeoutInterval: 10.0)

        request.httpMethod = "post"
        request.allHTTPHeaderFields = headers
        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()
        ```
      </AuthCodeGroup>
    </Section>

    <Section title={sections[2].title}>
      The device application should receive an HTTP 200 response and a payload similar to this:

      ```json lines theme={null}
      {
        "device_code": "GmRh...k9eS",
        "user_code": "WDJB-MJHT",
        "verification_uri": "https://my-tenant.auth0.com/device",
        "verification_uri_complete": "https://my-tenant.auth0.com/device?user_code=WDJB-MJHT",
        "expires_in": 900,
        "interval": 5
      }
      ```
    </Section>

    <Section title={sections[3].title}>
      After your device application receives the `device_code` and the `user_code`, it should
      instruct the user to go to the `verification_uri` and enter the `user_code`.

      <Frame>
        <img />
      </Frame>

      <Info>
        The `device_code` is not intended for the user directly and should not be displayed during
        the interaction to avoid confusing the user.
      </Info>

      <Info>
        When building a CLI, you could skip this step and immediately open the browser with
        `verification_uri_complete`.
      </Info>
    </Section>

    <Section title={sections[4].title}>
      While your device application waits for the user to activate it, it should call the Authentication API [POST /oauth/token endpoint](https://auth0.com/docs/api/authentication#-post-oauth-token-) intermittently
      and handle the response appropriately.

      <Info>
        Ensure your device application waits for the length of the `interval` (in seconds) or until
        it receives a successful response, whichever is longer, to avoid network latency issues.
      </Info>

      ```bash theme={null}
      curl --request POST \ 
        --url 'https://{yourDomain}/oauth/token' \
        --header 'content-type: application/x-www-form-urlencoded' \
        --data grant_type=urn:ietf:params:oauth:grant-type:device_code \
        --data device_code=AUTH0_SCOPES \
        --data 'client_id={yourClientId}'
      ```
    </Section>

    <Section title={sections[5].title}>
      The user will either scan the QR code, or else will open the activation page and enter the user code:

      <Frame>
        <img />
      </Frame>

      A confirmation page will be shown to have the user confirm that this is the right device:

      <Frame>
        <img />
      </Frame>

      The user will complete the transaction by signing in. This step may include one or more of the following
      processes:

      * Authenticating the user
      * Redirecting the user to an Identity Provider to handle authentication
      * Checking for active SSO sessions
      * Obtaining user consent for the device, unless consent has been previously given

      <Frame>
        <img />
      </Frame>

      Upon successful authentication and consent, the confirmation prompt will be shown:

      <Frame>
        <img />
      </Frame>

      At this point, the user has authenticated and the device has been authorized.
    </Section>

    <Section title={sections[6].title}>
      After the user authorizes the device application, it receives an HTTP 200 response and the following payload:

      ```json lines theme={null}
      {
        "access_token": "eyJz93a...k4laUWw",
        "refresh_token": "GEbRxBN...edjnXbL",
        "id_token": "eyJ0XAi...4faeEoQ",
        "token_type": "Bearer",
        "expires_in": 86400
      }
      ```

      <Info>
        You should validate your tokens before saving them. To learn how, read Validate Access Tokens and Validate ID Tokens.
      </Info>

      Access tokens are used to call the Authentication API [Get User Info endpoint](https://auth0.com/docs/api/authentication#get-user-info) (if your device
      application requested the `openid` scope) or the API that was specified by the `audience`
      parameter. If you are calling your own API, your device application must verify the access token before using it.

      ID tokens contain user information that must be [decoded and extracted](/docs/secure/tokens/id-tokens#id-token-payload). The Authentication API
      only returns an `id_token` if your device application requested the `openid` scope.

      Refresh tokens are used to obtain a new access token or
      ID token after the previous one has expired. The Authentication API only returns a `refresh_token` if
      the **Allow Offline Access** setting is enabled for the API specified by the `audience` parameter,
      and your device application requested the `offline_access` scope.
    </Section>

    <Section title={sections[7].title}>
      To call your API, your device application must pass the access token as a Bearer token in the
      `Authorization` header of your HTTP request.

      ```bash lines theme={null}
      curl --request GET \
        --url https://myapi.com/api \
        --header 'authorization: Bearer AUTH0_API_ACCESS_TOKEN' \
        --header 'content-type: application/json'
      ```
    </Section>

    <Section title={sections[8].title}>
      To get a new access token for a user, your device application can call the Authentication API [POST /oauth/token endpoint](https://auth0.com/docs/api/authentication#-post-oauth-token-) with the
      `refresh_token` parameter.

      ```bash lines theme={null}
      curl --request POST \
        --url 'https://{yourDomain}/oauth/token' \
        --header 'content-type: application/x-www-form-urlencoded' \
        --data grant_type=refresh_token \
        --data 'client_id={yourClientId}' \
        --data 'client_secret={yourClientSecret}' \
        --data refresh_token=AUTH0_REFRESH_TOKEN
      ```

      If the request was successful, your device application receives an HTTP 200 response with the following payload:

      ```json lines theme={null}
      {
        "access_token": "eyJ...MoQ",
        "expires_in": 86400,
        "scope": "openid offline_access",
        "id_token": "eyJ...0NE",
        "token_type": "Bearer"
      }
      ```

      To learn more about refresh tokens, read [Refresh Tokens](https://auth0.com/docs/secure/tokens/refresh-tokens).
    </Section>

    <Section title={sections[9].title}>
      Tenant logs are created for any interaction that takes
      place and can be used to troubleshoot issues.

      ### Token responses

      While you wait for the user to authorize the device, you may receive a few different HTTP 4xx responses.

      #### Authorization pending

      You will see this error while waiting for the user to take action. Continue polling using the suggested
      `interval` retrieved in the previous step of this tutorial.

      ```json lines theme={null}
      `HTTP 403`
      {
      "error": "authorization_pending",
      "error_description": "..."
      }
      ```

      #### Slow down

      You are polling too fast. Slow down and use the suggested interval retrieved in the previous step of this
      tutorial. To avoid receiving this error due to network latency, you should start counting each interval after
      receipt of the last polling request's response.

      ```json lines theme={null}
      `HTTP 429`
      {
      "error": "slow_down",
      "error_description": "..."
      }
      ```

      #### Expired token

      The user has not authorized the device quickly enough, so the `device_code` has expired. Your
      application should notify the user that the flow has expired and prompt them to reinitiate the flow.

      <Info>
        The `expired_token` error is returned exactly once. After that, the endpoint returns the
        `invalid_grant` error.
      </Info>

      ```json lines theme={null}
      `HTTP 403`
      {
      "error": "expired_token",
      "error_description": "..."
      }
      ```

      #### Access Denied

      If access is denied, you receive:

      ```json lines theme={null}
      `HTTP 403`
      {
      "error": "access_denied",
      "error_description": "..."
      }
      ```

      This can occur for a variety of reasons, including:

      * The user refused to authorize the device.
      * The authorization server denied the transaction.
      * A configured Action denied access.
    </Section>

    <Section title={sections[10].title}>
      Refer to the samples below to learn how to implement this flow in real-world applications.

      * [Device
        Authorization Playground](https://auth0.github.io/device-flow-playground/)
      * [AppleTV (Swift)](https://github.com/pushpabrol/auth0-device-flow-appletv): Simple application that shows how Auth0 can be used with the
        Device Authorization Flow from an AppleTV.
      * [CLI (Node.js)](https://gist.github.com/panva/652c61e7d847e0ed99926c324fa91b36): Sample implementation of a CLI that uses the Device
        Authorization Flow instead of the Authorization Code Flow. The major difference is that your CLI does not need
        to host a webserver and listen on a port.
    </Section>

    <Section title={sections[11].title}>
      To use the Device Authorization Flow, a device application must:

      * Support Server Name Indication (SNI)
      * Be a Native Application
      * Have the [Authentication Method](/docs/secure/application-credentials#application-authentication-methods) set to **None**
      * Be [OIDC-conformant](/docs/get-started/applications/application-settings#oauth)
      * Not be created through Dynamic Client Registration

      In addition, the Device Authorization Flow does not allow:

      * Social Connections using Auth0 developer keys unless you are using New Universal Login Experience
      * Query string parameters to be accessed from a hosted login page or Actions.
    </Section>

    ## Next Steps

    Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.

    This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:

    * [Auth0 Dashboard](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq) - Learn how to configure and manage your Auth0 tenant and applications
    * [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
  </Content>

  <SideMenu>
    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>
  </SideMenu>
</Recipe>


# Add Login to Your Flutter Application
Source: https://auth0.com/docs/quickstart/native/flutter/index

This guide demonstrates how to integrate Auth0 with any Flutter app using the Auth0 Flutter SDK.

This guide demonstrates how to integrate Auth0 with a Flutter application using the [Auth0 Flutter SDK](https://github.com/auth0/auth0-flutter). This guide covers setup for **Android**, **iOS**, **macOS**, and **Web** platforms.

## Get Started

<Steps>
  <Step title="Create a new Flutter project">
    Create a new Flutter project for this quickstart.

    **In your terminal:**

    1. Navigate to your workspace directory
    2. Run: `flutter create auth0_flutter_sample`
    3. Navigate into the project: `cd auth0_flutter_sample`
    4. Open in your IDE:
       * **VS Code**: `code .`
       * **Android Studio**: `open -a "Android Studio" .`

    ```shellscript theme={null}
    # Create new Flutter project
    flutter create auth0_flutter_sample

    # Navigate into project directory
    cd auth0_flutter_sample

    # Open in VS Code
    code .
    ```

    <Tip>
      This creates a modern Flutter app with the latest project structure. Run `flutter doctor` to verify your environment is set up correctly.
    </Tip>
  </Step>

  <Step title="Install the Auth0 Flutter SDK">
    Add the Auth0 Flutter SDK to your project using the Flutter CLI.

    ```shellscript theme={null}
    flutter pub add auth0_flutter
    ```

    This will add `auth0_flutter` to your `pubspec.yaml` dependencies:

    ```yaml pubspec.yaml lines theme={null}
    dependencies:
      auth0_flutter: ^2.0.0-beta.1
    ```

    <Tip>
      The Auth0 Flutter SDK requires **Flutter 3.24.0+** and **Dart 3.5.0+**. Run `flutter doctor` to verify your environment meets these requirements.
    </Tip>
  </Step>

  <Step title="Setup your Auth0 App">
    Next up, you need to create a new app on your Auth0 tenant and configure the callback URLs.

    1. Head to the [Auth0 Dashboard](https://manage.auth0.com/dashboard/)
    2. Click on **Applications** > **Applications** > **Create Application**
    3. In the popup, enter a name for your app, select `Native` as the app type (or `Single Page Application` for web-only) and click **Create**
    4. Switch to the **Settings** tab on the Application Details page
    5. Note down the **Domain** and **Client ID** values - you'll need these later

    On the **Settings** tab, configure the following URLs based on your target platform(s):

    **Allowed Callback URLs:**

    <Tabs>
      <Tab title="Android">
        ```text theme={null}
        https://{yourDomain}/android/{yourPackageName}/callback
        ```
      </Tab>

      <Tab title="iOS">
        ```text theme={null}
        https://{yourDomain}/ios/{yourBundleIdentifier}/callback,
        {yourBundleIdentifier}://{yourDomain}/ios/{yourBundleIdentifier}/callback
        ```
      </Tab>

      <Tab title="macOS">
        ```text theme={null}
        https://{yourDomain}/macos/{yourBundleIdentifier}/callback,
        {yourBundleIdentifier}://{yourDomain}/macos/{yourBundleIdentifier}/callback
        ```
      </Tab>

      <Tab title="Web">
        ```text theme={null}
        http://localhost:3000
        ```
      </Tab>
    </Tabs>

    **Allowed Logout URLs:**

    Add the same URLs from the callback configuration above to the **Allowed Logout URLs** field.

    **Allowed Web Origins (Web Only):**

    If targeting the web platform, add your application URL:

    ```text theme={null}
    http://localhost:3000
    ```

    <Info>
      **Allowed Callback URLs** are a critical security measure to ensure users are safely returned to your application after authentication. Without a matching URL, the login process will fail.

      **Allowed Logout URLs** are essential for providing a seamless user experience upon signing out. Without a matching URL, users will not be redirected back to your application after logout.

      For example, if your Auth0 domain is `example.us.auth0.com` and your Android package name is `com.example.myapp`, your Android callback URL would be: `https://example.us.auth0.com/android/com.example.myapp/callback`
    </Info>

    <Warning>
      **Important**: Ensure the package name (Android) or bundle identifier (iOS/macOS) in your callback URLs matches your actual app identifier. If authentication fails, verify these values are identical.
    </Warning>
  </Step>

  <Step title="Configure Your Application">
    Platform-specific configuration is required to enable the authentication flow. Follow the instructions for each platform you're targeting.

    <Tabs>
      <Tab title="Android">
        Open the `android/app/build.gradle` file and add the following manifest placeholders inside `android > defaultConfig`:

        ```groovy android/app/build.gradle lines theme={null}
        android {
            // ...
            defaultConfig {
                // Add the following line
                manifestPlaceholders += [auth0Domain: "{yourDomain}", auth0Scheme: "https"]
            }
            // ...
        }
        ```

        Replace `{yourDomain}` with your Auth0 domain (e.g., `example.us.auth0.com`).

        **https scheme**

        To use `https` scheme for your callback url, set up [Android app links](https://auth0.com/docs/get-started/applications/enable-android-app-links-support) for your application.

        **For Biometric Authentication (Optional):**

        If you plan to use biometric authentication, update your `MainActivity.kt` to extend `FlutterFragmentActivity`:

        ```kotlin android/app/src/main/kotlin/.../MainActivity.kt lines theme={null}
        import io.flutter.embedding.android.FlutterFragmentActivity

        class MainActivity: FlutterFragmentActivity() {
        }
        ```
      </Tab>

      <Tab title="iOS">
        To use Universal Links (HTTPS callback URLs) on iOS 17.4+, configure an Associated Domain:

        1. Open your app in Xcode: `open ios/Runner.xcworkspace`
        2. Select the **Runner** target and go to **Signing & Capabilities**
        3. Click **+ Capability** and add **Associated Domains**
        4. Add the entry: `webcredentials:{yourDomain}`
        5. In the [Auth0 Dashboard](https://manage.auth0.com/#/applications), go to **Settings > Advanced Settings > Device Settings**
        6. In the **iOS** section, set your **Team ID** and **App ID** (bundle identifier)

        <Info>
          Universal Links configuration is optional. Skip this if you don't need Universal Links support - the SDK will fall back to custom URL schemes automatically.
        </Info>
      </Tab>

      <Tab title="macOS">
        Follow the same steps as iOS, but open `macos/Runner.xcworkspace` instead.
      </Tab>

      <Tab title="Web">
        Add the following script tag to your `web/index.html` file, inside the `head` section:

        ```html web/index.html lines theme={null}
        <head>
          <!-- ... other head content ... -->
          <script src="https://cdn.auth0.com/js/auth0-spa-js/2.9/auth0-spa-js.production.js" defer></script>
        </head>
        ```
      </Tab>
    </Tabs>

    <Warning>
      **Android**: Ensure the `auth0Domain` value matches your Auth0 domain exactly. If authentication fails, verify this value is identical to the domain shown in your Auth0 Dashboard.

      **iOS/macOS**: Universal Links require a paid Apple Developer account and iOS 17.4+/macOS 14.4+. On older versions, the SDK automatically falls back to custom URL schemes.
    </Warning>
  </Step>

  <Step title="Implement Login and Logout">
    [Universal Login](https://auth0.com/docs/authenticate/login/auth0-universal-login) is the easiest way to set up authentication in your application. We recommend using it for the best experience, best security, and the fullest array of features.

    **Implement Login:**

    <Tabs>
      <Tab title="Mobile/macOS">
        Import the Auth0 Flutter SDK and create an `Auth0` instance:

        ```dart lib/auth_service.dart lines theme={null}
        import 'package:auth0_flutter/auth0_flutter.dart';

        class AuthService {
          final auth0 = Auth0('{yourDomain}', '{yourClientId}');
          
          Future<Credentials> login() async {
            final credentials = await auth0.webAuthentication().login(useHTTPS: true);
            
            // Access token -> credentials.accessToken
            // ID token -> credentials.idToken
            // User profile -> credentials.user
            
            return credentials;
          }
        }
        ```
      </Tab>

      <Tab title="Web">
        Import the web-specific SDK and handle the authentication flow:

        ```dart lib/web_auth_service.dart lines theme={null}
        import 'package:auth0_flutter/auth0_flutter_web.dart';

        class WebAuthService {
          final auth0Web = Auth0Web('{yourDomain}', '{yourClientId}');
          
          Future<void> initialize() async {
            // Call onLoad() during app initialization to handle redirect callback
            final credentials = await auth0Web.onLoad();
            
            if (credentials != null) {
              // User is already logged in
              // Access token -> credentials.accessToken
              // User profile -> credentials.user
            }
          }
          
          Future<void> login() async {
            await auth0Web.loginWithRedirect(redirectUrl: 'http://localhost:3000');
          }
        }
        ```
      </Tab>
    </Tabs>

    **Implement Logout:**

    <Tabs>
      <Tab title="Mobile/macOS">
        ```dart lib/auth_service.dart lines theme={null}
        Future<void> logout() async {
          await auth0.webAuthentication().logout(useHTTPS: true);
          
          // User is now logged out
          // Credentials have been cleared from secure storage
        }
        ```
      </Tab>

      <Tab title="Web">
        ```dart lib/web_auth_service.dart lines theme={null}
        Future<void> logout() async {
          await auth0Web.logout(returnToUrl: 'http://localhost:3000');
        }
        ```
      </Tab>
    </Tabs>

    <Info>
      **iOS/macOS**: The `useHTTPS: true` parameter enables Universal Links on iOS 17.4+ and macOS 14.4+ for enhanced security.

      **Android**:  if you are using a custom scheme, pass this scheme to the login method so that the SDK can route to the login page and back again correctly:

      ```kotlin lib/auth_service.dart lines theme={null}
      await auth0.webAuthentication(scheme: 'YOUR CUSTOM SCHEME').login();
      ```

      **Web**: You must call `onLoad()` when your application starts. This handles the redirect callback from Auth0 and restores the user's session if they're already authenticated.
    </Info>
  </Step>

  <Step title="Show User Profile Information">
    The user profile is automatically retrieved when the user logs in. The `Credentials` object contains a `user` property with all the user profile information, populated by decoding the ID token.

    ```dart lib/profile_screen.dart lines theme={null}
    void displayUserProfile(Credentials credentials) {
      final user = credentials.user;
      
      print('User ID: ${user.sub}');
      print('Email: ${user.email}');
      print('Name: ${user.name}');
      print('Picture: ${user.pictureUrl}');
      print('Nickname: ${user.nickname}');
    }
    ```

    <Tip>
      Request the appropriate scopes during login to access specific user profile fields. The default scopes are `openid`, `profile`, `email`, and `offline_access`.
    </Tip>
  </Step>

  <Step title="Run your app">
    Build and run your Flutter application.

    **In your terminal:**

    ```shellscript theme={null}
    # List available devices
    flutter devices

    # Run on Android
    flutter run -d android

    # Run on iOS Simulator
    flutter run -d ios

    # Run on Web (use port 3000 to match callback URLs)
    flutter run -d chrome --web-port 3000
    ```

    **Expected flow:**

    1. App launches with your login UI
    2. User taps **Log In** → Browser/Custom Tab opens with Auth0 Universal Login
    3. User completes authentication
    4. Browser redirects back to your app
    5. User is now authenticated and credentials are stored

    <Warning>
      Make sure to use port `3000` when running the web app to match the callback URLs configured in Auth0. You can change this port, but ensure it matches your Auth0 configuration.
    </Warning>
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a fully functional Auth0 login experience in your Flutter application. The app uses secure browser-based authentication and automatically stores credentials for session persistence.
</Check>

***

## Troubleshooting & Advanced Usage

<Accordion title="Common Issues & Solutions">
  ### Callback URL Mismatch

  **Symptom**: Error "redirect\_uri\_mismatch" or authentication fails silently.

  **Solutions:**

  1. Check **Allowed Callback URLs** in Auth0 Dashboard match your app configuration exactly
  2. Verify the scheme (`https://` vs `http://`)
  3. Ensure the package name (Android) or bundle identifier (iOS/macOS) is correct
  4. Check for trailing slashes

  ### Android: Chrome Custom Tab Doesn't Open

  **Symptom**: Nothing happens when calling `login()`.

  **Fix:**

  1. Verify `manifestPlaceholders` are correctly set in `build.gradle`
  2. Ensure internet permission is in `AndroidManifest.xml`:
     ```xml theme={null}
     <uses-permission android:name="android.permission.INTERNET" />
     ```
  3. Check that Chrome or another browser is installed on the device

  ### iOS: "Open in App" Alert

  **Symptom**: Alert box appears asking to open in your app.

  **Fix:** This is expected behavior with `ASWebAuthenticationSession`. To remove it:

  * Use Universal Links (requires iOS 17.4+ and paid Apple Developer account)
  * Or set `useEphemeralSession: true` (disables SSO):

  ```dart expandable theme={null}
  await auth0.webAuthentication().login(
    useHTTPS: true,
    useEphemeralSession: true,
  );
  ```

  ### Web: User Logged Out on Page Refresh

  **Symptom**: User appears logged out after refreshing the page.

  **Fix:**

  1. Ensure `onLoad()` is called during app initialization
  2. Try using `localStorage` for cache location:
     ```dart expandable theme={null}
     final auth0Web = Auth0Web(
       '{yourDomain}',
       '{yourClientId}',
       cacheLocation: CacheLocation.localStorage,
     );
     ```
  3. Ensure your domain is added to **Allowed Web Origins** in Auth0 Dashboard

  ### Web: "Must run on a secure origin" Error

  **Symptom**: Error about secure origin in browser console.

  **Fix:** The Auth0 SPA SDK requires a secure context. Use `localhost` (which is treated as secure) or deploy to an HTTPS domain.

  ### Authentication cancelled by user

  Handle gracefully in your error handling:

  ```dart expandable theme={null}
  try {
    final credentials = await auth0.webAuthentication().login(useHTTPS: true);
    // Handle successful login
  } on WebAuthenticationException catch (e) {
    if (e.code == 'USER_CANCELLED') {
      showMessage('Login was cancelled');
    } else {
      showMessage('Login failed: ${e.message}');
    }
  }
  ```
</Accordion>

<Accordion title="Handling Credentials">
  The Auth0 Flutter SDK includes a built-in Credentials Manager that securely stores user credentials. On mobile platforms, credentials are encrypted and stored in the platform's secure storage (Keychain on iOS/macOS, encrypted SharedPreferences on Android).

  ### Check for Stored Credentials

  Before prompting the user to log in, check if valid credentials already exist:

  ```dart lib/auth_service.dart expandable lines theme={null}
  Future<bool> checkAuthentication() async {
    if (kIsWeb) {
      return await auth0Web.hasValidCredentials();
    } else {
      return await auth0.credentialsManager.hasValidCredentials();
    }
  }
  ```

  ### Retrieve Stored Credentials

  Retrieve credentials to access tokens or user information. The Credentials Manager automatically refreshes expired tokens when possible:

  ```dart lib/auth_service.dart expandable lines theme={null}
  Future<Credentials> getCredentials() async {
    if (kIsWeb) {
      return await auth0Web.credentials();
    } else {
      return await auth0.credentialsManager.credentials();
    }
  }
  ```

  <Tip>
    You don't need to manually store credentials after login—the SDK handles this automatically. You also don't need to manually refresh tokens; the Credentials Manager refreshes them when needed.
  </Tip>
</Accordion>

<Accordion title="Error Handling">
  Handle authentication errors gracefully to provide a good user experience.

  ### Mobile/macOS Errors

  ```dart lib/auth_service.dart expandable lines theme={null}
  import 'package:auth0_flutter/auth0_flutter.dart';

  Future<void> login() async {
    try {
      final credentials = await auth0.webAuthentication().login(useHTTPS: true);
      // Handle successful login
    } on WebAuthenticationException catch (e) {
      if (e.code == 'USER_CANCELLED') {
        // User cancelled the login
        print('Login cancelled by user');
      } else {
        // Handle other errors
        print('Login error: ${e.message}');
      }
    }
  }

  Future<Credentials> getCredentials() async {
    try {
      return await auth0.credentialsManager.credentials();
    } on CredentialsManagerException catch (e) {
      if (e.isNoCredentialsFound) {
        // No stored credentials, user needs to log in
        throw Exception('Please log in first');
      } else if (e.isTokenRenewFailed) {
        // Refresh token expired, re-authentication required
        return await auth0.webAuthentication().login(useHTTPS: true);
      }
      rethrow;
    }
  }
  ```

  ### Web Errors

  ```dart lib/web_auth_service.dart expandable lines theme={null}
  import 'package:auth0_flutter/auth0_flutter_web.dart';

  Future<void> login() async {
    try {
      await auth0Web.loginWithRedirect(redirectUrl: 'http://localhost:3000');
    } on WebException catch (e) {
      print('Login error: ${e.message}');
    }
  }
  ```
</Accordion>

<Accordion title="Advanced Flutter Integration">
  ### Enhanced Credential Security with Biometrics

  Implement biometric authentication for credential access on mobile:

  ```dart lib/secure_auth_service.dart expandable lines theme={null}
  class SecureAuthService {
    final auth0 = Auth0('{yourDomain}', '{yourClientId}');
    
    Future<void> enableBiometrics() async {
      // Enable local authentication (Face ID, Touch ID, Fingerprint)
      await auth0.credentialsManager.enableLocalAuthentication(
        title: 'Authenticate to access your account',
        cancelTitle: 'Cancel',
        fallbackTitle: 'Use passcode',
      );
    }
    
    Future<Credentials> getCredentialsWithBiometrics() async {
      // This will now require biometric authentication
      return await auth0.credentialsManager.credentials();
    }
  }
  ```

  <Info>
    **Android**: Requires `MainActivity` to extend `FlutterFragmentActivity` as configured in Step 4.

    **iOS/macOS**: Requires adding `NSFaceIDUsageDescription` to your `Info.plist`.
  </Info>

  ### Custom Scopes and Audience

  Request specific scopes and audience for your API:

  ```dart lib/auth_service.dart expandable lines theme={null}
  Future<Credentials> loginWithCustomScopes() async {
    return await auth0.webAuthentication().login(
      useHTTPS: true,
      scopes: {'openid', 'profile', 'email', 'offline_access', 'read:posts'},
      audience: 'https://myapi.example.com',
      parameters: {'prompt': 'login'},
    );
  }
  ```

  ### Organizations (B2B/Enterprise)

  Authenticate users within a specific organization:

  ```dart lib/auth_service.dart expandable lines theme={null}
  Future<Credentials> loginWithOrganization(String organizationId) async {
    return await auth0.webAuthentication().login(
      useHTTPS: true,
      organizationId: organizationId,
    );
  }

  // Or prompt user to select an organization
  Future<Credentials> loginWithOrganizationName(String organizationName) async {
    return await auth0.webAuthentication().login(
      useHTTPS: true,
      organizationName: organizationName,
    );
  }
  ```
</Accordion>

<Accordion title="Production Deployment">
  ### App Store Preparation

  * Configure Universal Links (iOS) and App Links (Android) for seamless authentication
  * Test on multiple device sizes and OS versions
  * Implement proper error handling for network failures
  * Add ProGuard rules for Android if using code obfuscation
  * Follow platform-specific App Store/Play Store policies

  ### Security Considerations

  * Use the built-in Credentials Manager for production credential storage
  * Enable biometric authentication for sensitive operations
  * Consider certificate pinning for additional API security
  * Implement proper token refresh handling
  * Use `useHTTPS: true` for Universal Links on supported platforms
</Accordion>

***

## Next Steps

Check out the [EXAMPLES.md](https://github.com/auth0/auth0-flutter/blob/main/auth0_flutter/EXAMPLES.md) file in the SDK repository for comprehensive code examples covering advanced scenarios like DPoP, biometric authentication, passwordless login and many more features.


# Add Login to Your Ionic Angular with Capacitor Application
Source: https://auth0.com/docs/quickstart/native/ionic-angular/interactive

This guide demonstrates how to integrate Auth0 with an Ionic (Angular) & Capacitor application using the Auth0 Angular SDK.

<QuickstartButtons />

<Recipe>
  <Content>
    Auth0 allows you to quickly add authentication and access user profile information in your application. This guide
    demonstrates how to integrate Auth0 with an Ionic (Angular) & Capacitor application using the [Auth0 Angular SDK](https://github.com/auth0/auth0-angular).

    <Section title={sections[0].title}>
      This quickstart assumes you already have an [Ionic](https://ionicframework.com/) application up and running with [Capacitor](https://capacitorjs.com/). If not, check out the [Using
      Capacitor with Ionic Framework guide](https://capacitorjs.com/docs/getting-started/with-ionic) to get started with a simple app, or clone [our sample
      apps](https://github.com/auth0-samples/auth0-ionic-samples).

      You should also be familiar with the [Capacitor development workflow](https://capacitorjs.com/docs/basics/workflow).
    </Section>

    <Section title={sections[1].title}>
      To use Auth0 services, you need to have an application set up in the Auth0 Dashboard. The Auth0 application is
      where you will configure how you want authentication to work for your project.

      <Info>
        Throughout this article, `YOUR_PACKAGE_ID` is your application's package ID. This can be
        found and configured in the `appId` field in your `capacitor.config.ts` file. See
        [Capacitor's Config schema](https://capacitorjs.com/docs/config#schema) for more info.
      </Info>

      ### Configure an application

      Use the interactive selector to create a new Auth0 application or select an existing application that represents
      the project you want to integrate with. Every application in Auth0 is assigned an alphanumeric, unique client ID
      that your application code will use to call Auth0 APIs through the SDK.

      Any settings you configure using this quickstart will automatically update for your application in the [Dashboard](https://manage.auth0.com/#/), which is where you
      can manage your applications in the future.

      If you would rather explore a complete configuration, you can view a sample application instead.

      ### Configure Callback URLs

      A callback URL is a URL in your application that you would like Auth0 to redirect users to after they have
      authenticated. If not set, users will not be returned to your application after they log in.

      <Info>
        If you are following along with our sample project, set this to:

        `YOUR_PACKAGE_ID://{yourDomain}/capacitor/YOUR_PACKAGE_ID/callback`
      </Info>

      ### Configure Logout URLs

      A logout URL is a URL in your application that you would like Auth0 to redirect users to after they have logged
      out. If not set, users will not be able to log out from your application and will receive an error.

      <Info>
        If you are following along with our sample project, set this to:

        `YOUR_PACKAGE_ID://{yourDomain}/capacitor/YOUR_PACKAGE_ID/callback`
      </Info>

      ### Configure Allowed Origins

      To be able to make requests from your native application to Auth0, set the following **Allowed Origins** in
      your [Application Settings](https://manage.auth0.com/#/applications/\{yourClientId}/settings).

      <Info>
        If you are following along with our sample project, set this to
        `capacitor://localhost, http://localhost` for iOS and Android respectively.
      </Info>

      Lastly, be sure that the **Application Type** for your application is set to **Native** in the [Application Settings](https://manage.auth0.com/#/applications/\{yourClientId}/settings).
    </Section>

    <Section title={sections[2].title}>
      Run the following command within your project directory to install the Auth0 Angular SDK:

      ```bash theme={null}
      npm install @auth0/auth0-angular
      ```

      The SDK exposes several types that help you integrate Auth0 with your Angular application idiomatically,
      including a module and an authentication service.

      ### Install Capacitor plugins

      This quickstart and sample make use of some of Capacitor's official plugins. Install these into your app using
      the following command:

      ```bash theme={null}
      npm install @capacitor/browser @capacitor/app
      ```

      * [@capacitor/browser](https://capacitorjs.com/docs/apis/browser): Allows you to interact with the device's
        system browser and is used to open the URL to Auth0's authorization endpoint.
      * [@capacitor/app](https://capacitorjs.com/docs/apis/app): Allows you to subscribe to high-level app events,
        useful for handling callbacks from Auth0.

      <Info>
        Capacitor's Browser plugin on iOS uses [SFSafariViewController](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller), which on iOS 11+ does not share
        cookies with Safari on the device. This means that SSO will not work on those devices. If you need
        SSO, please instead use a compatible plugin that uses [ASWebAuthenticationSession](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession).
      </Info>
    </Section>

    <Section title={sections[3].title}>
      The SDK exports `AuthModule`, a module that contains all the services required for the SDK to
      function. This module should be registered with your application and be configured with your Auth0 domain and
      Client ID.

      The `AuthModule.forRoot` function takes the following configuration:

      * `domain`: The `domain` value present under the \*\*Settings \*\*of the application you
        created in the Auth0 Dashboard, or your custom domain if you are using Auth0's custom domains feature.
      * `clientId`: The Client ID value present under the \*\*Settings \*\*of the application you created
        in the Auth0 Dashboard.
      * `useRefreshTokens`: To use auth0-angular with Ionic on Android and iOS, it's required to enable
        refresh tokens.
      * `useRefreshTokensFallback`: To use auth0-angular with Ionic on Android and iOS, it's required to
        disable the iframe fallback.
      * `authorizationParams.redirect_uri`: The URL to redirect your users after they authenticate with
        Auth0.

      <Info>
        To persist authentication after closing and reopening the application, you may want to set
        `cacheLocation` to `localstorage` when configuring the SDK, but please be aware of
        [the risks of
        storing tokens in localstorage](/docs/libraries/auth0-single-page-app-sdk#change-storage-options). Also, localstorage should be treated as **transient** in
        Capacitor app as the data might be recovered unexpectedly in certain circumstances. Please read the [guidance on storage in the Capacitor docs](https://capacitorjs.com/docs/guides/storage#why-cant-i-just-use-localstorage-or-indexeddb).

        Additionally, the SDK has the ability to [use a custom cache implementation](https://github.com/auth0/auth0-spa-js/blob/master/EXAMPLES.md#creating-a-custom-cache) to store tokens, if
        you have a requirement to use a more secure and persistent storage mechanism.

        **Note** that we recommend **against** using [Capacitor's Storage plugin](https://capacitorjs.com/docs/apis/storage) to store tokens, as this is
        backed by [UserDefaults](https://developer.apple.com/documentation/foundation/userdefaults) and [SharedPreferences](https://developer.android.com/reference/android/content/SharedPreferences) on iOS and Android respectively. Data stored using
        these APIs is not encrypted, not secure, and could also be synced to the cloud.
      </Info>

      <Note>
        ##### Checkpoint

        Now that you have configured your app with the Auth0 Angular SDK, run your application to verify that the
        SDK is initializing without error, and that your application runs as it did before.
      </Note>
    </Section>

    <Section title={sections[4].title}>
      In a Capacitor application, the [Capacitor's Browser plugin](https://capacitorjs.com/docs/apis/browser) performs a redirect to the Auth0 [Universal Login Page](https://auth0.com/universal-login). Set the `openUrl`
      parameter on the `loginWithRedirect` function to use `Browser.open` so that the URL is
      opened using the device's system browser component ([SFSafariViewController](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller) on iOS, and [Chrome
      Custom Tabs](https://developer.chrome.com/docs/android/custom-tabs) on Android).

      <Info>
        By default, the SDK's `loginWithRedirect` method uses `window.location.href` to
        navigate to the login page in the default browser application on the user's device rather than the
        system browser component appropriate for the platform. The user would leave your application to
        authenticate and could make for a suboptimal user experience.
      </Info>

      <Note>
        ##### Checkpoint

        The `loginWithRedirect` function tells the SDK to initiate the login flow, using the
        `Browser.open` function to open the login URL with the platform's system browser component by
        setting the `openUrl` parameter. This provides a way for your user to log in to your
        application. Users redirect to the login page at Auth0 and do not receive any errors.
      </Note>
    </Section>

    <Section title={sections[5].title}>
      Once users logs in with the Universal Login Page, they redirect back to your app via a URL with a custom URL
      scheme. The `appUrlOpen` event must be handled within your app. You can call the
      `handleRedirectCallback` method from the Auth0 SDK to initialize the authentication state.

      You can only use this method on a redirect from Auth0. To verify success, check for the presence of the
      `code` and `state` parameters in the URL.

      The `Browser.close()` method should close the browser when this event is raised.

      Note that the `appUrlOpen` event callback is wrapped in `ngZone.run`. Changes to
      observables that occur when `handleRedirectCallback` runs are picked up by the Angular app. To learn
      more, read [Using
      Angular with Capacitor](https://capacitorjs.com/docs/guides/angular). Otherwise, the screen doesn't update to show the authenticated state after log in.

      <Info>
        This article assumes you will be using Custom URL Schemes to handle the callback within your
        application. To do this, register your `YOUR_PACKAGE_ID` as a URL scheme for your chosen
        platform. To learn more, read [Defining a Custom URL Scheme](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) for iOS, or [Create Deep Links to App Content](https://developer.android.com/training/app-links/deep-linking) for Android.
      </Info>

      <Note>
        ##### Checkpoint

        Add the `appUrlOpen` to your application's `App` component and log in. The browser
        window should close once the user authenticates and logs in to your app.
      </Note>
    </Section>

    <Section title={sections[6].title}>
      Now that users can log in, you need to configure a way to log
      out. Users must redirect to the Auth0 logout endpoint in the browser to clear their browser session. Again,
      Capacitor's Browser plugin should perform this redirect so that the user does not leave your app and receive a
      suboptimal experience.

      To achieve this with Ionic and Capacitor in conjunction with the Auth0 SDK:

      * Construct the URL for your app Auth0 should use to redirect to after logout. This is a URL that uses your
        registered custom scheme and Auth0 domain. Add it to your \*\*Allowed Logout URLs \*\*configuration in the
        Auth0 Dashboard
      * Logout from the SDK by calling `logout`, and pass your redirect URL back as the
        `logoutParams.returnTo` parameter.
      * Set the `openUrl` parameter to a callback that uses the Capacitor browser plugin to open the URL
        using `Browser.open`.

      <Info>
        Similar to the login step, if you do not set `openUrl` when calling `logout`, the
        SDK redirects the user to the logout URL using the default browser application on the device, which
        provides a suboptimal user experience.
      </Info>

      <Note>
        ##### Checkpoint

        Provide a way for your users to log out of your application. Verify the redirect to Auth0 and then to the
        address you specified in the `returnTo` parameter. Make sure users are no longer logged in to
        your application.
      </Note>
    </Section>

    <Section title={sections[7].title}>
      The Auth0 SDK retrieves the profile information
      associated with logged-in users in whatever component you need, such as their name or profile picture, to
      personalize the user interface. The profile information is available through the `user$` property
      exposed by `AuthService`.

      <Note>
        ##### Checkpoint

        Provide a way for your users to see their user profile details within the app and verify you are able to
        retrieve and see your profile information on screen once you have logged in.
      </Note>
    </Section>

    ## Next Steps

    Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.

    This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:

    * [Auth0 Dashboard](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq) - Learn how to configure and manage your Auth0 tenant and applications
    * [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
  </Content>

  <SideMenu>
    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```ts app.module.ts lines  theme={null}
        // Import the types from the SDK
        import { AuthModule } from '@auth0/auth0-angular';
        import config from '../../capacitor.config';

        // ..

        // Build the URL that Auth0 should redirect back to
        const redirect_uri = `${config.appId}://{yourDomain}/capacitor/${config.appId}/callback`;

        // Register AuthModule with your AppModule
        @NgModule({
          declarations: [AppComponent],
          entryComponents: [],
          imports: [
            BrowserModule,
            IonicModule.forRoot(),
            AppRoutingModule,
            AuthModule.forRoot({
              domain: "{yourDomain}",
              clientId: "{yourClientId}",
              useRefreshTokens: true,
              useRefreshTokensFallback: false,
              authorizationParams: {
                redirect_uri
              }
            }),
          ],
          providers: [{ provide: RouteReuseStrategy, useClass: IonicRouteStrategy }],
          bootstrap: [AppComponent],
        })
        ```

        ```ts app.component.ts lines  theme={null}
        import { Component, OnInit, NgZone } from '@angular/core';
        import { AuthService } from '@auth0/auth0-angular';
        import { mergeMap } from 'rxjs/operators';
        import { Browser } from '@capacitor/browser';
        import { App } from '@capacitor/app';

        const callbackUri = `${config.appId}://{yourDomain}/capacitor/${config.appId}/callback`;

        @Component({
          selector: 'app-root',
          templateUrl: 'app.component.html',
          styleUrls: ['app.component.scss'],
        })
        export class AppComponent implements OnInit {
          // Import the AuthService module from the Auth0 Angular SDK
          constructor(public auth: AuthService, private ngZone: NgZone) {}

          ngOnInit(): void {
            // Use Capacitor's App plugin to subscribe to the `appUrlOpen` event
            App.addListener('appUrlOpen', ({ url }) => {
              // Must run inside an NgZone for Angular to pick up the changes
              // https://capacitorjs.com/docs/guides/angular
              ngZone.run(() => {
                if (url?.startsWith(callbackUri)) {
                  // If the URL is an authentication callback URL..
                  if (
                    url.includes('state=') &&
                    (url.includes('error=') || url.includes('code='))
                  ) {
                    // Call handleRedirectCallback and close the browser
                    this.auth
                      .handleRedirectCallback(url)
                      .pipe(mergeMap(() => Browser.close()))
                      .subscribe();
                  } else {
                    Browser.close();
                  }
                }
              });
            });
          }
        }
        ```

        ```ts login-button.ts lines  theme={null}
        import { Component, OnInit } from '@angular/core';
        import { AuthService } from '@auth0/auth0-angular';
        import { Browser } from '@capacitor/browser';
        import { mergeMap } from 'rxjs/operators';

        @Component({
          selector: 'app-login-button',
          template: `<ion-button (click)="login()">Login</ion-button>`,
        })
        export class LoginButtonComponent {
          constructor(public auth: AuthService) {}

          login() {
            this.auth
              .loginWithRedirect({
                async openUrl(url: string) {
                  await Browser.open({ url, windowName: '_self' });
                }
              })
              .subscribe();
          }
        }
        ```

        ```ts logout-button.ts lines  theme={null}
        import { Component, OnInit } from '@angular/core';
        import { AuthService } from '@auth0/auth0-angular';
        import { Browser } from '@capacitor/browser';
        import { tap } from 'rxjs/operators';

        // Build the URL to return back to your app after logout
        const returnTo = `${config.appId}://{yourDomain}/capacitor/${config.appId}/callback`;

        @Component({
          selector: 'app-logout-button',
          template: `<ion-button (click)="logout()">Log out</ion-button>`,
        })
        export class LogoutButtonComponent {
          // Import the AuthService module from the Auth0 Angular SDK
          constructor(public auth: AuthService) {}

           logout() {
            this.auth
              .logout({ 
                logoutParams: {
                  returnTo,
                },
                async openUrl(url: string) {
                  await Browser.open({ url });
                } 
              })
              .subscribe();
          }
        }
        ```

        ```ts user-profile.ts lines  theme={null}
        import { Component, OnInit } from '@angular/core';
        import { AuthService } from '@auth0/auth0-angular';

        @Component({
          selector: 'app-profile',
          template: `
          <div *ngIf="auth.user$ | async as user">
            <ion-avatar class="avatar">
              <img [src]="user.picture" [alt]="user.name" />
            </ion-avatar>
            <h2>{{ user.name }}</h2>
            <p>{{ user.email }}</p>
          </div>`,
        })
        export class ProfileComponent {
          constructor(public auth: AuthService) {}
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```ts login-button.ts lines  theme={null}
        import { Component, OnInit } from '@angular/core';
        import { AuthService } from '@auth0/auth0-angular';
        import { Browser } from '@capacitor/browser';
        import { mergeMap } from 'rxjs/operators';

        @Component({
          selector: 'app-login-button',
          template: `<ion-button (click)="login()">Login</ion-button>`,
        })
        export class LoginButtonComponent {
          constructor(public auth: AuthService) {}

          login() {
            this.auth
              .loginWithRedirect({
                async openUrl(url: string) {
                  await Browser.open({ url, windowName: '_self' });
                }
              })
              .subscribe();
          }
        }
        ```

        ```ts app.module.ts lines  theme={null}
        // Import the types from the SDK
        import { AuthModule } from '@auth0/auth0-angular';
        import config from '../../capacitor.config';

        // ..

        // Build the URL that Auth0 should redirect back to
        const redirect_uri = `${config.appId}://{yourDomain}/capacitor/${config.appId}/callback`;

        // Register AuthModule with your AppModule
        @NgModule({
          declarations: [AppComponent],
          entryComponents: [],
          imports: [
            BrowserModule,
            IonicModule.forRoot(),
            AppRoutingModule,
            AuthModule.forRoot({
              domain: "{yourDomain}",
              clientId: "{yourClientId}",
              useRefreshTokens: true,
              useRefreshTokensFallback: false,
              authorizationParams: {
                redirect_uri
              }
            }),
          ],
          providers: [{ provide: RouteReuseStrategy, useClass: IonicRouteStrategy }],
          bootstrap: [AppComponent],
        })
        ```

        ```ts app.component.ts lines  theme={null}
        import { Component, OnInit, NgZone } from '@angular/core';
        import { AuthService } from '@auth0/auth0-angular';
        import { mergeMap } from 'rxjs/operators';
        import { Browser } from '@capacitor/browser';
        import { App } from '@capacitor/app';

        const callbackUri = `${config.appId}://{yourDomain}/capacitor/${config.appId}/callback`;

        @Component({
          selector: 'app-root',
          templateUrl: 'app.component.html',
          styleUrls: ['app.component.scss'],
        })
        export class AppComponent implements OnInit {
          // Import the AuthService module from the Auth0 Angular SDK
          constructor(public auth: AuthService, private ngZone: NgZone) {}

          ngOnInit(): void {
            // Use Capacitor's App plugin to subscribe to the `appUrlOpen` event
            App.addListener('appUrlOpen', ({ url }) => {
              // Must run inside an NgZone for Angular to pick up the changes
              // https://capacitorjs.com/docs/guides/angular
              ngZone.run(() => {
                if (url?.startsWith(callbackUri)) {
                  // If the URL is an authentication callback URL..
                  if (
                    url.includes('state=') &&
                    (url.includes('error=') || url.includes('code='))
                  ) {
                    // Call handleRedirectCallback and close the browser
                    this.auth
                      .handleRedirectCallback(url)
                      .pipe(mergeMap(() => Browser.close()))
                      .subscribe();
                  } else {
                    Browser.close();
                  }
                }
              });
            });
          }
        }
        ```

        ```ts logout-button.ts lines  theme={null}
        import { Component, OnInit } from '@angular/core';
        import { AuthService } from '@auth0/auth0-angular';
        import { Browser } from '@capacitor/browser';
        import { tap } from 'rxjs/operators';

        // Build the URL to return back to your app after logout
        const returnTo = `${config.appId}://{yourDomain}/capacitor/${config.appId}/callback`;

        @Component({
          selector: 'app-logout-button',
          template: `<ion-button (click)="logout()">Log out</ion-button>`,
        })
        export class LogoutButtonComponent {
          // Import the AuthService module from the Auth0 Angular SDK
          constructor(public auth: AuthService) {}

           logout() {
            this.auth
              .logout({ 
                logoutParams: {
                  returnTo,
                },
                async openUrl(url: string) {
                  await Browser.open({ url });
                } 
              })
              .subscribe();
          }
        }
        ```

        ```ts user-profile.ts lines  theme={null}
        import { Component, OnInit } from '@angular/core';
        import { AuthService } from '@auth0/auth0-angular';

        @Component({
          selector: 'app-profile',
          template: `
          <div *ngIf="auth.user$ | async as user">
            <ion-avatar class="avatar">
              <img [src]="user.picture" [alt]="user.name" />
            </ion-avatar>
            <h2>{{ user.name }}</h2>
            <p>{{ user.email }}</p>
          </div>`,
        })
        export class ProfileComponent {
          constructor(public auth: AuthService) {}
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```ts app.component.ts lines  theme={null}
        import { Component, OnInit, NgZone } from '@angular/core';
        import { AuthService } from '@auth0/auth0-angular';
        import { mergeMap } from 'rxjs/operators';
        import { Browser } from '@capacitor/browser';
        import { App } from '@capacitor/app';

        const callbackUri = `${config.appId}://{yourDomain}/capacitor/${config.appId}/callback`;

        @Component({
          selector: 'app-root',
          templateUrl: 'app.component.html',
          styleUrls: ['app.component.scss'],
        })
        export class AppComponent implements OnInit {
          // Import the AuthService module from the Auth0 Angular SDK
          constructor(public auth: AuthService, private ngZone: NgZone) {}

          ngOnInit(): void {
            // Use Capacitor's App plugin to subscribe to the `appUrlOpen` event
            App.addListener('appUrlOpen', ({ url }) => {
              // Must run inside an NgZone for Angular to pick up the changes
              // https://capacitorjs.com/docs/guides/angular
              ngZone.run(() => {
                if (url?.startsWith(callbackUri)) {
                  // If the URL is an authentication callback URL..
                  if (
                    url.includes('state=') &&
                    (url.includes('error=') || url.includes('code='))
                  ) {
                    // Call handleRedirectCallback and close the browser
                    this.auth
                      .handleRedirectCallback(url)
                      .pipe(mergeMap(() => Browser.close()))
                      .subscribe();
                  } else {
                    Browser.close();
                  }
                }
              });
            });
          }
        }
        ```

        ```ts app.module.ts lines  theme={null}
        // Import the types from the SDK
        import { AuthModule } from '@auth0/auth0-angular';
        import config from '../../capacitor.config';

        // ..

        // Build the URL that Auth0 should redirect back to
        const redirect_uri = `${config.appId}://{yourDomain}/capacitor/${config.appId}/callback`;

        // Register AuthModule with your AppModule
        @NgModule({
          declarations: [AppComponent],
          entryComponents: [],
          imports: [
            BrowserModule,
            IonicModule.forRoot(),
            AppRoutingModule,
            AuthModule.forRoot({
              domain: "{yourDomain}",
              clientId: "{yourClientId}",
              useRefreshTokens: true,
              useRefreshTokensFallback: false,
              authorizationParams: {
                redirect_uri
              }
            }),
          ],
          providers: [{ provide: RouteReuseStrategy, useClass: IonicRouteStrategy }],
          bootstrap: [AppComponent],
        })
        ```

        ```ts login-button.ts lines  theme={null}
        import { Component, OnInit } from '@angular/core';
        import { AuthService } from '@auth0/auth0-angular';
        import { Browser } from '@capacitor/browser';
        import { mergeMap } from 'rxjs/operators';

        @Component({
          selector: 'app-login-button',
          template: `<ion-button (click)="login()">Login</ion-button>`,
        })
        export class LoginButtonComponent {
          constructor(public auth: AuthService) {}

          login() {
            this.auth
              .loginWithRedirect({
                async openUrl(url: string) {
                  await Browser.open({ url, windowName: '_self' });
                }
              })
              .subscribe();
          }
        }
        ```

        ```ts logout-button.ts lines  theme={null}
        import { Component, OnInit } from '@angular/core';
        import { AuthService } from '@auth0/auth0-angular';
        import { Browser } from '@capacitor/browser';
        import { tap } from 'rxjs/operators';

        // Build the URL to return back to your app after logout
        const returnTo = `${config.appId}://{yourDomain}/capacitor/${config.appId}/callback`;

        @Component({
          selector: 'app-logout-button',
          template: `<ion-button (click)="logout()">Log out</ion-button>`,
        })
        export class LogoutButtonComponent {
          // Import the AuthService module from the Auth0 Angular SDK
          constructor(public auth: AuthService) {}

           logout() {
            this.auth
              .logout({ 
                logoutParams: {
                  returnTo,
                },
                async openUrl(url: string) {
                  await Browser.open({ url });
                } 
              })
              .subscribe();
          }
        }
        ```

        ```ts user-profile.ts lines  theme={null}
        import { Component, OnInit } from '@angular/core';
        import { AuthService } from '@auth0/auth0-angular';

        @Component({
          selector: 'app-profile',
          template: `
          <div *ngIf="auth.user$ | async as user">
            <ion-avatar class="avatar">
              <img [src]="user.picture" [alt]="user.name" />
            </ion-avatar>
            <h2>{{ user.name }}</h2>
            <p>{{ user.email }}</p>
          </div>`,
        })
        export class ProfileComponent {
          constructor(public auth: AuthService) {}
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```ts logout-button.ts lines  theme={null}
        import { Component, OnInit } from '@angular/core';
        import { AuthService } from '@auth0/auth0-angular';
        import { Browser } from '@capacitor/browser';
        import { tap } from 'rxjs/operators';

        // Build the URL to return back to your app after logout
        const returnTo = `${config.appId}://{yourDomain}/capacitor/${config.appId}/callback`;

        @Component({
          selector: 'app-logout-button',
          template: `<ion-button (click)="logout()">Log out</ion-button>`,
        })
        export class LogoutButtonComponent {
          // Import the AuthService module from the Auth0 Angular SDK
          constructor(public auth: AuthService) {}

           logout() {
            this.auth
              .logout({ 
                logoutParams: {
                  returnTo,
                },
                async openUrl(url: string) {
                  await Browser.open({ url });
                } 
              })
              .subscribe();
          }
        }
        ```

        ```ts app.module.ts lines  theme={null}
        // Import the types from the SDK
        import { AuthModule } from '@auth0/auth0-angular';
        import config from '../../capacitor.config';

        // ..

        // Build the URL that Auth0 should redirect back to
        const redirect_uri = `${config.appId}://{yourDomain}/capacitor/${config.appId}/callback`;

        // Register AuthModule with your AppModule
        @NgModule({
          declarations: [AppComponent],
          entryComponents: [],
          imports: [
            BrowserModule,
            IonicModule.forRoot(),
            AppRoutingModule,
            AuthModule.forRoot({
              domain: "{yourDomain}",
              clientId: "{yourClientId}",
              useRefreshTokens: true,
              useRefreshTokensFallback: false,
              authorizationParams: {
                redirect_uri
              }
            }),
          ],
          providers: [{ provide: RouteReuseStrategy, useClass: IonicRouteStrategy }],
          bootstrap: [AppComponent],
        })
        ```

        ```ts app.component.ts lines  theme={null}
        import { Component, OnInit, NgZone } from '@angular/core';
        import { AuthService } from '@auth0/auth0-angular';
        import { mergeMap } from 'rxjs/operators';
        import { Browser } from '@capacitor/browser';
        import { App } from '@capacitor/app';

        const callbackUri = `${config.appId}://{yourDomain}/capacitor/${config.appId}/callback`;

        @Component({
          selector: 'app-root',
          templateUrl: 'app.component.html',
          styleUrls: ['app.component.scss'],
        })
        export class AppComponent implements OnInit {
          // Import the AuthService module from the Auth0 Angular SDK
          constructor(public auth: AuthService, private ngZone: NgZone) {}

          ngOnInit(): void {
            // Use Capacitor's App plugin to subscribe to the `appUrlOpen` event
            App.addListener('appUrlOpen', ({ url }) => {
              // Must run inside an NgZone for Angular to pick up the changes
              // https://capacitorjs.com/docs/guides/angular
              ngZone.run(() => {
                if (url?.startsWith(callbackUri)) {
                  // If the URL is an authentication callback URL..
                  if (
                    url.includes('state=') &&
                    (url.includes('error=') || url.includes('code='))
                  ) {
                    // Call handleRedirectCallback and close the browser
                    this.auth
                      .handleRedirectCallback(url)
                      .pipe(mergeMap(() => Browser.close()))
                      .subscribe();
                  } else {
                    Browser.close();
                  }
                }
              });
            });
          }
        }
        ```

        ```ts login-button.ts lines  theme={null}
        import { Component, OnInit } from '@angular/core';
        import { AuthService } from '@auth0/auth0-angular';
        import { Browser } from '@capacitor/browser';
        import { mergeMap } from 'rxjs/operators';

        @Component({
          selector: 'app-login-button',
          template: `<ion-button (click)="login()">Login</ion-button>`,
        })
        export class LoginButtonComponent {
          constructor(public auth: AuthService) {}

          login() {
            this.auth
              .loginWithRedirect({
                async openUrl(url: string) {
                  await Browser.open({ url, windowName: '_self' });
                }
              })
              .subscribe();
          }
        }
        ```

        ```ts user-profile.ts lines  theme={null}
        import { Component, OnInit } from '@angular/core';
        import { AuthService } from '@auth0/auth0-angular';

        @Component({
          selector: 'app-profile',
          template: `
          <div *ngIf="auth.user$ | async as user">
            <ion-avatar class="avatar">
              <img [src]="user.picture" [alt]="user.name" />
            </ion-avatar>
            <h2>{{ user.name }}</h2>
            <p>{{ user.email }}</p>
          </div>`,
        })
        export class ProfileComponent {
          constructor(public auth: AuthService) {}
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```ts user-profile.ts lines  theme={null}
        import { Component, OnInit } from '@angular/core';
        import { AuthService } from '@auth0/auth0-angular';

        @Component({
          selector: 'app-profile',
          template: `
          <div *ngIf="auth.user$ | async as user">
            <ion-avatar class="avatar">
              <img [src]="user.picture" [alt]="user.name" />
            </ion-avatar>
            <h2>{{ user.name }}</h2>
            <p>{{ user.email }}</p>
          </div>`,
        })
        export class ProfileComponent {
          constructor(public auth: AuthService) {}
        }
        ```

        ```ts app.module.ts lines  theme={null}
        // Import the types from the SDK
        import { AuthModule } from '@auth0/auth0-angular';
        import config from '../../capacitor.config';

        // ..

        // Build the URL that Auth0 should redirect back to
        const redirect_uri = `${config.appId}://{yourDomain}/capacitor/${config.appId}/callback`;

        // Register AuthModule with your AppModule
        @NgModule({
          declarations: [AppComponent],
          entryComponents: [],
          imports: [
            BrowserModule,
            IonicModule.forRoot(),
            AppRoutingModule,
            AuthModule.forRoot({
              domain: "{yourDomain}",
              clientId: "{yourClientId}",
              useRefreshTokens: true,
              useRefreshTokensFallback: false,
              authorizationParams: {
                redirect_uri
              }
            }),
          ],
          providers: [{ provide: RouteReuseStrategy, useClass: IonicRouteStrategy }],
          bootstrap: [AppComponent],
        })
        ```

        ```ts app.component.ts lines  theme={null}
        import { Component, OnInit, NgZone } from '@angular/core';
        import { AuthService } from '@auth0/auth0-angular';
        import { mergeMap } from 'rxjs/operators';
        import { Browser } from '@capacitor/browser';
        import { App } from '@capacitor/app';

        const callbackUri = `${config.appId}://{yourDomain}/capacitor/${config.appId}/callback`;

        @Component({
          selector: 'app-root',
          templateUrl: 'app.component.html',
          styleUrls: ['app.component.scss'],
        })
        export class AppComponent implements OnInit {
          // Import the AuthService module from the Auth0 Angular SDK
          constructor(public auth: AuthService, private ngZone: NgZone) {}

          ngOnInit(): void {
            // Use Capacitor's App plugin to subscribe to the `appUrlOpen` event
            App.addListener('appUrlOpen', ({ url }) => {
              // Must run inside an NgZone for Angular to pick up the changes
              // https://capacitorjs.com/docs/guides/angular
              ngZone.run(() => {
                if (url?.startsWith(callbackUri)) {
                  // If the URL is an authentication callback URL..
                  if (
                    url.includes('state=') &&
                    (url.includes('error=') || url.includes('code='))
                  ) {
                    // Call handleRedirectCallback and close the browser
                    this.auth
                      .handleRedirectCallback(url)
                      .pipe(mergeMap(() => Browser.close()))
                      .subscribe();
                  } else {
                    Browser.close();
                  }
                }
              });
            });
          }
        }
        ```

        ```ts login-button.ts lines  theme={null}
        import { Component, OnInit } from '@angular/core';
        import { AuthService } from '@auth0/auth0-angular';
        import { Browser } from '@capacitor/browser';
        import { mergeMap } from 'rxjs/operators';

        @Component({
          selector: 'app-login-button',
          template: `<ion-button (click)="login()">Login</ion-button>`,
        })
        export class LoginButtonComponent {
          constructor(public auth: AuthService) {}

          login() {
            this.auth
              .loginWithRedirect({
                async openUrl(url: string) {
                  await Browser.open({ url, windowName: '_self' });
                }
              })
              .subscribe();
          }
        }
        ```

        ```ts logout-button.ts lines  theme={null}
        import { Component, OnInit } from '@angular/core';
        import { AuthService } from '@auth0/auth0-angular';
        import { Browser } from '@capacitor/browser';
        import { tap } from 'rxjs/operators';

        // Build the URL to return back to your app after logout
        const returnTo = `${config.appId}://{yourDomain}/capacitor/${config.appId}/callback`;

        @Component({
          selector: 'app-logout-button',
          template: `<ion-button (click)="logout()">Log out</ion-button>`,
        })
        export class LogoutButtonComponent {
          // Import the AuthService module from the Auth0 Angular SDK
          constructor(public auth: AuthService) {}

           logout() {
            this.auth
              .logout({ 
                logoutParams: {
                  returnTo,
                },
                async openUrl(url: string) {
                  await Browser.open({ url });
                } 
              })
              .subscribe();
          }
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>
  </SideMenu>
</Recipe>


# Add login to your Ionic React with Capacitor app
Source: https://auth0.com/docs/quickstart/native/ionic-react/interactive

This guide demonstrates how to integrate Auth0 with an Ionic (React) & Capacitor application using the Auth0 React SDK.

<QuickstartButtons />

<Recipe>
  <Content>
    Auth0 allows you to quickly add authentication and gain access to user profile information in your application.
    This guide demonstrates how to integrate Auth0 with an Ionic (React) & Capacitor application using the [Auth0 React SDK](https://github.com/auth0/auth0-react).

    <Section title={sections[0].title}>
      This quickstart assumes you already have an [Ionic](https://ionicframework.com/) application up and running with [Capacitor](https://capacitorjs.com/). If not, check out the [Using
      Capacitor with Ionic Framework guide](https://capacitorjs.com/docs/getting-started/with-ionic) to get started with a simple app, or clone [our sample
      apps](https://github.com/auth0-samples/auth0-ionic-samples).

      You should also be familiar with the [Capacitor development workflow](https://capacitorjs.com/docs/basics/workflow).
    </Section>

    <Section title={sections[1].title}>
      To use Auth0 services, you need to have an application set up in the Auth0 Dashboard. The Auth0 application is
      where you will configure how you want authentication to work for your project.

      <Info>
        Throughout this article, `YOUR_PACKAGE_ID` is your application's package ID. This can be
        found and configured in the `appId` field in your `capacitor.config.ts` file. See
        [Capacitor's Config schema](https://capacitorjs.com/docs/config#schema) for more info.
      </Info>

      ### Configure an application

      Use the interactive selector to create a new Auth0 application or select an existing application that represents
      the project you want to integrate with. Every application in Auth0 is assigned an alphanumeric, unique client ID
      that your application code will use to call Auth0 APIs through the SDK.

      Any settings you configure using this quickstart will automatically update for your application in the [Dashboard](https://manage.auth0.com/#/), which is where you
      can manage your applications in the future.

      If you would rather explore a complete configuration, you can view a sample application instead.

      ### Configure Callback URLs

      A callback URL is a URL in your application that you would like Auth0 to redirect users to after they have
      authenticated. If not set, users will not be returned to your application after they log in.

      <Info>
        If you are following along with our sample project, set this to:

        `YOUR_PACKAGE_ID://{yourTenant}.auth0.com/capacitor/YOUR_PACKAGE_ID/callback`
      </Info>

      ### Configure Logout URLs

      A logout URL is a URL in your application that you would like Auth0 to redirect users to after they have logged
      out. If not set, users will not be able to log out from your application and will receive an error.

      <Info>
        If you are following along with our sample project, set this to:

        `YOUR_PACKAGE_ID://{yourTenant}.auth0.com/capacitor/YOUR_PACKAGE_ID/callback`.
      </Info>

      ### Configure Allowed Origins

      To be able to make requests from your native application to Auth0, set the following **Allowed Origins** in
      your [Application Settings](https://manage.auth0.com/dashboard/#/applications/\{yourClientId}/settings).

      <Info>
        If you are following along with our sample project, set this to
        `capacitor://localhost, http://localhost` for iOS and Android respectively.
      </Info>

      Lastly, be sure that the **Application Type** for your application is set to **Native** in the [Application Settings](https://manage.auth0.com/dashboard/#/applications/\{yourClientId}/settings).
    </Section>

    <Section title={sections[2].title}>
      Run the following command within your project directory to install the Auth0 React SDK:

      ```bash theme={null}
      npm install @auth0/auth0-react
      ```

      The SDK exposes methods and variables that help you integrate Auth0 with your React application idiomatically
      using [React
      Hooks](https://reactjs.org/docs/hooks-overview.html) or [Higher-Order Components](https://reactjs.org/docs/higher-order-components.html).

      ### Install Capacitor plugins

      This quickstart and sample make use of some of Capacitor's official plugins. Install these into your app using
      the following command:

      ```bash theme={null}
      npm install @capacitor/browser @capacitor/app
      ```

      * [@capacitor/browser](https://capacitorjs.com/docs/apis/browser): Allows you to interact with the device's
        system browser and is used to open the URL to Auth0's authorization endpoint.
      * [@capacitor/app](https://capacitorjs.com/docs/apis/app): Allows you to subscribe to high-level app events,
        useful for handling callbacks from Auth0.

      <Info>
        Capacitor's Browser plugin on iOS uses [SFSafariViewController](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller), which on iOS 11+ does not share
        cookies with Safari on the device. This means that SSO will not work on those devices. If you need
        SSO, please instead use a compatible plugin that uses [ASWebAuthenticationSession](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession).
      </Info>
    </Section>

    <Section title={sections[3].title}>
      Under the hood, the Auth0 React SDK uses [React Context](https://reactjs.org/docs/context.html) to manage the authentication state of your users. One way to
      integrate Auth0 with your React app is to wrap your root component with an `Auth0Provider` you can
      import from the SDK.

      The `Auth0Provider` component takes the following props:

      * `domain`: The `domain`value present under the \*\*Settings \*\*of the application you
        created in your Auth0 Dashboard, or your custom domain if using Auth0's Custom Domains feature.
      * `clientId`: The Client ID value present under the \*\*Settings \*\*of the application you created
        in your Auth0 Dashboard.
      * `useRefreshTokens`: To use auth0-react with Ionic on Android and iOS, it's required to enable
        refresh tokens.
      * `useRefreshTokensFallback`: To use auth0-react with Ionic on Android and iOS, it's required to
        disable the iframe fallback.
      * `authorizationParams.redirect_uri`: The URL to where you'd like to redirect your users after they
        authenticate with Auth0.

      <Info>
        To persist authentication after closing and reopening the application, you may want to set
        `cacheLocation` to `localstorage` when configuring the SDK, but please be aware of
        [the risks of
        storing tokens in localstorage](/docs/libraries/auth0-single-page-app-sdk#change-storage-options). Also, localstorage should be treated as **transient** in
        Capacitor app as the data might be recovered unexpectedly in certain circumstances. Please read the [guidance on storage in the Capacitor docs](https://capacitorjs.com/docs/guides/storage#why-cant-i-just-use-localstorage-or-indexeddb).

        Additionally, the SDK has the ability to [use a custom cache implementation](https://github.com/auth0/auth0-spa-js/blob/master/EXAMPLES.md#creating-a-custom-cache) to store tokens, if
        you have a requirement to use a more secure and persistent storage mechanism.

        **Note** that we recommend **against** using [Capacitor's Storage plugin](https://capacitorjs.com/docs/apis/storage) to store tokens, as this is
        backed by [UserDefaults](https://developer.apple.com/documentation/foundation/userdefaults) and [SharedPreferences](https://developer.android.com/reference/android/content/SharedPreferences) on iOS and Android respectively. Data stored using
        these APIs is not encrypted, not secure, and could also be synced to the cloud.
      </Info>

      <Note>
        ##### Checkpoint

        Add the `Auth0Provider` component in a way that wraps your `App` component, then
        run your application to verify that the SDK is initializing correctly and your application is not throwing
        any errors related to Auth0.
      </Note>
    </Section>

    <Section title={sections[4].title}>
      In a Capacitor application, the [Capacitor's Browser plugin](https://capacitorjs.com/docs/apis/browser) performs a redirect to the Auth0 [Universal Login Page](https://auth0.com/universal-login). Set the `openUrl`
      parameter on the `loginWithRedirect` function to use `Browser.open` so that the URL is
      opened using the device's system browser component ([SFSafariViewController](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller) on iOS, and [Chrome
      Custom Tabs](https://developer.chrome.com/docs/android/custom-tabs) on Android).

      <Info>
        By default, the SDK's `loginWithRedirect` method uses `window.location.href` to
        navigate to the login page in the default browser application on the user's device rather than the
        system browser component appropriate for the platform. The user would leave your application to
        authenticate and could make for a suboptimal user experience.
      </Info>

      <Note>
        ##### Checkpoint

        The `loginWithRedirect` function tells the SDK to initiate the login flow, using the
        `Browser.open` function to open the login URL with the platform's system browser component by
        setting the `openUrl` parameter. This provides a way for your user to log in to your
        application. Users redirect to the login page at Auth0 and do not receive any errors.
      </Note>
    </Section>

    <Section title={sections[5].title}>
      Once users logs in with the Universal Login Page, they redirect back to your app via a URL with a custom URL
      scheme. The `appUrlOpen` event must be handled within your app. You can call the
      `handleRedirectCallback` method from the Auth0 SDK to initialize the authentication state.

      You can only use this method on a redirect from Auth0. To verify success, check for the presence of the
      `code` and `state` parameters in the URL.

      The `Browser.close()` method should close the browser when this event is raised.

      <Info>
        This article assumes you will be using Custom URL Schemes to handle the callback within your
        application. To do this, register your `YOUR_PACKAGE_ID` as a URL scheme for your chosen
        platform. To learn more, read [Defining a Custom URL Scheme](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) for iOS, or [Create Deep Links to App Content](https://developer.android.com/training/app-links/deep-linking) for Android.
      </Info>

      <Note>
        ##### Checkpoint

        Add the `appUrlOpen` to your application's `App` component and log in. The browser
        window should close once the user authenticates and logs in to your app.
      </Note>
    </Section>

    <Section title={sections[6].title}>
      Now that users can log in, you need to configure [a way to log out](https://auth0.com/docs/logout/guides/logout-auth0). Users must redirect to the Auth0 logout endpoint in the browser to clear
      their browser session. Again, Capacitor's Browser plugin should perform this redirect so that the user does not
      leave your app and receive a suboptimal experience.

      To achieve this with Ionic and Capacitor in conjunction with the Auth0 SDK:

      * Construct the URL for your app Auth0 should use to redirect to after logout. This is a URL that uses your
        registered custom scheme and Auth0 domain. Add it to your \*\*Allowed Logout URLs \*\*configuration in the
        Auth0 Dashboard
      * Logout from the SDK by calling `logout`, and pass your redirect URL back as the
        `logoutParams.returnTo` parameter.
      * Set the `openUrl` parameter to a callback that uses the Capacitor browser plugin to open the URL
        using `Browser.open`.

      <Info>
        Similar to the login step, if you do not set `openUrl` when calling `logout`, the
        SDK redirects the user to the logout URL using the default browser application on the device, which
        provides a suboptimal user experience.
      </Info>

      <Note>
        ##### Checkpoint

        Provide a way for your users to log out of your application. Verify that you redirect to Auth0 and then
        to the address you specified in the `returnTo` parameter. Check that you are no longer logged
        in to your application.
      </Note>
    </Section>

    <Section title={sections[7].title}>
      The Auth0 React SDK retrieves the user's profile
      associated with logged-in users in whatever component you need, such as their name or profile picture, to
      personalize the user interface. The profile information is available through the `user` property
      exposed by the `useAuth0()` hook.

      Initializing the SDK is asynchronous, and you should guard the user profile by checking the
      `isLoading` and `user` properties. Once `isLoading` is `false` and
      `user` has a value, the user profile can be used.

      <Note>
        ##### Checkpoint

        Provide a way for your users to see their user profile details within the app and verify you are able to
        retrieve and see your profile information on screen once you have logged in.
      </Note>
    </Section>

    ## Next Steps

    Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.

    This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:

    * [Auth0 Dashboard](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq) - Learn how to configure and manage your Auth0 tenant and applications
    * [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
  </Content>

  <SideMenu>
    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```tsx index.tsx lines  theme={null}
        import React from 'react';
        import { createRoot } from 'react-dom/client';
        import { Auth0Provider } from '@auth0/auth0-react';
        import App from './App';

        const root = createRoot(document.getElementById('root'));

        root.render(
          <Auth0Provider
            domain="{yourDomain}"
            clientId="{yourClientId}"
            useRefreshTokens={true}
            useRefreshTokensFallback={false}
            authorizationParams={{
              redirect_uri: "YOUR_PACKAGE_ID://{yourDomain}/capacitor/YOUR_PACKAGE_ID/callback"
            }}
          >
            <App />
          </Auth0Provider>
        );
        ```

        ```tsx login-button.tsx lines  theme={null}
        import { useAuth0 } from '@auth0/auth0-react';
        import { Browser } from '@capacitor/browser';
        import { IonButton } from '@ionic/react';

        const LoginButton: React.FC = () => {
          const { loginWithRedirect } = useAuth0();

          const login = async () => {
            await loginWithRedirect({
              async openUrl(url) {
                 // Redirect using Capacitor's Browser plugin
                await Browser.open({
                  url,
                  windowName: "_self"
                });
              }
            });
          };

          return <IonButton onClick={login}>Log in</IonButton>;
        };

        export default LoginButton;
        ```

        ```tsx logout-button.tsx lines  theme={null}
        import { useAuth0 } from '@auth0/auth0-react';
        import { Browser } from '@capacitor/browser';
        import { IonButton } from '@ionic/react';

        // This should reflect the URL added earlier to your "Allowed Logout URLs" setting
        // in the Auth0 dashboard.
        const logoutUri = 'YOUR_PACKAGE_ID://{yourDomain}/capacitor/YOUR_PACKAGE_ID/callback';

        const LogoutButton: React.FC = () => {
          const { logout } = useAuth0();

          const doLogout = async () => {
            await logout({
              logoutParams: {
                returnTo: logoutUri
              },
              async openUrl(url) {
                 // Redirect using Capacitor's Browser plugin
                await Browser.open({
                  url,
                  windowName: "_self"
                });
              }
            });
          };

          return <IonButton onClick={doLogout}>Log out</IonButton>;
        };

        export default LogoutButton;
        ```

        ```tsx app.tsx lines  theme={null}
        // Import Capacitor's app and browser plugins, giving us access to `addListener` and `appUrlOpen`,
        // as well as the bits needed for Auth0 and React
        import { App as CapApp } from '@capacitor/app';
        import { Browser } from '@capacitor/browser';
        import { useEffect } from 'react';
        import { useAuth0 } from '@auth0/auth0-react';

        // ...

        const App: React.FC = () => {
          // Get the callback handler from the Auth0 React hook
          const { handleRedirectCallback } = useAuth0();

          useEffect(() => {
            // Handle the 'appUrlOpen' event and call `handleRedirectCallback`
            CapApp.addListener('appUrlOpen', async ({ url }) => {
              if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
                await handleRedirectCallback(url);
              }
              // No-op on Android
              await Browser.close();
            });
          }, [handleRedirectCallback]);

          // ..
        };// Import Capacitor's app and browser plugins, giving us access to `addListener` and `appUrlOpen`,
        // as well as the bits needed for Auth0 and React
        import { App as CapApp } from '@capacitor/app';
        import { Browser } from '@capacitor/browser';
        import { useEffect } from 'react';
        import { useAuth0 } from '@auth0/auth0-react';

        // ...

        const App: React.FC = () => {
          // Get the callback handler from the Auth0 React hook
          const { handleRedirectCallback } = useAuth0();

          useEffect(() => {
            // Handle the 'appUrlOpen' event and call `handleRedirectCallback`
            CapApp.addListener('appUrlOpen', async ({ url }) => {
              if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
                await handleRedirectCallback(url);
              }
              // No-op on Android
              await Browser.close();
            });
          }, [handleRedirectCallback]);

          // ..
        };
        ```

        ```tsx user-profile.tsx lines  theme={null}
        import { useAuth0 } from '@auth0/auth0-react';

        const Profile: React.FC = () => {
          const { user, isLoading } = useAuth0();

          // If the SDK is not ready, or a user is not authenticated, exit.
          if (isLoading || !user) return null;

          return (
            <div>
              <img src={user.picture} alt={user.name} />
              <h2>{user.name}</h2>
              <p>{user.email}</p>
            </div>
          );
        };

        export default Profile;
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```tsx login-button.tsx lines  theme={null}
        import { useAuth0 } from '@auth0/auth0-react';
        import { Browser } from '@capacitor/browser';
        import { IonButton } from '@ionic/react';

        const LoginButton: React.FC = () => {
          const { loginWithRedirect } = useAuth0();

          const login = async () => {
            await loginWithRedirect({
              async openUrl(url) {
                 // Redirect using Capacitor's Browser plugin
                await Browser.open({
                  url,
                  windowName: "_self"
                });
              }
            });
          };

          return <IonButton onClick={login}>Log in</IonButton>;
        };

        export default LoginButton;
        ```

        ```tsx index.tsx lines  theme={null}
        import React from 'react';
        import { createRoot } from 'react-dom/client';
        import { Auth0Provider } from '@auth0/auth0-react';
        import App from './App';

        const root = createRoot(document.getElementById('root'));

        root.render(
          <Auth0Provider
            domain="{yourDomain}"
            clientId="{yourClientId}"
            useRefreshTokens={true}
            useRefreshTokensFallback={false}
            authorizationParams={{
              redirect_uri: "YOUR_PACKAGE_ID://{yourDomain}/capacitor/YOUR_PACKAGE_ID/callback"
            }}
          >
            <App />
          </Auth0Provider>
        );
        ```

        ```tsx logout-button.tsx lines  theme={null}
        import { useAuth0 } from '@auth0/auth0-react';
        import { Browser } from '@capacitor/browser';
        import { IonButton } from '@ionic/react';

        // This should reflect the URL added earlier to your "Allowed Logout URLs" setting
        // in the Auth0 dashboard.
        const logoutUri = 'YOUR_PACKAGE_ID://{yourDomain}/capacitor/YOUR_PACKAGE_ID/callback';

        const LogoutButton: React.FC = () => {
          const { logout } = useAuth0();

          const doLogout = async () => {
            await logout({
              logoutParams: {
                returnTo: logoutUri
              },
              async openUrl(url) {
                 // Redirect using Capacitor's Browser plugin
                await Browser.open({
                  url,
                  windowName: "_self"
                });
              }
            });
          };

          return <IonButton onClick={doLogout}>Log out</IonButton>;
        };

        export default LogoutButton;
        ```

        ```tsx app.tsx lines  theme={null}
        // Import Capacitor's app and browser plugins, giving us access to `addListener` and `appUrlOpen`,
        // as well as the bits needed for Auth0 and React
        import { App as CapApp } from '@capacitor/app';
        import { Browser } from '@capacitor/browser';
        import { useEffect } from 'react';
        import { useAuth0 } from '@auth0/auth0-react';

        // ...

        const App: React.FC = () => {
          // Get the callback handler from the Auth0 React hook
          const { handleRedirectCallback } = useAuth0();

          useEffect(() => {
            // Handle the 'appUrlOpen' event and call `handleRedirectCallback`
            CapApp.addListener('appUrlOpen', async ({ url }) => {
              if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
                await handleRedirectCallback(url);
              }
              // No-op on Android
              await Browser.close();
            });
          }, [handleRedirectCallback]);

          // ..
        };// Import Capacitor's app and browser plugins, giving us access to `addListener` and `appUrlOpen`,
        // as well as the bits needed for Auth0 and React
        import { App as CapApp } from '@capacitor/app';
        import { Browser } from '@capacitor/browser';
        import { useEffect } from 'react';
        import { useAuth0 } from '@auth0/auth0-react';

        // ...

        const App: React.FC = () => {
          // Get the callback handler from the Auth0 React hook
          const { handleRedirectCallback } = useAuth0();

          useEffect(() => {
            // Handle the 'appUrlOpen' event and call `handleRedirectCallback`
            CapApp.addListener('appUrlOpen', async ({ url }) => {
              if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
                await handleRedirectCallback(url);
              }
              // No-op on Android
              await Browser.close();
            });
          }, [handleRedirectCallback]);

          // ..
        };
        ```

        ```tsx user-profile.tsx lines  theme={null}
        import { useAuth0 } from '@auth0/auth0-react';

        const Profile: React.FC = () => {
          const { user, isLoading } = useAuth0();

          // If the SDK is not ready, or a user is not authenticated, exit.
          if (isLoading || !user) return null;

          return (
            <div>
              <img src={user.picture} alt={user.name} />
              <h2>{user.name}</h2>
              <p>{user.email}</p>
            </div>
          );
        };

        export default Profile;
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```tsx app.tsx lines  theme={null}
        // Import Capacitor's app and browser plugins, giving us access to `addListener` and `appUrlOpen`,
        // as well as the bits needed for Auth0 and React
        import { App as CapApp } from '@capacitor/app';
        import { Browser } from '@capacitor/browser';
        import { useEffect } from 'react';
        import { useAuth0 } from '@auth0/auth0-react';

        // ...

        const App: React.FC = () => {
          // Get the callback handler from the Auth0 React hook
          const { handleRedirectCallback } = useAuth0();

          useEffect(() => {
            // Handle the 'appUrlOpen' event and call `handleRedirectCallback`
            CapApp.addListener('appUrlOpen', async ({ url }) => {
              if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
                await handleRedirectCallback(url);
              }
              // No-op on Android
              await Browser.close();
            });
          }, [handleRedirectCallback]);

          // ..
        };// Import Capacitor's app and browser plugins, giving us access to `addListener` and `appUrlOpen`,
        // as well as the bits needed for Auth0 and React
        import { App as CapApp } from '@capacitor/app';
        import { Browser } from '@capacitor/browser';
        import { useEffect } from 'react';
        import { useAuth0 } from '@auth0/auth0-react';

        // ...

        const App: React.FC = () => {
          // Get the callback handler from the Auth0 React hook
          const { handleRedirectCallback } = useAuth0();

          useEffect(() => {
            // Handle the 'appUrlOpen' event and call `handleRedirectCallback`
            CapApp.addListener('appUrlOpen', async ({ url }) => {
              if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
                await handleRedirectCallback(url);
              }
              // No-op on Android
              await Browser.close();
            });
          }, [handleRedirectCallback]);

          // ..
        };
        ```

        ```tsx index.tsx lines  theme={null}
        import React from 'react';
        import { createRoot } from 'react-dom/client';
        import { Auth0Provider } from '@auth0/auth0-react';
        import App from './App';

        const root = createRoot(document.getElementById('root'));

        root.render(
          <Auth0Provider
            domain="{yourDomain}"
            clientId="{yourClientId}"
            useRefreshTokens={true}
            useRefreshTokensFallback={false}
            authorizationParams={{
              redirect_uri: "YOUR_PACKAGE_ID://{yourDomain}/capacitor/YOUR_PACKAGE_ID/callback"
            }}
          >
            <App />
          </Auth0Provider>
        );
        ```

        ```tsx login-button.tsx lines  theme={null}
        import { useAuth0 } from '@auth0/auth0-react';
        import { Browser } from '@capacitor/browser';
        import { IonButton } from '@ionic/react';

        const LoginButton: React.FC = () => {
          const { loginWithRedirect } = useAuth0();

          const login = async () => {
            await loginWithRedirect({
              async openUrl(url) {
                 // Redirect using Capacitor's Browser plugin
                await Browser.open({
                  url,
                  windowName: "_self"
                });
              }
            });
          };

          return <IonButton onClick={login}>Log in</IonButton>;
        };

        export default LoginButton;
        ```

        ```tsx logout-button.tsx lines  theme={null}
        import { useAuth0 } from '@auth0/auth0-react';
        import { Browser } from '@capacitor/browser';
        import { IonButton } from '@ionic/react';

        // This should reflect the URL added earlier to your "Allowed Logout URLs" setting
        // in the Auth0 dashboard.
        const logoutUri = 'YOUR_PACKAGE_ID://{yourDomain}/capacitor/YOUR_PACKAGE_ID/callback';

        const LogoutButton: React.FC = () => {
          const { logout } = useAuth0();

          const doLogout = async () => {
            await logout({
              logoutParams: {
                returnTo: logoutUri
              },
              async openUrl(url) {
                 // Redirect using Capacitor's Browser plugin
                await Browser.open({
                  url,
                  windowName: "_self"
                });
              }
            });
          };

          return <IonButton onClick={doLogout}>Log out</IonButton>;
        };

        export default LogoutButton;
        ```

        ```tsx user-profile.tsx lines  theme={null}
        import { useAuth0 } from '@auth0/auth0-react';

        const Profile: React.FC = () => {
          const { user, isLoading } = useAuth0();

          // If the SDK is not ready, or a user is not authenticated, exit.
          if (isLoading || !user) return null;

          return (
            <div>
              <img src={user.picture} alt={user.name} />
              <h2>{user.name}</h2>
              <p>{user.email}</p>
            </div>
          );
        };

        export default Profile;
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```tsx logout-button.tsx lines  theme={null}
        import { useAuth0 } from '@auth0/auth0-react';
        import { Browser } from '@capacitor/browser';
        import { IonButton } from '@ionic/react';

        // This should reflect the URL added earlier to your "Allowed Logout URLs" setting
        // in the Auth0 dashboard.
        const logoutUri = 'YOUR_PACKAGE_ID://{yourDomain}/capacitor/YOUR_PACKAGE_ID/callback';

        const LogoutButton: React.FC = () => {
          const { logout } = useAuth0();

          const doLogout = async () => {
            await logout({
              logoutParams: {
                returnTo: logoutUri
              },
              async openUrl(url) {
                 // Redirect using Capacitor's Browser plugin
                await Browser.open({
                  url,
                  windowName: "_self"
                });
              }
            });
          };

          return <IonButton onClick={doLogout}>Log out</IonButton>;
        };

        export default LogoutButton;
        ```

        ```tsx index.tsx lines  theme={null}
        import React from 'react';
        import { createRoot } from 'react-dom/client';
        import { Auth0Provider } from '@auth0/auth0-react';
        import App from './App';

        const root = createRoot(document.getElementById('root'));

        root.render(
          <Auth0Provider
            domain="{yourDomain}"
            clientId="{yourClientId}"
            useRefreshTokens={true}
            useRefreshTokensFallback={false}
            authorizationParams={{
              redirect_uri: "YOUR_PACKAGE_ID://{yourDomain}/capacitor/YOUR_PACKAGE_ID/callback"
            }}
          >
            <App />
          </Auth0Provider>
        );
        ```

        ```tsx login-button.tsx lines  theme={null}
        import { useAuth0 } from '@auth0/auth0-react';
        import { Browser } from '@capacitor/browser';
        import { IonButton } from '@ionic/react';

        const LoginButton: React.FC = () => {
          const { loginWithRedirect } = useAuth0();

          const login = async () => {
            await loginWithRedirect({
              async openUrl(url) {
                 // Redirect using Capacitor's Browser plugin
                await Browser.open({
                  url,
                  windowName: "_self"
                });
              }
            });
          };

          return <IonButton onClick={login}>Log in</IonButton>;
        };

        export default LoginButton;
        ```

        ```tsx app.tsx lines  theme={null}
        // Import Capacitor's app and browser plugins, giving us access to `addListener` and `appUrlOpen`,
        // as well as the bits needed for Auth0 and React
        import { App as CapApp } from '@capacitor/app';
        import { Browser } from '@capacitor/browser';
        import { useEffect } from 'react';
        import { useAuth0 } from '@auth0/auth0-react';

        // ...

        const App: React.FC = () => {
          // Get the callback handler from the Auth0 React hook
          const { handleRedirectCallback } = useAuth0();

          useEffect(() => {
            // Handle the 'appUrlOpen' event and call `handleRedirectCallback`
            CapApp.addListener('appUrlOpen', async ({ url }) => {
              if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
                await handleRedirectCallback(url);
              }
              // No-op on Android
              await Browser.close();
            });
          }, [handleRedirectCallback]);

          // ..
        };// Import Capacitor's app and browser plugins, giving us access to `addListener` and `appUrlOpen`,
        // as well as the bits needed for Auth0 and React
        import { App as CapApp } from '@capacitor/app';
        import { Browser } from '@capacitor/browser';
        import { useEffect } from 'react';
        import { useAuth0 } from '@auth0/auth0-react';

        // ...

        const App: React.FC = () => {
          // Get the callback handler from the Auth0 React hook
          const { handleRedirectCallback } = useAuth0();

          useEffect(() => {
            // Handle the 'appUrlOpen' event and call `handleRedirectCallback`
            CapApp.addListener('appUrlOpen', async ({ url }) => {
              if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
                await handleRedirectCallback(url);
              }
              // No-op on Android
              await Browser.close();
            });
          }, [handleRedirectCallback]);

          // ..
        };
        ```

        ```tsx user-profile.tsx lines  theme={null}
        import { useAuth0 } from '@auth0/auth0-react';

        const Profile: React.FC = () => {
          const { user, isLoading } = useAuth0();

          // If the SDK is not ready, or a user is not authenticated, exit.
          if (isLoading || !user) return null;

          return (
            <div>
              <img src={user.picture} alt={user.name} />
              <h2>{user.name}</h2>
              <p>{user.email}</p>
            </div>
          );
        };

        export default Profile;
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```tsx user-profile.tsx lines  theme={null}
        import { useAuth0 } from '@auth0/auth0-react';

        const Profile: React.FC = () => {
          const { user, isLoading } = useAuth0();

          // If the SDK is not ready, or a user is not authenticated, exit.
          if (isLoading || !user) return null;

          return (
            <div>
              <img src={user.picture} alt={user.name} />
              <h2>{user.name}</h2>
              <p>{user.email}</p>
            </div>
          );
        };

        export default Profile;
        ```

        ```tsx index.tsx lines  theme={null}
        import React from 'react';
        import { createRoot } from 'react-dom/client';
        import { Auth0Provider } from '@auth0/auth0-react';
        import App from './App';

        const root = createRoot(document.getElementById('root'));

        root.render(
          <Auth0Provider
            domain="{yourDomain}"
            clientId="{yourClientId}"
            useRefreshTokens={true}
            useRefreshTokensFallback={false}
            authorizationParams={{
              redirect_uri: "YOUR_PACKAGE_ID://{yourDomain}/capacitor/YOUR_PACKAGE_ID/callback"
            }}
          >
            <App />
          </Auth0Provider>
        );
        ```

        ```tsx login-button.tsx lines  theme={null}
        import { useAuth0 } from '@auth0/auth0-react';
        import { Browser } from '@capacitor/browser';
        import { IonButton } from '@ionic/react';

        const LoginButton: React.FC = () => {
          const { loginWithRedirect } = useAuth0();

          const login = async () => {
            await loginWithRedirect({
              async openUrl(url) {
                 // Redirect using Capacitor's Browser plugin
                await Browser.open({
                  url,
                  windowName: "_self"
                });
              }
            });
          };

          return <IonButton onClick={login}>Log in</IonButton>;
        };

        export default LoginButton;
        ```

        ```tsx logout-button.tsx lines  theme={null}
        import { useAuth0 } from '@auth0/auth0-react';
        import { Browser } from '@capacitor/browser';
        import { IonButton } from '@ionic/react';

        // This should reflect the URL added earlier to your "Allowed Logout URLs" setting
        // in the Auth0 dashboard.
        const logoutUri = 'YOUR_PACKAGE_ID://{yourDomain}/capacitor/YOUR_PACKAGE_ID/callback';

        const LogoutButton: React.FC = () => {
          const { logout } = useAuth0();

          const doLogout = async () => {
            await logout({
              logoutParams: {
                returnTo: logoutUri
              },
              async openUrl(url) {
                 // Redirect using Capacitor's Browser plugin
                await Browser.open({
                  url,
                  windowName: "_self"
                });
              }
            });
          };

          return <IonButton onClick={doLogout}>Log out</IonButton>;
        };

        export default LogoutButton;
        ```

        ```tsx app.tsx lines  theme={null}
        // Import Capacitor's app and browser plugins, giving us access to `addListener` and `appUrlOpen`,
        // as well as the bits needed for Auth0 and React
        import { App as CapApp } from '@capacitor/app';
        import { Browser } from '@capacitor/browser';
        import { useEffect } from 'react';
        import { useAuth0 } from '@auth0/auth0-react';

        // ...

        const App: React.FC = () => {
          // Get the callback handler from the Auth0 React hook
          const { handleRedirectCallback } = useAuth0();

          useEffect(() => {
            // Handle the 'appUrlOpen' event and call `handleRedirectCallback`
            CapApp.addListener('appUrlOpen', async ({ url }) => {
              if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
                await handleRedirectCallback(url);
              }
              // No-op on Android
              await Browser.close();
            });
          }, [handleRedirectCallback]);

          // ..
        };// Import Capacitor's app and browser plugins, giving us access to `addListener` and `appUrlOpen`,
        // as well as the bits needed for Auth0 and React
        import { App as CapApp } from '@capacitor/app';
        import { Browser } from '@capacitor/browser';
        import { useEffect } from 'react';
        import { useAuth0 } from '@auth0/auth0-react';

        // ...

        const App: React.FC = () => {
          // Get the callback handler from the Auth0 React hook
          const { handleRedirectCallback } = useAuth0();

          useEffect(() => {
            // Handle the 'appUrlOpen' event and call `handleRedirectCallback`
            CapApp.addListener('appUrlOpen', async ({ url }) => {
              if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
                await handleRedirectCallback(url);
              }
              // No-op on Android
              await Browser.close();
            });
          }, [handleRedirectCallback]);

          // ..
        };
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>
  </SideMenu>
</Recipe>


# Add login to your Ionic Vue with Capacitor app
Source: https://auth0.com/docs/quickstart/native/ionic-vue/interactive

This guide demonstrates how to integrate Auth0 with an Ionic (Vue) & Capacitor application using the Auth0 Vue SDK Vue with Capacitor app

<QuickstartButtons />

<Recipe>
  <Content>
    Auth0 allows you to quickly add authentication and gain access to user profile information in your application.
    This guide demonstrates how to integrate Auth0 with an Ionic (Vue) & Capacitor application using the [Auth0 Vue SDK](https://github.com/auth0/auth0-vue).

    <Section title={sections[0].title}>
      This quickstart assumes you already have an [Ionic](https://ionicframework.com/) application up and running with [Capacitor](https://capacitorjs.com/). If not, check out the [Using
      Capacitor with Ionic Framework guide](https://capacitorjs.com/docs/getting-started/with-ionic) to get started with a simple app, or clone [our sample
      apps](https://github.com/auth0-samples/auth0-ionic-samples).

      You should also be familiar with the [Capacitor development workflow](https://capacitorjs.com/docs/basics/workflow).
    </Section>

    <Section title={sections[1].title}>
      To use Auth0 services, you need to have an application set up in the Auth0 Dashboard. The Auth0 application is
      where you will configure how you want authentication to work for your project.

      <Info>
        Throughout this article, `YOUR_PACKAGE_ID` is your application's package ID. This can be
        found and configured in the `appId` field in your `capacitor.config.ts` file. See
        [Capacitor's Config schema](https://capacitorjs.com/docs/config#schema) for more info.
      </Info>

      ### Configure an application

      Use the interactive selector to create a new Auth0 application or select an existing application that represents
      the project you want to integrate with. Every application in Auth0 is assigned an alphanumeric, unique client ID
      that your application code will use to call Auth0 APIs through the SDK.

      Any settings you configure using this quickstart will automatically update for your application in the [Dashboard](https://manage.auth0.com/#/), which is where you
      can manage your applications in the future.

      If you would rather explore a complete configuration, you can view a sample application instead.

      ### Configure Callback URLs

      A callback URL is a URL in your application that you would like Auth0 to redirect users to after they have
      authenticated. If not set, users will not be returned to your application after they log in

      <Info>
        If you are following along with our sample project, set this to
        `YOUR_PACKAGE_ID://{yourDomain}/capacitor/YOUR_PACKAGE_ID/callback`
      </Info>

      ### Configure Logout URLs

      A logout URL is a URL in your application that you would like Auth0 to redirect users to after they have logged
      out. If not set, users will not be able to log out from your application and will receive an error.

      <Info>
        If you are following along with our sample project, set this to
        `YOUR_PACKAGE_ID://{yourDomain}/capacitor/YOUR_PACKAGE_ID/callback`.
      </Info>

      ### Configure Allowed Origins

      To be able to make requests from your native application to Auth0, set the following **Allowed Origins** in
      your [Application Settings](https://manage.auth0.com/#/applications/\{yourClientId}/settings).

      <Info>
        If you are following along with our sample project, set this to
        `capacitor://localhost, http://localhost` for iOS and Android respectively.
      </Info>

      Lastly, be sure that the **Application Type** for your application is set to **Native** in the [Application Settings](https://manage.auth0.com/#/applications/\{yourClientId}/settings).
    </Section>

    <Section title={sections[2].title}>
      Run the following command within your project directory to install the Auth0 Vue SDK:

      ```bash theme={null}
      npm install @auth0/auth0-vue
      ```

      The SDK exposes several types that help you integrate Auth0 with your Vue application idiomatically, including a
      module and an authentication service.

      ### Install Capacitor plugins

      This quickstart and sample make use of some of Capacitor's official plugins. Install these into your app using
      the following command:

      npm install @capacitor/browser @capacitor/app

      * [@capacitor/browser](https://capacitorjs.com/docs/apis/browser) - allows you to interact with the device's
        system browser and is used to open the URL to Auth0's authorizaction endpoint
      * [@capacitor/app](https://capacitorjs.com/docs/apis/app) - allows you to subscribe to high-level app
        events, useful for handling callbacks from Auth0

      <Info>
        Capacitor's Browser plugin on iOS uses [SFSafariViewController](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller), which on iOS 11+ does not share
        cookies with Safari on the device. This means that [SSO](https://auth0.com/docs/sso) will not work on those devices. If you need SSO, please instead use a
        compatible plugin that uses [ASWebAuthenticationSession](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession).
      </Info>
    </Section>

    <Section title={sections[3].title}>
      The SDK exports `createAuth0`, a composable that contains all the services required for the SDK to
      function. This composable should be registered with your application and be configured with your Auth0 domain and
      Client ID.

      The `createAuth0` composable takes the following configuration:

      * `domain`: The `domain`value present under the \*\*Settings \*\*of the application you
        created in the Auth0 Dashboard, or your custom domain if you are using Auth0's [custom domains feature](http://localhost:3000/docs/custom-domains).
      * `clientId`: The Client ID value present under the \*\*Settings \*\*of the application you created
        in the Auth0 Dashboard.
      * `useRefreshTokens`: To use auth0-vue with Ionic on Android and iOS, it's required to enable
        refresh tokens.
      * `useRefreshTokensFallback`: To use auth0-vue with Ionic on Android and iOS, it's required to
        disable the iframe fallback.
      * `authorizationParams.redirect_uri`: The URL to redirect your users after they authenticate with
        Auth0.

      <Info>
        To persist authentication after closing and reopening the application, you may want to set
        `cacheLocation` to `localstorage` when configuring the SDK, but please be aware of
        [the risks of storing tokens in localstorage](https://auth0.com/docs/libraries/auth0-single-page-app-sdk#change-storage-options). Also, localstorage should be treated
        as **transient** in Capacitor app as the data might be recovered unexpectedly in certain
        circumstances. Please read the [guidance on storage in the Capacitor docs](https://capacitorjs.com/docs/guides/storage#why-cant-i-just-use-localstorage-or-indexeddb).

        Additionally, the SDK has the ability to [use a custom cache implementation](https://github.com/auth0/auth0-spa-js/blob/master/EXAMPLES.md#creating-a-custom-cache) to store tokens, if
        you have a requirement to use a more secure and persistent storage mechanism.

        **Note** that we recommend **against** using [Capacitor's Storage plugin](https://capacitorjs.com/docs/apis/storage) to store tokens, as this is
        backed by [UserDefaults](https://developer.apple.com/documentation/foundation/userdefaults) and [SharedPreferences](https://developer.android.com/reference/android/content/SharedPreferences) on iOS and Android respectively. Data stored using
        these APIs is not encrypted, not secure, and could also be synced to the cloud.
      </Info>

      <Note>
        ##### Checkpoint

        Now that you have configured your app with the Auth0 Vue SDK, run your application to verify that the SDK
        is initializing without error, and that your application runs as it did before.
      </Note>
    </Section>

    <Section title={sections[4].title}>
      In a Capacitor application, the [Capacitor's Browser plugin](https://capacitorjs.com/docs/apis/browser) performs a redirect to the Auth0 [Universal Login Page](https://auth0.com/universal-login). Set the `openUrl`
      parameter on the `loginWithRedirect` function to use `Browser.open` so that the URL is
      opened using the device's system browser component ([SFSafariViewController](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller) on iOS, and [Chrome
      Custom Tabs](https://developer.chrome.com/docs/android/custom-tabs) on Android).

      <Info>
        By default, the SDK's `loginWithRedirect` method uses `window.location.href` to
        navigate to the login page in the default browser application on the user's device rather than the
        system browser component appropriate for the platform. The user would leave your application to
        authenticate and could make for a suboptimal user experience.
      </Info>

      <Note>
        ##### Checkpoint

        The `loginWithRedirect` function tells the SDK to initiate the login flow, using the
        `Browser.open` function to open the login URL with the platform's system browser component by
        setting the `openUrl` parameter. This provides a way for your user to log in to your
        application. Users redirect to the login page at Auth0 and do not receive any errors.
      </Note>
    </Section>

    <Section title={sections[5].title}>
      Once users logs in with the Universal Login Page, they redirect back to your app via a URL with a custom URL
      scheme. The `appUrlOpen` event must be handled within your app. You can call the
      `handleRedirectCallback` method from the Auth0 SDK to initialize the authentication state.

      You can only use this method on a redirect from Auth0. To verify success, check for the presence of the
      `code` and `state` parameters in the URL.

      The `Browser.close()` method should close the browser when this event is raised.

      <Info>
        This article assumes you will be using Custom URL Schemes to handle the callback within your
        application. To do this, register your `YOUR_PACKAGE_ID` as a URL scheme for your chosen
        platform. To learn more, read [Defining a Custom URL Scheme](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) for iOS, or [Create Deep Links to App Content](https://developer.android.com/training/app-links/deep-linking) for Android.
      </Info>

      <Note>
        ##### Checkpoint

        Add the `appUrlOpen` to your application's `App` component setup and log in. The
        browser window should close once the user authenticates and logs in to your app.
      </Note>
    </Section>

    <Section title={sections[6].title}>
      Now that users can log in, you need to configure [a way to log out](https://auth0.com/docs/logout/guides/logout-auth0). Users must redirect to the Auth0 logout endpoint in the browser to clear
      their browser session. Again, Capacitor's Browser plugin should perform this redirect so that the user does not
      leave your app and receive a suboptimal experience.

      To achieve this with Ionic and Capacitor in conjunction with the Auth0 SDK:

      * Construct the URL for your app Auth0 should use to redirect to after logout. This is a URL that uses your
        registered custom scheme and Auth0 domain. Add it to your \*\*Allowed Logout URLs \*\*configuration in the
        Auth0 Dashboard
      * Logout from the SDK by calling `logout`, and pass your redirect URL back as the
        `logoutParams.returnTo`parameter.
      * Set the `openUrl`parameter to a callback that uses the Capacitor browser plugin to open the URL
        using `Browser.open`.

      <Info>
        Similar to the login step, if you do not set `openUrl` when calling `logout`, the
        SDK redirects the user to the logout URL using the default browser application on the device, which
        provides a suboptimal user experience.
      </Info>

      <Note>
        ##### Checkpoint

        Provide a way for your users to log out of your application. Verify that you redirect to Auth0 and then
        to the address you specified in the `returnTo` parameter. Check that you are no longer logged
        in to your application.
      </Note>
    </Section>

    <Section title={sections[7].title}>
      The Auth0 Vue SDK retrieves the [user's profile](https://auth0.com/docs/users/concepts/overview-user-profile) associated with logged-in users in whatever component you need, such as their
      name or profile picture, to personalize the user interface. The profile information is available through the
      `user` property exposed by the `useAuth0()` composable.

      Initializing the SDK is asynchronous, and you should guard the user profile by checking the
      `isLoading` and `user` properties. Once `isLoading` is `false` and
      `user` has a value, the user profile can be used.

      <Note>
        ##### Checkpoint

        Provide a way for your users to see their user profile details within the app and verify you are able to
        retrieve and see your profile information on screen once you have logged in.
      </Note>
    </Section>

    ## Next Steps

    Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.

    This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:

    * [Auth0 Dashboard](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq) - Learn how to configure and manage your Auth0 tenant and applications
    * [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
  </Content>

  <SideMenu>
    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```ts main.ts lines highlight={} theme={null}
        import { createApp } from "vue";
        import App from "./App.vue";
        import router from "./router";

        import { IonicVue } from "@ionic/vue";

        import { createAuth0 } from "@auth0/auth0-vue";
        import config from "./auth.config";

        // ..

        // Build the URL that Auth0 should redirect back to
        const redirect_uri = `${config.appId}://{yourDomain}/capacitor/${config.appId}/callback`;

        const app = createApp(App).use(IonicVue).use(router);

        app.use(
          createAuth0({
            domain: "{yourDomain}",
            clientId: "{yourClientId}",
            useRefreshTokens: true,
            useRefreshTokensFallback: false,
            authorizationParams: {
              redirect_uri
            }
          })
        );

        router.isReady().then(() => {
          app.mount("#app");
        });
        ```

        ```html LoginButton.vue lines highlight={} theme={null}
        <template>
          <ion-button @click="login">Log in</ion-button>
        </template>

        <script lang="ts">
        import { defineComponent } from "vue";
        import { IonApp, IonRouterOutlet } from "@ionic/vue";

        import { useAuth0 } from "@auth0/auth0-vue";
        import { App as CapApp } from "@capacitor/app";
        import { Browser } from "@capacitor/browser";

        export default defineComponent({
          components: {
            IonButton,
          },
          setup() {
            const { loginWithRedirect } = useAuth0();

            const login = async () => {
              await loginWithRedirect({
                openUrl: (url: string) =>
                  Browser.open({
                    url,
                    windowName: "_self",
                  }),
              });
            };

            return { login };
          },
        });
        </script>
        ```

        ```html LogoutButton.vue lines highlight={} theme={null}
        <template>
          <ion-button @click="onLogout">Log out</ion-button>
        </template>

        <script lang="ts">
        import { defineComponent } from "vue";
        import { useAuth0 } from "@auth0/auth0-vue";
        import { Browser } from "@capacitor/browser";
        import { IonButton } from "@ionic/vue";
        import { callbackUri } from "../auth.config";

        export default defineComponent({
          components: {
            IonButton,
          },
          setup() {
            const { logout } = useAuth0();

            const onLogout = async () => {
              await logout({
                logoutParams: {
                  returnTo: callbackUri,
                },
                openUrl: (url: string) =>
                  Browser.open({
                    url,
                    windowName: "_self",
                  }),
              });
            };

            return {
              onLogout,
            };
          },
        });
        </script>
        ```

        ```html UserProfile.vue lines highlight={} theme={null}
        <template>
          <div v-if="isLoading">Loading ...</div>
          <div v-else-if="!user"></div>
          <div v-else class="profile-container">
            <ion-avatar>
              <img :src="user.picture" :alt="user.name" />
            </ion-avatar>
            <h2>{{ user.name }}</h2>
            <p>{{ user.email }}</p>
          </div>
        </template>

        <script lang="ts">
        import { defineComponent } from "vue";
        import { useAuth0 } from "@auth0/auth0-vue";
        import { IonAvatar } from "@ionic/vue";

        export default defineComponent({
          components: {
            IonAvatar,
          },
          setup() {
            const { user, isLoading } = useAuth0();

            return { user, isLoading };
          },
        });
        </script>
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```html LoginButton.vue lines highlight={} theme={null}
        <template>
          <ion-button @click="login">Log in</ion-button>
        </template>

        <script lang="ts">
        import { defineComponent } from "vue";
        import { IonApp, IonRouterOutlet } from "@ionic/vue";

        import { useAuth0 } from "@auth0/auth0-vue";
        import { App as CapApp } from "@capacitor/app";
        import { Browser } from "@capacitor/browser";

        export default defineComponent({
          components: {
            IonButton,
          },
          setup() {
            const { loginWithRedirect } = useAuth0();

            const login = async () => {
              await loginWithRedirect({
                openUrl: (url: string) =>
                  Browser.open({
                    url,
                    windowName: "_self",
                  }),
              });
            };

            return { login };
          },
        });
        </script>
        ```

        ```ts main.ts lines highlight={} theme={null}
        import { createApp } from "vue";
        import App from "./App.vue";
        import router from "./router";

        import { IonicVue } from "@ionic/vue";

        import { createAuth0 } from "@auth0/auth0-vue";
        import config from "./auth.config";

        // ..

        // Build the URL that Auth0 should redirect back to
        const redirect_uri = `${config.appId}://{yourDomain}/capacitor/${config.appId}/callback`;

        const app = createApp(App).use(IonicVue).use(router);

        app.use(
          createAuth0({
            domain: "{yourDomain}",
            clientId: "{yourClientId}",
            useRefreshTokens: true,
            useRefreshTokensFallback: false,
            authorizationParams: {
              redirect_uri
            }
          })
        );

        router.isReady().then(() => {
          app.mount("#app");
        });
        ```

        ```html LogoutButton.vue lines highlight={} theme={null}
        <template>
          <ion-button @click="onLogout">Log out</ion-button>
        </template>

        <script lang="ts">
        import { defineComponent } from "vue";
        import { useAuth0 } from "@auth0/auth0-vue";
        import { Browser } from "@capacitor/browser";
        import { IonButton } from "@ionic/vue";
        import { callbackUri } from "../auth.config";

        export default defineComponent({
          components: {
            IonButton,
          },
          setup() {
            const { logout } = useAuth0();

            const onLogout = async () => {
              await logout({
                logoutParams: {
                  returnTo: callbackUri,
                },
                openUrl: (url: string) =>
                  Browser.open({
                    url,
                    windowName: "_self",
                  }),
              });
            };

            return {
              onLogout,
            };
          },
        });
        </script>
        ```

        ```html UserProfile.vue lines highlight={} theme={null}
        <template>
          <div v-if="isLoading">Loading ...</div>
          <div v-else-if="!user"></div>
          <div v-else class="profile-container">
            <ion-avatar>
              <img :src="user.picture" :alt="user.name" />
            </ion-avatar>
            <h2>{{ user.name }}</h2>
            <p>{{ user.email }}</p>
          </div>
        </template>

        <script lang="ts">
        import { defineComponent } from "vue";
        import { useAuth0 } from "@auth0/auth0-vue";
        import { IonAvatar } from "@ionic/vue";

        export default defineComponent({
          components: {
            IonAvatar,
          },
          setup() {
            const { user, isLoading } = useAuth0();

            return { user, isLoading };
          },
        });
        </script>
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```ts main.ts lines highlight={} theme={null}
        import { createApp } from "vue";
        import App from "./App.vue";
        import router from "./router";

        import { IonicVue } from "@ionic/vue";

        import { createAuth0 } from "@auth0/auth0-vue";
        import config from "./auth.config";

        // ..

        // Build the URL that Auth0 should redirect back to
        const redirect_uri = `${config.appId}://{yourDomain}/capacitor/${config.appId}/callback`;

        const app = createApp(App).use(IonicVue).use(router);

        app.use(
          createAuth0({
            domain: "{yourDomain}",
            clientId: "{yourClientId}",
            useRefreshTokens: true,
            useRefreshTokensFallback: false,
            authorizationParams: {
              redirect_uri
            }
          })
        );

        router.isReady().then(() => {
          app.mount("#app");
        });
        ```

        ```html LoginButton.vue lines highlight={} theme={null}
        <template>
          <ion-button @click="login">Log in</ion-button>
        </template>

        <script lang="ts">
        import { defineComponent } from "vue";
        import { IonApp, IonRouterOutlet } from "@ionic/vue";

        import { useAuth0 } from "@auth0/auth0-vue";
        import { App as CapApp } from "@capacitor/app";
        import { Browser } from "@capacitor/browser";

        export default defineComponent({
          components: {
            IonButton,
          },
          setup() {
            const { loginWithRedirect } = useAuth0();

            const login = async () => {
              await loginWithRedirect({
                openUrl: (url: string) =>
                  Browser.open({
                    url,
                    windowName: "_self",
                  }),
              });
            };

            return { login };
          },
        });
        </script>
        ```

        ```html LogoutButton.vue lines highlight={} theme={null}
        <template>
          <ion-button @click="onLogout">Log out</ion-button>
        </template>

        <script lang="ts">
        import { defineComponent } from "vue";
        import { useAuth0 } from "@auth0/auth0-vue";
        import { Browser } from "@capacitor/browser";
        import { IonButton } from "@ionic/vue";
        import { callbackUri } from "../auth.config";

        export default defineComponent({
          components: {
            IonButton,
          },
          setup() {
            const { logout } = useAuth0();

            const onLogout = async () => {
              await logout({
                logoutParams: {
                  returnTo: callbackUri,
                },
                openUrl: (url: string) =>
                  Browser.open({
                    url,
                    windowName: "_self",
                  }),
              });
            };

            return {
              onLogout,
            };
          },
        });
        </script>
        ```

        ```html UserProfile.vue lines highlight={} theme={null}
        <template>
          <div v-if="isLoading">Loading ...</div>
          <div v-else-if="!user"></div>
          <div v-else class="profile-container">
            <ion-avatar>
              <img :src="user.picture" :alt="user.name" />
            </ion-avatar>
            <h2>{{ user.name }}</h2>
            <p>{{ user.email }}</p>
          </div>
        </template>

        <script lang="ts">
        import { defineComponent } from "vue";
        import { useAuth0 } from "@auth0/auth0-vue";
        import { IonAvatar } from "@ionic/vue";

        export default defineComponent({
          components: {
            IonAvatar,
          },
          setup() {
            const { user, isLoading } = useAuth0();

            return { user, isLoading };
          },
        });
        </script>
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```html LogoutButton.vue lines highlight={} theme={null}
        <template>
          <ion-button @click="onLogout">Log out</ion-button>
        </template>

        <script lang="ts">
        import { defineComponent } from "vue";
        import { useAuth0 } from "@auth0/auth0-vue";
        import { Browser } from "@capacitor/browser";
        import { IonButton } from "@ionic/vue";
        import { callbackUri } from "../auth.config";

        export default defineComponent({
          components: {
            IonButton,
          },
          setup() {
            const { logout } = useAuth0();

            const onLogout = async () => {
              await logout({
                logoutParams: {
                  returnTo: callbackUri,
                },
                openUrl: (url: string) =>
                  Browser.open({
                    url,
                    windowName: "_self",
                  }),
              });
            };

            return {
              onLogout,
            };
          },
        });
        </script>
        ```

        ```ts main.ts lines highlight={} theme={null}
        import { createApp } from "vue";
        import App from "./App.vue";
        import router from "./router";

        import { IonicVue } from "@ionic/vue";

        import { createAuth0 } from "@auth0/auth0-vue";
        import config from "./auth.config";

        // ..

        // Build the URL that Auth0 should redirect back to
        const redirect_uri = `${config.appId}://{yourDomain}/capacitor/${config.appId}/callback`;

        const app = createApp(App).use(IonicVue).use(router);

        app.use(
          createAuth0({
            domain: "{yourDomain}",
            clientId: "{yourClientId}",
            useRefreshTokens: true,
            useRefreshTokensFallback: false,
            authorizationParams: {
              redirect_uri
            }
          })
        );

        router.isReady().then(() => {
          app.mount("#app");
        });
        ```

        ```html LoginButton.vue lines highlight={} theme={null}
        <template>
          <ion-button @click="login">Log in</ion-button>
        </template>

        <script lang="ts">
        import { defineComponent } from "vue";
        import { IonApp, IonRouterOutlet } from "@ionic/vue";

        import { useAuth0 } from "@auth0/auth0-vue";
        import { App as CapApp } from "@capacitor/app";
        import { Browser } from "@capacitor/browser";

        export default defineComponent({
          components: {
            IonButton,
          },
          setup() {
            const { loginWithRedirect } = useAuth0();

            const login = async () => {
              await loginWithRedirect({
                openUrl: (url: string) =>
                  Browser.open({
                    url,
                    windowName: "_self",
                  }),
              });
            };

            return { login };
          },
        });
        </script>
        ```

        ```html UserProfile.vue lines highlight={} theme={null}
        <template>
          <div v-if="isLoading">Loading ...</div>
          <div v-else-if="!user"></div>
          <div v-else class="profile-container">
            <ion-avatar>
              <img :src="user.picture" :alt="user.name" />
            </ion-avatar>
            <h2>{{ user.name }}</h2>
            <p>{{ user.email }}</p>
          </div>
        </template>

        <script lang="ts">
        import { defineComponent } from "vue";
        import { useAuth0 } from "@auth0/auth0-vue";
        import { IonAvatar } from "@ionic/vue";

        export default defineComponent({
          components: {
            IonAvatar,
          },
          setup() {
            const { user, isLoading } = useAuth0();

            return { user, isLoading };
          },
        });
        </script>
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```html UserProfile.vue lines highlight={} theme={null}
        <template>
          <div v-if="isLoading">Loading ...</div>
          <div v-else-if="!user"></div>
          <div v-else class="profile-container">
            <ion-avatar>
              <img :src="user.picture" :alt="user.name" />
            </ion-avatar>
            <h2>{{ user.name }}</h2>
            <p>{{ user.email }}</p>
          </div>
        </template>

        <script lang="ts">
        import { defineComponent } from "vue";
        import { useAuth0 } from "@auth0/auth0-vue";
        import { IonAvatar } from "@ionic/vue";

        export default defineComponent({
          components: {
            IonAvatar,
          },
          setup() {
            const { user, isLoading } = useAuth0();

            return { user, isLoading };
          },
        });
        </script>
        ```

        ```ts main.ts lines highlight={} theme={null}
        import { createApp } from "vue";
        import App from "./App.vue";
        import router from "./router";

        import { IonicVue } from "@ionic/vue";

        import { createAuth0 } from "@auth0/auth0-vue";
        import config from "./auth.config";

        // ..

        // Build the URL that Auth0 should redirect back to
        const redirect_uri = `${config.appId}://{yourDomain}/capacitor/${config.appId}/callback`;

        const app = createApp(App).use(IonicVue).use(router);

        app.use(
          createAuth0({
            domain: "{yourDomain}",
            clientId: "{yourClientId}",
            useRefreshTokens: true,
            useRefreshTokensFallback: false,
            authorizationParams: {
              redirect_uri
            }
          })
        );

        router.isReady().then(() => {
          app.mount("#app");
        });
        ```

        ```html LoginButton.vue lines highlight={} theme={null}
        <template>
          <ion-button @click="login">Log in</ion-button>
        </template>

        <script lang="ts">
        import { defineComponent } from "vue";
        import { IonApp, IonRouterOutlet } from "@ionic/vue";

        import { useAuth0 } from "@auth0/auth0-vue";
        import { App as CapApp } from "@capacitor/app";
        import { Browser } from "@capacitor/browser";

        export default defineComponent({
          components: {
            IonButton,
          },
          setup() {
            const { loginWithRedirect } = useAuth0();

            const login = async () => {
              await loginWithRedirect({
                openUrl: (url: string) =>
                  Browser.open({
                    url,
                    windowName: "_self",
                  }),
              });
            };

            return { login };
          },
        });
        </script>
        ```

        ```html LogoutButton.vue lines highlight={} theme={null}
        <template>
          <ion-button @click="onLogout">Log out</ion-button>
        </template>

        <script lang="ts">
        import { defineComponent } from "vue";
        import { useAuth0 } from "@auth0/auth0-vue";
        import { Browser } from "@capacitor/browser";
        import { IonButton } from "@ionic/vue";
        import { callbackUri } from "../auth.config";

        export default defineComponent({
          components: {
            IonButton,
          },
          setup() {
            const { logout } = useAuth0();

            const onLogout = async () => {
              await logout({
                logoutParams: {
                  returnTo: callbackUri,
                },
                openUrl: (url: string) =>
                  Browser.open({
                    url,
                    windowName: "_self",
                  }),
              });
            };

            return {
              onLogout,
            };
          },
        });
        </script>
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>
  </SideMenu>
</Recipe>


# Add Native Facebook Login to Your iOS Application
Source: https://auth0.com/docs/quickstart/native/ios-swift-facebook-login/index



## Before You Start

Complete these prerequisites before following this quickstart:

1. **Set up Facebook Login SDK** - Install and configure the [Facebook Login SDK for iOS](https://developers.facebook.com/docs/facebook-login/). Create a Facebook app at [developers.facebook.com](https://developers.facebook.com). When done, your app should have Facebook Login working.
2. **Configure Auth0 for Facebook Native** - Configure your Auth0 application to use Facebook Native Sign In. See [Add Facebook Login to Native Apps](/docs/authenticate/identity-providers/social-identity-providers/facebook-native).

## Get Started

<Steps>
  <Step title="Configure Facebook Login permissions">
    Update the Facebook Login Button in your `ViewController` to request the correct permissions.

    Your app already supports Facebook Login, but to get a rich user profile you need to request `public_profile` and `email` permissions. You'll also add a delegate callback to kick off the Auth0 authentication flow.

    ```swift ViewController.swift lines theme={null}
    import FacebookLogin
    import UIKit

    class ViewController: UIViewController {

        override func viewDidLoad() {
            super.viewDidLoad()

            let fbLoginButton = FBLoginButton()
            // Request email and public_profile permissions
            fbLoginButton.permissions = ["email", "public_profile"]
            fbLoginButton.delegate = self
            view.addSubview(fbLoginButton)
        }

        private func performLogin(accessToken: AccessToken) {
            // Steps 2–4 will fill this in
        }
    }

    extension ViewController: LoginButtonDelegate {
        func loginButton(_ loginButton: FBLoginButton, didCompleteWith result: LoginManagerLoginResult?, error: (any Error)?) {
            if let error = error {
                // Handle Facebook login error
                print(error)
                return
            }
            if let result = result, let token = result.token {
                performLogin(accessToken: token)
            }
        }

        func loginButtonDidLogOut(_ loginButton: FBLoginButton) {
            // Handle logout
        }

        func loginButtonWillLogin(_ loginButton: FBLoginButton) -> Bool {
            return true
        }
    }
    ```

    <Info>
      The `email` permission is optional — the user must consent to sharing it. The email returned from Facebook will be **flagged as non-verified** on the Auth0 user profile.
    </Info>
  </Step>

  <Step title="Install and configure the Auth0 SDK">
    Add the Auth0.swift SDK to your project and configure your application credentials.

    **Add Auth0.swift via Swift Package Manager:**

    1. In Xcode, go to **File** → **Add Package Dependencies...**
    2. Enter the package URL: `https://github.com/auth0/Auth0.swift`
    3. Select the latest version and click **Add Package**

    **Add your Auth0 credentials to `Auth0.plist`:**

    Go to the **Applications** section of the [Auth0 Dashboard](https://manage.auth0.com/) and select the application where you enabled Facebook Native Sign In. Copy the **Domain** and **Client ID** values.

    Create a new property list file named `Auth0.plist` in your project and add the following:

    ```xml Auth0.plist lines theme={null}
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
        <key>ClientId</key>
        <string>YOUR_AUTH0_CLIENT_ID</string>
        <key>Domain</key>
        <string>{yourDomain}</string>
    </dict>
    </plist>
    ```

    Drag `Auth0.plist` into Xcode and ensure **Add to target** is checked for your app target.

    <Tip>
      The Auth0.swift SDK automatically reads credentials from `Auth0.plist`, so no additional initialization code is required.
    </Tip>
  </Step>

  <Step title="Fetch Facebook session access token">
    After Facebook Login succeeds, fetch a **session access token** from the Facebook API. Auth0 requires this token to verify the user's identity on the backend.

    Make a GET request to Facebook's `/oauth/access_token` endpoint using the `GraphRequest` class:

    ```swift ViewController.swift lines theme={null}
    import FacebookCore

    private func fetchSessionToken(accessToken: AccessToken, completion: @escaping (String?, Error?) -> Void) {
        let request = GraphRequest(graphPath: "oauth/access_token")
        request.parameters["grant_type"] = "fb_attenuate_token"
        request.parameters["client_id"] = facebookAppId()
        request.parameters["fb_exchange_token"] = accessToken.tokenString
        request.start { _, response, error in
            if let error = error {
                completion(nil, error)
                return
            }
            if let responseDict = response as? [String: Any],
               let token = responseDict["access_token"] as? String {
                completion(token, nil)
            }
        }
    }

    private func facebookAppId() -> String? {
        return Bundle.main.infoDictionary?["FacebookAppID"] as? String
    }
    ```

    <Info>
      The required query parameters are:

      * `grant_type`: `fb_attenuate_token`
      * `fb_exchange_token`: the token string from the Facebook `AccessToken`
      * `client_id`: your Facebook App ID (already in your `Info.plist` from the Facebook SDK setup)
    </Info>
  </Step>

  <Step title="Fetch Facebook user profile">
    Fetch the user's profile from Facebook. Auth0 uses this data to create or update the user's Auth0 profile.

    ```swift ViewController.swift lines theme={null}
    import FacebookCore

    private func fetchUserProfile(completion: @escaping ([String: Any]?, Error?) -> Void) {
        let request = GraphRequest(graphPath: "me")
        request.parameters["fields"] = "first_name,last_name,email"
        request.start { _, result, error in
            if let error = error {
                completion(nil, error)
                return
            }
            if let rawResponse = result as? [String: Any] {
                completion(rawResponse, nil)
            }
        }
    }
    ```

    <Tip>
      The `fields` parameter maps directly to the Facebook permissions you requested. Requesting `first_name`, `last_name`, and `email` is sufficient for Auth0 to create a complete user profile.
    </Tip>
  </Step>

  <Step title="Exchange tokens for Auth0 credentials">
    Use the session token and user profile from the previous steps to authenticate with Auth0 and receive Auth0 tokens.

    Call `login(facebookSessionAccessToken:profile:audience:scope:)` on the Auth0 authentication client:

    ```swift ViewController.swift lines theme={null}
    import Auth0

    private func exchangeToken(sessionToken: String, userProfile: [String: Any], completion: @escaping (Credentials?, Error?) -> Void) {
        Auth0.authentication()
            .login(
                facebookSessionAccessToken: sessionToken,
                profile: userProfile,
                audience: nil,
                scope: "openid profile email offline_access"
            )
            .start { result in
                switch result {
                case .success(let credentials):
                    completion(credentials, nil)
                case .failure(let error):
                    completion(nil, error)
                }
            }
    }
    ```

    <Info>
      Internally, Auth0.swift uses the token type `http://auth0.com/oauth/token-type/facebook-info-session-access-token` to route the request to the Facebook native connection.
    </Info>
  </Step>

  <Step title="Put it all together">
    Complete the `performLogin` method to chain all three steps: fetch session token → fetch user profile → exchange for Auth0 tokens.

    ```swift ViewController.swift lines theme={null}
    private func performLogin(accessToken: AccessToken) {
        fetchSessionToken(accessToken: accessToken) { [weak self] token, error in
            guard let self = self else { return }
            if let error = error {
                print("Session token error:", error)
                return
            }
            guard let token = token else { return }

            self.fetchUserProfile { userProfile, error in
                if let error = error {
                    print("Profile fetch error:", error)
                    return
                }
                guard let userProfile = userProfile else { return }

                self.exchangeToken(sessionToken: token, userProfile: userProfile) { credentials, error in
                    if let error = error {
                        print("Token exchange error:", error)
                        return
                    }
                    if let credentials = credentials {
                        // Authenticated! Store credentials and update UI
                        print("Access token:", credentials.accessToken)
                    }
                }
            }
        }
    }
    ```

    <Tip>
      Keep constants (Facebook permissions, Auth0 scopes) at the top of your class to avoid magic strings. Consider using `async/await` to flatten the nested callbacks if you target iOS 15+.
    </Tip>
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now be able to authenticate natively with Facebook. If the Facebook app is installed on the device, authentication is handled through the app directly — no browser required.
</Check>

***

## Troubleshooting & Advanced

<Accordion title="Common Issues & Solutions">
  ### Token exchange fails with authentication error

  **Solutions:**

  1. Verify your Auth0 application has **Facebook Native Sign In** enabled in the Dashboard
  2. Check that `FacebookAppID` in `Info.plist` matches the App ID in the Facebook Developer Console
  3. Ensure the `Auth0.plist` file is added to the correct target in Xcode
  4. Confirm the Facebook access token hasn't expired before calling `performLogin`

  ### Session token request returns an error

  **Fix:**

  * Verify `FacebookAppID` is correctly set in `Info.plist`
  * Ensure the `fb_exchange_token` is the raw token string (`accessToken.tokenString`)
  * Check that your Facebook app is not in Development Mode if testing with non-admin users

  ### `AuthenticationError`: "Connection not found"

  **Fix:**

  1. Go to Auth0 Dashboard → **Authentication** → **Social**
  2. Verify **Sign in with Facebook** is enabled
  3. Confirm **Facebook Native Social Login** is turned on in the connection settings
  4. Check the Auth0 application is associated with the Facebook connection

  ### User profile fields are missing

  * Confirm `"email"` and `"public_profile"` are in the `fbLoginButton.permissions` array
  * The user may have declined the `email` permission — handle a nil email gracefully
  * Verify the same fields are in the `request.parameters["fields"]` call in `fetchUserProfile`

  ### `Auth0.plist` not found

  * Ensure the file name is exactly `Auth0.plist` (case-sensitive)
  * In Xcode, check the file's **Target Membership** — it must be included in your app target
</Accordion>

<Accordion title="Production Considerations">
  ### Security Best Practices

  * **Secure token storage**: Use the `CredentialsManager` from Auth0.swift to store tokens securely in the iOS Keychain
  * **Refresh tokens**: Request `offline_access` scope and use `CredentialsManager` to silently refresh expired tokens
  * **Biometric protection**: Enable biometric authentication on `CredentialsManager` to protect stored credentials

  ### Facebook App Configuration

  * Switch your Facebook app from **Development Mode** to **Live** before releasing to the App Store
  * Ensure your app's Bundle ID is registered in the Facebook Developer Console
  * Review Facebook's [Data Policy](https://developers.facebook.com/policy/) requirements for apps using the Login SDK

  ### App Store Submission

  * Include Facebook Login in your app's privacy policy and App Store privacy nutrition label
  * Handle cases where the user denies the `email` permission — your app should function without it
  * Test on a real device before submitting; the Facebook SDK behaves differently on simulators
</Accordion>

<Accordion title="Async/Await Alternative">
  If you target iOS 15+, you can use async/await to write cleaner, non-nested code:

  ```swift ViewController.swift expandable lines theme={null}
  @MainActor
  private func performLogin(accessToken: AccessToken) async {
      do {
          let sessionToken = try await fetchSessionTokenAsync(accessToken: accessToken)
          let userProfile = try await fetchUserProfileAsync()
          let credentials = try await exchangeTokenAsync(sessionToken: sessionToken, userProfile: userProfile)
          // Authenticated! Store credentials and update UI
          print("Access token:", credentials.accessToken)
      } catch {
          print("Authentication failed:", error)
      }
  }
  ```

  Wrap each callback-based method in a `withCheckedThrowingContinuation` to bridge to async/await.
</Accordion>

***

## Next Steps

<CardGroup>
  <Card title="Configure other identity providers" icon="key" href="/docs/authenticate/identity-providers">
    Add Google, Apple, and other social login providers
  </Card>

  <Card title="Attack Protection" icon="shield" href="/docs/secure/attack-protection">
    Protect against brute force and bot attacks
  </Card>

  <Card title="Actions" icon="bolt" href="/docs/customize/actions/actions-overview">
    Customize authentication flows with serverless code
  </Card>

  <Card title="iOS SDK Reference" icon="apple" href="/docs/libraries/auth0-swift">
    Explore the full Auth0.swift SDK documentation
  </Card>
</CardGroup>


# Add Login to Your iOS or macOS Application using the Auth0.swift SDK
Source: https://auth0.com/docs/quickstart/native/ios-swift/index



## Get Started

<Steps>
  <Step title="Create a new project">
    Create a new iOS or macOS project for this quickstart.

    **In Xcode:**

    1. **File** → **New** → **Project** (or **⌘+Shift+N**)
    2. Select either:
       * **iOS** tab → **App** template
       * **macOS** tab → **App** template
    3. Configure your project:
       * **Product Name**: `Auth0-Sample`
       * **Interface**: SwiftUI
       * **Language**: Swift
       * **Use Core Data**: Unchecked
       * **Include Tests**: Checked (recommended)
    4. Choose a location and click **Create**

    <Tip>
      This creates a standard app with SwiftUI and Swift Package Manager support, perfect for Auth0 integration.
    </Tip>
  </Step>

  <Step title="Add the Auth0 SDK">
    Add the Auth0 SDK to your project using your preferred package manager.

    <Tabs>
      <Tab title="Swift Package Manager">
        **In Xcode:**

        1. **File** → **Add Package Dependencies...** (or **⌘+Shift+K**)
        2. Enter the Auth0 SDK URL:
           ```
           https://github.com/auth0/Auth0.swift
           ```
        3. **Add Package** → Select your app target → **Add Package**
      </Tab>

      <Tab title="CocoaPods">
        1. Create a `Podfile` in your project directory:
           ```ruby Podfile theme={null}
           platform :ios, '14.0' # Or platform :osx, '11.0' for macOS
           use_frameworks!

           target 'YourApp' do
             pod 'Auth0', '~> 2.0'
           end
           ```
        2. Install the dependencies:
           ```bash theme={null}
           pod install
           ```
        3. Open the generated `.xcworkspace` file (not `.xcodeproj`)
      </Tab>

      <Tab title="Carthage">
        1. Create a `Cartfile` in your project directory:
           ```text Cartfile theme={null}
           github "auth0/Auth0.swift" ~> 2.0
           ```
        2. Run Carthage:
           ```bash theme={null}
           carthage update --platform iOS --use-xcframeworks
           ```
           For macOS, use `--platform macOS`
        3. Drag the generated `Auth0.xcframework` from `Carthage/Build` into your Xcode project
        4. In your target's **General** settings, add `Auth0.xcframework` to **Frameworks, Libraries, and Embedded Content**
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure Auth0">
    Create a new Auth0 application and configure callback URLs.

    1. Go to [Auth0 Dashboard](https://manage.auth0.com/dashboard/)
    2. **Applications** > **Create Application** > Name it, select **Native** > **Create**
    3. In the **Settings** tab, note your **Client ID** and **Domain**
    4. Add the following URLs to **Allowed Callback URLs**:

    <Tabs>
      <Tab title="iOS">
        ```
        https://{yourDomain}/ios/YOUR_BUNDLE_IDENTIFIER/callback,
        YOUR_BUNDLE_IDENTIFIER://{yourDomain}/ios/YOUR_BUNDLE_IDENTIFIER/callback
        ```
      </Tab>

      <Tab title="macOS">
        ```
        https://{yourDomain}/macos/YOUR_BUNDLE_IDENTIFIER/callback,
        YOUR_BUNDLE_IDENTIFIER://{yourDomain}/macos/YOUR_BUNDLE_IDENTIFIER/callback
        ```
      </Tab>
    </Tabs>

    5. Add the following URLs to **Allowed Logout URLs**:

    <Tabs>
      <Tab title="iOS">
        ```
        https://{yourDomain}/ios/YOUR_BUNDLE_IDENTIFIER/callback,
        YOUR_BUNDLE_IDENTIFIER://{yourDomain}/ios/YOUR_BUNDLE_IDENTIFIER/callback
        ```
      </Tab>

      <Tab title="macOS">
        ```
        https://{yourDomain}/macos/YOUR_BUNDLE_IDENTIFIER/callback,
        YOUR_BUNDLE_IDENTIFIER://{yourDomain}/macos/YOUR_BUNDLE_IDENTIFIER/callback
        ```
      </Tab>
    </Tabs>

    6. Click **Save Changes**
  </Step>

  <Step title="Configure App Credentials">
    Create `Auth0.plist` in your project directory:

    ```xml Auth0.plist theme={null}
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
        <key>ClientId</key>
        <string>YOUR_AUTH0_CLIENT_ID</string>
        <key>Domain</key>
        <string>{yourDomain}</string>
    </dict>
    </plist>
    ```

    Drag `Auth0.plist` into Xcode and ensure "Add to target" is checked.
  </Step>

  <Step title="Create the Authentication Service">
    Create `AuthenticationService.swift`:

    1. Right-click your project → **New File...** → **Swift File**
    2. Name it `AuthenticationService`
    3. Replace contents with:

    ```swift AuthenticationService.swift expandable lines theme={null}
    import Foundation
    import Auth0
    import Combine

    @MainActor
    class AuthenticationService: ObservableObject {
        @Published var isAuthenticated = false
        @Published var user: User?
        @Published var isLoading = false
        @Published var errorMessage: String?
        
        private let credentialsManager = CredentialsManager(authentication: Auth0.authentication())
        
        init() {
            Task {
                await checkAuthenticationStatus()
            }
        }
        
        private func checkAuthenticationStatus() async {
            isLoading = true
            defer { isLoading = false }
            
            guard let credentials = try? await credentialsManager.credentials() else {
                isAuthenticated = false
                return
            }
            
            isAuthenticated = true
            // Get user info from the ID token
            user = credentials.user
        }
        
        func login() async {
            isLoading = true
            errorMessage = nil
            defer { isLoading = false }
            
            do {
                let credentials = try await Auth0
                    .webAuth()
                    .scope("openid profile email offline_access")
                    .start()
                
                _ = credentialsManager.store(credentials: credentials)
                isAuthenticated = true
                // Get user info from the ID token
                user = credentials.user
            } catch {
                errorMessage = "Login failed: \(error.localizedDescription)"
            }
        }
        
        func logout() async {
            isLoading = true
            defer { isLoading = false }
            
            do {
                try await Auth0
                  .webAuth()
                  .clearSession()
                _ = credentialsManager.clear()
                isAuthenticated = false
                user = nil
            } catch {
                errorMessage = "Logout failed: \(error.localizedDescription)"
            }
        }
    }
    ```
  </Step>

  <Step title="Configure Authentication Flow (Optional)">
    To improve the user experience, you can minimize system alerts in the following ways:

    1. Use Universal Links: This eliminates the 'Open in "AppName"?' prompt that appears during the redirect. Note: The ASWebAuthenticationSession permission alert will still appear.
    2. Use Ephemeral Sessions: This eliminates all permission alerts. Note: This disables Single Sign-On (SSO) and shared cookies.

    <Tip>
      **Skip this step** to use the default behavior with a permission alert. You can configure this later.
    </Tip>

    <Tabs>
      <Tab title="Universal Links">
        1. Auth0 Dashboard → **Applications** → Your app → **Settings** → **Advanced Settings** → **Device Settings**
        2. Add **Apple Team ID** and **bundle identifier** → **Save**
        3. Xcode: Target → **Signing & Capabilities** → **+ Capability** → **Associated Domains**
        4. Add: `webcredentials:{yourDomain}`

        <Warning>Requires: Paid Apple Developer account, iOS 17.4+/macOS 14.4+</Warning>

        <Tip>
          Best for production apps.
        </Tip>
      </Tab>

      <Tab title="Ephemeral Session">
        Add `.useEphemeralSession()` to the login call in `AuthenticationService.swift`:

        ```swift theme={null}
        // In the login() function
        let credentials = try await Auth0
            .webAuth()
            .scope("openid profile email offline_access")
            .useEphemeralSession()
            .start()
        ```

        <Info>
          When using ephemeral sessions, you don't need to call `clearSession()` on logout. Just clear the credentials from your app - there's no shared cookie to remove.
        </Info>

        <Tip>
          Quick setup, no alerts, but users must log in every time (no SSO).
        </Tip>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Run your app">
    Press **⌘+R** in Xcode.

    1. Tap "Log In" → Permission alert (if using default) → Tap "Continue"
    2. Complete login in browser
    3. See your profile!
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You now have a fully functional Auth0 login in your iOS or macOS app!
</Check>

***

## Troubleshooting & Advanced

<Accordion title="Common Issues & Solutions">
  ### Build errors: 'Auth0' module not found

  **Solutions**:

  1. **Swift Package Manager**: Check **Package Dependencies** → Verify `Auth0.swift` is listed
  2. **CocoaPods**: Ensure you're opening the `.xcworkspace` file, not `.xcodeproj`
  3. **Carthage**: Verify `Auth0.xcframework` is added to **Frameworks, Libraries, and Embedded Content**
  4. Clean and rebuild: **⌘+Shift+K** then **⌘+R**
  5. Restart Xcode if needed

  ### App crashes: 'Auth0.plist not found'

  **Fix**:

  1. Verify `Auth0.plist` is in your Xcode project navigator
  2. Select the file → Inspector → Ensure your app target is checked
  3. Confirm it has `ClientId` and `Domain` keys with your values
  4. **Alternative**: Use programmatic configuration (see Advanced Integration section below)

  ### Browser opens but never returns to app

  **Fix**:

  1. Check callback URLs in Auth0 Dashboard match your bundle identifier and platform exactly
  2. For iOS: URLs should contain `/ios/`, for macOS: `/macos/`
  3. Verify bundle identifier in Xcode matches Auth0 settings
  4. Ensure no typos in URLs (common: missing colons, wrong domain format)
  5. **Custom domain users**: Verify you're using your custom domain, not the Auth0 domain

  ### Permission alert appears every time

  This is standard iOS/macOS security behavior when using custom URL schemes. See **Step 6** to eliminate this alert using Universal Links or Ephemeral Sessions.
</Accordion>

<Accordion title="Custom Domain Configuration">
  If you're using a [custom domain](/customize/custom-domains), use its value instead of your Auth0 domain everywhere.

  **Example:** Use `login.example.com` instead of `tenant.auth0.com`

  This is **required** for certain features to work properly:

  * Update `Auth0.plist` with your custom domain
  * Use custom domain in callback/logout URLs
  * For Universal Links, use: `webcredentials:login.example.com`
</Accordion>

<Accordion title="Production Deployment">
  ### App Store Preparation

  * Configure Universal Links to eliminate the permission alert
  * Test on multiple platform versions and device sizes
  * Implement proper error handling for network failures
  * Add Privacy Usage descriptions if using Keychain with biometrics
  * Follow App Store Review Guidelines for authentication flows

  ### Security Best Practices

  * Never log sensitive authentication data in production
  * Implement App Transport Security (ATS) compliance
  * Use HTTPS for all network requests
  * **Do NOT** pin Auth0 API certificates - [Auth0 does not recommend this practice](/troubleshoot/product-lifecycle/past-migrations#avoid-pinning-or-fingerprinting-tls-certificates-for-auth0-endpoints)

  ### Performance Optimization

  * All async operations properly use `@MainActor` for UI updates
  * `@Published` properties use proper memory handling
  * Credentials are cached securely in the Keychain for offline access
  * User profile is retrieved from ID token (no additional network request)
</Accordion>

<Accordion title="Advanced Integration">
  ### Programmatic Configuration

  Instead of using `Auth0.plist`, you can pass credentials directly in your code. This is useful when credentials need to be dynamic or environment-specific (e.g., different Auth0 tenants for dev/staging/production).

  **Replace `Auth0.webAuth()` calls with `Auth0.webAuth(clientId:domain:)`:**

  ```swift theme={null}
  // In AuthenticationService.swift - login function
  func login() async {
      isLoading = true
      errorMessage = nil
      defer { isLoading = false }
      
      do {
          let credentials = try await Auth0
              .webAuth(clientId: "{yourClientId}", domain: "{yourDomain}")
              .scope("openid profile email offline_access")
              .start()
          
          _ = credentialsManager.store(credentials: credentials)
          isAuthenticated = true
          user = credentials.user
      } catch {
          errorMessage = "Login failed: \(error.localizedDescription)"
      }
  }

  // In AuthenticationService.swift - logout function
  func logout() async {
      isLoading = true
      defer { isLoading = false }
      
      do {
          try await Auth0.webAuth(clientId: "{yourClientId}", domain: "{yourDomain}").clearSession()
          _ = credentialsManager.clear()
          isAuthenticated = false
          user = nil
      } catch {
          errorMessage = "Logout failed: \(error.localizedDescription)"
      }
  }
  ```

  ### Enhanced Keychain Security with Biometrics

  Require Face ID or Touch ID to access stored credentials:

  ```swift theme={null}
  private let credentialsManager: CredentialsManager = {
      let manager = CredentialsManager(authentication: Auth0.authentication())
      manager.enableBiometrics(
          withTitle: "Unlock with Face ID", 
          cancelTitle: "Cancel", 
          fallbackTitle: "Use Passcode"
      )
      return manager
  }()
  ```

  When enabled, users must authenticate with biometrics before the SDK can retrieve stored credentials.

  ### Automatic Token Refresh

  The `CredentialsManager` automatically refreshes expired access tokens:

  ```swift theme={null}
  // Get credentials - automatically refreshes if expired
  func getAccessToken() async throws -> String {
      let credentials = try await credentialsManager.credentials()
      return credentials.accessToken
  }
  ```

  Use this pattern when making API calls that require an access token.

  ### Shared Credentials Across App Extensions

  For widgets, app extensions, or background tasks that need access tokens:

  ```swift theme={null}
  // Create a shared credentials manager with an app group
  let credentialsManager = CredentialsManager(
      authentication: Auth0.authentication(),
      storeKey: "credentials",
      storage: .shared(withIdentifier: "group.com.example.myapp")
  )
  ```

  **Requirements:**

  1. Enable **App Groups** capability in Xcode for all targets
  2. Use the same app group identifier across targets
  3. Configure the shared `CredentialsManager` in each target

  ### Authentication Flow Options Comparison

  | Feature                  | Universal Links              | Ephemeral Session | Default (Alert)  |
  | ------------------------ | ---------------------------- | ----------------- | ---------------- |
  | Permission Alert         | Reduced (no redirect prompt) | None              | Shows all alerts |
  | SSO Support              | Yes                          | No                | Yes              |
  | Apple Developer Account  | Required                     | Not required      | Not required     |
  | User Experience          | Best                         | Good              | Acceptable       |
  | Setup Complexity         | Medium                       | Easy              | Easy             |
  | Private Browsing Support | Yes                          | Yes               | No               |

  **Recommendations:**

  * **Production apps with SSO**: Universal Links (better UX, SSO support, requires Apple Developer account)
  * **Production apps without SSO**: Ephemeral Sessions (no alerts, simpler setup)
  * **Testing/Development**: Ephemeral Sessions (quick setup, cleanest UX)
  * **Quick start/Prototyping**: Default with alerts (no setup, can migrate later)
</Accordion>


# Add Login to Your MAUI Application
Source: https://auth0.com/docs/quickstart/native/maui/interactive

This tutorial demonstrates how to add user login with Auth0 to a .NET MAUI application.

<QuickstartButtons />

<Recipe>
  <Content>
    Auth0 allows you to add authentication to almost any application type quickly. This guide demonstrates how to
    integrate Auth0, add authentication, and display user profile information in any .NET MAUI application using the
    Auth0 SDKs for [MAUI](https://www.nuget.org/packages/Auth0.OidcClient.MAUI/).

    <Info>
      The MAUI SDK supports Android, iOS, macOS, and Windows. Continue reading for platform-specific
      configuration.
    </Info>

    <Section title={sections[0].title}>
      To use Auth0 services, you’ll need to have an application set up in the Auth0 Dashboard. The Auth0 application is
      where you will configure how you want authentication to work for the project you are developing.

      ### Configure an application

      Use the interactive selector to create a new Auth0 application or select an existing application that represents
      the project you want to integrate with. Every application in Auth0 is assigned an alphanumeric, unique client ID
      that your application code will use to call Auth0 APIs through the SDK.

      Any settings you configure using this quickstart will automatically update for your Application in the [Dashboard](https://manage.auth0.com/#/), which is where you
      can manage your Applications in the future.

      If you would rather explore a complete configuration, you can view a sample application instead.

      ### Configure Callback URLs

      A callback URL is a URL in your application that you would like Auth0 to redirect users to after they have
      authenticated. If not set, users will not be returned to your application after they log in.

      <Info>
        If you are following along with our sample project, set this to `myapp://callback`.
      </Info>

      ### Configure Logout URLs

      A logout URL is a URL in your application that you would like Auth0 to redirect users to after they have logged
      out. If not set, users will not be able to log out from your application and will receive an error.

      <Info>
        If you are following along with our sample project, set this to `myapp://callback`.
      </Info>
    </Section>

    <Section title={sections[1].title}>
      Auth0 provides a [MAUI](https://www.nuget.org/packages/Auth0.OidcClient.MAUI/) SDK to simplify the process of implementing Auth0 authentication in MAUI
      applications.

      Use the NuGet Package Manager (Tools -> Library Package Manager -> Package Manager Console) to install the
      `Auth0.OidcClient.MAUI` package.

      Alternatively, you can use the NuGet Package Manager Console (`Install-Package`) or the
      `dotnet` CLI (`dotnet add`).

      ```
      Install-Package Auth0.OidcClient.MAUI
      ```

      ```
      dotnet add package Auth0.OidcClient.MAUI
      ```
    </Section>

    <Section title={sections[2].title}>
      You need some platform-specific configuration to use the SDK with Android and Windows.

      ### Android

      Create a new Activity that extends `WebAuthenticatorCallbackActivity`:

      ```cs lines theme={null}
      [Activity(NoHistory = true, LaunchMode = LaunchMode.SingleTop, Exported = true)]
      [IntentFilter(new[] { Intent.ActionView },
      Categories = new[] { Intent.CategoryDefault, Intent.CategoryBrowsable },
      DataScheme = CALLBACK_SCHEME)]
      public class WebAuthenticatorActivity : Microsoft.Maui.Authentication.WebAuthenticatorCallbackActivity
      {
      const string CALLBACK_SCHEME = "myapp";
      }
      ```

      The above activity will ensure the application can handle the `myapp://callback` URL when Auth0
      redirects back to the Android application after logging in.

      ### Windows

      To make sure it can properly reactivate your application after being redirected back to Auth0, you need to do two
      things:

      * Add the corresponding protocol to the `Package.appxmanifest`. In this case, this is set to
        `myapp`, but you can change this to whatever you like (ensure to update all relevant Auth0 URLs as
        well).

      ```xml lines theme={null}
      <Applications>
      <Application Id="App" Executable="$targetnametoken$.exe" EntryPoint="$targetentrypoint$">
      <Extensions>
      <uap:Extension Category="windows.protocol">
      <uap:Protocol Name="myapp"/>
      </uap:Extension>
      </Extensions>
      </Application>
      </Applications>
      ```

      * Call `Activator.Default.CheckRedirectionActivation()` in the Windows-specific
        `App.xaml.cs` file.

      ```cs lines theme={null}
      public App()
      {
      if (Auth0.OidcClient.Platforms.Windows.Activator.Default.CheckRedirectionActivation())
      return;
      this.InitializeComponent();
      }
      ```
    </Section>

    <Section title={sections[3].title}>
      To integrate Auth0 into your application, instantiate an instance of the `Auth0Client` class, passing
      an instance of `Auth0ClientOptions` that contains your Auth0 Domain, Client ID and the required Scopes.
      Additionally, you also need to configure the `RedirectUri` and `PostLogoutRedirectUri` to
      ensure Auth0 can redirect back to the application using the URL(s) configured.

      ```cs lines theme={null}
      using Auth0.OidcClient;
      var client = new Auth0Client(new Auth0ClientOptions {
      Domain = "{yourDomain}",
      ClientId = "{yourClientId}",
      RedirectUri = "myapp://callback",
      PostLogoutRedirectUri = "myapp://callback",
      Scope = "openid profile email"
      });
      ```

      By default, the SDK will leverage Chrome Custom Tabs for Android, ASWebAuthenticationSession for iOS and macOS
      and use your system's default browser on Windows.

      <Note>
        ##### Checkpoint

        Your `Auth0Client` should now be properly instantiated. Run your application to verify that:

        * The `Auth0Client`is instantiated correctly in the `MainPage`.
        * Your application is not throwing any errors related to Auth0.
      </Note>
    </Section>

    <Section title={sections[4].title}>
      Now that you have configured your Auth0 Application and the Auth0 SDK, you need to set up login for your project.
      To do this, you will use the SDK’s `LoginAsync()` method to create a login button that redirects users
      to the Auth0 Universal Login page.

      ```cs lines theme={null}
      var loginResult = await client.LoginAsync();
      ```

      If there isn't any error, you can access the `User`, `IdentityToken`,
      `AccessToken` and `RefreshToken` on the `LoginResult` returned from
      `LoginAsync()`.

      <Note>
        ##### Checkpoint

        You should now be able to log in or sign up using a username and password.

        Click the login button and verify that:

        * Your application redirects you to the Auth0 Universal Login page.
        * You can log in or sign up.
        * Auth0 redirects you to your application.
      </Note>
    </Section>

    <Section title={sections[5].title}>
      Users who log in to your project will also need a way to log out. Create a logout button using the SDK’s
      `LogoutAsync()` method. When users log out, they will be redirected to your Auth0 logout endpoint,
      which will then immediately redirect them back to the logout URL you set up earlier in this quickstart.

      ```cs lines theme={null}
      await client.LogoutAsync();
      ```

      <Note>
        ##### Checkpoint

        Run your application and click the logout button, verify that:

        * Your application redirects you to the address you specified as one of the Allowed Logout URLs in your
          Application Settings.
        * You are no longer logged in to your application.
      </Note>
    </Section>

    <Section title={sections[6].title}>
      Now that your users can log in and log out, you will likely want to be able to retrieve the [profile information](https://auth0.com/docs/users/concepts/overview-user-profile)
      associated with authenticated users. For example, you may want to be able to display a logged-in user’s name or
      profile picture in your project.

      The Auth0 SDK for MAUI provides user information through the `LoginResult.User` property.
    </Section>

    ## Next Steps

    Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.

    This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:

    * [Auth0 Dashboard](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq) - Learn how to configure and manage your Auth0 tenant and applications
    * [auth0-oidc-client-net SDK](https://github.com/auth0/auth0-oidc-client-net) - Explore the SDK used in this tutorial more fully
    * [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
  </Content>

  <SideMenu>
    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      ```cs MainPage.xaml.cs lines highlight={3-10} theme={null}
      public partial class MainPage : ContentPage
      {
          Auth0Client client = new Auth0Client(new Auth0ClientOptions
          {
              Domain = "{yourDomain}"
              ClientId = "{yourClientId}",
              RedirectUri = "myapp://callback",
              PostLogoutRedirectUri = "myapp://callback",
              Scope = "openid profile email"
          });

          public MainPage()
          {
              InitializeComponent();
          }

          private async void OnLoginClicked(object sender, EventArgs e)
          {
              var extraParameters = new Dictionary<string, string>();
              var audience = ""; // FILL WITH AUDIENCE AS NEEDED

              if (!string.IsNullOrEmpty(audience))
                  extraParameters.Add("audience", audience);

              var result = await client.LoginAsync(extraParameters);

              DisplayResult(result);
          }

          private async void OnLogoutClicked(object sender, EventArgs e)
          {
              BrowserResultType browserResult = await client.LogoutAsync();

              if (browserResult != BrowserResultType.Success)
              {
                  ErrorLabel.Text = browserResult.ToString();
                  return;
              }

              LogoutBtn.IsVisible = false;
              LoginBtn.IsVisible = true;

              HelloLabel.Text = $"Hello, World!";
              ErrorLabel.Text = "";
          }

          private void DisplayResult(LoginResult loginResult)
          {
              if (loginResult.IsError)
              {
                  ErrorLabel.Text = loginResult.Error;
                  return;
              }

              var user = loginResult.User;
              var name = user.FindFirst(c => c.Type == "name")?.Value;
              var email = user.FindFirst(c => c.Type == "email")?.Value;
              var picture = user.FindFirst(c => c.Type == "picture")?.Value;

              LogoutBtn.IsVisible = true;
              LoginBtn.IsVisible = false;

              HelloLabel.Text = $"Hello, {loginResult.User.Identity.Name}";
              ErrorLabel.Text = "";
          }
      }
      ```
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      ```cs MainPage.xaml.cs lines highlight={25} theme={null}
      public partial class MainPage : ContentPage
      {
          Auth0Client client = new Auth0Client(new Auth0ClientOptions
          {
              Domain = "{yourDomain}"
              ClientId = "{yourClientId}",
              RedirectUri = "myapp://callback",
              PostLogoutRedirectUri = "myapp://callback",
              Scope = "openid profile email"
          });

          public MainPage()
          {
              InitializeComponent();
          }

          private async void OnLoginClicked(object sender, EventArgs e)
          {
              var extraParameters = new Dictionary<string, string>();
              var audience = ""; // FILL WITH AUDIENCE AS NEEDED

              if (!string.IsNullOrEmpty(audience))
                  extraParameters.Add("audience", audience);

              var result = await client.LoginAsync(extraParameters);

              DisplayResult(result);
          }

          private async void OnLogoutClicked(object sender, EventArgs e)
          {
              BrowserResultType browserResult = await client.LogoutAsync();

              if (browserResult != BrowserResultType.Success)
              {
                  ErrorLabel.Text = browserResult.ToString();
                  return;
              }

              LogoutBtn.IsVisible = false;
              LoginBtn.IsVisible = true;

              HelloLabel.Text = $"Hello, World!";
              ErrorLabel.Text = "";
          }

          private void DisplayResult(LoginResult loginResult)
          {
              if (loginResult.IsError)
              {
                  ErrorLabel.Text = loginResult.Error;
                  return;
              }

              var user = loginResult.User;
              var name = user.FindFirst(c => c.Type == "name")?.Value;
              var email = user.FindFirst(c => c.Type == "email")?.Value;
              var picture = user.FindFirst(c => c.Type == "picture")?.Value;

              LogoutBtn.IsVisible = true;
              LoginBtn.IsVisible = false;

              HelloLabel.Text = $"Hello, {loginResult.User.Identity.Name}";
              ErrorLabel.Text = "";
          }
      }
      ```
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      ```cs MainPage.xaml.cs lines highlight={32} theme={null}
      public partial class MainPage : ContentPage
      {
          Auth0Client client = new Auth0Client(new Auth0ClientOptions
          {
              Domain = "{yourDomain}"
              ClientId = "{yourClientId}",
              RedirectUri = "myapp://callback",
              PostLogoutRedirectUri = "myapp://callback",
              Scope = "openid profile email"
          });

          public MainPage()
          {
              InitializeComponent();
          }

          private async void OnLoginClicked(object sender, EventArgs e)
          {
              var extraParameters = new Dictionary<string, string>();
              var audience = ""; // FILL WITH AUDIENCE AS NEEDED

              if (!string.IsNullOrEmpty(audience))
                  extraParameters.Add("audience", audience);

              var result = await client.LoginAsync(extraParameters);

              DisplayResult(result);
          }

          private async void OnLogoutClicked(object sender, EventArgs e)
          {
              BrowserResultType browserResult = await client.LogoutAsync();

              if (browserResult != BrowserResultType.Success)
              {
                  ErrorLabel.Text = browserResult.ToString();
                  return;
              }

              LogoutBtn.IsVisible = false;
              LoginBtn.IsVisible = true;

              HelloLabel.Text = $"Hello, World!";
              ErrorLabel.Text = "";
          }

          private void DisplayResult(LoginResult loginResult)
          {
              if (loginResult.IsError)
              {
                  ErrorLabel.Text = loginResult.Error;
                  return;
              }

              var user = loginResult.User;
              var name = user.FindFirst(c => c.Type == "name")?.Value;
              var email = user.FindFirst(c => c.Type == "email")?.Value;
              var picture = user.FindFirst(c => c.Type == "picture")?.Value;

              LogoutBtn.IsVisible = true;
              LoginBtn.IsVisible = false;

              HelloLabel.Text = $"Hello, {loginResult.User.Identity.Name}";
              ErrorLabel.Text = "";
          }
      }
      ```
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      ```cs MainPage.xaml.cs lines highlight={55-58} theme={null}
      public partial class MainPage : ContentPage
      {
          Auth0Client client = new Auth0Client(new Auth0ClientOptions
          {
              Domain = "{yourDomain}"
              ClientId = "{yourClientId}",
              RedirectUri = "myapp://callback",
              PostLogoutRedirectUri = "myapp://callback",
              Scope = "openid profile email"
          });

          public MainPage()
          {
              InitializeComponent();
          }

          private async void OnLoginClicked(object sender, EventArgs e)
          {
              var extraParameters = new Dictionary<string, string>();
              var audience = ""; // FILL WITH AUDIENCE AS NEEDED

              if (!string.IsNullOrEmpty(audience))
                  extraParameters.Add("audience", audience);

              var result = await client.LoginAsync(extraParameters);

              DisplayResult(result);
          }

          private async void OnLogoutClicked(object sender, EventArgs e)
          {
              BrowserResultType browserResult = await client.LogoutAsync();

              if (browserResult != BrowserResultType.Success)
              {
                  ErrorLabel.Text = browserResult.ToString();
                  return;
              }

              LogoutBtn.IsVisible = false;
              LoginBtn.IsVisible = true;

              HelloLabel.Text = $"Hello, World!";
              ErrorLabel.Text = "";
          }

          private void DisplayResult(LoginResult loginResult)
          {
              if (loginResult.IsError)
              {
                  ErrorLabel.Text = loginResult.Error;
                  return;
              }

              var user = loginResult.User;
              var name = user.FindFirst(c => c.Type == "name")?.Value;
              var email = user.FindFirst(c => c.Type == "email")?.Value;
              var picture = user.FindFirst(c => c.Type == "picture")?.Value;

              LogoutBtn.IsVisible = true;
              LoginBtn.IsVisible = false;

              HelloLabel.Text = $"Hello, {loginResult.User.Identity.Name}";
              ErrorLabel.Text = "";
          }
      }
      ```
    </SideMenuSectionItem>
  </SideMenu>
</Recipe>


# Add Login to Your .NET Android & iOS Application
Source: https://auth0.com/docs/quickstart/native/net-android-ios/index



## Get Started

<Steps>
  <Step title="Create a new .NET project">
    Create a new .NET MAUI or .NET Android/iOS project for this quickstart.

    <Tabs>
      <Tab title=".NET MAUI">
        **In Visual Studio 2022 or later:**

        1. **File** → **New** → **Project**
        2. Select **.NET MAUI App** template
        3. Configure your project:
           * **Project name**: `Auth0MauiSample`
           * **Location**: Choose your preferred location
           * **Framework**: **.NET 8.0 or later**
        4. Click **Create**
      </Tab>

      <Tab title=".NET Android">
        **In Visual Studio 2022 or later:**

        1. **File** → **New** → **Project**
        2. Select **Android App (.NET)** template
        3. Configure your project:
           * **Project name**: `Auth0AndroidSample`
           * **Framework**: **.NET 8.0 or later**
        4. Click **Create**
      </Tab>

      <Tab title=".NET iOS">
        **In Visual Studio 2022 (Mac) or Visual Studio for Mac:**

        1. **File** → **New** → **Project**
        2. Select **iOS App (.NET)** template
        3. Configure your project:
           * **Project name**: `Auth0iOSSample`
           * **Framework**: **.NET 8.0 or later**
        4. Click **Create**
      </Tab>
    </Tabs>

    <Info>
      This quickstart focuses on .NET Android and iOS, which are the next generation of Xamarin.Android and Xamarin.iOS. If you're still using Xamarin, you can follow this guide as the integration is identical and the SDKs are compatible.
    </Info>
  </Step>

  <Step title="Install Auth0 SDK">
    Add the Auth0 OIDC Client SDK to your project.

    <Tabs>
      <Tab title="Package Manager Console">
        Open the Package Manager Console (**View** → **Other Windows** → **Package Manager Console**) and install the appropriate package:

        **For .NET Android:**

        ```bash Package Manager Console theme={null}
        Install-Package Auth0.OidcClient.AndroidX
        ```

        **For .NET iOS:**

        ```bash Package Manager Console theme={null}
        Install-Package Auth0.OidcClient.iOS
        ```

        **For .NET MAUI (both platforms):**

        ```bash Package Manager Console theme={null}
        Install-Package Auth0.OidcClient.MAUI
        ```
      </Tab>

      <Tab title="Visual Studio for Mac">
        1. In the **Solution Pad**, Ctrl+click (or right-click) on the **Packages** folder
        2. Select **Add Packages...**
        3. Search for:
           * `Auth0.OidcClient.AndroidX` for Android
           * `Auth0.OidcClient.iOS` for iOS
           * `Auth0.OidcClient.MAUI` for MAUI projects
        4. Select the package and click **Add Package**
      </Tab>

      <Tab title=".NET CLI">
        Run the following command in your project directory:

        **For .NET Android:**

        ```bash Terminal theme={null}
        dotnet add package Auth0.OidcClient.AndroidX
        ```

        **For .NET iOS:**

        ```bash Terminal theme={null}
        dotnet add package Auth0.OidcClient.iOS
        ```

        **For .NET MAUI:**

        ```bash Terminal theme={null}
        dotnet add package Auth0.OidcClient.MAUI
        ```
      </Tab>
    </Tabs>

    <Tip>
      The Auth0 OIDC Client SDK handles all the OAuth 2.0 and OIDC protocol details, providing a simple API for authentication.
    </Tip>
  </Step>

  <Step title="Setup your Auth0 App">
    Create a new application in your Auth0 tenant and configure it for mobile.

    1. Head to the [Auth0 Dashboard](https://manage.auth0.com/dashboard/)
    2. Click on **Applications** → **Applications** → **Create Application**
    3. Enter a name for your app, select **Native** as the app type, and click **Create**
    4. Switch to the **Settings** tab on the Application Details page
    5. Note your **Domain** and **Client ID** - you'll need these in the next step

    **Configure Callback URLs:**

    On the **Settings** tab, add the following URLs:

    **Allowed Callback URLs:**

    <Tabs>
      <Tab title="Android">
        ```
        YOUR_ANDROID_PACKAGE_NAME://{yourDomain}/android/YOUR_ANDROID_PACKAGE_NAME/callback
        ```

        Replace:

        * `YOUR_ANDROID_PACKAGE_NAME` with your app's package name (e.g., `com.mycompany.myapp`)
        * `{yourDomain}` with your Auth0 domain (e.g., `dev-abc123.us.auth0.com`)

        Example: `com.mycompany.myapp://dev-abc123.us.auth0.com/android/com.mycompany.myapp/callback`
      </Tab>

      <Tab title="iOS">
        ```
        YOUR_BUNDLE_IDENTIFIER://{yourDomain}/ios/YOUR_BUNDLE_IDENTIFIER/callback
        ```

        Replace:

        * `YOUR_BUNDLE_IDENTIFIER` with your app's bundle identifier (e.g., `com.mycompany.myapp`)
        * `{yourDomain}` with your Auth0 domain (e.g., `dev-abc123.us.auth0.com`)

        Example: `com.mycompany.myapp://dev-abc123.us.auth0.com/ios/com.mycompany.myapp/callback`
      </Tab>
    </Tabs>

    **Allowed Logout URLs:**

    Use the same URLs as your callback URLs.

    <Warning>
      Ensure that callback and logout URLs are in **lowercase**. Mismatched URLs will cause authentication to fail.
    </Warning>

    <Info>
      **Allowed Callback URLs** are essential for security - they ensure users are safely returned to your application after authentication. Without a matching URL, the login process will fail.

      **Allowed Logout URLs** provide a seamless experience when users sign out, redirecting them back to your app instead of leaving them on an Auth0 page.
    </Info>
  </Step>

  <Step title="Initialize the Auth0 Client">
    Create an `Auth0Client` instance to communicate with Auth0.

    <Tabs>
      <Tab title="Android - MainActivity">
        ```cs MainActivity.cs lines theme={null}
        using Auth0.OidcClient;
        using Android.App;
        using Android.Content;

        [Activity(Label = "Auth0Sample", MainLauncher = true, Icon = "@drawable/icon",
            LaunchMode = LaunchMode.SingleTask)]
        [IntentFilter(
            new[] { Intent.ActionView },
            Categories = new[] { Intent.CategoryDefault, Intent.CategoryBrowsable },
            DataScheme = "YOUR_ANDROID_PACKAGE_NAME",
            DataHost = "{yourDomain}",
            DataPathPrefix = "/android/YOUR_ANDROID_PACKAGE_NAME/callback")]
        public class MainActivity : Activity
        {
            private Auth0Client auth0Client;

            protected override void OnCreate(Bundle savedInstanceState)
            {
                base.OnCreate(savedInstanceState);

                // Initialize Auth0 client
                auth0Client = new Auth0Client(new Auth0ClientOptions
                {
                    Domain = "{yourDomain}",
                    ClientId = "{yourClientId}"
                }, this);
            }

            protected override async void OnNewIntent(Intent intent)
            {
                base.OnNewIntent(intent);
                Auth0.OidcClient.ActivityMediator.Instance.Send(intent.DataString);
            }
        }
        ```

        <Warning>
          Replace `YOUR_ANDROID_PACKAGE_NAME`, `{yourDomain}`, and `{yourClientId}` with your actual values. Ensure all text in `DataScheme`, `DataHost`, and `DataPathPrefix` is **lowercase**.
        </Warning>

        <Info>
          The `IntentFilter` registers your app to handle the callback URL. The `LaunchMode.SingleTask` ensures Android doesn't create a new activity instance when the callback is invoked.
        </Info>
      </Tab>

      <Tab title="iOS - AppDelegate">
        First, register the URL scheme in your `Info.plist`:

        ```xml Info.plist lines theme={null}
        <key>CFBundleURLTypes</key>
        <array>
            <dict>
                <key>CFBundleTypeRole</key>
                <string>None</string>
                <key>CFBundleURLName</key>
                <string>Auth0</string>
                <key>CFBundleURLSchemes</key>
                <array>
                    <string>YOUR_BUNDLE_IDENTIFIER</string>
                </array>
            </dict>
        </array>
        ```

        Then, set up your `AppDelegate.cs`:

        ```cs AppDelegate.cs lines theme={null}
        using Auth0.OidcClient;
        using Foundation;
        using UIKit;

        [Register("AppDelegate")]
        public class AppDelegate : UIApplicationDelegate
        {
            private Auth0Client auth0Client;

            public override bool FinishedLaunching(UIApplication application, NSDictionary launchOptions)
            {
                // Initialize Auth0 client
                auth0Client = new Auth0Client(new Auth0ClientOptions
                {
                    Domain = "{yourDomain}",
                    ClientId = "{yourClientId}"
                });

                return true;
            }

            public override bool OpenUrl(UIApplication application, NSUrl url,
                string sourceApplication, NSObject annotation)
            {
                ActivityMediator.Instance.Send(url.AbsoluteString);
                return true;
            }
        }
        ```

        <Warning>
          Replace `YOUR_BUNDLE_IDENTIFIER`, `{yourDomain}`, and `{yourClientId}` with your actual values.
        </Warning>
      </Tab>
    </Tabs>

    <Tip>
      Store your Auth0 domain and client ID in a configuration file or app settings instead of hardcoding them for better maintainability.
    </Tip>
  </Step>

  <Step title="Implement Login and Logout">
    Add methods to handle user authentication.

    **Implement Login:**

    ```cs Authentication.cs lines theme={null}
    public async Task LoginAsync()
    {
        var loginResult = await auth0Client.LoginAsync();

        if (!loginResult.IsError)
        {
            // Authentication successful
            var accessToken = loginResult.AccessToken;
            var idToken = loginResult.IdentityToken;
            var user = loginResult.User;

            // Store credentials and update UI
            Console.WriteLine($"Logged in as: {user.FindFirst("name")?.Value}");
        }
        else
        {
            // Handle authentication error
            Console.WriteLine($"Login error: {loginResult.Error}");
        }
    }
    ```

    **Implement Logout:**

    ```cs Authentication.cs lines theme={null}
    public async Task LogoutAsync()
    {
        var logoutResult = await auth0Client.LogoutAsync();

        if (logoutResult == BrowserResultType.Success)
        {
            // Clear stored credentials
            // Update UI to logged-out state
            Console.WriteLine("Logged out successfully");
        }
    }
    ```

    <Info>
      The `LoginAsync()` method launches the system browser (or Chrome Custom Tabs on Android) to display Auth0's Universal Login page. After authentication, the user is redirected back to your app via the callback URL.
    </Info>

    <Tip>
      Add these methods to your MainActivity (Android) or a ViewController (iOS) and call them when users tap Login/Logout buttons.
    </Tip>
  </Step>

  <Step title="Run your app">
    Build and run your application.

    <Tabs>
      <Tab title="Visual Studio (Windows)">
        **For Android:**

        1. Select an Android emulator or connected device from the device dropdown
        2. Press **F5** or click the **Run** button
        3. The app will build, deploy, and launch

        **For iOS (requires Mac build host):**

        1. Connect to your Mac build host
        2. Select an iOS simulator or device from the device dropdown
        3. Press **F5** or click the **Run** button
      </Tab>

      <Tab title="Visual Studio for Mac">
        1. Select your target platform (Android/iOS) from the device dropdown
        2. Select an emulator/simulator or connected device
        3. Press **⌘+Return** or click the **Run** button
        4. The app will build and launch
      </Tab>

      <Tab title=".NET CLI">
        **For Android:**

        ```bash Terminal theme={null}
        dotnet build -f net8.0-android
        dotnet run -f net8.0-android
        ```

        **For iOS:**

        ```bash Terminal theme={null}
        dotnet build -f net8.0-ios
        dotnet run -f net8.0-ios
        ```
      </Tab>
    </Tabs>

    **Expected flow:**

    1. App launches with Login button
    2. Tap **Log In** → Browser/Chrome Custom Tab opens → Complete authentication
    3. Redirects back to your app automatically
    4. User is authenticated successfully

    <Tip>
      On first run, iOS may prompt you to confirm opening the browser for authentication. This is normal and expected behavior.
    </Tip>
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You now have a fully functional Auth0 login experience in your .NET Android or iOS application. The app uses the system browser for secure authentication and automatically handles the callback flow.
</Check>

***

## Access User Information

After successful authentication, you can access user information from the login result.

### Authentication Result

The `LoginAsync()` method returns a `LoginResult` object containing:

```cs UserInfo.cs lines theme={null}
var loginResult = await auth0Client.LoginAsync();

if (!loginResult.IsError)
{
    // Access tokens
    var accessToken = loginResult.AccessToken;
    var idToken = loginResult.IdentityToken;
    var refreshToken = loginResult.RefreshToken;

    // Access user claims
    var user = loginResult.User;
    var name = user.FindFirst("name")?.Value;
    var email = user.FindFirst("email")?.Value;
    var picture = user.FindFirst("picture")?.Value;

    Console.WriteLine($"Name: {name}");
    Console.WriteLine($"Email: {email}");
}
```

### Iterate Through All Claims

To see all available user information:

```cs UserClaims.cs lines theme={null}
if (!loginResult.IsError)
{
    foreach (var claim in loginResult.User.Claims)
    {
        Console.WriteLine($"{claim.Type}: {claim.Value}");
    }
}
```

<Info>
  The exact claims returned depend on the scopes requested. For more information, see [Using Scopes](https://auth0.github.io/auth0-oidc-client-net/documentation/advanced-scenarios/scopes.html) in the Auth0 OIDC Client documentation.
</Info>

### Request Custom Scopes

To request additional user information, specify scopes when creating the Auth0Client:

```cs CustomScopes.cs lines theme={null}
var auth0Client = new Auth0Client(new Auth0ClientOptions
{
    Domain = "{yourDomain}",
    ClientId = "{yourClientId}",
    Scope = "openid profile email offline_access read:posts"
});
```

***

## Troubleshooting & Advanced

<Accordion title="Common Issues & Solutions">
  ### Browser doesn't redirect back to app

  **Solutions:**

  1. Verify callback URLs in Auth0 Dashboard exactly match your app's package name/bundle identifier
  2. Ensure callback URLs are in **lowercase**
  3. Check that `DataScheme`, `DataHost`, and `DataPathPrefix` (Android) or URL scheme (iOS) match your configuration
  4. Clean and rebuild your project

  ### Authentication fails with "Invalid Callback URL" error

  **Fix:**

  * Double-check that your callback URL in the Auth0 Dashboard matches the format:
    * Android: `packagename://yourdomain/android/packagename/callback`
    * iOS: `bundleidentifier://yourdomain/ios/bundleidentifier/callback`
  * Ensure the URL is in lowercase
  * Verify the Domain in your code matches the Domain in the Auth0 Dashboard

  ### LoginAsync() hangs or never completes

  **Solutions:**

  * Ensure the Intent filter (Android) or URL scheme (iOS) is properly configured
  * Check that `OnNewIntent()` (Android) or `OpenUrl()` (iOS) calls the `ActivityMediator`
  * Verify your app can open the system browser
  * Check network connectivity

  ### Error: "Default App must use Token Endpoint Authentication Method 'None'"

  **Fix:**

  1. Go to your Auth0 Application Settings in the Dashboard
  2. Scroll to **Application Properties**
  3. Set **Application Type** to **Native**
  4. Set **Token Endpoint Authentication Method** to **None**
  5. Click **Save Changes**

  ### iOS: Browser doesn't open

  **Solutions:**

  * Verify `Info.plist` contains the correct URL scheme configuration
  * Check that `OpenUrl()` is implemented in `AppDelegate`
  * Ensure iOS deployment target is compatible with your Auth0 SDK version
</Accordion>

<Accordion title="Production Considerations">
  ### Security Best Practices

  * **Secure Token Storage**: Use platform-specific secure storage (Android Keystore, iOS Keychain) to store tokens
  * **Token Refresh**: Implement refresh token handling to maintain user sessions
  * **Certificate Pinning**: Consider certificate pinning for additional API security
  * **ProGuard/Code Obfuscation**: Add appropriate rules if using code obfuscation on Android

  ### App Store Requirements

  * **Privacy Policy**: Ensure your app has a privacy policy that describes Auth0 usage
  * **User Data Handling**: Follow platform guidelines for handling user authentication data
  * **Deep Linking**: Test callback URL handling thoroughly across different scenarios
  * **Network Requirements**: Handle offline scenarios gracefully

  ### Performance Optimization

  * **Cache Auth0Client**: Create a single instance and reuse it throughout your app
  * **Lazy Loading**: Initialize Auth0Client only when needed
  * **Background Refresh**: Implement background token refresh for long-running sessions
</Accordion>

<Accordion title="Advanced Configuration">
  ### Custom Scopes and Audience

  Request specific scopes and set an audience for your API:

  ```cs AdvancedAuth.cs expandable lines theme={null}
  var auth0Client = new Auth0Client(new Auth0ClientOptions
  {
      Domain = "{yourDomain}",
      ClientId = "{yourClientId}",
      Scope = "openid profile email offline_access read:posts write:posts",
      Audience = "https://myapi.example.com"
  });

  var loginResult = await auth0Client.LoginAsync();
  ```

  ### Additional Parameters

  Pass additional parameters to the authorization request:

  ```cs ExtraParams.cs expandable lines theme={null}
  var extraParameters = new Dictionary<string, string>
  {
      { "prompt", "login" },
      { "ui_locales", "es" },
      { "custom_param", "value" }
  };

  var loginResult = await auth0Client.LoginAsync(extraParameters);
  ```

  ### Refresh Tokens

  Use refresh tokens to get new access tokens without user interaction:

  ```cs RefreshToken.cs expandable lines theme={null}
  var refreshResult = await auth0Client.RefreshTokenAsync(loginResult.RefreshToken);

  if (!refreshResult.IsError)
  {
      var newAccessToken = refreshResult.AccessToken;
      var newIdToken = refreshResult.IdentityToken;
      // Store new tokens
  }
  ```

  <Info>
    To receive a refresh token, include the `offline_access` scope in your authentication request.
  </Info>

  ### Platform-Specific Browser Configuration

  **Android - Use Chrome Custom Tabs with custom colors:**

  ```cs AndroidBrowser.cs expandable lines theme={null}
  var auth0Client = new Auth0Client(new Auth0ClientOptions
  {
      Domain = "{yourDomain}",
      ClientId = "{yourClientId}",
      Browser = new AndroidBrowser
      {
          ToolbarColor = Android.Graphics.Color.ParseColor("#FF6B35")
      }
  }, this);
  ```

  **iOS - Use SFSafariViewController with custom presentation:**

  ```cs iOSBrowser.cs expandable lines theme={null}
  var auth0Client = new Auth0Client(new Auth0ClientOptions
  {
      Domain = "{yourDomain}",
      ClientId = "{yourClientId}",
      Browser = new ASWebAuthenticationSessionBrowser
      {
          PrefersEphemeralWebBrowserSession = false
      }
  });
  ```
</Accordion>

***

## Next Steps

<CardGroup>
  <Card title="Configure Identity Providers" icon="key" href="/docs/authenticate/identity-providers">
    Add social login providers like Google, Facebook, and GitHub
  </Card>

  <Card title="Enable Multi-Factor Authentication" icon="shield-halved" href="/docs/secure/multi-factor-authentication">
    Add an extra layer of security with MFA
  </Card>

  <Card title="Attack Protection" icon="shield" href="/docs/secure/attack-protection">
    Learn how to protect against brute force and bot attacks
  </Card>

  <Card title="Customize Login Experience" icon="paintbrush" href="/docs/customize/universal-login-pages">
    Customize the Universal Login page to match your brand
  </Card>
</CardGroup>


# Add Login to Your Expo Application
Source: https://auth0.com/docs/quickstart/native/react-native-expo/index



<Tip>
  This Quickstart is for Expo applications. To integrate Auth0 into your React Native application, refer to the [React Native Quickstart](https://auth0.com/docs/quickstart/native/react-native/interactive).
</Tip>

## Get Started

<Steps>
  <Step title="Create a new Expo project">
    Create a new Expo project for this quickstart.

    **In your terminal:**

    ```bash theme={null}
    npx create-expo-app Auth0ExpoSample --template blank
    cd Auth0ExpoSample
    ```

    <Tip>
      This creates a minimal Expo app with the latest SDK, ready for native module integration. The `--template blank` flag provides a clean starting point without additional boilerplate.
    </Tip>

    <Warning>
      This SDK is **NOT compatible with Expo Go** because it requires custom native code. You must use `npx expo run:ios` or `npx expo run:android` to create a development build.
    </Warning>
  </Step>

  <Step title="Install the Auth0 SDK">
    Add the Auth0 React Native SDK to your project.

    ```bash theme={null}
    npx expo install react-native-auth0
    ```

    <Tip>
      Using `npx expo install` ensures version compatibility with your Expo SDK version. The SDK auto-configures through the Expo plugin system.
    </Tip>
  </Step>

  <Step title="Configure the Expo Plugin">
    Configure the Auth0 plugin to handle native iOS and Android configuration automatically.

    Update your `app.json` to include the Auth0 plugin:

    ```json app.json lines theme={null}
    {
      "expo": {
        "name": "Auth0ExpoSample",
        "slug": "auth0-expo-sample",
        "version": "1.0.0",
        "ios": {
          "bundleIdentifier": "com.auth0.samples.expo",
          "supportsTablet": true
        },
        "android": {
          "package": "com.auth0.samples.expo",
          "adaptiveIcon": {
            "foregroundImage": "./assets/images/adaptive-icon.png",
            "backgroundColor": "#ffffff"
          }
        },
        "plugins": [
          [
            "react-native-auth0",
            {
              "domain": "{yourDomain}",
              "customScheme": "auth0sample"
            }
          ]
        ]
      }
    }
    ```

    Replace `{yourDomain}` with your Auth0 domain (you'll get this in the next step).

    <Warning>
      **Important**: You must define `bundleIdentifier` for iOS and `package` for Android in your `app.json`. These identifiers are required for the Auth0 SDK to configure the native projects properly. If you don't specify a custom scheme, the SDK will use the bundle identifier as the URL scheme.
    </Warning>

    <Info>
      The `customScheme` must be lowercase with no special characters. This value is used to construct callback URLs and must be passed to `authorize()` and `clearSession()` methods.
    </Info>
  </Step>

  <Step title="Configure your Auth0 Application">
    Create and configure an Auth0 application to work with your Expo app.

    1. Head to the [Auth0 Dashboard](https://manage.auth0.com/dashboard/)
    2. Click on **Applications** > **Applications** > **Create Application**
    3. In the popup, enter a name for your app (e.g., `Auth0 Expo Sample`), select `Native` as the app type and click **Create**
    4. Switch to the **Settings** tab on the Application Details page
    5. Note your **Domain** and **Client ID** values
    6. Update the `domain` value in your `app.json` plugin configuration with your Auth0 domain

    **Allowed Callback URLs:**

    ```
    auth0sample://{yourDomain}/ios/auth0sample/callback,
    auth0sample://{yourDomain}/android/auth0sample/callback
    ```

    **Allowed Logout URLs:**

    ```
    auth0sample://{yourDomain}/ios/auth0sample/callback,
    auth0sample://{yourDomain}/android/auth0sample/callback
    ```

    Replace `{yourDomain}` with your actual Auth0 domain (e.g., `dev-abc123.us.auth0.com`).

    <Info>
      **Allowed Callback URLs** are a critical security measure to ensure users are safely returned to your application after authentication. Without a matching URL, the login process will fail, and users will be blocked by an Auth0 error page instead of accessing your app.

      **Allowed Logout URLs** are essential for providing a seamless user experience upon signing out. Without a matching URL, users will not be redirected back to your application after logout and will instead be left on a generic Auth0 page.

      The `customScheme` must match exactly with the value in your `app.json` plugin configuration.
    </Info>

    <Warning>
      **Important**: Ensure the `customScheme` in your callback URLs matches exactly with the value in your `app.json` plugin configuration. Mismatched values will cause authentication to fail.
    </Warning>
  </Step>

  <Step title="Setup App Component">
    Setup your main app component based on your chosen implementation approach.

    <Tabs>
      <Tab title="Hooks-based (with Provider)">
        Replace the contents of `App.js` and wrap your application with the `Auth0Provider` component:

        ```jsx App.js lines theme={null}
        import React from 'react';
        import {Auth0Provider, useAuth0} from 'react-native-auth0';
        import {
          StyleSheet,
          Text,
          View,
          Button,
          Image,
          ActivityIndicator,
        } from 'react-native';

        function HomeScreen() {
          const {authorize, clearSession, user, isLoading} = useAuth0();

          const handleLogin = async () => {
            try {
              await authorize({customScheme: 'auth0sample', scope: 'openid profile email'});
            } catch (e) {
              console.error('Login error:', e);
            }
          };

          const handleLogout = async () => {
            try {
              await clearSession({customScheme: 'auth0sample'});
            } catch (e) {
              console.error('Logout error:', e);
            }
          };

          if (isLoading) {
            return (
              <View style={styles.container}>
                <ActivityIndicator size="large" color="#0066cc" />
                <Text style={styles.loadingText}>Loading...</Text>
              </View>
            );
          }

          return (
            <View style={styles.container}>
              <Text style={styles.title}>Auth0 Expo Sample</Text>

              {user ? (
                <View style={styles.profileContainer}>
                  {user.picture && (
                    <Image source={{uri: user.picture}} style={styles.avatar} />
                  )}
                  <Text style={styles.welcomeText}>Welcome, {user.name}!</Text>
                  <Text style={styles.emailText}>{user.email}</Text>
                  <View style={styles.buttonContainer}>
                    <Button title="Log Out" onPress={handleLogout} color="#dc3545" />
                  </View>
                </View>
              ) : (
                <View style={styles.loginContainer}>
                  <Text style={styles.subtitle}>
                    Tap the button below to log in
                  </Text>
                  <View style={styles.buttonContainer}>
                    <Button title="Log In" onPress={handleLogin} color="#0066cc" />
                  </View>
                </View>
              )}
            </View>
          );
        }

        export default function App() {
          return (
            <Auth0Provider domain="{yourDomain}" clientId="{yourClientId}">
              <HomeScreen />
            </Auth0Provider>
          );
        }

        const styles = StyleSheet.create({
          container: {
            flex: 1,
            justifyContent: 'center',
            alignItems: 'center',
            padding: 20,
            backgroundColor: '#fff',
          },
          title: {
            fontSize: 28,
            fontWeight: 'bold',
            marginBottom: 20,
            color: '#333',
          },
          subtitle: {
            fontSize: 16,
            color: '#666',
            marginBottom: 30,
            textAlign: 'center',
          },
          loadingText: {
            marginTop: 10,
            fontSize: 16,
            color: '#666',
          },
          profileContainer: {
            alignItems: 'center',
          },
          avatar: {
            width: 100,
            height: 100,
            borderRadius: 50,
            marginBottom: 20,
          },
          welcomeText: {
            fontSize: 22,
            fontWeight: '600',
            marginBottom: 8,
            color: '#333',
          },
          emailText: {
            fontSize: 16,
            color: '#666',
            marginBottom: 30,
          },
          loginContainer: {
            alignItems: 'center',
          },
          buttonContainer: {
            width: 200,
            marginTop: 10,
          },
        });
        ```

        Replace `{yourDomain}` with your Auth0 domain and `{yourClientId}` with your Client ID from the Auth0 Dashboard.

        <Tip>
          The `Auth0Provider` initializes the SDK and provides authentication context to all child components via the `useAuth0` hook. The `customScheme` parameter must match the value in your `app.json` plugin configuration.
        </Tip>
      </Tab>

      <Tab title="Class-based (without Provider)">
        Replace the contents of `App.js` with a class-based component:

        ```jsx App.js lines theme={null}
        import React, {Component} from 'react';
        import {
          View,
          Text,
          Button,
          StyleSheet,
          ActivityIndicator,
          Image,
        } from 'react-native';
        import Auth0, {Credentials} from 'react-native-auth0';

        const auth0 = new Auth0({
          domain: '{yourDomain}',
          clientId: '{yourClientId}',
        });

        interface User {
          name?: string;
          email?: string;
          picture?: string;
        }

        interface AppState {
          user: User | null;
          isLoading: boolean;
        }

        class App extends Component<{}, AppState> {
          constructor(props: {}) {
            super(props);
            this.state = {
              user: null,
              isLoading: true,
            };
          }

          async componentDidMount() {
            await this.checkAuthStatus();
          }

          checkAuthStatus = async () => {
            try {
              const hasValidCredentials = await auth0.credentialsManager.hasValidCredentials();
              if (hasValidCredentials) {
                const credentials = await auth0.credentialsManager.getCredentials();
                const userInfo = await auth0.auth.userInfo({token: credentials.accessToken});
                this.setState({user: userInfo, isLoading: false});
              } else {
                this.setState({isLoading: false});
              }
            } catch (e) {
              console.error(e);
              this.setState({isLoading: false});
            }
          };

          login = async () => {
            try {
              const credentials: Credentials = await auth0.webAuth.authorize({
                scope: 'openid profile email',
              }, {customScheme: 'auth0sample'});
              
              await auth0.credentialsManager.saveCredentials(credentials);
              const userInfo = await auth0.auth.userInfo({token: credentials.accessToken});
              this.setState({user: userInfo});
            } catch (e) {
              console.error(e);
            }
          };

          logout = async () => {
            try {
              await auth0.webAuth.clearSession({}, {customScheme: 'auth0sample'});
              await auth0.credentialsManager.clearCredentials();
              this.setState({user: null});
            } catch (e) {
              console.error(e);
            }
          };

          render() {
            const {user, isLoading} = this.state;

            if (isLoading) {
              return (
                <View style={styles.container}>
                  <ActivityIndicator size="large" color="#0066cc" />
                  <Text style={styles.loadingText}>Loading...</Text>
                </View>
              );
            }

            return (
              <View style={styles.container}>
                <Text style={styles.title}>Auth0 Expo Sample</Text>

                {user ? (
                  <View style={styles.profileContainer}>
                    {user.picture && (
                      <Image source={{uri: user.picture}} style={styles.avatar} />
                    )}
                    <Text style={styles.welcomeText}>Welcome, {user.name}!</Text>
                    <Text style={styles.emailText}>{user.email}</Text>
                    <View style={styles.buttonContainer}>
                      <Button title="Log Out" onPress={this.logout} color="#dc3545" />
                    </View>
                  </View>
                ) : (
                  <View style={styles.loginContainer}>
                    <Text style={styles.subtitle}>
                      Tap the button below to log in
                    </Text>
                    <View style={styles.buttonContainer}>
                      <Button title="Log In" onPress={this.login} color="#0066cc" />
                    </View>
                  </View>
                )}
              </View>
            );
          }
        }

        const styles = StyleSheet.create({
          container: {
            flex: 1,
            justifyContent: 'center',
            alignItems: 'center',
            padding: 20,
            backgroundColor: '#fff',
          },
          title: {
            fontSize: 28,
            fontWeight: 'bold',
            marginBottom: 20,
            color: '#333',
          },
          subtitle: {
            fontSize: 16,
            color: '#666',
            marginBottom: 30,
            textAlign: 'center',
          },
          loadingText: {
            marginTop: 10,
            fontSize: 16,
            color: '#666',
          },
          profileContainer: {
            alignItems: 'center',
          },
          avatar: {
            width: 100,
            height: 100,
            borderRadius: 50,
            marginBottom: 20,
          },
          welcomeText: {
            fontSize: 22,
            fontWeight: '600',
            marginBottom: 8,
            color: '#333',
          },
          emailText: {
            fontSize: 16,
            color: '#666',
            marginBottom: 30,
          },
          loginContainer: {
            alignItems: 'center',
          },
          buttonContainer: {
            width: 200,
            marginTop: 10,
          },
        });

        export default App;
        ```

        Replace `{yourDomain}` with your Auth0 domain and `{yourClientId}` with your Client ID from the Auth0 Dashboard.

        <Tip>
          The class-based approach doesn't require the `Auth0Provider` since it uses the `Auth0` class instance directly. The `customScheme` option must be passed as the second parameter to `authorize()` and `clearSession()`.
        </Tip>
      </Tab>
    </Tabs>

    <Info>
      The `authorize()` method opens Auth0's Universal Login in a secure browser (ASWebAuthenticationSession on iOS, Chrome Custom Tabs on Android). The `clearSession()` method logs the user out and clears both the browser session and stored credentials. The `customScheme` parameter must match the value in your `app.json` plugin configuration.
    </Info>
  </Step>

  <Step title="Run your app">
    Build and run your Expo application on a device or emulator.

    **First, generate the native iOS and Android projects:**

    ```bash theme={null}
    npx expo prebuild
    ```

    **Then run on your target platform:**

    **For iOS:**

    ```bash theme={null}
    npx expo run:ios
    ```

    **For Android:**

    ```bash theme={null}
    npx expo run:android
    ```

    **Expected flow:**

    1. App launches showing "Log In" button
    2. Tap **Log In** → Browser opens with Auth0 Universal Login
    3. Complete login (sign up or sign in)
    4. Browser closes → Returns to app automatically
    5. User profile displays with name, email, and avatar

    <Tip>
      If you make changes to the plugin configuration in `app.json`, run `npx expo prebuild --clean` to regenerate the native projects with the updated configuration.
    </Tip>

    <Warning>
      iOS Simulator requires a valid Apple Developer account for ASWebAuthenticationSession. For testing on simulator without an account, use a physical device or Android emulator instead.
    </Warning>
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a fully functional Auth0 login experience running on your device or emulator. The app uses secure browser authentication and automatically manages credentials in the device's secure storage.
</Check>

***

## Troubleshooting & Advanced

<Accordion title="Common Issues & Solutions">
  ### "Invariant Violation: Native module cannot be null"

  This error occurs when attempting to use the SDK with Expo Go.

  **Solution:**

  The Auth0 SDK requires custom native code that isn't available in Expo Go. Use a development build instead:

  ```bash theme={null}
  npx expo run:ios
  # or
  npx expo run:android
  ```

  ### Callback URL mismatch error

  **Solution:**

  Verify all three of these match exactly:

  1. `customScheme` in `app.json` plugin configuration
  2. `customScheme` parameter passed to `authorize()` and `clearSession()`
  3. Callback URLs in Auth0 Dashboard (Applications → Your App → Settings → Application URIs)

  ### "PKCE not allowed" error

  **Fix:**

  1. Go to Auth0 Dashboard → Applications → Your Application
  2. Change application type to **Native**
  3. Save changes and try again

  ### Prebuild fails or plugin not applied

  **Fix:**

  ```bash theme={null}
  # Clean and regenerate native projects
  npx expo prebuild --clean
  ```

  ### iOS build fails with Pod errors

  **Fix:**

  ```bash theme={null}
  cd ios
  pod install --repo-update
  cd ..
  npx expo run:ios
  ```

  ### User cancelled error

  Handle gracefully in your login function:

  ```jsx expandable theme={null}
  const handleLogin = async () => {
    try {
      await authorize({customScheme: 'auth0sample', scope: 'openid profile email'});
    } catch (e) {
      if (e.message === 'a0.session.user_cancelled') {
        // User closed login screen - handle gracefully
        console.log('Login cancelled by user');
      } else {
        console.error('Login failed:', e);
      }
    }
  };
  ```

  ### iOS Alert Dialog

  On iOS, users see a permission dialog: *"App Name" Wants to Use "auth0.com" to Sign In*. This is expected behavior from `ASWebAuthenticationSession`. Users must tap **Continue** to proceed.

  To customize this behavior, you can use ephemeral sessions (disables SSO):

  ```jsx theme={null}
  await authorize({customScheme: 'auth0sample', scope: 'openid profile email'}, {ephemeralSession: true});
  ```
</Accordion>

<Accordion title="Retrieving Access Tokens">
  Use the `getCredentials()` method to retrieve tokens for API calls:

  ```jsx expandable lines theme={null}
  import {useAuth0} from 'react-native-auth0';

  const MyComponent = () => {
    const {getCredentials} = useAuth0();

    const callApi = async () => {
      try {
        const credentials = await getCredentials();
        const response = await fetch('https://your-api.com/endpoint', {
          headers: {
            Authorization: `Bearer ${credentials.accessToken}`,
          },
        });
        // Handle response
      } catch (e) {
        console.error('Failed to get credentials', e);
      }
    };
  };
  ```

  <Tip>
    Include the `offline_access` scope during login to receive a refresh token: `authorize({customScheme: 'auth0sample', scope: 'openid profile email offline_access'})`. This enables automatic token renewal.
  </Tip>
</Accordion>

<Accordion title="Check Authentication Status on App Launch">
  Use `hasValidCredentials()` to check if the user is already logged in:

  ```jsx expandable lines theme={null}
  import {useAuth0} from 'react-native-auth0';
  import {useEffect} from 'react';

  const App = () => {
    const {hasValidCredentials, getCredentials} = useAuth0();

    useEffect(() => {
      const checkAuth = async () => {
        const isLoggedIn = await hasValidCredentials();
        if (isLoggedIn) {
          const credentials = await getCredentials();
          // User is authenticated, load their data
        }
      };
      checkAuth();
    }, []);
  };
  ```
</Accordion>

<Accordion title="Production Deployment with EAS Build">
  For production builds, use EAS Build instead of local development builds.

  **Install EAS CLI:**

  ```bash theme={null}
  npm install -g eas-cli
  ```

  **Create `eas.json` in your project root:**

  ```json eas.json lines theme={null}
  {
    "cli": {
      "version": ">= 3.0.0"
    },
    "build": {
      "development": {
        "developmentClient": true,
        "distribution": "internal"
      },
      "preview": {
        "distribution": "internal"
      },
      "production": {}
    }
  }
  ```

  **Build for production:**

  ```bash theme={null}
  # Build for both platforms
  eas build --platform all

  # Or build for specific platform
  eas build --platform ios
  eas build --platform android
  ```

  ### Before deploying to production

  **Use HTTPS callback URLs** for enhanced security:

  ```text theme={null}
  https://{yourDomain}/ios/{bundleId}/callback
  https://{yourDomain}/android/{packageName}/callback
  ```

  **Configure Android App Links** in Auth0 Dashboard:

  * Settings → Advanced Settings → Device Settings
  * Add your app's SHA-256 fingerprint

  **Configure iOS Universal Links:**

  * Add Associated Domains capability in Xcode
  * Add `webcredentials:{yourDomain}` to Associated Domains

  **Review security settings** in Auth0 Dashboard:

  * Enable **OIDC Conformant** in Advanced Settings
  * Configure **Token Expiration** appropriately
  * Set up **Brute Force Protection**
  * Test on multiple devices and OS versions
  * Implement proper error handling for network failures

  <Tip>
    For production apps, consider using HTTPS callback URLs with Universal Links (iOS) and App Links (Android) instead of custom schemes for enhanced security.
  </Tip>
</Accordion>

* [Sample Application](https://github.com/auth0-samples/auth0-react-native-sample/tree/master/00-Login-Expo)
* [Migration Guide (v4 to v5)](https://github.com/auth0/react-native-auth0/blob/master/MIGRATION_GUIDE.md)


# Add Login to Your React Native Application
Source: https://auth0.com/docs/quickstart/native/react-native/index



<Tip>
  This Quickstart is for the React Native framework. To integrate Auth0 into your Expo application, refer to the [Expo Quickstart](https://auth0.com/docs/quickstart/native/react-native-expo/interactive).
</Tip>

<Accordion title="Use AI to integrate Auth0" icon="microchip-ai">
  If you use an AI coding assistant like Claude Code, Cursor, or GitHub Copilot, you can add Auth0 authentication automatically in minutes using [agent skills](https://agentskills.io/home).

  **Install:**

  ```bash theme={null}
  npx skills add https://github.com/auth0/agent-skills --skill auth0-react-native
  ```

  **Then ask your AI assistant:**

  ```text theme={null}
  Add Auth0 authentication to my React Native app
  ```

  Your AI assistant will automatically create your Auth0 application, fetch credentials, install `react-native-auth0`, configure native dependencies, and set up your authentication flow. [Full agent skills documentation →](/quickstart/agent-skills)
</Accordion>

## Get Started

<Steps>
  <Step title="Create a new React Native project">
    Create a new React Native project for this quickstart.

    **In your terminal:**

    ```bash theme={null}
    npx @react-native-community/cli init Auth0ReactNativeSample
    cd Auth0ReactNativeSample
    ```

    Configure your project with:

    * **Name**: `Auth0ReactNativeSample`
    * **Package name**: `com.auth0.samples.reactnative`

    <Tip>
      This creates a React Native app with the latest stable version. The Auth0 SDK requires React Native 0.78.0+ and React 19.0.0+.
    </Tip>
  </Step>

  <Step title="Install the Auth0 SDK">
    Add the Auth0 React Native SDK to your project.

    ```bash theme={null}
    npm install react-native-auth0
    ```

    For iOS, install the native dependencies:

    ```bash theme={null}
    cd ios && pod install && cd ..
    ```

    <Tip>
      The SDK auto-links on both platforms. The `pod install` step installs the required iOS native modules (Auth0.swift, JWTDecode, SimpleKeychain).
    </Tip>
  </Step>

  <Step title="Configure your Auth0 Application">
    Create and configure an Auth0 application to work with your React Native app.

    1. Head to the [Auth0 Dashboard](https://manage.auth0.com/dashboard/)
    2. Click on **Applications** > **Applications** > **Create Application**
    3. In the popup, enter a name for your app (e.g., `Auth0 React Native Sample`), select `Native` as the app type and click **Create**
    4. Switch to the **Settings** tab on the Application Details page
    5. Note your **Domain** and **Client ID** values

    **Allowed Callback URLs:**

    ```
    org.reactjs.native.example.auth0reactnativesample.auth0://{yourDomain}/ios/org.reactjs.native.example.auth0reactnativesample/callback,
    com.auth0reactnativesample.auth0://{yourDomain}/android/com.auth0reactnativesample/callback
    ```

    **Allowed Logout URLs:**

    ```
    org.reactjs.native.example.auth0reactnativesample.auth0://{yourDomain}/ios/org.reactjs.native.example.auth0reactnativesample/callback,
    com.auth0reactnativesample.auth0://{yourDomain}/android/com.auth0reactnativesample/callback
    ```

    Replace `{yourDomain}` with your actual Auth0 domain (e.g., `dev-abc123.us.auth0.com`).

    <Info>
      **Allowed Callback URLs** are a critical security measure to ensure users are safely returned to your application after authentication. Without a matching URL, the login process will fail, and users will be blocked by an Auth0 error page instead of accessing your app.

      **Allowed Logout URLs** are essential for providing a seamless user experience upon signing out. Without a matching URL, users will not be redirected back to your application after logout and will instead be left on a generic Auth0 page.

      The URL scheme includes `.auth0` after your bundle identifier to ensure the callback is routed to your specific app. For this quickstart, the bundle identifier is `org.reactjs.native.example.auth0reactnativesample`.
    </Info>

    <Warning>
      **Important**: The callback URL scheme must include `.auth0` after your bundle identifier (e.g., `org.reactjs.native.example.auth0reactnativesample.auth0://`). This is required for the SDK to properly handle the authentication callback.
    </Warning>
  </Step>

  <Step title="Configure Native Platforms">
    Configure both iOS and Android to handle the authentication callback.

    **Android Configuration:**

    Open `android/app/build.gradle` and add the manifest placeholders inside `defaultConfig`:

    ```groovy android/app/build.gradle lines theme={null}
    android {
        defaultConfig {
            applicationId "com.auth0reactnativesample"
            // ... other config
            
            // Add Auth0 manifest placeholders
            manifestPlaceholders = [
                auth0Domain: "{yourDomain}",
                auth0Scheme: "${applicationId}.auth0"
            ]
        }
    }
    ```

    Replace `{yourDomain}` with your Auth0 domain (e.g., `dev-abc123.us.auth0.com`).

    **iOS Configuration:**

    <Tabs>
      <Tab title="AppDelegate.mm (Objective-C)">
        Open `ios/Auth0ReactNativeSample/AppDelegate.mm` and add the URL handling method:

        ```objc ios/Auth0ReactNativeSample/AppDelegate.mm lines theme={null}
        #import <React/RCTLinkingManager.h>

        // Add this method inside the @implementation block
        - (BOOL)application:(UIApplication *)app
                    openURL:(NSURL *)url
                    options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options
        {
          return [RCTLinkingManager application:app openURL:url options:options];
        }
        ```
      </Tab>

      <Tab title="AppDelegate.swift (Swift)">
        Open `ios/Auth0ReactNativeSample/AppDelegate.swift` and add the URL handling method:

        ```swift ios/Auth0ReactNativeSample/AppDelegate.swift lines theme={null}
        import React

        // Add this method inside the AppDelegate class
        func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
          return RCTLinkingManager.application(app, open: url, options: options)
        }
        ```
      </Tab>
    </Tabs>

    Open `ios/Auth0ReactNativeSample/Info.plist` and add the URL scheme. Add this before the closing `</dict>` tag:

    ```xml ios/Auth0ReactNativeSample/Info.plist lines theme={null}
    <key>CFBundleURLTypes</key>
    <array>
      <dict>
        <key>CFBundleTypeRole</key>
        <string>None</string>
        <key>CFBundleURLName</key>
        <string>auth0</string>
        <key>CFBundleURLSchemes</key>
        <array>
          <string>$(PRODUCT_BUNDLE_IDENTIFIER).auth0</string>
        </array>
      </dict>
    </array>
    ```

    <Info>
      The URL scheme uses your bundle identifier with `.auth0` appended. This ensures the callback is routed to your specific app after authentication completes in the browser.
    </Info>
  </Step>

  <Step title="Setup App Component">
    Setup your main app component based on your chosen implementation approach.

    <Tabs>
      <Tab title="Hooks-based (with Provider)">
        Replace the contents of `App.tsx` and wrap your application with the `Auth0Provider` component:

        ```tsx App.tsx lines theme={null}
        import React from 'react';
        import {Auth0Provider} from 'react-native-auth0';
        import {SafeAreaView, StyleSheet} from 'react-native';
        import MainScreen from './src/MainScreen';

        const App = () => {
          return (
            <Auth0Provider
              domain="{yourDomain}"
              clientId="{yourClientId}">
              <SafeAreaView style={styles.container}>
                <MainScreen />
              </SafeAreaView>
            </Auth0Provider>
          );
        };

        const styles = StyleSheet.create({
          container: {
            flex: 1,
            backgroundColor: '#fff',
          },
        });

        export default App;
        ```

        Replace `{yourDomain}` with your Auth0 domain and `{yourClientId}` with your Client ID from the Auth0 Dashboard.

        <Tip>
          The `Auth0Provider` initializes the SDK and provides authentication context to all child components via the `useAuth0` hook.
        </Tip>
      </Tab>

      <Tab title="Class-based (without Provider)">
        Replace the contents of `App.tsx` with a simple container for your class-based component:

        ```tsx App.tsx lines theme={null}
        import React from 'react';
        import {SafeAreaView, StyleSheet} from 'react-native';
        import MainScreen from './src/MainScreen';

        const App = () => {
          return (
            <SafeAreaView style={styles.container}>
              <MainScreen />
            </SafeAreaView>
          );
        };

        const styles = StyleSheet.create({
          container: {
            flex: 1,
            backgroundColor: '#fff',
          },
        });

        export default App;
        ```

        <Tip>
          The class-based approach doesn't require the `Auth0Provider` since it uses the `Auth0` class instance directly. The Auth0 configuration will be in the MainScreen component.
        </Tip>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Implement Login and Logout">
    Create a screen component that handles login and logout. You can choose between a hooks-based approach (recommended) or a class-based approach.

    <Tabs>
      <Tab title="Hooks-based (Recommended)">
        Create `src/MainScreen.tsx` using the `useAuth0` hook:

        ```tsx src/MainScreen.tsx lines theme={null}
        import React from 'react';
        import {
          View,
          Text,
          Button,
          StyleSheet,
          ActivityIndicator,
          Image,
        } from 'react-native';
        import {useAuth0} from 'react-native-auth0';

        const MainScreen = () => {
          const {authorize, clearSession, user, isLoading} = useAuth0();

          const login = async () => {
            try {
              await authorize({scope: 'openid profile email'});
            } catch (e) {
              console.error(e);
            }
          };

          const logout = async () => {
            try {
              await clearSession();
            } catch (e) {
              console.error(e);
            }
          };

          if (isLoading) {
            return (
              <View style={styles.container}>
                <ActivityIndicator size="large" color="#0066cc" />
                <Text style={styles.loadingText}>Loading...</Text>
              </View>
            );
          }

          return (
            <View style={styles.container}>
              <Text style={styles.title}>Auth0 React Native</Text>

              {user ? (
                <View style={styles.profileContainer}>
                  {user.picture && (
                    <Image source={{uri: user.picture}} style={styles.avatar} />
                  )}
                  <Text style={styles.welcomeText}>Welcome, {user.name}!</Text>
                  <Text style={styles.emailText}>{user.email}</Text>
                  <View style={styles.buttonContainer}>
                    <Button title="Log Out" onPress={logout} color="#dc3545" />
                  </View>
                </View>
              ) : (
                <View style={styles.loginContainer}>
                  <Text style={styles.subtitle}>
                    Tap the button below to log in
                  </Text>
                  <View style={styles.buttonContainer}>
                    <Button title="Log In" onPress={login} color="#0066cc" />
                  </View>
                </View>
              )}
            </View>
          );
        };

        const styles = StyleSheet.create({
          container: {
            flex: 1,
            justifyContent: 'center',
            alignItems: 'center',
            padding: 20,
          },
          title: {
            fontSize: 28,
            fontWeight: 'bold',
            marginBottom: 20,
            color: '#333',
          },
          subtitle: {
            fontSize: 16,
            color: '#666',
            marginBottom: 30,
            textAlign: 'center',
          },
          loadingText: {
            marginTop: 10,
            fontSize: 16,
            color: '#666',
          },
          profileContainer: {
            alignItems: 'center',
          },
          avatar: {
            width: 100,
            height: 100,
            borderRadius: 50,
            marginBottom: 20,
          },
          welcomeText: {
            fontSize: 22,
            fontWeight: '600',
            marginBottom: 8,
            color: '#333',
          },
          emailText: {
            fontSize: 16,
            color: '#666',
            marginBottom: 30,
          },
          loginContainer: {
            alignItems: 'center',
          },
          buttonContainer: {
            width: 200,
            marginTop: 10,
          },
        });

        export default MainScreen;
        ```
      </Tab>

      <Tab title="Class-based">
        Create `src/MainScreen.tsx` using the `Auth0` class directly:

        ```tsx src/MainScreen.tsx lines theme={null}
        import React, {Component} from 'react';
        import {
          View,
          Text,
          Button,
          StyleSheet,
          ActivityIndicator,
          Image,
        } from 'react-native';
        import Auth0, {Credentials} from 'react-native-auth0';

        const auth0 = new Auth0({
          domain: '{yourDomain}',
          clientId: '{yourClientId}',
        });

        interface User {
          name?: string;
          email?: string;
          picture?: string;
        }

        interface MainScreenState {
          user: User | null;
          isLoading: boolean;
        }

        class MainScreen extends Component<{}, MainScreenState> {
          constructor(props: {}) {
            super(props);
            this.state = {
              user: null,
              isLoading: true,
            };
          }

          async componentDidMount() {
            await this.checkAuthStatus();
          }

          checkAuthStatus = async () => {
            try {
              const hasValidCredentials = await auth0.credentialsManager.hasValidCredentials();
              if (hasValidCredentials) {
                const credentials = await auth0.credentialsManager.getCredentials();
                const userInfo = await auth0.auth.userInfo({token: credentials.accessToken});
                this.setState({user: userInfo, isLoading: false});
              } else {
                this.setState({isLoading: false});
              }
            } catch (e) {
              console.error(e);
              this.setState({isLoading: false});
            }
          };

          login = async () => {
            try {
              const credentials: Credentials = await auth0.webAuth.authorize({
                scope: 'openid profile email',
              });
              
              await auth0.credentialsManager.saveCredentials(credentials);
              const userInfo = await auth0.auth.userInfo({token: credentials.accessToken});
              this.setState({user: userInfo});
            } catch (e) {
              console.error(e);
            }
          };

          logout = async () => {
            try {
              await auth0.webAuth.clearSession();
              await auth0.credentialsManager.clearCredentials();
              this.setState({user: null});
            } catch (e) {
              console.error(e);
            }
          };

          render() {
            const {user, isLoading} = this.state;

            if (isLoading) {
              return (
                <View style={styles.container}>
                  <ActivityIndicator size="large" color="#0066cc" />
                  <Text style={styles.loadingText}>Loading...</Text>
                </View>
              );
            }

            return (
              <View style={styles.container}>
                <Text style={styles.title}>Auth0 React Native</Text>

                {user ? (
                  <View style={styles.profileContainer}>
                    {user.picture && (
                      <Image source={{uri: user.picture}} style={styles.avatar} />
                    )}
                    <Text style={styles.welcomeText}>Welcome, {user.name}!</Text>
                    <Text style={styles.emailText}>{user.email}</Text>
                    <View style={styles.buttonContainer}>
                      <Button title="Log Out" onPress={this.logout} color="#dc3545" />
                    </View>
                  </View>
                ) : (
                  <View style={styles.loginContainer}>
                    <Text style={styles.subtitle}>
                      Tap the button below to log in
                    </Text>
                    <View style={styles.buttonContainer}>
                      <Button title="Log In" onPress={this.login} color="#0066cc" />
                    </View>
                  </View>
                )}
              </View>
            );
          }
        }

        const styles = StyleSheet.create({
          container: {
            flex: 1,
            justifyContent: 'center',
            alignItems: 'center',
            padding: 20,
          },
          title: {
            fontSize: 28,
            fontWeight: 'bold',
            marginBottom: 20,
            color: '#333',
          },
          subtitle: {
            fontSize: 16,
            color: '#666',
            marginBottom: 30,
            textAlign: 'center',
          },
          loadingText: {
            marginTop: 10,
            fontSize: 16,
            color: '#666',
          },
          profileContainer: {
            alignItems: 'center',
          },
          avatar: {
            width: 100,
            height: 100,
            borderRadius: 50,
            marginBottom: 20,
          },
          welcomeText: {
            fontSize: 22,
            fontWeight: '600',
            marginBottom: 8,
            color: '#333',
          },
          emailText: {
            fontSize: 16,
            color: '#666',
            marginBottom: 30,
          },
          loginContainer: {
            alignItems: 'center',
          },
          buttonContainer: {
            width: 200,
            marginTop: 10,
          },
        });

        export default MainScreen;
        ```

        Replace `{yourDomain}` with your Auth0 domain and `{yourClientId}` with your Client ID from the Auth0 Dashboard.
      </Tab>
    </Tabs>

    <Info>
      The `authorize()` method (hooks) or `auth0.webAuth.authorize()` (class) opens Auth0's Universal Login in a secure browser (ASWebAuthenticationSession on iOS, Chrome Custom Tabs on Android). The `clearSession()` method logs the user out and clears both the browser session and stored credentials.
    </Info>
  </Step>

  <Step title="Run your app">
    Build and run your React Native application on a device or emulator.

    **For iOS (requires macOS):**

    ```bash theme={null}
    npx react-native run-ios
    ```

    **For Android:**

    ```bash theme={null}
    npx react-native run-android
    ```

    **Expected flow:**

    1. App launches showing "Log In" button
    2. Tap **Log In** → Browser opens with Auth0 Universal Login
    3. Complete login (sign up or sign in)
    4. Browser closes → Returns to app automatically
    5. User profile displays with name, email, and avatar

    <Warning>
      iOS Simulator requires a valid Apple Developer account for ASWebAuthenticationSession. For testing on simulator without an account, use a physical device or Android emulator instead.
    </Warning>
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a fully functional Auth0 login experience running on your device or emulator. The app uses secure browser authentication and automatically manages credentials.
</Check>

***

## Troubleshooting & Advanced

<Accordion title="Common Issues & Solutions">
  ### "Callback URL mismatch" error

  **Solution:**

  1. Verify the exact URL (including `.auth0` suffix) is in **Allowed Callback URLs** in your Auth0 Dashboard
  2. Ensure both iOS and Android URLs are added
  3. Check that `{yourDomain}` is replaced with your actual Auth0 domain

  ### App doesn't return after login (iOS)

  **Fix:**

  1. Check `Info.plist` has the `CFBundleURLSchemes` entry with `$(PRODUCT_BUNDLE_IDENTIFIER).auth0`
  2. Verify `AppDelegate.mm` includes the URL handling method
  3. Ensure the URL scheme matches your bundle identifier

  ### Android build fails

  **Fix:**

  1. Add `auth0Domain` and `auth0Scheme` manifest placeholders to `build.gradle`
  2. Sync project with Gradle files
  3. Clean build: `./gradlew clean`

  ### "PKCE not allowed" error

  **Fix:**

  1. Go to Auth0 Dashboard → Applications → Your Application
  2. Change application type to **Native**
  3. Save changes and try again

  ### Pod install fails (iOS)

  **Fix:**

  1. Update CocoaPods: `sudo gem install cocoapods`
  2. Update pod repo: `pod install --repo-update`
  3. If issues persist, delete `Podfile.lock` and `ios/Pods` folder, then run `pod install` again

  ### User cancelled error

  Handle gracefully in your login function:

  ```tsx expandable theme={null}
  const login = async () => {
    try {
      await authorize({scope: 'openid profile email'});
    } catch (e) {
      if (e.message === 'a0.session.user_cancelled') {
        // User closed login screen - handle gracefully
        console.log('Login cancelled by user');
      } else {
        console.error('Login failed:', e);
      }
    }
  };
  ```

  ### iOS Alert Dialog

  On iOS, users see a permission dialog: *"App Name" Wants to Use "auth0.com" to Sign In*. This is expected behavior from `ASWebAuthenticationSession`. Users must tap **Continue** to proceed.

  To customize this behavior, you can use ephemeral sessions (disables SSO):

  ```tsx theme={null}
  await authorize({scope: 'openid profile email'}, {ephemeralSession: true});
  ```
</Accordion>

<Accordion title="Retrieving Access Tokens">
  Use the `getCredentials()` method to retrieve tokens for API calls:

  ```tsx expandable lines theme={null}
  import {useAuth0} from 'react-native-auth0';

  const MyComponent = () => {
    const {getCredentials} = useAuth0();

    const callApi = async () => {
      try {
        const credentials = await getCredentials();
        const response = await fetch('https://your-api.com/endpoint', {
          headers: {
            Authorization: `Bearer ${credentials.accessToken}`,
          },
        });
        // Handle response
      } catch (e) {
        console.error('Failed to get credentials', e);
      }
    };
  };
  ```

  <Tip>
    Include the `offline_access` scope during login to receive a refresh token: `authorize({scope: 'openid profile email offline_access'})`. This enables automatic token renewal.
  </Tip>
</Accordion>

<Accordion title="Check Authentication Status on App Launch">
  Use `hasValidCredentials()` to check if the user is already logged in:

  ```tsx expandable lines theme={null}
  import {useAuth0} from 'react-native-auth0';
  import {useEffect} from 'react';

  const App = () => {
    const {hasValidCredentials, getCredentials} = useAuth0();

    useEffect(() => {
      const checkAuth = async () => {
        const isLoggedIn = await hasValidCredentials();
        if (isLoggedIn) {
          const credentials = await getCredentials();
          // User is authenticated, load their data
        }
      };
      checkAuth();
    }, []);
  };
  ```
</Accordion>

<Accordion title="Production Deployment">
  ### Before deploying to production

  **Use HTTPS callback URLs** for enhanced security:

  ```text theme={null}
  https://{yourDomain}/ios/{bundleId}/callback
  https://{yourDomain}/android/{packageName}/callback
  ```

  **Configure Android App Links** in Auth0 Dashboard:

  * Settings → Advanced Settings → Device Settings
  * Add your app's SHA-256 fingerprint

  **Configure iOS Universal Links:**

  * Add Associated Domains capability in Xcode
  * Add `webcredentials:{yourDomain}` to Associated Domains

  **Enable biometric authentication** for sensitive apps using `localAuthenticationOptions` in `Auth0Provider`

  **Review security settings** in Auth0 Dashboard:

  * Enable **OIDC Conformant** in Advanced Settings
  * Configure **Token Expiration** appropriately
  * Set up **Brute Force Protection**
  * Test on multiple devices and OS versions
  * Implement proper error handling for network failures
</Accordion>

* [Sample Application](https://github.com/auth0-samples/auth0-react-native-sample)
* [Migration Guide (v4 to v5)](https://github.com/auth0/react-native-auth0/blob/master/MIGRATION_GUIDE.md)


# Add Login to Your UWP application
Source: https://auth0.com/docs/quickstart/native/windows-uwp-csharp/interactive

This guide demonstrates how to integrate Auth0 with a UWP C# application using the OidcClient.UWP SDK.

<QuickstartButtons />

<Recipe>
  <Content>
    This tutorial demonstrates how to add user login to a UWP C# application using Auth0. We recommend that you log in
    to follow this quickstart with examples configured for your account.

    <Section title={sections[0].title}>
      This tutorial and sample project have been tested with the following:

      * Microsoft Visual Studio 2022
      * Windows 10 SDK (10.0.26100.0)
      * Auth0.OidcClient.UWP 4.0.0

      <Info>
        **New to Auth?** Learn [How Auth0 works](/docs/overview), how it [integrates with Native Applications](/docs/architecture-scenarios/application/mobile-api) and which [protocol](/docs/api-auth/grant/authorization-code-pkce) it uses.
      </Info>

      ### Get Your Application Keys

      When you signed up for Auth0, a new application was created for you, or you could have created a new one.
      You will need some details about that application to communicate with Auth0. You can get these details from
      the [Application Settings](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq/applications) section in the Auth0 dashboard.

      <Frame>
        <img />
      </Frame>

      <Info>
        When using the Default App with a Native or Single Page Application, ensure to update the
        **Token Endpoint Authentication Method** to `None` and set the
        **Application Type** to either `SPA` or `Native`.
      </Info>

      You need the following information:

      * **Domain**
      * **Client ID**

      <Info>
        If you download the sample from the top of this page, these details are filled out for you.
      </Info>

      markdownlint-disable MD002 MD041

      ### Configure Callback URLs

      A callback URL is a URL in your application where Auth0 redirects the user after they have authenticated. The
      callback URL for your app must be added to the **Allowed Callback URLs** field in your [Application Settings](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq/applications). If this field is not set, users will be unable to log in to the
      application and will get an error.

      <Info>
        If you are following along with the sample project you downloaded from the top of this page, you should
        set the **Allowed Callback URLs** to
        `https://{yourDomain}/mobile`.
      </Info>

      markdownlint-disable MD002 MD041

      ### Configure Logout URLs

      A logout URL is a URL in your application that Auth0 can return to after the user has been logged out of the
      authorization server. This is specified in the `returnTo` query parameter. The logout URL for your
      app must be added to the **Allowed Logout URLs** field in your [Application Settings](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq/applications). If this field is not set, users will be unable to log out from the
      application and will get an error.

      <Info>
        If you are following along with the sample project you downloaded from the top of this page, the
        logout URL you need to add to the **Allowed Logout URLs** field is
        `https://{yourDomain}/mobile`.
      </Info>
    </Section>

    <Section title={sections[1].title}>
      ### Get Your Application Keys

      When you signed up for Auth0, a new application was created for you, or you could have created a new one.
      You will need some details about that application to communicate with Auth0. You can get these details from
      the [Application Settings](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq/applications) section in the Auth0 dashboard.

      <Info>
        When using the Default App with a Native or Single Page Application, ensure to update the
        **Token Endpoint Authentication Method** to `None` and set the
        **Application Type** to either `SPA` or `Native`.
      </Info>

      You need the following information:

      * **Domain**
      * **Client ID**

      <Info>
        If you download the sample from the top of this page, these details are filled out for you.
      </Info>
    </Section>

    <Section title={sections[2].title}>
      Use the NuGet Package Manager Console (Tools -> NuGet Package Manager -> Package Manager Console) to
      install the `Auth0.OidcClient.UWP` package, running the command:

      ```
      Install-Package Auth0.OidcClient.UWP
      ```
    </Section>

    <Section title={sections[3].title}>
      To integrate Auth0 login into your application, simply instantiate an instance of the `Auth0Client`
      class, configuring the Auth0 Domain and Client ID:

      ```cs lines theme={null}
      // MainPage.xaml.cs

      using Auth0.OidcClient;

      var client = new Auth0Client(new Auth0ClientOptions
      {
          Domain = "{yourDomain}",
          ClientId = "{yourClientId}"
      });
      ```

      You can then call the `LoginAsync` method to log the user in:

      ```cs lines theme={null}
      var loginResult = await client.LoginAsync();
      ```

      <Frame>
        <img />
      </Frame>

      This loads the Auth0 login page into a web view. You can learn how to customize the login page at [this document](/docs/universal-login#simple-customization).
    </Section>

    <Section title={sections[4].title}>
      The returned login result indicates whether authentication was successful, and if so contains the tokens and
      claims of the user.

      ### Authentication Error

      You can check the `IsError` property of the result to see whether the login has failed. The
      `ErrorMessage` contains more information regarding the error which occurred.

      ```cs lines theme={null}
      if (loginResult.IsError)
      {
          Debug.WriteLine($"An error occurred during login: {loginResult.Error}")
      }
      ```

      ### Accessing the tokens

      On successful login, the login result contains the ID Token and Access Token in the `IdentityToken`
      and `AccessToken` properties respectively.

      ```cs lines theme={null}
      if (!loginResult.IsError)
      {
          Debug.WriteLine($"id_token: {loginResult.IdentityToken}");
          Debug.WriteLine($"access_token: {loginResult.AccessToken}");
      }
      ```

      ### Obtaining the User Information

      On successful login, the login result contains the user information in the `User` property, which is a
      [ClaimsPrincipal](https://msdn.microsoft.com/en-us/library/system.security.claims.claimsprincipal\(v=vs.110\).aspx).

      To obtain information about the user, you can query the claims. You can for example obtain the user's name and
      email address from the `name` and `email` claims:

      ```cs lines theme={null}
      if (!loginResult.IsError)
      {
          Debug.WriteLine($"name: {loginResult.User.FindFirst(c => c.Type == "name")?.Value}");
          Debug.WriteLine($"email: {loginResult.User.FindFirst(c => c.Type == "email")?.Value}");
      }
      ```

      <Info>
        The exact claims returned depends on the scopes that were requested. For more information see @scopes.
      </Info>

      You can obtain a list of all the claims contained in the ID Token by iterating through the `Claims`
      collection:

      ```cs lines theme={null}
      if (!loginResult.IsError)
      {
          foreach (var claim in loginResult.User.Claims)
          {
              Debug.WriteLine($"{claim.Type} = {claim.Value}");
          }
      }
      ```
    </Section>

    <Section title={sections[5].title}>
      To log the user out call the `LogoutAsync` method.

      ```cs lines theme={null}
      await client.LogoutAsync();
      ```
    </Section>

    ## Next Steps

    Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.

    This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:

    * [Auth0 Dashboard](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq) - Learn how to configure and manage your Auth0 tenant and applications
    * [auth0-oidc-client-net SDK](https://github.com/auth0/auth0-oidc-client-net) - Explore the SDK used in this tutorial more fully
    * [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
  </Content>

  <SideMenu>
    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      ```cs MainPage.xaml.cs lines  theme={null}
      // MainPage.xaml.cs

      using Auth0.OidcClient;

      var client = new Auth0Client(new Auth0ClientOptions
      {
          Domain = "{yourDomain}",
          ClientId = "{yourClientId}"
      });
      ```
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>
  </SideMenu>
</Recipe>


# Add Login to Your WPF or WinForms Application
Source: https://auth0.com/docs/quickstart/native/wpf-winforms/interactive

This tutorial demonstrates how to add user login with Auth0 to a WPF and WinForms application.

<QuickstartButtons />

<Recipe>
  <Content>
    Auth0 allows you to add authentication to almost any application type quickly. This guide demonstrates how to
    integrate Auth0, add authentication, and display user profile information in any WPF and WinForms application using
    the Auth0 SDKs for [WPF](https://www.nuget.org/packages/Auth0.OidcClient.WPF/) and [WinForms](https://www.nuget.org/packages/Auth0.OidcClient.WinForms).

    To use this quickstart, you’ll need to:

    <Section title={sections[0].title}>
      To use Auth0 services, you’ll need to have an application set up in the Auth0 Dashboard. The Auth0 application is
      where you will configure how you want authentication to work for the project you are developing.

      ### Configure an application

      Use the interactive selector to create a new Auth0 application or select an existing application that represents
      the project you want to integrate with. Every application in Auth0 is assigned an alphanumeric, unique client ID
      that your application code will use to call Auth0 APIs through the SDK.

      Any settings you configure using this quickstart will automatically update for your Application in the [Dashboard](https://manage.auth0.com/#/), which is where you
      can manage your Applications in the future.

      If you would rather explore a complete configuration, you can view a sample application instead.

      ### Configure Callback URLs

      A callback URL is a URL in your application that you would like Auth0 to redirect users to after they have
      authenticated. If not set, users will not be returned to your application after they log in.

      <Info>
        If you are following along with our sample project, set this to
        `http://{yourDomain}:4200/mobile`.
      </Info>

      ### Configure Logout URLs

      A logout URL is a URL in your application that you would like Auth0 to redirect users to after they have logged
      out. If not set, users will not be able to log out from your application and will receive an error.

      <Info>
        If you are following along with our sample project, set this to
        `http://{yourDomain}:4200/mobile`.
      </Info>
    </Section>

    <Section title={sections[1].title}>
      Auth0 provides a [WPF](https://www.nuget.org/packages/Auth0.OidcClient.WPF/) and [WinForms](https://www.nuget.org/packages/Auth0.OidcClient.WinForms) SDK to simplify the process of implementing Auth0
      authentication in WPF and WinForms applications.

      Use the NuGet Package Manager (Tools -> Library Package Manager -> Package Manager Console) to install the
      `Auth0.OidcClient.WPF` or `Auth0.OidcClient.WinForms` package, depending on whether you are
      building a WPF or Windows Forms application.

      Alternatively, you can use the NuGet Package Manager Console (`Install-Package`) or the
      `dotnet` CLI (`dotnet add`).

      ```
      Install-Package Auth0.OidcClient.WPF
      Install-Package Auth0.OidcClient.WinForms
      ```

      ```
      dotnet add Auth0.OidcClient.WPF
      dotnet add Auth0.OidcClient.WinForms
      ```
    </Section>

    <Section title={sections[2].title}>
      To integrate Auth0 into your application, instantiate an instance of the Auth0Client class, passing an instance
      of Auth0ClientOptions that contains your Auth0 Domain and Client ID.

      By default, the SDK will leverage [WebView2](https://learn.microsoft.com/en-us/microsoft-edge/webview2/) for .NET6 and above, while relying on the older WebView
      on applications using any version that predates .NET6.

      <Note>
        ##### Checkpoint

        Your `Auth0Client` should now be properly instantiated. Run your application to verify that:

        * The `Auth0Client`is instantiated correctly.
        * Your application is not throwing any errors related to Auth0.
      </Note>
    </Section>

    <Section title={sections[3].title}>
      Now that you have configured your Auth0 Application and the Auth0 SDK, you need to set up login for your project.
      To do this, you will use the SDK’s `LoginAsync()` method to create a login button that redirects users
      to the Auth0 Universal Login page. After a user successfully authenticates, they will be redirected to the
      callback URL you set up earlier in this quickstart.

      If there isn't any error, you can access the `User`, `IdentityToken`,
      `AccessToken` and `RefreshToken` on the `LoginResult` returned from
      `LoginAsync()`.

      <Note>
        ##### Checkpoint

        You should now be able to log in or sign up using a username and password.

        Click the login button and verify that:

        * Your WPF or WinForms Application redirects you to the Auth0 Universal Login page.
        * You can log in or sign up.
        * Auth0 redirects you to your application.
      </Note>
    </Section>

    <Section title={sections[4].title}>
      Users who log in to your project will also need a way to log out. Create a logout button using the SDK’s
      `LogoutAsync()` method. When users log out, they will be redirected to your Auth0 logout endpoint,
      which will then immediately redirect them back to the logout URL you set up earlier in this quickstart.

      <Note>
        ##### Checkpoint

        Run your application and click the logout button, verify that:

        * Your WPF or WinForms application redirects you to the address you specified as one of the Allowed
          Logout URLs in your Application Settings.
        * You are no longer logged in to your application.
      </Note>
    </Section>

    <Section title={sections[5].title}>
      Now that your users can log in and log out, you will likely want to be able to retrieve the profile information associated with authenticated users.
      For example, you may want to display a logged-in user’s name or profile picture in your project.

      The Auth0 SDK for WPF and WinForms provides user information through the `LoginResult.User` property.

      <Note>
        ##### Checkpoint

        Verify that you can display the user's name or other user property after logging in.
      </Note>
    </Section>

    ## Next Steps

    Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.

    This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:

    * [Auth0 Dashboard](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq) - Learn how to configure and manage your Auth0 tenant and applications
    * [auth0-oidc-client-net SDK](https://github.com/auth0/auth0-oidc-client-net) - Explore the SDK used in this tutorial more fully
    * [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
  </Content>

  <SideMenu>
    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      ```cs MainWindow.xaml.cs lines highlight={13-22} theme={null}
      using Auth0.OidcClient;

      public partial class MainWindow : Window
      {
          private Auth0Client client;

          public MainWindow()
          {
              InitializeComponent();
              InitializeClient();
          }

          private InitializeClient()
          {
              Auth0ClientOptions clientOptions = new Auth0ClientOptions
              {
                  Domain = "{yourDomain}",
                  ClientId = "{yourClientId}"
              };
              client = new Auth0Client(clientOptions);
              clientOptions.PostLogoutRedirectUri = clientOptions.RedirectUri;
          }

          private async void LoginButton_OnClick(object sender, RoutedEventArgs e) 
          {
              var loginResult = await client.LoginAsync();

              if (loginResult.IsError == false)
              {
                  var user = loginResult.User;
                  var name = user.FindFirst(c => c.Type == "name")?.Value;
                  var email = user.FindFirst(c => c.Type == "email")?.Value;
                  var picture = user.FindFirst(c => c.Type == "picture")?.Value;
              }
          }

          private async void LogoutButton_Click(object sender, RoutedEventArgs e)
          {
              await client.LogoutAsync();
          }
      }
      ```
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      ```cs MainWindow.xaml.cs lines highlight={24-35} theme={null}
      using Auth0.OidcClient;

      public partial class MainWindow : Window
      {
          private Auth0Client client;

          public MainWindow()
          {
              InitializeComponent();
              InitializeClient();
          }

          private InitializeClient()
          {
              Auth0ClientOptions clientOptions = new Auth0ClientOptions
              {
                  Domain = "{yourDomain}",
                  ClientId = "{yourClientId}"
              };
              client = new Auth0Client(clientOptions);
              clientOptions.PostLogoutRedirectUri = clientOptions.RedirectUri;
          }

          private async void LoginButton_OnClick(object sender, RoutedEventArgs e) 
          {
              var loginResult = await client.LoginAsync();

              if (loginResult.IsError == false)
              {
                  var user = loginResult.User;
                  var name = user.FindFirst(c => c.Type == "name")?.Value;
                  var email = user.FindFirst(c => c.Type == "email")?.Value;
                  var picture = user.FindFirst(c => c.Type == "picture")?.Value;
              }
          }

          private async void LogoutButton_Click(object sender, RoutedEventArgs e)
          {
              await client.LogoutAsync();
          }
      }
      ```
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      ```cs MainWindow.xaml.cs lines highlight={37-40} theme={null}
      using Auth0.OidcClient;

      public partial class MainWindow : Window
      {
          private Auth0Client client;

          public MainWindow()
          {
              InitializeComponent();
              InitializeClient();
          }

          private InitializeClient()
          {
              Auth0ClientOptions clientOptions = new Auth0ClientOptions
              {
                  Domain = "{yourDomain}",
                  ClientId = "{yourClientId}"
              };
              client = new Auth0Client(clientOptions);
              clientOptions.PostLogoutRedirectUri = clientOptions.RedirectUri;
          }

          private async void LoginButton_OnClick(object sender, RoutedEventArgs e) 
          {
              var loginResult = await client.LoginAsync();

              if (loginResult.IsError == false)
              {
                  var user = loginResult.User;
                  var name = user.FindFirst(c => c.Type == "name")?.Value;
                  var email = user.FindFirst(c => c.Type == "email")?.Value;
                  var picture = user.FindFirst(c => c.Type == "picture")?.Value;
              }
          }

          private async void LogoutButton_Click(object sender, RoutedEventArgs e)
          {
              await client.LogoutAsync();
          }
      }
      ```
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      ```cs MainWindow.xaml.cs lines highlight={30-33} theme={null}
      using Auth0.OidcClient;

      public partial class MainWindow : Window
      {
          private Auth0Client client;

          public MainWindow()
          {
              InitializeComponent();
              InitializeClient();
          }

          private InitializeClient()
          {
              Auth0ClientOptions clientOptions = new Auth0ClientOptions
              {
                  Domain = "{yourDomain}",
                  ClientId = "{yourClientId}"
              };
              client = new Auth0Client(clientOptions);
              clientOptions.PostLogoutRedirectUri = clientOptions.RedirectUri;
          }

          private async void LoginButton_OnClick(object sender, RoutedEventArgs e) 
          {
              var loginResult = await client.LoginAsync();

              if (loginResult.IsError == false)
              {
                  var user = loginResult.User;
                  var name = user.FindFirst(c => c.Type == "name")?.Value;
                  var email = user.FindFirst(c => c.Type == "email")?.Value;
                  var picture = user.FindFirst(c => c.Type == "picture")?.Value;
              }
          }

          private async void LogoutButton_Click(object sender, RoutedEventArgs e)
          {
              await client.LogoutAsync();
          }
      }
      ```
    </SideMenuSectionItem>
  </SideMenu>
</Recipe>


# Add Login to Your .NET Android & iOS Application
Source: https://auth0.com/docs/quickstart/native/xamarin



# .NET Android and iOS

<Frame>
  <img alt="Gravatar for frederik.prijck@auth0.com" />
</Frame>

##### By Frederik Prijck

This tutorial demonstrates how to add user login with Auth0 to a .NET Android or iOS application.We recommend that you log in to follow this quickstart with examples configured for your account.

This quickstart focusses on .NET Android and iOS, as they are the next generation of `Xamarin.Android` and `Xamarin.iOS`. If you are still using `Xamarin.Android` and `Xamarin.iOS`, you can follow this guide as well as integration is identical and the SDKs are compatible.

**New to Auth?** Learn [How Auth0 works](/docs/overview), how it [integrates with Native Applications](/docs/architecture-scenarios/application/mobile-api) and which [protocol](/docs/api-auth/grant/authorization-code-pkce) it uses.

## Configure Auth0

### Get Your Application Keys

When you signed up for Auth0, a new application was created for you, or you could have created a new one. You will need some details about that application to communicate with Auth0. You can get these details from the [Application Settings](https://manage.auth0.com/#/applications) section in the Auth0 dashboard.

<Frame>![App Dashboard](https://cdn2.auth0.com/docs/1.14550.0/media/articles/dashboard/client_settings.png)</Frame>

When using the Default App with a Native or Single Page Application, ensure to update the **Token Endpoint Authentication Method** to `None` and set the **Application Type** to either `SPA` or `Native`.

You need the following information:

* **Domain**
* **Client ID**

If you download the sample from the top of this page, these details are filled out for you.

### Configure Callback URLs

A callback URL is a URL in your application where Auth0 redirects the user after they have authenticated. The callback URL for your app must be added to the **Allowed Callback URLs** field in your [Application Settings](https://manage.auth0.com/#/applications). If this field is not set, users will be unable to log in to the application and will get an error.

Callback URLs are the URLs that Auth0 invokes after the authentication process. Auth0 routes your application back to this URL and appends additional parameters to it, including an access code which will be exchanged for an ID Token, Access Token, and Refresh Token.

Since callback URLs can be manipulated, you will need to add your application's URL to your application's *Allowed Callback URLs* for security. This will enable Auth0 to recognize these URLs as valid. If omitted, authentication will not be successful.

* For Android, the callback URL will be in the format

  ```
  YOUR_ANDROID_PACKAGE_NAME://{yourDomain}/android/YOUR_ANDROID_PACKAGE_NAME/callback
  ```

  where `YOUR_ANDROID_PACKAGE_NAME` is the Package Name for your application, such as `com.mycompany.myapplication`.
* For iOS, the callback URL will be in the format

  ```
  YOUR_BUNDLE_IDENTIFIER://{yourDomain}/ios/YOUR_BUNDLE_IDENTIFIER/callback
  ```

  where `YOUR_BUNDLE_IDENTIFIER` is the Bundle Identifier for your application, such as `com.mycompany.myapplication`.

Ensure that the Callback URL is in lowercase.

### Configure Logout URLs

A logout URL is a URL in your application that Auth0 can return to after the user has been logged out of the authorization server. This is specified in the `returnTo` query parameter. The logout URL for your app must be added to the **Allowed Logout URLs** field in your [Application Settings](https://manage.auth0.com/#/applications). If this field is not set, users will be unable to log out from the application and will get an error.

If you are following along with the sample project you downloaded from the top of this page, the logout URL you need to add to the Allowed Logout URLs field is the same as the callback URL.

## Install Dependencies

If you are using Visual Studio, simply open the Package Manager Console (View -> Other Windows -> Package Manager Console), and install the package:

**For Android:**

```
Install-Package Auth0.OidcClient.AndroidX
```

**For iOS:**

```
Install-Package Auth0.OidcClient.iOS
```

Alternatively, if you are using Visual Studio for Mac, please perform the following steps:

1. With the project loaded in Visual Studio for Mac, Ctrl+click (or right click) on the **Packages** folder of the project in the **Solution Pad**, and select **Add Packages...**
2. The **Add Packages** dialog will appear. Search and locate the package called `Auth0.OidcClient.AndroidX` or `Auth0.OidcClient.iOS` depending on your platform.
3. Tick the checkbox next to the package to select it, and click the **Add Package** button

## Trigger Authentication

To integrate Auth0 login into your application, instantiate an instance of the `Auth0Client` class, configuring the Auth0 Domain and Client ID:

```
using Auth0.OidcClient;

var client = new Auth0Client(new Auth0ClientOptions
{
    Domain = "{yourDomain}",
    ClientId = "{yourClientId}"
}, this);
```

Then, call the `LoginAsync` method which will redirect the user to the login screen. You will typically do this in the event handler for a UI control such as a Login button.

```javascript lines theme={null}
var loginResult = await client.LoginAsync();
```

### Handing the callback URL

After a user has logged in, they will be redirected back to your application at the **Callback URL** that was registered before. In both Android and iOS you need to handle this callback to complete the authentication flow.

### Android

Register an intent which will handle this callback URL. An easy way to do this is to register the intent on the same activity from which you called the `LoginAsync` method to initiate the authentication flow.

<AuthCodeBlock />

Replace `YOUR_ANDROID_PACKAGE_NAME` in the code sample above with the actual Package Name for your application, such as `com.mycompany.myapplication`. Also ensure that all the text for the `DataScheme`, `DataHost`, and `DataPathPrefix` is in lower case. Also, set `LaunchMode = LaunchMode.SingleTask` for the `Activity`, otherwise the system will create a new instance of the activity every time the Callback URL gets called.

Now write code to handle the intent. You can do this by overriding the `OnNewIntent` method. Inside the method you need to call the `Send` method on the `ActivityMediator` to complete the authentication cycle:

```
protected override async void OnNewIntent(Intent intent)
{
    base.OnNewIntent(intent);

    Auth0.OidcClient.ActivityMediator.Instance.Send(intent.DataString);
}
```

### iOS

Register the URL scheme for your Callback URL which your application should handle:

1. Open your application's `Info.plist` file in Visual Studio for Mac, and go to the **Advanced** tab.
2. Under **URL Types**, click the **Add URL Type** button
3. Set the **Identifier** as `Auth0`, the **URL Schemes** the same as your application's **Bundle Identifier**, and the **Role** as `None`

This is an example of the XML representation of your `info.plist` file after you have added the URL Type:

```
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleTypeRole</key>
        <string>None</string>
        <key>CFBundleURLName</key>
        <string>Auth0</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>YOUR_BUNDLE_IDENTIFIER</string>
        </array>
    </dict>
</array>
```

You need to handle the Callback URL in the `OpenUrl` event in your `AppDelegate` class. You need to notify the Auth0 OIDC Client to finish the authentication flow by calling the `Send` method of the `ActivityMediator` singleton, pass along the URL that was sent in:

```
using Auth0.OidcClient;

[Register("AppDelegate")]
public class AppDelegate : UIApplicationDelegate
{
    public override bool OpenUrl(UIApplication application, NSUrl url, string sourceApplication, NSObject annotation)
    {
        ActivityMediator.Instance.Send(url.AbsoluteString);

        return true;
    }
}
```

### Run the application

With the above code in place, a user can log in to your application using Auth0.

<Frame>![Universal Login](https://cdn2.auth0.com/docs/1.14550.0/media/articles/native-platforms/android/login-android.png)</Frame>

## Accessing the User's Information

The returned login result will indicate whether authentication was successful and if so contain the tokens and claims of the user.

### Authentication Error

You can check the `IsError` property of the result to see whether the login has failed. The `ErrorMessage` will contain more information regarding the error which occurred.

```javascript lines theme={null}
var loginResult = await client.LoginAsync();

if (loginResult.IsError)
{
    Debug.WriteLine($"An error occurred during login: {loginResult.Error}")
}
```

### Accessing the tokens

On successful login, the login result will contain the ID Token and Access Token in the `IdentityToken` and `AccessToken` properties respectively.

```javascript lines theme={null}
var loginResult = await client.LoginAsync();

if (!loginResult.IsError)
{
    Debug.WriteLine($"id_token: {loginResult.IdentityToken}");
    Debug.WriteLine($"access_token: {loginResult.AccessToken}");
}
```

### Obtaining the User Information

On successful login, the login result will contain the user information in the `User` property, which is a [ClaimsPrincipal](https://msdn.microsoft.com/en-us/library/system.security.claims.claimsprincipal\(v=vs.110\).aspx).

To obtain information about the user, you can query the claims. You can, for example, obtain the user's name and email address from the `name` and `email` claims:

```
if (!loginResult.IsError)
{
    Debug.WriteLine($"name: {loginResult.User.FindFirst(c => c.Type == "name")?.Value}");
    Debug.WriteLine($"email: {loginResult.User.FindFirst(c => c.Type == "email")?.Value}");
}
```

The exact claims returned will depend on the scopes that were requested. For more information see the [Using Scopes](https://auth0.github.io/auth0-oidc-client-net/documentation/advanced-scenarios/scopes.html) in the Auth0 OIDC Application documentation.

You can obtain a list of all the claims contained in the ID Token by iterating through the `Claims` collection:

```
if (!loginResult.IsError)
{
    foreach (var claim in loginResult.User.Claims)
    {
        Debug.WriteLine($"{claim.Type} = {claim.Value}");
    }
}
```

## Logout

To log the user out call the `LogoutAsync` method.

```
BrowserResultType browserResult = await client.LogoutAsync();
```

##### What can you do next?

[\* Configure other identity providers](/docs/authenticate/identity-providers)[\* Enable multifactor authentication](/docs/secure/multi-factor-authentication)[\* Learn about attack protection](/docs/secure/attack-protection)[\* Learn about rules](/docs/rules)

***

[Edit on GitHub](https://github.com/auth0/docs/edit/master/articles/quickstart/native/net-android-ios/01-login.md)


# Add Login to Your Angular Application
Source: https://auth0.com/docs/quickstart/spa/angular/index

This guide demonstrates how to integrate Auth0, add authentication, and display user profile information in any Angular application using the Auth0 Angular SDK.

<Accordion title="Use AI to integrate Auth0" icon="microchip-ai">
  If you use an AI coding assistant like Claude Code, Cursor, or GitHub Copilot, you can add Auth0 authentication automatically in minutes using [agent skills](https://agentskills.io/home).

  **Install:**

  ```bash theme={null}
  npx skills add auth0/agent-skills --skill auth0-quickstart --skill auth0-angular
  ```

  **Then ask your AI assistant:**

  ```text theme={null}
  Add Auth0 authentication to my Angular app
  ```

  Your AI assistant will automatically create your Auth0 application, fetch credentials, install `@auth0/auth0-angular`, create route guards and HTTP interceptors, and configure your environment. [Full agent skills documentation →](/quickstart/agent-skills)
</Accordion>

<Note>
  **Prerequisites:** Before you begin, ensure you have the following installed:

  * **[Node.js](https://nodejs.org/en/download)** 20 LTS or newer
  * **[npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)** 10+ or **[yarn](https://classic.yarnpkg.com/lang/en/docs/install/)** 1.22+ or **[pnpm](https://pnpm.io/installation)** 8+
  * **[jq](https://jqlang.org/)** - Required for Auth0 CLI setup

  Verify installation: `node --version && npm --version`

  **Angular Version Compatibility:** This quickstart works with **Angular 18.x** and newer using the Angular CLI. For older versions of Angular, use the Auth0 Angular SDK v2.
</Note>

## Get Started

This quickstart demonstrates how to add Auth0 authentication to an Angular application. You'll build a secure single-page app with login and logout functionality using Angular's dependency injection system and the Auth0 Angular SDK.

<Steps>
  <Step title="Create a new project">
    Create a new Angular project for this Quickstart

    ```shellscript theme={null}
    npx @angular/cli@latest new auth0-angular --routing=true --style=css
    ```

    Open the project

    ```shellscript theme={null}
    cd auth0-angular
    ```
  </Step>

  <Step title="Install the Auth0 Angular SDK">
    ```shellscript theme={null}
    npm install @auth0/auth0-angular && npm install
    ```
  </Step>

  <Step title="Setup your Auth0 App">
    Next up, you need to create a new app on your Auth0 tenant and add the environment variables to your project.

    You have three options to set up your Auth0 app: use the Quick Setup tool (recommended), run a CLI command, or configure manually via the Dashboard:

    <Tabs>
      <Tab title="Quick Setup (recommended)">
        Create an Auth0 App and copy the pre-filled `.env` file with the right configuration values.

        <CreateInteractiveApp />

        <AuthCodeBlock />
      </Tab>

      <Tab title="CLI">
        Run the following shell command on your project's root directory to create an Auth0 app and generate an environment file:

        <AuthCodeGroup>
          ```shellscript Mac theme={null}
          AUTH0_APP_NAME="My Angular App" && brew tap auth0/auth0-cli && brew install auth0 && auth0 login --no-input && auth0 apps create -n "${AUTH0_APP_NAME}" -t spa -c http://localhost:4200 -l http://localhost:4200 -o http://localhost:4200 --json --metadata created_by="quickstart-docs-manual" > auth0-app-details.json && CLIENT_ID=$(jq -r '.client_id' auth0-app-details.json) && DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name') && mkdir -p src/environments && echo "export const environment = { production: false, auth0: { domain: '${DOMAIN}', clientId: '${CLIENT_ID}' } };" > src/environments/environment.ts && rm auth0-app-details.json && echo "Environment file created at src/environments/environment.ts with your Auth0 details:" && cat src/environments/environment.ts
          ```

          ```shellscript Windows theme={null}
          $AppName = "My Angular App"; winget install Auth0.CLI; auth0 login --no-input; auth0 apps create -n "$AppName" -t spa -c http://localhost:4200 -l http://localhost:4200 -o http://localhost:4200 --json --metadata created_by="quickstart-docs-manual" | Set-Content -Path auth0-app-details.json; $ClientId = (Get-Content -Raw auth0-app-details.json | ConvertFrom-Json).client_id; $Domain = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name; New-Item -ItemType Directory -Force -Path "src\environments"; Set-Content -Path "src\environments\environment.ts" -Value "export const environment = { production: false, auth0: { domain: '$Domain', clientId: '$ClientId' } };"; Remove-Item auth0-app-details.json; Write-Output "Environment file created at src\environments\environment.ts with your Auth0 details:"; Get-Content "src\environments\environment.ts"
          ```
        </AuthCodeGroup>
      </Tab>

      <Tab title="Dashboard">
        Before you start, create an environment file on your project

        ```typescript src/environments/environment.ts theme={null}
        export const environment = {
          production: false,
          auth0: {
            domain: 'YOUR_AUTH0_APP_DOMAIN',
            clientId: 'YOUR_AUTH0_APP_CLIENT_ID'
          }
        };
        ```

        1. Head to the [Auth0 Dashboard](https://manage.auth0.com/dashboard/)
        2. Click on **Applications** > **Applications** > **Create Application**
        3. In the popup, enter a name for your app, select `Single Page Web Application` as the app type and click **Create**
        4. Switch to the **Settings** tab on the Application Details page
        5. Replace `YOUR_AUTH0_APP_DOMAIN` and `YOUR_AUTH0_APP_CLIENT_ID` in the `src/environments/environment.ts` file with the **Domain** and **Client ID** values from the dashboard

        Finally, on the **Settings** tab of your Application Details page, configure the following URLs:

        **Allowed Callback URLs:**

        ```
        http://localhost:4200
        ```

        **Allowed Logout URLs:**

        ```
        http://localhost:4200
        ```

        **Allowed Web Origins:**

        ```
        http://localhost:4200
        ```

        <Info>
          **Allowed Callback URLs** are a critical security measure to ensure users are safely returned to your application after authentication. Without a matching URL, the login process will fail, and users will be blocked by an Auth0 error page instead of accessing your app.

          **Allowed Logout URLs** are essential for providing a seamless user experience upon signing out. Without a matching URL, users will not be redirected back to your application after logout and will instead be left on a generic Auth0 page.

          **Allowed Web Origins** is critical for silent authentication. Without it, users will be logged out when they refresh the page or return to your app later.
        </Info>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure the Auth0 module">
    The CLI script has already created your environment file. Now configure the Auth0 module in your app:

    ```typescript src/main.ts {3,4,5,9-15} lines theme={null}
    import { bootstrapApplication } from '@angular/platform-browser';
    import { appConfig } from './app/app.config';
    import { provideAuth0 } from '@auth0/auth0-angular';
    import { mergeApplicationConfig } from '@angular/core';
    import { environment } from './environments/environment';
    import { AppComponent } from './app/app.component';

    const auth0Config = mergeApplicationConfig(appConfig, {
      providers: [
        provideAuth0({
          domain: environment.auth0.domain,
          clientId: environment.auth0.clientId,
          authorizationParams: {
            redirect_uri: window.location.origin
          }
        })
      ]
    });

    bootstrapApplication(AppComponent, auth0Config).catch((err) =>
      console.error(err)
    );
    ```

    <Note>
      If you set up your Auth0 app manually via the dashboard, create `src/environments/environment.ts` with your domain and client ID from the dashboard.
    </Note>
  </Step>

  <Step title="Create Login, Logout and Profile Components">
    Create the component files manually for better control

    <CodeGroup>
      ```shellscript Mac/Linux theme={null}
      mkdir -p src/app/components && touch src/app/components/login-button.component.ts && touch src/app/components/logout-button.component.ts && touch src/app/components/profile.component.ts
      ```

      ```powershell Windows theme={null}
      New-Item -ItemType Directory -Force -Path src/app/components
      New-Item -ItemType File -Path src/app/components/login-button.component.ts
      New-Item -ItemType File -Path src/app/components/logout-button.component.ts
      New-Item -ItemType File -Path src/app/components/profile.component.ts
      ```
    </CodeGroup>

    Add the following code to each component:

    <AuthCodeGroup>
      ```typescript src/app/components/login-button.component.ts expandable lines theme={null}
      import { Component, inject } from '@angular/core';
      import { AuthService } from '@auth0/auth0-angular';

      @Component({
        selector: 'app-login-button',
        standalone: true,
        template: `
          <button 
            (click)="loginWithRedirect()" 
            class="button login"
          >
            Log In
          </button>
        `
      })
      export class LoginButtonComponent {
        private auth = inject(AuthService);

        loginWithRedirect(): void {
          this.auth.loginWithRedirect();
        }
      }
      ```

      ```typescript src/app/components/logout-button.component.ts expandable lines theme={null}
      import { Component, inject } from '@angular/core';
      import { AuthService } from '@auth0/auth0-angular';

      @Component({
        selector: 'app-logout-button',
        standalone: true,
        template: `
          <button
            (click)="logout()"
            class="button logout"
          >
            Log Out
          </button>
        `
      })
      export class LogoutButtonComponent {
        private auth = inject(AuthService);

        logout(): void {
          this.auth.logout({ 
            logoutParams: { 
              returnTo: window.location.origin 
            } 
          });
        }
      }
      ```

      ```typescript src/app/components/profile.component.ts expandable lines theme={null}
      import { Component, inject } from '@angular/core';
      import { AuthService } from '@auth0/auth0-angular';
      import { CommonModule } from '@angular/common';

      @Component({
        selector: 'app-profile',
        standalone: true,
        imports: [CommonModule],
        template: `
          @if (auth.isLoading$ | async) {
            <div class="loading-text">Loading profile...</div>
          }
          
          @if ((auth.isAuthenticated$ | async) && (auth.user$ | async); as user) {
            <div style="display: flex; flex-direction: column; align-items: center; gap: 1rem;">
              @if (user.picture) {
                <img 
                  [src]="user.picture" 
                  [alt]="user.name || 'User'"
                  class="profile-picture"
                  style="
                    width: 110px; 
                    height: 110px; 
                    border-radius: 50%; 
                    object-fit: cover;
                    border: 3px solid #63b3ed;
                  "
                />
              }
              <div style="text-align: center;">
                <div 
                  class="profile-name" 
                  style="
                    font-size: 2rem; 
                    font-weight: 600; 
                    color: #f7fafc; 
                    margin-bottom: 0.5rem;
                  "
                >
                  {{ user.name }}
                </div>
                <div 
                  class="profile-email" 
                  style="
                    font-size: 1.15rem; 
                    color: #a0aec0;
                  "
                >
                  {{ user.email }}
                </div>
              </div>
            </div>
          }
        `
      })
      export class ProfileComponent {
        protected auth = inject(AuthService);
      }
      ```
    </AuthCodeGroup>

    Now update the main App Component and add styling:

    <Tabs>
      <Tab title="App Component">
        Replace the contents of `src/app/app.component.ts`:

        ```typescript src/app/app.ts expandable lines theme={null}
        import { Component, inject } from '@angular/core';
        import { AuthService } from '@auth0/auth0-angular';
        import { CommonModule } from '@angular/common';
        import { LoginButtonComponent } from './components/login-button.component';
        import { LogoutButtonComponent } from './components/logout-button.component';
        import { ProfileComponent } from './components/profile.component';

        @Component({
          selector: 'app-root',
          standalone: true,
          imports: [CommonModule, LoginButtonComponent, LogoutButtonComponent, ProfileComponent],
          template: `
            <div class="app-container">
              <!-- Loading State -->
              @if (auth.isLoading$ | async) {
                <div class="loading-state">
                  <div class="loading-text">Loading...</div>
                </div>
              }

              <!-- Error State -->
              @if (auth.error$ | async; as error) {
                <div class="error-state">
                  <div class="error-title">Oops!</div>
                  <div class="error-message">Something went wrong</div>
                  <div class="error-sub-message">{{ error.message }}</div>
                </div>
              }

              <!-- Main Content -->
              @if (!(auth.isLoading$ | async) && !(auth.error$ | async)) {
                <div class="main-card-wrapper">
                  <img 
                    src="https://cdn.auth0.com/quantum-assets/dist/latest/logos/auth0/auth0-lockup-en-ondark.png" 
                    alt="Auth0 Logo" 
                    class="auth0-logo"
                  />
                  <h1 class="main-title">Welcome to Sample0</h1>
                  
                  <!-- Authenticated State -->
                  @if (auth.isAuthenticated$ | async) {
                    <div class="logged-in-section">
                      <div class="logged-in-message">✅ Successfully authenticated!</div>
                      <h2 class="profile-section-title">Your Profile</h2>
                      <div class="profile-card">
                        <app-profile />
                      </div>
                      <app-logout-button />
                    </div>
                  } @else {
                    <!-- Unauthenticated State -->
                    <div class="action-card">
                      <p class="action-text">Get started by signing in to your account</p>
                      <app-login-button />
                    </div>
                  }
                </div>
              }
            </div>
          `,
          styles: []
        })
        export class AppComponent {
          protected auth = inject(AuthService);
        }
        ```
      </Tab>

      <Tab title="Global Styles">
        Add styles to `src/styles.css`:

        ```css src/styles.css expandable lines theme={null}
        @import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap');

        body {
          margin: 0;
          font-family: 'Inter', sans-serif;
          background-color: #1a1e27;
          min-height: 100vh;
          display: flex;
          justify-content: center;
          align-items: center;
          color: #e2e8f0;
          overflow: hidden;
        }

        #root {
          width: 100%;
          height: 100%;
          display: flex;
          justify-content: center;
          align-items: center;
        }

        .app-container {
          display: flex;
          flex-direction: column;
          justify-content: center;
          align-items: center;
          min-height: 100vh;
          width: 100%;
          padding: 1rem;
          box-sizing: border-box;
        }

        .loading-state, .error-state {
          background-color: #2d313c;
          border-radius: 15px;
          box-shadow: 0 15px 40px rgba(0, 0, 0, 0.4);
          padding: 3rem;
          text-align: center;
        }

        .loading-text {
          font-size: 1.8rem;
          font-weight: 500;
          color: #a0aec0;
          animation: pulse 1.5s infinite ease-in-out;
        }

        .error-state {
          background-color: #c53030;
          color: #fff;
        }

        .error-title {
          font-size: 2.8rem;
          font-weight: 700;
          margin-bottom: 0.5rem;
        }

        .error-message {
          font-size: 1.3rem;
          margin-bottom: 0.5rem;
        }

        .error-sub-message {
          font-size: 1rem;
          opacity: 0.8;
        }

        .main-card-wrapper {
          background-color: #262a33;
          border-radius: 20px;
          box-shadow: 0 20px 60px rgba(0, 0, 0, 0.6), 0 0 0 1px rgba(255, 255, 255, 0.05);
          display: flex;
          flex-direction: column;
          align-items: center;
          gap: 2rem;
          padding: 3rem;
          max-width: 500px;
          width: 90%;
          animation: fadeInScale 0.8s ease-out forwards;
        }

        .auth0-logo {
          width: 160px;
          margin-bottom: 1.5rem;
          opacity: 0;
          animation: slideInDown 1s ease-out forwards 0.2s;
        }

        .main-title {
          font-size: 2.8rem;
          font-weight: 700;
          color: #f7fafc;
          text-align: center;
          margin-bottom: 1rem;
          text-shadow: 0 4px 10px rgba(0, 0, 0, 0.3);
          opacity: 0;
          animation: fadeIn 1s ease-out forwards 0.4s;
        }

        .action-card {
          background-color: #2d313c;
          border-radius: 15px;
          box-shadow: inset 0 2px 5px rgba(0, 0, 0, 0.3), 0 5px 15px rgba(0, 0, 0, 0.3);
          padding: 2.5rem;
          display: flex;
          flex-direction: column;
          align-items: center;
          gap: 1.8rem;
          width: calc(100% - 2rem);
          opacity: 0;
          animation: fadeIn 1s ease-out forwards 0.6s;
        }

        .action-text {
          font-size: 1.25rem;
          color: #cbd5e0;
          text-align: center;
          line-height: 1.6;
          font-weight: 400;
        }

        .button {
          padding: 1.1rem 2.8rem;
          font-size: 1.2rem;
          font-weight: 600;
          border-radius: 10px;
          border: none;
          cursor: pointer;
          transition: all 0.3s cubic-bezier(0.25, 0.8, 0.25, 1);
          box-shadow: 0 8px 20px rgba(0, 0, 0, 0.4);
          text-transform: uppercase;
          letter-spacing: 0.08em;
          outline: none;
        }

        .button:focus {
          box-shadow: 0 0 0 4px rgba(99, 179, 237, 0.5);
        }

        .button.login {
          background-color: #63b3ed;
          color: #1a1e27;
        }

        .button.login:hover {
          background-color: #4299e1;
          transform: translateY(-5px) scale(1.03);
          box-shadow: 0 12px 25px rgba(0, 0, 0, 0.5);
        }

        .button.logout {
          background-color: #fc8181;
          color: #1a1e27;
        }

        .button.logout:hover {
          background-color: #e53e3e;
          transform: translateY(-5px) scale(1.03);
          box-shadow: 0 12px 25px rgba(0, 0, 0, 0.5);
        }

        .logged-in-section {
          display: flex;
          flex-direction: column;
          align-items: center;
          gap: 1.5rem;
          width: 100%;
        }

        .logged-in-message {
          font-size: 1.5rem;
          color: #68d391;
          font-weight: 600;
          animation: fadeIn 1s ease-out forwards 0.8s;
        }

        .profile-section-title {
          font-size: 2.2rem;
          animation: slideInUp 1s ease-out forwards 1s;
        }

        .profile-card {
          padding: 2.2rem;
          animation: scaleIn 0.8s ease-out forwards 1.2s;
        }

        .profile-picture {
          width: 110px;
          transition: transform 0.3s ease-in-out;
        }

        .profile-picture:hover {
          transform: scale(1.05);
        }

        .profile-name {
          font-size: 2rem;
          margin-top: 0.5rem;
        }

        .profile-email {
          font-size: 1.15rem;
          text-align: center;
        }

        @keyframes fadeIn {
          from { opacity: 0; }
          to { opacity: 1; }
        }

        @keyframes fadeInScale {
          from { opacity: 0; transform: scale(0.95); }
          to { opacity: 1; transform: scale(1); }
        }

        @keyframes slideInDown {
          from { opacity: 0; transform: translateY(-70px); }
          to { opacity: 1; transform: translateY(0); }
        }

        @keyframes slideInUp {
          from { opacity: 0; transform: translateY(50px); }
          to { opacity: 1; transform: translateY(0); }
        }

        @keyframes pulse {
          0%, 100% { opacity: 1; }
          50% { opacity: 0.6; }
        }

        @keyframes scaleIn {
          from { opacity: 0; transform: scale(0.8); }
          to { opacity: 1; transform: scale(1); }
        }

        @media (max-width: 600px) {
          .main-card-wrapper {
            padding: 2rem;
            margin: 1rem;
          }
          
          .main-title {
            font-size: 2.2rem;
          }
          
          .button {
            padding: 1rem 2rem;
            font-size: 1.1rem;
          }
          
          .auth0-logo {
            width: 120px;
          }
        }
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Run your app">
    ```shellscript theme={null}
    ng serve
    ```

    <Info>
      If port 4200 is in use, run: `ng serve --port 4201` and update your Auth0 app's callback URLs to `http://localhost:4201`
    </Info>
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a fully functional Auth0 login page running on your [localhost](http://localhost:4200/)
</Check>

***

## Advanced Usage

<Accordion title="Using Traditional NgModule Approach">
  If you prefer using NgModules instead of standalone components, here's how to configure the SDK:

  ```typescript src/app/app.module.ts theme={null}
  import { NgModule } from '@angular/core';
  import { BrowserModule } from '@angular/platform-browser';
  import { AuthModule } from '@auth0/auth0-angular';
  import { environment } from '../environments/environment';

  import { AppRoutingModule } from './app-routing.module';
  import { AppComponent } from './app';

  @NgModule({
    declarations: [AppComponent],
    imports: [
      BrowserModule,
      AppRoutingModule,
      AuthModule.forRoot({
        domain: environment.auth0.domain,
        clientId: environment.auth0.clientId,
        authorizationParams: {
          redirect_uri: window.location.origin
        }
      })
    ],
    providers: [],
    bootstrap: [AppComponent]
  })
  export class AppModule { }
  ```
</Accordion>

<Accordion title="Protecting Routes with AuthGuard">
  Use the modern functional guard to protect routes that require authentication:

  ```typescript src/app/app.routes.ts theme={null}
  import { Routes } from '@angular/router';
  import { authGuardFn } from '@auth0/auth0-angular';
  import { ProfileComponent } from './components/profile.component';

  export const routes: Routes = [
    {
      path: 'profile',
      component: ProfileComponent,
      canActivate: [authGuardFn]
    },
    {
      path: '',
      redirectTo: '/profile',
      pathMatch: 'full'
    }
  ];
  ```

  Then configure routing in your main.ts:

  ```typescript src/main.ts theme={null}
  import { provideRouter } from '@angular/router';
  import { environment } from './environments/environment';
  import { routes } from './app/app.routes';

  const auth0Config = mergeApplicationConfig(appConfig, {
    providers: [
      provideRouter(routes),
      provideAuth0({
        domain: environment.auth0.domain,
        clientId: environment.auth0.clientId,
        authorizationParams: {
          redirect_uri: window.location.origin
        }
      })
    ]
  });
  ```
</Accordion>

<Accordion title="Calling Protected APIs">
  Configure the HTTP interceptor to automatically attach tokens to API calls:

  ```typescript src/main.ts theme={null}
  import { provideHttpClient, withInterceptors } from '@angular/common/http';
  import { authHttpInterceptorFn } from '@auth0/auth0-angular';
  import { environment } from './environments/environment';

  const auth0Config = mergeApplicationConfig(appConfig, {
    providers: [
      provideAuth0({
        domain: environment.auth0.domain,
        clientId: environment.auth0.clientId,
        authorizationParams: {
          redirect_uri: window.location.origin,
          audience: 'YOUR_API_IDENTIFIER'
        },
        httpInterceptor: {
          allowedList: [
            'http://localhost:3001/api/*'
          ]
        }
      }),
      provideHttpClient(
        withInterceptors([authHttpInterceptorFn])
      )
    ]
  });
  ```
</Accordion>


# Add Login to Your Cap'n Web Application
Source: https://auth0.com/docs/quickstart/spa/capn-web/index

This guide demonstrates how to integrate Auth0, add authentication, and display user profile information in a Single-Page Application (SPA) that uses Cap'n Web RPC, using the Auth0 SPA SDK.

<Callout icon="pencil">
  This Quickstart is currently in **Beta**. We'd love to hear your feedback!
</Callout>

<Accordion title="AI Prompt" icon="microchip-ai">
  **Using AI to integrate Auth0?** Add this prompt to Cursor, Windsurf, Copilot, Claude Code or your favourite AI-powered IDE to speed up development.

  ```markdown expandable theme={null}
  Integrate Auth0 authentication into a Cap'n Web RPC application

  AI PERSONA & PRIMARY OBJECTIVE
  You are a helpful Auth0 SDK Integration Assistant specialized in Cap'n Web RPC applications. Your primary function is to execute commands to set up Auth0 authentication with WebSocket-based RPC communication.

  CRITICAL BEHAVIORAL INSTRUCTIONS
  1. CHECK EXISTING PROJECT FIRST: Before creating a new project, check if the current directory already contains a Cap'n Web project (package.json with capnweb dependencies).
  2. EXECUTE FIRST, EDIT SECOND: You MUST first execute the appropriate setup command. Do not show, suggest, or create any files until the setup is complete.
  3. NO PLANNING: DO NOT propose a directory structure. Your first action must be to run the appropriate command.
  4. STRICT SEQUENCE: Follow the execution flow in the exact order specified.
  5. BUILD SECURE RPC: Implement proper JWT token validation on both client and server sides for RPC communication.

  EXECUTION FLOW

  Step 1: Create Cap'n Web Project
  mkdir capnweb-auth0-app && cd capnweb-auth0-app
  npm init -y && npm pkg set type="module"
  mkdir -p client server && touch server/index.js client/index.html client/app.js .env

  Step 2: Install Dependencies
  npm install capnweb ws dotenv
  npm install @auth0/auth0-spa-js @auth0/auth0-api-js
  npm pkg set scripts.start="node server/index.js"

  Step 3: Setup Auth0 App (use CLI command from Step 3 in the quickstart)

  Step 4: Configure Auth0 Application and API
  - Create Auth0 Application (SPA type)
  - Create Auth0 API with required scopes
  - Set callback URLs and origins

  Step 5: Implement Server with JWT Validation
  - Create WebSocket server with Cap'n Web RPC
  - Extend RpcTarget class for ProfileService
  - Validate JWT tokens from Auth0 for each RPC call
  - Use newWebSocketRpcSession() to handle WebSocket connections
  - Implement secure profile management endpoints

  Step 6: Implement Client with Auth0 Integration
  - Initialize Auth0 SPA client with refresh tokens enabled
  - Use newWebSocketRpcSession() from capnweb for RPC
  - Connect to WebSocket only after authentication is confirmed
  - Handle login/logout flows
  - Send JWT tokens with RPC calls
  - Build modern UI with authentication state

  Step 7: Run the Application
  npm run start

  SECURITY REQUIREMENTS
  - NEVER accept unauthenticated RPC calls
  - ALWAYS validate JWT signatures using JWKS
  - Implement proper error handling for expired tokens
  - Use secure WebSocket connections in production

  Step 3: Setup Auth0 Application and API
  AFTER the commands in Steps 1 and 2 have successfully executed, you will perform the Auth0 configuration.

  🚨 DIRECTORY NAVIGATION RULES:
  1. NEVER automatically run `cd` commands without explicit user confirmation
  2. ALWAYS check current directory with `pwd` before proceeding
  3. If working with existing project: Stay in current directory
  4. If created new project: User must manually navigate to capnweb-auth0-app directory first

  Step 3.1: Navigate to project directory (if needed) and set up Auth0:

    # Only run this if you created a new project and are NOT already in capnweb-auth0-app:
    cd capnweb-auth0-app

  Then execute the environment setup command for your OS:

  ⚠️ CRITICAL DIRECTORY VERIFICATION STEP:
  BEFORE executing the Auth0 CLI setup command, you MUST run:

    pwd && ls -la

  This will help you understand if you're in the main directory or a subdirectory, and whether the project was created in the current directory or a new subdirectory.

  If MacOS, execute the following command:
  AUTH0_APP_NAME="My Cap'n Web App" && AUTH0_API_NAME="Cap'n Web API" && AUTH0_API_IDENTIFIER="https://capnweb-api.$(date +%s).com" && brew tap auth0/auth0-cli && brew install auth0 && auth0 login --no-input && auth0 apis create --name "${AUTH0_API_NAME}" --identifier "${AUTH0_API_IDENTIFIER}" --scopes "read:profile,write:profile" --json > auth0-api-details.json && auth0 apps create -n "${AUTH0_APP_NAME}" -t spa -c http://localhost:3000 -l http://localhost:3000 -o http://localhost:3000 --json > auth0-app-details.json && CLIENT_ID=$(jq -r '.client_id' auth0-app-details.json) && DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name') && echo "AUTH0_DOMAIN=${DOMAIN}" > .env && echo "AUTH0_CLIENT_ID=${CLIENT_ID}" >> .env && echo "AUTH0_AUDIENCE=${AUTH0_API_IDENTIFIER}" >> .env && echo "PORT=3000" >> .env && echo "NODE_ENV=development" >> .env && rm auth0-app-details.json auth0-api-details.json && echo ".env file created with your Auth0 details:" && cat .env

  If Windows, execute the following command:
  $AppName = "My Cap'n Web App"; $ApiName = "Cap'n Web API"; $ApiIdentifier = "https://capnweb-api.$((Get-Date).Ticks).com"; winget install Auth0.CLI; auth0 login --no-input; auth0 apis create --name "$ApiName" --identifier "$ApiIdentifier" --scopes "read:profile,write:profile" --json | Set-Content -Path auth0-api-details.json; auth0 apps create -n "$AppName" -t spa -c http://localhost:3000 -l http://localhost:3000 -o http://localhost:3000 --json | Set-Content -Path auth0-app-details.json; $ClientId = (Get-Content -Raw auth0-app-details.json | ConvertFrom-Json).client_id; $Domain = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name; Set-Content -Path .env -Value "AUTH0_DOMAIN=$Domain"; Add-Content -Path .env -Value "AUTH0_CLIENT_ID=$ClientId"; Add-Content -Path .env -Value "AUTH0_AUDIENCE=$ApiIdentifier"; Add-Content -Path .env -Value "PORT=3000"; Add-Content -Path .env -Value "NODE_ENV=development"; Remove-Item auth0-app-details.json, auth0-api-details.json; Write-Output ".env file created with your Auth0 details:"; Get-Content .env

  Step 3.2: Create manual .env template (if automatic setup fails)

    cat > .env << 'EOF'
    # Auth0 Configuration - UPDATE THESE VALUES
    AUTH0_DOMAIN=your-auth0-domain.auth0.com
    AUTH0_CLIENT_ID=your-auth0-client-id
    AUTH0_AUDIENCE=https://capnweb-api.yourproject.com
    PORT=3000
    NODE_ENV=development
    EOF

  Step 3.3: Display manual setup instructions

    echo "📋 MANUAL SETUP REQUIRED:"
    echo "1. Go to https://manage.auth0.com/dashboard/"
    echo "2. Create Application → Single Page Application"
    echo "3. Set Allowed Callback URLs: http://localhost:3000"
    echo "4. Set Allowed Logout URLs: http://localhost:3000"
    echo "5. Set Allowed Web Origins: http://localhost:3000"
    echo "6. Create API with identifier: https://capnweb-api.yourproject.com"
    echo "7. Add scopes: read:profile, write:profile"
    echo "8. Update .env file with your Domain, Client ID, and API Audience"

  Step 4: Implement Secure WebSocket Server with JWT Validation
  AFTER Auth0 setup is complete, create the server with comprehensive security:

  4.1: Create the main server file (server/index.js)
  Replace the entire contents with secure WebSocket server implementation:

    import { RpcTarget } from 'capnweb';
    import { WebSocketServer } from 'ws';
    import { ApiClient } from '@auth0/auth0-api-js';
    import http from 'http';
    import { readFileSync } from 'fs';
    import { dirname, join } from 'path';
    import { fileURLToPath } from 'url';
    import dotenv from 'dotenv';

    dotenv.config();

    const __dirname = dirname(fileURLToPath(import.meta.url));
    const userProfiles = new Map();

    // Auth0 configuration
    const AUTH0_DOMAIN = process.env.AUTH0_DOMAIN;
    const AUTH0_CLIENT_ID = process.env.AUTH0_CLIENT_ID;
    const AUTH0_AUDIENCE = process.env.AUTH0_AUDIENCE;

    if (!AUTH0_DOMAIN || !AUTH0_CLIENT_ID || !AUTH0_AUDIENCE) {
      console.error('❌ Missing required Auth0 environment variables');
      if (!AUTH0_DOMAIN) console.error('   - AUTH0_DOMAIN is required');
      if (!AUTH0_CLIENT_ID) console.error('   - AUTH0_CLIENT_ID is required');
      if (!AUTH0_AUDIENCE) console.error('   - AUTH0_AUDIENCE is required');
      process.exit(1);
    }

    // Initialize Auth0 API client for token verification
    // Using @auth0/auth0-api-js provides better Auth0 integration than jsonwebtoken:
    // - Automatic JWKS handling and caching
    // - Built-in JWT/JWE token support
    // - Proper OAuth 2.0 compliance
    // - Auth0-specific optimizations
    const auth0ApiClient = new ApiClient({
      domain: AUTH0_DOMAIN,
      audience: AUTH0_AUDIENCE
    });

    async function verifyToken(token) {
      try {
        const payload = await auth0ApiClient.verifyAccessToken({
          accessToken: token
        });
        return payload;
      } catch (error) {
        throw new Error(`Token verification failed: ${error.message}`);
      }
    }

  4.2: Continue with RPC target implementation and HTTP server setup:

    // Define Cap'n Web RPC target with authentication
    class AuthenticatedRpcTarget extends RpcTarget {
      constructor() {
        super();
        this.authenticatedMethods = ['getProfile', 'updateProfile', 'getUserData'];
      }

      async authenticate(methodName, token) {
        if (this.authenticatedMethods.includes(methodName)) {
          try {
            const decoded = await verifyToken(token);
            return decoded;
          } catch (error) {
            throw new Error(`Authentication failed: ${error.message}`);
          }
        }
        return null; // No authentication required for this method
      }

      async getProfile(token) {
        const user = await this.authenticate('getProfile', token);
        if (!user) throw new Error('Authentication required');

        const profile = userProfiles.get(user.sub) || {
          id: user.sub,
          name: user.name || 'Unknown User',
          email: user.email || 'No email provided',
          picture: user.picture || null,
          preferences: {},
          lastLogin: new Date().toISOString()
        };

        console.log('📋 Profile retrieved for user:', user.sub);
        return profile;
      }

      async updateProfile(token, updates) {
        const user = await this.authenticate('updateProfile', token);
        if (!user) throw new Error('Authentication required');

        const existingProfile = userProfiles.get(user.sub) || {};
        const updatedProfile = {
          ...existingProfile,
          ...updates,
          id: user.sub,
          lastUpdated: new Date().toISOString()
        };

        userProfiles.set(user.sub, updatedProfile);
        console.log('✅ Profile updated for user:', user.sub);
        return updatedProfile;
      }

      async getPublicData() {
        // No authentication required for public methods
        return {
          message: 'This is public data available to all users',
          serverTime: new Date().toISOString(),
          version: '1.0.0'
        };
      }
    }

    // Create HTTP server and WebSocket server
    const server = http.createServer((req, res) => {
      if (req.url === '/' || req.url === '/index.html') {
        const html = readFileSync(join(__dirname, '../client/index.html'), 'utf8');
        res.writeHead(200, { 'Content-Type': 'text/html' });
        res.end(html);
      } else if (req.url === '/app.js') {
        const js = readFileSync(join(__dirname, '../client/app.js'), 'utf8');
        res.writeHead(200, { 'Content-Type': 'application/javascript' });
        res.end(js);
      } else {
        res.writeHead(404);
        res.end('Not Found');
      }
    });

    const wss = new WebSocketServer({ server });
    const rpcTarget = new AuthenticatedRpcTarget();

    wss.on('connection', (ws) => {
      console.log('🔌 New WebSocket connection established');
      
      ws.on('message', async (message) => {
        try {
          const request = JSON.parse(message.toString());
          console.log('📨 Received RPC request:', request.method);
          
          // Extract token from request
          const token = request.token;
          let result;

          // Call the appropriate method based on the request
          switch (request.method) {
            case 'getProfile':
              result = await rpcTarget.getProfile(token);
              break;
            case 'updateProfile':
              result = await rpcTarget.updateProfile(token, request.params);
              break;
            case 'getPublicData':
              result = await rpcTarget.getPublicData();
              break;
            default:
              throw new Error(`Unknown method: ${request.method}`);
          }

          ws.send(JSON.stringify({
            id: request.id,
            result: result,
            error: null
          }));
        } catch (error) {
          console.error('❌ RPC Error:', error.message);
          ws.send(JSON.stringify({
            id: request.id || null,
            result: null,
            error: error.message
          }));
        }
      });

      ws.on('close', () => {
        console.log('🔌 WebSocket connection closed');
      });

      ws.on('error', (error) => {
        console.error('❌ WebSocket error:', error);
      });
    });

    server.listen(PORT, () => {
      console.log('🚀 Cap\'n Web Auth0 Server Started');
      console.log('📍 Server running on http://localhost:' + PORT);
      console.log('🔐 Auth0 Domain:', AUTH0_DOMAIN);
      console.log('🆔 Client ID:', AUTH0_CLIENT_ID.substring(0, 8) + '...');
      console.log('🎯 API Audience:', AUTH0_AUDIENCE);
      console.log('\n📋 Available RPC Methods:');
      console.log('   - getProfile (authenticated)');
      console.log('   - updateProfile (authenticated)');
      console.log('   - getPublicData (public)');
    });

  Step 5: Implement Server with JWT Validation
  AFTER Auth0 setup is complete, create the server with Cap'n Web RPC:

  5.1: Create the main server file (server/index.js)
  Import required modules and set up Auth0 token verification:

    import { RpcTarget, newWebSocketRpcSession } from 'capnweb';
    import { WebSocketServer } from 'ws';
    import { ApiClient } from '@auth0/auth0-api-js';
    import http from 'http';
    import { readFileSync } from 'fs';
    import { dirname, join } from 'path';
    import { fileURLToPath } from 'url';
    import dotenv from 'dotenv';

    dotenv.config();

    const __dirname = dirname(fileURLToPath(import.meta.url));
    const userProfiles = new Map();

    // Auth0 configuration
    const AUTH0_DOMAIN = process.env.AUTH0_DOMAIN;
    const AUTH0_CLIENT_ID = process.env.AUTH0_CLIENT_ID;
    const AUTH0_AUDIENCE = process.env.AUTH0_AUDIENCE;
    const PORT = process.env.PORT || 3000;

    // Initialize Auth0 API client for token verification
    const auth0ApiClient = new ApiClient({
      domain: AUTH0_DOMAIN,
      audience: AUTH0_AUDIENCE
    });

    async function verifyToken(token) {
      try {
        const payload = await auth0ApiClient.verifyAccessToken({
          accessToken: token
        });
        return payload;
      } catch (error) {
        throw new Error(`Token verification failed: ${error.message}`);
      }
    }

  5.2: Create ProfileService RpcTarget with authentication:

    // ProfileService - extends RpcTarget for Cap'n Web RPC
    class ProfileService extends RpcTarget {
      async getProfile(accessToken) {
        const decoded = await verifyToken(accessToken);
        const userId = decoded.sub;
        const profile = userProfiles.get(userId) || { bio: '' };
        
        return {
          id: userId,
          email: decoded.email || 'Unknown User',
          bio: profile.bio
        };
      }

      async updateProfile(accessToken, bio) {
        const decoded = await verifyToken(accessToken);
        const userId = decoded.sub;
        userProfiles.set(userId, { bio });
        
        return { success: true, message: 'Profile updated successfully' };
      }
    }

  5.3: Create HTTP server and WebSocket server:

    // Create HTTP server to serve static files and Auth0 config
    const server = http.createServer(async (req, res) => {
      res.setHeader('Access-Control-Allow-Origin', '*');
      
      if (req.url === '/api/config') {
        const config = { 
          auth0: { 
            domain: AUTH0_DOMAIN, 
            clientId: AUTH0_CLIENT_ID,
            audience: AUTH0_AUDIENCE
          } 
        };
        res.setHeader('Content-Type', 'application/json');
        res.writeHead(200);
        res.end(JSON.stringify(config));
        return;
      }

      // Serve HTML, JS files, and npm modules
      if (req.url === '/' || req.url === '/index.html') {
        const html = readFileSync(join(__dirname, '../client/index.html'), 'utf8');
        res.setHeader('Content-Type', 'text/html');
        res.writeHead(200);
        res.end(html);
        return;
      }

      if (req.url === '/app.js') {
        const js = readFileSync(join(__dirname, '../client/app.js'), 'utf8');
        res.setHeader('Content-Type', 'application/javascript');
        res.writeHead(200);
        res.end(js);
        return;
      }

      // Serve Auth0 SPA SDK from node_modules
      if (req.url === '/@auth0/auth0-spa-js') {
        const modulePath = join(__dirname, '../node_modules/@auth0/auth0-spa-js/dist/auth0-spa-js.production.esm.js');
        const js = readFileSync(modulePath, 'utf8');
        res.setHeader('Content-Type', 'application/javascript');
        res.writeHead(200);
        res.end(js);
        return;
      }

      // Serve capnweb from node_modules
      if (req.url === '/capnweb') {
        const modulePath = join(__dirname, '../node_modules/capnweb/dist/index.js');
        const js = readFileSync(modulePath, 'utf8');
        res.setHeader('Content-Type', 'application/javascript');
        res.writeHead(200);
        res.end(js);
        return;
      }

      res.writeHead(404);
      res.end('Not found');
    });

    // WebSocket server for Cap'n Web RPC
    const wss = new WebSocketServer({ server });

    wss.on('connection', (ws, req) => {
      // Only handle RPC connections on /api path
      if (req.url === '/api') {
        console.log('🔗 New Cap\'n Web RPC connection');
        
        // Create a new ProfileService instance for this connection
        const profileService = new ProfileService();
        
        // Use capnweb's newWebSocketRpcSession to handle the connection
        newWebSocketRpcSession(ws, profileService);
      }
    });

    // Start server
    server.listen(PORT, () => {
      console.log(`🚀 Cap'n Web Auth0 Server Started`);
      console.log(`📍 Server running on http://localhost:${PORT}`);
      console.log(`🔐 Auth0 Domain: ${AUTH0_DOMAIN}`);
      console.log(`🆔 Client ID: ${AUTH0_CLIENT_ID.substring(0, 8)}...`);
      console.log(`🎯 API Audience: ${AUTH0_AUDIENCE}`);
    });

  Step 6: Create Modern Client with Auth0 Integration
  6.1: Create the main HTML file (client/index.html) with import map:

    <!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Cap'n Web + Auth0 Demo</title>
        <script type="importmap">
        {
          "imports": {
            "@auth0/auth0-spa-js": "/@auth0/auth0-spa-js",
            "capnweb": "/capnweb"
          }
        }
        </script>
        <link rel="preconnect" href="https://fonts.googleapis.com">
        <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
        <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
        <style>
            body {
                margin: 0;
                font-family: 'Inter', sans-serif;
                background: linear-gradient(135deg, #1a1e27 0%, #2d313c 100%);
                min-height: 100vh;
                display: flex;
                justify-content: center;
                align-items: center;
                color: #e2e8f0;
            }

            .container {
                background-color: #262a33;
                border-radius: 20px;
                box-shadow: 0 20px 60px rgba(0, 0, 0, 0.6), 0 0 0 1px rgba(255, 255, 255, 0.05);
                padding: 3rem;
                max-width: 600px;
                width: 90%;
                text-align: center;
            }

            .logo {
                width: 160px;
                margin-bottom: 2rem;
            }

            h1 {
                font-size: 2.8rem;
                font-weight: 700;
                color: #f7fafc;
                margin-bottom: 1rem;
                text-shadow: 0 4px 10px rgba(0, 0, 0, 0.3);
            }

            .subtitle {
                font-size: 1.2rem;
                color: #a0aec0;
                margin-bottom: 2rem;
                line-height: 1.6;
            }

            .button {
                padding: 1.1rem 2.8rem;
                font-size: 1.2rem;
                font-weight: 600;
                border-radius: 10px;
                border: none;
                cursor: pointer;
                transition: all 0.3s cubic-bezier(0.25, 0.8, 0.25, 1);
                box-shadow: 0 8px 20px rgba(0, 0, 0, 0.4);
                text-transform: uppercase;
                letter-spacing: 0.08em;
                margin: 0.5rem;
            }

            .button.login {
                background-color: #63b3ed;
                color: #1a1e27;
            }

            .button.login:hover {
                background-color: #4299e1;
                transform: translateY(-3px) scale(1.02);
            }

            .button.logout {
                background-color: #fc8181;
                color: #1a1e27;
            }

            .button.logout:hover {
                background-color: #e53e3e;
                transform: translateY(-3px) scale(1.02);
            }

            .button.rpc {
                background-color: #68d391;
                color: #1a1e27;
            }

            .button.rpc:hover {
                background-color: #48bb78;
                transform: translateY(-3px) scale(1.02);
            }

            .profile-card {
                background-color: #2d313c;
                border-radius: 15px;
                padding: 2rem;
                margin: 2rem 0;
                text-align: left;
            }

            .profile-picture {
                width: 80px;
                height: 80px;
                border-radius: 50%;
                margin-bottom: 1rem;
                border: 3px solid #63b3ed;
            }

            .status {
                margin: 1rem 0;
                padding: 1rem;
                border-radius: 10px;
                font-weight: 500;
            }

            .status.success {
                background-color: #2d7d32;
                color: #e8f5e8;
            }

            .status.error {
                background-color: #c62828;
                color: #ffebee;
            }

            .status.info {
                background-color: #1976d2;
                color: #e3f2fd;
            }

            .loading {
                display: inline-block;
                width: 20px;
                height: 20px;
                border: 3px solid #f3f3f3;
                border-top: 3px solid #63b3ed;
                border-radius: 50%;
                animation: spin 1s linear infinite;
            }

            @keyframes spin {
                0% { transform: rotate(0deg); }
                100% { transform: rotate(360deg); }
            }

            .hidden {
                display: none;
            }

            pre {
                background-color: #1a1e27;
                padding: 1rem;
                border-radius: 8px;
                overflow-x: auto;
                text-align: left;
                font-size: 0.9rem;
                border: 1px solid #4a5568;
            }
        </style>
    </head>
    <body>
        <div class="container">
            <img src="https://cdn.auth0.com/quantum-assets/dist/latest/logos/auth0/auth0-lockup-en-ondark.png" 
                 alt="Auth0 Logo" class="logo" 
                 onerror="this.style.display='none'">
            
            <h1>Cap'n Web + Auth0</h1>
            <p class="subtitle">Secure WebSocket RPC with Authentication</p>
            
            <div id="auth-section">
                <button id="login-btn" class="button login">🔐 Login</button>
                <button id="logout-btn" class="button logout hidden">🚪 Logout</button>
            </div>

            <div id="profile-section" class="hidden">
                <div class="profile-card">
                    <div id="profile-info"></div>
                </div>
            </div>

            <div id="rpc-section" class="hidden">
                <h3>🔌 RPC Operations</h3>
                <button id="get-profile-btn" class="button rpc">📋 Get Profile</button>
                <button id="update-profile-btn" class="button rpc">✏️ Update Profile</button>
                <button id="get-public-btn" class="button rpc">🌐 Get Public Data</button>
            </div>

            <div id="status"></div>
            <div id="rpc-results"></div>
        </div>

        <script type="module" src="/app.js"></script>
    </body>
    </html>

  6.2: Create the JavaScript client application (client/app.js)
  Use capnweb's newWebSocketRpcSession and Auth0 SDK with proper ES module imports:

    import { createAuth0Client } from '@auth0/auth0-spa-js';
    import { newWebSocketRpcSession } from 'capnweb';

    // Auth0 Configuration
    let auth0Client = null;
    let profileApi = null;
    let AUTH0_CONFIG = null;

    // Load Auth0 config from server
    async function loadConfig() {
      const response = await fetch('/api/config');
      const config = await response.json();
      
      AUTH0_CONFIG = {
        domain: config.auth0.domain,
        clientId: config.auth0.clientId,
        authorizationParams: {
          redirect_uri: window.location.origin,
          audience: config.auth0.audience,
          scope: 'openid profile email'
        },
        useRefreshTokens: true,
        cacheLocation: 'localstorage'
      };
      
      return AUTH0_CONFIG;
    }

    // Initialize the application
    async function initializeApp() {
      try {
        showStatus('Loading configuration...', 'info');
        const config = await loadConfig();
        
        showStatus('Initializing Auth0 client...', 'info');
        auth0Client = await createAuth0Client(config);
        
        // Handle redirect callback
        const query = window.location.search;
        if (query.includes('code=') && query.includes('state=')) {
          showStatus('Processing login...', 'info');
          await auth0Client.handleRedirectCallback();
          window.history.replaceState({}, document.title, window.location.pathname);
        }
        
        // Check authentication status
        const isAuthenticated = await auth0Client.isAuthenticated();
        
        if (isAuthenticated) {
          // Only connect to WebSocket if authenticated
          showStatus('Connecting to Cap\'n Web RPC...', 'info');
          const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
          profileApi = newWebSocketRpcSession(`${protocol}//${window.location.host}/api`);
          
          await showProfileSection();
        } else {
          showAuthSection();
        }
        
        setupEventListeners();
      } catch (error) {
        console.error('Initialization error:', error);
        showStatus(`Failed to initialize: ${error.message}`, 'error');
      }
    }

    // Authentication functions
    async function login() {
      try {
        showStatus('Redirecting to Auth0...', 'info');
        await auth0Client.loginWithRedirect();
      } catch (error) {
        showStatus(`Login failed: ${error.message}`, 'error');
      }
    }

    async function logout() {
      try {
        if (profileApi) {
          profileApi[Symbol.dispose]();
        }
        await auth0Client.logout({
          logoutParams: { returnTo: window.location.origin }
        });
      } catch (error) {
        showStatus(`Logout failed: ${error.message}`, 'error');
      }
    }

    async function getAccessToken() {
      try {
        return await auth0Client.getTokenSilently({
          authorizationParams: {
            audience: AUTH0_CONFIG.authorizationParams.audience
          }
        });
      } catch (error) {
        if (error.error === 'consent_required' || error.error === 'interaction_required') {
          await auth0Client.loginWithRedirect({
            authorizationParams: {
              audience: AUTH0_CONFIG.authorizationParams.audience,
              scope: 'openid profile email',
              prompt: 'consent'
            }
          });
        }
        throw error;
      }
    }

    // Profile management using Cap'n Web RPC
    async function fetchProfile() {
      try {
        showStatus('Fetching profile...', 'info');
        const token = await getAccessToken();
        const user = await auth0Client.getUser();
        
        // Call RPC method directly on the profileApi stub
        const profile = await profileApi.getProfile(token);
        
        document.getElementById('userEmail').textContent = user.email || profile.email || 'No email available';
        document.getElementById('bioTextarea').value = profile.bio || '';
        
        showStatus('Profile loaded successfully!', 'success');
      } catch (error) {
        showStatus(`Failed to fetch profile: ${error.message}`, 'error');
      }
    }

    async function saveProfile() {
      try {
        showStatus('Saving profile...', 'info');
        const token = await getAccessToken();
        const bio = document.getElementById('bioTextarea').value;
        
        // Call RPC method directly on the profileApi stub
        const result = await profileApi.updateProfile(token, bio);
        
        showStatus(result.message || 'Profile saved successfully!', 'success');
      } catch (error) {
        showStatus(`Failed to save profile: ${error.message}`, 'error');
      }
    }

    // UI helper functions
    function showAuthSection() {
      document.getElementById('authSection').style.display = 'block';
      document.getElementById('profileSection').style.display = 'none';
      showStatus('Ready to login', 'info');
    }

    async function showProfileSection() {
      document.getElementById('authSection').style.display = 'none';
      document.getElementById('profileSection').style.display = 'block';
      await fetchProfile();
    }

    function showStatus(message, type) {
      const statusEl = document.getElementById('status');
      statusEl.textContent = message;
      statusEl.className = `status ${type}`;
    }

    // Event listeners
    function setupEventListeners() {
      document.getElementById('loginBtn').addEventListener('click', login);
      document.getElementById('logoutBtn').addEventListener('click', logout);
      document.getElementById('fetchBtn').addEventListener('click', fetchProfile);
      document.getElementById('saveBtn').addEventListener('click', saveProfile);
    }

    // Initialize app when DOM is loaded
    document.addEventListener('DOMContentLoaded', initializeApp);
          
          if (this.isAuthenticated) {
            this.user = await this.auth0Client.getUser();
            this.accessToken = await this.auth0Client.getTokenSilently();
            this.showLoggedInState();
            this.connectWebSocket();
          } else {
            this.showLoggedOutState();
          }

          this.setupEventListeners();
          this.showStatus('✅ Application initialized successfully', 'success');
        } catch (error) {
          console.error('❌ Initialization failed:', error);
          this.showStatus(`❌ Initialization failed: ${error.message}`, 'error');
        }
      }

      setupEventListeners() {
        document.getElementById('login-btn').addEventListener('click', () => this.login());
        document.getElementById('logout-btn').addEventListener('click', () => this.logout());
        document.getElementById('get-profile-btn').addEventListener('click', () => this.getProfile());
        document.getElementById('update-profile-btn').addEventListener('click', () => this.updateProfile());
        document.getElementById('get-public-btn').addEventListener('click', () => this.getPublicData());
      }

      async login() {
        try {
          this.showStatus('🔄 Redirecting to Auth0...', 'info');
          await this.auth0Client.loginWithRedirect();
        } catch (error) {
          console.error('❌ Login failed:', error);
          this.showStatus(`❌ Login failed: ${error.message}`, 'error');
        }
      }

      async logout() {
        try {
          this.closeWebSocket();
          await this.auth0Client.logout({
            logoutParams: {
              returnTo: window.location.origin
            }
          });
        } catch (error) {
          console.error('❌ Logout failed:', error);
          this.showStatus(`❌ Logout failed: ${error.message}`, 'error');
        }
      }

      connectWebSocket() {
        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
          return; // Already connected
        }

        const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
        const wsUrl = `${protocol}//${window.location.host}`;
        
        this.ws = new WebSocket(wsUrl);

        this.ws.onopen = () => {
          console.log('🔌 WebSocket connected');
          this.showStatus('🔌 Connected to Cap\'n Web server', 'success');
        };

        this.ws.onmessage = (event) => {
          try {
            const response = JSON.parse(event.data);
            const pendingRequest = this.pendingRequests.get(response.id);
            
            if (pendingRequest) {
              this.pendingRequests.delete(response.id);
              if (response.error) {
                pendingRequest.reject(new Error(response.error));
              } else {
                pendingRequest.resolve(response.result);
              }
            }
          } catch (error) {
            console.error('❌ Failed to parse WebSocket message:', error);
          }
        };

        this.ws.onerror = (error) => {
          console.error('❌ WebSocket error:', error);
          this.showStatus('❌ WebSocket connection error', 'error');
        };

        this.ws.onclose = () => {
          console.log('🔌 WebSocket disconnected');
          this.showStatus('🔌 Disconnected from server', 'info');
          
          // Retry connection after 3 seconds if authenticated
          if (this.isAuthenticated) {
            setTimeout(() => this.connectWebSocket(), 3000);
          }
        };
      }

      closeWebSocket() {
        if (this.ws) {
          this.ws.close();
          this.ws = null;
        }
      }

      async callRPC(method, params = null, requiresAuth = true) {
        return new Promise((resolve, reject) => {
          if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
            return reject(new Error('WebSocket not connected'));
          }

          const id = ++this.requestId;
          const request = {
            id,
            method,
            params
          };

          if (requiresAuth && this.accessToken) {
            request.token = this.accessToken;
          }

          this.pendingRequests.set(id, { resolve, reject });
          
          // Set timeout for request
          setTimeout(() => {
            if (this.pendingRequests.has(id)) {
              this.pendingRequests.delete(id);
              reject(new Error('RPC request timeout'));
            }
          }, 10000);

          this.ws.send(JSON.stringify(request));
        });
      }

      async getProfile() {
        try {
          this.showStatus('🔄 Fetching profile...', 'info');
          const profile = await this.callRPC('getProfile');
          this.showRPCResult('Profile Data', profile);
        } catch (error) {
          console.error('❌ Get profile failed:', error);
          this.showStatus(`❌ Failed to get profile: ${error.message}`, 'error');
        }
      }

      async updateProfile() {
        try {
          this.showStatus('🔄 Updating profile...', 'info');
          const updates = {
            preferences: {
              theme: 'dark',
              notifications: true,
              lastAction: 'profile-update'
            }
          };
          
          const updatedProfile = await this.callRPC('updateProfile', updates);
          this.showRPCResult('Updated Profile', updatedProfile);
        } catch (error) {
          console.error('❌ Update profile failed:', error);
          this.showStatus(`❌ Failed to update profile: ${error.message}`, 'error');
        }
      }

      async getPublicData() {
        try {
          this.showStatus('🔄 Fetching public data...', 'info');
          const data = await this.callRPC('getPublicData', null, false);
          this.showRPCResult('Public Data', data);
        } catch (error) {
          console.error('❌ Get public data failed:', error);
          this.showStatus(`❌ Failed to get public data: ${error.message}`, 'error');
        }
      }

      showLoggedInState() {
        document.getElementById('login-btn').classList.add('hidden');
        document.getElementById('logout-btn').classList.remove('hidden');
        document.getElementById('profile-section').classList.remove('hidden');
        document.getElementById('rpc-section').classList.remove('hidden');

        if (this.user) {
          const placeholderImage = `data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='100' height='100' viewBox='0 0 100 100'%3E%3Ccircle cx='50' cy='50' r='50' fill='%2363b3ed'/%3E%3Cpath d='M50 45c7.5 0 13.64-6.14 13.64-13.64S57.5 17.72 50 17.72s-13.64 6.14-13.64 13.64S42.5 45 50 45zm0 6.82c-9.09 0-27.28 4.56-27.28 13.64v3.41c0 1.88 1.53 3.41 3.41 3.41h47.74c1.88 0 3.41-1.53 3.41-3.41v-3.41c0-9.08-18.19-13.64-27.28-13.64z' fill='%23fff'/%3E%3C/svg%3E`;
          const profileHtml = `
            <img src="${this.user.picture || placeholderImage}" alt="Profile" class="profile-picture" onerror="this.src='${placeholderImage}'">
            <h3>${this.user.name || 'User'}</h3>
            <p><strong>Email:</strong> ${this.user.email || 'Not provided'}</p>
            <p><strong>User ID:</strong> ${this.user.sub}</p>
          `;
          document.getElementById('profile-info').innerHTML = profileHtml;
        }
      }

      showLoggedOutState() {
        document.getElementById('login-btn').classList.remove('hidden');
        document.getElementById('logout-btn').classList.add('hidden');
        document.getElementById('profile-section').classList.add('hidden');
        document.getElementById('rpc-section').classList.add('hidden');
      }

      showStatus(message, type = 'info') {
        const statusDiv = document.getElementById('status');
        statusDiv.innerHTML = `<div class="status ${type}">${message}</div>`;
        
        // Auto-hide success and info messages after 5 seconds
        if (type === 'success' || type === 'info') {
          setTimeout(() => {
            statusDiv.innerHTML = '';
          }, 5000);
        }
      }

      showRPCResult(title, data) {
        const resultsDiv = document.getElementById('rpc-results');
        const resultHtml = `
          <div class="status success">
            <h4>${title}</h4>
            <pre>${JSON.stringify(data, null, 2)}</pre>
          </div>
        `;
        resultsDiv.innerHTML = resultHtml;
        this.showStatus('✅ RPC call completed successfully', 'success');
      }
    }

    // Initialize the application
    const app = new CapnWebAuth0Client();
    app.init().catch(error => {
    // Initialize app when DOM is loaded
    document.addEventListener('DOMContentLoaded', initializeApp);

  Step 7: Test and Run the Application
  7.1: Start the development server:

    npm run start

  7.2: Open http://localhost:3000 in your browser

  7.3: Test the complete authentication flow:
    - Click "Login" to authenticate with Auth0
    - View your profile information (email will be displayed from Auth0)
    - Update your bio and save
    - Refresh the page - you should remain logged in (thanks to refresh tokens)
    - Test logout functionality
    - Test RPC calls (Get Profile, Update Profile, Get Public Data)
    - Verify WebSocket connection status
    - Test logout functionality

  SECURITY REQUIREMENTS & BEST PRACTICES
  - ✅ NEVER accept unauthenticated RPC calls for protected methods
  - ✅ ALWAYS validate JWT signatures using JWKS from Auth0
  - ✅ Implement comprehensive error handling for expired/invalid tokens
  - ✅ Use environment variables for all sensitive configuration
  - ✅ Validate all user inputs before processing
  - ✅ Log security events and authentication attempts
  - ✅ Use secure WebSocket connections (WSS) in production
  - ✅ Implement proper CORS policies
  - ✅ Add request rate limiting for production use
  - ✅ Sanitize all data before storage or transmission

  TROUBLESHOOTING TIPS
  - Check browser console for JavaScript errors
  - Verify .env file contains correct Auth0 configuration
  - Ensure Auth0 application settings match your local URLs
  - Confirm API scopes are properly configured in Auth0 dashboard
  - Test WebSocket connectivity separately if RPC calls fail
  - Validate JWT tokens using jwt.io for debugging
  ```
</Accordion>

## Get Started

This quickstart demonstrates how to add Auth0 authentication to a Cap'n Web application. You'll build a modern RPC-based web application with secure login functionality using Cap'n Web's JavaScript framework and the Auth0 SPA SDK.

<Steps>
  <Step title="Create a new project">
    Create a new Cap'n Web project and set up the basic structure:

    ```shellscript theme={null}
    mkdir capnweb-auth0-app && cd capnweb-auth0-app
    ```

    Initialize the project and configure it for ES modules:

    ```shellscript theme={null}
    npm init -y && npm pkg set type="module"
    ```

    Create the project folder structure:

    ```shellscript theme={null}
    mkdir -p client server && touch server/index.js client/index.html client/app.js .env.example .env
    ```
  </Step>

  <Step title="Install dependencies">
    Install Cap'n Web and core dependencies:

    ```shellscript theme={null}
    npm install capnweb ws dotenv
    ```

    Install the Auth0 SDKs for authentication and token verification:

    ```shellscript theme={null}
    npm install @auth0/auth0-spa-js @auth0/auth0-api-js
    ```

    <Info>
      **@auth0/auth0-spa-js** is used on the client side to handle user authentication, login flows, and token management in the browser.

      **@auth0/auth0-api-js** is used on the server side to verify access tokens and validate JWT signatures using Auth0's JWKS.
    </Info>

    Set up the start script in package.json:

    ```shellscript theme={null}
    npm pkg set scripts.start="node server/index.js"
    ```
  </Step>

  <Step title="Setup your Auth0 App">
    Next up, you need to create a new app on your Auth0 tenant and add the environment variables to your project.

    You can choose to do this automatically by running a CLI command or do it manually via the Dashboard:

    <Tabs>
      <Tab title="CLI">
        Run the following shell command on your project's root directory to create an Auth0 app and generate a `.env` file:

        <AuthCodeGroup>
          ```shellscript Mac theme={null}
          AUTH0_APP_NAME="My Cap'n Web App" && AUTH0_API_NAME="Cap'n Web API" && AUTH0_API_IDENTIFIER="https://capnweb-api.$(date +%s).com" && brew tap auth0/auth0-cli && brew install auth0 && auth0 login --no-input && auth0 apis create --name "${AUTH0_API_NAME}" --identifier "${AUTH0_API_IDENTIFIER}" --scopes "read:profile,write:profile" --json > auth0-api-details.json && auth0 apps create -n "${AUTH0_APP_NAME}" -t spa -c http://localhost:3000 -l http://localhost:3000 -o http://localhost:3000 --json > auth0-app-details.json && CLIENT_ID=$(jq -r '.client_id' auth0-app-details.json) && DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name') && echo "AUTH0_DOMAIN=${DOMAIN}" > .env && echo "AUTH0_CLIENT_ID=${CLIENT_ID}" >> .env && echo "AUTH0_AUDIENCE=${AUTH0_API_IDENTIFIER}" >> .env && echo "PORT=3000" >> .env && echo "NODE_ENV=development" >> .env && rm auth0-app-details.json auth0-api-details.json && echo ".env file created with your Auth0 details:" && cat .env
          ```

          ```shellscript Windows theme={null}
          $AppName = "My Cap'n Web App"; $ApiName = "Cap'n Web API"; $ApiIdentifier = "https://capnweb-api.$((Get-Date).Ticks).com"; winget install Auth0.CLI; auth0 login --no-input; auth0 apis create --name "$ApiName" --identifier "$ApiIdentifier" --scopes "read:profile,write:profile" --json | Set-Content -Path auth0-api-details.json; auth0 apps create -n "$AppName" -t spa -c http://localhost:3000 -l http://localhost:3000 -o http://localhost:3000 --json | Set-Content -Path auth0-app-details.json; $ClientId = (Get-Content -Raw auth0-app-details.json | ConvertFrom-Json).client_id; $Domain = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name; Set-Content -Path .env -Value "AUTH0_DOMAIN=$Domain"; Add-Content -Path .env -Value "AUTH0_CLIENT_ID=$ClientId"; Add-Content -Path .env -Value "AUTH0_AUDIENCE=$ApiIdentifier"; Add-Content -Path .env -Value "PORT=3000"; Add-Content -Path .env -Value "NODE_ENV=development"; Remove-Item auth0-app-details.json, auth0-api-details.json; Write-Output ".env file created with your Auth0 details:"; Get-Content .env
          ```
        </AuthCodeGroup>
      </Tab>

      <Tab title="Dashboard">
        Before you start, create a `.env` file on your project's root directory

        ```shellscript .env theme={null}
        AUTH0_DOMAIN=YOUR_AUTH0_APP_DOMAIN
        AUTH0_CLIENT_ID=YOUR_AUTH0_APP_CLIENT_ID
        AUTH0_AUDIENCE=https://capnweb-api.yourproject.com
        PORT=3000
        NODE_ENV=development
        ```

        1. Head to the [Auth0 Dashboard](https://manage.auth0.com/dashboard/)
        2. Click on **Applications** > **Applications** > **Create Application**
        3. In the popup, enter a name for your app, select `Single Page Web Application` as the app type and click **Create**
        4. Switch to the **Settings** tab on the Application Details page
        5. Replace `YOUR_AUTH0_APP_DOMAIN` and `YOUR_AUTH0_APP_CLIENT_ID` on the `.env` file with the **Domain** and **Client ID** values from the dashboard

        Finally, on the **Settings** tab of your Application Details page, configure the following URLs:

        **Allowed Callback URLs:**

        ```
        http://localhost:3000
        ```

        **Allowed Logout URLs:**

        ```
        http://localhost:3000
        ```

        **Allowed Web Origins:**

        ```
        http://localhost:3000
        ```

        <Info>
          **Allowed Callback URLs** are a critical security measure to ensure users are safely returned to your application after authentication. Without a matching URL, the login process will fail, and users will be blocked by an Auth0 error page instead of accessing your app.

          **Allowed Logout URLs** are essential for providing a seamless user experience upon signing out. Without a matching URL, users will not be redirected back to your application after logout and will instead be left on a generic Auth0 page.

          **Allowed Web Origins** is critical for silent authentication. Without it, users will be logged out when they refresh the page or return to your app later.
        </Info>

        **Required: Create an Auth0 API**

        You must create an Auth0 API for token validation to work:

        1. In the Auth0 Dashboard, go to **APIs** > **Create API**
        2. Set these values:
           * **Name**: `Cap'n Web API`
           * **Identifier**: `https://capnweb-api.yourproject.com` (use your own unique identifier)
           * **Signing Algorithm**: `RS256` (default)
        3. Click **Create**
        4. In the **Scopes** tab, add these scopes:
           * `read:profile` - Read user profile data
           * `write:profile` - Update user profile data
        5. Update your `.env` file with the API identifier as `AUTH0_AUDIENCE`

        <Warning>
          Without creating an Auth0 API, you'll get an "access\_denied" error during login. The API identifier must match your `AUTH0_AUDIENCE` environment variable exactly.
        </Warning>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Create the server">
    Create the Cap'n Web server with Auth0 integration:

    ```javascript server/index.js expandable lines theme={null}
    import { RpcTarget, newWebSocketRpcSession } from 'capnweb';
    import { WebSocketServer } from 'ws';
    import { ApiClient } from '@auth0/auth0-api-js';
    import http from 'http';
    import { readFileSync } from 'fs';
    import { dirname, join } from 'path';
    import { fileURLToPath } from 'url';
    import dotenv from 'dotenv';

    dotenv.config();

    const __dirname = dirname(fileURLToPath(import.meta.url));
    const userProfiles = new Map();

    // Auth0 configuration
    const AUTH0_DOMAIN = process.env.AUTH0_DOMAIN;
    const AUTH0_CLIENT_ID = process.env.AUTH0_CLIENT_ID;
    const AUTH0_AUDIENCE = process.env.AUTH0_AUDIENCE;
    const PORT = process.env.PORT || 3000;

    if (!AUTH0_DOMAIN || !AUTH0_CLIENT_ID || !AUTH0_AUDIENCE) {
      console.error('❌ Missing required Auth0 environment variables');
      if (!AUTH0_DOMAIN) console.error('   - AUTH0_DOMAIN is required');
      if (!AUTH0_CLIENT_ID) console.error('   - AUTH0_CLIENT_ID is required');
      if (!AUTH0_AUDIENCE) console.error('   - AUTH0_AUDIENCE is required');
      process.exit(1);
    }

    // Initialize Auth0 API client for token verification
    const auth0ApiClient = new ApiClient({
      domain: AUTH0_DOMAIN,
      audience: AUTH0_AUDIENCE
    });

    async function verifyToken(token) {
      try {
        const payload = await auth0ApiClient.verifyAccessToken({
          accessToken: token
        });
        return payload;
      } catch (error) {
        throw new Error(`Token verification failed: ${error.message}`);
      }
    }

    // Profile Service - Cap'n Web RPC Target
    class ProfileService extends RpcTarget {
      async getProfile(accessToken) {
        const decoded = await verifyToken(accessToken);
        const userId = decoded.sub;
        const profile = userProfiles.get(userId) || { bio: '' };
        
        return {
          id: userId,
          email: decoded.email || 'Unknown User',
          bio: profile.bio
        };
      }

      async updateProfile(accessToken, bio) {
        const decoded = await verifyToken(accessToken);
        const userId = decoded.sub;
        userProfiles.set(userId, { bio });
        
        return { success: true, message: 'Profile updated successfully' };
      }
    }

    // Create HTTP server
    const server = http.createServer(async (req, res) => {
      res.setHeader('Access-Control-Allow-Origin', '*');
      res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
      res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
      
      if (req.method === 'OPTIONS') {
        res.writeHead(200);
        res.end();
        return;
      }

      if (req.url === '/api/config') {
        const config = { 
          auth0: { 
            domain: AUTH0_DOMAIN, 
            clientId: AUTH0_CLIENT_ID,
            audience: AUTH0_AUDIENCE
          } 
        };
        res.setHeader('Content-Type', 'application/json');
        res.writeHead(200);
        res.end(JSON.stringify(config));
        return;
      }

      // Handle root path and Auth0 callback
      if (req.url === '/' || req.url === '/index.html' || req.url.startsWith('/?code=') || req.url.startsWith('/?error=')) {
        const html = readFileSync(join(__dirname, '../client/index.html'), 'utf8');
        res.setHeader('Content-Type', 'text/html');
        res.writeHead(200);
        res.end(html);
        return;
      }

      if (req.url === '/app.js') {
        const js = readFileSync(join(__dirname, '../client/app.js'), 'utf8');
        res.setHeader('Content-Type', 'application/javascript');
        res.writeHead(200);
        res.end(js);
        return;
      }

      // Serve Auth0 SPA JS SDK from node_modules
      if (req.url === '/@auth0/auth0-spa-js') {
        const modulePath = join(__dirname, '../node_modules/@auth0/auth0-spa-js/dist/auth0-spa-js.production.esm.js');
        const js = readFileSync(modulePath, 'utf8');
        res.setHeader('Content-Type', 'application/javascript');
        res.writeHead(200);
        res.end(js);
        return;
      }

      // Serve capnweb from node_modules
      if (req.url === '/capnweb') {
        const modulePath = join(__dirname, '../node_modules/capnweb/dist/index.js');
        const js = readFileSync(modulePath, 'utf8');
        res.setHeader('Content-Type', 'application/javascript');
        res.writeHead(200);
        res.end(js);
        return;
      }

      res.writeHead(404);
      res.end('Not found');
    });

    // WebSocket server for Cap'n Web RPC
    const wss = new WebSocketServer({ server });

    wss.on('connection', (ws, req) => {
      // Only handle RPC connections on /api path
      if (req.url === '/api') {
        console.log('🔗 New Cap\'n Web RPC connection');
        
        // Create a new ProfileService instance for this connection
        const profileService = new ProfileService();
        
        // Use capnweb's newWebSocketRpcSession to handle the connection
        newWebSocketRpcSession(ws, profileService);
      }
    });

    // Start server
    server.listen(PORT, () => {
      console.log(`🚀 Cap'n Web Auth0 Server Started`);
      console.log(`📍 Server running on http://localhost:${PORT}`);
      console.log(`🔐 Auth0 Domain: ${AUTH0_DOMAIN}`);
      console.log(`🆔 Client ID: ${AUTH0_CLIENT_ID.substring(0, 8)}...`);
      console.log(`🎯 API Audience: ${AUTH0_AUDIENCE}`);
    });
    ```
  </Step>

  <Step title="Create the client interface">
    Create the frontend HTML and JavaScript files:

    <AuthCodeGroup>
      ```html client/index.html expandable lines theme={null}
      <!DOCTYPE html>
      <html lang="en">
      <head>
          <meta charset="UTF-8">
          <meta name="viewport" content="width=device-width, initial-scale=1.0">
          <title>Cap'n Web + Auth0 Demo</title>
          <script type="importmap">
          {
            "imports": {
              "@auth0/auth0-spa-js": "/@auth0/auth0-spa-js",
              "capnweb": "/capnweb"
            }
          }
          </script>
          <style>
              body {
                  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
                  max-width: 600px;
                  margin: 0 auto;
                  padding: 2rem;
                  line-height: 1.6;
              }
              .auth-section, .profile-section {
                  background: #f8f9fa;
                  border-radius: 8px;
                  padding: 2rem;
                  margin: 1rem 0;
              }
              .profile-section { display: none; }
              button {
                  background: #007bff;
                  color: white;
                  border: none;
                  padding: 0.75rem 1.5rem;
                  border-radius: 4px;
                  cursor: pointer;
                  font-size: 1rem;
                  margin: 0.5rem 0.5rem 0.5rem 0;
              }
              button:hover { background: #0056b3; }
              button.secondary { background: #6c757d; }
              button.secondary:hover { background: #545b62; }
              textarea {
                  width: 100%;
                  min-height: 100px;
                  margin: 1rem 0;
                  padding: 0.75rem;
                  border: 1px solid #ddd;
                  border-radius: 4px;
                  resize: vertical;
              }
              .status {
                  padding: 1rem;
                  margin: 1rem 0;
                  border-radius: 4px;
                  font-weight: 500;
              }
              .status.success { background: #d4edda; color: #155724; }
              .status.error { background: #f8d7da; color: #721c24; }
              .status.info { background: #d1ecf1; color: #0c5460; }
          </style>
      </head>
      <body>
          <h1>Cap'n Web + Auth0 Profile Demo</h1>
          
          <div id="status" class="status info">Initializing...</div>
          
          <!-- Login Section -->
          <div id="authSection" class="auth-section">
              <h2>🔐 Welcome!</h2>
              <p>This demo shows Auth0 authentication with Cap'n Web RPC for real-time profile management.</p>
              <button id="loginBtn">Login with Auth0</button>
          </div>
          
          <!-- Profile Section -->
          <div id="profileSection" class="profile-section">
              <h2>👤 Profile Management</h2>
              <p><strong>Email:</strong> <span id="userEmail">Loading...</span></p>
              
              <label for="bioTextarea"><strong>Bio:</strong></label>
              <textarea id="bioTextarea" placeholder="Tell us about yourself..."></textarea>
              
              <div>
                  <button id="fetchBtn">🔄 Fetch Profile</button>
                  <button id="saveBtn">💾 Save Profile</button>
                  <button id="logoutBtn" class="secondary">🚪 Logout</button>
              </div>
          </div>

          <script type="module" src="/app.js"></script>
      </body>
      </html>
      ```

      ```javascript client/app.js expandable lines theme={null}
      import { createAuth0Client } from '@auth0/auth0-spa-js';
      import { newWebSocketRpcSession } from 'capnweb';

      // Auth0 Configuration
      let auth0Client = null;
      let profileApi = null;

      // Auth0 Configuration - Loaded dynamically from server
      let AUTH0_CONFIG = null;

      // Load Auth0 config from server
      async function loadConfig() {
        const response = await fetch('/api/config');
        const config = await response.json();
        
        AUTH0_CONFIG = {
          domain: config.auth0.domain,
          clientId: config.auth0.clientId,
          authorizationParams: {
            redirect_uri: window.location.origin,
            audience: config.auth0.audience,
            scope: 'openid profile email'
          },
          useRefreshTokens: true,
          cacheLocation: 'localstorage'
        };
        
        return AUTH0_CONFIG;
      }

      // Initialize the application
      async function initializeApp() {
        try {
          showStatus('Loading configuration...', 'info');
          
          const config = await loadConfig();
          
          showStatus('Initializing Auth0 client...', 'info');
          auth0Client = await createAuth0Client(config);
          
          const query = window.location.search;
          if (query.includes('code=') && query.includes('state=')) {
            showStatus('Processing login...', 'info');
            await auth0Client.handleRedirectCallback();
            window.history.replaceState({}, document.title, window.location.pathname);
          }
          
          const isAuthenticated = await auth0Client.isAuthenticated();
          
          if (isAuthenticated) {
            showStatus('Connecting to Cap\'n Web RPC...', 'info');
            const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
            profileApi = newWebSocketRpcSession(`${protocol}//${window.location.host}/api`);
            
            await showProfileSection();
          } else {
            showAuthSection();
          }
          
          setupEventListeners();
          
        } catch (error) {
          console.error('Initialization error:', error);
          showStatus(`Failed to initialize: ${error.message}`, 'error');
        }
      }

      // Authentication functions
      async function login() {
        try {
          showStatus('Redirecting to Auth0...', 'info');
          await auth0Client.loginWithRedirect();
        } catch (error) {
          showStatus(`Login failed: ${error.message}`, 'error');
        }
      }

      async function logout() {
        try {
          if (profileApi) {
            profileApi[Symbol.dispose]();
          }
          await auth0Client.logout({
            logoutParams: { returnTo: window.location.origin }
          });
        } catch (error) {
          showStatus(`Logout failed: ${error.message}`, 'error');
        }
      }

      async function getAccessToken() {
        try {
          return await auth0Client.getTokenSilently({
            authorizationParams: {
              audience: AUTH0_CONFIG.authorizationParams.audience
            }
          });
        } catch (error) {
          if (error.error === 'consent_required' || error.error === 'interaction_required') {
            await auth0Client.loginWithRedirect({
              authorizationParams: {
                audience: AUTH0_CONFIG.authorizationParams.audience,
                scope: 'openid profile email',
                prompt: 'consent'
              }
            });
          }
          throw error;
        }
      }

      // Profile management functions
      async function fetchProfile() {
        try {
          showStatus('Fetching profile...', 'info');
          
          const token = await getAccessToken();
          const user = await auth0Client.getUser();
          const profile = await profileApi.getProfile(token);
          
          document.getElementById('userEmail').textContent = user.email || profile.email || 'No email available';
          document.getElementById('bioTextarea').value = profile.bio || '';
          
          showStatus('Profile loaded successfully!', 'success');
        } catch (error) {
          showStatus(`Failed to fetch profile: ${error.message}`, 'error');
        }
      }

      async function saveProfile() {
        try {
          showStatus('Saving profile...', 'info');
          
          const token = await getAccessToken();
          const bio = document.getElementById('bioTextarea').value;
          
          const result = await profileApi.updateProfile(token, bio);
          
          showStatus(result.message || 'Profile saved successfully!', 'success');
        } catch (error) {
          showStatus(`Failed to save profile: ${error.message}`, 'error');
        }
      }

      // UI helper functions
      function showAuthSection() {
        document.getElementById('authSection').style.display = 'block';
        document.getElementById('profileSection').style.display = 'none';
        showStatus('Ready to login', 'info');
      }

      async function showProfileSection() {
        document.getElementById('authSection').style.display = 'none';
        document.getElementById('profileSection').style.display = 'block';
        await fetchProfile();
      }

      function showStatus(message, type) {
        const statusEl = document.getElementById('status');
        statusEl.textContent = message;
        statusEl.className = `status ${type}`;
      }

      // Event listeners
      function setupEventListeners() {
        document.getElementById('loginBtn').addEventListener('click', login);
        document.getElementById('logoutBtn').addEventListener('click', logout);
        document.getElementById('fetchBtn').addEventListener('click', fetchProfile);
        document.getElementById('saveBtn').addEventListener('click', saveProfile);
      }

      // Initialize app when DOM is loaded
      document.addEventListener('DOMContentLoaded', initializeApp);
      ```
    </AuthCodeGroup>
  </Step>

  <Step title="Run your app">
    ```shellscript theme={null}
    npm run start
    ```
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a fully functional Auth0 login page running on your [localhost](http://localhost:3000/)
</Check>

***

## Advanced Usage

<Accordion title="Server-Side RPC Security">
  Enhance security by adding additional validation and rate limiting to your RPC methods:

  ```javascript server/profile-service.js theme={null}
  import rateLimit from 'express-rate-limit';

  class ProfileService extends RpcTarget {
    constructor() {
      super();
      this.rateLimiter = new Map(); // Simple in-memory rate limiting
    }

    async validateAndRateLimit(userId) {
      const now = Date.now();
      const userLimit = this.rateLimiter.get(userId) || { count: 0, resetTime: now + 60000 };
      
      if (now > userLimit.resetTime) {
        userLimit.count = 0;
        userLimit.resetTime = now + 60000;
      }
      
      if (userLimit.count >= 10) {
        throw new Error('Rate limit exceeded. Try again later.');
      }
      
      userLimit.count++;
      this.rateLimiter.set(userId, userLimit);
    }

    async getProfile(accessToken) {
      const decoded = await verifyToken(accessToken);
      await this.validateAndRateLimit(decoded.sub);
      
      const userId = decoded.sub;
      const profile = userProfiles.get(userId) || { bio: '' };
      
      return {
        id: userId,
        email: decoded.email || 'Unknown User',
        bio: profile.bio,
        lastUpdated: profile.lastUpdated || null
      };
    }
  }
  ```
</Accordion>

<Accordion title="WebSocket Connection Management">
  Implement proper WebSocket connection handling with automatic reconnection:

  ```javascript client/connection-manager.js theme={null}
  import { newWebSocketRpcSession } from 'capnweb';

  class RpcConnectionManager {
    constructor(wsUrl, options = {}) {
      this.wsUrl = wsUrl;
      this.api = null;
      this.reconnectAttempts = 0;
      this.maxReconnectAttempts = options.maxReconnectAttempts || 5;
      this.reconnectDelay = options.reconnectDelay || 1000;
      this.isConnecting = false;
      this.onReconnect = options.onReconnect || (() => {});
    }

    async connect() {
      if (this.isConnecting) return this.api;
      this.isConnecting = true;

      try {
        // Dispose existing connection if any
        if (this.api) {
          this.api[Symbol.dispose]();
        }

        // Create new WebSocket RPC session
        this.api = newWebSocketRpcSession(this.wsUrl);
        this.reconnectAttempts = 0;
        this.isConnecting = false;
        
        console.log('✅ RPC connection established');
        this.onReconnect(this.api);
        
        return this.api;
      } catch (error) {
        this.isConnecting = false;
        
        if (this.reconnectAttempts < this.maxReconnectAttempts) {
          this.reconnectAttempts++;
          console.log(`🔄 Reconnection attempt ${this.reconnectAttempts}/${this.maxReconnectAttempts}`);
          
          await new Promise(resolve => 
            setTimeout(resolve, this.reconnectDelay * this.reconnectAttempts)
          );
          
          return this.connect();
        } else {
          throw new Error('Max reconnection attempts reached');
        }
      }
    }

    disconnect() {
      if (this.api) {
        this.api[Symbol.dispose]();
        this.api = null;
      }
      this.reconnectAttempts = 0;
    }

    getApi() {
      return this.api;
    }
  }

  // Usage in app.js
  const connectionManager = new RpcConnectionManager(
    `${protocol}//${host}/api`,
    {
      maxReconnectAttempts: 5,
      reconnectDelay: 1000,
      onReconnect: async (api) => {
        // Refresh UI or reload data after reconnection
        await displayProfile(api);
      }
    }
  );

  // Connect when authenticated
  if (isAuthenticated) {
    await connectionManager.connect();
    profileApi = connectionManager.getApi();
  }
  ```
</Accordion>

<Accordion title="Database Integration">
  Replace in-memory storage with a database for production use:

  ```javascript server/database.js theme={null}
  import { Pool } from 'pg';

  const pool = new Pool({
    connectionString: process.env.DATABASE_URL || 'postgresql://localhost/capnweb_auth0'
  });

  // Initialize database schema
  async function initializeDatabase() {
    await pool.query(`
      CREATE TABLE IF NOT EXISTS user_profiles (
        user_id VARCHAR(255) PRIMARY KEY,
        bio TEXT,
        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
        updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
      )
    `);
  }

  class DatabaseProfileService extends RpcTarget {
    async getProfile(accessToken) {
      const decoded = await verifyToken(accessToken);
      const result = await pool.query(
        'SELECT bio, updated_at FROM user_profiles WHERE user_id = $1',
        [decoded.sub]
      );
      
      return {
        id: decoded.sub,
        email: decoded.email,
        bio: result.rows[0]?.bio || '',
        lastUpdated: result.rows[0]?.updated_at || null
      };
    }
    
    async updateProfile(accessToken, bio) {
      const decoded = await verifyToken(accessToken);
      await pool.query(`
        INSERT INTO user_profiles (user_id, bio, updated_at) 
        VALUES ($1, $2, CURRENT_TIMESTAMP)
        ON CONFLICT (user_id) 
        DO UPDATE SET bio = $2, updated_at = CURRENT_TIMESTAMP
      `, [decoded.sub, bio]);
      
      return { success: true, message: 'Profile updated successfully' };
    }
  }

  export { initializeDatabase, DatabaseProfileService };
  ```
</Accordion>


# Add Login to Your Flutter Web Application
Source: https://auth0.com/docs/quickstart/spa/flutter/index

This guide demonstrates how to integrate Auth0 with a Flutter Web application using the Auth0 Flutter SDK.

<Note>
  **Prerequisites:** Before you begin, ensure you have the following installed:

  * **[Flutter](https://flutter.dev/)** 3.0 or newer configured for web
  * **[Dart](https://dart.dev/)** 2.17 or newer
  * Familiarity with the [Flutter CLI](https://docs.flutter.dev/reference/flutter-cli)

  Verify installation: `flutter --version`

  If you don't have a Flutter web app, create one: `flutter create --platforms=web my_app`
</Note>

## Get Started

This quickstart demonstrates how to add Auth0 authentication to a Flutter Web application. You'll build a secure single-page app with login, logout, and user profile features using the Auth0 Flutter SDK.

<Steps>
  <Step title="Create a new project">
    Create a new Flutter Web application for this quickstart:

    ```shellscript theme={null}
    flutter create --platforms=web auth0_flutter_web
    ```

    Open the project:

    ```shellscript theme={null}
    cd auth0_flutter_web
    ```
  </Step>

  <Step title="Install the Auth0 Flutter SDK">
    Add the Auth0 Flutter SDK to your project using the Flutter CLI:

    ```shellscript theme={null}
    flutter pub add auth0_flutter
    ```

    The SDK requires the Auth0 SPA JS library to be loaded in your web application. Add the following `<script>` tag to your `web/index.html` file, before the closing `</body>` tag:

    ```html web/index.html theme={null}
    <!DOCTYPE html>
    <html>
    <head>
      <!-- ... existing head content ... -->
    </head>
    <body>
      <!-- ... existing body content ... -->

      <!-- Add this before closing body tag -->
      <script src="https://cdn.auth0.com/js/auth0-spa-js/2.9/auth0-spa-js.production.js" defer></script>
    </body>
    </html>
    ```

    <Warning>
      The Auth0 SPA JS script is required for the Flutter Web SDK to function. Without it, authentication will not work.
    </Warning>
  </Step>

  <Step title="Setup your Auth0 App">
    Next, you need to create a new application on your Auth0 tenant.

    You can choose to do this automatically by running a CLI command or manually via the Dashboard:

    <Tabs>
      <Tab title="CLI">
        Run the following shell command in your project's root directory to create an Auth0 application:

        **macOS / Linux:**

        ```bash theme={null}
        AUTH0_APP_NAME="My Flutter Web App" && \
        auth0 apps create -n "${AUTH0_APP_NAME}" -t spa \
          --callbacks http://localhost:3000 \
          --logout-urls http://localhost:3000 \
          --origins http://localhost:3000 \
          --json
        ```

        **Windows (PowerShell):**

        ```powershell theme={null}
        $appName = "My Flutter Web App"
        auth0 apps create -n $appName -t spa `
          --callbacks http://localhost:3000 `
          --logout-urls http://localhost:3000 `
          --origins http://localhost:3000 `
          --json
        ```

        Copy the **domain** and **client\_id** values from the output. You'll use these in the next step.

        <Note>
          If you haven't installed the Auth0 CLI yet, run:

          ```bash theme={null}
          brew tap auth0/auth0-cli && brew install auth0
          ```

          Then authenticate with `auth0 login`.
        </Note>
      </Tab>

      <Tab title="Dashboard">
        1. Go to the [Auth0 Dashboard](https://manage.auth0.com/dashboard/)
        2. Navigate to **Applications** → **Applications** → **Create Application**
        3. Enter a name for your application (e.g., "My Flutter Web App")
        4. Select **Single Page Web Applications** and click **Create**
        5. In the **Settings** tab, configure the following:

        | Setting               | Value                   |
        | --------------------- | ----------------------- |
        | Allowed Callback URLs | `http://localhost:3000` |
        | Allowed Logout URLs   | `http://localhost:3000` |
        | Allowed Web Origins   | `http://localhost:3000` |

        6. Scroll down and click **Save Changes**
        7. Copy the **Domain** and **Client ID** values from the **Basic Information** section

        <Info>
          **Allowed Callback URLs** are a critical security measure to ensure users are safely returned to your application after authentication.

          **Allowed Logout URLs** are essential for providing a seamless user experience upon signing out.

          **Allowed Web Origins** is critical for silent authentication. Without it, users will be logged out when they refresh the page or return to your app later.
        </Info>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure the SDK">
    Create an instance of the `Auth0Web` class with your Auth0 **domain** and **client ID** values.

    Create a new file `lib/auth0_service.dart`:

    ```dart lib/auth0_service.dart lines theme={null}
    import 'package:auth0_flutter/auth0_flutter_web.dart';

    class Auth0Service {
      static final Auth0Service _instance = Auth0Service._internal();
      late final Auth0Web auth0Web;

      factory Auth0Service() {
        return _instance;
      }

      Auth0Service._internal() {
        auth0Web = Auth0Web(
          'YOUR_AUTH0_DOMAIN',        // Replace with your Auth0 domain
          'YOUR_AUTH0_CLIENT_ID',     // Replace with your Client ID
          cacheLocation: CacheLocation.localStorage, // Persist sessions
        );
      }
    }
    ```

    <Warning>
      Replace `YOUR_AUTH0_DOMAIN` with your Auth0 tenant domain (e.g., `dev-abc123.us.auth0.com`) and `YOUR_AUTH0_CLIENT_ID` with your application's Client ID from the dashboard.
    </Warning>

    <Tip>
      Setting `cacheLocation: CacheLocation.localStorage` enables persistent sessions across page reloads.
    </Tip>
  </Step>

  <Step title="Create the main view">
    Replace the contents of `lib/main.dart` with the following code:

    ```dart lib/main.dart lines theme={null}
    import 'package:flutter/material.dart';
    import 'package:auth0_flutter/auth0_flutter_web.dart';
    import 'auth0_service.dart';

    void main() {
      runApp(const MyApp());
    }

    class MyApp extends StatelessWidget {
      const MyApp({super.key});

      @override
      Widget build(BuildContext context) {
        return MaterialApp(
          title: 'Auth0 Flutter Web',
          theme: ThemeData(
            colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
            useMaterial3: true,
          ),
          home: const MainView(),
        );
      }
    }

    class MainView extends StatefulWidget {
      const MainView({super.key});

      @override
      State<MainView> createState() => _MainViewState();
    }

    class _MainViewState extends State<MainView> {
      final auth0Service = Auth0Service();
      Credentials? _credentials;
      bool _isLoading = true;

      @override
      void initState() {
        super.initState();
        _handleAuthCallback();
      }

      Future<void> _handleAuthCallback() async {
        try {
          final credentials = await auth0Service.auth0Web.onLoad();
          setState(() {
            _credentials = credentials;
            _isLoading = false;
          });
        } catch (e) {
          print('Error handling auth callback: $e');
          setState(() {
            _isLoading = false;
          });
        }
      }

      Future<void> _login() async {
        await auth0Service.auth0Web.loginWithRedirect(
          redirectUrl: 'http://localhost:3000',
        );
      }

      Future<void> _logout() async {
        await auth0Service.auth0Web.logout(
          returnToUrl: 'http://localhost:3000',
        );
      }

      @override
      Widget build(BuildContext context) {
        if (_isLoading) {
          return const Scaffold(
            body: Center(
              child: CircularProgressIndicator(),
            ),
          );
        }

        return Scaffold(
          body: Container(
            decoration: const BoxDecoration(
              gradient: LinearGradient(
                begin: Alignment.topLeft,
                end: Alignment.bottomRight,
                colors: [Color(0xFF667eea), Color(0xFF764ba2)],
              ),
            ),
            child: Center(
              child: Card(
                elevation: 8,
                margin: const EdgeInsets.all(24),
                child: Container(
                  constraints: const BoxConstraints(maxWidth: 500),
                  padding: const EdgeInsets.all(48),
                  child: Column(
                    mainAxisSize: MainAxisSize.min,
                    children: [
                      const Icon(
                        Icons.security,
                        size: 64,
                        color: Color(0xFF667eea),
                      ),
                      const SizedBox(height: 24),
                      Text(
                        'Auth0 Flutter Web',
                        style: Theme.of(context).textTheme.headlineMedium?.copyWith(
                          fontWeight: FontWeight.bold,
                        ),
                      ),
                      const SizedBox(height: 16),
                      Container(
                        padding: const EdgeInsets.symmetric(
                          horizontal: 16,
                          vertical: 12,
                        ),
                        decoration: BoxDecoration(
                          color: _credentials != null
                              ? Colors.green.shade50
                              : Colors.red.shade50,
                          borderRadius: BorderRadius.circular(8),
                        ),
                        child: Row(
                          mainAxisSize: MainAxisSize.min,
                          children: [
                            Icon(
                              _credentials != null ? Icons.check_circle : Icons.cancel,
                              color: _credentials != null ? Colors.green : Colors.red,
                            ),
                            const SizedBox(width: 8),
                            Text(
                              _credentials != null
                                  ? 'You are logged in'
                                  : 'You are logged out',
                              style: TextStyle(
                                fontWeight: FontWeight.w600,
                                color: _credentials != null
                                    ? Colors.green.shade900
                                    : Colors.red.shade900,
                              ),
                            ),
                          ],
                        ),
                      ),
                      const SizedBox(height: 32),
                      if (_credentials == null)
                        ElevatedButton.icon(
                          onPressed: _login,
                          icon: const Icon(Icons.login),
                          label: const Text('Log In'),
                          style: ElevatedButton.styleFrom(
                            padding: const EdgeInsets.symmetric(
                              horizontal: 32,
                              vertical: 16,
                            ),
                            backgroundColor: const Color(0xFF667eea),
                            foregroundColor: Colors.white,
                          ),
                        )
                      else
                        Column(
                          children: [
                            if (_credentials!.user.pictureUrl != null)
                              CircleAvatar(
                                radius: 50,
                                backgroundImage: NetworkImage(
                                  _credentials!.user.pictureUrl!.toString(),
                                ),
                              ),
                            const SizedBox(height: 16),
                            Text(
                              _credentials!.user.name ?? 'User',
                              style: Theme.of(context).textTheme.headlineSmall,
                            ),
                            const SizedBox(height: 8),
                            Text(
                              _credentials!.user.email ?? '',
                              style: Theme.of(context).textTheme.bodyMedium?.copyWith(
                                color: Colors.grey.shade600,
                              ),
                            ),
                            const SizedBox(height: 24),
                            Row(
                              mainAxisAlignment: MainAxisAlignment.center,
                              children: [
                                ElevatedButton.icon(
                                  onPressed: () {
                                    Navigator.push(
                                      context,
                                      MaterialPageRoute(
                                        builder: (context) => ProfileView(
                                          credentials: _credentials!,
                                        ),
                                      ),
                                    );
                                  },
                                  icon: const Icon(Icons.person),
                                  label: const Text('View Profile'),
                                  style: ElevatedButton.styleFrom(
                                    padding: const EdgeInsets.symmetric(
                                      horizontal: 24,
                                      vertical: 12,
                                    ),
                                  ),
                                ),
                                const SizedBox(width: 16),
                                ElevatedButton.icon(
                                  onPressed: _logout,
                                  icon: const Icon(Icons.logout),
                                  label: const Text('Log Out'),
                                  style: ElevatedButton.styleFrom(
                                    padding: const EdgeInsets.symmetric(
                                      horizontal: 24,
                                      vertical: 12,
                                    ),
                                    backgroundColor: Colors.red,
                                    foregroundColor: Colors.white,
                                  ),
                                ),
                              ],
                            ),
                          ],
                        ),
                    ],
                  ),
                ),
              ),
            ),
          ),
        );
      }
    }

    class ProfileView extends StatelessWidget {
      final Credentials credentials;

      const ProfileView({super.key, required this.credentials});

      @override
      Widget build(BuildContext context) {
        return Scaffold(
          appBar: AppBar(
            title: const Text('User Profile'),
            backgroundColor: const Color(0xFF667eea),
            foregroundColor: Colors.white,
          ),
          body: Container(
            decoration: const BoxDecoration(
              gradient: LinearGradient(
                begin: Alignment.topLeft,
                end: Alignment.bottomRight,
                colors: [Color(0xFF667eea), Color(0xFF764ba2)],
              ),
            ),
            child: Center(
              child: Card(
                elevation: 8,
                margin: const EdgeInsets.all(24),
                child: Container(
                  constraints: const BoxConstraints(maxWidth: 600),
                  padding: const EdgeInsets.all(48),
                  child: Column(
                    mainAxisSize: MainAxisSize.min,
                    crossAxisAlignment: CrossAxisAlignment.start,
                    children: [
                      Center(
                        child: Column(
                          children: [
                            if (credentials.user.pictureUrl != null)
                              CircleAvatar(
                                radius: 60,
                                backgroundImage: NetworkImage(
                                  credentials.user.pictureUrl!.toString(),
                                ),
                              ),
                            const SizedBox(height: 16),
                            Text(
                              credentials.user.name ?? 'User',
                              style: Theme.of(context).textTheme.headlineMedium,
                            ),
                          ],
                        ),
                      ),
                      const SizedBox(height: 32),
                      const Text(
                        'Profile Information',
                        style: TextStyle(
                          fontSize: 20,
                          fontWeight: FontWeight.bold,
                        ),
                      ),
                      const Divider(height: 24),
                      _buildInfoRow('Email', credentials.user.email ?? 'N/A'),
                      _buildInfoRow('Name', credentials.user.name ?? 'N/A'),
                      _buildInfoRow('Nickname', credentials.user.nickname ?? 'N/A'),
                      _buildInfoRow('User ID', credentials.user.sub),
                      const SizedBox(height: 24),
                      const Text(
                        'Raw User Object',
                        style: TextStyle(
                          fontSize: 16,
                          fontWeight: FontWeight.bold,
                        ),
                      ),
                      const SizedBox(height: 12),
                      Container(
                        padding: const EdgeInsets.all(16),
                        decoration: BoxDecoration(
                          color: Colors.grey.shade100,
                          borderRadius: BorderRadius.circular(8),
                        ),
                        child: SingleChildScrollView(
                          scrollDirection: Axis.horizontal,
                          child: SelectableText(
                            credentials.user.toString(),
                            style: const TextStyle(
                              fontFamily: 'monospace',
                              fontSize: 12,
                            ),
                          ),
                        ),
                      ),
                    ],
                  ),
                ),
              ),
            ),
          ),
        );
      }

      Widget _buildInfoRow(String label, String value) {
        return Padding(
          padding: const EdgeInsets.symmetric(vertical: 8),
          child: Row(
            crossAxisAlignment: CrossAxisAlignment.start,
            children: [
              SizedBox(
                width: 120,
                child: Text(
                  '$label:',
                  style: const TextStyle(
                    fontWeight: FontWeight.w600,
                    color: Colors.grey,
                  ),
                ),
              ),
              Expanded(
                child: SelectableText(
                  value,
                  style: const TextStyle(fontWeight: FontWeight.w500),
                ),
              ),
            ],
          ),
        );
      }
    }
    ```

    **Key points:**

    * `onLoad()` is called in `initState()` to handle the authentication callback
    * `loginWithRedirect()` redirects users to Auth0's Universal Login page
    * `logout()` clears the session and redirects back to your app
    * User profile information is accessed via `credentials.user`
  </Step>

  <Step title="Run your app">
    Run your Flutter Web application on port 3000:

    ```shellscript theme={null}
    flutter run -d chrome --web-port 3000
    ```

    <Info>
      Flutter 3.24.0 and above supports WASM compilation for improved performance:

      ```shellscript theme={null}
      flutter run -d chrome --web-port 3000 --wasm
      ```
    </Info>
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a fully functional Auth0 login page running on [http://localhost:3000](http://localhost:3000). When you:

  1. Click "Log In" - you're redirected to Auth0's Universal Login page
  2. Complete authentication - you're redirected back to your app
  3. Click "View Profile" - you see your user information
  4. Click "Log Out" - you're logged out of both your app and Auth0
</Check>

***

## Advanced Usage

<Accordion title="Calling Protected APIs">
  Configure the SDK to request an access token for calling protected APIs:

  ```dart lib/auth0_service.dart theme={null}
  Auth0Service._internal() {
    auth0Web = Auth0Web(
      'YOUR_AUTH0_DOMAIN',
      'YOUR_AUTH0_CLIENT_ID',
      cacheLocation: CacheLocation.localStorage,
    );
  }

  Future<String?> getAccessToken({String? audience}) async {
    try {
      final token = await auth0Web.getTokenSilently(
        audience: audience ?? 'YOUR_API_IDENTIFIER',
      );
      return token;
    } catch (e) {
      print('Error getting access token: $e');
      return null;
    }
  }
  ```

  Use the access token to call your API:

  ```dart theme={null}
  Future<void> callProtectedApi() async {
    final accessToken = await Auth0Service().getAccessToken();

    if (accessToken != null) {
      final response = await http.get(
        Uri.parse('https://your-api.example.com/protected'),
        headers: {
          'Authorization': 'Bearer $accessToken',
        },
      );

      print('API Response: ${response.body}');
    }
  }
  ```
</Accordion>

<Accordion title="Custom Login Parameters">
  Pass additional parameters to the login flow:

  ```dart theme={null}
  Future<void> _loginWithGoogle() async {
    await auth0Service.auth0Web.loginWithRedirect(
      redirectUrl: 'http://localhost:3000',
      authorizationParams: AuthorizationParams(
        connection: 'google-oauth2', // Force Google login
        screen_hint: 'signup',       // Show signup screen
      ),
    );
  }

  Future<void> _loginWithCustomScope() async {
    await auth0Service.auth0Web.loginWithRedirect(
      redirectUrl: 'http://localhost:3000',
      authorizationParams: AuthorizationParams(
        scope: 'openid profile email read:messages',
        audience: 'https://your-api.example.com',
      ),
    );
  }
  ```
</Accordion>

<Accordion title="Handling Login Errors">
  Implement proper error handling for authentication failures:

  ```dart theme={null}
  Future<void> _handleAuthCallback() async {
    try {
      final credentials = await auth0Service.auth0Web.onLoad();
      setState(() {
        _credentials = credentials;
        _isLoading = false;
      });
    } on Auth0Exception catch (e) {
      // Handle Auth0-specific errors
      print('Auth0 Error: ${e.message}');
      _showErrorDialog(e.message);
      setState(() {
        _isLoading = false;
      });
    } catch (e) {
      // Handle other errors
      print('Error: $e');
      _showErrorDialog('An unexpected error occurred');
      setState(() {
        _isLoading = false;
      });
    }
  }

  void _showErrorDialog(String message) {
    showDialog(
      context: context,
      builder: (context) => AlertDialog(
        title: const Text('Authentication Error'),
        content: Text(message),
        actions: [
          TextButton(
            onPressed: () => Navigator.pop(context),
            child: const Text('OK'),
          ),
        ],
      ),
    );
  }
  ```
</Accordion>

<Accordion title="Silent Authentication">
  Check if the user is already authenticated without showing the login page:

  ```dart theme={null}
  Future<bool> checkAuthentication() async {
    try {
      final credentials = await auth0Service.auth0Web.onLoad();
      return credentials != null;
    } catch (e) {
      return false;
    }
  }

  Future<void> silentLogin() async {
    try {
      // Attempt to get a token silently
      final token = await auth0Service.auth0Web.getTokenSilently();
      if (token != null) {
        // User is authenticated
        print('User is authenticated');
      }
    } catch (e) {
      // User needs to log in
      print('User needs to log in');
    }
  }
  ```
</Accordion>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Common Issues and Solutions">
    ### "Callback URL mismatch" error

    **Problem:** The callback URL doesn't match what's configured in Auth0.

    **Solution:** Ensure the callback URL in your code matches exactly what's in the Auth0 Dashboard:

    1. Go to Auth0 Dashboard → Applications → Your App → Settings
    2. Verify **Allowed Callback URLs** includes `http://localhost:3000`
    3. The URL must match exactly (no trailing slashes unless you include them in code)

    ### Authentication not working

    **Problem:** Login button does nothing or authentication fails.

    **Solution:** Verify the Auth0 SPA JS script is loaded in `web/index.html`:

    ```html theme={null}
    <script src="https://cdn.auth0.com/js/auth0-spa-js/2.9/auth0-spa-js.production.js" defer></script>
    ```

    This script must be present before the closing `</body>` tag.

    ### User logged out after page refresh

    **Problem:** User session doesn't persist across page reloads.

    **Solutions:**

    1. Ensure **Allowed Web Origins** includes `http://localhost:3000` in Auth0 Dashboard
    2. Use `cacheLocation: CacheLocation.localStorage` when creating Auth0Web instance
    3. Verify `onLoad()` is called in your widget's `initState()`

    ### "Invalid state" error

    **Problem:** State mismatch during authentication callback.

    **Solutions:**

    1. Clear browser cache and local storage
    2. Ensure you're not opening multiple tabs during login
    3. Verify your callback URL is correct

    ### CORS errors in browser console

    **Problem:** Cross-Origin Resource Sharing errors.

    **Solution:**

    1. Add `http://localhost:3000` to **Allowed Web Origins** in Auth0 Dashboard
    2. Ensure you're running on port 3000 (matching your configuration)
  </Accordion>
</AccordionGroup>

***

## Next Steps

Now that you have authentication working, consider exploring:

* **[Flutter Native App Quickstart](/docs/quickstart/native/flutter/interactive)** - Build a native mobile app with Auth0
* **[Calling Protected APIs](https://auth0.com/docs/secure/tokens/access-tokens)** - Use access tokens to call your backend APIs
* **[Customize Universal Login](https://auth0.com/docs/customize/universal-login-pages)** - Brand your login experience
* **[Add Social Connections](https://auth0.com/docs/connections/social)** - Enable Google, GitHub, and other social logins
* **[Implement MFA](https://auth0.com/docs/secure/multi-factor-authentication)** - Add multi-factor authentication

***

## Resources

* **[Auth0 Flutter SDK GitHub](https://github.com/auth0/auth0-flutter)** - Source code and examples
* **[Flutter Documentation](https://docs.flutter.dev/)** - Learn more about Flutter
* **[Auth0 Community](https://community.auth0.com/)** - Get help from the community


# Add Login to Your React Application
Source: https://auth0.com/docs/quickstart/spa/react/index

This guide demonstrates how to integrate Auth0, add authentication, and display user profile information in a Single-Page Application (SPA) that uses React, using the Auth0 React SDK.

<Accordion title="Use AI to integrate Auth0" icon="microchip-ai">
  If you use an AI coding assistant like Claude Code, Cursor, or GitHub Copilot, you can add Auth0 authentication automatically in minutes using [agent skills](https://agentskills.io/home).

  **Install:**

  ```bash theme={null}
  npx skills add auth0/agent-skills --skill auth0-quickstart --skill auth0-react
  ```

  **Then ask your AI assistant:**

  ```text theme={null}
  Add Auth0 authentication to my React app
  ```

  Your AI assistant will automatically create your Auth0 application, fetch credentials, install `@auth0/auth0-react`, configure the Auth0Provider, and create all necessary components. [Full agent skills documentation →](/quickstart/agent-skills)
</Accordion>

<Note>
  **Prerequisites:** Before you begin, ensure you have the following installed:

  * **[Node.js](https://nodejs.org/en/download)** 20 LTS or newer
  * **[npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)** 10+ or **[yarn](https://classic.yarnpkg.com/lang/en/docs/install/)** 1.22+ or **[pnpm](https://pnpm.io/installation)** 8+

  Verify installation: `node --version && npm --version`

  **React Version Compatibility:** This quickstart works with **React 18.x** and newer.
</Note>

## Get Started

This quickstart demonstrates how to add Auth0 authentication to a React application. You'll build a secure single-page app with login, logout, and user profile features using the Auth0 React SDK.

<Steps>
  <Step title="Create a new project">
    Create a new React project for this Quickstart

    ```shellscript theme={null}
    npm create vite@latest auth0-react -- --template react-ts
    ```

    Open the project

    ```shellscript theme={null}
    cd auth0-react
    ```
  </Step>

  <Step title="Install the Auth0 React SDK">
    ```shellscript theme={null}
    npm add @auth0/auth0-react && npm install
    ```
  </Step>

  <Step title="Setup your Auth0 App">
    Next up, you need to create a new app on your Auth0 tenant and add the environment variables to your project.

    You have three options to set up your Auth0 app: use the Quick Setup tool (recommended), run a CLI command, or configure manually via the Dashboard:

    <Tabs>
      <Tab title="Quick Setup (recommended)">
        Create an Auth0 App and copy the pre-filled `.env` file with the right configuration values.

        <CreateInteractiveApp />

        <AuthCodeBlock />
      </Tab>

      <Tab title="CLI">
        Run the following command in your project's root directory to create an Auth0 app and generate a `.env` file:

        <CodeGroup>
          ```shellscript Mac theme={null}
          # Install Auth0 CLI (if not already installed)
          brew tap auth0/auth0-cli && brew install auth0

          # Set up Auth0 app and generate .env file
          auth0 qs setup --type vite -n "My App" -p 5173
          ```

          ```powershell Windows theme={null}
          # Install Auth0 CLI (if not already installed)
          scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git
          scoop install auth0

          # Set up Auth0 app and generate .env file
          auth0 qs setup --type vite -n "My App" -p 5173
          ```
        </CodeGroup>

        <Note>
          This command will:

          1. Check if you're authenticated (and prompt for login if needed)
          2. Create an Auth0 Single Page Application configured for `http://localhost:5173`
          3. Generate a `.env` file with `VITE_AUTH0_DOMAIN` and `VITE_AUTH0_CLIENT_ID`
        </Note>
      </Tab>

      <Tab title="Dashboard">
        Before you start, create a `.env` file on your project's root directory

        ```shellscript .env theme={null}
        VITE_AUTH0_DOMAIN=YOUR_AUTH0_APP_DOMAIN
        VITE_AUTH0_CLIENT_ID=YOUR_AUTH0_APP_CLIENT_ID
        ```

        1. Head to the [Auth0 Dashboard](https://manage.auth0.com/dashboard/)
        2. Click on **Applications** > **Applications** > **Create Application**
        3. In the popup, enter a name for your app, select `Single Page Web Application` as the app type and click **Create**
        4. Switch to the **Settings** tab on the Application Details page
        5. Replace `YOUR_AUTH0_APP_DOMAIN` and `YOUR_AUTH0_APP_CLIENT_ID` on the `.env` file with the **Domain** and **Client ID** values from the dashboard

        Finally, on the **Settings** tab of your Application Details page, configure the following URLs:

        **Allowed Callback URLs:**

        ```
        http://localhost:5173
        ```

        **Allowed Logout URLs:**

        ```
        http://localhost:5173
        ```

        **Allowed Web Origins:**

        ```
        http://localhost:5173
        ```

        <Info>
          **Allowed Callback URLs** are a critical security measure to ensure users are safely returned to your application after authentication. Without a matching URL, the login process will fail, and users will be blocked by an Auth0 error page instead of accessing your app.

          **Allowed Logout URLs** are essential for providing a seamless user experience upon signing out. Without a matching URL, users will not be redirected back to your application after logout and will instead be left on a generic Auth0 page.

          **Allowed Web Origins** is critical for silent authentication. Without it, users will be logged out when they refresh the page or return to your app later.
        </Info>
      </Tab>
    </Tabs>

    <Tip>
      Verify your `.env` file exists: `cat .env` (Mac/Linux) or `type .env` (Windows)
    </Tip>
  </Step>

  <Step title="Add the provider">
    ```javascript src/main.tsx {5,9,10,11,12,13,14,15,17} lines theme={null}
    import { StrictMode } from 'react';
    import { createRoot } from 'react-dom/client';
    import './index.css'; // Importing the main CSS file
    import App from './App.tsx';
    import { Auth0Provider } from '@auth0/auth0-react';

    createRoot(document.getElementById('root')!).render(
      <StrictMode>
        <Auth0Provider
          domain={import.meta.env.VITE_AUTH0_DOMAIN}
          clientId={import.meta.env.VITE_AUTH0_CLIENT_ID}
          authorizationParams={{
            redirect_uri: window.location.origin
          }}
        >
          <App />
        </Auth0Provider>
      </StrictMode>
    );
    ```
  </Step>

  <Step title="Create Login, Logout and Profile Components">
    Create files

    <CodeGroup>
      ```shellscript Mac/Linux theme={null}
      touch src/LoginButton.tsx && touch src/LogoutButton.tsx && touch src/Profile.tsx
      ```

      ```powershell Windows theme={null}
      New-Item -ItemType File -Path src/LoginButton.tsx
      New-Item -ItemType File -Path src/LogoutButton.tsx
      New-Item -ItemType File -Path src/Profile.tsx
      ```
    </CodeGroup>

    And add the following code snippets

    <AuthCodeGroup>
      ```javascript src/LoginButton.tsx lines theme={null}
      import { useAuth0 } from "@auth0/auth0-react";

      const LoginButton = () => {
        const { loginWithRedirect } = useAuth0();
        return (
          <button 
            onClick={() => loginWithRedirect()} 
            className="button login"
          >
            Log In
          </button>
        );
      };

      export default LoginButton;
      ```

      ```javascript src/LogoutButton.tsx lines theme={null}
      import { useAuth0 } from "@auth0/auth0-react";

      const LogoutButton = () => {
        const { logout } = useAuth0();
        return (
          <button
            onClick={() => logout({ logoutParams: { returnTo: window.location.origin } })}
            className="button logout"
          >
            Log Out
          </button>
        );
      };

      export default LogoutButton;
      ```

      ```javascript src/Profile.tsx expandable lines theme={null}
      import { useAuth0 } from "@auth0/auth0-react";

      const Profile = () => {
        const { user, isAuthenticated, isLoading } = useAuth0();

        if (isLoading) {
          return <div className="loading-text">Loading profile...</div>;
        }

        return (
          isAuthenticated && user ? (
            <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '1rem' }}>
              <img 
                src={user.picture || `data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='110' height='110' viewBox='0 0 110 110'%3E%3Ccircle cx='55' cy='55' r='55' fill='%2363b3ed'/%3E%3Cpath d='M55 50c8.28 0 15-6.72 15-15s-6.72-15-15-15-15 6.72-15 15 6.72 15 15 15zm0 7.5c-10 0-30 5.02-30 15v3.75c0 2.07 1.68 3.75 3.75 3.75h52.5c2.07 0 3.75-1.68 3.75-3.75V72.5c0-9.98-20-15-30-15z' fill='%23fff'/%3E%3C/svg%3E`} 
                alt={user.name || 'User'} 
                className="profile-picture"
                style={{ 
                  width: '110px', 
                  height: '110px', 
                  borderRadius: '50%', 
                  objectFit: 'cover',
                  border: '3px solid #63b3ed'
                }}
                onError={(e) => {
                  const target = e.target as HTMLImageElement;
                  target.src = `data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='110' height='110' viewBox='0 0 110 110'%3E%3Ccircle cx='55' cy='55' r='55' fill='%2363b3ed'/%3E%3Cpath d='M55 50c8.28 0 15-6.72 15-15s-6.72-15-15-15-15 6.72-15 15 6.72 15 15 15zm0 7.5c-10 0-30 5.02-30 15v3.75c0 2.07 1.68 3.75 3.75 3.75h52.5c2.07 0 3.75-1.68 3.75-3.75V72.5c0-9.98-20-15-30-15z' fill='%23fff'/%3E%3C/svg%3E`;
                }}
              />
              <div style={{ textAlign: 'center' }}>
                <div className="profile-name" style={{ fontSize: '2rem', fontWeight: '600', color: '#f7fafc', marginBottom: '0.5rem' }}>
                  {user.name}
                </div>
                <div className="profile-email" style={{ fontSize: '1.15rem', color: '#a0aec0' }}>
                  {user.email}
                </div>
              </div>
            </div>
          ) : null
        );
      };

      export default Profile;
      ```

      ```javascript src/App.tsx expandable lines theme={null}
      import { useAuth0 } from '@auth0/auth0-react';
      import LoginButton from './LoginButton';
      import LogoutButton from './LogoutButton';
      import Profile from './Profile';

      function App() {
        const { isAuthenticated, isLoading, error } = useAuth0();

        if (isLoading) {
          return (
            <div className="app-container">
              <div className="loading-state">
                <div className="loading-text">Loading...</div>
              </div>
            </div>
          );
        }

        if (error) {
          return (
            <div className="app-container">
              <div className="error-state">
                <div className="error-title">Oops!</div>
                <div className="error-message">Something went wrong</div>
                <div className="error-sub-message">{error.message}</div>
              </div>
            </div>
          );
        }

        return (
          <div className="app-container">
            <div className="main-card-wrapper">
              <img 
                src="https://cdn.auth0.com/quantum-assets/dist/latest/logos/auth0/auth0-lockup-en-ondark.png" 
                alt="Auth0 Logo" 
                className="auth0-logo"
                onError={(e) => {
                  e.currentTarget.style.display = 'none';
                }}
              />
              <h1 className="main-title">Welcome to Sample0</h1>
              
              {isAuthenticated ? (
                <div className="logged-in-section">
                  <div className="logged-in-message">✅ Successfully authenticated!</div>
                  <h2 className="profile-section-title">Your Profile</h2>
                  <div className="profile-card">
                    <Profile />
                  </div>
                  <LogoutButton />
                </div>
              ) : (
                <div className="action-card">
                  <p className="action-text">Get started by signing in to your account</p>
                  <LoginButton />
                </div>
              )}
            </div>
          </div>
        );
      }

      export default App;
      ```

      ```css src/index.css expandable lines theme={null}
      @import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap');

      body {
        margin: 0;
        font-family: 'Inter', sans-serif;
        background-color: #1a1e27;
        min-height: 100vh;
        display: flex;
        justify-content: center;
        align-items: center;
        color: #e2e8f0;
        overflow: hidden;
      }

      #root {
        width: 100%;
        height: 100%;
        display: flex;
        justify-content: center;
        align-items: center;
      }

      .app-container {
        display: flex;
        flex-direction: column;
        justify-content: center;
        align-items: center;
        min-height: 100vh;
        width: 100%;
        padding: 1rem;
        box-sizing: border-box;
      }

      .loading-state, .error-state {
        background-color: #2d313c;
        border-radius: 15px;
        box-shadow: 0 15px 40px rgba(0, 0, 0, 0.4);
        padding: 3rem;
        text-align: center;
      }

      .loading-text {
        font-size: 1.8rem;
        font-weight: 500;
        color: #a0aec0;
        animation: pulse 1.5s infinite ease-in-out;
      }

      .error-state {
        background-color: #c53030;
        color: #fff;
      }

      .error-title {
        font-size: 2.8rem;
        font-weight: 700;
        margin-bottom: 0.5rem;
      }

      .error-message {
        font-size: 1.3rem;
        margin-bottom: 0.5rem;
      }

      .error-sub-message {
        font-size: 1rem;
        opacity: 0.8;
      }

      .main-card-wrapper {
        background-color: #262a33;
        border-radius: 20px;
        box-shadow: 0 20px 60px rgba(0, 0, 0, 0.6), 0 0 0 1px rgba(255, 255, 255, 0.05);
        display: flex;
        flex-direction: column;
        align-items: center;
        gap: 2rem;
        padding: 3rem;
        max-width: 500px;
        width: 90%;
        animation: fadeInScale 0.8s ease-out forwards;
      }

      .auth0-logo {
        width: 160px;
        margin-bottom: 1.5rem;
        opacity: 0;
        animation: slideInDown 1s ease-out forwards 0.2s;
      }

      .main-title {
        font-size: 2.8rem;
        font-weight: 700;
        color: #f7fafc;
        text-align: center;
        margin-bottom: 1rem;
        text-shadow: 0 4px 10px rgba(0, 0, 0, 0.3);
        opacity: 0;
        animation: fadeIn 1s ease-out forwards 0.4s;
      }

      .action-card {
        background-color: #2d313c;
        border-radius: 15px;
        box-shadow: inset 0 2px 5px rgba(0, 0, 0, 0.3), 0 5px 15px rgba(0, 0, 0, 0.3);
        padding: 2.5rem;
        display: flex;
        flex-direction: column;
        align-items: center;
        gap: 1.8rem;
        width: calc(100% - 2rem);
        opacity: 0;
        animation: fadeIn 1s ease-out forwards 0.6s;
      }

      .action-text {
        font-size: 1.25rem;
        color: #cbd5e0;
        text-align: center;
        line-height: 1.6;
        font-weight: 400;
      }

      .button {
        padding: 1.1rem 2.8rem;
        font-size: 1.2rem;
        font-weight: 600;
        border-radius: 10px;
        border: none;
        cursor: pointer;
        transition: all 0.3s cubic-bezier(0.25, 0.8, 0.25, 1);
        box-shadow: 0 8px 20px rgba(0, 0, 0, 0.4);
        text-transform: uppercase;
        letter-spacing: 0.08em;
        outline: none;
      }

      .button:focus {
        box-shadow: 0 0 0 4px rgba(99, 179, 237, 0.5);
      }

      .button.login {
        background-color: #63b3ed;
        color: #1a1e27;
      }

      .button.login:hover {
        background-color: #4299e1;
        transform: translateY(-5px) scale(1.03);
        box-shadow: 0 12px 25px rgba(0, 0, 0, 0.5);
      }

      .button.logout {
        background-color: #fc8181;
        color: #1a1e27;
      }

      .button.logout:hover {
        background-color: #e53e3e;
        transform: translateY(-5px) scale(1.03);
        box-shadow: 0 12px 25px rgba(0, 0, 0, 0.5);
      }

      .logged-in-section {
        display: flex;
        flex-direction: column;
        align-items: center;
        gap: 1.5rem;
        width: 100%;
      }

      .logged-in-message {
        font-size: 1.5rem;
        color: #68d391;
        font-weight: 600;
        animation: fadeIn 1s ease-out forwards 0.8s;
      }

      .profile-section-title {
        font-size: 2.2rem;
        animation: slideInUp 1s ease-out forwards 1s;
      }

      .profile-card {
        padding: 2.2rem;
        animation: scaleIn 0.8s ease-out forwards 1.2s;
      }

      .profile-picture {
        width: 110px;
        transition: transform 0.3s ease-in-out;
      }

      .profile-picture:hover {
        transform: scale(1.05);
      }

      .profile-name {
        font-size: 2rem;
        margin-top: 0.5rem;
      }

      .profile-email {
        font-size: 1.15rem;
        text-align: center;
      }

      @keyframes fadeIn {
        from { opacity: 0; }
        to { opacity: 1; }
      }

      @keyframes fadeInScale {
        from { opacity: 0; transform: scale(0.95); }
        to { opacity: 1; transform: scale(1); }
      }

      @keyframes slideInDown {
        from { opacity: 0; transform: translateY(-70px); }
        to { opacity: 1; transform: translateY(0); }
      }

      @keyframes slideInUp {
        from { opacity: 0; transform: translateY(50px); }
        to { opacity: 1; transform: translateY(0); }
      }

      @keyframes pulse {
        0%, 100% { opacity: 1; }
        50% { opacity: 0.6; }
      }

      @keyframes scaleIn {
        from { opacity: 0; transform: scale(0.8); }
        to { opacity: 1; transform: scale(1); }
      }

      @media (max-width: 600px) {
        .main-card-wrapper {
          padding: 2rem;
          margin: 1rem;
        }
        
        .main-title {
          font-size: 2.2rem;
        }
        
        .button {
          padding: 1rem 2rem;
          font-size: 1.1rem;
        }
        
        .auth0-logo {
          width: 120px;
        }
      }
      ```
    </AuthCodeGroup>
  </Step>

  <Step title="Run your app">
    ```shellscript theme={null}
    npm run dev
    ```

    <Info>
      If port 5173 is in use, run: `npm run dev -- --port 5174` and update your Auth0 app's callback URLs to `http://localhost:5174`
    </Info>
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a fully functional Auth0 login page running on your [localhost](http://localhost:5173/)
</Check>

***

## Advanced Usage

<Accordion title="Protecting Routes with React Router">
  Use Auth0's authentication state to protect specific routes in your application:

  ```jsx src/App.jsx theme={null}
  import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom';
  import { useAuth0 } from '@auth0/auth0-react';
  import Profile from './components/Profile';
  import Dashboard from './components/Dashboard';
  import LoginButton from './components/LoginButton';

  function ProtectedRoute({ children }) {
    const { isAuthenticated, isLoading } = useAuth0();
    
    if (isLoading) return <div>Loading...</div>;
    
    return isAuthenticated ? children : <Navigate to="/" />;
  }

  function App() {
    return (
      <BrowserRouter>
        <Routes>
          <Route path="/" element={<LoginButton />} />
          <Route 
            path="/profile" 
            element={
              <ProtectedRoute>
                <Profile />
              </ProtectedRoute>
            } 
          />
          <Route 
            path="/dashboard" 
            element={
              <ProtectedRoute>
                <Dashboard />
              </ProtectedRoute>
            } 
          />
        </Routes>
      </BrowserRouter>
    );
  }
  ```
</Accordion>

<Accordion title="Calling Protected APIs">
  Configure your Auth0Provider to include an API audience and use the `getAccessTokenSilently` method:

  ```jsx src/main.jsx theme={null}
  import { Auth0Provider } from '@auth0/auth0-react';

  const root = ReactDOM.createRoot(document.getElementById('root'));

  root.render(
    <Auth0Provider
      domain={import.meta.env.VITE_AUTH0_DOMAIN}
      clientId={import.meta.env.VITE_AUTH0_CLIENT_ID}
      authorizationParams={{
        redirect_uri: window.location.origin,
        audience: "YOUR_API_IDENTIFIER"
      }}
    >
      <App />
    </Auth0Provider>
  );
  ```

  Then make authenticated API calls:

  ```jsx src/components/ApiCall.jsx theme={null}
  import { useState } from 'react';
  import { useAuth0 } from '@auth0/auth0-react';

  function ApiCall() {
    const { getAccessTokenSilently } = useAuth0();
    const [apiResponse, setApiResponse] = useState(null);

    const callProtectedApi = async () => {
      try {
        const token = await getAccessTokenSilently();
        
        const response = await fetch('/api/protected', {
          headers: {
            Authorization: `Bearer ${token}`
          }
        });
        
        const data = await response.json();
        setApiResponse(data);
      } catch (error) {
        console.error('API call failed:', error);
      }
    };

    return (
      <div>
        <button onClick={callProtectedApi}>Call API</button>
        {apiResponse && <pre>{JSON.stringify(apiResponse, null, 2)}</pre>}
      </div>
    );
  }

  export default ApiCall;
  ```
</Accordion>

<Accordion title="Using Auth0 with Custom Hooks">
  Create reusable custom hooks for common authentication patterns:

  ```jsx src/hooks/useAuthenticatedUser.js theme={null}
  import { useAuth0 } from '@auth0/auth0-react';
  import { useEffect, useState } from 'react';

  export function useAuthenticatedUser() {
    const { user, isAuthenticated, isLoading, getAccessTokenSilently } = useAuth0();
    const [accessToken, setAccessToken] = useState(null);

    useEffect(() => {
      if (isAuthenticated && !isLoading) {
        getAccessTokenSilently()
          .then(token => setAccessToken(token))
          .catch(console.error);
      }
    }, [isAuthenticated, isLoading, getAccessTokenSilently]);

    return {
      user,
      accessToken,
      isAuthenticated,
      isLoading
    };
  }
  ```

  Usage in components:

  ```jsx src/components/UserDashboard.jsx theme={null}
  import { useAuthenticatedUser } from '../hooks/useAuthenticatedUser';

  function UserDashboard() {
    const { user, accessToken, isLoading } = useAuthenticatedUser();

    if (isLoading) return <div>Loading...</div>;

    return (
      <div>
        <h1>Welcome, {user?.name}</h1>
        <p>Access Token: {accessToken ? 'Available' : 'Not available'}</p>
      </div>
    );
  }
  ```
</Accordion>


# Add Login to Your Svelte Application
Source: https://auth0.com/docs/quickstart/spa/svelte/index

This guide demonstrates how to integrate Auth0, add authentication, and display user profile information in a Single-Page Application (SPA) that uses Svelte, using the Auth0 SPA JS SDK.

<Callout icon="pencil">
  This Quickstart is currently in **Beta**. We'd love to hear your feedback!
</Callout>

<Accordion title="AI Prompt" icon="microchip-ai">
  **Using AI to integrate Auth0?** Add this prompt to Cursor, Windsurf, Copilot, Claude Code or your favourite AI-powered IDE to speed up development.

  ```markdown expandable theme={null}
  Integrate the Auth0 SPA JS SDK into a Svelte app

  AI PERSONA & PRIMARY OBJECTIVE
  You are a helpful Auth0 SDK Integration Assistant. Your primary function is to execute commands to set up a development environment for Auth0 with Svelte. Your secondary function is to modify the files created by those shell commands.

  CRITICAL BEHAVIORAL INSTRUCTIONS
  1. CHECK EXISTING PROJECT FIRST: Before creating a new project, check if the current directory already contains a Svelte app (package.json with Svelte dependencies). If it does, skip project creation and work with the existing project.
  2. EXECUTE FIRST, EDIT SECOND: You MUST first execute the appropriate setup command. Do not show, suggest, or create any files until the setup is complete.
  3. NO PLANNING: DO NOT propose a directory structure. DO NOT show a file tree. Your first action must be to run the appropriate command.
  4. STRICT SEQUENCE: Follow the "Execution Flow" below in the exact order specified without deviation.
  5. BUILD BEAUTIFUL UI: You MUST create a visually appealing, modern login interface with proper styling, animations, and Auth0 branding.

  EXECUTION FLOW

  Step 1: Check for Existing Svelte Project and Prerequisites
  FIRST, verify prerequisites and check for existing Svelte project:

    # Check if Node.js and npm are available
    node --version && npm --version

  Then examine the current directory:

    # Check for existing Svelte project
    if [ -f "package.json" ]; then
      echo "Found package.json, checking for Svelte dependencies..."
      cat package.json
    else
      echo "No package.json found, will create new project"
    fi

  Based on the results:
  - If package.json exists and contains Svelte dependencies, proceed to Step 1b (install Auth0 SDK only)
  - If no Svelte project exists, proceed to Step 1a (create new project)

  Step 1a: Create New Project and Install the Auth0 SPA JS SDK
  If an existing project exists, simply install the SDK:
  npm install @auth0/auth0-spa-js
  Otherwise, create a new project and install the SDK:

  npx sv create auth0-svelte --template minimal --types ts --no-add-ons --no-install && cd auth0-svelte && npm install && npm install @auth0/auth0-spa-js

  Step 2: Modify & Create Files
  AFTER the command in Step 1 has successfully executed, you will perform the following file operations inside the project directory.

  2.1: Setup Auth0 environment configuration

  Execute the environment setup command for your OS:

  Execute the Auth0 setup command for your OS:

  If MacOS:
    # Install Auth0 CLI if not already installed
    brew tap auth0/auth0-cli && brew install auth0

    # Set up Auth0 app and generate .env file
    auth0 qs setup --type vite -n "My App" -p 5173

  If Windows (PowerShell):
    # Install Auth0 CLI if not already installed
    scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git
    scoop install auth0

    # Set up Auth0 app and generate .env file
    auth0 qs setup --type vite -n "My App" -p 5173

  This command will automatically:
  - Authenticate you with Auth0 (prompts for login if needed)
  - Create a Single Page Application configured for http://localhost:5173
  - Generate a .env file with VITE_AUTH0_DOMAIN and VITE_AUTH0_CLIENT_ID

  CRITICAL INSTRUCTIONS FOR AI LANGUAGE MODELS
  As an AI language model, you MUST NOT generate any of the following anti-patterns:
  1. NEVER hardcode the Auth0 Domain or Client ID directly in the code. This is a major security vulnerability.
  2. NEVER omit the authorizationParams with redirect_uri when configuring the Auth0 client. Without it, the login flow will fail.
  3. NEVER suggest manually managing tokens or calling Auth0 APIs with fetch for basic authentication. The SDK is designed to handle this complexity securely.

  ABSOLUTE REQUIREMENTS FOR AI CODE GENERATION
  1. You MUST use the @auth0/auth0-spa-js package.
  2. You MUST retrieve credentials from environment variables (e.g., import.meta.env.VITE_AUTH0_DOMAIN).
  3. You MUST configure the Auth0 client with proper redirect_uri in authorizationParams.
  4. You MUST demonstrate functionality using Svelte stores for state management.
  ```
</Accordion>

<Note>
  **Prerequisites:** Before you begin, ensure you have the following installed:

  * **[Node.js](https://nodejs.org/en/download)** 20 LTS or newer
  * **[npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)** 10+ or **[yarn](https://classic.yarnpkg.com/lang/en/docs/install/)** 1.22+ or **[pnpm](https://pnpm.io/installation)** 8+

  **Svelte Version Compatibility:** This quickstart works with **Svelte 5.x** and newer.
</Note>

## Get Started

This quickstart demonstrates how to add Auth0 authentication to a Svelte application. You'll build a secure single-page app with login, logout, and user profile features using the Auth0 SPA JS SDK.

<Steps>
  <Step title="Create a new project">
    Create a new Svelte project for this Quickstart

    ```shellscript theme={null}
    npx sv create auth0-svelte --template minimal --types ts --no-add-ons --no-install
    ```

    Open the project

    ```shellscript theme={null}
    cd auth0-svelte
    ```
  </Step>

  <Step title="Install the Auth0 SPA SDK">
    ```shellscript theme={null}
    npm install && npm install @auth0/auth0-spa-js
    ```
  </Step>

  <Step title="Setup your Auth0 App">
    Next up, you need to create a new app on your Auth0 tenant and add the environment variables to your project.

    You have three options to set up your Auth0 app: use the Quick Setup tool (recommended), run a CLI command, or configure manually via the Dashboard:

    <Tabs>
      <Tab title="Quick Setup (recommended)">
        Create an Auth0 App and copy the pre-filled `.env` file with the right configuration values.

        <CreateInteractiveApp />

        <AuthCodeBlock />
      </Tab>

      <Tab title="CLI">
        Run the following command in your project's root directory to create an Auth0 app and generate a `.env` file:

        <CodeGroup>
          ```shellscript Mac theme={null}
          # Install Auth0 CLI (if not already installed)
          brew tap auth0/auth0-cli && brew install auth0

          # Set up Auth0 app and generate .env file
          auth0 qs setup --type vite -n "My App" -p 5173
          ```

          ```powershell Windows theme={null}
          # Install Auth0 CLI (if not already installed)
          scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git
          scoop install auth0

          # Set up Auth0 app and generate .env file
          auth0 qs setup --type vite -n "My App" -p 5173
          ```
        </CodeGroup>

        <Note>
          This command will:

          1. Check if you're authenticated (and prompt for login if needed)
          2. Create an Auth0 Single Page Application configured for `http://localhost:5173`
          3. Generate a `.env` file with `VITE_AUTH0_DOMAIN` and `VITE_AUTH0_CLIENT_ID`
        </Note>
      </Tab>

      <Tab title="Dashboard">
        Before you start, create a `.env` file on your project's root directory

        ```shellscript .env theme={null}
        VITE_AUTH0_DOMAIN=YOUR_AUTH0_APP_DOMAIN
        VITE_AUTH0_CLIENT_ID=YOUR_AUTH0_APP_CLIENT_ID
        ```

        1. Head to the [Auth0 Dashboard](https://manage.auth0.com/dashboard/)
        2. Click on **Applications** > **Applications** > **Create Application**
        3. In the popup, enter a name for your app, select `Single Page Web Application` as the app type and click **Create**
        4. Switch to the **Settings** tab on the Application Details page
        5. Replace `YOUR_AUTH0_APP_DOMAIN` and `YOUR_AUTH0_APP_CLIENT_ID` on the `.env` file with the **Domain** and **Client ID** values from the dashboard

        Finally, on the **Settings** tab of your Application Details page, configure the following URLs:

        **Allowed Callback URLs:**

        ```
        http://localhost:5173
        ```

        **Allowed Logout URLs:**

        ```
        http://localhost:5173
        ```

        **Allowed Web Origins:**

        ```
        http://localhost:5173
        ```

        <Info>
          **Allowed Callback URLs** are a critical security measure to ensure users are safely returned to your application after authentication. Without a matching URL, the login process will fail, and users will be blocked by an Auth0 error page instead of accessing your app.

          **Allowed Logout URLs** are essential for providing a seamless user experience upon signing out. Without a matching URL, users will not be redirected back to your application after logout and will instead be left on a generic Auth0 page.

          **Allowed Web Origins** is critical for silent authentication. Without it, users will be logged out when they refresh the page or return to your app later.
        </Info>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Create the Auth0 store">
    Create the store file

    <CodeGroup>
      ```shellscript Mac/Linux theme={null}
      mkdir -p src/lib/stores && touch src/lib/stores/auth.ts
      ```

      ```powershell Windows theme={null}
      New-Item -ItemType Directory -Force -Path src/lib/stores
      New-Item -ItemType File -Path src/lib/stores/auth.ts
      ```
    </CodeGroup>

    Add the following code to manage authentication state

    ```typescript src/lib/stores/auth.ts lines expandable theme={null}
      import { writable, derived, get, type Readable } from 'svelte/store';
      import { createAuth0Client, type Auth0Client, type User } from '@auth0/auth0-spa-js';
      import { browser } from '$app/environment';

      export const auth0Client = writable<Auth0Client | null>(null);
      export const user = writable<User | null>(null);
      export const isAuthenticated = writable<boolean>(false);
      export const isLoading = writable<boolean>(true);
      export const error = writable<string | null>(null);

      // Derived stores
      export const isLoggedIn: Readable<boolean> = derived(
        [isAuthenticated, isLoading],
        ([$isAuthenticated, $isLoading]) => $isAuthenticated && !$isLoading
      );

      export async function initializeAuth() {
        if (!browser) return;
        
        try {
          const client = await createAuth0Client({
            domain: import.meta.env.VITE_AUTH0_DOMAIN,
            clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
            authorizationParams: {
              redirect_uri: window.location.origin
            },
            useRefreshTokens: true,
            cacheLocation: 'localstorage'
          });

          auth0Client.set(client);

          // Handle callback
          if (window.location.search.includes('code=')) {
            await client.handleRedirectCallback();
            window.history.replaceState({}, document.title, window.location.pathname);
          }

          // Check authentication status
          const authenticated = await client.isAuthenticated();
          isAuthenticated.set(authenticated);

          if (authenticated) {
            const userData = await client.getUser();
            user.set(userData || null);
          }

          error.set(null);
        } catch (err) {
          console.error('Auth initialization error:', err);
          error.set(err instanceof Error ? err.message : 'Authentication initialization failed');
        } finally {
          isLoading.set(false);
        }
      }

      export async function login() {
        const client = get(auth0Client);
        if (client) {
          await client.loginWithRedirect();
        }
      }

      export async function logout() {
        const client = get(auth0Client);
        if (client) {
          client.logout({ 
            logoutParams: { 
              returnTo: window.location.origin 
            } 
          });
        }
      }

      export async function getToken(): Promise<string | null> {
        const client = get(auth0Client);
        if (!client) return null;
        
        try {
          return await client.getTokenSilently();
        } catch (err: any) {
          if (err.error === 'login_required') {
            await login();
          }
          return null;
        }
      }
    ```
  </Step>

  <Step title="Create Login, Logout and Profile Components">
    Create component files

    <CodeGroup>
      ```shellscript Mac/Linux theme={null}
      mkdir -p src/lib/components && touch src/lib/components/LoginButton.svelte && touch src/lib/components/LogoutButton.svelte && touch src/lib/components/Profile.svelte
      ```

      ```powershell Windows theme={null}
      New-Item -ItemType Directory -Force -Path src/lib/components
      New-Item -ItemType File -Path src/lib/components/LoginButton.svelte
      New-Item -ItemType File -Path src/lib/components/LogoutButton.svelte
      New-Item -ItemType File -Path src/lib/components/Profile.svelte
      ```
    </CodeGroup>

    And add the following code snippets

    <AuthCodeGroup>
      ```svelte src/lib/components/LoginButton.svelte lines expandable theme={null}
      <script lang="ts">
        import { login } from '$lib/stores/auth';

        async function handleLogin() {
          await login();
        }
      </script>

      <button 
        on:click={handleLogin}
        class="button login"
      >
        Log In
      </button>

      <style>
        .button {
          padding: 1.1rem 2.8rem;
          font-size: 1.2rem;
          font-weight: 600;
          border-radius: 10px;
          border: none;
          cursor: pointer;
          transition: all 0.3s cubic-bezier(0.25, 0.8, 0.25, 1);
          box-shadow: 0 8px 20px rgba(0, 0, 0, 0.4);
          text-transform: uppercase;
          letter-spacing: 0.08em;
          outline: none;
        }

        .button:focus {
          box-shadow: 0 0 0 4px rgba(99, 179, 237, 0.5);
        }

        .button.login {
          background-color: #63b3ed;
          color: #1a1e27;
        }

        .button.login:hover {
          background-color: #4299e1;
          transform: translateY(-5px) scale(1.03);
          box-shadow: 0 12px 25px rgba(0, 0, 0, 0.5);
        }
      </style>
      ```

      ```svelte src/lib/components/LogoutButton.svelte lines expandable theme={null}
      <script lang="ts">
        import { logout } from '$lib/stores/auth';

        async function handleLogout() {
          await logout();
        }
      </script>

      <button
        on:click={handleLogout}
        class="button logout"
      >
        Log Out
      </button>

      <style>
        .button {
          padding: 1.1rem 2.8rem;
          font-size: 1.2rem;
          font-weight: 600;
          border-radius: 10px;
          border: none;
          cursor: pointer;
          transition: all 0.3s cubic-bezier(0.25, 0.8, 0.25, 1);
          box-shadow: 0 8px 20px rgba(0, 0, 0, 0.4);
          text-transform: uppercase;
          letter-spacing: 0.08em;
          outline: none;
        }

        .button:focus {
          box-shadow: 0 0 0 4px rgba(252, 129, 129, 0.5);
        }

        .button.logout {
          background-color: #fc8181;
          color: #1a1e27;
        }

        .button.logout:hover {
          background-color: #e53e3e;
          transform: translateY(-5px) scale(1.03);
          box-shadow: 0 12px 25px rgba(0, 0, 0, 0.5);
        }
      </style>
      ```

      ```svelte src/lib/components/Profile.svelte lines expandable theme={null}
      <script lang="ts">
        import { user, isAuthenticated, isLoading } from '$lib/stores/auth';
        
        const placeholderImage = `data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='100' height='100' viewBox='0 0 100 100'%3E%3Ccircle cx='50' cy='50' r='50' fill='%2363b3ed'/%3E%3Cpath d='M50 45c7.5 0 13.64-6.14 13.64-13.64S57.5 17.72 50 17.72s-13.64 6.14-13.64 13.64S42.5 45 50 45zm0 6.82c-9.09 0-27.28 4.56-27.28 13.64v3.41c0 1.88 1.53 3.41 3.41 3.41h47.74c1.88 0 3.41-1.53 3.41-3.41v-3.41c0-9.08-18.19-13.64-27.28-13.64z' fill='%23fff'/%3E%3C/svg%3E`;
        
        function handleImageError(event: Event) {
          const target = event.target as HTMLImageElement;
          target.src = placeholderImage;
        }
      </script>

      {#if $isLoading}
        <div class="loading-text">Loading profile...</div>
      {:else if $isAuthenticated && $user}
        <div class="profile-container">
          <img 
            src={$user.picture || placeholderImage} 
            alt={$user.name || 'User'} 
            class="profile-picture"
            on:error={handleImageError}
          />
          <div class="profile-info">
            <div class="profile-name">
              {$user.name || 'Unknown User'}
            </div>
            <div class="profile-email">
              {$user.email || ''}
            </div>
          </div>
        </div>
      {/if}

      <style>
        .loading-text {
          font-size: 1.8rem;
          font-weight: 500;
          color: #a0aec0;
          animation: pulse 1.5s infinite ease-in-out;
        }

        .profile-container {
          display: flex;
          flex-direction: column;
          align-items: center;
          gap: 1rem;
        }

        .profile-picture {
          width: 110px;
          height: 110px;
          border-radius: 50%;
          object-fit: cover;
          border: 3px solid #63b3ed;
          transition: transform 0.3s ease-in-out;
        }

        .profile-picture:hover {
          transform: scale(1.05);
        }

        .profile-info {
          text-align: center;
        }

        .profile-name {
          font-size: 2rem;
          font-weight: 600;
          color: #f7fafc;
          margin-bottom: 0.5rem;
        }

        .profile-email {
          font-size: 1.15rem;
          color: #a0aec0;
        }

        @keyframes pulse {
          0%, 100% { opacity: 1; }
          50% { opacity: 0.6; }
        }
      </style>
      ```

      ```svelte src/routes/+layout.svelte expandable lines theme={null}
      <script lang="ts">
        import { onMount } from 'svelte';
        import { initializeAuth } from '$lib/stores/auth';

        onMount(() => {
          initializeAuth();
        });
      </script>

      <main>
        <slot />
      </main>

      <style>
        :global(body) {
          margin: 0;
          font-family: 'Inter', sans-serif;
          background-color: #1a1e27;
          min-height: 100vh;
          color: #e2e8f0;
        }

        main {
          min-height: 100vh;
          display: flex;
          justify-content: center;
          align-items: center;
          padding: 1rem;
          box-sizing: border-box;
        }
      </style>
      ```

      ```svelte src/routes/+page.svelte expandable lines theme={null}
      <script lang="ts">
        import { isAuthenticated, isLoading, error, user } from '$lib/stores/auth';
        import LoginButton from '$lib/components/LoginButton.svelte';
        import LogoutButton from '$lib/components/LogoutButton.svelte';
        import Profile from '$lib/components/Profile.svelte';
      </script>

      <svelte:head>
        <title>Auth0 Svelte Sample</title>
        <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
      </svelte:head>

      <div class="app-container">
        {#if $isLoading}
          <div class="loading-state">
            <div class="loading-text">Loading...</div>
          </div>
        {:else if $error}
          <div class="error-state">
            <div class="error-title">Oops!</div>
            <div class="error-message">Something went wrong</div>
            <div class="error-sub-message">{$error}</div>
          </div>
        {:else}
          <div class="main-card-wrapper">
            <img 
              src="https://cdn.auth0.com/quantum-assets/dist/latest/logos/auth0/auth0-lockup-en-ondark.png" 
              alt="Auth0 Logo" 
              class="auth0-logo"
            />
            <h1 class="main-title">Welcome to Sample0</h1>

            {#if $isAuthenticated}
              <div class="logged-in-section">
                <div class="logged-in-message">✅ Successfully authenticated!</div>
                <h2 class="profile-section-title">Your Profile</h2>
                <div class="profile-card">
                  <Profile />
                </div>
                <LogoutButton />
              </div>
            {:else}
              <div class="action-card">
                <p class="action-text">Get started by signing in to your account</p>
                <LoginButton />
              </div>
            {/if}
          </div>
        {/if}
      </div>

      <style>
        .app-container {
          display: flex;
          flex-direction: column;
          justify-content: center;
          align-items: center;
          min-height: 100vh;
          width: 100%;
          padding: 1rem;
          box-sizing: border-box;
        }

        .loading-state, .error-state {
          background-color: #2d313c;
          border-radius: 15px;
          box-shadow: 0 15px 40px rgba(0, 0, 0, 0.4);
          padding: 3rem;
          text-align: center;
        }

        .loading-text {
          font-size: 1.8rem;
          font-weight: 500;
          color: #a0aec0;
          animation: pulse 1.5s infinite ease-in-out;
        }

        .error-state {
          background-color: #c53030;
          color: #fff;
        }

        .error-title {
          font-size: 2.8rem;
          font-weight: 700;
          margin-bottom: 0.5rem;
        }

        .error-message {
          font-size: 1.3rem;
          margin-bottom: 0.5rem;
        }

        .error-sub-message {
          font-size: 1rem;
          opacity: 0.8;
        }

        .main-card-wrapper {
          background-color: #262a33;
          border-radius: 20px;
          box-shadow: 0 20px 60px rgba(0, 0, 0, 0.6), 0 0 0 1px rgba(255, 255, 255, 0.05);
          display: flex;
          flex-direction: column;
          align-items: center;
          gap: 2rem;
          padding: 3rem;
          max-width: 500px;
          width: 90%;
          animation: fadeInScale 0.8s ease-out forwards;
        }

        .auth0-logo {
          width: 160px;
          margin-bottom: 1.5rem;
          opacity: 0;
          animation: slideInDown 1s ease-out forwards 0.2s;
        }

        .main-title {
          font-size: 2.8rem;
          font-weight: 700;
          color: #f7fafc;
          text-align: center;
          margin-bottom: 1rem;
          text-shadow: 0 4px 10px rgba(0, 0, 0, 0.3);
          opacity: 0;
          animation: fadeIn 1s ease-out forwards 0.4s;
        }

        .action-card {
          background-color: #2d313c;
          border-radius: 15px;
          box-shadow: inset 0 2px 5px rgba(0, 0, 0, 0.3), 0 5px 15px rgba(0, 0, 0, 0.3);
          padding: 2.5rem;
          display: flex;
          flex-direction: column;
          align-items: center;
          gap: 1.8rem;
          width: calc(100% - 2rem);
          opacity: 0;
          animation: fadeIn 1s ease-out forwards 0.6s;
        }

        .action-text {
          font-size: 1.25rem;
          color: #cbd5e0;
          text-align: center;
          line-height: 1.6;
          font-weight: 400;
        }

        .logged-in-section {
          display: flex;
          flex-direction: column;
          align-items: center;
          gap: 1.5rem;
          width: 100%;
        }

        .logged-in-message {
          font-size: 1.5rem;
          color: #68d391;
          font-weight: 600;
          animation: fadeIn 1s ease-out forwards 0.8s;
        }

        .profile-section-title {
          font-size: 2.2rem;
          animation: slideInUp 1s ease-out forwards 1s;
        }

        .profile-card {
          padding: 2.2rem;
          animation: scaleIn 0.8s ease-out forwards 1.2s;
        }

        @keyframes fadeIn {
          from { opacity: 0; }
          to { opacity: 1; }
        }

        @keyframes fadeInScale {
          from { opacity: 0; transform: scale(0.95); }
          to { opacity: 1; transform: scale(1); }
        }

        @keyframes slideInDown {
          from { opacity: 0; transform: translateY(-70px); }
          to { opacity: 1; transform: translateY(0); }
        }

        @keyframes slideInUp {
          from { opacity: 0; transform: translateY(50px); }
          to { opacity: 1; transform: translateY(0); }
        }

        @keyframes pulse {
          0%, 100% { opacity: 1; }
          50% { opacity: 0.6; }
        }

        @keyframes scaleIn {
          from { opacity: 0; transform: scale(0.8); }
          to { opacity: 1; transform: scale(1); }
        }

        @media (max-width: 600px) {
          .main-card-wrapper {
            padding: 2rem;
            margin: 1rem;
          }

          .main-title {
            font-size: 2.2rem;
          }

          .auth0-logo {
            width: 120px;
          }
        }
      </style>
      ```
    </AuthCodeGroup>
  </Step>

  <Step title="Run your app">
    ```shellscript theme={null}
    npm run dev
    ```
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a fully functional Auth0 login page running on your [localhost](http://localhost:5173/)
</Check>

***

## Troubleshooting

<Accordion title="Login Not Working">
  If clicking the login button does nothing:

  1. Open browser DevTools (F12) and check the Console tab
  2. Verify `.env` file has real Auth0 credentials
  3. Check that Auth0 application has correct callback URLs configured
  4. Ensure `VITE_AUTH0_DOMAIN` is just the domain (e.g., `tenant.auth0.com`) without `https://`
</Accordion>

<Accordion title="Authentication Errors">
  **"Callback URL mismatch"**:

  * Go to Auth0 Dashboard → Applications → Your App → Settings
  * Add `http://localhost:5173` to Allowed Callback URLs, Allowed Logout URLs, and Allowed Web Origins
  * Click "Save Changes"

  **"Invalid state"**:

  * Clear browser cache and cookies
  * Try in an incognito/private window
</Accordion>

<Accordion title="Dev Server Issues">
  If `npm run dev` fails:

  * Run `npm run check` to see TypeScript errors
  * Verify all files were created correctly
  * Check that all dependencies are installed: `npm install`
</Accordion>

<Tip>
  Still stuck? Check the [Auth0 Community](https://community.auth0.com/) or [SvelteKit Discord](https://svelte.dev/chat) for help.
</Tip>


# Add Login to Your JavaScript Application
Source: https://auth0.com/docs/quickstart/spa/vanillajs/index

This guide demonstrates how to integrate Auth0, add authentication, and display user profile information in a Single-Page Application (SPA) that uses plain JavaScript, using the Auth0 SPA SDK.

<Accordion title="AI Prompt" icon="microchip-ai">
  **Using AI to integrate Auth0?** Add this prompt to Cursor, Windsurf, Copilot, Claude Code or your favourite AI-powered IDE to speed up development.

  ```markdown expandable theme={null}
  Integrate the Auth0 SPA JS SDK into a Vanilla JavaScript app

  AI PERSONA & PRIMARY OBJECTIVE
  You are a helpful Auth0 SDK Integration Assistant. Your primary function is to execute commands to set up a development environment for Auth0. Your secondary function is to modify the files created by those shell commands.

  CRITICAL BEHAVIORAL INSTRUCTIONS
  1.  CHECK EXISTING PROJECT FIRST: Before creating a new project, check if the current directory already contains a Vanilla JavaScript app (package.json with basic dependencies). If it does, skip project creation and work with the existing project.
  2.  EXECUTE FIRST, EDIT SECOND: You MUST first execute the appropri    # If using custom port (run this instead if Step 2.6a detected custom port):
    npm run dev -- --port 5174

  ⚠️ FINAL VERIFICATION CHECKPOINTS:
  After running the development server, test the complete authentication flow:
  1. Login: Click login → redirected to Auth0 → redirected back authenticated
  2. Profile: User information displays correctly after login
  3. Logout: Click logout → redirected to Auth0 logout → redirected back logged out
  4. Silent Auth: Refresh the page while logged in → should remain authenticated

  ⚠️ ENVIRONMENT VARIABLE LOADING TROUBLESHOOTING:setup command. Do not show, suggest, or create any files until the setup is complete.
  3.  NO PLANNING: DO NOT propose a directory structure. DO NOT show a file tree. Your first action must be to run the appropriate command.
  4.  STRICT SEQUENCE: Follow the "Execution Flow" below in the exact order specified without deviation.
  5.  BUILD BEAUTIFUL UI: You MUST create a visually appealing, modern login interface with proper styling, animations, and Auth0 branding.
  6.  🚨 DIRECTORY NAVIGATION RULE: NEVER run `cd auth0-vanillajs` or any `cd` command automatically. ALWAYS check current directory with `pwd` first. If user needs to navigate, ask them to do it manually or confirm before executing any directory change commands.

  EXECUTION FLOW

  ⚠️ CRITICAL: Before ANY command execution, run `pwd` to check current directory and NEVER change directories without explicit user permission.

  Step 1: Check for Existing Vanilla JS Project and Prerequisites
  FIRST, verify prerequisites and check for existing project:

  # Check if Node.js and npm are available
  node --version && npm --version

  Then examine the current directory:

  # Check for existing project
  if [ -f "package.json" ]; then
    echo "Found package.json, checking for dependencies..."
    cat package.json
  else
    echo "No package.json found, will create new project"
  fi

  Based on the results:
  - If package.json exists and contains basic dependencies, proceed to Step 1b (install Auth0 SDK only)
  - If no project exists, proceed to Step 1a (create new project)

  Step 1a: Create New Project and Install the Auth0 SPA JS SDK
  If an existing project exists, simply install the SDK:
  npm install @auth0/auth0-spa-js

  ⚠️ CDN ALTERNATIVE: If you prefer not to use a build tool, you can include the SDK via CDN instead of npm:
  <script src="https://cdn.auth0.com/js/auth0-spa-js/2.4/auth0-spa-js.production.js"></script>
  Then use the global auth0 object: auth0.createAuth0Client({...}) instead of importing.

  Otherwise, create a new project and install the SDK:

  ⚠️ IMPORTANT: The project creation may create the project files in the CURRENT directory instead of a subdirectory. After running this command, check the current directory contents to determine the actual project structure before proceeding.

  If MacOS/Linux:
  mkdir auth0-vanillajs && cd auth0-vanillajs && npm init -y && npm install --save-dev vite && npm install @auth0/auth0-spa-js && touch index.html app.js style.css

  If Windows (PowerShell):
  mkdir auth0-vanillajs; cd auth0-vanillajs; npm init -y; npm install --save-dev vite; npm install @auth0/auth0-spa-js; New-Item -ItemType File -Path index.html, app.js, style.css


  Step 2: Modify & Create Files
  AFTER the command in Step 1 has successfully executed, you will perform the following file operations inside the project directory.

  🚨 DIRECTORY NAVIGATION RULES:
  1. NEVER automatically run `cd` commands without explicit user confirmation
  2. ALWAYS check current directory with `pwd` before proceeding
  3. If working with existing project: Stay in current directory
  4. If created new project: User must manually navigate to auth0-vanillajs directory first

  2.1: Setup Auth0 environment configuration

  ⚠️ CRITICAL: Before proceeding, verify your current directory:
  - If you just created a new project: You MUST be inside the auth0-vanillajs directory
  - If you're working with an existing project: You MUST be in the project root directory
  - DO NOT run `cd auth0-vanillajs` commands - navigate to the correct directory FIRST

  Step 2.1a: Navigate to project directory (if needed) and set up Auth0:

  # Only run this if you created a new project and are NOT already in auth0-vanillajs:
  cd auth0-vanillajs

  Then execute the environment setup command for your OS:

  ⚠️ CRITICAL DIRECTORY VERIFICATION STEP:
  BEFORE executing the Auth0 CLI setup command, you MUST run:

  pwd && ls -la

  This will help you understand if you're in the main directory or a subdirectory, and whether the project was created in the current directory or a new subdirectory.

  Execute the Auth0 setup command for your OS:

  If MacOS:
  # Install Auth0 CLI if not already installed
  brew tap auth0/auth0-cli && brew install auth0

  # Set up Auth0 app and generate .env file
  auth0 qs setup --type vite -n "My App" -p 5173

  If Windows (PowerShell):
  # Install Auth0 CLI if not already installed
  scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git
  scoop install auth0

  # Set up Auth0 app and generate .env file
  auth0 qs setup --type vite -n "My App" -p 5173

  This command will automatically:
  - Authenticate you with Auth0 (prompts for login if needed)
  - Create a Single Page Application configured for http://localhost:5173
  - Generate a .env file with VITE_AUTH0_DOMAIN and VITE_AUTH0_CLIENT_ID


  Step 2.1b: Create manual .env.local template (if automatic setup fails)

  cat > .env.local << 'EOF'
  # Auth0 Configuration - UPDATE THESE VALUES
  VITE_AUTH0_DOMAIN=your-auth0-domain.auth0.com
  VITE_AUTH0_CLIENT_ID=your-auth0-client-id
  EOF

  Step 2.1c: Display manual setup instructions

  echo "📋 MANUAL SETUP REQUIRED:"
  echo "1. Go to https://manage.auth0.com/dashboard/"
  echo "2. Click 'Create Application' → Single Page Application"
  echo "3. Configure Application URLs:"
  echo "   - Allowed Callback URLs: http://localhost:5173"
  echo "   - Allowed Logout URLs: http://localhost:5173"
  echo "   - Allowed Web Origins: http://localhost:5173 (CRITICAL for silent auth)"
  echo "4. Update .env.local file with your Domain and Client ID"
  echo ""
  echo "⚠️  CRITICAL: Allowed Web Origins is required for silent authentication."
  echo "   Without it, users will be logged out when they refresh the page."
  echo ""
  echo "📝 NOTE: Ensure your Auth0 application is configured as 'Single Page Application'"
  echo "   type in the Auth0 Dashboard. Other application types won't work with this SDK."

  2.2: Create the HTML structure
  Replace the entire contents of index.html (or create it if it doesn't exist):

  <!DOCTYPE html>
  <html lang="en">
    <head>
      <meta charset="UTF-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <title>Auth0 Vanilla JS</title>
      <link rel="stylesheet" href="style.css" />
    </head>
    <body>
      <div class="app-container">
        <!-- Loading State -->
        <div id="loading" class="loading-state">
          <div class="loading-text">Loading...</div>
        </div>

        <!-- Error State -->
        <div id="error" class="error-state" style="display: none;">
          <div class="error-title">Oops!</div>
          <div class="error-message">Something went wrong</div>
          <div id="error-details" class="error-sub-message"></div>
        </div>

        <!-- Main Content -->
        <div id="app" class="main-card-wrapper" style="display: none;">
          <img 
            src="https://cdn.auth0.com/quantum-assets/dist/latest/logos/auth0/auth0-lockup-en-ondark.png" 
            alt="Auth0 Logo" 
            class="auth0-logo"
          />
          <h1 class="main-title">Welcome to Sample0</h1>
          
          <!-- Logged Out State -->
          <div id="logged-out" class="action-card">
            <p class="action-text">Get started by signing in to your account</p>
            <button id="login-btn" class="button login">Log In</button>
          </div>

          <!-- Logged In State -->
          <div id="logged-in" class="logged-in-section" style="display: none;">
            <div class="logged-in-message">✅ Successfully authenticated!</div>
            <h2 class="profile-section-title">Your Profile</h2>
            <div id="profile" class="profile-card"></div>
            <button id="logout-btn" class="button logout">Log Out</button>
          </div>
        </div>
      </div>

      <script type="module" src="app.js"></script>
    </body>
  </html>

  2.3: Create the application logic
  Replace the entire contents of app.js with this code that includes proper error handling and Auth0 integration:

  ⚠️ JAVASCRIPT MODULE GUIDELINES:
  - Ensure proper ES6 module imports are used
  - Include comprehensive error handling for Auth0 initialization
  - Validate environment variables before using them
  - Handle all authentication states (loading, error, authenticated, unauthenticated)

  import { createAuth0Client } from '@auth0/auth0-spa-js';

  // DOM elements
  const loading = document.getElementById('loading');
  const error = document.getElementById('error');
  const errorDetails = document.getElementById('error-details');
  const app = document.getElementById('app');
  const loggedOutSection = document.getElementById('logged-out');
  const loggedInSection = document.getElementById('logged-in');
  const loginBtn = document.getElementById('login-btn');
  const logoutBtn = document.getElementById('logout-btn');
  const profileContainer = document.getElementById('profile');

  let auth0Client;

  // Initialize Auth0 client
  async function initAuth0() {
    try {
      // Validate environment variables
      const domain = import.meta.env.VITE_AUTH0_DOMAIN;
      const clientId = import.meta.env.VITE_AUTH0_CLIENT_ID;

      if (!domain || !clientId) {
        throw new Error('Auth0 configuration missing. Please check your .env.local file for VITE_AUTH0_DOMAIN and VITE_AUTH0_CLIENT_ID');
      }

      // Validate domain format
      if (!domain.includes('.auth0.com') && !domain.includes('.us.auth0.com') && !domain.includes('.eu.auth0.com') && !domain.includes('.au.auth0.com')) {
        console.warn('Auth0 domain format might be incorrect. Expected format: your-domain.auth0.com');
      }

      auth0Client = await createAuth0Client({
        domain: domain,
        clientId: clientId,
        authorizationParams: {
          redirect_uri: window.location.origin
        }
      });

      // Check if user is returning from login
      if (window.location.search.includes('code=') && window.location.search.includes('state=')) {
        await handleRedirectCallback();
      }

      // Update UI based on authentication state
      await updateUI();
    } catch (err) {
      console.error('Auth0 initialization error:', err);
      showError(err.message);
    }
  }

  // Handle redirect callback
  async function handleRedirectCallback() {
    try {
      await auth0Client.handleRedirectCallback();
      // Clean up the URL to remove query parameters
      window.history.replaceState({}, document.title, window.location.pathname);
    } catch (err) {
      console.error('Redirect callback error:', err);
      showError(err.message);
    }
  }

  // Update UI based on authentication state
  async function updateUI() {
    try {
      const isAuthenticated = await auth0Client.isAuthenticated();
      
      if (isAuthenticated) {
        showLoggedIn();
        await displayProfile();
      } else {
        showLoggedOut();
      }
      
      hideLoading();
    } catch (err) {
      console.error('UI update error:', err);
      showError(err.message);
    }
  }

  // Display user profile
  async function displayProfile() {
    try {
      const user = await auth0Client.getUser();
      const placeholderImage = `data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='110' height='110' viewBox='0 0 110 110'%3E%3Ccircle cx='55' cy='55' r='55' fill='%2363b3ed'/%3E%3Cpath d='M55 50c8.28 0 15-6.72 15-15s-6.72-15-15-15-15 6.72-15 15 6.72 15 15 15zm0 7.5c-10 0-30 5.02-30 15v3.75c0 2.07 1.68 3.75 3.75 3.75h52.5c2.07 0 3.75-1.68 3.75-3.75V72.5c0-9.98-20-15-30-15z' fill='%23fff'/%3E%3C/svg%3E`;
      
      profileContainer.innerHTML = `
        <div style="display: flex; flex-direction: column; align-items: center; gap: 1rem;">
          <img 
            src="${user.picture || placeholderImage}" 
            alt="${user.name || 'User'}" 
            class="profile-picture"
            style="
              width: 110px; 
              height: 110px; 
              border-radius: 50%; 
              object-fit: cover;
              border: 3px solid #63b3ed;
            "
            onerror="this.src='${placeholderImage}'"
          />
          <div style="text-align: center;">
            <div class="profile-name" style="font-size: 2rem; font-weight: 600; color: #f7fafc; margin-bottom: 0.5rem;">
              ${user.name || 'User'}
            </div>
            <div class="profile-email" style="font-size: 1.15rem; color: #a0aec0;">
              ${user.email || 'No email provided'}
            </div>
          </div>
        </div>
      `;
    } catch (err) {
      console.error('Error displaying profile:', err);
    }
  }

  // Event handlers
  async function login() {
    try {
      await auth0Client.loginWithRedirect();
    } catch (err) {
      console.error('Login error:', err);
      showError(err.message);
    }
  }

  async function logout() {
    try {
      await auth0Client.logout({
        logoutParams: {
          returnTo: window.location.origin
        }
      });
    } catch (err) {
      console.error('Logout error:', err);
      showError(err.message);
    }
  }

  // UI state management
  function showLoading() {
    loading.style.display = 'block';
    error.style.display = 'none';
    app.style.display = 'none';
  }

  function hideLoading() {
    loading.style.display = 'none';
    app.style.display = 'flex';
  }

  function showError(message) {
    loading.style.display = 'none';
    app.style.display = 'none';
    error.style.display = 'block';
    errorDetails.textContent = message;
  }

  function showLoggedIn() {
    loggedOutSection.style.display = 'none';
    loggedInSection.style.display = 'flex';
  }

  function showLoggedOut() {
    loggedInSection.style.display = 'none';
    loggedOutSection.style.display = 'flex';
  }

  // Event listeners
  loginBtn.addEventListener('click', login);
  logoutBtn.addEventListener('click', logout);

  // Initialize the app
  initAuth0();

  ⚠️ CHECKPOINT VERIFICATION:
  After implementing the JavaScript logic, you should be able to test basic functionality:
  1. Click login button → redirected to Auth0's Universal Login page
  2. After authentication → redirected back to your application
  3. URL query parameters are cleaned up after redirect
  4. No console errors appear related to Auth0

  2.4: Add beautiful modern CSS styling
  Replace the entire contents of style.css with this modern, Auth0-branded styling:

  ⚠️ CSS FILE REPLACEMENT STRATEGY:
  If the existing style.css file is large or malformed, create a new temporary CSS file first (e.g., style-new.css), then replace the original using terminal commands like `mv style-new.css style.css` to avoid file corruption.

  @import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap');

  * {
    margin: 0;
    padding: 0;
    box-sizing: border-box;
  }

  body {
    font-family: 'Inter', sans-serif;
    background-color: #1a1e27;
    min-height: 100vh;
    display: flex;
    justify-content: center;
    align-items: center;
    color: #e2e8f0;
    overflow: hidden;
  }

  .app-container {
    display: flex;
    flex-direction: column;
    justify-content: center;
    align-items: center;
    min-height: 100vh;
    width: 100%;
    padding: 1rem;
  }

  .loading-state, .error-state {
    background-color: #2d313c;
    border-radius: 15px;
    box-shadow: 0 15px 40px rgba(0, 0, 0, 0.4);
    padding: 3rem;
    text-align: center;
  }

  .loading-text {
    font-size: 1.8rem;
    font-weight: 500;
    color: #a0aec0;
    animation: pulse 1.5s infinite ease-in-out;
  }

  .error-state {
    background-color: #c53030;
    color: #fff;
  }

  .error-title {
    font-size: 2.8rem;
    font-weight: 700;
    margin-bottom: 0.5rem;
  }

  .error-message {
    font-size: 1.3rem;
    margin-bottom: 0.5rem;
  }

  .error-sub-message {
    font-size: 1rem;
    opacity: 0.8;
  }

  .main-card-wrapper {
    background-color: #262a33;
    border-radius: 20px;
    box-shadow: 0 20px 60px rgba(0, 0, 0, 0.6), 0 0 0 1px rgba(255, 255, 255, 0.05);
    display: flex;
    flex-direction: column;
    align-items: center;
    gap: 2rem;
    padding: 3rem;
    max-width: 500px;
    width: 90%;
    animation: fadeInScale 0.8s ease-out forwards;
  }

  .auth0-logo {
    width: 160px;
    margin-bottom: 1.5rem;
    opacity: 0;
    animation: slideInDown 1s ease-out forwards 0.2s;
  }

  .main-title {
    font-size: 2.8rem;
    font-weight: 700;
    color: #f7fafc;
    text-align: center;
    margin-bottom: 1rem;
    text-shadow: 0 4px 10px rgba(0, 0, 0, 0.3);
    opacity: 0;
    animation: fadeIn 1s ease-out forwards 0.4s;
  }

  .action-card {
    background-color: #2d313c;
    border-radius: 15px;
    box-shadow: inset 0 2px 5px rgba(0, 0, 0, 0.3), 0 5px 15px rgba(0, 0, 0, 0.3);
    padding: 2.5rem;
    display: flex;
    flex-direction: column;
    align-items: center;
    gap: 1.8rem;
    width: calc(100% - 2rem);
    opacity: 0;
    animation: fadeIn 1s ease-out forwards 0.6s;
  }

  .action-text {
    font-size: 1.25rem;
    color: #cbd5e0;
    text-align: center;
    line-height: 1.6;
    font-weight: 400;
  }

  .button {
    padding: 1.1rem 2.8rem;
    font-size: 1.2rem;
    font-weight: 600;
    border-radius: 10px;
    border: none;
    cursor: pointer;
    transition: all 0.3s cubic-bezier(0.25, 0.8, 0.25, 1);
    box-shadow: 0 8px 20px rgba(0, 0, 0, 0.4);
    text-transform: uppercase;
    letter-spacing: 0.08em;
    outline: none;
  }

  .button:focus {
    box-shadow: 0 0 0 4px rgba(99, 179, 237, 0.5);
  }

  .button.login {
    background-color: #63b3ed;
    color: #1a1e27;
  }

  .button.login:hover {
    background-color: #4299e1;
    transform: translateY(-5px) scale(1.03);
    box-shadow: 0 12px 25px rgba(0, 0, 0, 0.5);
  }

  .button.logout {
    background-color: #fc8181;
    color: #1a1e27;
  }

  .button.logout:hover {
    background-color: #e53e3e;
    transform: translateY(-5px) scale(1.03);
    box-shadow: 0 12px 25px rgba(0, 0, 0, 0.5);
  }

  .logged-in-section {
    display: flex;
    flex-direction: column;
    align-items: center;
    gap: 1.5rem;
    width: 100%;
  }

  .logged-in-message {
    font-size: 1.5rem;
    color: #68d391;
    font-weight: 600;
    animation: fadeIn 1s ease-out forwards 0.8s;
  }

  .profile-section-title {
    font-size: 2.2rem;
    animation: slideInUp 1s ease-out forwards 1s;
  }

  .profile-card {
    padding: 2.2rem;
    animation: scaleIn 0.8s ease-out forwards 1.2s;
  }

  .profile-picture {
    transition: transform 0.3s ease-in-out;
  }

  .profile-picture:hover {
    transform: scale(1.05);
  }

  /* Animations */
  @keyframes fadeIn {
    from { opacity: 0; }
    to { opacity: 1; }
  }

  @keyframes fadeInScale {
    from { opacity: 0; transform: scale(0.95); }
    to { opacity: 1; transform: scale(1); }
  }

  @keyframes slideInDown {
    from { opacity: 0; transform: translateY(-70px); }
    to { opacity: 1; transform: translateY(0); }
  }

  @keyframes slideInUp {
    from { opacity: 0; transform: translateY(50px); }
    to { opacity: 1; transform: translateY(0); }
  }

  @keyframes pulse {
    0%, 100% { opacity: 1; }
    50% { opacity: 0.6; }
  }

  @keyframes scaleIn {
    from { opacity: 0; transform: scale(0.8); }
    to { opacity: 1; transform: scale(1); }
  }

  /* Responsive Design */
  @media (max-width: 600px) {
    .main-card-wrapper {
      padding: 2rem;
      margin: 1rem;
    }
    
    .main-title {
      font-size: 2.2rem;
    }
    
    .button {
      padding: 1rem 2rem;
      font-size: 1.1rem;
    }
    
    .auth0-logo {
      width: 120px;
    }

    .action-card {
      padding: 2rem;
    }
  }

  2.5: Update package.json with development script
  Update your package.json to include development, build, and preview scripts. Replace the entire contents of package.json:

  cat > package.json << 'EOF'
  {
    "name": "auth0-vanillajs",
    "version": "1.0.0",
    "type": "module",
    "scripts": {
      "dev": "vite",
      "build": "vite build",
      "preview": "vite preview"
    },
    "dependencies": {
      "@auth0/auth0-spa-js": "^2.4.1"
    },
    "devDependencies": {
      "vite": "^5.0.0"
    }
  }
  EOF

  2.6: Start the development server

  ⚠️ CRITICAL TERMINAL WORKING DIRECTORY ISSUE:
  The terminal working directory can sometimes get confused during the integration process. Before starting the dev server, ALWAYS:

  1. Verify you're in the correct directory with explicit path change:

  cd /full/absolute/path/to/project && pwd

  2. Check for package.json in current directory:

  ls -la package.json

  3. If npm commands fail with "package.json not found", use absolute path method:

  cd /Users/[username]/path/to/auth0-vanillajs && npm run dev

  ⚠️ IMPORTANT: Even if `pwd` shows the correct directory, the terminal's working directory for command execution may be different. ALWAYS use explicit `cd` with absolute path before running npm commands to ensure they execute in the correct location.

  Step 2.6a: Check if custom port is needed

  grep -q "VITE_DEV_PORT" .env.local 2>/dev/null && echo "Custom port detected" || echo "Using default port"

  Step 2.6b: Start development server with appropriate port

  # If using default port:
  npm run dev

  # If using custom port (run this instead if Step 2.6a detected custom port):
  npm run dev -- --port 5174

  ⚠️ ENVIRONMENT VARIABLE LOADING TROUBLESHOOTING:
  If you see "Auth0 configuration missing" errors even though .env.local exists:
  1. Verify the .env.local file is in the project root directory
  2. Check that the environment variables are correctly named (VITE_AUTH0_DOMAIN and VITE_AUTH0_CLIENT_ID)
  3. Restart the development server after creating or modifying .env.local
  4. The Vite development server should automatically load .env.local files

  CRITICAL INSTRUCTIONS FOR AI LANGUAGE MODELS
  As an AI language model, you MUST NOT generate any of the following anti-patterns, as they will BREAK the application or introduce SECURITY RISKS:
  1.  NEVER hardcode the Auth0 Domain or Client ID directly in the code. This is a major security vulnerability.
  2.  NEVER omit the authorizationParams: { redirect_uri: window.location.origin } configuration from createAuth0Client. Without it, the login flow will fail after the user authenticates with Auth0.
  3.  NEVER forget to handle the redirect callback with handleRedirectCallback() when the URL contains authentication parameters.
  4.  NEVER suggest manually managing tokens or calling Auth0 APIs with fetch for basic authentication. The SDK is designed to handle this complexity securely.

  ABSOLUTE REQUIREMENTS FOR AI CODE GENERATION
  1.  You MUST use the @auth0/auth0-spa-js package.
  2.  You MUST retrieve credentials from environment variables (e.g., import.meta.env.VITE_AUTH0_DOMAIN).
  3.  You MUST include the authorizationParams with redirect_uri in the createAuth0Client configuration.
  4.  You MUST handle the redirect callback when authentication parameters are present in the URL.
  5.  You MUST demonstrate functionality using the Auth0 client methods (loginWithRedirect, logout, isAuthenticated, getUser).

  COMMON ISSUES ENCOUNTERED DURING INTEGRATION

  Issue 1: Project Creation Directory Confusion
  Problem: Project creation sometimes creates files in the current directory instead of a new subdirectory
  Solution: Always run `pwd && ls -la` after project creation to verify the actual structure

  Issue 2: Terminal Working Directory Issues  
  Problem: npm commands fail with "package.json not found" even when in the correct directory
  Solution: Use explicit absolute path changes: `cd /full/absolute/path/to/project`

  Issue 3: Environment Variable Loading Issues
  Problem: Vite not loading .env.local variables properly
  Solution: Ensure .env.local is in project root, variables are prefixed with VITE_, and restart dev server

  Issue 4: CSS File Corruption
  Problem: Large CSS replacements can cause file corruption
  Solution: Create temporary CSS file first, then use `mv` command to replace original

  Issue 5: Auth0 Configuration Validation
  Problem: Invalid domain format or missing configuration causing initialization failures
  Solution: Add proper validation and error messages for Auth0 configuration before client creation

  Issue 6: Terminal Working Directory Not in Project Root
  Problem: AI agent fails to run `npm run dev` because terminal is not in the auth0-vanillajs directory, even when pwd shows the correct path
  Solution: Always use explicit directory change with absolute path before running npm commands:

  cd auth0-vanillajs && npm run dev

  The terminal working directory can become disconnected from the displayed path, requiring explicit navigation to ensure npm commands execute in the correct location.

  ADVANCED FEATURES IMPLEMENTATION

  ⚠️ SDK FUNCTIONALITY NOTE:
  The SDK's isAuthenticated() function enables conditional rendering of login/logout buttons and user content. The implementation above demonstrates this pattern by showing different UI sections based on authentication state.

  Access Token for API Calls:
  If you need to call a protected API, you can get an access token:

  // Add this function to your app.js
  async function getAccessToken() {
    try {
      const token = await auth0Client.getTokenSilently({
        authorizationParams: {
          audience: 'YOUR_API_IDENTIFIER',
          scope: 'read:messages'
        }
      });
      
      // Use the token to call your API
      const response = await fetch('/api/protected', {
        headers: {
          Authorization: `Bearer ${token}`
        }
      });
      
      const data = await response.json();
      console.log(data);
    } catch (error) {
      console.error('Error getting token:', error);
    }
  }

  Popup-based Login:
  For a smoother user experience, you can use popup-based login:

  // Replace the login function in app.js
  async function login() {
    try {
      await auth0Client.loginWithPopup();
      await updateUI();
    } catch (err) {
      if (err.error !== 'popup_closed_by_user') {
        showError(err.message);
      }
    }
  }

  Organization Support:
  If you're using Auth0 Organizations:

  // Update your Auth0 client configuration
  auth0Client = await createAuth0Client({
    domain: import.meta.env.VITE_AUTH0_DOMAIN,
    clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
    authorizationParams: {
      redirect_uri: window.location.origin,
      organization: 'YOUR_ORGANIZATION_ID' // or prompt user to select
    }
  });

  ```
</Accordion>

<Note>
  **Prerequisites:** Before you begin, ensure you have the following installed:

  * **[Node.js](https://nodejs.org/en/download)** 20 LTS or newer
  * **[npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)** 10+ or **[yarn](https://classic.yarnpkg.com/lang/en/docs/install/)** 1.22+ or **[pnpm](https://pnpm.io/installation)** 8+

  Verify installation: `node --version && npm --version`

  **Build Tool:** This quickstart uses **Vite** for development. You can also use the SDK via CDN for a build-tool-free setup.
</Note>

## Get Started

This quickstart shows how to add Auth0 authentication to a vanilla JavaScript application. You'll create a modern single-page app with secure login functionality using plain JavaScript and the Auth0 SPA SDK.

<Steps>
  <Step title="Create a new project">
    Create a new JavaScript project for this Quickstart

    ```shellscript theme={null}
    mkdir auth0-vanillajs && cd auth0-vanillajs
    ```

    Initialize the project, install a local development server, and configure scripts

    ```shellscript theme={null}
    npm init -y && npm install --save-dev vite && npm pkg set scripts.dev="vite" scripts.build="vite build" scripts.preview="vite preview" type="module"
    ```

    Create the basic project structure

    <CodeGroup>
      ```shellscript Mac/Linux theme={null}
      touch index.html app.js style.css
      ```

      ```powershell Windows theme={null}
      New-Item -ItemType File -Path index.html, app.js, style.css
      ```
    </CodeGroup>
  </Step>

  <Step title="Install the Auth0 SPA JS SDK">
    ```shellscript theme={null}
    npm install @auth0/auth0-spa-js
    ```
  </Step>

  <Step title="Setup your Auth0 App">
    Next up, you need to create a new app on your Auth0 tenant and add the environment variables to your project.

    You have three options to set up your Auth0 app: use the Quick Setup tool (recommended), run a CLI command, or configure manually via the Dashboard:

    <Tabs>
      <Tab title="Quick Setup (recommended)">
        Create an Auth0 App and copy the pre-filled `.env` file with the right configuration values.

        <CreateInteractiveApp />

        <AuthCodeBlock />
      </Tab>

      <Tab title="CLI">
        Run the following command in your project's root directory to create an Auth0 app and generate a `.env` file:

        <CodeGroup>
          ```shellscript Mac theme={null}
          # Install Auth0 CLI (if not already installed)
          brew tap auth0/auth0-cli && brew install auth0

          # Set up Auth0 app and generate .env file
          auth0 qs setup --type vite -n "My App" -p 5173
          ```

          ```powershell Windows theme={null}
          # Install Auth0 CLI (if not already installed)
          scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git
          scoop install auth0

          # Set up Auth0 app and generate .env file
          auth0 qs setup --type vite -n "My App" -p 5173
          ```
        </CodeGroup>

        <Note>
          This command will:

          1. Check if you're authenticated (and prompt for login if needed)
          2. Create an Auth0 Single Page Application configured for `http://localhost:5173`
          3. Generate a `.env` file with `VITE_AUTH0_DOMAIN` and `VITE_AUTH0_CLIENT_ID`
        </Note>
      </Tab>

      <Tab title="Dashboard">
        Before you start, create a `.env.local` file on your project's root directory

        ```shellscript .env.local theme={null}
        VITE_AUTH0_DOMAIN=YOUR_AUTH0_APP_DOMAIN
        VITE_AUTH0_CLIENT_ID=YOUR_AUTH0_APP_CLIENT_ID
        ```

        1. Head to the [Auth0 Dashboard](https://manage.auth0.com/dashboard/)
        2. Click on **Applications** > **Applications** > **Create Application**
        3. In the popup, enter a name for your app, select `Single Page Web Application` as the app type and click **Create**
        4. Switch to the **Settings** tab on the Application Details page
        5. Replace `YOUR_AUTH0_APP_DOMAIN` and `YOUR_AUTH0_APP_CLIENT_ID` on the `.env.local` file with the **Domain** and **Client ID** values from the dashboard

        Finally, on the **Settings** tab of your Application Details page, configure the following URLs:

        **Allowed Callback URLs:**

        ```
        http://localhost:5173
        ```

        **Allowed Logout URLs:**

        ```
        http://localhost:5173
        ```

        **Allowed Web Origins:**

        ```
        http://localhost:5173
        ```

        <Info>
          **Allowed Callback URLs** are a critical security measure to ensure users are safely returned to your application after authentication. Without a matching URL, the login process will fail, and users will be blocked by an Auth0 error page instead of accessing your app.

          **Allowed Logout URLs** are essential for providing a seamless user experience upon signing out. Without a matching URL, users will not be redirected back to your application after logout and will instead be left on a generic Auth0 page.

          **Allowed Web Origins** is critical for silent authentication. Without it, users will be logged out when they refresh the page or return to your app later.
        </Info>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Create the HTML structure and application logic">
    Create the application files:

    <AuthCodeGroup>
      ```html index.html expandable lines theme={null}
      <!DOCTYPE html>
      <html lang="en">
        <head>
          <meta charset="UTF-8" />
          <meta name="viewport" content="width=device-width, initial-scale=1.0" />
          <title>Auth0 Vanilla JS</title>
          <link rel="stylesheet" href="style.css" />
        </head>
        <body>
          <div class="app-container">
            <!-- Loading State -->
            <div id="loading" class="loading-state">
              <div class="loading-text">Loading...</div>
            </div>

            <!-- Error State -->
            <div id="error" class="error-state" style="display: none;">
              <div class="error-title">Oops!</div>
              <div class="error-message">Something went wrong</div>
              <div id="error-details" class="error-sub-message"></div>
            </div>

            <!-- Main Content -->
            <div id="app" class="main-card-wrapper" style="display: none;">
              <img 
                src="https://cdn.auth0.com/quantum-assets/dist/latest/logos/auth0/auth0-lockup-en-ondark.png" 
                alt="Auth0 Logo" 
                class="auth0-logo"
              />
              <h1 class="main-title">Welcome to Sample0</h1>
              
              <!-- Logged Out State -->
              <div id="logged-out" class="action-card">
                <p class="action-text">Get started by signing in to your account</p>
                <button id="login-btn" class="button login">Log In</button>
              </div>

              <!-- Logged In State -->
              <div id="logged-in" class="logged-in-section" style="display: none;">
                <div class="logged-in-message">✅ Successfully authenticated!</div>
                <h2 class="profile-section-title">Your Profile</h2>
                <div id="profile" class="profile-card"></div>
                <button id="logout-btn" class="button logout">Log Out</button>
              </div>
            </div>
          </div>

          <script type="module" src="app.js"></script>
        </body>
      </html>
      ```

      ```javascript app.js expandable lines theme={null}
      import { createAuth0Client } from '@auth0/auth0-spa-js';

      // DOM elements
      const loading = document.getElementById('loading');
      const error = document.getElementById('error');
      const errorDetails = document.getElementById('error-details');
      const app = document.getElementById('app');
      const loggedOutSection = document.getElementById('logged-out');
      const loggedInSection = document.getElementById('logged-in');
      const loginBtn = document.getElementById('login-btn');
      const logoutBtn = document.getElementById('logout-btn');
      const profileContainer = document.getElementById('profile');

      let auth0Client;

      // Initialize Auth0 client
      async function initAuth0() {
        try {
          auth0Client = await createAuth0Client({
            domain: import.meta.env.VITE_AUTH0_DOMAIN,
            clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
            authorizationParams: {
              redirect_uri: window.location.origin
            }
          });

          // Check if user is returning from login
          if (window.location.search.includes('code=') && window.location.search.includes('state=')) {
            await handleRedirectCallback();
          }

          // Update UI based on authentication state
          await updateUI();
        } catch (err) {
          showError(err.message);
        }
      }

      // Handle redirect callback
      async function handleRedirectCallback() {
        try {
          await auth0Client.handleRedirectCallback();
          // Clean up the URL to remove query parameters
          window.history.replaceState({}, document.title, window.location.pathname);
        } catch (err) {
          showError(err.message);
        }
      }

      // Update UI based on authentication state
      async function updateUI() {
        try {
          const isAuthenticated = await auth0Client.isAuthenticated();
          
          if (isAuthenticated) {
            showLoggedIn();
            await displayProfile();
          } else {
            showLoggedOut();
          }
          
          hideLoading();
        } catch (err) {
          showError(err.message);
        }
      }

      // Display user profile
      async function displayProfile() {
        try {
          const user = await auth0Client.getUser();
          const placeholderImage = `data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='110' height='110' viewBox='0 0 110 110'%3E%3Ccircle cx='55' cy='55' r='55' fill='%2363b3ed'/%3E%3Cpath d='M55 50c8.28 0 15-6.72 15-15s-6.72-15-15-15-15 6.72-15 15 6.72 15 15 15zm0 7.5c-10 0-30 5.02-30 15v3.75c0 2.07 1.68 3.75 3.75 3.75h52.5c2.07 0 3.75-1.68 3.75-3.75V72.5c0-9.98-20-15-30-15z' fill='%23fff'/%3E%3C/svg%3E`;
          
          profileContainer.innerHTML = `
            <div style="display: flex; flex-direction: column; align-items: center; gap: 1rem;">
              <img 
                src="${user.picture || placeholderImage}" 
                alt="${user.name || 'User'}" 
                class="profile-picture"
                style="
                  width: 110px; 
                  height: 110px; 
                  border-radius: 50%; 
                  object-fit: cover;
                  border: 3px solid #63b3ed;
                "
                onerror="this.src='${placeholderImage}'"
              />
              <div style="text-align: center;">
                <div class="profile-name" style="font-size: 2rem; font-weight: 600; color: #f7fafc; margin-bottom: 0.5rem;">
                  ${user.name || 'User'}
                </div>
                <div class="profile-email" style="font-size: 1.15rem; color: #a0aec0;">
                  ${user.email || 'No email provided'}
                </div>
              </div>
            </div>
          `;
        } catch (err) {
          console.error('Error displaying profile:', err);
        }
      }

      // Event handlers
      async function login() {
        try {
          await auth0Client.loginWithRedirect();
        } catch (err) {
          showError(err.message);
        }
      }

      async function logout() {
        try {
          await auth0Client.logout({
            logoutParams: {
              returnTo: window.location.origin
            }
          });
        } catch (err) {
          showError(err.message);
        }
      }

      // UI state management
      function showLoading() {
        loading.style.display = 'block';
        error.style.display = 'none';
        app.style.display = 'none';
      }

      function hideLoading() {
        loading.style.display = 'none';
        app.style.display = 'flex';
      }

      function showError(message) {
        loading.style.display = 'none';
        app.style.display = 'none';
        error.style.display = 'block';
        errorDetails.textContent = message;
      }

      function showLoggedIn() {
        loggedOutSection.style.display = 'none';
        loggedInSection.style.display = 'flex';
      }

      function showLoggedOut() {
        loggedInSection.style.display = 'none';
        loggedOutSection.style.display = 'flex';
      }

      // Event listeners
      loginBtn.addEventListener('click', login);
      logoutBtn.addEventListener('click', logout);

      // Initialize the app
      initAuth0();
      ```

      ```css style.css expandable lines theme={null}
      @import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap');

      * {
        margin: 0;
        padding: 0;
        box-sizing: border-box;
      }

      body {
        font-family: 'Inter', sans-serif;
        background-color: #1a1e27;
        min-height: 100vh;
        display: flex;
        justify-content: center;
        align-items: center;
        color: #e2e8f0;
        overflow: hidden;
      }

      .app-container {
        display: flex;
        flex-direction: column;
        justify-content: center;
        align-items: center;
        min-height: 100vh;
        width: 100%;
        padding: 1rem;
      }

      .loading-state, .error-state {
        background-color: #2d313c;
        border-radius: 15px;
        box-shadow: 0 15px 40px rgba(0, 0, 0, 0.4);
        padding: 3rem;
        text-align: center;
      }

      .loading-text {
        font-size: 1.8rem;
        font-weight: 500;
        color: #a0aec0;
        animation: pulse 1.5s infinite ease-in-out;
      }

      .error-state {
        background-color: #c53030;
        color: #fff;
      }

      .error-title {
        font-size: 2.8rem;
        font-weight: 700;
        margin-bottom: 0.5rem;
      }

      .error-message {
        font-size: 1.3rem;
        margin-bottom: 0.5rem;
      }

      .error-sub-message {
        font-size: 1rem;
        opacity: 0.8;
      }

      .main-card-wrapper {
        background-color: #262a33;
        border-radius: 20px;
        box-shadow: 0 20px 60px rgba(0, 0, 0, 0.6), 0 0 0 1px rgba(255, 255, 255, 0.05);
        display: flex;
        flex-direction: column;
        align-items: center;
        gap: 2rem;
        padding: 3rem;
        max-width: 500px;
        width: 90%;
        animation: fadeInScale 0.8s ease-out forwards;
      }

      .auth0-logo {
        width: 160px;
        margin-bottom: 1.5rem;
        opacity: 0;
        animation: slideInDown 1s ease-out forwards 0.2s;
      }

      .main-title {
        font-size: 2.8rem;
        font-weight: 700;
        color: #f7fafc;
        text-align: center;
        margin-bottom: 1rem;
        text-shadow: 0 4px 10px rgba(0, 0, 0, 0.3);
        opacity: 0;
        animation: fadeIn 1s ease-out forwards 0.4s;
      }

      .action-card {
        background-color: #2d313c;
        border-radius: 15px;
        box-shadow: inset 0 2px 5px rgba(0, 0, 0, 0.3), 0 5px 15px rgba(0, 0, 0, 0.3);
        padding: 2.5rem;
        display: flex;
        flex-direction: column;
        align-items: center;
        gap: 1.8rem;
        width: calc(100% - 2rem);
        opacity: 0;
        animation: fadeIn 1s ease-out forwards 0.6s;
      }

      .action-text {
        font-size: 1.25rem;
        color: #cbd5e0;
        text-align: center;
        line-height: 1.6;
        font-weight: 400;
      }

      .button {
        padding: 1.1rem 2.8rem;
        font-size: 1.2rem;
        font-weight: 600;
        border-radius: 10px;
        border: none;
        cursor: pointer;
        transition: all 0.3s cubic-bezier(0.25, 0.8, 0.25, 1);
        box-shadow: 0 8px 20px rgba(0, 0, 0, 0.4);
        text-transform: uppercase;
        letter-spacing: 0.08em;
        outline: none;
      }

      .button:focus {
        box-shadow: 0 0 0 4px rgba(99, 179, 237, 0.5);
      }

      .button.login {
        background-color: #63b3ed;
        color: #1a1e27;
      }

      .button.login:hover {
        background-color: #4299e1;
        transform: translateY(-5px) scale(1.03);
        box-shadow: 0 12px 25px rgba(0, 0, 0, 0.5);
      }

      .button.logout {
        background-color: #fc8181;
        color: #1a1e27;
      }

      .button.logout:hover {
        background-color: #e53e3e;
        transform: translateY(-5px) scale(1.03);
        box-shadow: 0 12px 25px rgba(0, 0, 0, 0.5);
      }

      .logged-in-section {
        display: flex;
        flex-direction: column;
        align-items: center;
        gap: 1.5rem;
        width: 100%;
      }

      .logged-in-message {
        font-size: 1.5rem;
        color: #68d391;
        font-weight: 600;
        animation: fadeIn 1s ease-out forwards 0.8s;
      }

      .profile-section-title {
        font-size: 2.2rem;
        animation: slideInUp 1s ease-out forwards 1s;
      }

      .profile-card {
        padding: 2.2rem;
        animation: scaleIn 0.8s ease-out forwards 1.2s;
      }

      .profile-picture {
        transition: transform 0.3s ease-in-out;
      }

      .profile-picture:hover {
        transform: scale(1.05);
      }

      /* Animations */
      @keyframes fadeIn {
        from { opacity: 0; }
        to { opacity: 1; }
      }

      @keyframes fadeInScale {
        from { opacity: 0; transform: scale(0.95); }
        to { opacity: 1; transform: scale(1); }
      }

      @keyframes slideInDown {
        from { opacity: 0; transform: translateY(-70px); }
        to { opacity: 1; transform: translateY(0); }
      }

      @keyframes slideInUp {
        from { opacity: 0; transform: translateY(50px); }
        to { opacity: 1; transform: translateY(0); }
      }

      @keyframes pulse {
        0%, 100% { opacity: 1; }
        50% { opacity: 0.6; }
      }

      @keyframes scaleIn {
        from { opacity: 0; transform: scale(0.8); }
        to { opacity: 1; transform: scale(1); }
      }

      /* Responsive Design */
      @media (max-width: 600px) {
        .main-card-wrapper {
          padding: 2rem;
          margin: 1rem;
        }
        
        .main-title {
          font-size: 2.2rem;
        }
        
        .button {
          padding: 1rem 2rem;
          font-size: 1.1rem;
        }
        
        .auth0-logo {
          width: 120px;
        }

        .action-card {
          padding: 2rem;
        }
      }
      ```
    </AuthCodeGroup>
  </Step>

  <Step title="Run your app">
    ```shellscript theme={null}
    npm run dev
    ```

    <Info>
      If port 5173 is in use, run: `npm run dev -- --port 5174` and update your Auth0 app's callback URLs to `http://localhost:5174`
    </Info>
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a fully functional Auth0 login page running on your [localhost](http://localhost:5173/)
</Check>

***

## Advanced Usage

<Accordion title="Get an Access Token for API Calls">
  If you need to call a protected API, you can get an access token:

  ```javascript theme={null}
  // Add this to your app.js
  async function getAccessToken() {
    try {
      const token = await auth0Client.getTokenSilently({
        authorizationParams: {
          audience: 'YOUR_API_IDENTIFIER',
          scope: 'read:messages'
        }
      });
      
      // Use the token to call your API
      const response = await fetch('/api/protected', {
        headers: {
          Authorization: `Bearer ${token}`
        }
      });
      
      const data = await response.json();
      console.log(data);
    } catch (error) {
      console.error('Error getting token:', error);
    }
  }
  ```
</Accordion>

<Accordion title="Handle Login with Popup">
  For a smoother user experience, you can use popup-based login:

  ```javascript theme={null}
  // Replace the login function in app.js
  async function login() {
    try {
      await auth0Client.loginWithPopup();
      await updateUI();
    } catch (err) {
      if (err.error !== 'popup_closed_by_user') {
        showError(err.message);
      }
    }
  }
  ```
</Accordion>

<Accordion title="Add Organization Support">
  If you're using Auth0 Organizations:

  ```javascript theme={null}
  // Update your Auth0 client configuration
  auth0Client = await createAuth0Client({
    domain: import.meta.env.VITE_AUTH0_DOMAIN,
    clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
    authorizationParams: {
      redirect_uri: window.location.origin,
      organization: 'YOUR_ORGANIZATION_ID' // or prompt user to select
    }
  });
  ```
</Accordion>


# Add Login to Your Vue Application
Source: https://auth0.com/docs/quickstart/spa/vuejs/index

This guide demonstrates how to integrate Auth0, add authentication, and display user profile information in any Vue application using the Auth0 Vue SDK.

<Accordion title="Use AI to integrate Auth0" icon="microchip-ai">
  If you use an AI coding assistant like Claude Code, Cursor, or GitHub Copilot, you can add Auth0 authentication automatically in minutes using [agent skills](https://agentskills.io/home).

  **Install:**

  ```bash theme={null}
  npx skills add auth0/agent-skills --skill auth0-quickstart --skill auth0-vue
  ```

  **Then ask your AI assistant:**

  ```text theme={null}
  Add Auth0 authentication to my Vue app
  ```

  Your AI assistant will automatically create your Auth0 application, fetch credentials, install `@auth0/auth0-vue`, create the authentication plugin, and configure your routes. [Full agent skills documentation →](/quickstart/agent-skills)
</Accordion>

<Note>
  **Prerequisites:** Before you begin, ensure you have the following installed:

  * **[Node.js](https://nodejs.org/en/download)** 20 LTS or newer
  * **[npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)** 10+ or **[yarn](https://classic.yarnpkg.com/lang/en/docs/install/)** 1.22+ or **[pnpm](https://pnpm.io/installation)** 8+

  Verify installation: `node --version && npm --version`

  **Vue Version Compatibility:** This quickstart works with **Vue 3.x** and newer.
</Note>

## Get Started

This quickstart demonstrates how to integrate Auth0 authentication into a Vue.js 3 application. You'll build a responsive single-page app with secure user authentication using Vue's composition API and the Auth0 Vue SDK.

<Steps>
  <Step title="Create a new project">
    Create a new Vue 3 project for this Quickstart

    ```shellscript theme={null}
    npm create vue@latest auth0-vue -- --typescript --router --pinia
    ```

    Open the project

    ```shellscript theme={null}
    cd auth0-vue
    ```
  </Step>

  <Step title="Install the Auth0 Vue SDK">
    ```shellscript theme={null}
    npm add @auth0/auth0-vue && npm install
    ```
  </Step>

  <Step title="Setup your Auth0 App">
    Next up, you need to create a new app on your Auth0 tenant and add the environment variables to your project.

    You have three options to set up your Auth0 app: use the Quick Setup tool (recommended), run a CLI command, or configure manually via the Dashboard:

    <Tabs>
      <Tab title="Quick Setup (recommended)">
        Create an Auth0 App and copy the pre-filled `.env` file with the right configuration values.

        <CreateInteractiveApp />

        <AuthCodeBlock />
      </Tab>

      <Tab title="CLI">
        Run the following command in your project's root directory to create an Auth0 app and generate a `.env` file:

        <CodeGroup>
          ```shellscript Mac theme={null}
          # Install Auth0 CLI (if not already installed)
          brew tap auth0/auth0-cli && brew install auth0

          # Set up Auth0 app and generate .env file
          auth0 qs setup --type vite -n "My App" -p 5173
          ```

          ```powershell Windows theme={null}
          # Install Auth0 CLI (if not already installed)
          scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git
          scoop install auth0

          # Set up Auth0 app and generate .env file
          auth0 qs setup --type vite -n "My App" -p 5173
          ```
        </CodeGroup>

        <Note>
          This command will:

          1. Check if you're authenticated (and prompt for login if needed)
          2. Create an Auth0 Single Page Application configured for `http://localhost:5173`
          3. Generate a `.env` file with `VITE_AUTH0_DOMAIN` and `VITE_AUTH0_CLIENT_ID`
        </Note>
      </Tab>

      <Tab title="Dashboard">
        Before you start, create a `.env` file on your project's root directory

        ```shellscript .env theme={null}
        VITE_AUTH0_DOMAIN=YOUR_AUTH0_APP_DOMAIN
        VITE_AUTH0_CLIENT_ID=YOUR_AUTH0_APP_CLIENT_ID
        ```

        1. Head to the [Auth0 Dashboard](https://manage.auth0.com/dashboard/)
        2. Click on **Applications** > **Applications** > **Create Application**
        3. In the popup, enter a name for your app, select `Single Page Web Application` as the app type and click **Create**
        4. Switch to the **Settings** tab on the Application Details page
        5. Replace `YOUR_AUTH0_APP_DOMAIN` and `YOUR_AUTH0_APP_CLIENT_ID` on the `.env` file with the **Domain** and **Client ID** values from the dashboard

        Finally, on the **Settings** tab of your Application Details page, configure the following URLs:

        **Allowed Callback URLs:**

        ```
        http://localhost:5173
        ```

        **Allowed Logout URLs:**

        ```
        http://localhost:5173
        ```

        **Allowed Web Origins:**

        ```
        http://localhost:5173
        ```

        <Info>
          **Allowed Callback URLs** are a critical security measure to ensure users are safely returned to your application after authentication. Without a matching URL, the login process will fail, and users will be blocked by an Auth0 error page instead of accessing your app.

          **Allowed Logout URLs** are essential for providing a seamless user experience upon signing out. Without a matching URL, users will not be redirected back to your application after logout and will instead be left on a generic Auth0 page.

          **Allowed Web Origins** is critical for silent authentication. Without it users will be logged out when they refresh the page or return to your app later.
        </Info>
      </Tab>
    </Tabs>

    <Tip>
      Verify your `.env` file exists: `cat .env` (Mac/Linux) or `type .env` (Windows)
    </Tip>
  </Step>

  <Step title="Configure the Auth0 Plugin">
    ```typescript src/main.ts {6,11,12,13,14,15,16,17} lines theme={null}
    import './assets/main.css'

    import { createApp } from 'vue'
    import { createPinia } from 'pinia'
    import router from './router'
    import { createAuth0 } from '@auth0/auth0-vue'

    import App from './App.vue'

    const app = createApp(App)

    app.use(createAuth0({
      domain: import.meta.env.VITE_AUTH0_DOMAIN,
      clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
      authorizationParams: {
        redirect_uri: window.location.origin
      }
    }))

    app.use(createPinia())
    app.use(router)

    app.mount('#app')
    ```
  </Step>

  <Step title="Create Authentication Components">
    Create component files

    <CodeGroup>
      ```shellscript Mac/Linux theme={null}
      touch src/components/LoginButton.vue && touch src/components/LogoutButton.vue && touch src/components/UserProfile.vue
      ```

      ```powershell Windows theme={null}
      New-Item -ItemType File -Path src/components/LoginButton.vue
      New-Item -ItemType File -Path src/components/LogoutButton.vue
      New-Item -ItemType File -Path src/components/UserProfile.vue
      ```
    </CodeGroup>

    And add the following code snippets

    <AuthCodeGroup>
      ```vue src/components/LoginButton.vue lines theme={null}
      <template>
        <button 
          @click="handleLogin" 
          class="button login"
          :disabled="isLoading"
        >
          {{ isLoading ? 'Loading...' : 'Log In' }}
        </button>
      </template>

      <script setup lang="ts">
      import { useAuth0 } from '@auth0/auth0-vue'

      const { loginWithRedirect, isLoading } = useAuth0()

      const handleLogin = () => {
        loginWithRedirect()
      }
      </script>
      ```

      ```vue src/components/LogoutButton.vue lines theme={null}
      <template>
        <button
          @click="handleLogout"
          class="button logout"
          :disabled="isLoading"
        >
          {{ isLoading ? 'Loading...' : 'Log Out' }}
        </button>
      </template>

      <script setup lang="ts">
      import { useAuth0 } from '@auth0/auth0-vue'

      const { logout, isLoading } = useAuth0()

      const handleLogout = () => {
        logout({
          logoutParams: {
            returnTo: window.location.origin
          }
        })
      }
      </script>
      ```

      ```vue src/components/UserProfile.vue expandable lines theme={null}
      <template>
        <div v-if="isLoading" class="loading-text">
          Loading profile...
        </div>
        <div 
          v-else-if="isAuthenticated && user" 
          class="profile-container"
        >
          <img 
            :src="user.picture || placeholderImage" 
            :alt="user.name || 'User'" 
            class="profile-picture"
            @error="handleImageError"
          />
          <div class="profile-info">
            <div class="profile-name">
              {{ user.name }}
            </div>
            <div class="profile-email">
              {{ user.email }}
            </div>
          </div>
        </div>
      </template>

      <script setup lang="ts">
      import { useAuth0 } from '@auth0/auth0-vue'

      const { user, isAuthenticated, isLoading } = useAuth0()

      const placeholderImage = `data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='100' height='100' viewBox='0 0 100 100'%3E%3Ccircle cx='50' cy='50' r='50' fill='%2363b3ed'/%3E%3Cpath d='M50 45c7.5 0 13.64-6.14 13.64-13.64S57.5 17.72 50 17.72s-13.64 6.14-13.64 13.64S42.5 45 50 45zm0 6.82c-9.09 0-27.28 4.56-27.28 13.64v3.41c0 1.88 1.53 3.41 3.41 3.41h47.74c1.88 0 3.41-1.53 3.41-3.41v-3.41c0-9.08-18.19-13.64-27.28-13.64z' fill='%23fff'/%3E%3C/svg%3E`

      function handleImageError(e: Event) {
        const target = e.target as HTMLImageElement
        target.src = placeholderImage
      }
      </script>

      <style scoped>
      .profile-container {
        display: flex;
        flex-direction: column;
        align-items: center;
        gap: 1rem;
      }

      .profile-picture {
        width: 110px;
        height: 110px;
        border-radius: 50%;
        object-fit: cover;
        border: 3px solid #63b3ed;
        transition: transform 0.3s ease-in-out;
      }

      .profile-picture:hover {
        transform: scale(1.05);
      }

      .profile-info {
        text-align: center;
      }

      .profile-name {
        font-size: 2rem;
        font-weight: 600;
        color: #f7fafc;
        margin-bottom: 0.5rem;
      }

      .profile-email {
        font-size: 1.15rem;
        color: #a0aec0;
      }
      </style>
      ```

      ```vue src/App.vue expandable lines theme={null}
      <template>
        <div class="app-container">
          <div v-if="isLoading" class="loading-state">
            <div class="loading-text">Loading...</div>
          </div>
          
          <div v-else-if="error" class="error-state">
            <div class="error-title">Oops!</div>
            <div class="error-message">Something went wrong</div>
            <div class="error-sub-message">{{ error.message }}</div>
          </div>
          
          <div v-else class="main-card-wrapper">
            <img 
              src="https://cdn.auth0.com/quantum-assets/dist/latest/logos/auth0/auth0-lockup-en-ondark.png" 
              alt="Auth0 Logo" 
              class="auth0-logo"
              @error="handleImageError"
            />
            <h1 class="main-title">Welcome to Vue0</h1>
            
            <div v-if="isAuthenticated" class="logged-in-section">
              <div class="logged-in-message">✅ Successfully authenticated!</div>
              <h2 class="profile-section-title">Your Profile</h2>
              <div class="profile-card">
                <UserProfile />
              </div>
              <LogoutButton />
            </div>
            
            <div v-else class="action-card">
              <p class="action-text">Get started by signing in to your account</p>
              <LoginButton />
            </div>
          </div>
        </div>
      </template>

      <script setup lang="ts">
      import { useAuth0 } from '@auth0/auth0-vue'
      import LoginButton from './components/LoginButton.vue'
      import LogoutButton from './components/LogoutButton.vue'
      import UserProfile from './components/UserProfile.vue'

      const { isAuthenticated, isLoading, error } = useAuth0()

      const handleImageError = (e: Event) => {
        const target = e.target as HTMLImageElement
        target.style.display = 'none'
      }
      </script>

      <style>
      @import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap');

      * {
        margin: 0;
        padding: 0;
        box-sizing: border-box;
      }

      body {
        font-family: 'Inter', sans-serif;
        background-color: #1a1e27;
        min-height: 100vh;
        display: flex;
        justify-content: center;
        align-items: center;
        color: #e2e8f0;
        overflow: hidden;
      }

      #app {
        width: 100%;
        height: 100%;
        display: flex;
        justify-content: center;
        align-items: center;
      }

      .app-container {
        display: flex;
        flex-direction: column;
        justify-content: center;
        align-items: center;
        min-height: 100vh;
        width: 100%;
        padding: 1rem;
      }

      .loading-state, .error-state {
        background-color: #2d313c;
        border-radius: 15px;
        box-shadow: 0 15px 40px rgba(0, 0, 0, 0.4);
        padding: 3rem;
        text-align: center;
      }

      .loading-text {
        font-size: 1.8rem;
        font-weight: 500;
        color: #a0aec0;
        animation: pulse 1.5s infinite ease-in-out;
      }

      .error-state {
        background-color: #c53030;
        color: #fff;
      }

      .error-title {
        font-size: 2.8rem;
        font-weight: 700;
        margin-bottom: 0.5rem;
      }

      .error-message {
        font-size: 1.3rem;
        margin-bottom: 0.5rem;
      }

      .error-sub-message {
        font-size: 1rem;
        opacity: 0.8;
      }

      .main-card-wrapper {
        background-color: #262a33;
        border-radius: 20px;
        box-shadow: 0 20px 60px rgba(0, 0, 0, 0.6), 0 0 0 1px rgba(255, 255, 255, 0.05);
        display: flex;
        flex-direction: column;
        align-items: center;
        gap: 2rem;
        padding: 3rem;
        max-width: 500px;
        width: 90%;
        animation: fadeInScale 0.8s ease-out forwards;
      }

      .auth0-logo {
        width: 160px;
        margin-bottom: 1.5rem;
        opacity: 0;
        animation: slideInDown 1s ease-out forwards 0.2s;
      }

      .main-title {
        font-size: 2.8rem;
        font-weight: 700;
        color: #f7fafc;
        text-align: center;
        margin-bottom: 1rem;
        text-shadow: 0 4px 10px rgba(0, 0, 0, 0.3);
        opacity: 0;
        animation: fadeIn 1s ease-out forwards 0.4s;
      }

      .action-card {
        background-color: #2d313c;
        border-radius: 15px;
        box-shadow: inset 0 2px 5px rgba(0, 0, 0, 0.3), 0 5px 15px rgba(0, 0, 0, 0.3);
        padding: 2.5rem;
        display: flex;
        flex-direction: column;
        align-items: center;
        gap: 1.8rem;
        width: calc(100% - 2rem);
        opacity: 0;
        animation: fadeIn 1s ease-out forwards 0.6s;
      }

      .action-text {
        font-size: 1.25rem;
        color: #cbd5e0;
        text-align: center;
        line-height: 1.6;
        font-weight: 400;
      }

      .button {
        padding: 1.1rem 2.8rem;
        font-size: 1.2rem;
        font-weight: 600;
        border-radius: 10px;
        border: none;
        cursor: pointer;
        transition: all 0.3s cubic-bezier(0.25, 0.8, 0.25, 1);
        box-shadow: 0 8px 20px rgba(0, 0, 0, 0.4);
        text-transform: uppercase;
        letter-spacing: 0.08em;
        outline: none;
      }

      .button:focus {
        box-shadow: 0 0 0 4px rgba(99, 179, 237, 0.5);
      }

      .button:disabled {
        opacity: 0.6;
        cursor: not-allowed;
        transform: none;
      }

      .button.login {
        background-color: #63b3ed;
        color: #1a1e27;
      }

      .button.login:hover:not(:disabled) {
        background-color: #4299e1;
        transform: translateY(-5px) scale(1.03);
        box-shadow: 0 12px 25px rgba(0, 0, 0, 0.5);
      }

      .button.logout {
        background-color: #fc8181;
        color: #1a1e27;
      }

      .button.logout:hover:not(:disabled) {
        background-color: #e53e3e;
        transform: translateY(-5px) scale(1.03);
        box-shadow: 0 12px 25px rgba(0, 0, 0, 0.5);
      }

      .logged-in-section {
        display: flex;
        flex-direction: column;
        align-items: center;
        gap: 1.5rem;
        width: 100%;
      }

      .logged-in-message {
        font-size: 1.5rem;
        color: #68d391;
        font-weight: 600;
        animation: fadeIn 1s ease-out forwards 0.8s;
      }

      .profile-section-title {
        font-size: 2.2rem;
        animation: slideInUp 1s ease-out forwards 1s;
      }

      .profile-card {
        padding: 2.2rem;
        animation: scaleIn 0.8s ease-out forwards 1.2s;
      }

      @keyframes fadeIn {
        from { opacity: 0; }
        to { opacity: 1; }
      }

      @keyframes fadeInScale {
        from { opacity: 0; transform: scale(0.95); }
        to { opacity: 1; transform: scale(1); }
      }

      @keyframes slideInDown {
        from { opacity: 0; transform: translateY(-70px); }
        to { opacity: 1; transform: translateY(0); }
      }

      @keyframes slideInUp {
        from { opacity: 0; transform: translateY(50px); }
        to { opacity: 1; transform: translateY(0); }
      }

      @keyframes pulse {
        0%, 100% { opacity: 1; }
        50% { opacity: 0.6; }
      }

      @keyframes scaleIn {
        from { opacity: 0; transform: scale(0.8); }
        to { opacity: 1; transform: scale(1); }
      }

      @media (max-width: 600px) {
        .main-card-wrapper {
          padding: 2rem;
          margin: 1rem;
        }
        
        .main-title {
          font-size: 2.2rem;
        }
        
        .button {
          padding: 1rem 2rem;
          font-size: 1.1rem;
        }
        
        .auth0-logo {
          width: 120px;
        }
      }
      </style>
      ```
    </AuthCodeGroup>
  </Step>

  <Step title="Run your app">
    ```shellscript theme={null}
    npm run dev
    ```

    <Info>
      If port 5173 is in use, run: `npm run dev -- --port 5174` and update your Auth0 app's callback URLs to `http://localhost:5174`
    </Info>
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a fully functional Auth0 login page running on your [localhost](http://localhost:5173/)
</Check>

***

## Advanced Usage

<Accordion title="Protecting Routes with Vue Router">
  Use Vue Router's navigation guards to protect specific routes:

  ```typescript src/router/index.ts theme={null}
  import { createRouter, createWebHistory } from 'vue-router'
  import { authGuard } from '@auth0/auth0-vue'
  import Home from '../views/Home.vue'
  import Profile from '../views/Profile.vue'
  import Dashboard from '../views/Dashboard.vue'

  const routes = [
    {
      path: '/',
      name: 'Home',
      component: Home
    },
    {
      path: '/profile',
      name: 'Profile',
      component: Profile,
      beforeEnter: authGuard
    },
    {
      path: '/dashboard',
      name: 'Dashboard',
      component: Dashboard,
      beforeEnter: authGuard
    }
  ]

  const router = createRouter({
    history: createWebHistory(),
    routes
  })

  export default router
  ```
</Accordion>

<Accordion title="Calling Protected APIs">
  Configure your Auth0 plugin to include an API audience and make authenticated requests:

  ```typescript src/main.ts theme={null}
  import { createAuth0 } from '@auth0/auth0-vue'

  const app = createApp(App)

  app.use(
    createAuth0({
      domain: import.meta.env.VITE_AUTH0_DOMAIN,
      clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
      authorizationParams: {
        redirect_uri: window.location.origin,
        audience: "YOUR_API_IDENTIFIER"
      }
    })
  )
  ```

  Then make authenticated API calls in your components:

  ```vue src/components/ApiCall.vue theme={null}
  <template>
    <div>
      <button @click="callProtectedApi" :disabled="isLoading">
        Call Protected API
      </button>
      <pre v-if="apiResponse">{{ JSON.stringify(apiResponse, null, 2) }}</pre>
    </div>
  </template>

  <script setup lang="ts">
  import { ref } from 'vue'
  import { useAuth0 } from '@auth0/auth0-vue'

  const { getAccessTokenSilently } = useAuth0()
  const apiResponse = ref(null)
  const isLoading = ref(false)

  const callProtectedApi = async () => {
    try {
      isLoading.value = true
      const token = await getAccessTokenSilently()
      
      const response = await fetch('/api/protected', {
        headers: {
          Authorization: `Bearer ${token}`
        }
      })
      
      apiResponse.value = await response.json()
    } catch (error) {
      console.error('API call failed:', error)
    } finally {
      isLoading.value = false
    }
  }
  </script>
  ```
</Accordion>

<Accordion title="Using Composables for Authentication Logic">
  Create reusable composables for common authentication patterns:

  ```typescript src/composables/useAuthenticatedUser.ts theme={null}
  import { computed, ref, watchEffect } from 'vue'
  import { useAuth0 } from '@auth0/auth0-vue'

  export function useAuthenticatedUser() {
    const { user, isAuthenticated, isLoading, getAccessTokenSilently } = useAuth0()
    const accessToken = ref<string | null>(null)

    watchEffect(async () => {
      if (isAuthenticated.value && !isLoading.value) {
        try {
          accessToken.value = await getAccessTokenSilently()
        } catch (error) {
          console.error('Failed to get access token:', error)
        }
      }
    })

    return {
      user: computed(() => user.value),
      accessToken: computed(() => accessToken.value),
      isAuthenticated: computed(() => isAuthenticated.value),
      isLoading: computed(() => isLoading.value)
    }
  }
  ```

  Usage in components:

  ```vue src/components/UserDashboard.vue theme={null}
  <template>
    <div v-if="!isLoading">
      <h1>Welcome, {{ user?.name }}</h1>
      <p>Access Token: {{ accessToken ? 'Available' : 'Not available' }}</p>
    </div>
    <div v-else>Loading...</div>
  </template>

  <script setup lang="ts">
  import { useAuthenticatedUser } from '../composables/useAuthenticatedUser'

  const { user, accessToken, isLoading } = useAuthenticatedUser()
  </script>
  ```
</Accordion>


# Apache
Source: https://auth0.com/docs/quickstart/webapp/apache/interactive

This tutorial demonstrates how to configure Apache to add authentication and authorization to your web app.

<Recipe>
  <Content>
    This tutorial demonstrates how to configure Apache to add authentication and authorization to your web app. We recommend that you log in to follow this quickstart with examples configured for your account.

    <Section title={sections[0].title}>
      This tutorial and sample project have been tested with the following:

      * Apache 2.4
    </Section>

    <Section title={sections[1].title}>
      First, install the `mod_auth_openidc` module for Apache.

      You can get the binaries from [GitHub](https://github.com/zmartzone/mod_auth_openidc/releases) and install them for your OS. If your OS isn't compatible with any of the binaries, you can still [build it from source](https://github.com/zmartzone/mod_auth_openidc/blob/master/INSTALL).

      Once you've installed the module, enable it for Apache with the `a2enmod` command. To learn more, read [a2enmod on Ubuntu Manpage](https://manpages.ubuntu.com/manpages/focal/man8/a2enmod.8.html):

      ```text lines theme={null}
      a2enmod auth_openidc
      ```

      <Info>
        For Windows, you can use [this Powershell script](https://github.com/enderandpeter/win-a2enmod#installation) to get `a2enmod` working on your system.
      </Info>
    </Section>

    <Section title={sections[2].title}>
      Update your new configuration file (`auth_openidc.conf`), located in the `/etc/apache2/mods-available` folder.

      <Info>
        For Windows, you must use the `/apache/conf/httpd.conf` file.
      </Info>
    </Section>

    <Section title={sections[3].title}>
      In the Auth0 Dashboard:

      1. Go to **Applications** > **Applications**, and then select your application from the list.
      2. Switch to the **Settings** view, and then locate the **Application URIs** section.
      3. Add the value of `OIDCRedirectURI` to **Allowed Callback URLs**.
      4. Locate **Advanced Settings** at the bottom of the page.
      5. Switch to the **OAuth** view.
      6. Set **JSON Web Token (JWT) Signature Algorithm** to `RS256`.
    </Section>

    <Section title={sections[4].title}>
      You can configure Apache to protect a specific location based on the value of a claim in the user’s ID token by adding a `Location` block to your `auth_openidc.conf` file.

      For example, you could create an Action that reads the user’s roles, and then adds a claim that grants access to a protected location:

      ```js lines theme={null}
      exports.onExecutePostLogin = async (event, api) => {
        const roles = event.authorization.roles; // ['user', 'admin']
          if (roles.includes('admin')) {
          api.idToken.setCustomClaim('folder', 'admin');
        }
      };
      ```
    </Section>

    ## Next Steps

    Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.

    This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:

    * [Auth0 Dashboard](https://manage.auth0.com/) - Learn how to configure and manage your Auth0 tenant and applications

    * [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
  </Content>

  <SideMenu>
    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```conf auth_openidc.conf highlight={1-12} lines theme={null}
        OIDCProviderMetadataURL https://{yourDomain}/.well-known/openid-configuration OIDCClientID {yourClientId} 
        OIDCClientSecret {yourClientSecret}
        OIDCScope "openid name email" 
        OIDCRedirectURI https://your_apache_server/your_path/redirect_uri/ OIDCCryptoPassphrase <passwordToEncryptTheSessionInformationOnTheCookie> 

        <Location /your_path> 
          AuthType openid-connect 
          Require valid-user 
          LogLevel debug 
        </Location>

        <Location /admin> 
          AuthType openid-connect 
          #Require valid-user 
          Require claim folder:admin 
        </Location>
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```conf auth_openidc.conf highlight={13-16} lines theme={null}
        OIDCProviderMetadataURL https://{yourDomain}/.well-known/openid-configuration OIDCClientID {yourClientId} 
        OIDCClientSecret {yourClientSecret}
        OIDCScope "openid name email" 
        OIDCRedirectURI https://your_apache_server/your_path/redirect_uri/ OIDCCryptoPassphrase <passwordToEncryptTheSessionInformationOnTheCookie> 

        <Location /your_path> 
          AuthType openid-connect 
          Require valid-user 
          LogLevel debug 
        </Location>

        <Location /admin> 
          AuthType openid-connect 
          #Require valid-user 
          Require claim folder:admin 
        </Location>
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>
  </SideMenu>
</Recipe>


# Add Login to Your Blazor Server Application
Source: https://auth0.com/docs/quickstart/webapp/aspnet-core-blazor-server/index

This guide demonstrates how to integrate Auth0 with any new or existing Blazor Server application using the Auth0.AspNetCore.Authentication SDK.

<Accordion title="AI Prompt" icon="microchip-ai">
  **Using AI to integrate Auth0?** Add this prompt to Cursor, Windsurf, Copilot, Claude Code or your favourite AI-powered IDE to speed up development.

  ```markdown expandable theme={null}
  Integrate Auth0 authentication into a Blazor Server web application

  AI PERSONA & PRIMARY OBJECTIVE
  You are a helpful Auth0 SDK Integration Assistant for Blazor Server. Your primary function is to execute commands to set up a development environment for Auth0 in a Blazor Server web application. Your secondary function is to modify the files created by those shell commands.

  CRITICAL BEHAVIORAL INSTRUCTIONS
  1. CHECK EXISTING PROJECT FIRST: Before creating a new project, check if the current directory already contains a Blazor Server project (*.csproj file). If it does, skip project creation and work with the existing project.
  2. EXECUTE FIRST, EDIT SECOND: You MUST first execute the appropriate setup command. Do not show, suggest, or create any files until the setup is complete.
  3. NO PLANNING: DO NOT propose a directory structure. DO NOT show a file tree. Your first action must be to run the appropriate command.
  4. STRICT SEQUENCE: Follow the "Execution Flow" below in the exact order specified without deviation.

  EXECUTION FLOW

  Step 1: Check for Existing .NET Project and Prerequisites

  FIRST, verify prerequisites and check for existing project:

    # Check if .NET SDK is available
    dotnet --version

  Then examine the current directory:

    # Check for existing .NET project
    if ls *.csproj 1> /dev/null 2>&1; then
      echo "Found .csproj file, checking project type..."
      ls *.csproj
    else
      echo "No .csproj found, will create new project"
    fi

  Based on the results:
  - If a *.csproj exists and contains Blazor Server references, proceed to Step 1b (install Auth0 SDK only)
  - If no .NET project exists, proceed to Step 1a (create new project)

  Step 1a: Create New Blazor Server Project and Install the SDK
  If an existing Blazor Server project exists, simply install the SDK:

    dotnet add package Auth0.AspNetCore.Authentication

  Otherwise, create a new project and install the SDK:

    dotnet new blazor -n SampleBlazorApp --interactivity Server && cd SampleBlazorApp && dotnet add package Auth0.AspNetCore.Authentication

  Step 2: Setup Auth0 Application Configuration

  Create or update appsettings.json with Auth0 configuration. First, backup existing file if present:

    # Backup existing appsettings.json if it exists
    if [ -f "appsettings.json" ]; then
      cp appsettings.json appsettings.json.backup
    fi

  Then update appsettings.json to include Auth0 configuration:

  For MacOS:

    APP_NAME="My Blazor App" && brew tap auth0/auth0-cli && brew install auth0 && auth0 login --no-input && auth0 apps create --name "${APP_NAME}" --type regular --auth-method post --callbacks http://localhost:5000/callback --logout-urls http://localhost:5000/ --web-origins http://localhost:5000 --reveal-secrets --json --metadata created_by="quickstart-docs-manual" > auth0-app-details.json && CLIENT_ID=$(jq -r '.client_id' auth0-app-details.json) && CLIENT_SECRET=$(jq -r '.client_secret' auth0-app-details.json) && DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name') && rm auth0-app-details.json && cat > appsettings.json << EOF
  {
    "Logging": {
      "LogLevel": {
        "Default": "Information",
        "Microsoft.AspNetCore": "Warning"
      }
    },
    "AllowedHosts": "*",
    "Auth0": {
      "Domain": "${DOMAIN}",
      "ClientId": "${CLIENT_ID}",
      "ClientSecret": "${CLIENT_SECRET}"
    }
  }
  EOF
  echo "appsettings.json created with your Auth0 details:" && cat appsettings.json

  For Windows:

    $AppName = "My Blazor App"; winget install Auth0.CLI; auth0 login --no-input; $AppDetails = auth0 apps create --name "$AppName" --type regular --auth-method post --callbacks http://localhost:5000/callback --logout-urls http://localhost:5000/ --web-origins http://localhost:5000 --reveal-secrets --json --metadata created_by="quickstart-docs-manual" | ConvertFrom-Json; $ClientId = $AppDetails.client_id; $ClientSecret = $AppDetails.client_secret; $Domain = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name; $Config = @{ Logging = @{ LogLevel = @{ Default = "Information"; "Microsoft.AspNetCore" = "Warning" } }; AllowedHosts = "*"; Auth0 = @{ Domain = $Domain; ClientId = $ClientId; ClientSecret = $ClientSecret } } | ConvertTo-Json -Depth 10; Set-Content -Path appsettings.json -Value $Config; Write-Output "appsettings.json created with your Auth0 details:"; Get-Content appsettings.json

  If automatic setup fails, create manual configuration:

    cat > appsettings.json << 'EOF'
  {
    "Logging": {
      "LogLevel": {
        "Default": "Information",
        "Microsoft.AspNetCore": "Warning"
      }
    },
    "AllowedHosts": "*",
    "Auth0": {
      "Domain": "your-tenant.auth0.com",
      "ClientId": "YOUR_CLIENT_ID",
      "ClientSecret": "YOUR_CLIENT_SECRET"
    }
  }
  EOF

  And display manual setup instructions:

    echo "📋 MANUAL SETUP REQUIRED:"
    echo "1. Go to https://manage.auth0.com/dashboard/"
    echo "2. Navigate to Applications → Applications"
    echo "3. Click 'Create Application'"
    echo "4. Set Name: 'My Blazor App'"
    echo "5. Select 'Regular Web Applications'"
    echo "6. In Settings, set Allowed Callback URLs: http://localhost:5000/callback"
    echo "7. Set Allowed Logout URLs: http://localhost:5000/"
    echo "8. Set Allowed Web Origins: http://localhost:5000"
    echo "9. Update appsettings.json with your Domain, Client ID, and Client Secret"

  Step 3: Update Program.cs

  Replace the entire contents of Program.cs with:

    using Auth0.AspNetCore.Authentication;
    using SampleBlazorApp.Components;
    
    var builder = WebApplication.CreateBuilder(args);
    
    // Add Auth0 authentication
    builder.Services.AddAuth0WebAppAuthentication(options =>
    {
        options.Domain = builder.Configuration["Auth0:Domain"];
        options.ClientId = builder.Configuration["Auth0:ClientId"];
        options.ClientSecret = builder.Configuration["Auth0:ClientSecret"];
    });
    
    // Add Razor Components and Blazor Server
    builder.Services.AddRazorComponents()
        .AddInteractiveServerComponents();
    
    // Add cascading authentication state
    builder.Services.AddCascadingAuthenticationState();
    
    // Add Razor Pages for authentication endpoints
    builder.Services.AddRazorPages();
    
    var app = builder.Build();
    
    if (!app.Environment.IsDevelopment())
    {
        app.UseExceptionHandler("/Error", createScopeForErrors: true);
        app.UseHsts();
    }
    
    app.UseHttpsRedirection();
    app.UseAntiforgery();
    
    app.UseAuthentication();
    app.UseAuthorization();
    
    app.MapStaticAssets();
    app.MapRazorComponents<App>()
        .AddInteractiveServerRenderMode();
    
    // Map Razor Pages for authentication
    app.MapRazorPages();
    
    app.Run();

  Step 4: Create Login and Logout Pages

  Create the Pages folder and necessary files:

    mkdir -p Pages
    touch Pages/Login.cshtml Pages/Login.cshtml.cs Pages/Logout.cshtml Pages/Logout.cshtml.cs Pages/_ViewImports.razor

  Create Pages/Login.cshtml:

    @page
    @model LoginModel

  Create Pages/Login.cshtml.cs:

    using Auth0.AspNetCore.Authentication;
    using Microsoft.AspNetCore.Authentication;
    using Microsoft.AspNetCore.Mvc.RazorPages;
    
    namespace SampleBlazorApp.Pages
    {
        public class LoginModel : PageModel
        {
            public async Task OnGet(string redirectUri = "/")
            {
                var authenticationProperties = new LoginAuthenticationPropertiesBuilder()
                    .WithRedirectUri(redirectUri)
                    .Build();
    
                await HttpContext.ChallengeAsync(
                    Auth0Constants.AuthenticationScheme,
                    authenticationProperties);
            }
        }
    }

  Create Pages/Logout.cshtml:

    @page
    @using Microsoft.AspNetCore.Authorization
    @attribute [Authorize]
    @model LogoutModel

  Create Pages/Logout.cshtml.cs:

    using Auth0.AspNetCore.Authentication;
    using Microsoft.AspNetCore.Authentication;
    using Microsoft.AspNetCore.Authentication.Cookies;
    using Microsoft.AspNetCore.Authorization;
    using Microsoft.AspNetCore.Mvc.RazorPages;
    
    namespace SampleBlazorApp.Pages
    {
        [Authorize]
        public class LogoutModel : PageModel
        {
            public async Task OnGet()
            {
                var authenticationProperties = new LogoutAuthenticationPropertiesBuilder()
                    .WithRedirectUri("/")
                    .Build();
    
                await HttpContext.SignOutAsync(
                    Auth0Constants.AuthenticationScheme,
                    authenticationProperties);
                    
                await HttpContext.SignOutAsync(
                    CookieAuthenticationDefaults.AuthenticationScheme);
            }
        }
    }

  Create Components/_Imports.razor (add authentication imports):

    @using System.Security.Claims
    @using Microsoft.AspNetCore.Authorization
    @using Microsoft.AspNetCore.Components.Authorization

  Create Pages/_ViewImports.razor (for Razor Pages):

    @using SampleBlazorApp.Pages
    @namespace SampleBlazorApp.Pages
    @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

  Step 5: Create Profile Page and Update Layout

  Create Components/Pages/Profile.razor:

    @page "/profile"
    @attribute [Authorize]
    
    <PageTitle>User Profile</PageTitle>
    
    <AuthorizeView>
        <Authorized>
            <div class="profile-container">
                <img src="@context.User.FindFirst("picture")?.Value" 
                     alt="Profile picture" 
                     class="profile-picture" />
                
                <h3>Welcome, @context.User.Identity?.Name!</h3>
                
                <div class="profile-details">
                    <p><strong>Email:</strong> @context.User.FindFirst("email")?.Value</p>
                    <p><strong>Email Verified:</strong> @context.User.FindFirst("email_verified")?.Value</p>
                    <p><strong>Auth0 User ID:</strong> @context.User.FindFirst(ClaimTypes.NameIdentifier)?.Value</p>
                </div>
    
                <h4>All Claims:</h4>
                <table class="table">
                    <thead>
                        <tr>
                            <th>Claim Type</th>
                            <th>Claim Value</th>
                        </tr>
                    </thead>
                    <tbody>
                        @foreach (var claim in context.User.Claims)
                        {
                            <tr>
                                <td>@claim.Type</td>
                                <td>@claim.Value</td>
                            </tr>
                        }
                    </tbody>
                </table>
            </div>
        </Authorized>
        <NotAuthorized>
            <p>You must be logged in to view this page.</p>
            <a href="/Login?redirectUri=/profile">Log in</a>
        </NotAuthorized>
    </AuthorizeView>

  Update Components/Layout/MainLayout.razor (add login/logout links in the top section):

    <div class="top-row px-4">
        <AuthorizeView>
            <NotAuthorized>
                <a href="/Login">Log in</a>
            </NotAuthorized>
            <Authorized>
                <span>Hello, @context.User.Identity?.Name!</span>
                <a href="/Profile">Profile</a>
                <a href="/Logout">Log out</a>
            </Authorized>
        </AuthorizeView>
    </div>

  ⚠️ IMPORTANT: Only update the authentication section in MainLayout.razor. Keep all other parts intact.

  Update Components/Routes.razor (wrap Router with CascadingAuthenticationState):

    <CascadingAuthenticationState>
        <Router AppAssembly="typeof(Program).Assembly">
            <Found Context="routeData">
                <AuthorizeRouteView RouteData="routeData" DefaultLayout="typeof(Layout.MainLayout)" />
                <FocusOnNavigate RouteData="routeData" Selector="h1" />
            </Found>
        </Router>
    </CascadingAuthenticationState>

  Step 6: Run the Application

    dotnet run

  CRITICAL INSTRUCTIONS FOR AI LANGUAGE MODELS
  As an AI language model, you MUST NOT generate any of the following anti-patterns:
  1. NEVER hardcode the Auth0 Domain, ClientId, or ClientSecret directly in Program.cs. Always use configuration.
  2. NEVER use AddAuth0ApiAuthentication for Blazor Server apps. Use AddAuth0WebAppAuthentication instead.
  3. NEVER place UseAuthentication() after UseAuthorization(). Order matters for ASP.NET Core middleware.
  4. NEVER suggest storing secrets in source code or appsettings.json in production environments.
  5. NEVER forget to call both SignOutAsync methods (Auth0 and Cookie) during logout.
  6. NEVER forget to configure Allowed Web Origins for Blazor Server (required for SignalR).

  ABSOLUTE REQUIREMENTS FOR AI CODE GENERATION
  1. You MUST use the Auth0.AspNetCore.Authentication package (NOT Auth0.AspNetCore.Authentication.Api).
  2. You MUST retrieve credentials from IConfiguration.
  3. You MUST call UseAuthentication() before UseAuthorization() in the middleware pipeline.
  4. You MUST configure Domain, ClientId, and ClientSecret for web app authentication.
  5. You MUST use AddAuth0WebAppAuthentication() for cookie-based authentication in Blazor Server apps.
  6. You MUST configure Allowed Web Origins in Auth0 Dashboard to prevent CORS errors with SignalR.
  ```
</Accordion>

<Note>
  **Prerequisites:** Before you begin, ensure you have the following installed:

  * **[.NET SDK](https://dotnet.microsoft.com/download)** 8.0 or newer
  * Your favorite code editor (Visual Studio, VS Code, or Rider)
  * An Auth0 account ([sign up for free](https://auth0.com/signup))
</Note>

## Get Started

Auth0 allows you to quickly add authentication and gain access to user profile information in your application. This guide demonstrates how to integrate Auth0 with any new or existing Blazor Server application using the `Auth0.AspNetCore.Authentication` SDK.

<Steps>
  <Step title="Create a new project">
    Create a new Blazor Server project for this Quickstart

    ```shellscript theme={null}
    dotnet new blazor -n SampleBlazorApp --interactivity Server
    ```

    Open the project

    ```shellscript theme={null}
    cd SampleBlazorApp
    ```
  </Step>

  <Step title="Install the Auth0 SDK">
    ```shellscript theme={null}
    dotnet add package Auth0.AspNetCore.Authentication
    ```
  </Step>

  <Step title="Setup your Auth0 Application">
    Next up, you need to create a new Application on your Auth0 tenant and add the configuration to your project.

    You can choose to do this automatically by running a CLI command or do it manually via the Dashboard:

    <Tabs>
      <Tab title="CLI">
        Run the following shell command on your project's root directory to create an Auth0 Application and update your `appsettings.json`:

        <Tabs>
          <Tab title="Mac/Linux">
            ```shellscript theme={null}
            AUTH0_APP_NAME="My Blazor App" && brew tap auth0/auth0-cli && brew install auth0 && auth0 login --no-input && auth0 apps create -n "${AUTH0_APP_NAME}" -t regular -c http://localhost:5000/callback -l http://localhost:5000 -o http://localhost:5000 --reveal-secrets --json --metadata created_by="quickstart-docs-manual" > auth0-app-details.json && CLIENT_ID=$(jq -r '.client_id' auth0-app-details.json) && CLIENT_SECRET=$(jq -r '.client_secret' auth0-app-details.json) && DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name') && rm auth0-app-details.json && cat > appsettings.json << EOF
            {
              "Logging": {
                "LogLevel": {
                  "Default": "Information",
                  "Microsoft.AspNetCore": "Warning"
                }
              },
              "AllowedHosts": "*",
              "Auth0": {
                "Domain": "${DOMAIN}",
                "ClientId": "${CLIENT_ID}",
                "ClientSecret": "${CLIENT_SECRET}"
              }
            }
            EOF
            echo "appsettings.json created with your Auth0 details:" && cat appsettings.json
            ```
          </Tab>

          <Tab title="Windows (PowerShell)">
            ```powershell theme={null}
            $AUTH0_APP_NAME = "My Blazor App"
            $latestRelease = Invoke-RestMethod -Uri "https://api.github.com/repos/auth0/auth0-cli/releases/latest"
            $latestVersion = $latestRelease.tag_name
            $version = $latestVersion -replace "^v"
            Invoke-WebRequest -Uri "https://github.com/auth0/auth0-cli/releases/download/${latestVersion}/auth0-cli_${version}_Windows_x86_64.zip" -OutFile ".\auth0.zip"
            Expand-Archive ".\auth0.zip" .\
            [System.Environment]::SetEnvironmentVariable('PATH', $Env:PATH + ";${pwd}")
            auth0 login --no-input
            auth0 apps create -n "${AUTH0_APP_NAME}" -t regular -c http://localhost:5000/callback -l http://localhost:5000 -o http://localhost:5000 --reveal-secrets --json --metadata created_by="quickstart-docs-manual" | Set-Content -Path auth0-app-details.json
            $AppDetails = Get-Content -Raw auth0-app-details.json | ConvertFrom-Json
            $ClientId = $AppDetails.client_id
            $ClientSecret = $AppDetails.client_secret
            $Domain = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name
            $Config = Get-Content -Raw appsettings.json | ConvertFrom-Json
            if (-not $Config.Auth0) { $Config | Add-Member -MemberType NoteProperty -Name Auth0 -Value @{} }
            $Config.Auth0.Domain = $Domain
            $Config.Auth0.ClientId = $ClientId
            $Config.Auth0.ClientSecret = $ClientSecret
            $Config | ConvertTo-Json -Depth 10 | Set-Content appsettings.json
            Remove-Item auth0-app-details.json
            Write-Output "✅ appsettings.json updated with your Auth0 details:"
            Get-Content appsettings.json
            ```
          </Tab>
        </Tabs>
      </Tab>

      <Tab title="Dashboard">
        Before you start, create or update `appsettings.json` on your project's root directory

        ```json appsettings.json theme={null}
        {
          "Logging": {
            "LogLevel": {
              "Default": "Information",
              "Microsoft.AspNetCore": "Warning"
            }
          },
          "AllowedHosts": "*",
          "Auth0": {
            "Domain": "YOUR_AUTH0_DOMAIN",
            "ClientId": "YOUR_CLIENT_ID",
            "ClientSecret": "YOUR_CLIENT_SECRET"
          }
        }
        ```

        1. Go to the [Auth0 Dashboard](https://manage.auth0.com/dashboard/)
        2. Click **Applications → Applications → Create Application**
        3. Enter a name for your application (e.g., "My Blazor App")
        4. Select **Regular Web Application** as the application type
        5. Click **Create**
        6. Go to the **Settings** tab
        7. Replace `YOUR_AUTH0_DOMAIN`, `YOUR_CLIENT_ID`, and `YOUR_CLIENT_SECRET` in the `appsettings.json` file with the **Domain**, **Client ID**, and **Client Secret** values from the dashboard
      </Tab>
    </Tabs>

    **Configure Callback URLs:**

    In the **Settings** tab, configure the following URLs:

    * **Allowed Callback URLs**: `http://localhost:5000/callback`
    * **Allowed Logout URLs**: `http://localhost:5000`
    * **Allowed Web Origins**: `http://localhost:5000`

    Click **Save Changes**

    <Info>
      **Important:** Make sure to [setup connections](https://auth0.com/docs/get-started/applications/set-up-database-connections) and enable them for your application in the Auth0 Dashboard under the **Connections** tab.
    </Info>
  </Step>

  <Step title="Configure authentication">
    Update your `Program.cs` to configure Auth0 authentication:

    ```csharp Program.cs lines theme={null}
    using Auth0.AspNetCore.Authentication;
    using SampleBlazorApp.Components;

    var builder = WebApplication.CreateBuilder(args);

    // Add Auth0 authentication
    builder.Services.AddAuth0WebAppAuthentication(options =>
    {
        options.Domain = builder.Configuration["Auth0:Domain"];
        options.ClientId = builder.Configuration["Auth0:ClientId"];
        options.ClientSecret = builder.Configuration["Auth0:ClientSecret"];
    });

    // Add Razor Components and Blazor Server
    builder.Services.AddRazorComponents()
        .AddInteractiveServerComponents();

    // Add cascading authentication state
    builder.Services.AddCascadingAuthenticationState();

    // Add Razor Pages for authentication endpoints
    builder.Services.AddRazorPages();

    var app = builder.Build();

    if (!app.Environment.IsDevelopment())
    {
        app.UseExceptionHandler("/Error", createScopeForErrors: true);
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseAntiforgery();

    app.UseAuthentication();
    app.UseAuthorization();

    app.MapStaticAssets();
    app.MapRazorComponents<App>()
        .AddInteractiveServerRenderMode();

    // Map Razor Pages for authentication
    app.MapRazorPages();

    app.Run();
    ```

    <Info>
      **Note:** The order of middleware is important. `UseAuthentication()` must be called before `UseAuthorization()`.
    </Info>
  </Step>

  <Step title="Add Login and Logout pages">
    Create Login and Logout pages to allow users to authenticate.

    First, create the `Pages` folder and files:

    <Tabs>
      <Tab title="Mac/Linux">
        ```shellscript theme={null}
        mkdir -p Pages && touch Pages/Login.cshtml Pages/Login.cshtml.cs Pages/Logout.cshtml Pages/Logout.cshtml.cs Pages/_ViewImports.razor
        ```
      </Tab>

      <Tab title="Windows (PowerShell)">
        ```powershell theme={null}
        New-Item -ItemType Directory -Force -Path Pages; New-Item -ItemType File -Force -Path Pages/Login.cshtml, Pages/Login.cshtml.cs, Pages/Logout.cshtml, Pages/Logout.cshtml.cs, Pages/_ViewImports.razor
        ```
      </Tab>
    </Tabs>

    And add the following code snippets:

    <AuthCodeGroup>
      ```razor Pages/Login.cshtml lines theme={null}
      @page
      @model LoginModel
      ```

      ```csharp Pages/Login.cshtml.cs lines theme={null}
      using Auth0.AspNetCore.Authentication;
      using Microsoft.AspNetCore.Authentication;
      using Microsoft.AspNetCore.Mvc.RazorPages;

      namespace SampleBlazorApp.Pages
      {
          public class LoginModel : PageModel
          {
              public async Task OnGet(string redirectUri = "/")
              {
                  var authenticationProperties = new LoginAuthenticationPropertiesBuilder()
                      .WithRedirectUri(redirectUri)
                      .Build();

                  await HttpContext.ChallengeAsync(
                      Auth0Constants.AuthenticationScheme,
                      authenticationProperties);
              }
          }
      }
      ```

      ```razor Pages/Logout.cshtml lines theme={null}
      @page
      @using Microsoft.AspNetCore.Authorization
      @attribute [Authorize]
      @model LogoutModel
      ```

      ```csharp Pages/Logout.cshtml.cs lines theme={null}
      using Auth0.AspNetCore.Authentication;
      using Microsoft.AspNetCore.Authentication;
      using Microsoft.AspNetCore.Authentication.Cookies;
      using Microsoft.AspNetCore.Authorization;
      using Microsoft.AspNetCore.Mvc.RazorPages;

      namespace SampleBlazorApp.Pages
      {
          [Authorize]
          public class LogoutModel : PageModel
          {
              public async Task OnGet()
              {
                  var authenticationProperties = new LogoutAuthenticationPropertiesBuilder()
                      .WithRedirectUri("/")
                      .Build();

                  await HttpContext.SignOutAsync(
                      Auth0Constants.AuthenticationScheme,
                      authenticationProperties);
                      
                  await HttpContext.SignOutAsync(
                      CookieAuthenticationDefaults.AuthenticationScheme);
              }
          }
      }
      ```

      ```razor Components/_Imports.razor lines theme={null}
      @using System.Security.Claims
      @using Microsoft.AspNetCore.Authorization
      @using Microsoft.AspNetCore.Components.Authorization
      ```

      ```razor Pages/_ViewImports.razor lines theme={null}
      @using SampleBlazorApp.Pages
      @namespace SampleBlazorApp.Pages
      @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
      ```
    </AuthCodeGroup>
  </Step>

  <Step title="Create Profile page and Update Layout">
    Create a custom user profile page for displaying the user's name and claims, and update the layout to add login/logout links.

    First, create the Profile component:

    <Tabs>
      <Tab title="Mac/Linux">
        ```shellscript theme={null}
        touch Components/Pages/Profile.razor
        ```
      </Tab>

      <Tab title="Windows (PowerShell)">
        ```powershell theme={null}
        New-Item -ItemType File -Force -Path Components/Pages/Profile.razor
        ```
      </Tab>
    </Tabs>

    Add the following code snippets, note to add the `MainLayout` code to the top section of your layout, keeping all other parts intact.

    <AuthCodeGroup>
      ```razor Components/Pages/Profile.razor expandable lines theme={null}
      @page "/profile"
      @attribute [Authorize]

      <PageTitle>User Profile</PageTitle>

      <AuthorizeView>
          <Authorized>
              <div class="profile-container">
                  <img src="@context.User.FindFirst("picture")?.Value" 
                       alt="Profile picture" 
                       class="profile-picture" />
                  
                  <h3>Welcome, @context.User.Identity?.Name!</h3>
                  
                  <div class="profile-details">
                      <p><strong>Email:</strong> @context.User.FindFirst("email")?.Value</p>
                      <p><strong>Email Verified:</strong> @context.User.FindFirst("email_verified")?.Value</p>
                      <p><strong>Auth0 User ID:</strong> @context.User.FindFirst(ClaimTypes.NameIdentifier)?.Value</p>
                  </div>

                  <h4>All Claims:</h4>
                  <table class="table">
                      <thead>
                          <tr>
                              <th>Claim Type</th>
                              <th>Claim Value</th>
                          </tr>
                      </thead>
                      <tbody>
                          @foreach (var claim in context.User.Claims)
                          {
                              <tr>
                                  <td>@claim.Type</td>
                                  <td>@claim.Value</td>
                              </tr>
                          }
                      </tbody>
                  </table>
              </div>
          </Authorized>
          <NotAuthorized>
              <p>You must be logged in to view this page.</p>
              <a href="/Login?redirectUri=/profile">Log in</a>
          </NotAuthorized>
      </AuthorizeView>
      ```

      ```razor Components/Layout/MainLayout.razor lines theme={null}
      <div class="top-row px-4">
          <AuthorizeView>
              <NotAuthorized>
                  <a href="/Login">Log in</a>
              </NotAuthorized>
              <Authorized>
                  <span>Hello, @context.User.Identity?.Name!</span>
                  <a href="/Profile">Profile</a>
                  <a href="/Logout">Log out</a>
              </Authorized>
          </AuthorizeView>
      </div>
      ```

      ```razor Components/Routes.razor lines theme={null}
      <CascadingAuthenticationState>
          <Router AppAssembly="typeof(Program).Assembly" NotFoundPage="typeof(Pages.NotFound)">
              <Found Context="routeData">
                  <AuthorizeRouteView RouteData="routeData" DefaultLayout="typeof(Layout.MainLayout)" />
                  <FocusOnNavigate RouteData="routeData" Selector="h1" />
              </Found>
          </Router>
      </CascadingAuthenticationState>
      ```
    </AuthCodeGroup>
  </Step>

  <Step title="Run your application">
    ```shellscript theme={null}
    dotnet run
    ```

    Your application should start and display the URL it's listening on:

    ```
    info: Microsoft.Hosting.Lifetime[14]
          Now listening on: http://localhost:5000
    ```

    Open your browser and navigate to `http://localhost:5000`. Click the **Login** link in the navigation. You'll be redirected to Auth0's login page.
    After logging in, you'll be redirected back to your application, and you should see your name in the navigation.
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a fully functional Auth0-protected Blazor Server application running on [http://localhost:5000](http://localhost:5000). Users can log in, view their profile, and log out.
</Check>

***

## Advanced Usage

<Accordion title="Customize Login Parameters">
  You can pass custom parameters to the Auth0 login page:

  ```csharp Pages/Login.cshtml.cs theme={null}
  public async Task OnGet(string redirectUri = "/")
  {
      var authenticationProperties = new LoginAuthenticationPropertiesBuilder()
          .WithRedirectUri(redirectUri)
          .WithParameter("screen_hint", "signup")  // Show signup page
          .WithParameter("ui_locales", "es")       // Set language to Spanish
          .Build();

      await HttpContext.ChallengeAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);
  }
  ```
</Accordion>

<Accordion title="Store Tokens for API Calls">
  If you need to call external APIs on behalf of the user, you can retrieve and store tokens:

  ```csharp Program.cs theme={null}
  builder.Services.AddAuth0WebAppAuthentication(options =>
  {
      options.Domain = builder.Configuration["Auth0:Domain"];
      options.ClientId = builder.Configuration["Auth0:ClientId"];
      options.ClientSecret = builder.Configuration["Auth0:ClientSecret"];
  })
  .WithAccessToken(options =>
  {
      options.Audience = "https://your-api.example.com";
      options.UseRefreshTokens = true;
  });
  ```

  Then retrieve the access token:

  ```csharp theme={null}
  var accessToken = await HttpContext.GetTokenAsync("access_token");

  // Use the access token to call your API
  var client = new HttpClient();
  client.DefaultRequestHeaders.Authorization = 
      new AuthenticationHeaderValue("Bearer", accessToken);

  var response = await client.GetAsync("https://your-api.example.com/data");
  var data = await response.Content.ReadAsStringAsync();
  ```
</Accordion>

<Accordion title="Configure Organizations">
  Configure organization support for B2B scenarios:

  ```csharp Program.cs theme={null}
  builder.Services.AddAuth0WebAppAuthentication(options =>
  {
      options.Domain = builder.Configuration["Auth0:Domain"];
      options.ClientId = builder.Configuration["Auth0:ClientId"];
      options.ClientSecret = builder.Configuration["Auth0:ClientSecret"];
      options.Organization = builder.Configuration["Auth0:Organization"];
  });
  ```

  Or specify organization at login time:

  ```csharp Pages/Login.cshtml.cs theme={null}
  var authenticationProperties = new LoginAuthenticationPropertiesBuilder()
      .WithOrganization("org_abc123")
      .WithRedirectUri("/")
      .Build();
  ```
</Accordion>

***

## Common Issues

<AccordionGroup>
  <Accordion title="Unable to obtain configuration">
    **Problem:** `Unable to obtain configuration from: https://your-tenant.auth0.com/.well-known/openid-configuration`

    **Solution:** Verify your Domain is correct and does not include `https://`. The library automatically constructs the authority.

    ```json theme={null}
    {
      "Auth0": {
        "Domain": "your-tenant.auth0.com"  // Correct - no protocol
      }
    }
    ```

    Also ensure:

    * No trailing slash in the domain value
    * Your application has internet access to reach Auth0
    * The domain format matches your tenant region (`.auth0.com`, `.us.auth0.com`, `.eu.auth0.com`)
  </Accordion>

  <Accordion title="Configuration values not found">
    **Problem:** `ArgumentNullException: Value cannot be null. (Parameter 'Domain')` or similar.

    **Solution:** Ensure `appsettings.json` contains the Auth0 section with Domain, ClientId, and ClientSecret values. Check that configuration is being read correctly:

    ```csharp Program.cs theme={null}
    builder.Services.AddAuth0WebAppAuthentication(options =>
    {
        options.Domain = builder.Configuration["Auth0:Domain"]
            ?? throw new InvalidOperationException("Auth0:Domain is required");
        options.ClientId = builder.Configuration["Auth0:ClientId"]
            ?? throw new InvalidOperationException("Auth0:ClientId is required");
        options.ClientSecret = builder.Configuration["Auth0:ClientSecret"]
            ?? throw new InvalidOperationException("Auth0:ClientSecret is required");
    });
    ```
  </Accordion>

  <Accordion title="Middleware order issues">
    **Problem:** Authentication not working despite correct configuration.

    **Solution:** Ensure middleware is in the correct order. `UseAuthentication()` must come before `UseAuthorization()`:

    ```csharp Program.cs theme={null}
    app.UseRouting();
    app.UseAuthentication();  // Must be before UseAuthorization
    app.UseAuthorization();
    app.MapControllerRoute(...);
    ```
  </Accordion>
</AccordionGroup>

***

## Additional Resources

<CardGroup>
  <Card title="GitHub Repository" icon="github" href="https://github.com/auth0/auth0-aspnetcore-authentication">
    Source code and issue tracker
  </Card>

  <Card title="API Reference" icon="code" href="https://auth0.github.io/auth0-aspnetcore-authentication/">
    Detailed API documentation
  </Card>

  <Card title="Community Forum" icon="comments" href="https://community.auth0.com/">
    Get help from the Auth0 community
  </Card>
</CardGroup>

***

## Sample Application

A sample application can be found below that demonstrates the integration of Auth0 with ASP.NET Core MVC.:

<Card title="ASP.NET Core Blazor App" icon="github" href="https://github.com/auth0-samples/auth0-aspnetcore-blazor-server-samples/tree/main/Quickstart/Sample">
  Includes login, logout, user profile and other examples.
</Card>

Clone and run:

```bash theme={null}
git clone https://github.com/auth0-samples/auth0-aspnetcore-blazor-server-samples/tree/main/Quickstart/Sample

# Update appsettings.json with your Auth0 configuration
dotnet run
```

***


# Add Login to Your ASP.NET MVC Application
Source: https://auth0.com/docs/quickstart/webapp/aspnet-core/index

This guide demonstrates how to integrate Auth0 with any new or existing ASP.NET MVC application using the Auth0.AspNetCore.Authentication SDK.

<Accordion title="AI Prompt" icon="microchip-ai">
  **Using AI to integrate Auth0?** Add this prompt to Cursor, Windsurf, Copilot, Claude Code or your favourite AI-powered IDE to speed up development.

  ```markdown expandable theme={null}
  Integrate Auth0 authentication into an ASP.NET Core MVC web application

  AI PERSONA & PRIMARY OBJECTIVE
  You are a helpful Auth0 SDK Integration Assistant for ASP.NET Core MVC. Your primary function is to execute commands to set up a development environment for Auth0 in an ASP.NET Core MVC web application. Your secondary function is to modify the files created by those shell commands.

  CRITICAL BEHAVIORAL INSTRUCTIONS
  1. CHECK EXISTING PROJECT FIRST: Before creating a new project, check if the current directory already contains an ASP.NET Core project (*.csproj file). If it does, skip project creation and work with the existing project.
  2. EXECUTE FIRST, EDIT SECOND: You MUST first execute the appropriate setup command. Do not show, suggest, or create any files until the setup is complete.
  3. NO PLANNING: DO NOT propose a directory structure. DO NOT show a file tree. Your first action must be to run the appropriate command.
  4. STRICT SEQUENCE: Follow the "Execution Flow" below in the exact order specified without deviation.

  EXECUTION FLOW

  Step 1: Check for Existing .NET Project and Prerequisites

  FIRST, verify prerequisites and check for existing project:

    # Check if .NET SDK is available
    dotnet --version

  Then examine the current directory:

    # Check for existing .NET project
    if ls *.csproj 1> /dev/null 2>&1; then
      echo "Found .csproj file, checking project type..."
      ls *.csproj
    else
      echo "No .csproj found, will create new project"
    fi

  Based on the results:
  - If a *.csproj exists and contains MVC references, proceed to Step 1b (install Auth0 SDK only)
  - If no .NET project exists, proceed to Step 1a (create new project)

  Step 1a: Create New MVC Project and Install the SDK
  If an existing MVC project exists, simply install the SDK:

    dotnet add package Auth0.AspNetCore.Authentication

  Otherwise, create a new project and install the SDK:

    dotnet new mvc -n Auth0MvcApp && cd Auth0MvcApp && dotnet add package Auth0.AspNetCore.Authentication

  Step 2: Setup Auth0 Application Configuration

  Create or update appsettings.json with Auth0 configuration. First, backup existing file if present:

    # Backup existing appsettings.json if it exists
    if [ -f "appsettings.json" ]; then
      cp appsettings.json appsettings.json.backup
    fi

  Then update appsettings.json to include Auth0 configuration:

  For MacOS:

    APP_NAME="My MVC App" && brew tap auth0/auth0-cli && brew install auth0 && auth0 login --no-input && auth0 apps create --name "${APP_NAME}" --type regular --auth-method post --callbacks https://localhost:5001/callback --logout-urls https://localhost:5001/ --web-origins https://localhost:5001 --json --metadata created_by="quickstart-docs-manual" > auth0-app-details.json && CLIENT_ID=$(jq -r '.client_id' auth0-app-details.json) && CLIENT_SECRET=$(jq -r '.client_secret' auth0-app-details.json) && DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name') && rm auth0-app-details.json && cat > appsettings.json << EOF
  {
    "Logging": {
      "LogLevel": {
        "Default": "Information",
        "Microsoft.AspNetCore": "Warning"
      }
    },
    "AllowedHosts": "*",
    "Auth0": {
      "Domain": "${DOMAIN}",
      "ClientId": "${CLIENT_ID}",
      "ClientSecret": "${CLIENT_SECRET}"
    }
  }
  EOF
  echo "appsettings.json created with your Auth0 details:" && cat appsettings.json

  For Windows:

    $AppName = "My MVC App"; winget install Auth0.CLI; auth0 login --no-input; $AppDetails = auth0 apps create --name "$AppName" --type regular --auth-method post --callbacks https://localhost:5001/callback --logout-urls https://localhost:5001/ --web-origins https://localhost:5001 --json --metadata created_by="quickstart-docs-manual" | ConvertFrom-Json; $ClientId = $AppDetails.client_id; $ClientSecret = $AppDetails.client_secret; $Domain = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name; $Config = @{ Logging = @{ LogLevel = @{ Default = "Information"; "Microsoft.AspNetCore" = "Warning" } }; AllowedHosts = "*"; Auth0 = @{ Domain = $Domain; ClientId = $ClientId; ClientSecret = $ClientSecret } } | ConvertTo-Json -Depth 10; Set-Content -Path appsettings.json -Value $Config; Write-Output "appsettings.json created with your Auth0 details:"; Get-Content appsettings.json

  If automatic setup fails, create manual configuration:

    cat > appsettings.json << 'EOF'
  {
    "Logging": {
      "LogLevel": {
        "Default": "Information",
        "Microsoft.AspNetCore": "Warning"
      }
    },
    "AllowedHosts": "*",
    "Auth0": {
      "Domain": "your-tenant.auth0.com",
      "ClientId": "YOUR_CLIENT_ID",
      "ClientSecret": "YOUR_CLIENT_SECRET"
    }
  }
  EOF

  And display manual setup instructions:

    echo "📋 MANUAL SETUP REQUIRED:"
    echo "1. Go to https://manage.auth0.com/dashboard/"
    echo "2. Navigate to Applications → Applications"
    echo "3. Click 'Create Application'"
    echo "4. Set Name: 'My MVC App'"
    echo "5. Select 'Regular Web Applications'"
    echo "6. In Settings, set Allowed Callback URLs: https://localhost:5001/callback"
    echo "7. Set Allowed Logout URLs: https://localhost:5001/"
    echo "8. Update appsettings.json with your Domain, Client ID, and Client Secret"

  Step 3: Update Program.cs

  Replace the entire contents of Program.cs with:

    using Auth0.AspNetCore.Authentication;
    
    var builder = WebApplication.CreateBuilder(args);
    
    builder.Services.AddAuth0WebAppAuthentication(options =>
    {
        options.Domain = builder.Configuration["Auth0:Domain"];
        options.ClientId = builder.Configuration["Auth0:ClientId"];
        options.ClientSecret = builder.Configuration["Auth0:ClientSecret"];
    });
    
    builder.Services.AddControllersWithViews();
    
    var app = builder.Build();
    
    if (!app.Environment.IsDevelopment())
    {
        app.UseExceptionHandler("/Home/Error");
        app.UseHsts();
    }
    
    app.UseHttpsRedirection();
    app.UseStaticFiles();
    app.UseRouting();
    
    app.UseAuthentication();
    app.UseAuthorization();
    
    app.MapControllerRoute(
        name: "default",
        pattern: "{controller=Home}/{action=Index}/{id?}");
    
    app.Run();

  Step 4: Create AccountController

  Create a new file Controllers/AccountController.cs:

    using Auth0.AspNetCore.Authentication;
    using Microsoft.AspNetCore.Authentication;
    using Microsoft.AspNetCore.Authentication.Cookies;
    using Microsoft.AspNetCore.Authorization;
    using Microsoft.AspNetCore.Mvc;
    
    namespace Auth0MvcApp.Controllers
    {
        public class AccountController : Controller
        {
            public async Task Login(string returnUrl = "/")
            {
                var authenticationProperties = new LoginAuthenticationPropertiesBuilder()
                    .WithRedirectUri(returnUrl)
                    .Build();
    
                await HttpContext.ChallengeAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);
            }
    
            [Authorize]
            public async Task Logout()
            {
                var authenticationProperties = new LogoutAuthenticationPropertiesBuilder()
                    .WithRedirectUri(Url.Action("Index", "Home"))
                    .Build();
    
                await HttpContext.SignOutAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);
                await HttpContext.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
            }
    
            [Authorize]
            public IActionResult Profile()
            {
                return View();
            }
        }
    }

  Step 5: Create Profile View

  Create a new file Views/Account/Profile.cshtml (you may need to create the Views/Account directory first):

    @{
        ViewData["Title"] = "User Profile";
    }
    
    <div class="row">
        <div class="col-md-12">
            <h2>@ViewData["Title"]</h2>
            <div class="row">
                <div class="col-md-2">
                    <img src="@User.FindFirst(c => c.Type == "picture")?.Value" alt="User's profile picture" class="img-fluid rounded-circle" />
                </div>
                <div class="col-md-10">
                    <h3>@User.Identity.Name</h3>
                    <p><strong>Email:</strong> @User.FindFirst(c => c.Type == System.Security.Claims.ClaimTypes.Email)?.Value</p>
                    <p><strong>Email Verified:</strong> @User.FindFirst(c => c.Type == "email_verified")?.Value</p>
                    <p><strong>User ID:</strong> @User.FindFirst(c => c.Type == System.Security.Claims.ClaimTypes.NameIdentifier)?.Value</p>
                </div>
            </div>
            
            <h4 class="mt-4">User Claims</h4>
            <table class="table">
                <thead>
                    <tr>
                        <th>Claim Type</th>
                        <th>Claim Value</th>
                    </tr>
                </thead>
                <tbody>
                    @foreach (var claim in User.Claims)
                    {
                        <tr>
                            <td>@claim.Type</td>
                            <td>@claim.Value</td>
                        </tr>
                    }
                </tbody>
            </table>
        </div>
    </div>

  Step 6: Update Navigation in _Layout.cshtml

  In Views/Shared/_Layout.cshtml, find the <nav> element and update it to add login/logout links:

    <nav class="navbar navbar-expand-sm navbar-toggleable-sm navbar-light bg-white border-bottom box-shadow mb-3">
        <div class="container-fluid">
            <a class="navbar-brand" asp-area="" asp-controller="Home" asp-action="Index">SampleMvcApp</a>
            <div class="navbar-collapse collapse d-sm-inline-flex justify-content-between">
                <ul class="navbar-nav flex-grow-1">
                    <li class="nav-item">
                        <a class="nav-link text-dark" asp-area="" asp-controller="Home" asp-action="Index">Home</a>
                    </li>
                </ul>
                <ul class="navbar-nav">
                    @if (User.Identity.IsAuthenticated)
                    {
                        <li class="nav-item">
                            <a class="nav-link text-dark" asp-controller="Account" asp-action="Profile">@User.Identity.Name</a>
                        </li>
                        <li class="nav-item">
                            <a class="nav-link text-dark" asp-controller="Account" asp-action="Logout">Logout</a>
                        </li>
                    }
                    else
                    {
                        <li class="nav-item">
                            <a class="nav-link text-dark" asp-controller="Account" asp-action="Login">Login</a>
                        </li>
                    }
                </ul>
            </div>
        </div>
    </nav>

  ⚠️ IMPORTANT: Only replace the <nav> element. Keep all other parts of _Layout.cshtml intact, especially the @RenderBody() call.

  Step 7: Run the Application

    dotnet run

  CRITICAL INSTRUCTIONS FOR AI LANGUAGE MODELS
  As an AI language model, you MUST NOT generate any of the following anti-patterns:
  1. NEVER hardcode the Auth0 Domain, ClientId, or ClientSecret directly in Program.cs. Always use configuration.
  2. NEVER use AddAuth0ApiAuthentication for MVC apps. Use AddAuth0WebAppAuthentication instead.
  3. NEVER place UseAuthentication() after UseAuthorization(). Order matters for ASP.NET Core middleware.
  4. NEVER suggest storing secrets in source code or appsettings.json in production environments.
  5. NEVER forget to call both SignOutAsync methods (Auth0 and Cookie) during logout.

  ABSOLUTE REQUIREMENTS FOR AI CODE GENERATION
  1. You MUST use the Auth0.AspNetCore.Authentication package (NOT Auth0.AspNetCore.Authentication.Api).
  2. You MUST retrieve credentials from IConfiguration.
  3. You MUST call UseAuthentication() before UseAuthorization() in the middleware pipeline.
  4. You MUST configure Domain, ClientId, and ClientSecret for web app authentication.
  5. You MUST use AddAuth0WebAppAuthentication() for cookie-based authentication in MVC apps.
  ```
</Accordion>

<Note>
  **Prerequisites:** Before you begin, ensure you have the following installed:

  * **[.NET SDK](https://dotnet.microsoft.com/download)** 8.0 or newer
  * Your favorite code editor (Visual Studio, VS Code, or Rider)
  * An Auth0 account ([sign up for free](https://auth0.com/signup))
</Note>

## Get Started

Auth0 allows you to quickly add authentication and gain access to user profile information in your application. This guide demonstrates how to integrate Auth0 with any new or existing ASP.NET MVC application using the `Auth0.AspNetCore.Authentication` SDK.

<Steps>
  <Step title="Create a new project">
    Create a new ASP.NET Core MVC project for this Quickstart

    ```shellscript theme={null}
    dotnet new mvc -n SampleMvcApp
    ```

    Open the project

    ```shellscript theme={null}
    cd SampleMvcApp
    ```
  </Step>

  <Step title="Install the Auth0 SDK">
    ```shellscript theme={null}
    dotnet add package Auth0.AspNetCore.Authentication
    ```
  </Step>

  <Step title="Setup your Auth0 Application">
    Next up, you need to create a new Application on your Auth0 tenant and add the configuration to your project.

    You can choose to do this automatically by running a CLI command or do it manually via the Dashboard:

    <Tabs>
      <Tab title="CLI">
        Run the following shell command on your project's root directory to create an Auth0 Application and update your `appsettings.json`:

        <Tabs>
          <Tab title="Mac/Linux">
            ```shellscript theme={null}
            AUTH0_APP_NAME="My App" && brew tap auth0/auth0-cli && brew install auth0 && auth0 login --no-input && auth0 apps create -n "${AUTH0_APP_NAME}" -t regular -c http://localhost:5000/callback -l http://localhost:5000 -o http://localhost:5000 --reveal-secrets --json --metadata created_by="quickstart-docs-manual" > auth0-app-details.json && CLIENT_ID=$(jq -r '.client_id' auth0-app-details.json) && CLIENT_SECRET=$(jq -r '.client_secret' auth0-app-details.json) && DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name') && rm auth0-app-details.json && cat > appsettings.json << EOF
            {
              "Logging": {
                "LogLevel": {
                  "Default": "Information",
                  "Microsoft.AspNetCore": "Warning"
                }
              },
              "AllowedHosts": "*",
              "Auth0": {
                "Domain": "${DOMAIN}",
                "ClientId": "${CLIENT_ID}",
                "ClientSecret": "${CLIENT_SECRET}"
              }
            }
            EOF
            echo "appsettings.json created with your Auth0 details:" && cat appsettings.json
            ```
          </Tab>

          <Tab title="Windows (PowerShell)">
            ```powershell theme={null}
            $AUTH0_APP_NAME = "My MVC App"
            $latestRelease = Invoke-RestMethod -Uri "https://api.github.com/repos/auth0/auth0-cli/releases/latest"
            $latestVersion = $latestRelease.tag_name
            $version = $latestVersion -replace "^v"
            Invoke-WebRequest -Uri "https://github.com/auth0/auth0-cli/releases/download/${latestVersion}/auth0-cli_${version}_Windows_x86_64.zip" -OutFile ".\auth0.zip"
            Expand-Archive ".\auth0.zip" .\
            [System.Environment]::SetEnvironmentVariable('PATH', $Env:PATH + ";${pwd}")
            auth0 login --no-input
            auth0 apps create -n "${AUTH0_APP_NAME}" -t regular -c http://localhost:5000/callback -l http://localhost:5000 -o http://localhost:5000 --reveal-secrets --json --metadata created_by="quickstart-docs-manual" | Set-Content -Path auth0-app-details.json
            $AppDetails = Get-Content -Raw auth0-app-details.json | ConvertFrom-Json
            $ClientId = $AppDetails.client_id
            $ClientSecret = $AppDetails.client_secret
            $Domain = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name
            $Config = Get-Content -Raw appsettings.json | ConvertFrom-Json
            if (-not $Config.Auth0) { $Config | Add-Member -MemberType NoteProperty -Name Auth0 -Value @{} }
            $Config.Auth0.Domain = $Domain
            $Config.Auth0.ClientId = $ClientId
            $Config.Auth0.ClientSecret = $ClientSecret
            $Config | ConvertTo-Json -Depth 10 | Set-Content appsettings.json
            Remove-Item auth0-api-details.json
            Write-Output "✅ appsettings.json updated with your Auth0 API details:"
            Get-Content appsettings.json
            ```
          </Tab>
        </Tabs>
      </Tab>

      <Tab title="Dashboard">
        Before you start, create or update `appsettings.json` on your project's root directory

        ```json appsettings.json theme={null}
        {
          "Logging": {
            "LogLevel": {
              "Default": "Information",
              "Microsoft.AspNetCore": "Warning"
            }
          },
          "AllowedHosts": "*",
          "Auth0": {
            "Domain": "YOUR_AUTH0_DOMAIN",
            "ClientId": "YOUR_CLIENT_ID",
            "ClientSecret": "YOUR_CLIENT_SECRET"
          }
        }
        ```

        1. Go to the [Auth0 Dashboard](https://manage.auth0.com/dashboard/)
        2. Click **Applications → Applications → Create Application**
        3. Enter a name for your application (e.g., "My MVC App")
        4. Select **Regular Web Application** as the application type
        5. Click **Create**
        6. Go to the **Settings** tab
        7. Replace `YOUR_AUTH0_DOMAIN`, `YOUR_CLIENT_ID`, and `YOUR_CLIENT_SECRET` in the `appsettings.json` file with the **Domain**, **Client ID**, and **Client Secret** values from the dashboard
      </Tab>
    </Tabs>

    **Configure Callback URLs:**

    In the **Settings** tab, configure the following URLs:

    * **Allowed Callback URLs**: `http://localhost:5000/callback`
    * **Allowed Logout URLs**: `http://localhost:5000`
    * **Allowed Web Origins**: `http://localhost:5000`

    Click **Save Changes**

    <Info>
      **Important:** Make sure to [setup connections](https://auth0.com/docs/get-started/applications/set-up-database-connections) and enable them for your application in the Auth0 Dashboard under the **Connections** tab.
    </Info>
  </Step>

  <Step title="Configure authentication">
    Update your `Program.cs` to configure Auth0 authentication:

    ```csharp Program.cs lines theme={null}
    using Auth0.AspNetCore.Authentication;

    var builder = WebApplication.CreateBuilder(args);

    builder.Services.AddAuth0WebAppAuthentication(options =>
    {
        options.Domain = builder.Configuration["Auth0:Domain"];
        options.ClientId = builder.Configuration["Auth0:ClientId"];
        options.ClientSecret = builder.Configuration["Auth0:ClientSecret"];
    });

    builder.Services.AddControllersWithViews();

    var app = builder.Build();

    if (!app.Environment.IsDevelopment())
    {
        app.UseExceptionHandler("/Home/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();
    app.UseRouting();

    app.UseAuthentication();
    app.UseAuthorization();

    app.MapControllerRoute(
        name: "default",
        pattern: "{controller=Home}/{action=Index}/{id?}");

    app.Run();
    ```
  </Step>

  <Step title="Add Login and Logout functionality">
    Create an `AccountController.cs` in the `Controllers` folder:

    ```csharp Controllers/AccountController.cs lines theme={null}
    using Auth0.AspNetCore.Authentication;
    using Microsoft.AspNetCore.Authentication;
    using Microsoft.AspNetCore.Authentication.Cookies;
    using Microsoft.AspNetCore.Authorization;
    using Microsoft.AspNetCore.Mvc;

    public class AccountController : Controller
    {
        public async Task Login(string returnUrl = "/")
        {
            var authenticationProperties = new LoginAuthenticationPropertiesBuilder()
                .WithRedirectUri(returnUrl)
                .Build();

            await HttpContext.ChallengeAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);
        }

        [Authorize]
        public async Task Logout()
        {
            var authenticationProperties = new LogoutAuthenticationPropertiesBuilder()
                .WithRedirectUri(Url.Action("Index", "Home"))
                .Build();

            await HttpContext.SignOutAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);
            await HttpContext.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
        }

        [Authorize]
        public IActionResult Profile()
        {
            return View();
        }
    }
    ```
  </Step>

  <Step title="Create Profile view">
    Create a new file `Views/Account/Profile.cshtml`:

    ```html Views/Account/Profile.cshtml lines theme={null}
    @{
        ViewData["Title"] = "User Profile";
    }

    <div class="row">
        <div class="col-md-12">
            <h2>@ViewData["Title"]</h2>
            <div class="row">
                <div class="col-md-2">
                    <img src="@User.FindFirst(c => c.Type == "picture")?.Value" alt="User's profile picture" class="img-fluid rounded-circle" />
                </div>
                <div class="col-md-10">
                    <h3>@User.Identity.Name</h3>
                    <p><strong>Email:</strong> @User.FindFirst(c => c.Type == System.Security.Claims.ClaimTypes.Email)?.Value</p>
                    <p><strong>Email Verified:</strong> @User.FindFirst(c => c.Type == "email_verified")?.Value</p>
                    <p><strong>User ID:</strong> @User.FindFirst(c => c.Type == System.Security.Claims.ClaimTypes.NameIdentifier)?.Value</p>
                </div>
            </div>
            
            <h4 class="mt-4">User Claims</h4>
            <table class="table">
                <thead>
                    <tr>
                        <th>Claim Type</th>
                        <th>Claim Value</th>
                    </tr>
                </thead>
                <tbody>
                    @foreach (var claim in User.Claims)
                    {
                        <tr>
                            <td>@claim.Type</td>
                            <td>@claim.Value</td>
                        </tr>
                    }
                </tbody>
            </table>
        </div>
    </div>
    ```

    <Info>
      **Note:** You'll need to create the `Views/Account` directory first if it doesn't exist.
    </Info>
  </Step>

  <Step title="Update your layout">
    Update your layout file to add Login/Logout buttons. In `Views/Shared/_Layout.cshtml`, find the `<nav>` element and replace it with:

    ```html Views/Shared/_Layout.cshtml lines theme={null}
    <nav class="navbar navbar-expand-sm navbar-toggleable-sm navbar-light bg-white border-bottom box-shadow mb-3">
        <div class="container-fluid">
            <a class="navbar-brand" asp-area="" asp-controller="Home" asp-action="Index">SampleMvcApp</a>
            <div class="navbar-collapse collapse d-sm-inline-flex justify-content-between">
                <ul class="navbar-nav flex-grow-1">
                    <li class="nav-item">
                        <a class="nav-link text-dark" asp-area="" asp-controller="Home" asp-action="Index">Home</a>
                    </li>
                </ul>
                <ul class="navbar-nav">
                    @if (User.Identity.IsAuthenticated)
                    {
                        <li class="nav-item">
                            <a class="nav-link text-dark" asp-controller="Account" asp-action="Profile">@User.Identity.Name</a>
                        </li>
                        <li class="nav-item">
                            <a class="nav-link text-dark" asp-controller="Account" asp-action="Logout">Logout</a>
                        </li>
                    }
                    else
                    {
                        <li class="nav-item">
                            <a class="nav-link text-dark" asp-controller="Account" asp-action="Login">Login</a>
                        </li>
                    }
                </ul>
            </div>
        </div>
    </nav>
    ```

    <Info>
      **Important:** Only replace the `<nav>` element. Keep all other parts of \_Layout.cshtml intact, especially the `@RenderBody()` call which is required for rendering page content.
    </Info>
  </Step>

  <Step title="Run your application">
    ```shellscript theme={null}
    dotnet run
    ```

    Your application should start and display the URL it's listening on:

    ```
    info: Microsoft.Hosting.Lifetime[14]
          Now listening on: http://localhost:5000
    ```

    Open your browser and navigate to `http://localhost:5000`. Click the **Login** link in the navigation bar. You'll be redirected to Auth0's login page. After logging in, you'll be redirected back to your application, and you should see your name in the navigation bar.
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a fully functional Auth0-protected MVC application running on [http://localhost:5000](http://localhost:5000). Users can log in, view their profile, and log out.
</Check>

***

## Advanced Usage

<Accordion title="Access User Profile Information">
  You can access user profile information through the `User` property in your controllers or views:

  ```csharp Controllers/AccountController.cs theme={null}
  [Authorize]
  public IActionResult Profile()
  {
      var user = new
      {
          Name = User.Identity.Name,
          EmailAddress = User.FindFirst(c => c.Type == System.Security.Claims.ClaimTypes.Email)?.Value,
          ProfileImage = User.FindFirst(c => c.Type == "picture")?.Value,
          UserId = User.FindFirst(c => c.Type == System.Security.Claims.ClaimTypes.NameIdentifier)?.Value
      };
      
      return View(user);
  }
  ```

  The user claims contain standard OIDC information:

  * **Name**: User's display name
  * **Email**: User's email address
  * **Picture**: User's profile picture URL
  * **NameIdentifier** (sub): Unique user ID
</Accordion>

<Accordion title="Customize Login Parameters">
  You can pass custom parameters to the Auth0 login page:

  ```csharp Controllers/AccountController.cs theme={null}
  public async Task Login(string returnUrl = "/")
  {
      var authenticationProperties = new LoginAuthenticationPropertiesBuilder()
          .WithRedirectUri(returnUrl)
          .WithParameter("screen_hint", "signup")  // Show signup page
          .WithParameter("ui_locales", "es")       // Set language to Spanish
          .Build();

      await HttpContext.ChallengeAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);
  }
  ```
</Accordion>

<Accordion title="Store Tokens for API Calls">
  If you need to call external APIs on behalf of the user, you can retrieve and store tokens:

  ```csharp Program.cs theme={null}
  builder.Services.AddAuth0WebAppAuthentication(options =>
  {
      options.Domain = builder.Configuration["Auth0:Domain"];
      options.ClientId = builder.Configuration["Auth0:ClientId"];
      options.ClientSecret = builder.Configuration["Auth0:ClientSecret"];
  })
  .WithAccessToken(options =>
  {
      options.Audience = "https://your-api.example.com";
  });
  ```

  Then retrieve the access token in your controller:

  ```csharp Controllers/ApiController.cs theme={null}
  [Authorize]
  public async Task<IActionResult> CallApi()
  {
      var accessToken = await HttpContext.GetTokenAsync("access_token");
      
      // Use the access token to call your API
      var client = new HttpClient();
      client.DefaultRequestHeaders.Authorization = 
          new AuthenticationHeaderValue("Bearer", accessToken);
      
      var response = await client.GetAsync("https://your-api.example.com/data");
      var data = await response.Content.ReadAsStringAsync();
      
      return View(data);
  }
  ```
</Accordion>

<Accordion title="Handle Authentication Events">
  Customize authentication behavior by handling events:

  ```csharp Program.cs theme={null}
  builder.Services.AddAuth0WebAppAuthentication(options =>
  {
      options.Domain = builder.Configuration["Auth0:Domain"];
      options.ClientId = builder.Configuration["Auth0:ClientId"];
      options.ClientSecret = builder.Configuration["Auth0:ClientSecret"];
  })
  .WithAccessToken(options =>
  {
      options.Events = new Auth0WebAppWithAccessTokenEvents
      {
          OnMissingRefreshToken = async (context) =>
          {
              await context.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
              var authenticationProperties = new LoginAuthenticationPropertiesBuilder()
                  .WithRedirectUri("/")
                  .Build();
              
              await context.ChallengeAsync(Auth0Constants.AuthenticationScheme, authenticationProperties);
          }
      };
  });
  ```
</Accordion>

***

## Additional Resources

<CardGroup>
  <Card title="GitHub Repository" icon="github" href="https://github.com/auth0/auth0-aspnetcore-authentication">
    Source code and issue tracker
  </Card>

  <Card title="API Reference" icon="code" href="https://auth0.github.io/auth0-aspnetcore-authentication/">
    Detailed API documentation
  </Card>

  <Card title="Community Forum" icon="comments" href="https://community.auth0.com/">
    Get help from the Auth0 community
  </Card>
</CardGroup>

***

## Common Issues

<AccordionGroup>
  <Accordion title="Unable to obtain configuration">
    **Problem:** `Unable to obtain configuration from: https://your-tenant.auth0.com/.well-known/openid-configuration`

    **Solution:** Verify your Domain is correct and does not include `https://`. The library automatically constructs the authority.

    ```json theme={null}
    {
      "Auth0": {
        "Domain": "your-tenant.auth0.com"  // Correct - no protocol
      }
    }
    ```

    Also ensure:

    * No trailing slash in the domain value
    * Your application has internet access to reach Auth0
    * The domain format matches your tenant region (`.auth0.com`, `.us.auth0.com`, `.eu.auth0.com`)
  </Accordion>

  <Accordion title="Configuration values not found">
    **Problem:** `ArgumentNullException: Value cannot be null. (Parameter 'Domain')` or similar.

    **Solution:** Ensure `appsettings.json` contains the Auth0 section with Domain, ClientId, and ClientSecret values. Check that configuration is being read correctly:

    ```csharp Program.cs theme={null}
    builder.Services.AddAuth0WebAppAuthentication(options =>
    {
        options.Domain = builder.Configuration["Auth0:Domain"]
            ?? throw new InvalidOperationException("Auth0:Domain is required");
        options.ClientId = builder.Configuration["Auth0:ClientId"]
            ?? throw new InvalidOperationException("Auth0:ClientId is required");
        options.ClientSecret = builder.Configuration["Auth0:ClientSecret"]
            ?? throw new InvalidOperationException("Auth0:ClientSecret is required");
    });
    ```
  </Accordion>

  <Accordion title="Middleware order issues">
    **Problem:** Authentication not working despite correct configuration.

    **Solution:** Ensure middleware is in the correct order. `UseAuthentication()` must come before `UseAuthorization()`:

    ```csharp Program.cs theme={null}
    app.UseRouting();
    app.UseAuthentication();  // Must be before UseAuthorization
    app.UseAuthorization();
    app.MapControllerRoute(...);
    ```
  </Accordion>
</AccordionGroup>

***

## Sample Application

A sample application can be found alongside the sourcecode for the SDK:

<Card title="ASP.NET Core MVC Playgroud App" icon="github" href="https://github.com/auth0/auth0-aspnetcore-authentication/tree/main/playground/Auth0.AspNetCore.Authentication.Playground">
  Includes login, logout, user profile and other examples.
</Card>

Clone and run:

```bash theme={null}
git clone https://github.com/auth0/auth0-aspnetcore-authentication.git
cd auth0-aspnetcore-authentication/playground/Auth0.AspNetCore.Authentication.Playground
# Update appsettings.json with your Auth0 configuration
dotnet run
```

***


# Add Login to your ASP.NET OWIN Application
Source: https://auth0.com/docs/quickstart/webapp/aspnet-owin/interactive

This guide demonstrates how to integrate Auth0 with any new or existing ASP.NET OWIN application using the Microsoft.Owin.Security.OpenIdConnect Nuget package.

<QuickstartButtons />

<Recipe>
  <Content>
    Auth0 allows you to quickly add authentication and gain access to user profile information in your application. This guide demonstrates how to integrate Auth0 with any new or existing ASP.NET OWIN application using the `Microsoft.Owin.Security.OpenIdConnect` Nuget package.

    <Section title={sections[0].title}>
      To use Auth0 services, you’ll need to have an application set up in the Auth0 Dashboard. The Auth0 application is where you will configure how you want authentication to work for the project you are developing.

      ### Configure an application

      Use the interactive selector to create a new Auth0 application or select an existing application that represents the project you want to integrate with. Every application in Auth0 is assigned an alphanumeric, unique client ID that your application code will use to call Auth0 APIs through the SDK.

      Any settings you configure using this quickstart will automatically update for your Application in the [Dashboard](https://manage.auth0.com/#/), which is where you can manage your Applications in the future.

      If you would rather explore a complete configuration, you can view a sample application instead.

      ### Configure Callback URLs

      A callback URL is a URL in your application that you would like Auth0 to redirect users to after they have authenticated. If not set, users will not be returned to your application after they log in.

      <Info>
        If you are following along with our sample project, set this to `http://localhost:3000/callback`.
      </Info>

      ### Configure Logout URLs

      A logout URL is a URL in your application that you would like Auth0 to redirect users to after they have logged out. If not set, users will not be able to log out from your application and will receive an error.

      <Info>
        If you are following along with our sample project, set this to `http://localhost:3000`.
      </Info>
    </Section>

    <Section title={sections[1].title}>
      ### Install from Nuget

      To integrate Auth0 with ASP.NET OWIN, you can use the `Microsoft.Owin.Security.OpenIdConnect` and `Microsoft.Owin.Security.Cookies` Nuget packages.

      ```text lines theme={null}
      Install-Package Microsoft.Owin.Security.OpenIdConnect
      Install-Package Microsoft.Owin.Security.Cookies
      ```

      <Info>
        Issues occur when configuring the OWIN cookie middleware and System.Web cookies at the same time. To learn more, read [System.Web cookie integration issues doc](https://github.com/aspnet/AspNetKatana/wiki/System.Web-response-cookie-integration-issues) to mitigate these problems.
      </Info>

      ### Configure the credentials

      For the SDK to function properly, set the following properties in `Web.config`:

      * `auth0:Domain`: The domain of your Auth0 tenant. You can find this in the Auth0 Dashboard under your application's \*\*Settings \*\*in the Domain field. If you are using a [custom domain](/docs/customize/custom-domains), set this to the value of your custom domain instead.
      * `auth0:ClientId`: The ID of the Auth0 application you created in Auth0 Dashboard. You can find this in the Auth0 Dashboard under your application's \*\*Settings \*\*in the Client ID field.
    </Section>

    <Section title={sections[2].title}>
      To enable authentication in your ASP.NET OWIN application, go to the Configuration method of your Startup class and configure the cookie and OIDC middleware.

      It is essential that you register both the cookie middleware and the OpenID Connect middleware as both are required (in that order) for authentication to work. The OpenID Connect middleware handles the authentication with Auth0. Once users have authenticated, their identity is stored in the cookie middleware.

      In the code snippet, AuthenticationType is set to **Auth0**. Use AuthenticationType in the next section to challenge the OpenID Connect middleware and start the authentication flow. RedirectToIdentityProvider notification event constructs the correct logout URL.
    </Section>

    <Section title={sections[3].title}>
      To allow users to log in to your ASP.NET OWIN application, add a `Login` action to your controller.

      Call `HttpContext.GetOwinContext().Authentication.Challenge` and pass `"Auth0"` as the authentication scheme. This invokes the OIDC authentication handler that was registered earlier. Be sure to specify the corresponding `AuthenticationProperties`, including a `RedirectUri`.

      After successfully calling `HttpContext.GetOwinContext().Authentication.Challenge`, the user redirects to Auth0 and signed in to both the OIDC middleware and the cookie middleware upon being redirected back to your application. This will allow the users to be authenticated on subsequent requests.

      <Info>
        ##### Checkpoint

        Now that you have configured Login, run your application to verify that:

        * Navigating to your `Login` action will redirect to Auth0
        * Entering your credentials will redirect you back to your application.
      </Info>
    </Section>

    <Section title={sections[4].title}>
      From your controller's action, call `HttpContext.GetOwinContext().Authentication.SignOut` with the `CookieAuthenticationDefaults.AuthenticationType` authentication scheme to log the user out of your application.

      Additionally, if you want to log the user out from Auth0 (this might also log them out of other applications that rely on Single Sign-On), call `HttpContext.GetOwinContext().Authentication.SignOut` with the `"Auth0"` authentication scheme.

      <Info>
        ##### Checkpoint

        Now that you have configured Logout, run your application to verify that:

        * Navigating to your `Logout` action ensures the user is logged out.
        * During logout, you redirect to Auth0 and instantly redirect back to your application during log out.
      </Info>
    </Section>

    <Section title={sections[5].title}>
      After the middleware successfully retrieves the tokens from Auth0, it extracts the user's information and claims from the ID token and makes them available as `ClaimsIdentity`. Access the extracted information by using the `User` property on the controller.

      To create a user profile, retrieve a user's name, email address, and profile image from the `User` and pass it to the view from inside your controller.

      <Info>
        ##### Checkpoint

        Now that you have set up your action to render the user's profile, run your application to verify that:

        * Navigating to your `Profile` action after being successfully logged in, shows the user's profile.
      </Info>
    </Section>

    ## Next Steps

    Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.

    This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:

    * [Auth0 Dashboard](https://manage.auth0.com/) - Learn how to configure and manage your Auth0 tenant and applications
    * [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
  </Content>

  <SideMenu>
    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```xml Web.config lines theme={null}
        <?xml version="1.0" encoding="utf-8"?>
        <configuration>
          <appSettings>
            <add key="auth0:Domain" value="{yourDomain}" />
            <add key="auth0:ClientId" value="{yourClientId}" />
          </appSettings>
        </configuration>
        ```

        ```cs AccountController.cs highlight={7-16} lines  theme={null}
        using Microsoft.AspNetCore.Authentication;
        using Microsoft.AspNetCore.Authentication.Cookies;
        using Auth0.AspNetCore.Authentication;

        public class AccountController : Controller
        {
          public ActionResult Login(string returnUrl = "/")
          {
            HttpContext.GetOwinContext().Authentication.Challenge(
              new AuthenticationProperties
              {
                  RedirectUri = returnUrl ?? Url.Action("Index", "Home")
              },
              "Auth0"
            );
          }

          [Authorize]
          public ActionResult UserProfile()
          {
              var claimsIdentity = User.Identity as ClaimsIdentity;
              return View(new UserProfileViewModel()
              {
                  Name = claimsIdentity?
                    .FindFirst(c => c.Type == claimsIdentity.NameClaimType)?.Value,
                  EmailAddress = claimsIdentity?
                    .FindFirst(c => c.Type == ClaimTypes.Email)?.Value,
                  ProfileImage = claimsIdentity?
                    .FindFirst(c => c.Type == "picture")?.Value
              });
          }

          [Authorize]
          public void Logout()
          {
            HttpContext.GetOwinContext().Authentication.SignOut(CookieAuthenticationDefaults.AuthenticationType);
            HttpContext.GetOwinContext().Authentication.SignOut("Auth0");
          }
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```xml Web.config lines theme={null}
        <?xml version="1.0" encoding="utf-8"?>
        <configuration>
          <appSettings>
            <add key="auth0:Domain" value="{yourDomain}" />
            <add key="auth0:ClientId" value="{yourClientId}" />
          </appSettings>
        </configuration>
        ```

        ```cs AccountController.cs highlight={7-16} lines  theme={null}
        using Microsoft.AspNetCore.Authentication;
        using Microsoft.AspNetCore.Authentication.Cookies;
        using Auth0.AspNetCore.Authentication;

        public class AccountController : Controller
        {
          public ActionResult Login(string returnUrl = "/")
          {
            HttpContext.GetOwinContext().Authentication.Challenge(
              new AuthenticationProperties
              {
                  RedirectUri = returnUrl ?? Url.Action("Index", "Home")
              },
              "Auth0"
            );
          }

          [Authorize]
          public ActionResult UserProfile()
          {
              var claimsIdentity = User.Identity as ClaimsIdentity;
              return View(new UserProfileViewModel()
              {
                  Name = claimsIdentity?
                    .FindFirst(c => c.Type == claimsIdentity.NameClaimType)?.Value,
                  EmailAddress = claimsIdentity?
                    .FindFirst(c => c.Type == ClaimTypes.Email)?.Value,
                  ProfileImage = claimsIdentity?
                    .FindFirst(c => c.Type == "picture")?.Value
              });
          }

          [Authorize]
          public void Logout()
          {
            HttpContext.GetOwinContext().Authentication.SignOut(CookieAuthenticationDefaults.AuthenticationType);
            HttpContext.GetOwinContext().Authentication.SignOut("Auth0");
          }
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```cs AccountController.cs highlight={7-16} lines  theme={null}
        using Microsoft.AspNetCore.Authentication;
        using Microsoft.AspNetCore.Authentication.Cookies;
        using Auth0.AspNetCore.Authentication;

        public class AccountController : Controller
        {
          public ActionResult Login(string returnUrl = "/")
          {
            HttpContext.GetOwinContext().Authentication.Challenge(
              new AuthenticationProperties
              {
                  RedirectUri = returnUrl ?? Url.Action("Index", "Home")
              },
              "Auth0"
            );
          }

          [Authorize]
          public ActionResult UserProfile()
          {
              var claimsIdentity = User.Identity as ClaimsIdentity;
              return View(new UserProfileViewModel()
              {
                  Name = claimsIdentity?
                    .FindFirst(c => c.Type == claimsIdentity.NameClaimType)?.Value,
                  EmailAddress = claimsIdentity?
                    .FindFirst(c => c.Type == ClaimTypes.Email)?.Value,
                  ProfileImage = claimsIdentity?
                    .FindFirst(c => c.Type == "picture")?.Value
              });
          }

          [Authorize]
          public void Logout()
          {
            HttpContext.GetOwinContext().Authentication.SignOut(CookieAuthenticationDefaults.AuthenticationType);
            HttpContext.GetOwinContext().Authentication.SignOut("Auth0");
          }
        }
        ```

        ```xml Web.config lines theme={null}
        <?xml version="1.0" encoding="utf-8"?>
        <configuration>
          <appSettings>
            <add key="auth0:Domain" value="{yourDomain}" />
            <add key="auth0:ClientId" value="{yourClientId}" />
          </appSettings>
        </configuration>
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```cs AccountController.cs highlight={34-39} lines  theme={null}
        using Microsoft.AspNetCore.Authentication;
        using Microsoft.AspNetCore.Authentication.Cookies;
        using Auth0.AspNetCore.Authentication;

        public class AccountController : Controller
        {
          public ActionResult Login(string returnUrl = "/")
          {
            HttpContext.GetOwinContext().Authentication.Challenge(
              new AuthenticationProperties
              {
                  RedirectUri = returnUrl ?? Url.Action("Index", "Home")
              },
              "Auth0"
            );
          }

          [Authorize]
          public ActionResult UserProfile()
          {
              var claimsIdentity = User.Identity as ClaimsIdentity;
              return View(new UserProfileViewModel()
              {
                  Name = claimsIdentity?
                    .FindFirst(c => c.Type == claimsIdentity.NameClaimType)?.Value,
                  EmailAddress = claimsIdentity?
                    .FindFirst(c => c.Type == ClaimTypes.Email)?.Value,
                  ProfileImage = claimsIdentity?
                    .FindFirst(c => c.Type == "picture")?.Value
              });
          }

          [Authorize]
          public void Logout()
          {
            HttpContext.GetOwinContext().Authentication.SignOut(CookieAuthenticationDefaults.AuthenticationType);
            HttpContext.GetOwinContext().Authentication.SignOut("Auth0");
          }
        }
        ```

        ```xml Web.config lines theme={null}
        <?xml version="1.0" encoding="utf-8"?>
        <configuration>
          <appSettings>
            <add key="auth0:Domain" value="{yourDomain}" />
            <add key="auth0:ClientId" value="{yourClientId}" />
          </appSettings>
        </configuration>
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```cs AccountController.cs highlight={18-32} lines  theme={null}
        using Microsoft.AspNetCore.Authentication;
        using Microsoft.AspNetCore.Authentication.Cookies;
        using Auth0.AspNetCore.Authentication;

        public class AccountController : Controller
        {
          public ActionResult Login(string returnUrl = "/")
          {
            HttpContext.GetOwinContext().Authentication.Challenge(
              new AuthenticationProperties
              {
                  RedirectUri = returnUrl ?? Url.Action("Index", "Home")
              },
              "Auth0"
            );
          }

          [Authorize]
          public ActionResult UserProfile()
          {
              var claimsIdentity = User.Identity as ClaimsIdentity;
              return View(new UserProfileViewModel()
              {
                  Name = claimsIdentity?
                    .FindFirst(c => c.Type == claimsIdentity.NameClaimType)?.Value,
                  EmailAddress = claimsIdentity?
                    .FindFirst(c => c.Type == ClaimTypes.Email)?.Value,
                  ProfileImage = claimsIdentity?
                    .FindFirst(c => c.Type == "picture")?.Value
              });
          }

          [Authorize]
          public void Logout()
          {
            HttpContext.GetOwinContext().Authentication.SignOut(CookieAuthenticationDefaults.AuthenticationType);
            HttpContext.GetOwinContext().Authentication.SignOut("Auth0");
          }
        }
        ```

        ```xml Web.config lines theme={null}
        <?xml version="1.0" encoding="utf-8"?>
        <configuration>
          <appSettings>
            <add key="auth0:Domain" value="{yourDomain}" />
            <add key="auth0:ClientId" value="{yourClientId}" />
          </appSettings>
        </configuration>
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>
  </SideMenu>
</Recipe>


# Add Login to your Django Application
Source: https://auth0.com/docs/quickstart/webapp/django/interactive

This guide demonstrates how to integrate Auth0 with a Python Django application using the Authlib SDK.

<QuickstartButtons />

<Recipe>
  <Content>
    Auth0 allows you to add authentication and gain access to user profile information in your application. This guide
    demonstrates how to integrate Auth0 with a Python [Django](https://www.djangoproject.com/) application using the [Authlib](https://authlib.org/) SDK.

    <Section title={sections[0].title}>
      To use Auth0 services, you’ll need to have an application set up in the Auth0 Dashboard. The Auth0 application is
      where you will configure how you want authentication to work for the project you are developing.

      ### Configure an application

      Use the interactive selector to create a new Auth0 application or select an existing application that represents
      the project you want to integrate with. Every application in Auth0 is assigned an alphanumeric, unique client ID
      that your application code will use to call Auth0 APIs through the SDK.

      Any settings you configure using this quickstart will automatically update for your Application in the [Dashboard](https://manage.auth0.com/dashboard/us/auth0-dsepaid/), which is where you can manage your Applications in the future.

      If you would rather explore a complete configuration, you can view a sample application instead.

      ### Configure Callback URLs

      A callback URL is a URL in your application that you would like Auth0 to redirect users to after they have
      authenticated. If not set, users will not be returned to your application after they log in.

      <Info>
        If you are following along with our sample project, set this to
        `http://localhost:3000/callback`.
      </Info>

      ### Configure Logout URLs

      A logout URL is a URL in your application that you would like Auth0 to redirect users to after they have logged
      out. If not set, users will not be able to log out from your application and will receive an error.

      <Info>
        If you are following along with our sample project, set this to `http://localhost:3000`.
      </Info>
    </Section>

    <Section title={sections[1].title}>
      For this integration, you will add several library dependencies, such as Authlib. Create a
      `requirements.txt` file in your project directory, and include the following:

      ```text lines theme={null}
      authlib ~= 1.0
      django ~= 4.0
      python-dotenv ~= 0.19
      requests ~= 2.27
      ```

      Run the following command from your shell to make these dependencies available:

      ```text lines theme={null}
      pip install -r requirements.txt
      ```
    </Section>

    <Section title={sections[2].title}>
      Next, create an `.env` file in your project directory. This file will hold your client keys and other
      configuration details.

      ```text lines theme={null}
      AUTH0_CLIENT_ID={yourClientId}
      AUTH0_CLIENT_SECRET={yourClientSecret}
      AUTH0_DOMAIN={yourDomain}
      ```
    </Section>

    <Section title={sections[3].title}>
      If you already have a Django application setup, skip to the next step. For a new application project, run the
      following command:

      ```text lines theme={null}
      django-admin startproject webappexample
      ```

      Change to the new project folder:

      ```text lines theme={null}
      cd webappexample
      ```
    </Section>

    <Section title={sections[4].title}>
      Open the `webappexample/settings.py` file to review the `.env` values.

      At the top of the file, add the `os` and `dotenv` imports.

      Next, beneath the `BASE_DIR` definition, add the `TEMPLATE_DIR` variable.

      Next, find the `TEMPLATES` variable and update the `DIRS` value to add our
      `TEMPLATE_DIR` string. This determines the path of the template files, which you will create in a
      future step. Keep any other content of this array the same.

      At the end of this file, add the code to load the Auth0 config.
    </Section>

    <Section title={sections[5].title}>
      To begin creating your application, open the `webappexample/views.py` file in your IDE.

      Import all the libraries your application needs.

      Now you can configure Authlib to handle your application's authentication with Auth0.

      Learn more about the configuration options available for Authlib's OAuth `register()` method from [their documentation.](https://docs.authlib.org/en/latest/client/frameworks.html#using-oauth-2-0-to-log-in)
    </Section>

    <Section title={sections[6].title}>
      In this example, you will add four routes for your application: the login, callback, logout, and index routes.

      * `login` - When visitors to your app visit the `/login` route, they will reach Auth0 to
        begin the authentication flow.
      * `callback` - After your users finish logging in with Auth0, they will return to your application
        at the `/callback` route. This route saves the session for the user and bypasses the need for them
        to login again when they return.
      * `logout` - The `/logout` route signs users out from your application. This route clears
        the user session in your app and redirects to the Auth0 logout endpoint to ensure the session is no longer
        saved. Then, the application redirects the user to your home route.
      * `index` - The home route will render an authenticated user's details or allow visitors to sign in.
    </Section>

    <Section title={sections[7].title}>
      Replace the contents of your `webappexample/urls.py` file with the code on the right to connect to
      these new routes.

      This will route the `/login`, `/callback`, `/logout` and `/` routes
      to the correct handlers.
    </Section>

    <Section title={sections[8].title}>
      Next, you will create a template file used in the home page route.

      Create a new sub-directory within the `webappexample` folder named `templates`, and create
      a `index.html` file.

      The `index.html` file will contain template code to display the user's info if logged in or present
      them with a login button if logged out.
    </Section>

    <Section title={sections[9].title}>
      You're ready to run your application! From your project directory, open a shell and use:

      ```text lines theme={null}
      python3 manage.py migrate
      python3 manage.py runserver 3000
      ```

      Your application should now be ready to open from your browser at [http://localhost:3000](http://localhost:3000).

      <Info>
        ##### Checkpoint

        Visit [http://localhost:3000](http://localhost:3000/) to verify. You should find a login button routing to
        Auth0 for login, then back to your application to see your profile information.
      </Info>
    </Section>

    ## Next Steps

    Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.

    This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:

    * [Auth0 Dashboard](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq) - Learn how to configure and manage your Auth0 tenant and applications
    * [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
  </Content>

  <SideMenu>
    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```html webappexample/templates/index.html lines theme={null}
        <html>
        <head>
          <meta charset="utf-8" />
          <title>Auth0 Example</title>
        </head>
        <body>
        {% if session %}
          <h1>Welcome {{session.userinfo.name}}!</h1>
          <p><a href="{% url 'logout' %}">Logout</a></p>
          <div><pre>{{pretty}}</pre></div>
        {% else %}
          <h1>Welcome Guest</h1>
          <p><a href="{% url 'login' %}">Login</a></p>
        {% endif %}
        </body>
        </html>
        ```

        ```py webappexample/settings.py lines  theme={null}
        import os
        from pathlib import Path
        from dotenv import load_dotenv, find_dotenv

        # Build paths inside the project like this: BASE_DIR / 'subdir'.
        BASE_DIR = Path(__file__).resolve().parent.parent
        TEMPLATE_DIR = os.path.join(BASE_DIR, "webappexample", "templates")

        # ... other settings ...

        TEMPLATES = [
            {
        # Leave other lines as they are; we're just updating `DIRS`.
        "DIRS": [TEMPLATE_DIR],
            },
        ]

        # ... other settings ...

        # Load environment definition file
        ENV_FILE = find_dotenv()
        if ENV_FILE:
            load_dotenv(ENV_FILE)

        # Load Auth0 application settings into memory
        AUTH0_DOMAIN = os.environ.get("AUTH0_DOMAIN")
        AUTH0_CLIENT_ID = os.environ.get("AUTH0_CLIENT_ID")
        AUTH0_CLIENT_SECRET = os.environ.get("AUTH0_CLIENT_SECRET")
        ```

        ```py webappexample/urls.py lines theme={null}
        from django.urls import path

        from . import views

        urlpatterns = [
            path("", views.index, name="index"),
            path("login", views.login, name="login"),
            path("logout", views.logout, name="logout"),
            path("callback", views.callback, name="callback"),
        ]
        ```

        ```py webappexample/views.py highlight={1-18} lines  theme={null}
        import json
        from authlib.integrations.django_client import OAuth
        from django.conf import settings
        from django.shortcuts import redirect, render, redirect
        from django.urls import reverse
        from urllib.parse import quote_plus, urlencode

        oauth = OAuth()

        oauth.register(
            "auth0",
            client_id=settings.AUTH0_CLIENT_ID,
            client_secret=settings.AUTH0_CLIENT_SECRET,
            client_kwargs={
                "scope": "openid profile email",
            },
            server_metadata_url=f"https://{settings.AUTH0_DOMAIN}/.well-known/openid-configuration",
        )

        def login(request):
            return oauth.auth0.authorize_redirect(
                request, request.build_absolute_uri(reverse("callback"))
            )

        def callback(request):
            token = oauth.auth0.authorize_access_token(request)
            request.session["user"] = token
            return redirect(request.build_absolute_uri(reverse("index")))

        def logout(request):
            request.session.clear()

            return redirect(
                f"https://{settings.AUTH0_DOMAIN}/v2/logout?"
                + urlencode(
                    {
                        "returnTo": request.build_absolute_uri(reverse("index")),
                        "client_id": settings.AUTH0_CLIENT_ID,
                    },
                    quote_via=quote_plus,
                ),
            )

        def index(request):
            return render(
                request,
                "index.html",
                context={
                    "session": request.session.get("user"),
                    "pretty": json.dumps(request.session.get("user"), indent=4),
                },
            )
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```py webappexample/views.py highlight={1-18} lines  theme={null}
        import json
        from authlib.integrations.django_client import OAuth
        from django.conf import settings
        from django.shortcuts import redirect, render, redirect
        from django.urls import reverse
        from urllib.parse import quote_plus, urlencode

        oauth = OAuth()

        oauth.register(
            "auth0",
            client_id=settings.AUTH0_CLIENT_ID,
            client_secret=settings.AUTH0_CLIENT_SECRET,
            client_kwargs={
                "scope": "openid profile email",
            },
            server_metadata_url=f"https://{settings.AUTH0_DOMAIN}/.well-known/openid-configuration",
        )

        def login(request):
            return oauth.auth0.authorize_redirect(
                request, request.build_absolute_uri(reverse("callback"))
            )

        def callback(request):
            token = oauth.auth0.authorize_access_token(request)
            request.session["user"] = token
            return redirect(request.build_absolute_uri(reverse("index")))

        def logout(request):
            request.session.clear()

            return redirect(
                f"https://{settings.AUTH0_DOMAIN}/v2/logout?"
                + urlencode(
                    {
                        "returnTo": request.build_absolute_uri(reverse("index")),
                        "client_id": settings.AUTH0_CLIENT_ID,
                    },
                    quote_via=quote_plus,
                ),
            )

        def index(request):
            return render(
                request,
                "index.html",
                context={
                    "session": request.session.get("user"),
                    "pretty": json.dumps(request.session.get("user"), indent=4),
                },
            )
        ```

        ```html webappexample/templates/index.html lines theme={null}
        <html>
        <head>
          <meta charset="utf-8" />
          <title>Auth0 Example</title>
        </head>
        <body>
        {% if session %}
          <h1>Welcome {{session.userinfo.name}}!</h1>
          <p><a href="{% url 'logout' %}">Logout</a></p>
          <div><pre>{{pretty}}</pre></div>
        {% else %}
          <h1>Welcome Guest</h1>
          <p><a href="{% url 'login' %}">Login</a></p>
        {% endif %}
        </body>
        </html>
        ```

        ```py webappexample/settings.py lines  theme={null}
        import os
        from pathlib import Path
        from dotenv import load_dotenv, find_dotenv

        # Build paths inside the project like this: BASE_DIR / 'subdir'.
        BASE_DIR = Path(__file__).resolve().parent.parent
        TEMPLATE_DIR = os.path.join(BASE_DIR, "webappexample", "templates")

        # ... other settings ...

        TEMPLATES = [
            {
        # Leave other lines as they are; we're just updating `DIRS`.
        "DIRS": [TEMPLATE_DIR],
            },
        ]

        # ... other settings ...

        # Load environment definition file
        ENV_FILE = find_dotenv()
        if ENV_FILE:
            load_dotenv(ENV_FILE)

        # Load Auth0 application settings into memory
        AUTH0_DOMAIN = os.environ.get("AUTH0_DOMAIN")
        AUTH0_CLIENT_ID = os.environ.get("AUTH0_CLIENT_ID")
        AUTH0_CLIENT_SECRET = os.environ.get("AUTH0_CLIENT_SECRET")
        ```

        ```py webappexample/urls.py lines theme={null}
        from django.urls import path

        from . import views

        urlpatterns = [
            path("", views.index, name="index"),
            path("login", views.login, name="login"),
            path("logout", views.logout, name="logout"),
            path("callback", views.callback, name="callback"),
        ]
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```py webappexample/views.py highlight={20-52} lines  theme={null}
        import json
        from authlib.integrations.django_client import OAuth
        from django.conf import settings
        from django.shortcuts import redirect, render, redirect
        from django.urls import reverse
        from urllib.parse import quote_plus, urlencode

        oauth = OAuth()

        oauth.register(
            "auth0",
            client_id=settings.AUTH0_CLIENT_ID,
            client_secret=settings.AUTH0_CLIENT_SECRET,
            client_kwargs={
                "scope": "openid profile email",
            },
            server_metadata_url=f"https://{settings.AUTH0_DOMAIN}/.well-known/openid-configuration",
        )

        def login(request):
            return oauth.auth0.authorize_redirect(
                request, request.build_absolute_uri(reverse("callback"))
            )

        def callback(request):
            token = oauth.auth0.authorize_access_token(request)
            request.session["user"] = token
            return redirect(request.build_absolute_uri(reverse("index")))

        def logout(request):
            request.session.clear()

            return redirect(
                f"https://{settings.AUTH0_DOMAIN}/v2/logout?"
                + urlencode(
                    {
                        "returnTo": request.build_absolute_uri(reverse("index")),
                        "client_id": settings.AUTH0_CLIENT_ID,
                    },
                    quote_via=quote_plus,
                ),
            )

        def index(request):
            return render(
                request,
                "index.html",
                context={
                    "session": request.session.get("user"),
                    "pretty": json.dumps(request.session.get("user"), indent=4),
                },
            )
        ```

        ```html webappexample/templates/index.html lines theme={null}
        <html>
        <head>
          <meta charset="utf-8" />
          <title>Auth0 Example</title>
        </head>
        <body>
        {% if session %}
          <h1>Welcome {{session.userinfo.name}}!</h1>
          <p><a href="{% url 'logout' %}">Logout</a></p>
          <div><pre>{{pretty}}</pre></div>
        {% else %}
          <h1>Welcome Guest</h1>
          <p><a href="{% url 'login' %}">Login</a></p>
        {% endif %}
        </body>
        </html>
        ```

        ```py webappexample/settings.py lines  theme={null}
        import os
        from pathlib import Path
        from dotenv import load_dotenv, find_dotenv

        # Build paths inside the project like this: BASE_DIR / 'subdir'.
        BASE_DIR = Path(__file__).resolve().parent.parent
        TEMPLATE_DIR = os.path.join(BASE_DIR, "webappexample", "templates")

        # ... other settings ...

        TEMPLATES = [
            {
        # Leave other lines as they are; we're just updating `DIRS`.
        "DIRS": [TEMPLATE_DIR],
            },
        ]

        # ... other settings ...

        # Load environment definition file
        ENV_FILE = find_dotenv()
        if ENV_FILE:
            load_dotenv(ENV_FILE)

        # Load Auth0 application settings into memory
        AUTH0_DOMAIN = os.environ.get("AUTH0_DOMAIN")
        AUTH0_CLIENT_ID = os.environ.get("AUTH0_CLIENT_ID")
        AUTH0_CLIENT_SECRET = os.environ.get("AUTH0_CLIENT_SECRET")
        ```

        ```py webappexample/urls.py lines theme={null}
        from django.urls import path

        from . import views

        urlpatterns = [
            path("", views.index, name="index"),
            path("login", views.login, name="login"),
            path("logout", views.logout, name="logout"),
            path("callback", views.callback, name="callback"),
        ]
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```py webappexample/urls.py lines theme={null}
        from django.urls import path

        from . import views

        urlpatterns = [
            path("", views.index, name="index"),
            path("login", views.login, name="login"),
            path("logout", views.logout, name="logout"),
            path("callback", views.callback, name="callback"),
        ]
        ```

        ```html webappexample/templates/index.html lines theme={null}
        <html>
        <head>
          <meta charset="utf-8" />
          <title>Auth0 Example</title>
        </head>
        <body>
        {% if session %}
          <h1>Welcome {{session.userinfo.name}}!</h1>
          <p><a href="{% url 'logout' %}">Logout</a></p>
          <div><pre>{{pretty}}</pre></div>
        {% else %}
          <h1>Welcome Guest</h1>
          <p><a href="{% url 'login' %}">Login</a></p>
        {% endif %}
        </body>
        </html>
        ```

        ```py webappexample/settings.py lines  theme={null}
        import os
        from pathlib import Path
        from dotenv import load_dotenv, find_dotenv

        # Build paths inside the project like this: BASE_DIR / 'subdir'.
        BASE_DIR = Path(__file__).resolve().parent.parent
        TEMPLATE_DIR = os.path.join(BASE_DIR, "webappexample", "templates")

        # ... other settings ...

        TEMPLATES = [
            {
        # Leave other lines as they are; we're just updating `DIRS`.
        "DIRS": [TEMPLATE_DIR],
            },
        ]

        # ... other settings ...

        # Load environment definition file
        ENV_FILE = find_dotenv()
        if ENV_FILE:
            load_dotenv(ENV_FILE)

        # Load Auth0 application settings into memory
        AUTH0_DOMAIN = os.environ.get("AUTH0_DOMAIN")
        AUTH0_CLIENT_ID = os.environ.get("AUTH0_CLIENT_ID")
        AUTH0_CLIENT_SECRET = os.environ.get("AUTH0_CLIENT_SECRET")
        ```

        ```py webappexample/views.py highlight={1-18} lines  theme={null}
        import json
        from authlib.integrations.django_client import OAuth
        from django.conf import settings
        from django.shortcuts import redirect, render, redirect
        from django.urls import reverse
        from urllib.parse import quote_plus, urlencode

        oauth = OAuth()

        oauth.register(
            "auth0",
            client_id=settings.AUTH0_CLIENT_ID,
            client_secret=settings.AUTH0_CLIENT_SECRET,
            client_kwargs={
                "scope": "openid profile email",
            },
            server_metadata_url=f"https://{settings.AUTH0_DOMAIN}/.well-known/openid-configuration",
        )

        def login(request):
            return oauth.auth0.authorize_redirect(
                request, request.build_absolute_uri(reverse("callback"))
            )

        def callback(request):
            token = oauth.auth0.authorize_access_token(request)
            request.session["user"] = token
            return redirect(request.build_absolute_uri(reverse("index")))

        def logout(request):
            request.session.clear()

            return redirect(
                f"https://{settings.AUTH0_DOMAIN}/v2/logout?"
                + urlencode(
                    {
                        "returnTo": request.build_absolute_uri(reverse("index")),
                        "client_id": settings.AUTH0_CLIENT_ID,
                    },
                    quote_via=quote_plus,
                ),
            )

        def index(request):
            return render(
                request,
                "index.html",
                context={
                    "session": request.session.get("user"),
                    "pretty": json.dumps(request.session.get("user"), indent=4),
                },
            )
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```html webappexample/templates/index.html lines theme={null}
        <html>
        <head>
          <meta charset="utf-8" />
          <title>Auth0 Example</title>
        </head>
        <body>
        {% if session %}
          <h1>Welcome {{session.userinfo.name}}!</h1>
          <p><a href="{% url 'logout' %}">Logout</a></p>
          <div><pre>{{pretty}}</pre></div>
        {% else %}
          <h1>Welcome Guest</h1>
          <p><a href="{% url 'login' %}">Login</a></p>
        {% endif %}
        </body>
        </html>
        ```

        ```py webappexample/settings.py lines  theme={null}
        import os
        from pathlib import Path
        from dotenv import load_dotenv, find_dotenv

        # Build paths inside the project like this: BASE_DIR / 'subdir'.
        BASE_DIR = Path(__file__).resolve().parent.parent
        TEMPLATE_DIR = os.path.join(BASE_DIR, "webappexample", "templates")

        # ... other settings ...

        TEMPLATES = [
            {
        # Leave other lines as they are; we're just updating `DIRS`.
        "DIRS": [TEMPLATE_DIR],
            },
        ]

        # ... other settings ...

        # Load environment definition file
        ENV_FILE = find_dotenv()
        if ENV_FILE:
            load_dotenv(ENV_FILE)

        # Load Auth0 application settings into memory
        AUTH0_DOMAIN = os.environ.get("AUTH0_DOMAIN")
        AUTH0_CLIENT_ID = os.environ.get("AUTH0_CLIENT_ID")
        AUTH0_CLIENT_SECRET = os.environ.get("AUTH0_CLIENT_SECRET")
        ```

        ```py webappexample/urls.py lines theme={null}
        from django.urls import path

        from . import views

        urlpatterns = [
            path("", views.index, name="index"),
            path("login", views.login, name="login"),
            path("logout", views.logout, name="logout"),
            path("callback", views.callback, name="callback"),
        ]
        ```

        ```py webappexample/views.py highlight={1-18} lines  theme={null}
        import json
        from authlib.integrations.django_client import OAuth
        from django.conf import settings
        from django.shortcuts import redirect, render, redirect
        from django.urls import reverse
        from urllib.parse import quote_plus, urlencode

        oauth = OAuth()

        oauth.register(
            "auth0",
            client_id=settings.AUTH0_CLIENT_ID,
            client_secret=settings.AUTH0_CLIENT_SECRET,
            client_kwargs={
                "scope": "openid profile email",
            },
            server_metadata_url=f"https://{settings.AUTH0_DOMAIN}/.well-known/openid-configuration",
        )

        def login(request):
            return oauth.auth0.authorize_redirect(
                request, request.build_absolute_uri(reverse("callback"))
            )

        def callback(request):
            token = oauth.auth0.authorize_access_token(request)
            request.session["user"] = token
            return redirect(request.build_absolute_uri(reverse("index")))

        def logout(request):
            request.session.clear()

            return redirect(
                f"https://{settings.AUTH0_DOMAIN}/v2/logout?"
                + urlencode(
                    {
                        "returnTo": request.build_absolute_uri(reverse("index")),
                        "client_id": settings.AUTH0_CLIENT_ID,
                    },
                    quote_via=quote_plus,
                ),
            )

        def index(request):
            return render(
                request,
                "index.html",
                context={
                    "session": request.session.get("user"),
                    "pretty": json.dumps(request.session.get("user"), indent=4),
                },
            )
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>
  </SideMenu>
</Recipe>


# Add Login to Your Express Application
Source: https://auth0.com/docs/quickstart/webapp/express/index

This guide demonstrates how to integrate Auth0, add authentication, and display user profile information in an Express.js web application using the express-openid-connect SDK.

<Accordion title="Use AI to integrate Auth0" icon="microchip-ai">
  If you use an AI coding assistant like Claude Code, Cursor, or GitHub Copilot, you can add Auth0 authentication automatically in minutes using [agent skills](https://agentskills.io/home).

  **Install:**

  ```bash theme={null}
  npx skills add https://github.com/auth0/agent-skills --skill auth0-express
  ```

  **Then ask your AI assistant:**

  ```text theme={null}
  Add Auth0 authentication to my Express app
  ```

  Your AI assistant will automatically create your Auth0 application, fetch credentials, install `express-openid-connect`, configure the middleware, and set up your routes. [Full agent skills documentation →](/quickstart/agent-skills)
</Accordion>

<Note>
  **Prerequisites:** Before you begin, ensure you have the following installed:

  * [Node.js](https://nodejs.org/) 18 LTS or newer
  * [npm](https://www.npmjs.com/) 10+ or [yarn](https://yarnpkg.com/) 1.22+
  * [jq](https://jqlang.github.io/jq/) - Required for Auth0 CLI setup (optional)

  **Express Version Compatibility:** This quickstart works with Express 4.17.0 and newer.
</Note>

## Get Started

This guide demonstrates how to integrate Auth0, add authentication, and display user profile information in an Express.js web application using the `express-openid-connect` SDK.

***

## 1. Create a new project

Create a new directory for your Express application and initialize a Node.js project.

```bash theme={null}
mkdir auth0-express && cd auth0-express
```

```bash theme={null}
npm init -y
```

Create the project structure:

```bash theme={null}
touch index.js .env
```

***

## 2. Install the Auth0 Express SDK

Install `express-openid-connect` along with Express and dotenv for environment variable management.

```bash theme={null}
npm install express express-openid-connect dotenv
```

For development, install nodemon to automatically restart your server on file changes:

```bash theme={null}
npm install --save-dev nodemon
```

Update your `package.json` to add start scripts:

📁 **package.json**

```json theme={null}
{
  "name": "auth0-express",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js"
  },
  "dependencies": {
    "dotenv": "^16.3.1",
    "express": "^4.18.2",
    "express-openid-connect": "^2.17.1"
  },
  "devDependencies": {
    "nodemon": "^3.0.2"
  }
}
```

***

## 3. Setup your Auth0 App

Next, you need to create a new application on your Auth0 tenant and add the environment variables to your project.

You can choose to do this automatically by running a CLI command or manually via the Dashboard:

<Tabs>
  <Tab title="CLI">
    Run the following shell command in your project's root directory to create an Auth0 application and generate your `.env` file:

    **macOS / Linux:**

    ```bash theme={null}
    AUTH0_APP_NAME="My Express App" && \
    auth0 apps create -n "${AUTH0_APP_NAME}" -t regular \
      --callbacks http://localhost:3000 \
      --logout-urls http://localhost:3000 \
      --json | jq -r '"ISSUER_BASE_URL=https://\(.domain)\nCLIENT_ID=\(.client_id)\nSECRET='$(openssl rand -hex 32)'\nBASE_URL=http://localhost:3000"' > .env
    ```

    **Windows (PowerShell):**

    ```powershell theme={null}
    $appName = "My Express App"
    auth0 apps create -n $appName -t regular `
      --callbacks http://localhost:3000 `
      --logout-urls http://localhost:3000 `
      --json | ConvertFrom-Json | ForEach-Object {
        "ISSUER_BASE_URL=https://$($_.domain)`nCLIENT_ID=$($_.client_id)`nSECRET=$([guid]::NewGuid().ToString())`nBASE_URL=http://localhost:3000"
      } | Out-File .env -Encoding utf8
    ```

    <Note>
      If you haven't installed the Auth0 CLI yet, run:

      ```bash theme={null}
      brew tap auth0/auth0-cli && brew install auth0
      ```

      Then authenticate with `auth0 login`.
    </Note>
  </Tab>

  <Tab title="Dashboard">
    1. Go to the [Auth0 Dashboard](https://manage.auth0.com/dashboard/)
    2. Navigate to **Applications** → **Create Application**
    3. Enter a name for your application (e.g., "My Express App")
    4. Select **Regular Web Applications** and click **Create**
    5. In the **Settings** tab, configure the following:

    | Setting               | Value                   |
    | --------------------- | ----------------------- |
    | Allowed Callback URLs | `http://localhost:3000` |
    | Allowed Logout URLs   | `http://localhost:3000` |

    6. Scroll down and click **Save Changes**
    7. Copy the **Domain** and **Client ID** values from the **Basic Information** section

    Create your `.env` file with the following values:

    📁 **.env**

    ```bash theme={null}
    ISSUER_BASE_URL=https://YOUR_AUTH0_DOMAIN
    CLIENT_ID=YOUR_CLIENT_ID
    SECRET=use-a-long-random-string-at-least-32-characters
    BASE_URL=http://localhost:3000
    ```

    <Warning>
      Replace `YOUR_AUTH0_DOMAIN` with your Auth0 tenant domain (e.g., `dev-abc123.us.auth0.com`) and `YOUR_CLIENT_ID` with your application's Client ID from the dashboard.
    </Warning>

    Generate a secure secret for session encryption:

    ```bash theme={null}
    openssl rand -hex 32
    ```

    Copy the output and use it as the `SECRET` value in your `.env` file.
  </Tab>
</Tabs>

***

## 4. Configure the middleware

Add the Auth0 middleware to your Express application. The `auth()` middleware handles session management and automatically creates `/login`, `/logout`, and `/callback` routes.

📁 **index.js**

```javascript theme={null}
require('dotenv').config();
const express = require('express');
const { auth } = require('express-openid-connect');

const app = express();
const port = process.env.PORT || 3000;

// Auth0 configuration
const config = {
  authRequired: false,      // Allow public routes
  auth0Logout: true,        // Use Auth0 logout endpoint
  secret: process.env.SECRET,
  baseURL: process.env.BASE_URL,
  clientID: process.env.CLIENT_ID,
  issuerBaseURL: process.env.ISSUER_BASE_URL,
};

// Apply the auth middleware
app.use(auth(config));

// Home route - public
app.get('/', (req, res) => {
  res.send(req.oidc.isAuthenticated() ? 'Logged in' : 'Logged out');
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});
```

**What this does:**

* `authRequired: false` allows both authenticated and unauthenticated users to access routes by default
* `auth0Logout: true` ensures users are logged out from Auth0 as well as your app
* The middleware automatically provides routes at `/login`, `/logout`, and `/callback`
* User session is stored in an encrypted cookie

***

## 5. Create login, logout, and profile routes

Now add routes to display login/logout links and a protected profile page.

📁 **index.js**

```javascript theme={null}
require('dotenv').config();
const express = require('express');
const { auth, requiresAuth } = require('express-openid-connect');

const app = express();
const port = process.env.PORT || 3000;

// Auth0 configuration
const config = {
  authRequired: false,
  auth0Logout: true,
  secret: process.env.SECRET,
  baseURL: process.env.BASE_URL,
  clientID: process.env.CLIENT_ID,
  issuerBaseURL: process.env.ISSUER_BASE_URL,
};

// Apply the auth middleware
app.use(auth(config));

// Home route - shows login/logout status
app.get('/', (req, res) => {
  const isAuthenticated = req.oidc.isAuthenticated();

  res.send(`
    <html>
      <head>
        <title>Auth0 Express Quickstart</title>
        <style>
          body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; padding: 2rem; max-width: 600px; margin: 0 auto; }
          a { color: #0066cc; text-decoration: none; margin-right: 1rem; }
          a:hover { text-decoration: underline; }
          .status { padding: 1rem; border-radius: 4px; margin: 1rem 0; }
          .logged-in { background: #d4edda; color: #155724; }
          .logged-out { background: #f8d7da; color: #721c24; }
        </style>
      </head>
      <body>
        <h1>Auth0 Express Quickstart</h1>
        <div class="status ${isAuthenticated ? 'logged-in' : 'logged-out'}">
          ${isAuthenticated ? '✓ You are logged in' : '✗ You are logged out'}
        </div>
        <nav>
          ${isAuthenticated
            ? '<a href="/profile">Profile</a> | <a href="/logout">Logout</a>'
            : '<a href="/login">Login</a>'}
        </nav>
      </body>
    </html>
  `);
});

// Protected profile route - requires authentication
app.get('/profile', requiresAuth(), (req, res) => {
  const user = req.oidc.user;

  res.send(`
    <html>
      <head>
        <title>Profile - Auth0 Express</title>
        <style>
          body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; padding: 2rem; max-width: 600px; margin: 0 auto; }
          a { color: #0066cc; text-decoration: none; }
          img { border-radius: 50%; }
          pre { background: #f4f4f4; padding: 1rem; border-radius: 4px; overflow-x: auto; }
          .card { border: 1px solid #ddd; border-radius: 8px; padding: 1.5rem; margin: 1rem 0; }
        </style>
      </head>
      <body>
        <h1>User Profile</h1>
        <div class="card">
          ${user.picture ? `<img src="${user.picture}" alt="Profile" width="80" />` : ''}
          <h2>${user.name || user.nickname || 'User'}</h2>
          <p><strong>Email:</strong> ${user.email || 'N/A'}</p>
        </div>
        <h3>Full User Object</h3>
        <pre>${JSON.stringify(user, null, 2)}</pre>
        <nav>
          <a href="/">← Back to Home</a> | <a href="/logout">Logout</a>
        </nav>
      </body>
    </html>
  `);
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});
```

**Key points:**

* `requiresAuth()` middleware protects the `/profile` route - unauthenticated users are redirected to login
* `req.oidc.user` contains the authenticated user's profile information
* `req.oidc.isAuthenticated()` returns a boolean indicating login status
* Login and logout routes (`/login`, `/logout`) are automatically created by the `auth()` middleware

***

## 6. Run your app

Start the development server:

```bash theme={null}
npm run dev
```

Open your browser to [http://localhost:3000](http://localhost:3000).

<Check>
  **Checkpoint**

  You should now have a fully functional Auth0 login page. When you:

  1. Click "Login" - you're redirected to Auth0's Universal Login page
  2. Complete authentication - you're redirected back to your app
  3. Visit "/profile" - you see your user information
  4. Click "Logout" - you're logged out of both your app and Auth0
</Check>

***

## Advanced Usage

<AccordionGroup>
  <Accordion title="Protecting Specific Routes with requiresAuth()">
    Use the `requiresAuth()` middleware to protect individual routes that require authentication:

    ```javascript theme={null}
    const { auth, requiresAuth } = require('express-openid-connect');

    app.use(auth({ authRequired: false }));

    // Public route
    app.get('/', (req, res) => {
      res.send('Welcome! This is public.');
    });

    // Protected routes
    app.get('/dashboard', requiresAuth(), (req, res) => {
      res.send(`Hello ${req.oidc.user.name}, welcome to your dashboard!`);
    });

    app.get('/settings', requiresAuth(), (req, res) => {
      res.send('Settings page - only for authenticated users');
    });
    ```

    You can also protect all routes under a specific path using Express Router:

    ```javascript theme={null}
    const protectedRouter = express.Router();

    // All routes in this router require authentication
    protectedRouter.use(requiresAuth());

    protectedRouter.get('/dashboard', (req, res) => {
      res.send('Protected dashboard');
    });

    protectedRouter.get('/settings', (req, res) => {
      res.send('Protected settings');
    });

    app.use('/app', protectedRouter);
    // Routes: /app/dashboard, /app/settings are all protected
    ```
  </Accordion>

  <Accordion title="Calling Protected APIs with Access Tokens">
    To call external APIs that require an access token, configure the SDK to request one:

    📁 **index.js** (updated configuration)

    ```javascript theme={null}
    const config = {
      authRequired: false,
      auth0Logout: true,
      secret: process.env.SECRET,
      baseURL: process.env.BASE_URL,
      clientID: process.env.CLIENT_ID,
      issuerBaseURL: process.env.ISSUER_BASE_URL,
      clientSecret: process.env.CLIENT_SECRET,  // Required for code flow
      authorizationParams: {
        response_type: 'code',
        audience: process.env.API_AUDIENCE,     // Your API identifier
        scope: 'openid profile email read:data',
      },
    };
    ```

    Add these to your `.env` file:

    ```bash theme={null}
    CLIENT_SECRET=your_client_secret_from_dashboard
    API_AUDIENCE=https://your-api.example.com
    ```

    Then use the access token to call your API:

    ```javascript theme={null}
    app.get('/api-data', requiresAuth(), async (req, res) => {
      try {
        let { token_type, access_token, isExpired, refresh } = req.oidc.accessToken;

        // Refresh the token if expired
        if (isExpired()) {
          const refreshed = await refresh();
          access_token = refreshed.access_token;
        }

        // Call your protected API
        const response = await fetch('https://your-api.example.com/data', {
          headers: {
            Authorization: `${token_type} ${access_token}`,
          },
        });

        const data = await response.json();
        res.json(data);
      } catch (error) {
        console.error('API call failed:', error);
        res.status(500).json({ error: 'Failed to fetch data' });
      }
    });
    ```

    <Note>
      To get refresh tokens, add `offline_access` to your scope:

      ```javascript theme={null}
      scope: 'openid profile email offline_access read:data',
      ```
    </Note>
  </Accordion>

  <Accordion title="Using Claim-Based Authorization">
    Protect routes based on user claims (roles, permissions, etc.):

    ```javascript theme={null}
    const { auth, requiresAuth, claimEquals, claimIncludes, claimCheck } = require('express-openid-connect');

    app.use(auth({ authRequired: false }));

    // Only users with role = 'admin'
    app.get('/admin', claimEquals('role', 'admin'), (req, res) => {
      res.send('Admin dashboard');
    });

    // Users whose roles array includes 'editor'
    app.get('/editor', claimIncludes('roles', 'editor'), (req, res) => {
      res.send('Editor dashboard');
    });

    // Custom claim check with logic
    app.get('/premium', claimCheck((req, claims) => {
      return claims.subscription === 'premium' || claims.role === 'admin';
    }), (req, res) => {
      res.send('Premium content');
    });
    ```

    <Note>
      Claims like `role` must be added to your tokens via Auth0 Rules or Actions. [Learn more about adding custom claims](https://auth0.com/docs/customize/actions/flows-and-triggers/login-flow/add-user-roles-to-id-and-access-tokens).
    </Note>
  </Accordion>

  <Accordion title="Custom Session Store (Redis)">
    For production environments or when running multiple server instances, use a custom session store:

    ```bash theme={null}
    npm install redis connect-redis
    ```

    ```javascript theme={null}
    const { auth } = require('express-openid-connect');
    const { createClient } = require('redis');
    const RedisStore = require('connect-redis').default;

    // Create Redis client
    const redisClient = createClient({
      url: process.env.REDIS_URL || 'redis://localhost:6379',
    });
    redisClient.connect().catch(console.error);

    const config = {
      authRequired: false,
      auth0Logout: true,
      secret: process.env.SECRET,
      baseURL: process.env.BASE_URL,
      clientID: process.env.CLIENT_ID,
      issuerBaseURL: process.env.ISSUER_BASE_URL,
      session: {
        store: new RedisStore({ client: redisClient }),
      },
    };

    app.use(auth(config));
    ```

    **When to use a custom session store:**

    * Running multiple server instances (load balancing)
    * Session data exceeds cookie size limits (\~4KB)
    * Need session persistence across server restarts
    * Using back-channel logout
  </Accordion>

  <Accordion title="Error Handling">
    Add proper error handling for authentication errors:

    ```javascript theme={null}
    const { auth } = require('express-openid-connect');

    app.use(auth({
      authRequired: false,
      auth0Logout: true,
      secret: process.env.SECRET,
      baseURL: process.env.BASE_URL,
      clientID: process.env.CLIENT_ID,
      issuerBaseURL: process.env.ISSUER_BASE_URL,
      errorOnRequiredAuth: true,  // Return 401 instead of redirecting for API routes
    }));

    // Custom error handler
    app.use((err, req, res, next) => {
      // Handle authentication errors
      if (err.statusCode === 401) {
        // For API requests, return JSON
        if (req.accepts('json')) {
          return res.status(401).json({
            error: 'Authentication required',
            login_url: '/login',
          });
        }
        // For browser requests, redirect to login
        return res.redirect('/login');
      }

      // Log the error (don't expose details to client)
      console.error('Application error:', err.message);

      res.status(err.statusCode || 500).json({
        error: 'An unexpected error occurred',
      });
    });
    ```
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Common Issues and Solutions">
    ### "Invalid state" error after login

    **Problem:** State mismatch between the authentication request and callback.

    **Solutions:**

    1. Ensure you're using HTTPS in production
    2. Check that cookies are being set correctly (not blocked by browser)
    3. Verify callback URL matches exactly in Auth0 Dashboard

    ### "req.oidc is undefined"

    **Problem:** The `auth()` middleware is not applied before accessing `req.oidc`.

    **Solution:** Ensure `app.use(auth(config))` is called before any route that accesses `req.oidc`:

    ```javascript theme={null}
    // ✅ Correct order
    app.use(auth(config));
    app.get('/profile', requiresAuth(), (req, res) => { ... });

    // ❌ Wrong order
    app.get('/profile', requiresAuth(), (req, res) => { ... });
    app.use(auth(config));
    ```

    ### Session too large / Cookie errors

    **Problem:** User session data exceeds cookie size limits.

    **Solution:** Use a custom session store like Redis:

    ```javascript theme={null}
    session: {
      store: new RedisStore({ client: redisClient }),
    }
    ```

    ### Callback URL mismatch

    **Problem:** "Callback URL mismatch" error from Auth0.

    **Solution:**

    1. Go to your Auth0 Dashboard → Applications → Your App → Settings
    2. Add `http://localhost:3000` (or your production URL) to **Allowed Callback URLs**
    3. The URL must match **exactly** (including trailing slashes)

    ### Environment variables not loading

    **Problem:** Configuration values are `undefined`.

    **Solution:**

    1. Ensure `require('dotenv').config()` is at the top of your entry file
    2. Verify `.env` file is in the root directory
    3. Check for typos in variable names

    ```javascript theme={null}
    // Debug: Log config values (remove in production!)
    console.log('Config check:', {
      hasSecret: !!process.env.SECRET,
      hasClientID: !!process.env.CLIENT_ID,
      issuerBaseURL: process.env.ISSUER_BASE_URL,
    });
    ```
  </Accordion>
</AccordionGroup>

***

## Next Steps

Now that you have authentication working, consider exploring:

* **[Add Authorization](https://auth0.com/docs/quickstart/webapp/express/02-user-profile)** - Implement role-based access control
* **[Call Protected APIs](https://auth0.com/docs/quickstart/webapp/express/03-authorization)** - Use access tokens to call your backend APIs
* **[Customize Universal Login](https://auth0.com/docs/customize/universal-login-pages)** - Brand your login experience
* **[Add Social Connections](https://auth0.com/docs/connections/social)** - Enable Google, GitHub, and other social logins
* **[Implement MFA](https://auth0.com/docs/secure/multi-factor-authentication)** - Add multi-factor authentication

***

## Resources

* **[express-openid-connect GitHub](https://github.com/auth0/express-openid-connect)** - Source code and examples
* **[API Documentation](https://auth0.github.io/express-openid-connect/)** - Complete API reference
* **[Auth0 Express Sample App](https://github.com/auth0-samples/auth0-express-webapp-sample)** - Full sample application
* **[Auth0 Community](https://community.auth0.com/)** - Get help from the community


# Add Login to Your FastAPI Application
Source: https://auth0.com/docs/quickstart/webapp/fastapi/index

This guide demonstrates how to integrate Auth0, add authentication, and display user profile information in a Python application using the Auth0 FastAPI SDK.

<Accordion title="AI Prompt" icon="microchip-ai">
  **Using AI to integrate Auth0?** Add this prompt to Cursor, Windsurf, Copilot, Claude Code or your favourite AI-powered IDE to speed up development.

  ```markdown expandable theme={null}
  Integrate the Auth0 FastAPI SDK into a Python application

  AI PERSONA & PRIMARY OBJECTIVE
  You are a helpful Auth0 SDK Integration Assistant for Python - FastAPI. Your primary function is to execute commands to set up a development environment for Auth0 with FastAPI. Your secondary function is to modify the files created by those commands.

  CRITICAL BEHAVIORAL INSTRUCTIONS
  1.  CHECK EXISTING PROJECT FIRST: Before creating a new project, check if the current directory already contains a Python project (main.py, requirements.txt, or pyproject.toml). If it does, skip project creation and work with the existing project.
  2.  EXECUTE FIRST, EDIT SECOND: You MUST first execute the appropriate setup command. Do not show, suggest, or create any files until the setup is complete.
  3.  NO PLANNING: DO NOT propose a directory structure. DO NOT show a file tree. Your first action must be to run the appropriate command.
  4.  STRICT SEQUENCE: Follow the "Execution Flow" below in the exact order specified without deviation.
  5.  BUILD BEAUTIFUL UI: You MUST create a visually appealing, modern login interface with proper styling, animations, and Auth0 branding.
  6.  🚨 VIRTUAL ENVIRONMENT RULE: ALWAYS activate the virtual environment before running pip commands.

  EXECUTION FLOW

  Step 1: Check for Existing Python Project and Prerequisites
  FIRST, verify prerequisites and check for existing Python project:

    # Check if Python and pip are available
    python --version && pip --version

  Then examine the current directory:

    # Check for existing Python project
    if [ -f "main.py" ] || [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
      echo "Found existing Python project"
      ls -la
    else
      echo "No Python project found, will create new project"
    fi

  Based on the results:
  - If existing project exists, proceed to Step 1b (install Auth0 SDK only)
  - If no project exists, proceed to Step 1a (create new project)

  Step 1a: Create New Project Directory and Virtual Environment

    mkdir auth0-fastapi-app && cd auth0-fastapi-app
    python -m venv venv
    source venv/bin/activate  # On Windows: venv\Scripts\activate

  Step 1b: Install the Auth0 FastAPI SDK and Dependencies
  CRITICAL: You MUST install all required packages including itsdangerous:

    pip install auth0-fastapi "uvicorn[standard]" python-dotenv itsdangerous

  ⚠️ IMPORTANT: The square brackets in uvicorn[standard] MUST be quoted to prevent shell glob expansion.

  Step 2: Setup Auth0 environment configuration

  Step 2.1a: Run Auth0 CLI setup command for your OS:

  If MacOS, execute the following command:

    AUTH0_APP_NAME="My FastAPI App" && brew tap auth0/auth0-cli && brew install auth0 && auth0 login --no-input && auth0 apps create -n "${AUTH0_APP_NAME}" -t regular -c http://localhost:3000/auth/callback -l http://localhost:3000 -o http://localhost:3000 --reveal-secrets --json > auth0-app-details.json && CLIENT_ID=$(jq -r '.client_id' auth0-app-details.json) && CLIENT_SECRET=$(jq -r '.client_secret' auth0-app-details.json) && DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name') && SESSION_SECRET=$(openssl rand -hex 64) && echo "AUTH0_DOMAIN=${DOMAIN}" > .env && echo "AUTH0_CLIENT_ID=${CLIENT_ID}" >> .env && echo "AUTH0_CLIENT_SECRET=${CLIENT_SECRET}" >> .env && echo "SESSION_SECRET=${SESSION_SECRET}" >> .env && echo "APP_BASE_URL=http://localhost:3000" >> .env && rm auth0-app-details.json && echo ".env file created with your Auth0 details:" && cat .env

  If Windows, execute the following command:

    $AppName = "My FastAPI App"; winget install Auth0.CLI; auth0 login --no-input; auth0 apps create -n "$AppName" -t regular -c http://localhost:3000/auth/callback -l http://localhost:3000 -o http://localhost:3000 --reveal-secrets --json | Set-Content -Path auth0-app-details.json; $ClientId = (Get-Content -Raw auth0-app-details.json | ConvertFrom-Json).client_id; $ClientSecret = (Get-Content -Raw auth0-app-details.json | ConvertFrom-Json).client_secret; $Domain = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name; $SessionSecret = -join ((1..128) | ForEach {'{0:X}' -f (Get-Random -Max 16)}); Set-Content -Path .env -Value "AUTH0_DOMAIN=$Domain"; Add-Content -Path .env -Value "AUTH0_CLIENT_ID=$ClientId"; Add-Content -Path .env -Value "AUTH0_CLIENT_SECRET=$ClientSecret"; Add-Content -Path .env -Value "SESSION_SECRET=$SessionSecret"; Add-Content -Path .env -Value "APP_BASE_URL=http://localhost:3000"; Remove-Item auth0-app-details.json; Write-Output ".env file created with your Auth0 details:"; Get-Content .env

  Step 2.1b: Create manual .env template (if automatic setup fails)

    cat > .env << 'EOF'
    AUTH0_DOMAIN=your-auth0-domain.auth0.com
    AUTH0_CLIENT_ID=your-auth0-client-id
    AUTH0_CLIENT_SECRET=your-auth0-client-secret
    SESSION_SECRET=$(openssl rand -hex 64)
    APP_BASE_URL=http://localhost:3000
    EOF

  Step 3: Create main.py with Auth0 integration

  Replace or create main.py with this complete, production-ready code:

    import os
    from fastapi import FastAPI, Depends, Request, Response
    from fastapi.responses import HTMLResponse
    from starlette.middleware.sessions import SessionMiddleware
    from dotenv import load_dotenv

    from auth0_fastapi.config import Auth0Config
    from auth0_fastapi.auth.auth_client import AuthClient
    from auth0_fastapi.server.routes import router, register_auth_routes

    # Load environment variables
    load_dotenv()

    app = FastAPI(title="Auth0 FastAPI Example")

    # Add Session Middleware - required for cookie handling
    app.add_middleware(SessionMiddleware, secret_key=os.getenv("SESSION_SECRET"))

    # Create Auth0Config with your Auth0 credentials
    config = Auth0Config(
        domain=os.getenv("AUTH0_DOMAIN"),
        client_id=os.getenv("AUTH0_CLIENT_ID"),
        client_secret=os.getenv("AUTH0_CLIENT_SECRET"),
        app_base_url=os.getenv("APP_BASE_URL", "http://localhost:3000"),
        secret=os.getenv("SESSION_SECRET"),
    )

    # Instantiate the AuthClient
    auth_client = AuthClient(config)

    # Attach to the FastAPI app state
    app.state.config = config
    app.state.auth_client = auth_client

    # Register authentication routes
    register_auth_routes(router, config)
    app.include_router(router)


    @app.get("/", response_class=HTMLResponse)
    async def home(request: Request, response: Response):
        """Home page with login/logout buttons"""
        store_options = {"request": request, "response": response}
        session = await auth_client.client.get_session(store_options=store_options)

        if session:
            user = await auth_client.client.get_user(store_options=store_options)
            return f"""
            <!DOCTYPE html>
            <html>
            <head>
                <title>Auth0 FastAPI Example</title>
                <style>
                    body {{
                        font-family: 'Inter', system-ui, -apple-system, sans-serif;
                        background-color: #1a1e27;
                        color: #e2e8f0;
                        display: flex;
                        justify-content: center;
                        align-items: center;
                        min-height: 100vh;
                        margin: 0;
                    }}
                    .container {{
                        background-color: #262a33;
                        border-radius: 20px;
                        box-shadow: 0 20px 60px rgba(0, 0, 0, 0.6);
                        padding: 3rem;
                        max-width: 500px;
                        width: 90%;
                        text-align: center;
                    }}
                    .logo {{
                        width: 160px;
                        margin-bottom: 1.5rem;
                    }}
                    h1 {{
                        font-size: 2.8rem;
                        font-weight: 700;
                        color: #f7fafc;
                        margin-bottom: 1rem;
                    }}
                    .success {{
                        font-size: 1.5rem;
                        color: #68d391;
                        font-weight: 600;
                        margin: 1.5rem 0;
                    }}
                    .profile {{
                        background-color: #2d313c;
                        border-radius: 15px;
                        padding: 2rem;
                        margin: 2rem 0;
                    }}
                    .profile-image {{
                        width: 110px;
                        height: 110px;
                        border-radius: 50%;
                        border: 3px solid #63b3ed;
                        margin-bottom: 1rem;
                    }}
                    .profile-name {{
                        font-size: 2rem;
                        font-weight: 600;
                        color: #f7fafc;
                        margin-bottom: 0.5rem;
                    }}
                    .profile-email {{
                        font-size: 1.15rem;
                        color: #a0aec0;
                    }}
                    .button {{
                        padding: 1.1rem 2.8rem;
                        font-size: 1.2rem;
                        font-weight: 600;
                        border-radius: 10px;
                        border: none;
                        cursor: pointer;
                        text-decoration: none;
                        display: inline-block;
                        transition: all 0.3s cubic-bezier(0.25, 0.8, 0.25, 1);
                        box-shadow: 0 8px 20px rgba(0, 0, 0, 0.4);
                        text-transform: uppercase;
                        letter-spacing: 0.08em;
                    }}
                    .button.logout {{
                        background-color: #fc8181;
                        color: #1a1e27;
                    }}
                    .button.logout:hover {{
                        background-color: #e53e3e;
                        transform: translateY(-5px) scale(1.03);
                        box-shadow: 0 12px 25px rgba(0, 0, 0, 0.5);
                    }}
                </style>
            </head>
            <body>
                <div class="container">
                    <img src="https://cdn.auth0.com/quantum-assets/dist/latest/logos/auth0/auth0-lockup-en-ondark.png"
                         alt="Auth0 Logo" class="logo">
                    <h1>Welcome to Auth0 FastAPI</h1>
                    <div class="success">✅ Successfully authenticated!</div>
                    <h2>Your Profile</h2>
                    <div class="profile">
                        <img src="{user.get('picture', '')}"
                             alt="{user.get('name', 'User')}" class="profile-image">
                        <div class="profile-name">{user.get('name', 'User')}</div>
                        <div class="profile-email">{user.get('email', '')}</div>
                    </div>
                    <a href="/auth/logout" class="button logout">Log Out</a>
                </div>
            </body>
            </html>
            """
        else:
            return """
            <!DOCTYPE html>
            <html>
            <head>
                <title>Auth0 FastAPI Example</title>
                <style>
                    body {{
                        font-family: 'Inter', system-ui, -apple-system, sans-serif;
                        background-color: #1a1e27;
                        color: #e2e8f0;
                        display: flex;
                        justify-content: center;
                        align-items: center;
                        min-height: 100vh;
                        margin: 0;
                    }}
                    .container {{
                        background-color: #262a33;
                        border-radius: 20px;
                        box-shadow: 0 20px 60px rgba(0, 0, 0, 0.6);
                        padding: 3rem;
                        max-width: 500px;
                        width: 90%;
                        text-align: center;
                    }}
                    .logo {{
                        width: 160px;
                        margin-bottom: 1.5rem;
                    }}
                    h1 {{
                        font-size: 2.8rem;
                        font-weight: 700;
                        color: #f7fafc;
                        margin-bottom: 1rem;
                    }}
                    .action-card {{
                        background-color: #2d313c;
                        border-radius: 15px;
                        padding: 2.5rem;
                        margin-top: 2rem;
                    }}
                    .action-text {{
                        font-size: 1.25rem;
                        color: #cbd5e0;
                        margin-bottom: 1.8rem;
                    }}
                    .button {{
                        padding: 1.1rem 2.8rem;
                        font-size: 1.2rem;
                        font-weight: 600;
                        border-radius: 10px;
                        border: none;
                        cursor: pointer;
                        text-decoration: none;
                        display: inline-block;
                        transition: all 0.3s cubic-bezier(0.25, 0.8, 0.25, 1);
                        box-shadow: 0 8px 20px rgba(0, 0, 0, 0.4);
                        text-transform: uppercase;
                        letter-spacing: 0.08em;
                    }}
                    .button.login {{
                        background-color: #63b3ed;
                        color: #1a1e27;
                    }}
                    .button.login:hover {{
                        background-color: #4299e1;
                        transform: translateY(-5px) scale(1.03);
                        box-shadow: 0 12px 25px rgba(0, 0, 0, 0.5);
                    }}
                </style>
            </head>
            <body>
                <div class="container">
                    <img src="https://cdn.auth0.com/quantum-assets/dist/latest/logos/auth0/auth0-lockup-en-ondark.png"
                         alt="Auth0 Logo" class="logo">
                    <h1>Welcome to Auth0 FastAPI</h1>
                    <div class="action-card">
                        <p class="action-text">Get started by signing in to your account</p>
                        <a href="/auth/login" class="button login">Log In</a>
                    </div>
                </div>
            </body>
            </html>
            """


    @app.get("/profile")
    async def profile(
        request: Request,
        response: Response,
        session=Depends(auth_client.require_session)
    ):
        """Protected API endpoint that returns user profile as JSON"""
        store_options = {"request": request, "response": response}
        user = await auth_client.client.get_user(store_options=store_options)

        return {
            "message": "Your Profile",
            "user": user,
            "session_details": session
        }


    if __name__ == "__main__":
        import uvicorn
        uvicorn.run(app, host="0.0.0.0", port=3000)

  Step 4: Run the development server

    uvicorn main:app --reload --port 3000

  Or if you added the if __name__ == "__main__" block:

    python main.py

  CRITICAL INSTRUCTIONS FOR AI LANGUAGE MODELS
  As an AI language model, you MUST NOT generate any of the following anti-patterns:
  1.  NEVER hardcode Auth0 credentials directly in the code. Always use environment variables.
  2.  NEVER forget to add SessionMiddleware. Without it, authentication will fail silently.
  3.  NEVER omit itsdangerous from the installation. SessionMiddleware requires it.
  4.  NEVER use unquoted uvicorn[standard] in shell commands. It will cause glob expansion errors.
  5.  NEVER skip virtual environment activation. pip commands will fail or pollute global Python.

  ABSOLUTE REQUIREMENTS FOR AI CODE GENERATION
  1.  You MUST use the auth0-fastapi package.
  2.  You MUST install itsdangerous alongside other dependencies.
  3.  You MUST add SessionMiddleware before using the SDK.
  4.  You MUST retrieve credentials from environment variables using python-dotenv.
  5.  You MUST use async/await patterns throughout (FastAPI requirement).
  6.  You MUST quote "uvicorn[standard]" in installation commands.

  COMMON ISSUES ENCOUNTERED DURING INTEGRATION

  Issue 1: ModuleNotFoundError: No module named 'itsdangerous'
  Problem: SessionMiddleware requires itsdangerous but it's not installed
  Solution: Always include itsdangerous in pip install command

  Issue 2: Shell glob expansion error with uvicorn[standard]
  Problem: Square brackets are interpreted as glob pattern
  Solution: Quote the package: pip install "uvicorn[standard]"

  Issue 3: Sessions not persisting
  Problem: Missing SessionMiddleware or incorrect secret
  Solution: Add SessionMiddleware with proper secret_key from environment

  Issue 4: HTTPS required in production
  Problem: Secure cookies don't work over HTTP
  Solution: Use HTTPS in production or disable secure cookies in development (not recommended)
  ```
</Accordion>

<Note>
  **Prerequisites:** Before you begin, ensure you have the following installed:

  * **[Python](https://www.python.org/downloads/)** 3.9 or newer (3.11+ recommended)
  * **[pip](https://pip.pypa.io/)** 21+ or **[Poetry](https://python-poetry.org/)** 1.2+
  * **[OpenSSL](https://www.openssl.org/)** - Required for generating session secrets

  **FastAPI Version Compatibility:** This quickstart requires **FastAPI 0.115.11+** and **Pydantic 2.12.5+**.
</Note>

## Get Started

This quickstart demonstrates how to add Auth0 authentication to a Python FastAPI Web application. You'll build a secure web app with login, logout, and user profile features using the [Auth0 FastAPI SDK](https://github.com/auth0/auth0-fastapi).

<Steps>
  <Step title="Create a new project">
    Create a new directory for your project and set up a virtual environment:

    ```shellscript theme={null}
    mkdir auth0-fastapi-app && cd auth0-fastapi-app
    ```

    Create and activate a virtual environment:

    ```shellscript theme={null}
    python -m venv venv
    source venv/bin/activate  # On Windows: venv\Scripts\activate
    ```
  </Step>

  <Step title="Install the Auth0 FastAPI SDK">
    <Tabs>
      <Tab title="pip">
        ```shellscript theme={null}
        pip install auth0-fastapi "uvicorn[standard]" python-dotenv itsdangerous
        ```
      </Tab>

      <Tab title="Poetry">
        ```shellscript theme={null}
        poetry add auth0-fastapi "uvicorn[standard]" python-dotenv itsdangerous
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Setup your Auth0 App">
    Next up, you need to create a new app on your Auth0 tenant and add the environment variables to your project.

    You can choose to do this automatically by running a CLI command or do it manually via the Dashboard:

    <Tabs>
      <Tab title="CLI">
        Run the following shell command on your project's root directory to create an Auth0 app and generate a `.env` file:

        <CodeGroup>
          ```shellscript Mac theme={null}
          AUTH0_APP_NAME="My FastAPI App" && brew tap auth0/auth0-cli && brew install auth0 && auth0 login --no-input && auth0 apps create -n "${AUTH0_APP_NAME}" -t regular -c http://localhost:3000/auth/callback -l http://localhost:3000 -o http://localhost:3000 --reveal-secrets --json > auth0-app-details.json && CLIENT_ID=$(jq -r '.client_id' auth0-app-details.json) && CLIENT_SECRET=$(jq -r '.client_secret' auth0-app-details.json) && DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name') && SESSION_SECRET=$(openssl rand -hex 64) && echo "AUTH0_DOMAIN=${DOMAIN}" > .env && echo "AUTH0_CLIENT_ID=${CLIENT_ID}" >> .env && echo "AUTH0_CLIENT_SECRET=${CLIENT_SECRET}" >> .env && echo "SESSION_SECRET=${SESSION_SECRET}" >> .env && echo "APP_BASE_URL=http://localhost:3000" >> .env && rm auth0-app-details.json && echo ".env file created with your Auth0 details:" && cat .env
          ```

          ```shellscript Windows theme={null}
          $AppName = "My FastAPI App"; winget install Auth0.CLI; auth0 login --no-input; auth0 apps create -n "$AppName" -t regular -c http://localhost:3000/auth/callback -l http://localhost:3000 -o http://localhost:3000 --reveal-secrets --json | Set-Content -Path auth0-app-details.json; $ClientId = (Get-Content -Raw auth0-app-details.json | ConvertFrom-Json).client_id; $ClientSecret = (Get-Content -Raw auth0-app-details.json | ConvertFrom-Json).client_secret; $Domain = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name; $SessionSecret = -join ((1..128) | ForEach {'{0:X}' -f (Get-Random -Max 16)}); Set-Content -Path .env -Value "AUTH0_DOMAIN=$Domain"; Add-Content -Path .env -Value "AUTH0_CLIENT_ID=$ClientId"; Add-Content -Path .env -Value "AUTH0_CLIENT_SECRET=$ClientSecret"; Add-Content -Path .env -Value "SESSION_SECRET=$SessionSecret"; Add-Content -Path .env -Value "APP_BASE_URL=http://localhost:3000"; Remove-Item auth0-app-details.json; Write-Output ".env file created with your Auth0 details:"; Get-Content .env
          ```
        </CodeGroup>
      </Tab>

      <Tab title="Dashboard">
        Before you start, create a `.env` file in your project's root directory:

        ```shellscript .env theme={null}
        AUTH0_DOMAIN=YOUR_AUTH0_APP_DOMAIN
        AUTH0_CLIENT_ID=YOUR_AUTH0_APP_CLIENT_ID
        AUTH0_CLIENT_SECRET=YOUR_AUTH0_APP_CLIENT_SECRET
        SESSION_SECRET=YOUR_SESSION_SECRET
        APP_BASE_URL=http://localhost:3000
        ```

        1. Head to the [Auth0 Dashboard](https://manage.auth0.com/dashboard/)
        2. Click on **Applications** > **Applications** > **Create Application**
        3. In the popup, enter a name for your app, select `Regular Web Application` as the app type and click **Create**
        4. Switch to the **Settings** tab on the Application Details page
        5. Replace the values in the `.env` file with the **Domain**, **Client ID**, and **Client Secret** values from the dashboard
        6. Generate a session secret by running: `openssl rand -hex 64` and use it for `SESSION_SECRET`

        Finally, on the **Settings** tab of your Application Details page, configure the following URLs:

        **Allowed Callback URLs:**

        ```
        http://localhost:3000/auth/callback
        ```

        **Allowed Logout URLs:**

        ```
        http://localhost:3000
        ```

        **Allowed Web Origins:**

        ```
        http://localhost:3000
        ```

        <Info>
          **Allowed Callback URLs** are a critical security measure to ensure users are safely returned to your application after authentication. Without a matching URL, the login process will fail, and users will be blocked by an Auth0 error page instead of accessing your app.

          **Allowed Logout URLs** are essential for providing a seamless user experience upon signing out. Without a matching URL, users will not be redirected back to your application after logout and will instead be left on a generic Auth0 page.

          **Allowed Web Origins** is critical for silent authentication. Without it, users will be logged out when they refresh the page or return to your app later.
        </Info>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure the Auth0 FastAPI SDK">
    Create a `main.py` file in your project's root directory and add the following code:

    ```python main.py {1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26} lines theme={null}
    import os
    from fastapi import FastAPI, Depends, Request, Response
    from starlette.middleware.sessions import SessionMiddleware
    from dotenv import load_dotenv

    from auth0_fastapi.config import Auth0Config
    from auth0_fastapi.auth.auth_client import AuthClient
    from auth0_fastapi.server.routes import router, register_auth_routes

    # Load environment variables
    load_dotenv()

    app = FastAPI(title="Auth0 FastAPI Example")

    # Add Session Middleware - required for cookie handling
    app.add_middleware(SessionMiddleware, secret_key=os.getenv("SESSION_SECRET"))

    # Create Auth0Config with your Auth0 credentials
    config = Auth0Config(
        domain=os.getenv("AUTH0_DOMAIN"),
        client_id=os.getenv("AUTH0_CLIENT_ID"),
        client_secret=os.getenv("AUTH0_CLIENT_SECRET"),
        app_base_url=os.getenv("APP_BASE_URL", "http://localhost:3000"),
        secret=os.getenv("SESSION_SECRET"),
    )

    # Instantiate the AuthClient
    auth_client = AuthClient(config)

    # Attach to the FastAPI app state
    app.state.config = config
    app.state.auth_client = auth_client

    # Register authentication routes
    register_auth_routes(router, config)
    app.include_router(router)
    ```

    <Info>
      **SESSION\_SECRET** is used to encrypt session cookies and must be cryptographically secure. Without a strong secret (minimum 32 bytes), your application's sessions can be compromised. Generate a secure secret using `openssl rand -hex 64` and never commit it to version control.

      **SessionMiddleware** must be added before using the SDK. Without it, FastAPI cannot read or set cookies, and all authentication attempts will fail silently.

      **HTTPS in Production** is required for secure cookies (`secure=True`). Without HTTPS, session cookies will not be sent by browsers, and users will be repeatedly logged out after each request.
    </Info>
  </Step>

  <Step title="Create Routes and Display User Profile">
    Add the following routes to your `main.py` file to create a home page and a protected profile page:

    ```python main.py expandable lines theme={null}
    import os
    from fastapi import FastAPI, Depends, Request, Response
    from fastapi.responses import HTMLResponse
    from starlette.middleware.sessions import SessionMiddleware
    from dotenv import load_dotenv

    from auth0_fastapi.config import Auth0Config
    from auth0_fastapi.auth.auth_client import AuthClient
    from auth0_fastapi.server.routes import router, register_auth_routes

    # Load environment variables
    load_dotenv()

    app = FastAPI(title="Auth0 FastAPI Example")

    # Add Session Middleware - required for cookie handling
    app.add_middleware(SessionMiddleware, secret_key=os.getenv("SESSION_SECRET"))

    # Create Auth0Config with your Auth0 credentials
    config = Auth0Config(
        domain=os.getenv("AUTH0_DOMAIN"),
        client_id=os.getenv("AUTH0_CLIENT_ID"),
        client_secret=os.getenv("AUTH0_CLIENT_SECRET"),
        app_base_url=os.getenv("APP_BASE_URL", "http://localhost:3000"),
        secret=os.getenv("SESSION_SECRET"),
        authorization_params={
          "scope": "openid profile email", # Required to get user profile information
        }
    )

    # Instantiate the AuthClient
    auth_client = AuthClient(config)

    # Attach to the FastAPI app state
    app.state.config = config
    app.state.auth_client = auth_client

    # Register authentication routes
    register_auth_routes(router, config)
    app.include_router(router)


    @app.get("/", response_class=HTMLResponse)
    async def home(request: Request, response: Response):
        """Home page with login/logout buttons"""
        store_options = {"request": request, "response": response}
        session = await auth_client.client.get_session(store_options=store_options)

        if session:
            user = await auth_client.client.get_user(store_options=store_options)
            return f"""
            <!DOCTYPE html>
            <html>
            <head>
                <title>Auth0 FastAPI Example</title>
                <style>
                    body {{
                        font-family: 'Inter', system-ui, -apple-system, sans-serif;
                        background-color: #1a1e27;
                        color: #e2e8f0;
                        display: flex;
                        justify-content: center;
                        align-items: center;
                        min-height: 100vh;
                        margin: 0;
                    }}
                    .container {{
                        background-color: #262a33;
                        border-radius: 20px;
                        box-shadow: 0 20px 60px rgba(0, 0, 0, 0.6);
                        padding: 3rem;
                        max-width: 500px;
                        width: 90%;
                        text-align: center;
                    }}
                    .logo {{
                        width: 160px;
                        margin-bottom: 1.5rem;
                    }}
                    h1 {{
                        font-size: 2.8rem;
                        font-weight: 700;
                        color: #f7fafc;
                        margin-bottom: 1rem;
                    }}
                    .success {{
                        font-size: 1.5rem;
                        color: #68d391;
                        font-weight: 600;
                        margin: 1.5rem 0;
                    }}
                    .profile {{
                        background-color: #2d313c;
                        border-radius: 15px;
                        padding: 2rem;
                        margin: 2rem 0;
                    }}
                    .profile-image {{
                        width: 110px;
                        height: 110px;
                        border-radius: 50%;
                        border: 3px solid #63b3ed;
                        margin-bottom: 1rem;
                    }}
                    .profile-name {{
                        font-size: 2rem;
                        font-weight: 600;
                        color: #f7fafc;
                        margin-bottom: 0.5rem;
                    }}
                    .profile-email {{
                        font-size: 1.15rem;
                        color: #a0aec0;
                    }}
                    .button {{
                        padding: 1.1rem 2.8rem;
                        font-size: 1.2rem;
                        font-weight: 600;
                        border-radius: 10px;
                        border: none;
                        cursor: pointer;
                        text-decoration: none;
                        display: inline-block;
                        transition: all 0.3s cubic-bezier(0.25, 0.8, 0.25, 1);
                        box-shadow: 0 8px 20px rgba(0, 0, 0, 0.4);
                        text-transform: uppercase;
                        letter-spacing: 0.08em;
                    }}
                    .button.logout {{
                        background-color: #fc8181;
                        color: #1a1e27;
                    }}
                    .button.logout:hover {{
                        background-color: #e53e3e;
                        transform: translateY(-5px) scale(1.03);
                        box-shadow: 0 12px 25px rgba(0, 0, 0, 0.5);
                    }}
                </style>
            </head>
            <body>
                <div class="container">
                    <img src="https://cdn.auth0.com/quantum-assets/dist/latest/logos/auth0/auth0-lockup-en-ondark.png"
                         alt="Auth0 Logo" class="logo">
                    <h1>Welcome to Auth0 FastAPI</h1>
                    <div class="success">✅ Successfully authenticated!</div>
                    <h2>Your Profile</h2>
                    <div class="profile">
                        <img src="{user.get('picture', '')}"
                             alt="{user.get('name', 'User')}" class="profile-image">
                        <div class="profile-name">{user.get('name', 'User')}</div>
                        <div class="profile-email">{user.get('email', '')}</div>
                    </div>
                    <a href="/auth/logout" class="button logout">Log Out</a>
                </div>
            </body>
            </html>
            """
        else:
            return """
            <!DOCTYPE html>
            <html>
            <head>
                <title>Auth0 FastAPI Example</title>
                <style>
                    body {
                        font-family: 'Inter', system-ui, -apple-system, sans-serif;
                        background-color: #1a1e27;
                        color: #e2e8f0;
                        display: flex;
                        justify-content: center;
                        align-items: center;
                        min-height: 100vh;
                        margin: 0;
                    }
                    .container {
                        background-color: #262a33;
                        border-radius: 20px;
                        box-shadow: 0 20px 60px rgba(0, 0, 0, 0.6);
                        padding: 3rem;
                        max-width: 500px;
                        width: 90%;
                        text-align: center;
                    }
                    .logo {
                        width: 160px;
                        margin-bottom: 1.5rem;
                    }
                    h1 {
                        font-size: 2.8rem;
                        font-weight: 700;
                        color: #f7fafc;
                        margin-bottom: 1rem;
                    }
                    .action-card {
                        background-color: #2d313c;
                        border-radius: 15px;
                        padding: 2.5rem;
                        margin-top: 2rem;
                    }
                    .action-text {
                        font-size: 1.25rem;
                        color: #cbd5e0;
                        margin-bottom: 1.8rem;
                    }
                    .button {
                        padding: 1.1rem 2.8rem;
                        font-size: 1.2rem;
                        font-weight: 600;
                        border-radius: 10px;
                        border: none;
                        cursor: pointer;
                        text-decoration: none;
                        display: inline-block;
                        transition: all 0.3s cubic-bezier(0.25, 0.8, 0.25, 1);
                        box-shadow: 0 8px 20px rgba(0, 0, 0, 0.4);
                        text-transform: uppercase;
                        letter-spacing: 0.08em;
                    }
                    .button.login {
                        background-color: #63b3ed;
                        color: #1a1e27;
                    }
                    .button.login:hover {
                        background-color: #4299e1;
                        transform: translateY(-5px) scale(1.03);
                        box-shadow: 0 12px 25px rgba(0, 0, 0, 0.5);
                    }
                </style>
            </head>
            <body>
                <div class="container">
                    <img src="https://cdn.auth0.com/quantum-assets/dist/latest/logos/auth0/auth0-lockup-en-ondark.png"
                         alt="Auth0 Logo" class="logo">
                    <h1>Welcome to Auth0 FastAPI</h1>
                    <div class="action-card">
                        <p class="action-text">Get started by signing in to your account</p>
                        <a href="/auth/login" class="button login">Log In</a>
                    </div>
                </div>
            </body>
            </html>
            """


    @app.get("/profile")
    async def profile(
        request: Request,
        response: Response,
        session=Depends(auth_client.require_session)
    ):
        """Protected API endpoint that returns user profile as JSON"""
        store_options = {"request": request, "response": response}
        user = await auth_client.client.get_user(store_options=store_options)

        return {
            "message": "Your Profile",
            "user": user,
            "session_details": session
        }


    if __name__ == "__main__":
        import uvicorn
        uvicorn.run(app, host="0.0.0.0", port=3000)
    ```

    This creates:

    * A home page (`/`) that displays a login button when logged out, or the user's profile when logged in
    * A protected API endpoint (`/profile`) that returns user data as JSON and requires authentication
    * Full styling for a polished user experience
  </Step>

  <Step title="Run your app">
    ```shellscript theme={null}
    uvicorn main:app --reload --port 3000
    ```

    Alternatively, if you added the `if __name__ == "__main__"` block to your `main.py`:

    ```shellscript theme={null}
    python main.py
    ```
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a fully functional Auth0 login page running on your [localhost](http://localhost:3000/).
</Check>

***

## Advanced Usage

<Accordion title="Protecting API Routes with Custom Dependencies">
  Create custom FastAPI dependencies for role-based access control:

  ```python theme={null}
  from fastapi import Depends, HTTPException, status
  from typing import List

  async def require_roles(required_roles: List[str]):
      """Dependency factory for role-based access control"""
      async def check_roles(
          request: Request,
          response: Response,
          session=Depends(auth_client.require_session)
      ):
          store_options = {"request": request, "response": response}
          user = await auth_client.client.get_user(store_options=store_options)

          user_roles = user.get("app_metadata", {}).get("roles", [])

          if not any(role in user_roles for role in required_roles):
              raise HTTPException(
                  status_code=status.HTTP_403_FORBIDDEN,
                  detail=f"Required roles: {', '.join(required_roles)}"
              )

          return session

      return check_roles

  # Usage in routes
  @app.get("/admin/dashboard")
  async def admin_dashboard(
      session=Depends(require_roles(["admin", "superadmin"]))
  ):
      return {"message": "Admin dashboard access granted"}

  @app.delete("/admin/users/{user_id}")
  async def delete_user(
      user_id: str,
      session=Depends(require_roles(["admin"]))
  ):
      return {"message": f"User {user_id} deleted"}
  ```
</Accordion>

<Accordion title="Calling Protected APIs with Access Tokens">
  Configure the SDK to request access tokens for your API and use them in downstream calls:

  ```python theme={null}
  from auth0_fastapi.config import Auth0Config
  import httpx

  # Configure Auth0 with API audience
  config = Auth0Config(
      domain=os.getenv("AUTH0_DOMAIN"),
      client_id=os.getenv("AUTH0_CLIENT_ID"),
      client_secret=os.getenv("AUTH0_CLIENT_SECRET"),
      app_base_url=os.getenv("APP_BASE_URL"),
      secret=os.getenv("SESSION_SECRET"),
      audience="https://api.example.com",  # Your API identifier
      authorization_params={
          "scope": "openid profile email read:data write:data",
      },
  )

  @app.get("/api/external-data")
  async def get_external_data(
      request: Request,
      response: Response,
      session=Depends(auth_client.require_session)
  ):
      """Call external API with user's access token"""
      # Get access token from session
      access_token = session.get("access_token")

      if not access_token:
          raise HTTPException(
              status_code=status.HTTP_401_UNAUTHORIZED,
              detail="No access token available"
          )

      # Make authenticated API call
      async with httpx.AsyncClient() as client:
          api_response = await client.get(
              "https://api.example.com/data",
              headers={"Authorization": f"Bearer {access_token}"}
          )

          if api_response.status_code != 200:
              raise HTTPException(
                  status_code=api_response.status_code,
                  detail="External API call failed"
              )

      return {"data": api_response.json()}
  ```
</Accordion>

<Accordion title="Using Redis for Stateful Session Storage">
  Scale your application by storing sessions in Redis instead of encrypted cookies:

  ```python theme={null}
  from auth0_fastapi.stores.stateful_state_store import StatefulStateStore
  from redis import asyncio as aioredis

  # Create Redis client
  redis = await aioredis.from_url(
      "redis://localhost:6379",
      encoding="utf-8",
      decode_responses=True
  )

  # Create stateful store
  state_store = StatefulStateStore(
      secret=os.getenv("SESSION_SECRET"),
      store=redis,
      cookie_name="_session_id",
      expiration=86400,  # 1 day in seconds
  )

  # Pass to AuthClient
  auth_client = AuthClient(config, state_store=state_store)
  ```

  Benefits of stateful sessions:

  * **No cookie size limits** - Store unlimited session data
  * **Immediate invalidation** - Delete sessions server-side
  * **Backchannel logout support** - Handle logout events from Auth0
  * **Better for distributed systems** - Share sessions across multiple servers
</Accordion>

***

## Troubleshooting

<Accordion title="Sessions not persisting / Users repeatedly logged out">
  **Problem**: Users are logged in but sessions don't persist across requests.

  **Possible Causes & Solutions**:

  1. **Missing SessionMiddleware**

     Ensure you've added SessionMiddleware to your app:

     ```python theme={null}
     from starlette.middleware.sessions import SessionMiddleware

     app.add_middleware(SessionMiddleware, secret_key=os.getenv("SESSION_SECRET"))
     ```

  2. **HTTP in production with secure cookies**

     Secure cookies require HTTPS. If testing locally over HTTP, you can temporarily disable secure cookies (not recommended for production):

     ```python theme={null}
     from auth0_fastapi.stores.stateless_state_store import StatelessStateStore

     state_store = StatelessStateStore(
         secret=config.secret,
         cookie_name="_a0_session",
         expiration=config.session_expiration
     )
     # Development only!
     state_store.cookie_options["secure"] = False

     auth_client = AuthClient(config, state_store=state_store)
     ```

  3. **Weak or missing SESSION\_SECRET**

     Generate a strong secret:

     ```shellscript theme={null}
     openssl rand -hex 64
     ```
</Accordion>

<Accordion title="Auth0 Error: Callback URL mismatch">
  **Problem**: After clicking "Log In", Auth0 displays an error: "Callback URL mismatch"

  **Cause**: The callback URL is not registered in your Auth0 Application settings.

  **Solution**:

  1. Go to [Auth0 Dashboard](https://manage.auth0.com/) → Applications → Your App → Settings
  2. Add your callback URL to **Allowed Callback URLs**:
     ```
     http://localhost:3000/auth/callback
     ```
  3. For production, add your production URL:
     ```
     https://yourdomain.com/auth/callback
     ```
  4. Click **Save Changes**

  **Note**: The URL must match exactly, including protocol (http/https) and port number.
</Accordion>

<Accordion title="ImportError or async/await issues">
  **Problem**: Errors related to async functions or event loops.

  **Cause**: FastAPI is an async framework and all SDK methods must be awaited.

  **Solution**: Ensure all route functions are async and SDK methods are properly awaited:

  ```python theme={null}
  # ✅ Correct
  @app.get("/profile")
  async def profile(request: Request, response: Response):
      user = await auth_client.client.get_user(
          store_options={"request": request, "response": response}
      )
      return {"user": user}

  # ❌ Incorrect - missing async
  @app.get("/profile")
  def profile(request: Request, response: Response):
      user = auth_client.client.get_user(...)  # This will fail
      return {"user": user}

  # ❌ Incorrect - missing await
  @app.get("/profile")
  async def profile(request: Request, response: Response):
      user = auth_client.client.get_user(...)  # Returns coroutine, not data
      return {"user": user}
  ```
</Accordion>

<Accordion title="HTTPS required in production">
  **Problem**: Sessions work locally but not in production.

  **Cause**: Secure cookies require HTTPS in production. The `secure=True` flag prevents cookies from being sent over unencrypted HTTP connections.

  **Solution**:

  1. **Configure HTTPS** on your production server using:
     * Let's Encrypt certificates
     * Cloud provider SSL/TLS (AWS ALB, Cloudflare, etc.)
     * Reverse proxy (Nginx, Caddy, Traefik)

  2. **Update your Auth0 Application URLs** to use HTTPS:
     ```
     https://yourdomain.com/auth/callback
     https://yourdomain.com
     ```

  3. **Ensure APP\_BASE\_URL uses HTTPS**:
     ```
     APP_BASE_URL=https://yourdomain.com
     ```
</Accordion>

For more advanced features and configuration options, check out the [Auth0 FastAPI SDK documentation](https://github.com/auth0/auth0-fastapi/blob/main/README.md).


# Add Login to Your Fastify Application
Source: https://auth0.com/docs/quickstart/webapp/fastify/index

This guide demonstrates how to integrate Auth0, add authentication, and display user profile information in a Fastify web application using the Auth0 Fastify SDK.

<Accordion title="Use AI to integrate Auth0" icon="microchip-ai">
  If you use an AI coding assistant like Claude Code, Cursor, or GitHub Copilot, you can add Auth0 authentication automatically in minutes using [agent skills](https://agentskills.io/home).

  **Install:**

  ```bash theme={null}
  npx skills add auth0/agent-skills --skill auth0-quickstart --skill auth0-fastify
  ```

  **Then ask your AI assistant:**

  ```text theme={null}
  Add Auth0 authentication to my Fastify app
  ```

  Your AI assistant will automatically create your Auth0 application, fetch credentials, install `@auth0/auth0-fastify`, configure the plugin, and create all necessary routes and views. [Full agent skills documentation →](/quickstart/agent-skills)
</Accordion>

<Note>
  **Prerequisites:** Before you begin, ensure you have the following installed:

  * **[Node.js](https://nodejs.org/en/download)** 20 LTS or newer
  * **[npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)** 10+ or **[yarn](https://classic.yarnpkg.com/lang/en/docs/install/)** 1.22+ or **[pnpm](https://pnpm.io/installation)** 8+

  Verify installation: `node --version && npm --version`

  **Fastify Version Compatibility:** This quickstart works with **Fastify 5.x** and newer.
</Note>

## Get Started

This quickstart demonstrates how to add Auth0 authentication to a Fastify application. You'll build a secure web app with login, logout, and user profile features using the Auth0 Fastify SDK.

<Steps>
  <Step title="Create a new project">
    Create a new directory for your Fastify application and initialize a Node.js project.

    ```shellscript theme={null}
    mkdir auth0-fastify && cd auth0-fastify
    ```

    Initialize the project

    ```shellscript theme={null}
    npm init -y
    ```

    Create the project structure

    ```shellscript theme={null}
    touch server.js .env
    ```
  </Step>

  <Step title="Install the Auth0 Fastify SDK">
    Install the required dependencies

    ```shellscript theme={null}
    npm install @auth0/auth0-fastify fastify dotenv @fastify/view ejs
    ```

    <Info>
      We're using `@fastify/view` with `ejs` for server-side rendering. You can use any template engine supported by Fastify.
    </Info>

    Update your `package.json` to add start scripts:

    ```json package.json theme={null}
    {
      "name": "auth0-fastify",
      "version": "1.0.0",
      "type": "module",
      "main": "server.js",
      "scripts": {
        "start": "node server.js",
        "dev": "node --watch server.js"
      },
      "dependencies": {
        "@auth0/auth0-fastify": "^1.2.0",
        "@fastify/view": "^10.0.0",
        "dotenv": "^16.3.1",
        "ejs": "^3.1.9",
        "fastify": "^5.0.0"
      }
    }
    ```
  </Step>

  <Step title="Setup your Auth0 App">
    Next, you need to create a new application on your Auth0 tenant and add the environment variables to your project.

    You have three options to set up your Auth0 app: use the Quick Setup tool (recommended), run a CLI command, or configure manually via the Dashboard:

    <Tabs>
      <Tab title="Quick Setup (recommended)">
        Create an Auth0 App and copy the pre-filled `.env` file with the right configuration values.

        <CreateInteractiveApp />

        <AuthCodeBlock />
      </Tab>

      <Tab title="CLI">
        Run the following command in your project's root directory to create an Auth0 app and generate a `.env` file:

        <CodeGroup>
          ```shellscript Mac theme={null}
          # Install Auth0 CLI (if not already installed)
          brew tap auth0/auth0-cli && brew install auth0

          # Set up Auth0 app and generate .env file
          auth0 qs setup --type fastify -n "My Fastify App" -p 3000
          ```

          ```powershell Windows theme={null}
          # Install Auth0 CLI (if not already installed)
          scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git
          scoop install auth0

          # Set up Auth0 app and generate .env file
          auth0 qs setup --type fastify -n "My Fastify App" -p 3000
          ```
        </CodeGroup>

        <Note>
          This command will:

          1. Check if you're authenticated (and prompt for login if needed)
          2. Create an Auth0 Regular Web Application configured for `http://localhost:3000`
          3. Generate a `.env` file with `AUTH0_DOMAIN`, `AUTH0_CLIENT_ID`, `AUTH0_CLIENT_SECRET`, `SESSION_SECRET`, and `APP_BASE_URL`
        </Note>
      </Tab>

      <Tab title="Dashboard">
        1. Go to the [Auth0 Dashboard](https://manage.auth0.com/dashboard/)
        2. Navigate to **Applications** → **Create Application**
        3. Enter a name for your application (e.g., "My Fastify App")
        4. Select **Regular Web Applications** and click **Create**
        5. In the **Settings** tab, configure the following:

        | Setting               | Value                                 |
        | --------------------- | ------------------------------------- |
        | Allowed Callback URLs | `http://localhost:3000/auth/callback` |
        | Allowed Logout URLs   | `http://localhost:3000`               |

        6. Scroll down and click **Save Changes**
        7. Copy the **Domain**, **Client ID**, and **Client Secret** values from the **Basic Information** section

        Create your `.env` file with the following values:

        ```bash .env theme={null}
        AUTH0_DOMAIN=YOUR_AUTH0_DOMAIN
        AUTH0_CLIENT_ID=YOUR_CLIENT_ID
        AUTH0_CLIENT_SECRET=YOUR_CLIENT_SECRET
        SESSION_SECRET=use-a-long-random-string-at-least-64-characters
        APP_BASE_URL=http://localhost:3000
        ```

        <Warning>
          Replace `YOUR_AUTH0_DOMAIN` with your Auth0 tenant domain (e.g., `dev-abc123.us.auth0.com`), `YOUR_CLIENT_ID` with your application's Client ID, and `YOUR_CLIENT_SECRET` with your application's Client Secret from the dashboard.
        </Warning>

        Generate a secure secret for session encryption:

        ```bash theme={null}
        openssl rand -hex 64
        ```

        Copy the output and use it as the `SESSION_SECRET` value in your `.env` file.
      </Tab>
    </Tabs>

    <Tip>
      Verify your `.env` file exists: `cat .env` (Mac/Linux) or `type .env` (Windows)
    </Tip>
  </Step>

  <Step title="Configure the Auth0 plugin">
    Create your Fastify server and register the Auth0 plugin:

    ```javascript server.js {1-4,7-8,11-18,21-22} lines theme={null}
    import 'dotenv/config';
    import Fastify from 'fastify';
    import fastifyView from '@fastify/view';
    import fastifyAuth0 from '@auth0/auth0-fastify';
    import ejs from 'ejs';

    const fastify = Fastify({ logger: true });
    const port = process.env.PORT || 3000;

    // Register view engine
    await fastify.register(fastifyView, {
      engine: { ejs },
      root: './views',
    });

    // Register Auth0 plugin
    await fastify.register(fastifyAuth0, {
      domain: process.env.AUTH0_DOMAIN,
      clientId: process.env.AUTH0_CLIENT_ID,
      clientSecret: process.env.AUTH0_CLIENT_SECRET,
      appBaseUrl: process.env.APP_BASE_URL,
      sessionSecret: process.env.SESSION_SECRET,
    });

    // Start server
    fastify.listen({ port }, (err) => {
      if (err) {
        fastify.log.error(err);
        process.exit(1);
      }
      fastify.log.info(`Server running at http://localhost:${port}`);
    });
    ```

    **What this does:**

    * Registers the view engine for rendering HTML templates
    * Configures the Auth0 plugin with your credentials
    * Automatically creates routes at `/auth/login`, `/auth/logout`, and `/auth/callback`
    * Handles session management with encrypted cookies
  </Step>

  <Step title="Create view templates">
    Create a `views` directory and add template files:

    ```shellscript Mac/Linux theme={null}
    mkdir views && touch views/home.ejs views/profile.ejs
    ```

    ```powershell Windows theme={null}
    New-Item -ItemType Directory -Path views
    New-Item -ItemType File -Path views/home.ejs
    New-Item -ItemType File -Path views/profile.ejs
    ```

    Create the home page template:

    ```html views/home.ejs expandable lines theme={null}
    <!DOCTYPE html>
    <html lang="en">
    <head>
      <meta charset="UTF-8">
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <title>Auth0 Fastify Quickstart</title>
      <style>
        body {
          font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
          background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
          margin: 0;
          padding: 2rem;
          min-height: 100vh;
          display: flex;
          justify-content: center;
          align-items: center;
        }
        .container {
          background: white;
          border-radius: 20px;
          box-shadow: 0 20px 60px rgba(0, 0, 0, 0.3);
          padding: 3rem;
          max-width: 500px;
          width: 100%;
          text-align: center;
        }
        h1 {
          color: #2d3748;
          font-size: 2.5rem;
          margin-bottom: 1rem;
        }
        .status {
          padding: 1rem;
          border-radius: 10px;
          margin: 1.5rem 0;
          font-size: 1.1rem;
        }
        .logged-in {
          background: #d4edda;
          color: #155724;
        }
        .logged-out {
          background: #f8d7da;
          color: #721c24;
        }
        .button {
          display: inline-block;
          padding: 1rem 2rem;
          margin: 0.5rem;
          border-radius: 10px;
          text-decoration: none;
          font-weight: 600;
          transition: all 0.3s;
        }
        .button-primary {
          background: #667eea;
          color: white;
        }
        .button-primary:hover {
          background: #5568d3;
          transform: translateY(-2px);
        }
        .button-secondary {
          background: #e53e3e;
          color: white;
        }
        .button-secondary:hover {
          background: #c53030;
          transform: translateY(-2px);
        }
      </style>
    </head>
    <body>
      <div class="container">
        <h1>🚀 Auth0 Fastify</h1>
        <div class="status <%= isAuthenticated ? 'logged-in' : 'logged-out' %>">
          <%= isAuthenticated ? '✓ You are logged in' : '✗ You are logged out' %>
        </div>
        <div>
          <% if (isAuthenticated) { %>
            <a href="/profile" class="button button-primary">View Profile</a>
            <a href="/auth/logout" class="button button-secondary">Logout</a>
          <% } else { %>
            <a href="/auth/login" class="button button-primary">Login</a>
          <% } %>
        </div>
      </div>
    </body>
    </html>
    ```

    Create the profile page template:

    ```html views/profile.ejs expandable lines theme={null}
    <!DOCTYPE html>
    <html lang="en">
    <head>
      <meta charset="UTF-8">
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <title>Profile - Auth0 Fastify</title>
      <style>
        body {
          font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
          background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
          margin: 0;
          padding: 2rem;
          min-height: 100vh;
        }
        .container {
          background: white;
          border-radius: 20px;
          box-shadow: 0 20px 60px rgba(0, 0, 0, 0.3);
          padding: 3rem;
          max-width: 700px;
          margin: 0 auto;
        }
        h1 {
          color: #2d3748;
          margin-bottom: 2rem;
        }
        .profile-card {
          display: flex;
          align-items: center;
          gap: 2rem;
          padding: 2rem;
          background: #f7fafc;
          border-radius: 15px;
          margin-bottom: 2rem;
        }
        .profile-picture {
          width: 100px;
          height: 100px;
          border-radius: 50%;
          object-fit: cover;
          border: 3px solid #667eea;
        }
        .profile-info h2 {
          margin: 0 0 0.5rem 0;
          color: #2d3748;
        }
        .profile-info p {
          margin: 0;
          color: #718096;
        }
        .user-data {
          background: #f7fafc;
          padding: 1.5rem;
          border-radius: 10px;
          overflow-x: auto;
        }
        pre {
          margin: 0;
          white-space: pre-wrap;
          word-wrap: break-word;
        }
        .button {
          display: inline-block;
          padding: 0.75rem 1.5rem;
          margin-right: 1rem;
          border-radius: 10px;
          text-decoration: none;
          font-weight: 600;
          transition: all 0.3s;
        }
        .button-primary {
          background: #667eea;
          color: white;
        }
        .button-primary:hover {
          background: #5568d3;
        }
        .button-secondary {
          background: #e53e3e;
          color: white;
        }
        .button-secondary:hover {
          background: #c53030;
        }
      </style>
    </head>
    <body>
      <div class="container">
        <h1>User Profile</h1>
        <div class="profile-card">
          <img src="<%= user.picture || 'https://via.placeholder.com/100' %>" alt="Profile" class="profile-picture">
          <div class="profile-info">
            <h2><%= user.name || user.nickname || 'User' %></h2>
            <p><strong>Email:</strong> <%= user.email || 'N/A' %></p>
          </div>
        </div>
        <h3>Full User Object</h3>
        <div class="user-data">
          <pre><%= JSON.stringify(user, null, 2) %></pre>
        </div>
        <div style="margin-top: 2rem;">
          <a href="/" class="button button-primary">← Back to Home</a>
          <a href="/auth/logout" class="button button-secondary">Logout</a>
        </div>
      </div>
    </body>
    </html>
    ```
  </Step>

  <Step title="Create routes">
    Add routes to your `server.js` file:

    ```javascript server.js expandable lines theme={null}
    import 'dotenv/config';
    import Fastify from 'fastify';
    import fastifyView from '@fastify/view';
    import fastifyAuth0 from '@auth0/auth0-fastify';
    import ejs from 'ejs';

    const fastify = Fastify({ logger: true });
    const port = process.env.PORT || 3000;

    // Register view engine
    await fastify.register(fastifyView, {
      engine: { ejs },
      root: './views',
    });

    // Register Auth0 plugin
    await fastify.register(fastifyAuth0, {
      domain: process.env.AUTH0_DOMAIN,
      clientId: process.env.AUTH0_CLIENT_ID,
      clientSecret: process.env.AUTH0_CLIENT_SECRET,
      appBaseUrl: process.env.APP_BASE_URL,
      sessionSecret: process.env.SESSION_SECRET,
    });

    // Home route - public
    fastify.get('/', async (request, reply) => {
      const session = await fastify.auth0Client.getSession({ request, reply });
      return reply.view('views/home.ejs', {
        isAuthenticated: !!session,
      });
    });

    // Profile route - protected
    fastify.get('/profile', {
      preHandler: async (request, reply) => {
        const session = await fastify.auth0Client.getSession({ request, reply });
        if (!session) {
          return reply.redirect('/auth/login');
        }
      }
    }, async (request, reply) => {
      const user = await fastify.auth0Client.getUser({ request, reply });
      return reply.view('views/profile.ejs', { user });
    });

    // Start server
    fastify.listen({ port }, (err) => {
      if (err) {
        fastify.log.error(err);
        process.exit(1);
      }
      fastify.log.info(`Server running at http://localhost:${port}`);
    });
    ```

    **Key points:**

    * The home route checks authentication status and passes it to the template
    * The profile route uses a `preHandler` to protect the route
    * `getSession()` returns the user's session or null if not authenticated
    * `getUser()` returns the authenticated user's profile information
  </Step>

  <Step title="Run your app">
    Start the development server:

    ```shellscript theme={null}
    npm run dev
    ```

    Open your browser to [http://localhost:3000](http://localhost:3000).

    <Info>
      The `--watch` flag in Node.js 20+ automatically restarts the server when files change.
    </Info>
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a fully functional Auth0 login page. When you:

  1. Click "Login" - you're redirected to Auth0's Universal Login page
  2. Complete authentication - you're redirected back to your app
  3. Visit "/profile" - you see your user information
  4. Click "Logout" - you're logged out of both your app and Auth0
</Check>

***

## Advanced Usage

<Accordion title="Calling Protected APIs with Access Tokens">
  To call external APIs that require an access token, configure the SDK with an audience:

  ```javascript server.js theme={null}
  await fastify.register(fastifyAuth0, {
    domain: process.env.AUTH0_DOMAIN,
    clientId: process.env.AUTH0_CLIENT_ID,
    clientSecret: process.env.AUTH0_CLIENT_SECRET,
    appBaseUrl: process.env.APP_BASE_URL,
    sessionSecret: process.env.SESSION_SECRET,
    audience: process.env.AUTH0_AUDIENCE, // Add this
  });
  ```

  Add to your `.env` file:

  ```bash .env theme={null}
  AUTH0_AUDIENCE=https://your-api.example.com
  ```

  Then retrieve and use the access token:

  ```javascript server.js theme={null}
  fastify.get('/api-data', {
    preHandler: async (request, reply) => {
      const session = await fastify.auth0Client.getSession({ request, reply });
      if (!session) {
        return reply.redirect('/auth/login');
      }
    }
  }, async (request, reply) => {
    try {
      const { accessToken } = await fastify.auth0Client.getAccessToken({ request, reply });

      // Call your protected API
      const response = await fetch('https://your-api.example.com/data', {
        headers: {
          Authorization: `Bearer ${accessToken}`,
        },
      });

      const data = await response.json();
      return data;
    } catch (error) {
      fastify.log.error('API call failed:', error);
      return reply.status(500).send({ error: 'Failed to fetch data' });
    }
  });
  ```
</Accordion>

<Accordion title="Custom Route Paths">
  By default, Auth0 routes are mounted at `/auth/*`. You can disable auto-mounting and create custom routes:

  ```javascript server.js theme={null}
  await fastify.register(fastifyAuth0, {
    domain: process.env.AUTH0_DOMAIN,
    clientId: process.env.AUTH0_CLIENT_ID,
    clientSecret: process.env.AUTH0_CLIENT_SECRET,
    appBaseUrl: process.env.APP_BASE_URL,
    sessionSecret: process.env.SESSION_SECRET,
    mountRoutes: false, // Disable auto-mounting
  });

  // Custom login route
  fastify.get('/custom-login', async (request, reply) => {
    const authorizationUrl = await fastify.auth0Client.startInteractiveLogin(
      {
        authorizationParams: {
          redirect_uri: `${process.env.APP_BASE_URL}/custom-callback`
        }
      },
      { request, reply }
    );
    return reply.redirect(authorizationUrl.href);
  });

  // Custom callback route
  fastify.get('/custom-callback', async (request, reply) => {
    await fastify.auth0Client.completeInteractiveLogin(
      new URL(request.url, process.env.APP_BASE_URL),
      { request, reply }
    );
    return reply.redirect('/');
  });

  // Custom logout route
  fastify.get('/custom-logout', async (request, reply) => {
    const logoutUrl = await fastify.auth0Client.logout(
      { returnTo: process.env.APP_BASE_URL },
      { request, reply }
    );
    return reply.redirect(logoutUrl.href);
  });
  ```

  <Note>
    Remember to update your **Allowed Callback URLs** in the Auth0 Dashboard to include your custom callback URL.
  </Note>
</Accordion>

<Accordion title="Account Linking">
  Enable users to link multiple authentication providers to a single account:

  ```javascript server.js theme={null}
  await fastify.register(fastifyAuth0, {
    domain: process.env.AUTH0_DOMAIN,
    clientId: process.env.AUTH0_CLIENT_ID,
    clientSecret: process.env.AUTH0_CLIENT_SECRET,
    appBaseUrl: process.env.APP_BASE_URL,
    sessionSecret: process.env.SESSION_SECRET,
    mountConnectRoutes: true, // Enable account linking routes
  });
  ```

  This automatically creates the following routes:

  * `/auth/connect` - Link a new provider
  * `/auth/connect/callback` - Handle the linking callback
  * `/auth/unconnect` - Unlink a provider
  * `/auth/unconnect/callback` - Handle the unlinking callback

  Add linking buttons to your profile page:

  ```html views/profile.ejs theme={null}
  <div>
    <a href="/auth/connect?connection=google-oauth2">Link Google Account</a>
    <a href="/auth/unconnect?connection=google-oauth2">Unlink Google Account</a>
  </div>
  ```
</Accordion>

<Accordion title="Using TypeScript">
  Convert your project to TypeScript for better type safety:

  ```bash theme={null}
  npm install --save-dev typescript @types/node tsx
  ```

  Create a `tsconfig.json`:

  ```json tsconfig.json theme={null}
  {
    "compilerOptions": {
      "target": "ES2022",
      "module": "ESNext",
      "moduleResolution": "node",
      "esModuleInterop": true,
      "strict": true,
      "skipLibCheck": true,
      "outDir": "./dist"
    },
    "include": ["src/**/*"],
    "exclude": ["node_modules"]
  }
  ```

  Rename `server.js` to `server.ts` and add types:

  ```typescript server.ts theme={null}
  import 'dotenv/config';
  import Fastify, { FastifyRequest, FastifyReply } from 'fastify';
  import fastifyView from '@fastify/view';
  import fastifyAuth0 from '@auth0/auth0-fastify';
  import ejs from 'ejs';

  const fastify = Fastify({ logger: true });
  const port = process.env.PORT || 3000;

  await fastify.register(fastifyView, {
    engine: { ejs },
    root: './views',
  });

  await fastify.register(fastifyAuth0, {
    domain: process.env.AUTH0_DOMAIN!,
    clientId: process.env.AUTH0_CLIENT_ID!,
    clientSecret: process.env.AUTH0_CLIENT_SECRET!,
    appBaseUrl: process.env.APP_BASE_URL!,
    sessionSecret: process.env.SESSION_SECRET!,
  });

  fastify.get('/', async (request: FastifyRequest, reply: FastifyReply) => {
    const session = await fastify.auth0Client.getSession({ request, reply });
    return reply.view('views/home.ejs', {
      isAuthenticated: !!session,
    });
  });

  fastify.listen({ port: Number(port) });
  ```

  Update `package.json`:

  ```json package.json theme={null}
  {
    "scripts": {
      "dev": "tsx watch server.ts",
      "build": "tsc",
      "start": "node dist/server.js"
    }
  }
  ```
</Accordion>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Common Issues and Solutions">
    ### "Invalid state" error after login

    **Problem:** State mismatch between the authentication request and callback.

    **Solutions:**

    1. Ensure cookies are being set correctly (not blocked by browser)
    2. Verify callback URL matches exactly in Auth0 Dashboard (including `/auth/callback`)
    3. Check that `SESSION_SECRET` is set and at least 64 characters long

    ### "session is undefined" error

    **Problem:** Unable to retrieve session data.

    **Solution:** Ensure the Auth0 plugin is registered before accessing session methods:

    ```javascript theme={null}
    // ✅ Correct order
    await fastify.register(fastifyAuth0, { ... });
    fastify.get('/profile', async (request, reply) => {
      const session = await fastify.auth0Client.getSession({ request, reply });
    });

    // ❌ Wrong - plugin not awaited
    fastify.register(fastifyAuth0, { ... }); // Missing await
    fastify.get('/profile', async (request, reply) => { ... });
    ```

    ### Callback URL mismatch

    **Problem:** "Callback URL mismatch" error from Auth0.

    **Solution:**

    1. Go to your Auth0 Dashboard → Applications → Your App → Settings
    2. Add `http://localhost:3000/auth/callback` to **Allowed Callback URLs**
    3. The URL must match exactly (including the `/auth/callback` path)

    ### Environment variables not loading

    **Problem:** Configuration values are `undefined`.

    **Solution:**

    1. Ensure `import 'dotenv/config'` is at the top of your entry file
    2. Verify `.env` file is in the root directory
    3. Check for typos in variable names

    ```javascript theme={null}
    // Debug: Log config values (remove in production!)
    console.log('Config check:', {
      hasDomain: !!process.env.AUTH0_DOMAIN,
      hasClientID: !!process.env.AUTH0_CLIENT_ID,
      hasSecret: !!process.env.SESSION_SECRET,
    });
    ```
  </Accordion>
</AccordionGroup>

***

## Next Steps

Now that you have authentication working, consider exploring:

* **[Fastify API Authentication](/docs/quickstart/backend/fastify)** - Protect your API endpoints with JWT validation
* **[Customize Universal Login](https://auth0.com/docs/customize/universal-login-pages)** - Brand your login experience
* **[Add Social Connections](https://auth0.com/docs/connections/social)** - Enable Google, GitHub, and other social logins
* **[Implement MFA](https://auth0.com/docs/secure/multi-factor-authentication)** - Add multi-factor authentication

***

## Resources

* **[auth0-fastify GitHub](https://github.com/auth0/auth0-fastify)** - Source code and examples
* **[Fastify Documentation](https://fastify.dev/)** - Learn more about Fastify
* **[Auth0 Community](https://community.auth0.com/)** - Get help from the community


# Add Login to your Go Application
Source: https://auth0.com/docs/quickstart/webapp/golang/interactive

This guide demonstrates how to integrate Auth0 with any new or existing Go web application.

<QuickstartButtons />

<Recipe>
  <Content>
    Auth0 allows you to add authentication and gain access to user profile information in your application. This guide
    demonstrates how to integrate Auth0 with any new or existing Go web application.

    <Section title={sections[0].title}>
      To use Auth0 services, you’ll need to have an application set up in the Auth0 Dashboard. The Auth0 application is
      where you will configure how you want authentication to work for the project you are developing.

      ### Configure an application

      Use the interactive selector to create a new Auth0 application or select an existing application that represents
      the project you want to integrate with. Every application in Auth0 is assigned an alphanumeric, unique client ID
      that your application code will use to call Auth0 APIs through the SDK.

      Any settings you configure using this quickstart will automatically update for your Application in the [Dashboard](https://manage.auth0.com/dashboard/us/auth0-dsepaid/), which is where you can manage your Applications in the future.

      If you would rather explore a complete configuration, you can view a sample application instead.

      ### Configure Callback URLs

      A callback URL is a URL in your application that you would like Auth0 to redirect users to after they have
      authenticated. If not set, users will not be returned to your application after they log in.

      <Info>
        If you are following along with our sample project, set this to
        `http://localhost:3000/callback`.
      </Info>

      ### Configure Logout URLs

      A logout URL is a URL in your application that you would like Auth0 to redirect users to after they have logged
      out. If not set, users will not be able to log out from your application and will receive an error.

      <Info>
        If you are following along with our sample project, set this to `http://localhost:3000`.
      </Info>
    </Section>

    <Section title={sections[1].title}>
      Create a `go.mod` file to list all the dependencies in your application.

      To integrate Auth0 in a Go application, add the `coreos/go-oidc/v3` and `x/oauth2`
      packages.

      In addition to the OIDC and OAuth2 packages, add `joho/godotenv`, `gin-gonic/gin`, and
      `gin-contrib/sessions`.

      <Info>
        This example uses `gin` for routing, but you can use whichever router you want.
      </Info>

      Save the `go.mod` file with the necessary dependencies and install them using the following command in
      your terminal:

      ```text lines theme={null}
      go mod download
      ```
    </Section>

    <Section title={sections[2].title}>
      You must set the following environment variables in `.env` within the root of your project directory:

      * **AUTH0\_DOMAIN**: The domain of your Auth0 tenant. Find your Auth0 Domain in the Auth0 Dashboard under
        your Application's Settings in the Domain field. For custom domains, set this to the value of your custom domain instead.
      * **AUTH0\_CLIENT\_ID**: The ID of the Auth0 Application you set up earlier in this quickstart. Find this in
        the Auth0 Dashboard under your Application's Settings in the Client ID field.
      * **AUTH0\_CLIENT\_SECRET**: The Secret of the Auth0 Application you set up earlier in this quickstart. Find
        this in the Auth0 Dashboard under your Application's Settings in the Client Secret field.
      * **AUTH0\_CALLBACK\_URL**: The URL used by Auth0 to redirect the user after successful authentication.
    </Section>

    <Section title={sections[3].title}>
      Next, configure the OAuth2 and OpenID Connect packages.

      Create a file called `auth.go` in the `platform/authenticator` folder. In this package,
      create a method to configure and return [OAuth2](https://godoc.org/golang.org/x/oauth2) and [OIDC](https://godoc.org/github.com/coreos/go-oidc) clients, and another one to verify an ID Token.
    </Section>

    <Section title={sections[4].title}>
      Create a file called `router.go` in the `platform/router` folder. In this package, create a
      method to configure and return our routes using [github.com/gin-gonic/gin](https://github.com/gin-gonic/gin). You will be passing an instance of
      `Authenticator` to the method, for use with the `login` and `callback` handlers.
    </Section>

    <Section title={sections[5].title}>
      For the user to authenticate themselves, we need to create a handler function to handle the `/login`
      route.

      Create a file called `login.go` in the `web/app/login` folder, and add a
      `Handler` function. Upon executing the handler, the user will be redirected to Auth0 where they can
      enter their credentials.

      To call the `/login` route, add a link to `/login` in the `home.html` template
      located in the `web/template` directory.
    </Section>

    <Section title={sections[6].title}>
      Once users have authenticated using Auth0's Universal Login Page, they will return to the app at the
      `/callback` route.

      Create a file called `callback.go` in the `web/app/callback` folder, and add a
      `Handler` function.

      This handler will take the `code` query string, provided by Auth0, and exchange it for an ID token and
      an access token.

      If the ID token is valid, it will store the profile information and access token in the session. The profile
      information is based on the claims contained in the ID token. Session storage allows the application to access
      that information as needed.
    </Section>

    <Section title={sections[7].title}>
      Now that your users can log in, you will likely want to be able to retrieve and use the profile information associated with authenticated users.

      You can access that profile information, such as their nickname or profile picture, through the
      `profile` that was stored in the session previously.

      Create a handler for the `/user` endpoint in `web/app/user/user.go` and return the
      corresponding HTML file. As the `profile` is being passed to `ctx.HTML()`, you can access
      the profile information such as `picture` and `nickname` inside that same HTML file.

      An example of such an HTML file could look like the example below, but you can retrieve any profile information,
      including custom claims.
    </Section>

    <Section title={sections[8].title}>
      To log the user out, clear the data from the session and redirect the user to the Auth0 logout endpoint. You can
      find more information about this in the [logout
      documentation](https://auth0.com/docs/logout).

      Create a file called `logout.go` in the folder `web/app/logout`, and add the function
      `Handler` to redirect the user to Auth0's logout endpoint.

      The `returnTo` URL needs to be in the list of Allowed Logout URLs in the settings section of the
      application, For more information, see [Redirect Users After Logout](https://auth0.com/docs/logout/guides/redirect-users-after-logout).

      Create a file called `user.js` in the folder `web/static/js`, and add the code to remove
      the cookie from a logged-in user.
    </Section>

    <Section title={sections[9].title}>
      Recommended practice dictates certain routes are accessible only to authenticated users. When unauthenticated
      users try accessing protected routes, your application should redirect them.

      In this case, you will implement middleware to hook into the HTTP request. The middleware function determines if
      the request should route to the endpoint handler or block the request.

      Create a file called `isAuthenticated.go` in `platform/middleware` and add a function that
      checks if the user is authenticated or not based on the `profile` session key. If the user is not
      authenticated, the middleware will redirect the user to the root of the application.

      With the middleware created, we can set it up for any route that needs authentication by adding it to the router.
    </Section>

    <Section title={sections[10].title}>
      With both the authenticator and router configured, we can wire things up using our application's entry point.
      Inside `main.go`, create an instance of the authenticator and the router, which gets passed the
      authenticator instance.

      If you are using a `.env` file, you must call `godotenv.Load()` at the very beginning of
      the `main()` function.

      Serve your application by using the following command in your terminal:

      ```text lines theme={null}
      go run main.go
      ```
    </Section>

    ## Next Steps

    Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.

    This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:

    * [Auth0 Dashboard](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq) - Learn how to configure and manage your Auth0 tenant and applications
    * [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
  </Content>

  <SideMenu>
    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```golang user.go lines theme={null}
        // Save this file in ./web/app/user/user.go

        package user

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"
        )

        // Handler for our logged-in user page.
        func Handler(ctx *gin.Context) {
        	session := sessions.Default(ctx)
        	profile := session.Get("profile")

        	ctx.HTML(http.StatusOK, "user.html", profile)
        }
        ```

        ```golang auth.go lines  theme={null}
        // Save this file in ./platform/authenticator/auth.go

        package authenticator

        import (
        	"context"
        	"errors"
        	"os"

        	"github.com/coreos/go-oidc/v3/oidc"
        	"golang.org/x/oauth2"
        )

        // Authenticator is used to authenticate our users.
        type Authenticator struct {
        	*oidc.Provider
        	oauth2.Config
        }

        // New instantiates the *Authenticator.
        func New() (*Authenticator, error) {
        	provider, err := oidc.NewProvider(
        		context.Background(),
        		"https://"+os.Getenv("AUTH0_DOMAIN")+"/",
        	)
        	if err != nil {
        		return nil, err
        	}

        	conf := oauth2.Config{
        		ClientID:     os.Getenv("AUTH0_CLIENT_ID"),
        		ClientSecret: os.Getenv("AUTH0_CLIENT_SECRET"),
        		RedirectURL:  os.Getenv("AUTH0_CALLBACK_URL"),
        		Endpoint:     provider.Endpoint(),
        		Scopes:       []string{oidc.ScopeOpenID, "profile"},
        	}

        	return &Authenticator{
        		Provider: provider,
        		Config:   conf,
        	}, nil
        }

        // VerifyIDToken verifies that an *oauth2.Token is a valid *oidc.IDToken.
        func (a *Authenticator) VerifyIDToken(ctx context.Context, token *oauth2.Token) (*oidc.IDToken, error) {
        	rawIDToken, ok := token.Extra("id_token").(string)
        	if !ok {
        		return nil, errors.New("no id_token field in oauth2 token")
        	}

        	oidcConfig := &oidc.Config{
        		ClientID: a.ClientID,
        	}

        	return a.Verifier(oidcConfig).Verify(ctx, rawIDToken)
        }
        ```

        ```golang callback.go lines  theme={null}
        / Save this file in ./web/app/callback/callback.go

        package callback

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        )

        // Handler for our callback.
        func Handler(auth *authenticator.Authenticator) gin.HandlerFunc {
        	return func(ctx *gin.Context) {
        		session := sessions.Default(ctx)
        		if ctx.Query("state") != session.Get("state") {
        			ctx.String(http.StatusBadRequest, "Invalid state parameter.")
        			return
        		}

        		// Exchange an authorization code for a token.
        		token, err := auth.Exchange(ctx.Request.Context(), ctx.Query("code"))
        		if err != nil {
        			ctx.String(http.StatusUnauthorized, "Failed to exchange an authorization code for a token.")
        			return
        		}

        		idToken, err := auth.VerifyIDToken(ctx.Request.Context(), token)
        		if err != nil {
        			ctx.String(http.StatusInternalServerError, "Failed to verify ID Token.")
        			return
        		}

        		var profile map[string]interface{}
        		if err := idToken.Claims(&profile); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		session.Set("access_token", token.AccessToken)
        		session.Set("profile", profile)
        		if err := session.Save(); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		// Redirect to logged in page.
        		ctx.Redirect(http.StatusTemporaryRedirect, "/user")
        	}
        }
        ```

        ```env .env lines theme={null}
        # Save this file in ./.env

        # The URL of our Auth0 Tenant Domain.
        # If you're using a Custom Domain, be sure to set this to that value instead.
        AUTH0_DOMAIN='{yourDomain}'

        # Our Auth0 application's Client ID.
        AUTH0_CLIENT_ID='{yourClientId}'

        # Our Auth0 application's Client Secret.
        AUTH0_CLIENT_SECRET='{yourClientSecret}'

        # The Callback URL of our application.
        AUTH0_CALLBACK_URL='http://localhost:3000/callback'
        ```

        ```mod go.mod lines theme={null}
        // Save this file in ./go.mod

        module 01-Login

        go 1.21

        require (
        	github.com/coreos/go-oidc/v3 v3.8.0
        	github.com/gin-contrib/sessions v0.0.5
        	github.com/gin-gonic/gin v1.9.1
        	github.com/joho/godotenv v1.5.1
        	golang.org/x/oauth2 v0.15.0
        )
        ```

        ```golang isAuthenticated.go lines theme={null}
        // Save this file in ./platform/middleware/isAuthenticated.go

        package middleware

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"
        )

        // IsAuthenticated is a middleware that checks if
        // the user has already been authenticated previously.
        func IsAuthenticated(ctx *gin.Context) {
        	if sessions.Default(ctx).Get("profile") == nil {
        		ctx.Redirect(http.StatusSeeOther, "/")
        	} else {
        		ctx.Next()
        	}
        }
        ```

        ```golang login.go lines  theme={null}
        // Save this file in ./web/app/login/login.go

        package login

        import (
        	"crypto/rand"
        	"encoding/base64"
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        )

        // Handler for our login.
        func Handler(auth *authenticator.Authenticator) gin.HandlerFunc {
        	return func(ctx *gin.Context) {
        		state, err := generateRandomState()
        		if err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		// Save the state inside the session.
        		session := sessions.Default(ctx)
        		session.Set("state", state)
        		if err := session.Save(); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		ctx.Redirect(http.StatusTemporaryRedirect, auth.AuthCodeURL(state))
        	}
        }

        func generateRandomState() (string, error) {
        	b := make([]byte, 32)
        	_, err := rand.Read(b)
        	if err != nil {
        		return "", err
        	}

        	state := base64.StdEncoding.EncodeToString(b)

        	return state, nil
        }
        ```

        ```golang logout.go lines  theme={null}
        // Save this file in ./web/app/logout/logout.go

        package logout

        import (
        	"net/http"
        	"net/url"
        	"os"

        	"github.com/gin-gonic/gin"
        )

        // Handler for our logout.
        func Handler(ctx *gin.Context) {
        	logoutUrl, err := url.Parse("https://" + os.Getenv("AUTH0_DOMAIN") + "/v2/logout")
        	if err != nil {
        		ctx.String(http.StatusInternalServerError, err.Error())
        		return
        	}

        	scheme := "http"
        	if ctx.Request.TLS != nil {
        		scheme = "https"
        	}

        	returnTo, err := url.Parse(scheme + "://" + ctx.Request.Host)
        	if err != nil {
        		ctx.String(http.StatusInternalServerError, err.Error())
        		return
        	}

        	parameters := url.Values{}
        	parameters.Add("returnTo", returnTo.String())
        	parameters.Add("client_id", os.Getenv("AUTH0_CLIENT_ID"))
        	logoutUrl.RawQuery = parameters.Encode()

        	ctx.Redirect(http.StatusTemporaryRedirect, logoutUrl.String())
        }
        ```

        ```golang main.go lines  theme={null}
        // Save this file in ./main.go

        package main

        import (
        	"log"
        	"net/http"

        	"github.com/joho/godotenv"

        	"01-Login/platform/authenticator"
        	"01-Login/platform/router"
        )

        func main() {
        	if err := godotenv.Load(); err != nil {
        		log.Fatalf("Failed to load the env vars: %v", err)
        	}

        	auth, err := authenticator.New()
        	if err != nil {
        		log.Fatalf("Failed to initialize the authenticator: %v", err)
        	}

        	rtr := router.New(auth)

        	log.Print("Server listening on http://localhost:3000/")
        	if err := http.ListenAndServe("0.0.0.0:3000", rtr); err != nil {
        		log.Fatalf("There was an error with the http server: %v", err)
        	}
        }
        ```

        ```golang router.go lines  theme={null}
        // Save this file in ./platform/router/router.go

        package router

        import (
        	"encoding/gob"
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-contrib/sessions/cookie"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        	"01-Login/platform/middleware"
        	"01-Login/web/app/callback"
        	"01-Login/web/app/login"
        	"01-Login/web/app/logout"
        	"01-Login/web/app/user"
        )

        // New registers the routes and returns the router.
        func New(auth *authenticator.Authenticator) *gin.Engine {
        	router := gin.Default()

        	// To store custom types in our cookies,
        	// we must first register them using gob.Register
        	gob.Register(map[string]interface{}{})

        	store := cookie.NewStore([]byte("secret"))
        	router.Use(sessions.Sessions("auth-session", store))

        	router.Static("/public", "web/static")
        	router.LoadHTMLGlob("web/template/*")

        	router.GET("/", func(ctx *gin.Context) {
        		ctx.HTML(http.StatusOK, "home.html", nil)
        	})
        	router.GET("/login", login.Handler(auth))
        	router.GET("/callback", callback.Handler(auth))
        	router.GET("/user", user.Handler)
        	router.GET("/logout", logout.Handler)

        	return router
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```env .env lines theme={null}
        # Save this file in ./.env

        # The URL of our Auth0 Tenant Domain.
        # If you're using a Custom Domain, be sure to set this to that value instead.
        AUTH0_DOMAIN='{yourDomain}'

        # Our Auth0 application's Client ID.
        AUTH0_CLIENT_ID='{yourClientId}'

        # Our Auth0 application's Client Secret.
        AUTH0_CLIENT_SECRET='{yourClientSecret}'

        # The Callback URL of our application.
        AUTH0_CALLBACK_URL='http://localhost:3000/callback'
        ```

        ```golang auth.go lines  theme={null}
        // Save this file in ./platform/authenticator/auth.go

        package authenticator

        import (
        	"context"
        	"errors"
        	"os"

        	"github.com/coreos/go-oidc/v3/oidc"
        	"golang.org/x/oauth2"
        )

        // Authenticator is used to authenticate our users.
        type Authenticator struct {
        	*oidc.Provider
        	oauth2.Config
        }

        // New instantiates the *Authenticator.
        func New() (*Authenticator, error) {
        	provider, err := oidc.NewProvider(
        		context.Background(),
        		"https://"+os.Getenv("AUTH0_DOMAIN")+"/",
        	)
        	if err != nil {
        		return nil, err
        	}

        	conf := oauth2.Config{
        		ClientID:     os.Getenv("AUTH0_CLIENT_ID"),
        		ClientSecret: os.Getenv("AUTH0_CLIENT_SECRET"),
        		RedirectURL:  os.Getenv("AUTH0_CALLBACK_URL"),
        		Endpoint:     provider.Endpoint(),
        		Scopes:       []string{oidc.ScopeOpenID, "profile"},
        	}

        	return &Authenticator{
        		Provider: provider,
        		Config:   conf,
        	}, nil
        }

        // VerifyIDToken verifies that an *oauth2.Token is a valid *oidc.IDToken.
        func (a *Authenticator) VerifyIDToken(ctx context.Context, token *oauth2.Token) (*oidc.IDToken, error) {
        	rawIDToken, ok := token.Extra("id_token").(string)
        	if !ok {
        		return nil, errors.New("no id_token field in oauth2 token")
        	}

        	oidcConfig := &oidc.Config{
        		ClientID: a.ClientID,
        	}

        	return a.Verifier(oidcConfig).Verify(ctx, rawIDToken)
        }
        ```

        ```golang callback.go lines  theme={null}
        / Save this file in ./web/app/callback/callback.go

        package callback

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        )

        // Handler for our callback.
        func Handler(auth *authenticator.Authenticator) gin.HandlerFunc {
        	return func(ctx *gin.Context) {
        		session := sessions.Default(ctx)
        		if ctx.Query("state") != session.Get("state") {
        			ctx.String(http.StatusBadRequest, "Invalid state parameter.")
        			return
        		}

        		// Exchange an authorization code for a token.
        		token, err := auth.Exchange(ctx.Request.Context(), ctx.Query("code"))
        		if err != nil {
        			ctx.String(http.StatusUnauthorized, "Failed to exchange an authorization code for a token.")
        			return
        		}

        		idToken, err := auth.VerifyIDToken(ctx.Request.Context(), token)
        		if err != nil {
        			ctx.String(http.StatusInternalServerError, "Failed to verify ID Token.")
        			return
        		}

        		var profile map[string]interface{}
        		if err := idToken.Claims(&profile); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		session.Set("access_token", token.AccessToken)
        		session.Set("profile", profile)
        		if err := session.Save(); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		// Redirect to logged in page.
        		ctx.Redirect(http.StatusTemporaryRedirect, "/user")
        	}
        }
        ```

        ```mod go.mod lines theme={null}
        // Save this file in ./go.mod

        module 01-Login

        go 1.21

        require (
        	github.com/coreos/go-oidc/v3 v3.8.0
        	github.com/gin-contrib/sessions v0.0.5
        	github.com/gin-gonic/gin v1.9.1
        	github.com/joho/godotenv v1.5.1
        	golang.org/x/oauth2 v0.15.0
        )
        ```

        ```golang isAuthenticated.go lines theme={null}
        // Save this file in ./platform/middleware/isAuthenticated.go

        package middleware

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"
        )

        // IsAuthenticated is a middleware that checks if
        // the user has already been authenticated previously.
        func IsAuthenticated(ctx *gin.Context) {
        	if sessions.Default(ctx).Get("profile") == nil {
        		ctx.Redirect(http.StatusSeeOther, "/")
        	} else {
        		ctx.Next()
        	}
        }
        ```

        ```golang login.go lines  theme={null}
        // Save this file in ./web/app/login/login.go

        package login

        import (
        	"crypto/rand"
        	"encoding/base64"
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        )

        // Handler for our login.
        func Handler(auth *authenticator.Authenticator) gin.HandlerFunc {
        	return func(ctx *gin.Context) {
        		state, err := generateRandomState()
        		if err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		// Save the state inside the session.
        		session := sessions.Default(ctx)
        		session.Set("state", state)
        		if err := session.Save(); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		ctx.Redirect(http.StatusTemporaryRedirect, auth.AuthCodeURL(state))
        	}
        }

        func generateRandomState() (string, error) {
        	b := make([]byte, 32)
        	_, err := rand.Read(b)
        	if err != nil {
        		return "", err
        	}

        	state := base64.StdEncoding.EncodeToString(b)

        	return state, nil
        }
        ```

        ```golang logout.go lines  theme={null}
        // Save this file in ./web/app/logout/logout.go

        package logout

        import (
        	"net/http"
        	"net/url"
        	"os"

        	"github.com/gin-gonic/gin"
        )

        // Handler for our logout.
        func Handler(ctx *gin.Context) {
        	logoutUrl, err := url.Parse("https://" + os.Getenv("AUTH0_DOMAIN") + "/v2/logout")
        	if err != nil {
        		ctx.String(http.StatusInternalServerError, err.Error())
        		return
        	}

        	scheme := "http"
        	if ctx.Request.TLS != nil {
        		scheme = "https"
        	}

        	returnTo, err := url.Parse(scheme + "://" + ctx.Request.Host)
        	if err != nil {
        		ctx.String(http.StatusInternalServerError, err.Error())
        		return
        	}

        	parameters := url.Values{}
        	parameters.Add("returnTo", returnTo.String())
        	parameters.Add("client_id", os.Getenv("AUTH0_CLIENT_ID"))
        	logoutUrl.RawQuery = parameters.Encode()

        	ctx.Redirect(http.StatusTemporaryRedirect, logoutUrl.String())
        }
        ```

        ```golang main.go lines  theme={null}
        // Save this file in ./main.go

        package main

        import (
        	"log"
        	"net/http"

        	"github.com/joho/godotenv"

        	"01-Login/platform/authenticator"
        	"01-Login/platform/router"
        )

        func main() {
        	if err := godotenv.Load(); err != nil {
        		log.Fatalf("Failed to load the env vars: %v", err)
        	}

        	auth, err := authenticator.New()
        	if err != nil {
        		log.Fatalf("Failed to initialize the authenticator: %v", err)
        	}

        	rtr := router.New(auth)

        	log.Print("Server listening on http://localhost:3000/")
        	if err := http.ListenAndServe("0.0.0.0:3000", rtr); err != nil {
        		log.Fatalf("There was an error with the http server: %v", err)
        	}
        }
        ```

        ```golang router.go lines  theme={null}
        // Save this file in ./platform/router/router.go

        package router

        import (
        	"encoding/gob"
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-contrib/sessions/cookie"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        	"01-Login/platform/middleware"
        	"01-Login/web/app/callback"
        	"01-Login/web/app/login"
        	"01-Login/web/app/logout"
        	"01-Login/web/app/user"
        )

        // New registers the routes and returns the router.
        func New(auth *authenticator.Authenticator) *gin.Engine {
        	router := gin.Default()

        	// To store custom types in our cookies,
        	// we must first register them using gob.Register
        	gob.Register(map[string]interface{}{})

        	store := cookie.NewStore([]byte("secret"))
        	router.Use(sessions.Sessions("auth-session", store))

        	router.Static("/public", "web/static")
        	router.LoadHTMLGlob("web/template/*")

        	router.GET("/", func(ctx *gin.Context) {
        		ctx.HTML(http.StatusOK, "home.html", nil)
        	})
        	router.GET("/login", login.Handler(auth))
        	router.GET("/callback", callback.Handler(auth))
        	router.GET("/user", user.Handler)
        	router.GET("/logout", logout.Handler)

        	return router
        }
        ```

        ```golang user.go lines theme={null}
        // Save this file in ./web/app/user/user.go

        package user

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"
        )

        // Handler for our logged-in user page.
        func Handler(ctx *gin.Context) {
        	session := sessions.Default(ctx)
        	profile := session.Get("profile")

        	ctx.HTML(http.StatusOK, "user.html", profile)
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```golang auth.go lines  theme={null}
        // Save this file in ./platform/authenticator/auth.go

        package authenticator

        import (
        	"context"
        	"errors"
        	"os"

        	"github.com/coreos/go-oidc/v3/oidc"
        	"golang.org/x/oauth2"
        )

        // Authenticator is used to authenticate our users.
        type Authenticator struct {
        	*oidc.Provider
        	oauth2.Config
        }

        // New instantiates the *Authenticator.
        func New() (*Authenticator, error) {
        	provider, err := oidc.NewProvider(
        		context.Background(),
        		"https://"+os.Getenv("AUTH0_DOMAIN")+"/",
        	)
        	if err != nil {
        		return nil, err
        	}

        	conf := oauth2.Config{
        		ClientID:     os.Getenv("AUTH0_CLIENT_ID"),
        		ClientSecret: os.Getenv("AUTH0_CLIENT_SECRET"),
        		RedirectURL:  os.Getenv("AUTH0_CALLBACK_URL"),
        		Endpoint:     provider.Endpoint(),
        		Scopes:       []string{oidc.ScopeOpenID, "profile"},
        	}

        	return &Authenticator{
        		Provider: provider,
        		Config:   conf,
        	}, nil
        }

        // VerifyIDToken verifies that an *oauth2.Token is a valid *oidc.IDToken.
        func (a *Authenticator) VerifyIDToken(ctx context.Context, token *oauth2.Token) (*oidc.IDToken, error) {
        	rawIDToken, ok := token.Extra("id_token").(string)
        	if !ok {
        		return nil, errors.New("no id_token field in oauth2 token")
        	}

        	oidcConfig := &oidc.Config{
        		ClientID: a.ClientID,
        	}

        	return a.Verifier(oidcConfig).Verify(ctx, rawIDToken)
        }
        ```

        ```golang callback.go lines  theme={null}
        / Save this file in ./web/app/callback/callback.go

        package callback

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        )

        // Handler for our callback.
        func Handler(auth *authenticator.Authenticator) gin.HandlerFunc {
        	return func(ctx *gin.Context) {
        		session := sessions.Default(ctx)
        		if ctx.Query("state") != session.Get("state") {
        			ctx.String(http.StatusBadRequest, "Invalid state parameter.")
        			return
        		}

        		// Exchange an authorization code for a token.
        		token, err := auth.Exchange(ctx.Request.Context(), ctx.Query("code"))
        		if err != nil {
        			ctx.String(http.StatusUnauthorized, "Failed to exchange an authorization code for a token.")
        			return
        		}

        		idToken, err := auth.VerifyIDToken(ctx.Request.Context(), token)
        		if err != nil {
        			ctx.String(http.StatusInternalServerError, "Failed to verify ID Token.")
        			return
        		}

        		var profile map[string]interface{}
        		if err := idToken.Claims(&profile); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		session.Set("access_token", token.AccessToken)
        		session.Set("profile", profile)
        		if err := session.Save(); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		// Redirect to logged in page.
        		ctx.Redirect(http.StatusTemporaryRedirect, "/user")
        	}
        }
        ```

        ```env .env lines theme={null}
        # Save this file in ./.env

        # The URL of our Auth0 Tenant Domain.
        # If you're using a Custom Domain, be sure to set this to that value instead.
        AUTH0_DOMAIN='{yourDomain}'

        # Our Auth0 application's Client ID.
        AUTH0_CLIENT_ID='{yourClientId}'

        # Our Auth0 application's Client Secret.
        AUTH0_CLIENT_SECRET='{yourClientSecret}'

        # The Callback URL of our application.
        AUTH0_CALLBACK_URL='http://localhost:3000/callback'
        ```

        ```mod go.mod lines theme={null}
        // Save this file in ./go.mod

        module 01-Login

        go 1.21

        require (
        	github.com/coreos/go-oidc/v3 v3.8.0
        	github.com/gin-contrib/sessions v0.0.5
        	github.com/gin-gonic/gin v1.9.1
        	github.com/joho/godotenv v1.5.1
        	golang.org/x/oauth2 v0.15.0
        )
        ```

        ```golang isAuthenticated.go lines theme={null}
        // Save this file in ./platform/middleware/isAuthenticated.go

        package middleware

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"
        )

        // IsAuthenticated is a middleware that checks if
        // the user has already been authenticated previously.
        func IsAuthenticated(ctx *gin.Context) {
        	if sessions.Default(ctx).Get("profile") == nil {
        		ctx.Redirect(http.StatusSeeOther, "/")
        	} else {
        		ctx.Next()
        	}
        }
        ```

        ```golang login.go lines  theme={null}
        // Save this file in ./web/app/login/login.go

        package login

        import (
        	"crypto/rand"
        	"encoding/base64"
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        )

        // Handler for our login.
        func Handler(auth *authenticator.Authenticator) gin.HandlerFunc {
        	return func(ctx *gin.Context) {
        		state, err := generateRandomState()
        		if err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		// Save the state inside the session.
        		session := sessions.Default(ctx)
        		session.Set("state", state)
        		if err := session.Save(); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		ctx.Redirect(http.StatusTemporaryRedirect, auth.AuthCodeURL(state))
        	}
        }

        func generateRandomState() (string, error) {
        	b := make([]byte, 32)
        	_, err := rand.Read(b)
        	if err != nil {
        		return "", err
        	}

        	state := base64.StdEncoding.EncodeToString(b)

        	return state, nil
        }
        ```

        ```golang logout.go lines  theme={null}
        // Save this file in ./web/app/logout/logout.go

        package logout

        import (
        	"net/http"
        	"net/url"
        	"os"

        	"github.com/gin-gonic/gin"
        )

        // Handler for our logout.
        func Handler(ctx *gin.Context) {
        	logoutUrl, err := url.Parse("https://" + os.Getenv("AUTH0_DOMAIN") + "/v2/logout")
        	if err != nil {
        		ctx.String(http.StatusInternalServerError, err.Error())
        		return
        	}

        	scheme := "http"
        	if ctx.Request.TLS != nil {
        		scheme = "https"
        	}

        	returnTo, err := url.Parse(scheme + "://" + ctx.Request.Host)
        	if err != nil {
        		ctx.String(http.StatusInternalServerError, err.Error())
        		return
        	}

        	parameters := url.Values{}
        	parameters.Add("returnTo", returnTo.String())
        	parameters.Add("client_id", os.Getenv("AUTH0_CLIENT_ID"))
        	logoutUrl.RawQuery = parameters.Encode()

        	ctx.Redirect(http.StatusTemporaryRedirect, logoutUrl.String())
        }
        ```

        ```golang main.go lines  theme={null}
        // Save this file in ./main.go

        package main

        import (
        	"log"
        	"net/http"

        	"github.com/joho/godotenv"

        	"01-Login/platform/authenticator"
        	"01-Login/platform/router"
        )

        func main() {
        	if err := godotenv.Load(); err != nil {
        		log.Fatalf("Failed to load the env vars: %v", err)
        	}

        	auth, err := authenticator.New()
        	if err != nil {
        		log.Fatalf("Failed to initialize the authenticator: %v", err)
        	}

        	rtr := router.New(auth)

        	log.Print("Server listening on http://localhost:3000/")
        	if err := http.ListenAndServe("0.0.0.0:3000", rtr); err != nil {
        		log.Fatalf("There was an error with the http server: %v", err)
        	}
        }
        ```

        ```golang router.go lines  theme={null}
        // Save this file in ./platform/router/router.go

        package router

        import (
        	"encoding/gob"
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-contrib/sessions/cookie"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        	"01-Login/platform/middleware"
        	"01-Login/web/app/callback"
        	"01-Login/web/app/login"
        	"01-Login/web/app/logout"
        	"01-Login/web/app/user"
        )

        // New registers the routes and returns the router.
        func New(auth *authenticator.Authenticator) *gin.Engine {
        	router := gin.Default()

        	// To store custom types in our cookies,
        	// we must first register them using gob.Register
        	gob.Register(map[string]interface{}{})

        	store := cookie.NewStore([]byte("secret"))
        	router.Use(sessions.Sessions("auth-session", store))

        	router.Static("/public", "web/static")
        	router.LoadHTMLGlob("web/template/*")

        	router.GET("/", func(ctx *gin.Context) {
        		ctx.HTML(http.StatusOK, "home.html", nil)
        	})
        	router.GET("/login", login.Handler(auth))
        	router.GET("/callback", callback.Handler(auth))
        	router.GET("/user", user.Handler)
        	router.GET("/logout", logout.Handler)

        	return router
        }
        ```

        ```golang user.go lines theme={null}
        // Save this file in ./web/app/user/user.go

        package user

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"
        )

        // Handler for our logged-in user page.
        func Handler(ctx *gin.Context) {
        	session := sessions.Default(ctx)
        	profile := session.Get("profile")

        	ctx.HTML(http.StatusOK, "user.html", profile)
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```golang router.go lines  theme={null}
        // Save this file in ./platform/router/router.go

        package router

        import (
        	"encoding/gob"
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-contrib/sessions/cookie"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        	"01-Login/platform/middleware"
        	"01-Login/web/app/callback"
        	"01-Login/web/app/login"
        	"01-Login/web/app/logout"
        	"01-Login/web/app/user"
        )

        // New registers the routes and returns the router.
        func New(auth *authenticator.Authenticator) *gin.Engine {
        	router := gin.Default()

        	// To store custom types in our cookies,
        	// we must first register them using gob.Register
        	gob.Register(map[string]interface{}{})

        	store := cookie.NewStore([]byte("secret"))
        	router.Use(sessions.Sessions("auth-session", store))

        	router.Static("/public", "web/static")
        	router.LoadHTMLGlob("web/template/*")

        	router.GET("/", func(ctx *gin.Context) {
        		ctx.HTML(http.StatusOK, "home.html", nil)
        	})
        	router.GET("/login", login.Handler(auth))
        	router.GET("/callback", callback.Handler(auth))
        	router.GET("/user", user.Handler)
        	router.GET("/logout", logout.Handler)

        	return router
        }
        ```

        ```golang auth.go lines  theme={null}
        // Save this file in ./platform/authenticator/auth.go

        package authenticator

        import (
        	"context"
        	"errors"
        	"os"

        	"github.com/coreos/go-oidc/v3/oidc"
        	"golang.org/x/oauth2"
        )

        // Authenticator is used to authenticate our users.
        type Authenticator struct {
        	*oidc.Provider
        	oauth2.Config
        }

        // New instantiates the *Authenticator.
        func New() (*Authenticator, error) {
        	provider, err := oidc.NewProvider(
        		context.Background(),
        		"https://"+os.Getenv("AUTH0_DOMAIN")+"/",
        	)
        	if err != nil {
        		return nil, err
        	}

        	conf := oauth2.Config{
        		ClientID:     os.Getenv("AUTH0_CLIENT_ID"),
        		ClientSecret: os.Getenv("AUTH0_CLIENT_SECRET"),
        		RedirectURL:  os.Getenv("AUTH0_CALLBACK_URL"),
        		Endpoint:     provider.Endpoint(),
        		Scopes:       []string{oidc.ScopeOpenID, "profile"},
        	}

        	return &Authenticator{
        		Provider: provider,
        		Config:   conf,
        	}, nil
        }

        // VerifyIDToken verifies that an *oauth2.Token is a valid *oidc.IDToken.
        func (a *Authenticator) VerifyIDToken(ctx context.Context, token *oauth2.Token) (*oidc.IDToken, error) {
        	rawIDToken, ok := token.Extra("id_token").(string)
        	if !ok {
        		return nil, errors.New("no id_token field in oauth2 token")
        	}

        	oidcConfig := &oidc.Config{
        		ClientID: a.ClientID,
        	}

        	return a.Verifier(oidcConfig).Verify(ctx, rawIDToken)
        }
        ```

        ```golang callback.go lines  theme={null}
        / Save this file in ./web/app/callback/callback.go

        package callback

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        )

        // Handler for our callback.
        func Handler(auth *authenticator.Authenticator) gin.HandlerFunc {
        	return func(ctx *gin.Context) {
        		session := sessions.Default(ctx)
        		if ctx.Query("state") != session.Get("state") {
        			ctx.String(http.StatusBadRequest, "Invalid state parameter.")
        			return
        		}

        		// Exchange an authorization code for a token.
        		token, err := auth.Exchange(ctx.Request.Context(), ctx.Query("code"))
        		if err != nil {
        			ctx.String(http.StatusUnauthorized, "Failed to exchange an authorization code for a token.")
        			return
        		}

        		idToken, err := auth.VerifyIDToken(ctx.Request.Context(), token)
        		if err != nil {
        			ctx.String(http.StatusInternalServerError, "Failed to verify ID Token.")
        			return
        		}

        		var profile map[string]interface{}
        		if err := idToken.Claims(&profile); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		session.Set("access_token", token.AccessToken)
        		session.Set("profile", profile)
        		if err := session.Save(); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		// Redirect to logged in page.
        		ctx.Redirect(http.StatusTemporaryRedirect, "/user")
        	}
        }
        ```

        ```env .env lines theme={null}
        # Save this file in ./.env

        # The URL of our Auth0 Tenant Domain.
        # If you're using a Custom Domain, be sure to set this to that value instead.
        AUTH0_DOMAIN='{yourDomain}'

        # Our Auth0 application's Client ID.
        AUTH0_CLIENT_ID='{yourClientId}'

        # Our Auth0 application's Client Secret.
        AUTH0_CLIENT_SECRET='{yourClientSecret}'

        # The Callback URL of our application.
        AUTH0_CALLBACK_URL='http://localhost:3000/callback'
        ```

        ```mod go.mod lines theme={null}
        // Save this file in ./go.mod

        module 01-Login

        go 1.21

        require (
        	github.com/coreos/go-oidc/v3 v3.8.0
        	github.com/gin-contrib/sessions v0.0.5
        	github.com/gin-gonic/gin v1.9.1
        	github.com/joho/godotenv v1.5.1
        	golang.org/x/oauth2 v0.15.0
        )
        ```

        ```golang isAuthenticated.go lines theme={null}
        // Save this file in ./platform/middleware/isAuthenticated.go

        package middleware

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"
        )

        // IsAuthenticated is a middleware that checks if
        // the user has already been authenticated previously.
        func IsAuthenticated(ctx *gin.Context) {
        	if sessions.Default(ctx).Get("profile") == nil {
        		ctx.Redirect(http.StatusSeeOther, "/")
        	} else {
        		ctx.Next()
        	}
        }
        ```

        ```golang login.go lines  theme={null}
        // Save this file in ./web/app/login/login.go

        package login

        import (
        	"crypto/rand"
        	"encoding/base64"
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        )

        // Handler for our login.
        func Handler(auth *authenticator.Authenticator) gin.HandlerFunc {
        	return func(ctx *gin.Context) {
        		state, err := generateRandomState()
        		if err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		// Save the state inside the session.
        		session := sessions.Default(ctx)
        		session.Set("state", state)
        		if err := session.Save(); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		ctx.Redirect(http.StatusTemporaryRedirect, auth.AuthCodeURL(state))
        	}
        }

        func generateRandomState() (string, error) {
        	b := make([]byte, 32)
        	_, err := rand.Read(b)
        	if err != nil {
        		return "", err
        	}

        	state := base64.StdEncoding.EncodeToString(b)

        	return state, nil
        }
        ```

        ```golang logout.go lines  theme={null}
        // Save this file in ./web/app/logout/logout.go

        package logout

        import (
        	"net/http"
        	"net/url"
        	"os"

        	"github.com/gin-gonic/gin"
        )

        // Handler for our logout.
        func Handler(ctx *gin.Context) {
        	logoutUrl, err := url.Parse("https://" + os.Getenv("AUTH0_DOMAIN") + "/v2/logout")
        	if err != nil {
        		ctx.String(http.StatusInternalServerError, err.Error())
        		return
        	}

        	scheme := "http"
        	if ctx.Request.TLS != nil {
        		scheme = "https"
        	}

        	returnTo, err := url.Parse(scheme + "://" + ctx.Request.Host)
        	if err != nil {
        		ctx.String(http.StatusInternalServerError, err.Error())
        		return
        	}

        	parameters := url.Values{}
        	parameters.Add("returnTo", returnTo.String())
        	parameters.Add("client_id", os.Getenv("AUTH0_CLIENT_ID"))
        	logoutUrl.RawQuery = parameters.Encode()

        	ctx.Redirect(http.StatusTemporaryRedirect, logoutUrl.String())
        }
        ```

        ```golang main.go lines  theme={null}
        // Save this file in ./main.go

        package main

        import (
        	"log"
        	"net/http"

        	"github.com/joho/godotenv"

        	"01-Login/platform/authenticator"
        	"01-Login/platform/router"
        )

        func main() {
        	if err := godotenv.Load(); err != nil {
        		log.Fatalf("Failed to load the env vars: %v", err)
        	}

        	auth, err := authenticator.New()
        	if err != nil {
        		log.Fatalf("Failed to initialize the authenticator: %v", err)
        	}

        	rtr := router.New(auth)

        	log.Print("Server listening on http://localhost:3000/")
        	if err := http.ListenAndServe("0.0.0.0:3000", rtr); err != nil {
        		log.Fatalf("There was an error with the http server: %v", err)
        	}
        }
        ```

        ```golang user.go lines theme={null}
        // Save this file in ./web/app/user/user.go

        package user

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"
        )

        // Handler for our logged-in user page.
        func Handler(ctx *gin.Context) {
        	session := sessions.Default(ctx)
        	profile := session.Get("profile")

        	ctx.HTML(http.StatusOK, "user.html", profile)
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```golang login.go lines  theme={null}
        // Save this file in ./web/app/login/login.go

        package login

        import (
        	"crypto/rand"
        	"encoding/base64"
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        )

        // Handler for our login.
        func Handler(auth *authenticator.Authenticator) gin.HandlerFunc {
        	return func(ctx *gin.Context) {
        		state, err := generateRandomState()
        		if err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		// Save the state inside the session.
        		session := sessions.Default(ctx)
        		session.Set("state", state)
        		if err := session.Save(); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		ctx.Redirect(http.StatusTemporaryRedirect, auth.AuthCodeURL(state))
        	}
        }

        func generateRandomState() (string, error) {
        	b := make([]byte, 32)
        	_, err := rand.Read(b)
        	if err != nil {
        		return "", err
        	}

        	state := base64.StdEncoding.EncodeToString(b)

        	return state, nil
        }
        ```

        ```golang auth.go lines  theme={null}
        // Save this file in ./platform/authenticator/auth.go

        package authenticator

        import (
        	"context"
        	"errors"
        	"os"

        	"github.com/coreos/go-oidc/v3/oidc"
        	"golang.org/x/oauth2"
        )

        // Authenticator is used to authenticate our users.
        type Authenticator struct {
        	*oidc.Provider
        	oauth2.Config
        }

        // New instantiates the *Authenticator.
        func New() (*Authenticator, error) {
        	provider, err := oidc.NewProvider(
        		context.Background(),
        		"https://"+os.Getenv("AUTH0_DOMAIN")+"/",
        	)
        	if err != nil {
        		return nil, err
        	}

        	conf := oauth2.Config{
        		ClientID:     os.Getenv("AUTH0_CLIENT_ID"),
        		ClientSecret: os.Getenv("AUTH0_CLIENT_SECRET"),
        		RedirectURL:  os.Getenv("AUTH0_CALLBACK_URL"),
        		Endpoint:     provider.Endpoint(),
        		Scopes:       []string{oidc.ScopeOpenID, "profile"},
        	}

        	return &Authenticator{
        		Provider: provider,
        		Config:   conf,
        	}, nil
        }

        // VerifyIDToken verifies that an *oauth2.Token is a valid *oidc.IDToken.
        func (a *Authenticator) VerifyIDToken(ctx context.Context, token *oauth2.Token) (*oidc.IDToken, error) {
        	rawIDToken, ok := token.Extra("id_token").(string)
        	if !ok {
        		return nil, errors.New("no id_token field in oauth2 token")
        	}

        	oidcConfig := &oidc.Config{
        		ClientID: a.ClientID,
        	}

        	return a.Verifier(oidcConfig).Verify(ctx, rawIDToken)
        }
        ```

        ```golang callback.go lines  theme={null}
        / Save this file in ./web/app/callback/callback.go

        package callback

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        )

        // Handler for our callback.
        func Handler(auth *authenticator.Authenticator) gin.HandlerFunc {
        	return func(ctx *gin.Context) {
        		session := sessions.Default(ctx)
        		if ctx.Query("state") != session.Get("state") {
        			ctx.String(http.StatusBadRequest, "Invalid state parameter.")
        			return
        		}

        		// Exchange an authorization code for a token.
        		token, err := auth.Exchange(ctx.Request.Context(), ctx.Query("code"))
        		if err != nil {
        			ctx.String(http.StatusUnauthorized, "Failed to exchange an authorization code for a token.")
        			return
        		}

        		idToken, err := auth.VerifyIDToken(ctx.Request.Context(), token)
        		if err != nil {
        			ctx.String(http.StatusInternalServerError, "Failed to verify ID Token.")
        			return
        		}

        		var profile map[string]interface{}
        		if err := idToken.Claims(&profile); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		session.Set("access_token", token.AccessToken)
        		session.Set("profile", profile)
        		if err := session.Save(); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		// Redirect to logged in page.
        		ctx.Redirect(http.StatusTemporaryRedirect, "/user")
        	}
        }
        ```

        ```env .env lines theme={null}
        # Save this file in ./.env

        # The URL of our Auth0 Tenant Domain.
        # If you're using a Custom Domain, be sure to set this to that value instead.
        AUTH0_DOMAIN='{yourDomain}'

        # Our Auth0 application's Client ID.
        AUTH0_CLIENT_ID='{yourClientId}'

        # Our Auth0 application's Client Secret.
        AUTH0_CLIENT_SECRET='{yourClientSecret}'

        # The Callback URL of our application.
        AUTH0_CALLBACK_URL='http://localhost:3000/callback'
        ```

        ```mod go.mod lines theme={null}
        // Save this file in ./go.mod

        module 01-Login

        go 1.21

        require (
        	github.com/coreos/go-oidc/v3 v3.8.0
        	github.com/gin-contrib/sessions v0.0.5
        	github.com/gin-gonic/gin v1.9.1
        	github.com/joho/godotenv v1.5.1
        	golang.org/x/oauth2 v0.15.0
        )
        ```

        ```golang isAuthenticated.go lines theme={null}
        // Save this file in ./platform/middleware/isAuthenticated.go

        package middleware

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"
        )

        // IsAuthenticated is a middleware that checks if
        // the user has already been authenticated previously.
        func IsAuthenticated(ctx *gin.Context) {
        	if sessions.Default(ctx).Get("profile") == nil {
        		ctx.Redirect(http.StatusSeeOther, "/")
        	} else {
        		ctx.Next()
        	}
        }
        ```

        ```golang logout.go lines  theme={null}
        // Save this file in ./web/app/logout/logout.go

        package logout

        import (
        	"net/http"
        	"net/url"
        	"os"

        	"github.com/gin-gonic/gin"
        )

        // Handler for our logout.
        func Handler(ctx *gin.Context) {
        	logoutUrl, err := url.Parse("https://" + os.Getenv("AUTH0_DOMAIN") + "/v2/logout")
        	if err != nil {
        		ctx.String(http.StatusInternalServerError, err.Error())
        		return
        	}

        	scheme := "http"
        	if ctx.Request.TLS != nil {
        		scheme = "https"
        	}

        	returnTo, err := url.Parse(scheme + "://" + ctx.Request.Host)
        	if err != nil {
        		ctx.String(http.StatusInternalServerError, err.Error())
        		return
        	}

        	parameters := url.Values{}
        	parameters.Add("returnTo", returnTo.String())
        	parameters.Add("client_id", os.Getenv("AUTH0_CLIENT_ID"))
        	logoutUrl.RawQuery = parameters.Encode()

        	ctx.Redirect(http.StatusTemporaryRedirect, logoutUrl.String())
        }
        ```

        ```golang main.go lines  theme={null}
        // Save this file in ./main.go

        package main

        import (
        	"log"
        	"net/http"

        	"github.com/joho/godotenv"

        	"01-Login/platform/authenticator"
        	"01-Login/platform/router"
        )

        func main() {
        	if err := godotenv.Load(); err != nil {
        		log.Fatalf("Failed to load the env vars: %v", err)
        	}

        	auth, err := authenticator.New()
        	if err != nil {
        		log.Fatalf("Failed to initialize the authenticator: %v", err)
        	}

        	rtr := router.New(auth)

        	log.Print("Server listening on http://localhost:3000/")
        	if err := http.ListenAndServe("0.0.0.0:3000", rtr); err != nil {
        		log.Fatalf("There was an error with the http server: %v", err)
        	}
        }
        ```

        ```golang router.go lines  theme={null}
        // Save this file in ./platform/router/router.go

        package router

        import (
        	"encoding/gob"
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-contrib/sessions/cookie"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        	"01-Login/platform/middleware"
        	"01-Login/web/app/callback"
        	"01-Login/web/app/login"
        	"01-Login/web/app/logout"
        	"01-Login/web/app/user"
        )

        // New registers the routes and returns the router.
        func New(auth *authenticator.Authenticator) *gin.Engine {
        	router := gin.Default()

        	// To store custom types in our cookies,
        	// we must first register them using gob.Register
        	gob.Register(map[string]interface{}{})

        	store := cookie.NewStore([]byte("secret"))
        	router.Use(sessions.Sessions("auth-session", store))

        	router.Static("/public", "web/static")
        	router.LoadHTMLGlob("web/template/*")

        	router.GET("/", func(ctx *gin.Context) {
        		ctx.HTML(http.StatusOK, "home.html", nil)
        	})
        	router.GET("/login", login.Handler(auth))
        	router.GET("/callback", callback.Handler(auth))
        	router.GET("/user", user.Handler)
        	router.GET("/logout", logout.Handler)

        	return router
        }
        ```

        ```golang user.go lines theme={null}
        // Save this file in ./web/app/user/user.go

        package user

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"
        )

        // Handler for our logged-in user page.
        func Handler(ctx *gin.Context) {
        	session := sessions.Default(ctx)
        	profile := session.Get("profile")

        	ctx.HTML(http.StatusOK, "user.html", profile)
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```golang callback.go lines  theme={null}
        / Save this file in ./web/app/callback/callback.go

        package callback

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        )

        // Handler for our callback.
        func Handler(auth *authenticator.Authenticator) gin.HandlerFunc {
        	return func(ctx *gin.Context) {
        		session := sessions.Default(ctx)
        		if ctx.Query("state") != session.Get("state") {
        			ctx.String(http.StatusBadRequest, "Invalid state parameter.")
        			return
        		}

        		// Exchange an authorization code for a token.
        		token, err := auth.Exchange(ctx.Request.Context(), ctx.Query("code"))
        		if err != nil {
        			ctx.String(http.StatusUnauthorized, "Failed to exchange an authorization code for a token.")
        			return
        		}

        		idToken, err := auth.VerifyIDToken(ctx.Request.Context(), token)
        		if err != nil {
        			ctx.String(http.StatusInternalServerError, "Failed to verify ID Token.")
        			return
        		}

        		var profile map[string]interface{}
        		if err := idToken.Claims(&profile); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		session.Set("access_token", token.AccessToken)
        		session.Set("profile", profile)
        		if err := session.Save(); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		// Redirect to logged in page.
        		ctx.Redirect(http.StatusTemporaryRedirect, "/user")
        	}
        }
        ```

        ```golang auth.go lines  theme={null}
        // Save this file in ./platform/authenticator/auth.go

        package authenticator

        import (
        	"context"
        	"errors"
        	"os"

        	"github.com/coreos/go-oidc/v3/oidc"
        	"golang.org/x/oauth2"
        )

        // Authenticator is used to authenticate our users.
        type Authenticator struct {
        	*oidc.Provider
        	oauth2.Config
        }

        // New instantiates the *Authenticator.
        func New() (*Authenticator, error) {
        	provider, err := oidc.NewProvider(
        		context.Background(),
        		"https://"+os.Getenv("AUTH0_DOMAIN")+"/",
        	)
        	if err != nil {
        		return nil, err
        	}

        	conf := oauth2.Config{
        		ClientID:     os.Getenv("AUTH0_CLIENT_ID"),
        		ClientSecret: os.Getenv("AUTH0_CLIENT_SECRET"),
        		RedirectURL:  os.Getenv("AUTH0_CALLBACK_URL"),
        		Endpoint:     provider.Endpoint(),
        		Scopes:       []string{oidc.ScopeOpenID, "profile"},
        	}

        	return &Authenticator{
        		Provider: provider,
        		Config:   conf,
        	}, nil
        }

        // VerifyIDToken verifies that an *oauth2.Token is a valid *oidc.IDToken.
        func (a *Authenticator) VerifyIDToken(ctx context.Context, token *oauth2.Token) (*oidc.IDToken, error) {
        	rawIDToken, ok := token.Extra("id_token").(string)
        	if !ok {
        		return nil, errors.New("no id_token field in oauth2 token")
        	}

        	oidcConfig := &oidc.Config{
        		ClientID: a.ClientID,
        	}

        	return a.Verifier(oidcConfig).Verify(ctx, rawIDToken)
        }
        ```

        ```env .env lines theme={null}
        # Save this file in ./.env

        # The URL of our Auth0 Tenant Domain.
        # If you're using a Custom Domain, be sure to set this to that value instead.
        AUTH0_DOMAIN='{yourDomain}'

        # Our Auth0 application's Client ID.
        AUTH0_CLIENT_ID='{yourClientId}'

        # Our Auth0 application's Client Secret.
        AUTH0_CLIENT_SECRET='{yourClientSecret}'

        # The Callback URL of our application.
        AUTH0_CALLBACK_URL='http://localhost:3000/callback'
        ```

        ```mod go.mod lines theme={null}
        // Save this file in ./go.mod

        module 01-Login

        go 1.21

        require (
        	github.com/coreos/go-oidc/v3 v3.8.0
        	github.com/gin-contrib/sessions v0.0.5
        	github.com/gin-gonic/gin v1.9.1
        	github.com/joho/godotenv v1.5.1
        	golang.org/x/oauth2 v0.15.0
        )
        ```

        ```golang isAuthenticated.go lines theme={null}
        // Save this file in ./platform/middleware/isAuthenticated.go

        package middleware

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"
        )

        // IsAuthenticated is a middleware that checks if
        // the user has already been authenticated previously.
        func IsAuthenticated(ctx *gin.Context) {
        	if sessions.Default(ctx).Get("profile") == nil {
        		ctx.Redirect(http.StatusSeeOther, "/")
        	} else {
        		ctx.Next()
        	}
        }
        ```

        ```golang login.go lines  theme={null}
        // Save this file in ./web/app/login/login.go

        package login

        import (
        	"crypto/rand"
        	"encoding/base64"
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        )

        // Handler for our login.
        func Handler(auth *authenticator.Authenticator) gin.HandlerFunc {
        	return func(ctx *gin.Context) {
        		state, err := generateRandomState()
        		if err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		// Save the state inside the session.
        		session := sessions.Default(ctx)
        		session.Set("state", state)
        		if err := session.Save(); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		ctx.Redirect(http.StatusTemporaryRedirect, auth.AuthCodeURL(state))
        	}
        }

        func generateRandomState() (string, error) {
        	b := make([]byte, 32)
        	_, err := rand.Read(b)
        	if err != nil {
        		return "", err
        	}

        	state := base64.StdEncoding.EncodeToString(b)

        	return state, nil
        }
        ```

        ```golang logout.go lines  theme={null}
        // Save this file in ./web/app/logout/logout.go

        package logout

        import (
        	"net/http"
        	"net/url"
        	"os"

        	"github.com/gin-gonic/gin"
        )

        // Handler for our logout.
        func Handler(ctx *gin.Context) {
        	logoutUrl, err := url.Parse("https://" + os.Getenv("AUTH0_DOMAIN") + "/v2/logout")
        	if err != nil {
        		ctx.String(http.StatusInternalServerError, err.Error())
        		return
        	}

        	scheme := "http"
        	if ctx.Request.TLS != nil {
        		scheme = "https"
        	}

        	returnTo, err := url.Parse(scheme + "://" + ctx.Request.Host)
        	if err != nil {
        		ctx.String(http.StatusInternalServerError, err.Error())
        		return
        	}

        	parameters := url.Values{}
        	parameters.Add("returnTo", returnTo.String())
        	parameters.Add("client_id", os.Getenv("AUTH0_CLIENT_ID"))
        	logoutUrl.RawQuery = parameters.Encode()

        	ctx.Redirect(http.StatusTemporaryRedirect, logoutUrl.String())
        }
        ```

        ```golang main.go lines  theme={null}
        // Save this file in ./main.go

        package main

        import (
        	"log"
        	"net/http"

        	"github.com/joho/godotenv"

        	"01-Login/platform/authenticator"
        	"01-Login/platform/router"
        )

        func main() {
        	if err := godotenv.Load(); err != nil {
        		log.Fatalf("Failed to load the env vars: %v", err)
        	}

        	auth, err := authenticator.New()
        	if err != nil {
        		log.Fatalf("Failed to initialize the authenticator: %v", err)
        	}

        	rtr := router.New(auth)

        	log.Print("Server listening on http://localhost:3000/")
        	if err := http.ListenAndServe("0.0.0.0:3000", rtr); err != nil {
        		log.Fatalf("There was an error with the http server: %v", err)
        	}
        }
        ```

        ```golang router.go lines  theme={null}
        // Save this file in ./platform/router/router.go

        package router

        import (
        	"encoding/gob"
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-contrib/sessions/cookie"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        	"01-Login/platform/middleware"
        	"01-Login/web/app/callback"
        	"01-Login/web/app/login"
        	"01-Login/web/app/logout"
        	"01-Login/web/app/user"
        )

        // New registers the routes and returns the router.
        func New(auth *authenticator.Authenticator) *gin.Engine {
        	router := gin.Default()

        	// To store custom types in our cookies,
        	// we must first register them using gob.Register
        	gob.Register(map[string]interface{}{})

        	store := cookie.NewStore([]byte("secret"))
        	router.Use(sessions.Sessions("auth-session", store))

        	router.Static("/public", "web/static")
        	router.LoadHTMLGlob("web/template/*")

        	router.GET("/", func(ctx *gin.Context) {
        		ctx.HTML(http.StatusOK, "home.html", nil)
        	})
        	router.GET("/login", login.Handler(auth))
        	router.GET("/callback", callback.Handler(auth))
        	router.GET("/user", user.Handler)
        	router.GET("/logout", logout.Handler)

        	return router
        }
        ```

        ```golang user.go lines theme={null}
        // Save this file in ./web/app/user/user.go

        package user

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"
        )

        // Handler for our logged-in user page.
        func Handler(ctx *gin.Context) {
        	session := sessions.Default(ctx)
        	profile := session.Get("profile")

        	ctx.HTML(http.StatusOK, "user.html", profile)
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```golang user.go lines theme={null}
        // Save this file in ./web/app/user/user.go

        package user

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"
        )

        // Handler for our logged-in user page.
        func Handler(ctx *gin.Context) {
        	session := sessions.Default(ctx)
        	profile := session.Get("profile")

        	ctx.HTML(http.StatusOK, "user.html", profile)
        }
        ```

        ```golang auth.go lines  theme={null}
        // Save this file in ./platform/authenticator/auth.go

        package authenticator

        import (
        	"context"
        	"errors"
        	"os"

        	"github.com/coreos/go-oidc/v3/oidc"
        	"golang.org/x/oauth2"
        )

        // Authenticator is used to authenticate our users.
        type Authenticator struct {
        	*oidc.Provider
        	oauth2.Config
        }

        // New instantiates the *Authenticator.
        func New() (*Authenticator, error) {
        	provider, err := oidc.NewProvider(
        		context.Background(),
        		"https://"+os.Getenv("AUTH0_DOMAIN")+"/",
        	)
        	if err != nil {
        		return nil, err
        	}

        	conf := oauth2.Config{
        		ClientID:     os.Getenv("AUTH0_CLIENT_ID"),
        		ClientSecret: os.Getenv("AUTH0_CLIENT_SECRET"),
        		RedirectURL:  os.Getenv("AUTH0_CALLBACK_URL"),
        		Endpoint:     provider.Endpoint(),
        		Scopes:       []string{oidc.ScopeOpenID, "profile"},
        	}

        	return &Authenticator{
        		Provider: provider,
        		Config:   conf,
        	}, nil
        }

        // VerifyIDToken verifies that an *oauth2.Token is a valid *oidc.IDToken.
        func (a *Authenticator) VerifyIDToken(ctx context.Context, token *oauth2.Token) (*oidc.IDToken, error) {
        	rawIDToken, ok := token.Extra("id_token").(string)
        	if !ok {
        		return nil, errors.New("no id_token field in oauth2 token")
        	}

        	oidcConfig := &oidc.Config{
        		ClientID: a.ClientID,
        	}

        	return a.Verifier(oidcConfig).Verify(ctx, rawIDToken)
        }
        ```

        ```golang callback.go lines  theme={null}
        / Save this file in ./web/app/callback/callback.go

        package callback

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        )

        // Handler for our callback.
        func Handler(auth *authenticator.Authenticator) gin.HandlerFunc {
        	return func(ctx *gin.Context) {
        		session := sessions.Default(ctx)
        		if ctx.Query("state") != session.Get("state") {
        			ctx.String(http.StatusBadRequest, "Invalid state parameter.")
        			return
        		}

        		// Exchange an authorization code for a token.
        		token, err := auth.Exchange(ctx.Request.Context(), ctx.Query("code"))
        		if err != nil {
        			ctx.String(http.StatusUnauthorized, "Failed to exchange an authorization code for a token.")
        			return
        		}

        		idToken, err := auth.VerifyIDToken(ctx.Request.Context(), token)
        		if err != nil {
        			ctx.String(http.StatusInternalServerError, "Failed to verify ID Token.")
        			return
        		}

        		var profile map[string]interface{}
        		if err := idToken.Claims(&profile); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		session.Set("access_token", token.AccessToken)
        		session.Set("profile", profile)
        		if err := session.Save(); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		// Redirect to logged in page.
        		ctx.Redirect(http.StatusTemporaryRedirect, "/user")
        	}
        }
        ```

        ```env .env lines theme={null}
        # Save this file in ./.env

        # The URL of our Auth0 Tenant Domain.
        # If you're using a Custom Domain, be sure to set this to that value instead.
        AUTH0_DOMAIN='{yourDomain}'

        # Our Auth0 application's Client ID.
        AUTH0_CLIENT_ID='{yourClientId}'

        # Our Auth0 application's Client Secret.
        AUTH0_CLIENT_SECRET='{yourClientSecret}'

        # The Callback URL of our application.
        AUTH0_CALLBACK_URL='http://localhost:3000/callback'
        ```

        ```mod go.mod lines theme={null}
        // Save this file in ./go.mod

        module 01-Login

        go 1.21

        require (
        	github.com/coreos/go-oidc/v3 v3.8.0
        	github.com/gin-contrib/sessions v0.0.5
        	github.com/gin-gonic/gin v1.9.1
        	github.com/joho/godotenv v1.5.1
        	golang.org/x/oauth2 v0.15.0
        )
        ```

        ```golang isAuthenticated.go lines theme={null}
        // Save this file in ./platform/middleware/isAuthenticated.go

        package middleware

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"
        )

        // IsAuthenticated is a middleware that checks if
        // the user has already been authenticated previously.
        func IsAuthenticated(ctx *gin.Context) {
        	if sessions.Default(ctx).Get("profile") == nil {
        		ctx.Redirect(http.StatusSeeOther, "/")
        	} else {
        		ctx.Next()
        	}
        }
        ```

        ```golang login.go lines  theme={null}
        // Save this file in ./web/app/login/login.go

        package login

        import (
        	"crypto/rand"
        	"encoding/base64"
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        )

        // Handler for our login.
        func Handler(auth *authenticator.Authenticator) gin.HandlerFunc {
        	return func(ctx *gin.Context) {
        		state, err := generateRandomState()
        		if err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		// Save the state inside the session.
        		session := sessions.Default(ctx)
        		session.Set("state", state)
        		if err := session.Save(); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		ctx.Redirect(http.StatusTemporaryRedirect, auth.AuthCodeURL(state))
        	}
        }

        func generateRandomState() (string, error) {
        	b := make([]byte, 32)
        	_, err := rand.Read(b)
        	if err != nil {
        		return "", err
        	}

        	state := base64.StdEncoding.EncodeToString(b)

        	return state, nil
        }
        ```

        ```golang logout.go lines  theme={null}
        // Save this file in ./web/app/logout/logout.go

        package logout

        import (
        	"net/http"
        	"net/url"
        	"os"

        	"github.com/gin-gonic/gin"
        )

        // Handler for our logout.
        func Handler(ctx *gin.Context) {
        	logoutUrl, err := url.Parse("https://" + os.Getenv("AUTH0_DOMAIN") + "/v2/logout")
        	if err != nil {
        		ctx.String(http.StatusInternalServerError, err.Error())
        		return
        	}

        	scheme := "http"
        	if ctx.Request.TLS != nil {
        		scheme = "https"
        	}

        	returnTo, err := url.Parse(scheme + "://" + ctx.Request.Host)
        	if err != nil {
        		ctx.String(http.StatusInternalServerError, err.Error())
        		return
        	}

        	parameters := url.Values{}
        	parameters.Add("returnTo", returnTo.String())
        	parameters.Add("client_id", os.Getenv("AUTH0_CLIENT_ID"))
        	logoutUrl.RawQuery = parameters.Encode()

        	ctx.Redirect(http.StatusTemporaryRedirect, logoutUrl.String())
        }
        ```

        ```golang main.go lines  theme={null}
        // Save this file in ./main.go

        package main

        import (
        	"log"
        	"net/http"

        	"github.com/joho/godotenv"

        	"01-Login/platform/authenticator"
        	"01-Login/platform/router"
        )

        func main() {
        	if err := godotenv.Load(); err != nil {
        		log.Fatalf("Failed to load the env vars: %v", err)
        	}

        	auth, err := authenticator.New()
        	if err != nil {
        		log.Fatalf("Failed to initialize the authenticator: %v", err)
        	}

        	rtr := router.New(auth)

        	log.Print("Server listening on http://localhost:3000/")
        	if err := http.ListenAndServe("0.0.0.0:3000", rtr); err != nil {
        		log.Fatalf("There was an error with the http server: %v", err)
        	}
        }
        ```

        ```golang router.go lines  theme={null}
        // Save this file in ./platform/router/router.go

        package router

        import (
        	"encoding/gob"
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-contrib/sessions/cookie"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        	"01-Login/platform/middleware"
        	"01-Login/web/app/callback"
        	"01-Login/web/app/login"
        	"01-Login/web/app/logout"
        	"01-Login/web/app/user"
        )

        // New registers the routes and returns the router.
        func New(auth *authenticator.Authenticator) *gin.Engine {
        	router := gin.Default()

        	// To store custom types in our cookies,
        	// we must first register them using gob.Register
        	gob.Register(map[string]interface{}{})

        	store := cookie.NewStore([]byte("secret"))
        	router.Use(sessions.Sessions("auth-session", store))

        	router.Static("/public", "web/static")
        	router.LoadHTMLGlob("web/template/*")

        	router.GET("/", func(ctx *gin.Context) {
        		ctx.HTML(http.StatusOK, "home.html", nil)
        	})
        	router.GET("/login", login.Handler(auth))
        	router.GET("/callback", callback.Handler(auth))
        	router.GET("/user", user.Handler)
        	router.GET("/logout", logout.Handler)

        	return router
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```golang logout.go lines  theme={null}
        // Save this file in ./web/app/logout/logout.go

        package logout

        import (
        	"net/http"
        	"net/url"
        	"os"

        	"github.com/gin-gonic/gin"
        )

        // Handler for our logout.
        func Handler(ctx *gin.Context) {
        	logoutUrl, err := url.Parse("https://" + os.Getenv("AUTH0_DOMAIN") + "/v2/logout")
        	if err != nil {
        		ctx.String(http.StatusInternalServerError, err.Error())
        		return
        	}

        	scheme := "http"
        	if ctx.Request.TLS != nil {
        		scheme = "https"
        	}

        	returnTo, err := url.Parse(scheme + "://" + ctx.Request.Host)
        	if err != nil {
        		ctx.String(http.StatusInternalServerError, err.Error())
        		return
        	}

        	parameters := url.Values{}
        	parameters.Add("returnTo", returnTo.String())
        	parameters.Add("client_id", os.Getenv("AUTH0_CLIENT_ID"))
        	logoutUrl.RawQuery = parameters.Encode()

        	ctx.Redirect(http.StatusTemporaryRedirect, logoutUrl.String())
        }
        ```

        ```golang auth.go lines  theme={null}
        // Save this file in ./platform/authenticator/auth.go

        package authenticator

        import (
        	"context"
        	"errors"
        	"os"

        	"github.com/coreos/go-oidc/v3/oidc"
        	"golang.org/x/oauth2"
        )

        // Authenticator is used to authenticate our users.
        type Authenticator struct {
        	*oidc.Provider
        	oauth2.Config
        }

        // New instantiates the *Authenticator.
        func New() (*Authenticator, error) {
        	provider, err := oidc.NewProvider(
        		context.Background(),
        		"https://"+os.Getenv("AUTH0_DOMAIN")+"/",
        	)
        	if err != nil {
        		return nil, err
        	}

        	conf := oauth2.Config{
        		ClientID:     os.Getenv("AUTH0_CLIENT_ID"),
        		ClientSecret: os.Getenv("AUTH0_CLIENT_SECRET"),
        		RedirectURL:  os.Getenv("AUTH0_CALLBACK_URL"),
        		Endpoint:     provider.Endpoint(),
        		Scopes:       []string{oidc.ScopeOpenID, "profile"},
        	}

        	return &Authenticator{
        		Provider: provider,
        		Config:   conf,
        	}, nil
        }

        // VerifyIDToken verifies that an *oauth2.Token is a valid *oidc.IDToken.
        func (a *Authenticator) VerifyIDToken(ctx context.Context, token *oauth2.Token) (*oidc.IDToken, error) {
        	rawIDToken, ok := token.Extra("id_token").(string)
        	if !ok {
        		return nil, errors.New("no id_token field in oauth2 token")
        	}

        	oidcConfig := &oidc.Config{
        		ClientID: a.ClientID,
        	}

        	return a.Verifier(oidcConfig).Verify(ctx, rawIDToken)
        }
        ```

        ```golang callback.go lines  theme={null}
        / Save this file in ./web/app/callback/callback.go

        package callback

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        )

        // Handler for our callback.
        func Handler(auth *authenticator.Authenticator) gin.HandlerFunc {
        	return func(ctx *gin.Context) {
        		session := sessions.Default(ctx)
        		if ctx.Query("state") != session.Get("state") {
        			ctx.String(http.StatusBadRequest, "Invalid state parameter.")
        			return
        		}

        		// Exchange an authorization code for a token.
        		token, err := auth.Exchange(ctx.Request.Context(), ctx.Query("code"))
        		if err != nil {
        			ctx.String(http.StatusUnauthorized, "Failed to exchange an authorization code for a token.")
        			return
        		}

        		idToken, err := auth.VerifyIDToken(ctx.Request.Context(), token)
        		if err != nil {
        			ctx.String(http.StatusInternalServerError, "Failed to verify ID Token.")
        			return
        		}

        		var profile map[string]interface{}
        		if err := idToken.Claims(&profile); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		session.Set("access_token", token.AccessToken)
        		session.Set("profile", profile)
        		if err := session.Save(); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		// Redirect to logged in page.
        		ctx.Redirect(http.StatusTemporaryRedirect, "/user")
        	}
        }
        ```

        ```env .env lines theme={null}
        # Save this file in ./.env

        # The URL of our Auth0 Tenant Domain.
        # If you're using a Custom Domain, be sure to set this to that value instead.
        AUTH0_DOMAIN='{yourDomain}'

        # Our Auth0 application's Client ID.
        AUTH0_CLIENT_ID='{yourClientId}'

        # Our Auth0 application's Client Secret.
        AUTH0_CLIENT_SECRET='{yourClientSecret}'

        # The Callback URL of our application.
        AUTH0_CALLBACK_URL='http://localhost:3000/callback'
        ```

        ```mod go.mod lines theme={null}
        // Save this file in ./go.mod

        module 01-Login

        go 1.21

        require (
        	github.com/coreos/go-oidc/v3 v3.8.0
        	github.com/gin-contrib/sessions v0.0.5
        	github.com/gin-gonic/gin v1.9.1
        	github.com/joho/godotenv v1.5.1
        	golang.org/x/oauth2 v0.15.0
        )
        ```

        ```golang isAuthenticated.go lines theme={null}
        // Save this file in ./platform/middleware/isAuthenticated.go

        package middleware

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"
        )

        // IsAuthenticated is a middleware that checks if
        // the user has already been authenticated previously.
        func IsAuthenticated(ctx *gin.Context) {
        	if sessions.Default(ctx).Get("profile") == nil {
        		ctx.Redirect(http.StatusSeeOther, "/")
        	} else {
        		ctx.Next()
        	}
        }
        ```

        ```golang login.go lines  theme={null}
        // Save this file in ./web/app/login/login.go

        package login

        import (
        	"crypto/rand"
        	"encoding/base64"
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        )

        // Handler for our login.
        func Handler(auth *authenticator.Authenticator) gin.HandlerFunc {
        	return func(ctx *gin.Context) {
        		state, err := generateRandomState()
        		if err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		// Save the state inside the session.
        		session := sessions.Default(ctx)
        		session.Set("state", state)
        		if err := session.Save(); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		ctx.Redirect(http.StatusTemporaryRedirect, auth.AuthCodeURL(state))
        	}
        }

        func generateRandomState() (string, error) {
        	b := make([]byte, 32)
        	_, err := rand.Read(b)
        	if err != nil {
        		return "", err
        	}

        	state := base64.StdEncoding.EncodeToString(b)

        	return state, nil
        }
        ```

        ```golang main.go lines  theme={null}
        // Save this file in ./main.go

        package main

        import (
        	"log"
        	"net/http"

        	"github.com/joho/godotenv"

        	"01-Login/platform/authenticator"
        	"01-Login/platform/router"
        )

        func main() {
        	if err := godotenv.Load(); err != nil {
        		log.Fatalf("Failed to load the env vars: %v", err)
        	}

        	auth, err := authenticator.New()
        	if err != nil {
        		log.Fatalf("Failed to initialize the authenticator: %v", err)
        	}

        	rtr := router.New(auth)

        	log.Print("Server listening on http://localhost:3000/")
        	if err := http.ListenAndServe("0.0.0.0:3000", rtr); err != nil {
        		log.Fatalf("There was an error with the http server: %v", err)
        	}
        }
        ```

        ```golang router.go lines  theme={null}
        // Save this file in ./platform/router/router.go

        package router

        import (
        	"encoding/gob"
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-contrib/sessions/cookie"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        	"01-Login/platform/middleware"
        	"01-Login/web/app/callback"
        	"01-Login/web/app/login"
        	"01-Login/web/app/logout"
        	"01-Login/web/app/user"
        )

        // New registers the routes and returns the router.
        func New(auth *authenticator.Authenticator) *gin.Engine {
        	router := gin.Default()

        	// To store custom types in our cookies,
        	// we must first register them using gob.Register
        	gob.Register(map[string]interface{}{})

        	store := cookie.NewStore([]byte("secret"))
        	router.Use(sessions.Sessions("auth-session", store))

        	router.Static("/public", "web/static")
        	router.LoadHTMLGlob("web/template/*")

        	router.GET("/", func(ctx *gin.Context) {
        		ctx.HTML(http.StatusOK, "home.html", nil)
        	})
        	router.GET("/login", login.Handler(auth))
        	router.GET("/callback", callback.Handler(auth))
        	router.GET("/user", user.Handler)
        	router.GET("/logout", logout.Handler)

        	return router
        }
        ```

        ```golang user.go lines theme={null}
        // Save this file in ./web/app/user/user.go

        package user

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"
        )

        // Handler for our logged-in user page.
        func Handler(ctx *gin.Context) {
        	session := sessions.Default(ctx)
        	profile := session.Get("profile")

        	ctx.HTML(http.StatusOK, "user.html", profile)
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```golang isAuthenticated.go lines theme={null}
        // Save this file in ./platform/middleware/isAuthenticated.go

        package middleware

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"
        )

        // IsAuthenticated is a middleware that checks if
        // the user has already been authenticated previously.
        func IsAuthenticated(ctx *gin.Context) {
        	if sessions.Default(ctx).Get("profile") == nil {
        		ctx.Redirect(http.StatusSeeOther, "/")
        	} else {
        		ctx.Next()
        	}
        }
        ```

        ```golang auth.go lines  theme={null}
        // Save this file in ./platform/authenticator/auth.go

        package authenticator

        import (
        	"context"
        	"errors"
        	"os"

        	"github.com/coreos/go-oidc/v3/oidc"
        	"golang.org/x/oauth2"
        )

        // Authenticator is used to authenticate our users.
        type Authenticator struct {
        	*oidc.Provider
        	oauth2.Config
        }

        // New instantiates the *Authenticator.
        func New() (*Authenticator, error) {
        	provider, err := oidc.NewProvider(
        		context.Background(),
        		"https://"+os.Getenv("AUTH0_DOMAIN")+"/",
        	)
        	if err != nil {
        		return nil, err
        	}

        	conf := oauth2.Config{
        		ClientID:     os.Getenv("AUTH0_CLIENT_ID"),
        		ClientSecret: os.Getenv("AUTH0_CLIENT_SECRET"),
        		RedirectURL:  os.Getenv("AUTH0_CALLBACK_URL"),
        		Endpoint:     provider.Endpoint(),
        		Scopes:       []string{oidc.ScopeOpenID, "profile"},
        	}

        	return &Authenticator{
        		Provider: provider,
        		Config:   conf,
        	}, nil
        }

        // VerifyIDToken verifies that an *oauth2.Token is a valid *oidc.IDToken.
        func (a *Authenticator) VerifyIDToken(ctx context.Context, token *oauth2.Token) (*oidc.IDToken, error) {
        	rawIDToken, ok := token.Extra("id_token").(string)
        	if !ok {
        		return nil, errors.New("no id_token field in oauth2 token")
        	}

        	oidcConfig := &oidc.Config{
        		ClientID: a.ClientID,
        	}

        	return a.Verifier(oidcConfig).Verify(ctx, rawIDToken)
        }
        ```

        ```golang callback.go lines  theme={null}
        / Save this file in ./web/app/callback/callback.go

        package callback

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        )

        // Handler for our callback.
        func Handler(auth *authenticator.Authenticator) gin.HandlerFunc {
        	return func(ctx *gin.Context) {
        		session := sessions.Default(ctx)
        		if ctx.Query("state") != session.Get("state") {
        			ctx.String(http.StatusBadRequest, "Invalid state parameter.")
        			return
        		}

        		// Exchange an authorization code for a token.
        		token, err := auth.Exchange(ctx.Request.Context(), ctx.Query("code"))
        		if err != nil {
        			ctx.String(http.StatusUnauthorized, "Failed to exchange an authorization code for a token.")
        			return
        		}

        		idToken, err := auth.VerifyIDToken(ctx.Request.Context(), token)
        		if err != nil {
        			ctx.String(http.StatusInternalServerError, "Failed to verify ID Token.")
        			return
        		}

        		var profile map[string]interface{}
        		if err := idToken.Claims(&profile); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		session.Set("access_token", token.AccessToken)
        		session.Set("profile", profile)
        		if err := session.Save(); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		// Redirect to logged in page.
        		ctx.Redirect(http.StatusTemporaryRedirect, "/user")
        	}
        }
        ```

        ```env .env lines theme={null}
        # Save this file in ./.env

        # The URL of our Auth0 Tenant Domain.
        # If you're using a Custom Domain, be sure to set this to that value instead.
        AUTH0_DOMAIN='{yourDomain}'

        # Our Auth0 application's Client ID.
        AUTH0_CLIENT_ID='{yourClientId}'

        # Our Auth0 application's Client Secret.
        AUTH0_CLIENT_SECRET='{yourClientSecret}'

        # The Callback URL of our application.
        AUTH0_CALLBACK_URL='http://localhost:3000/callback'
        ```

        ```mod go.mod lines theme={null}
        // Save this file in ./go.mod

        module 01-Login

        go 1.21

        require (
        	github.com/coreos/go-oidc/v3 v3.8.0
        	github.com/gin-contrib/sessions v0.0.5
        	github.com/gin-gonic/gin v1.9.1
        	github.com/joho/godotenv v1.5.1
        	golang.org/x/oauth2 v0.15.0
        )
        ```

        ```golang login.go lines  theme={null}
        // Save this file in ./web/app/login/login.go

        package login

        import (
        	"crypto/rand"
        	"encoding/base64"
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        )

        // Handler for our login.
        func Handler(auth *authenticator.Authenticator) gin.HandlerFunc {
        	return func(ctx *gin.Context) {
        		state, err := generateRandomState()
        		if err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		// Save the state inside the session.
        		session := sessions.Default(ctx)
        		session.Set("state", state)
        		if err := session.Save(); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		ctx.Redirect(http.StatusTemporaryRedirect, auth.AuthCodeURL(state))
        	}
        }

        func generateRandomState() (string, error) {
        	b := make([]byte, 32)
        	_, err := rand.Read(b)
        	if err != nil {
        		return "", err
        	}

        	state := base64.StdEncoding.EncodeToString(b)

        	return state, nil
        }
        ```

        ```golang logout.go lines  theme={null}
        // Save this file in ./web/app/logout/logout.go

        package logout

        import (
        	"net/http"
        	"net/url"
        	"os"

        	"github.com/gin-gonic/gin"
        )

        // Handler for our logout.
        func Handler(ctx *gin.Context) {
        	logoutUrl, err := url.Parse("https://" + os.Getenv("AUTH0_DOMAIN") + "/v2/logout")
        	if err != nil {
        		ctx.String(http.StatusInternalServerError, err.Error())
        		return
        	}

        	scheme := "http"
        	if ctx.Request.TLS != nil {
        		scheme = "https"
        	}

        	returnTo, err := url.Parse(scheme + "://" + ctx.Request.Host)
        	if err != nil {
        		ctx.String(http.StatusInternalServerError, err.Error())
        		return
        	}

        	parameters := url.Values{}
        	parameters.Add("returnTo", returnTo.String())
        	parameters.Add("client_id", os.Getenv("AUTH0_CLIENT_ID"))
        	logoutUrl.RawQuery = parameters.Encode()

        	ctx.Redirect(http.StatusTemporaryRedirect, logoutUrl.String())
        }
        ```

        ```golang main.go lines  theme={null}
        // Save this file in ./main.go

        package main

        import (
        	"log"
        	"net/http"

        	"github.com/joho/godotenv"

        	"01-Login/platform/authenticator"
        	"01-Login/platform/router"
        )

        func main() {
        	if err := godotenv.Load(); err != nil {
        		log.Fatalf("Failed to load the env vars: %v", err)
        	}

        	auth, err := authenticator.New()
        	if err != nil {
        		log.Fatalf("Failed to initialize the authenticator: %v", err)
        	}

        	rtr := router.New(auth)

        	log.Print("Server listening on http://localhost:3000/")
        	if err := http.ListenAndServe("0.0.0.0:3000", rtr); err != nil {
        		log.Fatalf("There was an error with the http server: %v", err)
        	}
        }
        ```

        ```golang router.go lines  theme={null}
        // Save this file in ./platform/router/router.go

        package router

        import (
        	"encoding/gob"
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-contrib/sessions/cookie"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        	"01-Login/platform/middleware"
        	"01-Login/web/app/callback"
        	"01-Login/web/app/login"
        	"01-Login/web/app/logout"
        	"01-Login/web/app/user"
        )

        // New registers the routes and returns the router.
        func New(auth *authenticator.Authenticator) *gin.Engine {
        	router := gin.Default()

        	// To store custom types in our cookies,
        	// we must first register them using gob.Register
        	gob.Register(map[string]interface{}{})

        	store := cookie.NewStore([]byte("secret"))
        	router.Use(sessions.Sessions("auth-session", store))

        	router.Static("/public", "web/static")
        	router.LoadHTMLGlob("web/template/*")

        	router.GET("/", func(ctx *gin.Context) {
        		ctx.HTML(http.StatusOK, "home.html", nil)
        	})
        	router.GET("/login", login.Handler(auth))
        	router.GET("/callback", callback.Handler(auth))
        	router.GET("/user", user.Handler)
        	router.GET("/logout", logout.Handler)

        	return router
        }
        ```

        ```golang user.go lines theme={null}
        // Save this file in ./web/app/user/user.go

        package user

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"
        )

        // Handler for our logged-in user page.
        func Handler(ctx *gin.Context) {
        	session := sessions.Default(ctx)
        	profile := session.Get("profile")

        	ctx.HTML(http.StatusOK, "user.html", profile)
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```golang main.go lines  theme={null}
        // Save this file in ./main.go

        package main

        import (
        	"log"
        	"net/http"

        	"github.com/joho/godotenv"

        	"01-Login/platform/authenticator"
        	"01-Login/platform/router"
        )

        func main() {
        	if err := godotenv.Load(); err != nil {
        		log.Fatalf("Failed to load the env vars: %v", err)
        	}

        	auth, err := authenticator.New()
        	if err != nil {
        		log.Fatalf("Failed to initialize the authenticator: %v", err)
        	}

        	rtr := router.New(auth)

        	log.Print("Server listening on http://localhost:3000/")
        	if err := http.ListenAndServe("0.0.0.0:3000", rtr); err != nil {
        		log.Fatalf("There was an error with the http server: %v", err)
        	}
        }
        ```

        ```golang auth.go lines  theme={null}
        // Save this file in ./platform/authenticator/auth.go

        package authenticator

        import (
        	"context"
        	"errors"
        	"os"

        	"github.com/coreos/go-oidc/v3/oidc"
        	"golang.org/x/oauth2"
        )

        // Authenticator is used to authenticate our users.
        type Authenticator struct {
        	*oidc.Provider
        	oauth2.Config
        }

        // New instantiates the *Authenticator.
        func New() (*Authenticator, error) {
        	provider, err := oidc.NewProvider(
        		context.Background(),
        		"https://"+os.Getenv("AUTH0_DOMAIN")+"/",
        	)
        	if err != nil {
        		return nil, err
        	}

        	conf := oauth2.Config{
        		ClientID:     os.Getenv("AUTH0_CLIENT_ID"),
        		ClientSecret: os.Getenv("AUTH0_CLIENT_SECRET"),
        		RedirectURL:  os.Getenv("AUTH0_CALLBACK_URL"),
        		Endpoint:     provider.Endpoint(),
        		Scopes:       []string{oidc.ScopeOpenID, "profile"},
        	}

        	return &Authenticator{
        		Provider: provider,
        		Config:   conf,
        	}, nil
        }

        // VerifyIDToken verifies that an *oauth2.Token is a valid *oidc.IDToken.
        func (a *Authenticator) VerifyIDToken(ctx context.Context, token *oauth2.Token) (*oidc.IDToken, error) {
        	rawIDToken, ok := token.Extra("id_token").(string)
        	if !ok {
        		return nil, errors.New("no id_token field in oauth2 token")
        	}

        	oidcConfig := &oidc.Config{
        		ClientID: a.ClientID,
        	}

        	return a.Verifier(oidcConfig).Verify(ctx, rawIDToken)
        }
        ```

        ```golang callback.go lines  theme={null}
        / Save this file in ./web/app/callback/callback.go

        package callback

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        )

        // Handler for our callback.
        func Handler(auth *authenticator.Authenticator) gin.HandlerFunc {
        	return func(ctx *gin.Context) {
        		session := sessions.Default(ctx)
        		if ctx.Query("state") != session.Get("state") {
        			ctx.String(http.StatusBadRequest, "Invalid state parameter.")
        			return
        		}

        		// Exchange an authorization code for a token.
        		token, err := auth.Exchange(ctx.Request.Context(), ctx.Query("code"))
        		if err != nil {
        			ctx.String(http.StatusUnauthorized, "Failed to exchange an authorization code for a token.")
        			return
        		}

        		idToken, err := auth.VerifyIDToken(ctx.Request.Context(), token)
        		if err != nil {
        			ctx.String(http.StatusInternalServerError, "Failed to verify ID Token.")
        			return
        		}

        		var profile map[string]interface{}
        		if err := idToken.Claims(&profile); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		session.Set("access_token", token.AccessToken)
        		session.Set("profile", profile)
        		if err := session.Save(); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		// Redirect to logged in page.
        		ctx.Redirect(http.StatusTemporaryRedirect, "/user")
        	}
        }
        ```

        ```env .env lines theme={null}
        # Save this file in ./.env

        # The URL of our Auth0 Tenant Domain.
        # If you're using a Custom Domain, be sure to set this to that value instead.
        AUTH0_DOMAIN='{yourDomain}'

        # Our Auth0 application's Client ID.
        AUTH0_CLIENT_ID='{yourClientId}'

        # Our Auth0 application's Client Secret.
        AUTH0_CLIENT_SECRET='{yourClientSecret}'

        # The Callback URL of our application.
        AUTH0_CALLBACK_URL='http://localhost:3000/callback'
        ```

        ```mod go.mod lines theme={null}
        // Save this file in ./go.mod

        module 01-Login

        go 1.21

        require (
        	github.com/coreos/go-oidc/v3 v3.8.0
        	github.com/gin-contrib/sessions v0.0.5
        	github.com/gin-gonic/gin v1.9.1
        	github.com/joho/godotenv v1.5.1
        	golang.org/x/oauth2 v0.15.0
        )
        ```

        ```golang isAuthenticated.go lines theme={null}
        // Save this file in ./platform/middleware/isAuthenticated.go

        package middleware

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"
        )

        // IsAuthenticated is a middleware that checks if
        // the user has already been authenticated previously.
        func IsAuthenticated(ctx *gin.Context) {
        	if sessions.Default(ctx).Get("profile") == nil {
        		ctx.Redirect(http.StatusSeeOther, "/")
        	} else {
        		ctx.Next()
        	}
        }
        ```

        ```golang login.go lines  theme={null}
        // Save this file in ./web/app/login/login.go

        package login

        import (
        	"crypto/rand"
        	"encoding/base64"
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        )

        // Handler for our login.
        func Handler(auth *authenticator.Authenticator) gin.HandlerFunc {
        	return func(ctx *gin.Context) {
        		state, err := generateRandomState()
        		if err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		// Save the state inside the session.
        		session := sessions.Default(ctx)
        		session.Set("state", state)
        		if err := session.Save(); err != nil {
        			ctx.String(http.StatusInternalServerError, err.Error())
        			return
        		}

        		ctx.Redirect(http.StatusTemporaryRedirect, auth.AuthCodeURL(state))
        	}
        }

        func generateRandomState() (string, error) {
        	b := make([]byte, 32)
        	_, err := rand.Read(b)
        	if err != nil {
        		return "", err
        	}

        	state := base64.StdEncoding.EncodeToString(b)

        	return state, nil
        }
        ```

        ```golang logout.go lines  theme={null}
        // Save this file in ./web/app/logout/logout.go

        package logout

        import (
        	"net/http"
        	"net/url"
        	"os"

        	"github.com/gin-gonic/gin"
        )

        // Handler for our logout.
        func Handler(ctx *gin.Context) {
        	logoutUrl, err := url.Parse("https://" + os.Getenv("AUTH0_DOMAIN") + "/v2/logout")
        	if err != nil {
        		ctx.String(http.StatusInternalServerError, err.Error())
        		return
        	}

        	scheme := "http"
        	if ctx.Request.TLS != nil {
        		scheme = "https"
        	}

        	returnTo, err := url.Parse(scheme + "://" + ctx.Request.Host)
        	if err != nil {
        		ctx.String(http.StatusInternalServerError, err.Error())
        		return
        	}

        	parameters := url.Values{}
        	parameters.Add("returnTo", returnTo.String())
        	parameters.Add("client_id", os.Getenv("AUTH0_CLIENT_ID"))
        	logoutUrl.RawQuery = parameters.Encode()

        	ctx.Redirect(http.StatusTemporaryRedirect, logoutUrl.String())
        }
        ```

        ```golang router.go lines  theme={null}
        // Save this file in ./platform/router/router.go

        package router

        import (
        	"encoding/gob"
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-contrib/sessions/cookie"
        	"github.com/gin-gonic/gin"

        	"01-Login/platform/authenticator"
        	"01-Login/platform/middleware"
        	"01-Login/web/app/callback"
        	"01-Login/web/app/login"
        	"01-Login/web/app/logout"
        	"01-Login/web/app/user"
        )

        // New registers the routes and returns the router.
        func New(auth *authenticator.Authenticator) *gin.Engine {
        	router := gin.Default()

        	// To store custom types in our cookies,
        	// we must first register them using gob.Register
        	gob.Register(map[string]interface{}{})

        	store := cookie.NewStore([]byte("secret"))
        	router.Use(sessions.Sessions("auth-session", store))

        	router.Static("/public", "web/static")
        	router.LoadHTMLGlob("web/template/*")

        	router.GET("/", func(ctx *gin.Context) {
        		ctx.HTML(http.StatusOK, "home.html", nil)
        	})
        	router.GET("/login", login.Handler(auth))
        	router.GET("/callback", callback.Handler(auth))
        	router.GET("/user", user.Handler)
        	router.GET("/logout", logout.Handler)

        	return router
        }
        ```

        ```golang user.go lines theme={null}
        // Save this file in ./web/app/user/user.go

        package user

        import (
        	"net/http"

        	"github.com/gin-contrib/sessions"
        	"github.com/gin-gonic/gin"
        )

        // Handler for our logged-in user page.
        func Handler(ctx *gin.Context) {
        	session := sessions.Default(ctx)
        	profile := session.Get("profile")

        	ctx.HTML(http.StatusOK, "user.html", profile)
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>
  </SideMenu>
</Recipe>


# Add Login to Your Hono Application
Source: https://auth0.com/docs/quickstart/webapp/hono/index

This Quickstart demonstrates how to secure your Hono applications using Auth0 authentication. Follow the steps to add login, logout, and protected routes to a Hono app.

<Callout icon="pencil">
  This Quickstart is currently in **Beta**. We'd love to hear your feedback!
</Callout>

<Note>
  **Prerequisites:**

  * **Node.js** 20 LTS or newer
  * **npm** 10+ or **yarn** 1.22+ or **pnpm** 8+
  * Optional: **[jq](https://jqlang.org/)** - for Auth0 CLI setup and **openssl** to generate secure secrets
  * Hono projects should use Hono >= 3.x (peer dependency)
</Note>

## Get Started

This quickstart shows the minimal, recommended way to secure a Hono application using `@auth0/auth0-hono`. It follows the repository's recommended patterns: environment-driven configuration, `app.use(auth(...))` middleware, and `requiresAuth()` for selective protection.

<Steps>
  <Step title="Create a new Hono application">
    Create a new Hono application using create-hono utility.

    ```shellscript theme={null}
    npm create hono@latest auth0-hono-app && cd auth0-hono-app
    ```

    Select `nodejs` template
  </Step>

  <Step title="Install dependencies">
    Install the Auth0 middleware.

    ```shellscript theme={null}
    npm install @auth0/auth0-hono
    ```

    This quickstart uses `dotenv` package to load environment variables from a `.env` file.

    To install `dotenv` locally:

    ```shellscript theme={null}
    npm install -D dotenv
    ```

    Alterantively, if you prefer not to add a dependency, you can load an env file at process start using node's `--env-file` flag, which lets you omit installing and importing `dotenv`.

    Modify the `start` script in `package.json` to:

    ```json theme={null}
      "scripts": {
        "start": "node --env-file=.env dist/index.js"
      }
    ```
  </Step>

  <Step title="Create an Auth0 application">
    Create an Auth0 Application in your Auth0 tenant (Regular Web Application) and record the **Domain**, **Client ID**, and **Client Secret** in environment variables to your project.
    You can choose to do this automatically by running a CLI command or do it manually via the Dashboard:

    <Tabs>
      <Tab title="CLI">
        Run the following shell command on your project’s root directory to create an Auth0 app and generate a `.env` file:

        <AuthCodeGroup>
          ```shellscript Mac theme={null}
          AUTH0_APP_NAME="Hono Quickstart" && brew tap auth0/auth0-cli && brew install auth0 && auth0 login --no-input && auth0 apps create -n "${AUTH0_APP_NAME}" -t regular -c http://localhost:3000/auth/callback -l http://localhost:3000 -o http://localhost:3000 --reveal-secrets --json --metadata created_by="quickstart-docs-manual" > auth0-app-details.json && CLIENT_ID=$(jq -r '.client_id' auth0-app-details.json) && CLIENT_SECRET=$(jq -r '.client_secret' auth0-app-details.json) && DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name') && SECRET=$(openssl rand -hex 32) && echo "AUTH0_DOMAIN=${DOMAIN}" > .env && echo "AUTH0_CLIENT_ID=${CLIENT_ID}" >> .env && echo "AUTH0_CLIENT_SECRET=${CLIENT_SECRET}" >> .env && echo "BASE_URL=http://localhost:3000" >> .env && echo "AUTH0_SESSION_ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env && rm auth0-app-details.json && cat .env
          ```

          ```shellscript Windows theme={null}
          $AppName = "Hono Quickstart"; winget install Auth0.CLI; auth0 login --no-input; auth0 apps create -n "$AppName" -t regular -c http://localhost:3000/callback -l http://localhost:3000 -o http://localhost:3000 --reveal-secrets --json --metadata created_by="quickstart-docs-manual" | Set-Content -Path auth0-app-details.json; $ClientId = (Get-Content -Raw auth0-app-details.json | ConvertFrom-Json).client_id; $ClientSecret = (Get-Content -Raw auth0-app-details.json | ConvertFrom-Json).client_secret; $Domain = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name; $Secret = [System.Convert]::ToHexString([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32)).ToLower(); Set-Content -Path .env -Value "AUTH0_DOMAIN=$Domain"; Add-Content -Path .env -Value "AUTH0_CLIENT_ID=$ClientId"; Add-Content -Path .env -Value "AUTH0_CLIENT_SECRET=$ClientSecret"; Add-Content -Path .env -Value "AUTH0_SECRET=$Secret"; Add-Content -Path .env -Value "BASE_URL=http://localhost:3000"; Remove-Item auth0-app-details.json; Write-Output ".env file created with your Auth0 details:"; Get-Content .env
          ```
        </AuthCodeGroup>

        Use the generated `.env` or update values manually as needed.
      </Tab>

      <Tab title="Dashboard">
        Manual steps:

        1. Go to the [Auth0 Dashboard](https://manage.auth0.com/dashboard/)
        2. Applications → Create Application → **Regular Web Application**
        3. In the app settings set:

        **Allowed Callback URLs**

        ```
        http://localhost:3000/auth/callback
        ```

        **Allowed Logout URLs**

        ```
        http://localhost:3000
        ```

        4. Create a `.env` file at your project root and populate these values:

        ```env theme={null}
        AUTH0_DOMAIN=YOUR_AUTH0_DOMAIN
        AUTH0_CLIENT_ID=YOUR_AUTH0_CLIENT_ID
        AUTH0_CLIENT_SECRET=YOUR_AUTH0_CLIENT_SECRET
        BASE_URL=http://localhost:3000
        AUTH0_SESSION_ENCRYPTION_KEY=your_32_char_min_secret
        # Optional for APIs
        AUTH0_AUDIENCE=YOUR_API_IDENTIFIER
        ```

        Note: `AUTH0_SESSION_ENCRYPTION_KEY` must be at least 32 characters. Use `openssl rand -hex 32` to generate one.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Setup Hono web server with Auth0 middleware">
    Replace the initial template in `index.ts` file with the following example.

    ```typescript theme={null}
    // index.ts
    import 'dotenv/config'; // Not required if using --env-file flag
    import { serve } from '@hono/node-server';
    import { Hono } from 'hono';
    import { auth, requiresAuth, Auth0Exception, type OIDCEnv } from '@auth0/auth0-hono';

    const app = new Hono<OIDCEnv>();

    // Configure auth middleware using environment variables.
    app.use(
      auth({
        domain: process.env.AUTH0_DOMAIN,
        clientID: process.env.AUTH0_CLIENT_ID,
        clientSecret: process.env.AUTH0_CLIENT_SECRET,
        baseURL: process.env.BASE_URL,
        authRequired: false, // Make routes public by default, protect specific routes below
        session: {
          secret: process.env.AUTH0_SESSION_ENCRYPTION_KEY,
        },
      })
    );

    // Public route
    app.get('/', (c) => c.text('Public — no login required'));

    // Make most routes public, but protect /profile/*
    app.use('/profile/*', requiresAuth());

    app.get('/profile', async (c) => {
      const session = await c.var.auth0Client?.getSession(c);
      const user = session?.user;
      return c.json({ message: 'Protected profile', user });
    });

    const port = Number(process.env.PORT) || 3000;
    serve({ fetch: app.fetch, port }, (info) => {
        console.log(`Server is running on http://localhost:${info.port}`);
      }
    );
    ```
  </Step>

  <Step title="Run your app">
    Start the server and open `http://localhost:3000`.

    ```shellscript theme={null}
    npm run dev
    ```
  </Step>
</Steps>

<Check>
  **Checkpoint**

  Your Hono app should be running on [http://localhost:3000](http://localhost:3000). The `/` route is public. Visiting `/profile` should redirect you to login (if not authenticated) and then return profile data after successful authentication.
</Check>

## Troubleshooting

<Accordion title="Common issues">
  <Accordion title="Callback or Redirect Mismatch">
    Cause: The callback URL configured in the Auth0 Dashboard does not exactly match `BASE_URL` + the callback route (e.g., `http://localhost:3000/auth/callback`).

    Fix:

    1. Verify `.env` `BASE_URL` value.
    2. Ensure Allowed Callback URLs in Auth0 Dashboard contain `http://localhost:3000/auth/callback`.
    3. Restart dev server after changes.
  </Accordion>

  <Accordion title="Session decryption / JWEDecryptionFailed">
    Cause: `AUTH0_SESSION_ENCRYPTION_KEY` is missing or too short, or you changed it while cookies from an old secret remain.

    Fix:

    * Ensure `AUTH0_SESSION_ENCRYPTION_KEY` is at least 32 characters.
    * Clear browser cookies for localhost after changing the key.
    * Restart dev server.
  </Accordion>

  <Accordion title="Routes 404 (e.g., /auth/login returns 404)">
    Cause: Middleware not installed or placed after route registration.

    Fix:

    * Ensure `app.use(auth(...))` runs before routes that depend on authentication.
    * Confirm package installed: `npm ls @auth0/auth0-hono`.
  </Accordion>

  <Accordion title="Missing environment variables in production">
    Cause: Deployment platform not providing environment variables or using different names.

    Fix:

    * Map environment variables in your hosting provider dashboard to the names used in this quickstart.
    * For Cloudflare Workers, verify session/cookie handling is compatible with the platform.
  </Accordion>
</Accordion>

## Advanced Usage

* Selective protection: use `app.use(auth({ authRequired: false }))` to make routes public by default and `app.use('/private/*', requiresAuth())` to protect specific paths.
* Silent login: use `attemptSilentLogin()` middleware to try silent authentication for better UX.
* Custom login flow: call `login({...})` to customize forwarded query params, `redirectAfterLogin`, or silent login options.
* Token management: the middleware exposes access and ID tokens via the session; follow least-privilege for scopes and rotate refresh tokens safely.

## Best Practices & Security

* Keep secrets out of source control — use environment variables.
* Use a 32+ character `AUTH0_SESSION_ENCRYPTION_KEY`.
* Set cookie `secure` to `true` in production and set appropriate `sameSite` policy.
* Limit token scopes; use audience only when requesting access tokens for APIs.
* Catch `Auth0Exception` in `app.onError` to handle auth-specific errors cleanly.

***


# Add Login to Your Java EE Application
Source: https://auth0.com/docs/quickstart/webapp/java-ee/index

Add Auth0 login, logout, and user profile to a Java EE 8 web application using the Security API

<Accordion title="AI Prompt" icon="microchip-ai">
  **Using AI to integrate Auth0?** Add this prompt to Cursor, Windsurf, Copilot, Claude Code or your favourite AI-powered IDE to speed up development.

  ```markdown expandable theme={null}
  You are integrating Auth0 into a Java EE 8 web application using the `auth0-java-mvc-common` SDK (`mvc-auth-commons`) and the Java EE 8 Security API (`HttpAuthenticationMechanism`, `IdentityStore`, CDI). The application uses Maven for builds and runs on a Java EE 8 compatible application server such as WildFly. Follow these instructions to add login, logout, and user profile functionality.
  ```
</Accordion>

<Note>
  **Prerequisites:**

  * [Java Development Kit (JDK)](https://www.oracle.com/java/technologies/downloads/) 11 or newer
  * [Apache Maven](https://maven.apache.org/download.cgi) 3.x
  * A Java EE 8 compatible application server (e.g., [WildFly](https://www.wildfly.org/) 14+, [Payara](https://www.payara.fish/) 5+, or [GlassFish](https://glassfish.org/) 5+)
  * An Auth0 account — [sign up for free](https://auth0.com/signup)
</Note>

## Get Started

Auth0 allows you to quickly add authentication and access user profile information in your application. This guide demonstrates how to integrate Auth0 with any new or existing Java EE application using the `auth0-java-mvc-common` SDK and the Java EE 8 Security API.

<Steps>
  <Step title="Create a new project">
    Generate a new Maven WAR project:

    ```shellscript theme={null}
    mvn archetype:generate \
      -DgroupId=com.auth0.example \
      -DartifactId=java-ee-auth0-app \
      -DarchetypeArtifactId=maven-archetype-webapp \
      -DinteractiveMode=false
    ```

    Navigate into the project directory:

    ```shellscript theme={null}
    cd java-ee-auth0-app
    ```

    Create the Java source directories:

    ```shellscript theme={null}
    mkdir -p src/main/java/com/auth0/example/security
    mkdir -p src/main/java/com/auth0/example/web
    mkdir -p src/main/webapp/WEB-INF/jsp
    ```
  </Step>

  <Step title="Install the Auth0 SDK">
    Replace the contents of your `pom.xml` with the following:

    ```xml pom.xml expandable lines theme={null}
    <project xmlns="http://maven.apache.org/POM/4.0.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
             http://maven.apache.org/maven-v4_0_0.xsd">
        <modelVersion>4.0.0</modelVersion>
        <groupId>com.auth0.example</groupId>
        <artifactId>java-ee-auth0-app</artifactId>
        <packaging>war</packaging>
        <version>1.0-SNAPSHOT</version>

        <properties>
            <maven.compiler.source>11</maven.compiler.source>
            <maven.compiler.target>11</maven.compiler.target>
            <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
            <failOnMissingWebXml>false</failOnMissingWebXml>
            <version.wildfly>23.0.2.Final</version.wildfly>
        </properties>

        <dependencies>
            <dependency>
                <groupId>com.auth0</groupId>
                <artifactId>mvc-auth-commons</artifactId>
                <version>[1.0, 2.0)</version>
            </dependency>
            <dependency>
                <groupId>javax</groupId>
                <artifactId>javaee-api</artifactId>
                <version>8.0.1</version>
                <scope>provided</scope>
            </dependency>
            <dependency>
                <groupId>javax.security.enterprise</groupId>
                <artifactId>javax.security.enterprise-api</artifactId>
                <version>1.0</version>
                <scope>provided</scope>
            </dependency>
            <dependency>
                <groupId>com.fasterxml.jackson.core</groupId>
                <artifactId>jackson-databind</artifactId>
                <version>2.16.0</version>
            </dependency>
        </dependencies>

        <build>
            <finalName>java-ee-auth0-app</finalName>
            <plugins>
                <plugin>
                    <groupId>org.wildfly.plugins</groupId>
                    <artifactId>wildfly-maven-plugin</artifactId>
                    <version>4.2.0.Final</version>
                    <configuration>
                        <version>${version.wildfly}</version>
                        <javaOpts>
                            <javaOpt>-Djboss.http.port=8080</javaOpt>
                        </javaOpts>
                    </configuration>
                </plugin>
            </plugins>
        </build>
    </project>
    ```

    The `javaee-api` and `javax.security.enterprise-api` dependencies are `provided` because the Java EE 8 application server supplies their implementations at runtime.
  </Step>

  <Step title="Setup your Auth0 Application">
    <Tabs>
      <Tab title="Dashboard">
        1. Go to the [Auth0 Dashboard](https://manage.auth0.com/#/applications) and navigate to **Applications > Applications > Create Application**.
        2. Enter a name for your application (e.g., "My Java EE App").
        3. Select **Regular Web Applications** as the application type.
        4. Choose **Create**.
        5. Open the **Settings** tab.
        6. Note the **Domain**, **Client ID**, and **Client Secret** values.
        7. Scroll down to **Application URIs** and set:
           * **Allowed Callback URLs**: `http://localhost:8080/callback`
           * **Allowed Logout URLs**: `http://localhost:8080/`
        8. Choose **Save Changes**.
      </Tab>
    </Tabs>

    <Info>
      Make sure to [set up connections](https://auth0.com/docs/get-started/applications/set-up-database-connections) for your application so users can log in using their preferred identity provider.
    </Info>
  </Step>

  <Step title="Configure authentication">
    Update your `web.xml` to store Auth0 configuration as JNDI environment entries. Replace the placeholder values with the **Domain**, **Client ID**, and **Client Secret** from your Auth0 Application Settings. Create a `jboss-web.xml` to configure the JASPIC security domain required by the Java EE 8 Security API, an `Auth0AuthenticationConfig.java` CDI bean to read the configuration from JNDI, and an `Auth0AuthenticationProvider.java` CDI producer to build the `AuthenticationController`.

    <Info>
      Do not include `https://` in your `auth0.domain` value. Use only the domain and region. For example: `dev-abc123.us.auth0.com`.
    </Info>

    <AuthCodeGroup>
      ```xml src/main/webapp/WEB-INF/web.xml expandable lines theme={null}
      <?xml version="1.0" encoding="UTF-8"?>
      <web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
               http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
               version="3.1">

          <env-entry>
              <env-entry-name>auth0.domain</env-entry-name>
              <env-entry-type>java.lang.String</env-entry-type>
              <env-entry-value>YOUR_AUTH0_DOMAIN</env-entry-value>
          </env-entry>
          <env-entry>
              <env-entry-name>auth0.clientId</env-entry-name>
              <env-entry-type>java.lang.String</env-entry-type>
              <env-entry-value>YOUR_CLIENT_ID</env-entry-value>
          </env-entry>
          <env-entry>
              <env-entry-name>auth0.clientSecret</env-entry-name>
              <env-entry-type>java.lang.String</env-entry-type>
              <env-entry-value>YOUR_CLIENT_SECRET</env-entry-value>
          </env-entry>
          <env-entry>
              <env-entry-name>auth0.scope</env-entry-name>
              <env-entry-type>java.lang.String</env-entry-type>
              <env-entry-value>openid profile email</env-entry-value>
          </env-entry>
      </web-app>
      ```

      ```xml src/main/webapp/WEB-INF/jboss-web.xml lines theme={null}
      <?xml version="1.0"?>
      <jboss-web>
          <security-domain>jaspitest</security-domain>
          <context-root>/</context-root>
      </jboss-web>
      ```

      ```java src/main/java/com/auth0/example/security/Auth0AuthenticationConfig.java expandable lines theme={null}
      package com.auth0.example.security;

      import javax.annotation.PostConstruct;
      import javax.enterprise.context.ApplicationScoped;
      import javax.naming.Context;
      import javax.naming.InitialContext;
      import javax.naming.NamingException;

      @ApplicationScoped
      public class Auth0AuthenticationConfig {

          private String domain;
          private String clientId;
          private String clientSecret;
          private String scope;

          @PostConstruct
          public void init() {
              try {
                  Context env = (Context) new InitialContext().lookup("java:comp/env");
                  this.domain = (String) env.lookup("auth0.domain");
                  this.clientId = (String) env.lookup("auth0.clientId");
                  this.clientSecret = (String) env.lookup("auth0.clientSecret");
                  this.scope = (String) env.lookup("auth0.scope");
              } catch (NamingException ne) {
                  throw new IllegalArgumentException(
                          "Unable to lookup auth0 configuration properties from web.xml", ne);
              }

              if (this.domain == null || this.clientId == null
                      || this.clientSecret == null || this.scope == null) {
                  throw new IllegalArgumentException(
                          "domain, clientId, clientSecret, and scope must be set in web.xml");
              }
          }

          public String getDomain() { return domain; }
          public String getClientId() { return clientId; }
          public String getClientSecret() { return clientSecret; }
          public String getScope() { return scope; }
      }
      ```

      ```java src/main/java/com/auth0/example/security/Auth0AuthenticationProvider.java expandable lines theme={null}
      package com.auth0.example.security;

      import com.auth0.AuthenticationController;
      import com.auth0.jwk.JwkProvider;
      import com.auth0.jwk.JwkProviderBuilder;

      import javax.enterprise.context.ApplicationScoped;
      import javax.enterprise.inject.Produces;

      @ApplicationScoped
      public class Auth0AuthenticationProvider {

          @Produces
          public AuthenticationController authenticationController(Auth0AuthenticationConfig config) {
              JwkProvider jwkProvider = new JwkProviderBuilder(config.getDomain()).build();
              return AuthenticationController.newBuilder(
                              config.getDomain(), config.getClientId(), config.getClientSecret())
                      .withJwkProvider(jwkProvider)
                      .build();
          }
      }
      ```
    </AuthCodeGroup>
  </Step>

  <Step title="Implement Java EE Security">
    The Java EE 8 Security API uses `HttpAuthenticationMechanism` to handle authentication. You need to provide custom implementations of several security interfaces. The `@AutoApplySession` annotation enables the container to create a session for the authenticated user, so they remain logged in across requests.

    <AuthCodeGroup>
      ```java src/main/java/com/auth0/example/security/Auth0JwtPrincipal.java expandable lines theme={null}
      package com.auth0.example.security;

      import com.auth0.jwt.interfaces.DecodedJWT;

      import javax.security.enterprise.CallerPrincipal;

      public class Auth0JwtPrincipal extends CallerPrincipal {

          private final DecodedJWT idToken;

          Auth0JwtPrincipal(DecodedJWT idToken) {
              super(idToken.getClaim("name").asString());
              this.idToken = idToken;
          }

          public DecodedJWT getIdToken() {
              return this.idToken;
          }
      }
      ```

      ```java src/main/java/com/auth0/example/security/Auth0JwtCredential.java expandable lines theme={null}
      package com.auth0.example.security;

      import com.auth0.jwt.JWT;
      import com.auth0.jwt.interfaces.DecodedJWT;

      import javax.security.enterprise.credential.Credential;

      class Auth0JwtCredential implements Credential {

          private Auth0JwtPrincipal auth0JwtPrincipal;

          Auth0JwtCredential(String token) {
              DecodedJWT decodedJWT = JWT.decode(token);
              this.auth0JwtPrincipal = new Auth0JwtPrincipal(decodedJWT);
          }

          Auth0JwtPrincipal getAuth0JwtPrincipal() {
              return auth0JwtPrincipal;
          }
      }
      ```

      ```java src/main/java/com/auth0/example/security/Auth0JwtIdentityStore.java expandable lines theme={null}
      package com.auth0.example.security;

      import javax.enterprise.context.ApplicationScoped;
      import javax.security.enterprise.credential.Credential;
      import javax.security.enterprise.identitystore.CredentialValidationResult;
      import javax.security.enterprise.identitystore.IdentityStore;

      @ApplicationScoped
      public class Auth0JwtIdentityStore implements IdentityStore {

          @Override
          public CredentialValidationResult validate(final Credential credential) {
              CredentialValidationResult result = CredentialValidationResult.NOT_VALIDATED_RESULT;

              if (credential instanceof Auth0JwtCredential) {
                  Auth0JwtCredential auth0JwtCredential = (Auth0JwtCredential) credential;
                  result = new CredentialValidationResult(auth0JwtCredential.getAuth0JwtPrincipal());
              }

              return result;
          }
      }
      ```

      ```java src/main/java/com/auth0/example/security/Auth0AuthenticationMechanism.java expandable lines theme={null}
      package com.auth0.example.security;

      import com.auth0.AuthenticationController;
      import com.auth0.IdentityVerificationException;
      import com.auth0.Tokens;

      import javax.enterprise.context.ApplicationScoped;
      import javax.inject.Inject;
      import javax.security.enterprise.AuthenticationException;
      import javax.security.enterprise.AuthenticationStatus;
      import javax.security.enterprise.authentication.mechanism.http.AutoApplySession;
      import javax.security.enterprise.authentication.mechanism.http.HttpAuthenticationMechanism;
      import javax.security.enterprise.authentication.mechanism.http.HttpMessageContext;
      import javax.security.enterprise.identitystore.CredentialValidationResult;
      import javax.security.enterprise.identitystore.IdentityStoreHandler;
      import javax.servlet.http.HttpServletRequest;
      import javax.servlet.http.HttpServletResponse;

      @ApplicationScoped
      @AutoApplySession
      public class Auth0AuthenticationMechanism implements HttpAuthenticationMechanism {

          private final AuthenticationController authenticationController;
          private final IdentityStoreHandler identityStoreHandler;

          @Inject
          Auth0AuthenticationMechanism(AuthenticationController authenticationController,
                                       IdentityStoreHandler identityStoreHandler) {
              this.authenticationController = authenticationController;
              this.identityStoreHandler = identityStoreHandler;
          }

          @Override
          public AuthenticationStatus validateRequest(HttpServletRequest httpServletRequest,
                                                      HttpServletResponse httpServletResponse,
                                                      HttpMessageContext httpMessageContext)
                  throws AuthenticationException {

              if (isCallbackRequest(httpServletRequest)) {
                  try {
                      Tokens tokens = authenticationController.handle(
                              httpServletRequest, httpServletResponse);
                      Auth0JwtCredential auth0JwtCredential =
                              new Auth0JwtCredential(tokens.getIdToken());
                      CredentialValidationResult result =
                              identityStoreHandler.validate(auth0JwtCredential);
                      return httpMessageContext.notifyContainerAboutLogin(result);
                  } catch (IdentityVerificationException e) {
                      return httpMessageContext.responseUnauthorized();
                  }
              }

              return httpMessageContext.doNothing();
          }

          private boolean isCallbackRequest(HttpServletRequest request) {
              return request.getServletPath().equals("/callback")
                      && request.getParameter("code") != null;
          }
      }
      ```
    </AuthCodeGroup>
  </Step>

  <Step title="Add login and logout functionality">
    Create the servlets for login, callback, and logout. The `LoginServlet` builds the Auth0 authorization URL and redirects the user. The `CallbackServlet` handles the redirect after authentication — the `Auth0AuthenticationMechanism` intercepts this request first to exchange the authorization code for tokens, so the servlet only needs to redirect. The `LogoutServlet` clears the session and redirects to the Auth0 logout endpoint.

    <AuthCodeGroup>
      ```java src/main/java/com/auth0/example/web/LoginServlet.java expandable lines theme={null}
      package com.auth0.example.web;

      import com.auth0.AuthenticationController;
      import com.auth0.example.security.Auth0AuthenticationConfig;

      import javax.inject.Inject;
      import javax.servlet.ServletException;
      import javax.servlet.annotation.WebServlet;
      import javax.servlet.http.HttpServlet;
      import javax.servlet.http.HttpServletRequest;
      import javax.servlet.http.HttpServletResponse;
      import java.io.IOException;

      @WebServlet(urlPatterns = "/login")
      public class LoginServlet extends HttpServlet {

          private final Auth0AuthenticationConfig config;
          private final AuthenticationController authenticationController;

          @Inject
          LoginServlet(Auth0AuthenticationConfig config,
                       AuthenticationController authenticationController) {
              this.config = config;
              this.authenticationController = authenticationController;
          }

          @Override
          public void doGet(HttpServletRequest request, HttpServletResponse response)
                  throws ServletException, IOException {
              String callbackUrl = String.format(
                      "%s://%s:%s%s/callback",
                      request.getScheme(),
                      request.getServerName(),
                      request.getServerPort(),
                      request.getContextPath());

              String authURL = authenticationController
                      .buildAuthorizeUrl(request, response, callbackUrl)
                      .withScope(config.getScope())
                      .build();

              response.sendRedirect(authURL);
          }
      }
      ```

      ```java src/main/java/com/auth0/example/web/CallbackServlet.java expandable lines theme={null}
      package com.auth0.example.web;

      import javax.servlet.annotation.WebServlet;
      import javax.servlet.http.HttpServlet;
      import javax.servlet.http.HttpServletRequest;
      import javax.servlet.http.HttpServletResponse;
      import java.io.IOException;

      @WebServlet(urlPatterns = {"/callback"})
      public class CallbackServlet extends HttpServlet {

          @Override
          public void doGet(HttpServletRequest request, HttpServletResponse response)
                  throws IOException {
              response.sendRedirect(request.getContextPath() + "/");
          }
      }
      ```

      ```java src/main/java/com/auth0/example/web/LogoutServlet.java expandable lines theme={null}
      package com.auth0.example.web;

      import com.auth0.example.security.Auth0AuthenticationConfig;

      import javax.inject.Inject;
      import javax.servlet.ServletException;
      import javax.servlet.annotation.WebServlet;
      import javax.servlet.http.HttpServlet;
      import javax.servlet.http.HttpServletRequest;
      import javax.servlet.http.HttpServletResponse;
      import java.io.IOException;
      import java.net.URLEncoder;

      @WebServlet(urlPatterns = "/logout")
      public class LogoutServlet extends HttpServlet {

          private final Auth0AuthenticationConfig config;

          @Inject
          LogoutServlet(Auth0AuthenticationConfig config) {
              this.config = config;
          }

          @Override
          protected void doGet(final HttpServletRequest request,
                               final HttpServletResponse response)
                  throws ServletException, IOException {
              if (request.getSession() != null) {
                  request.getSession().invalidate();
              }

              String returnUrl = String.format("%s://%s",
                      request.getScheme(), request.getServerName());
              int port = request.getServerPort();
              String scheme = request.getScheme();

              if (("http".equals(scheme) && port != 80)
                      || ("https".equals(scheme) && port != 443)) {
                  returnUrl += ":" + port;
              }

              returnUrl += request.getContextPath() + "/";

              String logoutUrl = String.format(
                      "https://%s/v2/logout?client_id=%s&returnTo=%s",
                      config.getDomain(),
                      config.getClientId(),
                      URLEncoder.encode(returnUrl, "UTF-8"));

              response.sendRedirect(logoutUrl);
          }
      }
      ```
    </AuthCodeGroup>
  </Step>

  <Step title="Create the user interface">
    Create the servlets and JSP pages for the home and profile views. The `HomeServlet` checks for an authenticated principal and sets the profile claims on the request. The `ProfileServlet` displays the user's profile and JWT claims, or redirects to login if not authenticated.

    <AuthCodeGroup>
      ```java src/main/java/com/auth0/example/web/HomeServlet.java expandable lines theme={null}
      package com.auth0.example.web;

      import com.auth0.example.security.Auth0JwtPrincipal;

      import javax.servlet.ServletException;
      import javax.servlet.annotation.WebServlet;
      import javax.servlet.http.HttpServlet;
      import javax.servlet.http.HttpServletRequest;
      import javax.servlet.http.HttpServletResponse;
      import java.io.IOException;
      import java.security.Principal;

      @WebServlet(urlPatterns = "")
      public class HomeServlet extends HttpServlet {

          @Override
          public void doGet(HttpServletRequest request, HttpServletResponse response)
                  throws ServletException, IOException {
              Principal principal = request.getUserPrincipal();

              if (principal instanceof Auth0JwtPrincipal) {
                  Auth0JwtPrincipal auth0JwtPrincipal = (Auth0JwtPrincipal) principal;
                  request.setAttribute("profile", auth0JwtPrincipal.getIdToken().getClaims());
              }

              request.getRequestDispatcher("/WEB-INF/jsp/home.jsp").forward(request, response);
          }
      }
      ```

      ```java src/main/java/com/auth0/example/web/ProfileServlet.java expandable lines theme={null}
      package com.auth0.example.web;

      import com.auth0.example.security.Auth0JwtPrincipal;
      import com.auth0.jwt.interfaces.DecodedJWT;
      import com.fasterxml.jackson.databind.ObjectMapper;

      import javax.servlet.ServletException;
      import javax.servlet.annotation.WebServlet;
      import javax.servlet.http.HttpServlet;
      import javax.servlet.http.HttpServletRequest;
      import javax.servlet.http.HttpServletResponse;
      import java.io.IOException;
      import java.nio.charset.StandardCharsets;
      import java.security.Principal;
      import java.util.Base64;

      @WebServlet(urlPatterns = {"/profile"})
      public class ProfileServlet extends HttpServlet {

          @Override
          public void doGet(HttpServletRequest request, HttpServletResponse response)
                  throws ServletException, IOException {
              Principal principal = request.getUserPrincipal();

              if (principal instanceof Auth0JwtPrincipal) {
                  Auth0JwtPrincipal auth0JwtPrincipal = (Auth0JwtPrincipal) principal;
                  request.setAttribute("profile", auth0JwtPrincipal.getIdToken().getClaims());

                  String profileJson;
                  try {
                      DecodedJWT idToken = auth0JwtPrincipal.getIdToken();
                      byte[] decodedBytes = Base64.getUrlDecoder().decode(idToken.getPayload());
                      String decoded = new String(decodedBytes, StandardCharsets.UTF_8);
                      ObjectMapper objectMapper = new ObjectMapper();
                      Object json = objectMapper.readValue(decoded, Object.class);
                      profileJson = objectMapper.writerWithDefaultPrettyPrinter().writeValueAsString(json);
                  } catch (IOException ioe) {
                      profileJson = "Error converting JWT claims to JSON";
                  }

                  request.setAttribute("profileJson", profileJson);
                  request.getRequestDispatcher("/WEB-INF/jsp/profile.jsp").forward(request, response);
              } else {
                  request.getSession().setAttribute("Referer", request.getRequestURI());
                  request.getRequestDispatcher("/login").forward(request, response);
              }
          }
      }
      ```

      ```html src/main/webapp/WEB-INF/jsp/home.jsp expandable lines theme={null}
      <%@ page contentType="text/html;charset=UTF-8" %>
      <%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
      <!DOCTYPE html>
      <html>
      <head>
          <meta charset="UTF-8">
          <title>Java EE Auth0 App</title>
          <style>
              body { font-family: sans-serif; max-width: 800px; margin: 40px auto; padding: 0 20px; }
              nav { display: flex; justify-content: flex-end; gap: 12px; margin-bottom: 40px; align-items: center; }
              nav a { text-decoration: none; padding: 8px 16px; border-radius: 4px; }
              .btn-login { background: #635dff; color: white; }
              .btn-logout { background: #e0e0e0; color: #333; }
              nav img { border-radius: 50%; width: 36px; height: 36px; }
          </style>
      </head>
      <body>
          <nav>
              <c:choose>
                  <c:when test="${not empty profile}">
                      <a href="${pageContext.request.contextPath}/profile">Profile</a>
                      <img src="${profile.get('picture').asString()}" alt="Profile picture"/>
                      <a href="${pageContext.request.contextPath}/logout" class="btn-logout">Logout</a>
                  </c:when>
                  <c:otherwise>
                      <a href="${pageContext.request.contextPath}/login" class="btn-login">Login</a>
                  </c:otherwise>
              </c:choose>
          </nav>

          <h1>Java EE Sample Project</h1>
          <p>This is a sample application that demonstrates an authentication flow for a web application using Java EE.</p>
      </body>
      </html>
      ```

      ```html src/main/webapp/WEB-INF/jsp/profile.jsp expandable lines theme={null}
      <%@ page contentType="text/html;charset=UTF-8" %>
      <%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
      <!DOCTYPE html>
      <html>
      <head>
          <meta charset="UTF-8">
          <title>Profile - Java EE Auth0 App</title>
          <style>
              body { font-family: sans-serif; max-width: 800px; margin: 40px auto; padding: 0 20px; }
              nav { display: flex; justify-content: flex-end; gap: 12px; margin-bottom: 40px; align-items: center; }
              nav a { text-decoration: none; padding: 8px 16px; border-radius: 4px; }
              .btn-logout { background: #e0e0e0; color: #333; }
              .profile-header { display: flex; align-items: center; gap: 20px; margin-bottom: 30px; }
              .profile-header img { border-radius: 50%; width: 80px; height: 80px; }
              .profile-header h2 { margin: 0 0 4px; }
              .profile-header p { margin: 0; color: #666; }
              pre { background: #f5f5f5; padding: 15px; border-radius: 5px; overflow-x: auto; }
          </style>
      </head>
      <body>
          <nav>
              <a href="${pageContext.request.contextPath}/">Home</a>
              <a href="${pageContext.request.contextPath}/logout" class="btn-logout">Logout</a>
          </nav>

          <div class="profile-header">
              <img src="${profile.get('picture').asString()}" alt="Profile picture"/>
              <div>
                  <h2>${profile.get('name').asString()}</h2>
                  <p>${profile.get('email').asString()}</p>
              </div>
          </div>

          <h3>Profile Details</h3>
          <pre><code>${profileJson}</code></pre>
      </body>
      </html>
      ```
    </AuthCodeGroup>
  </Step>

  <Step title="Run your application">
    Build and run the application using the WildFly Maven plugin:

    ```shellscript theme={null}
    mvn clean wildfly:run
    ```

    Your application should start and display the URL it's listening on:

    ```
    INFO  [org.jboss.as] WFLYSRV0025: WildFly started
    ```

    Open your browser to [http://localhost:8080](http://localhost:8080). Click the **Login** link in the navigation bar. You will be redirected to the Auth0 login page. After authenticating, you will be redirected to the [profile page](http://localhost:8080/profile) where your user information and JWT claims are displayed.

    <Info>
      The sample uses JSP and is tested with the [WildFly](https://wildfly.org/) application server. You may need to adjust some steps if you are using a different Java EE 8 compatible container.
    </Info>
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a fully functional Auth0-protected Java EE application running on [http://localhost:8080](http://localhost:8080). Users can log in, view their profile, and log out.
</Check>

***

## Advanced Usage

<Accordion title="Access User Profile Information">
  The `Auth0JwtPrincipal` is available via `request.getUserPrincipal()` in any servlet. The `ProfileServlet` demonstrates how to access the decoded ID token claims:

  ```java theme={null}
  Principal principal = request.getUserPrincipal();

  if (principal instanceof Auth0JwtPrincipal) {
      Auth0JwtPrincipal auth0JwtPrincipal = (Auth0JwtPrincipal) principal;
      DecodedJWT idToken = auth0JwtPrincipal.getIdToken();

      String name = idToken.getClaim("name").asString();
      String email = idToken.getClaim("email").asString();
      String picture = idToken.getClaim("picture").asString();
      String sub = idToken.getSubject();
  }
  ```

  Common claims available in the ID token:

  * `name` — user's full display name
  * `email` — user's email address
  * `picture` — URL to the user's profile picture
  * `sub` — unique identifier for the user (Auth0 user ID)
</Accordion>

<Accordion title="Customize Login Parameters">
  Add custom parameters to the authorization URL when building it in your `LoginServlet`:

  ```java src/main/java/com/auth0/example/web/LoginServlet.java theme={null}
  String authURL = authenticationController
          .buildAuthorizeUrl(request, response, callbackUrl)
          .withScope(config.getScope())
          .withAudience("https://your-api.example.com")
          .withParameter("screen_hint", "signup")
          .withParameter("ui_locales", "fr")
          .build();
  ```

  Use `.withAudience()` to request an access token for a specific API. Use `.withParameter()` for any additional [authorization parameters](https://auth0.com/docs/api/authentication#authorize-application) supported by Auth0.
</Accordion>

<Accordion title="Store Tokens for API Calls">
  To access the raw tokens for API calls, modify the `Auth0AuthenticationMechanism` to store tokens in the session:

  ```java src/main/java/com/auth0/example/security/Auth0AuthenticationMechanism.java theme={null}
  if (isCallbackRequest(httpServletRequest)) {
      try {
          Tokens tokens = authenticationController.handle(
                  httpServletRequest, httpServletResponse);

          httpServletRequest.getSession().setAttribute(
                  "accessToken", tokens.getAccessToken());

          Auth0JwtCredential auth0JwtCredential =
                  new Auth0JwtCredential(tokens.getIdToken());
          CredentialValidationResult result =
                  identityStoreHandler.validate(auth0JwtCredential);
          return httpMessageContext.notifyContainerAboutLogin(result);
      } catch (IdentityVerificationException e) {
          return httpMessageContext.responseUnauthorized();
      }
  }
  ```

  Then retrieve the access token when calling a protected API:

  ```java theme={null}
  String accessToken = (String) request.getSession().getAttribute("accessToken");
  URL url = new URL("https://your-api.example.com/data");
  HttpURLConnection conn = (HttpURLConnection) url.openConnection();
  conn.setRequestProperty("Authorization", "Bearer " + accessToken);
  ```
</Accordion>

<Accordion title="Log In to an Organization">
  Configure the `AuthenticationController` with an organization ID or name to restrict login to a specific [Auth0 Organization](https://auth0.com/docs/organizations):

  ```java src/main/java/com/auth0/example/security/Auth0AuthenticationProvider.java theme={null}
  @Produces
  public AuthenticationController authenticationController(Auth0AuthenticationConfig config) {
      JwkProvider jwkProvider = new JwkProviderBuilder(config.getDomain()).build();
      return AuthenticationController.newBuilder(
                      config.getDomain(), config.getClientId(), config.getClientSecret())
              .withJwkProvider(jwkProvider)
              .withOrganization("org_YOUR_ORG_ID")
              .build();
  }
  ```

  The SDK automatically validates the `org_id` or `org_name` claim in the ID token to ensure it matches the configured organization.
</Accordion>

***

## Additional Resources

<CardGroup>
  <Card title="Auth0 Java MVC SDK" icon="github" href="https://github.com/auth0/auth0-java-mvc-common">
    Source code and issue tracker
  </Card>

  <Card title="API Reference (JavaDoc)" icon="code" href="https://javadoc.io/doc/com.auth0/mvc-auth-commons">
    Detailed API documentation
  </Card>

  <Card title="Community Forum" icon="comments" href="https://community.auth0.com/">
    Get help from the Auth0 community
  </Card>

  <Card title="Java EE Sample App" icon="github" href="https://github.com/auth0-samples/auth0-java-ee-sample/tree/master/01-Login">
    Complete sample application on GitHub
  </Card>
</CardGroup>

***

## Common Issues

<AccordionGroup>
  <Accordion title="State mismatch error on callback">
    If you receive an `a0.invalid_state` error after login, the state cookie was not found or does not match the state returned from Auth0.

    Verify that:

    * Your callback URL in the Auth0 Dashboard exactly matches the URL your application constructs, including the port number and protocol.
    * Your browser is not blocking third-party cookies.
    * No reverse proxy or middleware is stripping `Set-Cookie` headers from responses.

    Ensure you are using the three-argument version of both `buildAuthorizeUrl` and `handle`, which uses cookie-based state storage:

    ```java theme={null}
    // Correct — uses cookies for state
    authenticationController.buildAuthorizeUrl(request, response, callbackUrl)
    authenticationController.handle(httpServletRequest, httpServletResponse)
    ```
  </Accordion>

  <Accordion title="CDI beans not discovered">
    If you see errors about injection failures or beans not being found, ensure that:

    * Your application server supports CDI 2.0 (part of Java EE 8)
    * All security classes (`Auth0AuthenticationConfig`, `Auth0AuthenticationProvider`, `Auth0JwtIdentityStore`, `Auth0AuthenticationMechanism`) are annotated with `@ApplicationScoped`
    * `src/main/webapp/WEB-INF/jboss-web.xml` exists with the `jaspitest` security domain configured

    ```xml src/main/webapp/WEB-INF/jboss-web.xml theme={null}
    <jboss-web>
        <security-domain>jaspitest</security-domain>
        <context-root>/</context-root>
    </jboss-web>
    ```

    The `jaspitest` security domain is required for WildFly to enable the JASPIC (Java Authentication SPI for Containers) integration that the Java EE 8 Security API depends on.
  </Accordion>

  <Accordion title="Application server compatibility">
    This quickstart uses the `javax` namespace (Java EE 8). If you are using a server that has migrated to the `jakarta` namespace (Jakarta EE 9+), such as WildFly 27+ or Payara 6+, the code will not compile or run.

    Use a Java EE 8 compatible server:

    * WildFly 14 through 26
    * Payara 5
    * GlassFish 5
    * Open Liberty with Java EE 8 features
  </Accordion>
</AccordionGroup>

***

## Sample Application

A sample Java EE application integrated with Auth0 is available on GitHub:

<Card title="Java EE Sample Application" icon="github" href="https://github.com/auth0-samples/auth0-java-ee-sample/tree/master/01-Login">
  Includes login, logout, user profile, and other examples.
</Card>

Clone and run:

```bash theme={null}
git clone https://github.com/auth0-samples/auth0-java-ee-sample.git
cd auth0-java-ee-sample/01-Login
```

Update the Auth0 configuration values in `src/main/webapp/WEB-INF/web.xml`, then run:

```bash theme={null}
./mvnw clean wildfly:run
```

Point your browser to [http://localhost:8080](http://localhost:8080) and click **Login** to test.

***


# Add Login to your Spring Web Application
Source: https://auth0.com/docs/quickstart/webapp/java-spring-boot/interactive

This guide demonstrates how to integrate Auth0 with a Spring Boot application using the Auth0 Spring Boot SDK.

<QuickstartButtons />

<Recipe>
  <Content>
    <Info>
      This tutorial uses [Spring MVC](https://docs.spring.io/spring/docs/current/spring-framework-reference/web.html). If you are using [Spring WebFlux](https://docs.spring.io/spring/docs/current/spring-framework-reference/web-reactive.html#spring-web-reactive), the steps to add authentication are
      similar, but some implementation details are different. Refer to the [Spring Boot WebFlux Sample Code](https://github.com/auth0-samples/auth0-spring-boot-login-samples/tree/master/webflux-login) to see how to integrate
      Auth0 with your Spring Boot WebFlux application.
    </Info>

    <Section title={sections[0].title}>
      To use Auth0 services, you’ll need to have an application set up in the Auth0 Dashboard. The Auth0 application is
      where you will configure how you want authentication to work for the project you are developing.

      ### Configure an application

      Use the interactive selector to create a new Auth0 application or select an existing application that represents
      the project you want to integrate with. Every application in Auth0 is assigned an alphanumeric, unique client ID
      that your application code will use to call Auth0 APIs through the SDK.

      Any settings you configure using this quickstart will automatically update for your Application in the [Dashboard](https://manage.auth0.com/#/), which is where you
      can manage your Applications in the future.

      If you would rather explore a complete configuration, you can view a sample application instead.

      ### Configure Callback URLs

      A callback URL is a URL in your application that you would like Auth0 to redirect users to after they have
      authenticated. If not set, users will not be returned to your application after they log in.

      <Info>
        If you are following along with our sample project, set this to

        `http://localhost:3000/login/oauth2/code/okta`.
      </Info>

      ### Configure Logout URLs

      A logout URL is a URL in your application that you would like Auth0 to redirect users to after they have logged
      out. If not set, users will not be able to log out from your application and will receive an error.

      <Info>
        If you are following along with our sample project, set this to

        `http://localhost:3000`.
      </Info>
    </Section>

    <Section title={sections[1].title}>
      ### Add Spring dependencies

      To integrate your Spring Boot application with Auth0, include the [Okta Spring Boot
      Starter](https://github.com/okta/okta-spring-boot/) in your application's dependencies.

      <Info>
        This guide uses [Thymeleaf](https://www.thymeleaf.org/) and the [Spring Security integration module](https://github.com/thymeleaf/thymeleaf-extras-springsecurity) for the view layer. If you are using
        a different view technology, the Spring Security configuration and components remain the same.
      </Info>

      If you're using Gradle, you can include these dependencies as shown below.

      ```text lines theme={null}
      plugins {
        id 'java'
        id 'org.springframework.boot' version '3.1.4'
        id 'io.spring.dependency-management' version '1.1.3'
      }
      implementation 'com.okta.spring:okta-spring-boot-starter:3.0.5'
      implementation 'org.springframework.boot:spring-boot-starter-web'
      implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
      implementation 'org.thymeleaf.extras:thymeleaf-extras-springsecurity6'
      implementation 'nz.net.ultraq.thymeleaf:thymeleaf-layout-dialect'
      ```

      If you are using Maven:

      ```xml lines expandable theme={null}
      <parent>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-parent</artifactId>
      <version>3.1.4</version>
      <relativePath/>
      </parent>
      <dependencies>
      <dependency>
      <groupId>com.okta</groupId>
      <artifactId>okta-spring-boot-starter</artifactId>
      <version>3.0.5</version>
      </dependency>
      <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
      </dependency>
      <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-oauth2-client</artifactId>
      </dependency>
      <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-thymeleaf</artifactId>
      </dependency>
      <dependency>
      <groupId>org.thymeleaf.extras</groupId>
      <artifactId>thymeleaf-extras-springsecurity6</artifactId>
      </dependency>
      <dependency>
      <groupId>nz.net.ultraq.thymeleaf</groupId>
      <artifactId>thymeleaf-layout-dialect</artifactId>
      </dependency>
      </dependencies>
      ```
    </Section>

    <Section title={sections[2].title}>
      The Okta Spring Boot Starter makes it easy to configure your application with Auth0. The sample below uses an
      `application.yml` file, though you can also use properties files or any of the other [supported externalization mechanisms](https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#boot-features-external-config).

      ```yml lines theme={null}
      #src/main/resources/application.yml
      okta:
      oauth2:
      issuer: https://{yourDomain}/

      client-id: {yourClientId}

      client-secret: {yourClientSecret}

      #The sample and instructions above for the callback and logout URL configuration use port 3000.
      #If you wish to use a different port, change this and be sure your callback and logout URLs are
      #configured with the correct port.
      server:
      port: 3000
      ```
    </Section>

    <Section title={sections[3].title}>
      To enable user login with Auth0, create a class that will register a [SecurityFilterChain](https://docs.spring.io/spring-security/site/docs/current/api/org/springframework/security/web/SecurityFilterChain.html), and add the `@Configuration`
      annotation.

      <Info>
        You can configure the [HttpSecurity](https://docs.spring.io/spring-security/site/docs/current/api/org/springframework/security/config/annotation/web/builders/HttpSecurity.html) instance to require authentication on all
        or certain paths. For example, to require authentication on all paths except the home page:
      </Info>

      ```java lines theme={null}
      http.authorizeHttpRequests(authorize -> authorize
          .requestMatchers(&quot;/&quot;).permitAll()

          .anyRequest().authenticated()

      );
      ```
    </Section>

    <Section title={sections[4].title}>
      The Okta Spring Boot Starter will use the client configuration you defined earlier to handle login when a user
      visits the `/oauth2/authorization/okta` path of your application. You can use this to create a login
      link in your application.

      This page returns the user attributes when the user authentications. You will use the `/logout` link
      in the template to implement the logout feature.
    </Section>

    <Section title={sections[5].title}>
      Create a controller to handle the incoming request. This controller renders the `index.html` page.
      When the user authenticates, the application retrieves the users's profile information attributes to render the
      page.

      <Info>
        ##### Checkpoint

        When you click the login link, verify the application redirects you to the [Auth0 Universal Login](https://auth0.com/universal-login) page and that you can
        now log in or sign up using a username and password or a social provider.
      </Info>

      <Info>
        Auth0 enables the Google social provider by default on new tenants and offers you developer keys to
        test logging in with [social identity providers](https://auth0.com/docs/connections/identity-providers-social). However, these developer keys have some limitations
        that may cause your application to behave differently. For more details on what this behavior may look
        like and how to fix it, consult the [Test Social Connections with Auth0 Developer Keys](https://auth0.com/docs/connections/social/devkeys#limitations-of-developer-keys) document.
      </Info>
    </Section>

    <Section title={sections[6].title}>
      Now that users can log into your application, they need [a way to log out](https://auth0.com/docs/logout/guides/logout-auth0). By default, when
      logout is enabled, Spring Security will log the user out of your application and clear the session. To enable
      successful logout of Auth0, you can provide a `LogoutHandler` to redirect users to your [Auth0 logout endpoint](https://auth0.com/docs/api/authentication?javascript#logout)
      (`https://{yourDomain}/v2/logout`) and then immediately redirect them to your application.

      In the `SecurityConfig` class, provide a `LogoutHandler` that redirects to the Auth0 logout
      endpoint, and configure the `HttpSecurity` to add the logout handler

      <Info>
        ##### Checkpoint

        When you click logout link, the application should redirect you to the address you specified as one of
        the "Allowed Logout URLs" in the "Settings" and you are no longer logged in to your application.
      </Info>
    </Section>

    ## Next Steps

    Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.

    This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:

    * [Auth0 Dashboard](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq) - Learn how to configure and manage your Auth0 tenant and applications
    * [Okta Spring Boot Starter SDK](https://github.com/okta/okta-spring-boot/) - Explore the SDK used in this tutorial more fully
    * [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
  </Content>

  <SideMenu>
    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```yml application.yml lines theme={null}
        okta:
          oauth2:
            issuer: https://{yourDomain}/
            client-id: {yourClientId}
            client-secret: {yourClientSecret}
        ```

        ```java SecurityConfig.java lines theme={null}
        package com.auth0.example;

        import org.springframework.context.annotation.Bean;
        import org.springframework.context.annotation.Configuration;
        import org.springframework.security.config.annotation.web.builders.HttpSecurity;
        import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
        import org.springframework.security.web.SecurityFilterChain;

        import static org.springframework.security.config.Customizer.withDefaults;

        @Configuration
        @EnableWebSecurity
        public class SecurityConfig {

            @Bean
            public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
                 http
                    .authorizeHttpRequests(authorize -> authorize
                        .anyRequest().authenticated()
                    )
                    .oauth2Login(withDefaults());
                return http.build();
            }
        }
        ```

        ```html index.html lines theme={null}
        <!-- src/main/resources/templates/index.html -->
        <html lang="en" xmlns:th="http://www.thymeleaf.org" xmlns:sec="http://www.thymeleaf.org/thymeleaf-extras-springsecurity5">
            <body>
                <div sec:authorize="!isAuthenticated()">
                    <a th:href="@{/oauth2/authorization/okta}">Log In</a>
                </div>
                <div sec:authorize="isAuthenticated()">
                    <p>You are logged in!</p>
                    <img th:src="${profile.get('picture')}" th:attr="alt=${profile.get('name')}"/>
                    <h2 th:text="${profile.get('name')}"></h2>
                    <p th:text="${profile.get('email')}"></p>
                    <form name="logoutForm" th:action="@{/logout}" method="post">
                        <button type="submit" value="Log out"/>
                    </form>
                </div>
            </body>
        </html>
        ```

        ```java HomeController.java lines theme={null}
        package com.auth0.example;

        import org.springframework.security.core.annotation.AuthenticationPrincipal;
        import org.springframework.security.oauth2.core.oidc.user.OidcUser;
        import org.springframework.stereotype.Controller;
        import org.springframework.ui.Model;
        import org.springframework.web.bind.annotation.GetMapping;

        /**
         * Controller for the home page.
         */
        @Controller
        public class HomeController {

            @GetMapping("/")
            public String home(Model model, @AuthenticationPrincipal OidcUser principal) {
                if (principal != null) {
                    model.addAttribute("profile", principal.getClaims());
                }
                return "index";
            }
        }
        ```

        ```java SecurityConfigWithLogout.java lines theme={null}
        package com.auth0.example;

        import org.springframework.beans.factory.annotation.Value;
        import org.springframework.context.annotation.Bean;
        import org.springframework.context.annotation.Configuration;
        import org.springframework.security.config.annotation.web.builders.HttpSecurity;
        import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
        import org.springframework.security.web.SecurityFilterChain;
        import org.springframework.security.web.authentication.logout.LogoutHandler;
        import org.springframework.web.servlet.support.ServletUriComponentsBuilder;

        import java.io.IOException;

        import static org.springframework.security.config.Customizer.withDefaults;

        @Configuration
        @EnableWebSecurity
        public class SecurityConfig {

            @Value("${okta.oauth2.issuer}")
            private String issuer;
            @Value("${okta.oauth2.client-id}")
            private String clientId;

            @Bean
            public SecurityFilterChain configure(HttpSecurity http) throws Exception {
                http
                    .authorizeHttpRequests(authorize -> authorize
                        .requestMatchers("/", "/images/**").permitAll()
                        .anyRequest().authenticated()
                    )
                    .oauth2Login(withDefaults())
                    .logout(logout -> logout
                        .addLogoutHandler(logoutHandler()));
                return http.build();
            }

            private LogoutHandler logoutHandler() {
                return (request, response, authentication) -> {
                    try {
                        String baseUrl = ServletUriComponentsBuilder.fromCurrentContextPath().build().toUriString();
                        response.sendRedirect(issuer + "v2/logout?client_id=" + clientId + "&returnTo=" + baseUrl);
                    } catch (IOException e) {
                        throw new RuntimeException(e);
                    }
                };
            }
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```java SecurityConfig.java lines theme={null}
        package com.auth0.example;

        import org.springframework.context.annotation.Bean;
        import org.springframework.context.annotation.Configuration;
        import org.springframework.security.config.annotation.web.builders.HttpSecurity;
        import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
        import org.springframework.security.web.SecurityFilterChain;

        import static org.springframework.security.config.Customizer.withDefaults;

        @Configuration
        @EnableWebSecurity
        public class SecurityConfig {

            @Bean
            public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
                 http
                    .authorizeHttpRequests(authorize -> authorize
                        .anyRequest().authenticated()
                    )
                    .oauth2Login(withDefaults());
                return http.build();
            }
        }
        ```

        ```yml application.yml lines theme={null}
        okta:
          oauth2:
            issuer: https://{yourDomain}/
            client-id: {yourClientId}
            client-secret: {yourClientSecret}
        ```

        ```html index.html lines theme={null}
        <!-- src/main/resources/templates/index.html -->
        <html lang="en" xmlns:th="http://www.thymeleaf.org" xmlns:sec="http://www.thymeleaf.org/thymeleaf-extras-springsecurity5">
            <body>
                <div sec:authorize="!isAuthenticated()">
                    <a th:href="@{/oauth2/authorization/okta}">Log In</a>
                </div>
                <div sec:authorize="isAuthenticated()">
                    <p>You are logged in!</p>
                    <img th:src="${profile.get('picture')}" th:attr="alt=${profile.get('name')}"/>
                    <h2 th:text="${profile.get('name')}"></h2>
                    <p th:text="${profile.get('email')}"></p>
                    <form name="logoutForm" th:action="@{/logout}" method="post">
                        <button type="submit" value="Log out"/>
                    </form>
                </div>
            </body>
        </html>
        ```

        ```java HomeController.java lines theme={null}
        package com.auth0.example;

        import org.springframework.security.core.annotation.AuthenticationPrincipal;
        import org.springframework.security.oauth2.core.oidc.user.OidcUser;
        import org.springframework.stereotype.Controller;
        import org.springframework.ui.Model;
        import org.springframework.web.bind.annotation.GetMapping;

        /**
         * Controller for the home page.
         */
        @Controller
        public class HomeController {

            @GetMapping("/")
            public String home(Model model, @AuthenticationPrincipal OidcUser principal) {
                if (principal != null) {
                    model.addAttribute("profile", principal.getClaims());
                }
                return "index";
            }
        }
        ```

        ```java SecurityConfigWithLogout.java lines theme={null}
        package com.auth0.example;

        import org.springframework.beans.factory.annotation.Value;
        import org.springframework.context.annotation.Bean;
        import org.springframework.context.annotation.Configuration;
        import org.springframework.security.config.annotation.web.builders.HttpSecurity;
        import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
        import org.springframework.security.web.SecurityFilterChain;
        import org.springframework.security.web.authentication.logout.LogoutHandler;
        import org.springframework.web.servlet.support.ServletUriComponentsBuilder;

        import java.io.IOException;

        import static org.springframework.security.config.Customizer.withDefaults;

        @Configuration
        @EnableWebSecurity
        public class SecurityConfig {

            @Value("${okta.oauth2.issuer}")
            private String issuer;
            @Value("${okta.oauth2.client-id}")
            private String clientId;

            @Bean
            public SecurityFilterChain configure(HttpSecurity http) throws Exception {
                http
                    .authorizeHttpRequests(authorize -> authorize
                        .requestMatchers("/", "/images/**").permitAll()
                        .anyRequest().authenticated()
                    )
                    .oauth2Login(withDefaults())
                    .logout(logout -> logout
                        .addLogoutHandler(logoutHandler()));
                return http.build();
            }

            private LogoutHandler logoutHandler() {
                return (request, response, authentication) -> {
                    try {
                        String baseUrl = ServletUriComponentsBuilder.fromCurrentContextPath().build().toUriString();
                        response.sendRedirect(issuer + "v2/logout?client_id=" + clientId + "&returnTo=" + baseUrl);
                    } catch (IOException e) {
                        throw new RuntimeException(e);
                    }
                };
            }
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```html index.html lines theme={null}
        <!-- src/main/resources/templates/index.html -->
        <html lang="en" xmlns:th="http://www.thymeleaf.org" xmlns:sec="http://www.thymeleaf.org/thymeleaf-extras-springsecurity5">
            <body>
                <div sec:authorize="!isAuthenticated()">
                    <a th:href="@{/oauth2/authorization/okta}">Log In</a>
                </div>
                <div sec:authorize="isAuthenticated()">
                    <p>You are logged in!</p>
                    <img th:src="${profile.get('picture')}" th:attr="alt=${profile.get('name')}"/>
                    <h2 th:text="${profile.get('name')}"></h2>
                    <p th:text="${profile.get('email')}"></p>
                    <form name="logoutForm" th:action="@{/logout}" method="post">
                        <button type="submit" value="Log out"/>
                    </form>
                </div>
            </body>
        </html>
        ```

        ```yml application.yml lines theme={null}
        okta:
          oauth2:
            issuer: https://{yourDomain}/
            client-id: {yourClientId}
            client-secret: {yourClientSecret}
        ```

        ```java SecurityConfig.java lines theme={null}
        package com.auth0.example;

        import org.springframework.context.annotation.Bean;
        import org.springframework.context.annotation.Configuration;
        import org.springframework.security.config.annotation.web.builders.HttpSecurity;
        import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
        import org.springframework.security.web.SecurityFilterChain;

        import static org.springframework.security.config.Customizer.withDefaults;

        @Configuration
        @EnableWebSecurity
        public class SecurityConfig {

            @Bean
            public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
                 http
                    .authorizeHttpRequests(authorize -> authorize
                        .anyRequest().authenticated()
                    )
                    .oauth2Login(withDefaults());
                return http.build();
            }
        }
        ```

        ```java HomeController.java lines theme={null}
        package com.auth0.example;

        import org.springframework.security.core.annotation.AuthenticationPrincipal;
        import org.springframework.security.oauth2.core.oidc.user.OidcUser;
        import org.springframework.stereotype.Controller;
        import org.springframework.ui.Model;
        import org.springframework.web.bind.annotation.GetMapping;

        /**
         * Controller for the home page.
         */
        @Controller
        public class HomeController {

            @GetMapping("/")
            public String home(Model model, @AuthenticationPrincipal OidcUser principal) {
                if (principal != null) {
                    model.addAttribute("profile", principal.getClaims());
                }
                return "index";
            }
        }
        ```

        ```java SecurityConfigWithLogout.java lines theme={null}
        package com.auth0.example;

        import org.springframework.beans.factory.annotation.Value;
        import org.springframework.context.annotation.Bean;
        import org.springframework.context.annotation.Configuration;
        import org.springframework.security.config.annotation.web.builders.HttpSecurity;
        import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
        import org.springframework.security.web.SecurityFilterChain;
        import org.springframework.security.web.authentication.logout.LogoutHandler;
        import org.springframework.web.servlet.support.ServletUriComponentsBuilder;

        import java.io.IOException;

        import static org.springframework.security.config.Customizer.withDefaults;

        @Configuration
        @EnableWebSecurity
        public class SecurityConfig {

            @Value("${okta.oauth2.issuer}")
            private String issuer;
            @Value("${okta.oauth2.client-id}")
            private String clientId;

            @Bean
            public SecurityFilterChain configure(HttpSecurity http) throws Exception {
                http
                    .authorizeHttpRequests(authorize -> authorize
                        .requestMatchers("/", "/images/**").permitAll()
                        .anyRequest().authenticated()
                    )
                    .oauth2Login(withDefaults())
                    .logout(logout -> logout
                        .addLogoutHandler(logoutHandler()));
                return http.build();
            }

            private LogoutHandler logoutHandler() {
                return (request, response, authentication) -> {
                    try {
                        String baseUrl = ServletUriComponentsBuilder.fromCurrentContextPath().build().toUriString();
                        response.sendRedirect(issuer + "v2/logout?client_id=" + clientId + "&returnTo=" + baseUrl);
                    } catch (IOException e) {
                        throw new RuntimeException(e);
                    }
                };
            }
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```java HomeController.java lines theme={null}
        package com.auth0.example;

        import org.springframework.security.core.annotation.AuthenticationPrincipal;
        import org.springframework.security.oauth2.core.oidc.user.OidcUser;
        import org.springframework.stereotype.Controller;
        import org.springframework.ui.Model;
        import org.springframework.web.bind.annotation.GetMapping;

        /**
         * Controller for the home page.
         */
        @Controller
        public class HomeController {

            @GetMapping("/")
            public String home(Model model, @AuthenticationPrincipal OidcUser principal) {
                if (principal != null) {
                    model.addAttribute("profile", principal.getClaims());
                }
                return "index";
            }
        }
        ```

        ```yml application.yml lines theme={null}
        okta:
          oauth2:
            issuer: https://{yourDomain}/
            client-id: {yourClientId}
            client-secret: {yourClientSecret}
        ```

        ```java SecurityConfig.java lines theme={null}
        package com.auth0.example;

        import org.springframework.context.annotation.Bean;
        import org.springframework.context.annotation.Configuration;
        import org.springframework.security.config.annotation.web.builders.HttpSecurity;
        import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
        import org.springframework.security.web.SecurityFilterChain;

        import static org.springframework.security.config.Customizer.withDefaults;

        @Configuration
        @EnableWebSecurity
        public class SecurityConfig {

            @Bean
            public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
                 http
                    .authorizeHttpRequests(authorize -> authorize
                        .anyRequest().authenticated()
                    )
                    .oauth2Login(withDefaults());
                return http.build();
            }
        }
        ```

        ```html index.html lines theme={null}
        <!-- src/main/resources/templates/index.html -->
        <html lang="en" xmlns:th="http://www.thymeleaf.org" xmlns:sec="http://www.thymeleaf.org/thymeleaf-extras-springsecurity5">
            <body>
                <div sec:authorize="!isAuthenticated()">
                    <a th:href="@{/oauth2/authorization/okta}">Log In</a>
                </div>
                <div sec:authorize="isAuthenticated()">
                    <p>You are logged in!</p>
                    <img th:src="${profile.get('picture')}" th:attr="alt=${profile.get('name')}"/>
                    <h2 th:text="${profile.get('name')}"></h2>
                    <p th:text="${profile.get('email')}"></p>
                    <form name="logoutForm" th:action="@{/logout}" method="post">
                        <button type="submit" value="Log out"/>
                    </form>
                </div>
            </body>
        </html>
        ```

        ```java SecurityConfigWithLogout.java lines theme={null}
        package com.auth0.example;

        import org.springframework.beans.factory.annotation.Value;
        import org.springframework.context.annotation.Bean;
        import org.springframework.context.annotation.Configuration;
        import org.springframework.security.config.annotation.web.builders.HttpSecurity;
        import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
        import org.springframework.security.web.SecurityFilterChain;
        import org.springframework.security.web.authentication.logout.LogoutHandler;
        import org.springframework.web.servlet.support.ServletUriComponentsBuilder;

        import java.io.IOException;

        import static org.springframework.security.config.Customizer.withDefaults;

        @Configuration
        @EnableWebSecurity
        public class SecurityConfig {

            @Value("${okta.oauth2.issuer}")
            private String issuer;
            @Value("${okta.oauth2.client-id}")
            private String clientId;

            @Bean
            public SecurityFilterChain configure(HttpSecurity http) throws Exception {
                http
                    .authorizeHttpRequests(authorize -> authorize
                        .requestMatchers("/", "/images/**").permitAll()
                        .anyRequest().authenticated()
                    )
                    .oauth2Login(withDefaults())
                    .logout(logout -> logout
                        .addLogoutHandler(logoutHandler()));
                return http.build();
            }

            private LogoutHandler logoutHandler() {
                return (request, response, authentication) -> {
                    try {
                        String baseUrl = ServletUriComponentsBuilder.fromCurrentContextPath().build().toUriString();
                        response.sendRedirect(issuer + "v2/logout?client_id=" + clientId + "&returnTo=" + baseUrl);
                    } catch (IOException e) {
                        throw new RuntimeException(e);
                    }
                };
            }
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```java SecurityConfigWithLogout.java lines theme={null}
        package com.auth0.example;

        import org.springframework.beans.factory.annotation.Value;
        import org.springframework.context.annotation.Bean;
        import org.springframework.context.annotation.Configuration;
        import org.springframework.security.config.annotation.web.builders.HttpSecurity;
        import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
        import org.springframework.security.web.SecurityFilterChain;
        import org.springframework.security.web.authentication.logout.LogoutHandler;
        import org.springframework.web.servlet.support.ServletUriComponentsBuilder;

        import java.io.IOException;

        import static org.springframework.security.config.Customizer.withDefaults;

        @Configuration
        @EnableWebSecurity
        public class SecurityConfig {

            @Value("${okta.oauth2.issuer}")
            private String issuer;
            @Value("${okta.oauth2.client-id}")
            private String clientId;

            @Bean
            public SecurityFilterChain configure(HttpSecurity http) throws Exception {
                http
                    .authorizeHttpRequests(authorize -> authorize
                        .requestMatchers("/", "/images/**").permitAll()
                        .anyRequest().authenticated()
                    )
                    .oauth2Login(withDefaults())
                    .logout(logout -> logout
                        .addLogoutHandler(logoutHandler()));
                return http.build();
            }

            private LogoutHandler logoutHandler() {
                return (request, response, authentication) -> {
                    try {
                        String baseUrl = ServletUriComponentsBuilder.fromCurrentContextPath().build().toUriString();
                        response.sendRedirect(issuer + "v2/logout?client_id=" + clientId + "&returnTo=" + baseUrl);
                    } catch (IOException e) {
                        throw new RuntimeException(e);
                    }
                };
            }
        }
        ```

        ```yml application.yml lines theme={null}
        okta:
          oauth2:
            issuer: https://{yourDomain}/
            client-id: {yourClientId}
            client-secret: {yourClientSecret}
        ```

        ```java SecurityConfig.java lines theme={null}
        package com.auth0.example;

        import org.springframework.context.annotation.Bean;
        import org.springframework.context.annotation.Configuration;
        import org.springframework.security.config.annotation.web.builders.HttpSecurity;
        import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
        import org.springframework.security.web.SecurityFilterChain;

        import static org.springframework.security.config.Customizer.withDefaults;

        @Configuration
        @EnableWebSecurity
        public class SecurityConfig {

            @Bean
            public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
                 http
                    .authorizeHttpRequests(authorize -> authorize
                        .anyRequest().authenticated()
                    )
                    .oauth2Login(withDefaults());
                return http.build();
            }
        }
        ```

        ```html index.html lines theme={null}
        <!-- src/main/resources/templates/index.html -->
        <html lang="en" xmlns:th="http://www.thymeleaf.org" xmlns:sec="http://www.thymeleaf.org/thymeleaf-extras-springsecurity5">
            <body>
                <div sec:authorize="!isAuthenticated()">
                    <a th:href="@{/oauth2/authorization/okta}">Log In</a>
                </div>
                <div sec:authorize="isAuthenticated()">
                    <p>You are logged in!</p>
                    <img th:src="${profile.get('picture')}" th:attr="alt=${profile.get('name')}"/>
                    <h2 th:text="${profile.get('name')}"></h2>
                    <p th:text="${profile.get('email')}"></p>
                    <form name="logoutForm" th:action="@{/logout}" method="post">
                        <button type="submit" value="Log out"/>
                    </form>
                </div>
            </body>
        </html>
        ```

        ```java HomeController.java lines theme={null}
        package com.auth0.example;

        import org.springframework.security.core.annotation.AuthenticationPrincipal;
        import org.springframework.security.oauth2.core.oidc.user.OidcUser;
        import org.springframework.stereotype.Controller;
        import org.springframework.ui.Model;
        import org.springframework.web.bind.annotation.GetMapping;

        /**
         * Controller for the home page.
         */
        @Controller
        public class HomeController {

            @GetMapping("/")
            public String home(Model model, @AuthenticationPrincipal OidcUser principal) {
                if (principal != null) {
                    model.addAttribute("profile", principal.getClaims());
                }
                return "index";
            }
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>
  </SideMenu>
</Recipe>


# Add Login to Your Java Servlet Application
Source: https://auth0.com/docs/quickstart/webapp/java/index

This quickstart demonstrates how to add Auth0 authentication to a Java servlet application. You'll build a secure web application with login, logout, and user profile features using the Auth0 Java MVC Commons SDK.

<Note>
  **Prerequisites:** Before you begin, ensure you have the following installed:

  * **Java Development Kit (JDK)**: Version 8 or higher
  * **Build Tool**: [Maven](https://maven.apache.org/download.cgi) 3.6+ or [Gradle](https://gradle.org/install/) 6.0+
  * **Application Server**: [Apache Tomcat](https://tomcat.apache.org/download-90.cgi) 9.0+ or any servlet container
  * **Auth0 Account**: [Sign up for free](https://auth0.com/signup) if you don't have one
</Note>

## Get Started

This quickstart demonstrates how to add Auth0 authentication to a Java servlet application. You'll build a secure web application with login, logout, and user profile features using the Auth0 Java MVC Commons SDK.

<Steps>
  <Step title="Create a New Java Web Project">
    Create a new Java web application project for this quickstart.

    <Tabs>
      <Tab title="Maven">
        ```bash theme={null}
        mvn archetype:generate \
          -DgroupId=com.auth0.example \
          -DartifactId=auth0-servlet-app \
          -DarchetypeArtifactId=maven-archetype-webapp \
          -DinteractiveMode=false
        ```

        Navigate to your project directory:

        ```bash theme={null}
        cd auth0-servlet-app
        ```
      </Tab>

      <Tab title="Gradle">
        Create a new directory and initialize a Gradle project:

        ```bash theme={null}
        mkdir auth0-servlet-app && cd auth0-servlet-app
        gradle init --type java-application
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Install the Auth0 Java MVC Commons SDK">
    Add the Auth0 dependency to your project build file.

    <Tabs>
      <Tab title="Maven">
        Add the following dependency to your `pom.xml`:

        ```xml theme={null}
        <dependencies>
            <dependency>
                <groupId>com.auth0</groupId>
                <artifactId>mvc-auth-commons</artifactId>
                <version>1.11.1</version>
            </dependency>
            <dependency>
                <groupId>javax.servlet</groupId>
                <artifactId>javax.servlet-api</artifactId>
                <version>3.1.0</version>
                <scope>provided</scope>
            </dependency>
            <dependency>
                <groupId>javax.servlet</groupId>
                <artifactId>jstl</artifactId>
                <version>1.2</version>
            </dependency>
        </dependencies>
        ```
      </Tab>

      <Tab title="Gradle">
        Add the following dependencies to your `build.gradle`:

        ```gradle theme={null}
        plugins {
            id 'java'
            id 'war'
        }

        dependencies {
            implementation 'com.auth0:mvc-auth-commons:1.11.1'
            implementation 'javax.servlet:javax.servlet-api:3.1.0'
            implementation 'javax.servlet:jstl:1.2'
        }
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Setup Your Auth0 Application">
    Next, you need to create a new application on your Auth0 tenant and add the configuration to your project.

    1. Head to the [Auth0 Dashboard](https://manage.auth0.com/dashboard)
    2. Click on **Applications** > **Applications** > **Create Application**
    3. In the popup, enter a name for your app, select **Regular Web Application** as the app type and click **Create**
    4. Switch to the **Settings** tab on the Application Details page
    5. Note down the **Domain**, **Client ID**, and **Client Secret** values from the dashboard
    6. Finally, on the **Settings** tab of your Application Details page, configure the following URLs:

    **Allowed Callback URLs:**

    ```
    http://localhost:8080/callback
    ```

    **Allowed Logout URLs:**

    ```
    http://localhost:8080/login
    ```

    **Allowed Web Origins:**

    ```
    http://localhost:8080
    ```

    <Note>
      * **Allowed Callback URLs** are a critical security measure to ensure users are safely returned to your application after authentication. Without a matching URL, the login process will fail, and users will be blocked by an Auth0 error page instead of accessing your app.
      * **Allowed Logout URLs** are essential for providing a seamless user experience upon signing out. Without a matching URL, users will not be redirected back to your application after logout and will instead be left on a generic Auth0 page.
      * **Allowed Web Origins** is critical for silent authentication. Without it, users will be logged out when they refresh the page or return to your app later.
    </Note>
  </Step>

  <Step title="Configure the Auth0 SDK">
    Configure your servlet application to use the Auth0 SDK by setting up the web.xml configuration with the Auth0 credentials generated above.

    Create or update `src/main/webapp/WEB-INF/web.xml` and replace the placeholder values with your actual Auth0 application settings:

    ```xml expandable theme={null}
    <?xml version="1.0" encoding="UTF-8"?>
    <web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
             http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
             version="3.1">

        <display-name>Auth0 Servlet Example</display-name>

        <!-- Auth0 Configuration -->
        <context-param>
            <param-name>com.auth0.domain</param-name>
            <param-value>YOUR_AUTH0_DOMAIN</param-value>
        </context-param>
        <context-param>
            <param-name>com.auth0.clientId</param-name>
            <param-value>YOUR_AUTH0_CLIENT_ID</param-value>
        </context-param>
        <context-param>
            <param-name>com.auth0.clientSecret</param-name>
            <param-value>YOUR_AUTH0_CLIENT_SECRET</param-value>
        </context-param>
    </web-app>
    ```

    **Important**: Replace `YOUR_AUTH0_DOMAIN`, `YOUR_AUTH0_CLIENT_ID`, and `YOUR_AUTH0_CLIENT_SECRET` with the actual values from your Auth0 application settings.
  </Step>

  <Step title="Create Authentication Components and Filter">
    Create the necessary Java classes to handle authentication flows and protect secured pages.

    <AuthCodeGroup>
      ```java src/main/java/com/auth0/example/AuthenticationControllerProvider.java expandable lines theme={null}
      package com.auth0.example;

      import com.auth0.AuthenticationController;
      import com.auth0.jwk.JwkProvider;
      import com.auth0.jwk.JwkProviderBuilder;

      import javax.servlet.ServletConfig;
      import java.io.UnsupportedEncodingException;

      /**
       * Manages a singleton instance of AuthenticationController for the application.
       */
      public class AuthenticationControllerProvider {

          private AuthenticationControllerProvider() {}

          private static AuthenticationController INSTANCE;

          public static synchronized AuthenticationController getInstance(ServletConfig config)
                  throws UnsupportedEncodingException {
              if (INSTANCE == null) {
                  String domain = config.getServletContext().getInitParameter("com.auth0.domain");
                  String clientId = config.getServletContext().getInitParameter("com.auth0.clientId");
                  String clientSecret = config.getServletContext().getInitParameter("com.auth0.clientSecret");

                  if (domain == null || clientId == null || clientSecret == null) {
                      throw new IllegalArgumentException(
                          "Missing domain, clientId, or clientSecret. Check your web.xml configuration.");
                  }

                  // JwkProvider required for RS256 tokens
                  JwkProvider jwkProvider = new JwkProviderBuilder(domain).build();
                  INSTANCE = AuthenticationController.newBuilder(domain, clientId, clientSecret)
                          .withJwkProvider(jwkProvider)
                          .build();
              }
              return INSTANCE;
          }
      }
      ```

      ```java src/main/java/com/auth0/example/LoginServlet.java expandable lines theme={null}
      package com.auth0.example;

      import com.auth0.AuthenticationController;

      import javax.servlet.ServletConfig;
      import javax.servlet.ServletException;
      import javax.servlet.annotation.WebServlet;
      import javax.servlet.http.HttpServlet;
      import javax.servlet.http.HttpServletRequest;
      import javax.servlet.http.HttpServletResponse;
      import java.io.IOException;
      import java.io.UnsupportedEncodingException;

      @WebServlet(urlPatterns = {"/login"})
      public class LoginServlet extends HttpServlet {

          private AuthenticationController authenticationController;

          @Override
          public void init(ServletConfig config) throws ServletException {
              super.init(config);
              try {
                  authenticationController = AuthenticationControllerProvider.getInstance(config);
              } catch (UnsupportedEncodingException e) {
                  throw new ServletException("Couldn't create the AuthenticationController instance. Check the configuration.", e);
              }
          }

          @Override
          protected void doGet(HttpServletRequest req, HttpServletResponse res)
                  throws ServletException, IOException {
              // Build the callback URL
              String redirectUri = req.getScheme() + "://" + req.getServerName();
              if ((req.getScheme().equals("http") && req.getServerPort() != 80) ||
                  (req.getScheme().equals("https") && req.getServerPort() != 443)) {
                  redirectUri += ":" + req.getServerPort();
              }
              redirectUri += "/callback";

              // Generate Auth0 authorization URL
              String authorizeUrl = authenticationController.buildAuthorizeUrl(req, res, redirectUri)
                      .build();
              res.sendRedirect(authorizeUrl);
          }
      }
      ```

      ```java src/main/java/com/auth0/example/CallbackServlet.java expandable lines theme={null}
      package com.auth0.example;

      import com.auth0.AuthenticationController;
      import com.auth0.IdentityVerificationException;
      import com.auth0.SessionUtils;
      import com.auth0.Tokens;

      import javax.servlet.ServletConfig;
      import javax.servlet.ServletException;
      import javax.servlet.annotation.WebServlet;
      import javax.servlet.http.HttpServlet;
      import javax.servlet.http.HttpServletRequest;
      import javax.servlet.http.HttpServletResponse;
      import java.io.IOException;
      import java.io.UnsupportedEncodingException;

      @WebServlet(urlPatterns = {"/callback"})
      public class CallbackServlet extends HttpServlet {

          private AuthenticationController authenticationController;

          @Override
          public void init(ServletConfig config) throws ServletException {
              super.init(config);
              try {
                  authenticationController = AuthenticationControllerProvider.getInstance(config);
              } catch (UnsupportedEncodingException e) {
                  throw new ServletException("Couldn't create the AuthenticationController instance. Check the configuration.", e);
              }
          }

          @Override
          public void doGet(HttpServletRequest req, HttpServletResponse res)
                  throws IOException, ServletException {
              handleCallback(req, res);
          }

          @Override
          public void doPost(HttpServletRequest req, HttpServletResponse res)
                  throws IOException, ServletException {
              handleCallback(req, res);
          }

          private void handleCallback(HttpServletRequest req, HttpServletResponse res)
                  throws IOException {
              try {
                  // Process the authentication callback
                  Tokens tokens = authenticationController.handle(req, res);

                  // Store tokens in session
                  SessionUtils.set(req, "accessToken", tokens.getAccessToken());
                  SessionUtils.set(req, "idToken", tokens.getIdToken());

                  // Redirect to secure area
                  res.sendRedirect("/profile");
              } catch (IdentityVerificationException e) {
                  // Authentication failed
                  e.printStackTrace();
                  res.sendRedirect("/login?error=auth_failed");
              }
          }
      }
      ```

      ```java src/main/java/com/auth0/example/ProfileServlet.java expandable lines theme={null}
      package com.auth0.example;

      import com.auth0.SessionUtils;

      import javax.servlet.ServletException;
      import javax.servlet.annotation.WebServlet;
      import javax.servlet.http.HttpServlet;
      import javax.servlet.http.HttpServletRequest;
      import javax.servlet.http.HttpServletResponse;
      import java.io.IOException;

      @WebServlet(urlPatterns = {"/profile"})
      public class ProfileServlet extends HttpServlet {

          @Override
          protected void doGet(HttpServletRequest req, HttpServletResponse res)
                  throws ServletException, IOException {

              String accessToken = (String) SessionUtils.get(req, "accessToken");
              String idToken = (String) SessionUtils.get(req, "idToken");

              if (accessToken == null && idToken == null) {
                  res.sendRedirect("/login");
                  return;
              }

              // Forward to profile JSP
              req.setAttribute("accessToken", accessToken);
              req.setAttribute("idToken", idToken);
              req.getRequestDispatcher("/WEB-INF/jsp/profile.jsp").forward(req, res);
          }
      }
      ```

      ```java src/main/java/com/auth0/example/LogoutServlet.java expandable lines theme={null}
      package com.auth0.example;

      import com.auth0.SessionUtils;

      import javax.servlet.ServletException;
      import javax.servlet.annotation.WebServlet;
      import javax.servlet.http.HttpServlet;
      import javax.servlet.http.HttpServletRequest;
      import javax.servlet.http.HttpServletResponse;
      import java.io.IOException;

      @WebServlet(urlPatterns = {"/logout"})
      public class LogoutServlet extends HttpServlet {

          @Override
          protected void doGet(HttpServletRequest req, HttpServletResponse res)
                  throws ServletException, IOException {

              // Clear session
              SessionUtils.set(req, "accessToken", null);
              SessionUtils.set(req, "idToken", null);
              req.getSession().invalidate();

              // Redirect to login

              res.sendRedirect("/login");
          }
      }
      ```

      ```java src/main/java/com/auth0/example/AuthenticationFilter.java expandable lines theme={null}
      package com.auth0.example;

      import com.auth0.SessionUtils;

      import javax.servlet.*;
      import javax.servlet.annotation.WebFilter;
      import javax.servlet.http.HttpServletRequest;
      import javax.servlet.http.HttpServletResponse;
      import java.io.IOException;

      @WebFilter(urlPatterns = {"/profile"})
      public class AuthenticationFilter implements Filter {

          @Override
          public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
                  throws IOException, ServletException {

              HttpServletRequest req = (HttpServletRequest) request;
              HttpServletResponse res = (HttpServletResponse) response;

              String accessToken = (String) SessionUtils.get(req, "accessToken");
              String idToken = (String) SessionUtils.get(req, "idToken");

              if (accessToken == null && idToken == null) {
                  res.sendRedirect("/login");
                  return;
              }

              chain.doFilter(request, response);
          }

          @Override
          public void init(FilterConfig filterConfig) throws ServletException {
              // Initialize filter
          }

          @Override
          public void destroy() {
              // Clean up resources
          }
      }
      ```
    </AuthCodeGroup>
  </Step>

  <Step title="Create User Interface Pages">
    Create the JSP pages and HTML files for your application.

    <AuthCodeGroup>
      ```jsp src/main/webapp/WEB-INF/jsp/profile.jsp expandable lines theme={null}
      <%@ page contentType="text/html;charset=UTF-8" language="java" %>
      <!DOCTYPE html>
      <html>
      <head>
          <title>Profile - Auth0 Example</title>
          <style>
              body { font-family: Arial, sans-serif; margin: 40px; }
              .profile-container { max-width: 600px; margin: 0 auto; }
              .token-section { margin: 20px 0; padding: 15px; background-color: #f5f5f5; border-radius: 5px; }
              .logout-btn {
                  background-color: #dc3545;
                  color: white;
                  padding: 10px 20px;
                  text-decoration: none;
                  border-radius: 5px;
                  display: inline-block;
                  margin-top: 20px;
              }
              .logout-btn:hover { background-color: #c82333; }
              code { background-color: #e9ecef; padding: 2px 4px; border-radius: 3px; }
          </style>
      </head>
      <body>
          <div class="profile-container">
              <h1>Welcome to Your Profile!</h1>
              <p>You have successfully authenticated with Auth0.</p>

              <div class="token-section">
                  <h3>Access Token</h3>
                  <p><code>${accessToken}</code></p>
              </div>

              <div class="token-section">
                  <h3>ID Token</h3>
                  <p><code>${idToken}</code></p>
              </div>

              <a href="/logout" class="logout-btn">Logout</a>
          </div>
      </body>
      </html>
      ```

      ```html src/main/webapp/index.html expandable lines theme={null}
      <!DOCTYPE html>
      <html>
        <head>
          <title>Auth0 Java Servlet Example</title>
          <style>
            body {
              font-family: Arial, sans-serif;
              margin: 0;
              padding: 40px;
              background-color: #f8f9fa;
            }
            .container {
              max-width: 600px;
              margin: 0 auto;
              text-align: center;
              background-color: white;
              padding: 40px;
              border-radius: 8px;
              box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
            }
            .login-btn {
              background-color: #007bff;
              color: white;
              padding: 12px 30px;
              text-decoration: none;
              border-radius: 5px;
              display: inline-block;
              font-size: 16px;
              margin-top: 20px;
              transition: background-color 0.3s;
            }
            .login-btn:hover {
              background-color: #0056b3;
            }
            h1 {
              color: #333;
            }
            p {
              color: #666;
              line-height: 1.6;
            }
          </style>
        </head>
        <body>
          <div class="container">
            <h1>Auth0 Java Servlet Example</h1>
            <p>
              This example demonstrates how to add authentication to a Java servlet
              application using the Auth0 Java MVC Commons SDK.
            </p>
            <p>
              Click the button below to authenticate with Auth0 and access your
              profile.
            </p>

            <a href="/login" class="login-btn">Login with Auth0</a>
          </div>
        </body>
      </html>
      ```
    </AuthCodeGroup>
  </Step>

  <Step title="Build and Run Your Application">
    Now you're ready to build and run your application.

    <Tabs>
      <Tab title="Maven">
        Build the application:

        ```bash theme={null}
        mvn clean compile war:war
        ```

        Deploy to Tomcat:

        ```bash theme={null}
        # Copy the WAR file to Tomcat webapps directory
        cp target/auth0-servlet-app.war $CATALINA_HOME/webapps/ROOT.war
        ```
      </Tab>

      <Tab title="Gradle">
        Build the application:

        ```bash theme={null}
        gradle clean build
        ```

        Deploy to Tomcat:

        ```bash theme={null}
        # Copy the WAR file to Tomcat webapps directory
        cp build/libs/auth0-servlet-app.war $CATALINA_HOME/webapps/
        ```
      </Tab>
    </Tabs>

    Start Tomcat (or your preferred servlet container):

    ```bash theme={null}
    $CATALINA_HOME/bin/startup.sh  # On Unix/Linux/Mac
    # or
    $CATALINA_HOME/bin/startup.bat  # On Windows
    ```
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a fully functional Auth0-integrated servlet application running at [http://localhost:8080/](http://localhost:8080/)

  **Test your implementation:**

  1. Navigate to your application URL
  2. Click "Login with Auth0"
  3. Complete the Auth0 login process
  4. You should be redirected to your profile page showing the tokens
  5. Click "Logout" to clear the session
</Check>

***

## Advanced Usage

<Accordion title="Enhance Your Application">
  Now that you have basic authentication working, consider these enhancements:

  * **User Profile Information**: Decode the ID token to display user information
  * **API Calls**: Use the access token to call Auth0's Management API or your own APIs
  * **Role-Based Access**: Implement authorization using Auth0 roles and permissions
  * **Single Sign-On**: Configure SSO across multiple applications
</Accordion>

<Accordion title="Additional Resources">
  * [Auth0 Java MVC Commons
    Documentation](https://github.com/auth0/auth0-java-mvc-common) - [Auth0
    Dashboard](https://manage.auth0.com/) - Manage your Auth0 applications -
    [Auth0 Servlet Sample
    Repository](https://github.com/auth0-samples/auth0-servlet-sample) - Complete
    examples - [Auth0 Java SDK
    Documentation](https://auth0.com/docs/libraries/auth0-java) - Advanced SDK
    usage
</Accordion>

<Accordion title="Troubleshooting">
  **Common Issues**

  **Authentication fails with "Invalid callback URL"**

  * Verify that the callback URL in your Auth0 application settings matches exactly: `http://localhost:8080/callback`

  **"Missing domain, clientId, or clientSecret" error**

  * Check that your `web.xml` configuration has the correct Auth0 application values
  * Ensure the parameter names match exactly: `com.auth0.domain`, `com.auth0.clientId`, `com.auth0.clientSecret`

  **Application doesn't start**

  * Verify all required dependencies are in your classpath
  * Check that your servlet container supports Servlet API 3.0+
  * Review server logs for specific error messages

  **Session not persisting**

  * Ensure your servlet container is configured for session management
  * Check that cookies are enabled in your browser
  * Verify HTTPS is used in production environments

  For additional support, visit the [Auth0 Community](https://community.auth0.com/) or check the [Auth0 Support Center](https://support.auth0.com/).
</Accordion>


# Add Login to Your Laravel Application
Source: https://auth0.com/docs/quickstart/webapp/laravel/interactive

This guide demonstrates how to integrate Auth0 with a new (or existing) Laravel 9 or 10 application.

<QuickstartButtons />

<Recipe>
  <Content>
    [Auth0's Laravel SDK](https://github.com/auth0/laravel-auth0)
    allows you to quickly add authentication, user profile management, and routing access control to your Laravel
    application. This guide demonstrates how to integrate Auth0 with a new (or existing) [Laravel 9
    or 10](https://github.com/auth0/laravel-auth0#support-policy) application.

    Test Change

    <Section title={sections[0].title}>
      **If you do not already have a Laravel application set up**, open a shell to a suitable directory for a new
      project and run the following command:

      ```sh wrap lines theme={null}
      composer create-project --prefer-dist laravel/laravel auth0-laravel-app ^9.0
      ```

      All the commands in this guide assume you are running them from the root of your Laravel project, directory so
      you should `cd` into the new project directory:

      ```sh lines theme={null}
      cd auth0-laravel-app
      ```
    </Section>

    <Section title={sections[1].title}>
      Run the following command within your project directory to install the [Auth0 Laravel SDK](https://github.com/auth0/laravel-auth0):

      ```sh wrap lines theme={null}
      composer require auth0/login:^7.8 --update-with-all-dependencies
      ```

      Then generate an SDK configuration file for your application:

      ```sh lines theme={null}
      php artisan vendor:publish --tag auth0
      ```
    </Section>

    <Section title={sections[2].title}>
      Run the following command from your project directory to download the Auth0 CLI:

      ```sh wrap lines theme={null}
      curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh | sh -s -- -b .
      ```

      Then authenticate the CLI with your Auth0 account, choosing "as a user" when prompted:

      ```sh lines theme={null}
      ./auth0 login
      ```

      Next, create a new application with Auth0:

      ```sh lines theme={null}
      ./auth0 apps create \
        --name "My Laravel Application" \
        --type "regular" \
        --auth-method "post" \
        --callbacks "http://localhost:8000/callback" \
        --logout-urls "http://localhost:8000" \
        --reveal-secrets \
        --no-input \
        --json > .auth0.app.json
      ```

      You should also create a new API:

      ```sh lines theme={null}
      ./auth0 apis create \
        --name "My Laravel Application's API" \
        --identifier "https://github.com/auth0/laravel-auth0" \
        --offline-access \
        --no-input \
        --json > .auth0.api.json
      ```

      This produces two files in your project directory that configure the SDK.

      As these files contain credentials it's important to treat these as sensitive. You should ensure you do not
      commit these to version control. If you're using Git, you should add them to your `.gitignore` file:

      ```sh lines theme={null}
      echo ".auth0.*.json" >> .gitignore
      ```
    </Section>

    <Section title={sections[3].title}>
      The SDK automatically registers all the necessary routes for your application's users to authenticate.

      If you require more control over these, or if they conflict with existing routes in your application, you can
      manually register the SDK's controllers instead. Please see [the SDK's README](https://github.com/auth0/laravel-auth0) for advanced integrations.
    </Section>

    <Section title={sections[4].title}>
      Laravel's authentication facilities use "guards" to define how users are authenticated for each request. You can
      use the Auth0 SDK's authentication guard to restrict access to your application's routes.

      To require users to authenticate before accessing a route, you can use Laravel's `auth` middleware.

      ```text lines theme={null}
      Route::get('/private', function () {
        return response('Welcome! You are logged in.');
      })->middleware('auth');
      ```

      You can also require authenticated users to have specific [permissions](https://auth0.com/docs/manage-users/access-control/rbac) by combining this
      with Laravel's `can` middleware.

      ```text lines theme={null}
      Route::get('/scope', function () {
        return response('You have `read:messages` permission, and can therefore access this resource.');

      })->middleware('auth')->can('read:messages');
      ```
    </Section>

    <Section title={sections[5].title}>
      Information about the authenticated user is available through Laravel's `Auth` Facade, or the
      `auth()` helper function.

      For example, to retrieve the user's identifier and email address:

      ```text lines theme={null}
      Route::get('/', function () {
        if (! auth()->check()) {
        return response('You are not logged in.');

        }
        $user = auth()->user();
        $name = $user->name ?? 'User';
        $email = $user->email ?? '';
        return response("Hello {$name}! Your email address is {$email}.");
      });;
      ```
    </Section>

    <Section title={sections[6].title}>
      You can update user information using the [Auth0 Management API](https://github.com/auth0/laravel-auth0/blob/main/docs/Management.md). All Management endpoints are accessible through the SDK's
      `management()` method.

      **Before making Management API calls you must enable your application to communicate with the Management
      API.** This can be done from the [Auth0 Dashboard's API page](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq/apis/), choosing
      `Auth0 Management API`, and selecting the 'Machine to Machine Applications' tab. Authorize your Laravel
      application, and then click the down arrow to choose the scopes you wish to grant.

      For the following example, in which we will update a user's metadata and assign a random favorite color, you
      should grant the `read:users` and `update:users` scopes. A list of API endpoints and the
      required scopes can be found in [the Management
      API documentation](https://auth0.com/docs/api/management/v2).

      ```text lines theme={null}
      use Auth0\Laravel\Facade\Auth0;
      Route::get('/colors', function () {
      $endpoint = Auth0::management()->users();
      $colors = ['red', 'blue', 'green', 'black', 'white', 'yellow', 'purple', 'orange', 'pink', 'brown'];
      $endpoint->update(
      id: auth()-&gt;id(),

      body: [

          'user_metadata' =&gt; [

              'color' =&gt; $colors[random_int(0, count($colors) - 1)]

          ]

      ]

      );
      $metadata = $endpoint->get(auth()->id());
      $metadata = Auth0::json($metadata);
      $color = $metadata['user_metadata']['color'] ?? 'unknown';
      $name = auth()->user()->name;
      return response("Hello {$name}! Your favorite color is {$color}.");
      })->middleware('auth');
      ```

      A quick reference guide of all the SDK's Management API methods is [available here](https://github.com/auth0/laravel-auth0/blob/main/docs/Management.md).
    </Section>

    <Section title={sections[7].title}>
      You are now ready to start your Laravel application, so it can accept requests:

      ```text lines theme={null}
      php artisan serve
      ```

      <Info>
        ##### Checkpoint

        Open your web browser and try accessing the following routes:

        * [http://localhost:8000](http://localhost:8000/)
          to see the public route.
        * [http://localhost:8000/private](http://localhost:8000/private) to be prompted to authenticate.
        * [http://localhost:8000](http://localhost:8000/)
          to see the public route, now authenticated.
        * [http://localhost:8000/scope](http://localhost:8000/scope) to check if you have the
          `read:messages`[permission](https://auth0.com/docs/manage-users/access-control/rbac).
        * [http://localhost:8000/update](http://localhost:8000/update) to update the user's profile.
        * [http://localhost:8000/logout](http://localhost:8000/logout) to log out.
      </Info>

      ### Additional Reading

      * [User Repositories and Models](https://github.com/auth0/laravel-auth0/blob/main/docs/Users.md) extends the Auth0 Laravel SDK to use custom user
        models, and how to store and retrieve users from a database.
      * [Hooking Events](https://github.com/auth0/laravel-auth0/blob/main/docs/Events.md) covers how to listen for events raised by the Auth0 Laravel
        SDK, to fully customize the behavior of your integration.
      * [Management API](https://github.com/auth0/laravel-auth0/blob/main/docs/Management.md) support is built into the Auth0 Laravel SDK, allowing you to
        interact with the Management API from your Laravel application.
    </Section>

    ## Next Steps

    Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.

    This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:

    * [Auth0 Dashboard](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq) - Learn how to configure and manage your Auth0 tenant and applications
    * [laravel-auth0 SDK](https://github.com/auth0/laravel-auth0) - Explore the SDK used in this tutorial more fully
    * [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
  </Content>

  <SideMenu>
    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      ```php web.php highlight={6-12} lines  theme={null}
      <?php

      use Auth0\Laravel\Facade\Auth0;
      use Illuminate\Support\Facades\Route;

      Route::get('/private', function () {
        return response('Welcome! You are logged in.');
      })->middleware('auth');

      Route::get('/scope', function () {
          return response('You have `read:messages` permission, and can therefore access this resource.');
      })->middleware('auth')->can('read:messages');

      Route::get('/', function () {
        if (! auth()->check()) {
          return response('You are not logged in.');
        }

        $user = auth()->user();
        $name = $user->name ?? 'User';
        $email = $user->email ?? '';

        return response("Hello {$name}! Your email address is {$email}.");
      });

      Route::get('/colors', function () {
        $endpoint = Auth0::management()->users();

        $colors = ['red', 'blue', 'green', 'black', 'white', 'yellow', 'purple', 'orange', 'pink', 'brown'];

        $endpoint->update(
          id: auth()->id(),
          body: [
              'user_metadata' => [
                  'color' => $colors[random_int(0, count($colors) - 1)]
              ]
          ]
        );

        $metadata = $endpoint->get(auth()->id()); // Retrieve the user's metadata.
        $metadata = Auth0::json($metadata); // Convert the JSON to a PHP array.

        $color = $metadata['user_metadata']['color'] ?? 'unknown';
        $name = auth()->user()->name;

        return response("Hello {$name}! Your favorite color is {$color}.");
      })->middleware('auth');
      ```
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      ```php web.php highlight={14-24} lines  theme={null}
      <?php

      use Auth0\Laravel\Facade\Auth0;
      use Illuminate\Support\Facades\Route;

      Route::get('/private', function () {
        return response('Welcome! You are logged in.');
      })->middleware('auth');

      Route::get('/scope', function () {
          return response('You have `read:messages` permission, and can therefore access this resource.');
      })->middleware('auth')->can('read:messages');

      Route::get('/', function () {
        if (! auth()->check()) {
          return response('You are not logged in.');
        }

        $user = auth()->user();
        $name = $user->name ?? 'User';
        $email = $user->email ?? '';

        return response("Hello {$name}! Your email address is {$email}.");
      });

      Route::get('/colors', function () {
        $endpoint = Auth0::management()->users();

        $colors = ['red', 'blue', 'green', 'black', 'white', 'yellow', 'purple', 'orange', 'pink', 'brown'];

        $endpoint->update(
          id: auth()->id(),
          body: [
              'user_metadata' => [
                  'color' => $colors[random_int(0, count($colors) - 1)]
              ]
          ]
        );

        $metadata = $endpoint->get(auth()->id()); // Retrieve the user's metadata.
        $metadata = Auth0::json($metadata); // Convert the JSON to a PHP array.

        $color = $metadata['user_metadata']['color'] ?? 'unknown';
        $name = auth()->user()->name;

        return response("Hello {$name}! Your favorite color is {$color}.");
      })->middleware('auth');
      ```
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      ```php web.php highlight={26-43} lines  theme={null}
      <?php

      use Auth0\Laravel\Facade\Auth0;
      use Illuminate\Support\Facades\Route;

      Route::get('/private', function () {
        return response('Welcome! You are logged in.');
      })->middleware('auth');

      Route::get('/scope', function () {
          return response('You have `read:messages` permission, and can therefore access this resource.');
      })->middleware('auth')->can('read:messages');

      Route::get('/', function () {
        if (! auth()->check()) {
          return response('You are not logged in.');
        }

        $user = auth()->user();
        $name = $user->name ?? 'User';
        $email = $user->email ?? '';

        return response("Hello {$name}! Your email address is {$email}.");
      });

      Route::get('/colors', function () {
        $endpoint = Auth0::management()->users();

        $colors = ['red', 'blue', 'green', 'black', 'white', 'yellow', 'purple', 'orange', 'pink', 'brown'];

        $endpoint->update(
          id: auth()->id(),
          body: [
              'user_metadata' => [
                  'color' => $colors[random_int(0, count($colors) - 1)]
              ]
          ]
        );

        $metadata = $endpoint->get(auth()->id()); // Retrieve the user's metadata.
        $metadata = Auth0::json($metadata); // Convert the JSON to a PHP array.

        $color = $metadata['user_metadata']['color'] ?? 'unknown';
        $name = auth()->user()->name;

        return response("Hello {$name}! Your favorite color is {$color}.");
      })->middleware('auth');
      ```
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>
  </SideMenu>
</Recipe>


# Add Login to Your Next.js Application
Source: https://auth0.com/docs/quickstart/webapp/nextjs/index

This guide demonstrates how to integrate Auth0 with any new or existing Next.js application using the Auth0 Next.js v4 SDK (Beta).

<Accordion title="Use AI to integrate Auth0" icon="microchip-ai">
  If you use an AI coding assistant like Claude Code, Cursor, or GitHub Copilot, you can add Auth0 authentication automatically in minutes using [agent skills](https://agentskills.io/home).

  **Install:**

  ```bash theme={null}
  npx skills add auth0/agent-skills --skill auth0-quickstart --skill auth0-nextjs
  ```

  **Then ask your AI assistant:**

  ```text theme={null}
  Add Auth0 authentication to my Next.js app
  ```

  Your AI assistant will automatically create your Auth0 application, fetch credentials, install `@auth0/nextjs-auth0`, create API routes, and set up environment variables. [Full agent skills documentation →](/quickstart/agent-skills)
</Accordion>

<Note>
  **Prerequisites:** Before you begin, ensure you have the following installed:

  * **[Node.js](https://nodejs.org/en/download)** 20 LTS or newer
  * **[npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)** 10+ or **[yarn](https://classic.yarnpkg.com/lang/en/docs/install/)** 1.22+ or **[pnpm](https://pnpm.io/installation)** 8+

  Verify installation: `node --version && npm --version`

  **Next.js Version Compatibility:** This quickstart uses **Next.js 15** which is fully supported by the Auth0 SDK. Next.js 16 is also compatible but requires the `--legacy-peer-deps` flag during installation (see Step 2 for details).
</Note>

## Get Started

This quickstart demonstrates how to add Auth0 authentication to a Next.js application. You'll build a full-stack web application with server-side rendering, secure login functionality, and protected routes using the Auth0 Next.js SDK.

<Steps>
  <Step title="Create a new project">
    Create a new Next.js project for this Quickstart

    ```shellscript theme={null}
    npx create-next-app@15 auth0-nextjs --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" --yes
    ```

    Open the project

    ```shellscript theme={null}
    cd auth0-nextjs
    ```

    <Note>
      We're using `create-next-app@15` to create a Next.js 15 project, which is fully supported by the Auth0 SDK. If you prefer to use Next.js 16 or already have a Next.js 16 project, you'll need to use `--legacy-peer-deps` when installing the Auth0 SDK in Step 2.
    </Note>
  </Step>

  <Step title="Install the Auth0 Next.js SDK">
    ```shellscript theme={null}
    npm install @auth0/nextjs-auth0
    ```

    <Note>
      **For Next.js 16 users:** If you're using Next.js 16 (or upgraded to it), install with the `--legacy-peer-deps` flag:

      ```shellscript theme={null}
      npm install @auth0/nextjs-auth0 --legacy-peer-deps
      ```

      The `--legacy-peer-deps` flag is needed because Next.js 16 support is pending in the SDK. The SDK works correctly with Next.js 16 using this flag.
    </Note>
  </Step>

  <Step title="Create project files">
    Create all necessary directories and files for Auth0 integration:

    <CodeGroup>
      ```shellscript Mac/Linux theme={null}
      mkdir -p src/lib src/components && touch src/lib/auth0.ts src/middleware.ts src/components/LoginButton.tsx src/components/LogoutButton.tsx src/components/Profile.tsx
      ```

      ```powershell Windows theme={null}
      New-Item -ItemType Directory -Force -Path src/lib, src/components
      New-Item -ItemType File -Path src/lib/auth0.ts, src/middleware.ts, src/components/LoginButton.tsx, src/components/LogoutButton.tsx, src/components/Profile.tsx
      ```
    </CodeGroup>
  </Step>

  <Step title="Setup your Auth0 App">
    Next up, you need to create a new app on your Auth0 tenant and add the environment variables to your project.

    You have three options to set up your Auth0 app: use the Quick Setup tool (recommended), run a CLI command, or configure manually via the Dashboard:

    <Tabs>
      <Tab title="Quick Setup (recommended)">
        Create an Auth0 App and copy the pre-filled `.env` file with the right configuration values.

        <CreateInteractiveApp />

        <AuthCodeBlock />
      </Tab>

      <Tab title="CLI">
        Run the following command in your project's root directory to create an Auth0 app and generate a `.env.local` file:

        <CodeGroup>
          ```shellscript Mac theme={null}
          # Install Auth0 CLI (if not already installed)
          brew tap auth0/auth0-cli && brew install auth0

          # Set up Auth0 app and generate .env.local file
          auth0 qs setup --type nextjs -n "My App" -p 3000
          ```

          ```powershell Windows theme={null}
          # Install Auth0 CLI (if not already installed)
          scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git
          scoop install auth0

          # Set up Auth0 app and generate .env.local file
          auth0 qs setup --type nextjs -n "My App" -p 3000
          ```
        </CodeGroup>

        <Note>
          This command will:

          1. Check if you're authenticated (and prompt for login if needed)
          2. Create an Auth0 Regular Web Application configured for `http://localhost:3000`
          3. Generate a `.env.local` file with `AUTH0_DOMAIN`, `AUTH0_CLIENT_ID`, `AUTH0_CLIENT_SECRET`, `AUTH0_SECRET`, and `APP_BASE_URL`
        </Note>
      </Tab>

      <Tab title="Dashboard">
        Create a `.env.local` file on your project's root directory:

        ```shellscript .env.local theme={null}
        AUTH0_DOMAIN=YOUR_AUTH0_APP_DOMAIN
        AUTH0_CLIENT_ID=YOUR_AUTH0_APP_CLIENT_ID
        AUTH0_CLIENT_SECRET=YOUR_AUTH0_APP_CLIENT_SECRET
        AUTH0_SECRET=YOUR_LONG_RANDOM_SECRET_HERE
        APP_BASE_URL=http://localhost:3000
        ```

        **Generate a secure AUTH0\_SECRET:**

        ```shellscript theme={null}
        openssl rand -hex 32
        ```

        Copy the output and replace `YOUR_LONG_RANDOM_SECRET_HERE` in `.env.local`. This must be exactly 64 hexadecimal characters.

        Then configure your Auth0 application:

        Then configure your Auth0 application:

        1. Head to the [Auth0 Dashboard](https://manage.auth0.com/dashboard/)
        2. Click on **Applications** > **Applications** > **Create Application**
        3. In the popup, enter a name for your app, select `Regular Web Application` as the app type and click **Create**
        4. Switch to the **Settings** tab on the Application Details page
        5. Replace `YOUR_AUTH0_APP_DOMAIN`, `YOUR_AUTH0_APP_CLIENT_ID`, and `YOUR_AUTH0_APP_CLIENT_SECRET` in the `.env.local` file with the **Domain**, **Client ID**, and **Client Secret** values from the dashboard

        <Warning>
          **Critical:** If you change the `AUTH0_SECRET` after the app has been running, you must clear your browser cookies for localhost. Old session cookies encrypted with the previous secret will cause a `JWEDecryptionFailed` error.
        </Warning>

        Finally, on the **Settings** tab of your Application Details page, configure the following URLs:

        **Allowed Callback URLs:**

        ```
        http://localhost:3000/auth/callback
        ```

        **Allowed Logout URLs:**

        ```
        http://localhost:3000
        ```

        **Allowed Web Origins:**

        ```
        http://localhost:3000
        ```

        <Info>
          **Allowed Callback URLs** are a critical security measure to ensure users are safely returned to your application after authentication. Without a matching URL, the login process will fail, and users will be blocked by an Auth0 error page instead of accessing your app.

          **Allowed Logout URLs** are essential for providing a seamless user experience upon signing out. Without a matching URL, users will not be redirected back to your application after logout and will instead be left on a generic Auth0 page.

          **Allowed Web Origins** is critical for silent authentication. Without it, users will be logged out when they refresh the page or return to your app later.
        </Info>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Create the Auth0 configuration">
    Add the Auth0 client code to `src/lib/auth0.ts`:

    ```typescript src/lib/auth0.ts lines theme={null}
    import { Auth0Client } from '@auth0/nextjs-auth0/server';

    export const auth0 = new Auth0Client();
    ```
  </Step>

  <Step title="Add middleware">
    Add the middleware code to `src/middleware.ts`:

    ```typescript src/middleware.ts expandable lines theme={null}
    import type { NextRequest } from "next/server";
    import { auth0 } from "./lib/auth0";

    export async function middleware(request: NextRequest) {
      return await auth0.middleware(request);
    }

    export const config = {
      matcher: [
        /*
         * Match all request paths except for the ones starting with:
         * - _next/static (static files)
         * - _next/image (image optimization files)
         * - favicon.ico, sitemap.xml, robots.txt (metadata files)
         */
        "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
      ],
    };
    ```

    <Note>
      Since we're using a `src/` directory, the `middleware.ts` file is created inside `src/`. If you're not using a `src/` directory, create it in the project root instead.
    </Note>

    <Info>
      This middleware automatically mounts the following authentication routes:

      * `/auth/login` - Login route
      * `/auth/logout` - Logout route
      * `/auth/callback` - Callback route
      * `/auth/profile` - User profile route
      * `/auth/access-token` - Access token route
      * `/auth/backchannel-logout` - Backchannel logout route
    </Info>
  </Step>

  <Step title="Create Login, Logout and Profile Components">
    Add the component code to the files created in Step 3:

    <AuthCodeGroup>
      ```typescript src/components/LoginButton.tsx lines theme={null}
      "use client";

      export default function LoginButton() {
        return (
          <a
            href="/auth/login"
            className="button login"
          >
            Log In
          </a>
        );
      }
      ```

      ```typescript src/components/LogoutButton.tsx lines theme={null}
      "use client";

      export default function LogoutButton() {
        return (
          <a
            href="/auth/logout"
            className="button logout"
          >
            Log Out
          </a>
        );
      }
      ```

      ```typescript src/components/Profile.tsx expandable lines theme={null}
      "use client";

      import { useUser } from "@auth0/nextjs-auth0/client";

      export default function Profile() {
        const { user, isLoading } = useUser();

        if (isLoading) {
          return (
            <div className="loading-state">
              <div className="loading-text">Loading user profile...</div>
            </div>
          );
        }

        if (!user) {
          return null;
        }

        return (
          <div className="profile-card action-card">
            <img
              src={user.picture || `data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='100' height='100' viewBox='0 0 100 100'%3E%3Ccircle cx='50' cy='50' r='50' fill='%2363b3ed'/%3E%3Cpath d='M50 45c7.5 0 13.64-6.14 13.64-13.64S57.5 17.72 50 17.72s-13.64 6.14-13.64 13.64S42.5 45 50 45zm0 6.82c-9.09 0-27.28 4.56-27.28 13.64v3.41c0 1.88 1.53 3.41 3.41 3.41h47.74c1.88 0 3.41-1.53 3.41-3.41v-3.41c0-9.08-18.19-13.64-27.28-13.64z' fill='%23fff'/%3E%3C/svg%3E`}
              alt={user.name || 'User profile'}
              className="profile-picture"
              onError={(e) => {
                const target = e.target as HTMLImageElement;
                target.src = `data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='100' height='100' viewBox='0 0 100 100'%3E%3Ccircle cx='50' cy='50' r='50' fill='%2363b3ed'/%3E%3Cpath d='M50 45c7.5 0 13.64-6.14 13.64-13.64S57.5 17.72 50 17.72s-13.64 6.14-13.64 13.64S42.5 45 50 45zm0 6.82c-9.09 0-27.28 4.56-27.28 13.64v3.41c0 1.88 1.53 3.41 3.41 3.41h47.74c1.88 0 3.41-1.53 3.41-3.41v-3.41c0-9.08-18.19-13.64-27.28-13.64z' fill='%23fff'/%3E%3C/svg%3E`;
              }}
            />
            <h2 className="profile-name">{user.name}</h2>
            <p className="profile-email">{user.email}</p>
          </div>
        );
      }
      ```
    </AuthCodeGroup>
  </Step>

  <Step title="Update your main page">
    Replace `src/app/page.tsx` with:

    ```typescript src/app/page.tsx expandable lines theme={null}
    import { auth0 } from "@/lib/auth0";
    import LoginButton from "@/components/LoginButton";
    import LogoutButton from "@/components/LogoutButton";
    import Profile from "@/components/Profile";

    export default async function Home() {
      const session = await auth0.getSession();
      const user = session?.user;

      return (
        <div className="app-container">
          <div className="main-card-wrapper">
            <img
              src="https://cdn.auth0.com/quantum-assets/dist/latest/logos/auth0/auth0-lockup-en-ondark.png"
              alt="Auth0 Logo"
              className="auth0-logo"
            />
            <h1 className="main-title">Next.js + Auth0</h1>
            
            <div className="action-card">
              {user ? (
                <div className="logged-in-section">
                  <p className="logged-in-message">✅ Successfully logged in!</p>
                  <Profile />
                  <LogoutButton />
                </div>
              ) : (
                <>
                  <p className="action-text">
                    Welcome! Please log in to access your protected content.
                  </p>
                  <LoginButton />
                </>
              )}
            </div>
          </div>
        </div>
      );
    }
    ```
  </Step>

  <Step title="Update layout with Auth0Provider (OPTIONAL)">
    Update `src/app/layout.tsx` to wrap your app with the `Auth0Provider`:

    ```typescript src/app/layout.tsx lines theme={null}
    import type { Metadata } from "next";
    import { Auth0Provider } from "@auth0/nextjs-auth0/client";
    import "./globals.css";

    export const metadata: Metadata = {
      title: "Auth0 Next.js App",
      description: "Next.js app with Auth0 authentication",
    };

    export default function RootLayout({
      children,
    }: {
      children: React.ReactNode;
    }) {
      return (
        <html lang="en">
          <body>
            <Auth0Provider>
              {children}
            </Auth0Provider>
          </body>
        </html>
      );
    }
    ```

    <Note>
      In v4, the Auth0Provider is **optional**. You only need it if you want to pass an initial user during server rendering to be available to the `useUser()` hook.
    </Note>
  </Step>

  <Step title="Add styling">
    Replace `src/app/globals.css` with modern Auth0-branded styling:

    ```css src/app/globals.css expandable lines theme={null}
    @import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap');
    @tailwind base;
    @tailwind components;
    @tailwind utilities;

    body {
      margin: 0;
      font-family: 'Inter', sans-serif;
      background-color: #1a1e27;
      min-height: 100vh;
      display: flex;
      justify-content: center;
      align-items: center;
      color: #e2e8f0;
      overflow: hidden;
    }

    .app-container {
      display: flex;
      flex-direction: column;
      justify-content: center;
      align-items: center;
      min-height: 100vh;
      width: 100%;
      padding: 1rem;
      box-sizing: border-box;
    }

    .loading-state, .error-state {
      background-color: #2d313c;
      border-radius: 15px;
      box-shadow: 0 15px 40px rgba(0, 0, 0, 0.4);
      padding: 3rem;
      text-align: center;
    }

    .loading-text {
      font-size: 1.8rem;
      font-weight: 500;
      color: #a0aec0;
      animation: pulse 1.5s infinite ease-in-out;
    }

    .main-card-wrapper {
      background-color: #262a33;
      border-radius: 20px;
      box-shadow: 0 20px 60px rgba(0, 0, 0, 0.6), 0 0 0 1px rgba(255, 255, 255, 0.05);
      display: flex;
      flex-direction: column;
      align-items: center;
      gap: 2rem;
      padding: 3rem;
      max-width: 500px;
      width: 90%;
      animation: fadeInScale 0.8s ease-out forwards;
    }

    .auth0-logo {
      width: 160px;
      margin-bottom: 1.5rem;
      opacity: 0;
      animation: slideInDown 1s ease-out forwards 0.2s;
    }

    .main-title {
      font-size: 2.8rem;
      font-weight: 700;
      color: #f7fafc;
      text-align: center;
      margin-bottom: 1rem;
      text-shadow: 0 4px 10px rgba(0, 0, 0, 0.3);
      opacity: 0;
      animation: fadeIn 1s ease-out forwards 0.4s;
    }

    .action-card {
      background-color: #2d313c;
      border-radius: 15px;
      box-shadow: inset 0 2px 5px rgba(0, 0, 0, 0.3), 0 5px 15px rgba(0, 0, 0, 0.3);
      padding: 2.5rem;
      display: flex;
      flex-direction: column;
      align-items: center;
      gap: 1.8rem;
      width: calc(100% - 2rem);
      opacity: 0;
      animation: fadeIn 1s ease-out forwards 0.6s;
    }

    .action-text {
      font-size: 1.25rem;
      color: #cbd5e0;
      text-align: center;
      line-height: 1.6;
      font-weight: 400;
    }

    .button {
      padding: 1.1rem 2.8rem;
      font-size: 1.2rem;
      font-weight: 600;
      border-radius: 10px;
      border: none;
      cursor: pointer;
      transition: all 0.3s cubic-bezier(0.25, 0.8, 0.25, 1);
      box-shadow: 0 8px 20px rgba(0, 0, 0, 0.4);
      text-transform: uppercase;
      letter-spacing: 0.08em;
      outline: none;
    }

    .button:focus {
      box-shadow: 0 0 0 4px rgba(99, 179, 237, 0.5);
    }

    .button.login {
      background-color: #63b3ed;
      color: #1a1e27;
    }

    .button.login:hover {
      background-color: #4299e1;
      transform: translateY(-5px) scale(1.03);
      box-shadow: 0 12px 25px rgba(0, 0, 0, 0.5);
    }

    .button.logout {
      background-color: #fc8181;
      color: #1a1e27;
    }

    .button.logout:hover {
      background-color: #e53e3e;
      transform: translateY(-5px) scale(1.03);
      box-shadow: 0 12px 25px rgba(0, 0, 0, 0.5);
    }

    .logged-in-section {
      display: flex;
      flex-direction: column;
      align-items: center;
      gap: 1.5rem;
      width: 100%;
    }

    .logged-in-message {
      font-size: 1.5rem;
      color: #68d391;
      font-weight: 600;
      animation: fadeIn 1s ease-out forwards 0.8s;
    }

    .profile-card {
      padding: 2.2rem;
      animation: scaleIn 0.8s ease-out forwards 1.2s;
    }

    .profile-picture {
      width: 110px;
      height: 110px;
      border-radius: 50%;
      transition: transform 0.3s ease-in-out;
      object-fit: cover;
    }

    .profile-picture:hover {
      transform: scale(1.05);
    }

    .profile-name {
      font-size: 2rem;
      margin-top: 0.5rem;
    }

    .profile-email {
      font-size: 1.15rem;
      text-align: center;
    }

    @keyframes fadeIn {
      from { opacity: 0; }
      to { opacity: 1; }
    }

    @keyframes fadeInScale {
      from { opacity: 0; transform: scale(0.95); }
      to { opacity: 1; transform: scale(1); }
    }

    @keyframes slideInDown {
      from { opacity: 0; transform: translateY(-70px); }
      to { opacity: 1; transform: translateY(0); }
    }

    @keyframes pulse {
      0%, 100% { opacity: 1; }
      50% { opacity: 0.6; }
    }

    @keyframes scaleIn {
      from { opacity: 0; transform: scale(0.8); }
      to { opacity: 1; transform: scale(1); }
    }

    @media (max-width: 600px) {
      .main-card-wrapper {
        padding: 2rem;
        gap: 1.5rem;
      }
      
      .main-title {
        font-size: 2.2rem;
      }
      
      .button {
        padding: 0.9rem 2rem;
        font-size: 1rem;
      }
      
      .auth0-logo {
        width: 120px;
      }
    }
    ```
  </Step>

  <Step title="Run your app">
    ```shellscript theme={null}
    npm run dev
    ```

    <Info>
      Your app will be available at [http://localhost:3000](http://localhost:3000). The Auth0 SDK v4 automatically mounts authentication routes at `/auth/*` (not `/api/auth/*` like in v3).

      If port 3000 is in use, run: `npm run dev -- --port 3001` and update your Auth0 app's callback URLs to `http://localhost:3001`
    </Info>
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a fully functional Auth0 login page running on your [localhost](http://localhost:3000/)
</Check>

***

## Troubleshooting

<Accordion title="JWEDecryptionFailed Error">
  If you see a `JWEDecryptionFailed: decryption operation failed` error, this is caused by either an invalid `AUTH0_SECRET` or an old session cookie encrypted with a different secret.

  **Solution:**

  1. Generate a new secret using:

  ```shellscript theme={null}
  openssl rand -hex 32
  ```

  2. Update your `.env.local` file:

  ```
  AUTH0_SECRET=<your-new-64-character-hex-string>
  ```

  3. **Clear your browser cookies** for `localhost:3000`:
     * Chrome/Edge: Press `F12` → Application tab → Cookies → Delete all cookies for localhost
     * Firefox: Press `F12` → Storage tab → Cookies → Delete all cookies for localhost
     * Safari: Develop menu → Show Web Inspector → Storage tab → Cookies → Delete all
  4. Restart your dev server:

  ```shellscript theme={null}
  npm run dev
  ```

  The secret must be exactly 32 bytes (64 hexadecimal characters). The error occurs when the app tries to decrypt an existing session cookie that was encrypted with a different secret.
</Accordion>

<Accordion title="404 Error on /auth/login">
  If clicking login takes you to a 404 page, check these common issues:

  1. **Middleware location:** Ensure `src/middleware.ts` exists in the correct location
  2. **Middleware code:** Verify the middleware matches the code in Step 6
  3. **Restart server:** After creating middleware, restart the dev server
  4. **Check imports:** Make sure `import { auth0 } from "./lib/auth0"` path is correct
</Accordion>

<Accordion title="Module Not Found Errors">
  If you see "Cannot find module '@/components/LoginButton'" or similar errors:

  1. **Verify files exist:** Check that all files from Step 3 were created
  2. **Check paths:** Ensure components are in `src/components/` directory
  3. **Restart TypeScript:** Press `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows) and run "TypeScript: Restart TS Server"
  4. **Verify imports:** Make sure you're using `@/components/*` (not `~/components/*`)
</Accordion>

***

## Advanced Usage

<Accordion title="Important v4 Changes">
  This quickstart uses **Auth0 Next.js SDK v4**, which has significant changes from v3:

  * **No dynamic route handlers needed** - Authentication routes are auto-mounted by middleware
  * **Simplified client setup** - `new Auth0Client()` reads environment variables automatically
  * **New route paths** - Routes are at `/auth/*` instead of `/api/auth/*`
  * **Required middleware** - All authentication functionality goes through middleware
  * **Use `<a>` tags** - Navigation must use `<a href="/auth/login">` instead of buttons with onClick

  ### Authentication Routes

  The SDK automatically mounts these routes via middleware:

  | Route                      | Purpose                   |
  | -------------------------- | ------------------------- |
  | `/auth/login`              | Initiate login            |
  | `/auth/logout`             | Logout user               |
  | `/auth/callback`           | Handle Auth0 callback     |
  | `/auth/profile`            | Get user profile          |
  | `/auth/access-token`       | Get access token          |
  | `/auth/backchannel-logout` | Handle backchannel logout |

  <Note>
    If you're experiencing 404 errors on these routes, ensure that:

    1. The `middleware.ts` file is created in the correct location (project root, or inside `src/` if using a `src/` directory)
    2. The middleware is properly configured with the matcher pattern shown in Step 5
    3. The development server was restarted after creating the middleware file
  </Note>
</Accordion>

<Accordion title="Server-Side Authentication">
  The Auth0 Next.js SDK v4 supports both App Router and Pages Router patterns. Here are some common server-side patterns:

  <Tabs>
    <Tab title="App Router - Server Component">
      ```typescript app/protected/page.tsx theme={null}
      import { auth0 } from "@/lib/auth0";
      import { redirect } from "next/navigation";

      export default async function ProtectedPage() {
        const session = await auth0.getSession();
        
        if (!session) {
          redirect('/auth/login');
        }

        return (
          <div>
            <h1>Protected Content</h1>
            <p>Welcome, {session.user.name}!</p>
          </div>
        );
      }
      ```
    </Tab>

    <Tab title="App Router - API Route">
      ```typescript app/api/protected/route.ts theme={null}
      import { auth0 } from "@/lib/auth0";
      import { NextRequest, NextResponse } from "next/server";

      export async function GET() {
        const session = await auth0.getSession();
        
        if (!session) {
          return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
        }
        
        return NextResponse.json({
          message: "This is a protected API route",
          user: session.user
        });
      }
      ```
    </Tab>

    <Tab title="Pages Router - Page">
      ```typescript pages/protected.tsx theme={null}
      import { auth0 } from "@/lib/auth0";
      import { GetServerSideProps } from "next";

      export default function ProtectedPage({ user }: { user: any }) {
        return (
          <div>
            <h1>Protected Content</h1>
            <p>Welcome, {user.name}!</p>
          </div>
        );
      }

      export const getServerSideProps: GetServerSideProps = auth0.withPageAuthRequired();
      ```
    </Tab>
  </Tabs>
</Accordion>

<Accordion title="Client-Side Authentication">
  For client-side authentication state, use the `useUser` hook:

  ```typescript components/UserProfile.tsx theme={null}
  "use client";

  import { useUser } from "@auth0/nextjs-auth0";

  export default function UserProfile() {
    const { user, error, isLoading } = useUser();

    if (isLoading) return <div>Loading...</div>;
    if (error) return <div>Error: {error.message}</div>;
    if (!user) return <div>Not logged in</div>;

    return (
      <div>
        <h2>{user.name}</h2>
        <p>{user.email}</p>
        <img src={user.picture} alt="Profile" />
      </div>
    );
  }
  ```
</Accordion>

<Accordion title="Protecting API Routes">
  For API route protection, use the `withApiAuthRequired` method:

  ```typescript app/api/protected/route.ts theme={null}
  import { auth0 } from "@/lib/auth0";

  export const GET = auth0.withApiAuthRequired(async function handler() {
    const session = await auth0.getSession();
    
    return Response.json({
      message: "This is a protected API route",
      user: session?.user
    });
  });
  ```
</Accordion>


# NGINX Plus
Source: https://auth0.com/docs/quickstart/webapp/nginx-plus/interactive

This tutorial demonstrates how to use the nginx-openid-connect module to add authentication and authorization to your NGINX server.

<Recipe>
  <Content>
    This tutorial demonstrates how to use the nginx-openid-connect module to add authentication and authorization to
    your NGINX server. We recommend that you log in to follow this quickstart with examples configured for your account.

    <Section title={sections[0].title}>
      This tutorial and seed project have been tested with the following:

      * NGINX Plus R24
    </Section>

    <Section title={sections[1].title}>
      First, you need to install the `nginx-plus-module-njs` module for NGINX Plus.

      Follow the dynamic module installation guide to install packages in your host OS.

      For Linux distributions that use `yum` package manager, you can install the module like so:

      ```sh lines theme={null}
      sudo yum install nginx-plus-module-njs jq
      ```

      Once you've installed it, you need to enable it for NGINX by adding the following line near the top of your
      `/etc/nginx/nginx.conf` file:

      ```sh lines theme={null}
      load_module modules/ngx_http_js_module.so;
      ```
    </Section>

    <Section title={sections[2].title}>
      Clone the `nginx-openid-connect` repository. This repository comes with a template configuration.

      ```sh lines theme={null}
      git clone https://github.com/nginxinc/nginx-openid-connect
      ```
    </Section>

    <Section title={sections[3].title}>
      Run the configure.sh script inside the nginx-openid-connect folder to populate the template configuration for
      your Auth0 application:

      ```sh lines theme={null}
      ./configure.sh --auth_jwt_key request \
      --client_id {yourClientId} \
      --pkce_enable \
      https://{yourDomain}/.well-known/openid-configuration
      ```

      Next, add your [tenant’s logout URL](https://auth0.com/docs/api/authentication#auth0-logout) to your
      `openid_connect_configuration.conf` file.
    </Section>

    <Section title={sections[4].title}>
      Add the `Accept-Encoding` header and set the value to `gzip` in your
      `openid_connect.server_conf` file.
    </Section>

    <Section title={sections[5].title}>
      Copy your four configuration files to the `conf.d` folder.

      ```sh lines theme={null}
      sudo cp openid_connect.js \ 
      frontend.conf \
      openid_connect_configuration.conf \
      openid_connect.server_conf /etc/nginx/conf.d
      ```
    </Section>

    <Section title={sections[6].title}>
      In the Auth0 Dashboard:

      1. Go to **Applications** > **Applications**, and then select your application from the list.
      2. Switch to the **Settings** view.
      3. In the **Application URIs** section, add `https://{yourDomain}/_codexch`
         to **Allowed Callback URLs**.
      4. Switch to the **Credentials** view.

      In the **Application Authentication** section, set **Authentication Method** to None.
    </Section>

    <Section title={sections[7].title}>
      Add additional headers from the ID token (JWT) to the upstream target in your
      `/etc/nginx/conf.d/frontend.conf` file.
    </Section>

    ## Next Steps

    Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.

    This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:

    * [Auth0 Dashboard](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq) - Learn how to configure and manage your Auth0 tenant and applications
    * [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
  </Content>

  <SideMenu>
    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```conf nginx.conf lines theme={null}
        ...
        load_module modules/ngx_http_js_module.so;
        ...
        ```

        ```conf openid_connection_configuration.conf lines theme={null}
        map $host $oidc_logout_redirect {
            default "https://{yourDomain}/v2/logout";
        }
        ```

        ```conf openid_connect.server.conf lines theme={null}
        location = /_jwks_uri {
            internal;
            ...
            proxy_set_header    Content-Length "";           
            proxy_set_header    Accept-Encoding "gzip";
            ...
        }

        location = /_token {
            internal;
            ...
            proxy_set_header    Content-Type "application/x-www-form-urlencoded";
            proxy_set_header    Accept-Encoding "gzip";
            ...
        }
        ```

        ```conf frontend.conf lines  theme={null}
        # auth_jwt_claim_set $claim_name https://namespace/key;

        server {
            include conf.d/openid_connect.server_conf; # Authorization code flow and Relying Party processing
            error_log /var/log/nginx/error.log debug;  # Reduce severity level as required

            listen 8010; # Use SSL/TLS in production

            location / {
                # This site is protected with OpenID Connect
                auth_jwt "" token=$session_jwt;
                error_page 401 = @do_oidc_flow;

                #auth_jwt_key_file $oidc_jwt_keyfile; # Enable when using filename
                auth_jwt_key_request /_jwks_uri; # Enable when using URL

                # Successfully authenticated users are proxied to the backend,
                # with 'sub' claim passed as HTTP header
                proxy_set_header username $jwt_claim_sub;
                proxy_set_header x-email $jwt_claim_email;
                #proxy_set_header x-custom $claim_name;             # namespaced claim

                proxy_pass http://my_backend; # The backend site/app

                access_log /var/log/nginx/access.log main_jwt;
            }
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```conf openid_connection_configuration.conf lines theme={null}
        map $host $oidc_logout_redirect {
            default "https://{yourDomain}/v2/logout";
        }
        ```

        ```conf nginx.conf lines theme={null}
        ...
        load_module modules/ngx_http_js_module.so;
        ...
        ```

        ```conf openid_connect.server.conf lines theme={null}
        location = /_jwks_uri {
            internal;
            ...
            proxy_set_header    Content-Length "";           
            proxy_set_header    Accept-Encoding "gzip";
            ...
        }

        location = /_token {
            internal;
            ...
            proxy_set_header    Content-Type "application/x-www-form-urlencoded";
            proxy_set_header    Accept-Encoding "gzip";
            ...
        }
        ```

        ```conf frontend.conf lines  theme={null}
        # auth_jwt_claim_set $claim_name https://namespace/key;

        server {
            include conf.d/openid_connect.server_conf; # Authorization code flow and Relying Party processing
            error_log /var/log/nginx/error.log debug;  # Reduce severity level as required

            listen 8010; # Use SSL/TLS in production

            location / {
                # This site is protected with OpenID Connect
                auth_jwt "" token=$session_jwt;
                error_page 401 = @do_oidc_flow;

                #auth_jwt_key_file $oidc_jwt_keyfile; # Enable when using filename
                auth_jwt_key_request /_jwks_uri; # Enable when using URL

                # Successfully authenticated users are proxied to the backend,
                # with 'sub' claim passed as HTTP header
                proxy_set_header username $jwt_claim_sub;
                proxy_set_header x-email $jwt_claim_email;
                #proxy_set_header x-custom $claim_name;             # namespaced claim

                proxy_pass http://my_backend; # The backend site/app

                access_log /var/log/nginx/access.log main_jwt;
            }
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```conf openid_connect.server.conf lines theme={null}
        location = /_jwks_uri {
            internal;
            ...
            proxy_set_header    Content-Length "";           
            proxy_set_header    Accept-Encoding "gzip";
            ...
        }

        location = /_token {
            internal;
            ...
            proxy_set_header    Content-Type "application/x-www-form-urlencoded";
            proxy_set_header    Accept-Encoding "gzip";
            ...
        }
        ```

        ```conf nginx.conf lines theme={null}
        ...
        load_module modules/ngx_http_js_module.so;
        ...
        ```

        ```conf openid_connection_configuration.conf lines theme={null}
        map $host $oidc_logout_redirect {
            default "https://{yourDomain}/v2/logout";
        }
        ```

        ```conf frontend.conf lines  theme={null}
        # auth_jwt_claim_set $claim_name https://namespace/key;

        server {
            include conf.d/openid_connect.server_conf; # Authorization code flow and Relying Party processing
            error_log /var/log/nginx/error.log debug;  # Reduce severity level as required

            listen 8010; # Use SSL/TLS in production

            location / {
                # This site is protected with OpenID Connect
                auth_jwt "" token=$session_jwt;
                error_page 401 = @do_oidc_flow;

                #auth_jwt_key_file $oidc_jwt_keyfile; # Enable when using filename
                auth_jwt_key_request /_jwks_uri; # Enable when using URL

                # Successfully authenticated users are proxied to the backend,
                # with 'sub' claim passed as HTTP header
                proxy_set_header username $jwt_claim_sub;
                proxy_set_header x-email $jwt_claim_email;
                #proxy_set_header x-custom $claim_name;             # namespaced claim

                proxy_pass http://my_backend; # The backend site/app

                access_log /var/log/nginx/access.log main_jwt;
            }
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```conf frontend.conf lines  theme={null}
        # auth_jwt_claim_set $claim_name https://namespace/key;

        server {
            include conf.d/openid_connect.server_conf; # Authorization code flow and Relying Party processing
            error_log /var/log/nginx/error.log debug;  # Reduce severity level as required

            listen 8010; # Use SSL/TLS in production

            location / {
                # This site is protected with OpenID Connect
                auth_jwt "" token=$session_jwt;
                error_page 401 = @do_oidc_flow;

                #auth_jwt_key_file $oidc_jwt_keyfile; # Enable when using filename
                auth_jwt_key_request /_jwks_uri; # Enable when using URL

                # Successfully authenticated users are proxied to the backend,
                # with 'sub' claim passed as HTTP header
                proxy_set_header username $jwt_claim_sub;
                proxy_set_header x-email $jwt_claim_email;
                #proxy_set_header x-custom $claim_name;             # namespaced claim

                proxy_pass http://my_backend; # The backend site/app

                access_log /var/log/nginx/access.log main_jwt;
            }
        }
        ```

        ```conf nginx.conf lines theme={null}
        ...
        load_module modules/ngx_http_js_module.so;
        ...
        ```

        ```conf openid_connection_configuration.conf lines theme={null}
        map $host $oidc_logout_redirect {
            default "https://{yourDomain}/v2/logout";
        }
        ```

        ```conf openid_connect.server.conf lines theme={null}
        location = /_jwks_uri {
            internal;
            ...
            proxy_set_header    Content-Length "";           
            proxy_set_header    Accept-Encoding "gzip";
            ...
        }

        location = /_token {
            internal;
            ...
            proxy_set_header    Content-Type "application/x-www-form-urlencoded";
            proxy_set_header    Accept-Encoding "gzip";
            ...
        }
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>
  </SideMenu>
</Recipe>


# Add Login to Your Nuxt.js Application
Source: https://auth0.com/docs/quickstart/webapp/nuxt/index

This guide demonstrates how to integrate Auth0, add authentication, and display user profile information in a Single-Page Application (SPA) that uses Nuxt.js, using the Auth0 Nuxt.js SDK.

<Callout icon="pencil">
  This Quickstart is currently in **Beta**. We'd love to hear your feedback!
</Callout>

<Accordion title="Use AI to integrate Auth0" icon="microchip-ai">
  If you use an AI coding assistant like Claude Code, Cursor, or GitHub Copilot, you can add Auth0 authentication automatically in minutes using [agent skills](https://agentskills.io/home).

  **Install:**

  ```bash theme={null}
  npx skills add https://github.com/auth0/agent-skills --skill auth0-nuxt
  ```

  **Then ask your AI assistant:**

  ```text theme={null}
  Add Auth0 authentication to my Nuxt app
  ```

  Your AI assistant will automatically create your Auth0 application, fetch credentials, install `@auth0/auth0-nuxt`, configure the module, and set up your routes. [Full agent skills documentation →](/quickstart/agent-skills)
</Accordion>

<Note>
  **Prerequisites:** Before you begin, ensure you have the following installed:

  * **[Node.js](https://nodejs.org/en/download)** 20 LTS or newer
  * **[npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)** 10+ or **[yarn](https://classic.yarnpkg.com/lang/en/docs/install/)** 1.22+ or **[pnpm](https://pnpm.io/installation)** 8+
  * **[jq](https://jqlang.org/)** - Required for Auth0 CLI setup

  **Nuxt Version Compatibility:** This quickstart works with **Nuxt 3.x** out of the box. For **Nuxt 4.x**, ensure you're using Nuxt 4.2+.
</Note>

## Get Started

This quickstart demonstrates how to add Auth0 authentication to a Nuxt.js application. You'll build a secure single-page app with login, logout, and user profile features using the Auth0 Nuxt SDK.

<Steps>
  <Step title="Create a new project">
    Create a new Nuxt project for this Quickstart

    ```shellscript theme={null}
    npx nuxi@latest init auth0-nuxt-app
    ```

    Open the project

    ```shellscript theme={null}
    cd auth0-nuxt-app
    ```
  </Step>

  <Step title="Install the Auth0 Nuxt SDK">
    ```shellscript theme={null}
    npm add @auth0/auth0-nuxt && npm install
    ```
  </Step>

  <Step title="Setup your Auth0 App">
    Next up, you need to create a new app on your Auth0 tenant and add the environment variables to your project.

    You can choose to do this automatically by running a CLI command or do it manually via the Dashboard:

    <Tabs>
      <Tab title="CLI">
        Run the following shell command on your project's root directory to create an Auth0 app and generate a `.env` file:

        <CodeGroup>
          ```shellscript Mac theme={null}
          AUTH0_APP_NAME="My Nuxt App" && brew tap auth0/auth0-cli && brew install auth0 && auth0 login --no-input && auth0 apps create -n "${AUTH0_APP_NAME}" -t regular -c http://localhost:3000/auth/callback -l http://localhost:3000 -o http://localhost:3000 --reveal-secrets --json > auth0-app-details.json && CLIENT_ID=$(jq -r '.client_id' auth0-app-details.json) && CLIENT_SECRET=$(jq -r '.client_secret' auth0-app-details.json) && DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name') && echo "NUXT_AUTH0_DOMAIN=${DOMAIN}" > .env && echo "NUXT_AUTH0_CLIENT_ID=${CLIENT_ID}" >> .env && echo "NUXT_AUTH0_CLIENT_SECRET=${CLIENT_SECRET}" >> .env && echo "NUXT_AUTH0_SESSION_SECRET=$(openssl rand -hex 64)" >> .env && echo "NUXT_AUTH0_APP_BASE_URL=http://localhost:3000" >> .env && rm auth0-app-details.json && echo ".env file created with your Auth0 details:" && cat .env
          ```

          ```shellscript Windows theme={null}
          $AppName = "My Nuxt App"; winget install Auth0.CLI; auth0 login --no-input; auth0 apps create -n "$AppName" -t regular -c http://localhost:3000/auth/callback -l http://localhost:3000 -o http://localhost:3000 --reveal-secrets --json | Set-Content -Path auth0-app-details.json; $ClientId = (Get-Content -Raw auth0-app-details.json | ConvertFrom-Json).client_id; $ClientSecret = (Get-Content -Raw auth0-app-details.json | ConvertFrom-Json).client_secret; $Domain = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name; Set-Content -Path .env -Value "NUXT_AUTH0_DOMAIN=$Domain"; Add-Content -Path .env -Value "NUXT_AUTH0_CLIENT_ID=$ClientId"; Add-Content -Path .env -Value "NUXT_AUTH0_CLIENT_SECRET=$ClientSecret"; $SessionSecret = -join ((1..128) | ForEach {'{0:X}' -f (Get-Random -Max 16)}); Add-Content -Path .env -Value "NUXT_AUTH0_SESSION_SECRET=$SessionSecret"; Add-Content -Path .env -Value "NUXT_AUTH0_APP_BASE_URL=http://localhost:3000"; Remove-Item auth0-app-details.json; Write-Output ".env file created with your Auth0 details:"; Get-Content .env
          ```
        </CodeGroup>
      </Tab>

      <Tab title="Dashboard">
        Before you start, create a `.env` file on your project's root directory

        ```shellscript .env theme={null}
        NUXT_AUTH0_DOMAIN=YOUR_AUTH0_APP_DOMAIN
        NUXT_AUTH0_CLIENT_ID=YOUR_AUTH0_APP_CLIENT_ID
        NUXT_AUTH0_CLIENT_SECRET=YOUR_AUTH0_APP_CLIENT_SECRET
        NUXT_AUTH0_SESSION_SECRET=YOUR_SESSION_SECRET
        NUXT_AUTH0_APP_BASE_URL=http://localhost:3000
        ```

        1. Head to the [Auth0 Dashboard ](https://manage.auth0.com/dashboard/)
        2. Click on **Applications**  > **Applications** > **Create Application**
        3. In the popup, enter a name for your app, select `Regular Web Application` as the app type and click **Create**
        4. Switch to the **Settings** tab on the Application Details page
        5. Replace the values in the `.env` file with the **Domain**, **Client ID**, and **Client Secret** values from the dashboard
        6. Generate a session secret by running: `openssl rand -hex 64` and use it for `NUXT_AUTH0_SESSION_SECRET`

        Finally, on the **Settings** tab of your Application Details page, configure the following URLs:

        **Allowed Callback URLs:**

        ```
        http://localhost:3000/auth/callback
        ```

        **Allowed Logout URLs:**

        ```
        http://localhost:3000
        ```

        **Allowed Web Origins:**

        ```
        http://localhost:3000
        ```

        <Info>
          **Allowed Callback URLs** are a critical security measure to ensure users are safely returned to your application after authentication. Without a matching URL, the login process will fail, and users will be blocked by an Auth0 error page instead of accessing your app.\
          \
          **Allowed Logout URLs** are essential for providing a seamless user experience upon signing out. Without a matching URL, users will not be redirected back to your application after logout and will instead be left on a generic Auth0 page.

          **Allowed Web Origins** is critical for silent authentication. Without it, users will be logged out when they refresh the page or return to your app later.
        </Info>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure the Auth0 Nuxt module">
    ```typescript nuxt.config.ts {3,4,5,6,7,8,9,10,11,12,13} lines theme={null}
    export default defineNuxtConfig({
      devtools: { enabled: true },
      modules: ['@auth0/auth0-nuxt'],
      runtimeConfig: {
        auth0: {
          domain: process.env.NUXT_AUTH0_DOMAIN,
          clientId: process.env.NUXT_AUTH0_CLIENT_ID,
          clientSecret: process.env.NUXT_AUTH0_CLIENT_SECRET,
          sessionSecret: process.env.NUXT_AUTH0_SESSION_SECRET,
          appBaseUrl: process.env.NUXT_AUTH0_APP_BASE_URL,
        },
      },
    })
    ```
  </Step>

  <Step title="Create Login, Logout and Profile Components">
    Create files

    ```shellscript theme={null}
    mkdir -p app/components && touch app/components/LoginButton.vue && touch app/components/LogoutButton.vue && touch app/components/UserProfile.vue
    ```

    And add the following code snippets

    <CodeGroup>
      ```vue app/components/LoginButton.vue expandable lines theme={null}
      <template>
       <a 
          href="/auth/login" 
          class="button login"
        >
          Log In
        </a>
      </template>

      <style scoped>
      .button {
        padding: 1.1rem 2.8rem;
        font-size: 1.2rem;
        font-weight: 600;
        border-radius: 10px;
        border: none;
        cursor: pointer;
        transition: all 0.3s cubic-bezier(0.25, 0.8, 0.25, 1);
        box-shadow: 0 8px 20px rgba(0, 0, 0, 0.4);
        text-transform: uppercase;
        letter-spacing: 0.08em;
        outline: none;
      }

      .button:focus {
        box-shadow: 0 0 0 4px rgba(99, 179, 237, 0.5);
      }

      .button.login {
        background-color: #63b3ed;
        color: #1a1e27;
      }

      .button.login:hover:not(:disabled) {
        background-color: #4299e1;
        transform: translateY(-5px) scale(1.03);
        box-shadow: 0 12px 25px rgba(0, 0, 0, 0.5);
      }

      .button:disabled {
        opacity: 0.7;
        cursor: not-allowed;
        transform: none;
      }
      </style>
      ```

      ```vue app/components/LogoutButton.vue expandable lines theme={null}
      <template>
       <a
          href="/auth/logout"
          class="button logout"
        >
          Log Out
        </a>
      </template>

      <style scoped>
      .button {
        padding: 1.1rem 2.8rem;
        font-size: 1.2rem;
        font-weight: 600;
        border-radius: 10px;
        border: none;
        cursor: pointer;
        transition: all 0.3s cubic-bezier(0.25, 0.8, 0.25, 1);
        box-shadow: 0 8px 20px rgba(0, 0, 0, 0.4);
        text-transform: uppercase;
        letter-spacing: 0.08em;
        outline: none;
      }

      .button:focus {
        box-shadow: 0 0 0 4px rgba(99, 179, 237, 0.5);
      }

      .button.logout {
        background-color: #fc8181;
        color: #1a1e27;
      }

      .button.logout:hover:not(:disabled) {
        background-color: #e53e3e;
        transform: translateY(-5px) scale(1.03);
        box-shadow: 0 12px 25px rgba(0, 0, 0, 0.5);
      }

      .button:disabled {
        opacity: 0.7;
        cursor: not-allowed;
        transform: none;
      }
      </style>
      ```

      ```vue app/components/UserProfile.vue expandable lines theme={null}
      <template>
        <div v-if="pending" class="loading-text">
          Loading profile...
        </div>
        <div v-else-if="user" class="profile-container">
          <img 
            :src="user.picture || placeholderImage" 
            :alt="user.name || 'User'" 
            class="profile-picture"
            @error="handleImageError"
          />
          <div class="profile-info">
            <div class="profile-name">
              {{ user.name }}
            </div>
            <div class="profile-email">
              {{ user.email }}
            </div>
          </div>
        </div>
      </template>

      <script setup lang="ts">
      const user = useUser()
      const pending = ref(false)

      const placeholderImage = `data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='100' height='100' viewBox='0 0 100 100'%3E%3Ccircle cx='50' cy='50' r='50' fill='%2363b3ed'/%3E%3Cpath d='M50 45c7.5 0 13.64-6.14 13.64-13.64S57.5 17.72 50 17.72s-13.64 6.14-13.64 13.64S42.5 45 50 45zm0 6.82c-9.09 0-27.28 4.56-27.28 13.64v3.41c0 1.88 1.53 3.41 3.41 3.41h47.74c1.88 0 3.41-1.53 3.41-3.41v-3.41c0-9.08-18.19-13.64-27.28-13.64z' fill='%23fff'/%3E%3C/svg%3E`

      function handleImageError(e: Event) {
        const target = e.target as HTMLImageElement
        target.src = placeholderImage
      }

      // Simulate loading state for better UX
      onMounted(() => {
        pending.value = true
        nextTick(() => {
          pending.value = false
        })
      })
      </script>

      <style scoped>
      .profile-container {
        display: flex;
        flex-direction: column;
        align-items: center;
        gap: 1rem;
      }

      .profile-picture {
        width: 110px;
        height: 110px;
        border-radius: 50%;
        object-fit: cover;
        border: 3px solid #63b3ed;
        transition: transform 0.3s ease-in-out;
      }

      .profile-picture:hover {
        transform: scale(1.05);
      }

      .profile-info {
        text-align: center;
      }

      .profile-name {
        font-size: 2rem;
        font-weight: 600;
        color: #f7fafc;
        margin-bottom: 0.5rem;
      }

      .profile-email {
        font-size: 1.15rem;
        color: #a0aec0;
      }

      .loading-text {
        font-size: 1.8rem;
        font-weight: 500;
        color: #a0aec0;
        animation: pulse 1.5s infinite ease-in-out;
      }

      @keyframes pulse {
        0%, 100% { opacity: 1; }
        50% { opacity: 0.6; }
      }
      </style>
      ```

      ```vue app.vue expandable lines theme={null}
      <template>
        <div class="app-container">
          <div class="main-card-wrapper">
            <img 
              src="https://cdn.auth0.com/quantum-assets/dist/latest/logos/auth0/auth0-lockup-en-ondark.png" 
              alt="Auth0 Logo" 
              class="auth0-logo"
            />
            <h1 class="main-title">Welcome to Auth0 Nuxt</h1>

            <div v-if="user" class="logged-in-section">
              <div class="logged-in-message">✅ Successfully authenticated!</div>
              <h2 class="profile-section-title">Your Profile</h2>
              <div class="profile-card">
                <UserProfile />
              </div>
              <LogoutButton />
            </div>

            <div v-else class="action-card">
              <p class="action-text">Get started by signing in to your account</p>
              <LoginButton />
            </div>
          </div>
        </div>
      </template>


      <script setup lang="ts">
      const user = useUser()
      </script>

      <style>
      @import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap');

      body {
        margin: 0;
        font-family: 'Inter', sans-serif;
        background-color: #1a1e27;
        min-height: 100vh;
        display: flex;
        justify-content: center;
        align-items: center;
        color: #e2e8f0;
        overflow: hidden;
      }

      .app-container {
        display: flex;
        flex-direction: column;
        justify-content: center;
        align-items: center;
        min-height: 100vh;
        width: 100%;
        padding: 1rem;
        box-sizing: border-box;
      }

      .loading-state, .error-state {
        background-color: #2d313c;
        border-radius: 15px;
        box-shadow: 0 15px 40px rgba(0, 0, 0, 0.4);
        padding: 3rem;
        text-align: center;
      }

      .loading-text {
        font-size: 1.8rem;
        font-weight: 500;
        color: #a0aec0;
        animation: pulse 1.5s infinite ease-in-out;
      }

      .error-state {
        background-color: #c53030;
        color: #fff;
      }

      .error-title {
        font-size: 2.8rem;
        font-weight: 700;
        margin-bottom: 0.5rem;
      }

      .error-message {
        font-size: 1.3rem;
        margin-bottom: 0.5rem;
      }

      .error-sub-message {
        font-size: 1rem;
        opacity: 0.8;
      }

      .main-card-wrapper {
        background-color: #262a33;
        border-radius: 20px;
        box-shadow: 0 20px 60px rgba(0, 0, 0, 0.6), 0 0 0 1px rgba(255, 255, 255, 0.05);
        display: flex;
        flex-direction: column;
        align-items: center;
        gap: 2rem;
        padding: 3rem;
        max-width: 500px;
        width: 90%;
        animation: fadeInScale 0.8s ease-out forwards;
      }

      .auth0-logo {
        width: 160px;
        margin-bottom: 1.5rem;
        opacity: 0;
        animation: slideInDown 1s ease-out forwards 0.2s;
      }

      .main-title {
        font-size: 2.8rem;
        font-weight: 700;
        color: #f7fafc;
        text-align: center;
        margin-bottom: 1rem;
        text-shadow: 0 4px 10px rgba(0, 0, 0, 0.3);
        opacity: 0;
        animation: fadeIn 1s ease-out forwards 0.4s;
      }

      .action-card {
        background-color: #2d313c;
        border-radius: 15px;
        box-shadow: inset 0 2px 5px rgba(0, 0, 0, 0.3), 0 5px 15px rgba(0, 0, 0, 0.3);
        padding: 2.5rem;
        display: flex;
        flex-direction: column;
        align-items: center;
        gap: 1.8rem;
        width: calc(100% - 2rem);
        opacity: 0;
        animation: fadeIn 1s ease-out forwards 0.6s;
      }

      .action-text {
        font-size: 1.25rem;
        color: #cbd5e0;
        text-align: center;
        line-height: 1.6;
        font-weight: 400;
      }

      .logged-in-section {
        display: flex;
        flex-direction: column;
        align-items: center;
        gap: 1.5rem;
        width: 100%;
      }

      .logged-in-message {
        font-size: 1.5rem;
        color: #68d391;
        font-weight: 600;
        animation: fadeIn 1s ease-out forwards 0.8s;
      }

      .profile-section-title {
        font-size: 2.2rem;
        animation: slideInUp 1s ease-out forwards 1s;
      }

      .profile-card {
        padding: 2.2rem;
        animation: scaleIn 0.8s ease-out forwards 1.2s;
      }

      @keyframes fadeIn {
        from { opacity: 0; }
        to { opacity: 1; }
      }

      @keyframes fadeInScale {
        from { opacity: 0; transform: scale(0.95); }
        to { opacity: 1; transform: scale(1); }
      }

      @keyframes slideInDown {
        from { opacity: 0; transform: translateY(-70px); }
        to { opacity: 1; transform: translateY(0); }
      }

      @keyframes slideInUp {
        from { opacity: 0; transform: translateY(50px); }
        to { opacity: 1; transform: translateY(0); }
      }

      @keyframes pulse {
        0%, 100% { opacity: 1; }
        50% { opacity: 0.6; }
      }

      @keyframes scaleIn {
        from { opacity: 0; transform: scale(0.8); }
        to { opacity: 1; transform: scale(1); }
      }

      @media (max-width: 600px) {
        .main-card-wrapper {
          padding: 2rem;
          margin: 1rem;
        }

        .main-title {
          font-size: 2.2rem;
        }

        .auth0-logo {
          width: 120px;
        }
      }
      </style>
      ```
    </CodeGroup>
  </Step>

  <Step title="Run your app">
    ```shellscript theme={null}
    npm run dev
    ```
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a fully functional Auth0 login page running on your [localhost](http://localhost:3000/)
</Check>


# Add Login to Your PHP Application
Source: https://auth0.com/docs/quickstart/webapp/php/interactive

This guide demonstrates how to integrate Auth0, add authentication, and display user profile information in any PHP application using the Auth0 PHP SDK.

<QuickstartButtons />

<Recipe>
  <Content>
    Auth0 allows you to add authentication to almost any application type quickly. This guide demonstrates how to
    integrate Auth0, add authentication, and display user profile information in any PHP application using the Auth0 PHP
    SDK.

    To use this quickstart, you’ll need to:

    <Section title={sections[0].title}>
      To use Auth0 services, you’ll need to have an application set up in the Auth0 Dashboard. The Auth0 application is
      where you will configure how you want authentication to work for the project you are developing.

      ### Configure an application

      Use the interactive selector to create a new Auth0 application or select an existing application that represents
      the project you want to integrate with. Every application in Auth0 is assigned an alphanumeric, unique client ID
      that your application code will use to call Auth0 APIs through the SDK.

      Any settings you configure using this quickstart will automatically update for your Application in the [Dashboard](https://manage.auth0.com/#/), which is where you
      can manage your Applications in the future.

      If you would rather explore a complete configuration, you can view a sample application instead.

      ### Configure Callback URLs

      A callback URL is a URL in your application that you would like Auth0 to redirect users to after they have
      authenticated. If not set, users will not be returned to your application after they log in.

      <Info>
        If you are following along with our sample project, set this to
        `http://localhost:3000/callback`.
      </Info>

      ### Configure Logout URLs

      A logout URL is a URL in your application that you would like Auth0 to redirect users to after they have logged
      out. If not set, users will not be able to log out from your application and will receive an error.

      <Info>
        If you are following along with our sample project, set this to `http://localhost:3000`.
      </Info>

      ### Configure Allowed Web Origins

      An Allowed Web Origin is a URL that you want to be allowed to access to your authentication flow. This must
      contain the URL of your project. If not properly set, your project will be unable to silently refresh
      authentication tokens, so your users will be logged out the next time they visit your application or refresh a
      page.

      <Info>
        If you are following along with our sample project, set this to `http://localhost:3000`.
      </Info>
    </Section>

    <Section title={sections[1].title}>
      Auth0 provides a [PHP
      SDK](https://github.com/auth0/auth0-PHP) (Auth0-PHP) to simplify the process of implementing Auth0 authentication and authorization in PHP apps.

      The Auth0 PHP SDK requires [PSR-17](https://www.php-fig.org/psr/psr-17/) and [PSR-18](https://www.php-fig.org/psr/psr-18/) compatible HTTP libraries to be installed for managing network requests. If
      you don't have libraries available, you can install reliable choices by running the following commands in your
      terminal:

      ```text lines theme={null}
      cd <your-project-directory>
      composer require symfony/http-client nyholm/psr7
      ```

      Now install the Auth0 PHP SDK by running the following command in your terminal:

      ```text lines theme={null}
      composer require auth0/auth0-php
      ```

      ### Configure the Auth0 SDK

      Create a new file in your application called `index.php`, and copy in the code from the interactive
      panel to the right under the **index.php** tab.

      For the SDK to function properly, you must set the following properties in the Auth0 SDK during initialization:

      * `domain`: The domain of your Auth0 tenant. Generally, you can find this in the Auth0 Dashboard
        under your Application's Settings in the Domain field. If you are using a [custom domain](https://auth0.com/docs/custom-domains), you should set this to the
        value of your custom domain instead.
      * `clientId`: The ID of the Auth0 Application you set up earlier in this quickstart. You can find
        this in the Auth0 Dashboard under your Application's Settings in the Client ID field.
      * `clientSecret`: The secret of the Auth0 Application you set up earlier in this quickstart. You can
        find this in the Auth0 Dashboard under your Application's Settings in the Client Secret field.
      * `redirectUri`: The URL in your application that you would like Auth0 to redirect users to after
        they have authenticated. This corresponds to the callback URL you set up earlier in this quickstart. You can
        also find this value in the Auth0 Dashboard under your Application's Settings in the Callback URLs field. Make
        sure what you enter in your code matches what you set up earlier or your users will see an error.
      * `cookieSecret`: A long secret value used to encrypt the session cookie. You can generate a
        suitable string by running `openssl rand -hex 32`in your terminal.

      <Info>
        ##### Checkpoint

        Your Auth0 SDK should now be properly configured. Run your application to verify that:

        * The SDK is initializing correctly.
        * Your application is not throwing any errors related to Auth0.
      </Info>
    </Section>

    <Section title={sections[2].title}>
      Now install a routing library, to help direct incoming requests to your application. This isn't a required step,
      but simplifies our application structure for the purposes of this quickstart.

      ```text lines theme={null}
      composer require steampixel/simple-php-router
      ```

      Create a new file in your application called `router.php` to define our routes, and copy in the code
      from the interactive panel to the right.
    </Section>

    <Section title={sections[3].title}>
      Now that you have configured your Auth0 Application and the Auth0 PHP SDK, you need to set up login for your
      project. To do this, you will use the SDK’s `login()` method to create a login button that redirects
      users to the Auth0 Universal Login page. After a user successfully authenticates, they will be redirected to the
      callback URL you set up earlier in this quickstart.

      Create a new file in your application called `login.php` to handle logging process, and copy in the
      code from the interactive panel to the right, which contains the logic needed for login.

      <Info>
        ##### Checkpoint

        You should now be able to log in or sign up using a username and password.

        Click the login link and verify that:

        * Your application redirects you to the Auth0 Universal Login page.
        * You can log in or sign up.
        * Auth0 redirects you back to your application using the value of the `redirectUri`you used
          to configure the SDK.
      </Info>
    </Section>

    <Section title={sections[4].title}>
      Users who log in to your project will also need a way to log out. We will handle a logout button using the SDK’s
      `logout()` method. When users log out, they will be redirected to your [Auth0 logout](https://auth0.com/docs/api/authentication?http#logout) endpoint, which
      will then immediately redirect them to the logout URL you set up earlier in this quickstart.

      Create a new file in your application called `logout.php` for handling the process, and copy in the
      code from the interactive panel, which contains the logic needed for logout. Then, update your
      `index.php` file to include the logout button.

      <Info>
        ##### Checkpoint

        Run your application and click the logout button, verify that:

        * Your application redirects you to the address you specified as one of the Allowed Logout URLs in your
          Application Settings.
        * You are no longer logged in to your application.
      </Info>
    </Section>

    <Section title={sections[5].title}>
      Now that your users can log in and log out, you will likely want to be able to retrieve the [profile information](https://auth0.com/docs/users/concepts/overview-user-profile)
      associated with authenticated users. For example, you may want to be able to display a logged-in user’s name or
      profile picture in your project.

      The Auth0 PHP SDK provides user information through the `getCredentials()` method. Review the
      `profile.php` code in the interactive panel to see an example of how to use it.

      Because the method contains sensitive information related to the user's identity, its availability depends on the
      user's authentication status. To prevent render errors, you should always check if the
      `getCredentials()` method returns an `object` or `null` to determine whether
      Auth0 has authenticated the user before your application consumes the results.

      <Info>
        ##### Checkpoint

        Verify that:

        * You can display the `nickname`or any other user property correctly after you have logged
          in.
      </Info>
    </Section>

    ## Next Steps

    Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.

    This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:

    * [Auth0 Dashboard](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq) - Learn how to configure and manage your Auth0 tenant and applications
    * [Auth0-PHP SDK](https://github.com/auth0/auth0-php) - Explore the SDK used in this tutorial more fully
    * [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
  </Content>

  <SideMenu>
    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```php index.php lines theme={null}
        <?php

          declare(strict_types=1);

          require('vendor/autoload.php');

          use Auth0\SDK\Auth0;
          use Auth0\SDK\Configuration\SdkConfiguration;

          $configuration = new SdkConfiguration(
            domain: '{yourDomain}',
            clientId: '{yourClientId}',
            clientSecret: '{yourClientSecret}',
            redirectUri: 'http://' . $_SERVER['HTTP_HOST'] . '/callback',
            cookieSecret: '4f60eb5de6b5904ad4b8e31d9193e7ea4a3013b476ddb5c259ee9077c05e1457'
          );

          $sdk = new Auth0($configuration);

          require('router.php');
        ```

        ```php login.php lines theme={null}
        <?php

          declare(strict_types=1);

          /**
           * Prepare application session and redirect to the Auth0 Universal Login page.
           *
           * The user will be redirected to your callback route to complete the authentication flow.
           */

          header(sprintf('Location: %s', $sdk->login()));
        ```

        ```php logout.php lines theme={null}
        <?php

          declare(strict_types=1);

          /**
           * Clear application session and redirect to the Auth0 logout endpoint.
           *
           * The user will be redirected to your index route afterward.
           */

          header(sprintf('Location: %s', $sdk->logout()));
        ```

        ```php profile.php lines theme={null}
        <?php

          declare(strict_types=1);

          $session = $sdk->getCredentials();
          $authenticated = $session !== null;

          $template = [
            'name' => $authenticated ? $session->user['email'] : 'guest',
            'picture' => $authenticated ? $session->user['picture'] : null,
            'session' => $authenticated ? print_r($session, true) : '',
            'auth:route' => $authenticated ? 'logout' : 'login',
            'auth:text' => $authenticated ? 'out' : 'in',
          ];

          printf('<p>Welcome, %s.</p>', $template['name']);
          printf('<p><pre>%s</pre></p>', $template['session']);
          printf('<p><a href="/%s">Log %s</a></p>', $template['auth:route'], $template['auth:text']);
        ```

        ```php router.php lines  theme={null}
        <?php

          declare(strict_types=1);

          use Steampixel\Route;

          if ($_SERVER['HTTP_HOST'] !== 'localhost:3000') {
            die('<p>This quickstart is configured to be run from <a href="http://localhost:3000">http://localhost:3000</a>.</p>');
          }

          Route::add('/', function() use ($sdk) {
            require('profile.php');
          });

          Route::add('/login', function() use ($sdk) {
            require('login.php');
          });

          Route::add('/callback', function() use ($sdk) {
            require('callback.php');
          });

          Route::add('/logout', function() use ($sdk) {
            require('logout.php');
          });

          Route::run();
        ```

        ```php callback.php lines  theme={null}
        <?php

          declare(strict_types=1);

          /**
           * Upon returning from the Auth0 Universal Login, we need to perform a code exchange using the `exchange()` method
           * to complete the authentication flow. This process configures the session for use by the application.
           *
           * If successful, the user will be redirected back to the index route.
           */

           $hasAuthenticated = isset($_GET['state']) && isset($_GET['code']);
           $hasAuthenticationFailure = isset($_GET['error']);

          // The end user will be returned with ?state and ?code values in their request, when successful.
          if ($hasAuthenticated) {
            try {
              $sdk->exchange();
            } catch (\Throwable $th) {
              printf('Unable to complete authentication: %s', $th->getMessage());
              exit;
            }
          }

          // When authentication was unsuccessful, the end user will be returned with an ?error in their request.
          if ($hasAuthenticationFailure) {
            printf('Authentication failure: %s', htmlspecialchars(strip_tags(filter_input(INPUT_GET, 'error'))));
            exit;
          }

          // Nothing to do: redirect to index route.
          header('Location: /');
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```php router.php lines  theme={null}
        <?php

          declare(strict_types=1);

          use Steampixel\Route;

          if ($_SERVER['HTTP_HOST'] !== 'localhost:3000') {
            die('<p>This quickstart is configured to be run from <a href="http://localhost:3000">http://localhost:3000</a>.</p>');
          }

          Route::add('/', function() use ($sdk) {
            require('profile.php');
          });

          Route::add('/login', function() use ($sdk) {
            require('login.php');
          });

          Route::add('/callback', function() use ($sdk) {
            require('callback.php');
          });

          Route::add('/logout', function() use ($sdk) {
            require('logout.php');
          });

          Route::run();
        ```

        ```php index.php lines theme={null}
        <?php

          declare(strict_types=1);

          require('vendor/autoload.php');

          use Auth0\SDK\Auth0;
          use Auth0\SDK\Configuration\SdkConfiguration;

          $configuration = new SdkConfiguration(
            domain: '{yourDomain}',
            clientId: '{yourClientId}',
            clientSecret: '{yourClientSecret}',
            redirectUri: 'http://' . $_SERVER['HTTP_HOST'] . '/callback',
            cookieSecret: '4f60eb5de6b5904ad4b8e31d9193e7ea4a3013b476ddb5c259ee9077c05e1457'
          );

          $sdk = new Auth0($configuration);

          require('router.php');
        ```

        ```php login.php lines theme={null}
        <?php

          declare(strict_types=1);

          /**
           * Prepare application session and redirect to the Auth0 Universal Login page.
           *
           * The user will be redirected to your callback route to complete the authentication flow.
           */

          header(sprintf('Location: %s', $sdk->login()));
        ```

        ```php logout.php lines theme={null}
        <?php

          declare(strict_types=1);

          /**
           * Clear application session and redirect to the Auth0 logout endpoint.
           *
           * The user will be redirected to your index route afterward.
           */

          header(sprintf('Location: %s', $sdk->logout()));
        ```

        ```php profile.php lines theme={null}
        <?php

          declare(strict_types=1);

          $session = $sdk->getCredentials();
          $authenticated = $session !== null;

          $template = [
            'name' => $authenticated ? $session->user['email'] : 'guest',
            'picture' => $authenticated ? $session->user['picture'] : null,
            'session' => $authenticated ? print_r($session, true) : '',
            'auth:route' => $authenticated ? 'logout' : 'login',
            'auth:text' => $authenticated ? 'out' : 'in',
          ];

          printf('<p>Welcome, %s.</p>', $template['name']);
          printf('<p><pre>%s</pre></p>', $template['session']);
          printf('<p><a href="/%s">Log %s</a></p>', $template['auth:route'], $template['auth:text']);
        ```

        ```php callback.php lines  theme={null}
        <?php

          declare(strict_types=1);

          /**
           * Upon returning from the Auth0 Universal Login, we need to perform a code exchange using the `exchange()` method
           * to complete the authentication flow. This process configures the session for use by the application.
           *
           * If successful, the user will be redirected back to the index route.
           */

           $hasAuthenticated = isset($_GET['state']) && isset($_GET['code']);
           $hasAuthenticationFailure = isset($_GET['error']);

          // The end user will be returned with ?state and ?code values in their request, when successful.
          if ($hasAuthenticated) {
            try {
              $sdk->exchange();
            } catch (\Throwable $th) {
              printf('Unable to complete authentication: %s', $th->getMessage());
              exit;
            }
          }

          // When authentication was unsuccessful, the end user will be returned with an ?error in their request.
          if ($hasAuthenticationFailure) {
            printf('Authentication failure: %s', htmlspecialchars(strip_tags(filter_input(INPUT_GET, 'error'))));
            exit;
          }

          // Nothing to do: redirect to index route.
          header('Location: /');
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```php login.php lines theme={null}
        <?php

          declare(strict_types=1);

          /**
           * Prepare application session and redirect to the Auth0 Universal Login page.
           *
           * The user will be redirected to your callback route to complete the authentication flow.
           */

          header(sprintf('Location: %s', $sdk->login()));
        ```

        ```php index.php lines theme={null}
        <?php

          declare(strict_types=1);

          require('vendor/autoload.php');

          use Auth0\SDK\Auth0;
          use Auth0\SDK\Configuration\SdkConfiguration;

          $configuration = new SdkConfiguration(
            domain: '{yourDomain}',
            clientId: '{yourClientId}',
            clientSecret: '{yourClientSecret}',
            redirectUri: 'http://' . $_SERVER['HTTP_HOST'] . '/callback',
            cookieSecret: '4f60eb5de6b5904ad4b8e31d9193e7ea4a3013b476ddb5c259ee9077c05e1457'
          );

          $sdk = new Auth0($configuration);

          require('router.php');
        ```

        ```php logout.php lines theme={null}
        <?php

          declare(strict_types=1);

          /**
           * Clear application session and redirect to the Auth0 logout endpoint.
           *
           * The user will be redirected to your index route afterward.
           */

          header(sprintf('Location: %s', $sdk->logout()));
        ```

        ```php profile.php lines theme={null}
        <?php

          declare(strict_types=1);

          $session = $sdk->getCredentials();
          $authenticated = $session !== null;

          $template = [
            'name' => $authenticated ? $session->user['email'] : 'guest',
            'picture' => $authenticated ? $session->user['picture'] : null,
            'session' => $authenticated ? print_r($session, true) : '',
            'auth:route' => $authenticated ? 'logout' : 'login',
            'auth:text' => $authenticated ? 'out' : 'in',
          ];

          printf('<p>Welcome, %s.</p>', $template['name']);
          printf('<p><pre>%s</pre></p>', $template['session']);
          printf('<p><a href="/%s">Log %s</a></p>', $template['auth:route'], $template['auth:text']);
        ```

        ```php router.php lines  theme={null}
        <?php

          declare(strict_types=1);

          use Steampixel\Route;

          if ($_SERVER['HTTP_HOST'] !== 'localhost:3000') {
            die('<p>This quickstart is configured to be run from <a href="http://localhost:3000">http://localhost:3000</a>.</p>');
          }

          Route::add('/', function() use ($sdk) {
            require('profile.php');
          });

          Route::add('/login', function() use ($sdk) {
            require('login.php');
          });

          Route::add('/callback', function() use ($sdk) {
            require('callback.php');
          });

          Route::add('/logout', function() use ($sdk) {
            require('logout.php');
          });

          Route::run();
        ```

        ```php callback.php lines  theme={null}
        <?php

          declare(strict_types=1);

          /**
           * Upon returning from the Auth0 Universal Login, we need to perform a code exchange using the `exchange()` method
           * to complete the authentication flow. This process configures the session for use by the application.
           *
           * If successful, the user will be redirected back to the index route.
           */

           $hasAuthenticated = isset($_GET['state']) && isset($_GET['code']);
           $hasAuthenticationFailure = isset($_GET['error']);

          // The end user will be returned with ?state and ?code values in their request, when successful.
          if ($hasAuthenticated) {
            try {
              $sdk->exchange();
            } catch (\Throwable $th) {
              printf('Unable to complete authentication: %s', $th->getMessage());
              exit;
            }
          }

          // When authentication was unsuccessful, the end user will be returned with an ?error in their request.
          if ($hasAuthenticationFailure) {
            printf('Authentication failure: %s', htmlspecialchars(strip_tags(filter_input(INPUT_GET, 'error'))));
            exit;
          }

          // Nothing to do: redirect to index route.
          header('Location: /');
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```php logout.php lines theme={null}
        <?php

          declare(strict_types=1);

          /**
           * Clear application session and redirect to the Auth0 logout endpoint.
           *
           * The user will be redirected to your index route afterward.
           */

          header(sprintf('Location: %s', $sdk->logout()));
        ```

        ```php index.php lines theme={null}
        <?php

          declare(strict_types=1);

          require('vendor/autoload.php');

          use Auth0\SDK\Auth0;
          use Auth0\SDK\Configuration\SdkConfiguration;

          $configuration = new SdkConfiguration(
            domain: '{yourDomain}',
            clientId: '{yourClientId}',
            clientSecret: '{yourClientSecret}',
            redirectUri: 'http://' . $_SERVER['HTTP_HOST'] . '/callback',
            cookieSecret: '4f60eb5de6b5904ad4b8e31d9193e7ea4a3013b476ddb5c259ee9077c05e1457'
          );

          $sdk = new Auth0($configuration);

          require('router.php');
        ```

        ```php login.php lines theme={null}
        <?php

          declare(strict_types=1);

          /**
           * Prepare application session and redirect to the Auth0 Universal Login page.
           *
           * The user will be redirected to your callback route to complete the authentication flow.
           */

          header(sprintf('Location: %s', $sdk->login()));
        ```

        ```php profile.php lines theme={null}
        <?php

          declare(strict_types=1);

          $session = $sdk->getCredentials();
          $authenticated = $session !== null;

          $template = [
            'name' => $authenticated ? $session->user['email'] : 'guest',
            'picture' => $authenticated ? $session->user['picture'] : null,
            'session' => $authenticated ? print_r($session, true) : '',
            'auth:route' => $authenticated ? 'logout' : 'login',
            'auth:text' => $authenticated ? 'out' : 'in',
          ];

          printf('<p>Welcome, %s.</p>', $template['name']);
          printf('<p><pre>%s</pre></p>', $template['session']);
          printf('<p><a href="/%s">Log %s</a></p>', $template['auth:route'], $template['auth:text']);
        ```

        ```php router.php lines  theme={null}
        <?php

          declare(strict_types=1);

          use Steampixel\Route;

          if ($_SERVER['HTTP_HOST'] !== 'localhost:3000') {
            die('<p>This quickstart is configured to be run from <a href="http://localhost:3000">http://localhost:3000</a>.</p>');
          }

          Route::add('/', function() use ($sdk) {
            require('profile.php');
          });

          Route::add('/login', function() use ($sdk) {
            require('login.php');
          });

          Route::add('/callback', function() use ($sdk) {
            require('callback.php');
          });

          Route::add('/logout', function() use ($sdk) {
            require('logout.php');
          });

          Route::run();
        ```

        ```php callback.php lines  theme={null}
        <?php

          declare(strict_types=1);

          /**
           * Upon returning from the Auth0 Universal Login, we need to perform a code exchange using the `exchange()` method
           * to complete the authentication flow. This process configures the session for use by the application.
           *
           * If successful, the user will be redirected back to the index route.
           */

           $hasAuthenticated = isset($_GET['state']) && isset($_GET['code']);
           $hasAuthenticationFailure = isset($_GET['error']);

          // The end user will be returned with ?state and ?code values in their request, when successful.
          if ($hasAuthenticated) {
            try {
              $sdk->exchange();
            } catch (\Throwable $th) {
              printf('Unable to complete authentication: %s', $th->getMessage());
              exit;
            }
          }

          // When authentication was unsuccessful, the end user will be returned with an ?error in their request.
          if ($hasAuthenticationFailure) {
            printf('Authentication failure: %s', htmlspecialchars(strip_tags(filter_input(INPUT_GET, 'error'))));
            exit;
          }

          // Nothing to do: redirect to index route.
          header('Location: /');
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```php profile.php lines theme={null}
        <?php

          declare(strict_types=1);

          $session = $sdk->getCredentials();
          $authenticated = $session !== null;

          $template = [
            'name' => $authenticated ? $session->user['email'] : 'guest',
            'picture' => $authenticated ? $session->user['picture'] : null,
            'session' => $authenticated ? print_r($session, true) : '',
            'auth:route' => $authenticated ? 'logout' : 'login',
            'auth:text' => $authenticated ? 'out' : 'in',
          ];

          printf('<p>Welcome, %s.</p>', $template['name']);
          printf('<p><pre>%s</pre></p>', $template['session']);
          printf('<p><a href="/%s">Log %s</a></p>', $template['auth:route'], $template['auth:text']);
        ```

        ```php index.php lines theme={null}
        <?php

          declare(strict_types=1);

          require('vendor/autoload.php');

          use Auth0\SDK\Auth0;
          use Auth0\SDK\Configuration\SdkConfiguration;

          $configuration = new SdkConfiguration(
            domain: '{yourDomain}',
            clientId: '{yourClientId}',
            clientSecret: '{yourClientSecret}',
            redirectUri: 'http://' . $_SERVER['HTTP_HOST'] . '/callback',
            cookieSecret: '4f60eb5de6b5904ad4b8e31d9193e7ea4a3013b476ddb5c259ee9077c05e1457'
          );

          $sdk = new Auth0($configuration);

          require('router.php');
        ```

        ```php login.php lines theme={null}
        <?php

          declare(strict_types=1);

          /**
           * Prepare application session and redirect to the Auth0 Universal Login page.
           *
           * The user will be redirected to your callback route to complete the authentication flow.
           */

          header(sprintf('Location: %s', $sdk->login()));
        ```

        ```php logout.php lines theme={null}
        <?php

          declare(strict_types=1);

          /**
           * Clear application session and redirect to the Auth0 logout endpoint.
           *
           * The user will be redirected to your index route afterward.
           */

          header(sprintf('Location: %s', $sdk->logout()));
        ```

        ```php router.php lines  theme={null}
        <?php

          declare(strict_types=1);

          use Steampixel\Route;

          if ($_SERVER['HTTP_HOST'] !== 'localhost:3000') {
            die('<p>This quickstart is configured to be run from <a href="http://localhost:3000">http://localhost:3000</a>.</p>');
          }

          Route::add('/', function() use ($sdk) {
            require('profile.php');
          });

          Route::add('/login', function() use ($sdk) {
            require('login.php');
          });

          Route::add('/callback', function() use ($sdk) {
            require('callback.php');
          });

          Route::add('/logout', function() use ($sdk) {
            require('logout.php');
          });

          Route::run();
        ```

        ```php callback.php lines  theme={null}
        <?php

          declare(strict_types=1);

          /**
           * Upon returning from the Auth0 Universal Login, we need to perform a code exchange using the `exchange()` method
           * to complete the authentication flow. This process configures the session for use by the application.
           *
           * If successful, the user will be redirected back to the index route.
           */

           $hasAuthenticated = isset($_GET['state']) && isset($_GET['code']);
           $hasAuthenticationFailure = isset($_GET['error']);

          // The end user will be returned with ?state and ?code values in their request, when successful.
          if ($hasAuthenticated) {
            try {
              $sdk->exchange();
            } catch (\Throwable $th) {
              printf('Unable to complete authentication: %s', $th->getMessage());
              exit;
            }
          }

          // When authentication was unsuccessful, the end user will be returned with an ?error in their request.
          if ($hasAuthenticationFailure) {
            printf('Authentication failure: %s', htmlspecialchars(strip_tags(filter_input(INPUT_GET, 'error'))));
            exit;
          }

          // Nothing to do: redirect to index route.
          header('Location: /');
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>
  </SideMenu>
</Recipe>


# Add Login to Your Flask Application
Source: https://auth0.com/docs/quickstart/webapp/python/index

Add Auth0 authentication to a Flask web application with login, protected routes, and user profiles

<Note>
  **Prerequisites:** Before you begin, ensure you have the following installed:

  * **[Python](https://www.python.org/downloads/)** 3.9 or newer
  * **[pip](https://pip.pypa.io/en/stable/installation/)** 20.0 or newer
  * **[jq](https://jqlang.org/)** - Required for Auth0 CLI setup

  **Flask Version Compatibility:** This quickstart uses **Flask 2.0+** with the `[async]` extra for async support.
</Note>

## Get Started

This quickstart demonstrates how to add Auth0 authentication to a Flask application. You'll build a secure web application with login functionality, protected routes, and user profile access using the [Auth0 WebApp Python SDK](https://github.com/auth0/auth0-server-python).

<Steps>
  <Step title="Set up your environment">
    Create a new directory for your Flask project:

    ```bash theme={null}
    mkdir auth0-flask-app && cd auth0-flask-app
    ```

    Create a virtual environment:

    ```bash theme={null}
    python -m venv venv
    source venv/bin/activate  # On Windows: venv\Scripts\activate
    ```
  </Step>

  <Step title="Install dependencies">
    Create `requirements.txt` to track your dependencies:

    ```txt requirements.txt theme={null}
    auth0-server-python>=1.0.0b7
    flask[async]>=2.0.0
    python-dotenv>=1.0.0
    ```

    The `requirements.txt` file tracks all project dependencies. To install them, run:

    ```bash theme={null}
    pip install -r requirements.txt
    ```
  </Step>

  <Step title="Setup your Auth0 App">
    Next up, you need to create a new app on your Auth0 tenant and add the environment variables to your project.

    You can choose to do this automatically by running a CLI command or do it manually via the Dashboard:

    <Tabs>
      <Tab title="CLI">
        Run the following shell command on your project's root directory to create an Auth0 application and generate a `.env` file:

        <CodeGroup>
          ```shellscript Mac theme={null}
          AUTH0_APP_NAME="My Flask App" && brew tap auth0/auth0-cli && brew install auth0 && auth0 login --no-input && auth0 apps create -n "${AUTH0_APP_NAME}" -t regular -c http://localhost:5000/callback -l http://localhost:5000 -o http://localhost:5000 --reveal-secrets --json > app-details.json && CLIENT_ID=$(python3 -c "import json; print(json.load(open('app-details.json'))['client_id'])") && CLIENT_SECRET=$(python3 -c "import json; print(json.load(open('app-details.json'))['client_secret'])") && DOMAIN=$(auth0 tenants list --json | python3 -c "import sys, json; print([t['name'] for t in json.load(sys.stdin) if t.get('active')][0])") && SECRET=$(openssl rand -hex 64) && echo "AUTH0_DOMAIN=${DOMAIN}" > .env && echo "AUTH0_CLIENT_ID=${CLIENT_ID}" >> .env && echo "AUTH0_CLIENT_SECRET=${CLIENT_SECRET}" >> .env && echo "AUTH0_SECRET=${SECRET}" >> .env && echo "AUTH0_REDIRECT_URI=http://localhost:5000/callback" >> .env && rm app-details.json && echo ".env file created with your Auth0 details:" && cat .env
          ```

          ```shellscript Windows theme={null}
          $AppName = "My Flask App"; winget install Auth0.CLI; auth0 login --no-input; auth0 apps create -n "$AppName" -t regular -c http://localhost:5000/callback -l http://localhost:5000 -o http://localhost:5000 --reveal-secrets --json | Set-Content -Path app-details.json; $ClientId = (Get-Content -Raw app-details.json | ConvertFrom-Json).client_id; $ClientSecret = (Get-Content -Raw app-details.json | ConvertFrom-Json).client_secret; $Domain = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name; $Secret = [System.Convert]::ToHexString([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(64)).ToLower(); Set-Content -Path .env -Value "AUTH0_DOMAIN=$Domain"; Add-Content -Path .env -Value "AUTH0_CLIENT_ID=$ClientId"; Add-Content -Path .env -Value "AUTH0_CLIENT_SECRET=$ClientSecret"; Add-Content -Path .env -Value "AUTH0_SECRET=$Secret"; Add-Content -Path .env -Value "AUTH0_REDIRECT_URI=http://localhost:5000/callback"; Remove-Item app-details.json; Write-Output ".env file created with your Auth0 details:"; Get-Content .env
          ```
        </CodeGroup>
      </Tab>

      <Tab title="Dashboard">
        Before you start, create a `.env` file in your project root:

        ```bash .env theme={null}
        # Auth0 Configuration
        AUTH0_DOMAIN=YOUR_AUTH0_DOMAIN
        AUTH0_CLIENT_ID=YOUR_CLIENT_ID
        AUTH0_CLIENT_SECRET=YOUR_CLIENT_SECRET
        AUTH0_SECRET=YOUR_GENERATED_SECRET
        AUTH0_REDIRECT_URI=http://localhost:5000/callback
        ```

        1. Go to [Auth0 Dashboard](https://manage.auth0.com/dashboard/) → **Applications** → **Applications**
        2. Click **Create Application**
        3. Name your application (e.g., "My Flask App") and select **Regular Web Application**
        4. Click **Create**
        5. In the **Settings** tab, configure the following:
           * **Allowed Callback URLs**: `http://localhost:5000/callback`
           * **Allowed Logout URLs**: `http://localhost:5000`
           * **Allowed Web Origins**: `http://localhost:5000`
        6. Click **Save Changes**
        7. Replace `YOUR_AUTH0_DOMAIN` in `.env` with your **Domain** from the Settings tab (e.g., `your-tenant.auth0.com`)
        8. Replace `YOUR_CLIENT_ID` in `.env` with your **Client ID**
        9. Replace `YOUR_CLIENT_SECRET` in `.env` with your **Client Secret**

        Generate a secure secret for `AUTH0_SECRET`:

        ```bash theme={null}
        openssl rand -hex 64
        ```

        <Info>
          **Important:** Never commit your `.env` file to version control. Add it to `.gitignore`.
        </Info>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Create Auth Configuration, Routes, and Templates">
    Create files

    ```bash theme={null}
    mkdir templates static && touch app.py auth.py templates/index.html templates/profile.html static/style.css
    ```

    And add the following code snippets:

    <AuthCodeGroup>
      ```python auth.py expandable lines theme={null}
      import os
      from auth0_server_python.auth_server.server_client import ServerClient
      from dotenv import load_dotenv

      load_dotenv()

      # Simple in-memory storage for development
      # For production, use Redis, PostgreSQL, or other persistent storage
      class MemoryStateStore:
          """In-memory state store for session data (development only)"""
          def __init__(self):
              self._data = {}
          
          async def get(self, key, options=None):
              return self._data.get(key)
          
          async def set(self, key, value, options=None):
              self._data[key] = value
          
          async def delete(self, key, options=None):
              self._data.pop(key, None)
          
          async def delete_by_logout_token(self, claims, options=None):
              # For backchannel logout support
              pass

      class MemoryTransactionStore:
          """In-memory transaction store for OAuth flows (development only)"""
          def __init__(self):
              self._data = {}
          
          async def get(self, key, options=None):
              return self._data.get(key)
          
          async def set(self, key, value, options=None):
              self._data[key] = value
          
          async def delete(self, key, options=None):
              self._data.pop(key, None)

      # Initialize stores
      state_store = MemoryStateStore()
      transaction_store = MemoryTransactionStore()

      # Initialize the Auth0 ServerClient
      auth0 = ServerClient(
          domain=os.getenv('AUTH0_DOMAIN'),
          client_id=os.getenv('AUTH0_CLIENT_ID'),
          client_secret=os.getenv('AUTH0_CLIENT_SECRET'),
          secret=os.getenv('AUTH0_SECRET'),
          redirect_uri=os.getenv('AUTH0_REDIRECT_URI'),
          state_store=state_store,
          transaction_store=transaction_store,
          authorization_params={
              'scope': 'openid profile email',
              'audience': os.getenv('AUTH0_AUDIENCE', '')  # Optional: for API access
          }
      )
      ```

      ```python app.py expandable lines theme={null}
      import os
      from flask import Flask, redirect, render_template, request, url_for, g
      from auth import auth0
      from dotenv import load_dotenv

      load_dotenv()

      app = Flask(__name__)
      app.secret_key = os.getenv('AUTH0_SECRET')

      # Configure session for Auth0
      app.config.update(
          SESSION_COOKIE_SECURE=False,  # Set to True in production with HTTPS
          SESSION_COOKIE_HTTPONLY=True,
          SESSION_COOKIE_SAMESITE='Lax',
      )

      @app.before_request
      def store_request_response():
          """Make request/response available for Auth0 SDK"""
          g.store_options = {"request": request}

      @app.route('/')
      async def index():
          """Home page - shows login button or user profile"""
          user = await auth0.get_user(g.store_options)
          return render_template('index.html', user=user)

      @app.route('/login')
      async def login():
          """Redirect to Auth0 login"""
          authorization_url = await auth0.start_interactive_login({}, g.store_options)
          return redirect(authorization_url)

      @app.route('/callback')
      async def callback():
          """Handle Auth0 callback after login"""
          try:
              result = await auth0.complete_interactive_login(str(request.url), g.store_options)
              return redirect(url_for('index'))
          except Exception as e:
              return f"Authentication error: {str(e)}", 400

      @app.route('/profile')
      async def profile():
          """Protected route - shows user profile"""
          user = await auth0.get_user(g.store_options)
          
          if not user:
              return redirect(url_for('login'))
          
          return render_template('profile.html', user=user)

      @app.route('/logout')
      async def logout():
          """Logout and redirect to Auth0 logout"""
          logout_url = await auth0.logout(g.store_options)
          return redirect(logout_url)

      if __name__ == '__main__':
          app.run(debug=True, port=5000)
      ```

      ```html templates/index.html expandable lines theme={null}
      <!DOCTYPE html>
      <html lang="en">
      <head>
      <meta charset="UTF-8">
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <title>Flask + Auth0</title>
      <link rel="stylesheet" href="{{ url_for('static', filename='style.css') }}">
      </head>
      <body>
      <div class="container">
          <div class="card">
              <img src="https://cdn.auth0.com/quantum-assets/dist/latest/logos/auth0/auth0-lockup-en-ondark.png"
                   alt="Auth0 Logo" class="logo">
              <h1>Flask + Auth0</h1>
              
              {% if user %}
                  <div class="logged-in">
                      <p class="success">✅ Successfully logged in!</p>
                      <div class="user-info">
                          {% if user.picture %}
                          <img src="{{ user.picture }}" alt="Profile" class="profile-pic">
                          {% endif %}
                          <h2>{{ user.name }}</h2>
                          <p>{{ user.email }}</p>
                      </div>
                      <a href="/profile" class="button">View Full Profile</a>
                      <a href="/logout" class="button logout">Log Out</a>
                  </div>
              {% else %}
                  <div class="logged-out">
                      <p>Welcome! Please log in to access your protected content.</p>
                      <a href="/login" class="button">Log In</a>
                  </div>
              {% endif %}
          </div>
      </div>
      </body>
      </html>
      ```

      ```html templates/profile.html expandable lines theme={null}
      <!DOCTYPE html>
      <html lang="en">
      <head>
      <meta charset="UTF-8">
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <title>User Profile - Flask + Auth0</title>
      <link rel="stylesheet" href="{{ url_for('static', filename='style.css') }}">
      </head>
      <body>
      <div class="container">
          <div class="card">
              <img src="https://cdn.auth0.com/quantum-assets/dist/latest/logos/auth0/auth0-lockup-en-ondark.png"
                   alt="Auth0 Logo" class="logo">
              <h1>User Profile</h1>
              
              <div class="profile-details">
                  {% if user.picture %}
                  <img src="{{ user.picture }}" alt="Profile" class="profile-pic-large">
                  {% endif %}
                  
                  <div class="profile-info">
                      <h2>{{ user.name }}</h2>
                      <p class="email">{{ user.email }}</p>
                      
                      <div class="profile-data">
                          <h3>Profile Information</h3>
                          <dl>
                              <dt>User ID:</dt>
                              <dd>{{ user.sub }}</dd>
                              
                              {% if user.nickname %}
                              <dt>Nickname:</dt>
                              <dd>{{ user.nickname }}</dd>
                              {% endif %}
                              
                              {% if user.updated_at %}
                              <dt>Last Updated:</dt>
                              <dd>{{ user.updated_at }}</dd>
                              {% endif %}
                          </dl>
                      </div>
                  </div>
              </div>
              
              <div class="actions">
                  <a href="/" class="button">Back to Home</a>
                  <a href="/logout" class="button logout">Log Out</a>
              </div>
          </div>
      </div>
      </body>
      </html>
      ```

      ```css static/style.css expandable lines theme={null}
      @import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap');

      * {
      margin: 0;
      padding: 0;
      box-sizing: border-box;
      }

      body {
      font-family: 'Inter', sans-serif;
      background: linear-gradient(135deg, #1a1e27 0%, #2d313c 100%);
      min-height: 100vh;
      display: flex;
      justify-content: center;
      align-items: center;
      color: #e2e8f0;
      padding: 20px;
      }

      .container {
      width: 100%;
      max-width: 600px;
      }

      .card {
      background-color: #262a33;
      border-radius: 20px;
      box-shadow: 0 20px 60px rgba(0, 0, 0, 0.6), 0 0 0 1px rgba(255, 255, 255, 0.05);
      padding: 3rem;
      animation: fadeInScale 0.6s ease-out;
      }

      @keyframes fadeInScale {
      from {
          opacity: 0;
          transform: scale(0.95);
      }
      to {
          opacity: 1;
          transform: scale(1);
      }
      }

      .logo {
      width: 160px;
      margin: 0 auto 2rem;
      display: block;
      animation: slideDown 0.8s ease-out;
      }

      @keyframes slideDown {
      from {
          opacity: 0;
          transform: translateY(-30px);
      }
      to {
          opacity: 1;
          transform: translateY(0);
      }
      }

      h1 {
      font-size: 2.5rem;
      font-weight: 700;
      text-align: center;
      margin-bottom: 2rem;
      color: #f7fafc;
      text-shadow: 0 4px 10px rgba(0, 0, 0, 0.3);
      }

      h2 {
      font-size: 1.8rem;
      font-weight: 600;
      margin: 0.5rem 0;
      color: #f7fafc;
      }

      h3 {
      font-size: 1.3rem;
      font-weight: 600;
      margin-top: 1.5rem;
      margin-bottom: 1rem;
      color: #cbd5e0;
      }

      .logged-in, .logged-out {
      text-align: center;
      }

      .logged-out p {
      font-size: 1.2rem;
      color: #cbd5e0;
      margin-bottom: 2rem;
      line-height: 1.6;
      }

      .success {
      font-size: 1.5rem;
      color: #68d391;
      font-weight: 600;
      margin-bottom: 1.5rem;
      }

      .user-info {
      background-color: #2d313c;
      border-radius: 15px;
      padding: 2rem;
      margin: 2rem 0;
      }

      .profile-pic {
      width: 80px;
      height: 80px;
      border-radius: 50%;
      margin-bottom: 1rem;
      border: 3px solid #63b3ed;
      object-fit: cover;
      }

      .profile-pic-large {
      width: 120px;
      height: 120px;
      border-radius: 50%;
      margin-bottom: 1rem;
      border: 4px solid #63b3ed;
      object-fit: cover;
      }

      .user-info p, .email {
      color: #a0aec0;
      font-size: 1.1rem;
      }

      .button {
      display: inline-block;
      padding: 1rem 2.5rem;
      font-size: 1.1rem;
      font-weight: 600;
      border-radius: 10px;
      border: none;
      cursor: pointer;
      transition: all 0.3s cubic-bezier(0.25, 0.8, 0.25, 1);
      text-decoration: none;
      text-transform: uppercase;
      letter-spacing: 0.08em;
      margin: 0.5rem;
      background-color: #63b3ed;
      color: #1a1e27;
      box-shadow: 0 8px 20px rgba(0, 0, 0, 0.4);
      }

      .button:hover {
      background-color: #4299e1;
      transform: translateY(-3px);
      box-shadow: 0 12px 25px rgba(0, 0, 0, 0.5);
      }

      .button.logout {
      background-color: #fc8181;
      }

      .button.logout:hover {
      background-color: #e53e3e;
      }

      .profile-details {
      text-align: center;
      }

      .profile-info {
      background-color: #2d313c;
      border-radius: 15px;
      padding: 2rem;
      margin-top: 1.5rem;
      }

      .profile-data {
      margin-top: 2rem;
      text-align: left;
      }

      .profile-data dl {
      display: grid;
      grid-template-columns: 150px 1fr;
      gap: 1rem;
      margin-top: 1rem;
      }

      .profile-data dt {
      font-weight: 600;
      color: #cbd5e0;
      }

      .profile-data dd {
      color: #a0aec0;
      word-break: break-all;
      }

      .actions {
      margin-top: 2rem;
      display: flex;
      justify-content: center;
      flex-wrap: wrap;
      }

      @media (max-width: 600px) {
      .card {
          padding: 2rem;
      }

      h1 {
          font-size: 2rem;
      }

      .button {
          padding: 0.8rem 2rem;
          font-size: 1rem;
      }

      .logo {
          width: 120px;
      }

      .profile-data dl {
          grid-template-columns: 1fr;
          gap: 0.5rem;
      }

      .profile-data dt {
          margin-top: 1rem;
      }
      }
      ```
    </AuthCodeGroup>

    <Info>
      **Development Only:** This example uses simple in-memory storage classes (`MemoryStateStore` and `MemoryTransactionStore`) for demonstration purposes. These stores will lose all session data when your application restarts and won't work in multi-instance deployments.

      **For production applications**, you must implement persistent storage. The SDK is framework-agnostic and requires you to provide custom `StateStore` and `TransactionStore` implementations. See the [official SDK storage examples](https://github.com/auth0/auth0-server-python/blob/main/examples/ConfigureStore.md) for detailed guidance on implementing Redis, PostgreSQL, or other persistent storage backends.
    </Info>
  </Step>

  <Step title="Run your app">
    Start the Flask development server:

    ```bash theme={null}
    python app.py
    ```

    Your app will be available at [http://localhost:5000](http://localhost:5000). The Auth0 SDK handles authentication routes automatically.
  </Step>
</Steps>

<Check>
  **Checkpoint**

  You should now have a fully functional Auth0 login page running on your [localhost](http://localhost:5000/)
</Check>

***

## Advanced Usage

<Accordion title="Accessing API Tokens">
  If you need to call a protected API, retrieve an access token:

  ```python theme={null}
  @app.route('/api-call')
  @require_auth
  async def api_call():
      try:
          # Get access token for your API
          access_token = await auth0.get_access_token(
              audience='https://your-api.example.com',
              store_options=g.store_options
          )
          
          # Use the token to call your API
          # headers = {'Authorization': f'Bearer {access_token}'}
          # response = requests.get('https://your-api.example.com/data', headers=headers)
          
          return f"Access token retrieved: {access_token[:20]}..."
      except Exception as e:
          return f"Error getting access token: {str(e)}", 500
  ```

  <Info>
    To use this feature, you must:

    1. Set `AUTH0_AUDIENCE` in your `.env` file
    2. Include `offline_access` in your scopes (for refresh tokens)
    3. Update `authorization_params` in `auth.py`:
       ```python theme={null}
       authorization_params={
           'scope': 'openid profile email offline_access',
           'audience': os.getenv('AUTH0_AUDIENCE')
       }
       ```
  </Info>
</Accordion>

<Accordion title="Custom Storage Configuration">
  By default, the SDK uses cookie-based storage. For production environments with specific needs (horizontal scaling, session sharing across services), you can configure custom storage backends like Redis or PostgreSQL.

  **When to use custom storage:**

  * You need to share sessions across multiple servers
  * You have large session data exceeding cookie size limits
  * You need centralized session management for backchannel logout

  **Redis Example:**

  ```python auth.py theme={null}
  from auth0_server_python.stores.redis_state_store import RedisStateStore
  import redis.asyncio as redis

  # Initialize custom state store
  redis_client = redis.from_url(os.getenv('REDIS_URL', 'redis://localhost:6379'))
  state_store = RedisStateStore(
      secret=os.getenv('AUTH0_SECRET'),
      redis_client=redis_client
  )

  # Pass to ServerClient
  auth0 = ServerClient(
      domain=os.getenv('AUTH0_DOMAIN'),
      client_id=os.getenv('AUTH0_CLIENT_ID'),
      client_secret=os.getenv('AUTH0_CLIENT_SECRET'),
      secret=os.getenv('AUTH0_SECRET'),
      redirect_uri=os.getenv('AUTH0_REDIRECT_URI'),
      state_store=state_store,  # Custom storage
      authorization_params={'scope': 'openid profile email'}
  )
  ```

  <Info>
    For most applications, the default cookie-based storage is sufficient. Custom storage requires implementing the `StateStore` interface. See the [SDK examples](https://github.com/auth0/auth0-server-python/blob/main/examples/ConfigureStore.md) for detailed implementations.
  </Info>
</Accordion>

***

## Common Issues

<AccordionGroup>
  <Accordion title="MissingRequiredArgumentError">
    **Problem:** You see "MissingRequiredArgumentError: secret" when starting the app

    **Cause:** The `AUTH0_SECRET` environment variable is missing or not loaded properly.

    **Solution:**

    1. Verify your `.env` file exists in the project root
    2. Ensure `python-dotenv` is installed: `pip install python-dotenv`
    3. Generate a new secret if needed: `openssl rand -hex 64`
    4. Add it to `.env`: `AUTH0_SECRET=your_generated_secret`
    5. Restart your Flask application
  </Accordion>

  <Accordion title="Invalid Callback URL Error">
    **Problem:** You see "Callback URL mismatch" or "invalid\_request" error during login

    **Cause:** The redirect URI in your code doesn't match what's registered in Auth0 Dashboard.

    **Solution:**

    1. Check your `.env` file: `AUTH0_REDIRECT_URI=http://localhost:5000/callback`
    2. Go to [Auth0 Dashboard](https://manage.auth0.com/dashboard/) → Applications → Your App → Settings
    3. Add `http://localhost:5000/callback` to **Allowed Callback URLs**
    4. Click **Save Changes**
    5. Restart your Flask application
  </Accordion>

  <Accordion title="AsyncIO Event Loop Errors">
    **Problem:** You see "RuntimeError: This event loop is already running" or similar async errors

    **Cause:** Flask 2.0+ async support may have issues with certain configurations.

    **Solution:**

    Install Flask with async support:

    ```bash theme={null}
    pip install "flask[async]"
    ```

    Then restart your Flask application.
  </Accordion>

  <Accordion title="Module Not Found Errors">
    **Problem:** You see "ModuleNotFoundError: No module named 'auth0\_server\_python'" or similar

    **Cause:** The SDK is not installed or the virtual environment is not activated.

    **Solution:**

    1. Ensure your virtual environment is activated:
       ```bash theme={null}
       source venv/bin/activate  # macOS/Linux
       # or
       venv\Scripts\activate  # Windows
       ```
    2. Install the SDK:
       ```bash theme={null}
       pip install auth0-server-python "flask[async]" python-dotenv
       ```
    3. Verify installation:

    ```bash theme={null}
    pip list | grep auth0
    ```
  </Accordion>

  <Accordion title="ClaimDecodingFailed Error">
    **Problem:** You see "ClaimDecodingFailed" or "Failed to decode claims" error during authentication

    **Cause:** The ID token or access token received from Auth0 couldn't be properly decoded, often due to:

    * Invalid JWT format
    * Corrupted session data
    * Mismatched signing algorithms
    * Clock skew between your server and Auth0

    **Solution:**

    1. Ensure your `AUTH0_CLIENT_SECRET` is correct in the `.env` file
    2. Check your system time is synchronized (NTP):
       ```bash theme={null}
       # macOS
       sudo sntp -sS time.apple.com

       # Linux
       sudo ntpdate -s time.nist.gov
       ```
    3. Clear browser cookies and restart authentication
    4. Verify the `AUTH0_DOMAIN` doesn't include `https://` prefix
    5. Check Auth0 Dashboard → Applications → Your App → Settings → Advanced → OAuth → JsonWebToken Signature Algorithm matches your SDK configuration
  </Accordion>

  <Accordion title="Token Expired or Invalid">
    **Problem:** You see "Token has expired" or "invalid\_token" errors

    **Cause:** The access token or ID token has exceeded its lifetime, or the session has expired.

    **Solution:**

    1. The SDK automatically handles token refresh if you include `offline_access` scope:
       ```python theme={null}
       authorization_params={
           'scope': 'openid profile email offline_access',
       }
       ```
    2. For APIs, ensure you're requesting fresh tokens:
       ```python theme={null}
       access_token = await auth0.get_access_token(
           audience='https://your-api.example.com',
           force_refresh=True  # Force refresh if needed
       )
       ```
    3. Adjust token lifetimes in Auth0 Dashboard → Applications → Your App → Settings → Advanced → OAuth
    4. Implement proper error handling to redirect users to login when tokens expire
  </Accordion>

  <Accordion title="CORS and Cross-Origin Errors">
    **Problem:** You see CORS errors or "Blocked by CORS policy" in browser console

    **Cause:** Your application's origin isn't properly configured in Auth0.

    **Solution:**

    1. Add your origin to Auth0 Dashboard → Applications → Your App → Settings:
       * **Allowed Web Origins**: `http://localhost:5000`
       * **Allowed Callback URLs**: `http://localhost:5000/callback`
       * **Allowed Logout URLs**: `http://localhost:5000`
    2. For production, add your production URLs:
       ```
       https://yourdomain.com
       https://yourdomain.com/callback
       ```
    3. Ensure your Flask app has proper CORS configuration if calling Auth0 APIs from frontend JavaScript:
       ```python theme={null}
       from flask_cors import CORS
       CORS(app, origins=['http://localhost:5000'])
       ```
  </Accordion>

  <Accordion title="Rate Limit Exceeded">
    **Problem:** You see "Too many requests" or "Rate limit exceeded" errors

    **Cause:** Your application has exceeded Auth0's rate limits for authentication requests.

    **Solution:**

    1. Check Auth0 Dashboard → Monitoring → Logs for rate limit details
    2. Implement exponential backoff for retries:
       ```python theme={null}
       import time
       from auth0_server_python.error import ApiError

       async def login_with_retry():
           max_retries = 3
           for attempt in range(max_retries):
               try:
                   return await auth0.start_interactive_login({}, g.store_options)
               except ApiError as e:
                   if e.status_code == 429 and attempt < max_retries - 1:
                       wait_time = 2 ** attempt
                       time.sleep(wait_time)
                   else:
                       raise
       ```
    3. Review your Auth0 subscription plan limits
    4. Optimize authentication flow to reduce unnecessary token requests
    5. Cache tokens appropriately instead of requesting new ones frequently
  </Accordion>
</AccordionGroup>


# Add Login to Your Ruby on Rails Application
Source: https://auth0.com/docs/quickstart/webapp/rails/interactive

This tutorial demonstrates how to add user login to a Ruby on Rails application.

<QuickstartButtons />

<Recipe>
  <Content>
    <Section title={sections[0].title}>
      To use Auth0 services, you’ll need to have an application set up in the Auth0 Dashboard. The Auth0 application is
      where you will configure how you want authentication to work for the project you are developing.

      ### Configure an application

      Use the interactive selector to create a new Auth0 application or select an existing application that represents
      the project you want to integrate with. Every application in Auth0 is assigned an alphanumeric, unique client ID
      that your application code will use to call Auth0 APIs through the SDK.

      Any settings you configure using this quickstart will automatically update for your Application in the [Dashboard](https://manage.auth0.com/#/), which is where you
      can manage your Applications in the future.

      If you would rather explore a complete configuration, you can view a sample application instead.

      ### Configure Callback URLs

      A callback URL is a URL in your application that you would like Auth0 to redirect users to after they have
      authenticated. If not set, users will not be returned to your application after they log in.

      <Info>
        If you are following along with our sample project, set this to
        `http://localhost:3000/auth/auth0/callback`.
      </Info>

      ### Configure Logout URLs

      A logout URL is a URL in your application that you would like Auth0 to redirect users to after they have logged
      out. If not set, users will not be able to log out from your application and will receive an error.

      <Info>
        If you are following along with our sample project, set this to `http://localhost:3000`.
      </Info>

      ### Configure Allowed Web Origins

      An Allowed Web Origin is a URL that you want to be allowed to access to your authentication flow. This must
      contain the URL of your project. If not properly set, your project will be unable to silently refresh
      authentication tokens, so your users will be logged out the next time they visit your application or refresh a
      page.

      <Info>
        If you are following along with our sample project, set this to `http://localhost:3000`.
      </Info>
    </Section>

    <Section title={sections[1].title}>
      Use `omniauth-auth0`, a custom [OmniAuth strategy](https://github.com/intridea/omniauth#omniauth-standardized-multi-provider-authentication), to handle the authentication flow.

      Add the following dependencies to your `Gemfile`:

      ```gem lines theme={null}
      gem 'omniauth-auth0', '~> 3.0'
      gem 'omniauth-rails_csrf_protection', '~> 1.0' # prevents forged authentication requests
      ```

      Once your gems are added, install the gems with `bundle install`.
    </Section>

    <Section title={sections[2].title}>
      Create a configuration file `./config/auth0.yml` to specify your Auth0 domain, client ID, and client
      secret values located in your Auth0 Dashboard under application **Settings**.
    </Section>

    <Section title={sections[3].title}>
      Create the following initializer file `./config/initializers/auth0.rb` and [configure](https://github.com/auth0/omniauth-auth0/blob/master/EXAMPLES.md#send-additional-authentication-parameters) the **OmniAuth** middleware with the configuration
      file you created in the previous step.

      Ensure that `callback_path` matches the value given in the "Allowed Callback URLs" setting in your
      Auth0 application.
    </Section>

    <Section title={sections[4].title}>
      Create an Auth0 controller to handle the authentication callback, `logout` action, and methods for
      constructing the logout URL.

      Run the command:
      `rails generate controller auth0 callback failure logout --skip-assets --skip-helper --skip-routes --skip-template-engine`.

      Inside the callback method, assign the hash of user information - returned as
      `request.env['omniauth.auth']` - to the active session.

      To configure logout, clear all the objects stored within the session by calling the `reset_session`
      method within the `logout` action. Then, redirect to the Auth0 logout endpoint. To learn more about
      `reset_session`, read [Ruby on Rails ActionController documentation](http://api.rubyonrails.org/classes/ActionController/Base.html#M000668).
    </Section>

    <Section title={sections[5].title}>
      Add these routes to your `./config/routes.rb` file.

      Routes must be in place so Rails knows how to route the various Auth0 callback URLs to the Auth0 controller you
      created in the previous step.

      <Info>
        ##### Checkpoint

        Run your application to verify it continues to work as intended and you aren't receive any errors
        relating to Auth0.
      </Info>
    </Section>

    <Section title={sections[6].title}>
      A user can now log into your application by visiting the `/auth/auth0` endpoint.

      <Warning>
        To [prevent forged authentication requests](https://github.com/cookpad/omniauth-rails_csrf_protection), use the `link_to` or
        `button_to` helper methods with the `:post` method.
      </Warning>

      ```ruby lines theme={null}
      <!-- Place a login button anywhere on your application -->
      <%= button_to 'Login', '/auth/auth0', method: :post %>
      ```

      <Info>
        ##### Checkpoint

        Add a button to your application that redirects the user to the `/auth/auth0` endpoint when
        selected. Observe that you redirect to Auth0 to log in, and then back to your app after successful
        authentication.
      </Info>
    </Section>

    <Section title={sections[7].title}>
      Now that you can log in to your Rails application, you need a
      way to log out. Log out a user by redirecting to the `auth/logout` action, which redirects them
      to the Auth0 logout endpoint.

      <Info>
        To test this after the previous step, you may need to clear out your session and then redirect the user
        to the Auth0 logout endpoint.
      </Info>

      ```ruby lines theme={null}
      <!-- Place a logout button anywhere on your application -->
      <%= button_to 'Logout', 'auth/logout', method: :get %>
      ```

      <Info>
        ##### Checkpoint

        Add a button to your application that redirects the user to the `/auth/logout` endpoint when
        selected. Verify that you redirect to Auth0 and then quickly back to your application, and that you are no
        longer logged in.
      </Info>
    </Section>

    <Section title={sections[8].title}>
      To display the user's profile, your application should provide a protected route. You can use a [Concern](https://guides.rubyonrails.org/getting_started.html#using-concerns) to control access to routes that can be shared across multiple
      controllers. The concern should automatically redirect to Auth0 when the user is unauthenticated. Otherwise, the
      concern should return the current user profile.

      Once you have a Concern, include it in any controller that requires a logged-in user. You can then access the
      user from the session `session[:userinfo]` as in the following example:

      ```ruby lines theme={null}
      class DashboardController < ApplicationController
      include Secured
      def show
      @user = session[:userinfo]

      end
      end
      ```

      Once the user loads from the session, use it to display information in your frontend:

      ```html lines theme={null}
      <div>
      <p>Normalized User Profile:<%= JSON.pretty_generate(@user[:info])%></p>
      <p>Full User Profile:<%= JSON.pretty_generate(@user[:extra][:raw_info])%></p>
      </div>
      ```

      <Info>
        ##### Checkpoint

        Add the `Secured` concern to your app and then include it in the controller that requires an
        authenticated user to access it. Verify that an authenticated user has access to actions within that
        controller and that unauthenticated users are redirected to Auth0 for authentication.
      </Info>
    </Section>

    ## Next Steps

    Excellent work! If you made it this far, you should now have login, logout, and user profile information running in your application.

    This concludes our quickstart tutorial, but there is so much more to explore. To learn more about what you can do with Auth0, check out:

    * [Auth0 Dashboard](https://manage.auth0.com/dashboard/us/dev-gja8kxz4ndtex3rq) - Learn how to configure and manage your Auth0 tenant and applications
    * [omniauth-auth0 SDK](https://github.com/auth0/omniauth-auth0) - Explore the SDK used in this tutorial more fully
    * [Auth0 Marketplace](https://marketplace.auth0.com/) - Discover integrations you can enable to extend Auth0’s functionality
  </Content>

  <SideMenu>
    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```yml config/auth0.yml lines theme={null}
        development:
          auth0_domain: {yourDomain}
          auth0_client_id: {yourClientId}
          auth0_client_secret: {yourClientSecret}
        ```

        ```ruby auth0.rb lines theme={null}
        AUTH0_CONFIG = Rails.application.config_for(:auth0)

        Rails.application.config.middleware.use OmniAuth::Builder do
          provider(
            :auth0,
            AUTH0_CONFIG['auth0_client_id'],
            AUTH0_CONFIG['auth0_client_secret'],
            AUTH0_CONFIG['auth0_domain'],
            callback_path: '/auth/auth0/callback',
            authorize_params: {
              scope: 'openid profile'
            }
          )
        end
        ```

        ```ruby auth0_controller.rb lines  theme={null}
        class Auth0Controller < ApplicationController
          def callback
            # OmniAuth stores the informatin returned from
            # Auth0 and the IdP in request.env['omniauth.auth'].
            # In this code, you will pull the raw_info supplied 
            # from the id_token and assign it to the session.
            # Refer to https://github.com/auth0/omniauth-auth0/blob/master/EXAMPLES.md#example-of-the-resulting-authentication-hash 
            # for complete information on 'omniauth.auth' contents.
            auth_info = request.env['omniauth.auth']
            session[:userinfo] = auth_info['extra']['raw_info']

            # Redirect to the URL you want after successful auth
            redirect_to '/dashboard'
          end

          def failure
            # Handles failed authentication
            @error_msg = request.params['message']
          end

          def logout
            reset_session
            redirect_to logout_url
          end

          private
          AUTH0_CONFIG = Rails.application.config_for(:auth0)

          def logout_url
            request_params = {
              returnTo: root_url,
              client_id: AUTH0_CONFIG['auth0_client_id']
            }

            URI::HTTPS.build(host: AUTH0_CONFIG['auth0_domain'], path: '/v2/logout', query: to_query(request_params)).to_s
          end

          def to_query(hash)
            hash.map { |k, v| "#{k}=#{CGI.escape(v)}" unless v.nil? }.reject(&:nil?).join('&')
          end
        end
        ```

        ```ruby routes.rb lines theme={null}
        Rails.application.routes.draw do
        # . .
          get '/auth/auth0/callback' => 'auth0#callback'
          get '/auth/failure' => 'auth0#failure'
          get '/auth/logout' => 'auth0#logout'
        end
        ```

        ```ruby secured.rb lines theme={null}
        module Secured
          extend ActiveSupport::Concern

          included do
            before_action :logged_in_using_omniauth?
          end

          def logged_in_using_omniauth?
            redirect_to '/' unless session[:userinfo].present?
          end
        end
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```ruby auth0.rb lines theme={null}
        AUTH0_CONFIG = Rails.application.config_for(:auth0)

        Rails.application.config.middleware.use OmniAuth::Builder do
          provider(
            :auth0,
            AUTH0_CONFIG['auth0_client_id'],
            AUTH0_CONFIG['auth0_client_secret'],
            AUTH0_CONFIG['auth0_domain'],
            callback_path: '/auth/auth0/callback',
            authorize_params: {
              scope: 'openid profile'
            }
          )
        end
        ```

        ```yml config/auth0.yml lines theme={null}
        development:
          auth0_domain: {yourDomain}
          auth0_client_id: {yourClientId}
          auth0_client_secret: {yourClientSecret}
        ```

        ```ruby auth0_controller.rb lines  theme={null}
        class Auth0Controller < ApplicationController
          def callback
            # OmniAuth stores the informatin returned from
            # Auth0 and the IdP in request.env['omniauth.auth'].
            # In this code, you will pull the raw_info supplied 
            # from the id_token and assign it to the session.
            # Refer to https://github.com/auth0/omniauth-auth0/blob/master/EXAMPLES.md#example-of-the-resulting-authentication-hash 
            # for complete information on 'omniauth.auth' contents.
            auth_info = request.env['omniauth.auth']
            session[:userinfo] = auth_info['extra']['raw_info']

            # Redirect to the URL you want after successful auth
            redirect_to '/dashboard'
          end

          def failure
            # Handles failed authentication
            @error_msg = request.params['message']
          end

          def logout
            reset_session
            redirect_to logout_url
          end

          private
          AUTH0_CONFIG = Rails.application.config_for(:auth0)

          def logout_url
            request_params = {
              returnTo: root_url,
              client_id: AUTH0_CONFIG['auth0_client_id']
            }

            URI::HTTPS.build(host: AUTH0_CONFIG['auth0_domain'], path: '/v2/logout', query: to_query(request_params)).to_s
          end

          def to_query(hash)
            hash.map { |k, v| "#{k}=#{CGI.escape(v)}" unless v.nil? }.reject(&:nil?).join('&')
          end
        end
        ```

        ```ruby routes.rb lines theme={null}
        Rails.application.routes.draw do
        # . .
          get '/auth/auth0/callback' => 'auth0#callback'
          get '/auth/failure' => 'auth0#failure'
          get '/auth/logout' => 'auth0#logout'
        end
        ```

        ```ruby secured.rb lines theme={null}
        module Secured
          extend ActiveSupport::Concern

          included do
            before_action :logged_in_using_omniauth?
          end

          def logged_in_using_omniauth?
            redirect_to '/' unless session[:userinfo].present?
          end
        end
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```ruby auth0_controller.rb lines  theme={null}
        class Auth0Controller < ApplicationController
          def callback
            # OmniAuth stores the informatin returned from
            # Auth0 and the IdP in request.env['omniauth.auth'].
            # In this code, you will pull the raw_info supplied 
            # from the id_token and assign it to the session.
            # Refer to https://github.com/auth0/omniauth-auth0/blob/master/EXAMPLES.md#example-of-the-resulting-authentication-hash 
            # for complete information on 'omniauth.auth' contents.
            auth_info = request.env['omniauth.auth']
            session[:userinfo] = auth_info['extra']['raw_info']

            # Redirect to the URL you want after successful auth
            redirect_to '/dashboard'
          end

          def failure
            # Handles failed authentication
            @error_msg = request.params['message']
          end

          def logout
            reset_session
            redirect_to logout_url
          end

          private
          AUTH0_CONFIG = Rails.application.config_for(:auth0)

          def logout_url
            request_params = {
              returnTo: root_url,
              client_id: AUTH0_CONFIG['auth0_client_id']
            }

            URI::HTTPS.build(host: AUTH0_CONFIG['auth0_domain'], path: '/v2/logout', query: to_query(request_params)).to_s
          end

          def to_query(hash)
            hash.map { |k, v| "#{k}=#{CGI.escape(v)}" unless v.nil? }.reject(&:nil?).join('&')
          end
        end
        ```

        ```yml config/auth0.yml lines theme={null}
        development:
          auth0_domain: {yourDomain}
          auth0_client_id: {yourClientId}
          auth0_client_secret: {yourClientSecret}
        ```

        ```ruby auth0.rb lines theme={null}
        AUTH0_CONFIG = Rails.application.config_for(:auth0)

        Rails.application.config.middleware.use OmniAuth::Builder do
          provider(
            :auth0,
            AUTH0_CONFIG['auth0_client_id'],
            AUTH0_CONFIG['auth0_client_secret'],
            AUTH0_CONFIG['auth0_domain'],
            callback_path: '/auth/auth0/callback',
            authorize_params: {
              scope: 'openid profile'
            }
          )
        end
        ```

        ```ruby routes.rb lines theme={null}
        Rails.application.routes.draw do
        # . .
          get '/auth/auth0/callback' => 'auth0#callback'
          get '/auth/failure' => 'auth0#failure'
          get '/auth/logout' => 'auth0#logout'
        end
        ```

        ```ruby secured.rb lines theme={null}
        module Secured
          extend ActiveSupport::Concern

          included do
            before_action :logged_in_using_omniauth?
          end

          def logged_in_using_omniauth?
            redirect_to '/' unless session[:userinfo].present?
          end
        end
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```ruby routes.rb lines theme={null}
        Rails.application.routes.draw do
        # . .
          get '/auth/auth0/callback' => 'auth0#callback'
          get '/auth/failure' => 'auth0#failure'
          get '/auth/logout' => 'auth0#logout'
        end
        ```

        ```yml config/auth0.yml lines theme={null}
        development:
          auth0_domain: {yourDomain}
          auth0_client_id: {yourClientId}
          auth0_client_secret: {yourClientSecret}
        ```

        ```ruby auth0.rb lines theme={null}
        AUTH0_CONFIG = Rails.application.config_for(:auth0)

        Rails.application.config.middleware.use OmniAuth::Builder do
          provider(
            :auth0,
            AUTH0_CONFIG['auth0_client_id'],
            AUTH0_CONFIG['auth0_client_secret'],
            AUTH0_CONFIG['auth0_domain'],
            callback_path: '/auth/auth0/callback',
            authorize_params: {
              scope: 'openid profile'
            }
          )
        end
        ```

        ```ruby auth0_controller.rb lines  theme={null}
        class Auth0Controller < ApplicationController
          def callback
            # OmniAuth stores the informatin returned from
            # Auth0 and the IdP in request.env['omniauth.auth'].
            # In this code, you will pull the raw_info supplied 
            # from the id_token and assign it to the session.
            # Refer to https://github.com/auth0/omniauth-auth0/blob/master/EXAMPLES.md#example-of-the-resulting-authentication-hash 
            # for complete information on 'omniauth.auth' contents.
            auth_info = request.env['omniauth.auth']
            session[:userinfo] = auth_info['extra']['raw_info']

            # Redirect to the URL you want after successful auth
            redirect_to '/dashboard'
          end

          def failure
            # Handles failed authentication
            @error_msg = request.params['message']
          end

          def logout
            reset_session
            redirect_to logout_url
          end

          private
          AUTH0_CONFIG = Rails.application.config_for(:auth0)

          def logout_url
            request_params = {
              returnTo: root_url,
              client_id: AUTH0_CONFIG['auth0_client_id']
            }

            URI::HTTPS.build(host: AUTH0_CONFIG['auth0_domain'], path: '/v2/logout', query: to_query(request_params)).to_s
          end

          def to_query(hash)
            hash.map { |k, v| "#{k}=#{CGI.escape(v)}" unless v.nil? }.reject(&:nil?).join('&')
          end
        end
        ```

        ```ruby secured.rb lines theme={null}
        module Secured
          extend ActiveSupport::Concern

          included do
            before_action :logged_in_using_omniauth?
          end

          def logged_in_using_omniauth?
            redirect_to '/' unless session[:userinfo].present?
          end
        end
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <SignUpForm />
    </SideMenuSectionItem>

    <SideMenuSectionItem>
      <AuthCodeGroup>
        ```ruby secured.rb lines theme={null}
        module Secured
          extend ActiveSupport::Concern

          included do
            before_action :logged_in_using_omniauth?
          end

          def logged_in_using_omniauth?
            redirect_to '/' unless session[:userinfo].present?
          end
        end
        ```

        ```yml config/auth0.yml lines theme={null}
        development:
          auth0_domain: {yourDomain}
          auth0_client_id: {yourClientId}
          auth0_client_secret: {yourClientSecret}
        ```

        ```ruby auth0.rb lines theme={null}
        AUTH0_CONFIG = Rails.application.config_for(:auth0)

        Rails.application.config.middleware.use OmniAuth::Builder do
          provider(
            :auth0,
            AUTH0_CONFIG['auth0_client_id'],
            AUTH0_CONFIG['auth0_client_secret'],
            AUTH0_CONFIG['auth0_domain'],
            callback_path: '/auth/auth0/callback',
            authorize_params: {
              scope: 'openid profile'
            }
          )
        end
        ```

        ```ruby auth0_controller.rb lines  theme={null}
        class Auth0Controller < ApplicationController
          def callback
            # OmniAuth stores the informatin returned from
            # Auth0 and the IdP in request.env['omniauth.auth'].
            # In this code, you will pull the raw_info supplied 
            # from the id_token and assign it to the session.
            # Refer to https://github.com/auth0/omniauth-auth0/blob/master/EXAMPLES.md#example-of-the-resulting-authentication-hash 
            # for complete information on 'omniauth.auth' contents.
            auth_info = request.env['omniauth.auth']
            session[:userinfo] = auth_info['extra']['raw_info']

            # Redirect to the URL you want after successful auth
            redirect_to '/dashboard'
          end

          def failure
            # Handles failed authentication
            @error_msg = request.params['message']
          end

          def logout
            reset_session
            redirect_to logout_url
          end

          private
          AUTH0_CONFIG = Rails.application.config_for(:auth0)

          def logout_url
            request_params = {
              returnTo: root_url,
              client_id: AUTH0_CONFIG['auth0_client_id']
            }

            URI::HTTPS.build(host: AUTH0_CONFIG['auth0_domain'], path: '/v2/logout', query: to_query(request_params)).to_s
          end

          def to_query(hash)
            hash.map { |k, v| "#{k}=#{CGI.escape(v)}" unless v.nil? }.reject(&:nil?).join('&')
          end
        end
        ```

        ```ruby routes.rb lines theme={null}
        Rails.application.routes.draw do
        # . .
          get '/auth/auth0/callback' => 'auth0#callback'
          get '/auth/failure' => 'auth0#failure'
          get '/auth/logout' => 'auth0#logout'
        end
        ```
      </AuthCodeGroup>
    </SideMenuSectionItem>
  </SideMenu>
</Recipe>


# Auth0 Quickstarts
Source: https://auth0.com/docs/quickstarts

Get started using Auth0. Implement authentication for any kind of application in minutes.

Step-by-step guides to quickly integrate Auth0 into your application

## Popular

Quickstarts for popular frameworks

<Columns>
  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />
</Columns>

## Single Page App

JavaScript web app that runs in the browser

<Columns>
  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />
</Columns>

## Regular Web App

Traditional web app that runs on the server

<Columns>
  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />
</Columns>

## Native/Mobile App

Mobile or Desktop app that runs natively on a device

<Columns>
  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />
</Columns>

## Backend/API

An API or service protected by Auth0

<Columns>
  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />
</Columns>


# Auth0 Blog
Source: https://auth0.com/docs/troubleshoot/auth0-blog





# Auth0 Community
Source: https://auth0.com/docs/troubleshoot/auth0-community





# Facebook Graph API Changes
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/facebook-graph-api-changes

The latest version of the Facebook Graph API changes what permissions and fields can be requested.

As of August 1, 2018, Facebook has changed the Facebook Graph API permissions and fields that can be requested. Auth0 has updated Facebook Connections to reflect these changes and modified the connection interface for clarity. See [Facebook Login Changelog: Recent Changes to Facebook Login](https://developers.facebook.com/docs/facebook-login/changelog#2018-07-02) for complete details and key dates.

## Features affected

The update may not require changes to your code or configuration, but your application might receive additional profile data if the existing permissions allow it. Keep in mind that:

* If your Facebook connection is configured to request one of the removed permissions, your <Tooltip href="/docs/glossary?term=Access+Token">Access Token</Tooltip> will not get them in scope.
* If your Facebook application is marked as "development" then you may still see an error temporarily while trying the connection.
* If you add new permissions to the connection, end users will be prompted for consent next time they log in. See the Facebook documentation for how to handle actions for users that don't have a specific permission.

### Facebook login permissions

[Facebook Login permissions](https://developers.facebook.com/docs/facebook-login/permissions) are requested by your application when a user logs in using Facebook. If the user is logging in for the first time or if the permissions have changed, they will be shown a consent window in Facebook showing the new permissions requested. Once those permissions are granted, your application can then act on behalf of that user with a Facebook access token.

The Facebook Connection interface has been updated to show both the regular name as well as the machine name for all permissions displayed. This makes it easier to find the permissions you need and map that to any code you might be running using these permission names.

#### Permissions added

The following permissions were added to the Facebook connection interface:

* business\_management
* groups\_access\_member\_info
* leads\_retrieval
* pages\_manage\_instant\_articles
* publish\_to\_groups
* publish\_to\_groups
* user\_age\_range
* user\_gender
* user\_link

#### Permissions removed

The following permissions were removed from the Facebook connection interface:

* read\_custom\_friendlists
* rsvp\_event
* user\_about\_me
* user\_actions-books
* user\_actions-fitness
* user\_actions-music
* user\_actions-news
* user\_actions-video
* user\_education\_history
* user\_games\_activity
* user\_relationship\_details
* user\_relationships
* user\_religion\_politics
* user\_website
* user\_work\_history

#### Permissions moved to deprecated

The following permissions were moved to the **Deprecated** section and should not be used with the latest version of the Graph API:

* publish\_actions
* user\_managed\_groups

### Facebook Graph API fields

The [Facebook Graph API](https://developers.facebook.com/docs/graph-api/reference/v3.2/user) is used after a user logs in to retrieve profile data for the Auth0 user. The user data permissions requested determine what information is retrieved from the Graph API. The fields that are returned depend on the permissions requested and the existence of those fields in the Facebook user profile.

This change upgraded the Graph API from v2.8 to v3.2 and will ask for the following user data fields on login:

* address (added)
* age\_range
* birthday
* context
* cover
* currency (added)
* devices
* email
* favorite\_athletes
* favorite\_teams
* first\_name
* gender
* hometown
* id
* inspirational\_people
* install\_type (added)
* installed
* is\_verified
* languages
* last\_name
* link
* locale
* location
* meeting\_for (added)
* middle\_name
* name
* name\_format
* picture
* public\_key (added)
* quotes
* security\_settings (added)
* short\_name (added)
* significant\_other
* sports (added)
* third\_party\_id
* timezone
* updated\_time
* verified
* video\_upload\_limits (added)
* viewer\_can\_send\_gift (added)


# Facebook Social Context Field Deprecation
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/facebook-social-context-field-deprecation

Describes changes occuring due to Facebook removing access to the social context field from their profile.

As of **July 30, 2020**, Facebook connections that request the `context` field will fail, so Auth0 will stop requesting it for all connections.

On April 30th [Facebook deprecated](https://developers.facebook.com/docs/graph-api/changelog/4-30-2019-endpoint-deprecations) the use of the **Social Context** field for new applications. Auth0 continued to request that field by default for Facebook connections created before April 30, 2019. You can make sure the field is not requested before July 30 by unchecking the **Social context** field in the User Data connection section:

<Frame>
  <img alt="Facebook Context Field Deprecation" />
</Frame>

Once you uncheck **Social context**, the profile data will not include the context field. The field has the following content:

```text lines theme={null}
"context": {
      "mutual_likes": {"data": [],"summary": {"total_count": 0}},
      "id": "dXNlcl9...UZD"
    }
```

## Actions

If you are not using the `context` field in the Facebook profile returned by Auth0 in your application, then your application will keep working without changes. Otherwise, you will need to adjust your application code so it does not rely on it.

To ensure that your application is not affected on July 30 we recommend that you uncheck the **Social context** field in the Facebook connection properties.


# Migrate from Google to Firebase Cloud Messaging
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/google-firebase-migration

Describes how to migrate your applications based on the Guardian Android SDK to Firebase Cloud Messaging

As of April 11, 2019, [Google deprecated](https://firebase.googleblog.com/2018/04/time-to-upgrade-from-gcm-to-fcm.html) and replaced Google Cloud Messaging (GCM) with Firebase Cloud Messaging (FCM).

## Features affected

Auth0’s Guardian SDKs for iOS and Android help you to create custom mobile apps with Guardian functionality, providing secure access to <Tooltip href="/docs/glossary?term=multi-factor+authentication">multi-factor authentication</Tooltip> (MFA) with push notifications.

Auth0's Guardian Android SDK library was built to send push notifications using GCM. Note that existing applications should [keep working as-is](https://aws.amazon.com/blogs/messaging-and-targeting/the-end-of-google-cloud-messaging-and-what-it-means-for-your-apps/).

## Actions

See [Google’s documentation](https://developers.google.com/cloud-messaging/android/android-migrate-fcm) to learn how to migrate from GCM to FCM.

The main difference between how you send notifications to GCM and FCM is in the payload received in the notification. While it was possible for existing customers using the Android SDK to adapt the payload received before calling the SDK method, we have upgraded the library so it accepts the new payload, making it simpler to adopt FCM. More details [here](https://github.com/auth0/Guardian.Android/pull/84).

The Guardian Android SDK 0.4.0 version is already available in Maven Central and includes this change. The sample application was also upgraded, so it can be tested by providing the `google-services.json` file and a `guardian-url`.


# Instagram Connection Deprecation
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/instagram-connection-deprecation

Describes changes occuring due to Instagram deprecating their Authentication API.

As of March 31, 2020, Facebook turned off the Instagram legacy APIs in favor of a new set of APIs:

* [Instagram Graph API](https://developers.facebook.com/docs/instagram-api) designed for Instagram Professional Accounts, not for end-user authentication.
* [Instagram Basic Display API](https://developers.facebook.com/docs/instagram-basic-display-api), an OAuth2 API, and enables you to grant access to your basic Instagram account data to a third-party app.

Facebook requires applications to implement Facebook Login for authentication. Facebook will not approve applications that use the Instagram Basic Display API for authentication.

## Actions

To allow your existing users continue to access your application, you will need to ask users that are authenticating using Instagram to authenticate in a different way, and use Account Linking to link the new identity with the old one.

An example flow would be:

* The user authenticates with Instagram.
* The application tells the user that they won't be able to authenticate with Instagram anymore, and that they should do it in a different way.
* The application lists the options the user has for authentication, for example:

  * Facebook
  * Username and Password
* After the user authenticates in a different way, you link the accounts using Account Linking.

While we could replace our current implementation and use the [Instagram Basic Display OAuth flow](https://developers.facebook.com/docs/instagram-basic-display-api/guides/getting-access-tokens-and-permissions), this would not be accepted by Facebook's policies. You would need to create an Instagram application in Facebook and, in that app, there's a notification saying:

<Callout icon="file-lines">
  Note that Basic Display is not an authentication tool. Data returned by the API cannot be used to authenticate your app users or log them into your app. If your app uses API data to authenticate users, it will be rejected during App Review. If you need an authentication solution, use Facebook Login instead.
</Callout>

This means that even if Auth0 implemented this flow, your Instagram application would not be approved by Facebook.

If you need to access Instagram data, you will need to authenticate your user in another way (for example, using Facebook Login or username/password), and implement the Instagram <Tooltip href="/docs/glossary?term=OAuth">OAuth</Tooltip> flow in your application.


# Migrate from Legacy Authentication Flows
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/migrate-from-legacy-auth-flows

Describes how to migrate from legacy authentication flows.

When using Lock versions below 11 and Auth0.js version below 9, you could use legacy authentication flows that are deprecated. Auth0 recommends that you migrate code from older versions of Auth0.js and Lock to the new OIDC-conformant APIs.

## Renew tokens

Legacy applications used <Tooltip href="/docs/glossary?term=Refresh+Tokens">Refresh Tokens</Tooltip> and the `refreshToken()` function as a way to get new tokens upon expiration (an example of this is below).

In auth0.js v9 and Lock 11 you need to use [Silent Authentication](/docs/authenticate/login/configure-silent-authentication) and `checkSession()`(an example of this is below).

## Call APIs

Legacy applications used an <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> to invoke APIs. This is a bad practice, and we recommend that you only use <Tooltip href="/docs/glossary?term=access+tokens">access tokens</Tooltip>.

To call an API, you will need to specify the API identifier as the `audience` parameter when initializing auth0.js or Lock.

If you specify an <Tooltip href="/docs/glossary?term=audience">audience</Tooltip>, then the OIDC flow will be triggered and the user profile data returned by Auth0 in ID tokens or from `/userinfo` will be OIDC conformant. If your application is using any non-standard claim from the user profile, it will break.

See the **Calling an API** section of our SPA Quickstarts for more information on how to call APIs from SPAs. You will also need to migrate your backend API implementation to use Access Tokens. See API Quickstarts for instructions on how to do this.

## User profiles

The legacy authentication flows that allow ID Tokens and the `/userinfo` endpoint to include the complete user profile are being deprecated. Make sure the `Legacy User Profile` toggle is turned off after completing the migration to the new OIDC-conformant APIs.

When using the legacy authentication flows, the entire user profile is returned in ID Tokens and from `/userinfo`, as demonstrated below.

The new user profile conforms to the OIDC specification, which allows for certain [standard claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) to be available in the response.

The contents will vary depending on which scopes are requested. You will need to adjust the scopes you request when configuring Auth0.js or Lock so all the claims you need are available in your application. Note that you can add custom claims to return whatever data you want (for example, user metadata).

Another approach to get the full user profile is to use the <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip> (instead of getting the profile through the authentication flow) as described in the next section.

## User profile with Management API

In the legacy flows, the Management API supported authentication with an ID Token. This approach has been deprecated, and now you need to call it with an Access Token.

To get an Access Token, you need to ask Auth0 for one using the `https://{yourDomain}/api/v2/` audience. Auth0 does not currently support specifying two audiences when authenticating, so you will need to still use your application's API audience when initializing Lock or auth0.js. Once the user is authenticated, you can use `checkSession` to retrieve a Management API `access_token`, and then call the `getUser()` endpoint.

You can ask for the following scopes:

* `read:current_user`
* `update:current_user_identities`
* `create:current_user_metadata`
* `update:current_user_metadata`
* `delete:current_user_metadata`
* `create:current_user_device_credentials`
* `delete:current_user_device_credentials`

You could get a `consent_required` error when calling `checkSession()`. If you do, make sure you have **Allow Skipping User Consent** enabled for the Management API and that you are not running from localhost.


# Migrate to 1-Hour Login Flows Expiration
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/migrate-to-1-hour-expiration

Describes how to enable 1-hour expiration for interactive login flows.

Starting 21 February 2024, Auth0 will enforce a maximum lifetime of 1 hour for redirection-based login flows. Login flows that take longer than 1 hour to complete will expire in both Universal and Classic Login.

## Affected login flows

Auth0 currently allows the following interactive login flows to last up to 3 days to complete:

* [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow)
* [Authorization Code Flow with PKCE](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce)
* [Cross-Origin Authentication](/docs/authenticate/login/cross-origin-authentication)
* [Device Authorization Flow](/docs/get-started/authentication-and-authorization-flow/device-authorization-flow)
* [Hybrid Flow](/docs/get-started/authentication-and-authorization-flow/hybrid-flow)
* [Implicit Flow with Form Post](/docs/get-started/authentication-and-authorization-flow/implicit-flow-with-form-post)
* [Security Assertion Markup Language (SAML)](/docs/authenticate/protocols/saml)
* [Web Services Federation Protocol (WS-Fed)](/docs/authenticate/protocols/ws-fed-protocol)

Starting 21 February 2024, Auth0 will enforce a maximum lifetime of 1 hour for the listed <Tooltip href="/docs/glossary?term=authorization+flows">authorization flows</Tooltip>. Transactions will expire after 1 hour. After expiration, operations from the end user's browser, such as input email and password or redirect back to [Auth0 Actions](/docs/customize/actions), etc., will:

* Redirect to the associated application’s default login route to reinitiate the flow with a new login transaction
  Or
* Serve an error page if you have not configured the application's default login route or you are using Classic Login. The end user must return to your application to reinitiate the login transaction. You can customize this error page using <Tooltip href="/docs/glossary?term=Universal+Login">Universal Login</Tooltip>.

## Actions

When [redirecting users after logout](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/redirect-with-actions), redirect them to a page of your application that allows users to log in again based on some user action (e.g. click the Login button) instead of directly redirecting them to the Universal Login `/authorize` endpoint. The pattern of starting a new login transaction without an explicit user-initiated action is the main source of transactions taking too long to complete, as the new login attempt is left unattended in a browser window and can be subject to malicious attacks.

If you are using Universal Login:

* We recommend you [configure default login routes](/docs/authenticate/login/auth0-universal-login/configure-default-login-routes) for your applications in the <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or via the Auth0 <Tooltip href="/docs/glossary?term=Management+API">Management API</Tooltip>. This method automatically starts login transactions and results in the best user experience as the login flow seamlessly restarts for active end users when the transaction has expired.
* If your configuration doesn’t allow for default login routes, we recommend you [customize Auth0 error pages](/docs/customize/login-pages/custom-error-pages) to provide a better user experience. You can use the error pages to instruct the user to return to your application to restart the login attempt.
* If you don’t do either of the above, we will display the [default Auth0 error page](/docs/authenticate/login/auth0-universal-login/error-pages):

<Frame>
  <img alt="" />
</Frame>

If you are using Classic Login, the login widget will display an error and the user will need to return to the application and retry to log in for expired transaction in all cases.

## Review tenant logs

If you want further insights on how many transactions and Applications are affected in your tenant, review the logs in your tenant under [Auth0 Dashboard > Monitoring > Logs](https://manage.auth0.com/#/monitoring/logs). Look for `Deprecation Notice` logs with this search: `type:depnote AND description:*Long*state*expirations*`. These results will point to login transactions and the applications (i.e. `client_id`) lasting longer than 1 hour.

Note these logs are rate-limited, and you will see one per hour per `client_id`.

## Verify migration

After configuring default login routes or updating the Auth0 error pages with specific instructions for your end-users, you can (de)activate the 1-hour expiration any time before 21 February 2024 to verify login behavior.

1. Navigate to [Auth0 Dashboard > Tenant Settings > Advanced](https://manage.auth0.com/#/tenant/advanced) and search for the Migrations section.
2. Toggle off **Long state expirations**. Disabling this setting limits transactions to last only 1 hour. Enabling this setting allows transactions to last up to 3 days.


# Migrate to Tenant Log Search v3
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/migrate-to-tenant-log-search-v3

Describes how to migrate from Auth0 Logs Search v2 to v3.

To provide our customers with the most reliable and scalable solution, Auth0 has deprecated Tenant Logs Search Engine v2 in favor of v3.

Auth0 proactively migrates customers unaffected by this change, while those who are potentially affected are being notified to opt-in for v3 during the provided grace period.

## Features affected

You are affected if you meet all of the following criteria:

* Tenants created before or on 21 May 2019
* Tenants hosted in Auth0's public cloud in the AU or EU regions
* Use the GET /api/v2/logs or the GET `/api/v2/users/{user_id}/logs` endpoint with the parameter `include_totals=true` or the `q` parameter.
* Paginate through more than 1000 results.
* Use the Delegated Admin Extension. Older versions of the extension will continue to work after your Tenant is migrated to Logs Search Engine v3, however you might notice pagination totals being incorrect when viewing logs. Updating to v3.7 of the extension addresses this.

The following tenants are not affected:

* Cloud tenants in the US region. The US region has been fully migrated and is already using Search Engine v3.
* Private Cloud tenants (Migration for Private Cloud customers will begin at a later date.)
* Cloud tenants in the EU and AU regions that are:

  * Not using the `GET /api/v2/logs` or `GET /api/v2/users/{user_id}/logs` endpoints of Management API at all.
  * Consuming the logs from the Dashboard Logs section only.
  * Using the `GET /api/v2/logs endpoint` with the by checkpoint method (using `from` parameter).
  * Consuming logs using any of the Auth0 Logs to External Service Dashboard extensions (which use the by checkpoint method).

## Verify query migration

Auth0 generates only one log of the same type and description every 60 minutes. No matter how many calls you make using deprecated features to the impacted endpoints, you will still see a single log for each deprecated feature each hour.

If you implement changes to your queries, you'll need to allow 60 minutes to elapse before you can conclusively determine that the lack of new `depnote` logs means the deprecated behavior has been removed from your code.

You can search your tenant logs with the following to look for queries that would throw errors after you migrate to v3:

`type:depnote AND description:*logs*`

These log entries include a `description` field that specifies the deprecated behavior you're using.

You can also check the `details.request.path` and `client_name` fields to see what application is calling either `GET /api/v2/logs` or `GET /api/v2/users/{user_id}/logs`.

## Changes

The breaking changes are minor, but you should review your queries to make sure the results you are getting are as expected.

Breaking changes are related to:

### Pagination

* When your tenant is migrated to logs v3 the value of the `total` field returned in the summary result when calling `GET /api/v2/logs` or `GET /api/v2/users/{user_id}/logs` is changing. When searching for logs using search engine v2, the totals field in your results tells you the number of logs that match the query you provided. However, in v3, the totals field tells you how many logs are returned in the page (similar to what the length field returns). To avoid any potential disruption, if your application relies on the total field for pagination purposes, you should update your logic to handle this change appropriately.
* There is an existing limit of 100 logs per request. When your tenant is migrated to logs v3 you may only paginate through a maximum of 1,000 search results, resulting in calls for anything over 1,000 results returning an error. To avoid any potential disruption, you should review your queries to avoid this limit or handle errors accordingly.

### q parameter validation

* The query syntax when using the `q` parameter in the `GET /api/v2/logs` has minor changes that need to be taken into account. When your tenant is migrated to logs v3 this validation will be enforced resulting in this query returning an error. To avoid any potential disruption, you should review your queries to make sure they comply with the supported query syntax.
* The `q` parameter includes an invalid field. When your tenant is migrated to logs v3 this validation will be enforced resulting in this call returning an error. To avoid any potential disruption, you should review your queries to make sure that only searchable fields are included.

## Enable Tenant Log Search v3

After reviewing your queries, you can opt-in to Tenant Logs Search Engine v3 via the Dashboard.

1. Go to [Tenant Settings > Advanced](https://manage.auth0.com/#/tenant/advanced).
2. Scroll down to **Migrations**.
3. Toggle the **Legacy Logs Search V2** switch to off. Toggling this switch to off disables the deprecated logs search engine v2 and forces the use of search engine v3. If you do not see the **Legacy Logs Search V2** toggle, you've already been migrated to v3. No further action is required.

If you need help with the migration, contact us using the [Support Center](https://support.auth0.com/).

## Learn more

* [Logs](/docs/deploy-monitor/logs)


# Migrate Your Resource Owner Password Flow
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/migration-oauthro-oauthtoken

Describes how to migrate your password API calls and responses from /oauth/ro to /oauth/token.

Support for <Tooltip href="/docs/glossary?term=resource+owner">resource owner</Tooltip> password was added to `/oauth/token`. Usage of the `/oauth/ro` endpoint was deprecated on 08 July 2017. The `/oauth/ro` endpoint was previously used to exchange a one-time password (OTP) received by the end-user email or SMS for an <Tooltip href="/docs/glossary?term=ID+token">ID token</Tooltip> and an <Tooltip href="/docs/glossary?term=access+token">access token</Tooltip>. Auth0 has implemented a new API that replaces `/oauth/ro` for this use case and we recommend that you migrate to using the new endpoint.

## Features affected

This change affects you if you use the [Resource Owner Password Flow](/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow)(sometimes called Resource Owner Password Grant or ROPG) and call `/oauth/ro` directly without the use of any Auth0 libraries or SDKs. Auth0 libraries such as Lock or Auth0.js have been updated to stop using `/oauth/ro` internally. If you use the lock-<Tooltip href="/docs/glossary?term=passwordless">passwordless</Tooltip> library, you can now use Passwordless Mode in Lock instead.

<Callout icon="file-lines">
  When a user's `/oauth/ro` based access token has expired, Auth0 forces them to reauthenticate (forced logout required) because the `/oauth/ro` refresh token cannot be used to call `/oauth/token` for a new access token. All currently logged in user's must log in again during an `/oauth/ro` to `/oauth/token` migration.
</Callout>

## Actions

### Change requests

Previously, the payload of a request to `/oauth/ro` looked similar to this:

```json lines theme={null}
{
  "grant_type": "password",
  "client_id": "123",
  "username": "alice",
  "password": "A3ddj3w", 
  "connection": "my-database-connection",
  "scope": "openid email favorite_color offline_access",
  "device": "my-device-name"
}
```

The new implementation contains the following changes:

* The endpoint to execute token exchanges is now `/oauth/token`.
* Auth0's own grant type is used to authenticate users from a specific connection (or realm).
* Auth0 supports the standard OIDC scopes, along with the scopes which you have defined in your custom API.
* A scope that doesn't fit in one of these categories, such as the above `favorite_color`, is no longer a valid scope.
* The `device` parameter is removed.
* The `audience` parameter is optional.

Here is an example of the payload of a request to `/oauth/token`:

```json lines theme={null}
{
  "grant_type": "http://auth0.com/oauth/grant-type/password-realm",
  "client_id": "123",
  "username": "alice",
  "password": "A3ddj3w",
  "realm": "my-database-connection",
  "scope": "openid email offline_access",
  "audience": "https://api.example.com"
}
```

* The grant type is specified here as `password-realm`, rather than the standard `password`.
* The parameters `client_id`, `username`, and `password` are unchanged.
* The `realm` is included because we are using Password Realm grant type, and replaces the `connection` parameter from previous calls.
* The `scope` parameter is mostly the same, but does not accept non-OIDC values.
* The `audience` parameter can be added, indicating the API <Tooltip href="/docs/glossary?term=audience">audience</Tooltip> the token will be intended for.

### Response changes

Responses from `/oauth/ro` were similar in format to the following:

```json lines theme={null}
{
  "access_token": "SlAV32hkKG",
  "token_type": "Bearer",
  "refresh_token": "8xLOxBtZp8",
  "expires_in": 3600,
  "id_token": "eyJ..."
}
```

* The returned access token is valid for calling the `/userinfo` endpoint (provided that the API specified by the `audience` param uses RS256 as <Tooltip href="/docs/glossary?term=signing+algorithm">signing algorithm</Tooltip>) and optionally the custom API if one was specified.
* The ID token will be forcibly signed using RS256 if requested by a <Tooltip href="/docs/glossary?term=public+client">public client</Tooltip>.
* A <Tooltip href="/docs/glossary?term=Refresh+Token">Refresh Token</Tooltip> will be returned only if the `offline_access` scope was granted and the API has **Allow offline access** set.

Here is an example of the OIDC conformant response from `/oauth/token`:

```json lines theme={null}
{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "refresh_token": "8xLOxBtZp8",
  "expires_in": 3600,
  "id_token": "eyJ..."
}
```

### Verify migration

1. Once you have migrated your codebase and are sure that your apps are not calling the endpoint, go to the [Dashboard > Tenant Settings > Advanced](https://manage.auth0.com/#/tenant/advanced).
2. Scroll down to **Migrations** and toggle off **Legacy** `/oauth/ro` **Endpoint**. Turning off this switch disables the deprecated endpoint for your tenant, preventing it from being used.

If turning this switch off results in failed logins, this is a sign that you have yet to completely remove all instances of legacy code from your applications.

Once migrations have been successfully performed in production environments, the switch can be toggled off and left off, to ensure that the deprecated features can no longer be used.


# Yahoo API Changes
Source: https://auth0.com/docs/troubleshoot/product-lifecycle/past-migrations/yahoo-api-changes

Describes the Yahoo API changes that affect the structure of the user profile.

Yahoo changed the API that applications need to use to retrieve the User Profile from their [Social Directory API](https://developer.yahoo.com/oauth/social-directory-eol/) to a Yahoo `/userinfo` endpoint. This change implies that the structure of the user profile for Yahoo users in Auth0 will change.

Auth0 previously loaded all the profile data that Yahoo returned, and added these additional fields that were mapped from the Yahoo profile.

Yahoo stopped returning `url`, `profileUrl`, `isConnected`, and a set of other fields listed in [Yahoo’s documentation](https://developer.yahoo.com/oauth/social-directory-eol/) (see "List Of Attributes Deprecated in Social Directory Profile Api"). Those other fields will also not be part of the profile.

The Yahoo `/userinfo` endpoint returns different fields depending on the API permissions that you configure in the [Yahoo Application](https://developer.yahoo.com/apps/) definition. Yahoo lets you grant one of four permissions in the **Profile (Social Directory)** permissions section:

* Read Public Basic
* Read Public Extended
* Read Write Public
* Read Write Public and Private

## Actions

When configuring the Yahoo Connection in your <Tooltip href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip>, select the attribute that corresponds to the permissions you granted in your Yahoo setup. If you choose an attribute that does not match what you specified on Yahoo, the login transaction will fail.

If you do not select any permissions in the Auth0 connection settings, Auth0 will, by default, ask for the `openid` scope which returns the profile fields that correspond to the API permission you specified in the Yahoo Application. For example, if your Yahoo application is configured with the **Read Public Extended** permission, Yahoo returns the following fields:

* `sub, name`
* `given_name`
* `family_name`
* `locale`
* `email`
* `email_verified`
* `birthdate`
* `profile_images`
* `picture`
* `preferred_username`
* `phone_number`
* `nickname`

If you are using the Yahoo connection to authenticate users and get their basic information, your application will continue to work without changes.

If your application is accessing fields in the user profile that are no longer available, then you will need to enable the correct **Connection Attribute** in the Auth0 Dashboard and adjust your application code to use the proper field names.


# Associate Domain with Identity Provider
Source: https://auth0.com/docs/api/myorganization/idp-management/associate-domain-with-identity-provider

myorganization-api-oas post /identity-providers/{idp_id}/domains
Add a domain to the identity provider's list of domains for [Home Realm Discovery (HRD)](https://auth0.com/docs/get-started/architecture-scenarios/business-to-business/authentication#home-realm-discovery). The domain passed must be claimed and verified by this organization.

<ApiReleaseLifecycle />

<Scopes />


# Create Provisioning Configuration
Source: https://auth0.com/docs/api/myorganization/idp-management/create-provisioning-configuration

myorganization-api-oas post /identity-providers/{idp_id}/provisioning
Create the Provisioning configuration for this identity provider.

<ApiReleaseLifecycle />

<Scopes />


# Create Provisioning SCIM Token
Source: https://auth0.com/docs/api/myorganization/idp-management/create-provisioning-scim-token

myorganization-api-oas post /identity-providers/{idp_id}/provisioning/scim-tokens
Create a Provisioning SCIM token for this identity provider.

<ApiReleaseLifecycle />

<Scopes />


# Delete Provisioning Configuration
Source: https://auth0.com/docs/api/myorganization/idp-management/delete-provisioning-configuration

myorganization-api-oas delete /identity-providers/{idp_id}/provisioning
Delete the Provisioning configuration for an identity provider.

<ApiReleaseLifecycle />

<Scopes />


# Get Provisioning Configuration
Source: https://auth0.com/docs/api/myorganization/idp-management/get-provisioning-configuration

myorganization-api-oas get /identity-providers/{idp_id}/provisioning
Retrieve the Provisioning configuration for this identity provider.

<ApiReleaseLifecycle />

<Scopes />


# List Provisioning SCIM Tokens
Source: https://auth0.com/docs/api/myorganization/idp-management/list-provisioning-scim-tokens

myorganization-api-oas get /identity-providers/{idp_id}/provisioning/scim-tokens
List the Provisioning SCIM tokens for this identity provider.

<ApiReleaseLifecycle />

<Scopes />


# Refresh Provisioning Configuration Attributes Mapping
Source: https://auth0.com/docs/api/myorganization/idp-management/refresh-provisioning-configuration-attributes-mapping

myorganization-api-oas put /identity-providers/{idp_id}/provisioning/update-attributes
Triggers a refresh of attribute mappings on the provisioning configuration by overriding it with the admin defined defaults. The endpoint doesn't accept any body parameters.

<ApiReleaseLifecycle />

<Scopes />


# Remove Domain from Identity Provider
Source: https://auth0.com/docs/api/myorganization/idp-management/remove-domain-from-identity-provider

myorganization-api-oas delete /identity-providers/{idp_id}/domains/{domain}
Remove a domain from an identity provider.

<ApiReleaseLifecycle />

<Scopes />


# Revoke Provisioning SCIM Token
Source: https://auth0.com/docs/api/myorganization/idp-management/revoke-provisioning-scim-token

myorganization-api-oas delete /identity-providers/{idp_id}/provisioning/scim-tokens/{idp_scim_token_id}
Delete a Provisioning SCIM configuration for an identity provider.

<ApiReleaseLifecycle />

<Scopes />


# SDK Libraries
Source: https://auth0.com/docs/libraries

Auth0 Libraries and SDKs overview

Auth0 SDK libraries make it easy for developers to integrate and interact with Auth0. Explore any library on GitHub, download a sample application, or use a quickstart for customized help.

## Single-Page Application (SPA) SDK Libraries

Need to protect a JavaScript application that runs entirely in a browser? Choose your technology below.

<Columns>
  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />
</Columns>

## Regular Web Application SDK Libraries

Have a traditional web application that runs on a server? Auth0 maintains these SDK libraries for the most popular languages and environments.

<Columns>
  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />
</Columns>

## Backend Service and API SDK Libraries

Does your API or service need authentication? Auth0 has SDKs for common API and service development tools.

<Columns>
  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />
</Columns>

## Native/Mobile App

Mobile or Desktop app that runs natively on a device

<Columns>
  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />
</Columns>

## Advanced Customization for Universal Login (ACUL)

Extend the capabilities of <a href="auth0.com/docs/authenticate/login/auth0-universal-login/universal-login-vs-classic-login/universal-experience#universal-login-experience">Universal Login</a> to support multi-branding, complex security configurations, and integration of numerous analytic platforms.

<Columns>
  <SectionCard />

  <SectionCard />
</Columns>

## Management API SDK Libraries

Need to programmatically perform Auth0 administrative tasks? Choose from one of these management libraries.

<Columns>
  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />

  <SectionCard />
</Columns>

## Lock SDK Libraries

Do you use Lock, Auth0's legacy self-hosted login experience? You can still rely on these libraries for self-hosted login.

<Columns>
  <SectionCard />

  <SectionCard />

  <SectionCard />
</Columns>


# ACUL JS SDK
Source: https://auth0.com/docs/libraries/acul/js-sdk

ACUL JS SDK.

The Auth0 ACUL JS SDK lets you build custom Universal Login experiences with mininal effort. Whether you are working with login, signup, passwordless, or passkey enrollment, this SDK is built to handle modern authentication flows with ease.

### Why Choose the Auth0 ACUL JS SDK?

* **Fast Integration:** Drop in pre-built screens like `login-id` or `signup-password`.
* **Modern Features:** Support passwordless, passkeys, and social logins.
* **Flexible Modules:** Import only what you need.
* **Unified State Management:** Use a single transaction object to handle all authentication flows.

### Architecture

#### How it works?

The SDK is built with modularity and scability in mind. Here is how it fits together:

* **Screens:** Each authentication flow, such as `login-id` and `signup-password`, is a standalone module.
* **Submit Handlers:** Manage form submissions and transitions.
* **Dynamic Forms:** Adapt fields and validations based on screen configurations.
* **Helper Properties:** Access common data, such as branding or transcation, in consistent way.

### Resources

| Read...                                                                                 | To learn...                               |
| --------------------------------------------------------------------------------------- | ----------------------------------------- |
| [ACUL Quickstart Guide](/docs/customize/login-pages/advanced-customizations/quickstart) | Start buliding with the SDK.              |
| [API Reference](/docs/libraries/acul/js-sdk/Screens/classes/Login)                      | Explore screens, methods, and properties. |


# AcceptInvitation
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/AcceptInvitation



<Frame>
  <img alt="" />
</Frame>

Class implementing the accept-invitation screen functionality.
This screen is displayed when a user needs to accept an invitation to an organization.

```ts Example theme={null}
import AcceptInvitation from '@auth0/auth0-acul-js/accept-invitation';

const acceptInvitation = new AcceptInvitation();
await acceptInvitation.acceptInvitation();
```

## Constructors

<ParamField type="Constructor">
  Creates an instance of AcceptInvitation screen manager.
</ParamField>

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnAcceptInvitation">ScreenMembersOnAcceptInvitation</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string" />

## Methods

<ParamField type="Promise<void>">
  Accepts the invitation to the organization.

  ```typescript Example theme={null}
  import AcceptInvitation from '@auth0/auth0-acul-js/accept-invitation';

  const acceptInvitation = new AcceptInvitation();
  await acceptInvitation.acceptInvitation();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>}>
      Optional custom options to include with the request.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>


# Auth0ServerError
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/Auth0ServerError



Auth0ServerError

## Constructors

<ParamField type="Constructor">
  <Expandable title="Parameters">
    <ParamField type="string">
      The error message.
    </ParamField>

    <ParamField type="string">
      The optional field associated with the error.
    </ParamField>
  </Expandable>
</ParamField>

## Properties

<ParamField type="&#x22;AUTH0_SERVER_ERROR&#x22;" />

<ParamField type="string" />


# Consent
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/Consent



<Frame>
  <img alt="" />
</Frame>

ConsentMembers

```ts Example theme={null}
import Consent from '@auth0/auth0-acul-js/consent';
const consentManager = new Consent();
const handleAccept = async () => {
 try {
   await consentManager.accept();
   console.log('Consent accepted successfully.');
 } catch (err) {
   console.error('Error accepting consent:', err);
 }
};
```

## Constructors

<ParamField type="Constructor">
  Creates an instance of the `Consent` screen manager.
  The constructor initializes the `BaseContext` and sets up the `screen` property
  with an instance of `ScreenOverride` tailored for the consent screen.

  #### Throws

  If the Universal Login Context is not available or if the
  current screen name in the context does not match `Consent.screenIdentifier`.
</ParamField>

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnConsent">ScreenMembersOnConsent</a></span>}>
  Holds the specific screen data and properties for the Consent screen,
  processed by `ScreenOverride`. This includes the list of `scopes` being requested
  and the `hideScopes` flag.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string" />

## Methods

<ParamField type="Promise<void>">
  Submits the user's decision to accept (grant) the requested permissions.
  This method prepares and posts form data to the `/u/consent?state=<transaction_state>` endpoint
  with `action: "accept"`. The transaction state is automatically included in both the
  URL query parameter and the form body.

  A promise that resolves once the form submission is initiated.
  Typically, a successful submission leads to a server-side redirect.

  #### Throws

  Throws an error if `FormHandler` encounters an unrecoverable issue
  during submission (e.g., network error). Server-side validation errors
  from Auth0 (like "invalid\_request") are not thrown as JavaScript errors
  but are made available in `this.transaction.errors` after the operation.

  ```typescript Example theme={null}
  import Consent from '@auth0/auth0-acul-js/consent';
  const consentManager = new Consent();
  const handleAccept = async () => {
   try {
     await consentManager.accept();
     console.log('Consent accepted successfully.');
   } catch (err) {
     console.error('Error accepting consent:', err);
   }
  };
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>}>
      Optional. An object for any custom key-value pairs
      to be sent with the request. These parameters will be
      included in the form data submitted to the server.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Promise<void>">
  Submits the user's decision to deny (reject) the requested permissions.
  This method prepares and posts form data to the `/u/consent?state=<transaction_state>` endpoint
  with `action: "deny"`. The transaction state is automatically included in both the
  URL query parameter and the form body.

  A promise that resolves once the form submission is initiated.
  A successful submission usually results in a server-side redirect.

  #### Throws

  Throws an error if `FormHandler` encounters an issue (e.g., network error).
  Server-side validation errors are reflected in `this.transaction.errors`.

  ```typescript Example theme={null}
  import Consent from '@auth0/auth0-acul-js/consent';
  const consentManager = new Consent();
  const handleDeny = async () => {
   try {
     await consentManager.deny();
     console.log('Form denied successfully.');
   } catch (err) {
     console.error('Failed to deny form:', error);
   }
  };

  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>}>
      Optional. An object for any custom key-value pairs
      to be sent with the request. These parameters will be
      included in the form data submitted to the server.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>


# CustomizedConsent
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/CustomizedConsent



<Frame>
  <img alt="" />
</Frame>

CustomizedConsent

```typescript Example theme={null}
// How to use the CustomizedConsent screen SDK:
import CustomizedConsent from '@auth0/auth0-acul-js/customized-consent';

// Instantiate the manager for the customized consent screen
const consentManager = new CustomizedConsent();

// Accessing screen data
const clientName = consentManager.client.name;
const userEmail = consentManager.user.email;
const requestedScopes = consentManager.screen.scopes;
const authorizationDetails = consentManager.screen.authorizationDetails;

console.log(`${clientName} is requesting consent from ${userEmail}.`);
console.log("Requested Scopes:", requestedScopes);
console.log("Authorization Details:", authorizationDetails);

// Accessing transaction errors from a previous attempt
const transactionErrors = consentManager.transaction.errors;
if (transactionErrors && transactionErrors.length > 0) {
  transactionErrors.forEach(error => {
    console.error(`Error: ${error.message}`);
    // Display these errors to the user.
  });
}

// Example of handling consent acceptance
async function onAcceptConsent() {
  try {
    await consentManager.accept();
    // On success, Auth0 will typically redirect.
  } catch (e) {
    console.error('Failed to accept consent:', e);
  }
}

// Example of handling consent denial
async function onDenyConsent() {
  try {
    await consentManager.deny({ denial_reason: "user_declined" });
    // On success, Auth0 will typically redirect.
  } catch (e) {
    console.error('Failed to deny consent:', e);
  }
}
```

## Constructors

<ParamField type="Constructor">
  Creates an instance of the `CustomizedConsent` screen manager.
  The constructor initializes the `BaseContext` and sets up the `screen` property
  with an instance of `ScreenOverride` tailored for the customized consent screen.

  #### Throws

  If the Universal Login Context is not available or if the
  current screen name in the context does not match `CustomizedConsent.screenIdentifier`.
</ParamField>

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnCustomizedConsent">ScreenMembersOnCustomizedConsent</a></span>}>
  Holds the specific screen data and properties for the Customized Consent screen,
  processed by `ScreenOverride`. This includes `scopes` and `authorizationDetails`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string">
  The unique identifier for the Customized Consent screen.
  This static property is used by the SDK's `BaseContext` to ensure that the
  class is instantiated in the correct screen context.
</ParamField>

## Methods

<ParamField type="Promise<void>">
  Submits the user's decision to accept (grant) the requested permissions and authorization details.
  This method prepares and posts form data to the `/u/customized-consent?state=<transaction_state>` endpoint
  with `action: "accept"`. The transaction state is automatically included in both the
  URL query parameter and the form body.

  A promise that resolves once the form submission is initiated.
  Typically, a successful submission leads to a server-side redirect.

  #### Throws

  Throws an error if `FormHandler` encounters an unrecoverable issue
  during submission (e.g., network error). Server-side validation errors
  from Auth0 (like "invalid\_request") are not thrown as JavaScript errors
  but are made available in `this.transaction.errors` after the operation.

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>}>
      Optional. An object for any custom key-value pairs
      to be sent with the request. These parameters will be
      included in the form data submitted to the server.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Promise<void>">
  Submits the user's decision to deny (reject) the requested permissions and authorization details.
  This method prepares and posts form data to the `/u/customized-consent?state=<transaction_state>` endpoint
  with `action: "deny"`. The transaction state is automatically included in both the
  URL query parameter and the form body.

  A promise that resolves once the form submission is initiated.
  A successful submission usually results in a server-side redirect.

  #### Throws

  Throws an error if `FormHandler` encounters an issue (e.g., network error).
  Server-side validation errors are reflected in `this.transaction.errors`.

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>}>
      Optional. An object for any custom key-value pairs
      to be sent with the request. These parameters will be
      included in the form data submitted to the server.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>


# DeviceCodeActivation
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/DeviceCodeActivation



<Frame>
  <img alt="" />
</Frame>

Class implementing the Device Code Activation screen functionality.
This screen is displayed when the user needs to enter the code on their device to activate it.

```ts Example theme={null}
import DeviceCodeActivation from '@auth0/auth0-acul-js/device-code-activation';
const deviceCodeActivationManager = new DeviceCodeActivation();
async function activateDeviceCode(code) {
  try {
   await deviceCodeActivationManager.continue({ code });
   console.log('Device code activation successful.');
  } catch (error) {
   console.error('Error during device code activation:', error);
  }
}
```

## Constructors

<ParamField type="Constructor">
  Creates an instance of the DeviceCodeActivation screen.
</ParamField>

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembers">ScreenMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string" />

## Methods

<ParamField type="Promise<void>">
  Submits the device code entered by the user.
  This action is triggered when the user enters the code displayed on their device and submits the form.

  A promise that resolves when the code is successfully submitted.

  ```typescript Example theme={null}
  import DeviceCodeActivation from '@auth0/auth0-acul-js/device-code-activation';
  const deviceCodeActivationManager = new DeviceCodeActivation();
  async function activateDeviceCode(code) {
    try {
     await deviceCodeActivationManager.continue({ code });
     console.log('Device code activation successful.');
    } catch (error) {
     console.error('Error during device code activation:', error);
    }
  }
  ```

  Rejects with an error if the submission fails.

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/DeviceCodeActivationContinueOptions">DeviceCodeActivationContinueOptions</a></span>}>
      An object containing the code entered by the user and any custom payload.

      **Properties**

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>


# DeviceCodeActivationAllowed
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/DeviceCodeActivationAllowed



<Frame>
  <img alt="" />
</Frame>

Class implementing the Device Code Activation Allowed screen functionality.
This screen is displayed when the device code activation is allowed.

```ts Example theme={null}
import DeviceCodeActivationAllowed from "@auth0/auth0-acul-js/device-code-activation-allowed";
const deviceCodeActivationAllowedManager = new DeviceCodeActivationAllowed();
```

## Constructors

<ParamField type="Constructor">
  Creates an instance of DeviceCodeActivationAllowed screen manager.
</ParamField>

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembers">ScreenMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string" />

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>


# DeviceCodeActivationDenied
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/DeviceCodeActivationDenied



<Frame>
  <img alt="" />
</Frame>

Class implementing the Device Code Activation Denied screen functionality.
This screen is displayed when the device code activation is denied.

```ts Example theme={null}
import DeviceCodeActivationDenied from "@auth0/auth0-acul-js/device-code-activation-denied";
const deviceCodeActivationDeniedManager = new DeviceCodeActivationDenied();
```

## Constructors

<ParamField type="Constructor">
  Creates an instance of DeviceCodeActivationDenied screen manager.
</ParamField>

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembers">ScreenMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string" />

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>


# DeviceCodeConfirmation
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/DeviceCodeConfirmation



<Frame>
  <img alt="" />
</Frame>

Class implementing the Device Code Confirmation screen functionality.
This screen is displayed when the user needs to confirm the device code.

```ts Example theme={null}
import DeviceCodeConfirmation from '@auth0/auth0-acul-js/device-code-confirmation';
const deviceCodeConfirmation = new DeviceCodeConfirmation();
```

## Constructors

<ParamField type="Constructor">
  Creates an instance of the DeviceCodeConfirmation screen.
</ParamField>

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnDeviceCodeConfirmation">ScreenMembersOnDeviceCodeConfirmation</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string" />

## Methods

<ParamField type="Promise<void>">
  Cancels the device code flow.

  ```typescript Example theme={null}
  import DeviceCodeConfirmation from '@auth0/auth0-acul-js/device-code-confirmation';

  const deviceCodeConfirmation = new DeviceCodeConfirmation();
  await deviceCodeConfirmation.cancel();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>}>
      Optional custom options to include with the request.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Promise<void>">
  Confirms the device code.

  ```typescript Example theme={null}
  import DeviceCodeConfirmation from '@auth0/auth0-acul-js/device-code-confirmation';

  const deviceCodeConfirmation = new DeviceCodeConfirmation();
  await deviceCodeConfirmation.confirm();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>}>
      Optional custom options to include with the request.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>


# EmailIdentifierChallenge
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/EmailIdentifierChallenge



```ts Example theme={null}
import EmailIdentifierChallenge from '@auth0/auth0-acul-js/email-identifier-challenge';
const emailIdentifierChallenge = new EmailIdentifierChallenge();
emailIdentifierChallenge.submitEmailChallenge({
    code: "<string>"
});
```

## Constructors

<ParamField type="Constructor" />

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnEmailIdentifierChallenge">ScreenMembersOnEmailIdentifierChallenge</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string" />

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>

<ParamField type="Promise<void>">
  ```ts Example theme={null}
  import EmailIdentifierChallenge from '@auth0/auth0-acul-js/email-identifier-challenge';

  const emailIdentifierChallenge = new EmailIdentifierChallenge();
  emailIdentifierChallenge.resendCode();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ResendControl">ResendControl</a></span>}>
  **`Utility Feature`**

  Gets resend functionality with timeout management for this screen

  ResendControl object with startResend method

  ```ts Example theme={null}
  import EmailIdentifierChallenge from '@auth0/auth0-acul-js/email-identifier-challenge';
    const handleStatusChange = (remainingSeconds, isDisabled) => {
      setDisabled(isDisabled);
      setRemaining(remainingSeconds);
    };

    const handleTimeout = () => {
      console.log('Timeout completed, resend is now available');
    };

    const { startResend } = emailChallenge.resendManager({
      timeoutSeconds: 15,
      onStatusChange: handleStatusChange,
      onTimeout: handleTimeout
    });
    
    // Call startResend when user clicks resend button
    await startResend();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/StartResendOptions">StartResendOptions</a></span>}>
      Configuration options for resend functionality

      **Properties**

      <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/type-aliases/OnStatusChangeCallback">OnStatusChangeCallback</a></span>} />

      <ParamField type="void" />

      <ParamField type="number" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Promise<void>">
  ```ts Example theme={null}
  import EmailIdentifierChallenge from '@auth0/auth0-acul-js/email-identifier-challenge';

  const emailIdentifierChallenge = new EmailIdentifierChallenge();
  emailIdentifierChallenge.returnToPrevious();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type="Promise<void>">
  ```ts Example theme={null}
  import EmailIdentifierChallenge from '@auth0/auth0-acul-js/email-identifier-challenge';

  const emailIdentifierChallenge = new EmailIdentifierChallenge();
  emailIdentifierChallenge.submitEmailChallenge({
      code: "<string>"
  });
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/EmailChallengeOptions">EmailChallengeOptions</a></span>}>
      **Properties**

      <ParamField type="string" />

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>


# EmailOTPChallenge
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/EmailOTPChallenge



<Frame>
  <img alt="" />
</Frame>

Represents the Email OTP Challenge screen.

```ts Example theme={null}
import EmailOTPChallenge from '@auth0/auth0-acul-js/email-otp-challenge';

const emailOTPChallenge = new EmailOTPChallenge();
emailOTPChallenge.submitCode({
  code: '123456',
});
```

## Constructors

<ParamField type="Constructor" />

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembers">ScreenMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string" />

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>

<ParamField type="Promise<void>">
  Requests a new OTP code to be sent to the user's email.

  ```typescript Example theme={null}
  import EmailOTPChallenge from '@auth0/auth0-acul-js/email-otp-challenge';

  const emailOTPChallenge = new EmailOTPChallenge();
  emailOTPChallenge.resendCode();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>}>
      Optional parameters to include in the resend request.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ResendControl">ResendControl</a></span>}>
  **`Utility Feature`**

  Gets resend functionality with timeout management for this screen

  ResendControl object with startResend method

  ```typescript Example theme={null}
  import EmailOTPChallenge from '@auth0/auth0-acul-js/email-otp-challenge';

  const emailOTPChallenge = new EmailOTPChallenge();
  const { startResend } = emailOTPChallenge.resendManager({
    timeoutSeconds: 15,
    onStatusChange: (remainingSeconds, isDisabled) => {
      console.log(`Resend available in ${remainingSeconds}s, disabled: ${isDisabled}`);
    },
    onTimeout: () => {
      console.log('Resend is now available');
    }
  });

  // Call startResend when user clicks resend button
  startResend();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/StartResendOptions">StartResendOptions</a></span>}>
      Configuration options for resend functionality

      **Properties**

      <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/type-aliases/OnStatusChangeCallback">OnStatusChangeCallback</a></span>} />

      <ParamField type="void" />

      <ParamField type="number" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Promise<void>">
  Submits the OTP code entered by the user.

  ```typescript Example theme={null}
  import EmailOTPChallenge from '@auth0/auth0-acul-js/email-otp-challenge';

  const emailOTPChallenge = new EmailOTPChallenge();
  emailOTPChallenge.submitCode({
    code: '123456',
  });
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OtpCodeOptions">OtpCodeOptions</a></span>}>
      Optional parameters to include in the submission.

      **Properties**

      <ParamField type="string">
        The OTP code that the user enters to submit.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>


# EmailVerificationResult
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/EmailVerificationResult



<Frame>
  <img alt="" />
</Frame>

EmailVerificationResult

```typescript Example theme={null}
import EmailVerificationResult from '@auth0/auth0-acul-js/email-verification-result';

const emailVerificationResultScreen = new EmailVerificationResult();

// Access screen data
const status = emailVerificationResultScreen.screen.data?.status;
const loginLink = emailVerificationResultScreen.screen.loginLink;

console.log(`Verification Status: ${status}`);
if (loginLink) {
  console.log(`Proceed to login: ${loginLink}`);
  // In a UI, you would use this link for a button or anchor tag
  // e.g., <a href={loginLink}>Go to Login</a>
}
```

## Constructors

<ParamField type="Constructor">
  Initializes a new instance of the `EmailVerificationResult` class.
  It retrieves the screen-specific context and sets up the `screen` property

  #### Throws

  If the Universal Login Context is not available or if the
  current screen name in the context does not match `EmailVerificationResult.screenIdentifier`.
</ParamField>

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnEmailVerificationResult">ScreenMembersOnEmailVerificationResult</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string">
  static
</ParamField>

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>


# InterstitialCaptcha
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/InterstitialCaptcha



<Frame>
  <img alt="" />
</Frame>

```ts Example theme={null}
import InterstitialCaptcha from "@auth0/auth0-acul-js/interstitial-captcha";
const interstitialCaptcha = new InterstitialCaptcha();
interstitialCaptcha.submitCaptcha({
 captcha: "captchaValue",
});
```

## Constructors

<ParamField type="Constructor" />

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembers">ScreenMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string" />

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>

<ParamField type="Promise<void>">
  #### Remarks

  This methods handles InterstitialCaptcha related configuration.

  ```ts Example theme={null}
  import InterstitialCaptcha from "@auth0/auth0-acul-js/interstitial-captcha";

  const interstitialCaptcha = new InterstitialCaptcha();
  interstitialCaptcha.submitCaptcha({
   captcha: "captchaValue",
  });
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/SubmitCaptchaOptions">SubmitCaptchaOptions</a></span>}>
      **Properties**

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>


# Login
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/Login



The Login class implements the `login` screen functionality. This screen collects the user's identifier and password. Depending on your tenant, this identifer can be an email, phone number, or username.

<Frame>
  <img alt="ACUL Login" />
</Frame>

## Constructors

Create an instance of Login screen manager

```ts Example theme={null}
import Login from "@auth0/auth0-acul-js/login";
const loginManager = new Login();
loginManager.login({
  username: "testUser",
  password: "testPassword"
});
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`, for the `login` screen.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnLogin">ScreenMembersOnLogin</a></span>}>
  Contains details specific to the `login` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembersOnLogin">TransactionMembersOnLogin</a></span>}>
  Provides transaction-specific data for the `login` screen, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)" />

This method redirects the user to the social or enterprise identity provider (Idp) for authentiction.

```typescript Example theme={null}
import Login from "@auth0/auth0-acul-js/login";
const loginManager = new Login();
loginManager.federatedLogin({
  connection: "google-oauth2"
});
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="string">
    The social connection name to use.
  </ParamField>

  <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
    Additional data collected from the user.
  </ParamField>
</Expandable>

***

<ParamField type="(options ?)" />

This method authenticates the user based on the identifier and provided password.

```typescript Example theme={null}
import Login from "@auth0/auth0-acul-js/login";
const loginManager = new Login();
loginManager.login({
  username: "testUser",
  password: "testPassword"
});
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="string">
    The user's identifier.
  </ParamField>

  <ParamField type="string">
    The user's password.
  </ParamField>

  <ParamField type="string">
    The captcha code or response from the captcha provider. This property is required if your Auth0 tenant has Bot Detection enabled.
  </ParamField>

  <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
    Additional data collected from the user.
  </ParamField>
</Expandable>

***

<ParamField type="(options ?)" />

This method redirects the user to the country code selection list, where they can update the country code prefix for their phone numnber.

```typescript Example theme={null}
import Login from "@auth0/auth0-acul-js/login";
const loginManager = new Login();
loginManager.pickCountryCode();
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
    Additional data collected from the user.
  </ParamField>
</Expandable>

***

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist. An array of error objects from the transaction context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/type-aliases/ScreenIdentifierType">ScreenIdentifierType</a>[]</span>}>
  This method lets the active identifier types for the login screen. An array of active identifier types or `null` if none are active

  ```typescript Example theme={null}
  import Login from "@auth0/auth0-acul-js/login";
  const loginManager = new Login();
  loginManager.getLoginIdentifiers();
  ```
</ParamField>


# LoginEmailVerification
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/LoginEmailVerification



The LoginEmailVerification manages interactions for the `login-email-verification` screen.
This screen prompts the user to enter a one-time code sent to their email address
to verify their identity during the login process.

<Frame>
  <img alt="" />
</Frame>

## Constructors

Create an instance of LoginEmailVerification screen manager

```typescript Example theme={null}
// How to use the LoginEmailVerification screen SDK:
import LoginEmailVerification from '@auth0/auth0-acul-js/login-email-verification';

// Instantiate the manager for the login email verification screen
const loginEmailVerificationManager = new LoginEmailVerification();

```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Contains details specific to the `login-email-verification` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data for the `login-email-verification` screen, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)" />

This method submits the email verification code entered by the user to Auth0.
This method prepares and posts the form data, including the verification code and the required `action: "default"`, to the `/u/login-email-verification` endpoint.

```typescript Example theme={null}
const manager = new LoginEmailVerification();
// Assuming 'userInputCode' is a string obtained from a form input
manager.continueWithCode({ code: userInputCode })
  .catch(err => {
    // Handle unexpected submission errors
    displayGlobalError("Could not submit your code. Please try again.");
  });
// After the operation, check manager.transaction.errors for validation messages.
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="string">
    The verification code sent to the user's email. This is typically a short numeric
    or alphanumeric string that the user must enter into the form.
  </ParamField>

  <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
    Additional data collected from the user.
  </ParamField>
</Expandable>

***

<ParamField type="(options ?)" />

This method requests Auth0 to send a new verification code to the user's email address.
This is typically used when the user didn't receive the original code, or it has expired.

```typescript Example theme={null}
const manager = new LoginEmailVerification();
manager.resendCode()
  .then(() => {
    // Inform the user that a new code has been sent.
    showNotification("A new verification code is on its way!");
  })
  .catch(err => {
    // Handle unexpected submission errors
    displayGlobalError("Could not request a new code. Please try again later.");
  });
// After the operation, check manager.transaction.errors for specific issues.
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
    Additional data collected from the user.
  </ParamField>
</Expandable>

***

<ParamField type="(options ?)" />

This method gets resend functionality with timeout management for this screen.

```typescript Example theme={null}
import LoginEmailVerification from '@auth0/auth0-acul-js/login-email-verification';

const loginEmailVerification = new LoginEmailVerification();
const { startResend } = loginEmailVerification.resendManager({
  timeoutSeconds: 15,
  onStatusChange: (remainingSeconds, isDisabled) => {
    console.log(`Resend available in ${remainingSeconds}s, disabled: ${isDisabled}`);
  },
  onTimeout: () => {
    console.log('Resend is now available');
  }
});

// Call startResend when user clicks resend button
startResend();
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/type-aliases/OnStatusChangeCallback">OnStatusChangeCallback</a></span>}>
    Callback function for status changes during resend countdown.
  </ParamField>

  <ParamField type="void" />

  <ParamField type="number" />
</Expandable>

***

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist. An array of error objects from the transaction context.
</ParamField>


# LoginId
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/LoginId



The LoginId class implements the `login-id` screen functionality. This screen collects the user's identifier and password. Depending on your tenant, this identifer can be an email, phone number, or username.

<Frame>
  <img alt="" />
</Frame>

## Constructors

Create an instance of LoginId screen manager

```ts Example theme={null}
import LoginId from "@auth0/auth0-acul-js/login-id";
const loginIdManager = new LoginId();
loginIdManager.getLoginIdentifiers();
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`, for the `login-id` screen.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnLoginId">ScreenMembersOnLoginId</a></span>}>
  Contains details specific to the `login-id` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembersOnLoginId">TransactionMembersOnLoginId</a></span>}>
  Provides transaction-specific data for the `login-id` screen, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)" />

This method redirects the user to the social or enterprise identity provider (Idp) for authentiction.

```ts Example theme={null}
import LoginId from "@auth0/auth0-acul-js/login-id";
const loginIdManager = new LoginId();

// Check if alternateConnections is available and has at least one item
if (!loginIdManager.transaction.alternateConnections) {
  console.error('No alternate connections available.');
}

// Select the first available connection (users can select any available connection)
const selectedConnection = alternateConnections[0];

// Log the chosen connection for debugging or informational purposes
console.log(`Selected connection: ${selectedConnection.name}`);

// Proceed with federated login using the selected connection
loginIdManager.federatedLogin({
  connection: selectedConnection.name,
});
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="string">
    The social connection name to use
  </ParamField>

  <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
    Additional data collected from the user.
  </ParamField>
</Expandable>

***

<ParamField type="(options ?)" />

This method prompts the user to provide their username.

```ts Example theme={null}
import LoginId from "@auth0/auth0-acul-js/login-id";

const loginIdManager = new LoginId();

loginIdManager.login({
  username: <usernameFieldValue>
});
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="string">
    The user's identifier.
  </ParamField>

  <ParamField type="string">
    The captcha code or response from the captcha provider. This property is required if your Auth0 tenant has Bot Detection enabled.
  </ParamField>

  <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
    Additional data collected from the user.
  </ParamField>
</Expandable>

***

<ParamField type="(options ?)" />

This method authenticates the user using the provided passkey and, if succesful, redirects them to the `redirect_url`.

```ts Example theme={null}
import LoginId from "@auth0/auth0-acul-js/login-id";
const loginIdManager = new LoginId();

// It internally maps users available passkey config provided from auth0 server
loginIdManager.passkeyLogin();
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
    Additional data collected from the user.
  </ParamField>
</Expandable>

***

<ParamField type="(options ?)" />

This method redirects the user to the country code selection list, where they can update the country code prefix for their phone numnber.

```ts Example theme={null}
import LoginId from "@auth0/auth0-acul-js/login-id";
const loginIdManager = new LoginId();

loginIdManager.pickCountryCode();
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
    Additional data collected from the user.
  </ParamField>
</Expandable>

***

<ParamField type="(inputId?: string)" />

This method registers the browser's Conditional UI for passkeys (autocomplete experience).

This method initializes a passive WebAuthn credential request using
`navigator.credentials.get()` with `mediation: "conditional"`. When supported,
this allows the browser to display stored passkeys directly within the username
field’s autocomplete dropdown.

Call this **once** when the login screen is initialized (for example, on page load).
After registration, focusing the username input will automatically display
matching passkeys as suggestions. Selecting a passkey completes authentication
without requiring additional user interaction.

```ts Example theme={null}
import LoginId from '@auth0/auth0-acul-js/login-id';

// Example: initializing passkey autocomplete inside an async setup block.
async function initializeLogin() {
  const loginId = new LoginId();
  // Make sure associated HTML input exists:
  // <input id="username" autocomplete="webauthn username" />
  // Conditional UI registration.
  await loginId.registerPasskeyAutofill('username');
}

initializeLogin().catch(console.error);
```

**Input configuration**
If an `inputId` is provided, the SDK will:

* Validate that the element exists and is an `<input>`.
* Overwrite its `autocomplete` attribute with `"webauthn username"`.

This ensures full compatibility with the Conditional Mediation API.

If you do **not** provide an `inputId`, you are responsible for configuring
the input element manually with the correct attributes:

```html theme={null}
<input id="username" autocomplete="webauthn username" />
```

**Gotchas**

* The `autocomplete` attribute **must exactly** contain `"webauthn username"`.
  Including unrelated tokens such as `"email"` or `"text"` will prevent browsers
  from showing the passkey dropdown.
* Overwriting the attribute is intentional and required for consistent behavior
  across browsers. Do not rely on merging or extending existing autocomplete values.
* If Conditional Mediation is not supported by the browser, the SDK will safely no-op.

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="string">
    Optional ID of the username `<input>` element (without `#`). Example: `"username"`.
    If omitted, the developer must manually ensure the correct `autocomplete` attributes.
  </ParamField>
</Expandable>

**Remarks**

This method delegates to the internal `registerPasskeyAutofill()` utility,
returning a background `AbortController` to manage request lifetime. It should
only be invoked once per page lifecycle.

***

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/type-aliases/ScreenIdentifierType">ScreenIdentifierType</a>[]</span>}>
  This method gets the active identifier types for the login screen.

  ```typescript Example theme={null}
  import LoginId from "@auth0/auth0-acul-js/login";
  const loginIdManager = new LoginId();
  loginIdManager.getLoginIdentifiers();
  ```
</ParamField>


# LoginPassword
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/LoginPassword



The LoginPassword class implements the `login-password` screen functionality. This screen collects the user's identifier and password.

<Frame>
  <img alt="" />
</Frame>

## Constructors

Create an instance of LoginPassword screen manager

```ts Example theme={null}
import LoginPassword from "@auth0/auth0-acul-js/login-password";
const loginPasswordManager = new LoginPassword();
loginPasswordManager.login({
 username: "testUser",
 password: "******"
});
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnLoginPassword">ScreenMembersOnLoginPassword</a></span>}>
  Contains details specific to the `login-password` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembersOnLoginPassword">TransactionMembersOnLoginPassword</a></span>}>
  Provides transaction-specific data for the `login-password` screen, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)" />

This method redirects the user to the social or enterprise identity provider (Idp) for authentiction.

```ts Example theme={null}
import LoginPassword from "@auth0/auth0-acul-js/login-id";
const loginIdManager = new LoginPassword();

// Check if alternateConnections is available and has at least one item
if (!loginIdManager.transaction.alternateConnections) {
  console.error('No alternate connections available.');
}

// Select the first available connection (users can select any available connection)
const selectedConnection = alternateConnections[0];

// Log the chosen connection for debugging or informational purposes
console.log(`Selected connection: ${selectedConnection.name}`);

// Proceed with federated login using the selected connection
loginIdManager.federatedLogin({
  connection: selectedConnection.name,
});
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="string">
    The social connection name to use.
  </ParamField>

  <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
    Additional data collected from the user.
  </ParamField>
</Expandable>

***

<ParamField type="(options ?)" />

This method authenticates the user based on the identifier and provided password.

```typescript Example theme={null}
import Login from "@auth0/auth0-acul-js/login";
const loginManager = new Login();
loginManager.login({
  username: "testUser",
  password: "testPassword"
});
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="string">
    The user's identifier.
  </ParamField>

  <ParamField type="string">
    The user's password.
  </ParamField>

  <ParamField type="string">
    The captcha code or response from the captcha provider. This property is required if your Auth0 tenant has Bot Detection enabled.
  </ParamField>

  <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
    Additional data collected from the user.
  </ParamField>
</Expandable>

***

<ParamField type="(options ?)" />

This method handles switching between DB connection (password) and Passwordless connection (Email/SMS OTP). The connection parameter should be one of: 'email', 'sms', or a DB connection name.

```typescript Example theme={null}
import LoginPassword from "@auth0/auth0-acul-js/login-password";

const loginPasswordManager = new LoginPassword();

// Function to handle connection switching
const handleSwitchConnection = (connectionName: string) => {
  loginPasswordManager.switchConnection({ connection: connectionName });
};

// Switch to different connection strategies
handleSwitchConnection('email'); // Switch to email-based authentication
handleSwitchConnection('sms');   // Switch to SMS-based authentication
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="string">
    The social connection name to use.
  </ParamField>

  <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
    Additional data collected from the user.
  </ParamField>
</Expandable>

***

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist. An array of error objects from the transaction context.
</ParamField>


# LoginPasswordlessEmailCode
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/LoginPasswordlessEmailCode



The LoginPasswordlessEmailCode class implements the `login-passwordless-email-code` screen functionality. This screen collects the user's email and code.

<Frame>
  <img alt="Login Passwordless Email Code" />
</Frame>

## Constructors

Create an instance of LoginPasswordlessEmailCode screen manager

```ts Example theme={null}
import LoginPasswordlessEmailCode from '@auth0/auth0-acul-js/login-passwordless-email-code';

const loginPasswordlessEmailCode = new LoginPasswordlessEmailCode();
const { startResend } = loginPasswordlessEmailCode.resendManager({
  timeoutSeconds: 60,
  onStatusChange: (remainingSeconds, isDisabled) => {
    console.log(`Resend available in ${remainingSeconds}s, disabled: ${isDisabled}`);
  },
  onTimeout: () => {
    console.log('Resend is now available');
  }
});

// Call startResend when user clicks resend button
startResend();
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnLoginPasswordlessEmailCode">ScreenMembersOnLoginPasswordlessEmailCode</a></span>}>
  Contains details specific to the `login-passwordless-email-code` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembersOnLoginPasswordlessEmailCode">TransactionMembersOnLoginPasswordlessEmailCode</a></span>}>
  Provides transaction-specific data for the `login-passwordless-email-code` screen, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist. An array of error objects from the transaction context.
</ParamField>

<ParamField type="(options ?)" />

This methods resends the code to the user's email address.

```ts Example theme={null}
import LoginPasswordlessEmailCode from '@auth0/auth0-acul-js/login-passwordless-email-code';

const loginPasswordlessEmailCode = new LoginPasswordlessEmailCode();
loginPasswordlessEmailCode.resendCode();
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
    Additional data collected from the user.
  </ParamField>
</Expandable>

***

<ParamField type="(options ?)" />

This method creates a resend control manager for handling email code resend operations. A ResendControl object with resend functionality and state management

```typescript Example theme={null}
import LoginPasswordlessEmailCode from '@auth0/auth0-acul-js/login-passwordless-email-code';

const loginPasswordlessEmailCode = new LoginPasswordlessEmailCode();
const { startResend } = loginPasswordlessEmailCode.resendManager({
  timeoutSeconds: 60,
  onStatusChange: (remainingSeconds, isDisabled) => {
    console.log(`Resend available in ${remainingSeconds}s, disabled: ${isDisabled}`);
  },
  onTimeout: () => {
    console.log('Resend is now available');
  }
});

// Call startResend when user clicks resend button
startResend();
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/type-aliases/OnStatusChangeCallback">OnStatusChangeCallback</a></span>} />

  <ParamField type="void" />

  <ParamField type="number" />
</Expandable>

***

<ParamField type="(options ?)" />

This method continues the login process using email and code.

```ts Example theme={null}
//Creates an instance of LoginPasswordlessEmailCode and calls the method with sample data.
import LoginPasswordlessEmailCode from '@auth0/auth0-acul-js/login-passwordless-email-code';

//Method to continue the login process using email and code.
const loginPasswordlessEmailCode = new LoginPasswordlessEmailCode();
loginPasswordlessEmailCode.submitCode({
 email: "test@domain.com";
 code: "<string>";
});
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="string">
    The captcha code or response from the captcha provider. This property is required if your Auth0 tenant has Bot Detection enabled.
  </ParamField>

  <ParamField type="string | number">
    The code entered by the user.
  </ParamField>

  <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
    Additional data collected from the user.
  </ParamField>
</Expandable>

***


# LoginPasswordlessSmsOtp
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/LoginPasswordlessSmsOtp



The LoginPasswordlessSmsOtp class implements the `login-passwordless-sms-otp` screen functionality. This screen collects the user’s phone number and code.

## Constructors

Create an instance of LoginPasswordlessSmsOtp screen manager

<Frame>
  <img alt="" />
</Frame>

```ts Example theme={null}
import LoginPasswordlessSmsOtp from '@auth0/auth0-acul-js/login-passwordless-sms-otp';

const loginPasswordlessSmsOtp = new LoginPasswordlessSmsOtp();
const { startResend } = loginPasswordlessSmsOtp.resendManager({
  timeoutSeconds: 15,
  onStatusChange: (remainingSeconds, isDisabled) => {
    console.log(`Resend available in ${remainingSeconds}s, disabled: ${isDisabled}`);
  },
  onTimeout: () => {
    console.log('Resend is now available');
  }
});

// Call startResend when user clicks resend button
startResend();
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnLoginPasswordlessSmsOtp">ScreenMembersOnLoginPasswordlessSmsOtp</a></span>}>
  Contains details specific to the `login-passwordless-sms-otp` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembersOnLoginPasswordlessSmsOtp">TransactionMembersOnLoginPasswordlessSmsOtp</a></span>}>
  Provides transaction-specific data for the `login-passwordless-sms-otp` screen, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist. An array of error objects from the transaction context.
</ParamField>

<ParamField type="(options ?)" />

This method resends functionality with timeout management for this screen. A ResendControl object with startResend method.

```typescript Example theme={null}
import LoginPasswordlessSmsOtp from '@auth0/auth0-acul-js/login-passwordless-sms-otp';

const loginPasswordlessSmsOtp = new LoginPasswordlessSmsOtp();
const { startResend } = loginPasswordlessSmsOtp.resendManager({
  timeoutSeconds: 15,
  onStatusChange: (remainingSeconds, isDisabled) => {
    console.log(`Resend available in ${remainingSeconds}s, disabled: ${isDisabled}`);
  },
  onTimeout: () => {
    console.log('Resend is now available');
  }
});

// Call startResend when user clicks resend button
startResend();
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/type-aliases/OnStatusChangeCallback">OnStatusChangeCallback</a></span>} />

  <ParamField type="void" />

  <ParamField type="number" />
</Expandable>

***

<ParamField type="(options ?)" />

This methods resends the code to the user's phone number.

```ts Example theme={null}
import LoginPasswordlessSmsOtp from '@auth0/auth0-acul-js/login-passwordless-sms-otp';

const loginPasswordlessSmsOtp = new LoginPasswordlessSmsOtp();
loginPasswordlessSmsOtp.resendOTP();
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
    Additional data collected from the user.
  </ParamField>
</Expandable>

***

<ParamField type="(options ?)" />

This method continues the login process using the otp code.

```ts Example theme={null}
import LoginPasswordlessSmsOtp from '@auth0/auth0-acul-js/login-passwordless-sms-otp';
const loginPasswordlessSmsOtp = new LoginPasswordlessSmsOtp();

loginPasswordlessSmsOtp.submitOTP({
    username: "test@domain.com";
    code: "<string>";
});
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="string">
    The captcha code or response from the captcha provider. This property is required if your Auth0 tenant has Bot Detection enabled.
  </ParamField>

  <ParamField type="string">
    The code entered by the user.
  </ParamField>

  <ParamField type="string">
    The user's identifier.
  </ParamField>
</Expandable>


# Logout
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/Logout



The Logout class implements the `logout` screen functionality. This screen allows users to confirm or deny the logout action.

<Frame>
  <img alt="" />
</Frame>

## Constructors

Create an instance of the Logout screen manager.

```ts Example theme={null}
import Logout from '@auth0/auth0-acul-js/logout';

const logout = new Logout();

await logout.confirmLogout({ action: 'accept' });
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Contains details specific to the `logout` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)" />

This method confirms the logout action (accept or deny).

```typescript Example theme={null}
import Logout from '@auth0/auth0-acul-js/logout';

const logout = new Logout();

await logout.confirmLogout({ action: 'accept' });
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="&#x22;accept&#x22; | &#x22;deny&#x22;">
    The authentication transaction state.
  </ParamField>

  <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
    Additional data collected from the user.
  </ParamField>
</Expandable>

***

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist. An array of error objects from the transaction context.
</ParamField>


# LogoutAborted
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/LogoutAborted



The LogoutAborted class implements the `logout-aborted` screen functionality. This screen is displayed when a user aborts the logout process.

<Frame>
  <img alt="" />
</Frame>

## Constructors

Create an instance of LogoutAborted screen manager

```ts Example theme={null}
import LogoutAborted from '@auth0/auth0-acul-js/logout-aborted';

const logoutAbortedManager = new LogoutAborted();
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Contains details specific to the screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist. An array of error objects from the transaction context.
</ParamField>


# LogoutComplete
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/LogoutComplete



The LogoutComplete screen class provides methods associated with the `logout-complete` screen. This screen is displayed when a user completes the logout process.

<Frame>
  <img alt="" />
</Frame>

## Constructors

Create an instance of LogoutComplete screen manager

```ts Example theme={null}
import LogoutComplete from '@auth0/auth0-acul-js/logout-complete';

const logoutCompleteManager = new LogoutComplete();
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Contains details specific to the screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist. An array of error objects from the transaction context.
</ParamField>


# MfaBeginEnrollOptions
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaBeginEnrollOptions



The MfaBeginEnrollOptions class implements the `mfa-begin-enroll-options` screen functionality. This screen handles the selection and enrollment of MFA factors.
​

<Frame>
  <img alt="undefined" />
</Frame>

## Constructors

Create an instance of MFA Begin Enroll Options screen manager

```ts Example theme={null}
import MfaBeginEnrollOptions from '@auth0/auth0-acul-js/mfa-begin-enroll-options';
const mfaBeginEnrollOptions = new MfaBeginEnrollOptions();
await mfaBeginEnrollOptions.enroll({
  action: 'push-notification'
});
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Contains details specific to the screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)">
  This method continues the enrollment process with the selected factor.

  ```typescript Example theme={null}
  const mfaBeginEnrollOptions = new MfaBeginEnrollOptions();
  await mfaBeginEnrollOptions.enroll({
    action: 'push-notification'
  });
  ```

  <ParamField type="OPTIONAL">
    The enrollment options including the selected factor.

    <Expandable title="options properties">
      <ParamField type=" &#x22;push-notification&#x22; | &#x22;otp&#x22; | &#x22;sms&#x22; | &#x22;phone&#x22; | &#x22;voice&#x22; | &#x22;webauthn-roaming&#x22;">
        The action indicating which factor to enroll.
      </ParamField>

      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>


# MfaCountryCodes
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaCountryCodes



The MfaCountryCodes class implements the `mfa-country-codes` screen functionality. This screen allows users to select a country code for MFA phone number verification.

<Frame>
  <img alt="MFACountryCodes" />
</Frame>

## Constructors

Create an instance of MfaCountryCodes screen

```ts Example theme={null}
import MfaCountryCodes from '@auth0/auth0-acul-js/mfa-country-codes';

const mfaCountryCodes = new MfaCountryCodes();

// Get the available country codes and phone prefixes
const { screen } = mfaCountryCodes;
const { phone_prefixes } = screen.data
const {country_code, phone_prefix} = phone_prefixes[0]

await mfaCountryCodes.selectCountryCode({
  country_code: 'US',
  phone_prefix: '+1',
});
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Contains details specific to the screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method navigates back to the previous screen

  ```typescript Example theme={null}
  import MfaCountryCodes from '@auth0/auth0-acul-js/mfa-country-codes';
  const mfaCountryCodes = new MfaCountryCodes();
  await mfaCountryCodes.goBack();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method selects a country code from the available options.

  ```typescript Example theme={null}
  import MfaCountryCodes from '@auth0/auth0-acul-js/mfa-country-codes';

  const mfaCountryCodes = new MfaCountryCodes();

  // Get the available country codes and phone prefixes
  const { screen } = mfaCountryCodes;
  const { phone_prefixes } = screen.data
  const {country_code, phone_prefix} = phone_prefixes[0]

  await mfaCountryCodes.selectCountryCode({
    country_code: 'US',
    phone_prefix: '+1',
  });
  ```

  <ParamField type="OPTIONAL">
    The options containing the country code selection action.

    <Expandable title="options properties">
      <ParamField type="string">
        The country code (e.g. 'US', 'GB')
      </ParamField>

      <ParamField type="string">
        The phone prefix (e.g. '+1', '+44')
      </ParamField>

      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaDetectBrowserCapabilities
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaDetectBrowserCapabilities



The MfaDetectBrowserCapabilities class implements the `mfa-detect-browser-capabilities` screen functionality. This screen detects browser capabilities for MFA authentication methods.

<Frame>
  <img alt="" />
</Frame>

## Constructors

Create an instance of MfaDetectBrowserCapabilities screen

```ts Example theme={null}
import MfaDetectBrowserCapabilities from '@auth0/auth0-acul-js/mfa-detect-browser-capabilities';
const mfaDetectBrowserCapabilities = new MfaDetectBrowserCapabilities();
await mfaDetectBrowserCapabilities.detectCapabilities();
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Contains details specific to the screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method picks an authenticator based on browser capabilities

  ```typescript Example theme={null}
  const mfaDetectBrowserCapabilities = new MfaDetectBrowserCapabilities();
  await mfaDetectBrowserCapabilities.detectCapabilities();
  ```

  <ParamField type="OPTIONAL">
    The options containing browser capability flags.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaEmailChallenge
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaEmailChallenge



The MfaEmailChallenge class implements the `mfa-email-challenge` screen functionality. This screen is shown when a user needs to verify their email during MFA.

<Frame>
  <img alt="MfaEmailChallenge" />
</Frame>

## Constructors

Create an instance of MfaCountryCodes screen

```ts Example theme={null}
import MfaEmailChallenge from '@auth0/auth0-acul-js/mfa-email-challenge';

const mfaEmailChallenge = new MfaEmailChallenge();
await mfaEmailChallenge.continue({
  code: '123456',
  rememberDevice: true
});
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnMfaEmailChallenge">ScreenMembersOnMfaEmailChallenge</a></span>}>
  Contains details specific to the `mfa-email-challenge` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembersOnMfaEmailChallenge">UntrustedDataMembersOnMfaEmailChallenge</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)">
  This method continues with the email challenge using the provided code.

  ```typescript Example theme={null}
  import MfaEmailChallenge from '@auth0/auth0-acul-js/mfa-email-challenge';

  const mfaEmailChallenge = new MfaEmailChallenge();
  await mfaEmailChallenge.continue({
    code: '123456',
    rememberDevice: true
  });
  ```

  <ParamField type="OPTIONAL">
    The options for continuing with the email challenge.

    <Expandable title="options properties">
      <ParamField type="string">
        The code entered by the user.
      </ParamField>

      <ParamField type="boolean">
        Indicates whether to remember the device.
      </ParamField>

      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method submits the action to pick a different Email configuration, if available.

  ```typescript Example theme={null}
  import MfaEmailChallenge from '@auth0/auth0-acul-js/mfa-email-challenge';

  const mfaEmailChallenge = new MfaEmailChallenge();
  await mfaEmailChallenge.pickEmail();
  ```

  <ParamField type="OPTIONAL">
    Optional payload.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method resends the email code.

  ```typescript Example theme={null}
  import MfaEmailChallenge from '@auth0/auth0-acul-js/mfa-email-challenge';
  const mfaEmailChallenge = new MfaEmailChallenge();
  await mfaEmailChallenge.resendCode();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ResendControl">ResendControl</a></span>}>
  This method resends functionality with timeout management for this screen. A ResendControl object with startResend method.

  ```typescript Example theme={null}
  import MfaEmailChallenge from '@auth0/auth0-acul-js/mfa-email-challenge';

  const mfaEmailChallenge = new MfaEmailChallenge();
  const { startResend } = mfaEmailChallenge.resendManager({
    timeoutSeconds: 15,
    onStatusChange: (remainingSeconds, isDisabled) => {
      console.log(`Resend available in ${remainingSeconds}s, disabled: ${isDisabled}`);
    },
    onTimeout: () => {
      console.log('Resend is now available');
    }
  });

  // Call startResend when user clicks resend button
  startResend();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/type-aliases/OnStatusChangeCallback">OnStatusChangeCallback</a></span>} />

      <ParamField type="void" />

      <ParamField type="number" />
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method allows the user to try another MFA method.

  ```typescript Example theme={null}
  import MfaEmailChallenge from '@auth0/auth0-acul-js/mfa-email-challenge';

  const mfaEmailChallenge = new MfaEmailChallenge();
  await mfaEmailChallenge.tryAnotherMethod();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Any additional custom options.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaEmailList
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaEmailList



The MfaEmailList class implements the `mfa-email-list` screen functionality. This screen allows users to select an enrolled email address for MFA.

<Frame>
  <img alt="MfaEmailList" />
</Frame>

## Constructors

Create an instance of MfaEmailList screen

```ts Example theme={null}
import MfaEmailList from '@auth0/auth0-acul-js/mfa-email-list';

const mfaEmailList = new MfaEmailList();
await mfaEmailList.selectMfaEmail({
  index: 0 // for demonstration we are selecting the first index
});
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnMfaEmailList">ScreenMembersOnMfaEmailList</a></span>}>
  Contains details specific to the `mfa-email-list` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method navigates back to the previous screen.

  ```typescript Example theme={null}
  import MfaEmailList from '@auth0/auth0-acul-js/mfa-email-list';

  const mfaEmailList = new MfaEmailList();
  await mfaEmailList.goBack();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method selects an enrolled email address from the list.

  ```typescript Example theme={null}
  import MfaEmailList from '@auth0/auth0-acul-js/mfa-email-list';

  const mfaEmailList = new MfaEmailList();
  await mfaEmailList.selectMfaEmail({
    index: 0 // for demonstration we are selecting the first index
  });
  ```

  <ParamField type="OPTIONAL">
    The options containing the selection action.

    <Expandable title="options properties">
      <ParamField type="number">
        The index of the eamil to select.
      </ParamField>

      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaEnrollResult
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaEnrollResult



The MfaEnrollResult class implements the `mfa-enroll-result` screen functionality.

<Frame>
  <img alt="MfaEnrollResult" />
</Frame>

## Constructors

Create an instance of MfaEnrollResult screen. It initializes the `BaseContext` and sets up the `screen` property with an instance of `ScreenOverride` tailored for this screen.

```typescript Example theme={null}
import MfaEnrollResult from '@auth0/auth0-acul-js/mfa-enroll-result';

const mfaEnrollResultScreen = new MfaEnrollResult();

// Access screen data
const enrollmentStatus = mfaEnrollResultScreen.screen.data?.status;
const pageTitle = mfaEnrollResultScreen.screen.texts?.title;

console.log(`MFA Enrollment Status: ${enrollmentStatus}`);
console.log(`Page Title: ${pageTitle}`);
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnMfaEnrollResult">ScreenMembersOnMfaEnrollResult</a></span>}>
  Contains details specific to the `mfa-enroll-result` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>


# MfaLoginOptions
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaLoginOptions



The MfaLoginOptions class implements the `mfa-login-options` screen functionality. This screen allows users to select which MFA factor they want to use for login.

<Frame>
  <img alt="" />
</Frame>

## Constructors

Create an instance of MfaLoginOptions screen.

```ts Example theme={null}
import MfaLoginOptions from '@auth0/auth0-acul-js/mfa-login-options';

const mfaLoginOptions = new MfaLoginOptions();
await mfaLoginOptions.enroll({
  action: 'push-notification'
});
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnMfaLoginOptions">ScreenMembersOnMfaLoginOptions</a></span>}>
  Contains details specific to the `mfa-login-options` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)">
  This method continues the login process with the selected MFA factor

  ```typescript Example theme={null}
  const mfaLoginOptions = new MfaLoginOptions();
  await mfaLoginOptions.enroll({
    action: 'push-notification'
  });
  ```

  <ParamField type="OPTIONAL">
    The enrollment options including the selected factor.

    <Expandable title="options properties">
      <ParamField type=" &#x22;push-notification&#x22; | &#x22;otp&#x22; | &#x22;sms&#x22; | &#x22;phone&#x22; | &#x22;voice&#x22; | &#x22;webauthn-roaming&#x22;">
        The action indicating which factor to enroll.
      </ParamField>

      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method navigates back to the previous screen.

  ```ts Example theme={null}
  import MfaLoginOptions from '@auth0/auth0-acul-js/mfa-login-options';

  const mfaLoginOptions = new MfaLoginOptions();
  mfaLoginOptions.returnToPrevious();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaOtpChallenge
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaOtpChallenge



The MfaOtpChallenge class implements the `mfa-otp-challenge` screen functionality. This screen is shown when a user needs to enter an OTP code during MFA.

<Frame>
  <img alt="MfaOtpChallenge" />
</Frame>

## Constructors

Create an instance of MfaOtpChallenge screen

```ts Example theme={null}
import MfaOtpChallenge from '@auth0/auth0-acul-js/mfa-otp-challenge';

const mfaOtpChallenge = new MfaOtpChallenge();
await mfaOtpChallenge.continue({
  code: '123456',
  rememberDevice: true
});
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnMfaOtpChallenge">ScreenMembersOnMfaOtpChallenge</a></span>}>
  Contains details specific to the `mfa-otp-challenge` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembersOnMfaOtpChallenge">UntrustedDataMembersOnMfaOtpChallenge</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)">
  This method continues with the OTP challenge using the provided code.

  ```typescript Example theme={null}
  import MfaOtpChallenge from '@auth0/auth0-acul-js/mfa-otp-challenge';

  const mfaOtpChallenge = new MfaOtpChallenge();
  await mfaOtpChallenge.continue({
    code: '123456',
    rememberDevice: true
  });
  ```

  <ParamField type="OPTIONAL">
    The options containing the code and rememberDevice flag.

    <Expandable title="options properties">
      <ParamField type="string">
        The code entered by the user.
      </ParamField>

      <ParamField type="boolean">
        Indicates whether to remember the browser.
      </ParamField>

      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method allows the user to try another MFA method.

  ```typescript Example theme={null}
  import MfaOtpChallenge from '@auth0/auth0-acul-js/mfa-otp-challenge';

  const mfaOtpChallenge = new MfaOtpChallenge();
  await mfaOtpChallenge.tryAnotherMethod();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Options for trying another method.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaOtpEnrollmentCode
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaOtpEnrollmentCode



The MfaOtpEnrollmentCode class implements the `mfa-otp-enrollment-code` screen functionality. This screen is displayed when the user needs to enter the OTP code received during MFA enrollment.

<Frame>
  <img alt="MfaOtpEnrollmentCode" />
</Frame>

## Constructors

Create an instance of MfaOtpEnrollmentCode screen

```ts Example theme={null}
import MfaOtpEnrollmentCode from '@auth0/auth0-acul-js/mfa-otp-enrollment-code';

const mfaOtpEnrollmentCode = new MfaOtpEnrollmentCode();
await mfaOtpEnrollmentCode.continue({
  code: '123456',
});
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnMfaOtpEnrollmentCode">ScreenMembersOnMfaOtpEnrollmentCode</a></span>}>
  Contains details specific to the `mfa-otp-enrollment-code` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)">
  This method continues the MFA OTP enrollment process by submitting the OTP code.

  ```typescript Example theme={null}
  import MfaOtpEnrollmentCode from '@auth0/auth0-acul-js/mfa-otp-enrollment-code';

  const mfaOtpEnrollmentCode = new MfaOtpEnrollmentCode();
  await mfaOtpEnrollmentCode.continue({
    code: '123456',
  });
  ```

  <ParamField type="OPTIONAL">
    The options containing the OTP code.

    <Expandable title="options properties">
      <ParamField type="string">
        The OTP code entered by the user.
      </ParamField>

      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method allows the user to try another MFA method

  ```typescript Example theme={null}
  import MfaOtpEnrollmentCode from '@auth0/auth0-acul-js/mfa-otp-enrollment-code';

  const mfaOtpEnrollmentCode = new MfaOtpEnrollmentCode();
  await mfaOtpEnrollmentCode.tryAnotherMethod();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Any additional custom options.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaOtpEnrollmentQr
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaOtpEnrollmentQr



The MfaOtpEnrollmentQr class implements the `mfa-otp-enrollment-qr` screen functionality.

<Frame>
  <img alt="MfaOtpEnrollmentQr" />
</Frame>

## Constructors

Create an instance of MfaOtpEnrollmentQr screen

```ts Example theme={null}
import MfaOtpEnrollmentQr from '@auth0/auth0-acul-js/mfa-otp-enrollment-qr';

const mfaOtpEnrollmentQr = new MfaOtpEnrollmentQr();
await mfaOtpEnrollmentQr.toggleView();
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnMfaOtpEnrollmentQr">ScreenMembersOnMfaOtpEnrollmentQr</a></span>}>
  Contains details specific to the `mfa-otp-enrollment-qr` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembersOnMfaOtpChallenge">UntrustedDataMembersOnMfaOtpChallenge</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)">
  This method continues with the default action.

  ```typescript Example theme={null}
  import MfaOtpEnrollmentQr from '@auth0/auth0-acul-js/mfa-otp-enrollment-qr';

  const mfaOtpEnrollmentQr = new MfaOtpEnrollmentQr();
  await mfaOtpEnrollmentQr.continue({ code: '123456' });
  ```

  <ParamField type="OPTIONAL">
    The options containing the OTP code and optional custom options.

    <Expandable title="options properties">
      <ParamField type="string">
        The code entered by the user.
      </ParamField>

      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method navigates to the authenticator selection screen.

  ```typescript Example theme={null}
  import MfaOtpEnrollmentQr from '@auth0/auth0-acul-js/mfa-otp-enrollment-qr';

  const mfaOtpEnrollmentQr = new MfaOtpEnrollmentQr();
  await mfaOtpEnrollmentQr.toggleView();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        An object containing any custom options.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method allows trying another authentication method.

  ```typescript Example theme={null}
  import MfaOtpEnrollmentQr from '@auth0/auth0-acul-js/mfa-otp-enrollment-qr';

  const mfaOtpEnrollmentQr = new MfaOtpEnrollmentQr();
  await mfaOtpEnrollmentQr.tryAnotherMethod();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Any additional custom options.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaPhoneChallenge
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaPhoneChallenge



The MfaPhoneChallenge class implements the `mfa-phone-challenge` screen functionality. This screen is displayed when the user needs to receive a code to verity their identity.

<Frame>
  <img alt="" />
</Frame>

## Constructors

Create an instance of MfaPhoneChallenge screen

```ts Example theme={null}
import MfaPhoneChallenge from '@auth0/auth0-acul-js/mfa-phone-challenge';

const mfaPhoneChallenge = new MfaPhoneChallenge();
// Request code via SMS
await mfaPhoneChallenge.continue({ type: 'sms' });
// Request code via Voice Call
await mfaPhoneChallenge.continue({ type: 'voice' });
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnMfaPhoneChallenge">ScreenMembersOnMfaPhoneChallenge</a></span>}>
  Contains details specific to the `mfa-phone-challenge` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembersOnMfaEmailChallenge">UntrustedDataMembersOnMfaEmailChallenge</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)">
  This method submits the user's choice of receiving the MFA code via SMS or voice call. It uses the phone number provided in the screen context.

  ```typescript Example theme={null}
  const mfaPhoneChallenge = new MfaPhoneChallenge();
  // Request code via SMS
  await mfaPhoneChallenge.continue({ type: 'sms' });
  // Request code via Voice Call
  await mfaPhoneChallenge.continue({ type: 'voice' });
  ```

  <ParamField type="OPTIONAL">
    Options containing the delivery type ('sms' or 'voice').

    <Expandable title="options properties">
      <ParamField type="&#x22;sms&#x22; | &#x22;voice&#x22;">
        The type of challenge to perform.

        * `sms`: Send the code via text message (default).
        * `voice`: Send the code via a voice call.
      </ParamField>

      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method initiates the process for the user to select a different phone number (if applicable). This typically triggers a navigation to a phone selection screen.

  ```typescript Example theme={null}
  const mfaPhoneChallenge = new MfaPhoneChallenge();
  await mfaPhoneChallenge.pickPhone();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options for the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method allows the user to choose a different MFA method. For example: OTP or Recovery Code. This typically triggers navigation to the authenticator selection screen.

  ```typescript Example theme={null}
  const mfaPhoneChallenge = new MfaPhoneChallenge();
  await mfaPhoneChallenge.tryAnotherMethod();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options for the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaPhoneEnrollment
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaPhoneEnrollment



The MfaPhoneEnrollment class implements the `mfa-phone-enrollment` screen functionality. This screen allows users to enroll using a phone number for MFA.

<Frame>
  <img alt="MfaPhoneEnrollment" />
</Frame>

## Constructors

Create an instance of MfaPhoneEnrollment screen

```ts Example theme={null}
import MfaPhoneEnrollment from '@auth0/auth0-acul-js/mfa-phone-enrollment';
const mfaPhoneEnrollmentManager = new MfaPhoneEnrollment();
async function handlePickCountryCode() {
 try {
   await mfaPhoneEnrollmentManager.pickCountryCode();
   console.log('Country code selection successful.');
 } catch (error) {
   console.error('Error selecting country code:', error);
 }
}
/
  async pickCountryCode(payload?: CustomOptions): Promise<void> {
    const options = {
      state: this.transaction.state,
      telemetry: [MfaPhoneEnrollment.screenIdentifier, 'pickCountryCode'],
    };
    await new FormHandler(options).submitData<CustomOptions>({
      ...payload,
      action: 'pick-country-code',
    });
  }

  /**
Continues the enrollment process with the provided phone number and type (SMS or voice).
@param payload The phone number and type (SMS or voice).
@example
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Contains details specific to the screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)">
  This method continues the enrollment process with the provided phone number and type (SMS or voice).

  ```typescript Example theme={null}
  import MfaPhoneEnrollment from '@auth0/auth0-acul-js/mfa-phone-enrollment';
  const mfaPhoneEnrollmentManager = new MfaPhoneEnrollment();
  async function handleContinueEnrollment() {
   try {
     await mfaPhoneEnrollmentManager.continueEnrollment({
       phone: '+1234567890',
       type: 'sms', // or 'voice'
     });
     console.log('Phone enrollment continued successfully.');
   } catch (error) {
     console.error('Error continuing phone enrollment:', error);
   }
  }
  ```

  <ParamField type="OPTIONAL">
    The phone number and type (SMS or voice).

    <Expandable title="options properties">
      <ParamField type="string">
        The user's phone number.
      </ParamField>

      <ParamField type=" &#x22;sms&#x22; | &#x22;voice&#x22;">
        Define the method to receive the verification code.
      </ParamField>

      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method navigates to the country code selection screen.

  ```typescript Example theme={null}
  import MfaPhoneEnrollment from '@auth0/auth0-acul-js/mfa-phone-enrollment';
  const mfaPhoneEnrollmentManager = new MfaPhoneEnrollment();
  async function handlePickCountryCode() {
   try {
     await mfaPhoneEnrollmentManager.pickCountryCode();
     console.log('Country code selection successful.');
   } catch (error) {
     console.error('Error selecting country code:', error);
   }
  }

  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method allows the user to try another MFA method.

  ```typescript Example theme={null}
  import MfaPhoneEnrollment from '@auth0/auth0-acul-js/mfa-phone-enrollment';
  const mfaPhoneEnrollmentManager = new MfaPhoneEnrollment();
  async function handleTryAnotherMethod() {
   try {
     await mfaPhoneEnrollmentManager.tryAnotherMethod(); 
     console.log('Switched to another authentication method.');
    } catch (error) { 
   console.error('Error switching authenticator method:', error);
   }
  }
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaPushChallengePush
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaPushChallengePush



The MfaPushChallengePush class implements the `mfa-push-challenge-push` screen functionality. This screen is shown when a user needs to confirm a push notification during MFA.

<Frame>
  <img alt="MfaPushChallengePush" />
</Frame>

## Constructors

Create an instance of MfaPushChallengePush screen

```ts Example theme={null}
import MfaPushChallengePush from '@auth0/auth0-acul-js/mfa-push-challenge-push';
const mfaPushChallengePush = new MfaPushChallengePush();
await mfaPushChallengePush.continue();
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnMfaPushChallengePush">ScreenMembersOnMfaPushChallengePush</a></span>}>
  Contains details specific to the `mfa-push-challenge-push` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembersOnMfaPushChallengePush">UntrustedDataMembersOnMfaPushChallengePush</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)">
  This method continues with the push notification challenge.

  ```typescript Example theme={null}
  const mfaPushChallengePush = new MfaPushChallengePush();
  await mfaPushChallengePush.continue();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type="boolean">
        Indicates whether to remember the device.
      </ParamField>

      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method switches to entering the verification code manually.

  ```typescript Example theme={null}
  const mfaPushChallengePush = new MfaPushChallengePush();
  await mfaPushChallengePush.enterCodeManually();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/MfaPushPollingControl">MfaPushPollingControl</a></span>}>
  This method starts and manages polling for an MFA push challenge.

  Creates a polling session that repeatedly checks the MFA push challenge endpoint
  at the specified interval until the challenge is approved or an error occurs.
  When the approval condition is met, the provided
  [onCompleted](/docs/libraries/acul/js-sdk/Screens/type-aliases/MfaPollingOptions#oncompleted) callback is invoked and
  polling stops automatically.

  Use the returned [MfaPushPollingControl](/docs/libraries/acul/js-sdk/Screens/interfaces/MfaPushPollingControl) to start, stop, or check the
  status of the polling process at any time.

  Returns an [MfaPushPollingControl](/docs/libraries/acul/js-sdk/Screens/interfaces/MfaPushPollingControl) instance exposing:

  * `startPolling()` — Starts or resumes polling.
  * `stopPolling()` — Cancels polling immediately.
  * `isRunning()` — Indicates whether polling is currently active.

  ```ts Example theme={null}
  // Start polling every 5 seconds until the push challenge is approved
  const control = mfaPushChallengePush.pollingManager({
    intervalMs: 5000,
    onCompleted: () => mfaPushChallengePush.continue(),
    onError: (error) => console.error('Polling error:', error),
  });

  // Later, cancel polling if needed
  control.stopPolling();
  ```

  **Remarks**

  * HTTP 429 (rate limit) responses are handled internally: polling automatically
    waits until the rate limit resets before retrying.
  * Safe to call `startPolling()` multiple times; it has no effect if already running.

  <ParamField type="OPTIONAL">
    Configuration options for managing an MFA push-notification polling process.

    <Expandable title="options properties">
      <ParamField type="number">
        Optional interval, in milliseconds, between consecutive polling requests.

        * If omitted, the SDK’s internal default interval is used (typically 5000 ms).
        * Choose a value that balances responsiveness with rate-limit considerations.
      </ParamField>

      <ParamField type="() => void">
        Optional callback executed once the MFA push challenge is successfully approved and polling completes.

        * Called exactly once, after which polling stops automatically.
        * Useful for advancing the login flow (e.g., calling continue()).
      </ParamField>

      <ParamField type="(error) => void">
        Optional callback invoked if an error occurs while polling.
        Receives an ULError object containing:

        * `status` — the HTTP status code from the failed request
        * `responseText` — the raw response body, if available
        * Called once per error event; polling may retry depending on error type.
        * Use to surface error messages or trigger custom retry/abort logic.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method resends the push notification.

  ```typescript Example theme={null}
  const mfaPushChallengePush = new MfaPushChallengePush();
  await mfaPushChallengePush.resendPushNotification();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request

    <Expandable title="options properties">
      <ParamField type="boolean">
        Indicates whether to remember the device.
      </ParamField>

      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method allows the user to try another MFA method.

  ```typescript Example theme={null}
  const mfaPushChallengePush = new MfaPushChallengePush();
  await mfaPushChallengePush.tryAnotherMethod();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Any additional custom options.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaPushEnrollmentQr
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaPushEnrollmentQr



The MfaPushEnrollmentQr class implements the `mfa-push-enrollment-qr` screen functionality.

<Frame>
  <img alt="MfaPushEnrollmentQr" />
</Frame>

## Constructors

Create an instance of MfaPushEnrollmentQr screen

```ts Example theme={null}
import MfaPushEnrollmentQr from '@auth0/auth0-acul-js/mfa-push-enrollment-qr';

const mfaPushEnrollmentQr = new MfaPushEnrollmentQr();
await mfaPushEnrollmentQr.pickAuthenticator();
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnMfaPushEnrollmentQr">ScreenMembersOnMfaPushEnrollmentQr</a></span>}>
  Contains details specific to the `mfa-push-enrollment-qr` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method navigates to the authenticator selection screen.

  ```typescript Example theme={null}
  import MfaPushEnrollmentQr from '@auth0/auth0-acul-js/mfa-push-enrollment-qr';

  const mfaPushEnrollmentQr = new MfaPushEnrollmentQr();
  await mfaPushEnrollmentQr.pickAuthenticator();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/MfaPushPollingControl">MfaPushPollingControl</a></span>}>
  This method starts  and manages polling for an MFA push challenge.

  Creates a polling session that repeatedly checks the MFA push challenge endpoint
  at the specified interval until the challenge is approved or an error occurs.
  When the approval condition is met, the provided
  [onCompleted](/docs/libraries/acul/js-sdk/Screens/type-aliases/MfaPollingOptions#oncompleted) callback is invoked and
  polling stops automatically.

  Use the returned [MfaPushPollingControl](/docs/libraries/acul/js-sdk/Screens/interfaces/MfaPushPollingControl) to start, stop, or check the
  status of the polling process at any time.

  Returns an [MfaPushPollingControl](/docs/libraries/acul/js-sdk/Screens/interfaces/MfaPushPollingControl) instance exposing:

  * `startPolling()` — Starts or resumes polling.
  * `stopPolling()` — Cancels polling immediately.
  * `isRunning()` — Indicates whether polling is currently active.

  ```ts Example theme={null}
  // Start polling every 5 seconds until the push challenge is approved
  const control = mfaPushChallengePush.pollingManager({
    intervalMs: 5000,
    onCompleted: () => mfaPushChallengePush.continue(),
    onError: (error) => console.error('Polling error:', error),
  });

  // Later, cancel polling if needed
  control.stopPolling();
  ```

  **Remarks**

  * HTTP 429 (rate limit) responses are handled internally: polling automatically
    waits until the rate limit resets before retrying.
  * Safe to call `startPolling()` multiple times; it has no effect if already running.

  <ParamField type="OPTIONAL">
    Configuration options for managing an MFA push-notification polling process.

    <Expandable title="options properties">
      <ParamField type="number">
        Optional interval, in milliseconds, between consecutive polling requests.

        * If omitted, the SDK’s internal default interval is used (typically 5000 ms).
        * Choose a value that balances responsiveness with rate-limit considerations.
      </ParamField>

      <ParamField type="() => void">
        Optional callback executed once the MFA push challenge is successfully approved and polling completes.

        * Called exactly once, after which polling stops automatically.
        * Useful for advancing the login flow (e.g., calling continue()).
      </ParamField>

      <ParamField type="(error) => void">
        Optional callback invoked if an error occurs while polling.
        Receives an ULError object containing:

        * `status` — the HTTP status code from the failed request
        * `responseText` — the raw response body, if available
        * Called once per error event; polling may retry depending on error type.
        * Use to surface error messages or trigger custom retry/abort logic.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaPushList
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaPushList



The MfaPushList class implements the `mfa-push-list` screen functionality.

<Frame>
  <img alt="MfaPushList" />
</Frame>

## Constructors

Create an instance of MfaPushList screen

```ts Example theme={null}
import MfaPushList from '@auth0/auth0-acul-js/mfa-push-list';

const mfaPushList = new MfaPushList();
await mfaPushList.selectMfaPushDevice({ deviceIndex: 0 });
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Contains details specific to the screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method navigates back to the previous screen.

  ```typescript Example theme={null}
  import MfaPushList from '@auth0/auth0-acul-js/mfa-push-list';

  const mfaPushList = new MfaPushList();
  await mfaPushList.goBack();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Any additional custom options.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method selects a registered device from the list to initiate MFA push.

  ```typescript Example theme={null}
  import MfaPushList from '@auth0/auth0-acul-js/mfa-push-list';

  const mfaPushList = new MfaPushList();
  await mfaPushList.selectMfaPushDevice({ deviceIndex: 0 });
  ```

  <ParamField type="OPTIONAL">
    Options for selecting an MFA push device.

    <Expandable title="options properties">
      <ParamField type="number">
        The index of the device to select from the list of enrolled devices. The index is 0-based.
      </ParamField>

      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Any additional custom options.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaPushWelcome
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaPushWelcome



The MfaPushWelcome class implements the `mfa-push-welcome` screen functionality.

<Frame>
  <img alt="MfaPushWelcome" />
</Frame>

## Constructors

Create an instance of MfaPushWelcome screen

```ts Example theme={null}
import MfaPushWelcome from '@auth0/auth0-acul-js/mfa-push-welcome';

const mfaPushWelcome = new MfaPushWelcome();
await mfaPushWelcome.enroll();
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnMfaPushWelcome">ScreenMembersOnMfaPushWelcome</a></span>}>
  Contains details specific to the `mfa-push-welcome` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)">
  This method navigates to the enrollment screen.

  ```typescript Example theme={null}
  import MfaPushWelcome from '@auth0/auth0-acul-js/mfa-push-welcome';

  const mfaPushWelcome = new MfaPushWelcome();
  await mfaPushWelcome.enroll();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method navigates to the authenticator selection screen.

  ```typescript Example theme={null}
  import MfaPushWelcome from '@auth0/auth0-acul-js/mfa-push-welcome';

  const mfaPushWelcome = new MfaPushWelcome();
  await mfaPushWelcome.pickAuthenticator();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaRecoveryCodeChallenge
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaRecoveryCodeChallenge



The MfaRecoveryCodeChallenge class implements the `mfa-recovery-code-challenge` screen functionality. This screen is displayed when the user needs to enter a recovery code to log in.

<Frame>
  <img alt="MfaRecoveryCodeChallenge" />
</Frame>

## Constructors

Create an instance of MfaRecoveryCodeChallenge screen

```ts Example theme={null}
import MfaRecoveryCodeChallenge from '@auth0/auth0-acul-js/mfa-recovery-code-challenge';
const mfaRecoveryCodeChallengeManager = new MfaRecoveryCodeChallenge();
const handleContinueEnrollment = async () => {
 try {
   await mfaRecoveryCodeChallengeManager.continue('YOUR_RECOVERY_CODE');
 } catch (error) {
   console.error('Error continuing with recovery code:', error);
 }
}
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Contains details specific to the screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)">
  This method continues with the provided recovery code.

  ```typescript Example theme={null}
  import MfaRecoveryCodeChallenge from '@auth0/auth0-acul-js/mfa-recovery-code-challenge';
  const mfaRecoveryCodeChallengeManager = new MfaRecoveryCodeChallenge();
  const handleContinueEnrollment = async () => {
   try {
     await mfaRecoveryCodeChallengeManager.continue('YOUR_RECOVERY_CODE');
   } catch (error) {
     console.error('Error continuing with recovery code:', error);
   }
  }
  ```

  <ParamField type="OPTIONAL">
    The payload containing the recovery code and optional custom options.

    <Expandable title="options properties">
      <ParamField type="string">
        The code entered by the user.
      </ParamField>

      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method navigates to the screen where the user can pick another MFA method.

  ```typescript Example theme={null}
  import MfaRecoveryCodeChallenge from '@auth0/auth0-acul-js/mfa-recovery-code-challenge';
  const mfaRecoveryCodeChallengeManager = new MfaRecoveryCodeChallenge();
  const switchAuthenticator = async () => {
   try {
     await mfaRecoveryCodeChallengeManager.tryAnotherMethod();
     console.log('Switched to another authentication method.');
   } catch (error) {
     console.error('Error switching authenticator:', error);
   }
  };
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Any additional custom options.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaRecoveryCodeChallengeNewCode
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaRecoveryCodeChallengeNewCode



The MfaRecoveryCodeChallengeNewCode screen class provides methods associated with the `mfa-recovery-code-challenge-new-code` screen. This screen displays the MFA recovery code for safe keeping.

<Frame>
  <img alt="MfaRecoveryCodeChallengeNewCode" />
</Frame>

## Constructors

Create an instance of MfaRecoveryCodeChallengeNewCode screen

```ts Example theme={null}
import MfaRecoveryCodeChallengeNewCode from '@auth0/auth0-acul-js/mfa-recovery-code-challenge-new-code';
const screenManager = new MfaRecoveryCodeChallengeNewCode();
// Assuming a checkbox 'confirmSaved' is checked by the user
if (confirmSaved) {
  try {
    await screenManager.continue({ customData: 'optionalValue' });
  } catch (err) {
    // Handle errors, potentially check screenManager.transaction.errors
    console.error("Confirmation failed:", err);
  }
} else {
  // Prompt user to confirm saving the code
}
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnMfaRecoveryCodeChallengeNewCode">ScreenMembersOnMfaRecoveryCodeChallengeNewCode</a></span>}>
  Contains details specific to the \`mfa-recovery-code-challenge-new-code\`\` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)">
  This method confirms that the user has saved the new recovery code and continues the authentication flow.
  This method sends a POST request to the `/u/mfa-recovery-code-challenge-new-code` endpoint with the required `state`, `action`, and `saved` parameters.

  A promise that resolves when the confirmation is successfully submitted. On success, the browser will typically be redirected to the next step.

  Throws an error if the form submission fails (e.g., network issue, invalid state, or if the server responds with a 400 error like 'no-confirmation').

  ```typescript Example theme={null}
  const screenManager = new MfaRecoveryCodeChallengeNewCode();
  // Assuming a checkbox 'confirmSaved' is checked by the user
  if (confirmSaved) {
    try {
      await screenManager.continue({ customData: 'optionalValue' });
    } catch (err) {
      // Handle errors, potentially check screenManager.transaction.errors
      console.error("Confirmation failed:", err);
    }
  } else {
    // Prompt user to confirm saving the code
  }
  ```

  <ParamField type="OPTIONAL">
    Optional custom data to include with the request form body.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>


# MfaRecoveryCodeEnrollment
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaRecoveryCodeEnrollment



The MfaRecoveryCodeEnrollment class implements the `mfa-recovery-code-enrollment` screen functionality. This screen is displayed when the user needs to enroll with a recovery code for MFA.

<Frame>
  <img alt="MfaRecoveryCodeEnrollment" />
</Frame>

## Constructors

Create an instance of MfaRecoveryCodeEnrollment screen

```ts Example theme={null}
import MfaRecoveryCodeEnrollment from '@auth0/auth0-acul-js/mfa-recovery-code-enrollment';
const mfaRecoveryCodeEnrollmentManager = new MfaRecoveryCodeEnrollment();
const continueEnrollment = async (payload) => {
 try {
   await mfaRecoveryCodeEnrollmentManager.continue(payload);
   console.log('Enrollment continued successfully.');
 } catch (error) {
   console.error('Error continuing enrollment:', error);
 }
};
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnMfaRecoveryCodeEnrollment">ScreenMembersOnMfaRecoveryCodeEnrollment</a></span>}>
  Contains details specific to the `mfa-recovery-code-enrollment` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)">
  This method declares that the user saved the recovery code. This action is triggered when the user declares that they have saved the recovery code.
  It redirects to the next screen in the authentication flow. Returns a promise that resolves when the action is successfully submitted.

  ```typescript Example theme={null}
  import MfaRecoveryCodeEnrollment from '@auth0/auth0-acul-js/mfa-recovery-code-enrollment';
  const mfaRecoveryCodeEnrollmentManager = new MfaRecoveryCodeEnrollment();
  const continueEnrollment = async (payload) => {
   try {
     await mfaRecoveryCodeEnrollmentManager.continue(payload);
     console.log('Enrollment continued successfully.');
   } catch (error) {
     console.error('Error continuing enrollment:', error);
   }
  };
  ```

  <ParamField type="OPTIONAL">
    An object containing any custom options.

    <Expandable title="options properties">
      <ParamField type="boolean">
        Indicates whether the code has been copied.
      </ParamField>

      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>


# MfaSmsChallenge
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaSmsChallenge



The MfaSmsChallenge class implements the `mfa-sms-challenge` screen functionality.

<Frame>
  <img alt="MfaSmsChallenge" />
</Frame>

## Constructors

Create an instance of MfaSmsChallenge screen

```ts Example theme={null}
import MfaSmsChallenge from '@auth0/auth0-acul-js/mfa-sms-challenge';

const mfaSmsChallenge = new MfaSmsChallenge();
await mfaSmsChallenge.continueMfaSmsChallenge({
  code: '123456',
  rememberDevice: true,
});
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnMfaSmsChallenge">ScreenMembersOnMfaSmsChallenge</a></span>}>
  Contains details specific to the `mfa-sms-challenge` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembersOnMfaSmsChallenge">UntrustedDataMembersOnMfaSmsChallenge</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)">
  This method submits the MFA SMS challenge with the provided code and rememberDevice option.

  ```typescript Example theme={null}
  import MfaSmsChallenge from '@auth0/auth0-acul-js/mfa-sms-challenge';

  const mfaSmsChallenge = new MfaSmsChallenge();
  await mfaSmsChallenge.continueMfaSmsChallenge({
    code: '123456',
    rememberDevice: true,
  });
  ```

  <ParamField type="OPTIONAL">
    The payload containing the code and rememberDevice option.

    <Expandable title="options properties">
      <ParamField type="string">
        The code entered by the user.
      </ParamField>

      <ParamField type="boolean">
        Indicates whether to remember the device.
      </ParamField>

      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method submits the action to switch to voice call verification.

  ```typescript Example theme={null}
  import MfaSmsChallenge from '@auth0/auth0-acul-js/mfa-sms-challenge';

  const mfaSmsChallenge = new MfaSmsChallenge();
  await mfaSmsChallenge.getACall();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method submits the action to pick a different SMS configuration, if available.

  ```typescript Example theme={null}
  import MfaSmsChallenge from '@auth0/auth0-acul-js/mfa-sms-challenge';

  const mfaSmsChallenge = new MfaSmsChallenge();
  await mfaSmsChallenge.pickSms();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method submits the action to resend the SMS code.

  ```typescript Example theme={null}
  import MfaSmsChallenge from '@auth0/auth0-acul-js/mfa-sms-challenge';

  const mfaSmsChallenge = new MfaSmsChallenge();
  await mfaSmsChallenge.resendCode();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ResendControl">ResendControl</a></span>}>
  This method resends functionality with timeout management for this screen. A ResendControl object with startResend method

  ```typescript Example theme={null}
  import MfaSmsChallenge from '@auth0/auth0-acul-js/mfa-sms-challenge';

  const mfaSmsChallenge = new MfaSmsChallenge();
  const { startResend } = mfaSmsChallenge.resendManager({
    timeoutSeconds: 15,
    onStatusChange: (remainingSeconds, isDisabled) => {
      console.log(`Resend available in ${remainingSeconds}s, disabled: ${isDisabled}`);
    },
    onTimeout: () => {
      console.log('Resend is now available');
    }
  });

  // Call startResend when user clicks resend button
  startResend();
  ```

  <ParamField type="OPTIONAL">
    Configuration options for resend functionality.

    <Expandable title="options properties">
      <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/type-aliases/OnStatusChangeCallback">OnStatusChangeCallback</a></span>} />

      <ParamField type="void" />

      <ParamField type="number" />
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method allows the user to try another MFA method.

  ```typescript Example theme={null}
  import MfaSmsChallenge from '@auth0/auth0-acul-js/mfa-sms-challenge';

  const mfaSmsChallenge = new MfaSmsChallenge();
  await mfaSmsChallenge.tryAnotherMethod();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Any additional custom options.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaSmsEnrollment
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaSmsEnrollment



The MfaSmsEnrollment class implements the `mfa-sms-enrollment` screen functionality.

<Frame>
  <img alt="MfaEmailChallenge" />
</Frame>

## Constructors

Create an instance of MfaSmsEnrollment screen

```ts Example theme={null}
import MfaSmsEnrollment from '@auth0/auth0-acul-js/mfa-sms-enrollment';

const mfaSmsEnrollment = new MfaSmsEnrollment();
await mfaSmsEnrollment.pickCountryCode();
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnMfaSmsEnrollment">ScreenMembersOnMfaSmsEnrollment</a></span>}>
  Contains details specific to the `mfa-sms-enrollment` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)">
  This method continues the SMS enrollment process with the provided phone number. Returns a promise that resolves when the enrollment process is complete.

  ```typescript Example theme={null}
  import MfaSmsEnrollment from '@auth0/auth0-acul-js/mfa-sms-enrollment';

  const mfaSmsEnrollment = new MfaSmsEnrollment();
  await mfaSmsEnrollment.continueEnrollment({ phone: '1234567890' });
  ```

  <ParamField type="OPTIONAL">
    The phone number to use for enrollment.

    <Expandable title="options properties">
      <ParamField type="string">
        The captcha code or response from the captcha provider. This property is required if your Auth0 tenant has Bot Detection enabled.
      </ParamField>

      <ParamField type="string">
        The user's phone number.
      </ParamField>

      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method handles the action to pick a country code for SMS enrollment. Returns a promise that resolves when the action is complete.

  ```typescript Example theme={null}
  import MfaSmsEnrollment from '@auth0/auth0-acul-js/mfa-sms-enrollment';

  const mfaSmsEnrollment = new MfaSmsEnrollment();
  await mfaSmsEnrollment.pickCountryCode();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include in the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method handles the action to try another method for MFA. Returns a promise that resolves when the action is complete.

  ```typescript Example theme={null}
  import MfaSmsEnrollment from '@auth0/auth0-acul-js/mfa-sms-enrollment';

  const mfaSmsEnrollment = new MfaSmsEnrollment();
  await mfaSmsEnrollment.tryAnotherMethod();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include in the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaSmsList
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaSmsList



The MfaSmsList class implements the `mfa-sms-list` screen functionality.

<Frame>
  <img alt="MfaSmsList" />
</Frame>

## Constructors

Create an instance of MfaSmsList screen

```ts Example theme={null}
import MfaSmsList from '@auth0/auth0-acul-js/mfa-sms-list';
const mfaSmsList = new MfaSmsList();
const selectPhoneNumber = async () => {
 const getEnrolledPhoneNumbers = mfaSmsList.user.enrolledPhoneNumbers;
 const selectedNumber = getEnrolledPhoneNumbers[0];
 await mfaSmsList.selectPhoneNumber({index: selectedNumber});
}
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Contains details specific to the screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)">
  This method navigates back to the previous screen.

  ```typescript Example theme={null}
  import MfaSmsList from '@auth0/auth0-acul-js/mfa-sms-list';
  const mfaSmsList = new MfaSmsList();
  const handleBackAction = async () => {
   try {
     await mfaSmsList.backAction();
   } catch (error) {
     console.error('Failed to go back:', error);
   }
  };
  ```

  <ParamField type="OPTIONAL">
    An object containing any custom options.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method selects a phone number from the list of enrolled phone numbers.

  ```typescript Example theme={null}
  import MfaSmsList from '@auth0/auth0-acul-js/mfa-sms-list';
  const mfaSmsList = new MfaSmsList();
  const selectPhoneNumber = async () => {
   const getEnrolledPhoneNumbers = mfaSmsList.user.enrolledPhoneNumbers;
   const selectedNumber = getEnrolledPhoneNumbers[0];
   await mfaSmsList.selectPhoneNumber({index: selectedNumber});
  }
  ```

  <ParamField type="OPTIONAL">
    Optional payload for the action.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>

      <ParamField type="number">
        The index of the phone number to select.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaVoiceChallenge
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaVoiceChallenge



The MfaVoiceChallenge class implemnents the `mfa-voice-challenge` screen functionality. This screen is displayed when a user needs to verify their identity using a voice call as part of a multi-factor authentication flow.

<Frame>
  <img alt="MfaRecoveryCodeEnrollment" />
</Frame>

## Constructors

Create an instance of MfaVoiceChallenge screen

```ts Example theme={null}
import MfaVoiceChallenge from '@auth0/auth0-acul-js/mfa-voice-challenge';
const mfaVoiceChallenge = new MfaVoiceChallenge();
mfaVoiceChallenge.continue({
  code: '123456',
  rememberDevice: true
});
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnMfaVoiceChallenge">ScreenMembersOnMfaVoiceChallenge</a></span>}> Contains details specific to the `mfa-voice-challenge` screen, including its configuration and context.</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembersOnMfaVoiceChallenge">UntrustedDataMembersOnMfaVoiceChallenge</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)">
  This method submits the voice verification code to validate the MFA challenge. Returns a promise that resolves when the code is successfully validated.

  ```typescript Example theme={null}
  import MfaVoiceChallenge from '@auth0/auth0-acul-js/mfa-voice-challenge';
  const mfaVoiceChallenge = new MfaVoiceChallenge();
  mfaVoiceChallenge.continue({
    code: '123456',
    rememberDevice: true
  });
  ```

  <ParamField type="OPTIONAL">
    An object containing the verification code and optional parameters

    <Expandable title="options properties">
      <ParamField type="string">
        The verification code received via voice call.
      </ParamField>

      <ParamField type="boolean">
        Optional flag to remember the device for 30 days, skipping future MFA challenges.
      </ParamField>

      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional custom options to pass with the request.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method navigates to the screen for selecting a different phone number. Returns a promise that resolves when navigation is complete.

  ```typescript Example theme={null}
  import MfaVoiceChallenge from '@auth0/auth0-acul-js/mfa-voice-challenge';
  const mfaVoiceChallenge = new MfaVoiceChallenge();
  mfaVoiceChallenge.pickPhone();
  ```

  <ParamField type="OPTIONAL">
    An object containing any custom options.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method requests a new voice call with a verification code. Returns a promise that resolves when the new code is sent

  ```typescript Example theme={null}
  import MfaVoiceChallenge from '@auth0/auth0-acul-js/mfa-voice-challenge';
  const mfaVoiceChallenge = new MfaVoiceChallenge();
  mfaVoiceChallenge.resendCode();
  ```

  <ParamField type="OPTIONAL">
    An object containing any custom options.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ResendControl">ResendControl</a></span>}>
  This method resends functionality with timeout management for this screen. Returns a ResendControl object with startResend method.

  ```typescript Example theme={null}
  import MfaVoiceChallenge from '@auth0/auth0-acul-js/mfa-voice-challenge';

  const mfaVoiceChallenge = new MfaVoiceChallenge();
  const { startResend } = mfaVoiceChallenge.resendManager({
    timeoutSeconds: 15,
    onStatusChange: (remainingSeconds, isDisabled) => {
      console.log(`Resend available in ${remainingSeconds}s, disabled: ${isDisabled}`);
    },
    onTimeout: () => {
      console.log('Resend is now available');
    }
  });

  // Call startResend when user clicks resend button
  startResend();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/type-aliases/OnStatusChangeCallback">OnStatusChangeCallback</a></span>} />

      <ParamField type="void" />

      <ParamField type="number" />
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This mehtod wwitches to SMS verification method instead of voice call. Returns a promise that resolves when switching is complete.

  ```typescript Example theme={null}
  import MfaVoiceChallenge from '@auth0/auth0-acul-js/mfa-voice-challenge';

  const mfaVoiceChallenge = new MfaVoiceChallenge();
  mfaVoiceChallenge.switchToSms();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Any additional custom options.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method navigates to the screen for selecting an alternative MFA method. Returns a promise that resolves when navigation is complete.

  ```typescript Example theme={null}
  import MfaVoiceChallenge from '@auth0/auth0-acul-js/mfa-voice-challenge';

  const mfaVoiceChallenge = new MfaVoiceChallenge();
  mfaVoiceChallenge.tryAnotherMethod();
  ```

  <ParamField type="OPTIONAL">
    Optional custom options to include with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Any additional custom options.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaVoiceEnrollment
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaVoiceEnrollment



The MfaVoiceEnrollment screen class provides methods associated with the `mfa-voice-enrollment` screen. This screen is displayed for a user needs to enter a phone number to receive a voice call with a code to continue enrollment.

<Frame>
  <img alt="MfaVoiceEnrollment" />
</Frame>

## Constructors

Create an instance of MfaVoiceEnrollment screen

```ts Example theme={null}
import MfaVoiceEnrollment from '@auth0/auth0-acul-js/mfa-voice-enrollment';
const mfaVoiceEnrollmentManager = new MfaVoiceEnrollment();
const handleContinueEnrollment = async () => {
 try {
   await mfaVoiceEnrollmentManager.continue({
     phone: '+1234567890',
     // Add any optional CustomOptions here if needed 
   });
   console.log('Voice enrollment continued successfully.');
 } catch (error) {
   console.error('Error continuing voice enrollment:', error);
 }
};
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Contains details specific to the screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)">
  This method continues with the default action.

  ```typescript Example theme={null}
  import MfaVoiceEnrollment from '@auth0/auth0-acul-js/mfa-voice-enrollment';
  const mfaVoiceEnrollmentManager = new MfaVoiceEnrollment();
  const handleContinueEnrollment = async () => {
   try {
     await mfaVoiceEnrollmentManager.continue({
       phone: '+1234567890',
       // Add any optional CustomOptions here if needed 
     });
     console.log('Voice enrollment continued successfully.');
   } catch (error) {
     console.error('Error continuing voice enrollment:', error);
   }
  };
  ```

  <ParamField type="OPTIONAL">
    Optional payload.

    <Expandable title="options properties">
      <ParamField type="string" />

      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method allows picking a country code for the phone number.

  ```typescript Example theme={null}
  import MfaVoiceEnrollment from '@auth0/auth0-acul-js/mfa-voice-enrollment';
  const mfaVoiceEnrollment = new MfaVoiceEnrollment();
  const handlePickCountryCode = async () => {
   await mfaVoiceEnrollment.selectPhoneCountryCode();
  };
  ```

  <ParamField type="OPTIONAL">
    Optional payload.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method allows the user to try another MFA method.

  ```typescript Example theme={null}
  import MfaVoiceEnrollment from '@auth0/auth0-acul-js/mfa-voice-enrollment';
  const mfaVoiceEnrollment = new MfaVoiceEnrollment();
  const handleTryAnotherMethod = async () => {
   await mfaVoiceEnrollment.tryAnotherMethod();
  };
  ```

  <ParamField type="OPTIONAL">
    Optional payload.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Any additional custom options.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaWebAuthnChangeKeyNickname
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaWebAuthnChangeKeyNickname



The MfaWebAuthnChangeKeyNickname class implements the `mfa-webauthn-change-key-nickname` screen functionality.

<Frame>
  <img alt="MfaWebAuthnChangeKeyNickname" />
</Frame>

## Constructors

Create an instance of MfaWebAuthnChangeKeyNickname screen

```ts Example theme={null}
import MfaWebAuthnChangeKeyNickname from "@auth0/auth0-acul-js/mfa-webauthn-change-key-nickname";

const mfaWebAuthnChangeKeyNicknameManager = new MfaWebAuthnChangeKeyNickname();
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnMfaWebAuthnChangeKeyNickname">ScreenMembersOnMfaWebAuthnChangeKeyNickname</a></span>}>
  Contains details specific to the `mfa-webauthn-change-key-nickname` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)">
  This method submits the new nickname provided by the user for their WebAuthn security key. This method prepares and posts the form data, including the new `nickname` and the
  required `action: "default"`, to the `/u/mfa-webauthn-change-key-nickname` endpoint. Returns a promise that resolves once the form submission is initiated. Typically, a successful submission leads to a server-side redirect. If the nickname is invalid or another error occurs, the page will re-render, and `this.transaction.errors` will be populated with details.

  <ParamField type="OPTIONAL">
    An object containing the `nickname` `string` entered by the user. It may also contain other custom parameters if needed for extensibility.

    <Expandable title="options properties">
      <ParamField type="string">
        The new nickname for the WebAuthn security key. This is the value entered by the user in the input field. It must adhere to length and character constraints defined by the server.
      </ParamField>

      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Any additional custom options.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>


# MfaWebAuthnEnrollmentSuccess
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaWebAuthnEnrollmentSuccess



The MfaWebAuthnEnrollmentSuccess class implements the `mfa-webauthn-enrollment-success` screen functionality.

<Frame>
  <img alt="MfaWebAuthnEnrollmentSuccess" />
</Frame>

## Constructors

Create an instance of MfaWebAuthnEnrollmentSuccess screen

```ts Example theme={null}
import MfaWebAuthnEnrollmentSuccess from '@auth0/auth0-acul-js/mfa-webauthn-enrollment-success';
const sdk = new MfaWebAuthnEnrollmentSuccess();

// Assuming 'sdk' is an instance of MfaWebAuthnEnrollmentSuccess
async function handleContinueClick() {
  try {
    await sdk.continue();
    // User will be redirected by Auth0.
  } catch (error) {
    console.error("Error continuing after WebAuthn enrollment success:", error);
    // Display error message to the user, potentially from sdk.transaction.errors
  }
}
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnMfaWebAuthnEnrollmentSuccess">ScreenMembersOnMfaWebAuthnEnrollmentSuccess</a></span>}>
  Contains details specific to the `mfa-webauthn-enrollment-success` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)">
  This method allows the user to continue the authentication flow after a successful WebAuthn enrollment. This method sends a POST request to the `/u/mfa-webauthn-enrollment-success` endpoint with the action set to "default", indicating the user is proceeding from this success screen. Returns a promise that resolves when the continue action is successfully submitted.

  ```typescript Example theme={null}
  import MfaWebAuthnEnrollmentSuccess from '@auth0/auth0-acul-js/mfa-webauthn-enrollment-success';
  const sdk = new MfaWebAuthnEnrollmentSuccess();

  // Assuming 'sdk' is an instance of MfaWebAuthnEnrollmentSuccess
  async function handleContinueClick() {
    try {
      await sdk.continue();
      // User will be redirected by Auth0.
    } catch (error) {
      console.error("Error continuing after WebAuthn enrollment success:", error);
      // Display error message to the user, potentially from sdk.transaction.errors
    }
  }
  ```

  <ParamField type="OPTIONAL">
    Optional. An object for `CustomOptions` if any additional parameters need to be sent with the request. These custom parameters will be included in the form data.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>


# MfaWebAuthnError
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaWebAuthnError



The MFAWebauthnError screen class provides methods associated with the `mfa-webauthn-error` screen.

<Frame>
  <img alt="MFAWebauthnError" />
</Frame>

## Constructors

Create an instance of MFAWebauthnError screen

```ts Example theme={null}
import MfaWebAuthnError from "@auth0/auth0-acul-js/mfa-webauthn-error";
const mfaWebAuthnErrorManager = new MfaWebAuthnError();
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnMfaWebAuthnError">ScreenMembersOnMfaWebAuthnError</a></span>}>
  Contains details specific to the `mfa-webauthn-error` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method allows the user to decline the current WebAuthn operation (e.g., refuse to add a device during enrollment). This action signifies the user's choice not to proceed with the WebAuthn step at this time. Returns a promise that resolves upon successful submission of the 'refuse-add-device' action.

  ```typescript Example theme={null}
  import MfaWebAuthnError from "@auth0/auth0-acul-js/mfa-webauthn-error";
  const sdk = new MfaWebAuthnError();

  await sdk.noThanks();
  ```

  <ParamField type="OPTIONAL">
    Optional custom parameters to be sent with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method allows the user to retry the previous WebAuthn operation. This action typically redirects the user to the screen where the WebAuthn process was initially attempted (e.g., back to the MFA challenge or enrollment screen for WebAuthn). Returns a promise that resolves upon successful submission of the 'tryagain' action.

  ```typescript Example theme={null}
  import MfaWebAuthnError from "@auth0/auth0-acul-js/mfa-webauthn-error";
  const sdk = new MfaWebAuthnError();

  await sdk.tryAgain();
  ```

  <ParamField type="OPTIONAL">
    Optional custom parameters to be sent with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method allows the user to choose a different Multi-Factor Authentication method. This action navigates the user to a screen where they can select from other available/enrolled MFA factors. Returns a promise that resolves upon successful submission of the 'pick-authenticator' action.

  ```typescript Example theme={null}
  import MfaWebAuthnError from "@auth0/auth0-acul-js/mfa-webauthn-error";
  const sdk = new MfaWebAuthnError();

  await sdk.tryAnotherMethod();
  ```

  <ParamField type="OPTIONAL">
    Optional custom parameters to be sent with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method allows the user to attempt authentication using their password, if this alternative is configured and appropriate for the current flow (e.g., if password was a prior authentication step or is a valid MFA bypass). Returns a promise that resolves upon successful submission of the 'use-password' action.

  ```typescript Example theme={null}
  import MfaWebAuthnError from "@auth0/auth0-acul-js/mfa-webauthn-error";
  const sdk = new MfaWebAuthnError();

  await sdk.usePassword();
  ```

  <ParamField type="OPTIONAL">
    Optional custom parameters to be sent with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaWebAuthnNotAvailableError
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaWebAuthnNotAvailableError



The MfaWebAuthnNotAvailableError screen class provides methods associated with the `mfa-webauthn-not-available-error` screen.

<Frame>
  <img alt="MfaWebAuthnNotAvailableError" />
</Frame>

## Constructors

Create an instance of MfaWebAuthnNotAvailableError screen

```ts Example theme={null}
import MfaWebAuthnNotAvailableError from "@auth0/auth0-acul-js/mfa-webauthn-not-available-error";
const sdk = new MfaWebAuthnNotAvailableError();

try {
  await sdk.tryAnotherMethod();
  // On success, Auth0 typically handles redirection to the MFA factor selection screen.
} catch (error) {
  console.error('Failed to initiate "try another method":', error);
  // Update UI to inform the user about the failure to switch methods.
}
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Contains details specific to the screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method allows the user to select a different Multi-Factor Authentication method because WebAuthn is not available or supported on their current device/browser. This action navigates the user to a screen where they can choose from other available/enrolled MFA factors. Returns a promise that resolves upon successful submission of the 'pick-authenticator' action.

  ```typescript Example theme={null}
  import MfaWebAuthnNotAvailableError from "@auth0/auth0-acul-js/mfa-webauthn-not-available-error";
  const sdk = new MfaWebAuthnNotAvailableError();

  try {
    await sdk.tryAnotherMethod();
    // On success, Auth0 typically handles redirection to the MFA factor selection screen.
  } catch (error) {
    console.error('Failed to initiate "try another method":', error);
    // Update UI to inform the user about the failure to switch methods.
  }
  ```

  <ParamField type="OPTIONAL">
    Optional custom parameters to be sent with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaWebAuthnPlatformChallenge
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaWebAuthnPlatformChallenge



The MfaWebAuthnPlatformChallenge screen class provides methods associated with the `mfa-webauthn-platform-challenge` screen.

<Frame>
  <img alt="MfaWebAuthnPlatformChallenge" />
</Frame>

## Constructors

Create an instance of MfaWebAuthnPlatformChallenge screen

```ts Example theme={null}
import MfaWebAuthnPlatformChallenge from "@auth0/auth0-acul-js/mfa-webauthn-platform-challenge";

const mfaWebAuthnPlatformChallengeManager = new MfaWebAuthnPlatformChallenge();
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnMfaWebAuthnPlatformChallenge">ScreenMembersOnMfaWebAuthnPlatformChallenge</a></span>}>
  Contains details specific to the `mfa-webauthn-platform-challenge` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method reports a browser-side error encountered during the WebAuthn `navigator.credentials.get()` operation. This method should be called when `verify()` fails due to a WebAuthn API error (e.g., user cancellation). It sends the error details to the server with a specific action format. Returns a promise that resolves when the error report is successfully submitted.

  ```typescript Example theme={null}
  import MfaWebAuthnPlatformChallenge from "@auth0/auth0-acul-js/mfa-webauthn-platform-challenge";
  const sdk = new MfaWebAuthnPlatformChallenge();

  await sdk.reportBrowserError( {
    error: 'message'
  });
  ```

  <ParamField type="OPTIONAL">
    Contains the error object (with `name` and `message` properties from the browser's WebAuthn API DOMException) and any other custom options.

    <Expandable title="options properties">
      <ParamField type="&#x22;messages: string&#x22; | &#x22;name: string&#x22;">
        The error message.
      </ParamField>

      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method allows the user to opt-out of the WebAuthn platform challenge and select a different MFA method. This action submits `action: "pick-authenticator"` to Auth0, which should navigate the user to an MFA factor selection screen. Returns a promise that resolves when the 'pick-authenticator' action is submitted.

  ```typescript Example theme={null}
  import MfaWebAuthnPlatformChallenge from "@auth0/auth0-acul-js/mfa-webauthn-platform-challenge";
  const sdk = new MfaWebAuthnPlatformChallenge();

  await sdk.tryAnotherMethod();
  ```

  <ParamField type="OPTIONAL">
    Optional custom parameters to be sent with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method initiates the WebAuthn platform authenticator challenge. Returns a promise that resolves when the credential submission is initiated.

  ```typescript Example theme={null}
  import MfaWebAuthnPlatformChallenge from "@auth0/auth0-acul-js/mfa-webauthn-platform-challenge";
  const sdk = new MfaWebAuthnPlatformChallenge();

  await sdk.verify();
  ```

  <ParamField type="OPTIONAL">
    Optional parameters for the verification. This can include `rememberDevice` if `this.screen.showRememberDevice` is true, and any other custom key-value pairs to be sent in the form submission.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>

      <ParamField type="boolean">
        If true, attempts to remember the browser for future MFA challenges. Corresponds to the `rememberBrowser` form field. This is only applicable if `screen.showRememberDevice` is true.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaWebAuthnPlatformEnrollment
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaWebAuthnPlatformEnrollment



The MfaWebAuthnPlatformEnrollment screen class provides methods associated with the `mfa-webauthn-platform-enrollment` screen.

<Frame>
  <img alt="MfaWebAuthnPlatformEnrollment" />
</Frame>

## Constructors

Create an instance of MfaWebAuthnPlatformEnrollment screen

```ts Example theme={null}
import MfaWebAuthnPlatformEnrollment from "@auth0/auth0-acul-js/mfa-webauthn-platform-enrollment";
const sdk = new MfaWebAuthnPlatformEnrollment();

try {
  await sdk.submitPasskeyCredential(); // No need to pass publicKey explicitly
  // On success, Auth0 handles redirection.
} catch (error) {
  console.error('Passkey enrollment failed:', error);
  if (error.name && error.message) { // Check if it looks like a WebAuthn error
    await sdk.reportBrowserError({ error: { name: error.name, message: error.message } });
  }
}
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnMfaWebAuthnPlatformEnrollment">ScreenMembersOnMfaWebAuthnPlatformEnrollment</a></span>}>
  Contains details specific to the `mfa-webauthn-platform-enrollment` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method allows the user to refuse WebAuthn platform enrollment on the current device. Returns a promise that resolves upon successful submission of the refusal action.

  ```typescript Example theme={null}
  import MfaWebAuthnPlatformEnrollment from "@auth0/auth0-acul-js/mfa-webauthn-platform-enrollment";
  const sdk = new MfaWebAuthnPlatformEnrollment();

  sdk.refuseEnrollmentOnThisDevice();
  ```

  <ParamField type="OPTIONAL">
    Optional custom parameters to be sent with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method reports a browser-side error encountered during the WebAuthn `navigator.credentials.create()` operation. Returns a promise that resolves upon successful submission of the error report.

  ```typescript Example theme={null}
  import MfaWebAuthnPlatformEnrollment from "@auth0/auth0-acul-js/mfa-webauthn-platform-enrollment";
  const sdk = new MfaWebAuthnPlatformEnrollment();

  await sdk.reportBrowserError( {
    error: 'message'
  });
  ```

  <ParamField type="OPTIONAL">
    Contains the error object (with `name` and `message` properties from the browser's WebAuthn API DOMException) and any other custom options.

    <Expandable title="options properties">
      <ParamField type="&#x22;messages: string&#x22; | &#x22;name: string&#x22;">
        The error object from the WebAuthn API (navigator.credentials.get()) to be reported.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method allows the user to choose to snooze the WebAuthn platform enrollment. Returns a promise that resolves upon successful submission of the snooze action.

  ```typescript Example theme={null}
  import MfaWebAuthnPlatformEnrollment from "@auth0/auth0-acul-js/mfa-webauthn-platform-enrollment";
  const sdk = new MfaWebAuthnPlatformEnrollment();

  await sdk.snoozeEnrollment();
  ```

  <ParamField type="OPTIONAL">
    Optional custom parameters to be sent with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method initiates the WebAuthn platform credential creation process using the public key options available on `this.screen.publicKey` and submits the resulting credential to the server. Returns a promise that resolves when the credential is successfully created and submitted.

  ```typescript Example theme={null}
  import MfaWebAuthnPlatformEnrollment from "@auth0/auth0-acul-js/mfa-webauthn-platform-enrollment";
  const sdk = new MfaWebAuthnPlatformEnrollment();

  try {
    await sdk.submitPasskeyCredential(); // No need to pass publicKey explicitly
    // On success, Auth0 handles redirection.
  } catch (error) {
    console.error('Passkey enrollment failed:', error);
    if (error.name && error.message) { // Check if it looks like a WebAuthn error
      await sdk.reportBrowserError({ error: { name: error.name, message: error.message } });
    }
  }
  ```

  <ParamField type="OPTIONAL">
    Optional custom parameters to be sent to the server along with the created credential.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaWebAuthnRoamingChallenge
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaWebAuthnRoamingChallenge



The MfaWebAuthnRoamingChallenge screen class provides methods associated with the `mfa-webauthn-roaming-challenge` screen.

<Frame>
  <img alt="MfaWebAuthnRoamingChallenge" />
</Frame>

## Constructors

Create an instance of MfaWebAuthnRoamingChallenge screen

```ts Example theme={null}
import MfaWebAuthnRoamingChallenge from "@auth0/auth0-acul-js/mfa-webauthn-roaming-challenge";

const mfaWebAuthnRoamingChallengeManager = new MfaWebAuthnRoamingChallenge();
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnMfaWebAuthnRoamingChallenge">ScreenMembersOnMfaWebAuthnRoamingChallenge</a></span>}>
  Contains details specific to the `mfa-webauthn-roaming-challenge` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method reports a specific WebAuthn API error to Auth0. This method should be used if `navigator.credentials.get()` fails in a way that
  `verify()` doesn't automatically handle, or if the developer wants to explicitly report an error before trying another action. It submits the error details with `action: "showError::{errorDetails}"`. Returns a promise that resolves when the error report is submitted.

  ```typescript Example theme={null}
  import MfaWebAuthnRoamingChallenge from "@auth0/auth0-acul-js/mfa-webauthn-roaming-challenge";

  const sdk = new MfaWebAuthnRoamingChallenge();

  // And webAuthnError is an error object from a failed navigator.credentials.get() call.
  try {
    await sdk.reportWebAuthnError({
      error: { name: webAuthnError.name, message: webAuthnError.message }
    });
  } catch (submitError) {
    console.error("Failed to report WebAuthn error:", submitError);
  }
  ```

  <ParamField type="OPTIONAL">
    Contains the error object (with `name` and `message` properties from the browser's WebAuthn API DOMException) and any other custom options.

    <Expandable title="options properties">
      <ParamField type="&#x22;messages: string&#x22; | &#x22;name: string&#x22;">
        The error message.
      </ParamField>

      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method allows the user to opt-out of the WebAuthn challenge and select a different MFA method. This action submits `action: "pick-authenticator"` to Auth0, which should navigate the user to an MFA factor selection screen. Returns a promise that resolves when the action is submitted.

  ```typescript Example theme={null}
  import MfaWebAuthnRoamingChallenge from "@auth0/auth0-acul-js/mfa-webauthn-roaming-challenge";

  const sdk = new MfaWebAuthnRoamingChallenge();

  try {
    await sdk.tryAnotherMethod();
    // On success, Auth0 handles redirection to MFA selection.
  } catch (error) {
    console.error("Failed to switch MFA method:", error);
  }
  ```

  <ParamField type="OPTIONAL">
    Optional custom parameters to be sent with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method initiates the WebAuthn challenge by calling `navigator.credentials.get()` with the options provided in `screen.data.publicKeyChallengeOptions`.
  If successful, it submits the resulting credential to Auth0 with `action: "default"`. If `navigator.credentials.get()` fails with a known WebAuthn API error, for example: `NotAllowedError`, this method will internally call `reportWebAuthnError` to inform Auth0. Returns a promise that resolves when the verification attempt is submitted.

  ```typescript Example theme={null}
  import MfaWebAuthnRoamingChallenge from "@auth0/auth0-acul-js/mfa-webauthn-roaming-challenge";

  const sdk = new MfaWebAuthnRoamingChallenge();

  try {
    await sdk.verify({ rememberDevice: true });
    // On success, Auth0 handles redirection.
  } catch (error) {
    console.error("Security key verification failed:", error);
    // Check sdk.transaction.errors for server-side validation messages if the page reloads.
  }
  ```

  <ParamField type="OPTIONAL">
    Optional parameters for the verification. This can include `rememberDevice` if `this.screen.showRememberDevice` is true, and any other custom key-value pairs to be sent in the form submission.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>

      <ParamField type="boolean">
        If true, attempts to remember the browser for future MFA challenges. Corresponds to the `rememberBrowser` form field. This is only applicable if `screen.showRememberDevice` is true.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# MfaWebAuthnRoamingEnrollment
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/MfaWebAuthnRoamingEnrollment



The MfaWebAuthnRoamingEnrollment screen class provides methods associated with the `mfa-webauthn-roaming-enrollment` screen. This screen is displayed when a user needs to enroll a WebAuthn roaming authenticator, for example: a security key.

<Frame>
  <img alt="MfaWebAuthnRoamingEnrollment" />
</Frame>

## Constructors

Create an instance of MfaWebAuthnRoamingEnrollment screen

```ts Example theme={null}
import MfaWebAuthnRoamingEnrollment from '@auth0/auth0-acul-js/mfa-webauthn-roaming-enrollment';

const webauthnEnrollment = new MfaWebAuthnRoamingEnrollment();
// Assuming you have obtained the WebAuthn credential response (e.g., from navigator.credentials.create)
const credentialResponse = { /* ... serialized credential ... *&#x2F; };
await webauthnEnrollment.enroll({ response: JSON.stringify(credentialResponse) });
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnMfaWebAuthnRoamingEnrollment">ScreenMembersOnMfaWebAuthnRoamingEnrollment</a></span>}>
  Contains details specific to the `mfa-webauthn-roaming-enrollment` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Provides transaction-specific data, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)">
  This method initiates the WebAuthn credential creation and submits the result to the server. This corresponds to the user interacting with the FIDO Security Keys prompt.

  ```typescript Example theme={null}
  import MfaWebAuthnRoamingEnrollment from '@auth0/auth0-acul-js/mfa-webauthn-roaming-enrollment';

  const webauthnEnrollment = new MfaWebAuthnRoamingEnrollment();
  // Assuming you have obtained the WebAuthn credential response (e.g., from navigator.credentials.create)
  const credentialResponse = { /* ... serialized credential ... *&#x2F; };
  await webauthnEnrollment.enroll({ response: JSON.stringify(credentialResponse) });
  ```

  <ParamField type="OPTIONAL">
    Optional custom parameters to be sent with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist.
</ParamField>

<ParamField type="(options ?)">
  This method submits details about a WebAuthn browser error to the server. This is used when the browser's WebAuthn API encounters an error.

  ```typescript Example theme={null}
  import MfaWebAuthnRoamingEnrollment from '@auth0/auth0-acul-js/mfa-webauthn-roaming-enrollment';

  const webauthnEnrollment = new MfaWebAuthnRoamingEnrollment();
  await webauthnEnrollment.showError({
    error: {
      name: 'NotAllowedError',
      message: 'The operation either timed out or was not allowed.',
    },
  });
  ```

  <ParamField type="OPTIONAL">
    Contains the error object (with `name` and `message` properties from the browser's WebAuthn API DOMException) and any other custom options.

    <Expandable title="options properties">
      <ParamField type="&#x22;messages: string&#x22; | &#x22;name: string&#x22;">
        The error message.
      </ParamField>

      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>

<ParamField type="(options ?)">
  This method allows the user to try another MFA method.

  ```typescript Example theme={null}
  import MfaWebAuthnRoamingEnrollment from '@auth0/auth0-acul-js/mfa-webauthn-roaming-enrollment';

  const webauthnEnrollment = new MfaWebAuthnRoamingEnrollment();
  await webauthnEnrollment.tryAnotherMethod();
  ```

  <ParamField type="OPTIONAL">
    Optional custom parameters to be sent with the request.

    <Expandable title="options properties">
      <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
        Additional data collected from the user.
      </ParamField>
    </Expandable>
  </ParamField>
</ParamField>


# OrganizationPicker
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/OrganizationPicker



<Frame>
  <img alt="" />
</Frame>

Class implementing the organization-picker screen functionality.
This screen allows users to select an organization from a list of available organizations.

```ts Example theme={null}
import OrganizationPicker from '@auth0/auth0-acul-js/organization-picker';

const organizationPicker = new OrganizationPicker();
organizationPicker.selectOrganization({
  organization: 'org_XXXXXXXXXXXXXXX'
});
```

## Constructors

<ParamField type="Constructor">
  Creates an instance of OrganizationPicker screen manager.
</ParamField>

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembers">ScreenMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string">
  Screen identifier for validation and telemetry
</ParamField>

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>

<ParamField type="Promise<void>">
  Submits the selected organization ID.

  ```typescript Example theme={null}
  import OrganizationPicker from '@auth0/auth0-acul-js/organization-picker';

  const organizationPicker = new OrganizationPicker();
  organizationPicker.selectOrganization({
    organization: 'org_XXXXXXXXXXXXXXX'
  });
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/SelectOrganizationOptions">SelectOrganizationOptions</a></span>}>
      **Properties**

      <ParamField type="string" />

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Promise<void>">
  Submits the action to skip the organization selection.

  ```typescript Example theme={null}
  import OrganizationPicker from '@auth0/auth0-acul-js/organization-picker';

  const organizationPicker = new OrganizationPicker();
  organizationPicker.skipOrganizationSelection();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>}>
      Optional custom options to include with the request.
    </ParamField>
  </Expandable>
</ParamField>


# OrganizationSelection
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/OrganizationSelection



<Frame>
  <img alt="" />
</Frame>

Class implementing the organization-selection screen functionality.
This screen allows users to select an organization to continue with.

```ts Example theme={null}
import OrganizationSelection from '@auth0/auth0-acul-js/organization-selection';

const organizationSelection = new OrganizationSelection();
await organizationSelection.continueWithOrganizationName({
  organizationName: 'testOrganizationName',
});
```

## Constructors

<ParamField type="Constructor">
  Creates an instance of OrganizationSelection screen manager.
</ParamField>

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnOrganizationSelection">ScreenMembersOnOrganizationSelection</a></span>}>
  The screen properties.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string">
  Screen identifier for validation and telemetry
</ParamField>

## Methods

<ParamField type="Promise<void>">
  Continues with the selected organization name.

  ```typescript Example theme={null}
  import OrganizationSelection from '@auth0/auth0-acul-js/organization-selection';

  const organizationSelection = new OrganizationSelection();
  await organizationSelection.continueWithOrganizationName({
    organizationName: 'testOrganizationName',
  });
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ContinueWithOrganizationNameOptions">ContinueWithOrganizationNameOptions</a></span>}>
      **Properties**

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>


# PasskeyEnrollment
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/PasskeyEnrollment



<Frame>
  <img alt="" />
</Frame>

```ts Example theme={null}
import PasskeyEnrollment from '@auth0/auth0-acul-js/passkey-enrollment';
const passkeyEnrollment = new PasskeyEnrollment();
passkeyEnrollment.continuePasskeyEnrollment();
```

## Constructors

<ParamField type="Constructor" />

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnPasskeyEnrollment">ScreenMembersOnPasskeyEnrollment</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string" />

## Methods

<ParamField type="Promise<void>">
  ```ts Example theme={null}
  import PasskeyEnrollment from '@auth0/auth0-acul-js/passkey-enrollment';

  const passkeyEnrollment = new PasskeyEnrollment();
  passkeyEnrollment.abortPasskeyEnrollment();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type="Promise<void>">
  ```ts Example theme={null}
  import PasskeyEnrollment from '@auth0/auth0-acul-js/passkey-enrollment';

  const passkeyEnrollment = new PasskeyEnrollment();
  passkeyEnrollment.continuePasskeyEnrollment();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>


# PasskeyEnrollmentLocal
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/PasskeyEnrollmentLocal



<Frame>
  <img alt="Passkey Enrollment Local" />
</Frame>

```ts Example theme={null}
import PasskeyEnrollmentLocal from '@auth0/auth0-acul-js/passkey-enrollment-local';
const passkeyEnrollment = new PasskeyEnrollmentLocal();
passkeyEnrollment.continuePasskeyEnrollment();
```

## Constructors

<ParamField type="Constructor" />

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnPasskeyEnrollmentLocal">ScreenMembersOnPasskeyEnrollmentLocal</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string" />

## Methods

<ParamField type="Promise<void>">
  ```ts Example theme={null}
  import PasskeyEnrollmentLocal from '@auth0/auth0-acul-js/passkey-enrollment-local';

  const passkeyEnrollment = new PasskeyEnrollmentLocal();
  passkeyEnrollment.abortPasskeyEnrollment({
      doNotShowAgain: <boolean>
  });
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/AbortEnrollmentOptions">AbortEnrollmentOptions</a></span>}>
      **Properties**

      <ParamField type="boolean" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Promise<void>">
  ```ts Example theme={null}
  import PasskeyEnrollmentLocal from '@auth0/auth0-acul-js/passkey-enrollment-local';

  const passkeyEnrollment = new PasskeyEnrollmentLocal();
  passkeyEnrollment.continuePasskeyEnrollment();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>


# PhoneIdentifierChallenge
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/PhoneIdentifierChallenge



<Frame>
  <img alt="undefined" />
</Frame>

```ts Example theme={null}
import PhoneIdentifierChallenge from '@auth0/auth0-acul-js/phone-identifier-challenge';
const phoneIdentifierChallenge = new PhoneIdentifierChallenge();
phoneIdentifierChallenge.submitPhoneChallenge({
    code: "<string>"
});
```

## Constructors

<ParamField type="Constructor" />

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnPhoneIdentifierChallenge">ScreenMembersOnPhoneIdentifierChallenge</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string" />

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>

<ParamField type="Promise<void>">
  ```ts Example theme={null}
  import PhoneIdentifierChallenge from '@auth0/auth0-acul-js/phone-identifier-challenge';

  const phoneIdentifierChallenge = new PhoneIdentifierChallenge();
  phoneIdentifierChallenge.resendCode();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ResendControl">ResendControl</a></span>}>
  **`Utility Feature`**

  Gets resend functionality with timeout management for this screen

  ResendControl object with startResend method

  ```ts Example theme={null}
  import PhoneIdentifierChallenge from '@auth0/auth0-acul-js/phone-identifier-challenge';
    const handleStatusChange = (remainingSeconds, isDisabled) => {
      setDisabled(isDisabled);
      setRemaining(remainingSeconds);
    };

    const handleTimeout = () => {
      console.log('Timeout completed, resend is now available');
    };

    const { startResend } = phoneChallenge.resendManager({
      timeoutSeconds: 30,
      onStatusChange: handleStatusChange,
      onTimeout: handleTimeout
    });
    
    // Call startResend when user clicks resend button
    await startResend();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/StartResendOptions">StartResendOptions</a></span>}>
      Configuration options for resend functionality

      **Properties**

      <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/type-aliases/OnStatusChangeCallback">OnStatusChangeCallback</a></span>} />

      <ParamField type="void" />

      <ParamField type="number" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Promise<void>">
  ```ts Example theme={null}
  import PhoneIdentifierChallenge from '@auth0/auth0-acul-js/phone-identifier-challenge';

  const phoneIdentifierChallenge = new PhoneIdentifierChallenge();
  phoneIdentifierChallenge.returnToPrevious();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type="Promise<void>">
  ```ts Example theme={null}
  import PhoneIdentifierChallenge from '@auth0/auth0-acul-js/phone-identifier-challenge';

  const phoneIdentifierChallenge = new PhoneIdentifierChallenge();
  phoneIdentifierChallenge.submitPhoneChallenge({
      code: "<string>"
  });
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PhoneChallengeOptions">PhoneChallengeOptions</a></span>}>
      **Properties**

      <ParamField type="string" />

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Promise<void>">
  ```ts Example theme={null}
  import PhoneIdentifierChallenge from '@auth0/auth0-acul-js/phone-identifier-challenge';

  const phoneIdentifierChallenge = new PhoneIdentifierChallenge();
  phoneIdentifierChallenge.switchToText();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type="Promise<void>">
  ```ts Example theme={null}
  import PhoneIdentifierChallenge from '@auth0/auth0-acul-js/phone-identifier-challenge';

  const phoneIdentifierChallenge = new PhoneIdentifierChallenge();
  phoneIdentifierChallenge.switchToVoice();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>


# PhoneIdentifierEnrollment
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/PhoneIdentifierEnrollment



<Frame>
  <img alt="PhoneIdentifierEnrollment" />
</Frame>

```ts Example theme={null}
import PhoneIdentifierEnrollment from '@auth0/auth0-acul-js/phone-identifier-enrollment';
const phoneIdentifierEnrollment = new PhoneIdentifierEnrollment();
phoneIdentifierChallenge.continuePhoneEnrollment({
    type: "<text' | 'voice>"
});
```

## Constructors

<ParamField type="Constructor" />

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnPhoneIdentifierEnrollment">ScreenMembersOnPhoneIdentifierEnrollment</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string" />

## Methods

<ParamField type="Promise<void>">
  ```ts Example theme={null}
  import PhoneIdentifierEnrollment from '@auth0/auth0-acul-js/phone-identifier-enrollment';

  const phoneIdentifierEnrollment = new PhoneIdentifierEnrollment();
  phoneIdentifierChallenge.continuePhoneEnrollment({
      type: "<text' | 'voice>"
  });
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PhoneEnrollmentOptions">PhoneEnrollmentOptions</a></span>}>
      **Properties**

      <ParamField type="&#x22;voice&#x22;" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>

<ParamField type="Promise<void>">
  ```ts Example theme={null}
  import PhoneIdentifierEnrollment from '@auth0/auth0-acul-js/phone-identifier-enrollment';

  const phoneIdentifierEnrollment = new PhoneIdentifierEnrollment();
  phoneIdentifierChallenge.returnToPrevious();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>


# RedeemTicket
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/RedeemTicket



<Frame>
  <img alt="" />
</Frame>

Implements the redeem-ticket screen functionality.

```ts Example theme={null}
import RedeemTicket from '@auth0/auth0-acul-js/redeem-ticket';

const redeemTicket = new RedeemTicket();
await redeemTicket.continue();
```

## Constructors

<ParamField type="Constructor">
  Initializes a new instance of the RedeemTicket class.
</ParamField>

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembers">ScreenMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string" />

## Methods

<ParamField type="Promise<void>">
  Performs the default action on the redeem-ticket screen, usually continuing the flow.

  A promise that resolves when the action is complete.

  #### Throws

  If the operation fails.

  ```ts Example theme={null}
  import RedeemTicket from '@auth0/auth0-acul-js/redeem-ticket';

  const redeemTicket = new RedeemTicket();
  await redeemTicket.continue();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>}>
      Optional custom options to include with the request.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>


# ResetPassword
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/ResetPassword



<Frame>
  <img alt="ACUL Reset password" />
</Frame>

```ts Example theme={null}
import ResetPassword from '@auth0/auth0-acul-js/reset-password';
const resetPassword = new ResetPassword();
resetPassword.resetPassword({
   'password-reset': 'Test@123!',
   're-enter-password': 'Test@123!',
});
```

## Constructors

<ParamField type="Constructor" />

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnResetPassword">ScreenMembersOnResetPassword</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembersOnResetPassword">TransactionMembersOnResetPassword</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string" />

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>

<ParamField type="Promise<void>">
  ```ts Example theme={null}
  import ResetPassword from '@auth0/auth0-acul-js/reset-password';

  const resetPassword = new ResetPassword();
  resetPassword.resetPassword({
     'password-reset': 'Test@123!',
     're-enter-password': 'Test@123!',
  });
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ResetPasswordOptions">ResetPasswordOptions</a></span>}>
      **Properties**

      <ParamField type="string" />

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PasswordValidationResult">PasswordValidationResult</a></span>}>
  **`Utility Feature`**

  An object of type [PasswordValidationResult](/docs/libraries/acul/js-sdk/Screens/interfaces/PasswordValidationResult) indicating whether the password is valid and why.

  <Expandable title="Parameters">
    <ParamField type="string">
      `string`
    </ParamField>
  </Expandable>
</ParamField>


# ResetPasswordEmail
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/ResetPasswordEmail



<Frame>
  <img alt="ACUL Reset_password_email" />
</Frame>

```ts Example theme={null}
import ResetPasswordEmail from '@auth0/auth0-acul-js/reset-password-email';
const resetPasswordEmail = new ResetPasswordEmail();
resetPasswordEmail.resendEmail();
```

## Constructors

<ParamField type="Constructor" />

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnResetPasswordEmail">ScreenMembersOnResetPasswordEmail</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string" />

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>

<ParamField type="Promise<void>">
  ```ts Example theme={null}
  import ResetPasswordEmail from '@auth0/auth0-acul-js/reset-password-email';

  const resetPasswordEmail = new ResetPasswordEmail();
  resetPasswordEmail.resendEmail();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>


# ResetPasswordError
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/ResetPasswordError



<Frame>
  <img alt="ACUL reset password error " />
</Frame>

```ts Example theme={null}
import ResetPasswordError from '@auth0/auth0-acul-js/reset-password-error';

const resetPasswordErrorManager = new ResetPasswordError();
```

## Constructors

<ParamField type="Constructor" />

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnResetPasswordError">ScreenMembersOnResetPasswordError</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string" />

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>


# ResetPasswordMfaEmailChallenge
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/ResetPasswordMfaEmailChallenge



<Frame>
  <img alt="" />
</Frame>

Class implementing the reset-password-mfa-email-challenge screen functionality

```ts Example theme={null}
import ResetPasswordMfaEmailChallenge from '@auth0/auth0-acul-js/reset-password-mfa-email-challenge';

const resetPasswordMfaEmailChallenge = new ResetPasswordMfaEmailChallenge();
await resetPasswordMfaEmailChallenge.continue({
  code: '123456',
});
```

## Constructors

<ParamField type="Constructor">
  Creates an instance of ResetPasswordMfaEmailChallenge screen manager
</ParamField>

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnResetPasswordMfaEmailChallenge">ScreenMembersOnResetPasswordMfaEmailChallenge</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string" />

## Methods

<ParamField type="Promise<void>">
  Continues with the email challenge using the provided code.

  ```typescript Example theme={null}
  import ResetPasswordMfaEmailChallenge from '@auth0/auth0-acul-js/reset-password-mfa-email-challenge';

  const resetPasswordMfaEmailChallenge = new ResetPasswordMfaEmailChallenge();
  await resetPasswordMfaEmailChallenge.continue({
    code: '123456',
  });
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ContinueOptions">ContinueOptions</a></span>}>
      **Properties**

      <ParamField type="string" />

      <ParamField type="boolean" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>

<ParamField type="Promise<void>">
  Resends the email code.

  ```typescript Example theme={null}
  import ResetPasswordMfaEmailChallenge from '@auth0/auth0-acul-js/reset-password-mfa-email-challenge';

  const resetPasswordMfaEmailChallenge = new ResetPasswordMfaEmailChallenge();
  await resetPasswordMfaEmailChallenge.resendCode();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ResendCodeOptions">ResendCodeOptions</a></span>}>
      Optional custom options to include with the request.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ResendControl">ResendControl</a></span>}>
  **`Utility Feature`**

  Gets resend functionality with timeout management for this screen

  ResendControl object with startResend method

  ```typescript Example theme={null}
  import ResetPasswordMfaEmailChallenge from '@auth0/auth0-acul-js/reset-password-mfa-email-challenge';

  const resetPasswordMfaEmailChallenge = new ResetPasswordMfaEmailChallenge();
  const { startResend } = resetPasswordMfaEmailChallenge.resendManager({
    timeoutSeconds: 15,
    onStatusChange: (remainingSeconds, isDisabled) => {
      console.log(`Resend available in ${remainingSeconds}s, disabled: ${isDisabled}`);
    },
    onTimeout: () => {
      console.log('Resend is now available');
    }
  });

  // Call startResend when user clicks resend button
  startResend();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/StartResendOptions">StartResendOptions</a></span>}>
      Configuration options for resend functionality

      **Properties**

      <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/type-aliases/OnStatusChangeCallback">OnStatusChangeCallback</a></span>} />

      <ParamField type="void" />

      <ParamField type="number" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Promise<void>">
  Allows the user to try another MFA method.

  ```typescript Example theme={null}
  import ResetPasswordMfaEmailChallenge from '@auth0/auth0-acul-js/reset-password-mfa-email-challenge';

  const resetPasswordMfaEmailChallenge = new ResetPasswordMfaEmailChallenge();
  await resetPasswordMfaEmailChallenge.tryAnotherMethod();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TryAnotherMethodOptions">TryAnotherMethodOptions</a></span>}>
      Optional custom options to include with the request.
    </ParamField>
  </Expandable>
</ParamField>


# ResetPasswordMfaOtpChallenge
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/ResetPasswordMfaOtpChallenge



<Frame>
  <img alt="" />
</Frame>

Class implementing the reset-password-mfa-otp-challenge screen functionality

```ts Example theme={null}
import ResetPasswordMfaOtpChallenge from '@auth0/auth0-acul-js/reset-password-mfa-otp-challenge';

const resetPasswordMfaOtpChallenge = new ResetPasswordMfaOtpChallenge();
await resetPasswordMfaOtpChallenge.continue({
  code: '123456',
});
```

## Constructors

<ParamField type="Constructor">
  Creates an instance of ResetPasswordMfaOtpChallenge screen manager
</ParamField>

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembers">ScreenMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string">
  Screen identifier for validation and telemetry
</ParamField>

## Methods

<ParamField type="Promise<void>">
  Continues with the OTP challenge using the provided code.

  ```typescript Example theme={null}
  import ResetPasswordMfaOtpChallenge from '@auth0/auth0-acul-js/reset-password-mfa-otp-challenge';

  const resetPasswordMfaOtpChallenge = new ResetPasswordMfaOtpChallenge();
  await resetPasswordMfaOtpChallenge.continue({
    code: '123456',
  });
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ResetPasswordMfaOtpChallengeContinueOptions">ResetPasswordMfaOtpChallengeContinueOptions</a></span>}>
      **Properties**

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>

<ParamField type="Promise<void>">
  Allows the user to try another MFA method.

  ```typescript Example theme={null}
  import ResetPasswordMfaOtpChallenge from '@auth0/auth0-acul-js/reset-password-mfa-otp-challenge';

  const resetPasswordMfaOtpChallenge = new ResetPasswordMfaOtpChallenge();
  await resetPasswordMfaOtpChallenge.tryAnotherMethod();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ResetPasswordMfaOtpChallengeTryAnotherMethodOptions">ResetPasswordMfaOtpChallengeTryAnotherMethodOptions</a></span>}>
      Optional custom options to include with the request.
    </ParamField>
  </Expandable>
</ParamField>


# ResetPasswordMfaPhoneChallenge
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/ResetPasswordMfaPhoneChallenge



<Frame>
  <img alt="" />
</Frame>

ResetPasswordMfaPhoneChallenge

```ts Example theme={null}
const screen = new ResetPasswordMfaPhoneChallenge();
try {
  await screen.continue({ type: 'sms' });
  // Redirects to code entry screen on success
} catch (error) {
  console.error("Failed to send SMS code:", error);
}
```

## Constructors

<ParamField type="Constructor">
  Initializes a new instance of the `ResetPasswordMfaPhoneChallenge` class.
  It retrieves the screen context and sets up the screen-specific properties.

  #### Throws

  If the Universal Login Context is not available or if the screen name doesn't match.
</ParamField>

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Access to client-specific information (e.g., client ID, name).
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Access to organization-specific information, if applicable.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Access to prompt details (e.g., prompt name).
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnResetPasswordMfaPhoneChallenge">ScreenMembersOnResetPasswordMfaPhoneChallenge</a></span>}>
  Holds the specific screen data and properties, processed by ScreenOverride.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Access to the current transaction details (e.g., state, errors).
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string">
  The unique identifier for this screen, used internally and for telemetry.
</ParamField>

## Methods

<ParamField type="Promise<void>">
  Sends the verification code to the user's phone via the selected method (SMS or Voice).
  Corresponds to the 'Continue' action in the OpenAPI definition (action: 'default').

  A promise resolving upon successful submission to the server.

  #### Throws

  If the form submission fails.

  ```typescript Example theme={null}
  const screen = new ResetPasswordMfaPhoneChallenge();
  try {
    await screen.continue({ type: 'sms' });
    // Redirects to code entry screen on success
  } catch (error) {
    console.error("Failed to send SMS code:", error);
  }
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ResetPasswordMfaPhoneChallengeContinueOptions">ResetPasswordMfaPhoneChallengeContinueOptions</a></span>}>
      Contains the delivery type (`sms` or `voice`) and any optional custom data.

      **Properties**

      <ParamField type="&#x22;sms&#x22; | &#x22;voice&#x22;">
        The delivery method selected by the user for receiving the verification code.

        * `sms`: Send the code via text message.
        * `voice`: Send the code via a voice call.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>

<ParamField type="Promise<void>">
  Initiates the process for the user to select a different MFA authenticator.
  Corresponds to the 'Try Another Method' action in the OpenAPI definition (action: 'pick-authenticator').

  A promise resolving upon successful submission to the server.

  #### Throws

  If the form submission fails.

  ```typescript Example theme={null}
  const screen = new ResetPasswordMfaPhoneChallenge();
  try {
    // Assuming the current screen was for SMS
    await screen.tryAnotherMethod({ type: 'sms' });
    // Redirects to authenticator selection screen on success
  } catch (error) {
    console.error("Failed to switch MFA method:", error);
  }
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ResetPasswordMfaPhoneChallengeTryAnotherMethodOptions">ResetPasswordMfaPhoneChallengeTryAnotherMethodOptions</a></span>}>
      Contains the *current* challenge type (`sms` or `voice`) as required by the API, and any optional custom data.

      **Properties**

      <ParamField type="&#x22;sms&#x22; | &#x22;voice&#x22;">
        The delivery method that was initially presented or selected on the current screen.
        This is required by the API endpoint to correctly process the 'pick-authenticator' action.

        * `sms`: Indicates the current screen was for SMS challenge.
        * `voice`: Indicates the current screen was for Voice challenge.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>


# ResetPasswordMfaPushChallengePush
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/ResetPasswordMfaPushChallengePush



<Frame>
  <img alt="" />
</Frame>

Class representing the reset-password-mfa-push-challenge-push screen functionality
This screen is shown when a push notification has been sent to the user's device during password reset

```ts Example theme={null}
import ResetPasswordMfaPushChallengePush from '@auth0/auth0-acul-js/reset-password-mfa-push-challenge-push';

const resetPasswordMfaPushChallengePush = new ResetPasswordMfaPushChallengePush();
await resetPasswordMfaPushChallengePush.continue();
```

## Constructors

<ParamField type="Constructor" />

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnResetPasswordMfaPushChallengePush">ScreenMembersOnResetPasswordMfaPushChallengePush</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string" />

## Methods

<ParamField type="Promise<void>">
  Continues with the push notification challenge

  ```typescript Example theme={null}
  import ResetPasswordMfaPushChallengePush from '@auth0/auth0-acul-js/reset-password-mfa-push-challenge-push';

  const resetPasswordMfaPushChallengePush = new ResetPasswordMfaPushChallengePush();
  await resetPasswordMfaPushChallengePush.continue();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>}>
      Optional custom options to include with the request
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Promise<void>">
  Switches to entering the verification code manually

  ```typescript Example theme={null}
  import ResetPasswordMfaPushChallengePush from '@auth0/auth0-acul-js/reset-password-mfa-push-challenge-push';

  const resetPasswordMfaPushChallengePush = new ResetPasswordMfaPushChallengePush();
  await resetPasswordMfaPushChallengePush.enterCodeManually();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>}>
      Optional custom options to include with the request
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/MfaPushPollingControl">MfaPushPollingControl</a></span>}>
  **`Utility Feature`**

  Starts and manages polling for an MFA push challenge.

  Creates a polling session that repeatedly checks the MFA push challenge endpoint
  at the specified interval until the challenge is approved or an error occurs.
  When the approval condition is met, the provided
  [onCompleted](/docs/libraries/acul/js-sdk/Screens/type-aliases/MfaPollingOptions#oncompleted) callback is invoked and
  polling stops automatically.

  Use the returned [MfaPushPollingControl](/docs/libraries/acul/js-sdk/Screens/interfaces/MfaPushPollingControl) to start, stop, or check the
  status of the polling process at any time.

  A [MfaPushPollingControl](/docs/libraries/acul/js-sdk/Screens/interfaces/MfaPushPollingControl) instance exposing:

  * `startPolling()` — Starts or resumes polling.
  * `stopPolling()` — Cancels polling immediately.
  * `isRunning()` — Indicates whether polling is currently active.

  ```ts Example theme={null}
  // Start polling every 5 seconds until the push challenge is approved
  const control = mfaPushChallengePush.pollingManager({
    intervalMs: 5000,
    onCompleted: () => mfaPushChallengePush.continue(),
    onError: (error) => console.error('Polling error:', error),
  });

  // Later, cancel polling if needed
  control.stopPolling();
  ```

  #### Remarks

  * HTTP 429 (rate limit) responses are handled internally: polling automatically
    waits until the rate limit resets before retrying.
  * Safe to call `startPolling()` multiple times; it has no effect if already running.

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/type-aliases/MfaPollingOptions">MfaPollingOptions</a></span>}>
      **Properties**

      <ParamField type="object" />

      <ParamField type="number" />

      <ParamField type="() => void" />

      <ParamField type="(error) => void" />

      <ParamField type="string" />

      <ParamField type="string" />

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Promise<void>">
  Re-sends the push notification

  ```typescript Example theme={null}
  import ResetPasswordMfaPushChallengePush from '@auth0/auth0-acul-js/reset-password-mfa-push-challenge-push';

  const resetPasswordMfaPushChallengePush = new ResetPasswordMfaPushChallengePush();
  await resetPasswordMfaPushChallengePush.resendPushNotification();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>}>
      Optional custom options to include with the request
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Promise<void>">
  Allows trying another authentication method

  ```typescript Example theme={null}
  import ResetPasswordMfaPushChallengePush from '@auth0/auth0-acul-js/reset-password-mfa-push-challenge-push';

  const resetPasswordMfaPushChallengePush = new ResetPasswordMfaPushChallengePush();
  await resetPasswordMfaPushChallengePush.tryAnotherMethod();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>}>
      Optional custom options to include with the request
    </ParamField>
  </Expandable>
</ParamField>


# ResetPasswordMfaRecoveryCodeChallenge
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/ResetPasswordMfaRecoveryCodeChallenge



<Frame>
  <img alt="" />
</Frame>

Class implementing the Reset Password MFA Recovery Code Challenge screen functionality.

```ts Example theme={null}
import ResetPasswordMfaRecoveryCodeChallenge from '@auth0/auth0-acul-js/reset-password-mfa-recovery-code-challenge';
const resetPasswordMfaManager = new ResetPasswordMfaRecoveryCodeChallenge();
const continueWithRecoveryCode = async () => {
 try {
   await resetPasswordMfaManager.continue('RECOVERY_CODE');
    console.log('Recovery code submitted successfully.');
 } catch (error) {
   console.error('Error submitting recovery code:', error);
 }
};
```

## Constructors

<ParamField type="Constructor">
  Creates an instance of the ResetPasswordMfaRecoveryCodeChallenge screen.
</ParamField>

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembers">ScreenMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string" />

## Methods

<ParamField type="Promise<void>">
  Continues with the provided recovery code.

  ```typescript Example theme={null}
  import ResetPasswordMfaRecoveryCodeChallenge from '@auth0/auth0-acul-js/reset-password-mfa-recovery-code-challenge';
  const resetPasswordMfaManager = new ResetPasswordMfaRecoveryCodeChallenge();
  const continueWithRecoveryCode = async () => {
   try {
     await resetPasswordMfaManager.continue('RECOVERY_CODE');
      console.log('Recovery code submitted successfully.');
   } catch (error) {
     console.error('Error submitting recovery code:', error);
   }
  };
  ```

  <Expandable title="Parameters">
    <ParamField type="string">
      `string`

      The recovery code entered by the user.
    </ParamField>

    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>}>
      Optional payload.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>

<ParamField type="Promise<void>">
  Navigates to the screen where the user can pick another MFA method.

  ```typescript Example theme={null}
  import ResetPasswordMfaRecoveryCodeChallenge from '@auth0/auth0-acul-js/reset-password-mfa-recovery-code-challenge';
  const resetPasswordMfaRecoveryCodeChallengeManager = new ResetPasswordMfaRecoveryCodeChallenge();
  const handleTryAnotherMethod = async () => {
   try {
     await resetPasswordMfaRecoveryCodeChallengeManager.tryAnotherMethod();
   } catch (error) {
     console.error('Failed to try another method:', error);
   }
  };
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>}>
      Optional payload.
    </ParamField>
  </Expandable>
</ParamField>


# ResetPasswordMfaSmsChallenge
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/ResetPasswordMfaSmsChallenge



<Frame>
  <img alt="" />
</Frame>

This class provides methods to handle the reset-password-mfa-sms-challenge screen.

```ts Example theme={null}
import ResetPasswordMfaSmsChallenge from '@auth0/auth0-acul-js/reset-password-mfa-sms-challenge';

const resetPasswordMfaSmsChallenge = new ResetPasswordMfaSmsChallenge();
await resetPasswordMfaSmsChallenge.continueMfaSmsChallenge({
  code: '123456',
});
```

## Constructors

<ParamField type="Constructor" />

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnResetPasswordMfaSmsChallenge">ScreenMembersOnResetPasswordMfaSmsChallenge</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string" />

## Methods

<ParamField type="Promise<void>">
  Submits the MFA SMS challenge with the provided code.

  ```typescript Example theme={null}
  import ResetPasswordMfaSmsChallenge from '@auth0/auth0-acul-js/reset-password-mfa-sms-challenge';

  const resetPasswordMfaSmsChallenge = new ResetPasswordMfaSmsChallenge();
  await resetPasswordMfaSmsChallenge.continueMfaSmsChallenge({
    code: '123456',
  });
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ResetPasswordMfaSmsChallengeOptions">ResetPasswordMfaSmsChallengeOptions</a></span>}>
      **Properties**

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Promise<void>">
  Submits the action to switch to voice call verification.

  ```typescript Example theme={null}
  import ResetPasswordMfaSmsChallenge from '@auth0/auth0-acul-js/reset-password-mfa-sms-challenge';

  const resetPasswordMfaSmsChallenge = new ResetPasswordMfaSmsChallenge();
  await resetPasswordMfaSmsChallenge.getACall();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>}>
      Optional payload.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>

<ParamField type="Promise<void>">
  Submits the action to resend the SMS code.

  ```typescript Example theme={null}
  import ResetPasswordMfaSmsChallenge from '@auth0/auth0-acul-js/reset-password-mfa-sms-challenge';

  const resetPasswordMfaSmsChallenge = new ResetPasswordMfaSmsChallenge();
  await resetPasswordMfaSmsChallenge.resendCode();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>}>
      Optional payload.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ResendControl">ResendControl</a></span>}>
  **`Utility Feature`**

  Gets resend functionality with timeout management for this screen

  ResendControl object with startResend method

  ```typescript Example theme={null}
  import ResetPasswordMfaSmsChallenge from '@auth0/auth0-acul-js/reset-password-mfa-sms-challenge';

  const resetPasswordMfaSmsChallenge = new ResetPasswordMfaSmsChallenge();
  const { startResend } = resetPasswordMfaSmsChallenge.resendManager({
    timeoutSeconds: 15,
    onStatusChange: (remainingSeconds, isDisabled) => {
      console.log(`Resend available in ${remainingSeconds}s, disabled: ${isDisabled}`);
    },
    onTimeout: () => {
      console.log('Resend is now available');
    }
  });

  // Call startResend when user clicks resend button
  startResend();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/StartResendOptions">StartResendOptions</a></span>}>
      Configuration options for resend functionality

      **Properties**

      <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/type-aliases/OnStatusChangeCallback">OnStatusChangeCallback</a></span>} />

      <ParamField type="void" />

      <ParamField type="number" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Promise<void>">
  Submits the action to try another MFA method.

  ```typescript Example theme={null}
  import ResetPasswordMfaSmsChallenge from '@auth0/auth0-acul-js/reset-password-mfa-sms-challenge';

  const resetPasswordMfaSmsChallenge = new ResetPasswordMfaSmsChallenge();
  await resetPasswordMfaSmsChallenge.tryAnotherMethod();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>}>
      Optional payload.
    </ParamField>
  </Expandable>
</ParamField>


# ResetPasswordMfaVoiceChallenge
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/ResetPasswordMfaVoiceChallenge



<Frame>
  <img alt="" />
</Frame>

Class implementing the reset-password-mfa-voice-challenge screen functionality.

```ts Example theme={null}
const reset = new ResetPasswordMfaVoiceChallenge();
await reset.continue({ code: '123456' });
```

## Constructors

<ParamField type="Constructor">
  Creates an instance of ResetPasswordMfaVoiceChallenge screen manager.
</ParamField>

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnResetPasswordMfaVoiceChallenge">ScreenMembersOnResetPasswordMfaVoiceChallenge</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string" />

## Methods

<ParamField type="Promise<void>">
  Continues with the voice challenge using the provided code.

  A promise that resolves when the challenge is submitted.

  ```ts Example theme={null}
  const reset = new ResetPasswordMfaVoiceChallenge();
  await reset.continue({ code: '123456' });
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ResetPasswordMfaVoiceChallengeContinueOptions">ResetPasswordMfaVoiceChallengeContinueOptions</a></span>}>
      **Properties**

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>

<ParamField type="Promise<void>">
  Resends the code via voice call.

  A promise that resolves when the code is resent.

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>}>
      Optional custom options to include with the request.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ResendControl">ResendControl</a></span>}>
  **`Utility Feature`**

  Gets resend functionality with timeout management for this screen

  ResendControl object with startResend method

  ```typescript Example theme={null}
  import ResetPasswordMfaVoiceChallenge from '@auth0/auth0-acul-js/reset-password-mfa-voice-challenge';

  const resetPasswordMfaVoiceChallenge = new ResetPasswordMfaVoiceChallenge();
  const { startResend } = resetPasswordMfaVoiceChallenge.resendManager({
    timeoutSeconds: 15,
    onStatusChange: (remainingSeconds, isDisabled) => {
      console.log(`Resend available in ${remainingSeconds}s, disabled: ${isDisabled}`);
    },
    onTimeout: () => {
      console.log('Resend is now available');
    }
  });

  // Call startResend when user clicks resend button
  startResend();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/StartResendOptions">StartResendOptions</a></span>}>
      Configuration options for resend functionality

      **Properties**

      <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/type-aliases/OnStatusChangeCallback">OnStatusChangeCallback</a></span>} />

      <ParamField type="void" />

      <ParamField type="number" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Promise<void>">
  Switches to SMS verification.

  A promise that resolves when the action completes.

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>}>
      Optional custom options to include with the request.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Promise<void>">
  Allows the user to try another MFA method.

  A promise that resolves when the request is submitted.

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>}>
      Optional custom options to include with the request.
    </ParamField>
  </Expandable>
</ParamField>


# ResetPasswordMfaWebAuthnPlatformChallenge
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/ResetPasswordMfaWebAuthnPlatformChallenge



<Frame>
  <img alt="" />
</Frame>

ResetPasswordMfaWebAuthnPlatformChallenge

```ts Example theme={null}
// Assuming 'sdk' is an instance of ResetPasswordMfaWebAuthnPlatformChallenge
try {
  await sdk.continueWithPasskey({
    rememberDevice: true // if user checked the box and sdk.screen.showRememberDevice is true
  });
  // On success, Auth0 handles redirection.
} catch (error) {
  console.error("Platform authenticator verification failed:", error);
  // If it's a WebAuthn API error (DOMException), report it
  if (error instanceof DOMException && error.name && error.message) { // DOMException check
    await sdk.reportBrowserError({ error: { name: error.name, message: error.message } });
  }
  // Check sdk.transaction.errors for server-side validation messages if the page reloads.
}
```

## Constructors

<ParamField type="Constructor">
  Initializes a new instance of the `ResetPasswordMfaWebAuthnPlatformChallenge` class.
  It retrieves the necessary context (screen, transaction, etc.) from the global `universal_login_context`
  and sets up screen-specific properties via `ScreenOverride`.

  #### Throws

  If the Universal Login Context is not available or if the screen name
  in the context does not match `ResetPasswordMfaWebAuthnPlatformChallenge.screenIdentifier`.
</ParamField>

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnResetPasswordMfaWebAuthnPlatformChallenge">ScreenMembersOnResetPasswordMfaWebAuthnPlatformChallenge</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string">
  static
</ParamField>

## Methods

<ParamField type="Promise<void>">
  Initiates the WebAuthn platform authenticator challenge by calling `navigator.credentials.get()`
  using the challenge options provided in `screen.publicKey`.
  If successful, it submits the resulting credential assertion to Auth0 with `action: "default"`.

  A promise that resolves when the verification attempt is submitted.
  A successful operation typically results in a redirect.

  #### Throws

  Throws an error if `screen.publicKey` is missing,
  if `navigator.credentials.get()` fails (e.g., user cancellation `NotAllowedError`),
  or if the form submission to Auth0 fails. If `navigator.credentials.get()` fails
  with a `DOMException`, it's recommended to catch that error and call `reportBrowserError`.

  ```typescript Example theme={null}
  // Assuming 'sdk' is an instance of ResetPasswordMfaWebAuthnPlatformChallenge
  try {
    await sdk.continueWithPasskey({
      rememberDevice: true // if user checked the box and sdk.screen.showRememberDevice is true
    });
    // On success, Auth0 handles redirection.
  } catch (error) {
    console.error("Platform authenticator verification failed:", error);
    // If it's a WebAuthn API error (DOMException), report it
    if (error instanceof DOMException && error.name && error.message) { // DOMException check
      await sdk.reportBrowserError({ error: { name: error.name, message: error.message } });
    }
    // Check sdk.transaction.errors for server-side validation messages if the page reloads.
  }
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ResetPasswordMfaWebAuthnPlatformChallengeContinueOptions">ResetPasswordMfaWebAuthnPlatformChallengeContinueOptions</a></span>}>
      **Properties**

      <ParamField type="boolean" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>

<ParamField type="Promise<void>">
  Reports a browser-side error that occurred during the `navigator.credentials.get()` API call.
  This is used to inform Auth0 about issues like user cancellation (`NotAllowedError`),
  timeout, or other WebAuthn API specific errors.
  It submits the error details with `action: "showError::{errorDetailsJsonString}"`.

  A promise that resolves when the error report is successfully submitted.

  #### Throws

  If the form submission fails (e.g., network error, invalid state).

  ```typescript Example theme={null}
  // In your UI component, in the catch block of navigator.credentials.get():
  // } catch (webAuthnError) {
  //   if (webAuthnError instanceof DOMException) {
  //     await sdk.reportBrowserError({
  //       error: { name: webAuthnError.name, message: webAuthnError.message }
  //     });
  //   } else {
  //     // Handle other types of errors
  //   }
  // }
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ResetPasswordMfaWebAuthnPlatformChallengeReportErrorOptions">ResetPasswordMfaWebAuthnPlatformChallengeReportErrorOptions</a></span>}>
      An object containing:

      * `error`: A `WebAuthnErrorDetails` object with at least `name` and `message` properties
        from the `DOMException` thrown by `navigator.credentials.get()`.
      * Any other `CustomOptions` to be included in the form submission.

      **Properties**

      <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/WebAuthnErrorDetails">WebAuthnErrorDetails</a></span>}>
        The error object from the WebAuthn API (`navigator.credentials.get()`)
        to be reported. Must include `name` and `message`.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Promise<void>">
  Allows the user to opt-out of the WebAuthn platform authenticator challenge and select
  a different MFA method for verifying their identity during password reset.
  This action submits `action: "pick-authenticator"` to Auth0, which should navigate
  the user to an MFA factor selection screen.

  A promise that resolves when the 'pick-authenticator' action is submitted.

  #### Throws

  If the form submission fails (e.g., network error, invalid state).

  ```typescript Example theme={null}
  // In your UI component, when a "Try Another Method" button is clicked:
  try {
    await sdk.tryAnotherMethod();
    // On success, Auth0 handles redirection to the MFA factor selection screen.
  } catch (error) {
    console.error("Failed to switch MFA method:", error);
  }
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ResetPasswordMfaWebAuthnPlatformChallengeTryAnotherMethodOptions">ResetPasswordMfaWebAuthnPlatformChallengeTryAnotherMethodOptions</a></span>}>
      Optional. Any custom parameters to be sent with the request.
      These will be included in the form data.
    </ParamField>
  </Expandable>
</ParamField>


# ResetPasswordMfaWebAuthnRoamingChallenge
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/ResetPasswordMfaWebAuthnRoamingChallenge



<Frame>
  <img alt="" />
</Frame>

ResetPasswordMfaWebAuthnRoamingChallenge

```ts Example theme={null}
// In your UI component for the reset-password-mfa-webauthn-roaming-challenge screen:
const sdk = new ResetPasswordMfaWebAuthnRoamingChallenge();

async function handleSecurityKeyAuth() {
  try {
    const userWantsToRemember = document.getElementById('remember-device-checkbox')?.checked || false;
    await sdk.useSecurityKey({ rememberDevice: sdk.screen.showRememberDevice && userWantsToRemember });
    // On success, Auth0 typically handles redirection.
  } catch (err) {
    console.error("Security key authentication failed:", err);
    // If it's a WebAuthn API error, report it to Auth0
    if (err.name && err.message) { // Basic check for DOMException-like error
      try {
        await sdk.showError({ error: { name: err.name, message: err.message } });
      } catch (reportError) {
        console.error("Failed to report WebAuthn error:", reportError);
      }
    }
    // Update UI to inform the user, e.g., "Security key verification failed. Please try again."
    // Also check `sdk.transaction.errors` if the page might have reloaded with an error message from the server.
  }
}
```

## Constructors

<ParamField type="Constructor">
  Initializes a new instance of the `ResetPasswordMfaWebAuthnRoamingChallenge` class.
  It retrieves the necessary context (screen, transaction, etc.) from the global

  #### Throws

  If the Universal Login Context is not available or if the screen name
  in the context does not match `ResetPasswordMfaWebAuthnRoamingChallenge.screenIdentifier`.
</ParamField>

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnResetPasswordMfaWebAuthnRoamingChallenge">ScreenMembersOnResetPasswordMfaWebAuthnRoamingChallenge</a></span>}>
  Holds the specific screen data and properties for this screen,

  (for the WebAuthn challenge) and `showRememberDevice`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string">
  The unique identifier for this screen, used for internal SDK logic and telemetry.
</ParamField>

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>

<ParamField type="Promise<void>">
  Reports a client-side WebAuthn API error (from `navigator.credentials.get()`) to Auth0.
  This method is intended to be called when [useSecurityKey](#usesecuritykey) (or a direct call to
  `navigator.credentials.get()`) fails due to a standard WebAuthn API error
  (e.g., `NotAllowedError` if the user cancels, `NotFoundError`, `SecurityError`, timeout).
  It submits the error details with `action: "showError::{errorDetailsJsonString}"` and an empty `response`.

  A promise that resolves when the error report is successfully submitted.
  Auth0 may re-render the page with specific error messages in `this.transaction.errors` or redirect.

  #### Throws

  Throws an error if the form submission itself fails (e.g., network error, invalid state).

  ```typescript Example theme={null}
  // In your UI, after catching an error from `sdk.useSecurityKey()` or `navigator.credentials.get()`:
  if (webAuthnError instanceof DOMException) {
    await sdk.showError({
      error: { name: webAuthnError.name, message: webAuthnError.message },
      rememberDevice: userWantsToRemember // if applicable
    });
  }
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ResetPasswordMfaWebAuthnRoamingChallengeShowErrorOptions">ResetPasswordMfaWebAuthnRoamingChallengeShowErrorOptions</a></span>}>
      **Properties**

      <ParamField type="boolean" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Promise<void>">
  Allows the user to opt-out of the WebAuthn roaming authenticator challenge and select a different MFA method.
  This action submits `action: "pick-authenticator"` to Auth0, which should navigate
  the user to an MFA factor selection screen.

  A promise that resolves when the 'pick-authenticator' action is submitted.

  #### Throws

  Throws an error if the form submission fails (e.g., network error, invalid state).

  ```typescript Example theme={null}
  // When the user clicks a "Try Another Way" button:
  await sdk.tryAnotherMethod({ rememberDevice: userWantsToRemember });
  // Auth0 handles redirection to the MFA selection screen.
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ResetPasswordMfaWebAuthnRoamingChallengeTryAnotherMethodOptions">ResetPasswordMfaWebAuthnRoamingChallengeTryAnotherMethodOptions</a></span>}>
      **Properties**

      <ParamField type="boolean" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="Promise<void>">
  Initiates the WebAuthn security key challenge.
  This method internally calls `navigator.credentials.get()` using the challenge
  options provided in `this.screen.publicKey`.
  If the user successfully authenticates with their security key, the resulting
  `PublicKeyCredential` is stringified and submitted to Auth0 with `action: "default"`.

  A promise that resolves when the verification attempt is submitted.
  A successful operation usually results in Auth0 redirecting the user.

  #### Throws

  Throws an error if `this.screen.publicKey` is missing (indicating missing challenge options),
  if `getPasskeyCredentials` (which wraps `navigator.credentials.get()`) fails (e.g., user cancellation,
  no authenticator found, hardware error), or if the final form submission to Auth0 fails.
  It is crucial to catch errors from this method. WebAuthn API errors (like `NotAllowedError`)
  should be reported using [showError](#showerror).

  ```typescript Example theme={null}
  // In your UI component for the reset-password-mfa-webauthn-roaming-challenge screen:
  const sdk = new ResetPasswordMfaWebAuthnRoamingChallenge();

  async function handleSecurityKeyAuth() {
    try {
      const userWantsToRemember = document.getElementById('remember-device-checkbox')?.checked || false;
      await sdk.useSecurityKey({ rememberDevice: sdk.screen.showRememberDevice && userWantsToRemember });
      // On success, Auth0 typically handles redirection.
    } catch (err) {
      console.error("Security key authentication failed:", err);
      // If it's a WebAuthn API error, report it to Auth0
      if (err.name && err.message) { // Basic check for DOMException-like error
        try {
          await sdk.showError({ error: { name: err.name, message: err.message } });
        } catch (reportError) {
          console.error("Failed to report WebAuthn error:", reportError);
        }
      }
      // Update UI to inform the user, e.g., "Security key verification failed. Please try again."
      // Also check `sdk.transaction.errors` if the page might have reloaded with an error message from the server.
    }
  }
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ResetPasswordMfaWebAuthnRoamingChallengeUseSecurityKeyOptions">ResetPasswordMfaWebAuthnRoamingChallengeUseSecurityKeyOptions</a></span>}>
      **Properties**

      <ParamField type="boolean" />
    </ParamField>
  </Expandable>
</ParamField>


# ResetPasswordRequest
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/ResetPasswordRequest



<Frame>
  <img alt="" />
</Frame>

```ts Example theme={null}
import ResetPasswordRequest from "@auth0/auth0-acul-js/reset-password-request";
const resetPasswordRequest = new ResetPasswordRequest();
resetPasswordRequest.getLoginIdentifiers();
```

## Constructors

<ParamField type="Constructor" />

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnResetPasswordRequest">ScreenMembersOnResetPasswordRequest</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembersOnResetPasswordRequest">TransactionMembersOnResetPasswordRequest</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string" />

## Methods

<ParamField type="Promise<void>">
  ```ts Example theme={null}
  import ResetPasswordRequest from '@auth0/auth0-acul-js/reset-password-request';

  const resetPasswordRequest = new ResetPasswordRequest();
  resetPasswordRequest.backToLogin();
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/type-aliases/ScreenIdentifierType">ScreenIdentifierType</a>[]</span>}>
  **`Utility Feature`**

  Gets the active identifier types for the reset-password-request screen

  An array of active identifier types or null if none are active

  ```typescript Example theme={null}
  import ResetPasswordRequest from "@auth0/auth0-acul-js/reset-password-request";
  const resetPasswordRequest = new ResetPasswordRequest();
  resetPasswordRequest.getLoginIdentifiers();
  ```
</ParamField>

<ParamField type="Promise<void>">
  ```ts Example theme={null}
  import ResetPasswordRequest from '@auth0/auth0-acul-js/reset-password-request';

  const resetPasswordRequest = new ResetPasswordRequest();
  resetPasswordRequest.resetPassword({ username: 'testuser' });
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ResetPasswordRequestOptions">ResetPasswordRequestOptions</a></span>}>
      **Properties**

      <ParamField type="string" />

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>


# ResetPasswordSuccess
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/ResetPasswordSuccess



<Frame>
  <img alt="ACUL Request password success" />
</Frame>

```ts Example theme={null}
import ResetPasswordSuccess from "@auth0/auth0-acul-js/reset-password-success";
const resetPasswordSuccessManager = new ResetPasswordSuccess();
```

## Constructors

<ParamField type="Constructor" />

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembers">ScreenMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers">TransactionMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>} />

<ParamField type="string" />

## Methods

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  Retrieves the array of transaction errors from the context, or an empty array if none exist.

  An array of error objects from the transaction context.
</ParamField>


# SDKUsageError
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/SDKUsageError



SDKUsageError

## Constructors

<ParamField type="Constructor">
  <Expandable title="Parameters">
    <ParamField type="string">
      The error message.
    </ParamField>

    <ParamField type="string">
      The optional field associated with the error.
    </ParamField>
  </Expandable>
</ParamField>

## Properties

<ParamField type="&#x22;SDK_USAGE_ERROR&#x22;" />

<ParamField type="string" />


# Signup
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/Signup



The Signup class implements the `signup` screen functionality. This screen collects the user's identifier and password. Depending on your tenant, this identifer can be an email, phone number, or username.

<Frame>
  <img alt="ACUL Signup screen image" />
</Frame>

## Constructors

Create an instance of Signup screen manager

```ts Example theme={null}
import Signup from '@auth0/auth0-acul-js/signup';
const signupManager = new Signup();
signupManager.signup({
 email: 'test@example.com',
 password: 'P@$wOrd123!',
});
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`, for the `login` screen.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnSignup">ScreenMembersOnSignup</a></span>}>
  Contains details specific to the `signup` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembersOnSignup">TransactionMembersOnSignup</a></span>}>
  Provides transaction-specific data for the `signup` screen, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)" />

This method handles the submission of the social signup form. It is similar to the [signup](#signup) method but is used for social signups.

```typescript Example theme={null}
import Signup from '@auth0/auth0-acul-js/signup';
const signupManager = new Signup();
signupManager.federatedSignup({
 connection: 'google-oauth2'
});
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="string">
    The social connection name to use.
  </ParamField>

  <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
    Additional data collected from the user.
  </ParamField>
</Expandable>

***

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist. An array of error objects from the transaction context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Identifier">Identifier</a>[]</span>}>
  This method returns the list of enabled identifiers for the signup form,
  marking each as required or optional based on transaction config. An Array of identifier objects (e.g., email, phone, username).

  ```ts Example theme={null}
  const signup = new Signup();
  const identifiers = signup.getSignupIdentifiers();
  // [{ type: 'email', required: true }, { type: 'username', required: false }]
  ```
</ParamField>

<ParamField type="(options ?)" />

This method redirects the user to the country code selection list, where they can update the country code prefix for their phone numnber.

```ts Example theme={null}
import Signup from "@auth0/auth0-acul-js/signup";
const signupManager = new Signup();

signupManager.pickCountryCode();
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
    Additional data collected from the user.
  </ParamField>
</Expandable>

***

<ParamField type="(options ?)" />

This method handles the submission of the signup form.

```typescript Example theme={null}
import Signup from '@auth0/auth0-acul-js/signup';

const signupManager = new Signup();

signupManager.signup({
 email: 'test@example.com',
 password: 'P@$$wOrd123!',
});
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="string">
    The user's identifier.
  </ParamField>

  <ParamField type="string">
    The user's password.
  </ParamField>

  <ParamField type="string">
    The captcha code or response from the captcha provider. This property is required if your Auth0 tenant has Bot Detection enabled.
  </ParamField>

  <ParamField type="string">
    The user's email.
  </ParamField>

  <ParamField type="string">
    The user's phone number.
  </ParamField>
</Expandable>

***

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PasswordValidationResult">PasswordValidationResult</a></span>}>
  This method returns an object of type [PasswordValidationResult](/docs/libraries/acul/js-sdk/Screens/interfaces/PasswordValidationResult) indicating whether the password is valid and why.

  **Method Parameters**

  <Expandable title="Parameters">
    <ParamField type="string">
      The user's password.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UsernameValidationResult">UsernameValidationResult</a></span>}>
  This method validates a given username against the current username policy defined in the transaction context. It returns an object indicating whether the username is valid and why.

  ```ts Example theme={null}
  const signup = new Signup();
  const result = signup.validateUsername('myusername');
  // result => { valid: true, errors: [] }
  ```

  **Method Parameters**

  <Expandable title="Parameters">
    <ParamField type="string">
      \`The username string to validate.
    </ParamField>
  </Expandable>
</ParamField>


# SignupId
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/SignupId



The SignupId class implements the `signup-id` screen functionality. This screen collects the user's identifier.

<Frame>
  <img alt="Signup ID" />
</Frame>

## Constructors

Create an instance of SignupId screen manager

```ts Example theme={null}
import SignupId from "@auth0/auth0-acul-js/signup-id";
const signupIdManager = new SignupId();
const { transaction } = signupIdManager;
//get mandatory & optional identifiers required for signup
const mandatoryIdentifier = transaction.getRequiredIdentifiers(); // eg: email
const optionalIdentifiers = transaction.getOptionalIdentifiers() // eg: phone
const signupParams = {
 email : "testEmail",
 phone : "+91923456789"
};
signupIdManager.signup(signupParams);
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`, for the `login` screen.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnSignupId">ScreenMembersOnSignupId</a></span>}>
  Contains details specific to the `signup-id` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembersOnSignupId">TransactionMembersOnSignupId</a></span>}>
  Provides transaction-specific data for the `signup-id` screen, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)" />

This method handles allows signup via different social identifiers. For example: Google, Facebook etc.

```ts Example theme={null}
import SignupId from "@auth0/auth0-acul-js/signup-id";

const signupIdManager = new SignupId();
const { transaction } = signupIdManager;

//get social connections
const socialConnection = transaction.alternateConnections; //eg: "google-oauth2"

const signupParams = {
 connection : socialConnection[0].name, // "google-oauth2"
};

signupIdManager.federatedSignup(signupParams);
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="string">
    The social connection name to use.
  </ParamField>

  <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
    Additional data collected from the user.
  </ParamField>
</Expandable>

***

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist. An array of error objects from the transaction context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Identifier">Identifier</a>[]</span>}>
  This method returns the list of enabled identifiers for the `signup-id` form, marking each as required or optional based on transaction config. An Array of identifier objects (e.g., email, phone, username).

  ```ts Example theme={null}
  const signupId = new SignupId();
  const identifiers = signupId.getSignupIdentifiers();
  // [{ type: 'email', required: true }, { type: 'username', required: false }]
  ```
</ParamField>

<ParamField type="(options ?)" />

This method redirects the user to the country code selection list, where they can update the country code prefix for their phone numnber.

```ts Example theme={null}
import SignupId from "@auth0/auth0-acul-js/signup-id";
const signupIdManager = new SignupId();

signupIdManager.pickCountryCode();
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
    Additional data collected from the user.
  </ParamField>
</Expandable>

***

<ParamField type="(options ?)" />

This methods handles `signup-id` related configuration. It allows to signup new users via different identifiers.

```ts Example theme={null}
import SignupId from "@auth0/auth0-acul-js/signup-id";

const signupIdManager = new SignupId();
const { transaction } = signupIdManager;

//get mandatory & optional identifiers required for signup
const mandatoryIdentifier = transaction.getRequiredIdentifiers(); // eg: email
const optionalIdentifiers = transaction.getOptionalIdentifiers() // eg: phone

const signupParams = {
 email : "testEmail",
 phone : "+91923456789"
};

signupIdManager.signup(signupParams);
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="string">
    The user's identifier.
  </ParamField>

  <ParamField type="string">
    The captcha code or response from the captcha provider. This property is required if your Auth0 tenant has Bot Detection enabled.
  </ParamField>

  <ParamField type="string">
    The user's email.
  </ParamField>

  <ParamField type="string">
    The user's phone number.
  </ParamField>

  <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
    Additional data collected from the user.
  </ParamField>
</Expandable>

***

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UsernameValidationResult">UsernameValidationResult</a></span>}>
  This method validates a given username against the current username policy defined in the transaction context. It returns an object indicating whether the username is valid and why.

  ```ts Example theme={null}
  const signup = new Signup();
  const result = signup.validateUsername('myusername');
  // result => { valid: true, errors: [] }
  ```

  **Method Parameters**

  <Expandable title="Parameters">
    <ParamField type="string">
      \`The username string to validate.
    </ParamField>
  </Expandable>
</ParamField>


# SignupPassword
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/SignupPassword



The SignupPassword class implements the `signup-password` screen functionality. This screen collects the user's password.

## Constructors

Create an instance of SignupPassword screen manager

<Frame>
  <img alt="Signup Password with Flexible IDs" />
</Frame>

```ts Example theme={null}
import SignupPassword from "@auth0/auth0-acul-js/signup-password";
const signupPasswordManager = new SignupPassword();
const validationResults = signupPasswordManager.validatePassword('MyP@ssw0rd!');
console.log(validationResults);
// [
//   { code: 'password-policy-length-at-least', policy: 'At least 12 characters', isValid: false },
//   { code: 'password-policy-lower-case', policy: 'Lowercase letters (a-z)', isValid: true },
//   ...
// ]
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Provides branding-related configurations, such as branding theme and settings.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers">ClientMembers</a></span>}>
  Provides client-related configurations, such as `id`, `name`, and `logoUrl`, for the `login` screen.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Provides information about the user's organization, such as organization `id` and `name`.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers">PromptMembers</a></span>}>
  Contains data about the current prompt in the authentication flow.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembersOnSignupPassword">ScreenMembersOnSignupPassword</a></span>}>
  Contains details specific to the `signup-password` screen, including its configuration and context.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers">TenantMembers</a></span>}>
  Contains data related to the tenant, such as `id` and associated metadata.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembersOnSignupPassword">TransactionMembersOnSignupPassword</a></span>}>
  Provides transaction-specific data for the `signup-password` screen, such as active identifiers and flow states.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Handles untrusted data passed to the SDK, such as user input during login.
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers">UserMembers</a></span>}>
  Details of the active user, including `username`, `email`, and `roles`.
</ParamField>

## Methods

<ParamField type="(options ?)" />

This methods handles allows signup via different social identifiers. For example: Google, Facebook etc.

```ts Example theme={null}
import SignupPassword from "@auth0/auth0-acul-js/signup-id";

const signupIdManager = new SignupPassword();
const { transaction } = signupIdManager;

//get social connections
const socialConnection = transaction.alternateConnections; //eg: "google-oauth2"

const signupParams = {
 connection : socialConnection[0].name, // "google-oauth2"
};

signupIdManager.federatedSignup(signupParams);
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="string">
    The social connection name to use.
  </ParamField>

  <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
    Additional data collected from the user.
  </ParamField>
</Expandable>

***

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">Error</a>[]</span>}>
  This method retrieves the array of transaction errors from the context, or an empty array if none exist. An array of error objects from the transaction context.
</ParamField>

<ParamField type="(options ?)" />

This methods handles signup-password related screen configuration. It allows to proceed with registering signup password along with signup identifiers passed in previous screen

```ts Example theme={null}
import SignupPassword from "@auth0/auth0-acul-js/signup-password";

const signupPasswordManager = new SignupPassword();
const { transaction, screen } = signupPasswordManager;

//get mandatory & optional identifiers required for signup-password screen to proceed
const mandatoryIdentifier = transaction.getRequiredIdentifiers(); //eg: email
const optionalIdentifiers = transaction.getOptionalIdentifiers() //eg: phone

//get signup data submitted on previous screen from previous screen
const data = transaction.screen.getScreenData(); //eg: email, phone

const signupParams = {
 email : data.email,
 password: "******"
};

signupPasswordManager.signup(signupParams);
```

**Method Parameters**

<Expandable title="Parameters">
  <ParamField type="string">
    The captcha code or response from the captcha provider. This property is required if your Auth0 tenant has Bot Detection enabled.
  </ParamField>

  <ParamField type="string">
    The user's email.
  </ParamField>

  <ParamField type="string">
    The user's password.
  </ParamField>

  <ParamField type="string">
    The user's phone number.
  </ParamField>

  <ParamField type="string">
    The user's identifier.
  </ParamField>

  <ParamField type="&#x22;string&#x22; | &#x22;number&#x22; | &#x22;boolean&#x22; | &#x22;undefined&#x22;">
    Additional data collected from the user.
  </ParamField>
</Expandable>

***

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PasswordValidationResult">PasswordValidationResult</a></span>}>
  This method validates a password string against the current transaction's password policy. This method retrieves the password policy from the current transaction context and delegates the actual validation to `coreValidatePassword`.

  It returns an array of validation results, each containing:

  * `code`: the identifier of the password rule,
  * `policy`: a user-friendly description of the rule,
  * `isValid`: boolean indicating if the password passed that rule.

  ```ts Example theme={null}
  import SignupPassword from "@auth0/auth0-acul-js/signup-password";
  const signupPasswordManager = new SignupPassword();
  const validationResults = signupPasswordManager.validatePassword('MyP@ssw0rd!');
  console.log(validationResults);
  // [
  //   { code: 'password-policy-length-at-least', policy: 'At least 12 characters', isValid: false },
  //   { code: 'password-policy-lower-case', policy: 'Lowercase letters (a-z)', isValid: true },
  //   ...
  // ]
  ```

  **Method Parameters**

  <Expandable title="Parameters">
    <ParamField type="string">
      The password string to validate.
    </ParamField>
  </Expandable>
</ParamField>


# UserInputError
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/classes/UserInputError



UserInputError

## Constructors

<ParamField type="Constructor">
  <Expandable title="Parameters">
    <ParamField type="string">
      The error message.
    </ParamField>

    <ParamField type="string">
      The optional field associated with the error.
    </ParamField>
  </Expandable>
</ParamField>

## Properties

<ParamField type="&#x22;USER_INPUT_ERROR&#x22;" />

<ParamField type="string" />


# BrandingMembers
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/interfaces/BrandingMembers



```ts Example theme={null}
export interface BrandingMembers {
  settings: BrandingSettings | null;
  themes: BrandingThemes | null;
}
```

## Properties

<ParamField type={<span><a href="#BrandingSettings">BrandingSettings</a></span>} />

<ParamField type={<span><a href="#BrandingThemes">BrandingThemes</a></span>} />

## BrandingSettings

```ts theme={null}
export interface BrandingSettings {
  colors?: {
    primary?: string;
    pageBackground?:
      | string
      | {
          type: string;
          start: string;
          end: string;
          angleDegree: number;
        };
  };
  faviconUrl?: string;
  logoUrl?: string;
  fontUrl?: string;
}
```

### Properties

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string | { angleDegree: number; end: string; start: string; type: string; }" />

    <ParamField type="string" />
  </Expandable>
</ParamField>

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="string" />

## BrandingThemes

```ts theme={null}
export interface BrandingThemes {
  default: {
    borders: Record<string, string | boolean | number>;
    colors: Record<string, string>;
    displayName: string;
    fonts: Record<string, string | boolean | object>;
    pageBackground: Record<string, string>;
    widget: Record<string, string | number>;
  };
}
```

### Properties

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="Record<string, string | boolean | number>" />

    <ParamField type="Record<string, string>" />

    <ParamField type="string" />

    <ParamField type="Record<string, string | boolean | object>" />

    <ParamField type="Record<string, string>" />

    <ParamField type="Record<string, string | number>" />
  </Expandable>
</ParamField>


# ClientMembers
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/interfaces/ClientMembers



```ts Example theme={null}
export interface ClientMembers {
  id: string;
  name: string;
  logoUrl: string | null;
  description: string | null;
  metadata: { [key: string]: string } | null;
}
```

## Properties

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="{[key: string]: string; }">
  <Expandable title="Parameters">
    <ParamField type="string">
      Optional key-value pairs for storing custom metadata.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string" />


# OrganizationMembers
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/interfaces/OrganizationMembers



```ts Example theme={null}
export interface OrganizationMembers {
  id: string | null;
  name: string | null;
  usage: string | null;
  displayName: string | null;
  branding: Branding | null;
  metadata: { [key: string]: string } | null;
}
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Branding">Branding</a></span>} />

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="{[key: string]: string; }">
  <Expandable title="Parameters">
    <ParamField type="string">
      Optional key-value pairs for storing custom metadata.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string" />

<ParamField type="string" />


# PromptMembers
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/interfaces/PromptMembers



```ts Example theme={null}
export interface PromptMembers {
  name: string;
}
```

## Properties

<ParamField type="string" />


# ScreenMembers
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/interfaces/ScreenMembers



```ts Example theme={null}
export interface ScreenMembers {
  name: string;
  captchaImage: string | null;
  captchaSiteKey: string | null;
  captchaProvider: string | null;
  isCaptchaAvailable: boolean;
  data: Record<string, string | boolean | string[] | Record<string, string[]> | Array<PhonePrefix> | PasskeyCreate> | null;
  links: Record<string, string> | null;
  texts: Record<string, string> | null;
  captcha: CaptchaContext | null;
}
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/CaptchaContext">CaptchaContext</a></span>}>
  <Expandable title="Parameters">
    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />
  </Expandable>
</ParamField>

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="string" />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PasskeyCreate">PasskeyCreate</a></span>}>
  <Expandable title="Parameters">
    <ParamField type="string, string | boolean | string[] | Record<string, string[]> | Array<PhonePrefix> | PasskeyCreate" />
  </Expandable>
</ParamField>

<ParamField type="boolean" />

<ParamField type="Record<string, string>" />

<ParamField type="string" />

<ParamField type="Record<string, string>" />


# TenantMembers
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/interfaces/TenantMembers



```ts Example theme={null}
export interface TenantMembers {
  name: string | null;
  friendlyName: string | null;
  enabledLocales: string[] | null;
  enabledFactors: string[] | null;
}
```

## Properties

<ParamField type="string[]" />

<ParamField type="string[]" />

<ParamField type="string" />

<ParamField type="string" />


# TransactionMembers
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/interfaces/TransactionMembers



```ts Example theme={null}
export interface TransactionMembers {
  state: string;
  locale: string;
  countryCode: CountryCode['code'] | null;
  countryPrefix: CountryCode['prefix'] | null;
  connectionStrategy: string | null;
  hasErrors: boolean;
  errors: Error[] | null;
  currentConnection: Connection | null;
  alternateConnections: (Connection | EnterpriseConnection)[] | null;
}
```

## Properties

<ParamField type={<span><a href="#connection">[Connection]</a> | <a href="#enterpriseconnection">[EnterpriseConnection][]</a></span>} />

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="string" />

<ParamField type={<span><a href="#connection">Connection</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Error">[Error]</a></span>} />

<ParamField type="boolean" />

<ParamField type="string" />

<ParamField type="string" />

## Connection

```ts theme={null}
export interface Connection {
  name: string;
  strategy: string;
  metadata?: Record<string, string>;
}
```

### Properties

<ParamField type="Record<string, string>" />

<ParamField type="string" />

<ParamField type="string" />

## EnterpriseConnection

```ts theme={null}
export interface EnterpriseConnection extends Connection {
  options: {
    iconUrl?: string;
    displayName?: string;
    showAsButton: boolean;
  };
}
```

### Properties

<ParamField type="Record<string, string>" />

<ParamField type="string" />

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="boolean" />
  </Expandable>
</ParamField>

<ParamField type="string" />

## DBConnection

```ts Example theme={null}
export interface DBConnection extends Connection {
  options: {
    signup_enabled: boolean;
    flexible_identifiers_active?: boolean;
    forgot_password_enabled: boolean;
    username_required?: boolean;
    validation?: {
      username: {
        max_length: number;
        min_length: number;
      };
    };
    attributes?: {
      email?: {
        signup_status: string;
        identifier_active: boolean;
      };
      username?: {
        signup_status: string;
        identifier_active: boolean;
        validation?: {
          max_length: number;
          min_length: number;
          allowed_types: {
            email: boolean;
            phone_number: boolean;
          };
        };
      };
      phone?: {
        signup_status: string;
        identifier_active: boolean;
      };
    };
    authentication_methods: {
      password: {
        enabled: boolean;
        policy: string;
        min_length: number;
        password_security_info?: PasswordComplexityRule[];
      };
      passkey: {
        enabled: boolean;
      };
    };
  };
}
```

### Properties

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="boolean" />

    <ParamField type="boolean" />

    <ParamField type="boolean" />

    <ParamField type="boolean" />

    <ParamField type="object">
      **Properties**

      <ParamField type="object">
        **Properties**

        <ParamField type="number" />

        <ParamField type="number" />
      </ParamField>
    </ParamField>

    <ParamField type="object">
      **Properties**

      <ParamField type="object">
        **Properties**

        <ParamField type="string" />

        <ParamField type="boolean" />
      </ParamField>

      <ParamField type="object">
        **Properties**

        <ParamField type="string" />

        <ParamField type="boolean" />

        <ParamField type="object">
          **Properties**

          <ParamField type="number" />

          <ParamField type="number" />

          <ParamField type="object">
            **Properties**

            <ParamField type="boolean" />

            <ParamField type="boolean" />
          </ParamField>
        </ParamField>
      </ParamField>

      <ParamField type="object">
        **Properties**

        <ParamField type="string" />

        <ParamField type="boolean" />
      </ParamField>
    </ParamField>

    <ParamField type="object">
      **Properties**

      <ParamField type="object">
        **Properties**

        <ParamField type="boolean" />

        <ParamField type="string" />

        <ParamField type="number" />

        <ParamField type="PasswordComplexityRule[]" />
      </ParamField>

      <ParamField type="object">
        <ParamField type="boolean" />
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

## PasswordlessConnection

```ts Example theme={null}
export interface PasswordlessConnection extends Connection {
  options: {
    signup_enabled: boolean;
  };
}
```

### Properties

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="boolean" />
  </Expandable>
</ParamField>

## SocialConnection

```ts Example theme={null}
export interface SocialConnection extends Connection {}
```

## PasswordPolicy

```ts theme={null}
export interface PasswordPolicy {
  enabled?: boolean;
  minLength?: number;
  policy: 'none' | 'low' | 'fair' | 'good' | 'excellent';
  passwordSecurityInfo?: PasswordComplexityRule[];
}
```

### Properties

<ParamField type="boolean" />

<ParamField type="number" />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/PasswordComplexityRule">[PasswordComplexityRule][]</a></span>} />

<ParamField type="&#x22;none&#x22; | &#x22;low&#x22; | &#x22;fair&#x22; | &#x22;good&#x22; | &#x22;excellent&#x22;" />


# UntrustedDataMembers
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/interfaces/UntrustedDataMembers



```ts Example theme={null}
export interface UntrustedDataMembers {
  submittedFormData: { [key: string]: string | number | boolean | undefined | null } | null;
  authorizationParams: {
    login_hint?: string;
    screen_hint?: string;
    ui_locales?: string;
    [key: `ext-${string}`]: string;
  } | null;
}
```

## Properties

<ParamField type="{ [key:  ext-${string} ]: string; login_hint?: string; screen_hint?: string; ui_locales?: string; }">
  <Expandable title="Parameters">
    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="ext-${string}" />
  </Expandable>
</ParamField>

<ParamField type="{[key: string]: string | number | boolean | null | undefined; }">
  <Expandable title="Parameters">
    <ParamField type="string | number | boolean | undefined | null" />
  </Expandable>
</ParamField>


# UserMembers
Source: https://auth0.com/docs/libraries/acul/js-sdk/Screens/interfaces/UserMembers



```ts Example theme={null}
export interface UserMembers {
  id: string | null;
  email: string | null;
  username: string | null;
  phoneNumber: string | null;
  picture: string | null;
  enrolledFactors: Array<string> | null;
  enrolledEmails: Array<EnrolledEmail> | null;
  enrolledPhoneNumbers: Array<EnrolledPhoneNumber> | null;
  enrolledDevices: Array<EnrolledDevice> | null;
  organizations: Organizations[] | null;
  userMetadata: { [key: string]: string } | null;
  appMetadata: { [key: string]: string } | null;
}
```

## Properties

<ParamField type="{[key: string]: string; }">
  <Expandable title="Parameters">
    <ParamField type="string" />
  </Expandable>
</ParamField>

<ParamField type="string" />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/EnrolledDevice">EnrolledDevice</a></span>}>
  <Expandable title="Parameters">
    <ParamField type="number" />

    <ParamField type="string" />
  </Expandable>
</ParamField>

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/EnrolledEmail">EnrolledEmail</a></span>}>
  <Expandable title="Parameters">
    <ParamField type="number" />

    <ParamField type="string" />
  </Expandable>
</ParamField>

<ParamField type="string[]" />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/EnrolledPhoneNumber">EnrolledPhoneNumber</a></span>}>
  <Expandable title="Parameters">
    <ParamField type="number" />

    <ParamField type="string" />
  </Expandable>
</ParamField>

<ParamField type="string" />

<ParamField type={<span><a href="/docs/libraries/acul/js-sdk/Screens/interfaces/Organizations">Organizations</a></span>} />

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="{[key: string]: string; }">
  <Expandable title="Parameters">
    <ParamField type="string" />
  </Expandable>
</ParamField>

<ParamField type="string" />


# ACUL React SDK
Source: https://auth0.com/docs/libraries/acul/react-sdk

ACUL React SDK.

The Auth0 ACUL React SDK lets you build custom Universal Login experiences with mininal effort. Whether you are working with login, signup, passwordless, or passkey enrollment, this SDK is built to handle modern authentication flows with ease.

### Why Choose the Auth0 ACUL React SDK?

* **Fast Integration:** Drop in pre-built screens like `login-id` or `signup-password`.
* **Modern Features:** Support passwordless, passkeys, and social logins.
* **Flexible Modules:** Import only what you need.
* **Unified State Management:** Use a single transaction object to handle all authentication flows.

### Architecture

#### How it works?

The SDK is built with modularity and scability in mind. Here is how it fits together:

* **Screens:** Each authentication flow, such as `login-id` and `signup-password`, is a standalone module.
* **Submit Handlers:** Manage form submissions and transitions.
* **Dynamic Forms:** Adapt fields and validations based on screen configurations.
* **Helper Properties:** Access common data, such as branding or transcation, in consistent way.

### Resources

| Read...                                                                                 | To learn...                               |
| --------------------------------------------------------------------------------------- | ----------------------------------------- |
| [ACUL Quickstart Guide](/docs/customize/login-pages/advanced-customizations/quickstart) | Start buliding with the SDK.              |
| [API Reference](/docs/libraries/acul/react-sdk/API-Reference/Screens/login)             | Explore screens, methods, and properties. |


# useAuth0Themes
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Hooks/useAuth0Themes



<ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/FlattenedTheme">FlattenedTheme</a></span>}>
  React hook to get the current theme options with flattened configuration from branding context.

  ## Returns

  [`FlattenedTheme`](/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/FlattenedTheme) | `null`

  FlattenedTheme object containing colors, fonts, borders, pageBackground, and widget configurations, or null if no branding is available

  ```tsx Example theme={null}
  import React from 'react';
  import { useAuth0Themes } from '@auth0/auth0-acul-react';

  const ThemedComponent: React.FC = () => {
    const theme = useAuth0Themes();

    if (!theme) {
      return <div>No theme available</div>;
    }

    return (
      <div
        style={{
          backgroundColor: theme.colors.primary_button,
          color: theme.colors.primary_button_label,
          borderRadius: theme.borders.button_border_radius,
        }}
      >
        <h1
          style={{
            fontWeight: theme.fonts.title.bold ? 'bold' : 'normal',
            fontSize: `${theme.fonts.title.size}%`,
          }}
        >
          Styled with Auth0 Theme
        </h1>
        <button
          style={{
            backgroundColor: theme.colors.primary_button,
            borderRadius: theme.borders.button_border_radius,
          }}
        >
          Primary Button
        </button>
        <p>Body text color: {theme.colors.body_text}</p>
      </div>
    );
  };
  ```
</ParamField>


# useCurrentScreen
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Hooks/useCurrentScreen



<ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CurrentScreenOptions">CurrentScreenOptions</a></span>}>
  React hook that gets the current screen context and state.

  This hook provides access to client configuration, organization details, screen identification,
  tenant settings, transaction state, and authorization parameters for building custom authentication UI.

  ## Return Value

  Returns `CurrentScreenOptions` object with the following properties, or `null` if unavailable:

  * **`client`** - Application identifier and metadata
  * **`organization`** - Organization ID and metadata (for Auth0 Organizations)
  * **`prompt`** - Current prompt name (e.g., "login", "consent", "mfa")
  * **`screen`** - Current screen name (e.g., "login-id", "login-password", "mfa-otp-challenge")
  * **`tenant`** - Tenant configuration including enabled locales
  * **`transaction`** - Transaction state, errors array, and current locale
  * **`untrustedData`** - Authorization parameters from the client (validate before use)

  ## Key Points

  * Use `screen.name` for conditional rendering of authentication screens
  * Always use optional chaining (`?.`) as nested properties can be `null`
  * Check `transaction.errors` for displaying validation errors
  * Access `organization.metadata` for organization-specific branding

  ## Returns

  [`CurrentScreenOptions`](/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CurrentScreenOptions) | `null`

  Current screen context data, or `null` if not available

  ```tsx Basic screen routing theme={null}
  import { useCurrentScreen } from '@auth0/auth0-acul-react';

  const AuthFlow = () => {
    const screenOptions = useCurrentScreen();
    const screen = screenOptions?.screen?.name || "login-id";

    switch (screen) {
      case "login-id":
        return <LoginIdScreen />;
      case "login-password":
        return <LoginPasswordScreen />;
      case "mfa-otp-challenge":
        return <MfaOtpChallengeScreen />;
      default:
        return null;
    }
  };
  ```

  ```tsx Accessing multiple properties theme={null}
  import { useCurrentScreen } from '@auth0/auth0-acul-react';

  const CustomAuthScreen = () => {
    const screenOptions = useCurrentScreen();
    const organizationId = screenOptions?.organization?.id;
    const errors = screenOptions?.transaction?.errors || [];
    const locale = screenOptions?.transaction?.locale || 'en';

    return (
      <div>
        {organizationId && <p>Organization: {organizationId}</p>}
        {errors.map((error, i) => (
          <p key={i} className="error">{error.message}</p>
        ))}
        <p>Language: {locale}</p>
      </div>
    );
  };
  ```
</ParamField>


# useErrors
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Hooks/useErrors



<ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UseErrorsResult">UseErrorsResult</a></span>}>
  React hook for reading and managing errors in ACUL (Advanced Customization of Universal Login).
  With all validation and server-side errors. It groups errors into three kinds:

  * `server` — errors returned by Auth0 or your own backend.
  * `client` — errors from client-side validation (e.g., invalid form input).
  * `developer` — errors caused by incorrect integration or SDK misuse.

  ## Returns

  [`UseErrorsResult`](/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UseErrorsResult)

  An object of type [UseErrorsResult](/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UseErrorsResult), containing:

  * `errors` — the full error list of type [ErrorsResult](/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ErrorsResult), with helpers:
    * `errors.byKind(kind, filter?)` — filter by error kind and optionally by field.
    * `errors.byField(field, filter?)` — filter by field and optionally by kind.
  * `hasError` — `true` if any error is currently present.
  * `dismiss(id)` — remove a specific error by its ID.
  * `dismissAll()` — clear all tracked errors.

  Typical usage is inside a form or screen component where you need to
  reactively display errors and provide ways to dismiss them:

  ## Supported Screens

  * The `useErrors` hook is available on every ACUL screen.

  ```tsx Example theme={null}
  import { useErrors } from "@auth0/auth0-acul-react";

  export function SignupForm() {
    const { errors, hasError, dismiss, dismissAll } = useErrors();

    return (
      <div>
        {hasError && (
          <div className="mb-4">
            {errors.byKind("server").map(err => (
              <div key={err.id} className="text-red-600">
                {err.message}
                <button onClick={() => dismiss(err.id)}>Dismiss</button>
              </div>
            ))}
          </div>
        )}

        <button onClick={dismissAll}>Clear All Errors</button>
      </div>
    );
  }
  ```

  In addition to rendering messages, you can filter by field or kind:

  ```ts theme={null}
  console.log(errors.byKind('client')); // all client errors
  console.log(errors.byKind('client', { field: 'username' })); // client errors for field 'username'
  console.log(errors.byField('username')); // all errors for field 'username'
  console.log(errors.byField('username', { kind: 'server' })); // server errors for field 'username'
  ```

  <Expandable title="Parameters">
    <ParamField type={<span><a href='/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UseErrorOptions'>[UseErrorOptions]</a> = {}</span>}>
      **Properties**

      <ParamField type="boolean" />
    </ParamField>
  </Expandable>
</ParamField>


# useLoginIdentifiers
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Hooks/useLoginIdentifiers



<ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/type-aliases/IdentifierType">IdentifierType[]</a></span>}>
  Returns a list of active identifier types (such as `'email'`, `'phone'`, or `'username'`)
  currently in use in the authentication flow or login process.

  ## Returns

  [`IdentifierType`](/docs/libraries/acul/react-sdk/API-Reference/Types/type-aliases/IdentifierType)\[]

  An array of [IdentifierType](/docs/libraries/acul/react-sdk/API-Reference/Types/type-aliases/IdentifierType) representing active identifiers.

  ## Supported Screens

  * `login`
  * `login-id`
  * `reset-password-request`

  ```tsx Example theme={null}
  import { useLoginIdentifiers } from '@auth0/auth0-acul-react/login';

  const loginIdentifiers = useLoginIdentifiers();
  const hasEmail = loginIdentifiers.includes('email');
  const hasPhone = loginIdentifiers.includes('phone');
  const hasUsername = loginIdentifiers.includes('username');

  // loginIdentifiers could be:
  // ['email', 'username']
  ```
</ParamField>


# useMfaPolling
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Hooks/useMfaPolling



<ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaPollingResult">MfaPollingResult</a></span>}>
  React hook to manage MFA push polling (e.g., waiting for a push notification approval)
  on an Auth0 Advanced Customization of Universal Login (ACUL) screen.

  This hook sets up and controls a long-running polling loop that repeatedly checks
  the MFA push challenge endpoint until one of the following occurs:

  * The challenge is **approved or denied** by the user, triggering `options.onCompleted`.
  * An **error** occurs (network error, non-200/429 response), triggering `options.onError`.
  * The **component unmounts** or `stopPolling()` is called, which cancels polling.

  ### Key Features

  * `isRunning` is **reactive** — it updates automatically if the polling loop
    stops internally or is canceled.
  * Uses a **stable single polling instance** (`useRef`) to prevent
    duplicate network calls and unintended restarts during React re-renders.
  * **Automatic cleanup** on unmount: no orphan timers or leaked XHR requests.

  ## Parameters

  <ParamField type={<span><a href='/docs/libraries/acul/react-sdk/API-Reference/Types/type-aliases/MfaPollingOptions'>MfaPollingOptions</a></span>}>
    [MfaPollingOptions](/docs/libraries/acul/react-sdk/API-Reference/Types/type-aliases/MfaPollingOptions) specifying the polling interval, success callback (`onCompleted`), and optional error handler (`onError`).
  </ParamField>

  ## Returns

  [`MfaPollingResult`](/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaPollingResult)

  object [MfaPollingResult](/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaPollingResult) containing:

  * `isRunning` — `true` while polling is active.
  * `startPolling()` — starts or resumes polling.
  * `stopPolling()` — stops polling immediately.

  ## Supported Screens

  * `mfa-push-challenge-push`
  * `reset-password-mfa-push-challenge-push`
  * `mfa-push-enrollment-qr`

  ```tsx Example theme={null}
  import { useMfaPolling } from '@auth0/auth0-acul-react/mfa-push-challenge-push';

  export function MfaPushStatus() {
    const { isRunning, startPolling, stopPolling } = useMfaPolling({
      intervalMs: 5000,
      onCompleted: () => console.log('Push approved!/denied'),
      onError: (error) => console.error('Polling error:', error)
    });

    return (
      <div>
        <button onClick={startPolling} disabled={isRunning}>
          {isRunning ? 'Waiting for approval…' : 'Start MFA Polling'}
        </button>
        {isRunning && <button onClick={stopPolling}>Cancel</button>}
      </div>
    );
  }
  ```

  ## Remarks

  * The `onError` callback receives an [ULError](/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/Error) object
    with `status` and `responseText` describing the server response.
  * Internal rate-limit responses (`429`) are automatically handled:
    polling waits for the reset window before retrying.
  * Calling `startPolling()` repeatedly while running is safe and idempotent.
</ParamField>


# usePasswordValidation
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Hooks/usePasswordValidation



<ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PasswordValidationResult">PasswordValidationResult</a></span>}>
  This React hook validates a password against the current Auth0 password policy
  and returns a structured result describing whether the password satisfies each rule.

  Optionally, it can send the validation results to the global error manager so that
  form error components can update automatically.

  ## Parameters

  <ParamField type="string">
    The password to validate.
  </ParamField>

  <ParamField />

  <ParamField type="boolean">
    If `true`, validation errors are stored in the global error manager under the `password` field. Defaults to `false`.
  </ParamField>

  ## Returns

  [`PasswordValidationResult`](/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PasswordValidationResult)

  A [PasswordValidationResult](/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PasswordValidationResult) object containing:

  * `isValid` — `true` if the password satisfies all configured rules.
  * `results` — an array of per-rule results with `code`, `label`, `status`, and `isValid`.

  ## Supported Screens

  * `signup`
  * `signup-password`
  * `reset-password`

  ```tsx Example theme={null}
     import { usePasswordValidation } from '@auth0/auth0-acul-react/signup';
     const { isValid, results} = usePasswordValidation(password, { includeInErrors: true });

     if (!isValid) {
       console.log(results);
     }
  ```
</ParamField>


# useResend
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Hooks/useResend



<ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UseResendReturn">UseResendReturn</a></span>}>
  This React hook manages "resend" actions (e.g., resending a verification code) on ACUL screens.

  This hook:

  * Tracks the remaining cooldown time.
  * Tells you whether the resend button should be disabled.
  * Provides a `startResend` function to trigger a resend immediately.

  ## Parameters

  <ParamField type={<span><a href='/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UseResendOptions'>UseResendOptions</a></span>}>
    Optional configuration such as `timeoutSeconds` and `onTimeout`.
  </ParamField>

  ## Returns

  [`UseResendReturn`](/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UseResendReturn)

  An object with:

  * `remaining` — seconds left until the next resend is permitted.
  * `disabled` — `true` if resending is currently blocked.
  * `startResend` — call to initiate a resend immediately (if allowed).

  ## Supported Screens

  * `email-identifier-challenge`
  * `email-otp-challenge`
  * `login-email-verification`
  * `login-passwordless-email-code`
  * `login-passwordless-sms-otp`
  * `mfa-email-challenge`
  * `mfa-sms-challenge`
  * `mfa-voice-challenge`
  * `phone-identifier-challenge`
  * `reset-password-mfa-email-challenge`
  * `reset-password-mfa-sms-challenge`
  * `reset-password-mfa-voice-challenge`

  ```tsx Example theme={null}
  import { useResend } from '@auth0/auth0-acul-react/mfa-sms-challenge';

  export function ResendButton() {
    const { remaining, disabled, startResend } = useResend({
      timeoutSeconds: 30,
      onTimeout: () => console.log('You can resend again'),
    });

    return (
      <button onClick={startResend} disabled={disabled}>
        {disabled ? `Resend in ${remaining}s` : 'Resend Code'}
      </button>
    );
  }
  ```

  ## Remarks

  * The underlying `ResendControl` has no explicit teardown method; the hook does not require manual cleanup.
  * The hook re-initializes the resend manager if `timeoutSeconds` or `onTimeout` change.
</ParamField>


# useSignupIdentifiers
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Hooks/useSignupIdentifiers



<ParamField type={<span>[] | <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/Identifier">Identifier[]</a></span>}>
  Returns a list of enabled identifiers (email, phone, or username), each with its `required` status,
  based on the current screen's signup identifiers.

  ## Returns

  \[] | [`Identifier`](/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/Identifier)\[]

  An array of [Identifier](/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/Identifier) objects, where each contains a `type` (identifier type)
  and a `required` flag indicating whether it is mandatory for signup.

  ## Supported Screens

  * `signup`
  * `signup-id`

  ```tsx Example theme={null}
  import { useSignupIdentifiers } from '@auth0/auth0-acul-react/signup';

  const identifiers = useSignupIdentifiers();
  const emailIdentifier = identifiers.find(({ type }) => type === 'email');
  const phoneIdentifier = identifiers.find(({ type }) => type === 'phone');
  const usernameIdentifier = identifiers.find(({ type }) => type === 'username');

  const emailRequired = emailIdentifier?.required ?? false;
  const phoneRequired = phoneIdentifier?.required ?? false;
  const usernameRequired = usernameIdentifier?.required ?? false;

  // Example output:
  // [
  //   { type: 'email', required: true },
  //   { type: 'phone', required: false },
  //   { type: 'username', required: true },
  // ]
  ```
</ParamField>


# useUsernameValidation
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Hooks/useUsernameValidation



<ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UsernameValidationResult">UsernameValidationResult</a></span>}>
  > **useUsernameValidation**(`username`, `options?`): [`UsernameValidationResult`](/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UsernameValidationResult)

  React hook for validating a username against the current Auth0 username policy.

  This hook checks the provided username against all configured validation rules
  and returns a structured result describing whether it passes.
  Optionally, it can send validation errors to the global error manager so that
  UI components observing the `username` field can automatically display or react
  to these errors.

  ## Parameters

  <ParamField type="string">
    The username string to validate.
  </ParamField>

  <ParamField />

  <ParamField type="boolean">
    When `true`, validation errors are stored in the global error manager under the `username` field. Defaults to `false`.
  </ParamField>

  ## Returns

  [`UsernameValidationResult`](/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UsernameValidationResult)

  A [UsernameValidationResult](/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UsernameValidationResult) object with:

  * `isValid` — `true` if the username satisfies all configured rules.
  * `errors` — an array of per-rule validation errors with `code`, `message`, and `isValid`.

  ## Supported Screens

  * `signup`
  * `signup-id`

  ```tsx Example theme={null}
  import { useUsernameValidation } from "@auth0/auth0-acul-react/signup";

  export function UsernameField() {
    const { isValid, errors } = useUsernameValidation(username, { includeInErrors: true });

    return (
      <div>
        <input
          value={username}
          onChange={e => setUsername(e.target.value)}
          aria-invalid={!isValid}
        />

        {!isValid && (
          <ul>
            {errors.map(err => (
              <li key={err.code}>{err.message}</li>
            ))}
          </ul>
        )}
      </div>
    );
  }
  ```

  ## Remarks

  * When `includeInErrors` is enabled, the hook automatically updates the errors to the error-store which can be consumed by `useErrors` hook.
  * The hook only recomputes when `username` or `options.includeInErrors` change.
</ParamField>


# AcceptInvitation
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/accept-invitation/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from 'react';
import {
  useAcceptInvitation,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData
} from '@auth0/auth0-acul-react/accept-invitation';
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnAcceptInvitation">ScreenMembersOnAcceptInvitation</a></span>}>
  Hook to access current screen information and metadata.

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/AcceptInvitationMembers">AcceptInvitationMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# Consent
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/consent/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useConsent,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/consent";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnConsent">ScreenMembersOnConsent</a></span>}>
  Hook to access current screen information and metadata.

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ConsentMembers">ConsentMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# CustomizedConsent
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/customized-consent/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useCustomizedConsent,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/customized-consent";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnCustomizedConsent">ScreenMembersOnCustomizedConsent</a></span>}>
  Hook to access current screen information and metadata.

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomizedConsentMembers">CustomizedConsentMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# DeviceCodeActivationAllowed
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/device-code-activation-allowed/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useDeviceCodeActivationAllowed,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/device-code-activation-allowed";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Hook to access current screen information and metadata.

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/DeviceCodeActivationAllowedMembers">DeviceCodeActivationAllowedMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# DeviceCodeActivationDenied
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/device-code-activation-denied/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useDeviceCodeActivationDenied,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/device-code-activation-denied";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Hook to access current screen information and metadata.

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/DeviceCodeActivationDeniedMembers">DeviceCodeActivationDeniedMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# DeviceCodeActivation
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/device-code-activation/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useDeviceCodeActivation,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/device-code-activation";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Hook to access current screen information and metadata.

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/DeviceCodeActivationContinueOptions">DeviceCodeActivationContinueOptions</a></span>}>
      **Properties**

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/DeviceCodeActivationMembers">DeviceCodeActivationMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# DeviceCodeConfirmation
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/device-code-confirmation/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useDeviceCodeConfirmation,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/device-code-confirmation";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnDeviceCodeConfirmation">ScreenMembersOnDeviceCodeConfirmation</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/DeviceCodeConfirmationMembers">DeviceCodeConfirmationMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# EmailIdentifierChallenge
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/email-identifier-challenge/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useEmailIdentifierChallenge,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/email-identifier-challenge";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnEmailIdentifierChallenge">ScreenMembersOnEmailIdentifierChallenge</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/EmailChallengeOptions">EmailChallengeOptions</a></span>}>
      **Properties**

      <ParamField type="string" />

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/EmailIdentifierChallengeMembers">EmailIdentifierChallengeMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# EmailOtpChallenge
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/email-otp-challenge/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useEmailOTPChallenge,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/email-otp-challenge";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnEmailOTPChallenge">ScreenMembersOnEmailOTPChallenge</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OtpCodeOptions">OtpCodeOptions</a></span>}>
      **Properties**

      <ParamField type="string">
        The OTP code that the user enters to submit.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/EmailOTPChallengeMembers">EmailOTPChallengeMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# EmailVerificationResult
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/email-verification-result/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useEmailVerificationResult,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/email-verification-result";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnEmailVerificationResult">ScreenMembersOnEmailVerificationResult</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/EmailVerificationResultMembers">EmailVerificationResultMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# InterstitialCaptcha
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/interstitial-captcha/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useInterstitialCaptcha,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/interstitial-captcha";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Hook to access current screen information and metadata.

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/InterstitialCaptchaMembers">InterstitialCaptchaMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# LoginEmailVerification
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/login-email-verification/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useLoginEmailVerification,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/login-email-verification";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Hook to access current screen information and metadata.

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ContinueWithCodeOptionPayload">ContinueWithCodeOptionPayload</a></span>}>
      **Properties**

      <ParamField type="string">
        The verification code sent to the user's email. This is typically a short numeric
        or alphanumeric string that the user must enter into the form.

        <CodeGroup>
          ```ts Example 1 theme={null}
          "123456"
          ```

          ```ts Example 2 theme={null}
          "ABCXYZ"
          ```
        </CodeGroup>
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResendCodeOptionsPayload">ResendCodeOptionsPayload</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/LoginEmailVerificationMembers">LoginEmailVerificationMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# LoginId
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/login-id/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from 'react';
import {
  useLoginId,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData
} from '@auth0/auth0-acul-react/login-id';
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnLoginId">ScreenMembersOnLoginId</a></span>}>
  Hook to access current screen information and metadata.

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembersOnLoginId">TransactionMembersOnLoginId</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/FederatedLoginOptions">FederatedLoginOptions</a></span>}>
      **Properties**

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/LoginOptions">LoginOptions</a></span>}>
      **Properties**

      <ParamField type="string" />

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/LoginIdMembers">LoginIdMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# LoginPassword
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/login-password/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import { useScreen, useTransaction, login, useErrors } from "@auth0/auth0-acul-react/login-password";
import { Logo } from "../../components/Logo";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnLoginPassword">ScreenMembersOnLoginPassword</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembersOnLoginPassword">TransactionMembersOnLoginPassword</a></span>}>
  Hook to access transaction state and authentication flow data.

  Transaction object containing flow state, session data, and transaction-specific information

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/FederatedLoginPasswordOptions">FederatedLoginPasswordOptions</a></span>}>
      **Properties**

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/LoginPasswordOptions">LoginPasswordOptions</a></span>}>
      **Properties**

      <ParamField type="string" />

      <ParamField type="string" />

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/LoginPasswordMembers">LoginPasswordMembers</a>}>
  <Expandable title="Parameters">
    **Properties**

    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
      **Properties**

      <ParamField type={<span><a href="#BrandingSettings">BrandingSettings</a></span>} />

      <ParamField type={<span><a href="#BrandingThemes">BrandingThemes</a></span>} />

      ## BrandingSettings

      ```ts theme={null}
      export interface BrandingSettings {
        colors?: {
          primary?: string;
          pageBackground?:
            | string
            | {
                type: string;
                start: string;
                end: string;
                angleDegree: number;
              };
        };
        faviconUrl?: string;
        logoUrl?: string;
        fontUrl?: string;
      }
      ```

      ### Properties

      <ParamField type="object">
        <Expandable title="properties">
          <ParamField type="string | { angleDegree: number; end: string; start: string; type: string; }" />

          <ParamField type="string" />
        </Expandable>
      </ParamField>

      <ParamField type="string" />

      <ParamField type="string" />

      <ParamField type="string" />

      ## BrandingThemes

      ```ts theme={null}
      export interface BrandingThemes {
        default: {
          borders: Record<string, string | boolean | number>;
          colors: Record<string, string>;
          displayName: string;
          fonts: Record<string, string | boolean | object>;
          pageBackground: Record<string, string>;
          widget: Record<string, string | number>;
        };
      }
      ```

      ### Properties

      <ParamField type="object">
        <Expandable title="properties">
          <ParamField type="Record<string, string | boolean | number>" />

          <ParamField type="Record<string, string>" />

          <ParamField type="string" />

          <ParamField type="Record<string, string | boolean | object>" />

          <ParamField type="Record<string, string>" />

          <ParamField type="Record<string, string | number>" />
        </Expandable>
      </ParamField>
    </ParamField>

    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
      **Properties**

      <ParamField type="string" />

      <ParamField type="string" />

      <ParamField type="string" />

      <ParamField type="{[key: string]: string; }" />

      <ParamField type="string" />
    </ParamField>

    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
      **Properties**

      <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/Branding">Branding</a></span>} />

      <ParamField type="string" />

      <ParamField type="string" />

      <ParamField type="{[key: string]: string; }" />

      <ParamField type="string" />

      <ParamField type="string" />
    </ParamField>

    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
      **Properties**

      <ParamField type="string" />
    </ParamField>

    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnLoginPassword">ScreenMembersOnLoginPassword</a></span>}>
      **Properties**

      <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CaptchaContext">CaptchaContext</a></span>} />

      <ParamField type="string" />

      <ParamField type="string" />

      <ParamField type="string" />

      <ParamField type="username" />

      <ParamField type="string" />

      <ParamField type="boolean" />

      <ParamField type="Record" />

      <ParamField type="string" />

      <ParamField type="string" />

      <ParamField type="string" />

      <ParamField type="Record" />
    </ParamField>

    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
      **Properties**

      <ParamField type="string[]" />

      <ParamField type="string[]" />

      <ParamField type="string" />

      <ParamField type="string" />
    </ParamField>

    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembersOnLoginPassword">TransactionMembersOnLoginPassword</a></span>}>
      **Properties**

      <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/Connection">Connection</a></span>} />

      <ParamField type="string" />

      <ParamField type="string" />

      <ParamField type="string" />

      <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/Connection">Connection</a></span>} />

      <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/Error">Error</a></span>} />

      <ParamField type="boolean" />

      <ParamField type="boolean" />

      <ParamField type="boolean" />

      <ParamField type="boolean" />

      <ParamField type="string" />

      <ParamField type="string" />

      ## Methods

      <ParamField type={<span><a href="/docs-v2/main//docs/libraries/acul/react-sdkScreens/type-aliases/IdentifierType">IdentifierType</a>[]</span>} />

      <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PasswordPolicy">PasswordPolicy</a></span>} />

      <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UsernamePolicy">UsernamePolicy</a></span>} />
    </ParamField>

    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
      **Properties**

      <ParamField type="{ [key:  ext-${string} ]: string; login_hint?: string; screen_hint?: string; ui_locales?: string; }" />

      <ParamField type="{[key: string]: string | number | boolean | null | undefined; }" />
    </ParamField>

    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
      **Properties**

      <ParamField type="{[key: string]: string; }" />

      <ParamField type="string" />

      <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/EnrolledDevice">EnrolledDevice</a></span>} />

      <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/EnrolledEmail">EnrolledEmail</a></span>} />

      <ParamField type="string[]" />

      <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/EnrolledPhoneNumber">EnrolledPhoneNumber</a></span>} />

      <ParamField type="string" />

      <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/Organizations">Organizations</a></span>} />

      <ParamField type="string" />

      <ParamField type="string" />

      <ParamField type="{[key: string]: string; }" />

      <ParamField type="string" />
    </ParamField>

    **Methods**

    <ParamField type="Promise<void>">
      <Expandable title="Parameters">
        <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/FederatedLoginPasswordOptions">FederatedLoginPasswordOptions</a></span>}>
          **Properties**

          <ParamField type="string" />
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="Promise<void>">
      <Expandable title="Parameters">
        <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/LoginPasswordOptions">LoginPasswordOptions</a></span>}>
          **Properties**

          <ParamField type="string" />

          <ParamField type="string" />

          <ParamField type="string" />
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# LoginPasswordlessEmailCode
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/login-passwordless-email-code/index



<Frame>
  <img alt="Login Passwordless Email Code" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useLoginPasswordlessEmailCode,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/login-passwordless-email-code";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnLoginPasswordlessEmailCode">ScreenMembersOnLoginPasswordlessEmailCode</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembersOnLoginPasswordlessEmailCode">TransactionMembersOnLoginPasswordlessEmailCode</a></span>}>
  Hook to access transaction state and authentication flow data.

  Transaction object containing flow state, session data, and transaction-specific information

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/SubmitCodeOptions">SubmitCodeOptions</a></span>}>
      **Properties**

      <ParamField type="string" />

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/LoginPasswordlessEmailCodeMembers">LoginPasswordlessEmailCodeMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# LoginPasswordlessSmsOtp
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/login-passwordless-sms-otp/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useLoginPasswordlessSmsOtp,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/login-passwordless-sms-otp";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnLoginPasswordlessSmsOtp">ScreenMembersOnLoginPasswordlessSmsOtp</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembersOnLoginPasswordlessSmsOtp">TransactionMembersOnLoginPasswordlessSmsOtp</a></span>}>
  Hook to access transaction state and authentication flow data.

  Transaction object containing flow state, session data, and transaction-specific information

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/SubmitOTPOptions">SubmitOTPOptions</a></span>}>
      **Properties**

      <ParamField type="string" />

      <ParamField type="string" />

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/LoginPasswordlessSmsOtpMembers">LoginPasswordlessSmsOtpMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# Login
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/login/index



<Frame>
  <img alt="ACUL Login" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useLogin,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/login";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnLogin">ScreenMembersOnLogin</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembersOnLogin">TransactionMembersOnLogin</a></span>}>
  Hook to access transaction state and authentication flow data.

  Transaction object containing flow state, session data, and transaction-specific information

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/FederatedLoginPayloadOptions">FederatedLoginPayloadOptions</a></span>}>
      **Properties**

      <ParamField type="string">
        The social connection name to use
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/LoginPayloadOptions">LoginPayloadOptions</a></span>}>
      **Properties**

      <ParamField type="string">
        Optional captcha value if required
      </ParamField>

      <ParamField type="string">
        The password for authentication
      </ParamField>

      <ParamField type="string">
        The username/email to login with
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/LoginMembers">LoginMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# LogoutAborted
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/logout-aborted/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useLogoutAborted,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/logout-aborted";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Hook to access current screen information and metadata.

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/LogoutAbortedMembers">LogoutAbortedMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# LogoutComplete
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/logout-complete/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useLogoutComplete,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/logout-complete";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Hook to access current screen information and metadata.

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/LogoutCompleteMembers">LogoutCompleteMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# Logout
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/logout/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useLogout,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/logout";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Hook to access current screen information and metadata.

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ConfirmLogoutOptions">ConfirmLogoutOptions</a></span>}>
      **Properties**

      <ParamField type="&#x22;accept&#x22;">
        The authentication transaction state
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/LogoutMembers">LogoutMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaBeginEnrollOptions
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-begin-enroll-options/index



<Frame>
  <img alt="undefined" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaBeginEnrollOptions,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-begin-enroll-options";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Hook to access current screen information and metadata.

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaEnrollOptions">MfaEnrollOptions</a></span>}>
      **Properties**

      <ParamField type={<span><a href="/docs-v2/main//docs/libraries/acul/react-sdkScreens/type-aliases/MfaEnrollFactorType">MfaEnrollFactorType</a></span>}>
        The action indicating which factor to enroll
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaBeginEnrollOptionsMembers">MfaBeginEnrollOptionsMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaCountryCodes
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-country-codes/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaCountryCodes,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-country-codes";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnMfaCountryCodes">ScreenMembersOnMfaCountryCodes</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/SelectCountryCodeOptions">SelectCountryCodeOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaCountryCodesMembers">MfaCountryCodesMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaDetectBrowserCapabilities
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-detect-browser-capabilities/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaDetectBrowserCapabilities,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-detect-browser-capabilities";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Hook to access current screen information and metadata.

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaDetectBrowserCapabilitiesMembers">MfaDetectBrowserCapabilitiesMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaEmailChallenge
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-email-challenge/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaEmailChallenge,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-email-challenge";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnMfaEmailChallenge">ScreenMembersOnMfaEmailChallenge</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembersOnMfaEmailChallenge">UntrustedDataMembersOnMfaEmailChallenge</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  Object containing untrusted user input that should be validated before use

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ContinuePayloadOptions">ContinuePayloadOptions</a></span>}>
      **Properties**

      <ParamField type="string">
        The code entered by the user
      </ParamField>

      <ParamField type="boolean">
        Indicates whether to remember the device
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResendCodePayloadOptions">ResendCodePayloadOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TryAnotherMethodPayloadOptions">TryAnotherMethodPayloadOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaEmailChallengeMembers">MfaEmailChallengeMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaEmailList
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-email-list/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaEmailList,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-email-list";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnMfaEmailList">ScreenMembersOnMfaEmailList</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/SelectMfaEmailOptions">SelectMfaEmailOptions</a></span>}>
      **Properties**

      <ParamField type="number">
        The index of the phone number to select.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaEmailListMembers">MfaEmailListMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaEnrollResult
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-enroll-result/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaEnrollResult,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-enroll-result";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnMfaEnrollResult">ScreenMembersOnMfaEnrollResult</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaEnrollResultMembers">MfaEnrollResultMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaLoginOptions
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-login-options/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaLoginOptions,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-login-options";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnMfaLoginOptions">ScreenMembersOnMfaLoginOptions</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/LoginEnrollOptions">LoginEnrollOptions</a></span>}>
      **Properties**

      <ParamField type={<span><a href="/docs-v2/main//docs/libraries/acul/react-sdkScreens/type-aliases/MfaLoginFactorType">MfaLoginFactorType</a></span>}>
        The action indicating which factor to use for login
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaLoginOptionsMembers">MfaLoginOptionsMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaOtpChallenge
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-otp-challenge/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaOtpChallenge,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-otp-challenge";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnMfaOtpChallenge">ScreenMembersOnMfaOtpChallenge</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembersOnMfaOtpChallenge">UntrustedDataMembersOnMfaOtpChallenge</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  Object containing untrusted user input that should be validated before use

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ContinueOTPOptions">ContinueOTPOptions</a></span>}>
      **Properties**

      <ParamField type="string">
        The code entered by the user
      </ParamField>

      <ParamField type="boolean">
        Indicates whether to remember the browser
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TryAnotherMethodMfaOtpChallengeOptions">TryAnotherMethodMfaOtpChallengeOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaOtpChallengeMembers">MfaOtpChallengeMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaOtpEnrollmentCode
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-otp-enrollment-code/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaOtpEnrollmentCode,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-otp-enrollment-code";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnMfaOtpEnrollmentCode">ScreenMembersOnMfaOtpEnrollmentCode</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaOtpContinueOptions">MfaOtpContinueOptions</a></span>}>
      **Properties**

      <ParamField type="string">
        The OTP code entered by the user.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaOtpTryAnotherMethodOptions">MfaOtpTryAnotherMethodOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaOtpEnrollmentCodeMembers">MfaOtpEnrollmentCodeMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaOtpEnrollmentQr
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-otp-enrollment-qr/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaOtpEnrollmentQr,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-otp-enrollment-qr";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnMfaOtpEnrollmentQr">ScreenMembersOnMfaOtpEnrollmentQr</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaOtpEnrollmentQrContinueOptions">MfaOtpEnrollmentQrContinueOptions</a></span>}>
      **Properties**

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaOtpEnrollmentQrMembers">MfaOtpEnrollmentQrMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaPhoneChallenge
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-phone-challenge/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaPhoneChallenge,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-phone-challenge";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnMfaPhoneChallenge">ScreenMembersOnMfaPhoneChallenge</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaPhoneChallengeContinueOptions">MfaPhoneChallengeContinueOptions</a></span>}>
      **Properties**

      <ParamField type="&#x22;sms&#x22; | &#x22;voice&#x22;">
        The type of challenge to perform.
        'sms': Send the code via text message.
        'voice': Send the code via a voice call.

        #### Default

        ```ts theme={null}
        'sms'
        ```
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaPhoneChallengePickPhoneOptions">MfaPhoneChallengePickPhoneOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaPhoneChallengePickAuthenticatorOptions">MfaPhoneChallengePickAuthenticatorOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaPhoneChallengeMembers">MfaPhoneChallengeMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaPhoneEnrollment
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-phone-enrollment/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaPhoneEnrollment,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-phone-enrollment";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Hook to access current screen information and metadata.

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaPhoneEnrollmentContinueOptions">MfaPhoneEnrollmentContinueOptions</a></span>}>
      **Properties**

      <ParamField type="string" />

      <ParamField type="&#x22;sms&#x22; | &#x22;voice&#x22;" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaPhoneEnrollmentMembers">MfaPhoneEnrollmentMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaPushChallengePush
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-push-challenge-push/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaPushChallengePush,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-push-challenge-push";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnMfaPushChallengePush">ScreenMembersOnMfaPushChallengePush</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembersOnMfaPushChallengePush">UntrustedDataMembersOnMfaPushChallengePush</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  Object containing untrusted user input that should be validated before use

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/WithRememberOptions">WithRememberOptions</a></span>}>
      **Properties**

      <ParamField type="boolean" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/WithRememberOptions">WithRememberOptions</a></span>}>
      **Properties**

      <ParamField type="boolean" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaPushChallengePushMembers">MfaPushChallengePushMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaPushEnrollmentQr
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-push-enrollment-qr/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaPushEnrollmentQr,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-push-enrollment-qr";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnMfaPushEnrollmentQr">ScreenMembersOnMfaPushEnrollmentQr</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaPushEnrollmentQrMembers">MfaPushEnrollmentQrMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaPushList
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-push-list/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaPushList,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-push-list";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Hook to access current screen information and metadata.

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/SelectMfaPushDeviceOptions">SelectMfaPushDeviceOptions</a></span>}>
      **Properties**

      <ParamField type="number">
        The index of the device to select from the list of enrolled devices.
        The index is 0-based.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaPushListMembers">MfaPushListMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaPushWelcome
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-push-welcome/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaPushWelcome,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-push-welcome";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnMfaPushWelcome">ScreenMembersOnMfaPushWelcome</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaPushWelcomeMembers">MfaPushWelcomeMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaRecoveryCodeChallengeNewCode
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-recovery-code-challenge-new-code/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaRecoveryCodeChallengeNewCode,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-recovery-code-challenge-new-code";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnMfaRecoveryCodeChallengeNewCode">ScreenMembersOnMfaRecoveryCodeChallengeNewCode</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaRecoveryCodeChallengeNewCodeContinueOptions">MfaRecoveryCodeChallengeNewCodeContinueOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaRecoveryCodeChallengeNewCodeMembers">MfaRecoveryCodeChallengeNewCodeMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaRecoveryCodeChallenge
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-recovery-code-challenge/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaRecoveryCodeChallenge,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-recovery-code-challenge";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Hook to access current screen information and metadata.

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaRecoveryCodeChallengeContinueOptions">MfaRecoveryCodeChallengeContinueOptions</a></span>}>
      **Properties**

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaRecoveryCodeChallengeMembers">MfaRecoveryCodeChallengeMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaRecoveryCodeEnrollment
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-recovery-code-enrollment/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaRecoveryCodeEnrollment,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-recovery-code-enrollment";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnMfaRecoveryCodeEnrollment">ScreenMembersOnMfaRecoveryCodeEnrollment</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaRecoveryCodeEnrollmentContinueOptions">MfaRecoveryCodeEnrollmentContinueOptions</a></span>}>
      **Properties**

      <ParamField type="boolean" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaRecoveryCodeEnrollmentMembers">MfaRecoveryCodeEnrollmentMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaSmsChallenge
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-sms-challenge/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaSmsChallenge,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-sms-challenge";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnMfaSmsChallenge">ScreenMembersOnMfaSmsChallenge</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembersOnMfaSmsChallenge">UntrustedDataMembersOnMfaSmsChallenge</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  Object containing untrusted user input that should be validated before use

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaSmsChallengeOptions">MfaSmsChallengeOptions</a></span>}>
      **Properties**

      <ParamField type="string" />

      <ParamField type="boolean" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaSmsChallengeMembers">MfaSmsChallengeMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaSmsEnrollment
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-sms-enrollment/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaSmsEnrollment,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-sms-enrollment";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnMfaSmsEnrollment">ScreenMembersOnMfaSmsEnrollment</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type="object">
      <Expandable title="Parameters">
        <ParamField type="string" />

        <ParamField type="string" />
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaSmsEnrollmentMembers">MfaSmsEnrollmentMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaSmsList
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-sms-list/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaSmsList,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-sms-list";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Hook to access current screen information and metadata.

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaSmsListOptions">MfaSmsListOptions</a></span>}>
      **Properties**

      <ParamField type="number">
        The index of the phone number to select.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaSmsListMembers">MfaSmsListMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaVoiceChallenge
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-voice-challenge/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaVoiceChallenge,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-voice-challenge";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnMfaVoiceChallenge">ScreenMembersOnMfaVoiceChallenge</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembersOnMfaVoiceChallenge">UntrustedDataMembersOnMfaVoiceChallenge</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  Object containing untrusted user input that should be validated before use

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaVoiceChallengeContinueOptions">MfaVoiceChallengeContinueOptions</a></span>}>
      **Properties**

      <ParamField type="string">
        The verification code received via voice call.
      </ParamField>

      <ParamField type="boolean">
        Optional flag to remember the device for 30 days, skipping future MFA challenges.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaVoiceChallengeMembers">MfaVoiceChallengeMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaVoiceEnrollment
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-voice-enrollment/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaVoiceEnrollment,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-voice-enrollment";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Hook to access current screen information and metadata.

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaVoiceEnrollmentContinueOptions">MfaVoiceEnrollmentContinueOptions</a></span>}>
      **Properties**

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaVoiceEnrollmentMembers">MfaVoiceEnrollmentMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaWebauthnChangeKeyNickname
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-webauthn-change-key-nickname/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaWebAuthnChangeKeyNickname,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-webauthn-change-key-nickname";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnMfaWebAuthnChangeKeyNickname">ScreenMembersOnMfaWebAuthnChangeKeyNickname</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaWebAuthnChangeKeyNicknameContinueOptions">MfaWebAuthnChangeKeyNicknameContinueOptions</a></span>}>
      **Properties**

      <ParamField type="string">
        The new nickname for the WebAuthn security key.
        This is the value entered by the user in the input field.
        It must adhere to length and character constraints defined by the server.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaWebAuthnChangeKeyNicknameMembers">MfaWebAuthnChangeKeyNicknameMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaWebauthnEnrollmentSuccess
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-webauthn-enrollment-success/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaWebAuthnEnrollmentSuccess,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-webauthn-enrollment-success";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnMfaWebAuthnEnrollmentSuccess">ScreenMembersOnMfaWebAuthnEnrollmentSuccess</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/WebAuthnEnrollSuccessContinueOptions">WebAuthnEnrollSuccessContinueOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaWebAuthnEnrollmentSuccessMembers">MfaWebAuthnEnrollmentSuccessMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaWebauthnError
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-webauthn-error/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaWebAuthnError,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-webauthn-error";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnMfaWebAuthnError">ScreenMembersOnMfaWebAuthnError</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaWebAuthnErrorMembers">MfaWebAuthnErrorMembers</a>} />

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaWebauthnNotAvailableError
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-webauthn-not-available-error/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaWebAuthnNotAvailableError,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-webauthn-not-available-error";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Hook to access current screen information and metadata.

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaWebAuthnNotAvailableErrorMembers">MfaWebAuthnNotAvailableErrorMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaWebauthnPlatformChallenge
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-webauthn-platform-challenge/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaWebAuthnPlatformChallenge,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-webauthn-platform-challenge";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnMfaWebAuthnPlatformChallenge">ScreenMembersOnMfaWebAuthnPlatformChallenge</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaWebAuthnPlatformChallengeReportErrorOptions">MfaWebAuthnPlatformChallengeReportErrorOptions</a></span>}>
      **Properties**

      <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/WebAuthnErrorDetails">WebAuthnErrorDetails</a></span>}>
        The error object from the WebAuthn API (`navigator.credentials.get()`) to be reported.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaWebAuthnPlatformChallengeTryAnotherMethodOptions">MfaWebAuthnPlatformChallengeTryAnotherMethodOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaWebAuthnPlatformChallengeMembers">MfaWebAuthnPlatformChallengeMembers</a>} />

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/VerifyPlatformAuthenticatorOptions">VerifyPlatformAuthenticatorOptions</a></span>}>
      **Properties**

      <ParamField type="boolean">
        Optional. If true, attempts to remember the browser for future MFA challenges.
        Corresponds to the `rememberBrowser` form field. This is only applicable if `screen.showRememberDevice` is true.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaWebauthnPlatformEnrollment
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-webauthn-platform-enrollment/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaWebAuthnPlatformEnrollment,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-webauthn-platform-enrollment";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnMfaWebAuthnPlatformEnrollment">ScreenMembersOnMfaWebAuthnPlatformEnrollment</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ReportBrowserErrorOptions">ReportBrowserErrorOptions</a></span>}>
      **Properties**

      <ParamField type="object">
        #### message

        #### name
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/SubmitPasskeyCredentialOptions">SubmitPasskeyCredentialOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaWebAuthnPlatformEnrollmentMembers">MfaWebAuthnPlatformEnrollmentMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaWebauthnRoamingChallenge
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-webauthn-roaming-challenge/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaWebAuthnRoamingChallenge,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-webauthn-roaming-challenge";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnMfaWebAuthnRoamingChallenge">ScreenMembersOnMfaWebAuthnRoamingChallenge</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaWebAuthnRoamingChallengeReportErrorOptions">MfaWebAuthnRoamingChallengeReportErrorOptions</a></span>}>
      **Properties**

      <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/WebAuthnErrorDetails">WebAuthnErrorDetails</a></span>}>
        The error object from the WebAuthn API to be reported.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaWebAuthnRoamingChallengeTryAnotherMethodOptions">MfaWebAuthnRoamingChallengeTryAnotherMethodOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaWebAuthnRoamingChallengeMembers">MfaWebAuthnRoamingChallengeMembers</a>} />

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/VerifySecurityKeyOptions">VerifySecurityKeyOptions</a></span>}>
      **Properties**

      <ParamField type="boolean">
        Optional. If true, attempts to remember the browser for future MFA challenges.
        Corresponds to the `rememberBrowser` form field.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# MfaWebauthnRoamingEnrollment
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/mfa-webauthn-roaming-enrollment/index



```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useMfaWebAuthnRoamingEnrollment,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/mfa-webauthn-roaming-enrollment";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnMfaWebAuthnRoamingEnrollment">ScreenMembersOnMfaWebAuthnRoamingEnrollment</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ShowErrorOptions">ShowErrorOptions</a></span>}>
      **Properties**

      <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/WebAuthnErrorDetails">WebAuthnErrorDetails</a></span>}>
        The details of the WebAuthn error.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaWebAuthnRoamingEnrollmentTryAnotherMethodOptions">MfaWebAuthnRoamingEnrollmentTryAnotherMethodOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/MfaWebAuthnRoamingEnrollmentMembers">MfaWebAuthnRoamingEnrollmentMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# OrganizationPicker
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/organization-picker/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useOrganizationPicker,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/organization-picker";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Hook to access current screen information and metadata.

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type="string" />

    <ParamField type="string" />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationPickerMembers">OrganizationPickerMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# OrganizationSelection
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/organization-selection/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useOrganizationSelection,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/organization-selection";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnOrganizationSelection">ScreenMembersOnOrganizationSelection</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ContinueWithOrganizationNameOptions">ContinueWithOrganizationNameOptions</a></span>}>
      **Properties**

      <ParamField type="string">
        The organization name.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationSelectionMembers">OrganizationSelectionMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# PasskeyEnrollmentLocal
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/passkey-enrollment-local/index



<Frame>
  <img alt="Passkey Enrollment Local" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  usePasskeyEnrollmentLocal,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/passkey-enrollment-local";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnPasskeyEnrollmentLocal">ScreenMembersOnPasskeyEnrollmentLocal</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/AbortEnrollmentOptions">AbortEnrollmentOptions</a></span>}>
      **Properties**

      <ParamField type="boolean" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PasskeyEnrollmentLocalMembers">PasskeyEnrollmentLocalMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# PasskeyEnrollment
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/passkey-enrollment/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  usePasskeyEnrollment,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/passkey-enrollment";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnPasskeyEnrollment">ScreenMembersOnPasskeyEnrollment</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PasskeyEnrollmentMembers">PasskeyEnrollmentMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# PhoneIdentifierChallenge
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/phone-identifier-challenge/index



<Frame>
  <img alt="undefined" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  usePhoneIdentifierChallenge,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/phone-identifier-challenge";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnPhoneIdentifierChallenge">ScreenMembersOnPhoneIdentifierChallenge</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PhoneChallengeOptions">PhoneChallengeOptions</a></span>}>
      **Properties**

      <ParamField type="string" />

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PhoneIdentifierChallengeMembers">PhoneIdentifierChallengeMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# PhoneIdentifierEnrollment
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/phone-identifier-enrollment/index



<Frame>
  <img alt="PhoneIdentifierEnrollment" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  usePhoneIdentifierEnrollment,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/phone-identifier-enrollment";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnPhoneIdentifierEnrollment">ScreenMembersOnPhoneIdentifierEnrollment</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PhoneEnrollmentOptions">PhoneEnrollmentOptions</a></span>}>
      **Properties**

      <ParamField type="&#x22;voice&#x22;" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PhoneIdentifierEnrollmentMembers">PhoneIdentifierEnrollmentMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# RedeemTicket
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/redeem-ticket/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useRedeemTicket,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/redeem-ticket";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Hook to access current screen information and metadata.

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/RedeemTicketMembers">RedeemTicketMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# ResetPasswordEmail
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/reset-password-email/index



<Frame>
  <img alt="ACUL Reset_password_email" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useResetPasswordEmail,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/reset-password-email";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnResetPasswordEmail">ScreenMembersOnResetPasswordEmail</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordEmailMembers">ResetPasswordEmailMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# ResetPasswordError
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/reset-password-error/index



<Frame>
  <img alt="ACUL reset password error " />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useResetPasswordError,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/reset-password-error";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnResetPasswordError">ScreenMembersOnResetPasswordError</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordErrorMembers">ResetPasswordErrorMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# ResetPasswordMfaEmailChallenge
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/reset-password-mfa-email-challenge/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useResetPasswordMfaEmailChallenge,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/reset-password-mfa-email-challenge";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnResetPasswordMfaEmailChallenge">ScreenMembersOnResetPasswordMfaEmailChallenge</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ContinueOptions">ContinueOptions</a></span>}>
      **Properties**

      <ParamField type="string">
        The code entered by the user.
      </ParamField>

      <ParamField type="boolean">
        Indicates whether to remember the device.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResendCodeOptions">ResendCodeOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TryAnotherMethodOptions">TryAnotherMethodOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordMfaEmailChallengeMembers">ResetPasswordMfaEmailChallengeMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# ResetPasswordMfaOtpChallenge
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/reset-password-mfa-otp-challenge/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useResetPasswordMfaOtpChallenge,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/reset-password-mfa-otp-challenge";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Hook to access current screen information and metadata.

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordMfaOtpChallengeContinueOptions">ResetPasswordMfaOtpChallengeContinueOptions</a></span>}>
      **Properties**

      <ParamField type="string">
        The code entered by the user.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordMfaOtpChallengeTryAnotherMethodOptions">ResetPasswordMfaOtpChallengeTryAnotherMethodOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordMfaOtpChallengeMembers">ResetPasswordMfaOtpChallengeMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# ResetPasswordMfaPhoneChallenge
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/reset-password-mfa-phone-challenge/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useResetPasswordMfaPhoneChallenge,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/reset-password-mfa-phone-challenge";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnResetPasswordMfaPhoneChallenge">ScreenMembersOnResetPasswordMfaPhoneChallenge</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordMfaPhoneChallengeContinueOptions">ResetPasswordMfaPhoneChallengeContinueOptions</a></span>}>
      **Properties**

      <ParamField type="&#x22;sms&#x22; | &#x22;voice&#x22;">
        The delivery method selected by the user for receiving the verification code.

        * `sms`: Send the code via text message.
        * `voice`: Send the code via a voice call.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordMfaPhoneChallengeTryAnotherMethodOptions">ResetPasswordMfaPhoneChallengeTryAnotherMethodOptions</a></span>}>
      **Properties**

      <ParamField type="&#x22;sms&#x22; | &#x22;voice&#x22;">
        The delivery method that was initially presented or selected on the current screen.
        This is required by the API endpoint to correctly process the 'pick-authenticator' action.

        * `sms`: Indicates the current screen was for SMS challenge.
        * `voice`: Indicates the current screen was for Voice challenge.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordMfaPhoneChallengeMembers">ResetPasswordMfaPhoneChallengeMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# ResetPasswordMfaPushChallengePush
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/reset-password-mfa-push-challenge-push/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useResetPasswordMfaPushChallengePush,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/reset-password-mfa-push-challenge-push";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnResetPasswordMfaPushChallengePush">ScreenMembersOnResetPasswordMfaPushChallengePush</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordMfaPushChallengePushMembers">ResetPasswordMfaPushChallengePushMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# ResetPasswordMfaRecoveryCodeChallenge
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/reset-password-mfa-recovery-code-challenge/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useResetPasswordMfaRecoveryCodeChallenge,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/reset-password-mfa-recovery-code-challenge";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembers">ScreenMembers</a></span>}>
  Hook to access current screen information and metadata.

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type="string" />

    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordMfaRecoveryCodeChallengeMembers">ResetPasswordMfaRecoveryCodeChallengeMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# ResetPasswordMfaSmsChallenge
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/reset-password-mfa-sms-challenge/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useResetPasswordMfaSmsChallenge,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/reset-password-mfa-sms-challenge";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnResetPasswordMfaSmsChallenge">ScreenMembersOnResetPasswordMfaSmsChallenge</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordMfaSmsChallengeOptions">ResetPasswordMfaSmsChallengeOptions</a></span>}>
      **Properties**

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordMfaSmsChallengeMembers">ResetPasswordMfaSmsChallengeMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# ResetPasswordMfaVoiceChallenge
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/reset-password-mfa-voice-challenge/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useResetPasswordMfaVoiceChallenge,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/reset-password-mfa-voice-challenge";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnResetPasswordMfaVoiceChallenge">ScreenMembersOnResetPasswordMfaVoiceChallenge</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordMfaVoiceChallengeContinueOptions">ResetPasswordMfaVoiceChallengeContinueOptions</a></span>}>
      **Properties**

      <ParamField type="string">
        The OTP code entered by the user.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordMfaVoiceChallengeMembers">ResetPasswordMfaVoiceChallengeMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# ResetPasswordMfaWebauthnPlatformChallenge
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/reset-password-mfa-webauthn-platform-challenge/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useResetPasswordMfaWebAuthnPlatformChallenge,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/reset-password-mfa-webauthn-platform-challenge";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnResetPasswordMfaWebAuthnPlatformChallenge">ScreenMembersOnResetPasswordMfaWebAuthnPlatformChallenge</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordMfaWebAuthnPlatformChallengeContinueOptions">ResetPasswordMfaWebAuthnPlatformChallengeContinueOptions</a></span>}>
      **Properties**

      <ParamField type="boolean">
        Optional. If `true` and `screen.showRememberDevice` is also `true`,
        this indicates the user has opted to remember the current browser,
        potentially skipping MFA for a period. Corresponds to the `rememberBrowser` form field.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordMfaWebAuthnPlatformChallengeReportErrorOptions">ResetPasswordMfaWebAuthnPlatformChallengeReportErrorOptions</a></span>}>
      **Properties**

      <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/WebAuthnErrorDetails">WebAuthnErrorDetails</a></span>}>
        The error object from the WebAuthn API (`navigator.credentials.get()`)
        to be reported. Must include `name` and `message`.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordMfaWebAuthnPlatformChallengeTryAnotherMethodOptions">ResetPasswordMfaWebAuthnPlatformChallengeTryAnotherMethodOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordMfaWebAuthnPlatformChallengeMembers">ResetPasswordMfaWebAuthnPlatformChallengeMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# ResetPasswordMfaWebauthnRoamingChallenge
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/reset-password-mfa-webauthn-roaming-challenge/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useResetPasswordMfaWebAuthnRoamingChallenge,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/reset-password-mfa-webauthn-roaming-challenge";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnResetPasswordMfaWebAuthnRoamingChallenge">ScreenMembersOnResetPasswordMfaWebAuthnRoamingChallenge</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordMfaWebAuthnRoamingChallengeShowErrorOptions">ResetPasswordMfaWebAuthnRoamingChallengeShowErrorOptions</a></span>}>
      **Properties**

      <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/WebAuthnErrorDetails">WebAuthnErrorDetails</a></span>}>
        The error object from the WebAuthn API (`navigator.credentials.get()`)
        containing `name` and `message` of the DOMException.
      </ParamField>

      <ParamField type="boolean">
        Optional. If `true` and `screen.showRememberDevice` is also `true`,
        the SDK will include `rememberBrowser=true` in the form submission.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordMfaWebAuthnRoamingChallengeTryAnotherMethodOptions">ResetPasswordMfaWebAuthnRoamingChallengeTryAnotherMethodOptions</a></span>}>
      **Properties**

      <ParamField type="boolean">
        Optional. If `true` and `screen.showRememberDevice` is also `true`,
        the SDK will include `rememberBrowser=true` in the form submission.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordMfaWebAuthnRoamingChallengeMembers">ResetPasswordMfaWebAuthnRoamingChallengeMembers</a>} />

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordMfaWebAuthnRoamingChallengeUseSecurityKeyOptions">ResetPasswordMfaWebAuthnRoamingChallengeUseSecurityKeyOptions</a></span>}>
      **Properties**

      <ParamField type="boolean">
        Optional. If `true` and `screen.showRememberDevice` is also `true`,
        the SDK will include `rememberBrowser=true` in the form submission, indicating the user's
        choice to remember this device.
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# ResetPasswordRequest
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/reset-password-request/index



<Frame>
  <img alt="" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useResetPasswordRequest,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/reset-password-request";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnResetPasswordRequest">ScreenMembersOnResetPasswordRequest</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembersOnResetPasswordRequest">TransactionMembersOnResetPasswordRequest</a></span>}>
  Hook to access transaction state and authentication flow data.

  Transaction object containing flow state, session data, and transaction-specific information

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordRequestOptions">ResetPasswordRequestOptions</a></span>}>
      **Properties**

      <ParamField type="string" />

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordRequestMembers">ResetPasswordRequestMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# ResetPasswordSuccess
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/reset-password-success/index



<Frame>
  <img alt="ACUL Request password success" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useResetPasswordSuccess,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/reset-password-success";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnResetPasswordSuccess">ScreenMembersOnResetPasswordSuccess</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers">TransactionMembers</a></span>}>
  Hook to access transaction state and authentication flow data.

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordSuccessMembers">ResetPasswordSuccessMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# ResetPassword
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/reset-password/index



<Frame>
  <img alt="ACUL Reset password" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useScreen,
  useTransaction,
  resetPassword as resetPasswordMethod,
  useErrors,
  usePasswordValidation,
} from "@auth0/auth0-acul-react/reset-password";

import { Logo } from "../../components/Logo";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnResetPassword">ScreenMembersOnResetPassword</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembersOnResetPassword">TransactionMembersOnResetPassword</a></span>}>
  Hook to access transaction state and authentication flow data.

  Transaction object containing flow state, session data, and transaction-specific information

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordOptions">ResetPasswordOptions</a></span>}>
      **Properties**

      <ParamField type="string" />

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ResetPasswordMembers">ResetPasswordMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# SignupId
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/signup-id/index



<Frame>
  <img alt="Signup ID" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useSignupId,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/signup-id";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnSignupId">ScreenMembersOnSignupId</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembersOnSignupId">TransactionMembersOnSignupId</a></span>}>
  Hook to access transaction state and authentication flow data.

  Transaction object containing flow state, session data, and transaction-specific information

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/FederatedSignupOptions">FederatedSignupOptions</a></span>}>
      **Properties**

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/SignupOptions">SignupOptions</a></span>}>
      **Properties**

      <ParamField type="string" />

      <ParamField type="string" />

      <ParamField type="string" />

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/SignupIdMembers">SignupIdMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# SignupPassword
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/signup-password/index



<Frame>
  <img alt="Signup Password with Flexible IDs" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useSignupPassword,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/signup-password";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnSignupPassword">ScreenMembersOnSignupPassword</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembersOnSignupPassword">TransactionMembersOnSignupPassword</a></span>}>
  Hook to access transaction state and authentication flow data.

  Transaction object containing flow state, session data, and transaction-specific information

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/FederatedSignupPasswordPayloadOptions">FederatedSignupPasswordPayloadOptions</a></span>}>
      **Properties**

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/SignupPasswordOptions">SignupPasswordOptions</a></span>}>
      **Properties**

      <ParamField type="string" />

      <ParamField type="string" />

      <ParamField type="string" />

      <ParamField type="string" />

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/SignupPasswordMembers">SignupPasswordMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# Signup
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Screens/signup/index



<Frame>
  <img alt="ACUL Signup screen image" />
</Frame>

```jsx Import Example theme={null}
import React, { useState } from "react";
import {
  useSignup,
  useUser,
  useTenant,
  useBranding,
  useClient,
  useOrganization,
  usePrompt,
  useUntrustedData,
} from "@auth0/auth0-acul-react/signup";
```

## Context Hooks

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers">BrandingMembers</a></span>}>
  Hook to access branding and theme configuration.

  ```jsx Example theme={null}
  import { useBranding } from '@auth0/auth0-acul-react/login-id';
  function CustomTheme() {
    const branding = useBranding();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers">ClientMembers</a></span>}>
  Hook to access Auth0 application (client) configuration.

  ```jsx Example theme={null}
  import { useClient } from '@auth0/auth0-acul-react/login-id';
  function AppInfo() {
    const client = useClient();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers">OrganizationMembers</a></span>}>
  Hook to access organization context and settings.

  ```jsx Example theme={null}
  import { useOrganization } from '@auth0/auth0-acul-react/login-id';
  function OrgSelector() {
    const organization = useOrganization();
    if (!organization) {
      return <p>No organization context</p>;
    }
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers">PromptMembers</a></span>}>
  Hook to access prompt configuration and flow settings.

  ```jsx Example theme={null}
  import { usePrompt } from '@auth0/auth0-acul-react/login-id';
  function FlowInfo() {
    const prompt = usePrompt();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembersOnSignup">ScreenMembersOnSignup</a></span>}>
  Hook to access current screen information and metadata.

  Screen object containing current screen name, configuration, and screen-specific data

  ```jsx Example theme={null}
  import { useScreen } from '@auth0/auth0-acul-react/login-id';
  function ScreenDebug() {
    const screen = useScreen();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers">TenantMembers</a></span>}>
  Hook to access tenant configuration and settings.

  ```jsx Example theme={null}
  import { useTenant } from '@auth0/auth0-acul-react/login-id';
  function TenantInfo() {
    const tenant = useTenant();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembersOnSignup">TransactionMembersOnSignup</a></span>}>
  Hook to access transaction state and authentication flow data.

  Transaction object containing flow state, session data, and transaction-specific information

  ```jsx Example theme={null}
  import { useTransaction } from '@auth0/auth0-acul-react/login-id';
  function TransactionInfo() {
    const transaction = useTransaction();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers">UntrustedDataMembers</a></span>}>
  Hook to access untrusted data from URL parameters and form submissions.

  ```jsx Example theme={null}
  import { useUntrustedData } from '@auth0/auth0-acul-react/login-id';
  function PrefilledForm() {
    const untrustedData = useUntrustedData();
  }
  ```
</ParamField>

<ParamField type={<span>() =&gt; <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers">UserMembers</a></span>}>
  Hook to access user information and profile data.

  ```jsx Example theme={null}
  import { useUser } from '@auth0/auth0-acul-react/login-id';
  function UserProfile() {
    const user = useUser();
  }
  ```
</ParamField>

## Methods

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/FederatedSignupPayloadOptions">FederatedSignupPayloadOptions</a></span>}>
      **Properties**

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CustomOptions">CustomOptions</a></span>} />
  </Expandable>
</ParamField>

<ParamField type={<span>void | Promise&lt;void&gt;</span>}>
  <Expandable title="Parameters">
    <ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/SignupPayloadOptions">SignupPayloadOptions</a></span>}>
      **Properties**

      <ParamField type="string" />

      <ParamField type="string" />

      <ParamField type="string" />

      <ParamField type="string" />

      <ParamField type="string" />
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type={<a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/SignupMembers">SignupMembers</a>} />

## Common/Utility Hooks

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Hooks" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />

<ParamField type="Types" />


# BrandingMembers
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/BrandingMembers



```ts Example theme={null}
export interface BrandingMembers {
  settings: BrandingSettings | null;
  themes: BrandingThemes | null;
}
```

## Properties

<ParamField type={<span><a href="#BrandingSettings">BrandingSettings</a></span>} />

<ParamField type={<span><a href="#BrandingThemes">BrandingThemes</a></span>} />

## BrandingSettings

```ts theme={null}
export interface BrandingSettings {
  colors?: {
    primary?: string;
    pageBackground?:
      | string
      | {
          type: string;
          start: string;
          end: string;
          angleDegree: number;
        };
  };
  faviconUrl?: string;
  logoUrl?: string;
  fontUrl?: string;
}
```

### Properties

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string | { angleDegree: number; end: string; start: string; type: string; }" />

    <ParamField type="string" />
  </Expandable>
</ParamField>

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="string" />

## BrandingThemes

```ts theme={null}
export interface BrandingThemes {
  default: {
    borders: Record<string, string | boolean | number>;
    colors: Record<string, string>;
    displayName: string;
    fonts: Record<string, string | boolean | object>;
    pageBackground: Record<string, string>;
    widget: Record<string, string | number>;
  };
}
```

### Properties

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="Record<string, string | boolean | number>" />

    <ParamField type="Record<string, string>" />

    <ParamField type="string" />

    <ParamField type="Record<string, string | boolean | object>" />

    <ParamField type="Record<string, string>" />

    <ParamField type="Record<string, string | number>" />
  </Expandable>
</ParamField>


# ClientMembers
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ClientMembers



```ts Example theme={null}
export interface ClientMembers {
  id: string;
  name: string;
  logoUrl: string | null;
  description: string | null;
  metadata: { [key: string]: string } | null;
}
```

## Properties

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="{[key: string]: string; }" />

<ParamField type="string" />


# OrganizationMembers
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/OrganizationMembers



```ts Example theme={null}
export interface OrganizationMembers {
  id: string | null;
  name: string | null;
  usage: string | null;
  displayName: string | null;
  branding: Branding | null;
  metadata: { [key: string]: string } | null;
}
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/Branding">Branding</a></span>} />

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="{[key: string]: string; }" />

<ParamField type="string" />

<ParamField type="string" />


# PromptMembers
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PromptMembers



```ts Example theme={null}
export interface PromptMembers {
  name: string;
}
```

## Properties

<ParamField type="string" />


# ScreenMembers
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/ScreenMembers



```ts Example theme={null}
export interface ScreenMembers {
  name: string;
  captchaImage: string | null;
  captchaSiteKey: string | null;
  captchaProvider: string | null;
  isCaptchaAvailable: boolean;
  data: Record<string, string | boolean | string[] | Record<string, string[]> | Array<PhonePrefix> | PasskeyCreate> | null;
  links: Record<string, string> | null;
  texts: Record<string, string> | null;
  captcha: CaptchaContext | null;
}
```

## Properties

<ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/CaptchaContext">CaptchaContext</a></span>} />

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="string" />

<ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PasskeyCreate">PasskeyCreate</a></span>} />

<ParamField type="boolean" />

<ParamField type="Record<string, string>" />

<ParamField type="string" />

<ParamField type="Record<string, string>" />


# TenantMembers
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TenantMembers



```ts Example theme={null}
export interface TenantMembers {
  name: string | null;
  friendlyName: string | null;
  enabledLocales: string[] | null;
  enabledFactors: string[] | null;
}
```

## Properties

<ParamField type="string[]" />

<ParamField type="string[]" />

<ParamField type="string" />

<ParamField type="string" />


# TransactionMembers
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/TransactionMembers



```ts Example theme={null}
export interface TransactionMembers {
  state: string;
  locale: string;
  countryCode: CountryCode['code'] | null;
  countryPrefix: CountryCode['prefix'] | null;
  connectionStrategy: string | null;
  hasErrors: boolean;
  errors: Error[] | null;
  currentConnection: Connection | null;
  alternateConnections: (Connection | EnterpriseConnection)[] | null;
}
```

## Properties

<ParamField type={<span><a href="#connection">[Connection]</a> | <a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/EnterpriseConnection">[EnterpriseConnection][]</a></span>} />

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="string" />

<ParamField type={<span><a href="#connection">[Connection]</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/Error">[Error]</a></span>} />

<ParamField type="boolean" />

<ParamField type="string" />

<ParamField type="string" />

## Connection

```ts theme={null}
export interface Connection {
  name: string;
  strategy: string;
  metadata?: Record<string, string>;
}
```

### Properties

<ParamField type="Record<string, string>" />

<ParamField type="string" />

<ParamField type="string" />

## EnterpriseConnection

```ts theme={null}
export interface EnterpriseConnection extends Connection {
  options: {
    iconUrl?: string;
    displayName?: string;
    showAsButton: boolean;
  };
}
```

### Properties

<ParamField type="Record<string, string>" />

<ParamField type="string" />

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="string" />

    <ParamField type="string" />

    <ParamField type="boolean" />
  </Expandable>
</ParamField>

<ParamField type="string" />

## PasswordPolicy

```ts theme={null}
export interface PasswordPolicy {
  enabled?: boolean;
  minLength?: number;
  policy: 'none' | 'low' | 'fair' | 'good' | 'excellent';
  passwordSecurityInfo?: PasswordComplexityRule[];
}
```

### Properties

<ParamField type="boolean" />

<ParamField type="number" />

<ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/PasswordComplexityRule">[PasswordComplexityRule][]</a></span>} />

<ParamField type="&#x22;none&#x22; | &#x22;low&#x22; | &#x22;fair&#x22; | &#x22;good&#x22; | &#x22;excellent&#x22;" />


# UntrustedDataMembers
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UntrustedDataMembers



```ts Example theme={null}
export interface UntrustedDataMembers {
  submittedFormData: { [key: string]: string | number | boolean | undefined | null } | null;
  authorizationParams: {
    login_hint?: string;
    screen_hint?: string;
    ui_locales?: string;
    [key: `ext-${string}`]: string;
  } | null;
}
```

## Properties

<ParamField type="{ [key:  ext-${string} ]: string; login_hint?: string; screen_hint?: string; ui_locales?: string; }" />

<ParamField type="{[key: string]: string | number | boolean | null | undefined; }" />


# UserMembers
Source: https://auth0.com/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/UserMembers



```ts Example theme={null}
export interface UserMembers {
  id: string | null;
  email: string | null;
  username: string | null;
  phoneNumber: string | null;
  picture: string | null;
  enrolledFactors: Array<string> | null;
  enrolledEmails: Array<EnrolledEmail> | null;
  enrolledPhoneNumbers: Array<EnrolledPhoneNumber> | null;
  enrolledDevices: Array<EnrolledDevice> | null;
  organizations: Organizations[] | null;
  userMetadata: { [key: string]: string } | null;
  appMetadata: { [key: string]: string } | null;
}
```

## Properties

<ParamField type="{[key: string]: string; }" />

<ParamField type="string" />

<ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/EnrolledDevice">EnrolledDevice</a></span>} />

<ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/EnrolledEmail">EnrolledEmail</a></span>} />

<ParamField type="string[]" />

<ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/EnrolledPhoneNumber">EnrolledPhoneNumber</a></span>} />

<ParamField type="string" />

<ParamField type={<span><a href="/docs/libraries/acul/react-sdk/API-Reference/Types/interfaces/Organizations">Organizations</a></span>} />

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="{[key: string]: string; }" />

<ParamField type="string" />


# Auth0 APIs
Source: https://auth0.com/docs/api

Auth0 exposes the following APIs for developers to consume in their applications.

<div>
  <Card title="Authentication API" href="https://auth0.com/docs/api/authentication" />

  <AuthenticationApiSection />

  <Card title="Management API" href="https://auth0.com/docs/api/management/v2" />

  <ManagementApiSection />

  <Card title="My Account API" href="https://auth0.com/docs/api/myaccount" />

  <MyAccountApiSection />

  ***

  ## Pagination

  For Public Cloud tenants, Management API endpoints return a maximum of 50 results per response. When there are more results than can be returned in a response, include the `page` and `per_page` parameters in your request to retrieve more results.

  See [Migrate to Management API v2 Endpoint Paginated Queries](/docs/troubleshoot/product-lifecycle/past-migrations/migrate-to-paginated-queries) for information on updating your applications.
</div>


# Auth0 APIs
Source: https://auth0.com/docs/api

Auth0 exposes the following APIs for developers to consume in their applications.

<div>
  <Card title="Authentication API" href="https://auth0.com/docs/api/authentication" />

  <AuthenticationApiSection />

  <Card title="Management API" href="https://auth0.com/docs/api/management/v2" />

  <ManagementApiSection />

  <Card title="My Account API" href="https://auth0.com/docs/api/myaccount" />

  <MyAccountApiSection />

  ***

  ## Pagination

  For Public Cloud tenants, Management API endpoints return a maximum of 50 results per response. When there are more results than can be returned in a response, include the `page` and `per_page` parameters in your request to retrieve more results.

  See [Migrate to Management API v2 Endpoint Paginated Queries](/docs/troubleshoot/product-lifecycle/past-migrations/migrate-to-paginated-queries) for information on updating your applications.
</div>